NAME¶
/etc/sync-accounts - configuration file for sync-accounts
DESCRIPTION¶
/etc/sync-accounts contains the default configuration of the
sync-accounts(8) account synchronisation tool.
The configuration file specifies how to access and update the local password and
group databases, where sync-accounts should log.
It also specifies the list of (remote) sources for account information, and
which accounts and details should be copied from each source to the local
system.
OVERALL SYNTAX AND SEMANTICS¶
The configuration file is parsed as a series of lines. First, leading and
trailing whitespace on each line is removed, and then empty lines, or lines
starting with
#, are removed.
Each line is parsed as a directive. The order of directives is significant; some
directives set up information which later directives rely on.
The configuration file must contain an
end directive; anything after that
point is ignored.
GLOBAL DIRECTIVES¶
These directives may appear only at the start of the file (before any other
directives), and each directive must appear only once; otherwise,
sync-accounts my behave oddly.
- lockpasswd|lockgroup method
[details ...]
- Specifies how the passwd and group files should be read
and/or locked. See LOCKING METHOD DIRECTIVES below.
- logfile filename
- Append log messages to filename instead of stdout.
Errors still go to stderr.
- localformat bsd|std
- Specifies the local password file is in the relevant
format: std is the standard V7 password file (with a SysV-style
/etc/shadow if /etc/shadow exists). bsd is the BSD4.4 master.passwd
format, and should be used only with lockpasswd runvia vipw. The
default is std.
LOCKING METHOD DIRECTIVES¶
One
lockgroup and one
lockpasswd directive must be present, in the
global directives at the start of the config file.
The choice of the appropriate directives can be difficult without special
knowledge of the local system. In general, it is best to use
lockpasswd
runvia vipw where this is available, as if this works avoids having to
know the names of the lockfiles.
GNU systems (including GNU/Linux and Debian GNU/BSD) typically lock the group
file separately and supply
vigr, in which case you should use
lockgroup vigr.
Most systems other than GNU do not lock the group file at all (or assume that
all programs which modify the group file will lock the passwd file), in which
case
lockgroup none is appropriate.
If vigr or vipw is not available or is known to be broken (eg, because it does
not lock properly), then use
link.
- lockpasswd|lockgroup runvia
program
- sync-accounts will reinvoke itself using program,
which must behave like vipw or vigr. sync-accounts will set
the EDITOR environment variable to the path it was invoked with
(Perl's $0) and put some information for its own use into
SYNC_ACCOUNTS_* environment variables (which will also allow
sync-accounts to tell that it has already been reinvoked via
program and should not do so again).
If both lockpasswd runvia vipw and lockgroup runvia
vigr are specified, then it must be possible and safe for the
EDITOR run by vipw to invoke vigr, as this is what
sync-accounts will do.
- lockpasswd|lockgroup link
suffix| filename
- sync-accounts will attempt to lock the passwd or group file
by making a hardlink from the real file to the specified filename. If
suffix|filename starts with a / it is interpreted as
a filename; otherwise it is interpreted as a suffix, to be appended to the
real database filename.
- lockpasswd|lockgroup none
- sync-accounts will not attempt to lock the passwd or group
files at all.
lockgroup none is appropriate on systems where there is no separate
locking for the group file (either because there is no proper support for
automatic editing of the group file, or because you're expected to lock
the password file), although in the absence of vigr it's inevitable
that simultaneous changes to the group file made by both the human
sysadmin and by sync-accounts will cause problems.
lockpasswd none is very dangerous and should not normally be used. It
will cause data loss if any other tool for changing password data is used
- eg, passwd(1).
PER-SOURCE DIRECTIVES¶
Within each source's section, all of the per-source directives must appear
before any account-selection directives; otherwise sync-accounts may behave
oddly. If a per-source directive is repeated, the last setting takes effect.
- host source
- Starts a source's section. Usually each source will
correspond exactly to one host which is acting as a source of account
data. The host directive resets the per-source parameters to the
defaults. source need not be the source host's official name in any
sense and is used only for identification. Any source must be named
in only one host directive, or sync-accounts may behave oddly.
- getpasswd|getgroup|getshadow
command...
- sync-accounts always fetches account data from sources by
running specified commands on the local host; it does not contain any
network protocols, itself.
command is fed to sh -c and might typically contain something
like
ssh syncacct@remote.host cat /etc/passwd
where the user syncacct on remote.host is in group shadow, or
cat /var/local/sync-accounts/remote.host/passwd where the file named
is copied across using cron.
getpasswd must be specified if user data is to be transferred;
getgroup must be specified if group data is to be transferred.
getshadow should be specified iff getpasswd is specified but the data
from getpasswd does not contain actual password information, and should
emit data in Sys-V shadow password format.
- remoteformat std|bsd
- Specifies the format of the output of getpasswd. std
is standard V7 passwd file format (optionally augmented by the use of a
shadow file fetched with getshadow). bsd is the BSD4.4
master.passwd format (and getshadow should not normally be used with
remoteformat bsd). The default is std.
SYNCHRONISATION SETTINGS¶
The following directives affect the way that account data is copied. They may be
freely mixed with other directives, and repeated. The setting in effect is the
one set by the last relevant settings directive before any particular
account-selection directive.
- uidmin|uidmax value
- When an account is to be created locally, a uid/gid will be
chosen which is one higher than the highest currently in use, except that
ids below uidmin or above uidmax are ignored and will never be used. There
is no default.
- homebase homebase
- When an account is to be created locally, its home
directory will be homebase/username where
username is the name of the account. The default is
/home.
- [no]sameuid
- Specifies whether uids are supposed to match. With
sameuid, it is an error for the uid or gid of a synchronised local
account not to match the corresponding remote account, and new local
accounts will get the remote accounts' ids. The default is
nosameuid.
- usergroups | nousergroups | defaultgid
gid
- Specifies whether local accounts are supposed to have
corresponding groups, or all be part of a particular group. The default is
usergroups.
With usergroups, when a new account is created, the corresponding
per-user group will be created as well, and per-user groups are created
for existing accounts if necessary (if account creation is enabled). If
the gid or group name for a per-user group is already taken for a
different group name or gid this will be logged, and processing of that
account will be inhibited, but it is not a fatal error.
With defaultgid, newly-created accounts will be made a part of that
group, and the groups of existing accounts will be left alone.
With nousergroups, no new accounts can be created, and existing
accounts' groups will be left alone.
- createuser [command] |
nocreateuser
- Specifies whether accounts found on the remote host should
be created if necessary, and what command to run to do the the rest of the
account setup (eg, creation of home directory, etc.). The default is
nocreateuser.
If createuser is specified without a command then
sync-accounts-createuser is used; the supplied
sync-accounts-createuser program is a reasonable minimal implementation.
With createuser, either sameuid, or both uidmin and uidmax, must be
specified, if accounts are actually to be created.
The command is passed to sh -c. See
sync-accounts-createuser(8) for details of command's
environment and functionality.
- group|nogroup glob-pattern
- group specifies that the membership of the local
groups specified should be adjusted adjusted whenever account data for any
user is copied, so that the account will be a member of the affected group
locally iff the source account it is a member of the same group on the
source host.
The most recently-encountered glob-pattern for a particular group takes
effect. The default is nogroups *.
The glob patterns may contain only alphanumerics, the two glob
metacharacters * ? and four punctuation characters - + . _;
\-quoting and character sets and ranges are not supported.
- defaultshell pathname
- Local accounts' shells will, when an account is
synchronised, be set to the remote account's shell if the same file exists
locally and is executable. Otherwise, this value will be used. The default
is /bin/sh.
ACCOUNT SELECTION¶
These directives specify that the selected accounts are to be synchronised: that
is, the local account data will be unconditionally overwritten (according to
the synchronisation settings) with data from the current source (according to
the most recent
host directive).
Any particular local username will only be synchronised once; the source and
settings for first account selection directive which selects that local
username will be used.
When an account is synchronised, the account password, comment field, and shell
will be copied unconditionally. If
sameuid is in effect specified the
uid will be checked (or copied, for new accounts).
- user username
[remote=remoteusername]
- Specifies that account data should be copied for local user
username from the remote account remoteusername (or
username if remoteusername is not specified).
- users ruidmin-ruidmax
- Specifies that all remote users whose remote uid is in the
given range are to be synchronised to corresponding user accounts. (Note
that the remote uid will only be copied if sameuid is in
effect.)
- nouser username
- Specifies that data for username is not to be copied,
even if subsequent user or users directives suggest that it should
be.
- addhere
- This directive has no effect on sync-accounts. However, it
is used as a placeholder by grab-account: new accounts for creation are
inserted just before addhere. See grab-account(8).
FINAL DIRECTIVE¶
- end
- must appear in the configuration file, usually at the end
of the file. Nothing after it will be read.
BUGS¶
The advice about the correct
lockpasswd and
lockgroup directives
is probably out of date or flatly wrong.
AUTHOR¶
sync-accounts and this manpage are part of the
sync-accounts
package which was written by Ian Jackson <ian@chiark.greenend.org.uk>.
They are Copyright 1999-2000,2002 Ian Jackson
<ian@davenant.greenend.org.uk>, and Copyright 2000-2001 nCipher
Corporation Ltd.
The sync-accounts package is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3, or (at your option) any later
version.
This is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with
this program; if not, consult the Free Software Foundation's website at
www.fsf.org, or the GNU Project website at www.gnu.org.
SEE ALSO¶
sync-accounts(8),
grab-account(8),
sync-accounts-createuser(8),
passwd(5),
group(5),
shadow(5),
master.passwd(5),
vipw(8),
vigr(8)