Conf Files#
This section discusses plugin configuration files and flags.
Conf File Location#
The location of the conf files directory, or individual conf files can be set using a VPP agent CLI start flag, or env variable export.
Conf file directory
Conf file directory flag:
-config-dir="."If the conf file directory is /opt/vpp-agent/dev, then start the VPP agent with this command:
vpp-agent --config-dir=/opt/vpp-agent/devSame conf file directory, but using the env variable of CONFIG_DIR:
export CONFIG_DIR=/opt/vpp-agent/devIndividual conf file location
Using per-plugin flags or env variables will override the conf file directory option.
If the etcd conf file location is /opt/vpp-agent/dev/etcd.conf, then start the VPP agent with the etcd conf file flag of --etcd-config= like so:
vpp-agent -etcd-config=/opt/vpp-agent/dev/etcd.confUsing the ETCD_CONFIG env variable:
export ETCD_CONFIG=/opt/vpp-agent/dev/etcd.confPlugin Conf Files#
Bolt#
-bolt-config= Bolt Conf File Options
| Option | Type | Default | Description |
|---|---|---|---|
| db-path | string | Path to Bolt DB file | |
| file-mode | os.FileMode | File mode and permission bits in decimal format | |
| lock-timeout | time.Duration | Timeout duration for waiting to obtain file lock, set to zero to wait indefinitely. |
Bolt References:
Cassandra#
-cassandra-config= Cassandra Conf File Options
| Option | Type | Default | Description |
|---|---|---|---|
| endpoints | string | list of host IP addresses of cassandra cluster nodes | |
| port | int | 9042 | Cassandra port |
| op_timeout | time.Duration | 600ms | Connection Timeout |
| dial_timeout | time.Duration | 600ms | initial session timeout, used during initial dial to server |
| redial_interval | time.Duration | 60sec | Interval between gocql attempts to reconnect to known down nodes |
| protocol_version | int | 4 | Sets the version of the native protocol to use. This will enable features in the driver for specific protocol versions. Generally this should be set to a known version (2,3,4) for the cluster being connected to. If it is 0 or unset (the default), then the driver will attempt to discover the highest supported protocol for the cluster. In clusters with nodes of different versions, the protocol selected is not defined (i.e., it can be any of the supported in the cluster). |
| TLS Setup | Defines client cert, client private key, certificate authority, whether to skip verification of server name & certificate, disable TLS |
Cassandra References:
Consul#
-consul-config=Consul Conf File Options
| Option | Type | Default | Description |
|---|---|---|---|
| address | string | 0.0.0.0:8500 | Consul server address |
| resync-after-reconnect | bool | false | Perform resync procedure for all registered plugins following reconnect to Consul server |
Consult References:
etcd#
-etcd-config=etcd Conf File Options
| Option | Type | Default | Description |
|---|---|---|---|
| endpoints | string | 172.17.0.1:2379 | list of host IP addresses of ETCD database server |
| dial-timeout | time.Duration | 1000000000ns | timeout for connecting to etcd |
| operation-timeout | time.Duration | 3000000000ns | timeout for any request-reply etcd operation |
| insecure-transport | bool | false | TLS not used |
| insecure-skip-tls-verify | bool | false | Controls whether a client verifies the server’s certificate chain and host name. If InsecureSkipVerify is true, TLS accepts any certificate presented by the server and any host name in that certificate. In this mode, TLS is susceptible to man-in-the-middle attacks. This should be used only for testing. |
| cert-file | string | TLS Certification File | |
| key-file | string | TLS certification key | |
| ca-file | string | CA file used to create a set of x509 certificates | |
| auto-compact | time.Duration | 0 | Interval between etcd auto compaction cycles. 0 means disabled |
| resync-after-reconnect | bool | false | Perform resync procedure for all registered plugins following reconnect to etcd server |
| allow-delayed-start | bool | false | Allow to start without connected ETCD database. Plugin will try to connect and if successful, overall resync will be called |
| reconnect-interval | time.Duration | 2000000000ns | Interval between attempts to reconnect to the etcd server |
etcd References:
FileDB#
-filedb-config=FileDB Conf File Options
| Option | Type | Default | Description |
|---|---|---|---|
| configuration-paths | string | A set of files/directories with configuration files. Examples are /path/to/directory/ or /path/to/file.ext. If the target is a directory, all .json or .yaml files are read. |
|
| status-path | string | Path to the file where status data will be stored. /path/to/status.txt is an example. If it is not defined, status is not propagated. The file extension determines whether the data will be stored in .json or .yaml format. The target cannot be a directory. |
Note: filesystem refers to the name of the FileDB plugin.
FileDB References:
GoVPPMux#
-govpp-config=GoVPPMux Conf File Options
| Option | Type | Default | Description |
|---|---|---|---|
| binapi-socket-path | string | /run/vpp-api.sock | defines path to the binapi socket file |
| connect-via-shm | bool | false | Connect to VPP for configuration requests via the shared memory |
| shm-prefix | string | Defines a prefix prepended to the name used for shared memory (SHM) segments. If not set, shared memory segments are created directly in the SHM directory /dev/shm. | |
| stats-socket-path | string | /run/vpp/stats.sock | Defines path to the stats socket file |
| resync-after-reconnect | bool | false | Perform resync procedure for all registered plugins following reconnect to VPP |
| retry-request-count | int | 0 | Number of binary API request retries if VPP is suddenly disconnected |
| retry-request-timeout | time.Duration | 500ms | Interval between binary API request retries |
| retry-connect-count | int | 3 | Number of connection request retries if VPP is not unreachable. |
| retry-connect-timeout | time.Duration | 1000000000ns | Interval between connection request retries |
| proxy-enabled | bool | true | Enable VPP proxy |
| health-check-probe-interval | time.Duration | time between health check probes | |
| health-check-reply-timeout | time.Duration | if this timer pops, probe is considered failed | |
| health-check-threshold | int | number of consecutive failed health checks until an error is reported |
GoVPPMux References:
GRPC#
-grpc-config=GRPC Conf File Options
| Option | Type | Default | Description |
|---|---|---|---|
| endpoint | string | 0.0.0.0:9111 | address of gRPC netListener |
| permission | int | 000 | Three or four-digit permission setup for unix domain socket file (if used) |
| force-socket-removal | bool | false | If set and unix type network is used, the existing socket file will be always removed and re-created |
| network | string | tcp | Available socket types: tcp, tcp4, tcp6, unix and unixpacket. |
| max-msg-size | int | 4096 | Maximum message size in bytes for inbound messages |
| max-concurrent-streams | unit32 | 0 | returns a ServerOption that will apply a limit on the number of concurrent streams to each ServerTransport |
| extended-logging | bool | false | Enables logging additional gRPC transport messages |
| insecure-transport | bool | false | if true, TLS configuration will not be used |
The following config file options are used if insecure-transport is false:
| Option | Type | Default | Description |
|---|---|---|---|
| cert-file | string | Required for creating a secure connection. example is /path/to/cert.pem | |
| key-file | string | Required for creating a secure connection. example is /path/to/key.pem | |
| ca-file | string | Set custom CA to verify client’s certificate. If not set, client’s certificate is not required. Examples ca-files are /path/to/ca1.pem and /path/to/ca2.pem |
This flag can be used to set the GRPC port:
-grpc-port=GRPC References:
Kafka#
-kafka-config=Kafka Conf File Options
| Option | Type | Default | Description |
|---|---|---|---|
| Addrs | string | 127.0.0.1:9092 | Kafka server addresses |
| group_id | string | Name of the consumer’s group | |
| TLS | TLS Configuration |
Kafka References:
KV Scheduler#
-kvscheduler-config=KV Scheduler Conf File Options
| Option | Type | Default | Description |
|---|---|---|---|
| record-transaction-history | bool | true |
History of processed transactions is recorded |
| transaction-history-age-limit | uint32 (in minutes) | 24hrs | Age limit for recording transaction history with the exception of permanently recorded init period |
| permanently-recorded-init-period | uint32 (in minutes) | 60min | Duration of period from init that will be permanently recorded |
| enable-txn-simulation | bool | false |
Enable transaction simulation |
| print-txn-summary | bool | true |
Print transaction summary for each transaction |
KV Scheduler References:
Linux Interface Plugin#
-linux-ifplugin-config=Linux Interface Plugin Conf File Options
| Option | Type | Default | Description |
|---|---|---|---|
| disabled | bool | false | Used to disable linux ifplugin |
| go-routines-count | int | 10 | How many goroutines (at most) will split configured network namespaces to execute the Retrieve operation in parallel |
Linux Interface References:
Linux IP Tables#
-linux-iptables-config=Linux IP Tables Plugin Conf File Options
| Option | Type | Default | Description |
|---|---|---|---|
| disabled | bool | false | Used to disable linux iptables plugin |
| go-routines-count | int | 10 | How many goroutines (at most) will split configured network namespaces to execute the Retrieve operation in parallel |
Linux IP Tables References:
Linux L3#
-linux-l3plugin-config=Linux L3 Plugin Conf File Options
| Option | Type | Default | Description |
|---|---|---|---|
| disabled | bool | false | Used to disable linux L3 plugin |
| go-routines-count | int | 10 | How many goroutines (at most) will split configured network namespaces to execute the Retrieve operation in parallel |
Linux L3 References:
Linux Namespace#
--linux-nsplugin-config=Linux Namespace Plugin Conf File Options
| Option | Type | Default | Description |
|---|---|---|---|
| disabled | bool | false | Used to disable linux namespace plugin |
Linux Namespace References:
Log Manager#
--logs-config=Log Manager Conf File Options
| Option | Type | Default | Description |
|---|---|---|---|
| default-level | string | info | Set default config level for every plugin. Overwritten by environmental variable ‘INITIAL_LOGLVL’ |
| loggers | Specifies a list of named loggers with their respective log levels. see loggers example below |
||
| hooks | Specifies a list of hooks for logging to external links. Parameters for a given hook are protocol, address, port and levels. See hooks example below. |
Loggers example:
loggers:
- name: "agentcore",
level: debug
- name: "status-check",
level: info
- name: "linux-plugin",
level: warnHooks example:
hooks:
syslog:
levels:
- panic
# - fatal
# - error
# - warn
# - info
# - debug
# fluent:
# address: "10.20.30.41"
# port: 4521
# protocol: tcp
# levels:
# - error
# logstash:
# address: "10.20.30.42"
# port: 123
# protocol: tcpLog Manager References:
Process Manager#
-process-manager-config=Process Manager Conf File Options
| Option | Type | Default | Description |
|---|---|---|---|
| template-path | string | path where process templates will be stored |
Process Manager References:
REST#
-http-config=REST Plugin Conf File Options
| Option | Type | Default | Description |
|---|---|---|---|
| endpoint | string | 0.0.0.0:9191 | Address of the HTTP server |
| read-timeout | time.Duration | 0 | Maximum amount of time (in nanoseconds) for reading the entire request, including the body. Read-timeout does not let handlers make per-request decisions on each request body’s acceptable deadline or upload rate. Therefore most users will prefer to use read-header-timeout. It is valid to use both. |
| read-header-timeout | time.Duration | 0 | Maximum amount of time (in nanoseconds) to read request headers. The connection’s read deadline is reset after reading the headers and the Handler can decide what is considered too slow for the body. |
| write-timeout | time.Duration | 0 | Maximum amount of time (in nanoseconds) before timing out writes to a response. It is reset whenever a new request’s header is read. It does not let Handlers make decisions on a per-request basis. |
| idle-timeout | time.Duration | 0 | Maximum amount of time (in nanoseconds) to wait for the next request when keepalives are enabled. If the idle timeout is zero, the value of read-timeout is used. If both are zero, there is no timeout. |
| max-header-bytes | int | 0 | Maximum number of bytes the server will read parsing the request header’s keys and values, including the request line. It does not limit the size of the request body. |
| enable-token-auth | bool | false | Enables or disables HTTP token authentication |
| users | Registers additional users with permissions. Admin with full access to every permission group is registered automatically. Password must be in hashed form. See users format example below. |
||
| password-hash-cost | int | 7 | Number in range 4-31 used as a parameter for hashing passwords. Large numbers require more CPU time and memory to process. |
| token-expiration | time.Duration | 60000000000ns | Token expiration time in nanoseconds. Zero means no expiration time |
| token-signature | string | string value used as key to sign a tokens |
User format example:
users:
- name: <name>
password_hash: <hash>
permissions: [<group1>, <group2>, ...]
`This flag can be used to set the HTTP port:
-http-port=REST References:
Service Label#
--microservice-label=Service Label Plugin Conf File Options
| Option | Type | Default | Description |
|---|---|---|---|
| microservice-label | string | Identifies a particular instance of a VPP agent. Used to form a key prefix associated with the VPP agent’s config data contained in an etcd data store. |
Service Label References:
Supervisor#
The supervisor is an infrastructure plugin providing mechanisms to handle and manage processes and process hooks.
The conf file is split into two main categories:
- programs or processes
- hooks
Each of these may contain multiple entries so more programs or hooks can be contained in a single file.
References:
Telemetry#
--telemetry_config=Telemetry Plugin Conf File Options
| Option | Type | Default | Description |
|---|---|---|---|
| disabled | bool | false | Used to disable telemetry plugin |
| prometheus-disabled | bool | false | export to prometheus |
| polling-interval | time.Duration | 30sec | interval between VPP reads |
| skipped | string | skip some metrics collection such runtime, memory, buffers, nodes, interfaces |
Telemetry References:
VPP Interface#
-vpp-ifplugin-config=VPP Interface Plugin Conf File Options
| Option | Type | Default | Description |
|---|---|---|---|
| MTU | unit32 | 0 | Default maximum transmission unit (MTU) size. The value is used if an interface without an MTU is created. Note that the MTU in the interface configuration is preferred. |
| status-publishers | string | Enables the VPP agent to send status data back to a KV data store. etcd, redis or both are supported. |
VPP agent -h command#
Use this command to display flag, conf file name, and env variable information for all conf files.
vpp-agent -hOutput:
__
_ _____ ___ _______ ____ ____ ___ / /_
| |/ / _ \/ _ /___/ _ '/ _ '/ -_/ _ / __/ vpp-agent v3.2.0-alpha-1-g615f9fd36
|___/ .__/ .__/ \_'_/\_' /\__/_//_\__/ Wed Mar 18 17:59:27 UTC 2020 (15 days ago)
/_/ /_/ /___/ root@67748e05ef29 (go1.14 linux/amd64)
Usage of vpp-agent:
-config-dir=".": Location of the config files; can also be set via 'CONFIG_DIR' env variable.
-configurator-config="configurator.conf": Location of the "configurator" plugin config file; can also be set via "CONFIGURATOR_CONFIG" env variable.
-consul-config="consul.conf": Location of the "consul" plugin config file; can also be set via "CONSUL_CONFIG" env variable.
-etcd-config="etcd.conf": Location of the "etcd" plugin config file; can also be set via "ETCD_CONFIG" env variable.
-govpp-config="govpp.conf": Location of the "govpp" plugin config file; can also be set via "GOVPP_CONFIG" env variable.
-grpc-config="grpc.conf": Location of the "grpc" plugin config file; can also be set via "GRPC_CONFIG" env variable.
-grpc-port="": Configure "grpc" server port
-http-config="http.conf": Location of the "http" plugin config file; can also be set via "HTTP_CONFIG" env variable.
-http-port="9191": Configure "http" server port
-kafka-config="kafka.conf": Location of the "kafka" plugin config file; can also be set via "KAFKA_CONFIG" env variable.
-kvscheduler-config="kvscheduler.conf": Location of the "kvscheduler" plugin config file; can also be set via "KVSCHEDULER_CONFIG" env variable.
-linux-ifplugin-config="linux-ifplugin.conf": Location of the "linux-ifplugin" plugin config file; can also be set via "LINUX-IFPLUGIN_CONFIG" env variable.
-linux-iptablesplugin-config="linux-iptablesplugin.conf": Location of the "linux-iptablesplugin" plugin config file; can also be set via "LINUX-IPTABLESPLUGIN_CONFIG" env variable.
-linux-l3plugin-config="linux-l3plugin.conf": Location of the "linux-l3plugin" plugin config file; can also be set via "LINUX-L3PLUGIN_CONFIG" env variable.
-linux-nsplugin-config="linux-nsplugin.conf": Location of the "linux-nsplugin" plugin config file; can also be set via "LINUX-NSPLUGIN_CONFIG" env variable.
-logs-config="logs.conf": Location of the "logs" plugin config file; can also be set via "LOGS_CONFIG" env variable.
-microservice-label="vpp1": microservice label; also set via 'MICROSERVICE_LABEL' env variable.
-msgsync-config="msgsync.conf": Location of the "msgsync" plugin config file; can also be set via "MSGSYNC_CONFIG" env variable.
-orchestrator-config="orchestrator.conf": Location of the "orchestrator" plugin config file; can also be set via "ORCHESTRATOR_CONFIG" env variable.
-redis-config="redis.conf": Location of the "redis" plugin config file; can also be set via "REDIS_CONFIG" env variable.
-restpapi-config="restpapi.conf": Location of the "restpapi" plugin config file; can also be set via "RESTPAPI_CONFIG" env variable.
-telemetry-config="telemetry.conf": Location of the "telemetry" plugin config file; can also be set via "TELEMETRY_CONFIG" env variable.
-vpp-aclplugin-config="vpp-aclplugin.conf": Location of the "vpp-aclplugin" plugin config file; can also be set via "VPP-ACLPLUGIN_CONFIG" env variable.
-vpp-ifplugin-config="vpp-ifplugin.conf": Location of the "vpp-ifplugin" plugin config file; can also be set via "VPP-IFPLUGIN_CONFIG" env variable.