<!--
   $Id: pam_rhosts.sgml,v 1.1.1.2 2002/09/15 20:08:32 hartmans Exp $
   
   This file was written by Andrew G. Morgan <morgan@kernel.org>
-->

<sect1>The rhosts module

<sect2>Synopsis

<p>
<descrip>

<tag><bf>Module Name:</bf></tag>
<tt/pam_rhosts_auth/

<tag><bf>Author:</bf></tag>
Al Longyear &lt;longyear@netcom.com&gt;

<tag><bf>Maintainer:</bf></tag>

<tag><bf>Management groups provided:</bf></tag>
authentication

<tag><bf>Cryptographically sensitive:</bf></tag>
	
<tag><bf>Security rating:</bf></tag>

<tag><bf>Clean code base:</bf></tag>
Clean.

<tag><bf>System dependencies:</bf></tag>

<tag><bf>Network aware:</bf></tag>
Standard <tt/inet_addr()/, <tt/gethostbyname()/ function calls.

</descrip>

<sect2>Overview of module

<p>
This module performs the standard network authentication for services,
as used by traditional implementations of <em/rlogin/ and <em/rsh/
etc.

<sect2>Authentication component

<p>
<descrip>

<tag><bf>Recognized arguments:</bf></tag>
<tt/no_hosts_equiv/; <tt/no_rhosts/; <tt/debug/; <tt/no_warn/;
<tt/privategroup/; <tt/promiscuous/; <tt/suppress/

<tag><bf>Description:</bf></tag>

The authentication mechanism of this module is based on the contents
of two files; <tt>/etc/hosts.equiv</tt> (or <tt/_PATH_HEQUIV/ in
<tt>#include &lt;netdb.h&gt;</tt>) and <tt>~/.rhosts</tt>.  Firstly,
hosts listed in the former file are treated as equivalent to the
localhost. Secondly, entries in the user's own copy of the latter file
is used to map "<tt/remote-host remote-user/" pairs to that user's
account on the current host. Access is granted to the user if their
host is present in <tt>/etc/hosts.equiv</tt> and their remote account
is identical to their local one, or if their remote account has an
entry in their personal configuration file.

<p>
Some restrictions are applied to the attributes of the user's personal
configuration file: it must be a regular file (as defined by
<tt/S_ISREG(x)/ of POSIX.1); it must be owned by the <em/superuser/ or
the user; it must not be writable by any user besides its owner.

<p>
The module authenticates a remote user (internally specified by the
item <tt/PAM_RUSER/) connecting from the remote host (internally
specified by the item <tt/PAM_RHOST/).  Accordingly, for applications
to be compatible this authentication module they must set these items
prior to calling <tt/pam_authenticate()/.  The module is not capable
of independently probing the network connection for such information.

<p>
In the case of <tt/root/-access, the <tt>/etc/host.equiv</tt> file is
<em/ignored/ unless the <tt>hosts_equiv_rootok</tt> option
should be used.  Instead, the superuser must have a correctly configured
personal configuration file.

<p>
The behavior of the module is modified by flags:
<itemize>
<item>
<tt/debug/ -
log more information to <tt/syslog(3)/. (XXX - actually, this module
does not do any logging currently, please volunteer to fix this!)

<item>
<tt/no_warn/ -
do not give verbal warnings to the user about failures etc. (XXX -
this module currently does not issue any warnings, please volunteer to
fix this!)

<item>
<tt/no_hosts_equiv/ -
ignore the contents of the <tt>/etc/hosts.equiv</tt> file.

<item>
<tt/hosts_equiv_rootok/ -
allow the use of <tt>/etc/hosts.equiv</tt> for superuser.  Without this
option <tt>/etc/hosts.equiv</tt> is not consulted for the superuser account.
This option has no effect if the <tt>no_hosts_equiv</tt> option is used.

<item>
<tt/no_rhosts/ -
ignore the contents of all user's personal configuration file
<tt>~/.rhosts</tt>.

<item>
<tt/privategroup/ -
normally, the <tt>~/.rhosts</tt> file must not be writable by anyone
other than its owner.  This option overlooks group write access in the
case that the group owner of this file has the same name as the
user being authenticated.  To lessen the security problems associated
with this option, the module also checks that the user is the only
member of their private group.

<item>
<tt/promiscuous/ -
A host entry of `+' will lead to all hosts being granted
access. Without this option, '+' entries will be ignored. Note, that
the <tt/debug/ option will syslog a warning in this latter case.

<item>
<tt/suppress/ -
This will prevent the module from <tt/syslog(3)/ing a warning message
when this authentication fails.  This option is mostly for keeping
logs free of meaningless errors, in particular when the module is used
with the <tt/sufficient/ control flag.

</itemize>
<tag><bf>Examples/suggested usage:</bf></tag>

To allow users to login from trusted remote machines, you should try
adding the following line to your <tt>/etc/pam.conf</tt> file
<em/before/ the line that would otherwise prompt the user for a
password:
<tscreen>
<verb>
#
# No passwords required for users from hosts listed above.
#
login  auth  sufficient  pam_rhosts_auth.so no_rhosts
</verb>
</tscreen>
Note, in this example, the system administrator has turned off all
<em/personal/ <em/rhosts/ configuration files. Also note, that this module
can be used to <em/only/ allow remote login from hosts specified in
the <tt>/etc/host.equiv</tt> file, by replacing <tt/sufficient/ in the
above example with <tt/required/.

</descrip>

<!--
End of sgml insert for this module.
-->
