Skip to content

Commit

Permalink
lots of doc changes reflecting "push to admin" is default now :)
Browse files Browse the repository at this point in the history 
  - added comments to easy install to help do it manually
  - README: some stuff moved to tips doc, brief summary of extras
    (over gitosis) added
  - INSTALL: major revamp, easy install and manual install,
    much shorter and much more readable!

plus other docs changed as needed, and updated the tips doc to roll in
some details from "update.mkd" in the "ml" branch
  • Loading branch information
Sitaram Chamarty committed Oct 11, 2009
1 parent d0d9cbe commit d78bbe8
Show file tree
Hide file tree
Showing 9 changed files with 313 additions and 320 deletions.
112 changes: 44 additions & 68 deletions README.mkd
View file
Expand Up @@ -9,17 +9,16 @@
---- ----


Gitolite is the bare essentials of gitosis, with a completely different Gitolite is a rewrite of gitosis, with a completely different config file that
config file that allows (at last!) access control down to the branch level, allows (at last!) access control down to the branch level, including
including specifying who can and cannot *rewind* a given branch. It is specifying who can and cannot *rewind* a given branch.
released under GPL v2. See COPYING for details.


In this document: In this document:


* why * why
* what's gone * what's extra
* what's new * security
* the workflow * contact and license


---- ----


Expand All @@ -32,30 +31,15 @@ a typical $DAYJOB setting, there are some issues:
and be done and be done
* often, "python-setuptools" isn't installed (and on a Solaris9 I was trying * often, "python-setuptools" isn't installed (and on a Solaris9 I was trying
to help remotely, we never did manage to install it eventually) to help remotely, we never did manage to install it eventually)
* or you don't have root access, or the ability to add users * you don't have root access, or the ability to add users (this is also true
for people who have just one userid on a hosting provider)
* the most requested feature (see "what's new?") had to be written anyway * the most requested feature (see "what's new?") had to be written anyway


### what's gone

While I was pondering the need to finally learn python[1] , I also realised
that:

* no one in $DAYJOB type environments will use or approve access methods
that work without any authentication, so I didn't need gitweb/daemon
support in the tool or in the config file.

Update 2009-09-24: I don't use this feature but someone wanted it, so I
added it... see the "faq, tips, etc" document for more

* the idea that you admin it by pushing to a special repo is nice, but not
really necessary because of how rarely these changes are made, especially
considering how much code is involved in that piece

All of this pointed to a rewrite. In perl, naturally :-) All of this pointed to a rewrite. In perl, naturally :-)


### what's new ### what's extra


Per-branch permissions. You will not believe how often I am asked this at **Per-branch permissions**. You will not believe how often I am asked this at
$DAYJOB. This is almost the single reason I started *thinking* about rolling $DAYJOB. This is almost the single reason I started *thinking* about rolling
my own gitosis in the first place. my own gitosis in the first place.


Expand All @@ -65,50 +49,42 @@ deleting a branch (which is really just an extreme form of rewind). I needed
something in between allowing anyone to do it (the default) and disabling it something in between allowing anyone to do it (the default) and disabling it
completely (`receive.denyNonFastForwards` or `receive.denyDeletes`). completely (`receive.denyNonFastForwards` or `receive.denyDeletes`).


Take a look at the example config file in the repo to see how I do this. I Here're **some more features**. All of them are documented in detail
copied the basic idea from `update-hook-example.txt` (it's one of the "howto"s somewhere in the `doc/` subdirectory.
that come with the git source tree). However, please note the difference in
the size and complexity of the *operational code* between the update hook in * simpler, yet far more powerful, config file syntax, including specifying
that example, and in mine :-) The reason is in the next section. gitweb/daemon access. You'll need this power if you manage lots of users

+ repos + combinations of access
### the workflow * config file syntax gets checked upfront, and much more thoroughly

* if your requirements are still too complex, you can split up the config
In order to get per-branch access, you *must* use an update hook. However, file and delegate authority over parts of it
that only gets invoked on a push; "read" access still has to be controlled * more comprehensive logging [aka: management does not think "blame" is just
right at the beginning, before git even enters the scene (just the way gitosis a synonym for "annotate" :-)]
currently works). * "personal namespace" prefix for each dev
* migration guide and simple converter for gitosis conf file
* "exclude" (or "deny" rights in the config file) -- this is the "rebel"
branch in the repository, and always will be ;-)

### security

Due to the environment in which this was created and the need it fills, I
consider this a "security" program, albeit a very modest one. The code is
very small and easily reviewable -- the 2 programs that actually control
access when a user logs in total about 200 lines of code (about
80 lines according to "sloccount").

For the first person to find a security hole in it, defined as allowing a
normal user (not the gitolite admin) to read a repo, or write/rewind a ref,
that the config file says he shouldn't, and caused by a bug in *code* that is
in the "master" branch, (not in the other branches, or the configuration file
or in Unix, perl, shell, etc.)... well I can't afford 1000 USD rewards like
djb, so you'll have to settle for 1000 INR (Indian Rupees) as a "token" prize
:-)


So: either split the access control into two config files, or have two ----
completely different programs *both* parse the same one and pick what they
want. Crap... I definitely don't want the hook doing any parsing, (and it
would be nice if the auth-control program didn't have to either).

So I changed the workflow completely:

* all admin changes happen *on the server*, in a special directory that
contains the config and the users' pubkeys. But there's no commit and
push afterward
* instead, after making changes, you "compile" the configuration. This
refreshes `~/.ssh/authorized_keys`, as well as puts a parsed form of the
access list in a file for the other two pieces to use.

The pre-parsed form is basically a huge perl variable. It's human readable
too (never mind what the python guys say!)

So the admin knows immediately if the config file had any problems, which is
good. Also, the relatively complex parse code is not part of the actual
access control points, which are:

* the program that is run via `~/.ssh/authorized_keys` (I call it
`gl-auth-command`, equivalent to `gitosis-serve`); this decides whether
git should even be allowed to run (basic R/W/no access)
* the update-hook on each repo, which decides the per-branch permissions

### footnotes


[1] I hate whitespace to mean anything significant except for text; this is a ### contact and license
personal opinion *only*, so pythonistas please back off :-)


### contact Gitolite is released under GPL v2. See COPYING for details.


sitaramc@gmail.com sitaramc@gmail.com
2 changes: 1 addition & 1 deletion conf/example.gitolite.rc
View file
Expand Up @@ -5,7 +5,7 @@
# this file is meant to be pulled into a perl program using "do" or "require". # this file is meant to be pulled into a perl program using "do" or "require".


# You do NOT need to know perl to edit the paths; it should be fairly # You do NOT need to know perl to edit the paths; it should be fairly
# self-explanatory # self-explanatory and easy to maintain perl syntax :-)


# -------------------------------------- # --------------------------------------


Expand Down
127 changes: 29 additions & 98 deletions doc/0-INSTALL.mkd
View file
@@ -1,9 +1,24 @@
# installing gitolite # installing gitolite


This document tells you how to install gitolite. After the install is done,
you may want to see the "admin" document for adding users, repos, etc.

There's an easy install script for Linux, and for other Unixes there's a
slightly more manual process. Both are explained here.

In this document:

* easy install
* manual install
* other notes
* next steps

----

### easy install ### easy install


There is now an easy install script that makes installing very easy for the There is an easy install script that makes installing very easy for the common
common case. **This script is meant to be run on your workstation, not on the case. **This script is meant to be run on your workstation, not on the
server!** It will take care of all the server side work, *and* get you server!** It will take care of all the server side work, *and* get you
"push-to-admin" too :-) In short, it does **everything**! "push-to-admin" too :-) In short, it does **everything**!


Expand Down Expand Up @@ -35,110 +50,26 @@ info).


#### disadvantages #### disadvantages


* has been tested only with Linux. However, the script now makes a much * has been tested only with Linux
better "document" on what actually needs to be done, so people installing
on non-Linux machines can probably follow the steps in the script and
install if they wish. Sort of "simulate" it... :)


### manual install ### manual install


If for some reason you cannot use the easy-install method, (for example, If for some reason you cannot use the easy-install method, (for example,
you're on a non-Linux machine) read on. Unlike the easy install, all the you're on a non-Linux machine), it's not very complicated. Just open the file
below stuff is meant to be run on the server. `src/00-easy-install.sh` in a nice, syntax coloring, text editor, and follow

the instructions marked "MANUAL" :-)
#### pre-requisites on the server

If you managed to install git, you might already have what gitolite needs:

* git itself, the more recent the better
* perl, typically installed with git, since git sort of needs it; any
version that includes `Data::Dumper`[1] will do.
* one user account on the server, with password access [2]


A major objective is to allow use by people without root access, permissions ### other notes
to create other userids, etc. Even if you have root, please add a user just
for gitolite and do all this from that user.


#### getting a tar file from a clone * If you edit `~/.gitolite.rc` and change any paths, be sure to keep the

perl syntax -- you *don't* have to know perl to do so, it's fairly easy to
You can clone the repo from github, then execute a make command to extract a guess in this limited case
tar file of the branch you want. Please use the make command, not a plain
"git archive". The comments in the `Makefile` will explain why.

git clone git://github.com/sitaramc/gitolite.git
cd gitolite
make master.tar
# or maybe "make rebel.tar" or "make pu.tar"

#### install from tar file

* make a temp directory somewhere, cd to it, and unpack the tar file
* run `src/install.pl` and follow the prompts

**When you are told to edit some file, please read the comments in the file**.
And if you can make some time to read the documentation, please do.
Especially if you have problems.

Notes:

* At present the location of `~/.gitolite.rc` is fixed (maybe later I'll
change it to a "git config" variable but I don't see much need right now)

If you edit it and change any paths, be sure to keep the perl syntax --
you *don't* have to know perl to do so, it's fairly easy to guess in this
limited case. And of course, make sure you adjust the commands shown
above to suit the new locations


* the config file is (by default) at `~/.gitolite/conf/gitolite.conf`, * the config file is (by default) at `~/.gitolite/conf/gitolite.conf`,
though you can change its location in the "rc" file. Edit the file as you though you can change its location in the "rc" file. Edit the file as you
wish. The comments in the file ought to be clear enough but let me know wish. The comments in the example file (`conf/example.conf`) ought to be
if not clear enough but let me know if not

* if you want to bring in existing (bare, server) repos into gitolite, this
should work (refer to `~/.gitolite.rc` for *your* values of the pathnames
below):
* backup the repo, then move it to `$BASE_REPO`
* copy `$GL_ADMINDIR/src/update-hook.pl` to
`[reponame].git/hooks/update` -- if you don't do this, per branch
restrictions will not work
* then update the keys and the config file and "compile" (see "admin"
document)

### Footnotes:

[1] Actually, due to the way gitolite is architected, you can manage
without `Data::Dumper` on the server if you have no choice. Only
`gl-compile-conf` needs it, so just run that on some other machine and copy
the two output files across. Cumbersome but doable... the advantage of
separating all the hard work into a manually-run piece :)

[2] If you have *only* pubkey access, and **no** password access, then your
pubkey is already in the server's `~/.ssh/authorized_keys`. If you also need
to access git as a developer (clone, push, etc), do *not* submit this same
pubkey to gitolite -- it won't work.

Instead, create a different keypair for your "developer" role (by, e.g.,
`ssh-keygen -t rsa -f ~/.ssh/gitdev`), then give `~/.ssh/gitdev.pub` to
gitolite as "yourname.pub", just like you would do for any other user.

Then you create a suitable `~/.ssh/config` to use the correct key
automatically, something like this:

host gitadm
hostname my.server
user my_userid_on_server

host gitdev
hostname my.server
user my_userid_on_server
identityfile ~/.ssh/gitdev

From now on, `ssh gitadm` will get you a command line on the server, to do
gitolite admin and other work. And your repository URLs would look like
`gitdev:reponame.git`. Very, very, simple...

And as with gitosis, there's more "ssh" magic than "git" magic here :-)


---- ### next steps


gitolite is released under the GPL v2 license. See COPYING for details See the "admin" document for how to add users, etc.
40 changes: 34 additions & 6 deletions doc/0-UPGRADE.mkd
View file
@@ -1,11 +1,19 @@
# upgrading gitolite atomically # upgrading gitolite atomically


Upgrading is done **manually, on the server** (except the last step, which is
on your admin repo clone), even if you installed it using the easy install
script on the client. First, it's not as difficult as an install so you don't
really need a script. Second, you may have customised the "rc" file
(`~/.gitolite.rc` on the server) and I'm reluctant to mess with that in an
automated way.

### general upgrade notes ### general upgrade notes


If you follow the steps below, you can make the upgrade "atomic", so you don't If you follow the steps below, you can make the upgrade "atomic", so you don't
have to do it at a "quiet" time or something. have to do it at a "quiet" time or something.


1. untar the new version to some temp directory and `cd` to it 1. copy a tar file containing the new version to the server, untar it to some
temp directory and `cd` to it


2. *prepare* the new version of `~/.gitolite.rc`. It **must** have **all** 2. *prepare* the new version of `~/.gitolite.rc`. It **must** have **all**
the variables defined in `conf/example.gitolite.rc` (the "new" rc file), the variables defined in `conf/example.gitolite.rc` (the "new" rc file),
Expand All @@ -31,12 +39,11 @@ have to do it at a "quiet" time or something.
src/install.pl src/install.pl


5. compile the config once again, in case the *internal* format of the 5. compile the config once again, in case the *internal* format of the
compiled config file (`$GL_CONF_COMPILED`) has changed compiled config file (`$GL_CONF_COMPILED`) has changed.

src/gl-compile-conf


(if you've already setup "push-to-admin", this step should be replaced by To do this, you have to do a "git push" on the client side. That might
a "git push". Make a dummy commit if needed, to make the push happen). require a dummy change (maybe add a blank line somewhere) because
otherwise the push will not happen.


And you're done. And you're done.


Expand All @@ -45,6 +52,27 @@ And you're done.
If any extra steps beyond the generic ones above are needed, they will be If any extra steps beyond the generic ones above are needed, they will be
listed here, newest first. listed here, newest first.


#### upgrading from 410c9ba

Between 410c9ba and this version, gitolite managed to make "push to admin" the
default for new installs, but in a much more painless way. If you're
upgrading, you're not forced to use "push to admin", but I'd suggest you:

* make sure you have password-less (pubkey) login to a command line on your
server
* save your `~/.gitolite.rc`, `keydir/*.pub` and your `conf/gitolite.conf`
files from the server, bring them to your workstation
* then run `src/00-easy-install.sh` on the workstation, as if it were a
fresh install
* when the editor pops up to edit the rc file, delete all the lines in
it and copy them from the saved `~/.gitolite.rc`
* at the end of the script, after the gitolite-admin repo has been
cloned successfully, copy the saved `conf/gitolite.conf` and
`keydir/*.pub` to the clone, then add, commit, and push

Gitolite also learnt to delegate parts of the config to other users. See
`doc/5-delegation.mkd` for details.

#### upgrading from 8217ef9 #### upgrading from 8217ef9


Between 8217ef9 and this version, gitolite learnt to handle gitweb/daemon Between 8217ef9 and this version, gitolite learnt to handle gitweb/daemon
Expand Down

0 comments on commit d78bbe8

Please sign in to comment.