Configuration file

From, an OpenBSD-based firewall
Revision as of 11:38, 19 October 2011 by Anders (talk | contribs)
Jump to: navigation, search

This page mainly describes the syntax of the configuration. The functionality of the system is fully defined by its configuration file, and system modifications such as skeleton files if root access is enabled. Since root access is disabled by default, administrators can normally get a complete picture of the system by studying the configuration file. From the web administration, it can be viewed on the Configuration > Plain-text editor page. Using the CLI (for example over SSH) it is viewed by typing> configure
[] show
bgp {

How the file is used by the system

The configuration is stored in a revision-managed database. Every time a new configuration is saved, it is commited to the database. The current (running) configuration is shown by checking out the latest configuration revision; called HEAD. Each revision is associated with a revision number, which is a simple, increasing integer counter. When a user commits a configuration, it's first applied (made effective to the system). If the application was successful, it is saved.

Whenever a new configuration is applied, it's transformed into event keys, which may have an ID and several values. These new keys are compared to the old (running configuration) keys, comprising an event list. If a user commits a configuration which results in no events (differences in keys) an exception (error) is given. One example of this would be if a user added the line media autoselect to an interface. Since autoselect is the default media type, no event would be generated by this configuration change (which is correct, since it doesn't not represent a change in the system state). If a list of events were generated, it's delivered to the backend's routines responsible of updating the system state. The minimally necessary change in order to bring the system into the new requested state will be performed.

Upon boot (system startup) the latest revision (HEAD) is checked out by the backend, and compared to the old list of keys, which is of course empty. Thus, a every change necessary to bring a reset system into the state requested by the configuration is performed.

File format and syntax

The configuration has a hierarchical format, with one statement per line, and child/parent relationships indicated by curly brackets and tabs. For example, an IP address 2a01:2b0:3030:1337::1 on a network with prefix length 64 configured an a VLAN with tag 1 on a physical interface with device name em0 would be represented as

interface em0 {
    interface vlan1 {
        address 2a01:2b0:3030:1337::da7a/64

Configuration grammar

The table below specifies the entire configuration grammar, and what it does.

  • interface ifname
    • address cidr (both IPv4 and IPv6)
    • route cidr address (both IPv4 and IPv6)
      • label quoted string (only one)
    • group quoted string
    • description quoted string (only one)
    • mtu integer (only one)
    • lladdress linkaddress (only one)
    • media media (only one)
    • metric integer (only one)
    • rdomain integer (only one)
    • interface vlanid
      • generic options such as address
      • tag integer (defaults to the id, only one)
      • prio integer (defaults to 0, only one)
    • interface carpid
      • generic options such as address
      • vhid integer (defaults to the id, only one)
      • advbase integer (defaults to 0, only one)
      • advskew integer (defaults to 0, only one)
      • password quoted string (defaults to 0, only one)
      • state carpstate (defaults to 0, only one)
Grammar Category Multiple  Default Comment
interface name { Generic Yes n/a These shared interface options applies to most interfaces
    group quoted string Generic Yes n/a Add the interface to a group (good way to name interfaces)
    description quoted string Generic No n/a Only visual free-text description of the interface
    address cidr IP Yes n/a Add an address with netmask using CIDR notation (both IPv4 and IPv6)
    dhcp-client { IP Yes n/a Configure an address automatically using DHCP
        timeout integer IP No 60 DHCP client timeout in seconds
        retry integer IP No 300 DHCP client total retry timeout in seconds
        request dhcpobj IP Yes Everything Objects to request, such as "router" or "name-server"
    firewall { IP Yes n/a Add firewall rules (pf) directly to the interface as an conditional anchor
    route cidr address { Routing Yes n/a Add a static route to cidr via gateway address (both IPv4 and IPv6)
        label quoted string Routing No n/a Set a label on the route
    rdomain integer Routing No 0 Place the interface in the routing domain integer
    metric integer Routing No 0 Set the metric to integer hops, used by some routing protocols
    mtu integer Link No n/a Set the interface's MTU
    lladdress linkaddress Link No n/a Set the interface's link layer (MAC) address
    interface vlanid { VLAN Yes n/a Create a VLAN interface on the parent interface with tag id
        generic options Generic Yes n/a Most shared options such as address and group
        tag integer VLAN No Interface's id Set the interface's VLAN tag
        prio integer VLAN No 0 Set the interface's VLAN prio
    interface carpid { Failover Yes n/a Create a failover interface on the parent interface
        generic options Generic Yes n/a Most shared options such as address and group
        vhid integer Failover No Interface's id Set the virtual (redundant) IP's ID
        advbase integer Failover No 1 Set the virtual (redundant) IP's announce interval in seconds
        advskew integer Failover No 0 Skew the virtual (redundant) IP's announce interval
        password quoted string Failover No Empty Set the virtual (redundant) IP's authentication key
interface device { Physical Yes n/a Interface options for physical interfaces
    media media Physical No autoselect Set the interface's media type, such as "10baseT"
    mediaopt mediaopt Physical No n/a Set the interface's media options, such as "full-duplex" or "hostap" for 802.11
    mode mode Link Physical autoselect Set the interface's mode, such as "11g" for 802.11 wireless interfaces
    ssid quoted string 802.11 No n/a Set the interface's IEEE 802.11 ESSID
    key quoted string 802.11 No n/a Set the interface's IEEE 802.11 WPA2 key
    channel quoted string 802.11 No n/a Set the interface's IEEE 802.11 channel

Keywords Description  Example
interface ifname { Creates a scope for settings options on an interface, or at leasts makes sure that it exists. For example interface em0 { interface pfsync0 { will create an interface of type pfsync (which happens to handle firewall state synchronization) on the physical interface em0. This is probably a bad example, as such an interface is automatically created by the cluster-syncport keyword. interface em0 { interface pfsync0 {
group quoted string Assign the interface to a group, which is also a very good way to give interfaces names. interface em0 { group "wan"