<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">
<sect1 id="tsvn-serversetup-svnserve">
	<title>Svnserve Based Server</title>
	<sect2 id="tsvn-serversetup-svnserve-1">
		<title>Introduction</title>
		<indexterm>
			<primary>svnserve</primary>
		</indexterm>
		<para>
			There may be situations where it's not possible to use Apache as
			your server.  Fortunately, Git includes Svnserve
			- a lightweight stand-alone server which uses a custom protocol
			over an ordinary TCP/IP connection.
		</para>
		<para>
			In most cases svnserve is easier to setup and runs faster than
			the Apache based server. And now that SASL support is included
			it is easy to secure as well.
		</para>
	</sect2>
	<sect2 id="tsvn-serversetup-svnserve-2">
		<title>Installing svnserve</title>
		<para>
			<orderedlist>
				<listitem>
					<para>
						Get the latest version of Git from
						<ulink url="http://Git.tigris.org/servlets/ProjectDocumentList?folderID=91">
							<citetitle>http://Git.tigris.org/servlets/ProjectDocumentList?folderID=91</citetitle>
						</ulink>.
						Alternatively get a pre-packaged installer from CollabNet at
						<ulink url="http://www.collab.net/downloads/Git">
							<citetitle>http://www.collab.net/downloads/Git</citetitle>
						</ulink>.
						This installer will setup svnserve as a Windows service, and also includes
						some of the tools you need if you are going to use SASL for security.
					</para>
				</listitem>
				<listitem>
					<para>
						If you already have a version of Git installed, and
						svnserve is running, you will need to stop it before continuing.
					</para>
				</listitem>
				<listitem>
					<para>
						Run the Git installer. If you run the installer on
						your server (recommended) you can skip step 4.
					</para>
				</listitem>
				<listitem>
					<para>
						Open the windows-explorer, go to the
						installation directory of Git (usually
						<filename>C:\Program Files\Git</filename>) and in the
						<filename>bin</filename> directory, find the files
						<filename>svnserve.exe</filename>,
						<filename>intl3_svn.dll</filename>,
						<filename>libapr.dll</filename>,
						<filename>libapriconv.dll</filename>,
						<filename>libapriutil.dll</filename>,
						<filename>libdb*.dll</filename>,
						<filename>libeay32.dll</filename> and
						<filename>ssleay32.dll</filename>
						- copy these files, or just copy all of the <filename>bin</filename>
						directory, into a directory on your server e.g.
						<filename>c:\svnserve</filename>
					</para>
				</listitem>
			</orderedlist>
		</para>
	</sect2>
	<sect2 id="tsvn-serversetup-svnserve-3">
		<title>Running svnserve</title>
		<para>
			Now that svnserve is installed, you need it running
			on your server.  The simplest approach is to run the following from a DOS
			shell or create a windows shortcut:
<screen>
svnserve.exe --daemon
</screen>
			svnserve will now start waiting for incoming requests
			on port 3690. The --daemon switch tells svnserve to run
			as a daemon process, so it will always exist until it is manually terminated.
		</para>
		<para>
			If you have not yet created a repository, follow the
			instructions given with the Apache server setup
			<xref linkend="tsvn-serversetup-apache-4"/>.
		</para>
		<para>
			To test that svnserve is working, use
			<menuchoice>
				<guimenu>TortoiseGit</guimenu>
				<guimenuitem>Repo-Browser</guimenuitem>
			</menuchoice>
			to view a repository.
		</para>
		<para>
			Assuming your repository is located in
			<filename>c:\repos\TestRepo</filename>, and your server is called
			<filename>localhost</filename>, enter:
<screen>
svn://localhost/repos/TestRepo
</screen>
			when prompted by the repo browser.
		</para>
		<para>
			You can also increase security and save time entering URLs with
			svnserve by using the --root switch to set the root
			location and restrict access to a specified directory on the server:
<screen>
svnserve.exe --daemon --root drive:\path\to\repository\root
</screen>
			Using the previous test as a guide, svnserve would now run as:
<screen>
svnserve.exe --daemon --root c:\repos
</screen>
			And in TortoiseGit our repo-browser URL is now shortened to:
<screen>
svn://localhost/TestRepo
</screen>
			Note that the --root switch is also needed if your repository is located 
			on a different partition or drive than the location of svnserve 
			on your server.
		</para>
		<para>
			Svnserve will service any number of repositories. Just locate them somewhere
			below the root folder you just defined, and access them using a URL relative
			to that root.
		</para>
		<warning>
			<para>
				Do not create or access a Berkeley DB repository on a network share.
				It <emphasis>cannot</emphasis> exist on a remote filesystem.
				Not even if you have the network drive mapped to a drive letter.
				If you attempt to use Berkeley DB on a network share,
				the results are unpredictable - you may see mysterious errors
				right away, or it may be months before you discover that your
				repository database is subtly corrupted.
			</para>
		</warning>
		<sect3 id="tsvn-serversetup-svnservice">
			<title>Run svnserve as a Service</title>
			<indexterm>
				<primary>svnserve</primary>
			</indexterm>
			<para>
				Running svnserve as a user is usually not the best way.
				It means always having a user logged in on your server,
				and remembering to restart it after a reboot. A better way is to run 
				svnserve as a windows service. Starting with Git 1.4,
				svnserve can be installed as a native windows service.
			</para>
			<para>
				To install svnserve as a native windows service, execute the following
				command all on one line to create a service which is automatically
				started when windows starts.
<screen>
sc create svnserve binpath= "c:\svnserve\svnserve.exe --service 
    --root c:\repos" displayname= "Git" depend= tcpip 
    start= auto
</screen>
				If any of the paths include spaces, you have to use (escaped) quotes
				around the path, like this:
<screen>
sc create svnserve binpath= "
    \"C:\Program Files\Git\bin\svnserve.exe\"
    --service --root c:\repos" displayname= "Git" 
    depend= tcpip start= auto
</screen>
				You can also add a description after creating the service. This
				will show up in the Windows Services Manager.
<screen>
sc description svnserve "Git server (svnserve)"
</screen>
			</para>
			<para>
				Note the rather unusual command line format used by <literal>sc</literal>.
				In the <literal>key= value</literal> pairs there must be no space between
				the key and the <literal>=</literal> but there must be a space before the
				value.
			</para>
			<tip>
				<para>
					Microsoft now recommend services to be run as under either the
					Local Service or Network Service account. Refer to
					<ulink 
						url="http://www.microsoft.com/technet/security/topics/serversecurity/serviceaccount/default.mspx">
						<citetitle>The Services and Service Accounts Security Planning Guide</citetitle>
					</ulink>.
					To create the service under the Local Service account, append the
					following to the example above.
<screen>
obj= "NT AUTHORITY\LocalService"
</screen>
					Note that you would have to give the Local Service account
					appropriate rights to both Git and your repositories,
					as well as any applications which are used by hook scripts.
					The built-in group for this is called "LOCAL SERVICE".
				</para>
			</tip>
			<para>
				Once you have installed the service, you need to go to the services
				manager to start it (this time only; it will start automatically when
				the server reboots).
			</para>
			<para>
				For more detailed information, refer to
				<ulink 
					url="http://svn.collab.net/repos/svn/trunk/notes/windows-service.txt">
					<citetitle>Windows Service Support for Svnserve</citetitle>
				</ulink>.
			</para>
			<para>
				If you installed an earlier version of svnserve using the
				<literal>SVNService</literal> wrapper, and you now want to use
				the native support instead, you will need to unregister the wrapper
				as a service (remember to stop the service first!).
				Simply use the command
<screen>
svnservice -remove
</screen>
				to remove the service registry entry.
			</para>
		</sect3>
	</sect2>
	<sect2 id="tsvn-serversetup-svnserve-4">
		<title>Basic Authentication with svnserve</title>
		<para>
			The default svnserve setup provides anonymous read-only access.
			This means that you can use an <literal>svn://</literal> URL
			to checkout and update, or use the repo-browser in TortoiseGit
			to view the repository, but you won't be able to commit any changes.
		</para>
		<para>
			To enable write access to a repository, you need to edit the
			<filename>conf/svnserve.conf</filename> file in your repository
			directory.  This file controls the configuration of the
			svnserve daemon, and also contains useful documentation.
		</para>
		<para>
			You can enable anonymous write access by simply setting:
<screen>
[general]
anon-access = write
</screen>
			However, you will not know who has made changes to a repository,
			as the <literal>svn:author</literal> property will be empty.
			You will also be unable to control who makes changes to a
			repository.  This is a somewhat risky setup!
		</para>
		<para>
			One way to overcome this is to create a password database:
<screen>
[general]
anon-access = none
auth-access = write
password-db = userfile
</screen>
			Where <filename>userfile</filename> is a file which exists in
			the same directory as <filename>svnserve.conf</filename>.  This
			file can live elsewhere in your file system (useful for when you
			have multiple repositories which require the same access rights)
			and may be referenced using an absolute path, or a path
			relative to the <filename>conf</filename> directory.
			If you include a path, it must be written
			<filename>/the/unix/way</filename>.
			Using \ or drive letters will not work.
			The <filename>userfile</filename> should have a structure of:
<screen>
[users]
username = password
...
</screen>
			This example would deny all access for unauthenticated
			(anonymous) users, and give read-write access to users listed
			in <filename>userfile</filename>.
		</para>
		<tip>
			<para>
				If you maintain multiple repositories using the same password 
				database, the use of an authentication realm will make life 
				easier for users, as TortoiseGit can cache your credentials 
				so that you only have to enter them once.  More information 
				can be found in the Git book, specifically in the 
				sections
				<ulink url="http://svnbook.red-bean.com/en/1.5/svn.serverconfig.svnserve.html#svn.serverconfig.svnserve.auth.users">
					<citetitle>Create a 'users' file and realm</citetitle> 
				</ulink>
				and 
				<ulink url="http://svnbook.red-bean.com/en/1.5/svn.serverconfig.netmodel.html#svn.serverconfig.netmodel.credcache">
					<citetitle>Client Credentials Caching</citetitle>
				</ulink>
			</para>
		</tip>
	</sect2>
	<sect2 id="tsvn-serversetup-svnserve-sasl">
		<title>Better Security with SASL</title>
		<indexterm>
			<primary>SASL</primary>
		</indexterm>
		<sect3 id="tsvn-serversetup-svnserve-sasl-whatis">
			<title>What is SASL?</title>
			<para>
				The Cyrus Simple Authentication and Security Layer is
				open source software written by Carnegie Mellon University.
				It adds generic authentication and encryption capabilities
				to any network protocol, and as of Git 1.5 and later,
				both the svnserve server and TortoiseGit client know how to
				make use of this library.
			</para>
			<para>
				For a more complete discussion of the options available, you should
				look at the Git book in the section
				<ulink url="http://svnbook.red-bean.com/en/1.5/svn.serverconfig.svnserve.html#svn.serverconfig.svnserve.sasl">
					<citetitle>Using svnserve with SASL</citetitle>
				</ulink>.
				If you are just looking for a simple way to set up secure
				authentication and encryption on a Windows server, so that your
				repository can be accessed safely over the big bad Internet,
				read on.
			</para>
		</sect3>
		<sect3 id="tsvn-serversetup-svnserve-sasl-auth">
			<title>SASL Authentication</title>
			<para>
				To activate specific SASL mechanisms on the server, you'll
				need to do three things. First, create a <literal>[sasl]</literal>
				section in your repository's <filename>svnserve.conf</filename>
				file, with this key-value pair:
<screen>
use-sasl = true
</screen>
			</para>
			<para>
				Second, create a file called <filename>svn.conf</filename> in a
				convenient location - typically in the directory where Git
				is installed.
			</para>
			<para>
				Thirdly, create two new registry entries to tell SASL where to
				find things. Create a registry key named
				<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\Carnegie Mellon\Project Cyrus\SASL Library]</literal>
				and place two new string values inside it:
				<literal>SearchPath</literal> set to the directory path containing
				the <filename>sasl*.dll</filename> plug-ins (normally in the
				Git install directory), and <literal>ConfFile</literal> set
				to the directory containing the <filename>svn.conf</filename> file.
				If you used the CollabNet installer, these registry keys will already
				have been created for you.
			</para>
			<para>
				Edit the <filename>svn.conf</filename> file to contain the following:

<screen>
pwcheck_method: auxprop
auxprop_plugin: sasldb
mech_list: DIGEST-MD5
sasldb_path: C:\TortoiseGit\sasldb
</screen>
				The last line shows the location of the authentication database,
				which is a file called <filename>sasldb</filename>.
				This could go anywhere, but a convenient choice is the repository
				parent path. Make sure that the svnserve service has read access
				to this file.
			</para>
			<para>
				If svnserve was already running, you will need to restart it to
				ensure it reads the updated configuration.
			</para>
			<para>
				Now that everything is set up, all you need to do is create some
				users and passwords. To do this you need the
				<literal>saslpasswd2</literal> program. If you used the CollabNet
				installer, that program will be in the install directory.
				Use a command something like this:
<screen>
saslpasswd2 -c -f C:\TortoiseGit\sasldb -u realm username
</screen>
				The <literal>-f</literal> switch gives the database location,
				<literal>realm</literal> must be the same as the value you
				defined in your repository's <filename>svnserve.conf</filename>
				file, and username is exactly what you expect it to be.
				Note that the realm is not allowed to contain space characters.
			</para>
			<para>
				You can list the usernames stored in the database using the
				<literal>sasldblistusers2</literal> program.
			</para>
		</sect3>
		<sect3 id="tsvn-serversetup-svnserve-sasl-encrypt">
			<title>SASL Encryption</title>
			<para>
				To enable or disable different levels of encryption, you can
				set two values in your repository's
				<filename>svnserve.conf</filename> file:
<screen>
[sasl]
use-sasl = true
min-encryption = 128
max-encryption = 256
</screen>
			</para>
			<para>
				The <literal>min-encryption</literal> and
				<literal>max-encryption</literal> 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.
			</para>
		</sect3>
	</sect2>
	<sect2 id="tsvn-serversetup-svnserve-5">
		<title>Authentication with svn+ssh</title>
		<para>
			Another way to authenticate users with a svnserve
			based server is to use a secure shell (SSH) to tunnel
			requests through. It is not as simple to set up as SASL,
			but it may be useful is some cases.
		</para>
		<para>
			With this approach, svnserve is not run as a daemon
			process, rather, the secure shell starts svnserve
			for you, running it as the SSH authenticated user. To
			enable this, you need a secure shell daemon on your server.
		</para>
		<para>
			A basic method for setting up your server is given in
			<xref linkend="tsvn-ssh-howto"/>.
			You can find other SSH topics within the FAQ by searching
			for <quote>SSH</quote>.
		</para>
		<para>
			Further information about svnserve can be found in the
			<ulink url="http://svnbook.red-bean.com">
				<citetitle>Version Control with Git</citetitle>
			</ulink>.
		</para>
	</sect2>
	<sect2 id="tsvn-serversetup-svnserve-6">
		<title>Path-based Authorization with svnserve</title>
		<para>
			Starting with Git 1.3, svnserve supports the same
			<literal>mod_authz_svn</literal> path-based authorization scheme
			that is available with the Apache server. You need to edit the
			<filename>conf/svnserve.conf</filename> file in your repository
			directory and add a line referring to your authorization file.
<screen>
[general]
authz-db = authz
</screen>
			Here, <filename>authz</filename> is a file you create to define
			the access permissions. You can use a separate file for each
			repository, or you can use the same file for several repositories.
			Read <xref linkend="tsvn-serversetup-mod_authz_svn"/>
			for a description of the file format.
		</para>
	</sect2>
</sect1>
