contrib/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" "19 February 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 'wpa_cli reconfigure' 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=/var/run/wpa_supplicant
  45 ctrl_interface_group=wheel
  46 #
  47 # home network; allow all valid ciphers
  48 network={
  49         ssid="home"
  50         scan_ssid=1
  51         key_mgmt=WPA-PSK
  52         psk="very secret passphrase"
  53 }
  54 #
  55 # work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers
  56 network={
  57         ssid="work"
  58         scan_ssid=1
  59         key_mgmt=WPA-EAP
  60         pairwise=CCMP TKIP
  61         group=CCMP TKIP
  62         eap=TLS
  63         identity="user@example.com"
  64         ca_cert="/etc/cert/ca.pem"
  65         client_cert="/etc/cert/user.pem"
  66         private_key="/etc/cert/user.prv"
  67         private_key_passwd="password"
  68 }
  69 .fi
  70 .RE
  71 .TP 3
  72 2.
  73 WPA-RADIUS/EAP-PEAP/MSCHAPv2 with RADIUS servers that
  74 use old peaplabel (e.g., Funk Odyssey and SBR, Meetinghouse
  75 Aegis, Interlink RAD-Series)
  76 .sp
  77 .RS
  78
  79 .nf
  80 ctrl_interface=/var/run/wpa_supplicant
  81 ctrl_interface_group=wheel
  82 network={
  83         ssid="example"
  84         scan_ssid=1
  85         key_mgmt=WPA-EAP
  86         eap=PEAP
  87         identity="user@example.com"
  88         password="foobar"
  89         ca_cert="/etc/cert/ca.pem"
  90         phase1="peaplabel=0"
  91         phase2="auth=MSCHAPV2"
  92 }
  93 .fi
  94 .RE
  95 .TP 3
  96 3.
  97 EAP-TTLS/EAP-MD5-Challenge configuration with anonymous
  98 identity for the unencrypted use. Real identity is sent only
  99 within an encrypted TLS tunnel.
 100 .sp
 101 .RS
 102
 103 .nf
 104 ctrl_interface=/var/run/wpa_supplicant
 105 ctrl_interface_group=wheel
 106 network={
 107         ssid="example"
 108         scan_ssid=1
 109         key_mgmt=WPA-EAP
 110         eap=TTLS
 111         identity="user@example.com"
 112         anonymous_identity="anonymous@example.com"
 113         password="foobar"
 114         ca_cert="/etc/cert/ca.pem"
 115         phase2="auth=MD5"
 116 }
 117 .fi
 118 .RE
 119 .TP 3
 120 4.
 121 IEEE 802.1X (i.e., no WPA) with dynamic WEP keys
 122 (require both unicast and broadcast); use EAP-TLS for
 123 authentication
 124 .sp
 125 .RS
 126
 127 .nf
 128 ctrl_interface=/var/run/wpa_supplicant
 129 ctrl_interface_group=wheel
 130 network={
 131         ssid="1x-test"
 132         scan_ssid=1
 133         key_mgmt=IEEE8021X
 134         eap=TLS
 135         identity="user@example.com"
 136         ca_cert="/etc/cert/ca.pem"
 137         client_cert="/etc/cert/user.pem"
 138         private_key="/etc/cert/user.prv"
 139         private_key_passwd="password"
 140         eapol_flags=3
 141 }
 142 .fi
 143 .RE
 144 .TP 3
 145 5.
 146 Catch all example that allows more or less all
 147 configuration modes. The configuration options are used based
 148 on what security policy is used in the selected SSID. This is
 149 mostly for testing and is not recommended for normal
 150 use.
 151 .sp
 152 .RS
 153
 154 .nf
 155 ctrl_interface=/var/run/wpa_supplicant
 156 ctrl_interface_group=wheel
 157 network={
 158         ssid="example"
 159         scan_ssid=1
 160         key_mgmt=WPA-EAP WPA-PSK IEEE8021X NONE
 161         pairwise=CCMP TKIP
 162         group=CCMP TKIP WEP104 WEP40
 163         psk="very secret passphrase"
 164         eap=TTLS PEAP TLS
 165         identity="user@example.com"
 166         password="foobar"
 167         ca_cert="/etc/cert/ca.pem"
 168         client_cert="/etc/cert/user.pem"
 169         private_key="/etc/cert/user.prv"
 170         private_key_passwd="password"
 171         phase1="peaplabel=0"
 172         ca_cert2="/etc/cert/ca2.pem"
 173         client_cert2="/etc/cer/user.pem"
 174         private_key2="/etc/cer/user.prv"
 175         private_key2_passwd="password"
 176 }
 177 .fi
 178 .RE
 179 .TP 3
 180 6.
 181 Authentication for wired Ethernet. This can be used with
 182 'wired' interface (-Dwired on command line).
 183 .sp
 184 .RS
 185
 186 .nf
 187 ctrl_interface=/var/run/wpa_supplicant
 188 ctrl_interface_group=wheel
 189 ap_scan=0
 190 network={
 191         key_mgmt=IEEE8021X
 192         eap=MD5
 193         identity="user"
 194         password="password"
 195         eapol_flags=0
 196 }
 197 .fi
 198 .RE
 199 .SH "CERTIFICATES"
 200 .PP
 201 Some EAP authentication methods require use of
 202 certificates. EAP-TLS uses both server side and client
 203 certificates whereas EAP-PEAP and EAP-TTLS only require the server
 204 side certificate. When client certificate is used, a matching
 205 private key file has to also be included in configuration. If the
 206 private key uses a passphrase, this has to be configured in
 207 wpa_supplicant.conf ("private_key_passwd").
 208 .PP
 209 wpa_supplicant supports X.509 certificates in PEM and DER
 210 formats. User certificate and private key can be included in the
 211 same file.
 212 .PP
 213 If the user certificate and private key is received in
 214 PKCS#12/PFX format, they need to be converted to suitable PEM/DER
 215 format for wpa_supplicant. This can be done, e.g., with following
 216 commands:
 217 .sp
 218 .RS
 219
 220 .nf
 221 # convert client certificate and private key to PEM format
 222 openssl pkcs12 -in example.pfx -out user.pem -clcerts
 223 # convert CA certificate (if included in PFX file) to PEM format
 224 openssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys
 225 .fi
 226 .RE
 227 .SH "SEE ALSO"
 228 .PP
 229 \fBwpa_supplicant\fR(8)
 230 \fBopenssl\fR(1)