[svnbook commit] r3044 - trunk/src/en/book
sussman
noreply at red-bean.com
Fri May 2 15:59:39 CDT 2008
Author: sussman
Date: Fri May 2 15:59:38 2008
New Revision: 3044
Log:
* ch06-server-configuration.xml: more copyedits. more to come.
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 15:59:38 2008
@@ -911,18 +911,18 @@
options available to you.</para>
<sidebar>
- <title>What is SASL?</title>
+ <title>What Is SASL?</title>
<para>The Cyrus Simple Authentication and Security Layer is
- open-source software written by Carnegie Mellon University.
+ open source software written by Carnegie Mellon University.
It adds generic authentication and encryption capabilities
to any network protocol, and as of Subversion 1.5 and later,
both the <command>svnserve</command> server
and <command>svn</command> client know how to make use of
this library. It may or may not be available to you: if
you're building Subversion yourself, you'll need to have at
- least version 2.1 of SASL installed on your system and
+ least version 2.1 of SASL installed on your system, and
you'll need to make sure that it's detected during
- Subversion's build process. If you're using a pre-built
+ Subversion's build process. If you're using a prebuilt
Subversion binary package, you'll have to check with the
package maintainer as to whether SASL support was compiled
in. SASL comes with a number of pluggable modules that
@@ -937,22 +937,22 @@
<ulink url="http://asg.web.cmu.edu/sasl/sasl-library.html"/>.</para>
</sidebar>
- <para>Normally, when a subversion client connects
- to <command>svnserve</command>, the server sends a greeting
- which advertises a list of capabilities it supports, and the
+ <para>Normally, when a subversion client connects to
+ <command>svnserve</command>, the server sends a greeting that
+ advertises a list of the capabilities it supports, and the
client responds with a similar list of capabilities. If the
server is configured to require authentication, it then sends
- a challenge which lists the authentication mechanisms
+ a challenge that lists the authentication mechanisms
available; the client responds by choosing one of the
mechanisms, and then authentication is carried out in some
number of roundtrip messages. Even when SASL capabilities
aren't present, the client and server inherently know how to
- use the CRAM-MD5 and ANONYMOUS mechanisms (see
- <xref linkend="svn.serverconfig.svnserve.auth"/>). If server
- and client were linked against SASL, then a number of other
- authentication mechanisms may also be available. However,
- you'll need to explicitly configure SASL on the server-side to
- advertise them.</para>
+ use the CRAM-MD5 and ANONYMOUS mechanisms (see the earlier
+ section <xref linkend="svn.serverconfig.svnserve.auth"/>). If
+ server and client were linked against SASL, then a number of
+ other authentication mechanisms may also be available.
+ However, you'll need to explicitly configure SASL on the
+ server side to advertise them.</para>
<sect3 id="svn.serverconfig.svnserve.sasl.authn">
<title>Authenticating with SASL</title>
@@ -963,15 +963,15 @@
repository's <filename>svnserve.conf</filename> file, with
this key-value pair:</para>
- <screen>
+ <programlisting>
use-sasl = true
-</screen>
+</programlisting>
<para>Second, create a file
called <filename>subversion.conf</filename> in a place where
the SASL library can find it—typically in the
- directory where SASL plugins are located. You'll have to
- locate the plugin directory on your particular system, such
+ directory where SASL plug-ins are located. You'll have to
+ locate the plug-in directory on your particular system, such
as <filename>/usr/lib/sasl2/</filename>
or <filename>/etc/sasl2/</filename>. (Note that this
is <emphasis>not</emphasis>
@@ -979,29 +979,29 @@
within a repository!)</para>
<para>On a Windows server, you'll have to also edit the
- registry (using a tool like <command>regedit</command>) to
- tell SASL where to find things. Create a registry key
+ registry (using a tool such as <command>regedit</command>)
+ to tell SASL where to find things. Create a registry key
named <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\Carnegie
Mellon\Project Cyrus\SASL Library]</literal>, and place two
keys inside it: a key called <literal>SearchPath</literal>
- (whose value is a path containing the
- SASL <filename>.dll</filename> plugins), and a key
- called <literal>ConfFile</literal> (whose value is a path
+ (whose value is a path containing the SASL
+ <filename>.dll</filename> plug-ins), and a key called
+ <literal>ConfFile</literal> (whose value is a path
containing the <filename>subversion.conf</filename>
- file.)</para>
+ file).</para>
<para>Because SASL provides so many different kinds of
authentication mechanisms, it would be foolish (and far
beyond the scope of this book) to try and describe every
possible server-side configuration. Instead, we recommend
- that you read the documentation supplied in
- the <filename>doc/</filename> subdirectory of the SASL
- source code. It goes into great detail about each mechanism
- and how to configure the server appropriately for each. For
- the purposes of this discussion, we'll just demonstrate a
- simple example of configuring the DIGEST-MD5 mechanism. For
+ that you read the documentation supplied in the
+ <filename>doc/</filename> subdirectory of the SASL source
+ code. It goes into great detail about every mechanism and
+ how to configure the server appropriately for each. For the
+ purposes of this discussion, we'll just demonstrate a simple
+ example of configuring the DIGEST-MD5 mechanism. For
example, if your <filename>subversion.conf</filename>
- contains:</para>
+ contains the following:</para>
<screen>
pwcheck_method: auxprop
@@ -1009,13 +1009,13 @@
mech_list: DIGEST-MD5
</screen>
- <para>...then you've told SASL to advertise the DIGEST-MD5
- mechanism to clients, and to check user passwords against a
- private password database (typically stored
- in <filename>/etc/sasldb2</filename>). A system
- administrator can then use
- the <command>saslpasswd2</command> program to add or modify
- usernames and passwords in the database:</para>
+ <para>then you've told SASL to advertise the DIGEST-MD5
+ mechanism to clients and to check user passwords against a
+ private password database (typically stored in
+ <filename>/etc/sasldb2</filename>). A system administrator
+ can then use the <command>saslpasswd2</command> program to
+ add or modify usernames and passwords in the
+ database:</para>
<screen>
$ saslpasswd2 -c -u realm username
@@ -1031,16 +1031,17 @@
standard SASL password database, make sure that
the <command>svnserve</command> program has read access to
the file (and possibly write access as well, if you're using
- a mechanism such as OTP.)</para>
+ a mechanism such as OTP).</para>
<para>This is just one simple way of configuring SASL. Many
- other authentication mechanisms available, and passwords can
- be stored in other places such as in LDAP or a SQL database.
- Consult the full SASL documentation for details.</para>
+ other authentication mechanisms are available, and passwords
+ can be stored in other places such as in LDAP or a SQL
+ database. Consult the full SASL documentation for
+ details.</para>
<para>Remember that if you configure your server to only allow
- certain SASL authentication mechanisms, this can also have
- the effect of forcing all of connecting clients to have SASL
+ certain SASL authentication mechanisms, this can have the
+ effect of forcing all of connecting clients to have SASL
support as well. Any Subversion client built without SASL
support (which includes all pre-1.5 clients) will be unable
to authenticate. On the one hand, this sort of restriction
@@ -1053,15 +1054,15 @@
</sect3>
<sect3 id="svn.serverconfig.svnserve.sasl.encryption">
- <title>SASL Encryption</title>
+ <title>SASL encryption</title>
- <para>SASL is also able to perform data-encryption if a
+ <para>SASL is also able to perform data encryption if a
particular mechanism supports it. The built-in CRAM-MD5
mechanism doesn't support encryption, but DIGEST-MD5 does,
- and mechanisms like SRP actually require use of the OpenSSL
- library . To enable or disable different levels of
- encryption, you can set two values in your
- repository's <filename>svnserve.conf</filename> file:</para>
+ and mechanisms such as SRP actually require use of the
+ OpenSSL library. To enable or disable different levels of
+ encryption, you can set two values in your repository's
+ <filename>svnserve.conf</filename> file:</para>
<screen>
[sasl]
@@ -1070,17 +1071,17 @@
max-encryption = 256
</screen>
- <para>The <literal>min-encryption</literal>
- and <literal>max-encryption</literal> variables control the
+ <para>The <literal>min-encryption</literal> and
+ <literal>max-encryption</literal> variables control the
level of encryption demanded by the server. To disable
encryption completely, set both values to 0. To enable
- simple checksumming of data (i.e. prevent tampering and
+ simple checksumming of data (i.e., prevent tampering and
guarantee data integrity without encryption), set both
values to 1. If you wish to allow—but not
require—encryption, set the minimum value to 0, and
the maximum value to some bit-length. To require encryption
unconditionally, set both values to numbers greater than 1.
- In our example above, we require clients to do at least
+ In our previous example, we require clients to do at least
128-bit encryption, but no more than 256-bit
encryption.</para>
@@ -1124,13 +1125,13 @@
<command>svnserve</command> process on the remote machine
running as the user <literal>harry</literal>. The
<command>svnserve</command> command is being invoked in tunnel
- mode (<option>-t</option>) and its network protocol is being
+ mode (<option>-t</option>), and its network protocol is being
<quote>tunneled</quote> over the encrypted connection by
- <command>ssh</command>, the tunnel-agent.
+ <command>ssh</command>, the tunnel agent.
<command>svnserve</command> is aware that it's running as the
user <literal>harry</literal>, and if the client performs a
- commit, the authenticated username will be used as the
- author of the new revision.</para>
+ commit, the authenticated username will be used as the author
+ of the new revision.</para>
<para>The important thing to understand here is that the
Subversion client is <emphasis>not</emphasis> connecting to a
@@ -1145,7 +1146,7 @@
repository, remember that it's the <command>ssh</command>
program prompting for authentication, and
<emphasis>not</emphasis> the <command>svn</command> client
- program. That means there's no automatic password caching
+ program. That means there's no automatic password-caching
going on (see <xref linkend="svn.serverconfig.netmodel.credcache"/>). The
Subversion client often makes multiple connections to the
repository, though users don't normally notice this due to the
@@ -1153,7 +1154,7 @@
<literal>svn+ssh://</literal> URLs, however, users may be
annoyed by <command>ssh</command> repeatedly asking for a
password for every outbound connection. The solution is to
- use a separate SSH password-caching tool like
+ use a separate SSH password-caching tool such as
<command>ssh-agent</command> on a Unix-like system, or
<command>pageant</command> on Windows.</para>
@@ -1164,30 +1165,25 @@
<literal>file://</literal> URL. If multiple system users are
going to be accessing the repository directly, you may want to
place them into a common group, and you'll need to be careful
- about umasks. (Be sure to read <xref
- linkend="svn.serverconfig.multimethod"/>.) But even in the case of
- tunneling, the <filename>svnserve.conf</filename> file can
- still be used to block access, by simply setting
- <literal>auth-access = read</literal> or <literal>auth-access
- = none</literal>.
- <footnote>
- <para>Note that using any sort
- of <command>svnserve</command>-enforced access control at
- all is a bit pointless; the user already has direct access to
- the repository database.</para>
- </footnote>
- </para>
+ about umasks (be sure to read <xref
+ linkend="svn.serverconfig.multimethod"/> later in this
+ chapter). But even in the case of tunneling, the
+ <filename>svnserve.conf</filename> file can still be used to
+ block access, by simply setting <literal>auth-access =
+ read</literal> or <literal>auth-access = none</literal>.
+ <footnote> <para>Note that using any sort of
+ <command>svnserve</command>-enforced access control at all is
+ a bit pointless; the user already has direct access to the
+ repository database.</para> </footnote> </para>
<para>You'd think that the story of SSH tunneling would end
here, but it doesn't. Subversion allows you to create custom
- tunnel behaviors in your run-time <filename>config</filename>
- file (see <xref linkend="svn.advanced.confarea"/>). For example,
- suppose you want to use RSH instead of SSH.
- <footnote>
- <para>We don't actually recommend this, since RSH is notably
- less secure than SSH.</para>
- </footnote>
- In the <literal>[tunnels]</literal> section of your
+ tunnel behaviors in your runtime <filename>config</filename>
+ file (see <xref linkend="svn.advanced.confarea"/>.) For
+ example, suppose you want to use RSH instead of SSH.
+ <footnote> <para>We don't actually recommend this, since RSH
+ is notably less secure than SSH.</para> </footnote> In the
+ <literal>[tunnels]</literal> section of your
<filename>config</filename> file, simply define it like
this:</para>
@@ -1202,7 +1198,7 @@
URL scheme, the Subversion client will actually be running the
command <command>rsh host svnserve -t</command> behind the
scenes. If you include a username in the URL (for example,
- <literal>svn+rsh://username@host/path</literal>) the client
+ <literal>svn+rsh://username@host/path</literal>), the client
will also include that in its command (<command>rsh
username at host svnserve -t</command>). But you can define new
tunneling schemes to be much more clever than that:</para>
@@ -1220,7 +1216,7 @@
<literal>svn+joessh://</literal> URL would invoke the
particular SSH binary with <option>-p 29934</option> as
arguments—useful if you want the tunnel program to
- connect to a non-standard port.</para>
+ connect to a nonstandard port.</para>
<para>Second, it shows how to define a custom environment
variable that can override the name of the tunneling program.
More information about the svnbook-dev
mailing list