Purpose

Describe how to access and use Platform X Linux virtual machines via an SSH tunnel. To log in through the Azure portal reference Platform X: Logging in to Virtual Machines via Azure.

Definitions

[Link for document 119988 is unavailable at this time]

Summary

Project-Specific az commands

Azure commands will require parameters to be included that will differ based on the research environment. 

You can view the specific project commands by logging in with your Platform X account information here: https://controlpanel.platformx.wisc.edu/.

1. Select Project
2. Click on your VM name
3. On the right hand side select List Command Cheatsheet

Overview

Steps for using your Virtual Machine

1. Install software for Programmatic Control on your SMPH-provided desktop or laptop. Complete this step once. 
2. Log into Azure Cloud using your project-specific az login command. (see: [Link for document 119974 is unavailable at this time])
3. Start your VM.
4. Log into your VM via your project-specific az command. 
5. Log off your VM when you are finished for the day.
6. Shut down your VM at the end of the day. Make sure your team isn't using the VM. (see: Platform X: Check Virtual Machine for Active Users)

Other operations

• Restart your VM
• View your VM status

Introduction

Create a connection from your workstation to compute resources within Azure Cloud by using commands that all begin with az. You will log into Azure Cloud with your Azure credentials (e.g. <NetID>@platformx.wisc.edu).

Once in Azure Cloud, you log into your particular linux virtual machine. You will know you are connected to your virtual machine when the prompt in your PowerShell (Windows) or Terminal (Mac) changes.

When you are finished using your VM, you will exit the VM, then after confirming your colleagues are not still using the VM,shut the machine down for the evening.

Each project has distinct compute resources established, and the particular az commands needed for each project differ as a result. Reference the project-specific az commands.

This document will reference the appropriate command by label, e.g., "Connect to the VM" or "Start the VM".  This documentation uses the Substance Misuse Data Commons project as the example, but unless you are in that project group, the command for your project will vary from the text below. Replace the example az commands shown with your particular equivalent command (Platform X: User Guide - Project-Specific Azure Commands).

Initial Computer Setup

To access the virtual machine (VM) you must use a computer that is managed by an approved IT department (ex. SMPH, UW Health) and is connected to the SMPH VPN. You will only need to perform the following steps once.

Install Software for Programmatic Control 

If you would like to have programmatic control of your VM via SSH tunnel, request that your local IT department installs the following applications on your computer.

Windows 10

• • PowerShell (version 7.2 or newer)
  • Azure CLI, aka AzCLI (version 2.31.0 or newer)
  • The SSH extension for the AZCLI (version 1.0.0 or newer) 
  • RDP apps

MacOS

• • Azure CLI, aka AzCLI (version 2.31.0 or newer)
  • The SSH extension for the AZCLI (version 1.0.0 or newer) 
  • RDP apps

Using Your Virtual Machine (VM)

Starting (Powering On) your virtual machine (VM)

Note: You may not need to do this if the VM is already up and running. Issuing this command when the VM is already powered on will do no harm.

Your virtual machine may be in the cloud, but it still needs to be "turned on" to work. If you're turning your VM off at the end of the day (this will save you money) you'll need to turn it back on the next morning. To power on your virtual machine:

1. In PowerShell (Windows) or Terminal (Mac) run your project-specific "Start the VM" az command (reminder this uses an example project - use your own project commands)

az vm start -g rg-submisuse-prod -n vm-submisuse-prod

2. You will see the text "Running..." with a rotating cursor indicating that the start operation is in process, and will look like this:

Figure 11. Starting your VM.

3. Once the VM has completed its boot up process, the command prompt will reappear:

Figure 12. Your VM is now running.

Congratulations! Your VM is now up and running and you may attempt to connect to it using your project-specific az command. You are now incurring the expense of running your VM. A reminder that shutting down your VM when you don't need it (nights, weekends, etc.) is a great way to make the most of Azure Cloud resources.

Connect to your VM

You can connect to your VM with your project-specific command. You must be on the SMPH VPN and successfully logged into Azure Cloud as above.

1. In PowerShell (Windows) or Terminal (Mac) run your project-specific "Connect to your VM" az command. 

az ssh vm -g rg-submisuse-prod -n vm-submisuse-prod

2. Once you've successfully connected to the VM, you should see a welcome message with general information and references about the VM like in figure 7.

Figure 7. VM Welcome Screen.

NOTE: If this is your FIRST login to the VM:

• You will need to be added to the appropriate user groups before being able to fully utilize the VM. Please email submit a Navigator ticket via the Platform X Support Portal to be added.
• The following "authenticity" message may appear on your command line. This is expected. Verify the IP address of the host with what was communicated to you and if it matches type yes and press Enter.

Figure 8. SSH Authenticity Challenge.

Disconnecting from your VM

To leave your VM and exit your ssh session, run the following command in your PowerShell (Windows) or Terminal (Mac):

exit

Your VM session in your shell/terminal will show something like this:

Figure 9. Exiting your VM.

Note that your prompt, while in the VM, will show your NetID and the name of the project VM.  When you exit your VM, your prompt will return to that you normally see on your workstation or laptop.

Stopping (Powering Off) your VM

Turning your VM off when you aren't using it saves money and energy, so it is a good thing to do. Azure Cloud makes this easy to do, but it does use some jargon in the command.  A VM can be "stopped" or it can be "deallocated."  If your VM is in either of these states (that you could see by "Viewing your VM's Status") you won't be able to use your VM. 

Turning off your VM does NOT mean you will lose your data. All data stored in the usual places will be there when you come back. You're simply turning it off to save some money. 

"Stopped" doesn't mean what you would probably think it would mean in Azure. The term for "my VM is off and I am not paying for it any longer" is deallocated.  There are separate commands for deallocate and stop in Azure, but you only ever need to use deallocate. If you want to learn more, see the FAQ below or az documentation. 

1. In PowerShell (Windows) or Terminal (Mac) run your project-specific "Stop the VM" az command to power off the virtual machine and deallocate system resources. There is one caveat.

az vm deallocate -g rg-submisuse-prod -n vm-submisuse-prod

2. You will see the text "Running..." (with a rotating cursor indicating an operation is in progress) in the command line while the VM is deallocated.

Figure 15. Deallocating your VM.

3. Once the VM is deallocated, the command prompt will reappear.

Figure 16. Your VM is deallocated.

As soon as deallocation is complete, your VM is off and you are no longer incurring VM usage costs. 

View your VM's status

If you try to connect and the attempt fails, the VM may not be powered on.  You can check the status of your VM with your project-specific "View VM Status" command. It may say "stopped" or "deallocated" -- and that means it is not running. You'll have to start your VM in order to connect.

az vm get-instance-view -n vm-submisuse-prod -g rg-submisuse-prod --query instanceView.statuses[1] --output table

Figure 10. Viewing your VM's status.

Restart your VM

To "reboot" your VM:

1. Use your project-specific az commands to "Restart the VM". Note that the command is "restart", but in other ways resembles the start command.

az vm restart -g rg-submisuse-prod -n vm-submisuse-prod

Figure 13. Restarting your VM.

Figure 14. Your VM has restarted.

Virtual Machine States

What is the difference between an Azure VM’s ‘Stopped’ and ‘Deallocated’ state?

If in doubt, use "Deallocate"; this stops the VM and removes it from hardware so you save money. Your data is stored safely on SSD hard drives and will be there when you turn your VM back on. "Stop" is a real command, but it doesn't do what you want it to do: your machine won't be reachable, but you will still be paying the hourly fee. Use "Deallocate."

Stopped State

When you are logged in to the operating system of an Azure VM, you can issue a command to shut down the server. This will kick you out of the OS and stop all processes but will maintain the allocated hardware (including the IP addresses currently assigned). If you find the VM in the Azure console, you’ll see the state listed as “Stopped”. The biggest thing you need to know about this state is that you are still being charged by the hour for this instance.

Deallocated State

The other way to stop your virtual machine is through Azure itself, whether that’s through the console, PowerShell, or the Azure CLI. When you stop a VM through Azure, rather than through the OS, it goes into a “Stopped (deallocated)” state. This means that any non-static public IPs will be released, but you’ll also stop paying for the VM’s compute costs. This is a great way to save money on your Azure costs when you don’t need those VMs running.

Additional Help

If you need additional help, please email Platform X Support Portal

Document Template

[Link for document 119690 is unavailable at this time]

Related Controlled Documents

[Link for document 119974 is unavailable at this time]

Platform X: User Guide - Accessing and Using a Virtual Machine via SSH

Document History