Configuration mode templates

From VyOS
Jump to: navigation, search

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>". 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.