.. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. Convention for heading levels in Neutron devref: ======= Heading 0 (reserved for the title in a document) ------- Heading 1 ~~~~~~~ Heading 2 +++++++ Heading 3 ''''''' Heading 4 (Avoid deeper levels because they do not render well.) Command-line Interface ====================== The **neutron** shell utility interacts with OpenStack Networking API from the command-line. It supports the entire features of OpenStack Networking API. Basic Usage ----------- In order to use the CLI, you must provide your OpenStack username, password, project, domain information for both user and project, and auth endpoint. Use the corresponding configuration options (``--os-username``, ``--os-password``, ``--os-project-name``, ``--os-user-domain-id``, ``os-project-domain-id``, and ``--os-auth-url``), but it is easier to set them in environment variables. .. code-block:: shell export OS_USERNAME=user export OS_PASSWORD=pass export OS_PROJECT_NAME=project export OS_USER_DOMAIN_ID=default export OS_PROJECT_DOMAIN_ID=default export OS_AUTH_URL=http://auth.example.com:5000/v3 If you are using Identity v2.0 API (DEPRECATED), you don't need to pass domain information. .. code-block:: shell export OS_USERNAME=user export OS_PASSWORD=pass export OS_TENANT_NAME=tenant export OS_AUTH_URL=http://auth.example.com:5000/v2.0 Once you've configured your authentication parameters, you can run **neutron** commands. All commands take the form of: .. code-block:: none neutron [arguments...] Run **neutron help** to get a full list of all possible commands, and run **neutron help ** to get detailed help for that command. Using with os-client-config ~~~~~~~~~~~~~~~~~~~~~~~~~~~ `os-client-config `_ provides more convenient way to manage a collection of client configurations and you can easily switch multiple OpenStack-based configurations. To use os-client-config, you first need to prepare ``~/.config/openstack/clouds.yaml`` like the following. .. code-block:: yaml clouds: devstack: auth: auth_url: http://auth.example.com:5000 password: your-secret project_domain_id: default project_name: demo user_domain_id: default username: demo identity_api_version: '3' region_name: RegionOne devstack-admin: auth: auth_url: http://auth.example.com:35357 password: another-secret project_domain_id: default project_name: admin user_domain_id: default username: admin identity_api_version: '3' region_name: RegionOne Then, you need to specify a configuration name defined in the above clouds.yaml. .. code-block:: shell export OS_CLOUD=devstack For more detail information, see the `os-client-config `_ documentation. Using with keystone token ~~~~~~~~~~~~~~~~~~~~~~~~~ The command-line tool will attempt to re-authenticate using your provided credentials for every request. You can override this behavior by manually supplying an auth token using ``--os-url`` and ``--os-auth-token``. You can alternatively set these environment variables. .. code-block:: shell export OS_URL=http://neutron.example.org:9696/ export OS_TOKEN=3bcc3d3a03f44e3d8377f9247b0ad155 Using noauth mode ~~~~~~~~~~~~~~~~~ If neutron server does not require authentication, besides these two arguments or environment variables (We can use any value as token.), we need manually supply ``--os-auth-strategy`` or set the environment variable. .. code-block:: shell export OS_AUTH_STRATEGY=noauth Display options --------------- Filtering ~~~~~~~~~ Neutron API supports filtering in the listing operation. **neutron** CLI supports this feature too. To specify a filter in ``*-list`` command, you need to pass a pair of an attribute name and an expected value with the format of ``-- ``. The example below retrieves ports owned by compute instances. .. code-block:: console $ neutron port-list --device_owner network:dhcp +--------------------------------------+------+-------------------+-------------------------------------------------------------------------------------------------------------+ | id | name | mac_address | fixed_ips | +--------------------------------------+------+-------------------+-------------------------------------------------------------------------------------------------------------+ | 8953d683-29ad-4be3-b73f-060727c7849b | | fa:16:3e:4b:9e:0a | {"subnet_id": "6b832dfe-f271-443c-abad-629961414a73", "ip_address": "10.0.0.2"} | | | | | {"subnet_id": "cdcc616b-0cff-482f-96f5-06fc63d21247", "ip_address": "fd12:877c:1d66:0:f816:3eff:fe4b:9e0a"} | +--------------------------------------+------+-------------------+-------------------------------------------------------------------------------------------------------------+ You can also specify multiple filters. The example below retrieves security group rules applied to IPv4 traffic which belongs to a security group bfa493f9-2b03-46d2-8399-b9b038a53bc1. .. code-block:: console $ neutron security-group-rule-list --security-group-id bfa493f9-2b03-46d2-8399-b9b038a53bc1 --ethertype IPv4 +--------------------------------------+----------------+-----------+-----------+---------------+-----------------+ | id | security_group | direction | ethertype | protocol/port | remote | +--------------------------------------+----------------+-----------+-----------+---------------+-----------------+ | 65489805-0400-4bce-9bd9-16a81952263c | default | egress | IPv4 | any | any | | 9429f336-4947-4643-bbd9-24528cc65648 | default | ingress | IPv4 | any | default (group) | +--------------------------------------+----------------+-----------+-----------+---------------+-----------------+ .. note:: Looking up UUID from name is not supported when specifying a filter. You need to use UUID to specify a specific resource. .. note:: Filtering for dictionary or list attributes is not supported. Changing displayed columns ~~~~~~~~~~~~~~~~~~~~~~~~~~ If you want displayed columns in a list operation, ``-c`` option can be used. ``-c`` can be specified multiple times and the column order will be same as the order of ``-c`` options. .. code-block:: console $ neutron port-list -c id -c device_owner -c fixed_ips +--------------------------------------+--------------------------+-------------------------------------------------------------------------------------------------------------+ | id | device_owner | fixed_ips | +--------------------------------------+--------------------------+-------------------------------------------------------------------------------------------------------------+ | 41ca1b9b-4bbd-4aa8-bcaa-31d3d5704205 | network:router_interface | {"subnet_id": "6b832dfe-f271-443c-abad-629961414a73", "ip_address": "10.0.0.1"} | | 8953d683-29ad-4be3-b73f-060727c7849b | network:dhcp | {"subnet_id": "6b832dfe-f271-443c-abad-629961414a73", "ip_address": "10.0.0.2"} | | | | {"subnet_id": "cdcc616b-0cff-482f-96f5-06fc63d21247", "ip_address": "fd12:877c:1d66:0:f816:3eff:fe4b:9e0a"} | | a9da29f8-4504-4526-a5ce-cd3624fbd173 | neutron:LOADBALANCER | {"subnet_id": "6b832dfe-f271-443c-abad-629961414a73", "ip_address": "10.0.0.3"} | | | | {"subnet_id": "cdcc616b-0cff-482f-96f5-06fc63d21247", "ip_address": "fd12:877c:1d66:0:f816:3eff:feb1:ab71"} | | d6a1ff96-0a99-416f-a4d6-65d9614cf64e | compute:nova | {"subnet_id": "6b832dfe-f271-443c-abad-629961414a73", "ip_address": "10.0.0.4"} | | | | {"subnet_id": "cdcc616b-0cff-482f-96f5-06fc63d21247", "ip_address": "fd12:877c:1d66:0:f816:3eff:fe2c:348e"} | | f4789225-26d0-409f-8047-82d2c7a87a95 | network:router_interface | {"subnet_id": "cdcc616b-0cff-482f-96f5-06fc63d21247", "ip_address": "fd12:877c:1d66::1"} | +--------------------------------------+--------------------------+-------------------------------------------------------------------------------------------------------------+ .. _cli_extra_arguments: Extra arguments for create/update operation ------------------------------------------- **neutron** CLI has a mechanism called the *extra arguments* for ``*-create`` and ``*-update`` commands. It allows users to specify a set of *unknown options* which are not defined as options and not shown in the help text. **Unknown options MUST be placed at the end of the command line.** *unknown options* will be directly passed to the API layer. By this mechanism, you can pass an attribute which is not defined in the upstream **neutron** CLI. For example, when you are developing a new feature which add a new attribute to an existing resource, it is useful because we can test your feature without changing the existing neutron CLI. For example, if you run the following command:: neutron resource-update --key1 value1 --key2 value2 where ``resource`` is some resource name and ``--key1`` and ``--key2`` are unknown options, then the following JSON will be sent to the neutron API:: PUT /v2.0/resources/ { "resource": { "key2": "value2", "key1": "value1" } } Key interpretation ~~~~~~~~~~~~~~~~~~ This means an option name (``--key1`` in this case) must be one of valid resources of a corresponding resource. An option name ``--foo_bar`` is recognized as an attribute name ``foo_bar``. ``--foo-bar`` is also interpreted as an attribute name ``foo_bar``. Value interpretation ~~~~~~~~~~~~~~~~~~~~ By default, if the number of values is 1, the option value is interpreted as a string and is passed to the API layer as specified in a command-line. If the number of values is greater than 1, the option value is interpreted as a list and the result in the API layer will be same as when specifying a list as described below. neutron resource-update --key1 val1 val2 val3 --key2 val4 In the above example, a value of ``key1`` is interpreted as ``["val1", "val2", "val3"]`` and a value of ``key2`` is interpreted as ``val4``. The extra argument mechanism supports more complex value like a list or a dict. Specify a list value ++++++++++++++++++++ A command-line:: neutron resource-update --key list=true val1 val2 val3 will send the following in the API layer:: { "key": [ "val1", "val2", "val3" ] } .. note:: If you want to specify a list value, it is recommended to specify ``list=true``. When ``list=true`` is specified, specified values are interpreted as a list even regardless of the number of values. If ``list=true`` is not specified, specified values are interpreted depends on the number of values how. If the number of values is more than 2, the specified values are interpreted as a list. If 1, the value is interpreted as a string. Specify a dict value ++++++++++++++++++++ A command-line:: neutron resource-update --key type=dict key1=val1,key2=val2,key3=val3 will send the following in the API layer:: { "key": { "key1": "val1", "key2": "val2", "key3": "val3" } } .. note:: ``type=bool True/False`` and ``type=int 10`` are also supported. Specify a list of dicts +++++++++++++++++++++++ A command-line:: neutron resource-update --key type=dict list=true key1=val1 key2=val2 key3=val3 will send the following in the API layer:: { "key": [ {"key1": "val1"}, {"key2": "val2"}, {"key3": "val3"} ] } Passing None as a value ~~~~~~~~~~~~~~~~~~~~~~~ There is a case where we would like to pass ``None`` (``null`` in JSON) in the API layer. To do this:: neutron resource-update --key action=clear The following body will be in the API layer:: {"key": null} .. note:: If ``action=clear`` is specified, ``list=true`` or ``type=dict`` is ignored. It means when ``action=clear`` is specified ``None`` is always sent. Debugging --------- Display API-level communication ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``-v`` (or ``--verbose``, ``--debug``) option displays a detail interaction with your neutron server. It is useful to debug what happens in the API level. Here is an sample output of ``net-show`` command. The first line show what parameters are recognized by neutronclient. It is sometimes useful to check if command-line parameters you specify are recognized properly. .. code-block:: console $ neutron -v net-show mynetwork 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=[])) Next, neutronclient sends an authentication request to keystone to get a token which is used in further operations. .. code-block:: console DEBUG: keystoneauth.session REQ: curl -g -i -X GET http://172.16.18.47:5000 -H "Accept: application/json" -H "User-Agent: keystoneauth1" 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 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"}]}]}} DEBUG: keystoneauth.identity.v3.base Making authentication request to http://172.16.18.47:5000/v3/auth/tokens Neutronclient looks up a network ID corresponding to a given network name. .. code-block:: console 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" 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 RESP BODY: {"networks": [{"id": "3698d3c7-d581-443e-bf86-53c4e3a738f7"}]} Finally, neutronclient retrieves a detail of a given network using the resolved ID. .. code-block:: console 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" 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 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"}} +-----------------------+--------------------------------------+ | Field | Value | +-----------------------+--------------------------------------+ | admin_state_up | True | | id | 3698d3c7-d581-443e-bf86-53c4e3a738f7 | | mtu | 0 | | name | mynetwork | | port_security_enabled | True | | router:external | False | | shared | False | | status | ACTIVE | | subnets | | | tenant_id | 8f0ebf767043483a987736c8c684178d | +-----------------------+--------------------------------------+