deleg.mkd

   1 <!-- options: toc -->
   2
   3 % delegating access control responsibilities
   4
   5 include sidebar-toc
   6
   7 Delegation allows you to divide up a large conf file into smaller groups of
   8 repos (called **subconf**s) and hand over responsibility to manage them to
   9 **sub-admin**s.  Gitolite can prevent one sub-admin from being able to set
  10 access rules for any other sub-admin's repos.
  11
  12 Delegation is achieved by combining two gitolite features: [subconf][] and the
  13 [NAME VREF][NAME].
  14
  15 # example
  16
  17 Here's a sample conf that does delegation:
  18
  19 .#! conf/vim-color
  20     @webbrowsers        = firefox lynx browsers/..*
  21     @webservers         = apache nginx servers/..*
  22     @malwares           = conficker storm ms/..*
  23         # side note: if anyone objects, we claim ms stands for "metasploit" ;-)
  24
  25     # the admin repo access probably had these 2 lines to start with:
  26     repo gitolite-admin
  27         RW+                                     = sitaram
  28     # now add these lines to the config for the admin repo
  29         RW                                      = alice bob mallory
  30         RW  VREF/NAME/conf/subs/webbrowsers     = alice
  31         RW  VREF/NAME/conf/subs/webservers      = bob
  32         RW  VREF/NAME/conf/subs/malwares        = mallory
  33         -   VREF/NAME/                          = alice bob mallory
  34
  35     # pull in these files using the "subconf" command
  36     subconf "subs/*.conf"
  37 .end
  38
  39 If you've read the [VREF][vref] part, or at least understood how [NAME
  40 VREF][NAME]s work, it should be clear that, in terms of changes to the
  41 gitolite-admin repo:
  42
  43 *   The user sitaram has no restrictins of any kind
  44 *   Users alice, bob, and mallory can only touch files within their assigned
  45     areas within conf/subs.  If they try to change any other file (keydir,
  46     conf/gitolite.conf, or something in one of the other sub-admin's areas),
  47     then the last rule kicks in and the push gets rejected.
  48
  49 Now all we need is to see what this "subconf" thing is all about.
  50
  51 # the subconf command {#subconf}
  52
  53 Subconf is exactly like the include command in syntax:
  54
  55 .#! conf/vim-color
  56     subconf "foo.conf"
  57 .end
  58
  59 but while reading the included file (as well as anything included from it),
  60 gitolite sets the "current subconf name" to "foo".
  61
  62 A "subconf" imposes some restrictions on what repos can be managed.
  63
  64 For example, while the subconf name is "foo", as in the above example,
  65 gitolite will only process "repo" lines for:
  66
  67   * A repo called "foo".
  68   * A group called "@foo", as long as the group is defined in the main conf
  69     file (i.e., *outside* "foo.conf").
  70   * A member of a group called "@foo" (again, defined outside).
  71   * A repo that matches a member of a group called "@foo" if that member is a
  72     regular expression.
  73
  74 Here's an example.  If the main conf file contains
  75
  76 .#! conf/vim-color
  77     @foo    =   aa bb cc/..*
  78 .end
  79
  80 then the subconf can only accept repo statements that refer to 'foo', '@foo',
  81 'aa', 'bb', or any repo whose name starts with 'cc/'.
  82
  83 **Note**: the subconf name "master" is special; it is the default subconf in
  84 effect for the main conf file and has no restrictions.
  85
  86 ## how the "subconf name" is derived
  87
  88 For subconf lines that look just like include statements, i.e.,
  89
  90 .#! conf/vim-color
  91     subconf "foo/bar.conf"
  92     subconf "frob/*.conf"
  93         # assume frob has files aa.conf, bb.conf
  94 .end
  95
  96 the subconf name as each file is being processed is the base name of the file.
  97 This means it would be "bar" for the first line, "aa" when processing
  98 "frob/aa.conf", and "bb" when processing "frob/bb.conf".
  99
 100 A variation of subconf exists that can explicitly state the subconf name:
 101
 102 .#! conf/vim-color
 103     subconf foo "frob/*.conf"
 104 .end
 105
 106 In this variation, regardless of what file in "frob/" is being read, the
 107 subconf name in effect is "foo".
 108
 109 # security notes
 110
 111 ## group names
 112
 113 You can use "@group"s defined in the main config file but do not attempt to
 114 redefine or extend them in your own subconf file.  If you must extend a group
 115 (say `@foo`) defined in the main config file, do this:
 116
 117 .#! conf/vim-color
 118     @myfoo  =   @foo
 119     # now do whatever you want with @myfoo
 120 .end
 121
 122 Group names you define in your subconf will not clash even if the exact same
 123 name is used in another subconf file, so you need not worry about that.
 124
 125 ## delegating pubkeys
 126
 127 Short answer: not gonna happen.
 128
 129 The delegation feature is meant only for access control rules, not pubkeys.
 130 Adding/removing pubkeys is a much more significant event than changing branch
 131 level permissions for people already on staff, and only the main admin should
 132 be allowed to do it.
 133
 134 Gitolite's "userids" all live in the same namespace.  This is unlikely to
 135 change, so please don't ask -- it gets real complicated to do otherwise.
 136 Allowing sub-admins to add users means username collisions, which also means
 137 security problems (admin-A creates a pubkey for Admin-B, thus gaining access
 138 to all of Admin-B's stuff).
 139
 140 If you feel the need to delegate even that, please just go the whole hog and
 141 give them separate gitolite instances (i.e., running on different servers, or
 142 at least under different gitolite hosting users on the same server)!