Table of Contents
Intended Audience
The target audience for this reference guide is Administrators who are responsible for configuring and managing Clavister NetShield Firewalls. This guide assumes that the reader has a basic understanding of IP networks and network security.Text Structure and Conventions
The text is broken down into chapters and subsections. Numbered subsections are shown in the table of contents at the beginning. An index is included at the end of the document to aid with alphabetical lookup of subjects.Where a "See chapter/section" link (such as: see Chapter 6, Routing) is provided in the main text, this can be clicked to take the reader directly to that reference.
Text that may appear in the user interface of the product is designated by being in bold case. Where a term is being introduced for the first time or being stressed, it may appear in italics.
Where console interaction is shown in the main text outside of an example, it will appear in a box with a gray background.
System:/>
Where a web address reference is shown in the text, clicking it will open the specified URL in a browser in a
new window (some systems may not allow this).
For example, http://www.clavister.com.
Examples
Examples in the text are denoted by the header Example and appear with a gray background as shown below. They contain a CLI example as appropriate. (The cOS Stream CLI Reference Guide documents all CLI commands.)Example 1. Example Notation
Information about what the example is trying to achieve is found here, sometimes with an explanatory image.
Command-Line Interface
The Command Line Interface example would appear here. It would start with the command prompt followed by the command:
System:/>
somecommand someproperty=somevalue
Highlighted Content
Special sections of text which the reader should pay special attention to are indicated by icons on the left hand side of the page followed by a short paragraph in italicized text. Such sections are of the following types with the following purposes:![]() |
Note |
---|---|
This indicates some piece of information that is an addition to the preceding text. It may concern something that is being emphasized, or something that is not obvious or explicitly stated in the preceding text. |
![]() |
Tip |
---|---|
This indicates a piece of non-critical information that is useful to know in certain situations but is not essential reading. |
![]() |
Caution |
---|---|
This indicates where the reader should be careful with their actions as an undesirable situation may result if care is not exercised. |
![]() |
Important |
---|---|
This is an essential point that the reader should read and understand. |
![]() |
Warning |
---|---|
This is essential reading for the user as they should be aware that a serious situation may result if certain actions are taken or not taken. |
Trademarks
Certain names in this publication are the trademarks of their respective owners.Clavister NetShield Firewall and cOS Stream are trademarks of Clavister.
Windows is either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.
Apple, Mac and Mac OS are trademarks of Apple Inc. registered in the United States and/or other countries.
VMware is the registered trademark of VMware, Inc. in the United States and/or other countries.
![]() |
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 https://my.clavister.com. It is also available in a framed HTML version. |
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: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.
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.
Product Education and Certification
For details about classroom and online education as well as certification, visit the Clavister company website at http://www.clavister.com or contact your local sales representative.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.
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
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.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.
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.
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.
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.
A route lookup is made using the routing table. The destination interface for the flow has now been determined.
The IP rules are now searched for a rule that matches the packet. The following parameters are part of the matching process:
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.
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.
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.
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: 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
Name
----------
AdminUsers
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
User
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>
ccSystem:/>
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 AdminUsersSystem:/LocalUserDatabase/AdminUsers>
add User audit Password=audit Groups=Auditors
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.
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:
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.
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.
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
SourceInterface=if1
SourceNetwork=if1_net
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:
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:Authenticating username and password credentials against a local user database in cOS Stream. These databases are described further in Section 2.1.2, The Local User Database.
Authenticating username and password credentials against an external RADIUS database. This feature is described further in Section 2.1.6, RADIUS Management Authentication.
Authenticating using a public/private key pair. Setting this up is described next.
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 my_key.pub, the CLI would be:
System:/>
add SSHClientKey my_pub_key
PublicKey=file://my_key.pub
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>
ccSystem:/>
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: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.
<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: 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 10.49.02.01, the command would be:
System:/>
add Address IPAddress my_address Address=10.49.02.01
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:System:/>
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-system1After activating the change, the CLI prompt becomes the following:
my-system1:/>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
COMMAND
time (t). Display and set current system time.
"
"
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 mainSystem:/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
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. 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
IPAddress=my_log_server_ip
LogSeverity=
If the tab character is now entered, a list of available options is displayed for the LogSeverity property:
System:/>
add LogReceiver LogReceiverSyslog my_receiver
IPAddress=my_log_server_ip
LogSeverity=(tab)
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:
Name
-----------
<empty>
Debug
Information
Notice
Warning
Error
Critical
Alert
Emergency
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 203.0.113.10. 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=203.0.113.10
Entering the " * " (asterisk/star) character before entering tab will cause the default property value to be automatically filled in.
System:/>
set RemoteManagement RemoteMgmtSSH RemoteMgmtSSH
LogEnabled=?(tab)
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 mainSystem:/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
Interface=if1
Network=if1_net
Name=new_route1
To return to the default CLI context, the command is cc on its own:
System:/RoutingTable/main> cc
System:/>
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:AccountingServers=server1,server2,server3
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: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. 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.System:/>
add OSPFProcess Name=my_process1 RouterID=ip_ospf1 Added OSPFProcess OSPFSystem:/>
set OSPFProcess OSPF1 RouterID=<empty> Updated OSPFProcess OSPF
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.
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:
System:/>
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!"
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
SessionIdleTime=1000000
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.
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
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:
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 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.
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:
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).
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.
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 |
---|---|
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. 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
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: 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 126.12.11.01 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 126.12.11.01 "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=126.12.11.01 Comments="if1 address"
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. 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.
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. 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=10.6.60.10 add IPAddress if1_net Address=10.6.60.0/24 add IPAddress if1_br Address=10.6.60.255 add IPAddress if1_dns1 Address=141.1.1.1 " " "
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.
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: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: 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. |
# The following line defines the if1 IPv4 address add Address IPAddress if1_ip Address=10.6.60.10
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.sgscOS 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.
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:
<user_name>@<firewall_ip_address>:<filepath>
For example:
admin@10.62.11.10:config.bkp
The <user_name> must be a defined user belonging to the administrator user group.
![]() |
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 10.5.62.11 then to upload a configuration backup file called config.bkp from the local disk, the SCP command would be:
> scp config.bkp admin1@10.5.62.11:.
To download a configuration backup to the current local directory, the command would be:
> scp admin1@10.5.62.11:config.bkp .
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 192.168.3.1:
> scp C:\cert-1.cer admin@192.168.3.1:
> scp C:\cert-1.key admin@192.168.3.1:
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.
> scp admin@192.168.3.1:*.mib .
To download all the downloadable files:
> scp admin@192.168.3.1:* .
Wildcards can also be used when uploading. For example, to upload all the backup files
in the current directory:
> scp *.bkp admin@192.168.3.1:.
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: 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:
LocalUserDB=""
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:
RemoteServer=my_radius_server1
More than one server can be specified:
RemoteServer=my_radius_server1,my_radius_server2
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:
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.
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.
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:
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.
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=192.168.1.1 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=192.168.1.1 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=192.168.1.1 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=192.168.1.1 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
LocalUserDB=""
RemoteServer=my_radius_auth1,my_radius_auth2
RemoteLoadBalance=RoundRobin
AuthOrder=LocalLast
MultipleLogins=AllowOne
Now, use this profile with the default RemoteMgmtSSH object:
System:/>
set RemoteManagement RemoteMgmtSSH RemoteMgmtSSH
AuthProfile=my_mgmt_auth_profile
Overview
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:
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:
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.
> scp admin@192.168.1.17:/*.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:IfPktsTotCnt OBJECT-TYPE SYNTAX Counter32 MAX-ACCESS read-only STATUS current DESCRIPTION "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.
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
SourceInterface=lan
SourceNetwork=mgmt-net
GetCommunity=my-community-string
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.
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.
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.
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
SourceInterface=if1
SourceNetwork=if1_net
LocalUserDB=AdminUsers
PrivacyPassword=mysecretpassword
RequestLimit=20
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.
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: 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: 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. |
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 10.5.4.36 and 10.5.4.76. 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=10.5.4.36 Name=my_tsrv1
Now add the second server:
System:/DateTime>
add TimeServer IP=10.5.4.76 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 requestedSystem:/>
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.Overview
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.
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
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: Backup files are temporary |
---|---|
Any backup files created are not held in permanent memory and will disappear after system restarts. |
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@10.5.62.11:.
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: 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. |
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. 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.
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.
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 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
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
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: 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:<date><time><module>.dumpWhere the <module> identifies the module which is the source of the crashdump, preceded by the date and time of the crash occurring. For example:
2011-01-01_00.00.36_rtbld.dump
![]() |
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: 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. |
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:
/interfaces/common/[..n]/bytes_recv
Where [..n] represents the name of the interface.
For example, the bytes_recv statistic associated with the if1 interface is identified with the path:
/interfaces/common/if1/bytes_recv
These variable references in paths are indicated in the Statistics Reference Guide using the [..n] notation.
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.cOS Stream provides a set of CLI commands to help with troubleshooting problems. These commands are described in this section.
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 10.4.0.2. The CLI command would be:System:/>
ping 10.4.0.2
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 10.4.0.2 -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 10.4.0.2, the command would be:System:/>
ping -udp 10.4.0.2
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 203.0.113.10 -port=80 -request="GET /HTTP/1.0\n\n"
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
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 10.4.0.2 -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 192.168.0.10:
System:/>
ping 10.6.58.10 -srciface=if2 -srcip=192.168.0.10 -verbose
This command will construct an ICMP packet with a destination IP of 10.6.58.10 and cOS Stream will behave as though that packet had arrived at the interface if2 and had come from the external IP address 192.168.0.10.
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 192.168.14.1 -srciface=if14 -srcip=192.168.14.12 -verbose
Simulating 4-byte ICMP ping to 192.168.14.1:44434
from (if14) 192.168.14.12:8
(Response is not displayed when '-srciface' is used)
SNOOP: POLICY-1 : Forward lookup matched PBR rule "RoutingRule_1"
(id 0x3039) against <ICMP if14;192.168.14.12:2048 -> 192.168.14.1:44434>
SNOOP: POLICY-1 : Drop <ICMP
if14;192.168.14.12:2048 -> 192.168.14.1:44434>:
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 Interface |
Source Network |
Destination Interface |
Destination Network |
Service |
---|---|---|---|---|---|
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 192.168.14.1 -srciface=if14 -srcip=192.168.14.12 -verbose
Simulating 4-byte ICMP ping to 192.168.14.1:2524
from (if14) 192.168.14.12:8
(Response is not displayed when '-srciface' is used)
SNOOP: POLICY-1 : Forward lookup matched PBR rule "RoutingRule_1"
(id 0x3039) against <ICMP if14;192.168.14.12:2048 -> 192.168.14.1:2524>
SNOOP: POLICY-1 : <ICMP if14;192.168.14.12:2048 -> 192.168.14.1:2524>:
Found reverse route "Route_3" (ID: 0x3ead62f) 192.168.14.0/24 ->
if14 (Gateway: none) in table "Main" (ID: 0x20).
SNOOP: POLICY-1 : <ICMP if14;192.168.14.12:2048 -> 192.168.14.1:2524>:
Found forward route "Route_3" (ID: 0x3ead62f) 192.168.14.0/24 ->
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;192.168.14.12:2048 ->
192.168.14.1:2524>: 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 192.168.14.1 -srciface=if14 -srcip=192.168.14.12 -verbose
Simulating 4-byte ICMP ping to 192.168.14.1:24093
from (if14) 192.168.14.12:8
(Response is not displayed when '-srciface' is used)
SNOOP: POLICY-1 : Forward lookup matched PBR rule "RoutingRule_1"
(id 0x3039) against <ICMP if14;192.168.14.12:2048 -> 192.168.14.1:24093>
SNOOP: POLICY-1 : <ICMP if14;192.168.14.12:2048 -> 192.168.14.1:24093>:
Found reverse route "Route_3" (ID: 0x3ead62f) 192.168.14.0/24 -> if14
(Gateway: none) in table "Main" (ID: 0x20).
SNOOP: POLICY-1 : <ICMP if14;192.168.14.12:2048 -> 192.168.14.1:24093>:
Found forward route "Route_3" (ID: 0x3ead62f) 192.168.14.0/24 -> 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;192.168.14.12:2048 ->
192.168.14.1:24093>: 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 192.168.0.5 to 10.4.0.2, the command would be the following:System:/>
ping 10.4.0.2 -srcip=192.168.0.5
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.
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: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.
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: 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 192.168.12.200->192.168.12.1 IHL:20 DataLen:12 TTL:59 Proto:ICMP
ICMP Echo request ID:4042 Seq:0
-----------------------------------------------------------------------
IP 192.168.12.1->192.168.12.200 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: 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=203.0.113.3
A range can be specified instead:
System:/>
pcapdump -start if3 -ip=203.0.113.3-203.0.113.7
Or an entire network:
System:/>
pcapdump -start if3 -ip=203.0.113.0/24
Here, IPv4 is mixed with IPv6:
System:/>
pcapdump -start if3 -ip=203.0.113.3,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=203.0.113.3 -ipdest=2001:db8::1
![]() |
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. |
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.
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)
Overview
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.
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: 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 action=none
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:
cOS Stream is in the process of restarting and no values are yet available.
The SensorID property of the HWMONMonitor object does not correspond to any sensor in the hardware.
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.
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
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.
Sensor Name | Sensor Type | Sensor Number | Minimum Limit | Maximum Limit |
---|---|---|---|---|
CPUTemp | TEMP | 0 | 0 | 80 |
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 |
Sensor Name | Sensor Type | Sensor Number | Minimum Limit | Maximum Limit |
---|---|---|---|---|
PSU1 Installed | GPIO | 0 | 0 | 1 |
PSU1 Power OK | GPIO | 256 | 0 | 1 |
PSU1 Temperature | TEMP | 512 | 0 | 0 |
PSU1 Fan Speed | FANRPM | 768 | 5000 | 14000 |
PSU1 Output Voltage | VOLT | 1024 | 0 | 0 |
PSU1 Output Current | CURR | 1280 | 0 | 0 |
PSU1 Input Power | POWER | 1536 | 0 | 0 |
PSU1 Output Power | POWER | 1792 | 0 | 0 |
PSU2 Installed | GPIO | 2048 | 0 | 1 |
PSU2 Power OK | GPIO | 2304 | 0 | 1 |
PSU2 Temperature | TEMP | 2560 | 0 | 0 |
PSU2 Fan Speed | FANRPM | 2816 | 5000 | 14000 |
PSU2 Output Voltage | VOLT | 3072 | 0 | 0 |
PSU2 Output Current | CURR | 3328 | 0 | 0 |
PSU2 Input Power | POWER | 3584 | 0 | 0 |
PSU2 Output Power | POWER | 3840 | 0 | 0 |
System Vcore Internal | VOLT | 4096 | 0 | 1.744 |
System 3.3V Internal | VOLT | 4097 | 0 | 0 |
System 12V Internal | VOLT | 4098 | 11.5 | 13.0 |
System CMOS Battery | VOLT | 4099 | 2.9 | 3.2 |
System 5V Internal | VOLT | 4100 | 0 | 0 |
System FAN1 Speed | FANRPM | 4101 | 6000 | 14000 |
System FAN2 Speed | FANRPM | 4102 | 6000 | 14000 |
System FAN3 Speed | FANRPM | 4103 | 6000 | 14000 |
System Temperature 1 | TEMP | 4104 | 0 | 80 |
System Temperature 2 | TEMP | 4105 | 0 | 80 |
Air Intake Temp | TEMP | 4105 | 0 | 50 |
CPU Temperature | TEMP | 4352 | 0 | 95 |
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.
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 (127.0.0.0/8).
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.
System:/>
show Interface EthernetInterface
Interface Name IP Addresses Routing Table
-------------- ------------ -------------
if1 10.1.50.102 main
if2 10.6.58.100 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 10.1.1.2, we could use the CLI command:
System:/>
set Interface EthernetInterface if1 IPAddress=10.1.1.2
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=10.1.1.2
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
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
Table
--------- ---- ------------- ------ --------
if2 192.168.0.1 Null
Overview
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: 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.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.Assign a name to the VLAN interface.
Select the interface for the VLAN. Either a physical interface or another VLAN object which has been configured as a service VLAN.
Assign a VLAN ID that is unique on the physical interface.
Optionally specify an IP address for the VLAN. If not specified, it defaults to the address of the associated interface.
Optionally specify an IP broadcast address for the VLAN.
Create the required route(s) for the VLAN in the appropriate routing table.
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
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 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.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
Type=88a8
BaseInterface=if3
VLANID=100
A VLAN object can now be added to this:
System:/>
add Interface VLAN vlan1
BaseInterface=svlan_A
VLANID=1
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.
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.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:
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 mainSystem:/IPRuleSet/main>
add IPRule Action=Allow Service=all_services SourceInterface=my_zone1 SourceNetwork=all-nets DestinationInterface=my_zone2 DestinationNetwork=all-nets Name=allow_zone1_to_zone2
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
SecurityEquivalentInterfaces=if2,if3
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
SecurityEquivalentInterfaces=<empty>
The interface if2 and if3 will still be part of the same security/transport equivalent group but now with only 2 members.
Introduction
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: 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. |
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.
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.
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:
L2 - The source and destination MAC addresses (the default).
L2L3 - The source and destination IP addresses.
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. 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 : 172.27.0.90
Private IP : 172.27.0.240
Peer IP : 172.27.0.249
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:
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 : 0.0.0.0
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 : 172.27.0.90
Private IP : 172.27.0.240
Peer IP : 172.27.0.249
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
LAGEnabled=Yes
LAGMembers=if1,if2,if3
LAGMode=BalanceXOR
LAGTxPolicy=L2
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.
Overview
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.
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:Create a new GRETunnel object. This requires at minimum, an IP address for both the local endpoint and the remote endpoint of the tunnel.
Add a Route to the main routing table that routes traffic destined for the remote network into the tunnel.
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: 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:
An ICMP Ping can be sent through the tunnel to this endpoint.
The source IP address of log messages sent through the tunnel from the local tunnel interface.
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.
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 172.16.0.0/16.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 192.168.10.0/24 is lannet on the lan interface, the steps for setting up cOS Stream on A are:In the address book set up the following IP objects:
Create a GRE Tunnel object called GRE_to_B with the following parameters:
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 192.168.11.0/24 is lannet on the lan interface, the steps for setting up cOS Stream on B are as follows:In the address book set up the following IP objects:
Create a GRE Tunnel object called GRE_to_A with the following parameters:
Define a route in the main routing table which routes all traffic to remote_net_A on the GRE_to_A GRE interface.
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
LocalEndpoint=172.16.0.1
RemoteEndpoint=172.16.1.1
RoutingTableMembership=my_gre_rt
IPAddress=192.168.11.1
SessionKey=1
Add a route to send traffic to the remote network:
System:/>
cc RoutingTable my_gre_rtSystem:/RoutingTable/my_gre_rt>
add Route Interface=GRE_to_B Network=192.168.11.0/24
The tunnel GRE_to_A would be configured in a similar way on firewall B.
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: 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: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.
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.
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
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:
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.
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.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 | 192.168.0.10 | 08:00:10:0f:bc:a5 | 45 |
Dynamic | 193.13.66.77 | 0a:46:42:4f:ac:65 | 136 |
Static | 10.5.16.3 | 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 192.168.0.10 is mapped to the MAC address 08:00:10:0f:bc:a5.
The second entry in the table dynamically maps the IPv4 address 193.13.66.77 to the MAC address 0a:46:42:4f:ac:65.
The third entry is a static ARP entry binding the IPv4 address 10.5.16.3 to the MAC address 4a:32:12:6c:89:a4.
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 192.168.10.200 00:50:56:2c:5f:5b 389
if2 Dynamic 192.168.20.1 00:50:56:d0:0f:01 580
if3 Dynamic 192.168.30.1 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 192.168.10.200 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.
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:
The local physical interface for the ARP object.
The IPv4 address for the MAC/IP mapping.
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 192.168.10.15 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
Interface=if2
IP=192.168.10.15
Mode=Static
MACAddress=4b-86-f6-c5-a2-14
Finally return to the default, root context:
System:/ARPEntries>
ccSystem:/>
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 192.168.10.1 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=192.168.10.1 Mode=Publish
Finally return to the default, root context:
System:/ARPEntries>
ccSystem:/>
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.
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: 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.
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, 192.168.0.14.
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, 192.168.0.14,10.15.0.50,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 255.255.255.0). The suffix /27 corresponds to a 32 address net (netmask 255.255.255.224) 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, 192.168.0.10-192.168.0.15 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: 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 192.168.10.16 to the address book:
Command-Line Interface
System:/>
add Address IPAddress www_srv1 Address=192.168.10.16
Example 5.2. Adding an IP Network
This example adds an IP network named wwwsrvnet with address 192.168.10.0/24 to the address book:
Command-Line Interface
System:/>
add Address IPAddress wwwsrvnet Address=192.168.10.0/24
Example 5.3. Adding an IP Range
This example adds a range of IPv4 addresses from 192.168.10.16 to 192.168.10.21 and names the range wwwservers:
Command-Line Interface
System:/>
add Address IPAddress wwwservers
Address=192.168.10.16-192.168.10.21
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 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.
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: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 0.0.0.0/0, 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 object includes all IP4 and IP6 addresses.
The netobjects command shows the current address book contents. For example:
System:/>
netobjects
all-nets 0.0.0.0/0, ::/0
all-nets-ip4 0.0.0.0/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=10.1.1.2,198.10.2.1
There is no limit to the number of addresses that can be assigned to a single Ethernet interface.
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.
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: 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. |
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 10.15.0.50 with network 10.15.0.0/24. 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=10.15.0.50
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=10.15.0.0/24
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> ccSystem:/>
![]() |
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 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 (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>
ccSystem:/>
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:
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
IPv6AddressConfiguration=SLAAC
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 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.
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.
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 203.0.113.0/24 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::203.0.113.0/120
Next, add the IPv6 address 2013.0.113.10 from this network:
System:/>
add Address IPAddress my_mixed_addr Address=2001:db8::203.0.113.10
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 203.0.113.10 as 2001:db8::ffff:203.0.113.10.
Overview
Instead of specifying an address object to be an IP address, it can instead be specified as an FQDN (for example: server1.example.com). 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 Address=server.example.com
The requirement for DNS resolution of an FQDN can also be written explicitly:
System:/>
add Address IPAddress my_fqdn_ip Address=dns:server.example.com
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.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 server.example.com:Here, the FQDN can be specified using the same rules that are described earlier for creating FQDN address objects.System:/>
cc RuleSet IPRuleSet mainSystem:/IPRuleSet/main>
add IPRule SourceInterface=lan SourceNetwork=lan_net DestinationInterface=any DestinationNetwork=dns:server.example.com Service=all_services Name=deny_lan_to_example Action=Allow
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, DNSThe 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. 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
Address=server.example.com
FQDNValidAfterTTL=15000
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 server.example.com. 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 Address=server.example.com
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 www.example.com will not be allowed.
Command-Line Interface
A. Create the FQDN address object for www.example.com:
System:/>
add Address IPAddress my_website_fqdn Address=www.example.com
B. Drop connections to the site:
System:/>
cc RuleSet IPRuleSet mainSystem:/IPRuleSet/main>
add IPRule SourceInterface=lan SourceNetwork=lan_net DestinationInterface=any DestinationNetwork=my_website_fqdn Service=all_services Name=deny_lan_to_example Action=Deny
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.
Routers
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 10.6.0.0/16 <empty> 10.6.58.100
This shows that the main table contains a single route, which says that the network 10.6.0.0/16 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.In the above diagram, the LAN interface is connected to the network 192.168.0.0/24 and the DMZ interface is connected to the network 10.4.0.0/16. The WAN interface is connected to the network 195.66.77.0/24 and the address of the ISP gateway to the public Internet is 195.66.77.4.
The associated routing table for this would be as follows:
Route # | Interface | Destination | Gateway |
---|---|---|---|
1 | if1 | 192.168.0.0/24 | |
2 | dmz | 10.4.0.0/16 | |
3 | wan | 195.66.77.0/24 | |
4 | wan | all-nets-ip4 | 195.66.77.4 |
The above routing table provides the following information:
Route #1
All packets going to hosts on the 192.168.0.0/24 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 10.4.0.0/16 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 195.66.77.0/24 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 195.66.77.4. 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 192.168.0.4 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 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 192.168.10.1, this will be chosen if the route's Network property is 192.168.10.0/24.
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:
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 10.1.1.0/24 is bound to a physical interface that has a single IPv4 address within the network of 10.1.1.1. If we now attach a second network 10.2.2.0/24 to the interface via the switch, it is unbound since none of the interface's IP addresses belong to it.
By adding a route for this second network with the LocalIP specified as 10.2.2.1, the interface will then respond to ARP requests from the 10.2.2.0/24 network. The clients in this second network must also have their Default Gateway set to 10.2.2.1 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 10.2.2.0/24 on the interface if1 with LocalIP set as 10.2.2.1.
System:/>
cc RoutingTable main System:/RoutingTable/main> add Route Interface=if1 Network=10.2.2.0/24 LocalIP=10.2.2.1 System:/RoutingTable/main> ccSystem:/>
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.
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 0.0.0.0 0.0.0.0 192.168.0.1 192.168.0.10 20 10.0.0.0 255.0.0.0 10.4.2.143 10.4.2.143 1 10.4.2.143 255.255.255.255 127.0.0.1 127.0.0.1 50 10.255.255.255 255.255.255.255 10.4.2.143 10.4.2.143 50 85.11.194.33 255.255.255.255 192.168.0.1 192.168.0.10 20 127.0.0.0 255.0.0.0 127.0.0.1 127.0.0.1 1 192.168.0.0 255.255.255.0 192.168.0.10 192.168.0.10 20 192.168.0.10 255.255.255.255 127.0.0.1 127.0.0.1 20 192.168.0.255 255.255.255.255 192.168.0.10 192.168.0.10 20 224.0.0.0 240.0.0.0 10.4.2.143 10.4.2.143 50 224.0.0.0 240.0.0.0 192.168.0.10 192.168.0.10 20 255.255.255.255 255.255.255.255 10.4.2.143 10.4.2.143 1 255.255.255.255 255.255.255.255 192.168.0.10 192.168.0.10 1 Default Gateway: 192.168.0.1 =================================================================== Persistent Routes: None
The corresponding routing table in cOS Stream will be similar to the following:
Flags Network Iface Gateway Local IP Metric ----- ------------------ -------- -------------- --------- ------ 192.168.0.0/24 if1 20 10.0.0.0/8 wan 1 0.0.0.0/0 wan 192.168.0.1 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 192.168.0.5 to 192.168.0.17 and another route for IP addresses 192.168.0.18 to 192.168.0.254. 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 mainSystem:/RoutingTable/main>
show Route # Interface Network Gateway Local IP - --------- -------- ------------- -------- 1 wan all-nets 213.124.165.1 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
----- ------------------ ------- --------------- -------- ------
192.168.0.0/24 if1 0
213.124.165.0/24 wan 0
0.0.0.0/0 wan 213.124.165.1 0
![]() |
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. 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 192.168.0.10 and 193.55.66.77, respectively, will result in the following routes:
Route # | Interface | Destination | Gateway |
---|---|---|---|
1 | core | 192.168.0.10 | |
2 | core | 193.55.66.77 |
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 | 224.0.0.0/4 |
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.
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:
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.
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.
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 RouteMonitor=Yes MonitorGateway=Yes System:/RoutingTable/main> ccSystem:/>
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> ccSystem:/>
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.
Overview
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
MonitoringMethod=ARP/ND
IPAddress=203.0.113.8
Samples=15
MaxFailedSamples=5
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
IPAddress=203.0.113.5
ReachabilityRequired=Yes
Return to the original CLI context:
System:/RoutingTable/main> cc
System:/>
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 | 195.66.77.1 | 10 | On |
2 | wan | all-nets | 193.54.68.1 | 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 | 203.0.113.1 | 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 | 203.0.113.1 | 10 | On |
2 | dsl | all-nets | 198.51.100.1 | 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.
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.
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 192.168.0.0/24.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.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 LocalEndpoint IP address of 203.0.113.5 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
SourceInterface=if2
LocalEndpoint=203.0.113.5
RoutingTableMembership=inner_rt
OuterRoutingTable=outer_rt
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.
Overview
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:
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.
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 |
---|---|
As the destination interface is unknown until the route lookup has been done, policy-based routing cannot be based on the destination interface. |
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: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
Interface=if3
Network=my_network
Finally, change back to the default CLI context:
System:/RoutingTable/my_pbr_table>
ccSystem:/>
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
Service=http
SourceInterface=any
SourceNetwork=all-nets-ip4
DestinationNetwork=my_network
ForwardRoutingTable=my_pbr_table
ReturnRoutingTable=my_pbr_table
Name=my_routing_rule
This current contents of the routing rule set can be listed:
System:/PBRRules>
show
RoutingRule
# 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>
ccSystem:/>
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:
Source Interface |
Source Network |
Destination Network |
Forward Routing Table |
Return 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 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: 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:
Source Interface |
Source Network |
Destination Network |
Selected Service |
Forward RoutingTable |
Return 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.
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.
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:
Learn about all the connected routing devices.
Receive information from these devices about which networks they are connected to.
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).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 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: 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. |
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:
Overview
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 6.6.3.1, 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 6.6.3.1, The OSPFProcess Object.
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 6.6.3.2, 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.
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 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 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 6.6.3.5, 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.
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 192.168.1.1 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.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 192.168.1.1 and vice versa. These virtual links need to be configured in Area 1.
To set this feature up in cOS Stream, see Section 6.6.3.6, 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: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.
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.
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.
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.
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.
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.
![]() |
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. |
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.
This is used in an HA cluster and is the ID for this firewall and not the cluster.
![]() |
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.
Authentication
OSPF supports the following authentication options:
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.
![]() |
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. |
Advanced
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.
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 0.0.0.0 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.
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: 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 224.0.0.5. 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.
Authentication
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:
Advanced
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 |
---|---|
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.
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 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.
Configuration
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.Here, the three routes on Area 0 can be collapsed into one by setting up an OSPF Aggregate object for the network 192.168.0.0/24 on Area 1.
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.
Authentication
If enabled, use the authentication configured for the OSPFProcess object.
![]() |
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.
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.
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 |
---|---|
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.
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.
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 0.0.0.0 for the Area ID.
An AS can have multiple areas but in many cases only one is needed. The ID 0.0.0.0 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:
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.
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:
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.
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.
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 192.168.55.0/24 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: 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, 192.168.55.0/24.
This OSPFInterface object tells cOS Stream that any OPSF related connections to addresses within the network 192.168.55.0/24 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 192.168.55.0/24. This address must be different for A and B. Assume that 192.168.55.1 is chosen for A and 192.168.55.2 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 192.168.55.1. 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:
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 192.168.55.2 for the IPsecTunnel object on A and 192.168.55.1 for the IPsecTunnel object on B.
The IPAddress property determines the source IP address of tunnel traffic.
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.
The property AddRouteToRemoteNetwork should be set to No so the route to the RemoteNetwork is not added automatically.
![]() |
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. |
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 10.4.0.0/16 and on the other side it is the IPv4 network 192.168.0.0/24.
The goal is to configure OSPF on both firewalls so routing information is automatically exchanged and traffic can be correctly routed between the 10.4.0.0/16 network and the 192.168.0.0/24 network. The IP rules that are needed to allow such traffic to flow are not included in this example.
Example 6.10. Creating an OSPFProcess
ObjectFirst, 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 0.0.0.0. Assume that the name for the area object is area_0 and the same AreaID of 0.0.0.0.
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=0.0.0.0
This new OSPFArea object can be displayed with the command:
System:/OSPFProcess/as_0>
show
OSPFArea/
Name Area ID Comments
---- ------- --------
! area_0 0.0.0.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
Network=if1_net
System:/OSPFProcess/as_0/OSPFArea/area_0>
add OSPFInterface if3
Network=if3_net
Return to the default CLI context:
System:/OSPFProcess/as_0/OSPFArea/area_0>
ccSystem:/>
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 Name=ImportOSPFRoutes DestinationNetworkIn=all-nets-ip4 Added RouteExportRuleOSPF/1(Import).System:/OSPFProcess/as_0>
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:
System:/OSPFProcess/as/RouteExportRuleOSPF/1(Import)>
add ExportToRoutingTable
Destination=main
Added ExportToRoutingTable/1.
Return to the default CLI context:
System:/OSPFProcess/as/RouteExportRuleOSPF/1(Import)>
ccSystem:/>
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
DestinationNetworkIn=all-nets-ip4
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:
System:/RoutingTable/main/RouteExportRule/1>
add ExportToOSPF
ExportToProcess=as_0
Name=ExportRoutesToAS
Finish by returning to the default CLI context:
System:/RoutingTable/main/RouteExportRule/1>
ccSystem:/>
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.
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
Area: 0.0.0.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 10.6.60.10 172.22.60.33 865 0x80000001
2 Router-LSA 192.168.0.3 172.22.60.33 865 0x80000003
1 Router-LSA 192.168.60.1 191.168.60.1 861 0x80000002
*[0x0001d282]
Note that the area name needs to be qualified with the AS name.
For example, to display OSPF neighbors:
System:/>
ospf -neighbor
Neighbor: 192.168.0.3 (10.6.60.10)
Interface: if3
Prio: 1
Options: E
State: FULL
Expire: 25
DR: 10.6.60.10
BDR 10.6.60.141
ID Type Link ID Age Seq#
-- ----------- ------------ --- ----------
4 Network-LSA 10.6.60.10 6 0x80000001
2 Router-LSA 192.168.0.3 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.
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
----- --------------- ----------- --------------- ---------- ------
192.168.1.0/24 if1 0
172.16.0.0/16 if3 0
O 192.168.2.0/24 if3 10.6.60.10 1
Here, the route for 192.168.2.0/24 has been imported via OSPF and that network can be found on the if3 interface with the gateway of 10.6.60.10. 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:
![]() |
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
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
Overview
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 192.168.0.10.
A single BGP neighbor will be associated with the process that has the IPv4 address 10.0.0.100.
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=192.168.0.10
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
IPAddress=10.0.0.100
RemoteASNum=64513
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 10.0.1.0/24 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 10.0.1.0/24:
System:/BGPProcess/my_bgp> add RouteExportRuleBGP
DestinationNetworkIn=10.0.1.0/24
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:
System:/BGPProcess/my_bgp/RouteExportRuleBGP/1>
add ExportToRoutingTable
Destination=main
Return to the default CLI context:
System:/BGPProcess/my_bgp/RouteExportRuleBGP/1> cc
System:/>
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 10.0.2.0/24:
System:/RoutingTable/main> add RouteExportRule
DestinationNetworkIn=10.0.2.0/24
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:
System:/RoutingTable/main/RouteExportRule/1>
add ExportToBGP
ExportToProcess=my_bgp
Return to the default CLI context:
System:/RoutingTable/main/RouteExportRule/1> cc
System:/>
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 10.0.2.15.
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
Action=Allow
Network=10.0.2.15
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
Action=Allow
MatchIP=my_net
SetNextHop=10.0.0.90
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
RouteMapOut=my_map
Return to the default CLI context:
System:/RoutingTable/main/RouteExportRule/1> cc
System:/>
![]() |
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. |
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.
Overview
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 192.168.4.1
Alternatively, <host> can be a DNS resolvable
Fully Qualified Domain Name (FQDN), for example:
System:/>
traceroute server.example.com
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 server.example.com
The equivalent when sending a TCP message would be:
System:/>
traceroute -tcp server.example.com
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. Below is some typical output from traceroute using the default settings with the destination specified as an FQDN:System:/>
traceroute server.example.com
Traceroute to 10.194.40.247, 32 hops max, 32-byte packets
1 <1 ms 10 ms 10 ms 10.4.16.1
2 10 ms 10 ms 10 ms 10.4.0.2
3 10 ms 0 ms 10 ms 10.194.40.247
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 10.194.40.247.
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.
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 server.example.com -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 server.example.com -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 server.example.com -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 server.example.com -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 server.example.com -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 server.example.com -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 server.example.com -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 server.example.com -timeout=2000
Any timeout conditions are indicated in the traceroute output. An example of this is shown below:
System:/>
traceroute example.com
Traceroute to 10.194.40.247, 32 hops max, 32-byte packets
1 0 ms 0 ms 10 ms 10.4.16.1
2 10 ms 10 ms 10 ms 10.4.0.2
3 10 ms 10 ms 10 ms 10.131.48.2
4 * * * Request timed out
A timeout could occur because any of the following:
-verbose
This option provides some additional information, including the routing table used. For example:
System:/>
traceroute server.example.com -verbose
Traceroute to 10.194.40.247, 32 hops max, 32-byte packets (IPv4 ICMP)
Using route "0.0.0.0/0 via if2 , gw: 10.4.16.1" in routingtable "main":
1 <1 ms 10 ms 10 ms 10.4.16.1
2 10 ms 10 ms 10 ms 10.4.0.2
3 10 ms 0 ms 10 ms 10.194.40.247
The full list of options can be found in the separate CLI Reference Guide.
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: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 0.0.0.0/0 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.
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.
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.
Because IP rul