Gitolite Integration Guide

1. Running GitMS with Gitolite

From GitMS 1.3 onwards, you can run and replicate Gitolite, the popular authorization layer.

Gitolite's authorization rules are enforced based on the configuration of the gitolite.conf file in the gitolite-admin repository which is created during installation. Changes to this file are enforced when a push to this repo is received via the post-update hook within the repository.

As the rules are contained within a repository you can install GitMS to replicate this repo to allow the same authorization to be applied across multiple nodes. This section gives instructions for allowing GitMS to replicate Gitolite.

2. Requirements

2.1 SELinux

If SELinux is installed, and you want to continue using it, there are two installion options for gitolite:

• Add it to an already allowed directory such as /var/lib/gitolite.
• Add permissions to SELinux to allow the home directory of user git to be written to by httpd.

Enter the following SELinux commands to allow gitolite over apache:

	# yum -y install policycoreutils-python
	# setsebool -P httpd_enable_homedirs on
	# usermod -a -G apache git 
	# chcon -R -t httpd_sys_rw_content_t /home/gitms
	# chcon -R -t httpd_sys_rw_content_t /opt/wandisco/git-multisite/replicator/content_delivery  
	# setsebool -P httpd_can_network_connect on                    
	# setsebool -P git_system_enable_homedirs on 
	# semanage permissive -a httpd_sys_script_t     

2.2 Configure IPtables

If IPtables is active it blocks http connections as well as the GitMS replicator/UI. To allow these connections, add exceptions so that /etc/sysconfig/iptables looks like:

	*filter
	:INPUT ACCEPT [0:0]
	:FORWARD ACCEPT [0:0]
	:OUTPUT ACCEPT [11:12222]
	-A INPUT -m state --state RELATED,ESTABLISHED -j ACCEPT
	-A INPUT -p icmp -j ACCEPT
	-A INPUT -i lo -j ACCEPT
	-A INPUT -p tcp -m state --state NEW -m tcp --dport 6789 -j ACCEPT
	-A INPUT -p tcp -m state --state NEW -m tcp --dport 8080 -j ACCEPT
	-A INPUT -p tcp -m state --state NEW -m tcp --dport 80 -j ACCEPT
	-A INPUT -p tcp -m state --state NEW -m tcp --dport 8082 -j ACCEPT
	-A INPUT -p tcp -m state --state NEW -m tcp --dport 8085 -j ACCEPT
	-A INPUT -p tcp -m state --state NEW -m tcp --dport 9001 -j ACCEPT
	-A INPUT -p tcp -m state --state NEW -m tcp --dport 443 -j ACCEPT
	-A INPUT -p tcp -m state --state NEW -m tcp --dport 22 -j ACCEPT
	-A INPUT -j REJECT --reject-with icmp-host-prohibited
	-A FORWARD -j REJECT --reject-with icmp-host-prohibited
	COMMIT
	# Completed on Mon Jul 29 13:52:30 2013	
	

This increases the OUTPUT ACCEPT from 2222 to 12222 which allows outgoing connections up to port 12222.

3. Install and set up GitMS

1. Download and install your preferred version of GitMS (tarball or Rpm) under the git user and git group.
2. When nodes are inducted to each other create a replication group including both nodes.
3. Add the gitolite-admin repo to the replication group.
4. To allow for enforcement of access-control changes in Gitolite, the Gitolite environment variables must also be replicated.

3.1 Set up GitMS to replicate Gitolite variables

To allow GitMS to send the enviroment variables for gitolite across both servers the application.properties file must be updated there are 3 ways this is done listed below

3.1.1 Direct edit of application.properties file

1. Open the applications.properties file for GitMS in <gitms_installation_folder>/replicator/properties/application.properties (default install is /opt/wandisco/git-multisite/).
2. Add the following line to the bottom of the file on each server:

   gitms.hooks.env=GL_USER,GL_TID,GL_LOGFILE,GL_ADMIN_BASE,GL_REPO,GL_BINDIR,GL_LIBDIR

3. Restart the replicator for each node.

3.1.2 Curl command sent to replicator

1. Send a curl command to the replicated settings endpoint to allow the changes to be replicated out to all members inducted to the node where the command was sent.
2. Issue the following command via curl:

   # curl --header "Content-Type: application/xml" -X PUT -data @replicated_config.xml http://<ServerIP>:8082/api/configuration/replicated

   Where replicated_config.xml is a xml with the environmental variables to be replicated. As shown below:

   
   <configuration>
     <property>
        <key>gitms.hooks.env</key>
        <value>GL_USER,GL_TID,GL_LOGFILE,GL_ADMIN_BASE,GL_REPO,GL_BINDIR,GL_LIBDIR</value>
     </property>
          </configuration>
   		

   These settings will be passed out across all nodes. Confirm this by checking the applications.properties file of each node.

3.1.3 Using replicated settings script

You can use this script to send settings out to all inducted nodes as follows:

# ./replicated_settings -a <Path_to_applications.properties> -k gitms.hooks.env -v GL_USER,GL_TID,GL_LOGFILE,GL_ADMIN_BASE,GL_REPO,GL_BINDIR,GL_LIBDIR
		

Run this locally on one of Gitolite servers. Link to script : replicated_settings.sh.

3.2 Changes to gitolite-admin repo to allow replication

To allow the post-update scripts of gitolite to be run on receipt of a replicated upgrade you need to edit the gitolite-admin repo:

1. cd to the hooks folder of gitolite-admin.git repo which should be in: $HOME/repositories/gitolite-admin.git/.
2. symlink the available post-update script to rp-post-update with:

   # ln -s post-update rp-post-update

3. You can either repeat this command in each version of the repository or rsync it to all other servers.
4. Use the ls -l command to show something similar to this output:

   #   lrwxrwxrwx. 1 git  git  52 Jul 30 08:40 post-update -> /home/git/.gitolite/hooks/gitolite-admin/post-update
   #   lrwxrwxrwx. 1 git  git  11 Jul 30 11:23 rp-post-update -> post-update
   #   lrwxrwxrwx. 1 git  git  39 Jul 30 08:40 update -> /home/git/.gitolite/hooks/common/update
   			

5. Clone the gitolite-admin repo using this command as admin user on client to begin configuring Gitolite:

   # git clone git@<server_address>:gitolite-admin

6. Changes made should now be replicated and enforced by all instances of Gitolite in the replication-group.

4. Deploy over SSH

To run Gitolite and GitMS over SSH:

1. Log into the git user in the home directory and create a bin folder.
2. Add this folder to $PATH by appending this line to .bashrc or .bashrc_profile of git user:

   # export PATH=$PATH:$HOME/bin

   You may need to do source .bashrc, or log out and log back in, to get changes to take effect. echo $PATH should show your new bin folder at the end.
3. Scp the admin.pub key from the client machine to git user's home directory on the Gitolite server.
4. Get the Gitolite installation folder via Git with:

   # git clone git://github.com/sitaramc/gitolite

5. As the git user, run the following commands from home directory:

   #  gitolite/install -ln
   #  gitolite setup -pk $HOME/admin.pub  ( or key of which ever user wish to make first admin )	
   			

6. Repeat this on both nodes with the same admin.pub key. You should have a repositories folder in home directory with two repos present: gitolite-admin.git and testing.git
7. To test that the setup is correct, from client machine, run this command as admin user:

   # git clone git@<serveraddress>:gitolite-admin

   You should be able to successfully clone out the gitolite-admin repo. This repo will have a single commit in git logs for Gitolite setup:

   #  cd gitolite-admin
   #  git log
   #  commit 21729090fb8c5cc55a6050f728a85b99f352e177
   #  Author: git on gitolite.domain <git@gitolite.domain>
   #  Date:   Wed Jul 30 08:40:10 2014 -0400
   #
   #  gitolite setup -pk /home/git/admin.pub	
   			

8. As this commit is different on each node, you need to get the repository in a consistent state by rsyncing the node between each server. From /home/git/repositories run:

   # rsync -r gitolite-admin.git root@<otherServerIP>:/home/git/repositories/gitolite-admin.git

9. Then on the other server change ownership of the repo to git:git

   # chown -R git:git gitolite-admin.git

10. cd into the admin repo and check the git log again the commit message should match the other version of the gitolite-admin repo.

5. Deploy over HTTP

5.1 Starting requirements

Make sure that you have istalled and set up GitMS and Gitolite before working through this section.

5.2 Install Apache and SSL support

# yum -y install httpd

# yum -y install httpd mod_ssl
	

5.3 Create passwd file

1. htpasswd -c /var/www/gitolite.passwd <Username>
2. Change the ownership of the passwd file:

   chown apache:apache /var/www/gitolite.passwd

5.4 Set up Gitolite to authenticate over HTTP

1. Edit .gitolite.rc in the gitolite installation directory, /home/git, in the example.
2. Add the following line to the top of the file:

   $ENV{PATH} .= ":/home/git/bin";

   Replace "/home/git/bin" with the bin directory of gitolite.
3. Create folders in the httpd home folder. This defaults to /var/www/ on centos and oracle linux:

   # mkdir /var/www/git /var/www/bin

4. Correct the permissions and ownership of the new folders:

   # chown -R apache:apache /var/www/git
   # chown -R git:git /var/www/bin
   # chmod -R 0755 /var/www/git /var/www/bin
   			

5. In the /var/www/bin folder create "gitolite-suexec-wrapper" script and add the following lines:

   #!/bin/bash
   #
   # Suexec wrapper for gitolite-shell
   #
   
   export GIT_PROJECT_ROOT="/home/git/repositories"
   export GITOLITE_HTTP_HOME="/home/git"
   
   ${GITOLITE_HTTP_HOME}/gitolite/src/gitolite-shell
   			

   where GIT_PROJECT_ROOT is the repositories directory for gitolite and GITOLITE_HTTP_HOME is the directory that contains Gitolite.
6. Give this script the permissions 0700:

   # chmod 0700 gitolite-suexec-wrapper
   # chown git:git gitolite-suexec-wrapper
   			

7. Create gitolite.conf in the /etc/httpd/conf.d folder and add the following lines:

   <VirtualHost *:80>
       ServerName        git.example.com
       ServerAlias       git
       ServerAdmin       you@example.com
   
       DocumentRoot /var/www/git
       <Directory /var/www/git>
           Options       None
           AllowOverride none
           Order         allow,deny
           Allow         from all
       </Directory>
   
       SuexecUserGroup git git
       ScriptAlias /git/ /var/www/bin/gitolite-suexec-wrapper/
       ScriptAlias /gitmob/ /var/www/bin/gitolite-suexec-wrapper/
   
       <Location /git>
           AuthType Basic
           AuthName "Git Access"
           Require valid-user
           AuthUserFile /var/www/gitolite.passwd
       </Location>
   </VirtualHost>
   			

5.4.1 Allow git pushes

1. Change to the directory were the repo is:

   su - gitms -s /bin/bash
   cd /home/gitms/repos/bar.git
   git config http.receivepack true
   git config core.sharedRepository group	
   			

2. Do this in each repo and on all replicas, i.e. each version of repo1 on each node.
3. Restart Apache:

   # service httpd restart

You should now be able to authenticate through Apache and apply authorization rules to users coming in over http.

6. Deploy over HTTPS

To allow authentication of users over HTTPS begin by following the setup steps for HTTP.

6.1 Generate certificates

An easy tool to generate certificates is easy-rsa. You need to have the Epel rep installed to use this:

# wget http://dl.fedoraproject.org/pub/epel/6/i386/epel-release-6-8.noarch.rpm
# rpm -Uvh epel-release-6-8.noarch.rpm
# yum install easy-rsa
# cp -r /usr/share/easy-rsa/2.0 .
# cd 2.0/
# source vars
# ./clean-all
# ./build-ca
# ./build-key-server gitolite1 (when prompted for the CommonName use the system IP address if the system does not have a register DNS name)
	

Copy a cert and key into /etc/apache on each node:

# cp ./keys/gitolite1.crt /etc/httpd
# cp ./keys/gitolite1.key /etc/httpd
# chown apache:apache /etc/httpd/gitolite1.crt /etc/httpd/gitolite1.key	
	

Add conf file for HTTPS

1. In the apache conf files add a conf file for https in /etc/httpd/conf.d/gitolitehttps.conf.
2. Add the following lines to this file:

   <VirtualHost *:443>
   DocumentRoot /var/www/git
   ServerName git.example.com
   RewriteEngine On
   RewriteCond %{REMOTE_USER} ^(.*)$
   RewriteRule ^(.*)$ - [E=R_U:%1]
   RequestHeader set X-Remote-User %{R_U}e
   SSLEngine on
   SSLCertificateFile /etc/httpd/gitolite1.crt
   SSLCertificateKeyFile /etc/httpd/gitolite1.key
    DocumentRoot /var/www/git
       <Directory /var/www/git>
           Options        +ExecCGI
           AllowOverride none
           Order         allow,deny
           Allow         from all
       </Directory>
   
       SuexecUserGroup git git
       ScriptAlias /git/ /var/www/bin/gitolite-suexec-wrapper.sh/
       ScriptAlias /gitmob/ /var/www/bin/gitolite-suexec-wrapper.sh/
   
       <Location /git>
           AuthType Basic
           AuthName "Git Access"
           Require valid-user
           AuthUserFile /var/www/gitolite.passwd
       </Location>
   </VirtualHost>
   			

3. Restart Apache:

   # service httpd restart

6.1 Add the certificate to client machines

The server certificate generated will not be recognized by your client. Either:

• Turn off strict SSL checking:

  git config --global http.sslVerify false

• Add CA certificate to the client machine by adding the ./keys/ca.crt file to the set of CA certificates the client system accepts. See How do I install a root certificate?

7. Tips and warnings

1. When using Gitolite with http, any repository that you want to allow access over apache must have R=daemon added to its permissions. You can then add the Apache users' individual permissions to the repo.
2. Following installation of Gitolite, you may need to run this command to set the same permissions on new Gitolite folders as the rest of home directory.

   # restorecon -R -v /home

3. If you create a repository via Gitolite, this will be created on all nodes as a bare repo. You can then add this repository to GitMS and replicate it either in the same group as admin repository or in a separate group with its own node roles and schedule.
4. Gitolite's documentation currently states no SeLinux rules to allow gitolite over httpd. To do this, install it in a directory already allowed under SeLinux from gitolite documentation: If your server is running SELinux, and you install gitolite to /var/gitolite or another location unsupported by default SELinux policies, then SELinux will prevent sshd from reading .ssh/authorized_keys. Consider installing gitolite to /var/lib/gitolite, which is a supported location by default SELinux policies.