Networking API v2.0 (CURRENT)

Use virtual networking services among devices that the OpenStack Compute service manages. The Networking (neutron) API v2.0 combines the API v1.1 functionality with some essential Internet Protocol Address Management (IPAM) functionality. The API enables users to associate IP address blocks and other network configuration settings with an OpenStack Networking network. You can choose an IP address from the block or let OpenStack Networking choose the first available IP address.

Effective in the OpenStack Liberty release, the Networking API v2.0 does not support XML requests and responses.

API versions

Lists information for all Networking API versions.

GET
/
List API versions

Lists information about all Networking API versions.

 
Normal response codes
200 300
{
    "versions": [
        {
            "status": "CURRENT",
            "id": "v2.0",
            "links": [
                {
                    "href": "http://23.253.228.211:9696/v2.0",
                    "rel": "self"
                }
            ]
        }
    ]
}

This operation does not accept a request body.

Networks

Lists, shows details for, creates, updates, and deletes networks.

GET
/v2.0/networks
List networks

Lists networks to which the tenant has access.

 

Use the fields query parameter to filter the response. For information, see Filtering and Column Selection.

Use the tags, tags-any, not-tags, not-tags-any query parameter to filter the response with tags. For information, see REST API Impact.

Normal response codes
200
Error response codes
unauthorized (401)
Response parameters
Parameter Style Type Description
networks plain xsd:list

A list of network objects.

admin_state_up plain xsd:boolean

The administrative state of the network, which is up (true) or down (false).

id plain csapi:UUID

The UUID of the network.

name plain xsd:string

The network name.

shared plain xsd:boolean

Indicates whether this network is shared across all tenants. By default, only administrative users can change this value.

status plain xsd:string

The network status.

subnets plain xsd:list

The associated subnets.

tenant_id plain csapi:UUID

The UUID of the tenant.

router:external plain xsd:boolean

Indicates whether this network is externally accessible.

mtu plain xsd:int

The MTU of a network resource.

availability_zones plain xsd:list

The availability zone for the network.

availability_zone_hints plain xsd:list

The availability zone candidate for the network.

{
    "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,
            "mtu": 0,
            "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,
            "mtu": 0,
            "shared": true,
            "id": "db193ab3-96e3-4cb3-8fc5-05f4296d0324",
            "provider:segmentation_id": null
        }
    ]
}

This operation does not accept a request body.

POST
/v2.0/networks
Create network

Creates a network.

 

A request body is optional. An administrative user can specify another tenant UUID, which is the tenant who owns the network, in the request body.

Normal response codes
201
Error response codes
badRequest (400), unauthorized (401)
Request parameters
Parameter Style Type Description
network plain xsd:dict

A network object.

admin_state_up (Optional) plain xsd:boolean

The administrative state of the network, which is up (true) or down (false).

name (Optional) plain xsd:string

The network name. A request body is optional: If you include it, it can specify this optional attribute.

shared (Optional) plain xsd:boolean

Indicates whether this network is shared across all tenants. By default, only administrative users can change this value.

tenant_id (Optional) plain csapi:UUID

Admin-only. The UUID of the tenant that owns the network. This tenant can be different from the tenant that makes the create network request. However, only administrative users can specify a tenant UUID other than their own. You cannot change this value through authorization policies.

router:external (Optional) plain xsd:boolean

Indicates whether this network is externally accessible.

Response parameters
Parameter Style Type Description
network plain xsd:dict

A network object.

admin_state_up plain xsd:boolean

The administrative state of the network, which is up (true) or down (false).

id plain csapi:UUID

The UUID of the network.

name plain xsd:string

The network name.

shared plain xsd:boolean

Indicates whether this network is shared across all tenants. By default, only administrative users can change this value.

status plain xsd:string

The network status.

subnets plain xsd:list

The associated subnets.

tenant_id plain csapi:UUID

The UUID of the tenant.

router:external plain xsd:boolean

Indicates whether this network is externally accessible.

mtu plain xsd:int

The MTU of a network resource.

availability_zones plain xsd:list

The availability zone for the network.

availability_zone_hints plain xsd:list

The availability zone candidate for the network.

{
    "network": {
        "name": "sample_network",
        "admin_state_up": true
    }
}
{
    "network": {
        "status": "ACTIVE",
        "subnets": [],
        "name": "net1",
        "admin_state_up": true,
        "tenant_id": "9bacb3c5d39d41a79512987f338cf177",
        "router:external": false,
        "mtu": 0,
        "shared": false,
        "id": "4e8e5957-649f-477b-9e5b-f1f75b21c03c"
    }
}
POST
/v2.0/networks
Bulk create 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 parameters
Parameter Style Type Description
networks plain xsd:list

A list of network objects.

admin_state_up (Optional) plain xsd:boolean

The administrative state of the network, which is up (true) or down (false).

name (Optional) plain xsd:string The network name.
shared (Optional) plain xsd:boolean

Admin-only. Indicates whether this network is shared across all tenants.

tenant_id (Optional) plain csapi:UUID

The UUID of the tenant who owns the network. Only administrative users can specify a tenant UUID other than their own. You cannot change this value through authorization policies.

router:external (Optional) plain xsd:boolean

Indicates whether this network is externally accessible.

port_security_enabled (Optional) plain xsd:boolean

The port security status. A valid value is enabled (true) or disabled (false).

Response parameters
Parameter Style Type Description
networks plain xsd:list

A list of network objects.

admin_state_up plain xsd:boolean

The administrative state of the network, which is up (true) or down (false).

id plain csapi:UUID

The UUID of the network.

name plain xsd:string

The network name.

shared plain xsd:boolean

Indicates whether this network is shared across all tenants.

status plain xsd:string

The network status.

subnets plain xsd:list

The associated subnets.

tenant_id plain csapi:UUID

The UUID of the tenant who owns the network.

router:external plain xsd:boolean

Indicates whether this network is externally accessible.

mtu plain xsd:int

The MTU of a network resource.

port_security_enabled plain xsd:boolean

The port security status. A valid value is enabled (true) or disabled (false).

{
    "networks": [
        {
            "name": "sample_network3",
            "admin_state_up": true
        },
        {
            "name": "sample_network4",
            "admin_state_up": true
        }
    ]
}
{
    "networks": [
        {
            "status": "ACTIVE",
            "subnets": [],
            "name": "sample_network3",
            "provider:physical_network": null,
            "admin_state_up": true,
            "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
            "mtu": 0,
            "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",
            "mtu": 0,
            "shared": false,
            "id": "af374017-c9ae-4a1d-b799-ab73111476e2",
            "provider:segmentation_id": null
        }
    ]
}
GET
/v2.0/networks/​{network_id}​
Show network details

Shows details for a network.

 

You can control which response parameters are returned by using the fields query parameter. For information, see Filtering and column selection.

The response might show extension response parameters. For information, see Networks multiple provider extension (networks).

Normal response codes
200
Error response codes
unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
network_id URI csapi:UUID

The UUID of the network.

Response parameters
Parameter Style Type Description
network plain xsd:dict

A network object.

admin_state_up plain xsd:boolean

The administrative state of the network, which is up (true) or down (false).

id plain csapi:UUID

The UUID of the network.

changed_at plain xsd:dateTime

Time at which the network has been created.

name plain xsd:string

The network name.

shared plain xsd:boolean

Indicates whether this network is shared across all tenants. By default, only administrative users can change this value.

status plain xsd:string

The network status.

subnets plain xsd:list

The associated subnets.

tenant_id plain csapi:UUID

The UUID of the tenant.

router:external plain xsd:boolean

Indicates whether this network is externally accessible.

updated_at plain xsd:dateTime

Time at which the network has been updated.

mtu plain xsd:int

The MTU of a network resource.

availability_zones plain xsd:list

The availability zone for the network.

availability_zone_hints plain xsd:list

The availability zone candidate for the network.

{
    "network": {
        "status": "ACTIVE",
        "subnets": [
            "54d6f61d-db07-451c-9ab3-b9609b6b6f0b"
        ],
        "name": "private-network",
        "router:external": false,
        "admin_state_up": true,
        "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
        "created_at": "2016-03-08T20:19:41",
        "mtu": 0,
        "shared": true,
        "port_security_enabled": true,
        "updated_at": "2016-03-08T20:19:41",
        "id": "d32019d3-bc6e-4319-9c1d-6722fc136a22"
    }
}

This operation does not accept a request body.

PUT
/v2.0/networks/​{network_id}​
Update network

Updates a network.

 
Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), forbidden (403), itemNotFound (404)
Request parameters
Parameter Style Type Description
network_id URI csapi:UUID

The UUID of the network.

network plain xsd:dict

A network object.

admin_state_up (Optional) plain xsd:boolean

The administrative state of the network, which is up (true) or down (false).

name (Optional) plain xsd:string The network name.
shared (Optional) plain xsd:boolean

Admin-only. Indicates whether this network is shared across all tenants.

router:external (Optional) plain xsd:boolean

Indicates whether this network is externally accessible.

port_security_enabled (Optional) plain xsd:boolean

The port security status. A valid value is enabled (true) or disabled (false).

Response parameters
Parameter Style Type Description
network plain xsd:dict

A network object.

admin_state_up plain xsd:boolean

The administrative state of the network, which is up (true) or down (false).

id plain csapi:UUID

The UUID of the network.

name plain xsd:string

The network name.

shared plain xsd:boolean

Indicates whether this network is shared across all tenants. By default, only administrative users can change this value.

status plain xsd:string

The network status.

subnets plain xsd:list

The associated subnets.

tenant_id plain csapi:UUID

The UUID of the tenant.

router:external plain xsd:boolean

Indicates whether this network is externally accessible.

mtu plain xsd:int

The MTU of a network resource.

availability_zones plain xsd:list

The availability zone for the network.

availability_zone_hints plain xsd:list

The availability zone candidate for the network.

{
    "network": {
        "name": "sample_network_5_updated"
    }
}
{
    "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,
        "mtu": 0,
        "shared": false,
        "port_security_enabled": true,
        "id": "1f370095-98f6-4079-be64-6d3d4a6adcc6",
        "provider:segmentation_id": null
    }
}
DELETE
/v2.0/networks/​{network_id}​
Delete network

Deletes a network and its associated resources.

 
Normal response codes
204
Error response codes
unauthorized (401), itemNotFound (404), conflict (409)
Request parameters
Parameter Style Type Description
network_id URI csapi:UUID

The UUID of the network.

This operation does not accept a request body and does not return a response body.

Subnets

Lists, shows details for, creates, updates, and deletes subnet resources.

GET
/v2.0/subnets
List subnets

Lists subnets to which the tenant has access.

 

Default policy settings returns exclusively subnets owned by the tenant submitting the request, unless the request is submitted by a 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.

Normal response codes
200
Error response codes
unauthorized (401)
Request parameters
Parameter Style Type Description
display_name (Optional) query xsd:string

Name of the network.

network_id (Optional) query csapi:UUID

The ID of the attached network.

tenant_id (Optional) plain csapi:UUID

The UUID of the tenant who owns the network. Only administrative users can specify a tenant UUID other than their own. You cannot change this value through authorization policies.

gateway_ip (Optional) query xsd:string

The gateway IP address.

ip_version (Optional) query xsd:int

The IP version, which is 4 or 6.

cidr (Optional) query xsd:string

The CIDR.

id (Optional) query csapi:UUID

The ID of the subnet.

enable_dhcp (Optional) query xsd:boolean

If true, DHCP is enabled and If false, DHCP is disabled.

ipv6_ra_mode (Optional) query xsd:string

A valid value is dhcpv6-stateful, dhcpv6-stateless, or slaac.

ipv6_address_mode (Optional) query xsd:string

A valid value is dhcpv6-stateful, dhcpv6-stateless, or slaac.

Response parameters
Parameter Style Type Description
subnets plain xsd:list

A list of subnet objects.

name plain xsd:string

The subnet name.

network_id plain csapi:UUID

The UUID of the attached network.

created_at plain xsd:dateTime

Time at which subnet has been created.

updated_at plain xsd:dateTime

Time at which subnet has been updated.

tenant_id plain csapi:UUID

The UUID of the tenant who owns the network. Only administrative users can specify a tenant UUID other than their own.

allocation_pools plain xsd:list

The start and end addresses for the allocation pools.

start plain xsd:string

The start address for the allocation pools.

end plain xsd:string

The end address for the allocation pools.

gateway_ip plain xsd:string

The gateway IP address.

ip_version plain xsd:int

The IP version, which is 4 or 6.

cidr plain xsd:string

The CIDR.

id plain csapi:UUID

The UUID of the subnet.

enable_dhcp plain xsd:boolean

Set to true if DHCP is enabled and false if DHCP is disabled.

dns_nameservers plain xsd:list

The DNS server.

host_routes plain xsd:list

A list of host route dictionaries for the subnet. For example:

"host_routes":[
    {
      "destination":"0.0.0.0/0",
      "nexthop":"123.45.67.89"
    },
    {
      "destination":"192.168.0.0/24",
      "nexthop":"192.168.0.1"
    }
]
destination plain xsd:string

The destination for static route.

nexthop plain xsd:string

The next hop for the destination.

ipv6_ra_mode plain xsd:string

The IPv6 RA mode, which is dhcpv6-stateful, dhcpv6-stateless, or slaac.

ipv6_address_mode plain xsd:string

The IPv6 address mode, which is dhcpv6-stateful, dhcpv6-stateless, or slaac.

{
    "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"
                }
            ],
            "host_routes": [],
            "ip_version": 4,
            "gateway_ip": "192.0.0.1",
            "cidr": "192.0.0.0/8",
            "id": "54d6f61d-db07-451c-9ab3-b9609b6b6f0b"
        }
    ]
}
POST
/v2.0/subnets
Create subnet

Creates a subnet on a network.

 

OpenStack Networking does not try to derive the correct IP version from the CIDR. If you do not specify the gateway_ip attribute, OpenStack Networking allocates an address from the CIDR for the gateway for the subnet.

To specify a subnet without a gateway, set the gateway_ip attribute to null in the request body. If you do not specify the allocation_pools attribute, 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 you specify both the allocation_pools and gateway_ip attributes, you must ensure that the gateway IP does not overlap with the allocation pools; otherwise, the call returns the Conflict (409) response code.

A subnet can have one or more name servers and host routes. Hosts in this subnet use the name servers. Devices with IP addresses from this subnet, not including the local subnet route, use the host routes.

Specify the ipv6_ra_mode and ipv6_address_mode attributes to create subnets that support IPv6 configurations, such as stateless address autoconfiguration (SLAAC), DHCPv6 stateful, and DHCPv6 stateless configurations.

Normal response codes
201
Error response codes
badRequest (400), unauthorized (401), forbidden (403), itemNotFound (404), conflict (409)
Request parameters
Parameter Style Type Description
subnet plain xsd:dict

A subnet object.

name (Optional) plain xsd:string

The subnet name.

network_id plain csapi:UUID

The UUID of the attached network.

tenant_id (Optional) plain csapi:UUID

The UUID of the tenant who owns the network. Only administrative users can specify a tenant UUID other than their own. You cannot change this value through authorization policies.

allocation_pools (Optional) plain xsd:list

The start and end addresses for the allocation pools.

start (Optional) plain xsd:string

The start address for the allocation pools.

end (Optional) plain xsd:string

The end address for the allocation pools.

gateway_ip (Optional) plain xsd:string

The gateway IP address.

ip_version plain xsd:int

The IP version, which is 4 or 6.

cidr plain xsd:string

The CIDR.

enable_dhcp (Optional) plain xsd:boolean

Set to true if DHCP is enabled and false if DHCP is disabled.

dns_nameservers (Optional) plain xsd:list

A list of DNS name servers for the subnet. Specify each name server as an IP address and separate multiple entries with a space. For example [8.8.8.7 8.8.8.8].

host_routes (Optional) plain xsd:list

A list of host route dictionaries for the subnet. For example:

"host_routes":[
    {
      "destination":"0.0.0.0/0",
      "nexthop":"123.45.67.89"
    },
    {
      "destination":"192.168.0.0/24",
      "nexthop":"192.168.0.1"
    }
]
destination (Optional) plain xsd:string

The destination for static route.

nexthop (Optional) plain xsd:string

The next hop for the destination.

ipv6_ra_mode (Optional) plain xsd:string

A valid value is dhcpv6-stateful, dhcpv6-stateless, or slaac.

ipv6_address_mode (Optional) plain xsd:string

A valid value is dhcpv6-stateful, dhcpv6-stateless, or slaac.

Response parameters
Parameter Style Type Description
subnet plain xsd:dict

A subnet object.

name plain xsd:string

The subnet name.

network_id plain csapi:UUID

The UUID of the attached network.

created_at plain xsd:dateTime

Time at which subnet has been created.

updated_at plain xsd:dateTime

Time at which subnet has been updated.

tenant_id plain csapi:UUID

The UUID of the tenant who owns the network. Only administrative users can specify a tenant UUID other than their own.

allocation_pools plain xsd:list

The start and end addresses for the allocation pools.

start plain xsd:string

The start address for the allocation pools.

end plain xsd:string

The end address for the allocation pools.

gateway_ip plain xsd:string

The gateway IP address.

ip_version plain xsd:int

The IP version, which is 4 or 6.

cidr plain xsd:string

The CIDR.

id plain csapi:UUID

The UUID of the subnet.

enable_dhcp plain xsd:boolean

Set to true if DHCP is enabled and false if DHCP is disabled.

dns_nameservers plain xsd:list

The DNS server.

host_routes plain xsd:list

A list of host route dictionaries for the subnet. For example:

"host_routes":[
    {
      "destination":"0.0.0.0/0",
      "nexthop":"123.45.67.89"
    },
    {
      "destination":"192.168.0.0/24",
      "nexthop":"192.168.0.1"
    }
]
destination plain xsd:string

The destination for static route.

nexthop plain xsd:string

The next hop for the destination.

ipv6_ra_mode plain xsd:string

The IPv6 RA mode, which is dhcpv6-stateful, dhcpv6-stateless, or slaac.

ipv6_address_mode plain xsd:string

The IPv6 address mode, which is dhcpv6-stateful, dhcpv6-stateless, or slaac.

{
    "subnet": {
        "network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
        "ip_version": 4,
        "cidr": "10.0.0.1"
    }
}
{
    "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"
    }
}
POST
/v2.0/subnets
Bulk create subnet

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 parameters
Parameter Style Type Description
subnets plain xsd:list

A list of subnet objects.

name (Optional) plain xsd:string

The subnet name.

network_id plain csapi:UUID

The UUID of the attached network.

tenant_id (Optional) plain csapi:UUID

The UUID of the tenant who owns the network. Only administrative users can specify a tenant UUID other than their own. You cannot change this value through authorization policies.

allocation_pools (Optional) plain xsd:list

The start and end addresses for the allocation pools.

start (Optional) plain xsd:string

The start address for the allocation pools.

end (Optional) plain xsd:string

The end address for the allocation pools.

gateway_ip (Optional) plain xsd:string

The gateway IP address.

ip_version plain xsd:int

The IP version, which is 4 or 6.

cidr plain xsd:string

The CIDR.

enable_dhcp (Optional) plain xsd:boolean

Set to true if DHCP is enabled and false if DHCP is disabled.

dns_nameservers (Optional) plain xsd:list

A list of DNS name servers for the subnet. Specify each name server as an IP address and separate multiple entries with a space. For example [8.8.8.7 8.8.8.8].

host_routes (Optional) plain xsd:list

A list of host route dictionaries for the subnet. For example:

"host_routes":[
    {
      "destination":"0.0.0.0/0",
      "nexthop":"123.45.67.89"
    },
    {
      "destination":"192.168.0.0/24",
      "nexthop":"192.168.0.1"
    }
]
destination (Optional) plain xsd:string

The destination for static route.

nexthop (Optional) plain xsd:string

The next hop for the destination.

ipv6_ra_mode (Optional) plain xsd:string

A valid value is dhcpv6-stateful, dhcpv6-stateless, or slaac.

ipv6_address_mode (Optional) plain xsd:string

A valid value is dhcpv6-stateful, dhcpv6-stateless, or slaac.

Response parameters
Parameter Style Type Description
subnets plain xsd:list

A list of subnet objects.

name plain xsd:string

The subnet name.

network_id plain csapi:UUID

The UUID of the attached network.

created_at plain xsd:dateTime

Time at which subnet has been created.

updated_at plain xsd:dateTime

Time at which subnet has been updated.

tenant_id plain csapi:UUID

The UUID of the tenant who owns the network. Only administrative users can specify a tenant UUID other than their own.

allocation_pools plain xsd:list

The start and end addresses for the allocation pools.

start plain xsd:string

The start address for the allocation pools.

end plain xsd:string

The end address for the allocation pools.

gateway_ip plain xsd:string

The gateway IP address.

ip_version plain xsd:int

The IP version, which is 4 or 6.

cidr plain xsd:string

The CIDR.

id plain csapi:UUID

The UUID of the subnet.

enable_dhcp plain xsd:boolean

Set to true if DHCP is enabled and false if DHCP is disabled.

dns_nameservers plain xsd:list

The DNS server.

host_routes plain xsd:list

A list of host route dictionaries for the subnet. For example:

"host_routes":[
    {
      "destination":"0.0.0.0/0",
      "nexthop":"123.45.67.89"
    },
    {
      "destination":"192.168.0.0/24",
      "nexthop":"192.168.0.1"
    }
]
destination plain xsd:string

The destination for static route.

nexthop plain xsd:string

The next hop for the destination.

ipv6_ra_mode plain xsd:string

The IPv6 RA mode, which is dhcpv6-stateful, dhcpv6-stateless, or slaac.

ipv6_address_mode plain xsd:string

The IPv6 address mode, which is dhcpv6-stateful, dhcpv6-stateless, or slaac.

{
    "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"
        }
    ]
}
{
    "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"
        }
    ]
}
GET
/v2.0/subnets/​{subnet_id}​
Show subnet details

Shows details for a subnet.

 

Use the fields query parameter to filter the results.

Normal response codes
200
Error response codes
unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
subnet_id URI csapi:UUID

The UUID of the subnet.

Response parameters
Parameter Style Type Description
subnet plain xsd:dict

A subnet object.

name plain xsd:string

The subnet name.

network_id plain csapi:UUID

The UUID of the attached network.

created_at plain xsd:dateTime

Time at which subnet has been created.

updated_at plain xsd:dateTime

Time at which subnet has been updated.

tenant_id plain csapi:UUID

The UUID of the tenant who owns the network. Only administrative users can specify a tenant UUID other than their own.

allocation_pools plain xsd:list

The start and end addresses for the allocation pools.

start plain xsd:string

The start address for the allocation pools.

end plain xsd:string

The end address for the allocation pools.

gateway_ip plain xsd:string

The gateway IP address.

ip_version plain xsd:int

The IP version, which is 4 or 6.

cidr plain xsd:string

The CIDR.

id plain csapi:UUID

The UUID of the subnet.

enable_dhcp plain xsd:boolean

Set to true if DHCP is enabled and false if DHCP is disabled.

dns_nameservers plain xsd:list

The DNS server.

host_routes plain xsd:list

A list of host route dictionaries for the subnet. For example:

"host_routes":[
    {
      "destination":"0.0.0.0/0",
      "nexthop":"123.45.67.89"
    },
    {
      "destination":"192.168.0.0/24",
      "nexthop":"192.168.0.1"
    }
]
destination plain xsd:string

The destination for static route.

nexthop plain xsd:string

The next hop for the destination.

ipv6_ra_mode plain xsd:string

The IPv6 RA mode, which is dhcpv6-stateful, dhcpv6-stateless, or slaac.

ipv6_address_mode plain xsd:string

The IPv6 address mode, which is dhcpv6-stateful, dhcpv6-stateless, or slaac.

{
    "subnet": {
        "name": "my_subnet",
        "enable_dhcp": true,
        "network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
        "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
        "created_at": "2016-03-08T20:19:41",
        "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",
        "updated_at": "2016-03-08T20:19:41",
        "id": "54d6f61d-db07-451c-9ab3-b9609b6b6f0b"
    }
}

This operation does not accept a request body.

PUT
/v2.0/subnets/​{subnet_id}​
Update subnet

Updates a subnet.

 

Some attributes, such as IP version (ip_version), and CIDR (cidr) cannot be updated. Attempting to update these attributes results in a 400 Bad Request error.

Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), forbidden (403), itemNotFound (404)
Request parameters
Parameter Style Type Description
subnet_id URI csapi:UUID

The UUID of the subnet.

subnet plain xsd:dict

A subnet object.

name (Optional) plain xsd:string

The subnet name.

allocation_pools (Optional) plain xsd:dict

The start and end addresses for the allocation pools.

start (Optional) plain xsd:string

The start address for the allocation pools.

end (Optional) plain xsd:string

The end address for the allocation pools.

gateway_ip (Optional) plain xsd:string

The gateway IP address.

enable_dhcp (Optional) plain xsd:boolean

Set to true if DHCP is enabled and false if DHCP is disabled.

dns_nameservers (Optional) plain xsd:list

The DNS server.

host_routes (Optional) plain xsd:list

A list of host route dictionaries for the subnet. For example:

"host_routes":[
    {
      "destination":"0.0.0.0/0",
      "nexthop":"123.45.67.89"
    },
    {
      "destination":"192.168.0.0/24",
      "nexthop":"192.168.0.1"
    }
]
destination (Optional) plain xsd:string

The destination for static route.

nexthop (Optional) plain xsd:string

The next hop for the destination.

Response parameters
Parameter Style Type Description
subnet plain xsd:dict

A subnet object.

name plain xsd:string

The subnet name.

network_id plain csapi:UUID

The UUID of the attached network.

created_at plain xsd:dateTime

Time at which subnet has been created.

updated_at plain xsd:dateTime

Time at which subnet has been updated.

tenant_id plain csapi:UUID

The UUID of the tenant who owns the network. Only administrative users can specify a tenant UUID other than their own.

allocation_pools plain xsd:list

The start and end addresses for the allocation pools.

start plain xsd:string

The start address for the allocation pools.

end plain xsd:string

The end address for the allocation pools.

gateway_ip plain xsd:string

The gateway IP address.

ip_version plain xsd:int

The IP version, which is 4 or 6.

cidr plain xsd:string

The CIDR.

id plain csapi:UUID

The UUID of the subnet.

enable_dhcp plain xsd:boolean

Set to true if DHCP is enabled and false if DHCP is disabled.

dns_nameservers plain xsd:list

The DNS server.

host_routes plain xsd:list

A list of host route dictionaries for the subnet. For example:

"host_routes":[
    {
      "destination":"0.0.0.0/0",
      "nexthop":"123.45.67.89"
    },
    {
      "destination":"192.168.0.0/24",
      "nexthop":"192.168.0.1"
    }
]
destination plain xsd:string

The destination for static route.

nexthop plain xsd:string

The next hop for the destination.

ipv6_ra_mode plain xsd:string

The IPv6 RA mode, which is dhcpv6-stateful, dhcpv6-stateless, or slaac.

ipv6_address_mode plain xsd:string

The IPv6 address mode, which is dhcpv6-stateful, dhcpv6-stateless, or slaac.

{
    "subnet": {
        "name": "my_subnet"
    }
}
{
    "subnet": {
        "name": "my_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"
    }
}
DELETE
/v2.0/subnets/​{subnet_id}​
Delete subnet

Deletes a 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 parameters
Parameter Style Type Description
subnet_id URI csapi:UUID

The UUID of the subnet.

This operation does not accept a request body and does not return a response body.

Ports

Lists, shows details for, creates, updates, and deletes ports.

GET
/v2.0/ports
List ports

Lists ports to which the tenant has access.

 

Default policy settings return only those ports that are owned by the tenant who submits the request, unless the request is submitted by a user with administrative rights. Users can control which attributes are returned by using the fields query parameter. You can use query parameters to filter the response.For information, see Filtering and Column Selection.

Normal response codes
200
Error response codes
unauthorized (401)
Request parameters
Parameter Style Type Description
status (Optional) query xsd:string

The port status. Value is ACTIVE or DOWN.

display_name (Optional) query xsd:string

The port name.

admin_state (Optional) query xsd:boolean

The administrative state of the router, which is up (true) or down (false).

network_id (Optional) query csapi:UUID

The UUID of the attached network.

tenant_id (Optional) query csapi:UUID

The UUID of the tenant who owns the network. Only administrative users can specify a tenant UUID other than their own. You cannot change this value through authorization policies.

device_owner (Optional) query xsd:string

The UUID of the entity that uses this port. For example, a DHCP agent.

mac_address (Optional) query xsd:string

The MAC address of the port.

port_id (Optional) query csapi:UUID

The UUID of the port.

security_groups (Optional) query xsd:list

The UUIDs of any attached security groups.

device_id (Optional) query csapi:UUID

The UUID of the device that uses this port. For example, a virtual server.

Response parameters
Parameter Style Type Description
ports plain xsd:list

A list of port objects.

status plain xsd:string

The port status. Value is ACTIVE or DOWN.

name plain xsd:string

The port name.

allowed_address_pairs plain xsd:list

A set of zero or more allowed address pairs. An address pair consists of an IP address and MAC address.

ip_address plain xsd:string

The IP address.

mac_address plain xsd:string

The MAC address.

created_at plain xsd:dateTime

Time at which port has been created.

updated_at plain xsd:dateTime

Time at which port has been updated.

admin_state_up plain xsd:boolean

The administrative state of the port, which is up (true) or down (false).

network_id plain csapi:UUID

The UUID of the attached network.

tenant_id plain csapi:UUID

The UUID of the tenant who owns the network. Only administrative users can specify a tenant UUID other than their own.

extra_dhcp_opts plain xsd:list

A set of zero or more extra DHCP option pairs. An option pair consists of an option value and name.

opt_value plain xsd:string

The extra DHCP option value.

opt_name plain xsd:string

The extra DHCP option name.

device_owner plain xsd:string

The UUID of the entity that uses this port. For example, a DHCP agent.

fixed_ips plain xsd:list

The IP addresses for the port. Includes the IP address and UUID of the subnet.

subnet_id plain csapi:UUID

The UUID of the subnet to which the port is attached.

ip_address plain xsd:string

The fixed IP address of the port.

id plain csapi:UUID

The UUID of the port.

security_groups plain xsd:list

The UUIDs of any attached security groups.

device_id plain csapi:UUID

The UUID of the device that uses this port. For example, a virtual server.

port_security_enabled plain xsd:boolean

The port security status. The status is enabled (true) or disabled (false).

{
    "ports": [
        {
            "status": "ACTIVE",
            "name": "",
            "allowed_address_pairs": [],
            "admin_state_up": true,
            "network_id": "70c1db1f-b701-45bd-96e0-a313ee3430b3",
            "tenant_id": "",
            "extra_dhcp_opts": [],
            "device_owner": "network:router_gateway",
            "mac_address": "fa:16:3e:58:42:ed",
            "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",
            "name": "",
            "allowed_address_pairs": [],
            "admin_state_up": true,
            "network_id": "f27aa545-cbdd-4907-b0c6-c9e8b039dcc2",
            "tenant_id": "d397de8a63f341818f198abb0966f6f3",
            "extra_dhcp_opts": [],
            "device_owner": "network:router_interface",
            "mac_address": "fa:16:3e:bb:3c:e4",
            "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"
        }
    ]
}
POST
/v2.0/ports
Create port

Creates a port on a network.

 

To define the network in which to create the port, specify 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 parameters
Parameter Style Type Description
port plain xsd:dict

A port object.

name (Optional) plain xsd:string

A symbolic name for the port.

admin_state_up (Optional) plain xsd:boolean

The administrative status of the port, which is up (true) or down (false).

tenant_id (Optional) plain csapi:UUID

The UUID of the tenant who owns the network. Only administrative users can specify a tenant UUID other than their own. You cannot change this value through authorization policies.

mac_address (Optional) plain xsd:string

The MAC address. If you specify an address that is not valid, a Bad Request (400) status code is returned. If you do not specify a MAC address, OpenStack Networking tries to allocate one. If a failure occurs, a Service Unavailable (503) response code is returned.

fixed_ips (Optional) plain xsd:list

If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.

subnet_id (Optional) plain csapi:UUID

If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.

ip_address (Optional) plain xsd:string

If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.

security_groups (Optional) plain xsd:list

One or more security group UUIDs.

network_id plain csapi:UUID

The UUID of the network.

allowed_address_pairs (Optional) plain xsd:list

A set of zero or more allowed address pairs. An address pair contains an IP address and MAC address.

ip_address (Optional) plain xsd:string

The IP address of an allowed address pair.

mac_address (Optional) plain xsd:string

The MAC address of an allowed address pair.

opt_value (Optional) plain xsd:string

The extra DHCP option value.

opt_name (Optional) plain xsd:string

The extra DHCP option name.

device_owner (Optional) plain xsd:string

The UUID of the entity that uses this port. For example, a DHCP agent.

device_id (Optional) plain csapi:UUID

The UUID of the device that uses this port. For example, a virtual server.

Response parameters
Parameter Style Type Description
port plain xsd:dict

A port object.

status plain xsd:string

The port status. Value is ACTIVE or DOWN.

name plain xsd:string

The port name.

allowed_address_pairs plain xsd:list

A set of zero or more allowed address pairs. An address pair consists of an IP address and MAC address.

ip_address plain xsd:string

The IP address.

mac_address plain xsd:string

The MAC address.

created_at plain xsd:dateTime

Time at which port has been created.

updated_at plain xsd:dateTime

Time at which port has been updated.

admin_state_up plain xsd:boolean

The administrative state of the port, which is up (true) or down (false).

network_id plain csapi:UUID

The UUID of the attached network.

tenant_id plain csapi:UUID

The UUID of the tenant who owns the network. Only administrative users can specify a tenant UUID other than their own.

extra_dhcp_opts plain xsd:list

A set of zero or more extra DHCP option pairs. An option pair consists of an option value and name.

opt_value plain xsd:string

The extra DHCP option value.

opt_name plain xsd:string

The extra DHCP option name.

device_owner plain xsd:string

The UUID of the entity that uses this port. For example, a DHCP agent.

fixed_ips plain xsd:list

The IP addresses for the port. Includes the IP address and UUID of the subnet.

subnet_id plain csapi:UUID

The UUID of the subnet to which the port is attached.

ip_address plain xsd:string

The fixed IP address of the port.

id plain csapi:UUID

The UUID of the port.

security_groups plain xsd:list

The UUIDs of any attached security groups.

device_id plain csapi:UUID

The UUID of the device that uses this port. For example, a virtual server.

port_security_enabled plain xsd:boolean

The port security status. The status is enabled (true) or disabled (false).

{
    "port": {
        "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7",
        "name": "private-port",
        "admin_state_up": true
    }
}
{
    "port": {
        "status": "DOWN",
        "name": "private-port",
        "allowed_address_pairs": [],
        "admin_state_up": true,
        "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7",
        "tenant_id": "d6700c0c9ffa4f1cb322cd4a1f3906fa",
        "device_owner": "",
        "mac_address": "fa:16:3e:c9:cb:f0",
        "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": ""
    }
}
POST
/v2.0/ports
Bulk create 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 parameters
Parameter Style Type Description
ports plain xsd:list

A list of port objects.

name (Optional) plain xsd:string

A symbolic name for the port.

admin_state_up (Optional) plain xsd:boolean

The administrative status of the port, which is up (true) or down (false).

tenant_id (Optional) plain csapi:UUID

The UUID of the tenant who owns the network. Only administrative users can specify a tenant UUID other than their own. You cannot change this value through authorization policies.

mac_address (Optional) plain xsd:string

The MAC address. If you specify an address that is not valid, a Bad Request (400) status code is returned. If you do not specify a MAC address, OpenStack Networking tries to allocate one. If a failure occurs, a Service Unavailable (503) response code is returned.

fixed_ips (Optional) plain xsd:list

If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.

subnet_id (Optional) plain csapi:UUID

If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.

ip_address (Optional) plain xsd:string

If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.

security_groups (Optional) plain xsd:list

One or more security group UUIDs.

network_id plain csapi:UUID

The UUID of the network.

allowed_address_pairs (Optional) plain xsd:list

A set of zero or more allowed address pairs. An address pair contains an IP address and MAC address.

ip_address (Optional) plain xsd:string

The IP address of an allowed address pair.

mac_address (Optional) plain xsd:string

The MAC address of an allowed address pair.

opt_value (Optional) plain xsd:string

The extra DHCP option value.

opt_name (Optional) plain xsd:string

The extra DHCP option name.

device_owner (Optional) plain xsd:string

The UUID of the entity that uses this port. For example, a DHCP agent.

device_id (Optional) plain csapi:UUID

The UUID of the device that uses this port. For example, a virtual server.

Response parameters
Parameter Style Type Description
ports plain xsd:list

A list of port objects.

status plain xsd:string

The port status. Value is ACTIVE or DOWN.

name plain xsd:string

The port name.

allowed_address_pairs plain xsd:list

A set of zero or more allowed address pairs. An address pair consists of an IP address and MAC address.

ip_address plain xsd:string

The IP address.

mac_address plain xsd:string

The MAC address.

created_at plain xsd:dateTime

Time at which port has been created.

updated_at plain xsd:dateTime

Time at which port has been updated.

admin_state_up plain xsd:boolean

The administrative state of the port, which is up (true) or down (false).

network_id plain csapi:UUID

The UUID of the attached network.

tenant_id plain csapi:UUID

The UUID of the tenant who owns the network. Only administrative users can specify a tenant UUID other than their own.

extra_dhcp_opts plain xsd:list

A set of zero or more extra DHCP option pairs. An option pair consists of an option value and name.

opt_value plain xsd:string

The extra DHCP option value.

opt_name plain xsd:string

The extra DHCP option name.

device_owner plain xsd:string

The UUID of the entity that uses this port. For example, a DHCP agent.

fixed_ips plain xsd:list

The IP addresses for the port. Includes the IP address and UUID of the subnet.

subnet_id plain csapi:UUID

The UUID of the subnet to which the port is attached.

ip_address plain xsd:string

The fixed IP address of the port.

id plain csapi:UUID

The UUID of the port.

security_groups plain xsd:list

The UUIDs of any attached security groups.

device_id plain csapi:UUID

The UUID of the device that uses this port. For example, a virtual server.

port_security_enabled plain xsd:boolean

The port security status. The status is enabled (true) or disabled (false).

{
    "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"
        }
    ]
}
{
    "ports": [
        {
            "status": "DOWN",
            "name": "sample_port_1",
            "allowed_address_pairs": [],
            "admin_state_up": false,
            "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7",
            "tenant_id": "d6700c0c9ffa4f1cb322cd4a1f3906fa",
            "device_owner": "",
            "mac_address": "fa:16:3e:48:b8:9f",
            "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",
            "name": "sample_port_2",
            "allowed_address_pairs": [],
            "admin_state_up": false,
            "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7",
            "tenant_id": "d6700c0c9ffa4f1cb322cd4a1f3906fa",
            "device_owner": "",
            "mac_address": "fa:16:3e:f4:73:df",
            "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": ""
        }
    ]
}
GET
/v2.0/ports/​{port_id}​
Show port details

Shows details for a port.

 
Normal response codes
200
Error response codes
unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
port_id URI csapi:UUID

The UUID of the port.

Response parameters
Parameter Style Type Description
port plain xsd:dict

A port object.

status plain xsd:string

The port status. Value is ACTIVE or DOWN.

name plain xsd:string

The port name.

allowed_address_pairs plain xsd:list

A set of zero or more allowed address pairs. An address pair consists of an IP address and MAC address.

ip_address plain xsd:string

The IP address.

mac_address plain xsd:string

The MAC address.

created_at plain xsd:dateTime

Time at which port has been created.

updated_at plain xsd:dateTime

Time at which port has been updated.

admin_state_up plain xsd:boolean

The administrative state of the port, which is up (true) or down (false).

network_id plain csapi:UUID

The UUID of the attached network.

tenant_id plain csapi:UUID

The UUID of the tenant who owns the network. Only administrative users can specify a tenant UUID other than their own.

extra_dhcp_opts plain xsd:list

A set of zero or more extra DHCP option pairs. An option pair consists of an option value and name.

opt_value plain xsd:string

The extra DHCP option value.

opt_name plain xsd:string

The extra DHCP option name.

device_owner plain xsd:string

The UUID of the entity that uses this port. For example, a DHCP agent.

fixed_ips plain xsd:list

The IP addresses for the port. Includes the IP address and UUID of the subnet.

subnet_id plain csapi:UUID

The UUID of the subnet to which the port is attached.

ip_address plain xsd:string

The fixed IP address of the port.

id plain csapi:UUID

The UUID of the port.

security_groups plain xsd:list

The UUIDs of any attached security groups.

device_id plain csapi:UUID

The UUID of the device that uses this port. For example, a virtual server.

port_security_enabled plain xsd:boolean

The port security status. The status is enabled (true) or disabled (false).

{
    "port": {
        "status": "ACTIVE",
        "name": "",
        "allowed_address_pairs": [],
        "admin_state_up": true,
        "network_id": "a87cc70a-3e15-4acf-8205-9b711a3531b7",
        "tenant_id": "7e02058126cc4950b75f9970368ba177",
        "created_at": "2016-03-08T20:19:41",
        "extra_dhcp_opts": [],
        "device_owner": "network:router_interface",
        "mac_address": "fa:16:3e:23:fd:d7",
        "fixed_ips": [
            {
                "subnet_id": "a0304c3a-4f08-4c43-88af-d796509c97d2",
                "ip_address": "10.0.0.1"
            }
        ],
        "id": "46d4bfb9-b26e-41f3-bd2e-e6dcc1ccedb2",
        "updated_at": "2016-03-08T20:19:41",
        "security_groups": [],
        "device_id": "5e3898d7-11be-483e-9732-b2f5eccd2b2e"
    }
}

This operation does not accept a request body.

PUT
/v2.0/ports/​{port_id}​
Update port

Updates a 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 subnet allocation pools, and replaced by the IPs in the request body. Therefore, this operation replaces the fixed_ip attribute when you specify it 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 in the request body. Therefore, this operation replaces the security_groups attribute when you specify it in the request body. If the 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 parameters
Parameter Style Type Description
port_id URI csapi:UUID

The UUID of the port.

port plain xsd:dict

A port object.

name (Optional) plain xsd:string

A symbolic name for the port.

admin_state_up (Optional) plain xsd:boolean

The administrative status of the port, which is up (true) or down (false).

tenant_id (Optional) plain csapi:UUID

The UUID of the tenant who owns the network. Only administrative users can specify a tenant UUID other than their own. You cannot change this value through authorization policies.

mac_address (Optional) plain xsd:string

The MAC address. If you specify an address that is not valid, a Bad Request (400) status code is returned. If you do not specify a MAC address, OpenStack Networking tries to allocate one. If a failure occurs, a Service Unavailable (503) response code is returned.

fixed_ips (Optional) plain xsd:list

If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.

subnet_id (Optional) plain csapi:UUID

If you specify only a subnet UUID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.

ip_address (Optional) plain xsd:string

If you specify both a subnet UUID and an IP address, OpenStack Networking tries to allocate the address to the port.

security_groups (Optional) plain xsd:list

One or more security group UUIDs.

network_id plain csapi:UUID

The UUID of the network.

allowed_address_pairs (Optional) plain xsd:list

A set of zero or more allowed address pairs. An address pair contains an IP address and MAC address.

ip_address (Optional) plain xsd:string

The IP address of an allowed address pair.

mac_address (Optional) plain xsd:string

The MAC address of an allowed address pair.

opt_value (Optional) plain xsd:string

The extra DHCP option value.

opt_name (Optional) plain xsd:string

The extra DHCP option name.

device_owner (Optional) plain xsd:string

The UUID of the entity that uses this port. For example, a DHCP agent.

device_id (Optional) plain csapi:UUID

The UUID of the device that uses this port. For example, a virtual server.

Response parameters
Parameter Style Type Description
port plain xsd:dict

A port object.

status plain xsd:string

The port status. Value is ACTIVE or DOWN.

name plain xsd:string

The port name.

allowed_address_pairs plain xsd:list

A set of zero or more allowed address pairs. An address pair consists of an IP address and MAC address.

ip_address plain xsd:string

The IP address.

mac_address plain xsd:string

The MAC address.

created_at plain xsd:dateTime

Time at which port has been created.

updated_at plain xsd:dateTime

Time at which port has been updated.

admin_state_up plain xsd:boolean

The administrative state of the port, which is up (true) or down (false).

network_id plain csapi:UUID

The UUID of the attached network.

tenant_id plain csapi:UUID

The UUID of the tenant who owns the network. Only administrative users can specify a tenant UUID other than their own.

extra_dhcp_opts plain xsd:list

A set of zero or more extra DHCP option pairs. An option pair consists of an option value and name.

opt_value plain xsd:string

The extra DHCP option value.

opt_name plain xsd:string

The extra DHCP option name.

device_owner plain xsd:string

The UUID of the entity that uses this port. For example, a DHCP agent.

fixed_ips plain xsd:list

The IP addresses for the port. Includes the IP address and UUID of the subnet.

subnet_id plain csapi:UUID

The UUID of the subnet to which the port is attached.

ip_address plain xsd:string

The fixed IP address of the port.

id plain csapi:UUID

The UUID of the port.

security_groups plain xsd:list

The UUIDs of any attached security groups.

device_id plain csapi:UUID

The UUID of the device that uses this port. For example, a virtual server.

port_security_enabled plain xsd:boolean

The port security status. The status is enabled (true) or disabled (false).

{
    "port": {
        "name": "test-for-port-update",
        "admin_state_up": true,
        "device_owner": "compute:nova",
        "binding:host_id": "test_for_port_update_host"
    }
}
{
    "port": {
        "status": "DOWN",
        "binding:host_id": "test_for_port_update_host",
        "allowed_address_pairs": [],
        "extra_dhcp_opts": [],
        "device_owner": "compute:nova",
        "binding:profile": {},
        "fixed_ips": [
            {
                "subnet_id": "898dec4a-74df-4193-985f-c76721bcc746",
                "ip_address": "20.20.0.4"
            }
        ],
        "id": "43c831e0-19ce-4a76-9a49-57b57e69428b",
        "security_groups": [
            "ce0179d6-8a94-4f7c-91c2-f3038e2acbd0"
        ],
        "device_id": "",
        "name": "test-for-port-update",
        "admin_state_up": true,
        "network_id": "883fc383-5ea1-4c8b-8916-e1ddb0a9f365",
        "tenant_id": "522eda8d23124b25bf03fe44f1986b74",
        "binding:vif_details": {},
        "binding:vnic_type": "normal",
        "binding:vif_type": "binding_failed",
        "mac_address": "fa:16:3e:11:11:5e"
    }
}
DELETE
/v2.0/ports/​{port_id}​
Delete port

Deletes a 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 parameters
Parameter Style Type Description
port_id URI csapi:UUID

The UUID of the port.

This operation does not accept a request body and does not return a response body.

Service providers

Lists service providers.

GET
/v2.0/service-providers
List service providers

Lists service providers and their associated service types.

 
Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), itemNotFound (404), conflict (409)
Response parameters
Parameter Style Type Description
service_providers plain xsd:list

A list of service_provider objects.

service_type plain xsd:string

The service type, which is CORE, DUMMY, FIREWALL, FLAVORS, L3_ROUTER_NAT, LOADBALANCER, LOADBALANCERV2, METERING, QOS, or VPN.

default plain xsd:boolean

Defines whether the provider is the default for the service type. If this value is true, the provider is the default. If this value is false, the provider is not the default.

name plain xsd:string

User-facing provider name.

{
    "service_providers": [
        {
            "service_type": "LOADBALANCER",
            "default": true,
            "name": "haproxy"
        }
    ]
}

This operation does not accept a request body.