hostap/wpa_supplicant/doc/docbook/wpa_supplicant.conf.sgml

239 lines
6.7 KiB
Text
Raw Normal View History

<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<refentry>
<refmeta>
<refentrytitle>wpa_supplicant.conf</refentrytitle>
<manvolnum>5</manvolnum>
</refmeta>
<refnamediv>
<refname>wpa_supplicant.conf</refname>
<refpurpose>configuration file for wpa_supplicant</refpurpose>
</refnamediv>
<refsect1>
<title>Overview</title>
<para><command>wpa_supplicant</command> is configured using a text
file that lists all accepted networks and security policies,
including pre-shared keys. See the example configuration file,
probably in <command>/usr/share/doc/wpa_supplicant/</command>, for
detailed information about the configuration format and supported
fields.</para>
<para>All file paths in this configuration file should use full
(absolute, not relative to working directory) path in order to allow
working directory to be changed. This can happen if wpa_supplicant is
run in the background.</para>
<para>Changes to configuration file can be reloaded be sending
SIGHUP signal to <command>wpa_supplicant</command> ('killall -HUP
wpa_supplicant'). Similarly, reloading can be triggered with
the <emphasis>wpa_cli reconfigure</emphasis> command.</para>
<para>Configuration file can include one or more network blocks,
e.g., one for each used SSID. wpa_supplicant will automatically
select the best network based on the order of network blocks in
the configuration file, network security level (WPA/WPA2 is
preferred), and signal strength.</para>
</refsect1>
<refsect1>
<title>Quick Examples</title>
<orderedlist>
<listitem>
<para>WPA-Personal (PSK) as home network and WPA-Enterprise with
EAP-TLS as work network.</para>
<blockquote><programlisting>
# allow frontend (e.g., wpa_cli) to be used by all users in 'wheel' group
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
#
# home network; allow all valid ciphers
network={
ssid="home"
scan_ssid=1
key_mgmt=WPA-PSK
psk="very secret passphrase"
}
#
# work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers
network={
ssid="work"
scan_ssid=1
key_mgmt=WPA-EAP
pairwise=CCMP TKIP
group=CCMP TKIP
eap=TLS
identity="user@example.com"
ca_cert="/etc/cert/ca.pem"
client_cert="/etc/cert/user.pem"
private_key="/etc/cert/user.prv"
private_key_passwd="password"
}
</programlisting></blockquote>
</listitem>
<listitem>
<para>WPA-RADIUS/EAP-PEAP/MSCHAPv2 with RADIUS servers that
use old peaplabel (e.g., Funk Odyssey and SBR, Meetinghouse
Aegis, Interlink RAD-Series)</para>
<blockquote><programlisting>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
network={
ssid="example"
scan_ssid=1
key_mgmt=WPA-EAP
eap=PEAP
identity="user@example.com"
password="foobar"
ca_cert="/etc/cert/ca.pem"
phase1="peaplabel=0"
phase2="auth=MSCHAPV2"
}
</programlisting></blockquote>
</listitem>
<listitem>
<para>EAP-TTLS/EAP-MD5-Challenge configuration with anonymous
identity for the unencrypted use. Real identity is sent only
within an encrypted TLS tunnel.</para>
<blockquote><programlisting>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
network={
ssid="example"
scan_ssid=1
key_mgmt=WPA-EAP
eap=TTLS
identity="user@example.com"
anonymous_identity="anonymous@example.com"
password="foobar"
ca_cert="/etc/cert/ca.pem"
phase2="auth=MD5"
}
</programlisting></blockquote>
</listitem>
<listitem>
<para>IEEE 802.1X (i.e., no WPA) with dynamic WEP keys
(require both unicast and broadcast); use EAP-TLS for
authentication</para>
<blockquote><programlisting>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
network={
ssid="1x-test"
scan_ssid=1
key_mgmt=IEEE8021X
eap=TLS
identity="user@example.com"
ca_cert="/etc/cert/ca.pem"
client_cert="/etc/cert/user.pem"
private_key="/etc/cert/user.prv"
private_key_passwd="password"
eapol_flags=3
}
</programlisting></blockquote>
</listitem>
<listitem>
<para>Catch all example that allows more or less all
configuration modes. The configuration options are used based
on what security policy is used in the selected SSID. This is
mostly for testing and is not recommended for normal
use.</para>
<blockquote><programlisting>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
network={
ssid="example"
scan_ssid=1
key_mgmt=WPA-EAP WPA-PSK IEEE8021X NONE
pairwise=CCMP TKIP
group=CCMP TKIP WEP104 WEP40
psk="very secret passphrase"
eap=TTLS PEAP TLS
identity="user@example.com"
password="foobar"
ca_cert="/etc/cert/ca.pem"
client_cert="/etc/cert/user.pem"
private_key="/etc/cert/user.prv"
private_key_passwd="password"
phase1="peaplabel=0"
ca_cert2="/etc/cert/ca2.pem"
client_cert2="/etc/cer/user.pem"
private_key2="/etc/cer/user.prv"
private_key2_passwd="password"
}
</programlisting></blockquote>
</listitem>
<listitem>
<para>Authentication for wired Ethernet. This can be used with
<emphasis>wired</emphasis> interface (-Dwired on command line).</para>
<blockquote><programlisting>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
ap_scan=0
network={
key_mgmt=IEEE8021X
eap=MD5
identity="user"
password="password"
eapol_flags=0
}
</programlisting></blockquote>
</listitem>
</orderedlist>
</refsect1>
<refsect1>
<title>Certificates</title>
<para>Some EAP authentication methods require use of
certificates. EAP-TLS uses both server side and client
certificates whereas EAP-PEAP and EAP-TTLS only require the server
side certificate. When client certificate is used, a matching
private key file has to also be included in configuration. If the
private key uses a passphrase, this has to be configured in
wpa_supplicant.conf ("private_key_passwd").</para>
<para>wpa_supplicant supports X.509 certificates in PEM and DER
formats. User certificate and private key can be included in the
same file.</para>
<para>If the user certificate and private key is received in
PKCS#12/PFX format, they need to be converted to suitable PEM/DER
format for wpa_supplicant. This can be done, e.g., with following
commands:</para>
<blockquote><programlisting>
# convert client certificate and private key to PEM format
openssl pkcs12 -in example.pfx -out user.pem -clcerts
# convert CA certificate (if included in PFX file) to PEM format
openssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys
</programlisting></blockquote>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry>
<refentrytitle>wpa_supplicant</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>
<citerefentry>
<refentrytitle>openssl</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>