# HG changeset patch # User Paul Crowley # Date 1255432950 -3600 # Node ID 3035990989ee59c04981f29542952ae3931335d3 # Parent eace50ec642773dbc710166934d585cc45e5532d Documentation improvements diff -r eace50ec6427 -r 3035990989ee doc/configuring-access --- a/doc/configuring-access Tue Oct 13 12:03:23 2009 +0100 +++ b/doc/configuring-access Tue Oct 13 12:22:30 2009 +0100 @@ -1,10 +1,10 @@ ACCESS.CONF Out of the box, there are just two kinds of users: the ones with keys in -"keys/root" and those in "keys/users". However, you can change this by editing -"access.conf". There are two "access.conf" files, one in -"/etc/mercurial-server" and one in "hgadmin"; the two are simply concatenated -before being read. +"keys/root" and those in "keys/users". However, you can change this by +editing "access.conf". There are two "access.conf" files, one in +"/etc/mercurial-server" and one in "hgadmin"; the two are simply +concatenated before being read. Each line of access.conf has the following syntax: @@ -23,13 +23,14 @@ user= - user's key repo= - repo (as the user supplies it) -The first rule in the file which has all its conditions satisfied is used to -determine whether an action is allowed. +The first rule in the file which has all its conditions satisfied is used +to determine whether an action is allowed. If no rule is matched the +request is denied. -Paths cannot contain any special characters except "/"; glob patterns cannot -contain any special characters except "/" and "*". "*" matches zero or more -characters not including "/" while "**" matches zero or more characters -including "/". +Paths cannot contain any special characters except "/"; glob patterns +cannot contain any special characters except "/" and "*". "*" matches zero +or more characters not including "/" while "**" matches zero or more +characters including "/". Blank lines and lines that start with "#" are ignored. @@ -40,8 +41,8 @@ write user=users/** This means: keys in "root" can do anything; keys in "users" cannot create -repositories, cannot even read the hgadmin repository, but can read and write -any other repository; no other key has any access. +repositories, cannot even read the hgadmin repository, but can read and +write any other repository; no other key has any access. More advanced access configuration is covered in file-conditions. diff -r eace50ec6427 -r 3035990989ee doc/file-conditions --- a/doc/file-conditions Tue Oct 13 12:03:23 2009 +0100 +++ b/doc/file-conditions Tue Oct 13 12:22:30 2009 +0100 @@ -3,10 +3,11 @@ Read configuring-access before you read this. mercurial-server supports file and branch conditions, which restrict an -operation depending on what files it modifies and what branch the work is on. -However, the way these conditions work is subtle and can be counterintuitive - -if you want to keep things simple, stick to user and repo conditions, and then -things are likely to work the way you would expect. +operation depending on what files it modifies and what branch the work is +on. However, the way these conditions work is subtle and can be +counterintuitive - if you want to keep things simple, stick to user and +repo conditions, and then things are likely to work the way you would +expect. File and branch conditions are added to the conditions against which a rule matches, just like user and repo conditions; they have this form: @@ -14,8 +15,8 @@ file= - file in the repo branch= - name of the branch -However, in order to understand what effect adding these conditions will have, -it helps to understand how and when these rules are applied. +However, in order to understand what effect adding these conditions will +have, it helps to understand how and when these rules are applied. The rules file is used to make four decisions: @@ -24,35 +25,35 @@ - Whether to allow a changeset on a particular branch at all - Whether to allow a changeset to change a particular file -When the first two of these decisions are being made, nothing is known about -what files might be changed, and so all file conditions automatically succeed -for the purpose of such decisions. This means that doing tricky things with -file conditions can have counterintuitive consequences: +When the first two of these decisions are being made, nothing is known +about what files might be changed, and so all file conditions automatically +succeed for the purpose of such decisions. This means that doing tricky +things with file conditions can have counterintuitive consequences: -- You cannot limit read access to a subset of a repository with a "read" rule -and a file condition: any user who has access to a repository can read all of -it and its full history. Such a rule can only have the effect of masking a -later "write" rule, as in this example: +- You cannot limit read access to a subset of a repository with a "read" +rule and a file condition: any user who has access to a repository can read +all of it and its full history. Such a rule can only have the effect of +masking a later "write" rule, as in this example: read repo=specialrepo file=dontwritethis write repo=specialrepo -allows all users to read specialrepo, and to write to all files *except* that -any changeset which writes to "dontwritethis" will be rejected. +allows all users to read specialrepo, and to write to all files *except* +that any changeset which writes to "dontwritethis" will be rejected. - For similar reasons, don't give "init" rules file conditions. -- Don't try to deny write access to a particular file on a particular branch - -a developer can write to the file on another branch and then merge it in. -Either deny all writes to the branch from that user, or allow them to write to -all the files they can write to on any branch. In other words, something like -this will have the intended effect: +- Don't try to deny write access to a particular file on a particular +branch - a developer can write to the file on another branch and then merge +it in. Either deny all writes to the branch from that user, or allow them +to write to all the files they can write to on any branch. In other words, +something like this will have the intended effect: write user=docs/* branch=docs file=docs/* -But something like this will not have the intended effect; it will effectively -allow these users to write to any file on any branch, by writing it to "docs" -first: +But something like this will not have the intended effect; it will +effectively allow these users to write to any file on any branch, by +writing it to "docs" first: write user=docs/* branch=docs write user=docs/* file=docs/* diff -r eace50ec6427 -r 3035990989ee doc/how-it-works --- a/doc/how-it-works Tue Oct 13 12:03:23 2009 +0100 +++ b/doc/how-it-works Tue Oct 13 12:22:30 2009 +0100 @@ -18,6 +18,7 @@ repository called "hgadmin". A hook in this repository re-runs "refresh-auth" on the most recent version after every push. -Finally, hook in an extension is run for each changeset that is remotely -committed, which uses the rules file to determine whether to allow the -changeset. +When users try to commit new changesets, a hook is run which consults the +rules file to decide whether to allow the changeset into the repository. +This can depend not only on the user and the repository, but also the +branch and files in the changeset.