Introduction ============ The Cloud Computing service of the `SCIGNE platform `_ offers the user the possiblity to start virtual machines (*VM*) easily. This virtual machines can be used independently to provide single computing server, or orchestrated to create an advanced computing infrastructure (like a computing or a kubernetes cluster). Such Cloud service is called Infrastructure-as-a-Service and permits the user to choose the operating system, the size of the server (number of cores, memory size, etc). It is based on the `OpenStack `_ software. Thanks to all available modules (authentication, image management, storage management, container as a service, etc), OpenStack makes possible to run a complete Cloud infrastructures and to provide a large range of services to the users. This documentation details the use of the OpenStack command-line client (CLI), named **openstack**. This tools interacts with the OpenStack modules through their public API and permits to use efficiently the SCIGNE Cloud Computing service. However, for user looking for a more user-friendly interface, a `web-based dashboard (Horizon) `_. is available. As its use is very intuitive, it is not covered by the following documentation. The team managing the SCIGNE platform is available for helping you to use this service. Please, feel free to `contact us `_ if you need any further information or if you want to have a training organised on this topic! Installation ============ This section details the installation process of the OpenStack command-line client. The OpenStack client is available for several operating systems. It can be installed using the Operating System package manager, like **apt** and **yum**, or by using PIP. In any case, a recent version of `Python `_ is required. Note that you should not mix a PIP-based installation with a package-based installation, as it may lead to compatibility issues. We are recommending to use package-based installation, when it is feasible. The different installation modes are explained in the following chapters. Installation Based on Operating System Packages ----------------------------------------------- Debian and Ubuntu Systems +++++++++++++++++++++++++ The version of the OpenStack client provided by default on Ubuntu may be old, compared to the OpenStack version used on the SCIGNE platform. In order to get access to all features, it is recommended to use a recent version of the client. Such versions are made available through the *cloud-archive* package repository. For installing a specific version of the client (i.e. *Train* as in this example), you should use the following commands as super-user: .. code-block:: console $ sudo add-apt-repository cloud-archive:train $ sudo apt-get update $ sudo apt-get install python-openstackclient Installation on RedHat Entreprise Linux +++++++++++++++++++++++++++++++++++++++ The installation processes on both RedHat Enterprise Linux and RedHat-like systems (CentOS, RockyLinux, etc) are different. This section details the installation on RedHat system with **yum**. It is done by completing the following steps. The software is only available for version 7 and 8 of RedHat. If you want to install the clients on an earlier version, it is necessary to follow the PIP installation method. .. code-block:: console $ sudo yum install -y https://www.rdoproject.org/repos/openstack/openstack-train/rdo-release-train-1.noarch.rpm $ sudo yum update -y $ sudo yum install -y python-openstackclient Installation on CentOS ++++++++++++++++++++++ The installation by using **yum** on CentOS system are realised with the following steps. The client is available for the CentOS 7 (up to OpenStack Train version) and CentOS 8 (starting with OpenStack Train version). If you want to use recent OpenStack version with CentOS 7, you should follow the PIP-based installation process. .. code-block:: console $ sudo yum install -y centos-release-openstack-train $ sudo yum update -y $ sudo yum install -y python-openstackclient .. note:: The ``centos-release-openstack-train`` package is provided by the *extras* repository, enabled by default on CentOS 7. Installation Based on PIP ------------------------- First, it is required to verify that PIP is correctly installed on your system. The installation of PIP is detailed on the `PIP site `_. The OpenStack client is installed with the following command line : .. code-block:: console $ pip install python-openstackclient Verification of the installation -------------------------------- Execute the **openstack** command with the ``--version`` argument to verify that the client is correctly installed: .. code-block:: console $ openstack --version openstack 3.14.2 Please note that the version returned by the **openstack** command can be different with the version displayed in this example. Definition of the Environment Variables --------------------------------------- Once the installation is done, you are nearly ready to use the SCIGNE Cloud service. The last step is to configure the client. For doing this, create the ``${HOME}/.novacreds/iphc.sh`` file with the following content (*username*, *password* and *FG_Cloud* values have to be replaced with the values you received from the SCIGNE team when your account has been created): .. code-block:: bash export LANG=en_US.utf-8 export LC_ALL=en_US.utf-8 export OS_USERNAME=username export OS_PASSWORD=password export OS_PROJECT_NAME=FG_Cloud export OS_USER_DOMAIN_NAME=default export OS_PROJECT_DOMAIN_NAME=default export OS_AUTH_URL=https://sbgcloud.in2p3.fr:5000/v3 export OS_IDENTITY_API_VERSION=3 Once the file is created, it has to be sourced for loading the environment variables within your actuel shell: .. code-block:: console $ source ${HOME}/.novacreds/iphc.sh It is necessary to perform this step each time you are running a new shell, unless you are adding the **source** command into you shell initialisation script (i.e., the ``${HOME}/.bashrc`` file for **bash**). You can now test your client againt the SCIGNE Cloud service: .. code-block:: console $ openstack server list -c ID -c Name -c Status -c Image +--------------------------------------+-------+--------+----------------------+ | ID | Name | Status | Image Name | +--------------------------------------+-------+--------+----------------------+ | 36dd1e32-2a79-4e78-a4e1-999335de3cbd | MY_VM | ACTIVE | Image for Ubuntu ... | +--------------------------------------+-------+--------+----------------------+ The above command displays the list of virtual machines running in the project defined by the ``OS_PROJECT_NAME`` variable at the time you run it. Thus, the list displayed will differ from the one used in this example. Password Modification --------------------- Before using the service, it is required to modify your password for security reasons. This is done with the following command: .. code-block:: console $ openstack user password set Current Password: New Password: Repeat New Password: You should update the password you are using to authenticate to match your new password Once this operation has been performed, the new password has been updated on the server side, but not on the client side: .. code-block:: console $ openstack server list ERROR: Invalid OpenStack Nova credentials. You have to update the corresponding environment variable: .. code-block:: console $ export OS_PASSWORD=MY_NEW_PASSWORD $ openstack server list +--------------------------------------+-------+--------+---------------------------+------------------------------+ | ID | Name | Status | Networks | Image Name | +--------------------------------------+-------+--------+---------------------------+------------------------------+ | 36dd1e32-2a79-4e78-a4e1-999335de3cbd | MY_VM | ACTIVE | fg-default-net=172.16.19.226 | Image for Ubuntu Server 2... | +--------------------------------------+-------+--------+---------------------------+------------------------------+ If the command is successfull, then you can update the ``${HOME}/.novacreds/iphc.sh`` file with your new password. Once the password has been updated in the ``${HOME}/.novacreds/iphc.sh`` file, it is necessary to source this file again to update the environment variable value. The following interactive help is available: .. code-block:: console $ openstack help user set Change current user password optional arguments: -h, --help show this help message and exit --password New user password --original-password Original user password SSH Key Management ------------------- To be able to connect to your virtal machine, it is required to have a SSH key and to register it against the OpenStack service: .. code-block:: console $ ssh-keygen -t rsa -f ${HOME}/.novacreds/cloudkey [...] $ openstack keypair create --public-key=${HOME}/.novacreds/cloudkey.pub cloudkey $ openstack keypair list +----------+-------------------------------------------------+ | Name | Fingerprint | +----------+-------------------------------------------------+ | cloudkey | 33:91:4b:38:52:63:1d:18:7b:e0:e3:0d:3b:63:ce:4b | +----------+-------------------------------------------------+ Virtual Machine Management ========================== This part describes the management of virtual machines. OpenStack Environment Discovery ------------------------------- A few commands permit your to see all available elements available to build your virtual machine. First, the list of operation system images can be obtained with: .. code-block:: console $ openstack image list +--------------------------------------+------------------------------------------------------+--------+ | ID | Name | Status | +--------------------------------------+------------------------------------------------------+--------+ | 6368a92f-4fab-4c8b-93a8-24b80d3eccf9 | Image for CentOS Server 7 [CentOS/7/KVM] | active | | badb9c02-779a-4da8-9c5a-9c59b6284362 | Image for CentOS Server 8 [CentOS/8/KVM] | active | | bcac8255-a321-4349-82e6-6918b34e1df1 | Image for RancherOS [Other/1.5.6/KVM] | active | | a8a2b0d1-ffed-4315-be00-fc14828a5203 | Image for Ubuntu Server 18.04 LTS [Ubuntu/18.04/KVM] | active | | 979d05cb-4164-4f0b-91da-c70608285401 | Image for Ubuntu Server 20.04 LTS [Ubuntu/20.0] | active | | d55e54e0-1d9b-494d-a529-a4a40c60eb23 | ubuntu-18.04-docker-x86_64 | active | +--------------------------------------+------------------------------------------------------+--------+ .. note:: As the list of the available images is updated regularly, it is very likely that you will get a slightly different result. Then, the list of available flavor (size of servers) is displayed with: .. code-block:: console $ openstack flavor list +--------------------------------------+-------------------+--------+------+-----------+-------+-----------+ | ID | Name | RAM | Disk | Ephemeral | VCPUs | Is Public | +--------------------------------------+-------------------+--------+------+-----------+-------+-----------+ | 00b54b02-63d0-4d15-927d-6e2f5a4d4920 | g4.xlarge-4xmem | 65536 | 40 | 0 | 8 | True | | 048fc66b-d60a-4d07-b1e4-1fae3e6ab395 | m1.small-mmem | 4096 | 20 | 0 | 1 | True | | 1ff24edd-1283-469c-abc1-7f697873d63c | m1.2xlarge | 32768 | 20 | 0 | 16 | True | | 2 | m1.small | 2048 | 20 | 0 | 1 | True | | 242a578e-b314-4f33-83ea-b05f50f08960 | g2.xlarge-4xmem | 65536 | 40 | 0 | 8 | True | | 588f4548-b8e7-48fd-8ee5-357662a4c08f | m1.2xlarge-8xmem | 131072 | 20 | 0 | 16 | True | | 5f0a3206-5f25-4341-beba-7d0a96cdb108 | m1.8xlarge-16xmem | 262144 | 20 | 0 | 64 | True | | 6cdf0bde-85c6-4e92-b7ab-f80c75a695b7 | m1.xlarge | 16384 | 20 | 0 | 8 | True | | 7005975e-735f-4b08-a69d-2ce1a771be85 | m1.8xlarge | 131072 | 20 | 0 | 64 | True | | 73730dea-ca08-47fb-ac0b-2ebd6dbe1465 | g1.xlarge-4xmem | 65536 | 40 | 0 | 8 | True | | 895f886c-85dd-4924-9a35-4177655559c5 | m1.large-2d | 8192 | 40 | 0 | 4 | True | | ab1fbd4c-324d-4155-bd0f-72f077f0ebce | m1.medium | 4096 | 20 | 0 | 2 | True | | ab9784d7-e785-4f4e-a415-1d188505b5eb | m1.large | 8192 | 20 | 0 | 4 | True | | aca4fac9-4761-4735-88b8-4102d6f4ecb3 | m1.2xlarge-4xmem | 65536 | 20 | 0 | 16 | True | | cf7f0d1f-8ecd-4b19-b6bb-f2f89cf55bd0 | m1.4xlarge | 65536 | 20 | 0 | 32 | True | | d6aae2a5-8f5d-40dd-b6f3-2e8d9fb7efa1 | m1.xlarge-8xmem | 131072 | 20 | 0 | 8 | True | +--------------------------------------+-------------------+--------+------+-----------+-------+-----------+ At least, to know the networks usable by the virtual machine, use : .. code-block:: console $ openstack network list +--------------------------------------+----------------+--------------------------------------+ | ID | Name | Subnets | +--------------------------------------+----------------+--------------------------------------+ | 3877b236-dbca-4541-a007-7444d38acabc | fg-default-net | c8ba2397-a874-47e9-8f54-0ed433fa2240 | | 8fa5eb12-ee72-4e77-a45b-8fde11efc75f | ext-net | 6e8ffc7a-4536-4c21-a8e5-00227ee8619a | +--------------------------------------+----------------+--------------------------------------+ In the previous table, two networks are available: ``fg-default-net`` and ``ext-net``. In fact, only the ``fg-default-net`` network is usable directly at boot time by the virtual machine. The other network is used afterwards to provide public IP addresses. Virtual Machine Creation ------------------------ In the previous section, we have retrieved the list of all the elements that can be used to compose the virtual machine. Once you have chosen the different elements of your virtual machine, you can instantiate it using the **openstack server create** command. For example, if we want to run an Ubuntu image with 1 cpu, 2 GB RAM and 20 GB hard disk on the ``fg-default-net`` network and whose name will be *MY\_VM\_NAME*, we would use the following command use the following command: .. code-block:: console $ openstack server create --key-name cloudkey --image 979d05cb-4164-4f0b-91da-c70608285401 \ --flavor m1.small --nic net-id=3877b236-dbca-4541-a007-7444d38acabc MY_VM_NAME +-----------------------------+----------------------------------------------------------------------------------------+ | Field | Value | +-----------------------------+----------------------------------------------------------------------------------------+ | OS-DCF:diskConfig | MANUAL | | OS-EXT-AZ:availability_zone | | | OS-EXT-STS:power_state | NOSTATE | | OS-EXT-STS:task_state | scheduling | | OS-EXT-STS:vm_state | building | | OS-SRV-USG:launched_at | None | | OS-SRV-USG:terminated_at | None | | accessIPv4 | | | accessIPv6 | | | addresses | | | adminPass | W6jJUvpRhAyU | | config_drive | | | created | 2021-11-24T06:24:39Z | | flavor | m1.small (2) | | hostId | | | id | 367110ac-b05a-4855-884e-e3b00717ab4a | | image | Image for Ubuntu Server 20.04 LTS [Ubuntu/20.0] (979d05cb-4164-4f0b-91da-c70608285401) | | key_name | cloudkey | | name | MY_VM_NAME | | progress | 0 | | project_id | 92d2f61945214c8a80d12d696b82426e | | properties | | | security_groups | name='default' | | status | BUILD | | updated | 2021-11-24T06:24:39Z | | user_id | d04e19e72801e8d9d802a6178a7d5a006e3cc9383c35e82a769fc6686782b667 | | volumes_attached | | +-----------------------------+----------------------------------------------------------------------------------------+ .. note:: When launching virtual machines, you may find yourself issues with quota overruns: .. code-block:: console $ openstack server create [...] MY_VM_NAME ERROR: Quota exceeded for cores: Requested 1, but already used 22 of 22 cores (HTTP 413) (Request-ID: req-6aefedba-4666-4393-b6a1-24423f3bef78) In this example, the error tells you that all available processors for your group (*project*) are currently occupied. You can either wait for other users to free up some, or ask the SCIGNE team to allocate you additional quota. You can list the quota limits with the following command: .. code-block:: console $ openstack quota show +-----------------------+----------------------------------+ | Field | Value | +-----------------------+----------------------------------+ | backup-gigabytes | 1000 | | backups | 10 | | cores | 256 | | fixed-ips | -1 | | floating-ips | 64 | | gigabytes | 8192 | | gigabytes___DEFAULT__ | -1 | | gigabytes_ceph | -1 | | groups | 10 | | health_monitors | None | | injected-file-size | 10240 | | injected-files | 5 | | injected-path-size | 255 | | instances | 64 | | key-pairs | 100 | | l7_policies | None | | listeners | None | | load_balancers | None | | location | None | | name | None | | networks | 100 | | per-volume-gigabytes | -1 | | pools | None | | ports | 500 | | project | 92d2f61945214c8a80d12d696b82426e | | project_name | FG_Cloud | | properties | 128 | | ram | 1048576 | | rbac_policies | 10 | | routers | 10 | | secgroup-rules | 256 | | secgroups | 32 | | server-group-members | 10 | | server-groups | 32 | | snapshots | 10 | | snapshots___DEFAULT__ | -1 | | snapshots_ceph | -1 | | subnet_pools | -1 | | subnets | 100 | | volumes | 64 | | volumes___DEFAULT__ | -1 | | volumes_ceph | -1 | +-----------------------+----------------------------------+ Online help is available and describes all usable parameters: .. code-block:: console $ openstack help server create usage: openstack server create [-h] [-f {json,shell,table,value,yaml}] [-c COLUMN] [--max-width ] [--fit-width] [--print-empty] [--noindent] [--prefix PREFIX] (--image | --volume ) --flavor [--security-group ] [--key-name ] [--property ] [--file ] [--user-data ] [--availability-zone ] [--block-device-mapping ] [--nic ] [--network ] [--port ] [--hint ] [--config-drive |True] [--min ] [--max ] [--wait] Create a new server [...] .. note:: When using the **openstack** command, it is possible to use names (e.g. *MY\_VM\_NAME*) as well as identifiers (e.g. ``36dd1e32-2a79-4e78-a4e1-999335de3cbd``). It is recommended to use the IDs, as they are unique (it is possible to run two virtual machines with the same name). With the following command, it is possible to monitor the status of the VM: .. code-block:: console $ openstack server show MY_VM_NAME +-----------------------------+----------------------------------------------------------------------------------------+ | Field | Value | +-----------------------------+----------------------------------------------------------------------------------------+ | OS-DCF:diskConfig | MANUAL | | OS-EXT-AZ:availability_zone | nova | | OS-EXT-STS:power_state | Running | | OS-EXT-STS:task_state | None | | OS-EXT-STS:vm_state | active | | OS-SRV-USG:launched_at | 2021-11-24T06:26:47.000000 | | OS-SRV-USG:terminated_at | None | | accessIPv4 | | | accessIPv6 | | | addresses | fg-default-net=172.16.19.226 | | config_drive | | | created | 2021-11-24T06:24:39Z | | flavor | m1.small (2) | | hostId | cf41a7ccb0611d6dcc24e54c5983dbe17dda36cf954f5e4625607474 | | id | 367110ac-b05a-4855-884e-e3b00717ab4a | | image | Image for Ubuntu Server 20.04 LTS [Ubuntu/20.0] (979d05cb-4164-4f0b-91da-c70608285401) | | key_name | cloudkey | | name | MY_VM_NAME | | progress | 0 | | project_id | 92d2f61945214c8a80d12d696b82426e | | properties | | | security_groups | name='default' | | status | ACTIVE | | updated | 2021-11-24T06:25:49Z | | user_id | d04e19e72801e8d9d802a6178a7d5a006e3cc9383c35e82a769fc6686782b667 | | volumes_attached | | +-----------------------------+----------------------------------------------------------------------------------------+ The *ACTIVE* status tells us that the VM is ready to be used. However, it doesn't have an interface to the external network yet, since its IP address is in the internal network. Before being able to connect to it with SSH, it is necessary to attach a public IP address to it. This IP is visible and accessible from the internet. This is detailed in the `Network Management <#network-management>`_ chapter. Customizing Virtual Machines ---------------------------- You can customize your virtual machine during their creation by using the ``--user-data`` parameter with the **openstack server create** command. This parameter references a file containing instructions for the **cloud-init** software that is present in the virtual machine. The following example upgrades the system and installs additional packages packages, useful for encrypting a volume and the security. Create a file ``cloud_init_cfg.txt`` containing: .. code-block:: yaml #cloud-config # Upgrade the instance OS packages on first boot package_upgrade: true # Add packages for entropy gathering and encrypted volume management packages: - cryptsetup - fail2ban - haveged .. note:: The first '#' character must be present in the file as it is, it tells the **cloud-init** software the format of the contents of the ``cloud_init_cfg.txt`` file. And use it when creating your virtual machine: .. code-block:: console $ openstack server create [...] --user-data cloud_init_cfg.txt MY_VM_NAME .. note:: Warning: the execution of the **cloud-init** software is not instantaneous. If you request a full operating system update, it may take several minutes to complete, even though you can already connect to the VM with **ssh**. To check that everything went well, you can check the contents of the ``/var/log/cloud-init.log`` and ``/var/log/cloud-init-output.log`` files on the virtual machine. The **cloud-init** software is very sensitive to the file format of the ``cloud_init_cfg.txt`` file: spaces, tabs and other formatting elements are very important. In addition to referring to the documentation indicated below, you can use the **yamlint** tool to check the format. However, it is more picky than **cloud-init**, so use its remarks only for information. Build your contextualisation script a little at a time, checking at each step that what you have added is working correctly. Look at the `cloud-init documentation `_ to get more information about the configuration options of this tool. Network Management ------------------ To be able to connect to your VM, you have to add a public IP address. This section details how to add such address to you VM. First, you need to check if a public IP address is available: .. code-block:: console $ openstack floating ip list -c ID -c "Floating IP Address" -c "Fixed IP Address" +--------------------------------------+---------------------+------------------+ | ID | Floating IP Address | Fixed IP Address | +--------------------------------------+---------------------+------------------+ | 03a25383-a3ee-42d9-8dc2-7184257f55c3 | 134.158.151.32 | 172.16.19.133 | | 07514ea0-8b5c-4eb4-83b1-791c848ae29d | 134.158.151.205 | 172.16.19.43 | | 09918b58-9ae3-4e9f-a759-7929ab3f78f6 | 134.158.151.110 | 172.16.19.26 | | 106cdc30-1aba-4ac0-b9ec-373321488487 | 134.158.151.142 | None | ... +--------------------------------------+---------------------+------------------+ In this list, three IP adresses are already associated with a private IP and an IP address is available (the ``Fixed IP Address`` field contains the *None* value). If all IP addresses are used, then it is necessary to create a new: .. code-block:: console $ openstack floating ip create ext-net +---------------------+--------------------------------------+ | Field | Value | +---------------------+--------------------------------------+ | description | | | fixed_ip_address | None | | floating_ip_address | 134.158.151.224 | | floating_network_id | 314be651-fcaa-4dcc-ac0a-dfdcd7e58ba1 | | headers | | | id | f60c77d9-bae4-422d-83c3-16d155bac396 | | port_id | None | | project_id | 59402a7327114c2cb97f0d9e6263cdda | | router_id | None | | status | DOWN | +---------------------+--------------------------------------+ Once the IP address is available, it can be attached to the VM with the following command: .. code-block:: console $ openstack server add floating ip MY_VM_NAME 134.158.151.224 It is possible to verify that the IP address is correctly associated to the virtual machine: .. code-block:: console $ openstack server list --name MY_VM_NAME -c ID -c Name -c Networks +--------------------------------------+------------+-----------------------------------------------+ | ID | Name | Networks | +--------------------------------------+------------+-----------------------------------------------+ | 91243eef-9168-4250-b4d8-466f02797823 | MY_VM_NAME | fg-default-net=172.16.19.226, 134.158.151.224 | +--------------------------------------+------------+-----------------------------------------------+ Now that the virtual machine has a public IP address, you can check the network connectivity with the **ping** command: .. code-block:: console $ ping -c 3 134.158.151.224 If it works fine, then you can connect to it with **ssh**: .. code-block:: console $ ssh -i ${HOME}/.novacreds/cloudkey centos@134.158.151.224 If the connection to the virtual machine fails, look at the `SSH Error <#ssh-error>`_ section. .. note:: The default username used to connect to Ubuntu and CentOS systems are *ubuntu* and *centos* respectively. Storage Management ------------------ By default, when a virtual machine is deleted, all changes you have applied to it are lost. If you want to store data, like software or scientific data, that are reusable between two following virtual machines, you have to create a persistent storage. This type of storage is like an external drive that you plug to your VM either at boot time or later. To display the list of persistent storage, use: .. code-block:: console $ openstack volume list +--------------------------------------+---------------+-----------+------+--------------------------------------------+ | ID | Display Name | Status | Size | Attached to | +--------------------------------------+---------------+-----------+------+--------------------------------------------+ | d874ed50-f4dd-11e6-b99e-8f36e05a44c6 | MONGODB | in-use | 100 | Attached to DATA_ANALYSIS on /dev/vdd | | e3469d32-f4dd-11e6-b9be-3b36b57652e5 | DATA_1 | in-use | 200 | Attached to DATA_ANALYSIS on /dev/vdc | | ec8de7c4-f4dd-11e6-a96b-7f9e7042f1e8 | chemistry-vol | available | 200 | | | 0243cb42-f4de-11e6-9d72-b73ff56f8215 | VM_IPHC_START | available | 10 | | | 09c16c44-f4de-11e6-8b45-433e4aa51e4c | SIMDAT_VOLUME | available | 8 | | | 0e48a656-f4de-11e6-878b-eb0c0efe4cca | vmdata_disk_2 | available | 250 | | | 13c86eae-f4de-11e6-b316-1f8b7ed3376e | DATA_DISK | in-use | 50 | Attached to DATA_ANALYSIS on /dev/vdb | | 179a0326-f4de-11e6-920c-c7f2b28ed02b | R_Data | in-use | 8 | Attached to vm_iphc_r_analysis on /dev/vdb | +--------------------------------------+---------------+-----------+------+--------------------------------------------+ For creating a persistent storage with a size of 8 GB and named *MY_VOLUME_NAME*, use the following command: .. code-block:: console $ openstack volume create --size 8 MY_VOLUME_NAME +---------------------+--------------------------------------+ | Field | Value | +---------------------+--------------------------------------+ | attachments | [] | | availability_zone | nova | | bootable | false | | consistencygroup_id | None | | created_at | 2017-02-16T10:08:02.493311 | | description | None | | encrypted | False | | id | 58230433-086f-4ff2-99ac-8c3e0f5520c2 | | multiattach | False | | name | MY_VOLUME_NAME | | properties | | | replication_status | disabled | | size | 8 | | snapshot_id | None | | source_volid | None | | status | creating | | type | None | | updated_at | None | | user_id | c13c93bf1b79447c8cd1464128d7685f | +---------------------+--------------------------------------+ Then, attach this volume to your virtual machine by using the identifier of the storage: .. code-block:: console $ openstack server add volume --device /dev/vdb MY_VM_NAME 58230433-086f-4ff2-99ac-8c3e0f5520c2 The storage will be shown to the operating system as ``/dev/vdb``. To verifiy that the disk is correctly associated with the VM, check the content of the ``Status`` column with the following command. It the ``Status`` column has for value *in-use* and the ``Attached to`` column contains the identified of the VM, then it is fine. .. code-block:: console $ openstack volume list --name MY_VOLUME_NAME +--------------------------------------+----------------+--------+------+------------------------------------+ | ID | Display Name | Status | Size | Attached to | +--------------------------------------+----------------+--------+------+------------------------------------+ | 58230433-086f-4ff2-99ac-8c3e0f5520c2 | MY_VOLUME_NAME | in-use | 8 | Attached to MY_VM_NAME on /dev/vdb | +--------------------------------------+-------------------------+------+------------------------------------+ At the begin, this disk does not contain any data and is not formatted. If this disk will store confidential data, it is recommended to encrypt the volume. This operation is detailed in the `Disk Encryption <#disk-encryption>`_ chapter. Otherwise, connect to your VM, format the volume and mount it: .. code-block:: console [centos@my-vm-name ~]$ sudo su [root@my-vm-name centos]# mkfs -t ext4 /dev/vdb [root@my-vm-name centos]# mkdir /storage1 [root@my-vm-name centos]# mount /dev/vdb /storage1 [root@my-vm-name centos]# df -h /storage1 Filesystem Size Used Avail Use% Mounted on /dev/vdb 8.0G 3.0M 7.8G 1% /storage1 The last command permits us to verify that the size of the disk corresponds to the one we have chosen (8 GB in this example) and that the disk is correctly mounted on ``/storage1``. .. note:: The virtual disk can also be partitioned before being formated. This disk can be moved from one virtual machine to another. For doing this, you have to umount it correctly: .. code-block:: console [root@my-vm-name centos]# umount /storage1 .. note:: If you have added the reference of your persistent disk in the ``/etc/fstab`` file of your VM, and you have move the disk to another VM, do not forget to remove any reference to this disk in the ``/etc/fstab`` file, otherwise the virtual machine will not boot (it will be looking for a disk that is not available anymore). The disk can be removed from the VM with the following command: .. code-block:: console $ openstack server remove volume MY_VM_NAME 58230433-086f-4ff2-99ac-8c3e0f5520c2 $ openstack volume list --name MY_VOLUME_NAME +--------------------------------------+----------------+-----------+------+-------------+ | ID | Display Name | Status | Size | Attached to | +--------------------------------------+----------------+-----------+------+-------------+ | 58230433-086f-4ff2-99ac-8c3e0f5520c2 | MY_VOLUME_NAME | available | 8 | | +--------------------------------------+----------------------------+------+-------------+ .. note:: When the virtual machine is rebooted, the disk is not automatically mounted to the filesystem. To mount the disk automatically, a reference to it must be added to the ``/etc/fstab`` file. Virtual Machine Deletion ------------------------ If the virtual machine is no longer required, it can be deleted. Deleting the virtual machine permits to free up the resources (as long it is not deleted, it will be accounted in the usage statistics and in the quota). In this case, all the modifications that have been made to the image (package installation, etc) will be lost, except for those that are on the persistent disk. Before deleting the VM, you have to connect to the VM and unmount the disk (to avoid data corruption): .. code-block:: console [root@my-vm-name centos]# umount /storage1 If you do not need anymore the data on the persistent storage, you may initialise it with random data (this task can be quite long), detache it from the server and delete it: .. code-block:: console [root@my-vm-name centos]# dd if=/dev/urandom of=/dev/vdb bs=4k $ openstack server remove volume MY_VM_NAME 58230433-086f-4ff2-99ac-8c3e0f5520c2 $ openstack volume delete 58230433-086f-4ff2-99ac-8c3e0f5520c2 At least, the following command can be run to delete effectively the VM: .. code-block:: console $ openstack server delete MY_VM_NAME Advanced Usage ============== This chapter describes several possibilities to get further in the usage of the SCIGNE Cloud service. Time Synchronisation -------------------- The access to NTP servers outside the SCIGNE platform is not permitted. If you are using time synchronisation tools, you need to configure them with our NTP servers: * sbgntp1.in2p3.fr (193.48.89.16) * sbgntp2.in2p3.fr (193.48.89.17) ntpd ++++ If you are using **ntpd** for time synchronisation, you need to have the following lines in your ``/etc/ntp.conf`` file: .. code-block:: console server 193.48.89.16 restrict 193.48.89.16 mask 255.255.255.255 nomodify notrap noquery server 193.48.89.17 restrict 193.48.89.17 mask 255.255.255.255 nomodify notrap noquery chronyd +++++++ If you are using **chronyd** for time synchronisation, you need to have the following lines in the ``/etc/chrony.conf`` configuration file: .. code-block:: console server 193.48.89.16 server 193.48.89.17 Disk Encryption --------------- This section details the use of the `dm-crypt/LUKS tool `_ for the encryption of permanent disks. This tools is provided as standard by Linux distributions and can easily be installed with the package manager of your virtual machine. The example is based on using an Ubuntu distribution, but can easily be reproduced with a RedHat-based operating system. .. code-block:: console ubuntu@my-vm-name:~$ sudo su - sudo: unable to resolve host my-vm-name root@my-vm-name:~# apt -y update root@my-vm-name:~# apt -y install cryptsetup To encrypt a permanent disk, it must first be properly initialized. In the example below, the disk named ``/dev/vdb`` is first filled with random data, then it is initialized using the **cryptsetup luksFormat** command. This first step can be quite long. .. code-block:: console root@my-vm-name:~# dd if=/dev/urandom of=/dev/vdb bs=4k root@my-vm-name:~# cryptsetup -v --cipher aes-xts-plain64 --key-size 512 \ --hash sha512 --iter-time 5000 --use-random luksFormat /dev/vdb If the latter command slows down or even freezes with the following message: .. code-block:: console System is out of entropy while generating volume key. Please move mouse or type some text in another window to gather some random events. Generating key (0% done). Then you can make the **cryptsetup [...] luksFormat** command faster by installing the **haveged** program in your virtual machine (which is already done if you followed the procedure described in the `Customizing Virtual Machines <#customizing-virtual-machines>`_ chapter). The following command verifies that the disk is now of type LUKS: .. code-block:: console root@my-vm-name:~# cryptsetup luksDump /dev/vdb LUKS header information for /dev/vdb Version: 1 Cipher name: aes Cipher mode: xts-plain64 Hash spec: sha512 Payload offset: 4096 MK bits: 512 MK digest: c4 f7 4b 02 2a 3f 12 c1 2c ba e5 c9 d2 45 9a cd 89 20 6c 73 MK salt: 98 58 3e f3 f6 88 99 ea 2a f3 cf 71 a0 0d e5 8b d5 76 64 cb d2 5c 9b d1 8a d3 1d 18 0e 04 7a eb MK iterations: 81250 UUID: c216d954-199e-4eab-a167-a3587bd41cb3 Key Slot 0: ENABLED Iterations: 323227 Salt: a0 45 3e 98 fa cf 60 74 c6 09 3d 54 97 89 be 65 5b 96 7c 1c 39 26 47 b4 8b 0e c1 3a c9 94 83 c2 Key material offset: 8 AF stripes: 4000 Key Slot 1: DISABLED Key Slot 2: DISABLED Key Slot 3: DISABLED Key Slot 4: DISABLED Key Slot 5: DISABLED Key Slot 6: DISABLED Key Slot 7: DISABLED The disc is now ready for use. The first time you use it, the following steps should be taken: 1. Open the encrypted disk with the **cryptsetup luksOpen** command. The name *storage1* is only indicative, you can choose what you want: .. code-block:: console root@my-vm-name:~# cryptsetup luksOpen /dev/vdb storage1 2. Create a filesystem on the disk: .. code-block:: console root@my-vm-name:~# mkfs.ext4 /dev/mapper/storage1 3. Create a mount point for the disk: .. code-block:: console root@my-vm-name:~# mkdir /storage1 4. Mount the disk: .. code-block:: console root@my-vm-name:~# mount -t ext4 /dev/mapper/storage1 /storage1 5. Verify the available space (which can be slightly different with the value given to the **openstack volume create**): .. code-block:: console root@my-vm-name:~# df -h /storage1 Filesystem Size Used Avail Use% Mounted on /dev/mapper/storage1 2.0G 6.0M 1.9G 1% /storage1 Once the disk is operational, steps 2 and 3 are no longer necessary. You can now send files (e.g. DATA.dat) from your home computer to your virtual machine securely, for example with **scp**: .. code-block:: console $ scp -i ${HOME}/.novacreds/cloudkey DONNEES.dat ubuntu@134.158.151.224:/le/chemin/destination DONNEES.dat 100% 82 0.1KB/s 00:00 When you have finished working on the disk, you can remove it cleanly with the following commands: .. code-block:: console root@my-vm-name:~# umount /storage1 root@my-vm-name:~# cryptsetup close storage1 For the next uses of this persistent virtual disk, there will be no need to perform all these operations, only do the following: .. code-block:: console root@my-vm-name:~# cryptsetup luksOpen /dev/vdb storage1 root@my-vm-name:~# mkdir /storage1 root@my-vm-name:~# mount -t ext4 /dev/mapper/storage1 /storage1 Troubleshooting =============== This section allows you to solve the most common problems encountered when using OpenStack. SSH Error --------- Immediately after starting the virtual machine, you may find yourself with connection problems: .. code-block:: console $ ssh -i ${HOME}/.novacreds/cloudkey ubuntu@134.158.151.224 ssh: connect to host 134.158.151.224 port 22: Connection refused This problem is usually due to the fact that the SSH service is not yet started on the virtual machine. You have to wait, which can take up to several minutes. Another type of error may be encountered: .. code-block:: console $ ssh -i ${HOME}/.novacreds/cloudkey ubuntu@134.158.151.224 [...] Permission denied (publickey). In this case, you need to check that the SSH key you are using is the same as the one stored in the OpenStack database. To do this, check that their fingerprints are equivalent. To obtain the fingerprint of the key stored by OpenStack, run: .. code-block:: console $ openstack keypair list +----------+-------------------------------------------------+ | Name | Fingerprint | +----------+-------------------------------------------------+ | cloudkey | 0d:97:13:66:49:03:44:da:69:82:3c:dd:b9:d7:25:64 | +----------+-------------------------------------------------+ And to get the key fingerprint used by the **ssh** command, run: .. code-block:: console $ ssh-keygen -lf ${HOME}/.novacreds/cloudkey.pub 2048 33:91:4b:38:52:63:1d:18:7b:e0:e3:0d:3b:63:ce:4b you@home (RSA) If they are different, you must update your public key in OpenStack: .. code-block:: console $ openstack keypair delete cloudkey $ openstack keypair add --pub-key=${HOME}/.novacreds/cloudkey.pub cloudkey $ openstack keypair list +----------+-------------------------------------------------+ | Name | Fingerprint | +----------+-------------------------------------------------+ | cloudkey | 33:91:4b:38:52:63:1d:18:7b:e0:e3:0d:3b:63:ce:4b | +----------+-------------------------------------------------+ If they are the same, OpenStack may not have been able to install them correctly when the new VM was started. The **cloud-init** software is responsible for installing the SSH key in your virtual machine. You can see the cloud-init log lines in the virtual machine console. To get the console connection url, use the following command: .. code-block:: console $ openstack console url show --novnc MY_VM_NAME +-------+----------------------------------------------------------------------------------------+ | Type | Url | +-------+----------------------------------------------------------------------------------------+ | novnc | http://sbgcloud.in2p3.fr:6080/vnc_auto.html?token=d609176d-c397-4841-b4dc-566300209209 | +-------+----------------------------------------------------------------------------------------+ Then, after logging into the console with a web browser, look for lines that contain the elements *ci-info* and *Authorized keys from* and compare with your key fingerprints. If you see any error messages, the easiest thing to do is to `contact the SCIGNE team `_ with a copy of these error messages. When the key is successfully transferred to the virtual machine, you get a message like: .. code-block:: console Cloud-init v. 0.7.5 running 'module:final' at Mon, 27 Jun 2015 08:15:34 +0000. Up 65.40 seconds. ci-info: ++++++++++++++Authorized keys from /root/.ssh/authorized_keys for user root++++++++++++++ ci-info: +---------+-------------------------------------------------+---------+-----------------+ ci-info: | Keytype | Fingerprint (md5) | Options | Comment | ci-info: +---------+-------------------------------------------------+---------+-----------------+ ci-info: | ssh-rsa | 33:91:4b:38:52:63:1d:18:7b:e0:e3:0d:3b:63:ce:4b | - | joe@hey.com | ci-info: +---------+-------------------------------------------------+---------+-----------------+ If you only want to view the console output of the virtual machine, it is more convenient to use : .. code-block:: console $ openstack console log show MY_VM_NAME Additional Documentation ======================== The following sites can be consulted to obtain more information about the use of OpenStack: - `The OpenStack client user guide `_; - `The official OpenStack wiki `_; - `Q&A about OpenStack `_.