docs/user-guide/opflex-agent-ovs-user-guide.rst

   1 .. _opflex-agent-ovs-user-guide:
   2
   3 OpFlex agent-ovs User Guide
   4 ===========================
   5
   6 Introduction
   7 ------------
   8
   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
  12 tools like OpenStack.
  13
  14 Agent Configuration
  15 -------------------
  16
  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"
  19
  20 Here is an example configuration file that documents the available
  21 options:
  22
  23 ::
  24
  25     {
  26         // Logging configuration
  27         // "log": {
  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"
  32         //     // Default: "info"
  33         //     "level": "info"
  34         // },
  35
  36         // Configuration related to the OpFlex protocol
  37         "opflex": {
  38             // The policy domain for this agent.
  39             "domain": "openstack",
  40
  41             // The unique name in the policy domain for this agent.
  42             "name": "example-agent",
  43
  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
  47             // peers.
  48             "peers": [
  49                 // EXAMPLE:
  50                 // {"hostname": "10.0.0.30", "port": 8009}
  51             ],
  52
  53             "ssl": {
  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
  58                 "mode": "encrypted",
  59
  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"
  65             },
  66
  67             "inspector": {
  68                 // Enable the MODB inspector service, which allows
  69                 // inspecting the state of the managed object database.
  70                 // Default: true
  71                 "enabled": true,
  72
  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"
  76             },
  77
  78             "notif": {
  79                 // Enable the agent notification service, which sends
  80                 // notifications to interested listeners over a UNIX
  81                 // socket.
  82                 // Default: true
  83                 "enabled": true,
  84
  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",
  88
  89                 // Set the socket owner user after binding if the user
  90                 // exists
  91                 // Default: do not set the owner
  92                 // "socket-owner": "root",
  93
  94                 // Set the socket group after binding if the group name
  95                 // exists
  96                 // Default: do not set the group
  97                 "socket-group": "opflexep",
  98
  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"
 103             }
 104         },
 105
 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"]
 111         },
 112
 113         // Service sources provide metadata about services that can
 114         // provide functionality for local endpoints
 115         "service-sources": {
 116             // Filesystem path to monitor for service information
 117             // Default: no service sources
 118             "filesystem": ["/var/lib/opflex-agent-ovs/services"]
 119         },
 120
 121         // Renderers enforce policy obtained via OpFlex.
 122         // Default: no renderers
 123         "renderers": {
 124             // Stitched-mode renderer for interoperating with a
 125             // hardware fabric such as ACI
 126             // EXAMPLE:
 127             "stitched-mode": {
 128                 // "Integration" bridge used to enforce contracts and forward
 129                 // packets
 130                 "int-bridge-name": "br-int",
 131
 132                 // "Access" bridge used to enforce access control and enforce
 133                 // security groups.
 134                 "access-bridge-name": "br-access",
 135
 136                 // Set encapsulation type.  Must set either vxlan or vlan.
 137                 "encap": {
 138                     // Encapsulate traffic with VXLAN.
 139                     "vxlan" : {
 140                         // The name of the tunnel interface in OVS
 141                         "encap-iface": "br0_vxlan0",
 142
 143                         // The name of the interface whose IP should be used
 144                         // as the source IP in encapsulated traffic.
 145                         "uplink-iface": "team0.4093",
 146
 147                         // The vlan tag, if any, used on the uplink interface.
 148                         // Set to zero or omit if the uplink is untagged.
 149                         "uplink-vlan": 4093,
 150
 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",
 156
 157                         // UDP port number of the encapsulated traffic.
 158                         "remote-port": 8472
 159                     }
 160
 161                     // Encapsulate traffic with a locally-significant VLAN
 162                     // tag
 163                     // EXAMPLE:
 164                     // "vlan" : {
 165                     //     // The name of the uplink interface in OVS
 166                     //     "encap-iface": "team0"
 167                     // }
 168                 },
 169
 170                 // Configure forwarding policy
 171                 "forwarding": {
 172                     // Configure the virtual distributed router
 173                     "virtual-router": {
 174                         // Enable virtual distributed router.  Set to true
 175                         // to enable or false to disable.
 176                         // Default: true.
 177                         "enabled": true,
 178
 179                         // Override MAC address for virtual router.
 180                         // Default: "00:22:bd:f8:19:ff"
 181                         "mac": "00:22:bd:f8:19:ff",
 182
 183                         // Configure IPv6-related settings for the virtual
 184                         // router
 185                         "ipv6" : {
 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
 192                         }
 193                     },
 194
 195                     // Configure virtual distributed DHCP server
 196                     "virtual-dhcp": {
 197                         // Enable virtual distributed DHCP server.  Set to
 198                         // true to enable or false to disable.
 199                         // Default: true
 200                         "enabled": true,
 201
 202                         // Override MAC address for virtual dhcp server.
 203                         // Default: "00:22:bd:f8:19:ff"
 204                         "mac": "00:22:bd:f8:19:ff"
 205                     },
 206
 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
 213                         //   mac.
 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"
 220                     }
 221                 },
 222
 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",
 226
 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"
 230             }
 231         }
 232     }
 233
 234 Endpoint Registration
 235 ---------------------
 236
 237 The agent learns about endpoints using endpoint metadata files located
 238 by default in "/var/lib/opflex-agent-ovs/endpoints".
 239
 240 These are JSON-format files such as the (unusually complex) example
 241 below:
 242
 243 ::
 244
 245     {
 246         "uuid": "83f18f0b-80f7-46e2-b06c-4d9487b0c754",
 247         "policy-space-name": "test",
 248         "endpoint-group-name": "group1",
 249         "interface-name": "veth0",
 250         "ip": [
 251             "10.0.0.1", "fd8f:69d8:c12c:ca62::1"
 252         ],
 253         "dhcp4": {
 254             "ip": "10.200.44.2",
 255             "prefix-len": 24,
 256             "routers": ["10.200.44.1"],
 257             "dns-servers": ["8.8.8.8", "8.8.4.4"],
 258             "domain": "example.com",
 259             "static-routes": [
 260                 {
 261                     "dest": "169.254.169.0",
 262                     "dest-prefix": 24,
 263                     "next-hop": "10.0.0.1"
 264                 }
 265             ]
 266         },
 267         "dhcp6": {
 268             "dns-servers": ["2001:4860:4860::8888", "2001:4860:4860::8844"],
 269             "search-list": ["test1.example.com", "example.com"]
 270         },
 271         "ip-address-mapping": [
 272             {
 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"
 278             },
 279             {
 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"
 285             }
 286         ],
 287         "mac": "00:00:00:00:00:01",
 288         "promiscuous-mode": false
 289     }
 290
 291 The possible parameters for these files are:
 292
 293 **uuid**
 294     A globally unique ID for the endpoint
 295
 296 **endpoint-group-name**
 297     The name of the endpoint group for the endpoint
 298
 299 **policy-space-name**
 300     The name of the policy space for the endpoint group.
 301
 302 **interface-name**
 303     The name of the OVS interface to which the endpoint is attached
 304
 305 **ip**
 306     A list of strings contains either IPv4 or IPv6 addresses that the
 307     endpoint is allowed to use
 308
 309 **mac**
 310     The MAC address for the endpoint’s interface.
 311
 312 **promiscuous-mode**
 313     Allow traffic from this VM to bypass default port security
 314
 315 **dhcp4**
 316     A distributed DHCPv4 configuration block (see below)
 317
 318 **dhcp6**
 319     A distributed DHCPv6 configuration block (see below)
 320
 321 **ip-address-mapping**
 322     A list of IP address mapping configuration blocks (see below)
 323
 324 DHCPv4 configuration blocks can contain the following parameters:
 325
 326 **ip**
 327     the IP address to return with DHCP. Must be one of the configured
 328     IPv4 addresses.
 329
 330 **prefix**
 331     the subnet prefix length
 332
 333 **routers**
 334     a list of default gateways for the endpoint
 335
 336 **dns**
 337     a list of DNS server addresses
 338
 339 **domain**
 340     The domain name parameter to send in the DHCP reply
 341
 342 **static-routes**
 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
 346
 347 DHCPv6 configuration blocks can contain the following parameters:
 348
 349 **dns**
 350     A list of DNS servers for the endpoint
 351
 352 **search-patch**
 353     The DNS search path for the endpoint
 354
 355 IP address mapping configuration blocks can contain the following
 356 parameters:
 357
 358 **uuid**
 359     a globally unique ID for the virtual endpoint created by the
 360     mapping.
 361
 362 **floating-ip**
 363     Map using DNAT to this floating IPv4 or IPv6 address
 364
 365 **mapped-ip**
 366     the source IPv4 or IPv6 address; must be one of the IPs assigned to
 367     the endpoint.
 368
 369 **endpoint-group-name**
 370     The name of the endpoint group for the NATed IP
 371
 372 **policy-space-name**
 373     The name of the policy space for the NATed IP
 374
 375 Inspector
 376 ---------
 377
 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.
 381
 382 The command is called "gbp\_inspect" and takes the following arguments:
 383
 384 ::
 385
 386     # gbp_inspect -h
 387     Usage: gbp_inspect [options]
 388     Allowed options:
 389       -h [ --help ]                         Print this help message
 390       --log arg                             Log to the specified file (default
 391                                             standard out)
 392       --level arg (=warning)                Use the specified log level (default
 393                                             warning)
 394       --syslog                              Log to syslog instead of file or
 395                                             standard out
 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
 404                                             returned object
 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
 413
 414 Here are some examples of the ways to use this tool.
 415
 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,
 419 nonrecursively:
 420
 421 ::
 422
 423     # gbp_inspect -q DmtreeRoot
 424     ───⦁ 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/
 430
 431 You can also display all the properties for each object:
 432
 433 ::
 434
 435     # gbp_inspect -p -q GbpeL24Classifier
 436     ───⦁ GbpeL24Classifier,/PolicyUniverse/PolicySpace/test/GbpeL24Classifier/classifier4/
 437           {
 438             connectionTracking : 1 (reflexive)
 439             dFromPort          : 80
 440             dToPort            : 80
 441             etherT             : 2048 (ipv4)
 442             name               : classifier4
 443             prot               : 6
 444           }
 445     ───⦁ GbpeL24Classifier,/PolicyUniverse/PolicySpace/test/GbpeL24Classifier/classifier3/
 446           {
 447             etherT : 34525 (ipv6)
 448             name   : classifier3
 449             order  : 100
 450             prot   : 58
 451           }
 452     ───⦁ GbpeL24Classifier,/PolicyUniverse/PolicySpace/test/GbpeL24Classifier/classifier1/
 453           {
 454             etherT : 2054 (arp)
 455             name   : classifier1
 456             order  : 102
 457           }
 458     ───⦁ GbpeL24Classifier,/PolicyUniverse/PolicySpace/test/GbpeL24Classifier/classifier2/
 459           {
 460             etherT : 2048 (ipv4)
 461             name   : classifier2
 462             order  : 101
 463             prot   : 1
 464           }
 465
 466 You can also request to get the all the children of an object you query
 467 for:
 468
 469 ::
 470
 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/
 475
 476 You can also follow references found in any object downloads:
 477
 478 ::
 479
 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/