WANdisco
 Navigation:  v | Release Notes | Install | Upgrade | Administration | Reference | Gerrit | API | Glossary | Archive

Gitolite Integration Guide

1. Running Git MultiSite with Gitolite

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

Authentication vs Authorization

  • Authentication identifies users.
  • Authorization defines, with rules, what users are allowed to do on a system.

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

 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.

2.1 SELinux

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

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 Git MultiSite 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 Git MultiSite

  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 Git MultiSite 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 upon 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 Git MultiSite 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

Starting requirements

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

Install Apache and SSL support

# yum -y install httpd

# yum -y install httpd mod_ssl

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

Set up Gitolite to authenticate over HTTP

  1. Edit .gitolite.rc in the gitolite installation directory, /home/git, in our example.
  2. 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
    
  3. 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
    
  4. 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.
  5. Give this script the permissions 0700:
    # chmod 0700 gitolite-suexec-wrapper
    # chown git:git gitolite-suexec-wrapper
    
  6. 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>
    

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 set up steps above for http.

Generate certificates

An easy tool to generate certificates is easy-rsa 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:

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 Git MultiSite 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.