89
90
config file in which case the supplied value will override the
90
91
default for that parameter.
93
You may use references to environment variables in the values of parameters.
94
String parameters will have %VAR% references expanded as late as possible (when
95
the string is used in the program), allowing for the use of variables that
96
rsync sets at connection time, such as RSYNC_USER_NAME. Non\-string parameters
97
(such as true/false settings) are expanded when read from the config file. If
98
a variable does not exist in the environment, or if a sequence of characters is
99
not a valid reference (such as an un\-paired percent sign), the raw characters
100
are passed through unchanged. This helps with backward compatibility and
101
safety (e.g. expanding a non\-existent %VAR% to an empty string in a path could
102
result in a very unsafe path). The safest way to insert a literal % into a
92
105
.IP "\fBmotd file\fP"
93
106
This parameter allows you to specify a
94
107
\(dq\&message of the day\(dq\& to display to clients on each connect. This
95
108
usually contains site information and any legal notices. The default
110
This can be overridden by the \fB\-\-dparam=motdfile=FILE\fP
111
command\-line option when starting the daemon.
98
113
.IP "\fBpid file\fP"
99
114
This parameter tells the rsync daemon to write
100
115
its process ID to that file. If the file already exists, the rsync
101
116
daemon will abort rather than overwrite the file.
117
This can be overridden by the \fB\-\-dparam=pidfile=FILE\fP
118
command\-line option when starting the daemon.
104
121
You can override the default port the daemon will listen on
338
381
default is for this parameter to be disabled.
341
This parameter determines if this module should be
342
listed when the client asks for a listing of available modules. By
343
setting this to false you can create hidden modules. The default is
344
for modules to be listable.
384
This parameter determines whether this module is
385
listed when the client asks for a listing of available modules. In addition,
386
if this is false, the daemon will pretend the module does not exist
387
when a client denied by \(dq\&hosts allow\(dq\& or \(dq\&hosts deny\(dq\& attempts to access it.
388
Realize that if \(dq\&reverse lookup\(dq\& is disabled globally but enabled for the
389
module, the resulting reverse lookup to a potentially client\-controlled DNS
390
server may still reveal to the client that it hit an existing module.
391
The default is for modules to be listable.
347
394
This parameter specifies the user name or user ID that
348
395
file transfers to and from that module should take place as when the daemon
349
396
was run as root. In combination with the \(dq\&gid\(dq\& parameter this determines what
350
file permissions are available. The default is uid \-2, which is normally
351
the user \(dq\&nobody\(dq\&.
397
file permissions are available. The default when run by a super\-user is to
398
switch to the system\(cq\&s \(dq\&nobody\(dq\& user. The default for a non\-super\-user is to
399
not try to change the user. See also the \(dq\&gid\(dq\& parameter.
401
The RSYNC_USER_NAME environment variable may be used to request that rsync run
402
as the authorizing user. For example, if you want a rsync to run as the same
403
user that was received for the rsync authentication, this setup is useful:
406
uid = %RSYNC_USER_NAME%
354
This parameter specifies the group name or group ID that
355
file transfers to and from that module should take place as when the daemon
356
was run as root. This complements the \(dq\&uid\(dq\& parameter. The default is gid \-2,
357
which is normally the group \(dq\&nobody\(dq\&.
412
This parameter specifies one or more group names/IDs that will be
413
used when accessing the module. The first one will be the default group, and
414
any extra ones be set as supplemental groups. You may also specify a \(dq\&*\(dq\& as
415
the first gid in the list, which will be replaced by all the normal groups for
416
the transfer\(cq\&s user (see \(dq\&uid\(dq\&). The default when run by a super\-user is to
417
switch to your OS\(cq\&s \(dq\&nobody\(dq\& (or perhaps \(dq\&nogroup\(dq\&) group with no other
418
supplementary groups. The default for a non\-super\-user is to not change any
419
group attributes (and indeed, your OS may not allow a non\-super\-user to try to
420
change their group settings).
359
422
.IP "\fBfake super\fP"
360
423
Setting \(dq\&fake super = yes\(dq\& for a module causes the
438
501
manpage for information on the format of this string.
440
503
.IP "\fBauth users\fP"
441
This parameter specifies a comma and
442
space\-separated list of usernames that will be allowed to connect to
504
This parameter specifies a comma and/or space\-separated
505
list of authorization rules. In its simplest form, you list the usernames
506
that will be allowed to connect to
443
507
this module. The usernames do not need to exist on the local
444
system. The usernames may also contain shell wildcard characters. If
508
system. The rules may contain shell wildcard characters that will be matched
509
against the username provided by the client for authentication. If
445
510
\(dq\&auth users\(dq\& is set then the client will be challenged to supply a
446
511
username and password to connect to the module. A challenge response
447
512
authentication protocol is used for this exchange. The plain text
449
514
\(dq\&secrets file\(dq\& parameter. The default is for all users to be able to
450
515
connect without a password (this is called \(dq\&anonymous rsync\(dq\&).
517
In addition to username matching, you can specify groupname matching via a \(cq\&@\(cq\&
518
prefix. When using groupname matching, the authenticating username must be a
519
real user on the system, or it will be assumed to be a member of no groups.
520
For example, specifying \(dq\&@rsync\(dq\& will match the authenticating user if the
521
named user is a member of the rsync group.
523
Finally, options may be specified after a colon (:). The options allow you to
524
\(dq\&deny\(dq\& a user or a group, set the access to \(dq\&ro\(dq\& (read\-only), or set the access
525
to \(dq\&rw\(dq\& (read/write). Setting an auth\-rule\-specific ro/rw setting overrides
526
the module\(cq\&s \(dq\&read only\(dq\& setting.
528
Be sure to put the rules in the order you want them to be matched, because the
529
checking stops at the first matching user or group, and that is the only auth
530
that is checked. For example:
533
auth users = joe:deny @guest:deny admin:rw @rsync:ro susan joe sam
537
In the above rule, user joe will be denied access no matter what. Any user
538
that is in the group \(dq\&guest\(dq\& is also denied access. The user \(dq\&admin\(dq\& gets
539
access in read/write mode, but only if the admin user is not in group \(dq\&guest\(dq\&
540
(because the admin user\-matching rule would never be reached if the user is in
541
group \(dq\&guest\(dq\&). Any other user who is in group \(dq\&rsync\(dq\& will get read\-only
542
access. Finally, users susan, joe, and sam get the ro/rw setting of the
543
module, but only if the user didn\(cq\&t match an earlier group\-matching rule.
545
See the description of the secrets file for how you can have per\-user passwords
546
as well as per\-group passwords. It also explains how a user can authenticate
547
using their user password or (when applicable) a group password, depending on
548
what rule is being authenticated.
452
550
See also the section entitled \(dq\&USING RSYNC\-DAEMON FEATURES VIA A REMOTE
453
551
SHELL CONNECTION\(dq\& in \fBrsync\fP(1) for information on how handle an
454
552
rsyncd.conf\-level username that differs from the remote\-shell\-level
455
553
username when using a remote shell to connect to an rsync daemon.
457
555
.IP "\fBsecrets file\fP"
458
This parameter specifies the name of
459
a file that contains the username:password pairs used for
460
authenticating this module. This file is only consulted if the \(dq\&auth
461
users\(dq\& parameter is specified. The file is line based and contains
462
username:password pairs separated by a single colon. Any line starting
463
with a hash (#) is considered a comment and is skipped. The passwords
464
can contain any characters but be warned that many operating systems
465
limit the length of passwords that can be typed at the client end, so
466
you may find that passwords longer than 8 characters don\(cq\&t work.
556
This parameter specifies the name of a file that contains
557
the username:password and/or @groupname:password pairs used for authenticating
558
this module. This file is only consulted if the \(dq\&auth users\(dq\& parameter is
559
specified. The file is line\-based and contains one name:password pair per
560
line. Any line has a hash (#) as the very first character on the line is
561
considered a comment and is skipped. The passwords can contain any characters
562
but be warned that many operating systems limit the length of passwords that
563
can be typed at the client end, so you may find that passwords longer than 8
564
characters don\(cq\&t work.
566
The use of group\-specific lines are only relevant when the module is being
567
authorized using a matching \(dq\&@groupname\(dq\& rule. When that happens, the user
568
can be authorized via either their \(dq\&username:password\(dq\& line or the
569
\(dq\&@groupname:password\(dq\& line for the group that triggered the authentication.
571
It is up to you what kind of password entries you want to include, either
572
users, groups, or both. The use of group rules in \(dq\&auth users\(dq\& does not
573
require that you specify a group password if you do not want to use shared
468
576
There is no default for the \(dq\&secrets file\(dq\& parameter, you must choose a name
469
577
(such as \f(CW/etc/rsyncd.secrets\fP). The file must normally not be readable
470
by \(dq\&other\(dq\&; see \(dq\&strict modes\(dq\&.
578
by \(dq\&other\(dq\&; see \(dq\&strict modes\(dq\&. If the file is not found or is rejected, no
579
logins for a \(dq\&user auth\(dq\& module will be possible.
472
581
.IP "\fBstrict modes\fP"
473
582
This parameter determines whether or not
500
609
or similar for IPv6, e.g. ffff:ffff:ffff:ffff:: instead of /64. All IP
501
610
addresses which match the masked IP address will be allowed in.
503
a hostname. The hostname as determined by a reverse lookup will
504
be matched (case insensitive) against the pattern. Only an exact
612
a hostname pattern using wildcards. If the hostname of the connecting IP
613
(as determined by a reverse lookup) matches the wildcarded name (using the
614
same rules as normal unix filename matching), the client is allowed in. This
615
only works if \(dq\&reverse lookup\(dq\& is enabled (the default).
507
a hostname pattern using wildcards. These are matched using the
508
same rules as normal unix filename matching. If the pattern matches
509
then the client is allowed in.
617
a hostname. A plain hostname is matched against the reverse DNS of the
618
connecting IP (if \(dq\&reverse lookup\(dq\& is enabled), and/or the IP of the given
619
hostname is matched against the connecting IP (if \(dq\&forward lookup\(dq\& is
620
enabled, as it is by default). Any match will be allowed in.
541
652
The default is no \(dq\&hosts deny\(dq\& parameter, which means all hosts can connect.
654
.IP "\fBreverse lookup\fP"
655
Controls whether the daemon performs a reverse lookup
656
on the client\(cq\&s IP address to determine its hostname, which is used for
657
\(dq\&hosts allow\(dq\&/\(dq\&hosts deny\(dq\& checks and the \(dq\&%h\(dq\& log escape. This is enabled by
658
default, but you may wish to disable it to save time if you know the lookup will
659
not return a useful result, in which case the daemon will use the name
660
\(dq\&UNDETERMINED\(dq\& instead.
662
If this parameter is enabled globally (even by default), rsync performs the
663
lookup as soon as a client connects, so disabling it for a module will not
664
avoid the lookup. Thus, you probably want to disable it globally and then
665
enable it for modules that need the information.
667
.IP "\fBforward lookup\fP"
668
Controls whether the daemon performs a forward lookup
669
on any hostname specified in an hosts allow/deny setting. By default this is
670
enabled, allowing the use of an explicit hostname that would not be returned
671
by reverse DNS of the connecting IP.
543
673
.IP "\fBignore errors\fP"
544
674
This parameter tells rsyncd to
545
675
ignore I/O errors on the daemon when deciding whether to run the delete
570
700
sequences prefixed with a percent (%) character. An optional numeric
571
701
field width may also be specified between the percent and the escape
572
702
letter (e.g. \(dq\&\fB%\-50n %8l %07p\fP\(dq\&).
703
In addition, one or more apostrophes may be specified prior to a numerical
704
escape to indicate that the numerical value should be made more human\-readable.
705
The 3 supported levels are the same as for the \fB\-\-human\-readable\fP
706
command\-line option, though the default is for human\-readability to be off.
707
Each added apostrophe increases the level (e.g. \(dq\&\fB%'\&'\&l %'\&b %f\fP\(dq\&).
574
709
The default log format is \(dq\&%o %h [%a] %m (%u) %f %l\(dq\&, and a \(dq\&%t [%p] \(dq\&
575
710
is always prefixed when using the \(dq\&log file\(dq\& parameter.
684
821
.IP "\fBpre\-xfer exec\fP, \fBpost\-xfer exec\fP"
685
822
You may specify a command to be run
686
823
before and/or after the transfer. If the \fBpre\-xfer exec\fP command fails, the
687
transfer is aborted before it begins.
824
transfer is aborted before it begins. Any output from the script on stdout (up
825
to several KB) will be displayed to the user when aborting, but is NOT
826
displayed if the script returns success. Any output from the script on stderr
827
goes to the daemon\(cq\&s stderr, which is typically discarded (though see
828
\-\-no\-detatch option for a way to see the stderr output, which can assist with
689
831
The following environment variables will be set, though some are
690
832
specific to the pre\-xfer or the post\-xfer environment:
704
846
\fBRSYNC_PID\fP: A unique number for this transfer.
706
848
\fBRSYNC_REQUEST\fP: (pre\-xfer only) The module/path info specified
707
by the user (note that the user can specify multiple source files,
708
so the request can be something like \(dq\&mod/path1 mod/path2\(dq\&, etc.).
849
by the user. Note that the user can specify multiple source files,
850
so the request can be something like \(dq\&mod/path1 mod/path2\(dq\&, etc.
710
852
\fBRSYNC_ARG#\fP: (pre\-xfer only) The pre\-request arguments are set
711
in these numbered values. RSYNC_ARG0 is always \(dq\&rsyncd\(dq\&, and the last
712
value contains a single period.
853
in these numbered values. RSYNC_ARG0 is always \(dq\&rsyncd\(dq\&, followed by
854
the options that were used in RSYNC_ARG1, and so on. There will be a
855
value of \(dq\&.\(dq\& indicating that the options are done and the path args
856
are beginning \-\- these contain similar information to RSYNC_REQUEST,
857
but with values separated and the module name stripped off.
714
859
\fBRSYNC_EXIT_STATUS\fP: (post\-xfer only) the server side\(cq\&s exit value.
715
860
This will be 0 for a successful run, a positive value for an error that the
727
872
are run using the permissions of the user that started the daemon (not the
728
873
module\(cq\&s uid/gid setting) without any chroot restrictions.
875
.SH "CONFIG DIRECTIVES"
878
There are currently two config directives available that allow a config file to
879
incorporate the contents of other files: \fB&include\fP and \fB&merge\fP. Both
880
allow a reference to either a file or a directory. They differ in how
881
segregated the file\(cq\&s contents are considered to be.
883
The \fB&include\fP directive treats each file as more distinct, with each one
884
inheriting the defaults of the parent file, starting the parameter parsing
885
as globals/defaults, and leaving the defaults unchanged for the parsing of
886
the rest of the parent file.
888
The \fB&merge\fP directive, on the other hand, treats the file\(cq\&s contents as
889
if it were simply inserted in place of the directive, and thus it can set
890
parameters in a module started in another file, can affect the defaults for
893
When an \fB&include\fP or \fB&merge\fP directive refers to a directory, it will read
894
in all the \fB*.conf\fP or \fB*.inc\fP files (respectively) that are contained inside
895
that directory (without any
896
recursive scanning), with the files sorted into alpha order. So, if you have a
897
directory named \(dq\&rsyncd.d\(dq\& with the files \(dq\&foo.conf\(dq\&, \(dq\&bar.conf\(dq\&, and
898
\(dq\&baz.conf\(dq\& inside it, this directive:
901
&include /path/rsyncd.d
905
would be the same as this set of directives:
908
&include /path/rsyncd.d/bar.conf
909
&include /path/rsyncd.d/baz.conf
910
&include /path/rsyncd.d/foo.conf
914
except that it adjusts as files are added and removed from the directory.
916
The advantage of the \fB&include\fP directive is that you can define one or more
917
modules in a separate file without worrying about unintended side\-effects
918
between the self\-contained module files.
920
The advantage of the \fB&merge\fP directive is that you can load config snippets
921
that can be included into multiple module definitions, and you can also set
922
global values that will affect connections (such as \fBmotd file\fP), or globals
923
that will affect other include files.
925
For example, this is a useful /etc/rsyncd.conf file:
929
log file = /var/log/rsync.log
930
pid file = /var/lock/rsync.lock
933
&include /etc/rsyncd.d
937
This would merge any /etc/rsyncd.d/*.inc files (for global values that should
938
stay in effect), and then include any /etc/rsyncd.d/*.conf files (defining
939
modules without any global\-value cross\-talk).
730
941
.SH "AUTHENTICATION STRENGTH"