VyOS configuration CLI commands are defined in *templates*. Templates are text files stored in a directory tree, where directory names define command names, and template files define command behaviour.
Configuration templates are stored in /opt/vyatta/share/vyatta-cfg-templates/
Quick example: suppose we want to add a dummy option that will be set with "set system options dummy-option".
```
# Create the directory for the command
sudo mkdir /opt/vyatta/share/vyatta-cfg/templates/system/options/dummy-option
# Create a template file
sudo sh -c 'echo "help: Dummy option" > /opt/vyatta/share/vyatta-cfg/templates/system/options/dummy-option/node.def'
```
Now you can see it in Tab completion, set it, and commit it.
vyos@vyos# set system options
Possible completions:
dummy-option Dummy option
reboot-on-panic
Reboot system on kernel panic
vyos@vyos# set system options dummy-option
vyos@vyos# commit
vyos@vyos# show system options
dummy-option
Template fields
===============
Node type fields
----------------
### type:
Defined allowed value type for the node.
Available types:
| Type | Description |
|---------|-------------------------------------------------------|
| txt | String, no format checks |
| bool | Boolean, available values are "true" and "false" |
| u32 | Unsigned 32-bit integer, e.g. 9000 |
| ipv4 | IPv4 address, e.g.192.0.2.199 |
| ipv4net | IPv4 with prefix length, e.g. 192.0.2.42/27 |
| ipv6 | IPv6 address, e.g. 2001:db8:af::100 |
| ipv6net | IPv6 address with prefix length, e.g. 2001:db8:1::/64 |
| macaddr | Colon separated MAC address, e.g. 00:aa:bb:cc:dd:ee |
Example:
File: system/options/dummy-option/node.def
type: u32
gives
vyos@vyos# set system options dummy-option fgsfds
"fgsfds" is not a valid value of type "u32"
Value validation failed
Set failed
This field is not mandatory. Nodes without type: field are considered "typeless" and can't have a value. This is commonly used for yes/no switches (like in "set interfaces ethernet eth0 disable").
### multi:
Allows the node to have multiple values (like in "set system name-server"). This field should be the first field in template.
Note that a multi node can not be a tag node and vice versa.
Example:
File: system/options/dummy-option/node.def
multi:
type: txt
gives
vyos@vyos# set system options dummy-option foo
vyos@vyos# set system options dummy-option bar
vyos@vyos# commit
vyos@vyos# show system options
dummy-option foo
dummy-option bar
### tag:
Tag nodes are named containers other nodes. E.g. in "interfaces ethernet eth0 address 192.0.2.1/24", "eth0" is a tag node, that serves as container for "address" and other nodes. Note that a tag node can not be multi. This field must be the first field in the file.
Child nodes of a tag nodes are defined inside node.tag directory.
Example:
system/
options/
dummy-option/
node.def
node.tag/
even-more-dummy-option/
node.def
File: system/options/dummy-option/node.def
tag:
type: txt
File: system/options/dummy-option/node.tag/even-more-dummy-option/node.def
type: u32
gives
vyos@vyos# set system options dummy-option foo even-more-dummy-option 42
vyos@vyos# set system options dummy-option bar even-more-dummy-option 9000
vyos@vyos# commit
vyos@vyos# show system options
dummy-option bar {
even-more-dummy-option 9000
}
dummy-option foo {
even-more-dummy-option 42
}
Completion help fields
----------------------
### help:
Defines the help string that is displayed at first level completion (i.e. for one level upper than the node).
File: system/options/dummy-option/node.def
help: Dummy option
gives
vyos@vyos# set system options <Tab press>
Possible completions:
dummy-option Dummy option
### comp_help:
Defines help string for the node displayed in Tab help for the node level.
Example:
File: system/options/dummy-option/node.def
type: txt
comp_help: Anything you want
gives
vyos@vyos# set system options dummy-option
Possible completions:
Detailed information:
Anything you want
### val_help:
Defines help strings for possible values. Typical format: "val_help: <value|type>; `<help>`{=html}". Note that you can use type names to generate type-specific help. Also you can use multiple val_help: fields.
Example:
File: system/options/dummy-option/node.def
type: txt
val_help: ipv4; IPv4 address to listen on
val_help: any; Listen on all addresses
gives
vyos@vyos# set system options dummy-option <Tab>
Possible completions:
<x.x.x.x/x> IPv4 address to listen on
any Listen on all addresses
### allowed:
Defines an embedded shell scripts that generates a list of allowed values. This is convenient in case allowed value list depends on the system state and configuration, e.g. network interfaces or configured rules.
Example:
File: system/options/dummy-option/node.def
type: txt
allowed: echo "foo bar baz"
gives
vyos@vyos# set system options dummy-option
Possible completions:
bar
baz
foo
**Note:** it does not prevent the user from setting other values, use syntax: or commit: fields for that.
Syntax check fields
-------------------
### syntax:
Defines syntax check for the value. Commonly used in form "syntax:expression:". This check is executed for "set" commands, if it fails, set fails too.
Example:
File: system/options/dummy-option/node.def
type: txt
syntax:expression: $VAR(@) in "foo", "bar", "baz"; "Value must be foo, bar, or baz"
gives
vyos@vyos# set system options dummy-option quux
Value must be foo, bar, or baz
Value validation failed
Set failed
In fields that support expressions you can use external executables for the checks, like 'syntax:expression: exec "/opt/vyatta/sbin/myscript.pl --value=$VAR(@)"; "Syntax error"'. If that executable returns 0, check is successful.
### commit:
Defines commit-time check. This is commonly used for consistency checks that can not be performed until the complete configuration is available, e.g. checking for mutually exclusive options.
Usage and syntax are identical to "syntax:" field.
Other fields
------------
### priority:
Defined how early in the commit process the node is processed. Use it if your node must be processed only when some other configuration is available (like there is no point in configuring BGP until routing policies are configured).
You can list all existing priorities by executing "/opt/vyatta/sbin/priority.pl".
### default:
Defines default value for the node that will be applied if the value is deleted.
Commit action fields
--------------------
These define embedded shell scripts that are executed at different stages or types of commit process.
### begin:
Executed at the beginning of commit, before everything else.
### end:
Executed at the end of commit, after everything else. This is commonly used as the only commit field if you want to define all the commit logic yourself.
### create:
Executed only if this is a newly created node.
### update:
Executed if node value has changes.
### delete:
Executed if node is deleted.