XML Config

The FireBrick FireBrick 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 FireBrick can be accessed via web interface using its IP address. This provides the 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 FireBrick.
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.

Important: a new FireBrick will have no users defined – in this state you can access the web pages and edit the config with no access controls defined. Once a user is defined the access is restricted to users.

Download config

Perform a GET on the URL /config/config to get the current config. This can be done using the following curl command:-

curl http://IP-address/config/config –user “username:password” –output “filename“

Upload config

To upload the config you need to send the config file as if posted by a web form using encoding type multipart/form-data. This can be done using the following curl command:-

curl http://IP-address/config/config –user “username: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 FireBrick, edit it, and sent it back to the FireBrick. 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 starts with <?xml version=”1.0″ encoding=”UTF-8″?> which defines the version and character encoding. UTF-8 is used everywhere by the FireBrick.

In the file are elements, which have a start tag, some content, and an end tag. Elements with no content can have a self-closing tag. The content of the element can be other elements or text, but the FireBrick does not put text within elements.
At the top level the file normally only has one element, and then has other elements within it.

The start tag consists of a < followed by the tag name and possibly a number of attributes which are name=”value” or name=’value’, and then >. The end tag is just </ followed by the tag name followed by >. A self-closing tag is the same as a start tag but ends /> and then has no content or end tag.

Whilst there is generally not any text between the tags, white space (spaces and line breaks) are normally used to make the layout clear.

There are special character sequences which are used to avoid any clash with these control character. They are &amp; for an &, &lt; for <, &gt; for >, and &quot; for “. Apart from these you can use any ASCII and UTF-8 characters.

Config files

The config file starts with the <?xml… line and then has a single XML element which is called config. I.e. it starts with a start tag for config and then has a number of other elements and finally ends with an end tag 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 state 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 elements in the config element are the top-level elements in the FireBrick configuration, each has start and end elements or maybe self-closing. They may have attributes on the start or self-closing element and have other elements between the start and end.

Specific documentation for your FireBrick

The software release pages provide a number of files which you can download. These include the code for the release and boot-loader but also include an XSDfile and Doc file.

The XSD file is a formal definition of the XML configuration for that specific release of the 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 elements 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.

Numbers

As simple integers are often used for things like line speeds, all integers can be input using SI abbreviations G (giga), M (mega) or k (kilo). If these are used then a decimal part can be used as well. E.g. 1.5k means 1500. You can also use IEC abbreviations Gi (gibi), Mi (mebi) or Ki (kibi). You can also add B for bytes, e.g. 1.5MiB means 12582912.

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 from 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-B.
  • 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 indicate 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 a hyphen and 0-65535. It can be one number meaning range of one. The second number has to be higher or the same as the first number.

A leading – means 0-, and a trailing – means -65535.

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.

Duration

A duration is a period of time in seconds and can be HH:MM:SS or MM:SS or seconds. You can simply enter a number of seconds greater than 59 though.

Colour

A colour is #rgb, #rgba, #rrggbb, #rrggbbaa, or one of a set of named colours.

Rational

A positive rational number, e.g. 1/3.

Password

Passwords can be entered when saving the config, but as part of the saving process, they are converted to a hash. Passwords retrieve are always presented as the hash.
There are three formats of hash, and these can be pre-calculated and supplied as a hash when saving a config if you wish. All are a prefix, such as MD5# followed by hexadecimal.

  • SHA1# followed by 20, 21, 22 or 23 bytes worth of hex. The first 20 bytes are the hash. The 0 to 3 extra bytes are salt. The hash is of the password concatenated with any salt on the end. SHA1 is the preferred format.
  • MD5# followed by 16, 17, 18 or 19 bytes worth of hex. The first 16 bytes are the hash. The 0 to 3 extra bytes are salt. The hash is of the password concatenated with any salt on the end.
  • FB105# followed by 20 bytes worth of hex. This is a legacy format used when converting configuration files from a FireBrick FB105. The format is not documented.

 

Even though the passwords are hashed, you should avoid disclosing the hashes as they can be vulnerable to dictionary attacks. You should also ensure passwords are of suitable quality in the first place to avoid such attacks.

Secret

A secret is just a string, but there is an option to show the config with secrets suppressed.