source: networking/netprogs/rsync-systemd.xml@ 4b422698

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY rsync-download-http "http://samba.org/ftp/rsync/src/rsync-&rsync-version;.tar.gz">
  <!ENTITY rsync-download-ftp  "ftp://ftp.samba.org/pub/rsync/src/rsync-&rsync-version;.tar.gz">
  <!ENTITY rsync-md5sum        "43bd6676f0b404326eee2d63be3cdcfe">
  <!ENTITY rsync-size          "869 KB">
  <!ENTITY rsync-buildsize     "9.0 MB">
  <!ENTITY rsync-time          "0.3 SBU">
]>

<sect1 id="rsync" xreflabel="rsync-&rsync-version;">
  <?dbhtml filename="rsync.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>rsync-&rsync-version;</title>

  <indexterm zone="rsync">
    <primary sortas="a-rsync">rsync</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to rsync</title>

    <para>The <application>rsync</application> package contains the
    <command>rsync</command> utility. This is useful for synchronizing large
    file archives over a network.</para>

    &lfs75_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Download (HTTP): <ulink url="&rsync-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Download (FTP): <ulink url="&rsync-download-ftp;"/></para>
      </listitem>
      <listitem>
        <para>Download MD5 sum: &rsync-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size: &rsync-size;</para>
      </listitem>
      <listitem>
        <para>Estimated disk space required: &rsync-buildsize;</para>
      </listitem>
      <listitem>
        <para>Estimated build time: &rsync-time;</para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">rsync Dependencies</bridgehead>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="popt"/>
    </para>

    <para condition="html" role="usernotes">User Notes:
    <ulink url="&blfs-wiki;/rsync"/></para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of rsync</title>

    <para>For security reasons, running the <application>rsync</application>
    server as an unprivileged user and group is encouraged. If you intend to
    run <command>rsync</command> as a daemon, create the
    <systemitem class="username">rsyncd</systemitem> user and group
    with the following commands issued by the
    <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>groupadd -g 48 rsyncd &amp;&amp;
useradd -c "rsyncd Daemon" -d /home/rsync -g rsyncd \
    -s /bin/false -u 48 rsyncd</userinput></screen>

    <para>Install <application>rsync</application> by running the following
    commands:</para>

<screen><userinput>./configure --prefix=/usr --without-included-zlib &amp;&amp;
make</userinput></screen>

    <para>If you have <xref linkend="doxygen"/> installed and wish to
    build HTML API documentation, issue <command>doxygen</command>.</para>

    <para>To test the results, issue: <command>make check</command>.</para>

    <para>Now, as the <systemitem class="username">root</systemitem> user:</para>

<screen role='root'><userinput>make install</userinput></screen>

    <para>If you built the documentation, install it using the following
    commands as the <systemitem class="username">root</systemitem> user:</para>

<screen role='root'><userinput>install -v -m755 -d          /usr/share/doc/rsync-&rsync-version;/api &amp;&amp;
install -v -m644 dox/html/*  /usr/share/doc/rsync-&rsync-version;/api</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para>
      <parameter>--without-included-zlib</parameter>: This switch enables
      compilation with system-installed zlib library.
    </para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring rsync</title>

    <sect3 id="rsync-config">
      <title>Config Files</title>

      <para><filename>/etc/rsyncd.conf</filename></para>

      <indexterm zone="rsync rsync-config">
        <primary sortas="e-etc-rsyncd.conf">/etc/rsyncd.conf</primary>
      </indexterm>

    </sect3>

    <sect3>
      <title>Configuration Information</title>

      <para>For client access to remote files, you may need to install the
      <xref linkend="openssh"/> package to connect to the remote server.</para>

      <para>This is a simple download-only configuration to set up running
      <command>rsync</command> as a server. See the rsyncd.conf(5)
      man-page for additional options (i.e., user authentication).</para>

<screen role="root"><userinput>cat &gt; /etc/rsyncd.conf &lt;&lt; "EOF"
<literal># This is a basic rsync configuration file
# It exports a single module without user authentication.

motd file = /home/rsync/welcome.msg
use chroot = yes

[localhost]
    path = /home/rsync
    comment = Default rsync module
    read only = yes
    list = yes
    uid = rsyncd
    gid = rsyncd
</literal>
EOF</userinput></screen>

    <para>You can find additional configuration information and general
    documentation about <command>rsync</command> at
    <ulink url="http://rsync.samba.org/documentation.html"/>.</para>

    </sect3>

    <sect3 id="rsync-init">
      <title>Systemd Units</title>

      <para>Note that you only want to start the
      <application>rsync</application> server if you want to provide an
      <application>rsync</application> archive on your local machine.
      You don't need this unit to run the
      <application>rsync</application> client.</para>

      <para>
        To start the <command>rsync</command> daemon at boot,
        install the systemd units from the <xref linkend="bootscripts"/>
        package by running the following command as the
        <systemitem class="username">root</systemitem> user:
      </para>

<screen role="root"><userinput>make install-rsyncd</userinput></screen>

      <note>
        <para>
          This package comes with two types of units: A service file and a socket file.
          The service file will start rsync daemon once at boot and it will keep running until the
          system shuts down. The socket file will make systemd listen on rsync port (Default 873, needs
          to be edited for anything else) and will start rsync daemon when something tries to connect
          to that port and stop the daemon when the connection is terminated. This is
          called socket activation.

          By default, the first method is used - rsync daemon is started at boot and stopped at shutdown.
          If the socket method is desired, you need to run as the
          <systemitem class="username">root</systemitem> user:

<screen role="root"><userinput>systemctl stop rsyncd &amp;&amp;
systemctl disable rsyncd &amp;&amp;
systemctl enable rsyncd.socket &amp;&amp;
systemctl start rsyncd.socket</userinput></screen>

          Note that socket method is only useful for remote backups. For local backups you'll need the
          service method.
        </para>
      </note>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Program</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>rsync</seg>
        <seg>None</seg>
        <seg>Optionally, /usr/share/doc/rsync-&rsync-version;</seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="rsync-prog">
        <term><command>rsync</command></term>
        <listitem>
          <para>is a replacement for <command>rcp</command> (and
          <command>scp</command>) that has many more features. It uses the
          <quote>rsync algorithm</quote> which provides a very fast method of
          syncing remote files. It does this by sending just the differences
          in the files across the link, without requiring that both sets of
          files are present at one end of the link beforehand.</para>
          <indexterm zone="rsync rsync-prog">
            <primary sortas="b-rsync">rsync</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>