DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

rsyncd.conf(5)




rsyncd.conf(5)            FILE FORMATS             rsyncd.conf(5)


NAME

     rsyncd.conf - configuration file for rsync in daemon mode


SYNOPSIS

     rsyncd.conf


DESCRIPTION

     The rsyncd.conf file is the runtime configuration  file  for
     rsync when run as an rsync daemon.

     The rsyncd.conf file controls authentication,  access,  log-
     ging and available modules.


FILE FORMAT

     The file consists of modules and parameters. A module begins
     with the name of the module in square brackets and continues
     until the next module begins. Modules contain parameters  of
     the form name = value.

     The file is line-based -- that is,  each  newline-terminated
     line represents either a comment, a module name or a parame-
     ter.

     Only the first equals sign in a  parameter  is  significant.
     Whitespace  before  or  after  the first equals sign is dis-
     carded. Leading, trailing and internal whitespace in  module
     and parameter names is irrelevant. Leading and trailing whi-
     tespace in a parameter value  is  discarded.  Internal  whi-
     tespace within a parameter value is retained verbatim.

     Any line beginning with a hash (#) is ignored, as are  lines
     containing only whitespace. (If a hash occurs after anything
     other than leading whitespace, it is considered  a  part  of
     the lines content.)

     Any line ending in a \ is continued on the next line in  the
     customary UNIX fashion.

     The values following the equals sign in parameters  are  all
     either  a  string (no quotes needed) or a boolean, which may
     be given as yes/no, 0/1 or true/false. Case is not  signifi-
     cant in boolean values, but is preserved in string values.


LAUNCHING THE RSYNC DAEMON

     The rsync daemon is  launched  by  specifying  the  --daemon
     option to rsync.

     The daemon must run with root privileges if you wish to  use
     chroot,  to  bind  to  a port numbered under 1024 (as is the
     default 873), or to set file ownership.  Otherwise, it  must
     just have permission to read and write the appropriate data,
     log, and lock files.

                    Last change: 21 Dec 2015                    1

rsyncd.conf(5)            FILE FORMATS             rsyncd.conf(5)

     You can launch it either via inetd, as a stand-alone daemon,
     or  from  an  rsync  client via a remote shell.  If run as a
     stand-alone daemon then just run the command rsync  --daemon
     from a suitable startup script.

     When run via inetd you  should  add  a  line  like  this  to
     /etc/services:

       rsync           873/tcp

     and a single line something like this to /etc/inetd.conf:

       rsync   stream  tcp     nowait  root   /usr/bin/rsync rsyncd --daemon

     Replace /usr/bin/rsync with the path to where you have rsync
     installed  on your system.  You will then need to send inetd
     a HUP signal to tell it to reread its config file.

     Note that you should not send the rsync daemon a HUP  signal
     to  force  it  to  reread  the rsyncd.conf file. The file is
     re-read on each client connection.


GLOBAL PARAMETERS

     The first parameters in the file (before a [module]  header)
     are the global parameters.  Rsync also allows for the use of
     a [global] module name to indicate the start of one or  more
     global-parameter sections (the name must be lower case).

     You may also include any module  parameters  in  the  global
     part  of  the  config  file in which case the supplied value
     will override the default for that parameter.

     You may use  references  to  environment  variables  in  the
     values  of  parameters.   String  parameters will have %VAR%
     references expanded as late as possible (when the string  is
     used in the program), allowing for the use of variables that
     rsync sets at  connection  time,  such  as  RSYNC_USER_NAME.
     Non-string  parameters  (such  as  true/false  settings) are
     expanded when read from the config file.  If a variable does
     not exist in the environment, or if a sequence of characters
     is not a valid  reference  (such  as  an  un-paired  percent
     sign),  the  raw  characters  are  passed through unchanged.
     This helps with  backward  compatibility  and  safety  (e.g.
     expanding  a non-existent %VAR% to an empty string in a path
     could result in a very unsafe  path).   The  safest  way  to
     insert a literal % into a value is to use %%.

     motd file
          This parameter allows you to specify a message  of  the
          day to display to clients on each connect. This usually

                    Last change: 21 Dec 2015                    2

rsyncd.conf(5)            FILE FORMATS             rsyncd.conf(5)

          contains site information and any  legal  notices.  The
          default is no motd file.  This can be overridden by the
          --dparam=motdfile=FILE command-line option when  start-
          ing the daemon.

     pid file
          This parameter tells the rsync daemon to write its pro-
          cess  ID to that file.  If the file already exists, the
          rsync daemon will abort rather than overwrite the file.
          This  can  be  overridden  by the --dparam=pidfile=FILE
          command-line option when starting the daemon.

     port You can override  the  default  port  the  daemon  will
          listen  on  by specifying this value (defaults to 873).
          This is ignored if the daemon is being  run  by  inetd,
          and is superseded by the --port command-line option.

     address
          You can override the default IP address the daemon will
          listen on by specifying this value.  This is ignored if
          the daemon is being run by inetd, and is superseded  by
          the --address command-line option.

     socket options
          This parameter can provide endless fun for  people  who
          like  to  tune  their systems to the utmost degree. You
          can set all sorts of  socket  options  which  may  make
          transfers  faster  (or  slower!). Read the man page for
          the setsockopt() system call for details on some of the
          options  you  may be able to set. By default no special
          socket options are set.  These  settings  can  also  be
          specified via the --sockopts command-line option.

     listen backlog
          You can override the default  backlog  value  when  the
          daemon listens for connections.  It defaults to 5.


MODULE PARAMETERS

     After the global parameters you should define  a  number  of
     modules,  each module exports a directory tree as a symbolic

                    Last change: 21 Dec 2015                    3

rsyncd.conf(5)            FILE FORMATS             rsyncd.conf(5)

     name. Modules are exported by specifying a  module  name  in
     square brackets [module] followed by the parameters for that
     module.  The module name cannot contain a slash or a closing
     square  bracket.   If  the  name  contains  whitespace, each
     internal sequence of whitespace will be changed into a  sin-
     gle space, while leading or trailing whitespace will be dis-
     carded.  Also, the name cannot be global as that exact  name
     indicates that global parameters follow (see above).

     As  with  GLOBAL  PARAMETERS,  you  may  use  references  to
     environment  variables in the values of parameters.  See the
     GLOBAL PARAMETERS section for more details.

     comment
          This parameter specifies a description string  that  is
          displayed next to the module name when clients obtain a
          list of available modules. The default is no comment.

     path This parameter specifies the directory in  the  daemons
          filesystem  to make available in this module.  You must
          specify this parameter for each module in rsyncd.conf.

          You may base the paths  value  off  of  an  environment
          variable  by surrounding the variable name with percent
          signs.  You can even reference a variable that  is  set
          by  rsync  when  the  user connects.  For example, this
          would use the authorizing users name in the path:

              path = /home/%RSYNC_USER_NAME%

          It is fine if the path includes internal spaces -- they
          will   be  retained  verbatim  (which  means  that  you
          shouldnt try to escape them).  If your final  directory
          has a trailing space (and this is somehow not something
          you wish to fix), append a trailing slash to  the  path
          to avoid losing the trailing whitespace.

     use chroot
          If use chroot is true, the rsync daemon will chroot  to
          the  path  before  starting  the file transfer with the
          client.  This has the  advantage  of  extra  protection
          against  possible implementation security holes, but it
          has   the   disadvantages   of   requiring   super-user
          privileges,  of not being able to follow symbolic links
          that are either absolute or outside  of  the  new  root
          path, and of complicating the preservation of users and

                    Last change: 21 Dec 2015                    4

rsyncd.conf(5)            FILE FORMATS             rsyncd.conf(5)

          groups by name (see below).

          As an additional safety  feature,  you  can  specify  a
          dot-dir in the modules path to indicate the point where
          the chroot should occur.  This allows rsync to run in a
          chroot  with  a  non-/ path for the top of the transfer
          hierarchy.   Doing  this  guards   against   unintended
          library loading (since those absolute paths will not be
          inside the transfer hierarchy unless you have  used  an
          unwise  pathname), and lets you setup libraries for the
          chroot that are outside of the transfer.  For  example,
          specifying  /var/rsync/./module1  will  chroot  to  the
          /var/rsync directory and set the inside-chroot path  to
          /module1.   If  you had omitted the dot-dir, the chroot
          would have used the whole path, and  the  inside-chroot
          path would have been /.

          When use chroot is false or the inside-chroot  path  is
          not  /,  rsync will:  (1) munge symlinks by default for
          security reasons (see munge symlinks for a way to  turn
          this  off,  but only if you trust your users), (2) sub-
          stitute leading slashes  in  absolute  paths  with  the
          modules  path  (so  that  options such as --backup-dir,
          --compare-dest, etc.  interpret  an  absolute  path  as
          rooted  in  the modules path dir), and (3) trim .. path
          elements from args if rsync believes they would  escape
          the  module  hierarchy.   The default for use chroot is
          true, and is the safer choice (especially if the module
          is not read-only).

          When this parameter is enabled, the numeric-ids  option
          will  also  default  to  being  enabled (disabling name
          lookups).  See below for what a chroot needs  in  order
          for name lookups to succeed.

          If you copy library resources into the  modules  chroot
          area,  you  should protect them through your OSs normal
          user/group  or  ACL  settings  (to  prevent  the  rsync
          modules  user from being able to change them), and then
          hide them from the users view via exclude (see  how  in
          the  discussion  of  that parameter).  At that point it
          will be safe to enable the mapping of users and  groups
          by name using this numeric ids daemon parameter.

          Note also that you are free to setup custom  user/group
          information  in  the chroot area that is different from
          your normal system.  For example, you could  abbreviate
          the list of users and groups.

     numeric ids

                    Last change: 21 Dec 2015                    5

rsyncd.conf(5)            FILE FORMATS             rsyncd.conf(5)

          Enabling this parameter disables the mapping  of  users
          and groups by name for the current daemon module.  This
          prevents  the  daemon   from   trying   to   load   any
          user/group-related  files  or libraries.  This enabling
          makes the transfer behave as if the client  had  passed
          the  --numeric-ids  command-line  option.   By default,
          this parameter is enabled for chroot modules  and  dis-
          abled  for  non-chroot modules.  Also keep in mind that
          uid/gid preservation requires the module to be  running
          as root (see uid) or for fake super to be configured.

          A chroot-enabled module should not have this  parameter
          enabled  unless  youve  taken  steps to ensure that the
          module  has  the  necessary  resources  it   needs   to
          translate names, and that it is not possible for a user
          to change those resources.   That  includes  being  the
          code  being  able  to  call functions like getpwuid() ,
          getgrgid() ,  getpwname()  ,  and  getgrnam()  ).   You
          should   test  what  libraries  and  config  files  are
          required for your OS and get those setup before  start-
          ing to test name mapping in rsync.

     munge symlinks
          This parameter tells rsync to modify  all  symlinks  in
          the    same    way    as   the   (non-daemon-affecting)
          --munge-links  command-line  option  (using  a   method
          described  below).  This should help protect your files
          from user trickery when your daemon module is writable.
          The  default  is disabled when use chroot is on and the
          inside-chroot path is /, otherwise it is enabled.

          If you disable this parameter on a daemon that  is  not
          read-only,  there  are tricks that a user can play with
          uploaded symlinks to access daemon-excluded  items  (if
          your  module has any), and, if use chroot is off, rsync
          can even be tricked into showing or changing data  that
          is  outside  the  modules  path  (as access-permissions
          allow).

          The way rsync disables the use of symlinks is to prefix
          each   one   with  the  string  /rsyncd-munged/.   This
          prevents the links from being  used  as  long  as  that
          directory  does  not  exist.   When  this  parameter is
          enabled, rsync will refuse to run if  that  path  is  a
          directory  or a symlink to a directory.  When using the
          munge symlinks parameter in a chroot area that  has  an
          inside-chroot path of /, you should add /rsyncd-munged/
          to the exclude setting for the module so  that  a  user
          cant try to create it.

                    Last change: 21 Dec 2015                    6

rsyncd.conf(5)            FILE FORMATS             rsyncd.conf(5)

          Note:  rsync  makes  no  attempt  to  verify  that  any
          pre-existing  symlinks  in the modules hierarchy are as
          safe as you want them to be (unless, of course, it just
          copied  in the whole hierarchy).  If you setup an rsync
          daemon on a new area or locally add symlinks,  you  can
          manually  protect  your  symlinks  from being abused by
          prefixing  /rsyncd-munged/  to  the  start   of   every
          symlinks  value.  There is a perl script in the support
          directory of the source code named munge-symlinks  that
          can be used to add or remove this prefix from your sym-
          links.

          When this parameter is disabled on  a  writable  module
          and use chroot is off (or the inside-chroot path is not
          /), incoming symlinks will be modified to drop a  lead-
          ing  slash  and  to  remove .. path elements that rsync
          believes will allow a symlink  to  escape  the  modules
          hierarchy.   There are tricky ways to work around this,
          though, so you had  better  trust  your  users  if  you
          choose this combination of parameters.

     charset
          This specifies the name of the character set  in  which
          the  modules  filenames are stored.  If the client uses
          an --iconv option, the daemon will use the value of the
          charset  parameter  regardless of the character set the
          client actually passed.  This allows the daemon to sup-
          port  charset  conversion  in  a  chroot module without
          extra files in the chroot area, and also  ensures  that
          name-translation  is  done  in a consistent manner.  If
          the charset parameter is not set, the --iconv option is
          refused, just as if iconv had been specified via refuse
          options.

          If you wish to force users to always use --iconv for  a
          particular  module,  add no-iconv to the refuse options
          parameter.  Keep in mind that this will restrict access
          to your module to very new rsync clients.

     max connections
          This parameter allows you to specify the maximum number
          of   simultaneous  connections  you  will  allow.   Any
          clients connecting when the maximum  has  been  reached
          will  receive a message telling them to try later.  The
          default is 0, which means no limit.  A  negative  value
          disables the module.  See also the lock file parameter.

                    Last change: 21 Dec 2015                    7

rsyncd.conf(5)            FILE FORMATS             rsyncd.conf(5)

     log file
          When the log file  parameter  is  set  to  a  non-empty
          string, the rsync daemon will log messages to the indi-
          cated file rather than using syslog. This  is  particu-
          larly  useful  on  systems (such as AIX) where syslog()
          doesnt work for chrooted programs.  The file is  opened
          before  chroot()  is  called,  allowing it to be placed
          outside the transfer.   If  this  value  is  set  on  a
          per-module  basis  instead  of globally, the global log
          will  still  contain  any  authorization  failures   or
          config-file error messages.

          If the daemon fails to open the specified file, it will
          fall back to using syslog and output an error about the
          failure.  (Note that the failure to open the  specified
          log file used to be a fatal error.)

          This  setting  can   be   overridden   by   using   the
          --log-file=FILE  or  --dparam=logfile=FILE command-line
          options.  The former overrides all the log-file parame-
          ters of the daemon and all module settings.  The latter
          sets the daemons log file and the default for  all  the
          modules,  which  still  allows  modules to override the
          default setting.

     syslog facility
          This parameter allows you to specify the syslog  facil-
          ity  name  to  use when logging messages from the rsync
          daemon. You may use any standard syslog  facility  name
          which is defined on your system. Common names are auth,
          authpriv, cron, daemon, ftp,  kern,  lpr,  mail,  news,
          security,  syslog,  user, uucp, local0, local1, local2,
          local3, local4, local5, local6 and local7. The  default
          is  daemon.  This setting has no effect if the log file
          setting is  a  non-empty  string  (either  set  in  the
          per-modules settings, or inherited from the global set-
          tings).

     max verbosity
          This parameter allows you to control the maximum amount
          of  verbose  information that youll allow the daemon to
          generate (since  the  information  goes  into  the  log
          file).  The  default  is  1, which allows the client to
          request one level of verbosity.

          This also affects the users ability to  request  higher
          levels of --info and --debug logging.  If the max value
          is 2, then no info and/or debug value  that  is  higher

                    Last change: 21 Dec 2015                    8

rsyncd.conf(5)            FILE FORMATS             rsyncd.conf(5)

          than  what  would  be set by -vv will be honored by the
          daemon in its logging.  To see how high of a  verbosity
          level  you  need  to accept for a particular info/debug
          level,   refer   to   rsync   --info=help   and   rsync
          --debug=help.   For  instance, it takes max-verbosity 4
          to be able to output debug TIME2 and FLIST3.

     lock file
          This parameter specifies the file to use to support the
          max connections parameter. The rsync daemon uses record
          locking on this file to ensure that the max connections
          limit  is not exceeded for the modules sharing the lock
          file.  The default is /var/run/rsyncd.lock.

     read only
          This parameter determines whether clients will be  able
          to  upload  files or not. If read only is true then any
          attempted uploads will fail. If read only is false then
          uploads  will  be  possible  if file permissions on the
          daemon side allow them. The default is for all  modules
          to be read only.

          Note that auth users can override  this  setting  on  a
          per-user basis.

     write only
          This parameter determines whether clients will be  able
          to  download  files  or not. If write only is true then
          any attempted downloads will fail.  If  write  only  is
          false  then  downloads will be possible if file permis-
          sions on the daemon side allow them.   The  default  is
          for this parameter to be disabled.

     list This parameter determines whether this module is listed
          when  the  client  asks  for  a  listing  of  available
          modules.  In addition, if this  is  false,  the  daemon
          will  pretend  the  module does not exist when a client
          denied by hosts allow or hosts deny attempts to  access
          it.   Realize  that  if reverse lookup is disabled glo-
          bally but enabled for the module, the resulting reverse
          lookup  to  a  potentially client-controlled DNS server
          may still reveal to the client that it hit an  existing
          module.  The default is for modules to be listable.

                    Last change: 21 Dec 2015                    9

rsyncd.conf(5)            FILE FORMATS             rsyncd.conf(5)

     uid  This parameter specifies the user name or user ID  that
          file  transfers  to  and  from  that module should take
          place as when the daemon was run as root.  In  combina-
          tion  with  the gid parameter this determines what file
          permissions are available. The default when  run  by  a
          super-user  is  to  switch  to the systems nobody user.
          The default for a  non-super-user  is  to  not  try  to
          change the user.  See also the gid parameter.

          The RSYNC_USER_NAME environment variable may be used to
          request  that  rsync  run as the authorizing user.  For
          example, if you want a rsync to run as  the  same  user
          that  was  received  for the rsync authentication, this
          setup is useful:

              uid = %RSYNC_USER_NAME%
              gid = *

     gid  This parameter specifies one or  more  group  names/IDs
          that will be used when accessing the module.  The first
          one will be the default group, and any  extra  ones  be
          set  as  supplemental groups.  You may also specify a *
          as the first gid in the list, which will be replaced by
          all the normal groups for the transfers user (see uid).
          The default when run by a super-user is  to  switch  to
          your  OSs  nobody  (or  perhaps  nogroup) group with no
          other  supplementary  groups.   The   default   for   a
          non-super-user  is  to  not change any group attributes
          (and indeed, your OS may not allow a non-super-user  to
          try to change their group settings).

     fake super
          Setting fake super = yes for a module causes the daemon
          side  to  behave  as  if  the --fake-super command-line
          option had been specified.  This allows the full attri-
          butes of a file to be stored without having to have the
          daemon actually running as root.

     filter
          The daemon has its own  filter  chain  that  determines
          what  files  it will let the client access.  This chain
          is not sent to the client and  is  independent  of  any

                    Last change: 21 Dec 2015                   10

rsyncd.conf(5)            FILE FORMATS             rsyncd.conf(5)

          filters  the client may have specified.  Files excluded
          by the daemon filter chain (daemon-excluded files)  are
          treated  as  non-existent  if  the client tries to pull
          them, are skipped with an error message if  the  client
          tries  to  push them (triggering exit code 23), and are
          never deleted from the  module.   You  can  use  daemon
          filters  to prevent clients from downloading or tamper-
          ing with private administrative files,  such  as  files
          you may add to support uid/gid name translations.

          The daemon filter  chain  is  built  from  the  filter,
          include from, include, exclude from, and exclude param-
          eters, in that order of  priority.   Anchored  patterns
          are  anchored  at  the  root of the module.  To prevent
          access to an entire subtree, for example, /secret,  you
          must exclude everything in the subtree; the easiest way
          to  do  this  is  with  a  triple-star   pattern   like
          /secret/***.

          The filter parameter takes a  space-separated  list  of
          daemon  filter rules, though it is smart enough to know
          not to split a token at an internal  space  in  a  rule
          (e.g.  - /foo  - /bar is parsed as two rules).  You may
          specify one or more merge-file rules using  the  normal
          syntax.  Only one filter parameter can apply to a given
          module in the config file, so put  all  the  rules  you
          want  in  a  single parameter.  Note that per-directory
          merge-file rules do not provide as much  protection  as
          global  rules,  but  they  can be used to make --delete
          work better during a client download operation  if  the
          per-dir  merge  files  are included in the transfer and
          the client requests that they be used.

     exclude
          This parameter takes a space-separated list  of  daemon
          exclude patterns.  As with the client --exclude option,
          patterns can be qualified with -  or +   to  explicitly
          indicate  exclude/include.   Only one exclude parameter
          can apply to a given module.  See the filter  parameter
          for a description of how excluded files affect the dae-
          mon.

     include
          Use an include to override the effects of  the  exclude
          parameter.   Only  one include parameter can apply to a
          given module.  See the filter parameter for a  descrip-
          tion of how excluded files affect the daemon.

                    Last change: 21 Dec 2015                   11

rsyncd.conf(5)            FILE FORMATS             rsyncd.conf(5)

     exclude from
          This parameter specifies the name of a file on the dae-
          mon  that  contains  daemon  exclude  patterns, one per
          line.  Only one exclude from parameter can apply  to  a
          given  module; if you have multiple exclude-from files,
          you can specify them as a  merge  file  in  the  filter
          parameter.   See the filter parameter for a description
          of how excluded files affect the daemon.

     include from
          Analogue of exclude from for a file of  daemon  include
          patterns.  Only one include from parameter can apply to
          a  given  module.   See  the  filter  parameter  for  a
          description of how excluded files affect the daemon.

     incoming chmod
          This  parameter  allows  you  to  specify  a   set   of
          comma-separated chmod strings that will affect the per-
          missions of all incoming files (files  that  are  being
          received  by  the  daemon).  These changes happen after
          all other permission calculations, and this  will  even
          override  destination-default  and/or  existing permis-
          sions when the client does not  specify  --perms.   See
          the  description  of  the  --chmod rsync option and the
          chmod(1) manpage for information on the format of  this
          string.

     outgoing chmod
          This  parameter  allows  you  to  specify  a   set   of
          comma-separated chmod strings that will affect the per-
          missions of all outgoing files (files  that  are  being
          sent out from the daemon).  These changes happen first,
          making the sent permissions appear to be different than
          those  stored  in the filesystem itself.  For instance,
          you could disable group write permissions on the server
          while  having  it  appear to be on to the clients.  See
          the description of the --chmod  rsync  option  and  the
          chmod(1)  manpage for information on the format of this
          string.

     auth users
          This parameter specifies a comma and/or space-separated

                    Last change: 21 Dec 2015                   12

rsyncd.conf(5)            FILE FORMATS             rsyncd.conf(5)

          list of authorization rules.  In its simplest form, you
          list the usernames that will be allowed to  connect  to
          this  module. The usernames do not need to exist on the
          local system. The  rules  may  contain  shell  wildcard
          characters  that  will  be matched against the username
          provided by the  client  for  authentication.  If  auth
          users is set then the client will be challenged to sup-
          ply a username and password to connect to the module. A
          challenge  response authentication protocol is used for
          this exchange. The plain text usernames  and  passwords
          are  stored  in  the file specified by the secrets file
          parameter. The default is for all users to be  able  to
          connect  without  a  password (this is called anonymous
          rsync).

          In addition  to  username  matching,  you  can  specify
          groupname  matching  via a @ prefix.  When using group-
          name matching, the authenticating username  must  be  a
          real  user on the system, or it will be assumed to be a
          member of no groups.  For  example,  specifying  @rsync
          will match the authenticating user if the named user is
          a member of the rsync group.

          Finally, options may be specified after  a  colon  (:).
          The  options  allow  you to deny a user or a group, set
          the access to ro (read-only), or set the access  to  rw
          (read/write).  Setting an auth-rule-specific ro/rw set-
          ting overrides the modules read only setting.

          Be sure to put the rules in the order you want them  to
          be  matched,  because  the  checking stops at the first
          matching user or group, and that is the only auth  that
          is checked.  For example:

            auth users = joe:deny @guest:deny admin:rw @rsync:ro susan joe sam

          In the above rule, user joe will be  denied  access  no
          matter  what.   Any  user that is in the group guest is
          also denied access.  The  user  admin  gets  access  in
          read/write  mode,  but only if the admin user is not in
          group guest (because the admin user-matching rule would
          never  be  reached if the user is in group guest).  Any
          other user who is in group  rsync  will  get  read-only
          access.   Finally,  users  susan,  joe, and sam get the
          ro/rw setting of the module, but only if the user didnt
          match an earlier group-matching rule.

          See the description of the secrets file for how you can
          have per-user passwords as well as per-group passwords.
          It also explains how  a  user  can  authenticate  using

                    Last change: 21 Dec 2015                   13

rsyncd.conf(5)            FILE FORMATS             rsyncd.conf(5)

          their  user password or (when applicable) a group pass-
          word, depending on what rule is being authenticated.

          See  also  the  section  entitled  USING   RSYNC-DAEMON
          FEATURES  VIA A REMOTE SHELL CONNECTION in rsync(1) for
          information on how handle an rsyncd.conf-level username
          that  differs from the remote-shell-level username when
          using a remote shell to connect to an rsync daemon.

     secrets file
          This parameter specifies the name of a file  that  con-
          tains  the username:password and/or @groupname:password
          pairs used for authenticating this module. This file is
          only  consulted  if  the auth users parameter is speci-
          fied.   The  file  is  line-based  and   contains   one
          name:password  pair  per line.  Any line has a hash (#)
          as the very first character on the line is considered a
          comment  and is skipped.  The passwords can contain any
          characters but be warned that  many  operating  systems
          limit  the length of passwords that can be typed at the
          client end, so you may find that passwords longer  than
          8 characters dont work.

          The use of group-specific lines are only relevant  when
          the module is being authorized using a matching @group-
          name rule.  When that happens, the user can be  author-
          ized  via  either  their  username:password line or the
          @groupname:password line for the group  that  triggered
          the authentication.

          It is up to you what kind of password entries you  want
          to  include, either users, groups, or both.  The use of
          group rules in auth users does  not  require  that  you
          specify  a  group  password  if  you do not want to use
          shared passwords.

          There is no default for the secrets file parameter, you
          must  choose a name (such as /etc/rsyncd.secrets).  The
          file must normally not be readable by other; see strict
          modes.   If  the  file  is not found or is rejected, no
          logins for a user auth module will be possible.

     strict modes
          This parameter determines whether or  not  the  permis-
          sions  on  the secrets file will be checked.  If strict
          modes is true, then the secrets file must not be  read-
          able  by  any user ID other than the one that the rsync
          daemon is running under.  If strict modes is false, the

                    Last change: 21 Dec 2015                   14

rsyncd.conf(5)            FILE FORMATS             rsyncd.conf(5)

          check  is  not  performed.   The default is true.  This
          parameter was added to accommodate rsync running on the
          Windows operating system.

     hosts allow
          This parameter allows you to specify a list of patterns
          that  are matched against a connecting clients hostname
          and IP address. If none of the patterns match then  the
          connection is rejected.

          Each pattern can be in one of five forms:

          o    a dotted decimal IPv4 address of the form a.b.c.d,
               or  an  IPv6  address of the form a:b:c::d:e:f. In
               this case the incoming machines  IP  address  must
               match exactly.

          o    an address/mask in the form ipaddr/n where  ipaddr
               is  the IP address and n is the number of one bits
               in the netmask.  All IP addresses which match  the
               masked IP address will be allowed in.

          o    an address/mask in the form ipaddr/maskaddr  where
               ipaddr  is the IP address and maskaddr is the net-
               mask in dotted decimal notation for IPv4, or simi-
               lar  for  IPv6, e.g. ffff:ffff:ffff:ffff:: instead
               of /64. All IP addresses which match the masked IP
               address will be allowed in.

          o    a hostname pattern using wildcards. If  the  host-
               name  of  the  connecting  IP  (as determined by a
               reverse lookup) matches the wildcarded name (using
               the  same rules as normal unix filename matching),
               the client is allowed  in.   This  only  works  if
               reverse lookup is enabled (the default).

          o    a hostname. A plain hostname  is  matched  against
               the  reverse  DNS of the connecting IP (if reverse
               lookup is enabled), and/or the  IP  of  the  given
               hostname  is matched against the connecting IP (if
               forward lookup is enabled, as it is  by  default).
               Any match will be allowed in.

          Note IPv6 link-local addresses can have a scope in  the
          address specification:

                    Last change: 21 Dec 2015                   15

rsyncd.conf(5)            FILE FORMATS             rsyncd.conf(5)

              fe80::1%link1
              fe80::%link1/64
              fe80::%link1/ffff:ffff:ffff:ffff::

          You can also combine hosts allow with a separate  hosts
          deny  parameter.  If both parameters are specified then
          the hosts allow parameter is checked first and a  match
          results  in the client being able to connect. The hosts
          deny parameter is then checked and a match  means  that
          the host is rejected. If the host does not match either
          the hosts allow or the hosts deny patterns then  it  is
          allowed to connect.

          The default is no hosts allow  parameter,  which  means
          all hosts can connect.

     hosts deny
          This parameter allows you to specify a list of patterns
          that  are matched against a connecting clients hostname
          and IP address. If the pattern matches then the connec-
          tion  is  rejected.  See  the hosts allow parameter for
          more information.

          The default is no hosts deny parameter, which means all
          hosts can connect.

     reverse lookup
          Controls whether the daemon performs a  reverse  lookup
          on  the  clients  IP address to determine its hostname,
          which is used for hosts allow/hosts deny checks and the
          %h log escape.  This is enabled by default, but you may
          wish to disable it to save time if you know the  lookup
          will not return a useful result, in which case the dae-
          mon will use the name UNDETERMINED instead.

          If  this  parameter  is  enabled  globally   (even   by
          default), rsync performs the lookup as soon as a client
          connects, so disabling it for a module will  not  avoid
          the lookup.  Thus, you probably want to disable it glo-
          bally and then enable it  for  modules  that  need  the
          information.

     forward lookup
          Controls whether the daemon performs a  forward  lookup
          on  any  hostname  specified  in  an  hosts  allow/deny

                    Last change: 21 Dec 2015                   16

rsyncd.conf(5)            FILE FORMATS             rsyncd.conf(5)

          setting.  By default this is enabled, allowing the  use
          of  an  explicit hostname that would not be returned by
          reverse DNS of the connecting IP.

     ignore errors
          This parameter tells rsyncd to ignore I/O errors on the
          daemon when deciding whether to run the delete phase of
          the transfer. Normally rsync skips the --delete step if
          any I/O errors have occurred in order to prevent disas-
          trous deletion due to a temporary resource shortage  or
          other  I/O  error.  In  some cases this test is counter
          productive so you can use this parameter  to  turn  off
          this behavior.

     ignore nonreadable
          This tells the rsync daemon to completely ignore  files
          that  are  not readable by the user. This is useful for
          public archives that may have some  non-readable  files
          among  the  directories,  and  the sysadmin doesnt want
          those files to be seen at all.

     transfer logging
          This parameter enables per-file  logging  of  downloads
          and  uploads  in a format somewhat similar to that used
          by ftp daemons.  The daemon always logs the transfer at
          the  end,  so if a transfer is aborted, no mention will
          be made in the log file.

          If you want to customize the log  lines,  see  the  log
          format parameter.

     log format
          This parameter allows you to specify  the  format  used
          for  logging  file  transfers  when transfer logging is
          enabled.  The format is a text string containing embed-
          ded  single-character  escape sequences prefixed with a
          percent (%) character.  An optional numeric field width
          may  also  be  specified  between  the  percent and the
          escape letter (e.g. %-50n %8l %07p).  In addition,  one
          or more apostrophes may be specified prior to a numeri-
          cal escape to indicate that the numerical value  should
          be  made  more  human-readable.  The 3 supported levels
          are the same as for the  --human-readable  command-line
          option,  though the default is for human-readability to

                    Last change: 21 Dec 2015                   17

rsyncd.conf(5)            FILE FORMATS             rsyncd.conf(5)

          be off.  Each  added  apostrophe  increases  the  level
          (e.g. %''l %'b %f).

          The default log format is %o %h [%a] %m (%u) %f %l, and
          a  %t  [%p]  is always prefixed when using the log file
          parameter.  (A perl script  that  will  summarize  this
          default log format is included in the rsync source code
          distribution in the support subdirectory:  rsyncstats.)

          The single-character escapes that are understood are as
          follows:

          o    %a the remote IP address  (only  available  for  a
               daemon)

          o    %b the number of bytes actually transferred

          o    %B  the  permission  bits  of   the   file   (e.g.
               rwxrwxrwt)

          o    %c the total size of the block checksums  received
               for the basis file (only when sending)

          o    %C the full-file MD5  checksum  if  --checksum  is
               enabled or a file was transferred (only for proto-
               col 30 or above).

          o    %f the filename (long form on sender; no  trailing
               /)

          o    %G the gid of the file (decimal) or DEFAULT

          o    %h the remote host name (only available for a dae-
               mon)

          o    %i an itemized list of what is being updated

          o    %l the length of the file in bytes

          o    %L the string  ->  SYMLINK,    =>  HARDLINK,  or
               (where SYMLINK or HARDLINK is a filename)

          o    %m the module name

          o    %M the last-modified time of the file

          o    %n the filename (short form; trailing / on dir)

          o    %o the operation, which is  send,  recv,  or  del.
               (the latter includes the trailing period)

                    Last change: 21 Dec 2015                   18

rsyncd.conf(5)            FILE FORMATS             rsyncd.conf(5)

          o    %p the process ID of this rsync session

          o    %P the module path

          o    %t the current date time

          o    %u the authenticated username or an empty string

          o    %U the uid of the file (decimal)

          For a list of what the characters mean that are  output
          by  %i,  see  the --itemize-changes option in the rsync
          manpage.

          Note that some of the logged output changes when  talk-
          ing  with  older rsync versions.  For instance, deleted
          files were only output as  verbose  messages  prior  to
          rsync 2.6.4.

     timeout
          This parameter  allows  you  to  override  the  clients
          choice  for  I/O  timeout  for  this module. Using this
          parameter you can ensure that rsync wont wait on a dead
          client  forever. The timeout is specified in seconds. A
          value of zero means no timeout and is  the  default.  A
          good  choice  for  anonymous  rsync  daemons may be 600
          (giving a 10 minute timeout).

     refuse options
          This parameter allows you to specify a  space-separated
          list of rsync command line options that will be refused
          by your rsync daemon.  You may specify the full  option
          name,  its  one-letter  abbreviation,  or  a  wild-card
          string that matches  multiple  options.   For  example,
          this  would  refuse --checksum (-c) and all the various
          delete options:

              refuse options = c delete

          The reason the above refuses all delete options is that
          the  options  imply  --delete,  and implied options are
          refused just like explicit options.  As  an  additional
          safety  feature,  the  refusal  of  delete also refuses
          remove-source-files when the daemon is the  sender;  if
          you  want the latter without the former, instead refuse

                    Last change: 21 Dec 2015                   19

rsyncd.conf(5)            FILE FORMATS             rsyncd.conf(5)

          delete-* -- that refuses all the delete  modes  without
          affecting --remove-source-files.

          When an option is refused, the daemon prints  an  error
          message  and  exits.   To  prevent all compression when
          serving files, you can  use  dont  compress  =  *  (see
          below)  instead  of  refuse options = compress to avoid
          returning an error to a client that  requests  compres-
          sion.

     dont compress
          This parameter allows you to select filenames based  on
          wildcard  patterns  that  should not be compressed when
          pulling files from the daemon (no  analogous  parameter
          exists  to  govern  the  pushing of files to a daemon).
          Compression is expensive in terms of CPU usage,  so  it
          is  usually good to not try to compress files that wont
          compress well, such as already compressed files.

          The dont compress  parameter  takes  a  space-separated
          list  of case-insensitive wildcard patterns. Any source
          filename matching one  of  the  patterns  will  not  be
          compressed during transfer.

          See the --skip-compress parameter in the rsync(1)  man-
          page  for  the  list  of  file  suffixes  that  are not
          compressed by default.  Specifying a value for the dont
          compress  parameter changes the default when the daemon
          is the sender.

     pre-xfer exec, post-xfer exec
          You may specify a command to be run before and/or after
          the  transfer.  If the pre-xfer exec command fails, the
          transfer is aborted before it begins.  Any output  from
          the  script  on  stdout  (up  to  several  KB)  will be
          displayed  to  the  user  when  aborting,  but  is  NOT
          displayed  if  the  script returns success.  Any output
          from the script on stderr goes to the  daemons  stderr,
          which  is  typically discarded (though see --no-detatch
          option for a way to see the stderr  output,  which  can
          assist with debugging).

          The following environment variables will be set, though
          some  are  specific  to  the  pre-xfer or the post-xfer
          environment:

                    Last change: 21 Dec 2015                   20

rsyncd.conf(5)            FILE FORMATS             rsyncd.conf(5)

          o    RSYNC_MODULE_NAME: The name of  the  module  being
               accessed.

          o    RSYNC_MODULE_PATH: The  path  configured  for  the
               module.

          o    RSYNC_HOST_ADDR: The accessing hosts IP address.

          o    RSYNC_HOST_NAME: The accessing hosts name.

          o    RSYNC_USER_NAME: The accessing users  name  (empty
               if no user).

          o    RSYNC_PID: A unique number for this transfer.

          o    RSYNC_REQUEST:  (pre-xfer  only)  The  module/path
               info  specified  by  the user.  Note that the user
               can specify multiple source files, so the  request
               can be something like mod/path1 mod/path2, etc.

          o    RSYNC_ARG#: (pre-xfer only) The pre-request  argu-
               ments are set in these numbered values. RSYNC_ARG0
               is always rsyncd, followed  by  the  options  that
               were used in RSYNC_ARG1, and so on.  There will be
               a value of . indicating that the options are  done
               and  the  path args are beginning -- these contain
               similar information  to  RSYNC_REQUEST,  but  with
               values separated and the module name stripped off.

          o    RSYNC_EXIT_STATUS:  (post-xfer  only)  the  server
               sides exit value.  This will be 0 for a successful
               run, a positive value for an error that the server
               generated,  or  a -1 if rsync failed to exit prop-
               erly.  Note that  an  error  that  occurs  on  the
               client  side  does  not  currently get sent to the
               server side, so this is not the final exit  status
               for the whole transfer.

          o    RSYNC_RAW_STATUS: (post-xfer only)  the  raw  exit
               value from waitpid() .

          Even though the commands can be associated with a  par-
          ticular  module,  they are run using the permissions of
          the user that  started  the  daemon  (not  the  modules
          uid/gid setting) without any chroot restrictions.


CONFIG DIRECTIVES

     There are currently two  config  directives  available  that
     allow  a  config  file  to incorporate the contents of other

                    Last change: 21 Dec 2015                   21

rsyncd.conf(5)            FILE FORMATS             rsyncd.conf(5)

     files:  &include and &merge.   Both  allow  a  reference  to
     either a file or a directory.  They differ in how segregated
     the files contents are considered to be.

     The &include directive treats each file  as  more  distinct,
     with  each  one  inheriting the defaults of the parent file,
     starting the  parameter  parsing  as  globals/defaults,  and
     leaving  the  defaults unchanged for the parsing of the rest
     of the parent file.

     The &merge directive, on the other hand,  treats  the  files
     contents  as  if  it  were  simply  inserted in place of the
     directive, and thus  it  can  set  parameters  in  a  module
     started  in  another file, can affect the defaults for other
     files, etc.

     When an &include or &merge directive refers to a  directory,
     it will read in all the *.conf or *.inc files (respectively)
     that are contained inside that directory (without any recur-
     sive scanning), with the files sorted into alpha order.  So,
     if you have  a  directory  named  rsyncd.d  with  the  files
     foo.conf, bar.conf, and baz.conf inside it, this directive:

         &include /path/rsyncd.d

     would be the same as this set of directives:

         &include /path/rsyncd.d/bar.conf
         &include /path/rsyncd.d/baz.conf
         &include /path/rsyncd.d/foo.conf

     except that it adjusts as files are added and  removed  from
     the directory.

     The advantage of the &include  directive  is  that  you  can
     define one or more modules in a separate file without worry-
     ing about unintended side-effects between the self-contained
     module files.

     The advantage of the &merge directive is that you  can  load
     config  snippets  that  can be included into multiple module
     definitions, and you can also set global  values  that  will
     affect connections (such as motd file), or globals that will
     affect other include files.

     For example, this is a useful /etc/rsyncd.conf file:

         port = 873
         log file = /var/log/rsync.log
         pid file = /var/lock/rsync.lock

                    Last change: 21 Dec 2015                   22

rsyncd.conf(5)            FILE FORMATS             rsyncd.conf(5)

         &merge /etc/rsyncd.d
         &include /etc/rsyncd.d

     This would merge any /etc/rsyncd.d/*.inc files  (for  global
     values  that  should  stay  in effect), and then include any
     /etc/rsyncd.d/*.conf files  (defining  modules  without  any
     global-value cross-talk).


AUTHENTICATION STRENGTH

     The authentication protocol used in rsync is a 128  bit  MD4
     based challenge response system. This is fairly weak protec-
     tion, though (with at  least  one  brute-force  hash-finding
     algorithm   publicly  available),  so  if  you  want  really
     top-quality security, then I recommend that  you  run  rsync
     over  ssh.  (Yes, a future version of rsync will switch over
     to a stronger hashing method.)

     Also note that the rsync daemon protocol does not  currently
     provide  any encryption of the data that is transferred over
     the connection. Only authentication is provided. Use ssh  as
     the transport if you want encryption.

     Future versions of rsync may support SSL for better  authen-
     tication  and  encryption,  but that is still being investi-
     gated.


EXAMPLES

     A simple rsyncd.conf file that allow anonymous  rsync  to  a
     ftp area at /home/ftp would be:

     [ftp]
             path = /home/ftp
             comment = ftp export area

     A more sophisticated example would be:

     uid = nobody
     gid = nobody
     use chroot = yes
     max connections = 4
     syslog facility = local5
     pid file = /var/run/rsyncd.pid

     [ftp]
             path = /var/ftp/./pub
             comment = whole ftp area (approx 6.1 GB)

     [sambaftp]
             path = /var/ftp/./pub/samba

                    Last change: 21 Dec 2015                   23

rsyncd.conf(5)            FILE FORMATS             rsyncd.conf(5)

             comment = Samba ftp area (approx 300 MB)

     [rsyncftp]
             path = /var/ftp/./pub/rsync
             comment = rsync ftp area (approx 6 MB)

     [sambawww]
             path = /public_html/samba
             comment = Samba WWW pages (approx 240 MB)

     [cvs]
             path = /data/cvs
             comment = CVS repository (requires authentication)
             auth users = tridge, susan
             secrets file = /etc/rsyncd.secrets

     The /etc/rsyncd.secrets file would look something like this:

          tridge:mypass
          susan:herpass


FILES

     /etc/rsyncd.conf or rsyncd.conf


SEE ALSO

     rsync(1)


DIAGNOSTICS


BUGS

     Please report bugs! The rsync bug tracking system is  online
     at http://rsync.samba.org/


VERSION

     This man page is current for version 3.1.2 of rsync.


CREDITS

     rsync is distributed under the GNU General  Public  License.
     See the file COPYING for details.

     The     primary     ftp     site      for      rsync      is
     ftp://rsync.samba.org/pub/rsync.

     A WEB site is available at http://rsync.samba.org/

     We would be delighted to hear from you if you like this pro-
     gram.

     This program uses the zlib compression  library  written  by
     Jean-loup Gailly and Mark Adler.

                    Last change: 21 Dec 2015                   24

rsyncd.conf(5)            FILE FORMATS             rsyncd.conf(5)


THANKS

     Thanks to Warren Stanley for his original idea and patch for
     the  rsync  daemon.  Thanks to Karsten Thygesen for his many
     suggestions and documentation!


AUTHOR

     rsync was written by Andrew  Tridgell  and  Paul  Mackerras.
     Many people have later contributed to it.

     Mailing lists for support and development are  available  at
     http://lists.samba.org

                    Last change: 21 Dec 2015                   25


Man(1) output converted with man2html