source: networking/netprogs/rsync.xml@ c463c87

<?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-systemd">
      <title>Systemd Unit File</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 script to run the
      <application>rsync</application> client.
      The systemd-units package provides two types of units: A service file and 
      a socket file. The service file will start rsyncd daemon once at boot 
      and it will keep running until the system shuts down. The socket 
      file will make systemd listen to sshd port (Default 873) and will start rsyncd 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 - rsyncd daemon is started at boot and stopped at shutdown.
      </para>

      <para>To install the systemd unit file init included in the
      <xref linkend="systemd-units"/> package run the following command
       as the <systemitem class="username">root</systemitem> 
       user:
      </para>

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

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

      <para>
       If the socket method is desired, you need to run the following commands as the
       <systemitem class="username">root</systemitem> 
        user:
      </para>

<screen role="root"><userinput>
systemctl stop rsyncd &amp;&amp; 
systemctl disable rsyncd.service &amp;&amp; 
systemctl enable rsyncd.socket &amp;&amp;
systemctl start rsync.socket</userinput></screen>
    </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>