The FB2700 is shipped in a factory reset state. This means it has a default configuration that allows the unit to be attached directly to a computer, or into an existing network, and is accessible via a web browser on a known IP address for further configuration.

Besides allowing initial web access to the unit, the factory reset configuration provides a starting point for you to develop a bespoke configuration that meets your requirements.

A printed copy of the QuickStart Guide is included with your FB2700 and covers the basic setup required to gain access to the web based user interface. If you have already followed the steps in the QuickStart guide, and are able to access the FB2700 via a web browser, you can begin to work with the factory reset configuration by referring to Chapter 3.

Initial set up is also covered in this manual, so if you have not already followed the QuickStart Guide, please start at Chapter 2.

The remainder of this chapter provides an overview of the FB2700's capabilities, and covers your product support options.

The FB2700 is an extremely versatile network appliance which you can think of as something akin to a Swiss army knife for networking.

It can :

and much more...

The FB2700 has four copper (RJ45) Ethernet network ports that can operate at 10Mb/s, 100Mb/s, or 1Gb/s. The ports implement auto-negotiation by default, but operation can be fine-tuned to suit specific circumstances. The function of these ports is very flexible, and defined by the device's configuration. The ports implement one or more interfaces, and each interface can span either a single port or a user-defined group of ports.

When a port group is defined, the ports in the group work as a conventional Layer 2 network switch, directly transferring traffic at wire-speed that is destined for a Layer 2 address that is present on one of the other ports in the group.

Conversely, multiple interfaces can be implemented on a single physical port (or port group) via support for IEEE 802.1Q VLANs, ideal for using the FB2700 with VLAN-capable network switches. In this case, a single physical connection can be made between a VLAN-capable switch and the FB2700, and with the switch configured appropriately, this physical connection will carry traffic to/from multiple VLANs, and the FB2700 can do Layer 3 processing (routing/firewalling etc.) between nodes on two or more VLANs.

The FB2700 has a simple two level software-feature-set. Devices are graded as "base" models or "fully-loaded" models. The base model lacks a few of the features such as BGP, L2TP and various bonding and tunnelling features.

You can use the base model for routing packets, filtering (firewalling) or arranging a 3G fallback for your DSL line.

The "fully-loaded" model is useful for bonding multiple lines, tunnelling and more obscure features such as announcing addresses to an upstream provider by BGP.

It is possible to upgrade from "base" to "fully-loaded" at a later date if you wish. Contact your dealer for details. The cost is usually just the difference in the price between the models.

Every major FB2700 software release is accompanied by a release-specific version of this manual. This manual documents software version V2.01.101 - please refer to Section 4.3 to find out more about software releases, and to see how to identify which software version your FB2700 is currently running.

If your FB2700 is running a different version of system software, then please consult the version of this manual that documents that specific version, as there may be significant differences between the software versions. Also bear in mind that if you are not reading the latest version of the manual (and using the latest software release), references in this manual to external resources, such as the FireBrick website, may be out of date.

You can find the latest revision of a manual for a specific software version on the FB2700 software downloads website. This includes the revision history for all software releases.

This manual is intended to guide FB2700 owners in configuring their units for their specific applications. We try to make no significant assumption about the reader's knowledge of FireBrick products, but as might be expected given the target market for the products, it is assumed the reader has a reasonable working knowledge of common IP and Ethernet networking concepts. So, whether you've used FireBrick products for years, or have purchased one for the very first time, and whether you're a novice or a network guru, this Manual sets out to be an easy to read, definitive guide to FireBrick product configuration for all FireBrick customers.

There are a number of useful technical details included in the appendices. These are intended to be a reference guide for key features.

At FireBrick, we appreciate that different people learn in different ways - some like to dive in, hands-on, working with examples and tweaking them until they work the way they want, referring to documentation as required. Other people prefer to build their knowledge up from first principles, and gain a thorough understanding of what they're working with. Most people we suspect fall somewhere between these two learning styles.

This Manual aims to be highly usable regardless of your learning style - material is presented in an order that starts with fundamental concepts, and builds to more complex operation of your FireBrick. At all stages we hope to provide a well-written description of how to configure each aspect of the FireBrick, and - where necessary - provide enough insight into the FireBrick's internal operation that you understand why the configuration achieves what it does.

Various typefaces and presentation styles are used in this document as follows :-

If you'd like to make any comments on this Manual, point out errors, make suggestions for improvement or provide any other feedback, we would be pleased to hear from you via e-mail at : docs@firebrick.co.uk.

Technical support is available, in the first instance, via the reseller from which you purchased your FireBrick. FireBrick provide extensive training and support to resellers and you will find them experts in FireBrick products.

However, before contacting them, please ensure you have :-

Many FireBrick resellers also offer general IT support, including installation, configuration, maintenance, and training. You may be able to get your reseller to develop FB2700 configurations for you - although this will typically be chargeable, you may well find this cost-effective, especially if you are new to FireBrick products.

If you are not satisfied with the support you are getting from your reseller, please contact us.

A public IRC channel is available for FireBrick discussion - the details are :-

Some applications notes have been created by the FireBrick team and included on the web site. There are also useful Wiki web sites provided by main dealers which cover specific configuration examples. Ask your dealer for more details. These are usually public Wiki web sites even if not buying from that specific dealer.

FireBrick provide training courses for the full FireBrick series of products, and also training course on general IP networking that are useful if you are new to networking with IP.

Training course attendance is mandatory for all FireBrick dealers to be accredited.

To obtain information about upcoming courses, please contact us via e-mail at : training@firebrick.co.uk.

The setup wizard allows you to fill in a few key items before entering the normal configuration editor.

The object model has a formal definition in the form of an XML Schema Document (XSD) file, which is itself an XML file, normally intended for machine-processing. A more readable version of this information is available in Appendix M.

Note, however, that this is reference material, containing only brief descriptions, and intended for users who are familiar with the product, and in particular, for users configuring their units primarily via XML.

The XSD file is also available on the software downloads website by following the "XSD" link that is present against each software release.

Most objects have a comment attribute which is free-form text that can be used for any purpose. Similarly, most objects have a source attribute that is intended for use by automated configuration management tools. Neither of these attributes have a direct effect on the operation of the FB2700.

Many objects have a name attribute which is mandatory and often needs to be unique within the list of objects. This allows the named object to be referenced from other attributes. The data type for these is typically an NMTOKEN which is a variant of a string type that does not allow spaces. If you include spaces then they are removed automatically. This helps avoid any problems referencing names in other places especially where the reference may be a space separated list.

Many objects have a graph attribute. This allows a graph name to be specified. However, the actual graph name will be normalised to avoid spaces and limit the number of characters. Try to keep graph names as basic characters (letters, numbers) to avoid confusion.

When you send the FireBrick a configuration the value is parsed and stored internally in a binary format. This means that when you access the config later it is possible the value you see is a normalised version of the value. For example storing a number as 000123 will return as 123.

In some cases you can enter a value in a format you will never see come back when you view the config. For example, simple integers can have SI magnitide suffixes, e.g. G (giga), M (mega), or k (kilo), so you can enter 1.5k but will see 1500. You can also use Gi (gibi), Mi (mebi), or Ki (kibi) for IEC units based on powers of two. You can also suffix B to mean bytes and the resulting value stored will be 8 times larger (as integers are used for bits/second speed settings). Other examples include using colour names like red which you see as #ff0000.

Where the type is in fact a list of a type, the actual value in the XML attribute is actually a space separated list. This is consistent with the XSD (XML Schema Definition). In the web based editor such lists are automatically split on to separate lines to make it easier to read and edit, but in the raw XML the list simple uses a single space between each item.

For example allow="192.168.0.0/16 10.0.0.0/8 172.16.0.0/12" lists three IP prefixes to allow.

Some types are simply a set of acceptable values, the simplest of which is Boolean allowing false and true.

The simple lists of values are detailed in Section M.2, with the acceptable values.

However, in some cases a data type is a reference to some other object, in which case the acceptable values are the name of those referenced objects. In most cases the web based config can ensure it provides a pull down menu of the acceptable values.

There is one special case for IP groups where the value can be an IP address, or range, or the name of an IP group. In this case the web config editor expects you to correctly type the name of an IP group.

There is one other special case of graph names where you can typically enter any name, including one of the defined shaper names or make up a new name as you wish with no error when you save the config. Graphs are created on the fly and so you have to be careful to correctly type graph names in the config to get the desired effect.

As per normal XML Schema rules, dates and times are in ISO8601 format, e.g. 2024-04-28 or 2024-04-28T16:37:48.

However, unlike XML Schema rules, durations are in the format for HH:MM:SS, or MM:SS, or just seconds, e.g. 1:00:00 for one hour. However, to allow XML Schema compliant input a duration can also be entered in the normal format such as PT1H for one hour, which appears as 1:00:00. Note that P1M and PT1M specify 1 month and one minute durations, respectively.

Colours can be entered in normal css style format such as #FF0000 or #F00, or use a small set of colour names such as red. A fourth byte for transparency can be provided if applicable.

There are two cases where the information entered in the config may be sensitive. One case is a password, for example one used for a user log in to the FireBrick. This this case you can provide a simple text password in the config you send, but what you get back will be a hash, e.g. SHA256#92E12F9A333C68690078AC041CD840996EB366A190F7D8966C48AB84A5729F66DCBC7C1A01​9FC277583684E81015EA. The exact format used may change over time, and if an older hash, such as MD5 exists in the config, it will actually change to a newer hash format automatically next time someone logs in using that password. The hashes include salt to make them harder to crack, but none the less it is best to keep config files secure and not reveal the hashes used.

Another special case is the use of a OTP (One Time Passcode) system. You can put a plain text password and a BASE32 OTP seed in the config for a user, and they will come back as a hashed password (as above), and a # followed by base64 coded data for the OTP code.

In addition, there are also secrets which are passwords which cannot be stored in a hashed format (because of the way they are used). Both passwords and secrets are only displayed if you have full access to the config. If you have limited access, or select to view the config with secrets hidden then they all appear as "secret". However such secrets are stored in the config file in plain text.

It is possible (though complex) for you to make hashes and OTP seeds off-line and simply store in the config. For more information on how passwords are hashed and OTP seeds are stored, see Appendix L.

Being an IP based firewall / router the FireBrick config has a lot of places where an IP address can be entered. In some cases a simple single IP address, but in other cases as an IP and subnet size (CIDR notation) or even a range of IP addresses. Often a list of IP addresses and/or ranges can be specified in a space separated list.

The User Interface has the following general layout :-

Note that the main-menu items themselves have a specific function when clicked - clicking such items displays a general page related to that item - for example, clicking on Status shows some overall status information, whereas sub-menu items under Status display specific categories of status information.

The user interface pages used to change the device configuration are referred to as the 'config pages' in this manual - these pages are accessed by clicking on the "Edit" item in the sub-menu under the "Config" main-menu item.

The structure of the config pages mirrors the object hierarchy, and therefore they are themselves naturally hierachical. Your position in the hierarchy is illustrated in the 'breadcrumbs' trail at the top of the page, for example :-

Firewall/mapping rules :: rule-set 1 of 3 (filters) :: rule 7 of 19 (ICMP)

This shows that the current page is showing a rule, which exists within a rule-set, which in turn is in the "Firewall/mapping rules" category (see below).

3.7.2.1. Configuration categories

Configuration objects are grouped into a number of categories. At the top of the config pages is a set of icons, one for each category, as shown in Figure 3.1 :-

Figure 3.1. Icons for configuration categories

Within each category, there are one or more sections delimited by horizontal lines. Each of these sections has a heading, and corresponds to a particular type of top-level object, and relates to a major part of the configuration that comes under the selected category. See Figure 3.2 for an example showing part of the "Setup" category, which includes general system settings (the system object) and control of system services (network services provided by the FB2700, such as the web-interface web server, telnet server etc., controlled by the services object).

Figure 3.2. The "Setup" category

Each section is displayed as a tabulated list showing any existing objects of the associated type. Each row of the table corresponds with one object, and a subset (typically those of most interest at a glance) of the object's attributes are shown in the columns - the column heading shows the attribute name. If no objects of that type exist, there will be a single row with an "Add" link. Where the order of the objects matter, there will be an 'Add' link against each object - clicking an 'Add' link for a particular object will insert a new object before it. To add a new object after the last existing one, click on the 'Add' link on the bottom (or only) row of the table.

Tip

If there is no 'Add' link present, then this means there can only exist a limited number of objects of that type (possibly only one), and this many already exist. The existing object(s) may have originated from the factory reset configuration.

You can 'push-down' into the hierarchy by clicking the 'Edit' link in a table row. This takes you to a page to edit that specific object. The page also shows any child objects of the object being edited, using the same horizontal-line delimited section style used in the top-level categories. You can navigate back up the hierarchy using various methods - see Section 3.7.3.

Caution

Clicking the "Add" link will create a new sub-object which will have blank/default settings. This can be useful to see what attributes an object can take, but if you do not want this blank object to be part of the configuration you later save you will need to click Erase. Simply going back "Up" or moving to another part of the config will leave this newly created empty object and that could have undesirable effects on the operation of your FireBrick if saved.

3.7.2.2. Object settings

The details of an object are displayed as a matrix of boxes (giving the appearance of a wall of bricks), one for each attribute associated with that object type. Figure 3.3 shows an example for an interface object (covered in Chapter 6) :-

Figure 3.3. Editing an "Interface" object

By default, more advanced or less frequently used attributes are hidden - if this applies to the object being edited, you will see the text shown in Figure 3.4. The hidden attributes can be displayed by clicking on the link "Show all".

Figure 3.4. Show hidden attributes

Each brick in the wall contains the following :-

• a checkbox - if the checkbox is checked, an appropriate value entry widget is displayed, otherwise, a default value is shown and applied for that setting. If the attribute is not optional then no checkbox is shown.
• the attribute name - this is a compact string that exactly matches the underlying XML attribute name
• a short description of the attribute

Tip

If there is no default shown for an attribute then its value, if needed, is zero, blank, null, empty string, false (internally it is zero bits!). In some cases the presence of an attribute will have meaning even if that attribute is an empty string or zero value. In some cases the default for an attribute will not be a fixed value but will depend on other factors, e.g. it may be "auto", or "set if using xyz...". The description of the default value should make this clear. Where an optional attribute is not ticked the attribute does not appear in the XML at all.

These can be seen in Figure 3.5 :-

Figure 3.5. Attribute definitions

If the attribute value is shown in a 'strike-through' font (with a horizontal line through it mid-way vertically), this illustrates that the attribute can't be set - this will happen where the attribute value would reference an instance of particular type of object, but there are not currently any instances of objects of that type defined.

Tip

Since the attribute name is a compact, concise and un-ambiguous way of referring to an attribute, please quote attribute names when requesting technical support, and expect technical support staff to discuss your configuration primarily in terms of attribute (and object/element) names, rather than descriptive text, or physical location on your screen (both of which can vary between software releases).

You navigate around the hierarchy using one or more of the following :-

Figure 3.6. Navigation controls

Navigating away from an object using the supported navigation controls doesn't cause any modifications to that object to be lost, even if the configuration has not yet been saved back to the FB2700. All changes are initially held in-memory (in the web browser itself), and are committed back to the FireBrick only when you press the Save button.

The navigation button area, shown in Figure 3.6, also includes three other buttons :-

To back up / save or restore the configuration, start by clicking on the "Config" main-menu item. This will show a page with a form to upload a configuration file (in XML) to the FB2700 - also on the page is a link "Download/save config" that will download the current configuration in XML format.

It is also possible to set auto-backup-url to a URL (starting https://) to automatically post a copy of the config to a server of your choice shortly after any changes. There is a delay of a few minutes after the last change before posting the config. The config post also includes a header X-Signed with a digital signature of the config itself using the private key stored in the FireBrick Certificates store against the FireBrick serial number. This should be used to check for authenticity of the posted config.

It is possible to change the colour of the interface's header and footer banners from the config editor. Select the "Setup" category icon and choose to edit "General system services" and then "Web server settings" and "banner-background". By default, this will also change the colour of the config editor and the highlight text colour (used for hyperlinks and headings). If needed, you can set those colours separately - click "Show all" at the bottom of the page to see the options.

Alternatively you can edit the XML configuration file (see Section 3.8) and set the banner-background attribute for the http service.

It is also possible to configure an external CSS to use with the FireBrick web control pages, via the css-url attribute. This allows a great deal of control of the overall layout and appearance. This can be useful for dealers or IT support companies to set up FireBricks in a style and branding of their choice.

An XML file is a text file (i.e. contains human-readable characters only) with formally defined structure and content. An XML file starts with the line :-

<?xml version="1.0" encoding="UTF-8"?>

This defines the version of XML that the file complies with and the character encoding in use. The UTF-8 character coding is used everywhere by the FireBrick.

The XML file contains one or more elements, which may be nested into a hiearchy.

Each element consists of some optional content, bounded by two tags - a start tag AND an end tag.

A start tag consists of the following sequence of characters:-

An end tag consists of the following sequence of characters:-

If an element needs no content, it can be represented with a more compact self closing tag. A self closing tag is the same as a start tag but ends with /> and then has no content or end tag.

Since the <, > and " characters have special meaning, there are special ('escape') character sequences starting with the ampersand character that are used to represent these characters. They are :-

Note that since the ampersand character has special meaning, it too has an escape character sequence.

Attributes are written in the form : name="value" or name='value'. Multiple attributes are separated by white-space (spaces and line breaks).

Generally, the content of an element can be other child elements or text. However, the FB2700 doesn't use text content in elements - all configuration data is specified via attributes. Therefore you will see that elements only contain one or more child elements, or no content at all. Whilst there is generally not any text between the tags, white space is normally used to make the layout clear.

At the top level, an XML file normally only has one element (the root element), which contains the entire element hierarchy. In the FB2700 the root element is <config>, and it contains 'top-level' configuration elements that cover major areas of the configuration, such as overall system settings, interface definitions, firewall rule sets etc.

In addition to this User Manual, there is reference material is available that documents the XML elements - refer to Section 3.2.1.

The XML representation of the configuration can be viewed and edited (in text form) via the web interface by clicking on "XML View" and "XML Edit" respectively under the main-menu "Config" item. Viewing the configuration is, as you might expect, 'read-only', and so is 'safe' in as much as you can't accidentally change the configuration.

An example of a simple, but complete XML configuration is shown below, with annotations pointing out the main elements

<?xml version="1.0" encoding="UTF-8"?>
<config xmlns="http://firebrick.ltd.uk/xml/fb9000/"	
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://firebrick.ltd.uk/xml/fb9000/  ...
        timestamp="2024-03-14T12:24:07Z"
        patch="8882">

 <system name="gateway"             
         contact="Peter Smith"
         location="The Basement"
         log-support="fb-support">
 </system>

 <user name="peter"                 
       full-name="Peter Smith"
       password="FB105#4D42454D26F8BF5480F07DFA1E41AE47410154F6"
       timeout="PT3H20M"
       config="full"
       level="DEBUG"/>

 <log name="default"/>           
 <log name="fb-support">
  <email to="crashlog@firebrick.ltd.uk"
         comment="Crash logs emailed to FireBrick Support"/>
 </log>

 <services>                      
  <time/>
  <telnet log="default"/>
  <http/>
  <dns domain="watchfront.co.uk"
       resolvers="81.187.42.42 81.187.96.96"/>
 </services>

 <port name="WAN"                   
       ports="1"/>
 <port name="LAN"
       ports="2"/>

 <interface name="WAN"              
            port="WAN">
  <subnet name="ADSL"
          ip="81.187.106.73/30"/>
 </interface>

 <interface name="LAN"               
            port="LAN">
  <subnet name="LAN"
          ip="81.187.96.94/28"/>
  <dhcp name="LAN"
        ip="81.187.96.88-92"
        log="default"/>
 </interface>

  <rule-set name="filters"            
           no-match-action="drop">
  <rule name="Our-Traffic"
        source-interface="self"
        comment="FB originated traffic allowed"/>
  <rule name="FireBrick UI"
        target-port="80"
        target-interface="self"
        protocol="6"/>
  <rule name="ICMP"
        protocol="1"
        log="default"/>
  <rule name="All outgoing"
        source-interface="LAN"/>
  <rule name="FB-access"
        source-interface="LAN"
        target-port="80"
        target-interface="self"
        protocol="6"
        comment="FB web config access"/>
  <rule name="final-no-match"
        log="default"
        action="drop"
        comment="Catch all - sets default logging for no match"/>
 </rule-set>
 </config>

To download the configuration from the FB2700 you need to perform an HTTP GET of the following URL :-

http://<FB2700 IP address or DNS name>/config/config

An example of doing this using curl, run on a Linux box is shown below :-

curl http://<FB2700 IP address or DNS name>/config/config
   --user "username:password" --output "filename"

Replace username and password with appropriate credentials.

The XML configuration file will be stored in the file specified by filename - you can choose any file extension you wish (or none at all), but we suggest that you use .xml for consistency with the file extension used when saving a configuration via the User Interface (see Section 3.7.4).

To upload the configuration to the FB2700 you need to send the configuration XML file as if posted by a web form, using encoding MIME type multipart/form-data.

An example of doing this using curl, run on a Linux box is shown below :-

curl http://<FB2700 IP address or DNS name>/config/config
   --user "username:password" --form config="@filename"

A user's login level is set with the level attribute, and determines what CLI commands the user can run. The default, if the level attribute is not specified, is ADMIN - you may wish to downgrade the level for users who are not classed as 'system administrators'.

The configuration access level determines whether a user has read-only or read-write access to the configuration, as shown in Table 4.2 below. This mechanism can also be used to deny all access to the configuration using the none level, but still allowing access to other menus and diagnostics.

Config access also requires at least admin level for their login level to access config via the web interface.

It is possible to test a new config, causing it to be applied but not saved to permament storage. This test config automatically reverts after a few minutes if not committed, or if the brick restarts, e.g. power cycle. It is recommended that you test a config first to ensure you have not locked yourself out, and there is a user level to force you to have to test configs first.

To improve security, login sessions to either the web user interface, or to the command-line interface (via telnet, see Chapter 21), will time-out after a period of inactivity. This idle time-out defaults to 5 minutes, and can be changed by setting the timeout attribute value.

The time-out value is specified using the syntax for the XML fb:duration data type. The syntax is hours, minutes and seconds, or minutes and seconds or just seconds. E.g. 5:00.

To set a user's time-out in the user interface, tick the checkbox next to timeout, and enter a value in the format described above.

Setting a timeout to 0 means unlimited and should obviously be used with care.

Normally, all config data is updated via the config edit process, and this allows a new password to be set for any user.

However, there is also a menu to allow a logged in user to change their own password. This does not require the user to have any config access permission. Simply enter the old password, and the new password twice and the password is updated.

If you have set up an OTP configuration for a user, then you cannot change the password simply using the configuration editor (unless also setting a new OTP configuration from scratch or removing it). In such cases the password should be set using the password change web page. This is also good practice as it avoids the administrator knowing people's passwords.

A login to the FireBrick normally requires only a username and password. However you can configure an additional security measure using a One Time Password (OTP) device. These are available as key fobs that show a code, but are more commonly done by use of a mobile phone application.

In order for the device to work you need a key which is known to the FireBrick and the device. However, this is very simple to set up. A user can access the Password / OTP menu where a random key is allocated and displayed within a QR 2D bar code. Most authenticator applications simply scan the QR code and start showing the 6 digit number on the display (which changes every 30 seconds). You then enter your password and a code from your device to complete the process.

It is possible for anyone with configuration access to edit your user settings and remove the OTP settings if you wish. This can be useful if you lose or break the phone, for example. You may want to keep a local configuration user as a backup as well, as OTP cannot be used if the clock is not set for any reason.

When you login, after you submit your username and password you are asked for a code from the authenticator to complete the login process.

It is also possible to enter the password as the authenticator code followed by the configured password. This is useful if using HTTP authentication to access a web page where there is no separate option for the authenticator input to be provided.

If OTP is configured you can leave the password blank (which is not normally allowed) and hence use the authenticator code as the entire password, though this is not recommended for security reasons as it also means the TOTP seed is recoverable from the config.

The system name, also called the hostname, is used in various aspects of the FB2700's functions, and so we recommend you set the hostname to something appropriate for your network.

The hostname is set using the name attribute.

The attributes shown in Table 4.3 allow you to specify general administrative details about the unit :-

The log and log-... attributes control logging of events related to the operation of the system itself. For details on event logging, please refer to Chapter 5, and for details on the logging control attributes on system object, please refer to Section 5.7.

The home page is the first page you see after logging in to the FB2700, or when you click the Home main-menu item. The home page displays the system name, and, if defined, the text specified by the intro attribute on the system object.

Additionally, you can define one or more web links to appear on the home page. These are defined using link objects, which are child objects of the system object.

To make a usable link, you must specify the following two attributes on the link object :-

Additionally, you can name a link, specify a comment, and make the presence of the link on the home page conditional on a profile.

There are three types of software release : factory, beta and alpha. For full details on the differences between these software releases, refer to the FB2700 software downloads website - please follow the 'read the instructions' link that you will find just above the list of software versions.

The current software version is displayed on the main Status page, shown when you click the Status main menu-item itself (i.e. not a submenu item). The main software application version is shown next to the word "Software", e.g. :-

Software     FB9001 TEST Balcombe (V2.01.101 2024-10-29T11:17:05)

The software version is also displayed in the right hand side of the 'footer' area of each web page, and is shown immediately after you log in to a command-line session.

If automatic installs are allowed, the FB2700 will check for new software on boot up and approximately every 24 hours thereafter - your FB2700 should therefore pick up new software at most ~ 24 hours after it is released (assuming no delay is configured). You can choose to allow this process to install only new factory-releases, factory or beta releases, or any release, which then includes alpha releases (if your FB2700 is enabled for alpha software - see Section 4.3.1) - refer to Section 4.3.3.2 for details on how to configure auto upgrades.

This method is entirely manual, in the sense that the brick itself does not download new software from the FireBrick servers, and responsibilty for loading breakpoint releases as required lies with the user.

In order to do this, you will first need to download the required software image file (which has the file extension .img) from the FB2700 software downloads website onto your PC.

Then go to the Status Software page, the form to upload the image file is at the bottom.

A log target is a named destination (initially internal to the FB2700) for log entries - you can set up multiple log targets which you can use to separate out log event messages according to some criteria - for example, you could log all firewalling related log events to a log target specifically for that purpose. This makes it easier to locate events you are looking for, and helps you keep each log target uncluttered with un-related log events - this is particularly important when when you are logging a lot of things very quickly.

A log target is defined using a log top-level object - when using the web User Interface, these objects are in the "Setup" category, under the heading "Log target controls".

Every log entry is put in a buffer in RAM, which only holds a certain number of log entries (typically around 1MB of text) - once the buffer is full, the oldest entries are lost as new ones arrive. Since the buffer is stored in volatile memory (RAM), buffer contents are lost on reboot or power failure.

This buffer can be viewed via the web interface or command line which can show the history in the buffer and then follow the log in real time (even when viewing via a web browser, with some exceptions - see Section 5.6.1).

In some cases it is essential to ensure logged events can be viewed even after a power failure. You can flag a log target to log to the non-volatile Flash memory within the FB2700, where it will remain stored even after a power failure. You should read Section 5.5 before deciding to log events to Flash memory.

Each log target has various attributes and child objects defining what happens to log entries to this target. However, in the simplest case, where you do not require non-volatile storage, or external logging (see Section 5.3), the log object will only need a name attribute, and will have no child objects. In XML this will look something like :-

<log name="my_log"/>

The FB2700 supports sending of log entries across a network to a syslog server. Syslog is described in RFC5424, and the FB2700 includes microsecond resolution time stamps, the hostname (from system settings) and a module name in entries sent via syslog. Syslog logging is very quick as there is no reply, and syslog servers can be easily set up on most operating systems, particularly Unix-like systems such as Linux.

The module name refers to which part of the system caused the log entry, and is also shown in all other types of logging such as web and console.

To enable log messages to be sent to a syslog server, you need to create a syslog object that is a child of the log target (log) object. You must then specify the DNS name or IP address of your syslog server by setting the server attribute on the syslog object. You can also set the facility and/or severity values using these attributes :-

The FB2700 normally uses the 'standard' syslog port number of 514, but if necessary, you can change this by setting the port attribute value.

You can cause logs to be sent by e-mail by creating an email object that is a child of the log target (log) object.

An important aspect of emailed logs is that they have a delay and a hold-off. The delay means that the email is not sent immediately because often a cluster of events happen over a short period and it is sensible to wait for several log lines for an event before e-mailing.

The hold-off period is the time that the FB2700 waits after sending an e-mail, before sending another. Having a hold-off period means you don't get an excessive number of e-mails ; since the logging system is initially storing event messages in RAM, the e-mail that is sent after the hold-off period will contain any messages that were generated during the hold-off period.

The following aspects of the e-mail process can be configured :-

An example of a simple log target with e-mailing is available in a factory reset configuration - the associated XML is shown below, from which you can see that in many cases, you only need to specify the to attribute (the comment attribute is an optional, general comment field) :-

 <log name="fb-support"
      comment="Log target for sending logs to FireBrick support team">
  <email to="crashlog@firebrick.ltd.uk"
         comment="Crash logs emailed to FireBrick Support team"/>
 </log>

A profile can be used to stop emails at certain times, and when the email logging is back on an active profile it tries to catch up any entries still in the RAM buffer if possible.

To view a log in the web User Interface, select the "Log" item in the "Status" menu. Then select which log target to view by clicking the appropriate link. You can also view a 'pseudo' log target "All" which shows log event messages sent to any log target.

The web page then continues showing log events on the web page in real time i.e. as they happen.

All log targets can be viewed via the web User Interface, regardless of whether they specify any external logging (or logging to Flash memory).

The command line allows logs to be viewed, and you can select which log target, or all targets. The logging continues on screen until you press a key such as RETURN.

In addition, anything set to log to console shows anyway (see Section 5.1.1.2), unless disabled with the troff command.

Up to four port groups can be defined, with each group comprising a set of one or more physical ports that doesn't overlap with any other group. The ports within the group normally work as a conventional Ethernet switch, directly transferring traffic at wire-speed that is destined for a MAC address that is present on one of the other ports in the group, but can alternatively be configured as a trunked group.

The port group has a trunk setting which defaults to being false. When only one port is in the group it makes no difference how this is set. With more than one port, when trunk is false, the ports work as a switch, passing traffic directly at gigabit speeds between the physical ports. With more than one port, when trunk is true, the ports work as a link aggregation trunk and not as a switch. There is no option for some ports in a group to be trunked and also switched to other ports.

The FireBrick supports LACP (Link Aggregation Control Portocol) which is used to coordinate and control trunked port groups by exchanging LACP packets over the links. There is a lacp setting in the individual ethernet port settings which can be used to control LACP's behaviour, as follows:

The FB2700 has an internal 1G switch with a single link to communicate with the CPU. The maximum bandwidth for incoming traffic is limited by that link, and so dedicating multiple physical ports in a bonded way to LACP could result in the switch receiving twice as much traffic as it can send onwards. This would result in the internal switch dropping packets during traffic spikes. To avoid this, we configure any additional ports as a hot standby. This provides rapid failover whilst allowing the other device a chance to shape/queue packets appropriately.

In the FB2700, an interface is a logical equivalent of a physical Ethernet interface adapter. Each interface normally exists in a distinct broadcast domain, and is associated with at most one port group.

Each port group, which could be a single port, can operate simply as an interface with no VLANs, or can have one or more tagged VLANs which are treated as separate logical interfaces. Using VLAN tags and a VLAN capable switch you can effectively increase the number of physical ports.

Appendix E contains a brief overview of VLANs and the concept of broadcast domains.

Each interface can have one or more subnets definitions associated with it. The ability to specify multiple subnets on an interface can be used where it is necessary to communicate with devices on two different subnets and it is acceptable that the subnets exist in the same broadcast domain. For example, it may not be possible to reassign machine addresses to form a single subnet, but the machines do not require firewalling from each other.

You may also have both IPv4 and IPv6 subnets on an interface where you are also using IPv6 networking.

The primary attributes that define a subnet are the IP address range of the subnet, the IP address of the FB2700 itself on that subnet, and an optional name.

The IP address and address-range are expressed together using CIDR notation - if you are not familiar with this notation, please refer to Appendix B for an overview.

To create or edit subnets, select the Interface category in the top-level icons, then click Edit next to the appropriate interface - under the section headed "IP subnet on the interface", you will see the list of existing subnet child objects (if any), and an "Add" link.

To create a new subnet, click on the Add link to take you to a new subnet object defintion. Tick the ip checkbox, and enter the appropriate CIDR notation.

Editing an existing subnet works similarly - click the Edit link next to the subnet you want to modify.

The FB2700 can perform conventional Network Address Translation (NAT) for network connections / flows originating from all machines on a subnet (for example, one using RFC1918 private IP address space) by setting the nat attribute on the subnet object.

The FB2700 can act as a DHCP server to dynamically allocate IP addresses to clients. Optionally, the allocation can be accompanied by information such as a list of DNS resolvers that the client should use.

Since the DHCP behaviour needs to be defined for each interface (specifically, each broadcast domain), the behaviour is controlled by one or more dhcp objects, which are children of an interface object.

Address allocations are made from a pool of addresses - the pool is either explicitly defined using the ip attribute, or if ip is not specified, it consists of all addresses on the interface, i.e. from all subnets but excluding network or broadcast addresses, or any addresses that the FB2700 has seen ARP responses for (eg addresses already in use, perhaps through a device configured with a fixed static address).

The XML below shows an example of an explicitly-specified DHCP pool :

  <interface ...>
  ...
    <dhcp name="LAN"
          ip="172.30.16.50-80"
          log="default"/>
  ...
  </interface>

Every allocation made by the DHCP server built-in to the FB2700 is stored in non-volatile memory, and will survive power-cycling and/or rebooting. The allocations can be seen using the "DHCP" item in the "Status" menu, or using the show dhcp CLI command.

If a client does not request renewal of the lease before it expires, the allocation entry will show "expired". Expired entries remain stored, and are used to lease the same IP address again if the same client (as identified by its MAC address) requests an IP address. However, if a new MAC address requests an allocation, and there are no available IPs (excluding expired allocations) in the allocation pool, then the oldest expired allocation IP address is reused for the new client.

  <interface ...>
  ...
    <dhcp name="laptop"
          ip="81.187.96.81"
          mac="0090F59E4F12"
          dns="81.187.42.42 81.187.96.96"
          log="default"/>
  ...
  </interface>

  <interface ...>
  ...
    <dhcp name="VoIP"
        ip="10.20.30.40-50"
        mac="000413 000E08"
	class="*phone*"
        dns="8.8.8.8"
        log="DHCP-Phones"
        comment="VoIP phones"/>
  ...
  </interface>

You can configure the FireBrick to operate as a DHCP/BOOTP Relay agent simply by setting the dhcp-relay in the interface object to the IPv4 address of the remote DHCP server.

If you also configure a DHCP allocation on the same interface, this is checked first, and if there are no suitable allocation pools or IP addresses available then the request is relayed. Normally you would configure either a relay or a pool and not both.

The top level dhcp-relay configuration allows you to configure the FireBrick to be the remote server for a DHCP/BOOTP Relay Agent. The relay attribute allows specific pools to be set up for specific relays. The table and allow allow you to limit the use of the DHCP Remote server to requests from specific sources - note that renewal requests come from the allocated IP, or NAT IP if behind NAT and not necessarily from the relay IP.

The allocation-table attribute allows for this pool of IPs to be placed in a separate table, thus allowing it to be independant from other DHCP allocations on the FireBrick and to allow different overlapping pools for different relay endpoints, which is not uncommon if the endpoints are behind separate NAT routers.

If you are connecting a port to a link-partner that does not support auto-negotiation (or has it disabled), it is advisable to disable auto-negotiation on the FB2700 port. To do this, tick the checkbox for the autoneg attribute and select false from the drop-down box. You will then need to set port speed and duplex mode manually (see below) to match the link-partner settings.

If auto-negotiation is enabled, the FB2700 port will normally advertise that it is capable of link-speeds of 10Mb/s, 100Mb/s or 1Gb/s - if you have reason to restrict the possible link-speed to one of these values you can set the speed attribute to 10M, 100M or 1G. This will cause the port to only advertise the specified speed - if the (auto-negotiate capable) link-partner does not support that speed, the link will fail to establish.

If auto-negotiation is disabled, the speed attribute simply sets the port's speed.

If auto-negotiation is enabled, the FB2700 port will normally advertise that it is capable of either half- or full- duplex operation modes - if you have reason to restrict the operation to either of these modes, you can set the duplex attribute to either half or full. This will cause the port to only advertise the specified mode - if the (auto-negotiate capable) link-partner does not support that mode, the link will fail to establish.

If auto-negotiation is disabled, the duplex attribute simply sets the port's duplex mode.

For each port, the green and yellow port LEDs can be set to indicate any of the conditions shown in Table 6.1, by setting the green and/or yellow attributes.

For example, to configure the port LEDs to show the port link speed via the pattern of the green and yellow LEDs, you could set the green attribute to Link10-1000/Activity, and the yellow attribute to Link100-1000 so that the indication is :-

For connection-orientated protocols such as TCP, the session-tracking is able to detect connection closure and delete the session from the session-table.

For protocols such as UDP, which will likely be carrying a higher-level protocol that may well itself implement some form of connection-orientated data transfers, further inspection and analysis of communications is not done by the FB2700. To do so would require support for a very wide range of protocols that are carried over UDP, and this is generally not practical.

Instead, all sessions (including TCP ones) have an associated time-out value - if no packets matching the session arrive for a period equal to the time-out value, the session is deleted automatically. This is adequate for most cases, but may require selection of a suitable time-out value based on knowledge of how frequently the higher-level protocol sends packets. An unnecessarily high time-out may cause the session-table to become populated with a significant number of sessions that correspond to flows or connections that have actually ceased.

However, the FB2700 has highly efficient handling of session tracking, both in terms of memory usage and processor load, so in practice it can easily handle very large session tables (hundreds of thousands of entries).

Note that TCP sessions also have time-outs; this is necessary since the connection may not be cleanly closed, for example one end may crash - if there were no time-out, the session-table would hold a stale entry until the FB2700 was rebooted.

The default timeouts for various session types are shown in Table 7.1.

As each packet arrives, the FB2700 determines whether the packet is part of an existing active session by doing a look-up in the session table. If a matching session is found, the session-table entry details determine how the packet is handled. If no matching session is found, the list of session-rules is then analysed to determine whether a new session should be established, or whether the traffic should be dropped or rejected.

Each session rule contains a list of criteria that traffic must match against, and contains an action specification that is used in the logic to decide whether the session will be allowed or not. The session rule can also :-

Session-rules are grouped into rule-sets, and together they are involved in a well-defined processing flow sequence - described in the next section - that determines the final outcome for a candidate session.

The following processing flow applies to rules and rule-sets :-

The short-lived session that is created when either drop and reject are actioned will appear in the session table when it is viewed in the web user interface (or via the CLI) - see Figure 7.1 for an example of ICMP sessions resulting from some pings ; the session lifetime is around one second.

Figure 7.1. Example sessions created by drop and reject actions

Note that drop and reject both drop packets, with the difference only being whether notification of this is sent back to the traffic source.

This processing flow is illustrated as a flow-chart in Figure 7.2 :-

Figure 7.2. Processing flow chart for rule-sets and session-rules

It is helpful to understand that a session rule contributes to the final set of information recorded in the session-table entry - a rule does not necessarily completely define what the session-table will contain, unless it is the only rule that matches the traffic under consideration. It is for this reason, that the rules contain attributes with names such as 'set-nat' - the 'set' refers to the action of setting a flag or a parameter in the session-table entry that is being 'constructed'.

It is possible, and quite common, for more than one rule (in different rule-sets) to match given traffic. In such cases, the rules generally serve different purposes - earlier ones might be for firewalling, whilst later ones might be used to subsequently assign some of the allowed-traffic to traffic-shaping. In such cases, an earlier rule will use the continue action to jump out of the earlier rule-set.

A rule-set is defined by a rule-set top-level object. To create or edit rule-sets in the web user interface, select the "Firewall" category icon - here you will see the list of existing rule-set objects (if any), and an "Add" link next to each.

To create a new rule-set, click on an "Add" link to insert a new rule-set before the one associated with the link. This will take you to a new rule-set defintion. Editing an existing rule-set works similarly - click the "Edit" link next to the rule-set you want to modify.

As described in Section 7.3.2, a rule-set can optionally specify entry-criteria - in the web user interface, these come under the heading "Matching criteria for whole set", when editing a rule-set definition. The entry-criteria are detemined by the following attributes, all of which are optional, but if they are specified, then the criteria must be met for processing of the rules within the rule-set to occur. These are also criteria that can be specified on individual rules within a rule-set :-

There are also checks for just ip being either source or target IP, interface being either source or target interface.

A rule-set can also be named by setting the name attribute value, and enabled/disabled under control of a profile. The comment attribute is a general purpose comment field that you can use to briefly describe the purpose of the rule-set.

Under the heading "Individual rules, first match applies", you will see the list of session-rules within the rule-set. A session-rule is defined by a rule object, which is a child object of a rule-set object.

Below the list of session-rules, you will see the no-match-action attribute, which is mandatory and has one of the values shown in Table 7.2. Recall that this attribute specifies the action to take if all of the rules in a rule-set have been considered, and none of them matched against the traffic.

 <rule-set name="firewall_to_LAN"
           target-interface="LAN"       
           no-match-action="drop">   
  <rule name="web"   
        target-port="80"
        protocol="6"
        comment="WAN access to company web server"/>   
 
 </rule-set>

NAT breaks the way Internet Protocol was designed as it stops end to end addressing and routing of packets. This causes problems with all sorts of protocols that sensibly expect IP to work as designed, and even some that assume NAT is in use. NAT is not itself a consistent and predictable process, and so it makes it very difficult to accommodate during protocol design.

Because of the many issues with NAT it is strongly recommended that NAT is only ever used where it is unavoidable. This is specifically where the availability of public IP addresses is limited.

Unfortunately with legacy IP version 4 addresses the supply of address space is now limited and most ISPs are only providing a single IPv4 address with an Internet Connection (or charging where more are provided). This means that it is common to require NAT for IPv4 on a typical Internet connection.

Because of the many problems with NAT and the ways in which many protocols are broken by its use, many NAT devices (such as broadband routers) will provide an Application Layer Gateway (ALG) as part of the NAT implementation. This provides special case handling for each higher level protocol or system making use of NAT that the device knows of, and provides work-arounds for the issues caused by NAT. In some cases this may simply be customised session timeout, but in some cases the support can be extensive and make major changes to the payload of packets passed through the device.

ALGs have a number of problems. Obviously they only work at all where the device knows of the protocol in question, and this is a major drawback for new protocol development. However, they are often imperfect in the way they work. It is not uncommon for ALGs designed to support VoIP using SIP to be significantly flawed such that you are better off turning off the ALG and leaving end devices to work around the NAT themselves.

The real solution to all of the issues with NAT is not ALGs, as they are simply not a scalable work-around for problems. The solution is the use of IPv6, the current Internet Protocol version. The FireBrick is designed from the ground up to support IPv6 and we recommend the use of IPv6 wherever possible.

The rules for firewalling allow a set-nat setting to be set true or false. Rules in later rule-sets can override this setting just like any other setting in the firewall rules.

What the NAT setting does is cause the FireBrick to change the source IP and port used for the session. It picks an IP based on the interface to which the traffic will finally be sent, and uses the most appropriate IP address that it can to try and ensure correct return traffic to that IP address.

The port that is chosen is picked from a pool of available source port addresses that are not currently in use. This ensures that the reply traffic can be correctly matched with the specific session even if multiple sessions are using the same original ports.

When using a PPPoE connection you may have a single IPv4 address assigned to the connection and so will need to NAT traffic sent down that connection to the Internet. To accommodate this there is a nat setting which can be enabled on the PPPoE configuration.

If this NAT setting is enabled then the default for all IPv4 traffic directed to the PPPoE session is for NAT to be used. This default applies if the firewalling rules have not otherwise explicitly set the NAT setting for the traffic in question. i.e. this can be overridden by specific firewalling rules.

Just as with PPPoE, there is a NAT setting which will cause traffic sent via the dongle to have NAT set by default, unless overridden by firewall rules. However, in the case of a dongle it is so rare to have a block of IPv4 addresses the NAT setting is enabled by default in the dongle configuration.

Where NAT is needed for other types of external routing, you can set NAT using explict rule-sets and rules. A simple rule-set at the end of all rule-sets can easily be set up to identify traffic being sent to a specific target interface and set the NAT setting.

In some cases you may have a combination of real routed IPv4 addresses and some RFC1918 private addresses. These could be on different interfaces and subnets.

Typically in such cases you want to use NAT for external communications only when using the private addresses, but non-NAT when using the public addresses. The logic can be complicated where there may be fallback arrangements, such as a dongle, which may have to use NAT for all traffic even the normally public routed addresses if the dongle does not have routing for these addresses.

The recommended way to handle this is a rule-set at the end of rule-sets for handling NAT, in which a specific rule is created to match traffic being sent to the external interface (e.g. PPPoE) which is from an RFC1918 address and setting NAT mode in such cases. Using this arrangement ensures that traffic internally between RFC1918 and public IP addresses can continue without using NAT internally.

Carrier grade NAT (CGN) is where an ISP provides end users with a private address and provides a further level of NAT in the network (within the carrier).

Ideally you should try and make use Internet connections without CGN, but if you have to then you are likely to encounter additional issues with NAT. CGNs do often include some ALGs, but they bring all of the issues with NAT to a new level. As ever we recommend using PPPoE to avoid an extra layer of NAT in a broadband router.

In some cases the FireBrick may be expected to provide a carrier level of NAT in terms of number of sessions handled. Whilst the FireBrick does not have any ALGs, it can be very effective, and it supports overloading of ports. This means that the allocation of ports for NAT allows multiple sessions that are to different target IP addresses and ports to come from the same port on the FireBrick, allowing use of the same port multiple times. This allows a lot more sessions that would otherwise be expected based on number of TCP and UDP ports available. This overloading of ports is automatic and part of the way the FireBrick handles NAT.

For backwards compatibility with older FireBricks there is a NAT setting on the subnet config. The idea is that a subnet defined as an RFC1918 private block can simply be tagged as NAT. The effect is that any traffic from that subnet has NAT set by default. Again, this can be overridden by firewall rules.

Whenever you define a subnet or one is created dynamically (e.g. by DHCP), an associated route is automatically created for the associated prefix. Packets being routed to a subnet are sent to the Ethernet interface that the subnet is associated with. Traffic routed to the subnet will use ARP or ND to find the final MAC address to send the packet to.

In addition, a subnet definition creates a very specific single IP (a "/32" for IPv4, or a "/128" for IPv6) route for the IP address of the FB2700 itself on that subnet. This is a separate loop-back route which effectively internally routes traffic back into the FB2700 itself - i.e. it never appears externally.

A subnet can also have a gateway specified, either in the config or by DHCP or RA. This gateway is just like creating a route to 0.0.0.0/0 or ::/0 as a specific route configuration. It is mainly associated with the subnet for convenience. If defined by DHCP or RA then, like the rest of the routes created by DHCP or RA, it is removed when the DHCP or RA times out.

Example: <subnet ip="192.168.0.1/24"/> creates a route for destination 192.168.0.0/24 to the interface associated with that subnet. A loop-back route to 192.168.0.1 (the FB2700's own IP address on that subnet) is also created.

Routes can be defined to forward traffic to another IP address, which will typically be another router (often also called a gateway) For such a routing target, the gateway's IP address is then used to determine how to route the traffic, and another routing decision is made. This subsequent routing decision usually identifies an interface or other data link to send the packet via - in more unusual cases, the subsequent routing decision identifies another gateway, so it is possible for the process to be 'recursive' until a 'real' destination is found.

Example: <route ip="0.0.0.0/0" gateway="192.168.0.100"/> creates a default IPv4 route that forwards traffic to 192.168.0.100. The routing for 192.168.0.100 then has to be looked up to find the final target, e.g. it may be to an Ethernet interface, in which case an ARP is done for 192.168.0.100 to find the MAC to send the traffic.

There is logic to ensure that the next-hop is valid - the gateway specified must be routable somewhere and if that is via an Ethernet interface then the endpoint must be answering ARP or ND packets. If not, then the route using the gateway is suppressed and other less specific routes may apply.

It is possible to define two special targets :-

The blackhole and nowhere top-level objects are used to specify prefixes which are routed to these special targets. In the User Interface, these objects can be found under the Routes category icon.

When using BGP you can also define a network which is announced by default, along with any dead-end-community, and treated otherwise the same as nowhere.

The following timing control parameters apply :-

The timeout and recover parameters do not apply to manually set profiles (see Section 9.2.4) and those based on time-of-day (see Section 9.2.2.2).

The tests described in the previous section are used to form an overall test result. Normally this overall result is used to determine the profile state using the mapping Pass > Active and Fail > Inactive. By setting the invert attribute to true, the overall result is inverted (Pass changed to Fail and vice-versa) first before applying the mapping.

You can manually override all tests, and force the profile state using the set attribute - a value of true forces the state to Active, and false forces it to Inactive.

These profiles can be used as simple on/off controls for configuration objects. The following shows an example of two fixed-state profiles and one control switch, expressed in XML :-

<profile name="Off" set="false"/>
<profile name="On" set="true"/>
<profile name="IT-Support"
         comment="Allow IT support company access to server"
	 set="control-switch"/>

Note that the value of the invert attribute is ignored when manual override is requested. If we add special case switched profiles that are used internally, these will be named starting with fb-, so it is best not to name your own profiles starting fb-. An example of the ACME renewal control profile is given below.

As with many things in the FireBrick it is possible to script access to the control pages. The control profiles are a particularly useful example of this as it allows external scripts to control if a profile is active or inactive.

Obviously security is a concern, and it is possible to create a user allowed access only from some IP addresses, and even allowed NOBODY level access, but listed as a user allowed to set a specific control profile. This then allows a script using a username and password to control the profile from specific machines.

For example, setting a named profile:-

curl --silent --user name:pass 'http://1.2.3.4/profile?set=profilename'

And unsetting a named profile:-

curl --silent --user name:pass 'http://1.2.3.4/profile?unset=profilename'

Several objects in the FB2700's configuration allow you to specify the name of a graph, by setting the value of the graph attribute. This causes the traffic flow that is associated with that object (a firewall rule, an interface, or whatever the attribute is attached to) to be recorded on a graph with the specified name. For connections that have a defined state, such as a PPP link, the graph will also show the link state history. Other information, such as packet loss and latency may also be displayed, depending on whether it can be provided by the type of object you are graphing.

For example, the XML snippet below shows the graph attribute being set on an interface. As soon as you have set a graph attribute (and saved the configuration), a new graph with the specified name will be created.

 <interface name="LAN"
            port="LAN"
            graph="LAN">

The graph is viewable directly from the FB2700 via the web User Interface - to view a graph, click the "PNG" or "SVG" item in the "Graphs" menu. This will display all the graphs that are currently configured - it is not currently possible to show a single graph within the web User Interface environment.

It is possible to access the graph data in many ways, using the URL to control what information is shown, labels, and colours, and also allowing graphs to be archived. See Appendix K for more details.

Alternatively, the underlying graph data is available in XML format, again via the FB2700's built-in HTTP server. The XML version of the data can be viewed in the web User Interface by clicking the "XML" item in the "Graphs" menu, and then clicking on the name of the graph you're interested in.

Both directions of traffic flow are recorded, and are colour-coded on the PNG image generated by the FB2700. The directions are labelled "tx" and "rx", but the exact meaning of these will depend on what type of object the graph was referenced from - for example, on a graph for an interface, "tx" will be traffic leaving the FB2700, and "rx" will be traffic arriving at the FB2700.

Each data point on a graph corresponds to a 100 second interval ; where a data point is showing a traffic rate, the rate is an average over that interval. For each named graph, the FB2700 stores data for the last 24 hours.

Once you have graphed a (possibly bi-directional) traffic flow, you can then also define speed restrictions on those flows. These can be simple "Tx" and "Rx" speed limits or more complex settings allowing maximum average speeds over time.

You define the speed controls associated with the graphed traffic flow(s) by creating a shaper top-level object. To create or edit a shaper object in the web User Interface, first click on the "Shape" category icon. To create a new object, click the "Add" link. To edit an existing object, click the appropriate "Edit" link instead.

The shaper object specifies the parameters (primarily traffic rates) to use in the traffic shaping process, and the shaper is associated with the appropriate existing graph by specifying the name attribute of the shaper object to be the same as the name of the graph.

You can define a shaper object and set the speed controls for that shaper, and then define the graph attribute on something, e.g. an interface, to apply that shaper to the interface.

It is also possible, in most cases, to simply set a speed attribute on some object. This creates an un-named shaper (so no graph) which has the specified speed for egress (tx). This is unique to that object unlike named shapers which are shared between all objects using the same named shaper.

It is also possible to set graph and speed attributes to create a named shaper with the specified speed, without having to create a separate shaper object.

If you set a graph attribute without a speed attribute or creating a shaper object then that simply creates a graph without traffic shaping. Multiple objects can share the same graph.

Graphs can sometimes be created automatically and may have speeds applied. For L2TP sessions the circuit ID (which may be overridden by RADIUS auth responses) is used to make a graph for the session.

If defining a shaper using the shaper object there are a number of extra options which allow a long term shaper to be defined. A long term shaper is one that changes the actual speed applied dynamically to ensure a long term usage level that is within a defined setting.

The key parameters for the long term shaper are the target speed (e.g. tx), the minimum speed (e.g. tx-min) and maximum speed (e.g. tx-max). The target speed is the maximum rate that should apply over a long term, but actual speed is set dynamically between min and max rates.

The rate is initially set to the maximum. Actual usage below the target builds up credit. This credit is limited to allow a defined minimum burst time at the maximum rate. So if not used for a while the maximum rate can be used for the minimum burst time. However continued use at more than the target will accumulate over usage.

Once this credit is used up the rate starts to drop. It will drop all the way to the minimum set if necessary.

Once the over usage is cleared, but less usage or usage capped to below the target rate, the rate increases to the target rate.

Once a further credit is accumulated by lower usage than the target, and this is at a level to allow the minimum burst time at maximum rate, the rate increases to the maximum rate again.

Shapers can be shared between FireBricks with a common broadcast domain.

The interface to broadcast and listen on for sharing is set via the share-interface setting in the global cqm options. Once that is configured then setting the share option on a shaper will combine its state with that of other FireBricks when calculating any damping required.