docs/concepts.mkd

   1 # concepts, conventions, and terminology
   2
   3 ----
   4
   5 <span class="box-r">(I assume you're at least somewhat familiar with **git**
   6 itself.  If not, the ["before you start..."][req] page has a list of topics
   7 that you need to be familiar with, in order to use gitolite.)</span>
   8
   9 [req]: install#before-you-start-pre-requisites
  10
  11 This page will help newcomers get used to what we're talking about elsewhere.
  12 It also explains the special `gitolite-admin` repo and how it is used to do te
  13 day-to-day management of a gitolite server.
  14
  15 # authentication and authorisation
  16
  17 <span class="red">**Gitolite does not do authentication.  It only does
  18 authorisation.**</span>
  19
  20 So let's loosely define these words:
  21
  22 >   **Authentication** is the process of verifying that you are who you claim
  23 >   to be.  An authentication system will establish that I am the user
  24 >   "sitaram" on my work system.  The one behind gmail will similarly
  25 >   establish that I am "sitaramc".  And so on...
  26
  27 >   **Authorisation** is the process of asking what you want to do and
  28 >   deciding if you're allowed to do it or not.
  29
  30 When you install gitolite, your users will authenticate themselves to your
  31 server's "sshd" (ssh daemon) **or** to your web server.  If authentication
  32 succeeds, sshd or httpd will pass control to gitolite, which then performs the
  33 authorisation check -- i.e., figure out whether to allow you to do whatever it
  34 is you want to whatever repo you decided to touch.
  35
  36 # ssh mode and http mode
  37
  38 Git allows authenticated remote access using these two mechanisms: ssh and
  39 http.  Gitolite supports both.
  40
  41 Ssh mode is much easier to install and setup; most systems already have
  42 whatever you need, and -- except for creating the "hosting user" -- you don't
  43 need to do anything as root.  However, your users have to generate an ssh
  44 keypair for themselves (using "ssh-keygen") if they don't already have a
  45 keypair, and they have to send you the public key (the file ending in ".pub"),
  46 which you add to gitolite.
  47
  48 Http mode requires a bit more work in terms of setting things up.  Once setup,
  49 however, it may be a little easier for your users.  Authentication is by
  50 username + password, which, although much less secure than ssh keypairs, is
  51 conceptually easier for users.
  52
  53 # The "hosting user"
  54
  55 <span class="box-r">If you're wondering how it distinguishes between different
  56 users when they are all logging into "git", [this page](glssh) has answers!</span>
  57
  58 When you install gitolite in ssh mode, you pick one specific user on the Unix
  59 system to be the "hosting user".  This is the user whose name goes into the
  60 repo URLs your users will be cloning, for example `ssh://git@server/repo`, or
  61 the simpler form `git@server:repo`.
  62
  63 *Usually*, this is "git", and that is what we assume in this documentation.
  64 However, it can actually be any user on the system, and I think both the
  65 Fedora RPM and the Debian DEB use "gitolite", so adjust instructions and
  66 examples accordingly.  **Unless otherwise stated, everything that we do "on
  67 the server" is done in this userid (for ssh mode installations).**
  68
  69 Of course you can have any number of "hosting users", but that's rare.
  70
  71 # the "logical repo name"
  72
  73 Gitolite refers to repos using a logical repo name, which is whatever name you
  74 specified in the gitolite.conf file (described later).  The actual repo will
  75 be in `$HOME/repositories`, and will have a ".git" suffix.  So, for example,
  76 the logical repo name "foo" will be `$HOME/repositories/foo.git` on disk, and
  77 "bar/baz" will be `$HOME/repositories/bar/baz.git`.  The logical repo name is
  78 what you must use for all interactions with gitolite (within the conf file,
  79 repo name arguments to gitolite commands or API functions, etc.) unless
  80 specifically documented otherwise.
  81
  82 One exception: you're allowed to add the ".git" extension in git commands
  83 (clone, fetch, push, ls-remote, archive) if you wish, because git itself
  84 allows it, and we'd like to be as transparent as possible.  The
  85 `$HOME/repositories` prefix should never be specified.  If you do specify it,
  86 and things appear to work, [something is wrong!][ybpfail].
  87
  88 [ybpfail]: sts#appendix-5-why-bypassing-gitolite-causes-a-problem
  89
  90 # the special gitolite-admin repo
  91
  92 Gitolite manages git repos.  Among them is a repo called "gitolite-admin",
  93 which is a very special repository that helps you add and remove users and
  94 repos, as well as define access rules for them. **Most day-to-day management
  95 of gitolite is done by cloning this repository, making changes to it, and
  96 pushing the changes back to the server.**
  97
  98 Specifically, it contains a directory called "keydir", in which you place
  99 files with names like "alice.pub", "bob.pub", etc.  These are the public keys
 100 of you and your users.  (Of course this applies only to ssh mode).
 101
 102 It also contains a file called "conf/gitolite.conf", in which you add access
 103 rules specifying who gets what level of access to each repo.  Here's a simple
 104 example:
 105
 106 ```gitolite
 107 # these lines were already in the file
 108 repo foo
 109     RW+     =   alice
 110     RW      =   bob
 111
 112 # these lines were added just now
 113 repo bar
 114     RW+     =   bob
 115     R       =   alice
 116 ```
 117
 118 ----
 119
 120 Here's what happens when you commit the changes/additions to these files and
 121 push them to the server.  Since we've already seen the ssh/sshd part of this
 122 process (in the [overview](overview.mkd) page), we'll start off from
 123 "git-receive-pack":
 124
 125 ![](ct02.png)
 126
 127 1.  The `gitolite-admin` repo has a special `post-update` hook, installed by
 128     gitolite, which is invoked by `git-receive-pack`.  This is how gitolite gets
 129     in on the action.
 130
 131 2.  Gitolite looks at the keys in keydir, and updates ssh's authorized keys
 132     file using those keys, so ssh knows who the valid users are.  A ton of
 133     detail about this is in the [ssh pages](ssh).
 134
 135 3.  It then updates some internal files in `~/.gitolite`
 136
 137 4.  For new repositories (repos that do not exist in `~/repositories`, but are
 138     mentioned in `conf/gitolite.conf`), it **creates** the repository.
 139
 140 5.  For each repository, it updates a special file inside the repository that
 141     contains the rules pertaining to that repository.
 142
 143 And that, boys and girls, is how gitolite does its thing.  That is also why
 144 you should NEVER touch any of those files yourself, unless you know what
 145 you're doing!
 146