Difference between revisions of "Configuration file"

From securityrouter.org, an OpenBSD-based firewall
Jump to: navigation, search
Line 1: Line 1:
The functionality of the system is fully defined by
+
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
* its configuration file
 
* 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
 
 
  admin@fw1.halon.se> configure
 
  admin@fw1.halon.se> configure
 
  []
 
  []
Line 10: Line 6:
 
  ...
 
  ...
  
== The configuration file format ==
+
== How the file is used by the system ==
The
+
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 <pre>media autoselect</pre> to an <pre>interface</pre>. 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'' 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
 +
    }
 +
}

Revision as of 21:19, 6 October 2011

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

admin@fw1.halon.se> configure
[]
admin@fw1.halon.se# 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 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
    }
}