doc/tips/untrusted_git_push.mdwn

   1 This tip will describe how to allow anyone on the planet to `git push`
   2 changes into your wiki, without needing a special account. All a user needs
   3 to know is:
   4
   5         git clone git://your.wiki/path
   6         # now modify any of the files the wiki would let you modify on the web
   7         git push
   8
   9 This is a wonderful thing to set up for users, because then they can work
  10 on the wiki while offline, and they don't need to mess around with web
  11 browsers.
  12
  13 ## security
  14
  15 But, you might be wondering, how can this possibly be secure. Won't users
  16 upload all sorts of garbage, change pages you don't want them to edit, and so
  17 on.
  18
  19 The key to making it secure is configuring ikiwiki to run as your git
  20 repository's `pre-receive` hook. There it will examine every change that
  21 untrusted users push into the wiki, and reject pushes that contain changes
  22 that cannot be made using the web interface.
  23
  24 So, unless you have the [[plugins/attachment]] plugin turned on,
  25 non-page files cannot be added. And if it's turned on, whatever
  26 `allowed_attachments` checks you have configured will also check files
  27 pushed into git.
  28
  29 And, unless you have the [[plugins/remove]] plugin turned on, no
  30 files can be deleted.
  31
  32 And if you have `locked_pages` configured, then it will also affect what's
  33 pushed into git.
  34
  35 Untrusted committers will also not be able to upload files with strange
  36 modes, or push to any branch except for the configured `gitorigin_branch`,
  37 or manipulate tags.
  38
  39 One thing to keep an eye on is uploading large files. It may be easier to
  40 do this via git push than using the web, and that could be abused.
  41
  42 Also, no checking is done that the authors of commits are right, so people
  43 can make a commit that pretends to be done by someone else.
  44
  45 ## user setup
  46
  47 Add a dedicated user who will push in untrusted commits. This user should have
  48 a locked password, and `git-shell` as its shell.
  49
  50         root@bluebird:/home/joey>adduser --shell=/usr/bin/git-shell --disabled-password anon
  51         Adding user `anon' ...
  52
  53 ## ikiwiki setup
  54
  55 You should set up ikiwiki before turning on anonymous push in git.
  56
  57 Edit your wiki's setup file, and uncomment the lines for
  58 `git_test_receive_wrapper` and `untrusted_committers`.
  59
  60         # git pre-receive hook to generate
  61         git_test_receive_wrapper => '/srv/git/ikiwiki.info/.git/hooks/pre-receive',
  62         # unix users whose commits should be checked by the pre-receive hook
  63         untrusted_committers => ['anon'],
  64
  65 The `git_test_receive_wrapper` will become the git `pre-receive` hook. The
  66 `untrusted_committers` list is the list of unix users who will be pushing in
  67 untrusted changes. It should *not* include the user that ikiwiki normally runs
  68 as.
  69
  70 Once you're done modifying the setup file, don't forget to run
  71 `ikiwiki -setup --refresh --wrappers` on it.
  72
  73 ## git setup
  74
  75 You'll need to arrange the permissions on your bare git repository so that
  76 user anon can write to it. One way to do it is to create a group, and put
  77 both anon and your regular user in that group. Then make the bare git
  78 repository owned and writable by the group. See [[rcs/git]] for some more
  79 tips on setting up a git repository with multiple committers.
  80
  81 Note that anon should *not* be able to write to the `srcdir`, *only* to the bare git
  82 repository for your wiki.
  83
  84 If you want to allow git over `ssh`, generate a ssh key for anon, and
  85 publish the *private* key for other people to use. This is optional; you
  86 can use `git-daemon` instead and not worry about keys.
  87
  88 Now set up `git-daemon`. It will need to run as user `anon`, and be
  89 configured to export your wiki's bare git repository. I set it up as
  90 follows in `/etc/inetd.conf`, and ran `/etc/init.d/openbsd-inetd restart`.
  91
  92         git     stream  tcp     nowait  anon          /usr/bin/git-daemon git-daemon --inetd --export-all --interpolated-path=/srv/git/%H%D /srv/git
  93
  94 At this point you should be able to `git clone git://your.wiki/path` from
  95 anywhere, and check out the source to your wiki. But you won't be able to
  96 push to it yet, one more change is needed to turn that on. Edit the
  97 `config` file of your bare git repository, and allow `git-daemon` to
  98 receive pushes:
  99
 100         [daemon]
 101                 receivepack = true
 102
 103 Now pushes should be accepted, and your wiki immediatly be updated. If it
 104 doesn't, check your git repo's permissions, and make sure that the
 105 `post-update` and `pre-receive` hooks are suid so they run as the user who
 106 owns the `srcdir`.
 107
 108 ## infelicities
 109
 110 If a user tries to push a changeset that ikiwiki doesn't like, it will
 111 abort the push before refs are updated. However, the changeset will still
 112 be present in your repository, wasting space. Since nothing refers to it,
 113 it will be expired eventually. You can speed up the expiry by running `git
 114 prune`.
 115
 116 When aborting a push, ikiwiki displays an error message about why it didn't
 117 accept it. If using git over ssh, the user will see this error message,
 118 which is probably useful to them. But `git-daemon` is buggy, and hides this
 119 message from the user. This can make it hard for users to figure out why
 120 their push was rejected. (If this happens to you, look at "'git log --stat
 121 origin/master..`" and think about whether your changes would be accepted
 122 over the web interface.)