######################################################################### # The Honeywall Bootable CD-ROM # # by # # The Honeynet Project and the Research Alliance # ######################################################################### Honeywall CD-ROM CUSTOMIZE =========================== Last Modified: $Date: 2005/02/20 19:20:41 $ This document at present is just a free-association brain dump of concepts and theories of how to customize the roo distribution ISO. It will be cleaned up later. Setting up a development environment ==================================== The roo ISO not only serves as a boot-time installation medium, but also contains in itself the seeds for a development environment that allows one to customize the ISO and re-create their own ISO. All you need is the ISO in order to set up a Fedora Core 3 system to act as an ISO "factory" to produce more ISOs, but this time customized specifically for your site. For clarity in describing the ISO mastering process, there are some terms that you will need to know: Foundry, Factory, and Stand-alone modes. Let's look at them in reverse order: Standalone mode --------------- This is the mode that we expect most users will operate within, and does not involve any changes to the Roo ISO we distribute at all. You simply download the latest release ISO, burn it to CD-R/CD-RW, and either customize it using a honeywall.conf file found on a floppy disk, or through use of the the original "dialog" Text User Interface (TUI) and the new "Walleye" web GUI. There is no need to read any further if you plan on using the ISO in Stand-alone mode. Factory mode ------------ This is the mode of customization that someone would use to master their own customized ISOs with local default settings, unique passwords, etc. Factory mode assumes that you have unpacked an ISO that was distributed by the Honeynet Project, and are operating within your development directory. This is the mode documented in this file. Foundry mode ------------ This is the Honeynet Project ISO development mode. Anyone who is developing new features for the roo ISO using the CVS repository and initial ISO creation environment, is working in Foundry mode. (Others can ignore this mode, and it will not be documented here.) Setting up a Factory mode development environment ================================================= To set up a Factory mode development environment, the roo ISO contains scripts and an RPM package that "unpacks" itself into a directory you specify, makes sure the required hw-utils RPM file is installed on your system, and configures ISO creation scripts to make ISOs in that same development directory. If you wish, you can change settings to get consitituent files from different locations, have the ISOs be created in a different location, change release identifiers, etc. Most of this is done with the "hwconfig" program (part of the hw-utils package) and/or by editing the file "Makefile.in". (The development environment is centered around GNU Make and template files that have values written into them by "hwconfig" based on configuration settings the user can control. We may change the extension from .in to something else like .hwin at some point, to avoid conflict with GNU autoconf/automake.) Since the ISO contains everything that is needed to unpack itself, the easiest way to set up the development environment is to simply mount the ISO using a loopback mount and then run the "unpack-iso.sh" script in the top level of the ISO mount point. $ sudo mount -o ro,loop roo-1.0.b-119.iso /mnt $ ls /mnt autorun isolinux RPM-GPG-KEY-fedora-rawhide customization ks.cfg RPM-GPG-KEY-fedora-test dev README-en RPM-GPG-KEY-rawhide eula.txt RELEASE-NOTES-en RPM-LIST-roo-1.0.b-119 Fedora roo rpmlist.txt GPL ROO_BASE_VERSION TRANS.TBL hwconfig.cache RPM-GPG-KEY unpack-iso.sh hwconfig.defs RPM-GPG-KEY-beta hwconfig.defs.example RPM-GPG-KEY-fedora Some may recognize this as looking very much (but not exactly) like the structure of a Red Hat or Fedora install CD. That is because that is essentially what it is, only remastered and modified to use a custom Kickstart configuration file (ks.cfg) to control installation. (This magic was conjured by Earl Sammons and Allen Harper.) [Note: Don't expect to see this exact same structure after you unpack the ISO. Instead, the perspective gets flipped around to that of someone working in Factory mode. It will still exist, only it will be down one level in the cdrom/ directory.) The only file you need to care about at this point is "unpack-iso.sh". It will take care of everything necessary to create your development environment by installing the hw-utils RPM package, creating the development directory (if it doesn't already exist) and configuring the necessary files to make the build process work. From that point on, you only need to "cd" to your development directory and not venture any further if you don't want to. To do this, now run "unpack-iso.sh" like this: $ sudo /mnt/unpack-iso.sh /mnt /usr/local/src/rooiso /mnt/unpack-iso.sh: directory not found: /usr/local/src/rooiso Directory /usr/local/src/rooiso does not exist. Shall I create it? [y/n] y /mnt/unpack-iso.sh Extracting contents of /mnt to /usr/local/src/rooiso/ ... Deleting pesky TRANS.TBL files...Done. Creating links for customization scripts...Done. Configuring development environment...Done. At this point, you can create a functionally equivalent ISO (with no customization changes at all) by simply doing the following: $ cd /usr/local/src/rooiso $ sudo make iso [lots of feedback removed...] -rw-r--r-- 1 root root 274587648 Feb 20 12:15 roo-1.0.changeme-2.iso -rw-r--r-- 1 root root 57 Feb 20 12:15 roo-1.0.changeme-2.iso.md5 make[1]: Leaving directory `/usr/local/src/rooiso' You now have a new bootable install ISO (or you can use the same mechanism to now spawn further Factory mode development directories.) Installing a pre-configured honeywall.conf file ----------------------------------------------- One of the primary reasons for using customization is to set all the honeywall.conf variables to what you want (or something very close to it) before burning your ISO to CD-RW. [Note: Please use CD-RW discs whenever possible to avoid creating a lot of needless plastic waste on unused ISOs.] To get a copy of the distributed honeywall.conf file, you must use "rpm2cpio", or install a Honeywall and copy /etc/honeywall.conf using a floppy disk or SSH. You can learn more about "rpm2cpio" here: http://www.rpm.org/max-rpm/s1-rpm-miscellania-rpm2cpio.html To do this, you would do the following: $ cd /usr/local/src/rooiso $ rpm2cpio cdrom/roo/roo-base*.rpm | sudo cpio -ivd ./etc/honeywall.conf $ sudo mv etc/honeywall.conf customization/ $ sudo rmdir etc $ sudo vi customization/honeywall.conf [make your edits and save.] You can now do "sudo make iso" and you will have a customized ISO ready for you to use main menu option 4, followed by "Defaults from /etc/honeywall.conf". If you set HwHEADLESS to "yes", the Honeywall will auto-configure from this file, just like it would have if you had used a floppy. [Note: This will be integrated into unpack-iso.sh so these steps will be unecessary.] Pre-loading SSH keys -------------------- There are two types of SSH keys you will likely want to pre-install on your Honeywall for remote administration: Public and private RSA and DSA keys for the Honeywall itself (so the management host will be able to authenticate the Honeywall) and public SSH keys for the management account (so the Honyewall can authenticate the incoming SSH connection from the management host). These keys are installed into the ISO in Factory mode by copying them into the customize/ folder. (In this example, we assume you have already generated host RSA/DSA keys that you want to have your Honeywall use on each installation, in the directory ~/honyewall): $ cd /usr/local/src/rooiso $ cp ~/.ssh/id_dsa.pub customize/ssh-keys/ $ cp ~/honeywall/ssh_host_[rd]sa_key* customize/ssh-keys You can now do "sudo make iso". Adding additional RPM packages, etc. ------------------------------------ Anything else you wish to do at install time can be handled by editing the file customization/custom.sh, which is run at first boot by /usr/sbin/bootcustom.sh. The example in customize/ shows what you might do with it. -- Dave Dittrich Information Assurance Researcher, dittrich@u.washington.edu The iSchool http://staff.washington.edu/dittrich University of Washington PGP key http://staff.washington.edu/dittrich/pgpkey.txt Fingerprint FE97 0C57 0843 F3EB 49A1 0CD0 8E0C D0BE C838 CCB5