CacheGuard OS
User's Guide - Version EH 1.3.2

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 Web traffic security & optimisation. It transforms an x86/x64 based machine into a powerful Web gateway appliance. Web traffic will be completely under your control since they cross the CacheGuard box. 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 surfers 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 Web surfers) the most important factor is the total number of end-users. A capacity manager integrated to the OS tunes the appliance during the installation for the given number of users. According to the the capacity management policy all end users are not connected at the same time but just 20 percents of them. For instance an appliance tuned for 100 end-users allows you to protect 100 not named users. So the appliance is tuned to run for 20 simultaneous users. Of course a burst of 100 simultaneous Web connections will be granted for a short period of time.

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

For 100 end-users (20 simultaneous users), a typical hardware configuration is:

For more users, prefer a server with more RAM, CPU Core and HDD Storage Capacity. Normally 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 4 CPU core, 6 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 HTTP real time Compression or 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 integrated into the CacheGuard OS.

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 bandwidths.

Note that CacheGuard OS may be installed for a minimal number of users on a mini computer. The minimum hardware configuration for 5 users 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 128 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 port. Your console port 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 to 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 surfers.

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 Web 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. At that moment, just type the <TAB> key to complete a command or to obtain a list of available arguments.