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

   1 OpFlex agent-ovs User Guide
   2 ===========================
   3
   4 Introduction
   5 ------------
   6
   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
  10 tools like OpenStack.
  11
  12 Agent Configuration
  13 -------------------
  14
  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"
  17
  18 Here is an example configuration file that documents the available
  19 options:
  20
  21 ::
  22
  23     {
  24         // Logging configuration
  25         // "log": {
  26         //    "level": "info"
  27         // },
  28
  29         // Configuration related to the OpFlex protocol
  30         "opflex": {
  31             // The policy domain for this agent.
  32             "domain": "openstack",
  33
  34             // The unique name in the policy domain for this agent.
  35             "name": "example-agent",
  36
  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
  40             // peers.
  41             "peers": [
  42                 // EXAMPLE:
  43                 {"hostname": "10.0.0.30", "port": 8009}
  44             ],
  45
  46             "ssl": {
  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
  51                 "mode": "disabled",
  52
  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/"
  57             },
  58
  59             "inspector": {
  60                 // Enable the MODB inspector service, which allows
  61                 // inspecting the state of the managed object database.
  62             // Default: enabled
  63                 "enabled": true,
  64
  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"
  68             }
  69         },
  70
  71         // Endpoint sources provide metadata about local endpoints
  72         "endpoint-sources": {
  73             // Filesystem path to monitor for endpoint information
  74             "filesystem": ["/var/lib/opflex-agent-ovs/endpoints"]
  75         },
  76
  77         // Renderers enforce policy obtained via OpFlex.
  78         "renderers": {
  79             // Stitched-mode renderer for interoperating with a
  80             // hardware fabric such as ACI
  81             // EXAMPLE:
  82             "stitched-mode": {
  83                 "ovs-bridge-name": "br0",
  84
  85                 // Set encapsulation type.  Must set either vxlan or vlan.
  86                 "encap": {
  87                     // Encapsulate traffic with VXLAN.
  88                     "vxlan" : {
  89                         // The name of the tunnel interface in OVS
  90                         "encap-iface": "br0_vxlan0",
  91
  92                         // The name of the interface whose IP should be used
  93                         // as the source IP in encapsulated traffic.
  94                         "uplink-iface": "eth0.4093",
  95
  96                         // The vlan tag, if any, used on the uplink interface.
  97                         // Set to zero or omit if the uplink is untagged.
  98                         "uplink-vlan": 4093,
  99
 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",
 105
 106                         // UDP port number of the encapsulated traffic.
 107                         "remote-port": 8472
 108                     }
 109
 110                     // Encapsulate traffic with a locally-significant VLAN
 111                     // tag
 112                     // EXAMPLE:
 113                     // "vlan" : {
 114                     //     // The name of the uplink interface in OVS
 115                     //     "encap-iface": "team0"
 116                     // }
 117                 },
 118
 119                 // Configure forwarding policy
 120                 "forwarding": {
 121                     // Configure the virtual distributed router
 122                     "virtual-router": {
 123                         // Enable virtual distributed router.  Set to true
 124                         // to enable or false to disable.  Default true.
 125                         "enabled": true,
 126
 127                         // Override MAC address for virtual router.
 128                         // Default is "00:22:bd:f8:19:ff"
 129                         "mac": "00:22:bd:f8:19:ff",
 130
 131                         // Configure IPv6-related settings for the virtual
 132                         // router
 133                         "ipv6" : {
 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
 140                         }
 141                     },
 142
 143                     // Configure virtual distributed DHCP server
 144                     "virtual-dhcp": {
 145                         // Enable virtual distributed DHCP server.  Set to
 146                         // true to enable or false to disable.  Default
 147                         // true.
 148                         "enabled": true,
 149
 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"
 153                     },
 154
 155                     "endpoint-advertisements": {
 156                         // Enable generation of periodic ARP/NDP
 157                         // advertisements for endpoints.  Default true.
 158                         "enabled": "true"
 159                     }
 160                 },
 161
 162                 // Location to store cached IDs for managing flow state
 163                 "flowid-cache-dir": "/var/lib/opflex-agent-ovs/ids"
 164             }
 165         }
 166     }
 167
 168 Endpoint Registration
 169 ---------------------
 170
 171 The agent learns about endpoints using endpoint metadata files located
 172 by default in "/var/lib/opflex-agent-ovs/endpoints".
 173
 174 These are JSON-format files such as the (unusually complex) example
 175 below:
 176
 177 ::
 178
 179     {
 180         "uuid": "83f18f0b-80f7-46e2-b06c-4d9487b0c754",
 181         "policy-space-name": "test",
 182         "endpoint-group-name": "group1",
 183         "interface-name": "veth0",
 184         "ip": [
 185             "10.0.0.1", "fd8f:69d8:c12c:ca62::1"
 186         ],
 187         "dhcp4": {
 188             "ip": "10.200.44.2",
 189             "prefix-len": 24,
 190             "routers": ["10.200.44.1"],
 191             "dns-servers": ["8.8.8.8", "8.8.4.4"],
 192             "domain": "example.com",
 193             "static-routes": [
 194                 {
 195                     "dest": "169.254.169.0",
 196                     "dest-prefix": 24,
 197                     "next-hop": "10.0.0.1"
 198                 }
 199             ]
 200         },
 201         "dhcp6": {
 202             "dns-servers": ["2001:4860:4860::8888", "2001:4860:4860::8844"],
 203             "search-list": ["test1.example.com", "example.com"]
 204         },
 205         "ip-address-mapping": [
 206             {
 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"
 212             },
 213             {
 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"
 219             }
 220         ],
 221         "mac": "00:00:00:00:00:01",
 222         "promiscuous-mode": false
 223     }
 224
 225 The possible parameters for these files are:
 226
 227 **uuid**
 228     A globally unique ID for the endpoint
 229
 230 **endpoint-group-name**
 231     The name of the endpoint group for the endpoint
 232
 233 **policy-space-name**
 234     The name of the policy space for the endpoint group.
 235
 236 **interface-name**
 237     The name of the OVS interface to which the endpoint is attached
 238
 239 **ip**
 240     A list of strings contains either IPv4 or IPv6 addresses that the
 241     endpoint is allowed to use
 242
 243 **mac**
 244     The MAC address for the endpoint’s interface.
 245
 246 **promiscuous-mode**
 247     Allow traffic from this VM to bypass default port security
 248
 249 **dhcp4**
 250     A distributed DHCPv4 configuration block (see below)
 251
 252 **dhcp6**
 253     A distributed DHCPv6 configuration block (see below)
 254
 255 **ip-address-mapping**
 256     A list of IP address mapping configuration blocks (see below)
 257
 258 DHCPv4 configuration blocks can contain the following parameters:
 259
 260 **ip**
 261     the IP address to return with DHCP. Must be one of the configured
 262     IPv4 addresses.
 263
 264 **prefix**
 265     the subnet prefix length
 266
 267 **routers**
 268     a list of default gateways for the endpoint
 269
 270 **dns**
 271     a list of DNS server addresses
 272
 273 **domain**
 274     The domain name parameter to send in the DHCP reply
 275
 276 **static-routes**
 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
 280
 281 DHCPv6 configuration blocks can contain the following parameters:
 282
 283 **dns**
 284     A list of DNS servers for the endpoint
 285
 286 **search-patch**
 287     The DNS search path for the endpoint
 288
 289 IP address mapping configuration blocks can contain the following
 290 parameters:
 291
 292 **uuid**
 293     a globally unique ID for the virtual endpoint created by the
 294     mapping.
 295
 296 **floating-ip**
 297     Map using DNAT to this floating IPv4 or IPv6 address
 298
 299 **mapped-ip**
 300     the source IPv4 or IPv6 address; must be one of the IPs assigned to
 301     the endpoint.
 302
 303 **endpoint-group-name**
 304     The name of the endpoint group for the NATed IP
 305
 306 **policy-space-name**
 307     The name of the policy space for the NATed IP
 308
 309 Inspector
 310 ---------
 311
 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.
 315
 316 The command is called "gbp\_inspect" and takes the following arguments:
 317
 318 ::
 319
 320     # gbp_inspect -h
 321     Usage: ./gbp_inspect [options]
 322     Allowed options:
 323       -h [ --help ]                         Print this help message
 324       --log arg                             Log to the specified file (default
 325                                             standard out)
 326       --level arg (=warning)                Use the specified log level (default
 327                                             info)
 328       --syslog                              Log to syslog instead of file or
 329                                             standard out
 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
 338                                             returned object
 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
 347
 348 Here are some examples of the ways to use this tool.
 349
 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,
 353 nonrecursively:
 354
 355 ::
 356
 357     # gbp_inspect -q DmtreeRoot
 358     --* 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/
 364
 365 You can also display all the properties for each object:
 366
 367 ::
 368
 369     # gbp_inspect -p -q GbpeL24Classifier
 370     --* GbpeL24Classifier,/PolicyUniverse/PolicySpace/test/GbpeL24Classifier/classifier4/
 371          {
 372            connectionTracking : 1 (reflexive)
 373            dFromPort          : 80
 374            dToPort            : 80
 375            etherT             : 2048 (ipv4)
 376            name               : classifier4
 377            prot               : 6
 378          }
 379     --* GbpeL24Classifier,/PolicyUniverse/PolicySpace/test/GbpeL24Classifier/classifier3/
 380          {
 381            etherT : 34525 (ipv6)
 382            name   : classifier3
 383            order  : 100
 384            prot   : 58
 385          }
 386     --* GbpeL24Classifier,/PolicyUniverse/PolicySpace/test/GbpeL24Classifier/classifier2/
 387          {
 388            etherT : 2048 (ipv4)
 389            name   : classifier2
 390            order  : 101
 391            prot   : 1
 392          }
 393
 394 You can also request to get the all the children of an object you query
 395 for:
 396
 397 ::
 398
 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/
 403
 404 You can also follow references found in any object downloads:
 405
 406 ::
 407
 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/
 422