Using Contiv-VPP Netctl

Contiv-VPP contiv-netctl is a command line interface (CLI) for querying information about Contiv-VPP components (include contiv-vswitches) operating inside a kubernetes (k8s) cluster. This blopg covers contiv-netctl syntax, describes the available commands, and provides common examples.contiv-netctl is installed on the K8s-master host during the installation of the Contiv-VPP CNI plugin.

In order to obtain information on nodes and pods, the Contiv-Netctl communicates with the Contiv-ETCD. The ETCD provides basic information including the status of contiv pods and the nodes where they reside. For information about contiv-vswitches and including VPP CLI support, contiv-netctl communicates with the Contiv-VPP Agent. There is one contiv-vpp agent per contiv-vswitch. This agent is connected to other Contiv-VPP parts of the Contiv setup. This is illustrated in the diagram below.


Contiv-VPP Architecture highlighting Contiv-Netctl

Note: Contiv-netctl is not to be confused with kubectl. Netctl is the CLI specifically for the Contiv-VPP deployment in a cluster, while kubectl is used for the entire Kubernetes cluster.

To find out how to install Contiv-VPP using Vagrant follow this link.

Accessing the Contiv-VPP Netctl

To access the contiv-netctl CLI, you must first access the master node.

After contiv-VPP is sucessfully deployed per the instructions above, follow these steps in order to access the k8s-master node:

cd into vpp/vagrant (cd vpp/vagrant)

From this directory log into the master node by using

Robin@MacbookPro:~/vpp/vagrant vagrant ssh k8s-master)

Now your CLI should look similar to this:

Welcome to Ubuntu 16.04 LTS (GNU/Linux 4.4.0-21-generic x86_64)
  • Documentation: New release ‘18.04.2 LTS’ available. Run ‘do-release-upgrade’ to upgrade to it.

Last login: Tue Feb 26 10:56:26 2019 from vagrant@k8s-master:~$

You can now use netctl by using the following syntax:

vagrant@k8s-master:~$ contiv-netctl [operation] [node] [parameters] [flags]

where operation, node, parameters, and flags are:

  • operation: specifies the query operation to be performed on one or more vswitches in the cluster

  • node: optional, specifies the node where the query operation is to be executed. For some query operations, if node is not specified, the operation is performed on all nodes.

  • parameters: optional, specifies parameters to the query operation

  • flags: Specifies optional flags. Currently, only the -h flag is supported; when specified, help text for the specified operation(s) is printed to stdout.

The following commands are Possible: help, ipam, nodes, pods, vppcli, vppdump

In the following section you will find a more detailed review of the commands you can use.


Node Information

The command contiv-netctl nodes will output vswitch information for all nodes running in the contiv cluster. The output will be something like this:

vagrant@k8s-master:~$ contiv-netctl nodes

ID NODE-NAME VPP-IP HOST-IP START-TIME STATE BUILD-VERSION BUILD-DATE 1 k8s-master Thu Feb 14 19:57:20 2019 OK v2.1.1 Thu Jan 24 11:45:00 2019 2 k8s-worker1 Thu Feb 14 19:56:48 2019 OK v2.1.1 Thu Jan 24 11:45:00 2019 3 k8s-worker2 Thu Feb 14 19:57:11 2019 OK v2.1.1 Thu Jan 24 11:45:00 2019

  • VPP-IP: IP-address of the host used for network connectivity as well as the tunnel end-point IP addresses for inter-pod vxlan tunnels.

  • HOST-IP: The IP-address of the host the node lies on

  • START-TIME: Shows you the time when the node was first started up

  • STATE: The health of the contiv-vswitch in the node

  • BUILD-VERSION: The version of the Contiv-agent that is running on the node

  • BUILD-DATE: The date that build was released

In order to find out more about the networking of Contiv-VPP refer to this site

Pod Information

The command contiv-netctl pods will output network information of all the pods connected to the specified node. If the node has not been specified it will show the pod information for all nodes.

The output for this command will be similar to this:

vagrant@k8s-master:~$ contiv-netctl pods

k8s-master (

POD-NAME NAMESPACE POD-IP IF-IDX IF-NAME contiv-crd-nc9dw kube-system contiv-etcd-0 kube-system contiv-ksr-sfh7t kube-system contiv-ui-596557c887-kh7wk kube-system 9 tap3 contiv-vswitch-c42xh kube-system coredns-78fcdf6894-5zln4 kube-system 7 tap1 coredns-78fcdf6894-gz6mt kube-system 8 tap2 etcd-k8s-master kube-system kube-apiserver-k8s-master kube-system kube-controller-manager-k8s-master kube-system kube-proxy-c96g8 kube-system kube-scheduler-k8s-master kube-system

k8s-worker1 (

POD-NAME NAMESPACE POD-IP IF-IDX IF-NAME contiv-vswitch-kpslq kube-system kube-proxy-lrkrl kube-system

k8s-worker2 (

POD-NAME NAMESPACE POD-IP IF-IDX IF-NAME contiv-vswitch-7dgm4 kube-system kube-proxy-hswcn kube-system kubernetes-dashboard-7f6874447b-95hq2 kube-system 7 tap1

IPAM Information

IPAM stands for IP Address Management. The command contiv-netctl ipam will show you ip address information for a specified node. If you do not specify the node, the information for all nodes will be shown.

The output of this command should look similar to this:

vagrant@k8s-master:~$ contiv-netctl ipam

ID NODE-NAME VPP-IP BVI-IP POD-CIDR VPP-2-HOST-CIDR POD-CLUSTER-CIDR 1 k8s-master 2 k8s-worker1 3 k8s-worker2

  • VPP-IP: Shows the IP-Address of the pod on the contiv vswitch

  • BVI-IP: The IP-Address of the Bride-Virtual-Interface

  • POD-CIDR: The IP range the pods on this node will be in

  • VPP-2-HOST-CIDR: The IP range that connects VPP to the host stack

  • POD-CLUSTER-CIDR: The IP range the pod clusters will be in on the specified node

Executing VPP debug CLI command

The command contiv-netctl vppcli will execute the specified VPP debug CLI command on the node that has been specified.

In order to find the list of possible CLI commands use the following command: contiv-netctl vppcli k8s-master ?

One useful VPPCLI Command is contiv-netctl vppcli k8s-master sh version This command will give you the software version of the contiv vswitch.

vagrant@k8s-master:~$ contiv-netctl vppcli k8s-master sh version

"vpp v18.10-22~g13f5dcf9-dirty built by root on 4450257c4ced at Thu Jan 24 08:42:51 UTC 2019 "

Another example command is contiv-netctl vppcli k8s-master sh int addr When using this command you should get something like this:

vagrant@k8s-master:~$ contiv-netctl vppcli k8s-master sh int addr

"GigabitEthernet0/8/0 (up):
local0 (dn):
loop0 (up):
  L3 ip4 table-id 1 fib-idx 1
loop1 (up):
  L2 bridge bd-id 1 idx 1 shg 1 bvi
  L3 ip4 table-id 1 fib-idx 1
tap0 (up):
tap1 (up):
  unnumbered, use loop0
  L3 ip4 table-id 1 fib-idx 1
tap2 (up):
  unnumbered, use loop0
  L3 ip4 table-id 1 fib-idx 1
tap3 (up):
  unnumbered, use loop0
  L3 ip4 table-id 1 fib-idx 1
vxlan_tunnel0 (up):
  L2 bridge bd-id 1 idx 1 shg 1
vxlan_tunnel1 (up):
  L2 bridge bd-id 1 idx 1 shg 1


The command vppdump allows you to execute the following commands that will help with basic debugging:

vagrant@k8s-master:~$ contiv-netctl vppdump

cmd 0: linux-interface-watcher cmd 1: microservice cmd 2: linux-interface cmd 3: linux-arp cmd 4: linux-route cmd 5: vpp-acl-to-interface cmd 6: vpp-bd-interface cmd 7: vpp-interface cmd 8: vpp-acl cmd 9: vpp-arp cmd 10: vpp-bridge-domain cmd 11: vpp-dhcp cmd 12: vpp-ip-scan-neighbor cmd 13: vpp-l2-fib cmd 14: vpp-nat44-dnat cmd 15: vpp-nat44-global cmd 16: vpp-nat44-interface cmd 17: vpp-proxy-arp cmd 18: vpp-proxy-arp-interface cmd 19: vpp-punt-ip-redirect cmd 20: vpp-punt-to-host cmd 21: vpp-static-route cmd 22: vpp-stn-rules cmd 23: vpp-unnumbered-interface cmd 24: vpp-xconnect

One of the possible commands is contiv-netctl vppdump k8s-master linux-interface-watcher

This is an example of an output for this command:

vagrant@k8s-master:~$ contiv-netctl vppdump k8s-master linux-interface-watcher

[ { "Key": "linux/interface/host-name/lo", "Value": {}, "Metadata": null, "Origin": 2 }, { "Key": "linux/interface/host-name/enp0s3", "Value": {}, "Metadata": null, "Origin": 2 }, { "Key": "linux/interface/host-name/enp0s9", "Value": {}, "Metadata": null, "Origin": 2 }, { "Key": "linux/interface/host-name/docker0", "Value": {}, "Metadata": null, "Origin": 2 }, { "Key": "linux/interface/host-name/vpp1", "Value": {}, "Metadata": null, "Origin": 2 } ]

As outputs of this and other vppdump commands are provided in VPP “CLI-ese” or JSON formats, it is beneficial to possess in-depth knowledge of VPP, kubernetes clusters and how Contiv-VPP works. Because of this and a unwritten rule of confining blog posts to a maximum 5-minute read, I did not include detailed explanations of all outputs.

About the Author

Robin is a German student who spent some time as an intern with the Contiv-VPP team at Cisco in San Jose. While casually using Contiv-VPP like any other normal person does, it one day struck him - There must be a CLI for Contiv-VPP! He began to dive deeper into this topic and the result was this blog.

You can reach Robin at

Back to blog