20 |
20 |
21 You should have received a copy of the GNU General Public License along |
21 You should have received a copy of the GNU General Public License along |
22 with this program; if not, write to the Free Software Foundation, Inc., |
22 with this program; if not, write to the Free Software Foundation, Inc., |
23 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. |
23 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. |
24 |
24 |
25 SUMMARY |
25 For details on how to install and use mercurial-server, see doc/manual.docbook. |
26 |
|
27 mercurial-server makes a group of repositories available to the developers |
|
28 you choose, identified by ssh keys, with easy key and access management |
|
29 based on hg. |
|
30 |
|
31 All of the repositories controlled by mercurial-server are owned by a |
|
32 single user (the "hg" user in what follows), but many remote users can act |
|
33 on them, and different users can have different permissions. We don't use |
|
34 file permissions to achieve that - instead, developers log in as the "hg" |
|
35 user when they connect to the repository host using ssh, using ssh URLs of |
|
36 the form "ssh://hg@repository-host/repository-name". A restricted shell |
|
37 prevents them from using this access for unauthorized purposes. Developers |
|
38 are authenticated only using SSH keys; no other form of authentication is |
|
39 supported. |
|
40 |
|
41 To give a user access to the repository, place their key in an |
|
42 appropriately-named subdirectory of "/etc/mercurial-server/keys" and run |
|
43 "/usr/local/share/mercurial-server/refresh-auth". You can then control what |
|
44 access they have to what repositories by editing the control file |
|
45 "/etc/mercurial-server/access.conf", which can match the names of these keys |
|
46 against a glob pattern. |
|
47 |
|
48 For convenient remote control of access, you can instead (if you have the |
|
49 privileges) make changes to a special repository called "hgadmin", which |
|
50 contains its own "access.conf" file and "keys" directory. Changes pushed to |
|
51 this repository take effect immediately. The two "access.conf" files are |
|
52 concatenated, and the keys directories merged. |
|
53 |
|
54 QUICK START |
|
55 |
|
56 You and all developers using this system will need an SSH public key, and |
|
57 will almost certainly want to be running ssh-agent (or its equivalent, eg |
|
58 Pageant under Windows). If you're not familiar with ssh-agent, you should |
|
59 learn about that before using this. |
|
60 |
|
61 In what follows, certain operations (eg installing mercurial-server itself) |
|
62 have to be done on the repository server (which we call "repository-host"), |
|
63 but any operation that involves checking in or out of Mercurial can be done |
|
64 wherever is most convenient to you; the most usual arrangment would be that |
|
65 you'd do these things at the machine you sit at, and on which you run |
|
66 ssh-agent, which is what authenticates you when you talk to the repository |
|
67 server. |
|
68 |
|
69 Ensure there is no user called "hg" on the repository host, and run |
|
70 "./install". This installs the mercurial-server files and control files, and |
|
71 creates and sets up the "hg" user. |
|
72 |
|
73 Place your SSH public key in the directory "/etc/mercurial-server/keys/root". |
|
74 I suggest creating yourself a directory and naming the key after your hostname |
|
75 (ie the file is called something like |
|
76 "/etc/mercurial-server/keys/root/yourname/yourhostname") so that you can |
|
77 easily manage users who have a different key on each host they use. Then run |
|
78 "/usr/local/share/mercurial-server/refresh-auth". |
|
79 |
|
80 The repository is now ready to use, and you are now the sole user able to |
|
81 change and create repositories on this repository host. |
|
82 |
|
83 CREATING REPOSITORIES |
|
84 |
|
85 To create a new repository, you clone a local repository onto the remote |
|
86 server. So if you want a new empty repository called "myproject", you can do |
|
87 (as yourself): |
|
88 |
|
89 hg init myproject |
|
90 hg clone myproject ssh://hg@repository-host/myproject |
|
91 |
|
92 ADDING OTHER USERS |
|
93 |
|
94 Because your key is in the "keys/root" subdirectory, you have the equivalent |
|
95 of "root privileges" over mercurial-server (not the whole computer, just |
|
96 mercurial-server). You can add other root users by putting their keys next to |
|
97 yours, or you can make less privileged users by putting their keys in the |
|
98 "keys/users" subdirectory - these users will be able to read and write to any |
|
99 repository (except one - see below) but will not be able to create new |
|
100 repositories. As always, when you change "/etc/mercurial-server/keys" you need |
|
101 to re-run "/usr/local/share/mercurial-server/refresh-auth". |
|
102 |
|
103 LOGGING |
|
104 |
|
105 Every push and pull is logged with the key used: see the file .hg/serve-log in |
|
106 each repository. |
|
107 |
|
108 USING HGADMIN |
|
109 |
|
110 It can be inconvenient to log on to the repository server, become root, copy |
|
111 keys around, and run "refresh-auth" every time you want to change user |
|
112 privileges. This is where mercurial-server shines :-) Suppose you have another |
|
113 user's SSH public key in the file "/tmp/theirkey" (on the machine you sit at, |
|
114 not necessarily the repository server) and you want to give them user-level |
|
115 access to the repository server. Run these commands: |
|
116 |
|
117 hg clone ssh://hg@repository-server/hgadmin |
|
118 cd hgadmin |
|
119 mkdir keys/users/thatuser |
|
120 cp /tmp/theirkey keys/users/thatuser/theirhostname |
|
121 hg add |
|
122 hg commit -m "Added key for thatuser" |
|
123 hg push |
|
124 |
|
125 In other words, hgadmin is a version controlled version of |
|
126 "/etc/mercurial-server", and changes to it take effect immediately - |
|
127 "refresh-auth" is run after every push. |
|
128 |
|
129 With the default access.conf file (see doc/configuring-access for more |
|
130 details) only users in "keys/root" can act on "hgadmin" - those with keys in |
|
131 "keys/users" cannot even read this repository. So multiple admins can use |
|
132 Mercurial's version control to cooperate on controlling access to the |
|
133 repository server in a natural way. |
|
134 |
|
135 You can also create an "access.conf" file in hgadmin, and this is appended to |
|
136 /etc/mercurial-server/access.conf whenever this is read - in other words, |
|
137 rules in the latter take precedence over those in the former. So once you're |
|
138 working with "hgadmin", it can be convenient to remove all the keys in |
|
139 "/etc/mercurial-server/keys" and all the entries in |
|
140 "/etc/mercurial-server/access.conf" and use hgadmin to control everything. If |
|
141 you find yourself locked out, you can get back in again by restoring some of |
|
142 the entries you removed from these files. |
|
143 |
|
144 MORE INFORMATION |
|
145 |
|
146 For more on how to use mercurial-server and configure access, see the files in |
|
147 the doc directory. |
|
148 |
|
149 THANKS |
|
150 |
|
151 Thanks for reading this far. If you use mercurial-server, please tell me about |
|
152 it. |
|
153 |
26 |
154 Paul Crowley, paul@lshift.net, 2009 |
27 Paul Crowley, paul@lshift.net, 2009 |
155 |
28 |