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