CacheGuard-OS
User's Guide - Version UF-2.2.1


Getting Started

 CacheGuard-OS is an autonomous OS (Operating System) that transforms an x86/x64 based machine (virtual or bare metal) into a network Security & Optimization appliance. Caution: the installation of CacheGuard-OS on a machine, formats all disks on that machine so all persistent data on that machine would be lost.

CacheGuard-OS is based on a Linux kernel and multiple other well-known open source software built from scatch to ensure the maximum level of integrity and security. The mere aggregation of those software and specific software developed by CacheGuard Technologies Ltd forms CacheGuard-OS. Note that CacheGuard does not depend on a particular Linux distribution because it is by itself an appliance oriented Linux distribution.

Open source software used by CacheGuard-OS are mainly distributed under the GNU GPL. Open source programs developped 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.

The installation program proposes to install CacheGuard-OS as a Gateway or a Manager system. A Gateway system is actually the system that provides network Security and Optimisation services. If you install several Gateways, you have the possibility to manage them separately one by one or manage them via a centralised Manager. In the latter case, you can install CacheGuard-OS as a Manager on a dedicated machine that you can use as a centralised Manager. Note that you should exclusively select one installation type on the same machine. In other words, the same machine can't act as a Gateway and as a Manager.

The installed Gateway can be used in forwarding mode to protect internel internet users while ins reverse mode, the Gateway secures and optimises network traffic exchanged with Web applications . Both modes can be activated at the same time on the same Gateway.

Machine Requirements

Gateway Machine Requirements

 The required machine resource for a Gateway system mainly depends on the total number of users to protect (in forwarding mode) or the maximum number of simultaneous users of Web applications to protect (in reverse mode). What we mean by simultaneous users are active users that consume the appliance resources (mainly RAM and CPU). Simultaneous users are distinguished from concurrent users that may be all connected to protected Web applications without necessarily consuming any resources on CacheGuard appliance. On Web applications servers, concurrent users usually consume RAM and/or disk spaces while on CacheGuard, only simultaneous users consume RAM and CPU (number of simultaneous users <= number of concurrent users).

During the installation, the OS is fine-tuned according to the required number of users to support in order to provide the best balance between performances and resources consumption. To provided an optimised quality of service, the tuner program considers that all forward users are not connected at the same time but only 20 percent of them. For instance, an appliance installed for 100 users allows you to protect 100 users/clients and 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.

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

For more users, prefer a machine with more RAM, CPU cores and disk capacity. As a rule of thumb, add 1 CPU core and 1 GB RAM (+ 75 GB disk in forwarding mode) for every 10 additional simultaneous users. For instance, an appliance that needs to support 40 simultaneous users, requires 6 CPU cores, 10 GB of RAM (+ 400 GB of disk capacity in forwarding mode).

On a hardware machine, CacheGuard-OS is more efficient with several low capacity disks configured as a RAID compared to a single high capacity disk. CacheGuard-OS innately supports software RAID by using 3% of the CPU resources only. Supported RAID levels are as follows: RAID 0 (stripping), RAID 1 (mirroring), RAID 5 (stripping + checksum), RAID 6 (stripping + double checksum) and RAID 10 (stripping + mirroring).

With CacheGuard-OS you have the possibility to activate all integrated security and optimisation features at the same time on the same machine. Some functions like the HTTP real time compression and the antivirus are more CPU intensive than others and the activation of the antivirus requires about 2 GB of RAM. Configuration rules mentioned above can be applied if you plan to activate all available features at the same time. You probably need less resources in case where you don't need to activate all available features together. Please note that in all cases, CacheGuard-OS requires at least 512 MB of RAM during its installation.

CacheGuard-OS requires at least 2 NIC (Network Interface Card). In case where your machine has only one NIC, you have the possibility to use an USB Ethernet adapter as the second NIC. To benefit from link bonding feature and/or to use the auxiliary network interface, you will need additional network interfaces (or USB Ethernet adapters).

Note that CacheGuard-OS can be installed for a minimal number of users on a mini computer. The minimum machine configuration to support 10 users in forwarding mode is as follows:

This configuration allows you to activate all CacheGuard-OS features at the same time on a x64 (64 bits) machine. However, in case where big RAM consumer services such as the antivirus are not required, CacheGuard-OS can run on a machine with only 256 MB of RAM. With that amount of RAM, your CacheGuard-OS based machine would perfectly work as a firewall and VPN server. But as mentioned before, the OS installation would still require at least 512 MB of RAM.

Manager Machine Requirements

The required machine resource for a Manager system mainly depends on the total number of Gateway systems to manage. To manage 10 Gateway systems, a typical machine configuration would be:

To manage more gateways, prefer a machine with more disk capacity. As a rule of thumb, add 25 about GB of disk capacity for every 10 additional Gateway systems to manage.

Machine compatibility

CacheGuard-OS supports almost all popular x86/x64 based devices in the market. If your device 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 device.

OS Installation

The same installation CDROM can be used to install the appliance as a Gateway system as well as a Manager system. Just follow given instructions during the installation to select the required system to install.

CDROM drive Installation

 To install CacheGuard-OS from a CDROM drive, follow instructions below:

USB memory stick Installation

 To install CacheGuard-OS from a USB memory stick, follow instructions below:

Network Installation

 To install CacheGuard-OS from the network, your target machine should support PXE boot. You will also need an installation server that runs the following services: To install CacheGuard-OS from the network, follow the instructions below:

The OVA distribution form

 The Gateway OVA (Open Virtual Appliance) form uses 2 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

For security reasons, VMware tools are not installed and can't be installed on a CacheGuard appliance.

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 plan to install CacheGuard on a Microsoft Hyper-V ® VM, think about disabling the MAC address spoofing on your VM.

Gateway Connection

In a basic configuration, CacheGuard Gateway divides your network into two separated areas: an external non trusted area connected to the internet and an internal trusted area connected to your LAN. CacheGuard uses two logical network interfaces. The first network interface is called external and the second network interface internal. Each logical network interface should be associated to at least one physical network interface.
The link command without any argument displays all detected physical network interfaces in your machine. The command link bond displays associations between logical and physical network interfaces. Use those commands to identify your network interfaces. By default the external network interface is associated to eth0 and the internal network interface to eth1.

Connect the internal physical interface to your LAN and the external physical interface to your WAN (usually your internet router).

Gateway Configuration

First Configuration

 To start, connect to CacheGuard console interface and login as the "admin" user. The console interface is one of the following:

When you first connect to the appliance the setup command is automatically executed to perform a basic network configuration. You have also the possibility to use the CLI (Command Line Interface) instead of the setup command to make a basic network configuration. To do so, you can use the following commands:

At this stage, the new IP configuration is not yet active. To activate it, you must execute the apply command (in case where the setup command is used, the apply command is automatically executed).

Basic Configuration

 The configuration procedure is straightforward: you run a set of commands to build a new configuration and then you apply that new configuration to activate it in a single transaction. The magical command that allows you activate a new configuration is called apply. This command replaces the running (current) configuration by the newly made configuration. It is important to note that during the phase of creating a new configuration, the running configuration is not affected. Therefore, you have the possibility to tune your new configuration before affecting the running configuration.

The apply command makes a series of verifications to ensure that the new configuration is consistent. If no integrity issues is detected, the apply operation begins and may approximately take between 5 and 180 seconds (depending on requested operations and your machine resources). Please note that the apply command runs in background. This means that after its invocation you can continue to execute some other commands but you can't modify any configurations before the termination of the last apply command. The apply report command displays a state report of its execution.

Many services in CacheGuard-OS depend on the appliance internal clock so setting the right time and date is crucial in running CacheGuard-OS. To setup the time and date of your system, use the following command:

where YYYY/MM/DD-hh:mm:ss are respectively the year, month, day, hours, minutes and seconds. For instance you can use the following: 2024/03/20-03:06:26. You have also the possibility to use NTP servers to setup the time and date. Please refer to the Date & Time documentation for further information.

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 a remote administrator as trusted, add her/his network IP address and the logical network interface via which she/he is allowed to connect to the system to the list of trusted administrators. The access command allows you to manage the list of trusted remote administrators. For instance, to allow an administrator having an IP address in the network 10.20.0.0 255.255.255.0 to connect to the system via the internal network interface, use the following commands:

The SSH and Web administration GUI interfaces/services should be activated before usage. To activate both, use the following commands:

To connect to a remote CacheGuard appliance from a Linux system, you can use the "ssh admin@10.20.0.254" command, where 10.20.0.254 is the internal IP address of your CacheGuard appliance. To configure a remote CacheGuard appliance using a Web browser, connect to the URL: "https://10.20.0.254:8090" where 10.20.0.254 is the internal IP address of your CacheGuard appliance. The default SSL certificate provided by the appliance is a self-signed certificate identified by the Id default in CacheGuard-OS. Before permanently accepting this certificate as a valid certificate, compare its fingerprint in your Web browser against the fingerprint obtained from your CacheGuard console port by invoking the tls server fingerprint default command. Mind that the protocol used is https and not http. By default, credentials to use to login via the Web administration GUI are the same as those used to login via the console port or via SSH. Think about setting different passwords for the console/ssh interfaces and the Web administration GUI (use the command password login).

Supported features/functions are called modes and they can be activated or deactivated using the mode command. By default, the forwarding Web proxy (web mode) as well as the transparent mode are activated. The transparent mode allows the appliance to transparently intercept HTTP traffic (TCP port 80) without being obliged to configure your Web browsers (Firefox, Chrome, Edge, Safari...) to use CacheGuard as a Web proxy. With this mode, the routing configuration of your networks should route all HTTP traffic via your CacheGuard appliance. For a basic implementation, your appliance may be your default gateway to the internet (see the Transparent Implementation for further information). In a non-transparent mode (web mode), your Web browsers should be configured to explicitly use CacheGuard Web proxy. The CacheGuard Web proxy can be reached at "10.20.0.254:8080" where "10.20.0.254" is the internal IP address of your CacheGuard appliance.

One interesting mode is the Web caching mode. To activate it, you can use the following commands:

There are plenty of modes in CacheGuard-OS that you can activate or deactivate as per your requirements. The General Modes section in this User's Guide gives you a brief description of each.

At this stage, you can use your appliance as a gateway to connect to the internet and browse the Web. If you need to protect your Web servers by your CacheGuard appliance, you must activate the reverse mode by invoking the mode rweb on and then configure the reverse mode using the rweb command. To get an optimised configuration, it is recommended to deactivate features that are not required. For instance, if you no longer need the forwarding Web proxy, you can deactivate it by using the mode web off command.

The command help gives a brief description of all available commands. To obtain the detail for a specific command, use the help command followed by a command (example: help ip). A completion facility is available when typing commands. To use the completion press the <TAB> key to complete a command or to obtain a list of available arguments.

Copyright (C) 2009-2024 CacheGuard - All rights reserved