[svnbook commit] r3048 - trunk/src/en/book
sussman
noreply at red-bean.com
Fri May 2 21:00:25 CDT 2008
Author: sussman
Date: Fri May 2 21:00:25 2008
New Revision: 3048
Log:
* ch06-server-configuration.xml: copyedit checkpoint.
Modified:
trunk/src/en/book/ch06-server-configuration.xml
Modified: trunk/src/en/book/ch06-server-configuration.xml
==============================================================================
--- trunk/src/en/book/ch06-server-configuration.xml (original)
+++ trunk/src/en/book/ch06-server-configuration.xml Fri May 2 21:00:25 2008
@@ -1307,9 +1307,9 @@
<para>In this example, <filename>/path/to/svnserve</filename>
might be a custom wrapper script
around <command>svnserve</command> which sets the umask (see
- <xref linkend="svn.serverconfig.multimethod"/>). It also shows how to
- anchor <command>svnserve</command> in a virtual root
- directory, just as one often does when
+ <xref linkend="svn.serverconfig.multimethod"/>.) It also
+ shows how to anchor <command>svnserve</command> in a virtual
+ root directory, just as one often does when
running <command>svnserve</command> as a daemon process.
This might be done either to restrict access to parts of the
system, or simply to relieve the user of having to type an
@@ -1318,7 +1318,7 @@
<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
+ each user, generate a public/private key-pair for each
person. Then place each public key into
the <filename>authorized_users</filename> file, one per
line, and use the <option>--tunnel-user</option>
@@ -1344,7 +1344,7 @@
other forms of SSH access, even if you've set
the <literal>command</literal> value
in <filename>authorized_keys</filename>. For example, the
- user may still get shell access through SSH, or be able to
+ user may still get shell access through SSH or be able to
perform X11 or general port-forwarding through your server.
To give the user as little permission as possible, you may
want to specify a number of restrictive options immediately
@@ -1376,7 +1376,7 @@
<!-- ================================================================= -->
<sect1 id="svn.serverconfig.httpd">
- <title>httpd, the Apache HTTP server</title>
+ <title>httpd, the Apache HTTP Server</title>
<para>The Apache HTTP Server is a <quote>heavy duty</quote>
network server that Subversion can leverage. Via a custom
@@ -1388,13 +1388,11 @@
writing—specifically, versioned
writing—capabilities. The result is a standardized,
robust system that is conveniently packaged as part of the
- Apache 2.0 software, is supported by numerous operating systems
+ Apache 2.0 software, supported by numerous operating systems
and third-party products, and doesn't require network
- administrators to open up yet another custom port.
- <footnote>
- <para>They really hate doing that.</para>
- </footnote>
- While an Apache-Subversion server has more features than
+ administrators to open up yet another custom port.<footnote>
+ <para>They really hate doing that.</para></footnote> While an
+ Apache-Subversion server has more features than
<command>svnserve</command>, it's also a bit more difficult
to set up. With flexibility often comes more complexity.</para>
@@ -1402,9 +1400,10 @@
Apache configuration directives. While some examples are given
of the use of these directives, describing them in full is
outside the scope of this chapter. The Apache team maintains
- excellent documentation, publicly available on their website at
+ excellent documentation, publicly available on their web site at
<ulink url="http://httpd.apache.org"/>. For example, a general
- reference for the configuration directives is located at <ulink url="
+ 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
@@ -1414,11 +1413,11 @@
file are directives that specify the on-disk locations of the
access and error logs generated by Apache (the
<literal>CustomLog</literal> and <literal>ErrorLog</literal>
- directives, respectively). Subversion's mod_dav_svn uses
- Apache's error logging interface as well. You can always browse
- the contents of those files for information that might reveal
- the source of a problem that is not clearly noticeable
- otherwise.</para>
+ directives, respectively).
+ Subversion's <command>mod_dav_svn</command> uses Apache's error
+ logging interface as well. You can always browse 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>
@@ -1430,21 +1429,21 @@
been somewhat slow to upgrade to the Apache 2.X series for
various reasons: some people fear change, especially changing
something as critical as a web server. Other people depend on
- plug-in modules that only work against the Apache 1.3 API, and
- are waiting for a 2.X port. Whatever the reason, many people
- begin to worry when they first discover that Subversion's
- Apache module is written specifically for the Apache 2 API.</para>
+ plug-in modules that work only against the Apache 1.3 API, and
+ they are waiting for a 2.X port. Whatever the reason, many
+ people begin to worry when they first discover that
+ Subversion's Apache module is written specifically for the
+ Apache 2 API.</para>
<para>The proper response to this problem is: don't worry about
- it. It's easy to run Apache 1.3 and Apache 2 side-by-side;
- simply install them to separate places, and use Apache 2 as a
+ it. It's easy to run Apache 1.3 and Apache 2 side by side;
+ simply install them to separate places and use Apache 2 as a
dedicated Subversion server that runs on a port other than 80.
Clients can access the repository by placing the port number
into the URL:</para>
<screen>
$ svn checkout http://host.example.com:7382/repos/project
-…
</screen>
</sidebar>
@@ -1464,23 +1463,23 @@
<itemizedlist>
<listitem>
- <para>getting httpd 2.0 up and running with the mod_dav
- module,</para>
+ <para>Getting httpd 2.0 up and running with
+ the <command>mod_dav</command> module</para>
</listitem>
<listitem>
- <para>installing the mod_dav_svn plugin to mod_dav, which
- uses Subversion's libraries to access the repository,
- and</para>
+ <para>Installing the <command>mod_dav_svn</command> back end
+ to <command>mod_dav</command>, which uses Subversion's
+ libraries to access the repository</para>
</listitem>
<listitem>
- <para>configuring your <filename>httpd.conf</filename>
- file to export (or expose) the repository.</para>
+ <para>Configuring your <filename>httpd.conf</filename>
+ 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
+ source code or by installing prebuilt binary packages of
them on your system. For the most up-to-date information on
how to compile Subversion for use with the Apache HTTP Server,
as well as how to compile and configure Apache itself for
@@ -1496,7 +1495,7 @@
<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
- to load the mod_dav_svn module using the
+ to load the <command>mod_dav_svn</command> module using the
<literal>LoadModule</literal> directive. This directive must
precede any other Subversion-related configuration items. If
your Apache was installed using the default layout, your
@@ -1527,7 +1526,7 @@
<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
- has an XML-like notation, starting with an opening tag, and
+ has an XML-like notation, starting with an opening tag and
ending with a closing tag, with various other configuration
directives in the middle. The purpose of the
<literal>Location</literal> directive is to instruct Apache to
@@ -1552,12 +1551,13 @@
<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
- <literal>SVNParentPath</literal> directive, to indicate that
- common parent directory. For example, if you know you will be
- creating multiple Subversion repositories in a directory
+ disk, you can use an alternative directive
+ —<literal>SVNParentPath</literal>— to indicate
+ that common parent directory. For example, if you know you
+ will be creating multiple Subversion repositories in a
+ directory
<filename>/var/svn</filename> that would be accessed via
- URLs like <uri>http://my.server.com/svn/repos1</uri>,
+ URLs such as <uri>http://my.server.com/svn/repos1</uri>,
<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>
@@ -1584,7 +1584,7 @@
<para>Be sure that when you define your new
<literal>Location</literal>, it doesn't overlap with other
- exported Locations. For example, if your main
+ exported locations. For example, if your main
<literal>DocumentRoot</literal> is exported to
<filename>/www</filename>, do not export a Subversion
repository in <literal><Location /www/repos></literal>.
@@ -1605,9 +1605,10 @@
directories. As part of the sanity checking done by the
Apache modules, the source of the copy is expected to be
located on the same machine as the destination of the copy.
- To satisfy this requirement, you might need to tell mod_dav
- the name you use as the hostname of your server. Generally,
- you can use the <literal>ServerName</literal> directive in
+ To satisfy this requirement, you might need to
+ tell <command>mod_dav</command> the name you use as the
+ hostname of your server. Generally, you can use
+ the <literal>ServerName</literal> directive in
<filename>httpd.conf</filename> to accomplish this.</para>
<screen>
@@ -1625,7 +1626,7 @@
<para>At this stage, you should strongly consider the question
of permissions. If you've been running Apache for some time
now as your regular web server, you probably already have a
- collection of content—web pages, scripts and such.
+ collection of content—web pages, scripts, and such.
These items have already been configured with a set of
permissions that allows them to work with Apache, or more
appropriately, that allows Apache to work with those files.
@@ -1656,7 +1657,8 @@
<title>Authentication Options</title>
<para>At this point, if you configured
- <filename>httpd.conf</filename> to contain something like</para>
+ <filename>httpd.conf</filename> to contain something like the
+ following:</para>
<screen>
<Location /svn>
@@ -1665,26 +1667,26 @@
</Location>
</screen>
- <para>…then your repository is <quote>anonymously</quote>
+ <para>then your repository is <quote>anonymously</quote>
accessible to the world. Until you configure some
authentication and authorization policies, the Subversion
- repositories you make available via the
+ repositories that you make available via the
<literal>Location</literal> directive will be generally
- accessible to everyone. In other words,</para>
+ accessible to everyone. In other words:</para>
<itemizedlist>
<listitem>
- <para>anyone can use their Subversion client to check out a
+ <para>Anyone can use a Subversion client to check out a
working copy of a repository URL (or any of its
- subdirectories),</para>
+ subdirectories).</para>
</listitem>
<listitem>
- <para>anyone can interactively browse the repository's
- latest revision simply by pointing their web browser to
- the repository URL, and</para>
+ <para>Anyone can interactively browse the repository's
+ latest revision simply by pointing a web browser to
+ the repository URL.</para>
</listitem>
<listitem>
- <para>anyone can commit to the repository.</para>
+ <para>Anyone can commit to the repository.</para>
</listitem>
</itemizedlist>
@@ -1697,7 +1699,7 @@
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.serverconfig.httpd.authn.basic">
- <title>Setting Up HTTP Authentication</title>
+ <title>Setting up HTTP authentication</title>
<para>The easiest way to authenticate a client is via the
HTTP Basic authentication mechanism, which simply uses a
@@ -1706,7 +1708,7 @@
utility for managing the list of acceptable usernames and
passwords. Let's grant commit access to
Sally and Harry. First, we need to add them to the password
- file.</para>
+ file:</para>
<screen>
$ ### First time: use -c to create the file
@@ -1752,17 +1754,16 @@
</screen>
<para>This <literal><Location></literal> block is not
- yet complete, and will not do anything useful. It's merely
- telling Apache that whenever authorization is required,
- Apache should harvest a username and password from the
- Subversion client. What's missing here, however, are
+ yet complete, and it will not do anything useful. It's
+ merely telling Apache that whenever authorization is
+ required, Apache should harvest a username and password from
+ the Subversion client. What's missing here, however, are
directives that tell Apache <emphasis>which</emphasis> sorts
of client requests require authorization. Wherever
- authorization is required, Apache will demand
- authentication as well. The simplest thing to do is protect
- all requests. Adding <literal>Require valid-user</literal>
- tells Apache that all requests require an authenticated
- user:</para>
+ authorization is required, Apache will demand authentication
+ as well. The simplest thing to do is protect all requests.
+ Adding <literal>Require valid-user</literal> tells Apache
+ that all requests require an authenticated user:</para>
<screen>
<Location /svn>
@@ -1784,10 +1785,10 @@
very nearly plain-text over the network, and thus are
extremely insecure.</para>
- <para>Another option is to not use Basic authentication
- but <quote>Digest</quote> authentication instead. Digest
- authentication allows the server to verify the client's
- identity <emphasis>without</emphasis> passing the plaintext
+ <para>Another option is to not use Basic authentication but to
+ use Digest authentication instead. Digest authentication
+ allows the server to verify the client's
+ identity <emphasis>without</emphasis> passing the plain-text
password over the network. Assuming that the client and
server both know the user's password, they can verify that
the password is the same by using it to apply a hashing
@@ -1821,7 +1822,7 @@
configure Apache to use a self-signed server certificate.
<footnote>
<para>While self-signed server certificates are still
- vulnerable to a <quote>man in the middle</quote> attack,
+ vulnerable to a <quote>man-in-the-middle</quote> attack,
such an attack is much more difficult for a casual
observer to pull off, compared to sniffing unprotected
passwords.</para>
@@ -1834,7 +1835,7 @@
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.serverconfig.httpd.authn.sslcerts">
- <title>SSL Certificate Management</title>
+ <title>SSL certificate management</title>
<para>Businesses that need to expose their repositories for access
outside the company firewall should be conscious of the
@@ -1853,7 +1854,7 @@
further communication is encrypted via a session key.</para>
<para>It's beyond the scope of this book to describe how to
- generate client and server certificates, and how to
+ generate client and server certificates and how to
configure Apache to use them. Many other books, including
Apache's own documentation, describe this task. But what
<emphasis>can</emphasis> be covered here is how to manage
@@ -1865,8 +1866,8 @@
information:</para>
<itemizedlist>
- <listitem><para>a server certificate</para></listitem>
- <listitem><para>a demand for a client certificate</para></listitem>
+ <listitem><para>A server certificate</para></listitem>
+ <listitem><para>A demand for a client certificate</para></listitem>
</itemizedlist>
<para>If the client receives a server certificate, it needs to
@@ -1899,14 +1900,14 @@
same question you've probably seen coming from your web
browser (which is just another HTTP client like Subversion).
If you choose the (p)ermanent option, the server certificate
- will be cached in your private run-time
+ will be cached in your private runtime
<filename>auth/</filename> area in just the same way your
username and password are cached (see <xref
linkend="svn.serverconfig.netmodel.credcache"/>). If cached,
Subversion will automatically trust this certificate
in future negotiations.</para>
- <para>Your run-time <filename>servers</filename> file also gives
+ <para>Your runtime <filename>servers</filename> file also gives
you the ability to make your Subversion client automatically
trust specific CAs, either globally or on a per-host basis.
Simply set the <literal>ssl-authority-files</literal>
@@ -1918,7 +1919,7 @@
ssl-authority-files = /path/to/CAcert1.pem;/path/to/CAcert2.pem
</screen>
- <para>Many OpenSSL installations also have a pre-defined set
+ <para>Many OpenSSL installations also have a predefined set
of <quote>default</quote> CAs that are nearly universally
trusted. To make the Subversion client automatically trust
these standard authorities, set the
@@ -1933,7 +1934,7 @@
Apache trusts. A client certificate is usually stored on
disk in encrypted format, protected by a local password.
When Subversion receives this challenge, it will ask you for
- both a path to the certificate and the password which
+ both a path to the certificate and for the password that
protects it:</para>
<screen>
@@ -1996,19 +1997,19 @@
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.serverconfig.httpd.authz.blanket">
- <title>Blanket Access Control</title>
+ <title>Blanket access control</title>
<para>The simplest form of access control is to authorize
- certain users for either read-only access to a repository,
- or read/write access to a repository.</para>
+ certain users for either read-only access to a repository or
+ read/write access to a repository.</para>
<para>You can restrict access on all repository operations by
adding the <literal>Require valid-user</literal> directive
to your <literal><Location></literal> block. Using
our previous example, this would mean that only clients that
claimed to be either <literal>harry</literal> or
- <literal>sally</literal>, and provided the correct
- password for their respective username, would be allowed to
+ <literal>sally</literal> and that provided the correct
+ password for their respective username would be allowed to
do anything with the Subversion repository:</para>
<screen>
@@ -2029,7 +2030,7 @@
<para>Sometimes you don't need to run such a tight ship. For
example, Subversion's own source code repository at
<ulink url="http://svn.collab.net/repos/svn"/> allows anyone
- in the world to perform read-only repository tasks (like
+ in the world to perform read-only repository tasks (such as
checking out working copies and browsing the repository with
a web browser), but restricts all write operations to
authenticated users. To do this type of selective
@@ -2083,7 +2084,7 @@
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.serverconfig.httpd.authz.perdir">
- <title>Per-Directory Access Control</title>
+ <title>Per-directory access control</title>
<para>It's possible to set up finer-grained permissions using
a second Apache httpd module,
More information about the svnbook-dev
mailing list