[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