[svnbook commit] r2864 - trunk/src/en/book
sussman
noreply at red-bean.com
Fri Aug 17 14:58:39 CDT 2007
Author: sussman
Date: Fri Aug 17 14:58:39 2007
New Revision: 2864
Log:
Finish chapter 6 edits suggested by offby1 in issue 63.
* src/en/book/ch06-server-configuration.xml: lots of small wording tweaks.
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 Aug 17 14:58:39 2007
@@ -264,7 +264,7 @@
<listitem><para>Requires users to be in same system group, or
use a shared ssh key.</para></listitem>
- <listitem><para>Can lead to file permissions
+ <listitem><para>If used improperly, can lead to file permissions
problems.</para></listitem>
</itemizedlist>
@@ -339,7 +339,7 @@
<command>svnserve</command> installation for small teams just
trying to get started with a Subversion server; it's the
simplest to set up, and has the fewest maintenance issues.
- Remember, you can always switch to a more complex server
+ You can always switch to a more complex server
deployment as your needs change.</para>
<para>Here are some general recommendations and tips, based on
@@ -476,7 +476,7 @@
<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,
+ <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
<emphasis>absolute</emphasis> path in the repository URL. For
@@ -510,9 +510,14 @@
<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>
+ <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>
<screen>
$ svnserve -i
@@ -563,8 +568,12 @@
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>. The <command>svnserve</command>
- program behaves normally (communicating via
+ that user</emphasis>. (Note that you, the user, will
+ rarely, if ever, have reason to invoke
+ <command>svnserve</command> with the <option>-t</option> at
+ 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>),
and assumes that the traffic is being automatically
redirected over some sort of tunnel back to the client.
@@ -652,7 +661,7 @@
embedded spaces.</para>
<para>Once the service is defined, it can stopped, started, or
- queried using standard GUI tools (The Services
+ queried using standard GUI tools (the Services
administrative control panel), or at the command line as
well:</para>
@@ -665,7 +674,7 @@
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
+ subcommands and options; run <literal>sc /?</literal> to
learn more about it.</para>
</sect3>
@@ -734,7 +743,7 @@
<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 this file and learn how
+ value</literal>). Let's walk through these files and learn how
to use them.</para>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
@@ -743,8 +752,9 @@
<para>For now, the <literal>[general]</literal> section of the
<filename>svnserve.conf</filename> has all the variables you
- need. Begin by defining a file which contains usernames and
- passwords, and an authentication realm:</para>
+ 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>
<screen>
[general]
@@ -797,7 +807,7 @@
and <literal>auth-access</literal> can be set to the values
<literal>none</literal>, <literal>read</literal>, or
<literal>write</literal>. Setting the value to
- <literal>none</literal> restricts all access of any kind;
+ <literal>none</literal> prohibits both reading and writing;
<literal>read</literal> allows read-only access to the
repository, and <literal>write</literal> allows complete
read/write access to the repository. For example:</para>
@@ -901,7 +911,7 @@
<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 attributed as the
+ 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
@@ -954,7 +964,9 @@
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. In the
+ 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>
@@ -1042,9 +1054,9 @@
</screen>
<para>The first field describes the type of key, the second
- field is the uuencoded key itself, and the third field is a
- comment. However, it's a lesser known fact that the entire
- line can be preceded by a <literal>command</literal>
+ field is the base64-encoded key itself, and the third field
+ is a comment. However, it's a lesser known fact that the
+ entire line can be preceded by a <literal>command</literal>
field:</para>
<screen>
@@ -1357,8 +1369,9 @@
whether to look for a file <filename>repos/foo.c</filename> in
the <literal>DocumentRoot</literal>, or whether to delegate
<command>mod_dav_svn</command> to return
- <filename>foo.c</filename> from the Subversion
- repository.</para>
+ <filename>foo.c</filename> from the Subversion repository.
+ The result is often an error from the server of the form
+ <literal>301 Moved Permanently</literal>.</para>
<sidebar>
<title>Server Names and the COPY Request</title>
@@ -1437,7 +1450,7 @@
<itemizedlist>
<listitem>
- <para>anyone can use their Subversion client to checkout a
+ <para>anyone can use their Subversion client to check out a
working copy of a repository URL (or any of its
subdirectories),</para>
</listitem>
@@ -1467,8 +1480,7 @@
username and password to verify that a user is who she says
she is. Apache provides an <command>htpasswd</command>
utility for managing the list of acceptable usernames and
- passwords, those to whom you wish to grant special access to
- your Subversion repository. Let's grant commit access to
+ passwords. Let's grant commit access to
Sally and Harry. First, we need to add them to the password
file.</para>
@@ -1555,7 +1567,7 @@
<footnote>
<para>While self-signed server certificates are still
vulnerable to a <quote>man in the middle</quote> attack,
- such an attack is still much more difficult for a casual
+ such an attack is much more difficult for a casual
observer to pull off, compared to sniffing unprotected
passwords.</para>
</footnote>
@@ -1630,13 +1642,13 @@
<para>This dialogue should look familiar; it's essentially the
same question you've probably seen coming from your web
- browser (which is just another HTTP client like Subversion!).
+ browser (which is just another HTTP client like Subversion).
If you choose the (p)ermanent option, the server certificate
will be cached in your private run-time
<filename>auth/</filename> area in just the same way your
username and password are cached (see <xref
linkend="svn.serverconfig.netmodel.credcache"/>). If cached,
- Subversion will automatically remember to trust this certificate
+ Subversion will automatically trust this certificate
in future negotiations.</para>
<para>Your run-time <filename>servers</filename> file also gives
@@ -2202,7 +2214,7 @@
<title>Apache Logging</title>
<para>Because Apache is an HTTP server at heart, it contains
- fantastically flexible logging feature. It's beyond the
+ fantastically flexible logging features. 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
@@ -2675,7 +2687,7 @@
these newly created files won't necessarily be owned by that
same group, which then creates more permissions problems for
your users. A good workaround is to set the group SUID bit on
- the repository's <filename>db</filename> directory. This causes
+ the repository's <filename>db</filename> directory. This causes
all newly-created log files to have the same group owner as the
parent directory.</para>
@@ -2711,19 +2723,24 @@
<itemizedlist>
<listitem>
<para>All of your SSH users need to be able to read and
- write to the repository. Put all the SSH users into a
- single group. Make the repository wholly owned by that
- group, and set the group permissions to read/write.</para>
+ write to the repository, so: put all the SSH users into a
+ single group. </para>
</listitem>
-
+ <listitem>
+ <para>
+ Make the repository wholly owned by that group.
+ </para></listitem>
+ <listitem><para>Set the group permissions to read/write.</para></listitem>
<listitem>
<para>Your users need to use a sane umask when accessing the
- repository. Make sure that <command>svnserve</command>
+ repository, so: make sure that <command>svnserve</command>
(<filename>/usr/bin/svnserve</filename>, or wherever
it lives in <literal>$PATH</literal>) is actually a
wrapper script which sets <command>umask 002</command> and
executes the real <command>svnserve</command>
- binary. Take similar measures when using
+ binary. </para></listitem>
+
+ <listitem><para>Take similar measures when using
<command>svnlook</command> and
<command>svnadmin</command>. Either run them with a sane
umask, or wrap them as described above.</para>
More information about the svnbook-dev
mailing list