[PATCH] Review notes on Subversion book: chapters 5 and 6
Eric Hanchrow
offby1 at blarg.net
Fri Mar 16 13:52:38 CDT 2007
Index: ch05-repository-admin.xml
===================================================================
--- ch05-repository-admin.xml (revision 2737)
+++ ch05-repository-admin.xml (working copy)
@@ -92,8 +92,8 @@
<varlistentry>
<term>format</term>
<listitem>
- <para>A file whose contents are a single integer value that
- dictates the version number of the repository layout.</para>
+ <para>A file that contains a single integer that
+ indicates the version number of the repository layout.</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -144,12 +144,12 @@
creating and configuring a repository are fairly straightforward
tasks. There are a few preliminary decisions you'll want to
make, but the actual work involved in any given setup of a
- Subversion repository is pretty straightforward, tending towards
+ Subversion repository is pretty straightforward, <!-- do we
+ really want to say this? --> tending towards
mindless repetition if you find yourself setting up multiples of
these things.</para>
- <para>Some of things you'll want to consider up front, though, are
- as follows:</para>
+ <para>Some things you'll want to consider up front, though, are:</para>
<itemizedlist>
<listitem>
@@ -390,8 +390,8 @@
at all because only one of the available back-ends will work
in this scenario.</para>
- <para>To try to address each and every possible way to deploy
- Subversion is both not possible and outside the scope of this
+ <para>Addressing each possible way to deploy
+ Subversion is both impossible, and outside the scope of this
book. We simply encourage you to evaluate your options using
these pages and other sources as your reference material, and
plan ahead.</para>
@@ -419,7 +419,10 @@
however, assumes that the reader is thinking
<quote>eff-ess-eff-ess</quote>.)</para>
</footnote>
- —a versioned filesystem implementation that uses the
+ —a versioned filesystem implementation <!-- this implies
+ that BDB, somehow, _doesn't_ use the native OS filesystem to
+ store data, which isn't true -->
+ that uses the
native OS filesystem to store data.</para>
<para><xref linkend="svn.reposadmin.basics.backends.tbl-1" />
@@ -708,7 +711,7 @@
waiting for a response.</para>
<para>The most important distinction, however, is FSFS's
- inability to be <quote>wedged</quote> when something goes
+ imperviousness to <quote>wedging</quote> when something goes
wrong. If a process using a Berkeley DB database runs into
a permissions problem or suddenly crashes, the database can
be left in an unusable state until an administrator recovers
@@ -843,7 +846,13 @@
report what is about to happen and to prevent it from
happening at all. Other hooks (the <quote>post hooks</quote>)
run after the completion of a repository event, and are useful
- for reporting purposes only. Each hook is handed enough
+ for reporting purposes only. <!-- not strictly true; the
+ post-commit hook often causes an "svn up" to run somewhere.
+ You _might_ claim that that's an example of reporting, but
+ that would be straining the definition of "reporting".
+ Perhaps we should say something like "... are useful only for
+ things that examine, rather than modify, the repos" -->
+ Each hook is handed enough
information to tell what that event is (or was), the specific
repository changes proposed (or completed), and the username
of the person who triggered the event.</para>
@@ -886,6 +895,9 @@
need to supply a program whose basename is the name of the
hook, and whose extension is one of the special extensions
recognized by Windows for executable programs, such as
+ <!-- even though .com is, strictly speaking, supported on
+ Windows, I suspect in practice it's a bad idea to create .com
+ files. So maybe we shouldn't mention them at all. -->
<filename>.exe</filename> or <filename>.com</filename> for
programs, and <filename>.bat</filename> for batch
files.</para>
@@ -902,6 +914,9 @@
and/or use absolute paths to programs.</para>
</tip>
+ <!-- "will attempt to"? Are there cases when this can fail? if
+ so, what are they? If not, why not just say "Subversion
+ executes hooks as ..." -->
<para>Subversion will attempt to execute hooks as the same user
who owns the process which is accessing the Subversion
repository. In most cases, the repository is being accessed
@@ -920,10 +935,11 @@
<xref linkend="svn.ref.reposhooks" />. As a repository
administrator, you'll need to decide which of hooks you wish
to implement (by way of providing an appropriately named and
- permissioned hook program), and how. This decision needs to
- be made with the bigger picture of how repository is deployed
- in mind. For example, if you are using server configuration
- stuffs to determine which usernames are permitted to commit
+ permissioned hook program), and how. When you make this
+ decision, keep in mind
+ the big picture of how your repository is deployed.
+ For example, if you are using server configuration
+ to determine which users are permitted to commit
changes to your repository, then you don't need to do this
sort of access control via the hook system.</para>
@@ -938,7 +954,7 @@
linkend="svn.developer" />.</para>
<warning>
- <para>While hook scripts can be leveraged to do almost
+ <para>While hook scripts can do almost
anything, there is one dimension in which hook script
authors should show restraint: do <emphasis>not</emphasis>
modify a commit transaction using hook scripts. While it
@@ -952,7 +968,7 @@
behavior. Instead of modifying the transaction, you should
simply <emphasis>validate</emphasis> the transaction in the
<filename>pre-commit</filename> hook and reject the commit
- if it does not meet the desired requirements. As an added
+ if it does not meet the desired requirements. As a
bonus, your users will learn the value of careful,
compliance-minded work habits.</para>
</warning>
@@ -979,15 +995,10 @@
applications and database environments have different
requirements, and so they have provided a mechanism for
overriding at runtime many of the configuration values for the
- Berkeley DB environment. Berkeley checks for the presence of
+ Berkeley DB environment: bdb checks for the presence of
a file named <filename>DB_CONFIG</filename> in the environment
- directory, and parses the options found in that file for use
- with that particular Berkeley DB environment.</para>
-
- <para>The Berkeley DB configuration file for a BDB-backed
- repository is located in the repository's
- <filename>db</filename> subdirectory, at
- <filename>db/DB_CONFIG</filename>. Subversion itself creates
+ directory (namely, the repository's
+ <filename>db</filename> subdirectory), and parses the options found in that file . Subversion itself creates
this file when it creates the rest of the repository. The
file initially contains some default options, as well as
pointers to the Berkeley DB online documentation so you can
@@ -1013,7 +1024,7 @@
<sect1 id="svn.reposadmin.maint">
<title>Repository Maintenance</title>
- <para>Maintaining a Subversion repository can be a daunting task,
+ <para>Maintaining a Subversion repository can be daunting,
mostly due to the complexities inherent in systems which have a
database backend. Doing the task well is all about knowing the
tools—what they are, when to use them, and how to use
@@ -1062,7 +1073,7 @@
<para>We've already mentioned <command>svnadmin</command>'s
<literal>create</literal> subcommand (see <xref
linkend="svn.reposadmin.basics.creating"/>). Most of the
- others we will cover as they become topically relevant later
+ others we will cover later
in this chapter. And you can consult <xref
linkend="svn.ref.svnadmin" /> for a full rundown of
subcommands and what each of them offers.</para>
@@ -1075,6 +1086,9 @@
<para><command>svnlook</command> is a tool provided by
Subversion for examining the various revisions and
+ <!-- we haven't introduced transactions yet. Should we thus
+ use <firstterm>, or include a link to a section that
+ discusses them in detail, or what? -->
transactions in a repository. No part of this program
attempts to change the repository. <command>svnlook</command>
is typically used by the repository hooks for reporting the
@@ -1161,6 +1175,8 @@
<para>The date, followed by a newline.</para>
</listitem>
<listitem>
+ <!-- it might be worth noting that the number of characters
+ is not necessarily the same as the number of bytes. -->
<para>The number of characters in the log message,
followed by a newline.</para>
</listitem>
@@ -1315,7 +1331,7 @@
recover</command> reflects the common use cases of the
<command>db_recover</command> utility.</para>
- <para>There are still a few Berkeley DB utilities that you
+ <para>However, there are still a few Berkeley DB utilities that you
might find useful. The <command>db_dump</command> and
<command>db_load</command> programs write and read,
respectively, a custom file format which describes the keys
@@ -1323,7 +1339,10 @@
databases are not portable across machine architectures,
this format is a useful way to transfer those databases from
machine to machine, irrespective of architecture or
- operating system. Also, the <command>db_stat</command>
+ operating system. <!-- why on Earth would I use db_dump instead
+ of "svnadmin dump"? You should probably explain that,
+ or else don't even mention them. -->
+ Also, the <command>db_stat</command>
utility can provide useful information about the status of
your Berkeley DB environment, including detailed statistics
about the locking and storage subsystems.</para>
@@ -1345,6 +1364,8 @@
misspelling or some misinformation, perhaps). If the
repository is configured (using the
<literal>pre-revprop-change</literal> and
+ <!-- I don't think post-revprop-change is necessary to allow
+ changes to log messages -->
<literal>post-revprop-change</literal> hooks; see <xref
linkend="svn.reposadmin.create.hooks"/>) to accept changes to this log
message after the commit is finished, then the user can
@@ -1366,12 +1387,13 @@
$ svnadmin setlog myrepos newlog.txt -r 388
</screen>
- <para>The <command>svnadmin setlog</command> command alone is
+ <para>The <command>svnadmin setlog</command> command, by
+ default, is
still bound by the same protections against modifying
unversioned properties as a remote client is—the
<literal>pre-</literal> and
<literal>post-revprop-change</literal> hooks are still
- triggered, and therefore must be setup to accept changes of
+ triggered, and therefore must be set up to accept changes of
this nature. But an administrator can get around these
protections by passing the <option>--bypass-hooks</option>
option to the <command>svnadmin setlog</command> command.</para>
@@ -1396,7 +1418,7 @@
past few years, disk usage is still a valid concern for
administrators seeking to version large amounts of data.
Every bit of version history information stored in the live
- repository is information that needs to be backed up
+ repository needs to be backed up
elsewhere, perhaps multiple times as part of rotating backup
schedules. It is useful to know what pieces of Subversion's
repository data need to remain on the live site, which need to
@@ -1406,7 +1428,7 @@
<sect3 id="svn.reposadmin.maint.diskspace.deltas">
<title>How Subversion saves disk space</title>
- <para>To keep the size of the repository as small as possible,
+ <para>To keep the repository small,
Subversion uses <firstterm>deltification</firstterm> (or,
<quote>deltified storage</quote>) within the repository
itself. Deltification involves encoding the representation
@@ -1418,11 +1440,11 @@
enough space to say, <quote>I look just like this other
piece of data over here, except for the following couple of
changes</quote>. The result is that most of the repository
- data that tends to be sizable—namely, the contents of
+ data that tends to be bulky—namely, the contents of
versioned files—is stored at a much smaller size than
the original <quote>fulltext</quote> representation of that
data. And for repositories created with Subversion 1.4 or
- later, the space saving get even better—now those
+ later, the space saving is even better—now those
fulltext representations of file contents are themselves
compressed.</para>
@@ -1452,7 +1474,7 @@
directory changes associated with it. This could happen for
several reasons: perhaps the client operation was
inelegantly terminated by the user, or a network failure
- might have occurred in the middle of an operation, etc.
+ occurred in the middle of an operation.
Regardless of the reason, dead transactions can happen.
They don't do any real harm, other than consuming disk
space. A fastidious administrator may nonetheless wish to
@@ -1476,7 +1498,8 @@
created the transaction, when it was created, what types of
changes were made in the transaction—information that
is helpful in determining whether or not the transaction is
- a safe candidate for removal! If so, the transaction's name
+ a safe candidate for removal! If you do indeed want to
+ remove a transaction, its name
can be passed to <command>svnadmin rmtxns</command>, which
will perform the cleanup of the transaction. In fact, the
<literal>rmtxns</literal> subcommand can take its input
@@ -1569,21 +1592,21 @@
before modifying the actual database files. These files
capture all the actions taken along the route of changing
the database from one state to another—while the
- database files reflect at any given time some state, the log
- files contain all the many changes along the way between
- states. As such, they can grow and accumulate quite
+ database files, at any given time, reflect a particular state, the log
+ files contain all the many changes along the way <emphasis>between</emphasis>
+ states. Thus, they can grow and accumulate quite
rapidly.</para>
<para>Fortunately, beginning with the 4.2 release of Berkeley
DB, the database environment has the ability to remove its
- own unused log files without any external procedures. Any
+ own unused log files automatically. Any
repositories created using an <command>svnadmin</command>
which is compiled against Berkeley DB version 4.2 or greater
will be configured for this automatic log file removal. If
you don't want this feature enabled, simply pass the
<option>--bdb-log-keep</option> option to the
<command>svnadmin create</command> command. If you forget
- to do this, or change your mind at a later time, simple edit
+ to do this, or change your mind at a later time, simply edit
the <filename>DB_CONFIG</filename> file found in your
repository's <filename>db</filename> directory, comment out
the line which contains the <literal>set_flags
@@ -1605,6 +1628,8 @@
list-unused-dblogs</command> command to list the unused
log files:</para>
+ <!-- why does this example use xargs, whereas an earlier
+ example about rmtxns used backticks? -->
<screen>
$ svnadmin list-unused-dblogs /path/to/repos
/path/to/repos/log.0000000031
@@ -1620,8 +1645,8 @@
as part of a backup or disaster recovery plan should
<emphasis>not</emphasis> make use of the log file
autoremoval feature. Reconstruction of a repository's
- data from log files can only be accomplished when the log
- files are all available. If some of the log files are
+ data from log files can only be accomplished when <emphasis>all</emphasis> the log
+ files are available. If some of the log files are
removed from disk before the backup system has a chance to
copy them elsewhere, the incomplete set of backed-up log
files is essentially useless.</para>
@@ -1684,7 +1709,7 @@
can permanently destroy a database environment. A
sufficiently paranoid repository administrator will have made
off-site backups of the repository data in some fashion, but
- head off to the tape backup storage closet just yet.</para>
+ don't head off to the tape backup storage closet just yet.</para>
<para>Instead, use the following recipe to attempt to
<quote>unwedge</quote> your repository:</para>
@@ -1736,6 +1761,8 @@
<para>If the previous procedure, for some reason, does not
successfully unwedge your repository, you should do two
+ <!-- do our readers know what "move out of the way" means?
+ Should we explain in detail? -->
things. First, move your broken repository out of the way and
restore your latest backup of it. Then, send an email to the
Subversion user list (at
@@ -1750,7 +1777,7 @@
<title>Migrating Repository Data Elsewhere</title>
<para>A Subversion filesystem has its data spread throughout
- various back-end data store files in a fashion generally
+ files in the repository, in a fashion generally
understood by (and of interest to) only the Subversion
developers themselves. However, circumstances may arise that
call for all, or some subset, of that data to be copied or
@@ -1762,7 +1789,8 @@
on disk) is a portable, flat file format that describes the
various revisions in your repository—what was changed,
by whom, when, and so on. This dump stream is the primary
- mechanism used to marshal versioned history—in whole or
+ mechanism used to <!-- do our readers know the term "marshal"? -->
+ marshal versioned history—in whole or
in part, with or without modification—between
repositories. And Subversion provides the tools necessary for
creating and loading these dump streams—the
@@ -1774,10 +1802,10 @@
human-readable portions and a familiar structure (it
resembles an RFC-822 format, the same type of format used
for most email), it is <emphasis>not</emphasis> a plaintext
- file format. The format should be treated as a binary file
- format, highly sensitive to meddling. Many text editor
- tools will corrupt the file's contents, often due to
- automatic line ending character conversion.</para>
+ file format: It is a binary file
+ format, highly sensitive to meddling. For example, many text editors
+ will corrupt the file by automatically converting
+ line endings.</para>
</warning>
<para>There are many reasons for dumping and loading Subversion
@@ -1797,10 +1825,10 @@
re-deploying a Berkeley DB repository on a new OS or CPU
architecture, switching between the Berkeley DB and FSFS
back-ends, or (as we'll cover in <xref
- linkend="svn.reposadmin.maint.filtering" /> purging versioned
+ linkend="svn.reposadmin.maint.filtering" />), purging versioned
data from repository history.</para>
- <para>Whatever your reason for migration repository history,
+ <para>Whatever your reason for migrating repository history,
using the <command>svnadmin dump</command> and
<command>svnadmin load</command> subcommands is
straightforward. <command>svnadmin dump</command> will output
@@ -1830,7 +1858,7 @@
requested range of revisions. Note that <command>svnadmin
dump</command> is reading revision trees from the repository
just like any other <quote>reader</quote> process would
- (<command>svn checkout</command>, for example). So it's safe
+ (<command>svn checkout</command>, for example), so it's safe
to run this command at any time.</para>
<para>The other subcommand in the pair, <command>svnadmin
@@ -1885,8 +1913,7 @@
course, you should use these options with care—if your
post-commit hook sends emails to a mailing list for each new
commit, you might not want to spew hundreds or thousands of
- commit emails in rapid succession at that list for each of the
- loaded revisions! You can read more about the use of hook
+ commit emails in rapid succession at that list! You can read more about the use of hook
scripts in <xref
linkend="svn.reposadmin.create.hooks"/>.</para>
@@ -1898,7 +1925,7 @@
<screen>
$ svnadmin create newrepos
-$ svnadmin dump myrepos | svnadmin load newrepos
+$ svnadmin dump oldrepos | svnadmin load newrepos
</screen>
<para>By default, the dump file will be quite large—much
@@ -1942,7 +1969,7 @@
revision. For one thing, there is no previous revision in the
dump file! And secondly, Subversion cannot know the state of
the repository into which the dump data will be loaded (if it
- ever, in fact, occurs). To ensure that the output of each
+ ever is). To ensure that the output of each
execution of <command>svnadmin dump</command> is
self-sufficient, the first dumped revision is by default a
full representation of every directory, file, and property in
@@ -1984,7 +2011,7 @@
nightly to append dump file data for all the revisions that
were added to the repository since the last time the script
ran. Used like this, <command>svnadmin dump</command> can be
- one way to backup changes to your repository over time in case
+ one way to back up changes to your repository over time in case
of a system crash or some other catastrophic event.</para>
<para>The dump format can also be used to merge the contents of
@@ -2192,8 +2219,8 @@
<warning>
<para>If you do plan on manually editing the dump file to
remove a top-level directory, make sure that your editor is
- not set to automatically convert end-lines to the native
- format (e.g. \r\n to \n) as the content will then not agree
+ not set to automatically convert end-of-line characters to the native
+ format (e.g. \r\n to \n), as the content will then not agree
with the metadata. This will render the dump file
useless.</para>
</warning>
@@ -2308,6 +2335,9 @@
readily available. If you suspect that you have any copies
of this sort in your repository, you might want to rethink
your set of included/excluded paths.</para>
+ <!-- ick. Can you point to a detailed explanation of 1) how to
+ recognize this situation if I accidentally stumble into it,
+ and 2) what to do about it? -->
<para>Finally, <command>svndumpfilter</command> takes path
filtering quite literally. If you are trying to copy the
@@ -2665,7 +2695,7 @@
time throughout the lifetime of the repository, and don't
leave an audit trail that indicates when they were changed,
replication processes have to pay special attention to them.
- If you've already mirror the first 15 revisions of a
+ If you've already mirrored the first 15 revisions of a
repository and someone then changes a revision property on
revision 12, <command>svnsync</command> won't know to go back
and patch up its copy of revision 12. You'll need to tell it
@@ -2729,11 +2759,12 @@
linkend="svn.ref.svn.c.switch" />. There is a possible danger
here, though, in that if the primary and mirror repositories
aren't in close synchronization, a working copy up-to-date
- with and pointing to the primary repository will, if relocated
+ with, and pointing to, the primary repository will, if relocated
to point to an out-of-date mirror, become confused about the
apparent sudden loss of revisions it fully expects to be
present.</para>
-
+ <!-- How would I recognize this "confusion" if I saw it? How do
+ I recover from it? -->
<para>Finally, be aware that the revision-based replication
provided by <command>svnsync</command> is only
that—replication of revisions. It does not include such
@@ -2764,7 +2795,7 @@
incremental. A full backup of the repository involves
squirreling away in one sweeping action all the information
required to fully reconstruct that repository in the event of
- a catastrophe. Usually, it means quite literally the
+ a catastrophe. Usually, it means, quite literally, the
duplication of the entire repository directory (which includes
either a Berkeley DB or FSFS environment). Incremental
backups are lesser things, backups of only the portion of the
@@ -2821,8 +2852,8 @@
regular basis. For example, you might consider using
<command>hot-backup.py</command> from a program scheduler
(such as <command>cron</command> on Unix systems) which will
- cause it to run nightly (or at whatever granularity of Time
- you deem safe enough for you).</para>
+ cause it to run nightly (or at whatever granularity of time
+ you deem safe).</para>
<para>Some administrators use a different backup mechanism built
around generating and storing repository dump data. We
@@ -2831,7 +2862,7 @@
perform an incremental backup of a given revision or range of
revisions. And of course, there is a full backup variation of
this achieved by omitting the <option>--incremental</option>
- option to that command. There is some value in these methods
+ option to that command. There is some value in these methods,
in that the format of your backed-up information is
flexible—it's not tied to a particular platform,
versioned filesystem type, or release of Subversion or
Index: ch06-server-configuration.xml
===================================================================
--- ch06-server-configuration.xml (revision 2737)
+++ ch06-server-configuration.xml (working copy)
@@ -100,6 +100,8 @@
</row>
<row>
+ <!-- might it be worthwhile to mention that you can get a
+ kind of authorization by using pre-commit hooks? -->
<entry>Authorization options</entry>
<entry>read/write access can be granted over whole
repository, or specified per-path.</entry>
@@ -136,6 +138,14 @@
<entry>Web viewing</entry>
<entry>limited built-in support, or via 3rd-party tools
such as ViewVC</entry>
+ <!-- does viewvc officially support remote repos access?
+ If not, we shouldn't mention it here. I might be
+ misunderstanding the point of this row - I -think-
+ you're talking about "ways of browsing your repo _that
+ use_ these access methods", as opposed to "ways of
+ browsing your repo _when you use these access methods to
+ do commits, checkouts, and other typical svn
+ operatioins". See the difference? -->
<entry>only via 3rd-party tools such as ViewVC</entry>
<entry>only via 3rd-party tools such as ViewVC</entry>
</row>
@@ -262,9 +272,12 @@
errors.</para></listitem>
<listitem><para>Requires users to be in same system group, or
+ <!-- this might need clarification. If users share an
+ ssh key, that only helps if they're also _logging in
+ as the same user_. Or am I misunderstanding? -->
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 +352,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
@@ -409,7 +422,7 @@
<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
+ 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>
@@ -471,12 +484,14 @@
$ # svnserve is now running, listening on port 3690
</screen>
+ <!-- is it worth saying pretty much what
+ http://subversion.tigris.org/faq.html#freebsd-listen-host says ? -->
<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,
+ <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 +525,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. Just below, 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,7 +583,10 @@
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>
+ 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
@@ -644,7 +667,7 @@
</screen>
<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>
@@ -657,7 +680,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>
@@ -676,6 +699,9 @@
repository.</para></listitem>
<listitem><para>The server processes the repository's
+ <!-- svn.serverconfig.overview.tbl-1 effectively says that
+ you can't do any authorization via svnserve; why, then,
+ does the server "enforce ... authorization policies"? -->
<filename>conf/svnserve.conf</filename> file, and begins to
enforce any authentication and authorization policies defined
therein.</para></listitem>
@@ -726,7 +752,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>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
@@ -735,8 +761,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]
@@ -744,6 +771,9 @@
realm = example realm
</screen>
+ <!-- what are the restrictions on the realm - may it be any
+ length; may it contain non-ASCII characters, if so, must it
+ use a particular encoding ... ? -->
<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
@@ -789,7 +819,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>
@@ -893,7 +923,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
@@ -946,7 +976,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>
@@ -1034,7 +1066,8 @@
</screen>
<para>The first field describes the type of key, the second
- field is the uuencoded key itself, and the third field is a
+ field is the <!-- well, base64-encoded, actually ... -->
+ 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:</para>
@@ -1351,6 +1384,8 @@
<command>mod_dav_svn</command> to return
<filename>foo.c</filename> from the Subversion
repository.</para>
+ <!-- what will the symptom look like? i.e., assuming someone
+ _does_ make this mistake, what will they see? -->
<sidebar>
<title>Server Names and the COPY Request</title>
@@ -1403,7 +1438,8 @@
aware that permission-related problems are perhaps the most
common oversight when configuring a Subversion repository for
use with Apache.</para>
-
+ <!-- again, it would be useful to include some examples of
+ common mistakes, along with the output of each -->
</sect2>
<!-- =============================================================== -->
@@ -1429,7 +1465,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>
@@ -1459,8 +1495,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>
@@ -1547,7 +1582,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>
@@ -1622,13 +1657,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
@@ -2088,7 +2123,7 @@
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,
+ 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>
@@ -2194,7 +2229,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
@@ -2219,7 +2254,7 @@
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
+ 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
@@ -2637,7 +2672,9 @@
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. <!-- I'm 99%
+ sure "svnadmin create" does this for you. -->
+ This causes
all newly-created log files to have the same group owner as the
parent directory.</para>
@@ -2660,6 +2697,8 @@
We recommend you choose the server that best meets your needs
and stick with it!</para>
+ <!-- this is another sidebar that could use an anchor, so that I
+ can easly hand out a URL to it. -->
<sidebar>
<title>The svn+ssh:// server checklist</title>
@@ -2673,19 +2712,25 @@
<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>
--
It is a truth universally acknowledged, that any language in
possession of a rich syntax, must be in want of a rewrite.
-- Piers Cawley
More information about the svnbook-dev
mailing list