1 files changed, 144 insertions, 0 deletions
diff --git a/rsync-ssl.1 b/rsync-ssl.1
new file mode 100644
index 0000000..c7f5ad1
--- /dev/null
+++ b/rsync-ssl.1
@@ -0,0 +1,144 @@
+.TH "rsync-ssl" "1" "20 Oct 2022" "rsync-ssl from rsync 3.2.7" "User Commands"
+.\" prefix=/usr
+.P
+.SH "NAME"
+.P
+rsync-ssl \- a helper script for connecting to an ssl rsync daemon
+.P
+.SH "SYNOPSIS"
+.P
+.nf
+rsync-ssl [--type=SSL_TYPE] RSYNC_ARGS
+.fi
+.P
+The online version of this manpage (that includes cross-linking of topics)
+is available at https://download.samba.org/pub/rsync/rsync-ssl.1.
+.P
+.SH "DESCRIPTION"
+.P
+The rsync-ssl script helps you to run an rsync copy to/from an rsync daemon
+that requires ssl connections.
+.P
+The script requires that you specify an rsync-daemon arg in the style of either
+\fBhostname::\fP (with 2 colons) or \fBrsync://hostname/\fP.  The default port used for
+connecting is 874 (one higher than the normal 873) unless overridden in the
+environment.  You can specify an overriding port via \fB\-\-port\fP or by including
+it in the normal spot in the URL format, though both of those require your
+rsync version to be at least 3.2.0.
+.P
+.SH "OPTIONS"
+.P
+If the \fBfirst\fP arg is a \fB\-\-type=SSL_TYPE\fP option, the script will only use
+that particular program to open an ssl connection instead of trying to find an
+openssl or stunnel executable via a simple heuristic (assuming that the
+\fBRSYNC_SSL_TYPE\fP environment variable is not set as well\ \-\- see below).  This
+option must specify one of \fBopenssl\fP or \fBstunnel\fP.  The equal sign is
+required for this particular option.
+.P
+All the other options are passed through to the rsync command, so consult the
+\fBrsync\fP(1) manpage for more information on how it works.
+.P
+.SH "ENVIRONMENT VARIABLES"
+.P
+The ssl helper scripts are affected by the following environment variables:
+.P
+.IP "\fBRSYNC_SSL_TYPE\fP"
+Specifies the program type that should be used to open the ssl connection.
+It must be one of \fBopenssl\fP or \fBstunnel\fP.  The \fB\-\-type=SSL_TYPE\fP option
+overrides this, when specified.
+.IP "\fBRSYNC_SSL_PORT\fP"
+If specified, the value is the port number that is used as the default when
+the user does not specify a port in their rsync command.  When not
+specified, the default port number is 874.  (Note that older rsync versions
+(prior to 3.2.0) did not communicate an overriding port number value to the
+helper script.)
+.IP "\fBRSYNC_SSL_CERT\fP"
+If specified, the value is a filename that contains a certificate to use
+for the connection.
+.IP "\fBRSYNC_SSL_KEY\fP"
+If specified, the value is a filename that contains a key for the provided
+certificate to use for the connection.
+.IP "\fBRSYNC_SSL_CA_CERT\fP"
+If specified, the value is a filename that contains a certificate authority
+certificate that is used to validate the connection.
+.IP "\fBRSYNC_SSL_OPENSSL\fP"
+Specifies the openssl executable to run when the connection type is set to
+openssl.  If unspecified, the $PATH is searched for "openssl".
+.IP "\fBRSYNC_SSL_GNUTLS\fP"
+Specifies the gnutls-cli executable to run when the connection type is set
+to gnutls.  If unspecified, the $PATH is searched for "gnutls-cli".
+.IP "\fBRSYNC_SSL_STUNNEL\fP"
+Specifies the stunnel executable to run when the connection type is set to
+stunnel.  If unspecified, the $PATH is searched first for "stunnel4" and
+then for "stunnel".
+.P
+.SH "EXAMPLES"
+.RS 4
+.P
+.nf
+rsync-ssl -aiv example.com::mod/ dest
+.fi
+.RE
+.RS 4
+.P
+.nf
+rsync-ssl --type=openssl -aiv example.com::mod/ dest
+.fi
+.RE
+.RS 4
+.P
+.nf
+rsync-ssl -aiv --port 9874 example.com::mod/ dest
+.fi
+.RE
+.RS 4
+.P
+.nf
+rsync-ssl -aiv rsync://example.com:9874/mod/ dest
+.fi
+.RE
+.P
+.SH "THE SERVER SIDE"
+.P
+For help setting up an SSL/TLS supporting rsync, see the instructions in
+rsyncd.conf.
+.P
+.SH "SEE ALSO"
+.P
+\fBrsync\fP(1), \fBrsyncd.conf\fP(5)
+.P
+.SH "CAVEATS"
+.P
+Note that using an stunnel connection requires at least version 4 of stunnel,
+which should be the case on modern systems.  Also, it does not verify a
+connection against the CA certificate collection, so it only encrypts the
+connection without any cert validation unless you have specified the
+certificate environment options.
+.P
+This script also supports a \fB\-\-type=gnutls\fP option, but at the time of this
+release the gnutls-cli command was dropping output, making it unusable.  If
+that bug has been fixed in your version, feel free to put gnutls into an
+exported RSYNC_SSL_TYPE environment variable to make its use the default.
+.P
+.SH "BUGS"
+.P
+Please report bugs! See the web site at https://rsync.samba.org/.
+.P
+.SH "VERSION"
+.P
+This manpage is current for version 3.2.7 of rsync.
+.P
+.SH "CREDITS"
+.P
+Rsync is distributed under the GNU General Public License.  See the file
+COPYING for details.
+.P
+A web site is available at https://rsync.samba.org/.  The site includes an
+FAQ-O-Matic which may cover questions unanswered by this manual page.
+.P
+.SH "AUTHOR"
+.P
+This manpage was written by Wayne Davison.
+.P
+Mailing lists for support and development are available at
+https://lists.samba.org/.