Fireball ISO is a VMWare virtual appliance that builds a bootable ISO image containing a hardened, custom version of Gentoo Linux, focused on providing firewall and other services to a network. This image may be burned to a CD (where it may be called a LiveCD), allowing an otherwise unused, old computer to boot it and act as a network security device, or it can be used in a virtual machine.
Even though this document is focused on using this product to generate a bootable firewall ISO, the product can be changed to perform any tasks for which a bootable (and potentially encrypted) Linux ISO makes sense. Perhaps it would be suitable for a secure cloud appliance. I would be very interested in the ideas everyone has - feel free to share through email or forum postings.
When the 1.3 release came out more than three years ago, I had thought that it might be the last release; it can be easily updated and modified, and so it wouldn't get out of date as long as Gentoo was maintained. However, Gentoo has made some sigificant changes in the past few years, and I wanted to save new users from having to spend time making those changes. Also, I continue to tinker, and feel it's time to change the focus to a simpler system, with features removed that no one has expressed interest in (like gogoc IPv6 tunnels, DSL support, etc.), to be a bit more secure by default; should you need these or other features, documentation exists on the Internet and elsewhere, and I'm happy to help after your own best efforts.
Please keep in mind that I myself wrote little of the software in this virtual appliance, and have no wish to take credit for the efforts of many open source software developers and companies who have been very generous with their time and knowledge. My main contribution was bringing everything together by following instructions written by the Gentoo and wider Linux communities (and occasionally providing additions or corrections), installing packages, setting up configuration files, writing scripts and documentation, and lots of testing and tweaking. If you have questions or problems with any specific software in this virtual appliance, you are more likely to get the quickest and best help in these places, in order:
If you have security issues related to the fundamental design or implementation of Fireball as a whole, please send them to me, with FIREBALL SECURITY in the subject line somewhere. These should be flaws with the underlying design or implementation of the unmodified Fireball virtual appliance. I will do what I can to address the issue, and may release updates if warranted. Whatever happens, in the end you are ultimately responsible for the security of your network, including your Fireball installation. If you don't feel that Fireball meets your needs, feel free to modify it, or simply don't use it.
Security problems with individual pieces of software should be referred to the authors or maintainers of that software; their contact details should be in the documentation of the applicable software. Make sure you have the latest versions and are following the recommended usage guidelines before you report problems. Of course, since Fireball is a very customizable system (like Gentoo itself), and any software can be configured in an insecure manner, you should not report issues related to any inherently-insecure configuration (like setting up poor firewall rules, installing insecure services, and so on).
Suggestions for new features are always welcome. I'm very interested in how you use Fireball, and how you modify it; perhaps others would be interested in your modifications. Constructive criticism would help to make Fireball ISO better, especially if it helps improve security and usability. Feel free to contact me with your stories and ideas.
Note: this will cover a very basic setup. For more details, please refer to the Gentoo documentation links above.
Start the virtual machine, and log in as
as the password. (Note: depending on your network setup, after startup
you may need to wait a while for
network services to time out before you can log in; if this occurs, it
will cease to be a problem after you configure
the network for the appliance.) You are now in the "base environment",
which is a
basic Gentoo installation that holds the Fireball build environment (a
collection of files that eventually become the bootable ISO
of your Fireball system).
The first thing you need to do is change the password of the base environment.
Note: make sure you record this new password in a safe place. If forgotten, there are ways to change or recover a lost root password; Google for methods. Fireball doesn't protect against these password recovery methods, so if this is a risk for you, you should implement protections against these methods (again, Google for protection methods).
I set my timezone to my local one, but others may wish to use UTC; it's up to you.
This uses CST6CDT as an example; replace with your desired timezone:
cp /usr/share/zoneinfo/CST6CDT /etc/localtime
Add your timezone name to this file:
nano /etc/profile # set the TZ variable to your timezone name # (example: export TZ=CST6CDT)Set "clock" variable to "UTC", or "local" if timezone is not UTC:
Set the IPv4 address.
ifconfig net0 [IP address desired]
Set your default gateway.
route add default gw [IP address of default gateway] net0
Now edit the
/etc/conf.d/net file with the same IP address and default gateway; this will save
them to be set at each reboot.
OpenDNS servers are already configured as the DNS servers. If you prefer, edit
and replace the existing OpenDNS IP addresses with others (for example, the DNS servers of
your ISP). If you choose to use the OpenDNS ones, you might wish to see http://www.opendns.com
for information on using their services.
The SSH server should start automatically when you boot up the Fireball appliance, and create new server keys. If you like, you can ssh to the machine, using the IP address you just set, and work with it from there.
One security change you should consider is to restrict the SSH server
to only listen on the IP address(es) on which you want to connect to
it. By default, the SSH server will listen on all interfaces, and you might not
need that. For example, I want my SSH server to listen on my local IPv4
and IPv6 addresses, but I don't want it to listen on my globally-reachable
IPv6 address (since I will not need to connect to my base environment
using that address); to accomplish that, I'll add the following lines to the
# listen on this local IPv4 address ListenAddress 192.168.2.1 # listen on this local IPv6 address ListenAddress fe80::20c:29ff:feae:4631%net0Note: make sure to use your own IP addresses. Include the correct interface at the end of link-local IPv6 addresses. To make these changes effective without rebooting, simply restart the sshd server:
/etc/init.d/sshd restartThen check that the ssh server is only listening (with TCP port 22) on the IP address(es) that you specify:
You can display the existing firewall rules with
fw (which is an alias for
iptables -nv -L); same with
fw6 for ip6tables
rules. Other display options can be added after the alias; for example:
fw6 # display all ip6tables rules fw INPUT # display only the iptables rules in the INPUT chain fw -t nat # display only the iptables rules in the nat tableYou might not need to make much, if any, modifications to these firewall rules, except possibly restricting SSH access to the allowed address(es), but you will definitely need to edit the rules later in the build environment, which will be used by the generated ISO.
You may like to change the existing update and/or rsync servers,
perhaps to ones closer to your geographical location. If you have Internet access, one easy way to do
this is to use
For a list of Gentoo update servers, run this and choose a few servers:
mirrorselect -i -o >> /etc/make.confFor the Gentoo rsync server, run this and choose one server:
mirrorselect -i -r -o >> /etc/make.confNow edit the /etc/make.conf, check the lines added at the end, and remove any duplicate SYNC or GENTOO_MIRROR lines above these.
Note: if you have a local rsync server, you can manually add that instead of using the
mirrorselect command above. It makes sense to set up your own if
you have more than one Gentoo installation in your local network, and it's very easy to do. Instructions are at
http://www.gentoo.org/doc/en/home-router-howto.xml - search for Rsync Server.
grep SYNC /etc/make.conf >> /root/livecd/source/etc/make.conf grep GENTOO_MIRROR /etc/make.conf >> /root/livecd/source/etc/make.confThen edit the file to remove duplicate SYNC or GENTOO_MIRROR lines if needed
To avoid generating too much traffic with the public sync servers, it's recommended not to sync with them more than once a day. This will help ensure that these free servers remain available to you and everyone else.
Note: the portage tree is not included with the Fireball virtual appliance, which reduces the size of the download, and would quickly get out of date anyway. While syncing will work eventually, it will be very slow the first time, so run this command to download the entire tree quickly:
emerge-webrsync # do this to get the entire portage tree
Once you have a portage tree, it's usually more efficient in time and bandwidth to sync it to get updates:
nano /etc/ntpd.confBy default, the NTP server doesn't listen on any ports or allow other hosts to synchronize their time with it, as a security measure. Note: occasionally you may see that the time isn't correctly set, especially if your base environment was in a suspended virtual machine. You may tell the NTP server to restart (when the configuration will cause the time to be updated) by running this command:
After you have configured the base environment, you should update it with newer software versions, like any other Gentoo system:
emerge –-sync # not needed if run earlier that day in the build environment emerge -aD --update --tree world
Make sure when you update configuration files (with
or other means) that you don't accidentally overwrite the important
configurations you need for your system to function. You should periodically do these update
commands, to ensure the base system run current versions of software. It's a good idea to take VMWare
snapshots of the Fireball appliance before major changes, to help you to restore quickly from unexpected problems.
You should occasionally back up the whole VMWare appliance as an additional safety measure;
snapshots are not the same as backups.
Most of your customization work will likely be inside the path that
holds the files that will become the generated Fireball bootable ISO
(what we'll call the
"build environment"). Most of the time, you'll need to
chroot into it. Simply run this command:
/root/setup_chroot.shand you'll be working inside the
/root/livecd/sourcedir as if you had booted into a Gentoo machine with that path as the root directory.
When you're done working in the build environment, exit the chroot by running the following commands:
exit /root/run_after_exiting_chroot.shThe last command will restore the previous environment; if it's not restored properly, problems may occur. (Note: for quick edits to specific files in the build environment, you can access the files without chrooting first by finding them in
/root/livecd/source/[path/filename]- this is what we did in the optional section above. Make sure that you don't get confused and start changing files in the base environment when you meant to change them in the build environment.)
Run the commands below after chrooting into the build environment with the
passwdAgain, this should be kept safe, so no unauthorized individuals can log in to the system. This is only a partial protection; enable encryption below (during the build process) for more protection.
Configure your IP address for the build environment; this won't be active until you actually generate the ISO and boot it up.
nano /etc/conf.d/netNote: the default setup has
net2as internal interfaces, and
net1as a potential external interface; be aware that there is no
/etc/init.d/net.net1to assign it a static IP address. If you have more interfaces or need a different setup, you'll need to make the appropriate changes.
If desired, edit
/etc/resolv.conf and replace the existing OpenDNS IP addresses with
other server IPs (for example, the DNS servers of your ISP).
Note: if you're using Fireball ISO as your Internet
router/firewall, the DNS servers in this file might be replaced
with your ISP's DNS servers, depending on how it assigns you an IP
address when your the ISO boots up. If you want to prevent this file
from being overwritten with other values from your ISP, remove the
usepeerdns line from the
Set the host name & domain name - replace the default name with the name of your server:
Generate new keys for your SSH server:
/usr/bin/ssh-keygen -t rsa -f /etc/ssh/ssh_host_rsa_key -N '' /usr/bin/ssh-keygen -t dsa -f /etc/ssh/ssh_host_dsa_key -N '' /usr/bin/ssh-keygen -t ecdsa -f /etc/ssh/ssh_host_ecdsa_key -N ''
Here we will modify the configuration for the DNS cache server (which provides DNS lookups to your network and caches them for quick replies). The same program can also provide DHCP services if you like.
dhcp-range, and put in the address range that you'd like to use.
dhcp-hostline for them. Look at the existing examples in the file to see several ways you can do this.
Set the timezone to your local one or UTC.
ls /usr/share/zoneinfoThis uses
CST6CDTas an example; replace with your desired timezone:
cp /usr/share/zoneinfo/CST6CDT /etc/localtimeAdd your timezone name to this file:
nano /etc/profile # set the TZ variable to your timezone nameOnce again, set "clock" variable to "UTC", or "local" if timezone is not UTC:
Set these up in
/etc/make.conf, similar to the base environment. However, the
rsync one is optional; since the base environment and build environment share
/usr/portage/* directories, if you sync in one, the other will not need sync again that day. If you always
sync in the base environment, you
won't need to have an rsync server configured inside the build
environment. However, you will still need to update the programs in
You can use the default Gentoo NTP servers, or edit this files and add others:
nano /etc/ntpd.confBy default, the NTP server doesn't allow other hosts to synchronize their time with it.
As in the base environment, the
ip6tables rules are very basic; you can edit them in
/var/lib/ip6tables/rules.save. If you're doing this on a live system, you can then reload the rules with
/etc/init.d/iptables reload and
/etc/init.d/ip4tables reload; alternately, you can add the rules with iptables commands, then save the rules with
/etc/init.d/iptables save and
/etc/init.d/ip4tables save. There are many guides to firewall rules; google for both IPv4 and IPv6 recommendations, since it's important to cover both.
You should be able to use the virtual appliance on any hardware, thanks to the VMWare hardware emulation. However, the Fireball ISO LiveCD that is generated from the build environment needs to have drivers for whatever hardware that you will use to run it, so you may have to customize and compile the kernel. You will need to decide whether to configure the kernel manually or use a program that will automatically configure and compile the kernel.
For the base environment, you may manually compile the kernel or use the genkernel program to compile it for you, and it doesn't need an initramfs; however, the build environment currently needs genkernel to make at least the initramfs (if not the kernel too), regardless of whether you want encryption or not.
Advantages of using genkernel
The kernel configurations used in compiling the host environment and build environment kernels
are in the
/root directory of each environment – you can load and modify these to
generate your own customized kernel. Follow the instructions in the Gentoo documentation pages.
If you want to manually compile the kernel, skip to hereTo use genkernel to compile kernel:
# suggested options: # - don't save kernel config to /etc/kernels (this assumes you back it up yourself) # - don't run "make clean" or "make mrproper" (might make build faster if you've done it before, # but don't use these options if there are compilation problems) # - use a specific config file rather than a generic one # - copy new kernel to grub bootloader (it's somewhat intelligent, but still check the grub # file afterwards, since you will need change/add options for new entries) # - add support for LUKS encryption (only needed in build environment if you want encryption) # line broken up for readability genkernel --no-save-config --no-clean --no-mrproper --kernel-config=/root/kernel-config-3.17.7-hardened-r1 --bootloader=grub --luks all
If you used genkernel to compile kernel, skip hereTo manually compile kernel:
# change to the directory that holds the kernel cd /usr/src/linux # optional; you can change the kernel configuration if needed make menuconfig # build kernel & modules make && make modules_install # copy the new kernel to the boot directory - it can be whatever name you like cp arch/x86/boot/bzImage /boot/[name of kernel] # build initramfs used in booting up the LiveCD - remove the "--luks" option # if you don't want ISO encryption (command line broken up for readability) genkernel --no-save-config --no-clean --no-mrproper --kernel-config=/root/kernel-config-3.17.7-hardened-r1 --bootloader=grub --luks initramfs
Note: if you've cleaned
/var/cache/*, you might get an error here, regarding
genkernel source code being missing. To solve this,
just re-emerge them
emerge -a busybox genkerneland re-run genkernel.
Note: if you have previouly generated an initramfs that supported encryption, and you wanted to make an unecrypted ISO (or the other way around), simply rebuild the initramfs with the appropriate options; you don't need to rebuild the kernel. You'll still need to generate the right kind of ISO with the build script; see below for the options.
Note: with newer versions of grsecurity, it's no longer a problem to have the
CONFIG_PAX_MEMORY_UDEREF kernel option (in the
Security options -> PaX -> Miscellaneous hardening menu) enabled for kernels being
run in some hardware-assisted virtual environments. This option is now recommended for all
environments; as with all options, do your testing with your own hardware to be sure.
# add the new kernel and initramfs to the grub config (or check them if you had # genkernel add them, and make any changes needed) nano /boot/grub/menu.lstNote: if you intend to use encryption in the generated ISO, you will need a few different options in the
kernelline in your grub config than if you weren't using encryption. For example:
# without encryption (kernel line split up for readability) title=Fireball Personal LiveCD (title can be what you like) kernel /boot/kernel-genkernel-x86-3.17.7-hardened-r1 root=/dev/ram0 init=/linuxrc ramdisk=8192 looptype=squashfs loop=/livecd.squashfs udev nodevfs cdroot initrd /boot/initramfs-genkernel-x86-3.17.7-hardened-r1 # with encryption (kernel line split up for readability) title=Fireball Personal LiveCD 3.17.7-hardened-r1 encrypted kernel /boot/kernel-genkernel-x86-3.17.7-hardened-r1 root=/dev/ram0 init=/linuxrc ramdisk=8192 crypt_root=/dev/loop real_root=/dev/mapper/root looptype=squashfs loop=/livecd.squashfs udev nodevfs cdroot initrd /boot/initramfs-genkernel-x86-3.17.7-hardened-r1_luks
As needed, you should update the build environment with new software versions, like any other Gentoo system. You should consider creating a new ISO after significant updates.
emerge –-sync # not needed if already run today in the base or build environment emerge -aD --update --tree worldMake sure when you update configuration files (with
etc-updateor other means) that you don't overwrite the important configurations you need for your system to function. Regular backups (and VMWare snapshots) are important, so you can easily recover from unexpected problems.
Since the Fireball ISO is intended to be a security product, you should remove things that you don't need in order to reduce potential threats. However, if you're using the appliance for another purpose, your needs will dictate the packages that you install. You can remove any software packages that you don't think you'll be using with:
emerge --unmerge [package name]Alternately, you can edit the build script to delete specific executables, esepecially if you don't want to remove a whole package that might provide some binaries that you actually need. For features built into the kernel that you don't want, you'll have to recompile the kernel to remove them. It's definitely worth the trouble, since it will help your system be more secure by reducing the potential attack area. To be safe, consider making a VMWare snapshot before doing significant changes, or ones that you're not sure about.
Feel free to customize the Fireball build environment how you see fit. This can be as flexible as a regular Gentoo Linux installation; documentation exists on the Internet for most things that you would like to do. If you'll be using the generated ISO as a security device, as stated previuosly, you should consider limiting the programs you add in order to reduce the possible vulnerabilities that the system could have.
If you have questions or problems with any of the software in the build environment, please consult the documentation and the authors of the programs.
While inside the chrooted build environment:
cd /root ./clean.shThe above script generates a list of files such as compilers, source code files, and many more things that are unneeded on the ISO; files contained in this list are removed by the build script before the ISO is assembled. You may need to change the script if you're using the generated ISO for something other than a firewall device. After running the clean script, leave the build environment chroot and restore the base environment:
exit /root/run_after_exiting_chroot.shNow build the Fireball ISO.
/root/build_cd.sh [options - see below]
A simple overview of the build process
/root/livecd/source/*are copied to
/root/livecd/target/*, excluding many unnecessary directories and files to speed things up.
/root/livecd/target, and a compressed squashfs file is generated from the files in that directory hierarchy.
Change in 1.4: the build process is now much more optimized for both encrypted and unencrypted ISOs. Rather than copying/pasting lots of dynamically-generated commands, as required by previous versions, now the unecrypted process is completely automated, and the encrypted process has dynamically-generated scripts that can be run after unscriptable actions, which has eliminated copy/paste.
The build script now requires the user to specify whether they want an encrypted or unencrypted ISO, and whether the ISO is a deployment or test version
Usage: ./build_cd.sh [-e|-u] [-d|-t] One option of each set is required on the command line -e (e)ncrypted LiveCD - requires password to decrypt at boot -u (u)n-encrypted LiveCD -d (d)eployment LiveCD -t (t)est LiveCD (for testing; some services can be disabled)The encrypted and unencrypted options each require a different initramfs file, built by genkernel; see above for options. The ISO will not boot with the incorrect initramfs.
For example, if you want to build an encrypted ISO for deployment, you would use these commands in the base environment:
cd /root/ ./build_cd.sh -ed
A few notes on "test" builds:
If you don't need encryption, skip to the Build the ISO section.
To support the optional encryption, the build_cd.sh script generates the appropriate commands, setting Bash enviroment variables along the way. In the past version, the user had to copy/paste the commands to run them, but now the build script generates two other scripts with the commands; some commands aren't easily scriptable, so each script in the chain helps work around this. Just follow the instructions printed by the scripts.A rough description of the encryption process - see the build script for the exact commands:
# define space for encrypted container, where [SIZE] is the size of the # squashfs file (in 512-byte blocks) + 2056 for LUKS overhead dd if=/dev/zero of=livecd.squashfs.encrypted.img bs=512 count=1 seek=[SIZE] # associate an available loop device (like /dev/loop) with the container file losetup [loop device] livecd.squashfs.encrypted.img # create the LUKS container - answer YES and enter your chosen passphrase twice cryptsetup -y luksFormat [loop device] # open the newly-created container, with the passphrase cryptsetup luksOpen [loop device] root # copy the squashfs file to the container dd if=/root/livecd/target/livecd.squashfs of=/dev/mapper/root bs=512 # mount the container and do a quick visual listing to make sure the squashfs file # was copied correctly mkdir /mnt/test/ mount /dev/mapper/root /mnt/test/ ls -l /mnt/test/ umount /mnt/test/ rmdir /mnt/test/ # close the container cryptsetup luksClose /dev/mapper/root # delete the loop device association losetup -d [loop device] # overwrite the old squashfs file with the encrypted container mv livecd.squashfs.encrypted.img livecd.squashfs
The build process may take 10 minutes or longer, depending on the
speed of your computer, whether it's the first time
you've built an ISO in this appliance (or if you've recently cleared the
/root/livecd/target directory), or if you select encryption. The generated ISO will be placed
/root/livecd/livecd.iso, ready for copying and burning as needed.
Note: while the build process has been improved over previous versions, there's certainly room for more improvements in the methods used, as well as in the size of the resulting ISO. Feel free to experiment if you like, but be sure to make snapshots or backups so you can easily restore if something goes horribly wrong. If you come up with good improvements that you'd like to share, feel free to let me know.
If you like, you can make modifications to configurations inside this virtual test machine, and see how things work (though you'll be unable to compile anything here, since all compilers are removed). For any changes you want to keep, you'll need to make the same changes in the Fireball appliance build environment.
If you want to make copies of the entire virtual appliance (definitely recommended for backups), here's some ways to reduce its size and allow it to compress even smaller:
/root/livecd/target/*directory; they will be created again when you build the next ISO, though the build will take a little longer.
rm -rf /root/livecd/target/*
rm -f /root/livecd/livecd.iso
rm -rf /usr/portage/*
rm -rf /root/livecd/source/var/cache/*
rm -rf /var/cache/* # Optional; perhaps some slight risk here
cat /dev/zero > /root/zeros.bin; sync; sleep 1; sync; rm -f /root/zeros.binWhen you're ready, shut down the virtual machine
shutdown -h now
Power-down the virtual machine if this hasn't already occurred, then exit whatever VMWare program you use.
*.lockfiles inside the directory containing the virtual appliance - these aren't needed.
You are solely responsible for the security of your computers and network. The Fireball system can be a part of your security plan, but must not exclusively be relied upon to provide complete security. A good security plan can include regular system updates on all machines in your network (including your Fireball ISO LiveCD), complex passwords, network and host intrusion detection and prevention systems, network and host firewalls, virus scanners, anti-spyware programs, user training, policy auditing, penetration testing, and so on.
Update Fireball regularly by updating the software packages in both the base and build environments, and generate a new LiveCD. Since this system will become out of date as time goes on, updating it will provide you with the latest program versions, including bug and security fixes. Having said that, though, updating or otherwise modifying the system also introduces the risk of adding new bugs or problems. You should make backups before introducing significant changes, and test those changes to make sure they work as desired.
Read system logs for signs of system problems, attacks, or compromises. Security books, email lists, and Google can help here.
Tweak firewall settings as needed to both protect your network and
allow your supported network activities. Remember that there are two
iptables (for IPv4) and
ip6tables (for IPv6). Each has its own set of rules, which may need to
change over time.
/root/run_after_exiting_chrootone or more times (it may take multiple times), until you get umount errors with paths "not mounted". Then run the build script again.
You're encouraged to test ISOs in a virtual machine as noted above. Virtual testing may save you some CDs, and allows you to tweak things until you're satisfied.
If you make a copy of the appliance, and change the virtual machine ID, you will
find that the virtual network interface card (NIC) name will change. If you want the NIC to still be
net0, etc., you can edit
/etc/udev/rules.d/70-my-network.rules and put the current
MAC for each NIC in the line with the interface name you want for it,
then restart udev and your network (or just reboot).
ISO Boot errors
The programs used in Fireball ISO are governed by their applicable licenses, viewable through their man pages or other documentation.
"Gentoo" is a trademark of Gentoo Foundation, Inc. Gentoo Linux and Hardened Gentoo are actively used, developed and maintained by lots of smart, passionate, and friendly people around the world. http://www.gentoo.org/
This Fireball ISO documentation is based in part on http://www.gentoo.org/doc/en/gentoo-x86-quickinstall.xml, and is also licensed under Creative Commons.