Table of Contents
To use TortoiseSVN (or any other Subversion client), you need a place where your repositories are located. You can either store your repositories locally and access them using the file:// protocol or you can place them on a server and access them with the http:// or svn:// protocols. The two server protocols can also be encrypted. You use https:// or svn+ssh://. This chapter shows you step by step on how you can set up such a server on a Windows machine.
If you don't have a server and/or if you only work alone then local repositories are probably your best choice. You can skip this chapter and go directly to Chapter 4, The Repository.
The most flexible of all possible server setups for Subversion is the Apache based one. Although a bit more complicated to set up, it offers benefits that other servers cannot:
The Apache based Subversion server uses the WebDAV protocol which is supported by many other programs as well. You could e.g. mount such a repository as a "Webfolder" in the Windows explorer and then access it like any other folder in the filesystem
You can point your browser to the URL of your repository and browse the contents of it without having a Subversion client installed. This gives access to your data to a much wider circle of users.
You can use any authentication mechanism Apache supports, including SSPI and LDAP.
Since Apache is very stable and secure, you automatically get the same security for your repository. This includes SSL encryption.
The first thing you need before installing Apache is a computer with either Windows2000 / WinXP+SP1 or Windows2003.
Please note that Windows XP without the servicepack 1 will lead to bogus network data and could therefore corrupt your repository!
Download the latest version of the Apache webserver from http://httpd.apache.org/download.cgi . Make sure that you download the version > 2.0.54 - the version 1.3.xx won't work! Also, versions lower than 2.0.54 won't work with Subversion 1.2 because of a bug in how Apache < 2.0.54 was built for Windows.
Once you have the Apache2 installer you
can doubleclick on it and it will guide you through
the installation process. Make sure that you enter
the server-URL correctly (if you don't have a dns name
for your server just enter the ip-address). I recommend
to install apache
for All Users, on Port 80, as a Service.
Note: if you already have IIS or any other
program running which listens on port 80 the
installation might fail. If that happens, go to the
programs directory,
\Apache Group\Apache2\conf
and locate the file
httpd.conf. Edit that file so that
Listen 80 is changed to a free
port, e.g. Listen 81.
Then restart the installation - this time it should
finish without problems.
Now test if the Apache-webserver is running
correctly by pointing your webbrowser to
http://localhost/
- a preconfigured Website should show up.
If you decide to install Apache as a service, be warned that by default it will run as the local system account. It would be a more secure practice for you to create a separate account for Apache to run as.
Make sure that the account on the server that Apache is running as has an explicit entry in the repository directory's access control list (right-click directory | properties | security), with full control. Otherwise, users will not be able to commit their changes.
Even if Apache runs as local system, you still need such an entry (which will be the SYSTEM account in this case).
If Apache does not have this permission set up, your users will get "Access denied" error messages, which show up in the Apache error log as error 500.
Download the latest version of Subversion from http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=91 .
Run the Subversion installer and follow the instructions. If the Subversion installer recognized that you've installed Apache, then you're almost done. If it couldn't find an Apache server then you have to do some additional steps.
Using the windows explorer, go to the installation
directory of Subversion (usually
c:\program files\Subversion)
and find the files
/httpd/mod_dav_svn.so and
mod_authz_svn.so. Copy these files
to the Apache modules directory (usually
c:\program files\apache group\apache2\modules
).
Copy the file /bin/libdb43.dll from
the Subversion installation directory to the Apache
modules directory.
Edit Apache's configuration file (usually
C:\Program Files\Apache
Group\Apache2\conf\httpd.conf) with a text
editor such as Notepad and make the following changes:
Uncomment (remove the '#' mark) the
following lines:
#LoadModule dav_fs_module modules/mod_dav_fs.so
#LoadModule dav_module modules/mod_dav.so
Add the following two lines to the end of the
LoadModule section.
LoadModule dav_svn_module modules/mod_dav_svn.so LoadModule authz_svn_module modules/mod_authz_svn.so
Now you have set up Apache and Subversion, but Apache doesn't
know how to handle Subversion clients like TortoiseSVN yet.
To get Apache to know which URL shall be used for Subversion
repositories you have to edit the Apache config file (usually
located in
c:\program files\apache group\apache2\conf\httpd.conf)
with any text editor you like (e.g. Notepad):
At the end of the Config file add the following lines:
<Location /svn> DAV svn SVNListParentPath on SVNParentPath D:\SVN AuthType Basic AuthName "Subversion repositories" AuthUserFile passwd #AuthzSVNAccessFile svnaccessfile Require valid-user </Location>
This configures Apache so that all your Subversion
repositories are physically located below
D:\SVN. The repositories are
served to the outside world from the URL:
http://MyServer/svn/
.
Access is restricted to known users/passwords
listed in the passwd file.
To create the passwd
file, open the command prompt (DOS-Box) again,
change to the apache2 folder (usually
c:\program files\apache
group\apache2)
and create the file by entering
bin\htpasswd -c passwd <username>
This will create a file with the name passwd which is used for authentication. Additional users can be added with
bin\htpasswd passwd <username>
Restart the Apache service again.
Point your browser to
http://MyServer/svn/MyNewRepository
(where MyNewRepository is the name of the
Subversion repository you created before). If all went
well you should be prompted for a username and password,
then you can see the contents of your
repository.
A short explanation of what you just entered:
Table 3.1. Apache httpd.conf Settings
| Setting | Explanation |
|---|---|
| <Location /svn> |
means that the Subversion repositories are available from the URL
http://MyServer/svn/
|
| DAV svn | tells Apache which module will be responsible to serve that URL - in this case the Subversion module. |
| SVNListParentPath on | For Subversion version 1.3 and higher, this directive enables listing all the available repositories under SVNParentPath. |
| SVNParentPath D:\SVN |
tells Subversion to look for repositories below
D:\SVN
|
| AuthType Basic | is to activate basic authentication, i.e. Username/password |
| AuthName "Subversion repositories" | is used as an information whenever an authentication dialog pops up to tell the user what the authentication is for |
| AuthUserFile passwd | specifies which password file to use for authentication |
| AuthzSVNAccessFile | Location of the Access file for paths inside a Subversion repository |
| Require valid-user | specifies that only users who entered a correct username/password are allowed to access the URL |
But that's just an example. There are many, many more possibilities of what you can do with the Apache webserver.
If you want your repository to have read access for everyone but write access only for specific users you can change the line
Require valid-user
to
<LimitExcept GET PROPFIND OPTIONS REPORT> Require valid-user </LimitExcept>
Using a passwd file limits and
grants access to all of your repositories as a unit.
If you want more control over which users have
access each folder inside a repository you can
uncomment the line
#AuthzSVNAccessFile svnaccessfile
and create a Subversion access file. Apache will
make sure that only valid users are able to access
your /svn location, and will then
pass the username to Subversion's AuthzSVNAccessFile
module so that it can enforce more granular access
based upon rules listed in the Subversion access file.
Note that paths are specified either as
repos:path or simply
path. If you don't specify a
particular repository, that access rule will apply to
all repositories under
SVNParentPath.
An example file would look like this:
[groups] admin = john, kate devteam1 = john, rachel, sally devteam2 = kate, peter, mark docs = bob, jane, mike training = zak # Default access rule for ALL repositories # Everyone can read, admins can write, Dan German is excluded. [/] * = r @admin = rw dangerman = # Allow developers complete access to their project repos [proj1:/] @devteam1 = rw [proj2:/] @devteam2 = rw [bigproj:/] @devteam1 = rw @devteam2 = rw trevor = rw # Give the doc people write access to all the docs folders [/trunk/doc] @docs = rw # Give trainees write access in the training repository only [TrainingRepos:/] @training = rw
If you used the SVNParentPath directive then you don't have to change the Apache config file everytime you add a new Subversion repository. Simply create the new repository under the same location as the first repository and you're done! In my company I have direct access to that specific folder on the server via SMB (normal windows file access). So I just create a new folder there, run the TortoiseSVN command → and a new project has a home...
The advantage of using the SVNParentPath directive is that you don't have to change the Apache config each time you create a new repository, but you also don't have an index of all created and available projects. If you point your browser to the path SVNParentPath points to, you will get a nasty error page showing.
To avoid that ugly error page and have a nice looking listing of all available projects instead, you can use the following PHP script which generates the index for you automatically. (You will need to install PHP on your server in order to use the below file).
For Subversion 1.3 and higher, just enable “SVNListParentPath on”.
As you might have noticed you need to make a username/password
entry in the passwd file for each user
separately. And if (for security reasons) you want your users
to periodically change their passwords you have to make the
change manually.
But there's a solution for that problem - at least if you're accessing the repository from inside a LAN with a windows domain controller: mod_auth_sspi!
The original SSPI module was offered by Syneapps including
sourcecode. But the development for it has been stopped. You can
still find that module on the internet - just do a
google search for it. We also have a compiled version of it
on our website, supplied by Norbert Unterberg.
This one is mod_auth_sspi 1.0.3 which supports a
SSPIUsernameCase [upper|lower] directive.
Get the mod_auth_sspi module
.
Download the module, copy the file
mod_auth_sspi.so
into the Apache modules folder.
Edit the Apache config file: add the line
LoadModule sspi_auth_module modules/mod_auth_sspi.so
to the LoadModule's section. Make sure you insert this line before the line
LoadModule auth_module modules/mod_auth.so
To make the Subversion location use this type of authentication you have to change the line
AuthType Basic
to
AuthType SSPI
also you need to add
SSPIAuth On SSPIAuthoritative On SSPIDomain <domaincontroller> SSPIOfferBasic On
within the <Location /svn> block. If you don't have a domain controller, leave the name of the domain control as <domaincontroller>.
Note that if you are authenticating using SSPI, then you don't
need the AuthUserFile line to define a
password file any more. Apache authenticates your username and
password against your windows domain instead. You will need to
update the users list in your svnaccessfile
to reference DOMAIN\username as well.
Subversion AuthzSVNAccessFile files are case sensitive in regard to user names ("JUser" is different from "juser").
In Microsoft's world, Windows domains and usernames are not case sensitive. Even so, some network administrators like to create user accounts in CamelCase (e.g. "JUser").
This difference can bite you when using SSPI authentication as the windows domain and user names are passed to Subversion in the same case as the user types them in at the prompt. Internet Explorer often passes the username to Apache automatically using whatever case the account was created with.
The end result is that you may need at least two entries in your AuthzSVNAccessFile for each user -- a lowercase entry and an entry in the same case that Internet Explorer passes to Apache. You will also need to train your users to also type in their credentials using lower case when accessing repositories via TortoiseSVN.
Apache's Error and Access logs are your best friend in
deciphering problems such as these as they will help you
determine the username string passed onto Subversion's
AuthzSVNAccessFile module. You may need to experiment with
the exact format of the user string in the svnaccessfile
(e.g. DOMAIN\user vs.
DOMAIN//user) in order to get
everything working.
If you're securing your server with SSL and use authentication against a windows domain you will encounter that browsing the repository with the Internet Explorer doesn't work anymore. Don't worry - this is only the Internet Explorer not able to authenticate. Other browsers don't have that problem and TortoiseSVN and any other Subversion client are still able to authenticate.
If you still want to use IE to browse the repository you can either:
define a separate <Location /path>
directive in the apache config file, and add the
SSPIBasicPreferred On.
This will allow IE to authenticate again, but
other browsers and Subversion won't be able to
authenticate against that location.
Offer browsing with unencrypted authentication (without SSL) too. Strangely IE doesn't have any problems with authenticating if the connection is not secured with SSL.
In the ssl "standard" setup there's often the following statement in apache's virtual ssl host:
SetEnvIf User-Agent ".*MSIE.*" \
nokeepalive ssl-unclean-shutdown \
downgrade-1.0 force-response-1.0
There are (were?) good reasons for this configuration, see http://www.modssl.org/docs/2.8/ssl_faq.html#ToC49 But if you want ntlm authentication you have to use keepalive: http://www.microsoft.com/resources/documentation/WindowsServ/2003/standard/proddocs/en-us/qos_enablekeepalives.asp If You uncomment the whole "SetEnvIf" You should be able to authenticate IE with windows authentication over SSL against the apache on Win32 with included mod_auth_sspi.
The apache server doesn't have SSL support installed by default due to US-export restrictions. But you can easily download the required module from somewhere else and install it yourself.
First you need the required files to enable
SSL. You can find those in the package available at
http://hunter.campbus.com/
.
Just unzip the package and then copy
mod_ssl.so to the
modules folder of Apache and the file
openssl.exe to the
bin folder. Also copy the file
conf/ssl.conf to the
conf folder of Apache.
Open the file
ssl.conf
in the Apache conf folder with a text editor.
Place a comment char (#) in front
of the following lines:
DocumentRoot "c:/apache/htdocs" ServerName www.example.com:443 ServerAdmin you@example.com ErrorLog logs/error_log TransferLog logs/access_log
change the line
SSLCertificateFile conf/ssl.crt/server.crt
to
SSLCertificateFile conf/ssl/my-server.cert
the line
SSLCertificateKeyFile conf/ssl.key/server.key
to
SSLCertificateKeyFile conf/ssl/my-server.key
and the line
SSLMutex file:logs/ssl_mutex
to
SSLMutex default
Delete the lines
<IfDefine SSL>
and
</IfDefine>
Open the Apache config file
(httpd.conf) and uncomment the line
#LoadModule ssl_module modules/mod_ssl.so
Openssl needs a config file. You can download
a working one from
http://tud.at/programm/openssl.cnf
.
Save the file to bin/openssl.cnf.
Please note: the file has the type
*.cnf.
Windows treats such files in a special way but it
really is just a text file!
Next you need to create an SSL certificate.
To do that open a command prompt (DOS-Box) and change to
the apache folder (e.g.
C:\program files\apache group\apache2)
and type the following command:
bin\openssl req -config bin\openssl.cnf -new -out my-server.csr
You will be asked for a passphrase. Please don't use simple words but whole sentences, e.g. a part of a poem. The longer the phrase the better. Also you have to enter the URL of you server. All other questions are optional but I recommend to fill out those too. Next type the commands
bin\openssl rsa -in privkey.pem -out my-server.key
and (on one line)
bin\openssl x509 -in my-server.csr -out my-server.cert
-req -signkey my-server.key -days 4000
This will create a certificate which will expire in 4000 days. And finally enter:
bin\openssl x509 -in my-server.cert -out my-server.der.crt -outform DER
These commands created some files in the Apache folder
(my-server.der.crt,
my-server.csr,
my-server.key,
.rnd,
privkey.pem,
my-server.cert).
Copy the files to the folder
conf/ssl (e.g.
C:\program files\apache group\apache2\conf\ssl)
- if this folder does not exist you have to create it first.
Restart the apache service.
Point your browser to
https://servername/svn/project
...
When you've set up SSL to make your repository more secure, you
might want to disable the normal access via non-ssl (http) and
only allow https access.
To do this, you have to add another directive to the Subversion
<Location> block: SSLRequireSSL.
An example <Location> block would look like this:
<Location /svn> DAV svn SVNParentPath D:\SVN SSLRequireSSL AuthType Basic AuthName "Subversion repositories" AuthUserFile passwd #AuthzSVNAccessFile svnaccessfile Require valid-user </Location>