sync-accounts/sync-accounts.5

   1 .\" Hey, Emacs!  This is an -*- nroff -*- source file.
   2 .TH SYNC\-ACCOUNTS 5 "15th July 2002" "Greenend" "chiark utilities"
   3 .SH NAME
   4 /etc/sync\-accounts \- configuration file for sync\-accounts
   5 .SH DESCRIPTION
   6 .B /etc/sync\-accounts
   7 contains the default configuration of the
   8 .BR sync-accounts (8)
   9 account synchronisation tool.
  10
  11 The configuration file specifies how to access and update the local
  12 password and group databases, where sync-accounts should log.
  13
  14 It also specifies the list of (remote) sources for account
  15 information, and which accounts and details should be copied from each
  16 source to the local system.
  17 .SH OVERALL SYNTAX AND SEMANTICS
  18 The configuration file is parsed as a series of lines.  First, leading
  19 and trailing whitespace on each line is removed, and then empty lines,
  20 or lines starting with
  21 .BR # ,
  22 are removed.
  23
  24 Each line is parsed as a directive.  The order of directives is
  25 significant; some directives set up information which later
  26 directives rely on.
  27
  28 The configuration file must contain an
  29 .B end
  30 directive; anything after that point is ignored.
  31 .SH GLOBAL DIRECTIVES
  32 These directives may appear only at the start of the file (before any
  33 other directives), and each directive must appear only once;
  34 otherwise, sync-accounts my behave oddly.
  35 .TP
  36 .BR lockpasswd | lockgroup " \fImethod\fP [\fIdetails \fP...]"
  37 Specifies how the passwd and group files should be read and/or locked.
  38 See
  39 .B LOCKING METHOD DIRECTIVES
  40 below.
  41 .TP
  42 .BI "logfile " filename
  43 Append log messages to
  44 .I filename
  45 instead of stdout.
  46 Errors still go to stderr.
  47 .TP
  48 .BR localformat " " bsd | std
  49 Specifies the local password file is in the relevant format:
  50 .B std
  51 is the standard V7 password file (with a SysV-style
  52 /etc/shadow if /etc/shadow exists).
  53 .B bsd
  54 is the BSD4.4 master.passwd format, and should be used only with
  55 .BR "lockpasswd runvia vipw" .
  56 The default is
  57 .BR std .
  58 .SH LOCKING METHOD DIRECTIVES
  59 One
  60 .B lockgroup
  61 and one
  62 .B lockpasswd
  63 directive must be present, in the global directives at the start of
  64 the config file.
  65
  66 The choice of the appropriate directives can be difficult without
  67 special knowledge of the local system.  In general, it is best to use
  68 .B lockpasswd runvia vipw
  69 where this is available, as if this works avoids having to know the
  70 names of the lockfiles.
  71
  72 GNU systems (including GNU/Linux and Debian GNU/BSD) typically lock
  73 the group file separately and supply
  74 .BR vigr ,
  75 in which case you should use
  76 .BR "lockgroup vigr" .
  77
  78 Most systems other than GNU do not lock the group file at all (or
  79 assume that all programs which modify the group file will lock the
  80 passwd file), in which case
  81 .B lockgroup none
  82 is appropriate.
  83
  84 If vigr or vipw is not available or is known to be broken (eg, because
  85 it does not lock properly), then use
  86 .BR link .
  87 .TP
  88 .BR lockpasswd | lockgroup " " runvia " \fIprogram\fP
  89 sync-accounts will reinvoke itself using
  90 .IR program ,
  91 which must behave like
  92 .B vipw
  93 or
  94 .BR vigr .
  95 sync-accounts will set the
  96 .B EDITOR
  97 environment variable to the path it was invoked with (Perl's
  98 .BR $0 )
  99 and put some information for its own use into
 100 .B SYNC_ACCOUNTS_*
 101 environment variables (which will also allow sync-accounts to tell
 102 that it has already been reinvoked via
 103 .I program
 104 and should not do so again).
 105
 106 If both
 107 .BI "lockpasswd runvia " vipw
 108 and
 109 .BI "lockgroup runvia " vigr
 110 are specified, then it must be possible and safe for the EDITOR
 111 run by
 112 .I vipw
 113 to invoke
 114 .IR vigr ,
 115 as this is what sync-accounts will do.
 116 .TP
 117 .BR lockpasswd | lockgroup " " link " \fIsuffix\fP|\fIfilename\fP
 118 sync-accounts will attempt to lock the passwd or group file by making
 119 a hardlink from the real file to the specified filename.
 120 If
 121 .IR suffix | filename
 122 starts with a
 123 .B /
 124 it is interpreted as a filename; otherwise it is interpreted as
 125 a suffix, to be appended to the real database filename.
 126 .TP
 127 .BR lockpasswd | lockgroup " " none
 128 sync-accounts will not attempt to lock the passwd or group files at
 129 all.
 130
 131 .B lockgroup none
 132 is appropriate on systems where there is no separate locking for the
 133 group file (either because there is no proper support for automatic
 134 editing of the group file, or because you're expected to lock the
 135 password file), although in the absence of
 136 .B vigr
 137 it's inevitable that simultaneous changes to the group file made by
 138 both the human sysadmin and by sync-accounts will cause problems.
 139
 140 .B lockpasswd none
 141 is very dangerous and should not normally be used.  It will cause data
 142 loss if any other tool for changing password data is used - eg,
 143 .BR passwd (1).
 144 .SH PER-SOURCE DIRECTIVES
 145 Within each source's section, all of the per-source directives must
 146 appear before any account-selection directives; otherwise
 147 sync-accounts may behave oddly.  If a per-source directive is
 148 repeated, the last setting takes effect.
 149 .TP
 150 .BI "host " source
 151 Starts a source's section.  Usually each source will correspond
 152 exactly to one host which is acting as a source of account data.
 153 The
 154 .B host
 155 directive resets the per-source parameters to the defaults.
 156 .I source
 157 need not be the source host's official name in any sense and is used
 158 only for identification.  Any
 159 .I source
 160 must be named in only one
 161 .B host
 162 directive, or sync-accounts may behave oddly.
 163 .TP
 164 .BR getpasswd | getgroup | getshadow " \fIcommand\fP..."
 165 sync-accounts always fetches account data from sources by running specified
 166 commands on the local host; it does not contain any network protocols,
 167 itself.
 168
 169 .I command
 170 is fed to
 171 .BR "sh -c"
 172 and might typically contain something like
 173 .br
 174 .B "    ssh syncacct@remote.host cat /etc/passwd"
 175 .br
 176 where the user syncacct on remote.host is in group shadow, or
 177 .br
 178 .B "    cat /var/local/sync-accounts/remote.host/passwd"
 179 where the file named is copied across using cron.
 180
 181 .B getpasswd
 182 must be specified if user data is to be transferred;
 183 .B getgroup
 184 must be specified if group data is to be transferred.
 185
 186 .B getshadow
 187 should be specified iff getpasswd is specified but the data from
 188 getpasswd does not contain actual password information, and should
 189 emit data in Sys-V shadow password format.
 190 .TP
 191 .BR remoteformat " " std | bsd
 192 Specifies the format of the output of getpasswd.
 193 .B std
 194 is standard V7 passwd file format (optionally augmented by the use of
 195 a shadow file fetched with getshadow).
 196 .B bsd
 197 is the BSD4.4 master.passwd format (and getshadow should not normally
 198 be used with
 199 .BR "remoteformat bsd" ).
 200 The default is
 201 .BR std .
 202 .SH SYNCHRONISATION SETTINGS
 203 The following directives affect the way that account data is copied.
 204 They may be freely mixed with other directives, and repeated.  The
 205 setting in effect is the one set by the last relevant settings
 206 directive before any particular account-selection directive.
 207 .TP
 208 .BR uidmin | uidmax " \fivalue\fP"
 209 When an account is to be created locally, a uid/gid will be chosen
 210 which is one higher than the highest currently in use, except that ids
 211 below uidmin or above uidmax are ignored and will never be used.
 212 There is no default.
 213 .TP
 214 .BI "homebase " homebase
 215 When an account is to be created locally, its home directory will be
 216 .IB homebase / username
 217 where
 218 .I username
 219 is the name of the account.  The default is
 220 .BR /home .
 221 .TP
 222 .RB [ no ] sameuid
 223 Specifies whether uids are supposed to match.  With
 224 .BR sameuid ,
 225 it is an error for the uid or gid of a synchronised local account not
 226 to match the corresponding remote account, and new local accounts will
 227 get the remote accounts' ids.
 228 The default is
 229 .BR nosameuid .
 230 .TP
 231 .BR usergroups " | " nousergroups " | " defaultgid " \fIgid\fP"
 232 Specifies whether local accounts are supposed to have
 233 corresponding groups, or all be part of a particular group.  The
 234 default is
 235 .BR usergroups .
 236
 237 With
 238 .BR usergroups ,
 239 when a new account is created, the
 240 corresponding per-user group will be created as well, and
 241 per-user groups are created for existing accounts if necessary
 242 (if account creation is enabled).  If the gid or group name for
 243 a per-user group is already taken for a different group name or
 244 gid this will be logged, and processing of that account will be
 245 inhibited, but it is not a fatal error.
 246
 247 With
 248 .BR defaultgid ,
 249 newly-created accounts will be made a part of that group,
 250 and the groups of existing accounts will be left alone.
 251
 252 With
 253 .BR nousergroups ,
 254 no new accounts can be created, and existing accounts' groups will be
 255 left alone.
 256 .TP
 257 .BR createuser " [\fIcommand\fP] | " nocreateuser
 258 Specifies whether accounts found on the remote host should be created
 259 if necessary, and what command to run to do the the rest of the
 260 account setup (eg, creation of home directory, etc.).  The default is
 261 .BR nocreateuser .
 262
 263 If
 264 .B createuser
 265 is specified without a command then
 266 .B sync-accounts-createuser
 267 is used; the supplied sync-accounts-createuser program is a reasonable
 268 minimal implementation.
 269
 270 With
 271 .BR createuser ,
 272 either sameuid, or both uidmin and uidmax, must be specified, if
 273 accounts are actually to be created.
 274
 275 The command is passed to
 276 .BR "sh -c" .
 277 See
 278 .BR sync-accounts-createuser (8)
 279 for details of
 280 .IR command 's
 281 environment and functionality.
 282 .TP
 283 .BR group | nogroup " \fIglob-pattern\fP"
 284 .B group
 285 specifies that the membership of the local groups specified should be
 286 adjusted adjusted whenever account data for any user is copied, so
 287 that the account will be a member of the affected group locally iff
 288 the source account it is a member of the same group on the source
 289 host.
 290
 291 The most recently-encountered glob-pattern for a particular group
 292 takes effect.  The default is
 293 .BR "nogroups *" .
 294
 295 The glob patterns may contain only alphanumerics, the two glob
 296 metacharacters
 297 .BR "* ?"
 298 and four punctuation characters
 299 .BR "- + . _" ;
 300 \fB\\\fP-quoting and character sets and ranges are not supported.
 301 .TP
 302 .BI "defaultshell " pathname
 303 Local accounts' shells will, when an account is synchronised, be set
 304 to the remote account's shell if the same file exists locally and is
 305 executable.  Otherwise, this value will be used.  The
 306 default is
 307 .BR /bin/sh .
 308 .SH ACCOUNT SELECTION
 309 These directives specify that the selected accounts are to be
 310 synchronised: that is, the local account data will be unconditionally
 311 overwritten (according to the synchronisation settings) with data from
 312 the current source (according to the most recent
 313 .B host
 314 directive).
 315
 316 Any particular local username will only be synchronised once; the
 317 source and settings for first account selection directive which
 318 selects that local username will be used.
 319
 320 When an account is synchronised, the account password, comment field,
 321 and shell will be copied unconditionally.  If
 322 .B sameuid
 323 is in effect specified the uid will be checked (or copied, for new
 324 accounts).
 325 .TP
 326 .BR user " \fIusername\fP [" remote "=\fIremoteusername\fP]"
 327 Specifies that account data should be copied for local user
 328 .I username
 329 from the remote account
 330 .I remoteusername
 331 (or
 332 .I username
 333 if
 334 .I remoteusername
 335 is not specified).
 336 .TP
 337 .RI "\fBusers\fP " ruidmin - ruidmax
 338 Specifies that all remote users whose remote uid is in the given range
 339 are to be synchronised to corresponding user accounts.  (Note that the
 340 remote uid will only be copied if
 341 .B sameuid
 342 is in effect.)
 343 .TP
 344 .BI "nouser " username
 345 Specifies that data for
 346 .I username is not to be copied, even
 347 if subsequent user or users directives suggest that it should be.
 348 .TP
 349 .B addhere
 350 This directive has no effect on sync-accounts.  However, it is used as
 351 a placeholder by grab-account: new accounts for creation are inserted
 352 just before addhere.  See
 353 .BR grab-account (8).
 354 .SH FINAL DIRECTIVE
 355 .TP
 356 .B end
 357 must appear in the configuration file, usually at the end of the file.
 358 Nothing after it will be read.
 359 .SH BUGS
 360 The advice about the correct
 361 .B lockpasswd
 362 and
 363 .B lockgroup
 364 directives is probably out of date or flatly wrong.
 365 .SH AUTHOR
 366 .B sync-accounts
 367 and this manpage are part of the
 368 .B sync-accounts
 369 package which was written by Ian Jackson <ian@chiark.greenend.org.uk>.
 370 They are Copyright 1999-2000,2002 Ian Jackson
 371 <ian@davenant.greenend.org.uk>, and Copyright 2000-2001 nCipher
 372 Corporation Ltd.
 373
 374 The sync-accounts package is free software; you can redistribute it
 375 and/or modify it under the terms of the GNU General Public License as
 376 published by the Free Software Foundation; either version 3, or (at
 377 your option) any later version.
 378
 379 This is distributed in the hope that it will be useful, but WITHOUT ANY
 380 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 381 FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
 382 details.
 383
 384 You should have received a copy of the GNU General Public License along
 385 with this program; if not, consult the Free Software Foundation's
 386 website at www.fsf.org, or the GNU Project website at www.gnu.org.
 387 .SH SEE ALSO
 388 .BR sync-accounts "(8), "
 389 .BR grab-account "(8), "
 390 .BR sync-accounts-createuser "(8), "
 391 .BR passwd "(5), "
 392 .BR group "(5), "
 393 .BR shadow "(5), "
 394 .BR master.passwd "(5), "
 395 .BR vipw "(8), "
 396 .BR vigr "(8)"