1 <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> 2 <refentry> 3 <refmeta> 4 <refentrytitle>wpa_supplicant.conf</refentrytitle> 5 <manvolnum>5</manvolnum> 6 </refmeta> 7 <refnamediv> 8 <refname>wpa_supplicant.conf</refname> 9 <refpurpose>configuration file for wpa_supplicant</refpurpose> 10 </refnamediv> 11 <refsect1> 12 <title>Overview</title> 13 14 <para><command>wpa_supplicant</command> is configured using a text 15 file that lists all accepted networks and security policies, 16 including pre-shared keys. See the example configuration file, 17 probably in <command>/usr/share/doc/wpa_supplicant/</command>, for 18 detailed information about the configuration format and supported 19 fields.</para> 20 21 <para>All file paths in this configuration file should use full 22 (absolute, not relative to working directory) path in order to allow 23 working directory to be changed. This can happen if wpa_supplicant is 24 run in the background.</para> 25 26 <para>Changes to configuration file can be reloaded be sending 27 SIGHUP signal to <command>wpa_supplicant</command> ('killall -HUP 28 wpa_supplicant'). Similarly, reloading can be triggered with 29 the <emphasis>wpa_cli reconfigure</emphasis> command.</para> 30 31 <para>Configuration file can include one or more network blocks, 32 e.g., one for each used SSID. wpa_supplicant will automatically 33 select the best network based on the order of network blocks in 34 the configuration file, network security level (WPA/WPA2 is 35 preferred), and signal strength.</para> 36 </refsect1> 37 38 <refsect1> 39 <title>Quick Examples</title> 40 41 <orderedlist> 42 <listitem> 43 44 <para>WPA-Personal (PSK) as home network and WPA-Enterprise with 45 EAP-TLS as work network.</para> 46 47 <blockquote><programlisting> 48 # allow frontend (e.g., wpa_cli) to be used by all users in 'wheel' group 49 ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel 50 # 51 # home network; allow all valid ciphers 52 network={ 53 ssid="home" 54 scan_ssid=1 55 key_mgmt=WPA-PSK 56 psk="very secret passphrase" 57 } 58 # 59 # work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers 60 network={ 61 ssid="work" 62 scan_ssid=1 63 key_mgmt=WPA-EAP 64 pairwise=CCMP TKIP 65 group=CCMP TKIP 66 eap=TLS 67 identity="user (a] example.com" 68 ca_cert="/etc/cert/ca.pem" 69 client_cert="/etc/cert/user.pem" 70 private_key="/etc/cert/user.prv" 71 private_key_passwd="password" 72 } 73 </programlisting></blockquote> 74 </listitem> 75 76 <listitem> 77 <para>WPA-RADIUS/EAP-PEAP/MSCHAPv2 with RADIUS servers that 78 use old peaplabel (e.g., Funk Odyssey and SBR, Meetinghouse 79 Aegis, Interlink RAD-Series)</para> 80 81 <blockquote><programlisting> 82 ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel 83 network={ 84 ssid="example" 85 scan_ssid=1 86 key_mgmt=WPA-EAP 87 eap=PEAP 88 identity="user (a] example.com" 89 password="foobar" 90 ca_cert="/etc/cert/ca.pem" 91 phase1="peaplabel=0" 92 phase2="auth=MSCHAPV2" 93 } 94 </programlisting></blockquote> 95 </listitem> 96 97 <listitem> 98 <para>EAP-TTLS/EAP-MD5-Challenge configuration with anonymous 99 identity for the unencrypted use. Real identity is sent only 100 within an encrypted TLS tunnel.</para> 101 102 103 <blockquote><programlisting> 104 ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel 105 network={ 106 ssid="example" 107 scan_ssid=1 108 key_mgmt=WPA-EAP 109 eap=TTLS 110 identity="user (a] example.com" 111 anonymous_identity="anonymous (a] example.com" 112 password="foobar" 113 ca_cert="/etc/cert/ca.pem" 114 phase2="auth=MD5" 115 } 116 </programlisting></blockquote> 117 118 </listitem> 119 120 <listitem> 121 <para>IEEE 802.1X (i.e., no WPA) with dynamic WEP keys 122 (require both unicast and broadcast); use EAP-TLS for 123 authentication</para> 124 125 <blockquote><programlisting> 126 ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel 127 network={ 128 ssid="1x-test" 129 scan_ssid=1 130 key_mgmt=IEEE8021X 131 eap=TLS 132 identity="user (a] example.com" 133 ca_cert="/etc/cert/ca.pem" 134 client_cert="/etc/cert/user.pem" 135 private_key="/etc/cert/user.prv" 136 private_key_passwd="password" 137 eapol_flags=3 138 } 139 </programlisting></blockquote> 140 </listitem> 141 142 143 <listitem> 144 <para>Catch all example that allows more or less all 145 configuration modes. The configuration options are used based 146 on what security policy is used in the selected SSID. This is 147 mostly for testing and is not recommended for normal 148 use.</para> 149 150 <blockquote><programlisting> 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 (a] 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 </programlisting></blockquote> 173 </listitem> 174 175 <listitem> 176 <para>Authentication for wired Ethernet. This can be used with 177 <emphasis>wired</emphasis> or <emphasis>roboswitch</emphasis> interface 178 (-Dwired or -Droboswitch on command line).</para> 179 180 <blockquote><programlisting> 181 ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel 182 ap_scan=0 183 network={ 184 key_mgmt=IEEE8021X 185 eap=MD5 186 identity="user" 187 password="password" 188 eapol_flags=0 189 } 190 </programlisting></blockquote> 191 </listitem> 192 </orderedlist> 193 194 195 196 197 198 </refsect1> 199 <refsect1> 200 <title>Certificates</title> 201 202 <para>Some EAP authentication methods require use of 203 certificates. EAP-TLS uses both server side and client 204 certificates whereas EAP-PEAP and EAP-TTLS only require the server 205 side certificate. When client certificate is used, a matching 206 private key file has to also be included in configuration. If the 207 private key uses a passphrase, this has to be configured in 208 wpa_supplicant.conf ("private_key_passwd").</para> 209 210 <para>wpa_supplicant supports X.509 certificates in PEM and DER 211 formats. User certificate and private key can be included in the 212 same file.</para> 213 214 <para>If the user certificate and private key is received in 215 PKCS#12/PFX format, they need to be converted to suitable PEM/DER 216 format for wpa_supplicant. This can be done, e.g., with following 217 commands:</para> 218 <blockquote><programlisting> 219 # convert client certificate and private key to PEM format 220 openssl pkcs12 -in example.pfx -out user.pem -clcerts 221 # convert CA certificate (if included in PFX file) to PEM format 222 openssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys 223 </programlisting></blockquote> 224 </refsect1> 225 226 <refsect1> 227 <title>See Also</title> 228 <para> 229 <citerefentry> 230 <refentrytitle>wpa_supplicant</refentrytitle> 231 <manvolnum>8</manvolnum> 232 </citerefentry> 233 <citerefentry> 234 <refentrytitle>openssl</refentrytitle> 235 <manvolnum>1</manvolnum> 236 </citerefentry> 237 </para> 238 </refsect1> 239 </refentry> 240
