Documentation update

fetch_doc.rb

@@ -10,7 +10,7 @@ require 'open-uri'
 
 BASE_URI = 'http://www.pamusb.org/wiki/doc/'
 DOC_PATH = './pam_usb/doc/'
-DOCS = [ 'installation', 'upgrading', 'configuration' ]
+DOCS = [ 'installation', 'upgrading', 'configuration', 'faq' ]
 MANS = [ 'pusb_hotplug', 'pusb_adm', 'pusb_check' ]
 
 REPLACE_LIST = [
@@ -55,7 +55,7 @@ DOCS.each do |doc|
 	STDOUT.flush
 
 	text = fetch_doc(doc)
-	File.open(File.join(DOC_PATH, doc), 'w') { |f| f.write(text) }
+	File.open(File.join(DOC_PATH, doc.upcase), 'w') { |f| f.write(text) }
 
 	puts "Done."
 end

pam_usb/Makefile

@@ -41,7 +41,7 @@ CONFS		:= doc/pusb.conf-dist
 CONFS_DEST	:= $(DESTDIR)/etc/pusb
 
 # Doc
-DOCS		:= doc/installation doc/configuration doc/upgrading
+DOCS		:= doc/INSTALLATION doc/CONFIGURATION doc/UPGRADING doc/FAQ
 DOCS_DEST	:= $(DESTDIR)/usr/share/doc/pamusb
 
 # Man

pam_usb/doc/FAQ

@@ -0,0 +1,21 @@
+====== Frequently Asked Questions ======
+
+> Q: Can I use my USB drive as usual ?
+>> A: Yes. pam_usb only occupies a few kilobytes of the device's space.
+
+> Q: What if I lose or break my USB key ? Will I be able to log back in ?
+>> A: Sure. Your usual password will be asked.
+
+> Q: How is the USB key identified ?
+>> A: The USB device is both identified by its manufacturer attributes (vendor,
+product, serial number) and by a few random bytes called one time pads that
+pam_usb writes and updates on the USB device upon authentication.
+
+> Q: What if someone copies the content of my flash drive ? Will she/he be able
+to log into my account ?
+>> A: Even if that person manages to fake your device's attributes (vendor,
+product, serial number, UUID), the one time pad they copied will be outdated as
+soon as you authenticate.
+
+> Q: Is my USB drive compatible with pam_usb ?
+>> A: About every USB flash drive will work with pam_usb.

pam_usb/doc/installation → pam_usb/doc/INSTALLATION

@@ -5,6 +5,7 @@ an older version of pamusb.
 
 ===== Requirements =====
 * Requirements for pam_usb and pusb_check:
+  * libpam
   * libhal-storage
   * libxml2
 
@@ -154,6 +155,49 @@ For instance, with GNOME:
 - Enter pusb_hotplug and press OK
 - Press Close
 
+====== 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:
+<defaults>
+  <option name="debug">true</option>
+</defaults>
+
+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:
+
+<services>
+  <service id="sudo">
+    <option name="debug">true</option>
+  </service>
+</services>
+
 ====== It works - What next ? ======
 
 * Have a look at the configuration documentation