README
changeset 49 a886ed5fec05
parent 36 b3237aabd0fe
child 50 77d97aa18f29
equal deleted inserted replaced
48:f0cb7ad9e4ab 49:a886ed5fec05
    10 
    10 
    11 WHAT IT GIVES YOU
    11 WHAT IT GIVES YOU
    12 
    12 
    13 These tools make it easier to provide a centralized repository host
    13 These tools make it easier to provide a centralized repository host
    14 with read/write access to many repositories for many developers.
    14 with read/write access to many repositories for many developers.
    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.
    32 
    37 
    33 QUICK START
    38 QUICK START
    34 
    39 
    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:
    66 
   120 
    67 <rule> <condition> <condition> ...
   121 <rule> <condition> <condition> ...
    68 
   122 
    69 Rule is one of
   123 Rule is one of
    70 
   124 
    89 more characters including "/".
   143 more characters including "/".
    90 
   144 
    91 Blank lines and lines that start with "#" are ignored.
   145 Blank lines and lines that start with "#" are ignored.
    92 
   146 
    93 FILE CONDITIONS
   147 FILE CONDITIONS
       
   148 
       
   149 mercurial-server supports file and branch conditions, which restrict an
       
   150 operation depending on what files it modifies and what branch the work is on.
       
   151 However, the way these conditions work is subtle and can be counterintuitive -
       
   152 if you want to keep things simple, stick to user and repo conditions, and then
       
   153 things are likely to work the way you would expect.
    94 
   154 
    95 The rules file is used to make four decisions:
   155 The rules file is used to make four decisions:
    96 
   156 
    97 - Whether to allow a repository to be created
   157 - Whether to allow a repository to be created
    98 - Whether to allow access to a repository
   158 - Whether to allow access to a repository
   161 
   221 
   162 Finally, a hook in an extension is run for each changeset that is
   222 Finally, a hook in an extension is run for each changeset that is
   163 remotely committed, which uses the rules file to determine whether to
   223 remotely committed, which uses the rules file to determine whether to
   164 allow the changeset.
   224 allow the changeset.
   165 
   225 
   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. 
       
   179 
   235 
   180 THANKS
   236 THANKS
   181 
   237 
   182 Thanks for reading this far.  If you use mercurial-server, please tell
   238 Thanks for reading this far.  If you use mercurial-server, please tell
   183 me about it.
   239 me about it.