YACS - Yet Another CD Script :-) ================================ (better known as debian-cd) Copyright 1999-2001 Raphaël Hertzog This set of tools is licensed under the General Public License version 2 or any later version. You can find it in /usr/share/common-licenses/GPL on a Debian GNU system. Thanks to Steve McIntyre for his work on slink_cd/debian_cd. Some ideas come from his script. Thanks to all the contributors on the debian-cd mailing list. What is needed? =============== Software: - the apt-get (>= 0.3.11.1) tool - apt-utils (for apt-ftparchive) - perl (>= 5.004) - bash (or another POSIX shell) - make - mkisofs/mkhybrid (mkisofs also provides the isoinfo binary used by the Pseudo Image Kit) - the perl Digest::MD5 module - lynx (for text version of README.html) and todos from sysutils to convert docs to DOS format (although you can rip that out, too) - if you want to generate jigdo files: jigdo-file (see below) Other: - lots of free space on your disks - a Debian mirror, on a partition where you can write. If you can't write on it then you may try to use a symlink farm, but it's not the recommended way to build Debian CDs. ------------------------------- - GENERATING DEBIAN CD IMAGES - ------------------------------- For the people that don't have time, here's the quick explanation: ================================================================== Edit the CONF.sh and change the PATHs for the mirror and so on. $ sensible-editor CONF.sh $ . CONF.sh $ make distclean $ make status $ make list COMPLETE=1 SIZELIMIT1=625000000 SRCSIZELIMIT=665000000 $ make official_images [ alternatively, if you only want binary images: $ make bin-official_images ] However, you really should consider reading further for more information. You can also take a look at build.sh and build_all.sh for an automatized way of building CD images. How to build a CD set - step by step ==================================== If you haven't already, change to the /usr/share/debian-cd/ directory (or, alternatively, set the variable BASEDIR in CONF.sh to point there). The process of building a CD is composed of the following steps: - first configure what is needed in CONF.sh and source it in your shell: $ . CONF.sh The exported environment variables will be used by all the tools involved here (Makefiles, perl scripts, shell scripts). If you want to build CD images for more than one arch, you will have to build them one after the other (you may use a shell script for this). Note that the temporary dir must be on the same device than the mirror because debian-cd uses hardlinks for generating an image tree. If you can't do this, you'll have to use the symlink farm. The symlink farm is explained at the end of this README. Keep in mind that the environment variables will stay in the environment after your debian-cd run, and may interfere with other program using the same variables (e.g. kernel-package). So if you want to be 100% safe, run debian-cd in a separate shell that you can leave after you're done. - then we clean everything that may still be there from previous runs: $ make distclean - now we'll check if your mirror is ok (with good Packages files): $ make mirrorcheck - then we initialize the temporary directory used for the build: $ make status If this has failed then this will be automatically launched: $ make correctstatus Note however that "make status" should never fail if it is used for building a CD set for the stable release... - now you can decide what you want on your CDs $ make list TASK=tasks/debian-2.2 COMPLETE=1 or $ make list TASK=tasks/gnome COMPLETE=0 SIZELIMIT=576716800 or $ export NONFREE=1; make list TASK=tasks/your-task-here COMPLETE=1 or for something like an official image for the USA (without non-US & non-free) : $ make list COMPLETE=1 SIZELIMIT1=576716800 .... take a look at the file tasks/* to see the options you can have :) You can change the behaviour of this command with the following variables: - if NONUS is set, then packages from non-US will be allowed (the value of NONUS must be the path to the non-US mirror if you have one) - if FORCENONUSONCD1 is set also, then packages will be rearranged so that non-US packages are all on CD#1. This includes the non-free ones if you specify NONFREE. Then 2 separate copies of CD#1 will be produced, identical in every respect except for the inclusion/lack of non-US packages. The same happens for the source CDs when they are built. - if NONFREE is set, then packages from non-free will be allowed (NONFREE must be exported to all sub-shells) - if EXTRANONFREE is set, then non-free packages will be included on an extra CD (the last CD in fact). Don't use NONFREE and EXTRANONFREE at the same time ! (EXTRANONFREE must be exported to all sub-shells) - if COMPLETE is set, all packages that are not listed in the selected task file will be included at the end - if SIZELIMIT is set, it will be used as the maximum size that we can put into each CD - if SIZELIMIT (with beeing a integer) is set, it will be used as the maximum size of the X'th binary CD. SIZELIMIT overrides SIZELIMIT ... - if SRCSIZELIMIT is set, it's used as the maximum size for source CD - if SRCSIZELIMIT (with beeing an integer) is set, it will be used as the maximum size of the X'th source CD This target calls the targets "bin-list" and "src-list" that can be used to build only binary CDs or only source CDs. - it may be time to add the disks-arch stuff and to make the CDs bootable: $ make bootable This affects only the binary CDs. If you want to use boot-floppies built by yourself you can add a parameter BOOTDISKS= which specifies the directory where they are. Note that $BOOTDISKS/current must be a symlink to the real directory and it must follow the same setup as the FTP mirror. Your boot-floppies must also be on the same partition as your mirror and temporary dir (hardlinks are used here too). Size calculation is imprecise for bootable CDs (usually the first CDs in the set), so you may need to manually adjust SIZELIMIT* variables to account for the size of the booting stuff used. - now, we'll add the binary packages to the temporary tree: $ make packages - and we'll add the sources to the temporary tree: $ make sources - if you want to install additional files: $ make bin-extras CD=1 ROOTSRC=/home/ftp/ DIR=goodies/wordperfect $ make src-extras CD=3 ROOTSRC=/home/ftp/ DIR=goodies/kernel-2.3 The first will copy /home/ftp/goodies/wordperfect/ to the first binary CD. It will be in /goodies/wordperfect/. You can call make extras multiple times if you need more. Please note that the files to be copied should be on the same partition than your mirror (unless you use a symlink farm). If you want to do customize your CD even more, you can use the hook system. Read more about that below. - We can add an md5sum.txt file on each CD to enable users to check their files: $ make md5list This calls the targets 'bin-md5list' and 'src-md5list'. You can choose to call only bin-md5list if you're building only binary images. - now we can create the images: $ make images If you don't have enough space for all images, you can generate only one image (of the second binary CD for example) with: $ make bin-image CD=2 Of course if you want to build all binary images you'll use: $ make bin-images The following will generate the source images: $ make src-images Note: here we use "make images", but you could as well use "make official_images" since the latter is the same as the former with some dependencies on targets that you already launched (make bootable packages sources). - if you want to generate a MD5SUMS file with the md5sums of the images you can do it with: $ make imagesums Official images =============== If you use make official_images you're building CD images that have the same properties than official CD images but they still doesn't have the name of "Official Images". The name of the images is given by setting the OFFICIAL and DEBVERSION environment variable (check CONF.sh). Please never ever use the "Official" name for a CD image that you built yourself. The only images that can be called "Official" are the ones built by Debian itself and which are provided on Debian's servers. The default configuration shipped with this package will automatically name the images "Unofficial". CD will work exactly in the same way with all Debian tools, only the label is different. That means you can use build.sh and build_all.sh to build your "Unofficial" images without modifying anything. Local packages ============== If you provide some custom made packages and you want to put them on Debian CD set you can do it. Simply put your packages in $MIRROR/dists/$CODENAME/local/binary-$ARCH/
. The organization of this sub-tree is the same than what you can find in the main, contrib or non-free part. You may use different section names if you want. Be sure to create Packages files (and Sources.gz if you include sources). You can also put your local packages under $MIRROR/pool/local (just a new facility for people who don't want packages under dists/). To include local packages, the LOCAL environment variable must be set to "1" while building the CDs. You can also set the LOCALDEBS environment variable, and it will be used instead of MIRROR when looking for local packages. Additional targets ================== Jigdo ----- You may also want to make the CD images available in jigdo format. Jigsaw Download, the successor to the Pseudo-Image Kit. See http://www.debian.org/CD/jigdo-cd/ for more information on jigdo. Set the DOJIGDO and related variables in CONF.sh. This is no separate target for jigdo, merely a modification of the "images" targets. You can choose only .iso generation (default), only .jigdo generation (for highly reduced disk usage), or both .iso and .jigdo generation. To generate the jigdo files and templates, you need the "jigdo-file" program, which is available via the same URL. Jigdo-file creates and maintains a cache/database file with checksums of all files on your Debian mirror. The first time, this may take hours to be generated (use "top" to see what's going on), so it's wise to keep the cache in your homedir and not delete it ever. Note that jigdo-file can easily use 60+ MB of working memory, so don't use this on machines with less than 128 MB RAM. The MD5SUMS file generated by the "imagesums" target will contain the MD5 checksums of all generated images, regardless of the DOJIGDO setting. If no full iso image is available, the MD5sum will be extracted from the .template file. A note in the Makefile shows how the original file size can be extracted from the .template in a similar way. About jigdo "fallback servers": jigdo works by downloading individual packages and other files from a normal Debian mirror, and using them to regenerate a CD/DVD image. However, the content of Debian mirrors changes over time, files are added and removed. But jigdo must have access to all files needed for the image it has to regenerate, even those that have been removed from the normal Debian mirrors. A fallback server contains a backup of the Debian FTP space for the moment the .jigdo files were generated. This backup is made available under a certain URL which is written to the .jigdo files. jigdo will *only* revert to the fallback server after an unsuccessful attempt to retrieve a file from the normal user-selected Debian mirror, so the bandwidth requirements are modest. A fallback is even necessary for .jigdo files of the stable release, because some files (typically documentation or boot floppies) can change at any time. debian-cd allows you to automatically create a directory on disc which is suitable for use as a fallback mirror. It is populated with hard links to the archive contents. In CONF.sh, simply supply as JIGDOFALLBACKPATH the name of the directory, and as JIGDOFALLBACKURLS the URLs under which it will be made available (two separate URLs are necessary, one for "Debian" and one for "Non-US"). About the hook system ===================== A hook script can be executed at different times. You can specify the script by setting the HOOK variable to the script filename. It will get 2 arguments, the first is the CD number. The second depends on where/when the hook script is called. It can be 'before-scanpackages' or 'before-mkisofs' (their values are explicit ...). When the script is called, the current directory will be the temporary directory used for the build (aka $TDIR/$CODENAME-$ARCH). There are hooks only for binary CDs at the present time. If HOOK is not set, it will look for a script $BASEDIR/tools/$CODENAME.hook. About the symlink farm ====================== If you don't have write access on the disk where you have the mirror or if for another reason hardlink cannot be used, you can try to use a symlink farm. Instead of having real files, your temporary tree will be filled with symlinks that mkhybrid will change into files when it will build the image. You'll need to use a special options. You have 2 lines of options in CONF.sh as examples. I've never tested the symlink farm ... it may well generate unusable images. Don't use it for ISO images that will used by many users. Note that you will also need a patched mkhybrid that does support the -F option. Have a look here about it : http://www.chiark.greenend.org.uk/~stevem/DebianCD/ The mkhybrid package in Debian does support this -F option since potato (Debian 2.2).