SYNC-ACCOUNTS(5)

💖 SYNC-ACCOUNTS(5) 💖

okay so bestie, welcome to the manual for /etc/sync-accounts — that's the config file for the sync-accounts(8) account synchronisation tool. it lives in section 5 of the chiark utilities manpages, and it's literally the blueprint for how your whole account-syncing situation goes down. let's get into it 🫶

---

🌸 NAME 🌸

/etc/sync-accounts — configuration file for sync-accounts

---

✨ DESCRIPTION ✨

/etc/sync-accounts holds the default configuration of the sync-accounts(8) account synchronisation tool. yes, the tool. main character energy only 💅

This config file is the one that spells out:

• how to access and update the local password and group databases,
• where sync-accounts should log,
• the list of (remote) sources for account information,
• and which accounts and details should be copied from each source onto the local system.

---

🎀 OVERALL SYNTAX AND SEMANTICS 🎀

The config file gets parsed as a series of lines. Here's the order of operations, no cap:

1. First, leading and trailing whitespace on each line gets removed.
2. Then, empty lines — or lines starting with # — get removed. (yes bestie, # is your comment bestie 💬)
3. Each remaining line is parsed as a directive.

The order of directives is significant — some directives set up info that later directives rely on. So don't go shuffling things around for funsies 🙈

The configuration file must contain an end directive; anything after that point is ignored. like, fully ghosted. 💀

---

👑 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 may behave oddly. and not the cute kind of odd, the "why is my passwd file like this" kind 😭

• lockpasswd|lockgroup method [details ...] — Specifies how the passwd and group files should be read and/or locked. Peep LOCKING METHOD DIRECTIVES below for the whole tea.
• logfile filename — Append log messages to filename instead of stdout. Errors still go to stderr though — some things never change ✨
• 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, sitting in the global directives at the start of the config file. no skipping, bestie 🚫

Picking the right directives can be lowkey hard without special knowledge of the local system. But here's the general vibe:

• In general, it's best to use lockpasswd runvia vipw where this is available, because if this works it avoids having to know the names of the lockfiles. slay, less homework for you 💅
• 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 they 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). very "i've been here before" of it 🌀

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. yes, it's a whole chain reaction 😭

• 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. wild, i know.

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. two people editing the same doc, no version history, yikes 💀

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). bestie. do NOT. 🙈

---

🦋 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. last one wins, periodt ✨

• 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. it's giving "i don't do long distance, you come to me" 💅

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. (yes, "iff" — that's if-and-only-if, we're being precise today 😌)

• 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. so like, whatever you said most recently? that's the rules now 🎀

• 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. (yeah, you gotta say it yourself, no assumptions here 🙈)
• 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. cozy 🏠
• [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. so it's a "we'll note that and move on" moment, not a crash-out 🫶
  • 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 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. (pick a lane, bestie ✋)

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 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. keeping it simple, keeping it cute ✨

• 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. 🐚

---

okay bestie that's part 1, and there's more coming so don't go anywhere — we're not done yet 💖

✨ ACCOUNT SELECTION ✨

okay so 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). no take-backs, bestie. 💅

Any particular local username will only be synchronised once; the source and settings for the first account selection directive which selects that local username will be used. periodt. ✨

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. so don't try to sneak extra stuff after end, bestie, it's giving invisible. 💀

🐛 BUGS 🐛

The advice about the correct lockpasswd and lockgroup directives is probably out of date or flatly wrong. 😭 lowkey iconic of it.

👑 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. slay. 💅

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) — go read these too, bestie, they're part of the lore. 📚

---

💖 k bye! this manual page is from Greenend, dated 15th July 2002, and it's the SYNC-ACCOUNTS(5) page. periodt. 💅✨