contrib/amd/hlfsd/hlfsd.8

   1 .\"
   2 .\" Copyright (c) 1997-1999 Erez Zadok
   3 .\" Copyright (c) 1989 Jan-Simon Pendry
   4 .\" Copyright (c) 1989 Imperial College of Science, Technology & Medicine
   5 .\" Copyright (c) 1989 The Regents of the University of California.
   6 .\" All rights reserved.
   7 .\"
   8 .\" This code is derived from software contributed to Berkeley by
   9 .\" Jan-Simon Pendry at Imperial College, London.
  10 .\"
  11 .\" Redistribution and use in source and binary forms, with or without
  12 .\" modification, are permitted provided that the following conditions
  13 .\" are met:
  14 .\" 1. Redistributions of source code must retain the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer.
  16 .\" 2. Redistributions in binary form must reproduce the above copyright
  17 .\"    notice, this list of conditions and the following disclaimer in the
  18 .\"    documentation and/or other materials provided with the distribution.
  19 .\" 3. All advertising materials mentioning features or use of this software
  20 .\"    must display the following acknowledgment:
  21 .\"      This product includes software developed by the University of
  22 .\"      California, Berkeley and its contributors.
  23 .\" 4. Neither the name of the University nor the names of its contributors
  24 .\"    may be used to endorse or promote products derived from this software
  25 .\"    without specific prior written permission.
  26 .\"
  27 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  28 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  29 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  30 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  31 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  32 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  33 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  34 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  35 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  36 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  37 .\" SUCH DAMAGE.
  38 .\"
  39 .\" $Id: hlfsd.8,v 1.2 1999/01/10 21:54:32 ezk Exp $
  40 .\" $FreeBSD: src/contrib/amd/hlfsd/hlfsd.8,v 1.5.2.5 2001/08/16 10:53:40 ru Exp $
  41 .\" $DragonFly: src/contrib/amd/hlfsd/hlfsd.8,v 1.2 2003/06/17 04:23:57 dillon Exp $
  42 .\"
  43 .\" HLFSD was written at Columbia University Computer Science Department, by
  44 .\" Erez Zadok <ezk@cs.columbia.edu> and Alexander Dupuy <dupuy@smarts.com>
  45 .\" It is distributed under the same terms and conditions as AMD.
  46 .\"
  47 .Dd September 14, 1993
  48 .Dt HLFSD 8
  49 .Os
  50 .Sh NAME
  51 .Nm hlfsd
  52 .Nd home-link file system daemon
  53 .Sh SYNOPSIS
  54 .Nm
  55 .Op Fl fhnpvC
  56 .Op Fl a Ar alt_dir
  57 .Bk -words
  58 .Op Fl c Ar cache-interval
  59 .Ek
  60 .Op Fl g Ar group
  61 .Bk -words
  62 .Op Fl i Ar reload-interval
  63 .Ek
  64 .Op Fl l Ar logfile
  65 .Bk -words
  66 .Op Fl o Ar mount-options
  67 .Op Fl x Ar log-options
  68 .Op Fl D Ar debug-options
  69 .Op Fl P Ar password-file
  70 .Ek
  71 .Op linkname Op subdir
  72 .Sh DESCRIPTION
  73 .Nm
  74 is a daemon which implements a filesystem containing a symbolic link to
  75 subdirectory within a user's home directory, depending on the user
  76 which accessed that link.  It was primarily designed to redirect
  77 incoming mail to users' home directories, so that it can read from
  78 anywhere.
  79 .Pp
  80 .Nm
  81 operates by mounting itself as an
  82 .Tn NFS
  83 server for the directory containing
  84 .Ar linkname ,
  85 which defaults to
  86 .Pa /hlfs/home .
  87 Lookups within that directory are handled by
  88 .Nm hlfsd ,
  89 which uses the password map to determine how to resolve the lookup.  The
  90 directory will be created if it doesn't already exist.  The symbolic link will
  91 be to the accessing user's home directory, with
  92 .Ar subdir
  93 appended to it.  If not specified,
  94 .Ar subdir
  95 defaults to
  96 .Pa .hlfsdir .
  97 This directory will also be created if it does not already exist.
  98 .Pp
  99 A
 100 .Er SIGHUP
 101 will flush the internal caches, and reload the password map.  It will also
 102 close and reopen the log file, to enable the original log file to be removed
 103 or rotated.  A
 104 .Er SIGUSR1
 105 will cause it to dump its internal table of user IDs and home directories to
 106 the file
 107 .Pa /usr/tmp/hlfsd.dump.XXXXXX .
 108 .Sh OPTIONS
 109 .Bl -tag -width Ds
 110 .It Fl a Ar alt_dir
 111 Alternate directory.  The name of the directory to which
 112 the symbolic link returned by
 113 .Nm
 114 will point, if it cannot access the home directory of the user.  This
 115 defaults to
 116 .Pa /var/hlfs .
 117 This directory will be created  if it doesn't exist.  It is expected
 118 that either users will read these files, or the system administrators
 119 will run a script to resend this
 120 .Dq lost mail
 121 to its owner.
 122 .It Fl c Ar cache-interval
 123 Caching interval.
 124 .Nm
 125 will cache the validity of home directories for this interval, in
 126 seconds.  Entries which have been verified within the last
 127 .Ar cache-interval
 128 seconds will not be verified again, since the operation could
 129 be expensive, and the entries are most likely still valid.
 130 After the interval has expired,
 131 .Nm
 132 will re-verify the validity of the user's home directory, and
 133 reset the cache time-counter.  The default value for
 134 .Ar cache-interval
 135 is 300 seconds
 136 (5 minutes).
 137 .It Fl f
 138 Force fast startup.  This option tells
 139 .Nm
 140 to skip startup-time consistency checks such as existence of mount
 141 directory, alternate spool directory, symlink to be hidden under the
 142 mount directory, their permissions and validity.
 143 .It Fl g Ar group
 144 Set the special group
 145 .Va HLFS_GID
 146 to
 147 .Ar group .
 148 Programs such as
 149 .Ic comsat ,
 150 (which access the mailboxes of other users)
 151 must be setgid
 152 .Va HLFS_GID
 153 to work properly.  The default group is
 154 .Dq hlfs .
 155 If no group is provided, and there is no group
 156 .Dq hlfs ,
 157 this feature is disabled.
 158 .It Fl h
 159 Help.  Print a brief help message, and exit.
 160 .It Fl i Ar reload-interval
 161 Map-reloading interval.  Each
 162 .Ar reload-interval
 163 seconds,
 164 .Nm
 165 will reload the password map.
 166 .Nm
 167 needs the password map for the UIDs and home directory pathnames.
 168 .Nm
 169 schedules a
 170 .Va SIGALRM
 171 to reload the password maps.  A
 172 .Va SIGHUP
 173 sent to
 174 .Nm
 175 will force it to reload the maps immediately.   The default value for
 176 .Ar reload-interval
 177 is 900 seconds
 178 (15 minutes).
 179 .It Fl l Ar logfile
 180 Specify a log file to which
 181 .Nm
 182 will record events.  If
 183 .Pa logfile
 184 is the string
 185 .Pa syslog
 186 then the log messages will be sent to the system log daemon by
 187 .Xr syslog 3 ,
 188 using the
 189 .Va LOG_DAEMON
 190 facility.  This is also the default.
 191 .It Fl n
 192 No verify.
 193 .Nm
 194 will not verify the validity of the symbolic link it will be
 195 returning, or that the user's home directory contains
 196 sufficient disk-space for spooling.  This can speed up
 197 .Nm
 198 at the cost of possibly returning symbolic links to home
 199 directories which are not currently accessible or are full.
 200 By default,
 201 .Nm
 202 validates the symbolic-link in the background.
 203 The
 204 .Fl n
 205 option overrides the meaning of the
 206 .Fl c
 207 option, since no caching is necessary.
 208 .It Fl o Ar mount-options
 209 Mount options.  Mount options which
 210 .Nm
 211 will use to mount itself on top of
 212 .Pa dirname .
 213 By default,
 214 .Ar mount-options
 215 is set to
 216 .Qq ro .
 217 If the system supports symbolic-link caching, default
 218 options are set to
 219 .Qq ro,nocache .
 220 .It Fl p
 221 Prints
 222 .Va PID .
 223 Outputs the process-id of
 224 .Nm
 225 to standard output where it can be saved into a file.
 226 .It Fl v
 227 Version.  Displays version information to standard error.
 228 .It Fl x Ar log-options
 229 Specify run-time logging options.  The options are a comma separated
 230 list chosen from: fatal, error, user, warn, info, map, stats, all.
 231 .It Fl C
 232 Force
 233 .Nm
 234 to run on systems that cannot turn off the NFS attribute-cache.  Use of
 235 this option on those systems is discouraged, as it may result in loss
 236 or misdelivery of mail.  The option is ignored on systems that can turn
 237 off the attribute-cache.
 238 .It Fl D Ar log-options
 239 Select from a variety of debugging options.  Prefixing an
 240 option with the string
 241 .Qq no
 242 reverses the effect of that option.  Options are cumulative.
 243 The most useful option is
 244 .Em all .
 245 Since this option is only used for debugging other options are not
 246 documented here.  A fuller description is available in the program
 247 source.  A
 248 .Va SIGUSR1
 249 sent to
 250 .Nm
 251 will cause it to dump its internal password map to the file
 252 .Pa /usr/tmp/hlfsd.dump.XXXXXX .
 253 .It Fl P Ar password-file
 254 Read the user-name, user-id, and home directory information from the file
 255 .Ar password-file .
 256 Normally,
 257 .Nm
 258 will use
 259 .Xr getpwent 3
 260 to read the password database.  This option allows you to override the
 261 default database, and is useful if you want to map users' mail files to a
 262 directory other than their home directory.  Only the username, uid, and
 263 home-directory fields of the file
 264 .Ar password-file
 265 are read and checked.  All other fields are ignored.  The file
 266 .Ar password-file
 267 must be compliant with
 268 .Ux
 269 System 7 colon-delimited format
 270 .Xr passwd 5 .
 271 .El
 272 .Sh FILES
 273 .Bl -tag -width /axx
 274 .It Pa /hlfs
 275 directory under which
 276 .Nm
 277 mounts itself and manages the symbolic link
 278 .Pa home .
 279 .It Pa .hlfsdir
 280 default sub-directory in the user's home directory, to which the
 281 .Pa home
 282 symbolic link returned by
 283 .Nm
 284 points.
 285 .It Pa /var/hlfs
 286 directory to which
 287 .Pa home
 288 symbolic link returned by
 289 .Nm
 290 points if it is unable to verify the that
 291 user's home directory is accessible.
 292 .El
 293 .Sh SEE ALSO
 294 .Xr mail 1 ,
 295 .Xr getgrent 3 ,
 296 .Xr getpwent 3 ,
 297 .Xr mtab 5 ,
 298 .Xr passwd 5 ,
 299 .Xr amd 8 ,
 300 .Xr cron 8 ,
 301 .Xr mount 8 ,
 302 .Xr sendmail 8 ,
 303 .Xr umount 8
 304 .Rs
 305 .%T HLFSD:  Delivering Email to Your $HOME
 306 .%B Proc. LISA-VII, The 7th Usenix System Administration Conference
 307 .%D November 1993
 308 .Re
 309 .Sh AUTHORS
 310 .An Erez Zadok Aq ezk@cs.columbia.edu ,
 311 Department of Computer Science, Columbia University,
 312 New York, USA.
 313 .Pp
 314 .An Alexander Dupuy Aq dupuy@smarts.com ,
 315 System Management ARTS, White Plains, New York, USA.
 316 .Sh HISTORY
 317 The
 318 .Nm
 319 utility appeared in
 320 .Fx 3.0 .