dist/wpa/wpa_supplicant/doc/docbook/wpa_supplicant.conf.5

   1 .\" This manpage has been automatically generated by docbook2man
   2 .\" from a DocBook document.  This tool can be found at:
   3 .\" <http://shell.ipoline.com/~elmert/comp/docbook2X/>
   4 .\" Please send any bug reports, improvements, comments, patches,
   5 .\" etc. to Steve Cheng <steve@ggi-project.org>.
   6 .TH "WPA_SUPPLICANT.CONF" "5" "10 August 2008" "" ""
   7
   8 .SH NAME
   9 wpa_supplicant.conf \- configuration file for wpa_supplicant
  10 .SH "OVERVIEW"
  11 .PP
  12 \fBwpa_supplicant\fR is configured using a text
  13 file that lists all accepted networks and security policies,
  14 including pre-shared keys. See the example configuration file,
  15 probably in \fB/usr/share/doc/wpa_supplicant/\fR, for
  16 detailed information about the configuration format and supported
  17 fields.
  18 .PP
  19 All file paths in this configuration file should use full
  20 (absolute, not relative to working directory) path in order to allow
  21 working directory to be changed. This can happen if wpa_supplicant is
  22 run in the background.
  23 .PP
  24 Changes to configuration file can be reloaded be sending
  25 SIGHUP signal to \fBwpa_supplicant\fR ('killall -HUP
  26 wpa_supplicant'). Similarly, reloading can be triggered with
  27 the \fBwpa_cli reconfigure\fR command.
  28 .PP
  29 Configuration file can include one or more network blocks,
  30 e.g., one for each used SSID. wpa_supplicant will automatically
  31 select the best network based on the order of network blocks in
  32 the configuration file, network security level (WPA/WPA2 is
  33 preferred), and signal strength.
  34 .SH "QUICK EXAMPLES"
  35 .TP 3
  36 1.
  37 WPA-Personal (PSK) as home network and WPA-Enterprise with
  38 EAP-TLS as work network.
  39 .sp
  40 .RS
  41
  42 .nf
  43 # allow frontend (e.g., wpa_cli) to be used by all users in 'wheel' group
  44 ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
  45 #
  46 # home network; allow all valid ciphers
  47 network={
  48         ssid="home"
  49         scan_ssid=1
  50         key_mgmt=WPA-PSK
  51         psk="very secret passphrase"
  52 }
  53 #
  54 # work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers
  55 network={
  56         ssid="work"
  57         scan_ssid=1
  58         key_mgmt=WPA-EAP
  59         pairwise=CCMP TKIP
  60         group=CCMP TKIP
  61         eap=TLS
  62         identity="user@example.com"
  63         ca_cert="/etc/cert/ca.pem"
  64         client_cert="/etc/cert/user.pem"
  65         private_key="/etc/cert/user.prv"
  66         private_key_passwd="password"
  67 }
  68 .fi
  69 .RE
  70 .TP 3
  71 2.
  72 WPA-RADIUS/EAP-PEAP/MSCHAPv2 with RADIUS servers that
  73 use old peaplabel (e.g., Funk Odyssey and SBR, Meetinghouse
  74 Aegis, Interlink RAD-Series)
  75 .sp
  76 .RS
  77
  78 .nf
  79 ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
  80 network={
  81         ssid="example"
  82         scan_ssid=1
  83         key_mgmt=WPA-EAP
  84         eap=PEAP
  85         identity="user@example.com"
  86         password="foobar"
  87         ca_cert="/etc/cert/ca.pem"
  88         phase1="peaplabel=0"
  89         phase2="auth=MSCHAPV2"
  90 }
  91 .fi
  92 .RE
  93 .TP 3
  94 3.
  95 EAP-TTLS/EAP-MD5-Challenge configuration with anonymous
  96 identity for the unencrypted use. Real identity is sent only
  97 within an encrypted TLS tunnel.
  98 .sp
  99 .RS
 100
 101 .nf
 102 ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
 103 network={
 104         ssid="example"
 105         scan_ssid=1
 106         key_mgmt=WPA-EAP
 107         eap=TTLS
 108         identity="user@example.com"
 109         anonymous_identity="anonymous@example.com"
 110         password="foobar"
 111         ca_cert="/etc/cert/ca.pem"
 112         phase2="auth=MD5"
 113 }
 114 .fi
 115 .RE
 116 .TP 3
 117 4.
 118 IEEE 802.1X (i.e., no WPA) with dynamic WEP keys
 119 (require both unicast and broadcast); use EAP-TLS for
 120 authentication
 121 .sp
 122 .RS
 123
 124 .nf
 125 ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
 126 network={
 127         ssid="1x-test"
 128         scan_ssid=1
 129         key_mgmt=IEEE8021X
 130         eap=TLS
 131         identity="user@example.com"
 132         ca_cert="/etc/cert/ca.pem"
 133         client_cert="/etc/cert/user.pem"
 134         private_key="/etc/cert/user.prv"
 135         private_key_passwd="password"
 136         eapol_flags=3
 137 }
 138 .fi
 139 .RE
 140 .TP 3
 141 5.
 142 Catch all example that allows more or less all
 143 configuration modes. The configuration options are used based
 144 on what security policy is used in the selected SSID. This is
 145 mostly for testing and is not recommended for normal
 146 use.
 147 .sp
 148 .RS
 149
 150 .nf
 151 ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
 152 network={
 153         ssid="example"
 154         scan_ssid=1
 155         key_mgmt=WPA-EAP WPA-PSK IEEE8021X NONE
 156         pairwise=CCMP TKIP
 157         group=CCMP TKIP WEP104 WEP40
 158         psk="very secret passphrase"
 159         eap=TTLS PEAP TLS
 160         identity="user@example.com"
 161         password="foobar"
 162         ca_cert="/etc/cert/ca.pem"
 163         client_cert="/etc/cert/user.pem"
 164         private_key="/etc/cert/user.prv"
 165         private_key_passwd="password"
 166         phase1="peaplabel=0"
 167         ca_cert2="/etc/cert/ca2.pem"
 168         client_cert2="/etc/cer/user.pem"
 169         private_key2="/etc/cer/user.prv"
 170         private_key2_passwd="password"
 171 }
 172 .fi
 173 .RE
 174 .TP 3
 175 6.
 176 Authentication for wired Ethernet. This can be used with
 177 \fBwired\fR interface (-Dwired on command line).
 178 .sp
 179 .RS
 180
 181 .nf
 182 ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
 183 ap_scan=0
 184 network={
 185         key_mgmt=IEEE8021X
 186         eap=MD5
 187         identity="user"
 188         password="password"
 189         eapol_flags=0
 190 }
 191 .fi
 192 .RE
 193 .SH "CERTIFICATES"
 194 .PP
 195 Some EAP authentication methods require use of
 196 certificates. EAP-TLS uses both server side and client
 197 certificates whereas EAP-PEAP and EAP-TTLS only require the server
 198 side certificate. When client certificate is used, a matching
 199 private key file has to also be included in configuration. If the
 200 private key uses a passphrase, this has to be configured in
 201 wpa_supplicant.conf ("private_key_passwd").
 202 .PP
 203 wpa_supplicant supports X.509 certificates in PEM and DER
 204 formats. User certificate and private key can be included in the
 205 same file.
 206 .PP
 207 If the user certificate and private key is received in
 208 PKCS#12/PFX format, they need to be converted to suitable PEM/DER
 209 format for wpa_supplicant. This can be done, e.g., with following
 210 commands:
 211 .sp
 212 .RS
 213
 214 .nf
 215 # convert client certificate and private key to PEM format
 216 openssl pkcs12 -in example.pfx -out user.pem -clcerts
 217 # convert CA certificate (if included in PFX file) to PEM format
 218 openssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys
 219 .fi
 220 .RE
 221 .SH "SEE ALSO"
 222 .PP
 223 \fBwpa_supplicant\fR(8)
 224 \fBopenssl\fR(1)