DOCS/tech/mirrors/mirror_howto.txt

   1                           ------------------------------
   2                           How to build an MPlayer mirror
   3                           ------------------------------
   4
   5 =======================================================================
   6 WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING!
   7 -----------------------------------------------------------------------
   8 This is a preliminary version. Do not rely on anything here.
   9 Please send feedback, corrections etc to mplayer-mirror.
  10 =======================================================================
  11
  12 About this document
  13 ~~~~~~~~~~~~~~~~~~~
  14
  15 Mirroring MPlayer is quite easy but requires a few steps to be taken
  16 and a few things taken care of. This document describes these steps
  17 in detail so that anyone wishing to build an official or an unofficial
  18 mirror can do that without much trouble.
  19
  20
  21
  22 A note on performance issues
  23 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  24
  25 A few of the commands used here will generate some load on our main server.
  26 Executed too often and by to many clients at once will overload our server
  27 and cause a performance degradation for all our users. Thus we kindly ask
  28 you to be considerate about what you do. We do not want to restrict mirroring
  29 to a few selected people, but this requires that everyone using the system
  30 outlined here to behave.
  31
  32
  33 Outline of the mirroring system
  34 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  35
  36 The mirroring system uses rsync to transfere the data and to perform
  37 updates. A script is provided to call the rsync client with the right
  38 set of parameters. This script should be called periodicaly with cron.
  39 Additionaly, official mirrors should set up an ssh account so that
  40 updates can be triggered when important updates on the main server
  41 are performed.
  42 Mirrors should provide their data over http or ftp or both. Each official
  43 mirror will be assigned a mirror number. This mirror number determines
  44 the hostname over which it will be reached.
  45
  46
  47 Getting the data, mirroring script and cron setup
  48 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  49
  50 The mirroring script to be used is provided over the svn repo at
  51 svn://svn.mplayerhq.hu/mplayer/trunk/DOCS/tech/mirrors/update_mplayer_rsync .
  52
  53 This script requires a working `rsync` client. The handling of the
  54 lock file is done by using `lockfile` from the procmail package.
  55 Using a lock file is recommended but not necessary. The temporary file
  56 generation is handled by `mktemp` which is available on from
  57 http://www.mktemp.org/mktemp/ .
  58
  59 The script contains a few configuration variables at the begining that
  60 can and should be set:
  61 PATH: The $PATH to be used within the script (recommended).
  62 LOCK: The full path to the lock file to be used
  63         (/var/lock/mplayer-mirror-lock or something similar, recommended).
  64 MIRROR_ROOT: The root of the mirror. This is the directory where all files
  65         are downloaded to (required).
  66 MAILADR: The mail address where reports should be send to (required).
  67 TMPDIR: The directory where the temporary should be created.
  68         If you set this explicitly, you have to uncomment the export below too.
  69         (defaults to /tmp if not set)
  70
  71 Install this script and set the variables according to your setup. Then run
  72 it once to get the first checkout of the mirror. This will require at the
  73 time of this writing (2006-06-10) about 500MB of disk space.
  74 You should get two directories in your $MIRROR_ROOT: homepage and MPlayer.
  75 The former containing the html pages for the mirror and the later the
  76 files for download.
  77
  78 If this worked out ok, you should set up a cron job that periodicaly updates
  79 the files. If you run an official mirror you should run the script every
  80 6h to 12h (6h recommended). If you do not run an official mirror, you should
  81 not run the script more often than once a day. Please use an "odd" time
  82 to run the script when it is unlikely that any other cron job is running.
  83 Bad times are e.g. full hours, or minutes that are divisible by 5.
  84 An example crontab line would look like this:
  85 ---
  86 17 1,8,13,19 * * * /path/to/update_mplayer_rsync
  87 ---
  88 (please change the minute and hours to something random)
  89
  90 You can change the rest of the script as you see fit, although it is not
  91 recommended. Please DO NOT CHANGE the options of the rsync commands.
  92 Especially DO NOT REMOVE the -t and -W options. These prevent calculating
  93 checksums on the server side which are very expensive.
  94
  95
  96 Setting up an ssh account for update triggers
  97 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  98
  99 Official mirrors should also provide an ssh based trigger to run the
 100 update script on request. This makes it possible to distribute releases
 101 and other important files imediatly to all mirrors.
 102
 103 The way it is set up does not need a special user other than the one
 104 with which the update script is run already and does not allow to run
 105 any other command.
 106
 107 First you need to create an ssh key pair by running the following command:
 108 ---
 109 ssh-keygen -t dsa -C MPHQ_rsync_trigger -f www#_sshkey
 110 ---
 111 (replace the '#' by your mirror number)
 112
 113 You should send the private key to us by mail and specify the host and
 114 user to be used. Please do use a private mail of one of us and DO NOT
 115 send the private key onto the mirror mailinglist.
 116
 117 The public key should be placed into the ~/.ssh/authorized_keys file of the
 118 user. To restrict the sshkey to one command only please place the follwoing
 119 directives at the begining of the line with the key:
 120 from="*.mplayerhq.hu",command="<path_to_update_mplayer_rsync"
 121 e.g.:
 122 ---
 123 from="*.mplayerhq.hu",command="/path/to/update_mplayer_all" ssh-dss AAAA
 124 B3NzaC1kc3MAAAEBAI20yhE3/bRjzojUhhMz4DHnGhcJUiPWOfoP9CygnFOYOxJTFlxgqM3iJiHWRxgK
 125 FJ/Uw40eV9K4Ww4fp2pe1guXJzKna8+6vBXaPPVEVxSyaxgtt4Xt3zpUuCnNljgArcEhwcNyOyH2RVln
 126 yhyxsrKhuq5ZoNHD3caBGjZu3eOR2atPGS1NOdeN/hytIoh8T8DicPqPI29yWX9yAjnHv6wdPutwMLu6
 127 [...]
 128 n0Fs3CJY6/1UpgDGH7VPey0SdpJEDewltRLA+buP++2vJD/NUOeGzcRydo2NdZ1wiiaytXxkaec928JC
 129 NABTeBh6NKAg4vnPvcRLKEBVdSrar/fARSbOmf3HOcsw3uZoAIE9jDGhnMKcnXfHjPZ2tZP9CHs6Wo4n
 130 yDOxIfDZmJ7VJqMRc6//p5k81pkkGvawbPA63StI/Dkv/648l4XONuJc2z5gaUdjrTA8TsD/VJGiGcHl
 131 mlGj3IWCBz7e4+XB3L64kFZwLCYN8kwDUAaHq4EtcMVOnQ== MPHQ_rsync_trigger
 132 ---
 133 (lines split for readability)
 134
 135
 136 Setting up a webserver
 137 ~~~~~~~~~~~~~~~~~~~~~~
 138
 139 TO BE DONE
 140
 141
 142 Setting up an FTP server
 143 ~~~~~~~~~~~~~~~~~~~~~~~~
 144
 145 TO BE DONE
 146
 147
 148 Mailinglist
 149 ~~~~~~~~~~~
 150
 151 TO BE DONE