1.. 2 Licensed under the Apache License, Version 2.0 (the "License"); you may 3 not use this file except in compliance with the License. You may obtain 4 a copy of the License at 5 6 http://www.apache.org/licenses/LICENSE-2.0 7 8 Unless required by applicable law or agreed to in writing, software 9 distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 10 WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 11 License for the specific language governing permissions and limitations 12 under the License. 13 14 15 Convention for heading levels in Neutron devref: 16 ======= Heading 0 (reserved for the title in a document) 17 ------- Heading 1 18 ~~~~~~~ Heading 2 19 +++++++ Heading 3 20 ''''''' Heading 4 21 (Avoid deeper levels because they do not render well.) 22 23Using neutron CLI 24================= 25 26The **neutron** shell utility interacts with OpenStack Networking API from the 27command-line. It supports the entire features of OpenStack Networking API. 28 29.. warning:: 30 31 neutron CLI is now deprecated and will be removed in the future. 32 Use openstack CLI instead. See `openstack CLI command list 33 <https://docs.openstack.org/python-openstackclient/latest/cli/command-list.html>`__ 34 and :doc:`its extensions for advanced networking services <osc_plugins>`. 35 The command mapping from neutron CLI to openstack CLI is available 36 `here <https://docs.openstack.org/python-openstackclient/latest/cli/decoder.html#neutron-cli>`__. 37 38Basic Usage 39----------- 40 41In order to use the CLI, you must provide your OpenStack username, password, 42project, domain information for both user and project, and auth endpoint. Use 43the corresponding configuration options (``--os-username``, ``--os-password``, 44``--os-project-name``, ``--os-user-domain-id``, ``os-project-domain-id``, and 45``--os-auth-url``), but it is easier to set them in environment variables. 46 47.. code-block:: shell 48 49 export OS_USERNAME=user 50 export OS_PASSWORD=pass 51 export OS_PROJECT_NAME=project 52 export OS_USER_DOMAIN_ID=default 53 export OS_PROJECT_DOMAIN_ID=default 54 export OS_AUTH_URL=http://auth.example.com:5000/v3 55 56If you are using Identity v2.0 API (DEPRECATED), you don't need to pass domain 57information. 58 59.. code-block:: shell 60 61 export OS_USERNAME=user 62 export OS_PASSWORD=pass 63 export OS_TENANT_NAME=tenant 64 export OS_AUTH_URL=http://auth.example.com:5000/v2.0 65 66Once you've configured your authentication parameters, you can run **neutron** 67commands. All commands take the form of: 68 69.. code-block:: none 70 71 neutron <command> [arguments...] 72 73Run **neutron help** to get a full list of all possible commands, and run 74**neutron help <command>** to get detailed help for that command. 75 76Using with os-client-config 77~~~~~~~~~~~~~~~~~~~~~~~~~~~ 78 79`os-client-config <https://docs.openstack.org/os-client-config/latest/>`_ 80provides more convenient way to manage a collection of client configurations 81and you can easily switch multiple OpenStack-based configurations. 82 83To use os-client-config, you first need to prepare 84``~/.config/openstack/clouds.yaml`` like the following. 85 86.. code-block:: yaml 87 88 clouds: 89 devstack: 90 auth: 91 auth_url: http://auth.example.com:5000 92 password: your-secret 93 project_domain_id: default 94 project_name: demo 95 user_domain_id: default 96 username: demo 97 identity_api_version: '3' 98 region_name: RegionOne 99 devstack-admin: 100 auth: 101 auth_url: http://auth.example.com:35357 102 password: another-secret 103 project_domain_id: default 104 project_name: admin 105 user_domain_id: default 106 username: admin 107 identity_api_version: '3' 108 region_name: RegionOne 109 110Then, you need to specify a configuration name defined in the above clouds.yaml. 111 112.. code-block:: shell 113 114 export OS_CLOUD=devstack 115 116For more detail information, see the 117`os-client-config <https://docs.openstack.org/os-client-config/latest/>`_ 118documentation. 119 120Using with keystone token 121~~~~~~~~~~~~~~~~~~~~~~~~~ 122 123The command-line tool will attempt to re-authenticate using your provided 124credentials for every request. You can override this behavior by manually 125supplying an auth token using ``--os-url`` and ``--os-auth-token``. You can 126alternatively set these environment variables. 127 128.. code-block:: shell 129 130 export OS_URL=http://neutron.example.org:9696/ 131 export OS_TOKEN=3bcc3d3a03f44e3d8377f9247b0ad155 132 133Using noauth mode 134~~~~~~~~~~~~~~~~~ 135 136If neutron server does not require authentication, besides these two arguments 137or environment variables (We can use any value as token.), we need manually 138supply ``--os-auth-strategy`` or set the environment variable. 139 140.. code-block:: shell 141 142 export OS_AUTH_STRATEGY=noauth 143 144Display options 145--------------- 146 147Filtering 148~~~~~~~~~ 149 150Neutron API supports filtering in the listing operation. 151**neutron** CLI supports this feature too. 152 153To specify a filter in ``*-list`` command, you need to pass a pair of an 154attribute name and an expected value with the format of ``--<attribute> <value>``. 155The example below retrieves ports owned by compute instances. 156 157.. code-block:: console 158 159 $ neutron port-list --device_owner network:dhcp 160 +--------------------------------------+------+-------------------+-------------------------------------------------------------------------------------------------------------+ 161 | id | name | mac_address | fixed_ips | 162 +--------------------------------------+------+-------------------+-------------------------------------------------------------------------------------------------------------+ 163 | 8953d683-29ad-4be3-b73f-060727c7849b | | fa:16:3e:4b:9e:0a | {"subnet_id": "6b832dfe-f271-443c-abad-629961414a73", "ip_address": "10.0.0.2"} | 164 | | | | {"subnet_id": "cdcc616b-0cff-482f-96f5-06fc63d21247", "ip_address": "fd12:877c:1d66:0:f816:3eff:fe4b:9e0a"} | 165 +--------------------------------------+------+-------------------+-------------------------------------------------------------------------------------------------------------+ 166 167You can also specify multiple filters. 168The example below retrieves security group rules applied to IPv4 traffic 169which belongs to a security group bfa493f9-2b03-46d2-8399-b9b038a53bc1. 170 171.. code-block:: console 172 173 $ neutron security-group-rule-list --security-group-id bfa493f9-2b03-46d2-8399-b9b038a53bc1 --ethertype IPv4 174 +--------------------------------------+----------------+-----------+-----------+---------------+-----------------+ 175 | id | security_group | direction | ethertype | protocol/port | remote | 176 +--------------------------------------+----------------+-----------+-----------+---------------+-----------------+ 177 | 65489805-0400-4bce-9bd9-16a81952263c | default | egress | IPv4 | any | any | 178 | 9429f336-4947-4643-bbd9-24528cc65648 | default | ingress | IPv4 | any | default (group) | 179 +--------------------------------------+----------------+-----------+-----------+---------------+-----------------+ 180 181.. note:: 182 183 Looking up UUID from name is not supported when specifying a filter. 184 You need to use UUID to specify a specific resource. 185 186.. note:: 187 188 Filtering for dictionary or list attributes is not supported. 189 190Changing displayed columns 191~~~~~~~~~~~~~~~~~~~~~~~~~~ 192 193If you want displayed columns in a list operation, ``-c`` option can be used. 194``-c`` can be specified multiple times and the column order will be same as 195the order of ``-c`` options. 196 197.. code-block:: console 198 199 $ neutron port-list -c id -c device_owner -c fixed_ips 200 +--------------------------------------+--------------------------+-------------------------------------------------------------------------------------------------------------+ 201 | id | device_owner | fixed_ips | 202 +--------------------------------------+--------------------------+-------------------------------------------------------------------------------------------------------------+ 203 | 41ca1b9b-4bbd-4aa8-bcaa-31d3d5704205 | network:router_interface | {"subnet_id": "6b832dfe-f271-443c-abad-629961414a73", "ip_address": "10.0.0.1"} | 204 | 8953d683-29ad-4be3-b73f-060727c7849b | network:dhcp | {"subnet_id": "6b832dfe-f271-443c-abad-629961414a73", "ip_address": "10.0.0.2"} | 205 | | | {"subnet_id": "cdcc616b-0cff-482f-96f5-06fc63d21247", "ip_address": "fd12:877c:1d66:0:f816:3eff:fe4b:9e0a"} | 206 | a9da29f8-4504-4526-a5ce-cd3624fbd173 | neutron:LOADBALANCER | {"subnet_id": "6b832dfe-f271-443c-abad-629961414a73", "ip_address": "10.0.0.3"} | 207 | | | {"subnet_id": "cdcc616b-0cff-482f-96f5-06fc63d21247", "ip_address": "fd12:877c:1d66:0:f816:3eff:feb1:ab71"} | 208 | d6a1ff96-0a99-416f-a4d6-65d9614cf64e | compute:nova | {"subnet_id": "6b832dfe-f271-443c-abad-629961414a73", "ip_address": "10.0.0.4"} | 209 | | | {"subnet_id": "cdcc616b-0cff-482f-96f5-06fc63d21247", "ip_address": "fd12:877c:1d66:0:f816:3eff:fe2c:348e"} | 210 | f4789225-26d0-409f-8047-82d2c7a87a95 | network:router_interface | {"subnet_id": "cdcc616b-0cff-482f-96f5-06fc63d21247", "ip_address": "fd12:877c:1d66::1"} | 211 +--------------------------------------+--------------------------+-------------------------------------------------------------------------------------------------------------+ 212 213.. _cli_extra_arguments: 214 215Extra arguments for create/update operation 216------------------------------------------- 217 218**neutron** CLI has a mechanism called the *extra arguments* for ``*-create`` 219and ``*-update`` commands. It allows users to specify a set of *unknown 220options* which are not defined as options and not shown in the help text. 221**Unknown options MUST be placed at the end of the command line.** 222*unknown options* will be directly passed to the API layer. By this mechanism, 223you can pass an attribute which is not defined in the upstream **neutron** 224CLI. For example, when you are developing a new feature which add a new 225attribute to an existing resource, it is useful because we can test your 226feature without changing the existing neutron CLI. 227 228For example, if you run the following command:: 229 230 neutron resource-update <ID> --key1 value1 --key2 value2 231 232where ``resource`` is some resource name and ``--key1`` and ``--key2`` are 233unknown options, then the following JSON will be sent to the neutron API:: 234 235 PUT /v2.0/resources/<ID> 236 237 { 238 "resource": { 239 "key2": "value2", 240 "key1": "value1" 241 } 242 } 243 244Key interpretation 245~~~~~~~~~~~~~~~~~~ 246 247This means an option name (``--key1`` in this case) must be one of valid 248resources of a corresponding resource. An option name ``--foo_bar`` is 249recognized as an attribute name ``foo_bar``. ``--foo-bar`` is also interpreted 250as an attribute name ``foo_bar``. 251 252Value interpretation 253~~~~~~~~~~~~~~~~~~~~ 254 255By default, if the number of values is 1, the option value is interpreted as a 256string and is passed to the API layer as specified in a command-line. 257 258If the number of values is greater than 1, the option value is interpreted as a 259list and the result in the API layer will be same as when specifying a list as 260described below. 261 262 neutron resource-update <ID> --key1 val1 val2 val3 --key2 val4 263 264In the above example, a value of ``key1`` is interpreted as 265``["val1", "val2", "val3"]`` and a value of ``key2`` is interpreted 266as ``val4``. 267 268The extra argument mechanism supports more complex value like a list or a dict. 269 270Specify a list value 271++++++++++++++++++++ 272 273A command-line:: 274 275 neutron resource-update <ID> --key list=true val1 val2 val3 276 277will send the following in the API layer:: 278 279 { 280 "key": [ 281 "val1", 282 "val2", 283 "val3" 284 ] 285 } 286 287.. note:: 288 289 If you want to specify a list value, it is recommended to specify 290 ``list=true``. When ``list=true`` is specified, specified values are 291 interpreted as a list even regardless of the number of values. 292 293 If ``list=true`` is not specified, specified values are interpreted 294 depends on the number of values how. If the number of values is more than 2, 295 the specified values are interpreted as a list. If 1, the value 296 is interpreted as a string. 297 298Specify a dict value 299++++++++++++++++++++ 300 301A command-line:: 302 303 neutron resource-update <ID> --key type=dict key1=val1,key2=val2,key3=val3 304 305will send the following in the API layer:: 306 307 { 308 "key": { 309 "key1": "val1", 310 "key2": "val2", 311 "key3": "val3" 312 } 313 } 314 315.. note:: 316 317 ``type=bool True/False`` and ``type=int 10`` are also supported. 318 319Specify a list of dicts 320+++++++++++++++++++++++ 321 322A command-line:: 323 324 neutron resource-update <ID> --key type=dict list=true key1=val1 key2=val2 key3=val3 325 326will send the following in the API layer:: 327 328 { 329 "key": [ 330 {"key1": "val1"}, 331 {"key2": "val2"}, 332 {"key3": "val3"} 333 ] 334 } 335 336Passing None as a value 337~~~~~~~~~~~~~~~~~~~~~~~ 338 339There is a case where we would like to pass ``None`` (``null`` in JSON) 340in the API layer. To do this:: 341 342 neutron resource-update <ID> --key action=clear 343 344The following body will be in the API layer:: 345 346 {"key": null} 347 348.. note:: 349 350 If ``action=clear`` is specified, ``list=true`` or ``type=dict`` is ignored. 351 It means when ``action=clear`` is specified ``None`` is always sent. 352 353Debugging 354--------- 355 356Display API-level communication 357~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 358 359``-v`` (or ``--verbose``, ``--debug``) option displays a detail interaction 360with your neutron server. It is useful to debug what happens in the API level. 361 362Here is an sample output of ``net-show`` command. 363 364The first line show what parameters are recognized by neutronclient. 365It is sometimes useful to check if command-line parameters you specify are recognized properly. 366 367.. code-block:: console 368 369 $ neutron -v net-show mynetwork 370 DEBUG: neutronclient.neutron.v2_0.network.ShowNetwork get_data(Namespace(columns=[], fields=[], formatter='table', id=u'mynetwork', max_width=0, noindent=False, prefix='', request_format='json', show_details=False, variables=[])) 371 372Next, neutronclient sends an authentication request to keystone to get a token 373which is used in further operations. 374 375.. code-block:: console 376 377 DEBUG: keystoneauth.session REQ: curl -g -i -X GET http://172.16.18.47:5000 -H "Accept: application/json" -H "User-Agent: keystoneauth1" 378 DEBUG: keystoneauth.session RESP: [300] Content-Length: 593 Vary: X-Auth-Token Keep-Alive: timeout=5, max=100 Server: Apache/2.4.7 (Ubuntu) Connection: Keep-Alive Date: Fri, 27 Nov 2015 20:10:54 GMT Content-Type: application/json 379 RESP BODY: {"versions": {"values": [{"status": "stable", "updated": "2015-03-30T00:00:00Z", "media-types": [{"base": "application/json", "type": "application/vnd.openstack.identity-v3+json"}], "id": "v3.4", "links": [{"href": "http://172.16.18.47:5000/v3/", "rel": "self"}]}, {"status": "stable", "updated": "2014-04-17T00:00:00Z", "media-types": [{"base": "application/json", "type": "application/vnd.openstack.identity-v2.0+json"}], "id": "v2.0", "links": [{"href": "http://172.16.18.47:5000/v2.0/", "rel": "self"}, {"href": "http://docs.openstack.org/", "type": "text/html", "rel": "describedby"}]}]}} 380 381 DEBUG: keystoneauth.identity.v3.base Making authentication request to http://172.16.18.47:5000/v3/auth/tokens 382 383Neutronclient looks up a network ID corresponding to a given network name. 384 385.. code-block:: console 386 387 DEBUG: keystoneauth.session REQ: curl -g -i -X GET http://172.16.18.47:9696/v2.0/networks.json?fields=id&name=mynetwork -H "User-Agent: python-neutronclient" -H "Accept: application/json" -H "X-Auth-Token: {SHA1}39300e7398d53a02afd183f13cb6afaef95ec4e5" 388 DEBUG: keystoneauth.session RESP: [200] Date: Fri, 27 Nov 2015 20:10:55 GMT Connection: keep-alive Content-Type: application/json; charset=UTF-8 Content-Length: 62 X-Openstack-Request-Id: req-ccebf6e4-4f52-4874-a1ab-5499abcba378 389 RESP BODY: {"networks": [{"id": "3698d3c7-d581-443e-bf86-53c4e3a738f7"}]} 390 391Finally, neutronclient retrieves a detail of a given network using the resolved ID. 392 393.. code-block:: console 394 395 DEBUG: keystoneauth.session REQ: curl -g -i -X GET http://172.16.18.47:9696/v2.0/networks/3698d3c7-d581-443e-bf86-53c4e3a738f7.json -H "User-Agent: python-neutronclient" -H "Accept: application/json" -H "X-Auth-Token: {SHA1}39300e7398d53a02afd183f13cb6afaef95ec4e5" 396 DEBUG: keystoneauth.session RESP: [200] Date: Fri, 27 Nov 2015 20:10:55 GMT Connection: keep-alive Content-Type: application/json; charset=UTF-8 Content-Length: 272 X-Openstack-Request-Id: req-261add00-d6d3-4ea7-becc-105b60ac7369 397 RESP BODY: {"network": {"status": "ACTIVE", "subnets": [], "name": "mynetwork", "admin_state_up": true, "tenant_id": "8f0ebf767043483a987736c8c684178d", "mtu": 0, "router:external": false, "shared": false, "port_security_enabled": true, "id": "3698d3c7-d581-443e-bf86-53c4e3a738f7"}} 398 399 +-----------------------+--------------------------------------+ 400 | Field | Value | 401 +-----------------------+--------------------------------------+ 402 | admin_state_up | True | 403 | id | 3698d3c7-d581-443e-bf86-53c4e3a738f7 | 404 | mtu | 0 | 405 | name | mynetwork | 406 | port_security_enabled | True | 407 | router:external | False | 408 | shared | False | 409 | status | ACTIVE | 410 | subnets | | 411 | tenant_id | 8f0ebf767043483a987736c8c684178d | 412 +-----------------------+--------------------------------------+ 413