Rel4tion-Wiki/maint/admin/Git_Server/Anonymous_Read_Access_with_Git_Daemon.mdwn

Gitolite itself works by default with Secure Shell (SSH) authentication to
control user access to the repositories. First the user's key is compared with
the keys stored on the server (under the 'keydir' folder in the gitolite-admin
repository), and then the configuration file (conf/gitolie.conf) is checked to
determine whether the user is allowed to do the operation they asked to do.

However, if your project is not private, e.g. it is a free software project, you
may wish to enable anonymous read-access of your repositories, so anyone with
internet access can look at the source code, download it, improve it, compile it
and run the program. Without this kind of access, only people whose keys have
been stored on the server, i.e. in the gitolite-admin repository, have access.

Git supports three protocols for anonymous read access: filesystem (the remote
repository is either on the same local filesystem or is really remote but is
accessed through a network filesystem), HTTP (the same protocol used for
downloading website content) and the git protocol, which was created for git.
We'll start with the git protocol.

Just like Gitolite uses an SSH server which waits for connection requests from
clients (team members), the git protocol access requires a server: This is the
git daemon. It is provided by the git package, so you already have it installed,
but it is not running. A separate package is needed, which will setup the daemon
as a service which runs automatically when you turn on the computer. One of
these packages needs to be installed:

- git-daemon-sysvinit
- git-daemon-run

If you have some knowledge about init systems, choose what's best for you.
Otherwise, let's go with what the gitolite package recommends to install:
git-daemon-run. Don't worry, it probably won't make much difference which one
you install. To install git-daemon-run, run this as root:

	# apt-get install git-daemon-run

Thanks to Gitolite's integration with the git daemon, the only thing left to do
is to enable repositories to be accessible via the git protocol. Gitolite
creates a special predefined user called 'daemon', which controls git protocol
access by having read access to repositories. Let's go back to our
gitolite.conf, which may look like this:

	repo    gitolite-admin
	        RW+     =   alice
	
	repo    cool-project
	        RW+     =   alice h4ck3r

The steps to add git daemon access to the cool-project repository are:

1. Give the 'daemon' user read access to it
2. Commit the change
3. Push

After the change the config file will look like this:

	repo    gitolite-admin
	        RW+     =   alice
	
	repo    cool-project
	        RW+     =   alice h4ck3r
	        R       =   daemon

The anonymous cloning address depends on the options given to the git-daemon
command. Let's go see them. If you installed git-daemon-run, the script that
runs the git-daemon service is /etc/sv/git-daemon/run and it should look like
this:

	#!/bin/sh
	exec 2>&1
	echo 'git-daemon starting.'
	exec chpst -ugitdaemon \
	  "$(git --exec-path)"/git-daemon --verbose --reuseaddr \
	    --base-path=/var/cache /var/cache/git

It means 3 things:

1. The repositories are looked for in the folder /var/cache/git
2. When cloning, there's no need to specify the /var/cache prefix, e.g. just
   /git/cool-project.git is enough
3. The daemon will run as a user named 'gitdaemon'

Of course this won't work because our repositories are not there. Also, the
gitdaemon user doesn't have any access to the git repositories, owned by the
__git__ user. We'll need to add gitdaemon to the __git__ group and make sure
users in the git group have read access to the repositories. And it's not all:
We'll need to make sure repositories give read access to the __git__ group.

First, let's fix the git-daemon configuration. Open the file
/etc/sv/git-daemon/run with your favorite text editor as root (for example
'nano', install with 'apt-get install nano') and change the base-path and the
repo directory. Now it should look like this:

	#!/bin/sh
	exec 2>&1
	echo 'git-daemon starting.'
	exec chpst -ugitdaemon:git \
	  "$(git --exec-path)"/git-daemon --verbose --reuseaddr \
	    --base-path=/home/git/repositories /home/git/repositories

It is also possible to use a non-standard port (9418 is git daemon's default) by
providing a port to the `git-daemon` command in the configuration above as a
command-line option, e.g. `--port=1234`.

After the change, the path to a repository cool-project is
/home/git/repositories/cool-project.git, but a base path is automatically
prepended so just cool-project.git is enough. In other words, cloning will look
like this, assuming the domain name of your git server is git.mysite.org:

	$ git clone git://git.mysite.org/cool-project.git

It also puts the gitdaemon user in the __git__ group. However, cloning still
doesn't work because gitolite creates repositories with permissions only for
itself (i.e. the __git__ user) and no permissions for the group. So what's left
is to:

1. Tell Gitolite to give the __git__ group read access to every new repository
2. Update existing repositories' access permissions (if necessary)

Note: Some repositories probably shouldn't have anonymous access, e.g. the
gitolite-admin repository. Even though the read access for 'daemon' in
gitolite.conf controls that, not giving gitdaemon read permissions adds an extra
security layer. Even if git daemon's authorization is bypassed somehow, e.g. by
mistake, it still cannot access gitolite-admin. However it depends on your
personal preference and situation. If you're the only one with SSH access to the
server and access to 'gitolite-admin', you're probably safe, especially if you
run a home server you physically own.

Let's tell gitolite to give new repositories permissions which will allow
members of the git group read them. Open the file /home/git/.gitolite.rc (if the
server is remote, use SSH to get there) and find, under "most often used/changed
variables", the following line:

	$REPO_UMASK = 0077;

This mask sets the default permissions for new repositories. It means the owner
(the __git__ user) has full access and everyone else has no access at all. To
give the git group members read access, change that line to the following and
save:

	$REPO_UMASK = 0027;

Now one last thing, let's see how to fix the permissions of existing
repositories. This is how it's done for the cool-project repository (must be
done on the server/ssh as the git user or as root):

	cd /home/git/repositories
	chmod g+rX .
	chmod -R g+rX cool-project.git

This applies the change to all existing repositories:

	cd /home/git/repositories
	chmod -R g+rX .

After the git daemon is restarted, it will start serving your repositories -
just the ones to whom 'daemon' has read access in gitolite.conf - anonymously
via the git protocol.

Note that if you want to serve your repositories via I2P, this is not enough. If
your server's firewall allows port 9418, the repositories will immediately
become available for git-protocol anonymous cloning via the clearnet, i.e. the
regular internet and not I2P. So if you want to use I2P, block port 9418 on your
server (if you run the server at home, it would be your home computer's
firewall. However if you use a router, it probably just blocks everything unless
you tell it to allow something, so don't allow port 9418. In any case you can
try cloning from another machine and see if it works). Later we'll see how to
create a server tunnel for I2P which forwards connections to port 9418 locally.
This will make your git protocol access work (only) via I2P.