![Kel Modderman](/assets/img/avatar_default.png)
The Debian package checker "lintian" was making noise about wpa_supplicant.conf(5). It was caused by a line beginning with ', which is apparently not liked by man(1). I suggest the use of <emphasis>word</emphasis> where 'word' is used at the moment. Signed-off-by: Kel Modderman <kel@otaku42.de>
238 lines
6.7 KiB
Text
238 lines
6.7 KiB
Text
<!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>
|