Add a user guide for 'vppcfg check'
This commit is contained in:
@ -1,9 +1,109 @@
|
|||||||
# A VPP Configuration Utility
|
# A VPP Configuration Utility
|
||||||
|
|
||||||
|
`vppcfg` is a commandline utility that applies a YAML based configuration file
|
||||||
|
safely to a running VPP dataplane. It contains a strict syntax and semantic validation,
|
||||||
|
and a path planner that brings the dataplane from any configuration state safely to any
|
||||||
|
other configuration state, as defined by these YAML files.
|
||||||
|
|
||||||
## User Guide
|
## User Guide
|
||||||
|
|
||||||
|
```
|
||||||
|
usage: vppcfg [-h] [-d] [-q] [-f] {check,dump,plan,apply} ...
|
||||||
|
|
||||||
|
positional arguments:
|
||||||
|
{check,dump,plan,apply}
|
||||||
|
check check given YAML config for validity (no VPP)
|
||||||
|
dump dump current running VPP configuration (VPP readonly)
|
||||||
|
plan plan changes from current VPP dataplane to target config (VPP readonly)
|
||||||
|
apply apply changes from current VPP dataplane to target config
|
||||||
|
|
||||||
|
optional arguments:
|
||||||
|
-h, --help show this help message and exit
|
||||||
|
-d, --debug enable debug logging, default False
|
||||||
|
-q, --quiet be quiet (only warnings/errors), default False
|
||||||
|
-f, --force force progress despite warnings, default False
|
||||||
|
```
|
||||||
|
|
||||||
### vppcfg check
|
### vppcfg check
|
||||||
|
|
||||||
|
The purpose of the **check** module is to read a YAML configuration file and validate
|
||||||
|
its syntax (using Yamale) and its semantics (using vppcfg's constraints based system).
|
||||||
|
If the config file is valid, the return value will be 0. If any syntax errors or semantic
|
||||||
|
constraint violations are found, the return value will be non-zero.
|
||||||
|
|
||||||
|
The configuration file (in YAML format) is given by a mandatory `-c/--config` flag, and
|
||||||
|
optionally a Yamale schema file, given by the `-s/--schema` flag (which will default to
|
||||||
|
the built-in default schema). Any violations will be shown in the ERROR log. A succesful
|
||||||
|
run will look like this:
|
||||||
|
|
||||||
|
```
|
||||||
|
$ ./vppcfg check -c example.yaml
|
||||||
|
[INFO ] root.main: Loading configfile example.yaml
|
||||||
|
[INFO ] vppcfg.config.valid_config: Configuration validated successfully
|
||||||
|
[INFO ] root.main: Configuration is valid
|
||||||
|
$ echo $?
|
||||||
|
0
|
||||||
|
```
|
||||||
|
|
||||||
|
A failure to validate can be due to one of two main reasons. Firstly, syntax violations
|
||||||
|
that trip the syntax parser, which can be seen in the output with the tag `yamale:`:
|
||||||
|
|
||||||
|
```
|
||||||
|
$ cat yamale-invalid.yaml
|
||||||
|
interfaces:
|
||||||
|
GigabitEthernet1/0/0:
|
||||||
|
descr: "the proper field name is description"
|
||||||
|
mtu: 127
|
||||||
|
|
||||||
|
$ ./vppcfg check -c yamale-invalid.yaml
|
||||||
|
[INFO ] root.main: Loading configfile yamale-invalid.yaml
|
||||||
|
[ERROR ] vppcfg.config.valid_config: yamale: interfaces.GigabitEthernet1/0/0.descr: Unexpected element
|
||||||
|
[ERROR ] vppcfg.config.valid_config: yamale: interfaces.GigabitEthernet1/0/0.mtu: 127 is less than 128
|
||||||
|
[ERROR ] root.main: Configuration is not valid, bailing
|
||||||
|
$ echo $?
|
||||||
|
254
|
||||||
|
```
|
||||||
|
|
||||||
|
Some configurations may be syntactically correct but still can't be applied, because they
|
||||||
|
might break some constraint or requirement from VPP. For example, an interface that has an
|
||||||
|
IP address can't be a member in a bridgedomain, or a sub-interface that has an IP address
|
||||||
|
with an incompatible encapsulation (notably, the lack of `exact-match`).
|
||||||
|
|
||||||
|
Semantic violations are mostly self-explanatory, just be aware that one YAML configuration
|
||||||
|
error may trip multiple validators:
|
||||||
|
|
||||||
|
```
|
||||||
|
$ cat semantic-invalid.yaml
|
||||||
|
interfaces:
|
||||||
|
GigabitEthernet3/0/0:
|
||||||
|
sub-interfaces:
|
||||||
|
100:
|
||||||
|
addresses: [ 192.0.2.1/30 ]
|
||||||
|
encapsulation:
|
||||||
|
dot1q: 100
|
||||||
|
GigabitEthernet3/0/1:
|
||||||
|
mtu: 1500
|
||||||
|
addresses: [ 10.0.0.1/29 ]
|
||||||
|
|
||||||
|
bridgedomains:
|
||||||
|
bd1:
|
||||||
|
mtu: 9000
|
||||||
|
interfaces: [ GigabitEthernet3/0/1 ]
|
||||||
|
$ ./vppcfg check -c semantic-invalid.yaml
|
||||||
|
[INFO ] root.main: Loading configfile semantic-invalid.yaml
|
||||||
|
[ERROR ] vppcfg.config.valid_config: sub-interface GigabitEthernet3/0/0.100 has an address but its encapsulation is not exact-match
|
||||||
|
[ERROR ] vppcfg.config.valid_config: interface GigabitEthernet3/0/1 is in L2 mode but has an address
|
||||||
|
[ERROR ] vppcfg.config.valid_config: bridgedomain bd1 member GigabitEthernet3/0/1 has an address
|
||||||
|
[ERROR ] vppcfg.config.valid_config: bridgedomain bd1 member GigabitEthernet3/0/1 has MTU 1500, while bridge has 9000
|
||||||
|
[ERROR ] root.main: Configuration is not valid, bailing
|
||||||
|
$ echo $?
|
||||||
|
254
|
||||||
|
```
|
||||||
|
|
||||||
|
In general, it's good practice to check the validity of a YAML file before attempting to
|
||||||
|
offer it for reconciliation. `vppcfg` will make no guarantees in case its input is not
|
||||||
|
fully valid!
|
||||||
|
|
||||||
### vppcfg dump
|
### vppcfg dump
|
||||||
|
|
||||||
### vppcfg plan
|
### vppcfg plan
|
||||||
|
Reference in New Issue
Block a user