diff --git a/doc/CONFIGURATION b/doc/CONFIGURATION index ade966e..58413a8 100644 --- a/doc/CONFIGURATION +++ b/doc/CONFIGURATION @@ -1,264 +1,310 @@ -====== Configuration ====== +Configuration file reference +============================ -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. +The configuration file is formatted in XML and subdivided in 4 sections: -===== Introduction ===== +* Default options, shared among every device, user and service +* Devices declaration and settings +* Users declaration and settings +* Services declaration and settings -* 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: -* The syntax is the following: +```xml - - - + + + - - - + + + - - - + + + - - - + + + - -* 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: - +``` + +Options +------- + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefaultDescription
enableBooleantrueEnable pam_usb
debugBooleanfalseEnable debug messages
quietBooleanfalseQuiet mode
color_logBooleantrueEnable colored output
one_time_padBooleantrueEnable the use of one time pads
deny_remoteBooleantrueDeny access from remote host (ssh)
probe_timeoutTime10sTime to wait for the volume to be detected
pad_expirationTime1hTime between pads regeneration
hostnameStringComputer's hostnameMust be unique accross computers using the same device
system_pad_directoryString.pamusbRelative path to the user's home used to store one time pads
device_pad_directoryString.pamusbRelative path to the device used to store one time pads
+ +Example: + +```xml - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - -===== 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: - +``` + +Devices +------- + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionExample
idAttributeArbitrary device nameMyDevice
vendorElementdevice's vendor nameSanDisk Corp.
modelElementdevice's model nameCruzer Titanium
serialElementserial number of the deviceSNDKXXXXXXXXXXXXXXXX
volume_uuidElementUUID of the device's volume used to store pads6F6B-42FC
+ +Example: + +```xml -SanDisk Corp. -Cruzer Titanium -SNDKXXXXXXXXXXXXXXXX -6F6B-42FC - - - - -===== 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: - - -MyDevice - - -gnome-screensaver-command --lock -beep-media-player --pause - - -gnome-screensaver-command --deactivate -beep-media-player --play - - -===== Services ===== - -^ Name ^ Type ^ Description ^ Example ^ -| id | Attribute | Name of the service | su | - - - - - - - - -===== Full example ===== - -This example demonstrates how to write a pam_usb configuration file and how to -combine and override options. - - - - - - --> - - --> - - - - - - SanDisk Corp. Cruzer Titanium SNDKXXXXXXXXXXXXXXXX 6F6B-42FC - + +``` + +Users +----- + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Example: + +```xml + + MyDevice + + + gnome-screensaver-command --lock + beep-media-player --pause + + + gnome-screensaver-command --deactivate + beep-media-player --play + +``` + +Services +-------- + +
NameTypeDescriptionExample
idAttributeLogin of the userroot
deviceElementid of the device associated to the userMyDevice
agentElementAgent commands, for use with pamusb-agent
+ + + + + + + + + + + + + +
NameTypeDescriptionExample
idAttributeName of the servicesu
+ +Example: +```xml + - - - + +``` - - +Location of the configuration file +---------------------------------- - - - MyDevice +By default, pam_usb.so and its tools will look for the configuration file at `/etc/pamusb.conf`. - - - +If you want to use a different location, you will have to use the `-c` flag. - - - MyDevice + # /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. - - gnome-screensaver-command --lock - gnome-screensaver-command --deactivate - - - - - - - - - - - - - - - - - - + pamusb-agent -c /some/other/path.conf