8 This software may be used and distributed according to the terms |
8 This software may be used and distributed according to the terms |
9 of the GNU General Public License, incorporated herein by reference. |
9 of the GNU General Public License, incorporated herein by reference. |
10 |
10 |
11 WHAT IT GIVES YOU |
11 WHAT IT GIVES YOU |
12 |
12 |
13 You maintain a local Mercurial repository called "hgadmin" which |
13 These tools make it easier to provide a centralized repository host |
14 controls what access is allowed to whom. When you push a new version |
14 with read/write access to many repositories for many developers. |
15 of this repository to the repository host, changes take effect |
15 Access control is managed with a special repository on the server |
16 immediately, so familiar "hg" commands are all that are needed to |
16 called "hgadmin"; pushes to this repository immediately change the |
17 maintain it. A "keys" directory contains the SSH keys of all the |
17 rules that are in effect. |
18 developers who have access, while "hg-ssh-access.conf" gives a set of |
18 |
19 rules defining who can do what to what. |
19 Inside "hgadmin" is a "keys" directory containing the SSH keys of all |
|
20 developers who have access, and a file "hg-ssh-access.conf" which |
|
21 gives a set of rules defining who can do what to what. |
20 |
22 |
21 HOW IT WORKS |
23 HOW IT WORKS |
22 |
24 |
23 The repository is owned by a single user (the "hg" user in what |
25 All of the repositories controlled by these tools are owned by a |
24 follows), but many remote users can act on it. We don't use file |
26 single user (the "hg" user in what follows), but many remote users can |
25 permissions to achieve that - instead, developers log in as the "hg" |
27 act on them. We don't use file permissions to achieve that - instead, |
26 user when they connect to the repository host using ssh, using ssh |
28 developers log in as the "hg" user when they connect to the repository |
27 URLs of the form "ssh://hg@repository-host/repository-name". A |
29 host using ssh, using ssh URLs of the form |
28 restricted shell prevents them from using this access for unauthorized |
30 "ssh://hg@repository-host/repository-name". A restricted shell |
29 purposes. |
31 prevents them from using this access for unauthorized purposes. |
30 |
32 |
31 Developers are authenticated only using SSH keys; no other form of |
33 Developers are authenticated only using SSH keys; no other form of |
32 authentication is supported. When a developer attempts to connect to |
34 authentication is supported. When a developer attempts to connect to |
33 a repository via ssh, the SSH daemon searches for a match for that |
35 a repository via ssh, the SSH daemon searches for a match for that |
34 user's key in ~hg/.ssh/authorized_keys. If the developer is |
36 user's key in ~hg/.ssh/authorized_keys. If the developer is |
38 identifying the developer. The shell parses the command the developer |
40 identifying the developer. The shell parses the command the developer |
39 is trying to execute, and consults a rules file to see if that |
41 is trying to execute, and consults a rules file to see if that |
40 developer is allowed to perform that action on that repository. The |
42 developer is allowed to perform that action on that repository. The |
41 bulk of the work of the restricted shell is done by the Python program |
43 bulk of the work of the restricted shell is done by the Python program |
42 "hg-ssh", but the shell script "hg-ssh-wrapper" sets up some |
44 "hg-ssh", but the shell script "hg-ssh-wrapper" sets up some |
43 configuration so that you can change it to suit your local installation. |
45 configuration so that you can change it to suit your local |
|
46 installation. |
44 |
47 |
45 The file ~hg/.ssh/authorized_keys is generated by "refresh-auth", |
48 The file ~hg/.ssh/authorized_keys is generated by "refresh-auth", |
46 which recurses through a directory of files containing SSH keys and |
49 which recurses through a directory of files containing SSH keys and |
47 generates an entry in authorized_keys for each one, using the name of |
50 generates an entry in authorized_keys for each one, using the name of |
48 the key file as the identifier for the developer. These keys will |
51 the key file as the identifier for the developer. These keys will |
49 live in the "keys" subdirectory of a repository, "hgadmin". A hook in |
52 live in the "keys" subdirectory of a repository called "hgadmin". A |
50 this repository re-runs "refresh-auth" on the most recent version |
53 hook in this repository re-runs "refresh-auth" on the most recent |
51 after every push. |
54 version after every push. |
52 |
55 |
53 GETTING STARTED |
56 GETTING STARTED |
54 |
57 |
55 This is only one setup - it can be tweaked in many ways, and is as |
58 This is only one setup - it can be tweaked in many ways, and is as |
56 specific as it is only in the interests of brevity. |
59 specific as it is only in the interests of brevity. |
57 |
60 |
58 You, and all users of your Hg repository, will need SSH public key |
61 You, and all users of this repository host, will need SSH public key |
59 authentication set up, preferably working with ssh-agent so you don't |
62 authentication set up, preferably working with ssh-agent so you don't |
60 have to type in your passphrase all the time. I assume you've done |
63 have to type in your passphrase all the time. I assume you've done |
61 that in what follows, so if you've done something different you'll |
64 that in what follows, so if you've done something different you'll |
62 need to change it appropriately. |
65 need to change it appropriately. |
63 |
66 |
64 Create a user called "hg" on the machine where the repository will |
67 Issue these commands to get the repository host started. These are |
65 live. I used the command |
68 written out here rather than encapsulated in a script because many of |
|
69 them may need to be different for your local setup. You will need |
|
70 root access on the repository host, because you need to create a new |
|
71 user. |
66 |
72 |
67 sudo adduser --system --shell /bin/sh --group --disabled-password \ |
73 ssh -A repository-host |
68 --gecos "Mercural repository" hg |
|
69 |
|
70 Issue these commands to become the hg user and set up the repository. |
|
71 Use your own name in place of "myname". |
|
72 |
|
73 ssh-add -L >> /tmp/my-ssh-public-key |
74 ssh-add -L >> /tmp/my-ssh-public-key |
74 sudo -u hg -s |
75 sudo adduser --system --shell /bin/sh --group --disabled-password \ |
75 cd ~hg |
76 --gecos "Mercurial repositories" hg |
|
77 sudo -u hg -H -s |
|
78 cd |
76 mkdir -p admin repos/hgadmin/keys/admin |
79 mkdir -p admin repos/hgadmin/keys/admin |
77 cd admin |
80 cd admin |
78 hg clone http://hg.opensource.lshift.net/hg-admin-tools |
81 hg clone http://hg.opensource.lshift.net/hg-admin-tools |
79 cp hg-admin-tools/hg-ssh-wrapper ~ |
82 cp hg-admin-tools/hg-ssh-wrapper ~ |
80 cd ../repos/hgadmin |
83 cd ../repos/hgadmin |
84 hg add |
87 hg add |
85 hg commit |
88 hg commit |
86 cp ~/admin/hg-admin-tools/hgadmin-hgrc .hg/hgrc |
89 cp ~/admin/hg-admin-tools/hgadmin-hgrc .hg/hgrc |
87 ../../admin/hg-admin-tools/refresh-auth |
90 ../../admin/hg-admin-tools/refresh-auth |
88 exit |
91 exit |
|
92 exit |
89 |
93 |
90 You should now have SSH access to this repository and full control. |
94 You are now the sole user able to change and create repositories on |
91 To administer these controls (and test your access), check out hgadmin: |
95 this repository host. To administer these controls (and test your |
|
96 access), check out hgadmin: |
92 |
97 |
93 mkdir ~/hg |
98 mkdir ~/hg |
94 cd ~/hg |
99 cd ~/hg |
95 hg clone ssh://hg@repository-host-name/hgadmin |
100 hg clone ssh://hg@repository-host/hgadmin |
96 cd hgadmin |
101 cd hgadmin |
97 |
102 |
98 You can now add other users by putting their keys in an appropriate |
103 You can now add other users by putting their keys in an appropriate |
99 subdirectory of the "keys" directory, and control their access by |
104 subdirectory of the "keys" directory, and control their access by |
100 editing hg-ssh-access.conf. Changes will take effect as soon as you |
105 editing hg-ssh-access.conf. Changes will take effect as soon as you |
101 push them to the remote repository. |
106 push them to "ssh://hg@repository-host/hgadmin". |
|
107 |
|
108 Users authorized to do so can now also create new repositories on this host with "clone": |
|
109 |
|
110 hg clone . ssh://hg@repository-host/my-project-name |
102 |
111 |
103 HG-SSH-ACCESS.CONF |
112 HG-SSH-ACCESS.CONF |
104 |
113 |
105 Each line of hg-ssh-access.conf has the following syntax: |
114 Each line of hg-ssh-access.conf has the following syntax: |
106 |
115 |