contrib/amd/hlfsd/hlfsd.8

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