source: server/other/rsync.xml@ fdf798a6

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

  <!ENTITY rsync-download-http "http://rsync.samba.org/ftp/rsync/rsync-&rsync-version;.tar.gz">
  <!ENTITY rsync-download-ftp "ftp://ftp.samba.org/pub/rsync/rsync-&rsync-version;.tar.gz">
  <!ENTITY rsync-md5sum "3691cdf1540d0649ba679edce6bae8fc">
  <!ENTITY rsync-size "643 KB">
  <!ENTITY rsync-buildsize "12 MB">
  <!ENTITY rsync-time "0.2 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>

    <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">Optional</bridgehead>
    <para><xref linkend="popt"/> and 
    <xref linkend="docbook-utils"/></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 &amp;&amp;
make</userinput></screen>

    <para>If you have DocBook-Utils installed and wish to build HTML
    documentation, issue:</para>

<screen><userinput>cd doc &amp;&amp;
docbook2html rsync.sgml &amp;&amp;
cd ..</userinput></screen>

    <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 HTML 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; &amp;&amp;
install -v -m644 doc/*.html /usr/share/doc/rsync-&rsync-version;</userinput></screen>

  </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>Boot Script</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.</para>

      <para>Install the <filename>/etc/rc.d/init.d/rsyncd</filename> init
      script included in the
      <xref linkend="intro-important-bootscripts"/> package.</para>

<screen role="root"><userinput>make install-rsyncd</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>