[SvnBook] #63: [PATCH] Hanchrow review [ch5]

SvnBook noreply at red-bean.com
Fri Aug 10 21:07:50 CDT 2007


#63: [PATCH] Hanchrow review [ch5]
-------------------------+--------------------------------------------------
 Reporter:  cmpilato     |       Owner:  nobody
     Type:  enhancement  |      Status:  new   
 Priority:  normal       |   Milestone:        
Component:  content      |     Version:        
 Keywords:               |  
-------------------------+--------------------------------------------------
 From: Eric Hanchrow <offby1 at blarg.net>

 {{{
 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>
 }}}

-- 
Ticket URL: <http://svnbook.red-bean.com/trac/ticket/63>
SvnBook <http://svnbook.red-bean.com/>


More information about the svnbook-dev mailing list