README
changeset 163 8d73bcd75243
parent 101 8b4cdc066967
child 170 0f5e30c85fc3
equal deleted inserted replaced
162:1c0bc7d33648 163:8d73bcd75243
     1 mercurial-server
     1 mercurial-server
     2 
     2 
     3 mercurial-server makes a group of repositories available to the developers
     3 mercurial-server gives your developers remote read/write access to
     4 you choose, identified by ssh keys, with easy key and access management
     4 centralized Mercurial repositories using SSH public key authentication; it
     5 based on hg.
     5 provides convenient and fine-grained key management and access control.
     6 
     6 
     7 http://www.lshift.net/mercurial-server.html
     7 http://www.lshift.net/mercurial-server.html
     8 
     8 
     9 Copyright (C) 2008-2009 LShift Ltd.
     9 Copyright (C) 2008-2009 LShift Ltd.
    10 
    10 
    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