FireBrick - Firewalls, Bonding ADSL, Routers, Traffic Shaping...
FireBrick FB6000
XML configuration
The FireBrick FB6000 series products have at their core a configuration file which is defined using XML (eXtensible Markup Language). This is very similar to web pages but has a more strict syntax and layout.
Managing the config
The FB6000 can be accessed via web interface using its IP address. This provides a main menu which includes the config management pages which are under the URL /config/. Initially there are no users defined, and this means anyone who can access the web pages can manage the config. You should immediately add a user and password to a new FB6000. The simplest way to do this is if via the config edit menu, adding a line in the main <config...> section like <user name="somename" password="somepassword"/>. Once added you will have to login to do any more with the main web interface.
Many users will want to download and upload the config from a script. This can be done without having to mimic normal web page login and session tracking as follows.
Download config
Perform a GET on the URL /config/config?username=username&password=password to get the current config. This can be done using the following curl command:-
curl http://IP-address/config/config --get --data username="username" --data password="password" --output "filename"
Upload config
To upload the config you need to send the config file, and username and password as if posted by a web form using encoding type multi-part/form-data. This can be done using the following curl command:-
curl http://IP-address/config/config --form username="username" --form password="password" --form config="@filename"
General tips
If you have XML editing tools then they may be a good way to manage the config file, but many people will simply edit the file directly using a simple text editor. If you have a text editor with syntax hi-lighting then that is ideal for editing XML and helps avoid simple syntax errors.
We recommend you start with a config received from the FB6000, edit it, and sent it back to the FB6000. This will alert you to any errors that have been detected so you can correct them and try again.
About XML
The syntax of XML is very formally defined. The file itself has to start with <?xml version="1.0" encoding="UTF-8"?>.
The file has elements that are between < and >. Outside these there can, in some cases, be text but usually it is just white space.
The elements come in different forms. A start element is < followed by a word and the possibly attributes and >. An end element is </ followed by a word and >. For every start there is later a matching end using the same word. Usually the elements between these are indented to show that they are inside the object that has been started and ended, however the spacing, line breaks and indentation are not important.
There is a special case of < a word, possibly some attributes and /> which is a self closing element, i.e. a start and end together.
The attributes are of the form name="value" or name='value'. The choice of " or ' is not relevant. The attributes are included between the <word and the > and separated by spaces.
There are special sequences that avoid any clash with these control character. They are & for an &, < for <, > for >, and " for ". Apart from these you can use ASCII and UTF-8 characters.
Config files
The config file starts with the <?xml... line and then has a single XML object which is called config. I.e. it starts with a start element for config and then has a number of other object and finally ends with an end element for config. The starting <config...> will also include a number attributes xmlns, xmlns:xsi and xsi:noNamespaceSchemaLocation. These attributes are a formal part of the configuration file that define where the config is defined, so you do not need to change these. The attributes may change when you upgrade your FireBrick to a later software version.
The objects in the config object are the top level objects in the FireBrick configuration, each has start and end elements or may be self-closing. They may have attributes on the start or self-closing element, and have other objects between the start and end.
Specific documentation for your FB6000
The software release pages provide a number files which you can download. These include the code for the release and boot-loader but also include an XSD file and Doc file.
The XSD file is a formal definition of the XML configuration for that specific release of software. It is itself an XML document and is mainly used for XML editors and management tools so that the tools know what is and is not allowed in the config.
The Doc file is a web page format manual for the XML configuration and lists all of the objects and attributes that are valid with ranges of values where appropriate and defaults where defined and comments explaining the operation of the config.
Specific data types
The documentation often specifies the default value that applies when an attribute is not specified. Where this is not the case, and there are no notes indicating otherwise, the default is the logical zero. e.g. an empty list for a list of items, or a numeric value 0 or an empty string or false for a boolean. In some cases, especially boolean values, there can be a default that depends on other factors or attributes and this is explained in the notes.
Lists
As per XSD standards an attribute that is a list of a simple type consists of a simple string of values separated by spaces. e.g. a list of IPs could be "192.168.0.1 192.168.0.2" meaning two IP addresses.
IP addresses
An IP address can be quoted in normal dotted quad IPv4 format (e.g. 192.168.0.1) or valid IPv6 format (e.g. 2001:DB8::1) including using IPv4 tail on the IPv6 address (e.g. 2001:DB8::192.168.0.1).
IP prefix or subnet
An IP prefix is an IP address followed by a slash and a bit length (e.g. 192.168.0.0/24). Where the slash and bit length is omitted this means the full bit length (e.g. 192.168.0.1 means 192.168.0.1/32). Where the full bit length applies the slash and bit length are omitted. Note that this is different to some other systems that omit the bit length when the prefix matches old style class based prefixes. e.g. 192.168.0.0 means 192.168.0.0/32 and not 192.168.0.0/24.
A prefix allows any IP to be entered but is always returned as the base IP. e.g. 192.168.0.1/24 would be output as 192.168.0.0/24. A subnet has an IP and bit length but the specific IP matters so it is not truncated. e.g. 192.168.0.1/24 as a subnet means IP address 192.168.0.1 in a 192.168.0.0/24 subnet.
Named IP lists
A prefix can, in some cases, be shown as a name which references a named prefix list defined elsewhere.
IP prefix filter
A prefix filter is used to test if a prefix (i.e. IP/len) is within a specific range. There are a number of syntax variations.
- ip means the single IP prefix, e.g. ip/32 for IPv4
- ip/A means the prefix with specific bit-length A. ip must match A bits of the prefix.
- ip/A-B means the prefix with bit-length in range A to B. ip must match A bits of the prefix.
- ip/A- Same as ip/A-32 for IPv4 or ip/A-128 for IPv6.
- ip/-B Same as ip/0-A.
- ip/A:B-C means the prefix with bit-length in range B to C. ip must match A bits of the prefix.
- ip/A:B Same as ip/A:B-B
IP range
In some instances an IP range can be specified. This only applied to IPv4 addresses. The general syntax is IP-IP but this can be simplified. e.g. 192.168.0.100-192.168.0.199 is the same as 192.168.0.100-199. Also, the range can be used with .X on the end, e.g. 192.168.10-20.X meaning 192.168.10.0-192.168.20.255. If the range matches an IP prefix, e.g. 172.16-31.X.X then this is shown as the prefix, e.g. 172.16.0.0/12.
IP ranges are used for firewall rules and the like. Usually a name can be used instead to indicated a named IP list defined elsewhere.
Community
A BGP community is shown either as a name for standard communities (65535:65281=no-export 65535:65282=no-advertise 65535:65283=local-as 65535:65284=no-peer) or as two decimal 16 bit numbers separated by a colon.
Port range
A port range is 0-65535 followed by hyphen and 0-65535. It can be one number meaning range of one. Second number has to be higher or the same as the first number.
Date/time
As per XSD standards, the date and date time are shown as YYYY-MM-DDTHH:MM:SSZ (e.g. 2010-02-06T10:46:09Z). The Z means zulu (UTC). Without the Z the time is assumed to be "local time" relevant for current time zone and daylight saving rules. Dates are just YYYY-MM-DD.
Colour
A colour is #rgb, #rgba, #rrggbb, #rrggbbaa, or one of a set of named colours.
Password
A password field allows input of a simple string, but this is then stored as a hash with salt and output as hex starting SHA1#. It is valid to enter SHA1# followed by a hex SHA1 of a password, or MD5# followed by a hex MD5 of a password too.
Secret
A secret is just a string, but there is an option to show the config with secrets suppressed.
Immutability
You can edit the config on the web pages or send and retrieve the config via applications such as curl. However, the config is never changed by the FB6000 - if you get the config from the FB6000 and get it again later, having not changed it, they will be the same.
When you send the config to the FB6000 it is recommended you get a copy back again afterwards as the process of storing the config will causes changes as follows:-
- The timestamp on the top level xml object will be set to the current time when the config is stored, ignoring whatever was in the file you sent.
- The layout will change to use consistent spacing and indentation regardless of formatting in your original file.
- The order of objects and attributes within an object will change to that defined in the XSD regardless of the order in your file. Where there a list of objects of the same type the order you specify is preserved though as this is often important to the operation of the FB6000.
- Passwords that are not already in MD5# or SHA1# format are automatically change the be a hash (normally SHA1# with random salt).
- Data values are normalised, e.g. an IP prefix using other than the first IP in the block is changed to show as first IP in the block. Variations of formatting for IPv6 addresses are shown in a consistent format. Etc. Basically, the output config uses the raw binary data for the data values to generate the config file that is returned.
- XML comments are not saved. Most object allow a comment="..." attribute for adding comments about the config and is recommended that you use this rather than <!-- ... --> style comments which are lost.
One exception is that the config includes the xsd reference and version which can change if you upgrade the software. A software upgrade can also change what is valid in the config, so could mean obsolete attributes and objects are no longer present in the config you retrieve.