You should really never need to directly modify the Gitolite section of the authorized_keys
file.
The idea of the @suffix
addition to keyfile pathnames is that it allows the administrator to easily add multiple keys for a single Gitolite user. In your case, keydir/alex@workbox.pub
and keydir/alex@homebox.pub
are both mapped to a single Gitolite user named alex
. This is usually what you want if both of those keys are “owned” by the same person; it lets you just use alex
in the configuration file instead of having to mention both keyfile names. If those keys are owned by different people (or you want to enforce different access restrictions for a person’s different keys), then you will need to name them slightly differently (either use a separator other than @
, or include at least one period between the @
and .pub
).
Multiple Keys per User
The Gitolite documentation section named “multiple keys per user” describes the ways you can configure multiple keys for a single Gitolite user. There are two main ways:
- put files named
username.pub
in different subdirectories of keydir
(the newer method),
- put an
@
suffix after the username (the older method, which has sometimes been difficult for Gitolite admins to grok).
With the subdirectory method, you would use pathnames like these:
keydir/workbox/alex.pub
keydir/homebox/alex.pub
With the suffix method, you would use pathnames like these:
keydir/alex@workbox.pub
keydir/alex@homebox.pub
All of the above pathnames supply keys that will authenticate as the Gitolite user named alex
(no @
in the user’s name); you would use (e.g.) RW+ = alex
in the configuration file. These methods (only using a portion of the key’s pathname to form the Gitolite username) let the admin add (and remove) keys for Gitolite users without having to edit the configuration file every time someone wants to use a new key (or loses access to (or control of) an old key).
For example, if alex
gets a new mobile device, you could add keydir/mobile/alex.pub
or keydir/alex@mobile.pub
to give that key access to everything that alex
can already access.
Email-style Usernames
There is a limitation to the suffix method: the suffix must not contain a period. This limitation exists so that you can use email addresses as usernames; you can still use suffixes (or subdirectories) with such usernames. The following key pathnames could be used to supply keys for the username jane@gmail.com
(@gmail.com
is a part of username):
keydir/external/jane@gmail.com.pub
keydir/jane@gmail.com@remotebox.pub
This jane@gmail.com
user is distinct from a plain jane
user.
Note: By manually adding an @workbox
suffix to the authorized_keys
entry, you effectively forced Gitolite to use an email-type username that contained no period (based on how the keydir pathnames are parsed into usernames, this is normally impossible).
Which to Use?
It seems like subdirectories make the most sense when you expect to be able to fit your users’ keys into a limited number of categories (home, work, mobile, etc.). The @
-suffixes seem useful if you have one-off keys that do not fit in any particular category.
Independent of subdirectory/suffix, email-style usernames might be useful for anyone that does not otherwise have a canonical username inside your organization (e.g. a temporary outside contractor).
Summary
Gitolite usernames are derived from the pathnames under keydir
, but the are not identical to the filenames used there. Specifically, the keydir
pathnames are mapped to usernames by stripping any subdirectories and removing the .pub
extension along with any @
suffixes (as long as there is no period after the @
—otherwise the @
is treated as part of an email-style username).
If you have a situation where a single person wants to use multiple keys, then you should probably use one of the above methods (subdirectories, or @
suffix (without a period)) to let you map multiple keys to a single Gitolite username.
Example: install keydir/workbox/alex.pub
and keydir/homebox/alex.pub
, then use alex
in the configuration file (giving equal access to both keys).
If you have keys for different people that you want to give similar names, or you want to authorize different access for a single person’s various keys (home access is read only?), then you should use a separator other than @
between the distinguishing parts of the username (or make sure there is a period after the @
so it is treated as an email-style username).
Example: install keydir/workbox/alex.pub
, keydir/homebox/alex-ro.pub
, and mobile/alex-ro.pub
, then use alex
and alex-ro
in the configuration file (e.g. in some way that gives alex-ro
read-only access, while alex
gets read-write access).