Fireball ISO 1.1 - indy@seerofsouls.com
Table of Contents
Summary 1
Features 2
Where to go for help 2
Security issues 3
Comments and suggestions 3
Base environment configuration 3
IP address 3
SSH keys 4
Gentoo rsync and update servers 4
Updates 4
Build environment configuration 5
IP address 5
Host name 5
SSH server keys 5
Set your root password 5
DNS servers 6
DHCP & DNS cache config 6
Set your local timezone 6
Gentoo rsync and update servers 6
NTP timeserver 6
PPP setup 7
IPTables & IP6Tables rules 7
Kernel configuration 7
Updates 7
Optional: IPv6 Internet connectivity 8
Remove unnecessary packages 8
Customization 9
Building the Fireball LiveCD 9
Testing the Fireball ISO 9
Making copies of the Fireball virtual appliance 10
Security Reminders 10
Troubleshooting 11
General troubleshooting 11
NIC interface changing for virtual appliance copies 11
Credits, etc. 11
Fireball is a VMWare virtual appliance that builds a bootable ISO image containing a stripped-down custom version of Gentoo, focused on providing firewall and other services to a network. This image may be burned to a CD, allowing an otherwise unused, old computer to boot it and act as a network security device. It can also be used in a virtual machine.
Features in the generated ISO include:
IPv4 support (of course!)
IPv6 support
tunneled IPv6 access for entire network to the Internet – this requires a free account with go6.net (also known as Gateway6 or Freenet6) tunnel broker
iptables and ip6tables firewalls
SSH server for full command-line access
DNS Cache
DHCP server
tcpdump & other networking utilities
Perl and Python scripting languages
Nano text editor
Ntp client
DSL support
Unnecessary programs removed from generated ISO, resulting in small size (about 76 MB).
Low hardware requirements: Pentium computer with CD-ROM capable of booting, and two network interface cards. No hard disk, monitor, or keyboard required (though a monitor and keyboard might be useful for troubleshooting configurations at first, and then as needed).
The virtual appliance can be updated just like a normal Gentoo system, allowing new images to be generated with security and other bug fixes, additional features, and updated configurations. It's your responsibility to update both the base appliance and the build environment as often as important changes are released.
It's important to keep in mind that I myself wrote none of the software in this virtual machine, save a few scripts and configuration files, and have no wish to take credit for the efforts of thousands of 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 community (and occasionally providing additions or corrections), and writing scripts to automate certain tasks (again, based on the instructions of others, plus my own experience) . If you have questions or problems related to any specific software in this virtual appliance, you should look for answers in these places, in order:
Man page, website, or other instructions of the related software. This is where the most detailed information is usually found. Google or another search engine can help you locate information on specific issues as needed.
Gentoo documentation
The Gentoo Installation Docs (http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?full=1 has it all in one page, for easy reading & searching). A stripped-down version is at http://www.gentoo.org/doc/en/gentoo-x86-quickinstall.xml. These two documents were used extensively in the creation of Fireball, and should be consulted for basic questions on configuring the operating system aspects of both the Fireball base environment and build environment.
The HOWTO Build a LiveCD from scratch (http://www.gentoo-wiki.info/HOWTO_build_a_LiveCD_from_scratch) provided most of the details to create the Fireball build environment inside the virtual machine, as well as actually getting it compiled into a bootable ISO image. Consult this if you're trying to make changes to the build environment itself, or want details on how the ISO is generated.
Me (Indy), for the build scripts and issues related to the Fireball virtual appliance as a whole - indy@seerofsouls.com. Please remember that I'm doing this for free (unless you hire me for specific tasks :-), and that I'm doing this in my spare time (yes, I have a job and family, which take up much of my time, as they should). You will likely get a response eventually, but it may not be very quick. A polite, complete and focused description of your question will definitely speed things up. Please exhaust the first two options before taking this route.
If you have security issues related to the fundamental design and/or implementation of Fireball as a whole, please send them to me, with FIREBALL SECURITY marked in the subject line somewhere. The security issues you report to me should be fundamental flaws with the underlying design or implementation of Fireball without any changes (in other words, it should be a problem with the unmodified virtual appliance). I will do what I can to address the issue, and may release updates if warranted. In any case, you are ultimately responsible for the security of your network. 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 how you have configured it (like setting up poor firewall rules, installing potentially vulnerable services, and so on).
Suggestions for new features are always welcome. I would especially be interested in how you use Fireball in your network, and how you modify it.
Feel free to contact me at indy@seerofsouls.com.
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 root, with the password "fireball" (without quotes). You are now in the "base environment", which is a basic Gentoo installation that holds the Fireball build environment (which contains the collection of files that eventually become the bootable ISO of your Fireball system).
Set the IP address (or change it to DHCP, if desired)
ifconfig eth0 <IP address desired>
Now edit the /etc/conf.d/net file with the same IP address, and make sure the route lists your default gateway correctly; this will save your configured address.
nano /etc/conf.d/net
The SSH server should start automatically, 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.
You may like to change the existing update and/or rsync servers, perhaps to ones closer to your geographical location.
For the Gentoo update server, run this:
mirrorselect -i -o >> /etc/make.conf
For the Gentoo rsync server, run this:
mirrorselect -i -r -o >> /etc/make.conf
Now edit the /etc/make.conf, check the lines added at the end, and remove any SYNC or GENTOO_MIRROR lines above these.
nano /etc/make.conf
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.
Optional: if you like, copy the same update and rsync servers into the build environment
grep SYNC /etc/make.conf >> /root/livecd/source/etc/make.conf grep GENTOO_MIRROR /etc/make.conf >> /root/livecd/source/etc/make.conf
Then edit the file to remove duplicate SYNC or GENTOO_MIRROR lines if needed
nano /root/livecd/source/etc/make.conf
End of Optional section
To avoid generating too much traffic with the public sync servers, please make sure you don't sync more than once a day. This will help ensure that these free servers remain available to you and everyone else.
As needed, you should update the base environment with new software versions, fixes, etc., like any other Gentoo system:
emerge –rsync # not needed if already run earlier that day in the build environment emerge -a --update world
Make sure when you update configuration files (like with "etc-update" or other means) that you don't accidentally overwrite the important configurations you need for your system to function. Regular backups (and VMWare snapshots) are important, so you can easily restore from unexpected problems.
You probably don't need to change much else in the initial Fireball environment, but will be doing most of your work inside the path that holds the files that will become the generated Fireball bootable ISO (what we'll call the "build environment"). To do most work in this path, you'll need to chroot into it. Simply run this command:
/root/setup_chroot.sh
and you'll be working inside the /root/livecd/source dir as if you had booted into a Gentoo machine with that path as the root directory.
Note: when you're done working in the build environment, exit the chroot by running the following commands:
exit /root/run_after_exiting_chroot.sh
This will restore the previous environment; if it's not restored properly, problems will occur.
(Note: for quick changes to specific files in the build environment, you can access the files without chrooting first by finding them in /root/livecd/source/<whatever path> - 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 setup_chroot script.
Configure your IP address for the build environment (of course, this won't be active until you actually generate the ISO and boot it up). Use the /etc/conf.d/net.example file as a reference.
nano /etc/conf.d/net
Set the host name & domain name - replace "fireball" with the name of your server:
sed -i -e 's/127\.0\.0\.1.*/127.0.0.1 fireball localhost/' /etc/hosts sed -i -e 's/HOSTNAME.*/HOSTNAME="fireball"/' /etc/conf.d/hostname
Generate new keys for your SSH server:
/usr/bin/ssh-keygen -t rsa1 -b 1024 -f /etc/ssh/ssh_host_key -N '' /usr/bin/ssh-keygen -d -f /etc/ssh/ssh_host_dsa_key -N '' /usr/bin/ssh-keygen -t rsa -f /etc/ssh/ssh_host_rsa_key -N ''
Run this command to set the root password in the build environment:
passwd
Note: make sure you record this in a safe place. 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).
If desired, edit /etc/resolv.conf and replace the existing OpenDNS IP addresses with other server IPs (like, for example, the DNS servers of your ISP or whatever you prefer). If you choose to use the OpenDNS ones, you might wish to see http://www.opendns.com for information on additional features that may be useful.
Note: the DNS servers in this file might be replaced automatically with your ISP's DNS servers, depending on how you're assigned an IP address when your Fireball ISO boots up. Remove "usepeerdns" from the /etc/conf.d/net file if you want to prevent this.
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.
-Edit /etc/dnsmasq.conf file. If you want to run DHCP to to IP addresses to machines on your internal network, uncomment and edit one of the lines with "dhcp-range", and put in the address range that you'd like to use.
--If there are machines which you'd like to always have the same addresses given to them, you can add a "dhcp-host" line for them. Look at the existing examples in the file to see several ways you can do this.
--If you'd like to specify an NTP server for the machines in your network (whether a local or remote one), you can do it in this file as well. Look for "NTP" to find several examples of how to do this.
-You can edit /etc/hosts and add any machines in your local network that you'd like the DNS server to resolve.
I set my timezone to my local one, but others may wish to use UTC; it's up to you.
ls /usr/share/zoneinfo
This uses CST6CDT as an example; replace with your desired timezone:
cp /usr/share/zoneinfo/CST6CDT /etc/localtime sed -i -e 's/export TZ.*/export TZ="CST6CDT"/' /etc/profile sed -i -e 's/TIMEZONE.*/TIMEZONE="CST6CDT"/' /etc/conf.d/clock
Just a reminder to set these up, as you did for the base environment above. It's important to remember that the base environment and build environment share the same /usr/portage/* directories – if you sync in one, the other will not need sync again that day.
You can use the default Gentoo NTP servers, or edit these files and add your own:
nano /etc/conf.d/ntp-client nano /etc/ntp.conf
There is an hourly cronjob (in /etc/cron.hourly/update_time) that will run ntpdate and update the server time using the server(s) listed in /etc/ntp.conf. Of course, if you feel comfortable in running ntpd on your firewall server, feel free to use it instead; the clock will be slightly more accurate (usually only tenths or hundredths of a second, if not less).
Fireball assumes that you use DSL for your Internet network connection. You will need to add your username and password to allow connection when the Fireball ISO boots up.
nano /etc/conf.d/net
If you don't use DSL, you'll need to configure your Internet connection appropriately. The Gentoo documentation links mentioned above should help you as needed.
Edit the firewall config files and rule files to customize your firewall rules for both IPv4 and IPv6.
For IPv4:
nano /etc/conf.d/iptables nano /etc/init.d/iptables
For IPv6:
nano /etc/conf.d/ip6tables nano /etc/init.d/ip6tables
To clear and reload the firewall rules, run "/etc/init.d/iptables restart" and/or "/etc/init.d/ip6tables restart" as needed.
You should be able to use the virtual appliance on any hardware, thanks to the VMWare hardware emulation. For the Fireball ISO, howwever, you may need to recompile the Linux kernel to build support for your network interface cards or other devices for the physical hardware that will run it. Follow the instructions in the Gentoo documentation pages. The kernel configs 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 a modified kernel.
After building a new kernel inside build environment, and copying it to the boot directory, you'll need to build a new initrd and rename it as appropriate so it is used by grub
genkernel initrd
Note: if you've cleaned var/cache, you might get an error after the genkernel line above, regarding busybox and/or genkernel source code being missing. To solve this, just re-emerge them:
emerge -a busybox genkernel
As needed, you should update the build environment with new software versions, fixes, etc., like any other Gentoo system:
emerge –rsync # not needed if run today in the base environment emerge -a --update world
Make sure when you update configuration files (like with "etc-update" or 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 restore from unexpected problems.
IPv6 support is already built into the kernel, so you can use this with the autoconfigured local address to access Fireball without any additional configuration. If you'd like to provide globally-routeable IPv6 addresses to your network, in order to reach the growing number of IPv6 services on the Internet, you can get an account at one of the free tunnel brokers.
These tunnel brokers provide a tunnel from the machine running the Fireball ISO to the broker's servers, through your normal Internet connection, which allow you to reach the Internet using IPv6 as well as IPv4. Gateway6 (go6, or called Freenet in Gentoo until recently) is already installed, so if you'd like to use it, get an free account at go6.net and edit the config file:
nano /etc/gateway6/gw6c.conf
Add your userid and password
Make sure the host_type is set to "router"
Set if_prefix to the network interface that is facing your internal network Mine is eth0, but yours may be different.
You might need to change the tunnel_mode to v6anyv4 or perhaps some other option
You can change the log options if desired. It's good to turn on maximum logging (3) while you're figuring things out, but once things are working fine, it's better to set it to minimal logging (1).
If you want the Gateway6 IPv6 functionality to start automatically, run the following command:
rc-update add gw6c default
Note: in theory this should work; however, my DSL connection takes a little while to come up, and since the gw6c runs before the Internet connection is working, the tunnel fails. I just rely on the cron job below to start the tunnel a few minutes after boot.
If you like, you can start the tunnel when desired:
/etc/init.d/gw6c start # use "restart" or "stop" to restart or stop the server
While this is running, other IPv6-enabled computers in the network will automatically be given public IPv6 addresses with which they can communicate to the Internet through the tunnel. Of course, they will also be able to use whatever IPv4 connections they have as well.
Note: The Gateway6 tunnel isn't entirely stable, and may go down at times. If you want the service to be monitored and restarted automatically, you can , add a cronjob to do this automatically.
To load the current crontab for root into the default editor for modification, run the command:
crontab -e -u root
and copy/paste something like the following line into the editor, then save it:
0,5,10,15,20,25,30,35,40,45,50,55 * * * * /bin/pidof gw6c >/dev/null 2>&1 || /usr/local/bin/restart_gw6c.sh
As written, this will check every 5 minutes to see if the gw6c process is running, and start it if needed. Of course, you can change the interval as desired.
Note: if you use the Gateway6 tunnel broker, the network device carrying the IPv6 traffic in and out of your network will depend on the tunnel configuration; for my setup, I use the v6udpv4 tunnel, so my device is called “tun”. Your ip6tables rules should use that device for any required filtering on that interface.
Since the Fireball ISO will turn the host on which it runs into a security device, you should remove things that you don't need in order to reduce the potential threats to your network.
You can remove anything that you don't think you'll be using with:
emerge --unmerge <whatever package>
You will be warned if the removal of a package will affect other packages.
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. However, since this is intended to be used as a security device, 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.sh
The clean.sh script generates a list of 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.
Then leave the build environment chroot and restore the base environment
exit ./run_after_exiting_chroot.sh
Now build the Fireball ISO
./build_cd.sh
A simple overview of this build process: the files from /root/livecd/source are copied to /root/livecd/target, excluding many unnecessary directories and files to speed things up. More aggressive file removals are done inside /root/livecd/target, and the ISO is then generated from files in that directory hierarchy. Note: by copying files from the source directory to the target directory, it allows more extensive file removals to occur there, while preserving the ability to restore files from the source directory if problems occur.
The build process may take 10 minutes or longer, depending on the speed of your computer, with more time needed if it's the first time you've built one in this appliance (or if you've recently cleared the /root/livecd/target directory). The generated ISO will be placed in /root/livecd/livecd.iso, ready for copying and burning.
You may wish to test a version of the ISO before burning it to a CD. If so, the ISO can be booted in a new VMWare virtual machine easily. Some obvious things may not work (like PPP/DSL setup), but it should give you a good idea about whether most things work as you'd like. As with any host, you should give this test version a different IP address than anything else on your network, so that you don't confuse machines on your network with duplicate IP addresses.
You can make modifications to configurations inside this test machine, and see how things work (though you'll be unable to compile anything here, since all compilers are removed). Of course, whatever changes you make aren't transferred to the Fireball appliance until you also apply the changes there.
If you want to make copies of the entire virtual appliance, either for backups (definitely recommended!) or to give to someone else, here's some ways to reduce its size and allow it to compress even smaller:
Delete the contents of 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/*
You can delete the cached temp files here
rm -rf /root/livecd/source/var/cache/*
If you want to save the most space, you can clear the cache of the base environment too. While I haven't had any issues with this, this is in a currently running system, so there's a risk it might cause some slight problems.
rm -rf /var/cache/* # Optional; perhaps some risk here
Fill the unallocated parts of the filesystem with zeros, to allow better compressionl; it will take a while, depending on the size of the virtual disk and the free space remaining. It's normal to see an error once the filesystem is full, but it will be emptied again.
cat /dev/zero > zeros.bin; sync; sleep 1; sync; rm -f zeros.bin
When you're ready, shut down the virtual machine
shutdown -h now
Exit whatever VMWare program you use, to remove the *.lock files.
Delete the *.log files inside the directory containing the virtual appliance - these aren't needed
You may use whatever compression program you like to compress the virtual appliance directory, but I suggest the 7zip (http://www.7-zip.org) compression format. In my experience and that of others, this seems to be the best compression choice for a virtual machine. Zip & gzip formats are more widespread, but usually generate much larger archives.
Look around on the web for more tips. Feel free to pass on to me any useful tips you find.
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 the Fireball system), good passwords, network and host intrusion detection & prevention systems, network and host firewalls, virus scanners, anti-spyware programs, user training, policy auditing, and so on.
You should update the Fireball system regularly. 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. (Of course, updating or otherwise modifying the system runs the risk of introducing new bugs or problems, so you should make backups before introducing significant changes, and test changes to make sure they work as desired.)
Read system logs for signs of system problems or attacks. 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 firewalls: iptables (for IPv4) and ip6tables (for IPv6). Each has its own set of rules, which may need to change over time.
You're encouraged to test ISOs in a virtual machine as noted above. This may save many CDs. Refer to the documentation links or Google to find answers to questions you may have.
If you make a copy of the virtual machine and change the ID, you will find that the virtual network interface card (NIC) will change (for example, from eth0 to eth1, etc.) If you want the NIC to still be eth0, you can either delete the /etc/udev/rules.d/70-persistent-net.rules file, or edit it and put the current MAC for the existing NIC in a line describing eth0, then reboot.
The easiest method is to delete the entire file:
rm /etc/udev/rules.d/70-persistent-net.rules
Then reboot the virtual machine:
shutdown -r now
"Gentoo" is a trademark of Gentoo Foundation, Inc.
The programs used in Fireball are governed by their applicable licenses.
This document is based in part on http://www.gentoo.org/doc/en/gentoo-x86-quickinstall.xml, and is also licensed under Creative Commons: http://creativecommons.org/licenses/by-sa/2.5.
The IPv6 firewall rules for ICMPv6 traffic is partially-based on http://tools.ietf.org/html/rfc4890.