Configure

From securityrouter.org, an OpenBSD-based firewall
Jump to: navigation, search

This page describes how to interact with the configuration file using the configure command. Configure may be invoked from the CLI interface, or from the system shell, its privilege level is inherit from the invoking user. Once started configure present you with an interactive prompt. Type help for a complete list of commands.

admin@fw1.halon.se> configure
[]
admin@fw1.halon.se# 

The latest configuration revision is checked out before prompting for commands. If the configuration is changed by another user or instance you may update configures working copy with the checkout command.

Action Syntax Example
Checkout a revision checkout [<revision>] checkout
View revision log log [<limit>] log 5

Working with the configuration

The Configuration file has a hierarchical format, with one statement per line, and child/parent relationships indicated by curly brackets and tabs. A local copy (that has been checked out) may be viewed with the show command.

system {
        authentication {
                user "admin" {
                        password "...
                }
        }
}

This concept with child/parent scopes and attributes may be think of as if each scope system { authentication { user "admin { were folders in a file system hierarchy, and password were a file. This concept of files and folders has the same benefits in the configure command as in your operating system shell, it allows you to filter information as you move into a scope or folder. This allows for shorter relative paths when you invoke commands and less noise.

Paths and commands may be auto-completed with the TAB key.

Action Syntax Example
Enter a configuration scope edit [<path>] edit system {
Leave a configuration scope edit [<path>] edit .. {
Show a configuration scope show [<path>] show system { authentication {
Show changes of the scope compare [<n>] [<m>] [<path>] edit system {
compare authentication {

For the compare command, if n is not specified it defaults to the local checkout. If m is not specified it defaults to the modified local copy.

admin@fw1.halon.se# edit system { 
[system]
admin@fw1.halon.se# edit authentication { 
[system { authentication]
admin@fw1.halon.se# show
authentication {
        user "admin" {
                password "$2a$06$vCj.oFZNS8MZjeu/J/fJ0O/OgURa7lVGN/2kUxijN8BmPrRfMyRq2" # SALTED-HASH
        }
}
[system { authentication]
admin@fw1.halon.se# edit ..
[system]
admin@fw1.halon.se#

The following commands may be used to modify the configuration.

Action Syntax Example Comment
Import import [<path>] import Imports a new configuration (from stdin)
Set set <path> [<attr>] set interface em0 { dhcp-server { Add a dhcp-server scope on em0
Delete delete <path> [<attr>] delete interface em0 { dhcp-server { Delete the dhcp-scope
Move rename <path> to <path> rename interface em0 { dhcp-server { to interface em1 { Moves the dhcp-server from em0 to em1
Rename rename <path> to <path> rename interface bridge0 { to interface bridge1 { Rename bridge0 to bridge1
Replace replace <xxx> with <yyy> replace bridge0 with bridge1 Replace bridge0 with bridge1 (textual)
Replace/Swap replace-swap <xxx> with <yyy> replace-swap em0 with em1 Swap em0 with em1 (textual)
Copy copy <path> to <path> copy interface em1 { dhcp-server { to interface em2 { dhcp-server { Copy the dhcp-server from em1 to em2

Once done editing the configuration, changes may be applied using the "commit" command.

Action Syntax Example Comment
Commit commit [-time <sec>] [msg] commit -time 60 Added a vlan Commits the configuration with the message "Added a vlan" during 60 seconds.
Confirm commit-confirm [<uuid>] commit-confirm xxxx-xx.. Confirm a pending commit (use -time on commit).
Cancel commit-cancel [<uuid>] commit-cancel xxxx-xx.. Cancel a pending commit (use -time on commit).
Promote promote-checkout promote-checkout Allow an old revision (not current) to be applied on to HEAD.
Rollback rollback [<revision>] rollback 13 If you're unhappy with your commit, you may rollback to a previous version.

If you leave the configure command, with uncommitted changes, you will be prompted.

Scripting with configure

configure may be used in script run by the local shell (sh). Commands are accepted as arguments, separated by a double dash (--). Errors are reported to stderr and it's terminated with a return code of 1 indicating an error. Requested data such as the output of show and commit are sent to stdout. A few examples follow.

# configure show > config.txt; echo $?
0
# configure import -- commit < config.txt; echo $?
No changes
1
# configure import -- commit < config.txt 2> /dev/null; echo $?
1
# vi config.txt (modify)
# configure import -- commit "added 5 new vlan's" < config.txt; echo $?
690
0
# configure delete system { dns { -- set system { dns { name-server 8.8.8.8 -- commit; echo $? 
691
0

A SOAP API is available for remote scripting.