Introduction ============ The IaaS Cloud Computing service provided by the `SCIGNE platform `_ allows users to independently start virtual machines (*VMs*) and orchestrate these deployments to create on-demand computing infrastructures. Users can choose the operating system and flavor (number of cores, amount of memory and disk space) for each of these machines. This service is based on the `OpenStack software `_. Thanks to the various modules available (authentication, image management, storage management, on-demand containers, scheduler, etc.), OpenStack enables users to manage a cloud-based infrastructure and provide a customizable set of services. This documentation details the use of the OpenStack command-line client (CLI), named **openstack**. This tool interacts with the OpenStack modules through their public API and permits to use efficiently the SCIGNE Cloud Computing service. However, for users 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 to help you use this service. Please, feel free to `contact us `_ if you need any further information or if you want to have training organized on this topic! Installation ============ This section details the installation process of the OpenStack command-line client. The OpenStack client is available for various operating systems, either through installation with PIP or via APT or YUM package managers for Debian, Ubuntu, RedHat or derivative Linux distributions. In all cases, the `Python software `_ (version 3 or later) must be installed. Only one installation of the OpenStack client is required, either with your distribution's package manager or with PIP. We recommend using the package manager installation whenever possible. The different installation modes are detailed below. Avoid using two installation modes, for example mixing PIP with distribution packages, to prevent conflicts between different versions that could render the client unusable. Installation Based on Operating System Packages ----------------------------------------------- Debian and Ubuntu Systems +++++++++++++++++++++++++ The version of the OpenStack client provided in recent Ubuntu distributions (22.04, 24.04) is compatible with the version of OpenStack installed on the SCIGNE platform. To install the default client, run the following as *root* user: .. code-block:: console $ sudo apt-get install python3-openstackclient Redhat and its derivatives ++++++++++++++++++++++++++ This section describes the installation procedure on Alma Linux 9. It is almost as simple as installing on Ubuntu. In fact, there is only one prerequisite: having the EPEL repository. It can be enabled with the following command (to be executed as the *root* user): .. code-block:: console $ dnf install epel-release Then, simply perform the installation with the **dnf** tool as the *root* user: .. code-block:: console $ dnf install python3-openstackclient Installation Based on PIP ------------------------- If you cannot use the previous methods (for example, because you do not have administrative rights on the machine), it is also possible to install the OpenStack client using **pip**. Details on how to install **pip** can be found on the `PIP website `_. The OpenStack client is installed with the following commands: .. code-block:: console $ pip install 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 6.2.0 Please note that the version returned by the **openstack** command can be different from 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/scigne.sh`` file with the following content (*username*, *password* and *SCIGNE* 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=SCIGNE 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 current shell: .. code-block:: console $ source ${HOME}/.novacreds/scigne.sh It is necessary to perform this step each time you are running a new shell, unless you are adding the above **source** command into you shell initialization script (for example, the ``${HOME}/.bashrc`` file for **bash**). You can now test your client against 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 | SCIGNE Ubuntu 24.04 x86_64 | +--------------------------------------+-------+--------+----------------------------+ 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 | iphc-net=172.16.19.226 | SCIGNE Ubuntu 24.04 x86_64 | +--------------------------------------+-------+--------+------------------------+----------------------------+ If the command is successful, then you can update the ``${HOME}/.novacreds/scigne.sh`` file with your new password. Once the password has been updated in the ``${HOME}/.novacreds/scigne.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 password 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 virtual 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 ------------------------------- The following commands will enable you to see all available elements you will use to build your virtual machine. First, the list of Operating System images can be obtained with: .. code-block:: console $ openstack image list +--------------------------------------+-----------------------------+--------+ | ID | Name | Status | +--------------------------------------+-----------------------------+--------+ | 49bb8d01-dd39-4834-96c2-cc06bd5b947f | SCIGNE Alma Linux 9 aarch64 | active | | 6113a16a-b3de-4534-862b-9151482ba15f | SCIGNE AlmaLinux 9 x86_64 | active | | 53cd0809-59be-40bf-a330-b92733ac2e82 | SCIGNE Debian 12 x86_64 | active | | 155730bc-7b1a-40b6-81f1-a01be4513d0d | SCIGNE Ubuntu 22.04 x86_64 | active | | 3c785ac5-b216-43dc-871b-6643962a2d19 | SCIGNE Ubuntu 24.04 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 flavors (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 last, to know the networks usable by the virtual machine, use : .. code-block:: console $ openstack network list +--------------------------------------+------------+--------------------------------------+ | ID | Name | Subnets | +--------------------------------------+------------+--------------------------------------+ | 3877b236-dbca-4541-a007-7444d38acabc | scigne-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: ``scigne-net`` and ``ext-net``. In fact, only the ``scigne-net`` network is usable directly at boot time by the virtual machine. The other network may be 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 ``iphc-net`` network and whose name will be *MY\_VM\_NAME*, we would 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 | 2025-09-11T06:24:39Z | | flavor | m1.small (2) | | hostId | | | id | 367110ac-b05a-4855-884e-e3b00717ab4a | | image | SCIGNE Ubuntu 24.04 x86_64 (3c785ac5-b216-43dc-871b-6643962a2d19) | | key_name | cloudkey | | name | MY_VM_NAME | | progress | 0 | | project_id | 92d2f61945214c8a80d12d696b82426e | | properties | | | security_groups | name='default' | | status | BUILD | | updated | 2025-09-11T06:24:39Z | | user_id | d04e19e72801e8d9d802a6178a7d5a006e3cc9383c35e82a769fc6686782b667 | | volumes_attached | | +-----------------------------+-------------------------------------------------------------------+ .. note:: When launching virtual machines, you may have 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 +-----------------------+----------------------------------+ | 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 | 2025-09-11T06:26:47.000000 | | OS-SRV-USG:terminated_at | None | | accessIPv4 | | | accessIPv6 | | | addresses | scigne-net=172.16.19.226 | | config_drive | | | created | 2025-09-11T06:24:39Z | | flavor | m1.small (2) | | hostId | cf41a7ccb0611d6dcc24e54c5983dbe17dda36cf954f5e4625607474 | | id | 367110ac-b05a-4855-884e-e3b00717ab4a | | image | SCIGNE Ubuntu 24.04 x86_64 (3c785ac5-b216-43dc-871b-6643962a2d19) | | key_name | cloudkey | | name | MY_VM_NAME | | progress | 0 | | project_id | 92d2f61945214c8a80d12d696b82426e | | properties | | | security_groups | name='default' | | status | ACTIVE | | updated | 2025-09-11T06: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 machines 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, useful for encrypting a volume and improve 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 ``cloud_init_cfg.txt`` file's content format. And then use this file 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 formatting. However, it is more picky than **cloud-init**, so use its remarks only for information. Build this contextualization file 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 informations 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 addresses are already associated with private IPs 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 an 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 | iphc-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 ubuntu@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 AlmaLinux systems are *ubuntu* and *almalinux* 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 is 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 | +--------------------------------------+---------------+-----------+------+--------------------------------------------+ To create 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 | 2025-09-11T10: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 the ``/dev/vdb`` device. To verify that the disk is correctly associated with the VM, check the content of the ``Status`` column with the following command. If the ``Status`` column has for value *in-use* and the ``Attached to`` column contains the identifier 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 first, 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 ubuntu@my-vm-name:~$ sudo su - root@my-vm-name:~# mkfs -t ext4 /dev/vdb root@my-vm-name:~# mkdir /storage1 root@my-vm-name:~# mount /dev/vdb /storage1 root@my-vm-name:~# df -h /storage1 Filesystem Size Used Avail Use% Mounted on /dev/vdb 8.0G 3.0M 7.8G 1% /storage1 The last command allows 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 formatted. This disk can be moved from one virtual machine to another. in order to do this, you first have to unmount it correctly: .. code-block:: console root@my-vm-name:~# umount /storage1 .. note:: If you have added the reference of your persistent disk in the ``/etc/fstab`` file of your VM, and you have moved 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 persistent disk (to avoid data corruption): .. code-block:: console root@my-vm-name:~# umount /storage1 If you no longer need the data on the persistent disk, you must reset it with random data for confidentiality reasons (this operation can take quite a long time): .. code-block:: console root@my-vm-name:~# dd if=/dev/urandom of=/dev/vdb bs=4M Then, once the data has been effectively deleted, detach and remove the volume with: .. code-block:: console $ openstack server remove volume MY_VM_NAME 58230433-086f-4ff2-99ac-8c3e0f5520c2 $ openstack volume delete 58230433-086f-4ff2-99ac-8c3e0f5520c2 At last, 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 Synchronization -------------------- The access to NTP servers outside the SCIGNE platform is not allowed. If you are using time synchronization 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 synchronization, 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 synchronization, 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 tool 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 - 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 from 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:/storage1/the/destination/path 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 -p /storage1 root@my-vm-name:~# mount -t ext4 /dev/mapper/storage1 /storage1 By default, SSH and ICMP ports are open. If you wish to open other ports, you must apply a security group to your virtual machine. This can be done via the web interface or command line. The current list of ports that can be used is as follows: * 80 * 443 * 1247 * 1248 * 2121 * 2379 * 3306 * 3389 * 4243 * 6443 * 7778 * 8443 * 8800 * 8080 * 8899 * 9000 * 9090 * 9443 * 10000 * 27017 Troubleshooting =============== This section may help you 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 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 | +----------+-------------------------------------------------+ 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 `_; - `Questions about OpenStack usage `_.