README

   1 This is the duct tape that ties repo.or.cz together, codenamed Girocco.
   2 You will find some hardcoded paths inside, and some other kludgy stuff; we are
   3 working on cleaning it up, though.
   4
   5 The user interface is kept in the cgi/ subdirectory (repo.or.cz/m/ is symlink
   6 to that).
   7
   8 There are two modes of operation for each project: hosting and mirroring.
   9
  10
  11 Hosting mode
  12 ------------
  13
  14 (All uids and gids are allocated from range 65536..infty. All passwords are
  15 stored in DES crypt(3) format because Apache is moronic - in the past the group
  16 file was also used as htpasswd file.)
  17
  18
  19 This is how the push access is provided:
  20
  21 The whole setup is confined in a chroot with its own instance of sshd running.
  22 The chroot looks like:
  23
  24 drwxr-xr-x root     repo  /
  25 drwxr-xr-x root     repo  /bin
  26 ------x--x root     repo  /bin/sh
  27 ------x--x root     root  /bin/git-index-pack
  28 ------x--x root     root  /bin/git-pack-objects
  29 ------x--x root     root  /bin/git-receive-pack
  30 ------x--x root     root  /bin/git-repack
  31 ------x--x root     root  /bin/git-rev-list
  32 ------x--x root     root  /bin/git-shell
  33 ------x--x root     root  /bin/git-unpack-objects
  34 ------x--x root     root  /bin/git-update-server-info
  35 ------x--x root     root  /bin/git-upload-pack
  36 drwxr-xr-x root     repo  /sbin
  37 ---x------ root     repo  /sbin/sshd
  38 drwxr-xr-x root     repo  /lib
  39 -r-xr-xr-x root     repo  /lib/libwrap.so.0
  40 -r-xr-xr-x root     repo  /lib/libpam.so.0
  41 -r-xr-xr-x root     repo  /lib/libresolv.so.2
  42 -r-xr-xr-x root     repo  /lib/libcrypto.so.0.9.7
  43 -r-xr-xr-x root     repo  /lib/libutil.so.1
  44 -r-xr-xr-x root     repo  /lib/libz.so.1
  45 -r-xr-xr-x root     repo  /lib/libnsl.so.1
  46 -r-xr-xr-x root     repo  /lib/libcrypt.so.1
  47 -r-xr-xr-x root     repo  /lib/libpthread.so.0
  48 -r-xr-xr-x root     repo  /lib/libc.so.6
  49 -r-xr-xr-x root     repo  /lib/ld-linux.so.2
  50 -r-xr-xr-x root     repo  /lib/libnss_compat.so.2
  51 -r-xr-xr-x root     repo  /lib/libgcc_s.so.1
  52 -r-xr-xr-x root     repo  /lib/libdl.so.2
  53 drwxrwsr-x repo     repo  /etc
  54 -rw-rw-r-- www-data repo  /etc/passwd
  55 -rw-rw-r-- www-data repo  /etc/group
  56 drwxr-x--- root     repo  /etc/ssh
  57 -rw-r--r-- root     repo  /etc/ssh/moduli
  58 -rw------- root     repo  /etc/ssh/ssh_host_rsa_key
  59 -rw-r--r-- root     repo  /etc/ssh/ssh_host_rsa_key.pub
  60 -rw------- root     repo  /etc/ssh/ssh_host_dsa_key
  61 -rw-r--r-- root     repo  /etc/ssh/ssh_host_dsa_key.pub
  62 -rw-r--r-- root     repo  /etc/ssh/sshd_config
  63 drwxrwsr-x repo     repo  /etc/sshkeys
  64 drwxrwsr-x pasky    repo  /srv/git
  65 drwxr-xr-x root     repo  /var
  66 drwxr-xr-x root     root  /var/run
  67 drwxr-xr-x root     repo  /var/run/sshd
  68 ---------- 65538    root  /var/run/mob
  69 -rw-r--r-- root     root  /var/run/sshd.pid
  70 drwxr-xr-x root     root  /srv
  71 drwxr-xr-x root     root  /dev
  72 crw-rw-rw- root     root  /dev/null
  73 crw-rw-rw- root     root  /dev/zero
  74 crw-rw-rw- root     root  /dev/random
  75 cr--r--r-- root     root  /dev/urandom
  76 srw-rw-rw- root     root  /dev/log
  77 lrwxrwxrwx root     root  /usr -> .
  78
  79 There is a (non-chroot) system user 'repo' and a group of the same name (the
  80 webserver is member of the group; TODO: suexec). The files in /etc are owned
  81 by repo.repo and group-writable, as well as all files in /srv/git/*/ but
  82 refs/**, info/**, and objects/** which are repo.project. /var/run/mob has zero
  83 permissions bits but is owned by the mob user.
  84
  85
  86 When you register a project, it will get a gid allocation and you will set a
  87 password for it. The triple is stored in a group(5) file (but containing just
  88 the project groups):
  89
  90         projname:crypt:gid:list,of,users
  91
  92 When you register a user, it will get a uid allocation and you will upload
  93 an ssh public key for it. The user is stored in a passwd(5) file (but
  94 containing just the repo.or.cz users; 65534 is nogroup):
  95
  96         username:x:uid:65534:email:/:/bin/git-shell
  97
  98 The authorized keys are stored in /etc/sshkeys/username.
  99
 100 When you (un)assign user to a project, you just manipulate the list of users
 101 for the project in /etc/group. The web interface for the project administration
 102 is protected by the group password; chroot/etc/group is used as the htpasswd
 103 file here.
 104
 105 Since Apache is not in the project groups, there is a special cronjob run
 106 every minute to fix up the permissions for the refs/, info/, and objects/
 107 project directories, under the root user.
 108
 109
 110 Mirror mode
 111 -----------
 112
 113 To keep things safe and neat, repo.or.cz is job-controlled: the only thing the
 114 cgi script does is scheduling a clone job (by creating a directory with some
 115 files at a magic location) and then the clonecheck.sh script is invoked every
 116 minute by cron (under more reasonable uid) to check if there are any jobs
 117 scheduled, and calls clone.sh to do the clone itself, notifying the user about
 118 the results.
 119
 120 The script that keeps repositories up-to-date is updatecheck.sh, being run
 121 by cron every hour and calling update.sh for all the relevant repositories.
 122
 123 updateglibc.sh stands somewhat out of the crowd and keeps the Git mirror of
 124 the glibc CVS repository up-to-date, so it's probably not interesting for
 125 anyone.
 126
 127 To make sure a project is not pushable when in mirror mode, the last colon
 128 in the /etc/group entry for the project is doubled.
 129
 130
 131 Girocco
 132 -------
 133
 134 Until Jul 2008, we called all the repo.or.cz machinery just 'repo', however
 135 that is not very good name, especially since we are now working at making
 136 the machinery suitable for universal usage even outside of repo.or.cz.
 137 Thankfully, Jan Engelhart invented a nice name 'Girocco', standing for
 138 'GIt Repo.Or.Cz COdebase'.