diff --git a/Makefile b/Makefile index a9bb755..a29dc6d 100644 --- a/Makefile +++ b/Makefile @@ -43,7 +43,7 @@ CONFS := doc/pamusb.conf CONFS_DEST := $(DESTDIR)/etc # Doc -DOCS := doc/QUICKSTART doc/CONFIGURATION doc/UPGRADING doc/FAQ +DOCS := doc/CONFIGURATION DOCS_DEST := $(DESTDIR)/usr/share/doc/pamusb # Man diff --git a/doc/QUICKSTART b/doc/QUICKSTART deleted file mode 100644 index 1c29f1e..0000000 --- a/doc/QUICKSTART +++ /dev/null @@ -1,238 +0,0 @@ -====== Quickstart ====== - -Before going ahead, make sure to follow the upgrading instructions if you're -using a version of pam_usb prior to 0.4.0. - -===== Installing ==== - - -==== Gentoo Linux ==== - -# emerge -av pam_usb - - -==== Ubuntu and Debian ==== - -# apt-get install libpam-usb pamusb-tools - - -==== 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, udisks and pmount. 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 git ==== - -If you want to use the development version, you can fetch the sources from -GitHub -$ git clone git:github.com/aluzzardi/pam_usb.git - -===== 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/doc/UPGRADING b/doc/UPGRADING deleted file mode 100644 index 62375db..0000000 --- a/doc/UPGRADING +++ /dev/null @@ -1,58 +0,0 @@ -====== Upgrading ====== - -If you're already using a pam_usb version prior to 0.4.0, you will have to -remove the older version before installing. - -You do not have to do this if you're already using >=0.4.0. - -===== Remove pam_usb.so from pam.d ===== - -$ grep -r pam_usb.so /etc/pam.d -/etc/pam.d/su:auth sufficient pam_usb.so -/etc/pam.d/gdm:auth sufficient pam_usb.so -[...] - -Edit every matching file and remove the pam_usb.so lines. -At the end of the operation, there shouldn't be any file contanining a reference -to pam_usb.so: - -$ grep -r pam_usb /etc/pam.d -$ - - -===== Remove .auth directories ===== - -Older versions of pam_usb used to create .auth directories in both the device -and the user's home directory. Those directories aren't used anymore, so feel -free to remove them: - -# rm -rf /root/.auth -# rm -rf /home/scox/.auth -# rm -rf /media/usbdisk/.auth - - - -===== Remove configuration files ===== - -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 - - - -===== Deinstall pam_usb ===== - -If you installed the old pam_usb version using your operating system's package -manager, then remove it by the same mean. - -Otherwise, you can remove it by hand by performing the following instructions: - -# rm -f /usr/bin/usbadm /usr/share/man/usbadm.1.gz -# rm -f /usr/bin/usbhotplug /etc/hotplug.d/default/pamusb.hotplug -/etc/pam.d/usbhotplug -# rm -f /lib/security/pam_usb.so - -===== Next ===== - -Go aheand and install the new version.