README
author Paul Crowley <paul@ciphergoth.org>
Mon, 21 Apr 2008 12:37:56 +0100
changeset 17 4c98440de851
parent 15 f3654416d178
child 18 538d6b198f4a
permissions -rw-r--r--
Started work on acl.py replacement - currently broken.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
13
1206ed37090a more README fixes
Paul Crowley <paul@ciphergoth.org>
parents: 12
diff changeset
     1
hg-admin-tools
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     3
A set of tools for managing authorization and access control for
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
     4
ssh-based Mercurial repositories
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     5
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
     6
Paul Crowley, paul@lshift.net, 2008
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     7
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     8
This software may be used and distributed according to the terms
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
     9
of the GNU General Public License, incorporated herein by reference.
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    10
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    11
WHAT IT GIVES YOU
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    12
14
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    13
These tools make it easier to provide a centralized repository host
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    14
with read/write access to many repositories for many developers.
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    15
Access control is managed with a special repository on the server
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    16
called "hgadmin"; pushes to this repository immediately change the
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    17
rules that are in effect.
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    18
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    19
Inside "hgadmin" is a "keys" directory containing the SSH keys of all
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    20
developers who have access, and a file "hg-ssh-access.conf" which
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    21
gives a set of rules defining who can do what to what.
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    22
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    23
HOW IT WORKS
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    24
14
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    25
All of the repositories controlled by these tools are owned by a
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    26
single user (the "hg" user in what follows), but many remote users can
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    27
act on them.  We don't use file permissions to achieve that - instead,
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    28
developers log in as the "hg" user when they connect to the repository
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    29
host using ssh, using ssh URLs of the form
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    30
"ssh://hg@repository-host/repository-name".  A restricted shell
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    31
prevents them from using this access for unauthorized purposes.
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    32
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    33
Developers are authenticated only using SSH keys; no other form of
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    34
authentication is supported.  When a developer attempts to connect to
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    35
a repository via ssh, the SSH daemon searches for a match for that
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    36
user's key in ~hg/.ssh/authorized_keys.  If the developer is
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    37
authorised to connect to the repository they will have an entry in
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    38
this file.  The entry includes a "command" prefix which specifies that
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    39
the restricted shell should be used; this shell is passed an argument
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    40
identifying the developer.  The shell parses the command the developer
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    41
is trying to execute, and consults a rules file to see if that
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    42
developer is allowed to perform that action on that repository.  The
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    43
bulk of the work of the restricted shell is done by the Python program
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    44
"hg-ssh", but the shell script "hg-ssh-wrapper" sets up some
14
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    45
configuration so that you can change it to suit your local
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    46
installation.
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    47
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    48
The file ~hg/.ssh/authorized_keys is generated by "refresh-auth",
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    49
which recurses through a directory of files containing SSH keys and
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    50
generates an entry in authorized_keys for each one, using the name of
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    51
the key file as the identifier for the developer.  These keys will
14
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    52
live in the "keys" subdirectory of a repository called "hgadmin".  A
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    53
hook in this repository re-runs "refresh-auth" on the most recent
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    54
version after every push.
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    55
13
1206ed37090a more README fixes
Paul Crowley <paul@ciphergoth.org>
parents: 12
diff changeset
    56
GETTING STARTED
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    57
10
524b4a45ef0a wrap overlong lines
Paul Crowley <paul@lshift.net>
parents: 4
diff changeset
    58
This is only one setup - it can be tweaked in many ways, and is as
524b4a45ef0a wrap overlong lines
Paul Crowley <paul@lshift.net>
parents: 4
diff changeset
    59
specific as it is only in the interests of brevity.
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    60
14
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    61
You, and all users of this repository host, will need SSH public key
10
524b4a45ef0a wrap overlong lines
Paul Crowley <paul@lshift.net>
parents: 4
diff changeset
    62
authentication set up, preferably working with ssh-agent so you don't
524b4a45ef0a wrap overlong lines
Paul Crowley <paul@lshift.net>
parents: 4
diff changeset
    63
have to type in your passphrase all the time.  I assume you've done
524b4a45ef0a wrap overlong lines
Paul Crowley <paul@lshift.net>
parents: 4
diff changeset
    64
that in what follows, so if you've done something different you'll
524b4a45ef0a wrap overlong lines
Paul Crowley <paul@lshift.net>
parents: 4
diff changeset
    65
need to change it appropriately.
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    66
14
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    67
Issue these commands to get the repository host started.  These are
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    68
written out here rather than encapsulated in a script because many of
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    69
them may need to be different for your local setup.  You will need
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    70
root access on the repository host, because you need to create a new
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    71
user.
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    72
14
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    73
   ssh -A repository-host
13
1206ed37090a more README fixes
Paul Crowley <paul@ciphergoth.org>
parents: 12
diff changeset
    74
   ssh-add -L >> /tmp/my-ssh-public-key
14
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    75
   sudo adduser --system --shell /bin/sh --group --disabled-password \
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    76
     --gecos "Mercurial repositories" hg
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    77
   sudo -u hg -H -s
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    78
   cd
15
f3654416d178 minor changes to README and script
Hubert Plociniczak <hubert@lshift.net>
parents: 14
diff changeset
    79
   mkdir -p admin repos/hgadmin/keys/admin .ssh
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    80
   cd admin
13
1206ed37090a more README fixes
Paul Crowley <paul@ciphergoth.org>
parents: 12
diff changeset
    81
   hg clone http://hg.opensource.lshift.net/hg-admin-tools
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    82
   cp hg-admin-tools/hg-ssh-wrapper ~
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    83
   cd ../repos/hgadmin
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    84
   hg init .
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    85
   echo "init admin/* *" > hg-ssh-access.conf
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    86
   cp /tmp/my-ssh-public-key keys/admin/myname
13
1206ed37090a more README fixes
Paul Crowley <paul@ciphergoth.org>
parents: 12
diff changeset
    87
   hg add
15
f3654416d178 minor changes to README and script
Hubert Plociniczak <hubert@lshift.net>
parents: 14
diff changeset
    88
   hg commit -m "initial commit"
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    89
   cp ~/admin/hg-admin-tools/hgadmin-hgrc .hg/hgrc
15
f3654416d178 minor changes to README and script
Hubert Plociniczak <hubert@lshift.net>
parents: 14
diff changeset
    90
   ../../admin/hg-admin-tools/refresh-auth ./hg-ssh-wrapper
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    91
   exit
14
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    92
   exit
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    93
14
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    94
You are now the sole user able to change and create repositories on
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    95
this repository host.  To administer these controls (and test your
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
    96
access), check out hgadmin:
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
    97
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    98
   mkdir ~/hg
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
    99
   cd ~/hg
14
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
   100
   hg clone ssh://hg@repository-host/hgadmin
12
834426fcbada rewrote README
Paul Crowley <paul@lshift.net>
parents: 10
diff changeset
   101
   cd hgadmin
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   102
10
524b4a45ef0a wrap overlong lines
Paul Crowley <paul@lshift.net>
parents: 4
diff changeset
   103
You can now add other users by putting their keys in an appropriate
524b4a45ef0a wrap overlong lines
Paul Crowley <paul@lshift.net>
parents: 4
diff changeset
   104
subdirectory of the "keys" directory, and control their access by
524b4a45ef0a wrap overlong lines
Paul Crowley <paul@lshift.net>
parents: 4
diff changeset
   105
editing hg-ssh-access.conf.  Changes will take effect as soon as you
14
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
   106
push them to "ssh://hg@repository-host/hgadmin".
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
   107
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
   108
Users authorized to do so can now also create new repositories on this host with "clone":
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
   109
e7d5254cd0ca fix repo confusion in README per Matthias's comments
Paul Crowley <paul@ciphergoth.org>
parents: 13
diff changeset
   110
  hg clone . ssh://hg@repository-host/my-project-name
13
1206ed37090a more README fixes
Paul Crowley <paul@ciphergoth.org>
parents: 12
diff changeset
   111
1206ed37090a more README fixes
Paul Crowley <paul@ciphergoth.org>
parents: 12
diff changeset
   112
HG-SSH-ACCESS.CONF
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   113
10
524b4a45ef0a wrap overlong lines
Paul Crowley <paul@lshift.net>
parents: 4
diff changeset
   114
Each line of hg-ssh-access.conf has the following syntax:
2
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   115
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   116
<rule> <keypattern> <repositorypattern>
a69f7bea408c added a README to describe how this works.
Paul Crowley <paul@lshift.net>
parents:
diff changeset
   117
10
524b4a45ef0a wrap overlong lines
Paul Crowley <paul@lshift.net>
parents: 4
diff changeset
   118
The "rule" is either "init", "allow", or "deny".  "keypattern" is a
524b4a45ef0a wrap overlong lines
Paul Crowley <paul@lshift.net>
parents: 4
diff changeset
   119
glob pattern matched against the name of the key used - for example,
524b4a45ef0a wrap overlong lines
Paul Crowley <paul@lshift.net>
parents: 4
diff changeset
   120
in our initial setup "admin/myname" matches "admin/*".
524b4a45ef0a wrap overlong lines
Paul Crowley <paul@lshift.net>
parents: 4
diff changeset
   121
"repositorypattern" is a pattern matched againt the repository name -
524b4a45ef0a wrap overlong lines
Paul Crowley <paul@lshift.net>
parents: 4
diff changeset
   122
so "hgadmin" matches "*".  Only boring characters are allowed in
524b4a45ef0a wrap overlong lines
Paul Crowley <paul@lshift.net>
parents: 4
diff changeset
   123
patterns and key and repository names - see the source for details.
13
1206ed37090a more README fixes
Paul Crowley <paul@ciphergoth.org>
parents: 12
diff changeset
   124
Blank lines and lines that start with "#" are ignored.  The first rule
1206ed37090a more README fixes
Paul Crowley <paul@ciphergoth.org>
parents: 12
diff changeset
   125
to match both the key and the repository applies: "deny" will deny all
1206ed37090a more README fixes
Paul Crowley <paul@ciphergoth.org>
parents: 12
diff changeset
   126
matching requests, "allow" allows read/write access to existing
1206ed37090a more README fixes
Paul Crowley <paul@ciphergoth.org>
parents: 12
diff changeset
   127
repositories, and "init" allows that and creation of new repositories.