[svnbook commit] r2652 - trunk/src/en/book
sussman
noreply at red-bean.com
Mon Feb 5 20:34:49 CST 2007
Author: sussman
Date: Mon Feb 5 20:34:49 2007
New Revision: 2652
Modified:
trunk/src/en/book/ch-server-configuration.xml
Log:
* src/en/ch-server-configuration.xml: remove spurious whitespace.
Modified: trunk/src/en/book/ch-server-configuration.xml
==============================================================================
--- trunk/src/en/book/ch-server-configuration.xml (original)
+++ trunk/src/en/book/ch-server-configuration.xml Mon Feb 5 20:34:49 2007
@@ -1,13 +1,13 @@
<chapter id="svn.serverconfig">
<title>Server Configuration</title>
-
+
<para>A Subversion repository can be accessed simultaneously by
clients running on the same machine on which the repository
resides using the <literal>file:///</literal> method. But the
typical Subversion setup involves a single server machine being
accessed from clients on computers all over the office—or,
perhaps, all over the world.</para>
-
+
<para>This section describes how to get your Subversion repository
exposed outside its host machine for use by remote clients. We
will cover Subversion's currently available server mechanisms,
@@ -15,15 +15,15 @@
this section, you should be able to decide which networking
setup is right for your needs, and understand how to enable such
a setup on your host computer.</para>
-
-
+
+
<!-- ================================================================= -->
<!-- ================================================================= -->
<!-- ================================================================= -->
<sect1 id="svn.serverconfig.overview">
-
+
<title>Overview</title>
-
+
<para>Subversion was designed with an abstract network layer.
This means that a repository can be programmatically accessed by
any sort of server process, and the client <quote>repository
@@ -31,7 +31,7 @@
speak relevant network protocols. In theory, Subversion can use
an infinite number of network implementations. In practice,
there are only two servers at the time of writing.</para>
-
+
<para>Apache is an extremely popular webserver; using the
<command>mod_dav_svn</command> module, Apache can access a
repository and make it available to clients via the
@@ -128,7 +128,7 @@
<varlistentry>
<term>How it works:</term>
<listitem>
- <para>Install and configure and standard Apache 2.0
+ <para>Install and configure a standard Apache 2.0
server, then activate a special subversion-server module.
Clients speak to server via HTTP or HTTPS, using the WebDAV
protocol.</para>
@@ -403,7 +403,7 @@
URLs — from a security standpoint, it's effectively
the same as local users accessing
via <literal>file:///</literal>, and can entail all the
- same problems if the administrator isn't careful.)</para>
+ same problems if the administrator isn't careful.</para>
</listitem>
</itemizedlist>
@@ -589,7 +589,7 @@
<screen>
$ ls ~/.subversion/auth/svn.simple/
-5671adf2865e267db74f09ba6f872c28
+5671adf2865e267db74f09ba6f872c28
3893ed123b39500bca8a0b382839198e
5c3c22968347b390f349ff340196ed39
@@ -633,7 +633,7 @@
they're surprised to see that they're never used, i.e. new
revisions still appear to have been committed
anonymously!</para></footnote>
-
+
Typically, these options are used when:</para>
<itemizedlist>
@@ -646,7 +646,7 @@
credentials.</para>
</listitem>
</itemizedlist>
-
+
<para>Here is a final summary that describes how a Subversion
client behaves when it receives an authentication
@@ -686,7 +686,7 @@
<!-- ================================================================= -->
<!-- ================================================================= -->
<sect1 id="svn.serverconfig.svnserve">
-
+
<title>svnserve, a custom server</title>
<para>The <command>svnserve</command> program is a lightweight
@@ -758,7 +758,7 @@
the remote filesystem space. Clients then use URLs that
have that path portion removed from them, leaving much
shorter (and much less revealing) URLs:</para>
-
+
<screen>
$ svn checkout svn://host.example.com/project1
…
@@ -1256,10 +1256,10 @@
exact <command>svnserve</command> command executed
by <command>sshd</command>, as well as how to have multiple
users share a single system account.</para>
-
+
<sect3 id="svn.serverconfig.svnserve.sshtricks.setup">
<title>Initial setup</title>
-
+
<para>To begin, locate the home directory of the account
you'll be using to launch <command>svnserve</command>. Make
sure the account has an SSH public/private keypair
@@ -1278,7 +1278,7 @@
<screen>
ssh-dsa AAAABtce9euch… user at example.com
</screen>
-
+
<para>The first field describes the type of key, the second
field is the uuencoded key itself, and the third field is a
comment. However, it's a lesser known fact that the entire
@@ -1301,14 +1301,14 @@
</screen>
</sect3>
-
+
<sect3 id="svn.serverconfig.svnserve.sshtricks.fixedcmd">
<title>Controlling the invoked command</title>
<para>Because we can specify the executed server-side command,
it's easy to name a specific <command>svnserve</command>
binary to run and to pass it extra arguments:</para>
-
+
<screen>
command="/path/to/svnserve -t -r /virtual/root" TYPE KEY COMMENT
</screen>
@@ -1324,7 +1324,7 @@
system, or simply to relieve the user of having to type an
absolute path in the <literal>svn+ssh://</literal>
URL.</para>
-
+
<para>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 keypair for each
@@ -1368,7 +1368,7 @@
</sect3>
</sect2>
-
+
</sect1>
@@ -1376,7 +1376,7 @@
<!-- ================================================================= -->
<!-- ================================================================= -->
<sect1 id="svn.serverconfig.httpd">
-
+
<title>httpd, the Apache HTTP server</title>
<para>The Apache HTTP Server is a <quote>heavy duty</quote>
@@ -1407,7 +1407,7 @@
<ulink url="http://httpd.apache.org"/>. For example, a general
reference for the configuration directives is located at <ulink url="
http://httpd.apache.org/docs-2.0/mod/directives.html"/>.</para>
-
+
<para>Also, as you make changes to your Apache setup, it is likely
that somewhere along the way a mistake will be made. If you are
not already familiar with Apache's logging subsystem, you should
@@ -1420,7 +1420,7 @@
the contents of those files for information that might reveal
the source of a problem that is not clearly noticeable
otherwise.</para>
-
+
<sidebar>
<title>Why Apache 2?</title>
@@ -1453,7 +1453,7 @@
<!-- =============================================================== -->
<sect2 id="svn.serverconfig.httpd.prereqs">
<title>Prerequisites</title>
-
+
<para>To network your repository over HTTP, you basically need
four components, available in two packages. You'll need
Apache <command>httpd</command> 2.0, the
@@ -1462,7 +1462,7 @@
filesystem provider module distributed with Subversion.
Once you have all of those components, the process of
networking your repository is as simple as:</para>
-
+
<itemizedlist>
<listitem>
<para>getting httpd 2.0 up and running with the mod_dav
@@ -1478,7 +1478,7 @@
file to export (or expose) the repository.</para>
</listitem>
</itemizedlist>
-
+
<para>You can accomplish the first two items either by
compiling <command>httpd</command> and Subversion from
source code, or by installing pre-built binary packages of
@@ -1487,13 +1487,13 @@
as well as how to compile and configure Apache itself for
this purpose, see the <filename>INSTALL</filename> file in
the top level of the Subversion source code tree.</para>
-
+
</sect2>
<!-- =============================================================== -->
<sect2 id="svn.serverconfig.httpd.basic">
<title>Basic Apache Configuration</title>
-
+
<para>Once you have all the necessary components installed on
your system, all that remains is the configuration of Apache
via its <filename>httpd.conf</filename> file. Instruct Apache
@@ -1508,7 +1508,7 @@
<literal>LoadModule</literal> directive has a simple syntax,
mapping a named module to the location of a shared library on
disk:</para>
-
+
<screen>
LoadModule dav_svn_module modules/mod_dav_svn.so
</screen>
@@ -1524,7 +1524,7 @@
LoadModule dav_svn_module modules/mod_dav_svn.so
</screen>
-
+
<para>At a later location in your configuration file, you now
need to tell Apache where you keep your Subversion repository
(or repositories). The <literal>Location</literal> directive
@@ -1543,14 +1543,14 @@
repository is located at
<filename>/absolute/path/to/repository</filename> using the
following <filename>httpd.conf</filename> syntax:</para>
-
+
<screen>
<Location /repos>
DAV svn
SVNPath /absolute/path/to/repository
</Location>
</screen>
-
+
<para>If you plan to support multiple Subversion repositories
that will reside in the same parent directory on your local
disk, you can use an alternative directive, the
@@ -1562,7 +1562,7 @@
<uri>http://my.server.com/svn/repos2</uri>, and
so on, you could use the <filename>httpd.conf</filename>
configuration syntax in the following example:</para>
-
+
<screen>
<Location /svn>
DAV svn
@@ -1571,7 +1571,7 @@
SVNParentPath /usr/local/svn
</Location>
</screen>
-
+
<para>Using the previous syntax, Apache will delegate the
handling of all URLs whose path portions begin with
<filename>/svn/</filename> to the Subversion DAV provider,
@@ -1581,7 +1581,7 @@
convenient syntax in that, unlike the use of the
<literal>SVNPath</literal> directive, you don't have to
restart Apache in order to create and network new
- repositories.</para>
+ repositories.</para>
<para>Be sure that when you define your new
<literal>Location</literal>, it doesn't overlap with other
@@ -1599,7 +1599,7 @@
<sidebar>
<title>Server Names and the COPY Request</title>
-
+
<para>Subversion makes use of the <literal>COPY</literal>
request type to perform server-side copies of files and
directories. As part of the sanity checking done by the
@@ -1671,7 +1671,7 @@
repositories you make available via the
<literal>Location</literal> directive will be generally
accessible to everyone. In other words,</para>
-
+
<itemizedlist>
<listitem>
<para>anyone can use their Subversion client to checkout a
@@ -1690,7 +1690,7 @@
<sect3 id="svn.serverconfig.httpd.authn.basic">
<title>Basic HTTP Authentication</title>
-
+
<para>The easiest way to authenticate a client is via the
HTTP Basic authentication mechanism, which simply uses a
username and password to verify that a user is who she says
@@ -1700,12 +1700,12 @@
your Subversion repository. Let's grant commit access to
Sally and Harry. First, we need to add them to the password
file.</para>
-
+
<screen>
$ ### First time: use -c to create the file
$ ### Use -m to use MD5 encryption of the password, which is more secure
$ htpasswd -cm /etc/svn-auth-file harry
-New password: *****
+New password: *****
Re-type new password: *****
Adding password for user harry
$ htpasswd -m /etc/svn-auth-file sally
@@ -1729,11 +1729,11 @@
use the <literal>AuthUserFile</literal> directive to specify
the location of the password file you created using
<command>htpasswd</command>.</para>
-
+
<para>After adding these three directives, your
<literal><Location></literal> block should look
something like this:</para>
-
+
<screen>
<Location /svn>
DAV svn
@@ -1796,7 +1796,7 @@
<sect3 id="svn.serverconfig.httpd.authn.sslcerts">
<title>SSL Certificate Management</title>
-
+
<para>Businesses that need to expose their repositories for access
outside the company firewall should be conscious of the
possibility that unauthorized parties could be
@@ -1878,7 +1878,7 @@
[global]
ssl-authority-files = /path/to/CAcert1.pem;/path/to/CAcert2.pem
</screen>
-
+
<para>Many OpenSSL installations also have a pre-defined set
of <quote>default</quote> CAs that are nearly universally
trusted. To make the Subversion client automatically trust
@@ -1943,7 +1943,7 @@
</sect3>
</sect2>
-
+
<!-- =============================================================== -->
<sect2 id="svn.serverconfig.httpd.authz">
<title>Authorization Options</title>
@@ -1970,7 +1970,7 @@
<literal>sally</literal>, and provided the correct
password for their respective username, would be allowed to
do anything with the Subversion repository:</para>
-
+
<screen>
<Location /svn>
DAV svn
@@ -1980,7 +1980,7 @@
AuthType Basic
AuthName "Subversion repository"
AuthUserFile /path/to/users/file
-
+
# only authenticated users may access the repository
Require valid-user
</Location>
@@ -1999,7 +1999,7 @@
have starting and ending tags, and you would nest them
inside your <literal><Location></literal>
block.</para>
-
+
<para>The parameters present on the <literal>Limit</literal>
and <literal>LimitExcept</literal> directives are HTTP
request types that are affected by that block. For example,
@@ -2013,7 +2013,7 @@
directive would be placed inside the
<literal><LimitExcept></literal> block instead of just
inside the <literal><Location></literal> block.</para>
-
+
<screen>
<Location /svn>
DAV svn
@@ -2037,7 +2037,7 @@
<literal>Security</literal> section of the Apache
documentation's tutorials collection at <ulink
url="http://httpd.apache.org/docs-2.0/misc/tutorials.html"/>.</para>
-
+
</sect3>
@@ -2094,7 +2094,7 @@
SVNParentPath /usr/local/svn
# our access control policy
- AuthzSVNAccessFile /path/to/access/file
+ AuthzSVNAccessFile /path/to/access/file
</Location>
</programlisting>
</example>
@@ -2112,17 +2112,17 @@
<Location /repos>
DAV svn
SVNParentPath /usr/local/svn
-
+
# our access control policy
- AuthzSVNAccessFile /path/to/access/file
-
+ AuthzSVNAccessFile /path/to/access/file
+
# only authenticated users may access the repository
Require valid-user
-
+
# how to authenticate a user
AuthType Basic
AuthName "Subversion repository"
- AuthUserFile /path/to/users/file
+ AuthUserFile /path/to/users/file
</Location>
</programlisting>
</example>
@@ -2146,19 +2146,19 @@
<Location /repos>
DAV svn
SVNParentPath /usr/local/svn
-
+
# our access control policy
- AuthzSVNAccessFile /path/to/access/file
-
- # try anonymous access first, resort to real
+ AuthzSVNAccessFile /path/to/access/file
+
+ # try anonymous access first, resort to real
# authentication if necessary.
Satisfy Any
Require valid-user
-
+
# how to authenticate a user
AuthType Basic
AuthName "Subversion repository"
- AuthUserFile /path/to/users/file
+ AuthUserFile /path/to/users/file
</Location>
</programlisting>
</example>
@@ -2223,9 +2223,9 @@
<Location /repos>
DAV svn
SVNParentPath /usr/local/svn
-
+
SVNPathAuthz off
-</Location>
+</Location>
</programlisting>
</example>
@@ -2249,7 +2249,7 @@
<sect3 id="svn.serverconfig.httpd.extra.browsing">
<title>Repository Browsing</title>
-
+
<para>One of the most useful benefits of an Apache/WebDAV
configuration for your Subversion repository is that the
youngest revisions of your versioned files and directories
@@ -2367,7 +2367,7 @@
to generate XML output when displaying a directory
listing, and to reference the XSLT stylesheet of your
choice:</para>
-
+
<screen>
<Location /svn>
DAV svn
@@ -2542,7 +2542,7 @@
extreme cases, this minimized network transmission could be
the difference between an operation timing out or completing
successfully.</para>
-
+
<para>Less interesting, but equally useful, are other features
of the Apache and Subversion relationship, such as the
ability to specify a custom port (instead of the default
@@ -2561,7 +2561,7 @@
complicated topic; for details, read <xref
linkend="svn.webdav"/>.</para>
-
+
</sect3>
</sect2>
@@ -2809,17 +2809,17 @@
<!-- ================================================================= -->
<!-- ================================================================= -->
<sect1 id="svn.serverconfig.multimethod">
-
+
<title>Supporting Multiple Repository Access Methods</title>
<para>You've seen how a repository can be accessed in many
different ways. But is it possible—or safe—for your
repository to be accessed by multiple methods simultaneously?
The answer is yes, provided you use a bit of foresight.</para>
-
+
<para>At any given time, these processes may require read and
write access to your repository:</para>
-
+
<itemizedlist>
<listitem>
<para>regular system users using a Subversion client (as
@@ -2842,7 +2842,7 @@
particular fixed user.</para>
</listitem>
</itemizedlist>
-
+
<para>The most common problem administrators run into is repository
ownership and permissions. Does every process (or user) in the
previous list have the rights to read and write the Berkeley DB
@@ -2853,7 +2853,7 @@
not enough, because a process may write to the database files
using an unfriendly umask—one that prevents access by
other users.</para>
-
+
<para>So the next step beyond setting up a common group for
repository users is to force every repository-accessing process
to use a sane umask. For users accessing the repository
@@ -2891,7 +2891,7 @@
seem a bit messy and complicated, but the problems of having
multiple users sharing write-access to common files are classic
ones that are not often elegantly solved.</para>
-
+
<para>Fortunately, most repository administrators will never
<emphasis>need</emphasis> to have such a complex configuration.
Users who wish to access repositories that live on the same
@@ -2947,7 +2947,7 @@
</chapter>
<!--
-local variables:
+local variables:
sgml-parent-document: ("book.xml" "chapter")
end:
-->
More information about the svnbook-dev
mailing list