cOS Core 14.00.06 Administration Guide


Table of Contents

1. cOS Core Overview
1.1. Features
1.2. cOS Core Architecture
1.2.1. State-based Architecture
1.2.2. cOS Core Building Blocks
1.3. Basic Packet Flow
1.4. cOS Core State Engine Packet Flow
2. Management and Maintenance
2.1. Managing cOS Core
2.1.1. Overview
2.1.2. Configuring Network Management Access
2.1.3. Administrator Accounts
2.1.4. The Web Interface
2.1.5. CLI Access
2.1.6. Using the CLI
2.1.7. CLI Scripts
2.1.8. Using SCP
2.1.9. The Local Console Boot Menu
2.1.10. Boot Menu for the NetWall 100/300/500/6000 Series
2.1.11. RADIUS Management Authentication
2.1.12. Strong Passwords
2.1.13. Management Advanced Settings
2.1.14. Working with Configurations
2.2. System Date and Time
2.2.1. Overview
2.2.2. Setting Date and Time Manually
2.2.3. Using External Time Servers
2.2.4. Settings Summary for Date and Time
2.3. Events and Logging
2.3.1. Overview
2.3.2. cOS Core Log Messages
2.3.3. Types of Log Receiver
2.3.4. The Memory Log Receiver (Memlog)
2.3.5. The Syslog Log Receiver
2.3.6. Logsnoop
2.3.7. Mail Alerting
2.3.8. The InControl Log Receiver (FWLog)
2.3.9. Severity Filter and Message Exceptions
2.3.10. SNMP Traps
2.3.11. Advanced Log Settings
2.4. Monitoring
2.4.1. Real-time Monitoring Using InControl
2.4.2. Real-time Monitor Alerts
2.4.3. The Link Monitor
2.4.4. Hardware Monitoring
2.4.5. Memory Monitoring Settings
2.5. SNMP
2.5.1. Management with SNMP
2.5.2. Persistent SNMP Interface Indexes
2.5.3. SNMP Advanced Settings
2.6. Diagnostic Tools
2.6.1. Overview
2.6.2. The ping Command
2.6.3. The stats Command
2.6.4. The connections Command
2.6.5. The dconsole Command
2.6.6. The pcapdump Command
2.6.7. The traceroute Command
2.6.8. The frags Command
2.6.9. The selftest Command
2.6.10. The techsupport Command
2.6.11. Creating an Anonymous Configuration Copy
2.7. Maintenance
2.7.1. Software Upgrades
2.7.2. Version Update Alerts
2.7.3. Auto-Update Mechanism
2.7.4. Backing Up Configurations
2.7.5. Restore to Factory Defaults
2.7.6. Listing and Adding Ethernet Interfaces
2.8. Licenses
2.8.1. Introduction
2.8.2. License Installation on Clavister Hardware
2.8.3. License Installation on Virtual Firewalls
2.8.4. License Updating on Clavister Hardware
2.8.5. Lockdown Mode
2.8.6. Licensing Issues
2.9. Languages
2.10. Diagnostics and Improvements
3. Fundamentals
3.1. The Address Book
3.1.1. Overview
3.1.2. IP Address Objects
3.1.3. Ethernet Address Objects
3.1.4. Address Groups
3.1.5. Auto-Generated Address Objects
3.1.6. Address Folders
3.1.7. FQDN Address Objects
3.1.8. FQDN Groups
3.2. IPv6 Support
3.3. Services
3.3.1. Overview
3.3.2. Creating Custom Services
3.3.3. ICMP Services
3.3.4. Custom IP Protocol Services
3.3.5. Service Groups
3.3.6. Custom Service Lifetime Timeouts
3.3.7. Path MTU Discovery
3.4. Interfaces
3.4.1. Overview
3.4.2. Ethernet Interfaces
3.4.3. Link Aggregation
3.4.4. VLAN
3.4.5. Service VLAN
3.4.6. PPPoE
3.4.7. GRE Tunnels
3.4.8. 6in4 Tunnels
3.4.9. Loopback Interfaces
3.4.10. Interface Groups
3.4.11. Zones
3.4.12. Layer 2 Pass Through
3.5. ARP
3.5.1. Overview
3.5.2. The ARP Cache
3.5.3. ARP Publish
3.5.4. ARP Advanced Settings
3.5.5. The Neighbor Cache
3.5.6. Device Intelligence
3.6. IP Rule Sets
3.6.1. Rulesets Overview
3.6.2. Creating IP Policies
3.6.3. Using Geolocation
3.6.4. IP Rule Set Processing
3.6.5. Multiple IP Rule Sets
3.6.6. IP Rule Set Folders
3.6.7. Configuration Object Groups
3.6.8. Stateless Policy
3.6.9. Creating IP Rules
3.7. Application Control
3.8. Schedules
3.9. Certificates
3.9.1. Overview
3.9.2. Uploading and Using Certificates
3.9.3. CRL Distribution Point Lists
3.9.4. CA Server Access
3.9.5. Generating Certificates
3.10. DNS
3.11. Internet Access Setup
3.11.1. Static Address Setup
3.11.2. DHCP Setup
3.11.3. The Minimum Requirements to Allow Traffic Flow
3.11.4. Creating a Route
3.11.5. Creating IP Rule Set Entries
3.11.6. Defining DNS Servers
4. Routing
4.1. Overview
4.2. Static Routing
4.2.1. Static Routing in cOS Core
4.2.2. Configuring Static Routes
4.2.3. Route Failover
4.2.4. Host Monitoring for Route Failover
4.2.5. Advanced Routing Settings for Route Failover
4.2.6. Proxy ARP
4.2.7. Broadcast Packet Forwarding
4.3. Policy-based Routing
4.4. Route Load Balancing
4.5. Active-Active Setup
4.6. Virtual Routing
4.6.1. Overview
4.6.2. A Simple Virtual Routing Scenario
4.6.3. The Disadvantage of Routing Rules
4.6.4. IP Rule Sets with Virtual Routing
4.6.5. Multiple IP rule sets
4.6.6. Troubleshooting
4.7. OSPF
4.7.1. Dynamic Routing
4.7.2. OSPF Concepts
4.7.3. OSPF Components
4.7.4. Dynamic Routing Rules
4.7.5. Setting Up OSPF
4.7.6. An OSPF Example
4.7.7. OSPF Troubleshooting
4.8. Multicast Routing
4.8.1. Overview
4.8.2. Multicast Forwarding with Multicast Policies
4.8.3. IGMP Configuration
4.8.4. Advanced IGMP Settings
4.8.5. Tunneling Multicast using GRE
4.9. Transparent Mode
4.9.1. Overview
4.9.2. Enabling Internet Access
4.9.3. A Transparent Mode Use Case
4.9.4. Host Detection By Packet Flooding
4.9.5. Spanning Tree BPDU Support
4.9.6. MPLS Pass Through
4.9.7. Advanced Settings for Transparent Mode
5. DHCP Services
5.1. Overview
5.2. IPv4 DHCP Client
5.3. IPv4 DHCP Server
5.3.1. Static IPv4 DHCP Hosts
5.3.2. Custom IPv4 Server Options
5.4. IPv4 DHCP Relay
5.5. IP Pools
5.6. DHCPv6
5.6.1. DHCPv6 Client
5.6.2. DHCPv6 Server
6. Application Layer Security
6.1. ALGs
6.1.1. Overview
6.1.2. HTTP ALG
6.1.3. FTP ALG
6.1.4. TFTP ALG
6.1.5. SMTP ALG
6.1.6. POP3 ALG
6.1.7. IMAP ALG
6.1.8. PPTP ALG
6.1.9. SIP ALG
6.1.10. H.323 ALG
6.1.11. TLS ALG
6.1.12. DNS ALG
6.1.13. Syslog ALG
6.2. Web Content Filtering
6.2.1. Overview
6.2.2. WCF Setup Using IP Policies
6.2.3. WCF Setup Using IP Rules
6.2.4. WCF Categories
6.2.5. Customizing WCF HTML Pages
6.2.6. HTTPS Setup with WCF
6.2.7. The WCF Performance Log
6.3. Email Control
6.3.1. Email Control Profiles with IP Policies
6.3.2. DNSBL Processing
6.3.3. SMTP Anti-Spam with IP Rules
6.4. Anti-Virus Scanning
6.4.1. Overview
6.4.2. Anti-Virus Processing in cOS Core
6.4.3. Activating Anti-Virus Scanning
6.4.4. Anti-Virus with ZoneDefense
6.4.5. The Anti-Virus Cache
6.5. File Control
7. Threat Prevention
7.1. Access Rules
7.1.1. Overview
7.1.2. IP Spoofing
7.1.3. Access Rule Settings
7.2. IP Reputation
7.3. Botnet Protection
7.4. DoS Protection
7.4.1. Overview
7.4.2. Setting up DoS Protection
7.4.3. DoS Attack Examples
7.5. Scanner Protection
7.6. Intrusion Detection and Prevention
7.6.1. Overview
7.6.2. IDP Configuration Components
7.6.3. IDP Signatures and Signature Groups
7.6.4. Insertion/Evasion Attack Prevention
7.6.5. Setting Up IDP
7.6.6. Updating IDP Signatures
7.6.7. Best Practice Deployment
7.7. Threshold Rules
7.8. Blacklisting Hosts and Networks
7.9. ZoneDefense
8. Address Translation
8.1. Overview
8.2. NAT
8.3. NAT Pools
8.4. SAT
8.4.1. Introduction
8.4.2. One-to-One IP Translation
8.4.3. Many-to-Many IP Translation
8.4.4. Many-to-One IP Translation
8.4.5. SAT with Stateless IP Rule Set Entries
8.4.6. Combining SAT with NAT
8.4.7. Port Translation
8.4.8. Protocols Handled by SAT
8.4.9. SAT Setup Using IP Rules
8.5. Automatic Translation
8.5.1. NAT Only Translation
8.5.2. NAT/SAT Translation
9. User Authentication
9.1. Overview
9.2. Authentication Setup
9.2.1. Authentication Setup Summary
9.2.2. Local User Databases
9.2.3. External RADIUS Servers
9.2.4. External LDAP Servers
9.2.5. Authentication Rules
9.2.6. HTTP Authentication
9.2.7. MAC Authentication
9.3. Customizing Authentication HTML
9.4. IP Policies Requiring Authentication
9.5. Brute Force Protection
9.6. User Identity Awareness
9.6.1. Overview
9.6.2. Setting Up Identity Awareness
9.6.3. Monitoring Identity Awareness Activity
9.7. Multi-Factor Authentication
9.8. RADIUS Accounting
9.8.1. Overview
9.8.2. RADIUS Accounting Messages
9.8.3. Interim Accounting Messages
9.8.4. Configuring RADIUS Accounting
9.8.5. RADIUS Accounting Security
9.8.6. RADIUS Accounting and High Availability
9.8.7. Handling Unresponsive RADIUS Servers
9.8.8. Accounting and System Shutdowns
9.8.9. Limitations with NAT
9.8.10. Advanced RADIUS Settings
9.9. Radius Relay
10. VPN
10.1. Overview
10.1.1. VPN Usage
10.1.2. VPN Encryption
10.1.3. VPN Planning
10.2. VPN Quick Start
10.2.1. IPsec LAN-to-LAN with Pre-shared Keys
10.2.2. IPsec LAN-to-LAN with Certificates
10.2.3. IPsec Roaming Clients with Pre-shared Keys
10.2.4. IPsec Roaming Clients with Certificates
10.2.5. L2TP/IPsec Roaming Clients with Pre-Shared Keys
10.2.6. L2TP/IPsec Roaming Clients with Certificates
10.2.7. PPTP Roaming Clients
10.3. IPsec
10.3.1. IPsec Principles
10.3.2. IPsec Tunnels in cOS Core
10.3.3. IPsec Tunnel Properties
10.3.4. IPsec Proposal Lists
10.3.5. Pre-shared Keys
10.3.6. LAN-to-LAN Tunnels with Pre-shared Keys
10.3.7. IPsec Roaming Clients
10.3.8. IPsec with Certificates
10.3.9. IPsec Tunnel Selection
10.3.10. IPsec IPv6 Support
10.3.11. Config Mode
10.3.12. IKEv2 Support
10.3.13. Setup for IKEv2 Roaming Clients
10.3.14. Setup for iOS Roaming Clients
10.3.15. Using IPsec Profiles
10.3.16. MOBIKE Support
10.3.17. IPsec Tunnel Monitoring
10.3.18. Using ID Lists with Certificates
10.3.19. DiffServ with IPsec
10.3.20. NAT Traversal
10.3.21. Using Alternate LDAP Servers
10.3.22. IPsec Hardware Acceleration
10.3.23. IPsec Advanced Settings
10.3.24. IPsec Troubleshooting
10.4. PPTP/L2TP
10.4.1. PPTP Servers
10.4.2. L2TP Servers
10.4.3. L2TP/PPTP Server Advanced Settings
10.4.4. PPTP/L2TP Clients
10.4.5. The l2tp and pptp Commands
10.5. L2TP Version 3
10.5.1. L2TPv3 Server
10.5.2. L2TPv3 Client
10.6. SSL VPN
10.6.1. Overview
10.6.2. Configuring SSL VPN in cOS Core
10.6.3. SSL VPN Setup Examples
10.6.4. The Windows SSL VPN Client
10.6.5. The Apple MacOS SSL VPN Client
10.7. OneConnect VPN
10.7.1. Overview
10.7.2. Configuring OneConnect VPN in cOS Core
10.7.3. OneConnect Interface Setup Examples
10.7.4. OpenConnect Client Setup
11. Traffic Management
11.1. Traffic Shaping
11.1.1. Overview
11.1.2. Traffic Shaping in cOS Core
11.1.3. Simple Bandwidth Limiting
11.1.4. Limiting Bandwidth in Both Directions
11.1.5. Creating Differentiated Limits Using Chains
11.1.6. Precedences
11.1.7. Pipe Groups
11.1.8. Traffic Shaping with VPN and Tunnels
11.1.9. Traffic Shaping Recommendations
11.1.10. A Summary of Traffic Shaping
11.1.11. More Pipe Examples
11.2. IDP Traffic Shaping
11.2.1. Overview
11.2.2. Setting Up IDP Traffic Shaping
11.2.3. Processing Flow
11.2.4. The Importance of Specifying a Network
11.2.5. A P2P Scenario
11.2.6. Viewing Traffic Shaping Objects
11.2.7. Guaranteeing Instead of Limiting Bandwidth
11.2.8. Logging
11.3. Server Load Balancing
11.3.1. Overview
11.3.2. SLB Distribution Algorithms
11.3.3. Selecting Stickiness
11.3.4. SLB Algorithms and Stickiness
11.3.5. SLB Server Monitoring
11.3.6. Behavior After Server Failure
11.3.7. Setting Up SLB
12. High Availability
12.1. Overview
12.2. HA Mechanisms
12.3. Setting Up HA
12.3.1. Hardware Setup
12.3.2. Wizard HA Setup
12.3.3. Manual HA Setup
12.3.4. Verifying that the Cluster Functions Correctly
12.3.5. Unique Shared Mac Addresses
12.4. HA Issues
12.5. Upgrading an HA Cluster
12.6. Link Monitoring and HA
12.7. HA Advanced Settings
13. Advanced Settings
13.1. IP Level Settings
13.2. TCP Settings
13.3. ICMP Settings
13.4. State Settings
13.5. Connection Timeout Settings
13.6. Length Limit Settings
13.7. Fragmentation Settings
13.8. Local Fragment Reassembly Settings
13.9. SSL/TLS Settings
13.10. Miscellaneous Settings
A. Subscription Based Features
B. IDP Signature Groups
C. Verified MIME filetypes
D. The OSI Framework
E. Third Party Software Licenses

Chapter 1: cOS Core Overview

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

A PDF version of this document along with all current and older documentation in PDF format can be found at https://my.clavister.com.

It is also available in a framed HTML version.

1.1. Features

Clavister cOS Core is the base software system that runs on Clavister NetWall hardware products. Alternatively, cOS Core can run in a virtualized environment on a customer's choice of hardware, with a range of platforms supported. In both cases, cOS Core provides the full capabilities of a Next Generation Firewall (NGFW).

cOS Core is a Network Security Operating System

Designed as a network security operating system, cOS Core features high throughput performance with high reliability plus highly granular control. cOS Core offers seamless integration of all its subsystems, in-depth administrative control of all functionality, as well as a minimal attack surface which helps to negate the risk from security attacks.

cOS Core Objects

From the administrator's perspective the conceptual approach of cOS Core is to visualize operations through a set of logical building blocks or objects. These objects allow the configuration of cOS Core in an almost limitless number of different ways in order to meet the requirements of the most demanding network security scenarios.

Key Features

cOS Core has an extensive feature set. The list below presents the key features of the product:

IP Routing

cOS Core provides a variety of options for IP routing including static routing, dynamic routing (with OSPF), virtual routing as well as multicast routing capabilities. In addition, cOS Core supports features such as Virtual LANs, Route Monitoring, Proxy ARP and Transparency.

For more information about this, see Chapter 4, Routing.

Firewalling Policies

cOS Core provides stateful inspection-based firewalling for a wide range of protocols such as TCP, UDP and ICMP. The administrator can define detailed firewalling policies based on source/destination network/interface, protocol, ports, user credentials, time-of-day and more.

Section 3.6, IP Rule Sets describes how to set up these policies to determine what traffic is allowed or rejected by cOS Core.

Address Translation

For functionality as well as security reasons, cOS Core supports policy-based address translation. Dynamic Address Translation (NAT) as well as Static Address Translation (SAT) is supported, and resolves most types of address translation needs.

This feature is covered in Chapter 8, Address Translation.

ALGs

cOS Core provides a range of Application Level Gateways (ALGs) which provide security features that examine traffic at higher OSI layers such as checking that file download content agrees with the given filetype. Another example is the SIP ALG which examines the SIP message exchanges that take place during the setup of peer to peer data exchanges.

For detailed information, see Section 6.1, ALGs.

VPN

cOS Core supports a range of Virtual Private Network (VPN) solutions. Support exists for IPsec, L2TP, L2TPv3, PPTP, as well as SSL VPN, with security policies definable for individual VPN connections.

This topic is covered in Chapter 10, VPN.

TLS Termination

cOS Core supports TLS termination so that the Clavister firewall can act as the endpoint for connections by HTTP web-browser clients (this feature is sometimes called SSL termination).

For detailed information, see Section 6.1.11, TLS ALG.

Application Control

cOS Core is able to identify data connections relating to particular applications and perform defined actions for those data streams such as blocking or traffic shaping. An example of an application is BitTorrent peer to peer streaming but could also relate to accessing certain websites such as Facebook.

For detailed information, see Section 3.7, Application Control.

Anti-Virus Scanning

cOS Core features integrated anti-virus functionality. Traffic passing through the firewall can be subjected to in-depth scanning for viruses, and virus sending hosts can be blacklisted and blocked.

For details of this feature, see Section 6.4, Anti-Virus Scanning.

Intrusion Detection and Prevention

To mitigate application-layer attacks towards vulnerabilities in services and applications, cOS Core provides a powerful Intrusion Detection and Prevention (IDP) engine. The IDP engine is policy-based and is able to perform high-performance scanning and detection of attacks and can perform blocking and optional black-listing of attacking hosts.

More information about IDP can be found in Section 7.6, Intrusion Detection and Prevention.

Web Content Filtering

cOS Core provides various mechanisms for filtering web content that is deemed inappropriate according to a web usage policy. With Web Content Filtering (WCF) web content can be blocked based on the URL. In addition, websites can be whitelisted or blacklisted.

More information about this topic can be found in Section 6.2, Web Content Filtering.

Traffic Management

cOS Core provides broad traffic management capabilities through Traffic Shaping, Threshold Rules and Server Load Balancing.

Traffic Shaping enables limiting and balancing of bandwidth; Threshold Rules allow specification of thresholds for sending alarms and/or limiting network traffic; Server Load Balancing enables a device running cOS Core to distribute network load to multiple hosts.

These features are discussed in detail in Chapter 11, Traffic Management.

User Authentication

The Clavister NetWall Firewall can be used for authenticating users before allowing access to protected resources. Multiple local user databases are supported as well as multiple external RADIUS servers, and separate authentication policies can be defined to support separate authentication schemes for different kinds of traffic.

In addition, cOS Core supports User Identity Awareness. This means Windows based clients need only be authenticated once by a Windows Active Directory™ server and the authenticated state is then relayed to cOS Core.

See Chapter 9, User Authentication for detailed information.

Operations and Maintenance

Administrator management of cOS Core is possible through either a Web-based User Interface (the Web Interface or WebUI) or via a Command Line Interface (the CLI). Both interfaces allow management of a single Clavister firewall at a time. cOS Core also provides detailed event and logging capabilities plus support for monitoring through SNMP.

More detailed information about this topic can be found in Chapter 2, Management and Maintenance.

High Availability

High Availability (HA) is supported through automatic fault-tolerant failover to a secondary Clavister firewall. The two devices act together as a cluster, with one being active while the other is passive but constantly mirroring the state of the active unit.

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

Virtual Routers

Using two or more, separate cOS Core routing tables, it is possible to create separate virtual routers in a single Clavister firewall. Although a single version of cOS Core is being run, it is possible to create separate sets of IP rules and other policies so that different sets of traffic can be completely separated from each other within a single firewall.

See Section 4.6, Virtual Routing for more information about this topic.

IPv6 Support

IPv6 addresses are supported on interfaces, within rule sets, within VPN and in many other aspects of cOS Core.

More information about this topic can be found in Section 3.2, IPv6 Support.

ZoneDefense

cOS Core can be used to control external switches using the ZoneDefense feature. This allows cOS Core to isolate portions of a network that contain hosts that are the source of undesirable network traffic. This is discussed further in Section 7.9, ZoneDefense.

REST API

Certain functions of cOS Core can be controlled by a program running on an external computer that makes use of the cOS Core REST API. This API is discussed briefly in some of the relevant sections of this guide but is described in detail in the separate cOS Core REST API Guide.

Virtualization

In a virtual environment such as VMware, KVM or Hyper-V, it is possible to have multiple, independent Clavister firewalls running on a single computer. The supported underlying hardware architectures are x86 and also ARM for KVM.

Installation and running cOS Core in virtual environments is described in the Clavister Virtual Series Getting Started Guide publications. There is a separate Getting Started Guide for VMware, KVM and Hyper-V. The KVM guide covers both X86 and ARM platforms.

For automatic initialization during cloud deployment, cOS Core supports Cloud-Init. This is described further in the Cloud-Init Setup chapter of the Getting Started Guide for the relevant virtual environment.

Apple M1 Support

The cOS Core KVM distribution for ARM can also run under QEMU on the Apple M1 platform. M1 support is discussed further in the Clavister Knowledge Base at the link:

https://kb.clavister.com/342066805

In addition to the list above, cOS Core includes a number of other features such as RADIUS Accounting, DHCP services, protection against Denial-of-Service (DoS) attacks, support for PPPoE, GRE, dynamic DNS services and much more.

Other cOS Core Documentation

Making use of the available documentation is recommended to get the most out of the cOS Core product. In addition to this administration guide, the reader should also be aware of the following companion documentation:

  • A Getting Started Guide for each Clavister hardware model and each virtual environment. This describes how to initially set up cOS Core for each type of environment.

  • The CLI Reference Guide which details all cOS Core CLI commands and cOS Core configuration objects.

  • The cOS Core Log Reference Guide which lists and describes all log event messages that cOS Core may generate.

  • The cOS Core Application Control Signatures reference which lists all the application control signatures available in cOS Core.

  • The Data Collection Guide which describes how to submit a support ticket to Clavister.

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

Additional, related documentation consists of:

  • The Hardware Replacement Guide for swapping out Clavister hardware with the same or different unit. This guide also covers the Clavister Cold Standby (CSB) service.

  • The InControl Administration Guide which covers all aspects of using the separate InControl product for the centralized management of multiple NetWall firewalls.

[Tip] Tip: Documentation is available in HTML format

The latest version of this guide and related NetWall documentation is available in HTML format at https://docs.clavister.com. The documentation for all older cOS Core versions can be downloaded in PDF format from https://my.clavister.com.

Security Advisories

A current listing of all general security advisories that could potentially affect cOS Core can be found online at the following link:

https://www.clavister.com/advisories/security

The Clavister Knowledge Base

Clavister maintains a searchable Knowledge Base on its website which contains a range of articles covering all Clavister products, including articles about NetWall firewalls and cOS Core. These articles are designed to expand on the base reference documentation which is provided in PDF format and links to specific cOS Core topics in the knowledge base can be found throughout this publication.

The knowledge base main page can be found at the following link:

https://kb.clavister.com

The Clavister YouTube "How-To" Videos

Clavister has a YouTube™ channel which has a specific "How-To" playlist. This provides visual example of using the cOS Core Web Interface to perform various administrative tasks in cOS Core. The playlist can be found at the following link:

https://www.youtube.com/channel/UC2i10VOdZ3FkydIrIUmHDPw/playlists

cOS Core Education and Certification

Clavister offers a full range of product courses and product certifications. For details about classroom and online cOS Core education as well as cOS Core certification, visit the Clavister company website at http://www.clavister.com or contact a local sales representative.

1.2. cOS Core Architecture

This section looks at the overall architecture of the cOS Core software product and describes some of the key concepts that lie behind its design.

1.2.1. State-based Architecture

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

Stateful Inspection

cOS Core employs a technique called stateful inspection which means that it inspects and forwards traffic on a per-connection basis. cOS Core detects when a new connection is being established, and keeps a small piece of information or state in its state table for the lifetime of that connection. By doing this, cOS Core is able to understand the context of the network traffic which enables it to perform in-depth traffic scanning, apply bandwidth management and a variety of other functions.

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

1.2.2. cOS Core Building Blocks

The basic building blocks in cOS Core are interfaces, logical objects and various types of rules (or rule sets).

Interfaces

Interfaces are the doorways through which network traffic enters or leaves the firewall.

The following types of interface are supported in cOS Core:

  • Physical interfaces - These correspond to the actual physical Ethernet interfaces.

  • Sub-interfaces - These include VLAN and PPPoE interfaces.

  • Tunnel interfaces - Used for receiving and sending traffic through VPN tunnels.

Interface Symmetry

The cOS Core 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. Also important are the Application Layer Gateway (ALG) objects which are used to define additional parameters on specific protocols such as HTTP, FTP, SMTP and H.323.

cOS Core Rule Sets

Finally, rules which are defined by the administrator in the various cOS Core rule sets are the basis for implementing cOS Core security policies. The most fundamental rules are the IP Rule Set, which are used to define the layer 3 IP filtering policies as well as carrying out address translation and server load balancing. The Traffic Shaping Rule Set defines the policies for bandwidth management, the IDP Rule Set controls the behavior of the intrusion detection and prevention engine and so on.

1.3. Basic Packet Flow

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

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

  2. The packet is associated with a Source Interface. The source interface is determined as follows:

    • If the Ethernet frame contains a VLAN ID (Virtual LAN identifier), the system checks for a configured VLAN interface with a corresponding VLAN ID. If one is found, that VLAN interface becomes the source interface for the packet. If no matching interface is found, the packet is dropped and the event is logged.

    • If the Ethernet frame contains a PPP payload, the system checks for a matching PPPoE interface. If one is found, that interface becomes the source interface for the packet. If no matching interface is found, the packet is dropped and the event is logged.

    • If none the above is true, the receiving Ethernet interface becomes the source interface for the packet.

  3. The IP datagram within the packet is passed on to the cOS Core Consistency Checker. The consistency 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.

  4. cOS Core now tries to lookup an existing connection 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 connection establishment process starts which includes steps from here to 10 below. If a match is found, the forwarding process continues at step 11 below.

  5. The source interface is examined to find out if the interface is a member of a specific routing table. Routing Rules are also evaluated to determine the correct routing table for the connection.

  6. The Access Rules are evaluated to find out if the source IP address of the new connection 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 we look 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 or the reverse route lookup determine that the source IP is invalid, then the packet is dropped and the event is logged.

  7. A route lookup is being made using the appropriate routing table. The destination interface for the connection has now been determined.

  8. The IP rule set is now searched for an entry that matches the packet. The following parameters are part of the matching process:

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

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

    If a rule is found that matches the new connection, the Action parameter of the rule decides what cOS Core should do with the connection. 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 to flow. A corresponding state will be added to the connection table for matching subsequent packets belonging to the same connection. In addition, the service object which matched the IP protocol and ports might have contained a reference to an Application Layer Gateway (ALG) object. This information is recorded in the state so that cOS Core will know that application layer processing will have to be performed on the connection.

    Finally, the opening of the new connection will be logged according to the log settings of the rule.

    [Note] Note: Additional actions

    There are actually a number of additional actions available such as address translation and server load balancing. The basic concept of dropping and allowing traffic is still the same.

  9. The IDP rule set is now evaluated in a similar way to the IP rule set. If a match is found, the IDP data is recorded with the state. By doing this, cOS Core will know that IDP scanning is supposed to be conducted on all packets belonging to this connection.

  10. The Traffic Shaping and the Threshold Limit rule sets are now searched. If a match is found, the corresponding information is recorded with the state. This will enable proper traffic management on the connection.

  11. From the information in the state, cOS Core now knows what to do with the incoming packet:

    • If ALG information is present or if IDP scanning is to be performed, the payload of the packet is taken care of by the TCP Pseudo-Reassembly subsystem, which in turn makes use of the different Application Layer Gateways, layer 7 scanning engines and so on, to further analyze or transform the traffic.

    • If the contents of the packet is encapsulated (such as with IPsec, PPTP/L2TP or some other type of tunneled protocol), then the interface lists are checked for a matching interface. If one is found, the packet is decapsulated and the payload (the plaintext) is sent into cOS Core again, now with the source interface being the matched tunnel interface. In other words, the process continues at step 3 above.

    • If traffic management information is present, the packet might get queued or otherwise be subjected to actions related to traffic management.

  12. Eventually, the packet will be forwarded out on the destination interface according to the state. If the destination interface is a tunnel interface or a physical sub-interface, additional processing such as encryption or encapsulation might occur.

The next section provides a set of diagrams illustrating the flow of packets through cOS Core.

1.4. cOS Core State Engine Packet Flow

The diagrams in this section provide a summary of the flow of packets through the cOS Core state-engine. There are three diagrams, each flowing into the next. It is not necessary to understand these diagrams, however, they can be useful as a reference when configuring cOS Core in certain situations.

Packet Flow Schematic Part I

Figure 1.1. Packet Flow Schematic Part I

The packet flow is continued below in Figure 1.2, “Packet Flow Schematic Part II”.

Packet Flow Schematic Part II

Figure 1.2. Packet Flow Schematic Part II

The packet flow is continued below in Figure 1.3, “Packet Flow Schematic Part III”.

Packet Flow Schematic Part III

Figure 1.3. Packet Flow Schematic Part III

Apply Rules

The figure below presents the detailed logic of the Apply Rules function in Figure 1.2, “Packet Flow Schematic Part II” above.

Expanded Apply Rules Logic

Figure 1.4. Expanded Apply Rules Logic

The above sequence is described further in the list The Routing Table Selection Process in Section 4.3, Policy-based Routing.

Chapter 2: Management and Maintenance

2.1. Managing cOS Core

2.1.1. Overview

cOS Core is designed to give both high performance and high reliability. Not only does it provide an extensive feature set, it also enables the administrator to be in full control of almost every detail of the system. This means the product can be deployed in the most challenging environments.

A good understanding on how cOS Core configuration is performed is crucial for proper usage of the system. For this reason, this section provides an in-depth presentation of the configuration subsystem as well as a description of how to work with the various management interfaces.

Management Access Methods

The following methods are available for accessing and managing cOS Core:

  • Web Interface

    The Web Interface (also known as the Web User Interface or WebUI) is built into cOS Core and provides a user-friendly and intuitive graphical management interface, accessible from a standard web browser.

    The browser connects to one of the firewall's Ethernet interfaces using HTTP or HTTPS (by default, only HTTPS is enabled) and cOS Core responds like a web server, allowing web pages to be used as the management interface.

    The Web Interface does not provide centralized management control of multiple firewalls. One browser window can communicate with one firewall, although it is possible to have multiple browser windows open at the same time.

    This feature is described further in Section 2.1.4, The Web Interface.

  • The CLI

    The Command Line Interface (CLI), accessible via the local console port or remotely using the Secure Shell (SSH) protocol, provides the most fine-grained control over all parameters in cOS Core.

    This feature is described further in Section 2.1.5, CLI Access and Section 2.1.6, Using the CLI.

  • Secure Copy

    Secure Copy (SCP) is a widely used communication protocol for file transfer. No specific SCP client is provided with cOS Core distributions but there exists a wide selection of SCP clients available for nearly all platforms.

    SCP is a complement to CLI usage and provides a secure means of file transfer between the administrator's management computer and the firewall. Various files used by cOS Core can be both uploaded and downloaded with SCP.

    This feature is described further in Section 2.1.8, Using SCP.

  • The Console Boot Menu

    Before cOS Core starts running, a console connected directly to the Clavister firewall's local console port can be used to do basic configuration through the boot menu. This menu can be entered by pressing any console key between power-up and cOS Core starting. It is the cOS Core firmware loader that is being accessed with the boot menu.

    This menu is described further in Section 2.1.9, The Local Console Boot Menu.

  • Clavister InControl

    InControl is a separate Clavister software product for the centralized administration of multiple Clavister firewalls.

    InControl provides an intuitive graphical client which runs on a standard Windows based PC. One or multiple clients communicate with an InControl server running on the same or a different Windows based computer. The server acts as a repository for all cOS Core configuration data and mediates all management commands sent by clients. With InControl, it is possible to create global configuration objects which are shared between firewalls so that the object needs to be changed only once on the InControl server and that change is automatically deployed to all affected firewalls.

    More information about InControl can be found in the separate InControl Administration Guide.

  • Clavister InCenter

    InCenter is a separate Clavister software product. InCenter provides an intuitive graphical client which is accessed through a standard web browser for managing and analyzing multiple firewalls via a server. The InCenter server can be running on on-premises hardware or it can be accessed as a cloud service provided by Clavister.

    More information about InCenter can be found in the separate InCenter Administration Guide.

All management access requires that a Remote Management object exists to allow that access. The predefined Remote Management objects and how to create new ones are described in the next section.

2.1.2. Configuring Network Management Access

Management access to cOS Core by an administrator depends on two factors:

  • The IP address assigned to the default management Ethernet interface. This IP address can be changed as long as the new IP still belongs to the network that is allowed by the relevant Remote Management object.

  • What kind of access the configuration's set of Remote Management objects allow. These objects determine the interface on which management access is permitted, what type of access is allowed via that interface, and which source IP addresses the access can originate from.

The Default Interface and IP for Management Access

The default management interface chosen by cOS Core can be different depending on the hardware platform but is usually the first one found by cOS Core when the available interfaces are first scanned on initial startup. For virtual environments, it is always cOS Core's logical If1 interface.

cOS Core assigns the default IPv4 address 192.168.1.1 to this management interface and HTTPS or SSH access is allowed from the 192.168.1.0/24 network.

Remote Management Objects

Remote access over a network to cOS Core is controlled by a set of Remote Management objects and these objects can be any of the following types:

  • HTTP/HTTPS Management

    A predefined object of this type called rmgmt_http already exists in the default cOS Core configuration for IPv4 access. A new Remote Management object must be created to allow HTTP/HTTPS management access using an IPv6 address and this is further described later in this section.

  • SSH Management

    This object type controls access via an SSH client. A predefined object of this type called rmgmt_ssh already exists in the default cOS Core configuration.

  • SNMP Management

    This object type controls access via an SNMP client. No object of this type exists in the default cOS Core configuration so one must be created to allow this kind of access.

    SNMP access is discussed further in Section 2.5, SNMP.

  • InCenter Management

    This object type controls management access from an InCenter server. No object of this type exists in the default cOS Core configuration so one must be created to allow this kind of access.

    Setting up this object is explained in the separate InCenter Administration Guide.

  • InControl Management (Netcon)

    This object type controls management access from an InControl server. No object of this type exists in the default cOS Core configuration so one must be created to allow this kind of access.

    Setting up this object is explained in the Preparing cOS Core chapter of the separate cOS Core InControl Administration Guide.

  • REST API

    This object type controls access from an external computer that uses a REST API to communicate with cOS Core so that changes to the cOS Core configuration can be made under the control of external software. No object of this type exists in the default cOS Core configuration so one must be created to allow this kind of access.

    The REST API feature is described further in the separate document entitled Clavister cOS Core REST API.

Predefined Remote Management Objects

The following Remote Management objects are already predefined in cOS Core:

  • rmgmt_http

    This is a RemoteMgmtHTTP object which controls HTTP and HTTPS access via the Web Interface. By default, only HTTPS is allowed from the 192.168.1.0/24 network on the default management interface. When upgrading cOS Core with a configuration that already has HTTP access enabled, this access remains unchanged.

  • rmgmt_ssh

    This is a RemoteMgmtSSH object that controls SSH access via the CLI. This is enabled by default and allows SSH access from the 192.168.1.0/24 network on the default management interface.

  • NetconMgmt

    This is an object that controls Netcon communication with an InControl server. Only a single object of this type can exist and it always has this name. The object will only be present as a predefined object on a Clavister hardware device that supports the InControl zero touch feature for automatic addition of devices to InControl control. This object should only be deleted if zero touch will not be used. The zero touch feature is fully described in the separate InControl Administration Guide.

For other types of access, such as SNMP access, additional Remote Management objects must be created.

Configuring IPv6 Management Access

It is possible for administrator access via HTTP/HTTPS to be configured using IPv6. To do this the following steps are needed:

  1. Create a new Remote Management object that has an IPv6 address object set for its Network filter.

  2. Enable IPv6 for the interface specified in the Remote Management object and assign an IPv6 address to that interface.

Preventing Loss of Management Access

When the IP address of the management interface or a remote management rule is changed, there is a risk that the change can prevent further management access. cOS Core prevents this in the following ways:

  • Changes made through the Web Interface

    For configuration changes to the Web Interface, there is a delay after performing a Save and Activate operation (the default is 30 seconds) followed by an automatic check that the web browser and cOS Core can still communicate. If communication is lost after the delay, the original configuration is restored.

    If the administrator expects that configuration changes will break the communication between cOS Core and the web browser (for example, by changing the management IP), they should select Save and Activate then login again before the timeout period expires. This login tells cOS Core that the administrator still has access and the configuration will not revert back to the old version.

  • Changes made through the CLI over SSH

    When using the CLI via an SSH connection, the administrator must first issue the command:

    Device:/> activate

    This activates the new configuration but the changes are not made permanent until the following command is issued:

    Device:/> commit

    If the commit command is not issued within a fixed period of time (the default is 30 seconds) after the activate, cOS Core assumes communication has been lost and the original configuration is restored.

    If a configuration change breaks SSH communication, the administrator must login in again over SSH in order to issue the commit command and make the changes persistent.

  • Changes made via the Local Console CLI

    Unlike when using SSH, communication with the local serial console cannot be lost if changing a management interface IP address and/or a remote management rule. This means that a commit command can always be issued after an activate command to make changes persistent. However, the administrator must then check manually if access via the management interface is still possible after entering commit.

If the default 30 second delay is too short, the delay can be changed in the configuration's advanced settings. The setting to change has the name Validation Timeout in the Web Interface and NetconBiDirTimeout in the CLI. It is a global setting.

Example 2.1. Changing the Management Validation Timeout

This example will change the validation timeout from its default value of 30 seconds to 60 seconds.

Command-Line Interface

Device:/> set Settings RemoteMgmtSettings NetconBiDirTimeout=60

Web Interface

  1. Go to: System > Device > Remote Management > Advanced Settings
  2. Set the following:
    • Validation Timeout: 60
  3. Click OK

An Alternative Method of Changing the Management Interface

An alternative method of changing the management interface, which avoids the 30 second delay entirely, is as follows:
  1. Login using the existing remote management interface, add a new Remote Management object, then activate and commit the change.

  2. Disconnect and then reconnect using the interface specified by the new Remote Management object.

  3. Delete the old Remote Management object and then activate and commit the change.

Changing the Management IP Address

The following example shows how the IPv4 address for access on the default management interface can be changed. The new address must belong to the network allowed by the relevant Remote Management object for that interface. If it does not, the object must be changed to allow the IP.

There are two ways of changing the management interface:

  • Change the IP address of the interface directly. For example, the CLI for this would be:

    Device:/> set Interface Ethernet <interface> IP=<ip_address>

    This is not recommended since the address object in the address book for this IP address would not change and nor would any of the other rules and object that refer to it.

  • Change the IP address of the address object for the interface IP. This is the recommended method of setting a new management IP address.

Example 2.2. Changing the Management Interface IP Address

This example will change the IPv4 address on the management If1 interface from 192.168.1.1 to 192.168.1.2. Since these belong to the same network, the network or the management policies do not need to be changed.

Command-Line Interface

Device:/> set Address IP4Address InterfaceAddresses/If1_ip
			Address=192.168.1.2

Web Interface

  1. Go to: Objects > Address Book
  2. Select the address folder InterfaceAddresses
  3. Select the address object If1
  4. Set the following:
    • IP address: 192.168.1.2
  5. Click OK

Changing a Remote Management Object

If the network as well as the IP address changes for a management interface, and/or a different interface is used, then the relevant management access rule will also need to be changed as shown in the example below.

Example 2.3. Changing a Remote Management Object

This example will change the current HTTP/HTTPS management access to allow access on the If2 interface and from the network defined by the address book object management_net which is already defined. Connection with both HTTP and HTTPS connection will be allowed.

Command-Line Interface

Device:/> set RemoteManagement RemoteMgmtHTTP rmgmt_http
			HTTP=Yes
			HTTPS=Yes
			Network=management_net
			Interface=If2

Web Interface

  1. Go to: System > Device > Remote Management > rmgmt_http
  2. Set the following:
    • Enable HTTP
    • Enable HTTPS
    • Interface: If2
    • Network: management_net
  3. Click OK

HA Cluster Management IPs Must Be Different

In an HA cluster, the management IPs should always be different on the master and slave units for their management interfaces. The shared IP address cannot be used for cOS Core management.

The individual IPv4 addresses for the management interface of the cluster master and slave units are held in the IP4 HA Address object for that interface and this is duplicated on both master and slave units. If the management interface IP in this address object is changed on one unit it will be automatically copied over to the other unit by the synchronization process.

Example 2.4. Changing the HA Management IP Address

This example will change the slave management IP address for the lan interface to 192.168.1.2 for an HA cluster.

Command-Line Interface

Device:/> set Address IP4HAAddress lan_ha_ip Address:2=192.168.1.2

Web Interface

  1. Go to: Objects > Address Book
  2. Select the address book object. In this case, lan_ha_ip
  3. Set the following:
    • Slave IP Address: 192.168.1.2
  4. Click OK

When it is activated and committed, this change will be synchronized over to the other unit in the cluster.

Adding Remote Management Objects

Extra management access objects can be added to a configuration. For example, to allow only HTTPS access on the If2 interface using the Web Interface, an additional RemoteMgmtHTTP could be added as shown in the next example.

Example 2.5. Adding Remote Management via HTTPS

This example assumes that a new RemoteMgmtHTTP object is to be added called https_access. This will allow HTTPS access on the If2 interface from any network and use the local database AdminUsers to authenticate the administrator's login credentials.

Command-Line Interface

Device:/> add RemoteManagement RemoteMgmtHTTP https_access
			Network=all-nets
			Interface=If2
			LocalUserDatabase=AdminUsers
			HTTPS=Yes

Web Interface

  1. Go to: System > Device > Remote Management > Add > HTTP/HTTPS Management
  2. Enter a Name for the HTTP/HTTPS remote management rule, in this case https_access
  3. Enable the HTTPS option
  4. Select the following:
    • User Database: AdminUsers
    • Interface: If2
    • Network: all-nets
  5. Click OK

Management Access Failure from an all-nets Route

If any VPN tunnel is set up and management access no longer works as expected, it is possible that there is a problem caused by an all-nets route being added to the main routing table so management traffic gets routed into the tunnel.

To solve this problem, the administrator will need to create a specific route that routes management interface traffic leaving the firewall back to the management sub-network.

2.1.3. Administrator Accounts

In the default configuration, cOS Core has a predefined local user database called AdminUsers. This contains two predefined user accounts:

  • Username admin with password admin.

    This account has full administrative read/write privileges.

  • Username audit with password audit.

    This account is for monitoring purposes only and has read-only privileges.

[Important] Important

For security reasons, it is recommended to change the default passwords of the default accounts as soon as possible after connecting with the Clavister firewall.

Creating Additional Accounts

Extra user accounts can be created as required. Accounts can either belong to the Administrator user group, in which case they have complete read/write administrative access. Alternatively, they can belong to the Auditor user group, in which case they have read-only access.

Only One Administrator Account Can Be Logged In

cOS Core does not allow more than one administrator account to be logged in at the same time. If one administrator logs in, then a second or more (using different credentials) will be allowed to login but they will only have audit privileges. In other words, the second or more administrators who login will only be able to read configurations and will not be able to change them.

However, cOS Core does allow the same administrator account (in other words, using the same administrator credentials) to be logged in more than once at the same time. This means it is possible, for example, to have a CLI session in progress as an administrator at the same time as also performing administrator management operations through the Web Interface.

2.1.4. The Web Interface

cOS Core provides an intuitive Web Interface (WebUI) for management via an Ethernet interface using a standard modern web browser. This allows the administrator to perform remote management from anywhere on a private network or over the Internet using a standard computer without having to install proprietary client software.

The Default Management Interface in Virtual Environments

For a new virtual cOS Core installation with factory defaults, the default management interface is always If1 and this always has a DHCP client enabled for automatic IP address assignment.

The Default Management Interface for Clavister Hardware Products

For all Clavister product models with factory defaults, the default interface is indicated in the list below, The IPv4 address of 192.168.1.1 is assigned unless a DHCP client is enabled on the interface in the default configuration.

Clavister Product Default Management Interface
NetWall 100 Series Physical LAN1.
NetWall 300/500/6000 Series
NetWall E80/W20/W20B/W30/W50
NetWall X8
Physical G1.
NetWall RSG-400 Logical X1 via any physical interface.
NetWall E10/E80B Physical LAN.
NetWall E5/E7 Physical gesw.
NetWall W3/W5/W40 Physical M1.
All virtual environments Logical If1.

More details on management access and how to change the management interface and/or IP address from the default is described in Section 2.1.2, Configuring Network Management Access.

Setting the Management Computer IP Address

The default management Ethernet interface of the firewall and the external management computer's Ethernet interface must be members of the same logical IP network for communication between them to succeed. Therefore, the connecting Ethernet interface of the management computer should be assigned the following static IP values:

  • IP address: 192.168.1.30
  • Subnet mask: 255.255.255.0
  • Default gateway: 192.168.1.1

The diagram below illustrates management computer connection via a switch.

Management Computer Connection

Figure 2.1. Management Computer Connection

For some Clavister hardware products, an IPv4 DHCP server is already enabled in cOS Core on the management interface. This means it is necessary only to enable an IPv4 DHCP client on the management computer's Ethernet interface for the computer to get the required IP addresses automatically after connection. Manual configuration is not required. This feature is described in the relevant Getting Started Guide for the hardware product. A DHCP server is never enabled for cOS Core in virtual environments.

For a description of how to set a static IP address on a Windows or MacOS computer, see the relevant appendix in the separate Clavister Getting Started Guide for the platform being used.

Logging on to the Web Interface

To access the Web Interface using the factory default settings, launch a web browser on the external management computer and point the browser to the IPv4 address 192.168.1.1.

Initial Browser Web Interface Access

Figure 2.2. Initial Browser Web Interface Access

Note that the protocol must be https:// when accessing cOS Core for the first time (HTTP access can be enabled later if required). With HTTPS, cOS Core will send back its own self-signed certificate for the encryption and the browser will ask the administrator to confirm that a security exception should be made.

When communication with the cOS Core is successfully established, a user authentication dialog like the one shown below will then be shown in the browser window.

Web Interface Login Dialog

Figure 2.3. Web Interface Login Dialog

After entering a valid username and password the Login button is clicked. If the user credentials are valid, the administrator is taken to the main Web Interface page.

[Note] Note: Password caching is prevented

The Web Interface prevents the caching of the password from the login credentials. This is also done in other cOS Core features where a password is requested through a browser screen. For example, with VPN authentication.

First Time Web Interface Login and the Setup Wizard

When logging on for the first time, the default username is always admin and the password is admin .

After successful login, the cOS Core Web Interface will be presented in the browser window. If no configuration changes have yet been uploaded to the firewall, the cOS Core Setup Wizard will start automatically to take a new user through the essential steps for cOS Core setup and establishing Internet access.

[Important] Important: Switch off popup blocking

Popup blocking must be disabled in the web browser to allow the cOS Core Setup Wizard to run since this appears in a popup window.

The wizard can be terminated and setup up done as a series of separate steps through the Web Interface if desired or alternatively through the CLI. Initial setup and the wizard are described in detail in the relevant Getting Started Guide.

Multi-language Support

The Web Interface login dialog offers the option to select a language other than English for the interface. Language support is provided by a set of separate resource files.

It may occasionally be the case that an upgrade of cOS Core can contain features that temporarily lack a complete non-English translation because of time constraints. In this case the original English will be used as a temporary solution in place of a translation to the selected language.

The Web Browser Interface

The Web Interface is a allows navigation to the various cOS Core subsystems and their related configuration objects. Current cOS Core operational information is shown by default.

[Note] Note: Security policies control remote management access

Access to the Web Interface is regulated by the configured remote management policy. By default, the system will only allow web access from the internal network. For more information about this topic, see Section 2.1.2, Configuring Network Management Access.

Interface Layout

The main Web Interface page is divided into the following major sections:

  • Menu bar

    The menu bar located at the top of the Web Interface contains a series of buttons for accessing different aspects of the configuration.

  • Object Navigator

    The navigator located on the left-hand side of the Web Interface is divided into a number of sections related to the chosen menu bar item.

  • Main Window

    The main window contains configuration or status details corresponding to the section selected in the menu bar or object navigator.

    When displaying tables of information in the main window, right clicking a line (for example, an IP policy) will bring up a context menu.

    This context menu can be used to add a new object, delete the current, change the ordering and other operations. The Clone function is used to make a complete copy of the current object and then add it as the last object in the table. Below is a typical example of the context menu.

[Tip] Tip: Hover over textual items for additional information

Many of the textual items in the Web Interface have the ability to present additional information about the item if the screen cursor is held over them. For example, the screenshot below shows the information displayed when the cursor hovers over the Primary Retry Interval field text in the RADIUS settings.

The Web Interface Quick Search Feature

The web interface provides a Quick Search feature for searching the configuration based on configuration paths. The feature is opened wih by clicking the magnifying glass icon in the top right of the Web Interface or using the shortcut Ctrl-P. At first, a drop-down menu of the entire configuration is displayed, as shown below.

Initial Display of the Web Interface Quick Search Feature

Figure 2.4. Initial Display of the Web Interface Quick Search Feature

As text is entered, the complete configuration list is reduced to objects that have paths containing the entered text. Note that the text entered uses spaces as a wildcard. For example, entering "network-ipsec" will display only objects with paths that contain the text "network-ipsec". Entering "network ipsec" will display objects with paths that contain both "network" and then later "ipsec". This is shown in the example below.

Web Interface Quick Search Filtering

Figure 2.5. Web Interface Quick Search Filtering

Quick search becomes hidden when it loses focus.

Activating Configuration Changes

As configuration changes are made through the Web Interface, they are not applied to the current running configuration until the administrator asks for them to be activated. Activation is done by choosing the Web Interface menu option Configuration > Save and Activate.

cOS Core will then perform a reconfigure operation which might cause only a slight, brief delay to current data traffic. To prevent a change locking out the administrator, cOS Core will revert to the old configuration if communication is lost with the web browser after a fixed time delay (30 seconds by default). This delay is discussed further in Section 2.1.2, Configuring Network Management Access.

[Note] Note: Examples in this guide assume activation will be performed

Most of the examples in this guide deal with editing cOS Core configurations. The final activation step is usually not explicitly stated.

Using CA Signed Certificates

By default, when the Web Interface is accessed with HTTPS, a self-signed certificate is sent to the browser which must be explicitly accepted by the user. However, it is possible to use a CA signed certificate and this can be done with certificate chaining. The next example demonstrates this.

Example 2.6. Remote Management via HTTPS with CA Signed Certificates

Command-Line Interface

Device:/> set Settings RemoteMgmtSettings 
			HTTPSCertificate=HostA
			HTTPSRootCertificates=RootA2,RootA1,RootA3

Web Interface

  1. Go to: System > Device > Remote Management > Advanced Settings
  2. Under WebUI enter the HTTPS Certificate and the Remote Management certificates.
  3. Click OK

These same CA signed certificates are also used by the cOS Core SSL VPN feature when a user is connecting for the first time and a dialog of options is displayed.

[Caution] Caution: Do not expose the management interface

The above examples are provided for illustrative purposes only. It is never advisable to expose any management interface to access from the Internet.

Restarting cOS Core with the Web Interface

The Web Interface can be used to restart cOS Core by selecting the option Status > Maintenance > Reset & Restore. The following restart options are available:
  • Reconfigure

    This does not restart the entire system but only reloads the configuration. This is equivalent to the reconf CLI command. In most cases, all connections including VPN tunnels are unaffected.

    Apart from reloading the configuration, many of cOS Core's internal data structures related to rules and traffic processing are reinitialized and this can sometimes be a way to solve problems related to memory management.

  • Restart

    This restarts the entire system and is equivalent to the shutdown CLI command. Only cOS Core restarts and not the cOS Core loader. This is the usual method of performing a restart.

  • Reboot

    This restarts the entire system and is equivalent to the shutdown -reboot CLI command. It is similar to the previous Restart option with a graceful shutdown but is also equivalent to switching system power off and on so that the cOS Core boot program is also reloaded. This option is not normally used in standard operation and also requires longer for the restart.

Logging out from the Web Interface

After finishing working with the Web Interface, it is advisable to always logout to prevent other users with access to the workstation getting unauthorized access to cOS Core. Logout is achieved by clicking on the Logout button at the right of the menu bar.

Management Traffic Routing with VPN Tunnels

If there is a problem with the management interface when communicating alongside VPN tunnels, check the main routing table and look for an all-nets route to the VPN tunnel. Management traffic may be using this route.

If no specific route is set up for the management interface then all management traffic coming from cOS Core will automatically be routed into the VPN tunnel. If this is the case then a route should be added by the administrator to route management traffic destined for the management network to the correct interface.

Changing the Device Name

Every Clavister firewall has a Device Name associated with it which is stored on the cOS Core configuration. This name appears in the title bar of the Web Interface and also appears in the CLI prompt as well as being displayed in large letters at the top of the Status page of the Web Interface.

By default, this name is always System but this can be changed to another identifier by going to System > Device > Name in the Web Interface. A comment can also be entered along with a device name.

Changing the device name from the default can be very useful when an administrator is managing multiple firewalls and needs a reminder of which device they are working with.

2.1.5. CLI Access

This section describes the methods for accessing the cOS Core Command Line Interface (CLI) and these are:

  • Direct access using the local console.

  • Network access via an Ethernet interface using SSH.

The authentication aspects of these methods will also be discussed. How the CLI is used is described later in Section 2.1.6, Using the CLI.

Local Console CLI Access

The local console port is a connection port on the firewall that allows management access to the cOS Core CLI through a direct connection to a management computer. The complete procedure for setting up this connection is described in detail in the relevant Clavister Getting Started Guide for the computing platform used.

Note that in a virtual environment, a physical connection is not needed since the local console corresponds to the console of the hypervisor.

In summary, the physical local console setup prerequisites required for Clavister NetWall hardware are the following:

  • An external management computer or device with the ability to emulate a terminal console. Appropriate communications software may need to be installed for console emulation and this is available from a number of third parties.

  • A cable with appropriate connectors to connect the external computer with the console port on the Clavister firewall with the computer.

To physically connect a terminal to the console port, follow these steps:

  1. Set the console communication protocol appropriately on the external computer if required.

  2. Connect one of end of the connector cable directly to the local console port on the firewall.

  3. Connect the other end of the cable to the external computer running the console.

  4. Press the enter key on the terminal console. The cOS Core prompt should appear on the console to indicate successful communication.

  5. Enter login credentials if this is required.

Local Console Login Credentials for Virtual Environments

For virtual environments (and also older Clavister x86 based hardware products), there are no login credentials set for local console access in the default configuration. However, a local console password can be set (there is no username) using the boot menu. This is described further in Section 2.1.9, The Local Console Boot Menu. This password will only be applicable to local console access and has no other usage.

Local Console Login Credentials for ARM Based Hardware

For the Clavister NetWall 100, 300, 500 and 6000 series hardware products, there are default local console login credentials set which come from the predefined admin user in the local user database. This user initially has the username admin and password admin. Local console access is controlled by a predefined cOS Core configuration object called Local Management. If required, local console login credentials can be disabled in the Local Management object. Alternatively, a different user could be set as the source for console login credentials.

Changing the Local Console Port Line Speed

If required, the console line speed can be changed either through the Web Interface or through the CLI. Note that changing the speed is only relevant where the local console port has a serial (RS-232) connection.

Example 2.7. Setting the Console Line Speed

In this example the console line speed is set to 19200 bps.

Command-Line Interface

Device:/> set COMPortDevice COM1 BitsPerSecond=19200

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

Go to: System > Advanced Settings > Com Port Devices

Click the console port line, configure the speed and then click OK

[Note] Note: Restart cOS Core after changing the console speed

After changing the local console port speed, the new setting will only come into effect after restarting cOS Core which can be done with the command:

Device:/> shutdown

A shutdown always restarts cOS Core.

SSH (Secure Shell) CLI Access

The SSH (Secure Shell) protocol can be used to access the CLI over the network from a remote host. SSH is a protocol primarily used for secure communication over insecure networks, providing strong authentication and data integrity. cOS Core supports version 2 of the SSH protocol SSH clients are freely available for almost all computing platforms.

SSH access is controlled by SSH Management objects in cOS Core. Management SSH access is enabled by default with a predefined object called mgmt_ssh already existing in the default cOS Core configuration. This object allows SSH access on the default management interface with authentication being performed using the predefined local user database called AdminUsers.

Disabling SSH access can be done by deleting the relevant SSH Management object.

Example 2.8. Adding a New SSH Remote Management Object

This example shows how to add a new remote management object for SSH access from the lan_net network via the lan interface.

Command-Line Interface

Device:/> add RemoteManagement RemoteMgmtSSH my_ssh_access
			Network=lan_net
			Interface=lan
			LocalUserDatabase=AdminUsers

Web Interface

  1. Go to: System > Device > Remote Management > Add > SSH Management
  2. Now enter:
    • Name: my_ssh_access
    • User Database: AdminUsers
    • Interface: lan
    • Network: lan_net
  3. Click OK

SSH Algorithm Selection

An SSH Management object has a property in the Web Interface called Algorithms which determines which set of algorithms from the cOS Core key ring objects are selected for use with SSH. The possible values for this property are the following:

  • Recommended

    This is the default value and uses an optimal selection of algorithms from the key ring to ensure security.

  • Legacy

    This option is not recommended and includes older insecure algorithms. It exists for backwards compatibility only.

  • Custom

    This option allows the administrator to create a custom selection of algorithms from the available choices in the key ring.

The algorithms included for the Recommended and Legacy settings are not listed here, but are displayed in the Web Interface page for the SSH Management object when each setting is selected. In addition, the RemoteMgmtSSH entry in the separate CLI Reference Guide lists the Recommended algorithms as the default property values.

SSH Access Using IPv6

The example above assumes that access from an SSH client will be done using the IPv4 address for an Ethernet interface on the firewall. However, access is also possible using an IPv6 address. The steps required in the cOS Core configuration for this are the following:

  • IPv6 must be enabled on the Ethernet interface to be used for management connection and an IPv6 address must also be assigned to it. Doing this is described further in Section 3.2, IPv6 Support.

  • An SSH Management rule must be added (as in the previous example) which has its Network property set to the IPv6 network (or host) from which the connection will come.

Automatic Public SSH Key Authentication

By default, SSH access requires a username and password to be entered. An alternative is to authenticate automatically by using SSH keys. This method of authentication is useful when using scripts. It is sometimes referred to as public key authentication.

Authentication in this way requires that the public key file of a public/private key pair is uploaded to cOS Core and associated with the relevant User object. Both the public and private key files are installed in the connecting SSH client.

SSH key authentication is enabled with the following steps:

  1. Create a suitable set of key files using a third party tool (for example, the PuTTY tool). Key generation can also be done directly within some SSH clients. The key files will consist of a private key file and a public key file. By convention, these are often called id_rsa (the private key) and id_rsa.pub (the public key).

  2. Install the key files into the SSH client. This may already have been done if the client was used to generate the keys.

  3. Add the public key to cOS Core. This can be done in one of the following ways:

    • Using the Web Interface

      Uploading of the public key file can be performed by going to Object > Key Ring in the Web Interface and selecting Add > SSH Public Key. Next, enter a suitable name and then select Upload SSH public key file to upload the file.

    • Using SCP

      When uploaded from an external computer using SCP, the public key file must be stored in the cOS Core folder called sshpublickeys (SCP and this folder are described further in Section 2.1.8, Using SCP). The following is a typical SCP command to do this:

      > scp id_rsa.pub admin@203.0.113.5:sshpublickeys/my_public_ssh_key

      Note that the public key file will usually have an original filetype of .pub but the filename on cOS Core cannot have a period (".") in the name. If the local filename of the certificate's public key file is id_rsa.pub, this must become something without the period in cOS Core storage. For example, it could get the new name my_public_ssh_key, which is used in the example command above.

    • Using the CLI

      The public key could be added using the cOS Core CLI. The following is an example of a typical command:

      Device:/> add SSHPublicKey my-pub-key PublicKey=”ssh-rsa DAB3NzaC1y2”

      Here, the key must be specified as a string and not a file. The key string in the above command has been shortened. It would typically be much longer.

    Adding public keys to cOS Core is also required for centralized management by the InCenter software tool and this is discussed further in the separate InCenter Administration Guide.

  4. In cOS Core, set the SSH Keys property of the relevant User object to be the uploaded public key file. For example, the user admin could be assigned the key file my_public_ssh_key. This step is described in detail in the example below.

  5. Connect to cOS Core using SSH with key authentication. Authentication will now occur automatically and there will be no prompt for credentials to be entered.

Example 2.9. Enabling SSH Authentication Using SSH Keys

This example shows how to enable automatic SSH authentication for the user admin. It is assumed that an SSH public key file called my_public_ssh_key has already been uploaded to cOS Core's sshpublickeys folder using SCP.

Note that after enabling SSH authentication, the configuration changes must be activated and saved like any other changes.

Command-Line Interface

Change the CLI context to be the user database containing the user:

Device:/> cc LocalUserDatabase AdminUsers

Set the SSHKeys property of the relevant user to be the uploaded SSH key file:

Device:/AdminUsers> set User admin SSHKeys=my_public_ssh_key

Change the CLI context back to the default:

Device:/AdminUsers> cc
Device:/> 

Web Interface

  1. Go to: System > Device > Local User Databases
  2. Select the database AdminUsers
  3. Select Users
  4. Select the user admin
  5. Select SSH Public Key
  6. Add the my_public_ssh_key to the Selected list
  7. Click OK

Logging In to the CLI

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

When accessing the CLI remotely through SSH, cOS Core will respond with a login prompt. Enter the username and press the Enter key, followed by the password and then Enter again. After the first startup, cOS Core will allow administrator login with the username admin and the password admin. This default password should be changed as soon as possible.

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

Device:/> 

If a welcome message has been set then it will be displayed directly after the login. For security reasons, it is advisable to either disable or anonymize the CLI welcome message.

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 to, for example, my-password the following CLI commands are used. First we must change the current category to be the LocalUserDatabase called AdminUsers (which exists by default):

Device:/> cc LocalUserDatabase AdminUsers

We are now in AdminUsers and can change the password of the admin user:

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

Finally, return the current category to the top level:

Device:/AdminUsers> cc

The Console Password Is Sometimes A Separate Password

Note, for virtual environments and older Clavister hardware; products, the password that can be set to protect direct local console access is a separate password and should not be confused with the passwords related to user accounts. This console password is further described in Section 2.1.9, The Local Console Boot Menu.

For the Clavister NetWall 100, 300, 500 and 6000 hardware products, the console username and password is the same as the admin user in the default local database. By default, this will be admin and admin. Local console access is controlled by a predefined object called Local Management. The console password can be disabled if desired by changing the Local Management object.

2.1.6. Using the CLI

cOS Core provides a Command Line Interface (CLI) for administrators who prefer or require a command line approach to administration, or who need more granular control of system configuration. The CLI is available either directly via the local console or remotely via an Ethernet interface using the Secure Shell (SSH) protocol from an SSH client. CLI access is discussed in the preceding Section 2.1.5, CLI Access.

The CLI provides a comprehensive set of commands that allow the display and modification of configuration data as well as allowing runtime data to be displayed and system maintenance tasks to be performed.

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.

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

The essential CLI commands for adding and manipulating configuration objects are the following:

  • add - Adds an object such as an IP address or a rule to the configuration.

  • set - Sets some property of an object to a value. For example, this might be used to set the source interface on an IP policy.

  • show - Displays the current categories or displays the values of a particular object.

  • delete - Deletes a specific object.

CLI Command Structure

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

The Object Category Can Be Omitted

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:
Device:/> show IP4Address my_address
However, tab completion will always assume the category is included. For example, tab completion would not be able to help complete the above command if the tab is pressed during or after the IPAddress object type.

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

[Note] Note: The terms Category and Context

When describing the CLI, the terms object category and object context are used interchangeably.

A command like add can also include object properties. To add a new IP4Address object with an IP address of 10.49.02.01, the command would be:

Device:/> add Address IP4Address my_address Address=10.49.02.01

The object type can be optionally preceded by the object category. A category groups together a set of types and mainly used with tab completion which is described below.

CLI Help

The CLI help command will show all available command options. A screenshot of the first part of the output from the help command is shown below:

[Tip] Tip: How to display help about help

Typing the CLI command:

Device:/> help help

will give information about the help command itself.

The CLI Command History

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

Tab Completion

Remembering all the commands and their options can be difficult. cOS Core provides a feature called tab completion which means that pressing the tab key will cause automatically completion of the current part of the command. If completion is not possible then pressing the tab key will alternatively display the possible command options that are available.

For example, when creating an IP Policy object, the command line might begin:

Device:/> add IPPolicy

If the tab key is now pressed, the mandatory space is inserted and if the tab key is pressed again the mandatory parameters are displayed:

A value is required for the following properties:

 DestinationInterface  Name     SourceInterface
 DestinationNetwork    Service  SourceNetwork

The following might be now be entered, with DestinationInterface incomplete:

Device:/> add IPPolicy DestinationI

If the tab key is now pressed, the property name is completed by cOS Core to become:

Device:/> add IPPolicy DestinationInterface=

Note that completion would not be possible for just Destination because this is still ambiguous and the "I" needs to be added so the first few characters can uniquely identify the property.

The tab key can then be used like this to help complete all the mandatory properties:

Device:/> add IPPolicy	SourceInterface=If2
			SourceNetwork=all-nets
			DestinationInterface=If2
			DestinationNetwork=all-nets
			Service=all_services
			Name=my_example_policy

[Note] Note: CLI commands in this guide may be reformatted

In order to make the individual elements of CLI commands in this publication clearer, they are sometimes broken into indented separate lines, like the example above. In an actual console window they would appear as a single continuous line which folds at the right margin.

Optional Parameters Are Tab Completed Last

Tab completion does not work with optional parameters until all the mandatory parameters have been entered. Once the mandatory property values have been assigned, using the tab key will list all the optional properties for the IP Policy object:
Optional properties, if no value is specified the default is used:

 Action      Comments                Index        Schedule
 AppControl  DestAddressTranslation  LogEnabled   SourceAddressTra
 Attribute   DestinationGeoFilter    LogSeverity  SourceGeoFilter

Getting the Default or Current Property Value

The period "." character before a tab can be used to automatically fill in the default value for an object property in an Add command. For example:
Device:/> add LogReceiver LogReceiverSyslog log_example
	Address=example_ip
	LogSeverity=.<tab>
This will fill in the default value for LogSeverity:
Device:/> add LogReceiver LogReceiverSyslog example
	Address=example_ip
	LogSeverity=Emergency,Alert,Critical,Error,Warning,Notice,Info
This severity list can then be edited with the back arrow and backspace keys. However, a default value is not always available.

This same sequence can be used to get the current property value in a Set command. For example:

Device:/> set LogReceiver LogReceiverSyslog log_example Address=.<tab>

This will display the current value for the Address property.

Appending Property Values

Another usage of the period character before a tab is to automatically fill in the current value of an object property in a command line. This is very useful when there is a need to append a new value to a list of pre-existing values.

For example, the following unfinished command may have been typed:

Device:/> set Address IP4Address If1_ip Address=

If a period "." followed by a tab is now entered, cOS Core displays the current value for Address. If that value were the IPv4 list 10.6.58.10,192.168.2.1 then the unfinished command line will automatically become:

Device:/> set Address IP4Address If1_ip Address=10.6.58.10,192.168.2.1

The displayed values can then be added to or changed with the backspace and back arrow keys before completing the command.

Object Categories

It has been mentioned that objects are grouped by type, such as IP4Address. Types themselves are grouped by category. The type IP4Address belongs to the category Address. The main use of categories is in 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 Core displays all the available categories. By choosing a category and then pressing tab again all the object types for that category is displayed. Using categories means that the user has a simple way to specify what kind of object they are trying to specify and a manageable number of options are displayed after pressing tab.

Not all object types belong in a category. The object type UserAuthRule is a type without a category and will appear in the category list after pressing tab at the beginning of a command.

The category is sometimes also referred to as the CLI context. The category does not have to be entered for the command to be valid but always appears when using tab completion. As discussed later, when commands are created automatically using CLI scripting, cOS Core omits the category in the commands it creates.

Selecting Object Categories

With some categories, it is necessary to first choose a member of that category with the cc (change category) 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:

Device:/> cc RoutingTable main
		
Device:/main> 

Notice that the command prompt changes to indicate the current category. The route can now be added:

Device:/main> add Route Name=new_route1 Interface=lan Network=If1_net

To deselect the category, the command is cc on its own:

Device:/main> cc
		
Device:/> 

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

Inserting into Rule Lists

Rule sets 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= parameter as an option. Inserting at the first position in a list is specified with the parameter Index=1 in an add command, the second position with the parameter Index=2 and so on.

Referencing by Name

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

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

Using Unique Names

For convenience and clarity, it is recommended that a name is assigned to all objects so that it can be used for reference if required. Reference by name is particularly useful when writing CLI scripts. For more on scripts see Section 2.1.7, CLI Scripts.

The CLI will enforce unique naming within an object type. For reasons of backward compatibility to earlier cOS Core releases, an exception exists with IP rules which can have duplicate names, however it is strongly recommended to avoid this. If a duplicate IP rule name is used in two IP rules then only the Index value can uniquely identify each IP rule in subsequent CLI commands. Referencing an IP rule with a duplicated name will fail and result in an error message.

InControl Domains

When using InControl as the means of configuring cOS Core, it is possible to use the logical concept of a Domain to share the same object between firewalls.

The Domain is a construct that only exists in InControl and not in individual firewall configurations. For this reason, the CLI cannot be used to manipulate domains.

Furthermore, an object in an InControl domain may not necessarily be used in the configuration of a firewall which is a child of that domain. If this is the case, the CLI cannot be used to manipulate a domain object on a firewall that does not use it.

Changing the CLI Prompt and Device Name

The default CLI prompt is:
Device:/> 
This can be customized, for example, to my-prompt:/>, by using the following CLI command:
Device:/> set device name="my-prompt"
The CLI Reference Guide uses the command prompt Device:/> throughout.

[Tip] Tip: The CLI prompt is the Web Interface device name

When the command line prompt is changed to a new string value, this string also appears as the new device name in the top level node of the Web Interface navigation tree.

Activating and Committing Changes

If any changes are made to the current configuration through the CLI, those changes will not be uploaded to cOS Core until the command:
Device:/> activate
is issued. Immediately following the activate command, the command:
Device:/> commit
should be issued to make those changes permanent.

[Note] Note: Examples in this guide assume activation will be performed

Most of the examples in this guide deal with editing cOS Core configurations. The final activation step is usually not explicitly stated.

If the commit command is not entered after the activate command within a given time period (the default is 30 seconds) then the changes are automatically undone and the old configuration restored. This topic is discussed further in Section 2.1.2, Configuring Network Management Access.

[Note] Note: CLI commits terminate Web Interface sessions

There is a possible side effect of committing changes through the CLI. Any Web Interface browser session that is logged in at the time of the commit will require that the user logs in again. This is because the Web Interface view of the configuration may no longer be valid.

Restarting and Rebooting cOS Core with the CLI

The CLI can be used to reboot cOS Core using the command:
Device:/> shutdown
This command performs a graceful shutdown of all connections and VPN tunnels before the restart and is sufficient for most situations that require a system restart. It includes a reloading of the configuration (in other words, a reconfiguration operation).

The shutdown command can be followed by an integer between 0 and 60 which is a delay in seconds before the command is executed. For example:

Device:/> shutdown 30

The default value for the delay is 5 seconds.

To shut down and restart both cOS Core and completely reinitialize the system, including the cOS Core loader (equivalent to switching the hardware off then on), use the command:

Device:/> shutdown -reboot

The -reboot option is rarely needed in normal circumstances and because it requires more time for the restart it is best not to use it. When cOS Core is upgraded the -reboot option is executed automatically during the upgrade process.

The same restart functions can be performed through the Web Interface by selecting the option: Status > Maintenance > Reset & Restore > Restart.

Initiating cOS Core Reconfiguration with the CLI

cOS Core can be forced to reread and reload the current configuration with the command:
Device:/> reconf
Apart from reloading the configuration, many of cOS Core's internal data structures related to rules and traffic processing are reinitialized. It is not usual to execute a reconfigure during normal operation but it can sometimes be a way to solve transient problems related to cOS Core memory management.

Unlike the system restart described above, a reconfiguration does not usually affect current connections or VPN tunnels. However, with some IPsec tunnel changes, a reconfiguration will mean the tunnels are lost and have to be reestablished because the tunnel SAs are no longer valid.

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:
Device:/> show -errors
This will cause cOS Core 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.

Logging off from the CLI

After finishing working with the CLI, it is recommended to logout in order to avoid letting anyone getting unauthorized access to the system. Log off by using the exit or the logout command.

Configuring Remote Management Access on an Interface

Remote management access may need to be configured through the CLI. Suppose management access is to be through Ethernet interface If2 which has an IP address 10.8.1.34.

First, we set the values for the IPv4 address objects for If2 which already exist in the cOS Core address book, starting with the interface IP:

Device:/> set Address IP4Address InterfaceAddresses/If2_ip
			Address=10.8.1.34

The network IP address for the interface must also be set to the appropriate value:

Device:/> set Address IP4Address InterfaceAddresses/If2_net
			Address=10.8.1.0/24

In this example, local IP addresses are used for illustration but these could be public IPv4 addresses instead. It is also assumed that the default address objects for the configuration are stored in an address book folder called InterfaceAddresses.

Next, create a remote HTTP management access object, in this example called HTTP_If2:

Device:/> add RemoteManagement RemoteMgmtHTTP HTTP_If2
			Interface=If2
			Network=all-nets
			LocalUserDatabase=AdminUsers
			AccessLevel=Admin
			HTTP=Yes

If we now activate and commit the new configuration, remote management access via the IPv4 address 10.8.1.34 is now possible using a web browser. If SSH management access is required then a RemoteMgmtSSH object should be added.

The assumption made with the above commands is that an all-nets route exists to the ISP's gateway. In other words, Internet access has been enabled for the firewall.

Managing Management Sessions with sessionmanager

The CLI provides a command called sessionmanager for managing management sessions themselves. The command can be used to manage all types of management sessions, including:

  • Secure Shell (SSH) CLI sessions.

  • Any CLI session through the local console interface.

  • Secure Copy (SCP) sessions.

  • Web Interface sessions connected by HTTP or HTTPS.

  • Sessions based on the Clavister proprietary Netcon protocol.

The command without any options gives a summary of currently open sessions:

Device:/> sessionmanager
		
Session Manager status
----------------------
Active connections          :      3
Maximum allowed connections :     64
Local idle session timeout  :    900
NetCon idle session timeout :    600

To see a list of all sessions use the -list option. Below is some typical output showing the local console session:

Device:/> sessionmanager -list

User     Database         IP         Type    Mode     Access
-------- ---------------- ---------  ------- -------  --------
local    <empty>          0.0.0.0    local   console  admin

If the user has full administrator privileges, they can forcibly terminate another management session using the -disconnect option of the sessionmanager command.

The sessionmanager command options are fully documented in the CLI Reference Guide.

2.1.7. CLI Scripts

To allow the administrator to easily store and execute sets of CLI commands, cOS Core 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 firewall.

The steps for creating a CLI script are as follows:

  1. Create a text file with a text editor containing a sequential list of CLI commands, one per line. The Clavister recommended convention is for these files to use the file extension .sgs (Security Gateway Script). The filename, including the extension, should not be more than 12 characters.

  2. Upload the file to the Clavister firewall using Secure Copy (SCP). There are a number of third party software products that can provide SCP on various computer platforms. Script files must be stored in a directory below the root called script. For example, a typical SCP console command for uploading might be:

    > scp my_script.sgs admin1@10.5.62.11:script/

    SCP uploading is discussed further in Section 2.1.8, Using SCP.

  3. Use the CLI command script -execute 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 CLI Reference Guide and specific examples of usage are detailed in the following sections. See also Section 2.1.6, Using the CLI.

[Note] Note: Uploaded scripts are lost after a restart

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

Only Four Commands are Allowed in CLI Scripts

The commands allowed in a script file are limited to four and these are:

  • add
  • set
  • delete
  • cc

If any other command appears in a script file it is ignored during execution and a warning message is output. For example, the ping command will be ignored.

Executing Scripts

As mentioned above, the script -execute command launches a named script file that has been previously uploaded to the firewall. For example, to execute the script file my_script.sgs which has already been uploaded, the CLI command would be:
Device:/> script -execute -name=my_script.sgs

Script Variables

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

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

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

[Note] Note: The symbol $0 is reserved

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

For example, a script called my_script.sgs is to be executed with IP address 126.12.11.01 replacing all occurrences of $1 in the script file and the string If1 address replacing all occurrences of $2.

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

add Address IP4Address If1_ip Address=$1 Comments=$2

To run this script file after uploading, the CLI command would be:

Device:/> script -execute -name=my_script.sgs 126.12.11.01 "If1 address"

When the script file runs, the variable replacement would mean that the file becomes:

add Address IP4Address If1_ip Address=126.12.11.01 Comments="If1 address"

Escaping Characters

Sometimes, there is a requirement to escape certain characters in a command so they are treated as ordinary characters when the command is executed. This is particularly true for the dollar-sign "$" character. Consider the string: "te$t". In order to have the dollar-sign treated as a normal character, it can be escaped in the normal way by using a backslash "\" 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. This means that the written ordering of the script 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 approach 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 confused and disjointed script files and in large script files it is often preferable to group together related CLI commands.

Error Handling

If an executing CLI script file encounters an error condition, the default behavior is for the script to terminate. This behavior can be overridden by using the -force option.

For example, to run a script file called my_script2.sgs in this way so that errors do not terminate execution, the CLI command would be:

Device:/> script -execute -name=my_script2.sgs -force

If -force is used, the script will continue to execute even if errors are returned by a command in the script file.

Script Output

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

Saving Scripts

When a script file is uploaded to the firewall, it is initially kept only in temporary RAM memory. If cOS Core restarts then any uploaded scripts will be lost from this volatile memory and must be uploaded again to run. To store a script between restarts, it must explicitly be moved to non-volatile cOS Core disk memory by using the script -store command.

For example, to move my_script.sgs to non-volatile memory, the command would be:

Device:/> script -store -name=my_script.sgs

Alternatively, all scripts can be moved to non-volatile memory with the command:

Device:/> script -store -all

Removing Scripts

To remove a saved script, the script -remove command can be used. For example, to remove the my_script.sgs script file, the command would be:
Device:/> script -remove -name=my_script.sgs

Listing Scripts

The script on its own, command without any parameters, lists all the scripts currently available and indicates the size of each script as well as the type of memory where it resides (residence in non-volatile memory is indicated by the word "Disk" in the Memory column).
Device:/> script
		
Name            Storage       Size (bytes)
--------------  ------------  --------------
my_script.sgs   RAM           8
my_script2.sgs  Disk          10

To list the content of a specific uploaded script file, for example my_script.sgs the command would be:

Device:/> script -show -name=my_script.sgs

Creating Scripts Automatically

When the same configuration objects needs to be copied between multiple 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 a configuration already exists that contains the objects that need to be copied, then running the script -create command on that configuration provides a way to automatically create the required script file. This script file can then be downloaded to the local management computer and then uploaded to and executed on other firewalls to duplicate the configuration objects.

For example, suppose the requirement is to create the same set of IP4Address objects on several firewalls that already exist on a particular firewall. The administrator would issue the following CLI command on the firewall that is to be copied:

Device:/> script -create Address IP4Address -name=new_script.sgs

This creates a script file called new_script_sgs which contains all the CLI commands necessary to create all IP4Address address objects in the configuration. The created file's contents might look something like the following:

add Address IP4Address If1_ip Address=10.6.60.10
add Address IP4Address If1_net Address=10.6.60.0/24
add Address IP4Address If1_br Address=10.6.60.255
add Address IP4Address If1_dns1 Address=141.1.1.1
		"
		"
		"

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

The following should be noted for automatically created scripts:

  • Automatically created scripts omit the object category.

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

    			add IP4Address...

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

    			add Address IP4Address...

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

  • The script filename length has a limit.

    The name of the file created using the -create option cannot be greater than 16 characters in length (including the extension) and the filetype should always be .sgs.

  • Both Set and Add appear in scripts.

    The default configuration objects will have a Set action and the objects added to the default configuration will have an Add action.

  • Creating scripts for the entire configuration.

    It is possible to create a script for the entire configuration with the command:

    Device:/> script -create -name=entire_config.sgs

    This can be useful if the entire configuration is to be recreated.

    However, note that the following objects will not be included in a script created for the entire configuration:

    1. Added Certificate objects.

    2. Objects marked for deletion.

  • Some objects are always excluded from created script files.

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

    • COMPortDevice
    • Ethernet
    • EthernetDevice
    • Device

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

[Tip] Tip: Listing created script commands on the console

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

Commenting in Script Files

Any line in a script file that begins with the # character is treated as a comment. For example:
# The following line defines the If1 IP address
add Address IP4Address 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 -execute -name my_script2.sgs
cOS Core allows the script file my_script2.sgs to execute another script file and so on. The maximum depth of this script nesting is 5.

Running Scripts from the Web Interface

It is possible to upload and execute a CLI script through the Web Interface. Following execution of the script, it is not retained in memory.

The script does not need to have a filetype of .sgs for this feature to be used. Any filetype is acceptable.

Example 2.10. Running a CLI Script from the Web Interface

In this example, a CLI script called my_script.sgs on local disk storage is uploaded and executed through the Web Interface.

Web Interface

  1. Go to: Status > Maintenance > Import Script
  2. Select Browse and choose the script file my_script.sgs
  3. Select Upload and Execute
  4. A message is displayed indicating successful execution
  5. The changed configuration must now be activated and saved

2.1.8. Using SCP

To upload and download files to or from the Clavister firewall, the Web Interface could be used in most cases. An alternative method of file transfer is to use the secure copy (SCP) protocol and an appropriate SCP client. SCP is based on the SSH protocol and many freely available SCP clients exist for most platforms. The SCP command line examples in this section are based on a typical command format for client software.

[Note] Note: Not all SCP client functions may be supported
Some extended SCP functions may not be supported by cOS Core. For example, the file listing function found in WinSCP is not supported.

SCP Command Format

SCP command syntax is straightforward for most console based SCP clients. The SCP command examples used here are based on a typical SCP client where scp is followed by the source and destination for the file transfer.

An example of how upload might be performed is using the command:

> scp <local_filename> <destination_gateway>

An example of how download might be performed is using the command:

> scp <source_gateway> <local_filename>

The source or destination firewall is usually of the form:
<user_name>@<firewall_ip_address>:<filepath>.

For example: admin@10.62.11.10:config.bak. The <user_name> must be a defined cOS Core user in the administrator user group.

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

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

The following table summarizes the operations that can be performed between an SCP client and cOS Core.

File type Upload possible Download possible
Configuration Backup (config.bak) Yes (also with WebUI) Yes (also with WebUI)
System Backup (full.bak) Yes (also with WebUI) Yes (also with WebUI)
Firmware upgrades Yes No
Licenses (license.lic) Yes (also with WebUI) No
Certificates Yes Yes
SSH public keys Yes No
Web auth banner files Yes Yes
Web content filter banner files Yes Yes

The cOS Core Folder Structure

cOS Core maintains a simple two level directory structure which consists of the top level root and a number of sub-directories. However, these "directories" such as sshlclientkey should be more correctly thought of as object types. All the files stored in the cOS Core root as well as all the object types can be displayed using the CLI command ls.

The resulting output is shown below:

Device:/> ls
		
HTTPALGBanners/
HTTPAuthBanners/
certificate/
config.bak
full.bak
license.lic
script/
sshpublickeys/

Apart from the individual files, the objects types listed are:

  • HTTPAuthBanners/ - The folder containing the HTML banner files for user authentication. Uploading these is described further in Section 6.2.5, Customizing WCF HTML Pages.

  • HTTPALGBanners/ - The folder containing HTML banner files for HTML ALG dynamic content filtering. Uploading these is described further in Section 6.2.5, Customizing WCF HTML Pages.

  • certificate/ - The folder containing uploaded X.509 digital certificates for VPN.

  • script/ - The folder containing all CLI scripts. Scripts are described further in Section 2.1.7, CLI Scripts.

  • sshpublickeys/ - The folder containing SSH client public key files that allow automatic authentication from an SSH client which has the matching private key installed.

    The filename should not have a filetype (in other words, there should be no period character in the name). After upload, the administrator should associate the file with a User object so that user can have automatic authentication enabled.

    SSH authentication with certificates is described further in Section 2.1.5, CLI Access.

Examples of SCP Uploading and Downloading

Below are examples of uploading and downloading commands using a typical SCP client. In some cases, a file may be located in the cOS Core root directory. Configuration backup files (config.bak) and the complete system backup files (full.bak) will be saved to the root directory. The cOS Core license file (license.lic) will also be stored in the root.

When uploading, these files contain a unique header which identifies what they are. cOS Core checks this header and ensures the file is stored only in the root (all files do not have a header).

If an administrator username is admin1 and the IPv4 address of the Clavister firewall is 10.5.62.11 then to upload a configuration backup, the SCP command would be:

> scp config.bak 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.bak .

To upload a file to an object type under the root, the command is slightly different. If there is a local CLI script file called my_script.sgs then the upload command could be the following

> scp my_script.sgs admin1@10.5.62.11:script/

If we have the same CLI script file called my_scripts.sgs stored on the firewall then the download command would be:

> scp admin1@10.5.62.11:script/my_script.sgs .

Activating Uploads

Like all configuration changes, SCP uploads only become active after the CLI commands activate have been issued and this must be followed by commit to make the change permanent.

Uploads of firmware upgrades (packaged in .upg files) or a full system backup (full.bak) are the exception. Both of these file types will result in an automatic system reboot. The other exception is for script uploads which do not affect the configuration.

2.1.9. The Local Console Boot Menu

Overview

The Clavister firmware loader is the base software on top of which cOS Core runs and the administrator's direct interface to this loader is called the Boot Menu. This section discusses the boot menu and also how the local console can be used to issue cOS Core CLI commands.

The NetWall 100, 300, 500 and 6000 Series Have a Different Boot Menu

Note that this section covers the boot menu for cOS Core in a virtualized environment and on older Clavister hardware products. The boot menu for the Clavister NetWall 100, 300, 500 and 6000 Series hardware products is covered by Section 2.1.10, Boot Menu for the NetWall 100/300/500/6000 Series.

Accessing the Local Console Boot Menu

The boot menu is only accessible via the Clavister firewall's local console port. It is displayed by pressing any console key to interrupt cOS Core's startup sequence when the "Press any key to abort and load boot menu" message appears on the console.

Once cOS Core has fully started, the boot menu cannot be displayed and a restart is required to have another opportunity to display it. When navigating the boot menu, the up/down arrow keys combined with the enter key can be used to select menu options. The <Esc> key can be used to return to the previous boot menu screen.

The Boot Menu Options Without a Password Set

When the boot menu is displayed without a console password set, the following options are presented:

  • Start System

    This closes the boot menu and continues the startup of cOS Core.

  • Display Latest Shutdown Message

    This shows the last cOS Core console message shown before the last system shutdown. This option is not shown if this is the first time that the cOS Core installation has started.

  • Display Latest Crash Dump Message

    This shows the latest crash dump message caused by an error condition in cOS Core. This option will only appear if there is a crash dump to display.

  • Reset Options

    This displays a submenu of reset options. These are described in detail later in this section.

  • Enable Console Password

    Set a password for console access. Until a password is set, anyone can utilize the console so setting a console is strongly recommended.

    The console password can be any sequence of characters but must be no greater than 64 characters in length. It is recommended to use only printable characters.

    The console password is only used for console access through the local console port and does not have a username associated with it. It is not related to the credentials used for login through other management interfaces, such as the Web Interface.

Menu Changes After Setting a Console Password

After a password is set, the subsequent boot menu display will initially offer only the following options:

  • Login

    This allows the administrator to log into the console using the console password so the complete boot menu can be displayed.

  • Start System

    This closes the boot menu and continues the startup of cOS Core.

After a successful console login, the boot menu is then displayed with the following extra options:

  • Change Console Password

    This option replaces the Enable Console Password option and allows the administrator to change the current password for console access.

  • Logout administrator

    This logs out the administrator and returns to the initial boot menu options.

Reset Menu Options

The Reset Options menu offers the following choices:

  • Transfer System to other Boot Media

    This option is for older legacy software installations only and is normally not used. It makes it possible to transfer (or copy) an image of the complete cOS Core system to a portable media, such as a USB stick. Booting can then be done using this media on another computer so that the cOS Core system can be installed there on local disk with another "Transfer System" operation.

  • Reset to Factory Defaults

    This option will restore the system to its initial default state. It will not appear if cOS Core is in its default state. The operations performed with this option are the following:

    1. Remove most cOS Core files stored on disk memory, including all certificates as well as HA and DHCP lease settings. However, not all files are deleted. For example, license files will not be deleted, nor will files created by the pcapdump command. Files related to the Anti-Virus or IDP features will also not be deleted. Any undeleted files can still be manually deleted using the appropriate CLI command.
    2. Reset console security so there is no console password.
    3. Restore the original default cOS Core configuration and loader executables.
  • Reset to Base Configuration

    This will only reset the cOS Core configuration to be the original, default configuration. Other aspects of the system, such as console security, will not be affected.

Using the Console for CLI Commands

cOS Core will startup either because the initial startup sequence wasn't interrupted to enter the boot menu or because startup was commenced from the boot menu. Once cOS Core is up and running, the local console can also be used to enter any CLI command in the same way that an SSH client can.

If a console password has been set and a login has not yet been performed then cOS Core will prompt for the console password before CLI commands can be entered and it is therefore recommended the console password is enabled as soon as possible in order to prevent unauthorized access.

[Note] Note: Output buffer limitations

The only limitation with issuing CLI commands through the local console is that there is a finite buffer allocated for output. This buffer limit means that a large volume of console output may be truncated. This happens rarely and usually only with data dumps from certain diagnostic commands. In such cases it is better to issue the commands using an SSH client instead.

2.1.10. Boot Menu for the NetWall 100/300/500/6000 Series

This section covers the boot menu for the Clavister NetWall 100, 300, 500 and 6000 Series hardware products which is accessible through the local console on those appliances. The boot menu for cOS Core in a virtualized environment and on older Clavister hardware products is covered by Section 2.1.9, The Local Console Boot Menu.

Accessing the Local Console Boot Menu

The boot menu is only accessible via the Clavister firewall's local console port. It is displayed by pressing the Esc key to interrupt the cOS Core startup sequence.

Once cOS Core has fully started, the boot menu cannot be displayed and a restart is required to have another opportunity to display it.

The Boot Menu Options

When the boot menu is displayed, the following options are presented:

  • Boot System

    This closes the boot menu and continues the startup of cOS Core.

  • Boot-failure recovery

    The system will boot using its own internal system memory. cOS Core will then run in a safe mode. This means the the system will function but only limited resources will be available. However, these resources are sufficient for cOS Core to be used with a full CLI command set to troubleshoot problems.

  • Reset system to factory default

    This restores both the current configuration and cOS Core version to the factory settings. Any cOS Core version upgrades that have been installed will be lost.

  • Restore system default configuration

    This restores only the default configuration. No cOS Core version upgrades that have been installed will be lost. This is the recommended option unless a full reset is required.

2.1.11. RADIUS Management Authentication

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

An alternative to using a local database is to have cOS Core perform authentication of the entered credentials against an external RADIUS server. This is done by changing the properties of the Remote Management object mgmt_http for Web Interface access and/or the properties of the mgmt_ssh object for CLI access via SSH. Configuring either of these objects for RADIUS authentication consists of the following steps:

  1. Select the Authentication Source property to be RADIUS.

  2. Select the Authentication Order property to be one of the following:

    1. Local First - 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.

    2. Local Last - The local database is only queried if none of the configured RADIUS servers responds to an authentication request.

  3. Select one or more RADIUS servers to use for authentication. If there is more than one, they will be tried sequentially if one is unavailable. The servers selected must have already been configured as Radius Server objects in cOS Core (see Section 9.2.3, External RADIUS Servers for how to do this).

  4. Specify the Admin Groups and/or Audit Groups to decide which kind of access will be given once login credentials are authenticated by a RADIUS server. These group names are matched by cOS Core against the group name returned for the user by the RADIUS server. Setting either of these properties to the single wildcard character asterisk "*" means that any group will get that access. Leaving either property blank means no user can have that type of access.

    The administrator group names take precedence over the auditor groups. This means if a user is first authenticated by being a member of the administrator groups, auditor group membership is ignored. Therefore, specifying the asterisk "*" character for the Admin Groups property means that auditor group membership will never be checked.

    Note that the wildcard "*" character can be used instead of all or part of a group name. For example, the string sys* means any group name that begins with the three letters sys.

[Important] Important: Group membership must be defined on the server

It is important to note that all management users authenticated by a RADIUS server must have their group membership defined on the RADIUS server. They cannot be authenticated without group membership which cOS Core matches against the Admin Groups and Audit Groups properties.

[Note] Note: Set the RADIUS Vendor ID for group membership

If the RADIUS server sends the group membership, it is necessary to use the Clavister-User-Group vendor specific attribute when configuring the server. The Clavister Vendor ID is 5089 and the Clavister-User-Group is defined as vendor-type 1 with a string value type.

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 almost no indication in the Web Interface or 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 any group in the Admin Groups or Audit Groups, then the Web Interface or CLI will display the following message:

	You do not have permission to access this device.

Generated Log Event Messages

Log messages indicate a successful or unsuccessful login by the administrator. With RADIUS management authentication, the log message will show the following field values:

  • The usergroups field will show a list of all the group memberships returned by the authenticating RADIUS server. This is often helps in troubleshooting why a user was unable to successfully login.

  • The access_level indicates the privileges granted for successful authentication.

  • The authsource field will have the value RADIUS.

  • The userdb field will have the value of the RADIUS server object name used.

  • The server_ip is the IP of the cOS Core interface the client is connecting to. It is not the IP of the authenticating RADIUS server.

  • The client_ip is the IP of the computer the user is trying to login from.

Below are some typical examples of log event messages:

  • Successful RADIUS Authentication

    A successful login with the user being part of the system_admins group:

event=admin_login authsystem=HTTP interface=If1 username=jdoe
usergroups=sys_admins access_level=administrator authsource=RADIUS
userdb=radius_auth1 server_ip=192.168.1.1 server_port=80
client_ip=192.168.1.30 client_port=6132
  • Insufficient Access Rights

    The user entered a correct username and password but the group name returned by the RADIUS server (sys_admins in the example below) was not found in either the Admin Groups or Audit Groups lists:

event=admin_authorization_failed action=disallow_admin_access
authsystem=HTTP interface=If1 username=jdoe usergroups=sys_admins
authsource=RADIUS	userdb=radius_auth1 server_ip=192.168.1.1
server_port=80 client_ip=192.168.1.30 client_port=6042
  • Servers Unreachable

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

event=admin_authsource_timeout authsystem=HTTP interface=If1 username=jdoe
authsource=RADIUS server_ip=192.168.1.1 server_port=80
client_ip=192.168.1.30 client_port=5987

The Local Console is a Fallback Option

It is possible that the administrator could be locked out from logging on via the Web Interface or the CLI over SSH because a RADIUS server will not authenticate the entered credentials and the local database is not allowed to do it either. In such cases, the local console port on the Clavister 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 console password is totally separate from other management passwords).

Example 2.11. Enabling RADIUS Management Authentication

This example will change the current default rule for Web Interface management access so that authentication is performed using two RADIUS servers. It is assumed that the RADIUS server objects are already defined in the configuration and have the names radius_auth1 and radius_auth2 where radius_auth2 is the fallback server in case the other fails to respond.

The Authentication Order will be set to Local First which will mean that the local cOS Core database will be consulted first. If the user is not found there then the RADIUS servers will be queried.

All users who are members of the group sys_admins are allowed full access privileges. All other authenticated users will have audit privileges only.

Command-Line Interface

Device:/> set RemoteManagement RemoteMgmtHTTP rmgmt_http
			AuthSource=RADIUS
			AuthOrder=LocalFirst
			RadiusServers=radius_auth1,radius_auth2
			AdminGroups=sys_admins

Web Interface

  1. Go to: System > Device > Remote Management
  2. Select the rmgmt_http object so that its properties can be edited
  3. Set Authentication Source to RADIUS
  4. Set Authentication Order to Local First
  5. For RADIUS Server, select radius_auth1 and press Include
  6. Repeat the preceding step, selecting radius_auth2
  7. Set Admin Groups to be sys_admins
  8. Click OK

2.1.12. Strong Passwords

To ensure system security, cOS Core has a global option to enforce the use of strong passwords for users in any local user databases. This option is only available in cOS Core version 11.10.00 and later.

A strong password is defined by cOS Core as follows:

  • It must be at least 8 characters in length.

  • It must not contain significant portions of the username.

  • It must comply with at least three of the following four requirements:

    1. It must contain at least one lowercase character.

    2. It must contain at least one uppercase character.

    3. It must contain at least one digit (0 to 9).

    4. It must contain at least one non-alphabetic character such as !, $, # or %.

Enabling Strong Passwords

The strong passwords feature is enabled by default in a new installation of cOS Core. However, it can be disabled manually and the cOS Core Setup Wizard also provides the option to disable it during initial cOS Core setup.

If it is not disabled in the setup wizard then the wizard will require a conforming strong password to be entered to replace the default weak admin password. If running the setup wizard is skipped and the strong password option is left enabled, cOS Core will not allow configuration changes to be activated until the admin password conforms to the strong password rules.

If setting up cOS Core for the first time, it is strongly recommended that the first step taken is to change the admin user password from the default weak value of admin to a password that conforms to the strong password rules.

Checking of Strong Passwords

If the strong passwords option is enabled, there are two occasions when new passwords are checked for strength:

  • When a new user is added to a local user database and the password specified.

  • When the password of an existing user is changed.

Apart from the user admin, a fresh cOS Core configuration will also have a pre-existing user called audit with the default password audit. The audit user password will remain weak until the administrator changes it to a password that conforms to the strong password rules listed above.

Upgrading Older cOS Core Versions

The strong passwords feature was introduced in cOS Core version 11.10.00. If an older cOS Core version than this is upgraded to a 11.10 version or later, the strong passwords option is always disabled after the upgrade. The strong passwords option must be manually enabled by the administrator if it is required.

However, all passwords for users created before the upgrade will be flagged as not having strong passwords, even if the strong password option is enabled later. If a weak password for a user from the old configuration is to be made strong then the password for that user should be changed to a strong password after the upgrade. If the strong passwords option is enabled, cOS Core will make sure that the new password conforms to the strong password rules when it is entered.

Checking User Password Status

When the user list for a local user database is displayed in the Web Interface, there is a column with the title Strong Password. This has a value of either Yes or No which indicates if the password conforms to the strong password rules or not.

Example 2.12. Disabling Strong Passwords

Although not recommended, this example shows how strong passwords are disabled so that they are no longer enforced by cOS Core in local user user databases.

Command-Line Interface

Device:/> set Settings MiscSettings EnforceStrongPasswords=No

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: System > AdvancedSettings > DeviceSettings > MiscSettings
  2. Disable the setting: Enforce Strong passwords
  3. Click OK

2.1.13. Management Advanced Settings

Under the Remote Management section of the Web Interface or InControl a number of advanced settings can be found. These are:

SSH Before Rules

Enable SSH traffic to the firewall regardless of configured IP rule set entries.

Default: Enabled

WebUI Before Rules

Enable HTTP(S) traffic to the firewall regardless of configured IP rule set entries.

Default: Enabled

SSH Idle Timeout

Number of seconds of inactivity until the local console user is automatically logged out.

Default: 900

NetCon Idle Timeout

Number of seconds of inactivity until the NetCon session is close.

Default: 600

NetCon Before Rules

For NetCon traffic to cOS Core: add an invisible rule to the IP rule set to allow NetCon traffic. If this setting is disabled then NetCon traffic will be subject to the IP rule set like any other traffic.

Default: Enabled

NetConMaxChannels

For NetCon traffic to cOS Core the following number of connections are guaranteed for each connection type:
  • Consoles: 4
  • Realtime loggers: 4
  • Stat pollers: 4
  • Receive contexts: 2
  • Send contexts: 4
NetConMaxChannels is the maximum total allowed for all these connection types. This means that with the default value of 18, 2 extra connections are allowed and they can be of any of the above types.

Default: 18

Validation Timeout

Specifies the amount of seconds to wait for the administrator to log in before reverting to the previous configuration.

Default: 30

WebUI HTTP port

Specifies the HTTP port for the Web Interface.

Default: 80

WebUI HTTPS port

Specifies the HTTP(S) port for the Web Interface.

Default: 443

HTTPS Certificate

Specifies which certificate to use for HTTPS traffic. Only EC and RSA certificates are supported.

Default: HTTPS

2.1.14. Working with Configurations

Configuration Objects

The system configuration is built up by Configuration Objects, where each object represents a configurable item of any kind. Examples of configuration objects are routing table entries, address book entries, service definitions, IP rules and so on. Each configuration object has a number of properties that constitute the values of the object.

Object Types

A configuration object has a well-defined type. The type defines the properties that are available for the configuration object, as well as the constraints for those properties. For instance, the IP4Address type is used for all configuration objects representing a named IPv4 address.

Object Organization

In the Web Interface the configuration objects are organized into a tree-like structure based on the type of the object.

In the CLI, similar configuration object types are grouped together in a category. These categories are different from the structure used in the Web Interface to allow quick access to the configuration objects in the CLI. The IP4Address, IP4Group and EthernetAddress types are, for instance, grouped in a category named Address, as they all represent different addresses. Consequently, Ethernet and VLAN objects are all grouped in a category named Interface, as they are all interface objects. The categories have actually no impact on the system configuration; they are merely provided as means to simplify administration.

The following examples show how to manipulate objects.

Example 2.13. Listing Configuration Objects

To find out what configuration objects exist, you can retrieve a listing of the objects. This example shows how to list all service objects.

Command-Line Interface

Device:/> show Service
A list of all services will be displayed, grouped by their respective type.

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: Objects > Services
  2. A web page listing all services will be presented.

A list contains the following basic elements:

  • Add Button - Displays a dropdown menu when clicked. The menu will list all types of configuration items that can be added to the list.

  • Header - The header row displays the titles of the columns in the list. The tiny arrow images next to each title can be used for sorting the list according to that column.

  • Rows - Each row in the list corresponds to one configuration item. Most commonly, each row starts with the name of the object (if the item has a name), followed by values for the columns in the list.

A single row in the list can be selected by clicking on the row on a spot where there is no hyperlink. The background color of the row will turn dark blue. Right-clicking the row will display a menu which gives the option to edit or delete the object as well as modify the order of the objects.

Example 2.14. Displaying a Configuration Object

The simplest operation on a configuration object is to show the values of its properties. This example shows how to display the contents of a configuration object representing the telnet service.

Command-Line Interface

Device:/> show Service ServiceTCPUDP telnet
						
          Property  Value
 -----------------  -------
             Name:  telnet
 DestinationPorts:  23
             Type:  TCP
      SourcePorts:  0-65535
         SYNRelay:  No
   PassICMPReturn:  No
              ALG:  <empty>
      MaxSessions:  1000
         Comments:  Telnet
The Property column lists the names of all properties in the ServiceTCPUDP class and the Value column lists the corresponding property values.

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: Objects > Services
  2. Select the telnet entry in the list
  3. A web page displaying the telnet service will be presented

Example 2.15. Editing a Configuration Object

When the behavior of cOS Core is changed, it is most likely necessary to modify one or several configuration objects. This example shows how to edit the Comments property of the telnet service.

Command-Line Interface

Device:/> set Service ServiceTCPUDP telnet Comments="Modified Comment"

Show the object again to verify the new property value:

Device:/> show Service ServiceTCPUDP telnet
						
          Property  Value
 -----------------  -------
             Name:  telnet
 DestinationPorts:  23
             Type:  TCP
      SourcePorts:  0-65535
         SYNRelay:  No
   PassICMPReturn:  No
              ALG:  <empty>
      MaxSessions:  1000
         Comments:  Modified Comment

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: Objects > Services
  2. Select the telnet entry in the list
  3. In the Comments textbox, a suitable comment
  4. Click OK

Verify that the new comment has been updated in the list.

[Important] Important: Configuration changes must be activated

Changes to a configuration object will not be applied to a running system until the new cOS Core configuration is activated.

Example 2.16. Adding a Configuration Object

This example shows how to add a new IP4Address object, here creating the IPv4 address 192.168.10.10, to the address book.

Command-Line Interface

Device:/> add Address IP4Address myhost Address=192.168.10.10

Show the new object:

Device:/> show Address IP4Address myhost
						
              Property  Value
 ---------------------  -------------
                 Name:  myhost
              Address:  192.168.10.10
       UserAuthGroups:  <empty>
 NoDefinedCredentials:  No
             Comments:  <empty>

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: Objects > Address Book
  2. Click on the Add button
  3. In the dropdown menu displayed, select IP Address
  4. In the Name text box, enter myhost
  5. Enter 192.168.10.10 in the IP Address textbox
  6. Click OK
  7. Verify that the new IP4 address object has been added to the list

Example 2.17. Deleting a Configuration Object

This example shows how to delete the newly added IP4Address object.

Command-Line Interface

Device:/> delete Address IP4Address myhost

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: Objects > Address Book
  2. Right-click on the row containing the myhost object.
  3. In the dropdown menu displayed, select Delete.

The row will be shown with a strikethrough line indicating that the object is marked for deletion.

Example 2.18. Undeleting a Configuration Object

A deleted object can always be restored until the configuration has been activated and committed. This example shows how to restore the deleted IP4Address object shown in the previous example.

Command-Line Interface

Device:/> undelete Address IP4Address myhost

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: Objects > Address Book
  2. Right-click on the row containing the myhost object.
  3. In the dropdown menu displayed, select Undo Delete.

Listing Modified Objects

After modifying several configuration objects, you might want to see a list of the objects that were changed, added and removed since the last commit.

Example 2.19. Listing Modified Configuration Objects

This example shows how to list configuration objects that have been modified.

Command-Line Interface

Device:/> show -changes
						
    Type           Object
    -------------  ------
 -  IP4Address     myhost
 *  ServiceTCPUDP  telnet

A "+" character in front of the row indicates that the object has been added. A "*" character indicates that the object has been modified. A "-" character indicates that the object has been marked for deletion.

Web Interface

  1. Go to: Configuration > View Changes in the menu bar.
  2. A list of changes is displayed.

Activating and Committing a Configuration

After changes to a configuration have been made, the configuration has to be activated for those changes to have an impact on the running system. During the activation process, the new proposed configuration is validated and cOS Core will attempt to initialize affected subsystems with the new configuration data.

[Important] Important: Committing IPsec Changes

The administrator should be aware that if any changes that affect the configurations of live IPsec tunnels are committed, then those live tunnels connections will be terminated and must be reestablished.

If the new configuration is validated, cOS Core will wait for a short period (30 seconds by default) during which a connection to the administrator must be reestablished.

If a lost connection could not be re-established then cOS Core will revert to using the previous configuration. This is a fail-safe mechanism and, amongst other things, can help prevent a remote administrator from locking themselves out.

Example 2.20. Activating and Committing a Configuration

This example shows how to activate and commit a new configuration.

Command-Line Interface

Device:/> activate

The system will validate and start using the new configuration. When the command prompt is shown again:

Device:/> commit

The new configuration is now committed.

InControl

Activating and committing changes with InControl is done in a different way to the Web Interface

Web Interface

  1. Go to: Configuration > Save and Activate in the menu bar
  2. Click OK to confirm

The web browser will automatically try to connect back to the Web Interface after 10 seconds. If the connection succeeds, this is interpreted by cOS Core as confirmation that remote management is still working. The new configuration is then automatically committed.

[Note] Note: Changes must be committed

The configuration must be committed before changes are saved. All changes to a configuration can be ignored simply by not committing a changed configuration.

Configuration Revision Numbers

Every time a new configuration version is created and activated, a configuration revision number is allocated to the version. This number has two parts and is of the form nn:mm.

The first part of the number, nn, is incremented every time a new configuration is activated through a non-InControl interface such as the Web Interface or CLI. The second part of the number, mm, is incremented every time a new configuration is activated through an InControl client. In the Web Interface, only the first part is displayed as the Configuration number in the start page.

2.2. System Date and Time

2.2.1. Overview

Correctly setting the date and time is important for cOS Core to operate properly. Time scheduled policies, auto-update of the IDP and Anti-Virus databases, and other product features such as digital certificates require that the system clock is accurately set.

In addition, log messages are tagged with timestamps 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 Local System Clock

To maintain current date and time, cOS Core makes use of the local hardware platform's real-time hardware clock. On Clavister hardware models, this clock is also equipped with a battery backup to guard against a temporary loss of power.

Methods of Setting the Time

cOS Core provides two methods of setting the time:

  • Setting Manually

    The date and time can be set manually by the administrator. This is described in Section 2.2.2, Setting Date and Time Manually.

  • Setting Automatically Using External Time Servers

    cOS Core supports the use of external time Servers using time synchronization protocols to automatically adjust the local system clock from the response to queries sent over the Internet to these servers. This is described further in Section 2.2.3, Using External Time Servers.

    There are two types of time server that cOS Core can use:

    1. Public Servers - These are servers that can be used by anyone.
    2. Clavister Servers - These are Clavister's own time servers and is the recommended method of setting the date and time.

2.2.2. Setting Date and Time Manually

Current Date and Time

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

Example 2.21. Setting the Current Date and Time

To adjust the current date and time, follow the steps outlined below:

Command-Line Interface

Device:/> 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. For example, to set the date and time to 9:25 in the morning on April 27th, 2008 the command would be:
Device:/> time -set 2008-04-27 09:25:00

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: System > Device > Date and Time
  2. Click Set Date and Time
  3. Set year, month, day and time via the dropdown controls
  4. Click OK
[Note] Note: A reconfigure is not required

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

Time Zones

The world is divided up into a number of time zones with Greenwich Mean Time (GMT) in London at zero longitude being taken as the base time zone. All other time zones going east and west from zero longitude are taken as being GMT plus or minus a given integer number of hours. All locations counted as being inside a given time zone will then have the same local time and this will have an integer hour offset from GMT.

Setting the Location and Enabling Daylight Saving Time (DST)

For cOS Core, the time zone is specified using the Location property of the Date and Time object. cOS Core has a database of all available time zones and the administrator just has to pick a place that matches the system's longitude position.

By default, the Location property is set to a value of ClavisterHQ (in other words, Stockholm time). The DST (daylight saving time) property is also enabled by default which means that the daylight saving rules for the given location will be automatically followed.

The Location property can be changed from the default at any time by the administrator. However, it can also be changed in one of the steps in the Startup Wizard which will run when cOS Core is started up for the first time.

Example 2.22. Setting the Time Zone Location

This example will modify the default cOS Core time zone to be Tokyo:

Command-Line Interface

Device:/> set DateTime Location=Asia/Tokyo

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: System > Device > Date and Time
  2. In the Location drop-down list, select Asia/Tokyo
  3. Click OK

2.2.3. Using External Time Servers

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

Time Synchronization Protocols

Time Synchronization Protocols are standardized methods for retrieving time information from external time servers. cOS Core supports the following such protocols:

  • SNTP

    Defined by RFC-2030, The Simple Network Time Protocol (SNTP) is a lightweight implementation of NTP (RFC-1305). SNTP is used by cOS Core to query time servers. Most public time servers are described as being NTP servers and are accessible using SNTP.

  • UDP/TIME

    The UDP/TIME protocol is an older method of providing time synchronization service over the Internet. The server sends back the time in seconds since midnight on January 1st, 1900.

Methods of Configuring Time Servers

cOS Core provides the ability to configure one of the following two types of time server:

  • The Clavister Time Server

    Clavister operates its own time server which can be used instead of publicly available servers.

  • Custom Time Servers

    Specific time servers can be specified. There are a number of publicly available time servers that can be configured.

Configuring these two types of server is described next.

Configuring the Clavister Time Server

A single property exists to switch on or off usage of the Clavister time server. This is the easiest way of configuring a time server since no other server details need to be specified. cOS Core will find the IP address of the time server by performing a DNS lookup of the time server's FQDN.

Note that at least one external DNS server must be configured in cOS Core so that the FQDN of the Clavister's time server can be resolved.

Example 2.23. Using the Clavister Time Server

To enable the use of the Clavister time server:

Command-Line Interface

Device:/> set DateTime TimeSynchronization=Clavister

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: System > Device > Date and Time
  2. Select Clavister (preconfigured timesync server)
  3. Click OK

Configuring Custom Time Servers

cOS Core can be configured to query multiple external time servers. By using more than a single server, situations where an unreachable server causes the time synchronization process to fail can be prevented. cOS Core always queries all configured time servers and then computes an average time based on all responses. Internet search engines can be used to find publicly available time servers.

When specifying the IP address of custom time servers, there are only two ways this can be done:

  • Specify an IPv4 or IPv6 address directly.

  • Specify an FQDN Address object which contains a reference to the server's URL. At least one external DNS server must also be configured in cOS Core to resolve such address objects. This is discussed further in Section 3.1.7, FQDN Address Objects.

Example 2.24. Configuring Custom Time Servers

In this example, time synchronization is set up to use the SNTP protocol to communicate with the time servers at the Swedish National Laboratory for Time and Frequency. The time server URLs are ntp1.sp.se and ntp2.sp.se.

It is assumed that the following FQDN Address objects have already been defined for the URLs:

  • ntp1_fqdn - ntp1.sp.se
  • ntp2_fqdn - ntp2.sp.se

Command-Line Interface

Device:/> set DateTime TimeSynchronization=custom
			TimeSyncServer1=ntp1_fqdn
			TimeSyncServer2=ntp2_fqdn
			TimeSyncInterval=86400

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: System > Device > Date and Time
  2. Enable Custom under Time synchronization
  3. Now enter:
    • Time Server Type: SNTP
    • Primary Time Server: ntp1_fqdn
    • Secondary Time Server: ntp2_fqdn
  4. Click OK

Note that the time server URLs must be specified as an FQDN Address object.

Example 2.25. Manually Triggering a Time Synchronization

Time synchronization can be manually triggered from the CLI. The output below shows a typical response.

Command-Line Interface

Device:/> time -sync
Attempting to synchronize system time...

Server time: 2008-02-27 12:21:52 (UTC+00:00)
Local time:  2008-02-27 12:24:30 (UTC+00:00) (diff: 158)

Local time successfully changed to server time.

Maximum Time Adjustment

To avoid situations where a faulty time server causes the clock to be updated with an extremely inaccurate time, a Maximum Adjustment value (in seconds) can be set. If the difference between the current cOS Core 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 cOS Core 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.

Example 2.26. Modifying the Maximum Adjustment Value

In this example, The maximum adjustment value will be set to 40,000 seconds. This is the maximum time difference that an external server is allowed to adjust for. There may be a valid reason why there is a significant difference such as an incorrect cOS Core configuration.

Command-Line Interface

Device:/> set DateTime TimeSyncMaxAdjust=40000

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: System > Device > Date and Time
  2. Set Max drift to 40000
  3. Click OK

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 adjustment value. It is then possible to manually force a synchronization and disregard the maximum adjustment parameter.

Example 2.27. Forcing Time Synchronization

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

Command-Line Interface

Device:/> time -sync -force

Synchronization Intervals

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.

2.2.4. Settings Summary for Date and Time

Below is a summary of the key properties for date and time:

Time Zone Location

Time zone offset in minutes.

Default: ClavisterHQ (Stockholm)

DST

Enable daylight saving time (DST) for the selected time zone.

Default: Enabled

Time Sync Server Type

Type of server for time synchronization, UDPTime or SNTP (Simple Network Time Protocol).

Default: SNTP

Primary Time Server

DNS hostname or IP Address of Timeserver 1.

Default: None

Secondary Time Server

DNS hostname or IP Address of Timeserver 2.

Default: None

tertiary Time Server

DNS hostname or IP Address of Timeserver 3.

Default: None

Interval between synchronization

Seconds between each resynchronization.

Default: 86400

Max time drift

Maximum time drift in seconds that a server is allowed to adjust.

Default: 600

Group interval

Interval according to which server responses will be grouped.

Default: 10

2.3. Events and Logging

2.3.1. Overview

The ability to log and analyze system activities is an essential feature of cOS Core. Logging enables not only monitoring of system status and health, but also allows auditing of network usage and assists in troubleshooting.

Log Message Generation

cOS Core defines a large number of different log messages, which are generated as a result of corresponding system events. Examples of such events are the establishment and tear-down of connections, receipt of malformed packets as well as the dropping of traffic according to filtering policies.

Log events are always generated for some aspects of cOS Core processing such as buffer usage, DHCP clients, High Availability and IPsec. The generation of events for some cOS Core subsystems, such as IP rule set usage, can be disabled or enabled as required.

Whenever an event message is generated, it can be filtered and distributed to a variety of Event Receivers, including Syslog and SNMP Trap receivers. Up to eight event receivers can be defined per firewall, with each receiver having its own customizable event filter.

Log Message Analysis Using InCenter

The InCenter Cloud service is a separate cloud based Clavister product that can be used to analyze log event messages from one or multiple cOS Core firewalls. The firewalls are configured to send log messages to the Clavister cloud and then a web browser can be used by the administrator to connect to the cloud and perform analysis on the stored messages and also to generate reports in PDF format. Reports can be generated on demand or automatically sent at specified intervals by email.

More information about the InCenter Cloud service can be found in the separate InCenter Cloud Administration Guide and companion InCenter Cloud Getting Started Guide. To begin using the InCenter cloud, request a subscription to the product by selecting the option after logging into the relevant MyClavister account.

The InCenter product is also available as an "on-premises" option so that the administrator can run the software on their own private server and the log messages from firewalls can be sent to this server instead of the cloud. This product is further described in the separate InCenter On-Premises Administration Guide. To obtain a license for this software, contact a Clavister sales office.

InCenter will not be discussed further in this section.

2.3.2. cOS Core Log Messages

Event Types

cOS Core defines several hundred events for which log messages can be generated. The events range from high-level, customizable, user events down to low-level and mandatory system events.

The conn_open event, for example, is a typical high-level event that generates an event message whenever a new connection is established, given that the matching security policy rule has defined that event messages should be generated for that connection.

An example of a low-level event would be the startup_normal event, which generates a mandatory event message as soon as the system starts up.

Message Format

All event messages have a common format, with attributes that include category, severity and recommended actions. These attributes enable easy filtering of messages, either within cOS Core prior to sending to an event receiver, or as part of the analysis after logging and storing messages on an external log server.

A list of all event messages can be found in the separate cOS Core Log Message Reference Guide. The beginning of that publication describes the design of log messages, and the various parameters that can appear in them.

Event Severity

The default severity of each log event is predefined and it can be, in order of highest to lowest severity, one of:

  • Emergency
  • Alert
  • Critical
  • Error
  • Warning
  • Notice
  • Info
  • Debug

By default, cOS Core sends any generated messages of level Info and above to any configured log servers but the level required for sending can be changed by the administrator. The Debug severity is intended for system troubleshooting only and is not normally used. All individual log messages with their meaning are described in the separate cOS Core Log Reference Guide.

Event Message Timestamping

When log messages are generated by cOS Core for sending to an external log server, they are always time stamped with the time expressed as UTC/GMT (Greenwich Mean Time). This makes it possible to compare events from different firewalls in different time zones which are set with different system times.

The exception to this is log messages which are displayed using the local Memlog feature. These are always time stamped with the current, local system time.

2.3.3. Types of Log Receiver

The event messages generated by cOS Core can be sent to one or more log receivers. For cOS Core to send log messages, it is necessary to configure in cOS Core one or more such log receiver objects. Each log receiver object is configured with properties that specify which events to capture and where to send them (for example, an Syslog external server).

cOS Core can distribute event messages to different types of receivers and these are enabled by creating any of the following types of Log Receiver objects.

  • Memory Log Receiver

    cOS Core has its own logging mechanism also known as the MemLog. This retains all event log messages in memory and allows direct viewing of recent log messages through the Web Interface.

    This is enabled by default but can be disabled.

    This receiver type is discussed further below in Section 2.3.4, The Memory Log Receiver (Memlog).

  • Syslog Receiver

    Syslog is the de-facto log message standard for logging events from network devices. If other network devices are already logging to Syslog servers, using Syslog for cOS Core log messages can simplify overall administration.

    This receiver type is discussed further below in Section 2.3.5, The Syslog Log Receiver.

  • Mail Alerting

    The Mail Alerting function allows a number of log messages to be grouped together into a single email which is then sent to a given email address via a designated SMTP server.

    This receiver type is discussed further below in Section 2.3.7, Mail Alerting.

  • InControl Log Receiver

    The separate Clavister InControl management product has the ability to receive and analyze log messages for one or many Clavister firewalls. Event messages sent to the InControl log receiver use the Clavister proprietary event message format for logging called FWLog. This format has a high level of detail and is suitable for allowing analysis of large amounts of log data.

    This receiver type is discussed further below in Section 2.3.8, The InControl Log Receiver (FWLog).

  • SNMP Traps

    An SNMP2c Event Receiver can be defined to collect SNMP Trap log messages. These receivers are typically used to collect and respond to critical alerts from network devices.

    This receiver type is discussed further below in Section 2.3.10, SNMP Traps.

2.3.4. The Memory Log Receiver (Memlog)

Overview

The Memory Log Receiver (also known as Memlog) is a feature in cOS Core that allows logging direct to memory in the firewall instead of sending messages to an external server. These messages can be examined through the standard user interfaces.

Memlog has Limited Capacity

Memlog memory available for new messages is limited to a fixed predetermined size. When the allocated memory is filled up with log messages, the oldest messages are discarded to make room for newer incoming messages. This means that MemLog holds a limited number of messages since the last system initialization and once the buffer fills they will only be the most recent. This means that when cOS Core is creating large numbers of messages in systems with, for example, large numbers of VPN tunnels, the Memlog information becomes less meaningful since it reflects a limited recent time period.

Memlog Timestamps

The timestamp shown is Memlog console output is always the local system time of the firewall. This is different from the timestamp on log messages sent to external log Receivers which are always time stamped with GMT time.

Disabling and Enabling Memlog

A single Memory Log Receiver object exists by default in cOS Core and memlog is therefore enabled by default. If logging to memlog is not required then the Memory Log Receiver object can be deleted and this type of logging will not occur. To re-enable memlog, add back the Memory Log Receiver object to the configuration. Only one instance of the Memory Log Receiver can exist at any one time.

Viewing and Saving the Memlog Buffer in the Web Interface

The entire memlog buffer can be viewed in the Web Interface by going to Status > Logging > System Log. This display is updated in real-time and it is also possible to save a snapshot of the buffer to a text file by pressing the Download Logs button.

InControl can also be used to view the memlog buffer and this is described further in the separate InControl Administrator Guide.

Real-time Log Event Monitoring on a CLI Console

It is possible to have log messages displayed on a CLI console in real-time as they are added to memlog by using the logsnoop CLI command. This command can also be used to extract logs from the memlog buffer based on filtering criteria which are not available when using the Web Interface. This command is discussed further in Section 2.3.6, Logsnoop.

2.3.5. The Syslog Log Receiver

Overview

Syslog is a common format for sending log data and is well suited to automated processing, filtering and searching.

Syslog Message Format

Most Syslog receivers expect each log entry to be prefaced with a timestamp and the IP address of the machine that sent the log data. For example:
Feb 5 2000 09:45:23 firewall.example.com
This is followed by the text the sender has chosen to send.
Feb 5 2000 09:45:23 firewall.example.com EFW: DROP:
Subsequent text is dependent on the event that has occurred.

In order to facilitate automated processing of all messages, cOS Core writes all log data to a single line of text. All data following the initial text is presented in the format name=value. This enables automatic filters to easily find the values they are looking for without assuming that a specific piece of data is in a specific location in the log entry.

[Note] Note: The Prio and Severity fields

The Prio= field in SysLog messages contains the same information as the Severity field for Clavister Logger messages. However, the ordering of the numbering is reversed.

Setting the Facility

The Facility property indicates to the server the type of program generating the Syslog message. If not specified, this is set to local0 (meaning a kernel message) by cOS Core. The facility name is commonly used as a filtering parameter by most syslog daemons.

Example 2.28. Enable Logging to a Syslog Host

This example enables logging of all events with a severity equal to Emergency or Alert to a Syslog server with the IPv4 address 192.168.6.1.

The facility name will also be set to local1 for this Syslog server.

Command-Line Interface

Device:/> add LogReceiver LogReceiverSyslog my_syslog
			IPAddress=192.168.6.1
			LogSeverity=Emergency,Alert
			Facility=local1

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: System > Device > Log Receivers > Add > Syslog Receiver
  2. Specify a name for the event receiver, in this example my_syslog
  3. Enter 192.168.6.1 as the IP Address
  4. Select local1 from the Facility list
  5. Select SeverityFilter and choose Emergency and Alert as the severities.
  6. Click OK
[Note] Note: The Syslog server itself must be correctly configured

The external Syslog server itself may have to be configured to correctly receive log messages from cOS Core. Refer to the documentation for the specific Syslog server being used in order to do this.

RFC-5424 Compliance

By default, cOS Core sends Syslog messages in a format that is suitable for most Syslog servers. However, some servers may require stricter adherence to the latest Syslog standard as defined by RFC-5424. For this reason, strict RFC-5424 compliance can be switched on by enabling the RFC5424 property of a Syslog receiver object in cOS Core.

InCenter Compliance

Where a syslog receiver is being configured to send log messages to Clavister InCenter (either the InCenter cloud service or an on-premises InCenter server) then the InCenter Compliance option should be enabled. This both enables RFC-5424 compliance as well as reducing the types of log messages sent to only those relevant for InCenter.

The InCenter product is discussed further in the separate InCenter Administration Guide and InCenter Cloud Administration Guide.

Setting the Hostname

In the header of every Syslog message there is a string field which is the Syslog hostname. By default, cOS Core always sets this to be the IP address of the sending interface.

If RFC-5424 compliance is enabled, it is also possible to set the hostname to a specific value. The example below shows how this is done.

Example 2.29. Enabling Syslog RFC-5424 Compliance with Hostname

This example enables logging of all events with a severity greater equal to Emergency or Alert to a Syslog server with the IPv4 address 192.168.5.1. RFC-5424 compliance will also be enabled with a hostname of my_host1 in the Syslog header.

Command-Line Interface

Device:/> add LogReceiver LogReceiverSyslog my_syslog
			IPAddress=192.168.5.1
			RFC5424=Yes
			Hostname=my_host1
			LogSeverity=Emergency,Alert

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: System > Device > Log Receivers > Add > Syslog Receiver
  2. Specify a name for the event receiver, in this example my_syslog_host
  3. Enter 192.168.5.1 as the IP Address
  4. Select an appropriate facility from the Facility list.
  5. Enable the option RFC-5424 Compliance.
  6. Enter my_host1 for the Hostname
  7. Select SeverityFilter and choose Emergency and Alert as the severities.
  8. Click OK

2.3.6. Logsnoop

As described in Section 2.3.4, The Memory Log Receiver (Memlog), there is a basic ability to monitor and view the log messages stored in the system memlog buffer through the Web Interface or InControl. The logsnoop CLI command extends this ability so that log messages generated by cOS Core can be viewed in any of the following ways:

  • Logsnoop can display log messages on the CLI console as they are generated in real-time and apply filtering to show only messages of interest to the administrator.

  • Logsnoop can look back in time and display the contents of the Memlog buffer which will contain a given number of the most recently generated log messages. Filtering can also be applied to this output to show only the messages of interest to the administrator.

  • The above two features can be combined so that both the contents of the memlog buffer and newly generated messages are displayed together.

Switching Real-time Logsnooping On and Off

To switch on snooping, the basic form of the command is:
Device:/> logsnoop -on
All log messages generated by cOS Core will now appear on the CLI console and each individual message is prefixed by the word "LOG". For example:
LOG: 2014-01-13 13:53:39 SYSTEM prio=Alert id=03200021 rev=1
event=demo_mode action=shutdown_soon shutdown=halt time=7200
The current status of logsnooping can be examined by entering the command with no parameters:
Device:/> logsnoop

Real time log snooping is enabled. Filter: All
To switch off snooping, use the command:
Device:/> logsnoop -off

Filtering Log Messages

Simply switching on snooping on a busy system can send an overwhelming number of messages to the console. It is usually advisable to add extra command parameters, either singly or in combinations, to filter the messages. The following examples illustrate using some of the many filtering parameters.

  • Filter by severity:

    Device:/> logsnoop -on -severity=warning

    Note that it is only possible to filter on a single severity level at once.

  • Filter by log ID number:

    Device:/> logsnoop -on -logid=1500001

    All the ID numbers can be found in the separate cOS Core Log Reference Guide. Leading zeros do not need to be specified.

  • Filter by Source IP:

    Device:/> logsnoop -on -srcip=192.168.1.10

    Here, the srcip field must exist in a log message for it to be displayed. For example, if the log message comes from an IP rule set entry the srcip field of a displayed message will contain the source IP for the connection that triggered the rule.

  • Filter by Source Interface:

    Device:/> logsnoop -on -srcif=If1

    Here, the srcif field must exist in a log message for it to be displayed. For example, if the log message comes from an IP rule set entry, the srcif field of a displayed message will contain the source interface for the connection that triggered the rule.

  • Filter by combining parameters:

    Device:/> logsnoop -on -severity=warning -srcip=192.168.1.10 -srcif=If1

    Any number of filtering parameters can be used together in a single logsnoop command.

A complete list of command parameters can be found in the entry of logsnoop in the separate cOS Core CLI Reference Guide. Alternatively, the following the CLI command can be used:

Device:/> help logsnoop

Filtering Wildcards and Free-text Filtering

When specifying filtering parameters, the following wildcards can be used:

  • * - An asterisk represents none or many characters.

  • ? - A question mark represents any single character.

For example, to find the text warning followed somewhere by udp, the command would be:

Device:/> logsnoop -on -pattern=*warning*udp*

The -pattern parameter specifies a free-text text filter for log messages. Wildcarding can also be used with other filtering parameters and is not limited to -pattern.

Limiting Log Message Numbers

Even when using filtering, the number of messages appearing at the console may still need to be reduced. The number of messages displayed can be limited in two ways:

  • Limit by frequency:

    Device:/> logsnoop -on -rate=5

    This will limit displayed log messages to a maximum of 5 per second.

  • Limit by total number:

    Device:/> logsnoop -on -num=100

    This will show only the first 100 log messages. After that, logsnoop is switched off.

Examining Memlog History

Memlog is the name of the local memory buffer that cOS Core uses to store a given number of the most recent log messages generated. It is enabled by default. When using logsnoop, examining memlog is done using the special parameter -source=memlog.

For example, the entire contents of the memlog buffer can be examined using the command:

Device:/> logsnoop -on -source=memlog

Even though the -on parameter must be used, this command does not switch on real-time logging and a matching command with the -off parameter is therefore not needed later.

Examining Memlog Plus New Log Messages

It is possible to examine the log history in memlog as well as switch on real-time log snooping at the same time. This is done with the command:
Device:/> logsnoop -on -source=both
This will display the contents of memlog and all subsequently generated messages. It is recommended to add further filtering parameters to the command.

If -source=both is used, a second command with the -off parameter will be needed later to switch off real-time logging.

Specifying a Time Range

The displayed log messages can be limited to those generated after a certain time with the parameter -starttime and/or those generated before a certain time with the -endtime parameter.

The time value itself can be specified in the following formats:

  • Using Date and Time

    The date and time together takes the format "yyyy-mm-dd hh.mm.ss" where the surrounding quotes are mandatory. For example: 2014-01-12 18:30:00. To look at log messages from 18:30 on the 12th of January onwards, the command would be:

    Device:/> logsnoop -on -starttime="2014-01-12 18:30:00"

    Note that the parameter value must be enclosed by quotes when both date and time are entered.

  • Using Date Only

    The date may be specified without the time and this takes the format yyyy-mm-dd, this time without enclosing quotes. For example: 2014-01-12. The time always defaults to 00:00:00 so this example is equivalent to 2014-01-12 00:00:00. To look at log messages for the whole of the 12th of January, the command would be:

    Device:/> logsnoop -on -starttime=2014-01-12 -endtime=2014-01-13

When not looking at memlog, setting the times will act as a way of turning logsnoop on and off at specified future times. If the -source=memlog option is used, the start and end times are used to look at a specific period in the memlog history.

2.3.7. Mail Alerting

Overview

By creating a Mail Altering object, cOS Core can be configured to send log messages in an email to a specified email address via a nominated external SMTP server. The Mail Altering object can be considered to be like other types of log receivers and it is possible to select the type of log messages that are sent.

The intended purpose of this feature is to provide a means of quickly alerting the administrator of any important cOS Core events so the selected level of severity for the events sent in this way will usually be very high.

Mail Alerting Object Properties

Many Mail Alerting object properties are the same as in other types of log receiver object and will not be listed again in this section. The object properties that are unique are the following:

  • SMTP Server

    The IP address of an SMTP server that will forward generated emails to the destination email address. This can also be an FQDN address object or a DNS resolvable FQDN (note that both require that a DNS server is configured in cOS Core).

  • Server Port

    The port number that the SMTP server listens on. This is set by default to the standard port number of 25.

  • SMTP Recipient

    A single destination email address for outgoing mails.

  • SMTP Sender

    A string which will be the sender name text in emails.

  • Subject

    A string which will be the subject text in emails.

  • Send Test Email

    This is not a property but a button in the Web Interface used to test the SMTP properties entered. It has a CLI equivalent and is explained further later in this section.

Event Trigger Mode

  • Single event trigger

    A single email is sent for at least each eligible event. The Event count threshold and Event count period values are not used with this option. However, when a single event is ready for sending it must wait for the Keep collecting before sending period so other eligible events can be added to the mail.

  • Rate of events trigger

    Multiple events are collected together into each email sent. The number of events collected before email sending is controlled by the values of the Event count threshold and Event count period properties.

  • Event count threshold

    An email is only sent if this number of events has occurred over the preceding number of minutes specified by the Event count period property. The trigger is therefore a given rate of events and not just an accumulation of events. Events that have already been included in a sent email are not counted again.

    When a Mail Alerting object is first created, this count is zero and is always reset to zero when cOS Core restarts. When an email is sent by the Mail Alerting, object, this count is also reset to zero.

    This property and the property Event count period are not used if Single event trigger is selected.

  • Event count period

    This is the number of minutes referred to in the Event count threshold description above and is the period of recent time in which events are being counted.

  • Send report emails

    When enabled, an email is always sent at least in the period of time specified by the Report email interval, even if the sent email has no events in it and even if the email is has no events in it or even if (in the case of the Rate of events trigger) the Event count threshold value has not been reached.

    This is not used in Single event trigger mode

  • Report email interval

    This is the maximum length of time in hours that can elapse before an email is sent even though the email might contain no events. Typically, this value might be set to 24 so that the Mail Alerting object generates at least one email a day even though it might be empty. This can inform the administrator that the system is up and highlight any events of interest.

  • Report email subject

    When a report email is sent, this will be the subject line of the email. This allows the administrator to easily distinguish if an email is a report email or an email generated by a trigger.

    The property must have a string value and cannot be left empty.

  • Keep collecting before sending

    If an email is ready to be sent, cOS Core will wait this number of minutes before sending it. Any new events that occur while the email is waiting to be sent are added to the pending email.

    This can be used in either triggering mode. If the mode is Single event trigger, any new events during the period after the initial triggering event will be added to the email.

    cOS Core only sends events in one minute intervals so this means that even is this property is set to zero, there can still be a delay before the email is sent and extra events can still be added during this delay.

  • Minimum time between emails

    Consecutive sent emails cannot have less than this amount of elapsed time between them. The value of this property can prevent emails being sent too often.

    If an email is ready to send but cannot because it is within this period of time, any new events will be added to the email until this period has expired.

Advanced Options

  • Identity

    This string parameter identifies the SMTP client in the HELO or EHLO command sent to the SMTP server by cOS Core. If this property is not set, cOS Core will set this automatically to the IPv4 address of the cOS Core interface that sends to the SMTP server.

  • X-Mailer

    This is the name of the software that is communicating with the SMTP server. This is optional and is left blank by default.

Mail Alerting Processing Flow

To better explain the settings for the event trigger properties, consider the following example: a Mail Alerting object has been configured in cOS Core and the Multiple events trigger option has been selected with an Event count period value of 2 minutes and an Event count threshold value of 3 events (in other words 3 events must occur in a 2 minute window for an email to be sent).

Assume that since sending its last email, 6 log events occur that are eligible for mailing and these occur over a 6 minute period of time. The diagram below divides the 6 minutes into 2 minute sections for clarity and shows when the events occur.

The processing flow is as follows:

  1. cOS Core starts counting the events from zero before the 1st event.

  2. The 3rd event occurs, reaching the threshold. However, the 1st event is outside the 2 minute time window and only the 2nd and 3rd events are inside the time period so an email is not sent.

  3. This is also the case for the 4th and 5th events. There are not enough other events in the previous 2 minutes for either to reach the threshold of 3.

  4. Only when the 6th event occurs is the threshold of 3 events reached within the previous 2 minutes and an email is sent (after waiting the Keep collecting before sending number of minutes during which time any new log events will be added to the email).

  5. cOS Core drops the 1st, 2nd and 3rd events so these are not included in the email.

  6. The event counter is reset to zero and event counting within the Event count period begins again.

Sending Test Emails

The mail alerting feature has a Send Test Email function to send a test email to the server. This is done by pushing the Send test email button in the Web Interface. In the CLI, a test email is sent with the following command:
Device:/> smtp -sendmail -logreceiver=<mail-alerting-object-name>
The body of the test email will contain text which is similar to the following:
This is message #1 sent to test the Mail Alerting object "my_mail_alert"
The number "#1" in the message will increment every time a test mail is sent from this log receiver.

In the Web Interface, the test button can be pushed even while the Mail Alerting object is being created and before the configuration change is activated and saved. This is not true with the equivalent CLI test mail function.

Sending to Multiple Email Addresses

More than one Mail Alerting object can be created so that log messages are sent to multiple email addresses. However, if the same log message information is being sent to multiple email addresses then it is not recommended to create multiple Mail Alerting objects for this purpose. Instead, create a mailing list email address on the SMTP server so that a mail sent to that address is sent to multiple email recipients.

Mail Size Limit

In order to limit the available memory that cOS Core uses for buffering log messages and building the email body, a limit is set on the email size. This limit is 8 Kbytes. When this limit is reached but the email had not yet been sent, any new log messages will be dropped. If events are dropped, the following message added to the email body:
 message(s) have been discarded because of because of email body size limit
If the available memory is completely used up while building the email, this message will have a slightly different text to indicate that. If messages are dropped repeatedly, it is an indication that either the event filter should be made more restrictive or that the emails should be sent more often.

If more than one Mail Alerting object is created, each will have its own piece of memory allocated for building emails.

Example 2.30. Setting up a Mail Alerting Object

This example configures an Mail Alerting object called my_smtp_receiver so that all events with a severity equal to Emergency or Alert are sent out in an email.

It is assumed that the recipient email address is admn@example.com and that the SMTP server address is 203.0.113.10. The default values for the threshold and associated properties are used.

All other configurable properties will be left at their default value.

Command-Line Interface

Device:/> add LogReceiver MailAlerting my_mail_alert
			IPAddress=203.0.113.10
			Receiver=admn@example.com
			Sender=device1
			Subject="Log message summary"
			LogSeverity=Emergency,Alert

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: System > Device > Event Receivers > Add > Mail Alerting
  2. Now enter:
    • Name: my_mail_alert
    • SMTP Server: 203.0.113.10
    • SMTP Receiver: admin@example.com
    • SMTP Sender: device1
    • Subject: Log message summary
  3. Under SeverityFilter make Emergency and Alert as the selected severities.
  4. Click OK

2.3.8. The InControl Log Receiver (FWLog)

The Clavister Logger refers to the proprietary Clavister logging method that uses the proprietary FWLog message format for sending log data. A receiving server for this format is also sometimes referred to as a FWLog Receiver. The ILA server component of the separate Clavister InControl™ management product is such a logger and this is the primary usage of the FWlog format.

Configuring the log receiver can be done in InControl or it could be done through the Web Interface or CLI.

Example 2.31. Enabling Logging to the Clavister Logger

This example enables logging of all events to a InControl ILA server with a severity equal to Alert or Emergency to the Clavister Logger (FWLog Receiver) with IPv4 address 192.168.4.1 listening on port 999 (the default).

This same procedure could also be performed through InControl.

Command-Line Interface

Device:/> add LogReceiver LogReceiverFWLog my_fwlog
			IPAddress=192.168.4.1
			Port=999
			LogSeverity=Emergency,Alert

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: System > Device > Log Receivers > Add > InControl Log Receiver (FWLog)
  2. Specify a name for the event receiver, in this example my_fwlog
  3. Enter 192.168.4.1 as the IP Address
  4. Select SeverityFilter and choose Emergency and Alert as the severities.
  5. Click OK

2.3.9. Severity Filter and Message Exceptions

For each log receiver it is possible to impose rules on what log message categories and severities are sent to that receiver. It is also possible to lower or raise the severity of specific events.

The Severity Filter

The Severity Filter is a means of specifying what severities, if any, are sent to the receiver. By default, all log messages except Debug are sent. This can be restricted further so, for example, only Emergency, Alert and Critical messages are sent.

Log Message Exceptions

After the severity filter is applied, any Log Message Exceptions are applied to generated messages. There can be more than one message exception for a log receiver and each consists of the following:

  • Category and ID

    This specifies the log messages that will be affected by the exception. If the ID number of the log message is not specified then all log messages for the specified category will be included.

    The ID of specific log messages can be found in the Log Reference Guide.

  • Type

    This can be one the following:

    1. Exclude - This will exclude the specified log message(s) even if they are allowed by the severity filter.

    2. Include - This will include the specified log message(s) even if they are excluded by the severity filter.

      In addition, the Severity of the included message(s) can be specified. If this is set to Default the original severity is used. Otherwise, the severity is set to the specified value. This provides the ability to raise (or lower) the severity of specific log messages.

2.3.10. SNMP Traps

The SNMP protocol

Simple Network Management Protocol (SNMP) is a means for communicating between a Network Management System (NMS) and a managed device. SNMP defines 3 types of messages: a Read command for an NMS to examine a managed device, a Write command to alter the state of a managed device and a Trap which is used by managed devices to send messages asynchronously to an NMS about a change of state.

SNMP Traps in cOS Core

cOS Core takes the concept of an SNMP Trap one step further by allowing any event message to be sent as an SNMP trap. This means that the administrator can set up SNMP Trap notification of events that are considered significant in the operation of a network.

The file CLAVISTER-TRAP.mib defines the SNMP objects and data types that are used to describe an SNMP Trap received from cOS Core.

This file is contained within cOS Core itself and can be extracted to a management computer's local disk either using the Web Interface or Secure Copy (SCP). Doing this is described further in Section 2.5, SNMP.

There is one generic trap object called OSGenericTrap, that is used for all traps. This object includes the following parameters:

  • System - The system generating the trap.
  • Severity - Severity of the message.
  • Category - What cOS Core subsystem is reporting the problem
  • ID - Unique identification within the category.
  • Description - A short textual description.
  • Action - What action is cOS Core taking.

This information can be cross-referenced to the separate Log Reference Guide using the ID.

Using SNMP2c or SNMPv3

cOS Core supports the sending of SNMP traps using either SNMP2c or SNMPv3. These SNMP protocol versions are very similar except that SNMPv3 can provide encryption and/or authentication and is therefore the preferred version from a security standpoint.

Configuring Event Receivers

The SNMP trap feature is configured by defining either an SNMP2c Event Receiver or an SNMPv3 Event Receiver object.

Repeat Count

Both the SNMP2c and SNMPv3 log receiver objects have a property called Repeat Count which specifies how many times any single event will be sent to the receiver. The default value for this is zero which means that every time a particular event occurs, a message will be sent to the receiver.

If, for example, the Repeat Count property is set to 3 then a particular event will be sent only for the first three times that it occurs since the last system startup (a system restart will initialize the count). This can prevent a constantly repeating event sending an unnecessary quantity of the same message to the receiver.

Interface Up/Down Events

Both the SNMP2c and SNMPv3 log receiver objects have a property called Use interface link up/down traps which can be disabled or enabled and is disabled by default. If enabled, any change in the online or offline status of any Ethernet interface in the configuration will cause an event to be sent to the receiver.

SNMPv3 Security Options

When using SNMPv3, there are three levels of security that can be chosen:

  • noAuthNoPriv - This disables both authentication and encryption (the default).

  • authNoPriv - This enables authentication using SHA-1 but disables encryption. Authentication is performed using the Password property which must be specified.

  • authPriv - This enables authentication using SHA-1 and enables encryption using AES. Authentication and encryption are performed using the Password property which must be specified.

Example 2.32. Configuring an SNMPv3 Event Receiver

This example configures an SNMPv3 Event Receiver receiver in cOS Core that will receive SNMP traps for all events with a severity of Emergency or Alert

Both authentication and encryption will be enabled and the receiver is assumed to have an IPv4 address of 192.168.3.1.

Command-Line Interface

Device:/> add LogReceiver EventReceiverSNMPv3 my_snmp_receiver
			IPAddress=192.168.3.1
			Username=my_name
			Password=myunguessablepassword
			Snmp3SecurityLevel=authPriv
			LogSeverity=Emergency,Alert

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: System > Event Receivers > Add > SNMPv3 Event Receiver
  2. Specify a name for the object, in this example my_snmp_receiver
  3. Enter 192.168.3.1 for the IP Address
  4. Choose the Security Level option of authPriv
  5. Enter my_name for Username
  6. Enter myunguessablepassword for Password
  7. Select SeverityFilter and choose Emergency and Alert as the severities.
  8. Click OK

2.3.11. Advanced Log Settings

The following advanced settings for cOS Core event logging are available to the administrator:

Send Limit

This setting specifies the maximum log messages that cOS Core will send per second. This value should never be set too low as this may result in important events not being logged. When the maximum is exceeded, the excess messages are dropped and are not buffered.

The administrator must make a case by case judgment about the message load that log servers can deal with. This can often depend on the server hardware platform being used and if the resources of the platform are being shared with other tasks.

Default: 2000

Alarm Repeat Interval

The delay in seconds between alarms when a continuous alarm is used. This setting is not available in virtual environments. As discussed in Section 2.4.4, Hardware Monitoring, the log messages generated by hardware monitoring are continuous and this setting should be used to limit the frequency of those messages.

Minimum 0, Maximum 10,000.

Default: 60 (one minute)

2.4. Monitoring

The real-time performance of cOS Core can be monitored in a number of ways. They are:

  • Using the real-time monitoring functionality in InControl.

  • cOS Core real-time monitor alerts.

  • The cOS Core link monitor.

  • Monitoring through an SNMP client.

  • Hardware monitoring for specific hardware models.

2.4.1. Real-time Monitoring Using InControl

Most cOS Core status and operational statistics are available to InControl for graphical display in a variety of display formats. This is achieved by InControl routinely polling cOS Core to gather the latest values of operational parameters. Note that the values from some subsystems, such as Web Content Filtering, are not available to InControl.

The following counters are available:

Throughput Statistics

CPU – The percentage load on the firewall CPU.

Forwarded bps - The number of bits forwarded through the firewall per second.

Forwarded pps - The number of packets forwarded through the firewall per second.

Buf use – Percentage of firewall packet buffers used.

Conns – The number of connections opened via Allow or NAT rules. No connections are opened for traffic allowed via FwdFast rules; such traffic is not included in this statistic.

Timers – The amount of timers used by the system.

Total mem usage – Percentage of the RAM memory that is currently being used.

Connection Rate Statistics

Conns opened per sec – The number of connections opened per second.

Conns closed per sec – The number of connections closed per second.

State Engine Statistics

ICMP Connections - Total number of ICMP connections.

UDP Connections - Total Number of UDP connections.

OPEN TCP - Total number of open TCP connections.

TCP SYN - Total number of TCP connections in the SYN phase.

TCP FIN - Total number of TCP connections in the FIN phase.

Other - Total number of other connection types such as IPsec.

TCP Buffer Statistics

Total small receive window usage - The number of small TCP receive windows currently being used.

Total large receive window usage - The number of large TCP receive windows currently being used.

Total small send window usage - The number of small TCP send windows currently being used.

Total large send window usage - The number of large TCP send windows currently being used.

Rule Usage Statistics

Each of the rules in a rule set has a counter associated with it which has the same name as the rule type. These counters indicate the number of matches that have taken place for each rule. The rule sets that exist are:

  • IP Rule Sets
  • Routing Rule Sets
  • DHCP Rule Sets
  • User Authentication Rule Sets

Interface/VLAN/VPN Statistics

Rx/Tx Ring counters - Some drivers support plotting of FIFO-errors, saturation, flooding and other values depending on the driver.

Pps counters – The number of packets received, sent and summed together.

Bbs – The number of bits received, sent and summed together.

Drops – The number of packets received by this interface that were dropped due to rule set decisions or failed packet consistency checks.

IP errors – The number of packets received by this interface that were mutilated so badly that they would have had difficulty passing through a router to reach the Clavister firewall. They are therefore unlikely to be the result of an attack.

Send Fails – The number of packets that could not be sent, either due to internal resource starvation caused by heavy loading or hardware problems or congested half-duplex connections.

Frags received – The number of IP packet fragments received by this interface.

Frag reass – The number of complete packets successfully reassembled from the fragments received.

Frag reass fail – The number of packets that could not be reassembled, either due to resource starvation, illegal fragmentation, or just packet loss.

Active SAs - Current active number of SAs in use (VPN only).

Pipe Statistics

Total Pipe Statistics

Num users – The current number of users, as defined by the grouping settings of each pipe, being tracked in the pipes system. Note that this value corresponds to the number of users active in each time slice of 1/20th of a second, and not to the number of users having "open" connections.

Per Pipe Statistics

Num Users - The current number of users as above but on a per pipe basis.

Current bps – The current throughput of the pipe, in bits per second, per precedence and as a sum of all precedences.

Current pps – The current throughput of the pipe, in packets per second, per precedence and as a sum of all precedences.

Reserved bps – The current bandwidth allocated to each precedence; lower precedences are not allowed to use this bandwidth. Note that there is no reserved bandwidth for precedence 0, as it is simply given what is left of the total limit after all higher precedence reservations are subtracted.

Dyn limit bps – The current bandwidth limit applied to the respective precedences. This is related to the Reserved bps statistic, but is usually higher, as it shows how much bandwidth is left after higher precedence reservations have been subtracted from the total limit.

Delayed Packets – The number of times packets have been delayed as a result of a pipe, precedence, or pipe user having used up its allotted bandwidth. Note that one single packet may be delayed several times; if a pipe is really full, this count may exceed the number of packets actually passing through the pipe.

Dropped Packets – The number of packets dropped. Packets are dropped when cOS Core is running out of packet buffers. This occurs when excessive amounts of packets need to be queued for later delivery. The packet dropped is always the one that has been queued the longest time globally, which means that the connection suffering from packet loss will be the one most overloading the system.

Dyn User Limit bps – The current bandwidth limit per user of the pipe. If dynamic bandwidth balancing is enabled, this value may be lower than the configured per-user limits.

DHCP Server Statistics

Total Rejected requests – Total number of rejected packets (all rules).

Per Rule Statistics

Usage – Number of used IPs in the pool.

Usage (%) – Above value calculated as a percentage.

Active Clients – Number of currently active clients (BOUND).

Active Clients (%) – Above value calculated as a percentage.

Reject requests – Number of rejected requests.

Total number of leases – Total number of leases in the pool.

DHCP Relay Statistics

Total active relayed clients - Number of active relays in the Clavister firewall.

Ongoing transactions - DHCP transactions in the firewall.

Total rejected - Number of packets rejected by the DHCPRelay.

Active relayed clients - Number of active relays that uses this specific rule.

Rejected packets per rule - Number of packets rejected from clients using this rule.

General ALG Statistics

Total ALG sessions - Total number of ALG sessions.

Total connections - Total number of connections.

Total TCP Streams - Total number of TCP streams.

HTTP ALG, Web Content Filtering and Antivirus Statistics

Total requests - Total number of requests.

Total allowed - Total number allowed.

Total blocked - Total number of blocks.

URLs requested - Requests per URL category.

URLs allowed - Allowed requests per URL category.

URLs rejected - Rejected requests per URL category.

SMTP ALG DNSBL Statistics

Total Sessions Checked - Total number of URLs checked.

Total Sessions Spam - Total number of URLs found to be Spam.

Total Sessions Dropped - Total number of sessions dropped.

SMTP ALG DNSBL Server Statistics

For each DNSBL server:

Total Sessions Checked - Total number of URLs checked by server.

Total Sessions Matched - Total number of URLs found to be Spam by server.

Total Failed Checks - Total number of checks where no response was received.

User Authentication Statistics

PPP – Number of PPP authenticated users.

HTTPAuth – Number of HTTP authenticated users.

Secure HTTP – Number of secure HTTP authenticated users.

XAUTH – Number of XAUTH authenticated users.

Link Monitor Statistics

PPP – Number of PPP authenticated users.

Packets lost/sec – Number of packets lost per second in polling.

Short Term Loss – % of short term packet loss.

Hosts Up – % of hosts available.

Packet Reassembly Statistics

Input Drops – Number of packet drops on input.

Load Factor – Loading of reassembly subsystem.

Allowed Buffers – Allowed buffers per connection.

IP Pools Statistics

Prepared – Number of prepared IP addresses.

Free – Number of addresses free.

Used – Number of addresses used.

Misses – Number of requests not met.

High Availability Statistics

Interface Queue – Size of the queue used for the sync interface.

Queue Usage Packets – Amount of the queue used in packets.

Queue Usage Bytes – Amount of the queue used in bytes.

Packets Sent – Number of packets sent on Sync.

Resent Packets – Number of packets resent on Sync.

2.4.2. Real-time Monitor Alerts

A number of cOS Core statistical values can be monitored through the Real-time Monitoring feature. Real-time Monitor Alert thresholds can be specified in cOS Core for any of these monitored values so that they can have a maximum and/or a minimum numerical threshold.

Should a specified maximum or minimum threshold be crossed, cOS Core will automatically generate a log message which will be sent to all configured log receivers. All such log messages belong to the REALTIMEMONITOR message category which has the identity number 54.

The log message ID number will therefore take the form 054XXXXX where XXXXX represents the position of the statistic generating the event in the list of alert rules. A log message with identity 05400003, for example, means log ID number 3 in this category number of 054.

However, the administrator can customize the log message by specifying an integer value for the optional property Log Message ID. This value will then replace the statistic position value in the generated 054XXXXX ID.

Monitor Alert Rules

Each Monitor Alert Rule consists of the following fields:
Name
User assigned name for the rule.
Sample time
The interval in seconds between checking the statistic.
Low threshold
The lower threshold (if specified).
High threshold
A higher threshold (if specified).
Continuous
This determines if an event is also generated when the threshold is crossed in the other direction. In other words, the statistic moves back to within acceptable limits. This field can be Yes or No.
Backoff
The minimum number of seconds between consecutive Monitor Threshold Rule log messages. This value can be useful in preventing a flood of log messages when a statistic is repeatedly passing a threshold and then receding from it again.

2.4.3. The Link Monitor

Overview

The Link Monitor is a feature in cOS Core that allows monitoring of the connectivity to one or more IP addresses external to the Clavister firewall. This monitoring is done using standard ICMP "Ping" requests and allows cOS Core to assess the availability of the network pathways to these IP addresses. The administrator can select one of a number of actions to occur should a pathway appear to be broken for some reason.

Link Monitor Actions

If sufficient replies are not received to link monitor polling, cOS Core makes the assumption that the common link to those IP address is down and can then initiate one of 3 configurable actions:

  • A reconfigure operation.

  • A High Availability (HA) cluster failover.

  • An HA cluster failover followed by a reconfigure operation.

Monitoring Multiple Hosts

A single Link Monitor object can monitor a single host or it can monitor multiple hosts. When monitoring a single host, either a failure of the host or the connection to the host can cause the monitor's action to be triggered.

When multiple hosts are specified for a single Link Monitor object, more than 50% of the hosts have to be unreachable for the object's action to trigger. This is useful when it is the availability of the connection to the hosts that is important and not the hosts themselves. If it is the availability of a single host that is important then a Link Monitor object should be created that monitors only that host.

The Link Monitor Reconfigure is Different

The reconfigure that can be triggered by the link monitor has one special aspect to it. The link monitor reconfigure has the additional action of restarting all interfaces. This means that if there is a problem related to a particular Ethernet NIC, perhaps due to overload, then this can be cleared by interface initialization. This results in only a momentary delay in throughput while the reconfigure takes place.

Link Monitor Uses

The Link Monitor is useful in two distinct scenarios:

  • An external device develops an occasional problem with its link to the firewall and the physical link needs to be renegotiated. Such problems can occur sometimes with some older equipment such as ADSL Modems. For this scenario action 1. Reconfigure should be selected.

    A reconfigure means that the cOS Core configuration will be reloaded. All connections and states are saved but reloading means all traffic is suspended for a short period and all interface links to external devices are renegotiated.

  • In an HA cluster setup, the link from the master to the external Internet (or other part of a network) can be continually monitored so that should the link fail, the slave will take over (assuming that the slave has a different physical connection to the monitored address). The action chosen for HA should be either 2. Failover or 3. Failover and reconfigure.

    If the first action option 1. Reconfigure is chosen in an HA cluster, then the reconfigure will also cause a failover since it will temporarily suspend the master's operation while the reconfigure takes place and the slave will take over when it detects this inactivity. If reconfiguration with failover is desirable, it is better to select the option 3. Failover and reconfigure since this performs the failover first and is nearly instantaneous with almost no traffic interruption. Reconfiguration first is slower and results in some traffic interruption.

    To preserve all tunnels in a VPN scenario, it is best to choose the 2. Failover option since a reconfiguration can cause some tunnels to be lost.

Link Monitoring with HA Clusters

The most common use for link monitoring is in the HA cluster scenario described above. It is important that the master and slave do not duplicate the same condition that triggered the link monitor. For example, if a particular router connected to the master firewall was being "pinged" by link monitoring, the slave should not also be connected to that router. If it is, the continued triggering of a reconfiguration by the link monitor will then cause the slave to failover back to the master, which will then failover back to the slave again and so on.

If it is important to not allow a failover during reconfiguration of the active unit in an HA cluster then the advanced setting Reconf Failover Time should be set to a value which is neither too low or too high.

Reconf Failover Time controls how long the inactive unit will wait for the active unit to reconfigure before taking over. Setting this value too low will mean the inactive unit does not wait long enough. Setting the value too high could mean significant downtime if the active unit fails during reconfiguration and the inactive unit needs to take over.

More information on clusters can be found in Chapter 12, High Availability.

IPsec Tunnels and HA Clusters

If the triggered link monitor action is a failover or failover and reconfigure, any IPsec tunnels are automatically closed and the tunnel SAs deleted at both ends. After the failover takes place the following will occur:

  • If the IPsec tunnel was a LAN-to-LAN tunnel, it will be automatically reestablished provided traffic flows within the keepalive time specified for the tunnel.

  • Any IPsec tunnels from external clients will be lost and will not be reestablished automatically. The client must initiate a new connection.

Link Monitor Object Properties

A Link Monitor configuration object has the following properties:

Action
Specifies which of the 3 actions described above cOS Core should take.
Addresses

This property specifies the IP address of one or more hosts to monitor. For multiple hosts, if half (50%) or more respond then there is assumed to be no problem. If less than half of multiple hosts do not respond, cOS Core assumes that there is a link problem. With a single host, it either responds or it doesn't so the 50% rule is not relevant.

A host is not used in this 50% calculation until cOS Core has been able to reach it at least once since the last cOS Core reconfiguration or full restart. This means that an unreachable host can be responsible for triggering an action once but not twice.

A group of three hosts, where one has been unreachable since the last reconfiguration, will therefore be treated as a two-host group until the third becomes reachable. This also means that if a problem triggers an action and the problem is not solved, cOS Core will not attempt to repeat the same action until the problem is solved and the hosts are again reachable.

Max Loss
A single host is considered unreachable if this number of consecutive ping responses to that host are not replied to. The default value is 7.
Initial Grace Period
Do not allow the link monitor to trigger an action for this number of seconds after the last reconfiguration. This avoids false positives during initial link negotiation. The default value is 45 seconds.
Ping Interval
The number of milliseconds between pings sent to hosts. The default value is 250.
Routing Table
This is the routing table used for looking up the route for the host IP addresses. The default is the main routing table.
Use Shared IP
This is only used when monitoring in a HA cluster. It allows the link monitor pings to be sent from the shared IP address instead of sending using the individual IPs of each unit. This is useful if public IPv4 addresses are not available for each unit in the cluster. See also Section 12.6, Link Monitoring and HA.

Example 2.33. Link Monitor Setup

This example creates a Link Monitor object that will monitor the availability of the host found at the IPv4 address my_host. It is assumed this IPv4 address is already defined in the cOS Core address book.

The action for the monitor is HA Failover if it detects that the host is unavailable.

Command-Line Interface

Device:/> add LinkMonitor Action=HAFailover Addresses=my_host

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: System > Device > Link Monitors > Add > Link Monitor
  2. Enter the following:
    • Action: HA Failover
    • Addresses: my_host
  3. Click OK

2.4.4. Hardware Monitoring

Feature Availability

Certain Clavister hardware models allow the administrator to use the CLI to query the current value of various hardware operational parameters such as the current temperature inside the firewall. This feature is referred to as Hardware Monitoring.

Configuring and performing hardware monitoring can be done either through the CLI or through the Web Interface. The feature is not available when cOS Core is running in a virtual environment.

Enabling Hardware Monitoring

The System > Device > Hardware Monitoring section of the Web Interface provides the administrator with the following settings for enabling hardware monitoring when it is available:

Enable Sensors

Enable/disable all hardware monitoring functionality.

Default: Disabled

Poll Interval

Polling interval for the Hardware Monitor which is the delay in milliseconds between readings of hardware monitor values. Minimum value: 100, Maximum value: 10000.

Default: 500

Using the hwm CLI Command

To get a list of the current values from all available sensors, the following command can be used:
Device:/> hwm -all
This can be abbreviated to:
Device:/> hwm -a
Some typical output from this command for two temperature sensors is shown below:
Device:/> hwm -a
		
Name               Current value (unit)
---------------   --------------------
SYS Temp        =    44.000 (C)     (x)
CPU Temp        =    41.500 (C)     (x)

[Note] Note

The "(x)" on the left side of the sensor listing indicates that the sensor is enabled.

The -verbose option displays the current values plus the configured ranges. Some typical output from this command is shown below:

Device:/> hwm -a -v

4 sensors available
Poll interval time = 500ms

Name [type][number] = low_limit] current_value [high_limit (unit)
-----------------------------------------------------------------
 SYS Temp         [TEMP  ][  0] =    44.000]    45.000 [ 0.000 (C)
 CPU Temp         [TEMP  ][  1] =    42.000]    42.500 [ 0.000 (C)
 AUX Temp         [TEMP  ][  2] =    41.000]    43.000 [ 0.000 (C)
 CPU Fan1         [FANRPM][  1] =  6125.000]  6250.000 [ 0.000 (RPM)

Time to probe sensors: 2.980000e-05 seconds

Each physical attribute listed on the left is given a minimum and maximum range within which it should operate. When the value returned after polling falls outside this range, cOS Core automatically generates an HWM log message that is sent to the configured log servers. If an SNMP trap receiver is one of the receivers configured, an SNMP trap is sent.

The temperature sensor names should be interpreted as follows:

  • The SYS temperature should be used as an indication of the overall temperature inside the entire hardware unit.

  • The CPU temperature relates specifically to the unit's central processor which can be lower than the overall temperature due to the method of cooling.

  • The AUX sensor is found in some other arbitrary location and should be used as an alternative indication of the overall temperature. Hotspots can cause variations between this and the SYS temperature.

[Note] Note: Sensors can differ depending on hardware type

Each hardware model can have a different set of sensors in different locations and with different operating ranges. The above output example and its values are for illustration only.

Setting the Minimum and Maximum Range

The minimum and maximum values shown in the output from the hwm command are set through the Web Interface by going to System > Device > Hardware Monitoring > Add and selecting the hardware parameter to monitor. The desired operating range can then be specified.

A sensor is identified in the Web Interface by specifying a unique combination of the following parameters:

  • Type

    This is the type of sensor shown in the CLI output above and is presented as a list of choices in the Web Interface. For example, Temp.

  • Sensor

    This is the number of the sensor as shown in the CLI output above. For example, the SYS Temp number is 0.

  • Name

    This is the Name of the sensor as shown in the CLI output above. For example, SYS Temp.

  • Enabled

    An individual sensor can be enabled or disabled used this setting. When enabled, an "(x)" is displayed next to the sensor in the output from the hwm command.

Controlling the Event Sending Frequency

The maximum frequency of log event generation when hardware monitoring values fall outside their preset range can be limited using the AlarmRepeatInterval setting in the LogSettings object. This setting is used because the monitored values are continuous.

For example, to change the interval from the default of 60 seconds to a new value of 900 seconds, use the CLI command:

Device:/> set Settings LogSettings AlarmRepeatInterval=900

This means that a new event message must now wait for 900 seconds after the previous one has been sent.

All the options for LogSettings can be found in Section 2.3.11, Advanced Log Settings.

Sensors for Clavister Products

The following are the available sensors for Clavister hardware products. Some of the products listed are no longer sold but they are included for completeness.

Note that all fan speeds are given in RPM and all temperatures are given in degrees Centigrade.

  • NetWall X8
Sensor Name Sensor Type Sensor Number Minimum Limit Maximum Limit
CPUTemp TEMP 0 0 65
SysTemp TEMP 1 65 65
  • NetWall E5

    Monitoring is not available.

  • NetWall E7

    Monitoring is not available.

  • NetWall E10
Sensor Name Sensor Type Sensor Number Minimum Limit Maximum Limit
CPUTemp TEMP 0 0 80
  • NetWall E80
Sensor Name Sensor Type Sensor Number Minimum Limit Maximum Limit
CPUTemp TEMP 0 0 80
  • NetWall E80B
Sensor Name Sensor Type Sensor Number Minimum Limit Maximum Limit
CPUTemp TEMP 0 0 80
  • NetWall W3
Sensor Name Sensor Type Sensor Number Minimum Limit Maximum Limit
Right_CPUFan1 FANRPM 2 4000  
Right_CPUFan2 FANRPM 0 4000  
Right_CPUFan3 FANRPM 3 4000  
Right_PSUFan FANRPM 1 4000  
SysTemp1 TEMP 2   70
SysTemp2 TEMP 3   70
CpuTemp TEMP 512   80
PSU GPIO 256 1  
  • NetWall W5
Sensor Name Sensor Type Sensor Number Minimum Limit Maximum Limit
Right_CPUFan1 FANRPM 2 4000  
Right_CPUFan2 FANRPM 0 4000  
Right_CPUFan3 FANRPM 3 4000  
Right_PSUFan FANRPM 1 4000  
Left_CPUFan1 FANRPM 6 4000  
Left_CPUFan2 FANRPM 4 4000  
Left_CPUFan3 FENRPM 7 4000  
Left_PSUFan FENRPM 5 4000  
SysTemp1 TEMP 2   70
SysTemp2 TEMP 3   70
CpuTemp TEMP 512   80
Right_PSU GPIO 256 0 2
Left_PSU GPIO 257 0 2
  • NetWall W20 and W30
Sensor Name Sensor Type Sensor Number Minimum Limit Maximum Limit
CPUFan FANRPM 1 1500  
SysTemp TEMP 0   70
CpuTemp TEMP 256   80
  • NetWall W20B
Sensor Name Sensor Type Sensor Number Minimum Limit Maximum Limit
CPUTemp TEMP 0 0 80
  • NetWall W40
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
  • NetWall W50
Sensor Name Sensor Type Sensor Number Minimum Limit Maximum Limit
Left_PSU GPIO 0 1 0
Right_PSU GPIO 1 1 0
SysTemp1 TEMP 256 0 70
SysTemp2 TEMP 257 0 70
CpuTemp1 TEMP 260 0 80
FanModule1_1 FANRPM 262 1500  
FanModule1_2 FANRPM 263 1500  
FanModule2_1 FANRPM 260 1500  
FanModule2_2 FANRPM 261 1500  
FanModule3_1 FANRPM 258 1500  
FanModule3_2 FANRPM 259 1500  
FanModule4_1 FANRPM 256 1500  
FanModule4_2 FANRPM 257 1500  
CpuTemp2 TEMP 512 0 80
  • NetWall 100 Series
Sensor Name Sensor Type Sensor Number Minimum Limit Maximum Limit
CPUTemp TEMP 0 0 80
  • NetWall 300 Series
Sensor Name Sensor Type Sensor Number Minimum Limit Maximum Limit
System Vcore Internal VOLT 0 0.494 1.744
System 12V Internal VOLT 1 11.4 13.9
System 5V Internal VOLT 2 4.8 5.8
System 3.3V Internal VOLT 3 2.976 3.632
System CMOS Battery VOLT 4 2.704 3.632
System FAN Speed FANRPM 5 1400 14000
System Temperature 1 TEMP 6 0 71
System Temperature 2 TEMP 7 0 75
System Temperature 3 TEMP 8 0 85
CPU Core Temperature TEMP 9 0 85
  • NetWall 500 Series
Sensor Name Sensor Type Sensor Number Minimum Limit Maximum Limit
System Vcore Internal VOLT 0 0.494 1.302
System 3.3V Internal VOLT 1 3.135 3.465
System 12V Internal VOLT 2 11.4 12.6
System CMOS Battery VOLT 3 1.9 3.465
System 5V Internal VOLT 4 4.75 5.25
System FAN Speed FANRPM 5 1800 14000
System Temperature 1 TEMP 6 0 80
System Temperature 2 TEMP 7 0 80
CPU Socket Temperature TEMP 8 0 95
  • NetWall 6000 Series

    Note that where a 6000 Series sensor has maximum and minimum range values which are both zero, this means that no limits are applied and the sensor cannot trigger an alarm. An example of this is the the PSU1 Input Power sensor.

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

2.4.5. Memory Monitoring Settings

The System > Device > Hardware Monitoring section of the Web Interface provides the administrator with a number of settings related to the monitoring of available memory. Note that these settings are not available in virtual environments. The available settings are the following:

Memory Poll Interval

Memory polling interval which is the delay in minutes between readings of memory values. Minimum 1, Maximum 200.

Default: 15 minutes

Memory Use Percentage

True if the memory monitor uses a percentage as the unit for monitoring, False if megabytes are used. Applies to Alert Level, Critical Level and Warning Level.

Default: True

Memory Log Repetition

Should we send a log message for each poll result that is in the Alert, Critical or Warning level, or should we only send when a new level is reached. If True, a message is sent each time Memory Poll Interval is triggered. If False, a message is sent when a value goes from one level to another.

Default: False

Alert Level

Generate an Alert log message if free memory is below this number of bytes. Disable by setting to 0. Maximum value is 10,000.

Default: 0

Critical Level

Generate a Critical log message if free memory is below this number of bytes. Disable by setting to 0. Maximum value is 10,000.

Default: 0

Warning Level

Generate a Warning log message if free memory is below this number of bytes. Disable by setting to 0. Maximum value 10,000.

Default: 0

2.5. SNMP

2.5.1. Management with SNMP

Simple Network Management Protocol (SNMP) is a standardized protocol for management of network devices. An SNMP compliant client can connect to a network device which supports the SNMP protocol to perform management tasks. cOS Core supports access by SNMP clients using the following versions of the SNMP protocol:

  • Version 1.
  • Version 2c.
  • Version 3.

However, only query operations are permitted by clients for security reasons. Specifically, cOS Core supports the following SNMP request operations:

  • The GET REQUEST operation.
  • The GET NEXT REQUEST operation.
  • The GET BULK REQUEST operation (SNMP Version 2c and 3 only).

Setting up SNMP Access in cOS Core

To allow access by an SNMP client, a Remote Management object of the type SNMP Management object must be created in the cOS Core configuration. This object has the following properties:
  • Protocol - Select Version 1 and 2c (the default) or select Version 3.

  • Interface - The cOS Core interface on which SNMP requests will arrive.

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

The other SNMP Management object properties are for security and depend on the SNMP protocol choice. These are explained next.

SNMP Security Options

The following are the security options, depending on which protocol is selected:

  • Versions 1 and 2c

    Authentication for SNMP Versions 1 and 2c uses the Community String property. The Community String is equivalent to a password and should be difficult to guess. It should be constructed in the same way as any other password, using combinations of upper and lower case letters along with digits.

    SNMP versions 1 and 2c do not provide any option for encryption and traffic is sent as plain text. For this reason, SNMP version 3 is often a better choice. If SNMP version 1 or version 2c must be used, it is possible to send the SNMP connection through a VPN tunnel that is established between the client computer and the Clavister firewall.

  • Version 3

    If SNMPv3 is selected for the protocol, it is then possible to set the Security Level property. This can take the following values:

    1. noAuthNoPriv - No authentication and no encryption.

    2. authNoPriv - SHA-1 authentication but no encryption.

    3. authPriv - SHA-1 authentication and AES encryption.

    If authentication is enabled, a Local User Database object must be selected which contains the valid username/password pairs that can be used for client access. Often the predefined AdminUsers database is sufficient if an administrator or auditor username/password combination will be used as the SNMPv3 credentials.

    If encryption is enabled, cOS Core will use only AES encryption. cOS Core does not support DES encryption (as specified in the SNMPv3 RFC) as this is generally now considered to offer inferior security.

The cOS Core MIB Files

An important component required by any SNMP client are MIB files. A Management Information Base (MIB) is a database, usually in the form of a plain text file, that defines the parameters on a network device that an SNMP client can access.

The MIB files for cOS Core are contained within cOS Core itself. They are stored in the cOS Core folder called SNMP_MIB and have the following names:

  • CLAVISTER-MIB.mib
  • CLAVISTER-SMI.mib
  • CLAVISTER-TRAPS-MIB.mib

Downloading MIB Files

The files listed above can be downloaded directly from cOS Core to a management computer's local disk, either using the Web Interface or Secure Copy (SCP). To do this with the Web Interface, go to Status > Maintenance > Resources.

If using an SCP client, a typical command line might be the following:

> pscp -l admin -pw admin 192.168.1.17:SNMP_MIB/CLAVISTER-MIB.mib .

Once on the disk storage of a management computer, the files can be imported by the SNMP client software.

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:
clvIfPktsTotCnt OBJECT-TYPE
  SYNTAX      Counter32
  MAX-ACCESS  read-only
  STATUS      current
  DESCRIPTION "Total number of packets transmitted by the interface"
               ::= { clvIfStatsEntry 10 }

Enabling IP Rule Set Checking for SNMP

The advanced setting SNMP Before Rules controls if all accesses by SNMP clients are checked against the IP rule set. By default, this is enabled and the recommendation is to always have this setting enabled.

The effect of enabling this setting is to add an invisible Allow rule at the top of the IP rule set which automatically permits accesses on port 161 from the network and on the interface specified for SNMP access. Port 161 is usually used for SNMP and cOS Core always expects SNMP traffic on that port.

Preventing SNMP Overload

The advanced setting SNMP Request Limit restricts the number of SNMP requests allowed per second. This can help prevent attacks through SNMP overload.

Example 2.34. Enabling SNMP Versions 1 and 2c Monitoring

This example enables SNMP version 1 and 2c access via the lan interface from the network mgmt-net using the community string Mg1RQqR.

Since the management client is on the internal network, there is no need for it to communicate via a VPN tunnel.

Command-Line Interface

Device:/> add RemoteManagement RemoteMgmtSNMP my_snmp_v1-2
			Interface=lan
			Network=mgmt-net
			SNMPGetCommunity=Mg1RQqR
Should it be necessary to enable SNMP Before Rules (which is enabled by default) then the command is:
Device:/> set Settings RemoteMgmtSettings SNMPBeforeRules=Yes

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: System > Device > Remote Management > Add > SNMP Management
  2. Now enter:
    • Name: my_snmp_v1-2
    • SNMP Version: SNMPv1 and SNMPv2c
  3. For Access Filter enter:

    • Interface: lan
    • Network: mgmt-net
  4. For Authentication enter:

    • Community: Mg1RQqR
  5. Click OK

Should it be necessary to enable SNMP Before Rules (which is enabled by default) then the setting can be found in System > Device > Remote Management > Advanced Settings.

Example 2.35. Enabling SNMP Version 3 Monitoring

This example is similar to the SNMP versions 1 and 2c example above, but uses SNMP version 3 instead. It enables SNMPv3 access via the lan interface from the network mgmt-net. Both SNMPv3 authentication and encryption will be enabled and authentication will be done using the local database called AdminUsers.

Command-Line Interface

Device:/> add RemoteManagement RemoteMgmtSNMP my_snmp_v3
			Interface=lan
			Network=mgmt-net
			SNMPversion=SNMPv3
			LocalUserDatabase=AdminUsers
			Snmp3SecurityLevel=authPriv
Should it be necessary to enable SNMP Before Rules (which is enabled by default) then the command is:
Device:/> set Settings RemoteMgmtSettings SNMPBeforeRules=Yes

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: System > Device > Remote Management > Add > SNMP Management
  2. Now enter:
    • Name: my_snmp_v3
    • SNMP Version: SNMPv3
    • Security Level: authPriv
  3. For Access Filter enter:

    • Interface: lan
    • Network: mgmt-net
  4. For Authentication enter:

    • Local User Database: AdminUsers
  5. Click OK

Should it be necessary to enable SNMP Before Rules (which is enabled by default) then the setting can be found in System > Device > Remote Management > Advanced Settings.

2.5.2. Persistent SNMP Interface Indexes

For SNMP access, cOS Core maintains an index table which contains a configuration's interfaces (all types of interfaces) and each interface has an index number which indicates its position in the table. SNMP client software, including scripts using SNMP, will use these index numbers to refer to a particular interface.

The Problem is Adding or Subtracting Interfaces

By default, the index table is built every time cOS Core restarts but this can mean that a given interface could get a new index number because new interfaces are added to or subtracted from the configuration. This can pose a problem to SNMP client software which is expecting an interface to have the same index number.

The Solution is Enabling Persistence

To make sure that an interface always has the same index number following a restart, the administrator should enable the SNMP Persist Interface Index setting. This is a global setting which is enabled for the entire configuration.

Enabling Persistent Interfaces in an HA Cluster

In an HA cluster, the interface index table is built in the same way and the table is mirrored between the cluster nodes. However, if interface persistence is enabled, it will only function correctly if the HA setting Synchronize Configuration is enabled on both master and slave. This can be found in the Web Interface by going to System > Device > High Availability and is enabled by default.

In InControl, the cluster property Cluster nodes synchronize automatically should be enabled (it is also enabled by default).

Adding Back a Subtracted Physical Interface

If a physical interface is removed from hardware (this could happen with expansion modules) then the interface will still exist in the index table since it has probably not been removed from the configuration. It is only when an interface is completely removed from a configuration that its entry in the index table disappears.

This means that if the physical interface is later added back to the hardware, it will continue to have the same index number. This is true even though the interface added may be a different physical unit.

Compacting the Index Table

When interface persistence is enabled, it works by having every interface keep the same position in the index table. This can mean that gaps appear in the table (and consequently the interface index numbering) as interfaces disappear. The administrator can, if they wish, defragment the table manually during a scheduled maintenance period using the following CLI command:
Device:/>  ifstat -snmpnewindexes
This must be followed by an Activate and Commit in order for the table to be defragmented.

There is no other reason to perform defragmentation other than to return the index numbering to a sequential list of numbers. Extra resources are not consumed because of fragmentation.

[Caution] Caution: Restoring a backup will renumber interface indexes

If a restore of a system backup is performed (either a full system restore or cOS Core configuration only), this will cause the interface index numbers to return to the values of the backup.

Example 2.36. Enabling SNMP Index Persistence

This example shows how to enable SNMP index persistence.

Command-Line Interface

Device:/> set Settings RemoteMgmtSettings SNMPPersistentIfIndex=Yes

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: System > Device > Remote Management
  2. Select Advanced Settings
  3. Under SNMP, enable the option Persistent Interface Index
  4. Click OK

2.5.3. SNMP Advanced Settings

The following SNMP advanced settings can be found under the Remote Management section in the Web Interface or InControl. They can also be set through the CLI.

SNMP Before RulesLimit

Enable SNMP traffic to the firewall without checking the IP rule set.

Default: Enabled

SNMP Request Limit

Maximum number of SNMP requests that will be processed each second by cOS Core. Should SNMP requests exceed this rate then the excess requests will be ignored by cOS Core.

Default: 100

System Contact

The contact person for the managed node.

Default: N/A

System Name

The name for the managed node.

Default: N/A

System Location

The physical location of the node.

Default: N/A

Interface Description (SNMP)

What to display in the SNMP MIB-II ifDescr variables.

Default: Name

Interface Alias

What to display in the SNMP ifMIB ifAlias variables.

Default: Hardware

Persistent Interface Index

A global setting that determines if interface index persistence is enabled.

Default: No

2.6. Diagnostic Tools

2.6.1. Overview

When troubleshooting network problems, cOS Core provides an assortment of tools to help with problem resolution.

The section describes some of the most important troubleshooting tools available to the administrator. Most of these are used as CLI commands.

2.6.2. The ping Command

The combination of the ICMP echo request and echo reply messages are known as ping. They provide a simple diagnostic tool to find out if a host is reachable. In the cOS Core CLI, the ping command provides this feature.

In its simplest form, the CLI command to ping a remote IP address takes the form:

Device:/> ping <ipaddress>

For example, to ping the IPv4 address 10.6.58.10:

Device:/> ping 10.6.58.10
		
Sending 1 4-byte ICMP ping to 10.6.58.10 from 192.168.3.20
using PBR table "main"
ICMP Reply from 192.168.1.1  seq=0  time=<10 ms  TTL=128

Ping Results:  Sent: 1, Received:1, Avg RTT: 10.0 ms

Here, the RTT is the round trip time for the ICMP echo request and reply messages. The TTL value is the Time To Live which is a hop counter. The initial TTL value is set by the sender and decremented by each router passed. When it reaches zero, the packet is discarded preventing packets from circulating forever.

This basic form of the ping command can also be used via the cOS Core Web Interface by going to: Status > Tools > Ping.

Choosing the Routing Table

By default, the outgoing source interface for ICMP ping is chosen by performing a lookup of the destination IP address in the main routing table. This can be overridden with the -pbr option in order to specify which routing table to use for the lookup. For example, if the routing table my_routing_table is to be used, the command would be:
Device:/> ping 10.6.58.10 -pbr=my_routing_table -verbose

IP Rule Set Entries for Outgoing Ping Messages

When the ICMP ping message is outgoing from cOS Core, it does not require that there is an IP rule set entry that allows the traffic since cOS Core is always trusted. In the cOS Core event message logs, an outgoing ping will generate a conn_open and conn_close log event using the Stock_Allow_All_Rule. The source interface will always be the core interface (meaning cOS Core itself).

IP Rule Set Entries for Incoming Ping Messages

Any ping messages that are incoming require an allowing IP rule set entry in order for cOS Core to respond and these entries should have their associated Service property set to be the predefined service ping-inbound. An example IP rule set entry for ping messages arriving on the wan interface would be the following:

Action Source
Interface
Source
Network
Destination
Interface
Destination
Network
Service
Allow wan all-nets core wan_ip ping-inbound

Using the -verbose Option

The -verbose option is recommended to get the maximum amount of information from ping usage. For example:
Device:/> ping 10.6.58.10 -verbose
		
Sending 1 4-byte ICMP ping to 10.6.58.10 from 192.168.3.20
 ... using route "192.168.3.20 via lan, gw (Iface IP)" in PBR table "main"
ICMP Reply from 192.168.3.20  seq=0  time=<10 ms  TTL=255

Ping Results:  Sent: 1, Received:1, Avg RTT: 10.0 ms
Here, the IPv4 address 192.168.3.20 is the IP address of the Ethernet interface on the firewall from which the ping is sent. The output shows the route lookup that was performed to find the correct interface.

Testing TCP and UDP Connectivity

ICMP messages are neither UDP or TCP but are considered to be their own third category of IP traffic. However, the cOS Core ping command has the ability to send a message to test either TCP or UDP connectivity.

To send as TCP, the -port option is used along with the -tcp option. Successful connectivity then results in a 3-way TCP handshake taking place with the destination host. For example:

Device:/> ping 10.6.58.10 -port=80 -tcp -verbose
		
Sending 0-byte TCP ping to 10.6.58.10:80 from 192.168.3.20:41207
using PBR table "main"
... using route "10.6.10.0/24 via aux, no gw" in PBR table "main"
TCP Reply from 10.6.58.10:80 to 192.168.3.20:41207 seq=0  SYN+ACK
time=>10 ms  TTL=128
TCP Reply from 10.6.58.10:80 to 192.168.3.20:41207 seq=0  ACK
time=>10 ms  TTL=128

TCP Ping Results:  Sent: 1, RST/ACKs Received:1, Loss: 0%, Avg RTT: 10.0 ms

This allows the remote hosts responsiveness to an incoming TCP connection to be established.

For testing UDP connectivity, use the -udp option with the -port option. The UDP message size can also be specified by using the -count option to specify the number of packets and the -length option to specify the packet length. For example:

Device:/> ping 10.6.58.10 -udp -port=2222 -verbose -count=1 -length=30

Sending 30-byte UDP ping to 10.6.58.10:2222 from 192.168.3.20:22307
using PBR table "main"
... using route "0.0.0.0/0 via ext, gw 192.168.3.1" in PBR table "main"
UDP Reply from 10.6.58.10:2222 to :192.168.3.20:22307 seq=0 time=50 TTL=58

Ping Results:  Sent: 1, Received:1, Loss: 0%, Avg RTT: 50.0 ms

If the size is not specified then cOS Core sends a single 4 byte UDP packet.

The "Could not open outbound connection" Message

This response may be encountered after the ping command is entered. There are a number of reasons for this message and they are listed in a Clavister Knowledge Base article at the following link:

https://kb.clavister.com/324735730

Incoming Packet Simulation Using the -srcif and -srcip Options

Instead of testing the responsiveness of a remote host, the cOS Core ping command can be used to simulate incoming traffic and thereby test the configured IP rule set and routing table. This is done by using the -srcif option to specify the interface that receives the message and the -srcip option to specify the sending IP address. For example:
Device:/> ping 10.6.58.10 -srcif=wan -srcip=192.168.14.12 -verbose
This command will construct an ICMP packet with destination IP 10.6.58.10 and cOS Core will behave as though the packet has arrived on the wan interface and had come from the IP address 192.168.14.12 . Note when the -verbose option is included, the output from the command will show the configuration rules that are triggered by the simulation.

The destination IP address specified in the ping command. could be an actual external host in which case the packet will be forwarded to it through the firewall, providing the configuration allows this.

In the example output below, it can be seen how a ping simulation can show pipe rules that are triggered when an ICMP message is received on the lan interface.

Device:/> ping 10.6.58.10 -srcif=lan -srcip=192.168.3.1 -verbose
		
Rule and routing information for ping:
PBR selected by rule "iface_member_main" - PBR table "main"
     allowed by rule "nat_all_wan"
		   piped by rule "out_pipe" - Fwd Chain: out
			 piped by rule "out_pipe" - Ret Chain: in

Sending 1 4-byte ICMP ping to 10.6.58.10 from 192.168.3.20
sent via route "0.0.0.0/0 via lan, gw 192.168.3.1" in PBR table "main"
ICMP Reply from 10.6.58.10  seq=0  time= 10 ms  TTL=247

Ping Results:  Sent: 1, Received:1, Avg RTT: 10.0 ms

The above output shows how a Pipe Rule object called out_pipe is triggered.

If there is no route that matches the combination of source IP and receiving interface (the -srcif parameter), the packet will be dropped by the default access rule. For example:

Device:/> ping 10.6.58.10 -srcif=wan -srcip=192.168.14.12 -verbose
		
Rule and routing information for ping:
PBR selected by rule "iface_member_main" - PBR table "main"
     DROPPED by rule "Default_Access_Rule"

For the simulated traffic not to be dropped, there must not only be a route that matches the combination of source IP address and receiving interface but also an IP rule set entry that allows the traffic arriving on that interface. If the administrator simulates ICMP traffic coming from the Internet that arrives on the wan interface and destined for some host on the protected network lan_net, the allowing IP rule set entry might be the following:

Action Source
Interface
Source
Network
Destination
Interface
Destination
Network
Service
Allow/NAT lan lan_net wan_net all-nets ping-inbound

If there is no IP rule set entry that permits the packet, it will also be dropped. For example:

Device:/> ping 10.6.58.10 -srcif=wan -srcip=192.168.14.12 -verbose
		
Rule and routing information for ping:
PBR selected by rule "iface_member_main" - PBR table "main"
     DROPPED by rule "Default_Rule"

[Note] Note: The -pbr option cannot be used with the -srcif option

The -pbr option cannot be used with the -srcif option. The routing table used is decided by the cOS Core configuration.

Ping with IPv6

So far, the use of the ping command has been discussed only for IPv4 addresses. IPv6 addresses can also be used with the ping command. For example:
Device:/> ping 2001:DB8::2
Using IPv6 with ping is discussed further in Section 3.2, IPv6 Support.

FQDN Resolution

When issuing a ping request from cOS Core, it is possible to specify the destination as a fully qualified domain name (FQDN). This is then resolved by cOS Core to a numerical IP address by using an external DNS server. For example:
Device:/> ping server.example.com

[Note] Note: At least one DNS server must be configured

For FQDN resolution to function, at least one DNS server must be configured in cOS Core. Configuring DNS servers is described in Section 3.10, DNS.

DNS servers might return either an IPv4 address or an IPv6 address or both. These three possibilities are treated as follows:

  • If only an IPv4 address is returned then that will be used by the ping command for the ICMP message.

  • If only an IPv6 address is returned then that will be used by the ping command for the ICMP message.

  • If both an IPv4 and an IPv6 address is available, cOS Core will use the IPv4 address by default. However, cOS Core can be forced to use the IPv6 address with the -6 command option. For example:

    Device:/> ping www.example.com -6

2.6.3. The stats Command

If a serious cOS Core problem is suspected then the first step should be to use the CLI command:

Device:/> stats

The stats command will provide a snapshot of the system and indicate the date and time of the last system shutdown and can also indicate if there has been a serious error in cOS Core operation. It should be remembered however that the buffer which stats uses is cleared by certain operations such a reconfigure and the output will not therefore show what occurred prior to buffer clearance.

Below is a typical example of output from the command:

Device:/> stats
Uptime             : 7 days, 02:12:38
Last shutdown      : 2014-06-17 16:05:00: Activating configuration changes
CPU Load           : 4%
Connections        : 23 out of 512000
Fragments          : 0 out of 16384 (0 lingering)
Buffers allocated  : 43280
Buffers memory     : 43280 x 2636 = 111412 KB
Fragbufs allocated : 32
Fragbufs memory    : 32 x 10040 = 313 KB
Out-of-buffers     : 0

At the end of the Last shutdown line is the reason for the shutdown.

stats Command Output with Poll Offloading

When cOS Core runs on certain hardware platforms or in the KVM virtual environment, it can make use of a technique known as poll offloading to increase performance. However, the cOS Core license must explicitly allow the feature for it to be used.

With poll offloading, two CPU cores can be used simultaneously by cOS Core. One CPU core will be running most of cOS Core's functions and the second will be running that part of cOS Core that handles Ethernet interface polling.

When the stats command is used with poll offloading active, the CPU Load line in the command output will show two percentages instead of one. The first percentage is the load for the CPU core that is running most of cOS Core's functions. The second percentage shows the load for the CPU core that is running the interface polling subsystem. An example of this output is shown below:

CPU Load           : 12%, 1%

Poll offloading is usually turned on automatically by cOS Core if the hardware platform supports it and the administrator does not normally need to enable it.

The settings for controlling the poll offloading feature are described in Section 13.10, Miscellaneous Settings.

2.6.4. The connections Command

By using the connections command, the administrator can get a snapshot of all the connections currently set up in the cOS Core state engine. The command can be abbreviated to conn and some example output is shown below:

Device:/> conn

State    Proto   Source                      Destination            Tmout
-------- ------- --------------------------- ----------------------- ------
TCP_OPEN TCP     If1:10.4.4.24:54047         If2:192.168.9.3:338    261772
UDP      UDP     If2:192.168.109.11:4500     If3:10.152.0.22:450    130
PING     ICMP    vlan1:192.168.1.1:512       If3:90.152.1.1:512     8
FIN_RCVD TCP     If1:10.4.4.121:55679        core:10.4.0.31:444     69
TCP_OPEN TCP     If2:192.168.96.77:35217     If3:10.93.2.49:463     70855
UDP      UDP     vlan1:192.168.100.163:560   vpn-A:10.45.1.2:161    9
UDP      UDP     vlan1:192.168.100.163:582   vpn-B:10.25.1.2:161    76

Each line in the command's output corresponds to a single connection. The fields shown are:

  • State

    This indicates the state of the connection and is only really relevant to TCP connections where different states apply. Some of the possible values are:

    1. UDP - A UDP pseudo-connection.

    2. PING - AN ICMP ping connection.

    3. TCP_OPEN - A TCP connection is opening.

    4. SYN_RCVD - A TCP connection has received a SYN packet and is open.

    5. FIN_RCVD - A TCP connection has been closed. Connections wait, by default, for 80 seconds before all data is cleaned up by cOS Core so that the connection could be reopened. The 80 second value is controlled by the cOS Core setting TCP FIN Idle Lifetime. The ability to reopen a connection is controlled by the cOS Core setting Allow TCP Reopen which is disabled by default.

    6. RAW IP - Another protocol which is identified in the Protocol column.

    7. ZOMBIE - This is a transient state that indicates being queued for deletion from the connection table.

      This state can appear because there are a large number of connections that are queued for deletion from the table but cOS Core has not yet had time to remove them all. Note that while in the zombie state, a connection will not forward any traffic.

      Zombie connections are also discussed in an article in the Clavister Knowledge Base at the following link:

      https://kb.clavister.com/324735766

  • Proto

    The protocol used for the connection. This can be the same as the State column is some cases. Some of the possible values are:

    1. UDP - A UDP pseudo-connection.

    2. ICMP - An ICMP ping connection.

    3. TCP - A TCP connection.

    4. ESP - Used for IPsec VPN tunnels.

    5. A number or name indicating the protocol being used. The State column will have the value RAW IP.

  • Source

    This consists of:

    1. The source interface. This could be the name of any type of cOS Core interface object such as a VLAN or IPsec tunnel. It can also be Core which indicates cOS Core itself is the connection's source.

    2. The source IP address for the connection.

    3. The source port number for the connection.

  • Destination

    This consists of:

    1. The destination interface. This could be the name of any type of cOS Core interface object such as a VLAN or IPsec tunnel. It can also be Core which indicates cOS Core itself is the connection's destination.

    2. The destination IP address for the connection.

    3. The destination port number for the connection.

  • Tmout

    The number of seconds until the connection times out because no traffic is detected. As soon as any traffic is detected being sent from either end of the connection, this value is reset to the default timeout. The defaults are controlled by the followed cOS Core settings:

    1. TCP Idle Lifetime - For TCP connections. The default value is 262144 seconds.

    2. UDP Idle Lifetime - For UDP connections. The default value is 130 seconds.

    3. Ping Idle Lifetime - For ICMP Ping connections. The default value is 8 seconds.

    4. Other Protocols Idle Lifetime - All other protocols. The default value is 130 seconds.

Filtering Connections

The connections command provides the ability to specify filters for which connections are display. To display only connections with the protocol TCP the command would be:
Device:/> conn -protocol=TCP
To see only connections with the source interface If3:
Device:/> conn -srciface=If3

Closing Connections

The connections command gives the administrator the ability to close all or selected connections. To close all, the command would be:
Device:/> conn -close -all
To close all connections with the source interface If3:
Device:/> conn -close -srciface=If3

The -verbose Option

When the -verbose option is used, the connections command adds another line of output for each connection that is prefixed with ...term:. This line shows the changes, if any, made by cOS Core in the interface or IP or port number as the connection traverses the firewall. For example, consider this output showing a single connection:
Device:/> conn -verbose

State    Proto   Source                      Destination            Tmout
-------- ------- --------------------------- ----------------------- ------
TCP_OPEN TCP     If1:10.4.0.16:60848         If3:192.168.96.82:80   262119
        ...term: If1:192.168.96.1:39097      If3:192.168.96.82:80   262119
Here, the original connection is subject to a NATing IP rule set entry which transforms If1:10.4.0.16:60848 into If1:192.168.96.1:39097. The destination remains the same but the source IP and port has been changed by cOS Core. For this example, a private IP address has been used for illustration but 192.168.96.1 would typically be a public IP address.

A complete list of all options for the connections command can be found in the separate CLI Reference Guide.

2.6.5. The dconsole Command

The next step is to use the CLI command:

Device:/> dconsole

This can be abbreviated to:

Device:/> dcon

The dconsole command provides a list of important events that have occurred during cOS Core operation and can help to establish the date, time and nature of events leading up to a serious problem occurring. The output might look similar like the following:

Showing diagnose entries since 2008-05-22:
2008-06-21 11:54:58                  Start (14.00.06-0:131)
2008-06-21 11:56:16                  Stop (RECONFIGURE)
2008-06-21 11:56:21                  Start (14.00.06-0:131)
2008-06-21 11:57:29                  Stop (RECONFIGURE)
2008-06-21 11:59:31                  Start (14.00.06-0:131)
2008-06-21 11:59:49                  Stop (NORMAL)
			"
			"

Output from dconsole can include a dump of the system memory in the case of serious runtime errors. Such a dump will look similar to the following:

'
'
Reason: Exception 'DataAbort' occurred at address 0x7aaea34
Generation date/time: 2008-07-04 14:23:56 List of loaded PE-modules:
fwloader(1.07.04): BA:0x00100000, EP:0x00101028, SS:0x0, IS:0xe7000
fwcore(814.00.06-2336): BA:0x07761038, EP:0x0007c630 Register dump:
----------------------------------------------------
r0 : 0xe1a0003c, r1 : 0x07c685dc, r2 : 0x00000004, r3 : 0x50013700,
r4 : 0x06cb2d04, r5 : 0x0753a740, r6 : 0x050ce1f8, r7 : 0x00000000,
r8 : 0x0753a79c, r9 : 0x050ce1f8, r10: 0x00000000, r11: 0x0775ff34,
r12: 0x00000004, sp : 0x0775fcec, lr : 0x079de7e4 Stack dump:
5da89306 c33613f4 c330cfc5 04411507 45515a49 86619f8b c0db0a81
4e395861 cb25b796 e3108934 932766c5 4dcff9e9 711c3463 b9cd5d1e
52149961 9324dea3 d340dc25 15458610 63582ded 689a0c54 dfb43131
02c7d971 a0ebb72c bfaae832 db216923 08ba693b 95e4de97 98d121a2
'
'

Although dconsole output may be difficult to interpret by the administrator, it can be emailed to Clavister support representatives for further investigation.

The dconsole command supersedes the crashdump command found in earlier versions of cOS Core.

Dconsole can also be run in the Web Interface by going to:
Status > Maintenance > Diagnostic Console
Selecting this option runs dconsole automatically and the output is immediately displayed in a text box. The contents of the text box can be copied and pasted into an email for review by support personnel. Pressing the Refresh button will run dconsole again and display the new output in the text box.

2.6.6. The pcapdump Command

A valuable diagnostic tool is the ability to examine the packets that enter and leave the interfaces of a Clavister firewall. For this purpose, cOS Core provides the CLI command pcapdump which not only allows the examination of packet streams entering and leaving interfaces but also allows the filtering of these streams according to specified criteria. Only the pcapdump CLI command usage is described in this section but its functions are also duplicated in the Web Interface.

The packets that are filtered out by pcapdump can then be saved in a file of type .cap which is the defacto libpcap library file format standard for packet capture.

The complete syntax of the pcapdump CLI command is described in the CLI Reference Guide. There is also an additional description of usage in the Clavister Knowledge Base at the following link:

https://kb.clavister.com/324736324

A Simple Example

An example of pcapdump usage is the following sequence:
Device:/> pcapdump -size 1024 -start lan
Device:/> pcapdump -stop lan
Device:/> pcapdump -show
Device:/> pcapdump -write lan -filename=cap_lan.cap
Device:/> pcapdump -cleanup

Going through this line by line we have:

1. Recording is started for the lan interface using a buffer size of 1024 Kbytes.

Device:/> pcapdump -size 1024 -start lan

2. The recording is stopped for the lan interface.

Device:/> pcapdump -stop lan

3. The dump output is displayed on the console in a summarized form.

Device:/> pcapdump -show

4. The same information is written in its complete form to a file called cap_lan.cap.

Device:/> pcapdump -write lan -filename=cap_lan.cap

At this point, the file cap_lan.cap should be downloaded to the management computer for analysis.

5. A final cleanup is performed and all memory taken is released.

Device:/> pcapdump -cleanup

Re-using Capture Files

Since the only way to delete files from the firewall is through the local console, the recommendation is to always use the same filename when using the pcapdump -write option. Each new write operation will then overwrite the old file.

Running on Multiple Interfaces

It is possible to have multiple pcapdump executions being performed at the same time. The following points describe this feature:

  1. All capture from all executions goes to the same memory buffer.

    The command can be launched multiple times with different interfaces specified. In this case the packet flow for the different executions will be grouped together in different sections of the report.

    If a clearer picture of packets flowing between interfaces is required in the output then it is best to issue one pcapdump command with the interfaces of interest specified.

  2. If no interface is specified then the capture is done on all interfaces.

  3. The -stop option without an interface specified will halt capture on all interfaces.

  4. pcapdump prevents capture running more than once on the same interface by detecting command duplication.

Filter Expressions

Seeing all packets passing through a particular interface often provides an excess of information to be useful. To focus on particular types of traffic the pcapdump command has the option to add a filter expression which has one of the following forms:

-eth=<macaddr> - Filter on source or destination MAC address.
-ethsrc=<macaddr> - Filter on source MAC address.
-ethdest=<macaddr> - Filter on destination MAC address.
-ip=<ipaddr> - Filter source or destination IP address.
-ipsrc=<ipaddr> - Filter on source IP address.
-ipdest=<ipaddr> - Filter on destination IP address.
-port=<portnum> - Filter on source or destination port number.
-srcport=<portnum> - Filter on source port number.
-destport=<portnum> - Filter on destination port number.
-proto=<id> - Filter on protocol where id is the decimal protocol id.
-<protocolname> - Instead of using -proto=, the protocol name alone can be specified and can be one of -tcp, -udp or -icmp.

Examining Multiple Ports

It is possible to specify the port as a list of port numbers:
Device:/> pcapdump -size 1024 -start lan -port=67,68
It is also possible to specify a port range:
Device:/> pcapdump -size 1024 -start lan -port=8080-8088

Downloading the Output File

As shown in one of the examples above, the -write option of pcapdump can save buffered packet information to a file on the firewall.

These output files are placed into the cOS Core root directory and the filename is specified in the pcapdump command line, usually with a filetype of .cap. The name of output files must follow certain rules which are described below. Files can be downloaded to the local management computer using Secure Copy (SCP) (see Section 2.1.8, Using SCP). A list of all files in the cOS Core root directory can be viewed by issuing the ls CLI command.

The -cleanup option will erase the files so cleanup should only be done after file download is complete.

Output File Naming Restrictions

The name of the file used for pcapdump output must comply with the following rules:

  • Excluding the filename extension, the name may not exceed 8 characters in length.

  • The filename extension cannot exceed 3 characters in length.

  • The filename and extension can only contain the characters A-Z, 0-9, "-" and "_".

Combining Filters

It is possible to use several of these filter expressions together in order to further refine the packets that are of interest. For example we might want to examine the packets going to a particular destination port at a particular destination IP address.

Compatibility with Wireshark

The open source tool Wireshark (formerly called Ethereal) is an extremely useful analysis tool for examining logs of captured packets. The industry standard .pcap file format used by pcapdump with its -write option means that it is compatible with Wireshark.

For more complete information about this topic, see http://www.wireshark.org.

Using pcap through the Web Interface

All the functions described above are available in the Web Interface by going to Status > Tools > PCAP. It is also possible to directly download the .cap file to the management computer. If Wireshark has been installed and the file association with it set up, the file can be opened directly in the software.

Extensive Packet Capture Could Affect Throughput

Over a short period, packet capture will not have a noticeable effect on firewall throughput. However, the administrator should be aware that extensive packet capture over a longer period may impact overall traffic throughput because of the processing resources that are required. The potential impact is hard to quantify because of the large number of variables.

2.6.7. The traceroute Command

Overview

The cOS Core traceroute CLI 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™.

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 Core sends its traceroute packets as ICMP ping messages. However, it is also possible to send messages using UDP or TCP. The basic form of the command for sending ICMP messages is the following:

Device:/> traceroute <destination>

The <destination> can be an IPv4 or IPv6 address, for example:

Device:/> traceroute 192.168.4.1

Or it can be a DNS resolvable Fully Qualified Domain Name (FQDN), for example:

Device:/> traceroute server.example.com

When using traceroute with an FQDN then at least one DNS server must have been configured in cOS Core to perform the resolution. Doing this is described in Section 3.10, DNS. To send a TCP message instead of ICMP, the command would be the following:

Device:/> traceroute -tcp server.example.com

To send a UDP message:

Device:/> traceroute -udp server.example.com

Note that the -tcp and -udp options must be placed before the destination in the command.

Traceroute Output

Below is some typical output from traceroute using the default settings with the destination specified as an FQDN:
Device:/> traceroute server.example.com
		
Tracing server.example.com [10.194.40.247], 30 hops max, 32 bytes of data
Hop#    RTT      RTT      RTT   Host
  1    10 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
Trace complete.
Here, each line of output corresponds to an attempt by traceroute to reach the next router.

By default, traceroute tries 3 times for each router hop and the Round Trip Time for each attempt expressed in milliseconds is shown under a corresponding RTT heading.

There were two routers in the path to the target destination in the above output (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 traceroute command output.

It is possible that different routers could respond 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.

Traceroute Options

The following are some of the important options for the traceroute command:

  • -6

    When the destination is specified as an FQDN, cOS Core 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 an IPv6 address is to be requested from the DNS server and used as the destination address.

    Device:/> traceroute server.example.com -6

    Alternatively, the IPv6 address could be entered directly after the traceroute command.

  • -maxhops

    This specifies the maximum value for the time-to-live parameter of the packets sent.

    Device:/> traceroute server.example.com -maxhops=20

    The default value is 30.

    Maxhops is important because if cOS Core 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 maxhops limit is reached.

  • -count

    This specifies how many attempts are made for each hop.

    Device:/> traceroute server.example.com -count=1

    The default value is 3.

  • -size

    This specifies how large the payload is that is sent. The payload is made up of random data.

    Device:/> traceroute server.example.com -size=128

    The default value is 32.

  • -nodelay

    This specifies that each query is to be sent as fast as possible.

    Device:/> traceroute server.example.com -nodelay

    The default is that this is disabled.

    The number of traceroute ICMP messages specified by the -count parameter are first sent continuously with no delay. Then there is a fixed delay of one second before the next set of messages are sent with an incremented time-to-live value. By specifying -nodelay, the one second delay is removed and the sets of messages are sent continuously with no delay between them. This continuous packet stream can simulate a denial-of service (DOS) attack.

  • -starthop

    This specifies what time-to-live (TTL) value to start with and therefore at which hop to start.

    Device:/> traceroute server.example.com -starthop=3

    The default value is 1.

  • -stop

    This terminates any traceroute that is in progress .

    Device:/> traceroute -stop

  • -timeout

    This is the amount of time cOS Core will wait for a response from a router or the destination before it increases the time-to-live and tries again.

    Device:/> traceroute server.example.com -timeout=2000

    Any timeout conditions are indicated in the traceroute output. An example of this is shown below:

    Device:/> traceroute example.com
    				
    Tracing example.com [10.120.184.11], 30 hops max, 32 bytes of data
    Hop#    RTT      RTT      RTT   Host
      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:

    1. A router or the destination may not be set up to respond to ICMP ping messages.
    2. The destination host may be offline.

Combining Options

Any of the above options can be combined in a single command. For example:
Device:/> traceroute server.example.com -count=2 -starthop=3 -maxhops=4
		
Hop#    RTT      RTT   Host
  3    10 ms    10 ms  10.131.48.2
  4    10 ms    10 ms  ge1-1-0-617.cty-pe3.una.se.ip.tzc.net [10.88.215.44]
  5    10 ms    10 ms  te2-1-80.zty-p2.sfl.se.ip.tzc.net [10.131.143.226]
  6   120 ms   120 ms  10.82.35.201
Maximum hops reached.
A complete description of all the command options can be found in the separate CLI Reference Guide.

2.6.8. The frags Command

IP datagram fragmentation results from the breaking down of larger packets into smaller datagram fragments that can fit within the Maximum Transmission Unit (MTU) size of the network equipment they must traverse. When such fragments are received by cOS Core, packet reassembly takes place to reconstruct the entire packet before it is forwarded.

The CLI command frags allows the administrator to examine the current status of the reassembly process. Using the frags command without any parameters lists the currently active reassemblies as shown in the example output below.

Device:/> frags
		
RecvIf Num  State   Source       Destination  Protocol Next  Timeout
------ ---- ------- ------------ ------------- -------- ----- -------
If1    886  Unknown 192.168.1.6  192.168.2.1  ESP          0 593/593
If2    890  Accept  10.0.1.60    192.168.3.1  UDP       7280 592/591
If3    345  Drop    192.168.0.2  10.1.1.2     UDP       1494 581/101

Each line of output from this command shows the status of an individual reassembly operation where at least one fragment of a packet has been received as an IP datagram. Each datagram in the reassembly process is uniquely identified by its source/destination IP address and its protocol number. A reassembly operation will remain in the output of the command as long as more fragments might be received.

Reassembly States

The State of reassembly shown by the frags command output can be one of the following:

  • Done

    Reassembly is complete but reassembly is kept alive for a short period in case there are any duplicate fragments.

  • Drop

    cOS Core has determined that the reassembled packet is to be dropped based on the configured rules. This is the opposite of the Accept state and all matching fragments received will be dropped.

  • Unknown

    This indicates that it has not yet been determined if the packet is to be dropped or accepted.

  • Accept

    This state indicates it has been determined to not drop the packet based on the configured rules. This is the opposite of Drop and matching fragments received are accepted.

  • Free

    This indicates a reassembly slot that is available for starting a new reassembly.

Options for the frags Command

To see only the reassembly slots that are in the Free state, use the -free option:
Device:/> frags -free
To see reassembly operations that are complete use the -done option:
Device:/> frags -done

Maximum Length Settings

cOS Core allows the following settings to be used to control the maximum size of incoming packets for different protocols so that packets exceeding these sizes are dropped:

  • Max UDP Length - Maximum size of UDP packets (default: 60,000 bytes).

  • Max GRE Length - Maximum size of GRE packets (default: 2000 bytes).

  • Max ESP Length - Maximum size of IPsec ESP packets (default: 2000 bytes).

  • Max TCP Length - Maximum size of a TCP packet (default: 1480 bytes).

However, the MTU value of the individual cOS Core interfaces determines how the packet size is split. For example, the maximum UDP length could be set to 60,000 but the interface MTU size might be 1500 so packets would be split into 41 fragments (60,000/1500).

Keeping these maximum settings to the lowest possible value is beneficial since unreasonably large packets can be used as a form of attack and they are immediately rejected by cOS Core when they exceed the set maximum.

TCP Length

With TCP, all normally configured TCP stacks will limit the size of TCP packets to the Maximum Segment Size (MSS) value. This MSS value will normally be the MTU value minus the IP header size of 20 bytes. With an MTU value of 1500 bytes, the MSS will be 1480 bytes and this will normally never need to be fragmented.

2.6.9. The selftest Command

It can be the case that operational problems are caused by a problem with the underlying hardware platform and not cOS Core. For this reason, the CLI command selftest is provided to perform tests on various aspects of hardware functioning.

[Warning] Warning: Do NOT conduct tests with live traffic!

It is important to remember that the selftest command should not be used on a system that is carrying live traffic. The command can cause connections and associated data to be lost and the test results themselves could then become unreliable.

Preparing the System for Testing

To ensure the complete reliability of any selftest, it is recommended to take a complete backup of the current configuration and reset the entire system to the default cOS Core configuration as well as having the hardware platform disconnected from any networks.

This is also true for units in an HA cluster. The cluster should be broken up into two separate hardware units and they should each be reset to the base configuration.

Resetting to the base configuration can be done through the CLI or Web Interface or InControl. Using the CLI, the command is:

Device:/> reset -configuration

RAM Memory Selftest

An example of selftest usage is to test the volatile system RAM memory:
Device:/> selftest -memory
This repeatedly writes a one megabyte block of data across the RAM memory space and then reads it back to check all write/read operations were error free.

By default, the memory test is performed only once across the memory but this could be repeated using the -num option. For example, to repeat the test 10 times:

Device:/> selftest -memory -num=10

Media Selftest

Another example of selftest usage is to test if the non-volatile system disk media is functioning:
Device:/> selftest -media
The disk media is often solid state and usually physically separate from RAM. The test writes a single test file called medtest.tmp onto the media and then reads this file back to verify its contents before deleting it. It therefore tests that both the media disk memory and the media file system are functioning. The test does not affect any existing files.

The media test uses a default file size of one megabyte but this size can be changed using the -size option which takes a whole number of megabytes as its value. For example, to set the tested file size to 10 megabytes:

Device:/> selftest -media -size=10

Throughput Testing

The following command options test traffic throughput:

  • -throughout

    This generates the maximum achievable traffic flow through all specified interfaces using the maximum packet size. This option does not validate the received packets.

  • -traffic

    This test generates traffic of mixed packet sizes between 60 and 1,518 bytes and verifies the content of each received frame. Received packets are verified.

For either the -throughput or the -traffic option, the test should be run so that interfaces are connected together and the output from one interface is received by another. This can be achieved in one of two ways:

  • Connection Through a Switch

    All the interfaces are connected to the same switch which is itself disconnected from any other networks. This is only satisfactory if the hardware platform provides the same maximum link speed on all Ethernet interfaces since faster interfaces can overwhelm slower ones.

  • Connecting Ethernet Interfaces In Pairs

    With a hardware platform that provides mixed Ethernet interface speeds, it is necessary to connect interfaces with similar maximum link speeds together in adjacent pairs. A switch should not be used. Testing should be done on one pair of interfaces at a time. For example, if the -throughput option is to be applied between the If1 and If2 interfaces, the command would be:

    Device:/> selftest -interfaces=If1,If2 -throughput

The -burnin Option

If the -burnin option is used, a set of tests, known as the test subset, is repeated continuously for a period of time. The default test period is two hours and the default subset is:

  • -memory
  • -ping
  • -throughput
  • -traffic
  • -cryptoaccel

The duration of the -burnin test can be changed, as can the test subset. For example, a test of the memory and media that is repeated for 30 minutes would be:

Device:/> selftest -burnin -minutes=30 -memory -media

The -burnin option could, for example, be used to detect errors that only occur sporadically or possibly only occur after some hardware component has reached a certain critical operating temperature.

The full list of options for selftest CLI command can be found in the separate CLI Reference Guide along with more command line examples.

2.6.10. The techsupport Command

The techsupport CLI command is a general command for problem troubleshooting that combines the output from several other troubleshooting commands into a single console output. This information can then used by the administrator but is usually sent to qualified support personnel to troubleshoot problems. It is the first and most helpful source of troubleshooting information and the output file is often referred to by support personnel as the TSF (Technical Support File).

The techsupport command can be run in one of the following ways:

  • By entering the techsupport command in a CLI console. This will cause output to be sent to the console. Since the contents can be long, this may not be the most appropriate way to run the command.

  • Run the command via the Web Interface. The cOS Core Web Interface provides a way to run the techsupport command by clicking a single button. The output from the command is saved to a file which is automatically saved to the local disk of the management computer running the browser.

    This method of running the command is the best way to obtain the output as a file which can then be sent to qualified support personnel for analysis.

    The file created by cOS Core will have a filename with the format techsupport-yyyymmdd.txt where yyyymmdd is the date of file creation. The header of the file also contains a timestamp which indicates the exact system time the file was created.

64 bit cOS Core Requires Manual Download of Crashdumps

For older versions of cOS Core, the latest crashdump is included in the output from the techsupport command. For newer 64 bit versions this is not the case so the latest crashdump must be manually downloaded for inclusion in a support ticket submission.

All virtual cOS Core versions for ARM platforms are 64 bit versions. In addition, newer Clavister hardware such as the 100, 300, 500 and 6000 Series (and later) are running 64 bit cOS Core. If unsure about the version type, 64 bit versions will indicate this in the first line of the output from the about command:

Device:/> about
Clavister cOS Core 14.00.06.01-36868 (x86 64-bit)

Manual crashdump downloading can be done through the Web Interface by going to Status > Maintenance > System Error Reports (64 bit versions 14.00.06 and later). Alternatively, any suitable SCP client can be used (all 64 bit versions). Crashdump files always have the filetype .dmp and are stored in a folder called crashdumps under the firewall's filesystem root. The simplest SCP download method is to download all available files as a single zip file with an SCP command in the following form:

> scp admin@<fw-ip-address>:crashdumps/all.dmp .

Alternatively, an individual crashdump file could be downloaded with the following command form:

> scp admin@<fw-ip-address>:crashdumps/<filename>.dmp .

Example 2.37. Creating techsupport Output

This example shows the techsupport command can be invoked in the CLI and the Web Interface.

Command-Line Interface

Device:/> techsupport

Web Interface

  1. Go to: Status > Maintenance > Technical Support
  2. Click the button Download Support File
  3. A file chooser dialog will appear to save the file with the given filename to the local disk.
  4. Click OK

2.6.11. Creating an Anonymous Configuration Copy

The option exists to download a copy of the current cOS Core configuration to a file and to make the copy anonymous. This file will be the same as a normal configuration backup file with the one exception that all sensitive data is automatically anonymized.

This anonymizing process means that data such as passwords, pre-shared keys and certificates, are automatically replaced by random data in the downloaded file. Using an anonymous configuration copy is recommended when sending a configuration for review by a third party, such as external support personnel. However, this type of configuration copy should not be confused with a true configuration backup copy, which is discussed in Section 2.7.4, Backing Up Configurations.

An anonymous configuration copy file created by cOS Core will have a filename with following format:

 anonymous_config-<firewall-device-name>-yyyymmdd-v<version>.bak

Where yyyymmdd is the date of file creation and <version> is an integer which indicates how many times the configuration has been changed (the number of activations) since it was last in the default configuration state. For example:

 anonymous_config-MyFirewall-20210214-v081.bak

Note that creating an anonymous configuration copy can only be done using the Web Interface.

Example 2.38. Creating an Anonymous Configuration Copy File

This example shows how an anonymous copy of the current cOS Core configuration can be created using the Web Interface.

Web Interface

  1. Go to: Status > Maintenance > Technical Support
  2. Click the button Download configuration file
  3. A file chooser dialog will appear to save the file with a given filename to the local disk.
  4. Click OK

2.7. Maintenance

2.7.1. Software Upgrades

cOS Core Upgrades Require a Support Agreement

Clavister routinely releases minor and major upgrades to cOS Core software. However, it should be noted that these are only available to customers who have a current cOS Core support agreement.

Every Release Has Release Notes

Every cOS Core upgrade is accompanied by a release notes document which details the new features and changes which the release provides as well as any issues it addresses. The release notes also detail any considerations an administrator should be aware of before proceeding with an upgrade. In general, there should be no problems upgrading an older version of cOS Core to a newer version, but the release notes (and the change log, discussed later) will highlight any that might occur.

cOS Core Components

cOS Core consists of two upgradeable software components: the Core and the Loader. Usually it is the Core which is the main concern of the administrator since this is an executable binary and contains all of cOS Core's principal functional components. The Loader is a low level firmware loader which makes up the interface with the underlying hardware platform and this is updated only with some major revisions of cOS Core.

cOS Core Components

Figure 2.6. cOS Core Components

The Core Executable

Whenever new functionality is added to cOS Core, or when defects have been found and corrected, a new Core is produced which is the cOS Core executable binary. The new Core is packaged as a single file which is digitally signed and made available for download from the Clavister website https://www.clavister.com.

The Naming of Upgrade Files

In the distribution of software upgrades, a cOS Core upgrade filename can be one of the following types:

  • The filename will indicate a particular hardware. If there is an upgrade file specific for a particular Clavister hardware model, that file should always be used for upgrades on that model.

  • An x86 version which should be used for virtual environments such as VMware, KVM or Hyper-V.

The Types of cOS Core Upgrade

The following types of cOS Core releases may be available when performing an upgrade:

  • Maintenance Releases

    These often have bug fixes only but may also contain minor feature additions. They are freely available to all customers who are licensed to run the base version involved in the upgrade. The last two digits in the version number will change for this type of upgrade. For example, version 12.00.00 might become version 11.00.01.

  • Feature Releases

    These usually have both feature additions and bug fixes. They are freely available to all customers who are licensed to run the base version involved in the upgrade. The middle two digits in the version number will change for this type of upgrade. For example, version 12.00.03 might become version 12.01.00.

  • Major Releases

    These involve the addition of major new functionality to cOS Core as well as bug fixes. They are available to customers who have a valid software subscription service contract. The first two digits of the version number will change for this type of upgrade. For example, version 12.mm.nn might become version 13.mm.nn.

[Caution] Caution: The cOS Core license must allow upgrading

If the New upgrades until date parameter in the cOS Core license has passed so the license is no longer valid, cOS Core will enter lockdown mode following an upgrade and only management access will be possible.

The Upgrade Procedure for Administrators Connected Via a Network

Upgrading to a new version of cOS Core as an administrator connected to a firewall via a network is a simple procedure. A cOS Core upgrade is packaged as a single file with filetype .upg and this can be downloaded first from the Clavister website by logging into the relevant MyClavister user account and searching for the required .upg file. This file is then uploaded to the firewall by using either of the following methods:

  • In the Web Interface, go to: Status > Maintenance > Upgrade. Then choose the option Upgrade Unit's Firmware to select and upload the relevant .upg file.

  • Upload the file using Secure Copy (SCP). When cOS Core receives the file, it automatically recognizes that it is an upgrade file.

When the upload of a .upg file is complete using any of the above methods, cOS Core will automatically initiate a full system restart. Any live traffic will therefore be interrupted and connections lost while this takes place.

[Important] Important: Change the default password before upgrading

It is strongly recommended that the default password of the admin user is changed before performing an upgrade. The reason for this is that in some circumstances the administrator can become locked out if the default password is not changed and the new version requires an admin password that conforms to the strong password policy.

The alternative is to disable strong password enforcement before upgrading, in which case the default admin password does not need to be changed.

Upgrading cOS Core Using InControl

When one or more firewalls are being managed using the Clavister InControl product, cOS Core upgrades can be done by creating an upgrade job in the InControl client. These jobs allow large numbers of firewalls to be upgraded at one time, with the upgrade optionally performed automatically at a nominated time. This can significantly simplify the upgrading of a small or large firewall population and is described further in the Upgrading Devices section of the separate InControl Administration Guide.

The Web Interface Change Log

When applying an upgrade in the Web Interface, if there are important upgrade issues that the administrator should be aware of then a special page will be displayed by cOS Core before it begins the update process. This page is called The Change Log.

The issues highlighted by the change log will also appear in the release notes for the new version but being reminded of them immediately before the upgrade begins can be useful. The change log might include such potential problems as incompatibility with previous cOS Core versions and it may not appear at all if an upgrade does not have any issues.

Taking A Full System Backup Before Upgrading is Recommended

It is recommended to make a full system backup before performing a system upgrade. If there is a requirement to later reverse the upgrade, this should be done by performing a full system restore to the original cOS Core version and the original configuration.

Causes of Upgrade Failure and Warning Messages

An upgrade might fail in which case cOS Core will show an explanatory message in the Web Interface. The reasons for failure can be one of the following:

  • Invalid .upg file.
  • Incorrect file checksum.
  • Incorrect file signature.
  • Incorrect .upg type.
  • Incorrect file for the platform.

In addition to error messages, the Web Interface can also generate warnings about the following potential problems:

  • Downgrading to an earlier version. This should not be done unless completely necessary.

  • The license subscription expiry date does not cover upgrading to the new version. This is important because cOS Core will go into lockdown mode after an update if the license does not allow it, where only management access will be possible.

Upgrades in a Virtual Environment

When running cOS Core in a virtual environment under VMware, KVM or Hyper-V, upgrades of cOS Core can be done just as they are performed on a single physical computer. It is not necessary to create a new virtual machine for a new version.

[Note] Note: Leave Dynamic High Buffers enabled

It is recommended that the advanced setting Dynamic High Buffers is always left enabled (its default value) after an upgrade since the cOS Core memory allocations may have changed. A hardware restart is required for a change in the setting to take effect and this can be achieved using the CLI command:

Device:/> shutdown

In some scenarios support personnel might recommend disabling Dynamic High Buffers and setting High Buffers to a higher fixed value. Where cOS Core is handling tens of thousands of simultaneous connections then it may be necessary to manually set a value above the automatic value. However, if the HighBuffers value is set too high, this may adversely affect throughput.

See Section 13.10, Miscellaneous Settings for a full explanation of these settings.

Checking Memory After an Upgrade

A cOS Core upgrade sometimes introduces new features which will increase the system memory requirements. This can lead to performance issues if the amount of free memory becomes constrained. It is therefore advisable to check the amount of available free memory after a major upgrade which introduces new features. Configuration adjustments may be advisable if the amount of free memory during operation with live traffic seems too low (for example, by reducing the total number of connections allowed or reducing the number of configured VPN tunnels).

The issue of memory and performance is also discussed in Section 3.4.2.3, Changing RX and TX Ring Sizes. The description of the Dynamic High Buffers setting found in Section 13.10, Miscellaneous Settings also provides further information about memory allocation.

Downgrading cOS Core

As mentioned previously in this section, downgrading to an earlier cOS Core should be done by restoring a full cOS Core system backup. For this reason, creating a full system backup is recommended before a cOS Core version upgrade.

Downgrading by installing an older cOS Core version in the form of a .upg file (leaving the original configuration unchanged) is not supported as there may be differences in the newer cOS Core version that make the configuration incompatible with an older version. The results of such a mismatch are unpredictable.

New Release Notifications

Notifications of new cOS Core releases are sent out to the email address associated with MyClavister accounts. Email preferences can be adjusted by choosing the Settings option after logging into the relevant account at the following URL:

https://my.clavister.com

2.7.2. Version Update Alerts

Overview

cOS Core can optionally receive information from Clavister servers related to available upgrades. This information is displayed to the administrator as alerts in the Web Interface. This informs the administrator that upgrades are available. This feature is enabled by default and must be disabled manually by the administrator, as shown in the example at the end of this section.

When enabled, alerts of available upgrades appear only in the Alerts portion of the cOS Core Web Interface toolbar.

Communication with Clavister Servers is Encrypted and Periodic

Communication between cOS Core and Clavister servers is encrypted and occurs at the following times:

  • Shortly after system startup.

  • Once per day following startup.

Required Prerequisites

This feature will only function if all of the following are true:

  • cOS Core is operating with a valid license.

  • cOS Core has access to the Internet.

  • The feature has not been disabled by the administrator.

Log Event Message Generation

A log message is generated when an alert is generated for the administrator that version upgrades are available. This message has a severity level of Notice and the log event name new_firmware_available.

Example 2.39. Disabling cOS Core Release Notifications

This example shows how to disable the diagnostics and quality improvements feature.

Command-Line Interface

Device:/> set UpdateCenter CheckForPatchReleases=No
			CheckForFeatureReleases=No

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: Status > Maintenance > Update Center
  2. Disable the setting Maintenance Releases
  3. Disable the setting Feature Releases
  4. Click OK

2.7.3. Auto-Update Mechanism

A number of cOS Core security features rely on external servers for automatic updates and content filtering. The Intrusion Prevention and Detection subsystem and the Anti-Virus subsystem require access to updated signature databases in order to provide protection against the latest threats.

To facilitate the Auto-Update feature Clavister maintains a global infrastructure of servers providing update services for Clavister firewalls. To ensure availability and low response times, cOS Core employs a mechanism for automatically selecting the most appropriate server to supply updates.

For more details on these features see the following sections:

All these subsystems require that the customer has a current valid Clavister subscription agreement for the features to work and for the associated databases to be automatically updated. This is discussed further in Appendix A, Subscription Based Features

2.7.4. Backing Up Configurations

The administrator has the ability to take a snapshot of the cOS Core system at a given point in time and restore it later, if necessary. The snapshot can be of two types:

  • A Configuration Backup Copy

    This is a copy of the current cOS Core configuration saved into a single file. It does not include the installed cOS Core version. This copy can then be used later for restoring only the configuration.

    It is important to create, at a minimum, a configuration backup on a regular basis so that a configuration can be easily recreated in the event of replacement of the hardware platform. The alternative is to recreate a configuration by manually adding its contents, piece by piece.

    Note that it also possible to create an anonymous configuration copy where sensitive data is automatically replaced by randomly generated data. This is discussed further in Section 2.6.11, Creating an Anonymous Configuration Copy.

  • A System Backup Copy

    This a complete backup of both the configuration and the installed cOS Core software saved into a single file. This is useful if restoring both the configuration and the cOS Core version upgraded.

    A complete system backup is a much larger file than a configuration backup and can be many megabytes, it is therefore not recommended to perform this on a regular basis because of the time involved. However, it is recommended to create this at least once when the Clavister firewall is initially configured and goes live. This is because having a full system backup will make it easier to restore the current configuration on replacement hardware.

[Note] Note: Backups do not contain everything

Backups include only static information from the cOS Core configuration. Dynamic information such as the DHCP server lease database or Anti-Virus/IDP databases will not be backed up.

Version Compatibility

Since a full system backup includes the full cOS Core software version, compatibility is not an issue with these types of backup.

With configuration only backups, the following should be noted:

  • A configuration backup created on a higher cOS Core version should never be uploaded to a lower cOS Core version. For example, a backup created from a system running version 11.20.00 of cOS Core should never be uploaded to a system running version 11.10.02.
  • A configuration backup created on a lower version can always be uploaded to a higher version, however there can be compatibility issues in certain cases which will be indicated by messages from cOS Core when the uploaded configuration is activated. Such issues can also result in a restart of cOS Core.

    For this reason, a full system backup is useful when trying to transfer a saved configuration to new hardware where the new hardware comes preloaded with a higher cOS Core version. First, upload the full system backup to get a system with the right version and then upload the latest configuration backup. If there is a requirement to move to a higher cOS Core version, an upgrade can then be performed.

The Management Interfaces Used

Both types of backup, configuration and system, can be performed either by downloading the file directly from the firewall using SCP (Secure Copy) or alternatively using the Web Interface. Backup cannot be done using CLI commands.

Similarly, restoring a backup is done in the reverse fashion. Either by uploading the backup file using SCP or alternatively through the Web Interface. A restore cannot be done with CLI commands.

[Warning] Warning: Do not upload a system backup to dissimilar hardware

Do not try to upload a full system backup (configuration plus cOS Core) to a hardware platform that is not the same type as the original.

This will cause the configuration to be automatically activated and cOS Core rebooted, with the possibility that cOS Core becomes unreachable. Upload of full system backups must be done to similar hardware since there is no opportunity to change the configuration before it is activated.

Operation Interruption

Backups can be created at any time without disturbing cOS Core operation. For restores, however, it is not recommended to have live traffic flowing since the restored configuration may significantly alter the security policies of the firewall.

After restoring a backup it is necessary to Activate the new configuration, as is done with a normal configuration change.

A complete system restore will require that cOS Core reinitializes, with the loss of all existing connections. Initialization may require some seconds to complete, depending on the hardware platform, and normal operation will not be possible during this time.

Backup and Restore using SCP

There are two files located in the cOS Core root directory which are created when a download operation commences. These files have the following names:

  • config.bak - This is the backup of the current configuration.
  • full.bak - This is the backup of the complete system.

SCP can be used to download either of these files. When the download is complete, the administrator should alter the filename manually to include the date of the download.

To restore a backup file using SCP, the administrator should upload the file to the Clavister firewall. The name of the file does not need to be changed in any way since cOS Core will read a header in the file to determine that it is a backup file. Any SCP upload of a backup file will cause that file's contents to be restored.

Backup and Restore using the Web Interface

As an alternative to using SCP, the administrator can initiate a backup or restore of the configuration or complete system through the Web Interface. When the Web Interface is used, cOS Core automatically names the two files listed above to include the current date. For example, the full.bak might become full-20210906.bak to show it is a snapshot of the state on September 9th, 2021. The example below illustrates using the Web Interface.

Example 2.40. Downloading a Complete System Backup

In this example we will back up the entire system.

InControl

Backing up the system with InControl is done in a different way to the Web Interface

Web Interface

  1. Go to: Status > Maintenance > Backup and Restore > Backup System
  2. A file dialog is shown - choose a directory for the created file and change the filename from the default if desired.
  3. Download of the backup file will then start
[Tip] Tip: Examining configuration backup files

It is possible to open a configuration only .bak file in a normal text editor and examine its contents although the file will contain some binary information which means it cannot be modified and saved.

Furthermore, a configuration .bak file only shows object property values that are different from the default values. Therefore, the best way to examine the configuration in a .bak file is to load it into cOS Core and use the Web Interface to view it without saving and activating it.

2.7.5. Restore to Factory Defaults

A restore to factory defaults can be applied so that it is possible to return to the original system state when cOS Core was first installed. When a restore is applied, data such as the IDP and Anti-Virus databases as well as pcapdump files are not deleted. These must be explicitly removed by using the appropriate command. The license file is also not deleted.

Example 2.41. Complete Reset to Factory Defaults

Command-Line Interface

Device:/> reset -unit

InControl

This operation cannot be performed with InControl.

Web Interface

  1. Go to: Status > Maintenance > Reset & Restore > Reset
  2. Select Restore the entire unit to factory defaults then confirm and wait for the restore to complete.
[Important] Important: Any upgrades will be lost after a factory reset

It should be understood that a reset to factory defaults is exactly that. Any cOS Core upgrades performed since the unit left the factory will be lost.

Resetting to the Default cOS Core Configuration

An alternative to a complete factory reset is only resetting the firewall to its default configuration. This means that only the cOS Core configuration is reset to its factory defaults state, not the underlying hardware.

Resetting to the default configuration can be done through the CLI or Web Interface or InControl. When using the CLI, the command to do this would be:

Device:/> reset -configuration

Resetting only the default software configuration is important when preparing a firewall for the zero touch feature in the InControl management software. Zero touch is explained further in the separate InControl Administration Guide.

Reset via the Console Boot Menu

Connect via the local console port on the firewall using a console emulator on a computer or other device. Restart the firewall and press a key when the "Press any key to abort and load boot menu" message appears on the console. When the console boot menu appears, select the hardware reset option, then confirm and wait for the process to complete. Using the boot menu is described in Section 2.1.9, The Local Console Boot Menu.

[Warning] Warning: Do NOT abort a reset to defaults

If the process of resetting to factory defaults is aborted before it finishes, the firewall can then cease to function properly with the complete loss of all stored user data.

Interface IP Addresses are Reset

Resetting to defaults will reset the management interface and IP address for management access to the default.

Apart from the management interface, the operation will also reset the IPv4 address of all other Ethernet interfaces to be 127.0.x.1 in the network 127.0.x.0/24. The value "x" is a number that starts with "1" and increases by one for each consecutive interface, skipping the management interface.

The IPv4 address 127.0.0.1 is not used since this is reserved for the loopback interface.

End of Life Procedures for Hardware Products

The restore to factory defaults option should also be used as part of the end of life procedure when Clavister firewall hardware is taken out of operation and will no longer be used. Returning a hardware device to its default state will overwrite all sensitive information such as VPN settings.

As a further precaution at the end of a hardware product's life, it also recommended that the physical memory media in a hardware device is destroyed and certified as destroyed by a suitable provider of computer disposal services.

2.7.6. Listing and Adding Ethernet Interfaces

The CLI command pciscan is a tool that is used in listing and upgrading the Ethernet ports for the Clavister firewall. It is usually relevant only for non-Clavister hardware although it can be used for examining the PCI hardware in Clavister devices.

Checking Ethernet Interfaces

If the pciscan command is used without parameters then a list of all the supported Ethernet interfaces in the firewall is obtained:
Device:/> pciscan
		
Idx VendorID DeviceID Bus  Slot IRQ Driver Info
012 0x8086   0x1010    2    4   0 "E1000"  Intel NETWORK - ETHERNET
013 0x8086   0x1010    2    4   1 "E1000"  Intel NETWORK - ETHERNET
020 0x8086   0x1012    5    4   0 "E1000"  Intel NETWORK - ETHERNET
021 0x8086   0x1012    5    4   1 "E1000"  Intel NETWORK - ETHERNET
022 0x8086   0x1012    6    4   0 "E1000"  Intel NETWORK - ETHERNET
"
"
Each line in the output shows the current configuration for each Ethernet interface.

To see all Ethernet interfaces on the firewall, regardless if they are supported or not, the relevant command is:

Device:/> pciscan -ethernet

To see all hardware on the PCI bus, both Ethernet and non-Ethernet, the command is:

Device:/> pciscan -all

Automatic Recognition of New Interfaces in Virtual Environments

If a new Ethernet interface is added to the underlying platform in a virtual environment such as KVM, then this can be detected by cOS Core and the configuration updated automatically using the following command:
Device:/> pciscan -cfgupdate
However, this command is only relevant to cOS Core running in a virtual environment. It is not relevant to Clavister hardware products and will result in an error message if used.

Forcing the Choice of Driver

When using non-Clavister hardware, there may be PCI cards installed that require a driver that cannot be automatically selected using the -cfgupdate option. In such a case the administrator can explicitly choose the driver from a list using the -force_driver option.

The index number of the PCI card is first identified from the output of the pciscan -all command. If the card number index is found to be 7 and the driver to choose is E1000 then the command is:

Device:/> pciscan -force_driver 7 E1000

The command offers tab completion for the available driver names so it is not necessary to know them in advance. It may be the case that a process of trial and error is required to identify the correct driver for the card.

2.8. Licenses

2.8.1. Introduction

To use cOS Core in a live environment, a cOS Core license file must be installed on the firewall. Every Clavister firewall requires its own unique license file which is linked to properties of the underlying computing platform.

The purpose of a license file is to define what the capabilities and limitations a cOS Core installation has. Such capabilities include parameters such as the number of VPN tunnels allowed and the maximum number of routing tables.

For full details about license pricing, contact a Clavister sales office

SECaaS and Non-SECaaS Licenses

There are two types of cOS Core licenses:

  • Non-SECaaS Licenses

    This is the older form of license which is still used on older Clavister hardware products.

    The installation of non-SECaaS licenses is described in Section 2.8.2, License Installation on Clavister Hardware.

  • SECaaS Licenses

    A Security as a Service (SECaaS) license is a subscription based license which does not have a given expiry date. Rather, validity is based on the ongoing maintenance of a subscription. From the 4th quarter of 2021, some Clavister products require a SECaaS license. This includes a new license for cOS Core in all virtual environments and for newer hardware models such as the 100, 300, 500 and 6000 series.

    SECaaS license management is not different from non-SECaaS licenses on Clavister hardware products and this is described in Section 2.8.2, License Installation on Clavister Hardware.

    However, the installation and management of SECaaS licenses for virtual firewalls (under VMware, KVM or Hyper-V) is different and this is described in Section 2.8.3, License Installation on Virtual Firewalls.

    Note that a common requirement for all SECaaS licenses is that cOS Core has both Internet access and a public DNS server configured. SECaaS licenses require periodic contact with Clavister license servers and throughput will become limited if this is not available.

    The SECaaS license is also used by a Managed Service Provider (MSP) and is sometimes referred to as an MSP license.

Demo Mode

Without a valid license installed, cOS Core will operate for 2 hours from startup in demo mode (demonstration mode). In this mode a firewall will have full capabilities, just as though a full license were installed. However, note that any subscription based features such as anti-virus scanning and IDP will not function in demo mode.

After 2 hours in demo mode, cOS Core will cease to function normally and it will enter lockdown mode, meaning that all network traffic will be dropped except for management traffic. cOS Core will also output a demo mode expiry message on the local console.

cOS Core must be restarted to enable it for a further 2 hour period and there is no limit on how many times this can be done. To remove the 2 hour limit or disable lockdown mode, a valid license must be installed. This is discussed further in Section 2.8.5, Lockdown Mode.

License Files

A cOS Core license consists of a single license file with filetype .lic. This is a text file that defines all the cOS Core capabilities allowed by the license which includes a digital signature to ensure the file cannot be altered.

License files can be opened and viewed in a normal text editor. Alternatively, the license -show command could be used in the cOS Core CLI. Below is an example of an older non-SECaaS license:

Device:/> license -show
		 
Contents of the License file
----------------------------
  Registration key:            1234-5678-9123-4567
  Bound to MAC address:        41-84-93-13-CD-76
  Company:                     My-Company
  Subscription Based License:  NO
  Registration date:           2021-04-09
  Issued date:                 2021-05-05
  Last modified:               2021-05-05 09:22:15
  New upgrades until:          2028-04-09
  Centralized Management:      2028-04-09
  Premium technical support:   2028-04-09
  Hardware replacement:        Yes
  IP Reputation until:         2028-04-09
  Web Content Filtering until: 2028-04-09
  Antivirus service until:     2028-04-09
  IDP Signature service until: 2028-04-09
  Application Control until:   2028-04-09
  DCC until:                   2028-04-09
  Ethernet Interfaces:         6
  Max Connections:             4384000
  Max PBR Tables:              5
  Max Routes:                  512
  Max Rules:                   2000
  Max Throughput:              6200
  Max VPN Tunnels:             1000
  Max VPN Throughput:          4100
  Max GRE Tunnels:             (unlimited)
  Max SSLVPN Tunnels:          1000
  Max VLANs:                   64
  Max HA cluster size:         2
  RADIUS relay:                YES
  User authentication:         YES
  Max PPP Tunnels:             1000
  PPP Clients Available:       YES
  PPP Servers Available:       YES
  IKE Responders Available:    YES
  OSPF Router Processes:       YES
  Multicast:                   YES
  Traffic Shaping:             YES
  Rate Limiting:               YES
  Route Load balancing:        YES
  Route Failover:              YES
  Virtual Hardware:            NO
  Poll Offloading:             YES

The following should be noted about the license contents:

  • The license indicates both the type of the license and its various features, as well as any numerical limitations on different functions.

  • The Centralized Management parameter allows InControl to be used for management of the firewall up until the specified date. After that date, management using InControl will no longer be possible.

  • It will not be possible to deploy configurations that exceed the license limits for a function. For example, the Max Routes parameter controls the maximum number of routes that can be configured.

  • New connections that exceed the value specified for the Max connections parameter will be dropped.

  • IPsec tunnels are subject to restrictions in the license. This affects both the total number of tunnels that can be established (the Max VPN Tunnels parameter) as well as the total throughput for all tunnels (the Max VPN Throughput parameter).

    IPsec tunnel licensing restrictions are discussed further in Section 10.3.24.6, IPsec License Limitations.

  • The Max PPP Tunnels parameter will limit the aggregate total of L2TP and PPTP tunnels.

License Expiry Behavior

The behavior of the firewall when a non-SECaaS license expires is covered by an article in the Clavister Knowledge Base at the following link:

https://kb.clavister.com/324735788

More details on how individual subsystems behave (for example, anti-virus) can be found in Appendix A, Subscription Based Features.

2.8.2. License Installation on Clavister Hardware

Overview

Licenses used on Clavister hardware fall into two categories:

  • Older non-SECaaS licenses on older Clavister products such as the E10, E80B, W20B, W30, W40 and W50.

  • Subscription based SECaaS licenses for newer products like the 100, 300, 500 and 6000 series.

Regardless of the license type, license management is the same on hardware products. However, SECaaS licenses require the following to be configured in cOS Core:

  • Internet access must be configured in cOS Core.

  • At least one public DNS server must also be configured in cOS Core.

Any of the methods for license installation described in this section can be used with Clavister hardware. After installation of the initial license, the option also exists for automatic license updates where licenses can be automatically downloaded by cOS Core from the Clavister server.

License Installation with Zero Touch

A special case for license installation exists for certain hardware models when using the zero touch feature with the InControl management product. Zero touch allows certain hardware models to automatically come under InControl control as soon as they are connected to the Internet. This also means that their cOS Core license is automatically installed.

The zero touch feature is not discussed further in this guide. It is described in detail in a dedicated chapter of the separate InControl Administration Guide.

MyClavister Registration is Required

For both hardware and virtual firewalls, the administrator must first register as a user on the Clavister website by going to https://my.clavister.com.

After MyClavister registration, the appropriate cOS Core license will become available for download from the MyClavister server when the identifying codes on the casing of a Clavister hardware model are registered on MyClavister. This can be done either manually by a user logged into MyClavister, or automatically by cOS Core.

Installing a cOS Core License for Clavister Hardware Products

For a Clavister hardware product, the following license installation options are available. Note that none of the methods below that begin with "Automatic" in the heading, require manual registration of the hardware product on the Clavister website.

  • Automatic installation through the Web Interface Setup Wizard

    When cOS Core is started on a Clavister hardware product for the first time, a Setup Wizard runs that leads the administrator through a number of steps to simplify such tasks as enabling Internet access.

    The last few optional steps in the setup wizard allow the automatic retrieval across the Internet of a license for the hardware. This requires only that the username and password of the relevant MyClavister customer account is entered. If these last setup wizard steps are skipped, a license can be installed later in a separate operation, which is described next.

    Note that the setup wizard steps are described in detail in the separate Getting Starting Guide for each hardware product.

  • Automatic installation through the Web Interface

    If linking with MyClavister and downloading of a license was not done using the Setup Wizard (described above), then this linking can be done later using the following steps:

    1. In the cOS Core Web Interface, go to Status > Maintenance > MyClavister.

    2. Enter the MyClavister username and password credentials for the relevant user account.

    3. Press the Login button followed by the Activate button to establish the link with the Clavister server.

    4. Go to Status > Maintenance > License in the Web Interface and press the Download button. The correct license will be fetched automatically across the Internet and installed.

      Note that the Upload button on the same web page is only used to upload a license file that was already on the local disk of the management computer.

  • Automatic installation through the CLI

    Use the following command in the cOS Core CLI:

    Device:/> license -activate -request -username=myname -password=mypass

    The customer username and password is included in the command so the license can be fetched automatically across the Internet. It is then necessary to manually enter the reconf or shutdown command to complete installation. The shutdown command is recommended as this restarts the firewall.

  • Manual installation through the Web Interface or using SCP

    Installing a license manually consists of the following steps:

    1. In a web browser, go to https://my.clavister.com and log into relevant MyClavister account.

    2. In MyClavister, go to Licenses > Register License.

    3. Select the option Register by Service Tag and Hardware Serial Number.

    4. Enter the Serial Number and Service Tag codes. For Clavister hardware products, these codes are found on a label on the unit. This will cause a new license to be generated and stored on the website. This license will appear in the user's license list on the site.

    5. Download the license to the management computer's local disk by clicking on it in the license list.

    6. In the cOS Core Web Interface, go to Status > Maintenance > License and press the Upload button to select the license file from the local disk. Following upload, cOS Core will ask if a reconfigure or restart should be performed to activate the new license. A restart is recommended.

      Alternatively, upload the license file using SCP. cOS Core will automatically recognize an uploaded license file but it is still necessary to manually to perform a reconfigure or restart operation to complete installation. A restart is recommended.

[Note] Note: Fetching licenses requires Clavister website access

When cOS Core communicates with the Clavister server, it first performs a DNS lookup of www.clavister.com and then opens a connection to the returned IPv4 address using port 80. Any network equipment that is located between the Clavister firewall and the Internet must permit this connection.

[Important] Important: A restart is recommended after installing a license

Some license changes, such as increasing the number of allowed VPN tunnels, change memory requirements and will not take effect until after cOS Core is restarted. Restarting will disrupt traffic flows but is recommended in order that all license parameters become active. If only a reconfiguration operation is performed, not all license parameters may come into effect although this does not disrupt traffic.

When installing a license through the Web Interface or when using the startup wizard, the options to restart or reconfigure are presented to the administrator. With the CLI and SCP, these options are not presented and restart must be initiated by the administrator.

For restarting via the Web Interface, go to Status > Maintenance > Reset & Restart. With the CLI, use the command:

Device:/> shutdown -reboot

How to Perform SCP License Uploading

When a license file needs to be uploaded to the firewall, SCP can be used.

Only one license file can exist on the Clavister firewall. The name of the file is not mandatory, and neither is the location since cOS Core will detect the file by examining its contents. By convention, the license file should be called license.lic and it should be uploaded to the top level of the cOS Core directory structure.

Under Linux the SCP upload command to a firewall called fw_name might be:

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

Under Microsoft Windows, the SCP upload would be performed using an appropriate SCP utility. For example, when using the PuTTY tool under Windows, the command line would be of the following form:

> pscp -scp -pw <pswd> <file-name.lic> admin@<IP-address>

2.8.3. License Installation on Virtual Firewalls

For cOS Core running in a virtual environment (such as VMware, KVM or Hyper-V) a subscription based Security as a Service (SECaaS) license must be installed and the installation procedure differs from installation on Clavister hardware.

The following should be noted for SECaaS license installation on a virtual platform:

  • The first time the SECaaS license is installed, it must be done manually.

  • SECaaS licenses require Internet access by cOS Core.

    Internet access is required for SECaaS license installation, as well as for continuously verifying and updating licenses. cOS Core must also have a public DNS server configured for the resolution of FQDNs.

  • Updates to the original license are installed automatically across the Internet and this is enabled by default.

Registering the SECaaS License on MyClavister

Before the SECaaS license becomes active, it must first be registered in the relevant MyClavister account. This requires the following steps:

  1. Go to the Clavister website and log into MyClavister.

  2. Select Register new license.

  3. Select the License Number and SECaaS ID option.

  4. Enter the license number and SECaaS ID for the license (these codes are supplied by Clavister).

  5. Press Register License.

An Older Non-SECaaS License Must First Be Deleted

If an older, non-SECaaS license is already installed, it must be deleted using the command:
Device:/> license -remove
This should be followed by the reconfiguration command:
Device:/> reconf

Installing the SECaaS License

Following registration and the deletion of any non-SECaaS license, the SECaaS license can be installed by automatically downloading it from the license server to cOS Core. This can be done with either the Web Interface or the CLI:

  • Installation with the CLI

    Enter the following CLI console command either remotely via SSH or locally using the firewall console:

    Device:/> license -secaas_add <secaas-system-id> <secaas-reg-key>

  • Installation with the Web Interface

    Open the Web Interface for the firewall and go to: Status > Maintenance > License. Enter the SECaaS system identifier and registration key, then press Register.

Note that installation steps for a SECaaS license in a virtual firewall, along with an example console session, are included in an article in the Clavister Knowledge Base at the following link:

https://kb.clavister.com/336145229

Deleting a SECaaS License

If the SECaaS license is to be deleted on a virtual firewall, the steps are the following:

  1. Disconnect cOS Core from the Internet, otherwise cOS Core may automatically reinstall the license.

  2. Enter the CLI console command:

    Device:/> license -remove

  3. Perform a reconfiguration operation with the command:

    Device:/> reconf

  4. After the reconfiguration operation completes, enter the command:

    Device:/> license -secaas_remove

  5. cOS Core will now automatically restart without the SECaaS license and SECaaS functions present.

SECaaS License Verification and Updating

Once a SECaaS license is installed, cOS Core will check every 4 hours that the license is valid and also check for any license updates. It does this by contacting the Clavister Service Provider Network (SPN) across the Internet.

If a newer license is found, cOS Core will download it and install it immediately. If verification fails the firewall will enter lockdown mode and only management access will be possible. A verification failure might be caused by license expiry, a faulty license file or a blacklisted license.

SECaaS Licenses with High Availability

When SECaaS licenses are used in a high availability (HA) cluster, both firewalls in the cluster must have an appropriate SECaaS license installed and both will independently try, like a standalone firewall, to contact the Clavister license server to verify the installed license.

However, a difference with HA is that if one of the cluster peers fails to make contact with the license server, it will query the license status of the other peer in the cluster. If the other peer has has had its SECaaS license verified then it too will become verified.

Reduced Functionality Mode

If cOS Core with a SECaaS license cannot contact the Clavister SPN for a grace period of 2 weeks, it will enter reduced functionality mode. This mode means that cOS Core operates as before but with the following restrictions:

  • The maximum total throughput of the firewall becomes 1 Mbps.

  • All log message generation is disabled except for log messages related to licenses.

Note that reduced functionality will also be entered if the license validity date expires during the 2 week grace period.

2.8.4. License Updating on Clavister Hardware

Updating an installed non-SECaaS license with a new one may be required because of license expiry or a change in the capabilities allowed by a license such as, for example, increasing the throughput limit or the total number of allowed connections.

There are two methods for updating installed licenses:

  • Manual Updating

    The existing license can be replaced with a new license by first downloading the license file from the Clavister website and then uploading it to the firewall using the Web Interface or SCP. Uploading the new license will automatically overwrite the old license.

    The steps for a manual update are the same as the steps used for the manual license installation described above in Section 2.8.2, License Installation on Clavister Hardware.

  • Automatic Updates

    Provided that it has Internet access, cOS Core will periodically check if a new license is available for download from the Clavister license server. If a new license becomes available, cOS Core will generate an alert for this in the Web Interface. After opening the alert, the administrator must then confirm that the new license should be automatically downloaded and installed.

    The automatic update feature is available with all Clavister hardware models as well as with virtual firewalls running in any of the supported virtual environments. Enabling the feature is described next.

Enabling Automatic Updates

For the automatic update feature to function, the administrator must have created a link between the firewall and the Clavister website at some point in time. This can be done in one of the following two ways:

  • In the Setup Wizard

    As one of the last steps in the cOS Core setup wizard. The wizard runs automatically as a pop-up window when the Web Interface is opened for the first time for a Clavister hardware device. In the step after the wizard's configuration activation step, the administrator can optionally enter their login credentials for the Clavister website. This establishes the link between the hardware and the website and does not need to be repeated later.

    Note that this option does not exist for cOS Core running in a virtual environment. The link can only be established after the initial license has been installed manually.

  • After cOS Core Has Initialized

    If the link with the Clavister website was not established with the setup wizard (and this will be the case with cOS Core running in a virtual environment) then it can be established later in the Web Interface by going to Status > Maintenance > My Clavister and entering the login credentials for the Clavister website.

    Alternatively, the following CLI can be used instead of the Web Interface:

    Device:/> license -myclavister -username=myuser -password=mypass

License Update Alerts

Even if automatic license updates have not been enabled, cOS Core will check for if a license update is available at the following times:

  • When the login credentials are entered in the MyClavister page in the Web Interface.

  • Automatically, every time the administrator logs in to the Web Interface.

  • When the Check button is pressed on the license page of the Web Interface.

If cOS Core detects a license update is available from the Clavister servers, the following alert will appear in the Web Interface, as shown below:

License Update Alerts

Figure 2.7. License Update Alerts

As stated above, the check for new license availability can be done without establishing the link with a Clavister MyClavister account. However, actually downloading and installing the license automatically is not possible without this link.

Initiating the License Update

Clicking the link in the license update alert will open the Web Interface license page. Provided the link with the license server has been previously established by entering the Clavister website login credentials, the Download button on the license page can be pressed to initiate the installation.

Restarting the firewall following installation is not required but is recommended. It may be necessary to reconfigure cOS Core correctly for any changes in the system's capabilities (for example, if the connection limit has increased).

Disabling Automatic Updates

If it is required to disable automatic updates then the link between the firewall and the Clavister website must be disabled. This is done by going to Status > Maintenance > My Clavister in the Web Interface and selecting the Logout option.

Alternatively, the same operation can be performed in the CLI with the following command:

Device:/> license -myclavister -disconnect

Downloading New Licenses with the CLI

There is no such alert capability in the CLI. However, providing the link between the device and the Clavister website has already been established, the following command can be entered to download and install any available license:
Device:/> license -downloadlicense

The Choice Between Restart and Reconfigure

As with installing a license for the first time, a restart of cOS Core after installing a license update is recommended so that the system is correctly configured for any changes in the license capabilities.

However, if the disruption to traffic flow caused by a restart is not desirable, a reconfigure operation can be performed instead. This will implement any license parameter changes but will not reallocate any memory that such changes might require for optimum performance. An example of a license change where a reconfigure is well suited is a change in validity dates, since this would not affect memory allocation in the firewall.

2.8.5. Lockdown Mode

cOS Core will enter a state known as Lockdown Mode if certain conditions occur. While in lockdown mode, only management traffic is allowed by the firewall and all other traffic will be dropped (local console access is still possible). Unlike the two hour time limit of Demo Mode, there is no time limit with lockdown mode.

Causes of Lockdown Mode

Conditions that trigger lockdown mode include the following:

  • The two hour demo mode has expired when no license is present.

  • Using the license on the wrong hardware.

  • An invalid license file signature.

  • Uploading a new revision of cOS Core when the New upgrades until parameter in the license file has passed.

  • A shared IPv4 address in an HA cluster has been set to the value 0.0.0.0.

  • The license is in some other way invalid.

Ending Lockdown Mode

When lockdown mode is entered, the condition can be terminated by installing a valid license or removing the configuration violation that triggered the condition. Removing the current license will cause cOS Core to enter the 2 hour demo mode from lockdown mode. This might be necessary to allow traffic to flow to the Internet in order to download a new license file.

If a valid license is not available then cOS Core needs to be restarted to end lockdown mode and this will begin another 2 hour demo mode period.

2.8.6. Licensing Issues

Behavior After Exceeding License Limits

When the administrator tries to change the cOS Core configuration in such a way that it exceeds the limitations of the current license, it will not be possible to deploy the configuration. This means that there is no disruption to live traffic if license parameters are exceeded.

This is similarly true when restoring a backup with a configuration that exceeds the limitations of the installed license. cOS Core will detect if the restored configuration exceeds any license limits and revert to the old configuration if it does.

The cOS Core objects that are subject to this behavior are as follows:

  • IPsecTunnel
  • L2TPClient
  • L2TPServer
  • L2TPv3Server
  • PPPoETunnel
  • SSLVPNInterface
  • RoutingTable
  • GRETunnel
  • VLAN

The behavior of IPsec is controlled by the license parameter PROP_TUNNELS. This limits the total number of IPsecTunnel objects that can be created but also how many live IPsec tunnels can be opened across the system. In a roaming clients situation, a single IPsecTunnel object could have thousands of tunnels associated with it. If an attempt is made to set up a tunnel so that the total number of IPsec tunnels across the system exceeds the PROP_TUNNELS limit, the attempt fails and a log message is generated to indicate the license limit is exceeded.

If present, the PROP_PPPTUNNELS license parameter controls the combined total number of L2TPClient, L2TPServer, L2TPv3Server and PPPoETunnel objects that can be created. If PROP_PPPTUNNELS is not specified in a license, the value defaults to the same value as PROP_TUNNELS.

The number of Route and IPRule objects are not subject to license restrictions although, for backward compatibility, these appear as license parameters.

[Warning] Warning: More restrictive licenses can cause lockdown

If a more restrictive license is loaded into cOS Core so that the existing number of an object type exceeds the limit of the new license, this will cause lockdown to occur. This situation must then be resolved by either the administrator reverting to the old license or editing the configuration to reduce the number of objects to be within the limits of the new license.

Ensure the Maximum Connections Parameter is Adequate

The cOS Core license file specifies the maximum number of concurrent traffic connections that cOS Core will allow. This is the parameter Max Connections in the file. It is important to have the appropriate value for this parameter so that it is never exceeded. If the setting DynamicMaxConnections is enabled then this license maximum will be used as the maximum allowed.

If the connection limit is exceeded then a connection_table_full log message is generated and the action specified by the advanced setting Connection Replace is followed. By default, this action is ReplaceLog which means that the oldest connection is dropped by cOS Core to allow the new connection to succeed.

Both the Max Connections and Connection Replace settings are discussed further in Section 13.4, State Settings. Note that any changes to the maximum allowed connections should be done with a minimum of live traffic. This is because a change may cause the connection table to be reinitialized so that all current connections are dropped and this will happen as soon as the configuration change is activated.

Replacing Hardware

If the hardware unit is replaced with another unit but the same license is to be used, the same procedures should be followed for installing the license in the new unit. The separate Hardware Replacement Guide covers this topic in detail.

License Swapping with the Cold Standby Service

Clavister customers can choose to make use of a facility called the Cold Standby (CSB) Service. This provides a duplicate hardware unit on customer premises to quickly replace a faulty unit. In this case, the license on the faulty hardware can be quickly transferred to the CSB unit through a special option on the Clavister website.

The CSB service and the CSB license swapping procedure is described fully in a dedicated chapter of the separate Hardware Replacement Guide.

HA Cluster Licensing

In a cOS Core High Availability Cluster, two identical licenses must be purchased, one for the master and one for the slave unit. Both licenses must include the ability to allow HA clustering.

[Important] Important: Use the correct license for hardware products

It is important to always use the correct license file for Clavister hardware product.

If licenses are not matched correctly to the product, complex administrative problems can arise later which can cause delays in rectifying problems.

2.9. Languages

The graphical management interface for cOS Core is available in a number of different languages. The language is selected from a dropbox when the interface is opened.

The selected language displayed in the graphical interface is read by cOS Core from one of a set of separate language files which reside in the non-volatile memory of the firewall. These files can be displayed and managed using the CLI languagefiles command and all of them have the filetype .RC.

To see all the available language files, use the command with no options:

Device:/> languagefiles
Language files
      LNG-CH.RC  -->  "Chinese"

The output shows that only the Chinese language file is present.

To delete a language file, use the -remove option:

Device:/> languagefiles -remove=LNG-CH.RC
Removing "LNG-CH.RC" ...OK

If there are no language files present, the following output is seen:

Device:/> languagefiles
Language files
  No language files found

The default language of English is hard-coded into cOS Core and does not appear as a file in the list.

2.10. Diagnostics and Improvements

Overview

To help Clavister improve cOS Core and related services, cOS Core includes a telemetry feature known as Diagnostics and Improvements. This consists of the optional ability of cOS Core to automatically send informational messages back to Clavister servers about the cOS Core installation.

This feature is enabled by default but can be disabled manually by the administrator, as shown in the example at the end of this section.

Communication is Encrypted and Periodic

Communication between cOS Core and Clavister servers is encrypted and occurs at the following times:

  • Shortly after system startup.

  • Once per day following startup.

The exception to the above are crash reports which are only sent once, after an anomalous event occurs.

Information Sent to Clavister

If the diagnostics and improvements feature is enabled, the information returned to Clavister by cOS Core can be of the following types:

  • Anonymous diagnostic reporting

    This information relates to the static parameters of cOS Core and includes the cOS Core version number and the version number of any installed databases such as the anti-virus or IDP database.

  • Anonymous diagnostic reporting plus usage statistics

    This is enabled by default. The usage statistics provide a higher level of detail on system operation and includes parameters such as:

    • System uptime.
    • Installed RAM memory size.
    • CPU load.
    • RAM memory usage.
    • Web content filtering statistics (if enabled).

  • Crash reports

    This is enabled by default and will send encrypted and anonymous information to Clavister if an anomalous system event occurs. A crash report is only sent once after such an event and it can help Clavister support engineers determine where in cOS Core a problem occurred and why.

[Note] Note: Log event messages are not generated

No log messages are generated when diagnostics and improvement information is sent by cOS Core back to Clavister.

Connecting with My Clavister

An additional option that can help Clavister with troubleshooting is to enable the option Connect with My Clavister. This means that the Diagnostics and Improvements information described above is no longer sent anonymously and Clavister can determine which customer using which license has sent the data.

For the option to function, cOS Core must have been associated with a My Clavister customer account at some time. This is often done as part of the initial setup procedure when using the Setup Wizard. If it has not, it can be done manually in the Web Interface by going to: Status > Maintenance > License.

This option is disabled by default. It must be explicitly enabled by the administrator. However, any such reported information that is held in Clavister databases can be deleted at any time by the administrator and this is done by logging in to the customer account on the Clavister website and selecting the relevant deletion option.

Example 2.42. Disabling Diagnostics and Quality Improvements Messaging

This example shows how to disable the diagnostics and quality improvements feature.

Command-Line Interface

Device:/> set Settings DiagnosticSettings EnableDiagnostics=No

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: System > Advanced Settings > Diagnostic Settings
  2. Disable the setting Anonymous Diagnostics Reporting
  3. Click OK

Chapter 3: Fundamentals

3.1. The Address Book

3.1.1. Overview

The cOS Core Address Book contains named objects representing various types of IP addresses, including single IP addresses, networks as well as ranges of IP addresses. Ethernet MAC addresses can also be defined in the address book.

Using address book objects has a number of important benefits:

  • It increases understanding of the configuration by using meaningful symbolic names.

  • Using address object names instead of entering numerical addresses reduces errors.

  • By defining an IP address object just once in the address book, changing the definition automatically also changes all references to it.

3.1.2. IP Address Objects

IP Address objects are used to define symbolic names for IPv4 and IPv6 addresses. An address object can represent either a single IP address (a specific host), a network or a range of IP addresses.

IP Address objects can additionally be used for specifying the credentials used in user authentication. For more information about this topic, see Chapter 9, User Authentication.

An address object for a simple IP address can be one of two types:

  • An IP4 Address object for IPv4 addresses.

  • An IP6 Address object for IPv6 addresses.

This section now goes on to describe the various ways that an IP4 Address object can be used. IP6 Address objects are described further in Section 3.2, IPv6 Support.

IPv4 Address Types

The following list presents the various types of addresses an IP4 Address object can hold, along with what format is used to represent that specific type:
  • Host

    A single host is represented simply by its IP address. For example, 192.168.0.14.

  • IP Network

    An IP Network is represented using Classless Inter Domain Routing (CIDR) form. CIDR uses a forward slash and a digit (0-32) to denote the size of the network as a postfix. This is also known as the netmask.

    /24 corresponds to a class C net with 256 addresses (netmask 255.255.255.0), /27 corresponds to a 32 address net (netmask 255.255.255.224) and so on.

    The numbers 0-32 correspond to the number of binary ones in the netmask. For example: 192.168.0.0/24.

  • IP Range

    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 netmask boundaries. They may include any span of IP addresses. For example, 192.168.0.10-192.168.0.15 represents six hosts in consecutive order.

Using a /31 Subnet Mask (RFC-3021)

It is possible to use an IPv4 31 bit subnet prefix (as defined in RFC-3021) in the cOS Core address book but some special considerations are required, otherwise this may be rejected by cOS Core. This topic is discussed further in an article in the Clavister Knowledge Base at the following link:

https://kb.clavister.com/324735678

Example 3.1. Adding a Simple IP4 Address

This example adds the IPv4 host wwwsrv1 with IP address 192.168.10.16 to the address book:

Command-Line Interface

Device:/> add Address IP4Address wwwsrv1 Address=192.168.10.16

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: Objects > Address Book > Add > IP4 Address
  2. Specify a suitable name for the IP host, in this case wwwwsrv1
  3. Enter 192.168.10.16 for the IP Address
  4. Click OK

Example 3.2. Adding an IPv4 Network

This example adds an IPv4 network named wwwsrvnet with address 192.168.10.0/24 to the address book:

Command-Line Interface

Device:/> add Address IP4Address wwwsrvnet Address=192.168.10.0/24

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: Objects > Address Book > Add > IP4 Address
  2. Specify a suitable name for the IP network, for example wwwsrvnet
  3. Enter 192.168.10.0/24 as the IP Address
  4. Click OK

Example 3.3. Adding an IPv4 Range

This example adds a range of IPv4 addresses from 192.168.10.16 to 192.168.10.21 and names the address object wwwservers:

Command-Line Interface

Device:/> add Address IP4Address wwwservers
			Address=192.168.10.16-192.168.10.21

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: Objects > Address Book > Add > IP4 Address
  2. Specify a suitable name for the IP Range, for example wwwservers.
  3. Enter 192.168.10.16-192.168.10.21 as the IP Address
  4. Click OK

Example 3.4. Deleting an Address Object

To delete an object named wwwsrv1 in the address book, do the following:

Command-Line Interface

Device:/> delete Address IP4Address wwwsrv1

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: Objects > Address Book
  2. Select the address object wwwsrv1
  3. Choose Delete from the menu
  4. Click OK

Deleting In-use IP Objects

If an IP object is deleted that is in use by another object then cOS Core will not allow the configuration to be deployed and will generate a warning message. In other words, it will appear that the object has been successfully deleted but cOS Core will not allow the configuration to be saved to the firewall.

3.1.3. Ethernet Address Objects

Ethernet Address 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 numerical Ethernet addresses.

When specifying an Ethernet address the format aa-bb-cc-dd-ee-ff should be used. Ethernet addresses are also displayed using this format.

Identifying the Related Hardware Manufacturer

A MAC address can be used for identifying the manufacturer of the related hardware and this is covered further in a Clavister Knowledge Base article at the following link:

https://kb.clavister.com/309987726

The cOS Core Device Intelligence feature provides the ability to identify information about external devices from their MAC addresses. This feature is fully described in Section 3.5.6, Device Intelligence.

Example 3.5. Adding an Ethernet Address

The following example adds an Ethernet Address object named wwwsrv1_mac with the numerical MAC address 08-a3-67-bc-2e-f2.

Command-Line Interface

Device:/> add Address EthernetAddress wwwsrv1_mac
			Address=08-a3-67-bc-2e-f2

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: Objects > Address Book > Add > Ethernet Address
  2. Specify a suitable name for the Ethernet Address object, for example wwwsrv1_mac
  3. Enter 08-a3-67-bc-2e-f2 as the MAC Address
  4. Click OK

3.1.4. Address Groups

Groups Simplify Configuration

Address objects can be grouped together in order to simplify configuration. Consider a number of public servers that should be accessible from the Internet. The servers have IP addresses that are not in a sequence, and can therefore not be referenced as an IP range. Consequently, individual IP Address objects have to be created for each server.

Instead of having to cope with the burden of creating and maintaining separate security policies that allow traffic to each server, an Address Group, for example called web-servers, could be created with the web server hosts as group members. Now, a single IP rule set entry can use the group as part of its filtering criteria, greatly simplifying the administrative task.

Address Group Types

An address group object can be one of the following types:
  • An IP4 Group object - This can contain only IPv4 Address objects as members.

  • An IP6 Group object - This can contain only IPv6 Address objects as members.

  • An Ethernet Address Group object - This can contain only Ethernet Address objects as members.

  • An FQDN Group object - This can contain only FQDN Address objects as members.

Group Membership Can Mean Inclusion or Exclusion

When groups are created with the Web Interface or InControl, it is possible to not only add address objects but also to explicitly exclude addresses from a group. However, it should be noted that excluding addresses from a group is not possible when manipulating groups using the CLI.

Exclusion from a group should not be confused with removing a member of a group. The excluded address object is still a member of a group but its effect on the group is to subtract from the IP address space described by the group.

For example, if a group member has the value 192.168.2.0/24, the single IPv4 address 192.168.2.1 could be an excluding member of the group. This will result in the group being equivalent to the range 192.168.2.2 to 192.168.2.255.

Groups Can Contain Different Subtypes

Although groups must contain the same type of object (for example, IP4 addresses), it is possible to mix subtypes in a group. For example, single IPv4 addresses can be combined with IPv4 ranges and IPv4 networks in an IP4 Group. The group will represent a union of all the member object's addresses.

For example, suppose an IP4 Group contains two member IP4 Address objects with the following IP address ranges:

  • 192.168.0.10 - 192.168.0.15
  • 192.168.0.14 - 192.168.0.19

The union represented by this group will be an address range of 192.168.0.10 - 192.168.0.19.

Adding and Removing Group Members Using the CLI

Once a group is established, it is often useful to be able to add new members or remove existing members. This is easily done with the Web Interface which provides an intuitive display showing the available objects and the objects in the group. It can also be done with the CLI but requires a special command syntax.

Suppose there already exists an IP4Group object called my_ip_group. It has three member IP4Address objects called my_ip_1, my_ip_2 and my_ip_3. Suppose that the object my_ip_2 is to be removed from the group. The command would be:

Device:/> set Address IP4Group my_ip_group Members-=my_ip_2

The option Members-= can remove one or more members of the group. To add one or more members to a group, the option Members+= can be used. Suppose that the IP4Address objects my_ip_4 and my_ip_5 are to be added to the group. The command would be:

Device:/> set Address IP4Group my_ip4_group Members+=my_ip_4,my_ip_5

Example 3.6. Creating an IP4 Group Object

This example assumes that two IP4 Address objects already exist in the address book and these are called my_ip4_address1 and my_ip4_address2. These addresses are to be combined into a single IP4 Group called my_ip4_group.

Command-Line Interface

Device:/> add Address IP4Group my_ip4_group
			Members=my_ip4_address1,my_ip4_address2

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: Objects > Address Book > Add > IP4 Group
  2. Specify the name as my_ip4_group
  3. Select my_ip4_address1 and press Include
  4. Select my_ip4_address2 and press Include
  5. Click OK

3.1.5. Auto-Generated Address Objects

To simplify the configuration, a number of address objects in the address book are automatically created by cOS Core when the system starts for the first time and these objects are used in various parts of the initial configuration.

The following address objects are auto-generated:

  • Interface Addresses

    For each Ethernet interface in the system, two IP Address objects are predefined; one object for the IPv4 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.

    These addresses are stored in an address book folder called InterfaceAddresses. However, in virtualized configurations, these addresses will be top level address book entries.

    On some older Clavister hardware models, the underscore is left out from the auto-generated interface network name. For example, the lan interface will have the network object lan_net.

    When changing the IP address of an Ethernet interface, it is strongly recommended to change the address of the default address book object and not change the IP address directly on the Ethernet interface.

  • The Default Gateway Address

    On most cOS Core hardware platforms, an IPv4 Address object with the suffix "_gw" is also auto-generated for the default interface used for connection to the Internet. For example, if the Internet connection is assumed to be on interface wan then the default gateway address gets the name wan_gw. This IP address represents the external router which acts as the gateway to the Internet.

    This address is used primarily by the routing table, but is also used by the DHCP client subsystem to store gateway address information acquired through DHCP. The object will have an empty IP address (0.0.0.0/0), and the correct IP address for the default gateway needs to be defined unless DHCP is being used and assigns it automatically.

  • The all-nets Address Object

    The all-nets IP address object is initialized to the IPv4 address 0.0.0.0/0, which represents all possible IPv4 addresses. The all-nets IP object is used extensively when configuring of cOS Core and it is important to understand its significance.

3.1.6. Address Folders

In order to help organize large numbers of entries in the address book, it is possible to create one or more Address Folder objects in the address book. These act like a folder in a computer's file system. They are created with a given name and can be used to gather together related address objects.

Using folders is simply a way for the administrator to conveniently divide up address book entries and no special properties are given to entries in different folders. cOS Core continues to see all entries as though they were in a large table of IP address objects.

The folder concept is also used by cOS Core in other contexts such as IP rule sets, where related entries can be grouped together in administrator created folders.

As discussed previously, there will already be a default folder created on initial startup called InterfaceAddresses which contains the default address objects for all the Ethernet interfaces detected by cOS Core.

Example 3.7. Adding an Address Folder Object

This example adds a new Address Folder object called my_address_folder.

Command-Line Interface

Device:/> add Address AddressFolder my_address_folder

InControl

Follow similar steps to those used for the Web Interface below.

Web Interface

  1. Go to: Objects > Address Book > Add > Address Folder
  2. Specify the name as my_address_folder
  3. Click OK

3.1.7. FQDN Address Objects

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) in an FQDN Address object. cOS Core will then automatically resolve the FQDN to an IP address when the object is referenced by other configuration objects.

FQDN Address Object Properties

An FQDN Address object has the following properties:

  • Name - The logical name of the object. This is specified by the administrator.

  • Address - The FQDN of the object. This is specified by the administrator.

  • Active Address - If the FQDN has been resolved then this will be the FQDN's IP address. Otherwise, this property has no value assigned to. This property can only be set by cOS Core.

Rules and Objects Supporting FQDN Address Object Usage

Currently, only the following types of cOS Core objects can contain a reference to an FQDN Address object.

  • The source and/or destination networks of an IP Policy object.

    Note that FQDN Address objects cannot be used with IP Rule objects.

  • The source and/or destination networks of Goto Rule or Return Rule objects in IP rule sets.

  • The source and/or destination networks of a Routing Rule.

  • The source and/or destination networks of an IDP Rule object.

  • The source and/or destination networks of a Pipe Rule object used for traffic shaping.

  • The source and/or destination networks of a Threshold Rule object used for traffic rate limiting.

  • The remote endpoint of an IPsec Tunnel object.

  • As the SMTP Server property of a Mail Alerting object.

  • The IP address of a custom time server when configuring the system date and time.

FQDN Resolution Requires a Configured DNS Server

For FQDN Address objects to function correctly, at least one external DNS server must be configured by creating a DNS Server object. For a description of configuring DNS servers in cOS Core, see Section 3.10, DNS

It is also important that the DNS server that resolves FQDN addresses and the replies it sends back can be trusted. Trust in the server is usually only an issue when a private DNS server is being used. If a server is compromised or its replies can be faked then this could result in FQDN queries being resolved to the IP addresses of malicious websites.

DNS Lookups Should Be Consistent Across Hosts and Firewalls

The administrator should ensure that the DNS lookup used for FQDN Address objects referenced by IP Policy 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 Core is using the same DNS server as the hosts it is protecting.

FQDN Address Object Usage Triggers FQDN Resolution

cOS Core will try to perform the DNS resolution only when a new configuration is deployed and that configuration makes use of an FQDN Address object. In other words, an FQDN Address object might already be in the current cOS Core configuration but the DNS lookup will only be performed when the configuration is changed so that the address object is referred to by, for example, an IP Policy object.

If no DNS server is configured, cOS Core will generate an error when attempting to deploy a configuration that makes use of an FQDN Address object in, for example, an IP Policy object.

Behavior With DNS Resolution Failure

If an FQDN Address object cannot be resolved to an IP address by cOS Core then any rules that reference the object will not be triggered by any traffic (in other words, it will appear as though the rules do not exist in the configuration).

Similarly, an IPsec tunnel with an endpoint specified as an FQDN address object will fail to be established if the FQDN cannot be resolved. In addition, any Mail Alerting object will not send alerts if its FQDN address object cannot be resolved.

DNS Responses Can Contain Multiple IPs

Depending on the FQDN, the DNS lookup can return both IPv4 and IPv6 addresses and there can be multiple IPs of each type in a single DNS reply. When a DNS query returns multiple addresses in a single reply, any of the addresses may be assigned by cOS Core to the FQDN Address object that initiated the query.

cOS Core can handle up to 1000 IPv4 addresses and/or 100 IPv6 addresses in a single DNS reply. Any IP addresses in excess of the 1000 limit for either type will be dropped. All addresses returned with a DNS reply will be stored in the FQDN cache so they can be looked up later.

Rule Processing Includes All FQDN IP Addresses

When cOS Core matches traffic against a rule that references an FQDN Address object, it checks against all the IP addresses associated with the FQDN. This means that if a DNS server returns more than one address in the same or multiple replies, the rule will trigger correctly for any of the IP addresses.

This is not relevant when FQDN Address objects are used as a single endpoint. For example, with IPsec Tunnel or Mail Alerting objects.

FQDN Address Caching

cOS Core uses an internal FQDN address cache to ensure that the same FQDN Address object does not need to be resolved every time it is referenced. The current cache contents can be examined using the following CLI command:
Device:/> dns -cache
An example of output from this command is shown below:
Device:/> dns -cache

Name                              Status     IP Cnt Address
---------------------------------- ---------- ------ --------------------
my_fqdn_address1                   Resolved       1  server1.example.com
my_fqdn_address2                   Unused         0
The status of a particular FQDN in the cache can be examined with the following command:
Device:/> dns -cache <FQDN>
Where <FQDN> is the logical configuration name of the address object in the address book. Below is an example of output from this command:
Device:/> dns -cache my_fqdn_address1
		
Address : my_fqdn_address1
Status  : Resolved

IP address                                          LifeTime 
--------------------------------------------------   --------
203.0.113.3                                         299

This information about the DNS cache can also be accessed in the Web Interface by going to Status > Run-time Information > DNS Cache.

The Minimum TTL Setting

When the DNS server returns IP addresses for an FQDN Address object, it also returns a Time To Live (TTL) value (also known as the lifetime). This value is stored with the entry for the FQDN Address object in the DNS cache. When the TTL expires, cOS Core will refresh the cache entry by issuing a new DNS query.

The TTL returned from the DNS server could be very low or even zero. For this reason, cOS Core provides a global DNS setting called Minimum TTL with a default value of 1 second. The greater of the TTL value returned from a DNS server and the value of Minimum TTL will determine when cOS Core queries the DNS server again.

The Minimum Cache Time Setting

There is also a second global DNS setting called Minimum Cache Time which has a default value of 86,400 seconds (one day). cOS Core will only remove an entry from the cache before the Minimum Cache Time period expires if the cache is full when a new entry needs to be added.

The Minimum Cache Time setting can be important when multiple DNS queries for the same FQDN might return different IP addresses. Some DNS servers may work in a round-robin fashion for a given FQDN, returning different IP addresses to consecutive queries to spread the server load. A higher minimum cache time can ensure all the possible IP addresses for a given FQDN will coexist in the cache.

Note that the TTL of a cache entry expires but the minimum cache time has not yet been reached, then a new DNS request for the FQDN will be issued by cOS Core and an additional cache entry will be created for any new IP address returned by the DNS server.

Using FQDN Wildcards

The asterisk "*" character can be used as a wildcard in the FQDN of an FQDN Address object to represent any combination of characters. The following rules apply to how wildcards can be used:

  • The wildcard can only be used as the first and/or last character in an FQDN.