contrib/wpa_supplicant/doc/docbook/wpa_supplicant.conf.sgml

   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 'wpa_cli reconfigure' 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=/var/run/wpa_supplicant
  50 ctrl_interface_group=wheel
  51 #
  52 # home network; allow all valid ciphers
  53 network={
  54         ssid="home"
  55         scan_ssid=1
  56         key_mgmt=WPA-PSK
  57         psk="very secret passphrase"
  58 }
  59 #
  60 # work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers
  61 network={
  62         ssid="work"
  63         scan_ssid=1
  64         key_mgmt=WPA-EAP
  65         pairwise=CCMP TKIP
  66         group=CCMP TKIP
  67         eap=TLS
  68         identity="user@example.com"
  69         ca_cert="/etc/cert/ca.pem"
  70         client_cert="/etc/cert/user.pem"
  71         private_key="/etc/cert/user.prv"
  72         private_key_passwd="password"
  73 }
  74 </programlisting></blockquote>
  75       </listitem>
  76
  77       <listitem>
  78         <para>WPA-RADIUS/EAP-PEAP/MSCHAPv2 with RADIUS servers that
  79         use old peaplabel (e.g., Funk Odyssey and SBR, Meetinghouse
  80         Aegis, Interlink RAD-Series)</para>
  81
  82 <blockquote><programlisting>
  83 ctrl_interface=/var/run/wpa_supplicant
  84 ctrl_interface_group=wheel
  85 network={
  86         ssid="example"
  87         scan_ssid=1
  88         key_mgmt=WPA-EAP
  89         eap=PEAP
  90         identity="user@example.com"
  91         password="foobar"
  92         ca_cert="/etc/cert/ca.pem"
  93         phase1="peaplabel=0"
  94         phase2="auth=MSCHAPV2"
  95 }
  96 </programlisting></blockquote>
  97       </listitem>
  98
  99       <listitem>
 100         <para>EAP-TTLS/EAP-MD5-Challenge configuration with anonymous
 101         identity for the unencrypted use. Real identity is sent only
 102         within an encrypted TLS tunnel.</para>
 103
 104
 105 <blockquote><programlisting>
 106 ctrl_interface=/var/run/wpa_supplicant
 107 ctrl_interface_group=wheel
 108 network={
 109         ssid="example"
 110         scan_ssid=1
 111         key_mgmt=WPA-EAP
 112         eap=TTLS
 113         identity="user@example.com"
 114         anonymous_identity="anonymous@example.com"
 115         password="foobar"
 116         ca_cert="/etc/cert/ca.pem"
 117         phase2="auth=MD5"
 118 }
 119 </programlisting></blockquote>
 120
 121       </listitem>
 122
 123       <listitem>
 124         <para>IEEE 802.1X (i.e., no WPA) with dynamic WEP keys
 125         (require both unicast and broadcast); use EAP-TLS for
 126         authentication</para>
 127
 128 <blockquote><programlisting>
 129 ctrl_interface=/var/run/wpa_supplicant
 130 ctrl_interface_group=wheel
 131 network={
 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>
 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 </programlisting></blockquote>
 178       </listitem>
 179
 180       <listitem>
 181         <para>Authentication for wired Ethernet. This can be used with
 182        'wired' interface (-Dwired on command line).</para>
 183
 184 <blockquote><programlisting>
 185 ctrl_interface=/var/run/wpa_supplicant
 186 ctrl_interface_group=wheel
 187 ap_scan=0
 188 network={
 189         key_mgmt=IEEE8021X
 190         eap=MD5
 191         identity="user"
 192         password="password"
 193         eapol_flags=0
 194 }
 195 </programlisting></blockquote>
 196       </listitem>
 197     </orderedlist>
 198
 199
 200
 201
 202
 203   </refsect1>
 204   <refsect1>
 205     <title>Certificates</title>
 206
 207     <para>Some EAP authentication methods require use of
 208     certificates. EAP-TLS uses both server side and client
 209     certificates whereas EAP-PEAP and EAP-TTLS only require the server
 210     side certificate. When client certificate is used, a matching
 211     private key file has to also be included in configuration. If the
 212     private key uses a passphrase, this has to be configured in
 213     wpa_supplicant.conf ("private_key_passwd").</para>
 214
 215     <para>wpa_supplicant supports X.509 certificates in PEM and DER
 216     formats. User certificate and private key can be included in the
 217     same file.</para>
 218
 219     <para>If the user certificate and private key is received in
 220     PKCS#12/PFX format, they need to be converted to suitable PEM/DER
 221     format for wpa_supplicant. This can be done, e.g., with following
 222     commands:</para>
 223 <blockquote><programlisting>
 224 # convert client certificate and private key to PEM format
 225 openssl pkcs12 -in example.pfx -out user.pem -clcerts
 226 # convert CA certificate (if included in PFX file) to PEM format
 227 openssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys
 228 </programlisting></blockquote>
 229   </refsect1>
 230
 231   <refsect1>
 232     <title>See Also</title>
 233     <para>
 234       <citerefentry>
 235         <refentrytitle>wpa_supplicant</refentrytitle>
 236         <manvolnum>8</manvolnum>
 237       </citerefentry>
 238       <citerefentry>
 239         <refentrytitle>openssl</refentrytitle>
 240         <manvolnum>1</manvolnum>
 241       </citerefentry>
 242     </para>
 243   </refsect1>
 244 </refentry>