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

SvnBook noreply at red-bean.com
Wed Aug 15 09:30:41 CDT 2007


#63: [PATCH] Hanchrow review [ch5:ch6]
--------------------------+-------------------------------------------------
  Reporter:  cmpilato     |       Owner:  sussman
      Type:  enhancement  |      Status:  new    
  Priority:  normal       |   Milestone:  1.4    
 Component:  content      |     Version:         
Resolution:               |    Keywords:         
--------------------------+-------------------------------------------------
Changes (by cmpilato):

  * owner:  cmpilato => sussman
  * summary:  [PATCH] Hanchrow review [ch5] => [PATCH] Hanchrow review
              [ch5:ch6]

Comment:

 Failed to notice that this patch is for ch5 and ch6.  I've reviewed and
 applied the ch5 stuff, so here's an updated ch6 patch that applies cleanly
 for sussman to play with:

 {{{
 Index: ch06-server-configuration.xml
 ===================================================================
 --- ch06-server-configuration.xml       (revision 2854)
 +++ 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
 @@ -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
 @@ -652,7 +675,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 +688,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>
 @@ -684,6 +707,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>
 @@ -734,7 +760,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 +769,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]
 @@ -752,6 +779,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
 @@ -797,7 +827,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 +931,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 +984,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,7 +1074,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>
 @@ -1359,6 +1392,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>
 @@ -1411,7 +1446,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>

      <!-- ===============================================================
 -->
 @@ -1437,7 +1473,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 +1503,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 +1590,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 +1665,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 +2237,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 +2710,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>

 @@ -2698,6 +2735,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>

 @@ -2711,19 +2750,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#comment:3>
SvnBook <http://svnbook.red-bean.com/>


More information about the svnbook-dev mailing list