Deploy ASP.NET Core on Linux: A Step-by-Step Azure Virtual Machine Guide

Table of Contents

This guide is specifically tailored for users who may not have extensive experience with Linux environments. It aims to provide a comprehensive overview of setting up a Linux virtual machine on Microsoft Azure, which will serve as the foundation for deploying ASP.NET Core applications. We will cover the essential steps required to get your Linux environment ready for subsequent training modules focusing on .NET Core deployments.

The primary objectives of this section include learning how to provision a Linux virtual machine within the Azure cloud platform. While this step is crucial for newcomers, experienced users who already possess a suitable Linux environment are welcome to bypass this initial setup phase. Following the virtual machine creation, the guide will detail the process of establishing a secure connection to this Linux instance from a Windows-based computer, which is a common scenario for developers.

Furthermore, this part will introduce fundamental Linux command-line operations essential for managing files, directories, and executing commands with elevated privileges. It will also touch upon the use of package managers, which are vital tools for installing and maintaining software on Linux systems. For optimal compatibility and to ensure that all subsequent lab exercises function correctly, it is strongly recommended to utilize an Ubuntu 18.04 LTS distribution, as this specific version was used during the development and testing of these training materials.

This initial section, Part 1.1, is structured into two main segments. The first segment walks you through the process of creating the Linux virtual machine in Windows Azure. The second segment provides detailed instructions on how to connect to your newly created Linux virtual machine, offering two distinct methods for connection based on the tools available on your Windows machine.

If you are already comfortable navigating and working within a Linux environment, feel free to skip this introductory section. You can proceed directly to Part 1.2, which delves into Linux special directories, understanding elevated user privileges, and working with package managers, building upon the foundational knowledge assumed from this part.

Create a Linux Virtual Machine in Windows Azure¶

Choosing the right Linux distribution is the first important decision you’ll make when setting up your virtual machine. Linux operating systems come in various forms, often referred to as “distros,” each with its own nuances and package management systems. While there are many similarities across distributions, particularly in core commands, the method for installing software can differ based on the package manager used. However, the fundamental steps for setting up a virtual machine in Azure generally remain consistent regardless of the chosen distribution.

The process for provisioning a Linux virtual machine through the Azure portal is comprehensively documented by Microsoft. A detailed walkthrough is provided in the official documentation, specifically in the article titled ‘QuickStart: Create a Linux virtual machine in the Azure portal’. This guide will not replicate every single click and setting described in that quickstart, as the linked resource offers clear and precise instructions readily available. However, it is important to emphasize a few critical configurations and decisions you will face during the creation process that are particularly relevant to this training.

The quickstart guide linked from the official documentation also covers connecting to the VM and optionally installing the Nginx web server. While you are free to follow those steps, installing Nginx is not strictly necessary at this stage. We will cover the installation and configuration of Nginx, which is a popular web server used for hosting ASP.NET Core applications, in detail in a later part of this training series. For now, focus solely on creating the virtual machine itself with the correct basic settings.

Authentication¶

One of the most significant decisions during the virtual machine creation process in Azure is selecting the authentication method for administrator access. Azure provides two primary options for securing your Linux VM login: using a password or using an SSH public key. While password authentication is simpler to configure initially and is acceptable for the context of this training, it is strongly recommended to opt for the SSH public key method.

SSH public key authentication offers significantly enhanced security compared to traditional password-based logins. It relies on a cryptographic key pair: a public key resides on the server (your Azure VM), and a corresponding private key remains securely on your local computer. When you attempt to connect, the server challenges your client, and your client proves its identity by using the private key to sign a message that the server can verify using the public key. This handshake is far less susceptible to brute-force attacks than guessing a password. For the purposes of this guide and as a general security best practice, we will assume you are using SSH public key authentication.

Azure simplifies the process of using SSH keys by offering to generate a new key pair for you directly within the virtual machine creation workflow. This feature allows you to automatically create both the public and private keys without needing external tools beforehand. You will be prompted to save the generated private key file to your local machine, which you will then use whenever you connect to the VM. This process streamlines the setup and ensures you have the necessary components readily available for secure access.

When configuring the administrator account during VM creation, explicitly select the SSH public key option under the authentication type. Furthermore, choose the Generate new key pair option provided by Azure. This action triggers the automatic creation and prompt to download your private key file. For the Username field, select a descriptive and memorable name; this will be the username you use to log in to the Linux command line.

Inbound Port Rules¶

Properly configuring network access is vital to ensure you can connect to your virtual machine and, later, access the applications running on it. During the virtual machine creation wizard, you will encounter a section for configuring inbound port rules, which are part of a Network Security Group (NSG) automatically associated with your VM. These rules act as a firewall, controlling which types of network traffic are allowed to reach your virtual machine from the internet or other networks.

To facilitate connecting to your virtual machine using SSH, you must allow inbound traffic on the standard SSH port, which is port 22. This rule enables your SSH client (like PowerShell or PuTTY) to initiate a secure connection to the VM’s command line interface. Additionally, since the ultimate goal is to host an ASP.NET Core application accessible via a web browser, you will also need to permit inbound traffic on the standard HTTP port, port 80. This rule allows users to access your web application once it is deployed and running. Therefore, ensure both SSH (22) and HTTP (80) ports are selected and allowed in the inbound port rules configuration.

Save the Private Key¶

If you chose the SSH public key authentication method and selected Generate new key pair, you will be presented with a crucial step just before the virtual machine deployment begins. A prompt will appear, often labeled “Generate new key pair,” indicating that the key has been created and is ready for download. You must select the option to Download private key and create resource. This action downloads a file to your local computer containing your SSH private key.

The downloaded private key file typically has a .pem file extension, which stands for Privacy-Enhanced Mail, although its use extends beyond email encryption. This file is extremely sensitive; it is your digital identity that authenticates you to the Linux virtual machine. Think of it as the key to your VM’s front door when using SSH. It is imperative that you save this file in a secure location on your local machine and under no circumstances share this file with anyone else. Losing this file means you might lose the ability to connect to your VM using this key, and if it falls into the wrong hands, unauthorized access could occur.

Determine the IP Address¶

Once the virtual machine creation process is complete and the resource has been successfully deployed in Azure, the next essential piece of information you need is the public IP address assigned to your VM. The public IP address is the unique address on the internet that allows your computer to locate and connect to the virtual machine. Navigate to the resource page for your newly created virtual machine within the Azure portal. The public IP address will be prominently displayed in the overview section.

Make sure to locate and note down this public IP address accurately. You will use this address as the target destination whenever you initiate an SSH connection from your local machine. It’s worth considering the type of public IP address assigned. By default, it might be dynamic, meaning it could change if the virtual machine is deallocated and then started again. For development or training environments where you might frequently stop and start the VM, using a static public IP address is highly recommended. A static IP address remains constant, ensuring that your connection information does not change, which simplifies reconnecting and configuring firewall rules or DNS records.

Connect to the Linux Virtual Machine¶

With your Linux virtual machine successfully provisioned in Azure and armed with its public IP address and your secure SSH private key, you are now ready to establish a connection. Unlike typical desktop operating systems that rely heavily on graphical user interfaces (GUI), managing servers, especially Linux servers, is most efficiently done through a command-line interface (CLI). This requires understanding a couple of key terms related to accessing and interacting with the Linux system via text commands.

When you connect to a Linux server remotely, you are typically interacting with two main components: a terminal emulator and a shell. Understanding the distinction, although often blurred in common usage, is helpful. You will not be clicking buttons or dragging windows on the VM itself; instead, you will type commands into a text-based interface and receive text output back. This method is powerful, flexible, and essential for server administration tasks, automation, and scripting.

The UNIX Terminal¶

Historically, the term “terminal” referred to physical devices used to interact with mainframe computers, such as teleprinters or video display units with keyboards. These were the points of access for users to input commands and view output. In modern computing, especially when connecting to remote servers, a terminal is a software application that emulates these physical devices. These applications provide a window where you can type commands and see the response from the remote machine. Examples include the command prompt or PowerShell on Windows, Terminal on macOS, or applications like PuTTY. The terminal emulator’s job is to handle input and output between you and the remote system’s shell.

The UNIX Shell¶

The shell is the command-line interpreter that runs on the Linux (or other UNIX-like) operating system itself. It acts as the interface between the user and the operating system’s kernel. When you type a command into your terminal emulator and press Enter, the terminal sends that command to the shell running on the remote machine. The shell interprets the command, interacts with the operating system to perform the requested task, and then sends the output back to the terminal emulator for you to see. Common shells include Bash (Bourne Again SHell), Zsh, and others. The shell is also sometimes loosely referred to as the “command line” or “CLI”. Shells provide not just command execution but also scripting capabilities, allowing sequences of commands to be automated.

This guide will demonstrate how to connect to your Azure Linux VM using two popular SSH client options available on Windows operating systems. The first method leverages the built-in SSH client available in recent versions of Windows 10 and Windows 11 via PowerShell or Command Prompt. The second method utilizes PuTTY, a widely used, free, and open-source terminal emulator and network file transfer application.

Connect by Using PowerShell SSH Terminal¶

Starting with Windows 10 version 1809 and later, Microsoft included an OpenSSH client directly within the operating system, making it much easier to establish secure shell connections without installing third-party software like PuTTY. You can access this SSH client through either the standard Command Prompt or PowerShell. To connect to your Linux virtual machine using this built-in client, open a PowerShell window and execute the SSH command using the following syntax. This syntax requires specifying the path to your private key file, the username you created for the VM, and the VM’s public IP address or hostname.

The basic command format is:

ssh -i <path to .pem private key file> <user>@<host>

Here, <path to .pem private key file> is the local path to the .pem file you downloaded from Azure. <user> is the administrator username you set during VM creation, and <host> is the public IP address or DNS name of your Azure VM. For instance, if your private key is located at d:\Learn\Linux\myPrivateKey.pem, your username is azureuser, and the VM’s IP is 20.100.50.123, the command would look like this:

ssh -i d:\Learn\Linux\myPrivateKey.pem azureuser@20.100.50.123

Upon your very first attempt to connect to a server, your SSH client doesn’t have any record of this server’s identity. Therefore, it will issue a warning message stating that “The authenticity of host ‘’ can’t be established.” This is a security feature to alert you if you might be connecting to an imposter server. You should verify the host key fingerprint displayed matches what Azure provides (though this step is often skipped in practice for simple setups like this training). When prompted “Are you sure you want to continue connecting (yes/no/[fingerprint])?”, type yes and press Enter to proceed.

After confirming the host’s authenticity (or bypassing the warning), you might encounter another message if the permissions on your private key file are not sufficiently restrictive on your Windows machine. The SSH client expects the private key file, which is essential for your identity, to be accessible only by your user account. If other users or groups on your computer have read or write access to the .pem file, the SSH client will issue a warning or even refuse to use the key, stating that “Permissions for ‘’ are too open.” This is a crucial security measure to prevent other processes or users on your local machine from potentially compromising your key.

To rectify this “permissions too open” issue on Windows, you need to adjust the NTFS file system permissions on the .pem file. The requirement is that only your user account and the SYSTEM account (which handles system-level operations) should have access to read this file. Often, files inherit permissions from their parent folder, which might grant access to groups like “Users” or “Administrators” beyond your specific user. Here are the steps to modify the permissions:

1. Locate the .pem private key file in Windows File Explorer. Right-click on the file and select Properties.
2. Navigate to the Security tab within the Properties window. Here you will see a list of groups and users and their associated permissions.
3. Click the Advanced button to open the Advanced Security Settings dialog. This window shows more detailed permission entries and information about inheritance.
4. If the permissions are inherited from the parent folder, you will see entries marked as “Inherited from…” You must disable this inheritance to set explicit permissions for this file. Click the Disable Inheritance button.
5. A dialog will appear asking what you want to do with the current inherited permissions. Select Convert inherited permissions into explicit permissions on this object. This action copies the currently inherited permissions and applies them directly to the file, allowing you to edit them.
6. Now, in the Advanced Security Settings dialog, you can remove unnecessary permission entries. Select any groups or users other than SYSTEM and your specific user account (e.g., your login name). Click the Remove button for each one. Ensure you do not remove the SYSTEM account or your own user account.
7. Verify that only the SYSTEM account and your specific user account remain in the list. Confirm that both of these entries have “Read & execute”, “Read”, and “Write” permissions (or equivalent, depending on how they were inherited/converted). The critical permission is that only your user and SYSTEM should have access at all, and ideally, your user only needs Read access for the key file itself for SSH login. However, ensuring only these two entities are listed is the primary goal.
8. Click OK on the Advanced Security Settings window and then OK on the main Properties window to save the changes.

After successfully adjusting the file permissions to restrict access solely to your user account and the SYSTEM, return to your PowerShell window. Attempt the same ssh -i ... command again. This time, if the permissions were the only issue, the SSH client should accept the private key and proceed with the authentication process. You should then see a welcome message from the Linux VM and be presented with the shell prompt, indicating you have successfully connected. You are now ready to interact with your Linux environment via the command line.

Connect by Using PuTTY¶

PuTTY is a well-established and popular free SSH and Telnet client for Windows, widely used for connecting to remote servers. If you are using an older version of Windows that doesn’t have the built-in OpenSSH client or if you simply prefer using a dedicated graphical client, PuTTY is an excellent alternative. You can download and install the latest version of PuTTY from its official website. The installation bundle typically includes several utilities, including PuTTY itself, PSCP (for secure file copy), and PuTTYgen (for generating SSH keys).

One important characteristic of PuTTY is that it uses its own proprietary format for storing private keys, known as PPK (PuTTY Private Key) format. The .pem file you downloaded from Azure containing your private key is in a standard OpenSSH format, which PuTTY does not directly accept for authentication. Therefore, before you can connect using PuTTY, you need to convert your .pem file into the .ppk format using the PuTTY Key Generator tool (PuTTYgen), which was installed alongside PuTTY.

To convert your private key file using PuTTYgen, follow these steps:

1. Launch the PuTTYgen application from your Windows Start menu. The PuTTY Key Generator window will open.
2. In the Parameters section at the bottom of the window, ensure that the RSA radio button is selected as the type of key to generate. Although you are loading an existing key, this setting influences how the key is handled or if you were generating a new one from scratch.
3. Click the Load button located in the middle of the window. This button allows you to select an existing private key file to load into PuTTYgen.
4. By default, the file open dialog might only show files with the .ppk extension. To find your .pem file, you need to change the file type filter. In the file type dropdown menu near the bottom right of the file selection window, select All Files (.). This will display all files in the directory, including your .pem file.
5. Navigate to the location where you saved your .pem private key file downloaded from Azure. Select the file and click Open.
6. PuTTYgen will attempt to import the private key from the .pem file. If successful, you will see a confirmation message indicating that the key was imported. The main window might populate with details about the key (like its type and fingerprint), although the sensitive key material itself is not fully displayed. You are now ready to save the key in PuTTY’s preferred .ppk format.
7. Click OK on the success message. Then, in the main PuTTYgen window, click the Save private key button.
8. PuTTYgen might ask you if you want to save the key without a passphrase. While adding a passphrase provides an extra layer of security (requiring you to enter the passphrase each time you use the key), for simplicity in this training, you can choose Yes to save it without a passphrase. Select a location and filename for the .ppk file (e.g., myPrivateKey.ppk) and click Save. Your private key is now saved in the .ppk format, ready for use with PuTTY.

Now that you have your private key in the correct format, you can use PuTTY to connect to your virtual machine.

1. Launch the PuTTY application. The PuTTY Configuration window will appear.
2. In the “Host Name (or IP address)” field, enter the connection information for your Linux VM. Use the format <username>@<public IP address> or <username>@<hostname>. For example, azureuser@20.100.50.123.
3. In the “Port” field, ensure that 22 is entered, which is the standard SSH port. Ensure the “Connection type” is set to SSH.
4. (Optional but recommended) You can save these session details for future use. Enter a name for this session under the “Saved Sessions” field (e.g., “Azure Linux VM”) and click the Save button. This allows you to simply select the saved session next time and click Load.
5. To configure PuTTY to use your .ppk private key file for authentication, navigate the Category tree on the left side of the PuTTY Configuration window. Expand the SSH category and select Auth.
6. In the Authentication options pane, click the Browse button next to the “Private key file for authentication” field.
7. Navigate to the location where you saved your converted .ppk private key file. Select the file and click Open. The path to the .ppk file will now appear in the field.
8. You are now ready to connect. Go back to the Session category at the top of the tree (or if you saved the session, select it and click Load). Click the Open button.

The first time you connect to the VM using PuTTY, similar to the PowerShell SSH client, you will receive a security alert. This alert warns you that the server’s host key is not cached in PuTTY’s registry and that you have no guarantee the server is the one you intend to connect to. This is PuTTY’s way of alerting you to a potentially untrusted server connection or a possible man-in-the-middle attack. For a known new VM like the one you just created in Azure, this warning is expected. Review the host key fingerprint if you are security conscious, but for this training, click Yes to accept the key and proceed with the connection. If successful, the PuTTY terminal window will open, display messages from the Linux VM, and present you with the command prompt, confirming your SSH connection.

For the remainder of this training series and subsequent labs, the examples and instructions for interacting with the Linux virtual machine will primarily assume you are using a standard SSH client via the command line, such as the built-in OpenSSH client available in PowerShell or Windows Terminal. The commands executed will be the same regardless of whether you use PowerShell SSH or PuTTY, as they are commands interpreted by the Linux shell.

Next steps¶

Part 1.2 - Basic operations on Linux will guide you through fundamental Linux commands and concepts essential for working with your virtual machine, including file system navigation, managing users, and using package managers.

---

We hope this detailed guide has helped you successfully create and connect to your Linux virtual machine on Azure using secure methods. Your feedback is valuable! If you encountered any issues, have questions, or found particular sections helpful, please feel free to share your thoughts below.