[svnbook commit] r3028 - trunk/src/en/book

sussman noreply at red-bean.com
Thu Apr 3 10:01:55 CDT 2008


Author: sussman
Date: Thu Apr  3 10:01:54 2008
New Revision: 3028

Log:
* ch06-server-configuriation.xml:  25% done with copyedits.  Oy, this is gonna kill me.

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	Thu Apr  3 10:01:54 2008
@@ -11,10 +11,10 @@
   <para>This chapter 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,
-    discussing the configuration and use of each.  After reading
-    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>
+    discussing the configuration and use of each.  After reading this
+    section, you should be able to decide which networking setup is
+    right for your needs, as well as understand how to enable such a
+    setup on your host computer.</para>
 
 
   <!-- ================================================================= -->
@@ -32,15 +32,15 @@
       an infinite number of network implementations.  In practice,
       there are only two servers at the time of this writing.</para>
 
-    <para>Apache is an extremely popular webserver; using the
+    <para>Apache is an extremely popular web server; using the
       <command>mod_dav_svn</command> module, Apache can access a
       repository and make it available to clients via the
       WebDAV/DeltaV protocol, which is an extension of HTTP.  Because
-      Apache is an extremely extensible web server, it provides a
-      number of features <quote>for free</quote>, such as encrypted
-      SSL communication, logging, integration with a number of
-      third-party authentication systems, and limited built-in web
-      browsing of repositories.</para>
+      Apache is an extremely extensible server, it provides a number
+      of features <quote>for free,</quote> such as encrypted SSL
+      communication, logging, integration with a number of third-party
+      authentication systems, and limited built-in web browsing of
+      repositories.</para>
 
     <para>In the other corner is <command>svnserve</command>: a small,
       lightweight server program that speaks a custom protocol with
@@ -49,7 +49,7 @@
       significantly faster network operations—but at the cost of
       some features as well.  While it can use SASL to provide a
       variety of authentication and encryption options, it has no
-      logging or built-in web-browsing.  It is, however, extremely
+      logging or built-in web browsing.  It is, however, extremely
       easy to set up and is often the best option for small teams just
       starting out with Subversion.</para>
 
@@ -69,11 +69,11 @@
       has no meaning, since each user is accessing the repository
       database files directly.</para>
 
-    <para>Here's a quick summary of the three typical server
-      deployments.</para>
+    <para><xref linkend="svn.serverconfig.overview.tbl-1"/> provides a
+      quick summary of the three typical server deployments.</para>
 
     <table id="svn.serverconfig.overview.tbl-1">
-      <title>Comparison of Subversion Server Options</title>
+      <title>Comparison of subversion server options</title>
       <tgroup cols="4">
         <thead>
           <row>
@@ -87,82 +87,82 @@
           <row>
             <entry>Authentication options</entry>
             <entry>HTTP(S) basic auth, X.509 certificates, LDAP, NTLM, or
-              any other mechanism available to Apache httpd</entry>
+              any other mechanism available to Apache httpd.</entry>
             <entry>CRAM-MD5 by default;  LDAP, NTLM, or any other mechanism
-              available to SASL</entry>
+              available to SASL.</entry>
             <entry>SSH</entry>
           </row>
 
           <row>
             <entry>User account options</entry>
-            <entry>private 'users' file, or other mechanisms
+            <entry>Private 'users' file, or other mechanisms
             available to Apache httpd (LDAP, SQL, etc.)</entry>
-            <entry>private 'users' file, or other mechanisms available
-              to SASL (LDAP, SQL, etc.)</entry>
-            <entry>system accounts</entry>
+            <entry>Private 'users' file, or other mechanisms available
+              to SASL (LDAP, SQL, etc.).</entry>
+            <entry>System accounts.</entry>
           </row>
 
           <row>
             <entry>Authorization options</entry>
-            <entry>read/write access can be granted over whole
-              repository, or specified per-path.</entry>
-            <entry>read/write access can be granted over whole
-              repository, or specified per-path.</entry>
-            <entry>read/write access only grantable over whole
-              repository</entry>
+            <entry>Read/write access can be granted over the whole
+              repository, or specified per path.</entry>
+            <entry>Read/write access can be granted over the whole
+              repository, or specified per path.</entry>
+            <entry>Read/write access only grantable over the whole
+              repository.</entry>
           </row>
 
           <row>
             <entry>Encryption</entry>
-            <entry>via optional SSL</entry>
-            <entry>via optional SASL features</entry>
-            <entry>SSH tunneled</entry>
+            <entry>Available via optional SSL.</entry>
+            <entry>Available via optional SASL features.</entry>
+            <entry>Inherent in SSH connection.</entry>
           </row>
 
           <row>
             <entry>Logging</entry>
-            <entry>full Apache logs of each HTTP request, with
+            <entry>Full Apache logs of each HTTP request, with
             optional <quote>high-level</quote> logging of general
-            client operations</entry>
-            <entry>no logging</entry>
-            <entry>no logging</entry>
+            client operations.</entry>
+            <entry>No logging.</entry>
+            <entry>No logging.</entry>
           </row>
 
           <row>
             <entry>Interoperability</entry>
-            <entry>partially usable by other WebDAV clients</entry>
-            <entry>only talks to svn clients</entry>
-            <entry>only talks to svn clients</entry>
+            <entry>Accessible by other WebDAV clients.</entry>
+            <entry>Talks only to svn clients.</entry>
+            <entry>Talks only to svn clients.</entry>
           </row>
 
           <row>
             <entry>Web viewing</entry>
-            <entry>limited built-in support, or via 3rd-party tools
-              such as ViewVC</entry>
-            <entry>only via 3rd-party tools such as ViewVC</entry>
-            <entry>only via 3rd-party tools such as ViewVC</entry>
+            <entry>Limited built-in support, or via third-party tools
+              such as ViewVC.</entry>
+            <entry>Only via third-party tools such as ViewVC.</entry>
+            <entry>Only via third-party tools such as ViewVC.</entry>
           </row>
 
           <row>
             <entry>Master-slave server replication</entry>
-            <entry>Transparent write-proxying available from slave to master</entry>
-            <entry>Can only create read-only slave servers</entry>
-            <entry>Can only create read-only slave servers</entry>
+            <entry>Transparent write-proxying available from slave to master.</entry>
+            <entry>Can only create read-only slave servers.</entry>
+            <entry>Can only create read-only slave servers.</entry>
           </row>
 
 
           <row>
             <entry>Speed</entry>
-            <entry>somewhat slower</entry>
-            <entry>somewhat faster</entry>
-            <entry>somewhat faster</entry>
+            <entry>Somewhat slower.</entry>
+            <entry>Somewhat faster.</entry>
+            <entry>Somewhat faster.</entry>
           </row>
 
           <row>
             <entry>Initial setup</entry>
-            <entry>somewhat complex</entry>
-            <entry>extremely simple</entry>
-            <entry>moderately simple </entry>
+            <entry>Somewhat complex.</entry>
+            <entry>Extremely simple.</entry>
+            <entry>Moderately simple.</entry>
           </row>
 
         </tbody>
@@ -220,7 +220,7 @@
 
             <listitem><para>By default, only one authentication method
                 is available, the network protocol is not encrypted,
-                and the server stores cleartext passwords.  (All these
+                and the server stores clear text passwords.  (All these
                 things can be changed by configuring SASL, but it's a
                 bit more work to do.)</para></listitem>
 
@@ -252,7 +252,7 @@
             <listitem><para>Network protocol is stateful and
                 noticeably faster than WebDAV.</para></listitem>
 
-            <listitem><para>You can take advantage of existing ssh
+            <listitem><para>You can take advantage of existing SSH
                 accounts and user infrastructure.</para></listitem>
 
             <listitem><para>All network traffic is
@@ -274,7 +274,7 @@
                 errors.</para></listitem>
 
             <listitem><para>Requires users to be in same system group, or
-                use a shared ssh key.</para></listitem>
+                use a shared SSH key.</para></listitem>
 
             <listitem><para>If used improperly, can lead to file permissions
                 problems.</para></listitem>
@@ -316,9 +316,9 @@
                   browser.</para></listitem>
 
               <listitem><para>Repository can be mounted as a network
-                  drive for transparent version control. (See
+                  drive for transparent version control (see
                   <xref
-                  linkend="svn.webdav.autoversioning"/>.)</para></listitem>
+                  linkend="svn.webdav.autoversioning"/>).</para></listitem>
 
             </itemizedlist>
           </listitem>
@@ -329,8 +329,9 @@
           <listitem>
             <itemizedlist>
 
-            <listitem><para>Noticeably slower than svnserve, because
-                HTTP is a stateless protocol and requires more
+            <listitem><para>Noticeably slower than
+                <command>svnserve</command>, because HTTP is a
+                stateless protocol and requires more network
                 turnarounds.</para></listitem>
 
             <listitem><para>Initial setup can be complex.</para></listitem>
@@ -366,10 +367,10 @@
             repository data will be transmitted in the clear over the
             network.  If your deployment is entirely within your
             company's LAN or VPN, this isn't an issue.  If the
-            repository is exposed to the wide-open internet, then you
+            repository is exposed to the wide-open Internet, then you
             might want to make sure that either the repository's
-            contents aren't sensitive (e.g. it contains only
-            open-source code), or that you go the extra mile in
+            contents aren't sensitive (e.g., it contains only
+            open source code), or that you go the extra mile in
             configuring SASL to encrypt network communications.</para>
         </listitem>
 
@@ -385,53 +386,50 @@
 
         <listitem>
            <para>If you've decided to use either Apache or stock
-             <command>svnserve</command>, create a
-             single <literal>svn</literal> user on your system and run
-             the server process as that user.  Be sure to make the
-             repository directory wholly owned by
-             the <literal>svn</literal> user as well.  From a security
+             <command>svnserve</command>, create a single
+             <command>svn</command> user on your system and run the
+             server process as that user.  Be sure to make the
+             repository directory wholly owned by the
+             <command>svn</command> user as well.  From a security
              point of view, this keeps the repository data nicely
              siloed and protected by operating system filesystem
              permissions, changeable by only the Subversion server
-             process itself.</para>
-        </listitem>
+             process itself.</para> </listitem>
 
         <listitem>
           <para>If you have an existing infrastructure heavily based
             on SSH accounts, and if your users already have system
             accounts on your server machine, then it makes sense to
-            deploy an svnserve-over-ssh solution.  Otherwise, we don't
-            widely recommend this option to the public.  It's
-            generally considered safer to have your users access the
-            repository via (imaginary) accounts managed
-            by <command>svnserve</command> or Apache, rather than by
-            full-blown system accounts.  If your deep desire for
-            encrypted communication still draws you to this option, we
-            recommend using Apache with SSL
-            or <command>svnserve</command> with SASL encryption
-            instead.</para>
-        </listitem>
+            deploy an <command>svnserve</command>-over-SSH solution.
+            Otherwise, we don't widely recommend this option to the
+            public.  It's generally considered safer to have your
+            users access the repository via (imaginary) accounts
+            managed by <command>svnserve</command> or Apache, rather
+            than by full-blown system accounts.  If your deep desire
+            for encrypted communication still draws you to this
+            option, we recommend using Apache with SSL or
+            <command>svnserve</command> with SASL encryption
+            instead.</para> </listitem>
 
         <listitem>
           <para>Do <emphasis>not</emphasis> be seduced by the simple
             idea of having all of your users access a repository
-            directly via <literal>file://</literal> URLs.  Even if
-            the repository is readily available to everyone via
-            network share, this is a bad idea.  It removes any layers
-            of protection between the users and the repository: users
-            can accidentally (or intentionally) corrupt the repository
+            directly via <literal>file://</literal> URLs.  Even if the
+            repository is readily available to everyone via network
+            share, this is a bad idea.  It removes any layers of
+            protection between the users and the repository: users can
+            accidentally (or intentionally) corrupt the repository
             database, it becomes hard to take the repository offline
             for inspection or upgrade, and it can lead to a mess of
-            file-permissions problems (see
-            <xref linkend="svn.serverconfig.multimethod"/>.)  Note
-            that this is also one of the reasons we warn against
-            accessing repositories via <literal>svn+ssh://</literal>
+            file-permissions problems (see <xref
+            linkend="svn.serverconfig.multimethod"/>).  Note that this
+            is also one of the reasons we warn against accessing
+            repositories via <literal>svn+ssh://</literal>
             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>
-        </listitem>
-      </itemizedlist>
+            the same as local users accessing via
+            <literal>file://</literal>, and it can entail all the same
+            problems if the administrator isn't careful.</para>
+            </listitem> </itemizedlist>
 
     </sect2>
 
@@ -442,7 +440,7 @@
   <!-- ================================================================= -->
   <sect1 id="svn.serverconfig.svnserve">
 
-    <title>svnserve, a custom server</title>
+    <title>svnserve, a Custom Server</title>
 
     <para>The <command>svnserve</command> program is a lightweight
       server, capable of speaking to clients over TCP/IP using a
@@ -477,7 +475,7 @@
 
       <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
       <sect3 id="svn.serverconfig.svnserve.invoking.daemon">
-        <title><command>svnserve</command> as Daemon</title>
+        <title><command>svnserve</command> as daemon</title>
 
         <para>The easiest option is to run <command>svnserve</command>
           as a standalone <quote>daemon</quote> process.  Use the
@@ -494,8 +492,8 @@
           exact port and hostname to <quote>bind</quote> to.</para>
 
       <para>Once we successfully start <command>svnserve</command> as
-        above, it makes every repository on your system available to
-        the network.  A client needs to specify an
+        explained previously, it makes every repository on your system
+        available to the network.  A client needs to specify an
         <emphasis>absolute</emphasis> path in the repository URL.  For
         example, if a repository is located at
         <filename>/var/svn/project1</filename>, then a client would
@@ -530,12 +528,13 @@
 
         <para>If you want <command>inetd</command> to launch the
           process, then you need to pass the <option>-i</option>
-          (<option>--inetd</option>) option.  In the example, we've shown the
-          output from running <literal>svnserve -i</literal> at the
-          command line, but note that isn't how you actually start the
-          daemon; see the paragraphs following the example for how to
-          configure <command>inetd</command> to
-          start <command>svnserve</command>.</para>
+          (<option>--inetd</option>) option.  In the following
+          example, we've shown the output from running
+          <literal>svnserve -i</literal> at the command line, but note
+          that isn't how you actually start the daemon; see the
+          paragraphs following the example for how to configure
+          <command>inetd</command> to start
+          <command>svnserve</command>.</para>
 
       <screen>
 $ svnserve -i
@@ -547,9 +546,9 @@
         Subversion client via <emphasis>stdin</emphasis> and
         <emphasis>stdout</emphasis> using a custom protocol.  This is
         the standard behavior for a program being run via
-        <command>inetd</command>.  The IANA has reserved port 3690
-        for the Subversion protocol, so on a Unix-like system you can
-        add lines to <filename>/etc/services</filename> like these (if
+        <command>inetd</command>.  The IANA has reserved port 3690 for
+        the Subversion protocol, so on a Unix-like system you can add
+        lines to <filename>/etc/services</filename> such as these (if
         they don't already exist):</para>
 
       <screen>
@@ -557,7 +556,7 @@
 svn           3690/udp   # Subversion
 </screen>
 
-      <para>And if your system is using a classic Unix-like
+      <para>If your system is using a classic Unix-like
         <command>inetd</command> daemon, you can add this line to
         <filename>/etc/inetd.conf</filename>:</para>
 
@@ -565,9 +564,9 @@
 svn stream tcp nowait svnowner /usr/bin/svnserve svnserve -i
 </screen>
 
-      <para>Make sure <quote>svnowner</quote> is a user which has
-        appropriate permissions to access your repositories.  Now, when
-        a client connection comes into your server on port 3690,
+      <para>Make sure <quote>svnowner</quote> is a user that has
+        appropriate permissions to access your repositories.  Now,
+        when a client connection comes into your server on port 3690,
         <command>inetd</command> will spawn an
         <command>svnserve</command> process to service it.  Of course,
         you may also want to add <option>-r</option> to the
@@ -578,12 +577,12 @@
 
       <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
       <sect3 id="svn.serverconfig.svnserve.invoking.tunnel">
-        <title><command>svnserve</command> over a Tunnel</title>
+        <title><command>svnserve</command> over a tunnel</title>
 
         <para>A third way to invoke <command>svnserve</command> is in
-          <quote>tunnel mode</quote>, with the <option>-t</option>
-          option.  This mode assumes that a remote-service program
-          such as <command>RSH</command> or <command>SSH</command> has
+          tunnel mode, using the <option>-t</option> option.  This
+          mode assumes that a remote-service program such as
+          <command>RSH</command> or <command>SSH</command> has
           successfully authenticated a user and is now invoking a
           private <command>svnserve</command> process <emphasis>as
           that user</emphasis>.  (Note that you, the user, will
@@ -592,7 +591,7 @@
           the command line; instead, the <command>SSH</command> daemon
           does so for you.)  The <command>svnserve</command> program
           behaves normally (communicating via
-          <emphasis>stdin</emphasis> and <emphasis>stdout</emphasis>),
+          <emphasis>stdin</emphasis> and <emphasis>stdout</emphasis>)
           and assumes that the traffic is being automatically
           redirected over some sort of tunnel back to the client.
           When <command>svnserve</command> is invoked by a tunnel
@@ -601,21 +600,22 @@
           It's essentially the same as a local user accessing the
           repository via <literal>file://</literal> URLs.</para>
 
-        <para>This option is described in much more detail in
-          <xref linkend="svn.serverconfig.svnserve.sshauth"/>.</para>
+        <para>This option is described in much more detail later in
+          this chapter in <xref
+          linkend="svn.serverconfig.svnserve.sshauth"/>.</para>
 
       </sect3>
 
       <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
       <sect3 id="svn.serverconfig.svnserve.invoking.winservice">
-        <title><command>svnserve</command> as Windows Service</title>
+        <title><command>svnserve</command> as Windows service</title>
 
         <para>If your Windows system is a descendant of Windows NT
-          (2000, 2003, XP, Vista), then you can
+          (2000, 2003, XP, or Vista), then you can
           run <command>svnserve</command> as a standard Windows
           service.  This is typically a much nicer experience than
           running it as a standalone daemon with the <option>--daemon
-          (-d)</option> option.  Using daemon-mode requires launching
+          (-d)</option> option.  Using daemon mode requires launching
           a console, typing a command, and then leaving the console
           window running indefinitely.  A Windows service, however,
           runs in the background, can start at boot time
@@ -627,7 +627,7 @@
           command-line tool <command>SC.EXE</command>.  Much like
           the <command>inetd</command> configuration line, you must
           specify an exact invocation of <command>svnserve</command>
-          for Windows to run at start-up time:</para>
+          for Windows to run at startup time:</para>
 
         <screen>
 C:\> sc create svn
@@ -637,31 +637,30 @@
         start= auto
 </screen>
 
-        <para>This defines a new Windows service
-          named <quote>svn</quote>, and which executes a
-          particular <command>svnserve.exe</command> command when
-          started (in this case, rooted
-          at <filename>C:\repos</filename>.)  There are a number of
-          caveats in the prior example, however.</para>
+        <para>This defines a new Windows service named
+          <quote>svn,</quote> which executes a particular
+          <command>svnserve.exe</command> command when started (in
+          this case, rooted at <filename>C:\repos</filename>).  There
+          are a number of caveats in the prior example,
+          however.</para>
 
         <para>First, notice that the <command>svnserve.exe</command>
-          program must always be invoked with
-          the <option>--service</option> option.  Any other options to
+          program must always be invoked with the
+          <option>--service</option> option.  Any other options to
           <command>svnserve</command> must then be specified on the
-          same line, but you cannot add conflicting options such
-          as <option>--daemon
-          (-d)</option>, <option>--tunnel</option>, or <option>--inetd
-          (-i)</option>.  Options such as <option>-r</option>
-          or <option>--listen-port</option> are fine, though.  Second, be
-          careful about spaces when invoking
-          the <command>SC.EXE</command> command: the
-          <literal>key= value</literal> patterns must have no
-          spaces between <literal>key=</literal> and exactly one
-          space before the <literal>value</literal>.  Lastly, be
-          careful about spaces in your command-line to be invoked.  If
-          a directory name contains spaces (or other characters that
-          need escaping), place the entire inner value
-          of <literal>binpath</literal> in double-quotes, by escaping
+          same line, but you cannot add conflicting options such as
+          <option>--daemon (-d)</option>, <option>--tunnel</option>,
+          or <option>--inetd (-i)</option>.  Options such as
+          <option>-r</option> or <option>--listen-port</option> are
+          fine, though.  Second, be careful about spaces when invoking
+          the <command>SC.EXE</command> command: the <literal>key=
+          value</literal> patterns must have no spaces between
+          <literal>key=</literal> and must have exactly one space
+          before the <literal>value</literal>.  Lastly, be careful
+          about spaces in your commandline to be invoked.  If a
+          directory name contains spaces (or other characters that
+          need escaping), place the entire inner value of
+          <literal>binpath</literal> in double-quotes, by escaping
           them:</para>
 
         <screen>
@@ -678,10 +677,10 @@
           you need to surround it with quote marks if it contains
           embedded spaces.</para>
 
-        <para>Once the service is defined, it can stopped, started, or
-          queried using standard GUI tools (the Services
-          administrative control panel), or at the command line as
-          well:</para>
+        <para>Once the service is defined, it can be stopped, started,
+          or queried using standard GUI tools (the Services
+          administrative control panel), or at the command
+          line:</para>
 
         <screen>
 C:\> net stop svn
@@ -701,7 +700,7 @@
 
     <!-- =============================================================== -->
     <sect2 id="svn.serverconfig.svnserve.auth">
-      <title>Built-in authentication and authorization</title>
+      <title>Built-in Authentication and Authorization</title>
 
       <para>When a client connects to an <command>svnserve</command>
         process, the following things happen:</para>
@@ -711,75 +710,77 @@
         repository.</para></listitem>
 
         <listitem><para>The server processes the repository's
-        <filename>conf/svnserve.conf</filename> file, and begins to
+        <filename>conf/svnserve.conf</filename> file and begins to
         enforce any authentication and authorization policies it
         describes.</para></listitem>
 
-        <listitem><para>Depending on the defined policies,</para>
+        <listitem><para>Depending on the defined policies, one of the
+        following may accur:</para>
 
           <itemizedlist>
-            <listitem><para>the client may be allowed to make requests
+            <listitem><para>The client may be allowed to make requests
               anonymously, without ever receiving an authentication
-              challenge, OR</para></listitem>
+              challenge.</para></listitem>
 
-            <listitem><para>the client may be challenged for
-              authentication at any time, OR</para></listitem>
+            <listitem><para>The client may be challenged for
+              authentication at any time.</para></listitem>
 
-            <listitem><para>if operating in <quote>tunnel
-              mode</quote>, the client will declare itself to be
-              already externally authenticated (typically by
-              SSH).</para></listitem>
+            <listitem><para>If operating in tunnel mode, the client
+              will declare itself to be already externally
+              authenticated (typically by SSH).</para></listitem>
           </itemizedlist>
         </listitem>
 
       </itemizedlist>
 
-      <para>The <command>svnserve</command> server, by default, only
-        knows how to send a CRAM-MD5 <footnote><para>See RFC
+      <para>The <command>svnserve</command> server, by default, knows
+        only how to send a CRAM-MD5 <footnote><para>See RFC
         2195.</para></footnote> authentication challenge.  In essence,
         the server sends a small amount of data to the client.  The
         client uses the MD5 hash algorithm to create a fingerprint of
-        the data and password combined, then sends the fingerprint as
-        a response.  The server performs the same computation with the
-        stored password to verify that the result is
-        identical.  <emphasis>At no point does the actual password
-        travel over the network.</emphasis></para>
+        the data and password combined, and then sends the fingerprint
+        as a response.  The server performs the same computation with
+        the stored password to verify that the result is identical.
+        <emphasis>At no point does the actual password travel over the
+        network.</emphasis></para>
 
       <para>If your <command>svnserve</command> server was built with
         SASL, then it not only knows how to send CRAM-MD5 challenges,
         but likely knows a whole host of other authentication
-        mechanisms.  See
-        <xref linkend="svn.serverconfig.svnserve.sasl"/> to configure
-        SASL authentication and encryption.</para>
+        mechanisms.  See <xref
+        linkend="svn.serverconfig.svnserve.sasl"/> later in this
+        chapter to learn how to configure SASL authentication and
+        encryption.</para>
 
       <para>It's also possible, of course, for the client to be
         externally authenticated via a tunnel agent, such as
         <command>SSH</command>.  In that case, the server simply
-        examines the user it's running as, and uses it as the
-        authenticated username.  For more on this, see <xref
+        examines the user it's running as, and uses this name as the
+        authenticated username.  For more on this, see the later
+        section <xref
         linkend="svn.serverconfig.svnserve.sshauth"/>.</para>
 
       <para>As you've already guessed, a repository's
         <filename>svnserve.conf</filename> file is the central
         mechanism for controlling authentication and authorization
         policies.  The file has the same format as other configuration
-        files (see <xref linkend="svn.advanced.confarea"/>): section names
-        are marked by square brackets (<literal>[</literal> and
-        <literal>]</literal>), comments begin with hashes
-        (<literal>#</literal>), and each section contains
-        specific variables that can be set (<literal>variable =
-        value</literal>).  Let's walk through these files and learn how
-        to use them.</para>
+        files (see <xref linkend="svn.advanced.confarea"/> in chapter
+        7): section names are marked by square brackets
+        (<literal>[</literal> and <literal>]</literal>), comments
+        begin with hashes (<literal>#</literal>), and each section
+        contains specific variables that can be set (<literal>variable
+        = value</literal>).  Let's walk through these files and learn
+        how to use them.</para>
 
       <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
       <sect3 id="svn.serverconfig.svnserve.auth.users">
-        <title>Create a 'users' file and realm</title>
+        <title>Create a users file and realm</title>
 
         <para>For now, the <literal>[general]</literal> section of the
           <filename>svnserve.conf</filename> has all the variables you
           need.  Begin by changing the values of those variables:
-          choose a name for a file which will contain your usernames
-          and passwords, and choose an authentication realm:</para>
+          choose a name for a file that will contain your usernames
+          and passwords and choose an authentication realm:</para>
 
         <screen>
 [general]
@@ -790,7 +791,7 @@
         <para>The <literal>realm</literal> is a name that you define.
           It tells clients which sort of <quote>authentication
           namespace</quote> they're connecting to; the Subversion
-          client displays it in the authentication prompt, and uses it
+          client displays it in the authentication prompt and uses it
           as a key (along with the server's hostname and port) for
           caching credentials on disk (see <xref
           linkend="svn.serverconfig.netmodel.credcache"/>).  The
@@ -884,7 +885,7 @@
 </screen>
 
         <para>The syntax of the <filename>authzfile</filename> file is
-          discussed in detail in
+          discussed in detail later in this chapter in
           <xref linkend="svn.serverconfig.pathbasedauthz"/>.  Note
           that the <literal>authz-db</literal> variable isn't mutually
           exclusive with the <literal>anon-access</literal>




More information about the svnbook-dev mailing list