]>
Commit | Line | Data |
---|---|---|
53fae556 WD |
1 | # NAME |
2 | ||
3 | rsync-ssl - a helper script for connecting to an ssl rsync daemon | |
4 | ||
5 | # SYNOPSIS | |
6 | ||
7 | ``` | |
00ec415a | 8 | rsync-ssl [--type=SSL_TYPE] RSYNC_ARGS |
53fae556 WD |
9 | ``` |
10 | ||
11 | # DESCRIPTION | |
12 | ||
13 | The rsync-ssl script helps you to run an rsync copy to/from an rsync daemon | |
14 | that requires ssl connections. | |
15 | ||
7dc9431f WD |
16 | The script requires that you specify an rsync-daemon arg in the style of either |
17 | `hostname::` (with 2 colons) or `rsync://hostname/`. The default port used for | |
18 | connecting is 874 (one higher than the normal 873) unless overridden in the | |
19 | environment. You can specify an overriding port via `--port` or by including | |
20 | it in the normal spot in the URL format, though both of those require your | |
21 | rsync version to be at least 3.2.0. | |
22 | ||
00ec415a WD |
23 | # OPTIONS |
24 | ||
25 | If the **first** arg is a `--type=SSL_TYPE` option, the script will only use | |
26 | that particular program to open an ssl connection instead of trying to find an | |
628dcceb | 27 | openssl or stunnel executable via a simple heuristic (assuming that the |
53fae556 | 28 | `RSYNC_SSL_TYPE` environment variable is not set as well -- see below). This |
00ec415a | 29 | option must specify one of `openssl` or `stunnel`. The equal sign is |
53fae556 WD |
30 | required for this particular option. |
31 | ||
32 | All the other options are passed through to the rsync command, so consult the | |
7dc9431f | 33 | **rsync**(1) manpage for more information on how it works. |
53fae556 | 34 | |
53fae556 WD |
35 | # ENVIRONMENT VARIABLES |
36 | ||
37 | The ssl helper scripts are affected by the following environment variables: | |
38 | ||
39 | 0. `RSYNC_SSL_TYPE` Specifies the program type that should be used to open the | |
00ec415a WD |
40 | ssl connection. It must be one of `openssl` or `stunnel`. The |
41 | `--type=SSL_TYPE` option overrides this, when specified. | |
53fae556 WD |
42 | 0. `RSYNC_SSL_PORT` If specified, the value is the port number that is used as |
43 | the default when the user does not specify a port in their rsync command. | |
44 | When not specified, the default port number is 874. (Note that older rsync | |
45 | versions (prior to 3.2.0) did not communicate an overriding port number | |
46 | value to the helper script.) | |
47 | 0. `RSYNC_SSL_CERT` If specified, the value is a filename that contains a | |
48 | certificate to use for the connection. | |
33379302 F |
49 | 0. `RSYNC_SSL_KEY` If specified, the value is a filename that contains a |
50 | key for the provided certificate to use for the connection. | |
53fae556 WD |
51 | 0. `RSYNC_SSL_CA_CERT` If specified, the value is a filename that contains a |
52 | certificate authority certificate that is used to validate the connection. | |
53fae556 WD |
53 | 0. `RSYNC_SSL_OPENSSL` Specifies the openssl executable to run when the |
54 | connection type is set to openssl. If unspecified, the $PATH is searched | |
55 | for "openssl". | |
6273153c WD |
56 | 0. `RSYNC_SSL_GNUTLS` Specifies the gnutls-cli executable to run when the |
57 | connection type is set to gnutls. If unspecified, the $PATH is searched | |
58 | for "gnutls-cli". | |
628dcceb WD |
59 | 0. `RSYNC_SSL_STUNNEL` Specifies the stunnel executable to run when the |
60 | connection type is set to stunnel. If unspecified, the $PATH is searched | |
61 | first for "stunnel4" and then for "stunnel". | |
00ec415a | 62 | |
53fae556 WD |
63 | # EXAMPLES |
64 | ||
7dc9431f WD |
65 | > rsync-ssl -aiv example.com::mod/ dest |
66 | ||
67 | > rsync-ssl --type=openssl -aiv example.com::mod/ dest | |
68 | ||
69 | > rsync-ssl -aiv --port 9874 example.com::mod/ dest | |
53fae556 | 70 | |
7dc9431f | 71 | > rsync-ssl -aiv rsync://example.com:9874/mod/ dest |
53fae556 | 72 | |
53fae556 WD |
73 | # SEE ALSO |
74 | ||
75 | **rsync**(1), **rsyncd.conf**(5) | |
76 | ||
628dcceb WD |
77 | # CAVEATS |
78 | ||
79 | Note that using an stunnel connection requires at least version 4 of stunnel, | |
80 | which should be the case on modern systems. Also, it does not verify a | |
81 | connection against the CA certificate collection, so it only encrypts the | |
82 | connection without any cert validation unless you have specified the | |
83 | certificate environment options. | |
84 | ||
6273153c WD |
85 | This script also supports a `--type=gnutls` option, but at the time of this |
86 | release the gnutls-cli command was dropping output, making it unusable. If | |
249e28c7 WD |
87 | that bug has been fixed in your version, feel free to put gnutls into an |
88 | exported RSYNC_SSL_TYPE environment variable to make its use the default. | |
6273153c | 89 | |
53fae556 WD |
90 | # BUGS |
91 | ||
b0ab07cd | 92 | Please report bugs! See the web site at <https://rsync.samba.org/>. |
53fae556 WD |
93 | |
94 | # VERSION | |
95 | ||
96 | This man page is current for version @VERSION@ of rsync. | |
97 | ||
98 | # CREDITS | |
99 | ||
100 | rsync is distributed under the GNU General Public License. See the file | |
101 | COPYING for details. | |
102 | ||
b0ab07cd | 103 | A web site is available at <https://rsync.samba.org/>. The site includes an |
53fae556 WD |
104 | FAQ-O-Matic which may cover questions unanswered by this manual page. |
105 | ||
106 | # AUTHOR | |
107 | ||
108 | This manpage was written by Wayne Davison. | |
109 | ||
110 | Mailing lists for support and development are available at | |
b0ab07cd | 111 | <https://lists.samba.org/>. |