INSTALL and README pretty much done

This commit is contained in:
Sitaram Chamarty 2009-08-24 13:29:33 +05:30 committed by Sitaram Chamarty
parent 3cddc4ca35
commit d33c408dc3
2 changed files with 160 additions and 58 deletions

106
INSTALL
View file

@ -1,25 +1,99 @@
There are 5 files you need to touch/copy
### quickinstall
example.conf
example.gitosis-lite.rc
gl-auth-command
gl-compile-conf
update-hook.pl
I assume all the files pertaining to this software are untarred and available
in the current directory.
1. copy `example.gitosis-lite.rc` as `~/.gitosis-lite.rc`. This location is
fixed for now (maybe later I'll change it to a "git config" variable).
A quick install, taking all the defaults, can be done with the following
commands; just copy and paste them into your shell:
2. edit `~/.gitosis-lite.rc` and change all the paths however you want. 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.
# this one is fixed to the location shown
cp example.gitosis-lite.rc ~/.gitosis-lite.rc
3. copy `example.conf` to whatever path you specified for `GL_CONF` in the rc
file in step 2. By default it is `~/.gitosis-lite/gitosis-lite.conf`.
# the destinations below are defaults; if you change the paths in the "rc"
# file above, these destinations also must change accordingly
# mkdir $REPO_BASE, $GL_ADMINDIR, and $GL_KEYDIR
mkdir ~/repositories
mkdir ~/.gitosis-lite
mkdir ~/.gitosis-lite/keydir
# copy sample conf to $GL_CONF
cp example.conf ~/.gitosis-lite/gitosis-lite.conf
# copy the 3 programs to $GL_ADMINDIR
cp update-hook.pl ~/.gitosis-lite
cp gl-auth-command ~/.gitosis-lite
cp gl-compile-conf ~/.gitosis-lite
# optional; copy the documents also (if you untarred the package into a
# temporary directory and need to get rid of it)
cp INSTALL README.markdown ~/.gitosis-lite
### install notes
* At present the location of `~/.gitosis-lite.rc` is fixed (maybe later I'll
change it to a "git config" variable).
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 `~/.gitosis-lite/gitosis-lite.conf`.
Edit the file as you wish. The comments in the file ought to be clear
enough but let me know if not
4. create directories for whatever you named in `GL_KEYDIR` and `REPO_BASE`
(default `~/.gitosis-lite/keydir` and `~/repositories`)
* if you want to bring in existing (bare, server) repos into gitosis-lite,
this should work:
* backup the repo, then move it to `$BASE_REPO`
* copy `$GL_ADMINDIR/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"
5. copy `update-hook.pl` to `$GL_ADMINDIR` (default `~/.gitosis-lite`)
### administer
* ask each user who will get access to send you a public key. See other
sources (for example
[here](http://sitaramc.github.com/0-installing/2-access-gitosis.html#generating_a_public_key))
for how to do this
* for each "user" in `$GL_CONF`, copy their public key to a file called
"user.pub" in `$GL_KEYDIR`
* edit the config file (`$GL_CONF`) to add the new users in whatever way you
like
* backup your `~/.ssh/authorized_keys` file if you feel nervous :-)
* cd to `$GL_ADMINDIR` and run `./gl-compile-conf`
#### optional -- if you want to be doubly sure
It should all work, but the first couple of times you may want to check these
* check the outputs
* `~/.ssh/authorized_keys` should contain one line for each "user" pub
key added, between two "marker" lines (which you should please please
not remove!). The line should contain a "command=" pointing to a
`$GL_ADMINDIR/gl-auth-command` file, then some sshd restrictions, the
key, etc.
* `$GL_CONF_COMPILED` (default
`~/.gitosis-lite/gitosis-lite.conf-compiled.pm`) should contain an
expanded list of the access control rules. It may look a little long,
but it's fairly intuitive!
* if the run threw up any "initialising empty repo" messages, check the
individual repos (inside `$REPO_BASE`) if you wish. Especially make sure
the `$REPO_BASE/[reponame].git/hooks/update` got copied OK and is
executable
### run
Just use it as normal. Every new repo mentioned has been created already, so
(as long as your clients are using git > 1.6.2), you can just clone it.
And once in a while, if you're feeling particularly BOFH-ish, take a look at
`$GL_ADMINDIR/log` :-)
### errors, warnings, etc
* when you clone an empty repo, git seems to complain about the remote
hanging up or something. I have no idea what that is, but it doesn't seem
to hurt anything. This happens even in normal git, not just gitosis-lite.

View file

@ -1,65 +1,93 @@
# gitosis-lite
gitosis-lite is the bare essentials of gitosis, with a completely different
config file that allows (at last!) access control down to the branch level,
including specifying who can and cannot *rewind* a given branch.
In this document:
* "lite"?
* what's extra
* workflow
* why
* what's gone
* what's new
* the workflow
----
### "lite"?
### why
I have been gitosis for a while, and have learnt a lot from it. But in a
typical $DAYJOB setting, there are some issues. It's not always Linux, so you
can't just "urpmi gitosis" and be done. "python-setuptools" isn't often
installed (and on a Solaris 9 I was trying to help remotely, we never did
manage it). And the most requested feature (see next section) had to be
written anyway.
I have been using gitosis for a while, and have learnt a lot from it. But in
a typical $DAYJOB setting, there are some issues:
While I was pondering having to finally learn python (I hate whitespace based
flow logic except for plain text; this is a *personal* opinion so pythonistas
can back off :-), I also realised that:
* it's not always Linux; you can't just "urpmi gitosis" (or yum or apt-get)
and be done
* often, "python-setuptools" isn't installed (and on a Solaris9 I was trying
to help remotely, we never did manage to install it eventually)
* the most requested feature (see "what's extra?") had to be written anyway
* no one in $DAYJOB settings will use or approve access methods that work
without any authentication, so I didn't need gitweb/daemon support in the
tool
* the idea that you admin it by pushing to a special repo is cute and
convenient, but not really necessary because of how rarely these changes
are made.
### what's gone
All of this pointed to a rewrite. In perl, naturally.
While I was pondering the need to finally learn python[1] , I also realised
that:
I also gained (and used) an unfair advantage: gits newer than 1.6.2 can clone
an empty repo, so I don't need complex logic in the permissions checking part
to *create* the repo initially -- I just create an empty bare repo when I
"compile" the config file (see "workflow" below).
* 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
* 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 :-)
### what's extra?
A lot of people in my $DAYJOB type world want per-branch permissions, so I
copied the basic idea from
git.git:Documentation/howto/update-hook-example.txt. I think this is the most
significant extra I have. This includes not just who can push to what branch,
but also whether they are allowed to rewind it or not (non-ff push).
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
my own gitosis in the first place.
### workflow
Take a look at the example config file in the repo to see how I do this. I
copied the basic idea from `update-hook-example.txt` (it's one of the "howto"s
that come with the git source tree). This includes not just who can push to
what branch, but also whether they are allowed to rewind it or not (non-ff
push).
I took the opportunity to change the workflow significantly.
However, please note the difference in the size and complexity of the
*operational code* between the update hook in that example, and in mine :-)
The reason is in the next section.
* all admin happens *on the server*, in a special directory
* after making any changes, one "compiles" the configuration. This
### the workflow
In order to get per-branch access, you *must* use an update hook. However,
that only gets invoked on a push; "read" access still has to be controlled
right at the beginning, before git even enters the scene (just the way gitosis
currently works).
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. Nothing prevents you from version-controlling that
directory if you wish to, but it's not *required*
* 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.
Why pre-parse? Because access control decisions are taken at two separate
stages now:
The pre-parsed form is basically a huge perl variable. It's human readable
too (never mind what the python guys say!)
* the program that is run via `~/.ssh/authorized_keys` (called
`gl-auth-command`, equivalent to `gitosis-serve`) decides whether even git
should be allowed to run (basic R/W/no access)
* the update-hook on each repo, which decides the per-branch permissions.
Advantages: all the complexity of parsing and error checking the parse is done
away from the two places where the actual access control happens, which are:
But the user specifies only one access file, and he doesn't have to know these
distinctions. So I avoid having to parse the access file in two completely
different programs by pre-compiling it and storing it as a perl "variable".
* 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
----
[1] I hate whitespace to mean anything significant except for text; this is a
personal opinion *only*, so pythonistas please back off :-)