source: server/other/svnserver.xml@ 5a3d9be7

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

]>

<sect1 id="svnserver" xreflabel="Running a Subversion Server">
<sect1info>
<othername>$LastChangedBy$</othername>
<date>$Date$</date>
</sect1info>
<?dbhtml filename="svnserver.html"?>
<title>Running a Subversion Server</title>

<sect2>
<title>Running a Subversion Server</title>
<para>This section will describe how to set up, administer and secure
a <application>Subversion</application> server.</para>

<sect3><title><application>Subversion server</application> dependencies</title>
<sect4><title>Required</title>
<para><xref linkend="subversion"/> and <xref linkend="openssh"/></para>
</sect4>
</sect3>

</sect2>

<sect2>
<title>Setting up a <application>Subversion</application> server.</title>
                                                                               
<para>The following instructions will install a  
<application>Subversion</application> server, which will be set up to
use <application>OpenSSH</application> as the secure remote access method, with
<command>svnserve</command> available for anonymous access.</para>

<para>Configuration of the <application>Subversion</application> server 
consists of the following steps:</para>
                                                                                
<sect3><title>1. Setup users, groups, and permissions</title>
<para>You'll need to be user root for the initial portion of
configuration. Create the svn user and group with the following 
commands:</para>

<screen><userinput><command>groupadd svn &amp;&amp;
useradd -c "SVN Owner" -d /home/svn -m -g svn -s /bin/false svn</command></userinput></screen>

<para>If you plan to have multiple repositories, you should have a 
group dedicated to each repository for ease of administration. Create 
the svntest group for the test repository and add the svn user to that
group with the following commands:</para>

<screen><userinput><command>groupadd svntest &amp;&amp;
usermod -G svntest svn</command></userinput></screen>

<para>Additionally you should set <command>umask 002</command> while working 
with a repository so that all new files will be writable by owner and group.
This is made mandatory by creating a wrapper script for
<command>svn</command> and <command>svnserve</command>:</para>

<screen><userinput><command>mv /usr/bin/svn /usr/bin/svn.orig &amp;&amp;
mv /usr/bin/svnserve /usr/bin/svnserve.orig &amp;&amp;
cat &gt;&gt; /usr/bin/svn &lt;&lt; "EOF"</command>
#!/bin/sh
umask 002
/usr/bin/svn.orig "$@"
<command>EOF
cat &gt;&gt; /usr/bin/svnserve &lt;&lt; "EOF"</command>
#!/bin/sh
umask 002
/usr/bin/svnserve.orig "$@"
<command>EOF
chmod 0755 /usr/bin/svn{,serve}</command></userinput></screen>

<note><para>If you use <application>Apache</application> for working with 
the repository over <acronym>HTTP</acronym>, even for anonymous access, you 
should wrap <command>/usr/sbin/httpd</command> in a similar 
script.</para></note>

</sect3>

<sect3><title>2. Create a <application>Subversion</application>
repository.</title>

<para>With subversion-1.1.0 and greater, a new type of repository 
data-store is available, <acronym>FSFS</acronym>.  There is a tradeoff 
for speed with the new backend, however, the repository can now be 
placed on a network mount, and any corruption does not require an
admin to recover the repository.  For more information and comparison 
between <acronym>FSFS</acronym> and <acronym>BDB</acronym>, plese see 
<ulink url="http://svnbook.red-bean.com/svnbook-1.1/ch05.html#svn-ch-5-sect-1.2.A"/>. 
Optionally you can pass <parameter>bdb</parameter> in place of 
<parameter>fsfs</parameter> in the following command to create a 
BerkelyDB data-store.</para>

<para>Create a new <application>Subversion</application> repository with
the following commands:</para>

<screen><userinput><command>install -d -m0755 /srv &amp;&amp;
install -d -m0755 -o svn -g svn /srv/svn/repositories &amp;&amp;
svnadmin create --fs-type fsfs /srv/svn/repositories/svntest</command></userinput></screen>

<para>Now that the repository is created, we need to populate it with
something useful. You'll need to have a predefined directory layout 
setup exactly as you want your repository to look. For example, here 
is a sample BLFS layout setup with a root of <filename>svntest/</filename>.
You'll need to setup a directory tree similar to the following:</para>

<screen>          svntest/            # The name of the repository
             trunk/           # Contains the existing source tree
                BOOK/
                bootscripts/
                edguide/
                patches/
                scripts/
             branches/        # Needed for additional branches
             tags/            # Needed for tagging release points</screen>

<para>Once you've created your directory layout as shown above, you are ready 
to do the initial import:</para>

<screen><userinput><command>svn import -m "Initial import." \
    <replaceable>[/path/to/source/tree]</replaceable> \
    file:///srv/svn/repositories/svntest</command></userinput></screen>

<para>Now go ahead and change owner and group information on the
repository, and add your normal user to the svn and svntest groups:</para>

<screen><userinput><command>chown -R svn:svntest /srv/svn/repositories/svntest &amp;&amp;
chmod -R g+w /srv/svn/repositories/svntest &amp;&amp;
chmod g+s /srv/svn/repositories/svntest/db &amp;&amp;
usermod -G svn,svntest,<replaceable>[insert existing groups]</replaceable> <replaceable>[username]</replaceable></command></userinput></screen>

<para>svntest is the group assigned to the svntest repository. As
mentioned earlier, this eases administration of multiple repositories
when using <application>OpenSSH</application> for authentication. Going 
forward, you'll need to add your regular user, and any additional users 
that you wish to have write access to the repository, to the svn and 
svntest groups.</para>
         
<para>In addition, you'll notice that the new repository's
<filename>db</filename> directory is set-groupID. If the reasoning is 
not immediately obvious, when using any external authentication method 
(such as <command>ssh</command>), the sticky bit is set so that all new files 
will be owned by the user, but group of svntest. Anyone in the svntest group 
can create files, but still give the entire group write access to those 
files. This avoids locking out other users from the repository.</para>

<para>Now, go ahead and return to your normal user account, and take a look at 
your new repository using <command>svnlook</command>:</para>

<screen><userinput><command>svnlook tree /srv/svn/repositories/svntest/</command></userinput></screen>

<note><para>You may need to log out and back in again to refresh your group
memberships. '<command>su <replaceable>[username]</replaceable></command>' 
should work around this as well.</para></note>

</sect3>

<sect3><title>3. Configure the server</title>

<para>As mentioned previously, these instructions will configure the 
server to use only <command>ssh</command> for write access to the repository 
and to provide anonymous access using <command>svnserve</command>. There are 
several other ways to provide access to the repository. These additional 
configurations are best explained at 
<ulink url="http://svnbook.red-bean.com/"/>.</para>

<para>Access configuration needs to be done for each repository. Create 
the <filename>svnserve.conf</filename> file for the svntest repository 
using the following commands:</para>

<screen><userinput><command>cp /srv/svn/repositories/svntest/conf/svnserve.conf \
    /srv/svn/repositories/svntest/conf/svnserve.conf.default &amp;&amp;
cat &gt; /srv/svn/repositories/svntest/conf/svnserve.conf &lt;&lt; "EOF"</command>
[general]
anon-access = read
auth-access = write
<command>EOF</command></userinput></screen>

<para>There is not a lot to the configuration file at all. You'll notice 
that only the general section is required. Take a look at the
<filename>svnserve.conf.default</filename> file for information on using 
<command>svnserve</command>'s built-in authentication method.</para>

</sect3>

<sect3><title>4. Starting the server</title>
<para>There are a couple of ways to start <command>svnserve</command>. The 
most common way is to start it as an <command>inetd</command> or 
<command>xinetd</command> process. Alternately, you can use a 
bootscript to start the service at startup.</para>

<note><para>If you do not wish to provide anonymous access to your svn
repositories or use <command>svnserve</command>'s built-in
authentication, you do not need to run 
<command>svnserve</command>.</para></note>

<para>If you use <command>inetd</command>, add a line to 
<filename>/etc/inetd.conf</filename> using the following commands:</para>

<screen><userinput><command>cat &gt;&gt; /etc/inetd.conf &lt;&lt; "EOF"</command>
svn stream tcp nowait svn /usr/bin/svnserve svnserve -i
<command>EOF</command></userinput></screen>

<para>If you use <command>xinetd</command>, add the following
lines to the <filename>/etc/xinetd.conf</filename> file:</para>

<screen><userinput><command>cat &gt;&gt; /etc/xinetd.conf &lt;&lt; "EOF"</command>
service svn
{
        port                    = 3690
        socket_type             = stream
        protocol                = tcp
        wait                    = no
        user                    = svn
        server                  = /usr/bin/svnserve
        server_args             = -i -r /srv/svn/repositories
}
<command>EOF</command></userinput></screen>

<para>Finally, if you wish to simply start the sever at
startup, install the svn bootscript included in the 
<xref linkend="intro-important-bootscripts"/> package.</para>

<screen><userinput><command>make install-svn</command></userinput></screen>

</sect3>

</sect2>

</sect1>