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)