Update README file and manpages

README

@@ -108,8 +108,14 @@ recommended that you start a separate shell with root privileges while
 configuring PAM to be able to revert changes if something goes wrong.
 Test your configuration thoroughly before closing the root shell.
 
+[[moduleArguments]]
 === Module Arguments
 
+The following table documents the set of arguments recognized by the module.
+Hard-wired defaults can be overridden by a <<confFile,configuration file>>.
+The definitions from the configuration file can be in turn overridden by
+individual files under `/etc/pam.d/`.
+
 [horizontal]
 debug::
 Enables debug output
@@ -240,6 +246,12 @@ FIDO devices. It is not possible to mix native credentials and SSH
 credentials. Once this option is enabled all credentials will be parsed
 as SSH.
 
+conf_file=file::
+Set an alternative location for the <<confFile,configuration file>>.
+The supplied path must be absolute, and must correspond to an existing
+regular file.
+The file can be empty.
+
 IMPORTANT: On dynamic networks (e.g. where hostnames are set by DHCP),
 users should not rely on the default origin and appid
 ("pam://$HOSTNAME") but set those parameters explicitly to the same
@@ -404,6 +416,36 @@ defined in the authorization mapping file. If during an authentication attempt
 a connected device is removed or a new device is plugged in, the authentication
 restarts from the top of the list.
 
+[[confFile]]
+== Configuration file
+
+A configuration file can be supplied in order to provide system-level default
+values for the `pam_u2f.so` module arguments.
+
+- The file can contain the same arguments as <<moduleArguments,defined above>>,
+  one per line.
+
+- The `conf_file=` argument, which can only appear under `/etc/pam.d/`.
+
+- Lines starting with `#` are interpreted as comments and skipped together with
+  empty lines.
+
+- Heading white-spaces (intended as in `isspace(3)`) are ignored. Everything
+  from the first non-white-space character till the end of line is interpreted
+  verbatim.
+
+- Square brackets around arguments, needed under `/etc/pam.d` to get spaces
+  correctly recognized, must not be supplied.
+
+The default path of the system-level configuration file is
+`/etc/security/pam_u2f.conf`.  The file is allowed to be missing or empty, in
+which case the `pam_u2f.so` configuration will default to the hard-wired
+values.
+
+Individual files under `/etc/pam.d/` can specify a different configuration file
+by means of the `conf_file=` argument.  Doing so will not affect other
+`/etc/pam.d/` files.
+
 == SELinux Note
 
 Due to an issue with Fedora Linux, and possibly with other

man/pam_u2f.8.txt

@@ -88,6 +88,7 @@ will be ignored.
 Set to prompt a message and wait before testing the presence of a U2F
 device. Recommended if your device doesn't have tactile trigger.
 
+
 *[prompt=your prompt here]*::
 Set individual prompt message for interactive mode. Watch the square
 brackets around this parameter to get spaces correctly recognized by
@@ -134,6 +135,13 @@ FIDO devices. It is not possible to mix native credentials and SSH
 credentials. Once this option is enabled all credentials will be parsed
 as SSH.
 
+*conf_file*=_path_::
+Set an alternative location for the configuration file.
+The supplied path must be absolute, and must correspond to an existing
+regular file.
+The file can be empty.
+See *CONFIGURATION FILE*.
+
 == EXAMPLES
 
 Second factor authentication deferring user verification configuration to the
@@ -162,6 +170,35 @@ mapping file in an encrypted home directory, will result in the
 impossibility of logging into the system. The partition is decrypted
 after login and the mapping file can not be accessed.
 
+== CONFIGURATION FILE
+A configuration file can be supplied in order to provide system-level default
+values for the `pam_u2f.so` module arguments.
+
+- The file can contain the same arguments as <<moduleArguments,defined above>>,
+  one per line.
+
+- The `conf_file=` argument, which can only appear under `/etc/pam.d/`.
+
+- Lines starting with `#` are interpreted as comments and skipped together with
+  empty lines.
+
+- Heading white-spaces (intended as in `isspace(3)`) are ignored. Everything
+  from the first non-white-space character till the end of line is interpreted
+  verbatim.
+
+- Square brackets around arguments, needed under `/etc/pam.d` to get spaces
+  correctly recognized, must not be supplied.
+
+The default path of the system-level configuration file is
+`/etc/security/pam_u2f.conf`.  The file is allowed to be missing or empty, in
+which case the `pam_u2f.so` configuration will default to the hard-wired
+values.
+
+Individual files under `/etc/pam.d/` can specify a different configuration file
+by means of the `conf_file=` argument.  Doing so will not affect other
+`/etc/pam.d/` files.
+
+
 == NOTES
 
 *Nodetect*