The purpose of this section is to explain in detail how to do your initial setup of a newly installed Honeywall CDROM. Please submit all bugs/corrections for this documentation or the Honeywall CDROM to our Bugzilla Server.

Last Modified: 16 August, 2005

5. Initial Setup

1. Overview
2. honeywall.conf Configuration File
3. Dialog Menu
4. SSL and SSH Fingerprint
5. OS Configurations

5.1 Overview
Once you are done installing the Honeywall CDROM and it reboots, you will have on your hard drive a fully functionaly Fedora Core 3 operating system with Honeywall functionality. This operating system has been minimized and hardened. It consists of 233 RPMs, including those developed by us for Honeywall functionality. After the initial reboot the system is automatically hardened by running the script /usr/local/bin/lockdown-hw.sh. This script is based on the Center for Internet Security (CIS) and National Institute of Standards and Technology (NIST). However, the Honeywall CDROM uses the default Fedora kernel, which has no kernel based security features enabled. Following installation, you may want to consider building your own kernel with security features, such as grsecurity.

Upon rebooting, you will find yourself at a terminal mode login prompt. Remember, this is a minimized system, so there is no local windowing support (you can install windowing support after the install if you want, or use Section 8: Customization, however the base does not include windowing.) From this login prompt, you need to begin the initial setup process of the Honeywall. The purpose of this process is to assign values to all the variables that the Honeywall and OS will need to properly function. You have two options for your initial setup of the Honeywall Roo.

1. Manually create a honeywall.conf configuration file and have the Honeywall read it during the installation phase, or install the configuration file to the system after the installation is complete.

2. Use the Dialog Menu interface. This is the more common method of an initial s etup, and is the same style interface as on the previous Honeywall Eeyore. It is used when you are at the system console, or have remote terminal access (such as through SSH).

The Honeywall comes with two default system accounts, roo (user ID 501) and root (user ID 0). Both share the same default password honey, which you will want to change right away. You cannot login as root, so you will have to login as roo then 'su -' to root. The Honeywall supports virtual terminals on the console, which can be accessed using the combination of the ALT key and one of the F1-F9 keys. The very first time you login as root into an un-configured system, you will be put into the Dialog Menu and a reminder saying you need to configure your system.

5.2 honeywall.conf Configuration File
The honeywall.conf configuration file is a ASCII text file that contains all the values for the variables the OS and Honeywall will be using. The Honeywall CDROM comes with a default honeywall.conf configuration file. If you want to configure your system, you will have to use your own /etc/honeywall.conf file. Its VERY IMPORTANT to understand that the Honeywall does not directly use the /etc/honeywall.conf file for its runtime configuration. That is done with variables that are maintained as files in the /hw/conf configuration directory. You do an initial setup by copying to your new Honeywall the /etc/honeywall.conf file, then using that file to populate /hw/conf. Sounds complicated, but its really easy to do.

You do this with the tool /usr/local/bin/hwctl. You copy your preconfigured honeywall.conf file to /etc/honeywall.conf on the Honeywall (using media such as a floppy or USB device), then use the following command update the /hw/conf directory and start the Honeywall services all in one step.

/usr/local/bin/hwctl -s -p /etc/honeywall.conf

Thats it! After this, the Honeywall will be fully configured, according to your settings. You can avoid the dialog interface entirely using this method (assuming you've set the variables properly!) and go straight to using the Walleye web interface. hwctl is documented by help output (hwctl -h). You can also learn more about how the variables work and internal functionality in Section 6: Maintaining and Section 9: Internals documentation.

5.3 Dialog Menu
The second, and more commonly used option, for configuring a newly installed Honeywall is to use go through the initial setup process via the Dialog Menu. Keep in mind, you cannot use the web admin interface to do the initial setup, as the Honeywall has no settings for remote management. When you login as root, the Dialog Menu will automatically start for you if your system has never been configured. You can also manuallyi start the Dialog Menu using the command menu. Note, only root can use the Dialog Menu, as no other user has the necessary privileges.

To setup the system using dialog, go into the Menu. You will have six choices for the primary menu. The Honeywall is configured using the "4: Honeywall Configuration" option. This menu option is modal, which means it behaves one way if the system has never been configured before (i.e., it automatically does an initial setup), and if the system has already been configured, it supports modification of individual components, or a full re-configuration. Since we are currently discussing installation, we will now discuss the initial setup mode.

After selecting option 4, you will be presented with three options for initial configuration.

• Floppy: In this method, the menu reads your preconfigured honeywall.conf configuration file from the local floppy and configures the system. This is similar to the initial setup process we described above, but automated the process for you.

• Defaults: This uses the default honeywall.conf configuration file that comes with the system. [Note: On first install, a copy of /etc/honeywall.conf is made to the file /etc/honeywall.conf.org. This file is the "factory defaults" file that will be mentioned later.]

• Interview: The menu will ask you a series of questions to obtain the information it needs, then configures the system based on that information. We recommend you have that information ready ahead of time. Refer to the Initial Setup Information document to learn what will be requested of you.

After initial configuration, menu option "4: Honeywall Configuration" will present you with separate options for each major configuration category (e.g., IP address information, remote management information, connection rate limiting, etc.) This menu allows you to manage the functioning of the Honeywall as you use it. Changes you make will take effect after they are applied to the configuration variables, and a backup of the /etc/honeywall.conf file will be made with a numeric extension (e.g., .0, then .1, etc., up to .9). This will allow you to recover from errors, or return to a previous state. [Note: features for recovering from errors are not yet implemented in the dialog or Walleye user interface, but you can always use the command line and hwctl -r -p as described elsewhere in this manual.]

At the bottom of the menu option you will find "13: Reconfigure System". This provides you with the same methods as the initial setup, allowing you to reset the honeywall from a honeywall.conf file floppy, from the /etc/honeywall.conf.orig "Factory defaults" file, or by going through the interview process again. [WARNING!!! Be VERY CAREFUL if you are doing this when logged in remotely, you MAY BE prevented from accessing the Honeywall remotely anymore!]

5.4 SSL SSH Fingerprint
Unless you have customized your own ISO and/or pre-loaded SSH keys using the floppy customization method, the initial installation will generate new SSH keys and an SSL certificate. These are required for encrypted communications using SSH and SSL. Before connecting to the Honeywall remotely, it is highly recommened that you prepare to confirm the fingerprints of these keys/cert. (Simply accepting new keys on first connection opens you up to a "man-in-the-middle" attack.) This is done from the command line as

For SSL: /usr/bin/openssl x509 -noout -fingerprint -text < /etc/walleye/server.crt
For SSH: /usr/bin/ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key

If you want to generate your own self-signed certificate manually, for SSL follow the instructions at Generating Your Own SSL Certificate. For SSH, you will want to use the command ssh-keygen.

5.5 OS Configurations
Once the Honeywall has been configured, there are several optional applications you will have to configure and enable from the command line.

• Configuring Tripwire
• Configuring International Keyboard
• Configuring Local Time