README
changeset 18 538d6b198f4a
parent 15 f3654416d178
child 20 f4daa224dc7e
equal deleted inserted replaced
17:4c98440de851 18:538d6b198f4a
    51 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
    52 live in the "keys" subdirectory of a repository called "hgadmin".  A
    52 live in the "keys" subdirectory of a repository called "hgadmin".  A
    53 hook in this repository re-runs "refresh-auth" on the most recent
    53 hook in this repository re-runs "refresh-auth" on the most recent
    54 version after every push.
    54 version after every push.
    55 
    55 
       
    56 Finally, a hook in an extension is run for each changeset that is
       
    57 remotely committed, which uses the rules file to determine whether to
       
    58 allow the changeset.
       
    59 
    56 GETTING STARTED
    60 GETTING STARTED
    57 
    61 
    58 This is only one setup - it can be tweaked in many ways, and is as
    62 This is only one setup - it can be tweaked in many ways, and is as
    59 specific as it is only in the interests of brevity.
    63 specific as it is only in the interests of brevity.
    60 
    64 
    77    sudo -u hg -H -s
    81    sudo -u hg -H -s
    78    cd
    82    cd
    79    mkdir -p admin repos/hgadmin/keys/admin .ssh
    83    mkdir -p admin repos/hgadmin/keys/admin .ssh
    80    cd admin
    84    cd admin
    81    hg clone http://hg.opensource.lshift.net/hg-admin-tools
    85    hg clone http://hg.opensource.lshift.net/hg-admin-tools
    82    cp hg-admin-tools/hg-ssh-wrapper ~
    86    cp hg-admin-tools/hg-ssh-wrapper hg-admin-tools/remote-hgrc ~
    83    cd ../repos/hgadmin
    87    cd ../repos/hgadmin
    84    hg init .
    88    hg init .
    85    echo "init admin/* *" > hg-ssh-access.conf
    89    echo "init user=admin/*" > hg-ssh-access.conf
    86    cp /tmp/my-ssh-public-key keys/admin/myname
    90    cp /tmp/my-ssh-public-key keys/admin/myname
    87    hg add
    91    hg add
    88    hg commit -m "initial commit"
    92    hg commit -m "initial commit"
    89    cp ~/admin/hg-admin-tools/hgadmin-hgrc .hg/hgrc
    93    cp ~/admin/hg-admin-tools/hgadmin-hgrc .hg/hgrc
    90    ../../admin/hg-admin-tools/refresh-auth ./hg-ssh-wrapper
    94    ../../admin/hg-admin-tools/refresh-auth ./hg-ssh-wrapper
   103 You can now add other users by putting their keys in an appropriate
   107 You can now add other users by putting their keys in an appropriate
   104 subdirectory of the "keys" directory, and control their access by
   108 subdirectory of the "keys" directory, and control their access by
   105 editing hg-ssh-access.conf.  Changes will take effect as soon as you
   109 editing hg-ssh-access.conf.  Changes will take effect as soon as you
   106 push them to "ssh://hg@repository-host/hgadmin".
   110 push them to "ssh://hg@repository-host/hgadmin".
   107 
   111 
   108 Users authorized to do so can now also create new repositories on this host with "clone":
   112 Users authorized to do so can now also create new repositories on this
       
   113 host with "clone":
   109 
   114 
   110   hg clone . ssh://hg@repository-host/my-project-name
   115   hg clone . ssh://hg@repository-host/my-project-name
   111 
   116 
   112 HG-SSH-ACCESS.CONF
   117 HG-SSH-ACCESS.CONF
   113 
   118 
   114 Each line of hg-ssh-access.conf has the following syntax:
   119 Each line of hg-ssh-access.conf has the following syntax:
   115 
   120 
   116 <rule> <keypattern> <repositorypattern>
   121 <rule> <condition> <condition> ...
   117 
   122 
   118 The "rule" is either "init", "allow", or "deny".  "keypattern" is a
   123 Rule is one of
   119 glob pattern matched against the name of the key used - for example,
   124 
   120 in our initial setup "admin/myname" matches "admin/*".
   125 init - allow any operation, including the creation of new repositories
   121 "repositorypattern" is a pattern matched againt the repository name -
   126 write - allow reads and writes to this file in this repository
   122 so "hgadmin" matches "*".  Only boring characters are allowed in
   127 read - allow the repo to be read but reject matching writes
   123 patterns and key and repository names - see the source for details.
   128 deny - deny all requests
   124 Blank lines and lines that start with "#" are ignored.  The first rule
   129 
   125 to match both the key and the repository applies: "deny" will deny all
   130 A condition is a globpattern matched against a relative path, one of:
   126 matching requests, "allow" allows read/write access to existing
   131 
   127 repositories, and "init" allows that and creation of new repositories.
   132 user=<globpattern> - user's key
       
   133 repo=<globpattern> - repo (as the user supplies it)
       
   134 file=<globpattern> - file in the repo
       
   135 
       
   136 The first rule in the file which has all its conditions satisfied is
       
   137 used to determine whether an action is allowed.
       
   138 
       
   139 Paths cannot contain any special characters except "/"; glob patterns
       
   140 cannot contain any special characters except "/" and "*".  "*" matches
       
   141 zero or more characters not including "/" while "**" matches zero or
       
   142 more characters including "/".
       
   143 
       
   144 Blank lines and lines that start with "#" are ignored.
       
   145 
       
   146 FILE CONDITIONS
       
   147 
       
   148 The rules file is used to make three decisions:
       
   149 
       
   150 - Whether to allow a repository to be created
       
   151 - Whether to allow access to a repository
       
   152 - Whether to allow a changeset to change a particular file
       
   153 
       
   154 When the first two of these decisions are being made, nothing is known
       
   155 about what files might be changed, and so all file conditions
       
   156 automatically succeed for the purpose of such decisions.  This means
       
   157 that doing tricky things with file conditions can have
       
   158 counterintuitive consequences:
       
   159 
       
   160 - You cannot limit read access to a subset of a repository with a
       
   161 "read" rule and a file condition: any user who has access to a
       
   162 repository can read all of it and its full history.  Such a rule can
       
   163 only have the effect of masking a later "write" rule, as in this
       
   164 example:
       
   165 
       
   166    read repo=specialrepo file=dontwritethis
       
   167    write repo=specialrepo
       
   168 
       
   169 allows all users to read specialrepo, and to write to all files
       
   170 *except* that any changeset which writes to "dontwritethis" will be
       
   171 rejected.
       
   172 
       
   173 - For similar reasons, don't give "init" rules file conditions.
       
   174 
       
   175 THANKS
       
   176 
       
   177 Thanks for reading this far.  If you use hg-admin-tools, please tell
       
   178 me about it.
       
   179 
       
   180 Paul Crowley, 2008