# router

A router is a logical component that forwards data packets between networks. It also provides Layer 3 and NAT forwarding to provide external network access for servers on project networks.

Network v2

## router add gateway

Add router gateway

    openstack router add gateway
        [--fixed-ip subnet=<subnet>,ip-address=<ip-address>]
        <router>
        <network>

--fixed-ip subnet=<subnet>,ip-address=<ip-address>

  Desired IP and/or subnet (name or ID) on external gateway: subnet=<subnet>,ip-address=<ip-address> (repeat option to set multiple fixed IP addresses)

router

  Router to modify (name or ID)

network

  External Network to a attach a router gateway to (name or ID)

## router add port

Add a port to a router

    openstack router add port <router> <port>

router

  Router to which port will be added (name or ID)

port

  Port to be added (name or ID)

## router add route

Add extra static routes to a router’s routing table.

    openstack router add route
        [--route destination=<subnet>,gateway=<ip-address>]
        <router>

--route destination=<subnet>,gateway=<ip-address>

  Add extra static route to the router. destination: destination subnet (in CIDR notation), gateway: nexthop IP address. Repeat option to add multiple routes. Trying to add a route that is already present (exactly, including destination and nexthop) in the routing table is allowed and is considered a successful operation.

router

  Router to which extra static routes will be added (name or ID)

## router add subnet

Add a subnet to a router

    openstack router add subnet <router> <subnet>

router

  Router to which subnet will be added (name or ID)

subnet

  Subnet to be added (name or ID)

## router create

Create a new router

    openstack router create
        [--extra-property type=<property_type>,name=<property_name>,value=<property_value>]
        [--enable | --disable]
        [--distributed
        |
        --centralized
        ]
        [--ha | --no-ha]
        [--description <description>]
        [--project <project>]
        [--project-domain <project-domain>]
        [--availability-zone-hint <availability-zone>]
        [--tag <tag> | --no-tag]
        [--external-gateway <network>]
        [--fixed-ip subnet=<subnet>,ip-address=<ip-address>]
        [--enable-snat | --disable-snat]
        [--enable-ndp-proxy | --disable-ndp-proxy]
        [--flavor <flavor-id>]
        [--enable-default-route-bfd]
        [--disable-default-route-bfd]
        [--enable-default-route-ecmp]
        [--disable-default-route-ecmp]
        [--qos-policy <qos-policy>]
        <name>

--extra-property type=<property_type>,name=<property_name>,value=<property_value>

  Additional parameters can be passed using this property. Default type of the extra property is string (‘str’), but other types can be used as well. Available types are: ‘dict’, ‘list’, ‘str’, ‘bool’, ‘int’. In case of ‘list’ type, ‘value’ can be semicolon-separated list of values. For ‘dict’ value is semicolon-separated list of the key:value pairs.

--enable

  Enable router (default)

--disable

  Disable router

--distributed

  Create a distributed router

--centralized

  Create a centralized router

--ha

  Create a highly available router

--no-ha

  Create a legacy router

--description <description>

  Set router description

--project <project>

  Owner’s project (name or ID)

--project-domain <project-domain>

  Domain the project belongs to (name or ID). This can be used in case collisions between project names exist.

--availability-zone-hint <availability-zone>

  Availability Zone in which to create this router (Router Availability Zone extension required, repeat option to set multiple availability zones)

--tag <tag>

  Tag to be added to the router (repeat option to set multiple tags)

--no-tag

  No tags associated with the router

--external-gateway <network>

  External Network used as router’s gateway (name or ID) (repeat option to set multiple gateways per router if the L3 service plugin in use supports it)

--fixed-ip subnet=<subnet>,ip-address=<ip-address>

  Desired IP and/or subnet (name or ID) on external gateway: subnet=<subnet>,ip-address=<ip-address> (repeat option to set multiple fixed IP addresses)

--enable-snat

  Enable Source NAT on external gateway

--disable-snat

  Disable Source NAT on external gateway

--enable-ndp-proxy

  Enable IPv6 NDP proxy on external gateway

--disable-ndp-proxy

  Disable IPv6 NDP proxy on external gateway

--flavor <flavor-id>

  Associate the router to a flavor (by name or ID

--enable-default-route-bfd

  Enable BFD sessions for default routes inferred from the external gateway port subnets for this router

--disable-default-route-bfd

  Disable BFD sessions for default routes inferred from the external gateway port subnets for this router

--enable-default-route-ecmp

  Add ECMP default routes if multiple are available via different gateway ports

--disable-default-route-ecmp

  Add default route only for first gateway port

--qos-policy <qos-policy>

  Attach QoS policy to router gateway IPs

name

  New router name

## router delete

Delete router(s)

    openstack router delete <router> [<router> ...]

router

  Router(s) to delete (name or ID)

## router list

List routers

    openstack router list
        [--format-config-file FORMAT_CONFIG]
        [--sort-column SORT_COLUMN]
        [--sort-ascending
        |
        --sort-descending
        ]
        [--name <name>]
        [--enable
        |
        --disable
        ]
        [--long]
        [--project <project>]
        [--project-domain <project-domain>]
        [--agent <agent-id>]
        [--tags <tag>[,<tag>,...]]
        [--any-tags <tag>[,<tag>,...]]
        [--not-tags <tag>[,<tag>,...]]
        [--not-any-tags <tag>[,<tag>,...]]

--format-config-file <FORMAT_CONFIG>

  Config file for the dict-to-csv formatter

--sort-column SORT_COLUMN

  specify the column(s) to sort the data (columns specified first have a priority, non-existing columns are ignored), can be repeated

--sort-ascending

  sort the column(s) in ascending order

--sort-descending

  sort the column(s) in descending order

--name <name>

  List routers according to their name

--enable

  List enabled routers

--disable

  List disabled routers

--long

  List additional fields in output

--project <project>

  List only routers with the specified project (name or ID)

--project-domain <project-domain>

  Domain the project belongs to (name or ID). This can be used in case collisions between project names exist.

--agent <agent-id>

  List only routers hosted by the specified agent (ID only)

--tags <tag>[,<tag>,...]

  List routers which have all given tag(s) (Comma-separated list of tags)

--any-tags <tag>[,<tag>,...]

  List routers which have any given tag(s) (Comma-separated list of tags)

--not-tags <tag>[,<tag>,...]

  Exclude routers which have all given tag(s) (Comma-separated list of tags)

--not-any-tags <tag>[,<tag>,...]

  Exclude routers which have any given tag(s) (Comma-separated list of tags)

## router ndp proxy create

Create NDP proxy

    openstack router ndp proxy create
        [--name <name>]
        --port <port>
        [--ip-address <ip-address>]
        [--description <description>]
        <router>

--name <name>

  New NDP proxy name

--port <port>

  The name or ID of the network port associated to the NDP proxy

--ip-address <ip-address>

  The IPv6 address that is to be proxied. In case the port has multiple addresses assigned, use this option to select which address is to be used.

--description <description>

  Text to describe/contextualize the use of the NDP proxy configuration

router

  The name or ID of a router

## router ndp proxy delete

Delete NDP proxy

    openstack router ndp proxy delete <ndp-proxy> [<ndp-proxy> ...]

ndp-proxy

  NDP proxy(s) to delete (name or ID)

## router ndp proxy list

List NDP proxies

    openstack router ndp proxy list
        [--format-config-file FORMAT_CONFIG]
        [--sort-column SORT_COLUMN]
        [--sort-ascending | --sort-descending]
        [--router <router>]
        [--port <port>]
        [--ip-address <ip-address>]
        [--project <project>]
        [--name <name>]
        [--project-domain <project-domain>]

--format-config-file <FORMAT_CONFIG>

  Config file for the dict-to-csv formatter

--sort-column SORT_COLUMN

  specify the column(s) to sort the data (columns specified first have a priority, non-existing columns are ignored), can be repeated

--sort-ascending

  sort the column(s) in ascending order

--sort-descending

  sort the column(s) in descending order

--router <router>

  List only NDP proxies associated with the specifed router (name or ID)

--port <port>

  List only NDP proxies associated with the specified port (name or ID)

--ip-address <ip-address>

  List only NDP proxies associated with the specified IPv6 address

--project <project>

  List only NDP proxies with the specified project (name or ID)

--name <name>

  List only NDP proxies with the specified name

--project-domain <project-domain>

  Domain the project belongs to (name or ID). This can be used in case collisions between project names exist.

## router ndp proxy set

Set NDP proxy properties

    openstack router ndp proxy set
        [--name <name>]
        [--description <description>]
        <ndp-proxy>

--name <name>

  Set NDP proxy name

--description <description>

  Text to describe/contextualize the use of the NDP proxy configuration

ndp-proxy

  The ID or name of the NDP proxy to update

## router ndp proxy show

Display NDP proxy details

    openstack router ndp proxy show <ndp-proxy>

ndp-proxy

  The ID or name of the NDP proxy

## router remove gateway

Remove router gateway

    openstack router remove gateway
        [--fixed-ip subnet=<subnet>,ip-address=<ip-address>]
        <router>
        <network>

--fixed-ip subnet=<subnet>,ip-address=<ip-address>

  IP and/or subnet (name or ID) on the external gateway which is used to identify a particular gateway if multiple are attached to the same network: subnet=<subnet>,ip-address=<ip-address>

router

  Router to modify (name or ID).

network

  External Network to remove a router gateway from (name or ID)

## router remove port

Remove a port from a router

    openstack router remove port <router> <port>

router

  Router from which port will be removed (name or ID)

port

  Port to be removed and deleted (name or ID)

## router remove route

Remove extra static routes from a router’s routing table.

    openstack router remove route
        [--route destination=<subnet>,gateway=<ip-address>]
        <router>

--route destination=<subnet>,gateway=<ip-address>

  Remove extra static route from the router. destination: destination subnet (in CIDR notation), gateway: nexthop IP address. Repeat option to remove multiple routes. Trying to remove a route that is already missing (fully, including destination and nexthop) from the routing table is allowed and is considered a successful operation.

router

  Router from which extra static routes will be removed (name or ID)

## router remove subnet

Remove a subnet from a router

    openstack router remove subnet <router> <subnet>

router

  Router from which the subnet will be removed (name or ID)

subnet

  Subnet to be removed (name or ID)

## router set

Set router properties

    openstack router set
        [--extra-property type=<property_type>,name=<property_name>,value=<property_value>]
        [--name <name>]
        [--description <description>]
        [--enable | --disable]
        [--distributed
        |
        --centralized
        ]
        [--route destination=<subnet>,gateway=<ip-address>]
        [--no-route]
        [--ha | --no-ha]
        [--external-gateway <network>]
        [--fixed-ip subnet=<subnet>,ip-address=<ip-address>]
        [--enable-snat | --disable-snat]
        [--enable-ndp-proxy | --disable-ndp-proxy]
        [--qos-policy <qos-policy> | --no-qos-policy]
        [--tag <tag>]
        [--no-tag]
        [--enable-default-route-bfd]
        [--disable-default-route-bfd]
        [--enable-default-route-ecmp]
        [--disable-default-route-ecmp]
        <router>

--extra-property type=<property_type>,name=<property_name>,value=<property_value>

  Additional parameters can be passed using this property. Default type of the extra property is string (‘str’), but other types can be used as well. Available types are: ‘dict’, ‘list’, ‘str’, ‘bool’, ‘int’. In case of ‘list’ type, ‘value’ can be semicolon-separated list of values. For ‘dict’ value is semicolon-separated list of the key:value pairs.

--name <name>

  Set router name

--description <description>

  Set router description

--enable

  Enable router

--disable

  Disable router

--distributed

  Set router to distributed mode (disabled router only)

--centralized

  Set router to centralized mode (disabled router only)

--route destination=<subnet>,gateway=<ip-address>

  Add routes to the router. destination: destination subnet (in CIDR notation) gateway: nexthop IP address (repeat option to add multiple routes). This is deprecated in favor of ‘router add/remove route’ since it is prone to race conditions between concurrent clients when not used together with –no-route to overwrite the current value of ‘routes’.

--no-route

  Clear routes associated with the router. Specify both –route and –no-route to overwrite current value of routes.

--ha

  Set the router as highly available (disabled router only)

--no-ha

  Clear high availability attribute of the router (disabled router only)

--external-gateway <network>

  External Network used as router’s gateway (name or ID) (repeat option to set multiple gateways per router if the L3 service plugin in use supports it).

--fixed-ip subnet=<subnet>,ip-address=<ip-address>

  Desired IP and/or subnet (name or ID) on external gateway: subnet=<subnet>,ip-address=<ip-address> (repeat option to set multiple fixed IP addresses)

--enable-snat

  Enable Source NAT on external gateway

--disable-snat

  Disable Source NAT on external gateway

--enable-ndp-proxy

  Enable IPv6 NDP proxy on external gateway

--disable-ndp-proxy

  Disable IPv6 NDP proxy on external gateway

--qos-policy <qos-policy>

  Attach QoS policy to router gateway IPs

--no-qos-policy

  Remove QoS policy from router gateway IPs

--tag <tag>

  Tag to be added to the router (repeat option to set multiple tags)

--no-tag

  Clear tags associated with the router. Specify both –tag and –no-tag to overwrite current tags

--enable-default-route-bfd

  Enable BFD sessions for default routes inferred from the external gateway port subnets for this router

--disable-default-route-bfd

  Disable BFD sessions for default routes inferred from the external gateway port subnets for this router

--enable-default-route-ecmp

  Add ECMP default routes if multiple are available via different gateway ports

--disable-default-route-ecmp

  Add default route only for first gateway port

router

  Router to modify (name or ID)

## router show

Display router details

    openstack router show <router>

router

  Router to display (name or ID)

## router unset

Unset router properties

    openstack router unset
        [--extra-property type=<property_type>,name=<property_name>,value=<property_value>]
        [--route destination=<subnet>,gateway=<ip-address>]
        [--external-gateway]
        [--qos-policy]
        [--tag <tag> | --all-tag]
        <router>

--extra-property type=<property_type>,name=<property_name>,value=<property_value>

  Additional parameters can be passed using this property. Default type of the extra property is string (‘str’), but other types can be used as well. Available types are: ‘dict’, ‘list’, ‘str’, ‘bool’, ‘int’. In case of ‘list’ type, ‘value’ can be semicolon-separated list of values. For ‘dict’ value is semicolon-separated list of the key:value pairs.

--route destination=<subnet>,gateway=<ip-address>

  Routes to be removed from the router. destination: destination subnet (in CIDR notation) gateway: nexthop IP address (repeat option to unset multiple routes)

--external-gateway

  Remove external gateway information from the router

--qos-policy

  Remove QoS policy from router gateway IPs

--tag <tag>

  Tag to be removed from the router (repeat option to remove multiple tags)

--all-tag

  Clear all tags associated with the router

router

  Router to modify (name or ID)

this page last updated: 2026-04-01 09:44:20

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.