Provided by: chiark-scripts_4.1.28+nmu2build1_all bug

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)