From 6efea9d7a30d61023807879b2dd9d7c7f6adb268 Mon Sep 17 00:00:00 2001 From: Sitaram Chamarty Date: Sun, 25 Sep 2011 07:52:45 +0530 Subject: [PATCH] (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 --- doc/admin-defined-commands.mkd | 88 +++++++++++++++++++++------------- 1 file changed, 55 insertions(+), 33 deletions(-) diff --git a/doc/admin-defined-commands.mkd b/doc/admin-defined-commands.mkd index 7b2bdbe..fa2d2b7 100644 --- a/doc/admin-defined-commands.mkd +++ b/doc/admin-defined-commands.mkd @@ -1,11 +1,11 @@ ## admin defined commands -**WARNING: Use this feature only if you really really know what you're doing. -If you come back to me saying this feature caused a problem, I will only -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!** +Summary: this document describes a mechanism to allow users controlled access +to specific programs or scripts, without giving them full shell access. -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: * deleting/trashing repos * enable/disable push access temporarily * (bonus) restricted admin + * how this feature came about ---- @@ -27,36 +28,29 @@ In this document: ### background -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. +Allowing users to get a shell is a no-no if you're using gitolite, but there +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 -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! +However, as the warning at the top says, careless use could allow users to +defeat this security and get a shell. Every command you approve must be +checked to be sure it cannot be compromised. -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 -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 -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? + @@ -130,9 +124,10 @@ as follows (don't use this exact code yet though): perl -I$GL_BINDIR -Mgitolite -e "cli_repo_rights('reponame')" -which will print two space-separated words, something like `_____R__W u1` or -maybe `____@R_@W `. (The former is the response for a wildcard repo -created by user `u1`, the latter is for a non-wildcard repo) +which will print two space-separated words: permissions and owner. Something +like `_____R__W u1` or maybe `____@R_@W `. (The `u1` indicates the +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 `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/ [lazy]: http://c2.com/cgi/wiki?LazinessImpatienceHubris [wild]: http://sitaramc.github.com/gitolite/doc/wildcard-repositories.html + +---- + + + +### how this feature came about + + + +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*. + + +