(doc) admin-defined commands doc fixes:

- make the warning less juvenile ;-)
  - de-emphasise the connection to wild repos; it's not as deep as the
    doc made it out to be
  - move the historical stuff out of the way
This commit is contained in:
Sitaram Chamarty 2011-09-25 07:52:45 +05:30
parent 7b8866dbf6
commit 6efea9d7a3

View file

@ -1,11 +1,11 @@
## admin defined commands ## admin defined commands
**WARNING: Use this feature only if you really really know what you're doing. Summary: this document describes a mechanism to allow users controlled access
If you come back to me saying this feature caused a problem, I will only to specific programs or scripts, without giving them full shell access.
laugh. The worse the problem, the louder I will laugh. You won't actually
hear me laughing, but you'll feel it in your bones, trust me!**
There may be other such **WARNING** sections below. **Read all of them**. **WARNING**: careless use of this feature, including inadequate review of
allowed commands or scripts, could compromise this security and allow users to
grant themselves full shell access, accidentally or otherwise.
---- ----
@ -20,6 +20,7 @@ In this document:
* <a href="#_deleting_trashing_repos">deleting/trashing repos</a> * <a href="#_deleting_trashing_repos">deleting/trashing repos</a>
* <a href="#_enable_disable_push_access_temporarily">enable/disable push access temporarily</a> * <a href="#_enable_disable_push_access_temporarily">enable/disable push access temporarily</a>
* <a href="#_bonus_restricted_admin">(bonus) restricted admin</a> * <a href="#_bonus_restricted_admin">(bonus) restricted admin</a>
* <a href="#_how_this_feature_came_about">how this feature came about</a>
---- ----
@ -27,36 +28,29 @@ In this document:
### background ### background
Gitolite was named to be short for "gitosis-lite". Someone now wants to turn Allowing users to get a shell is a no-no if you're using gitolite, but there
it into a "github-lite" :-) and even had some code to start me off thinking. are times when you want them to be able to run specific commands or custom
scripts that you (the admin) have pre-approved to be "safe". Here's how to
enable such commands.
Since my first impulse on being asked for a feature is to say no, I was However, as the warning at the top says, careless use could allow users to
casting about for a reason when he gave me one: he first made some noises defeat this security and get a shell. Every command you approve must be
about perl, then said something about rewriting it all in scheme. Nice... I checked to be sure it cannot be compromised.
resisted the urge to point him to [this][xkcd224], told him that's a great
idea and he should go for it, mentally blessing him for letting me off the
hook on coding it ;-) [Laziness][lazy] *is* the first virtue you know!
And that was that. For a couple of days. To help you with this, gitolite restricts ADCs arguments to only some very
safe characters (see `$ADC_CMD_ARGS_PATT` in `src/gitolite_rc.pm`). The code
inside the ADC, however, is *your* responsibility. The sample ADCs shipped
with gitolite (in `contrib/adc`) should be OK, but an extra pair of eyes never
hurt :-) so please review before installing them.
Soon, though, I realised that there could be a pretty big bonus in this for <font color="gray">
tightly controlled setups, so I went and coded it all anyway. See the section
on "restricted admin" for what's really exciting about this for *me*.
---- Finally, although this is a generic way to allow specific commands to be run,
most of the examples and sample ADCs pertain to allowing users to manage their
"own" repos. If that's your use case, please read
[doc/wildcard-repositories.mkd][wild] before you continue here.
It may be a good idea to read [doc/wildcard-repositories.mkd][wild] before </font>
you continue here though, because most of the uses of this feature also need
wildcard repos. (This also means you must set `$GL_WILDREPOS` to "1" in the
rc file).
The wildcard repo feature is a way to create repositories matching a pattern
(even if it as simple as `personal/CREATOR/.+`), and a way to specify two
categories of permissions for each such user-created repo.
What we want now is more than that, as you'll see in the examples below. And
I'm sure if you think of more uses you'll send them to me as "contrib"
entries, right?
<a name="_setting_it_up"></a> <a name="_setting_it_up"></a>
@ -130,9 +124,10 @@ as follows (don't use this exact code yet though):
perl -I$GL_BINDIR -Mgitolite -e "cli_repo_rights('reponame')" perl -I$GL_BINDIR -Mgitolite -e "cli_repo_rights('reponame')"
which will print two space-separated words, something like `_____R__W u1` or which will print two space-separated words: permissions and owner. Something
maybe `____@R_@W <gitolite>`. (The former is the response for a wildcard repo like `_____R__W u1` or maybe `____@R_@W <gitolite>`. (The `u1` indicates the
created by user `u1`, the latter is for a non-wildcard repo) queried repo is a wildcard repo created by user `u1`; for meanings of the "@"
see doc/report-output.mkd)
But that's cumbersome. There's a bash shell function called But that's cumbersome. There's a bash shell function called
`get_rights_and_owner` in `contrib/adc/adc.common-functions` that is much more `get_rights_and_owner` in `contrib/adc/adc.common-functions` that is much more
@ -228,3 +223,30 @@ because it's not using any wildcard repos].
[xkcd224]: http://xkcd.com/224/ [xkcd224]: http://xkcd.com/224/
[lazy]: http://c2.com/cgi/wiki?LazinessImpatienceHubris [lazy]: http://c2.com/cgi/wiki?LazinessImpatienceHubris
[wild]: http://sitaramc.github.com/gitolite/doc/wildcard-repositories.html [wild]: http://sitaramc.github.com/gitolite/doc/wildcard-repositories.html
----
<a name="_how_this_feature_came_about"></a>
### how this feature came about
<font color="gray">
Gitolite was named to be short for "gitosis-lite". Someone now wants to turn
it into a "github-lite" :-) and even had some code to start me off thinking.
Since my first impulse on being asked for a feature is to say no, I was
casting about for a reason when he gave me one: he first made some noises
about perl, then said something about rewriting it all in scheme. Nice... I
resisted the urge to point him to [this][xkcd224], told him that's a great
idea and he should go for it, mentally blessing him for letting me off the
hook on coding it ;-) [Laziness][lazy] *is* the first virtue you know!
And that was that. For a couple of days.
Soon, though, I realised that there could be a pretty big bonus in this for
tightly controlled setups, so I went and coded it all anyway. See the section
on "restricted admin" for what's really exciting about this for *me*.
</font>