README

   1 This repository manager originated at repo.or.cz, where it has been
   2 used to mirror, host, and fork projects both large and small.
   3
   4 The user interface is kept in the cgi/ subdirectory.  On the site,
   5 http://repo.or.cz/m/ links to a copy of that directory, configured
   6 by the apache.conf file.  But, wait... you don't have that file yet!
   7
   8 Configuration
   9 -------------
  10
  11 The first time you type 'make', your editor will open with a text
  12 configuration file that will be used to build the pages and scripts
  13 with site-specific constants.  After changing the setting to those
  14 appropriate for your site, the contents will be saved in 'config.txt',
  15 and the values will be used to transform the source files.
  16
  17 IMPORTANT: Do not edit the generated scripts!  If you switch branches,
  18 your changes will be overwritten when you type 'make'.
  19
  20 Once you have configured and built the scripts to your satisfaction, you can
  21 run the ./setup.sh script to ensure your setup is configured properly.
  22
  23 Service Overview
  24 ----------------
  25
  26 Project are established in one of three modes of operationt: mirror,
  27 depot, or fork.  All allow users to pull from the server, but only
  28 depot and fork modes allow pushing.
  29
  30 Depot mode
  31 ----------
  32
  33 Depot access is confined to a chroot jail, with its own instance of sshd
  34 running.  Herein, uids and gids are allocated from range 65536..infty.
  35 Passwords are stored in DES crypt(3) format, because Apache is moronic -
  36 in the past the group file was also used as htpasswd file.
  37
  38 The chroot should contain the following files:
  39
  40 drwxr-xr-x root     repo  /
  41 drwxr-xr-x root     repo  /bin
  42 ------x--x root     repo  /bin/sh
  43 ------x--x root     root  /bin/git-index-pack
  44 ------x--x root     root  /bin/git-pack-objects
  45 ------x--x root     root  /bin/git-receive-pack
  46 ------x--x root     root  /bin/git-repack
  47 ------x--x root     root  /bin/git-rev-list
  48 ------x--x root     root  /bin/git-shell
  49 ------x--x root     root  /bin/git-unpack-objects
  50 ------x--x root     root  /bin/git-update-server-info
  51 ------x--x root     root  /bin/git-upload-pack
  52 drwxr-xr-x root     repo  /sbin
  53 ---x------ root     repo  /sbin/sshd
  54 drwxr-xr-x root     repo  /lib
  55 -r-xr-xr-x root     repo  /lib/libwrap.so.0
  56 -r-xr-xr-x root     repo  /lib/libpam.so.0
  57 -r-xr-xr-x root     repo  /lib/libresolv.so.2
  58 -r-xr-xr-x root     repo  /lib/libcrypto.so.0.9.7
  59 -r-xr-xr-x root     repo  /lib/libutil.so.1
  60 -r-xr-xr-x root     repo  /lib/libz.so.1
  61 -r-xr-xr-x root     repo  /lib/libnsl.so.1
  62 -r-xr-xr-x root     repo  /lib/libcrypt.so.1
  63 -r-xr-xr-x root     repo  /lib/libpthread.so.0
  64 -r-xr-xr-x root     repo  /lib/libc.so.6
  65 -r-xr-xr-x root     repo  /lib/ld-linux.so.2
  66 -r-xr-xr-x root     repo  /lib/libnss_compat.so.2
  67 -r-xr-xr-x root     repo  /lib/libgcc_s.so.1
  68 -r-xr-xr-x root     repo  /lib/libdl.so.2
  69 drwxrwsr-x repo     repo  /etc
  70 -rw-rw-r-- www-data repo  /etc/passwd
  71 -rw-rw-r-- www-data repo  /etc/group
  72 drwxr-x--- root     repo  /etc/ssh
  73 -rw-r--r-- root     repo  /etc/ssh/moduli
  74 -rw------- root     repo  /etc/ssh/ssh_host_rsa_key
  75 -rw-r--r-- root     repo  /etc/ssh/ssh_host_rsa_key.pub
  76 -rw------- root     repo  /etc/ssh/ssh_host_dsa_key
  77 -rw-r--r-- root     repo  /etc/ssh/ssh_host_dsa_key.pub
  78 -rw-r--r-- root     repo  /etc/ssh/sshd_config
  79 drwxrwsr-x repo     repo  /etc/sshkeys
  80 drwxrwsr-x pasky    repo  /srv/git
  81 drwxr-xr-x root     repo  /var
  82 drwxr-xr-x root     root  /var/run
  83 drwxr-xr-x root     repo  /var/run/sshd
  84 ---------- 65538    root  /var/run/mob
  85 -rw-r--r-- root     root  /var/run/sshd.pid
  86 drwxr-xr-x root     root  /srv
  87 drwxr-xr-x root     root  /dev
  88 crw-rw-rw- root     root  /dev/null
  89 crw-rw-rw- root     root  /dev/zero
  90 crw-rw-rw- root     root  /dev/random
  91 cr--r--r-- root     root  /dev/urandom
  92 srw-rw-rw- root     root  /dev/log
  93 lrwxrwxrwx root     root  /usr -> .
  94
  95 There is a (non-chroot) system user 'repo' and a group of the same name (the
  96 webserver is member of the group; TODO: suexec). The files in /etc are owned
  97 by repo.repo and group-writable, as well as all files in /srv/git/*/ but
  98 refs/**, info/**, and objects/** which are repo.project. /var/run/mob has zero
  99 permissions bits but is owned by the mob user.
 100
 101
 102 When you register a project, it will get a gid allocation and you will set a
 103 password for it. The triple is stored in a group(5) file (but containing just
 104 the project groups):
 105
 106         projname:crypt:gid:list,of,users
 107
 108 When you register a user, it will get a uid allocation and you will upload
 109 an ssh public key for it. The user is stored in a passwd(5) file (but
 110 containing just the repo.or.cz users; 65534 is nogroup):
 111
 112         username:x:uid:65534:email:/:/bin/git-shell
 113
 114 The authorized keys are stored in /etc/sshkeys/username.
 115
 116 When you (un)assign user to a project, you just manipulate the list of users
 117 for the project in /etc/group. The web interface for the project administration
 118 is protected by the group password; chroot/etc/group is used as the htpasswd
 119 file here.
 120
 121 Since Apache is not in the project groups, there is a special cronjob run
 122 every minute to fix up the permissions for the refs/, info/, and objects/
 123 project directories, under the root user.
 124
 125 Mirror mode
 126 -----------
 127
 128 To keep things safe and neat, repo.or.cz is job-controlled: the only thing the
 129 cgi script does is scheduling a clone job (by creating a directory with some
 130 files at a magic location) and then the clonecheck.sh script is invoked every
 131 minute by cron (under more reasonable uid) to check if there are any jobs
 132 scheduled, and calls clone.sh to do the clone itself, notifying the user about
 133 the results.
 134
 135 The script that keeps repositories up-to-date is updatecheck.sh, being run
 136 by cron every hour and calling update.sh for all the relevant repositories.
 137
 138 updateglibc.sh stands somewhat out of the crowd and keeps the Git mirror of
 139 the glibc CVS repository up-to-date, so it's probably not interesting for
 140 anyone.
 141
 142 To make sure a project is not pushable when in mirror mode, the last colon
 143 in the /etc/group entry for the project is doubled.
 144
 145 Watchdogs
 146 ---------
 147
 148 When a watchdog is registered by a user, it must be stored first in
 149 their watchdog file for reference:
 150
 151         projname:branch:path
 152
 153 This file is stored in '/etc/watchdogs/user/<name>'.  Simultaneously,
 154 a project watchdog file ('/etc/watchdogs/project/<name>') must be
 155 updated with an entry used to trigger and send the notification.
 156
 157         username:branch:path