release as 0.60 to sid
[piuparts/piuparts.git] / README_pejacevic.txt
1 Notes about the piuparts installation on pejacevic.debian.org and it's slave(s)
2 ===============================================================================
3
4 This document describes the setup for https://piuparts.debian.org - it's used
5 for reference for the Debian System Administrators (DSA) as well as a guide
6 for other setting up a similar system, with the piuparts source code
7 installed from git. For regular installations we recommend to use the
8 piuparts-master and piuparts-slaves packages as described in
9 /usr/share/doc/piuparts-master/README_server.txt
10
11 == Installation
12
13 piuparts.debian.org is a setup running on several systems:
14 pejacevic.debian.org, running the piuparts-master instance and an apache
15 webserver to display the results and piu-slave-bm-a.debian.org, running
16 four piuparts-slave nodes. Not yet in operation there is another,
17 piu-slave-1und1-01.debian.org, which soon shall go into operation...
18
19 === piuparts installation from source
20
21 * basically, apt-get build-dep piuparts - in reality both systems get their
22   package configuration from git.debian.org/git/mirror/debian.org.git
23 * pejacevic runs a webserver as well (see below for apache configuration)
24 * Copy 'https://anonscm.debian.org/cgit/piuparts/piuparts.git/tree/update-piuparts-master-setup?h=develop'
25   and 'https://anonscm.debian.org/cgit/piuparts/piuparts.git/tree/update-piuparts-slave-setup?h=develop'
26   to the hosts which should be master and slave. (It's possible and has been
27   done for a long time to run them on the same host.(
28   Run the scripts as the piupartsm and piupartss users and clone that git
29   repository into '/srv/piuparts.debian.org/src' in the first place. Then
30   checkout the develop branch.
31 * Ideally provide '/srv/piuparts.debian.org/tmp' on (a sufficiently large)
32   tmpfs.
33 * `sudo ln -s /srv/piuparts.debian.org/etc/piuparts /etc/piuparts`
34 * See below for further user setup instructions.
35
36 === User setup
37
38 On pejacevic the piuparts-master user piupartsm needs to be created, on
39 piu-slave-bm-a a piupartss user is needed for the slave.
40 Both are members of the group piuparts and '/srv/piuparts.debian.org' needs to
41 be chmod 2775 and chown piuparts(sm):piuparts.
42
43 ==== '~/bashrc' for piupartsm and piupartss
44
45 Do this for the piupartsm user on pejacevic and piupartss on the slave(s):
46
47 ----
48 piupartsm@pejacevic$ cat >> ~/.bashrc <<-EOF
49
50 # added manually for piuparts
51 umask 0002
52 export PATH="~/bin:\$PATH"
53 EOF
54 ----
55
56 ==== set up ssh pubkey authentification
57
58 Then create an SSH keypair for piupartss and put it into
59 '/etc/ssh/userkeys/piupartsm' on pejacevic, so the piupartss user can login
60 with ssh and run only piuparts-master. Restrict it like this:
61
62 ----
63 $ cat /etc/ssh/userkeys/piupartsm
64 command="/srv/piuparts.debian.org/share/piuparts/piuparts-master",from="2001:41c8:1000:21::21:7,5.153.231.7",no-port-forwarding,no-X11-forwarding,no-agent-forwarding ssh-rsa ...
65 ----
66
67 === Setup sudo for the slave(s)
68
69 This is actually done by DSA:
70
71 ==== '/etc/sudoers' for piu-slave-bm-a and piu-slave-1und1-01
72
73 ----
74 # The piuparts slave needs to handle chroots.
75 piupartss       ALL = NOPASSWD: /usr/sbin/piuparts *, \
76                                 /bin/umount /srv/piuparts.debian.org/tmp/tmp*, \
77                                 /usr/bin/test -f /srv/piuparts.debian.org/tmp/tmp*, \
78                                 /usr/bin/rm -rf --one-file-system /srv/piuparts.debian.org/tmp/tmp*
79 ----
80
81 === Apache configuration
82
83 Any other webserver will do but apache is used on pejacevic (and maintained by DSA):
84
85 ----
86 <VirtualHost *:80>
87         ServerName piuparts.debian.org
88
89         ServerAdmin debian-admin@debian.org
90
91         ErrorLog /var/log/apache2/piuparts.debian.org-error.log
92         CustomLog /var/log/apache2/piuparts.debian.org-access.log combined
93
94         DocumentRoot /srv/piuparts.debian.org/htdocs
95         AddType text/plain log
96
97         HostnameLookups Off
98         UseCanonicalName Off
99         ServerSignature On
100         <IfModule mod_userdir.c>
101                 UserDir disabled
102         </IfModule>
103 </VirtualHost>
104 # vim:set syn=apache:
105 ----
106
107 == Running piuparts
108
109 === Updating the piuparts installation
110
111 Updating the master, pejacevic.debian.org:
112
113 ----
114 holger@pejacevic~$ sudo su - piupartsm update-piuparts-master-setup develop origin
115 ----
116
117 Updating the slave(s), for example on piu-slave-bm-a.debian.org:
118
119 ----
120 holger@piu-slave-bm-a~$ sudo su - piupartss update-piuparts-slave-setup develop origin
121 ----
122
123 === Running piuparts
124
125 When running piuparts in master/slave mode, the master is never run by itself,
126 instead it is always started by the slave(s).
127
128 ==== Starting and stopping the slaves
129
130 Run the following script under *your* user account to start four instances of
131 piuparts-slave on pejacevic, piuparts-master will be started automatically by
132 the slaves.
133
134 ----
135 holger@piu-slave-bm-a:~$ sudo -u piupartss -i slave_run
136 ----
137
138 There are several cronjobs installed via '~piupartsm/crontab' and
139 '~piupartss/crontab') to monitor both master and slave as well as the hosts
140 they are running on.
141
142 It's possible to kill a slave any time by pressing Ctrl-C.
143 Pressing Ctrl-C once will wait for the current test to finish,
144 pressing twice will abort the currently running test (which will be redone).
145 Clean termination may take some time and can be aborted by a third Ctrl-C,
146 but that may leave temporary directories and processes around.
147
148 See the 'piuparts_slave_run (8)' manpage for more information on 'slave_run'.
149
150 ==== Joining an existing slave session
151
152 Run the following script under *your* user account:
153
154 ----
155 holger@pejacevic:~$ sudo -u piupartss -i slave_join
156 ----
157
158 See the 'piuparts_slave_join (8)' manpage for more information on 'slave_join'.
159
160 === Generating reports for the website
161
162 'piuparts-report' is run daily at midnight and at noon from
163 '~piupartsm/crontab' on pejacevic.
164
165 === Cronjobs to aid problem spotting
166
167 Some cronjobs to aid problem spotting reside in '~piupartsm/bin/' and are run
168 daily by '~piupartsm/crontab'.
169
170 - 'detect_network_issues' should detect failed piuparts runs due to network
171   issues on the host.
172 - 'detect_stale_mounts' should detect stale mountpoints (usually of /proc)
173   from failed piuparts runs.
174
175 More checks should be added as we become aware of them.
176
177
178 == Authors
179
180 Last updated: October 2014
181
182 Holger Levsen <holger@layer-acht.org>
183
184 // vim: set filetype=asciidoc: