Update to MPlayer SVN rev 31179 and FFmpeg SVN rev 23156.
[vaapi:sewalliniusms-mplayer.git] / DOCS / tech / mirrors / mirror_howto.txt
1                           ------------------------------
2                           How to build an MPlayer mirror
3                           ------------------------------
4
5 This document might be inacurate or even incomplete, please
6 send feedback + corrections to the mplayer-mirror mailing list.
7
8 About this document
9 ~~~~~~~~~~~~~~~~~~~
10
11 Mirroring MPlayer is quite easy but requires a few steps to be taken
12 and a few things taken care of. This document describes these steps
13 in detail so that anyone wishing to build an official or an unofficial
14 mirror can do that without much trouble.
15
16
17 A note on performance issues
18 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
19
20 A few of the commands used here will generate some load on our main server.
21 Too many clients executing them at once will overload our server and cause
22 a performance degradation for all our users. Thus we kindly ask you to be
23 considerate about what you do. We do not want to restrict mirroring to a
24 few select people, but this requires everyone using the system described
25 here to behave.
26
27
28 Outline of the mirroring system
29 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
30
31 The mirroring system uses rsync to transfer the data and to perform
32 updates. A script (update_mplayer_rsync) is provided to call the rsync
33 client with the right set of parameters. This script should be run
34 periodically via cron.
35 Additionally, official mirrors should set up an ssh account so that
36 updates can be triggered when important changes on the main server
37 are performed.
38 Mirrors should provide their data over HTTP or FTP or both. Each official
39 mirror will be assigned a mirror number (wwwXXX.mplayerhq.hu or
40 ftpXXX.mplayerhq.hu where XXX is the mirror number). This mirror
41 number determines the hostname over which it can be reached directly.
42
43 All mirrors are put into our DNS round-robin for the www.mplayerhq.hu and
44 ftp.mplayerhq.hu names and should be set up to respond to these names as well.
45
46
47 Requirements
48 ~~~~~~~~~~~~
49 The requirements for any (official) mirror are:
50 1) rsync installed and some way to run the sync script periodicaly (eg cron)
51 2) subscribing to the mplayer-mirror mailing list (see below)
52
53 The requirements for a full website mirror are:
54 1) 500MB of free disk space (for the ftp and homepage directories).
55 2) A network connection with about 5Mbit/s sustained bandwidth.
56 3) A simple webserver that allows redirections and virtual server,
57    no PHP or CGI needed as all pages are static.
58
59 The requirements for a full ftp mirror are:
60 1) 500MB of free disk space (for the ftp directory).
61 2) (No bandwidth data for a ftp only server available)
62
63
64 Getting the data, mirroring script and cron setup
65 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
66
67 The mirroring script is located in our Subversion repository at
68
69   svn://svn.mplayerhq.hu/mplayer/trunk/DOCS/tech/mirrors/update_mplayer_rsync
70
71 or on the web at
72
73   http://svn.mplayerhq.hu/*checkout*/mplayer/trunk/DOCS/tech/mirrors/update_mplayer_rsync
74
75 This script requires a working `rsync` client. The handling of the
76 lock file is done by using `lockfile` from the procmail package.
77 Using a lock file is recommended but not necessary. The temporary file
78 generation is handled by `mktemp` which is available from
79 http://www.mktemp.org/mktemp/ .
80
81 The script contains a few configuration variables at the beginning that
82 can and should be set:
83 PATH: The $PATH to be used within the script (recommended).
84 LOCK: The full path to the lock file to be used (/var/lock/mplayer-mirror-lock
85       or something similar, recommended).
86 MIRROR_ROOT: The root of the mirror. This is the directory where all files
87              are downloaded to (required).
88 MAILADR: The mail address where reports should be sent to (required).
89 TMPDIR: The directory where temporary files should be created.
90         If you set this explicitly, you have to uncomment the export below
91         (defaults to /tmp if not set).
92
93 Install this script and set the variables according to your setup. Then run
94 it once to get the first checkout of the mirror. This will require (at the
95 time of this writing - 2006-06) about 500MB of disk space.
96 You should get two directories in your $MIRROR_ROOT: homepage and MPlayer.
97 The former containing the HTML pages for the mirror and the latter the
98 downloadable files.
99
100 If this worked out OK, you should set up a cron job that periodically updates
101 the files. If you run an official mirror you should run the script every
102 6h to 12h (6h recommended). If you do not run an official mirror, you should
103 not run the script more often than once a day. Please use an "odd" time
104 to run the script when it is unlikely that any other cron job is running.
105 Bad times are e.g. full hours, or minutes that are divisible by 5.
106 An example crontab line would look like this:
107 ---
108 17 1,8,13,19 * * * /path/to/update_mplayer_rsync
109 ---
110 (please change the minute and hours to something random)
111
112 You can change the rest of the script as you see fit, although it is not
113 recommended. Please DO NOT CHANGE the options of the rsync commands.
114 Especially DO NOT REMOVE the -t and -W options. These prevent calculating
115 checksums on the server side which are very expensive.
116
117
118 Setting up an SSH account for update triggers
119 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
120
121 Official mirrors should provide an ssh-based trigger to run the update script
122 on request. This makes it possible to distribute releases and other important
123 files immediately to all mirrors.
124
125 The setup does not need a special user other than the one as which the update
126 script is run and does not allow running any other command.
127
128 First you need to create an ssh key pair by running:
129 ---
130 ssh-keygen -t dsa -C MPHQ_rsync_trigger -f www#_sshkey
131 ---
132 (replace the '#' by your mirror number)
133
134 You should send the private key to us by mail and specify the host and
135 user to be used. Please use a private mail of one of the admins and
136 DO NOT send the private key to the mirror mailing list.
137
138 The public key should be placed in the ~/.ssh/authorized_keys file of the
139 user running the updates. To restrict the ssh key to only one command place
140 the following directives at the beginning of the line with the key:
141 from="*.mplayerhq.hu",command="<path_to_update_mplayer_rsync>"
142 e.g.:
143 ---
144 from="*.mplayerhq.hu",command="/path/to/update_mplayer_rsync" ssh-dss AAAA
145 B3NzaC1kc3MAAAEBAI20yhE3/bRjzojUhhMz4DHnGhcJUiPWOfoP9CygnFOYOxJTFlxgqM3iJiHWRxgK
146 FJ/Uw40eV9K4Ww4fp2pe1guXJzKna8+6vBXaPPVEVxSyaxgtt4Xt3zpUuCnNljgArcEhwcNyOyH2RVln
147 yhyxsrKhuq5ZoNHD3caBGjZu3eOR2atPGS1NOdeN/hytIoh8T8DicPqPI29yWX9yAjnHv6wdPutwMLu6
148 [...]
149 n0Fs3CJY6/1UpgDGH7VPey0SdpJEDewltRLA+buP++2vJD/NUOeGzcRydo2NdZ1wiiaytXxkaec928JC
150 NABTeBh6NKAg4vnPvcRLKEBVdSrar/fARSbOmf3HOcsw3uZoAIE9jDGhnMKcnXfHjPZ2tZP9CHs6Wo4n
151 yDOxIfDZmJ7VJqMRc6//p5k81pkkGvawbPA63StI/Dkv/648l4XONuJc2z5gaUdjrTA8TsD/VJGiGcHl
152 mlGj3IWCBz7e4+XB3L64kFZwLCYN8kwDUAaHq4EtcMVOnQ== MPHQ_rsync_trigger
153 ---
154 (lines split for readability)
155
156
157 Setting up a webserver
158 ~~~~~~~~~~~~~~~~~~~~~~
159
160 Set up Apache or whatever web server you prefer. We just have static pages,
161 so no fancy configuration is necessary. However, we need a few aliases so that
162 links on our pages work correctly. /MPlayer and /DOCS should redirect to the
163 directory with the downloadable files.
164
165 Here is an example stanza to paste into your Apache configuration:
166
167 <VirtualHost www#.mplayerhq.hu>
168         DocumentRoot /path/to/htdocs
169         Options FollowSymLinks Indexes
170         Alias /MPlayer  /path/to/MPlayer
171         Alias /DOCS     /path/to/MPlayer/DOCS
172         AddDefaultCharset off
173 </VirtualHost>
174
175 <VirtualHost www.mplayerhq.hu>
176         DocumentRoot /path/to/htdocs
177         Options FollowSymLinks Indexes
178         Alias /MPlayer  /path/to/MPlayer
179         Alias /DOCS     /path/to/MPlayer/DOCS
180         AddDefaultCharset off
181 </VirtualHost>
182
183 The AddDefaultCharset directive is necessary because newer versions of Apache
184 appear to default to defining a standard charset. This breaks our documentation
185 translations, which are written in different encodings.
186
187 The second VirtualHost is necessary for the DNS round-robin address.
188 To check whether this VirtualHost works, you can add a temporary entry into
189 your /etc/hosts file:
190
191 1.2.3.4 www.mplayerhq.hu
192
193 Replace the IP address by the real IP address of your mirror. Do not forget to
194 remove the entry after you finish testing.
195
196
197 Webserver checklist
198 ~~~~~~~~~~~~~~~~~~~
199
200 After setting up the web server, please verify that the following things work
201 both for your mirror address (www#.mplayerhq.hu) and the DNS round-robin
202 address (www.mplayerhq.hu):
203
204 - The virtual host is reachable by its address.
205 - The MPlayer and DOCS subdirectories work.
206 - The man pages and documentation are served with the correct content-type.
207   Try Russian or Chinese, you will notice breakage immediately.
208
209
210 Setting up an FTP server
211 ~~~~~~~~~~~~~~~~~~~~~~~~
212
213 Any FTP server will do. We use vsftpd, it is fast and secure. The setup is
214 similar to the web server setup. The FTP server should listen on both its mirror
215 address (ftp#.mplayerhq.hu) and the DNS round-robin address (ftp.mplayerhq.hu).
216 All our mirrors are public, so you should allow anonymous access.
217
218 You should have the same directory layout as we do on our server, so there
219 should be a subdirectory named 'MPlayer' (notice the capitals) that contains
220 the downloadable files.
221
222
223 Mailing list
224 ~~~~~~~~~~~~
225
226 All official mirror admins are required to subscribe to the mplayer-mirror
227 mailing list. It's used to coordinate the efforts and distribute information
228 among all admins. It is also very low traffic. Please use the webinterface
229 on http://lists.mplayerhq.hu/mailman/listinfo/mplayer-mirror to subscribe.
230 Please do not top-post on this mailing list.