summaryrefslogtreecommitdiff
path: root/about/what-is.mdwn
blob: a03a5aa07f8f88e267025109d2fb77b727c0da61 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
[[!meta title="What is Gitano?"]]

<!-- The elevator pitch -->

Gitano is a git server
providing user separation
with ssh keys or passwords
with access rules defined in customisable ACLs
and maximally sandboxed hooks written in Lua
with this configuration stored in git repositories
for both global and per-repository configuration
with additional server-side commands for easier administration
accessible over the git, http and ssh transport protocols.

<!-- More in-depth description of features -->

# …is a git server providing user separation with ssh keys or passwords…

Git servers implement the `git-{receive,upload}-pack` commands
when accessed over ssh,
handle requests to `/info/refs?service=git-{upload,receive}-pack`
when accessed over http,
and the bespoke protocol of the git transport.

Gitano implements the ssh interface by generating a `.ssh/authorized_keys` file
for all the permitted ssh keys
that specifies a proxy command that is told which user the key belonged to,
and which determines if the user is permitted to run the requested command
before running the appropriate git operation.

Gitano implements the http interface by providing `gitano-smart-http.cgi`
which the system administrator configures their web server to run,
and which authenticates the user based on a generated htpasswd file,
then determines whether the authenticated user is permitted to run the service,
before handing it off to `git-http-backend`.

Gitano supports the git interface by generating `git-daemon-export-ok` files
for every repository that the anonymous user is permitted to read.
The protocol implementation is left to the `git-daemon` functionality
which is built into `git`.

# …access rules defined as customisable ACLs…

All Gitano commands consult ACLs written in [lace][]
to determine whether the operation is permitted.

Existing git operations have ACLs applied by a hook installed by Gitano.

This allows a Gitano administrator to define rules
that permit delegation of roles to different users.

If those roles are defined by group membership
and the ability to add a user to a group is delegated
then the permission to grant permissions can also be delegated.

[lace]: https://www.gitano.org.uk/lace/

# …maximally sandboxed hooks written in Lua…

In addition to installing hooks to provide ACL checking for git operations,
these hooks will also run hook code, written in Lua, in a [supple][] sandbox,
such that it is safe to run semi-trusted code contributed by users
for purposes such as notifying web services of a repository update.

[supple]: https://www.gitano.org.uk/supple/

# …configuration stored in git for global and per-repository configuration…

Gitano reads the majority of its configuration
from the master branch of the `gitano-admin.git` repository
in the set of repositories it manages access to.

For operations performed on a specific repository
it reads configuration from that repository's `refs/gitano/admin` branch.

ACLs stored in `gitano-admin.git` are supplemented from `refs/gitano/admin`
so users may add their own access restrictions.

Any hooks defined in `gitano-admin.git` (i.e. a global hook) get called
with a per-repo hook as a parameter if defined in `refs/gitano/admin`,
so the global hook may decide whether to suppress or call the per-repo hook.
If a global hook is not defined then per-repo hooks are called if defined.

Users, their ssh keys, groups and GPG keys
are only loaded from the `gitano-admin.git` repository.

By putting the configuration of Gitano in repositories managed by Gitano
it is easy to make a backup of configuration with the data
by mirroring the repository content.
Configuration gains the same traceability guarantees as git history
and can be access controlled with the same mechanism as the data.

# …server side commands for easier administration…

Management of git repositories isn't naturally part of the git protocol,
so commands for creating and deleting repositories need to be added
so that you don't need a shell account on the machine to manage repositories.

Additionally operations that may be performed
by making changes to the `gitano-admin.git` repository
may also be done with the command-line,
which is significantly quicker and more scriptable than pushing changes.

<!-- Gitano lets you delegate CLI interface management
     but does not parse changes to gitano-admin to see what they do
     and then run ACLs to see whether the user is permitted to do so -->