diff --git a/pam_usb/doc/CONFIGURATION b/pam_usb/doc/CONFIGURATION
index 0b24fb7..da72e85 100644
--- a/pam_usb/doc/CONFIGURATION
+++ b/pam_usb/doc/CONFIGURATION
@@ -1,6 +1,9 @@
====== Configuration ======
+
+
+
===== Introduction =====
* The configuration file is formatted in XML and subdivided in 4 sections:
@@ -31,7 +34,7 @@
* Location of the configuration file
By default, pam_usb.so and its tools will look for the configuration file
-located in /etc/pusb/pusb.conf, but you can tell it to use a different file by
+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
@@ -39,8 +42,9 @@ 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 pusb_hotplug:
-pusb_hotplug -c /some/other/path.conf
+instance, when calling pamusb-agent:
+pamusb-agent -c /some/other/path.conf
+
@@ -62,9 +66,9 @@ wait for the volume to be detected|
| hostname | String | Computer's hostname | Computer name. Must be
unique accross computers using the same device |
-| system_pad_directory | String | .pusb | Relative path to the
+| system_pad_directory | String | .pamusb | Relative path to the
user's home used to store one time pads |
-| device_pad_directory | String | .pusb | Relative path to the
+| device_pad_directory | String | .pamusb | Relative path to the
device used to store one time pads|
* Example:
@@ -124,6 +128,7 @@ SNDKXXXXXXXXXXXXXXXX |
6F6B-42FC
+
===== Users =====
^ Name ^ Type ^ Description ^
@@ -132,7 +137,7 @@ Example ^
|
| device | Element | id of the device associated to the user |
MyDevice |
-| hotplug | Element | Hotplug commands, for use with pusb_hotplug | See
+| agent | Element | Agent commands, for use with pamusb-agent | See
below |
* Example:
@@ -163,6 +168,7 @@ beep-media-player -->
+
===== Full example =====
This example demonstrates how to write a pam_usb configuration file and how to
@@ -180,7 +186,7 @@ combine and override options.
-
+
SanDisk Corp.Cruzer TitaniumSNDKXXXXXXXXXXXXXXXX
@@ -219,7 +225,7 @@ enabled.
override the "quiet" option -->
-
+
gnome-screensaver-command --lockgnome-screensaver-command --deactivate
diff --git a/pam_usb/doc/INSTALLATION b/pam_usb/doc/INSTALLATION
deleted file mode 100644
index a54822d..0000000
--- a/pam_usb/doc/INSTALLATION
+++ /dev/null
@@ -1,214 +0,0 @@
-====== Installation ======
-
-Before going ahead, be sure to follow the upgrading instructions if you're using
-an older version of pam_usb.
-
-===== Requirements =====
-* Requirements for pam_usb and pusb_check:
- * libpam
- * libhal-storage
- * libxml2
-
-* Requirements for pusb_hotplug and pusb_conf:
- * python2.4
- * python-celementtree
- * python-dbus
- * python-gobject
-
-===== Installing from sources =====
-* Step 1: Download the latest release
-* Step 2: Unpack the distribution tarball
-
-$ tar -zxvf pam_usb-.tar.gz
-$ cd pam_usb-
-
-* Step 3: Compile and install
-
-$ make
-# make install
-
-====== Configuring ======
-
-===== Devices and Users =====
-
-* Copy the default configuration file to /etc/pusb/pusb.conf:
-
-cp /etc/pusb/pusb.conf-dist /etc/pusb/pusb.conf
-
-* Once you've connected your USB device to the computer, use pusb_conf to add it
-to the configuration file:
-
-# pusb_conf --add-device MyDevice
-Name : MyDevice
-Vendor : SanDisk Corp.
-Model : Cruzer Titanium
-Serial : SNDKXXXXXXXXXXXXXXXX
-Volume UUID : 6F6B-42FC (/dev/sda1)
-Save device to /etc/pusb/pusb.conf ?
-[y/n] y
-Done.
-
-Note that MyDevice can be any arbitrary name you'd like.
-If more devices are connected, pusb_conf will ask you which device you want to
-use.
-
-* Edit your /etc/pusb/pusb.conf config file to add the users:
-
-
- MyDevice
-
-
-
- MyDevice
-
-
-
-* In order to test if everything went fine, we're gonna use the pusb_check tool
-which will simulate an authentication event.
-
-# pusb_check -a -u root -s su
-* Authentication request for user "root" (su)
-* Device "MyDevice" is connected (good).
-* Performing one time pad verification...
-* Verification match, updating one time pads...
-* Access granted.
-
-===== PAM Module =====
-
-The PAM module pam_usb.so is used to let applications authenticate you using
-your USB device instead of asking your password. The default password-based
-authentication will be used as fallback if the device authentication goes wrong.
-
-You don't need to setup the hotplugging feature as pam_usb.so and pusb_hotplug
-are independent of each other.
-
-* Depending on the operating system you're using, you have to tell PAM to use
-pam_usb.so as default authentication method. There should be a file named
-either common-auth (Gentoo) under /etc/pam.d/. If you do NOT have neither of
-those files, you'll have to edit each pam.d service file you want to use (e.g.
-/etc/pam.d/su, /etc/pam.d/gdm and so on).
-
-* Locate the following line on /etc/pam.d/common-auth or /etc/pam.d/system-auth:
-
-auth required pam_unix.so nullok_secure
-
-* And change it to look something like that:
-
-auth sufficient pam_usb.so
-auth required pam_unix.so nullok_secure
-
-* You should now be able to authenticate the users configured in pusb.conf using
-your USB device:
-
-scox $ su
-* pam_usb v.SVN
-* Authentication request for user "root" (su)
-* Device "MyDevice" is connected (good).
-* Performing one time pad verification...
-* Verification match, updating one time pads...
-* Access granted.
-
-* Try to authenticate to a different application. pam_usb.so should work with
-any application using xscreensaver and many more).
-
-===== Hotplug =====
-
-Hotplugging is a feature provided by pusb_hotplug that allows you to
-automatically execute commands upon locking and unlocking events. Those events
-are generated when you insert or remove your authentication device.
-
-For instance, you could automatically start your screensaver as soon as you
-remove the device, and deactivate it when you plug the device back.
-
-* GNOME (gnome-screensaver):
-
- MyDevice
- gnome-screensaver-command --lock
- gnome-screensaver-command --deactivate
-
-
-* KDE (kscreensaver):
-
- MyDevice
- dcop kdesktop KScreensaverIface lock
- dcop kdesktop KScreensaverIface quit
-
-
-
-You can also execute more commands by adding extra entries.
-
-
-$ pusb_hotplug
-pusb_hotplug[18329]: pusb_hotplug up and running.
-pusb_hotplug[18329]: Watching device "MyDevice" for user "scox"
-pusb_hotplug[18329]: Device "MyDevice" has been removed, locking down user
-"scox"...
-pusb_hotplug[18329]: Running "gnome-screensaver-command --lock"
-pusb_hotplug[18329]: Locked.
-pusb_hotplug[18329]: Device "MyDevice" has been inserted. Performing
-verification...
-pusb_hotplug[18329]: Executing "/usr/bin/pusb_check -q -c /etc/pusb/pusb.conf -u
-scox -s pusb_hotplug -a"
-pusb_hotplug[18329]: Authentication succeeded. Unlocking user "scox"...
-pusb_hotplug[18329]: Running "gnome-screensaver-command --deactivate"
-pusb_hotplug[18329]: Unlocked.
-
-Depending on your desktop environment, you have to add pusb_hotplug to the list
-of autostarted applications so it will be started automatically.
-
-* GNOME:
- - Open System -> Preferences -> Sessions
- - Select Startup Programs and press Add
- - Enter pusb_hotplug and press OK
- - Press Close
-
-* KDE:
- - cd ~/.kde/Autostart
- - ln -s /usr/bin/pusb_hotplug pusb_hotplug
-
-====== Troubleshooting ======
-
-===== Log Analysis =====
-
-Both pam_usb.so and pusb_hotplug use the syslog facility to log authentication
-attempts.
-This can be useful for GUI-driven applications (for instance GDM) where you
-don't get to see console output.
-Messages are logged with the AUTH facility, they are usually written to
-/var/log/auth.log but may vary
-depending on the operating system you're using.
-
-# tail -f /var/log/auth.log
-pusb_hotplug[25429]: Device "sandisk" has been inserted. Performing
-verification...
-pusb_hotplug[25429]: Executing "/usr/bin/pusb_check -q -c /etc/pusb/pusb.conf -u
-scox -s pusb_hotplug -a"
-pam_usb[25485]: Authentication request for user "scox" (pusb_hotplug)
-pam_usb[25485]: Device "sandisk" is connected (good).
-pam_usb[25485]: Access granted.
-pusb_hotplug[25429]: Authentication succeeded. Unlocking user "scox"...
-pusb_hotplug[25429]: Unlocked.
-
-===== Enabling debug =====
-
-Enabling debug messages may help you find out what's wrong.
-
-To enable them, edit /etc/pusb/pusb.conf and set the following option:
-
-
-
-
-If you wish, you could enable debug messages only for a specific user, device or
-service.
-For instance, if you want to enable debug messages only for the sudo service,
-you could do the following:
-
-
-
-
-
-
-
-====== It works - What next ? ======
-
-* Have a look at the configuration documentation
diff --git a/pam_usb/doc/QUICKSTART b/pam_usb/doc/QUICKSTART
new file mode 100644
index 0000000..d502914
--- /dev/null
+++ b/pam_usb/doc/QUICKSTART
@@ -0,0 +1,227 @@
+====== Quickstart ======
+
+Before going ahead, make sure to follow the upgrading instructions if you're
+using an older version of pam_usb.
+
+===== Installing ====
+
+
+==== Installing from sources ====
+* Step 1: Download the latest release
+* Step 2: Unpack the distribution tarball
+
+$ tar -zxvf pam_usb-.tar.gz
+$ cd pam_usb-
+
+* Step 3: Make sure that you have installed the required dependencies
+
+pam_usb depends on libxml2, PAM and HAL. pam_usb's tools (pamusb-agent,
+pamusb-conf) depends on python, python-celementtree and python-gobject.
+
+* Step 3: Compile and install
+
+$ make
+# make install
+
+==== Installing from Subversion ====
+
+If you want to use the development version, you can fetch the sources from
+subversion
+$ svn co https:pamusb.svn.sourceforge.net/svnroot/pamusb/trunk/pam_usb
+
+===== Setting up =====
+
+
+
+==== Devices and Users ====
+
+* Once you've connected your USB device to the computer, use pamusb-conf to add
+it to the configuration file:
+
+# pamusb-conf --add-device MyDevice
+Please select the device you wish to add.
+* Using "SanDisk Corp. Cruzer Titanium (SNDKXXXXXXXXXXXXXXXX)" (only option)
+Which volume would you like to use for storing data ?
+* Using "/dev/sda1 (UUID: <6F6B-42FC>)" (only option)
+Name : MyDevice
+Vendor : SanDisk Corp.
+Model : Cruzer Titanium
+Serial : SNDKXXXXXXXXXXXXXXXX
+Volume UUID : 6F6B-42FC (/dev/sda1)
+Save to /etc/pamusb.conf ?
+[Y/n] y
+Done.
+
+Note that MyDevice can be any arbitrary name you'd like. Also, you can add as
+many devices as you want.
+
+* Users
+
+Now that we have added the devices, we have to configure the users.
+
+ # pamusb-conf --add-user root
+ Which device would you like to use for authentication ?
+ * Using "MyDevice" (only option)
+ User : root
+ Device : MyDevice
+ Save to /etc/pamusb.conf ?
+ [Y/n] y
+ Done.
+
+Repeat this step for every other username you'd like to use pam_usb with (e.g.
+pamusb-conf --add-user MyUsername).
+
+* In order to check if everything went fine, we are going to use the
+pamusb-check tool which will simulate an authentication event.
+
+# pamusb-check root
+* Authentication request for user "root" (pamusb-check)
+* Device "MyDevice" is connected (good).
+* Performing one time pad verification...
+* Verification match, updating one time pads...
+* Access granted.
+
+
+
+==== PAM Module ====
+
+The PAM module pam_usb.so is used to let applications authenticate you using
+your USB device instead of asking your password. The default password-based
+authentication will be used as fallback if the device authentication goes wrong.
+
+* Depending on the operating system you're using, you have to tell PAM to use
+pam_usb.so as default authentication method. There should be a file named
+either common-auth (Gentoo) under /etc/pam.d/. If you do NOT have neither of
+those files, you'll have to edit each pam.d service file you want to use (e.g.
+/etc/pam.d/su, /etc/pam.d/gdm and so on).
+
+* Locate the following line on /etc/pam.d/common-auth or /etc/pam.d/system-auth:
+
+auth required pam_unix.so nullok_secure
+
+* And change it to look something like that:
+
+auth sufficient pam_usb.so
+auth required pam_unix.so nullok_secure
+
+* You should now be able to authenticate the users configured in pamusb.conf
+using your USB device:
+
+scox $ su
+* pam_usb v.SVN
+* Authentication request for user "root" (su)
+* Device "MyDevice" is connected (good).
+* Performing one time pad verification...
+* Verification match, updating one time pads...
+* Access granted.
+
+* Try to authenticate to a different application. pam_usb.so should work with
+any application using xscreensaver and many more).
+
+
+
+
+==== Agent ====
+
+The pam_usb agent (pamusb-agent) allows you to automatically execute commands
+upon locking and unlocking events. Those events are generated when you insert or
+remove your authentication device.
+To configure the commands, you have to edit pam_usb's configuration file
+(/etc/pamusb.conf) and add agent entries into your user section.
+
+For instance, you could automatically start your screensaver as soon as you
+remove the device, and deactivate it when you plug the device back.
+
+* GNOME (gnome-screensaver):
+
+ MyDevice
+ gnome-screensaver-command --lock
+ gnome-screensaver-command --deactivate
+
+
+* KDE (kscreensaver):
+
+ MyDevice
+ dcop kdesktop KScreensaverIface lock
+ dcop kdesktop KScreensaverIface quit
+
+
+You can execute more commands by adding extra entries.
+
+
+$ pamusb-agent
+pamusb-agent[18329]: pamusb-agent up and running.
+pamusb-agent[18329]: Watching device "MyDevice" for user "scox"
+pamusb-agent[18329]: Device "MyDevice" has been removed, locking down user
+"scox"...
+pamusb-agent[18329]: Running "gnome-screensaver-command --lock"
+pamusb-agent[18329]: Locked.
+pamusb-agent[18329]: Device "MyDevice" has been inserted. Performing
+verification...
+pamusb-agent[18329]: Executing "/usr/bin/pamusb-check --quiet
+--config=/etc/pamusb.conf --service=pamusb-agent scox"
+pamusb-agent[18329]: Authentication succeeded. Unlocking user "scox"...
+pamusb-agent[18329]: Running "gnome-screensaver-command --deactivate"
+pamusb-agent[18329]: Unlocked.
+
+Depending on your desktop environment, you have to add pamusb-agent to the list
+of autostarted applications so it will be started automatically.
+
+* GNOME:
+ - Open System -> Preferences -> Sessions
+ - Select Startup Programs and press Add
+ - Enter pamusb-agent and press OK
+ - Press Close
+
+* KDE:
+ - cd ~/.kde/Autostart
+ - ln -s /usr/bin/pamusb-agent pamusb-agent
+
+===== Troubleshooting =====
+
+
+==== Log Analysis ====
+
+Both pam_usb.so and pamusb-agent use the syslog facility to log authentication
+attempts.
+This can be useful for GUI-driven applications (for instance GDM) where you
+don't get to see console output.
+Messages are logged with the AUTH facility, they are usually written to
+/var/log/auth.log but may vary
+depending on the operating system you're using.
+
+# tail -f /var/log/auth.log
+pamusb-agent[25429]: Device "sandisk" has been inserted. Performing
+verification...
+pamusb-agent[25429]: Executing "/usr/bin/pamusb-check --quiet
+--config=/etc/pamusb.conf --service=pamusb-agent scox"
+pam_usb[25485]: Authentication request for user "scox" (pamusb-agent)
+pam_usb[25485]: Device "sandisk" is connected (good).
+pam_usb[25485]: Access granted.
+pamusb-agent[25429]: Authentication succeeded. Unlocking user "scox"...
+pamusb-agent[25429]: Unlocked.
+
+
+==== Enabling debug ====
+
+Enabling debug messages may help you find out what's wrong.
+
+To enable them, edit /etc/pamusb.conf and set the following option:
+
+
+
+
+If you wish, you could enable debug messages only for a specific user, device or
+service.
+For instance, if you want to enable debug messages only for the sudo service,
+you could do the following:
+
+
+
+
+
+
+
+===== It works - What next ? =====
+
+* Have a look at the configuration documentation
diff --git a/pam_usb/doc/UPGRADING b/pam_usb/doc/UPGRADING
index b03c776..270b15a 100644
--- a/pam_usb/doc/UPGRADING
+++ b/pam_usb/doc/UPGRADING
@@ -31,10 +31,11 @@ free to remove them:
# rm -rf /media/usbdisk/.auth
+
===== Remove configuration files =====
-As configuration files of pam_usb 0.4.0 aren't backward compatible and are
-located under /etc/pusb, the old /etc/pam_usb is no more needed.
+As configuration files of pam_usb 0.4.0 aren't backward compatible, the old
+/etc/pam_usb is no more needed.
# rm -rf /etc/pam_usb
diff --git a/pam_usb/doc/pamusb-agent.1.gz b/pam_usb/doc/pamusb-agent.1.gz
index c4e968d..6fad245 100644
Binary files a/pam_usb/doc/pamusb-agent.1.gz and b/pam_usb/doc/pamusb-agent.1.gz differ
diff --git a/pam_usb/doc/pamusb-check.1.gz b/pam_usb/doc/pamusb-check.1.gz
index 988145a..898bd3c 100644
Binary files a/pam_usb/doc/pamusb-check.1.gz and b/pam_usb/doc/pamusb-check.1.gz differ
diff --git a/pam_usb/doc/pamusb-conf.1.gz b/pam_usb/doc/pamusb-conf.1.gz
index 2ace335..b157065 100644
Binary files a/pam_usb/doc/pamusb-conf.1.gz and b/pam_usb/doc/pamusb-conf.1.gz differ
diff --git a/pam_usb/utils/fetch_doc.rb b/pam_usb/utils/fetch_doc.rb
index df2f519..8209b8a 100755
--- a/pam_usb/utils/fetch_doc.rb
+++ b/pam_usb/utils/fetch_doc.rb
@@ -10,7 +10,7 @@ require 'open-uri'
BASE_URI = 'http://www.pamusb.org/wiki/doc/'
DOC_PATH = '../doc/'
-DOCS = [ 'installation', 'upgrading', 'configuration', 'faq' ]
+DOCS = [ 'quickstart', 'upgrading', 'configuration', 'faq' ]
MANS = [ 'pamusb-check', 'pamusb-agent', 'pamusb-conf' ]
REPLACE_LIST = [