User's Guide - Version EH-1.5.5

Getting Started

Caution: This is an autonomous full OS (Operating System) that requires a dedicated hardware or virtual machine. The full installation program formats all hard drives so all existing data will be erased after a full installation. Please read the CacheGuard license agreement before installing CacheGuard OS on your machine.

CacheGuard OS is a Linux-based OS dedicated to network security & traffic optimisation. It transforms an x86/x64 based machine into a powerful UTM (Unified Threat Management) appliance. Note that CacheGuard is an autonomous Operating System so no other OS is required to install it on your machines.

The installed appliance may be used in forwarding mode to protect Web users while a reverse mode allows you to secure and optimise your Web applications.

CacheGuard OS is the result of the mere aggregation of open source programs provided by CacheGuard Technologies Ltd and third parties open source software. Third parties open source software are mainly distributed under the GNU GPL. Open source programs provided by CacheGuard Technologies Ltd are distributed under the CacheGuard License which is a specific open source license. Please read the License Agreement carefully before any usage.

Hardware Requirements

To implement the CacheGuard-OS in forwarding mode (to protect users) the most important factor is the total number of users. A capacity manager integrated into the OS tunes the appliance during the OS installation according to the given number of users. The capacity manager considers that all users are not connected at the same time but just 20 percent of them. For instance an appliance installed for 100 users allows you to protect 100 users/clients ans is tuned to run for 20 simultaneous users. In this case a burst of 100 simultaneous users will be granted for a short period of time.

To implement CacheGuard-OS in reverse mode (to protect servers) you should consider the number of simultaneous Web connections rather than the total number of users.

For 100 users (20 simultaneous users), a typical hardware configuration would be:

For more users, prefer a server with more RAM, CPU Core and HDD Storage Capacity. As a rule of thumb, add 1 GB of RAM and 75 GB of HDD storage capacity for every 50 users. For instance an appliance tunned for 200 users requires a machine with 6 CPU core, 8 GB of RAM and 350 GB of HDD storage capacity.

A CacheGuard appliance runs better with several low storage capacity HDD configured as a RAID compared to a single high storage capacity HDD (CacheGuard-OS supports RAID 0, 1, 5, 6 and 10).

With CacheGuard you have the possibility to activate all integrated security and optimization features at the same time. Some features (like the Antivirus) are more CPU intensive than others. The above given configuration is required when you intend to activate all available features at the same time. You probably need less hardware resources if you don't need to activate all available features at the same time.

CacheGuard-OS requires at least 2 network interfaces. To use the link bonding feature and/or use the auxiliary network interface, you need additional network interfaces. Ethernet NIC (Network Interface Card) and USB Ethernet adapters are supported. In case you use a USB Ethernet adapter we recommend connecting it to the external (Internet) as USB Ethernet adapters usually have lower bandwidth.

Note that CacheGuard-OS can be installed for a minimal number of users on a mini computer. The minimum hardware configuration for 5 users on an x86 (32 bits) machine is as follows: This configuration allows you to activate all CacheGuard-OS features at the same time on a x64 (64 bits) machine. However CacheGuard-OS can be installed on a x86 (32 bits) machine with only 288 MB of RAM if memory consuming features such as the antivirus are not required.


Note that if your RAM is too small compared to your Hard Drive capacity, you should probably reduce your Hard Drive size by using the option "Limit the Total storage capacity" in the installation menu (This is done using percentage values). Also you can add additional RAM into your machine to match your Hard Drive storage capacity.

Hardware compatibility

CacheGuard supports almost all popular x86/x64 based hardware devices. If your hardware is not detected during the installation, please contact us and we will do our best to integrate adequate drivers into the OS to support your hardware.

OS Installation

The installation procedure tunes the OS according to three major parameters: The users capacity, the guarding capacity and the number of Web sites to cloak.

Users capacity is the total number of installed users. Note that only twenty percent (20%) of these users are considered to be simultaneous users and each user may open 15 simultaneous Web connections. For instance to support 20 simultaneous users, specify 100 for the users capacity.

The guarding record capacity is the maximum number of supported URLs or domain names used for the URL guarding feature.

Finally the number of supported Web sites to cloak is the number of Web sites that will be secured and optimised with CacheGuard. During the installation phase, the tuner module reserves adequate resources for each Web site. Web sites are identified by their full domain names.

CDROM Installation

USB memory stick Installation

Network Installation

Required tools

A Linux installation Server including:


The OVA distribution form

The OVA (Open Virtual Appliance) form uses 3 network interfaces that you should connect to the appropriate switch to match your needs. After running the virtual appliance login as "admin" (the password is "admin" too) and follow the setup operation (the external interface should be connected to your Internet router and the internal interface should be connected to your LAN switch).

VMware ® Notes

As CacheGuard aims to be compatible with almost all hardware and visualisation systems, there is no possibility to install VMware tools with it.

Linux KVM Notes

CacheGuard is fully compatible with all Linux KVM such as Proxmox ®.

Oracle VirtualBox ® Note

CacheGuard is fully compatible with Oracle VirtualBox ®.

Microsoft Hyper-V ® Note

Please note that if you intend to install CacheGuard on a Microsoft Hyper-V ® VM, think about disabling the MAC address spoofing on your VM.


To start, connect to your system using the console interface. The console interface is one of the following:

CacheGuard uses two logical network interfaces. The first network interface is named "internal" and the second network interface "external". Each logical network interface should be associated to at least one physical network interface.

The command "link" without any argument displays all detected physical network interfaces in your system. The command "link bond" displays associations between logical and physical network interfaces. Use these commands to identify your network interfaces. By default the internal network interface is associated to "eth0" and the external network interface to "eth1".

Connect all internal physical interfaces to your internal network and all external physical interfaces to your external network (usually your Internet router).

Note: to connect the external network interface directly to a router, use a crossed CAT 5 network cable. To connect it to a switch (or hub), use a straight (classic) CAT 5 network cable.

Simple Configuration

First Configuration

When you first connect to the appliance the command "setup" is automatically executed. This command performs a basic startup configuration. Please note that you can use this command at any time.

Basic Configuration

CacheGuard is implemented as a filter in your network by dividing the Web access segment into two separated areas: An external non trusted area connected to the Internet and an internal trusted area connected to backend Web servers or Web users.

To configure the network connect the console port and follow the following instructions:

The configuration procedure is straightforward: You have to run a set of commands to build a new configuration. During the phase of creating a new configuration the current running configuration is not affected. Once the new configuration is created you apply it to the appliance by invoking the command "apply". This command replaces the current running configuration with the newly built configuration. The "apply" command runs in background. This means after its invocation you can continue to execute other commands but you can't modify the settings before the termination of the last "apply" command. The command "apply" followed by the keyword "report" print a state report of its execution.

The caching policy and some self-management mechanisms depend on the internal clock of your appliance so setting the right time and date is crucial in running a proper configuration. Use the following command to initialise time & date: By default the appliance is in a transparent mode. That means no Web navigator (Windows IE, Mozilla...) configuration is required to filter HTTP (port 80) accesses. In this mode the IP configuration of your networks should route all HTTP traffic to your appliance. For a basic implementation, your appliance may be your default gateway to the Internet (See Transparent Implementation)

In a non-transparent mode, just configure your Web navigators to use the internal IP address of your CacheGuard appliance as HTTP, HTTPS and FTP proxy.

The rest of the configuration may be done using an SSH client or a Web browser. Only trusted administrators are allowed to remotely manage the appliance. To declare an administrator as trusted add his/her IP address to the list of trusted administrators - Just type the following commands:

The SSH or HTTPS interfaces should be activated before usage. To activate both use the following commands: To connect to a remote appliance under UNIX type "ssh admin@<cacheguard-internal-ip>". Remember that by default only the internal network interface could be used to remotely administrate the appliance (unless you configure the administration topology using the command "admin topology"). To configure a remote appliance using the Web administration GUI you should use a Web browser. Just connect to the URL: "https://<cacheguard-hostname.>. <cacheguard-domainname.>:8090" where <cacheguard-hostname.>. <cacheguard-domainname.> is resolved to the internal IP address of your appliance. The certificate provided by the appliance is self-signed. Before permanently accepting this certificate as a valid certificate compare its fingerprint printed in your Web browser against the fingerprint printed in the console interface (Use the command "admin https fp"). Mind that the protocol used is https and not http. The login name is "admin" and by default the password is the same as the password to login via the console port. Think about setting different passwords for the console/ssh interface and the Web administration GUI (use the command "password").

General features could be activated or deactivated using the command "mode". Keep in mind to always deactivate features that you don't really need. You probably want to activate the caching mode. For this use the following commands:

At this stage, you can use your appliance as a secure gateway appliance to connect to the Internet. However your needs may be to secure your precious Web servers. To do so, activate the reverse mode (Just invoke the command "mode rweb on" followed by the "apply" command as usual) and configure everything using the command "rweb". If you no longer need to browse the Web through your appliance deactivate the forward mode (use the command "mode web off").

An online manual is available at any time. The command "help" gives a brief description of all available commands. To obtain the detail for a specific command, type "help" followed by that command (example: "help access"). A completion facility is available when typing commands in a console interface. To use the completion just type the <TAB> key to complete a command or to obtain a list of available arguments.