Difference between revisions of "Gitolite"

From ArchWiki
Jump to: navigation, search
(IdentityFile does not exist, its Identityfile)
(Added Troubleshooting Section with information regarding about locked accounts.)
 
(35 intermediate revisions by 11 users not shown)
Line 1: Line 1:
 
[[Category:Version Control System]]
 
[[Category:Version Control System]]
[https://github.com/sitaramc/gitolite/wiki/ Gitolite] allows you to host Git repositories easily and securely.
+
[[ja:Gitolite]]
 +
[https://github.com/sitaramc/gitolite/wiki/ Gitolite] allows you to host Git repositories for multiple users easily and securely.
  
 
== Installation ==
 
== Installation ==
{{AUR|gitolite-git}} is available in the [[Arch User Repository]].
+
[[Install]] the {{Pkg|gitolite}} package.
 
+
It is also available on [https://github.com/sitaramc/gitolite/tree/master github], where you can find the last update.
+
  
 
== Configuration ==
 
== Configuration ==
Add a user
+
Installing gitolite automatically adds the ''gitolite'' user to the system, with home directory {{ic|/var/lib/gitolite}}.
# useradd -m -U -r -s /bin/bash -d /srv/git git
+
# su - git
+
$ gitolite setup -pk id_rsa.pub
+
  
Add to your work-machine's ~/.ssh/config:
+
=== Admin SSH access ===
Host server
+
HostName 192.168.12.2
+
User git
+
### IdentityFile specifies the private ssh-key
+
Identityfile ~/.ssh/id_rsa
+
  
 +
To give you admin access, copy your SSH public key to {{ic|/var/lib/gitolite/''username''.pub}}, where {{ic|username}} is your username.
 +
# install -o gitolite -g gitolite ~/.ssh/id_rsa.pub /var/lib/gitolite/''username''.pub
  
Do NOT add repos or users directly on the server! You MUST manage the server by cloning the special 'gitolite-admin' repo on your workstation:
+
Then run the Gitolite setup script as the ''gitolite'' user.
  $ git clone server:gitolite-admin
+
# su - gitolite
 +
$ gitolite setup -pk ''username''.pub
 +
 
 +
This puts your public key into the gitolite-admin keydir
 +
and gives your username RW+ access to the gitolite-admin repository
 +
 
 +
You can now remove the SSH public key you copied and exit the ''gitolite'' user shell
 +
$ rm ''username''.pub
 +
$ exit
 +
 
 +
Now as your user you can check that everything went correctly
 +
{{hc|$ ssh gitolite@''hostname'' info|
 +
hello ''username'', this is gitolite@''hostname'' running gitolite3 v3.6.2 on git 2.3.3
 +
 
 +
R W    gitolite-admin
 +
R W    testing
 +
}}
 +
 
 +
Do NOT add repositories or users directly as ''gitolite'' on the server!
 +
You MUST manage the server by cloning the special ''gitolite-admin'' repository
 +
  $ git clone gitolite@''hostname'':gitolite-admin
 +
 
 +
For reference see [https://github.com/sitaramc/gitolite/ Gitolite]
 +
 
 +
=== Adding http(s) access via Apache (with basic authentication) ===
 +
 
 +
We need to create an suEXEC wrapper script. To satisfy suEXEC's security requirements, the script and the directory containing it must be owned by {{ic|gitolite:gitolite}} and below {{ic|/srv/http}} in the directory hierarchy. For this example, we create the directory as {{ic|/srv/http/git/cgi-bin}}.
 +
# install -o gitolite -g gitolite -d /srv/http/git/cgi-bin
 +
 
 +
Create an suEXEC wrapper for the gitolite shell with the contents below. For this example, we create it as {{ic|/srv/http/git/cgi-bin/gitolite-suexec-wrapper}}.
 +
{{hc|/srv/http/git/cgi-bin/gitolite-suexec-wrapper|2=
 +
#!/usr/bin/bash
 +
#
 +
# suEXEC wrapper for gitolite-shell
 +
#
 +
 
 +
export GIT_PROJECT_ROOT=/var/lib/gitolite/repositories
 +
export GITOLITE_HTTP_HOME=/var/lib/gitolite
 +
 
 +
exec /usr/lib/gitolite/gitolite-shell
 +
}}
 +
 
 +
Make the wrapper executable and owned by {{ic|gitolite:gitolite}}.
 +
# chown gitolite:gitolite /srv/http/git/cgi-bin/gitolite-suexec-wrapper
 +
# chmod 0755 /srv/http/git/cgi-bin/gitolite-suexec-wrapper
 +
 
 +
Create an empty password database file, owned by {{ic|gitolite:http}}
 +
# install -o gitolite -g http -m 0640 /dev/null /srv/http/git/htpasswd
 +
 
 +
Apache's basic authentication mechanism is separate from ssh, and therefore requires a separate set of credentials. Create your web users using {{ic|htpasswd}}.
 +
# htpasswd /srv/http/git/htpasswd ''username''
 +
 
 +
Add the following to your Apache vhost configuration:
 +
{{bc|
 +
SuexecUserGroup gitolite gitolite
 +
ScriptAlias /git/ /srv/http/git/cgi-bin/gitolite-suexec-wrapper/
 +
 
 +
<Directory /srv/http/git/cgi-bin>
 +
    Require all granted
 +
</Directory>
 +
 
 +
<Location /git>
 +
    AuthType Basic
 +
    AuthName "Git Access"
 +
    AuthBasicProvider file
 +
    AuthUserFile /srv/http/git/htpasswd
 +
    Require valid-user
 +
</Location>
 +
}}
 +
 
 +
Restart {{ic|httpd.service}}.
 +
 
 +
Finally, in the gitolite-admin repository you cloned in the previous section, edit {{ic|conf/gitolite.conf}}, add an {{ic|1=R = daemon}} access rule to all repositories you want to make available via http, and push the changes.
  
 
== Add users ==
 
== Add users ==
 +
 +
=== ssh users ===
 
Ask each user who will get access to send you a public key. On their workstation generate the pair of ssh keys:
 
Ask each user who will get access to send you a public key. On their workstation generate the pair of ssh keys:
 
  $ ssh-keygen
 
  $ ssh-keygen
Line 35: Line 102:
  
 
Commit and push the changes them:
 
Commit and push the changes them:
  git commit -a
+
  $ git commit -a
  git push
+
  $ git push
  
== Gitosis-like usernames ==
+
=== http(s) users ===
If you want to distinguish users with the same login (like username@server1, username@server2) you may want to do the following (for gitolite-3.04-1):
+
  
* edit /usr/lib/gitolite/triggers/post-compile/ssh-authkeys and replace
+
User management for http(s) is more suitable for single-user setups. To add a new user or to change an existing user's password:
 +
# htpasswd /srv/http/git/htpasswd ''username''
 +
 
 +
== Gitosis-like ssh usernames ==
 +
If you want to distinguish users with the same login (like {{ic|username@server1}}, {{ic|username@server2}}) you may want to do the following (tested with {{Pkg|gitolite}} 3.04-1):
 +
 
 +
* edit {{ic|/usr/lib/gitolite/triggers/post-compile/ssh-authkeys}} and replace
 
  $user =~ s/(\@[^.]+)?\.pub$//;    # baz.pub, baz@home.pub -> baz
 
  $user =~ s/(\@[^.]+)?\.pub$//;    # baz.pub, baz@home.pub -> baz
 
by
 
by
 
  $user =~ s/\.pub$//;              # baz@home.pub -> baz@home
 
  $user =~ s/\.pub$//;              # baz@home.pub -> baz@home
* update authorized_keys file (for example, by pushing into gitolite-admin repo)
+
* update authorized_keys file (for example, by pushing into the ''gitolite-admin'' repository)
 +
 
 +
== Troubleshooting ==
 +
In case you cannot log in with the gitolite account, it may be caused by the account being locked, and depending of your ssh configuration.
 +
 
 +
If you have done some SSH hardening, it may be the cause of this behavior, as noted in [http://arlimus.github.io/articles/usepam/ SSH and locked users Article] and [http://unix.stackexchange.com/questions/193066/how-to-unlock-account-for-public-key-ssh-authorization-but-not-for-password-aut Unix & Linux StackExchange - How to unlock account for public key ssh authorization, but not for password authorization].
 +
 
 +
To solve this you have to allow PAM in {{ic|sshd_config}} or unlock the account by:
 +
 
 +
# usermod -p '*' gitolite
 +
 
 +
{{hc|# nano /etc/passwd|
 +
...
 +
gitolite:*:16199:0:99999:7:::
 +
...}}
 +
 
 +
{{Warning|Do not leave the account in the state left by {{ic|passwd -u}} (with a blank password field). Doing that will allow logins without entering a password!}}
  
 
== See also ==
 
== See also ==
http://sitaramc.github.com/gitolite/index.html
+
* [http://sitaramc.github.com/gitolite/index.html Gitolite Site]
 +
* [http://arlimus.github.io/articles/usepam/ SSH and locked users Article]
 +
* [http://unix.stackexchange.com/questions/193066/how-to-unlock-account-for-public-key-ssh-authorization-but-not-for-password-aut Unix & Linux StackExchange - How to unlock account for public key ssh authorization, but not for password authorization]

Latest revision as of 16:27, 29 July 2016

Gitolite allows you to host Git repositories for multiple users easily and securely.

Installation

Install the gitolite package.

Configuration

Installing gitolite automatically adds the gitolite user to the system, with home directory /var/lib/gitolite.

Admin SSH access

To give you admin access, copy your SSH public key to /var/lib/gitolite/username.pub, where username is your username.

# install -o gitolite -g gitolite ~/.ssh/id_rsa.pub /var/lib/gitolite/username.pub

Then run the Gitolite setup script as the gitolite user.

# su - gitolite
$ gitolite setup -pk username.pub

This puts your public key into the gitolite-admin keydir and gives your username RW+ access to the gitolite-admin repository

You can now remove the SSH public key you copied and exit the gitolite user shell

$ rm username.pub
$ exit

Now as your user you can check that everything went correctly

$ ssh gitolite@hostname info
hello username, this is gitolite@hostname running gitolite3 v3.6.2 on git 2.3.3

 R W    gitolite-admin
 R W    testing

Do NOT add repositories or users directly as gitolite on the server! You MUST manage the server by cloning the special gitolite-admin repository

$ git clone gitolite@hostname:gitolite-admin

For reference see Gitolite

Adding http(s) access via Apache (with basic authentication)

We need to create an suEXEC wrapper script. To satisfy suEXEC's security requirements, the script and the directory containing it must be owned by gitolite:gitolite and below /srv/http in the directory hierarchy. For this example, we create the directory as /srv/http/git/cgi-bin.

# install -o gitolite -g gitolite -d /srv/http/git/cgi-bin

Create an suEXEC wrapper for the gitolite shell with the contents below. For this example, we create it as /srv/http/git/cgi-bin/gitolite-suexec-wrapper.

/srv/http/git/cgi-bin/gitolite-suexec-wrapper
#!/usr/bin/bash
#
# suEXEC wrapper for gitolite-shell
#

export GIT_PROJECT_ROOT=/var/lib/gitolite/repositories
export GITOLITE_HTTP_HOME=/var/lib/gitolite

exec /usr/lib/gitolite/gitolite-shell

Make the wrapper executable and owned by gitolite:gitolite.

# chown gitolite:gitolite /srv/http/git/cgi-bin/gitolite-suexec-wrapper
# chmod 0755 /srv/http/git/cgi-bin/gitolite-suexec-wrapper

Create an empty password database file, owned by gitolite:http

# install -o gitolite -g http -m 0640 /dev/null /srv/http/git/htpasswd

Apache's basic authentication mechanism is separate from ssh, and therefore requires a separate set of credentials. Create your web users using htpasswd.

# htpasswd /srv/http/git/htpasswd username

Add the following to your Apache vhost configuration:

SuexecUserGroup gitolite gitolite
ScriptAlias /git/ /srv/http/git/cgi-bin/gitolite-suexec-wrapper/

<Directory /srv/http/git/cgi-bin>
    Require all granted
</Directory>

<Location /git>
    AuthType Basic
    AuthName "Git Access"
    AuthBasicProvider file
    AuthUserFile /srv/http/git/htpasswd
    Require valid-user
</Location>

Restart httpd.service.

Finally, in the gitolite-admin repository you cloned in the previous section, edit conf/gitolite.conf, add an R = daemon access rule to all repositories you want to make available via http, and push the changes.

Add users

ssh users

Ask each user who will get access to send you a public key. On their workstation generate the pair of ssh keys:

$ ssh-keygen

Rename each public key according to the user's name, with a .pub extension, like sitaram.pub or john-smith.pub. You can also use periods and underscores. Have the users send you the keys.

Copy all these *.pub files to keydir in your gitolite-admin repo clone. You can also organise them into various subdirectories of keydir if you wish, since the entire tree is searched.

Edit the config file (conf/gitolite.conf in your admin repo clone). See the gitolite.conf documentation (http://sitaramc.github.com/gitolite/admin.html#conf) for details on what goes in that file, syntax, etc. Just add new repos as needed, and add new users and give them permissions as required. The users names should be exactly the same as their keyfile names, but without the .pub extension

$ nano conf/gitolite.conf

Commit and push the changes them:

$ git commit -a
$ git push

http(s) users

User management for http(s) is more suitable for single-user setups. To add a new user or to change an existing user's password:

# htpasswd /srv/http/git/htpasswd username

Gitosis-like ssh usernames

If you want to distinguish users with the same login (like username@server1, username@server2) you may want to do the following (tested with gitolite 3.04-1):

  • edit /usr/lib/gitolite/triggers/post-compile/ssh-authkeys and replace
$user =~ s/(\@[^.]+)?\.pub$//;    # baz.pub, baz@home.pub -> baz

by

$user =~ s/\.pub$//;              # baz@home.pub -> baz@home
  • update authorized_keys file (for example, by pushing into the gitolite-admin repository)

Troubleshooting

In case you cannot log in with the gitolite account, it may be caused by the account being locked, and depending of your ssh configuration.

If you have done some SSH hardening, it may be the cause of this behavior, as noted in SSH and locked users Article and Unix & Linux StackExchange - How to unlock account for public key ssh authorization, but not for password authorization.

To solve this you have to allow PAM in sshd_config or unlock the account by:

# usermod -p '*' gitolite
# nano /etc/passwd
...
gitolite:*:16199:0:99999:7:::
...
Warning: Do not leave the account in the state left by passwd -u (with a blank password field). Doing that will allow logins without entering a password!

See also