source: trunk/debathena/NOTES @ 23752

Revision 23752, 24.9 KB checked in by geofft, 16 years ago (diff)
NOTES is badly in need of an update. Help it a bit. There's still some confusion about where the repo is and whether debuild or builder has access to it.
Line 
1This hierarchy contains Debian/Ubuntu-specific materials, also known
2as "Debathena".  The contents are:
3
4* debathena - Debathena-specific software packages such as PAM and NSS
5  modules.
6
7* config - Packages for configuring native system software in a manner
8  appropriate for Athena.
9
10* meta - Packages which contain nothing but dependencies on other
11  packages and serve as an installation convenience.
12
13* scripts - Build scripts and supporting materials.
14
15Debathena is a SIPB project, and its infrastructure and procedures
16will need to be adapted for Athena 10.  For the moment this file will
17document the Debathena procedures as they are, not as they will be.
18The current procedures do not even use this svn repository yet.
19
20Debian software used by Debathena:
21
22  * schroot - Used to manage build chroot environments for each
23    Debian/Ubuntu version.  We use the lvm-snapshot schroot type,
24    which allows rapid construction of ephemeral copies of template
25    "source" chroots, so that every binary package build is done in a
26    clean environment.
27
28  * debuild - Used to create Debian source packages from package
29    source directories.
30
31  * sbuild - Used to build binary packages from source packages inside
32    schroot environments.
33
34  * equivs - Used to create packages which only contain dependency
35    information.  Somewhat of a dirty hack, since it doesn't keep
36    proper changelogs, but it reduces overhead.
37
38  * CDBS (Common Debian Build System) - Referenced by debian/rules
39    files in packages.  Contains standard build rules to cut down on
40    per-package boilerplate.
41
42  * reprepro - Used to upload packages into the apt repositories.
43
44  * approx - Used to create a local cache of Debian packages on the
45    build server.  This cache is referenced by the build chroots for
46    improved performance.
47
48The remainder of this file documents procedures useful to Athena 10
49developers and the release engineer.
50
51Developers: Preferences setup
52-----------------------------
53
54You will probably want a $HOME/.devscripts file containing the
55following:
56
57DEBUILD_DPKG_BUILDPACKAGE_OPTS="-sa -us -uc -i -I.svn"
58
59This will save you from having to specify those options every time you
60run debuild.  Athena 10 scripts do not assume the above preferences,
61but the instructions in this file do.  The options mean:
62
63  * Look for original source as a tarfile or create one.
64  * Do not sign the source package.
65  * Do not sign the changes file.
66  * Ignore common version control metadata files when creating diffs.
67  * Ignore .svn paths when creating tarballs.
68
69You will also want a $HOME/.sbuildrc file containing the following:
70
71  $nolog = 1;
72  $mailto = 'yourusername';
73  $log_dir = '/tmp/sbuild-logs';
74  $maintainer_name = 'Debathena Project <debathena@mit.edu>';
75  $force_orig_source = 1;
76  $sbuild_mode = "user";
77  1;
78
79You should also set the environment variable DEBATHENA_APT to
80"/afs/dev.mit.edu/system/athena10/apt".
81
82Developers: Preparing a change
83------------------------------
84
85To prepare a change to a regular package (a source tree containing a
86debian/ subdir), make the edits in a checkout and record a changelog
87entry.  You can either edit debian/changelog using emacs changelog
88mode (C-c C-v to add a new version entry, C-c C-a to add a change
89entry, C-c C-f to finalize the entry) or you can run "dadch" from
90the debathena locker / SVN scripts directory.
91
92When creating a new version entry, bump the upstream version number
93(to 10.0.0 if it was not already that high) if you are changing the
94main package source.  Otherwise, just bump the Debian version
95component (change 0debathena1 to 0debathena2, for instance).
96
97Developers: Building a package for test purposes on one platform
98----------------------------------------------------------------
99
100After you have prepared a change, you will want to test that it builds
101and perhaps that it works before committing it.  First, if it is an
102Athena source directory using autoconf, run "daconfiscate" to set up
103the autoconf boilerplate which we don't check in.  Second, run
104"daorig" to copy or create an orig tarball in the parent directory if
105necessary.  Third, run "debuild".  The resulting package will be
106placed in the parent directory.
107
108In order to test if the package works, you can install it with "dpkg
109-i filename.deb".
110
111Developers: Building a package for test purposes on all platforms
112-----------------------------------------------------------------
113
114If the package you are working on interacts with the native OS in ways
115that might vary from platform to platform, you may want to do a test
116build for all platforms.  You will need to do this on
117linux-build-10.mit.edu or another machine which has been set up with
118build schroots.
119
120As above, run daconfiscate (if necessary) and then daorig.  Then run
121"debuild -S" to create a source package.  Now cd into the parent
122directory and identify the .dsc file created by debuild -S; it will
123have a name like debathena-just_9.4.0-0debathena2.dsc.  Run "da
124sbuildhack filename.dsc" to perform the package builds.  Each build
125will take place inside an ephemeral chroot based on a snapshot of a
126template for a particular Debian or Ubuntu version.  If a build fails
127and it's not obvious from the build log why, you may need to create
128your own ephemeral chroot session with a command like "schroot -c
129gutsy-amd64-sbuild /bin/sh" and then run debuild from within the
130package sources.
131
132If the build is successful, it will create a set of packages with
133names like debathena-just_9.4.0-0debathena2~ubuntu6.06_amd64.deb.
134
135Developers: Building an equivs package
136--------------------------------------
137
138Most of the packages under debathena/meta are faked up using equivs.
139To build one, just run:
140
141  equivs-build --full filename.equivs
142
143These equivs files make reference to ../common, so you must have a
144checkout of debathena/meta/common alongside the particular
145meta-package you are building.
146
147Developers: The meaning of metapackages
148---------------------------------------
149
150If you are adding a new package to the repository, you will probably
151at some point want to add it to one of the metapackages so that it
152doesn't have to be installed by hand.  Here are some descriptions
153which may help identify which metapackage is best:
154
155* locker: Provides access to Athena locker software--AFS and
156  automounter configuration, locker-related utilities, etc.
157
158* clients: Provides clients (either locally-written, like athinfo and
159  Discuss, or configurations) for Athena services, as well as
160  Athena-specific utility programs like "jot".  Configurations for
161  graphical client software are generally in the workstation package
162  instead, in order to make this package less intrusive.
163
164* standard: Implies locker and clients.  Also provides Athena shell
165  customizations and dotfiles.
166
167* login: Implies standard.  Configurations to merge the MIT user
168  namespace into the local machine namespace for the purpose of user
169  lookups and authentication.
170
171* login-graphical: Implies login.  Configurations for the graphical login
172  system and graphical client software intended to provide a standard
173  X login experience using Athena home directories.
174
175* extra-software: Implies a set of Debian packages common to cluster
176  machines and typical workstations.  The resulting software set is
177  rather large, and thus may not be desirable to all workstation
178  configurations.  Only stock Debian packages belong in this
179  metapackage; do not add other Debathena packages to it.
180
181* workstation: Implies login-graphical and extra-software.  The use case
182  is the same as that of the old "private workstations", so it includes
183  more centrally-managed configuration than standard or login does
184  (unattended updates, etc.). New as of May 2009.
185
186* thirdparty: Software supported by 3partysw that upstream Ubuntu
187  already happens to be keeping up to date, and is therefore easier to
188  install via packages than through lockers. This package is HUGE (1 GB of
189  network traffic, 3 GB installed), and is also not strongly tested on
190  Debian or on older releases of Ubuntu.
191
192* cluster: Implies workstation and thirdparty. Configures public cluster
193  machines (login-time LVM snapshots, cleanups between logins, public
194  root password, etc.). The snapshot code requires a particular LVM
195  layout that the PXE (netboot) cluster installer sets up.
196
197* debian-dev: Intended for developers of the system itself; provides a
198  set of Debian packages used by Debathena for development.
199
200For the most part a package should be listed in the "Depends:" line of
201a metapackage, but in some cases it is appropriate to hedge by using
202"Recommends:", which will cause aptitude to succeed even if the
203package is unavailable.  For example, a package which doesn't exist in
204all Debian/Ubuntu suites or isn't free can be listed under
205"Recommends:" so that our metapackages still work in all environments.
206
207Developers: Index of cluster packages
208-------------------------------------
209
210Some private workstation admins may want specific pieces of cluster
211infrastructure.  With Athena 9.4, they would typically install the
212entire Athena software suite and then turn off features they did not
213want via /etc/athena/rc.conf.  That is not generally possible in
214Athena 10; a debathena-cluster machine acts like a cluster machine in
215all respects.  Instead, the machine owner should install
216debathena-workstation and then install specific packages they might be
217interested in.  At this time, candidate packages include:
218
219  * debathena-dns-config: Installs a caching DNS resolver and
220    configures the machine to use it.
221
222  * debathena-tmp-cleaner: Cleans files in /tmp and /var/tmp which
223    have not been recently accessed.
224
225  * debathena-reactivate: Causes each graphical login to be performed
226    in a separate ephemeral snapshot of the chroot.  This package
227    requires the root filesystem to be an LVM logical volume inside a
228    volume group with 21GB of free space for the snapshots; if that is
229    not the case, it will break graphical logins.  Install with care.
230
231  * debathena-auto-update: Periodically updates the machine's software
232    and reboots (when no one is logged in) if necessary.
233
234Cluster packages which are generally not of interest to private
235machine owners include:
236
237  * debathena-cluster-login-config: Configures a variety of system
238    services to implement the cluster login policy (no tty logins, no
239    user switching, screensaver logout button after 20 minutes, etc.).
240
241  * debathena-clusterinfo: Looks up the machine's cluster information
242    in Hesiod and caches it on local disk.
243
244  * debathena-larvnet: Reports to the central larvnet server whether
245    anyone has a graphical login to the machine.
246
247  * debathena-syslog-config: Configures sysklogd so that some syslog
248    messages are forwarded to a central logging host.
249
250Release engineer: Bootstrapping the project infrastructure
251----------------------------------------------------------
252
253  1. Create the package repository (detailed instructions on this
254     pending).  Set the DEBATHENA_APT environment variable to point to
255     the package repository.  Put a copy of the debathena "scripts"
256     subdir in your path.
257
258  2. Create the build area.
259
260  3. Run 'reprepro -Vb $DEBATHENA_APT export' to set up the repository.
261     Build each equivs package under meta/ using 'equivs-build --full
262     *.equivs' and upload each with 'daupload-equivs-proposed
263     *.changes', followed by 'damove -proposed "" PACKAGE' (replacing
264     PACKAGE with the name of each equivs package you are moving).
265
266  4. Set up the build server.  The basic structure of the apt
267     repository must work for make-chroot to succeed, so this must
268     happen after step 3.
269
270  5. For each normal Debian package in dependency order, cd into its
271     directory in the build area and run "da sbuildhack *.dsc" and
272     "daupload-release *_source.changes".  If the package contains
273     only an "Architecture: all" binary package, pass the -A option to
274     both commands.
275
276     The all-packages script can generate an approximation of the
277     package list in dependency order, but it doesn't work right yet,
278     and ideally it would be possible to do several builds in parallel
279     using a Makefile like the one in scripts/build-server/build-all.
280     Improvements to this machinery are pending.
281
282  6. For each package under third, run "da ./debathenify-PKG source
283     binary upload".  Any created directories under third/openafs/meta
284     should be chmodded 777 to work around a perl/AFS permissions
285     issue with File::Temp; if this is not done, OpenAFS metapackage
286     builds will fail for other users.
287
288Release engineer: Updating the apt repository
289---------------------------------------------
290
291  1. ssh to the build server as the builder account and change to the
292     canonical build directory.
293
294  2. Run "gen-packages" to update the package list.  (Or "gen-packages
295     -c" if you know the AFS checkout of the source tree is up to date;
296     it should update every half hour.)
297
298  3. Run "ood-packages" to produce a list of out-of-date packages.
299
300  4. For each out of date package, run "dasource PKG".  Then change to
301     the package directory and run "da sbuildhack *.dsc" and
302     "daupload-release *_source.changes".  If the package contains
303     only an "Architecture: all" binary package, pass the -A option to
304     both commands.
305
306  5. svn update the meta directory.  If there are new subdirectories,
307     chmod them 777 to work around a perl/AFS permissions issue with
308     File::Temp.  For each updated subdir, change to it, run
309     "equivs-build --full *.equivs", and then "daequivsupload
310     FILENAME.changes" on the produced changes file.
311
312  6. svn update the third directory.  You can let autodebathenify
313     handle the updated scripts, or you can touch
314     ~/autodebathenify.suppress, make sure it's not running, and run
315     "da ./debathenify-PKG source binary upload" in each updated
316     directory.
317
318Sometimes you may have to mix up the order of the above steps in order
319to handle build dependencies.
320
321Release engineer: Setting up a build server
322-------------------------------------------
323
324  1. Install either Debian testing (or stable, if it's new enough, but
325     see the note about sbuild below) or the latest Ubuntu release.
326     The build server must be installed with free space in an LVM
327     volume group.  The build chroots consume 2GB each.
328
329  2. Install debathena-standard as per the the instructions in
330     http://debathena.mit.edu/install.
331
332  3. apt-key add /afs/dev.mit.edu/system/athena10/apt/athena10-archive.asc
333
334  4. Install the packages listed in scripts/build-server/packages
335     (using "aptitude install").
336
337     Note that currently the build system uses the latest version of
338     sbuild, so if you have not installed Debian testing, you'll
339     need to set up apt pinning to grab sbuild from there. See the
340     apt_preferences man page.
341
342  5. Install debathena-standard, debathena-ssh-server, and
343     debathena-build-depends (using "aptitude install").
344
345     (Depending on how recently debathena-build-depends was rebuilt,
346     additional packages might need to be installed to satisfy the
347     build-depends of newer packages.  This can be taken care of later
348     when an error occurs building a source package.)
349
350  6. Append to /etc/approx/approx.conf the contents of
351      scripts/build-server/approx.conf.tail.
352     Run: /etc/init.d/approx restart
353
354  7. Apply scripts/build-server/mount-defaults.patch.
355
356  8. Edit /etc/lvm/lvm.conf and change "archive = 1" to "archive = 0"
357     in order to avoid generating a bazillion backup files under
358     /etc/lvm/archive.
359
360  9. For each supported DIST (see scripts/debian-versions.sh) run:
361
362       VG=/dev/blah scripts/build-server/make-chroot DIST i386
363       VG=/dev/blah scripts/build-server/make-chroot DIST amd64
364
365     substituting the name of the volume group for blah.
366
367     Example: VG=/dev/dink scripts/build-server/make-chroot intrepid i386
368
369  10. Create a local account for builder with:
370
371        adduser --uid 1047 --disabled-password builder
372
373      Make the home directory mode 700.  Install a
374      daemon/linux-build-10.mit.edu keytab in the home directory as
375      "keytab".  Install a copy of the secret repository-signing key
376      (debathena@mit.edu) in the home directory's keyring with
377      something like:
378
379        kinit builder
380        gpg --export-secret-keys athena10@mit.edu | \
381          ssh -l builder machinename gpg --import
382
383      Create a file named .sbuildrc in builder's homedir containing:
384
385        $nolog = 1;
386        $mailto = 'source-wash@mit.edu';
387        $log_dir = '/tmp/sbuild-logs';
388        $maintainer_name = 'Debathena Project <debathena@mit.edu>';
389        $force_orig_source = 1;
390        $sbuild_mode = "user";
391        1;
392
393      Create a file named .ssh/config in builder's homedir containing:
394
395        Host svn.mit.edu
396          User debuildsvn
397
398      Add builder to the sbuild group in /etc/group.
399
400      Copy scripts/build-server/autodebathenify to builder's homedir.
401      Create a file named autodebathenify.config in builder's homedir
402      containing:
403
404        error_addr=source-wash@mit.edu
405        scripts_dir=/afs/dev.mit.edu/source/src-svn/debathena/scripts
406        build_dir=/afs/dev.mit.edu/project/release/10/build/third
407        packages="cyrus-sasl2-mit evolution-data-server lprng openafs tcsh"
408        export DEBATHENA_APT=/afs/dev.mit.edu/system/athena10/apt
409
410      Copy scripts/build-server/autodebathenify.cron to builder's
411      homedir and install it with "crontab autodebathenify.cron".
412
413      Create a file named .devscripts in builder's homedir containing:
414
415        DEBUILD_DPKG_BUILDPACKAGE_OPTS="-sa -us -uc -i -I.svn"
416
417      In builder's homedir, append to .bashrc:
418
419        add debathena
420        export PATH=$PATH:~/bin
421        export DEBATHENA_APT=/mit/debathena/apt
422
423
424Release engineer: Removing a build chroot on the build server
425-------------------------------------------------------------
426
427  1. Run VG=/dev/blah scripts/clean-schroots as root to make sure that
428     the build chroot is not mounted, substituting the name of the
429     volume group for blah.
430
431  2. Edit /etc/schroot/schroot.conf and delete the section
432     corresponding to the chroot.
433
434  3. Run lvchange -an blah/chrootname
435     substituting the name of the volume group for blah and the chroot
436     name for chroot.  Example: lvchange -an dink/gutsy-i386-sbuild
437
438  4. Run lvremove blah/chrootname
439
440Release engineer: Removing a dist from the apt repository
441---------------------------------------------------------
442
443  1. Inside the apt repository, edit conf/distributions and remove the
444     distribution section.
445
446  2. Run reprepro -Vb $DEBATHENA_APT --delete clearvanished
447
448Release engineer: Setting up a canonical build area
449---------------------------------------------------
450
451  1. Create an empty directory and cd into it.  The canonical build
452     area lives in /mit/debathena/packages/.
453
454  2. Run gen-packages to create the table of normal Debian packages.
455
456  3. Run dasource to create subdirs and source packages for each
457     normal Debian package.
458
459  4. Create checkouts of the meta and third directories:
460
461     svn co svn+ssh://svn.mit.edu/athena/trunk/debathena/meta
462     svn co svn+ssh://svn.mit.edu/athena/trunk/debathena/third
463     chmod 777 meta/*
464
465     A couple of subdirectories of debathena/meta are normal Debian
466     packages, so this will create redundant copies of those.  Ignore
467     them; they won't be used.
468
469Release engineer: Adding a new suite
470------------------------------------
471
472This process is rarely performed and the infrastructure for it is
473imperfect.  Substitute the name of the new suite for "newdist" in all
474steps below.
475
476  1. Make sure the apt repository is up to date with respect to the
477     source tree for the existing dists.
478
479  2. Add the new dist to scripts/debian-versions.sh.  (It is not
480     necessary to add the new dist to codes at this point, but it must
481     be present in the gettag conditional.)
482
483  3. Create the new distribution in the apt repository's configuration
484     file.  Create the skeleton of the dist by running "reprepro -Vb
485     $DEBATHENA_APT export".
486
487  4. On the build server, create a chroot for the new distribution as
488     documented above.  This may require downloading and installing a
489     more recent version of the debootstrap package from the
490     -backports dist corresponding to the build server's OS.
491
492  5. Set the DEBATHENA_BUILD_AREA environment variable to point to the
493     build area.
494
495  6. Fire up screen.
496
497  7. mkdir $DEBATHENA_BUILD_AREA/stamps.newdist.
498
499  8. cd into a checkout of debathena/scripts/build-server/build-all.
500
501  9. Edit Makefile (and check in the edit) so that suite is the new
502     distribution and psuite is the previously most recent Debian or
503     Ubuntu distribution.
504
505  10. Run "make deps.mk".
506
507  11. Run "make -k all STAMPS=$DEBATHENA_BUILD_AREA/stamps.newdist".
508      You can watch the builds happen in the other windows of the
509      screen session.  It's possible to do several builds at once with
510      make -j N.
511
512  12. debathenify packages will fail out; they must be built by hand.
513      When the build fails on one, cd into third/packagename in the
514      build area and run "./debathenify newdist-amd64 -A source binary
515      upload" and "./debathenify newdist-i386 binary upload".  Then
516      touch $DEBATHENA_BUILD_AREA/stamps.newdist/packagename.done" and
517      restart the build.
518
519      The newly created third/openafs/meta directories should be
520      chmodded 777 to work around a perl/AFS permissions issue.
521
522Release engineer: Maintaining autodebathenify
523---------------------------------------------
524
525autodebathenify is a cron job which runs on the builder account and
526keeps the OpenAFS modules and modified packages under debathena/third
527up to date when there are upstream changes.  It relies on the
528following:
529
530  * builder@ATHENA.MIT.EDU has access to a local account named
531    debuildsvn on svn.mit.edu with read access to the athena
532    repository.
533
534  * builder@ATHENA.MIT.EDU has write access to the canonical build
535    area and apt repository in the dev cell.
536
537  * The builder account on the build machine has a copy of the signing
538    private key for the apt repository.
539
540The cron job will silently exit if it detects that it is already
541running.  If it fails for any other reason, it will send mail to
542source-wash@mit.edu and touch a file named autodebathenify.suppress
543which will prevent it from running again until manual intervention.
544It is important to get autodebathenify running smoothly or the apt
545repository will become out of date with respect to third-party
546packages, which in turn will compromise the user experience.
547
548Even if you don't notice failure mail, it's good to check on the
549status of autodebathenify from time to time.  To do this, get tickets
550as builder and ssh to linux-build-10 as builder.  Run "ls -l logs" to
551see what's been going on.  A logfile with size around 48K indicates
552that autodebathenify ran normally but didn't find any new work to do.
553A logfile with size around 60 means that autodebathenify.suppress
554exists and the cron job has stopped running.  A longer logfile
555indicates that autodebathenify attempted to build and upload a
556package.
557
558Possible failure cases include:
559
560  * One of the upstream apt repositories timed out during an "apt-get
561    update" of an sbuild chroot.  If this happens, you can just remove
562    the autodebathenify.suppress file to get the cron job to start
563    running again.
564
565  * autodebathenify tried to build an upstream version which already
566    exists.  If this happens, the build will fail at upload time.  If
567    this happens, there is a bug in the part of the debathenify-*
568    script which checks whether our apt repository already has the
569    expected version of the built package.
570
571  * Debian and Ubuntu have .orig files with the same name but
572    different contexts for a particular third-party package.  This has
573    only happened once, with bash (which is currently not configured
574    into autodebathenify for that reason).  We do not have a general
575    mechanism for resolving such issues at this time.
576
577  * The new upstream version of the package is sufficiently different
578    to cause our modifications to fail to apply, and our debathenify-*
579    script needs to be adapted appropriately.
580
581The cron job is run out of builder's home directory, but its canonical
582source location is in debathena/scripts/build-server in this
583repository, should it need to be modified.
584
585After several months of operation, LVM snapshots on the build server
586will start to become slower and slower, as /etc/lvm/cache/.cache grows
587in size.  Turning off the cache entirely seems to cause schroot to
588occasionally fail; the current solution is to rm /etc/lvm/cache/.cache
589every so often.
590
591Release engineer: apt repository HTTP server setup
592--------------------------------------------------
593
594The apt repository server (debathena.mit.edu) is hosted on
595scripts.mit.edu out of the debathena locker. To replicate it on a
596dedicated server, install Apache and AFS (e.g., debathena-standard
597and apache2), and configure the document root to be
598  /mit/debathena/web_scripts
599
600There's also a crontab in /mit/debathena/cron_scripts that updates
601the package lists on the website. It expects to be able to edit the
602web_scripts directory; on scripts, it does so with daemon.scripts
603permissions.
604
605Trac (http://debathena.mit.edu/trac/) expects to use sql.mit.edu
606for its database.
Note: See TracBrowser for help on using the repository browser.