7.Gitolite Integration Guide

7.1 Running Git MultiSite with Gitolite

Introduction

From Git MultiSite 1.3 onwards, it is possible to run and replicate Gitolite, the popular authorization layer.

Authentication vs Authorization

Authorization is about deciding what users are allowed to do on a system. It is distinct from and follows on from the authentication, where users are identified.

Gitolites authorization rules are enforced based on the configuration of the gitolite.conf file within the gitolite-admin repository which is created during installation. Changes to this file are enforced once a push to this repo has been recieved via post-update hook within the repository.

As the rules are contained within a repository it is possible to install GitMS to replicate this repo to allow the same authorization to be applied across multiple nodes. Outlined below is the instructions for allowing GitMS to replicate Gitolite.

7.2 Requirements

System setup
Git MultiSite	You must be running Git MultiSite 1.3 or later. Earlier versions of Git MultSite did not support the replication of environmental variables
Git	You need to have Git Replicated binaries installed on all nodes.
Java	Use Oracle Java JRE-1.7 installed on all nodes.
Security	VMs with a git user with no authorized keys file present or previous ssh configuration Generate/copy over public SSH keys for the users you wish to use on Gitolite (must not be git users). We recommend simple naming on these files eg. admin.pub, generated by ssh-keygen. Do not set a passphrase.

SELinux

If SELinux is installed, and wish to continue using it, there are two installion options for gitolite, either adding it to an already allowed directory such as /var/lib/gitolite or adding permissions to SELinux to allow the home directory of user git to be written to by httpd.

Below are the SELinux commands that need entered 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

Configure IPtables

If IPtables is active it will block Http connections aswell as the gitms replicator/UI too allow these connections add the following exceptions to iptables: /etc/sysconfig/iptables should look 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

Increased the OUTPUT ACCEPT from 2222 to 12222 (allows outgoing connections up to port 12222)

7.4 Deploy over SSH

Follow these steps if you plan to run Gitolite and Git MultiSite over SSH

Start by logging into the git user in the home directory create a bin folder
Add this folder to $PATH. By appending the below line to .bashrc or .bashrc_profile of git user
```
# export PATH=$PATH:$HOME/bin
```
May need to do "source .bashrc" or logout and back in to get changes to take effect " echo $PATH " should show your new bin folder at the end
Scp the admin.pub key from the client machine to git users home directory on Gitolite server
Get the Gitolite installation folder via Git with below command.
```
# git clone git://github.com/sitaramc/gitolite
```
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 )	
	
```
Repeat this on Both nodes with the same admin.pub key , after the last step should have a repositories folder in home directory with two repos present, a gitolite-admin.git and testing.git To test that the setup is correct from client machine run this command as admin user :
```
# git clone git@<serveraddress>:gitolite-admin
```
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	
```
From as this commit is different on each node we will need to get the repository in a consistent state this is done through ryncing the node between each server From /home/git/repositories run the following command:
```
# rsync -r gitolite-admin.git root@<otherServerIP>:/home/git/repositories/gitolite-admin.git
```
Then on other server change ownership of the repo to git:git
```
# chown -R git:git gitolite-admin.git
```
cd into the admin repo and check the git log again the commit message should match the other version of the gitolite-admin repo.

7.3 Installation and setup of GitMS

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

Setting 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

Direct edit of application.properties file

open the applications.properties file for GitMS in <gitms_installation_folder>/replicator/properties/application.properties (default install is /opt/wandisco/git-multisite/)

append 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

following this restart the replicator for each node

Curl command sent to replicator

Sending a curl command to the replicated settings endpoint will allow the changes to be replicated out to all members inducted to the node, which the command was sent to.

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 this can be confirmed by checking the applications.properties file of each node.

Using replicated settings script

The below script can also be used to send settings out to all inducted nodes the usage of this script is 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

This should be run locally on one of Gitolite servers Link to script : replicated_settings.sh

Changes to gitolite-admin repo to allow replication

To allow the post-update scripts of gitolite to be run upon receipt of a replicated upgrade we need to edit the gitolite-admin repo.

cd to the hooks folder of gitolite-admin.git repo should be in: $HOME/repositories/gitolite-admin.git/hooks.
symlink the already present post-update script to rp-post-update with command below:
```
# ln -s post-update rp-post-update
```
Can either repeat this command in each version of the repository or rsync it to all other servers.

Carrying out the "ls -l" command should show something similar to the below 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

Following this can clone the gitolite-admin repo using command below as admin user on client to begin configuring Gitolite: # git clone git@<server_address>:gitolite-admin
Changes made should now be replicated and enforced by all instances of Gitolite in the replication-group.

Deploy over HTTP

Starting Requirements

This Section will start under the assumption that the previous steps to install and set up Gitolite and GitMS have been completed and working. Setup :

Install apache
# yum -y install httpd
install ssl support
# yum -y install httpd mod_ssl

Create passwd file

htpasswd -c /var/www/gitolite.passwd <Username>

Change the ownership of the passwd file:

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

Setting up Gitolite to authenticate over HTTP

Start by editing the .gitolite.rc file, ( found in the gitolite installation directory: /home/git , in our example) add the following line to the top of the file:
```
$ENV{PATH} .= ":/home/git/bin";
replacing /home/git/bin with the bin directory of gitolite.
create folders in the httpd home folder this will default to /var/www/ on centos and oracle linux
# mkdir /var/www/git /var/www/bin
```
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
```
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 Give this script the permissions 0700
```
# chmod 0700 gitolite-suexec-wrapper
# chown git:git gitolite-suexec-wrapper
```
Next create conf file for gitolite, this will be under the /etc/httpd/conf.d folder create file gitolite.conf 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>
```
Allow git pushes

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	
```
This needs to be done in each repo and on all replicas. e.g. each version of repo1 on each node

Following this Restart Apache
```
# service httpd restart
```
Should now be able to authenticate through Apache and apply authorization rules to users coming in over http

7.6 Deploy over HTTPS

To allow authentication of users over HTTPS begin by following the set up steps above for http.

To this file add the following lines:

Generate Certificates

An easy tool to generate certificates is easy-rsa (http://openvpn.net/index.php/open-source/documentation/miscellaneous/77-rsa-key-management.html) 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

In the apache conf files add a conf file for Https in /etc/httpd/conf.d/gitolitehttps.conf

to this file add the following lines:
```
<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>
```
Following this restart Apache
```
# service httpd restart
```
Adding the certificate to client machines

The server certificate generated will not be recognized by your client. You can either turn off strict SSL checking:
```
git config --global http.sslVerify false
```
Or the CA certificate can be added to the client machine, this means adding the ./keys/ca.crt file to the set of CA certificates the client system accepts. Instructions for doing this can be found here: http://askubuntu.com/questions/73287/how-do-i-install-a-root-certificate
7.7 Tips & Warnings
1. When using Gitolite with http, any repository wish 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 may need to run command below to set same permissions on new Gitolite folders as the rest of home directory.
```
# restorecon -R -v /home
```
3. If creating a repository via Gitolite this will be created on all nodes as a bare repo, This repository can then be added to GitMS and replicated either in 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, It's answer is to install 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.
Copyright © 2010-2014 WANdisco plc.
All Rights Reserved

This product is protected by copyright and distributed under licenses restricting copying, distribution and decompilation.

Git MultiSite
Last doc build: 10:45 - Wednesday 27th August 2014