---
search: false
---

How to activate OpenStack CLI access to 3Engines Cloud cloud using one- or two-factor authentication[🔗](#how-to-activate-openstack-cli-access-to-brand-name-cloud-using-one-or-two-factor-authentication "Permalink to this headline")
========================================================================================================================================================================================================================================

One-factor and two-factor authentication for activating command line access to the cloud[🔗](#one-factor-and-two-factor-authentication-for-activating-command-line-access-to-the-cloud "Permalink to this headline")
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

To log into a site, you usually provide user name and email address during the creation of the account and then you use those same data to enter the site. You provide that data once and that is why it is called “one-factor” authentication. Two-factor authentication requires the same but considers it to be only the first step; on 3Engines Cloud cloud, the second step is

> * to generate six-digit code using the appropriate software and then to
> * send it to the cloud as a means of additional certification.

Cloud parameters for authentication and, later, OpenStack CLI access, are found in a so-called *RC file*. This article will help you download and use it to first authenticate and then access the cloud using OpenStack CLI commands.

What We Are Going To Cover[🔗](#what-we-are-going-to-cover "Permalink to this headline")
---------------------------------------------------------------------------------------

> * How to download the RC file
> * Adjusting the name of the downloaded RC file
> * The contents of the downloaded RC file
> * How to activate the downloaded RC file
> * One factor authentication
> * Two factor authentication
> * Testing the connection
> * Resolving errors

Prerequisites[🔗](#prerequisites "Permalink to this headline")
-------------------------------------------------------------

No. 1 **Account**

You need a 3Engines Cloud hosting account with access to the Horizon interface: <https://horizon.3Engines.com>.

No. 2 **2FA**

If your account has 2FA enabled (which you will recognize from the respective prompt when authenticating), you need to install and configure a piece of software which generates six-digit codes used for 2FA. To set that up, follow one of these articles, depending on the type of device you are using:

* Mobile device (Android, iOS): [Two-Factor Authentication to 3Engines Cloud site using mobile application](Two-Factor-Authentication-for-3Engines-Cloud-Site.html.md)
* Computer [Two-Factor Authentication to 3Engines Cloud site using KeePassXC on desktop](Using-KeePassXC-for-Two-Factor-Authentication-on-3Engines-Cloud.html.md)

No. 3 **OpenStackClient installed and available**

Installing OpenStackClient on various platforms will also install the ability to run the **.sh** files. Since OpenStack is written in Python, it is recommended to use a dedicated virtual environment for the rest of this article.

Install GitBash on Windows
:   Run **.sh** files and install OpenStackClient from a GitBash window under Windows. [How to install OpenStackClient GitBash for Windows on 3Engines Cloud](../openstackcli/How-to-install-OpenStackClient-GitBash-or-Cygwin-for-Windows-on-3Engines-Cloud.html.md).

Install and run WSL (Linux under Windows)
:   Run **.sh** files and install OpenStackClient from a Ubuntu window under Windows. [How to install OpenStackClient on Windows using Windows Subsystem for Linux on 3Engines Cloud OpenStack Hosting](../openstackcli/How-to-install-OpenStackClient-on-Windows-using-Windows-Subsystem-for-Linux-on-3Engines-Cloud-OpenStack-Hosting.html.md).

Install OpenStackClient on Linux
:   [How to install OpenStackClient for Linux on 3Engines Cloud](../openstackcli/How-to-install-OpenStackClient-for-Linux-on-3Engines-Cloud.html.md).

How to download the RC file[🔗](#how-to-download-the-rc-file "Permalink to this headline")
-----------------------------------------------------------------------------------------

### Location of the link to RC file[🔗](#location-of-the-link-to-rc-file "Permalink to this headline")

**Click on account name**

Top right corner of the Horizon screen contains the account name. Depending on the cloud you are using, you will see a menu like this:

|  |
| --- |
| **WAW3-1, WAW3-2, FRA1-1** |
| ../_images/click_on_email.png |

**Click on API Access**

Navigate to **API Access** -> **Download OpenStack RC File**. Depending on the cloud you are using, you will see a menu like this:

|  |
| --- |
| **WAW3-1, WAW3-2, FRA1-1** |
| ../_images/download_rc_file_2fa.png |

Option **OpenStack clouds.yaml File** is out of scope of this article.

### Which OpenStack RC file to download[🔗](#which-openstack-rc-file-to-download "Permalink to this headline")

Choose the appropriate option, depending on the type of account:

2FA *not* active on the account
:   For clouds **WAW3-1, WAW3-2, FRA1-1**, select option **OpenStack RC File**.

2FA active on the account
:   Download file **OpenStack RC File (2FA)**.

You only need one copy of the RC file at any time. If you downloaded more than one copy of the file to the same folder without moving or renaming them, your operating system may differentiate amongst the downloaded files by adding additional characters at the end of the file name.

By way of example, let the downloaded RC file name be **cloud\_00734\_1-openrc-2fa.sh**. For your convenience, you may want to

> * rename it and
> * move to the folder in which you are going to activate it.

The contents of the downloaded RC file[🔗](#the-contents-of-the-downloaded-rc-file "Permalink to this headline")
---------------------------------------------------------------------------------------------------------------

RC file sets up *environment variables* which are used by the OpenStack CLI client to authenticate to the cloud. By convention, these variables are in upper case and start with **OS\_**: **OS\_TENANT\_ID**, **OS\_PROJECT\_NAME** etc. For example, in case of one-factor authentication, the RC file will ask for password and store it into a variable called **OS\_PASSWORD**.

Below is an example content of an RC file which does not use 2FA:

![rc_file_content.png](../_images/rc_file_content.png)

File which supports 2FA will have additional pieces of code for providing the second factor of authentication.

How to activate the downloaded RC file[🔗](#how-to-activate-the-downloaded-rc-file "Permalink to this headline")
---------------------------------------------------------------------------------------------------------------

The activation procedure will depend on the operating system you are working with:

**Ubuntu**
:   Assuming you are in the same folder in which the RC file is present, use the **source** command:

    > ```
    > source ./cloud_00734_1-openrc-2fa.sh
    >
    > ```

**macOS**
:   The same **source** command should work on macOS. In some versions of macOS though, an alternative command **zsh** could serve as well:

    ```
    zsh ./cloud_00734_1-openrc-2fa.sh

    ```

Note that in both cases **./** means “use the file in this very folder you already are in”.

**Windows**
:   On Windows, to execute file with **.sh** extension, you must have an installed application that can run *Bash* files.

    See Prerequisite No. 3, which describes in more detail how to run **.sh** files using various scenarios on Windows.

### Running with one-factor authentication[🔗](#running-with-one-factor-authentication "Permalink to this headline")

The activated **.sh** file will run in a Terminal window (user name is grayed out for privacy reasons):

![activate-api-2fa-01_creodias.png](../_images/activate-api-2fa-01_creodias.png)

Enter the password, either by typing it in or by pasting it in the way your terminal supports it, and press **Enter** on the keyboard. The password will not be visible on the screen.

If your account has only one-factor authentication, this is all you need to do to start running commands from command line.

### Two-factor authentication[🔗](#two-factor-authentication "Permalink to this headline")

If your file supports two-factor authentication, the terminal will first require the password, exactly the same as in case of one-factor authentication. Then you will get a prompt for the second factor, which usually comes in shape of a six-digit one-time password:

![activate-api-2fa-02_creodias.png](../_images/activate-api-2fa-02_creodias.png)

To get the six digit code, run the app that you are using for authentication. As recommended in **Prerequisite No. 2**, it may be

> * FreeOTP on mobile,
> * KeePassXC on desktop, or you may run
> * other software of your choice, or you can even write
> * your own Python or Bash code to generate the six digit code.

Let’s say that, for example, you are using FreeOTP on mobile device and that this is the icon you assigned to your account:

[![freeotp_icon_to_select.png](../_images/freeotp_icon_to_select.png)](../_images/freeotp_icon_to_select.png)

Tap on it and the six-digit number will appear:

[![freeotp_tapped_number.png](../_images/freeotp_tapped_number.png)](../_images/freeotp_tapped_number.png)

This six-digit number will be regenerated every thirty seconds. Enter the latest number into the Terminal window and press **Enter** on the keyboard. If everything worked correctly, after a few seconds you should return to your normal command prompt with no additional output:

![activate-api-2fa-03_creodias.png](../_images/activate-api-2fa-03_creodias.png)

Duration of life for environment variables set by sourcing the RC file[🔗](#duration-of-life-for-environment-variables-set-by-sourcing-the-rc-file "Permalink to this headline")
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

When you source the file, environment variables are set for your current shell. To prove it, open two terminal windows, source the RC file in one of them but not in the other and you won’t be able to authenticate from that second terminal window.

That is why you will need to activate your RC file each time you start a new terminal session. Once authenticated and while that terminal window is open, you can use it to issue OpenStack CLI commands at will.

Testing the connection[🔗](#testing-the-connection "Permalink to this headline")
-------------------------------------------------------------------------------

If not already, install OpenStack client using one of the links in Prerequisite No 3. To verify access, execute the following command which lists flavors available in 3Engines Cloud cloud:

```
openstack flavor list

```

You should get output similar to this:

![flavor_list_2fa_short.png](../_images/flavor_list_2fa_short.png)

Resolving errors[🔗](#resolving-errors "Permalink to this headline")
-------------------------------------------------------------------

### jq not installed[🔗](#jq-not-installed "Permalink to this headline")

**jq** is an app to parse JSON input. In this context, it serves to process the output from the server. It will be installed on most Linux distros. If you do not have it installed on your computer, you may get a message like this:

![jq_error.png](../_images/jq_error.png)

To resolve, [download from the official support page and follow the directions to install on your operating system](https://jqlang.github.io/jq/download/).

If you are using Git Bash on Windows and running into this error, Step 6 of article on GitBash from **Prerequisite 3**, has proper instructions for installing **jq**.

### 2FA accounts: entering a wrong password and/or six-digit code[🔗](#fa-accounts-entering-a-wrong-password-and-or-six-digit-code "Permalink to this headline")

If you enter a wrong six-digit code, you will get the following error:

```
Call to Keycloak failed with code 401 and message
 {
  "error": "invalid_grant",
  "error_description": "Invalid user credentials"
}

```

If that is the case, simply activate the RC file again as previously and type the correct credentials.

### 2FA accounts: lost Internet connection[🔗](#fa-accounts-lost-internet-connection "Permalink to this headline")

Activating a 2FA RC file requires access to 3Engines Cloud account service because it involves not only setting variables, but also obtaining an appropriate token.

If you do not have an Internet connection, you will receive the following output after having entered a six-digit code:

```
Call to Keycloak failed with code 000 and message

```

It will be followed by an empty line and you will be returned to your command prompt.

To resolve this issue, please connect to the Internet and try to activate the RC file again. If you are certain that you have Internet connection, it could mean that 3Engines Cloud account service is down. If no downtime was announced for it, please contact 3Engines Cloud customer support: [Helpdesk and Support](Help-Desk-And-Support.html.md)

### Non-2FA accounts: entering a wrong password[🔗](#non-2fa-accounts-entering-a-wrong-password "Permalink to this headline")

If your account does not have two-factor authentication and you entered a wrong password, you will **not** get an error. However, if you try to execute a command like **openstack flavor list**, you will get the error similar to this:

```
The request you have made requires authentication. (HTTP 401) (Request-ID: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx)

```

Instead of **x** characters, you will see a string of characters.

To resolve, activate your file again and enter the correct password.

### Using the wrong file[🔗](#using-the-wrong-file "Permalink to this headline")

If you have a 2FA authentication enabled for your account but have tried to activate the non-2FA version of the RC file, executing, say, command **openstack flavor list**, will give you the following error:

```
Unrecognized schema in response body. (HTTP 401)

```

If that is the case, download the correct file if needed and use it.

What To Do Next[🔗](#what-to-do-next "Permalink to this headline")
-----------------------------------------------------------------

With the appropriate version of RC file activated, you should be able to create and use

> * instances,
> * volumes,
> * networks,
> * Kubernetes clusters

and, in general, use all OpenStack CLI commands.

For example, if you want to create a new virtual machine, you can follow this article:

[How to create a VM using the OpenStack CLI client on 3Engines Cloud cloud](../cloud/How-to-create-a-VM-using-the-OpenStack-CLI-client-on-3Engines-Cloud-cloud.html.md)

If you want your new virtual machine to be based on an image which is not available on 3Engines Cloud cloud, you will need to upload it. The following article contains instructions how to do it:

[How to upload your custom image using OpenStack CLI on 3Engines Cloud](../cloud/How-to-upload-your-custom-image-using-OpenStack-CLI-on-3Engines-Cloud.html.md)