[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