More admin manual work

1 files changed, 107 insertions, 45 deletions

diff --git a/doc/admin/000.mdwn b/doc/admin/000.mdwn
index 239440d..f70f065 100644
--- a/doc/admin/000.mdwn
+++ b/doc/admin/000.mdwn
@@ -31,29 +31,30 @@ Gitano admins primarily enable people to do their jobs. This involves:
 * Possibly add and remove Git repositories, unless they allow people
   to do that themselves.
 
-Access control to Gitano is defined using a language called Lace. It
+Access control to Gitano is defined using a language called Lace. Lace
 is a fairly simple textual language for expressing what actions Gitano
-users can and can't do.
+users are, and are not, permitted to perform.
 
 # Gitano admin users
 
-Gitano recognises users based on the ssh key they use to log in. Each
-user may have multiple keys, but each key may only be used by one
-user.
+Gitano recognises users based on the ssh key they use to log in. (Gitano is
+also capable of using usernames and passwords though this is typically only
+used over HTTP(s) and is described further on the Gitano Wiki.)  Each user may
+have multiple keys, but each key may only be used by one user.
 
 Gitano administrators need to be in the `gitano-admin` group.
 When a Gitano instance is first created by the sysadmin
 (by running `gitano-setup`), as part of the process an admin user is created.
 This user belongs to the `gitano-admin` group.
 
-It is easiest if the admins have one account that they both for normal
-Gitano use and for doing admin things. However, from a security point
-of view, it is probably better to have a dedicated admin account for
-doing admin stuff. Further, each admin should have their own admin
-account so it's easier to see who did what. This requires the admins
-to have multiple keys, and to configure their ssh so that the right key
-is used for each account. This can be one with stanzas in
-`~/.ssh/config` such as these:
+While it may be easiest if the administrators of a Gitano instance have one
+account that they both for normal Gitano use and for doing admin things, from a
+security point of view, it is probably better to have a dedicated admin account
+for doing admin stuff. Further, each admin should have their own admin account
+on the Gitano instance so that it's easier to see who did what. This requires
+the admins to have multiple keys, and to configure their ssh so that the right
+key is used for each account. This can be one with stanzas in `~/.ssh/config`
+such as these:
 
     Host gitanoadmin
     Hostname git.example.com
@@ -67,15 +68,18 @@ the usual name for the git server:
 
 # User and group management
 
+Managing users and groups is a primary role for Gitano administrators.
+
 Use the commands in the table to manage user and groups. For more
 detail, give Gitano the command `help user` or `help group`.
 
 -------             --------------------------------------------------
 command             description
-`user`              list existing users
+`user list`         list existing users
 `user add`          create a new user
 `user del`          remove a user
-`group `            list existing groups
+`group list`        list existing groups
+`group show`        show the details of a particular group
 `group add`         create a new group
 `group del`         remove a group
 `group desciption`  set description of group
@@ -85,16 +89,17 @@ command             description
 `group delgroup`    remove group from group
 -------             --------------------------------------------------
 
-Typically, groups are used to bestow priviliedges to users. Gitano
+Typically, groups are used to bestow privileges to users. Gitano
 admins are added to the `gitano-admin` group. A site might have a
 group `devs` for all the users who are developers and thus need to be
 able to push changes to source code repositories. The site might also
 have a group `ops`, whose members have read-only access to the source
-code repositories.
+code repositories so that they can deploy the software, while having
+the permission to push changes to their operations repositories.
 
 Creating a site policy such as the above is a job for that site's
-Gitano admins. Gitano comes with a very simplistic policy by default.
-The policy is specified (implemented) using Lace, which we'll cover soon.
+Gitano admins. Gitano comes with a very basic policy by default.
+The policy is specified (implemented) using Lace, which we'll look at later.
 
 
 # Repository management
@@ -104,10 +109,11 @@ Gitano `help` command to get details.
 
 -------             ---------------------------------------------------
 command             description
+`ls`                list the repositories on the Gitano instance
 `create`            create a new, empty repository
 `destroy`           destroy a repository
 `copy`              create a new repoistory by copying an existing one
-`config`            inspect or set repository configurtion
+`config`            inspect or set repository configuration
 -------             ---------------------------------------------------
 
 Configuration variables for repositories are listed in a table.
@@ -121,7 +127,9 @@ variable                description
 -------                 ---------------------------------------------------
 
 You can set any configuration varible, but the `project.*` ones have
-special meaning to Gitano.
+special meaning to Gitano.  In addition if you are using CGit as your web
+interface to your repositories, then `cgitrc.*` end up forwarded to the
+repo stanza in the CGit config.
 
 
 # Lace syntax and semantics
@@ -131,7 +139,9 @@ Lace is a language to describe access control rules for Gitano.
 This chapter describes Lace in some detail. It is example driven:
 rather than starting from a syntax BNF and then describing the
 semantics of each construct, we'll skip the formalism and go through a
-series of examples, starting from a minimal ruleset ("hello, world").
+series of examples.  Note that not every example given here is complete
+and we recommend that you read the `gitano-admin.git::rules/*.lace` files
+to get a good grip on the default ruleset.
 
 ## The initial ruleset
 
@@ -156,7 +166,7 @@ walkthrough later, after we first cover some of the Lace language.
 
 ## First example
 
-The first example is really simplistic. It contains a rule to allow a
+Starting with a fairly simple example, the below contains a rule to allow a
 user to do anything to a repository prefixed by their username.
 
     define repo_is_usernamed repository prefix ${user}/
@@ -169,7 +179,12 @@ other means (e.g., the git protocol itself). When they do apply,
 however, they apply to everything: pulling, pushing, creating
 repositories, etc.
 
-Lace rules are evaluated from top to bottom. A rule consists of a
+Since Lace rules are evaluated from top to bottom, it is very important that
+you not only define your rules well, but also define them in the right place in
+the ruleset.  The first `deny` or `allow` rule which succeeds will immediately
+terminate further rule processing.
+
+When defining rules, you should bear in mind that a rule consists of a
 condition, and either allow or deny access if the condition is true.
 For example, the following two rules will allow access to cats, and
 deny access to dogs:
@@ -187,7 +202,7 @@ allow/deny statements:
     allow "Cats are cool" [user exact cat]
     deny "Dogs drool too much" [user exact dog]
 
-What happens if user is neiter cat nor dog? Neither condition will be
+What happens if user is neither `cat` nor `dog`? Neither condition will be
 true, and so access is neither allowed nor denied by the above ruleset
 snippet. Gitano would continue evaluating further rules. If no rule
 triggers, Gitano uses the default, which is set with the the `default`
@@ -198,7 +213,9 @@ statement:
 If a default isn't set, the opposite of the last statement is used. If
 the last statement is `allow`, but didn't trigger, the default is
 `deny`, and vice versa. This can be confusing, but works OK for very
-short rulesets. For anything else, set an explicit default.
+short rulesets. For anything else, set an explicit default.  In addition,
+once set, the default cannot be overridden later in the ruleset. The initial
+Gitano ruleset begins with the above `default` statement.
 
 ## Lace language summary
 
@@ -220,29 +237,32 @@ user if the action is taken, and a Boolean condition that decides if
 the action should be taken. In the example above, the conditions are
 `operation exact whoami` and `operation exact createrepo`.
 These use the predicate
-`operation`, which takes two arguments:
+`operation`; predicates takes two arguments:
 
 1.  A string comparison operator
 
     This can be one of:
 
     1.  `exact` if the operand must be exactly the same as the value.
-        This makes the most sense for the `operation` operator.
+        This makes the most sense for the `operation` or `user` operators.
         `is` is an alias for `exact`.
     2.  `prefix` if the value must begin with the operand.
         `starts` and `startswith` are aliases for `prefix`.
+        `prefix` is useful for rules about branch namespaces,
+        and may be used for repository namespaces.
     3.  `suffix` if the value must end with the operand.
         `ends` and `endswith` are aliases for `suffix`.
-        `prefix` is often used for branch namespaces,
-        and may be used for repository namespaces.
-    4.  `pattern` if the value must match a lua string match expression.
-    5.  `pcre` if the value must match a perl-compatible regular expression.
+        `suffix` is useful for managing roles as suffixes to group names
+        or defining rules which affect repos of the same name in different
+        folders on the server.
+    4.  `pattern` if the value must match a Lua string match expression.
+    5.  `pcre` if the value must match a Perl-compatible regular expression.
 
     Or one of the above with `!` prepended to invert the result.
 
-2.  The operand to compare against.
+2.  The value to compare against.
 
-In this case our condition evalueates to true
+In this case our condition evaluates to true
 if the user is trying to do that operation.
 
 ## Predicates in conditions
@@ -296,10 +316,10 @@ Predicates can be combined using the operators `anyof` and `allof`:
 
 These operators are followed by a list of conditions, and the result
 is true if any condition, or all conditions, respectively, are true.
-`anyof` is Boolean OR, `allof` is Boolean AND.
+`anyof` is Boolean _OR_, `allof` is Boolean _AND_.
 
-The result of an `allow`, `deny`, `anyof` or `alloff` condition
-may be negated with the boolean NOT operation (`!`):
+The result of an individual condition for `allow`, `deny`, `anyof` or `alloff`,
+may be negated with the boolean _NOT_ operation (`!`):
 
     deny "No cats" ![user exact cat]
 
@@ -317,7 +337,7 @@ depends on the operation being run.
 Table: Gitano variables
 
 ------------ ------------------- -----------------------------------------------------------------------
-operations   variable            description
+Operations   Variable            Description
 all          operation           The current operation being run.
 all          source              Protocol used to interact with Gitano. ("git", "http" or "ssh").
 all          user                Current Gitano user or "gitano/anonymous".
@@ -370,10 +390,12 @@ Since `user` and `config/project/owner` are both predicates and variables
 
     define is_owner user exact ${config/project/owner}
 
-The only constraint to worry about is that variables can't have multiple values.
-So `group` can't be used as a variable, but can be a predicate.
+The only constraint to worry about when deciding if a term should be used as a
+variable or as a predicate is that when expanding, variables can't have
+multiple values.  So `group` can't be used as a variable, but can be a
+predicate.
 
-If you had a config option for the contributors to a project
+If you had a config option which was a list of the contributors to a project
 you would be unable to check it with:
 
     define is_contributor user exact ${config/project/contributors}
@@ -389,7 +411,7 @@ follows:
 
 * If the included filename starts with `global:` it is included from
   the adminref (`master` branch of `gitano-admin.git`), directory
-  `rules`. Thus, `include global:foo.lace` means including
+  `rules`. Thus, `include global:foo` means including
   `rules/foo.lace` from the adminref.
 
 * Otherwise, without the global prefix,
@@ -397,7 +419,7 @@ follows:
   (`refs/gitano-admin` branch of the repository being operated on).
 
 Include statements can be made conditional by adding a predicate after the path,
-so you can split up your rules
+so you can split up your rules:
 
     #main.lace
     include update anyof [operation exact createref] [operation exact deleteref] [operation exact updaterefnonff]  [operation exact updaterefff]
@@ -414,5 +436,45 @@ When gitano-setup is run, the admin needs to specify a Unix user in
 whose home directory the git repositories stored. In this section
 we'll assume the home directory is `/home/git`.
 
-To backup a Gitano instance, backup `/home/git`. To restore, restore
-the directory.
+To backup a Gitano instance, simply backup `/home/git`. To restore, restore
+the directory and ensure the user exists in the system.
+
+# Stability of Gitano's interface
+
+As an administrator, the stability of Gitano's interface is very important to
+understand.
+
+* **Rulesets**: During the v1.x series of releases, Gitano rulesets will
+continue to work and while additional variables or predicates may be added,
+nothing will be removed or renamed entirely unless failing to do so would
+constitute a security risk.  This guarantee is not provided for a move from
+v1.x to v2.x.  or from any v1.n to v.(n-1).
+* **Commands**: The command interface of Gitano is meant for humans to interact
+with, and there is no stability of the command interface defined for the v1.x
+series of Gitano.
+* **Hooks**: The interface between Gitano and hooks is guaranteed to only
+increase in functionality through the v1.x series unless failing to remove or
+incompatibly alter functionality would constitute a security risk.
+* **Plugins**: The plugin interface is considered entirely unstable at this
+time and there is no guarantee that the current interfaces will remain stable
+through the v1.x series.  Any rules, commands, hooks, etc, defined in published
+plugins distributed with Gitano will be subject to the same constraints as
+stated above.
+* **Lua API**: The API of the Gitano Lua modules is an internal implementation
+detail for the purposes of the v1.x series and should not be relied upon to
+remain stable between any two releases in the series.
+
+# Bypassing Gitano security
+
+During setup of a Gitano instance, as well as the initial administrator user,
+the `gitano-setup` tool also created a user called `gitano-bypass`.  The bypass
+user is normally entirely unused, however it would behoove the sysadmin of the
+Gitano instance to understand that to use an SSH key associated with the bypass
+user will result in all rules, hooks, etc. being ignored.  This can cause
+issues if hooks are used to manage effects of changing git repositories;
+however it can also be the only way to correct certain issues (such as if an
+instances' administrators lock themselves out).
+
+Before using the bypass functionality, it is recommended that the sysadmin
+consult the Gitano wiki and also any administrators of the instance to ensure
+that they perform the minimum necessary change to restore access.