| 3.5. Data types | ||
|---|---|---|
 | Chapter 3. Configuration |  |
| 3.5. Data types | ||
|---|---|---|
| | Chapter 3. Configuration | |
All of the actual values in the configuration are provided by means of XML attributes, and so they are represented as a string of characters. The value is escaped as per XML rules, e.g. & for &, < for <, > for > and " for " within the string between the quote marks for the attribute value.
Obviously, even though all data is just a string, there are actually different data types, as defined in Section I.4, some of which have value restrictions (range of numbers, or specific string lengths, etc). Some of these are described in more details here.
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 I.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#92E12F9A333C68690078AC041CD840996EB366A190F7D8966C48AB84A5729F66DCBC7C1A019FC277583684E81015EA. 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 H.
Being an IP based 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.
Where a simple IP address is expected you can enter in any valid format for IP addresses. In some cases the field may specifically be IPv4 or IPv6 but in most cases either type of IP address can be entered. In the case of IPv6, the :: shortened format is accepted, and used on output. The legacy format, e.g. 2001:db8::192.168.0.1 format is also accepted as per IPv6 RFCs.
There is also a case where up to one IPv4 and up to one IPv6 address can be specified (separated by a space), e.g. when setting the source IP address for some protocol.
In some cases an IP address and subnet length is expected (in CIDR format), e.g. 192.168.0.1/24. There are two variations of this, one is a subnet which includes an IP address and length, such as 192.168.0.1/24. The other case is where the prefix is what matters, and so the IP address can be any within the prefix, so 192.168.0.1/24 would actually read back as 192.168.0.0/24.
Where the subnet is one IP, e.g. 192.168.0.1/32 it can be provided as, and reads back as a simple IP address, i.e. 192.168.0.1.
In some cases a range of IP addresses is needed, for example when making a filter for firewall rules or allow lists.
For IPv4 addresses this can use a format using a hyphen, e.g. 192.168.0.100-199. Where the range is wider there may be more after the hyphen, e.g. 192.168.0.100-1.99 is all from 192.168.0.100 to 192.168.1.99. Ultimately it can be a complete range such as 10.1.2.3-11.100.2.5, though that is rarely needed.
Where a range covers all parts after the hyphen then an X can be used, e.g. 10.2-4.X.X for 10.2.0.0 to 10.4.255.255.
A range can be provided as a simple IP address (for one IP in range) or as a CIDR format. IPv6 address ranges can only be CIDR format prefixes. If a range happens to be a CIDR range it shows in that format. E.g. 192.168.0.0-192.168.255.255 will read back as 192.168.0.0/16.
In some cases a list of IP ranges can also include named IP groups. In which case the IP groups are checked by name, firstly in the case of a rule-set where ip-group entries are specified, then system ip-group entries, and then named subnet entries (including DHCP client subnets).
| |  | |
| 3.4. Configuration upgrades and versioning |  | 3.6. Default values |