The purpose of this section is to explain how to administer and maintain you Honeywall once it is configured and deployed. Please submit all bugs/corrections for this documentation or the Honeywall CDROM to our Bugzilla Server.

Last Modified: 25 May, 2007

6. Maintaining

1. Overview
2. Dialog Menu
3. Web Interface
4. hwctl Utility
5. Operating System
6. Updates
7. Snort and Snort-Inline Rules Update

6.1 Overview
Once you have your Honeywall installed, configured and deployed, now what? How do you maintain the system, how do you keep it updated, how do you modify configurations? We will cover three different options for administering your Honeywall; hwctl, the Dialog Menu and Web Interface, We will then finish with updates, how you automate keeping the OS and Honeywall functionality current.

Before we can begin with administration, you need to quickly understand how the system saves and uses the information you give it. All of the values you give the system (IP addresses, email addreses, etc) are stored as variables in a special configuration directory in /hw/conf. Each value is stored in its own unique filename, similar to how /proc file systeme works on many Unix systems. For example, the file /hw/conf/HwTCPRATE contains the value for the limit of how many outbound TCP connections are allowed. There are currently over 50 files (unique variables) stored in this location. The system scripts and Honeywall functionality use these to determine its behavior. Whenever you use one of the utilities below to configure or modify the system, you are changing the values stored in the variables. Modifying variables in the honeywall.conf will not change the state of the variables on the system. Instead, use one of the three interfaces we provide, as they include a variety of internal checks.

Now, trying to archive or transport these values can be a pain in the butt. So, in addition, we created the configuration file /etc/honeywall.conf. This is a simple ASCII text file that takes all the variables and their values from /hw/conf, and stores them in a single file. This file is NOT used by the system. Instead, this is a simple way for you to store the system configuration (such as to a floppy) or transport to another system (such as over scp). This file is updated automatically everytime a variable is updated. For more information on how variables are stored and used, please refer to Section 9: Internals.

6.2 Dialog Menu
The Dialog Menu is the classic interface for administering the Honeywall CDROM. It was originally used in the Eeyore version. The new version is very similar, except it has new features added (and is blue instead of red). While this interface has the advantage of working locally on the system, it has the disadvantage of not being very user friendly.

To start the menu, execute the command menu. (It is in the PATH, but if you need to know, its location is /usr/sbin/menu.) You can have multiple instances of menu running at the same time, but it is not advised to have multiple instances of menu since there is no locking of variables and some scripts may not be in sync with changes made in another menu. The same is true for the Walleye admin interface

The menu is pretty self explanatory. Whenever you highlight an option, you will see a description of that option in the lower-left hand corner. To find out what all the different options are, refer to the Dialog Menu document. To learn how the Dialog Menu works and the commands it executes, refer to Section 9: Internals section. The one key point to remember is that changes in the Dialog Menu do NOT take effect until after you "Return to previous menu". The reason for this is the Dialog Menu is collecting all changes within a sub menu and then takes appropriate action when you "Return to previous menu". To take appropriate action on each and every change would likely get frustrating with all of the stopping and starting of services between each option.

6.3 Web Interface
The Web Interface is the new and improved (at least we hope :) interface to administering the Honeywall. It allows you to remotely point and click the day to day administration of your system. This system is designed to be the primary method for remote administration. The web interface has all the functionality of the Dialog Menu and more. Not only can it be used for administration, but for full system data analysis. As such, we have given it the sexy name Walleye (either for "Eye on the Honeywall", or in tribute to the late Douglas Adams: So long, and thanks for the fish.) From this point on, any reference to Walleye means the web based user interface that is used for Honeywall administration, configuration, and data analysis. This is not enabled by default, unless you use the automatic configuration features. Most users will have to enable it from the Dialog Menu.

To enable Walleye, go to your Dialog Menu and select option "4: Honeywall Configuration", then "2: Remote Management", then "12: Walleye". From here you will enable the Walleye functionality, including Argus and the web server, which will listen on port 443 (HTTPS using SSL). Before connecting to the Wallye interface for the first time, you will need to get the SSL certificate. This is used to confirm the identity of Walleye webserver the first time you access it with your browser.

Make sure that during your initial setup process you allowed inbound management connections to port 443 on the management interface and from the IP address of your management system(s). Once Walleye is up and running, you can connect to it using your browser (we currently test and support either Firefox or IE). Also, ensure cookies and JavaScript are both enabled (we know, we prefer not to use these either, but we figure if you can't trust the webserver, you probably should not be using the Honeywall CDROM: Create a profile just for the Walleye, to be safe. :). The URL to Walleye should look like

https://ip-address-mgmt-interface

You will get a login screen. Just like the operating system, the default user account for Walleye is the user roo with the default password honey. Upon your first login you will be requested to change the password. Note, Walleye comes with a password checking mechanism to enforce good passwords (its pretty strict). Be sure to have a good password ready before you login for the first time. It requires

• 8 or more characters
• One character must be a capital letter
• One character must be a number
• One character must be a symbol

Once you have set the password, be advised the user interface has a lockout feature. After 3 failed login attempts, that user will be blocked for 15 minutes. After 15 minutes have expired, you will be able to login again. If you have SSH access to the honeywall see the FAQ for steps to manually reset the password and clear the lock.

Once you are successfully logged in, you can begin to adminster the system. First, you will want to select "System Admin" from the GUI. This will take you to a window that has very similar options to the Dialog Menu, but is web based. There are several difference between the Dialog Menu and the Walleye. The first is Walleye does not have the ability go through the initial setup, it cannot take you through the interview process and reconfigure your system. You have to use the Dialog Menu to do that. The second difference between the two is the addition of the "Manage Users" option. This allows you to add, modify, or delete users that can have access to "Walleye". Users can be assigned one of three roles.

• User: Has read access to only the data analysis section.
• Admin Read-Only: Has read access to the data analysis and status sections.
• Admin: Has read and write access to everything.

6.4 hwctl Utility
/usr/local/bin/hwctl (which stands for "HoneywallControl") is a command line utility that allows you to change the values of Honeywall variables, updates and backs up /etc/honeywall.conf. In addition, when a variable is changed it gives you the option to automatically restart only those services that are affected by the variables changed. It is the only supported method of interacting with the Honeywall from the command line, and provides the interface for remote administration and management of your Honeywall. In addition, both the Dialog Menu and the Walleye interface call on the utility hwctl whenever they need to make a change to any variable or restart any service. Advanced users will most likely want to know about the command line interface, as well as the programming API methodology, to customize and enhance the Honeywall. If you know what variable you want to change, there is no need to go through the extra motions (mouse or keystrokes) of traversing menu interfaces just to set a single variable and make it take effect. This is where the command line interface, hwctl, comes in most handy. You can learn more about hwctl with its help command hwctl -h or reading the Section 9: Internals Section.

Here are some examples. First, there is a variable named HwTCPRATE (stored as the file /hw/conf/HwTCPRATE) which holds the value for how many outbound TCP connections the system will allow before restricting anymore connections. You can see the value of this variable using hwctl like this:

# hwctl HwTCPRATE
HwTCPRATE = 20

You can change the value of HwTCPRATE to 30 using this command:

# hwctl HwTCPRATE="30"

You can change the limits for TCP outbound connections and have those changes take effect immediately with the '-r' option.

hwctl -r HwTCPRATE="30"

You can have the system check to see if any variables have been changed, and if they have been changed, automatically start any services. If no variables have been changed, report as such.

hwctl -r

You can see all variables currently being used with the -A flag, as shown here:

# hwctl -A
HwUDPRATE=20
HwTCPRATE=20
HwFWBLACK=/etc/blacklist.txt
HwMANAGE_NETMASK=255.255.255.0
HwWALLEYE=yes
HwSEBEK=yes
HwSEBEK_LOG=yes
HwLAN_BCAST_ADDRESS=10.0.0.255
. . .

[Note: Using -a does not put spaces around the equals signs, which is the same format as the /etc/honeywall.conf file. If you wish to parse the output easier with programs like awk, you can use the -a option and output will look more like the earlier example showing just HwTCPRATE.]

6.5 Operating System
Managing the operating system should be similar to any Fedora Core installation. However, there are some minor differences due to the modifications we have made for honeywall functionality. The biggest difference can probably be found in the startup scripts. A variety of scripts have been added. These scripts replace some of the existing startup scripts, so they should no longer be used. The reason the non-used startup scripts are still on the system is they are part of the RPM packages. The scripts that are modified for use on the CDROM are:

For MYsql, use '/etc/init.d/hflow-mysqld', do not use '/etc/init.d/mysqld'
For Apache, use '/etc/init.d/walleye-httpd', do not use '/etc/init.d/httpd'

6.6 Updates
To keep your honeywall current, you use the tool yum(8). This tool can be used to query a remote server for updated RPM's, and if found download and install them, ensuring your systeme is up to date in a fully automated manner. yum can be manually run from the command line, or automated to run daily from cron. You can find all yum configuration files at

/etc/yum.repos.d/*

The following yum repos are configured on roo as of roo-1.2.hw-1 and are in the indicated "state" by default:

     Repo            State            Description        Notes
 =================================================================
  honeynet          Enabled     Honeynet Verified Update Repo [2]
  honeynet-test     Disabled    Honeynet Test Repo            [3]
  fedora-core       Disabled    Upstream Base OS Repo         [1]
  fedora-extras     Disabled    Upstream Extras Repo          [1]
  fedora-updates    Disabled    Upstream Updates Repo         [1]
 =================================================================

1. These repos are used by Honeynet Project developers to acquire updates the the underlying roo OS. The updates are tested/verified then placed in repo 'honeynet' for roo users to download. There is no need to enable these as you are already getting them from the Honeynet site by default. However, we provide the option if you prefer to get them from their original source.
2. This repo is the only one enabled by default. It is where verified updates and new featuers are added for download by roo users. This allows us to test all new updated RPM's before they are installed on the Honeywall.
3. This is where new updates and new features are placed for testing. You can enable this repo if you are brave and want to test new updates or features. If you feel the urge and find bugs, please enter a Bugzilla Report. Be warned that components in the repo have not been fully tested!
4. This is where new "add-on" tools will be placed in the future. This repo is not yet active. An announcement will be made with more details when it is activated.

To make it as easy as possible for you to enable/disable the yum repositories you want, we have added a tool called 'hwrepoconf'. Here is the usage (appears when no args given):

 hwrepoconf: Quick hack to manipulate enable-ness of repo configs

 Usage: hwrepoconf 

 No               Reports usage
 --enable-all             Enables all repos
 --disable-all            Disables all repos
 --enable repo1 repo2...  Enables listed repos
 --disable repo1 repo2..  Disables listed repos
 --defaults               Sets things back to default values
                           (All disabled except "honeynet")
 --show                   Show current settings
                           (enabled=1: Enabled)
                           (enabled=0: Disabled)

 Note: Repo filenames w/ or w/o trailing ".repo" (Not actual repo IDs)

Repo config files are in the standard yum location: /etc/yum.repos.d/ You will note that some of the repos have "includepkgs" or "excludepkgs" directives. These are in place to prevent accidental downloading of conflicting packages. Alter these commands at your own risk.

Examples
Below are examples of the most commom commands you may have to execute. You can also learn more about yum at Yum HOWTO.

• Update roo from default install (roo-1.1.hw-1 and newer) from verified Honeynet repo: 'yum update
• Try out new updates or features currently being tested by Honeynet developers:
  A. One time
  yum --enablerepo=honeynet-test update
  yum --enablerepo=honeynet-test install
  B. Permanent
  hwrepoconf --enable honeynet-test
  yum updatebr> yum install
  
• Display repo "enableness:
  hwrepoconf --show
  
• Return repo "enableness" back to Honeynet defaults
  hwrepoconf --defaults
  

By default, yum is not enabled to happen automatically every day. To enable this feature, you will want to use the chkconfig command. This will ensure yum will update your system every day at 0402 hours(default). Execute the following as root:

chkconfig yum on
/etc/init.d/yum start

This will continue every day, including after reboots, until you:

chkconfig yum off
/etc/init.d/yum stop

For security purposes, ALL RPMs are signed with the Honeynet Project RPM-GPG-KEY. If you decide to install or update RPMs from yum repos other than Honeynet Project repos, you will be prompted to "Confirm" download/install of a public RPM GPG signing key for the repo you are receiving files from. Once you have confirmed the key, just hit "y" to continue.

6.7 Snort and Snort-Inline Rules Update
One of the biggest changes since version 1.0 has been how we handle and maintain Snort and Snort-Inline rulesets. In the previous version we had a complex mechansim for manually editing and configuring rulesets, indviduals rules, and configurations. This proved too complex and timeconsuming. In version 1.1 we introduced a streamlined version that is simpler to use and configure. In addition, the CDROM is now distributed with the latest VRT ruleset.

The Walleye user interface has a new Snort & Snort-Inline Rules section. This will allow you to configure automatic updates of both rule sets using Oinkmaster. As part of this setup, you will need your own Oinkmaster code, which you can get from the Snort Subscription Page. Once this is configured, the honeywall will automatically download and install the new VRT Rulesets as well as convert the new rules for use with Snort-Inline. For details on how this works, and how to make manual modifications, refer to Snort-Rules details. To make any detailed modificationsn to the configuration files or individual rules, you must do so at the command line. All Snort and Snort-Inline configuration files and rulesets can be found in their default locations.