[svnbook commit] r2628 - trunk/src/en/book
sussman
noreply at red-bean.com
Mon Jan 22 02:03:08 CST 2007
Author: sussman
Date: Mon Jan 22 02:03:08 2007
New Revision: 2628
Modified:
trunk/src/en/book/ch-server-configuration.xml
Log:
Major changes/additions to chapter 6.
(Still more to do, but this is a good start.)
* src/en/ch-server-configuration.xml:
- new Overview section which describes pros/cons of servers
- new Overview section which makes explicit server recommendations
- lose a couple of obsolete-ish sidebars
- factorize path-based-authz description into its own section,
and make other the two server sections point to it
- new best-practice sidebar recommending not to use
path-based-authz unless absolutely necessary.
Modified: trunk/src/en/book/ch-server-configuration.xml
==============================================================================
--- trunk/src/en/book/ch-server-configuration.xml (original)
+++ trunk/src/en/book/ch-server-configuration.xml Mon Jan 22 02:03:08 2007
@@ -41,19 +41,6 @@
<xref linkend="svn.serverconfig.overview.tbl-1"/> presents a
comparison of the two servers.</para>
- <para>Note that Subversion, as an open-source project, does not
- officially endorse any server as <quote>primary</quote> or
- <quote>official</quote>. Neither network implementation is
- treated as a second-class citizen; each server has advantages
- and disadvantages. In fact, it's possible for different servers
- to run in parallel, each accessing your repositories in its own
- way, and each without hindering the other (see <xref
- linkend="svn.serverconfig.multimethod"/>). <xref
- linkend="svn.serverconfig.overview.tbl-1"/> gives a brief overview and
- comparison of the two available Subversion servers—as an
- administrator, it's up to you to choose whatever works best for
- you and your users.</para>
-
<table id="svn.serverconfig.overview.tbl-1">
<title>Network Server Comparison</title>
<tgroup cols="3">
@@ -67,77 +54,360 @@
<tbody>
<row>
<entry>Authentication options</entry>
-
<entry>HTTP(S) basic auth, X.509 certificates, LDAP, NTLM, or
any other mechanism available to Apache httpd</entry>
-
<entry>CRAM-MD5 or SSH</entry>
</row>
-
+
<row>
<entry>User account options</entry>
-
<entry>private 'users' file</entry>
-
<entry>private 'users' file, or existing system (SSH)
accounts</entry>
</row>
-
+
<row>
<entry>Authorization options</entry>
-
- <entry>blanket read/write access, or per-directory
- read/write control</entry>
-
- <entry>blanket read/write access, or per-directory write
- (but not read) control using a pre-commit hook</entry>
+ <entry>read/write access can be granted over whole
+ repository, or specified per-path.</entry>
+ <entry>read/write access can be granted over whole
+ repository, or specified per-path.</entry>
</row>
-
+
<row>
<entry>Encryption</entry>
-
<entry>via optional SSL</entry>
-
<entry>via optional SSH tunnel</entry>
</row>
<row>
+ <entry>Logging</entry>
+ <entry>full Apache logs of each HTTP request, with
+ optional <quote>high-level</quote> logging of general
+ client operations</entry>
+ <entry>no logging</entry>
+ </row>
+
+ <row>
<entry>Interoperability</entry>
-
<entry>partially usable by other WebDAV clients</entry>
-
- <entry>not interoperable</entry>
+ <entry>only talks to svn clients</entry>
</row>
<row>
<entry>Web viewing</entry>
-
<entry>limited built-in support, or via 3rd-party tools
such as ViewVC</entry>
-
- <entry>via 3rd-party tools such as ViewVC</entry>
+ <entry>only via 3rd-party tools such as ViewVC</entry>
</row>
<row>
<entry>Speed</entry>
-
<entry>somewhat slower</entry>
-
<entry>somewhat faster</entry>
</row>
<row>
<entry>Initial setup</entry>
-
<entry>somewhat complex</entry>
-
<entry>fairly simple</entry>
</row>
</tbody>
- </tgroup>
+ </tgroup>
</table>
-
+
+
+
+ <sect2 id="svn.serverconfig.overview.apache">
+
+ <title>The Apache HTTP Server</title>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>How it works:</term>
+ <listitem>
+ <para>Install and configure and standard Apache 2.0
+ server, then activate a special subversion-server module.
+ Clients speak to server via HTTP or HTTPS, using the WebDAV
+ protocol.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Why you might want to use it:</term>
+ <listitem>
+ <itemizedlist>
+
+ <listitem><para>Allows Subversion to use any of the
+ numerous authentication systems already integrated
+ with Apache.</para></listitem>
+
+ <listitem><para>No need to create system accounts on
+ server.</para></listitem>
+
+ <listitem><para>Full Apache logging.</para></listitem>
+
+ <listitem><para>Network traffic can be encrypted via
+ SSL.</para></listitem>
+
+ <listitem><para>HTTP(S) can usually go through corporate
+ firewalls.</para></listitem>
+
+ <listitem><para>Built-in repository browsing via web
+ browser.</para></listitem>
+
+ <listitem><para>Repository can be mounted as a network
+ drive for transparent version control. (See
+ <xref
+ linkend="svn.webdav.autoversioning"/>.)</para></listitem>
+
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Why you might want to avoid it:</term>
+ <listitem>
+ <itemizedlist>
+
+ <listitem><para>Noticeably slower than svnserve, because
+ HTTP is a stateless</para></listitem> protocol and
+ requires more turnarounds.
+
+ <listitem><para>Initial setup can be complex.</para></listitem>
+
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </sect2>
+
+
+ <sect2 id="svn.serverconfig.overview.svnserve">
+
+ <title>The <command>svnserve</command> Server</title>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>How it works:</term>
+ <listitem>
+ <para>A lightweight serve process which can run either as
+ a persistent daemon, or as something automatically
+ launched by inetd when necessary. Clients authenticate
+ via CRAM-MD5 algorithm and speak a custom network
+ protocol.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Why you might want to use it:</term>
+ <listitem>
+ <itemizedlist>
+
+ <listitem><para>Quick and easy to set
+ up.</para></listitem>
+
+ <listitem><para>Network protocol is stateful and
+ noticeably faster than WebDAV.</para></listitem>
+
+ <listitem><para>No need to create system accounts on
+ server.</para></listitem>
+
+ <listitem><para>Password is not passed over the
+ network.</para></listitem>
+
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Why you might want to avoid it:</term>
+ <listitem>
+ <itemizedlist>
+
+ <listitem><para>Network protocol is not
+ encrypted.</para></listitem>
+
+ <listitem><para>Only one choice of authentication
+ method.</para></listitem>
+
+ <listitem><para>Password is stored in the clear on the
+ server.</para></listitem>
+
+ <listitem><para>No logging of any kind, not even
+ errors.</para></listitem>
+
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </sect2>
+
+ <sect2 id="svn.serverconfig.overview.svn-ssh">
+
+ <title><command>svnserve</command> over SSH</title>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>How it works:</term>
+ <listitem>
+ <para> Each client uses an existing SSH (system) account
+ to spawn a temporary <command>svnserve</command> process
+ (running as themselves) on the server machine. The
+ <command>svnserve</command> process accesses the
+ repository, communicates with the client over the SSH
+ tunnel, then dies when the SSH connection is closed.
+ (There is no long-running <command>svnserve</command>
+ process.)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Why you might want to use it:</term>
+ <listitem>
+ <itemizedlist>
+
+ <listitem><para>Network protocol is stateful and
+ noticeably faster than WebDAV.</para></listitem>
+
+ <listitem><para>You can take advantage of existing ssh
+ accounts and user infrastructure.</para></listitem>
+
+ <listitem><para>All network traffic is
+ encrypted.</para></listitem>
+
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Why you might want to avoid it:</term>
+ <listitem>
+ <itemizedlist>
+
+ <listitem><para>Only one choice of authentication
+ method.</para></listitem>
+
+ <listitem><para>No logging of any kind, not even
+ errors.</para></listitem>
+
+ <listitem><para>Requires users to be in same system group, or
+ use a shared ssh key.</para></listitem>
+
+ <listitem><para>Can lead to file permissions
+ problems.</para></listitem>
+
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </sect2>
+
+ <sect2 id="svn.serverconfig.overview.choosing-a-server">
+
+ <title>Choosing the Best Server Configuration</title>
+
+ <para>So, which server should you use? Which is best?</para>
+
+ <para>Obviously, there's no right answer to that question.
+ Every team has different needs, and the different servers all
+ represent different sets of tradeoffs. The Subversion project
+ itself doesn't endorse one server or another, or consider
+ either server more <quote>official</quote> than
+ another.</para>
+
+ <para>In general, the authors of this book recommend a vanilla
+ <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
+ deployment as your needs change.</para>
+
+ <para>Here are some general recommendations, based on years of
+ supporting users:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>If you're trying to set up the simplest possible
+ server for your group, then a
+ vanilla <command>svnserve</command> installation is the
+ easiest, fastest route. Note, however, that your
+ repository data will be transmitted in the clear over the
+ network. If your deployment is entirely within your
+ company's LAN or VPN, this isn't an issue. If the
+ repository is exposed to the wide-open internet, then you
+ might want to make sure the repository's contents aren't
+ sensitive (e.g. it contains only open-source code.)</para>
+ </listitem>
+
+ <listitem>
+ <para>If you need to integrate with existing identity
+ systems (LDAP, Active Directory, NTLM, X.509, etc.), then
+ an Apache-based server is your only real option.
+ Similarly, if you absolutely need server-side logs of
+ either server errors or client activities, then an
+ Apache-based server is required.</para>
+ </listitem>
+
+ <listitem>
+ <para>If you've decided to use either Apache or stock
+ <command>svnserve</command>, create a
+ single <literal>svn</literal> user on your system, and
+ run either Apache or svnserve as that user. Be sure to
+ make the repository directory wholly owned by
+ the <literal>svn</literal> user as well. These keeps the
+ repository data nicely siloed and protected by operating
+ system filesystem permissions, changeable by only the
+ Subverion server process itself.</para>
+ </listitem>
+
+ <listitem>
+ <para>If you have an existing infrastructure heavily based
+ on SSH accounts, and if your users already have system
+ accounts on your server machine, then it makes sense to
+ deploy an svnserve-over-ssh solution. Otherwise, we don't
+ recommend this option to the general public. It's
+ generally considered safer to have your users access the
+ repository via (imaginary) accounts managed
+ by <command>svnserve</command> or Apache, rather than by
+ full-blown system accounts. If your deep desire for
+ encrypted communication still draws you to this option, we
+ recommend using Apache with SSL instead.</para>
+ </listitem>
+
+ <listitem>
+ <para>Do <emphasis>not</emphasis> be seduced by the simple
+ idea of having all of your users access a repository
+ directly via <literal>file:///</literal> URLs. Even if
+ the repository is readily available to everyone via
+ network share, this is a bad idea. It removes any layers
+ of protection between the users and the repository: users
+ can accidentally (or intentionally) corrupt the repository
+ database, it becomes hard to take the repository 'offline'
+ for inspection or upgrade, and it can lead to a mess of
+ file-permissions problems (see
+ <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
+ the same as local users accessing
+ via <literal>file:///</literal>, and can entail all the
+ same problems if the administrator isn't careful.)</para>
+ </listitem>
+ </itemizedlist>
+
+ </sect2>
+
</sect1>
<!-- ================================================================= -->
@@ -497,37 +767,10 @@
back to the client. When <command>svnserve</command> is
invoked by a tunnel agent like this, be sure that the
authenticated user has full read and write access to the
- repository database files. (See <xref
- linkend="svn.serverconfig.svnserve.invoking.sb-1"/>.) It's essentially the same as
+ repository database files. It's essentially the same as
a local user accessing the repository via
<literal>file:///</literal> URLs.</para>
- <sidebar id="svn.serverconfig.svnserve.invoking.sb-1">
- <title>Servers and Permissions: A Word of Warning</title>
-
- <para>First, remember that a Subversion repository is a
- collection of database files; any process which accesses the
- repository directly needs to have proper read and write
- permissions on the entire repository. If you're not
- careful, this can lead to a number of headaches, especially
- if you're using a Berkeley DB database rather than FSFS. Be
- sure to read <xref linkend="svn.serverconfig.multimethod"/>.</para>
-
- <para>Secondly, when configuring <command>svnserve</command>,
- Apache <command>httpd</command>, or any other server
- process, keep in mind that you might not want to launch the
- server process as the user <literal>root</literal> (or as
- any other user with unlimited permissions). Depending on
- the ownership and permissions of the repositories you're
- exporting, it's often prudent to use a
- different—perhaps custom—user. For example,
- many administrators create a new user named
- <literal>svn</literal>, grant that user exclusive ownership
- and rights to the exported Subversion repositories, and only
- run their server processes as that user.</para>
- </sidebar>
-
-
<para>Once the <command>svnserve</command> program is running,
it makes every repository on your system available to the
network. A client needs to specify an
@@ -715,22 +958,31 @@
auth-access = write
</screen>
- <para>Notice that <command>svnserve</command> only understands
- <quote>blanket</quote> access control. A user either has
- universal read/write access, universal read access, or no
- access. There is no detailed control over access to
- specific paths within the repository. For many projects and
- sites, this level of access control is more than adequate.
- However, if you need per-directory access control, you'll
- need to use either use Apache with
- <command>mod_authz_svn</command> (see <xref
- linkend="svn.serverconfig.httpd.authz.perdir"/>) or use a
- <command>pre-commit</command> hook script to control write
- access (see <xref linkend="svn.reposadmin.create.hooks"/>). The
- Subversion distribution comes with
- <command>commit-access-control.pl</command> and the more
- sophisticated <command>svnperms.py</command> scripts for use
- in pre-commit scripts.</para>
+ <para>The server process not only understands
+ these <quote>blanket</quote> access controls to the
+ repository, but also finer-grained access restrictions placed
+ on specific files and directories within the repository. To
+ make use of this feature, you need to define a file containing
+ more detailed rules, and then set
+ the <literal>authz-db</literal> variable to point to it:</para>
+
+ <screen>
+[general]
+password-db = userfile
+realm = example realm
+
+# Specific access rules for specific locations
+authz-db = authzfile
+</screen>
+
+ <para>The syntax of the <filename>authzfile</filename> file is
+ discussed in detail in
+ <xref linkend="svn.serverconfig.pathbasedauthz"/>. Note
+ that the <literal>authz-db</literal> variable isn't mutually
+ exclusive with the <literal>anon-access</literal>
+ and <literal>auth-access</literal> variables; if all the
+ variables are defined at once, then <emphasis>all</emphasis>
+ of the rules must be satisfied before access is allowed.</para>
</sect3>
</sect2>
@@ -817,7 +1069,13 @@
still be used to block access, by simply setting
<literal>auth-access = read</literal> or <literal>auth-access
= none</literal>.</para>
-
+ <footnote>
+ <para>Note that using any sort
+ of <command>svnserve</command>-enforced access control at
+ all is a bit pointless; the user already has direct access to
+ the repository database.</para>
+ </footnote>
+
<para>You'd think that the story of SSH tunneling would end
here, but it doesn't. Subversion allows you to create custom
tunnel behaviors in your run-time <filename>config</filename>
@@ -1238,11 +1496,11 @@
the name you use as the hostname of your server. Generally,
you can use the <literal>ServerName</literal> directive in
<filename>httpd.conf</filename> to accomplish this.</para>
-
+
<screen>
ServerName svn.example.com
</screen>
-
+
<para>If you are using Apache's virtual hosting support via
the <literal>NameVirtualHost</literal> directive, you may
need to use the <literal>ServerAlias</literal> directive to
@@ -1260,8 +1518,8 @@
appropriately, that allows Apache to work with those files.
Apache, when used as a Subversion server, will also need the
correct permissions to read and write to your Subversion
- repository. (See <xref linkend="svn.serverconfig.svnserve.invoking.sb-1"/>.)</para>
-
+ repository.</para>
+
<para>You will need to determine a permission system setup that
satisfies Subversion's requirements without messing up any
previously existing web page or script installations. This
@@ -1791,162 +2049,12 @@
</Location>
</programlisting>
</example>
-
- <para>Once your basic <literal>Location</literal> block is
- configured, you can create an access file and define some
- authorization rules in it.</para>
-
- <para>The syntax of the access file is the same familiar one
- used by <command>svnserve.conf</command> and the runtime
- configuration files. Lines that start with a hash
- (<literal>#</literal>) are ignored. In its simplest form,
- each section names a repository and path within it, and the
- authenticated usernames are the option names within each
- section. The value of each option describes the user's
- level of access to the repository path: either
- <literal>r</literal> (read-only) or <literal>rw</literal>
- (read-write). If the user is not mentioned at all, no
- access is allowed.</para>
-
- <para>To be more specific: the value of the section-names are
- either of the form <literal>[repos-name:path]</literal> or
- the form <literal>[path]</literal>. If you're using the
- <literal>SVNParentPath</literal> directive, then it's
- important to specify the repository names in your sections.
- If you omit them, then a section like
- <literal>[/some/dir]</literal> will match the path
- <filename>/some/dir</filename> in <emphasis>every</emphasis>
- repository. If you're using the <literal>SVNPath</literal>
- directive, however, then it's fine to only define paths in
- your sections—after all, there's only one
- repository.</para>
-
- <screen>
-[calc:/branches/calc/bug-142]
-harry = rw
-sally = r
-</screen>
-
- <para>In this first example, the user <literal>harry</literal> has
- full read and write access on the
- <filename>/branches/calc/bug-142</filename> directory in the
- <literal>calc</literal> repository, but the user
- <literal>sally</literal> has read-only access. Any other
- users are blocked from accessing this directory.</para>
-
- <para>Of course, permissions are inherited from
- parent to child directory. That means that we can specify a
- subdirectory with a different access policy for
- Sally:</para>
-
- <screen>
-[calc:/branches/calc/bug-142]
-harry = rw
-sally = r
-
-# give sally write access only to the 'testing' subdir
-[calc:/branches/calc/bug-142/testing]
-sally = rw
-</screen>
-
- <para>Now Sally can write to the <filename>testing</filename>
- subdirectory of the branch, but can still only read other
- parts. Harry, meanwhile, continues to have complete
- read-write access to the whole branch.</para>
-
- <para>It's also possible to explicitly deny permission to
- someone via inheritance rules, by setting the username
- variable to nothing:</para>
-
- <screen>
-[calc:/branches/calc/bug-142]
-harry = rw
-sally = r
-
-[calc:/branches/calc/bug-142/secret]
-harry =
-</screen>
-
- <para>In this example, Harry has read-write access to the
- entire <filename>bug-142</filename> tree, but has absolutely no
- access at all to the <filename>secret</filename>
- subdirectory within it.</para>
-
- <para>The thing to remember is that the most specific path
- always matches first. The <command>mod_authz_svn</command>
- module tries to match the path itself, and then the parent
- of the path, then the parent of that, and so on. The net
- effect is that mentioning a specific path in the accessfile
- will always override any permissions inherited from parent
- directories.</para>
-
- <para>By default, nobody has any access to the repository at
- all. That means that if you're starting with an empty file,
- you'll probably want to give at least read permission to all
- users at the root of the repository. You can do this by
- using the asterisk variable (<literal>*</literal>), which
- means <quote>all users</quote>:</para>
-
- <screen>
-[/]
-* = r
-</screen>
-
- <para>This is a common setup; notice that there's no
- repository name mentioned in the section name. This makes
- all repositories world readable to all users, whether you're
- using <literal>SVNPath</literal> or
- <literal>SVNParentPath</literal>. Once all users have
- read-access to the repositories, you can give explicit
- <literal>rw</literal> permission to certain users on specific
- subdirectories within specific repositories.</para>
-
- <para>The asterisk variable (<literal>*</literal>) is also
- worth special mention here: it's the
- <emphasis>only</emphasis> pattern which matches an anonymous
- user. If you've configured your <literal>Location</literal>
- block to allow a mixture of anonymous and authenticated
- access, all users start out accessing Apache anonymously.
- <command>mod_authz_svn</command> looks for a
- <literal>*</literal> value defined for the path being
- accessed; if it can't find one, then Apache demands real
- authentication from the client.</para>
-
- <para>The access file also allows you to define whole groups
- of users, much like the Unix <filename>/etc/group</filename>
- file:</para>
-
- <screen>
-[groups]
-calc-developers = harry, sally, joe
-paint-developers = frank, sally, jane
-everyone = harry, sally, joe, frank, sally, jane
-</screen>
-
- <para>Groups can be granted access control just like users.
- Distinguish them with an <quote>at</quote> (<literal>@</literal>)
- prefix:</para>
-
- <screen>
-[calc:/projects/calc]
- at calc-developers = rw
-
-[paint:/projects/paint]
- at paint-developers = rw
-jane = r
-</screen>
-
- <para>Groups can also be defined to contain other
- groups:</para>
-
- <screen>
-[groups]
-calc-developers = harry, sally, joe
-paint-developers = frank, sally, jane
-everyone = @calc-developers, @paint-developers
-</screen>
- <para>…and that's pretty much all there is to it.</para>
+ <para>Once you've settled on one of these three
+ basic <filename>httpd.conf</filename> templates, you need to
+ create your file containing access rules for particular
+ paths within the repository. This is described in
+ <xref linkend="svn.serverconfig.pathbasedauthz"/>.</para>
</sect3>
@@ -2173,6 +2281,242 @@
</sect1>
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <sect1 id="svn.serverconfig.pathbasedauthz">
+
+ <title>Path-Based Authorization</title>
+
+ <para>Both Apache and <command>svnserve</command> are capable of
+ granting (or denying) permissions to users. Typically this is
+ done over the entire repository: a user can read the repository
+ (or not), and she can write to the repository (or not). It's
+ also possible, however, to define finer-grained access rules.
+ One set of users may have permssion to write to a certain
+ directory in the repository, but not others; another directory
+ might not even be readable by all but a few special
+ people.</para>
+
+ <para>Both servers use a common file format to describe these
+ path-based access rules. In the case of Apache, one needs to
+ load the <command>mod_authz_svn</command> module and then add
+ the <literal>AuthzSVNAccessFile</literal> directive (within
+ the <filename>httpd.conf</filename> file) pointing to your own
+ rules-file. (For a full explanation, see
+ <xref linkend="svn.serverconfig.httpd.authz.perdir"/>.) If
+ you're using <command>svnserve</command>, then you need to make
+ the <literal>authz-db</literal> variable
+ (within <filename>svnserve.conf</filename>) point to your
+ rules-file.</para>
+
+ <sidebar>
+ <title>Best practice: do you really need path-based access
+ control?</title>
+
+ <para>A lot of administrators setting up Subversion for the
+ first time tend to jump into path-based access control without
+ giving it a lot of thought. The administrator usually knows
+ which teams of people are working on which projects, so it's
+ easy to jump in and grant certain teams access to certain
+ directories and not others. It seems like a natural thing,
+ and it appeases the administrator's desire to maintain tight
+ control of the repository.</para>
+
+ <para>Note, though, that there are often invisible costs
+ associated with this feature. Most of the time, while certain
+ users <emphasis>shouldn't</emphasis> be committing changes to
+ certain parts of the repository, that social contract doesn't
+ need to be technologically enforced. Teams can sometimes
+ spontaneously collaborate with each other; someone may want to
+ help someone else out by committing to an area she doesn't
+ normally work on. By preventing this sort of thing at the
+ server level, you're setting up barriers to unexpected
+ collaboration. You're also creating a bunch of rules that
+ need to be maintained as projects develop, new users are
+ added, and so on. It's a bunch of extra work to maintain.</para>
+
+ <para>Remember that this is a version control system! Even if
+ somebody accidentally commits a change to something they
+ shouldn't, it's easy to undo the change. And if a user
+ commits to the wrong place with deliberate malice, then it's a
+ social problem anyway, and that the problem needs to be dealt
+ with outside of Subversion.</para>
+
+ <para>So before you begin restricting users' access rights, ask
+ yourself if there's a real, honest need for this, or if it's
+ just something that <quote>sounds good</quote> to an
+ administrator. Remember that there's very little risk
+ involved, and that it's bad to become dependent on technology
+ as a crutch for social problems.<footnote><para>A common theme
+ in this book!</para></footnote>.</para>
+
+ <para>As an example to ponder, consider that the Subversion
+ project itself has always a notion of who is allowed to commit
+ where, but it's always been enforced socially. This is a good
+ model of community trust, especially for open-source projects.
+ Of course, sometimes there <emphasis>are</emphasis> truly
+ legitimate needs for path-based access control; within
+ corporations, for example, certain types of data really can be
+ sensitive, and access needs to be genuinely restricted to
+ small groups of people.</para>
+
+ </sidebar>
+
+ <para>Once your server knows where to find your rules-file, it's
+ time to define the rules.</para>
+
+ <para>The syntax of the file is the same familiar one used
+ by <command>svnserve.conf</command> and the runtime
+ configuration files. Lines that start with a hash
+ (<literal>#</literal>) are ignored. In its simplest form, each
+ section names a repository and path within it, and the
+ authenticated usernames are the option names within each
+ section. The value of each option describes the user's level of
+ access to the repository path: either
+ <literal>r</literal> (read-only) or <literal>rw</literal>
+ (read-write). If the user is not mentioned at all, no access is
+ allowed.</para>
+
+ <para>To be more specific: the value of the section-names are
+ either of the form <literal>[repos-name:path]</literal> or the
+ form <literal>[path]</literal>. If you're using the
+ <literal>SVNParentPath</literal> directive, then it's important
+ to specify the repository names in your sections. If you omit
+ them, then a section like
+ <literal>[/some/dir]</literal> will match the path
+ <filename>/some/dir</filename> in <emphasis>every</emphasis>
+ repository. If you're using the <literal>SVNPath</literal>
+ directive, however, then it's fine to only define paths in your
+ sections—after all, there's only one repository.</para>
+
+ <screen>
+[calc:/branches/calc/bug-142]
+harry = rw
+sally = r
+</screen>
+
+ <para>In this first example, the user <literal>harry</literal> has
+ full read and write access on the
+ <filename>/branches/calc/bug-142</filename> directory in the
+ <literal>calc</literal> repository, but the user
+ <literal>sally</literal> has read-only access. Any other users
+ are blocked from accessing this directory.</para>
+
+ <para>Of course, permissions are inherited from parent to child
+ directory. That means that we can specify a subdirectory with a
+ different access policy for Sally:</para>
+
+ <screen>
+[calc:/branches/calc/bug-142]
+harry = rw
+sally = r
+
+# give sally write access only to the 'testing' subdir
+[calc:/branches/calc/bug-142/testing]
+sally = rw
+</screen>
+
+ <para>Now Sally can write to the <filename>testing</filename>
+ subdirectory of the branch, but can still only read other parts.
+ Harry, meanwhile, continues to have complete read-write access
+ to the whole branch.</para>
+
+ <para>It's also possible to explicitly deny permission to someone
+ via inheritance rules, by setting the username variable to
+ nothing:</para>
+
+ <screen>
+[calc:/branches/calc/bug-142]
+harry = rw
+sally = r
+
+[calc:/branches/calc/bug-142/secret]
+harry =
+</screen>
+
+ <para>In this example, Harry has read-write access to the
+ entire <filename>bug-142</filename> tree, but has absolutely no
+ access at all to the <filename>secret</filename> subdirectory
+ within it.</para>
+
+ <para>The thing to remember is that the most specific path always
+ matches first. The <command>mod_authz_svn</command> module
+ tries to match the path itself, and then the parent of the path,
+ then the parent of that, and so on. The net effect is that
+ mentioning a specific path in the accessfile will always
+ override any permissions inherited from parent
+ directories.</para>
+
+ <para>By default, nobody has any access to the repository at all.
+ That means that if you're starting with an empty file, you'll
+ probably want to give at least read permission to all users at
+ the root of the repository. You can do this by using the
+ asterisk variable (<literal>*</literal>), which means <quote>all
+ users</quote>:</para>
+
+ <screen>
+[/]
+* = r
+</screen>
+
+ <para>This is a common setup; notice that there's no repository
+ name mentioned in the section name. This makes all repositories
+ world readable to all users, whether you're
+ using <literal>SVNPath</literal> or
+ <literal>SVNParentPath</literal>. Once all users have
+ read-access to the repositories, you can give explicit
+ <literal>rw</literal> permission to certain users on specific
+ subdirectories within specific repositories.</para>
+
+ <para>The asterisk variable (<literal>*</literal>) is also worth
+ special mention here: it's the
+ <emphasis>only</emphasis> pattern which matches an anonymous
+ user. If you've configured your <literal>Location</literal>
+ block to allow a mixture of anonymous and authenticated access,
+ all users start out accessing Apache anonymously.
+ <command>mod_authz_svn</command> looks for a
+ <literal>*</literal> value defined for the path being accessed;
+ if it can't find one, then Apache demands real authentication
+ from the client.</para>
+
+ <para>The access file also allows you to define whole groups of
+ users, much like the Unix <filename>/etc/group</filename>
+ file:</para>
+
+ <screen>
+[groups]
+calc-developers = harry, sally, joe
+paint-developers = frank, sally, jane
+everyone = harry, sally, joe, frank, sally, jane
+</screen>
+
+ <para>Groups can be granted access control just like users.
+ Distinguish them with an <quote>at</quote>
+ (<literal>@</literal>) prefix:</para>
+
+ <screen>
+[calc:/projects/calc]
+ at calc-developers = rw
+
+[paint:/projects/paint]
+ at paint-developers = rw
+jane = r
+</screen>
+
+ <para>Groups can also be defined to contain other groups:</para>
+
+ <screen>
+[groups]
+calc-developers = harry, sally, joe
+paint-developers = frank, sally, jane
+everyone = @calc-developers, @paint-developers
+</screen>
+
+ <para>…and that's pretty much all there is to it.</para>
+
+ </sect1>
+
<!-- ================================================================= -->
<!-- ================================================================= -->
More information about the svnbook-dev
mailing list