1 .. _opflex-agent-ovs-user-guide:
3 OpFlex agent-ovs User Guide
4 ===========================
9 agent-ovs is a policy agent that works with OVS to enforce a group-based
10 policy networking model with locally attached virtual machines or
11 containers. The policy agent is designed to work well with orchestration
17 The agent configuration is handled using its config file which is by
18 default found at "/etc/opflex-agent-ovs/opflex-agent-ovs.conf"
20 Here is an example configuration file that documents the available
26 // Logging configuration
28 // // Set the log level.
29 // // Possible values in descending order of verbosity:
30 // // "debug7"-"debug0", "debug" (synonym for "debug0"),
31 // // "info", "warning", "error", "fatal"
36 // Configuration related to the OpFlex protocol
38 // The policy domain for this agent.
39 "domain": "openstack",
41 // The unique name in the policy domain for this agent.
42 "name": "example-agent",
44 // a list of peers to connect to, by hostname and port. One
45 // peer, or an anycast pseudo-peer, is sufficient to bootstrap
46 // the connection without needing an exhaustive list of all
50 // {"hostname": "10.0.0.30", "port": 8009}
54 // SSL mode. Possible values:
55 // disabled: communicate without encryption (default)
56 // encrypted: encrypt but do not verify peers
57 // secure: encrypt and verify peer certificates
60 // The path to a directory containing trusted certificate
61 // authority public certificates, or a file containing a
62 // specific CA certificate.
63 // Default: "/etc/ssl/certs"
64 "ca-store": "/etc/ssl/certs"
68 // Enable the MODB inspector service, which allows
69 // inspecting the state of the managed object database.
73 // Listen on the specified socket for the inspector
74 // Default: "/var/run/opflex-agent-ovs-inspect.sock"
75 "socket-name": "/var/run/opflex-agent-ovs-inspect.sock"
79 // Enable the agent notification service, which sends
80 // notifications to interested listeners over a UNIX
85 // Listen on the specified socket for the inspector
86 // Default: "/var/run/opflex-agent-ovs-notif.sock"
87 "socket-name": "/var/run/opflex-agent-ovs-notif.sock",
89 // Set the socket owner user after binding if the user
91 // Default: do not set the owner
92 // "socket-owner": "root",
94 // Set the socket group after binding if the group name
96 // Default: do not set the group
97 "socket-group": "opflexep",
99 // Set the socket permissions after binding to the
100 // specified octal permissions mask
101 // Default: do not set the permissions
102 "socket-permissions": "770"
106 // Endpoint sources provide metadata about local endpoints
107 "endpoint-sources": {
108 // Filesystem path to monitor for endpoint information
109 // Default: no endpoint sources
110 "filesystem": ["/var/lib/opflex-agent-ovs/endpoints"]
113 // Service sources provide metadata about services that can
114 // provide functionality for local endpoints
116 // Filesystem path to monitor for service information
117 // Default: no service sources
118 "filesystem": ["/var/lib/opflex-agent-ovs/services"]
121 // Renderers enforce policy obtained via OpFlex.
122 // Default: no renderers
124 // Stitched-mode renderer for interoperating with a
125 // hardware fabric such as ACI
128 // "Integration" bridge used to enforce contracts and forward
130 "int-bridge-name": "br-int",
132 // "Access" bridge used to enforce access control and enforce
134 "access-bridge-name": "br-access",
136 // Set encapsulation type. Must set either vxlan or vlan.
138 // Encapsulate traffic with VXLAN.
140 // The name of the tunnel interface in OVS
141 "encap-iface": "br0_vxlan0",
143 // The name of the interface whose IP should be used
144 // as the source IP in encapsulated traffic.
145 "uplink-iface": "team0.4093",
147 // The vlan tag, if any, used on the uplink interface.
148 // Set to zero or omit if the uplink is untagged.
151 // The IP address used for the destination IP in
152 // the encapsulated traffic. This should be an
153 // anycast IP address understood by the upstream
154 // stiched-mode fabric.
155 "remote-ip": "10.0.0.32",
157 // UDP port number of the encapsulated traffic.
161 // Encapsulate traffic with a locally-significant VLAN
165 // // The name of the uplink interface in OVS
166 // "encap-iface": "team0"
170 // Configure forwarding policy
172 // Configure the virtual distributed router
174 // Enable virtual distributed router. Set to true
175 // to enable or false to disable.
179 // Override MAC address for virtual router.
180 // Default: "00:22:bd:f8:19:ff"
181 "mac": "00:22:bd:f8:19:ff",
183 // Configure IPv6-related settings for the virtual
186 // Send router advertisement messages in
187 // response to router solicitation requests as
188 // well as unsolicited advertisements. This
189 // is not required in stitched mode since the
190 // hardware router will send them.
191 "router-advertisement": false
195 // Configure virtual distributed DHCP server
197 // Enable virtual distributed DHCP server. Set to
198 // true to enable or false to disable.
202 // Override MAC address for virtual dhcp server.
203 // Default: "00:22:bd:f8:19:ff"
204 "mac": "00:22:bd:f8:19:ff"
207 "endpoint-advertisements": {
208 // Set mode for generation of periodic ARP/NDP
209 // advertisements for endpoints. Possible values:
210 // disabled: Do not send advertisements
211 // gratuitous-unicast: Send gratuitous endpoint
212 // advertisements as unicast packets to the router
214 // gratuitous-broadcast: Send gratuitous endpoint
215 // advertisements as broadcast packets.
216 // router-request: Unicast a spoofed request/solicitation
217 // for the subnet's gateway router.
218 // Default: router-request.
219 "mode": "gratuitous-broadcast"
223 // Location to store cached IDs for managing flow state
224 // Default: "/var/lib/opflex-agent-ovs/ids"
225 "flowid-cache-dir": "/var/lib/opflex-agent-ovs/ids",
227 // Location to write multicast groups for the mcast-daemon
228 // Default: "/var/lib/opflex-agent-ovs/mcast/opflex-groups.json"
229 "mcast-group-file": "/var/lib/opflex-agent-ovs/mcast/opflex-groups.json"
234 Endpoint Registration
235 ---------------------
237 The agent learns about endpoints using endpoint metadata files located
238 by default in "/var/lib/opflex-agent-ovs/endpoints".
240 These are JSON-format files such as the (unusually complex) example
246 "uuid": "83f18f0b-80f7-46e2-b06c-4d9487b0c754",
247 "policy-space-name": "test",
248 "endpoint-group-name": "group1",
249 "interface-name": "veth0",
251 "10.0.0.1", "fd8f:69d8:c12c:ca62::1"
256 "routers": ["10.200.44.1"],
257 "dns-servers": ["8.8.8.8", "8.8.4.4"],
258 "domain": "example.com",
261 "dest": "169.254.169.0",
263 "next-hop": "10.0.0.1"
268 "dns-servers": ["2001:4860:4860::8888", "2001:4860:4860::8844"],
269 "search-list": ["test1.example.com", "example.com"]
271 "ip-address-mapping": [
273 "uuid": "91c5b217-d244-432c-922d-533c6c036ab4",
274 "floating-ip": "5.5.5.1",
275 "mapped-ip": "10.0.0.1",
276 "policy-space-name": "common",
277 "endpoint-group-name": "nat-epg"
280 "uuid": "22bfdc01-a390-4b6f-9b10-624d4ccb957b",
281 "floating-ip": "fdf1:9f86:d1af:6cc9::1",
282 "mapped-ip": "fd8f:69d8:c12c:ca62::1",
283 "policy-space-name": "common",
284 "endpoint-group-name": "nat-epg"
287 "mac": "00:00:00:00:00:01",
288 "promiscuous-mode": false
291 The possible parameters for these files are:
294 A globally unique ID for the endpoint
296 **endpoint-group-name**
297 The name of the endpoint group for the endpoint
299 **policy-space-name**
300 The name of the policy space for the endpoint group.
303 The name of the OVS interface to which the endpoint is attached
306 A list of strings contains either IPv4 or IPv6 addresses that the
307 endpoint is allowed to use
310 The MAC address for the endpoint’s interface.
313 Allow traffic from this VM to bypass default port security
316 A distributed DHCPv4 configuration block (see below)
319 A distributed DHCPv6 configuration block (see below)
321 **ip-address-mapping**
322 A list of IP address mapping configuration blocks (see below)
324 DHCPv4 configuration blocks can contain the following parameters:
327 the IP address to return with DHCP. Must be one of the configured
331 the subnet prefix length
334 a list of default gateways for the endpoint
337 a list of DNS server addresses
340 The domain name parameter to send in the DHCP reply
343 A list of static route configuration blocks, which contains a
344 "dest", "dest-prefix", and "next-hop" parameters to send as static
345 routes to the end host
347 DHCPv6 configuration blocks can contain the following parameters:
350 A list of DNS servers for the endpoint
353 The DNS search path for the endpoint
355 IP address mapping configuration blocks can contain the following
359 a globally unique ID for the virtual endpoint created by the
363 Map using DNAT to this floating IPv4 or IPv6 address
366 the source IPv4 or IPv6 address; must be one of the IPs assigned to
369 **endpoint-group-name**
370 The name of the endpoint group for the NATed IP
372 **policy-space-name**
373 The name of the policy space for the NATed IP
378 The Opflex inspector is a useful command-line tool that will allow you
379 to inspect the state of the managed object database for the agent for
380 debugging and diagnosis purposes.
382 The command is called "gbp\_inspect" and takes the following arguments:
387 Usage: gbp_inspect [options]
389 -h [ --help ] Print this help message
390 --log arg Log to the specified file (default
392 --level arg (=warning) Use the specified log level (default
394 --syslog Log to syslog instead of file or
396 --socket arg (=/usr/var/run/opflex-agent-ovs-inspect.sock)
397 Connect to the specified UNIX domain
398 socket (default /usr/var/run/opfl
399 ex-agent-ovs-inspect.sock)
400 -q [ --query ] arg Query for a specific object with
401 subjectname,uri or all objects of a
402 specific type with subjectname
403 -r [ --recursive ] Retrieve the whole subtree for each
405 -f [ --follow-refs ] Follow references in returned objects
406 --load arg Load managed objects from the specified
407 file into the MODB view
408 -o [ --output ] arg Output the results to the specified
409 file (default standard out)
410 -t [ --type ] arg (=tree) Specify the output format: tree,
411 asciitree, list, or dump (default tree)
412 -p [ --props ] Include object properties in output
414 Here are some examples of the ways to use this tool.
416 You can get information about the running system using one or more
417 queries, which consist of an object model class name and optionally the
418 URI of a specific object. The simplest query is to get a single object,
423 # gbp_inspect -q DmtreeRoot
425 # gbp_inspect -q GbpEpGroup
426 ───⦁ GbpEpGroup,/PolicyUniverse/PolicySpace/test/GbpEpGroup/group1/
427 ───⦁ GbpEpGroup,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/
428 # gbp_inspect -q GbpEpGroup,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/
429 ───⦁ GbpEpGroup,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/
431 You can also display all the properties for each object:
435 # gbp_inspect -p -q GbpeL24Classifier
436 ───⦁ GbpeL24Classifier,/PolicyUniverse/PolicySpace/test/GbpeL24Classifier/classifier4/
438 connectionTracking : 1 (reflexive)
445 ───⦁ GbpeL24Classifier,/PolicyUniverse/PolicySpace/test/GbpeL24Classifier/classifier3/
447 etherT : 34525 (ipv6)
452 ───⦁ GbpeL24Classifier,/PolicyUniverse/PolicySpace/test/GbpeL24Classifier/classifier1/
458 ───⦁ GbpeL24Classifier,/PolicyUniverse/PolicySpace/test/GbpeL24Classifier/classifier2/
466 You can also request to get the all the children of an object you query
471 # gbp_inspect -r -q GbpEpGroup,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/
472 ──┬⦁ GbpEpGroup,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/
473 ├──⦁ GbpeInstContext,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/GbpeInstContext/
474 ╰──⦁ GbpEpGroupToNetworkRSrc,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/GbpEpGroupToNetworkRSrc/
476 You can also follow references found in any object downloads:
480 # gbp_inspect -fr -q GbpEpGroup,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/
481 ──┬⦁ GbpEpGroup,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/
482 ├──⦁ GbpeInstContext,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/GbpeInstContext/
483 ╰──⦁ GbpEpGroupToNetworkRSrc,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/GbpEpGroupToNetworkRSrc/
484 ──┬⦁ GbpBridgeDomain,/PolicyUniverse/PolicySpace/common/GbpBridgeDomain/bd_ext/
485 ╰──⦁ GbpBridgeDomainToNetworkRSrc,/PolicyUniverse/PolicySpace/common/GbpBridgeDomain/bd_ext/GbpBridgeDomainToNetworkRSrc/
486 ──┬⦁ GbpFloodDomain,/PolicyUniverse/PolicySpace/common/GbpFloodDomain/fd_ext/
487 ╰──⦁ GbpFloodDomainToNetworkRSrc,/PolicyUniverse/PolicySpace/common/GbpFloodDomain/fd_ext/GbpFloodDomainToNetworkRSrc/
488 ──┬⦁ GbpRoutingDomain,/PolicyUniverse/PolicySpace/common/GbpRoutingDomain/rd_ext/
489 ├──⦁ GbpRoutingDomainToIntSubnetsRSrc,/PolicyUniverse/PolicySpace/common/GbpRoutingDomain/rd_ext/GbpRoutingDomainToIntSubnetsRSrc/152/%2fPolicyUniverse%2fPolicySpace%2fcommon%2fGbpSubnets%2fsubnets_ext%2f/
490 ╰──⦁ GbpForwardingBehavioralGroupToSubnetsRSrc,/PolicyUniverse/PolicySpace/common/GbpRoutingDomain/rd_ext/GbpForwardingBehavioralGroupToSubnetsRSrc/
491 ──┬⦁ GbpSubnets,/PolicyUniverse/PolicySpace/common/GbpSubnets/subnets_ext/
492 ├──⦁ GbpSubnet,/PolicyUniverse/PolicySpace/common/GbpSubnets/subnets_ext/GbpSubnet/subnet_ext4/
493 ╰──⦁ GbpSubnet,/PolicyUniverse/PolicySpace/common/GbpSubnets/subnets_ext/GbpSubnet/subnet_ext6/