Improve README

diff --git a/README b/README
index bdc6cb9245c27b1b4dbf5bac4fe8aaace6c1a96b..0ec46bb50d9d0058bc177bbf9456b2992ad44ba0 100644 (file)
--- a/README
+++ b/README
@@ -61,8 +61,8 @@ disabled for such users.
 
 In accordance with the settings in /etc/repo_shell.conf:
 
-    sudo adduser --system --group <owner> --home /var/lib/svn \
-       --shell /bin/false <owner>
+    sudo adduser --system --group --home /var/lib/svn --shell /bin/false <owner>
+    sudo chsh -s /bin/sh <owner> # a shell is needed for 'sudo -iu'
     sudo install -d -o <owner> -g <owner> -m 0750 <svn_root>/..
     sudo install -d -o <owner> -g <owner> -m 0750 <svn_root>
     sudo install -d -o <owner> -g <owner> -m 0750 <git_root>
@@ -70,12 +70,33 @@ In accordance with the settings in /etc/repo_shell.conf:
 = Configure subversion repository ACLs
 
 Subversion repositories created with the svncreate command have their
-conf/svnserve.conf file pointing to the global {svn_root}/../authz.conf file.
-It is this file that is used to set access control permissions for repositories.
-Subversion's authz file allows path based control as well.  For more
-information, please see the Subversion Red Bean guide at:
+conf/svnserve.conf as a symbolic link pointing to the global
+{svn_root}/../svnserve.conf file, which then references internally the global
+authz.conf file.  It is this file that is used to set access control permissions
+for repositories.  Subversion's authz file allows path based control as well.
+For more information, please see the Subversion Red Bean guide at:
 http://svnbook.red-bean.com/en/1.7/svn.serverconfig.pathbasedauthz.html
 
+A simple and secure svnserve.conf file:
+
+    [general]
+    anon-access = none
+    auth-access = write
+    authz-db = /var/lib/svn/authz.conf
+
+A simple and secure authz.conf file:
+
+    [groups]
+    devs = user1, user2, user3
+
+    [/] # All repositories, all paths
+    @devs = rw
+    * =
+
+For path-based controls, consider using the pre-commit hook that uses
+svnperms.py.  The ability to prevent update of tags, which my definition is
+almost always an accident, is itself worth the price of admission.
+
 = Configure git repository ACLs
 
 Git repository access control is managed by the git acl file, located at
@@ -84,6 +105,14 @@ has a format similar but not exactly like Subversion's authz file.  The file
 defines one of three levels of access for various combinations of users and
 repositories, then compared to the git command arriving via SSH to determine if
 the access will be allowed.  Please see README.gitacls for more information.
+A simple .gitacls might look like:
+
+    [user_groups]
+    devs = user1 user2 user3
+
+    [repo *]
+    devs = rw
+    * =
 
 = Create a subversion repository