<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">
<sect1 id="tsvn-serversetup-apache">
	<title>Apache Based Server</title>
	<sect2 id="tsvn-serversetup-apache-1">
		<title>Introduction</title>
		<indexterm>
			<primary>Apache</primary>
		</indexterm>
		<para>
			The most flexible of all possible server setups for Git
			is the Apache based one. Although a bit more complicated to set up,
			it offers benefits that other servers cannot:
		</para>
		<indexterm>
			<primary>WebDAV</primary>
		</indexterm>
		<variablelist>
			<varlistentry>
				<term>WebDAV</term>
				<listitem>
					<para>
						The Apache based Git server uses the
						WebDAV protocol which is supported by many other
						programs as well. You could e.g. mount such
						a repository as a <quote>Web folder</quote> in the Windows
						explorer and then access it like any other
						folder in the file system.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>Browsing The Repository</term>
				<listitem>
					<para>
						You can point your browser to the URL of your
						repository and browse the contents of it without
						having a Git client installed. This
						gives access to your data to a much wider circle of
						users.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>Authentication</term>
				<listitem>
					<para>
						You can use any authentication mechanism Apache
						supports, including SSPI and LDAP.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>Security</term>
				<listitem>
					<para>
						Since Apache is very stable and secure,
						you automatically get the same security for your
						repository. This includes SSL encryption.
					</para>
				</listitem>
			</varlistentry>
		</variablelist>
	</sect2>
	<sect2 id="tsvn-serversetup-apache-2">
		<title>Installing Apache</title>
		<para>
			The first thing you need before installing Apache is a computer
			with Windows 2000, Windows XP+SP1, Windows 2003, Vista or Server 2008.
			<warning>
				<para>
					Please note that Windows XP without the service pack 1
					will lead to bogus network data and could therefore
					corrupt your repository!
				</para>
			</warning>
			<orderedlist>
				<listitem>
					<para>
						Download the latest version of the Apache
						web server from
						<ulink url="http://httpd.apache.org/download.cgi">
							<citetitle>http://httpd.apache.org/download.cgi</citetitle>
						</ulink>.
						Make sure that you download the version 2.2.x -
						the version 1.3.xx won't work!
					</para>
					<para>
						The msi installer for Apache can be found by clicking on <literal>other files</literal>,
						then browse to <filename>binaries/win32</filename>. You may want to choose
						the msi file <filename>apache-2.2.x-win32-x86-openssl-0.9.x.msi</filename>
						(the one that includes OpenSSL).
					</para>
				</listitem>
				<listitem>
					<para>
						Once you have the Apache2 installer you
						can double click 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
						<emphasis>for All Users, on Port 80, as a Service</emphasis>.
						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,
						<filename>\Apache Group\Apache2\conf</filename>
						and locate the file
						<filename>httpd.conf</filename>. Edit that file so that
						<literal>Listen 80</literal> is changed to a free
						port, e.g. <literal>Listen 81</literal>.
						Then restart the installation - this time it should
						finish without problems.
					</para>
				</listitem>
				<listitem>
					<para>
						Now test if the Apache web server is running
						correctly by pointing your web browser to
						<systemitem class="url">http://localhost/</systemitem>
						- a preconfigured Website should show up.
					</para>
				</listitem>
			</orderedlist>
			<caution>
				<para>
					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.
				</para>
				<para>
					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.
				</para>
				<para>
					Even if Apache runs as local system, you still need such an entry 
					(which will be the SYSTEM account in this case).
				</para>
				<para>
					If Apache does not have this permission set up, your users will get 
					<quote>Access denied</quote> error messages, which show up in the Apache error log 
					as error 500.
				</para>
			</caution>
		</para>
	</sect2>
	<sect2 id="tsvn-serversetup-apache-3">
		<title>Installing Git</title>
		<para>
			<orderedlist>
				<listitem>
					<para>
						Download the latest version of the Git Win32 binaries for
						Apache. Be sure to get the right version to integrate with your
						version of Apache, otherwise you will get an obscure error
						message when you try to restart.
						If you have Apache 2.2.x go to
						<ulink url="http://Git.tigris.org/servlets/ProjectDocumentList?folderID=8100">
							<citetitle>http://Git.tigris.org/servlets/ProjectDocumentList?folderID=8100</citetitle>
						</ulink>.
					</para>
				</listitem>
				<listitem>
					<para>
						Run the Git installer and follow
						the instructions. If the Git 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.
					</para>
				</listitem>
				<listitem>
					<indexterm>
						<primary>mod_authz_svn</primary>
					</indexterm>
					<para>
						Using the windows explorer, go to the installation
						directory of Git (usually
						<filename>c:\program files\Git</filename>)
						and find the files
						<filename>/httpd/mod_dav_svn.so</filename> and
						<filename>mod_authz_svn.so</filename>. Copy these files
						to the Apache modules directory	(usually
						<filename>c:\program files\apache group\apache2\modules
						</filename>).
					</para>
				</listitem>
				<listitem>
					<para>
						Copy the file <filename>/bin/libdb*.dll</filename>
						and <filename>/bin/intl3_svn.dll</filename> from
						the Git installation directory to the Apache
						bin directory.
					</para>
				</listitem>
				<listitem>
					<para>
						Edit Apache's configuration file (usually <filename>
						C:\Program Files\Apache
						Group\Apache2\conf\httpd.conf</filename>) with a text
						editor such as Notepad and make the following changes:
					</para>
					<para>
						Uncomment (remove the '<literal>#</literal>' mark) the
						following lines:
<screen>
#LoadModule dav_fs_module modules/mod_dav_fs.so
#LoadModule dav_module modules/mod_dav.so
</screen>
						Add the following two lines to the end of the
						<literal>LoadModule</literal> section.
<screen>
LoadModule dav_svn_module modules/mod_dav_svn.so
LoadModule authz_svn_module modules/mod_authz_svn.so
</screen>
					</para>
				</listitem>
			</orderedlist>
		</para>
	</sect2>
	<sect2 id="tsvn-serversetup-apache-4">
		<title>Configuration</title>
		<para>
			Now you have set up Apache and Git, but Apache doesn't
			know how to handle Git clients like TortoiseGit yet.
			To get Apache to know which URL will be used for Git
			repositories you have to edit the Apache configuration file (usually
			located in
			<filename>c:\program files\apache group\apache2\conf\httpd.conf</filename>)
			with any text editor you like (e.g. Notepad):
		<orderedlist>
				<listitem>
					<para>
						At the end of the config file add the following lines:
<screen>
&lt;Location /svn&gt;
  DAV svn
  SVNListParentPath on
  SVNParentPath D:\SVN
  #SVNIndexXSLT "/svnindex.xsl"
  AuthType Basic
  AuthName "Git repositories"
  AuthUserFile passwd
  #AuthzSVNAccessFile svnaccessfile
  Require valid-user
&lt;/Location&gt;
</screen>
						This configures Apache so that all your Git
						repositories are physically located below
						<filename>D:\SVN</filename>. The repositories are
						served to the outside world from the URL:
						<systemitem class="url">
							http://MyServer/svn/
						</systemitem>.
						Access is restricted to known users/passwords 
						listed in the <filename>passwd</filename> file.
					</para>
				</listitem>
				<listitem>
					<para>
						To create the <filename>passwd</filename>
						file, open the command prompt (DOS-Box) again,
						change to the <filename>apache2</filename> folder (usually
						<filename>c:\program files\apache
						group\apache2</filename>)
						and create the file by entering
<screen>
bin\htpasswd -c passwd &lt;username&gt;
</screen>
						This will create a file with the name <filename>passwd</filename> which is
						used for authentication. Additional users can be added
						with
<screen>
bin\htpasswd passwd &lt;username&gt;
</screen>
					</para>
				</listitem>
				<listitem>
					<para>
						Restart the Apache service again.
					</para>
				</listitem>
				<listitem>
					<para>
						Point your browser to
						<systemitem class="url">http://MyServer/svn/MyNewRepository</systemitem>
						(where <filename>MyNewRepository</filename> is the name of the
						Git 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.
					</para>
				</listitem>
			</orderedlist>
		</para>
		<indexterm>
			<primary>SVNPath</primary>
		</indexterm>
		<indexterm>
			<primary>SVNParentPath</primary>
		</indexterm>
		<para>
			A short explanation of what you just entered:
			<table id="tsvn-serversetup-apache-4-table">
				<title>Apache <filename>httpd.conf</filename> Settings</title>
				<tgroup cols="2">
					<colspec colnum="1" colwidth="1.5*"/>
					<colspec colnum="2" colwidth="3*"/>
					<thead>
						<row>
							<entry>Setting</entry>
							<entry>Explanation</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry condition="pot">&lt;Location /svn&gt;</entry>
							<entry>
								means that the Git repositories are available from the URL
								<systemitem class="url">http://MyServer/svn/</systemitem>
							</entry>
						</row>
						<row>
							<entry condition="pot">DAV svn</entry>
							<entry>
								tells Apache which module will be responsible to serve
								that URL - in this case the Git module.
							</entry>
						</row>
						<row>
							<entry condition="pot">SVNListParentPath on</entry>
							<entry>
								For Git version 1.3 and higher, this directive enables
								listing all the available repositories under
								<literal>SVNParentPath</literal>.
							</entry>
						</row>
						<row>
							<entry condition="pot">SVNParentPath D:\SVN</entry>
							<entry>
								tells Git to look for repositories below
								<filename>D:\SVN</filename>
							</entry>
						</row>
						<row>
							<entry condition="pot">SVNIndexXSLT "/svnindex.xsl"</entry>
							<entry>
								Used to make the browsing with a web browser
								prettier.
							</entry>
						</row>						
						<row>
							<entry condition="pot">AuthType Basic</entry>
							<entry>
								is to activate basic authentication, i.e.
								Username/password
							</entry>
						</row>
						<row>
							<entry condition="pot">AuthName "Git repositories"</entry>
							<entry>
								is used as an information whenever an authentication
								dialog pops up to tell the user what the authentication is for
							</entry>
						</row>
						<row>
							<entry condition="pot">AuthUserFile passwd</entry>
							<entry>
								specifies which password file to use for authentication
							</entry>
						</row>
						<row>
							<entry condition="pot">AuthzSVNAccessFile</entry>
							<entry>
								Location of the Access file for paths inside a
								Git repository
							</entry>
						</row>
						<row>
							<entry condition="pot">Require valid-user</entry>
							<entry>
								specifies that only users who entered a correct
								username/password are allowed to access the URL
							</entry>
						</row>
					</tbody>
				</tgroup>
			</table>
			But that's just an example. There are many, many more
			possibilities of what you can do with the Apache web server.
			<itemizedlist>
				<listitem>
					<para>
						If you want your repository to have read
						access for everyone but write access only for specific
						users you can change the line
<screen>
Require valid-user
</screen> to
<screen>
&lt;LimitExcept GET PROPFIND OPTIONS REPORT&gt;
Require valid-user
&lt;/LimitExcept&gt;
</screen>
					</para>
				</listitem>
				<listitem>
					<para>
						Using a <filename>passwd</filename> file limits and 
						grants access to all of your repositories as a unit. 
						If you want more control over which users have 
						access to each folder inside a repository you can 
						uncomment the line
<screen>
#AuthzSVNAccessFile svnaccessfile
</screen>
						and create a Git access file. Apache will 
						make sure that only valid users are able to access 
						your <filename>/svn</filename> location, and will then 
						pass the username to Git's <literal>AuthzSVNAccessFile</literal> 
						module so that it can enforce more granular access 
						based upon rules listed in the Git access file.
						Note that paths are specified either as
						<literal>repos:path</literal> or simply
						<literal>path</literal>. If you don't specify a
						particular repository, that access rule will apply to
						all repositories under
						<literal>SVNParentPath</literal>.
						The format of the authorization-policy file used by
						<literal>mod_authz_svn</literal> is described in
						<xref linkend="tsvn-serversetup-mod_authz_svn"/>
					</para>
				</listitem>
				<listitem>
					<para>
						To make browsing the repository with a web browser
						'prettier', uncomment the line
<screen>
#SVNIndexXSLT "/svnindex.xsl"
</screen>
						and put the files <filename>svnindex.xsl</filename>,
						<filename>svnindex.css</filename> and 
						<filename>menucheckout.ico</filename> in your document
						root directory (usually <filename>C:/Program Files/Apache Group/Apache2/htdocs</filename>).
						The directory is set with the <literal>DocumentRoot</literal> directive
						in your Apache config file.
					</para>
					<para>
						You can get those three files directly from our source repository
						at
						<ulink url="http://TortoiseGit.tigris.org/svn/TortoiseGit/trunk/contrib/other/svnindex">
							<citetitle>http://TortoiseGit.tigris.org/svn/TortoiseGit/trunk/contrib/other/svnindex</citetitle>
						</ulink>.
						(<xref linkend="tsvn-preface-source"/> explains how to access the TortoiseGit source repository).
					</para>
					<para>
						The XSL file from the TortoiseGit repository has a nice
						gimmick: if you browse the repository with your web browser, then
						every folder in your repository has an icon on the right shown.
						If you click on that icon, the TortoiseGit checkout dialog
						is started for this URL.
					</para>
				</listitem>
			</itemizedlist>
		</para>
	</sect2>
	<sect2 id="tsvn-serversetup-apache-parent-path">
		<title>Multiple Repositories</title>
		<indexterm>
			<primary>SVNParentPath</primary>
		</indexterm>
		<indexterm>
			<primary>Index of projects</primary>
		</indexterm>
		<para>
			If you used the <literal>SVNParentPath</literal> directive then you don't have to
			change the Apache config file every time you add a new Git
			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 TortoiseGit command
			<menuchoice>
				<guimenu>TortoiseGit</guimenu>
				<guimenuitem>Create repository here...</guimenuitem>
			</menuchoice>
			and a new project has a home...
		</para>
		<para>
			If you are using Git 1.3 or later, you can use the
			<literal>SVNListParentPath on</literal> directive to allow Apache
			to produce a listing of all available projects if you point your
			browser at the parent path rather than at a specific repository.
		</para>
	</sect2>
	<sect2 id="tsvn-serversetup-mod_authz_svn">
		<title>Path-Based Authorization</title>
		<indexterm>
			<primary>Authorization</primary>
		</indexterm>
		<indexterm>
			<primary>mod_authz_svn</primary>
		</indexterm>
		<para>
			The <literal>mod_authz_svn</literal> module permits fine-grained control of access
			permissions based on user names and repository paths. This is
			available with the Apache server, and as of Git 1.3
			it is available with svnserve as well.
		</para>
		<para>
			An example file would look like this:
<screen>
[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
</screen>
		</para>
		<para>
			Note that checking every path can be an expensive operation,
			particularly in the case of the revision log. The server
			checks every changed path in each revision and checks it for
			readability, which can be time-consuming on revisions which
			affect large numbers of files.
		</para>
		<para>
			Authentication and authorization are separate processes. If
			a user wants to gain access to a repository path, she has to meet
			<emphasis>both</emphasis>, the usual authentication requirements
			and the authorization requirements of the access file.
		</para>
	</sect2>
	<sect2 id="tsvn-serversetup-apache-5">
		<title>Authentication With a Windows Domain</title>
		<indexterm>
			<primary>Windows domain</primary>
		</indexterm>
		<indexterm>
			<primary>domaincontroller</primary>
		</indexterm>
		<para>
			As you might have noticed you need to make a username/password
			entry in the <filename>passwd</filename> 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.
		</para>
		<para>
			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: <literal>mod_auth_sspi</literal>!
		</para>
		<indexterm>
			<primary>SSPI</primary>
		</indexterm>
		<indexterm>
			<primary>NTLM</primary>
		</indexterm>
		<para>
			The original SSPI module was offered by Syneapps including
			source code. But the development for it has been stopped. 
			But don't despair, the community has picked it up and improved
			it. It has a new home on 
			<ulink url="http://sourceforge.net/projects/mod-auth-sspi/">
				<citetitle>SourceForge</citetitle>
			</ulink>.
		</para>
		<itemizedlist>
			<listitem>
				<para>
					Download the module which matches your apache version, 
					then copy the file <filename>mod_auth_sspi.so</filename>
					into the Apache modules folder.
				</para>
			</listitem>
			<listitem>
				<para>
					Edit the Apache config file: add the line
<screen>
LoadModule sspi_auth_module modules/mod_auth_sspi.so
</screen>
					to the <literal>LoadModule</literal> section. Make sure you
					insert this line <emphasis>before</emphasis> the line
<screen>
LoadModule auth_module modules/mod_auth.so
</screen>
				</para>
			</listitem>
			<listitem>
				<para>
					To make the Git location use this
					type of authentication you have to change the line
<screen>
AuthType Basic
</screen>
					to
<screen>
AuthType SSPI
</screen>
					also you need to add
<screen>
SSPIAuth On
SSPIAuthoritative On
SSPIDomain &lt;domaincontroller&gt;
SSPIOmitDomain on
SSPIUsernameCase lower
SSPIPerRequestAuth on
SSPIOfferBasic On
</screen>
					within the <literal>&lt;Location /svn&gt;</literal> block.
					If you don't have a domain controller, leave the name of
					the domain control as <literal>&lt;domaincontroller&gt;</literal>.
				</para>
			</listitem>
		</itemizedlist>
		<para>
			Note that if you are authenticating using SSPI, then you don't
			need the <literal>AuthUserFile</literal> 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 <filename>svnaccessfile</filename> 
			to reference <literal>DOMAIN\username</literal> as well.

		</para>
		<important>
			<para>
				The SSPI authentication is only enabled for SSL secured
				connections (https). If you're only using normal http
				connections to your server, it won't work.
			</para>
			<para>
				To enable SSL on your server, see the chapter:
				<xref linkend="tsvn-serversetup-apache-7"/>
			</para>
		</important>
		<tip>
			<para>
				Git <filename>AuthzSVNAccessFile</filename> files are
				case sensitive in regard to user names (<literal>JUser</literal>
				is different from <literal>juser</literal>). 
			</para>
			<para>
				In Microsoft's world, Windows domains and user names are not
				case sensitive.  Even so, some network administrators like 
				to create user accounts in CamelCase (e.g. <literal>JUser</literal>).
			</para>
			<para>
				This difference can bite you when using SSPI authentication 
				as the windows domain and user names are passed to Git 
				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.
			</para>
			<para>
				The end result is that you may need at least two entries in your
				<literal>AuthzSVNAccessFile</literal> 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
				TortoiseGit.  
			</para>
			<para>
				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 Git's 
				<literal>AuthzSVNAccessFile</literal> module. You may need to
				experiment with the exact format of the user string in the
				<literal>svnaccessfile</literal>
				(e.g. <literal>DOMAIN\user</literal> vs. 
				<literal>DOMAIN//user</literal>) in order to get 
				everything working.
			</para>
		</tip>
	</sect2>
	<sect2 id="tsvn-serversetup-apache-6">
		<title>Multiple Authentication Sources</title>
		<indexterm>
			<primary>Multiple authentication</primary>
		</indexterm>
		<para>
			It is also possible to have more than one authentication source for
			your Git repository. To do this, you need to make each 
			authentication type non-authoritative, so that Apache will check
			multiple sources for a matching username/password.
		</para>
		<para>
			A common scenario is to use both Windows domain authentication and 
			a <literal>passwd</literal> file, so that you can provide SVN access
			to users who don't have a Windows domain login.
		</para>
		<itemizedlist>
			<listitem>
				<para>
					To enable both Windows domain and <filename>passwd</filename>
					file authentication, add the following entries within the 
					<literal>&lt;Location&gt;</literal> block of your Apache config file:
<screen>
AuthBasicAuthoritative Off
SSPIAuthoritative Off
</screen>
				</para>
			</listitem>
		</itemizedlist>
		<para>
			Here is an example of the full Apache configuration for combined Windows 
			domain and <literal>passwd</literal> file authentication:
<screen>
&lt;Location /svn&gt;
  DAV svn
  SVNListParentPath on
  SVNParentPath D:\SVN

  AuthName "Git repositories"
  AuthzSVNAccessFile svnaccessfile.txt

# NT Domain Logins.
  AuthType SSPI
  SSPIAuth On
  SSPIAuthoritative Off
  SSPIDomain &lt;domaincontroller&gt;
  SSPIOfferBasic On

# Htpasswd Logins.
  AuthType Basic
  AuthBasicAuthoritative Off
  AuthUserFile passwd

  Require valid-user
&lt;/Location&gt;
</screen>
		</para>
	</sect2>
	<sect2 id="tsvn-serversetup-apache-7">
		<title>Securing the server with SSL</title>
		<indexterm>
			<primary>SSL</primary>
		</indexterm>
		<para>
			Even though Apache 2.2.x has OpenSSL support, it is not
			activated by default. You need to activate this manually.
		</para>
		<orderedlist>
			<listitem>
				<para>
					In the apache config file, uncomment the lines:
<screen>
#LoadModule ssl_module modules/mod_ssl.so
</screen>
					and at the bottom
<screen>
#Include conf/extra/httpd-ssl.conf
</screen>
					then change the line (on one line)
<screen>
SSLMutex "file:C:/Program Files/Apache Software Foundation/\
Apache2.2/logs/ssl_mutex"
</screen>
					to
<screen>
SSLMutex default
</screen>
					
				</para>
			</listitem>
			<listitem>
				<para>
					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.
					<filename>C:\program files\apache group\apache2</filename>)
					and type the following command:
<screen>
bin\openssl req -config conf\openssl.cnf -new -out my-server.csr
</screen>
					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 your server. All other questions are optional but we
					recommend you fill those in too.
				</para>
				<para>
					Normally the <filename>privkey.pem</filename> file is created
					automatically, but if it isn't you need to type this command
					to generate it:
<screen>
bin\openssl genrsa -out conf\privkey.pem 2048
</screen>
				</para>
				<para>
					Next type the commands
<screen>
bin\openssl rsa -in conf\privkey.pem -out conf\server.key
</screen>
					and (on one line)
<screen>
bin\openssl req -new -key conf\server.key -out conf\server.csr \
-config conf\openssl.cnf
</screen>
					and then (on one line)
<screen>
bin\openssl x509 -in conf\server.csr -out conf\server.crt
                 -req -signkey conf\server.key -days 4000
</screen>
					This will create a certificate which will expire in
					4000 days. And finally enter (on one line):
<screen>
bin\openssl x509 -in conf\server.cert -out conf\server.der.crt
                 -outform DER
</screen>
					These commands created some files in the Apache
					<filename>conf</filename> folder 
					(<filename>server.der.crt</filename>,
					<filename>server.csr</filename>,
					<filename>server.key</filename>,
					<filename>.rnd</filename>,
					<filename>privkey.pem</filename>,
					<filename>server.cert</filename>).
				</para>
			</listitem>
			<listitem>
				<para>
					Restart the Apache service.
				</para>
			</listitem>
			<listitem>
				<para>
					Point your browser to
					<systemitem class="url">https://servername/svn/project</systemitem>
					...
				</para>
			</listitem>
		</orderedlist>
		<important>
			<title>SSL and Internet Explorer</title>
			<para>
				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 TortoiseGit and any other Git client are
				still able to authenticate.
			</para>
			<para>
				If you still want to use IE to browse the repository
				you can either:
				<itemizedlist>
					<listitem>
						<para>
							define a separate <literal>&lt;Location /path&gt;</literal>
							directive in the Apache config file, and add the
							<literal>SSPIBasicPreferred On</literal>.
							This will allow IE to authenticate again, but
							other browsers and Git won't be able to
							authenticate against that location.
						</para>
					</listitem>
					<listitem>
						<para>
							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.
						</para>
					</listitem>
					<listitem>
						<para>
						In the SSL "standard" setup there's often the 
						following statement in Apache's virtual SSL host:
<screen>
SetEnvIf User-Agent ".*MSIE.*" \
             nokeepalive ssl-unclean-shutdown \
             downgrade-1.0 force-response-1.0
</screen>
						There are (were?) good reasons for this configuration, 
						see
						<ulink url="http://www.modssl.org/docs/2.8/ssl_faq.html#ToC49">
								<citetitle>http://www.modssl.org/docs/2.8/ssl_faq.html#ToC49</citetitle>
							</ulink>
						But if you want NTLM authentication you have to use <literal>keepalive</literal>.
						If You uncomment the whole <literal>SetEnvIf</literal> you should be able to
						authenticate IE with windows authentication over SSL against 
						the Apache on Win32 with included <literal>mod_auth_sspi</literal>.
						</para>
					</listitem>
				</itemizedlist>
			</para>
		</important>
		<important>
			<title>Forcing SSL access</title>
			<para>
				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 Git
				<literal>&lt;Location&gt;</literal> block: <literal>SSLRequireSSL</literal>.
			</para>
			<para>
					An example <literal>&lt;Location&gt;</literal> block would look like this:
<screen>
&lt;Location /svn&gt;
  DAV svn
  SVNParentPath D:\SVN
  SSLRequireSSL
  AuthType Basic
  AuthName "Git repositories"
  AuthUserFile passwd
  #AuthzSVNAccessFile svnaccessfile
  Require valid-user
&lt;/Location&gt;
</screen>
			</para>
		</important>
	</sect2>
	<sect2 id="tsvn-serversetup-apache-sslcerts">
		<title>Using client certificates with virtual SSL hosts</title>
		<para>
			Sent to the TortoiseGit mailing list by Nigel Green. Thanks!
		</para>
		<para>
			In some server configurations you may need to setup a single server
			containing 2 virtual SSL hosts: The first one for public web access, 
			with no requirement for a client certificate. The second one to be
			secure with a required client certificate, running a Git server.
		</para>
		<para>
			Adding an <literal>SSLVerifyClient Optional</literal> directive to the 
			<emphasis>per-server</emphasis> section of the Apache configuration
			(i.e. outside of any <literal>VirtualHost</literal> and
			<literal>Directory</literal> blocks) forces Apache to request a client
			Certificate in the initial SSL handshake. Due to a bug in
			<literal>mod_ssl</literal> it is essential that the certificate is
			requested at this point as it does not work if the SSL connection
			is re-negotiated.
		</para>
		<para>
			The solution is to add the following directive to the virtual host
			directory that you want to lock down for Git:
<screen>
SSLRequire %{SSL_CLIENT_VERIFY} eq "SUCCESS"
</screen>
			This directive grants access to the directory only if a 
			client certificate was received and verified successfully. 
		</para>
		<para>
			To summarise, the relevant lines of the Apache configuration are:
<screen>
SSLVerifyClient Optional

### Virtual host configuration for the PUBLIC host 
### (not requiring a certificate)

&lt;VirtualHost 127.0.0.1:443&gt;
  &lt;Directory "pathtopublicfileroot"&gt;
  &lt;/Directory&gt;
&lt;/VirtualHost&gt;

### Virtual host configuration for Git 
### (requiring a client certificate)
&lt;VirtualHost 127.0.0.1:443&gt;
  &lt;Directory "Git host root path"&gt;
    SSLRequire %{SSL_CLIENT_VERIFY} eq "SUCCESS"
  &lt;/Directory&gt;

  &lt;Location /svn&gt;
    DAV svn
    SVNParentPath /pathtorepository
  &lt;/Location&gt;
&lt;/VirtualHost&gt;
</screen>
		</para>
	</sect2>
</sect1>
