<chapter id="ch5">
<title>Configuration</title>

<section>
<title>Overview</title>
<para>

</para>

</section>

<section>
<title>Commandline Options</title>

<para>
<userinput>-W</userinput> 
</para>

<para>
Allow Xsupplicant to work with wpa_supplicant.
</para>

<para>
<userinput>-c /path/to/config_file</userinput>
</para>

<para>
You can specify a configuration file to be used with the "-c" option.  
Xsupplicant will automatically look for and use "/etc/xsupplicant.conf" if 
it exists.
</para>

<para>
<userinput>-i device</userinput>
</para>

<para>
Provide the interface on which to listen for EAPoL packets.  Please note that 
xsupplicant will currently look for any valid interfaces and fork to handle 
each valid interface it finds.  You do not need to run multiple instances 
of xsupplicant yourself.
</para>

<para>
<userinput>-d debug_level</userinput>
</para>

<para>
&lt;debug_level&gt; can be any of:

<itemizedlist>
    <listitem>
        <para>0 - 7 Old style debug flags.</para>
    </listitem>
    <listitem>
        <para>A - Enable ALL debug flags.</para>
    </listitem>
    <listitem>
        <para>c - Enable CONFIG debug flag.</para>
    </listitem>
    <listitem>
        <para>s - Enable STATE debug flag.</para>
    </listitem>
    <listitem>
        <para>a - Enable AUTHTYPES debug flag.</para>
    </listitem>
    <listitem>
        <para>i - Enable INT debug flag.</para>
    </listitem>
    <listitem>
        <para>n - Enable SNMP debug flag.</para>
    </listitem>
    <listitem>
        <para>e - Enable EVERYTHING debug flag.</para>
    </listitem>
    <listitem>
        <para>x - Enable EXCESSIVE debug flag.</para>
    </listitem>
</itemizedlist>
</para>

<para>
Debug flags can be stacked such as: <userinput>xsupplicant -d csai</userinput>.  This would provide CONFIG, STATE, AUTHTYPES, and INT debug output.
</para>

</section>

<section>
<title>System Wide Config File</title>
<para>
Xsupplicant will look for a file in /etc/xsupplicant.conf by default, unless 
the -c option is used at runtime.

The xsupplicant configuration file consists of several global variables and a 
set of network-specific configurations.  

Each network profile definition contains one or more EAP sections, which 
contain specific configuration information for the network in question.

<!--REVISIT: Each Release.-->

</para>
</section>

<section>
<title>Global Configuration Options</title>

<para>
The following is a complete list of the global options available in 
xsupplicant 1.0.1.  These options should be defined outside of any xsupplicant 
network profiles contained in your configuration file.
</para>

<section>
<title>Global Options</title>

<para>
The following list is a complete list of the global configuration options for 
the xsupplicant configuration file.
</para>

<variablelist>
<title>Xsupplicant Config - Global Options</title>
<varlistentry id="allow_interfaces">
<term><varname>allow_interfaces</varname></term>
<listitem>
<para>

Defining an interface in "allow_interfaces" will bypass the rules that 
xsupplicant uses to determine if an interface is valid.  For most people 
this setting shouldn't be needed.  It is useful for having xsupplicant 
attempt to authenticate on interfaces that don't appear to be true 
physical interfaces.  (i.e. Virtual interfaces such as eth0:1)

<example>
<title>Global Option "allow_interface"</title>
<programlisting>
allow_interfaces = eth0:1, eth0:2
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>

<varlistentry id="default_netname">
<term><varname>default_netname</varname></term>
<listitem>
<para>
If this option is not used, xsupplicant will attempt to read the profile 
"default" from the configuration file. Some users may actually have a network 
named "default", so this option can be used to redefine which profile is 
used as the default profile.

<example>
<title>Global Option "default_netname"</title>
<programlisting>
default_netname = default
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>

<varlistentry id="deny_interfaces">
<term><varname>deny_interfaces</varname></term>
<listitem>
<para>
Defining an interface in "deny_interfaces" will prevent xsupplicant from 
attempting to authenticate on a given interface.  This is useful if you 
know that you will never do 802.1X on a specific interface, such as a 
VMWare virtual interface.  However, allows will take priority over denies, so 
defining the same interface in the allow_interfaces, and deny_interfaces will 
result in the interface being used.
</para>

<para>
<example>
<title>Global Option "deny_interfaces"</title>
<programlisting>
deny_interfaces = eth1, vmnet0
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>

<varlistentry id="first_auth_command">
<term><varname>first_auth_command</varname></term>
<listitem>
<para>
This directive instructions xsupplicant to run the following command when 
xsupplicant authenticates to a wireless network for the first time.  
This will usually be used to start a DHCP client process.

<example>
<title>Global Option "first_auth_command"</title>
<programlisting>
first_auth_command = &lt;BEGIN_COMMAND&gt;dhclient %i&lt;END_COMMAND&gt;
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>

<varlistentry id="logfile">
<term><varname>logfile</varname></term>
<listitem>
<para>
When running in daemon, or non-foreground mode, you may want to have the 
output of the program.  So, define a log file here.  Each time XSupplicant 
is started, this file will be replaced.  So, there is no need to roll the 
log file.

<example>
<title>Global Option "logfile"</title>
<programlisting>
logfile = /var/log/xsupplicant.log
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>

<varlistentry id="network_list">
<term><varname>network_list</varname></term>
<listitem>
<para>
This directive defines all of the network profiles which should be kept 
in memory and used.Comma delimited list or "all" for keeping all defined 
configurations in memory. For efficiency, keep only the networks you might 
roam to in memory.  To avoid errors, make sure your default network is always 
in the network_list.  In general, you will want to leave this set to "all".

<example>
<title>Global Option "network_list"</title>
<programlisting>
network_list = all
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>

<varlistentry id="reauth_command">
<term><varname>reauth_command</varname></term>
<listitem>
<para>
This command is executed when xsupplicant reauthenticates to a wireless 
network.  This may be used to have the dhcp client rerequest it's IP address. 
This option will probably not be useful except in situations where the 
layer 3 network might change on a wireless network where the SSID remains 
the same, such as in the case of the University of Utah's wireless network.

<example>
<title>Global Option "reauth_command"</title>
<programlisting>
reauth_command = &lt;BEGIN_COMMAND&gt;echo "authenticated user %i"&lt;END_COMMAND&gt;
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>


<varlistentry id="startup_command">
<term><varname>startup_command</varname></term>
<listitem>
<para>
This command is executed when xsupplicant is first started.  This command 
can do things such as configure the card to associate with the network 
properly.

<example>
<title>Global Option "startup_command"</title>
<programlisting>
startup_command = &lt;BEGIN_COMMAND&gt;echo "some command"&lt;END_COMMAND&gt;
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>

</variablelist>

</section>

<section>
<title>State Machine Variables</title>
<para>
<itemizedlist>
<listitem><para>auth_period</para></listitem>
<listitem><para>max_starts</para></listitem>
<listitem><para>held_period</para></listitem>
</itemizedlist>
</para>

<para>
The auth_period, held_period, and max_starts modify the timers in the state 
machine.  (Please reference the 802.1X spec for info on how they are used.)
For most people, there is no reason to define these values, as the defaults 
should work.
</para>

</section>

</section>

<section>
<title>Network Profile Configuration Options</title>
<para>
A network profile consists of a declaration, such as "default".  
A complete profile definition is defined by a beginning and ending brace, 
"{" and "}" respectively.  The profile defines network specific attributes 
for 802.1X operation, such as allowed EAP-types, the username for a given 
EAP-type, and any EAP-type specific options.
</para>

<para>
Each network profile section may include one or more valid EAP-types.  
When the Authentication Server requests a given EAP type, xsupplicant will 
use that EAP type if a valid configuration exists.  Otherwise, xsupplicant 
will NAK the Authentication Server, and request the first EAP type defined 
by the "allow_types" configuration option.  If xsupplicant and the 
Authentication server cannot agree on an EAP type, the authentication will 
not take place, so be sure to define an appropriate EAP-type for your network!
</para>

<variablelist>
<title>Xsupplicant Config - Network Profile Options</title>
<varlistentry id="allow_types">
<term><varname>allow_types</varname></term>
<listitem>
<para>
This option describes which EAP types this network will allow.  The 
first type listed will be requested if the server tries to use something 
not in this list.  Individual EAP types can be specified, or the keyword 
"all" can be used to specify all EAP types.  Additionally, it is legal 
to use either an underscore (_) or dash (-) for the separator character 
between "eap" and the type.  For instance, "eap-tls" and "eap_tls" are 
both valid.

<example>
<title>Profile Option "allow_types"</title>
<programlisting>
allow_types = eap-tls, eap-md5, eap-gtc, eap-otp

allow_types = all
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>

<varlistentry id="dest_mac">
<term><varname>dest_mac</varname></term>
<listitem>
<para>
 This option forces xsupplicant to send its packets to this destination 
MAC address. In most cases, this isn't needed, and shouldn't be defined.

<example>
<title>Profile Option "dest_mac"</title>
<programlisting>
dest_mac = 00:aA:bB:cC:dD:eE
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>


<varlistentry id="identity">
<term><varname>identity</varname></term>
<listitem>
<para>
This defines the EAP Response Identity, also known as the "outer identity"
, or, what xsupplicant will respond with when presented with an EAP 
Identity Request. This is typically the username for this network.

<example>
<title>Profile Option "identity"</title>
<programlisting>
identity = &lt;BEGIN_ID&gt;myid@mynet.net&lt;END_ID&gt;
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>

<varlistentry id="type">
<term><varname>type</varname></term>
<listitem>
<para>
Xsupplicant will attempt to determine if a given interface is wired 
or wireless, but some drivers misbehave. This option forces xsupplicant 
to recognize interfaces in a certain way. Use this option if your 
interface is detected  incorrectly by xsupplicant.  Valid options are 
"wired" and "wireless".

<example>
<title>Profile Option "type"</title>
<programlisting>
type = wireless
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>

<varlistentry id="wireless_control">
<term><varname>wireless_control</varname></term>
<listitem>
<para>
If the profile is forced to wired, this will not do anything.  
However, if the interface is forced, or detected to be wireless 
XSupplicant will take control of re/setting WEP keys when the machine 
first starts, and when it jumps to a different AP.  In general, you 
won't need to define, or set this value.  Valid options are "yes" and 
"no". 

<example>
<title>Profile Option "wireless_control"</title>
<programlisting>
wireless_control = yes
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>

</variablelist>

</section>


<section>
<title>EAP Options</title>

<!--REVISIT: Can we combine earlier sections related to this?-->
<para>
Each network profile in the xsupplicant configuration file may have one or 
more EAP sections defined.  Each EAP section must be associated to a network 
profile.  Each EAP section may also have one or more subsections associated 
with it.
</para>

<para>
For instance, a configuration for EAP-TTLS may have any of CHAP, MSCHAP, 
MSCHAPv2, or PAP subsections defined.  Some EAP types do not contain any 
subsections.
</para>

<section>
<title>Reused EAP Options</title>
<para>
The following options are re-used in many of the EAP types listed below.  


<variablelist>
<title>Common EAP Options</title>

<varlistentry id="chunk_size">
<term><varname>chunk_size</varname></term>
<listitem>
<para>
The chunk_size directive specifies the maximum size that a certificate 
chunk can be.  Use this option in EAP types that use either one or both of 
client or server certificates (TLS, PEAP, TTLS).
</para>
<para>
<example>
<title>Common EAP Option "chunk_size"</title>
<programlisting>
chunk_size = 1398
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>

<varlistentry id="cncheck">
<term><varname>cncheck</varname></term>
<listitem>
<para>
The cncheck directive provides the ability to verify the CN field 
of an authentication server certificate for EAP types that use 
server-side certificates (TLS, TTLS, PEAP).
</para>
<para>
Use this directive in conjunction with cnexact to control how granular 
the server certificate check should be.
</para>
<para>
<example>
<title>Common EAP Option cncheck</title>
<programlisting>
cncheck = someradius.mynet.net
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>

<varlistentry id="cnexact">
<term><varname>cnexact</varname></term>
<listitem>
<para>
The cnexact directive forces a failure on authentication if the CN 
field of the server's certificate does not exactly match the cncheck 
option in the specified Network/EAP configuration.  Set this to "no" 
to only match the end of the string, which is useful in a situation 
where there might be mulitple authentication servers for your organization.
</para>
<para>
For example, a "cncheck = utah.edu" with a "cnexact = no" would match on 
"foo.utah.edu" and "bar.utah.edu", which might be separate servers on 
a campus utilizing 802.1X.  
</para>
<para>
<example>
<title>Common EAP Option "cnexact"</title>
<programlisting>
cnexact = yes
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>

<varlistentry id="crl_dir">
<term><varname>crl_dir</varname></term>
<listitem>
<para>
The crl_dir option is used to specify a directory containing 
certificate revocation lists.  This option can be used in EAP types that use 
either one or both of client or server certificates (TLS, PEAP, TTLS).
</para>
<para>
<example>
<title>Common EAP Option "crl_dir"</title>
<programlisting>
crl_dir = /home/user/certificates/revoked
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>

<varlistentry id="password">
<term><varname>password</varname></term>
<listitem>
<para>
The password directive is used in EAP types that require a password 
for authentication.
</para>
<para>
<example>
<title>Common EAP Option "password"</title>
<programlisting>
password = &lt;BEGIN_PASS&gt;password&lt;END_PASS&gt;
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>

<varlistentry id="random_file">
<term><varname>random_file</varname></term>
<listitem>
<para>
This option is used to specify the random file used to grab random 
data for certificate something-or-other. 

Use this option in EAP types that use either one or both of 
client or server certificates (TLS, PEAP, TTLS).
</para>
<para>
This option is typically /dev/urandom, but may be different depending on 
the operating system you are using.  You should probably not use /dev/random, 
since it blocks and can slow authentication down.
</para>
<para>
<example>
<title>Common EAP Option "random_file"</title>
<programlisting>
random_file = /dev/urandom
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>

<varlistentry id="root_cert">
<term><varname>root_cert</varname></term>
<listitem>
<para>
The root_cert option is used to specify the path to the CA public certificate 
which signed one or both of your server and client certificates.  
The root_cert option is used in EAP types that use either one or both of 
client or server certificates (TLS, PEAP, TTLS).
</para>
<para>
This certificate is used to verify, on the client side, that the server's 
certificate was signed by the appropriate certificate authority, and on the 
server side, to verify that the user certificate was signed by the proper 
certificate authority.  This certificate should be the same for both client 
and server, since it is simply the public key for the certificate authority 
that signed the client and server certificates.
</para>
<para>
You can specify a value of "NONE" to prevent xsupplicant from verifying the 
server certificate, but this is *HIGHLY* frowned upon.  If you use this 
option, you are opening yourself up to a very easy to execute 
man-in-the-middle attack that could compromise your username and password.  
Consider yourself warned. :-)
</para>
<!--REVISIT: What formats can the root certificate be in?-->
<para>
<example>
<title>Common EAP Option "root_cert"</title>
<programlisting>
root_cert = /home/user/certificates/root_cert.pem
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>

<varlistentry id="root_dir">
<term><varname>root_dir</varname></term>
<listitem>
<para>
The root_dir option is used to specify a path to a directory containing root 
certificates.  This can be used to force Xsupplicant to allow any combination 
of root certificates in a given directory to help simplify configuration.  
This option can be used instead of the root_cert directive in EAP types that 
use either one or both of client or server certificates (TLS, PEAP, TTLS).
</para>
<para>
<example>
<title>Common EAP Option "root_dir"</title>
<programlisting>
root_dir = /home/user/certificates
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>

<varlistentry id="session_resume">
<term><varname>session_resume</varname></term>
<listitem>
<para>
The session_resume directive is used to specify whether or not 
to attempt to initiate "TLS Session Resumption" (Also called "Fast Reconnect") 
when re-authenticating with a server.
</para>
<para>
<example>
<title>Common EAP Option "session_resume"</title>
<programlisting>
session_resume = yes
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>

<varlistentry id="username">
<term><varname>username</varname></term>
<listitem>
<para>
The username option is used in EAP types that require a username for 
authentication.
</para>
<para>
<example>
<title>Common EAP Option "username"</title>
<programlisting>
username = &lt;BEGIN_UNAME&gt;myid@mynet.net&lt;END_UNAME&gt;
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>

<varlistentry id="user_cert">
<term><varname>user_cert</varname></term>
<listitem>
<para>
This option, which is required for TLS, specifies the path to the user 
certificate used for TLS authentication.  A user certificate in TLS 
is similar to a username in password-based authentication mechanisms.
<!--REVISIT: What formats can the user_cert be in?-->
</para>
<para>
User certificates can also be used with PEAP and TTLS, but are not 
required, and most people will not need this functionality.
</para>
<para>
<example>
<title>Common EAP Option "user_cert"</title>
<programlisting>
user_cert = /home/user/certificates/user-cert.pem
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>

<varlistentry id="user_key">
<term><varname>user_key</varname></term>
<listitem>
<para>
This option is the key for the user_cert file.
<!--REVISIT: What formats can the user_key be in?-->
</para>
<para>
As with user_cert, this option is required for TLS and can be 
used with TTLS or PEAP if using a user certificate for authentication.
</para>
<para>
<example>
<title>Common EAP Option "user_key"</title>
<programlisting>
user_key = /home/user/certificates/user-key.pem
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>

<varlistentry id="user_key_pass">
<term><varname>user_key_pass</varname></term>
<listitem>
<para>
This is the password for the user_key.
</para>
<para>
<example>
<title>Common EAP Option "user_key_pass"</title>
<programlisting>
user_key_pass = &lt;BEGIN_PASS&gt;password for user-key.pem&lt;END_PASS&gt;
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>

</variablelist>

</para>
</section>

<!--REVISIT: Each Release-->
<section id="eap-aka">
<title>EAP-AKA</title>
<para>
EAP-AKA allows the following options: 
<link linkend="username">username</link>, 
<link linkend="password">password</link>, 
<link linkend="auto_realm">auto_realm</link>.
</para>
<para>
<example>
<title>Example EAP-AKA Configuration</title>
<programlisting role="Config">
logfile = /var/log/xsupplicant.log

startup_command = &lt;BEGIN_COMMAND&gt;dhclient %i&lt;END_COMMAND&gt;

default {
  allow_types = eap-aka

  identity = &lt;BEGIN_ID&gt;myid@mynet.net&lt;END_ID&gt;

  eap-aka {
      username = &lt;BEGIN_UNAME&gt;akauser&lt;END_UNAME&gt;
      password = &lt;BEGIN_PASS&gt;akauserpass!&lt;END_PASS&gt;     
      auto_realm = yes
  }
}
</programlisting>
</example>
</para>
</section>

<section id="eap-gtc">
<title>EAP-GTC</title>
<!--
<para>
EAP-GTC allows the following options: 
<link linkend="password">password</link>.
</para>
-->
<para>
<example>
<title>Example EAP-GTC Configuration</title>
<programlisting role="Config">
logfile = /var/log/xsupplicant.log

startup_command = &lt;BEGIN_COMMAND&gt;dhclient %i&lt;END_COMMAND&gt;

default {
  allow_types = eap-gtc

  identity = &lt;BEGIN_ID&gt;myid@mynet.net&lt;END_ID&gt;

  eap-gtc {
      <!--password = &lt;BEGIN_PASS&gt;password&lt;END_PASS&gt;-->
  }
}
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</section>

<section id="eap-md5">
<title>EAP-MD5</title>
<para>
EAP-MD5 allows the following option(s): 
<link linkend="password">password</link>.
</para>

<para>
<example>
<title>Example EAP-MD5 Configuration</title>
<programlisting role="Config">
logfile = /var/log/xsupplicant.log

startup_command = &lt;BEGIN_COMMAND&gt;dhclient %i&lt;END_COMMAND&gt;

default {
  allow_types = eap-md5

  identity = &lt;BEGIN_ID&gt;myid@mynet.net&lt;END_ID&gt;

  eap-md5 {
      password = &lt;BEGIN_PASS&gt;password&lt;END_PASS&gt;
  }
}
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</section>

<section id="eap-mschapv2">
<title>EAP-MSCHAPv2</title>
<para>
Valid eap-mschapv2 options are: 
<link linkend="username">username</link> (only needed when using mshcapv2 as a phase 2 type), 
<link linkend="password">password</link>.
</para>
<para>
eap-mschapv2 can also be defined as a sub-option inside of a PEAP profile. 
See the <link linkend="peap">PEAP</link> section for an example.  
</para>
<para>
<example>
<title>Example EAP-MSCHAPv2 Configuration</title>
<programlisting>
logfile=/var/log/xsupplicant.log

startup_command = &lt;BEGIN_COMMAND&gt;dhclient %i&lt;END_COMMAND&gt;

default {
  allow_types = eap-mschapv2

  identity = &lt;BEGIN_ID&gt;myid@mynet.net&lt;END_ID&gt;
  
  eap-mschapv2 {      
      password = &lt;BEGIN_PASS&gt;password&lt;END_PASS&gt;
  }
}
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</section>

<section id="eap-otp">
<title>EAP-OTP</title>
<!--
<para>
EAP-OTP allows the following options: <link linkend="password">password</link>.
</para>
-->
<para>
<example>
<title>Example EAP-OTP Configuration</title>
<programlisting role="Config">
logfile = /var/log/xsupplicant.log

startup_command = &lt;BEGIN_COMMAND&gt;dhclient %i&lt;END_COMMAND&gt;

default {
  allow_types = eap-otp

  identity = &lt;BEGIN_ID&gt;myid@mynet.net&lt;END_ID&gt;

  eap-otp {
       <!--password = &lt;BEGIN_PASS&gt;password&lt;END_PASS&gt;-->
  }
}
</programlisting>
</example>
</para>
</section>

<section id="eap-sim">
<title>EAP-SIM</title>
<para>
EAP-SIM allows the following options: 
<link linkend="username">username</link>, 
<link linkend="password">password</link>, 
<link linkend="auto_realm">auto_realm</link>.
</para>
<para>
<example>
<title>Example EAP-SIM Configuration</title>
<programlisting role="Config">
logfile = /var/log/xsupplicant.log

startup_command = &lt;BEGIN_COMMAND&gt;dhclient %i&lt;END_COMMAND&gt;

default {
  allow_types = eap-sim

  identity = &lt;BEGIN_ID&gt;myid@mynet.net&lt;END_ID&gt;

  eap-sim {
      username = &lt;BEGIN_UNAME&gt;simuser&lt;END_UNAME&gt;
      password = &lt;BEGIN_PASS&gt;simuserpass!&lt;END_PASS&gt;     
      auto_realm = yes
  }
}
</programlisting>
</example>
</para>
<section>
<title>EAP-SIM Specific Options</title>
<para>
The following list defines options specific to "eap-sim":
</para>
<variablelist>
<varlistentry id="auto_realm">
<term><varname>auto_realm</varname></term>
<listitem>
<para>
The auto_realm option determines whether or not your realm will be 
automatically appended to your username on authentication, or whether the 
user will do this manually in the xsupplicant configuration.  This option 
is fairly dependent on how your service is set up, so check with your provider 
to see if this option should be enabled.
</para>
<para>
Valid auto_realm options are: yes, no.
</para>
<para>
<example>
<title>EAP-SIM Option "auto_realm"</title>
<programlisting>
auto_realm = yes
</programlisting>
</example>
</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>

<section id="peap">
<title>PEAP</title>
<para>
Valid options for PEAP are: 
<link linkend="chunk_size">chunk_size</link>, 
<link linkend="cncheck">cncheck</link>, 
<link linkend="cnexact">cnexact</link>.
<link linkend="crl_dir">crl_dir</link>, 
<link linkend="random_file">random_file</link>, 
<link linkend="root_cert">root_cert</link>, 
<link linkend="root_dir">root_dir</link>, 
<link linkend="session_resume">session_resume</link>, 
<link linkend="user_cert">user_cert</link>, 
<link linkend="user_key">user_key</link>, 
<link linkend="user_key_pass">user_key_pass</link>, 

</para>
<para>
PEAP currently requires <link linkend="eap-mschapv2">eap-mschapv2</link> as a 
sub-option.  Future versions of xsupplicant may include support for other 
embedded EAP-types such as eap-gtc.  In addition, the 
"<link linkend="username">username</link>" directive is 
required for inner-eap types used with PEAP.  
</para>

<para>
<example>
<title>Example PEAP Configuration</title>
<programlisting role="Config">
logfile = /var/log/xsupplicant.log

startup_command = &lt;BEGIN_COMMAND&gt;dhclient %i&lt;END_CLIENT&gt;

default {

  allow_types = all

  identity = &lt;BEGIN_ID&gt;myid@mynet.net&lt;END_ID&gt;

  eap-peap {
      root_cert = /home/user/certificates/root.pem
      chunk_size = 1398
      random_file = /dev/urandom
      cncheck = radiusserver.mynet.net         
      cnexact = yes
      session_resume = no

      eap-mschapv2 {
        username = &lt;BEGIN_UNAME&gt;myid@mynet.net&lt;END_UNAME&gt;
        password = &lt;BEGIN_PASS&gt;password&lt;END_PASS&gt;
      }
  }
}
</programlisting>
</example>
</para>

</section>

<section id="eap-tls">
<title>EAP-TLS</title>
<para>
Valid options for EAP-TLS are: 
<link linkend="chunk_size">chunk_size</link>, 
<!--<link linkend="cncheck">cncheck</link>, -->
<!--<link linkend="cnexact">cnexact</link>.-->
<link linkend="crl_dir">crl_dir</link>, 
<link linkend="random_file">random_file</link>, 
<link linkend="root_cert">root_cert</link>, 
<link linkend="root_dir">root_dir</link>, 
<link linkend="session_resume">session_resume</link>, 
<link linkend="user_cert">user_cert</link>, 
<link linkend="user_key">user_key</link>, 
<link linkend="user_key_pass">user_key_pass</link>, 
</para>
<para>
<example>
<title>Example EAP-TLS Configuration</title>
<programlisting role="Config">
logfile = /var/log/xsupplicant.log

startup_command = &lt;BEGIN_COMMAND&gt;dhclient %i&lt;END_CLIENT&gt;

default {

  allow_types = all

  identity = &lt;BEGIN_ID&gt;myid@mynet.net&lt;END_ID&gt;

  eap_tls {
     user_cert = /home/user/certificates/user-cert.pem
     user_key  = /home/user/certificates/user-key.pem
     user_key_pass = &lt;BEGIN_PASS&gt;password for user-key.pem&lt;END_PASS&gt;
     root_cert = /home/user/certificates/root.pem
     crl_dir = /home/user/certificates/revoked
<!--     cncheck = mynet.net -->
<!--     cnexact = no -->
     chunk_size = 1398
     random_file = /dev/urandom
     session_resume = no
  }
}
</programlisting>
</example>
</para>
</section>

<section id="eap-ttls">
<title>EAP-TTLS</title>
<para>
Valid options for EAP-TTLS are: 
<link linkend="chunk_size">chunk_size</link>, 
<link linkend="cncheck">cncheck</link>, 
<link linkend="cnexact">cnexact</link>.
<link linkend="crl_dir">crl_dir</link>, 
<link linkend="random_file">random_file</link>, 
<link linkend="root_cert">root_cert</link>, 
<link linkend="root_dir">root_dir</link>, 
<link linkend="session_resume">session_resume</link>, 
<link linkend="user_cert">user_cert</link>, 
<link linkend="user_key">user_key</link>, 
<link linkend="user_key_pass">user_key_pass</link>, 
<link linkend="phase2_type">phase2_type</link> 
<!--REVISIT: Need to define phase2_type-->
</para>
<para>
EAP-TTLS may also have one or more sub-options: 
<link linkend="chap">chap</link>, 
<link linkend="mschap">mschap</link>, 
<link linkend="mschapv2">mschapv2</link>, 
<link linkend="pap">pap</link>.
<!--REVISIT: Need to define chap, mschap, mschapv2, pap-->
</para>

<para>
<example>
<title>Example EAP-TTLS Configuration</title>
<programlisting role="Config">
logfile = /var/log/xsupplicant.log

startup_command = &lt;BEGIN_COMMAND&gt;dhclient %i&lt;END_COMMAND&gt;

default {
  allow_types = eap-ttls

  identity = &lt;BEGIN_ID&gt;myid@mynet.net&lt;END_ID&gt;

  eap-ttls {
      root_cert = /home/user/certificates/root.pem
      chunk_size = 1398
      random_file = /dev/urandom
      cncheck = myradius.radius.com          
      cnexact = no                          
      session_resume = no
      phase2_type = pap

      pap {
        username = &lt;BEGIN_UNAME&gt;myid@mynet.net&lt;END_UNAME&gt;
        password = &lt;BEGIN_PASS&gt;password&lt;END_PASS&gt;
      }
  }
}
</programlisting>
</example>
</para>

<section>
<title>EAP-TTLS Specific Option(s)</title>
<para>
The following list defines options specifc to "eap-ttls":
</para>
<variablelist>
<varlistentry id="phase2_type">
<term><varname>phase2_type</varname></term>
<listitem>
<para>
The phase2_type directive specifies which phase2 type to use when 
authenticating with TTLS.
</para>
<para>
Valid phase 2 types are: 
<link linkend="chap">chap</link>, 
<link linkend="mschap">mschap</link>, 
<link linkend="mschapv2">mschapv2</link>,
<link linkend="pap">pap</link>.
</para>
<para>
<example>
<title>EAP-TTLS Option "phase2_type"</title>
<programlisting>
phase2_type = pap
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>

<varlistentry id="chap">
<term><varname>chap</varname></term>
<listitem>
<para>
Use this option in TTLS to specify a username and password for 
a CHAP authentication.  
</para>
<para>
Most people will probably want to use PAP with TTLS, however.
</para>
<para>
Valid chap options are:
<link linkend="username">username</link>,
<link linkend="password">password</link>,  
</para>
<para>
<example>
<title>EAP-TTLS Option "chap"</title>
<programlisting>
      chap {
        username = &lt;BEGIN_UNAME&gt;myid@mynet.net&lt;END_UNAME&gt;
        password = &lt;BEGIN_PASS&gt;password&lt;END_PASS&gt;
      }
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>


<varlistentry id="mschap">
<term><varname>mschap</varname></term>
<listitem>
<para>
Use this option in TTLS to specify a username and password for 
an MSCHAP authentication.  
</para>
<para>
Most people will probably want to use PAP with TTLS, however.
</para>
<para>
Valid mschap options are:
<link linkend="username">username</link>,
<link linkend="password">password</link>,  
</para>
<para>
<example>
<title>EAP-TTLS Option "mschap"</title>
<programlisting>
      mschap {
        username = &lt;BEGIN_UNAME&gt;myid@mynet.net&lt;END_UNAME&gt;
        password = &lt;BEGIN_PASS&gt;password&lt;END_PASS&gt;
      }
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>

<varlistentry id="mschapv2">
<term><varname>mschapv2</varname></term>
<listitem>
<para>
Use this option in TTLS to specify a username and password for 
an MSCHAPv2 authentication.  This option is different than <link linkend="eap-mschapv2">eap-mschapv2</link>.
</para>
<para>
Most people will probably want to use PAP with TTLS, however.
</para>
<para>
Valid mschapv2 options are:
<link linkend="username">username</link>,
<link linkend="password">password</link>,  
</para>
<para>
<example>
<title>EAP-TTLS Option "mschapv2"</title>
<programlisting>
      mschapv2 {
        username = &lt;BEGIN_UNAME&gt;myid@mynet.net&lt;END_UNAME&gt;
        password = &lt;BEGIN_PASS&gt;password&lt;END_PASS&gt;
      }
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>

<varlistentry id="pap">
<term><varname>pap</varname></term>
<listitem>
<para>
Use this option in TTLS to specify a username and password for 
a PAP authentication.  
</para>
<para>
Most people will probably want to use this option when authenticating 
with TTLS.
</para>
<para>
Valid pap options are:
<link linkend="username">username</link>,
<link linkend="password">password</link>,  
</para>
<para>
<example>
<title>EAP-TTLS Option "pap"</title>
<programlisting>
      pap {
        username = &lt;BEGIN_UNAME&gt;myid@mynet.net&lt;END_UNAME&gt;
        password = &lt;BEGIN_PASS&gt;password&lt;END_PASS&gt;
      }
</programlisting>
</example>
</para>
<para/><!--Force Spacing - We should probably rethink this-->
</listitem>
</varlistentry>
</variablelist>

</section>


</section>


<section id="leap">
<title>LEAP</title>
<para>
Valid options for LEAP are: 
<link linkend="password">password</link>
</para>

<para>
<example>
<title>Example LEAP Configuration</title>
<programlisting role="Config">
logfile = /var/log/xsupplicant.log

startup_command = &lt;BEGIN_COMMAND&gt;dhclient %i&lt;END_COMMAND&gt;

default {
  allow_types = leap

  identity = &lt;BEGIN_ID&gt;myid@mynet.net&lt;END_ID&gt;

  leap {
      password = &lt;BEGIN_PASS&gt;password&lt;END_PASS&gt;
  }
}
</programlisting>
</example>
</para>
</section>


</section>


<section>
<title>User Config File</title>
<para>
We hope to provide the ability to specify both a global configuration file 
and a more specific user configuration file capability in a future release of 
xsupplicant.
</para>
</section>


<section>
<title>Using a GUI for Configuration</title>
<para>
The current version of Xsupplicant does not provide a mechanism to configure 
itself from a Graphical User Interface, except for providing a password.  
We hope to provide such tools in the future.  Fortunately, the 1.0 config 
file format is much easier to read 
than older versions.  
</para>
<para>
If you have the QT development tools installed, you can compile and use the 
qt-gremlin, or xsup_monitor programs, to provided with Xsupplicant for 
real-time password prompting in X11.  We hope to extend this tool so it can 
also display EAP-Notifications as well.
</para>
</section>

</chapter>
