diff --git a/doc/CONFIGURATION.md b/doc/CONFIGURATION.md
index a5943a1..65400ac 100644
--- a/doc/CONFIGURATION.md
+++ b/doc/CONFIGURATION.md
@@ -30,96 +30,25 @@ The syntax is the following:
```
-Options
--------
-
-
-
-
Name
-
Type
-
Default
-
Description
-
-
-
-
enable
-
Boolean
-
true
-
Enable pam_usb
-
-
-
-
debug
-
Boolean
-
false
-
Enable debug messages
-
-
-
-
quiet
-
Boolean
-
false
-
Quiet mode
-
-
-
-
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
-
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
+
+| Name | Type | Default | Description |
+|------------------------|---------|---------------------|--------------------------------------------------------------|
+| `enable` | Boolean | `true` | Enable pam_usb |
+| `debug` | Boolean | `false` | Enable debug messages |
+| `quiet` | Boolean | `false` | Quiet mode |
+| `color_log` | Boolean | `true` | Enable colored output |
+| `one_time_pad` | Boolean | `true` | Enable the use of one time device-associated pad files |
+| `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 pad file regeneration |
+| `hostname` | String | Computer's hostname | 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 pad files |
+
+### Example:
```xml
@@ -129,7 +58,7 @@ Example:
-
+
@@ -158,54 +87,20 @@ Example:
```
-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
+
+
+| 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:
```xml
@@ -216,52 +111,30 @@ Example:
```
-Users
------
-
-
-
-
-
Name
-
Type
-
Description
-
Example
-
-
-
-
id
-
Attribute
-
Login of the user
-
root
-
-
-
-
device
-
Element
-
id of the device associated to the user
-
MyDevice
-
-
-
-
agent
-
env
-
Element
-
An environment variable for the command. For multiple variables use multiple env tags
-
-
cmd
-
Element
-
Agent command, associated with env tags in the same agent element
-
Element
-
Agent commands, for use with pamusb-agent
-
-
-
-Example:
+----------
+
+## Users
+
+| Name | Type | Description | Example |
+|----------|-----------|-------------------------------------------|------------|
+| `id` | Attribute | Login of the user | `root` |
+| `device` | Attribute | `id` of the device associated to the user | `MyDevice` |
+| `agent` | Element | Agent commands, for use with pamusb-agent | |
+
+### Agent
+
+
+| Name | Type | Description |
+|-------|-----------|-----------------------------------------------------------------------------------------------------|
+| `env` | Attribute | An environment variable for the command. For multiple environment variables use multiple `env` tags |
+| `cmd` | Attribute | Agent command, associated with `env` tags in the same agent element |
+
+### Example:
```xml
MyDevice
-
+
@@ -272,7 +145,7 @@ Example:
beep-media-player --pause
-
+
DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus
@@ -285,26 +158,15 @@ Example:
```
-Services
---------
-
-
-
-
Name
-
Type
-
Description
-
Example
-
-
-
-
id
-
Attribute
-
Name of the service
-
su
-
-
-
-Example:
+----------
+
+## Services
+
+| Name | Type | Description | Example |
+|------|-----------|---------------------|---------|
+| `id` | Attribute | Name of the service | `su` |
+
+### Example:
```xml
@@ -315,17 +177,64 @@ Example:
```
+----------
+
Location of the configuration file
----------------------------------
-By default, pam_usb.so and its tools will look for the configuration file at `/etc/security/pam_usb.conf`.
+By default, `pam_usb.so` and its tools will look for the configuration file at `/etc/security/pam_usb.conf`.
If you want to use a different location, you will have to use the `-c` flag.
- # /etc/pam.d/common-auth
- auth sufficient pam_usb.so -c /some/other/path.conf
- auth required pam_unix.so nullok_secure
+```
+# /etc/pam.d/system-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.
+
+```
+pamusb-agent -c /some/other/path.conf
+```
+
+Example configuration
+----------------------------------
+
+**NOTE**: For detailed information, rely on repository wiki pages.
+
+* **1)** Insert an USB block device
+* **2)** Add necessary user configuration into `/etc/security/pam_usb.conf` by running:
+
+```
+sudo pamusb-conf --add-user=
+```
+
+where `` is a valid Unix user name.
+
+* **3)** Add necessary device configuration into `/etc/security/pam_usb.conf` by running:
+
+```
+sudo pamusb-conf --add-device=
+```
+
+where `` is a recognizable name for your device. This value is only used internally in the configuration file as device `id` value.
+
+* **4)** Tweak `/etc/security/pam_usb.conf` manually as desired. Link devices and users, etc.
+
+**NOTE**: If you don't want to use one time pad files, consider setting `one_time_pad` option to `false`. Pad file use defaults to `true`.
+
+If you use one time pads, you need to do the following:
+
+* **5)** Manually mount USB block device partition. You need write access to the mounted partition.
+
+* **6)** Run `/usr/bin/pamusb-check --debug --service=pamusb-agent `
+
+where `` is associated with the USB block device.
-You will also have to use the -c option when calling pam_usb's tools.
+By default, this command creates directory `$HOME/.pamusb/` with a protected device-associated `.pad` file. If you format the device, you must
+delete `$HOME/.pamusb/.pad` file. The created `.pad` file can't be used with a new partition UUIDs for the same or any USB block device.
- pamusb-agent -c /some/other/path.conf
+* **7)** Unmount the USB block device.
+* **8)** Add proper PAM configuration into `/etc/pam.d/system-auth` as described above. For testing purposes, it's highly recommended to start with `sufficient` PAM option before possibly moving to `required` or `requisite` option since you can bypass faulty `pam_usb` configurations.
+* **9)** Test the device/user configuration by running `sudo echo "pam_usb test"`. The USB block device must be attached (mount not required) and the user must have proper configuration in `/etc/security/pam_usb.conf` file.