saslauthd/saslauthd.mdoc

   1 .\" $Id: saslauthd.mdoc,v 1.18 2004/03/25 18:24:26 rjs3 Exp $
   2 .\" Copyright 1997-2001 Messaging Direct Ltd. All rights reserved.
   3 .\"
   4 .\" This manpage uses the BSD mdoc manpage macros. Please don't
   5 .\" downgrade it to -man. The -mdoc macros are included with
   6 .\" GNU roff, and, of course, with the BSD distributions.
   7 .\"
   8 .\" To make life easier for sites that don't support -mdoc,
   9 .\" please generate (and commit!) an updated pre-formatted
  10 .\" manpage in saslauthd.8 whenever you change this source
  11 .\" version. Only the pre-formatted manpage is installed.
  12 .\"
  13 .Dd 10 24 2002
  14 .Dt SASLAUTHD 8
  15 .Os "CMU-SASL"
  16 .Sh NAME
  17 .Nm saslauthd
  18 .Nd sasl authentication server
  19 .Sh SYNOPSIS
  20 .Nm
  21 .Fl a
  22 .Ar authmech
  23 .Op Fl \&Tvdchlr
  24 .Op Fl O Ar option
  25 .Op Fl m Ar mux_path
  26 .Op Fl n Ar threads
  27 .Op Fl s Ar size
  28 .Op Fl t Ar timeout
  29 .Sh DESCRIPTION
  30 .Nm
  31 is a daemon process that handles plaintext authentication requests
  32 on behalf of the SASL library.
  33 .Pp
  34 The server fulfills two roles: it isolates all code requiring superuser
  35 privileges into a single process, and it can be used to provide
  36 .Em proxy
  37 authentication services to clients that do not understand
  38 SASL based authentication.
  39 .Pp
  40 .Nm
  41 should be
  42 started from the system boot scripts when going to
  43 multi-user mode. When running against a protected authentication
  44 database (e.g. the
  45 .Li shadow
  46 mechanism),
  47 it must be run as the superuser.
  48 .Ss Options
  49 Options named by lower\-case letters configure the server itself.
  50 Upper\-case options control the behavior of specific authentication
  51 mechanisms; their applicability to a particular authentication
  52 mechanism is described in the
  53 .Sx AUTHENTICATION MECHANISMS
  54 section.
  55 .Bl -tag -width indent
  56 .It Fl a Ar authmech
  57 Use
  58 .Ar authmech
  59 as the authentication mechanism. (See the
  60 .Sx AUTHENTICATION MECHANISMS
  61 section below.) This parameter is mandatory.
  62 .It Fl O Ar option
  63 A mechanism specific option (e.g. rimap hostname or config file path)
  64 .It Fl H Ar hostname
  65 The remote host to be contacted by the
  66 .Li rimap
  67 authentication mechanism. (Depricated, use -O instead)
  68 .It Fl m Ar path
  69 Use
  70 .Ar path
  71 as the pathname to the named socket to listen on for
  72 connection requests. This must be an absolute pathname, and MUST NOT
  73 include the trailing "/mux".  Note that the default for this value
  74 is "/var/state/saslauthd" (or what was specified at compile time)
  75 and that this directory must exist for saslauthd to function.
  76 .It Fl n Ar threads
  77 Use
  78 .Ar threads
  79 processes for responding to authentication queries. (default: 5)  A
  80 value of zero will indicate that saslauthd should fork an individual
  81 process for each connection.  This can solve leaks that occur in some
  82 deployments..
  83 .It Fl s Ar size
  84 Use
  85 .Ar size
  86 as the table size of the hash table (in kilobytes)
  87 .It Fl t Ar timeout
  88 Use
  89 .Ar timeout
  90 as the expiration time of the authentication cache (in seconds)
  91 .It Fl T
  92 Honour time-of-day login restrictions.
  93 .It Fl h
  94 Show usage information
  95 .It Fl c
  96 Enable cacheing of authentication credentials
  97 .It Fl l
  98 Disable the use of a lock file for controlling access to accept().
  99 .It Fl r
 100 Combine the realm with the login (with an '@' sign in between).  e.g.
 101 login: "foo" realm: "bar" will get passed as login: "foo@bar".  Note that
 102 the realm will still be passed, which may lead to unexpected behavior.
 103 .It Fl v
 104 Print the version number and available authentication
 105 mechanisms on standard error, then exit.
 106 .It Fl d
 107 Debugging mode.
 108 .El
 109 .Ss Logging
 110 .Nm
 111 logs it's activities via
 112 .Nm syslogd
 113 using the
 114 .Dv LOG_AUTH
 115 facility.
 116 .Sh AUTHENTICATION MECHANISMS
 117 .Nm
 118 supports one or more
 119 .Qq authentication mechanisms ,
 120 dependent upon the facilities provided by the underlying operating system.
 121 The mechanism is selected by the
 122 .Fl aho
 123 flag from the following list of choices:
 124 .Bl -tag -width "kerberos4"
 125 .It Li dce
 126 .Em (AIX)
 127 .Pp
 128 Authenticate using the DCE authentication environment.
 129 .It Li getpwent
 130 .Em (All platforms)
 131 .Pp
 132 Authenticate using the
 133 .Fn getpwent
 134 library function. Typically this authenticates against the
 135 local password file. See your systems
 136 .Xr getpwent 3
 137 man page for details.
 138 .It Li kerberos4
 139 .Em (All platforms)
 140 .Pp
 141 Authenticate against the local Kerberos 4 realm. (See the
 142 .Sx NOTES
 143 section for caveats about this driver.)
 144 .It Li kerberos5
 145 .Em (All platforms)
 146 .Pp
 147 Authenticate against the local Kerberos 5 realm.
 148 .It Li pam
 149 .Em (Linux, Solaris)
 150 .Pp
 151 Authenticate using Pluggable Authentication Modules (PAM).
 152 .It Li rimap
 153 .Em (All platforms)
 154 .Pp
 155 Forward authentication requests to a remote IMAP server. This driver
 156 connects to a remote IMAP server, specified using the -O flag,
 157 and attempts to login (via an IMAP
 158 .Ql LOGIN
 159 command) using the credentials
 160 supplied to the local
 161 server. If the remote authentication succeeds the local connection
 162 is also considered to be authenticated. The remote connection is closed
 163 as soon as the tagged response from the
 164 .Ql LOGIN
 165 command is received from the remote
 166 server.
 167 .Pp
 168 The
 169 .Ar option
 170 parameter to the
 171 .Fl O
 172 flag describes the remote server to forward
 173 authentication requests to.
 174 .Ar hostname
 175 can be a hostname (imap.example.com) or a dotted\-quad IP address
 176 (192.168.0.1). The latter is useful if the remote server is
 177 multi\-homed and has network interfaces that are unreachable from
 178 the local IMAP server. The remote host is contacted on the
 179 .Ql imap
 180 service port. A non\-default port can be specified by appending
 181 a slash and the port name or number
 182 to the
 183 .Ar hostname
 184 argument.
 185 .Pp
 186 The
 187 .Fl O
 188 flag and argument are mandatory when using the
 189 .Li rimap
 190 mechanism.
 191 .It Li shadow
 192 .Em (AIX, Irix, Linux, Solaris)
 193 .Pp
 194 Authenticate against the local
 195 .Qq shadow password file .
 196 The exact mechanism is system dependent.
 197 .Nm
 198 currently understands the
 199 .Fn getspnam
 200 and
 201 .Fn getuserpw
 202 library routines. Some systems
 203 honour the
 204 .Fl T
 205 flag.
 206 .It Li sasldb
 207 .Em (All platforms)
 208 .Pp
 209 Authenticate against the
 210 SASL authentication database.  Note that this is probabally not what you
 211 want to be using, and is even disabled at compile-time by default.
 212 If you want to use sasldb with the SASL library, you probably want to
 213 use the pwcheck_method of "auxprop" along with the sasldb auxprop plugin
 214 instead.
 215 .It Li ldap
 216 .Em (All platforms that support OpenLDAP 2.0 or higher)
 217 .Pp
 218 Authenticate against an ldap server.  The ldap configuration parameters are
 219 read from /usr/local/etc/saslauthd.conf.  The location of this file can be
 220 changed with the -O parameter. See the LDAP_SASLAUTHD file included with the
 221 distribution for the list of available parameters.
 222 .It Li sia
 223 .Em (Digital UNIX)
 224 .Pp
 225 Authenticate using the Digital
 226 .Ux
 227 Security Integration Architecture
 228 (a.k.a.
 229 .Qq enhanced security ) .
 230 .El
 231 .Sh NOTES
 232 The
 233 .Li kerberos4
 234 authentication driver consumes considerable resources. To perform an
 235 authentication it must obtain a ticket granting ticket
 236 from the TGT server
 237 .Sy on every authentication request.
 238 The Kerberos library routines that obtain the TGT also create a
 239 local ticket file, on the reasonable assumption that you will want
 240 to save the TGT for use by other Kerberos applications. These ticket
 241 files are unusable by
 242 .Nm No ,
 243 however there is no way not to create them. The overhead of creating
 244 and removing
 245 these ticket files can cause serious performance degradation on busy
 246 servers. (Kerberos
 247 was never intended to be used in this manner, anyway.)
 248 .Sh FILES
 249 .Bl -tag -width "/var/run/saslauthd/mux"
 250 .It Pa /var/run/saslauthd/mux
 251 The default communications socket.
 252 .It Pa /usr/local/etc/saslauthd.conf
 253 The default configuration file for ldap support.
 254 .El
 255 .Sh SEE ALSO
 256 .Xr passwd 1 ,
 257 .Xr getpwent 3 ,
 258 .Xr getspnam 3 ,
 259 .Xr getuserpw 3 ,
 260 .Xr sasl_checkpass 3
 261 .Xr sia_authenticate_user 3 ,