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 http://www.svnbook.com/ for stable versions of this book.

svnserve, a Custom Server

The svnserve program is a lightweight server, capable of speaking to clients over TCP/IP using a custom, stateful protocol. Clients contact an svnserve server by using URLs that begin with the svn:// or svn+ssh:// scheme. This section will explain the different ways of running svnserve, how clients authenticate themselves to the server, and how to configure appropriate access control to your repositories.

Invoking the Server

There are a few different ways to run the svnserve program:

  • Run svnserve as a standalone daemon, listening for requests.

  • Have the Unix inetd daemon temporarily spawn svnserve whenever a request comes in on a certain port.

  • Have SSH invoke a temporary svnserve over an encrypted tunnel.

  • Run svnserve as a Microsoft Windows service.

  • Run svnserve as a launchd job.

The following sections will cover in detail these various deployment options for svnserve.

svnserve as daemon

The easiest option is to run svnserve as a standalone daemon process. Use the -d option for this:

$ svnserve -d
$               # svnserve is now running, listening on port 3690

When running svnserve in daemon mode, you can use the --listen-port and --listen-host options to customize the exact port and hostname to bind to.

Once we successfully start svnserve as explained previously, it makes every repository on your system available to the network. A client needs to specify an absolute path in the repository URL. For example, if a repository is located at /var/svn/project1, a client would reach it via svn://host.example.com/var/svn/project1. To increase security, you can pass the -r option to svnserve, which restricts it to exporting only repositories below that path. For example:

$ svnserve -d -r /var/svn
…

Using the -r option effectively modifies the location that the program treats as the root of the remote filesystem space. Clients then use URLs that have that path portion removed from them, leaving much shorter (and much less revealing) URLs:

$ svn checkout svn://host.example.com/project1
…

svnserve via inetd

If you want inetd to launch the process, you need to pass the -i (--inetd) option. In the following example, we've shown the output from running svnserve -i at the command line, but note that this isn't how you actually start the daemon; see the paragraphs following the example for how to configure inetd to start svnserve.

$ svnserve -i
( success ( 2 2 ( ) ( edit-pipeline svndiff1 absent-entries commit-revprops d\
epth log-revprops atomic-revprops partial-replay ) ) )

When invoked with the --inetd option, svnserve attempts to speak with a Subversion client via stdin and stdout using a custom protocol. This is the standard behavior for a program being run via inetd. The IANA has reserved port 3690 for the Subversion protocol, so on a Unix-like system you can add lines to /etc/services such as these (if they don't already exist):

svn           3690/tcp   # Subversion
svn           3690/udp   # Subversion

If your system is using a classic Unix-like inetd daemon, you can add this line to /etc/inetd.conf:

svn stream tcp nowait svnowner /usr/bin/svnserve svnserve -i

Make sure svnowner is a user that has appropriate permissions to access your repositories. Now, when a client connection comes into your server on port 3690, inetd will spawn an svnserve process to service it. Of course, you may also want to add -r to the configuration line as well, to restrict which repositories are exported.

svnserve via xinetd

Some operating systems provide the xinetd daemon as an alternative to inetd. Fortunately, you can configure svnserve for use with xinetd, too. To do so, you'll need to create a configuration file /etc/xinetd.d/svn with the following contents:

# default: on
# description: Subversion server for the svn protocol
service svn
{
  disabled        = no
  port            = 3690
  socket_type     = stream
  protocol        = tcp
  wait            = no
  user            = subversion
  server          = /usr/local/bin/svnserve
  server_args     = -i -r /path/to/repositories
}

Be sure that your /etc/services configuration file contains the definition of the port used for the svn protocol (as described in the section called “svnserve via inetd”), otherwise the daemon will not start correctly.

In Redhat-based distributions, you then need to activate the new service using chkconfig --add svn. After doing so, you will be able to enable and disable the server using the graphical configuration tools.

svnserve over a tunnel

Another way to invoke svnserve is in tunnel mode, using the -t option. This mode assumes that a remote-service program such as rsh or ssh has successfully authenticated a user and is now invoking a private svnserve process as that user. (Note that you, the user, will rarely, if ever, have reason to invoke svnserve with the -t at the command line; instead, the SSH daemon does so for you.) The svnserve program behaves normally (communicating via stdin and stdout) and assumes that the traffic is being automatically redirected over some sort of tunnel back to the client. When svnserve is invoked by a tunnel agent like this, be sure that the authenticated user has full read and write access to the repository database files. It's essentially the same as a local user accessing the repository via file:// URLs.

This option is described in much more detail later in this chapter in the section called “Tunneling over SSH”.

svnserve as a Windows service

If your Windows system is a descendant of Windows NT (Windows 2000 or newer), you can run svnserve as a standard Windows service. This is typically a much nicer experience than running it as a standalone daemon with the --daemon (-d) option. Using daemon mode requires launching a console, typing a command, and then leaving the console window running indefinitely. A Windows service, however, runs in the background, can start at boot time automatically, and can be started and stopped using the same consistent administration interface as other Windows services.

You'll need to define the new service using the command-line tool SC.EXE. Much like the inetd configuration line, you must specify an exact invocation of svnserve for Windows to run at startup time:

C:\> sc create svn
        binpath= "C:\svn\bin\svnserve.exe --service -r C:\repos"
        displayname= "Subversion Server"
        depend= Tcpip
        start= auto

This defines a new Windows service named svn which executes a particular svnserve.exe command when started (in this case, rooted at C:\repos). There are a number of caveats in the prior example, however.

First, notice that the svnserve.exe program must always be invoked with the --service option. Any other options to svnserve must then be specified on the same line, but you cannot add conflicting options such as --daemon (-d), --tunnel, or --inetd (-i). Options such as -r or --listen-port are fine, though. Second, be careful about spaces when invoking the SC.EXE command: the key= value patterns must have no spaces between key= and must have exactly one space before the value. Lastly, be careful about spaces in your command line to be invoked. If a directory name contains spaces (or other characters that need escaping), place the entire inner value of binpath in double quotes, by escaping them:

C:\> sc create svn
        binpath= "\"C:\program files\svn\bin\svnserve.exe\" --service -r C:\repos"
        displayname= "Subversion Server"
        depend= Tcpip
        start= auto

Also note that the word binpath is misleading—its value is a command line, not the path to an executable. That's why you need to surround it with quotes if it contains embedded spaces.

Once the service is defined, it can be stopped, started, or queried using standard GUI tools (the Services administrative control panel), or at the command line:

C:\> net stop svn
C:\> net start svn

The service can also be uninstalled (i.e., undefined) by deleting its definition: sc delete svn. Just be sure to stop the service first! The SC.EXE program has many other subcommands and options; run sc /? to learn more about it.

svnserve as a launchd job

Mac OS X (10.4 and higher) uses launchd to manage processes (including daemons) both system-wide and per-user. A launchd job is specified by parameters in an XML property list file, and the launchctl command is used to manage the lifecycle of those jobs.

When configured to run as a launchd job, svnserve is automatically launched on demand whenever incoming Subversion svn:// network traffic needs to be handled. This is far more convenient than a configuration which requires you to manually invoke svnserve as a long-running background process.

To configure svnserve as a launchd job, first create a job definition file named /Library/LaunchDaemons/org.apache.subversion.svnserve.plist. Example 6.1, “A sample svnserve launchd job definition” provides an example of such a file.

Example 6.1. A sample svnserve launchd job definition

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
    "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
        <key>Label</key>
        <string>org.apache.subversion.svnserve</string>
        <key>ServiceDescription</key>
        <string>Host Subversion repositories using svn:// scheme</string>
        <key>ProgramArguments</key>
        <array>
            <string>/usr/bin/svnserve</string>
            <string>--inetd</string>
            <string>--root=/var/svn</string>
        </array>
        <key>UserName</key>
        <string>svn</string>
        <key>GroupName</key>
        <string>svn</string>
        <key>inetdCompatibility</key>
        <dict>
            <key>Wait</key>
            <false/>
        </dict>
        <key>Sockets</key>
        <dict>
            <key>Listeners</key>
            <array>
                <dict>
                    <key>SockServiceName</key>
                    <string>svn</string>
                    <key>Bonjour</key>
                    <true/>
                </dict>
            </array>
        </dict>
    </dict>
</plist>

[Warning] Warning

The launchd system can be somewhat challenging to learn. Fortunately, documentation exists for the commands described in this section. For example, run man launchd from the command line to see the manual page for launchd itself, man launchd.plist to read about the job definition format, etc.

Once your job definition file is created, you can activate the job using launchctl load:

$ sudo launchctl load \
       -w /Library/LaunchDaemons/org.apache.subversion.svnserve.plist

To be clear, this action doesn't actually launch svnserve yet. It simply tells launchd how to fire up svnserve when incoming networking traffic arrives on the svn network port; it will be terminated it after the traffic has been handled.

[Note] Note

Because we want svnserve to be a system-wide daemon process, we need to use sudo to manage this job as an administrator. Note also that the UserName and GroupName keys in the definition file are optional—if omitted, the job will run as the user who loaded the job.

Deactivating the job is just as easy to do—use launchctl unload:

$ sudo launchctl unload \
       -w /Library/LaunchDaemons/org.apache.subversion.svnserve.plist

launchctl also provides a way for you to query the status of jobs. If the job is loaded, there will be line which matches the Label specified in the job definition file:

$ sudo launchctl list | grep org.apache.subversion.svnserve
-       0       org.apache.subversion.svnserve
$

Built-in Authentication and Authorization

When a client connects to an svnserve process, the following things happen:

  • The client selects a specific repository.

  • The server processes the repository's conf/svnserve.conf file and begins to enforce any authentication and authorization policies it describes.

  • Depending on the defined policies, one of the following may occur:

    • The client may be allowed to make requests anonymously, without ever receiving an authentication challenge.

    • The client may be challenged for authentication at any time.

    • If operating in tunnel mode, the client will declare itself to be already externally authenticated (typically by SSH).

The svnserve server, by default, knows only how to send a CRAM-MD5[61] authentication challenge. In essence, the server sends a small amount of data to the client. The client uses the MD5 hash algorithm to create a fingerprint of the data and password combined, and then sends the fingerprint as a response. The server performs the same computation with the stored password to verify that the result is identical. At no point does the actual password travel over the network.

If your svnserve server was built with SASL support, it not only knows how to send CRAM-MD5 challenges, but also likely knows a whole host of other authentication mechanisms. See the section called “Using svnserve with SASL” later in this chapter to learn how to configure SASL authentication and encryption.

It's also possible, of course, for the client to be externally authenticated via a tunnel agent, such as ssh. In that case, the server simply examines the user it's running as, and uses this name as the authenticated username. For more on this, see the later section, the section called “Tunneling over SSH”.

As you've already guessed, a repository's svnserve.conf file is the central mechanism for controlling access to the repository. When used in conjunction with other supplemental files described in this section, this configuration file offers an administrator a complete solution for governing user authentication and authorization policies. Each of the files we'll discuss uses the format common to other configuration files (see the section called “Runtime Configuration Area”): section names are marked by square brackets ([ and ]), comments begin with hashes (#), and each section contains specific variables that can be set (variable = value). Let's walk through these files now and learn how to use them.

Create a users file and realm

For now, the [general] section of svnserve.conf has all the variables you need. Begin by changing the values of those variables: choose a name for a file that will contain your usernames and passwords and choose an authentication realm:

[general]
password-db = userfile
realm = example realm

The realm is a name that you define. It tells clients which sort of authentication namespace they're connecting to; the Subversion client displays it in the authentication prompt and uses it as a key (along with the server's hostname and port) for caching credentials on disk (see the section called “Caching credentials”). The password-db variable points to a separate file that contains a list of usernames and passwords, using the same familiar format. For example:

[users]
harry = foopassword
sally = barpassword

The value of password-db can be an absolute or relative path to the users file. For many admins, it's easy to keep the file right in the conf/ area of the repository, alongside svnserve.conf. On the other hand, it's possible you may want to have two or more repositories share the same users file; in that case, the file should probably live in a more public place. The repositories sharing the users file should also be configured to have the same realm, since the list of users essentially defines an authentication realm. Wherever the file lives, be sure to set the file's read and write permissions appropriately. If you know which user(s) svnserve will run as, restrict read access to the users file as necessary.

Set access controls

There are two more variables to set in the svnserve.conf file: they determine what unauthenticated (anonymous) and authenticated users are allowed to do. The variables anon-access and auth-access can be set to the value none, read, or write. Setting the value to none prohibits both reading and writing; read allows read-only access to the repository, and write allows complete read/write access to the repository. For example:

[general]
password-db = userfile
realm = example realm

# anonymous users can only read the repository
anon-access = read

# authenticated users can both read and write
auth-access = write

The example settings are, in fact, the default values of the variables, should you forget to define them. If you want to be even more conservative, you can block anonymous access completely:

[general]
password-db = userfile
realm = example realm

# anonymous users aren't allowed
anon-access = none

# authenticated users can both read and write
auth-access = write

The server process understands not only these blanket access controls to the repository, but also finer-grained access restrictions placed on specific files and directories within the repository. To make use of this feature, you need to define a file containing more detailed rules, and then set the authz-db variable to point to it:

[general]
password-db = userfile
realm = example realm

# Specific access rules for specific locations
authz-db = authzfile

We discuss the syntax of the authzfile file in detail later in this chapter, in the section called “Path-Based Authorization”. Note that the authz-db variable isn't mutually exclusive with the anon-access and auth-access variables; if all the variables are defined at once, all of the rules must be satisfied before access is allowed.

Using svnserve with SASL

For many teams, the built-in CRAM-MD5 authentication is all they need from svnserve. However, if your server (and your Subversion clients) were built with the Cyrus Simple Authentication and Security Layer (SASL) library, you have a number of authentication and encryption options available to you.

Normally, when a subversion client connects to svnserve, the server sends a greeting that advertises a list of the capabilities it supports, and the client responds with a similar list of capabilities. If the server is configured to require authentication, it then sends a challenge that lists the authentication mechanisms available; the client responds by choosing one of the mechanisms, and then authentication is carried out in some number of round-trip messages. Even when SASL capabilities aren't present, the client and server inherently know how to use the CRAM-MD5 and ANONYMOUS mechanisms (see the section called “Built-in Authentication and Authorization”). If server and client were linked against SASL, a number of other authentication mechanisms may also be available. However, you'll need to explicitly configure SASL on the server side to advertise them.

Authenticating with SASL

To activate specific SASL mechanisms on the server, you'll need to do two things. First, create a [sasl] section in your repository's svnserve.conf file with an initial key-value pair:

[sasl]
use-sasl = true

Second, create a main SASL configuration file called svn.conf in a place where the SASL library can find it—typically in the directory where SASL plug-ins are located. You'll have to locate the plug-in directory on your particular system, such as /usr/lib/sasl2/ or /etc/sasl2/. (Note that this is not the svnserve.conf file that lives within a repository!)

On a Windows server, you'll also have to edit the system registry (using a tool such as regedit) to tell SASL where to find things. Create a registry key named [HKEY_LOCAL_MACHINE\SOFTWARE\Carnegie Mellon\Project Cyrus\SASL Library], and place two keys inside it: a key called SearchPath (whose value is a path to the directory containing the SASL sasl*.dll plug-in libraries), and a key called ConfFile (whose value is a path to the parent directory containing the svn.conf file you created).

Because SASL provides so many different kinds of authentication mechanisms, it would be foolish (and far beyond the scope of this book) to try to describe every possible server-side configuration. Instead, we recommend that you read the documentation supplied in the doc/ subdirectory of the SASL source code. It goes into great detail about every mechanism and how to configure the server appropriately for each. For the purposes of this discussion, we'll just demonstrate a simple example of configuring the DIGEST-MD5 mechanism. For example, if your svn.conf file contains the following:

pwcheck_method: auxprop
auxprop_plugin: sasldb
sasldb_path: /etc/my_sasldb
mech_list: DIGEST-MD5

you've told SASL to advertise the DIGEST-MD5 mechanism to clients and to check user passwords against a private password database located at /etc/my_sasldb. A system administrator can then use the saslpasswd2 program to add or modify usernames and passwords in the database:

$ saslpasswd2 -c -f /etc/my_sasldb -u realm username

A few words of warning: first, make sure the realm argument to saslpasswd2 matches the same realm you've defined in your repository's svnserve.conf file; if they don't match, authentication will fail. Also, due to a shortcoming in SASL, the common realm must be a string with no space characters. Finally, if you decide to go with the standard SASL password database, make sure the svnserve program has read access to the file (and possibly write access as well, if you're using a mechanism such as OTP).

This is just one simple way of configuring SASL. Many other authentication mechanisms are available, and passwords can be stored in other places such as in LDAP or a SQL database. Consult the full SASL documentation for details.

Remember that if you configure your server to only allow certain SASL authentication mechanisms, this forces all connecting clients to have SASL support as well. Any Subversion client built without SASL support (which includes all pre-1.5 clients) will be unable to authenticate. On the one hand, this sort of restriction may be exactly what you want (My clients must all use Kerberos!). However, if you still want non-SASL clients to be able to authenticate, be sure to advertise the CRAM-MD5 mechanism as an option. All clients are able to use CRAM-MD5, whether they have SASL capabilities or not.

SASL encryption

SASL is also able to perform data encryption if a particular mechanism supports it. The built-in CRAM-MD5 mechanism doesn't support encryption, but DIGEST-MD5 does, and mechanisms such as SRP actually require use of the OpenSSL library. To enable or disable different levels of encryption, you can set two values in your repository's svnserve.conf file:

[sasl]
use-sasl = true
min-encryption = 128
max-encryption = 256

The min-encryption and max-encryption variables control the level of encryption demanded by the server. To disable encryption completely, set both values to 0. To enable simple checksumming of data (i.e., prevent tampering and guarantee data integrity without encryption), set both values to 1. If you wish to allow—but not require—encryption, set the minimum value to 0, and the maximum value to some bit length. To require encryption unconditionally, set both values to numbers greater than 1. In our previous example, we require clients to do at least 128-bit encryption, but no more than 256-bit encryption.

Tunneling over SSH

svnserve's built-in authentication (and SASL support) can be very handy, because it avoids the need to create real system accounts. On the other hand, some administrators already have well-established SSH authentication frameworks in place. In these situations, all of the project's users already have system accounts and the ability to SSH into the server machine.

It's easy to use SSH in conjunction with svnserve. The client simply uses the svn+ssh:// URL scheme to connect:

$ whoami
harry

$ svn list svn+ssh://host.example.com/repos/project
harryssh@host.example.com's password:  *****

foo
bar
baz
…

In this example, the Subversion client is invoking a local ssh process, connecting to host.example.com, authenticating as the user harryssh (according to SSH user configuration), then spawning a private svnserve process on the remote machine running as the user harryssh. The svnserve command is being invoked in tunnel mode (-t), and its network protocol is being tunneled over the encrypted connection by ssh, the tunnel agent. If the client performs a commit, the authenticated username harryssh will be used as the author of the new revision.

The important thing to understand here is that the Subversion client is not connecting to a running svnserve daemon. This method of access doesn't require a daemon, nor does it notice one if present. It relies wholly on the ability of ssh to spawn a temporary svnserve process, which then terminates when the network connection is closed.

When using svn+ssh:// URLs to access a repository, remember that it's the ssh program prompting for authentication, and not the svn client program. That means there's no automatic password-caching going on (see the section called “Caching credentials”). The Subversion client often makes multiple connections to the repository, though users don't normally notice this due to the password caching feature. When using svn+ssh:// URLs, however, users may be annoyed by ssh repeatedly asking for a password for every outbound connection. The solution is to use a separate SSH password-caching tool such as ssh-agent on a Unix-like system, or pageant on Windows.

When running over a tunnel, authorization is primarily controlled by operating system permissions to the repository's database files; it's very much the same as if Harry were accessing the repository directly via a file:// URL. If multiple system users are going to be accessing the repository directly, you may want to place them into a common group, and you'll need to be careful about umasks (be sure to read the section called “Supporting Multiple Repository Access Methods” later in this chapter). But even in the case of tunneling, you can still use the svnserve.conf file to block access, by simply setting auth-access = read or auth-access = none.[62]

You'd think that the story of SSH tunneling would end here, but it doesn't. Subversion allows you to create custom tunnel behaviors in your runtime config file (see the section called “Runtime Configuration Area”). For example, suppose you want to use RSH instead of SSH.[63] In the [tunnels] section of your config file, simply define it like this:

[tunnels]
rsh = rsh --

And now, you can use this new tunnel definition by using a URL scheme that matches the name of your new variable: svn+rsh://host/path. When using the new URL scheme, the Subversion client will actually be running the command rsh -- host svnserve -t behind the scenes. If you include a username in the URL (e.g., svn+rsh://username@host/path), the client will also include that in its command (rsh -- username@host svnserve -t).

[Warning] Warning

Notice that when defining an RSH-based tunnel, we've added the -- end-of-options argument to the tunnel command line. This is to prevent a malformed hostname from being treated as another option to the tunnel command. You should do the same for other tunnel programs (for example, SSH).

But you can define new tunneling schemes to be much more clever than that:

[tunnels]
joessh = $JOESSH /opt/alternate/ssh -p 29934 --

This example demonstrates a couple of things. First, it shows how to make the Subversion client launch a very specific tunneling binary (the one located at /opt/alternate/ssh) with specific options. In this case, accessing an svn+joessh:// URL would invoke the particular SSH binary with -p 29934 as arguments—useful if you want the tunnel program to connect to a nonstandard port.

Second, it shows how to define a custom environment variable that can override the name of the tunneling program. Setting the SVN_SSH environment variable is a convenient way to override the default SSH tunnel agent. But if you need to have several different overrides for different servers, each perhaps contacting a different port or passing a different set of options to SSH, you can use the mechanism demonstrated in this example. Now if we were to set the JOESSH environment variable, its value would override the entire value of the tunnel variable—$JOESSH would be executed instead of /opt/alternate/ssh -p 29934.

SSH Configuration Tricks

It's possible to control not only the way in which the client invokes ssh, but also to control the behavior of sshd on your server machine. In this section, we'll show how to control the exact svnserve command executed by sshd, as well as how to have multiple users share a single system account.

Initial setup

To begin, locate the home directory of the account you'll be using to launch svnserve. Make sure the account has an SSH public/private keypair installed, and that the user can log in via public-key authentication. Password authentication will not work, since all of the following SSH tricks revolve around using the SSH authorized_keys file.

If it doesn't already exist, create the authorized_keys file (on Unix, typically ~/.ssh/authorized_keys). Each line in this file describes a public key that is allowed to connect. The lines are typically of the form:

  ssh-dsa AAAABtce9euch… user@example.com

The first field describes the type of key, the second field is the base64-encoded key itself, and the third field is a comment. However, it's a lesser known fact that the entire line can be preceded by a command field:

  command="program" ssh-dsa AAAABtce9euch… user@example.com

When the command field is set, the SSH daemon will run the named program instead of the typical tunnel-mode svnserve invocation that the Subversion client asks for. This opens the door to a number of server-side tricks. In the following examples, we abbreviate the lines of the file as:

  command="program" TYPE KEY COMMENT

Controlling the invoked command

Because we can specify the executed server-side command, it's easy to name a specific svnserve binary to run and to pass it extra arguments:

  command="/path/to/svnserve -t -r /virtual/root" TYPE KEY COMMENT

In this example, /path/to/svnserve might be a custom wrapper script around svnserve which sets the umask (see the section called “Supporting Multiple Repository Access Methods”). It also shows how to anchor svnserve in a virtual root directory, just as one often does when running svnserve as a daemon process. This might be done either to restrict access to parts of the system, or simply to relieve the user of having to type an absolute path in the svn+ssh:// URL.

It's also possible to have multiple users share a single account. Instead of creating a separate system account for each user, generate a public/private key pair for each person. Then place each public key into the authorized_keys file, one per line, and use the --tunnel-user option:

  command="svnserve -t --tunnel-user=harry" TYPE1 KEY1 harry@example.com
  command="svnserve -t --tunnel-user=sally" TYPE2 KEY2 sally@example.com

This example allows both Harry and Sally to connect to the same account via public key authentication. Each of them has a custom command that will be executed; the --tunnel-user option tells svnserve to assume that the named argument is the authenticated user. Without --tunnel-user, it would appear as though all commits were coming from the one shared system account.

A final word of caution: giving a user access to the server via public-key in a shared account might still allow other forms of SSH access, even if you've set the command value in authorized_keys. For example, the user may still get shell access through SSH or be able to perform X11 or general port forwarding through your server. To give the user as little permission as possible, you may want to specify a number of restrictive options immediately after the command:

  command="svnserve -t --tunnel-user=harry",no-port-forwarding,no-agent-forw
arding,no-X11-forwarding,no-pty TYPE1 KEY1 harry@example.com

Note that this all must be on one line—truly on one line—since SSH authorized_keys files do not even allow the conventional backslash character (\) for line continuation. The only reason we've shown it with a line break is to fit it on the physical page of a book.

svnserve Configuration Reference

In the previous sections, we've mentioned numerous configuration options that administrators can use in their svnserve.conf files to configure the behavior of Subversion as accessed via Subversion's svnserve server option. In this section, we'll quickly summarize all the configuration options supported by this server.

The svnserve.conf configuration file uses a typical INI-style format, with name/value pairs of options grouped into named sections. (This is conveniently the same format used by Subversion's runtime configuration area on the client side of the network.) We'll describe herein each of those named sections and the options available for use within them.

By default, svnserve will consult per-repository configuration files located at conf/svnserve.conf within the physical directory structure of the repository. To instead use a single configuration file whose values apply to all repositories served via an instance of svnserve, use the --config-file option when starting your server.

[Note] Note

In the following sections, we will refer to the svnserve configuration file by its canonical name, svnserve.conf. The filename of actual configuration file used by your svnserve instance might be something else, though. We trust this won't be too confusing.

General configuration

The [general] section contains the most commonly used and broadly focused svnserve configuration options.

anon-access

Controls the access level granted to unauthenticated (anonymous) users. Valid values are write, read, and none, with read being the default value.

auth-access

Controls the access level granted to authenticaed users. Valid values are write, read, and none, with write being the default value.

authz-db

Specifies the location of the repository access file as described in the section called “Getting Started with Path-Based Access Control”. If a regular local path is used, then unless that path begins with a forward-slash character (/), it is interpreted as a path relative to the directory containing the svnserve.conf configuration file. If no path is specified, path-based access control will be disabled.

As a special consideration, you may also specify the location of an access file which is versioned inside a Subversion repository. Use a local URL (one which begins with file://) to refer to an absolute Subversion-versioned access file. Alternatively, use a repository relative URL (one which begins with ^/) to cause svnserve to consult for each repository the access file stored at the specified relative URL within that repository.

force-username-case

Specifies the case normalization applied to usernames before comparing them against the rules found in the access file (specified by the authz-db option). Valid values are upper (to uppercase the usernames), lower (to lowercase the usernames), and none (to perform no normalization at all). By default, svnserve will not perform any case normalization on usernames.

groups-db

Specifies the path of the groups file. If a regular local path is used, then unless that path begins with a forward-slash character (/), it is interpreted as a path relative to the directory containing the svnserve.conf configuration file.

You may also specify the location of a groups file which is versioned inside a Subversion repository. Use a local URL (one which begins with file://) to refer to an absolute Subversion-versioned file. Alternatively, use a repository relative URL (one which begins with ^/) to cause svnserve to consult for each repository the group file stored at the specified relative URL within that repository.

hooks-env

Specifies the path to the hook script environment configuration file. This option overrides the per-repository default location for this file, and can be used to configure the hook script environment for multiple repositories in a single file if an absolute path is specified. Unless you specify an absolute path, the file's location is interpreted as relative to the directory containing the svnserve.conf configuration file.

See the section called “Hook script environment configuration” for detailed information regarding the hook script environment configuration file.

password-db

Specifies the path of the password database file. Unless the path specified begins with a forward-slash character (/), it is interpreted as a path relative to the directory containing the svnserve.conf configuration file. Note that if the SASL feature is used, this option will be ignored.

realm

Specifies the authentication realm of the repository. This is primarily used by the client to associate cached authentication credentials with a specific repository or set of repositories. As such, it is best that the specified realm be unique across your repositories unless those repositories share the same password database. By default, the repository's UUID is used as its authentication realm.

Cyrus SASL configuration

The [sasl] section contains configuration which is specific to the optional Cyrus Simple Authentication and Security Layer (SASL) integration feature of svnserve. See the section called “Using svnserve with SASL” for a more thorough description of this feature and the benefits it provides.

max-encryption

Specifies—as an integer bit-width—the maximum desired strength of the security layer's encryption algorithm. The special value 0 means "no encryption", and the special value 1 means "integrity checking only". The default value for this option is 256 (256-bit encryption).

min-encryption

Specifies—as an integer bit-width—the minimum desired strength of the security layer's encryption algorithm. The special value 0 means "no encryption", and the special value 1 means "integrity checking only". The default value for this option is 0 (no encryption).

use-sasl

Specifies (as a true or false value) whether to enable the Cyrus SASL feature. Note that this feature is only available if svnserve was built with support for the feature. This feature is disabled by default.



[61] See RFC 2195.

[62] Note that using any sort of svnserve-enforced access control at all only makes sense if the users cannot bypass it and access the repository directory directly using other tools (such as cd and vi); implementing such restrictions is described in the section called “Controlling the invoked command”.

[63] We don't actually recommend this, since RSH is notably less secure than SSH.