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