<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>httpd, the Apache HTTP Server</title>
<link rel="stylesheet" type="text/css" href="styles.css" />
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1" />
<style type="text/css">
body { background-image: url('images/draft.png');
background-repeat: no-repeat;
background-position: top left;
/* The following properties make the watermark "fixed" on the page. */
/* I think that's just a bit too distracting for the reader... */
/* background-attachment: fixed; */
/* background-position: center center; */
}</style>
<link rel="home" href="index.html" title="Version Control with Subversion [DRAFT]" />
<link rel="up" href="svn.serverconfig.html" title="Chapter 6. Server Configuration" />
<link rel="prev" href="svn.serverconfig.svnserve.html" title="svnserve, a Custom Server" />
<link rel="next" href="svn.serverconfig.pathbasedauthz.html" title="Path-Based Authorization" />
</head>
<body>
<div xmlns="" id="vcws-version-notice">
<p>This text is a work in progress—highly subject to
change—and may not accurately describe any released
version of the Apache™ Subversion® software.
Bookmarking or otherwise referring others to this page is
probably not such a smart idea. Please visit
<a href="http://www.svnbook.com/">http://www.svnbook.com/</a>
for stable versions of this book.</p>
</div>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">httpd, the Apache HTTP Server</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="svn.serverconfig.svnserve.html">Prev</a> </td>
<th width="60%" align="center">Chapter 6. Server Configuration</th>
<td width="20%" align="right"> <a accesskey="n" href="svn.serverconfig.pathbasedauthz.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="sect1" title="httpd, the Apache HTTP Server">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="svn.serverconfig.httpd"></a>httpd, the Apache HTTP Server</h2>
</div>
</div>
</div>
<p>The Apache HTTP Server is a <span class="quote">“<span class="quote">heavy-duty</span>”</span>
network server that Subversion can leverage. Via a custom
module, <span class="command"><strong>httpd</strong></span> makes Subversion repositories
available to clients via the WebDAV/DeltaV<sup>[<a id="idp16271712" href="#ftn.idp16271712" class="footnote">66</a>]</sup>
protocol, which is an extension to HTTP 1.1. This protocol
takes the ubiquitous HTTP protocol that is the core of the World
Wide Web, and adds writing—specifically, versioned
writing—capabilities. The result is a standardized,
robust system that is conveniently packaged as part of the
Apache 2.0 software, supported by numerous operating systems and
third-party products, and doesn't require network administrators
to open up yet another custom port.<sup>[<a id="idp16272976" href="#ftn.idp16272976" class="footnote">67</a>]</sup> While an Apache-Subversion
server has more features than <span class="command"><strong>svnserve</strong></span>, it's
also a bit more difficult to set up. With flexibility often
comes more complexity.</p>
<p>Much of the following discussion includes references to
Apache configuration directives. While some examples are given
of the use of these directives, describing them in full is
outside the scope of this chapter. The Apache team maintains
excellent documentation, publicly available on their web site at
<a class="ulink" href="http://httpd.apache.org" target="_top">http://httpd.apache.org</a>. For example, a general
reference for the configuration directives is located at
<a class="ulink" href="http://httpd.apache.org/docs/current/mod/directives.html" target="_top">http://httpd.apache.org/docs/current/mod/directives.html</a>.</p>
<p>Also, as you make changes to your Apache setup, it is likely
that somewhere along the way a mistake will be made. If you are
not already familiar with Apache's logging subsystem, you should
become aware of it. In your <code class="filename">httpd.conf</code>
file are directives that specify the on-disk locations of the
access and error logs generated by Apache (the
<code class="literal">CustomLog</code> and <code class="literal">ErrorLog</code>
directives, respectively).
Subversion's <span class="command"><strong>mod_dav_svn</strong></span> uses Apache's error
logging interface as well. You can always browse the contents
of those files for information that might reveal the source of a
problem that is not clearly noticeable otherwise.</p>
<div class="sect2" title="Prerequisites">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="svn.serverconfig.httpd.prereqs"></a>Prerequisites</h3>
</div>
</div>
</div>
<p>To network your repository over HTTP, you basically need
four components, available in two packages. You'll need
Apache <span class="command"><strong>httpd</strong></span> 2.0 or newer, the
<span class="command"><strong>mod_dav</strong></span> DAV module that comes with it,
Subversion, and the <span class="command"><strong>mod_dav_svn</strong></span>
filesystem provider module distributed with Subversion.
Once you have all of those components, the process of
networking your repository is as simple as:</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>Getting httpd up and running with
the <span class="command"><strong>mod_dav</strong></span> module</p>
</li>
<li class="listitem">
<p>Installing the <span class="command"><strong>mod_dav_svn</strong></span> backend
to <span class="command"><strong>mod_dav</strong></span>, which uses Subversion's
libraries to access the repository</p>
</li>
<li class="listitem">
<p>Configuring your <code class="filename">httpd.conf</code>
file to export (or expose) the repository</p>
</li>
</ul>
</div>
<p>You can accomplish the first two items either by
compiling <span class="command"><strong>httpd</strong></span> and Subversion from
source code or by installing prebuilt binary packages of
them on your system. For the most up-to-date information on
how to compile Subversion for use with the Apache HTTP Server,
as well as how to compile and configure Apache itself for
this purpose, see the <code class="filename">INSTALL</code> file in
the top level of the Subversion source code tree.</p>
</div>
<div class="sect2" title="Basic Apache Configuration">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="svn.serverconfig.httpd.basic"></a>Basic Apache Configuration</h3>
</div>
</div>
</div>
<p>Once you have all the necessary components installed on
your system, all that remains is the configuration of Apache
via its <code class="filename">httpd.conf</code> file. Instruct Apache
to load the <span class="command"><strong>mod_dav_svn</strong></span> module using the
<code class="literal">LoadModule</code> directive. This directive must
precede any other Subversion-related configuration items. If
your Apache was installed using the default layout, your
<span class="command"><strong>mod_dav_svn</strong></span> module should have been
installed in the <code class="filename">modules</code> subdirectory of
the Apache install location (often
<code class="filename">/usr/local/apache2</code>). The
<code class="literal">LoadModule</code> directive has a simple syntax,
mapping a named module to the location of a shared library on
disk:</p>
<div class="informalexample">
<pre class="programlisting">
LoadModule dav_svn_module modules/mod_dav_svn.so
</pre>
</div>
<p>Apache interprets the <code class="literal">LoadModule</code>
configuration item's library path as relative to its own
server root. If configured as previously shown, Apache will
look for the Subversion DAV module shared library in its
own <code class="filename">modules/</code> subdirectory. Depending on
how Subversion was installed on your system, you might need to
specify a different path for this library altogether, perhaps
even an absolute path such as in the following example:</p>
<div class="informalexample">
<pre class="programlisting">
LoadModule dav_svn_module C:/Subversion/lib/mod_dav_svn.so
</pre>
</div>
<p>Note that if <span class="command"><strong>mod_dav</strong></span> was compiled as a
shared object (instead of statically linked directly to the
<span class="command"><strong>httpd</strong></span> binary), you'll need a similar
<code class="literal">LoadModule</code> statement for it, too. Be sure
that it comes before the <span class="command"><strong>mod_dav_svn</strong></span> line:</p>
<div class="informalexample">
<pre class="programlisting">
LoadModule dav_module modules/mod_dav.so
LoadModule dav_svn_module modules/mod_dav_svn.so
</pre>
</div>
<p>At a later location in your configuration file, you now
need to tell Apache where you keep your Subversion repository
(or repositories). The <code class="literal">Location</code> directive
has an XML-like notation, starting with an opening tag and
ending with a closing tag, with various other configuration
directives in the middle. The purpose of the
<code class="literal">Location</code> directive is to instruct Apache to
do something special when handling requests that are directed
at a given URL or one of its children. In the case of
Subversion, you want Apache to simply hand off support for
URLs that point at versioned resources to the DAV layer. You
can instruct Apache to delegate the handling of all URLs whose
path portions (the part of the URL that follows the server's
name and the optional port number) begin with
<code class="filename">/repos/</code> to a DAV provider whose
repository is located at
<code class="filename">/var/svn/repository</code> using the
following <code class="filename">httpd.conf</code> syntax:</p>
<div class="informalexample">
<pre class="programlisting">
<Location /repos>
DAV svn
SVNPath /var/svn/repository
</Location>
</pre>
</div>
<p>If you plan to support multiple Subversion repositories
that will reside in the same parent directory on your local
disk, you can use an alternative
directive—<code class="literal">SVNParentPath</code>—to
indicate that common parent directory. For example, if you
know you will be creating multiple Subversion repositories in
a directory <code class="filename">/var/svn</code> that would be
accessed via URLs such as
<code class="uri">http://my.server.com/svn/repos1</code>,
<code class="uri">http://my.server.com/svn/repos2</code>, and so on, you
could use the <code class="filename">httpd.conf</code> configuration
syntax in the following example:</p>
<div class="informalexample">
<pre class="programlisting">
<Location /svn>
DAV svn
# Automatically map any "/svn/foo" URL to repository /var/svn/foo
SVNParentPath /var/svn
</Location>
</pre>
</div>
<p>Using this syntax, Apache will delegate the
handling of all URLs whose path portions begin with
<code class="filename">/svn/</code> to the Subversion DAV provider,
which will then assume that any items in the directory
specified by the <code class="literal">SVNParentPath</code> directive
are actually Subversion repositories. This is a particularly
convenient syntax in that, unlike the use of the
<code class="literal">SVNPath</code> directive, you don't have to
restart Apache to add or remove hosted repositories.</p>
<p>Be sure that when you define your new
<code class="literal">Location</code>, it doesn't overlap with other
exported locations. For example, if your main
<code class="literal">DocumentRoot</code> is exported to
<code class="filename">/www</code>, do not export a Subversion
repository in <code class="literal"><Location /www/repos></code>.
If a request comes in for the URI
<code class="filename">/www/repos/foo.c</code>, Apache won't know
whether to look for a file <code class="filename">repos/foo.c</code> in
the <code class="literal">DocumentRoot</code>, or whether to delegate
<span class="command"><strong>mod_dav_svn</strong></span> to return
<code class="filename">foo.c</code> from the Subversion repository.
The result is often an error from the server of the form
<code class="literal">301 Moved Permanently</code>.</p>
<div class="sidebar" title="Server Names and the COPY Request">
<div class="titlepage">
<div>
<div>
<p class="title">
<strong>Server Names and the COPY Request</strong>
</p>
</div>
</div>
</div>
<p>Subversion makes use of the <code class="literal">COPY</code>
request type to perform server-side copies of files and
directories. As part of the sanity checking done by the
Apache modules, the source of the copy is expected to be
located on the same machine as the destination of the copy.
To satisfy this requirement, you might need to
tell <span class="command"><strong>mod_dav</strong></span> the name you use as the
hostname of your server. Generally, you can use
the <code class="literal">ServerName</code> directive in
<code class="filename">httpd.conf</code> to accomplish this.</p>
<div class="informalexample">
<pre class="programlisting">
ServerName svn.example.com
</pre>
</div>
<p>If you are using Apache's virtual hosting support via
the <code class="literal">NameVirtualHost</code> directive, you may
need to use the <code class="literal">ServerAlias</code> directive to
specify additional names by which your server is known.
Again, refer to the Apache documentation for full
details.</p>
</div>
<p>At this stage, you should strongly consider the question
of permissions. If you've been running Apache for some time
now as your regular web server, you probably already have a
collection of content—web pages, scripts, and such.
These items have already been configured with a set of
permissions that allows them to work with Apache, or more
appropriately, that allows Apache to work with those files.
Apache, when used as a Subversion server, will also need the
correct permissions to read and write to your Subversion
repository.</p>
<p>You will need to determine a permission system setup that
satisfies Subversion's requirements without messing up any
previously existing web page or script installations. This
might mean changing the permissions on your Subversion
repository to match those in use by other things that Apache
serves for you, or it could mean using the
<code class="literal">User</code> and <code class="literal">Group</code>
directives in <code class="filename">httpd.conf</code> to specify that
Apache should run as the user and group that owns your
Subversion repository. There is no single correct way to set
up your permissions, and each administrator will have
different reasons for doing things a certain way. Just be
aware that permission-related problems are perhaps the most
common oversight when configuring a Subversion repository for
use with Apache.</p>
</div>
<div class="sect2" title="Authentication Options">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="svn.serverconfig.httpd.authn"></a>Authentication Options</h3>
</div>
</div>
</div>
<p>At this point, if you configured
<code class="filename">httpd.conf</code> to contain something such as the
following:</p>
<div class="informalexample">
<pre class="programlisting">
<Location /svn>
DAV svn
SVNParentPath /var/svn
</Location>
</pre>
</div>
<p>your repository is <span class="quote">“<span class="quote">anonymously</span>”</span>
accessible to the world. Until you configure some
authentication and authorization policies, the Subversion
repositories that you make available via the
<code class="literal">Location</code> directive will be generally
accessible to everyone. In other words:</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>Anyone can use a Subversion client to check out a
working copy of a repository URL (or any of its
subdirectories).</p>
</li>
<li class="listitem">
<p>Anyone can interactively browse the repository's
latest revision simply by pointing a web browser to
the repository URL.</p>
</li>
<li class="listitem">
<p>Anyone can commit to the repository.</p>
</li>
</ul>
</div>
<p>Of course, you might have already set up
a <code class="filename">pre-commit</code> hook script to prevent
commits (see <a class="xref" href="svn.reposadmin.create.html#svn.reposadmin.hooks" title="Implementing Repository Hooks">the section called “Implementing Repository Hooks”</a>).
But as you read on, you'll see that it's also possible to use
Apache's built-in methods to restrict access in specific
ways.</p>
<div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25">
<img alt="[Tip]" src="images/tip.png" />
</td>
<th align="left">Tip</th>
</tr>
<tr>
<td align="left" valign="top">
<p>Requiring authentication defends against invalid users
directly accessing the repository, but does not guard the
privacy of valid users' network activity. See
<a class="xref" href="svn.serverconfig.httpd.html#svn.serverconfig.httpd.ssl" title="Protecting network traffic with SSL">the section called “Protecting network traffic with SSL”</a> for how to
configure your server to support SSL encryption, which can
provide that extra layer of protection.</p>
</td>
</tr>
</table>
</div>
<div class="sect3" title="Basic authentication">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="svn.serverconfig.httpd.authn.basic"></a>Basic authentication</h4>
</div>
</div>
</div>
<p>The easiest way to authenticate a client is via the HTTP
Basic authentication mechanism, which simply uses a username
and password to verify a user's identity. Apache provides
the <span class="command"><strong>htpasswd</strong></span> utility<sup>[<a id="idp16359776" href="#ftn.idp16359776" class="footnote">68</a>]</sup> for managing files containing
usernames and passwords.</p>
<div class="warning" title="Warning" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Warning">
<tr>
<td rowspan="2" align="center" valign="top" width="25">
<img alt="[Warning]" src="images/warning.png" />
</td>
<th align="left">Warning</th>
</tr>
<tr>
<td align="left" valign="top">
<p>Basic authentication is <span class="emphasis"><em>extremely</em></span>
insecure, because it sends passwords over the network
in very nearly plain text. See
<a class="xref" href="svn.serverconfig.httpd.html#svn.serverconfig.httpd.authn.digest" title="Digest authentication">the section called “Digest authentication”</a> for
details on using the much safer Digest mechanism.</p>
</td>
</tr>
</table>
</div>
<p>First, create a password file and grant access to
users Harry and Sally:</p>
<div class="informalexample">
<pre class="screen">
$ ### First time: use -c to create the file
$ ### Use -m to use MD5 encryption of the password, which is more secure
$ htpasswd -c -m /etc/svn-auth.htpasswd harry
New password: *****
Re-type new password: *****
Adding password for user harry
$ htpasswd -m /etc/svn-auth.htpasswd sally
New password: *******
Re-type new password: *******
Adding password for user sally
$
</pre>
</div>
<p>Next, ensure that Apache has access to the modules which
provide the Basic authentication and related
functionality: <code class="literal">mod_auth_basic</code>,
<code class="literal">mod_authn_file</code>, and
<code class="literal">mod_authz_user</code>. In many cases, these
modules are compiled into <span class="command"><strong>httpd</strong></span> itself,
but if not, you might need to explicitly load one or more of
them using the <code class="literal">LoadModule</code> directive:</p>
<div class="informalexample">
<pre class="programlisting">
LoadModule auth_basic_module modules/mod_auth_basic.so
LoadModule authn_file_module modules/mod_authn_file.so
LoadModule authz_user_module moduels/mod_authz_user.so
</pre>
</div>
<p>After ensuring the Apache has access to the required
functionality, you'll need to add some more directives
inside the <code class="literal"><Location></code> block to tell
Apache what type of authentication you wish to use, and just
how to to so:</p>
<div class="informalexample">
<pre class="programlisting">
<Location /svn>
DAV svn
SVNParentPath /var/svn
# Authentication: Basic
AuthName "Subversion repository"
AuthType Basic
AuthBasicProvider file
AuthUserFile /etc/svn-auth.htpasswd
</Location>
</pre>
</div>
<p>These directives work as follows:</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p><code class="literal">AuthName</code> is an arbitrary name
that you choose for the authentication domain. Most
browsers display this name in the dialog box when
prompting for username and password.</p>
</li>
<li class="listitem">
<p><code class="literal">AuthType</code> specifies the type of
authentication to use.</p>
</li>
<li class="listitem">
<p><code class="literal">AuthBasicProvider</code> specifies the
Basic authentication provider to use for the location.
In our example, we wish to consult a local password
file.</p>
</li>
<li class="listitem">
<p><code class="literal">AuthUserFile</code> specifies the
location of the password file to use.</p>
</li>
</ul>
</div>
<p>However, this <code class="literal"><Location></code> block
doesn't yet do anything useful. It merely tells Apache that
<span class="emphasis"><em>if</em></span> authorization were required, it
should challenge the Subversion client for a username and
password. (When authorization is required, Apache requires
authentication as well.) What's missing here, however, are
directives that tell Apache <span class="emphasis"><em>which sorts</em></span>
of client requests require authorization; currently, none do.
The simplest thing is to specify that <span class="emphasis"><em>all</em></span>
requests require authorization by adding
<code class="literal">Require valid-user</code> to the block:</p>
<div class="informalexample">
<pre class="programlisting">
<Location /svn>
DAV svn
SVNParentPath /var/svn
# Authentication: Basic
AuthName "Subversion repository"
AuthType Basic
AuthBasicProvider file
AuthUserFile /etc/svn-auth.htpasswd
# Authorization: Authenticated users only
Require valid-user
</Location>
</pre>
</div>
<p>Refer to <a class="xref" href="svn.serverconfig.httpd.html#svn.serverconfig.httpd.authz" title="Authorization Options">the section called “Authorization Options”</a>
for more detail on the <code class="literal">Require</code> directive
and other ways to set authorization policies.</p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25">
<img alt="[Note]" src="images/note.png" />
</td>
<th align="left">Note</th>
</tr>
<tr>
<td align="left" valign="top">
<p>The default value of the
<code class="literal">AuthBasicProvider</code> option is
<code class="literal">file</code>, so we won't bother including
it in future examples. Just know that if in a broader
context you've set this value to something else, you'll
need to explicitly reset it to <code class="literal">file</code>
within your Subversion <code class="literal"><Location></code>
block in order to get that behavior.</p>
</td>
</tr>
</table>
</div>
</div>
<div class="sect3" title="Digest authentication">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="svn.serverconfig.httpd.authn.digest"></a>Digest authentication</h4>
</div>
</div>
</div>
<p>Digest authentication is an improvement on Basic
authentication which allows the server to verify a client's
identity without sending the password over the network
unprotected. Both client and server create a non-reversible
MD5 hash of the username, password, requested URI, and a
<em class="firstterm">nonce</em> (number used once) provided by
the server and changed each time authentication is required.
The client sends its hash to the server, and the server then
verifies that the hashes match.</p>
<p>Configuring Apache to use Digest authentication is
straightforward. You'll need to ensure that
the <code class="literal">mod_auth_digest</code> module is available
(instead of <code class="literal">mod_auth_basic</code>), and then
make a few small variations on our prior example:</p>
<div class="informalexample">
<pre class="programlisting">
<Location /svn>
DAV svn
SVNParentPath /var/svn
# Authentication: Digest
AuthName "Subversion repository"
AuthType Digest
AuthDigestProvider file
AuthUserFile /etc/svn-auth.htdigest
# Authorization: Authenticated users only
Require valid-user
</Location>
</pre>
</div>
<p>Notice that <code class="literal">AuthType</code> is now set to
<code class="literal">Digest</code>, and we specify a different path
for <code class="literal">AuthUserFile</code>. Digest authentication
uses a different file format than Basic authentication,
created and managed using Apache's <span class="command"><strong>htdigest</strong></span>
utility<sup>[<a id="idp16401440" href="#ftn.idp16401440" class="footnote">69</a>]</sup> rather than <span class="command"><strong>htpasswd</strong></span>.
Digest authentication also has the additional concept of a
<span class="quote">“<span class="quote">realm</span>”</span>, which must match the value of the
<code class="literal">AuthName</code> directive.</p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25">
<img alt="[Note]" src="images/note.png" />
</td>
<th align="left">Note</th>
</tr>
<tr>
<td align="left" valign="top">
<p>For digest authentication, the authentication provider
is selected using the <code class="literal">AuthDigestProvider</code>
as shown in the previous example. As was the case with
the <code class="literal">AuthBasicProvider</code> directive,
<code class="literal">file</code> is the default value of the
<code class="literal">AuthDigestProvider</code> option, so this
line is not strictly required unless you need to override
a different value thereof inherited from a broader
configuration context.</p>
</td>
</tr>
</table>
</div>
<p>The password file can be created as follows:</p>
<div class="informalexample">
<pre class="screen">
$ ### First time: use -c to create the file
$ htdigest -c /etc/svn-auth.htdigest "Subversion repository" harry
Adding password for harry in realm Subversion repository.
New password: *****
Re-type new password: *****
$ htdigest /etc/svn-auth.htdigest "Subversion repository" sally
Adding user sally in realm Subversion repository
New password: *******
Re-type new password: *******
$
</pre>
</div>
</div>
</div>
<div class="sect2" title="Authorization Options">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="svn.serverconfig.httpd.authz"></a>Authorization Options</h3>
</div>
</div>
</div>
<p>At this point, you've configured authentication, but not
authorization. Apache is able to challenge clients and
confirm identities, but it has not been told how to allow or
restrict access to the clients bearing those identities. This
section describes two strategies for controlling access to
your repositories.</p>
<div class="sect3" title="Blanket access control">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="svn.serverconfig.httpd.authz.blanket"></a>Blanket access control</h4>
</div>
</div>
</div>
<p>The simplest form of access control is to authorize
certain users for either read-only access to a repository or
read/write access to a repository.</p>
<p>You can restrict access on all repository operations by
adding <code class="literal">Require valid-user</code> directly inside
the <code class="literal"><Location></code> block. The example
from <a class="xref" href="svn.serverconfig.httpd.html#svn.serverconfig.httpd.authn.digest" title="Digest authentication">the section called “Digest authentication”</a>
allows only clients that successfully authenticate to do
anything with the Subversion repository:</p>
<div class="informalexample">
<pre class="programlisting">
<Location /svn>
DAV svn
SVNParentPath /var/svn
# Authentication: Digest
AuthName "Subversion repository"
AuthType Digest
AuthUserFile /etc/svn-auth.htdigest
# Authorization: Authenticated users only
Require valid-user
</Location>
</pre>
</div>
<p>Sometimes you don't need to run such a tight ship. For
example, the server hosting Subversion's own source code at
<a class="ulink" href="https://svn.apache.org/repos/asf/subversion/" target="_top">https://svn.apache.org/repos/asf/subversion/</a> allows
anyone in the world to perform read-only repository tasks (such as
checking out working copies and browsing the repository),
but restricts write operations to authenticated users. The
<code class="literal">Limit</code> and <code class="literal">LimitExcept</code>
directives allow for this type of selective restriction.
Like the <code class="literal">Location</code> directive, these blocks
have starting and ending tags, and you would nest them
inside your <code class="literal"><Location></code>
block.</p>
<p>The parameters present on the <code class="literal">Limit</code>
and <code class="literal">LimitExcept</code> directives are HTTP
request types that are affected by that block. For example,
to allow anonymous read-only operations, you would use the
<code class="literal">LimitExcept</code> directive (passing the
<code class="literal">GET</code>, <code class="literal">PROPFIND</code>,
<code class="literal">OPTIONS</code>, and <code class="literal">REPORT</code>
request type parameters) and place the previously mentioned
<code class="literal">Require valid-user</code> directive inside the
<code class="literal"><LimitExcept></code> block instead of just
inside the <code class="literal"><Location></code> block.</p>
<div class="informalexample">
<pre class="programlisting">
<Location /svn>
DAV svn
SVNParentPath /var/svn
# Authentication: Digest
AuthName "Subversion repository"
AuthType Digest
AuthUserFile /etc/svn-auth.htdigest
# Authorization: Authenticated users only for non-read-only
# (write) operations; allow anonymous reads
<LimitExcept GET PROPFIND OPTIONS REPORT>
Require valid-user
</LimitExcept>
</Location>
</pre>
</div>
<p>These are only a few simple examples. For more in-depth
information about Apache access control and the
<code class="literal">Require</code> directive, take a look at the
<code class="literal">Security</code> section of the Apache
documentation's tutorials collection at <a class="ulink" href="http://httpd.apache.org/docs-2.0/misc/tutorials.html" target="_top">http://httpd.apache.org/docs-2.0/misc/tutorials.html</a>.</p>
</div>
<div class="sect3" title="Per-directory access control">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="svn.serverconfig.httpd.authz.perdir"></a>Per-directory access control</h4>
</div>
</div>
</div>
<p>It's possible to set up finer-grained permissions using
<span class="command"><strong>mod_authz_svn</strong></span>. This Apache module grabs
the various opaque URLs passing from client to server, asks
<span class="command"><strong>mod_dav_svn</strong></span> to decode them, and then
possibly vetoes requests based on access policies defined in
a configuration file.</p>
<p>If you've built Subversion from source code,
<span class="command"><strong>mod_authz_svn</strong></span> is automatically built
and installed alongside <span class="command"><strong>mod_dav_svn</strong></span>.
Many binary distributions install it automatically as well.
To verify that it's installed correctly, make sure it comes
right after <span class="command"><strong>mod_dav_svn</strong></span>'s
<code class="literal">LoadModule</code> directive in
<code class="filename">httpd.conf</code>:</p>
<div class="informalexample">
<pre class="programlisting">
LoadModule dav_module modules/mod_dav.so
LoadModule dav_svn_module modules/mod_dav_svn.so
LoadModule authz_svn_module modules/mod_authz_svn.so
</pre>
</div>
<p>To activate this module, you need to configure your
<code class="literal"><Location></code> block to use the
<code class="literal">AuthzSVNAccessFile</code> directive, which
specifies a file containing the permissions policy for paths
within your repositories. (In a moment, we'll discuss the
format of that file.)</p>
<p>Apache is flexible, so you have the option to configure
your block in one of three general patterns. To begin,
choose one of these basic configuration patterns. (The
following examples are very simple; look at Apache's own
documentation for much more detail on Apache authentication
and authorization options.)</p>
<p>The most open approach is to allow access to everyone.
This means Apache never sends authentication challenges, and
all users are treated as <span class="quote">“<span class="quote">anonymous</span>”</span>. (See
<a class="xref" href="svn.serverconfig.httpd.html#svn.serverconfig.httpd.authz.perdir.ex-1" title="Example 6.2. A sample configuration for anonymous access">Example 6.2, “A sample configuration for anonymous access”</a>.)</p>
<div class="example">
<a id="svn.serverconfig.httpd.authz.perdir.ex-1"></a>
<p class="title">
<strong>Example 6.2. A sample configuration for anonymous access</strong>
</p>
<div class="example-contents">
<pre class="programlisting">
<Location /repos>
DAV svn
SVNParentPath /var/svn
# Authentication: None
# Authorization: Path-based access control
AuthzSVNAccessFile /path/to/access/file
</Location>
</pre>
</div>
</div>
<br class="example-break" />
<p>On the opposite end of the paranoia scale, you can
configure Apache to authenticate all clients.
This block unconditionally requires authentication via the
<code class="literal">Require valid-user</code> directive, and defines
a means to authenticate valid users. (See
<a class="xref" href="svn.serverconfig.httpd.html#svn.serverconfig.httpd.authz.perdir.ex-2" title="Example 6.3. A sample configuration for authenticated access">Example 6.3, “A sample configuration for authenticated access”</a>.)</p>
<div class="example">
<a id="svn.serverconfig.httpd.authz.perdir.ex-2"></a>
<p class="title">
<strong>Example 6.3. A sample configuration for authenticated access</strong>
</p>
<div class="example-contents">
<pre class="programlisting">
<Location /repos>
DAV svn
SVNParentPath /var/svn
# Authentication: Digest
AuthName "Subversion repository"
AuthType Digest
AuthUserFile /etc/svn-auth.htdigest
# Authorization: Path-based access control; authenticated users only
AuthzSVNAccessFile /path/to/access/file
Require valid-user
</Location>
</pre>
</div>
</div>
<br class="example-break" />
<p>A third very popular pattern is to allow a combination
of authenticated and anonymous access. For example, many
administrators want to allow anonymous users to read certain
repository directories, but restrict access to more
sensitive areas to authenticated users. In this setup, all
users start out accessing the repository anonymously. If
your access control policy demands a real username at any
point, Apache will demand authentication from the client.
To do this, use both the <code class="literal">Satisfy Any</code>
and <code class="literal">Require valid-user</code> directives. (See
<a class="xref" href="svn.serverconfig.httpd.html#svn.serverconfig.httpd.authz.perdir.ex-3" title="Example 6.4. A sample configuration for mixed authenticated/anonymous access">Example 6.4, “A sample configuration for mixed
authenticated/anonymous access”</a>.)</p>
<div class="example">
<a id="svn.serverconfig.httpd.authz.perdir.ex-3"></a>
<p class="title">
<strong>Example 6.4. A sample configuration for mixed
authenticated/anonymous access</strong>
</p>
<div class="example-contents">
<pre class="programlisting">
<Location /repos>
DAV svn
SVNParentPath /var/svn
# Authentication: Digest
AuthName "Subversion repository"
AuthType Digest
AuthUserFile /etc/svn-auth.htdigest
# Authorization: Path-based access control; try anonymous access
# first, but authenticate if necessary
AuthzSVNAccessFile /path/to/access/file
Satisfy Any
Require valid-user
</Location>
</pre>
</div>
</div>
<br class="example-break" />
<p>The next step is to create the authorization file
containing access rules for particular paths within the
repository. We describe how later in this chapter, in
<a class="xref" href="svn.serverconfig.pathbasedauthz.html" title="Path-Based Authorization">the section called “Path-Based Authorization”</a>.</p>
</div>
<div class="sect3" title="Disabling path-based checks">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="svn.serverconfig.httpd.authz.pathauthzoff"></a>Disabling path-based checks</h4>
</div>
</div>
</div>
<p>The <span class="command"><strong>mod_dav_svn</strong></span> module goes through a
lot of work to make sure that data you've marked
<span class="quote">“<span class="quote">unreadable</span>”</span> doesn't get accidentally leaked.
This means it needs to closely monitor all of the paths
and file-contents returned by commands such as <span class="command"><strong>svn
checkout</strong></span> and <span class="command"><strong>svn update</strong></span>.
If these commands encounter a path that isn't
readable according to some authorization policy, the
path is typically omitted altogether. In the case of
history or rename tracing—for example, running a command such
as <strong class="userinput"><code>svn cat -r OLD foo.c</code></strong> on a file that
was renamed long ago—the rename tracking will simply
halt if one of the object's former names is determined to be
read-restricted.</p>
<p>All of this path checking can sometimes be quite
expensive, especially in the case of <span class="command"><strong>svn
log</strong></span>. When retrieving a list of revisions, the
server looks at every changed path in each revision and
checks it for readability. If an unreadable path is
discovered, it's omitted from the list of the revision's
changed paths (normally seen with
the <code class="option">--verbose</code> (<code class="option">-v</code>) option),
and the whole log message is suppressed. Needless to say,
this can be time-consuming on revisions that affect a large
number of files. This is the cost of security: even if you
haven't configured a module such as
<span class="command"><strong>mod_authz_svn</strong></span> at all, the
<span class="command"><strong>mod_dav_svn</strong></span> module is still asking Apache
<span class="command"><strong>httpd</strong></span> to run authorization checks on
every path. The <span class="command"><strong>mod_dav_svn</strong></span> module has
no idea what authorization modules have been installed, so
all it can do is ask Apache to invoke whatever might be
present.</p>
<p>On the other hand, there's also an escape hatch of
sorts, which allows you to trade security features for
speed. If you're not enforcing any sort of per-directory
authorization (i.e., not using
<span class="command"><strong>mod_authz_svn</strong></span> or similar module),
you can disable all of this path checking. In your
<code class="filename">httpd.conf</code> file, use the
<code class="literal">SVNPathAuthz</code> directive as shown in
<a class="xref" href="svn.serverconfig.httpd.html#svn.serverconfig.httpd.authz.pathauthzoff.ex-1" title="Example 6.5. Disabling path checks altogether">Example 6.5, “Disabling path checks altogether”</a>.</p>
<div class="example">
<a id="svn.serverconfig.httpd.authz.pathauthzoff.ex-1"></a>
<p class="title">
<strong>Example 6.5. Disabling path checks altogether</strong>
</p>
<div class="example-contents">
<pre class="programlisting">
<Location /repos>
DAV svn
SVNParentPath /var/svn
SVNPathAuthz off
</Location>
</pre>
</div>
</div>
<br class="example-break" />
<p>The <code class="literal">SVNPathAuthz</code> directive
is <span class="quote">“<span class="quote">on</span>”</span> by default. When
set to <span class="quote">“<span class="quote">off,</span>”</span> all path-based authorization
checking is disabled;
<span class="command"><strong>mod_dav_svn</strong></span> stops invoking authorization
checks on every path it discovers.</p>
</div>
</div>
<div class="sect2" title="Protecting network traffic with SSL">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="svn.serverconfig.httpd.ssl"></a>Protecting network traffic with SSL</h3>
</div>
</div>
</div>
<p>Connecting to a repository via <code class="literal">http://</code>
means that all Subversion activity is sent across the network
in the clear. This means that actions such as checkouts,
commits, and updates could potentially be intercepted by an
unauthorized party <span class="quote">“<span class="quote">sniffing</span>”</span> network traffic.
Encrypting traffic using SSL is a good way to protect
potentially sensitive information over the network.</p>
<p>If a Subversion client is compiled to use OpenSSL,
it gains the ability to speak to an Apache server via
<code class="literal">https://</code> URLs, so all traffic is encrypted
with a per-connection session key. The WebDAV library used by
the Subversion client is not only able to verify server
certificates, but can also supply client certificates when
challenged by the server.</p>
<div class="sect3" title="Subversion server SSL certificate configuration">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="svn.serverconfig.httpd.ssl.server"></a>Subversion server SSL certificate configuration</h4>
</div>
</div>
</div>
<p>It's beyond the scope of this book to describe how to
generate client and server SSL certificates and how to
configure Apache to use them. Many other references,
including Apache's own documentation (<a class="ulink" href="http://httpd.apache.org/docs/current/ssl/" target="_top">http://httpd.apache.org/docs/current/ssl/</a>),
describe the process.</p>
<div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25">
<img alt="[Tip]" src="images/tip.png" />
</td>
<th align="left">Tip</th>
</tr>
<tr>
<td align="left" valign="top">
<p>SSL certificates from well-known entities generally
cost money, but at a bare minimum, you can configure
Apache to use a self-signed certificate generated with a
tool such as OpenSSL (<a class="ulink" href="http://openssl.org" target="_top">http://openssl.org</a>).<sup>[<a id="idp16494256" href="#ftn.idp16494256" class="footnote">70</a>]</sup></p>
</td>
</tr>
</table>
</div>
</div>
<div class="sect3" title="Subversion client SSL certificate management">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="svn.serverconfig.httpd.ssl.client"></a>Subversion client SSL certificate management</h4>
</div>
</div>
</div>
<p>When connecting to Apache via <code class="literal">https://</code>,
a Subversion client can receive two different types of
responses:</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>A server certificate</p>
</li>
<li class="listitem">
<p>A challenge for a client certificate</p>
</li>
</ul>
</div>
<div class="sect4" title="Server certificate">
<div class="titlepage">
<div>
<div>
<h5 class="title"><a id="svn.serverconfig.httpd.ssl.client.servercert"></a>Server certificate</h5>
</div>
</div>
</div>
<p>When the client receives a server certificate, it needs
to verify that the server is who it claims to be. OpenSSL
does this by examining the signer of the server certificate,
or <em class="firstterm">certificate authority</em> (CA). If
OpenSSL is unable to automatically trust the CA, or if some
other problem occurs (such as an expired certificate or
hostname mismatch), the Subversion command-line client will
ask you whether you want to trust the server certificate
anyway:</p>
<div class="informalexample">
<pre class="screen">
$ svn list https://host.example.com/repos/project
Error validating server certificate for 'https://host.example.com:443':
- The certificate is not issued by a trusted authority. Use the
fingerprint to validate the certificate manually!
Certificate information:
- Hostname: host.example.com
- Valid: from Jan 30 19:23:56 2004 GMT until Jan 30 19:23:56 2006 GMT
- Issuer: CA, example.com, Sometown, California, US
- Fingerprint: 7d:e1:a9:34:33:39:ba:6a:e9:a5:c4:22:98:7b:76:5c:92:a0:9c:7b
(R)eject, accept (t)emporarily or accept (p)ermanently?
</pre>
</div>
<p>This dialogue is essentially the same question you may
have seen coming from your web browser (which is just
another HTTP client like Subversion). If you choose the
<code class="literal">(p)</code>ermanent option, Subversion will
cache the server certificate in your private runtime
<code class="filename">auth/</code> area, just as your username and
password are cached (see <a class="xref" href="svn.serverconfig.netmodel.html#svn.serverconfig.netmodel.credcache" title="Caching credentials">the section called “Caching credentials”</a>), and will
automatically trust the certificate in the future.</p>
<p>Your runtime <code class="filename">servers</code> file also gives
you the ability to make your Subversion client automatically
trust specific CAs, either globally or on a per-host basis.
Simply set the <code class="literal">ssl-authority-files</code>
variable to a semicolon-separated list of PEM-encoded CA
certificates:</p>
<div class="informalexample">
<pre class="programlisting">
[global]
ssl-authority-files = /path/to/CAcert1.pem;/path/to/CAcert2.pem
</pre>
</div>
<p>Many OpenSSL installations also have a predefined set
of <span class="quote">“<span class="quote">default</span>”</span> CAs that are nearly universally
trusted. To make the Subversion client automatically trust
these standard authorities, set the
<code class="literal">ssl-trust-default-ca</code> variable to
<code class="literal">true</code>.</p>
</div>
<div class="sect4" title="Client certificate challenge">
<div class="titlepage">
<div>
<div>
<h5 class="title"><a id="svn.serverconfig.httpd.ssl.client.clientcert"></a>Client certificate challenge</h5>
</div>
</div>
</div>
<p>If the client receives a challenge for a certificate,
the server is asking the client to prove its identity.
The client must send back a certificate signed by a CA
that the server trusts, along with a <em class="firstterm">challenge
response</em> which proves that the client owns the
private key associated with the certificate. The private
key and certificate are usually stored in an encrypted
format on disk, protected by a passphrase. When Subversion
receives this challenge, it will ask you for the path to the
encrypted file and the passphrase that protects it:</p>
<div class="informalexample">
<pre class="screen">
$ svn list https://host.example.com/repos/project
Authentication realm: https://host.example.com:443
Client certificate filename: /path/to/my/cert.p12
Passphrase for '/path/to/my/cert.p12': ********
</pre>
</div>
<p>Notice that the client credentials are stored in a
<code class="literal">.p12</code> file. To use a client certificate
with Subversion, it must be in PKCS#12 format, which is a
portable standard. Most web browsers are able to import
and export certificates in that format. Another option
is to use the OpenSSL command-line tools to convert
existing certificates into PKCS#12.</p>
<p>The runtime <code class="filename">servers</code> file also
allows you to automate this challenge on a per-host basis.
If you set the <code class="literal">ssl-client-cert-file</code>
and <code class="literal">ssl-client-cert-password</code> variables,
Subversion can automatically respond to a client
certificate challenge without prompting you:</p>
<div class="informalexample">
<pre class="programlisting">
[groups]
examplehost = host.example.com
[examplehost]
ssl-client-cert-file = /path/to/my/cert.p12
ssl-client-cert-password = somepassword
</pre>
</div>
<p>More security-conscious folk might want to exclude
<code class="literal">ssl-client-cert-password</code> to avoid
storing the passphrase in the clear on disk.</p>
</div>
</div>
</div>
<div class="sect2" title="Tuning for Performance">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="svn.serverconfig.httpd.perf"></a>Tuning for Performance</h3>
</div>
</div>
</div>
<p>The Apache HTTP Server is built for performance, but you
can improve upon its default configuration to get even better
results out of your Subversion service offering. In this
section, we'll recommend some specific configuration changes
to consider. Understand, however, that some of
the <code class="filename">httpd.conf</code> configuration options
we'll be discussing herein affect the general behavior of your
server, not merely the Subversion service. As such, you need
to consider the full breadth of your HTTP service offering to
discern how modifications to these settings for Subversion's
sake may affect your other services.</p>
<div class="sect3" title="KeepAlive">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="svn.serverconfig.httpd.perf.keepalive"></a>KeepAlive</h4>
</div>
</div>
</div>
<p>By default, the Apache HTTP Server is configured to
enable the re-use of a single server connection for multiple
requests. That's very beneficial for Subversion, because
unlike many HTTP-based applications, Subversion can very
quickly generate hundreds or thousands of requests against
the server for a single operation, and the cost of opening a
new connection to the server is non-trivial. Subversion
wants to squeeze as many requests as possible out of a
single connection before that connection is terminated by
the server. The <code class="literal">KeepAlive</code> directive is the
boolean flag which enables or disables this connection
re-use facility, and as we indicated previously, by default
its value is <code class="literal">On</code>.</p>
<p>But there's another directive which limits the number of
requests a client is allowed to submit on a single
connection: the <code class="literal">MaxKeepAliveRequests</code>
directive. The default value for that option
is <code class="literal">100</code>. This was probably sufficient for
older versions of Subversion, but Subversion 1.8 employs a
different HTTP communications library (called Serf) which
prefers to pipeline several smaller requests for specific bits
of information rather than asking the server to transmit
huge chunks of data in a single response. We recommend that
you increase the value of the
<code class="literal">MaxKeepAliveRequests</code> option
to at least <code class="literal">1000</code>.</p>
<div class="informalexample">
<pre class="programlisting">
#
# KeepAlive: Whether or not to allow persistent connections (more than
# one request per connection). Set to "Off" to deactivate.
#
KeepAlive On
#
# MaxKeepAliveRequests: The maximum number of requests to allow
# during a persistent connection. Set to 0 to allow an unlimited amount.
# We recommend you leave this number high, for maximum performance.
#
MaxKeepAliveRequests 1000
</pre>
</div>
</div>
<div class="sect3" title="Bulk updates">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="svn.serverconfig.httpd.perf.bulk-updates"></a>Bulk updates</h4>
</div>
</div>
</div>
<p>The biggest difference between the way that Subversion
1.8 clients and pre-1.8 clients behave is in how update-style
operations (<span class="command"><strong>svn checkout</strong></span>, <span class="command"><strong>svn
update</strong></span>, <span class="command"><strong>svn switch</strong></span>, etc.) are
handled. Older clients which used the Neon HTTP library for
communications preferred to ask the server for the entire
payload of information required from the server in a single
request. Admins will have noticed that in their server
logs, there would be some initial handshaking operations,
and then a <code class="literal">REPORT</code> request with a massive
response. That response was the entire checkout/update
dataset!</p>
<p>Subversion clients which use the Serf HTTP
library—which includes all clients built atop the
Subversion 1.8—still send the <code class="literal">REPORT</code>
request, but with slightly different flags set inside that
request. These flags ask the server not to send all the
data for the operation, but to instead send only a checklist
of other more specific things that the client needs to
subsequently fetch from the server in order to complete that
operation. In the server's <code class="filename">access_log</code>,
that <code class="literal">REPORT</code> is followed by many smaller
requests (<code class="literal">GET</code>s and, in older versions of
Subversion, <code class="literal">PROPFIND</code>s).</p>
<p>There are pros and cons to each approach. As we've
mentioned, the so-called bulk updates generate considerably
less information in the server logs, but a given Apache HTTP
Server child process is completely consumed for the duration
of what could be a lengthy operation. Non-bulk updates
offer opportunities for setting up content caches (which
themselves can improve performance), but generate server log
traffic which is whole orders of magnitude larger than the
bulk update approach. So, for one reason or another,
administrators may desire to exert a little more control
over which approach the clients use. Subversion 1.6
introduced the <code class="literal">SVNAllowBulkUpdates</code>
<span class="command"><strong>mod_dav_svn</strong></span> directive—a simple
boolean flag—to allow admins to specify whether the
server was allowed to honor bulk update requests. In
Subversion 1.8, this directive has expanded to include
a <code class="literal">Prefer</code> value in addition to the
<code class="literal">On</code> and <code class="literal">Off</code> values it
already supported. When <code class="literal">SVNAllowBulkUpdates</code>
is set to <code class="literal">Prefer</code>, supporting clients (1.8
or newer) will try to use the bulk update approach unless
otherwise configured.</p>
</div>
</div>
<div class="sect2" title="Extra Goodies">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="svn.serverconfig.httpd.extra"></a>Extra Goodies</h3>
</div>
</div>
</div>
<p>We've covered most of the authentication and authorization
options for Apache and <span class="command"><strong>mod_dav_svn</strong></span>. But
there are a few other nice features that Apache
provides.</p>
<div class="sect3" title="Repository browsing">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="svn.serverconfig.httpd.extra.browsing"></a>Repository browsing</h4>
</div>
</div>
</div>
<p>One of the most useful benefits of an Apache/WebDAV
configuration for your Subversion repository is that your
versioned files and directories are immediately available
for viewing via a regular web browser. Since Subversion
uses URLs to identify versioned resources, those URLs used
for HTTP-based repository access can be typed directly into
a web browser. Your browser will issue an
HTTP <code class="literal">GET</code> request for that URL; based on
whether that URL represents a versioned directory or
file, <span class="command"><strong>mod_dav_svn</strong></span> will respond with a
directory listing or with file contents.</p>
<div class="sect4" title="URL syntax">
<div class="titlepage">
<div>
<div>
<h5 class="title"><a id="svn.serverconfig.httpd.extra.browsing.syntax"></a>URL syntax</h5>
</div>
</div>
</div>
<p>If the URLs do not contain any information about which
version of the resource you wish to
see, <span class="command"><strong>mod_dav_svn</strong></span> will answer with the
youngest version. This functionality has the wonderful
side effect that you can pass around Subversion URLs to
your peers as references to documents, and those URLs will
always point at the latest manifestation of that document.
Of course, you can even use the URLs as hyperlinks from
other web sites, too.</p>
<p>As of Subversion 1.6, <span class="command"><strong>mod_dav_svn</strong></span>
supports a public URI syntax for examining older revisions
of both files and directories. The syntax uses the query
string portion of the URL to specify either or both of a
peg revision and operative revision, which Subversion will
then use to determine which version of the file or
directory to display to your web browser. Add the query
string name/value pair
<code class="literal">p=<em class="replaceable"><code>PEGREV</code></em></code>,
where <em class="replaceable"><code>PEGREV</code></em> is a revision
number, to specify the peg revision you wish to apply to the
request. Use
<code class="literal">r=<em class="replaceable"><code>REV</code></em></code>,
where <em class="replaceable"><code>REV</code></em> is a revision number, to
specify an operative revision.</p>
<p>For example, if you wish to see the latest version of a
<code class="filename">README.txt</code> file located in your
project's <code class="filename">/trunk</code>, point your web
browser to that file's repository URL, which might look
something like the following:</p>
<div class="informalexample">
<pre class="programlisting">
http://host.example.com/repos/project/trunk/README.txt
</pre>
</div>
<p>If you now wish to see some older version of that
file, add an operative revision to the URL's query
string:</p>
<div class="informalexample">
<pre class="programlisting">
http://host.example.com/repos/project/trunk/README.txt?r=1234
</pre>
</div>
<p>What if the thing you're trying to view no longer exists
in the youngest revision of the repository? That's where a
peg revision is handy:</p>
<div class="informalexample">
<pre class="programlisting">
http://host.example.com/repos/project/trunk/deleted-thing.txt?p=321
</pre>
</div>
<p>And of course, you can combine peg revision and
operative revision specifiers to fine-tune the exact item
you wish to view:</p>
<div class="informalexample">
<pre class="programlisting">
http://host.example.com/repos/project/trunk/renamed-thing.txt?p=123&r=21
</pre>
</div>
<p>The previous URL would display revision 21 of the
object which, in revision 123, was located
at <code class="filename">/trunk/renamed-thing.txt</code> in the
repository. See <a class="xref" href="svn.advanced.pegrevs.html" title="Peg and Operative Revisions">the section called “Peg and Operative Revisions”</a> for a
detailed explanation of these <span class="quote">“<span class="quote">peg revision</span>”</span>
and <span class="quote">“<span class="quote">operative revision</span>”</span> concepts. They can
be a bit tricky to wrap your head around.</p>
<p>As a reminder, this feature
of <span class="command"><strong>mod_dav_svn</strong></span> offers only a limited
repository browsing experience. You can see directory
listings and file contents, but no revision properties
(such as commit log messages) or file/directory
properties. For folks who require more extensive browsing
of repositories and their history, there are several
third-party software packages which offer this. Some
examples include ViewVC (<a class="ulink" href="http://viewvc.org" target="_top">http://viewvc.org</a>),
Trac (<a class="ulink" href="http://trac.edgewall.org" target="_top">http://trac.edgewall.org</a>) and WebSVN
(<a class="ulink" href="http://websvn.info" target="_top">http://websvn.info</a>). These third-party
tools don't affect <span class="command"><strong>mod_dav_svn</strong></span>'s
built-in <span class="quote">“<span class="quote">browseability</span>”</span>, and generally offer
a much wider set of features, including the display of the
aforementioned property sets, display of content
differences between file revisions, and so on.</p>
</div>
<div class="sect4" title="Proper MIME type">
<div class="titlepage">
<div>
<div>
<h5 class="title"><a id="svn.serverconfig.httpd.extra.browsing.mimetype"></a>Proper MIME type</h5>
</div>
</div>
</div>
<p>When browsing a Subversion repository, the web browser
gets a clue about how to render a file's contents by
looking at the <code class="literal">Content-Type:</code> header
returned in Apache's response to the
HTTP <code class="literal">GET</code> request. The value of this
header is some sort of MIME type. By default, Apache will
tell the web browsers that all repository files are of
the <span class="quote">“<span class="quote">default</span>”</span> MIME type,
typically <code class="literal">text/plain</code>. This can be
frustrating, however, if a user wishes repository files to
render as something more meaningful—for example,
it might be nice to have a <code class="filename">foo.html</code> file
in the repository actually render as HTML when
browsing.</p>
<p>To make this happen, you need only to make sure that
your files have the proper <code class="literal">svn:mime-type</code>
set. We discuss this in more detail in
<a class="xref" href="svn.advanced.props.file-portability.html#svn.advanced.props.special.mime-type" title="File Content Type">the section called “File Content Type”</a>,
and you can even configure your client to automatically
attach proper <code class="literal">svn:mime-type</code> properties
to files entering the repository for the first time; see
<a class="xref" href="svn.advanced.props.html#svn.advanced.props.auto" title="Automatic Property Setting">the section called “Automatic Property Setting”</a>.</p>
<p>Continuing our example, if one were to set
the <code class="literal">svn:mime-type</code> property
to <code class="literal">text/html</code> on
file <code class="filename">foo.html</code>, Apache would properly
tell your web browser to render the file as HTML. One
could also attach proper <code class="literal">image/*</code>
MIME-type properties to image files and ultimately get an
entire web site to be viewable directly from a repository!
There's generally no problem with this, as long as the web
site doesn't contain any dynamically generated
content.</p>
</div>
<div class="sect4" title="Customizing the look">
<div class="titlepage">
<div>
<div>
<h5 class="title"><a id="svn.serverconfig.httpd.extra.browsing.xslt"></a>Customizing the look</h5>
</div>
</div>
</div>
<p>You generally will get more use out of URLs to
versioned files—after all, that's where the
interesting content tends to lie. But you might have
occasion to browse a Subversion directory listing, where
you'll quickly note that the generated HTML used to
display that listing is very basic, and certainly not
intended to be aesthetically pleasing (or even
interesting). To enable customization of these directory
displays, Subversion provides an XML index feature. A
single <code class="literal">SVNIndexXSLT</code> directive in your
repository's <code class="literal">Location</code> block of
<code class="filename">httpd.conf</code> will
instruct <span class="command"><strong>mod_dav_svn</strong></span> to generate XML
output when displaying a directory listing, and to
reference the XSLT stylesheet of your choice:</p>
<div class="informalexample">
<pre class="programlisting">
<Location /svn>
DAV svn
SVNParentPath /var/svn
SVNIndexXSLT "/svnindex.xsl"
…
</Location>
</pre>
</div>
<p>Using the <code class="literal">SVNIndexXSLT</code> directive
and a creative XSLT stylesheet, you can make your
directory listings match the color schemes and imagery
used in other parts of your web site. Or, if you'd
prefer, you can use the sample stylesheets provided in the
Subversion source distribution's
<code class="filename">tools/xslt/</code> directory.
Keep in mind that the path provided to the
<code class="literal">SVNIndexXSLT</code> directory is actually a
URL path—browsers need to be able to read your
stylesheets to make use of them!</p>
</div>
<div class="sect4" title="Listing repositories">
<div class="titlepage">
<div>
<div>
<h5 class="title"><a id="svn.serverconfig.httpd.extra.browsing.reposlisting"></a>Listing repositories</h5>
</div>
</div>
</div>
<p>If you're serving a collection of repositories from a
single URL via the <code class="literal">SVNParentPath</code>
directive, then it's also possible to have Apache display
all available repositories to a web browser. Just
activate the <code class="literal">SVNListParentPath</code>
directive:</p>
<div class="informalexample">
<pre class="programlisting">
<Location /svn>
DAV svn
SVNParentPath /var/svn
SVNListParentPath on
…
</Location>
</pre>
</div>
<p>If a user now points her web browser to the
URL <code class="literal">http://host.example.com/svn/</code>,
she'll see a list of all Subversion repositories sitting
in <code class="filename">/var/svn</code>. Obviously, this can be
a security problem, so this feature is turned off by
default.</p>
</div>
</div>
<div class="sect3" title="Apache logging">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="svn.serverconfig.httpd.extra.logging"></a>Apache logging</h4>
</div>
</div>
</div>
<p>Because Apache is an HTTP server at heart, it contains
fantastically flexible logging features. It's beyond the
scope of this book to discuss all of the ways logging can be
configured, but we should point out that even the most
generic <code class="filename">httpd.conf</code> file will cause
Apache to produce two logs:
<code class="filename">error_log</code>
and <code class="filename">access_log</code>. These logs may appear
in different places, but are typically created in the
logging area of your Apache installation. (On Unix, they
often live
in <code class="filename">/usr/local/apache2/logs/</code>.)</p>
<p>The <code class="filename">error_log</code> describes any internal
errors that Apache runs into as it works.
The <code class="filename">access_log</code> file records every
incoming HTTP request received by Apache. This makes it
easy to see, for example, which IP addresses Subversion
clients are coming from, how often particular clients use
the server, which users are authenticating properly, and
which requests succeed or fail.</p>
<p>Unfortunately, because HTTP is a stateless protocol,
even the simplest Subversion client operation generates
multiple network requests. It's very difficult to look at
the <code class="filename">access_log</code> and deduce what the
client was doing—most operations look like a series
of cryptic <code class="literal">PROPPATCH</code>, <code class="literal">GET</code>,
<code class="literal">PUT</code>, and <code class="literal">REPORT</code>
requests. To make things worse, many client operations send
nearly identical series of requests, so it's even harder to
tell them apart.</p>
<p><span class="command"><strong>mod_dav_svn</strong></span>, however, can come to
your aid. By activating an <span class="quote">“<span class="quote">operational
logging</span>”</span> feature, you can
ask <span class="command"><strong>mod_dav_svn</strong></span> to create a separate log
file describing what sort of high-level operations your
clients are performing.</p>
<p>To do this, you need to make use of
Apache's <code class="literal">CustomLog</code> directive (which is
explained in more detail in Apache's own documentation).
Be sure to invoke this
directive <span class="emphasis"><em>outside</em></span> your
Subversion <code class="literal">Location</code> block:</p>
<div class="informalexample">
<pre class="programlisting">
<Location /svn>
DAV svn
…
</Location>
CustomLog logs/svn_logfile "%t %u %{SVN-ACTION}e" env=SVN-ACTION
</pre>
</div>
<p>In this example, we're asking Apache to create a special
logfile, <code class="filename">svn_logfile</code>, in the standard
Apache <code class="filename">logs</code> directory.
The <code class="literal">%t</code> and <code class="literal">%u</code>
variables are replaced by the time and username of the
request, respectively. The really important parts are the
two instances of <code class="literal">SVN-ACTION</code>.
When Apache sees that variable, it substitutes the value of
the <code class="literal">SVN-ACTION</code> environment variable,
which is automatically set by <span class="command"><strong>mod_dav_svn</strong></span>
whenever it detects a high-level client action.</p>
<p>So, instead of having to interpret a
traditional <code class="filename">access_log</code> like
this:</p>
<div class="informalexample">
<pre class="programlisting">
[26/Jan/2007:22:25:29 -0600] "PROPFIND /svn/calc/!svn/vcc/default HTTP/1.1" 207 398
[26/Jan/2007:22:25:29 -0600] "PROPFIND /svn/calc/!svn/bln/59 HTTP/1.1" 207 449
[26/Jan/2007:22:25:29 -0600] "PROPFIND /svn/calc HTTP/1.1" 207 647
[26/Jan/2007:22:25:29 -0600] "REPORT /svn/calc/!svn/vcc/default HTTP/1.1" 200 607
[26/Jan/2007:22:25:31 -0600] "OPTIONS /svn/calc HTTP/1.1" 200 188
[26/Jan/2007:22:25:31 -0600] "MKACTIVITY /svn/calc/!svn/act/e6035ef7-5df0-4ac0-b811-4be7c823f998 HTTP/1.1" 201 227
…
</pre>
</div>
<p>you can peruse a much more
intelligible <code class="filename">svn_logfile</code> like
this:</p>
<div class="informalexample">
<pre class="programlisting">
[26/Jan/2007:22:24:20 -0600] - get-dir /tags r1729 props
[26/Jan/2007:22:24:27 -0600] - update /trunk r1729 depth=infinity
[26/Jan/2007:22:25:29 -0600] - status /trunk/foo r1729 depth=infinity
[26/Jan/2007:22:25:31 -0600] sally commit r1730
</pre>
</div>
<p>In addition to the <code class="literal">SVN-ACTION</code>
environment variable, <span class="command"><strong>mod_dav_svn</strong></span> also
populates the <code class="literal">SVN-REPOS</code>
and <code class="literal">SVN-REPOS-NAME</code> variables, which carry
the filesystem path to the repository and the basename
thereof, respectively. You might wish to include references
to one or both of these variables in
your <code class="literal">CustomLog</code> format string, too,
especially if you are combining usage information from
multiple repositories into a single log file. For an
exhaustive list of all actions logged, see
<a class="xref" href="svn.serverconfig.operational-logging.html" title="High-level Logging">the section called “High-level Logging”</a>.</p>
<p>Obviously, the more information that Apache logs about
your Subversion activities, the more disk space on your
server those logs consume. It is non uncommon for
high-traffic Subversion servers to generate many gigabytes
of log information daily. Obviously, logs are only valuable
if they can be meaningfully processed, and huge log files
can quickly become unwieldy. There are various standard
approaches to Apache HTTP Server log management which are
outside the scope of this book. Administrators are
encouraged to use the log rotation and archival approach
which works best for them.</p>
<p>But what if Subversion is simply generating too much log
information to be useful? For example, in
<a class="xref" href="svn.serverconfig.httpd.html#svn.serverconfig.httpd.perf.bulk-updates" title="Bulk updates">the section called “Bulk updates”</a>,
we mentioned that certain approaches that Subversion clients
may take to checkouts and other update-style operations can
cause rapid growth of your server logs as requests for
individual pieces of the update data set are individually
logged (whereas in previous version of Subversion, they
might not have been). In this case, you might consider
using some Apache configuration magic to selectively silence
some of that log activity.</p>
<p>Apache HTTP Server's
<code class="literal">mod_setenvif</code> module offers
a <code class="literal">SetEnvIf</code> directive which is handy for
conditionally setting environment variables. And as it
turns out, the <code class="literal">CustomLog</code> directive can be
told to conditionally log requests based on the state of
environment variables. The following is a sample
configuration which instructs the server
to <span class="emphasis"><em>not</em></span> log <code class="literal">GET</code>
and <code class="literal">PROPFIND</code> requests aimed at private
Subversion URLs.</p>
<div class="informalexample">
<pre class="programlisting">
# Matches everything, just to initialize the "in_repos" variable.
SetEnvIf Request_URI "^" in_repos=0
# Set "in_repos" if this is a request for a private Subversion URL.
SetEnvIf Request_URI "/!svn/" in_repos=1
# Set "do_not_log" for non-public request types we don't care to log.
SetEnvIf Request_Method "GET" do_not_log
SetEnvIf Request_Method "PROPFIND" do_not_log
# Unset "do_not_log" for URLs that aren't private Subversion URLs.
SetEnvIf in_repos 0 !do_not_log
# Log requests, but only if "do_not_log" isn't set.
CustomLog logs/access_log env=!do_not_log
</pre>
</div>
<p>Using this configuration, <span class="command"><strong>httpd</strong></span> would
still log <code class="literal">GET</code> requests aimed at public
Subversion URLs. These are the sorts of requests generated
by a web browser as someone navigates the repository
directly. But <code class="literal">GET</code>
and <code class="literal">PROPFIND</code> requests aimed at so-called
"private" Subversion URLs—which are the very sorts of
requests used to fetch each and every individual file during
a checkout operation—won't get logged.</p>
</div>
<div class="sect3" title="Write-through proxying">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="svn.serverconfig.httpd.extra.writethruproxy"></a>Write-through proxying</h4>
</div>
</div>
</div>
<p>
<a id="idp16663856" class="indexterm"></a>
<a id="idp16665776" class="indexterm"></a>
<a id="idp16667680" class="indexterm"></a>One of the nice advantages of using Apache as a
Subversion server is that it can be set up for simple
replication. For example, suppose that your team is
distributed across four offices around the globe. The
Subversion repository can exist only in one of those
offices, which means the other three offices will not enjoy
accessing it—they're likely to experience
significantly slower traffic and response times when
updating and committing code. A powerful solution is to set
up a system consisting of one <em class="firstterm">master</em>
Apache server and several <em class="firstterm">slave</em>
Apache servers. If you place a slave server in each office,
users can check out a working copy from whichever slave
is closest to them. All read requests go to their local
slave. Write requests get automatically routed to the
single master server. When the commit completes, the master
then automatically <span class="quote">“<span class="quote">pushes</span>”</span> the new revision to
each slave server using the <span class="command"><strong>svnsync</strong></span>
replication tool.</p>
<p>This configuration creates a huge perceptual speed
increase for your users, because Subversion client traffic
is typically 80–90% read requests. And if those
requests are coming from a <span class="emphasis"><em>local</em></span>
server, it's a huge win.</p>
<p>In this section, we'll walk you through a standard setup
of this single-master/multiple-slave system. However, keep
in mind that your servers must be running at least Apache
2.2.0 (with <span class="command"><strong>mod_proxy</strong></span> loaded) and
Subversion 1.5 (<span class="command"><strong>mod_dav_svn</strong></span>).</p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25">
<img alt="[Note]" src="images/note.png" />
</td>
<th align="left">Note</th>
</tr>
<tr>
<td align="left" valign="top">
<p>Ours is just one example of how you might setup a
Subversion write-through proxy configuration. There are
other approaches. For example, rather than having the
master server push changes out to every slave server, the
slaves could periodically pull those changes from the
master. Or perhaps the master could push changes to a
single slave, which then pushes the same change to the
next slave, and so on down the line. Administrators are
encouraged to use this section for basic understanding
of what happens in a Subversion WebDAV proxy deployment
scenario, and then implement the specific approach that
works best for their organization.</p>
</td>
</tr>
</table>
</div>
<div class="sect4" title="Configure the servers">
<div class="titlepage">
<div>
<div>
<h5 class="title"><a id="svn.serverconfig.httpd.extra.writethruproxy.configure"></a>Configure the servers</h5>
</div>
</div>
</div>
<p>First, configure your master server's
<code class="filename">httpd.conf</code> file in the usual way.
Make the repository available at a certain URI location,
and configure authentication and authorization however
you'd like. After that's done, configure each of your
<span class="quote">“<span class="quote">slave</span>”</span> servers in the exact same way, but
add the special <code class="literal">SVNMasterURI</code> directive
to the block:</p>
<div class="informalexample">
<pre class="programlisting">
<Location /svn>
DAV svn
SVNPath /var/svn/repos
SVNMasterURI http://master.example.com/svn
…
</Location>
</pre>
</div>
<p>This new directive tells a slave server to redirect
all write requests to the master. (This is done
automatically via Apache's <span class="command"><strong>mod_proxy</strong></span>
module.) Ordinary read requests, however, are still
serviced by the slaves. Be sure that your master and
slave servers all have matching authentication and
authorization configurations; if they fall out of sync,
it can lead to big headaches.</p>
<p>Next, we need to deal with the problem of infinite
recursion. With the current configuration, imagine what
will happen when a Subversion client performs a commit to
the master server. After the commit completes, the server
uses <span class="command"><strong>svnsync</strong></span> to replicate the new
revision to each slave. But because
<span class="command"><strong>svnsync</strong></span> appears to be just another
Subversion client performing a commit, the slave will
immediately attempt to proxy the incoming write request
back to the master! Hilarity ensues.</p>
<p>The solution to this problem is to have the master
push revisions to a different
<code class="literal"><Location></code> on the slaves. This
location is configured to <span class="emphasis"><em>not</em></span> proxy
write requests at all, but to accept normal commits from
(and only from) the master's IP address:</p>
<div class="informalexample">
<pre class="programlisting">
<Location /svn-proxy-sync>
DAV svn
SVNPath /var/svn/repos
Order deny,allow
Deny from all
# Only let the server's IP address access this Location:
Allow from 10.20.30.40
…
</Location>
</pre>
</div>
</div>
<div class="sect4" title="Set up replication">
<div class="titlepage">
<div>
<div>
<h5 class="title"><a id="svn.serverconfig.httpd.extra.writethruproxy.replicate"></a>Set up replication</h5>
</div>
</div>
</div>
<p>Now that you've configured
your <code class="literal">Location</code> blocks on master and
slaves, you need to configure the master to replicate to
the slaves. Our walkthough uses <span class="command"><strong>svnsync</strong></span>,
which is covered in more detail in
<a class="xref" href="svn.reposadmin.maint.html#svn.reposadmin.maint.replication.svnsync" title="Replication with svnsync">the section called “Replication with svnsync”</a>.</p>
<p>First, make sure that each slave repository has a
<code class="filename">pre-revprop-change</code> hook script which
allows remote revision property changes. (This is
standard procedure for being on the receiving end of
<span class="command"><strong>svnsync</strong></span>.) Then log into the master
server and configure each of the slave repository URIs to
receive data from the master repository on the local
disk:</p>
<div class="informalexample">
<pre class="screen">
$ svnsync init http://slave1.example.com/svn-proxy-sync \
file:///var/svn/repos
Copied properties for revision 0.
$ svnsync init http://slave2.example.com/svn-proxy-sync \
file:///var/svn/repos
Copied properties for revision 0.
$ svnsync init http://slave3.example.com/svn-proxy-sync \
file:///var/svn/repos
Copied properties for revision 0.
# Perform the initial replication
$ svnsync sync http://slave1.example.com/svn-proxy-sync \
file:///var/svn/repos
Transmitting file data ....
Committed revision 1.
Copied properties for revision 1.
Transmitting file data .......
Committed revision 2.
Copied properties for revision 2.
…
$ svnsync sync http://slave2.example.com/svn-proxy-sync \
file:///var/svn/repos
Transmitting file data ....
Committed revision 1.
Copied properties for revision 1.
Transmitting file data .......
Committed revision 2.
Copied properties for revision 2.
…
$ svnsync sync http://slave3.example.com/svn-proxy-sync \
file:///var/svn/repos
Transmitting file data ....
Committed revision 1.
Copied properties for revision 1.
Transmitting file data .......
Committed revision 2.
Copied properties for revision 2.
…
</pre>
</div>
<p>After this is done, we configure the master server's
<code class="literal">post-commit</code> hook script to invoke
<span class="command"><strong>svnsync</strong></span> on each slave server:</p>
<div class="informalexample">
<pre class="programlisting">
#!/bin/sh
# Post-commit script to replicate newly committed revision to slaves
svnsync sync http://slave1.example.com/svn-proxy-sync \
file:///var/svn/repos > /dev/null 2>&1 &
svnsync sync http://slave2.example.com/svn-proxy-sync \
file:///var/svn/repos > /dev/null 2>&1 &
svnsync sync http://slave3.example.com/svn-proxy-sync \
file:///var/svn/repos > /dev/null 2>&1 &
</pre>
</div>
<p>The extra bits on the end of each line aren't
necessary, but they're a sneaky way to allow the sync
commands to run in the background so that the Subversion
client isn't left waiting forever for the commit to
finish. In addition to this
<code class="literal">post-commit</code> hook, you'll need a
<code class="literal">post-revprop-change</code> hook as well so
that when a user, say, modifies a log message, the slave
servers get that change also:</p>
<div class="informalexample">
<pre class="programlisting">
#!/bin/sh
# Post-revprop-change script to replicate revprop-changes to slaves
REV=${2}
svnsync copy-revprops http://slave1.example.com/svn-proxy-sync \
file:///var/svn/repos \
-r ${REV} > /dev/null 2>&1 &
svnsync copy-revprops http://slave2.example.com/svn-proxy-sync \
file:///var/svn/repos \
-r ${REV} > /dev/null 2>&1 &
svnsync copy-revprops http://slave3.example.com/svn-proxy-sync \
file:///var/svn/repos \
-r ${REV} > /dev/null 2>&1 &
</pre>
</div>
<p>The only thing we've left out here is what to do about
user-level locks (of the <span class="command"><strong>svn lock</strong></span>
variety). Locks are enforced by the master server during
commit operations; but all the information about locks is
distributed during read operations such as <span class="command"><strong>svn
update</strong></span> and <span class="command"><strong>svn status</strong></span> by the
slave server. As such, a fully functioning proxy setup
needs to perfectly replicate lock information from the
master server to the slave servers. Unfortunately, most
of the mechanisms that one might employ to accomplish this
replication fall short in one way or
another<sup>[<a id="idp16710208" href="#ftn.idp16710208" class="footnote">71</a>]</sup>. Many teams
don't use Subversion's locking features at all, so this
may be a nonissue for you. Sadly, for those teams which
do use locks, we have no recommendations on how to
gracefully work around this shortcoming.</p>
</div>
<div class="sect4" title="Caveats">
<div class="titlepage">
<div>
<div>
<h5 class="title"><a id="svn.serverconfig.httpd.extra.writethruproxy.caveats"></a>Caveats</h5>
</div>
</div>
</div>
<p>Your master/slave replication system should now be
ready to use. A couple of words of warning are in order,
however. Remember that this replication isn't entirely
robust in the face of computer or network crashes. For
example, if one of the automated
<span class="command"><strong>svnsync</strong></span> commands fails to complete for
some reason, the slaves will begin to fall behind. For
example, your remote users will see that they've committed
revision 100, but then when they run <span class="command"><strong>svn
update</strong></span>, their local server will tell them that
revision 100 doesn't yet exist! Of course, the problem
will be automatically fixed the next time another commit
happens and the subsequent <span class="command"><strong>svnsync</strong></span> is
successful—the sync will replicate all waiting
revisions. But still, you may want to set up some sort of
out-of-band monitoring to notice synchronization failures
and force <span class="command"><strong>svnsync</strong></span> to run when things go
wrong.</p>
<p>Another limitation of the write-through proxy
deployment model involves version mismatches—of the
version of Subversion which is installed, that
is—between the master and slave servers. Each new
release of Subversion may (and often does) add new
features to the network protocol used between the clients
and servers. Since feature negotiation happens against
the slave, it is the slave's protocol version and feature
set which is used. But write operations are passed
through to the master server quite literally. Therefore,
there is always a risk that the slave server will answer a
feature negotiation request from the client in way that is
true for the slave, but untrue for the master if the
master is running an older version of Subversion. This
could result in the client trying to use a new feature
that the master doesn't understand, and failing. There
are a couple of known problems of this sort in Subversion
1.7, which introduced a major revision of its HTTP
protocol. If you are deploying a Subversion 1.7 slave
server in front of a pre-1.7 master, you'll want to
configure your slave server's
Subversion <code class="literal"><Location></code> block with
the <code class="literal">SVNAdvertiseV2Protocol Off</code>
directive.</p>
<div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25">
<img alt="[Tip]" src="images/tip.png" />
</td>
<th align="left">Tip</th>
</tr>
<tr>
<td align="left" valign="top">
<p>For the best results possible, try to run the same
version of Subversion on your master and slave
servers.</p>
</td>
</tr>
</table>
</div>
<div class="sidebar" title="Can We Set Up Replication with svnserve?">
<div class="titlepage">
<div>
<div>
<p class="title">
<strong>Can We Set Up Replication with svnserve?</strong>
</p>
</div>
</div>
</div>
<p>If you're using <span class="command"><strong>svnserve</strong></span> instead
of Apache as your server, you can certainly configure
your repository's hook scripts to invoke
<span class="command"><strong>svnsync</strong></span> as we've shown here, thereby
causing automatic replication from master to slaves.
Unfortunately, at the time of this writing there is no way to
make slave <span class="command"><strong>svnserve</strong></span> servers
automatically proxy write requests back to the master
server. This means your users would only be able to
check out read-only working copies from the slave
servers. You'd have to configure your slave servers to
disallow write access completely. This might be useful
for creating read-only <span class="quote">“<span class="quote">mirrors</span>”</span> of popular
open source projects, but it's not a transparent
proxying system.</p>
</div>
</div>
</div>
<div class="sect3" title="Other Apache features">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="svn.serverconfig.httpd.extra.other"></a>Other Apache features</h4>
</div>
</div>
</div>
<p>Several of the features already provided by Apache in
its role as a robust web server can be leveraged for
increased functionality or security in Subversion as well.
The Subversion client is able to use SSL (the Secure Sockets
Layer, discussed earlier). If your Subversion client is
built to support SSL, it can access your Apache server
using <code class="literal">https://</code> and enjoy a high-quality
encrypted network session.</p>
<p>Equally useful are other features of the Apache and
Subversion relationship, such as the ability to specify a
custom port (instead of the default HTTP port 80) or a
virtual domain name by which the Subversion repository
should be accessed, or the ability to access the repository
through an HTTP proxy.</p>
<p>Finally, because <span class="command"><strong>mod_dav_svn</strong></span> is
speaking a subset of the WebDAV/DeltaV protocol, it's
possible to access the repository via third-party DAV
clients. Most modern operating systems (Win32, OS X, and
Linux) have the built-in ability to mount a DAV server as a
standard network <span class="quote">“<span class="quote">shared folder.</span>”</span> This is a
complicated topic, but also wondrous when implemented. For
details, read <a class="xref" href="svn.webdav.html" title="Appendix C. WebDAV and Autoversioning">Appendix C, <em>WebDAV and Autoversioning</em></a>.</p>
<p>Note that there are a number of other small tweaks one
can make to <span class="command"><strong>mod_dav_svn</strong></span> that perhaps do
not merit extensive coverage. For those interested,
however, we provide a complete list of
all <code class="filename">httpd.conf</code> directives
to which <span class="command"><strong>mod_dav_svn</strong></span> responds in
<a class="xref" href="svn.serverconfig.httpd.html#svn.serverconfig.httpd.ref.mod_dav_svn" title="mod_dav_svn configuration directives">the section called “mod_dav_svn configuration directives”</a>.</p>
</div>
</div>
<div class="sect2" title="Subversion Apache HTTP Server Configuration Reference">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="svn.serverconfig.httpd.ref"></a>Subversion Apache HTTP Server Configuration Reference</h3>
</div>
</div>
</div>
<p>In the previous sections, we've mentioned numerous
directives that administrators can use in their
<code class="filename">httpd.conf</code> files to enable and configure
their Subversion server offering, introducing each directive
as we also introduce the functionality it toggles. In this
section, we'll quickly summarize <span class="emphasis"><em>all</em></span> the
configuration directives supported by both of the Apache HTTP
Server modules which are provided as part of the standard
Subversion distribution.</p>
<div class="sect3" title="mod_dav_svn configuration directives">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="svn.serverconfig.httpd.ref.mod_dav_svn"></a>mod_dav_svn configuration directives</h4>
</div>
</div>
</div>
<p>The following configuration directives are recognized
and supported by Subversion's Apache HTTP Server module,
<span class="command"><strong>mod_dav_svn</strong></span>.</p>
<div class="variablelist">
<dl>
<dt>
<span class="term">
<code class="literal">DAV svn</code>
</span>
</dt>
<dd>
<p>Must be included in any
<code class="literal">Directory</code> or <code class="literal">Location</code>
block for a Subversion repository. It
tells <span class="command"><strong>httpd</strong></span> to use the Subversion
backend for <code class="literal">mod_dav</code> to handle all
requests.</p>
</dd>
<dt>
<span class="term">
<code class="literal">SVNActivitiesDB
<em class="replaceable"><code>directory-path</code></em></code>
</span>
</dt>
<dd>
<p>Specifies the location in the filesystem where the
activities database should be stored. By default,
<span class="command"><strong>mod_dav_svn</strong></span> creates and uses a
directory in the repository
called <code class="filename">dav/activities.d</code>. The
path specified with this option must be an absolute
path.</p>
<p>If specified for
an <code class="literal">SVNParentPath</code>
area, <span class="command"><strong>mod_dav_svn</strong></span> appends the
basename of the repository to the path specified here.
For example:</p>
<div class="informalexample">
<pre class="screen">
<Location /svn>
DAV svn
# any "/svn/foo" URL will map to a repository in
# /net/svn.nfs/repositories/foo
SVNParentPath "/net/svn.nfs/repositories"
# any "/svn/foo" URL will map to an activities db in
# /var/db/svn/activities/foo
SVNActivitiesDB "/var/db/svn/activities"
</Location>
</pre>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">SVNAdvertiseV2Protocol On|Off</code>
</span>
</dt>
<dd>
<p>New to Subversion 1.7, this toggles
whether <span class="command"><strong>mod_dav_svn</strong></span> advertises its
support for the new version of its HTTP protocol also
introduced in that version. Most admins will not wish
to use this directive (which is <code class="literal">On</code>
by default), choosing instead to enjoy the performance
benefits that the new protocol offers. However, whena
configuring a server as a write-through proxy to
another server which does not support the new
protocol, set this directive's value
to <code class="literal">Off</code>.</p>
</dd>
<dt>
<span class="term">
<code class="literal">SVNAllowBulkUpdates On|Off</code>
</span>
</dt>
<dd>
<p>Toggles support for all-inclusive
responses to update-style <code class="literal">REPORT</code>
requests. Subversion clients use
<code class="literal">REPORT</code> requests to get information
about directory tree checkouts and updates from
<span class="command"><strong>mod_dav_svn</strong></span>. They can ask the
server to send that information in one of two ways:
with the entirety of the tree's information in one
massive response, or with a
<em class="firstterm">skelta</em> (a skeletal
representation of a tree delta) which contains just
enough information for the client to know what
<span class="emphasis"><em>additional</em></span> data to request from
the server. When this directive is included with a
value of <code class="literal">Off</code>,
<span class="command"><strong>mod_dav_svn</strong></span> will only ever respond
to these <code class="literal">REPORT</code> requests with
skelta responses, regardless of the type of responses
requested by the client.</p>
<p>Most folks won't need to use this directive at
all. It primarily exists for administrators who
wish—for security or auditing reasons—to
force Subversion clients to fetch individually all the
files and directories needed for updates and
checkouts, thus leaving an audit trail of
<code class="literal">GET</code> and <code class="literal">PROPFIND</code>
requests in Apache's logs. The default value of this
directive is <code class="literal">On</code>.</p>
</dd>
<dt>
<span class="term">
<code class="literal">SVNAutoversioning On|Off</code>
</span>
</dt>
<dd>
<p>When its value is
<code class="literal">On</code>, allows write requests from
WebDAV clients to result in automatic commits. A
generic log message is auto-generated and attached to
each revision. If you enable autoversioning, you'll
likely want to set <code class="literal">ModMimeUsePathInfo
On</code> so that <code class="literal">mod_mime</code> can
set <code class="literal">svn:mime-type</code> to the correct
MIME type automatically (as best as
<code class="literal">mod_mime</code> is able to, of course).
For more information, see <a class="xref" href="svn.webdav.html" title="Appendix C. WebDAV and Autoversioning">Appendix C, <em>WebDAV and Autoversioning</em></a>. The default value of this
directive is <code class="literal">Off</code>.</p>
</dd>
<dt>
<span class="term">
<code class="literal">SVNCacheFullTexts On|Off</code>
</span>
</dt>
<dd>
<p>When set to <code class="literal">On</code>, this tells
Subversion to cache content fulltexts if sufficient
in-memory cache is available, which could offer a
significant performance benefit to the server. (See
also the <code class="literal">SVNInMemoryCacheSize</code>
directive.) The default value of this directive
is <code class="literal">Off</code>.</p>
</dd>
<dt>
<span class="term">
<code class="literal">SVNCacheTextDeltas On|Off</code>
</span>
</dt>
<dd>
<p>When set to <code class="literal">On</code>, this tells
Subversion to cache content deltas if sufficient
in-memory cache is available, which could offer a
significant performance benefit to the server. (See
also the <code class="literal">SVNInMemoryCacheSize</code>
directive.) The default value of this directive
is <code class="literal">Off</code>.</p>
</dd>
<dt>
<span class="term">
<code class="literal">SVNCompressionLevel
<em class="replaceable"><code>level</code></em></code>
</span>
</dt>
<dd>
<p>Specifies the compression level used when sending
file content over the network. A value
of <code class="literal">0</code> disables compression
altogether, and <code class="literal">9</code> is the maximum
value. <code class="literal">5</code> is the default
value.</p>
</dd>
<dt>
<span class="term">
<code class="literal">SVNIndexXSLT
<em class="replaceable"><code>directory-path</code></em></code>
</span>
</dt>
<dd>
<p>Specifies the URI of an XSL transformation for
directory indexes. This directive is optional.</p>
</dd>
<dt>
<span class="term">
<code class="literal">SVNInMemoryCacheSize
<em class="replaceable"><code>size</code></em></code>
</span>
</dt>
<dd>
<p>Specifies the maximum size (in kbytes) per process
of Subversion's in-memory object cache. The default
value is <code class="literal">16384</code>; use a value
of <code class="literal">0</code> to deactivate this cache
altogether.</p>
</dd>
<dt>
<span class="term">
<code class="literal">SVNListParentPath On|Off</code>
</span>
</dt>
<dd>
<p>When set to <code class="literal">On</code>, allows
a <code class="literal">GET</code>
of <code class="literal">SVNParentPath</code>, which results in
a listing of all repositories under that path. The
default setting is
<code class="literal">Off</code>.</p>
</dd>
<dt>
<span class="term">
<code class="literal">SVNMasterURI
<em class="replaceable"><code>url</code></em></code>
</span>
</dt>
<dd>
<p>Specifies a URI to the master Subversion
repository (used for a write-through proxy).</p>
</dd>
<dt>
<span class="term">
<code class="literal">SVNParentPath
<em class="replaceable"><code>directory-path</code></em></code>
</span>
</dt>
<dd>
<p>Specifies the location in the filesystem of a
parent directory whose child directories are
Subversion repositories. In a configuration block for
a Subversion repository, either this directive or
<code class="literal">SVNPath</code> must be present, but not
both.</p>
</dd>
<dt>
<span class="term">
<code class="literal">SVNPath
<em class="replaceable"><code>directory-path</code></em></code>
</span>
</dt>
<dd>
<p>Specifies the location in the
filesystem for a Subversion repository's files. In a
configuration block for a Subversion repository,
either this directive or
<code class="literal">SVNParentPath</code> must be present, but
not both.</p>
</dd>
<dt>
<span class="term">
<code class="literal">SVNPathAuthz On|Off|short_circuit</code>
</span>
</dt>
<dd>
<p>Controls path-based authorization by enabling
subrequests (<code class="literal">On</code>), disabling
subrequests (<code class="literal">Off</code>; see <a class="xref" href="svn.serverconfig.httpd.html#svn.serverconfig.httpd.authz.pathauthzoff" title="Disabling path-based checks">the section called “Disabling path-based checks”</a>),
or querying <span class="command"><strong>mod_authz_svn</strong></span> directly
(<code class="literal">short_circuit</code>). The default
value of this directive is <code class="literal">On</code>.</p>
</dd>
<dt>
<span class="term">
<code class="literal">SVNReposName
<em class="replaceable"><code>name</code></em></code>
</span>
</dt>
<dd>
<p>Specifies the name of a Subversion repository for
use in <code class="literal">HTTP GET</code> responses. This
value will be prepended to the title of all directory
listings (which are served when you navigate to a
Subversion repository with a web browser). This
directive is optional.</p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25">
<img alt="[Note]" src="images/note.png" />
</td>
<th align="left">Note</th>
</tr>
<tr>
<td align="left" valign="top">
<p>Subversion will not use the repository name as
configured via this directive when trying to match
rules in access control files. The repository names
used in that file's syntax are always derived from
the repository URL. See
<a class="xref" href="svn.serverconfig.pathbasedauthz.html#svn.serverconfig.pathbasedauthz.getting-started" title="Getting Started with Path-Based Access Control">the section called “Getting Started with Path-Based Access Control”</a> for details.</p>
</td>
</tr>
</table>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">SVNSpecialURI
<em class="replaceable"><code>component</code></em></code>
</span>
</dt>
<dd>
<p>Specifies the URI component (namespace) for
special Subversion resources. The default is
<code class="literal">!svn</code>, and most
administrators will never use this directive. Set
this only if there is a pressing need to have a file
named <code class="filename">!svn</code> in your repository.
If you change this on a server already in use, it will
break all of the outstanding working copies, and your
users will hunt you down with pitchforks and flaming
torches.</p>
</dd>
<dt>
<span class="term">
<code class="literal">SVNUseUTF8 On|Off</code>
</span>
</dt>
<dd>
<p>When set to <code class="literal">On</code>,
<span class="command"><strong>mod_dav_svn</strong></span> will communicate with
hook scripts using repository root paths encoded in
UTF-8, and will expect those scripts to likewise
generate output (such as error messages) encoded in
UTF-8. The default value of this option
is <code class="literal">Off</code>, which means
that <span class="command"><strong>mod_dav_svn</strong></span> assumes a 7-bit
ASCII encoding for its hook script interactions. This
option is available as of Subversion 1.8.</p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25">
<img alt="[Note]" src="images/note.png" />
</td>
<th align="left">Note</th>
</tr>
<tr>
<td align="left" valign="top">
<p>Administrators should ensure that the character
set and encoding expectations of hook scripts match
all the ways they might be invoked. For example, if
one repository is served by both <span class="command"><strong>httpd</strong></span>
and <span class="command"><strong>svnserve</strong></span>, <span class="command"><strong>svnserve</strong></span>
should also be configured to use UTF-8 (by setting
an appropriate locale in its environment) if this
option is enabled for <span class="command"><strong>mod_dav_svn</strong></span>.
Also, local filesystem paths containing non-ASCII
characters which will be accessed by those scripts
(such as repository root paths) must be properly
encoded in the filesystem to match the scripts'
expectations.</p>
</td>
</tr>
</table>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3" title="mod_authz_svn configuration directives">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="svn.serverconfig.httpd.ref.mod_authz_svn"></a>mod_authz_svn configuration directives</h4>
</div>
</div>
</div>
<p>The following configuration directives are provided
by <span class="command"><strong>mod_authz_svn</strong></span>, Subversion's path-based
authorization Apache HTTP Server module. For an in-depth
description of using path-based authorization in Subversion,
see <a class="xref" href="svn.serverconfig.pathbasedauthz.html" title="Path-Based Authorization">the section called “Path-Based Authorization”</a>.</p>
<div class="variablelist">
<dl>
<dt>
<span class="term">
<code class="literal">AuthzForceUsernameCase Upper|Lower</code>
</span>
</dt>
<dd>
<p>Set to <code class="literal">Upper</code>
or <code class="literal">Lower</code> to perform case conversion
of the specified sort on the authenticated username
before checking it for authorization. While usernames
are compared in a case-sensitive fashion against those
referenced in the authorization rules file, this
directive can at least normalize variably-cased
usernames into something consistent.</p>
</dd>
<dt>
<span class="term">
<code class="literal">AuthzSVNAccessFile
<em class="replaceable"><code>file-path</code></em></code>
</span>
</dt>
<dd>
<p>Consult <em class="replaceable"><code>file-path</code></em> for
access rules describing the permissions for paths in
Subversion repository.</p>
</dd>
<dt>
<span class="term">
<code class="literal">AuthzSVNAnonymous On|Off</code>
</span>
</dt>
<dd>
<p>Set to <code class="literal">Off</code> to disable two
special-case behaviours of this module: interaction
with the <code class="literal">Satisfy Any</code> directive and
enforcement of the authorization policy even when no
<code class="literal">Require</code> directives are present.
The default value of this directive is
<code class="literal">On</code>.</p>
</dd>
<dt>
<span class="term">
<code class="literal">AuthzSVNAuthoritative On|Off</code>
</span>
</dt>
<dd>
<p>Set to <code class="literal">Off</code> to allow access
control to be passed along to lower modules. The
default value of this directive is
<code class="literal">On</code>.</p>
</dd>
<dt>
<span class="term">
<code class="literal">AuthzSVNNoAuthWhenAnonymousAllowed On|Off</code>
</span>
</dt>
<dd>
<p>Set to <code class="literal">On</code> to suppress
authentication and authorization for requests which
anonymous users are allowed to perform. The default
value of this directive is
<code class="literal">On</code>.</p>
</dd>
</dl>
</div>
</div>
</div>
<div class="footnotes">
<br />
<hr width="100" align="left" />
<div class="footnote">
<p><sup>[<a id="ftn.idp16271712" href="#idp16271712" class="para">66</a>] </sup>See
<a class="ulink" href="http://www.webdav.org/" target="_top">http://www.webdav.org/</a>.</p>
</div>
<div class="footnote">
<p><sup>[<a id="ftn.idp16272976" href="#idp16272976" class="para">67</a>] </sup>They really
hate doing that.</p>
</div>
<div class="footnote">
<p><sup>[<a id="ftn.idp16359776" href="#idp16359776" class="para">68</a>] </sup>See
<a class="ulink" href="http://httpd.apache.org/docs/current/programs/htpasswd.html" target="_top">http://httpd.apache.org/docs/current/programs/htpasswd.html</a>.</p>
</div>
<div class="footnote">
<p><sup>[<a id="ftn.idp16401440" href="#idp16401440" class="para">69</a>] </sup>See
<a class="ulink" href="http://httpd.apache.org/docs/current/programs/htdigest.html" target="_top">http://httpd.apache.org/docs/current/programs/htdigest.html</a>.</p>
</div>
<div class="footnote">
<p><sup>[<a id="ftn.idp16494256" href="#idp16494256" class="para">70</a>] </sup>While self-signed certificates are
still vulnerable to a <span class="quote">“<span class="quote">man-in-the-middle</span>”</span>
attack (before a client sees the certificate for the first
time), such an attack is much more difficult for a casual
observer to pull off, compared to sniffing unprotected
passwords.</p>
</div>
<div class="footnote">
<p><sup>[<a id="ftn.idp16710208" href="#idp16710208" class="para">71</a>] </sup><a class="ulink" href="http://subversion.tigris.org/issues/show_bug.cgi?id=3457" target="_top">http://subversion.tigris.org/issues/show_bug.cgi?id=3457</a> tracks these problems.</p>
</div>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="svn.serverconfig.svnserve.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="svn.serverconfig.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="svn.serverconfig.pathbasedauthz.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">svnserve, a Custom Server </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Path-Based Authorization</td>
</tr>
</table>
</div>
<div xmlns="" id="vcws-footer">
<hr />
<img src="images/cc-by.png" style="float: right;" />
<p>You are reading <em>Version Control with Subversion</em> (for
Subversion 1.8), by Ben Collins-Sussman, Brian W. Fitzpatrick,
and C. Michael Pilato.</p>
<p>This work is licensed under
the <a href="http://creativecommons.org/licenses/by/2.0/">Creative Commons Attribution License v2.0</a>.</p>
<p>To submit comments, corrections, or other contributions to the
text, please visit <a href="http://www.svnbook.com/">http://www.svnbook.com/</a>.</p>
</div>
</body>
</html>
distrib
>
Mageia
>
6
>
i586
>
media
>
core-updates
>
by-pkgid
>
d32d95698a59acd37b394f83dfc217c6
>
files
>
209
