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

sussman noreply at red-bean.com
Sat Jan 27 17:06:22 CST 2007


Author: sussman
Date: Sat Jan 27 17:06:21 2007
New Revision: 2631

Modified:
   trunk/src/en/book/ch-server-configuration.xml

Log:
More major changes to chapter 6.

* src/en/ch-server-configuration.xml:

      - mention OSX keychain intergration
      - more clearly delineate the ways to start svnserve
      - explain how to run svnserve as native Windows Service
      - reorganize 'extras' Apache section into clearer subsection
      - document SVNListParentPath
      - remind users to set svn:mime-type for better browsing
      - document high-level logging feature
      - lots of misc. cleanup & rewording


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	Sat Jan 27 17:06:21 2007
@@ -362,13 +362,14 @@
         <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 either Apache or svnserve as that user.  Be sure to
-             make the repository directory wholly owned by
-             the <literal>svn</literal> user as well.  These keeps the
-             repository data nicely siloed and protected by operating
-             system filesystem permissions, changeable by only the
-             Subverion server process itself.</para>
+             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
+             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>
 
         <listitem>
@@ -376,7 +377,7 @@
             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
-            recommend this option to the general public.  It's
+            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
@@ -393,7 +394,7 @@
             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'
+            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
@@ -491,7 +492,7 @@
         (The runtime area is covered in more detail in <xref
         linkend="svn.advanced.confarea"/>.)  Successful credentials are
         cached on disk, keyed on a combination of hostname, port, and
-        authentication realm.</para>  
+        authentication realm.</para>
 
       <para>When the client receives an authentication challenge, it
         first looks for the appropriate credentials in the user's disk
@@ -507,14 +508,6 @@
       <itemizedlist>
 
         <listitem>
-          <para>The <filename>auth/</filename> caching area is
-            permission-protected so that only the user (owner) can
-            read data from it, not the world at large.  The operating
-            system's own file permissions are protecting the
-            password.</para>
-        </listitem>
-
-        <listitem>
           <para>On Windows 2000 and later, the Subversion client uses
             standard Windows cryptography services to encrypt the
             password on disk.  Because the encryption key is managed
@@ -528,9 +521,25 @@
         </listitem>
 
         <listitem>
-          <para>For the truly paranoid willing to sacrifice all
-            convenience, it's possible to disable credential caching
-            altogether.</para>
+          <para>Similarly, on Mac OS X, the Subversion client stores all
+            repository passwords in the Keychain service, protected by
+            the user's account passsword.</para>
+        </listitem>
+
+        <listitem>
+          <para>For other Unix-like operating systems, no standard
+            such <quote>keychain</quote> services exist.  However,
+            the <filename>auth/</filename> caching area is still
+            permission-protected so that only the user (owner) can
+            read data from it, not the world at large.  The operating
+            system's own file permissions are protecting the
+            password.</para>
+        </listitem>
+
+        <listitem>
+          <para>For the truly paranoid willing to sacrifice
+            convenience, it's always possible to disable credential
+            caching altogether.</para>
         </listitem>
 
       </itemizedlist>
@@ -694,12 +703,76 @@
     <sect2 id="svn.serverconfig.svnserve.invoking">
       <title>Invoking the Server</title>
 
-      <para>There are a few different ways to invoke the
-        <command>svnserve</command> program.  If invoked with no
-        options, you'll see nothing but a help message.  However, if
-        you're planning to have <command>inetd</command> launch the
-        process, then you can pass the <option>-i</option>
-        (<option>--inetd</option>) option:</para>
+      <para>There are a few different ways to run the
+        <command>svnserve</command> program:</para>
+
+      <itemizedlist>
+        <listitem><para>Run <command>svnserve</command> as a
+            standalone daemon, listening for
+            requests.</para></listitem>
+        <listitem><para>Have the Unix <command>inetd</command> daemon
+            temporarily spawn <command>svnserve</command> whenever a
+            request comes in on a certain port.</para></listitem>
+        <listitem><para>Have SSH invoke a
+            temporary <command>svnserve</command> over an encrypted
+            tunnel.</para></listitem>
+        <listitem><para>Run <command>svnserve</command> as a Windows
+            service.</para></listitem>
+      </itemizedlist>
+      <sect3 id="svn.serverconfig.svnserve.invoking.daemon">
+        <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
+          <option>-d</option> option for this:</para>
+
+        <screen>
+$ svnserve -d
+$               # svnserve is now running, listening on port 3690
+</screen>
+
+        <para>When running <command>svnserve</command> in daemon mode,
+          you can use the <option>--listen-port=</option> and
+          <option>--listen-host=</option> options to customize the
+          exact port and hostname to <quote>bind</quote> to.</para>
+
+      <para>Once the <command>svnserve</command> program is running,
+        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>/usr/local/repositories/project1</filename>, then a
+        client would reach it via
+        <uri>svn://host.example.com/usr/local/repositories/project1</uri>.
+        To increase security, you can pass the <option>-r</option>
+        option to <command>svnserve</command>, which restricts it to
+        exporting only repositories below that path.  For example:</para>
+      
+      <screen>
+$ svnserve -d -r /usr/local/repositories
+…
+</screen>
+
+      <para>Using the <option>-r</option> option effectively
+        modifies the location that the program treats as the root of
+        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
+…
+</screen>
+
+      </sect3>
+
+
+      <sect3 id="svn.serverconfig.svnserve.invoking.inetd">
+        <title><command>svnserve</command> via <command>inetd</command></title>
+
+        <para>If you want <command>inetd</command> launch the process,
+          then you can pass the <option>-i</option>
+          (<option>--inetd</option>) option:</para>
 
       <screen>
 $ svnserve -i
@@ -733,30 +806,20 @@
         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.</para>
+        <command>svnserve</command> process to service it.  Of course,
+        you may also want to add <option>-r</option> to the
+        configuration line as well, to restrict which repositories are
+        exported.</para>
 
-      <para>On a Windows system, third-party tools exist to run
-      <command>svnserve</command> as a service.  Look on Subversion's
-      website for a list of these tools.</para>
-
-      <para>A second option is to run <command>svnserve</command> as a
-        standalone <quote>daemon</quote> process.  Use the
-        <option>-d</option> option for this:</para>
+      </sect3>
 
-        <screen>
-$ svnserve -d
-$               # svnserve is now running, listening on port 3690
-</screen>
+      <sect3 id="svn.serverconfig.svnserve.invoking.tunnel">
+        <title><command>svnserve</command> over a Tunnel</title>
 
-      <para>When running <command>svnserve</command> in daemon mode,
-        you can use the <option>--listen-port=</option> and
-        <option>--listen-host=</option> options to customize the exact
-        port and hostname to <quote>bind</quote> to.</para>
-
-      <para>There's still a third way to invoke
-        <command>svnserve</command>, and that's in <quote>tunnel
-        mode</quote>, with the <option>-t</option> option.  This mode
-        assumes that a remote-service program such as
+      <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
         successfully authenticated a user and is now invoking a
         private <command>svnserve</command> process <emphasis>as that
@@ -771,34 +834,83 @@
         a local user accessing the repository via
         <literal>file:///</literal> URLs.</para>
 
-      <para>Once the <command>svnserve</command> program is running,
-        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>/usr/local/repositories/project1</filename>, then a
-        client would reach it via
-        <uri>svn://host.example.com/usr/local/repositories/project1</uri>.
-        To increase security, you can pass the <option>-r</option>
-        option to <command>svnserve</command>, which restricts it to
-        exporting only repositories below that path:</para>
-      
-      <screen>
-$ svnserve -d -r /usr/local/repositories
-…
-</screen>
+      <para>This option is described in much more detail in
+        <xref linkend="svn.serverconfig.svnserve.sshauth"/>.</para>
+
+      </sect3>
+
+      <sect3 id="svn.serverconfig.svnserve.invoking.winservice">
+        <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
+          run <command>svnserve</command> as a standard Windows
+          service.  You'll need to define the service using a
+          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>
+
+        <screen>
+C:\> sc create svn
+        binpath= "C:\svn\bin\svnserve.exe --service [args]"
+        displayname= "Subversion Server"
+        depend= Tcpip
+        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.  There are a number of caveats in the prior
+          example, however.</para>
+
+        <para>First, notice that the <command>svnserve.exe</command>
+          program is always invoked with
+          the <option>--service</option> option.  You must always
+          specify this option, and you may <emphasis>not</emphasis>
+          specify other conflicting options such
+          as <option>--daemon</option>, <option>--tunnel</option>,
+          or <option>--inetd</option>.  Options such
+          as <option>-r</option> or <option>--listen-port</option> are
+          fine.  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
+          them:</para>
+
+        <screen>
+C:\> sc create svn
+        binpath= "\"C:\program files\svn\bin\svnserve.exe\" --service [args]"
+        displayname= "Subversion Server"
+        depend= Tcpip
+        start= auto
+</screen>
+
+        <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>
+
+        <screen>
+C:\> net stop svn
+C:\> net start svn
+</screen>
+
+        <para>The service can also be uninstalled (i.e. undefined) by
+          deleting its definition:  <literal>sc delete svn</literal>.
+          Just be sure to stop the service first!
+          The <command>SC.EXE</command> program has many other
+          subcommands and options, run <literal>sc /?</literal> to
+          learn more about it.</para>
+
+      </sect3>
 
-      <para>Using the <option>-r</option> option effectively
-        modifies the location that the program treats as the root of
-        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
-…
-</screen>
- 
     </sect2>
 
     <!-- =============================================================== -->
@@ -2145,7 +2257,7 @@
           browser.  Since Subversion uses URLs to identify versioned
           resources, those URLs used for HTTP-based repository access
           can be typed directly into a Web browser.  Your browser will
-          issue a <literal>GET</literal> request for that URL, and
+          issue an HTTP <literal>GET</literal> request for that URL, and
           based on whether that URL represents a versioned directory
           or file, mod_dav_svn will respond with a directory listing
           or with file contents.</para>
@@ -2159,40 +2271,6 @@
           manifestation of that document.  Of course, you can even use
           the URLs as hyperlinks from other web sites, too.</para>
 
-        <para>You generally will get more use out of URLs to versioned
-          files—after all, that's where the interesting content
-          tends to lie.  But you might have occasion to browse a
-          Subversion directory listing, where you'll quickly note that
-          the generated HTML used to display that listing is very
-          basic, and certainly not intended to be aesthetically
-          pleasing (or even interesting).  To enable customization of
-          these directory displays, Subversion provides an XML index
-          feature.  A single <literal>SVNIndexXSLT</literal> directive
-          in your repository's <literal>Location</literal> block of
-          <filename>httpd.conf</filename> will instruct mod_dav_svn to
-          generate XML output when displaying a directory listing, and
-          to reference the XSLT stylesheet of your choice:</para>
- 
-        <screen>
-<Location /svn>
-  DAV svn
-  SVNParentPath /usr/local/svn
-  SVNIndexXSLT "/svnindex.xsl"
-  …
-</Location>
-</screen>
-
-        <para>Using the <literal>SVNIndexXSLT</literal> directive and
-          a creative XSLT stylesheet, you can make your directory
-          listings match the color schemes and imagery used in other
-          parts of your website.  Or, if you'd prefer, you can use the
-          sample stylesheets provided in the Subversion source
-          distribution's <filename>tools/xslt/</filename> directory.
-          Keep in mind that the path provided to the
-          <literal>SVNIndexXSLT</literal> directory is actually a URL
-          path—browsers need to be able to read your stylesheets
-          in order to make use of them!</para>
-
         <sidebar>
           <title>Can I view older revisions?</title>
 
@@ -2224,16 +2302,224 @@
             <footnote>
               <para>Back then, it was called <quote>ViewCVS</quote>.</para>
             </footnote>
-            and the latest bleeding-edge versions (at
-            the time of writing) are able to understand Subversion
+            and the latest releases are able to understand Subversion
             repositories as well.</para>
         </sidebar>
 
+        <sect4 id="svn.serverconfig.httpd.extra.browsing.mimetype">
+          <title>Proper MIME Type</title>
+
+          <para>When browsing a Subversion repository, the web browser
+            gets a clue about how to render a file's contents by
+            looking at the <literal>Content-Type:</literal> header
+            returned in Apache's response to the
+            HTTP <literal>GET</literal> request.  The value of this
+            header is some sort of MIME type.  By default, Apache will
+            tell the web browsers that all repository files are of
+            the <quote>default</quote> MIME type,
+            typically <literal>text/plain</literal>.  This can be
+            frustrating, however, if a user wishes repository files to
+            render as something more meaningful — for example,
+            it might be nice to have a <filename>foo.html</filename> file
+            in the repository actually render as HTML when
+            browsing.</para>
+
+          <para>To make this happen, you only need to make sure that
+            your files have the
+            proper <literal>svn:mime-type</literal> set.  This is
+            discussed in more detail in
+            <xref linkend="svn.advanced.props.special.mime-type"/>,
+            and you can even configure your client to automatically
+            attach proper <literal>svn:mime-type</literal> properties
+            to files entering the repository for the first time;  see
+            <xref linkend="svn.advanced.props.auto"/>.</para>
+
+          <para>So in our example, if one were to set
+          the <literal>svn:mime-type</literal> property
+          to <literal>text/html</literal> on
+          file <filename>foo.html</filename>, then Apache would
+          properly tell your web browser to render the file as
+          HTML.  One could also attach
+          proper <literal>image/*</literal> mime-type properties to
+          images, and by doing this, ultimately get an entire web
+          site to be viewable directly from a repository!  There's
+          generalyl no problem with doing this, as long as the
+          website doesn't contain any dynamically-generated
+          content.</para>
+
+        </sect4>
+
+        <sect4 id="svn.serverconfig.httpd.extra.browsing.xslt">
+          <title>Customizing the Look</title>
+
+          <para>You generally will get more use out of URLs to
+            versioned files—after all, that's where the
+            interesting content tends to lie.  But you might have
+            occasion to browse a Subversion directory listing, where
+            you'll quickly note that the generated HTML used to
+            display that listing is very basic, and certainly not
+            intended to be aesthetically pleasing (or even
+            interesting).  To enable customization of these directory
+            displays, Subversion provides an XML index feature.  A
+            single <literal>SVNIndexXSLT</literal> directive in your
+            repository's <literal>Location</literal> block of
+            <filename>httpd.conf</filename> will instruct mod_dav_svn
+            to generate XML output when displaying a directory
+            listing, and to reference the XSLT stylesheet of your
+            choice:</para>
+ 
+        <screen>
+<Location /svn>
+  DAV svn
+  SVNParentPath /usr/local/svn
+  SVNIndexXSLT "/svnindex.xsl"
+  …
+</Location>
+</screen>
+
+         <para>Using the <literal>SVNIndexXSLT</literal> directive and
+           a creative XSLT stylesheet, you can make your directory
+           listings match the color schemes and imagery used in other
+           parts of your website.  Or, if you'd prefer, you can use
+           the sample stylesheets provided in the Subversion source
+           distribution's <filename>tools/xslt/</filename> directory.
+           Keep in mind that the path provided to the
+           <literal>SVNIndexXSLT</literal> directory is actually a URL
+           path—browsers need to be able to read your
+           stylesheets in order to make use of them!</para>
+
+         </sect4>
+
+        <sect4 id="svn.serverconfig.httpd.extra.browsing.reposlisting">
+          <title>Listing Repositories</title>
+
+          <para>If you're serving a colllection of repositories from a
+            single URL via the <literal>SVNParentPath</literal>
+            directive, then it's also possible to have Apache display
+            all available repositories to a web browser.  Just
+            activate the <literal>SVNListParentPath</literal>
+            directive:</para>
+
+          <screen>
+<Location /svn>
+  DAV svn
+  SVNParentPath /usr/local/svn
+  SVNListParentPath on
+  …
+</Location>
+</screen>
+
+          <para>If a user now points her web browser to the
+          URL <literal>http://host.example.com/svn/</literal>, she'll
+          see list of all Subversion repositories sitting
+          in <filename>/usr/local/svn</filename>.  Obviously, this can
+          be a security problem, so this feature is turned off by
+          default.</para>
+
+        </sect4>
+
+      </sect3>
+
+      <sect3 id="svn.serverconfig.httpd.extra.logging">
+        <title>Apache Logging</title>
+
+        <para>Because Apache is an HTTP server at heart, it contains
+          fantastically flexible logging feature.  It's beyond the
+          scope of this book to discuss all ways logging can be
+          configured, but we should point out that even the most
+          generic <filename>httpd.conf</filename> file will cause
+          Apache to produce two logs:
+          <filename>error_log</filename>
+          and <filename>access_log</filename>.  These logs may appear
+          in different places, but are typically created in the
+          logging area of your Apache installation.  (On Unix, they
+          often live
+          in <filename>/usr/local/apache2/logs/</filename>.)</para>
+
+        <para>The <filename>error_log</filename> describes any interal
+          errors that Apache runs into as it works.
+          The <filename>access_log</filename> file records every
+          incoming HTTP request received by Apache.  This makes it
+          easy to see, for example, which IP addresses Subversion
+          clients are coming from, how often particular clients use
+          the server, which users are authenticating properly, and
+          which requests succeed or fail.</para>
+
+        <para>Unfortunately, because HTTP is a stateless protocol,
+          even the simplest Subversion client operation generates
+          multiple network requests.  It's very difficult to look at
+          the <filename>access_log</filename> and deduce what the
+          client was doing — most operations look like a series
+          of cryptic <literal>PROPPATCH</literal>, <literal>GET</literal>,
+          <literal>PUT</literal>, and <literal>REPORT</literal>
+          requests.  To make things worse, many client operations send
+          nearly-identical series of requests, so it's even harder to
+          tell them apart.</para>
+
+        <para><literal>mod_dav_svn</literal>, however, can come to
+          your aid.  By activating an <quote>operational
+          logging</quote> feature, you can
+          ask <literal>mod_dav_svn</literal> to create a separate log
+          file describing what sort of high-level operations your
+          clients are performing.</para>
+
+        <para>To do this, you need to make use of
+          Apache's <literal>CustomLog</literal> directive (which is
+          explained in more detail in Apache's own documentation).
+          Be sure to invoke this
+          directive <emphasis>outside</emphasis> of your
+          Subversion <literal>Location</literal> block:</para>
+
+        <screen>
+<Location /svn>
+  DAV svn
+  …
+</Location>
+
+CustomLog logs/svn_logfile "%t %u %{SVN-ACTION}e" env=SVN-ACTION
+</screen>
+
+        <para>In this example, we're asking Apache to create a special
+          logfile <filename>svn_logfile</filename> in the standard
+          Apache <filename>logs</filename> directory.
+          The <literal>%t</literal> and <literal>%u</literal>
+          variables are replaced by the time and username of the
+          request, respectively.  The really important part are the
+          two instances of <literal>SVN-ACTION</literal>.
+          When Apache sees that variable, it substitutes the value of
+          the <literal>SVN-ACTION</literal> environment variable,
+          which is automatically set by <literal>mod_dav_svn</literal>
+          whenever it detects a high-level client action.</para>
+
+        <para>So instead of having to interpret a
+          traditional <filename>access_log</filename> like
+          this:</para>
+
+        <screen>
+[26/Jan/2007:22:25:29 -0600] "PROPFIND /svn/calc/!svn/vcc/default HTTP/1.1" 207 398
+[26/Jan/2007:22:25:29 -0600] "PROPFIND /svn/calc/!svn/bln/59 HTTP/1.1" 207 449
+[26/Jan/2007:22:25:29 -0600] "PROPFIND /svn/calc HTTP/1.1" 207 647
+[26/Jan/2007:22:25:29 -0600] "REPORT /svn/calc/!svn/vcc/default HTTP/1.1" 200 607
+[26/Jan/2007:22:25:31 -0600] "OPTIONS /svn/calc HTTP/1.1" 200 188
+[26/Jan/2007:22:25:31 -0600] "MKACTIVITY /svn/calc/!svn/act/e6035ef7-5df0-4ac0-b811-4be7c823f998 HTTP/1.1" 201 227
+…
+</screen>
+
+        <para>… you can instead peruse a much more
+          intelligible <filename>svn_logfile</filename> like this:</para>
+
+        <screen>
+[26/Jan/2007:22:24:20 -0600] - list-dir '/'
+[26/Jan/2007:22:24:27 -0600] - update '/'
+[26/Jan/2007:22:25:29 -0600] - remote-status '/'
+[26/Jan/2007:22:25:31 -0600] sally commit r60
+</screen>
+
       </sect3>
 
       <sect3 id="svn.serverconfig.httpd.extra.other">
         <title>Other Features</title>
-        
+
         <para>Several of the features already provided by Apache in
           its role as a robust Web server can be leveraged for
           increased functionality or security in Subversion as well.
@@ -2246,7 +2532,7 @@
           of data).  You need only to compile support for the features
           you desire into Subversion and Apache, and properly
           configure the programs to use those features.</para>
-    
+
         <para>Deflate compression places a small burden on the client
           and server to compress and decompress network transmissions
           as a way to minimize the size of the actual transmission.




More information about the svnbook-dev mailing list