INSTALL and README pretty much done
This commit is contained in:
Sitaram Chamarty
Sitaram Chamarty
parent
3cddc4ca35
commit
d33c408dc3
106
INSTALL
106
INSTALL
|
|
@ -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.
|
||||
|
|
|
|||
112
README.markdown
112
README.markdown
|
|
@ -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 :-)
|
||||
|
|
|
|||
Loading…
Reference in a new issue