1 OpFlex agent-ovs User Guide
2 ===========================
7 agent-ovs is a policy agent that works with OVS to enforce a group-based
8 policy networking model with locally attached virtual machines or
9 containers. The policy agent is designed to work well with orchestration
15 The agent configuration is handled using its config file which is by
16 default found at "/etc/opflex-agent-ovs/opflex-agent-ovs.conf"
18 Here is an example configuration file that documents the available
24 // Logging configuration
29 // Configuration related to the OpFlex protocol
31 // The policy domain for this agent.
32 "domain": "openstack",
34 // The unique name in the policy domain for this agent.
35 "name": "example-agent",
37 // a list of peers to connect to, by hostname and port. One
38 // peer, or an anycast pseudo-peer, is sufficient to bootstrap
39 // the connection without needing an exhaustive list of all
43 {"hostname": "10.0.0.30", "port": 8009}
47 // SSL mode. Possible values:
48 // disabled: communicate without encryption
49 // encrypted: encrypt but do not verify peers
50 // secure: encrypt and verify peer certificates
53 // The path to a directory containing trusted certificate
54 // authority public certificates, or a file containing a
55 // specific CA certificate.
56 "ca-store": "/etc/ssl/certs/"
60 // Enable the MODB inspector service, which allows
61 // inspecting the state of the managed object database.
65 // Listen on the specified socket for the inspector
66 // Default /var/run/opflex-agent-ovs-inspect.sock
67 "socket-name": "/var/run/opflex-agent-ovs-inspect.sock"
71 // Endpoint sources provide metadata about local endpoints
73 // Filesystem path to monitor for endpoint information
74 "filesystem": ["/var/lib/opflex-agent-ovs/endpoints"]
77 // Renderers enforce policy obtained via OpFlex.
79 // Stitched-mode renderer for interoperating with a
80 // hardware fabric such as ACI
83 "ovs-bridge-name": "br0",
85 // Set encapsulation type. Must set either vxlan or vlan.
87 // Encapsulate traffic with VXLAN.
89 // The name of the tunnel interface in OVS
90 "encap-iface": "br0_vxlan0",
92 // The name of the interface whose IP should be used
93 // as the source IP in encapsulated traffic.
94 "uplink-iface": "eth0.4093",
96 // The vlan tag, if any, used on the uplink interface.
97 // Set to zero or omit if the uplink is untagged.
100 // The IP address used for the destination IP in
101 // the encapsulated traffic. This should be an
102 // anycast IP address understood by the upstream
103 // stiched-mode fabric.
104 "remote-ip": "10.0.0.32",
106 // UDP port number of the encapsulated traffic.
110 // Encapsulate traffic with a locally-significant VLAN
114 // // The name of the uplink interface in OVS
115 // "encap-iface": "team0"
119 // Configure forwarding policy
121 // Configure the virtual distributed router
123 // Enable virtual distributed router. Set to true
124 // to enable or false to disable. Default true.
127 // Override MAC address for virtual router.
128 // Default is "00:22:bd:f8:19:ff"
129 "mac": "00:22:bd:f8:19:ff",
131 // Configure IPv6-related settings for the virtual
134 // Send router advertisement messages in
135 // response to router solicitation requests as
136 // well as unsolicited advertisements. This
137 // is not required in stitched mode since the
138 // hardware router will send them.
139 "router-advertisement": true
143 // Configure virtual distributed DHCP server
145 // Enable virtual distributed DHCP server. Set to
146 // true to enable or false to disable. Default
150 // Override MAC address for virtual dhcp server.
151 // Default is "00:22:bd:f8:19:ff"
152 "mac": "00:22:bd:f8:19:ff"
155 "endpoint-advertisements": {
156 // Enable generation of periodic ARP/NDP
157 // advertisements for endpoints. Default true.
162 // Location to store cached IDs for managing flow state
163 "flowid-cache-dir": "/var/lib/opflex-agent-ovs/ids"
168 Endpoint Registration
169 ---------------------
171 The agent learns about endpoints using endpoint metadata files located
172 by default in "/var/lib/opflex-agent-ovs/endpoints".
174 These are JSON-format files such as the (unusually complex) example
180 "uuid": "83f18f0b-80f7-46e2-b06c-4d9487b0c754",
181 "policy-space-name": "test",
182 "endpoint-group-name": "group1",
183 "interface-name": "veth0",
185 "10.0.0.1", "fd8f:69d8:c12c:ca62::1"
190 "routers": ["10.200.44.1"],
191 "dns-servers": ["8.8.8.8", "8.8.4.4"],
192 "domain": "example.com",
195 "dest": "169.254.169.0",
197 "next-hop": "10.0.0.1"
202 "dns-servers": ["2001:4860:4860::8888", "2001:4860:4860::8844"],
203 "search-list": ["test1.example.com", "example.com"]
205 "ip-address-mapping": [
207 "uuid": "91c5b217-d244-432c-922d-533c6c036ab4",
208 "floating-ip": "5.5.5.1",
209 "mapped-ip": "10.0.0.1",
210 "policy-space-name": "common",
211 "endpoint-group-name": "nat-epg"
214 "uuid": "22bfdc01-a390-4b6f-9b10-624d4ccb957b",
215 "floating-ip": "fdf1:9f86:d1af:6cc9::1",
216 "mapped-ip": "fd8f:69d8:c12c:ca62::1",
217 "policy-space-name": "common",
218 "endpoint-group-name": "nat-epg"
221 "mac": "00:00:00:00:00:01",
222 "promiscuous-mode": false
225 The possible parameters for these files are:
228 A globally unique ID for the endpoint
230 **endpoint-group-name**
231 The name of the endpoint group for the endpoint
233 **policy-space-name**
234 The name of the policy space for the endpoint group.
237 The name of the OVS interface to which the endpoint is attached
240 A list of strings contains either IPv4 or IPv6 addresses that the
241 endpoint is allowed to use
244 The MAC address for the endpoint’s interface.
247 Allow traffic from this VM to bypass default port security
250 A distributed DHCPv4 configuration block (see below)
253 A distributed DHCPv6 configuration block (see below)
255 **ip-address-mapping**
256 A list of IP address mapping configuration blocks (see below)
258 DHCPv4 configuration blocks can contain the following parameters:
261 the IP address to return with DHCP. Must be one of the configured
265 the subnet prefix length
268 a list of default gateways for the endpoint
271 a list of DNS server addresses
274 The domain name parameter to send in the DHCP reply
277 A list of static route configuration blocks, which contains a
278 "dest", "dest-prefix", and "next-hop" parameters to send as static
279 routes to the end host
281 DHCPv6 configuration blocks can contain the following parameters:
284 A list of DNS servers for the endpoint
287 The DNS search path for the endpoint
289 IP address mapping configuration blocks can contain the following
293 a globally unique ID for the virtual endpoint created by the
297 Map using DNAT to this floating IPv4 or IPv6 address
300 the source IPv4 or IPv6 address; must be one of the IPs assigned to
303 **endpoint-group-name**
304 The name of the endpoint group for the NATed IP
306 **policy-space-name**
307 The name of the policy space for the NATed IP
312 The Opflex inspector is a useful command-line tool that will allow you
313 to inspect the state of the managed object database for the agent for
314 debugging and diagnosis purposes.
316 The command is called "gbp\_inspect" and takes the following arguments:
321 Usage: ./gbp_inspect [options]
323 -h [ --help ] Print this help message
324 --log arg Log to the specified file (default
326 --level arg (=warning) Use the specified log level (default
328 --syslog Log to syslog instead of file or
330 --socket arg (=/usr/local/var/run/opflex-agent-ovs-inspect.sock)
331 Connect to the specified UNIX domain
332 socket (default /usr/local/var/run/opfl
333 ex-agent-ovs-inspect.sock)
334 -q [ --query ] arg Query for a specific object with
335 subjectname,uri or all objects of a
336 specific type with subjectname
337 -r [ --recursive ] Retrieve the whole subtree for each
339 -f [ --follow-refs ] Follow references in returned objects
340 --load arg Load managed objects from the specified
341 file into the MODB view
342 -o [ --output ] arg Output the results to the specified
343 file (default standard out)
344 -t [ --type ] arg (=tree) Specify the output format: tree, list,
345 or dump (default tree)
346 -p [ --props ] Include object properties in output
348 Here are some examples of the ways to use this tool.
350 You can get information about the running system using one or more
351 queries, which consist of an object model class name and optionally the
352 URI of a specific object. The simplest query is to get a single object,
357 # gbp_inspect -q DmtreeRoot
359 # gbp_inspect -q GbpEpGroup
360 --* GbpEpGroup,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/
361 --* GbpEpGroup,/PolicyUniverse/PolicySpace/test/GbpEpGroup/group1/
362 # gbp_inspect -q GbpEpGroup,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/
363 --* GbpEpGroup,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/
365 You can also display all the properties for each object:
369 # gbp_inspect -p -q GbpeL24Classifier
370 --* GbpeL24Classifier,/PolicyUniverse/PolicySpace/test/GbpeL24Classifier/classifier4/
372 connectionTracking : 1 (reflexive)
379 --* GbpeL24Classifier,/PolicyUniverse/PolicySpace/test/GbpeL24Classifier/classifier3/
381 etherT : 34525 (ipv6)
386 --* GbpeL24Classifier,/PolicyUniverse/PolicySpace/test/GbpeL24Classifier/classifier2/
394 You can also request to get the all the children of an object you query
399 # gbp_inspect -r -q GbpEpGroup,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/
400 --* GbpEpGroup,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/
401 |-* GbpeInstContext,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/GbpeInstContext/
402 `-* GbpEpGroupToNetworkRSrc,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/GbpEpGroupToNetworkRSrc/
404 You can also follow references found in any object downloads:
408 # gbp_inspect -fr -q GbpEpGroup,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/
409 --* GbpEpGroup,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/
410 |-* GbpeInstContext,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/GbpeInstContext/
411 `-* GbpEpGroupToNetworkRSrc,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/GbpEpGroupToNetworkRSrc/
412 --* GbpFloodDomain,/PolicyUniverse/PolicySpace/common/GbpFloodDomain/fd_ext/
413 `-* GbpFloodDomainToNetworkRSrc,/PolicyUniverse/PolicySpace/common/GbpFloodDomain/fd_ext/GbpFloodDomainToNetworkRSrc/
414 --* GbpBridgeDomain,/PolicyUniverse/PolicySpace/common/GbpBridgeDomain/bd_ext/
415 `-* GbpBridgeDomainToNetworkRSrc,/PolicyUniverse/PolicySpace/common/GbpBridgeDomain/bd_ext/GbpBridgeDomainToNetworkRSrc/
416 --* GbpRoutingDomain,/PolicyUniverse/PolicySpace/common/GbpRoutingDomain/rd_ext/
417 |-* GbpRoutingDomainToIntSubnetsRSrc,/PolicyUniverse/PolicySpace/common/GbpRoutingDomain/rd_ext/GbpRoutingDomainToIntSubnetsRSrc/122/%2fPolicyUniverse%2fPolicySpace%2fcommon%2fGbpSubnets%2fsubnets_ext%2f/
418 `-* GbpForwardingBehavioralGroupToSubnetsRSrc,/PolicyUniverse/PolicySpace/common/GbpRoutingDomain/rd_ext/GbpForwardingBehavioralGroupToSubnetsRSrc/
419 --* GbpSubnets,/PolicyUniverse/PolicySpace/common/GbpSubnets/subnets_ext/
420 |-* GbpSubnet,/PolicyUniverse/PolicySpace/common/GbpSubnets/subnets_ext/GbpSubnet/subnet_ext4/
421 `-* GbpSubnet,/PolicyUniverse/PolicySpace/common/GbpSubnets/subnets_ext/GbpSubnet/subnet_ext6/