====== Configuration ======

Configuration is done through the pamusb-conf tool, as explained in the
[[quickstart]] section. Most users don't have to manually change pamusb.conf, 
however if you want to change some default settings, this document explains the
syntax of the pamusb.conf configuration file.

===== Introduction =====

* The configuration file is formatted in XML and subdivided in 4 sections:
  - Default options, shared among every device, user and service
  - Devices declaration and settings
  - Users declaration and settings
  - Services declaration and settings

* The syntax is the following:
<configuration>
 <defaults>
 
 </defaults>

 <devices>
 
 </devices>

 <users>
 
 </users>

 <services>
 
 </services>
</configuration>

* Location of the configuration file

By default, pam_usb.so and its tools will look for the configuration file
located in /etc/pamusb.conf, but you can tell it to use a different file by
using the -c option:

# /etc/pam.d/common-auth
auth    sufficient      pam_usb.so -c /some/other/path.conf
auth    required        pam_unix.so nullok_secure

You will also have to use the -c option when calling pam_usb's tools. For
instance, when calling pamusb-agent:
pamusb-agent -c /some/other/path.conf

===== Options =====

^ Name              ^ Type            ^ Default value       ^ Description  ^
| enable        | Boolean         | true                | Enable pam_usb        
|
| debug         | Boolean         | false               | Enable debug messages 
|
| quiet         | Boolean         | false               | Quiet mode (no verbose
output)                      |
| color_log     | Boolean         | true                | Enable colored output 
|
| one_time_pad  | Boolean         | true                | Enable the use of one
time pads                     |
| deny_remote   | Boolean         | true                | Deny access from
remote host (ssh)                  |
| probe_timeout | Time            | 10s                 | Time to wait for the
volume to be detected|
| pad_expiration| Time            | 1h                  | Time between pads
regeneration|
| hostname      | String          | Computer's hostname | Computer name. Must be
unique accross computers using the same device |                                

| system_pad_directory | String   | .pamusb             | Relative path to the
user's home used to store one time pads |
| device_pad_directory | String   | .pamusb             | Relative path to the
device used to store one time pads|

* Example:

<configuration>
<defaults>
  
  false
  
  true
 </defaults>
 <users>
   <user id="root">
     
     true
   </user>
   <user id="scox">
     
     false
 </users>
 <devices>
   <device id="sandisk">
     
     15
 </devices>
 <services>
   <service id="su">
     
     false
   </service>
 </services>
</configuration>

===== Devices =====

^ Name            ^ Type      ^ Description                                    ^
Example              ^
| id          | Attribute | Arbitrary device name                          |
MyDevice             |
| vendor      | Element   | device's vendor name                           |
SanDisk Corp.        |
| model       | Element   | device's model name                            |
Cruzer Titanium      |
| serial      | Element   | serial number of the device                    |
SNDKXXXXXXXXXXXXXXXX |
| volume_uuid | Element   | UUID of the device's volume used to store pads |
6F6B-42FC            |

* Example:

<device id="MyDevice">
<vendor>SanDisk Corp.</vendor>
<model>Cruzer Titanium</model>
<serial>SNDKXXXXXXXXXXXXXXXX</serial>
<volume_uuid>6F6B-42FC</volume_uuid>
</device>

===== Users =====

^ Name            ^ Type      ^ Description                                 ^
Example     ^
| id          | Attribute | Login of the user                           | root  
|
| device      | Element   | id of the device associated to the user     |
MyDevice    |
| agent       | Element   | Agent commands, for use with pamusb-agent   | See
below   |

* Example:

<user id="scox">
<device>MyDevice</device>

<agent event="lock">gnome-screensaver-command --lock</agent>
<agent event="lock">beep-media-player --pause</agent>

<agent event="unlock">gnome-screensaver-command --deactivate</agent>
<agent event="unlock">beep-media-player --play</agent>
</user>

===== Services =====

^ Name ^ Type      ^ Description         ^ Example ^
| id   | Attribute | Name of the service | su      |

<service id="su">

</service>

===== Full example =====

This example demonstrates how to write a pam_usb configuration file and how to
combine and override options.

<configuration>

<defaults>
  
  true -->
  
  false -->
</defaults>

<devices>
  <device id="MyDevice">
    
    <vendor>SanDisk Corp.</vendor>
    <model>Cruzer Titanium</model>
    <serial>SNDKXXXXXXXXXXXXXXXX</serial>
    <volume_uuid>6F6B-42FC</volume_uuid>

    <!--
      Override the debug option previously enabled by "defaults".
      Everytime a user associated to that device tries to authenticate,
debugging will be disabled.
      For other users using different devices, the debugging will still be
enabled.
    -->
    disable
  </device>
</devices>

<users>

  <user id="root">
    <device>MyDevice</device>

    <!--
      One time pads were disabled in the "defaults" section.
      Now we want to enable them for the user "root" so we override the option:
    -->
   true
  </user>

  <user id="scox">
    <device>MyDevice</device>

    <!-- We want pam_usb to work in quiet mode when authenticating "scox", so we
override the "quiet" option -->
    true

    <!-- Agent settings, used by pamusb-agent -->
    <agent event="lock">gnome-screensaver-command --lock</agent>
    <agent event="unlock">gnome-screensaver-command --deactivate</agent>
  </user>
</users>

<services>

  <service id="gdm">
    false
  </service>

  <!--
    We already disabled one time pads in the defaults section, but then
re-enabled them for the
    user "root" in the users section.

    Now we want to speed up console login for user root, so we simply override
again the one_time_pad option
    for the "login" (console) service.
  -->
  <service id="login">
    false
  </service>
</services>
</configuration>

