======================================================= Computer Science OpenStack cluster and Virtual Machines ======================================================= We provide virtual machines (VMs) as needed for students registered for courses in Computer Science. All virtual machines are hosted in an OpenStack cluster located in the basement of the Davis Marksbury Building. .. warning:: On 2020/10/01, the CS department changed host keys to strengthen security. For more information see `SSH Errors `_. You will probably see warnings from your client, this is expected and the SSH Errors document will show you how to resolve the problem. .. attention:: The **CS OpenStack Cluster** is on a private **IPv4** network. If you are on a external network you will need to connect to the `Campus VPN `_ first. If you are connected to a campus network like `Eduroam `_ you can connect directly to the `OpenStack Dashboard `_ or to your VM. .. note:: While you are on campus, don't connect from network ``UK-Guest``, ssh access is not allowed from it. Also, don't use **wifiHelp** to connect to your `VM`, please use **eduroam** Wifi Network. .. note:: If you are on eduroam and are unable to access it, there is a good chance you are connected using credentials from another institution. Remove/delete the connection and reconnect with your ``LinkBlue`` credentials. .. important:: Please read the section titled :ref:`uk-nf-edge` when connecting from a external network to avoid connection timeouts. Index ----- - :ref:`dashboard` - :ref:`connecting` - :ref:`fw` - :ref:`uk-nf-edge` .. _dashboard: OpenStack Dashboard ------------------- .. note:: Please **do not** use your **username@uky.edu** when login on the ``OpenStack Dashboard``, **just the username part**, For example, if your **linkbue ID** username is **pepe223**, use that instead of **pepe223@uky.edu** You can manage your VM through the OpenStack dashboard. The dashboard is helpful when the VM is non-responsive and needs to be forcefully rebooted or for configuring the network firewall. However, the most efficient method to connect and use your ``VM`` is connecting using the instructions detailed in :ref:`con-vm`. Accessing the dashboard +++++++++++++++++++++++ You can access the dashboard by going to the `OpenStack Dashboard `_. Enter your LinkBlue credentials ``without`` the ``@uky.edu`` for authentication. .. image:: _images/loginOpenStack.png :scale: 70% :align: center :alt: login page OpenStack calls VMs "instances" and accounts "projects". Your VM and project, as well as your login account on the VM, are all named after your LinkBlue ID. Upon logging in you should see an overview of your account and, at the bottom, your LinkBlue ID as a hyperlink. This is your VM instance. Click the link to open the management page for the VM. Click on the following picture to see a more detailed view of what you will see once you click on the **Instances** menu on the left. .. image:: _images/instanceOverview.png :scale: 65% :align: center :alt: Instance Overview When you click on the **Instance Name** of your VM, the tabs available give details of the VM as well as its firewall settings (called "Security Groups"), logs, and a console. Use the console only when NoMachine (see below) is not available, because NoMachine provides far better performance for a graphical desktop. .. note:: If the console is not responding to keyboard input, either (1) click the blue/grey status bar at the top of the console, or (2) click the "Click here to show only console" message, or (3) refresh the web page in your browser. .. _con-vm: .. _connecting: Connecting to your Virtual Machine ---------------------------------- .. note:: We create both **Linux** and **Windows** VMs. These VMs have a ``DNS`` entry setup which you should use to connect to your VM. For **Linux VMs** the DNS hostname is **linkblue.cs.uky.edu**, for **Windows VMs** the DNS address is **linkblue-win.cs.uky.edu**. However, in the case of **Windows**, **linkblue-win.ad.uky.edu** should also work since the machine is integrated with UK Campus' Authentication Directory. In both types of `VMs` you can use your ``LinkBlue username`` to login. .. attention:: When restarting your **Linux** VM please use ``sudo reboot`` via **ssh** whenever possible. If this is not possible then use the `OpenStack Dashboard`. There are different ways to connect to your VM. The method you select will depend on what you need to do on the machine, use the following index to select the most appropiate option for you: - :ref:`nomachine` - :ref:`filezilla` - :ref:`cn-putty` - :ref:`bitvise` - :ref:`cli-ssh` - :ref:`other-con-methods` Once your ``VM`` is created and it's running use the following methods to connect. The next two sections will detail how to connect using a graphical client and a ``SSHv2`` client. If you want to explore alternative methods to connect please see the section :ref:`other-con-methods` .. _nomachine: NoMachine client (Windows/Linux/Mac) ++++++++++++++++++++++++++++++++++++ NoMachine provides a great experience when connecting to your VM's Desktop. You can download it from `NoMachine Downloads `_. There are versions for **Windows**, **Mac** and **Linux**. Your VM already has NoMachine installed, and it's accepting connections, for this reason what you need is the client part to be able to connect. Once you have installed NoMachine on your own computer (your laptop, for instance), follow the images below for guidance or check this `Video `_ for a quick review of the process. Click ````. .. image:: _images/nm1.png :scale: 50% :align: center :alt: Instance Overview Make sure the protocol is 'NX', then click :guilabel:`Continue`. .. image:: _images/nm2.png :scale: 50% :align: center :alt: Instance Overview Enter the name of your VM (its DNS address) on the text field in the next screen. Choose password authentication. .. image:: _images/nm4.png :scale: 50% :align: center :alt: Instance Overview Most users do not need to configure a HTTP proxy. .. image:: _images/nm5.png :scale: 50% :align: center :alt: Instance Overview Enter your LinkBlue credentials. .. image:: _images/nm6.png :scale: 50% :align: center :alt: Instance Overview Configure the settings. .. image:: _images/nm7.png :scale: 50% :align: center :alt: Instance Overview .. note:: Display resolution can have a dramatic affect on performance. 1280x800 is a good initial setting. Useful NoMachine Features +++++++++++++++++++++++++ This subsection has some examples of what you can do with nomachine. If you need to copy information between the VM and your local machine this will help. For the best experience please play these videos on a computer or laptop. - Connect your USB stick to the local machine, then `Export your USB stick to your VM `_ (read/write). Here you could also export your local disk to the VM. - `Export your VM's disk to your local machine `_ (read/write on your home directory) Your VM is fully connected, for example if you need to submit information to **Canvas** you can connect with **NoMachine** and then open the web browser and connect to the site to do the required tasks. Since you have full control of your VM you can opt for a different browser (the default is Firefox) like Google Chrome/Chromium. .. _cli-ssh: Command Line SSH client +++++++++++++++++++++++ If your VM runs Linux, you can connect to it from another Linux/Unix/Mac machine via SSH (Secure Shell). The connection command looks like this: .. code-block:: shell $ ssh linkblueid@linkblueid.cs.uky.edu .. note:: If you get a **Warning** like the following: .. code-block:: console @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: POSSIBLE DNS SPOOFING DETECTED! @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ The ECDSA host key for linkblue.cs.uky.edu has changed, and the key for the corresponding IP address 172.31.112.111 is unknown. This could either mean that ... lines removed here ... Please contact your system administrator. Add correct host key in /Users/username/.ssh/known_hosts to get rid of this message. Offending ECDSA key in /Users/username/.ssh/known_hosts:1 ECDSA host key for linkblue.cs.uky.edu has changed and you have requested strict checking. Host key verification failed. This is normally due to the fact that your VM was recreated at the start of the semester, if this happens the first time you are connecting to it then it's safe to edit the file (in this case) /Users/username/.ssh/known_hosts and as can be seen line ``1`` (**Offending ECDSA key in /Users/username/.ssh/known_hosts:1**) is the line we need to remove from that text file, in this way our ssh client will not fail the check and create a new entry for your VM. SSH has the advantages of speed and accessibility, but it lacks a graphical user interface. If you are connecting from a machine running an X server able to receive forwarded X Windows connections over SSH, add `-Y` as a flag to the `ssh` command. Now you can run graphical applications on your VM and see them on your own machine. This setting and many more can be configured in an ssh configuration file; an example is included below. File name: *~/.ssh/config* .. code-block:: console Host linkblueid.cs.uky.edu KexAlgorithms +diffie-hellman-group1-sha1 Ciphers aes256-ctr,aes256-cbc ForwardX11Trusted yes In the example above, the first line specifies the host you are making a connection to. The lines immediately following are the configuration options specific to that host. See the man page for `ssh_config(5)` for more information. **Windows PowerShell SSH client** Recent versions of Windows PowerShell™ have OpenSSH available since Windows 10's Fall Creators Update (April 2018). The syntax is exactly the same as the Linux/Unix/Mac example from above. Open a PowerShell session and run the command:: ssh linkblueid@linkblueid.cs.uky.edu .. figure:: _images/powershell1.png :scale: 60% :alt: ssh example in powershell Example of an SSH session running in PowerShell This feature can be added to any version of Windows 10. Contact help@cs.uky.edu for assistance adding this feature if it is not included with your version of Windows. .. _filezilla: Filezilla (Windows/Linux/Mac) +++++++++++++++++++++++++++++ **Filezilla** is an excellent FTP client with support for **SFTP** (SSH File Transfer Protocol). In it's most basic version, it's free to use. This software allows you to transfer files easily between your machine and your VM, among other operations. Go to `Filezilla Downloads `_ and get the ``FileZilla Cient``. If you are presented with three options, select one that is not the **Pro** version. If the installation wizard asks if you want additional software, just unselect the checkbox and continue. Once you have installed **FileZilla**, proceed to open it. You will see a window like the following: .. image:: _images/fz00.png :align: center :alt: login page Go to ``File/Site Manager`` and use a configuration similar to the one in the next picture. Insert your username (like `abc123`) and the DNS name for your VM (like `abc123.cs.uky.edu`); then click ``OK``. .. image:: _images/fz01.png :align: center :alt: login page When you connect, you will see the following message: .. image:: _images/fz02.png :align: center :alt: login page To connect, you can go to the ``Site Manager`` and select your session, or you can simply click the arrow and select your session name, as in the following picture: .. image:: _images/fz03.png :align: center :alt: login page And when connected, you will see the directory contents of your VM, showing that your session is established: .. image:: _images/fz04.png :align: center :alt: login page .. _cn-putty: PuTTY (Windows) +++++++++++++++ **PuTTY** lets you to establish an ``SSHv2`` connection to your VM. To set up a Putty session, you can `click here `_ and scroll down to the section titled **PuTTY session setup and public key authentication**. You don't need to set up the public authentication part if you don't want (skip the first image and paragraph); just create the session using your username (like `abc123`) and the name of the remote host (your VM's name, such as `abc123.cs.uky.edu`, or a CS Server's name if you need/have access) and save the new session as detailed in the document. .. _bitvise: Bitvise SSH Client (Windows) ++++++++++++++++++++++++++++ This is an **SSH** client and also a file-transfer program. Follow these instructions to install the software, configure a profile and establish a connection. Download the software from `Bitvise SSH Client `_. After opening the program for the first time you will see a window like this: .. image:: _images/bv00.png :align: center :alt: login page The first step is to make a profile and save it. Click **New Profile** in the left panel and save the file with the profile information in a convenient folder. .. image:: _images/bv01.png :align: center :alt: login page In the **Server** section, enter your VM's hostname (like `abc123.cs.uky.edu`) and the port (**22**). Enter your username (like `abc123`) in the **Authentication** section. For **initial method**, select **password**, and leave everything else alone. Then click **Login**. You will see a window like the following: .. image:: _images/bv02.png :align: center :alt: login page Type your password. After the connection is established, you will see a terminal window and a file-transfer window, which you can use to interact with your **VM**. .. image:: _images/bv03.png :align: center :alt: login page By default, **Bitvise** sends keep-alive packets every 20 seconds to the server. This feature prevents your connection from timing out. .. _other-con-methods: Other Connection Methods ++++++++++++++++++++++++ Newer versions of Windows have both `ssh` and `scp` installed and accessible from a command window. On a Mac, you might want to use the terminal app along with `XQuartz `_. On Windows, you might want to use `Xming `_ or `Cygwin/X `_ or `MobaXterm `_. .. _fw: .. _firewall: OpenStack Network Firewall -------------------------- The default firewall settings for your VM block all ports except for the ones used by the `SSH` server and the `NoMachine` server. Although you may adjust your VM's firewall settings, please contact `help@cs.uky.edu `_ for assistance. Open ports can be a security risk. Creating Firewall rules on your VM ++++++++++++++++++++++++++++++++++ One of the reasons to create a new firewall rule is to allow ingress traffic directed to your `VM` to a specific port. Let's say that you need to open port ``1280/tcp`` on your `VM` because you are working on an application that needs to bind to a specific port and you need to test it, etc. .. attention:: Creating a firewall rule could lead to unauthorized access to non-secured applications that are listening on a socket. Make sure you don't expose any sensitive or private information from your application (the one listening on the network port) The Computer Science OpenStack Cluster's networking runs using a Private IPv4 subnet, this means that external network access (Internet) it's not allowed directly to the VMs, and this protects the VMs further from internet attacks, etc., however the VMs are still accessible all over campus so it's always good practice to exercise care on services listening on sockets. By default any incoming connection to most ports are not allowed, to create a rule (using the port 1280/tcp as an example) to allow this traffic execute the following steps: - Login on the `OpenStack Dashboard `_ - On the `left`, look for the menu ``Network`` and click on it, then click on ``Security Groups``. - You will see your `Security Group(s)`. Normally there is only one that is called ``default``. You need to select the checkbox on the left of it and click on ``Manage Rules`` on the right to see all your security rules (firewall rules) that are applied for your `VM` from the OpenStack's network functions. - To create a rule to allow incoming traffic to port ``1280/tcp`` do the following. - Click on ``Add Rule`` - Under ``Rule *`` Select the `protocol`, the next example assume you use the option ``Custom TCP Rule`` - Put a description (can be anything that describes the purpose of your rule) - Select the ``Direction``, here we need to allow incoming traffic to port ``1280`` so we select ``Ingress`` - By default ``Port`` is selected and below that we must specify which port is the destination, in this case we write ``1280`` in the text field. - On ``Remote`` leave it as ``CIRD``, in the text field below leave it as ``0.0.0.0/0`` **if** you want to allow traffic from `all` remote IP addresses. Otherwise, you will neeed to specify the remote address, something like ``172.31.49.87/32`` to specify a single `IP` address or ``172.31.49.128/25`` to specify a subnet, for example. - EtherType is by default at `IPv4` since the Computer Science OpenStack cluster don't use `IPv6`. - Click the ``Add`` button to submit the rule and it will take effect inmediately. Proceed to your `VM` for further testing. Your `VM` should now receive incoming traffic if the rule was correctly specified. All other options to create rules are very similar, make sure you exercise care when creating firewall rules. .. _uk-nf-edge: .. _uk-edge: UK Firewall and External connections ------------------------------------ The **UK** edge Firewall timeout idle connections, this means that if you are connecting from a network outside **UK** and your session is idle for a few minutes this connection will drop, causing a disconnection. To make sure your external connections won't timeout follow these steps. For Linux/Unix/Mac ++++++++++++++++++ If you prefer to connect using the command line use the following configuration. Edit the file ``~/.ssh/config`` and add the following: .. code-block:: shell Host * ServerAliveInterval 60 ServerAliveCountMax 3 For Windows/Unix/Mac (PuTTY) ++++++++++++++++++++++++++++ If you are using **PuTTY** you should have a session saved and you use this session to connect to the server(s). Click your session name (if you have more than one please repeat these steps on all your UK sessions) and click ``Load``. On the left panel, scroll down and click **Connection**, in the right side of the Window look at the top, it will say ``Seconds between keepalives``, it's by default on **0** which is disabled. Write a reasonable number of seconds, **60** seems to be a good number, in this way the ssh client will send keep alives packets to the server keeping the connection up. .. image:: _images/putty-keepal.png :scale: 100% :align: center :alt: PuTTY keep alive To save the new configuration, on the left panel scroll up to ``Session`` and click the session you modified, then click ``Save``. The next time you use the session to ssh into a remote host this keep alive configuration will prevent connection timeouts by sending periodic (based on the number of seconds set) ``SSH NULL packets`` to the server, in this way the UK firewall will refresh the timeout timer for your connection and it will not be droppped at the edge of the ingress network.