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 <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@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@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@example.com"
 111         anonymous_identity="anonymous@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@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@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>