path: root/doc/admin/000.mdwn

---
title: Gitano Admininistration
author: Lars Wirzenius and the Gitano project
date: unversioned for now
...

**NOTA BENE:** This is very much a work in progress. Tread carefully.

# Introduction

This document describes what a "Gitano admin" needs to know. Gitano
admins are reponsible for setting the policy of a Gitano installation:
who can access it, what they can do, what they can't do, and so on.
The target audience of this document is those who are members of the
`gitano-admin` group in a Gitano installation. We assume they know how
to use Gitano as a user already, and are comfortable editing plain
text files and using git to manage files.

This document is not about installing Gitano or configuring it to work
on a system.

# Overview

Gitano admins primarily enable people to do their jobs. This involves:

* define Gitano access control rules using Lace
* add and remove Gitano users
* helping people with their Gitano problems
* 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
is a fairly simple textual language for expressing what actions Gitano
users can and can't do.

# User and group management

FIXME. This chapter discusses managing users, groups inside Gitano,
including ssh key management.

# Repository management

FIXME. This chapter discusses repository management, including
repository config variables.

# Lace syntax and semantics

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").

## The initial ruleset

When a Gitano instance is installed and configured by the sysadmin, a
repository called `gitano-admin` is automatically created. This
repository contains administrative information for the Gitano
instance:

* Site metadata: name, output prefix.
* Which users are created in Gitano, including any metadata about them
  (name, ssh keys).
* Ditto for groups.
* Lace rulesets for access control.

The Lace ruleset is in the directory `rules` in `gitano-admin`. A
default ruleset is inserted when the Gitano instance is created. Many
Gitano sites can just use that, but it is simplistic, and so it may be
worth adjusting it for your needs.

The root of the ruleset is in `rules/core.lace`. We will have a
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
user to do anything to a repository prefixed by their username.

    define repo_is_usernamed repository prefix ${user}/
    allow "Users can create repos beginning with their username" repo_is_usernamed

Lace rules are used by Gitano whenever the user tries to do anything.
Note that they only apply for access to the repositories via Gitano
(i.e., over the ssh protocol), and do not apply when access is via
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
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:

    define user_is_cat user cat
    define user_is_dog user dog
    allow "Cats are cool" user_is_cat
    deny "Dogs drool too much" user_is_dog

The `define` statements define macros to simplify the conditions.
This is useful for more complicated things. For simpler things, like
the example above, you could write the condition directly into the
allow/deny statements:

    allow "Cats are cool" [user cat]
    deny "Dogs drool too much" [user dog]

What happens if user is neiter 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`
statement:

    default deny "The ruleset didn't provide access. Denying by default."

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.

## Lace language summary

The Lace language consists of the following constructs:

* `allow` and `deny` statements, with conditionals.
* Boolean expressions used in allow/deny statements.
* Macro definitions for boolean expressions, for making clearer
  conditionals.
* Includes to allow a ruleset to be split into multiple files.

The allow/deny statements look like this:

    allow "Everyone can see who they are" [operation whoami]
    deny "No more repos" [operation createrepo]

In other words, the action (`allow` or `deny`), a message shown to the
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 whoami` and `operation createrepo`. These use the operator
`operation`, which takes one argument, and evaluates to true if the
user is trying to do that operation. Operation, operation, operation.

## Predicates in conditions

Gitano defines a number of predicates to be used in conditions. See table.

Table: Gitano predicates

----------------------  -----------
`operation`             name of operation (gitano command)
`owner`                 username of repository owner
`group`                 groups of invoker of gitano or target of `as`
`ref`                   the ref (branch, tag) being operated on
`user`                  username of user invoking gitano, or target of `as`
`repository`            path of repository being operated on
`repository/basename`   the basename part of a repository
`repository/dirname`    all but the basename part of a repository
`start_tree`            to do with trees and tree changes during
`target_tree`           ... update hook tests, to be documented
`treediff/targets`      ... later (FIXME)
`treediff/added`        ...
`treediff/deleted`      ...
`treediff/modified`     ...
`treediff/renamed`      ...
`treediff/renamedto`    ...
`as_user`               username of user invoking `as otheruser`
`as_group`              groups of user invoking `as otheruser`
`targetuser`            username in a user manipulation command
`targetgroup`           the group in a group manipulation command
`targetgroup/prefix`    FIXME
`targetgroup/suffix`    FIXME
`member`                the user in an group manipulation command
`member/prefix`         FIXME
`member/suffix`         FIXME
----------------------  -----------


Predicates can be combined using the operators `anyof` and `allof`:

    allow "Mammals are cool" anyof [user cat] [user dog]

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.

The result of a condition may be negated with the boolean NOT
operation (`!`):

    deny "Only cats" ![user cat]

## Variables for conditions

Gitano defines a number of variables to be used in conditions. See
table. These provide values that predicates test. The list of values
depends on the operation being run. FIXME: Need help from Daniel to
complete a table.

Table: Gitano variables

---------   --------        -------------------------------------------
operation   variable        description
all         user            Current Gitano user
all         group           Current Gitano group
most        repository      Which repository is being operated on
---------   --------        -------------------------------------------


## Include statements in rulesets

A Lace statement may include another rules file. The search path is as
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/foo.lace` from the adminref.

* Otherwise, without the global prefix, it seems to be included
  relative to the including file. FIXME: But it's always included from
  adminref? What do I not get?

FIXME: What about per-project rules?

## Testing one's ruleset

META: This section discusses systematic testing of one's ruleset.
Might or might not include automated testing (with yarn).

# The default Gitano ruleset

META: This chapter is a walkthrough of the default Gitano ruleset.
Ideally implemented in such a way that it is either generated from the
Gitano source code, or vice versa.

# Good practices for writing rulesets

META: This chapter discusses various best practices for writing Gitano
rulesets. It may initially have to be a skeleton until the Gitano
community gathers enough experience to write something substantial.
But an interview with Daniel for good ideas should come up with enough
for an initial chapter.

# Common things one may want to do

META: This chapter discusses some common changes one may want to do to
the default ruleset. Ideally, there would be none, but reality is ugly.

## Anonymous access

META: This section describes how to allow anyone access to specific
repositories.

## Cgit integration

META: This section describes how to allow cgit show specific
repositories.

# Backup and restore of a Gitano instance

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 instnace, backup `/home/git`. To restore, restore
the directory. 

FIXME: Need to re-generate .ssh/authorizes_keys?