[linux-pam] Clarify pam_access docs re PAM service names and X $DISPLAY value testing. (Ticket #39)

[kukuk]

commit 7b39983f3a7b5e7522f1672e49dcbfe579f0228f
Author: Thorsten Kukuk <kukuk(a)thkukuk.de&gt;
Date:   Tue Mar 24 16:57:14 2015 +0100

    Clarify pam_access docs re PAM service names and X $DISPLAY value testing.
    (Ticket #39)
    
    * modules/pam_access/access.conf.5.xml
    * modules/pam_access/pam_access.8.xml
    
    Signed-off-by: Karl O. Pinc <kop at meme.com>

 modules/pam_access/access.conf.5.xml |   40 +++++++++++++++++++++++++++------
 modules/pam_access/pam_access.8.xml  |    5 ++-
 2 files changed, 35 insertions(+), 10 deletions(-)
---
diff --git a/modules/pam_access/access.conf.5.xml b/modules/pam_access/access.conf.5.xml
index a4d3419..d686d92 100644
--- a/modules/pam_access/access.conf.5.xml
+++ b/modules/pam_access/access.conf.5.xml
@@ -21,8 +21,12 @@
     <para>
       The <filename>/etc/security/access.conf</filename> file specifies
       (<replaceable>user/group</replaceable>,
<replaceable>host</replaceable>),
-      (<replaceable>user/group</replaceable>,
<replaceable>network/netmask</replaceable>) or
-      (<replaceable>user/group</replaceable>,
<replaceable>tty</replaceable>)
+      (<replaceable>user/group</replaceable>,
<replaceable>network/netmask</replaceable>),
+      (<replaceable>user/group</replaceable>,
<replaceable>tty</replaceable>),
+      (<replaceable>user/group</replaceable>,
+      <replaceable>X-$DISPLAY-value</replaceable>), or
+      (<replaceable>user/group</replaceable>,
+      <replaceable>pam-service-name</replaceable>)
       combinations for which a login will be either accepted or refused.
     </para>
     <para>
@@ -33,7 +37,14 @@
       combination, or, in case of non-networked logins, the first entry
       that matches the
       (<replaceable>user/group</replaceable>,
<replaceable>tty</replaceable>)
-      combination.  The permissions field of that table entry determines
+      combination, or in the case of non-networked logins without a
+      tty, the first entry that matches the
+      (<replaceable>user/group</replaceable>,
+      <replaceable>X-$DISPLAY-value</replaceable>) or
+      (<replaceable>user/group</replaceable>,
+      <replaceable>pam-service-name/</replaceable>)
+      combination.  The permissions field of that table entry
+      determines
       whether the login will be accepted or refused.
    </para>
 
@@ -65,14 +76,27 @@
     <para>
       The third field, the <replaceable>origins</replaceable>
       field, should be a list of one or more tty names (for non-networked
-      logins), host names, domain names (begin with "."), host addresses,
+      logins), X <varname>$DISPLAY</varname> values or PAM service
+      names (for non-networked logins without a tty), host names,
+      domain names (begin with "."), host addresses,
       internet network numbers (end with "."), internet network addresses
       with network mask (where network mask can be a decimal number or an
       internet address also), <emphasis>ALL</emphasis> (which always
matches)
-      or <emphasis>LOCAL</emphasis>. <emphasis>LOCAL</emphasis>
-      keyword matches if and only if the <emphasis>PAM_RHOST</emphasis> is
-      not set and &lt;origin&gt; field is thus set from
-      <emphasis>PAM_TTY</emphasis> or
<emphasis>PAM_SERVICE</emphasis>".
+      or <emphasis>LOCAL</emphasis>. The
<emphasis>LOCAL</emphasis>
+      keyword matches if and only if
+     
<citerefentry><refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      when called with an <parameter>item_type</parameter> of
+      <emphasis>PAM_RHOST</emphasis>, returns <code>NULL</code>
or an
+      empty string (and therefore the
+      <replaceable>origins</replaceable> field is compared against the
+      return value of
+     
<citerefentry><refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+      called with an <parameter>item_type</parameter> of
+      <emphasis>PAM_TTY</emphasis> or, absent that,
+      <emphasis>PAM_SERVICE</emphasis>).
+    </para>
+
+    <para>
       If supported by the system you can use
       <emphasis>@netgroupname</emphasis> in host or user patterns. The
       <emphasis>@@netgroupname</emphasis> syntax is supported in the user
diff --git a/modules/pam_access/pam_access.8.xml b/modules/pam_access/pam_access.8.xml
index 710e2e7..c629a9f 100644
--- a/modules/pam_access/pam_access.8.xml
+++ b/modules/pam_access/pam_access.8.xml
@@ -50,7 +50,8 @@
       The pam_access PAM module is mainly for access management.
       It provides logdaemon style login access control based on login
       names, host or domain names, internet addresses or network numbers,
-      or on terminal line names in case of non-networked logins.
+      or on terminal line names, X <varname>$DISPLAY</varname> values,
+      or PAM service names in case of non-networked logins.
     </para>
     <para>
       By default rules for access management are taken from config file
@@ -59,7 +60,7 @@
     </para>
     <para>
       If Linux PAM is compiled with audit support the module will report
-      when it denies access based on origin (host or tty).
+      when it denies access based on origin (host, tty, etc.).
     </para>
   </refsect1>