1 <?xml version="1.0" encoding="UTF-8"?>
\r
2 <!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">
\r
3 <sect1 id="tsvn-serversetup-svnserve">
\r
4 <title>Svnserve Based Server</title>
\r
5 <sect2 id="tsvn-serversetup-svnserve-1">
\r
6 <title>Introduction</title>
\r
8 <primary>svnserve</primary>
\r
11 There may be situations where it's not possible to use Apache as
\r
12 your server. Fortunately, Subversion includes Svnserve
\r
13 - a lightweight stand-alone server which uses a custom protocol
\r
14 over an ordinary TCP/IP connection.
\r
17 In most cases svnserve is easier to setup and runs faster than
\r
18 the Apache based server. And now that SASL support is included
\r
19 it is easy to secure as well.
\r
22 <sect2 id="tsvn-serversetup-svnserve-2">
\r
23 <title>Installing svnserve</title>
\r
28 Get the latest version of Subversion from
\r
29 <ulink url="http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=91">
\r
30 <citetitle>http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=91</citetitle>
\r
32 Alternatively get a pre-packaged installer from CollabNet at
\r
33 <ulink url="http://www.collab.net/downloads/subversion">
\r
34 <citetitle>http://www.collab.net/downloads/subversion</citetitle>
\r
36 This installer will setup svnserve as a Windows service, and also includes
\r
37 some of the tools you need if you are going to use SASL for security.
\r
42 If you already have a version of Subversion installed, and
\r
43 svnserve is running, you will need to stop it before continuing.
\r
48 Run the Subversion installer. If you run the installer on
\r
49 your server (recommended) you can skip step 4.
\r
54 Open the windows-explorer, go to the
\r
55 installation directory of Subversion (usually
\r
56 <filename>C:\Program Files\Subversion</filename>) and in the
\r
57 <filename>bin</filename> directory, find the files
\r
58 <filename>svnserve.exe</filename>,
\r
59 <filename>intl3_svn.dll</filename>,
\r
60 <filename>libapr.dll</filename>,
\r
61 <filename>libapriconv.dll</filename>,
\r
62 <filename>libapriutil.dll</filename>,
\r
63 <filename>libdb*.dll</filename>,
\r
64 <filename>libeay32.dll</filename> and
\r
65 <filename>ssleay32.dll</filename>
\r
66 - copy these files, or just copy all of the <filename>bin</filename>
\r
67 directory, into a directory on your server e.g.
\r
68 <filename>c:\svnserve</filename>
\r
74 <sect2 id="tsvn-serversetup-svnserve-3">
\r
75 <title>Running svnserve</title>
\r
77 Now that svnserve is installed, you need it running
\r
78 on your server. The simplest approach is to run the following from a DOS
\r
79 shell or create a windows shortcut:
\r
81 svnserve.exe --daemon
\r
83 svnserve will now start waiting for incoming requests
\r
84 on port 3690. The --daemon switch tells svnserve to run
\r
85 as a daemon process, so it will always exist until it is manually terminated.
\r
88 If you have not yet created a repository, follow the
\r
89 instructions given with the Apache server setup
\r
90 <xref linkend="tsvn-serversetup-apache-4"/>.
\r
93 To test that svnserve is working, use
\r
95 <guimenu>TortoiseGit</guimenu>
\r
96 <guimenuitem>Repo-Browser</guimenuitem>
\r
98 to view a repository.
\r
101 Assuming your repository is located in
\r
102 <filename>c:\repos\TestRepo</filename>, and your server is called
\r
103 <filename>localhost</filename>, enter:
\r
105 svn://localhost/repos/TestRepo
\r
107 when prompted by the repo browser.
\r
110 You can also increase security and save time entering URLs with
\r
111 svnserve by using the --root switch to set the root
\r
112 location and restrict access to a specified directory on the server:
\r
114 svnserve.exe --daemon --root drive:\path\to\repository\root
\r
116 Using the previous test as a guide, svnserve would now run as:
\r
118 svnserve.exe --daemon --root c:\repos
\r
120 And in TortoiseGit our repo-browser URL is now shortened to:
\r
122 svn://localhost/TestRepo
\r
124 Note that the --root switch is also needed if your repository is located
\r
125 on a different partition or drive than the location of svnserve
\r
129 Svnserve will service any number of repositories. Just locate them somewhere
\r
130 below the root folder you just defined, and access them using a URL relative
\r
135 Do not create or access a Berkeley DB repository on a network share.
\r
136 It <emphasis>cannot</emphasis> exist on a remote filesystem.
\r
137 Not even if you have the network drive mapped to a drive letter.
\r
138 If you attempt to use Berkeley DB on a network share,
\r
139 the results are unpredictable - you may see mysterious errors
\r
140 right away, or it may be months before you discover that your
\r
141 repository database is subtly corrupted.
\r
144 <sect3 id="tsvn-serversetup-svnservice">
\r
145 <title>Run svnserve as a Service</title>
\r
147 <primary>svnserve</primary>
\r
150 Running svnserve as a user is usually not the best way.
\r
151 It means always having a user logged in on your server,
\r
152 and remembering to restart it after a reboot. A better way is to run
\r
153 svnserve as a windows service. Starting with Subversion 1.4,
\r
154 svnserve can be installed as a native windows service.
\r
157 To install svnserve as a native windows service, execute the following
\r
158 command all on one line to create a service which is automatically
\r
159 started when windows starts.
\r
161 sc create svnserve binpath= "c:\svnserve\svnserve.exe --service
\r
162 --root c:\repos" displayname= "Subversion" depend= tcpip
\r
165 If any of the paths include spaces, you have to use (escaped) quotes
\r
166 around the path, like this:
\r
168 sc create svnserve binpath= "
\r
169 \"C:\Program Files\Subversion\bin\svnserve.exe\"
\r
170 --service --root c:\repos" displayname= "Subversion"
\r
171 depend= tcpip start= auto
\r
173 You can also add a description after creating the service. This
\r
174 will show up in the Windows Services Manager.
\r
176 sc description svnserve "Subversion server (svnserve)"
\r
180 Note the rather unusual command line format used by <literal>sc</literal>.
\r
181 In the <literal>key= value</literal> pairs there must be no space between
\r
182 the key and the <literal>=</literal> but there must be a space before the
\r
187 Microsoft now recommend services to be run as under either the
\r
188 Local Service or Network Service account. Refer to
\r
190 url="http://www.microsoft.com/technet/security/topics/serversecurity/serviceaccount/default.mspx">
\r
191 <citetitle>The Services and Service Accounts Security Planning Guide</citetitle>
\r
193 To create the service under the Local Service account, append the
\r
194 following to the example above.
\r
196 obj= "NT AUTHORITY\LocalService"
\r
198 Note that you would have to give the Local Service account
\r
199 appropriate rights to both Subversion and your repositories,
\r
200 as well as any applications which are used by hook scripts.
\r
201 The built-in group for this is called "LOCAL SERVICE".
\r
205 Once you have installed the service, you need to go to the services
\r
206 manager to start it (this time only; it will start automatically when
\r
207 the server reboots).
\r
210 For more detailed information, refer to
\r
212 url="http://svn.collab.net/repos/svn/trunk/notes/windows-service.txt">
\r
213 <citetitle>Windows Service Support for Svnserve</citetitle>
\r
217 If you installed an earlier version of svnserve using the
\r
218 <literal>SVNService</literal> wrapper, and you now want to use
\r
219 the native support instead, you will need to unregister the wrapper
\r
220 as a service (remember to stop the service first!).
\r
221 Simply use the command
\r
225 to remove the service registry entry.
\r
229 <sect2 id="tsvn-serversetup-svnserve-4">
\r
230 <title>Basic Authentication with svnserve</title>
\r
232 The default svnserve setup provides anonymous read-only access.
\r
233 This means that you can use an <literal>svn://</literal> URL
\r
234 to checkout and update, or use the repo-browser in TortoiseGit
\r
235 to view the repository, but you won't be able to commit any changes.
\r
238 To enable write access to a repository, you need to edit the
\r
239 <filename>conf/svnserve.conf</filename> file in your repository
\r
240 directory. This file controls the configuration of the
\r
241 svnserve daemon, and also contains useful documentation.
\r
244 You can enable anonymous write access by simply setting:
\r
247 anon-access = write
\r
249 However, you will not know who has made changes to a repository,
\r
250 as the <literal>svn:author</literal> property will be empty.
\r
251 You will also be unable to control who makes changes to a
\r
252 repository. This is a somewhat risky setup!
\r
255 One way to overcome this is to create a password database:
\r
259 auth-access = write
\r
260 password-db = userfile
\r
262 Where <filename>userfile</filename> is a file which exists in
\r
263 the same directory as <filename>svnserve.conf</filename>. This
\r
264 file can live elsewhere in your file system (useful for when you
\r
265 have multiple repositories which require the same access rights)
\r
266 and may be referenced using an absolute path, or a path
\r
267 relative to the <filename>conf</filename> directory.
\r
268 If you include a path, it must be written
\r
269 <filename>/the/unix/way</filename>.
\r
270 Using \ or drive letters will not work.
\r
271 The <filename>userfile</filename> should have a structure of:
\r
274 username = password
\r
277 This example would deny all access for unauthenticated
\r
278 (anonymous) users, and give read-write access to users listed
\r
279 in <filename>userfile</filename>.
\r
283 If you maintain multiple repositories using the same password
\r
284 database, the use of an authentication realm will make life
\r
285 easier for users, as TortoiseGit can cache your credentials
\r
286 so that you only have to enter them once. More information
\r
287 can be found in the Subversion book, specifically in the
\r
289 <ulink url="http://svnbook.red-bean.com/en/1.5/svn.serverconfig.svnserve.html#svn.serverconfig.svnserve.auth.users">
\r
290 <citetitle>Create a 'users' file and realm</citetitle>
\r
293 <ulink url="http://svnbook.red-bean.com/en/1.5/svn.serverconfig.netmodel.html#svn.serverconfig.netmodel.credcache">
\r
294 <citetitle>Client Credentials Caching</citetitle>
\r
299 <sect2 id="tsvn-serversetup-svnserve-sasl">
\r
300 <title>Better Security with SASL</title>
\r
302 <primary>SASL</primary>
\r
304 <sect3 id="tsvn-serversetup-svnserve-sasl-whatis">
\r
305 <title>What is SASL?</title>
\r
307 The Cyrus Simple Authentication and Security Layer is
\r
308 open source software written by Carnegie Mellon University.
\r
309 It adds generic authentication and encryption capabilities
\r
310 to any network protocol, and as of Subversion 1.5 and later,
\r
311 both the svnserve server and TortoiseGit client know how to
\r
312 make use of this library.
\r
315 For a more complete discussion of the options available, you should
\r
316 look at the Subversion book in the section
\r
317 <ulink url="http://svnbook.red-bean.com/en/1.5/svn.serverconfig.svnserve.html#svn.serverconfig.svnserve.sasl">
\r
318 <citetitle>Using svnserve with SASL</citetitle>
\r
320 If you are just looking for a simple way to set up secure
\r
321 authentication and encryption on a Windows server, so that your
\r
322 repository can be accessed safely over the big bad Internet,
\r
326 <sect3 id="tsvn-serversetup-svnserve-sasl-auth">
\r
327 <title>SASL Authentication</title>
\r
329 To activate specific SASL mechanisms on the server, you'll
\r
330 need to do three things. First, create a <literal>[sasl]</literal>
\r
331 section in your repository's <filename>svnserve.conf</filename>
\r
332 file, with this key-value pair:
\r
338 Second, create a file called <filename>svn.conf</filename> in a
\r
339 convenient location - typically in the directory where subversion
\r
343 Thirdly, create two new registry entries to tell SASL where to
\r
344 find things. Create a registry key named
\r
345 <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\Carnegie Mellon\Project Cyrus\SASL Library]</literal>
\r
346 and place two new string values inside it:
\r
347 <literal>SearchPath</literal> set to the directory path containing
\r
348 the <filename>sasl*.dll</filename> plug-ins (normally in the
\r
349 Subversion install directory), and <literal>ConfFile</literal> set
\r
350 to the directory containing the <filename>svn.conf</filename> file.
\r
351 If you used the CollabNet installer, these registry keys will already
\r
352 have been created for you.
\r
355 Edit the <filename>svn.conf</filename> file to contain the following:
\r
358 pwcheck_method: auxprop
\r
359 auxprop_plugin: sasldb
\r
360 mech_list: DIGEST-MD5
\r
361 sasldb_path: C:\TortoiseGit\sasldb
\r
363 The last line shows the location of the authentication database,
\r
364 which is a file called <filename>sasldb</filename>.
\r
365 This could go anywhere, but a convenient choice is the repository
\r
366 parent path. Make sure that the svnserve service has read access
\r
370 If svnserve was already running, you will need to restart it to
\r
371 ensure it reads the updated configuration.
\r
374 Now that everything is set up, all you need to do is create some
\r
375 users and passwords. To do this you need the
\r
376 <literal>saslpasswd2</literal> program. If you used the CollabNet
\r
377 installer, that program will be in the install directory.
\r
378 Use a command something like this:
\r
380 saslpasswd2 -c -f C:\TortoiseGit\sasldb -u realm username
\r
382 The <literal>-f</literal> switch gives the database location,
\r
383 <literal>realm</literal> must be the same as the value you
\r
384 defined in your repository's <filename>svnserve.conf</filename>
\r
385 file, and username is exactly what you expect it to be.
\r
386 Note that the realm is not allowed to contain space characters.
\r
389 You can list the usernames stored in the database using the
\r
390 <literal>sasldblistusers2</literal> program.
\r
393 <sect3 id="tsvn-serversetup-svnserve-sasl-encrypt">
\r
394 <title>SASL Encryption</title>
\r
396 To enable or disable different levels of encryption, you can
\r
397 set two values in your repository's
\r
398 <filename>svnserve.conf</filename> file:
\r
402 min-encryption = 128
\r
403 max-encryption = 256
\r
407 The <literal>min-encryption</literal> and
\r
408 <literal>max-encryption</literal> variables control the
\r
409 level of encryption demanded by the server. To disable
\r
410 encryption completely, set both values to 0. To enable
\r
411 simple checksumming of data (i.e., prevent tampering and
\r
412 guarantee data integrity without encryption), set both
\r
413 values to 1. If you wish to allow (but not require) encryption,
\r
414 set the minimum value to 0, and the maximum value to some
\r
415 bit-length. To require encryption unconditionally, set both
\r
416 values to numbers greater than 1. In our previous example,
\r
417 we require clients to do at least 128-bit encryption,
\r
418 but no more than 256-bit encryption.
\r
422 <sect2 id="tsvn-serversetup-svnserve-5">
\r
423 <title>Authentication with svn+ssh</title>
\r
425 Another way to authenticate users with a svnserve
\r
426 based server is to use a secure shell (SSH) to tunnel
\r
427 requests through. It is not as simple to set up as SASL,
\r
428 but it may be useful is some cases.
\r
431 With this approach, svnserve is not run as a daemon
\r
432 process, rather, the secure shell starts svnserve
\r
433 for you, running it as the SSH authenticated user. To
\r
434 enable this, you need a secure shell daemon on your server.
\r
437 A basic method for setting up your server is given in
\r
438 <xref linkend="tsvn-ssh-howto"/>.
\r
439 You can find other SSH topics within the FAQ by searching
\r
440 for <quote>SSH</quote>.
\r
443 Further information about svnserve can be found in the
\r
444 <ulink url="http://svnbook.red-bean.com">
\r
445 <citetitle>Version Control with Subversion</citetitle>
\r
449 <sect2 id="tsvn-serversetup-svnserve-6">
\r
450 <title>Path-based Authorization with svnserve</title>
\r
452 Starting with Subversion 1.3, svnserve supports the same
\r
453 <literal>mod_authz_svn</literal> path-based authorization scheme
\r
454 that is available with the Apache server. You need to edit the
\r
455 <filename>conf/svnserve.conf</filename> file in your repository
\r
456 directory and add a line referring to your authorization file.
\r
461 Here, <filename>authz</filename> is a file you create to define
\r
462 the access permissions. You can use a separate file for each
\r
463 repository, or you can use the same file for several repositories.
\r
464 Read <xref linkend="tsvn-serversetup-mod_authz_svn"/>
\r
465 for a description of the file format.
\r
OSDN Git Service
