OpenStack Networking (neutron) API v2.0 参考手册

mrj4733865

贡献于2015-05-08

字数:0 关键词: 分布式/云计算/大数据 手册

docs.openstack.org Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions ii OpenStack Networking (neutron) API v2.0 Reference API v2.0 and extensions (2014-05-20) Copyright © 2011-2014 OpenStack Foundation All rights reserved. This document is for software developers who develop applications by using the OpenStack Networking API v2.0. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions iii Table of Contents Preface ............................................................................................................................ 4 Intended audience .................................................................................................. 4 Document change history ....................................................................................... 5 Resources ................................................................................................................ 6 1. Overview ..................................................................................................................... 1 Glossary .................................................................................................................. 2 Concepts ................................................................................................................. 3 High-level task flow ............................................................................................... 10 Plug-ins .................................................................................................................. 12 2. General API information ............................................................................................ 13 Authentication and authorization .......................................................................... 13 Request and response types .................................................................................. 14 Filtering and column selection ............................................................................... 15 Synchronous versus asynchronous plug-in behavior ................................................ 15 Bulk-create ............................................................................................................ 16 Pagination ............................................................................................................. 16 Sorting .................................................................................................................. 19 Extensions ............................................................................................................. 20 Faults .................................................................................................................... 21 3. API operations .......................................................................................................... 22 Networks .............................................................................................................. 22 Subnets ................................................................................................................. 44 Ports ..................................................................................................................... 56 4. API extensions ........................................................................................................... 71 Get extension information ..................................................................................... 71 Agent management .............................................................................................. 78 Agent schedulers ................................................................................................... 83 Allowed address pairs ........................................................................................... 92 The binding Extended Attributes for Ports .......................................................... 95 Configurable external gateway modes ................................................................... 99 External networks (external-net) ................................................................... 104 Extra routes ......................................................................................................... 107 Firewall as a Service (FWaaS) ............................................................................... 109 Layer-3 networking (router) ............................................................................. 126 Load Balancer as a Service (LBaaS) ...................................................................... 142 Metering labels and rules .................................................................................... 169 Provider networks (provider) ........................................................................... 180 Multiple provider networks ................................................................................. 190 Quotas ................................................................................................................ 195 Security groups and rules (security-groups) .......................................................... 200 Virtual Private Network as a Service (VPNaaS) ..................................................... 212 Extra DHCP options (extra-dhcp-opt) ............................................................ 234 Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 4 Preface Intended audience .......................................................................................................... 4 Document change history ............................................................................................... 5 Resources ........................................................................................................................ 6 The OpenStack Networking (neutron) project provides virtual networking services among devices managed by the OpenStack compute service. This document describes the Networking (neutron) API v2.0 features. We welcome feedback, comments, and bug reports at bugs.launchpad.net/Neutron. Intended audience This guide is for software developers who create applications by using the Networking (neutron) API v2.0. To use this information, you should have a general understanding of the OpenStack Networking service, the OpenStack compute service, and the integration between the two. You should also have access to a plug-in that implements the Networking (neutron) API v2.0. You should also be familiar with: • ReSTful web services • HTTP/1.1 • JSON and XML data serialization formats Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 5 Document change history This version of the document replaces and obsoletes all previous versions. The following table describes the most recent changes: Revision Date Summary of Changes April 29, 2014 • Updated binding:capabilities to binding:vif_details. December 20, 2013 • Updated book to source information from WADL files. October 11, 2013 • Added the Networking API ports binding extension. May 22, 2013 • Updated the title of the book and project name to "OpenStack Networking." • Updated the title of the book to Reference from Developer Guide for consistency. March 23, 2013 • Updated incorrect nova command examples in the section called “High-level task flow” [10]. September 5, 2012 • Removed XML as a valid request or response type. August 17, 2012 • First edition of this book. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 6 Resources Use the following resources in conjunction with this guide: Resource See Related documents OpenStack Documentation OpenStack Neutron Wiki http://wiki.openstack.org/Neutron Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 1 1. Overview Glossary .......................................................................................................................... 2 Concepts ......................................................................................................................... 3 High-level task flow ....................................................................................................... 10 Plug-ins .......................................................................................................................... 12 The Neutron project provides virtual networking services among devices that are managed by the OpenStack compute service. The Networking API v2.0 combines the Quantum API v1.1 with some essential Internet Protocol Address Management (IPAM) capabilities from the Melange API. These IPAM capabilities enable you to: • Associate IP address blocks and other network configuration settings required by a network device, such as a default gateway and dns-servers settings, with an OpenStack Networking network. • Allocate an IP address from a block and associate it with a device that is attached to the network through an OpenStack Networking port. To do this, the Networking API v2.0 introduces the subnet entity. A subnet can represent either an IP version 4 or version 6 address block. Each OpenStack Networking network commonly has one or more subnets. When you create a port on the network, an available fixed IP address is allocated to it from one the designated subnets for each IP version. When you delete the port, the allocated addresses return to the pool of available IPs on the subnet. Networking API v2.0 users can choose a specific IP address from the block or let OpenStack Networking choose the first available IP address. Note The Quantum API v1.x was removed from the source code tree. To use the Quantum API v1.x, install the Quantum Essex release. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 2 Glossary Term Description CRUD Create, read, update, and delete (CRUD) are the basic functions of persistent storage in computer programming. entity Any piece of hardware or software that can connect to the network services provided by OpenStack Networking. An entity can use OpenStack Networking services by implementing a VIF. IPAM Internet Protocol Address Management (IPAM) is a means of planning, tracking, and managing the Internet Protocol (IP) address space that is used in a network. layer-2 network A virtual Ethernet network that is managed by the OpenStack Networking service. Currently, OpenStack Networking manages only Ethernet networks. network An isolated virtual layer-2 broadcast domain that is typically reserved for the tenant who created it unless the network is configured to be shared. Tenants can create multiple networks until they reach the thresholds specified by per-tenant quotas. plug-in A software component that implements Networking API v2.0. port A virtual switch port on a logical network switch. Virtual instances attach their interfaces into ports. The logical port also defines the MAC address and the IP addresses to be assigned to the interfaces plugged into them. When creating a port, any unallocated IP in the subnet can be stated specifically, even if the IP address is not in the allocation pool. Enabling users to specify the IP explicitly allows them to retain a particular subset of the subnet IPs for static allocation. subnet An IP address block that can be used to assign IP addresses to virtual instances. Each subnet must have a CIDR and must be associated with a network. IPs can be either selected from the whole subnet CIDR or from allocation pools that can be specified by the user. VM A virtual machine (VM) is a completely isolated guest operating system installation within a normal host operating system. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 3 Concepts Use the Networking API v2.0 to manage the following entities: • Network. An isolated virtual layer-2 domain. A network can also be a virtual, or logical, switch. See the section called “Network” [4]. • Subnet. An IP version 4 or version 6 address block from which IP addresses that are assigned to VMs on a specified network are selected. See the section called “Subnet” [6]. • Port. A virtual, or logical, switch port on a specified network. See the section called “Port” [8]. These entities have auto-generated unique identifiers and support basic create, read, update, and delete (CRUD) functions with the POST, GET, PUT, and DELETE verbs. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 4 Network A network is an isolated virtual layer-2 broadcast domain that is typically reserved for the tenant who created it unless you configure the network to be shared. Tenants can create multiple networks until the thresholds per-tenant quota is reached. In the Networking API v2.0, the network is the main entity. Ports and subnets are always associated with a network. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 5 The following table describes the attributes for network objects: Table 1.1. Network attributes Attribute Type Required CRUDa Default Value Validation Constraints Notes id uuid-str N/A R generated N/A UUID for the network. name String No CRU None N/A Human-readable name for the network. Might not be unique. admin_state_up Bool No CRU true {true|false} The administrative state of network. If false (down), the network does not forward packets. status String N/A R N/A N/A Indicates whether network is currently operational. Possible values include: • ACTIVE • DOWN • BUILD • ERROR Plug-ins might define additional values. subnets list(uuid- str) No R Empty List N/A subnets associated with this network. shared Bool No CRU False { True | False } Specifies whether the network resource can be accessed by any tenant or not. tenant_id uuid-str Nob CR N/A No constraint Owner of network. Only admin users can specify a tenant_id other than its own. a•C. Use the attribute in create operations. •R. This attribute is returned in response to show and list operations. •U. You can update the value of this attribute. •D. You can delete the value of this attribute. bIf OpenStack Networking is not running with the Keystone Identity service, the tenant_id attribute is required. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 6 Subnet A subnet represents an IP address block that can be used to assign IP addresses to virtual instances. Each subnet must have a CIDR and must be associated with a network. IPs can be either selected from the whole subnet CIDR or from allocation pools that can be specified by the user. A subnet can also optionally have a gateway, a list of dns name servers, and host routes. This information is pushed to instances whose interfaces are associated with the subnet. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 7 Table 1.2. Subnet Attributes Attribute Type Required CRUDa Default Value Validation Constraints Notes id uuid-str N/A R generated N/A UUID representing the subnet network_id uuid-str Yes CR N/A network this subnet is associated with. name String No CRU None N/A Human-readable name for the subnet. Might not be unique. ip_version int Yes CR 4 { 4 | 6 } IP version cidr string Yes CR N/A valid cidr in the form / cidr representing IP range for this subnet, based on IP version gateway_ip string No CRUD first address in cidr Valid IP address or null default gateway used by devices in this subnet dns_nameservers list(str) No CRU Empty list No constraint DNS name servers used by hosts in this subnet. allocation_pools list(dict) No CR Every address in cidr, excluding gateway_ip if configured star/end of range must be valid ip Sub-ranges of cidr available for dynamic allocation to ports [ { "start": "10.0.0.2", "end": "10.0.0.254"} ] host_routes list(dict) No CRU Empty List [] Routes that should be used by devices with IPs from this subnet (not including local subnet route). enable_dhcp Bool No CRU True { True | False } Specifies whether DHCP is enabled for this subnet or not. tenant_id uuid-str Nob CR N/A No constraint Owner of network. Only admin users can specify a tenant_id other than its own. a•C. Use the attribute in create operations. •R. This attribute is returned in response to show and list operations. •U. You can update the value of this attribute. •D. You can delete the value of this attribute. bIf OpenStack Networking is not running with the Keystone Identity service, the tenant_id attribute is required. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 8 Port A port represents a virtual switch port on a logical network switch. Virtual instances attach their interfaces into ports. The logical port also defines the MAC address and the IP address(es) to be assigned to the interfaces plugged into them. When IP addresses are associated to a port, this also implies the port is associated with a subnet, as the IP address was taken from the allocation pool for a specific subnet. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 9 Table 1.3. Port Attributes Attribute Type Required CRUDa Default Value Validation Constraints Notes id uuid-str N/A R generated N/A UUID for the port. network_id uuid-str Yes CR N/A existing network identifier Network that this port is associated with. name String No CRU None N/A Human-readable name for the port. Might not be unique. admin_state_up bool No CRU true {true|false} Administrative state of port. If false (down), port does not forward packets. status string N/A R N/A N/A Indicates whether network is currently operational. Possible values include: • ACTIVE • DOWN • BUILD • ERROR Plug-ins might define additional values. mac_address string No CR generated valid MAC in 6-octet form separated by colons Mac address to use on this port. fixed_ips list(dict) No CRU automatically allocated from pool Valid IP address and existing subnet identifier Specifies IP addresses for the port thus associating the port itself with the subnets where the IP addresses are picked from device_id str No CRUD None No constraint identifies the device (e.g., virtual server) using this port. device_owner str No CRUD None No constraint Identifies the entity (e.g.: dhcp agent) using this port. tenant_id uuid-str Nob CR N/A No constraint Owner of network. Only admin users can specify a tenant_id other than its own. security_groups list(dict) No CRUD None Existing security group IDs Specifies the IDs of any security groups associated with a port. a•C. Use the attribute in create operations. •R. This attribute is returned in response to show and list operations. •U. You can update the value of this attribute. •D. You can delete the value of this attribute. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 10 bIf OpenStack Networking is not running with the Keystone Identity service, the tenant_id attribute is required. High-level task flow The high-level task flow for OpenStack Networking involves creating a network, associating a subnet with that network, and booting a VM that is attached to the network. Clean-up includes deleting the VM, deleting any ports associated with the network, and deleting the networks. OpenStack Networking deletes any subnets associated with the deleted network. To use OpenStack Networking - high-level task flow 1. Create a network The tenant creates a network. For example, the tenant creates the net1 network. Its ID is net1_id. 2. Associate a subnet with the network The tenant associates a subnet with that network. For example, the tenant associates the 10.0.0.0/24 subnet with the net1 network. 3. Boot a VM and attach it to the network The tenant boots a virtual machine (VM) and specifies a single NIC that connects to the network. The following examples use the nova client to boot a VM. In the first example, Nova contacts OpenStack Networking to create the NIC and attach it to the net1 network, with the ID net1_id: $ nova boot --image --flavor --nic net-id= In a second example, you first create the port1, port and then you boot the VM with a specified port. OpenStack Networking creates a NIC and attaches it to the port1 port, with the ID port1_id: $ nova boot --image --flavor --nic port-id= OpenStack Networking chooses and assigns an IP address to the port1 port. For more information about the nova boot command, enter: $ nova help boot 4. Delete the VM The tenant deletes the VM. Nova contacts OpenStack Networking and deletes the port1 port. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 11 The allocated IP address is returned to the pool of available IP addresses. 5. Delete any ports If the tenant created any ports and associated them with the network, the tenant deletes the ports. 6. Delete the network The tenant deletes the network. This operation deletes an OpenStack Networking network and its associated subnets provided that no port is currently configured on the network. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 12 Plug-ins Virtual networking services are implemented through a plug-in. A plug-in can use different techniques and technologies to provide isolated virtual networks to tenants. A plug-in also provides other services, such as IP address management. Because each plug-in implements all the operations included in Networking API v2.0, do not be concerned about which plug- in is used. However, some plug-ins might expose additional capabilities through API extensions, which this document discusses. For more information about the extensions exposed by a particular plug-in, see the plug-in documentation. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 13 2. General API information Authentication and authorization ................................................................................. 13 Request and response types .......................................................................................... 14 Filtering and column selection ....................................................................................... 15 Synchronous versus asynchronous plug-in behavior ........................................................ 15 Bulk-create .................................................................................................................... 16 Pagination ..................................................................................................................... 16 Sorting .......................................................................................................................... 19 Extensions ..................................................................................................................... 20 Faults ............................................................................................................................ 21 The Networking API v2.0 is a ReSTful HTTP service that uses all aspects of the HTTP protocol including methods, URIs, media types, response codes, and so on. Providers can use existing features of the protocol including caching, persistent connections, and content compression. For example, providers who employ a caching layer can respond with a 203 code instead of a 200 code when a request is served from the cache. Additionally, providers can offer support for conditional GET requests by using ETags, or they may send a redirect in response to a GET request. Create clients so that these differences are accounted for. Authentication and authorization The Networking API v2.0 uses the Keystone Identity Service as the default authentication service. When Keystone is enabled, users that submit requests to the OpenStack Networking service must provide an authentication token in X-Auth-Token request header. You obtain the token by authenticating to the Keystone endpoint. For more information about Keystone, see the OpenStack Identity Service API v2.0 Reference. When Keystone is enabled, the tenant_id attribute is not required in create requests because the tenant ID is derived from the authentication token. The default authorization settings allow only administrative users to create resources on behalf of a different tenant. OpenStack Networking uses information received from Keystone to authorize user requests. OpenStack Networking handles the following types of authorization policies: • Operation-based policies specify access criteria for specific operations, possibly with fine- grained control over specific attributes. • Resource-based policies access a specific resource. Permissions might or might not be granted depending on the permissions configured for the resource. Currently available for only the network resource. The actual authorization policies enforced in OpenStack Networking might vary from deployment to deployment. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 14 Request and response types The Networking API v2.0 supports the JSON data serialization format. The format for both the request and the response can be specified by using the Content- Type header, the Accept header or adding the .json extension to the request URI. Example 2.1. JSON request with headers POST /v1.0/tenants/tenantX/networks HTTP/1.1 Host 127.0.0.1:9696 Content-Type application/json Accept application/json Content-Length 57 { "network": { "name": "sample_network", "admin_state_up": true } } Example 2.2. JSON response with headers HTTP/1.1 201 Created Content-Type application/json Content-Length 204 { "network": { "status": "ACTIVE", "subnets": [], "name": "net1", "admin_state_up": true, "tenant_id": "9bacb3c5d39d41a79512987f338cf177", "segments": [ { "provider:segmentation_id": 2, "provider:physical_network": "8bab8453-1bc9-45af-8c70- f83aa9b50453", "provider:network_type": "vlan" }, { "provider:segmentation_id": null, "provider:physical_network": "8bab8453-1bc9-45af-8c70- f83aa9b50453", "provider:network_type": "stt" } ], "shared": false, "port_security_enabled": true, "id": "4e8e5957-649f-477b-9e5b-f1f75b21c03c" } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 15 Filtering and column selection The Networking API v2.0 supports filtering based on all top level attributes of a resource. Filters are applicable to all list requests. For example, the following request returns all networks named foobar: GET /v2.0/networks?name=foobar When you specify multiple filters, the Networking API v2.0 returns only objects that meet all filtering criteria. The operation applies an AND condition among the filters. Note OpenStack Networking does not offer an OR mechanism for filters. Alternatively, you can issue a distinct request for each filter and build a response set from the received responses on the client-side. By default, OpenStack Networking returns all attributes for any show or list call. The Networking API v2.0 has a mechanism to limit the set of attributes returned. For example, return id. You can use the fields query parameter to control the attributes returned from the Networking API v2.0. For example, the following request returns only id and name for each network: GET /v2.0/networks.json?fields=id&fields=name Synchronous versus asynchronous plug-in behavior The Networking API v2.0 presents a logical model of network connectivity consisting of networks, ports, and subnets. It is up to the OpenStack Networking plug-in to communicate with the underlying infrastructure to ensure packet forwarding is consistent with the logical model. A plug-in might perform these operations asynchronously. When an API client modifies the logical model by issuing an HTTP POST, PUT, or DELETE request, the API call might return before the plug-in modifies underlying virtual and physical switching devices. However, an API client is guaranteed that all subsequent API calls properly reflect the changed logical model. For example, if a client issues an HTTP PUT request to set the attachment for a port, there is no guarantee that packets sent by the interface named in the attachment are forwarded immediately when the HTTP call returns. However, it is guaranteed that a subsequent HTTP GET request to view the attachment on that port returns the new attachment value. You can use the status attribute with the network and port resources to determine whether the OpenStack Networking plug-in has successfully completed the configuration of the resource. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 16 Bulk-create The Networking API v2.0 enables you to create several objects of the same type in the same API request. Bulk create operations use exactly the same API syntax as single create operations except that you specify a list of objects rather than a single object in the request body. Bulk operations are always performed atomically, meaning that either all or none of the objects in the request body are created. If a particular plug-in does not support atomic operations, the Networking API v2.0 emulates the atomic behavior so that users can expect the same behavior regardless of the particular plug-in running in the background. OpenStack Networking might be deployed without support for bulk operations and when the client attempts a bulk create operation, a 400 Bad request error is returned. Pagination To reduce load on the service, list operations will return a maximum number of items at a time. To navigate the collection, the parameters limit, marker and page_reverse can be set in the URI. For example: ?limit=100&marker=1234&page_reverse=False The marker parameter is the ID of the last item in the previous list. The limit parameter sets the page size. The page_reverse parameter sets the page direction. These parameters are optional. If the client requests a limit beyond the maximum limit configured by the deployment, the server returns the maximum limit number of items. For convenience, list responses contain atom "next" links and "previous" links. The last page in the list requested with 'page_reverse=False' will not contain "next" link, and the last page in the list requested with 'page_reverse=True' will not contain "previous" link. The following examples illustrate two pages with three items. The first page was retrieved through: GET http://127.0.0.1:9696/v2.0/networks.json?limit=2 Pagination is an optional feature of OpenStack Networking API, and it might be disabled. If pagination is disabled, the pagination parameters will be ignored and return all the items. If a particular plug-in does not support pagination operations, and pagination is enabled, the Networking API v2.0 will emulate the pagination behavior so that users can expect the same behavior regardless of the particular plug-in running in the background. Unfortunately OpenStack Networking does not expose any mechanism to tell user if pagination is supported by particular plug-in or enabled. Example 2.3. Network collection, first page: JSON request GET /v2.0/networks.json?limit=2 HTTP/1.1 Host: 127.0.0.1:9696 Content-Type: application/json Accept: application/json Example 2.4. Network collection, first page: JSON response { Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 17 "networks": [ { "admin_state_up": true, "id": "396f12f8-521e-4b91-8e21-2e003500433a", "name": "net3", "provider:network_type": "vlan", "provider:physical_network": "physnet1", "provider:segmentation_id": 1002, "router:external": false, "shared": false, "status": "ACTIVE", "subnets": [], "tenant_id": "20bd52ff3e1b40039c312395b04683cf" }, { "admin_state_up": true, "id": "71c1e68c-171a-4aa2-aca5-50ea153a3718", "name": "net2", "provider:network_type": "vlan", "provider:physical_network": "physnet1", "provider:segmentation_id": 1001, "router:external": false, "shared": false, "status": "ACTIVE", "subnets": [], "tenant_id": "20bd52ff3e1b40039c312395b04683cf" } ], "networks_links": [ { "href": "http://127.0.0.1:9696/v2.0/networks.json?limit=2&marker= 71c1e68c-171a-4aa2-aca5-50ea153a3718", "rel": "next" }, { "href": "http://127.0.0.1:9696/v2.0/networks.json?limit=2&marker= 396f12f8-521e-4b91-8e21-2e003500433a&page_reverse=True", "rel": "previous" } ] } Example 2.5. Network collection, first page: XML request GET /v2.0/networks.xml?limit=2 HTTP/1.1 Host: 127.0.0.1:9696 Content-Type: application/xml Accept: application/xml Example 2.6. Network collection, first page: XML response Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 18 ACTIVE net3 physnet1 True 20bd52ff3e1b40039c312395b04683cf vlan False False 396f12f8-521e-4b91-8e21-2e003500433a 1002 ACTIVE net2 physnet1 True 20bd52ff3e1b40039c312395b04683cf vlan False False 71c1e68c-171a-4aa2-aca5-50ea153a3718 1001 The last page won't show the "next" links Example 2.7. Network collection, last page: JSON request GET /v2.0/networks.json?limit=2&marker=71c1e68c-171a-4aa2-aca5-50ea153a3718 HTTP/1.1 Host: 127.0.0.1:9696 Content-Type: application/json Accept: application/json Example 2.8. Network collection, last page: JSON response { "networks": [ { "admin_state_up": true, "id": "b3680498-03da-4691-896f-ef9ee1d856a7", "name": "net1", "provider:network_type": "vlan", "provider:physical_network": "physnet1", "provider:segmentation_id": 1000, Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 19 "router:external": false, "shared": false, "status": "ACTIVE", "subnets": [], "tenant_id": "c05140b3dc7c4555afff9fab6b58edc2" } ], "networks_links": [ { "href": "http://127.0.0.1:9696/v2.0/networks.json?limit=2&marker= b3680498-03da-4691-896f-ef9ee1d856a7&page_reverse=True", "rel": "previous" } ] } Example 2.9. Network collection, last page: XML request GET /v2.0/networks.xml?limit=2&marker=71c1e68c-171a-4aa2-aca5-50ea153a3718 HTTP/1.1 Host: 127.0.0.1:9696 Content-Type: application/xml Accept: application/xml Example 2.10. Network collection, last page: XML response ACTIVE net1 physnet1 True c05140b3dc7c4555afff9fab6b58edc2 vlan False False b3680498-03da-4691-896f-ef9ee1d856a7 1000 Sorting You can use the sort_key and sort_dir parameters to sort the results of list operations. Currently sorting does not work with extended attributes of resource. The sort_key and Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 20 sort_dir can be repeated, and the number of sort_key and sort_dir provided must be same. The sort_dir parameter indicates in which direction to sort. Acceptable values are asc (ascending) and desc (descending). Sorting is optional feature of OpenStack Networking API, and it might be disabled. If sorting is disabled, the sorting parameters are ignored. If a particular plug-in does not support sorting operations and sorting is enabled, the Networking API v2.0 emulates the sorting behavior so that users can expect the same behavior regardless of the particular plug-in that runs in the background. Unfortunately OpenStack Networking does provide a mechanism to tell users if specific plug-ins support or have enabled sorting. Extensions The Networking API v2.0 is extensible. The purpose of Networking API v2.0 extensions is to: • Introduce new features in the API without requiring a version change. • Introduce vendor-specific niche functionality. • Act as a proving ground for experimental functionalities that might be included in a future version of the API. To programmatically determine which extensions are available, issue a GET request on the v2.0/extensions URI. To query extensions individually by unique alias, issue a GET request on the /v2.0/ extensions/alias_name URI. Use this method to easily determine if an extension is available. If the extension is not available, a 404 Not Found response is returned. You can extend existing core API resources with new actions or extra attributes. Also, you can add new resources as extensions. Extensions usually have tags that prevent conflicts with other extensions that define attributes or resources with the same names, and with core resources and attributes. Because an extension might not be supported by all plug-ins, the availability of an extension varies with deployments and the specific plug-in in use. For more information regarding specific extensions, see Chapter 4, “API extensions” [71] Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 21 Faults The Networking API v2.0 returns an error response if a failure occurs while processing a request. OpenStack Networking uses only standard HTTP error codes. 4nn errors indicate problems in the particular request being sent from the client. Error Description Malformed request URI or body requested admin state invalid Invalid values entered Bulk operations disallowed Validation failed 400 Bad request Method not allowed for request body (such as trying to update attributes that can be specified at create-time only) Non existent URI404 Not Found Resource not found Port configured on network IP allocated on subnet 409 Conflict Conflicting IP allocation pools for subnet 500 Internal server error Internal OpenStack Networking error 503 Service unavailable Failure in Mac address generation Users submitting requests to the Networking API v2.0 might also receive the following errors: • 401 Unauthorized - If invalid credentials are provided. • 403 Forbidden - If the user cannot access a specific resource or perform the requested operation. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 22 3. API operations Networks ...................................................................................................................... 22 Subnets ......................................................................................................................... 44 Ports ............................................................................................................................. 56 Provides virtual networking services among devices that are managed by the OpenStack Compute service. The Networking API v2.0 combines the API v1.1 functionality with some essential Internet Protocol Address Management (IPAM) functionality. Enables users to associate IP address blocks and other network configuration settings with a neutron network. You can choose a specific IP address from the block or let neutron choose the first available IP address. Method URI Description Networks GET / Lists information about all Networking API versions. GET /v2.0 Shows details for Networking API v2.0. GET /v2.0/extensions Lists available Networking API extensions. GET /v2.0/extensions/{alias} Gets detailed information for a specified extension. GET /v2.0/networks Lists networks to which the specified tenant has access. POST /v2.0/networks Creates a network. POST /v2.0/networks Creates multiple networks in a single request. GET /v2.0/networks/{network_id} Shows information for a specified network. PUT /v2.0/networks/{network_id} Updates a specified network. DELETE /v2.0/networks/{network_id} Deletes a specified network and its associated resources. Subnets GET /v2.0/subnets Lists subnets to which the specified tenant has access. POST /v2.0/subnets Creates a subnet on a specified network. POST /v2.0/subnets Creates multiple subnets in a single request. Specify a list of subnets in the request body. GET /v2.0/subnets/{subnet_id} Shows information for a specified subnet. PUT /v2.0/subnets/{subnet_id} Updates a specified subnet. DELETE /v2.0/subnets/{subnet_id} Deletes a specified subnet. Ports GET /v2.0/ports Lists ports to which the tenant has access. POST /v2.0/ports Creates a port on a specified network. POST /v2.0/ports Creates multiple ports in a single request. Specify a list of ports in the request body. GET /v2.0/ports/{port_id} Shows information for a specified port. PUT /v2.0/ports/{port_id} Updates a specified port. DELETE /v2.0/ports/{port_id} Deletes a specified port. Networks List, show information for, create, update, and delete networks. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 23 Method URI Description GET / Lists information about all Networking API versions. GET /v2.0 Shows details for Networking API v2.0. GET /v2.0/extensions Lists available Networking API extensions. GET /v2.0/extensions/{alias} Gets detailed information for a specified extension. GET /v2.0/networks Lists networks to which the specified tenant has access. POST /v2.0/networks Creates a network. POST /v2.0/networks Creates multiple networks in a single request. GET /v2.0/networks/{network_id} Shows information for a specified network. PUT /v2.0/networks/{network_id} Updates a specified network. DELETE /v2.0/networks/{network_id} Deletes a specified network and its associated resources. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 24 List API versions Method URI Description GET / Lists information about all Networking API versions. Normal response codes: 200, 300 Request This operation does not require a request body. Response Example 3.1. List API versions: JSON response { "versions": [ { "status": "CURRENT", "id": "v2.0", "links": [ { "href": "http://23.253.228.211:9696/v2.0", "rel": "self" } ] } ] } Example 3.2. List API versions: XML response CURRENT v2.0 http://23.253.228.211:9696/v2.0 self This operation does not return a response body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 25 Show API v2.0 details Method URI Description GET /v2.0 Shows details for Networking API v2.0. Normal response codes: 200, 203 Request This operation does not require a request body. Response Example 3.3. Show API v2.0 details: JSON response { "resources": [ { "links": [ { "href": "http://23.253.228.211:9696/v2.0/subnets", "rel": "self" } ], "name": "subnet", "collection": "subnets" }, { "links": [ { "href": "http://23.253.228.211:9696/v2.0/networks", "rel": "self" } ], "name": "network", "collection": "networks" }, { "links": [ { "href": "http://23.253.228.211:9696/v2.0/ports", "rel": "self" } ], "name": "port", "collection": "ports" } ] } This table shows the body parameters for the show api v2.0 details response: Name Type Description location AnyURI (Required) Full URL to a service or server. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 26 Example 3.4. Show API v2.0 details: XML response http://23.253.228.211:9696/v2.0/subnets self subnet subnets http://23.253.228.211:9696/v2.0/networks self network networks http://23.253.228.211:9696/v2.0/ports self port ports This operation does not return a response body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 27 List extensions Method URI Description GET /v2.0/extensions Lists available Networking API extensions. Normal response codes: 200, 203 Error response codes: computeFault (400, 500, …) Request This operation does not require a request body. Response Example 3.5. List extensions: JSON response { "extensions": [ { "updated": "2013-01-20T00:00:00-00:00", "name": "Neutron Service Type Management", "links": [], "namespace": "http://docs.openstack.org/ext/neutron/service-type/ api/v1.0", "alias": "service-type", "description": "API for retrieving service providers for Neutron advanced services" }, { "updated": "2012-10-05T10:00:00-00:00", "name": "security-group", "links": [], "namespace": "http://docs.openstack.org/ext/securitygroups/api/v2. 0", "alias": "security-group", "description": "The security groups extension." }, { "updated": "2013-02-07T10:00:00-00:00", "name": "L3 Agent Scheduler", "links": [], "namespace": "http://docs.openstack.org/ext/l3_agent_scheduler/ api/v1.0", "alias": "l3_agent_scheduler", "description": "Schedule routers among l3 agents" }, { "updated": "2013-02-07T10:00:00-00:00", "name": "Loadbalancer Agent Scheduler", "links": [], "namespace": "http://docs.openstack.org/ext/lbaas_agent_scheduler/ api/v1.0", "alias": "lbaas_agent_scheduler", "description": "Schedule pools among lbaas agents" }, { Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 28 "updated": "2013-03-28T10:00:00-00:00", "name": "Neutron L3 Configurable external gateway mode", "links": [], "namespace": "http://docs.openstack.org/ext/neutron/ext-gw-mode/ api/v1.0", "alias": "ext-gw-mode", "description": "Extension of the router abstraction for specifying whether SNAT should occur on the external gateway" }, { "updated": "2014-02-03T10:00:00-00:00", "name": "Port Binding", "links": [], "namespace": "http://docs.openstack.org/ext/binding/api/v1.0", "alias": "binding", "description": "Expose port bindings of a virtual port to external application" }, { "updated": "2012-09-07T10:00:00-00:00", "name": "Provider Network", "links": [], "namespace": "http://docs.openstack.org/ext/provider/api/v1.0", "alias": "provider", "description": "Expose mapping of virtual networks to physical networks" }, { "updated": "2013-02-03T10:00:00-00:00", "name": "agent", "links": [], "namespace": "http://docs.openstack.org/ext/agent/api/v2.0", "alias": "agent", "description": "The agent management extension." }, { "updated": "2012-07-29T10:00:00-00:00", "name": "Quota management support", "links": [], "namespace": "http://docs.openstack.org/network/ext/quotas-sets/ api/v2.0", "alias": "quotas", "description": "Expose functions for quotas management per tenant" }, { "updated": "2013-02-07T10:00:00-00:00", "name": "DHCP Agent Scheduler", "links": [], "namespace": "http://docs.openstack.org/ext/dhcp_agent_scheduler/ api/v1.0", "alias": "dhcp_agent_scheduler", "description": "Schedule networks among dhcp agents" }, { "updated": "2013-06-27T10:00:00-00:00", "name": "Multi Provider Network", "links": [], "namespace": "http://docs.openstack.org/ext/multi-provider/api/v1. 0", "alias": "multi-provider", Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 29 "description": "Expose mapping of virtual networks to multiple physical networks" }, { "updated": "2013-01-14T10:00:00-00:00", "name": "Neutron external network", "links": [], "namespace": "http://docs.openstack.org/ext/neutron/external_net/ api/v1.0", "alias": "external-net", "description": "Adds external network attribute to network resource." }, { "updated": "2012-07-20T10:00:00-00:00", "name": "Neutron L3 Router", "links": [], "namespace": "http://docs.openstack.org/ext/neutron/router/api/v1. 0", "alias": "router", "description": "Router abstraction for basic L3 forwarding between L2 Neutron networks and access to external networks via a NAT gateway." }, { "updated": "2013-07-23T10:00:00-00:00", "name": "Allowed Address Pairs", "links": [], "namespace": "http://docs.openstack.org/ext/allowedaddresspairs/ api/v2.0", "alias": "allowed-address-pairs", "description": "Provides allowed address pairs" }, { "updated": "2013-03-17T12:00:00-00:00", "name": "Neutron Extra DHCP opts", "links": [], "namespace": "http://docs.openstack.org/ext/neutron/ extra_dhcp_opt/api/v1.0", "alias": "extra_dhcp_opt", "description": "Extra options configuration for DHCP. For example PXE boot options to DHCP clients can be specified (e.g. tftp-server, server- ip-address, bootfile-name)" }, { "updated": "2012-10-07T10:00:00-00:00", "name": "LoadBalancing service", "links": [], "namespace": "http://wiki.openstack.org/neutron/LBaaS/API_1.0", "alias": "lbaas", "description": "Extension for LoadBalancing service" }, { "updated": "2013-02-01T10:00:00-00:00", "name": "Neutron Extra Route", "links": [], "namespace": "http://docs.openstack.org/ext/neutron/extraroutes/ api/v1.0", "alias": "extraroute", "description": "Extra routes configuration for L3 router" } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 30 ] } Example 3.6. List extensions: XML response 2013-01-20T00:00:00-00:00 Neutron Service Type Management http://docs.openstack.org/ext/neutron/service-type/api/v1. 0 service-type API for retrieving service providers for Neutron advanced services 2012-10-05T10:00:00-00:00 security-group http://docs.openstack.org/ext/securitygroups/api/v2.0 security-group The security groups extension. 2013-02-07T10:00:00-00:00 L3 Agent Scheduler http://docs.openstack.org/ext/l3_agent_scheduler/api/v1.0 l3_agent_scheduler Schedule routers among l3 agents 2013-02-07T10:00:00-00:00 Loadbalancer Agent Scheduler http://docs.openstack.org/ext/lbaas_agent_scheduler/api/v1. 0 lbaas_agent_scheduler Schedule pools among lbaas agents 2013-03-28T10:00:00-00:00 Neutron L3 Configurable external gateway mode http://docs.openstack.org/ext/neutron/ext-gw-mode/api/v1. 0 ext-gw-mode Extension of the router abstraction for specifying whether SNAT should occur on the external gateway 2014-02-03T10:00:00-00:00 Port Binding Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 31 http://docs.openstack.org/ext/binding/api/v1.0 binding Expose port bindings of a virtual port to external application 2012-09-07T10:00:00-00:00 Provider Network http://docs.openstack.org/ext/provider/api/v1.0 provider Expose mapping of virtual networks to physical networks 2013-02-03T10:00:00-00:00 agent http://docs.openstack.org/ext/agent/api/v2.0 agent The agent management extension. 2012-07-29T10:00:00-00:00 Quota management support http://docs.openstack.org/network/ext/quotas-sets/api/v2. 0 quotas Expose functions for quotas management per tenant 2013-02-07T10:00:00-00:00 DHCP Agent Scheduler http://docs.openstack.org/ext/dhcp_agent_scheduler/api/v1. 0 dhcp_agent_scheduler Schedule networks among dhcp agents 2013-06-27T10:00:00-00:00 Multi Provider Network http://docs.openstack.org/ext/multi-provider/api/v1.0 multi-provider Expose mapping of virtual networks to multiple physical networks 2013-01-14T10:00:00-00:00 Neutron external network http://docs.openstack.org/ext/neutron/external_net/api/v1. 0 external-net Adds external network attribute to network Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 32 resource. 2012-07-20T10:00:00-00:00 Neutron L3 Router http://docs.openstack.org/ext/neutron/router/api/v1.0 router Router abstraction for basic L3 forwarding between L2 Neutron networks and access to external networks via a NAT gateway. 2013-07-23T10:00:00-00:00 Allowed Address Pairs http://docs.openstack.org/ext/allowedaddresspairs/api/v2. 0 allowed-address-pairs Provides allowed address pairs 2013-03-17T12:00:00-00:00 Neutron Extra DHCP opts http://docs.openstack.org/ext/neutron/extra_dhcp_opt/api/ v1.0 extra_dhcp_opt Extra options configuration for DHCP. For example PXE boot options to DHCP clients can be specified (e.g. tftp-server, server-ip-address, bootfile-name) 2012-10-07T10:00:00-00:00 LoadBalancing service http://wiki.openstack.org/neutron/LBaaS/API_1.0 lbaas Extension for LoadBalancing service 2013-02-01T10:00:00-00:00 Neutron Extra Route http://docs.openstack.org/ext/neutron/extraroutes/api/v1. 0 extraroute Extra routes configuration for L3 router This operation does not return a response body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 33 Get extension details Method URI Description GET /v2.0/extensions/{alias} Gets detailed information for a specified extension. Normal response codes: 200, 203 Error response codes: computeFault (400, 500, …) Request This table shows the URI parameters for the get extension details request: Name Type Description {alias} String This operation does not require a request body. Response Example 3.7. Get extension details: JSON response { "extension": { "updated": "2013-02-03T10:00:00-00:00", "name": "agent", "links": [], "namespace": "http://docs.openstack.org/ext/agent/api/v2.0", "alias": "agent", "description": "The agent management extension." } } Example 3.8. Get extension details: XML response 2013-02-03T10:00:00-00:00 agent http://docs.openstack.org/ext/agent/api/v2.0 agent The agent management extension. This operation does not return a response body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 34 List networks Method URI Description GET /v2.0/networks Lists networks to which the specified tenant has access. You can control which attributes are returned by using the fields query parameter. For information, see Filtering and Column Selection in the OpenStack Networking API v2.0 Reference. Normal response codes: 200 Error response codes: unauthorized (401) Request This operation does not require a request body. Response Example 3.9. List networks: JSON response { "networks": [ { "status": "ACTIVE", "subnets": [ "54d6f61d-db07-451c-9ab3-b9609b6b6f0b" ], "name": "private-network", "provider:physical_network": null, "admin_state_up": true, "tenant_id": "4fd44f30292945e481c7b8a0c8908869", "provider:network_type": "local", "router:external": true, "shared": true, "id": "d32019d3-bc6e-4319-9c1d-6722fc136a22", "provider:segmentation_id": null }, { "status": "ACTIVE", "subnets": [ "08eae331-0402-425a-923c-34f7cfe39c1b" ], "name": "private", "provider:physical_network": null, "admin_state_up": true, "tenant_id": "26a7980765d0414dbc1fc1f88cdb7e6e", "provider:network_type": "local", "router:external": true, "shared": true, "id": "db193ab3-96e3-4cb3-8fc5-05f4296d0324", "provider:segmentation_id": null } ] } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 35 Example 3.10. List networks: XML response ACTIVE 54d6f61d-db07-451c-9ab3-b9609b6b6f0b private-network True 4fd44f30292945e481c7b8a0c8908869 local True True d32019d3-bc6e-4319-9c1d-6722fc136a22 ACTIVE 08eae331-0402-425a-923c-34f7cfe39c1b private True 26a7980765d0414dbc1fc1f88cdb7e6e local True True db193ab3-96e3-4cb3-8fc5-05f4296d0324 Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 36 Create network Method URI Description POST /v2.0/networks Creates a network. This operation does not require a request body. The tenant ID that you specify in the URI is the tenant that creates the network. An admin user can specify another tenant ID in the optional request body, which is the tenant who owns the network. Normal response codes: 201 Error response codes: badRequest (400), unauthorized (401) Request Example 3.11. Create network: JSON request { "network": { "name": "sample_network", "admin_state_up": true } } Example 3.12. Create network: XML request sample_network2 Response Example 3.13. Create network: JSON response { "network": { "status": "ACTIVE", "subnets": [], "name": "net1", "admin_state_up": true, "tenant_id": "9bacb3c5d39d41a79512987f338cf177", "segments": [ { "provider:segmentation_id": 2, "provider:physical_network": "8bab8453-1bc9-45af-8c70- f83aa9b50453", "provider:network_type": "vlan" }, { "provider:segmentation_id": null, "provider:physical_network": "8bab8453-1bc9-45af-8c70- f83aa9b50453", "provider:network_type": "stt" } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 37 ], "shared": false, "port_security_enabled": true, "id": "4e8e5957-649f-477b-9e5b-f1f75b21c03c" } } Example 3.14. Create network: XML response ACTIVE sample_network2 True 4fd44f30292945e481c7b8a0c8908869 local False c220b026-ece1-4ead-873f-83537f4c9f92 Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 38 Bulk create networks Method URI Description POST /v2.0/networks Creates multiple networks in a single request. In the request body, specify a list of networks. The bulk create operation is always atomic. Either all or no networks in the request body are created. Normal response codes: 201 Error response codes: badRequest (400), unauthorized (401) Request Example 3.15. Bulk create networks: JSON request { "networks": [ { "name": "sample_network3", "admin_state_up": true }, { "name": "sample_network4", "admin_state_up": true } ] } Example 3.16. Bulk create networks: XML request sample_network_5 sample_network_6 Response Example 3.17. Bulk create networks: JSON response { "networks": [ { "status": "ACTIVE", "subnets": [], "name": "sample_network3", "provider:physical_network": null, "admin_state_up": true, Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 39 "tenant_id": "4fd44f30292945e481c7b8a0c8908869", "provider:network_type": "local", "shared": false, "id": "bc1a76cb-8767-4c3a-bb95-018b822f2130", "provider:segmentation_id": null }, { "status": "ACTIVE", "subnets": [], "name": "sample_network4", "provider:physical_network": null, "admin_state_up": true, "tenant_id": "4fd44f30292945e481c7b8a0c8908869", "provider:network_type": "local", "shared": false, "id": "af374017-c9ae-4a1d-b799-ab73111476e2", "provider:segmentation_id": null } ] } Example 3.18. Bulk create networks: XML response ACTIVE sample_network_5 True 4fd44f30292945e481c7b8a0c8908869 local False 1f370095-98f6-4079-be64-6d3d4a6adcc6 ACTIVE sample_network_6 True 4fd44f30292945e481c7b8a0c8908869 local False ee2d3158-3e80-4fb3-ba87-c99f515d85e7 Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 40 Show network Method URI Description GET /v2.0/networks/{network_id} Shows information for a specified network. You can control which attributes are returned by using the fields query parameter. For information, see Filtering and Column Selection in the OpenStack Networking API v2.0 Reference. Normal response codes: 200 Error response codes: unauthorized (401), itemNotFound (404) Request This table shows the URI parameters for the show network request: Name Type Description {network_id} UUID The UUID for the network of interest to you. This operation does not require a request body. Response Example 3.19. Show network: JSON response { "network": { "status": "ACTIVE", "subnets": [ "54d6f61d-db07-451c-9ab3-b9609b6b6f0b" ], "name": "private-network", "provider:physical_network": null, "admin_state_up": true, "tenant_id": "4fd44f30292945e481c7b8a0c8908869", "provider:network_type": "local", "router:external": true, "shared": true, "id": "d32019d3-bc6e-4319-9c1d-6722fc136a22", "provider:segmentation_id": null } } Example 3.20. Show network: XML response ACTIVE Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 41 54d6f61d-db07-451c-9ab3-b9609b6b6f0b private-network True 4fd44f30292945e481c7b8a0c8908869 local True True d32019d3-bc6e-4319-9c1d-6722fc136a22 Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 42 Update network Method URI Description PUT /v2.0/networks/{network_id} Updates a specified network. Normal response codes: 200 Error response codes: badRequest (400), unauthorized (401), forbidden (403), itemNotFound (404) Request This table shows the URI parameters for the update network request: Name Type Description {network_id} UUID The UUID for the network of interest to you. Example 3.21. Update network: JSON request { "network": { "name": "sample_network_5_updated" } } Example 3.22. Update network: XML request sample-network-4-updated Response Example 3.23. Update network: JSON response { "network": { "status": "ACTIVE", "subnets": [], "name": "sample_network_5_updated", "provider:physical_network": null, "admin_state_up": true, "tenant_id": "4fd44f30292945e481c7b8a0c8908869", "provider:network_type": "local", "router:external": false, "shared": false, "id": "1f370095-98f6-4079-be64-6d3d4a6adcc6", "provider:segmentation_id": null } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 43 } Example 3.24. Update network: XML response ACTIVE sample-network-4-updated True 4fd44f30292945e481c7b8a0c8908869 local False False af374017-c9ae-4a1d-b799-ab73111476e2 Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 44 Delete network Method URI Description DELETE /v2.0/networks/{network_id} Deletes a specified network and its associated resources. Normal response codes: 204 Error response codes: unauthorized (401), itemNotFound (404), conflict (409) Request This table shows the URI parameters for the delete network request: Name Type Description {network_id} UUID The UUID for the network of interest to you. This operation does not require a request body. Subnets List, show information for, create, update, and delete subnet resources. Method URI Description GET /v2.0/subnets Lists subnets to which the specified tenant has access. POST /v2.0/subnets Creates a subnet on a specified network. POST /v2.0/subnets Creates multiple subnets in a single request. Specify a list of subnets in the request body. GET /v2.0/subnets/{subnet_id} Shows information for a specified subnet. PUT /v2.0/subnets/{subnet_id} Updates a specified subnet. DELETE /v2.0/subnets/{subnet_id} Deletes a specified subnet. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 45 List subnets Method URI Description GET /v2.0/subnets Lists subnets to which the specified tenant has access. Default policy settings returns exclusively subnets owned by the tenant submitting the request, unless the request is submitted by an user with administrative rights. You can control which attributes are returned by using the fields query parameter. You can filter results by using query string parameters. For information, see Filtering and Column Selection in the OpenStack Networking API v2.0 Reference. Normal response codes: 200 Error response codes: unauthorized (401) Request This operation does not require a request body. Response Example 3.25. List subnets: JSON response { "subnets": [ { "name": "private-subnet", "enable_dhcp": true, "network_id": "db193ab3-96e3-4cb3-8fc5-05f4296d0324", "tenant_id": "26a7980765d0414dbc1fc1f88cdb7e6e", "dns_nameservers": [], "allocation_pools": [ { "start": "10.0.0.2", "end": "10.0.0.254" } ], "host_routes": [], "ip_version": 4, "gateway_ip": "10.0.0.1", "cidr": "10.0.0.0/24", "id": "08eae331-0402-425a-923c-34f7cfe39c1b" }, { "name": "my_subnet", "enable_dhcp": true, "network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22", "tenant_id": "4fd44f30292945e481c7b8a0c8908869", "dns_nameservers": [], "allocation_pools": [ { "start": "192.0.0.2", "end": "192.255.255.254" } ], Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 46 "host_routes": [], "ip_version": 4, "gateway_ip": "192.0.0.1", "cidr": "192.0.0.0/8", "id": "54d6f61d-db07-451c-9ab3-b9609b6b6f0b" } ] } Example 3.26. List subnets: XML response private-subnet True db193ab3-96e3-4cb3-8fc5-05f4296d0324 26a7980765d0414dbc1fc1f88cdb7e6e 10.0.0.2 10.0.0.254 4 10.0.0.1 10.0.0.0/24 08eae331-0402-425a-923c-34f7cfe39c1b my_subnet True d32019d3-bc6e-4319-9c1d-6722fc136a22 4fd44f30292945e481c7b8a0c8908869 192.0.0.2 192.255.255.254 4 192.0.0.1 192.0.0.0/8 54d6f61d-db07-451c-9ab3-b9609b6b6f0b This operation does not return a response body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 47 Create subnet Method URI Description POST /v2.0/subnets Creates a subnet on a specified network. By default, OpenStack Networking creates IP v4 subnets. To create an IP v6 subnet, you must specify the value 6 for the ip_version attribute in the request body. OpenStack Networking does not try to derive the correct IP version from the provided CIDR. If the parameter for the gateway address, gateway_ip, is not specified, OpenStack Networking allocates an address from the cidr for the gateway for the subnet. To specify a subnet without a gateway, specify the value null for the gateway_ip attribute in the request body. If allocation pools attribute, allocation_pools, is not specified, OpenStack Networking automatically allocates pools for covering all IP addresses in the CIDR, excluding the address reserved for the subnet gateway. Otherwise, you can explicitly specify allocation pools as shown in the following example. When allocation_pools and gateway_ip are both specified, it is up to the user to ensure that the gateway IP does not overlap with the specified allocation pools; otherwise a 409 Conflict error occurs. Normal response codes: 201 Error response codes: badRequest (400), unauthorized (401), forbidden (403), itemNotFound (404), conflict (409) Request Example 3.27. Create subnet: JSON request { "subnet": { "subnet": { "network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22", "ip_version": 4, "cidr": "192.168.199.0/24" } } } Example 3.28. Create subnet: XML request test_subnet_1 d32019d3-bc6e-4319-9c1d-6722fc136a22 192.0.0.0/8 4 This operation does not require a request body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 48 Response Example 3.29. Create subnet: JSON response { "subnet": { "name": "", "enable_dhcp": true, "network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22", "tenant_id": "4fd44f30292945e481c7b8a0c8908869", "dns_nameservers": [], "allocation_pools": [ { "start": "192.168.199.2", "end": "192.168.199.254" } ], "host_routes": [], "ip_version": 4, "gateway_ip": "192.168.199.1", "cidr": "192.168.199.0/24", "id": "3b80198d-4f7b-4f77-9ef5-774d54e17126" } } Example 3.30. Create subnet: XML response test_subnet_1 True d32019d3-bc6e-4319-9c1d-6722fc136a22 4fd44f30292945e481c7b8a0c8908869 192.0.0.2 192.255.255.254 4 192.0.0.1 192.0.0.0/8 54d6f61d-db07-451c-9ab3-b9609b6b6f0b This operation does not return a response body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 49 Bulk create subnet Method URI Description POST /v2.0/subnets Creates multiple subnets in a single request. Specify a list of subnets in the request body. The bulk create operation is always atomic. Either all or no subnets in the request body are created. Normal response codes: 201 Error response codes: badRequest (400), unauthorized (401), forbidden (403), itemNotFound (404), conflict (409) Request Example 3.31. Bulk create subnet: JSON request { "subnets": [ { "cidr": "192.168.199.0/24", "ip_version": 4, "network_id": "e6031bc2-901a-4c66-82da-f4c32ed89406" }, { "cidr": "10.56.4.0/22", "ip_version": 4, "network_id": "64239a54-dcc4-4b39-920b-b37c2144effa" } ] } Example 3.32. Bulk create subnet: XML request test_subnet_1 a3775a7d-9f8b-4148-be81-c84bbd0837ce 10.0.0.0/8 4 test_subnet_2 a3775a7d-9f8b-4148-be81-c84bbd0837ce 192.168.0.0/16 4 This operation does not require a request body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 50 Response Example 3.33. Bulk create subnet: JSON response { "subnets": [ { "allocation_pools": [ { "end": "192.168.199.254", "start": "192.168.199.2" } ], "cidr": "192.168.199.0/24", "dns_nameservers": [], "enable_dhcp": true, "gateway_ip": "192.168.199.1", "host_routes": [], "id": "0468a7a7-290d-4127-aedd-6c9449775a24", "ip_version": 4, "name": "", "network_id": "e6031bc2-901a-4c66-82da-f4c32ed89406", "tenant_id": "d19231fc08ec4bc4829b668040d34512" }, { "allocation_pools": [ { "end": "10.56.7.254", "start": "10.56.4.2" } ], "cidr": "10.56.4.0/22", "dns_nameservers": [], "enable_dhcp": true, "gateway_ip": "10.56.4.1", "host_routes": [], "id": "b0e7435c-1512-45fb-aa9e-9a7c5932fb30", "ip_version": 4, "name": "", "network_id": "64239a54-dcc4-4b39-920b-b37c2144effa", "tenant_id": "d19231fc08ec4bc4829b668040d34512" } ] } Example 3.34. Bulk create subnet: XML response test_subnet_1 True a3775a7d-9f8b-4148-be81-c84bbd0837ce 60cd4f6dbc2f491982a284e7b83b5be3 Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 51 10.0.0.2 10.255.255.254 4 10.0.0.1 10.0.0.0/8 bd3fd365-fe19-431a-be63-07017a09316c test_subnet_2 True a3775a7d-9f8b-4148-be81-c84bbd0837ce 60cd4f6dbc2f491982a284e7b83b5be3 192.168.0.2 192.168.255.254 4 192.168.0.1 192.168.0.0/16 86e7c838-fb75-402b-9dbf-d68166e3f5fe This operation does not return a response body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 52 Show subnet Method URI Description GET /v2.0/subnets/{subnet_id} Shows information for a specified subnet. You can control which attributes are returned by using the fields query parameter. For information, see Filtering and Column Selection in the OpenStack Networking API v2.0 Reference. Normal response codes: 201 Error response codes: unauthorized (401), itemNotFound (404) Request This table shows the URI parameters for the show subnet request: Name Type Description {subnet_id} UUID The UUID for the subnet of interest to you. This operation does not require a request body. Response Example 3.35. Show subnet: JSON response { "subnet": { "name": "my_subnet", "enable_dhcp": true, "network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22", "tenant_id": "4fd44f30292945e481c7b8a0c8908869", "dns_nameservers": [], "allocation_pools": [ { "start": "192.0.0.2", "end": "192.255.255.254" } ], "host_routes": [], "ip_version": 4, "gateway_ip": "192.0.0.1", "cidr": "192.0.0.0/8", "id": "54d6f61d-db07-451c-9ab3-b9609b6b6f0b" } } Example 3.36. Show subnet: XML response test_subnet_1 Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 53 True d32019d3-bc6e-4319-9c1d-6722fc136a22 4fd44f30292945e481c7b8a0c8908869 192.0.0.2 192.255.255.254 4 192.0.0.1 192.0.0.0/8 54d6f61d-db07-451c-9ab3-b9609b6b6f0b This operation does not return a response body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 54 Update subnet Method URI Description PUT /v2.0/subnets/{subnet_id} Updates a specified subnet. Some attributes, such as IP version (ip_version), CIDR (cidr), and IP allocation pools (allocation_pools) cannot be updated. Attempting to update these attributes results in a 400 Bad Request error. Normal response codes: 201 Error response codes: badRequest (400), unauthorized (401), forbidden (403), itemNotFound (404) Request This table shows the URI parameters for the update subnet request: Name Type Description {subnet_id} UUID The UUID for the subnet of interest to you. Example 3.37. Update subnet: JSON request { "subnet": { "subnet": { "name": "my_subnet" } } } Example 3.38. Update subnet: XML request my_subnet This operation does not require a request body. Response Example 3.39. Update subnet: JSON response { "subnet": { "name": "private-subnet", "enable_dhcp": true, "network_id": "db193ab3-96e3-4cb3-8fc5-05f4296d0324", "tenant_id": "26a7980765d0414dbc1fc1f88cdb7e6e", "dns_nameservers": [], "allocation_pools": [ { "start": "10.0.0.2", Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 55 "end": "10.0.0.254" } ], "host_routes": [], "ip_version": 4, "gateway_ip": "10.0.0.1", "cidr": "10.0.0.0/24", "id": "08eae331-0402-425a-923c-34f7cfe39c1b" } } Example 3.40. Update subnet: XML response my_subnet True d32019d3-bc6e-4319-9c1d-6722fc136a22 4fd44f30292945e481c7b8a0c8908869 192.0.0.2 192.255.255.254 4 192.0.0.1 192.0.0.0/8 54d6f61d-db07-451c-9ab3-b9609b6b6f0b This operation does not return a response body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 56 Delete subnet Method URI Description DELETE /v2.0/subnets/{subnet_id} Deletes a specified subnet. The operation fails if subnet IP addresses are still allocated. Normal response codes: 204 Error response codes: unauthorized (401), itemNotFound (404), conflict (409) Request This table shows the URI parameters for the delete subnet request: Name Type Description {subnet_id} UUID The UUID for the subnet of interest to you. This operation does not require a request body. Ports List, show information for, create, update, and delete ports. Method URI Description GET /v2.0/ports Lists ports to which the tenant has access. POST /v2.0/ports Creates a port on a specified network. POST /v2.0/ports Creates multiple ports in a single request. Specify a list of ports in the request body. GET /v2.0/ports/{port_id} Shows information for a specified port. PUT /v2.0/ports/{port_id} Updates a specified port. DELETE /v2.0/ports/{port_id} Deletes a specified port. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 57 List ports Method URI Description GET /v2.0/ports Lists ports to which the tenant has access. Default policy settings return only those subnets that are owned by the tenant who submits the request, unless the request is submitted by an user with administrative rights. Users can control which attributes are returned by using the fields query parameter. Additionally, you can filter results by using query string parameters. For information, see Filtering and Column Selection in the OpenStack Networking API v2.0 Reference. Normal response codes: 200 Error response codes: unauthorized (401) Request This operation does not require a request body. Response Example 3.41. List ports: JSON response { "ports": [ { "status": "ACTIVE", "binding:host_id": "devstack", "name": "", "allowed_address_pairs": [], "admin_state_up": true, "network_id": "70c1db1f-b701-45bd-96e0-a313ee3430b3", "tenant_id": "", "extra_dhcp_opts": [], "binding:vif_details": { "port_filter": true, "ovs_hybrid_plug": true }, "binding:vif_type": "ovs", "device_owner": "network:router_gateway", "mac_address": "fa:16:3e:58:42:ed", "binding:profile": {}, "binding:vnic_type": "normal", "fixed_ips": [ { "subnet_id": "008ba151-0b8c-4a67-98b5-0d2b87666062", "ip_address": "172.24.4.2" } ], "id": "d80b1a3b-4fc1-49f3-952e-1e2ab7081d8b", "security_groups": [], "device_id": "9ae135f4-b6e0-4dad-9e91-3c223e385824" }, { "status": "ACTIVE", Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 58 "binding:host_id": "devstack", "name": "", "allowed_address_pairs": [], "admin_state_up": true, "network_id": "f27aa545-cbdd-4907-b0c6-c9e8b039dcc2", "tenant_id": "d397de8a63f341818f198abb0966f6f3", "extra_dhcp_opts": [], "binding:vif_details": { "port_filter": true, "ovs_hybrid_plug": true }, "binding:vif_type": "ovs", "device_owner": "network:router_interface", "mac_address": "fa:16:3e:bb:3c:e4", "binding:profile": {}, "binding:vnic_type": "normal", "fixed_ips": [ { "subnet_id": "288bf4a1-51ba-43b6-9d0a-520e9005db17", "ip_address": "10.0.0.1" } ], "id": "f71a6703-d6de-4be1-a91a-a570ede1d159", "security_groups": [], "device_id": "9ae135f4-b6e0-4dad-9e91-3c223e385824" } ] } Example 3.42. List ports: XML response ACTIVE devstack True 70c1db1f-b701-45bd-96e0-a313ee3430b3 True True ovs network:router_gateway fa:16:3e:58:42:ed normal 008ba151-0b8c-4a67-98b5-0d2b87666062 172.24.4.2 Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 59 d80b1a3b-4fc1-49f3-952e-1e2ab7081d8b 9ae135f4-b6e0-4dad-9e91-3c223e385824 ACTIVE devstack True f27aa545-cbdd-4907-b0c6-c9e8b039dcc2 d397de8a63f341818f198abb0966f6f3 True True ovs network:router_interface fa:16:3e:bb:3c:e4 normal 288bf4a1-51ba-43b6-9d0a-520e9005db17 10.0.0.1 f71a6703-d6de-4be1-a91a-a570ede1d159 9ae135f4-b6e0-4dad-9e91-3c223e385824 This operation does not return a response body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 60 Create port Method URI Description POST /v2.0/ports Creates a port on a specified network. You must specify the network where the port is to created in the network_id attribute in the request body. Normal response codes: 201 Error response codes: badRequest (400), unauthorized (401), forbidden (403), itemNotFound (404), macGenerationFailure (503), serviceUnavailable (503) Request Example 3.43. Create port: JSON request { "port": { "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7", "name": "private-port", "admin_state_up": true } } Example 3.44. Create port: JSON request test_port_1 a87cc70a-3e15-4acf-8205-9b711a3531b7 This operation does not require a request body. Response Example 3.45. Create port: JSON response { "port": { "status": "DOWN", "binding:host_id": "", "name": "private-port", "allowed_address_pairs": [], "admin_state_up": true, "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7", "tenant_id": "d6700c0c9ffa4f1cb322cd4a1f3906fa", "binding:vif_details": {}, "binding:vnic_type": "normal", "binding:vif_type": "unbound", "device_owner": "", "mac_address": "fa:16:3e:c9:cb:f0", "binding:profile": {}, "fixed_ips": [ Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 61 { "subnet_id": "a0304c3a-4f08-4c43-88af-d796509c97d2", "ip_address": "10.0.0.2" } ], "id": "65c0ee9f-d634-4522-8954-51021b570b0d", "security_groups": [ "f0ac4394-7e4a-4409-9701-ba8be283dbc3" ], "device_id": "" } } Example 3.46. Create port: XML response DOWN test_port_1 True a87cc70a-3e15-4acf-8205-9b711a3531b7 d6700c0c9ffa4f1cb322cd4a1f3906fa normal unbound fa:16:3e:09:e3:47 a0304c3a-4f08-4c43-88af-d796509c97d2 10.0.0.4 8021790b-4bfd-46ab-bcc7-0ef2f73bff43 f0ac4394-7e4a-4409-9701-ba8be283dbc3 This operation does not return a response body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 62 Bulk create ports Method URI Description POST /v2.0/ports Creates multiple ports in a single request. Specify a list of ports in the request body. Guarantees the atomic completion of the bulk operation. Normal response codes: 201 Error response codes: badRequest (400), unauthorized (401), forbidden (403), itemNotFound (404), conflict (409), macGenerationFailure (503) Request Example 3.47. Bulk create ports: JSON request { "ports": [ { "name": "sample_port_1", "admin_state_up": false, "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7" }, { "name": "sample_port_2", "admin_state_up": false, "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7" } ] } Example 3.48. Bulk create ports: XML request test_port_1-xml a87cc70a-3e15-4acf-8205-9b711a3531b7 test_port_2-xml a87cc70a-3e15-4acf-8205-9b711a3531b7 This operation does not require a request body. Response Example 3.49. Bulk create ports: JSON response { "ports": [ { Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 63 "status": "DOWN", "binding:host_id": "", "name": "sample_port_1", "allowed_address_pairs": [], "admin_state_up": false, "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7", "tenant_id": "d6700c0c9ffa4f1cb322cd4a1f3906fa", "binding:vif_details": {}, "binding:vnic_type": "normal", "binding:vif_type": "unbound", "device_owner": "", "mac_address": "fa:16:3e:48:b8:9f", "binding:profile": {}, "fixed_ips": [ { "subnet_id": "a0304c3a-4f08-4c43-88af-d796509c97d2", "ip_address": "10.0.0.5" } ], "id": "94225baa-9d3f-4b93-bf12-b41e7ce49cdb", "security_groups": [ "f0ac4394-7e4a-4409-9701-ba8be283dbc3" ], "device_id": "" }, { "status": "DOWN", "binding:host_id": "", "name": "sample_port_2", "allowed_address_pairs": [], "admin_state_up": false, "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7", "tenant_id": "d6700c0c9ffa4f1cb322cd4a1f3906fa", "binding:vif_details": {}, "binding:vnic_type": "normal", "binding:vif_type": "unbound", "device_owner": "", "mac_address": "fa:16:3e:f4:73:df", "binding:profile": {}, "fixed_ips": [ { "subnet_id": "a0304c3a-4f08-4c43-88af-d796509c97d2", "ip_address": "10.0.0.6" } ], "id": "235b09e0-63c4-47f1-b221-66ba54c21760", "security_groups": [ "f0ac4394-7e4a-4409-9701-ba8be283dbc3" ], "device_id": "" } ] } Example 3.50. Bulk create ports: XML response DOWN test_port_1-xml True a87cc70a-3e15-4acf-8205-9b711a3531b7 d6700c0c9ffa4f1cb322cd4a1f3906fa normal unbound fa:16:3e:fa:e2:34 a0304c3a-4f08-4c43-88af-d796509c97d2 10.0.0.7 054e8f14-4082-400e-afcc-5d6e5b3bcc0c f0ac4394-7e4a-4409-9701-ba8be283dbc3 DOWN test_port_2-xml True a87cc70a-3e15-4acf-8205-9b711a3531b7 d6700c0c9ffa4f1cb322cd4a1f3906fa normal unbound fa:16:3e:e6:cf:d9 a0304c3a-4f08-4c43-88af-d796509c97d2 10.0.0.8 879e96f9-6dd5-4232-bd19-3f39d0ae463b f0ac4394-7e4a-4409-9701-ba8be283dbc3 This operation does not return a response body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 65 Show port Method URI Description GET /v2.0/ports/{port_id} Shows information for a specified port. Normal response codes: 200 Error response codes: unauthorized (401), itemNotFound (404) Request This table shows the URI parameters for the show port request: Name Type Description {port_id} UUID The UUID for the port of interest to you. This operation does not require a request body. Response Example 3.51. Show port: JSON response { "port": { "status": "ACTIVE", "binding:host_id": "devstack", "name": "", "allowed_address_pairs": [], "admin_state_up": true, "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7", "tenant_id": "7e02058126cc4950b75f9970368ba177", "extra_dhcp_opts": [], "binding:vif_details": { "port_filter": true, "ovs_hybrid_plug": true }, "binding:vif_type": "ovs", "device_owner": "network:router_interface", "mac_address": "fa:16:3e:23:fd:d7", "binding:profile": {}, "binding:vnic_type": "normal", "fixed_ips": [ { "subnet_id": "a0304c3a-4f08-4c43-88af-d796509c97d2", "ip_address": "10.0.0.1" } ], "id": "46d4bfb9-b26e-41f3-bd2e-e6dcc1ccedb2", "security_groups": [], "device_id": "5e3898d7-11be-483e-9732-b2f5eccd2b2e" } } Example 3.52. Show port: XML response Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 66 ACTIVE devstack True a87cc70a-3e15-4acf-8205-9b711a3531b7 7e02058126cc4950b75f9970368ba177 True True ovs network:router_interface fa:16:3e:23:fd:d7 normal a0304c3a-4f08-4c43-88af-d796509c97d2 10.0.0.1 46d4bfb9-b26e-41f3-bd2e-e6dcc1ccedb2 5e3898d7-11be-483e-9732-b2f5eccd2b2e This operation does not return a response body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 67 Update port Method URI Description PUT /v2.0/ports/{port_id} Updates a specified port. You can update information for a port, such as its symbolic name and associated IPs. When you update IPs for a port, any previously associated IPs are removed, returned to the respective subnets allocation pools, and replaced by the IPs specified in the body for the update request. Therefore, this operation replaces the fixed_ip attribute when it is specified in the request body. If the updated IP addresses are not valid or are already in use, the operation fails and the existing IP addresses are not removed from the port. When you update security groups for a port and the operation succeeds, any associated security groups are removed and replaced by the security groups specified in the body for the update request. Therefore, this operation replaces the security_groups attribute when you specify it in the request body. However, if the specified security groups are not valid, the operation fails and the existing security groups are not removed from the port. Normal response codes: 200 Error response codes: badRequest (400), unauthorized (401), forbidden (403), itemNotFound (404), conflict (409) Request This table shows the URI parameters for the update port request: Name Type Description {port_id} UUID The UUID for the port of interest to you. Example 3.53. Update port: JSON request { "port": { "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7", "name": "private-port", "admin_state_up": true } } Example 3.54. Update port: JSON request test_port_1 a87cc70a-3e15-4acf-8205-9b711a3531b7 This operation does not require a request body. Response Example 3.55. Update port: JSON response { Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 68 "port": { "status": "DOWN", "binding:host_id": "", "name": "private-port", "allowed_address_pairs": [], "admin_state_up": true, "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7", "tenant_id": "d6700c0c9ffa4f1cb322cd4a1f3906fa", "binding:vif_details": {}, "binding:vnic_type": "normal", "binding:vif_type": "unbound", "device_owner": "", "mac_address": "fa:16:3e:c9:cb:f0", "binding:profile": {}, "fixed_ips": [ { "subnet_id": "a0304c3a-4f08-4c43-88af-d796509c97d2", "ip_address": "10.0.0.2" } ], "id": "65c0ee9f-d634-4522-8954-51021b570b0d", "security_groups": [ "f0ac4394-7e4a-4409-9701-ba8be283dbc3" ], "device_id": "" } } Example 3.56. Update port: XML response DOWN test_port_1 True a87cc70a-3e15-4acf-8205-9b711a3531b7 d6700c0c9ffa4f1cb322cd4a1f3906fa normal unbound fa:16:3e:09:e3:47 a0304c3a-4f08-4c43-88af-d796509c97d2 10.0.0.4 8021790b-4bfd-46ab-bcc7-0ef2f73bff43 f0ac4394-7e4a-4409-9701-ba8be283dbc3 Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 69 This operation does not return a response body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 70 Delete port Method URI Description DELETE /v2.0/ports/{port_id} Deletes a specified port. Any IP addresses that are associated with the port are returned to the respective subnets allocation pools. Normal response codes: 204 Error response codes: unauthorized (401), forbidden (403), itemNotFound (404) Request This table shows the URI parameters for the delete port request: Name Type Description {port_id} UUID The UUID for the port of interest to you. This operation does not require a request body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 71 4. API extensions Get extension information ............................................................................................. 71 Agent management ...................................................................................................... 78 Agent schedulers ........................................................................................................... 83 Allowed address pairs ................................................................................................... 92 The binding Extended Attributes for Ports .................................................................. 95 Configurable external gateway modes .......................................................................... 99 External networks (external-net) ........................................................................... 104 Extra routes ................................................................................................................. 107 Firewall as a Service (FWaaS) ....................................................................................... 109 Layer-3 networking (router) ..................................................................................... 126 Load Balancer as a Service (LBaaS) .............................................................................. 142 Metering labels and rules ............................................................................................ 169 Provider networks (provider) ................................................................................... 180 Multiple provider networks ......................................................................................... 190 Quotas ........................................................................................................................ 195 Security groups and rules (security-groups) .................................................................. 200 Virtual Private Network as a Service (VPNaaS) ............................................................. 212 Extra DHCP options (extra-dhcp-opt) .................................................................... 234 An API extension extends one or more of the following components of the core API: • Resources. An extension creates object classes. • Attributes. An extended attribute creates an attribute on existing resources. Prefixed by the extension name. • Actions. An extended action creates an operation on an existing resource. Generic API extensions are not plug-in-specific. For information about plug-in-specific extensions that ship with OpenStack Networking, see the extension documentation in the source code tree. Get extension information List available extensions and show details for a specified extension. Method URI Description GET /v2.0/extensions Lists available Networking API extensions. GET /v2.0/extensions/{alias} Gets detailed information for a specified extension. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 72 List extensions Method URI Description GET /v2.0/extensions Lists available Networking API extensions. Normal response codes: 200, 203 Error response codes: computeFault (400, 500, …) Request This operation does not require a request body. Response Example 4.1. List extensions: JSON response { "extensions": [ { "updated": "2013-01-20T00:00:00-00:00", "name": "Neutron Service Type Management", "links": [], "namespace": "http://docs.openstack.org/ext/neutron/service-type/ api/v1.0", "alias": "service-type", "description": "API for retrieving service providers for Neutron advanced services" }, { "updated": "2012-10-05T10:00:00-00:00", "name": "security-group", "links": [], "namespace": "http://docs.openstack.org/ext/securitygroups/api/v2. 0", "alias": "security-group", "description": "The security groups extension." }, { "updated": "2013-02-07T10:00:00-00:00", "name": "L3 Agent Scheduler", "links": [], "namespace": "http://docs.openstack.org/ext/l3_agent_scheduler/ api/v1.0", "alias": "l3_agent_scheduler", "description": "Schedule routers among l3 agents" }, { "updated": "2013-02-07T10:00:00-00:00", "name": "Loadbalancer Agent Scheduler", "links": [], "namespace": "http://docs.openstack.org/ext/lbaas_agent_scheduler/ api/v1.0", "alias": "lbaas_agent_scheduler", "description": "Schedule pools among lbaas agents" }, { Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 73 "updated": "2013-03-28T10:00:00-00:00", "name": "Neutron L3 Configurable external gateway mode", "links": [], "namespace": "http://docs.openstack.org/ext/neutron/ext-gw-mode/ api/v1.0", "alias": "ext-gw-mode", "description": "Extension of the router abstraction for specifying whether SNAT should occur on the external gateway" }, { "updated": "2014-02-03T10:00:00-00:00", "name": "Port Binding", "links": [], "namespace": "http://docs.openstack.org/ext/binding/api/v1.0", "alias": "binding", "description": "Expose port bindings of a virtual port to external application" }, { "updated": "2012-09-07T10:00:00-00:00", "name": "Provider Network", "links": [], "namespace": "http://docs.openstack.org/ext/provider/api/v1.0", "alias": "provider", "description": "Expose mapping of virtual networks to physical networks" }, { "updated": "2013-02-03T10:00:00-00:00", "name": "agent", "links": [], "namespace": "http://docs.openstack.org/ext/agent/api/v2.0", "alias": "agent", "description": "The agent management extension." }, { "updated": "2012-07-29T10:00:00-00:00", "name": "Quota management support", "links": [], "namespace": "http://docs.openstack.org/network/ext/quotas-sets/ api/v2.0", "alias": "quotas", "description": "Expose functions for quotas management per tenant" }, { "updated": "2013-02-07T10:00:00-00:00", "name": "DHCP Agent Scheduler", "links": [], "namespace": "http://docs.openstack.org/ext/dhcp_agent_scheduler/ api/v1.0", "alias": "dhcp_agent_scheduler", "description": "Schedule networks among dhcp agents" }, { "updated": "2013-06-27T10:00:00-00:00", "name": "Multi Provider Network", "links": [], "namespace": "http://docs.openstack.org/ext/multi-provider/api/v1. 0", "alias": "multi-provider", Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 74 "description": "Expose mapping of virtual networks to multiple physical networks" }, { "updated": "2013-01-14T10:00:00-00:00", "name": "Neutron external network", "links": [], "namespace": "http://docs.openstack.org/ext/neutron/external_net/ api/v1.0", "alias": "external-net", "description": "Adds external network attribute to network resource." }, { "updated": "2012-07-20T10:00:00-00:00", "name": "Neutron L3 Router", "links": [], "namespace": "http://docs.openstack.org/ext/neutron/router/api/v1. 0", "alias": "router", "description": "Router abstraction for basic L3 forwarding between L2 Neutron networks and access to external networks via a NAT gateway." }, { "updated": "2013-07-23T10:00:00-00:00", "name": "Allowed Address Pairs", "links": [], "namespace": "http://docs.openstack.org/ext/allowedaddresspairs/ api/v2.0", "alias": "allowed-address-pairs", "description": "Provides allowed address pairs" }, { "updated": "2013-03-17T12:00:00-00:00", "name": "Neutron Extra DHCP opts", "links": [], "namespace": "http://docs.openstack.org/ext/neutron/ extra_dhcp_opt/api/v1.0", "alias": "extra_dhcp_opt", "description": "Extra options configuration for DHCP. For example PXE boot options to DHCP clients can be specified (e.g. tftp-server, server- ip-address, bootfile-name)" }, { "updated": "2012-10-07T10:00:00-00:00", "name": "LoadBalancing service", "links": [], "namespace": "http://wiki.openstack.org/neutron/LBaaS/API_1.0", "alias": "lbaas", "description": "Extension for LoadBalancing service" }, { "updated": "2013-02-01T10:00:00-00:00", "name": "Neutron Extra Route", "links": [], "namespace": "http://docs.openstack.org/ext/neutron/extraroutes/ api/v1.0", "alias": "extraroute", "description": "Extra routes configuration for L3 router" } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 75 ] } Example 4.2. List extensions: XML response 2013-01-20T00:00:00-00:00 Neutron Service Type Management http://docs.openstack.org/ext/neutron/service-type/api/v1. 0 service-type API for retrieving service providers for Neutron advanced services 2012-10-05T10:00:00-00:00 security-group http://docs.openstack.org/ext/securitygroups/api/v2.0 security-group The security groups extension. 2013-02-07T10:00:00-00:00 L3 Agent Scheduler http://docs.openstack.org/ext/l3_agent_scheduler/api/v1.0 l3_agent_scheduler Schedule routers among l3 agents 2013-02-07T10:00:00-00:00 Loadbalancer Agent Scheduler http://docs.openstack.org/ext/lbaas_agent_scheduler/api/v1. 0 lbaas_agent_scheduler Schedule pools among lbaas agents 2013-03-28T10:00:00-00:00 Neutron L3 Configurable external gateway mode http://docs.openstack.org/ext/neutron/ext-gw-mode/api/v1. 0 ext-gw-mode Extension of the router abstraction for specifying whether SNAT should occur on the external gateway 2014-02-03T10:00:00-00:00 Port Binding Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 76 http://docs.openstack.org/ext/binding/api/v1.0 binding Expose port bindings of a virtual port to external application 2012-09-07T10:00:00-00:00 Provider Network http://docs.openstack.org/ext/provider/api/v1.0 provider Expose mapping of virtual networks to physical networks 2013-02-03T10:00:00-00:00 agent http://docs.openstack.org/ext/agent/api/v2.0 agent The agent management extension. 2012-07-29T10:00:00-00:00 Quota management support http://docs.openstack.org/network/ext/quotas-sets/api/v2. 0 quotas Expose functions for quotas management per tenant 2013-02-07T10:00:00-00:00 DHCP Agent Scheduler http://docs.openstack.org/ext/dhcp_agent_scheduler/api/v1. 0 dhcp_agent_scheduler Schedule networks among dhcp agents 2013-06-27T10:00:00-00:00 Multi Provider Network http://docs.openstack.org/ext/multi-provider/api/v1.0 multi-provider Expose mapping of virtual networks to multiple physical networks 2013-01-14T10:00:00-00:00 Neutron external network http://docs.openstack.org/ext/neutron/external_net/api/v1. 0 external-net Adds external network attribute to network Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 77 resource. 2012-07-20T10:00:00-00:00 Neutron L3 Router http://docs.openstack.org/ext/neutron/router/api/v1.0 router Router abstraction for basic L3 forwarding between L2 Neutron networks and access to external networks via a NAT gateway. 2013-07-23T10:00:00-00:00 Allowed Address Pairs http://docs.openstack.org/ext/allowedaddresspairs/api/v2. 0 allowed-address-pairs Provides allowed address pairs 2013-03-17T12:00:00-00:00 Neutron Extra DHCP opts http://docs.openstack.org/ext/neutron/extra_dhcp_opt/api/ v1.0 extra_dhcp_opt Extra options configuration for DHCP. For example PXE boot options to DHCP clients can be specified (e.g. tftp-server, server-ip-address, bootfile-name) 2012-10-07T10:00:00-00:00 LoadBalancing service http://wiki.openstack.org/neutron/LBaaS/API_1.0 lbaas Extension for LoadBalancing service 2013-02-01T10:00:00-00:00 Neutron Extra Route http://docs.openstack.org/ext/neutron/extraroutes/api/v1. 0 extraroute Extra routes configuration for L3 router This operation does not return a response body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 78 Get extension details Method URI Description GET /v2.0/extensions/{alias} Gets detailed information for a specified extension. Normal response codes: 200, 203 Error response codes: computeFault (400, 500, …) Request This table shows the URI parameters for the get extension details request: Name Type Description {alias} String This operation does not require a request body. Response Example 4.3. Get extension details: JSON response { "extension": { "updated": "2013-02-03T10:00:00-00:00", "name": "agent", "links": [], "namespace": "http://docs.openstack.org/ext/agent/api/v2.0", "alias": "agent", "description": "The agent management extension." } } Example 4.4. Get extension details: XML response 2013-02-03T10:00:00-00:00 agent http://docs.openstack.org/ext/agent/api/v2.0 agent The agent management extension. This operation does not return a response body. Agent management In a typical OpenStack Networking deployment, some agents run on network or compute nodes, such as neutron-dhcp-agent, neutron-ovs-agent, and neutron-l3- Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 79 agent. This extension enables administrators (enforced by the policy engine) to view status and update attributes for agents. Updating agent management API attributes affects operations of other components, such as OpenStack Networking schedulers. For example, administrators can disable a specified agent so that OpenStack Networking schedulers do not schedule resources to it. For how to use agent management extension and OpenStack Networking schedulers feature, see the OpenStack Cloud Administrator Guide. Verb URI Description GET /agents Lists agents that report their status to OpenStack Networking server. GET /agents/agent_id Shows details for a specified agent. PUT /agents/agent_id Updates the admin status and description for a specified agent. DELETE /agents/agent_id Deletes a specified agent. List agents Verb URI Description GET /agents Lists agents that report their status to OpenStack Networking server. Normal Response Code: 200 This operation does not require a request body. This operation returns a response body. The default policy behavior is that non-admin user won't be able to see any agent in the response when this call is invoked Example 4.5. List agents: JSON request GET /v2.0/agents HTTP/1.1 Host: controlnode:9696 User-Agent: python-neutronclient Content-Type: application/json Accept: application/json X-Auth-Token: c52a1b304fec4ca0ac85dc1741eec6e2 Example 4.6. List agents: JSON response { "agents":[ { "binary":"neutron-dhcp-agent", "description":null, "admin_state_up":false, "heartbeat_timestamp":"2013-03-26T09:35:13.000000", "alive":false, "id":"af4567ad-c2e6-4311-944d-22efc12f89af", "topic":"dhcp_agent", "host":"HostC", "agent_type":"DHCP agent", "started_at":"2013-03-26T09:35:01.000000", "created_at":"2013-03-26T09:35:01.000000", "configurations":{ "subnets":2, "use_namespaces":true, Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 80 "dhcp_driver":"neutron.agent.linux.dhcp.Dnsmasq", "networks":2, "dhcp_lease_time":120, "ports":3 } } ] } Show agent details Verb URI Description GET /agents/agent_id Shows details for a specified agent. Normal Response Code: 200 Error Response Codes:NotFound (404) if not authorized or the agent does not exist This operation returns information for the given agent. This operation does not require a request body. This operation returns a response body. The body contents depend on the agent's type. Example 4.7. Show agent details: JSON request GET /v2.0/agents/af4567ad-c2e6-4311-944d-22efc12f89af HTTP/1.1 Host: controlnode:9696 User-agent: python-neutronclient Content-Type: application/json Accept: application/json X-Auth-Token: a54d6fdda41341f892150e2aaf648f0d Example 4.8. Show agent details: JSON response { "agent":{ "binary":"neutron-dhcp-agent", "description":null, "admin_state_up":false, "heartbeat_timestamp":"2013-03-26T09:35:13.000000", "alive":false, "id":"af4567ad-c2e6-4311-944d-22efc12f89af", "topic":"dhcp_agent", "host":"HostC", "agent_type":"DHCP agent", "started_at":"2013-03-26T09:35:01.000000", "created_at":"2013-03-26T09:35:01.000000", "configurations":{ "subnets":2, "use_namespaces":true, "dhcp_driver":"neutron.agent.linux.dhcp.Dnsmasq", "networks":2, "dhcp_lease_time":120, "ports":3 } } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 81 Update agent Verb URI Description PUT /agents/agent_id Updates the admin status and description for a specified agent. Normal Response Code: 200 Error Response Codes: BadRequest (400) if something other than description or admin status is changed, NotFound (404) if not authorized or the agent does not exist This operation updates the agent's admin status and description. This operation requires a request body. This operation returns a response body. Example 4.9. Update agent: JSON request PUT /v2.0/agents/af4567ad-c2e6-4311-944d-22efc12f89af HTTP/1.1 Host: controlnode:9696 User-Agent: python-neutronclient Content-Type: application/json Accept: application/json X-Auth-Token: 4cbb09e780434b249ff596d6979fd8fc Content-Length: 38{ "agent": { "admin_state_up": "False" } } Example 4.10. Update agents: JSON response { "agent":{ "binary":"neutron-dhcp-agent", "description":null, "admin_state_up":false, "heartbeat_timestamp":"2013-03-26T09:35:13.000000", "alive":false, "id":"af4567ad-c2e6-4311-944d-22efc12f89af", "topic":"dhcp_agent", "host":"HostC", "agent_type":"DHCP agent", "started_at":"2013-03-26T09:35:01.000000", "created_at":"2013-03-26T09:35:01.000000", "configurations":{ "subnets":2, "use_namespaces":true, "dhcp_driver":"neutron.agent.linux.dhcp.Dnsmasq", "networks":2, "dhcp_lease_time":120, "ports":3 } } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 82 Delete agent Verb URI Description DELETE /agents/agent_id Deletes a specified agent. Normal Response Code: 204 Error Response Codes: NotFound (404) if not authorized or the agent does not exist This operation deletes the agent. This operation does not require a request body. This operation does not return a response body. Example 4.11. Delete agent: JSON request DELETE /v2.0/agents/44002aeb-2817-4cb8-9306-34308b4b40d9 HTTP/1.1 Host: controlnode:9696 User-Agent: python-neutronclient Content-Type: application/json Accept: application/json X-Auth-Token: 4cbb09e780434b249ff596d6979fd8fc Example 4.12. Delete agent: JSON response HTTP/1.1 204 No Content Content-Length: 0 Date: Tue, 26 Mar 2013 12:12:35 GMT Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 83 Agent schedulers The agent scheduler extensions schedule resources among agents on top of the the section called “Agent management” [78]. The agent scheduler feature consist of several agent scheduler extensions. In Havana, the following extensions are available. • DHCP agent scheduler (dhcp_agent_scheduler) • L3 agent scheduler (l3_agent_scheduler) • load balancer agent scheduler (lbaas_agent_scheduler) In Grizzly, the DHCP agent scheduler and the L3 agent scheduler features are provided by a single extension named the agent scheduler (agent_scheduler). In Havana, this extension is split into the DHCP agent scheduler and the L3 agent scheduler extensions. The load balancer agent scheduler extension was introduced in Havana. DHCP agent scheduler (dhcp_agent_scheduler) The DHCP agent scheduler extension enables administrators to assign DHCP servers for Neutron networks to given Neutron DHCP agents, and retrieve mappings between Neutron networks and DHCP agents. This feature is implemented on top of Agent Management extension. Verb URI Description GET /agents/agent_id/ dhcp-networks Lists networks that the specified DHCP agent hosts. GET / networks/ network_id/dhcp- agents Lists DHCP agents that host a specified network. POST /agents/agent_id/ dhcp-networks Schedules the network to that the specified DHCP agent. DELETE /agents/agent_id/ dhcp- networks/ network_id Removes the network from that the specified DHCP agent. List networks hosted by a DHCP agent Verb URI Description GET /agents/agent_id/ dhcp-networks Lists networks that the specified DHCP agenthosts. Normal response Code: 200 Error response Codes: Unauthorized (401), Forbidden (403) This operation does not require a request body. This operation returns a response body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 84 Example 4.13. List networks hosted by on DHCP agent: JSON request GET /v2.0/agents/d5724d7e-389d-4ba0-8d00-fc673a147bfa/dhcp-networks HTTP/1.1 Host: localhost:9696 User-Agent: python-neutronclient Content-Type: application/json Accept: application/json X-Auth-Token: 797f94caf0a8481c893a232cc0c1dfca Example 4.14. List networks hosted by DHCP agent: JSON response { "networks":[ { "status":"ACTIVE", "subnets":[ "15a09f6c-87a5-4d14-b2cf-03d97cd4b456" ], "name":"net1", "provider:physical_network":"physnet1", "admin_state_up":true, "tenant_id":"3671f46ec35e4bbca6ef92ab7975e463", "provider:network_type":"vlan", "router:external":false, "shared":false, "id":"2d627131-c841-4e3a-ace6-f2dd75773b6d", "provider:segmentation_id":1001 }, { "status":"ACTIVE", "subnets":[ ], "name":"net2", "provider:physical_network":null, "admin_state_up":true, "tenant_id":"3671f46ec35e4bbca6ef92ab7975e463", "provider:network_type":"local", "router:external":false, "shared":false, "id":"524e26ea-fad4-4bb0-b504-1ad0dc770e7a", "provider:segmentation_id":null }, { "status":"ACTIVE", "subnets":[ "43671fba-c76b-4c33-bd7e-8bef54145f2f" ], "name":"mynet1", "provider:physical_network":"physnet1", "admin_state_up":true, "tenant_id":"3671f46ec35e4bbca6ef92ab7975e463", "provider:network_type":"vlan", "router:external":false, "shared":false, "id":"cfa65a54-06a8-4f9f-86b0-73c700c02c41", "provider:segmentation_id":1000 } ] } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 85 List DHCP agents hosted by network Verb URI Description GET / networks/ network_id/dhcp- agents Lists DHCP agents that hosts a specified network. Normal response Code: 200 Error response Codes: Unauthorized (401), Forbidden (403) This operation does not require a request body. This operation returns a response body. Example 4.15. List DHCP agents hosted by network: JSON request GET /v2.0/networks/2d627131-c841-4e3a-ace6-f2dd75773b6d/dhcp-agents HTTP/1.1 Host: localhost:9696 User-Agent: python-neutronclient Content-Type: application/json Accept: application/json X-Auth-Token: cc0f378bdf1545fb8dea2120c89eb532 Example 4.16. List DHCP agents hosted by network: JSON response { "agents":[ { "binary":"neutron-dhcp-agent", "description":null, "admin_state_up":true, "heartbeat_timestamp":"2013-03-27T00:24:01.000000", "alive":false, "topic":"dhcp_agent", "host":"HostC", "agent_type":"DHCP agent", "created_at":"2013-03-26T23:54:20.000000", "started_at":"2013-03-26T23:54:20.000000", "id":"d5724d7e-389d-4ba0-8d00-fc673a147bfa", "configurations":{ "subnets":2, "use_namespaces":true, "dhcp_driver":"neutron.agent.linux.dhcp.Dnsmasq", "networks":2, "dhcp_lease_time":120, "ports":5 } } ] } Schedule network to DHCP agent Verb URI Description POST /agents/agent_id/ dhcp-networks Schedules the network to that the specified DHCP agent. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 86 Normal response Code: 201 Error response Codes: Unauthorized (401), Forbidden (403), Conflict (409) if the network is already hosted by that the specified DHCP agent, NotFound(404) when the specified agent is not a valid DHCP agent. This operation requires a request body. This operation returns a null body. Example 4.17. Schedule network: JSON request POST /v2.0/agents/d5724d7e-389d-4ba0-8d00-fc673a147bfa/dhcp-networks.json HTTP/1.1 Host: localhost:9696 User-Agent: python-neutronclient Content-Type: application/json Accept: application/json X-Auth-Token: d88f7af21ee34f6c87e23e46cf3f986d Content-Length: 54 {"network_id": "1ae075ca-708b-4e66-b4a7-b7698632f05f"} Example 4.18. Schedule network: JSON response HTTP/1.1 201 Created Content-Type: application/json; charset=UTF-8 Content-Length: 4 Date: Wed, 27 Mar 2013 01:22:46 GMT null Remove network from DHCP agent Verb URI Description DELETE /agents/agent_id/ dhcp- networks/ network_id Removes the network from that the specified DHCP agent. Normal response Code: 204 Error response Codes: Unauthorized (401), Forbidden (403), NotFound (404), Conflict (409) if the network is not hosted by that the specified DHCP agent. This operation does not require a request body. This operation does not return a response body. Example 4.19. Remove network from DHCP agent: JSON request DELETE /v2.0/agents/d5724d7e-389d-4ba0-8d00-fc673a147bfa/dhcp-networks/ 1ae075ca-708b-4e66-b4a7-b7698632f05f.json HTTP/1.1 Host: localhost:9696 User-Agent: python-neutronclient Content-Type: application/json Accept: application/json X-Auth-Token: 7ae91cde8f504031be5a2cd5b99d4fe9 Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 87 L3 agent scheduler (l3_agent_scheduler) The L3 agent scheduler extension allows administrators to assign Neutron routers to Neutron L3 agents, and retrieve mappings between Neutron routers and L3 agents. This feature is implemented on top of Agent Management extension. Verb URI Description GET /agents/agent_id/ l3-routers Lists routers that the specified L3 agent hosts. GET /routers/router_id/ l3-agents Lists L3 agents that hosts a specified router. POST /agents/agent_id/ l3-routers Schedules the router to that the specified L3 agent. DELETE /agents/agent_id/ l3- routers/router_id Removes the router from that the specified L3 agent. List routers hosted by an L3 agent Verb URI Description GET /agents/agent_id/ l3-routers Lists routers that the specified L3 agent hosts. Normal response Code: 200 Error response Codes: Unauthorized (401), Forbidden (403) This operation does not require a request body. This operation returns a response body. Example 4.20. List routers hosted by L3 agent: JSON request GET /v2.0/agents/fa24e88e-3d2f-4fc2-b038-5fb5be294c03/l3-routers.json HTTP/1.1 Host: localhost:9696 User-Agent: python-neutronclient Content-Type: application/json Accept: application/json X-Auth-Token: 6eeea6e73b68415f85d8368902a32c11 Example 4.21. List routers hosted by L3 agent: JSON response { "routers":[ { "status":"ACTIVE", "external_gateway_info":null, "name":"router1", "admin_state_up":true, "tenant_id":"3671f46ec35e4bbca6ef92ab7975e463", "routes":[ ], Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 88 "id":"8eef2388-f27d-4a17-986e-9319a77ccd9d" } ] } List L3 agents hosted by router Verb URI Description GET /routers/router_id/ l3-agents Lists L3 agents that hosts a specified router. Normal response Code: 200 Error response Codes: Unauthorized (401), Forbidden (403) This operation does not require a request body. This operation returns a response body. Example 4.22. List L3 agents hosted by router: JSON request GET /v2.0/routers/8eef2388-f27d-4a17-986e-9319a77ccd9d/l3-agents.json HTTP/1.1 Host: localhost:9696 User-Agent: python-neutronclient Content-Type: application/json Accept: application/json X-Auth-Token: bce63afb1e794c70972a19a7c2d6dcab Example 4.23. List L3 agents hosted by router: JSON response { "agents":[ { "binary":"neutron-l3-agent", "description":null, "admin_state_up":true, "heartbeat_timestamp":"2013-03-27T00:24:03.000000", "alive":false, "topic":"l3_agent", "host":"HostC", "agent_type":"L3 agent", "created_at":"2013-03-26T23:54:26.000000", "started_at":"2013-03-26T23:54:26.000000", "id":"fa24e88e-3d2f-4fc2-b038-5fb5be294c03", "configurations":{ "router_id":"", "gateway_external_network_id":"", "handle_internal_only_routers":true, "use_namespaces":true, "routers":0, "interfaces":0, "floating_ips":0, "interface_driver":"neutron.agent.linux.interface. OVSInterfaceDriver", "ex_gw_ports":0 } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 89 ] } Schedule router to L3 agent Verb URI Description POST /agents/agent_id/ l3-routers Schedules one router to that the specified L3 agent. Normal response Code: 201 Error response Codes: Unauthorized (401), Forbidden (403), Conflict (409) if the router is already hosted, NotFound (404) if the specified agent is not a valid L3 agent. This operation requires a request body. This operation returns a null body. Example 4.24. Schedule router: JSON request GET /v2.0/agents/fa24e88e-3d2f-4fc2-b038-5fb5be294c03/l3-routers.json HTTP/1.1 Host: localhost:9696 User-Agent: python-neutronclient Content-Type: application/json Accept: application/json X-Auth-Token: d88f7af21ee34f6c87e23e46cf3f986d Content-Length: 54 {"router_id": "8eef2388-f27d-4a17-986e-9319a77ccd9d"} Example 4.25. Schedule router: JSON response HTTP/1.1 201 Created Content-Type: application/json; charset=UTF-8 Content-Length: 4 Date: Wed, 27 Mar 2013 01:22:46 GMT null Remove router from L3 agent Verb URI Description DELETE /agents/agent_id/ l3- routers/network_id Removes the router from that the specified L3 agent. Normal response Code: 204 Error response Codes: Unauthorized (401), Forbidden (403), Conflict (409) if the router is not hosted by that the specified L3 agent. This operation does not require a request body. This operation does not return a response body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 90 Example 4.26. Remove router from L3 agent: JSON request DELETE /v2.0/agents/b7d7ba43-1a05-4b09-ba07-67242d4a98f4/l3-routers/8eef2388- f27d-4a17-986e-9319a77ccd9d.json HTTP/1.1 Host: localhost:9696 User-Agent: python-neutronclient Content-Type: application/json Accept: application/json X-Auth-Token: 2147ef6fe4444f0299b1c0b6b529ff47 Load balancer agent scheduler (lbaas_agent_scheduler) The LBaaS agent scheduler extension allows administrators to retrieve mappings between load balancer pools to LBaaS agents. In Havana, this extension does not provide an ability to assign load balancer pool to specific LBaaS agent. Pools are scheduled automatically when created. This feature is implemented on top of Agent Management extension. The load balancer agent scheduler extension was introduced in Havana. Verb URI Description GET /agents/agent_id/ loadbalancer-pools Lists pools that the specified LBaaS agent hosts. GET /lb/pools/pool_id/ loadbalancer-agent Shows an LBaaS agent that hosts a specified pool. List pools hosted by an LBaaS agent Verb URI Description GET /agents/agent_id/ loadbalancer-pools Lists pools that the specified LBaaS agent hosts. Normal response Code: 200 Error response Codes: Unauthorized (401), Forbidden (403) This operation does not require a request body. This operation returns a response body. Example 4.27. List pools hosted by LBaaS agent: JSON request GET /v2.0/agents/6ee1df7f-bae4-4ee9-910a-d33b000773b0/loadbalancer-pools.json HTTP/1.1 Host: localhost:9696 User-Agent: python-neutronclient Content-Type: application/json Accept: application/json X-Auth-Token: 6eeea6e73b68415f85d8368902a32c11 Example 4.28. List pools hosted by LBaaS agent: JSON response { "pools": [ { "admin_state_up": true, "description": "", "health_monitors": [], Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 91 "health_monitors_status": [], "id": "28296abb-e675-4288-9cd0-6c112c720db0", "lb_method": "ROUND_ROBIN", "members": [], "name": "pool1", "protocol": "HTTP", "provider": "haproxy", "status": "PENDING_CREATE", "status_description": null, "subnet_id": "f8fd83d3-2080-4ab9-9814-391fe7b8a7a4", "tenant_id": "54d7b6253c8c4e64862fbd08b3fc08cd", "vip_id": null } ] } Show LBaaS agent that hosts pool Verb URI Description GET /lb/pools/pool_id/ loadbalancer-agent Shows an LBaaS agent that hosts a specified pool. Normal response Code: 200 Error response Codes: Unauthorized (401), Forbidden (403) This operation does not require a request body. This operation returns a response body. Example 4.29. Show LBaaS agent that hosts pool: JSON request GET /v2.0/lb/pools/28296abb-e675-4288-9cd0-6c112c720db0/loadbalancer-agent. json HTTP/1.1 Host: localhost:9696 User-Agent: python-neutronclient Content-Type: application/json Accept: application/json X-Auth-Token: bce63afb1e794c70972a19a7c2d6dcab Example 4.30. Show LBaaS agent that hosts pool: JSON response { "agent": { "admin_state_up": true, "agent_type": "Loadbalancer agent", "alive": true, "binary": "neutron-loadbalancer-agent", "configurations": { "device_driver": "neutron.services.loadbalancer.drivers.haproxy. namespace_driver.HaproxyNSDriver", "devices": 0, "interface_driver": "neutron.agent.linux.interface. OVSInterfaceDriver" }, "created_at": "2013-10-01 12:50:13", "description": null, "heartbeat_timestamp": "2013-10-01 12:56:29", "host": "ostack02", Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 92 "id": "6ee1df7f-bae4-4ee9-910a-d33b000773b0", "started_at": "2013-10-01 12:50:13", "topic": "lbaas_process_on_host_agent" } } Allowed address pairs The allowed address pair extension extends the port attribute to enable you to specify arbitrary mac_address/ip_address(cidr) pairs that are allowed to pass through a port regardless of the subnet associated with the network. List ports Verb URI Description GET /ports Lists ports with their allowed address pair attributes. Normal Response Code: 200 OK Error Response Codes: 401 Unauthorized This operation returns, for each port, its allowed address pair attributes as well as all the attributes normally returned by the list port operation. Example 4.31. List ports with allowed address pair attributes: JSON response { "ports":[ { "admin_state_up": true, "allowed_address_pairs": [{"ip_address": "23.23.23.1", "mac_address": "fa:16:3e:c4:cd:3f"}], "device_id": "", "device_owner": "", "fixed_ips": [{"ip_address": "10.0.0.2", "subnet_id": "f4145134-b99b-4b18-9940-47239f071923"}], "id": "191f5290-3a5a-40ff-b0cb-cd4b115b400e", "mac_address": "fa:16:3e:c4:cd:3f", "name": "", "network_id": "327f2a2f-9d70-417f-ac3a-d3155e25cf25", "status": "DOWN", "tenant_id": "8462a4d167f84256b7035f4c408c1185" }, { "admin_state_up": true, "allowed_address_pairs": [], "device_id": "", "device_owner": "", "fixed_ips": [{"ip_address": "10.0.0.3", "subnet_id": "f4145134-b99b-4b18-9940-47239f071923"}], "id": "ec2fb9f9-a11b-4791-852d-eb1ab9b27a0e", "mac_address": "fa:16:3e:a9:3e:1a", "name": "", "network_id": "327f2a2f-9d70-417f-ac3a-d3155e25cf25", "status": "DOWN", "tenant_id": "8462a4d167f84256b7035f4c408c1185" } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 93 ] } Example 4.32. List ports with allowed address pair attributes: XML response ACTIVE 23.23.23.1 fa:16:3e:c4:cd:3f True 3537e809-8bec-4ae4-a5ab-2c6477760195 8462a4d167f84256b7035f4c408c1185 fa:16:3e:21:4c:2e f4145134-b99b-4b18-9940-47239f071923 10.0.0.21 191f5290-3a5a-40ff-b0cb-cd4b115b400e ACTIVE True 327f2a2f-9d70-417f-ac3a-d3155e25cf25 8462a4d167f84256b7035f4c408c1185 fa:16:3e:a9:3e:1a 18cf6972-95cc-4134-a986-843dc7433aa0 10.0.0.5 ec2fb9f9-a11b-4791-852d-eb1ab9b27a0e Show port details Verb URI Description GET /ports/port_id Shows details about a specified port, including allowed address pair attributes. Normal Response Code: 200 OK Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 94 Error Response Code: 401 Unauthorized, 404 Not Found Example 4.33. Show port with allowed address pair attributes: JSON response { "port": { "admin_state_up": true, "allowed_address_pairs": [{"ip_address": "23.23.23.1", "mac_address": "fa:16:3e:c4:cd:3f"}], "device_id": "", "device_owner": "", "fixed_ips": [{"ip_address": "10.0.0.2", "subnet_id": "f4145134-b99b-4b18-9940-47239f071923"}], "id": "191f5290-3a5a-40ff-b0cb-cd4b115b400e", "mac_address": "fa:16:3e:c4:cd:3f", "name": "", "network_id": "327f2a2f-9d70-417f-ac3a-d3155e25cf25", "status": "DOWN", "tenant_id": "8462a4d167f84256b7035f4c408c1185" } } Example 4.34. Show port with allowed address pair attributes: XML response ACTIVE 23.23.23.1 fa:16:3e:c4:cd:3f True 3537e809-8bec-4ae4-a5ab-2c6477760195 8462a4d167f84256b7035f4c408c1185 fa:16:3e:21:4c:2e f4145134-b99b-4b18-9940-47239f071923 10.0.0.21 191f5290-3a5a-40ff-b0cb-cd4b115b400e Create port Verb URI Description POST /ports Creates a port and explicitly specifies the allowed address pair attributes. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 95 Normal Response Code: 201 Error Response Code: 400 Bad Request, 401 Unauthorized, 403 Forbidden Bad request is returned if an allowed address pair matches the mac_address and ip_address on port. Note: If the mac_address field is left out of the body of the request the mac_address assigned to the port will be used. Example 4.35. Create port with allowed address pair attributes: JSON request { "port": { "network_id": "3537e809-8bec-4ae4-a5ab-2c6477760195", "allowed_address_pairs": [{"ip_address": "10.3.3.3"}] } } Update port Verb URI Description PUT /ports/port_id Updates a port, with new allowed address pair values. Normal Response Code: 200 OK Error Response Code: 400 Bad Request, 401 Unauthorized, 404 Not Found, 403 Forbidden Example 4.36. Update allowed address pair attributes for a port: JSON request { "port": { "allowed_address_pairs": [ {"ip_address": "10.0.0.1"} ] } } The binding Extended Attributes for Ports Use the Networking API v2.0 with the binding extended attributes to get information about, create, and update port objects. The binding-prefixed extended attributes for ports are: Table 4.1. binding Extended Attributes for Ports Attribute Type Required CRUDa Default Value Validation Constraints Notes binding:vif_type String N/A R None N/A Read-only. The vif type for the specified port. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 96 Attribute Type Required CRUDa Default Value Validation Constraints Notes binding:host_id uuid-str N/A CRU None N/A The ID of the host where the port is allocated. In some cases different implementations can run on different hosts. binding:profile list(dict) N/A CRU None N/A A dictionary that enables the application running on the specified host to pass and receive vif port-specific information to the plug-in. binding:capabilities list(dict) N/A R None N/A Read-only. A dictionary that enables the application to pass information about functions that Networking API v2.0 provides. Specify the following value: port_filter : Boolean to define whether Networking API v2.0 provides port filtering features such as security group and anti-MAC/ IP spoofing. a •C. Use the attribute in create operations. •R. This attribute is returned in response to show and list operations. •U. You can update the value of this attribute. •D. You can delete the value of this attribute. List Ports Verb URI Description GET /ports Lists ports to which the tenant has access. The binding extended attributes are visible to only administrative users. Normal Response Code: 200 Error Response Codes: Unauthorized (401) This operation lists ports to which the tenant has access. This operation does not require a request body. This operation returns a response body. In addition to any other fields returned in a list ports response, the following binding- prefixed fields are visible to administrative users: Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 97 Field Description binding:vif_type Read-only. The vif type for the specified port. binding:host_id The ID of the host where the port is allocated. In some cases different implementations can run on different hosts. binding:profile A dictionary that enables the application running on the specified host to pass and receive vif port-specific information to the plug-in. binding:capabilities Read-only. A dictionary that enables the application to pass information about functions that Networking API v2.0 provides. Specify the following value: port_filter : Boolean to define whether Networking API v2.0 provides port filtering features such as security group and anti- MAC/IP spoofing. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 98 Show Port Verb URI Description GET /ports/port-id Shows information for a specified port. The binding extended attributes are visible to only administrative users. Normal Response Code: 200 Error Response Codes: Unauthorized (401), Not Found (404) This operation returns information for the port specified in the request URI. This operation does not require a request body. This operation returns a response body. In addition to any fields returned in a show port details response, the following binding- prefixed extended attributes are visible to administrative users: Field Description binding:vif_type Read-only. The vif type for the specified port. binding:host_id The ID of the host where the port is allocated. In some cases different implementations can run on different hosts. binding:profile A dictionary that enables the application running on the specified host to pass and receive vif port-specific information to the plug-in. binding:capabilities Read-only. A dictionary that enables the application to pass information about functions that Networking API v2.0 provides. Specify the following value: port_filter : Boolean to define whether Networking API v2.0 provides port filtering features such as security group and anti- MAC/IP spoofing. Create Port Verb URI Description POST /ports Creates a port on a specified network. Only administrative users can add the binding extended attributes. Normal Response Code: 201 Error Response Codes: Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Conflict (409), MAC generation failure (503) This operation creates an OpenStack Networking port. You must specify the network where the port is to created on the network_id attribute in the request body. This operation requires a request body. This operation returns a response body. In addition to any attributes that can be set in a create port operation, administrative users can also set the following binding-prefixed extended attributes: Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 99 Field Description binding:host_id The ID of the host where the port is allocated. In some cases different implementations can run on different hosts. binding:profile A dictionary that enables the application running on the specified host to pass and receive vif port-specific information to the plug-in. Update Port Verb URI Description PUT /ports/port-id Updates a specified port. Only administrative users can update the binding extended attributes. Normal Response Code: 200 Error Response Codes: Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Conflict (409) Use this operation to update information for a port. This operation requires a request body. This operation returns a response body. In addition to any attributes that can be updated in an update port operation, administrative users can also update the following binding-prefixed extended attributes: Field Description binding:host_id The ID of the host where the port is allocated. In some cases different implementations can run on different hosts. binding:profile A dictionary that enables the application running on the specified host to pass and receive vif port-specific information to the plug-in. Configurable external gateway modes By default, when a gateway is attached to a router using the Neutron L3 extension, Network Address Translation (NAT) is enabled for traffic generated by subnets attached to the router. With this extension, the user will have the option of choosing whether SNAT should be enabled or not on a router basis. This is achieved simply by specifying a boolean attribute, enable_snat, in the external_gateway_info attribute of the router resource. This extension redefines the external_gateway_info attribute: Table 4.2. external_gateway_info attributes Attribute Type Required Default Value Validation Constraints Notes network_id UUID Yes N/A Must be a valid uuid representative of an external network. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 100 Attribute Type Required Default Value Validation Constraints Notes enable_snat Boolean No True {True|False} The default setting is True to ensure backward compatibility for plugins supporting this extension. SNAT can be enabled or disabled at any time on a Neutron router regardless of the current status of floating IPs. Floating IPs will continue working even when SNAT is disabled. List routers Verb URI Description GET /routers Lists neutron routers. Success and error response codes are not changed with regards to the operation as introduced by the L3 API extension. When this extension is enabled, this operation also returns the current Source NAT status for configured routers, as follows. The response for the show router operation is the same, with the obvious exception that a single router is returned. Example 4.37. Router list with configurable external gateway modes enabled { "routers": [{ "status": "ACTIVE", "external_gateway_info": {"network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8", "enable_snat": true}, "name": "second_router", "admin_state_up": true, "tenant_id": "6b96ff0cb17a4b859e1e575d221683d3", "id": "7177abc4-5ae9-4bb7-b0d4-89e94a4abf3b" }, { "status": "ACTIVE", "external_gateway_info": {"network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8", "enable_snat": false}, "name": "router1", "admin_state_up": true, "tenant_id": "33a40233088643acb66ff6eb0ebea679", "id": "a9254bdb-2613-4a13-ac4c-adc581fba50d" }] } Create router with external gateway Verb URI Description POST /routers Create a new Neutron router Success and error response codes are not changed with regards to the operation as introduced by the L3 API extension. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 101 Neutron API users can specify whether SNAT should be performed on the network specified as the router's external gateway by setting enable_snat in external_gateway_info to either True or False; the default value is True. Example 4.38. Create router with SNAT disabled POST /v2.0/routers Accept: application/json { "router": { "name": "another_router", "admin_state_up": true, "external_gateway_info": { "network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8", "enable_snat": false} } } HTTP/1.1 201 OK Content-Type: application/json; charset=UTF-8 { "router": { "status": "ACTIVE", "external_gateway_info": { "network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8", "enable_snat": false} "name": "another_router", "admin_state_up": true, "tenant_id": "6b96ff0cb17a4b859e1e575d221683d3", "id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e" } } Update external gateway information for router Verb URI Description PUT /routers/router_id Creates a neutron router. Success and error response codes are not changed with regards to the operation as introduced by the L3 API extension. Neutron API users can enable or disable SNAT on a router specifying the enable_snat attribute in the external_gateway_info attribute for the router resource. This operation can be either used for updating the SNAT status only, the external network, or both attributes at the same time. In any case, if the enable_snat attribute is not specified, it will default to True. For instance, if the current SNAT status is disabled, and the router's gateway is updated to a different external network without specifying enable_snat, SNAT will be enabled for the new network. It is important to note that whenever updating a router's external gateway information, the network_idparameter must be specified always, even if the final goal is just to enable or disable SNAT for the router on the same external network. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 102 The rest of this section provides some samples for updating a router's external gateway info with SNAT mode. Example 4.39. Disable SNAT for the current external network { "router": { "name": "another_router", "admin_state_up": true, "external_gateway_info": { "network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8"} } } { "router":{ "status":"ACTIVE", "external_gateway_info":{ "network_id":"3c5bcddd-6af9-4e6b-9c3e-c153e521cab8", "enable_snat":true }, "name":"another_router", "admin_state_up":true, "tenant_id":"6b96ff0cb17a4b859e1e575d221683d3", "id":"8604a0de-7f6b-409a-a47c-a1cc7bc77b2e" } } { "router":{ "status":"ACTIVE", "external_gateway_info":{ "network_id":"3c5bcddd-6af9-4e6b-9c3e-c153e521cab8", "enable_snat":false }, "name":"another_router", "admin_state_up":true, "tenant_id":"6b96ff0cb17a4b859e1e575d221683d3", "id":"8604a0de-7f6b-409a-a47c-a1cc7bc77b2e" } } { "router":{ "external_gateway_info":{ "network_id":"3c5bcddd-6af9-4e6b-9c3e-c153e521cab8", "enable_snat":false } } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 103 Example 4.40. Change external network and enable SNAT { "router": { "name": "another_router", "admin_state_up": true, "external_gateway_info": { "network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8", "enable_snat": false} } } { "router": { "status": "ACTIVE", "external_gateway_info": { "network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8", "enable_snat": false}, "name": "another_router", "admin_state_up": true, "tenant_id": "6b96ff0cb17a4b859e1e575d221683d3", "id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e" } } { "router": { "external_gateway_info": { "network_id": "002ab3b9-9127-4158-be30-4b45f3814df5"} } } { "router": { "status": "ACTIVE", "external_gateway_info": { "network_id": "002ab3b9-9127-4158-be30-4b45f3814df5", "enable_snat": true}, "name": "another_router", "admin_state_up": true, "tenant_id": "6b96ff0cb17a4b859e1e575d221683d3", "id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e" } } Example 4.41. Change external network and external-gateway SNAT disabled { "router": { "name": "another_router", "admin_state_up": true, "external_gateway_info": { "network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8", "enable_snat": false} } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 104 { "router": { "status": "ACTIVE", "external_gateway_info": { "network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8", "enable_snat": false}, "name": "another_router", "admin_state_up": true, "tenant_id": "6b96ff0cb17a4b859e1e575d221683d3", "id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e" } } { "router": { "external_gateway_info": { "network_id": "002ab3b9-9127-4158-be30-4b45f3814df5", "enable_snat": false} } } { "router": { "status": "ACTIVE", "external_gateway_info": { "network_id": "002ab3b9-9127-4158-be30-4b45f3814df5", "enable_snat": false}, "name": "another_router", "admin_state_up": true, "tenant_id": "6b96ff0cb17a4b859e1e575d221683d3", "id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e" } } External networks (external-net) The external network extension is used to specify whether the network is external or not. This information is used by Layer-3 network (router) extension. External networks are connected to a router's external gateway and host floating IPs. The external network extension adds the router:external attribute to the network resource. Table 4.3. Network Attributes Attribute Type Required CRUDa Default Value Validation Constraints Notes router:external Bool No CRU False { True | False } Specifies whether the network is an external network or not. a•C. Use the attribute in create operations. •R. This attribute is returned in response to show and list operations. •U. You can update the value of this attribute. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 105 •D. You can delete the value of this attribute. List networks Verb URI Description GET /networks Returns a list of networks with their router:external attributes. Response codes are same as the normal operation of listing networks. router:external attribute is visible to all users by default policy setting. Regular users are not authorized to create ports on external networks, however they will be able to see this attribute in their network list. This is because external networks can be used by any tenant to set an external gateway for Neutron routers or create floating IPs and associate them with ports on internal tenant networks. Example 4.42. List networks with router:external attribute: JSON response { "networks": [ { "admin_state_up": true, "id": "0f38d5ad-10a6-428f-a5fc-825cfe0f1970", "name": "net1", "router:external": false, "shared": false, "status": "ACTIVE", "subnets": [ "25778974-48a8-46e7-8998-9dc8c70d2f06" ], "tenant_id": "b575417a6c444a6eb5cc3a58eb4f714a" }, { "admin_state_up": true, "id": "8d05a1b1-297a-46ca-8974-17debf51ca3c", "name": "ext_net", "router:external": true, "shared": false, "status": "ACTIVE", "subnets": [ "2f1fb918-9b0e-4bf9-9a50-6cebbb4db2c5" ], "tenant_id": "5eb8995cf717462c9df8d1edfa498010" } ] } Show network details Verb URI Description GET /networks/network_id Returns details about a specific network, including external networks attributes. Response codes are same as the normal operation of listing networks. router:external attribute is visible to all users including non-admin by default policy setting. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 106 Example 4.43. Show network with external attributes: JSON response { "network": { "admin_state_up": true, "id": "8d05a1b1-297a-46ca-8974-17debf51ca3c", "name": "ext_net", "router:external": true, "shared": false, "status": "ACTIVE", "subnets": [ "2f1fb918-9b0e-4bf9-9a50-6cebbb4db2c5" ], "tenant_id": "5eb8995cf717462c9df8d1edfa498010" } } Create network Verb URI Description POST /networks Creates a new network using the external network extension attribute. If the user submitting the request is not allowed to set this attribute, a 403 Forbidden response will be returned. Usage of this attribute might be restricted through authorization policies. By the default policy only admin users can set this attribute. Example 4.44. Create network with external attributes: JSON request { "network": { "admin_state_up": true, "name": "ext_net", "router:external": true } } Update network Verb URI Description PUT /networks/network_id Updates a network, including the external network extension attribute. If the user submitting the request is not allowed to set this attribute, a 403 Forbidden response will be returned. Usage of this attribute might be restricted through authorization policies. By the default policy only admin users can set this attribute. Example 4.45. Update external attributes for a network: JSON request { "network":{ "router:external":true } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 107 Extra routes This extension adds extra routes to the router resource. You can specify a set of nexthop IPs and destination CIDRs. Note The nexthop IP must be a part of one of the subnets to which the router interfaces are connected. You can configure the routes attribute on only update operations. Table 4.4. Router attributes Attribute Type Required CRUDa Default Value Validation Constraints Notes routes list of dict No U None List should be in this form. [{'nexthop':IPAddress, 'destination':CIDR}] Extra route configuration a•C. Use the attribute in create operations. •R. This attribute is returned in response to show and list operations. •U. You can update the value of this attribute. •D. You can delete the value of this attribute. Update extra route Verb URI Description PUT /routers/router_id Updates logical router with routes attribute. Normal Response Code: 200 Error Response Codes: Unauthorized (401), Bad Request (400), Not Found (404), Conflict (409) This operation configures extra routes on the router. The nexthop IP must be a part of one of the subnets to which the router interfaces are connected. Otherwise, the server responds with 400 Bad Request error code. When a validation error is detected, such as a format error of IP address or CIDR, the server responds with 400 Bad Request. When Networking receives a request to delete the router interface for subnets that are used by one or more routes, it responds with 409 Conflict. Example 4.46. Update routes: XML response { "router":{ "routes":[ { "nexthop":"10.1.0.10", "destination":"40.0.1.0/24" } ] } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 108 Example 4.47. Update routes: JSON response {"router": {"status": "ACTIVE", "external_gateway_info": {"network_id": "5c26e0bb- a9a9-429c-9703-5c417a221096"}, "name": "router1", "admin_state_up": true, "tenant_id": "936fa220b2c24a87af51026439af7a3e", "routes": [{"nexthop": "10.1.0.10", "destination": "40.0.1.0/24"}], "id": "babc8173-46f6-4b6f-8b95-38c1683a4e22"} } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 109 Firewall as a Service (FWaaS) The FWaaS extension provides OpenStack users with the ability to deploy firewalls to protect their networks. The FWaaS extension enables you to: • Apply firewall rules on traffic entering and leaving tenant networks. • Support for applying tcp, udp, icmp, or protocol agnostic rules. • Creation and sharing of firewall policies which hold an ordered collection of the firewall rules. • Audit firewall rules and policies. This extension introduces these resources: • firewall: represents a logical firewall resource that a tenant can instantiate and manage. A firewall is associated with one firewall_policy. • firewall_policy: is an ordered collection of firewall_rules. A firewall_policy can be shared across tenants. Thus it can also be made part of an audit workflow wherein the firewall_policy can be audited by the relevant entity that is authorized (and can be different from the tenants which create or use the firewall_policy). • firewall_rule: represents a collection of attributes like ports, ip addresses which define match criteria and action (allow, or deny) that needs to be taken on the matched data traffic. Firewall rules Manage firewall rules. Table 4.5. Firewall rule attributes Attribute Type Required CRUD a Default value Validation constraints Notes id uuid-str N/A R generated N/A Unique identifier for the firewall rule object. tenant_id uuid-str Yes CR Derived from Authentication token N/A Owner of the firewall rule. Only admin users can specify a tenant identifier other than their own. name String No CRU None N/A Human readable name for the firewall rule (255 characters limit). Does not have to be unique. description String No CRU None N/A Human readable description for the firewall Rule (1024 characters limit). firewall_policy_id uuid-str No R None N/A This is a read-only attribute which gets populated with the uuid of the firewall policy when this firewall rule is associated with a firewall policy. A firewall rule can be associated with one firewall policy at a time. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 110 Attribute Type Required CRUD a Default value Validation constraints Notes The association can however be updated to a different firewall policy. This attribute can be "null" if the rule is not associated with any firewall policy. shared Bool No CRU false {true | false} When set to True makes this firewall rule visible to tenants other than its owner, and can be used in firewall policies not owned by its tenant. protocol String No CRU None {icmp | tcp | udp | null} IP Protocol ip_version Integer No CRU 4 {4 | 6} IP Protocol Version source_ip_address String (IP address or CIDR) No CRU None valid IP address (v4 or v6), or CIDR Source IP address or CIDR destination_ip_address String (IP address or CIDR) No CRU None Valid IP address (v4 or v6), or CIDR Destination IP address or CIDR source_port Integer No CRU None Valid port number (integer or string), or port range in the format of a ':' separated range). In the case of port range, both ends of the range are included. Source port number or a range destination_port Integer No CRU None Valid port number (integer or string), or port range in the format of a ':' separated range. In the case of port range, both ends of the range are included. Destination port number or a range position Integer No R None N/A This is a read-only attribute that gets assigned to this rule when the rule is associated with a firewall policy. It indicates the position of this rule in that firewall policy. This position number starts at 1. The position can be "null" if the firewall rule is not associated with any policy. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 111 Attribute Type Required CRUD a Default value Validation constraints Notes action String No CRU deny {allow | deny} Action to be performed on the traffic matching the rule (allow, deny) enabled Bool No CRU true {true | false} When set to False will disable this rule in the firewall policy. Facilitates selectively turning off rules without having to disassociate the rule from the firewall policy a•C. Use the attribute in create operations. •R. This attribute is returned in response to show and list operations. •U. You can update the value of this attribute. •D. You can delete the value of this attribute. List firewall rules Verb URI Description GET /fw/firewall_rules Lists firewall rules. Normal Response Code: 200 Error Response Codes: Unauthorized (401). This operation does not require a request body. This operation returns a response body. Example 4.48. List firewall rules: JSON request GET /v2.0/fw/firewall_rules.json User-Agent: python-neutronclient Accept: application/json Example 4.49. List firewall rules: JSON response { "firewall_rules": [ { "action": "allow", "description": "", "destination_ip_address": null, "destination_port": "80", "enabled": true, "firewall_policy_id": "c69933c1-b472-44f9-8226-30dc4ffd454c", "id": "8722e0e0-9cc9-4490-9660-8c9a5732fbb0", "ip_version": 4, "name": "ALLOW_HTTP", "position": 1, "protocol": "tcp", "shared": false, "source_ip_address": null, "source_port": null, "tenant_id": "45977fa2dbd7482098dd68d0d8970117" Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 112 } ] } Show firewall rule details Verb URI Description GET /fw/ firewall_rules/ firewall_rule-id Shows firewall rule details. Normal Response Code: 200 Error Response Codes: Unauthorized (401), Forbidden (403), Not Found (404) This operation does not require a request body. This operation returns a response body. Example 4.50. Show firewall rule: JSON request GET /v2.0/fw/firewall_rules/9faaf49f-dd89-4e39-a8c6-101839aa49bc.json User-Agent: python-neutronclient Accept: application/json Example 4.51. Show firewall rule: JSON response { "firewall_rule": { "action": "allow", "description": "", "destination_ip_address": null, "destination_port": "80", "enabled": true, "firewall_policy_id": null, "id": "8722e0e0-9cc9-4490-9660-8c9a5732fbb0", "ip_version": 4, "name": "ALLOW_HTTP", "position": null, "protocol": "tcp", "shared": false, "source_ip_address": null, "source_port": null, "tenant_id": "45977fa2dbd7482098dd68d0d8970117" } } Create firewall rule Verb URI Description POST /fw/firewall_rules Creates a firewall rule. Normal Response Code: 201 Error Response Codes: Unauthorized (401), Bad Request (400) This operation requires a request body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 113 This operation returns a response body. Example 4.52. Create firewall rule: JSON request POST /v2.0/fw/firewall_rules.json User-Agent: python-neutronclient Accept: application/json { "firewall_rule": { "action": "allow", "destination_port": "80", "enabled": true, "name": "ALLOW_HTTP", "protocol": "tcp" } } Example 4.53. Create firewall rule: JSON response HTTP/1.1 201 Created Content-Type: application/json; charset=UTF-8 { "firewall_rule": { "action": "allow", "description": "", "destination_ip_address": null, "destination_port": "80", "enabled": true, "firewall_policy_id": null, "id": "8722e0e0-9cc9-4490-9660-8c9a5732fbb0", "ip_version": 4, "name": "ALLOW_HTTP", "position": null, "protocol": "tcp", "shared": false, "source_ip_address": null, "source_port": null, "tenant_id": "45977fa2dbd7482098dd68d0d8970117" } } Update firewall rule Verb URI Description PUT /fw/ firewall_rules/ firewall_rule-id Updates a firewall rule. Normal Response Code: 200 Error Response Codes: Unauthorized (401), Bad Request (400), Not Found (404) Example 4.54. Update firewall rule: JSON request PUT /v2.0/fw/firewall_rules/41bfef97-af4e-4f6b-a5d3-4678859d2485.json User-Agent: python-neutronclient Accept: application/json Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 114 { "firewall_rule": { "shared": "true" } } Example 4.55. Update firewall rule: JSON response HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "firewall_rule": { "action": "allow", "description": "", "destination_ip_address": null, "destination_port": "80", "enabled": true, "firewall_policy_id": "c69933c1-b472-44f9-8226-30dc4ffd454c", "id": "8722e0e0-9cc9-4490-9660-8c9a5732fbb0", "ip_version": 4, "name": "ALLOW_HTTP", "position": 1, "protocol": "tcp", "shared": true, "source_ip_address": null, "source_port": null, "tenant_id": "45977fa2dbd7482098dd68d0d8970117" } } Delete firewall rule Verb URI Description DELETE /fw/ firewall_rules/ firewall_rule-id Deletes a firewall rule. Normal Response Code: 204 Error Response Codes: Unauthorized (401), Not Found (404), Conflict (409). The Conflict error response is returned when an operation is performed while the firewall is in a PENDING state. This operation does not require a request body. This operation does not return a response body. Example 4.56. Delete firewall rule: JSON request DELETE /v2.0/fw/firewall_rules/1be5e5f7-c45e-49ba-85da-156575b60d50.json User-Agent: python-neutronclient Accept: application/json Example 4.57. Delete firewall rule: JSON response HTTP/1.1 204 No Content Content-Length: 0 Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 115 Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 116 Firewall policies Manage firewall policies. Table 4.6. Firewall policy attributes Attribute Type Required CRUD a Default value Validation constraints Notes id uuid-str N/A R generated N/A Unique identifier for the firewall policy object. tenant_id uuid-str Yes CR Derived from Authentication token N/A Owner of the firewall policy. Only admin users can specify a tenant identifier other than their own. name String No CRU None N/A Human readable name for the firewall policy (255 characters limit). Does not have to be unique. description String No CRU None N/A Human readable description for the firewall policy (1024 characters limit) shared Bool No CRU false {true | false} When set to True makes this firewall policy visible to tenants other than its owner. firewall_rules List No CRU Empty list JSON list of firewall rule uuids This is an ordered list of firewall rule uuids. The firewall applies the rules in the order in which they appear in this list. audited Bool No CRU false {true | false} When set to True by the policy owner indicates that the firewall policy has been audited. This attribute is meant to aid in the firewall policy audit workflows. Each time the firewall policy or the associated firewall rules are changed, this attribute will be set to False and will have to be explicitly set to True through an update operation. a•C. Use the attribute in create operations. •R. This attribute is returned in response to show and list operations. •U. You can update the value of this attribute. •D. You can delete the value of this attribute. List firewall policies Verb URI Description GET /fw/firewall_policies Lists firewall policies. Normal Response Code: 200 Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 117 Error Response Codes: Unauthorized (401), Forbidden (403) This operation does not require a request body. This operation returns a response body. Example 4.58. List firewall policies: JSON request GET /v2.0/fw/firewall_policies.json User-Agent: python-neutronclient Accept: application/json Example 4.59. List firewall policies: JSON response { "firewall_policies": [ { "audited": false, "description": "", "firewall_rules": [ "8722e0e0-9cc9-4490-9660-8c9a5732fbb0" ], "id": "c69933c1-b472-44f9-8226-30dc4ffd454c", "name": "test-policy", "shared": false, "tenant_id": "45977fa2dbd7482098dd68d0d8970117" } ] } Show firewall policy details Verb URI Description GET /fw/ firewall_policies/ firewall_policy- id Shows firewall policy details. Normal Response Code: 200 Error Response Codes: Unauthorized (401), Not Found (404) This operation does not require a request body. This operation returns a response body. Example 4.60. Show firewall policy: JSON request GET /v2.0/fw/firewall_policies/9faaf49f-dd89-4e39-a8c6-101839aa49bc.json User-Agent: python-neutronclient Accept: application/json Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 118 Example 4.61. Show firewall policy: JSON response { "firewall_policy": { "audited": false, "description": "", "firewall_rules": [ "8722e0e0-9cc9-4490-9660-8c9a5732fbb0" ], "id": "c69933c1-b472-44f9-8226-30dc4ffd454c", "name": "test-policy", "shared": false, "tenant_id": "45977fa2dbd7482098dd68d0d8970117" } } Create firewall policy Verb URI Description POST /fw/firewall_policies Creates a firewall policy. Normal Response Code: 201 Error Response Codes: Unauthorized (401). This operation requires a request body. This operation returns a response body. Example 4.62. Create firewall policy: JSON request POST /v2.0/fw/firewall_policies.json User-Agent: python-neutronclient Accept: application/json { "firewall_policy": { "firewall_rules": [ "8722e0e0-9cc9-4490-9660-8c9a5732fbb0" ], "name": "test-policy" } } Example 4.63. Create firewall policy: JSON response HTTP/1.1 201 Created Content-Type: application/json; charset=UTF-8 Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 119 { "firewall_policy": { "audited": false, "description": "", "firewall_rules": [ "8722e0e0-9cc9-4490-9660-8c9a5732fbb0" ], "id": "c69933c1-b472-44f9-8226-30dc4ffd454c", "name": "test-policy", "shared": false, "tenant_id": "45977fa2dbd7482098dd68d0d8970117" } } Update firewall policy Verb URI Description PUT /fw/ firewall_policies/ firewall_policy- id Updates a firewall policy. Normal Response Code: 200 Error Response Codes: Unauthorized (401), Not Found (404) Example 4.64. Update firewall policy: JSON request PUT /v2.0/fw/firewall_policies/41bfef97-af4e-4f6b-a5d3-4678859d2485.json User-Agent: python-neutronclient Accept: application/json { "firewall_policy": { "firewall_rules": [ "a08ef905-0ff6-4784-8374-175fffe7dade", "8722e0e0-9cc9-4490-9660-8c9a5732fbb0" ] } } Example 4.65. Update firewall policy: JSON response HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "firewall_policy": { "audited": false, "description": "", "firewall_rules": [ "a08ef905-0ff6-4784-8374-175fffe7dade", "8722e0e0-9cc9-4490-9660-8c9a5732fbb0" ], "id": "c69933c1-b472-44f9-8226-30dc4ffd454c", "name": "test-policy", "shared": false, "tenant_id": "45977fa2dbd7482098dd68d0d8970117" } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 120 } Delete firewall policy Verb URI Description DELETE /fw/ firewall_policies/ firewall_policy- id Deletes a firewall policy. Normal Response Code: 204 Error Response Codes: Unauthorized (401), Not Found (404), Conflict (409 ). Conflict error code is returned the firewall policy is in use. This operation does not require a request body. This operation does not return a response body. Example 4.66. Delete firewall policy: JSON request DELETE /v2.0/fw/firewall_policies/1be5e5f7-c45e-49ba-85da-156575b60d50.json User-Agent: python-neutronclient Accept: application/json Example 4.67. Delete firewall policy: JSON response HTTP/1.1 204 No Content Content-Length: 0 Insert firewall rule in firewall policy Verb URI Description PUT /fw/ firewall_policies/ firewall_policy- id/insert_rule Inserts a firewall rule in a firewall policy relative to the position of other rules. Normal Response Code: 200 Error Response Codes: Unauthorized (401), Bad Request (400), Not Found (404). Bad Request error is returned in the case the rule information is missing. Example 4.68. Insert firewall rule in firewall policy: JSON request PUT /v2.0/fw/firewall_policies/41bfef97-af4e-4f6b-a5d3-4678859d2485/ insert_rule.json User-Agent: python-neutronclient Accept: application/json { "firewall_rule_id": "7bc34b8c-8d3b-4ada-a9c8-1f4c11c65692", "insert_after": "a08ef905-0ff6-4784-8374-175fffe7dade", "insert_before": "" } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 121 Example 4.69. Insert firewall rule in firewall policy: Response HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "audited": false, "description": "", "firewall_list": [], "firewall_rules": [ "a08ef905-0ff6-4784-8374-175fffe7dade", "7bc34b8c-8d3b-4ada-a9c8-1f4c11c65692", "8722e0e0-9cc9-4490-9660-8c9a5732fbb0" ], "id": "c69933c1-b472-44f9-8226-30dc4ffd454c", "name": "test-policy", "shared": false, "tenant_id": "45977fa2dbd7482098dd68d0d8970117" } insert_before and insert_after parameters refer to firewall rule uuids already associated with the firewall policy. firewall_rule_id refers to uuid of the rule being inserted. insert_before takes precedence over insert_after and if neither is specified, firewall_rule_is inserted at the first position. Remove firewall rule from firewall policy Verb URI Description PUT /fw/ firewall_policies/ firewall_policy- id/remove_rule Removes a firewall rule from a firewall policy. Normal Response Code: 200 Error Response Codes: Unauthorized (401), Bad Request (400), Not Found (404). Bad Request error is returned if the rule information is missing or when a firewall rule is tried to be removed from a firewall policy to which it is not associated. Example 4.70. Remove firewall rule from firewall policy: JSON request PUT /v2.0/fw/firewall_policies/41bfef97-af4e-4f6b-a5d3-4678859d2485/ remove_rule.json User-Agent: python-neutronclient Accept: application/json { "firewall_rule_id": "7bc34b8c-8d3b-4ada-a9c8-1f4c11c65692" } Example 4.71. Remove firewall rule from firewall policy: JSON response HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 122 "audited": false, "description": "", "firewall_list": [], "firewall_rules": [ "a08ef905-0ff6-4784-8374-175fffe7dade", "8722e0e0-9cc9-4490-9660-8c9a5732fbb0" ], "id": "c69933c1-b472-44f9-8226-30dc4ffd454c", "name": "test-policy", "shared": false, "tenant_id": "45977fa2dbd7482098dd68d0d8970117" } Firewalls Manage firewalls. Table 4.7. Firewall attributes Attribute Type Required CRUDa Default value Validation constraints Notes id uuid-str N/A R generated N/A Unique identifier for the firewall object. tenant_id uuid-str Yes CR Derived from Authentication token N/A Owner of the firewall. Only admin users can specify a tenant identifier other than their own. name String No CRU None N/A Human readable name for the firewall (255 characters limit). Does not have to be unique. description String No CRU None N/A Human readable description for the firewall (1024 characters limit) admin_state_up Bool N/A CRU true {true | false } Administrative state of the firewall. If false (down), firewall does not forward packets and will drop all traffic to/from VMs behind the firewall. status String N/A R N/A N/A Indicates whether firewall resource is currently operational. Possible values include: ACTIVE, DOWN, BUILD, ERROR, PENDING_CREATE, PENDING_UPDATE, or PENDING_DELETE. shared Bool No CRU false {true | false} When set to True makes this firewall rule visible to tenants other than its owner, and can be used in firewall policies not owned by its tenant. firewall_policy_id uuid-str No CRU None valid firewall policy uuid The firewall policy uuid that this firewall is associated with. This firewall will implement the rules contained in the firewall Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 123 Attribute Type Required CRUDa Default value Validation constraints Notes policy represented by this uuid. a•C. Use the attribute in create operations. •R. This attribute is returned in response to show and list operations. •U. You can update the value of this attribute. •D. You can delete the value of this attribute. List firewalls Verb URI Description GET /fw/firewalls Lists firewalls. Normal Response Code: 200 Error Response Codes: Unauthorized (401) This operation does not require a request body. This operation returns a response body. Example 4.72. List firewalls: JSON request GET /v2.0/fw/firewalls.json User-Agent: python-neutronclient Accept: application/json Example 4.73. List firewalls: JSON response { "firewalls": [ { "admin_state_up": true, "description": "", "firewall_policy_id": "c69933c1-b472-44f9-8226-30dc4ffd454c", "id": "3b0ef8f4-82c7-44d4-a4fb-6177f9a21977", "name": "", "status": "ACTIVE", "tenant_id": "45977fa2dbd7482098dd68d0d8970117" } ] } Show firewall details Verb URI Description GET /fw/ firewalls/firewall- id Shows firewall details. Normal Response Code: 200 Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 124 Error Response Codes: Unauthorized (401), Forbidden (403), Not Found (404) This operation does not require a request body. This operation returns a response body. Example 4.74. Show firewall: JSON request GET /v2.0/fw/firewalls/9faaf49f-dd89-4e39-a8c6-101839aa49bc.json User-Agent: python-neutronclient Accept: application/json Example 4.75. Show firewall: JSON response { "firewall": { "admin_state_up": true, "description": "", "firewall_policy_id": "c69933c1-b472-44f9-8226-30dc4ffd454c", "id": "3b0ef8f4-82c7-44d4-a4fb-6177f9a21977", "name": "", "status": "ACTIVE", "tenant_id": "45977fa2dbd7482098dd68d0d8970117" } } Create firewall Verb URI Description POST /fw/firewalls Creates a firewall. Normal Response Code: 201 Error Response Codes: Unauthorized (401), Bad Request (400) This operation requires a request body. This operation returns a response body. Example 4.76. Create firewall: JSON request POST /v2.0/fw/firewalls.json User-Agent: python-neutronclient Accept: application/json { "firewall": { "admin_state_up": true, "firewall_policy_id": "c69933c1-b472-44f9-8226-30dc4ffd454c" } } Example 4.77. Create firewall: JSON response HTTP/1.1 201 Created Content-Type: application/json; charset=UTF-8 Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 125 { "firewall": { "admin_state_up": true, "description": "", "firewall_policy_id": "c69933c1-b472-44f9-8226-30dc4ffd454c", "id": "3b0ef8f4-82c7-44d4-a4fb-6177f9a21977", "name": "", "status": "PENDING_CREATE", "tenant_id": "45977fa2dbd7482098dd68d0d8970117" } } Update firewall Verb URI Description PUT /fw/ firewalls/firewall- id Updates a firewall, provided status is not PENDING_*. Normal Response Code: 200 Error Response Codes: Unauthorized (401), Bad Request (400), Not Found (404) Example 4.78. Update firewall: JSON request PUT /v2.0/fw/firewalls/41bfef97-af4e-4f6b-a5d3-4678859d2485.json User-Agent: python-neutronclient Accept: application/json { "firewall": { "admin_state_up": "false" } } Example 4.79. Update firewall: JSON response HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "firewall": { "admin_state_up": false, "description": "", "firewall_policy_id": "c69933c1-b472-44f9-8226-30dc4ffd454c", "id": "3b0ef8f4-82c7-44d4-a4fb-6177f9a21977", "name": "", "status": "PENDING_UPDATE", "tenant_id": "45977fa2dbd7482098dd68d0d8970117" } } Delete firewall Verb URI Description DELETE /fw/ firewalls/firewall- id Deletes a firewall. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 126 Normal Response Code: 204 Error Response Codes: Unauthorized (401), Not Found (404) This operation does not require a request body. This operation does not return a response body. Example 4.80. Delete firewall: JSON request DELETE /v2.0/fw/firewalls/1be5e5f7-c45e-49ba-85da-156575b60d50.json User-Agent: python-neutronclient Accept: application/json Example 4.81. Delete firewall: JSON response HTTP/1.1 204 No Content Content-Length: 0 Layer-3 networking (router) The Layer-3 networking extension enables OpenStack Networking API users to route packets between subnets, forward packets from internal networks to external ones, and access instances from external networks through floating IPs. The OpenStack Networking layer-3 extension defines these resources: • router. A logical entity that forwards packets across internal subnets and NATs them on external networks through an appropriate external gateway. A router has an interface for each subnet with which it is associated. By default, the IP address of such interface is the subnet's gateway IP. Also, whenever a router is associated with a subnet, a port for that router interface is added to the subnet's network. • floatingip. Represents an external IP address that is mapped to an OpenStack Networking port and, optionally, a specific IP address on a private OpenStack Networking network. A floating IP enables access to an instance on a private network from an external network. Floating IPs can only be defined on networks where the router:external attribute (by the external network extension) is set to True. Table 4.8. Router attributes Attribute Type Required CRUDa Default value Validation constraints Notes id uuid-str N/A R generated N/A Unique identifier for the router. name String No CRU None N/A Human readable name for the router. Does not have to be unique. admin_state_up Bool No CRU true {true | false } Administrative state of the router. status String N/A R N/A N/A Indicates whether or not a router is currently operational. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 127 Attribute Type Required CRUDa Default value Validation constraints Notes tenant_id uuid-str No CR Derived from Authentication token N/A Owner of the router. Only admin users can specify a tenant identifier other than its own. external_gateway_info dict No CRU None No constraint Information on external gateway for the router. a •C. Use the attribute in create operations. •R. This attribute is returned in response to show and list operations. •U. You can update the value of this attribute. •D. You can delete the value of this attribute. Table 4.9. Floating IP attributes Attribute Type Required CRUD Default value Validation constraints Notes id uuid-str N/A R generated N/A Unique identifier for the floating IP instance. floating_network_id uuid-str Yes CR N/A UUID Pattern UUID of the external network where the floating IP is to be created. port_id uuid-str Yes CRU N/A UUID Pattern UUID of the port on an internal OpenStack Networking network that is associated with the floating IP. fixed_ip_address IP Address No CRU None IP address or null Specific IP address on port_id which should be associated with the floating IP. floating_ip_address IP Address N/A R Automatically allocated from pool N/A Address of the floating IP on the external network. tenant_id uuid-str No CR Derived from Authentication token N/A Owner of the floating IP. Only admin users can specify a tenant identifier other than its own. Method URI Description POST /v2.0/routers Creates a logical router. GET /v2.0/routers/{router_id} Shows details for a specified router. PUT /v2.0/routers/{router_id} Updates a logical router. DELETE /v2.0/routers/{router_id} Deletes a logical router and, if present, its external gateway interface. PUT /v2.0/routers/{router_id}/ add_router_interface Adds an internal interface to a logical router. PUT /v2.0/routers/ remove_router_interface Removes an internal interface from a logical router. POST /v2.0/floatingips Creates a floating IP, and, if you specify port information, associates the floating IP with an internal port. GET /v2.0/floatingips/{floatingip_id} Shows details for a specified floating IP. PUT /v2.0/floatingips/{floatingip_id} Updates a floating IP and its association with an internal port. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 128 Method URI Description DELETE /v2.0/floatingips/{floatingip_id} Deletes a floating IP and, if present, its associated port. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 129 Create router Method URI Description POST /v2.0/routers Creates a logical router. This operation creates a new logical router. When it is created, a logical router does not have any internal interface; it is not associated to any subnet. You can optionally specify an external gateway for a router at create time. The external gateway for the router must be plugged into an external network. An external network has its extended field router:external set to true. To specify an external gateway, the identifier of the external network must be passed in the external_gateway_info attribute in the request body, as follows: { "router":{ "external_gateway_info":{ "network_id":"8ca37218-28ff-41cb-9b10-039601ea7e6b" } } } Normal response codes: 201 Error response codes: badRequest (400), unauthorized (401) Request Example 4.82. Create router: JSON request { "router": { "name": "another_router", "external_gateway_info": { "network_id": "8ca37218-28ff-41cb-9b10-039601ea7e6b" }, "admin_state_up": true } } Response Example 4.83. Create router: JSON response { "router": { "status": "ACTIVE", "external_gateway_info": { "network_id": "8ca37218-28ff-41cb-9b10-039601ea7e6b" }, "name": "another_router", "admin_state_up": true, "tenant_id": "6b96ff0cb17a4b859e1e575d221683d3", "id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e" } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 130 Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 131 Show router details Method URI Description GET /v2.0/routers/{router_id} Shows details for a specified router. This example request shows details for a router in JSON format: GET /v2.0/routers/{router_id} Accept: application/json Use the fields query parameter to control which fields are returned in the response body. For information, see Filtering and Column Selection in the OpenStack Networking API v2.0 Reference. Normal response codes: 200 Error response codes: unauthorized (401), forbidden (403), itemNotFound (404) Request This table shows the URI parameters for the show router details request: Name Type Description {router_id} UUID The UUID of the router. This operation does not require a request body. Response Example 4.84. Show router details: JSON response { "routers": [ { "status": "ACTIVE", "external_gateway_info": { "network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8" }, "name": "router1", "admin_state_up": true, "tenant_id": "33a40233088643acb66ff6eb0ebea679", "id": "a9254bdb-2613-4a13-ac4c-adc581fba50d" } ] } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 132 Update router Method URI Description PUT /v2.0/routers/{router_id} Updates a logical router. You can update the name, administrative state, and the external gateway. For more information about how to set the external gateway for a router, see the create router operation. This operation does not enable the update of router interfaces. To update a router, use the add router interface and remove router interface operations. This example updates the external gateway information for a router: PUT /v2.0/routers/{router_id} Accept: application/json Normal response codes: 200 Error response codes: badRequest (400), unauthorized (401), itemNotFound (404) Request This table shows the URI parameters for the update router request: Name Type Description {router_id} UUID The UUID of the router. Example 4.85. Update router: JSON request { "router": { "external_gateway_info": { "network_id": "8ca37218-28ff-41cb-9b10-039601ea7e6b" } } } Response Example 4.86. Update router: JSON response { "router": { "status": "ACTIVE", "external_gateway_info": { "network_id": "8ca37218-28ff-41cb-9b10-039601ea7e6b" }, "name": "another_router", "admin_state_up": true, "tenant_id": "6b96ff0cb17a4b859e1e575d221683d3", "id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e" } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 133 Delete router Method URI Description DELETE /v2.0/routers/{router_id} Deletes a logical router and, if present, its external gateway interface. This operation fails if the router has attached interfaces. Use the remove router interface operation to remove all router interfaces before you delete the router. This example deletes a router: DELETE /v2.0/routers/{router_id} Accept: application/json Normal response codes: 204 Error response codes: unauthorized (401), itemNotFound (404), conflict (409) Request This table shows the URI parameters for the delete router request: Name Type Description {router_id} UUID The UUID of the router. This operation does not require a request body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 134 Add interface to router Method URI Description PUT /v2.0/routers/{router_id}/ add_router_interface Adds an internal interface to a logical router. This operation attaches a subnet to an internal router interface. You must specify either a subnet or port ID in the request body. If you specify both IDs, the operation returns a 400 Bad Request error. If you specify a subnet ID in the request body, the gateway IP address for the subnet is used to create the router interface. If you specify a port ID in the request body, the IP address associated with the port is used to create the router interface. The operation returns a 400 Bad Request error if several IP addresses are associated with the specified port, or if no IP address is associated with the port. The operation returns a 409 Conflict error if the port is already used. The port ID that is returned by this operation can either be the same ID passed in the request body or the ID of a new port created by this operation to attach the specified subnet to the router. After you run this operation, the device ID of this port is set to the router ID, and the device_owner attribute is set to network:router_interface, as shown in this example: { "port":{ "status":"ACTIVE", "name":"", "admin_state_up":true, "network_id":"5307648b-e836-4658-8f1a-ff7536870c64", "tenant_id":"6b96ff0cb17a4b859e1e575d221683d3", "device_owner":"network:router_interface", "mac_address":"fa:16:3e:f7:d1:9c", "fixed_ips":[ { "subnet_id":"a2f1f29d-571b-4533-907f-5803ab96ead1", "ip_address":"10.1.1.1" } ], "id":"3a44f4e5-1694-493a-a1fb-393881c673a4", "device_id":"7177abc4-5ae9-4bb7-b0d4-89e94a4abf3b" } } Normal response codes: 200 Error response codes: badRequest (400), unauthorized (401), itemNotFound (404), conflict (409) Request This table shows the URI parameters for the add interface to router request: Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 135 Name Type Description {router_id} UUID The UUID of the router. Example 4.87. Add interface to router: JSON request { "subnet_id": "a2f1f29d-571b-4533-907f-5803ab96ead1" } Response Example 4.88. Add interface to router: JSON response { "subnet_id": "a2f1f29d-571b-4533-907f-5803ab96ead1", "port_id": "3a44f4e5-1694-493a-a1fb-393881c673a4" } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 136 Remove interface from router Method URI Description PUT /v2.0/routers/ remove_router_interface Removes an internal interface from a logical router. This operation removes an internal router interface, which detaches a subnet from the router. You must specify either a subnet ID or port ID in the request body; this value is used to identify the router interface to remove. You can also specify both a subnet ID and port ID. If you specify both IDs, the subnet ID must correspond to the subnet ID of the first IP address on the port specified by the port ID. Otherwise, the operation returns a 409 Conflict error. The response contains information about the affected router and interface. The operation returns a 404 Not Found if the router or the subnet and port do not exist or are not visible to you. As a consequence of this operation, the port connecting the router with the subnet is removed from the subnet for the network. This example removes an interface from a router: PUT /v2.0/routers/{router_id}/remove_router_interface Accept: application/json Normal response codes: 200 Error response codes: badRequest (400), unauthorized (401), itemNotFound (404), conflict (409) Request Example 4.89. Remove interface from router: JSON request { "subnet_id": "a2f1f29d-571b-4533-907f-5803ab96ead1" } Response Example 4.90. Remove interface from router: JSON response { "id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e", "tenant_id": "2f245a7b-796b-4f26-9cf9-9e82d248fda7", "port_id": "3a44f4e5-1694-493a-a1fb-393881c673a4", "subnet_id": "a2f1f29d-571b-4533-907f-5803ab96ead1" } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 137 Create floating IP Method URI Description POST /v2.0/floatingips Creates a floating IP, and, if you specify port information, associates the floating IP with an internal port. If you do not specify port information in the request, you can issue an PUT request. You can create floating IPs on external networks only. If you specify a network that is not external, such as router:external=False, the operation returns a 400 error. If you do not specify a floating IP address in the request, the operation automatically allocates an address for the floating IP. If the requested floating IP address does not fall in the subnet range for the external network, the operation returns a 400 error. If the requested floating IP address is already in use, the operation returns a 409 error code. You can associate the floating IP with an internal port by using the port ID attribute in the request body. If you specify a port ID that is not valid, the operation returns a 404 error code. You must configure an IP address with the internal OpenStack Networking port associated with the floating IP or the operation returns a 400 error code. Because an OpenStack Networking port might be associated with multiple IP addresses, you can use the fixed_ip_address attribute in the request body to associate a particular IP address with the floating IP. By default, this operation associates the floating IP with a single IP address that is configured on a port. Therefore, if a port has multiple IP addresses, you must specify the fixed_ip_address attribute. If you specify an IP address that is not valid in the fixed_ip_address attribute, the operation returns a 400 error code. If the internal OpenStack Networking port and specified IP address are already associated with another floating IP, the operation returns a 409 error code. Normal response codes: 200 Error response codes: badRequest (400), unauthorized (401), conflict (409) Request Example 4.91. Create floating IP: JSON request { "floatingip": { "floating_network_id": "376da547-b977-4cfe-9cba-275c80debf57", "port_id": "ce705c24-c1ef-408a-bda3-7bbd946164ab" } } Response Example 4.92. Create floating IP: JSON response { Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 138 "floatingip": { "router_id": "d23abc8d-2991-4a55-ba98-2aaea84cc72f", "tenant_id": "4969c491a3c74ee4af974e6d800c62de", "floating_network_id": "376da547-b977-4cfe-9cba-275c80debf57", "fixed_ip_address": "10.0.0.3", "floating_ip_address": "172.24.4.228", "port_id": "ce705c24-c1ef-408a-bda3-7bbd946164ab", "id": "2f245a7b-796b-4f26-9cf9-9e82d248fda7" } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 139 Show floating IP details Method URI Description GET /v2.0/floatingips/{floatingip_id} Shows details for a specified floating IP. Use the fields query parameter to control which fields are returned in the response body. For information, see Filtering and Column Selection in the OpenStack Networking API v2.0 Reference. This example request shows details for a floating IP in JSON format. This example also filters the result by the fixed_ip_address and floating_ip_address fields. GET /v2.0/floatingips/{floatingip_id}?fields=fixed_ip_address&fields= floating_ip_address Accept: application/json Normal response codes: 200 Error response codes: unauthorized (401), forbidden (403), itemNotFound (404) Request This table shows the URI parameters for the show floating ip details request: Name Type Description {floatingip_id} UUID The UUID of the floating IP. This operation does not require a request body. Response Example 4.93. Show floating IP details: JSON response { "floatingip": { "fixed_ip_address": "10.0.0.3", "floating_ip_address": "172.24.4.228" } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 140 Update floating IP Method URI Description PUT /v2.0/floatingips/{floatingip_id} Updates a floating IP and its association with an internal port. The association process is the same as the process for the create floating IP operation. To disassociate a floating IP from a port, set the port_id attribute to null or omit it from the request body. This example updates a floating IP: PUT /v2.0/floatingips/{floatingip_id} Accept: application/json Depending on the request body that you submit, this request associates a port with or disassociates a port from a floating IP. Normal response codes: 200 Error response codes: badRequest (400), unauthorized (401), itemNotFound (404), conflict (409) Request This table shows the URI parameters for the update floating ip request: Name Type Description {floatingip_id} UUID The UUID of the floating IP. Example 4.94. Update floating IP (associate port): JSON { "floatingip": { "port_id": "fc861431-0e6c-4842-a0ed-e2363f9bc3a8" } } Example 4.95. Update floating IP (disassociate port): JSON { "floatingip": { "port_id": null } } Response Example 4.96. Update floating IP (associate port): JSON { "floatingip": { "router_id": "d23abc8d-2991-4a55-ba98-2aaea84cc72f", Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 141 "tenant_id": "4969c491a3c74ee4af974e6d800c62de", "floating_network_id": "376da547-b977-4cfe-9cba-275c80debf57", "fixed_ip_address": "10.0.0.4", "floating_ip_address": "172.24.4.228", "port_id": "fc861431-0e6c-4842-a0ed-e2363f9bc3a8", "id": "2f245a7b-796b-4f26-9cf9-9e82d248fda7" } } Example 4.97. Update floating IP (disassociate port): JSON { "floatingip": { "router_id": "d23abc8d-2991-4a55-ba98-2aaea84cc72f", "tenant_id": "4969c491a3c74ee4af974e6d800c62de", "floating_network_id": "376da547-b977-4cfe-9cba-275c80debf57", "fixed_ip_address": null, "floating_ip_address": "172.24.4.228", "port_id": null, "id": "2f245a7b-796b-4f26-9cf9-9e82d248fda7" } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 142 Delete floating IP Method URI Description DELETE /v2.0/floatingips/{floatingip_id} Deletes a floating IP and, if present, its associated port. This example deletes a floating IP: DELETE /v2.0/floatingips/{floatingip_id} Accept: application/json Normal response codes: 204 Error response codes: unauthorized (401), itemNotFound (404) Request This table shows the URI parameters for the delete floating ip request: Name Type Description {floatingip_id} UUID The UUID of the floating IP. This operation does not require a request body. Load Balancer as a Service (LBaaS) The LBaaS extension enables OpenStack tenants to load-balance their VM traffic. The extension enables you to: • Load-balance client traffic from one network to application services, such as VMs, on the same or a different network. • Load-balance several protocols, such as TCP and HTTP. • Monitor the health of application services. • Support session persistence. Concepts This extension introduces these concepts: VIP The primary load balancing configuration object. Specifies the virtual IP address and port where client traffic is received. Also defines other details such as the load balancing method to be used, protocol, and so on. This entity is sometimes known in load-balancing products as a virtual server, vserver, or listener. pool A logical set of devices, such as web servers, that you group together to receive and process traffic. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 143 The load balancing function chooses which member of the pool handles the new requests or connections received on the VIP address. Each VIP has one pool. pool member The application that runs on the back-end server. health monitor Determines whether or not back-end members of the VIP pool can process a request. A pool can have several health monitors associated with it. The LBaaS extension supports these types of health monitors: • PING. Pings the members by using ICMP. • TCP. Connects to the members by using TCP. • HTTP. Sends an HTTP request to the member. • HTTPS. Sends a secure HTTP request to the member. When a pool has several monitors associated with it, all monitors check each member of the pool. If any monitor declares a member as unhealthy, the member status is changed to inactive and the member does not participate in the load balancing for the pool. All monitors must declare the member to be healthy for it to stay active. session persistence Forces connections or requests in the same session to be processed by the same member as long as it is active. The LBaaS extension supports these types of persistence: • SOURCE_IP. All connections that originate from the same source IP address are handled by the same member of the pool. • HTTP_COOKIE. The load balancing function creates a cookie on the first request from a client. Subsequent requests that contain the same cookie value are handled by the same member of the pool. • APP_COOKIE. The load balancing function relies on a cookie established by the back-end application. All requests with the same cookie value are handled by the same member of the pool. Absence of session_persistence attribute means no session persistence mechanism is used. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 144 When no session persistence is used, the session_persistence attribute does not appear in the API response, instead of returning null. You can clear session persistence for the VIP by sending null in session_persistence attribute in a VIP update request. High-level task flow To use the LBaaS extension to configure load balancing, you must complete these high-level tasks: 1. Create a pool, which is initially empty. 2. Create one or several members in the pool. 3. Create one or several health monitors. 4. Associate the health monitors with the pool. 5. Create a VIP that is associated with the pool. VIP operations Method URI Description GET /v2.0/lb/vips Lists VIPs. POST /v2.0/lb/vips Creates a load balancer VIP. GET /v2.0/lb/vips/{vip_id} Shows details for a specified VIP. PUT /v2.0/lb/vips/{vip_id} Updates a specified load balancer VIP. DELETE /v2.0/lb/vips/{vip_id} Deletes a specified load balancer VIP. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 145 List VIPs Method URI Description GET /v2.0/lb/vips Lists VIPs. Normal response codes: 200 Error response codes: unauthorized (401), forbidden (403) Request This operation does not require a request body. Response Example 4.98. List VIPs: JSON response { "vips": [ { "status": "ACTIVE", "protocol": "HTTP", "description": "", "admin_state_up": true, "subnet_id": "8032909d-47a1-4715-90af-5153ffe39861", "tenant_id": "83657cfcdfe44cd5920adaf26c48ceea", "connection_limit": 1000, "pool_id": "72741b06-df4d-4715-b142-276b6bce75ab", "session_persistence": { "cookie_name": "MyAppCookie", "type": "APP_COOKIE" }, "address": "10.0.0.10", "protocol_port": 80, "port_id": "b5a743d6-056b-468b-862d-fb13a9aa694e", "id": "4ec89087-d057-4e2c-911f-60a3b47ee304", "name": "my-vip" } ] } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 146 Create a load balancer VIP Method URI Description POST /v2.0/lb/vips Creates a load balancer VIP. Normal response codes: 201 Error response codes: badRequest (400), unauthorized (401) Request Example 4.99. Create a load balancer VIP: JSON request { "vip": { "protocol": "HTTP", "name": "NewVip", "admin_state_up": true, "subnet_id": "8032909d-47a1-4715-90af-5153ffe39861", "pool_id": "61b1f87a-7a21-4ad3-9dda-7f81d249944f", "protocol_port": "80" } } Response Example 4.100. Create a load balancer VIP: JSON response { "vip": { "status": "PENDING_CREATE", "protocol": "HTTP", "description": "", "admin_state_up": true, "subnet_id": "8032909d-47a1-4715-90af-5153ffe39861", "tenant_id": "83657cfcdfe44cd5920adaf26c48ceea", "connection_limit": -1, "pool_id": "61b1f87a-7a21-4ad3-9dda-7f81d249944f", "address": "10.0.0.11", "protocol_port": 80, "port_id": "f7e6fe6a-b8b5-43a8-8215-73456b32e0f5", "id": "c987d2be-9a3c-4ac9-a046-e8716b1350e2", "name": "NewVip" } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 147 Show VIP details Method URI Description GET /v2.0/lb/vips/{vip_id} Shows details for a specified VIP. Normal response codes: 200 Error response codes: unauthorized (401), forbidden (403), itemNotFound (404) Request This table shows the URI parameters for the show vip details request: Name Type Description {vip_id} UUID The UUID for the VIP. This operation does not require a request body. Response Example 4.101. Show VIP details: JSON response { "vip": { "status": "ACTIVE", "protocol": "HTTP", "description": "", "admin_state_up": true, "subnet_id": "8032909d-47a1-4715-90af-5153ffe39861", "tenant_id": "83657cfcdfe44cd5920adaf26c48ceea", "connection_limit": 1000, "pool_id": "72741b06-df4d-4715-b142-276b6bce75ab", "session_persistence": { "cookie_name": "MyAppCookie", "type": "APP_COOKIE" }, "address": "10.0.0.10", "protocol_port": 80, "port_id": "b5a743d6-056b-468b-862d-fb13a9aa694e", "id": "4ec89087-d057-4e2c-911f-60a3b47ee304", "name": "my-vip" } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 148 Update VIP Method URI Description PUT /v2.0/lb/vips/{vip_id} Updates a specified load balancer VIP. Normal response codes: 200 Error response codes: badRequest (400), unauthorized (401), forbidden (403), itemNotFound (404) Request This table shows the URI parameters for the update vip request: Name Type Description {vip_id} UUID The UUID for the VIP. Example 4.102. Update VIP: JSON request { "vip": { "connection_limit": "1000" } } Response Example 4.103. Update VIP: JSON response { "vip": { "status": "PENDING_UPDATE", "protocol": "HTTP", "description": "", "admin_state_up": true, "subnet_id": "8032909d-47a1-4715-90af-5153ffe39861", "tenant_id": "83657cfcdfe44cd5920adaf26c48ceea", "connection_limit": 1000, "pool_id": "61b1f87a-7a21-4ad3-9dda-7f81d249944f", "address": "10.0.0.11", "protocol_port": 80, "port_id": "f7e6fe6a-b8b5-43a8-8215-73456b32e0f5", "id": "c987d2be-9a3c-4ac9-a046-e8716b1350e2", "name": "NewVip" } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 149 Delete VIP Method URI Description DELETE /v2.0/lb/vips/{vip_id} Deletes a specified load balancer VIP. Normal response codes: 204 Error response codes: unauthorized (401), itemNotFound (404), conflict (409) Request This table shows the URI parameters for the delete vip request: Name Type Description {vip_id} UUID The UUID for the VIP. This operation does not require a request body. Pool operations This section discusses operations for managing load balancer pools through the Load balancing as a service extension. Table 4.10. Pool Attributes Attribute Type Required CRUD a Default Value Validation Constraints Notes id uuid-str N/A R generated N/A Unique identifier for the pool. tenant_id uuid-str Yes CR Derived from authentication token. N/A Owner of the pool. Only an admin user can specify a tenant identifier other than its own vip_id uuid-str No R None UUID pattern. The vip that the pool associated with. name String No CRU None N/A Human readable name for the pool. Does not have to be unique. description String No CRU None N/A Human readable description for the pool. subnet_id uuid-str No CR None UUID pattern. The network that pool members belong to. protocol String Yes CR None { "TCP" | "HTTP" | "HTTPS" } The protocol of the pool. lb_method String Yes CRU None None The algorithm used to distribute load between the members of the pool. health_monitors uuid-list No CRU None N/A List of health monitors to associate with the pool. members uuid-list No R None N/A List of members that belong to the pool. admin_state_up Bool No CRU true {true | false } Administrative state of the pool. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 150 Attribute Type Required CRUD a Default Value Validation Constraints Notes status String N/A R N/A N/A Indicates whether a pool is currently operational or not. a•C. Use the attribute in create operations. •R. This attribute is returned in response to show and list operations. •U. You can update the value of this attribute. •D. You can delete the value of this attribute. Method URI Description GET /v2.0/lb/pools Lists pools. POST /v2.0/lb/pools Creates a load balancer pool. GET /v2.0/lb/pools/{pool_id} Shows details for a specified pool. PUT /v2.0/lb/pools/{pool_id} Updates a specified load balancer pool. DELETE /v2.0/lb/pools/{pool_id} Deletes a specified load balancer pool. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 151 List pools Method URI Description GET /v2.0/lb/pools Lists pools. Normal response codes: 200 Error response codes: unauthorized (401), forbidden (403) Request This operation does not require a request body. Response Example 4.104. List pools: JSON response { "pools": [ { "status": "ACTIVE", "lb_method": "ROUND_ROBIN", "protocol": "HTTP", "description": "", "health_monitors": [], "subnet_id": "b338d9c6-beec-4404-8e1a-b608c324a8ad", "tenant_id": "5ef70662f8b34079a6eddb8da9d75fe8", "admin_state_up": true, "name": "my-pool", "health_monitors_status": [], "members": [], "provider": "haproxy", "status_description": null, "id": "e019fadf-5083-40ad-9480-4553343995b6", "vip_id": null } ] } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 152 Create a load balancer pool Method URI Description POST /v2.0/lb/pools Creates a load balancer pool. Normal response codes: 201 Error response codes: badRequest (400), unauthorized (401) Request Example 4.105. Create a load balancer pool: JSON request { "pool": { "subnet_id": "8032909d-47a1-4715-90af-5153ffe39861", "lb_method": "ROUND_ROBIN", "protocol": "TCP", "name": "NewPool", "admin_state_up": true } } Response Example 4.106. Create a load balancer pool: JSON response { "pool": { "status": "PENDING_CREATE", "lb_method": "ROUND_ROBIN", "protocol": "HTTP", "description": "", "health_monitors": [], "subnet_id": "b338d9c6-beec-4404-8e1a-b608c324a8ad", "tenant_id": "5ef70662f8b34079a6eddb8da9d75fe8", "admin_state_up": true, "name": "my-pool", "health_monitors_status": [], "members": [], "provider": "haproxy", "status_description": null, "id": "e019fadf-5083-40ad-9480-4553343995b6", "vip_id": null } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 153 Show pool details Method URI Description GET /v2.0/lb/pools/{pool_id} Shows details for a specified pool. Normal response codes: 200 Error response codes: unauthorized (401), forbidden (403), itemNotFound (404) Request This table shows the URI parameters for the show pool details request: Name Type Description {pool_id} UUID The UUID for the pool. This operation does not require a request body. Response Example 4.107. Show pool details: JSON response { "pool": { "status": "ACTIVE", "lb_method": "ROUND_ROBIN", "protocol": "HTTP", "description": "", "health_monitors": [], "subnet_id": "b338d9c6-beec-4404-8e1a-b608c324a8ad", "tenant_id": "5ef70662f8b34079a6eddb8da9d75fe8", "admin_state_up": true, "name": "my-pool", "health_monitors_status": [], "members": [], "provider": "haproxy", "status_description": null, "id": "e019fadf-5083-40ad-9480-4553343995b6", "vip_id": null } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 154 Update pool Method URI Description PUT /v2.0/lb/pools/{pool_id} Updates a specified load balancer pool. Normal response codes: 200 Error response codes: badRequest (400), unauthorized (401), forbidden (403), itemNotFound (404) Request This table shows the URI parameters for the update pool request: Name Type Description {pool_id} UUID The UUID for the pool. Example 4.108. Update pool: JSON request { "pool": { "name": "my-updated-pool" } } Response Example 4.109. Update pool: JSON response { "pool": { "status": "PENDING_UPDATE", "lb_method": "ROUND_ROBIN", "protocol": "HTTP", "description": "", "health_monitors": [], "subnet_id": "b338d9c6-beec-4404-8e1a-b608c324a8ad", "tenant_id": "5ef70662f8b34079a6eddb8da9d75fe8", "admin_state_up": true, "name": "my-updated-pool", "health_monitors_status": [], "members": [], "provider": "haproxy", "status_description": null, "id": "e019fadf-5083-40ad-9480-4553343995b6", "vip_id": null } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 155 Delete pool Method URI Description DELETE /v2.0/lb/pools/{pool_id} Deletes a specified load balancer pool. Normal response codes: 204 Error response codes: unauthorized (401), itemNotFound (404), conflict (409) Request This table shows the URI parameters for the delete pool request: Name Type Description {pool_id} UUID The UUID for the pool. This operation does not require a request body. Member operations This section discusses operations for managing pool members through the Load balancing as a service extension. Table 4.11. Member Attributes Attribute Type Required CRUD a Default value Validation constraints Notes id uuid-str N/A R generated N/A Unique identifier for the member. tenant_id uuid-str Yes CR Derived from authentication token. N/A Owner of the member. Only an admin user can specify a tenant identifier other than its own. pool_id uuid-str Yes CRU None UUID pattern. The pool that the member belongs to. address IP Yes CR None IP address or null. The IP address of the member. protocol_port Integer Yes CR None [0..65535] The port on which the application is hosted. weight Integer No CRU 1 [0..256] The weight of a member determines the portion of requests or connections it services compared to the other members of the pool. A value of 0 means the member does not participate in load-balancing but still accepts persistent connections. admin_state_up Bool No CRU true {true | false } Administrative state of the member. status String N/A R N/A N/A Indicates whether or not a member is currently operational. a•C. Use the attribute in create operations. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 156 •R. This attribute is returned in response to show and list operations. •U. You can update the value of this attribute. •D. You can delete the value of this attribute. Method URI Description GET /v2.0/lb/members Lists members. POST /v2.0/lb/members Creates a load balancer member. GET /v2.0/lb/members/{member_id} Shows details for a specified member. PUT /v2.0/lb/members/{member_id} Updates a specified load balancer member. DELETE /v2.0/lb/members/{member_id} Deletes a specified load balancer member. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 157 List members Method URI Description GET /v2.0/lb/members Lists members. Normal response codes: 200 Error response codes: unauthorized (401), forbidden (403) Request This operation does not require a request body. Response Example 4.110. List members: JSON response { "members": [ { "status": "ACTIVE", "weight": 1, "admin_state_up": true, "tenant_id": "83657cfcdfe44cd5920adaf26c48ceea", "pool_id": "72741b06-df4d-4715-b142-276b6bce75ab", "address": "10.0.0.4", "protocol_port": 80, "id": "701b531b-111a-4f21-ad85-4795b7b12af6" }, { "status": "ACTIVE", "weight": 1, "admin_state_up": true, "tenant_id": "83657cfcdfe44cd5920adaf26c48ceea", "pool_id": "72741b06-df4d-4715-b142-276b6bce75ab", "address": "10.0.0.3", "protocol_port": 80, "id": "beb53b4d-230b-4abd-8118-575b8fa006ef" } ] } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 158 Create a load balancer member Method URI Description POST /v2.0/lb/members Creates a load balancer member. Normal response codes: 201 Error response codes: badRequest (400), unauthorized (401) Request Example 4.111. Create a load balancer member: JSON request { "member": { "protocol_port": "8080", "address": "10.0.0.5", "pool_id": "7803631d-f181-4500-b3a2-1b68ba2a75fd", "admin_state_up": true } } Response Example 4.112. Create a load balancer member: JSON response { "member": { "status": "PENDING_CREATE", "protocol_port": 8080, "weight": 1, "admin_state_up": true, "tenant_id": "4fd44f30292945e481c7b8a0c8908869", "pool_id": "7803631d-f181-4500-b3a2-1b68ba2a75fd", "address": "10.0.0.5", "status_description": null, "id": "48a471ea-64f1-4eb6-9be7-dae6bbe40a0f" } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 159 Show member details Method URI Description GET /v2.0/lb/members/{member_id} Shows details for a specified member. Normal response codes: 200 Error response codes: unauthorized (401), forbidden (403), itemNotFound (404) Request This table shows the URI parameters for the show member details request: Name Type Description {member_id} UUID The UUID for the member. This operation does not require a request body. Response Example 4.113. Show member details: JSON response { "member": { "status": "PENDING_CREATE", "protocol_port": 8080, "weight": 1, "admin_state_up": true, "tenant_id": "4fd44f30292945e481c7b8a0c8908869", "pool_id": "7803631d-f181-4500-b3a2-1b68ba2a75fd", "address": "10.0.0.5", "status_description": null, "id": "48a471ea-64f1-4eb6-9be7-dae6bbe40a0f" } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 160 Update member Method URI Description PUT /v2.0/lb/members/{member_id} Updates a specified load balancer member. Normal response codes: 200 Error response codes: badRequest (400), unauthorized (401), forbidden (403), itemNotFound (404) Request This table shows the URI parameters for the update member request: Name Type Description {member_id} UUID The UUID for the member. Example 4.114. Update member: JSON request { "member": { "admin_state_up": false } } Response Example 4.115. Update member: JSON response { "member": { "status": "PENDING_UPDATE", "protocol_port": 8080, "weight": 1, "admin_state_up": false, "tenant_id": "4fd44f30292945e481c7b8a0c8908869", "pool_id": "7803631d-f181-4500-b3a2-1b68ba2a75fd", "address": "10.0.0.5", "status_description": null, "id": "48a471ea-64f1-4eb6-9be7-dae6bbe40a0f" } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 161 Delete member Method URI Description DELETE /v2.0/lb/members/{member_id} Deletes a specified load balancer member. Normal response codes: 204 Error response codes: unauthorized (401), itemNotFound (404), conflict (409) Request This table shows the URI parameters for the delete member request: Name Type Description {member_id} UUID The UUID for the member. This operation does not require a request body. Health monitor operations This section discusses operations for managing load balancer health monitors through the LBaaS extension. Table 4.12. Health monitor attributes Attribute Type Required CRUD a Default value Validation constraints Notes id uuid-str N/A R generated N/A Unique ID for the health monitor. tenant_id uuid-str Yes CR Derived from authentication token. N/A Owner of the health monitor. Only an admin user can specify a tenant identifier other than its own. type String Yes CR None {"PING" | "TCP" | "HTTP" | "HTTPS"} The type of probe send by load balancer to verify member state delay Integer Yes CRU None non-negative The time in seconds between sending probes to members. timeout uuid-str Yes CRU None non-negative The maximum number of seconds for a monitor to wait for a connection to be established before it times out. The value must be less than the delay value. max_retries Integer Yes CRU None [1..10] Number of allowed connection failures before changing the member's status to INACTIVE. http_method String Nob CRU GET None The HTTP method used for requests by the monitor. url_path String Nob CRU / None The HTTP path of the request sent by the monitor to test a member's health. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 162 Attribute Type Required CRUD a Default value Validation constraints Notes This must be a string beginning with a / (forward slash). expected_codes String Nob CRU 200 Single value, such as 200, list, such as 200, 202, or range, such as 200-204. The list of HTTP status codes expected in response from the member to declare it healthy. admin_state_up Bool No CRU true {true | false } Administrative state of the health monitor. status String N/A R N/A N/A Indicates whether or not a health monitor is currently operational. a•C. Use the attribute in create operations. •R. This attribute is returned in response to show and list operations. •U. You can update the value of this attribute. •D. You can delete the value of this attribute. bRequired if type is HTTP or HTTPS. Method URI Description POST /v2.0/lb/pools/{pool_id}/ health_monitors Associates a health monitor with a specified pool. DELETE /v2.0/lb/pools/{pool_id}/ health_monitors/ {health_monitor_id} Disassociates a specified health monitor from a pool. GET /v2.0/lb/healthmonitors Lists health monitors. POST /v2.0/lb/healthmonitors Creates a load balancer health monitor. GET /v2.0/lb/healthmonitors/ {health_monitor_id} Shows details for a specified health monitor. PUT /v2.0/lb/healthmonitors/ {health_monitor_id} Updates a specified load balancer health monitor. DELETE /v2.0/lb/healthmonitors/ {health_monitor_id} Deletes a specified load balancer health monitor. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 163 Associate health monitor with pool Method URI Description POST /v2.0/lb/pools/{pool_id}/ health_monitors Associates a health monitor with a specified pool. Normal response codes: 201 Error response codes: badRequest (400), unauthorized (401) Request This table shows the URI parameters for the associate health monitor with pool request: Name Type Description {pool_id} UUID The UUID for the pool. Example 4.116. Associate health monitor with pool: JSON request { "health_monitor": { "id": "b624decf-d5d3-4c66-9a3d-f047e7786181" } } Response Example 4.117. Associate health monitor with pool: JSON response { "health_monitor": {} } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 164 Disassociate health monitor from pool Method URI Description DELETE /v2.0/lb/pools/{pool_id}/ health_monitors/ {health_monitor_id} Disassociates a specified health monitor from a pool. Normal response codes: 204 Error response codes: unauthorized (401), itemNotFound (404), conflict (409) Request This table shows the URI parameters for the disassociate health monitor from pool request: Name Type Description {pool_id} UUID The UUID for the pool. {health_monitor_id} UUID The UUID for the health monitor. This operation does not require a request body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 165 List health monitors Method URI Description GET /v2.0/lb/healthmonitors Lists health monitors. Normal response codes: 200 Error response codes: unauthorized (401), forbidden (403) Request This operation does not require a request body. Response Example 4.118. List health monitors: JSON response { "health_monitors": [ { "admin_state_up": true, "tenant_id": "83657cfcdfe44cd5920adaf26c48ceea", "delay": 10, "max_retries": 1, "timeout": 1, "type": "PING", "id": "466c8345-28d8-4f84-a246-e04380b0461d" }, { "admin_state_up": true, "tenant_id": "83657cfcdfe44cd5920adaf26c48ceea", "delay": 5, "expected_codes": "200", "max_retries": 2, "http_method": "GET", "timeout": 2, "url_path": "/", "type": "HTTP", "id": "5d4b5228-33b0-4e60-b225-9b727c1a20e7" } ] } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 166 Create a load balancer health monitor Method URI Description POST /v2.0/lb/healthmonitors Creates a load balancer health monitor. Normal response codes: 201 Error response codes: badRequest (400), unauthorized (401) Request Example 4.119. Create a load balancer health monitor: JSON request { "health_monitor": { "delay": "1", "max_retries": "1", "type": "HTTP", "timeout": "1", "admin_state_up": true } } Response Example 4.120. Create a load balancer health monitor: JSON response { "health_monitor": { "admin_state_up": true, "tenant_id": "4fd44f30292945e481c7b8a0c8908869", "delay": 1, "expected_codes": "200", "max_retries": 1, "http_method": "GET", "timeout": 1, "pools": [], "url_path": "/", "type": "HTTP", "id": "b624decf-d5d3-4c66-9a3d-f047e7786181" } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 167 Show health monitor details Method URI Description GET /v2.0/lb/healthmonitors/ {health_monitor_id} Shows details for a specified health monitor. Normal response codes: 200 Error response codes: unauthorized (401), forbidden (403), itemNotFound (404) Request This operation does not require a request body. Response Example 4.121. Show health monitor details: JSON response { "health_monitor": { "admin_state_up": true, "tenant_id": "83657cfcdfe44cd5920adaf26c48ceea", "delay": 5, "expected_codes": "200", "max_retries": 2, "http_method": "GET", "timeout": 2, "url_path": "/", "type": "HTTP", "id": "5d4b5228-33b0-4e60-b225-9b727c1a20e7" } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 168 Update health monitor Method URI Description PUT /v2.0/lb/healthmonitors/ {health_monitor_id} Updates a specified load balancer health monitor. Normal response codes: 200 Error response codes: badRequest (400), unauthorized (401), forbidden (403), itemNotFound (404) Request Example 4.122. Update health monitor: JSON request { "health_monitor": { "delay": "3" } } Response Example 4.123. Update health monitor: JSON response { "health_monitor": { "admin_state_up": true, "tenant_id": "4fd44f30292945e481c7b8a0c8908869", "delay": 3, "expected_codes": "200", "max_retries": 1, "http_method": "GET", "timeout": 1, "pools": [], "url_path": "/", "type": "HTTP", "id": "b624decf-d5d3-4c66-9a3d-f047e7786181" } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 169 Delete health monitor Method URI Description DELETE /v2.0/lb/healthmonitors/ {health_monitor_id} Deletes a specified load balancer health monitor. Normal response codes: 204 Error response codes: unauthorized (401), itemNotFound (404), conflict (409) Metering labels and rules Create, modify, and delete OpenStack Layer3 metering labels and rules. Method URI Description GET /v2.0/metering-labels Lists all l3 metering labels that belong to the specified tenant. POST /v2.0/metering-labels Creates a l3 metering label. GET /v2.0/metering-labels/ {metering_label_id} Shows informations for a specified metering label. DELETE /v2.0/metering-labels/ {metering_label_id} Deletes a l3 metering label. GET /v2.0/metering-label-rules Lists a summary of all l3 metering label rules belonging to the specified tenant. POST /v2.0/metering-label-rules Creates a l3 metering label rule. GET /v2.0/metering-label-rules/ {metering-label-rule-id} Shows detailed informations for a specified metering label rule. DELETE /v2.0/metering-label-rules/ {metering-label-rule-id} Deletes a specified l3 metering label rule. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 170 List metering labels Method URI Description GET /v2.0/metering-labels Lists all l3 metering labels that belong to the specified tenant. The list includes the unique ID for each metering labels. This operation does not require a request body. This operation returns a response body. Normal response codes: 200 Error response codes: unauthorized (401) Request Example 4.124. List metering labels: JSON request GET /v2.0/metering/metering-labels HTTP/1.1 Host: controlnode:9696 User-Agent: python-neutronclient Content-Type: application/json Accept: application/json X-Auth-Token: c52a1b304fec4ca0ac85dc1741eec6e2 This operation does not require a request body. Response Example 4.125. List metering labels: JSON response { "metering_labels": [ { "tenant_id": "45345b0ee1ea477fac0f541b2cb79cd4", "description": "label1 description", "name": "label1", "id": "a6700594-5b7a-4105-8bfe-723b346ce866" }, { "tenant_id": "45345b0ee1ea477fac0f541b2cb79cd4", "description": "label2 description", "name": "label2", "id": "e131d186-b02d-4c0b-83d5-0c0725c4f812" } ] } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 171 Create metering label Method URI Description POST /v2.0/metering-labels Creates a l3 metering label. This operation requires a request body. The following table describes the required and optional attributes in the request body: Table 4.13. Create Metering label rule Request Attributes Attribute Required Description name Required The name of the metering label. description Optional Description for the metering label. This operation returns a response body, which contains the following informations about the metering label: • name. Name of the metering label. • description. Description of the metering label. • tenant_id. The tenant ID for the specified metering label. • id. The metering label ID Normal response codes: 201 Error response codes: badRequest (400), unauthorized (401) Request Example 4.126. Create metering label: JSON request { "metering_label": { "name": "label1", "description": "description of label1" } } Response Example 4.127. Create metering label: JSON response { "metering_label": { "tenant_id": "45345b0ee1ea477fac0f541b2cb79cd4", "description": "description of label1", "name": "label1", "id": "bc91b832-8465-40a7-a5d8-ba87de442266" Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 172 } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 173 Show metering label Method URI Description GET /v2.0/metering-labels/ {metering_label_id} Shows informations for a specified metering label. This operation does not require a request body. This operation returns a response body that contains the description, name, ID. Normal response codes: 200 Error response codes: unauthorized (401), itemNotFound (404) Request This table shows the URI parameters for the show metering label request: Name Type Description {metering_label_id} Uuid The unique identifier of the metering label. Example 4.128. Show metering label: JSON request GET /v2.0/metering/metering-labels/a6700594-5b7a-4105-8bfe-723b346ce866 HTTP/ 1.1 Host: controlnode:9696 User-Agent: python-neutronclient Content-Type: application/json Accept: application/json X-Auth-Token: c52a1b304fec4ca0ac85dc1741eec6e2 This operation does not require a request body. Response Example 4.129. Show metering label: JSON response { "metering_label": { "tenant_id": "45345b0ee1ea477fac0f541b2cb79cd4", "description": "label1 description", "name": "label1", "id": "a6700594-5b7a-4105-8bfe-723b346ce866" } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 174 Delete metering label Method URI Description DELETE /v2.0/metering-labels/ {metering_label_id} Deletes a l3 metering label. This operation deletes a l3 metering label. This operation does not require a request body. This operation does not return a response body. Normal response codes: 204 Error response codes: unauthorized (401), itemNotFound (404) Request This table shows the URI parameters for the delete metering label request: Name Type Description {metering_label_id} Uuid The unique identifier of the metering label. Example 4.130. Delete metering label: JSON request DELETE /v2.0/metering/metering-labels/a6700594-5b7a-4105-8bfe-723b346ce866 HTTP/1.1 Host: controlnode:9696 User-Agent: python-neutronclient Content-Type: application/json Accept: application/json X-Auth-Token: c52a1b304fec4ca0ac85dc1741eec6e2 This operation does not require a request body. Response Example 4.131. Delete metering label: JSON response status: 204 This operation does not return a response body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 175 List metering label rules Method URI Description GET /v2.0/metering-label-rules Lists a summary of all l3 metering label rules belonging to the specified tenant. The list provides the unique ID for each metering label rule. This operation does not require a request body. This operation returns a response body. Normal response codes: 200 Error response codes: unauthorized (401) Request Example 4.132. List metering label rules: JSON request GET /v2.0/metering/metering-label-rules HTTP/1.1 Host: controlnode:9696 User-Agent: python-neutronclient Content-Type: application/json Accept: application/json X-Auth-Token: c52a1b304fec4ca0ac85dc1741eec6e2 This operation does not require a request body. Response Example 4.133. List metering label rules: JSON response { "metering_label_rules": [ { "remote_ip_prefix": "20.0.0.0/24", "direction": "ingress", "metering_label_id": "e131d186-b02d-4c0b-83d5-0c0725c4f812", "id": "9536641a-7d14-4dc5-afaf-93a973ce0eb8", "excluded": false }, { "remote_ip_prefix": "10.0.0.0/24", "direction": "ingress", "metering_label_id": "e131d186-b02d-4c0b-83d5-0c0725c4f812", "id": "ffc6fd15-40de-4e7d-b617-34d3f7a93aec", "excluded": false } ] } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 176 Create metering label rule Method URI Description POST /v2.0/metering-label-rules Creates a l3 metering label rule. This operation requires a request body. The following table describes the required and optional attributes in the request body: Table 4.14. Create Metering label rule Request Attributes Attribute Required Description direction Optional Ingress or egress: The direction in which metering rule is applied. Default: ingress metering_label_id Required The meteting label ID to associate with this metering rule. excluded Optional Specify whether the remote_ip_prefix will be excluded or not from traffic counters of the metering label, ie: to not count the traffic of a specific IP address of a range. Default: False remote_ip_prefix Required The remote IP prefix to be associated with this metering rule. packet. This operation returns a response body. Normal response codes: 201 Error response codes: badRequest (400), unauthorized (401), itemNotFound (404), buildInProgress (409) Request Example 4.134. Create metering label rule: JSON request { "metering_label_rule": { "remote_ip_prefix": "10.0.1.0/24", "direction": "ingress", "metering_label_id": "e131d186-b02d-4c0b-83d5-0c0725c4f812" } } Response Example 4.135. Create metering label rule: JSON response { Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 177 "metering_label_rule": { "remote_ip_prefix": "10.0.1.0/24", "direction": "ingress", "metering_label_id": "e131d186-b02d-4c0b-83d5-0c0725c4f812", "id": "00e13b58-b4f2-4579-9c9c-7ac94615f9ae", "excluded": false } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 178 Show metering label rule Method URI Description GET /v2.0/metering-label-rules/ {metering-label-rule-id} Shows detailed informations for a specified metering label rule. This operation does not require a request body. This operation returns a response body, which contains the following informations about the metering label rule: • direction. Either ingress or egress. • excluded. Either True or False. • The ID for the specified metering label rule • The remote IP prefix • The metering label ID for the metering label with which the rule is associated Normal response codes: 200 Error response codes: unauthorized (401), itemNotFound (404) Request This table shows the URI parameters for the show metering label rule request: Name Type Description {metering-label-rule-id} Uuid The unique identifier of metering label rule. Example 4.136. Show metering label rule: JSON request GET /v2.0/metering/metering-label-rules/9536641a-7d14-4dc5-afaf-93a973ce0eb8 HTTP/1.1 Host: controlnode:9696 User-Agent: python-neutronclient Content-Type: application/json Accept: application/json X-Auth-Token: c52a1b304fec4ca0ac85dc1741eec6e2 This operation does not require a request body. Response Example 4.137. Show metering label rule: JSON response { "metering_label_rule": { "remote_ip_prefix": "20.0.0.0/24", "direction": "ingress", "metering_label_id": "e131d186-b02d-4c0b-83d5-0c0725c4f812", "id": "9536641a-7d14-4dc5-afaf-93a973ce0eb8", Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 179 "excluded": false } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 180 Delete metering label rule Method URI Description DELETE /v2.0/metering-label-rules/ {metering-label-rule-id} Deletes a specified l3 metering label rule. This operation does not require a request body. This operation does not return a response body. Normal response codes: 204 Error response codes: unauthorized (401), itemNotFound (404) Request This table shows the URI parameters for the delete metering label rule request: Name Type Description {metering-label-rule-id} Uuid The unique identifier of metering label rule. Example 4.138. Delete metering label rule: JSON request DELETE /v2.0/metering/metering-labels/37b31179-71ee-4f0a-b130-0eeb28e7ede7 HTTP/1.1 Host: controlnode:9696 User-Agent: python-neutronclient Content-Type: application/json Accept: application/json X-Auth-Token: c52a1b304fec4ca0ac85dc1741eec6e2 This operation does not require a request body. Response Example 4.139. Delete metering label rule: JSON response status: 204 This operation does not return a response body. Provider networks (provider) The provider extended attributes for networks enable administrative users to specify how network objects map to the underlying networking infrastructure. These extended attributes also appear when administrative users query networks. To this aim, it extends the network resource by defining a set of attributes prefixed with provider. These attributes are added to the network resource: Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 181 • provider:network_type - Specifies the nature of the physical network mapped to this network resource. Examples are flat, vlan, or gre. • provider:physical_network - Identifies the physical network on top of which this network object is being implemented. The OpenStack Networking API does not expose any facility for retrieving the list of available physical networks. As an example, in the Open vSwitch plug-in this is a symbolic name which is then mapped to specific bridges on each compute host through the Open vSwitch plug-in configuration file. • provider:segmentation_id - Identifies an isolated segment on the physical network; the nature of the segment depends on the segmentation model defined by network_type. For instance, if network_type is vlan, then this is a vlan identifier; otherwise, if network_type is gre, then this will be a gre key. The actual semantics of these attributes depend on the technology back end of the particular plug-in. See the plug-in documentation and the OpenStack Cloud Administrator Guide to understand which values should be specific for each of these attributes when OpenStack Networking is deployed with a particular plug-in. The examples shown in this chapter refer to the Open vSwitch plug-in. The default policy settings enable only users with administrative rights to specify these parameters in requests and to see their values in responses. By default, the provider network extension attributes are completely hidden from regular tenants. As a rule of thumb, if these attributes are not visible in a GET /networks/ operation, this implies the user submitting the request is not authorized to view or manipulate provider network attributes. Method URI Description GET /v2.0/networks Lists networks that are accessible to the tenant who submits the request. POST /v2.0/networks Creates a network. GET /v2.0/networks/{network_id} Shows details for a specified network. PUT /v2.0/networks/{network_id} Updates a specified network. DELETE /v2.0/networks/{network_id} Deletes a specified network. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 182 List networks Method URI Description GET /v2.0/networks Lists networks that are accessible to the tenant who submits the request. Normal response codes: 200 Request This operation does not require a request body. Response Example 4.140. List networks: JSON response { "network": { "status": "ACTIVE", "subnets": [ "54d6f61d-db07-451c-9ab3-b9609b6b6f0b" ], "name": "private-network", "provider:physical_network": null, "admin_state_up": true, "tenant_id": "4fd44f30292945e481c7b8a0c8908869", "provider:network_type": "local", "router:external": true, "shared": true, "id": "d32019d3-bc6e-4319-9c1d-6722fc136a22", "provider:segmentation_id": null } } Example 4.141. List networks: XML response ACTIVE 54d6f61d-db07-451c-9ab3-b9609b6b6f0b private-network True 4fd44f30292945e481c7b8a0c8908869 local True True d32019d3-bc6e-4319-9c1d-6722fc136a22 Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 183 This operation does not return a response body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 184 Create network Method URI Description POST /v2.0/networks Creates a network. Normal response codes: 201 Request Example 4.142. Create network: JSON request { "network": { "name": "sample_network", "admin_state_up": true } } Example 4.143. Create network: XML request sample_network2 This operation does not require a request body. Response Example 4.144. Create network: JSON response { "network": { "status": "ACTIVE", "subnets": [], "name": "net1", "admin_state_up": true, "tenant_id": "9bacb3c5d39d41a79512987f338cf177", "segments": [ { "provider:segmentation_id": 2, "provider:physical_network": "8bab8453-1bc9-45af-8c70- f83aa9b50453", "provider:network_type": "vlan" }, { "provider:segmentation_id": null, "provider:physical_network": "8bab8453-1bc9-45af-8c70- f83aa9b50453", "provider:network_type": "stt" } ], "shared": false, "port_security_enabled": true, "id": "4e8e5957-649f-477b-9e5b-f1f75b21c03c" Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 185 } } Example 4.145. Create network: XML response ACTIVE sample_network2 True 4fd44f30292945e481c7b8a0c8908869 local False c220b026-ece1-4ead-873f-83537f4c9f92 This operation does not return a response body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 186 Show network details Method URI Description GET /v2.0/networks/{network_id} Shows details for a specified network. Normal response codes: 200 Request This table shows the URI parameters for the show network details request: Name Type Description {network_id} UUID The UUID for the network of interest to you. This operation does not require a request body. Response Example 4.146. Show network details: JSON response { "network": { "status": "ACTIVE", "subnets": [ "54d6f61d-db07-451c-9ab3-b9609b6b6f0b" ], "name": "private-network", "provider:physical_network": null, "admin_state_up": true, "tenant_id": "4fd44f30292945e481c7b8a0c8908869", "provider:network_type": "local", "router:external": true, "shared": true, "id": "d32019d3-bc6e-4319-9c1d-6722fc136a22", "provider:segmentation_id": null } } Example 4.147. Show network details: XML response ACTIVE 54d6f61d-db07-451c-9ab3-b9609b6b6f0b private-network True 4fd44f30292945e481c7b8a0c8908869 local Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 187 True True d32019d3-bc6e-4319-9c1d-6722fc136a22 This operation does not return a response body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 188 Update network Method URI Description PUT /v2.0/networks/{network_id} Updates a specified network. Normal response codes: 201 Request This table shows the URI parameters for the update network request: Name Type Description {network_id} UUID The UUID for the network of interest to you. Example 4.148. Update network: JSON request { "network": { "name": "sample_network_5_updated" } } Example 4.149. Update network: XML request sample-network-4-updated This operation does not require a request body. Response Example 4.150. Update network: JSON response { "network": { "status": "ACTIVE", "subnets": [], "name": "sample_network_5_updated", "provider:physical_network": null, "admin_state_up": true, "tenant_id": "4fd44f30292945e481c7b8a0c8908869", "provider:network_type": "local", "router:external": false, "shared": false, "id": "1f370095-98f6-4079-be64-6d3d4a6adcc6", "provider:segmentation_id": null } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 189 Example 4.151. Update network: XML response ACTIVE sample-network-4-updated True 4fd44f30292945e481c7b8a0c8908869 local False False af374017-c9ae-4a1d-b799-ab73111476e2 This operation does not return a response body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 190 Delete network Method URI Description DELETE /v2.0/networks/{network_id} Deletes a specified network. Request This table shows the URI parameters for the delete network request: Name Type Description {network_id} UUID The UUID for the network of interest to you. This operation does not require a request body. Multiple provider networks Set and retrieve the multiple provider networks extension attributes for network objects. Method URI Description GET /v2.0/networks Lists networks that are accessible to the tenant who submits the request. Networks with multiple segments include the segments list in the response. POST /v2.0/networks Creates a network with multiple segment mappings. GET /v2.0/networks/{network_id} Shows details for a specified network with multiple segments. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 191 List networks Method URI Description GET /v2.0/networks Lists networks that are accessible to the tenant who submits the request. Networks with multiple segments include the segments list in the response. Normal response codes: 200 Request This operation does not require a request body. Response Example 4.152. List networks: JSON response { "networks": [ { "status": "ACTIVE", "subnets": [], "name": "net1", "admin_state_up": true, "tenant_id": "9bacb3c5d39d41a79512987f338cf177", "segments": [ { "provider:segmentation_id": 2, "provider:physical_network": "8bab8453-1bc9-45af-8c70- f83aa9b50453", "provider:network_type": "vlan" }, { "provider:segmentation_id": 0, "provider:physical_network": "8bab8453-1bc9-45af-8c70- f83aa9b50453", "provider:network_type": "stt" } ], "router:external": false, "shared": false, "port_security_enabled": true, "id": "4e8e5957-649f-477b-9e5b-f1f75b21c03c" }, { "status": "ACTIVE", "subnets": [ "08eae331-0402-425a-923c-34f7cfe39c1b" ], "name": "private", "provider:physical_network": null, "admin_state_up": true, "tenant_id": "26a7980765d0414dbc1fc1f88cdb7e6e", "provider:network_type": "local", "router:external": true, "shared": true, Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 192 "id": "db193ab3-96e3-4cb3-8fc5-05f4296d0324", "provider:segmentation_id": null } ] } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 193 Create network with multiple segment mappings Method URI Description POST /v2.0/networks Creates a network with multiple segment mappings. Normal response codes: 201 Request Example 4.153. Create network with multiple segment mappings: JSON request { "network": { "segments": [ { "provider:segmentation_id": "2", "provider:physical_network": "8bab8453-1bc9-45af-8c70- f83aa9b50453", "provider:network_type": "vlan" }, { "provider:physical_network": "8bab8453-1bc9-45af-8c70- f83aa9b50453", "provider:network_type": "stt" } ], "name": "net1", "admin_state_up": true } } Response Example 4.154. Create network with multiple segment mappings: JSON response { "network": { "status": "ACTIVE", "subnets": [], "name": "net1", "admin_state_up": true, "tenant_id": "9bacb3c5d39d41a79512987f338cf177", "segments": [ { "provider:segmentation_id": 2, "provider:physical_network": "8bab8453-1bc9-45af-8c70- f83aa9b50453", "provider:network_type": "vlan" }, { "provider:segmentation_id": null, "provider:physical_network": "8bab8453-1bc9-45af-8c70- f83aa9b50453", Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 194 "provider:network_type": "stt" } ], "shared": false, "port_security_enabled": true, "id": "4e8e5957-649f-477b-9e5b-f1f75b21c03c" } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 195 Show details for a network with multiple segments Method URI Description GET /v2.0/networks/{network_id} Shows details for a specified network with multiple segments. Normal response codes: 200 Request This table shows the URI parameters for the show details for a network with multiple segments request: Name Type Description {network_id} UUID The UUID for the network of interest to you. This operation does not require a request body. Response Example 4.155. Show details for a network with multiple segments: JSON response { "network": { "status": "ACTIVE", "subnets": [], "name": "net1", "admin_state_up": true, "tenant_id": "9bacb3c5d39d41a79512987f338cf177", "segments": [ { "provider:segmentation_id": 2, "provider:physical_network": "8bab8453-1bc9-45af-8c70- f83aa9b50453", "provider:network_type": "vlan" }, { "provider:segmentation_id": 0, "provider:physical_network": "8bab8453-1bc9-45af-8c70- f83aa9b50453", "provider:network_type": "stt" } ], "router:external": false, "shared": false, "port_security_enabled": true, "id": "4e8e5957-649f-477b-9e5b-f1f75b21c03c" } } Quotas Use the neutron.conf configuration file to define and apply default quota values to all tenants. This extension enables an administrative user to define quotas values on a per- Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 196 tenant basis. For example, an administrative user can permit tenant A to create at most n networks and tenant B to create at most n networks. Method URI Description GET /v2.0/quotas Lists quotas for tenants who have non-default quota values. GET /v2.0/quotas/{tenant_id} Shows quotas for a specified tenant. PUT /v2.0/quotas/{tenant_id} Updates quotas for a specified tenant. Use when non- default quotas are desired. DELETE /v2.0/quotas/{tenant_id} Resets quotas to default values for a specified tenant. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 197 List quotas Method URI Description GET /v2.0/quotas Lists quotas for tenants who have non-default quota values. Normal response codes: 200 Error response codes: unauthorized (401), forbidden (403) Request This operation does not require a request body. Response Example 4.156. List quotas: JSON response { "quotas": [ { "subnet": 10, "network": 10, "floatingip": 50, "tenant_id": "b7445f221cda4f4a8ac7db6b218b1339", "router": 10, "port": 30 } ] } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 198 Show quota Method URI Description GET /v2.0/quotas/{tenant_id} Shows quotas for a specified tenant. Normal response codes: 200 Error response codes: unauthorized (401), forbidden (403) Request This table shows the URI parameters for the show quota request: Name Type Description {tenant_id} UUID The tenant ID in a multi-tenancy cloud. This operation does not require a request body. Response Example 4.157. Show quota: JSON response { "quota": { "subnet": 10, "router": 10, "port": 50, "network": 10, "floatingip": 50 } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 199 Update quota Method URI Description PUT /v2.0/quotas/{tenant_id} Updates quotas for a specified tenant. Use when non- default quotas are desired. Normal response codes: 200 Error response codes: unauthorized (401), forbidden (403) Request This table shows the URI parameters for the update quota request: Name Type Description {tenant_id} UUID The tenant ID in a multi-tenancy cloud. Example 4.158. Update quota: JSON request { "quota": { "subnet": 40, "router": 50, "network": 10, "floatingip": 30, "port": 30 } } Response Example 4.159. Update quota: JSON response { "quota": { "subnet": 40, "router": 50, "port": 30, "network": 10, "floatingip": 30 } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 200 Reset quota Method URI Description DELETE /v2.0/quotas/{tenant_id} Resets quotas to default values for a specified tenant. Normal response codes: 204 Error response codes: unauthorized (401), forbidden (403) Request This table shows the URI parameters for the reset quota request: Name Type Description {tenant_id} UUID The tenant ID in a multi-tenancy cloud. This operation does not require a request body. Security groups and rules (security-groups) Method URI Description GET /v2.0/security-groups Lists all OpenStack Networking security groups to which the specified tenant has access. POST /v2.0/security-groups Creates an OpenStack Networking security group. GET /v2.0/security-groups/ {security_group_id} Shows information for a specified security group. DELETE /v2.0/security-groups/ {security_group_id} Deletes an OpenStack Networking security group. GET /v2.0/security-group-rules Lists a summary of all OpenStack Networking security group rules that the specified tenant can access. POST /v2.0/security-group-rules Creates an OpenStack Networking security group rule. GET /v2.0/security-group-rules/{rules- security-groups-id} Shows detailed information for a specified security group rule. DELETE /v2.0/security-group-rules/{rules- security-groups-id} Deletes a specified rule from a OpenStack Networking security group. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 201 List security groups Method URI Description GET /v2.0/security-groups Lists all OpenStack Networking security groups to which the specified tenant has access. The list shows the unique ID for each security group and the rules that are associated with each security group. Normal response codes: 200 Error response codes: unauthorized (401) Request Example 4.160. List security groups: JSON request GET /v2.0/security-groups Accept: application/json This operation does not require a request body. Response Example 4.161. List security groups: JSON response { "security_groups": [ { "description": "default", "id": "85cc3048-abc3-43cc-89b3-377341426ac5", "name": "default", "security_group_rules": [ { "direction": "egress", "ethertype": "IPv6", "id": "3c0e45ff-adaf-4124-b083-bf390e5482ff", "port_range_max": null, "port_range_min": null, "protocol": null, "remote_group_id": null, "remote_ip_prefix": null, "security_group_id": "85cc3048- abc3-43cc-89b3-377341426ac5", "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550" }, { "direction": "egress", "ethertype": "IPv4", "id": "93aa42e5-80db-4581-9391-3a608bd0e448", "port_range_max": null, "port_range_min": null, "protocol": null, "remote_group_id": null, "remote_ip_prefix": null, Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 202 "security_group_id": "85cc3048- abc3-43cc-89b3-377341426ac5", "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550" }, { "direction": "ingress", "ethertype": "IPv6", "id": "c0b09f00-1d49-4e64-a0a7-8a186d928138", "port_range_max": null, "port_range_min": null, "protocol": null, "remote_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5", "remote_ip_prefix": null, "security_group_id": "85cc3048- abc3-43cc-89b3-377341426ac5", "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550" }, { "direction": "ingress", "ethertype": "IPv4", "id": "f7d45c89-008e-4bab-88ad-d6811724c51c", "port_range_max": null, "port_range_min": null, "protocol": null, "remote_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5", "remote_ip_prefix": null, "security_group_id": "85cc3048- abc3-43cc-89b3-377341426ac5", "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550" } ], "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550" } ] } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 203 Create security group Method URI Description POST /v2.0/security-groups Creates an OpenStack Networking security group. This operation creates a security group with default security group rules for the IPv4 and IPv6 ether types. Normal response codes: 201 Error response codes: badRequest (400), unauthorized (401) Request Example 4.162. Create security group: JSON request { "security_group": { "name": "new-webservers", "description": "security group for webservers" } } Response Example 4.163. Create security group: JSON response { "security_group": { "description": "security group for webservers", "id": "2076db17-a522-4506-91de-c6dd8e837028", "name": "new-webservers", "security_group_rules": [ { "direction": "egress", "ethertype": "IPv4", "id": "38ce2d8e-e8f1-48bd-83c2-d33cb9f50c3d", "port_range_max": null, "port_range_min": null, "protocol": null, "remote_group_id": null, "remote_ip_prefix": null, "security_group_id": "2076db17-a522-4506-91de-c6dd8e837028", "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550" }, { "direction": "egress", "ethertype": "IPv6", "id": "565b9502-12de-4ffd-91e9-68885cff6ae1", "port_range_max": null, "port_range_min": null, "protocol": null, "remote_group_id": null, "remote_ip_prefix": null, "security_group_id": "2076db17-a522-4506-91de-c6dd8e837028", Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 204 "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550" } ], "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550" } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 205 Show security group Method URI Description GET /v2.0/security-groups/ {security_group_id} Shows information for a specified security group. This operation returns a response body that contains the description, name, ID, and security group rules associated with the specified security group and tenant ID. Normal response codes: 200 Error response codes: unauthorized (401), itemNotFound (404) Request This table shows the URI parameters for the show security group request: Name Type Description {security_group_id} Uuid The unique identifier of the security group. Example 4.164. Show security group: JSON request GET /v2.0/security-groups/85cc3048-abc3-43cc-89b3-377341426ac5 Accept: application/json This operation does not require a request body. Response Example 4.165. Show security group: JSON response { "security_group": { "description": "default", "id": "85cc3048-abc3-43cc-89b3-377341426ac5", "name": "default", "security_group_rules": [ { "direction": "egress", "ethertype": "IPv6", "id": "3c0e45ff-adaf-4124-b083-bf390e5482ff", "port_range_max": null, "port_range_min": null, "protocol": null, "remote_group_id": null, "remote_ip_prefix": null, "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5", "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550" }, { "direction": "egress", "ethertype": "IPv4", "id": "93aa42e5-80db-4581-9391-3a608bd0e448", "port_range_max": null, Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 206 "port_range_min": null, "protocol": null, "remote_group_id": null, "remote_ip_prefix": null, "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5", "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550" }, { "direction": "ingress", "ethertype": "IPv6", "id": "c0b09f00-1d49-4e64-a0a7-8a186d928138", "port_range_max": null, "port_range_min": null, "protocol": null, "remote_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5", "remote_ip_prefix": null, "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5", "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550" }, { "direction": "ingress", "ethertype": "IPv4", "id": "f7d45c89-008e-4bab-88ad-d6811724c51c", "port_range_max": null, "port_range_min": null, "protocol": null, "remote_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5", "remote_ip_prefix": null, "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5", "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550" } ], "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550" } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 207 Delete security group Method URI Description DELETE /v2.0/security-groups/ {security_group_id} Deletes an OpenStack Networking security group. This operation deletes an OpenStack Networking security group and its associated security group rules, provided that a port is not associated with the security group. This operation does not require a request body. This operation does not return a response body. Normal response codes: 204 Error response codes: unauthorized (401), itemNotFound (404) Request This table shows the URI parameters for the delete security group request: Name Type Description {security_group_id} Uuid The unique identifier of the security group. Example 4.166. Delete security group: JSON request DELETE /v2.0/security-groups/e470bdfc-4869-459b-a561-cb3377efae59 Content-Type: application/json Accept: application/json This operation does not require a request body. Response Example 4.167. Delete security group: JSON response status: 204 This operation does not return a response body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 208 List security group rules Method URI Description GET /v2.0/security-group-rules Lists a summary of all OpenStack Networking security group rules that the specified tenant can access. The list provides the unique ID for each security group rule. Normal response codes: 200 Error response codes: unauthorized (401) Request Example 4.168. List security group rules: JSON request GET /v2.0/security-group-rules/ Accept: application/json This operation does not require a request body. Response Example 4.169. List security group rules: JSON response { "security_group_rules": [ { "direction": "egress", "ethertype": "IPv6", "id": "3c0e45ff-adaf-4124-b083-bf390e5482ff", "port_range_max": null, "port_range_min": null, "protocol": null, "remote_group_id": null, "remote_ip_prefix": null, "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5", "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550" }, { "direction": "egress", "ethertype": "IPv4", "id": "93aa42e5-80db-4581-9391-3a608bd0e448", "port_range_max": null, "port_range_min": null, "protocol": null, "remote_group_id": null, "remote_ip_prefix": null, "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5", "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550" }, { "direction": "ingress", "ethertype": "IPv6", "id": "c0b09f00-1d49-4e64-a0a7-8a186d928138", Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 209 "port_range_max": null, "port_range_min": null, "protocol": null, "remote_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5", "remote_ip_prefix": null, "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5", "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550" }, { "direction": "ingress", "ethertype": "IPv4", "id": "f7d45c89-008e-4bab-88ad-d6811724c51c", "port_range_max": null, "port_range_min": null, "protocol": null, "remote_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5", "remote_ip_prefix": null, "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5", "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550" } ] } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 210 Create security group rule Method URI Description POST /v2.0/security-group-rules Creates an OpenStack Networking security group rule. Normal response codes: 201 Error response codes: badRequest (400), unauthorized (401), itemNotFound (404), buildInProgress (409) Request Example 4.170. Create security group rule: JSON request { "security_group_rule": { "direction": "ingress", "port_range_min": "80", "ethertype": "IPv4", "port_range_max": "80", "protocol": "tcp", "remote_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5", "security_group_id": "a7734e61-b545-452d-a3cd-0189cbd9747a" } } Response Example 4.171. Create security group rule: JSON response { "security_group_rule": { "direction": "ingress", "ethertype": "IPv4", "id": "2bc0accf-312e-429a-956e-e4407625eb62", "port_range_max": 80, "port_range_min": 80, "protocol": "tcp", "remote_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5", "remote_ip_prefix": null, "security_group_id": "a7734e61-b545-452d-a3cd-0189cbd9747a", "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550" } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 211 Show security group rule Method URI Description GET /v2.0/security-group-rules/{rules- security-groups-id} Shows detailed information for a specified security group rule. The response body contains the following information about the security group rule: Normal response codes: 200 Error response codes: unauthorized (401), itemNotFound (404) Request This table shows the URI parameters for the show security group rule request: Name Type Description {rules-security-groups- id} Uuid The unique identifier of the security group rule. Example 4.172. Show security group rule: JSON request GET /v2.0/security-group-rules/ 3c0e45ff-adaf-4124-b083-bf390e5482ff Accept: application/json This operation does not require a request body. Response Example 4.173. Show security group rule: JSON response { "security_group_rule": { "direction": "egress", "ethertype": "IPv6", "id": "3c0e45ff-adaf-4124-b083-bf390e5482ff", "port_range_max": null, "port_range_min": null, "protocol": null, "remote_group_id": null, "remote_ip_prefix": null, "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5", "tenant_id": "e4f50856753b4dc6afee5fa6b9b6c550" } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 212 Delete security group rule Method URI Description DELETE /v2.0/security-group-rules/{rules- security-groups-id} Deletes a specified rule from a OpenStack Networking security group. Normal response codes: 204 Error response codes: unauthorized (401), itemNotFound (404) Request This table shows the URI parameters for the delete security group rule request: Name Type Description {rules-security-groups- id} Uuid The unique identifier of the security group rule. Example 4.174. Delete security group rule: JSON request DELETE /v2.0/security-group-rules/fc3c327a-b5b5-4cd3-9577-52893289ce08 Content-Type: application/json Accept: application/json This operation does not require a request body. Response Example 4.175. Delete security group rule: JSON response status: 204 This operation does not return a response body. Virtual Private Network as a Service (VPNaaS) The VPNaaS extension provides OpenStack tenants with the ability to extend private networks across the public telecommunication infrastructure. The capabilities provided by this initial implementation of the VPNaaS extension are: • Site-to-site Virtual Private Network connecting two private networks. • Multiple VPN connections per tenant. • Supporting IKEv1 policy with 3des, aes-128, aes-256, or aes-192 encryption. • Supporting IPSec policy with 3des, aes-128, aes-256, or aes-192 encryption, sha1 authentication, ESP, AH, or AH-ESP transform protocol, and tunnel or transport mode encapsulation. • Dead Peer Detection (DPD) allowing hold, clear, restart, disabled, or restart-by-peer actions. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 213 This extension introduces new resources: • service, a high level object that associates VPN with a specific subnet and router. • ikepolicy, the Internet Key Exchange policy identifying the authentication and encryption algorithm used during phase one and phase two negotiation of a VPN connection. • ipsecpolicy, the IP security policy specifying the authentication and encryption algorithm, and encapsulation mode used for the established VPN connection. • ipsec-site-connection, has details for the site-to-site IPsec connection, including the peer CIDRs, MTU, authentication mode, peer address, DPD settings, and status. Note This extension is experimental for the Havana release. The API may change without backward compatibility. Concepts A VPN service relates the Virtual Private Network with a specific subnet and router for a tenant. An IKE Policy is used for phase one and phase two negotiation of the VPN connection. Configuration selects the authentication and encryption algorithm used to establish a connection. An IPsec Policy is used to specify the encryption algorithm, transform protocol, and mode (tunnel/transport) for the VPN connection. A VPN connection represents the IPsec tunnel established between two sites for the tenant. This contains configuration settings specifying the policies used, peer information, MTU, and the DPD actions to take. High-level flow The high-level task flow for using VPNaaS API to configure a site-to-site Virtual Private Network is as follows: 1. The tenant creates a VPN service specifying the router and subnet. 2. The tenant creates an IKE Policy. 3. The tenant creates an IPsec Policy. 4. The tenant creates a VPN connection, specifying the VPN service, peer information, and IKE and IPsec policies. VPN services Manage a tenant's VPN service through this extension. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 214 Table 4.15. VPN Service Attributes Attribute Type Required CRUD a Default value Validation constraints Notes id uuid-str N/A R generated N/A Unique identifier for the VPN Service object. tenant_id uuid-str Yes CR Derived from Authentication token valid tenant_id Owner of the VPN service. Only admin users can specify a tenant identifier other than their own. name String No CRU None N/A Human readable name for the VPN service. Does not have to be unique. description String No CRU None N/A Human readable description for the VPN service. status String N/A R N/A N/A Indicates whether IPsec VPN service is currently operational. Possible values include: ACTIVE, DOWN, BUILD, ERROR, PENDING_CREATE, PENDING_UPDATE, or PENDING_DELETE. admin_state_up Bool N/A CRU true {true | false } Administrative state of the vpnservice. If false (down), port does not forward packets. subnet_id uuid-str Yes CR N/A valid subnet ID The subnet on which the tenant wants the VPN service. This may be extended in the future to support multiple subnets. router_id uuid-str Yes CR N/A valid router ID Router ID to which the VPN service is inserted. This may change in the future, when router level insertion is available. a•C. Use the attribute in create operations. •R. This attribute is returned in response to show and list operations. •U. You can update the value of this attribute. •D. You can delete the value of this attribute. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 215 List VPN services Verb URI Description GET /vpn/vpnservices Lists VPN services. Normal Response Code: 200 Error Response Codes: Unauthorized (401), Forbidden (403) This operation does not require a request body. This operation returns a response body. Example 4.176. List VPN Services: Request GET /v2.0/vpn/vpnservices.json User-Agent: python-neutronclient Accept: application/json Example 4.177. List VPN Services: Response { "vpnservices": [ { "router_id": "ec8619be-0ba8-4955-8835-3b49ddb76f89", "status": "PENDING_CREATE", "name": "myservice", "admin_state_up": true, "subnet_id": "f4fb4528-ed93-467c-a57b-11c7ea9f963e", "tenant_id": "ccb81365fe36411a9011e90491fe1330", "id": "9faaf49f-dd89-4e39-a8c6-101839aa49bc", "description": "" } ] } Show VPN service details Verb URI Description GET /vpn/ vpnservices/ service-id Shows details about a specified VPN service. Normal Response Code: 200 Error Response Codes: Unauthorized (401), Forbidden (403), Not Found (404) This operation does not require a request body. This operation returns a response body. Example 4.178. Show VPN Service: Request GET /v2.0/vpn/vpnservices/9faaf49f-dd89-4e39-a8c6-101839aa49bc.json User-Agent: python-neutronclient Accept: application/json Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 216 Example 4.179. Show VPN Service: Response { "vpnservice": { "router_id": "ec8619be-0ba8-4955-8835-3b49ddb76f89", "status": "PENDING_CREATE", "name": "myservice", "admin_state_up": true, "subnet_id": "f4fb4528-ed93-467c-a57b-11c7ea9f963e", "tenant_id": "ccb81365fe36411a9011e90491fe1330", "id": "9faaf49f-dd89-4e39-a8c6-101839aa49bc", "description": "" } } Create VPN service Verb URI Description POST /vpn/vpnservices Creates a VPN service. Normal Response Code: 201 Error Response Codes: Unauthorized (401), Bad Request (400) This operation requires a request body. This operation returns a response body. Example 4.180. Create VPN Service: Request POST /v2.0/vpn/vpnservices.json User-Agent: python-neutronclient Accept: application/json { "vpnservice": { "subnet_id": "f4fb4528-ed93-467c-a57b-11c7ea9f963e", "router_id": "ec8619be-0ba8-4955-8835-3b49ddb76f89", "name": "myservice", "admin_state_up": true } } Example 4.181. Create VPN: Response HTTP/1.1 201 Created Content-Type: application/json; charset=UTF-8 { "vpnservice": { "router_id": "ec8619be-0ba8-4955-8835-3b49ddb76f89", "status": "PENDING_CREATE", "name": "myservice", "admin_state_up": true, "subnet_id": "f4fb4528-ed93-467c-a57b-11c7ea9f963e", "tenant_id": "ccb81365fe36411a9011e90491fe1330", "id": "9faaf49f-dd89-4e39-a8c6-101839aa49bc", "description": "" } } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 217 Update VPN service Verb URI Description PUT /vpn/ vpnservices/ service-id Updates a VPN service, provided status is not indicating a PENDING_* state. Normal Response Code: 200 Error Response Codes: Unauthorized (401), Bad Request (400), Not Found (404) Example 4.182. Update VPN Service: Request PUT /v2.0/vpn/vpnservices/41bfef97-af4e-4f6b-a5d3-4678859d2485.json User-Agent: python-neutronclient Accept: application/json { "vpnservice": { "description": "Updated description" } } Example 4.183. Update VPN Service: Response HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "vpnservice": { "router_id": "881b7b30-4efb-407e-a162-5630a7af3595", "status": "ACTIVE", "name": "myvpn", "admin_state_up": true, "subnet_id": "25f8a35c-82d5-4f55-a45b-6965936b33f6", "tenant_id": "26de9cd6cae94c8cb9f79d660d628e1f", "id": "41bfef97-af4e-4f6b-a5d3-4678859d2485", "description": "Updated description" } } Delete VPN service Verb URI Description DELETE /vpn/ vpnservices/ service-id Deletes a VPN service. Normal Response Code: 204 Error Response Codes: Unauthorized (401), Not Found (404), Conflict (409) This operation does not require a request body. This operation does not return a response body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 218 Example 4.184. Delete VPN Service: Request DELETE /v2.0/vpn/vpnservices/1be5e5f7-c45e-49ba-85da-156575b60d50.json User-Agent: python-neutronclient Accept: application/json Example 4.185. Delete VPN Service: Response HTTP/1.1 204 No Content Content-Length: 0 IKE policies Manage IKE policies through the VPN as a Service extension. Table 4.16. IKE Policy Attributes Attribute Type Required CRUD a Default value Validation constraints Notes id uuid-str N/A R generated N/A Unique identifier for the IKE policy. tenant_id uuid-str Yes CR None valid tenant_id Unique identifier for owner of the VPN service. name string yes CRU None N/A Friendly name for the IKE policy. description string no CRU None N/A Description of the IKE policy. auth_algorithm string no CRU sha1 N/A Authentication Hash algorithms: sha1. encryption_algorithm string no CRU aes-128 N/A Encryption Algorithms: 3des, aes-128, aes-256, aes-192, etc. phase1_negotiation_ mode string no CRU Main Mode N/A IKE mode: Main Mode. pfs string no CRU Group5 N/A Perfect Forward Secrecy: Group2, Group5, or Group14. ike_version string no CRU v1 N/A Version: v1 or v2. lifetime dict no CRU units: seconds, value: 3600. Dictionary should be in this form: {'units': 'seconds', 'value': 2000}. Value is a positive integer. Lifetime of the SA. Units in 'seconds'. Either units or value may be omitted. a•C. Use the attribute in create operations. •R. This attribute is returned in response to show and list operations. •U. You can update the value of this attribute. •D. You can delete the value of this attribute. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 219 List IKE policies Verb URI Description GET /vpn/ikepolicies Lists IKE policies. Normal Response Code: 200 Error Response Codes: Unauthorized (401), Forbidden (403) This operation does not require a request body. This operation returns a response body. Example 4.186. List IKE Policies: Request GET /v2.0/vpn/ikepolicies.json User-Agent: python-neutronclient Accept: application/json Example 4.187. List IKE Policies: Response HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "ikepolicies": [ { "name": "ikepolicy1", "tenant_id": "ccb81365fe36411a9011e90491fe1330", "auth_algorithm": "sha1", "encryption_algorithm": "aes-256", "pfs": "group5", "phase1_negotiation_mode": "main", "lifetime": { "units": "seconds", "value": 3600 }, "ike_version": "v1", "id": "5522aff7-1b3c-48dd-9c3c-b50f016b73db", "description": "" } ] } Show IKE policy details Verb URI Description GET /vpn/ ikepolicies/ ikepolicy-id Shows details for a specified IKE policy. Normal Response Code: 200 Error Response Codes: Unauthorized (401), Forbidden (403), Not Found (404) This operation does not require a request body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 220 This operation returns a response body. Example 4.188. Show IKE Policy: Request GET /v2.0/vpn/ikepolicies/5522aff7-1b3c-48dd-9c3c-b50f016b73db.json User-Agent: python-neutronclient Accept: application/json Example 4.189. Show IKE Policy: Response HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "ikepolicy": { "name": "ikepolicy1", "tenant_id": "ccb81365fe36411a9011e90491fe1330", "auth_algorithm": "sha1", "encryption_algorithm": "aes-256", "pfs": "group5", "phase1_negotiation_mode": "main", "lifetime": { "units": "seconds", "value": 3600 }, "ike_version": "v1", "id": "5522aff7-1b3c-48dd-9c3c-b50f016b73db", "description": "" } } Create IKE policy Verb URI Description POST /vpn/ikepolicies Creates an IKE policy. Normal Response Code: 201 Error Response Codes: Unauthorized (401), Bad Request (400) This operation requires a request body. This operation returns a response body. Example 4.190. Create IKE Policy: Request POST /v2.0/vpn/ikepolicies.json User-Agent: python-neutronclient Accept: application/json { "ikepolicy": { "phase1_negotiation_mode": "main", "auth_algorithm": "sha1", "encryption_algorithm": "aes-128", "pfs": "group5", "lifetime": { "units": "seconds", Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 221 "value": 7200 }, "ike_version": "v1", "name": "ikepolicy1" } } Example 4.191. Create IKE Policy: Response HTTP/1.1 201 Created Content-Type: application/json; charset=UTF-8 { "ikepolicy": { "name": "ikepolicy1", "tenant_id": "ccb81365fe36411a9011e90491fe1330", "auth_algorithm": "sha1", "encryption_algorithm": "aes-128", "pfs": "group5", "phase1_negotiation_mode": "main", "lifetime": { "units": "seconds", "value": 7200 }, "ike_version": "v1", "id": "5522aff7-1b3c-48dd-9c3c-b50f016b73db", "description": "" } } Update IKE policy Verb URI Description PUT /vpn/ ikepolicies/ ikepolicy-id Updates an IKE policy. Normal Response Code: 200 Error Response Codes: Unauthorized (401), Bad Request (400), Not Found (404) Example 4.192. Update IKE Policy: Request PUT /v2.0/vpn/ikepolicies/5522aff7-1b3c-48dd-9c3c-b50f016b73db.json User-Agent: python-neutronclient Accept: application/json { "ikepolicy": { "encryption_algorithm": "aes-256" } } Example 4.193. Update IKE Policy: Response HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 222 "ikepolicy": { "name": "ikepolicy1", "tenant_id": "ccb81365fe36411a9011e90491fe1330", "auth_algorithm": "sha1", "encryption_algorithm": "aes-256", "pfs": "group5", "phase1_negotiation_mode": "main", "lifetime": { "units": "seconds", "value": 3600 }, "ike_version": "v1", "id": "5522aff7-1b3c-48dd-9c3c-b50f016b73db", "description": "" } } Delete IKE policy Verb URI Description DELETE /vpn/ ikepolicies/ ikepolicy-id Deletes an IKE policy. Normal Response Code: 204 Error Response Codes: Unauthorized (401), Not Found (404), Conflict (409) This operation does not require a request body. This operation does not return a response body. Example 4.194. Delete IKE Policy: Request DELETE /v2.0/vpn/ikepolicies/5522aff7-1b3c-48dd-9c3c-b50f016b73db.json User-Agent: python-neutronclient Accept: application/json Example 4.195. Delete IKE Policy: Response HTTP/1.1 204 No Content Content-Length: 0 IPSec policies Manage IPSec policies through the VPN as a Service extension. Table 4.17. IPSec Policy Attributes Attribute Type Required CRUD a Default value Validation constraints Notes id uuid-str N/A R generated N/A Unique identifier for the IPsec policy. tenant_id uuid-str Yes CR None valid tenant_id Unique identifier for owner of the VPN service. name string yes CRU None N/A Friendly name for the IPsec policy. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 223 Attribute Type Required CRUD a Default value Validation constraints Notes description string no CRU None N/A Description of the IPSec policy. transform_protocol string no CRU ESP N/A Transform protocol used: ESP, AH, or AH-ESP. encapsulation_mode string no CRU tunnel N/A Encapsulation mode: tunnel or transport. auth_algorithm string no CRU sha1 N/A Authentication algorithm: sha1. encryption_algorithm string no CRU aes-128 N/A Encryption Algorithms: 3des, aes-128, aes-256, or aes-192. pfs string no CRU group5 N/A Perfect Forward Secrecy: group2, group5, or group14. lifetime dict no CRU units: seconds, value: 3600. Dictionary should be in this form: {'units': 'seconds', 'value': 2000}. Value is a positive integer. Lifetime of the SA. Units in 'seconds'. Either units or value may be omitted. a•C. Use the attribute in create operations. •R. This attribute is returned in response to show and list operations. •U. You can update the value of this attribute. •D. You can delete the value of this attribute. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 224 List IPSec policies Verb URI Description GET /vpn/ipsecpolicies Lists IPSec policies. Normal Response Code: 200 Error Response Codes: Unauthorized (401), Forbidden (403) This operation does not require a request body. This operation returns a response body. Example 4.196. List IPSec Policies: Request GET /v2.0/vpn/ipsecpolicies.json User-Agent: python-neutronclient Accept: application/json Example 4.197. List IPSec Policies: Response HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "ipsecpolicies": [ { "name": "ipsecpolicy1", "transform_protocol": "esp", "auth_algorithm": "sha1", "encapsulation_mode": "tunnel", "encryption_algorithm": "aes-128", "pfs": "group14", "tenant_id": "ccb81365fe36411a9011e90491fe1330", "lifetime": { "units": "seconds", "value": 3600 }, "id": "5291b189-fd84-46e5-84bd-78f40c05d69c", "description": "" } ] } Show IPSec policy details Verb URI Description GET /vpn/ ipsecpolicies/ ipsecpolicy-id Shows details for a specified IPSec policy. Normal Response Code: 200 Error Response Codes: Unauthorized (401), Forbidden (403), Not Found (404) This operation does not require a request body. This operation returns a response body. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 225 Example 4.198. Show IPSec policy: Request GET /v2.0/vpn/ipsecpolicies/5291b189-fd84-46e5-84bd-78f40c05d69c.json User-Agent: python-neutronclient Accept: application/json Example 4.199. Show IPSec policy: Response HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "ipsecpolicy": { "name": "ipsecpolicy1", "transform_protocol": "esp", "auth_algorithm": "sha1", "encapsulation_mode": "tunnel", "encryption_algorithm": "aes-128", "pfs": "group14", "tenant_id": "ccb81365fe36411a9011e90491fe1330", "lifetime": { "units": "seconds", "value": 3600 }, "id": "5291b189-fd84-46e5-84bd-78f40c05d69c", "description": "" } } Create IPSec Policy Verb URI Description POST /vpn/ipsecpolicies Creates an IPSec policy. Normal Response Code: 201 Error Response Codes: Unauthorized (401), Bad Request (400) This operation requires a request body. This operation returns a response body. Example 4.200. Create IPSec policy: Request POST /v2.0/vpn/ipsecpolicies.json User-Agent: python-neutronclient Accept: application/json { "ipsecpolicy": { "name": "ipsecpolicy1", "transform_protocol": "esp", "auth_algorithm": "sha1", "encapsulation_mode": "tunnel", "encryption_algorithm": "aes-128", "pfs": "group5", "lifetime": { "units": "seconds", "value": 7200 Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 226 } } } Example 4.201. Create IPSec policy: Response HTTP/1.1 201 Created Content-Type: application/json; charset=UTF-8 { "ipsecpolicy": { "name": "ipsecpolicy1", "transform_protocol": "esp", "auth_algorithm": "sha1", "encapsulation_mode": "tunnel", "encryption_algorithm": "aes-128", "pfs": "group5", "tenant_id": "ccb81365fe36411a9011e90491fe1330", "lifetime": { "units": "seconds", "value": 7200 }, "id": "5291b189-fd84-46e5-84bd-78f40c05d69c", "description": "" } } Update IPSec Policy Verb URI Description PUT /vpn/ ipsecpolicies/ ipsecpolicy-id Updates an IPSec policy. Normal Response Code: 200 Error Response Codes: Unauthorized (401), Bad Request (400), Not Found (404) Example 4.202. Update IPSec policy: Request PUT /v2.0/vpn/ipsecpolicies/5291b189-fd84-46e5-84bd-78f40c05d69c.json User-Agent: python-neutronclient Accept: application/json { "ipsecpolicy": { "pfs": "group14" } } Example 4.203. Update IPSec policy: Response HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "ipsecpolicy": { "name": "ipsecpolicy1", "transform_protocol": "esp", "auth_algorithm": "sha1", Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 227 "encapsulation_mode": "tunnel", "encryption_algorithm": "aes-128", "pfs": "group14", "tenant_id": "ccb81365fe36411a9011e90491fe1330", "lifetime": { "units": "seconds", "value": 3600 }, "id": "5291b189-fd84-46e5-84bd-78f40c05d69c", "description": "" } } Delete IPSec policy Verb URI Description DELETE /vpn/ ipsecpolicies/ ipsecpolicy-id Deletes an IPSec policy. Normal Response Code: 204 Error Response Codes: Unauthorized (401), Not Found (404), Conflict (409) This operation does not require a request body. This operation does not return a response body. Example 4.204. Delete IPSec policy: Request DELETE /v2.0/vpn/ipsecpolicies/5291b189-fd84-46e5-84bd-78f40c05d69c.json User-Agent: python-neutronclient Accept: application/json Example 4.205. Delete IPSec policy: Response HTTP/1.1 204 No Content Content-Length: 0 IPSec site connections Manage IPSec site-to-site connections through the VPN as a Service extension. Table 4.18. IPSec site connection attributes Attribute Type Required CRUD a Default Value Validation Constraints Notes id uuid-str N/A R generated N/A Unique identifier for the IPSec site-to-site connection. tenant_id uuid-str Yes CR None valid tenant_id Unique identifier for owner of the VPN service. name string no CRU None N/A Name for IPSec site-to-site connection. description string no CRU None N/A Description of the IPSec site- to-site connection. peer_address string yes CRU N/A N/A Peer gateway public IPv4/ IPv6 address or FQDN. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 228 Attribute Type Required CRUD a Default Value Validation Constraints Notes peer_id string yes CRU N/A N/A Peer router identity for authentication. Can be IPv4/ IPv6 address, e-mail address, key id, or FQDN. peer_cidrs list[string]yes CRU N/A unique list of valid cidr in the form / Peer private CIDRs. route_mode string no R static static Route mode: static. This will be extended in the future. mtu integer no CRU 1500 Integer. Minimum is 68 for IPv4 and 1280 for IPv6. Maximum Transmission Unit to address fragmentation. auth_mode string no R psk psk/certs Authentication mode: PSK or certificate. psk string yes CRU N/A NO Pre Shared Key: any string. initiator string no CRU bi-directional bi-directional / response-only Whether this VPN can only respond to connections or can initiate as well. admin_state_up bool N/A CRU TRUE true / false Administrative state of VPN connection. If false (down), VPN connection does not forward packets. status string N/A R N/A N/A Indicates whether VPN connection is currently operational. Possible values include: ACTIVE, DOWN, BUILD, ERROR, PENDING_CREATE, PENDING_UPDATE, or PENDING_DELETE. ikepolicy_id uuid yes CR N/A Unique identifier of IKE policy Unique identifier of IKE policy. ipsecpolicy_id uuid yes CR N/A Unique identifier of IPSec policy Unique identifier of IPSec policy. vpnservice_id uuid yes CR N/A Unique identifier of VPN service Unique identifier of VPN service. dpd dict no CRU action: hold, interval: 30, timeout: 120 Dictionary should be in this form: {'action': 'clear', 'interval': 20, 'timeout': 60}. Interval is positive integer. Timeout is greater than interval. Dead Peer Detection protocol controls. Action: clear, hold, restart, disabled, or restart-by-peer. Interval and timeout in seconds. a•C. Use the attribute in create operations. •R. This attribute is returned in response to show and list operations. •U. You can update the value of this attribute. •D. You can delete the value of this attribute. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 229 Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 230 List IPSec site connections Verb URI Description GET /vpn/ipsec-site- connections Lists the IPSec site-to-site connections. Normal Response Code: 200 Error Response Codes: Unauthorized (401), Forbidden (403) This operation does not require a request body. This operation returns a response body. Example 4.206. List IPSec site connections: Request GET /v2.0/vpn/ipsec-site-connections.json User-Agent: python-neutronclient Accept: application/json Example 4.207. List IPSec site connections: Response HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "ipsec_site_connections": [ { "status": "PENDING_CREATE", "psk": "secret", "initiator": "bi-directional", "name": "vpnconnection1", "admin_state_up": true, "tenant_id": "ccb81365fe36411a9011e90491fe1330", "description": "", "auth_mode": "psk", "peer_cidrs": [ "10.1.0.0/24" ], "mtu": 1500, "ikepolicy_id": "bf5612ac-15fb-460c-9b3d-6453da2fafa2", "dpd": { "action": "hold", "interval": 30, "timeout": 120 }, "route_mode": "static", "vpnservice_id": "c2f3178d-5530-4c4a-89fc-050ecd552636", "peer_address": "172.24.4.226", "peer_id": "172.24.4.226", "id": "cbc152a0-7e93-4f98-9f04-b085a4bf2511", "ipsecpolicy_id": "8ba867b2-67eb-4835-bb61-c226804a1584" } ] } Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 231 Show IPSec site connection details Verb URI Description GET /vpn/ipsec-site- connections/ connection-id Shows details about a specified IPSec site-to-site connection. Normal Response Code: 200 Error Response Codes: Unauthorized (401), Forbidden (403), Not Found (404) This operation does not require a request body. This operation returns a response body. Example 4.208. Show IPSec site connection: Request GET /v2.0/vpn/ipsec-site-connections/cbc152a0-7e93-4f98-9f04-b085a4bf2511.json User-Agent: python-neutronclient Accept: application/json Example 4.209. Show IPSec site connection: Response HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "ipsec_site_connection": { "status": "PENDING_CREATE", "psk": "secret", "initiator": "bi-directional", "name": "vpnconnection1", "admin_state_up": true, "tenant_id": "ccb81365fe36411a9011e90491fe1330", "description": "", "auth_mode": "psk", "peer_cidrs": [ "10.1.0.0/24" ], "mtu": 1500, "ikepolicy_id": "bf5612ac-15fb-460c-9b3d-6453da2fafa2", "dpd": { "action": "hold", "interval": 30, "timeout": 120 }, "route_mode": "static", "vpnservice_id": "c2f3178d-5530-4c4a-89fc-050ecd552636", "peer_address": "172.24.4.226", "peer_id": "172.24.4.226", "id": "cbc152a0-7e93-4f98-9f04-b085a4bf2511", "ipsecpolicy_id": "8ba867b2-67eb-4835-bb61-c226804a1584" } } Create IPSec site connection Verb URI Description POST /vpn/ipsec-site- connections Creates an IPSec site connection. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 232 Normal Response Code: 201 Error Response Codes: Unauthorized (401), Bad Request (400) This operation requires a request body. This operation returns a response body. Example 4.210. Create IPSec site connection: Request POST /v2.0/vpn/ipsec-site-connections.json User-Agent: python-neutronclient Accept: application/json { "ipsec_site_connection": { "psk": "secret", "initiator": "bi-directional", "ipsecpolicy_id": "22b8abdc-e822-45b3-90dd-f2c8512acfa5", "admin_state_up": true, "peer_cidrs": [ "10.2.0.0/24" ], "mtu": "1500", "ikepolicy_id": "d3f373dc-0708-4224-b6f8-676adf27dab8", "dpd": { "action": "disabled", "interval": 60, "timeout": 240 }, "vpnservice_id": "7b347d20-6fa3-4e22-b744-c49ee235ae4f", "peer_address": "172.24.4.233", "peer_id": "172.24.4.233", "name": "vpnconnection1" } } Example 4.211. Create IPSec site connection: Response HTTP/1.1 201 Created Content-Type: application/json; charset=UTF-8 { "ipsec_site_connection": { "status": "PENDING_CREATE", "psk": "secret", "initiator": "bi-directional", "name": "vpnconnection1", "admin_state_up": true, "tenant_id": "b6887d0b45b54a249b2ce3dee01caa47", "description": "", "auth_mode": "psk", "peer_cidrs": [ "10.2.0.0/24" ], "mtu": 1500, "ikepolicy_id": "d3f373dc-0708-4224-b6f8-676adf27dab8", "dpd": { "action": "disabled", "interval": 60, Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 233 "timeout": 240 }, "route_mode": "static", "vpnservice_id": "7b347d20-6fa3-4e22-b744-c49ee235ae4f", "peer_address": "172.24.4.233", "peer_id": "172.24.4.233", "id": "af44dfd7-cf91-4451-be57-cd4fdd96b5dc", "ipsecpolicy_id": "22b8abdc-e822-45b3-90dd-f2c8512acfa5" } } Update IPSec site connection Verb URI Description PUT /vpn/ipsec-site- connections/ connection-id Updates an IPSec site-to-site connection, provided status is not indicating a PENDING_* state. Normal Response Code: 200 Error Response Codes: Unauthorized (401), Bad Request (400), Not Found (404) Example 4.212. Update IPSec site connection: Request PUT /v2.0/vpn/ipsec-site-connections/f7cf7305-f491-45f4-ad9c-8e7240fe3d72.json User-Agent: python-neutronclient Accept: application/json { "ipsec_site_connection": { "mtu": "2000" } } Example 4.213. Update IPSec site connection: Response HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "ipsec_site_connection": { "status": "DOWN", "psk": "secret", "initiator": "bi-directional", "name": "vpnconnection1", "admin_state_up": true, "tenant_id": "26de9cd6cae94c8cb9f79d660d628e1f", "description": "", "auth_mode": "psk", "peer_cidrs": [ "10.2.0.0/24" ], "mtu": 2000, "ikepolicy_id": "771f081c-5ec8-4f9a-b041-015dfb7fbbe2", "dpd": { "action": "hold", "interval": 30, "timeout": 120 }, Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 234 "route_mode": "static", "vpnservice_id": "41bfef97-af4e-4f6b-a5d3-4678859d2485", "peer_address": "172.24.4.233", "peer_id": "172.24.4.233", "id": "f7cf7305-f491-45f4-ad9c-8e7240fe3d72", "ipsecpolicy_id": "9958d4fe-3719-4e8c-84e7-9893895b76b4" } } Delete IPSec site connection Verb URI Description DELETE /vpn/ipsec-site- connections/ connection-id Deletes an IPSec site-to-site connection. Normal Response Code: 204 Error Response Codes: Unauthorized (401), Not Found (404), Conflict (409) This operation does not require a request body. This operation does not return a response body. Example 4.214. Delete IPSec site connection: Request DELETE /v2.0/vpn/ipsec-site-connections/cbc152a0-7e93-4f98-9f04-b085a4bf2511. json User-Agent: python-neutronclient Accept: application/json Example 4.215. Delete IPSec site connection: Response HTTP/1.1 204 No Content Content-Length: 0 Extra DHCP options (extra-dhcp-opt) The DHCP options extension allows adding DHCP options that are associated to a Neutron port. They are tagged such that they can be associated from the hosts file to designate a specific network interface and port. The DHCP tag scheme used to associate options to the host files is the port_id (UUID - in the form of 8-4-4-4-12 for a total of 36 characters), these associate options to a Neutron port and its network. The Dynamic Host Configuration Protocol (DHCP) provides a framework for passing configuration information to hosts on a TCP/IP network. Configuration parameters and other information are carried in tagged data items that are stored in the 'options' field of the DHCP message. You can specify a DHCP options when defining or updating a port by specifying the extra_dhcp_opts tag and providing its options as name value pairs, such as, opt_name='bootfile-name', opt_value='pxelinux.0'. Concepts The extra-dhcp-opt extension is an attribute extension which adds the following set of attributes to the port resource: Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 235 • extra-dhcp-opt:opt_name - Specified the DHCP option that this is defined as mapped to this port resource. Examples are bootfile-name, server-ip-address, tftp- server, etc.. • extra-dhcp-opt:opt_value - Identifies the value associated with the opt_name. These are handled in opt_name, opt_value pairs only. value_opt can be any text string depending upon the name. The actual semantics of extra-dhcp-opt attributes depend on the name of the dhcp option being used that defines the vendor extension to DHCP. For example reference RFC: http://tools.ietf.org/html/rfc2132, contains specific detail on BOOTP Vendor Extensions. List ports Verb URI Description GET /ports Lists ports with attributes. Normal response Code: 200 OK Error response Codes: 401 Unauthorized This operation returns all the ports defined in Neutron that to which this user has access. Example 4.216. List ports with extra_dhcp_opts: JSON response { "ports": [ { "status": "DOWN", "binding:host_id": null, "name": "", "allowed_address_pairs": [], "admin_state_up": true, "network_id": "87733bcc-8144-41b1-bb6b-d011d7a5168e", "tenant_id": "7ea98790cd854fb5a82ef3d41e5c156b", "extra_dhcp_opts": [{"opt_value": "testfile.1", "opt_name": "bootfile-name"}, {"opt_value": "123.123.123.45", "opt_name": "server-ip-address"}, {"opt_value": "123. 123.123.123", "opt_name": "tftp-server"}], "binding:vif_type": "ovs", "device_owner": "", "binding:capabilities": {"port_filter": true}, "mac_address": "fa:16:3e:52:92:3a", "fixed_ips": [{"subnet_id": "99a8aea3-b9da-409d-a5e5-f45338ceb4d3", "ip_address": "172.24.4.228"}], "id": "3c0c7a37-690a-43a8-8088-5d4c2c7f8484", "security_groups": ["9bf6f19a-ba4a-470f-b8ce-28c9ad66556c"], "device_id": "" }, { "status": "ACTIVE", "binding:host_id": null, "name": "", "allowed_address_pairs": [], "admin_state_up": true, "network_id": "87733bcc-8144-41b1-bb6b-d011d7a5168e", "tenant_id": "7ea98790cd854fb5a82ef3d41e5c156b", "extra_dhcp_opts": [], "binding:vif_type": "ovs", "device_owner": "compute:probe", "binding:capabilities": {"port_filter": true}, "mac_address": "fa:16:3e:49:56:07", Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 236 "fixed_ips": [{"subnet_id": "99a8aea3-b9da-409d-a5e5-f45338ceb4d3", "ip_address": "172.24.4.227"}], "id": "5212d40a-c2f5-4a5d-ad18-694658047654", "security_groups": ["9bf6f19a-ba4a-470f-b8ce-28c9ad66556c"], "device_id": "zvm2" } ] } Show port details Verb URI Description GET /ports/port_id Shows details about a specified port, including extra-dhcp-opt attributes. Normal response Code: 200 OK Error response Code: 401 Unauthorized, 404 Not Found This operation returns, for the port specified in the request URI, its port attributes, including the extra_dhcp_opts attributes. Example 4.217. Show port details with extra-dhcp-opt attributes: JSON response { "port": { "status": "DOWN", "binding:host_id": null, "name": "", "allowed_address_pairs": [], "admin_state_up": true, "network_id": "87733bcc-8144-41b1-bb6b-d011d7a5168e", "tenant_id": "7ea98790cd854fb5a82ef3d41e5c156b", "extra_dhcp_opts": [ {"opt_value": "testfile.1","opt_name": "bootfile-name"}, {"opt_value": "123.123.123.123", "opt_name": "tftp-server"}, {"opt_value": "123.123.123.45", "opt_name": "server-ip-address"} ], "binding:vif_type": "ovs", "device_owner": "", "binding:capabilities": {"port_filter": true}, "mac_address": "fa:16:3e:52:92:3a", "fixed_ips": [{"subnet_id": "99a8aea3-b9da-409d-a5e5-f45338ceb4d3", "ip_address": "172.24.4.228"}], "id": "3c0c7a37-690a-43a8-8088-5d4c2c7f8484", "security_groups": ["9bf6f19a-ba4a-470f-b8ce-28c9ad66556c"], "device_id": "" } } Create port Verb URI Description POST /ports Creates a port and explicitly specifies attributes with the extra- dhcp-opt extension attributes. Normal response Code: 200 OK Error response Code: 401 Unauthorized. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 237 This operation returns, for the port specified in the request URI, its port attributes, including the extra_dhcp_opts attributes. Example 4.218. Create port with extra-dhcp-opt attributes: JSON request { "port": { "network_id": "87733bcc-8144-41b1-bb6b-d011d7a5168e", "extra_dhcp_opts": [ {"opt_value": "pxelinux.0", "opt_name": "bootfile-name"}, {"opt_value": "123.123.123.123", "opt_name": "tftp-server"}, {"opt_value": "123.123.123.45", "opt_name": "server-ip-address"} ], "fixed_ips": [{"subnet_id": "99a8aea3-b9da-409d-a5e5-f45338ceb4d3", "ip_address": "172.24.4.230"}], "admin_state_up": true } } Example 4.219. Create port with extra-dhcp-opt attributes: JSON response { "port": { "status": "DOWN", "binding:host_id": null, "name": "", "allowed_address_pairs": [], "admin_state_up": true, "network_id": "87733bcc-8144-41b1-bb6b-d011d7a5168e", "tenant_id": "7ea98790cd854fb5a82ef3d41e5c156b", "extra_dhcp_opts": [ {"opt_value": "123.123.123.123", "opt_name": "tftp-server"}, {"opt_value": "pxelinux.0", "opt_name": "bootfile-name"}, {"opt_value": "123.123.123.45", "opt_name": "server-ip-address"} ], "binding:vif_type": "ovs", "device_owner": "", "binding:capabilities": {"port_filter": true}, "mac_address": "fa:16:3e:43:3c:b7", "fixed_ips": [{"subnet_id": "99a8aea3-b9da-409d-a5e5-f45338ceb4d3", "ip_address": "172.24.4.230"}], "id": "055d27c0-0194-4782-be45-275ff2c95c61", "security_groups": ["9bf6f19a-ba4a-470f-b8ce-28c9ad66556c"], "device_id": "" } } Update port Verb URI Description PUT /ports/port_id Updates attributes for a port, including extra_dhcp_opts extension attributes. Normal response Code: 200 OK Error response Code: 401 Unauthorized. This operation allow for the updating of attributes for the port specified in the request URI, its port attributes, including the extra_dhcp_opts attributes. Networking (neutron) API Reference May 20, 2014 API v2.0 and extensions 238 Example 4.220. Update port with extra-dhcp-opt attributes: JSON request { "port": { "extra_dhcp_opts": [{"opt_value": "testfile.1", "opt_name": "bootfile-name"}] } } Example 4.221. Update port with extra-dhcp-opt attributes: JSON response { "port": { "status": "DOWN", "binding:host_id": null, "name": "", "allowed_address_pairs": [], "admin_state_up": true, "network_id": "87733bcc-8144-41b1-bb6b-d011d7a5168e", "tenant_id": "7ea98790cd854fb5a82ef3d41e5c156b", "extra_dhcp_opts": [ {"opt_value": "123.123.123.123", "opt_name": "tftp-server"}, {"opt_value": "testfile.1", "opt_name": "bootfile-name"}, {"opt_value": "123.123.123.45", "opt_name": "server-ip-address"} ], "binding:vif_type": "ovs", "device_owner": "", "binding:capabilities": {"port_filter": true}, "mac_address": "fa:16:3e:43:3c:b7", "fixed_ips": [{"subnet_id": "99a8aea3-b9da-409d-a5e5-f45338ceb4d3", "ip_address": "172.24.4.230"}], "id": "055d27c0-0194-4782-be45-275ff2c95c61", "security_groups": ["9bf6f19a-ba4a-470f-b8ce-28c9ad66556c"], "device_id": "" } }

下载文档,方便阅读与编辑

文档的实际排版效果,会与网站的显示效果略有不同!!

需要 8 金币 [ 分享文档获得金币 ] 2 人已下载

下载文档

相关文档