Secure Shell (SSH) Access

Secure Shell (SSH) is a network communication protocol that provides a secure way to access and manage remote resources. SSH is essential for accessing virtual machines (VMs) in Hyperstack. By using SSH, users can securely connect to their VMs, execute commands, and manage applications and services.

To gain SSH access to your VMs in Hyperstack, you must create an SSH key pair. A key pair consists of a private key, which you keep secure on your local machine, and a public key, which is stored in Hyperstack. When you attempt to connect to the VM, the SSH protocol uses these keys to establish a secure and authenticated connection, ensuring unauthorized users cannot gain access. For SSH access, a VM must have a public IP address assigned, as this allows the VM to be reachable over the internet, enabling remote management and connectivity.

Follow the steps outlined in this article to securely access your virtual machines.

In this article

• Create an SSH key
• Access your virtual machine via SSH
• Manually generate an SSH key pair
• APIs for creating and managing SSH key pairs

---

Access your virtual machine via SSH

Prerequisites for SSH:

• Verify your VM is running: On the 'My Virtual Machine' page in Hyperstack, ensure the VM is displaying an ACTIVE status. It may take some time for all services to initialize after the VM is deployed. If there is a connection error, retry after a few minutes.

• Ensure your VM has a public IP address: To check if your VM has a public IP address, go to the 'Virtual Machines' section to open the 'My Virtual Machine' page.

  • If an IP address is listed under the 'Public IP' header, then your VM has a public IP.
  • If no IP address is listed, navigate to the 'Networking' tab on the VM's details page and toggle 'Public IP Attached' to assign one.

1. Navigate to the 'Virtual Machines' section in Hyperstack and click on the VM name to see its details. Once the VM is ACTIVE, click on the 'Firewall' tab to access firewall settings for the virtual machine.

   

2. Click the 'Enable SSH access' button.

   

   Enabling SSH access will automatically generate a firewall rule allowing incoming traffic from any IP (0.0.0.0/0) on port 22 via TCP, as illustrated below.

   

3. To access your virtual machine via SSH, execute the following command in a terminal (such as Terminal, PowerShell, etc.):

   ssh -i [path_to_ssh_key] [os_username]@[vm_ip_address]
   • '[path_to_ssh_key]' is replaced with the path to the SSH key that was generated in the 'Create SSH key' step.
   • '[os_username]' is replaced with the username of the operating system running on your virtual machine.
     • For Windows, the username is Administrator
     • For Ubuntu, the username is ubuntu
     • For Centos, the username is centos
     • For Debian, the username is debian
     • For Fedora, the username is fedora
   • '[vm_ip_address]' is replaced with the IP address of your virtual machine, which you can find on the 'My Virtual Machines' page under the 'PUBLIC IP' column.

   For example:

   ssh -i ../_ssh_keys/example-key_hyperstack.txt [email protected]

Congratulations! You have successfully connected to your virtual machine.

---

Create an SSH key

Learn how to create an SSH key for connecting to your VM via Secure Shell (SSH) by following the steps below.

Hyperstack

1. Start by clicking the 'Create New SSH Key' button.

2. In the 'Generate an SSH Key' popup window, click the 'Generate SSH Key' tab (alternatively, import your own public key if you already have an SSH key).

3. Complete the fields as shown below:
   a. Environment - Select the environment where the key will be created.
   b. Name - Give the key pair a name.

4. Click 'Generate'

tip

Save the location of your new SSH key, as you will need it to connect to your virtual machine.

Infrahub API

After you have generated a key pair, paste the public key you copied to your clipboard into the public_key field when making the API request to import an SSH key pair, as demonstrated below.

1. Import an SSH key pair via API

POST /core/keypairs

To import a key pair, use the POST /core/keypairs endpoint with the completed request body as shown in the request below.

In the body of the request include the following fields:

1. The name field containing the name of your choosing for the SSH key pair you are creating.

2. The environment_name field with the name of the environment within which the SSH key will be stored.

3. The public_key field with the public key that you just saved to clipboard in the previous step.

Example request

curl -X POST "https://infrahub-api.nexgencloud.com/v1/core/keypairs"
  -H "api_key: YOUR API KEY"
  -H "Content-Type: application/json"
  -d '{
    "name": "example-key-name",
    "environment_name": "example-environment-name",
    "public_key": "ssh-ed25519 AAAAAC3NzaC1lZDINTE5AAAAIHna64ksd7dXJKhsf8xKkXf+s9djdkx97Hs6Dfn [email protected]"
  }'

Response

{
  "status": true,
  "message": "Keypair is imported successfully",
  "keypair": {
    "id": 3,
    "name": "example-key-name",
    "environment": "example-environment-nam",
    "public_key": "ssh-ed25519 AAAAAC3NzaC1lZDINTE5AAAAIHna64ksd7dXJKhsf8xKkXf+s9djdkx97Hs6Dfn [email protected]",
    "fingerprint": "23:64:b2:8e:89:4b:be:21:a6:51:22:d8:80:fb:e2:22",
    "created_at": "1970-01-01T00:00:00.000Z"
  }
}

tip

Save the name of your new key pair, as this will be necessary to create your virtual machine.

2. Enable incoming SSH traffic to your virtual machine via API

To enable incoming traffic to your virtual machine using the API, you must create a security rule as follows:

Send a POST request to /core/virtual-machines/{virtual-machine-id}/sg-rules endpoint replacing virtual-machine-id in the path with the ID of the virtual machine for which you want to enable SSH access, and complete the body of the request as specified below.

• Include the integer ID of the virtual machine that this security rule is being attached to in the path of the request as follows:

  • /core/virtual-machines/{VM ID HERE}/sg-rules

• Complete the request body with the following fields and values:

  Field Name	Field Input	Description
  remote_ip_prefix	0.0.0.0/0	Allows traffic from any source IP address.
  direction	ingress	Designates that the security rule is for incoming traffic.
  ethertype	IPv4	Indicates the use of Internet Protocol version 4.
  protocol	icmp	Specifies the use of Internet Control Message Protocol.
  port_range_min	22	Specifies the minimum port value for SSH.
  port_range_max	22	Specifies the maximum port value for SSH.

Request

curl -X POST https://infrahub-api.nexgencloud.com/core/virtual-machines/{virtual-machine-id}/sg-rules \
  -H "accept: application/json" \
  -H "api_key: YOUR API KEY" \
  -d '{
        "remote_ip_prefix": "0.0.0.0/0",
        "direction": "ingress",
        "ethertype": "IPv4",
        "protocol": "tcp",
        "port_range_min": 22, 
        "port_range_max": 22
    }'

tip

Now that you have enabled incoming traffic to your VM on port 22, you can connect to it by executing the SSH command shown here.

---

Manually generate an SSH key pair

note

To automatically generate a key pair using Hyperstack's user-friendly UI, click here.

How to manually create a key pair:

Linux

1. Open Terminal.

2. Use the ssh-keygen command to create a new key:

   ssh-keygen

3. After you run the command, you will be asked to specify the names of files where the keys will be saved and enter the password for the private key. Press Enter to use the default name. The key pair will be created in the ~/.ssh directory.

4. Your public key will be saved with a .pub extension. The private key will be in the location you specified.

   Public key: /path/to/your/key.pub

   Private key: /path/to/your/key

5. Copy the public key from the <key_name>.pub file using any text editor, such as Notepad. Please note that the key must be written as a single line (no returns or line breaks).

caution

Never share your private SSH key. Only the public key needs to be imported to access your virtual machines.

Windows

1. Run cmd.exe or powershell.exe.

2. Use the ssh-keygen command to create a new key. Run this command:

   ssh-keygen

3. After you run the command, you will be prompted to specify the names of files where the keys will be saved and create a password for the private key. Press Enter to use the default name.

   The key pair will be created in C:\Users\<username>\.ssh\ or C:\Users\<username>\ depending on the command line interface.

   The public key will be saved in the <key_name>.pub file.

4. Copy the public key from the <key_name>.pub file using any text editor, such as Notepad. Please note that the key must be written as a single line (no returns or line breaks).

caution

Never share your private SSH key. Only the public key needs to be imported to access your virtual machines.

---

APIs for creating and managing SSH key pairs

To view the API reference documentation, click on the endpoint names below.

Endpoint Name	URL	Description
List key pairs	GET /core/keypairs	Returns a list of your existing SSH key pairs.
Import key pair	POST /core/keypairs	Imports an SSH key pair.
Update key pair	PUT /core/keypair/{id}	Modifies the name of an existing SSH key pair.
Delete key pair	DELETE /core/keypair/{id}	Deletes a key pair.

Back to top