InJoy Firewall for Linux. Platform specific configuration and installation README. ========================================================================== C O N T E N T S ========================================================================== 1.0 Prerequisites 2.0 Installation issues 3.0 System Implications 4.0 User Experience Issues 5.0 Manual Installation 6.0 Manual Deinstallation 7.0 Trouble Shooting 8.0 Bridged Mode ============================================================================== 1. P R E R E Q U I S I T E S ============================================================================== You are about to install a product that adds a new device driver to your Linux system. The device driver layers with existing device drivers and incompatibility or bugs in these drivers CAN potentially cause hazard to your Linux system. If you are NOT experienced in the following areas: * TCP/IP networking and routing * Linux recovery options (i.e. recovery disk or single user mode) THEN please backup critical data before installing this software and/or consult a local expert or seek help on the Internet. F/X Communications will in no way be held responsible for malfunctions or data loss inflicted by our software. 1.1 Supported Software ---------------------- InJoy will run on any of the below Linux platforms: * Red Hat Linux 9.0 - see additional notes below * Red Hat Linux 8.0, 7.3, 7.2 * Red Hat Enterprise Linux 3.x, 4.x, 5.x * Fedora Core 1 to 6 * Fedora 7 * Debian Sarge * Open SuSE 10.x * Mandrake 10 * Slackware 9.1 May work on other distibutions adhering to the Linux standards base: * Red Hat Linux 7.1 * Red Hat Linux 7.0 * Red Hat Linux 6.2 * Red Hat Linux 6.1 * Debian Woody or older (currently may require manual installation / followup) * other Additional Requirements: * Linux 2.4 or 2.6 kernel * Glibc 2.1 * GTK 1.2 and Gnome (for GUI applications) 1.2 Supported Hardware ---------------------- The InJoy Firewall has been tested with a multitude of Network Adapters on Linux. Below a small list of (some of) the tested adapters: * NE2000 compatible (ne.o driver) * 3Com Fast EtherLink/EtherLink XL Family * 3Com 3C905xx (100Mb PCI Adapter) * 3Com Etherlink III 16BIT-ISA * RTL8029 / RTL8129 / RTL8139 PCI Ethernet Adapter * IBM Etherjet 100 * D-Link DL2000-based Gigabit Ethernet Adapter * Intel PRO/1000 82544GC Gigabit Ethernet Controller * Intel PRO/1000 82540EM Gigabit Ethernet Controller * nVidia Corporation nForce2 Ethernet Controller * Many more... If you use PCMCIA network adapters, be sure to check the trouble-shooting section. If you have one of the following (1Gbit) network cards, you must use a 2.4.20+ kernel version (preferably the latest 2.4 kernel). e1000.o: Controller Adapter Name Board IDs ---------- ------------ --------- 82542 PRO/1000 Gigabit Server Adapter 700262-xxx, 717037-xxx 82543 PRO/1000 F Server Adapter 738640-xxx, A38888-xxx 82543 PRO/1000 T Server Adapter A19845-xxx, A33948-xxx 82544 PRO/1000 XT Server Adapter A51580-xxx 82544 PRO/1000 XF Server Adapter A50484-xxx 82544 PRO/1000 T Desktop Adapter A62947-xxx 82540 PRO/1000 MT Desktop Adapter A78408-xxx 82541 C91016-xxx 82545 PRO/1000 MT Server Adapter A92165-xxx 82546 PRO/1000 MT Dual Port Server Adapter A92111-xxx 82545 PRO/1000 MF Server Adapter A91622-xxx 82545 PRO/1000 MF Server Adapter(LX) A91624-xxx 82546 PRO/1000 MF Dual Port Server Adapter A91620-xxx The following network cards will not work in 2.4 kernels: * Broadcom Tigon3 * Broadcom 4400 * 3Com 3CR990 ============================================================================== 2. I N S T A L L A T I O N I S S U E S ============================================================================== 2.1 General issues ------------------ The installation script will install the required libraries in /usr/lib and install boot scripts in /etc. For this reason the installation script must be run as root. It will also create a file called /etc/fx.conf. This file should contain a space separated list of the network modules that InJoy Firewall will monitor. Many users of Red Hat (and other) Linux distributions are accustomed to using configuration programs such as netconfig or Network Configurator. Using these utilities with InJoy Firewall is perfectly acceptable. InJoy must be run as root, or have root privileges for creating routes, and accessing the /dev entries. If your Linux distribution is not using one of the supported kernels (indicated by the install script) and the install script fails to compile the driver on its own, follow the included instructions to build the InJoy driver manually. See source/build.txt for help. 2.2 Upgrade issues ------------------ When upgrading to a new version, it is recommended you run Install.sh after un-tar'ing. If you don't wish to run Install.sh, then be sure to manually copy the new libraries to /usr/lib. When creating the menu items on the Gnome Menu, old items are not destroyed. If you are upgrading from a previous install, you should either run the uninstall script or manually remove the old menu items to ensure there are no obsolete items. 2.3 Red Hat 9 additional installation issues: ---------------------------------------------------------------- Red Hat 9 now includes and uses the Native POSIX Thread Library (NPTL), which is an improved implementation of the POSIX threads for Linux. The NPTL library can cause problems (hangs) for applications that extensively use semaphores, such as the InJoy Firewall. The InJoy Firewall is tested with the new NPTL library, however not as extensively as with the older thread libraries. To completely eliminate this "concern", you can set the environment variable LD_ASSUME_KERNEL to 2.4.1, which means that the older "Linuxthreads with floating stacks" library will be used. For more information on LD_ASSUME_KERNEL, see Red Hat Linux 9 Release Notes: http://ftp.redhat.com/pub/redhat/linux/9/en/os/i386/RELEASE-NOTES To set up the environment variable, login as root, and add the following line to the end of ~/.bashrc export LD_ASSUME_KERNEL=2.4.1 This assumes that you are using the default bash shell for the Linux users. Setting environment variables in other shells may differ from this example, so check your shell's manual page or set bash as the root user's shell (you can do this by editing the /etc/passwd file). ============================================================================== 3. S Y S T E M I M P L I C A T I O N S ============================================================================== InJoy installs a device driver with hooks for talking to both other device drivers and to create dynamic PPP devices. Drivers loaded by InJoy firewall are modified on the fly to talk to the InJoy device driver directly. Boot scripts in /etc are modified to reflect these changes. ============================================================================== 4. U S E R E X P E R I E N C E I S S U E S ============================================================================== DW_BORDER_WIDTH and DW_BORDER_HEIGHT environment variables are used to control the perceived size of the windows. The default border-widths used are for the Red Hat 6.2 - 7.2 window managers default theme. ============================================================================== 5. M A N U A L I N S T A L L A T I O N ============================================================================== Manual installation is quite tricky. 1) You need to locate the fx.o object in sys/x.x.x (where x.x.x is the kernel version) for your kernel. And copy it into /lib/modules/x.x.x/kernel/drivers/net/. If your kernel is not present there, you can consult with build.txt file in source/ sub-directory of your InJoy Firewall installation about how to compile the driver manually. To find out which kernel version you are running, type: uname -r For 2.6 kernels family, driver filename extension is 'ko': fx.ko. 2) All of the libraries in the lib/ subdirectory need to be copied to /usr/lib or somewhere else that is listed in the /etc/ld.so.conf. Then /sbin/ldconfig needs to be run to recognise the newly installed libraries. 3) Then the boot scripts must be installed: sys/fx and sys/gateway go into /etc/rc.d/init.d. sys/fx and sys/gateway must go into the runlevel which you want to boot into, typically 3, 4 or 5 under rc.d corresponding names. For example, if you are using runlevel 5 (graphical login prompt), create symlinks in /etc/rc5.d: /etc/rc5.d/S10fx -> /etc/rc.d/init.d/fx /etc/rc5.d/S90gateway -> /etc/rc.d/init.d/gateway These scripts are named so that they load the fx.o driver before the network initializes. 4) A statically linked version of objcopy needs to be placed in /bin/fx_objcopy. One is distributed as sys/fx_objcopy. Also sys/findsym must be placed in /bin. 5) Finally you must run driver patching utility for each NIC module of your system. To figure out which NIC modules are currenlty loaded, issue the following command: lsmod Then for each loaded driver, call driver patching script as follows: ./Patch-Driver.sh 2.4.7-10 dl2k where 2.4.7-10 is running kernel version and dl2k is module name. You can determine which modules are NIC ones by comparing lsmod output with what is situated in /lib/modules/x.x.x/kernel/drivers/net. If the driver is located deeper in kernel source tree, for example, in /lib/modules/x.x.x/kernel/drivers/net/e1000/e1000.o, please use the following syntax (i.e. use directory name after drivers/net): ./Patch-Driver.sh 2.4.7-10 e1000/e1000 Then all that is required is a reboot. ============================================================================== 6. M A N U A L D E I N S T A L L A T I O N ============================================================================== All that is required for deinstallation is deleting all of the files that were installed during the installation phase and restore backups of NIC modules. Here is a list of files to delete: /etc/rc.d/rc?.d/S10fx /etc/rc.d/rc?.d/S90gateway /etc/rc.d/init.d/fx /etc/rc.d/init.d/gateway /etc/fx.conf /etc/fx_forward /etc/fx_startup /bin/fx_objcopy /bin/findsym /usr/share/gnome/apps/Internet/InJoy Firewall/* /usr/lib/libfirewall.so* /usr/lib/libfxip.so* /usr/lib/libfxmasq.so* /usr/lib/libfxutil.so* /usr/lib/libipfrag.so* /usr/lib/libfxipsec.so* /usr/lib/libfxauth.so* /usr/lib/libdhcpd.so* /usr/lib/libpppoe.so* /usr/lib/libpptp.so* /usr/lib/libgenerate.so* /usr/lib/libdw.so* /usr/lib/libdwcompat.so* /usr/share/pixmaps/gateway.png /usr/share/pixmaps/gwxp.png /usr/share/pixmaps/logview.png To restore backups of NIC modules, run this script: ./Unpatch-Drivers.sh 2.4.7-10 where 2.4.7-10 is running kernel version. All drivers will be restored as a result of executing this command. ============================================================================== 7. T R O U B L E S H O O T I N G ============================================================================== Q: InJoy Firewall sees only outgoing packets or doesn't see any packets at all. A: Follow these steps to locate and fix the problem: a) Make sure the fx.o module is loaded and operational. You can do this by running the "/sbin/lsmod" command and verify "fx" presence. If not found, load it manually by running "modprobe fx". b) Ensure that kernel uses patched NIC modules by using "/sbin/lsmod" command: it must show that NIC modules use fx.o driver (example): Module Size Used by dl2k 12512 1 e1000 62608 2 fx 12672 0 [dl2k e1000] If drivers don't use the fx.o driver, it means they are not patched. In this case, proceed with item 5 of Manual Installation section. c) Make sure that /etc/modules.conf or /etc/modprobe.conf contain correct module aliases, i.e. interface names match drivers. An example of correct modules.conf (excerpt): alias eth0 e1000 alias eth1 e1000 alias eth2 dl2k d) Certain PCMCIA NIC drivers involve more than one module for operation, e.g. "orinoco.o" and "orinoco_cs.o". Ensure that both are used by fx.o driver. ============================================================================== 8. B R I D G E D M O D E ============================================================================== It's possible to perform such installation of InJoy Firewall that it will not require reboot and will allow to unload F/X intermediate driver at first need. This type of installation involves creating a network bridge that will include only one interface - on which InJoy will run. Advantages also include the ability of bridged driver to work with any possible network adapter (of Ethernet type), including wireless, PCMCIA and others - without the need to perform complex operations of patching regular network adapter drivers. After installing InJoy in bridged mode, you will have two interfaces : eth0 and br0, for example. In any scripts or applications that require interface to be specified, you should use br0 instead of eth0. To install InJoy in bridged mode, simply run: # ./Install.sh bridge This will install the driver, edit your NIC configuration and transform it into bridges. Note that if you are installing InJoy remotely, e.g. via SSH session, it may be broken by restarting network subsystem. In this case, please re-connect your SSH client. Supported Linux distributions for bridged mode are the following: * Debian Sarge, * Fedora Core 3 to 6, * Fedora 7, * Open SuSE 10.x, * any other with 2.6 kernel and recognizable network configuration files (i.e. RedHat-like in /etc/sysconfig/network-scripts).