cOS Stream 3.90.00 Administration Guide

Table of Contents

1. Overview
1.1. Features
1.2. System Architecture
2. System Management
2.1. Management Access
2.1.1. Overview
2.1.2. The Local User Database
2.1.3. The CLI
2.1.4. CLI Scripting
2.1.5. Secure Copy
2.1.6. RADIUS Management Authentication
2.1.7. SNMP Monitoring
2.1.8. SNMPv3 Polling
2.2. Date and Time
2.2.1. Overview
2.2.2. Time Servers
2.3. Licensing
2.4. Backup and Restore
2.5. Upgrading Software
2.6. Crashdumps
2.7. Statistics
2.8. Diagnostic Tools
2.8.1. The Ping Command
2.8.2. Dconsole
2.8.3. Pcapdump
2.8.4. The techsupport Command
2.9. Hardware Monitoring
2.9.1. User Hardware Monitoring
2.9.2. System Hardware Monitoring
2.9.3. Sensors for Clavister Products
3. Interfaces
3.1. Ethernet Interfaces
3.2. VLAN
3.3. Service VLANs
3.4. Interface Groups
3.5. Zones
3.6. Security/Transport Equivalence
3.7. Link Aggregation
3.8. GRE Tunnels
3.9. Using Jumbo Frames
4. ARP
4.1. Overview
4.2. The ARP Cache
4.3. Creating ARP Entries
5. IP Address Management
5.1. The Address Book
5.2. Address Types
5.3. Auto-generated Address Objects
5.4. IPv6 Support
5.5. IPv6 With Embedded IPv4
5.6. FQDN Address Objects
6. Routing
6.1. Principles of Routing
6.2. Static Routing
6.3. Route Failover
6.3.1. Overview
6.3.2. Gateway Monitoring
6.3.3. Host Monitoring
6.3.4. Route Monitoring Issues
6.4. Virtual Routing
6.4.1. Overview
6.4.2. A Simple Virtual Routing Scenario
6.4.3. IPsec Virtual Routing
6.4.4. Troubleshooting
6.5. Policy-based Routing
6.6. OSPF
6.6.1. Dynamic Routing
6.6.2. OSPF Concepts
6.6.3. OSPF Configuration Objects
6.6.4. Dynamic Routing Rules
6.6.5. Setting Up OSPF
6.6.6. An OSPF Example
6.6.7. OSPF Troubleshooting
6.7. BGP
6.8. Traceroute
7. IP Rules
7.1. Security Policies
7.2. IP Rule Evaluation
7.3. IP Rule Actions
7.4. Geolocation
8. Services
8.1. Overview
8.2. SCTP
8.2.1. The SCTP Service
8.2.2. Multi-Homing Redundancy
8.2.3. Node Only Routes with Multi-Homing Redundancy
8.3. ICMP
8.4. ServiceIPProto Services
8.5. Service Groups
9. Address Translation
9.1. Overview
9.2. NAT
9.3. NAT Pools
9.4. Deterministic NAT
9.5. SAT
9.5.1. One-to-One Translation (1:1)
9.5.2. Many-to-Many Translation (M:N)
9.5.3. Many-to-One Translation (N:1)
9.5.4. Port Translation with SAT
9.5.5. Combining SAT with NAT in the Same Rule
9.6. Protocols Not Handled by SAT
9.7. NAT64 Address Translation
9.7.1. Stateful NAT64
9.7.2. Stateful NAT64 with DNS64
9.7.3. Stateful NAT64 Hairpinning
9.7.4. Stateless NAT64 (SIIT)
9.8. CGNAT
10. ALGs
10.1. Overview
10.2. FTP ALG
10.3. SIP ALG
10.4. DNS ALG
11. Internet Access
12. DNS
13. IPsec VPN
13.1. Overview
13.1.1. IPsec VPN Usage
13.1.2. IPsec VPN Encryption
13.1.3. IPsec VPN Planning
13.1.4. The SSL VPN Alternative
13.2. IPsec Components
13.2.1. Overview
13.2.2. Internet Key Exchange (IKE)
13.2.3. IKE Authentication
13.2.4. IPsec Protocols (ESP/AH)
13.2.5. Creating and Using Proposal Lists
13.2.6. Pre-shared Keys
13.2.7. Certificates with IPsec
13.2.8. IPsec Tunnels
13.2.9. Manually Keyed IPsec Tunnels
13.3. Setting Up IPsec Tunnels
13.3.1. IPsec LAN to LAN with Pre-shared Keys
13.3.2. IPsec LAN to LAN with Certificates
13.3.3. IKE Config Mode
13.3.4. IPsec Roaming Clients
13.4. NAT Traversal
13.5. DiffServ with IPsec
13.6. IPsec Troubleshooting
13.6.1. General Troubleshooting
13.6.2. Troubleshooting Certificate Problems
13.6.3. IPsec Troubleshooting Commands
13.6.4. Using ike -snoop
13.6.5. Management Interface Failure with VPN
13.6.6. Specific Error Messages
13.6.7. Specific Symptoms
15. SSL Inspection
16. Certificate Management
16.1. Configuring Certificates
16.2. CA Server Access
16.3. CRL Distribution Point Lists
16.4. Management with CMP
17. Authentication
17.1. Authentication Profiles
17.2. RADIUS Authentication
17.3. The radiussnoop Command
17.4. Multi-Factor Authentication
18. Access Rules
18.1. Overview
18.2. Creating Access Rules
19. GTP Inspection
20. Events and Logging
20.1. Overview
20.2. Using the log Command
20.3. Logging to Syslog Servers
20.4. Filtering Log Messages
20.5. SNMP Traps
21. DHCP
21.1. Overview
21.2. DHCP Servers
21.2.1. Defining DHCP Servers
21.2.2. Static DHCP Hosts
21.2.3. DHCP Server Custom Options
21.2.4. DHCP Server Advanced Settings
21.3. DHCP Client
22. High Availability
22.1. Overview
22.2. HA Mechanisms
22.3. Setting Up HA
22.4. Upgrading an HA Cluster
22.5. HA Issues
23. Traffic Shaping
23.1. Overview
23.1.1. Traffic Shaping Objectives
23.1.2. Traffic Shaping Implementation
23.2. Use Case Examples
23.2.1. Simple Bandwidth Limiting
23.2.2. Limiting Bandwidth in Both Directions
23.2.3. Creating Differentiated Limits Using Chains
23.3. Using Precedences
23.4. Grouping Users
23.5. Summary
23.5.1. Traffic Shaping Principles
23.5.2. Setup Recommendations
24. Threshold Rules
25. Black/Whitelists
25.1. Blacklisting
25.2. Whitelisting
26. Application Control
27. IPS
27.1. Overview
27.2. Setting Up IPS
27.3. IPS Signature Management
27.4. Snort File Usage
27.5. Best Practice Deployment
28. Advanced Settings
28.1. Flow Timeout Settings
28.2. Length Limit Settings
28.3. Fragmentation Settings
28.4. Local Fragment Reassembly Settings
28.5. Path MTU Discovery

Chapter 1: Overview

[Note] Note: This document is also available in other formats

A PDF version of this document along with all current and older documentation in PDF format can be found at

It also available in a framed HTML version.

1.1. Features

A Clavister NetShield Firewall running cOS Stream provides vital network security functions while providing high throughput performance by fully utilizing the parallel processing advantages of multi-core hardware platforms.

The firewall also provides seamless integration of all its subsystems, in-depth administrative control of functionality, as well as exposing a minimal attack surface which helps negate the risk from security attacks.

Configuration Objects

From the administrator's perspective the conceptual approach is to visualize operations through a set of logical building blocks or configuration objects. Combining different objects allows configuration in an almost limitless number of different ways. This granular control allows the administrator to meet the requirements of the most demanding network security scenarios.

Key Features

The list below presents the key features of cOS Stream's extensive feature set:

IP Routing
cOS Stream provides a variety of options for IP routing including static routing.
Firewalling Policies
cOS Stream provides stateful inspection-based firewalling for a wide range of protocols such as TCP, UDP and ICMP. The administrator can define detailed firewalling policies based on source/destination network/interface, protocol and ports.
cOS Stream supports IPsec based VPNs and can provide individual security policies for each VPN tunnel.
High Availability

High Availability (HA) is supported through automatic fault-tolerant failover to a secondary Clavister NetShield Firewall should a failure be detected. Two firewalls operate together in an HA cluster, with one being active while the other is passive and constantly mirroring the state of the active unit.

This feature is described in more detail in Chapter 22, High Availability.

System Documentation

Reading through the available documentation carefully will ensure that you get the most out the product. In addition to this document, the reader should also be aware of the companion reference guides:
  • The CLI Reference Guide details all CLI commands.

  • The Log Reference Guide details all log event messages.

  • The Statistics Reference Guide details all system statistics parameters.

  • The SNMP Traps Reference Guide details all system statistics parameters.

  • The Getting Started Guide documents describe how to set up a new installation for different platforms. This includes guides for Clavister hardware products, as well as for virtual environments.

  • The Use Case Guide describes how to set up the product for some specific scenarios.

Together, these documents form the essential reference material for product operation.

Product Education and Certification

For details about classroom and online education as well as certification, visit the Clavister company website at or contact your local sales representative.

1.2. System Architecture

The Clavister NetShield Firewall architecture is centered on the concept of flows. Traditional IP routers or switches commonly inspect all packets and then perform forwarding decisions based on information found in the packet headers. With this approach, packets are forwarded without any sense of context which eliminates any possibility to detect and analyze complex protocols and enforce corresponding security policies.

Stateful Inspection

The Clavister NetShield Firewall employs a technique called stateful inspection which means that it inspects and forwards traffic on a per-flow basis. cOS Stream detects when a new flow between a source and destination is being established, and keeps information about the flow over its lifetime. By doing this, cOS Stream is able to understand the context of network traffic and this enables it to perform a variety of important functions.

The stateful inspection approach additionally provides high throughput performance with the added advantage of a design that is highly scalable. The subsystem that implements stateful inspection will sometimes be referred to in documentation as the state-engine.

All flows have a specified idle lifetime, after which they are removed from the flow table.

Basic Building Blocks

From the administrator's viewpoint, the basic firewall building blocks are:

  • Interfaces such as physical Ethernet interfaces or logical VPN tunnels.

  • Logical Objects which are individual logical definitions within cOS Stream. For example, Address objects can be defined in the Address Book to give logical names to IP and other types of addresses.

  • Rule Sets which make up the security policies which the administrator wants to implement. These include IP rules.

These three types of building blocks are discussed next.


Interfaces are the doorways through which network traffic enters or leaves the Clavister NetShield Firewall. Without interfaces, a Clavister NetShield Firewall has no means for receiving or sending traffic.

The following types of interface are supported:

  • Physical interfaces

    These correspond to the actual physical Ethernet interface ports through which traffic arrives and leaves the Clavister NetShield Firewall.

  • Tunnel interfaces

    Used for receiving and sending traffic through VPN tunnels. These are treated as logically equivalent to physical interfaces when configuring cOS Stream. For example, a route in a routing table could specify either a physical or tunnel interface as the destination for a particular network.

Interface Symmetry

cOS Stream interface design is symmetric, meaning that the interfaces of the device are not fixed as being on the "insecure outside" or "secure inside" of a network topology. The notion of what is inside and outside is totally for the administrator to define.

Logical Objects

Logical objects can be seen as predefined building blocks for use by the rule sets. The address book, for instance, contains named objects representing host and network addresses.

Another example of logical objects are services which represent specific protocol and port combinations.

Rule Sets

Finally, rules which are defined by the administrator in the various rule sets are used for actually implementing cOS Stream security policies. The most fundamental set of rules are the IP Rules, which are used to define layer 3 IP filtering policies.

Basic Packet Flow

This section outlines the basic flow for packets received and forwarded by cOS Stream. The following description is simplified and might not be fully applicable in all scenarios, however, the basic principles will be valid for all deployments.

  1. An Ethernet frame is received on one of the Ethernet interfaces in the system. Basic Ethernet frame validation is performed and the packet is dropped if the frame is invalid.

  2. The IP datagram within the packet is passed on to the consistency checker. The checker performs a number of sanity checks on the packet, including validation of checksums, protocol flags, packet length and so on. If the consistency checks fail, the packet gets dropped and the event is logged.

  3. cOS Stream now tries to lookup an existing flow by matching parameters from the incoming packet. A number of parameters are used in the match attempt, including the source interface, source and destination IP addresses and IP protocol.

    If a match cannot be found, a flow establishment process starts.

  4. The Access Rules are evaluated to find out if the source IP address of the new flow is allowed on the received interface. If no Access Rule matches then a reverse route lookup will be done in the routing tables.

    In other words, by default, an interface will only accept source IP addresses that belong to networks routed over that interface. A reverse lookup means that cOS Stream looks in the routing tables to confirm that there is a route with this network as the destination on the same interface.

    If the Access Rule lookup determines that the source IP is invalid, then the packet is dropped and the event is logged.

  5. A route lookup is made using the routing table. The destination interface for the flow has now been determined.

  6. The IP rules are now searched for a rule that matches the packet. The following parameters are part of the matching process:

    • Source and destination interfaces
    • Source and destination network
    • IP protocol (for example TCP, UDP, ICMP)
    • TCP/UDP ports
    • ICMP types
    • Point in time in reference to a predefined schedule

    If a match cannot be found, the packet is dropped.

    If a rule is found that matches the new flow, the Action property of the rule decides what cOS Stream should do with the flow. If the action is Drop, the packet is dropped and the event is logged according to the log settings for the rule.

    If the action is Allow, the packet is allowed through the system. A corresponding flow will be noted by cOS Stream for matching subsequent packets belonging to the same flow. The allowed traffic is also bidirectional so that the same IP rule also permits packets to return from the destination network.

    Finally, the opening of the new flow will be logged according to the log settings of the rule. The default is for logging to be enabled.

  7. Eventually, the packet will be forwarded out on the destination interface according to the flow. If the destination interface is a tunnel interface, additional processing such as encryption or encapsulation might occur.

Chapter 2: System Management

2.1. Management Access

2.1.1. Overview

This chapter provides details of how to work with cOS Stream's management interfaces.

Management Access Methods

The following methods are available for management access:

  • Command Line Interface (CLI)

    The Command Line Interface (CLI) is accessible either locally via a computer's local console port or remotely to an IPv4 or IPv6 address across a network using the Secure Shell (SSH) protocol. It provides fine-grained control over all parameters in cOS Stream.

    This feature is described further in Section 2.1.3, The CLI.

  • SCP

    Secure Copy (SCP) is a widely used communication protocol for file transfer. SCP is a complement to the CLI and provides a secure means of file transfer between an external management computer and the firewall across an IP network. Various files used by cOS Stream, such as configuration backups, can be both uploaded and downloaded using SCP.

    This feature is described further in Section 2.1.5, Secure Copy.

    Note that there exists a wide selection of third part SCP clients for nearly all platforms.

  • SNMP

    A Simple Network Management Protocol (SNMP) client can connect to cOS Stream to get read-only access to system statistics.

    This feature is described further in Section 2.1.7, SNMP Monitoring.

  • InCenter

    Clavister InCenter is a separate software application that runs as a server on an external computer. Through its interfaces, simultaneous management of multiple Clavister NetShield Firewalls is possible using a single unified configuration database. This software is described further in the separate InCenter Administration Guide.

2.1.2. The Local User Database

By default, cOS Stream provides a default LocalUserDatabase object which can be used to authenticate management access if this method is selected (by default, it is selected). This database contains, at a minimum, one predefined user with the following default credentials:

Username: admin
Password: admin

This account has full administrative read/write privileges to all configuration data and is always the account used for initial SSH login (console access does not require any credentials in the default configuration).

[Important] Important: Change the default administrator password

For security, it is strongly recommended to change the password for the predefined admin account as soon as possible following the initial configuration of cOS Stream.

Displaying the Local User Database

When using the CLI, the name of the predefined local user database can be displayed with the command:
System:/> show LocalUserDatabase

The contents of this can be displayed by first changing the CLI context to be the database:
System:/> cc LocalUserDatabase AdminUsers
The CLI prompt will change to indicate the new context and the database contents can be displayed:
System:/LocalUserDatabase/AdminUsers> show
   Name   Groups          Comments
   -----  --------------  --------
   admin  Administrators  <empty>
Here, the Group membership is significant since this determines the privileges that a user has. Finally, return to the default CLI context:
System:/LocalUserDatabase/AdminUsers> cc

Creating an Auditor Account

Extra user accounts in the local user database can be created as required with arbitrary usernames and passwords. If the group is specified as Administrators then it has full access privileges.

If, however, the group is specified as the text string Auditors, the user will only have read-only privileges and will not be able to make configuration alterations. The following commands create an auditor account with a username of audit and a password of audit:

System:/> cc LocalUserDatabase AdminUsers
System:/LocalUserDatabase/AdminUsers> add User audit

Linking Logins to the Database

The local user database is referred to during a login because the relevant access object points to an AuthenticationProfile which then points to the database which stores the credentials.

For example, SSH logins are controlled by a RemoteMgmtSSH object. This object refers to an AuthenticationProfile object that then refers to the database to be used for authentication.

AuthenticationProfile objects are discussed further in Section 17.1, Authentication Profiles. The diagram below illustrates the relationship between the various components.

Local User Database Usage with SSH

Figure 2.1. Local User Database Usage with SSH

2.1.3. The CLI

The CLI provides a comprehensive set of commands that allow the display and modification of a configuration.

This section only provides a summary for using the CLI. For a complete reference for all CLI commands, see the separate Clavister cOS Stream CLI Reference Guide.

String Delimiters, the Escape Character and Special Characters

When entering CLI commands, literal strings can be enclosed in double quotation mark characters ("..."). For example:
add User my-user Password="pass word"
However, to include the double quotation mark itself in a string, it must be preceded by a backslash (\) which is the CLI escape character:
set User my-user Password="pass\"word"

Other special characters that might be needed are the following:

  • \r - The carriage return character.
  • \n - The new line character.
  • \t - The tab character.
  • \\ - The escape character \ itself.

For example:

set RemoteManagement RemoteMgmtSSH ssh Banner="Welcome!\r\n - Type \"help\"

Note that the only other case that requires a backslash escape character is when using the dollar sign ($) in a CLI script when it is not part of a variable such as $1. When used in another context within a CLI script, it must be written as \$. This is discussed further in Section 2.1.4, CLI Scripting.

Case Sensitivity

The CLI is case-sensitive. However, the tab completion feature of the CLI does not require the correct case to perform completion and will alter the typed case if it is required (the tab completion feature is explained later in this section).

CLI Access Methods

The CLI is accessible in one of two ways:

  • Remotely through a network connection to an Ethernet interface, using the Secure Shell (SSH) protocol from an SSH client (optionally with public key authentication).

    SSH access is controlled by a predefined RemoteMgmtSSH configuration object.

  • Locally through the firewall's local console. On a Clavister hardware product, direct connection is via the local console port on the unit. In a virtual environment, this is the same as the hypervisor's console.

    Local console access is controlled by a predefined ComPortAccess configuration object called COM1.

Enabling SSH Access

The Secure Shell (SSH) protocol can be used to access the CLI over a network from a remote host via one of the Ethernet interfaces. SSH is enabled by default on the default management Ethernet interface.

SSH is a protocol primarily used for secure communication over insecure networks, providing strong authentication and data integrity. SSH clients are freely available for almost all platforms. cOS Stream supports version 2 of the SSH protocol.

A RemoteMgmtSSH rule controls SSH access on the default management interface. A predefined RemoteMgmtSSH rule exists in the default configuration but it is disabled. It can be displayed with the CLI command:

System:/> show RemoteManagement RemoteMgmtSSH
  # Name
  - -------------
o 1 RemoteMgmtSSH

To enable this rule, use the command:

System:/> set RemoteManagement RemoteMgmtSSH RemoteMgmtSSH -enable

All such rules also require their SourceInterface and SourceNetwork properties to be set for any traffic to be accepted:

System:/> set RemoteManagement RemoteMgmtSSH RemoteMgmtSSH

The following output from a show command now confirms that the rule has all the required properties set and is enabled:

System:/> show RemoteManagement RemoteMgmtSSH
# Name          SourceInterface Source Network
- ------------- --------------- --------------
1 RemoteMgmtSSH if1             if1_net

Authentication for SSH access is controlled by the AuthProfile property of the RemoteMgmtSSH rule. By default this is set to a predefined AuthenticationProfile object called MgmtAuthProfile. This profile points to the predefined local user database which contains a predefined administrator account with the credentials:

  • Username: admin
  • Password: admin

The AgentType property of the authentication profile for SSH access should always be set to Basic. All authentication profile properties are explained in Section 17.1, Authentication Profiles.

Processing Multiple RemoteMgmtSSH rules

If there are multiple RemoteMgmtSSH rules, to ensure that the correct rule will match, they should not use overlapping filters. Instead, each rule should only specify the particular interface and network combination that it should trigger on.

Authentication Methods for SSH Management Access

The following methods can be used to authenticate the administrator when they try to connect to the cOS Stream using SSH:

SSH and SCP with Public Key Authentication

As an alternative to using a password when logging in via SSH or when using SCP, it is possible to automatically authenticate the user using public key authentication. This is done by cOS Stream having the public key of a public/private key pair and the SSH or SCP client having the corresponding private key. When the client connects, cOS Stream is then able to authenticate if the connecting user really has the private key in the key pair.

Public key authentication is set up with the following steps:

  • Generate a new public and private key pair as two identity files. Generating identity files can be done with a number of utilities such as the ssh-keygen utility which is part of the OpenSSH suite.

    Note that the RSA, ECDSA or DSA algorithms could be used for encryption. However, by default, only RSA or ECDSA are allowed and DSA is not allowed. The algorithms allowed are controlled by a property for each algorithm in the relevant RemoteMgmtSSH object. For example, allowing the DSA algorithm is controlled by the property AllowHostKeyDSA.

  • Use Secure Copy (SCP) to upload the .pub public key file to the root directory.

  • Add an SSHClientKey object to the configuration and associate this with the uploaded file. If the uploaded public key file is called, the CLI would be:

    System:/> add SSHClientKey my_pub_key

  • Associate the new SSHClientKey object with a user in a local database. Note that the local database used will be the one pointed to by the AuthenticationProfile object specified by the AuthProfile property of the triggering RemoteMgmtSSH rule.

    In this example, the default administration user admin will be chosen. First, change the CLI context to be the LocalUserDatabase object called AdminUsers:

    System:/> cc LocalUserDatabase AdminUsers 

    Now, set the SSHKeys property of the user called Admin:

    System:/LocalUserDatabase/AdminUsers> set User admin SSHKeys=my_pub_key

    Last, restore the CLI context to the default:

    System:/LocalUserDatabase/AdminUsers> cc

    In fact, any username could be assigned a public key in this way and not just an administrator.

  • The SSH or SCP client must be correctly configured to use public key authentication. Typically, this involves placing the public and private key files in a specific folder but this can vary according to the client.

  • Next, log on using the SSH client but without a password. If public key authentication fails, the SSH client should request the user's password instead. If it succeeds, the password will not be asked for and access will be granted.

The following should be noted about the behavior of SSH authentication using public keys:

  • If the SSH client attempts public key authentication but it fails because the user does not have an associated key in the database then authentication will revert to using the normal username/password method. These credentials will be looked up according to the method described by the associated AuthenticationProfile.

  • If public key authentication is successful then no actions specified in the AuthenticationProfile, such as RADIUS lookup, will be taken.

Troubleshooting SSH Access Problems

If the SSH console is timing out when attempting SSH access, there are a number of possible reasons:

  • Use the local console CLI to check that the SSH server is running:
    System:/> sshserver
    SSH Server   Port  Connected clients  Status
    -----------  ----  -----------------  -------
    ssh_allnets  22    1                  Running
    In the output shown, the server is clearly running. If the status was not Running or if the command returned a new CLI prompt with no output then there was most likely a problem with the initial configuration of the SSH server.
  • Check the configuration of the RemoteMgmtSSH object. If this object is incorrectly specified on initial startup, the SSH server may not run. Check that the RemoteMgmtSSH is enabled and that a valid authentication profile has been specified and that the profile points to a valid database containing a user with the login credentials expected.

    For example, the properties of a RemoteMgmtSSH object with the name ssh_allnets can be displayed using the command:

    System:/> show RemoteManagement RemoteMgmtSSH ssh_allnets

Controlling Direct Console Access to the CLI

The CLI can also be accessed using a console terminal connected directly to a local console port on the firewall. Access through a console port is controlled by a predefined COMPortAccess configuration object which has the name COM1. This can be displayed with the command:
show COMPortAccess 

Port Bps    Data bits Parity Stop bits Flow control Rows Cols
---- ------ --------- ------ --------- ------------ ---- ----
COM1 115200 8         None   1         None         40   80

An AuthenticationProfile is associated with the ComPortAccess object to specify authentication. In the default configuration, no profile is specified so there is no username/password pair required for console login. The same profile used by default for SSH could be associated with console access by using the command:

System:/> set COMPortAccess COM1 AuthProfile=MgmtAuthProfile

Basic Object Management Commands

When managing a firewall configuration, the following commands will be used to perform most of the operations for creating, changing and deleting objects:

  • add - Adds an object, such as an IP address or a rule, to a configuration along with a set of mandatory properties for the object.

  • set - Sets one or more configuration object properties to given values. For example, setting the source interface for a given IP rule.

  • show - Displays the current values of a particular object or set of configuration objects.

  • delete - Deletes a specific configuration object.

CLI Command Structure

CLI commands usually have the structure:
	<command> <object_category> <object_type> <object_name>
For example, to display an IP address object called my_address, the command would be:
System:/> show Address IPAddress my_address
The object category in this case is Address and the type within this category is IPAddress.

When typing commands, the object category can be left out where the command's meaning is unambiguous. For example, the show command above could have been entered as:

System:/> show IPAddress my_address

However, tab completion will always assume that the category is included. For example, tab completion would not be able to help complete the above command if the tab is pressed during or after the IPAddress object type.

The same object name could be used within two different categories or types although this is best avoided in order to avoid ambiguity when reading configurations.

[Note] Note: The terms Category and Context

When describing the CLI, the term object category is also sometimes referred to as the object context.

A command such as add can also include object properties. To add a new IPAddress object with an IPv4 address of, the command would be:

System:/> add Address IPAddress my_address Address=

Setting the System Name and CLI Prompt

Each firewall can have a unique system name and this name appears in the CLI prompt. The default name is System so the default CLI prompt is the following:
If the system name is to be changed to, for example, "my-system1" then the CLI command to do this is the following:
set System Name=my-system1
After activating the change, the CLI prompt becomes the following:

CLI Help

The CLI help command will show all available command options. Typing help followed by a command name will show help information for that command, providing details about the command's function and its options. For example:
System:/> help time
        time (t). Display and set current system time.

Typing the CLI command:

System:/> help help

will give information about the help command itself.

Configuration Object Help

A second help command that provides information about a particular object type or category of objects is helpconfig. This will provide a list of all the properties of an object. For example:
System:/> helpconfig EthernetInterface

Applying a Single Command to Multiple Objects

It is possible to apply a single set or delete command to multiple objects using the -Range option. However, this option can only be applied where the object is part of a list and therefore has an index number.

An example of an object that has an index number is the IPRule object which must be a member of the rule list in an IPRuleSet. Suppose that there are 100 IPRule objects in the main IP rule set. To change the rules with an index number between 65 and 80 (inclusive) so that their LogEnabled property is disabled, the command would be the following:

System:/> cc RuleSet IPRuleSet main
System:/IPRuleSet/main> set IPRule -Range=65-80 LogEnabled=No

Instead a more complex range could be specified:

System:/IPRuleSet/main> set IPRule -Range=10,11-15,60-65 LogEnabled=No

Deletion can be specified in the same way:

System:/IPRuleSet/main> delete IPRule -Range=90-100

The CLI Command History

Just like a command console in many versions of Microsoft Windows™, the up and down arrow keys allow the user to move through the list of commands in the CLI command history. For example, pressing the up arrow key once will make the last command executed appear at the current CLI prompt. After a command appears it can be re-executed in its original form or changed first before execution.

Tab Completion

Remembering, as well as typing commands and their options, can be demanding. The CLI provides a feature called tab completion which means that pressing the tab key during command typing will cause automatic completion of the current part of the command. If completion is not possible then pressing the tab key will provide information about the available options.

For example, consider the following, incomplete command to add a LogReceiver object called my_server to the configuration:

System:/> add LogReceiver LogReceiverSyslog my_receiver

If the tab character is now entered, a list of available options is displayed for the LogSeverity property:

System:/> add LogReceiver LogReceiverSyslog my_receiver
       Type:  String
Description:  Specifies with what severity log events
will be sent to the specified log receivers
    Default:  Emergency,Alert,Critical,Error,Warning,Notice,Information

List of all valid choices:


Tab Completion Only Displays Allowed Properties

There are some important principles that should be understood when using tab completion for object properties:
  • The properties of an object are either mandatory or optional. When using tab completion, optional properties are not displayed until all mandatory properties have been assigned a value.

  • An optional property's use can be dependent on the value specified for another property. For example, in an IPsecTunnel object, the optional ProxyARP property can only be used when the AddRouteToRemoteNetwork property has been set to Yes.

    The tab completion feature is aware of these dependencies and will not display a property if it is dependent on another property which has not yet been assigned a value. Looking at the IPsecTunnel example again, tab completion will only display the ProxyARP property if the AddRouteToRemoteNetwork property has already been assigned a value of Yes.

Special Characters Used with Tab Completion

When entering the value of an object property, the tab character can be preceded by any of the following special characters:

  • Entering the period "." (period) character before entering tab will insert the current value of the object property.

    For example, assume that there is already an object in the address book called my_address and it has the IPv4 address value Now enter the following command:

    System:/> set Address IPAddress my_address Address=.(tab)

    This will cause the current IP address to be displayed:

    System:/> set Address IPAddress my_address Address=

  • Entering the " * " (asterisk/star) character before entering tab will cause the default property value to be automatically filled in.

  • Entering the "?" (question mark) character before tab will provide information about the value that can be entered. For example:
    System:/> set RemoteManagement RemoteMgmtSSH RemoteMgmtSSH
             Type:  Boolean
      Description:  Enable logging.
          Default:  Yes
    Current Value:  Yes

Object Categories and Tab Completion

As mentioned above, objects are grouped by type, for example IPAddress. Types themselves are grouped by category. The type IPAddress belongs to the category Address. Categories are used by tab completion when searching for the right object type to use.

If a command such as add is entered and then the tab key is pressed, cOS Stream displays all the available categories. By choosing a category and then pressing tab again all the available object types for that category are displayed. Using categories means that there is a simple way to specify what kind of object is being sought and a manageable number of options are displayed after pressing the tab key.

Tab completion and its options are discussed further in the introduction to the separate Clavister NetShield Firewall CLI Reference Guide.

Selecting Object Categories

With some categories, it is necessary to first choose a member of that category with the cc (change category/context) command before individual objects can be manipulated. This is the case, for example, with routes. There can be more than one routing table, so when adding or manipulating a route we first have to use the cc command to identify which routing table we are interested in.

Suppose a route is to be added to the routing table main. The first command would be:

System:/> cc RoutingTable main

Notice that the command prompt changes to indicate the current category/context. We can now add the route:

System:/RoutingTable/main> add Route

To return to the default CLI context, the command is cc on its own:

System:/RoutingTable/main> cc

The categories that require an initial cc command before object manipulation have a "/" character following their names when displayed by a show command. For example: RoutingTable/.

Specifying Multiple Property Values

Sometimes a command property may need multiple values. For example, some commands use the property AccountingServers and more than one value can be specified for this property. When specifying multiple values, they should be separated by a comma (,) character. For example, if three servers server1, server2, server3 need to be specified then the property assignment in the command would be:

Resetting to the Default Value

Where an optional object property has been changed and the administrator wants to set it back the default value, the special value <empty> can be entered. Consider the following example, where the property RouterID is set back to its default value:
System:/> add OSPFProcess Name=my_process1 RouterID=ip_ospf1
Added OSPFProcess OSPF
System:/> set OSPFProcess OSPF1 RouterID=<empty>
Updated OSPFProcess OSPF

Inserting into Rule Lists

Rule lists such as the IP rule set have an ordering which is important. When adding using the CLI add command, the default is to add a new rule to the end of a list. When placement at a particular position is crucial, the add command can include the Index= property as an option. Inserting at the first position in a list is specified with Index=1 in an add command, the second position with Index=2 and so on.

Referencing by Name

The naming of some objects is optional and is done with the Name= property in an add command. An object, such as an IP rule, will always have an Index value which indicates its position in the rule list but can optionally be allocated a name as well. Subsequent manipulation of such a rule can be done either by referring to it by its index, that is to say its list position, or by alternatively using the name assigned to it.

The cOS Stream CLI Reference Guide lists the options available for each object, including Name= and Index=.

To make reading configurations easier, it is strongly advised to always add unique a unique name to important objects in a configuration. For example, IP rules should always have an appropriate name specified so that their purpose can be immediately understood.

Where the Name property is optional, it can also have duplicates but this is never recommended and can be confusing.

Logging On to the CLI

When access to the CLI has been established to cOS Stream through the serial console with a console client or through an Ethernet interface with an SSH client, the administrator will need to log on to the system before being able to execute any CLI commands. This authentication step is needed to ensure that only trusted users can access the system, as well as providing user information for auditing purposes.

After SSH communication is established, cOS Stream will respond with a login prompt to pressing the Enter key. Type in the username the login prompt followed by the Enter key. Type the password followed by the Enter key again. After the first startup, cOS Stream will allow administrator login with the username admin and the password admin. This default password should be changed as soon as possible.

If accessing the CLI through a local console connection to the firewall, authentication will only be required if an AuthenticationProfile is explicitly associated with the console's COMPortAccess object.

After a successful logon, the CLI command prompt will appear:


The default welcome message will also be displayed directly after the logon. This SSH welcome message can be removed with the CLI command:

System:/> set RemoteManagement RemoteMgmtSSH ssh Banner=

Where ssh is the name of the RemoteMgmtSSH object. To reset the message:

System:/> set RemoteManagement RemoteMgmtSSH ssh Banner="Welcome!"

SSH Connection Timeout

When connecting to cOS Stream with SSH, there is a default inactivity timeout of 30 minutes. This may be inconvenient. To increase this timeout to a higher value, the following CLI command can be used:
System:/> set RemoteManagement RemoteMgmtSSH ssh

Changing the admin User Password

It is recommended to change the default password of the admin account from admin to something else as soon as possible after initial startup. User passwords can be any combination of characters and cannot be greater than 256 characters in length. It is recommended to use only printable characters.

To change the password, for example to my-password, the following CLI commands are used. First, change the current CLI context to be the relevant LocalUserDatabase object:

System:/> cc LocalUserDatabase AdminUsers

The password of the admin user can now be changed:

System:/LocalUserDatabase/AdminUsers> set User admin Password="my-password"

Finally, return to the default CLI context:

System:/LocalUserDatabase/AdminUsers> cc

Activating and Committing Changes

If any changes are made to the current configuration through the CLI, those changes will not become active until the following command is issued:
System:/> activate
To make the changes permanent, this should be immediately followed by:
System:/> commit
Uncommitted changes in CLI listings of configuration objects are indicated by a plus "+" or "*" symbol appearing to the left of the object.

If the commit command is not issued within 30 seconds (the default time period) then the activated changes are automatically undone and the old configuration restored.

Symbols Indicating Object Status

When configuration objects are displayed with a show command, a symbol to the left of the object's output indicates a change of status that has not yet been committed. Two symbols are mentioned above. The complete list is:

- means the object has been deleted.
o means the object has been disabled.
! means the object has errors.
+ means the object has been newly created.
* means the object has been modified.

Checking Configuration Integrity

After changing a configuration and before issuing the activate and commit commands, it is possible to explicitly check for any problems in a configuration using the command:
System:/> show -errors
This will cause cOS Stream to scan the configuration about to be activated and list any problems. A possible problem that might be found in this way is a reference to an IP object in the address book that does not exist in a restored configuration backup.

All the changes made to a configuration can be shown before activation with the command:

System:/> show -changes

Examining the Configuration Log

Major system events such as deploying a new configuration as well as system starts are recorded in the Configuration Log. This is examined using the cfglog command as shown in the following example:
System:/> cfglog -all
Notice  vsinit/Configure:1805  2011-06-17 13:53:40
  - Beginning system reconfigure. System starting.
Notice  vsinit/Configure:1805  2011-06-17 15:59:30
  - Beginning system reconfigure. Activating new configuration.

Notice  vsinit/Configure:2033  2011-06-17 15:59:31
  - Reconfigure completed successfully.
If the command is used on its own, without the -all option, only those major system events that occurred from and including the last system start or reconfigure are shown.

The output from this command also shows if cOS Stream is running in demonstration mode, without a valid license.

System Performance Commands

When viewing system performance, the administrator is typically concerned about the CPU utilization on the data plane since overly high CPU usage can affect packet forwarding performance. This is viewed by accessing the statistical values found under /system/cpu/ and this is done using either the CLI or an SNMP client.

Using the CLI, the statistics command provides a means to examine individual or groups of values. To see all values for system cpu usage, a wild card can be used as in this example with some typical output:

System:/> statistics -add /system/cpu/*
Name | 2013-03-05 13:36:11              Value  Unit
--------------------------------------  -----  ----
/system/cpu/control_plane_usage         1      %
/system/cpu/cpus/ControlPlane_01/usage  1      %
/system/cpu/cpus/FastPath_01/usage      3      %
/system/cpu/cpus/FastPath_02/usage      11     %
/system/cpu/cpus/FastPath_03/usage      5      %
/system/cpu/cpus/FastPath_04/usage      31     %
/system/cpu/cpus/SlowPath_01/usage      7      %
/system/cpu/cpus/SlowPath_02/usage      3      %
/system/cpu/cpus/SlowPath_03/usage      23     %
/system/cpu/cpus/SlowPath_04/usage      14     %
/system/cpu/fast_path_usage             50     %
/system/cpu/slow_path_usage             47     %

The above output comes from a hypothetical processor with four cores. For each core, the fast path and slow path usage is shown with the total for each path at the bottom. The Control Plane handles configuration management and logging functions. The Slow Path deals with the setup of new flows. The Fast Path deals with packet forwarding functions.

The memory command provides a snapshot of memory utilization.

System:/> memory
  Free:                                   121306 KB
  Total (In listing + free):              135892 KB

The bulk of the above memory usage output has been omitted except for the final two lines. These give a summary of overall memory utilization.

The top command provides details of CPU utilization by control processes only. An example with truncated output is shown below.

System:/> top

Load avg: 0.94, 0.51, 0.35
CPU usage: 24.8%  CPUs: 1
Name          Time   CPU(%)
------------  -----  ------
statd         14:04  6.3
mdpd          12:52  5.1
vsinit        07:17  2.7

The format of this CPU usage summary follows the convention of the same command in UNIX. The Load avg figures are for the last 1, 5 and 15 minutes respectively. This list is ordered by CPU usage, with the most active processes placed at the top.

Multiple Administration Logins

The Clavister NetShield Firewall allows more than one user from the Administrators group to be logged in at the same time and change the configuration simultaneously. A change made by one such user is visible immediately to all others.

For example, if one user deletes a configuration object then another user who tries to change it will receive a message to say that the operation is invalid.

Logging Out from the CLI

After finishing working with the CLI, it is recommended to log out in order to avoid letting anyone getting unauthorized access to the system. This is done with the command:
System:/> exit

Changing the Command View

There are a number of different command "views". Each view provides access to a different subset of all available CLI commands. The names of these views are listed below:

  • default
  • advanced
  • debug
  • all
  • service

The currently enabled views can be listed by using the cmdview command with no parameters. For example:

System:/> cmdview
Command view(s) enabled: default

In normal operation the Default view is sufficient. However, some situations may require the use of commands that should be used cautiously and for that reason they are hidden in alternate command "views".

For example, to turn on the Advanced view, enter the command:

System:/> cmdview advanced

Entering the Help command will now show that an additional set of commands are available to the administrator in addition to the default set. These additional commands include, for example, ruledb which provides a technically detailed listing of the current IP rules.

Similarly, an extra set of diagnostic commands becomes available with the command:

System:/> cmdview debug

The Debug, Default and Advanced command views all become available if the parameter all is used:

System:/> cmdview all

The original, default command view is returned by using the following command:

System:/> cmdview default

The service Command View

The service command view is a special command view that provides access to commands that should be used with extreme caution because they can cause harm to the configuration if used incorrectly. Normally, only qualified support personnel should have access to this view.

For this reason, the service view is protected by an additional one time password (OTP) which must be requested from Clavister support.

2.1.4. CLI Scripting

To allow the administrator to easily store and execute sets of CLI commands, the Clavister NetShield Firewall provides a feature called CLI scripting. A CLI script is a predefined sequence of CLI commands which can be executed after they are saved to a file and the file is then uploaded to the Clavister NetShield Firewall.

The steps for creating a CLI script are as follows:

  1. Create a text file with a text editor containing a sequential list of CLI commands, one per line.

    The recommended convention is for these files to use the file extension .sgs (Security Gateway Script).

  2. Upload the file to the Clavister NetShield Firewall using Secure Copy (SCP). Script files must be stored in a directory under the root called /scripts. SCP uploading is discussed in detail in Section 2.1.5, Secure Copy.

  3. Use the CLI command script -run to run the script file.

The CLI script command is the tool used for script management and execution. The complete syntax of the command is described in the cOS Stream CLI Reference Guide and specific examples of usage are detailed in the following sections. See also Section 2.1.3, The CLI in this manual.

[Note] Note

Uploaded CLI script files are not held in permanent memory and will disappear after system restarts.

All CLI Commands are Allowed in Scripts

There are no restrictions on which CLI commands can appear in a script. Any valid command can be used.

Executing Scripts

As mentioned above, the script -run command launches a named script file that has been previously uploaded to the Clavister NetShield Firewall. For example, to execute the script file my_script.sgs which has already been uploaded, the CLI command would be:
System:/> script -run my_script.sgs

Script Variables

A script file can contain any number of script variables which are called:

$1, $2, $3, $4......$n

The values substituted for these variable names are specified as a list at the end of the script -run command line. The number n in the variable name indicates the variable value's position in this list. $1 comes first, $2 comes second and so on.

[Note] Note: The symbol $0 is reserved

Notice that the name of the first variable is $1. The variable $0 is reserved and is always replaced before execution by the name of the script file itself.

For example, a script called my_script.sgs is to be executed. The IPv4 address is to replace all occurrences of $1 in the script file and the string if1 address is to replace all occurrences of $2.

The file my_script.sgs contains the single CLI command line:

add Address IPAddress if1_ip Address=$1 Comments=$2

To run this script file after uploading to cOS Stream with the given substitutions, the CLI command would be:

> script -run my_script.sgs "if1 address"

Notice how the "if1 address" parameter is enclosed in quotes so any spaces can be included.

When the script file runs, the replacement of the variables means that the command becomes:

add Address IPAddress if1_ip Address= Comments="if1 address"

Escaping Characters

Sometimes, there is a requirement to escape certain characters in a command so they are treated as ordinary characters when the command is executed. This is particularly true for the dollar-sign "$" character. Consider the string: "te$t". In order to have the dollar-sign treated as a normal character, it can be escaped in the normal way by using a back-slash "\" character. The string would become "te\$t" and the dollar-sign is no longer treated as special.

Script Validation and Command Ordering

CLI scripts are not, by default, validated and the ordering of the commands does not matter. There can be a reference to a configuration object at the beginning of a script which is only created at the end of the script. Although this might seem illogical, it is done to improve the readability of scripts. If something always has to be created before it is referred to then this can result in a confused and disjointed script file and in long scripts it is often preferable to group together similar CLI commands.

Error Handling

If an executing CLI script file encounters an error condition, the default behavior is for the script to terminate. This behavior can be overridden by using the -force option. To run a script file called my_script2.sgs in this way, the CLI command is:
System:/> script -run my_script2.sgs -force
If -force is used, the script will continue to execute even if errors are returned by a command in the script file.

Script Output

Any output from script execution will appear at the CLI console. Normally this output only consists of any error messages that occur during execution. To see the confirmation of each command completing, the -verbose option should be used:
System:/> script -run my_script2.sgs -verbose

Scripts Are Lost After Restart

When a script file is uploaded to the Clavister NetShield Firewall, it is kept in temporary memory. If the system restarts then any uploaded scripts will be lost from memory and must be uploaded again before they can run.

Listing Scripts

The script on its own, command without any parameters, lists all the scripts currently available and indicates the size of each script.
System:/> script
Name            Size
--------------  ----
my_script.sgs   8
my_script2.sgs  10
To list the content of a specific uploaded script file, for example my_script.sgs the command would be:
System:/> script -show my_script.sgs

Creating Scripts Automatically

When the same configuration objects needs to be copied between multiple Clavister NetShield Firewalls, then one way to do this with the CLI is to create a script file that creates the required objects and then upload to and run the same script on each device.

If an installation already has the objects configured that need to be copied, then running the script -create command on that installation provides a way to automatically create the required script file. This script file can then be downloaded to the local management workstation and then uploaded to and executed on other Clavister NetShield Firewalls to duplicate the objects.

For example, suppose the requirement is to create the same set of IPAddress objects on several Clavister NetShield Firewalls that already exist on a single firewall. The administrator would connect to the single firewall with the CLI and issue the command:

System:/> script -create Address IPAddress -filename=new_script.sgs

This creates a script file called new_script_sgs which contains all the CLI commands necessary to create all IPAddress objects in that firewall's configuration. The created file's contents might, for example, be:

add Address IPAddress if1_ip Address=
add IPAddress if1_net Address=
add IPAddress if1_br Address=
add IPAddress if1_dns1 Address=

Note that with the -create option, the output file must be specified with the -filename= parameter. This is the only time that -filename= is used.

The file new_script_sgs can then be downloaded with SCP to the local management workstation computer and then uploaded and executed on other Clavister NetShield Firewalls. The end result is that all units will have the same IPAddress objects in their address book.

In order to preserve any script files created in this way between system restarts, they must downloaded to the local storage of the management workstation using SCP and then uploaded again later.

[Note] Note: Automatically created scripts omit the object category

In the created script example above, adding an IP address is done with the command:

			add IPAddress...

This is instead of the usual way of qualifying the object with its group name:

			add Address IPAddress...

Both are valid forms of the command. If an object type can be uniquely identified with its name, its object category need not be specified. With automatically generated scripts, this is always the case. This shortened form can also be used when typing the entire command in a CLI console although tab completion will always include the object category.

Objects Excluded from Script Files

Certain aspects of a configuration which are platform dependent cannot have a script file entry created when using the -create option. This is true when the CLI node/object type in the script -create command is one of:

  • COMPortDevice
  • EthernetDevice

These node types are skipped when the script file is created and cOS Stream gives the message No objects of selected category or type.

[Tip] Tip: Listing commands at the console

To list the created CLI commands on the console instead of saving them to a file, leave out the -filename= parameter in the script -create command.

Commenting Script Files

Any line in a script file that begins with the # character is treated as a comment. For example:
# The following line defines the if1 IPv4 address
add Address IPAddress if1_ip Address=

Scripts Running Other Scripts

It is possible for one script to run another script. For example, the script my_script.sgs could contain the line:
		script -run my_script2.sgs
cOS Stream allows the script file my_script2.sgs to execute another script file and so on. The maximum depth of this script nesting is 5 levels.

2.1.5. Secure Copy

To upload and download files to or from the Clavister NetShield Firewall, the Secure Copy (SCP) protocol can be used. SCP is based on the SSH protocol and many freely available SCP clients exist for almost all platforms. The command line examples given below are based on the most common command format found with SCP client software. Some SCP clients might use different syntax.

SCP Command Format

SCP command syntax is straightforward for most console based clients. The basic command used here is scp followed by the source and destination for the file transfer.

Upload is performed with the command:

> scp <local_filename> <destination_firewall>

Download is done with the command:

> scp <source_firewall> <local_filename>

The source or destination Clavister NetShield Firewall is specified using the format:


For example:


The <user_name> must be a defined user belonging to the administrator user group.

[Note] Note: SCP examples do not show the password prompt

SCP will normally prompt for the user password after the command line but that prompt is not shown in the examples given in this document.

Examples of SCP Uploading and Downloading

In some cases, a file is located in the system root. In other cases, it is located within a particular folder. All backup files are located in the root folder.

  • Uploading/Downloading Backup Files

    If an administrator username is admin1 and the IPv4 address of the Clavister NetShield Firewall is then to upload a configuration backup file called config.bkp from the local disk, the SCP command would be:

    > scp config.bkp admin1@

    To download a configuration backup to the current local directory, the command would be:

    > scp admin1@ .

  • Uploading Certificate Files

    The following command lines show how a typical SCP utility might upload a host certificate consisting of the two files called cert-1.cer and cert-1.key to a firewall which has the management IP address

     > scp C:\cert-1.cer admin@

     > scp C:\cert-1.key admin@

    In each case, the uploaded file will retain its original file name.

    Uploaded certificate files are stored in volatile memory and must be associated with a Certificate object to become a non-volatile part of the configuration. Doing this is described in Section 16.1, Configuring Certificates.

Using Wildcards with SCP

The use of the wildcard asterisk "*" character with SCP is supported. For example, to download all the files with a filetype of .MIB, the following command can be used:
 > scp admin@*.mib .
To download all the downloadable files:
 > scp admin@* .
Wildcards can also be used when uploading. For example, to upload all the backup files in the current directory:
 > scp *.bkp admin@

2.1.6. RADIUS Management Authentication

For system management tasks in the default configuration, the administrator logs in to the CLI via SSH using a username and password that are checked against the credentials stored in a local database.

An alternative to using a local database is to have cOS Stream perform authentication of the entered credentials against an external RADIUS server. This is done by changing the properties of the AuthenticationProfile object assigned to the RemoteManagementSSH object used for CLI access via SSH. The option exists to use either a local database or a RADIUS server as the authentication source, or a combination of both. If a combination is selected, the administrator can then select which source to try first.

[Caution] Caution: RADIUS is ignored with public key authentication

If cOS Stream is able to use public key authentication when an SSH client connects then RADIUS authentication will not also be attempted even though it might be configured in an associated AuthenticationProfile object.

Configuration Steps

Configuring the AuthenticationProfile for RADIUS authentication consists of the following steps:

  • If only RADIUS is to be used then set the LocalUserDB property to have no value:


    Otherwise, leave this property set to be the database that will be used with RADIUS authentication.

  • Set the RemoteServer property of the AuthenticationProfile object to be a RadiusServer object that already exists in the configuration:


    More than one server can be specified:


    See Section 17.2, RADIUS Authentication for how to define a RadiusServer object.

  • Set the RemoteLoadBalance property of the AuthenticationProfile object to specify how to behave if more than one RADIUS server is specified for the RemoteServer property. The available options are the following:

    1. None - This is the default value and means that the first server in a list will always be tried first. If it does not respond then the second will be tried, and so on. This choice ensures that the first server is always the preferred one and any other in the list are backups.

    2. RoundRobin - The first query goes to the first server in the list, the next query goes to next server, and so on until the list is exhausted and the next query goes to the first server in the list again. This option provides the best balancing of the load across all servers.

    3. TryAll - The authentication request is sent to all RADIUS servers. If any one of the servers replies and authenticates the user then other replies are ignored. This option can provide the fastest authentication since the fastest server in the list of servers will respond first.

  • Select the AuthOrder property to be one of the following:

    1. LocalLast - The local database is only queried if none of the configured RADIUS servers responds to an authentication request. If no RADIUS servers are configured then only the local database is used. This is the default value of the property.

    2. LocalFirst - The login credentials are first looked up in the local user database. If not found in the local database, the configured RADIUS servers are queried.

RADIUS Servers Must Be Correctly Configured

For RADIUS authentication to work, any RADIUS servers being used must be correctly configured to return the group membership of a user as a vendor specific attribute. The Clavister specific settings for this attribute are as follows:

  • Vendor-ID - 5089.

  • Vendor-assigned attribute number - 1.

  • Attribute format - String.

  • Attribute value - Clavister-User-Group.

The Login Message Changes for a Group Mismatch

Once set up, the login actions taken by the administrator are the same as with non-RADIUS authentication and there is usually no indication in the CLI that RADIUS is being used for authentication.

However, there is one exception. When the user credentials are correct but the group name returned by the RADIUS server does not match a valid group (it is not Administrators or Auditors) the CLI will display the following message:

	Access denied.

Generated Log Event Messages

Log messages indicate a successful or unsuccessful login by the administrator. With RADIUS management authentication, all the related messages belong to the AUTHSYS log category and can include the following parameter values:

  • The event parameter indicates the type of event.

  • The usergroups parameter is the group membership allowed by the authenticating RADIUS server.

  • The user parameter is the username used for login.

  • The userdb parameter will show the name of the LocalUserDatabase object or the RadiusServer object being used for authentication.

  • The ip parameter is the IP of the client computer that the user is trying to login from.

The types of log event messages that cOS Stream might generate are as follows:

  • Successful RADIUS Authentication

    A successful login using a RADIUS server with the user being part of the Administrators group.

 AUTHSYS: prio=notice id=00000 event=user_logged_in
 userid=33 user=jdoe ip= profile=MgmtAuthProfile agent=Basic
 userdb=RadiusServer1 usergroups="Administrators" action=none
  • Successful Local Database Authentication

    A successful login using the local database called AdminUsers with the user being part of the Administrators group. In this case, the usedb parameter will change.

AUTHSYS: prio=notice id=00000 event=user_logged_in
 userid=32 user=admin ip= profile=MgmtAuthProfile agent=Basic
 userdb=AdminUsers usergroups="Administrators" action=none
  • Insufficient Access Rights

    The user entered a correct username and password but the group name returned by the RADIUS server was neither Administrators or Auditors.

 AUTHSYS: prio=warning id=00000 event=received_radius_access-reject_message
 userid=33 user=jdoe ip= profile=MgmtAuthProfile
 agent=Basic userdb=RadiusServer1 action=none
  • Servers Unreachable

    All configured RADIUS servers were unreachable and a timeout condition occurred.

 AUTHSYS: prio=warning id=00000 event=authentication_source_did_not_respond
 userid=33 user=jdoe ip= profile=MgmtAuthProfile
 agent=Basic userdb=RadiusServer1 action=none

Use the Local Console as a Fallback Option

It is possible that the administrator could be locked out from logging on via the CLI over SSH because a RADIUS server will not authenticate the entered credentials and authentication using a local database is not enabled either. In such cases, the local console port on the Clavister NetShield Firewall can still be used for management access. However, if the password has been set for the local console then that password must still be given to get CLI management access (note that the local console password is totally separate from other management passwords).

Example 2.1. Enabling RADIUS Management Authentication

This example will change the current default rule for CLI SSH management access so that authentication is only performed using two RADIUS servers. It is assumed that the RADIUS server objects are already defined in the configuration and have the names my_radius_auth1 and my_radius_auth2. The authentication load will be shared between the two servers.

The authentication order will be set to LocalLast. The local database will never be used so it will be set to be null. Multiple logins will not be allowed.

Command-Line Interface

First, create an AuthenticationProfile object:

System:/> add AuthenticationProfile my_mgmt_auth_profile

Now, use this profile with the default RemoteMgmtSSH object:

System:/> set RemoteManagement RemoteMgmtSSH RemoteMgmtSSH

2.1.7. SNMP Monitoring


Simple Network Management Protocol (SNMP) is a standardized protocol for management of network devices. Any SNMP compliant client can connect to a network device which supports the SNMP protocol to query it for system status. cOS Stream allows such access by an SNMP client and a large range of statistical values to be queried. By default, SNMP access is not permitted and a suitable remote management rule must be configured to allow it.

Supported SNMP Versions

cOS Stream supports the following SNMP versions:

  • Version 1.
  • Version 2c.
  • Version 3 (SNMPv3).

This section discussed overall MIB file support and setting up version 1 or 2c access. SNMPv3 access is described in Section 2.1.8, SNMPv3 Polling.

Supported Request Operations

These are the supported SNMP request operations:

  • GET BULK REQUEST (SNMP version 2c and 3 only)

MIB Files

A Management Information Base (MIB) file is a database, in the form of a text file, which defines the parameters on a network device that an SNMP client can make queries for.

An SNMP client connecting to cOS Stream can use two different types of MIB files:

  • The Clavister provided MIB files.

    These are CLAVISTER-STREAM.mib and CLAVISTER-SMI.mib. These are needed for accessing the proprietary Clavister firewall statistical values.

  • Supported Standard MIBs.

    cOS Stream supports a subset of the statistical values defined in standard MIBs to provide a common set of values applicable across different network equipment manufacturers. These MIB files are freely available on the Internet. For details on what is supported, see the separate Statistics Reference Guide.

Downloading MIB Files

The Clavister MIB files are included in cOS Stream itself in its top-level directory and can be extracted to a management computer's local disk using Secure Copy (SCP). For example, a typical management console command to download both .mib files via the admin user might be the following:
> scp admin@*.mib .

The selected MIB file should be transferred to the hard disk of the workstation that will run the SNMP client so it can be imported by the client software. When the SNMP client runs, the MIB files are read and they tell the client which values can be queried.

MIB Entries

Each entry in the MIB includes a textual explanation of what the value is and a complete list is not reproduced in this guide. A typical MIB file entry for the total number of packets transmitted by an interface appears as follows:
    SYNTAX      Counter32
    MAX-ACCESS  read-only
    STATUS      current
        "Total number of packets transmitted by the interface"
    ::= { clvIfStatsEntry 10 }

All statistical values that can be accessed by SNMP are listed in the separate Statistics Reference Guide which provides all available information for each. This includes the description of the values together with the MIB OID, MIB name and MIB type.

Setting Up Version 1 or 2c SNMP Access

Version 1 or 2c SNMP access is enabled by creating RemoteMgmtSNMP rules with filters matching traffic for the SNMP requests that should be allowed. This is done using these filtering properties:

  • SourceInterface - The interface on which SNMP requests will arrive.

  • SourceNetwork - The IP address or network from which SNMP requests will come.

To ensure that the correct RemoteMgmtSNMP object triggers, different objects should not use overlapping filters. Instead, each object should specify a unique source interface and network combination. In addition, the source interface and network filters of RemoteMgmtSNMP and RemoteMgmtSNMP3 objects should also not overlap.

In addition to the filter parameters above, each RemoteMgmtSNMP rule also needs to have these two properties configured:

  • Name - A symbolic name for the rule.

  • GetCommunity - The SNMP community string to use for traffic matching this particular RemoteMgmtSNMP rule.

Other optional properties for the RemoteMgmtSNMP rule can be found in the separate CLI Reference Guide.

The Community String

Both SNMP Versions 1 and 2c use the SNMP community string as a way for the client and server to "authenticate" each other. It should however be noted that this provides no security as the string is transmitted in plain text. Instead, it limits the chances of clients accidentally connecting to the wrong server. For this purpose, it is advised to choose a community string that identifies the particular firewall. That way, the risk that a client accidentally connects to the IP of the wrong firewall is minimized.

Example 2.2. Enabling SNMP Version 1 or 2c Monitoring

This example enables SNMP access through the internal lan interface from the network mgmt-net using the community string "my-community-string".

Command-Line Interface

System:/> add RemoteManagement RemoteMgmtSNMP my_snmp

IP Rules are not Required with SNMP

Any type of SNMP access does not require any IP rules to be defined to allow SNMP related traffic to flow. Such traffic is automatically allowed by cOS Stream.

Security Concerns with Version 1 and 2c

It should be noted that SNMP Version 1 or 2c communication has no built-in security. All request and response data, including the community string, will be sent as plain text over a network. This is clearly insecure if a remote client is communicating over the public Internet. If this is the case, it is advisable to have remote access take place over an encrypted VPN tunnel or similarly secure means of communication.

However, SNMPv3 polling can provide both encryption and authentication and this is described in the next section.

2.1.8. SNMPv3 Polling

cOS Stream supports SNMPv3 polling by an external SNMPv3 client with an IPv4 or IPv6 address. SNMPv3 differs from the earlier SNMP versions in that it can provide both encryption and/or authentication.

Setting Up SNMPv3 Polling

The SNMPv3 polling feature is enabled by creating one or more RemoteMgmtSNMP3 objects in the firewall configuration. The mandatory properties for this object type will filter the incoming client requests and they are the following:

  • SourceInterface - The interface on which SNMPv3 client requests will arrive.

  • SourceNetwork - The IP address or network from which client SNMPv3 requests will come.

  • LocalUserDB - The local database to use for authentication. This must be specified, regardless of the security options used. This is because the SNMPv3 client must specify a user which is present in a local user database. The user does not need administrator or auditor privileges.

    Note that the passwords used for SNMPv3 authentication must be at least 8 characters long.

  • PrivacyPassword - This must be specified if the SecurityLevel is not set and left at the default value of AuthPriv. This value must be at least 8 characters long.

All the available properties are listed under the RemoteMgmtSNMP3 object entry in the separate CLI Reference Guide.

To ensure that the correct RemoteMgmtSNMP3 object triggers, different objects should not use overlapping filters. Instead, each object should specify a unique source interface and network combination. In addition, the source interface and network filters of RemoteMgmtSNMP and RemoteMgmtSNMP3 objects should also not overlap.

SecurityLevel Property Options

The SecurityLevel property of a RemoteMgmtSNMP3 object determines the type of security used. One of the following values can be chosen:

  • AuthPriv - This is the default setting. It enables both authentication and encryption.

  • AuthNoPriv - This enables authentication using the local user database but disables encryption.

  • NoAuthNoPriv - This disables both authentication and encryption.

SNMPv3 Encryption

When enabled, the AES-CFB algorithm is used by cOS Stream for encryption of SNMPv3 traffic and the value of the PrivacyPassword property is used as the key.

SNMPv3 Authentication

When enabled, authentication is always performed against the local user database specified by the LocalUserDatabase property. The password is not sent in clear text but instead a cryptographic hash of the password is sent.

By default, the algorithm used for creating the hash of the password is HMAC-SHA1-96. This can be changed by setting the property AuthenticationMethod to the alternative value of HMAC-MD5-96. However, HMAC-SHA1-96 is the recommended setting for strong security.

Note that SNMPv3 polling with authentication enabled will cease to function if the reboot counter has reached its maximum value. The reboot counter and how it is reset is explained further in Section 20.5, SNMP Traps.

Multiple Clients Are Allowed

A single RemoteMgmtSNMP3 object will allow multiple SNMPv3 clients to connect at the same time. Similarly, multiple RemoteMgmtSNMP3 objects with different interface and source network property values will allow multiple SNMPv3 clients to connect at the same time.

However, it is important that the SourceNetwork property for multiple RemoteMgmtSNMP3 objects do not have IP addresses assigned to them which overlap. If overlapping occurs, the behavior will be unpredictable.

Example 2.3. Setting Up SNMPv3 Polling

This example creates a RemoteMgmtSNMP3 object to allow SNMPv3 polling of the cOS Stream from an external SNMPv3 client on the network if1_net assigned to the if1 interface. A request limit will be imposed of 20 SNMPv3 client requests per second.

The user will be authenticated against the local database AdminUsers. The password mysecretpassword needs to be specified because the default value of the SecurityLevel property is AuthPriv.

Command-Line Interface

System:/> add RemoteManagement RemoteMgmtSNMP3 my-snmp3-rule

2.2. Date and Time

2.2.1. Overview

Correctly setting the date and time is important for cOS Stream to operate properly. For example, certificates used in certificate based VPN tunnels depend on the system clock being accurately set.

In addition, log messages are tagged with time-stamps in order to indicate when a specific event occurred. Not only does this assume a working clock, but also that the clock is correctly synchronized with other equipment in the network.

The administrator can set the date and time manually and this is recommended when a new system installation is started for the first time.

The Local System Time

For access to the current date and time, cOS Stream makes use of the local hardware real-time hardware clock. Depending on the platform, this clock can be equipped with a battery backup so that a loss of power will not affect the clock.

The system time is set with the following CLI command:

System:/> time -set YYYY-mm-DD HH:MM:SS

Where YYYY-mm-DD HH:MM:SS is the new date and time. Note that the date order is year, then month and then day.

Example 2.4. Setting the Current Date and Time

To adjust the current date and time to 9:25 in the morning on April 27th, 2015 :

Command-Line Interface

System:/> time -set 2015-04-27 09:25:00

[Note] Note: A reconfigure is not required

A new date and time will be applied by cOS Stream as soon as it is set. There is no requirement to reconfigure or restart the system.

Time Zones

The world is divided up into a number of time zones with Coordinated Universal Time (abbreviated as UTC and interchangeable with GMT) as the base time zone. All other time zones going east and west are taken as being UTC plus or minus a number of hours (either whole or fractional). All locations counted as being inside a given time zone will then have the same local time and this will be one of the integer offsets from UTC.

The DateTime object property TimeZone must be set to a value which reflects the time zone where the Clavister NetShield Firewall is physically located.

Example 2.5. Setting the Time Zone

To modify the time zone to be UTC plus 1 hour (Central European Time), the CLI would be the following:

Command-Line Interface

System:/> set DateTime Timezone=UTC+01:00

Note that CLI tab completion can present a list of all time zone value options.

Daylight Saving Time

Many regions follow Daylight Saving Time (DST) (or "Summer-time" as it is called in some countries) and this means clocks are advanced for the summer period. Unfortunately, the principles regulating DST vary from country to country, and in some cases there can be variations within the same country.

There is no specific setting for enabling DST in cOS Stream. Instead, DST is implicitly enabled by selecting the appropriate value for the Timezone property. For example, UTC+01:00 is the value for UTC plus one hour. However, UTC+01:00-EU is the value for UTC plus one hour which includes daylight saving. Tab completion can be used to identify all available values in the CLI.

Example 2.6. Enabling the Time Zone with DST

To modify the system time zone to be UTC plus 1 hour and to include the daylight saving applicable for the European union, the CLI would be the following:

Command-Line Interface

System:/> set DateTime Timezone=UTC+01:00-EU
[Note] Note: Switching off DST

Even though DST is implicitly enabled through the time zone value specified, it is still possible to turn it off by disabling the DSTAutoAdjust property of the Timezone object. The same property can be used to then re-enable it. This might be done, for example, for testing purposes.

2.2.2. Time Servers

The system clock which cOS Stream uses can sometimes become fast or slow after a period of operation. This is normal behavior in most network and computer equipment and is solved by utilizing Time Servers.

cOS Stream is able to adjust the clock automatically based on information received from one or more time servers which provide a highly accurate time, usually using atomic clocks. Using time servers is highly recommended as it ensures the system will have its date and time aligned with other network devices.

For hardware platforms without battery backup of the system clock, using time servers is a useful way to automatically set the correct time after initial startup.

The SNTP Protocol

Time Synchronization Protocols are standardized methods for retrieving time information from external time servers. The Clavister NetShield Firewall supports the Simple Network Time Protocol (SNTP) as defined by RFC 5905 (SNTPv4).

Configuring Time Servers

More than one time servers can be configured to query for time information. By using more than a single server, situations where an unreachable server causes the time synchronization process to fail can be prevented. cOS Stream always queries all configured servers and then computes an average time based on all responses. The configure servers, the steps are:

  • Set the TimeSyncEnable option on the DateTime object to be Yes.

  • Add each configured server as a new TimeServer object to the DateTime object.

Example 2.7. Enabling Time Synchronization using SNTP

In this example, time synchronization will be enabled and two time servers will be configured with IPv4 addresses and The created TimeServer objects will be given the names my_tsrv1 and my_tsrv2.

Command-Line Interface

First, change the context to be DateTime:

System:/> cc DateTime

Next, add a TimeServer object with the name my_tsrv1:

System:/DateTime> add TimeServer IP= Name=my_tsrv1

Now add the second server:

System:/DateTime> add TimeServer IP= Name=my_tsrv2

Then return to the default, root context:

System:/DateTime> cc

Finally, activate and commit the configuration changes.

Manually Triggering Time Synchronization

If there is a need to manually force the system clock to be updated then this can be done with the time -sync CLI command.

Example 2.8. Manually Triggering Time Synchronization

Time synchronization can be triggered from the CLI.

Command-Line Interface

System:/> time -sync

Time synchronization requested


Maximum Time Adjustment

To avoid situations where a faulty Time Server causes the clock to be updated with a extremely inaccurate time, a Maximum Adjustment value (in seconds) can be set. If the difference between the current system time and the time received from a Time Server is greater than this Maximum Adjustment value, then the Time Server response will be discarded.

For example, assume that the maximum adjustment value is set to 60 seconds and the current system time is 16:42:35. If a Time Server responds with a time of 16:43:38 then the difference is 63 seconds. This is greater than the maximum adjustment value so no update occurs for this response. The default value for the maximum adjustment is 600 seconds (ten minutes).

Example 2.9. Modifying the Maximum Adjustment Value

Command-Line Interface

System:/> set DateTime TimeSyncMaxAdjust=4000

Forcing Synchronization

Sometimes it might be necessary to override the maximum adjustment. For example, if time synchronization has just been enabled and the initial time difference is greater than the maximum adjust value. It is then possible to manually force a synchronization and disregard the maximum adjustment parameter.

Example 2.10. Forcing Time Synchronization

This example demonstrates how to force time synchronization, overriding the maximum adjustment setting.

Command-Line Interface

System:/> time -sync -force

The Time Synchronization Interval

The interval between each synchronization attempt can be adjusted if needed. By default, this value is 86,400 seconds (1 day), meaning that the time synchronization process is executed once in a 24 hour period.

Example 2.11. Changing the Time Synchronization Interval

Command-Line Interface

System:/> set DateTime TimeSyncInterval=3600

2.3. Licensing


To use the Clavister NetShield Firewall in a live environment, a license file must be deployed to the Clavister NetShield Firewall and associated with the configuration. The purpose of the license file is to define the capabilities and limitations that an installation has.

Demo Mode

Without a valid license, cOS Stream operates in Demo Mode. In this mode, cOS Stream has full functionality but will only operate for a limited amount of time before going into lockdown mode. The amount of time that demo mode lasts can vary, depending on the type of software distribution. The total time period allowed can be seen in the output from the CLI license command (with no options) as the value for the Demo parameter (this parameter has a value of <empty> with a valid license).

While cOS Stream operates in demo mode, the following will be true:

  • On initial startup, the console will indicate that demo mode is active and how much time is remaining before lockdown occurs.

  • A message will then appear in the CLI console after approximately 50%, 75% and 87.5% of the demo period has passed and this will indicate how much time remains.

  • A log event message called Remaining demo period will be periodically generated indicating that demo mode is active. The time remaining is shown in the explanation field of the log message.

  • The amount of time remaining before lockdown can be displayed at any time using the CLI command about.

  • When the demo period expires, the following message will be printed on the console:

    	Demo license timed out. System entering lockdown.

    If the about command is now entered, it will show the following message:

    	No license installed – DEMO mode expired

After the demo mode time period has expired, cOS Stream goes into lockdown mode so normal operation ends and only the following becomes possible:

  • The only access permitted to cOS Stream is management access by an administrator.

  • In addition to management access using the CLI, access is also possible using SCP and SNMP.

  • cOS Stream can be configured, including uploading and activating a license.

Log event and console messages indicate when lockdown mode goes into effect and when it ends.

License Files

A license file is a plain text file that defines all the capabilities allowed by the license plus a digital signature to ensure the file cannot be altered. The file can be opened and read in a normal text editor. It is generated and supplied by Clavister.

Associating Licenses

Associating a license file with cOS Stream is a two step process:

Step 1: Upload a License File

First, upload a license file to cOS Stream using SCP. More than one license can be uploaded but they must have different names. Files with the same name will overwrite each other. All license files will be lost after a system reboot except the currently activated license.

For example, the SCP command under Linux to upload a file called my_license.lic to a firewall called fw_name might be:

> scp license.lic user@fw_name:my_license.lic

Under windows the SCP upload would be done using an appropriate utility with SCP support.

Step 2: Activate the License File

Assuming that a license file called my_license.lic has already been uploaded using SCP, the CLI command to activate this license is:

System:/> license activate my_license.lic

This command causes a reconfigure to take place. If the reconfigure is successful then the capabilities of the new license will come into effect. If the reconfigure is not successful, cOS Stream will revert to its previous state which will either be to using the previously activated license or to lockdown mode.

Managing License Files

As stated above, a number of license files can be present in local temporary storage, however, only one can be active at any time. The CLI provides the license command to manage the active license. The options for this command are:

  • Activate

    As discussed above, the activate option causes a previously uploaded license to become the current license associated with cOS Stream. A copy of the license selected is made by cOS Stream and saved in non-volatile storage. It is this copy that is used during system operation and it is not lost after a system reboot.

  • Remove

    This option deactivates the currently activated license file:

    System:/> license remove

    After deactivation, cOS Stream enters lockdown mode. Previously uploaded license files are unaffected by this command and remain available for activation (although they will be lost after a system reboot).

  • No options

    If the license command is used without any options, it provides a summary of the currently activated license's properties. Some typical output from this command is shown below:

    System:/> license
               Property  Value
    -------------------  -------------------
               IsValid:  Yes
                    OS:  1
          RegisteredTo:  Clavister
       RegistrationKey:  0324-5761-7527-1384
                 OEMId:  0
          DisplayModel:  Generic
      RegistrationDate:  2018-04-27 00:00:00
          LastModified:  2019-05-24 10:24:46
            IssuedDate:  2019-05-24 00:00:00
    UpgradesValidUntil:  2021-04-27 00:00:00
            MACAddress:  01-91-FB-1A-A0-30
            IKETunnels:  2000
                   GTP:  Yes
                   BGP:  Yes
                  OSPF:  Yes
               CGNAT64:  Yes
                DetNAT:  No
              IPSUntil:  2021-04-27 00:00:00
                  Demo:  <empty>
           SiteLicense:  <empty>

    The MAC address in a valid license must match one of cOS Stream's Ethernet interfaces.

License Validity Expiration Behavior

There is no true expiration date for licenses where the firewall stops working. Instead, there is a Upgrades Valid Until date. When this date has passed, cOS Stream will continue to function but software upgrades will not be available.

However, note that after the upgrade validity date has passed, the IPS and Application control subsystems will no longer function. If enabled, they will no longer scan traffic and they will also not block any traffic.

Binding to a MAC Address

When a license file is created it is bound to the MAC address specified in the license. This means that the license is only valid if cOS Stream can detect that the MAC address of one of the hardware's Ethernet addresses is the same as the MAC address of the license.

For this reason, a license is not portable between different hardware units. If hardware is replaced so that the license Ethernet MAC address is no longer present then a new license will need to be generated.

The Current License is a Configuration Object

The current license for a configuration is also a configuration object called License and this can be accesses through the CLI. The following command will give the same output as the license command:
System:/> show License

2.4. Backup and Restore

The administrator has the ability to take a snapshot of a Clavister NetShield Firewall system at a given point in time and restore it if necessary. Backups can be one of the following two types:

  • Configuration Backup

    This is a backup of the entire current configuration but does not include a copy of the system software itself. This backup is the default type. Restoring this backup will only restore the original configuration.

  • System Backup

    This is a backup of the current configuration and includes a copy of the system software itself. This requires using the -system option when creating the backup. When the backup is restored, the current software version will be replaced by the version in the backup.

Creating a Backup

Backups are created in two steps:

  • Step 1:

    A backup is first created as a single file in local volatile memory. A configuration only backup is created with the following CLI command:

    System:/> backup -create

    Alternatively, a full system backup consisting of the current configuration as well as the current software version is created with the command:

    System:/> backup -create -system

    The file created will be placed in the root folder and it will have the default name config-YYYYMMDD.bkp where YYYYMMDD indicates the current date.

    If a specific filename is desired for the backup file then the command form is:

    System:/> backup -create <filename>

  • Step 2:

    Once created, backup files are transferred to an external computer by downloading the files from the Clavister NetShield Firewall using SCP (Secure Copy). As stated above, all backup files are saved in the root folder.

    It is important to note which Clavister NetShield Firewall hardware the backup file came from so that it can be restored to a processor that has the same logical interface names.

    SCP usage is described further in Section 2.1.5, Secure Copy.

[Note] Note: Backup files are temporary

Any backup files created are not held in permanent memory and will disappear after system restarts.

Restoring a Backup

Restoring a backup is also a two step process:

  • Step 1:

    Use SCP to upload the backup file to the root folder of the target Clavister NetShield Firewall. For example:

    > scp config.bkp admin1@

    SCP usage is described further in Section 2.1.5, Secure Copy.

  • Step 2:

    To make the uploaded configuration the current configuration, the following CLI command is used:

    System:/> backup -restore <filename>

    Where <filename> is the name of the file in cOS Stream's root folder.

    To list all the backup files, use the CLI command:

    System:/> backup -list

    When a restore begins, the selected file is validated before it replaces the current configuration. For the new configuration to become active, the CLI commands Activate followed by Commit are required after the restore is complete.

[Caution] Caution: Do not perform a restore with live traffic

A restore operation should not be attempted with live traffic flowing through the firewall. Any traffic flows will be disrupted.

Reverting to a Backup

After performing a restore operation, cOS Stream retains a copy of the original configuration (that is to say, the configuration that the restore replaced). This copy can be reactivated at any time with the CLI command:
System:/> backup -revert
A revert operation always uses the configuration in effect previous to the last restore if there was one. If no restore has been performed, a revert operation will have no effect.

Restoring to a Dissimilar Processor

It is important to restore a backup to a configuration which has the same interface names as the original hardware from which the backup was taken. The reason for this is that the backup may refer to logical interface names that do not exist on the new hardware.

Interface ID Collisions

Every interface in a backup file has a unique ID assigned to it which is based on the ordering of the interface in the system. In some unusual circumstances, the IDs of the interfaces in a backup might not agree with the IDs of the physical system. This might occur if an interface was deleted from a configuration and then later added back in.

When such a mismatched backup is restored, the restore will fail with a message that includes the line:

In VLAN vl: Interface ID change of 'vl'(nnnn->mmmm) is not supported.

Where nnnn and mmmm are the conflicting IDs. To force the restore so these ID mismatches are ignored, use the command:

System:/> backup -restore <filename>.pkg -reboot

This forces the system to reboot and then use the backup file.

Resetting to Factory Defaults

A special case of backup command usage exists for restoring the current configuration to the original factory default configuration:
System:/> backup -factoryreset

The following points should be noted about this operation:

  • Since the default configuration will be restored, this should only be done via an SSH client which is connected to the default management interface using the default management IP address or from a console which is connected to the firewall's local console interface. Otherwise, connection to the CLI will be lost after the command is issued.

  • The current configuration will be lost after a reset and cannot be recovered. For this reason, this operation should be used with caution.

    To remind the administrator that the command is irreversible, a prompt appears to ask if cOS Stream should proceed:

    System:/> backup -factoryreset
    This will reset the current configuration to factory default
    and reboot the system.
    This change is not reversible.
    Are you sure you want to continue? [yes/no]: yes
    Resetting configuration to factory default...
    Reset configuration to factory default successfully.
    The system is going down NOW!

    In CLI scripts, the -force option must be used to ignore any prompts since a script cannot respond to a prompt.

If both the configuration and the current version of the software are to be restored to the factory defaults, the CLI command becomes:

System:/> backup -factoryreset -system

This will similarly reboot the system once the reset process has completed. All upgrades of cOS Stream performed since hardware delivery will be lost as well as the current configuration.

Factory Resets on Clavister Hardware Products

Where cOS Stream is running on a Clavister hardware product, it is possible to reset to factory defaults by keeping a switch on the hardware appliance depressed for a given length of time. This procedure is fully explaining in the factory reset section in the Getting Started Guide for the relevant hardware guide.

An additional way to perform a factory reset on Clavister hardware products is to use the hardware's boot menu. This menu is entering by repeatedly pressing the Esc key at the local console as the hardware powers up. This menu is explained further in a dedicated section of the Getting Started Guide for the relevant hardware product.

2.5. Upgrading Software

From time to time Clavister will release new cOS Stream software versions. All version releases are provided in the form of a single file with the filetype .upg and a filename indicating the target platform and version number. All releases are installed in the same way.

The following should be noted about new releases:

  • Notifications about new releases is sent by email to registered MyClavister users. Email preferences should be set accordingly in the relevant MyClavister account.

  • It is recommended to always upgrade to the latest cOS Stream release.

  • The .upg file for a specific upgrade should be downloaded from the relevant MyClavister account before beginning the upgrade process.

  • Upgrades should be performed during a maintenance window when there is no live traffic. The upgrade process will disrupt any traffic flowing through the NetShield firewall.

  • As a precaution, it is recommended to take a full system backup before beginning the upgrade process.

  • The progress of the upgrade process will be displayed on the cOS Stream console, as described later in this section.

  • If the upgrade process fails then cOS Stream will automatically roll back any changes so the system will be unchanged.

  • Success of an upgrade will be displayed in the console at the end of the process but it can be reconfirmed manually using the about command.

Applying a .upg Upgrade File

Applying an upgrade file requires the following steps:

  • Upload the relevant .upg file to firewall disk storage using SCP.

  • Use the CLI upgrade command to apply the upgrade.

  • cOS Stream verifies the checksum and signature of the upgrade file and then installs it.

For a high availability (HA) cluster, the above procedure is repeated on each cluster node but with some extra considerations. This is described further in Section 22.4, Upgrading an HA Cluster.

The Upgrade Command

The CLI upgrade command is used to install an already uploaded .upg file. For example, if the file uploaded with SCP is called cos_stream_3_30_01.upg, the upgrade command with example output would be:
System:/> upgrade cos_stream_3_30_01.upg

This will upgrade the system using cos_stream_3_30_01.upg
Are you sure you want to continue? [yes/no]: yes
|0%Validating                     |50%Extracting                   |100%
The CLI displays a progress bar consisting of lines which will gradually increase to 100% completion.

The following should be noted:

  • After successful installation, the system will automatically restart itself.

  • If the system fails to configure with the new software version, the old version is automatically restored and the system is restarted.

  • When running a CLI script, the -force option should be used to suppress the continuation question. The full CLI command would be:

    System:/> upgrade <filename> -force

Managing Package Files

To check which .upg files have been uploaded and are available to be used with an upgrade, the following command is used:
System:/> upgrade -list
Wildcards cannot be used with the -list option.

To delete a package file, the following command can be used:

System:/> upgrade -delete <filename>

With the -delete option, the asterisk wildcard character ("*") can be used to represent filenames. For example, the delete all files:

System:/> upgrade -delete *.upg

2.6. Crashdumps

In the event of a serious system malfunction, cOS Stream generates a Crashdump and stores it in non-volatile system memory as a set of files. The files generated by a crashdump consist of critical data that can assist in troubleshooting the cause of the malfunction.

Crashdumps are for Technical Support

The files generated by crashdumps are not intended to be read and interpreted by the administrator. Instead, they are intended to be sent to product support personnel and all relevant files should be sent.

Downloading Crashdump Files

Any of the files generated by a crashdump can be downloaded using SCP. All files are kept in the storage folder called crashdumps. A typical SCP command to download a single file would take the form:
	scp  <user>@<fw-address>:/crashdumps/<crashdump-file>
To download all files in one operation, a typical SCP command would be:
	scp -r <user>@<fw-address>:crashdumps

Listing Crashdump Files

The CLI provides the command crashdump to manage the crashdump files stored in non-volatile memory. The -list option provides a list of all files currently stored along with their sizes in bytes plus the total memory used and available. For example, a typical listing might be:
System:/> crashdump -list
Size   Name
-----  -------------------------------
46142  2011-01-01_00.00.36_rtbld.dump
886    2011-01-01_00.00.52_dpcore.dump

Used space:     47028 Bytes
Free space:  24211456 Bytes

[Tip] Tip: The default option is -list

If no option is specified after the crashdump command, the option -list is assumed.

Crashdump File Naming

Every crashdump file has a filetype of .dump and the complete filename has the form:
Where the <module> identifies the module which is the source of the crashdump, preceded by the date and time of the crash occurring. For example:

[Note] Note: GMT is used in crashdump timestamps

The date and times used in crashdump timestamps are based on GMT. They are not based on local time.

Deleting a Single File

The -delete option can be used to delete files from permanent storage. For example, to remove the file 2011-01-01_00.00.52_dpcore.dump, the command would be:
System:/> crashdump -delete=2011-01-01_00.00.52_dpcore.dump

Deleting All Files

All crashdump files stored in memory can be deleted with the following command:
System:/> crashdump -delete=All
Instead of All, the wildcard asterisk character "*" can be used instead:
System:/> crashdump -delete=*

[Important] Important: Delete crashdump files after downloading

The size of non-volatile memory available for crashdump file storage is limited. It is therefore important to delete crashdump files as soon as they have been downloaded.

2.7. Statistics

cOS Stream maintains a large number of counters in memory that keep track of system activity. This information is kept only in memory and is mostly made up of single numerical values. The purpose of this is to be able to give the administrator an overview of the tasks being performed by the system and the counters are collectively known as Statistics.

Note that all values are reset between system restarts so that statistics are not carried over.

A separate document called the Clavister NetShield Firewall Statistics Reference Guide provides a detailed listing of all available statistical values. This section is designed to give a short introduction to their structure and use.

Accessing Statistics

There are two methods for the administrator to view statistics:

  • By using the statistics command in a CLI console.

  • Using an SNMP client that references a MIB file.

This section deals with examining statistics through the CLI. SNMP access to cOS Stream is described in Section 2.1.7, SNMP Monitoring.

The Hierarchical Statistics Structure

All statistics are part of a hierarchical tree structure which divides them into related values. This structure can be clearly seen in the contents of the Statistics Reference Guide.

An individual statistic is identified by means of a "path" which includes everything above it in the hierarchy. The form of this path is described in the Statistics Reference Guide. For example, the path definition for an interface's bytes_recv statistic is:


Where [..n] represents the name of the interface.

For example, the bytes_recv statistic associated with the if1 interface is identified with the path:


These variable references in paths are indicated in the Statistics Reference Guide using the [..n] notation.

Using the statistics Command

The CLI command statistics is used to display the value of one or many statistics at a moment in time or at a regular interval. Entering this command without options will initially give the following response:
System:/> statistics
The list of polled values is empty

The command maintains a list of statistics that can be polled and it is necessary to first add to the list using the -add option. Suppose that there is a requirement to see the number of active system users every 10 seconds. The command to add this to the list is:

System:/> statistics -add /authentication/system/active_users

The new contents of the list can now be displayed and at the same time all statistics on the list are polled:

System:/> statistics
Name | 2018-12-22 18:05:01                  Value  Unit
------------------------------------------  -----  -----
/authentication/system/active_users         1      users

A list of all statistics that can be polled is output from the command:

System:/> statistics -listall

Starting and Stopping Interval Polling

To begin polling the values in the list at a regular interval, the -poll and -interval options are used:
System:/> statistics -poll -interval=<number>
This turns on interval polling with new console output appearing every <number> seconds. In the example output below, more users appear after 10 seconds:
System:/> statistics -poll -interval=10
Name 2017-12-22 18:12:15                    Value  Unit
------------------------------------------  -----  -----
/authentication/system/active_users         2      users

Name 2017-12-22 18:12:25                    Value  Unit
------------------------------------------  -----  -----
/authentication/system/active_users         5      users
To stop interval polling use the following command:
System:/> statistics -stop

Using Wildcards

When adding statistics to the polling list, the asterisk "*" character can be used to specify all statistics within a particular category. For example, the statistic bytes_recv for the Ethernet interface if1 can be polled with the command:
System:/> statistics -add /interfaces/common/if1/bytes_recv
To poll all interfaces, the command would be:
System:/> statistics -add /interfaces/common/*/bytes_recv
Note, however, that the actual interface name specified as part of the path can vary from platform to platform.

Removing Polled Statistics

The -remove option can remove individual statistics from the polled list:
System:/> statistics -remove /authentication/system/active_users
If everything on the polled list is to be removed, this can be done using the wildcard character:
System:/> statistics -remove *
To remove specific groups of statistics, the wildcard character can be used with the -remove option in the same way as it is used with the -add option. For example:
System:/> statistics -remove /interfaces/common/*/bytes_recv

Logging Statistics Output to a File

The potential demands on memory make it impractical to log statistics polling output to a file on the firewall. However, it is possible to save the console output to a file in many SSH clients and this is the recommended way to do it.

Statistics and High Availability

Statistics are HA node specific and are therefore not synchronized between HA cluster nodes. This topic is discussed further in Section 22.5, HA Issues.

2.8. Diagnostic Tools

cOS Stream provides a set of CLI commands to help with troubleshooting problems. These commands are described in this section.

2.8.1. The Ping Command

When troubleshooting networking problems, one of the most useful tools is the CLI ping command. This command can send one of more ICMP ECHO, TCP or UDP packets to a specified IPv4 or IPv6 address and reports the reply that is received.

A Simple ICMP Example

The simplest example of ping usage is sending an ICMP ping message to the IPv4 address The CLI command would be:
System:/> ping
In the above command, the source interface is not explicitly specified so cOS Stream derives this by looking up the destination IP in the relevant routing table. The routing table used defaults to main but could be specified in the command using the -routingtable=<table> option. For example:
System:/> ping -routingtable=my-rtable
Note that when the source interface is not explicitly specified in this way, the configuration's rule sets are not checked to see if the traffic is allowed. Therefore the message is always sent and cannot be blocked or have address translation applied by the configured IP rules.

Specifying the Protocol and the Message Load

The ICMP ECHO, TCP or UDP protocols can be used when sending a message, with ICMP being the default. The protocol option is specified immediately following the ping command. For example, to send a UDP message to, the command would be:
System:/> ping -udp
When relevant, the message load can be specified using the -request option, so the response from an HTTP server could be tested with the following command:
System:/> ping -tcp -port=80 -request="GET /HTTP/1.0\n\n"

Sending to IPv6 Addresses

A message can be sent to an IPv6 address in the same way that it is sent to an IPv4 address. Any of the other options discussed previously can be used with IPv6 addresses. Below is an example of pinging the c1a1::1:2 IPv6 address:
System:/> ping c1a1::1:2

Sending 4-byte ICMP ping to c1a1::1:2:61083 from c1a1::1:1:128
4-byte ICMP reply from c1a1::1:2:61083 to c1a1::1:1:129

The -verbose Option

Extra information about traffic sent and received can be displayed when the -verbose option is used (this can be shortened to -v). For example:
System:/> ping -v
In some cases, extra information is available if the -vv (more verbose) option is used.

The verbose options are required when performing ping traffic simulation (described next) in order to see the configuration elements that are triggered during the simulation.

Incoming Packet Simulation Using the -srciface and -srcip Option

In addition to testing the responsiveness of a remote host, the ping command can be used to simulate incoming traffic on a given interface and thereby test how the current configuration responds to different types of traffic. This is done by using the -srciface option to specify the interface that will appear to be receiving the message generated, along with the -srcip option to specify the source IP address of the message.

For example, the following command would simulate an incoming ICMP ping message arriving on the if2 interface that was coming from the source IP address

System:/> ping -srciface=if2 -srcip= -verbose

This command will construct an ICMP packet with a destination IP of and cOS Stream will behave as though that packet had arrived at the interface if2 and had come from the external IP address

Note that the simulated traffic received in this way will be treated by the configuration as normal traffic. This means that such configuration elements as IP rule sets will be applied so any relevant NAT or SAT actions will also be applied. The traffic might even be dropped. Also note that the -routingtable option cannot be used with the -srciface option as it has no relevance in this context.

If there is no route that matches the combination of source IP address and receiving interface, the packet will be dropped. Some example output when this happens is listed below:

System:/> ping -srciface=if14 -srcip= -verbose
Simulating 4-byte ICMP ping to
  from (if14)
(Response is not displayed when '-srciface' is used)
SNOOP:  POLICY-1  : Forward lookup matched PBR rule "RoutingRule_1"
  (id 0x3039) against <ICMP if14; ->>
  if14; ->>:
	No route to source in table "Main" (ID: 0x20).

For the ping message not to be dropped, there must not only be a route that matches the source IP address and source interface combination but also an IP rule set entry that allows the traffic on that interface. If the administrator simulates the packet arriving on the if2 interface and going to some host on the network if1_net, the allowing IP rule set entry might be the following:

Action Source
Allow/NAT if1 if1_net if2 all-nets ping-inbound-ip4

If there is no IP rule set entry that allows the traffic it will also be dropped. The following example shows some example console output when this happens:

System:/> ping -srciface=if14 -srcip= -verbose
Simulating 4-byte ICMP ping to
  from (if14)
(Response is not displayed when '-srciface' is used)
SNOOP:  POLICY-1  : Forward lookup matched PBR rule "RoutingRule_1"
(id 0x3039) against <ICMP if14; ->>
SNOOP:  POLICY-1  : <ICMP if14; ->>:
  Found reverse route "Route_3" (ID: 0x3ead62f) ->
  if14 (Gateway: none) in table "Main" (ID: 0x20).
SNOOP:  POLICY-1  : <ICMP if14; ->>:
  Found forward route "Route_3" (ID: 0x3ead62f) ->
  if14 (Gateway: none) in table "Main" (ID: 0x20).
SNOOP:  POLICY-1  : Matched default rule "System::DefaultDrop"
SNOOP:  POLICY-1  : Dropped by default rule "System::DefaultDrop"
SNOOP:  POLICY-1  : <ICMP if14; ->>: Dropped by IP rules

Once both the routing problem and the IP rule problems that were indicated in the above two output examples are fixed, the following is an example of some problem-free output:

System:/> ping -srciface=if14 -srcip= -verbose
Simulating 4-byte ICMP ping to
  from (if14)
(Response is not displayed when '-srciface' is used)
SNOOP:  POLICY-1  : Forward lookup matched PBR rule "RoutingRule_1"
  (id 0x3039) against <ICMP if14; ->>
SNOOP:  POLICY-1  : <ICMP if14; ->>:
  Found reverse route "Route_3" (ID: 0x3ead62f) -> if14
  (Gateway: none) in table "Main" (ID: 0x20).
SNOOP:  POLICY-1  : <ICMP if14; ->>:
  Found forward route "Route_3" (ID: 0x3ead62f) -> if14
  (Gateway: none) in table "Main" (ID: 0x20).
SNOOP:  POLICY-1  : Matched rule "iprule_all_services" with id 0xdaa96f5
SNOOP:  POLICY-1  : Allow <ICMP if14; ->>: route via if14

Specifying Only the -srcip Option

The -srcip option can be used without -srciface when traffic is not being simulated. This usage allows an outgoing ping message to originate from a specific source IP address. For example, to send an ICMP ping from the IPv4 address to, the command would be the following:
System:/> ping -srcip=
Normal route lookup determines the sending interface. However, to use -srcip in this way, one of the following conditions needs to be true:

  • The source IP specified is one of the addresses that is configured on the sending interface.

  • If a route lookup is done on the source address, it is routed on the core interface.

All ping command options are listed in the separate CLI Reference Guide.

2.8.2. Dconsole

During system operation, important troubleshooting information is saved in system memory by the Dconsole subsystem. This information takes the form of time stamped messages which record both normal events such as system restarts but also any abnormal system events. These messages can be retrieved at any time using the CLI command:

System:/> dcon

The output generated by the dcon command provides an important diagnostic tool that can help to determine the cause of a system problem. However, it should be remembered that interpreting the output is often best done by sending the information to qualified support personnel.

Message Content

Each dcon message that is written during system operation includes the following information:

  • A timestamp to show when the message was generated.
  • Uptime since the last system start.
  • The severity level of the event.
  • The category name of the application code that generated the event.
  • The software module that caused the event.
  • A textual message stating what the event was.

Some typical output from the dcon command is shown below:

System:/> dcon
Showing diagnose entries since 2012-11-09:
2015-11-07 12:02:15     01:51:29        INFO    SYSTEM,CONFIG   vsinit  
Beginning reconfigure [type=Activating new config][reason=] [09ce5f4f]
2015-11-07 12:02:16     01:51:30        INFO    SYSTEM,CONFIG   vsinit
Reconfigure completed successfully [0b1a5f4f]

Here, the dcon command is used without any parameters and by default only messages stored for today are displayed. The first message retrieved indicates the time of a reconfigure. The second indicates the reconfigure has been successfully completed.

All the recent dconsole messages could have been displayed by using the command with some previous date specified:

System:/> dcon -show -date=2016-01-01

The Message Buffering Mechanism

A finite amount of volatile memory is allocated for the buffering of dcon messages. Typically, this buffer holds around a thousand messages although this number can vary because of the variable message length. The contents of this buffer are lost between system restarts.

When the volatile memory buffer is full, the newest message overwrites the oldest message. At certain times, the entire buffer is copied to a non-volatile memory file called dcon.bin and then the buffer is cleared. These copy operations occur when:

  • A system event with a Critical or High priority occurs.

  • Or the volatile memory buffer is explicitly flushed with the command:

    System:/> dcon -flush

When the copy operation occurs, the messages in the volatile memory buffer are appended to the existing messages in the non-volatile file dcon.bin. After the copying is complete, the volatile memory buffer is automatically cleared and begins to fill up again with new messages.

Messages can be appended to the non-volatile file until the configured maximum size of the file is reached. When this happens, cOS Stream erases the oldest 50% of the messages to clear space for new appended messages. The newest 50% of messages in the file are preserved.

During system startup the non-volatile file is allowed to temporarily grow beyond its configured maximum to accommodate any messages generated. This deals with the case that the file may be close to its size limit at startup but vital troubleshooting information still needs to be retained if a problem occurs.

The Volatile Memory Buffer is Circular

The volatile buffer is circular which means that new messages overwrite the oldest messages when it becomes full. When overwriting occurs, a dcon message is generated that takes a form similar to the following:
2015-11-06 13:11:26 368:23:42 INFO LOG dcon 801 Messages got Overwritten

Manually Clearing All Messages

All messages currently held in dconsole storage can be removed with the command:
System:/> dcon -clean
This clears all messages in both the volatile memory buffer and the non-volatile memory file.

Filtering Messages

When output reports are generated, dcon scans all the available messages in both volatile and non-volatile memory. The command provides a variety of options for filtering this output since the total number of available messages may be high.

For example, to show all events that have a severity of Critical or higher, use the command:

System:/> dcon -show -severity=Critical

To show all events that were generated after and including 1st June 2011, use the command:

System:/> dcon -show -date=2016-06-01

To show all events related to the system vsinit component, use the command:

System:/> dcon -show -app=vsinit

To show all events related to the system dataplane component, use the command:

System:/> dcon -show -app=dataplane

For a full list of dcon command options, refer to the separate Clavister NetShield Firewall CLI Reference Guide.

2.8.3. Pcapdump

A valuable diagnostic tool is the ability to examine the packets that enter and leave the interfaces of a Clavister NetShield Firewall. For this purpose, cOS Stream provides the CLI command pcapdump which allows the recording of packets entering and leaving all or certain interfaces. The captured packets can be stored in a file and/or displayed on the console in an easily readable text form. Filters can also be applied so that only packets meeting specific criteria are recorded.

This section focuses on some of the important options for using the command. The complete syntax of the pcapdump CLI command is described in the cOS Stream CLI Reference Guide.

[Important] Important: Pcapdump requires sufficient control plane memory

The pcapdump command requires that the control plane free memory space to be at least 100 MBytes. If this is not available then the pcapdump command will come back with a message saying that it has insufficient memory. This problem should only occur in a virtual environment and to resolve it, the virtual machine should be stopped and the memory allocated to cOS Stream should be increased. One Gigabyte of RAM for the whole virtual machine should be a minimum. The CLI memory command can show the amount of available memory in the control plane.

The Command View Needs to be Changed

The pcapdump command is not available in the default CLI view. The CLI view must be changed to at least debug with the following command:
System:/> cmdview debug

A Simple Example

An example of pcapdump usage is the following sequence which will record the packet flow on the if3 interface:

  • Recording is started for the if3 interface with the following command:

    System:/> pcapdump -start if3
    Starting packet capture on: if3

    By default, output is automatically saved to a file and no output appears on the console. Only one interface name can be specified in a command. To capture a group of interfaces, a pcapdump -start command must be issued for each interface. The following command with no interface specified will record packets on all interfaces:

    System:/> pcapdump -start

  • The total number of packets captured can be limited with the -count option. cOS Stream will total the packets arriving and the packets leaving to determine if the count specified has been reached. To capture just the first 100 packets on the if3 interface, the command would be:

    System:/> pcapdump -start if3 -count=100

    When the specified packet count is reached, the capture will be stopped automatically and a message will be output to the console. An example of this message for the command above could be:

    if3: Packet capture stopped (packet count reached).
    Packets have been saved to file "if3_2014-12-17_15.32.12.cap".

  • The currently enabled packet capture can be viewed along with the number of packets recorded so far by using the -status option:

    System:/> pcapdump -status
                 PCAP Status
    Interface Mode   Packets(In)   Packets(Out) Filter
    --------- ------ -----------   ------------ ------
    if3       ACTIVE 9             5

  • Recording can then be stopped for if3 with the -stop option:

    System:/> pcapdump -stop if3
    Stopping packet capture on: if3.
    Interface Pkts(In) Pkts(Out) Saved to file
    --------- -------- --------- ---------------------------
    if2       3        4         if3_2014-12-17_16.32.12.cap

    The name of the file used for the saved output consists of the interface name and the date and time when the recording is stopped. The -stop option without an interface specified will stop all captures for all interfaces:

    System:/> pcapdump -stop

    There is always a separate file created for every interface involved in a capture. Files are saved in volatile memory in the root directory and they are deleted following a restart.

  • All the available saved output files can now be listed using the -list option:

    System:/> pcapdump -list
           PCAP Files
    Size  Name
    ----  ---------------------------
    354  if3_2014-12-17_16.32.12.cap

  • To list the contents of a saved file, use the -show option with the filename:

    System:/> pcapdump -show -filename=if3_2014-12-17_16.32.12.cap
    Showing packets in file "if3_2014-12-17_16.32.12.cap":
    IP>  IHL:20  DataLen:12 TTL:59 Proto:ICMP
    ICMP Echo request  ID:4042  Seq:0
    IP>  IHL:20  DataLen:12 TTL:128 Proto:ICMP
    ICMP Echo reply  ID:4042  Seq:0

    Note that the -show option on its own will just show the packets that are in the buffer memory and have not been written yet. Buffering is discussed further later. If there is a need to stop the output from the show command, the Ctrl-S key sequence can be used to pause output and Ctrl-C can be used to break output.

    The -num option can only be used with -show and it limits the number of packets displayed. For example, if only the first 20 packets were to be displayed, the above command would become:

    System:/> pcapdump -show -filename=if3_2014-12-17_16.32.12.cap -num=20

    By default, the -show option displays all packets.

  • Saved files can be deleted with the -remove option:

    System:/> pcapdump -remove -filename=if3_2014-12-17_16.32.12.cap

    Wildcards could also have be used when specifying the filename so that a group of matching files can be deleted with one command. For example, to delete all files beginning with "if3":

    System:/> pcapdump -remove -filename=if3*

    This option could be used to remove all stored files with the following command:

    System:/> pcapdump -remove -filename=*

  • All saved files can be deleted and the memory buffer cleared with the following command:

    System:/> pcapdump -remove

    This buffer is automatically cleared when recording stops if the -nowrite option was not used. If the -nowrite option was used then the -remove option is needed to clear the buffer. A new recording session on the same interface will also clear that interface's buffer.

Using -snaplen to Reduce File Size

The -snaplen option can be used to truncate all packet information before it saved in the buffer and/or a file. However, it will not truncate the information displayed on the console. For example, to only store the first 100 characters of information for each packet, the following command could be used:
System:/> pcapdump -start if3 -snaplen=100
The truncation is done only when the information is stored and does not affect any filtering performed.

The -snaplen option is also useful in reducing the space needed in the pcapdump buffer by shortening the packet information stored. The allocated buffer size is discussed later in this section.

The Memory Buffer Records All Packets Stored

Except for the case of using only console output, all packet information captured is always saved in a memory buffer of a fixed size. There is one buffer allocated at the start of a capture for each interface involved. The space in the buffer occupied by packets can vary depending on the type of packets captured. The current buffer contents can be displayed with just the -show option:
System:/> pcapdump -show
The buffer contents can be explicitly written to a file with the command:
System:/> pcapdump -write
This will write all the buffer contents into as many files as there are interfaces being recorded. If only a particular interface is to be written to a file with a given name, say if3.cap, then the following command would be used:
System:/> pcapdump -write if3 -filename=if3.cap
Writing to the memory buffer can be turned off with the -nocap option. This might be used with the -out option so there is just live output to the console:
System:/> pcapdump -start -out -nocap
When the -nocap option is used, the -status option output will show the Mode as SNOOP instead of ACTIVE.
System:/> pcapdump -status
             PCAP Status

Interface Mode   Packets(In)  Packets(Out) Filter
--------- ------ -----------  ------------ ------
if3       SNOOP  124          174
The memory buffer can be cleared (along with any saved files) by using the command:
System:/> pcapdump -remove

As mentioned earlier, the buffer is usually cleared after packet recording stops and files are automatically written. However, if file writing is disabled by using the -nowrite option, the buffer is not cleared and subsequent pcapdump -start commands will append packet information to the current buffer contents.

The administrator has the option to examine the buffer contents or write the buffer contents to file. To clear the buffer when using the -nowrite option, the administrator must use the pcapdump -remove command.

Changing the Allocated Memory Buffer Size

A pcapdump -start command will allocate a buffer for each interface involved in the packet capture. By default, this buffer is 128 Kbytes. If the captured packets exceed this memory allocation, capture will stop and the following message will appear on the console:
	     Packet capture stopped (buffer size limit reached).
If this is a problem, the buffer size can be specified as larger in the command to start capture. For example, if the desired buffer size is 256 Kbytes then the command would be the following:
System:/> pcapdump -start if3 -bufsize=256 
The minimum buffer size is 128 Kbytes, but it is unlikely that the buffer size needs to be reduced to this. Another approach to solving an insufficient buffer size problem is to use the -snaplen option discussed previously. This will truncate the stored packet information and so reduce the information stored in the buffer and the size of the file created.

Writing Directly to the Console

As well as writing output to a file, output can be also directed to the console with the following version of the start command:
System:/> pcapdump -start if3 -out
This will send output to the console and at the same time save output to a file. If no file should be created then the -nowrite option is used:
System:/> pcapdump -start if3 -out -nowrite
The above command will still cause a buffer to be allocated to the interface and filled with captured packets so a file could be written by saving the buffer to a file, as described previously.

As discussed earlier, if the desire was to write to the console but only to the console and not allocate and fill a buffer, the command would be:

System:/> pcapdump -start if3 -out -nocap

Filtering Output

In conjunction with the above versions of the pcapdump command where the -start option was used with an interface, further filters can be applied to further restrict the type of packet captured.

The range of filters available is large and is fully documented on the online help (type help pcapdump) as well as in the separate CLI Reference Guide. This section will show examples of some of the filters to illustrate their use.

  • Port Number

    The general use of filters can be illustrated by looking at the filter for a specific port number:

    System:/> pcapdump -start if3 -port=53

    Or on a port range:

    System:/> pcapdump -start if3 -port=53-95

    Alternatively a list of ports could have been specified, so any of the list must match:

    System:/> pcapdump -start if3 -port=53,85,92

    Using -port means either the source or destination port must match the given values. However it is possible to specify these separately:

    System:/> pcapdump -start if3 -portdest=45 -portsrc=85

    cOS Stream provides predefined values which can be used for convenience instead of have to type integers. For example, to filter all traffic using the known FTP port numbers, the command could be:

    System:/> pcapdump -start if3 -port=FTP

    [Note] Note: An AND operation is performed on multiple filters

    When more than one filter parameter is specified then all parameters must match for the packet to be recorded by pcapdump. In other words, a logical AND operation is performed between the filters.

  • Protocol

    The -proto parameter looks for a specific traffic protocol at the IP level. For example, to only filter out ICMP traffic:

    System:/> pcapdump -start if3 -proto=ICMP

    Each string value like ICMP that can be used in the CLI is a convenience provided by cOS Stream. The actual assigned protocol number could be used instead. For ICMP, this is the number 1. Lists and ranges of protocols could be specified with either these predefined string values or the actual protocol numbers or both. For example, the following is valid:

    System:/> pcapdump -start if3 -proto=ICMP,2,7-9

  • IP Address

    The source or destination IP can be filtered. The IP specified can be IPv4 or IPv6 or a combination of both in a list. Below, is an example which specifies a single IPv4 address:

    System:/> pcapdump -start if3 -ip=

    A range can be specified instead:

    System:/> pcapdump -start if3 -ip=

    Or an entire network:

    System:/> pcapdump -start if3 -ip=

    Here, IPv4 is mixed with IPv6:

    System:/> pcapdump -start if3 -ip=,2001:db8::1

    Using -ip on its own means either the source or destination IPs must match the filter. However, these can be separated:

    System:/> pcapdump -start if3 -ipsrc= -ipdest=2001:db8::1

[Caution] Caution: Pcapdump can degrade performance

Running pcapdump will have some impact on overall system performance. The degree of impact depends on the options chosen. The impact can be reduced by capturing on the smallest number of interfaces possible and through using filters to reduce the amount of packets captured.

Raising the values of the -bufsize and/or -count options too high can have a particularly adverse effect on performance.

Compatibility with Wireshark

The open source tool Wireshark (formerly called Ethereal) is a useful analysis tool for examining the logs of captured packets. The industry standard .pcap file format is used by pcapdump when it writes data to a file which means that it is compatible with Wireshark.

The administrator must use SCP in order to download the .cap files created by pcapdump from cOS Stream disk storage to a local management workstation for reading by Wireshark.

Writing in Hex and K12 Format

All files written by the pcapdump command are in the .cap format. However, it is possible to write console output in either hexadecimal or K12 format. For example, to write output to the console in hexadecimal format, the command would be:
System:/> pcapdump -start if3 -out -hex
To write output to the console in K12 format, the command would be:
System:/> pcapdump -start if3 -out -k12

cOS Stream can also perform a conversion from the current buffer contents in .cap format to hexadecimal or K12 format on the console. To display the current buffer contents in hexadecimal, the command would be:

System:/> pcapdump -show if3 -hex

Writing hexadecimal to the console provides an alternative way to get packet data into Wireshark or another tool. The hexadecimal output displayed in an SSH client console can be copy and pasted into a local text file on the management workstation and then that file can be read by Wireshark.

2.8.4. The techsupport Command

The techsupport CLI command is a general command for problem troubleshooting that combines the output from several other troubleshooting commands into a single console output. This information can then used by the administrator but is usually sent to qualified support personnel to troubleshoot problems.

The simplest form of the command is the following:

System:/> techsupport

This will create a file in the top level (root) directory of the system file system called techsupport.txt. Each usage of the command will overwrite any previous techsupport.txt file.

Once created, there are two ways of examining the file's contents:

  • Download the file over a network connection by using SCP from an external management computer.

  • Use the following CLI command to display the current file contents on the console:

    System:/> techsupport -show

    The output on the console will automatically be paginated with an interactive prompt to show the next page. To display the entire file at once without pagination, use the following command:

    System:/> techsupport -show -nopages

The first few lines of the techsupport.text file include the system time when the contents were created. A typical example of this header is the following:

Technical Support Information
Please verify the contents before sending to Technical Support.
System Time: 2016-09-08 12:13:48 (UTC+00:00)

2.9. Hardware Monitoring


When cOS Stream is running on dedicated Clavister hardware (and not in a virtual environment), various sensors in the hardware will provide cOS Stream with information about the status of the hardware components. This information ranges from temperatures and fan speeds to indicating if components, such as power supply units, are operational.

The Sensor Polling Interval

By default, cOS Stream polls all hardware sensors every 5 seconds and stores the last retrieved sensor information until the next poll overwrites it. This 5 second interval can be changed globally by the administrator to another value between 1 and 30 seconds. For example, if the polling interval is to be changed to 20 seconds, the following CLI command would be used:
System:/> set Settings HWMONSettings SensorRefreshInterval=20

Type Of Hardware Monitoring

The Clavister NetShield Firewall provides two types of hardware monitoring that makes use of the information collected by sensor polling:
  • System hardware monitoring.

  • User hardware monitoring.

These types are explained in the sections that follow.

2.9.1. User Hardware Monitoring

In contrast to System Hardware Monitoring, the feature called User Hardware Monitoring is used to generate log event messages for specific sensors and conditions that are defined by the administrator.

Enabling User Hardware Monitoring

To enable user hardware monitoring for a sensor, a HWMONMonitor object must be created in the configuration and associated with the sensor. Only one sensor can be associated with one HWMONMonitor object.

Assume that monitoring of the CPU temperature is required. If the sensor name is CPU_Temp and the new object is to be called mon1, user monitoring for this sensor can be enabled with the following CLI command:

System:/> add HWMONMonitor mon1 SensorID=CPU_Temp

The HWMONMonitor object created will generate an event message when its sensor has a value that moves outside the thresholds defined for the object (in the case of temperatures and fan speeds) or when the status changes (in the case of a failed power supply).

Another log message is generated as the sensor value moves back to a normal value and becomes equal to the threshold value. In the above command, no minimum or maximum threshold values are specified so cOS Stream will use the default thresholds for this sensor. All sensors have default thresholds already defined. Note that the SensorID property must always be specified when creating an HWMONMonitor object.

By default, a severity of Warning is used for all log messages generated. The severity can be explicitly set by changing the Severity property of an HWMONMonitor object. For example, to set the severity to Emergency for the mon1 object, the CLI command would be:

System:/> set HWMONMonitor mon1 Severity=Emergency

Sensor Types

Sensors are of two types:
  • Numeric sensors - These provide numeric values. For example, temperature or fan speed.

  • Binary sensors - These provide a value that is either zero or one. For example, a PSU being operational or not operational.

Understanding the thresholds of a numeric sensor is straightforward but binary sensors require some additional explanation. Binary sensors have a value which is either 1 or 0. However, it depends on the sensor which value indicates a "normal" condition. For example, one sensor could indicate that a PSU is installed and its normal value is 1 (the PSU is present). Another sensor might indicate that a PSU has failed and its normal value is 0 (the PSU is operational and has not failed).

The following should be noted about HWMONMonitor object thresholds for binary sensors:

  • A binary sensor that has a normal value of 1 will have low and high thresholds that are both 1. When the sensor's value becomes 0, this will indicate an abnormal condition.

  • A binary sensor that has a normal value of 0 will have low and high thresholds that are both 0. When the sensor's value becomes 1, this will indicate an abnormal condition.

Changing Threshold Values

The lower and upper thresholds for an HWMONMonitor object associated with a numeric sensor can be changed from the default, as shown in the following example:
System:/> set HWMONMonitor mon1 LowThresh=-5 HighThresh=100
Note that negative values can be used for temperatures.

[Important] Important: Do not change thresholds of binary sensors

The thresholds associated with a binary sensor, such as PSU failure, should not be changed by the administrator. The default threshold values should always be used.

Changing the Monitoring Interval for the HWMONMonitor Object

The Interval property of an HWMONMonitor object decides how often, in seconds, the data from the object's associated sensor is examined. A higher value for this property will cause less log messages to be sent. For example, to examine the CPU temperature every 30 seconds, the CLI command would be as follows:
System:/> set HWMONMonitor mon1 Interval=30
Note that this interval does not affect the rate at which the sensors are polled, which is controlled by the global setting SensorRefreshInterval (described at the beginning of this topic). The Interval property only affects the frequency with which the currently stored sensor values are examined by the HWMONMonitor object to determine if a log message should be generated.

Log Messages

A message is generated when the sensor value passes outside the thresholds specified. A second log message is generated when the sensor value passes back inside the thresholds specified. Similarly, for a binary sensor, a log message is generated when the state of the sensor changes in either direction.

The log messages generated by HWMONMonitor objects all belong to the HWMON log message category. As described previously, the severity of the message is Warning by default but this can be changed by setting the Severity property of the HWMONMonitor object generating the message. Below are some examples of the log messages created by user hardware monitoring.

A sensor value above a maximum threshold:

SYSTEM,HWMON: prio=warning id=1081
event=sensor_value_above_monitor_threshold sensorid=”CPU_Temp”
description="CPU Temperature" name="n2" value=81
threshold=80 action=none

A sensor value below a minimum threshold:

SYSTEM,HWMON: prio=warning id=1079
event=sensor_value_below_monitor_threshold sensorid=”CPU_Temp”
description="CPU Temperature" name="n2" value=29
threshold=30 action=none

A sensor value crossing a threshold back to a normal value:

SYSTEM,HWMON: prio=warning id=1082
event=sensor_returned_to_normal sensorid=”CPU_Temp”
description="CPU Temperature" name="n2" value=80

The Log Repeat Interval

While the sensor value remains outside of its thresholds, a HWMONMonitor object will regenerate the log message, by default, every 6 hours so that the administrator continues to be reminded that the abnormal condition exists.

The default log repeat interval value of 6 hours can be changed by assigning a new value to the LogRepeatInterval property of the HWMONMonitor object. The value is specified as an integer number of seconds. For example, the following command would change the log repeat interval for the monitor called mon1 to become 12 hours:

System:/> Set HWMONMOnitor mon1 LogRepeatInterval=43200

Note that the minimum allowed value for the LogRepeatInterval property is 30 seconds and the maximum is 86,400 seconds (24 hours).

Displaying the Available Sensors

To see all the current available sensors, the hwmon -sensorlist command can be used. The following shows some typical output (the last two right hand columns showing lowest and highest have been truncated to fit the page width):
System:/> hwmon -sensorlist
Sensor ID       Description               Unit  Value  Monitor Min    Max
--------------  ------------------------  ----  -----  ------- -----  -----
CPU_Temp        CPU Temperature           C     58     yes     0      98    
System_Temp     System Temperature        C     24     no      0      55    
System_Power    System Power Consumption  W     224    no      0      500   
System_12V      System Internal Power     mV    12126  no      11500  13000 
FAN1_RPM        System FAN1 Speed         RPM   4200   no      1500   6800   
FAN2_RPM        System FAN2 Speed         RPM   4000   no      1500   6800  
FAN3_RPM        System FAN3 Speed         RPM   4100   no      1500   6800  
PSU1_Avail      PSU1 Available            -     1      no      1      1     
PSU1_Fail       PSU1 Failure Detected     -     0      no      0      0    
PSU1_Input_Lost PSU1 Power Input Lost     -     0      no      0      0     
PSU2_Avail      PSU2 Available            -     1      no      1      1   
PSU2_Fail       PSU2 Failure Detected     -     0      no      0      0   
PSU2_Input_Lost PSU2 Power Input Lost     -     0      no      0      0

The following should be noted about the above output:

  • The Value column indicates the value that the sensor returned when it was last polled. Here, the CPU temperature was 58 degrees when that sensor was last polled.

  • The Min and Max columns show the default thresholds that will be used if none are explicitly specified when an HWMONMonitor object is created. These default thresholds are fixed and cannot be changed by the administrator.

  • The value of no under the Monitor column means that no HWMONMonitor object is currently associated with that sensor. If there is at least one HWMONMonitor object associated with the sensor, the value in the column becomes Yes. Disabling an HWMONMonitor object will not affect its associated Yes value in this column.

Displaying the Current HWMONMonitor List

To see all the current HWMONMonitor objects, the hwmon is used with no parameters. The following shows some typical output for two configured HWMONMonitor objects called mon1 and mon2 that are monitoring CPU temperature:
System:/> hwmon
Name  Sensor    Description       Value  Low  High  Status  #Low  #High
----  --------  ----------------  -----  ---  ----  ------  ----  -----
mon1  CPU_Temp  CPU Temperature   59     0    98    NORMAL  0     0
mon2  CPU_Temp  CPU Temperature   59     20   70    NORMAL  0     0
Here, the Low and High columns are the currently defined thresholds for these HWMONMonitor objects. The #Low and #High columns are the total number of alarms triggered when the low and high thresholds are passed. Alarms are explained later in this section.

Note that in the above list, there are two HWMONMonitor objects defined for the same sensor. This is permissible and means that separate log messages can be generated for different sensor ranges.

The Status column in the above output indicates the status of the sensor value when it was last examined by the HWMONMonitor object and can show the following values:

  • NORMAL - The value is within the thresholds.

  • ALARM:LOW - The value has exceeded the minimum threshold and has not yet returned to normal.

  • ALARM:HIGH - The value has exceeded the maximum threshold and has not yet returned to normal.

  • WARNING: RETURN LOW - The value has just returned from being outside the minimum threshold to the normal range. The column will show NORMAL after the next reading of sensor values.

  • WARNING: RETURN HIGH - The value has just returned from being outside the maximum threshold to the normal range. The column will show NORMAL after the next reading of sensor values.

  • UNKNOWN STATUS - The possible reasons for this column entry are the following:

    1. cOS Stream is in the process of restarting and no values are yet available.

    2. The SensorID property of the HWMONMonitor object does not correspond to any sensor in the hardware.

    3. The sensor has a fault and is not returning values.

Displaying HWMONMonitor Properties

To see all the properties for an HWMONMonitor object, the hwmon <monitor-name> command can be used. For example, to see all the values for the HWMONMonitor called mon1, the command would be:
System:/> hwmon mon1
Name                       : mon1
Sensor id                  : CPU_Temp
Log severity setting       : warning
Description                : CPU Temperature
Value                      : 58
Low Threshold              : 0
Recommended low threshold  : 0
High Threshold             : 98
Recommended high threshold : 98
Action interval (seconds)  : 5
ALARM:LOW counter          : 1
ALARM:HIGH counter         : 3
Last status                : NORMAL

Note that the Recommended low threshold and the Recommended high threshold in the above output are the default threshold values for the associated sensor.

Sensor Alarms

As shown in the output above, each HWMONMonitor object has two alarm counters associated with it, the ALARM:LOW counter and the ALARM:HIGH counter. These properties of the object can only be read and cannot be manipulated by the administrator.

The following should be noted about the alarm counters:

  • Alarm counters start at zero after starting cOS Stream and are incremented each time the sensor value passes one of the thresholds.

  • For binary sensors, such as a PSU fail/not fail sensor, the alarm is incremented when the sensor value changes from 1 to 0, or 0 to 1. It is a change of state from the normal that increments the counter. However, only ALARM:HIGH is incremented if a normal value of 0 changes to 1 and only ALARM:LOW is incremented if a normal value of 1 changes to 0.

  • Alarm counters are not decremented. This allows the administrator to be able to see the total number of times the alarm has been triggered. The counters are only zeroed when cOS Stream is restarted or when the hardware monitoring is disabled globally and then re-enabled.

2.9.2. System Hardware Monitoring

The sensor information that is gathered by cOS Stream is available to an SNMP client using the SNMP protocol. This type of monitoring is known as System Monitoring.

System monitoring only has one option available that can be set by the administrator, and that is if it is enabled or disabled. All hardware monitoring is enabled by default, but this can be disabled by the following CLI command:

System:/> set Settings HWMONSettings MonitorEnable=No

This will disable both system and user monitoring. Both can be re-enabled with the following command:

System:/> set Settings HWMONSettings MonitorEnable=Yes

This setting affects both system monitoring and user monitoring

2.9.3. Sensors for Clavister Products

The following are the available sensors for the current range of Clavister hardware products running cOS Stream. All fan speeds are given in RPM and temperatures are in degrees centigrade.

  • NetShield S10
Sensor Name Sensor Type Sensor Number Minimum Limit Maximum Limit
CPUTemp TEMP 0 0 80
  • NetShield P40
Sensor Name Sensor Type Sensor Number Minimum Limit Maximum Limit
Left_PSU GPIO 0 1  
Right_PSU GPIO 0 1  
SysTemp1 TEMP 256 0 70
SysTemp2 TEMP 257 0 70
SysFan1 FANRPM 256 1500 12800
SysFan2 FANRPM 258 1500 12800
SysFan3 FANRPM 260 1500 12800
SysFan4 FANRPM 260 1500 12800
CPUTemp1 TEMP 512 0 80

  • NetShield 6000 Series
Sensor Name Sensor Type Sensor Description Minimum Limit Maximum Limit
PSU1_INST GPIO PSU1 Installed 1 1
PSU1_TEMP temperature PSU1 Temperature    
PSU1_FAN fan PSU1 Fan Speed 5000 14000
PSU1_V_OUT voltage PSU1 Output Voltage    
PSU1_I_OUT current PSU1 Output Current    
PSU1_P_IN power PSU1 Input Power    
PSU1_P_OUT power PSU1 Output Power    
PSU2_INST GPIO PSU2 Installed 1 1
PSU2_TEMP temperature PSU2 Temperature    
PSU2_FAN fan PSU2 Fan Speed 5000 14000
PSU2_V_OUT voltage PSU2 Output Voltage    
PSU2_I_OUT current PSU2 Output Current    
PSU2_P_IN power PSU2 Input Power    
PSU2_P_OUT power PSU2 Output Power    
SYS_VCORE voltage system Vcore Internal 0 1744
SYS_3V3 voltage System 3.3V Internal    
SYS_12V voltage System 12V Internal 11500 13000
SYS_VBAT voltage System CMOS Battery 2900 3200
SYS_5V voltage System 5V Internal    
SYS_FAN1 fan System FAN1 Speed 6000 14000
SYS_FAN2 fan System FAN2 Speed 6000 14000
SYS_FAN3 fan System FAN3 Speed 6000 14000
SYS_TEMP1 temperature System Temperature 1 0 80
SYS_TEMP2 temperature System Temperature 2 0 80
SYS_AIR_IN_TEMP temperature Air Intake Temp 0 50
CPU_TEMP temperature CPU Temperature 0 95

Chapter 3: Interfaces

An Interface is an important logical building block in cOS Stream. All network traffic that transits through, originates from or is terminated in a Clavister NetShield Firewall, does so through one or more interfaces.

Source and Destination Interfaces

An interface can be viewed as a doorway through which network traffic passes to or from cOS Stream. An interface has one of two functions:

  • The Source Interface

    When traffic arrives through an interface, that interface is referred to in cOS Stream as the source interface (also sometimes known as the receiving or incoming interface).

  • The Destination Interface

    When traffic leaves after being checked against cOS Stream's security policies, the interface used to send the traffic is referred to in cOS Stream as the destination interface (also sometimes known as the sending interface).

All traffic passing through cOS Stream has both a source and destination interface. As explained in more depth later, the special logical interface core is used when cOS Stream itself is the source or destination for traffic.

Interface Types

The Clavister NetShield Firewall supports a number of interface types, which can be divided into the following groups:

  • Ethernet Interfaces

    Each Ethernet interface represents a physical or virtual Ethernet port. All network traffic that originates from or enters a Clavister NetShield Firewall will pass through one of the physical interfaces.

    The Clavister NetShield Firewall currently supports Ethernet as the only physical interface type.

  • Tunnel Interfaces

    Tunnel interfaces are used when network traffic is being tunneled between the system and another tunnel end-point in the network, before it gets routed to its final destination. An IPsec tunnel object is such an interface and IPsec is described further in Section 13.2, IPsec Components.

    To accomplish tunneling, additional headers are added to the traffic that is to be tunneled. Furthermore, various transformations can be applied to the network traffic depending on the type of tunnel interface. For example, when routing traffic over an IPsec interface, the payload is usually encrypted to achieve confidentiality.

All Interfaces are Logically Equivalent

Even though the different types of interfaces may be very different in the way they function, cOS Stream treats all interfaces as logically equivalent. This is an important and powerful concept and means that all types of interfaces can be used almost interchangeably in the various rule sets and other configuration objects. This results in a high degree of flexibility in how traffic can be examined, controlled and routed.

An extension of this equivalency concept is that no interface is assumed to be connected to trusted "inside" networks or to untrusted "outside" networks. The administrator makes these decisions and implements security policies accordingly.

Interfaces have Unique Names

Each interface in cOS Stream is given a unique name to be able to identify and select it for use with other objects in a configuration. Some interface types, such as Ethernet interfaces, are already provided by cOS Stream with relevant default names that are possible to modify if required.

The any and core Interfaces

In addition, cOS Stream provides two special logical interfaces which are named any and core. The meaning of these are:
  • any represents all possible interfaces including the core interface.

  • core indicates that it is cOS Stream itself that will deal with traffic to and from this interface. An example of the use of core is when cOS Stream responds to ICMP "Ping" requests. By specifying the Destination Interface of an IP rule or route as core, cOS Stream will then know that it is itself that is the ultimate destination of the traffic.

3.1. Ethernet Interfaces

The Clavister NetShield Firewall supports Ethernet, Fast Ethernet, Gigabit Ethernet and 10 Gigabit Ethernet interfaces as defined by the IEEE 802.3 standards.

Ethernet Frames

With Ethernet, devices sends data as Ethernet frames and other devices "listen" to determine if they are the intended destination for any of these frames. A frame is a sequence of bits which specify the originating device plus the destination device plus the data payload along with error checking bits. A pause between the sending of individual frames allows devices time to process each frame before the next arrives and this pause is progressively smaller with the faster data transmission speeds.

The EthernetInterface and EthernetDevice Object Types

There are two types of configuration objects that are used to manage Ethernet interface operation: EthernetInterface and EthernetDevice. The EthernetInterface object is used to configure the logical properties of Ethernet operation such as IP address.

The EthernetDevice object is used to specify low level, driver related properties such as link-speed and duplex. It is the EthernetInterface object type that is covered by this section.

Ethernet Interface Properties

The following are the principal properties for an EthernetInterface object:

  • Interface Name

    The names of the Ethernet interfaces are predefined by the system, and are mapped to the names of the physical ports; a system with a wan port will have an Ethernet interface named wan and so on.

    The names of the Ethernet interfaces can be changed to better reflect their usage. For example, if an interface named dmz is connected to a wireless LAN, it might be convenient to change the interface name to wireless. For maintenance and troubleshooting, it is recommended to tag the corresponding physical port with the new name.

  • IP Addresses

    Each Ethernet interface is required to have an Interface IP Address. The interface IP address is used as the primary address for communicating with the system through the specific Ethernet interface.

    More than one IP address can be allocated to an Ethernet interface.

    IPAddress objects are usually used to define the IP addresses of Ethernet interfaces. Those objects are normally auto-generated by the system. This is discussed further in Section 5.3, Auto-generated Address Objects. When cOS Stream is first started, all unconfigured Ethernet interfaces will be assigned default addresses from the localhost sub-network (

  • MTU

    This determines the maximum size of packets in bytes that can be sent on this interface. By default, the interface uses the maximum size supported.

  • HACritical/Sync

    For HA cluster nodes it is important to identify those interfaces which are critical and those which are designated as sync interfaces. This is explained further in Chapter 22, High Availability.

Listing Ethernet Interfaces

To list all Ethernet interfaces, the CLI command is:
System:/> show Interface EthernetInterface

   Interface Name  IP Addresses  Routing Table
   --------------  ------------  -------------
   if1      main
   if2      main
The listing shows there are two interfaces. The IP address allocated to each is shown along with the routing table that is associated with them.

Changing the IP Address of an Ethernet Interface

To change the IP address on an interface, there are two methods:

  • Change the IP address directly on the interface. For example, if we want to change the IPv4 address of the lan interface to, we could use the CLI command:

    System:/> set Interface EthernetInterface if1 IPAddress=

    As explained next, this way of changing the IP address is not recommended.

  • Instead, the if1_ip object in the Address Book should be assigned the new address since it is this object that is used by many other objects such as IP rules. The CLI command to do this would be:

    System:/> set Address IPAddress if1_ip Address=

Assigning Multiple IP Addresses to an Interface

To assign multiple IPv4 addresses to an interface, assign multiple addresses to the interface's IP object in the address book. Assuming that two IPv4 addresses are defined in the address book as the objects ip1 and ip2 then the CLI for assignment would be:
System:/> set Address IPAddress if1_ip Address=ip1,ip2
If these multiple addresses belong to different networks then it will also be necessary to add an additional route in the relevant routing table since a route will only be added automatically for the first address.

When ip1 and ip2 are both IPv4 addresses belonging to different networks then those networks can also be assigned to the default network object for the interface. Using the example above, the CLI would be:

System:/> set Address IPAddress if1_net Address=ip1_net,ip2_net

Suppose that ip3 is an IPv6 address that is to be assigned to the if1 interface along with the IPv4 address object ip1. Assume also that there is already a corresponding network object defined called ip3_net. In this case a new address object for the interface network must also be defined. First, set the IP addresses for the interface as before:

System:/> set Address IPAddress if1_ip Address=ip1,ip3

Now, set the pre-existing IPv4 address object for the if1 interface network:

System:/> set Address IPAddress if1_net Address=ip1_net

No IPv6 network object exists for the interface so it must be added:

System:/> add Address IPAddress if1_ip6_net Address=ip3_net

Routes for IPv6 interface addresses are not added automatically so a route will also need to be added.

There is no limit to the number of addresses that can be assigned to an interface and this is true for any interface, not just Ethernet interfaces.

Enabling the DHCP Client Function

By default, all Ethernet interfaces have their IPv4 addresses allocated manually. However, any interface can have DHCP client functionality enabled for automatic assignment of IPv4 addresses and this is discussed further in Section 21.3, DHCP Client.

Enabling and Disabling an Ethernet Interface

To disable the interface if1 so that no traffic can flow through it, the CLI command is:
System:/> set Interface EthernetInterface if1 -disable
To enable the disabled interface, the command is:
System:/> set Interface EthernetInterface if1 -enable

Null Interfaces

If the Type property of an EthernetInterface is set to the value Null then the object can be said to be a null interface.

A null interface normally occurs because of either of the following:

  • The physical interface hardware is no longer present. This might occur when an expansion module is removed from hardware. In a virtual environment the equivalent to this is if a virtual interface is removed from the virtual machine.

  • The Ethernet interface becomes part of the list of interfaces assigned to the LAGMembers when the link aggregation feature is configured. This is discussed further in Section 3.7, Link Aggregation.

Regardless how a null interface comes about, it may still be referenced by other parts of the configuration. These references will still be valid but any object, such as an IPRule, that references a null interface will usually not perform any function. For example, if traffic is routed to a null interface then the traffic would simply go nowhere.

If the Type property reverts back to Ethernet then the interface will revert back to its original function.

The ifstat command can be used to show all null interfaces but only with the parameter -type set to a value of all or null. For example:

System:/> ifstat -type=null
Interface  Zone  IP Address     Type      Routing
---------  ----  -------------  ------    --------
if2        Null

3.2. VLAN


Virtual LAN (VLAN) support in cOS Stream allows the definition of one or more Virtual LAN interfaces which are associated with a particular physical interface. These are then considered to be logical interfaces by cOS Stream and can be treated like any other interface in rule sets and routing tables.

VLANs are useful in several different scenarios. A typical use is to allow one physical Ethernet interface to appear as multiple VLAN interfaces. This means that the number of available physical interface ports need not limit the number of connected external networks.

Another usage is to group together clients and/or hosts in an organisation so that the traffic belonging to different groups is kept completely separate in separate VLANs. Traffic can then only flow between the different VLANs under the control of cOS Stream and is filtered using the security policies described by the rule sets.

As explained in more detail below, VLAN configuration with cOS Stream involves a combination of VLAN trunks from the Clavister NetShield Firewall to switches and these switches are configured with port based VLANs on their interfaces. one or multiple VLANs.

[Note] Note: VLAN traffic can be combined with other traffic

Any physical interface can carry both non-VLAN traffic as well VLAN trunk traffic at the same time. A physical interface does not need to be devoted to VLAN traffic.

VLAN Processing

The Clavister NetShield Firewall follows the IEEE 802.1Q specification. The specifies how VLAN functions by adding a Virtual LAN Identifier (VLAN ID) to Ethernet frame headers which are part of a VLAN's traffic.

The VLAN ID is a number between 1 and 4094 which is used to identify the specific Virtual LAN to which each frame belongs. With this mechanism, Ethernet frames can belong to different Virtual LANs but can still share the same physical Ethernet link.

The following principles underlie the processing of VLAN tagged Ethernet frames at a physical interface:

  • Ethernet frames received on a physical interface by cOS Stream, are examined for a VLAN ID. If a VLAN ID is found and a matching VLAN interface has been defined for that interface, cOS Stream will use the VLAN interface as the logical source interface for further rule set processing.

  • If there is no VLAN ID attached to an Ethernet frame received on an interface then the frame is treated in the normal way and not as coming from a VLAN.

  • If VLAN tagged traffic is received on a physical interface and there is no VLAN defined for that interface in the configuration with a corresponding VLAN ID then that traffic is dropped by cOS Stream and an unknown_vlanid log message is generated.

  • The VLAN ID must be unique for a single physical interface but the same VLAN ID can be used on more than one physical interface. In other words, the same VLAN can span many physical interfaces.

  • A physical interface does not need to be dedicated to VLANs and can carry a mixture of VLAN and non-VLAN traffic.

VLAN Connections

The illustration below shows the connections for a typical VLAN scenario.

VLAN Connections

Figure 3.1. VLAN Connections

With VLANs, the physical connections are as follows:

  • One or more VLANs are configured on a physical Clavister NetShield Firewall interface and this is connected directly to a switch. This link acts as a VLAN trunk. The switch used must support port based VLANs. This means that each port on the switch can be configured with the ID of the VLAN or VLANs that a port is connected to. The port on the switch that connects to the firewall should be configured to accept the VLAN IDs that will flow through the trunk.

    In the illustration above the connections between the interfaces if1 and if2 to the switches Switch1 and Switch2 are VLAN trunks.

  • Other ports on the switch that connect to VLAN clients are configured with individual VLAN IDs. Any device connected to one of these ports will then automatically become part of the VLAN configured for that port. In Cisco switches this is called configuring a Static-access VLAN.

    On Switch1 in the illustration above, two interfaces are configured to be dedicated to VLAN1 and the third to VLAN2.

    The switch could also forward trunk traffic from the firewall into another trunk if required.

  • More than one interface on the firewall can carry VLAN trunk traffic and these will connect to separate switches. More than one trunk can be configured to carry traffic with the same VLAN ID.

Summary of VLAN Setup

Below are the key steps for setting up a VLAN interface.

  1. Assign a name to the VLAN interface.

  2. Select the interface for the VLAN. Either a physical interface or another VLAN object which has been configured as a service VLAN.

  3. Assign a VLAN ID that is unique on the physical interface.

  4. Optionally specify an IP address for the VLAN. If not specified, it defaults to the address of the associated interface.

  5. Optionally specify an IP broadcast address for the VLAN.

  6. Create the required route(s) for the VLAN in the appropriate routing table.

  7. Create rules in the IP rule set to allow traffic through on the VLAN interface.

For a standard, non-service VLAN, the Type property does not need to be specified. This is only required for a service (QinQ or stacked) VLAN. See Section 3.3, Service VLANs for more about this topic.

It is important to understand that the administrator should treat a VLAN interface just like a physical interface in that they require both appropriate IP rules and routes to exist in the configuration for traffic to flow through them. For example, if no IP rule with a particular VLAN interface as the source interface is defined allowing traffic to flow then packets arriving on that interface will be dropped.

Enabling the DHCP Client Function

By default, all VLAN interfaces have their IPv4 addresses allocated manually. However, any interface can have DHCP client functionality enabled for automatic assignment of IPv4 addresses and this is discussed further in Section 21.3, DHCP Client.

VLAN advanced settings

There is a single advanced setting for VLAN:

Unknown VLAN Tags

What to do with VLAN packets tagged with an unknown ID.

Default: DropLog

Example 3.1. Defining a VLAN

This example defines a VLAN called vlan_1 with a VLAN ID of 1. The IP address of the VLAN is assumed to be already defined in the address book as the object vlan1_ip.

Command-Line Interface

System:/> add Interface VLAN vlan_1

3.3. Service VLANs

To provide a VLAN solution in certain scenarios, it is possible to wrap traffic from multiple VLANs inside a single parent VLAN. This technique is referred to Q-in-Q VLANs or Stacked VLANs.

The same VLAN object is used to implement a Q-in-Q VLAN, with the Type property set to 88a8. The Type property corresponds to the TPID setting in the VLAN tag and this is explained further at the end of this section.

After the service VLAN object is defined, a non-service VLAN object can be placed inside it by setting its BaseInterface property to be the service VLAN object. This is demonstrated in the example below.

A Service VLAN Use Case

A Clavister NetShield Firewall can act as a terminator for a service VLAN. A typical use case for service VLAN termination is illustrated in the diagram below.

A Service VLAN Use Case

Figure 3.2. A Service VLAN Use Case

Here, corporate departments A and B each use two VLANs where the VLAN IDs 10 and 20 can be duplicated. A switch in each department connects it to another central corporate switch using the unique VLAN IDs 101 and 102. This central switch can now connect to the Clavister NetShield Firewall using a single service LAN which tunnels the 101 and 102 VLANs.

Defining a Service VLAN

A standard VLAN object is used to define a service VLAN but the Type property for the object is set to 0x88a8. This Type property corresponds to the TPID setting in the VLAN tag and this is explained further below.

After the service VLAN object is defined, a non-service VLAN object can be placed inside it by setting its Base Interface property to be the service VLAN object. This is demonstrated in the example below.

Example 3.2. Defining a Service VLAN

This example defines a service VLAN called svlan_A with an ID of 100 on the physical interface if3. The IP address will default to the IP of the physical interface.

Command-Line Interface

System:/> add Interface VLAN svlan_A

A VLAN object can now be added to this:

System:/> add Interface VLAN vlan1

The Complete List of Type Values

The complete list of values that can be used for the Type property in a VLAN object is shown below.

TPID (Hexadecimal) Decimal Equivalent Description
8100 33024 IEEE 802.1Q VLAN (the default)
88a8 34984 IEEE 802.1ad Service VLAN
9100 37120 0x9100 VLAN
9200 37376 0x9200 VLAN
9300 37632 0x9300 VLAN

The Type property specifies the Modified Tag Protocol Identifier (TPID) in the VLAN tag. The value is hexadecimal, so specifying 8100 for the Type corresponds to the hexadecimal number 0x8100.

Since the VLAN object defaults to a Type of 8100 (a standard VLAN), the only Type usually needed is 88a8 to specify a service VLAN. The last three entries in the list may be needed to provide interoperability with external equipment from some manufacturers.

Service VLANs within Service VLANs

The BaseInterface property of a service VLAN object can be another service VLAN object. In other words, one service VLAN can contain another service VLAN.

Although unusual beyond a couple of levels, cOS Stream permits up to 16 levels of nesting, with a VLAN object at the first level wrapped by a maximum of 15 levels of nested service VLAN objects.

3.4. Interface Groups

Any set of interfaces can be grouped together into an InterfaceGroup object. This can then be used in creating security policies in the place of a single group. When an InterfaceGroup is used, for example, as the source interface in an IP rule , any of the interfaces in the group could provide a match for the rule.

An InterfaceGroup can consist of ordinary Ethernet interfaces or it could consist of other types such as VLAN interfaces or VPN Tunnels. Also, the members of a group do not need to be the same type. For example, a group might consist of a combination of two Ethernet interfaces and a VLAN interface.

Configuration Usage of Interface Groups

An InterfaceGroup object can be referenced by the same object types and object properties that can reference the Zone object. A list of these can be found in Section 3.5, Zones.

Differences with Zones

The Zone object is similar to an InterfaceGroup object except that an interface points to a single Zone object whereas an InterfaceGroup points to one or more interfaces. Both can be used in a standalone firewall to provide a way to reference multiple interfaces with a single object. However, the Zone object is specifically designed to allow the deployment of a common configuration rule across multiple firewalls when they are under management by InCenter.

Example 3.3. Creating an Interface Group

This example creates an InterfaceGroup object with the two interface members if1 and if2.

Command-Line Interface

System:/> add Interface InterfaceGroup my_if_group Members=if1,if2

3.5. Zones

A Zone object is a means for grouping together interfaces. More specifically, it provides a means for grouping together both interfaces on a single firewall as well as interfaces across multiple firewalls when they are under management control by InCenter.

To define such a grouping of interfaces, a named Zone object is first created and then this is assigned to the Zone property of the interfaces within the zone. One interface can only reference a single zone but many interfaces may reference the same zone.

This is similar to the way InterfaceGroup objects are used. However, unlike an InterfaceGroup, which can refer to one or more interfaces, the referencing with zones is in the reverse direction and it is one-to-one; a single Zone object can be referred to by an interface.

The Intended Purpose of Zones with InCenter

The intended usage of zones, and why they are needed in addition to InterfaceGroup objects, is to be able to specify a global configuration rule in InCenter, such as an IPRule, which can then be deployed to multiple firewalls. The firewalls involved may have different interface types and naming but the zone membership of these interfaces will allow the deployed rule to be applied successfully.

When using zones in this way, the assignment of a zone to an interface should be done in InCenter after the firewall has been brought under centralized management device as a global device (which will reset the firewall's configuration to the factory default on import).

However, it is also possible for the feature to be used on a firewall not under InCenter control, as an alternative to using InterfaceGroup objects.

Object Types That Can Use Zones

Like an InterfaceGroup, a Zone can be referred to by Ethernet interfaces or it could be referred to by other interface types such as VLAN interfaces or IPsec Tunnels. In addition, different interface types can refer to the same Zone. For example, an Ethernet interface and a VLAN interface might have their Zone property set to the same Zone object.

A Zone object can be used in any of the following object types and properties:

  • SSLVPNServer - SourceInterface.
  • GRETunnel - SourceInterface.
  • IPsecTunnel - SourceInterface.
  • IPsecManualKeyedTunnel - SourceInterface.
  • IPRule - SourceInterface and DestinationInterface.
  • TrafficShapingRule - SourceInterface and DestinationInterface.
  • AccessRule - Interface.
  • RemoteMgmtSSH - SourceInterface and DestinationInterface.
  • RemoteMgmtSNMP - SourceInterface and DestinationInterface.
  • RemoteMgmtSNMP3 - SourceInterface and DestinationInterface.
  • BGPNeighbor - SourceInterface.
  • ThresholdRule - SourceInterface and DestinationInterface.
  • RoutingRule - SourceInterface.
  • WhitelistRule - SourceInterface.
  • IPSRule - SourceInterface and DestinationInterface.

Zones Appear in Log Messages

Where zones can be used with a configuration object, the zone settings will appear in log messages related to the object being triggered. Below is an example log message that shows this:
prio=warning id=00000 event=no_route_to_source srcip=fe80::1
pkt_flowdir=n/a pkt_srchw=00:50:56:c0:00:0b pkt_ipver=6 pkt_proto=UDP
pkt_recvif=if2 pkt_recvzone=FriendZone pkt_srcip=fe80::1
pkt_destip=ff02::1:2 pkt_srcport=546 pkt_destport=547 iface=if2
zone=FriendZone action=drop 

If an interface object property has not been assigned a zone object then it will appear as "n/a" in the log message (short for Not Assigned). The example log message below illustrates this:

prio=warning id=00000 event=no_source_route_for_packet
srchw=00:50:55:c0:00:0c srcip=fc03::64 destip=ff02::1:ff00:1
targetip=fc03::1 pkt_flowdir=n/a pkt_srchw=00:50:55:c0:00:0c
pkt_ipver=6 pkt_proto=ICMPv6 pkt_recvif=if3 pkt_recvzone=n/a
pkt_srcip=fc03::64 pkt_destip=ff02::1:ff00:1 pkt_type=135
pkt_code=0 pkt_id=0 iface=if3 zone=n/a action=drop 

Example 3.4. Creating a Zone and Setting a Reference to the Zone

This example creates a Zone called my_zone1 and then sets the interfaces if1 and if2 to belong to it. Finally, an IPRule object is created to allow traffic from my_zone1 to a second zone called my_zone2. It is assumed that my_zone2 has already been created and contains other interfaces.

Command-Line Interface

1. Create the new Zone object:

System:/> add Interface Zone my_zone1

2. Set interface if2 to belong to the zone:

System:/> set Interface EthernetInterface if1 Zone=my_zone1

3. Set interface if3 to belong to the zone:

System:/> set Interface EthernetInterface if2 Zone=my_zone1

4. Create an IP rule to allow traffic from my_zone1 to a second zone called my_zone2:

System:/> cc RuleSet IPRuleSet main
System:/IPRuleSet/main> add IPRule Action=Allow

3.6. Security/Transport Equivalence

Any interface, either physical or logical (for example, an IPsec tunnel or VLAN), has the property SecurityEquivalentInterfaces. By default, this has the value <empty> which means that both the incoming data and outgoing traffic for any data flow associated with the interface must be through that same interface, otherwise the traffic will be dropped by cOS Stream.

In some situations, however, it may be desirable that a flow's traffic leaves on one interface and arrives on a different interface. This might happen, for example, when using route failover or OSPF or with traffic to the Clavister NetShield Firewall coming from an external load-balancer. In these cases, the interfaces involved must have their SecurityEquivalentInterfaces property set to the other interfaces in the group which can be involved in a flow. All the interfaces in this group of interfaces are now said to be security/transport equivalent. Such a group must consist of at least 2 interfaces and could consist of several interfaces.

The following should be noted when using this feature:

  • Setting the SecurityEquivalentInterfaces interface property needs to be done only for a single interface in a group of interfaces since cOS Stream will automatically set the SecurityEquivalentInterfaces property for the other interfaces specified to the correct value.

  • To remove an interface from a group of security/transport equivalent interfaces, the SecurityEquivalentInterfaces interface property on just that one interface needs to be set to nothing. cOS Stream will then automatically update the other interfaces in the group so their SecurityEquivalentInterfaces property has that interface removed. If there were only two interfaces in the group to start with, both will no longer have their SecurityEquivalentInterfaces property set to a value.

Example 3.5. Setting the Security/Transport Equivalent Interface Property

Assume that the configuration has 3 Ethernet interfaces called if1, if2 and if3. All three are to be part of the same security/transport equivalent group.

Command-Line Interface

System:/> set Interface EthernetInterface if1

Suppose now that the interface if1 is to be removed from this group. This is done by setting the same property to no value (<empty>):

System:/> set Interface EthernetInterface if1

The interface if2 and if3 will still be part of the same security/transport equivalent group but now with only 2 members.

3.7. Link Aggregation


Where individual physical Ethernet interfaces of a firewall cannot provide the bandwidth required for a specific stream of traffic, it is possible to use the Link Aggregation feature to combine two or more physical interfaces together so they act as a single interface when connected to an external switch. This feature is sometimes referred to using the names Link Bundling or NIC Teaming.

Setting Up Link Aggregation

Link aggregation is configured in cOS Stream by setting the value of the LAGEnabled property of a single primary EthernetInterface object to a value of Yes. Other secondary EthernetInterface objects that will be part of this link aggregation are then assigned as a list to the primary interface's LAGMembers property. This list must also include the primary interface itself.

The following should be noted about the resulting aggregated interfaces:

  • The primary EthernetInterface object (with its LAGEnabled property enabled) will represent the aggregated interfaces in the configuration and can be referenced like a normal Ethernet interface. For example, the interface could be referenced by a Route or an IPRule object. cOS Stream will automatically spread traffic flows between all the physical interfaces that are part of the aggregation.

  • The logical name of the primary EthernetInterface object is automatically changed by cOS Stream so that it has the suffix "_lag". For example, the interface called if1 would become if1_lag.

    In addition, all references in the configuration to the original primary interface name will become references to the name with the _lag suffix and the name without the suffix can no longer be used in new references.

    Note that the address object names associated with the _lag interface are not changed.

  • The source IP address for all packets sent out on all the aggregated interfaces will be the IP address assigned to the primary _lag interface.

  • If the LAGEnabled property is later set to No, the primary interface name will not revert back to its original name.

  • The secondary aggregated interfaces that are specified in the LAGMembers property will be treated as null interfaces. This means that any other object that references them can still exist but will not have any function in the configuration.

    If a secondary interface is removed from the LAGMembers list, its Type property will be reset to its original value of Ethernet and the interface can again be used as a normal Ethernet interface.

    Null interfaces are discussed further at the end of Section 3.1, Ethernet Interfaces.

  • If desirable, it is possible to create a new logical primary EthernetInterface object that does not correspond to a physical interface, enable link aggregation on it and then add one or more actual physical interfaces as the secondary link aggregation members.

[Important] Important: Some changes require a system restart

The system will require a restart if changes are made to the interfaces that make up an aggregation. In other words, if a change is made to the properties LAGEnabled, LAGMembers or LAGMode.

An Example Use Case

An example use case for link aggregation is where the firewall might only have multiple one Gigabit Ethernet interfaces available but the traffic flow requirement is for a bandwidth of three Gigabits. Link aggregation can combine the capacities of separate physical interfaces into a single logical aggregated interface to meet this requirement.

The diagram below illustrates such a scenario, where three 1Gb networks need to communicate with a 10Gb network backbone through a firewall which has only 1Gb interfaces. Three of the firewall's 1Gb interfaces are connected to a single external switch and grouped into a single aggregated logical interface. The switch then provides the 10Gb link to the backbone.

A Link Aggregation Use Case

Figure 3.3. A Link Aggregation Use Case

Configuring the Mode

The LAGMode property of the primary link aggregation interface can be set to one of the following communication mode types, and this should match the way the connected external switch is configured:

  • The LACP (IEEE 802.3ad) type which uses negotiation between the switch and cOS Stream to manage traffic loading.

  • One of the static mode types which does not use negotiation with cOS Stream. Instead, different load balancing strategies can be selected and then implemented by cOS Stream.

These two mode types are explained next.

Using the LACP (IEEE 802.3ad) Mode

The LACP (Link Aggregation Control Protocol) mode means that the aggregation process is negotiated directly with the connnected switch. The switch must therefore also be configured to use LACP. With LACP, if a physical link become inoperative, cOS Stream will only try to send traffic over the remaining operational links.

The advantage of using LACP over one of the static modes is that cOS Stream will try to send a limited number of packets over the failed link before it switches to an alternate, working link. This means that the flow will not be dropped and the remote endpoint will experience only minor packet loss.

There are a number of interface properties that are specific to LACP and these are listed under the EthernetInterface object section of the separate CLI Reference Guide.

Using a Static Mode

When using one of the static modes, cOS Stream cannot know if one of the interfaces in the aggregation is not working and will try to send the traffic anyway. There is no negotiation taking place between cOS Stream and the connected switch. This means that on link failure, a flow can be dropped entirely.

However, selecting one of the static modes can provide specific properties to the traffic aggregation which can be desirable in particular circumstances. Any one of the following values can be assigned to the LAGMode property to determine the mode:

  • RoundRobin

    This provides load balancing and fault tolerance by transmission of packets in sequential order from the first available interface through to the last. Packets are bulk dequeued from devices then serviced in a round-robin manner. However, this does not guarantee the correct order and down-stream devices should be able to handle out of order packets.

  • ActiveBackup

    With this mode, only one interface in the aggregation is active at any one time. The initial interface to use is the primary interface but another initial interface can be designated using the LAGActiveBackupPrimary property. If this property is not set, the first interface in the LAGMembers list will be chosen as the active interface.

    A different interface becomes active only if the currently active interface fails. The next active interface selected is the next non-active interface in the list specified by the LAGMembers property.

    Note that the single logical interface’s MAC address is externally visible on only one physical port at a time to avoid confusing the connected switch.

  • BalanceXOR

    This provides transmit load balancing by selecting the sending interface based on a XOR calculation using the parameters specified by the LAGTxPolicy property. This means that packets with the same policy parameters are sent on the same interface. The LAGTxPolicy value choices along with the parameters that are combined to select the sending interface are the following:

    1. L2 - The source and destination MAC addresses (the default).

    2. L2L3 - The source and destination IP addresses.

    3. L3L4 - The source and destination IP addresses plus the TCP/UDP source and destination ports.

  • Broadcast

    This mode provides fault tolerance by transmitting packets on all aggregated interfaces.

  • BalanceTx

    This mode provides adaptive load balancing for data transmission. It dynamically assigns the transmitting interface based on loading. Statistics are collected in 100 milliseconds intervals and interface rebalancing is performed every 10 milliseconds.

  • BalanceRxTx

    This mode includes both adaptive transmit load balancing (described above) as well as receive load balancing. For receive load balancing, only the interface with the least load responds to the ARP message sent by the switch before the switch transmits the data.

All link aggregation related properties are listed under the EthernetInterface object section of the separate CLI Reference Guide.

Physical Interface Requirements

The following are the requirements for the physical Ethernet interfaces on the firewall that are aggregated together:

  • A maximum of 16 physical interfaces can be aggregated together into a single logical interface. In other words, the initial interface plus 15 other interfaces assigned as a list to the LAGMembers property.

  • All the physical interfaces that are aggregated together must operate at the same link speed.

  • All the physical interface connections for the aggregated interfaces must be connected to the same external switch.

Connecting to the External Switch

The physical cable links between the firewall and the external switch can be made either before or after defining link aggregation in a configuration and activating the changed configuration. cOS Stream will try to send data on the aggregated interfaces as soon as the configuration changes become active.

However, it is recommended that the physical cabling is in place before link aggregation is activated. This will provide the behavior which is expected from the feature and is particularly relevant if negotiated aggregation (LACP) is used.

Setting the Link Aggregation MTU Value

It is possible to set a specific MTU property value on the primary link aggregation interface and this value will then be used across all of its LAGMembers interfaces.

Setup with High Availability

When using link aggregation with HA, the flows from the Ethernet ports on each firewall in the HA cluster can connect to the same or different switches. However, if using the same switch, the switch must be configured so that the flows from each firewall are kept separate by creating two link aggregation groups in the switch.

Checking Link Aggregation Setup with the ifstat Command

When link aggregation has been set up, it is possible to check the status of the interfaces involved by using the ifstat CLI command with the interface name as a parameter. The output will be different depending on if the interface being viewed is the primary interface or if it is one of the member interfaces. The output for the primary interface will be different depending on if LACP is being used or if one of the static modes is used.

For example, suppose that the interface called lag1 is the primary interface and the other secondary members are the interfaces called if8 and if9. The following might be the first part of the output from the ifstat command for the primary interface when LACP is being used:

System:/> ifstat lag1
Interface lag1:
  IP Address     :
  Private IP     :
  Peer IP        :
  MAC            : 00:50:56:32:b6:89
  MAC HA Private : 10:00:00:0e:00:9d
  MAC HA Shared  : 10:00:00:0e:00:5d
  Driver         : bond
  Mode           : LACP (IEEE 802.1AX)
  Members        : if8 (link up) (up) [active, aggregation,
			synchronization, collecting, distributing]
                 : if9 (link up) (up) [active, aggregation,
			synchronization, collecting, distributing]
  Chksum offload : Unsupported
  Receive mode   : Promiscuous
  MTU            : 1500
  Routing Table  : main
  Zone           : <empty>
  Status         : 2 Gbps full duplex

The Mode line above indicates that LACP is being used. The Members line indicates the status of each of the members in the aggregation. The initial 3 fields in the line for each member are the following, in order with possible values:

  • Member interface name.

  • Physical link status - link up / link down.

  • LACP negotiation state - down / negotiating / mismatch / up.

When LACP is used, LACP flags are output inside square brackets (as shown above) and these can include any of the following in order:

  • active (initiating) / passive (listening).
  • aggregation - LCAP is enabled.
  • synchronization - Partner parameter synchronization.
  • defaulted - Partner parameters are defaulted.
  • collecting - Receiving.
  • distributing - Sending.
  • expired - Timed out.

For the interface if8, the ifstat command output indicates link aggregation membership with the LAG line. This is shown at the end of the partial ifstat output below:

System:/> ifstat if8
Interface if8:
  IP Address     :
  MAC            : 00:50:56:32:b6:89
  MAC HA Private : 10:00:00:0c:00:9d
  MAC HA Shared  : 10:00:00:0c:00:5d
  Device         : if8
  Driver         : em
  LAG            : lag1
  Chksum offload : Supported
  Receive mode   : Promiscuous
  MTU            : 1500
  Routing Table  : main
  Zone           : <empty>
  Status         : Link aggregation member (sink)

The LAG line does not indicate if LACP or a non-LACP mode is being used, only which primary interface it is an aggregated member of.

The following partial output from ifstat for the primary interface called lag2 shows how only the link status for each member is shown when a non-LACP (static) mode is used (in this case Balance XOR):

System:/> ifstat lag2
Interface lag2:
  IP Address     :
  Private IP     :
  Peer IP        :
  MAC            : 00:50:56:32:b6:89
  MAC HA Private : 10:00:00:0e:00:9d
  MAC HA Shared  : 10:00:00:0e:00:5d
  Driver         : bond
  Mode           : Balance XOR
  Members        : if8 (link up)
                 : if9 (link up)
  Chksum offload : Unsupported
  Receive mode   : Promiscuous
  MTU            : 1500
  Routing Table  : main
  Zone           : <empty>
  Status         : 2 Gbps full duplex

Example 3.6. Link Aggregation Setup

In this example, the Ethernet interface if1 will be the primary link aggregation interface. The secondary interfaces if2 and if3 will be aggregated as members with if1.

The distribution method over the three interfaces will be BalanceXOR based on the L2 policy (use source and destination MAC addresses).

Command-Line Interface

System:/> set Interface EthernetInterface if1

Any existing references to if1 will now become references to if1_lag and any new references should be to if1_lag. After activating the above change, the system must also be restarted.

To undo the aggregation, the command would be:

System:/> set Interface EthernetInterface if1_lag LAGEnabled=No

Note that after the above command, the if1_lag interface name will be unchanged and will not revert to if1. Note also that after activating this change, the system must also be restarted.

3.8. GRE Tunnels


The Generic Router Encapsulation (GRE) protocol is a simple, encapsulating protocol that can be used whenever there is a need to tunnel traffic across networks and/or through network devices.

Using GRE

GRE is typically used to provide a method of connecting two networks together across a third network such as the Internet. The two networks being connected together communicate with a common protocol which is tunneled using GRE through the intervening network. Some examples of reasons to use GRE might be the following:

  • Traversing network equipment that blocks a particular protocol.

  • Tunneling IPv6 traffic across an IPv4 network or tunneling IPv4 traffic across an IPv6 network.

  • Where a UDP data stream is to be multicast and it is necessary to transit through a network device which does not support multicasting, GRE can allow tunneling through the device.

GRE Security and Performance

A GRE tunnel does not use any encryption and is therefore not, in itself, secure. Any security must come from the protocol being tunneled. The advantage of GRE's lack of encryption is the high performance which is achievable because of the low traffic processing overhead.

The lack of encryption might be acceptable in some circumstances if the tunneling is done across an internal network that is not public.

Creating a GRE Tunnel

In cOS Stream, a GRE tunnel can be treated as a logical interface and has the same filtering, traffic shaping and other configuration capabilities as, for example, an Ethernet interface. Setting up a GRE tunnel requires the following steps:

  1. Create a new GRETunnel object. This requires at minimum, an IP address for both the local endpoint and the remote endpoint of the tunnel.

  2. Add a Route to the main routing table that routes traffic destined for the remote network into the tunnel.

  3. If required, add a Route that routes the tunnel endpoint IP address on the correct interface. This route is added to the routing table specified by the tunnel property RoutingTableMembership if it has been set. If it is not set, the main routing table is used by default.

[Caution] Caution: Check for possible looping in added routes

When configuring GRE routing, it is important to check that routes do not lead to looping of traffic. For example, outer GRE tunnel traffic routed back into the same tunnel.

Mandatory GRETunnel Properties

The following properties are required as a minimum when configuring a GRETunnel object:

  • LocalEndpoint

    This is the IP address of the tunnel's local endpoint. The address type can be IPv4 or IPv6 but the type must match the type of the RemoteEndpoint property. However, the traffic inside the tunnel could be either IPv4 or IPv6, regardless of the endpoint IP type.

  • RemoteEndpoint

    This is the IP address of the remote device which the tunnel will connect with.

Optional GRETunnel Properties

Some of the important optional properties that might be used with a GRE tunnel are the following:

  • IPAddress

    This is the IP address (either IPv4 or IPv6) of the local endpoint inside the tunnel on the local side. If not set, the default value is a zero address.

    The specified IP address could be used for any of the following example purposes:

    1. An ICMP Ping can be sent through the tunnel to this endpoint.

    2. The source IP address of log messages sent through the tunnel from the local tunnel interface.

    3. If NAT is being used then it will not be necessary to set the source IP on the IP rule that performs NAT on traffic going into the tunnel. This IP address will automatically be used as the source address for the outgoing traffic.

  • SourceInterface

    The interface or interfaces on which to listen for incoming GRE flows. More than one interface can be specified by using an InterfaceGroup object.

    If not specified, a value of any will be used for this property.

  • SessionKey

    A unique integer number can optionally be specified for a tunnel. This allows more than one GRE tunnel to run between the same two endpoints with this value used to distinguish between them. The session key used by each tunnel peer must match.

  • RoutingTableMembership

    This defines the routing table to be used for the traffic inside the tunnel. The Route object that is added to send the relevant traffic through the tunnel must be added to this routing table. If not specified, the main routing table will be used.

  • OuterRoutingTable

    This defines the routing table to be used for the outer tunnel traffic. In other words, for the tunnel setup itself. If not specified, the main routing table will be used.

A list of all properties can be found under the GRETunnel entry in the separate CLI Reference Guide.

GRE Tunnels and IP Rule Sets

Network traffic coming from the GRE tunnel will be transferred to the cOS Stream IP rule set for evaluation. The source interface of the network traffic will be the name of the associated GRE Tunnel.

The same is true for traffic in the opposite direction, that is, going into a GRE tunnel. Furthermore a Route has to be defined so that cOS Stream knows which traffic should be sent through the tunnel.

A Typical GRE Scenario

The diagram below shows a typical GRE scenario, where two firewalls labeled A and B must communicate with each other through the intervening internal network

A Typical GRE Scenario

Figure 3.4. A Typical GRE Scenario

Any traffic passing between A and B is tunneled through the intervening network using a GRE tunnel. Since the network is internal and not passing through the public Internet, there is no need for encryption.

The setup for the two firewalls are described next.

Part 1. Setup for firewall A

Assuming that the network is lannet on the lan interface, the steps for setting up cOS Stream on A are:

  1. In the address book set up the following IP objects:

    • remote_net_B:
    • local_gw:
    • remote_gw:
    • ip_GRE:

  2. Create a GRE Tunnel object called GRE_to_B with the following parameters:

    • IPAddress: ip_GRE
    • LocalEndpoint: local_gw
    • RemoteEndpoint: remote_gw
    • SessionKey: 1

  3. Define a route in the main routing table which routes all traffic to remote_net_B on the GRE_to_B GRE interface.
  4. Create the following entries in the IP rule set that allow traffic to pass through the tunnel:
Name Action Src Int Src Net Dest Int Dest Net Service
To_B Allow lan lannet GRE_to_B remote_net_B all_services
From_B Allow GRE_to_B remote_net_B lan lannet all_services

The CLI commands for firewall A setup are given in Example 3.7, “GRE Tunnel Setup”.

Part 2. Setup for firewall B

Assuming that the network is lannet on the lan interface, the steps for setting up cOS Stream on B are as follows:

  1. In the address book set up the following IP objects:

    • remote_net_A:
    • local_gw:
    • remote_gw:
    • ip_GRE:

  2. Create a GRE Tunnel object called GRE_to_A with the following parameters:

    • IPAddress: ip_GRE
    • LocalEndpoint: local_gw
    • RemoteEndpoint: remote_gw
    • SessionKey: 1

  3. Define a route in the main routing table which routes all traffic to remote_net_A on the GRE_to_A GRE interface.

  4. Create the following entries in the IP rule set that allow traffic to pass through the tunnel:

Name Action Src Int Src Net Dest Int Dest Net Service
To_A Allow lan lannet GRE_to_A remote_net_A all_services
From_A Allow GRE_to_A remote_net_A lan lannet all_services

Checking GRE Tunnel Status

IPsec tunnels have a status of being either up or not up. With GRE tunnels this does not apply. The GRE tunnel is considered established if it exists in the configuration.

However, it is possible to get more information about a GRE tunnel by using the ifstat CLI command. For example, if a tunnel is called gre_interface then the following command can be used:

System:/> ifstat my_gre_interface

Example 3.7. GRE Tunnel Setup

This example shows how to configure the GRE tunnel for firewall A from the setup scenario described previously in this section. The raw IP addresses will be used instead of references to address book objects.

Command-Line Interface

Add the GRE tunnel:

System:/> add Interface GRETunnel GRE_to_B

Add a route to send traffic to the remote network:

System:/> cc RoutingTable my_gre_rt
System:/RoutingTable/my_gre_rt> add Route Interface=GRE_to_B

The tunnel GRE_to_A would be configured in a similar way on firewall B.

3.9. Using Jumbo Frames

By default, Ethernet interfaces in cOS Stream operate with a default maximum packet payload size of 1500 bytes. By changing the global packet buffer size for cOS Stream, this maximum payload size can be increased for all interfaces. The size can be increased up to a maximum value of 9 kilobytes (9216 bytes), which corresponds to a maximum payload of 9000 bytes.

This ability to handle extra large packet sizes is a feature which is sometimes referred to as jumbo frames.

[Note] Note: Only virtual environments support jumbo frames

The jumbo frames feature is applicable only to virtual environments. Clavister hardware products do not support the feature.

Jumbo Frames Can Increase Throughput

Changing the packet buffer size to a value that matches the larger packet size of surrounding network equipment can increase overall firewall throughput since large packets may no longer need to be fragmented. However, increasing the buffer size will also increase the memory resources used.

It should also be noted that if packets much less than the increased packet buffer size need to be frequently processed, this could reduce throughput, so understanding the expected packet sizes is important.

Setting Up an Increased Packet Buffer Size

The following steps should be used to increase the packet buffer size:

  1. Change the global setting PacketBufferSize to a new value. For example, the following command will increase the buffer size for the system to the maximum value of 9 kilobytes:

    System:/> set Settings InterfaceSettings PacketBufferSize=9kB

    The value 9kB is a predefined value for this setting which can be used instead of specifying the number 9216. The other predefined values are 4kB (4096 bytes), and the value Default which is the standard size of 1522 bytes.

  2. Change the MTU on interfaces that will transmit the larger packet size. For example:

    System:/> set Interface EthernetInterface if1 MTU=9000

    Note that an MTU of 9000 would be used with the maximum packet buffer size of 9 kilobytes.

  3. Increase the maximum packet length for the relevant protocols. For example, to change the maximum TCP payload:

    System:/> set TCPSettings TCPMSSMax=8960

    To change IP payloads:

    System:/> set LengthLimSettings MaxTCPLen=8980

    System:/> set LengthLimSettings MaxOSPFLen=8980

    System:/> set LengthLimSettings MaxOtherSubIPLen=8980

  4. Following activation of these configuration changes, the system must be restarted so that memory is correctly reallocated.

Verified Features

The following cOS Stream features have been verified to function correctly with a larger packet buffer size:

  • Packet forwarding.
  • IPS scanning.
  • Threshold rules.
  • BGP.
  • OSPF.
  • VLANs.

Verified Ethernet Interface Hardware

The following Ethernet interfaces have been verified to function with the packet buffer sizes of 4 kilobytes and 9 kilobytes.

  • Intel™ 82599ES 10 GbE Controller (Dual-Port SFP+).

  • Mellanox ConnectX™-4 Lx EN MCX4121A-ACAT 25GbE Adapter (Dual-Port SFP28).

  • VirtIO.

Chapter 4: ARP

4.1. Overview

The ARP Protocol

Address Resolution Protocol (ARP) allows the mapping of a network layer protocol (OSI layer 3) address to a data link layer hardware address (OSI layer 2). In data networks it is used to resolve an IPv4 address into its corresponding Ethernet MAC address. ARP operates at the OSI layer 2, data link layer, and is encapsulated by Ethernet headers for transmission.

IP Addressing Over Ethernet

A host in an Ethernet network can communicate with another host only if it knows the MAC address of that host. Higher level protocols such as IP make use of IPv4 addresses which are fundamentally different from a lower level hardware addressing scheme like the MAC address. ARP is used to retrieve the Ethernet MAC address of a host by using its IP address.

ARP Resolution

When a host needs to resolve an IPv4 address to the corresponding Ethernet address, it broadcasts an ARP request packet. The ARP request packet contains the source MAC address, the source IPv4 address and the destination IPv4 address. Each host in the local network receives this packet. The host with the specified destination address, sends an ARP reply packet to the originating host with its MAC address.

4.2. The ARP Cache

The ARP Cache in network equipment, such as switches and firewalls, is an important component in the implementation of ARP. It consists of a dynamic table that stores the mappings between IPv4 addresses and Ethernet MAC addresses.

cOS Stream uses an ARP cache in exactly the same way as other network equipment. Initially, the cache is empty at startup and becomes populated with entries as traffic flows.

The typical contents of a minimal ARP Cache table might look similar to the following:

Type IPv4 Address MAC Address Expires
Dynamic 08:00:10:0f:bc:a5 45
Dynamic 0a:46:42:4f:ac:65 136
Static 4a:32:12:6c:89:a4 -

The explanation for the table contents are as follows:

  • The first entry in this ARP Cache is a dynamic ARP entry which tells us that IPv4 address is mapped to the MAC address 08:00:10:0f:bc:a5.

  • The second entry in the table dynamically maps the IPv4 address to the MAC address 0a:46:42:4f:ac:65.

  • The third entry is a static ARP entry binding the IPv4 address to the MAC address 4a:32:12:6c:89:a4.

The arp Command

The CLI provides the arp command to view entries in the ARP cache. The simplest form is used to view all entries:
System:/> arp -show
Using the arp command with no parameters is equivalent to this. A specific interface name can be included to show just entries for that interface. For example, the following command would show cache entries just for the if1 interface:
System:/> arp -show if1
All options for this command are described in the separate Clavister NetShield Firewall CLI Reference Guide.

Example 4.1. Displaying the ARP Cache

This example displays all current ARP cache entries for all interfaces.

Command-Line Interface

System:/> arp -show
                            ARP Cache

Iface  Type     Address           HWaddress          Expiration  
-----  -------  ----------------  -----------------   ----------  
if1    Dynamic    00:50:56:2c:5f:5b         389  
if2    Dynamic      00:50:56:d0:0f:01         580 
if3    Dynamic      00:50:56:d0:00:03         487

The Expiration Value

The last column in the example table and CLI output, Expiration, is used to indicate how much longer, in seconds, the ARP entry will be valid for.

For example, the first entry in the above CLI output has an expiry value of 389 which means that this entry will be rendered invalid and removed from the ARP Cache in 389 seconds from the current time. If traffic needs to be sent to the IPv4 address after expiration, cOS Stream will issue a new ARP request and update the cache with a new entry.

The default expiration time for dynamic ARP entries is 900 seconds (15 minutes). This can be changed by modifying the advanced setting ARPExpire.

Example 4.2. Changing the ARPExpire Setting

This example shows how to change the number of seconds for the ARPExpire setting.

Command-Line Interface

System:/> set Settings ARPTableSettings ARPExpire=1800
Modified ARPTableSettings.

The advanced setting ARP Expire Unknown specifies how long cOS Stream will remember addresses that cannot be reached. This limit is needed to ensure that cOS Stream does not continuously request such addresses. The default value for this setting is 3 seconds.

Example 4.3. Changing the ARPExpireUnknown Setting

This example shows how to change the number of seconds for the ARPExpireUnknown setting.

Command-Line Interface

System:/> set Settings ARPTableSettings ARPExpireUnknown=6
Modified ARPTableSettings.

Flushing the ARP Cache

If a host in a network is replaced with new hardware and retains the same IP address then it will probably have a new MAC address. If cOS Stream has an old ARP entry for the host in its ARP cache then that entry will become invalid because of the changed MAC address and this will cause data to be sent to the host over Ethernet which will never reach its destination.

After the ARP entry expiration time, cOS Stream will learn the new MAC address of the host but sometimes it may be necessary to manually force the update. The easiest way to achieve this is by flushing the ARP cache. This deletes all dynamic ARP entries from the cache and forces cOS Stream to issue new ARP queries to discover the MAC/IP address mappings for connected hosts.

Flushing can be done with the CLI command arp -flush.

Example 4.4. Flushing the ARP Cache

This example shows how to flush the ARP Cache from within the CLI.

Command-Line Interface

System:/> arp -flush
ARP cache of all interfaces flushed.

The Size of the ARP Cache

By default, the ARP Cache is able to hold 4096 ARP entries at the same time. This is adequate for most situations but on rare occasions, such as when there are several very large LANs directly connected to the firewall, it may be necessary to adjust this value upwards. This can be done by modifying the setting ARPCacheSize property in the ARPTableSettings object.

Example 4.5. Changing the ARP Cache Size

This example shows how to change the size of the ARP cache to hold 8192 entries.

Command-Line Interface

System:/> set Settings ARPTableSettings ARPCacheSize=8192
Modified ARPTableSettings.

Hash tables are used to rapidly look up entries in the ARP Cache. For maximum efficiency, a hash table should be twice as large as the entries it is indexing, so if the largest directly connected network contains 500 IP addresses, the size of the ARP entry hash table should be at least 1000. The administrator can modify the setting ARPHashSize to reflect specific network requirements. The default value of this setting is 512.

Example 4.6. Changing the ARP Hash Size

This example shows how to change the ARP hash size.

Command-Line Interface

System:/> set Settings ARPTableSettings ARPHashSize=1024
Modified ARPTableSettings.

4.3. Creating ARP Entries

To change the way ARP is handled on an interface, the administrator can create ARP objects, each of which has the following properties:


The type of ARP object. This can be one of:

  • Static - Create a fixed mapping in the local ARP cache.
  • Publish - Publish an IP address on a particular MAC address (or this interface).


The local physical interface for the ARP object.

IP Address

The IPv4 address for the MAC/IP mapping.

MAC Address

The MAC address for the MAC/IP mapping.

Static ARP Objects

A static ARP object can be used to insert a particular MAC/IP address mapping into the ARP cache.

The most frequent use of static ARP objects is in situations where some external network device is not responding to ARP requests correctly and is reporting an incorrect MAC address. Some network devices, such as wireless modems, can have such problems.

A frequent source of confusion is that this mode is not for publishing the address for external devices. Instead, static entries allow the administrator to tell cOS Stream how to reach external devices. The entry tells cOS Stream that a specific IPv4 address can be reached through a specific interface using a specific MAC address. This means, that when the firewall needs to communicate with the address it consults the ARP table static entries and can determine it can be reached at a specific MAC address on a specific interface.

This feature may also be used to lock an IP address to a specific MAC address for increasing security or to avoid denial-of-service if there are rogue users in a network. However, such protection only applies to packets being sent to that IP address. It does not apply to packets being sent from the IP address since the source MAC address can be forged.

Example 4.7. Creating a Static ARP Entry

This example will create a static mapping between IPv4 address and MAC address 4b:86:f6:c5:a2:14 on the if2 interface:

Command-Line Interface

First, change the context to be ARPEntries:

System:/> cc ARPEntries

Next, add an ARPEntry object to ARPEntries:

System:/ARPEntries> add ARPEntry

Finally return to the default, root context:

System:/ARPEntries> cc

ARP Publish

The Clavister NetShield Firewall supports publishing IP addresses on a particular interface. This can optionally be done along with a specific MAC address instead of the actual interface MAC address. cOS Stream will then send out these as ARP replies for any ARP requests received on the interface related to the published IP addresses.

This can be done for a number of reasons:

  • To give the impression that an interface has more than one IP address.

    This is useful if there are several separate IP spans on a single LAN. The hosts on each IP span may then use a gateway in their own span when these gateway addresses are published on the corresponding firewall interface.

  • Another use is publishing multiple addresses on an external interface, enabling cOS Stream to statically address translate traffic to these addresses and send it onwards to internal servers with private IPv4 addresses.

  • A less common purpose is to aid nearby network equipment responding to ARP in an incorrect manner.

Example 4.8. Publishing an ARP Entry

This example will create an ARPEntry that publishes the IPv4 address on the if1 interface:

Command-Line Interface

As in the previous example, change the context to be ARPEntries:

System:/> cc ARPEntries

Next, add an ARPEntry object to ARPEntries:

System:/ARPEntries> add ARP Interface=if1 IP= Mode=Publish

Finally return to the default, root context:

System:/ARPEntries> cc

Other ARP States

For troubleshooting purposes it is useful to understand some other possible ARP states. These can appear when using the ARP snoop feature, in log messages and also when looking at the ARP cache. Below is a summary:

  • Reslvng

    Processing an ARP request. A host with this IP has not yet been found.

  • Unknown

    No host with the IP was found.

  • Dynamic

    A host with the IP address was found.

  • Probing

    Currently testing that the host with the IP address is still available.

Chapter 5: IP Address Management

5.1. The Address Book

The Address Book contains named objects representing various types of IP addresses, including single IPv4 and IPv6 addresses, networks as well as ranges of addresses. Ethernet MAC addresses can also be defined in the address book.

[Note] Note: Network and prefix are synonymous

An IPv6 Prefix will often be referred to as the IPv6 Network in this guide. This is done to be consistent with the usage of the word Network with IPv4.

Address Book Benefits

Using address book objects has a number of important benefits:

  • It increases understanding of the configuration by referencing meaningful symbolic names.

  • Using address object names instead of entering numerical addresses reduces errors.

  • By defining an address object just once in the address book and then referencing this definition, changing the definition automatically also changes all references to it.

5.2. Address Types

The address book can contain the following Address object types:

  • IPAddress objects can contain IPv4 and/or IPv6 addresses.

  • EthernetAddress objects can contain MAC addresses. This can be further grouped together into EthernetAddressGroup objects.

IPAddress Objects

IPAddress objects are used to define symbolic names for various types of IP addresses, either IPv4 or IPv6 or mixed IPv4/IPv6. Depending on how the address is specified, an IP Address object can represent either a single IPv4 or IPv6 address (a specific host), a network or a range of IP addresses and even a DNS name.

Values for the Address Property of an IPAddress

The Address property holds the IP address values of an IPAddress object. The property can be set to a list of addresses which can be any mixture of the following types:

  • A Single Host

    A single host is represented simply by its IP address. This can be either an IPv4 or IPv6 address. For example,

    It is also possible to specify a comma separated list of hosts and these can be a mixture of IPv4 and IPv6 addresses. For example,,,2001:DB8::1.

  • IP Network

    An IPv4 Network is represented using Classless Inter Domain Routing (CIDR) form. CIDR uses a forward slash and a number (0-32) to denote the size of the network as a postfix. This number corresponds to the number of binary ones in the netmask.

    The suffix /24 corresponds to a class C net with 256 addresses (netmask The suffix /27 corresponds to a 32 address net (netmask and so on.

    For IPv6, the IPv6 prefix corresponds to the network. For example, 2001:db8::/32.

  • IP Ranges

    A range of IPv4 addresses is represented with the form a.b.c.d-e.f.g.h.

    Note that ranges are not limited to IPv4 netmask boundaries. They may include any span of IP addresses.
    For example, represents six IPv4 hosts in consecutive order.

    A range of IPv6 addresses is specified in the same way. For example, 2001:DB8::1-2001:DB8::6

[Note] Note: A maximum of 256 address items are allowed

The Address property of a single IPAddress object can hold a maximum of 256 address items, which can be any combination of the types listed above. A range or network is counted as a single item.

Adding and Displaying IPAddress Objects

The CLI command format for adding an IP address is:
System:/> add Address IPAddress <name> Address=<ip-address>
To display the value(s) assigned to an address object:
System:/> show Address IPAddress <name>
Alternatively, the netobjects command can be used:
System:/> netobjects <name>
Using the netobjects command without any options will display all IP address objects in the address book.

Example 5.1. Adding a Single IP Address

This example adds the IP host www_srv1 with IPv4 address to the address book:

Command-Line Interface

System:/> add Address IPAddress www_srv1 Address=

Example 5.2. Adding an IP Network

This example adds an IP network named wwwsrvnet with address to the address book:

Command-Line Interface

System:/> add Address IPAddress wwwsrvnet Address=

Example 5.3. Adding an IP Range

This example adds a range of IPv4 addresses from to and names the range wwwservers:

Command-Line Interface

System:/> add Address IPAddress wwwservers

Example 5.4. Deleting an Address Object

To delete an object named wwwsrv1 in the address book, do the following:

Command-Line Interface

System:/> delete Address IPAddress wwwsrv1

Deleting Referenced IP Address Objects

If an IP address object is deleted that is in use by another object, the deletion will appear successful. However, cOS Stream will not subsequently allow the configuration to be deployed and will generate an error message.

The CLI -references option can be used when displaying an IP address to list references to the address. For example, to find all references to the address object if1_ip, the CLI command would be:

System:/> show IPAddress if1_ip -references

EthernetAddress Objects

EthernetAddress objects are used to define symbolic names for MAC addresses. This is useful, for example, when populating the ARP table with static ARP entries, or for other parts of the configuration where symbolic names are preferred over hexadecimal MAC addresses.

When specifying an Ethernet MAC address, the format aa-bb-cc-dd-ee-ff should be used. Ethernet MAC addresses are also displayed using this format.

EthernetAddress objects can be further grouped together into EthernetAddressGroup objects.

Example 5.5. Adding an Ethernet Address

The following example adds an Ethernet Address object named wwwsrv1_mac with the numerical MAC address 08-a3-67-bc-2e-f2.

Command-Line Interface

System:/> add Address EthernetAddress wwwsrv1_mac

5.3. Auto-generated Address Objects

To simplify the configuration, a number of address objects in the address book are automatically created by cOS Stream when the system starts for the first time and these objects are used in various parts of the initial configuration.

Generated Objects

The following address objects are auto-generated by cOS Stream:

Interface Addresses

For each Ethernet interface in the system, two IPv4 Address objects are predefined; one object for the IP address of the actual interface, and one object representing the local network for that interface.

Interface IPv4 address objects are named <interface-name>_ip and network objects are named <interface-name>_net. As an example, an interface named if1 will have an associated interface IP object named if1_ip, and a network object named if1_net.


The all-nets-ip4 IPv4 address object is initialized to the IPv4 address, which represents all possible IP4 addresses. The all-nets-ip4 IP object is used extensively in the configuration and it is important to understand its significance.

The all-nets-ip6 object performs the same function as all-net-ip4 but for the IP6 address space.

The all-nets object includes all IP4 and IP6 addresses.

The netobjects command shows the current address book contents. For example:

System:/> netobjects
all-nets, ::/0  
all-nets-ip6  ::/0

Assigning Multiple IP Addresses to an Interface

As discussed in Section 3.1, Ethernet Interfaces, it is possible to assign multiple addresses to a single Ethernet interface. This is done by assigning the addresses to the interface's address object. For example:
System:/> set Address IPAddress if1_ip Address=,
There is no limit to the number of addresses that can be assigned to a single Ethernet interface.

5.4. IPv6 Support

The IP address standard IPv6 is designed as a successor to IPv4 with the principal advantage of providing a much larger address space. Among many other benefits, the large number of available global IPv6 addresses means that NAT should no longer required for sharing a limited number of public addresses.

IPv6 is usable with most configuration objects. A list of usage restrictions can be found later in this section.

IPv6 is Enabled by Default

By default, the Clavister NetShield Firewall supports IPv6 and this does not need to be explicitly enabled. If all IPv6 traffic is to be ignored, the following command can be used:
System:/> set Settings IPSettings AllowIPVersion=IPv4
This allows only IPv4 packets to be processed and all IPv6 packets will be dropped. Conversely, if all IPv4 packets are to be dropped and only IPv6 recognized, the CLI command would be:
System:/> set Settings IPSettings AllowIPVersion=IPv6
To return to the original, default situation where both IPv4 and IPv6 are processed, the command would be:
System:/> set Settings IPSettings AllowIPVersion=Any

Adding an IPv6 Address

IPv6 address objects are created in the address book in a similar way to IPv4 addresses.

For IPv6, only the all-nets-ip6 object (IPv6 address ::/0) exists by default in the address book. This means that the IPv6 address and network objects associated with interfaces must be created manually.

Example 5.6. Adding an IPv6 Address

This example adds a new address object called my_ip6_address to the address book with the single IPv6 address 2001:DB8::1.

Command-Line Interface

System:/> add Address IPAddress my_ip6_address Address=2001:DB8::1
[Note] Note: The prefix 2001:DB8::/32 is reserved for documentation

As described in RFC3849, the IPv6 prefix 2001:DB8::/32 is specifically reserved for documentation. All IPv6 examples in this guide use this network or addresses from it.

Enabling IPv6 on an Interface

Predefined address book objects already exist for each Ethernet interface. To enable IPv6 on an interface, an IPv6 address and network (prefix) are added to the associated address book objects.

This could be done specifying a comma separated list of the IPv4 address and the IPv6 address for the interface. However, the recommendation is to create a separate IPAddress object for the IPv6 address and add that to the interface.

If an IPv6 address and network are not assigned, IPv6 packets arriving at the interface are always dropped.

Example 5.7. Enabling IPv6 on an Interface

Assume that the interface if1 is to have the IPv4 address with network IPv6 is to be enabled on the interface with the IPv6 address 2001:DB8::1 from the network 2001:DB8::/32.

Command-Line Interface

Set the default address object for the interface to the IPv4 address.

System:/> set Address IPAddress if1_ip Address=

Add an IPv6 address object for the interface:

System:/> add Address IPAddress if1_ip6_ip Address=2001:DB8::1

Set the IPv4 and IPv6 addresses directly on the interface:

System:/> set Interface EthernetInterface if1 IPAddress=if1_ip,if1_ip6_ip

Set the IPv4 network for the interface:

System:/> set Address IPAddress if1_net Address=

Add a new object for the IPv6 network associated with the interface:

System:/> add Address IPAddress if1_ip6_net Address=2001:DB8::/32

The route for the IPv6 must now be added manually:

System:/> cc RoutingTable main
System:/RoutingTable/main> add Route Interface=if1 Network=if1_ip6_net
System:/RoutingTable/main> cc

[Tip] Tip: Use period plus tab when appending an address

When using the CLI set Address IPAddress command, the objective can be to append a new IP address value to any existing values.

All the existing values can be displayed by using the key sequence of a period ( . ) followed by a tab after Address=. A comma ( , ) can then be typed followed by the new address to be added to the list.

IPv6 Interface Routes are Not Added Automatically

When an IPv6 address and network are assigned to an Ethernet interface (both are required) then an IPv6 route for that interface should be added manually to the main routing table. The route cannot be added automatically.

IP Rules Can Mix IPv4 and IPv6

There is no requirement in cOS Stream to have separate IP rules that refer to IPv4 and IPv6 address objects. It is valid to use an IPAddress that combines both IPv4 and IPv6 addresses in a single IP rule.

However, an IP rule that has only IPv4 as its source and only IPv6 as its destination will not have any useful function. It is not possible, however, to mix IPv4 and IPv6 on a single route. Separate routes must be created.

Grouping IP Addresses

Since an IPAddress object can contain any number of IPv4 or IPv6 addresses as well as references to other IPAddress objects, these are used to create grouping of IP addresses. There is no special group address object in cOS Stream.

The all-nets Address Object

The preconfigured all-nets-ip4 address object is a catch-all object for all IPv4 addresses. Similarly, all-nets-ip6 represents all IPv6 addresses and only IPv6 addresses.

To represent all IPv4 and IPv6 addresses, all-nets-ip4 is combined with all-nets-ip6 in the single predefined object all-nets.

IPv6 Neighbor Discovery

IPv6 Neighbor Discovery (ND) is the IPv6 equivalent of the ARP protocol with IPv4 (see Chapter 4, ARP).

When IPv6 is enabled for a given Ethernet interface, cOS Stream will respond to any IPv6 Neighbor Solicitations (NS) sent to that interface with IPv6 Neighbor Advertisements (NA) for the IPv6 address configured for that interface.

Enabling neighbor discovery for other IP addresses on an interface can be achieved by adding an NDEntry object to the NDEntries list. The NDEntries object exists by default as an empty list and does not need to be created. The example below demonstrates adding an NDEntry to the list.

Example 5.8. Enabling Interface Neighbor Discovery

This example will create an NDEntry that publishes the IPv6 address my_ipv6 on the if3 interface:

Command-Line Interface

First, change the context to be NDEntries:

System:/> cc NDEntries

Next, add an NDEntry object to NDEntries:

System:/NDEntries> add NDEntry Interface=if3 IP=my_ipv6

Note that the default value for the Mode property is Publish.

Finally, return to the default, root context:

System:/NDEntries> cc

Enabling IPv6 Router Advertisements

An additional option for an Ethernet or VLAN interface is to enable IPv6 Router Advertisement. This is the IPv6 equivalent of an IPv4 DHCP server and it means that any external client connected to the interface can solicit and receive IPv6 messages to perform Stateless Address Auto-Configuration (SLAAC). The SLAAC process allows the client to create its own unique global IPv6 address based on the MAC address of its interface and the prefix of the IPv6 address for the interface it is connected to.

Enabling router advertisements in cOS Stream is done by enabling the AdvertiseIP property for a single Route object in a routing table. This enables advertisements on the interface specified in that route and only for the host or network specified in that route.

Example 5.9. Enabling IPv6 Advertisements

This example enables IPv6 advertisements on the route if1_route in the routing table main.

Command-Line Interface

First, change the current context to be the main routing table:

System:/> cc RoutingTable main

Now, enable router advertisements on the target route:

System:/RoutingTable/main> set if1_route AdvertiseIP6=yes

Finally, return to the default CLI context:

System:/> cc

Some of the values in the router advertisement are controlled by an object called a RouterAdvertisementProfile. This is assigned to the RouterAdvertisementProfile property of the interface. Initially, the value DefaultProfile is always assigned to this property for all interfaces. This uses the default values for a new RouterAdvertisementProfile object but does not correspond to an editable object in the system.

If the default values provided by the DefaultProfile value are not satisfactory, the following steps must be used:

  • Create a new RouterAdvertisementProfileTable object.

  • Add a new RouterAdvertisementProfile object to the table with the desired settings.

  • Associate this profile object with the interface.

Note that the value of the RouterAdvertisementProfile property for an interface only has meaning if the AdvertiseIP6 property of an associated route is enabled. It is enabling the AdvertiseIP6 property of the Route object that turns on router advertisements and not a profile assigned to the interface.

Enabling Automatic Interface Address Configuration

Another option for an Ethernet or VLAN interface is to enable automatic IPv6 Address Configuration of the interface. This is essentially the reverse of the Router Advertisement feature described above and can provide a means to automatically assign IPv6 addresses. When enabled, the following properties of the interface object can be automatically assigned by an external device that is sending out router advertisements:

  • IPAddress (address book object ifn_ip).
  • IPv6Network (address book object ifn_ip6_net).
  • IPv6DNS (address book object ifn_ip6_dns).
  • IPv6Gateway (address book object ifn_ip6_gw).

This option is enabled by setting the IPv6AddressConfiguration property to the value SLAAC. The default value for this property is Static which means that the properties listed above must get their values assigned manually by changing the corresponding address objects (these are also listed above). Out of these address book objects, only ifn_ip exists by default. The other address objects listed are automatically created by cOS Stream at the time that the IPv6AddressConfiguration property is set to SLAAC.

Example 5.10. Enabling Automatic Address Configuration

This example shows how to enable automatic address configuration on the if1 interface.

Command-Line Interface

System:/> set Interface EthernetInterface if1

The ND Cache and ndp Command

Like ARP, the IPv6 neighbor discovery mechanism in cOS Stream maintains a Neighbor Discovery Cache (ND cache). This cache can be displayed and managed using the ndp CLI command.

To display the entire cache use the command:

System:/> ndp -show
Neighbor cache of iface if1:
    Stale  fc01:6:13::1   = 77:2b:cb:8d:72:de   Expire=5033

Neighbor cache of iface if2:
     Good  fc01:22:13::1  = 00:1b:23:b1:d7:4f   Expire=28

To flush the entire cache use the command:

System:/> ndp -flush

A gratuitous neighbor discovery can be sent on an interface with a specified IP address with the command:

System:/> ndp -notify <if> -ip=<address>

The ndpsnoop Command

The ndpsnoop command will provide real-time logging at the console of both router advertisements and router solicitations. For example, to view all activity on the if1 interface.
System:/> ndpsnoop if1

All the options for the ndp and ndpsnoop commands can be found in the separate Clavister NetShield Firewall CLI Reference Guide.

IPv6 and IPsec

The Clavister NetShield Firewall supports the transport of either IPv4 or IPv6 over ESP. The ESP packets may themselves use either IPv4 or IPv6. This means that the local network and the remote network for an IPsec tunnel can be specified as IPv4 or IPv6 addresses. However, the local network and remote network must use the same IP version.

IPv6 and High Availability

The High Availability (HA) feature fully supports IPv6. Any IPv6 configuration objects will be mirrored on both the HA master and slave units including the NDP cache. If a failover occurs, state information will not be lost when one unit takes over processing from the other and IPv6 connections will not be lost.

In an HA configuration where interfaces have IPv6 enabled and IPv6 addresses assigned, there can be both a private and shared IPv6 address for each pair of interfaces. Each interface pair will have different private IPv6 addresses on the master and slave but will have the same shared IPv6 IP.

It is possible to have both an IPv4 and IPv6 shared IP address for the same interface. If this is the case, there must also be a private IPv4 and private IPv6 address for the individual interfaces in the pairing.

5.5. IPv6 With Embedded IPv4

cOS Stream allows the creation of IPv6 address objects in the address book which contain embedded IPv4 addresses. These IPv6 addresses can then be used anywhere in cOS Stream configuration where a normal IPv6 address would be used.

Embedding means that IPv6 addresses can be used on an IPv4 routing infrastructure that supports IPv6 tunneling.

Example 5.11. Adding an IPv6 Address with Embedded IPv4

This example adds two IPv6 addresses with the prefix 2001:db8::/32 (the documentation prefix) to the address book. The first has has the embedded IPv4 network and the second has the embedded host address 2013.0.113.10.

Command-Line Interface

System:/> add Address IPAddress my_mixed_net Address=2001:db8::

Next, add the IPv6 address 2013.0.113.10 from this network:

System:/> add Address IPAddress my_mixed_addr Address=2001:db8::

Specifying an IPv4 Mapped IPv6 Address

When IPv4 embedding is used, cOS Stream creates an IPv4 compatible IPv6 address object which consists of 96 zeros followed by the IPv4 address and this address type should be used as the addresses for IPv6 capable network devices.

However, if a network device is not IPv6 capable then it should have an IPv4 mapped IPv6 address which consists of 80 zeros followed by 16 ones followed by the IPv4 address. These preceding 16 ones for this type of address must be explicitly specified when creating the address object in cOS Stream. For example, by specifying the embedded IPv4 address as 2001:db8::ffff:

5.6. FQDN Address Objects


Instead of specifying an address object to be an IP address, it can instead be specified as an FQDN (for example: cOS Stream will then automatically resolve the FQDN to an IP address at runtime if the FQDN address object is referenced by another configuration object.

Specifying FQDN Address Objects

An FQDN address object is created by assigning the FQDN value to the IP property of an IPAddress object:
System:/> add Address IPAddress my_fqdn_ip
The requirement for DNS resolution of an FQDN can also be written explicitly:
System:/> add Address IPAddress my_fqdn_ip
Instead of the FQDN, just the domain name could be used but it requires the dns: prefix:
System:/> add Address IPAddress my_fqdn_ip Address=dns:example

The dns: Prefix Disables Format Checking

The dns: prefix seen in the examples above has a secondary function which is to turn off format checking of the FQDN. Without the prefix, cOS Stream will reject any FQDN that appears to be malformed, for example, because of unusual characters. Using the dns: prefix will force cOS Stream to accept any string value.

[Note] Note: Wildcarding in FQDNs is not supported

Wildcards cannot be used when specifying the FQDN in an FQDN address object. The reason is that cOS Stream populates the FQDN cache by itself sending queries to a DNS server. If an FQDN with wildcards, such as *, is sent to a DNS server, the server would not be able to resolve it.

Only IPRule Objects Can Use FQDN Address Objects

Currently, only IPRule objects can contain a reference to an FQDN address object.

It should be noted that as with any IPRule, it is not possible to have only IPv4 addresses on one side (source or destination) of the rule and only IPv6 addresses on the other side (destination or source). However, since FQDN resolution occurs at runtime, an FQDN address object may become an IP address type that contravenes this rule. If this happens there will a configuration error and the IPRule will be disabled with the following warning message generated:

   Inconsistent IP versions for source and destination IP Addresses

Direct FQDN Address References

It is possible to use FQDN address references in an IPRule object without first creating an intermediate IPAddress object. For example, consider the following addition of an IPRule that allows flows to
System:/> cc RuleSet IPRuleSet main
System:/IPRuleSet/main> add IPRule SourceInterface=lan
Here, the FQDN can be specified using the same rules that are described earlier for creating FQDN address objects.

FQDN Resolution Requires a Configured DNS Server

For FQDN address objects to function correctly, at least one external DNS server must be configured in cOS Stream by creating at least one DNS Server object in the cOS Stream configuration. For a description of configuring DNS servers in cOS Stream, see Chapter 12, DNS

The DNS Lookup Should Be Consistent

The administrator should ensure that the DNS lookup used for FQDN address objects referenced by IPRule objects returns the same results as the DNS lookup used by hosts that are affected by those policies. The best way to do this is to ensure that cOS Stream is using the same DNS server as the hosts it is protecting.

FQDN Address Object Activation Triggers FQDN Resolution

cOS Stream will try to perform the DNS resolution of FQDN address objects when a configuration is activated. This will happen even if no other object has a reference to the FQDN object.

If no DNS server is configured, cOS Stream will generate a warning when attempting to deploy a configuration with a reference to an FQDN address object.

FQDN Address Objects Can Store Multiple IPs

Depending on the FQDN, the DNS lookup can return both IPv4 and IPv6 addresses and there can up to 8 IPs of each type (16 in total) stored in the cache for a single FQDN.

FQDN Address Caching

cOS Stream uses a DNS cache to ensure that the same FQDN does not need to be resolved every time it is referenced. The current cache contents can be examined using the following command:
System:/> dns -list
However, a better method of displaying all the IP addresses being used for a particular FQDN address object is to display the full object properties:
System:/> show Address IPAddress <fqdn-address-object>
Alternatively, the netobjects command can be used:
System:/> netobjects <fqdn-address-object>

Cache Lifetimes

FQDN address objects differ to other types of cached DNS entries in that when the entry's TTL (Time To Live) expires, cOS Stream will refresh the cache entry by issuing a new DNS query. Setting the global minimum TTL and maximum TTL value is described in Chapter 12, DNS.

The global DNS object property called FQDNValidAfterTTLDefault is used only for FQDN address objects and it determines the minimum amount of time after the TTL has expired that an entry will stay in the cache. It has a default value of 86,400 seconds (one day). This can be relevant for consecutive DNS queries for the same FQDN which return different IP addresses because it ensures the multiple addresses will coexist.

The value of FQDNValidAfterTTLDefault can be overridden for an individual address object by setting the object's FQDNValidAfterTTL property:

System:/> add Address IPAddress my_fqdn_ip

Example 5.12. Adding an FQDN Address Object

This example shows how an FQDN address object called my_fqdn_ip1 is added to the cOS Stream address book.

The FQDN address object will contain the address for the FQDN It is assumed that a least one DNS server is already configured in cOS Stream so that the FQDN can be resolved to an IP address.

Command-Line Interface

System:/> add Address IPAddress my_fqdn_ip1

Example 5.13. Using FQDN Address Objects with an IP Rule

In this example, connections from internal clients on the if1_net network to the web site will not be allowed.

Command-Line Interface

A. Create the FQDN address object for

System:/> add Address IPAddress my_website_fqdn

B. Drop connections to the site:

System:/> cc RuleSet IPRuleSet main
System:/IPRuleSet/main> add IPRule SourceInterface=lan

Chapter 6: Routing

6.1. Principles of Routing

IP routing is one of the most fundamental functions of cOS Stream. Any IP packet flowing through a Clavister NetShield Firewall will be subjected to at least one routing decision at some point in time, and properly setting up routing is crucial for the system to function as expected.


IP routing is the mechanism used in TCP/IP based networks for delivering IP packets from their source to their ultimate destination through a number of intermediary network devices. These devices are most often referred to as routers since they perform the task of routing packets to their destination.

Routing Tables

In each router, one or more routing tables contain a list of routes and these are consulted to find out through which interface to send a packet so it can reach its intended destination.

There can be one or more routing tables. At a minimum, there is a single, predefined routing table called main. The interfaces of routes in these tables may be a physical Ethernet interface or it might be a configuration object that behaves like an interface such as a VPN tunnel.

Example 6.1. Listing the Routing Table main Contents

This example shows how to list the contents of the default routing table main.

Command-Line Interface

First, change the current context to be the main routing table:

System:/> cc RoutingTable main

Now, list the contents of the table:

System:/RoutingTable/main> show

   #  Interface  Network      Gateway  Local IP
   -  ---------  -----------  -------  -----------
   1  if2  <empty>

This shows that the main table contains a single route, which says that the network can be found on the interface if2.

The components of a single route in a routing table are discussed next.

The Components of a Route

When a route is defined it consists of the following properties:

  • Interface

    The interface to forward the packet on in order to reach the destination network. In other words, the interface to which the destination IP range is connected, either directly or through a router.

    The interface can be any logical interface. This includes Ethernet interfaces as well as VPN tunnels.

  • Network

    This is the destination network IP address range which is reached via the specified interface. The route chosen from a routing table is the one that has a destination IP range which includes the IP address being sought. If there is more than one such matching route, the route chosen is the one which has the smallest IP address range and lowest metric.

    The destination network all-nets-ip4 is usually always used in the route for public Internet access via an ISP. As its name suggests, all-nets-ip4 corresponds to all IP4 internet addresses and the route for this address is sometimes referred to as the default route since it is chosen when no other match can be found.

    It is not possible to mix IPv4 and IPv6 for this property.

  • Gateway

    The IP address of the gateway which is the next router in the path to the destination network. This is optional. If the destination network is connected directly to the interface, this is not needed.

    When a router lies between the Clavister NetShield Firewall and the destination network, a gateway IP must be specified. For example, if the route is for public Internet access via an ISP then the public IP address of the ISP's gateway router would be specified.

  • LocalIP

    This property usually does not need to be specified. If it is, cOS Stream responds to ARP queries sent to this address. A special section below explains this property in more depth.

  • Metric

    This is a metric value assigned to the route and is used as a weight when performing comparisons between alternate routes. If two routes are equivalent but have different metric values then the route with the lowest metric value is taken.

A Typical Routing Scenario

The diagram below illustrates a typical Clavister NetShield Firewall usage scenario.

A Typical Routing Scenario

Figure 6.1. A Typical Routing Scenario

In the above diagram, the LAN interface is connected to the network and the DMZ interface is connected to the network The WAN interface is connected to the network and the address of the ISP gateway to the public Internet is

The associated routing table for this would be as follows:

Route # Interface Destination Gateway
1 if1  
2 dmz  
3 wan  
4 wan all-nets-ip4

The above routing table provides the following information:

  • Route #1

    All packets going to hosts on the network should be sent out on the if1 interface. As no gateway is specified for the route entry, the host is assumed to be located on the network segment directly reachable from the if1 interface.

  • Route #2

    All packets going to hosts on the network are to be sent out on the dmz interface. For this route also, no gateway is specified since there is no "hop" via another router to the destination network.

  • Route #3

    All packets going to hosts on the network will be sent out on the wan interface. No gateway is required to reach this network.

  • Route #4

    All packets going to any host (the all-nets-ip4 network will match all hosts) will be sent out on the wan interface and to the gateway with IPv4 address That gateway will then consult its routing table to find out where to send the packets next.

    A route with its Network property set to all-nets-ip4 is often referred to as the Default Route since it will match all packets for which no specific route has been configured. This route usually specifies the interface which is connected to the public internet via an ISP.

    An equivalent default route for IPv6 traffic would have its Network property set to all-nets-ip6.

The Narrowest Routing Table Match is Selected

When a routing table is evaluated, the ordering of the routes is not important. Instead, all routes in the relevant routing table are evaluated and the most specific route is used. In other words, if two routes have destination networks that overlap, the narrower network definition will be taken before the wider one. This behavior is in contrast to IP rules where the first matching rule is used.

In the above example, a packet with a destination IPv4 address of will theoretically match both the first route and the last one. However, the first route entry is a narrower, more specific match so the evaluation will end there and the packet will be routed according to that entry.

Although routing table ordering is not important, it is still recommended for troubleshooting purposes to try and place narrower routes first and the default route last.

The LocalIP Property

The LocalIP property of a route is the source IP used for packets sent from the route's interface. This is automatically chosen by cOS Stream unless explicitly configured by the administrator.

When cOS Stream chooses the source IP automatically, it uses the IP address of the route's interface. If several IP addresses have been assigned to the interface, it takes the first address that is the same as or lies within the route's Network property. For example, if the first IPv4 address configured on the interface is, this will be chosen if the route's Network property is

If no match is found, cOS Stream takes the first address it finds that is the same IP type as the network. In other words, if the route's Network property is an IPv4 network, it takes the first IPv4 address assigned to the interface. If the network is an IPv6 network, it takes the first IPv6 address. If no such similar type is configured on the interface, the LocalIP property cannot be set and an event message is generated flagging this as an error.

Manually Setting the LocalIP Property

In some cases, the LocalIP needs to be set manually. Normally, a physical interface such as if1 is connected to a single network and the interface and network are on the same network. It can be said that the network is bound to a physical interface and clients on the connected network can automatically find the Clavister NetShield Firewall through ARP queries. ARP works because the clients and the interface are part of the same network.

A second network might then be added to the same physical interface via a switch, but with a new network range that does not include one of the physical interface's IP addresses. We would say that this network is not bound to the physical interface. Clients on this second network will not then be able to communicate with the Clavister NetShield Firewall because ARP will not function between the clients and the interface.

To solve this problem, a new route is added which has the following properties:

  • Interface: The interface on which the second network is found.
  • Network: The IP address range of the second network.
  • LocalIP: An address within the second network's IP range.

When the Default Gateway of the second network's clients is now set to the same value as the LocalIP of the above route, the clients will be able to communicate successfully with the interface. The IP address chosen in the second network is not significant, as long as it is the same value for the Default Gateway of the clients and the LocalIP.

The effect of adding the route with the LocalIP is that the firewall will act as a gateway with the LocalIP address and respond to, as well as send out, ARP queries as though the interface had that IP address.

The diagram below illustrates a scenario where this feature could be used. The IPv4 network is bound to a physical interface that has a single IPv4 address within the network of If we now attach a second network to the interface via the switch, it is unbound since none of the interface's IP addresses belong to it.

Using LocalIP with an Unbound Network

Figure 6.2. Using LocalIP with an Unbound Network

By adding a route for this second network with the LocalIP specified as, the interface will then respond to ARP requests from the network. The clients in this second network must also have their Default Gateway set to in order to reach the firewall.

This feature is normally used when an additional network is to be added to an interface but it is not desirable to change the existing IP addresses of the network. From a security standpoint, doing this can present significant risks since different networks will typically be joined together through a switch which imposes no controls on traffic passing between those networks. Caution should therefore be exercised before using this feature.

Example 6.2. Adding a Route with LocalIP

This example will show adding a route for the network on the interface if1 with LocalIP set as

System:/> cc RoutingTable main
System:/RoutingTable/main> add Route Interface=if1

System:/RoutingTable/main> cc

All Traffic Must have Two Associated Routes

Something that is not intuitive when trying to understand routing in cOS Stream is the fact that all traffic must have two routes associated with it. Not only must a route be defined for the destination network of a flow but also for the source network.

The route that defines the source network simply says that the source network is found on a particular interface. When a new flow is opened, cOS Stream performs a check known as a reverse route lookup which looks for this route. The source network route is not used to perform routing but instead as a check that the source network should be found on the interface where it arrived. If this check fails, cOS Stream generates a Disallowed by Access Rule error log message.

Even traffic destined for Core (cOS Stream itself), such as ICMP ping requests must follow the rule of having two routes associated with it. In this case, the interface of one of the routes is specified as Core.

6.2. Static Routing

The most basic form of routing is known as Static Routing. The term "static" is used because most entries in a routing table are part of the system's static configuration. They usually remain unchanged during long periods of system operation.

Due to this manual approach, static routing is most appropriate to use in network deployments where addresses are fairly fixed and where the amount of connected networks are limited to a few.

This section describes how to configure static routing and also explains how routing is implemented in cOS Stream.

Multiple routing tables are supported. A default table called main is predefined and is always present in cOS Stream. However, additional and completely separate routing tables can be defined by the administrator to provide alternate routing.

The Route Lookup Mechanism

The route lookup mechanism has some slight differences to how some other router products work. In many routers, where the IP packets are forwarded without context (in other words, the forwarding is stateless), the routing table is scanned for each and every IP packet received by the router. Packets are forwarded with state-awareness, so the route lookup process is tightly integrated into the stateful inspection mechanism.

When an IP packet is received on any of the interfaces, the list of active flows is consulted to see if there is already a flow to which the received packet belongs. If an existing flow is found, the flow information includes where to route the packet so there is no need for further lookups in the routing table. This is far more efficient than traditional routing table lookups, and is one reason for the high forwarding performance of cOS Stream.

If an established flow cannot be found, then the routing table is consulted. It is important to understand that the route lookup is performed before any of the various policy rules get evaluated (for example, IP rules). Consequently, the destination interface is known at the time cOS Stream decides if the flow should be allowed or dropped. This design allows for a more fine-grained control in security policies.

Route Notation

The Clavister NetShield Firewall uses a slightly different way of describing routes compared to most other systems but this way is easier to understand, making errors less likely.

Many other products do not use the specific interface in the routing table, but specify the IP address of the interface instead. The routing table below is from a Microsoft Windows workstation:

Interface List
0x1 ........................... MS TCP Loopback interface
0x10003 ...00 13 d4 51 8d dd ...... Intel(R) PRO/1000 CT Network
0x20004 ...00 53 45 00 00 00 ...... WAN (PPP/SLIP) Interface
Active Routes:
Network Destination        Netmask      Gateway    Interface Metric
     20      1     50     50     20      1     20     20     20     50     20      1      1
Default Gateway:
Persistent Routes:

The corresponding routing table in cOS Stream will be similar to the following:

Flags Network            Iface    Gateway        Local IP  Metric
----- ------------------ -------- -------------- --------- ------     if1                              20         wan                              1          wan             20

Note that multicast routes have not been included in the list but are displayed in the Microsoft listing.

Route Definition

The method of defining routes makes the reading and understanding of routing information easier.

A further advantage with the Clavister NetShield Firewall approach is that the administrator can directly specify a gateway for a particular route and the following is true:

  • A separate route does not need to be defined that includes the gateway IP address.

  • It does not matter even if there is a separate route which includes the gateway IP address and that routes traffic to a different interface.

Composite Subnets can be Specified

Another advantage with the Clavister NetShield Firewall approach to route definition is that it allows the administrator to specify routes for destinations that are not aligned with traditional subnet masks.

For example, it is perfectly legal to define one route for the destination IPv4 address range to and another route for IP addresses to This is a feature that makes cOS Stream highly suitable for routing in highly complex network topologies.

Displaying Routing Tables

It is important to note that routing tables that are initially configured by the administrator can have routes added, deleted and changed automatically during live operation and these changes will appear when the routing table contents are displayed.

These routing table changes can take place for different reasons. For example, if dynamic routing with OSPF has been enabled then routing tables will become populated with new routes learned from communicating with other OSPF routers in an OSPF network. Other events such as route failover can also cause routing table contents to change over time.

Example 6.3. Displaying the main Routing Table

This example illustrates how to display the contents of the default main routing table.

Command-Line Interface

To see the configured routing table:

System:/> cc RoutingTable main

System:/RoutingTable/main> show

   #  Interface  Network   Gateway        Local IP
   -  ---------  --------  -------------  --------
   1  wan        all-nets
   2  if1        if1_net
   3  wan        wan_net

To see the active routing table enter:

System:/> routes

Routing table: main

Flags Network            Iface         Gateway   Local IP Metric
----- ------------------ ------- --------------- -------- ------     if1                              0     wan                              0            wan           0
[Tip] Tip: The CLI cc command may be needed first

In the CLI example above, it was necessary to first select the name of a specific routing table with the cc command (meaning change category or change context) before manipulating individual routes. This is necessary for any category that could contain more than one named group of objects.

The all-nets Route

The most important route defined is the route to the network all-nets, which includes all IPv4 and IPv6 addresses. This route typically routes traffic to an ISP for public Internet access. In most examples in this publication, the all-nets-ip4 address object is used, which is the IPv4 subset of the all-nets address.

Core Routes

The Clavister NetShield Firewall automatically populates the active routing table with Core Routes. These routes are present for the system to understand where to route traffic that is destined for the system itself. There is one route added for each interface in the system. In other words, two interfaces named if1 and wan, and with IPv4 addresses and, respectively, will result in the following routes:

Route # Interface Destination Gateway
1 core  
2 core  

When the system receives an IP packet whose destination address is one of the interface IPs, the packet will be routed to the core interface. In other words, it is processed by cOS Stream itself.

There is also a core route added for all multicast addresses:

Route # Interface Destination Gateway
1 core  

6.3. Route Failover

6.3.1. Overview

The Route Failover feature is typically used in mission-critical situations where availability and connectivity are crucial. A typical example could be an enterprise where access to the Internet would be disrupted if a single flow to an external Internet Service Provider (ISP) fails. The solution would connectivity to a second ISP with route failover configured to use this second flow if the first fails.

This is illustrated in the diagram below, where there are different Ethernet interfaces and different routes being used to connect to ISP A and ISP B.

Route Failover Used for Internet Access

Figure 6.3. Route Failover Used for Internet Access

The Clavister NetShield Firewall implements route failover through the use of Route Monitoring in which cOS Stream monitors route connectivity by polling external hosts. cOS Stream will then switch traffic to an alternate route should this connectivity appear to be unavailable.

Setting Up Route Failover

To set up route failover, the following steps are required: Route Monitoring must be enabled and this is an option that is enabled on a route by route basis. To enable route failover in a scenario with a preferred and a backup route, the preferred route will have route monitoring enabled, however the backup route does not require this since it will usually have no route to failover to. When route monitoring is enabled for a route, one of the following monitoring methods must be chosen:

  • Decide on the route which requires a route failover if a network failure is detected. This will be sometimes referred to later as the primary route.

  • Make sure there is an alternate route in the route table to failover to. This route will not be chosen by default because of the value of its Metric property or because it has a wider Network property (cOS Stream will always choose the route with the narrowest fit for the destination IP).

  • Set up monitoring for the primary route. This can be one of the following two types:

    1. Gateway Monitoring

      If the Gateway property has been specified as the next router hop for the route, accessibility to that gateway can be monitored by sending periodic IPv4 ARP or IPv6 ND messages (depending on if it is an IPv4 or IPv6 route being monitored). As long as the gateway responds to these requests, the route is considered to be functioning correctly.

      Gateway monitoring is the quickest and easiest way for the administrator to set up monitoring and is described further in Section 6.3.2, Gateway Monitoring.

    2. Host Monitoring

      An alternative is to monitor the accessibility of one or more nominated hosts. These hosts might have known availability and polling them can indicate if traffic from the local Clavister NetShield Firewall is reaching them. Host monitoring also provides a way to measure the network delays in reaching remote hosts and to initiate failover to an alternate route if delays exceed administrator specified thresholds.

      A detailed discussion of host monitoring can be found in Section 6.3.3, Host Monitoring.

  • If the enabled monitoring method detects a connectivity failure, the route will be disabled and cOS Stream will search for an alternate route in the routing table.

Route Failover Processing

Once route monitoring is enabled, the processing steps are the following:

  • For every route with monitoring enabled, the designated host or hosts are monitored by polling.

  • Should monitoring indicate a problem with connectivity, the route is marked as disabled.

  • The system searches for an alternative route for the destination IP address. If one is found, that route is used for the traffic flow. If one is not found, traffic cannot flow.

  • The monitoring for the original route will continue even if the route is disabled. If monitoring indicates that connectivity is restored, the route will be re-enabled and used instead of the alternate route.

  • A restart will also cause a disabled route to be re-enabled. It can then be disabled if monitoring still indicates a connectivity problem.

Route failover processing is discussed further in Section 6.3.4, Route Monitoring Issues.

6.3.2. Gateway Monitoring

Gateway Monitoring is Simplified Host Monitoring

The idea with gateway monitoring is to provide a quick and easy way to enable host monitoring. Instead, gateway monitoring simplifies the process by requiring that only two Route object properties be set:

  • MonitorGateway

    When enabled, this will set up host monitoring to the IP address value specified by the Gateway property of the Route object. If the Gateway has not been set then setting MonitorGateway has no effect. By default, gateway monitoring is disabled. cOS Stream will use a predefined set of host monitoring settings that cannot be altered by the administrator. It will use the ARP/ND polling method.

    The following command will enable gateway monitoring for the second route (index=2) in the main routing table:

    System:/> cc RoutingTable main
    System:/RoutingTable/main> set Route 2
    System:/RoutingTable/main> cc

    The property RouteMonitor must always be enabled as well for both gateway monitoring and host monitoring.

  • GatewayMonitorInterval

    The time in milliseconds between each poll. This is the only gateway polling variable that can be set and it can be set in one of two ways. It can be set globally:

    System:/> set Settings RoutingSettings GatewayMonitorInterval=100

    Alternatively, it can be set just on the route itself:

    System:/> cc RoutingTable main
    System:/RoutingTable/main> set Route 2 GatewayMonitorInterval=100
    System:/RoutingTable/main> cc

    The command above assumes that the route being changed is the second one (index=2) in the routing table main.

Gateway polling and host monitoring can be enabled at the same time. Gateway monitoring could be also be set up by the administrator using host monitoring but if there is a requirement to have precise control over all the configurable options.

6.3.3. Host Monitoring


To provide a more flexible and configurable way to monitor the integrity of routes, cOS Stream provides the additional capability to perform Host Monitoring. This feature means that one or more external host systems can be routinely polled to check that a particular route is available.

The advantages of host monitoring are twofold:

  • In a complex network topology it is more reliable to check accessibility to external hosts. Just monitoring a link to a local switch may not indicate a problem in another part of the internal network.

  • Host monitoring can be used to help in setting the acceptable Quality of Service level of Internet response times. Internet access may be functioning but it may be desirable to instigate route failover if response latency times become unacceptable using the existing route.

Enabling Host Monitoring

Enabling host monitoring requires the following steps:

  • The RouteMonitor property of a Route object must be set to Yes. This is a prerequisite for either enabling gateway monitoring or host monitoring.

  • The MonitorHosts property of the same Route object must be set to Yes. This can be done in the same CLI command as the previous step.

  • One or more MonitorHost objects are added as children to the Route object. Each MonitorHost object specifies a single host to monitor and the monitoring settings for that host. Multiple hosts can provide a higher certainty that any network problem resides in the local network rather than because a single remote host is unreachable.

Settings in the Route Object

For host monitoring there are the following related properties for a Route object:

  • GracePeriod

    This is the period of time in seconds after startup or after reconfiguration of the Clavister NetShield Firewall which cOS Stream will wait before starting Route Monitoring. This waiting period allows time for all network links to initialize once the firewall comes online.

  • MinReachability

    This is the minimum number of hosts that must be considered to be accessible before the route is deemed to have failed. The criteria for host accessibility are described below.

  • GratuitousARPOnChange setting

    Send a gratuitous ARP or ND (depending on if the route is for IPv4 or IPv6) on the alternate route's interface to alert connected equipment of changes to MAC addresses and associated IP addresses. This is enabled by default and must be enabled for the alternate Route object.

Settings in the MonitoredHost Object

For each MonitoredHost object added to a Route object, there are a number of properties that should be set:

  • MonitoringMethod

    The method by which the host is to be polled. Currently, this can be:

    • ICMP - Polling using ICMP "Ping" messages. An IP address must be specified for this method and hosts must be configured to reply to such messages.

    • ARP/ND - This is used only for hosts that are on the same network as the Clavister NetShield Firewall. It works by sending either an IPv4 ARP query or an IPv6 Neighbor Discovery message to the host specified by the IP address. Which one is sent depends on the IP address type of the Route object's Network property.

  • IPAddress

    The IP address of the host when using the ICMP option. This will be either an IPv4 or an IPv6 address and this should agree with if the route is for an IPv4 or IPv6 network range.

  • OriginatorIP

    The source IP address used when polling a host. If not specified, the LocalIP property of the Route object will be used and if that is not set then the IP address of the sending interface IP will be used.

    Whichever source IP is used, its IP type (either IPv4 or IPv6) must agree with the IP type of the Network property of the Route object.

  • HostMonitorInterval

    The interval in milliseconds between polling attempts. The default setting is 1000 milliseconds and the minimum value allowed is 10 milliseconds.

  • Samples

    The number of polling attempts used as a sample size for calculating the Percentage Loss and the Average Latency. This value cannot be less than 1. The default value is 10.

  • MaxFailedSamples

    The maximum permissible number of polling attempts that fail. If this number is exceeded then the host is considered unreachable. The default value is 2.

  • MaxLatency

    The maximum number of milliseconds allowable between a poll request and the response. If this threshold is exceeded then the host is considered unreachable. Average Latency is calculated by averaging the response times from the host. If a polling attempt receives no response then it is not included in the averaging calculation.

  • ReachabilityRequired

    When this is selected, the host must be determined as accessible in order for that route to be considered to be functioning. Even if other hosts are accessible, this option says that the accessibility of a host with this option set is mandatory.

    Where multiple hosts are specified for host monitoring, more than one of them could have Reachability Required enabled. If cOS Stream determines that any host with this option enabled is not reachable, Route Failover is initiated.

Example 6.4. Setting Up Route Monitoring

This example will add route monitoring to the second route (index=2) in the main routing table. The monitoring will consist of polling two hosts on the same network. One host will be polled with ICMP and the other with ARP. If one host will not respond to ICMP because it is wrongly configured then we can check the other host's availability with ARP.

Change the CLI context to the main routing table.

System:/> cc RoutingTable main

Enable host monitoring:

System:/RoutingTable/main> set Route 2 RouteMonitor=Yes MonitorHosts=Yes

Change the CLI context to be the second route in the table:

System:/RoutingTable/main> cc Route 2

Add the first host monitor to the route which polls a host on the same network using ARP. The host is considered unreachable if 5 out of 15 attempts fails:

System:/RoutingTable/main/Route/2> add MonitoredHost

Add a second host monitor to the route which polls a remote host using ICMP (the default method). This host must be reachable:

System:/RoutingTable/main/Route/2> add MonitoredHost

Return to the original CLI context:

System:/RoutingTable/main> cc

6.3.4. Route Monitoring Issues

This section will discuss various issues that should be considered when setting up route monitoring.

Any Automatically Added Routes Will Need Redefining

It is important to note that route monitoring cannot be enabled on automatically added routes. For example, the routes that cOS Stream creates at initial startup for physical interfaces (these are known as core routes) are such automatically added routes. Routes added automatically during IPsec tunnel setup are also of this type.

The reason why monitoring cannot be enabled for these routes is because automatically created routes have a special status in a configuration and are treated differently. If route monitoring is required on an automatically created route, the original route should first be deleted and then it should be recreated manually as a new route. Monitoring can then be enabled on this newly created route.

Setting the Route Metric

When specifying routes, the administrator should manually set a route's Metric property. The metric is a positive integer that indicates how preferred the route is as a means to reach its destination. When two routes offer a means to reach the same destination, cOS Stream will select the one with the lowest metric value for sending data (if two routes have the same metric, the route found first in the routing table will be chosen).

A primary, preferred route should have a lower metric (for example "10"), and a secondary, failover route should have a higher metric value (for example "20").

Multiple Failover Routes

It is possible to specify more than one failover route. For instance, the primary route could have two other routes as failover routes instead of just one. In this case the metric should be different for each of the three routes: "10" for the primary route, "20" for the first failover route and "30" for the second failover route. The first two routes would have route monitoring enabled in the routing table but the last one (with the highest metric) would not since it has no route to failover to.

Failover Processing

Whenever monitoring determines that a route is not available, cOS Stream will mark the route as disabled and instigate route failover for existing and new flows. For already established flows, a route lookup will be performed to find the next best matching route and the flows will then switch to using the new route. For new flows, route lookup will ignore disabled routes and the next best matching route will be used instead.

The table below defines two default routes, both having all-nets as the destination, but using two different gateways. The first, primary route has the lowest metric and also has route monitoring enabled. Route monitoring for the second, alternate route is not meaningful since it has no failover route.

Route # Interface Destination Gateway Metric Monitoring
1 wan all-nets 10 On
2 wan all-nets 20 Off

When a new flow is about to be established to a host on the Internet, a route lookup will result in the route that has the lowest metric being chosen. If the primary WAN router should then fail, this will be detected by cOS Stream, and the first route will be disabled. As a consequence, a new route lookup will be performed and the second route will be selected with the first one being marked as disabled.

Re-enabling Routes

Even if a route has been disabled, cOS Stream will continue to check the status of that route. Should the route become available again, it will be re-enabled and existing flows will automatically be transferred back to it.

Route Interface Grouping

When using route monitoring, it is important to check if a failover to another route will cause the routing interface to be changed. If this could happen, it is necessary to take some precautionary steps to ensure that policies and existing flows will be maintained.

To illustrate the problem, consider the following configuration:

First, there is one IP rule that will NAT all HTTP traffic destined for the Internet through the wan interface:

Action Src Iface Src Net Dest Iface Dest Net Parameters
NAT if1 if1_net wan all-nets http

The routing table consequently contains the following default route:

Interface Destination Gateway Metric Monitoring
wan all-nets 10 Off

Now a secondary route is added over a backup DSL connection and Route Monitoring is enabled for this. The updated routing table will look like this:

Route # Interface Destination Gateway Metric Monitoring
1 wan all-nets 10 On
2 dsl all-nets 20 Off

Notice that route monitoring is enabled for the first route but not the backup, failover route.

As long as the preferred wan route is healthy, everything will work as expected. Route monitoring will also be functioning, so the secondary route will be enabled if the wan route should fail.

There are, however, some problems with this setup: if a route failover occurs, the default route will then use the dsl interface. When a new HTTP flow is then established from the intnet network, a route lookup will be made resulting in a destination interface of dsl. The IP rules will then be evaluated, but the original NAT rule assumes the destination interface to be wan so the new flow will be dropped by the rule set.

In addition, any existing flows matching the NAT rule will also be dropped as a result of the change in the destination interface. Clearly, this is undesirable.

To overcome this issue, potential destination interfaces should be grouped together into an InterfaceGroup object and the SecurityEquivalentInterfaces property of each interface should be set to the other interfaces in the group (see Section 3.6, Security/Transport Equivalence for more on this topic). This InterfaceGroup object will then used as the destination interface in IP rules. For more information on groups, see Section 3.4, Interface Groups.

6.4. Virtual Routing

6.4.1. Overview

Virtual Routing allows cOS Stream route lookup to be logically separated between different routing tables. This can be regarded as creating Virtual Routers within a single Clavister NetShield Firewall.

Enabling Virtual Routing

The following steps are needed to enable virtual routing:

  • Create one or more RoutingTable objects containing the routes that will be used for route lookup.

  • Associate an interface with a RoutingTable object by setting its RoutingTableMembership property. This means that all traffic received on the interface will be subject to route lookups in the designated table. Any reverse route lookups performed by cOS Stream will also be performed using the specified table.

Example 6.5. Associating an Interface with a Routing Table

In this example, the Ethernet interface if1 is associated with the routing table my_rtable.

System:/> set Interface if1 RoutingTableMembership=my_rtable

The Addition of Core Routes to Routing Tables

If the RoutingTableMembership is left at the default value of <all> then the core route for the interface (the route to the IP address of the interface) is automatically added to all RoutingTable objects. However, route lookup is only done using the main table.

If RoutingTableMembership is set to a specific RoutingTable object then the core route for the interface is only added to that routing table.

This is also true if the RoutingTableMembership is explicitly set to be the routing table main. If this is done, the core route is only added to the main table.

6.4.2. A Simple Virtual Routing Scenario

This section examines a simple scenario where virtual routing might be used. Consider a single Clavister NetShield Firewall connected to two external ISPs called ISP1 and ISP2.

ISP1 provides Internet connection to Department A and connects to the Clavister NetShield Firewall via the physical interface if1.

ISP2 provides Internet connection to Department B and connects via the physical interface if2. Using virtual routing, the Clavister NetShield Firewall is to be divided into 2 separated virtual routers, one for each ISP.

The virtual routers are set up using two dedicated routing tables, one called RT1 for ISP1 and Department A traffic. A second routing table called RT2 deals with ISP2 and Department B traffic.

The interface if1 is associated with RT1. Interface if2 is associated with RT2.

Reusing Internal IP Addresses

An advantage of using separate routing tables on different interfaces is that internal IP address ranges can be reused. For example, Department A and Department B could both use the internal network

Since route lookup is done in separate routing tables, there are no conflicts.

VPN Tunnels are Logical Interfaces

VPN tunnels are also considered to be interfaces in cOS Stream and can therefore also be associated with their own routing tables just as physical interfaces can.

6.4.3. IPsec Virtual Routing

Virtual Routing is supported for IPsecTunnel objects. This is implemented by being able to assign different routing tables for encrypted traffic inside the tunnel and the IKE/IPsec traffic outside the tunnel. The different routing tables can be assigned using an IPsecTunnel object's RoutingTableMembership and OuterRoutingTable properties.

This separation of routing between tunnels allows the complete separation of the traffic that flows through them and also allows the reuse of IP address ranges across tunnels.

Virtual Routing Setup with IPsec

To enable virtual routing for IPsec, the following properties should be assigned suitable values for each IPsecTunnel object:

  • RoutingTableMembership

    This is the routing table for the "inner" encrypted tunnel traffic. The predefined main routing table might be used for this purpose in some cases.

  • OuterRoutingTable

    This is the routing table for the tunnel's "outer" IKE and IPsec traffic. It specifies which routing table the source interface is to be a member of (in case it is found in multiple routing tables).

    Note that cOS Stream can also handle the unusual case of asymmetric routing where the incoming and outgoing traffic for a flow can use different interfaces. For IPsec virtual routing, this means that the SourceInterface does not have to be associated with the OuterRoutingTable.

Optional Setup Properties

The following IPsecTunnel object properties might also be assigned values for setting up virtual routing:

  • LocalEndpoint

    This is the local IP address to which the remote IPsec peers connect. Setting this value means that the tunnel will only be selected when peers connect to this IP address.

  • SourceInterface

    This is the interface which receives outer IKE and IPsec traffic. If this is not specified then cOS Stream will listen on all interfaces. Specifying this value will ensure the tunnel listens only on a specific interface.

Example 6.6. Setting Up IPsec Virtual Routing

This example shows how an existing IPsecTunnel object called my_ipsec_tunnel1 is configured for virtual routing so it is completely separated from other tunnels.

The following is assumed:

  • The interface if1 and network if1_net are on the protected side of the firewall. The remote network will connect to the local network if1_net.

  • The interface if2 and network if2_net are on the unprotected side. The IP address object if2_gw is the IP of an external router connected to if2.

  • The remote network from which traffic inside the tunnel originates is represented by the IP address object remote_net.

  • The SourceInterface will be set to if2. This is the interface on which IKE and IPsec traffic is received.
  • The LocalEndpoint IP address of will be used. This is the IP address to which the remote IPsec peer must connect.

  • It is assumed that two new routing tables have been created to route traffic correctly. One table is called outer_rt and this will be used to route the tunnel's outer IKE and IPsec traffic. The second routing table is called inner_rt and will route the traffic inside the tunnel. The contents of both tables are shown below.

Routing table outer_rt

# Interface Network Gateway
1 if2 if2net
2 if2 all-nets gw-if2

Routing table inner_rt

# Interface Network Gateway
1 if1 if1net
2 my_ipsec_tunnel1 remote_net

Command-Line Interface

System:/> set Interface IPsecTunnel1 my_ipsec_tunnel

6.4.4. Troubleshooting

The following are some simple diagnostic steps that can be used to identify problems with virtual routing.

  • Make sure that the IP rule source interface filters are correct.

  • Double check interface routing table membership. For all types of interfaces and tunnels.

  • Use "ping -routingtable=<table>" to source pings from different routing tables.

  • Use "arpsnoop -verbose <ifacenames>" to get verbose information about ARP resolution.

  • Use "routes <routingtable> -alltypes" to view all route entries in a given table, including "core" routes.

  • Use "routes -lookup=<ipaddr> <routingtable>" to make sure that a given IP address is routed the way it should be.

  • Use "flow -verbose" to view verbose information about open flows. Both ends of a flow will be shown; before and after address translation. Also, the routing tables used in the forward and return direction will be shown.

  • Enable logging and read the logs. In each virtual router, a separate IP rule decision is made, and a separate flow is established.

6.5. Policy-based Routing


Policy-based Routing (PBR) is a routing feature that provides administrators with significant flexibility in implementing routing policies by being able to use different routing tables for different traffic flows.

Normal routing forwards packets based on the destination IP address using information derived from statically configured routes or from dynamic routes added during runtime by features such as IPsec or OSPF. Instead, policy-based routing allows routes to be chosen based on other traffic characteristics in addition to the destination IP.

Policy-based routing allows the following:

  • Source-based Routing

    A different routing table can be chosen based on the source interface and/or source IP address of the traffic. For example, when more than one ISP is used to provide Internet services, policy-based routing can route traffic originating from different sets of users through different routes.

    When filtering on source IP address, traffic from one address range might be routed through one ISP while traffic from another address range might be routed through a second ISP. The same can be applied for the source interface.

  • Destination-based Routing

    A different routing table can be chosen based on the destination network of traffic.

    Destination-based routing can be combined with source-based routing so both source and destination is used to determine the routing table to use.

    [Note] Note

    As the destination interface is unknown until the route lookup has been done, policy-based routing cannot be based on the destination interface.

  • Service-based Routing

    A routing table can be chosen based on the traffic Service, meaning the transport protocol such as TCP or UDP, together with the source and/or destination port numbers. Policy-based routing can therefore route a given protocol, such as HTTP, through proxies such as Web caches. Specific services might also be routed through a specific ISP so that one ISP handles all SNMP traffic.

    Service-based routing can be combined with source-based and/or destination-based routing so that all three are considered when choosing a routing table.

Policy-based Routing Components

Policy-based routing in cOS Stream is implemented using two configuration components:

  • Alternate Routing Tables

    The administrator defines one or more alternate RoutingTable objects in addition to the default main routing table.

    These are also sometimes referred to in documentation as Named Routing Tables.

  • Routing Rules

    One or more RoutingRule objects are created to determine which routing table to use for which traffic.

    cOS Stream provides a predefined parent object called PBRRules to which RoutingRule objects are added.

Creating Alternate Routing Tables

cOS Stream has one predefined routing table called main. In addition to the main table, it is possible to define one or more, additional routing tables for policy-based routing. These will also be referred to in this document as alternate routing tables.

Alternate routing tables contain the same information for describing routes as main. Additionally, they have an extra property called Ordering. The Ordering property decides how route lookup is performed using alternate tables in conjunction with the main routing table. This is described further under the heading "The Ordering Property" below.

Example 6.7. Creating an Alternate Routing Table

In this example, a new routing table called my_pbr_table is created with the Ordering property set to First.

Command-Line Interface

To create the routing table:

System:/> add RoutingTable my_pbr_table Ordering=First

Example 6.8. Adding Routes to an Alternate Routing Table

After defining the routing table MyPBRTable, routes can be added to the table. Assume that the route to a network my_network is to be defined for the if3 interface.

Command-Line Interface

First, change the CLI context to be the routing table:

System:/> cc RoutingTable my_pbr_table

Now, add the route:

System:/RoutingTable/my_pbr_table> add Route

Finally, change back to the default CLI context:

System:/RoutingTable/my_pbr_table> cc

Creating Routing Rules

A RoutingRule object in the routing rule set can decide which routing table is selected. By default, there is a single routing rule set defined in cOS Stream which has the object name PBRRules and all routing rules are added to it as children.

A RoutingRule has a number of filtering properties that are similar to those used in an IP rule. A rule can trigger on a type of service (HTTP for example) in combination with the specified source interface and source/destination network. Routing rules cannot be filtered on destination interface as it would not be known before route lookup.

When looking up routing rules, the rule set is searched from top to bottom and it is the first matching rule found that is triggered.

Example 6.9. Creating a Routing Rule

In this example, a routing rule called my_routing_rule is created. This will select the routing table my_pbr_table for any http traffic destined for the network my_network.

Command-Line Interface

First, change the context to be the routing rule set:

System:/> cc PBRRules

Next, add the routing rule:

System:/PBRRules> add RoutingRule

This current contents of the routing rule set can be listed:

System:/PBRRules> show


  # Name Source interface Source network Destination network Service
  - ---- ---------------- -------------- ------------------- ------------
+ 1 my   any              all-nets       my_network          http

Finally, change back to the default CLI context:

System:/PBRRules> cc

Routing Rules can use IPv4 or IPv6 Addresses

Routing rules support either IPv4 or IPv6 addresses as the source and destination network for a rule's filtering properties.

However, both the source and destination network must be either IPv4 or IPv6. It is not permissible to combine IPv4 and IPv6 addresses in a single rule. For further discussion of this topic, see Section 5.4, IPv6 Support.

For this reason it is recommended to not use the all-nets address object in a routing rule. It is better to use either all-nets-ip4 or all-nets-ip6 so that it is clear what kind of IP addresses the rule applies to.

The Forward and Return Routing Table can be Different

In most cases, the routing table for forward and return traffic will be the same. However, in some cases it can be advantageous to have different values.

Consider the example of a firewall with two hypothetical interfaces wan1 and wan2 connected to two ISPs and with a protected network if1_net on the if1 interface. All IP addresses are assumed to be IPv4.

Assume, that there are two routing tables, the main routing table and an alternate routing table called isp2_rt. The contents of these tables are shown below:

The main routing table

Index # Interface Network Gateway
1 if1 if1_net  
2 wan1 all-nets-ip4 isp1_ip

The isp2_rt routing table

Index # Interface Destination Gateway
1 wan2 all-nets-ip4 isp2_ip

If traffic coming through wan2 is to have access to if1_net then a routing rule needs to be defined as follows:

Routing Table
Routing Table
wan2 all-nets-ip4 if1_net main isp2

This rule allows the forward traffic received through the wan2 interface to find the route for if1_net in the main routing table. The return traffic will use the isp2_rt table so it can reach the initiator of the flow.

With IPv4, this example would most likely have some address translation rules since if1_net will probably be a private IP network. For simplicity, these details have been omitted.

Interface Routing Table Membership

If a particular routing table is to be always used for traffic from a given source interface, regardless of the service, it is possible to associate the source interface explicitly with a particular routing table using the Routing Table Membership property of the interface.

The difference with this method of explicit association is that the administrator cannot specify the service, such as HTTP, for which the lookup will apply. Routing rules allow a more fine-grained approach to routing table selection by being able to also select a specific service and network filter.

The Routing Table Selection Process

When a packet corresponding to a new flow first arrives, these are the processing steps taken to determine which routing table to use:

  • The routing rules are looked up first. A search is made for a routing rule that matches the packet's source interface, source/destination network as well as service. If a matching rule is found then this determines the routing table to use.

  • If no matching routing rule is found, a check is made to see if the receiving interface is a member of a specific routing table. If the interface is associated with a particular routing table through its Routing Table Membership property, that routing table will be used. If there is no membership then the main table will be used.

The Ordering Property

When route lookups are to be performed in an alternate routing table, the Ordering property of the table decides how the alternate table is combined with the main routing table to lookup the route.

The three available options for the Ordering property are:

  • First

    With this option, route lookups will first of all be done in the alternate routing table. If no matching route is found there, the lookup will continue in the main routing table.

    Note that if a default route (a route with all-nets-ip4 or all-nets-ip6 as the network) is found in the alternate table, it will be counted as a match.

  • Last

    The behavior for this option is to start the route lookup in the main table. If no matching route is found, or the default route is found, a lookup for a matching route in the alternate table is performed. If no match is found in the alternate table then the default route in the main table will be used.

  • Only

    Route lookups will only be done in the alternate routing table. The existence of any other table is ignored. This is the default behavior.

    This option gives the administrator a way to dedicate a single routing table to one set of interfaces.

[Important] Important: Check that a default route exists

A common mistake when setting up policy-based routing with First or Last ordering is the absence of a default route with a destination network of all-nets-ip4 or all-nets-ip6 in the main routing table. If there is no matching route, the absence of a default route will mean that the traffic will be dropped.

The need for a default route applies regardless if the routing table is selected by using a routing rule, or by using the RoutingTableMembership property.

Setting Up Policy-based Routing with Multiple ISPs

A multiple ISP scenario is a common use of policy-based routing. Consider the situation where there are two protected networks, if1_net and if2_net, on a Clavister NetShield Firewall connected to the interfaces if1 and if2 respectively.

Now, suppose that are two different ISPs, ISP A with the gateway address isp_A_gw, and ISP B with the gateway address isp_B_gw. These ISPs are connected to the firewall interfaces wan1 and wan2 respectively.

The requirement is to have hosts and clients on if1_net use only ISP A for Internet connection. Similarly, if2_net is to use only ISP B.

The contents of the main routing table will be as follows:

Interface Network Gateway
if1 if1_net  
if2 if2_net  
wan1 all-nets-ip4 isp1_gw_ip

An alternate routing table rt2 is created with the following entry:

Interface Network Gateway
wan2 all-nets-ip4 isp2_gw_ip

The table rt2 has its Ordering property set to Last, which means that it will only be consulted if a lookup in the main routing table gives a match with the default all-nets route.

The policy-based routing rule set contains a single rule that triggers on traffic coming from the if2_net network bound for the public Internet:

Routing Table
if2 if2_net all-nets-ip4 all_services rt2 rt2

When the configuration objects listed above are created, the result is that flows originating from clients and hosts on if1_net and if2_net to the public Internet will be routed to the intended ISP.

Although routed correctly, the appropriate IPRule objects that are needed to allow these flows have been omitted from the description above.

6.6. OSPF

The feature called Dynamic Routing is implemented in cOS Stream using the Open Shortest Path First (OSPF) architecture.

This section begins by looking generally at the ways in which dynamic routing can be implemented. It then looks at how OSPF provides dynamic routing followed by a description of how OSPF is set up.

6.6.1. Dynamic Routing

Before looking at OSPF in detail, this section will discuss the general concept of Dynamic routing and the type of dynamic routing provided by OSPF. It introduces important concepts in dynamic routing and in OSPF.

Differences with Static Routing

Dynamic routing is different to static routing in the following respects:

  • Network devices that perform routing share exchange routing information.

  • These network devices are able to automatically adapt routing to changes in network topology.

Dynamic routing involves network devices performing the following processing steps:

  1. Learn about all the connected routing devices.

  2. Receive information from these devices about which networks they are connected to.

  3. Process the received information so that the best routes for remotely connected destinations are available in the device's local routing tables.

Dynamic routing responds to routing changes dynamically but has the disadvantage that it can be more susceptible to certain problems such as routing loops where traffic is routed back to the originating router.

Selecting the "Best" Route

One of two types of algorithms are generally used to implement dynamic routing and to select the "best" route:

  • A Distance Vector (DV) algorithm.

  • A Link State (LS) algorithm.

How a router decides the optimal or "best" route and then shares updated information with other routers depends on the type of algorithm used. The two most common algorithm types are discussed next.

Distance Vector Algorithms

A Distance Vector (DV) algorithm is a decentralized routing algorithm that computes the best path in a distributed way.

Each router in a network computes the "costs" of its own attached links, and shares routing information only with its neighboring routers. Each router determines the least-cost path to a destination by iterative computation and also using information exchanged with its neighbors.

Routing Information Protocol (RIP) is a well-known DV algorithm for router information exchange and operates by sending regular update messages and reflecting routing changes in routing tables. Path determination is based on the "length" of the path which is the number of intermediate routers (also known as "hops") to the destination.

After updating its own routing table, the router immediately begins transmitting its entire routing table to neighboring routers to inform them of changes.

Link State Algorithms

In contrast to DV algorithms, Link State (LS) algorithms enable routers to keep routing tables that reflect the topology of the entire network.

Each router broadcasts its attached links and link costs to all other routers in the network. When a router receives these broadcasts it runs the LS algorithm locally and calculates its own set of least-cost paths. Any change of the link state will be sent everywhere in the network, so that all routers keep the same routing table information and have a consistent view of the network.

Advantages of Link State Algorithms

Since global link state information is maintained throughout a network, LS algorithms, like the one used in OSPF, offer a high degree of configuration control and scalability. Changes result in broadcasts of only the updated information to other routers which means faster convergence and less possibility of routing loops. OSPF can also function within a hierarchy, whereas RIP has no knowledge of sub-network addressing.

The OSPF Solution

Open Shortest Path First (OSPF) is a widely used dynamic routing architecture which is based on LS algorithms. The Clavister NetShield Firewall can implement dynamic routing using OSPF.

An OSPF enabled router first identifies the routers and sub-networks that are directly connected to it and then broadcasts the information to all the other routers. Each router uses the information it receives to add the OSPF learned routes to its routing table.

With this larger picture, each OSPF router can identify the best route to a given destination IP. OSPF routers will then only broadcast updates to inform others of any route changes instead of broadcasting the entire routing table.

OSPF depends on various metrics for path determination, including hops, bandwidth, load and delay. OSPF can also provide a high level of control over the routing process since its parameters can be finely tuned.

A Simple OSPF Example

The network topology illustrated below provides a simple example of what can be achieved using OSPF. Here, there are two Clavister NetShield Firewalls, A and B, connected together directly and configured to be in the same OSPF area (the concept of OSPF area will be explained later).

A Simple OSPF Example

Figure 6.4. A Simple OSPF Example

OSPF allows firewall A to know that in order to reach network Y, traffic needs to be sent to firewall B. Instead of manually inserting this routing information into the routing tables of A, OSPF allows B's routing table information to be shared with A.

In the same way, OSPF allows firewall B to automatically become aware that network X can be reached via firewall A.

Under OSPF, this exchange of routing information is completely automatic.

OSPF Provides Route Redundancy

Now take the above scenario and add a third Clavister NetShield Firewall called C. This is illustrated below.

OSPF Providing Route Redundancy

Figure 6.5. OSPF Providing Route Redundancy

OSPF allows each of the three firewalls to share routing information with each other. Each of the three firewalls can be aware of what networks are reachable through the other two firewalls.

In addition, there is now route redundancy between any two of the firewalls. For example, if the direct link between A and C fails then OSPF allows both firewalls to know immediately that there is an alternate route between them via firewall B.

For instance, traffic from network X which is destined for network Z will be routed automatically through firewall B. When there is no failure and both alternate routes are available, OSPF determines which is the "best" route.

From the administrator's point of view, only the routes for directly connected networks need to be configured on each firewall. OSPF automatically provides the required routing information to find networks reachable via other firewalls, even if traffic needs to transit several firewalls to reach its destination.

[Tip] Tip: Ring topologies always provide alternate routes

When designing the topology of a network that implements OSPF, arranging the Clavister NetShield Firewalls in a circular ring means that any firewall always has two possible routes to any other. Should any one inter-firewall connection fail, an alternative path always exists.

A Look at Routing Metrics

In discussing dynamic routing and OSPF further, an understanding of Routing Metrics can be useful and a brief explanation is given here.

Routing metrics are the criteria that a routing algorithm will use to compute the "best" route to a destination. A routing protocol relies on one or several metrics to evaluate links across a network and to determine the optimal path. The principal metrics used with OSPF include:

Path length
The sum of the costs associated with each link. A commonly used value for this metric is called "hop count" which is the number of routing devices a packet must pass through when it travels from source to destination.
Item Bandwidth
The traffic capacity of a path in Mbps.
The usage of a router. The usage can be evaluated by CPU utilization and throughput.
The time it takes to move a packet from the source to the destination. The time depends on various factors, including bandwidth, load, and the length of the path.

6.6.2. OSPF Concepts


Open Shortest Path First (OSPF) is a routing protocol developed for IP networks by the Internet Engineering Task Force (IETF). The Clavister NetShield Firewall OSPF implementation is based upon RFC 2328, with compatibility to RFC 1583.

OSPF functions by routing IP packets based only on the destination IP address found in the IP packet header. IP packets are routed "as is", in other words they are not encapsulated in any further protocol headers as they transit the OSPF Autonomous System (AS).

The Autonomous System

The term Autonomous System (AS) refers to a single network or group of networks with a single, clearly defined routing policy controlled by a common administrator. It forms the top level of a tree structure which describes the various OSPF components.

OSPF Routers

An AS corresponds to a number of separate network devices which are running as OSPF Routers. A Clavister NetShield Firewall becomes an OSPF router by having an OSPFProcess object defined.

In most scenarios, only a single AS is required and therefore only a single OSPFProcess object needs to be defined on each Clavister NetShield Firewall involved in the OSPF AS. This object is described further in Section, The OSPFProcess Object.

Link-state Routing

OSPF makes use of link-state routing (LS). This means Link-state Advertisements (LSAs) are sent to the other routers within the same area. Each router maintains a database, known as a Link-state Database, which maps the topology of the autonomous system (AS). Using this database, each router constructs a tree of shortest paths to other routers, with itself as the root. This shortest-path tree is used to determine the best route to each destination in the AS.

OSPF Authentication.

All OSPF protocol exchanges can, if required, be authenticated. This means that only OSPF routers with the correct authentication can join an AS. Different authentication schemes can be used. Authentication can be performed using either a passphrase or an MD5 digest.

Authentication should be viewed as a way to make sure that the correct OSPF routers join an AS. It is therefore most useful when more than one AS is defined. This feature is described further in Section, The OSPFProcess Object.

OSPF Areas

An OSPF Area is a way of creating subgroups of networks and hosts within an OSPF AS. OSPF routers that are only connected to a single area are called internal routers. All interfaces on internal routers are directly connected to networks within the area.

The topology of an area is hidden from the rest of the AS. This information hiding reduces the amount of routing traffic exchanged. Also, routing within the area is determined only by the area's own topology, giving an area protection from bad routing data. An area is a generalization of an IP subnetted network.

Areas are defined by OSPFArea objects and are added to OSPFProcess objects. There can be more than one area within an AS so multiple OSPFArea objects could be added to a single OSPFProcess. In simple OSPF scenarios, a single OSPF area is sufficient and it should be defined on each Clavister NetShield Firewall which will be part of the OSPF AS.

This area object is described further in Section, The OSPFArea Object.

Components Related to OSPF Areas

A summary of OSPF components related to an area is given below:


Area Border Routers are routers that have interfaces connected to more than one area. These maintain a separate topological database for each area to which they have an interface.


Routers that exchange routing information with routers in other Autonomous Systems are called Autonomous System Boundary Routers. They advertise externally learned routes throughout the Autonomous System.

Backbone Areas

All OSPF AS' need to have at least the Backbone Area which is the OSPF area with an ID of 0. This is the area that other related areas should be connected to. The backbone ensures routing information is distributed between connected areas. When an area is not directly connected to the backbone it needs a virtual link to it.

An OSPF AS should be designed by beginning with the backbone.

Stub Areas

Stub areas are areas through which or into which AS external advertisements are not flooded. When an area is configured as a stub area, the router will automatically advertise a default route so that routers in the stub area can reach destinations outside the area.

Transit Areas

Transit areas are used to pass traffic from an area that is not directly connected to the backbone area.

The Designated Router

Each OSPF broadcast network has a single Designated Router (DR) and a single Backup Designated Router (BDR). The routers use OSPF Hello messages to determine the DR and BDR based on the priorities advertised by all the routers. If there is already a DR on the network, the router will accept that one, regardless of its own router priority.

With the Clavister NetShield Firewall, the DR and the BDR are assigned automatically.

OSPF Neighbors

Routers that are in the same area become neighbors in that area. Neighbors are elected by the use of OSPF Hello messages. These are sent out periodically on each interface using IP multicast. Routers become neighbors as soon as they see themselves listed in a neighbor's Hello message. In this way, two way communication is guaranteed.

The following Neighbor States are defined:


This is the initial state of the neighbor relationship.


When a Hello message is received from a neighbor, but does not include the Router ID of the firewall in it, the neighbor will be placed in the Init state.

As soon as the neighbor in question receives a Hello message it will know the sending router's Router ID and will send a Hello message with that included. The state of the neighbors will change to the 2-way state.


In this state the communication between the router and neighbor is bi-directional.

On Point-to-Point and Point-to-Multipoint OSPF interfaces, the state will be changed to Full. On Broadcast interfaces, only the DR/BDR will advance to the Full state with their neighbors, all the remaining neighbors will remain in the 2-Way state.


Preparing to build adjacency.


Routers are exchanging Data Descriptors.


Routers are exchanging LSAs.


This is the normal state of an adjacency between a router and the DR/BDR.

OSPF Aggregates

OSPF Aggregation is used to combine groups of routes with common addresses into a single entry in the routing table. This is commonly used to minimize the routing table.

To set this feature up in cOS Stream, see Section, OSPF Aggregates.

Virtual Links

Virtual links are used for the following scenarios:

A. Linking an area that does not have a direct connection to the backbone area.

B. Linking backbone areas when the backbone is partitioned.

These two uses are discussed next.

A. Linking areas without direct connection to the backbone

The backbone area always needs to be the center of all other areas. In some rare cases where it is impossible to have an area physically connected to the backbone, a Virtual Link is used. Virtual links can provide an area with a logical path to the backbone area.

This virtual link is established between two Area Border Routers (ABRs) that are on one common area, with one of the ABRs connected to the backbone area. In the example below two routers are connected to the same area (Area 1) but just one of them, fw1, is connected physically to the backbone area.

Virtual Links Connecting Areas

Figure 6.6. Virtual Links Connecting Areas

In the above example, a Virtual Link is configured between fw1 and fw2 on Area 1 as it is used as the transit area. In this configuration only the Router ID has to be configured. The diagram shows that fw2 needs to have a Virtual Link to fw1 with Router ID and vice versa. These virtual links need to be configured in Area 1.

B. Linking a Partitioned Backbone

OSPF allows for linking a partitioned backbone using a virtual link. The virtual link should be configured between two separate ABRs that touch the backbone from each side and have a common area in between.

Virtual Links with Partitioned Backbone

Figure 6.7. Virtual Links with Partitioned Backbone

The virtual link is configured between fw1 and fw2 on Area 1 as it is used as the transit area. In the configuration, only the Router ID has to be configured, as in the example above show fw2 need to have a virtual link to fw1 with the Router ID and vice versa. These virtual links need to be configured in Area 1.

To set this feature up in cOS Stream, see Section, The OSPFVLink Object.

Using OSPF

When using OSPF, there will be two or more firewalls connected together in some topology. OSPF will allow any of these firewalls to be able to correctly route traffic to a destination network connected to another firewall without needing a static route to be added manually to its routing tables.

OSPF allows connected Clavister NetShield Firewalls to share the information in their routing tables so that traffic entering an interface on one of the firewalls can be automatically routed so that it exits another firewall's interface on which the destination network is reachable.

Another important aspect is that the firewalls monitor the connections between each other and route traffic by an alternate connection if one is available. For scenarios involving more than two firewalls, a network topology can therefore be designed to provide tolerance for single link failures. If a connection between any two firewalls fails then an alternate traffic route is available between them.

OSPF High Availability Support

OSPF is supported by the High Availability (HA) feature. However, there are some issues that should be noted:

  1. Both the active and the inactive unit of an HA cluster will run separate OSPF processes, but the inactive unit will make sure that it is not the preferred choice for routing.

  2. The HA master and slave will not form OSPF adjacency with each other and are not allowed to become a DR or BDR on broadcast networks. This is done by forcing the router priority to 0.

  3. For OSPF HA support to work correctly, the Clavister NetShield Firewall needs to have a broadcast interface with at least one neighbor for all areas that the firewall is attached to. This is because the inactive unit in the cluster needs a neighbor to get the link state database from.

  4. It is not possible to put an HA cluster on the same broadcast network without any other neighbors (they will not form OSPF adjacency with each other because of the router priority is 0). However, it may be possible, depending on the scenario, to set up a point to point link between them instead.

  5. Special care must also be taken when setting up a virtual link to firewalls in an HA cluster. When the endpoint sets up a link to any HA firewall, it must set up 3 separate links: one to the shared, one to the master and one to the slave router id of the firewall.

6.6.3. OSPF Configuration Objects

This section looks at the objects that need to be configured to describe the OSPF AS structure and also lists the most important properties for these objects. The objects are defined on each Clavister NetShield Firewall that is part of the OSPF AS and will usually describe a single AS.

An illustration of the relationship between different OSPF objects is shown below.

OSPF Objects

Figure 6.8. OSPF Objects

[Note] Note

Dynamic routing rules are not included in the above diagram. They describe the rules for importing and exporting routes and do not describe the OSPF structure. They are covered in Section 6.6.4, Dynamic Routing Rules. The OSPFProcess Object

This object defines the autonomous system (AS) which is the top level of the OSPF AS structure. A similar OSPFProcess object should be defined on each Clavister NetShield Firewall which is part of the OSPF AS.

General Parameters


Specifies a symbolic name for the OSPF AS.


Specifies the IP address that is used to identify the router in a AS. If no Router ID is configured, the firewall computes the Router ID based on the highest IP address of any interface participating in the OSPF AS.

PrivRouter ID

This is used in an HA cluster and is the ID for this firewall and not the cluster.

[Note] Note
When running OSPF on a HA Cluster there is a need for a private master and private slave Router ID as well as the shared Router ID.

Set the reference bandwidth that is used when calculating the default interface cost for routes.

If bandwidth is used instead of specifying a metric on an OSPF Interface, the cost is calculated using the following formula:

cost = reference bandwidth / bandwidth


Enable this if the Clavister NetShield Firewall will be used in a environment that consists of routers that only support RFC 1583.


OSPF supports the following authentication options:

No (null) authentication

No authentication is used for OSPF protocol exchanges.


A simple password is used to authenticate all the OSPF protocol exchanges.


MD5 authentication consists of a key ID and 128-bit key. When MD5 digest is used the specified key is used to produce the 128-bit MD5 digest.

This does NOT mean that the OSPF packets are encrypted. If the OSPF traffic needs to be encrypted then they must be sent using a VPN. For example, using IPsec. Sending OSPF packets through an IPsec tunnel is discussed further in Section 6.6.5, Setting Up OSPF.

[Important] Note: Authentication must be the same on all routers

If a passphrase or MD5 authentication is configured for OSPF, the passphrase or authentication key must be the same for all the OSPFProcess objects in an Autonomous System (AS).

In other words, the same OSPF authentication must be replicated on all Clavister NetShield Firewalls.


Time Settings


Specifies the minimum time, in seconds, between two SPF calculations. The default time is 10 seconds. A value of 0 means that there is no delay. Note, however, that SPF can potentially be a CPU demanding process, so with large network topologies it is not recommended to run it often.


Specifies the delay time, in seconds, between when OSPF receives a topology change and when it starts an SPF calculation. The default time is 5 seconds. A value of 0 means that there is no delay. Note again that SPF can potentially be a CPU demanding process, so with large network topologies it is not recommended to run it often.


This specifies the time in seconds at which interval the OSPF LSAs are collected into a group and refreshed. It is more optimal to group many LSAs and process them at the same time, instead of running them one and one.


This specifies the time in seconds that the routing table will be kept unchanged after a reconfiguration of OSPF entries or a HA failover.

Memory Settings


Maximum amount in Kilobytes of RAM that the OSPF AS process are allowed to use, if no value is specified the default is 1% of installed RAM. Specifying 0 indicates that the OSPF AS process is allowed to use all available ram in the firewall. The OSPFArea Object

An Autonomous System (AS) is divided into smaller parts called an OSPF Area. An area collects together OSPF interfaces, neighbors, aggregates and virtual links. The OSPFArea object is used to define an area.

An OSPFArea object is a child of an OSPFProcess object and there can be many multiple areas defined under one process. In most simple networking scenarios, a single area is sufficient. Like the OSPFProcess object, a similar OSPFArea object should be defined on all the Clavister NetShield Firewalls which will be part of the same area.

General Parameters


Specifies the name of the OSPF Area.


Specifies the area id. If is specified then this is the backbone area.

There can only be one backbone area and it forms the central portion of an AS. Routing information that is exchanged between different areas always transits the backbone area.


Enable this option if the area is a stub area.


It is possible to configure if the firewall should become the default router for the stub area, and with what metric.

Import Filter

The import filter is used to filter what can be imported in the OSPF AS from either external sources (like the main routing table or a policy based routing table) or inside the OSPF area.


Specifies the network addresses allowed to be imported into this OSPF area from external routing sources.


Specifies the network addresses allowed to be imported from other routers inside the OSPF area. The OSPFInterface Object

This section describes how to configure an OSPFInterface object. OSPF interface objects are children of OSPF areas. Unlike areas, they are not similar on each Clavister NetShield Firewall in the OSPF AS. The purpose of an OSPF interface object is to describe a specific interface which will be part of an OSPF AS.

[Note] Note: Different interface types can be used with OSPF interfaces

Note that an OSPF Interface does not always correspond to a physical interface although this is the most common usage. Other types of interfaces, such as a VLAN, could instead be associated with an OSPF Interface.

General Parameters


Specifies which interface on the firewall will be used for this OSPF interface.


Specifies the IP network that is reachable through this interface. The route to this network is exported automatically to the OSPF AS. Exporting any other routes requires a RouteExportRule object which is described in Section 6.6.4, Dynamic Routing Rules.

The network must be specified for an OSPFInterface and only a single network can be used.


This can be one of the following:

  • Auto - Tries to automatically detect interface type. This can be used for physical interfaces.

  • Broadcast - The Broadcast interface type is an interface that has native Layer 2 broadcast/multicast capabilities. The typical example of a broadcast/multicast network is an ordinary physical Ethernet interface.

    When broadcast is used, OSPF will send OSPF Hello packets to the IP multicast address Those packets will be heard by all other the OSPF routers on the network. For this reason, no configuration of OSPF Neighbor objects is required for the discovery of neighboring routers.

  • Point-to-point - Point-to-Point is used for direct links which involve only two routers (in other words, two firewalls).

  • Point-to-multipoint - The Point-to-Multipoint interface type is a collection of Point-to-Point networks, where there is more than one router in a link that does not have OSI Layer 2 broadcast/multicast capabilities.


Specifies the metric for this OSPF interface. This represents the "cost" of sending packets over this interface. This cost is inversely proportional to the bandwidth of the interface.


If the metric is not specified, the bandwidth is specified instead. If the bandwidth is known then this can be specified directly instead of the metric.


All OSPF protocol exchanges can optionally be authenticated using a simple password (passphrase) or MD5 cryptographic hashes.

If Use Default for Router Process is enabled then the values configured in the router process properties are used. If this is not enabled then the following options are available:

  • No authentication specified - the default.
  • AuthPassphrase - A passphrase.
  • AuthMD5Key - MD5 Digest.



Specifies the number of seconds between Hello packets sent on the interface.


If not Hello packets are received from a neighbor within this interval then that neighbor router will be considered to be out of operation.


Specifies the number of seconds between retransmissions of LSAs to neighbors on this interface.


Specifies the estimated transmit delay for the interface. This value represents the maximum time it takes to forward a LSA packet trough the router.


Specifies the number of seconds between the interface brought up and the election of the DR and BDR. This value should be higher than the hello interval.


Specifies the router priority, a higher number increases this routers chance of becoming a DR or a BDR. If 0 is specified then this router will not be eligible in the DR/BDR election.

[Note] Note

An HA cluster will always have 0 as router priority, and can never be used as a DR or BDR.

The following should be noted for OSPFInterface objects:

The Network property of an OSPFInterface object is automatically exported to the OSPF AS. No dynamic routing rules are required to achieve this.

If the IgnoreMTU property is enabled for an OSPFInterface object, OSPF MTU mismatches will be allowed.

  • It is often required to include the network on the OSPFInterface in the OSPF AS but there is no need to run OSPF on the interface. This is done by enabling the Passive property of the OSPFInterface object to indicate that there are no OSPF routers connected to the interface. The OSPFNeighbor Object

In some scenarios the neighboring OSPF router to a firewall needs to be explicitly defined. For example, when the connection is not between physical interfaces.

The most common situation for using this object is when a VPN tunnel is used to connect two neighbors and there is a need to tell cOS Stream that the OSPF connection needs to be made through the tunnel. This type of VPN usage with IPsec tunnels is described further in Section 6.6.5, Setting Up OSPF.

OSPFNeighbor objects are created within an OSPFArea and each object has the following property parameters:


Specifies which OSPF interface the neighbor is located on.


The IP Address of the neighbor. This is the IP Address of the neighbors OSPF interface connecting to this router. For VPN tunnels this will be the IP address of the tunnel's remote end.


Specifies the metric value for the neighbor. OSPF Aggregates

OSPF Aggregation is used to combine groups of routes with common addresses into a single entry in the routing table. The following are the advantages of aggregation:

  • If advertised, aggregation will decrease the size of the routing table in the firewall (a primary function of the feature).

  • If not advertised the aggregated networks will be hidden.

  • OSPF related traffic is reduced.


To aggregate routes, OSPF Aggregate objects are created for an OSPF Area. Each of these objects has the following parameters:


The network consisting of the smaller routers.


If the aggregation should be advertised or not.

A Usage Example

In most, simple OSPF scenarios, OSPF Aggregate objects will not be needed. OSPF aggregation is only used when the firewall is acting as an Area Border Router (ABR) which is linking two or more OSPF areas. The diagram below illustrates a typical example of how aggregation would be used.

OSPF Route Aggregation Example

Figure 6.9. OSPF Route Aggregation Example

Here, the three routes on Area 0 can be collapsed into one by setting up an OSPF Aggregate object for the network on Area 1. The OSPFVLink Object

All areas in an OSPF AS must be physically connected to the backbone area (the area with ID 0). In some cases this is not possible and in that case a Virtual Link (VLink) can be used to connect to the backbone through a non-backbone area.

A virtual link is implemented by defining an OSPFVLink object as a child of an OSPF Area. Each OSPFVLink object has the following parameters:

General Parameters


Symbolic name of the virtual link.


The Router ID of the OSPFProcess object on the other side of the virtual link.



If enabled, use the authentication configured for the OSPFProcess object.

[Note] Note: Linking partitioned backbones

If the backbone area is partitioned, a virtual link is used to connect the different parts.

In simple OSPF scenarios, OSPFVLink objects will not be needed.

6.6.4. Dynamic Routing Rules

This section looks at Dynamic Routing Rules which decide which routes are exported to an OSPF AS from the local routing tables and which can be imported into the local routing tables from an AS. Overview

The Final OSPF Setup Step is Creating Dynamic Routing Rules

After the OSPF AS structure is created, the final step is to create Dynamic Routing Rules which allow the exchange of routing information between the local routing tables and the OSPF AS.

Dynamic routing rules are discussed here in the context of OSPF, but can also be used in other situations.

The Reasons for Dynamic Routing Rules

In a dynamic routing environment, it is important for routers to be able to regulate to what extent they will participate in the routing exchange. It is not feasible to accept or trust all received routing information, and it may be crucial to avoid parts of the routing tables being published to other routers.

For this reason, Dynamic Routing Rules are used to regulate the flow of routing information. These rules filter either statically configured or OSPF learned routes according to parameters such as the origin of the routes, destination and metric.

Usage with OSPF

Dynamic Routing Rules are used with OSPF to achieve the following:
  • Allowing the import of routes from the OSPF AS into local routing tables.

  • Allowing the export of routes from local routing tables to the OSPF AS.

  • Allowing the export of routes from one OSPF AS to another OSPF AS.

[Note] Note

The last usage of joining asynchronous systems together is rarely encountered except in very large networks.

The Two Types of Dynamic Routing Rules

There are two kinds of dynamic routing rule objects that can be defined. One for route import and one for route export:

  • RouteExportRuleOSPF for Route Import from an OSPF AS

    This object is added as a child to a OSPFProcess object. It determines which routes are to be imported from the OSPF.

    A ExportToRoutingTable object is added as a child to the RouteExportRuleOSPF object to determine which routing table the imported routes are added to.

  • RouteExportRule for Route Export to an OSPF AS

    This object is added as a child to a RoutingTable object. It determines the routes that are to exported to the OSPF from that routing table.

    The route to the Network property for all OSPFInterface objects is exported automatically to the OSPF AS. However, any other routes must be explicitly exported. This includes any routes that have a gateway defined, such as an all-nets-ip4 route to an ISP.

    A ExportToOSPF object is added as a child to the RouteExportRule object to determine which OSPF AS the routes will be exported to.

Specifying an IP Address Filter

Dynamic routing rules allow an IP address filter to be specified which narrows the routes that are imported or exported based on the network reached by those routes. One of two properties can be used for filtering the IP address or network specified in a route:

  • DestinationNetworkIn

    This will include all routes with IP addresses or networks matching or within the specified value.

  • DestinationNetworkExact

    This will include only those routes which have an IP address or network which are an exact match with the specified value. The IP addresses or networks that are within the value specified will not be included.

In simple cases, the DestinationNetworkIn property should be specified as all-nets-ip4 so that no filter is applied (all IPv4 addresses and networks are included).

If, for example, DestinationNetworkExact is specified as being all-nets-ip4 then only a route to exactly all-nets-ip4 would be included. All other routes are excluded.

Exporting Routes from One AS to Another

It is not true to say that a RouteExportRuleOSPF object is only involved in importing routes and can only have ExportToRoutingTable objects as children.

The exception is when exporting routes from one OSPF AS to another. This is done by adding a DynamicRouteRuleExportOSPF object as a child of a RouteExportRuleOSPF object and specifying the destination AS using the ExportToProcess property.

6.6.5. Setting Up OSPF

Setting up OSPF can seem complicated because of the large number of configuration possibilities that OSPF offers. However, in many cases a simple OSPF solution using a minimum of configuration objects is needed and setup can be straightforward.

Let us examine again the simple scenario described earlier with just two Clavister NetShield Firewalls.

Setting Up OSPF

Figure 6.10. Setting Up OSPF

In this example we connect together the two Clavister NetShield Firewalls with OSPF so they can share the routes in their routing tables. Both will be inside a single OSPF area which will be part of a single OSPF autonomous system (AS). If unfamiliar with these OSPF concepts, please refer to earlier sections for further explanation.

Beginning with just one of these firewalls, the setup steps are as follows:

1. Create an OSPFProcess object

Create an OSPFProcess object. This will represent an OSPF Autonomous Area (AS) which is the highest level in the OSPF hierarchy. Give the object an appropriate name. The Router ID can be left blank since this will be assigned automatically by cOS Stream.

2. Add an OSPFArea to the OSPFProcess

Within the OSPFProcess created in the previous step, add a new OSPFArea object. Assign an appropriate name and use the value for the Area ID.

An AS can have multiple areas but in many cases only one is needed. The ID identifies this area as the backbone area which forms the central portion of the AS.

3. Add OSPFInterface objects to the OSPFArea

Within the OSPFArea created in the previous step, add a new OSPF Interface object for each physical interface that will be part of the area.

The OSPFInterface object needs the following parameters specified in its properties:

  • Interface - the physical interface which will be part of the OSPF area.

  • Network - the network on the interface that will be part of the area.

    This does not need to be specified and if it is not, the network assigned to the physical interface is used. For example if lan is the interface then lannet will be the default network.

  • Interface Type - this would normally be Auto so that the correct type is automatically selected.

  • The Passive option should be enabled on the OSPFInterface object if the physical interface does not connect directly to another OSPFProcess (in other words, with another Clavister NetShield Firewall that acts as an OSPF router). For example, the interface may only be connected to a network of clients, in which case the option would be enabled.

    The option must be disabled (the default) if the physical interface is connected to another firewall which is set up as an OSPFProcess. In this example, the physical interface connected to the other firewall would have this option disabled.

4. Import Routes from the OSPF AS

Importing routes from the OSPF AS requires the following steps:

  1. A RouteExportRuleOSPF object is added as a child of the OSPFProcess.

    The DestinationNetworkIn filter property for this object should be set to all-nets-ip4 to import all routes. A narrower filter could be used.

  2. To the RouteExportRuleOSPF just added, add an ExportToRoutingTable object as a child. The Destination property of this object determines the routing table that routes are imported into.

    In the typical case this will be the routing table called main. However, the destination could also be another OSPF process or it could also be a BGP process.

5. Export Routes to the OSPF AS

Exporting routes to the OSPF AS requires the following steps:

  1. A RouteExportRule object is added as a child to the RoutingTable object from which routes will be exported.

    The DestinationNetworkIn filter property for the object should be set to all-nets-ip4 to export all routes. A narrower filter could be used.

  2. To the RouteExportRule just added, add a ExportToOSPF object as a child. The ExportToProcess property of this object determines the AS that routes are exported to.

    In the typical case this will be the routing table called main.

6. Repeat these steps on the other firewall

Now repeat steps 1 to 5 for the other Clavister NetShield Firewall that will be part of the same OSPF AS and OSPF area. The OSPFProcess and OSPFArea objects will be identical on each. The OSPFInterface objects will be different depending on which interfaces and networks are included.

If more than two firewalls will be part of the same OSPF area then all of them should be configured similarly.

OSPF Routing Information Exchange Begins Automatically

As the new configurations are created in the above steps and then deployed, OSPF will automatically start and begin exchanging routing information. Since OSPF is a dynamic and distributed system, it does not matter in which order the configurations of the individual firewalls are deployed.

When the physical link is plugged in between two interfaces on two different firewalls and those interfaces are configured with OSPFProcess objects, cOS Stream will begin exchanging routing information.

Sending OSPF Traffic Through a VPN Tunnel

In some cases, the link between two Clavister NetShield Firewalls which are configured with OSPFProcess objects may be insecure. For example, over the public Internet.

In this case, we can secure the link by setting up a VPN tunnel between the two firewalls and telling OSPF to use this tunnel for exchange of OSPF information. Next, we will look at how to set this up and assume that IPsec will be the chosen method for implementing the tunnel.

OSPF Over IPsec

Figure 6.11. OSPF Over IPsec

To create this setup we need to perform the normal OSPF steps described above but with the following additional steps applied to both firewalls A and B:

1. Set up an IPsec tunnel

First set up an IPsec tunnel in the normal way between the two firewalls A and B. This IPsec tunnel is now treated like any other interface when configuring OSPF.

2. Choose a random internal IP network

For both firewalls, we need to choose a common random IP network using internal, private IPv4 addresses. Assume that the network is used. Manually create a route in the main routing table that routes this network on the IPsec tunnel created in the previous step.

[Note] Note: The random network is not a real network

The random network is a convenience and is not associated with a physical network.

3. Define an OSPFInterface for the tunnel

Define an OSPFInterface object which has the IPsec tunnel for the Interface property. Specify the Type parameter to be Point-to-multipoint and the Network parameter to be the network chosen in the previous step,

This OSPFInterface object tells cOS Stream that any OPSF related connections to addresses within the network should be routed into the IPsec tunnel.

4. Define an OSPF Neighbor

Next, we must explicitly tell OSPF how to find the neighboring OSPF router. Do this by defining an OSPFNeighbor object. This consists of a pairing of the IPsec tunnel (which is treated like an interface) and the IP address of the OSPF router at the other end of the tunnel.

For the IPv4 address of the router, simply use any single IP address from the network This address must be different for A and B. Assume that is chosen for A and is chosen for B.

When cOS Stream sets up OSPF on A, it will look at this OSPFNeighbor object and try to send OSPF messages to the IPv4 address The OSPFInterface object defined in the previous step tells cOS Stream that OSPF related traffic to this IP address should be routed into the IPsec tunnel.

5. Change the properties of the IPsecTunnel

To finish the setup there needs to be changes made to the IPsec tunnel properties. These are:

  1. The IPsec tunnel IPAddress property should be set to the single IP address chosen for the OSPFNeighbor at the other end of the tunnel. In this example, it is set to for the IPsecTunnel object on A and for the IPsecTunnel object on B.

    The IPAddress property determines the source IP address of tunnel traffic.

  2. The properties LocalNetwork and RemoteNetwork should both be set to all-nets-ip4. These could be narrower if the networks are known but it is better to use all-nets-ip4.

  3. The property AddRouteToRemoteNetwork should be set to No so the route to the RemoteNetwork is not added automatically.

[Tip] Tip: Non-OSPF traffic can also use the tunnel

A VPN tunnel can carry both OSPF traffic as well as other types of traffic. There is no requirement to dedicate an IPsec tunnel to OSPF traffic.

6.6.6. An OSPF Example

This section goes through the detailed setup steps for the simple OSPF scenario illustrated below.

Here, two identical Clavister NetShield Firewalls called A and B are joined together directly via their if3 interfaces. Each has a network of hosts attached to its if1 interface. On one side, if1_net is the IPv4 network and on the other side it is the IPv4 network

The goal is to configure OSPF on both firewalls so routing information is automatically exchanged and traffic can be correctly routed between the network and the network. The IP rules that are needed to allow such traffic to flow are not included in this example.

An OSPF Example

Figure 6.12. An OSPF Example

Example 6.10. Creating an OSPFProcess


First, the Autonomous System (AS) must be defined on both firewalls.

On firewall A, create an OSPFProcess object. Assume that the object name will be as_0.

Command-Line Interface

System:/> add OSPFProcess as_0

Now, repeat this for firewall B, using the same OSPFProcess object name of as_0.

Example 6.11. Adding an OSPFArea Object

Now, add an OSPF Area object to the OSPFProcess object as_0 on firewall A.

This area will be the OSPF backbone area and will therefore have the ID Assume that the name for the area object is area_0 and the same AreaID of

Command-Line Interface

First, change the CLI context to be the OSPFProcess object created above:

System:/> cc OSPFProcess as_0

Now, add the area:

System:/OSPFProcess/as_0> add OSPFArea area_0 AreaID=

This new OSPFArea object can be displayed with the command:

System:/OSPFProcess/as_0> show


   Name    Area ID  Comments
   ----    -------  --------
!  area_0  <empty>

Now, repeat this for firewall B, using the same OSPF Area object name of area_0 and the same backbone AreaID.

Example 6.12. Adding OSPFInterface Objects

For firewall A, add OSPFInterface objects for each physical interface that is to be part of the OSPF area named area_0.

Command-Line Interface

Assume that the context is still the OSPFProcess called as_0 from the last example. Now, change the context to be the OSPFArea that was created previously:

System:/as_0> cc OSPArea area_0

Next, add the OSPFInterface objects:

System:/OSPFProcess/as_0/OSPFArea/area_0> add OSPFInterface if1

System:/OSPFProcess/as_0/OSPFArea/area_0> add OSPFInterface if3

Return to the default CLI context:

System:/OSPFProcess/as_0/OSPFArea/area_0> cc

The same procedure should be repeated for firewall B.

Example 6.13. Importing Routes into the main Routing Table

In this example, the routes received using OSPF will be added into the main routing table. To do this, a DynamicRoutingRule OSPF needs to be added as a child of the OSPFProcess object which describes the AS. In this example, the added object is called ImportOSPFRoutes.

Depending on the routing topology, it may be preferable to just import certain routes using the Destination Interface/Destination Network filters, but in this example all available routes are imported by setting the DestinationNetworkIn property to the value all-nets-ip4.

The steps are first performed for firewall A.

Command-Line Interface

First, change the context from the default to the OSPFProcess object:

System:/> cc OSPFProcess as_0

Next, add a RouteExportRuleOSPF object:

System:/OSPFProcess/as_0> add RouteExportRuleOSPF
Added RouteExportRuleOSPF/1(Import).

Notice that the rule is automatically allocated an index number of 1 and this is how it will be referenced later. The textual name is for description only.

Now, add a ExportToRoutingTable object as a child to the RouteExportRuleOSPF object created above. This specifies the destination routing table where the routes will be added, in this case the main table.

Change the CLI context to be the RouteExportRuleOSPF just added for import:

System:/OSPFProcess/as_0> cc RouteExportRuleOSPF 1

Next, add a ExportToRoutingTable object:

				add ExportToRoutingTable 
Added ExportToRoutingTable/1.

Return to the default CLI context:

System:/OSPFProcess/as/RouteExportRuleOSPF/1(Import)> cc

The same procedure should be repeated for firewall B.

Example 6.14. Exporting Routes into the OSPF AS

In this example, all the static routes from the main routing table will be exported into the OSPF AS named as_0. This is not required for routes to networks defined for OSPFInterface objects because those are exported automatically.

The steps are first performed for firewall A.

First, add another Dynamic Routing Policy Rule.

Command-Line Interface

First, change the context to be the main routing table:

System:/> cc RoutingTable main

Next, add a RouteExportRule object:

System:/RoutingTable/main> add RouteExportRule
Added RouteExportRule/1.

Now, change the context to be this new RouteExportRule object:

System:/RoutingTable/main> cc RouteExportRule 1

With the new context, add a ExportToOSPF object:

				add ExportToOSPF

Finish by returning to the default CLI context:

System:/RoutingTable/main/RouteExportRule/1> cc

The property DestinationNetworkIn=all-nets-ip4 is specified for the DynamicRoutingTableRTable object to specify that all routes are to be exported. If the only route to be exported is the all-nets-ip4 route then the property set should be DestinationNetworkExactly=all-nets-ip4.

The same procedure should be repeated for firewall B.

6.6.7. OSPF Troubleshooting

The OSPF CLI command

The CLI command ospf provides various options for examining the behavior of OSPF in real-time on a particular.

In order to see general OSPF activity on a CLI console, the -snoop option can be used:

System:/> ospf -snoop=on

Usually, there is only one OSPFProcess defined for a firewall and there is therefore no need to specify this explicitly in the command. The snooping processes is turned off with:

System:/> ospf -snoop=off

Snoop messages have the prefix SNP: to distinguish them from other console output.

A snapshot of the state of any of the different OSPF components can be displayed. For example, if an OSPFInterface object has the name ospf_if1, details about this can be shown with the command:

System:/> ospf -interface ospf_if1

A similar snapshot can be displayed for areas, neighbors, routes and LSAs. For example, to display the area_0 OSPF area. within the AS called as_0:

System:/> ospf -area as_0/area_0
       Stub: No
    Transit: No
 Interfaces: if1, if3
       LSAs: 3
 ChkSumSums: 0x1d282 - 0x0 - 0x1d282 (Int-Ext-Tot)
* LSAHshLmt: 65

ID  Type         Link ID       ADV Router    Age  Seq#
--  -----------  ------------  ------------  ---  ----------
4   Network-LSA  865  0x80000001
2   Router-LSA  865  0x80000003
1   Router-LSA  861  0x80000002

Note that the area name needs to be qualified with the AS name.

For example, to display OSPF neighbors:

System:/> ospf -neighbor
 Neighbor: (
Interface: if3
     Prio: 1
  Options: E
    State: FULL
   Expire: 25

ID  Type         Link ID       Age  Seq#
--  -----------  ------------  ---  ----------
4   Network-LSA    6    0x80000001
2   Router-LSA   6    0x80000003

OSPF interface operation can also be selectively halted and restarted. For example, to stop the OSPFInterface called ospf_if1, the CLI command would be:

System:/> ospf -ifacedown ospf_if1

To restart the same interface:

System:/> ospf -ifacedown ospf_if1

An entire functioning OSPFRouteProcess can also be halted. For example, assuming that there is only one OSPFRouteProcess object defined in the configuration, the CLI command to halt it is:

System:/> ospf -execute=stop

To start the stopped OSPFRouteProcess:

System:/> ospf -execute=start

To stop and then start in a single command:

System:/> ospf -execute=restart

The ospf command options are fully described in the separate Clavister NetShield Firewall CLI Reference Guide.

Checking Routing Tables

It is possible to check that routing information is being exchanged by examining the routing tables.

Routes that have been imported into the routing tables though OSPF are indicated with the letter "O" to the left of the route description. For example, the routes command might give following output:

System:/> routes
Flags Network         Iface       Gateway         Local IP   Metric
----- --------------- ----------- --------------- ---------- ------  if1                                    0   if3                                    0
O  if3                 1

Here, the route for has been imported via OSPF and that network can be found on the if3 interface with the gateway of The gateway in this case is of course the Clavister NetShield Firewall to which the traffic should be sent. That firewall may or may not be attached to the destination network but OSPF has determined that that is the optimum route to reach it.

Additional OSPF Log Event Messages

By default, a range of basic log event messages are generated by OSPF operation within cOS Stream. For example, if the OSPFProcess object running in cOS Stream is called my_ospf_proc, normal log generation would be enabled with the CLI command:
System:/> set OSPFProcess my_ospf_proc LogEnabled=Yes
This is the default setting so the command is only for illustration.

The following properties can be enabled to provide additional OSPF log messages for troubleshooting and/or monitoring purposes:

  • DebugPacket - Log general packet parsing events.

  • DebugHello - Log Hello packets.

  • DebugDDesc - Log database description packets.

  • DebugExchange - Log exchange packets.

  • DebugLSA - Log LSA events.

  • DebugSPF - Log SPF calculation events.

  • DebugRoute - Log routing table manipulation events.

Each of these properties can be assigned one of the following values:

  • Off - Nothing is logged.
  • Low - Logs all actions.
  • Medium - Logs all actions but with more detail.
  • High - Logs everything with maximum detail.

[Note] Note: The High setting generates large amounts of data

When using the High setting, the firewall will log a large amount of information, even when just connected to a small AS. Changing the value of the property LogSendRateLimit for the log receiver object may be required.

Example 6.15. Enabling OSPF Debug Log Events

In this example, the DebugHello and DebugRoute log events will be enabled for the OSPFProcess called my_ospf_proc.

Command-Line Interface

System:/> set OSPFProcess my_ospf_proc DebugHello=Low DebugRoute=High

OSPF Statistics

OSPF makes available a number of statistical values that can be monitored from a CLI console. To add monitoring of all OSPF statistics, use the command:
System:/> statistics -add /routing/ospf/*

To display the current values of the added OSPF statistics, the above command should be followed with:

System:/> statistics
Name                                              Value  Unit
------------------------------------------------  -----  --------------
/routing/ospf/pkt_errors                          0      packets
/routing/ospf/processes/ospf1/adjacency_failures  0      adjacencies
/routing/ospf/processes/ospf1/lsa_current         3      advertisements
/routing/ospf/processes/ospf1/lsa_errors          0      advertisements
/routing/ospf/processes/ospf1/lsa_max             3      advertisements
/routing/ospf/processes/ospf1/routers_current     1      routers
/routing/ospf/processes/ospf1/routers_max         1      routers
/routing/ospf/processes/ospf1/routes_current      3      routes
/routing/ospf/processes/ospf1/routes_max          3      routes

6.7. BGP


Border Gateway Protocol (BGP) allows the exchange of routing information between an Autonomous System (AS) and other Autonomous Systems. The Clavister NetShield Firewall can act as a single AS and use BGP to both import routes from and export routes to other autonomous systems.

BGP is implemented in cOS Stream in a similar way to OSPF. A single BGPProcess object must be defined which identifies the firewall as an AS with an AS number and router ID. Other objects are then added to define BGP neighbors as well as what routes can be imported from these neighbors and what routes can be exported to them.

BGP can both import and export routes from/to local routing tables as well as OSPF-processes.

In the simplest scenario, BGP setup will involve the following 3 steps:

A. Set up a BGP process that can communicate with other BGP processes.

B. Add process rules to import routes from BGP processes.

C. Add rules to export routes to BGP processes.

A detailed description of these three steps along with examples are given next.

A. Set up a BGP process that can communicate with BGP neighbors:

  • Create a BGPProcess object and set the ASNum and RouterID properties. Only a single BGPProcess object instance can be created in a firewall. The RouterID must be specified as an IPv4 address.

  • Add BGPNeighbor object as a child of the BGPProcess for each neighbor that the process will exchange routes with. At least one must be added.

    The IPAddress and RemoteASNum properties must be specified for the neighbor. IPv4 and IPv6 neighbor addresses can be mixed in a single process. The RemoteASNum property value must match the AS number of the neighbor BGP process but the IPAddress does not have to be the same as the Router ID of the neighbor.

Example 6.16. Setting Up a BGP Process with Neighbors

This example shows how a BGP process is created with associated neighbors. It is assumed the process will have a private AS number of 64512 and its ID specified as the private IPv4 address

A single BGP neighbor will be associated with the process that has the IPv4 address

Note that this and later examples use private IP addresses and private AS numbers. It is assumed that the AS is not connected to the public Internet.

Command-Line Interface

Add the BGPProcess object:

System:/> add BGPProcess my_bgp ASNum=64512 RouterID=

Change the CLI context to be the BGP process:

System:/> cc BGPProcess my_bgp

Add a BGPNeighbor as a child:

System:/BGPProcess/my_bgp> add BGPNeighbor

B. Add process rules to import routes from neighbors:

  • Add at least one RouteExportRuleBGP object as a child of the BGPProcess. The DestinationRouteIn property must be set to a network range. Only routes within that range will be imported from neighbors to one or more destinations. The destinations are specified in the next step.

  • Add at least one ExportToRoutingTable object as a child of the RouteExportRuleBGP created in the previous step. This new child object must have its Destination property set to a destination for the imported routes. The destination can be either a RoutingTable object or an OSPFProcess object.

    Multiple ExportToRoutingTable objects could be added if there is a need to send the same imported routes to multiple destinations.

Example 6.17. Adding Rules to Import Routes to a BGP Process

This example continues from the previous example and adds rules to the BGP process to import routes from neighbors. Only routes within the network will be imported and they will be inserted into cOS Stream's main routing table.

Command-Line Interface

Make sure the CLI context is the BGP process:

System:/> cc BGPProcess my_bgp

Add a child RouteExportRuleBGP object to import all routes within

System:/BGPProcess/my_bgp> add RouteExportRuleBGP 

Change the CLI context to be the rule:

System:/BGPProcess/my_bgp> cc RouteExportRuleBGP 1

Add an ExportToRoutingTable object as a child to specify the destination:

			add ExportToRoutingTable

Return to the default CLI context:

System:/BGPProcess/my_bgp/RouteExportRuleBGP/1> cc

C. Add rules to export routes to neighbors:

  • Add at least one RouteExportRule object as a child of a RoutingTable object. The DestinationNetworkIn property of the object must be set to a network range for the routes that will be exported.

  • Add an ExportToBGP object as a child of the RouteExportRule. The ExportToProcess property of this object must be set to the BGPProcess object created previously.

Example 6.18. Adding Rules to Export Routes to BGP Neighbors

This example continues from the previous example and adds a rule to cOS Stream's main routing table to export routes to BGP neighbors.

Command-Line Interface

Change the CLI context to be the main routing table:

System:/> cc RoutingTable main

Add a child RouteExportRule object to export all routes within

System:/RoutingTable/main> add RouteExportRule 

Change the CLI context to be the rule:

System:/RoutingTable/main> cc RouteExportRule 1

Add an ExportToRoutingTable object as a child to specify the destination:

			add ExportToBGP

Return to the default CLI context:

System:/RoutingTable/main/RouteExportRule/1> cc

Dynamically Applying Changes to Exchanged Routes

It is possible to dynamically apply specified modifications to given routes as they are exported to a particular neighbor or imported from a particular neighbor. The modifications could, for example, involve changing the route's next-hop or metric, or a variety of other parameters such as community related options.

Specifying such dynamic changes is done with the following steps:

  • Specify the affected route(s) by creating a RoutePrefixList object and add one or more child RoutePrefixEntry objects. Set the Network property of each RoutePrefixEntry object to filter out the affected routes.

  • Create a RouteMap object to specify the change to be made. The MatchIP property of this object is set to the RoutePrefixList created in the previous step and the appropriate property should be chosen to make the required change.

    For example, the SetNextHop property would be used to change the next-hop of the routes filtered by the RoutePrefixList. All the available properties that can be set can be found under the entry for the RouteMap object in the separate CLI Reference Guide.

  • For the BGPNeigbor object to which the changes will apply, set its RouteMapOut property to the RouteMap created in the previous step, if exported routes are to be changed. If routes imported from the neighbor are to be changed, the RouteMapIn property should be set to the RouteMap.

Using these steps is illustrated in the example below.

Example 6.19. Applying Dynamic Changes to BGP Routes

This example will change the next-hop of the exported route for the host at IP address

Command-Line Interface

Create a new RoutePrefixList object:

System:/> add DynRouteObject RoutePrefixList my_net

Change the CLI context to this list:

System:/> cc DynRouteObject RoutePrefixList my_net

Add a child RoutePrefixEntry object to specify the host:

System:/RoutePrefixList/my_net> add RoutePrefixEntry 

Return to the default CLI context:

System:/RoutePrefixList/my_net> cc

Create a new RouteMap object:

System:/> add DynRouteObject RouteMap my_map

Change the CLI context to this map:

System:/> cc DynRouteObject RouteMap my_map

Add a child RouteMapEntry object to specify the desired change:

System:/RouteMap/my_map> add RouteMapEntry 

Return to the default CLI context:

System:/RoutingTable/main/RouteExportRule/1> cc

Change the CLI context to be the BGP process:

System:/> cc BGPProcess my_bgp

Set the route map to use for routes exported a specific neighbor:

System:/BGPProcess my_bgp> set BGPNeighbor 1 

Return to the default CLI context:

System:/RoutingTable/main/RouteExportRule/1> cc

[Note] Note: Configuration with BGP

When BGP is configured with SIIT or NAT64, BGP export needs to be configured accordingly. This is discussed further in section 3.2 of RFC 6052.

Using BFD

Using Bidirectional Forwarding Detection (BFD) with BGP allows very fast failover time when a neighbor becomes unreachable. By default, it is disabled with BGP and is enabled by setting the value of the property FalloverDetection to BFD in the relevant BGPNeighbor object.

The following should be noted about using BFD:

  • For BFD to function, it must be enabled in all communicating BGP neighbors. In other words, on both sides of each neighbor pair.

  • For a standalone firewall that is not part of an HA cluster, enabling both BFD and the GracefulRestart property of the BGPProcess object should be avoided. This is because BFD will detect neighbor failure instantly and GracefulRestart will try to send traffic regardless of failure.

  • For an cOS Stream HA cluster, both BFD and GracefulRestart can be enabled together (enabling GracefulRestart is a requirement for HA).

  • The following four properties in BGPNeighbor can be used to modify BFD behavior:

    • BFDTransmitInterval

      The minimum interval between transmitting BFD hello packets to a neighbor with which a BFD session has been established (default, 250 msecs).

    • BFDReceiveInterval

      The minimum expected interval between receiving BFD hello packets from a neighbor with which a BFD session has been established (default, 250 msecs).

    • BFDHelloMultiplier

      The number of hello packets not received from a neighbor before the neighbor is consider unreachable (default, 3).

    • BFDSlowTimerInterval

      This determines how fast a new BFD session is started and can be used to slow asynchronous sessions (default, 2000 msecs)

    These properties are also discussed in the separate cOS Stream CLI Reference Guide.

BGP With High Availability Clusters

If a failover occurs in an HA cluster that is running BGP, the following should be noted:
  • To allow BGP to restart, the GracefulRestart and GracefulReset properties of the BGPProcess object should be enabled, as well as the GracefulRestart property of all BGPNeighbor objects.

    These properties, or their equivalent, should also be enabled on any BGP routers communicating with the firewall.

  • The routes set up by BGP are state synchronized and will be unaffected by the failover. This means that all traffic flows that use these routes will be unaffected after the failover completes.

  • The objects involved in BGP setup, such as the BGPProcess object, are not state synchronized. This means that the BGP mechanisms will be automatically set up again by cOS Stream after the failover.

  • The GracefulRestartTime and GracefulStalePath properties of the BGPProcess object should be set to the appropriate values. If the restart is too fast, information can be lost. It should be long enough to allow all internal BGP mechanisms to be fully initialized. The more routes and complexity, the more time that is required. Other factors include the number BGP peers and uplink speed. Trial and error may be required to find the appropriate settings.

  • As mentioned earlier, BFD could also be enabled for an HA cluster. However, note that BFD is separate from the HA cluster failover mechanism. A BFD failure will never trigger an HA failover.

6.8. Traceroute


The cOS Stream traceroute command provides information about the routes that packets take as they traverse the routers in the external network and the round-trip transit time to and from these routers. A similar traceroute command is found on many other systems such as Microsoft Windows™.

How Traceroute Functions

Traceroute functions by sending packets with a time-to-live (TTL) value that starts at 1 and is progressively incremented for subsequent packets. A router will decrement the time-to-live as a packet traverses it. If the value becomes zero, the packet is dropped by the router and an ICMP time-exceeded message is sent back to the source which sends another packet with a time-to-live of 2 in order to reach the next router. The incrementing of the time-to-live continues until the intended destination is reached. The ICMP time-exceeded messages sent back by the routers between the source and destination provide the basis for the traceroute output.

By default, cOS Stream sends its traceroute packets as ICMP ping messages. However, the option exists to send messages using either UDP or TCP.

The Basic Traceroute Command Format

The basic form of the traceroute command is the following:
System:/> traceroute <host>
The <host> can be either an IPv4 or IPv6 address, for example:
System:/> traceroute
Alternatively, <host> can be a DNS resolvable Fully Qualified Domain Name (FQDN), for example:
System:/> traceroute
When using traceroute with an FQDN, at least one DNS server must have been configured in cOS Stream to perform the resolution. Doing this is described in Chapter 12, DNS.

The equivalent command to the above when sending a UDP message would be:

System:/> traceroute -udp

The equivalent when sending a TCP message would be:

System:/> traceroute -tcp

Note that the UDP and TCP options must appear before the host in the command.

Manually Terminating Traceroute

After entering the traceroute command, cOS Stream will continue to send messages until either the trace is complete or the command is manually terminated. Manual termination is done by entering CTRL-C on the keyboard.

Traceroute Output

Below is some typical output from traceroute using the default settings with the destination specified as an FQDN:
System:/> traceroute
Traceroute to, 32 hops max, 32-byte packets	
1    <1 ms    10 ms    10 ms
2    10 ms    10 ms    10 ms
3    10 ms     0 ms    10 ms
Here, each line of output corresponds to an attempt by traceroute to reach the next router. The first column is the hop number.

By default, traceroute tries 3 times for each router hop and the Round Trip Time (RTT) for each attempt expressed in milliseconds is shown in the three columns that follow the hop number. In the example above, there were two routers in the path to the target destination, hop number 1 and hop number 2. The final hop. number 3, is the destination which was DNS resolved as the IPv4 address

The Route Can Change

Given the dynamic nature of a packet switch network, it is possible for consecutive packets sent by the traceroute command to pass through different sets of routers. It is difficult to know that this is occurring and it is not indicated in the command output.

It is also possible that different routers could have responded for a given hop value. The address displayed at the end of lines of traceroute output under the Host column is always the router that dealt with the last ICMP message sent for that hop.

Additional Traceroute Options

The following are some of the other options that can be used with the traceroute command:

  • -ipver

    When the destination is specified as an FQDN, by default cOS Stream will only request an IPv4 address from the resolving DNS server and will use that as the destination address. This option must be used if only an IPv6 address is to be used as the destination address. For example:

    System:/> traceroute -ipver=6

    Alternatively, the IPv6 address could be entered directly after the traceroute command.

  • -maxttl

    This specifies the maximum value for the time-to-live parameter of the packets sent.

    System:/> traceroute -maxttl=20

    The default value is 30.

    Note that if cOS Stream gets no response from a router within the set timeout (the default is 1 second) then it will continue to send ICMP ping messages with an increasing time-to-live value until the -maxttl limit is reached.

  • -queries

    This specifies how many attempts are made for each hop. For example:

    System:/> traceroute -count=1

    The default value is 3.

  • -length

    This specifies how large the sent payload is. The payload itself is made up of zeros. For example:

    System:/> traceroute -length=128

    The default value is 32.

  • -interval

    This specifies the number of milliseconds between each query (the default is 1000 milliseconds). For example:

    System:/> traceroute -interval=100

    An interval of zero means the messages are sent continuously and can simulate a denial of service attack.

  • -ttl

    This specifies what time-to-live (TTL) value to start with and therefore at which hop to start. For example:

    System:/> traceroute -ttl=3

    The default value is 1.

  • -noresolve

    This switches off the default behavior of resolving host names in the output from the command. For example:

    System:/> traceroute -noresolve

    The principle reason to use this option is that omitting host name resolution makes the command execution faster.

  • -timeout

    This is the amount of time cOS Stream will wait for a response from a router or the destination before it increases the time-to-live and tries again.

    System:/> traceroute -timeout=2000

    Any timeout conditions are indicated in the traceroute output. An example of this is shown below:

    System:/> traceroute
    Traceroute to, 32 hops max, 32-byte packets
    1     0 ms     0 ms    10 ms
    2    10 ms    10 ms    10 ms
    3    10 ms    10 ms    10 ms
    4     *        *        *     Request timed out

    A timeout could occur because any of the following:

    1. A router or the destination may not be set up to respond to the messages sent
    2. The destination host may be offline.

  • -verbose

    This option provides some additional information, including the routing table used. For example:

    System:/> traceroute -verbose
    Traceroute to, 32 hops max, 32-byte packets	(IPv4 ICMP)
    Using route " via if2 , gw:" in routingtable "main":
    1    <1 ms    10 ms    10 ms
    2    10 ms    10 ms    10 ms
    3    10 ms     0 ms    10 ms

The full list of options can be found in the separate CLI Reference Guide.

Chapter 7: IP Rules

7.1. Security Policies

Before examining IP rule sets in detail, it is useful to first look at the general concept of security policies to which IP rule sets belong.

Security Policy Characteristics

Security policies are configured by the administrator to regulate the way in which traffic can flow through the Clavister NetShield Firewall. Such policies are described by the rules defined in various rule sets. These rule sets share a uniform means of specifying filtering criteria which determine the type of traffic to which they will apply. Usually, the filtering criteria consist of the following rule properties:

Source Interface
An Interface where the packet is received on the Clavister NetShield Firewall. This could also be a physical Ethernet interface but might be a configuration object that acts as an interface such as a VPN tunnel.
Source Network
The network that contains the source IP address of the packet. This is usually an IP address object which defines a single IP address, a range of addresses or a network.
Destination Interface
An Interface from which the packet would leave the Clavister NetShield Firewall. This could also be a physical Ethernet interface but might be a configuration object that acts as an interface such as a VPN tunnel.
Destination Network
The network to which the destination IP address of the packet belongs. This is usually an IP address object which defines a single IP address, a range of addresses or a network.

The protocol type to which the packet belongs. Service objects define different protocols. Examples are HTTP and ICMP communication.

A number of predefined service objects exist but administrator defined custom services can also be created. Existing service objects can also be collected together into Service Groups so that a group can be specified in a policy rule instead of a single service.

IP Rules and the Default main Rule Set

IP rule sets are the most important of cOS Stream's security policy rule sets. They determine the critical packet filtering function of cOS Stream, regulating what is allowed or not allowed to pass between different interfaces and between interfaces and cOS Stream.

By default, one IP rule set always exists and this has the name main. The object type IPRuleSet exists in the category RuleSet so the CLI command to change the context to main is:

System:/> cc RuleSet IPRuleSet main

If tab completion is not being used, this can be shortened to

System:/> cc IPRuleSet main

Examples in this guide will assume tab completion is used with the longer form.

There are two possible approaches to how traffic traversing the Clavister NetShield Firewall could be dealt with:

  • Everything is denied unless specifically permitted.

  • Or everything is permitted unless specifically denied.

To provide optimal security from the outset, cOS Stream uses the first of these approaches. This means that when started for the first time, cOS Stream has no IP rules defined in the main IP rule set and all traffic arriving at all interfaces is therefore dropped. In order to permit any traffic to traverse the Clavister NetShield Firewall (as well as allowing cOS Stream to respond to ICMP Ping requests), some initial IP rules must be added to the configuration.

Each IP rule that is added by the administrator will define the following basic filtering criteria:

  • From what interface to what interface traffic flows (the Source Interface and Destination Interface).

  • From what network to what network the traffic flows (the Source Network and Destination Network).

  • What kind of protocol is affected (the Service).

  • What action the rule will take when a match on all the criteria is triggered (the Action).

IPv4 and IPv6 addresses for the network properties can coexist in the same IP rule set as well as in the same IP rule.

Specifying Any Interface or Network

When specifying the filtering criteria in any of the rule sets specified above there are a number of useful predefined filtering parameters that can be used:

  • For a Source or Destination Network, the all-nets-ip4 address object is equivalent to the IPv4 address which will mean that any IPv4 address is acceptable.

    Similarly, the all-nets-ip6 address object is equivalent to any IPv6 address. The address object all-nets includes both all-nets-ip4 and all-nets-ip6.

  • For Source or Destination Interface, the any option can be used so that cOS Stream will not care about the interface which the traffic is going to or coming from.
  • The Destination Interface can be specified as core. This means that traffic, such as an ICMP Ping, is destined for the Clavister NetShield Firewall itself and cOS Stream will respond to it.

    New flows that are initiated by cOS Stream itself do not need an explicit IP rule as they are allowed by default. For this reason, the interface core is not used as the source interface.

  • The Service can be specified as all_services which includes all possible protocols.

Traffic Flow Needs an IP Rule and a Route

As stated above, when cOS Stream is started for the first time, all traffic is dropped so at least one IP rule must be added to allow the traffic to flow. In fact, the following conditions need to be satisfied:

  • A route must exist in a routing table which specifies on which interface packets should leave in order to reach their destination.

    A second route must also exist that indicates the source of the traffic is found on the interface where the packets enter. This satisfies the reverse route lookup check performed by cOS Stream when a new flow is established.

  • An IP rule in an IP rule set which specifies the security policy that allows the packets from the source interface and network bound for the destination network to leave the Clavister NetShield Firewall on the interface decided by the route.

    If the IP rule used is an Allow rule then this is bi-directional by default.

The ordering of these steps is important. The route lookup occurs first to determine the exiting interface and then cOS Stream looks for an IP rule that allows the traffic to leave on that interface. If a rule does not exist allowing the traffic then it is dropped.

Simplified Traffic Flow

Figure 7.1. Simplified Traffic Flow

Before the route lookup is done, cOS Stream first checks that traffic from the source network should, in fact, be arriving on the interface where it was received. This is done by cOS Stream performing a reverse route lookup which means that the relevant routing table is searched for a route that indicates the network should be found on that interface.

This second route should logically exist if a flow is bi-directional and it must have a pair of routes associated with it, one for each direction.

Changing Multiple IPRule Objects Together

Because IP rules are indexed objects (each rule has a unique number in its rule set) it is possible to either apply the set or delete commands to multiple rules at the same time by using the -Range option.

For example, to change the LogEnabled property for all IP rules from index number 65 to 80 (inclusive), the command would be the following:

System:/> cc RuleSet IPRuleSet main
System:/IPRuleSet/main> set IPRule -Range=65-80 LogEnabled=No

A general discussion of the -Range option can be found in Section 2.1.3, The CLI.

IP Rule Snooping

A helpful troubleshooting command that can be used to see which IP rules are triggering in real-time is rulesnoop. However, this command is only available when the advanced command view is first enabled using the following command:
System:/> cmdview advanced
The rulesnoop command allows the administrator to receive messages on the console when IPRule objects trigger. Filters can be added to the command to specify which types of rules are of interest. The basic form of the command should specify the receive interface (in other words the SourceInterface of the IP rule). The value ALL can be used to specify all interfaces:
System:/> rulesnoop all
If the administrator is only interested in turning on rule snooping for the if1 interface then the command would be:
System:/> rulesnoop if1
In addition, a destination network and/or a source network can be specified as filters for the command. The destination network filter must always be specified first and can be the special value all-nets. For example, to apply a destination network filter for, the command would be the following:
System:/> rulesnoop if1
The -verbosity parameter can be used to increase the amount of detail provided. The default value for this parameter is BASIC but this can be increased to INFORMATIVE and then increased further to EXTREME. For example:
System:/> rulesnoop if1 -verbosity=informative

Rule snooping will continue until either CTRL-C is typed by the administrator or the following command is entered:

System:/> rulesnoop none

A complete list of rulesnoop options can be found in the separate CLI Reference Guide.

7.2. IP Rule Evaluation

When a new flow, such as a TCP/IP connection, is being established through the Clavister NetShield Firewall, the list of IP rules are evaluated from top to bottom until a rule that matches the parameters of the new flow is found. The first matching rule's Action is then performed. For this reason, the ordering of the IP rules in the rule set is important.

If the action in the matching IP rule allows it then the establishment of the new flow will go ahead. A new entry representing the new flow will then be added to the internal list of active flows. This list allows monitoring of opened and active flows.

If the matching IP rule action is Deny or Reject then the flow is not set up.

[Tip] Tip: Rules in the wrong order can cause problems

It is important to remember the principle that cOS Stream searches the IP rules from top to bottom, looking for the first matching rule.

If an IP rule seems to be ignored, check that some other rule above it is not being triggered first.

Stateful Inspection

After initial rule evaluation of the opening flow, subsequent packets belonging to that flow will not need to be evaluated individually against the rule set. Instead, a highly efficient algorithm searches the flow table for each packet to determine if it belongs to an established flow.

This approach is known as stateful inspection and is applied not only to stateful protocols such as TCP but also by means of "pseudo-connections" to stateless protocols such as UDP and ICMP. This approach means that evaluation against the IP rule set is only done in the initial opening phase of a flow. The size of the IP rule set consequently has negligible effect on overall throughput.

Flows are unidirectional. This means that a typical traffic connection, for example between a web browsing client and a web server, will consist of two flows. This is not the case with the ESP flows used in IPsec where only a single flow is required for the connection.

Examining Flows

All current flows can be shown using the flow CLI command. Some typical output is shown below:
System:/> flow -show
Proto   Source                        Destination                   Timeout
------- ----------------------------- ----------------------------- -------
TCP     wan:            core:           262142

If the -verbose option is used then the matching reverse flow for a connection is also shown. The command form is as follows:

System:/> flow -show -verbose