chiark / gitweb /
readahead to cope with plusses; no y2tics if unneeded
[chiark-utils.git] / 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 2, 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, write to the Free Software Foundation, Inc.,
386 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
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)"