Training Handout¶

1. Introduction to ScienceCloud¶

2. Hands-on Part¶

Get in touch with Science IT.
Your account has been activated?
- Open a web browser and go to https://cloud.s3it.uzh.ch (javascript and cookies must be enabled).
- Log in with your UZH webpass (the usual shortname and password).

Note

If you have signed up for the ScienceCloud Base training but are not part of any other ScienceCloud tenants yet, the credentials will not work because your account is not yet active. At the beginning of the training session, you will be added to the training project thus activating the account.

2.2. Get access to your instances¶

An SSH key is required to log into your newly created instances: SSH keys have several advantages over regular username/password authentication, but the main reason we use those is that they are really difficult to crack with a brute force approach. SSH keys are made up of two components system: a private key and a public key. The public key resides on the computer/instance you would like to connect to. The private key stays on your own computer. A SSH connection can only be established between a computer having the private key and a computer/instance having the corresponding public key. It's therefore important to never share your private key file.

Create a key on Linux/Mac/Windows10¶

```
ssh-keygen -t rsa -b 4096
```

The above command will prompt you to set a password to unlock the key. If you accept the default options offerred by ssh-keygen it subsequently generates two files named **id\_rsa.pub** and **id\_rsa** and saves them under `/home/<user>/.ssh/`

!!! note
    Ubuntu 16.04 does not support _DSA_ cipher suite for generating the key pair.

!!! note
    If invoking `ssh` from the Windows10 terminal leads to an error please refer to [this quick guide](https://www.howtogeek.com/336775/how-to-enable-and-use-windows-10s-built-in-ssh-commands/) or to [Microsoft documentation](https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_overview) or install an external application providing a ssh client and a key generator (see "Create a keypair on older Windows")

These files can be confirmed / displayed using
```
ls .ssh
```
which should show something similar to `id_rsa id_rsa.pub known_hosts`.

To display the content of the id\_rsa.pub file, which is the public half of your key, you can issue:

```
cat ~/.ssh/id_rsa.pub
```
which displays something like

`ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC6D3RuR2j6BvVy6I3Q1amScKYFs+qmI5D37bS9/vgdUvbQx0CnkyuAsx7UpPltXTz3+jkIcGJQqZJUZV1v00/y4iiaHTzp/PxRMT8bzIMw9cOnfZxhSQ1ekUr+wTfT8e5Hs+NabP4bfni/htE7LBk+Mrywgb5I4Mr3fKmKGH4DJzh2YUCt6oC/TivxuKYVrQPEy0BznFuwrHbpQoT6swUa3GaB5nIi/nPyHd6E/EIZ1be+U2y7+efmY9JlQKLaJg6iYumSbibLBQ8qw+ohHbcSBhDUmEiOosuYtvv8L8r3Bvj+2zyFU5DdArSvIPFQbma3/s9oqfYctcqGzVRmFeeJ`

Once the generation process is complete there are a few extra steps that needs to be followed:

1. Log in to https://cloud.s3it.uzh.ch, choose Access & Security.
2. Go to Keypairs tab, which shows the key pairs that are available for this project.
3. Select Import Keypair and choose the Keypair Name.
4. Paste the content of your SSH public key in the Public Key text section

Create a keypair on older Windows¶

Latest/updated versions of windows have the ssh client already available in the command line. If the above commands do not work, you can try to install the relevant update to enable ssh in the command prompt or use a third party application.

The first option can be achieved following the info on this quick guide or to Microsoft documentation , while the following steps need to be followed in order to use the third party application "PuTTY":

1. Download PuTTYgen from this link.
2. Open the PuTTYgen program.
3. For Type of key to generate, select SSH-2 RSA.
4. Click the Generate button.
5. Move your mouse in the area below the progress bar. When the progress bar is full, PuTTYgen generates your key pair.
6. Type a passphrase in the Key passphrase field. Type the same passphrase in the Confirm passphrase field. You can use a key without a passphrase, but this is not recommended.
7. Click the Save private key button to save the private key. You must save the private key.
8. Right-click in the text field labeled Public key for pasting into OpenSSH authorized_keys file and choose Select All and Copy.
9. Then:
  1. Log in to https://cloud.s3it.uzh.ch, choose Access & Security.
  2. Keypairs tab, which shows the key pairs that are available for this project.
  3. Import Keypair.
  4. Choose the Keypair Name.
  5. Paste in the Public Key text section the content of your ssh public key.

2.3. Launch an instance¶

Log in to https://cloud.s3it.uzh.ch.
On the Project tab, open the Compute tab and click Images category.
The dashboard shows three different sets of Images available: Project, Shared With Me, Public.
For the scope of the training, go to Public and look for the latest Ubuntu. You can spot it as the name starts with '***', has the higher distribution version and the latest build date: i.e. " ***Ubuntu 22.04 (2023-11-06) ". A complete list of the supported public images can be found at: Supported Images.
Click Launch Instance.
In the Launch Instance dialog box, specify the following values:
1. Instance Name: Assign a name to the virtual machine.
2. Instance Count: To launch multiple instances, enter a value greater than 1. (The default is 1.)
3. Flavor: Specify the size of the instance to launch. Check the user guide paragraph on flavors for detailed information.
4. Networks: To add a network to the instance, click the "+" of uzh-only Network field.
5. Key Pair: Check that your key pair is added to the instance.
Congratulation you've just launched your first instance on ScienceCloud!

Tip

If your instance does not launch correctly and ends up in an "error" status, you might want to check if the flavor is available on the ScienceCloud flavor availability report (requires internal network or VPN). If the flavor is not available, delete the error vm and try with an available flavor, otherwise contact us.

On Linux/Mac/Windows10 run SSH in terminal¶

The long way:
```
ssh -i ~/.ssh/id_rsa ubuntu@<your-instance-ip-address>
```
If you didn't use the default keypair name, then replace "id\_rsa" with the path of the private key.

One way to simplify ssh connections that are often used is to add the key to the ssh-agent.

To avoid inserting the passphrase of the private key each time you open a new connection, run:
```
ssh-add <path-to-id_rsa>
```
Obtain the instance IP address from the dashboard and insert it here:
```
ssh ubuntu@<your-instance-ip-address>
```
!!! note
    **Regarding usernames**
    The convention used for usernames used by the public images on ScienceCloud is straightforward: each distribution has a predefined user with the same name. I.e., every flavor of Ubuntu has username "ubuntu", Debian distros have "debian", CentOS have "centos" and so on.
    See [here](/cloud/supported_images) for information on what user to use with each image.

On older Windows¶

1.  Get the putty.exe from [here](http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html) and run it.
2.  Host Name: username@<instance-IP-address\> (The username will be `ubuntu` if you've chosen Ubuntu for your instance)
3.  Connection type: select SSH.
4.  In the Category pane, expand Connection, expand SSH, and then select Auth.
    1.  Click Browse.

    2.  Select your private key`.ppk` file that you generated for your key pair, and then click Open.

    3.  (Optional) If you plan to start this session again later, you can save the session information for future use. Select Session in the Category tree, enter a name for the session in Saved Sessions, and then clickSave.

    4.  Pressing the ‘Open’ button PuTTY will begin trying to connect you to the instance.
    5.  If this is the first time you connect to the instance, PuTTY displays a security alert box, click "Yes" to confirm you trust the host.

2.5. Install packages on a Debian/Ubuntu instance¶

Steps to install a new software package or upgrade existing software packages on a Debian/Ubuntu system.

To update the list of packages known by your system, you can run:
```
sudo apt-get update
```
To upgrade all the packages on your system (without installing extra packages or removing packages), run:
```
sudo apt-get upgrade
```
Hint

The upgrade process will eventually stop requiring some input, for example asking if keeping or replacing a configuration file changed locally on the machine. In this case the right choice would be to keep the locally modified file, which is the default. In general is correct and safe to always choose the default option when prompted. This behavior can be obtained adding the "-y" option to the upgrade command.

To install a package and all its dependencies on Ubuntu,

# If you are not sure about the package name or version, try to run a quick search on your repository by:
apt-cache search package_name
# Then install e.g. r-base by:
sudo apt-get install r-base

To remove the package from your system, run:
```
sudo apt-get remove r-base
```

2.6. Attach a volume to the Instance¶

Create a volume¶

1.  Log in to [https://cloud.s3it.uzh.ch](https://cloud.s3it.uzh.ch/).

2.  On the _Project_ tab, open the _Compute_ tab and click _Volumes_ category.

3.  _Volumes_ tab.
4.  Click Create Volume.
5.  Specify _Volume name_ and _Volume Size._
6.  Press Create Volume.

Attach Volume¶

1. On Volumes tab, select your volume.
2. From drop-down Edit volume list, select Manage attachments.
3. From Attach to instance list, choose the instance you wish to attach the volume to.
4. Press Attach Volume.

Format and mount the volume¶

Once a volume is attached to a VM it becomes visible to the operating system but it is in a blank state. To make use of it, you need to identify  and format it. Follow these steps to do so:

!!! danger
        ⚠️ The format operation (step b) should be performed only **once** when the volume is attached for the ***first*** time. Otherwise, ***the volume's data will be completely wiped!***

Get the name of the block device your volume is associated to: select the Volume tab on the ScienceCloud GUI and look for entries like /dev/vd<LETTER> or /dev/sd<LETTER> under the Attached To field – where <LETTER> is a lowercase latin letter like a, b, etc. You can also look into the list of all block devices attached to the instance by running the following command:
```
lsblk
```
1. Format your new disk into ext4 (recommended FS). See the "Danger" note above before running this command, and change the device name accordingly.
```
sudo mkfs.ext4 /dev/vd<LETTER>
```
2. Mount it on your file system
```
sudo mount /dev/vd<LETTER> /mnt
```
3. Check if it is mounted correctly (there should be a line starting with /dev/sd<LETTER> or /dev/vd<LETTER>)
```
df -h
```
4. Set the ownership of mounted volume to allow ubuntu user for read/write
```
sudo chown -R ubuntu:ubuntu /mnt 
```

2.7. Copy data to your instance (and back)¶

On Linux/Mac/Windows10¶

Open a terminal on your machine and use _["scp"](https://manpages.ubuntu.com/manpages/trusty/en/man1/scp.1.html)_.
!!! note
    For both upload and download you have to use scp on your local machine.
Upload:
    ```
    # Copy the file "foo.txt" from the localhost current directory to the /home/ubuntu/data directory (must exist)
    scp foo.txt ubuntu@<your-instance-ip-address>:data/
    ```
Download:
    ```
    # Copy the file "foo.txt" from the instance /home/ubuntu/data directory to the localhost current directory 
    scp ubuntu@<your-instance-ip-address>:data/foo.txt ./
    ```
!!! tip
    You might need to add the "-i PATH_TO_YOUR_PRIVATE_KEY" option if you have your key saved in a non-standard location and you have not added it yet with "ssh-add".

Using Filezilla software¶

1.  Download Filezilla from [here](https://filezilla-project.org/download.php?show_all=1) and install it.
2.  From File menu select _Site Manager_. You can also press Ctrl+S or Command+S.
3.  On right panel, select _New Site._
4.  On left panel specify the Host: instance IP address.
5.  Port: Only if it differs from the standards.
6.  Protocol: Select SFTP.
7.  Logon Type: choose Key file.
8.  User: The user ID to use when connecting (e.g., ubuntu).
9.  Key file: Browse and select your private key file.
10.  Login using _Connect button._
11.  Verify the host key fingerprints.
12.  Drag & drop files from your pc to the instance.

Note: If your private key is in .pem format, a new message will pop up to convert your key into .ppk which is supported by Filezilla.

Warning

⚠️ Due to reported cases of malware being bundled with FileZilla software installers, only use the link above for downloading and installing FileZilla. Specifically: do not install FileZilla from an installer that contains the word "bundle" in its name.

2.8. Snapshot¶

Snapshots are a feature that allows users to capture the running instance setup and save it without the need to pause or shutdown it. These snapshots are disk-only snapshots.

Create a snapshot¶

1.  Log in to [https://cloud.s3it.uzh.ch](https://cloud.s3it.uzh.ch/).
2.  On the _Project_ tab, open the _Compute_ tab and click _Instances_ category.
3.  Select the instance you want to take a snapshot of  
4.  recommended: shut off the instance if possible (via the dropdown action menu)
5.  Click on _Create Snapshot_
6.  Snapshot Name: Give the name to your snapshot
7.  Press _Create Snapshot_
8.  New snapshot is  displayed in the _Images_ category

Fit-for-a-purpose-snapshots/images: If you would like to have several pre-configured snapshots or images (i.e. VMs ready for a certain purpose), we encourage you to briefly contact us. We frequently have/had similar cases and may be able to simplify your task.

2.9. Protect your instance¶

You can prevent accidental instance(s) deletion by "locking" your instance. The relevant option can be found in the dropdown menu right next to your instance name in the Instances page.

Note: If you lock an instance no actions are possible on it. The error messages you will receive when trying are really generic so do remember which instance you lock or try to unlock them from that same menu in case you notice some inexplicable behaviour.

2.10 Access specific ports on your VM¶

By default the only incoming connections allowed to your VM are via SSH. If you need to access different ports or services running on your VM like a webserver (i.e. open ports 80 and possibly 443) you need to follow these steps:

Create security group:
1. Log in to https://cloud.s3it.uzh.ch
2. On the Project tab, open the Compute tab and click Access & Security category.
3. Security Groups tab.
4. Click Create Security Group.
5. Choose the Security Group Name, hit Create.
6. Select Manage rules of your group.
7. Add rule.
8. Enter for example port 80 (http)
Apply new security group to a running virtual machine:
1. Log in to https://cloud.s3it.uzh.ch
2. On the Instances tab, open the drop down menu next to your virtual machine and select Edit Security Group
3. Enable the newly created security group by clicking on the + sign next to the security group name
  Note: there is no reason to remove the default security group from your instance but if you decide to do so make sure you have all the rules you need in the newly created one.

3.0. Further topics¶

You can refer to the ScienceCloud User Guide for the further topics such as Associating the floating IP.

To get additional support to ScienceCloud, you can contact Science IT.