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