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.
<configuration> <defaults> <!-- default options --> </defaults> <devices> <!-- devices definitions --> </devices> <users> <!-- users definitions --> </users> <services> <!-- services definitions --> </services> </configuration>
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
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 |
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 |
<configuration> <defaults> <!-- Disable colored output by default --> <option name="color_log">false</option> <!-- Enable debug output --> <option name="debug">true</option> </defaults> <users> <user id="root"> <!-- Enable colored output for user "root" --> <option name="color_log">true</option> </user> <user id="scox"> <!-- Disable debug output for user "scox" --> <option name="debug">false</option> </users> <devices> <device id="sandisk"> <!-- Wait 15 seconds instead of the default 10 seconds for the "sandisk" device to be detected --> <option name="probe_timeout">15</option> </devices> <services> <service id="su"> <!-- Disable pam_usb for "su" ("su" will ask for a password as usual) --> <option name="enable">false<option> </service> </services> </configuration>
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 |
<device id="MyDevice"> <vendor>SanDisk Corp.</vendor> <model>Cruzer Titanium</model> <serial>SNDKXXXXXXXXXXXXXXXX</serial> <volume_uuid>6F6B-42FC</volume_uuid> </device>
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 |
<user id="scox"> <device>MyDevice</device> <!-- When the user "scox" removes the usb device, lock the screen and pause beep-media-player --> <agent event="lock">gnome-screensaver-command --lock</agent> <agent event="lock">beep-media-player --pause</agent> <!-- Resume operations when the usb device is plugged back and authenticated --> <agent event="unlock">gnome-screensaver-command --deactivate</agent> <agent event="unlock">beep-media-player --play</agent> </user>
Name | Type | Description | Example |
---|---|---|---|
id | Attribute | Name of the service | su |
<service id="su"> <!-- Here you can put service specific options such as "enable", "debug" etc. See the options section of this document. --> </service>
This example demonstrates how to write a pam_usb configuration file and how to combine and override options.
<configuration> <!-- Default options --> <defaults> <!-- Enable debug output by default--> <option name="debug">true</option> --> <!-- Disable one time pads by default --> <option name="one_time_pad">false</option> --> </defaults> <!-- Device settings --> <devices> <device id="MyDevice"> <!-- This part was generated by pamusb-conf --> <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. --> <option name="debug">disable</option> </device> </devices> <!-- User settings --> <users> <!-- Authenticate user "root" with device "MyDevice". --> <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: --> <option name="one_time_pad">true</option> </user> <!-- Authenticate user "scox" with device "MyDevice". --> <user id="scox"> <device>MyDevice</device> <!-- We want pam_usb to work in quiet mode when authenticating "scox", so we override the "quiet" option --> <option name="quiet">true</option> <!-- 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 settings (e.g. gdm, su, sudo...) --> <services> <!-- Disable pam_usb for gdm (a password will be asked as usual) --> <service id="gdm"> <option name="enable">false</option> </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"> <option name="one_time_pad">false</option> </service> </services> </configuration>