CONSIDER DEPRECATING THIS

Purpose

To show how SMPH researchers how to access and use Platform X Linux virtual machines. 

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. To make this easier for researchers the necessary commands you will need to use when in your specific project environment are typed out for you here: Platform X: User Guide - Project-Specific Azure Commands

---

1. Install the required software on your SMPH-provided desktop or laptop. Only do 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!!
7. Log out of Azure Cloud. (see: [Link for document 119974 is unavailable at this time] )

While working in your VM you may need to:

• Restart your VM.
• View your VM status.
• Copy files to or from your storage accounts (usable only from within your VM). See: [Link for document 119996 is unavailable at this time]

Introduction

You will 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 user id.

Once in Azure Cloud, you will use gain access to 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.

Finally, you will log out of Azure Cloud entirely, and can close down your local workstation.

---

Each project has distinct compute resources established, and the particular az commands needed for each project differ as a result.  Please see 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.  See: Platform X: User Guide - Project-Specific Azure Commands

---

Initial Computer Setup

To access the virtual machine (VM) you must use a computer that has been provisioned by an SMPH IT department and is connected to the SMPH VPN. You will only need to perform the following steps once.

Install Required Software

Request your local IT department install 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) 

MacOS

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

Connecting to Azure Cloud

Log into Azure Cloud

See [Link for document 119974 is unavailable at this time]

Set Your Subscription.

See [Link for document 119974 is unavailable at this time]

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 (and you should because it 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 (a reminder that we are showing resources from the Substance Misuse Data Commons project in the examples -- your project may differ slightly. See above.)

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. Resources from the Substance Misuse Data Commons project are shown as an example here. The equivalent command for a different project will vary. See above.

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 Platform X Support (platformx-support@mailplus.wisc.edu) 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. 

---

Important File System Information!

Every VM will have long-term, persistent data storage where you will keep your project work, your personal code, files, etc.  This data storage will be found under /users/ and will be where you will want to keep data that matters to you.  This data is perfectly safe when a VM gets turned off (deallocated), like you would expect.

There will also be other storage attached to the VM that is NOT persistent and does not get saved when the VM gets turned off. This is found under the /mnt/ directory. All data in and under this directory will be lost when the VM is turned off.  There is a prominent "DATALOSS_WARNING_README.txt" file located on the root of /mnt/ as a reminder to users that all data in this directory will be lost when the VM is stopped and deallocated.

The VM's /users/ directory will contain subfolders for each netid authorized to use that vm. It will also have a /users/labusers/ directory where shared data can be stored.  Typically, when copying data to and from your project's storage accounts, that data will be sourced or targeted somewhere under the /users/ folder.

See: [Link for document 119996 is unavailable at this time]

---

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.

F.A.Q.'s

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.

How do I manage the known_hosts.file on my workstation/client?

Azure AD acts as the core authentication platform and a certificate authority to SSH into Linux VM’s deployed within Platform X (leveraging openSSH certificate-based authentication).  In this way users will not need to manage the traditional known_hosts file for SSH key-based authentication.  Once Azure CLI authenticates your user object within Azure AD

Azure AD will manage the OpenSSH certificate-based authentication that is used within Azure based off your user object's authentication within Azure CLI, so SSH authenticate is vastly simplified for end users in this model (reference: Login in to Linux virtual machine in Azure using Azure Active Directory and openSSH certificate-based authentication | Microsoft Docs). The hope is that you will not need to managed the known_hosts file on your client, at least for Platform X resources

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 Linux VM

Document History