15 Access control is managed with a special repository on the server

    15 

    16 called "hgadmin"; pushes to this repository immediately change the

    16 All of the repositories controlled by these tools are owned by a single user

    17 rules that are in effect.

    17 (the "hg" user in what follows), but many remote users can act on them, and

    18 

    18 different users can have different permissions. We don't use file permissions to

    19 Inside "hgadmin" is a "keys" directory containing the SSH keys of all

    19 achieve that - instead, developers log in as the "hg" user when they connect to

    20 developers who have access, and a file "hg-ssh-access.conf" which

    20 the repository host using ssh, using ssh URLs of the form

    21 gives a set of rules defining who can do what to what.

    21 "ssh://hg@repository-host/repository-name". A restricted shell prevents them

    22 

    22 from using this access for unauthorized purposes. Developers are authenticated

    23 All of the repositories controlled by these tools are owned by a

    23 only using SSH keys; no other form of authentication is supported. 

    24 single user (the "hg" user in what follows), but many remote users can

    24 

    25 act on them.  We don't use file permissions to achieve that - instead,

    25 To give a user access to the repository, place their key in an

    26 developers log in as the "hg" user when they connect to the repository

    26 appropriately-named subdirectory of "/etc/mercurial-server/keys" and run

    27 host using ssh, using ssh URLs of the form

    27 "/etc/mercurial-server/refresh-auth". You can then control what access they have

    28 "ssh://hg@repository-host/repository-name".  A restricted shell

    28 to what repositories by editing the control file

    29 prevents them from using this access for unauthorized purposes.

    29 "/etc/mercurial-server/access.conf", which can match the names of these keys

    30 Developers are authenticated only using SSH keys; no other form of

    30 against a glob pattern. 

    31 authentication is supported.

    31 

    32 For convenient remote control of access, you can instead (if you have the

    33 privileges) make changes to a special repository called "hgadmin", which

    34 contains its own "access.conf" file and "keys" directory. Changes pushed to this

    35 repository take effect immediately. The two "access.conf" files are

    36 concatenated, and the keys directories merged.

    35 You will need 

    40 You and all developers using this system will need an SSH public key, and will

    36 

    41 almost certainly want to be running ssh-agent (or its equivalent, eg Pageant

    37 - "sudo" installed

    42 under Windows). If you're not familiar with ssh-agent, you should learn about

    38 - "sudo" root privileges

    43 that before using this.

    39 - an ssh-key set up with ssh-agent

    44 

    40 

    45 In what follows, certain operations (eg installing mercurial-server itself) have

    41 Ensure there is no user called "hg" on the repository host, and run

    46 to be done on the repository server (which we call "repository-host"), but any

    42 "./install" to create them. You are now the sole user able to change

    47 operation that involves checking in or out of Mercurial can be done wherever is

    43 and create repositories on this repository host.  To give access to

    48 most convenient to you; the most usual arrangment would be that you'd do these

    44 others, check out hgadmin - as yourself, and on whichever host is most

    49 things at the machine you sit at, and on which you run ssh-agent, which is what

    45 convenient, but using the ssh-key with which you set up the

    50 authenticates you when you talk to the repository server.

    46 repository:

    51 

    47 

    52 Ensure there is no user called "hg" on the repository host, and run "./install".

    48    mkdir ~/hg

    53 This installs the mercurial-server files and control files, and creates and sets

    49    cd ~/hg

    54 up the "hg" user.

    50    hg clone ssh://hg@repository-host/hgadmin

    55 

    51    cd hgadmin

    56 Place your SSH public key in the directory "/etc/mercurial-server/keys/root". I

    52 

    57 suggest creating yourself a directory and naming the key after your hostname (ie

    53 You can now add other users by putting their keys in an appropriate

    58 the file is called something like

    54 subdirectory of the "keys" directory, and control their access by

    59 "/etc/mercurial-server/keys/root/yourname/yourhostname") so that you can easily

    55 editing hg-ssh-access.conf.  Changes will take effect as soon as you

    60 manage users who have a different key on each host they use. Then run

    56 push them to "ssh://hg@repository-host/hgadmin".

    61 "/etc/mercurial-server/refresh-auth".

    57 

    62 

    58 Users authorized to do so can now also create new repositories on this

    63 The repository is now ready to use, and you are now the sole user able to change

    59 host with "clone":

    64 and create repositories on this repository host.  

    60 

    65 

    61   hg clone . ssh://hg@repository-host/my-project-name

    66 CREATING REPOSITORIES

    62 

    67 

    63 HG-SSH-ACCESS.CONF

    68 To create a new repository, you clone a local repository onto the remote server.

    64 

    69 So if you want a new empty repository called "myproject", you can do (as

    65 Each line of hg-ssh-access.conf has the following syntax:

    70 yourself):

    71 

    72     hg init myproject

    73     hg clone myproject ssh://hg@repository-host/myproject

    74 

    75 ADDING OTHER USERS

    76 

    77 Because your key is in the "keys/root" subdirectory, you have the equivalent of

    78 "root privileges" over mercurial-server (not the whole computer, just

    79 mercurial-server). You can add other root users by putting their keys next to

    80 yours, or you can make less privileged users by putting their keys in the

    81 "keys/users" subdirectory - these users will be able to read and write to any

    82 repository (except one - see below) but will not be able to create new

    83 repositories. As always, when you change "/etc/mercurial-server/keys" you need

    84 to re-run "/etc/mercurial-server/refresh-auth".

    85 

    86 USING HGADMIN

    87 

    88 It can be inconvenient to log on to the repository server, become root, copy

    89 keys around, and run "refresh-auth" every time you want to change user

    90 privileges. This is where mercurial-server shines :-) Suppose you have another

    91 user's SSH public key in the file "/tmp/theirkey" (on the machine you sit at,

    92 not necessarily the repository server) and you want to give them user-level

    93 access to the repository server. Run these commands:

    94 

    95     hg clone ssh://hg@repository-server/hgadmin

    96     cd hgadmin

    97     mkdir keys/user/thatuser

    98     cp /tmp/theirkey keys/user/thatuser/theirhostname

    99     hg add

   100     hg commit -m "Added key for thatuser"

   101     hg push

   102 

   103 In other words, hgadmin is a version controlled version of

   104 "/etc/mercurial-server/keys", and changes to it take effect immediately. Only

   105 "keys/root" users can act on "hgadmin" - those with keys in "keys/users" are

   106 locked out. Multiple admins can use Mercurial's version control to cooperate on

   107 controlling access to the repository server in a natural way. You can also add

   108 "root" users by putting their key in the "keys/root" directory in just the same

   109 way - these users will now be able to control hgadmin and create new

   110 repositories just as you can.

   111 

   112 ACCESS.CONF

   113 

   114 Out of the box, there are just two kinds of users: the ones with keys in

   115 "keys/root" and those in "keys/users". However, you can change this by editing

   116 "access.conf". There are two "access.conf" files, one in "/etc/mercurial-server"

   117 and one in "hgadmin"; the two are simply concatenated before being read.

   118 

   119 Each line of access.conf has the following syntax:

   166 LOCKING YOURSELF OUT

   226 LOCKED OUT?

   167 

   227 

   168 If you find yourself "locked out" - that is, that you no longer have

   228 Once you're working with "hgadmin", it can be convenient to remove all the keys

   169 the permissions needed in hgadmin - you can break back in again if

   229 in "/etc/mercurial-server/keys" and all the entries in

   170 you're able to become the "hg" user on the repository host.  Once you

   230 "/etc/mercurial-server/access.conf" and use hgadmin to control everything. If

   171 are that user, delete ~hg/.ssh/authorized_keys (to stop any user who

   231 you find yourself locked out, you can get back in again by restoring some of the

   172 might have access but shouldn't from using the repository while you

   232 entries you removed from these files - remember,

   173 fix things).  Then go into ~hg/repos/hgadmin, do an "hg update", edit

   233 "/etc/mercurial-server/access.conf" takes precedence over the "access.conf" in

   174 things to your satisfaction, and commit the change.  Finally, run

   234 "hgadmin".

   175 

   176 ~hg/admin/mercurial-server/refresh-auth ~hg/.ssh/authorized_keys ./hg-ssh-wrapper

   177 

   178 to regenerate ~hg/.ssh/authorized_keys.