Guide: SSH

SSH Key Pair Generation and Import

Generating an SSH Key Pair Locally

🐧 Linux / 🍎 macOS

Open a terminal and run the following command:

ssh-keygen -t rsa -b 4096 -f ~/.ssh/myKey

When prompted, enter a secure passphrase. Record it safely — without it, you won't be able to use the key pair.

This creates two files:

• Private key: ~/.ssh/myKey
• Public key: ~/.ssh/myKey.pub

Note: If you copy the key pair to or from another system, ensure that the private key has correct (restricted) permissions:

chmod 600 ~/.ssh/myKey

Now you can import your public key into the Dashboard.

---

🪟 Windows

Open Command Prompt (Click the Start menu, type cmd into the search bar and press Enter). Then run the following commands:

mkdir C:\Users\%USERNAME%\.ssh

ssh-keygen -t rsa -b 4096 -f C:\Users\%USERNAME%\.ssh\myKey

When prompted, enter a secure passphrase. Record it safely — without it, you won't be able to use the key pair.

This creates two files:

• Private key: C:\Users\%USERNAME%\.ssh\myKey

• Public key: C:\Users\%USERNAME%\.ssh\myKey.pub

Note: If you copy the key pair to or from another system, ensure that the private key has correct (restricted) permissions:

icacls "%USERPROFILE%\.ssh\myKey" /inheritance:r /grant:r "%USERNAME%:(R,W)"

Now you can import your public key into the Dashboard.

---

Importing an Existing SSH (Public) Key via Dashboard

To use a key you generated on your device:

1. Log in to the Dashboard.
2. Go to: Project → Compute → Key Pairs.
3. Click Import Public Key.
4. In the dialog:
   • Enter a unique name.
   • Make sure SSH Key is selected as the key type.
   • Upload your public key file (e.g., myKey.pub) or paste the contents of it.
5. Click Import Public Key.

Your public key name should now appear in the list and is ready for use.

---

Creating an SSH Key Pair via Dashboard

If you don’t have a key pair yet or prefer using the Dashboard:

1. Log in to the Dashboard.
2. Go to: Project → Compute → Key Pairs.
3. Click Create Key Pair.
4. In the dialog:
   • Enter a unique name.
   • Make sure SSH Key is selected as the key type.
5. Click Create Key Pair.

The public key name should now appear in the list and the private key will be automatically downloaded — save it securely, as you won’t be able to download it again.

Note: Ensure that the private key has correct (restricted) permissions:

• Linux/macOS: chmod 600 ~/.ssh/myKey.pem

• Windows: icacls "%USERPROFILE%\.ssh\myKey.pem" /inheritance:r /grant:r "%USERNAME%:(R,W)"

---

Advanced SSH Configuration

Once you have generated and imported your SSH key pair, you can simplify and improve your SSH experience by creating a personal SSH configuration file. This file, typically located at ~/.ssh/config, lets you store connection details, reuse existing connections, and keep sessions stable — all of which are especially useful when managing multiple OpenStack instances.

Organizing SSH Connections (.ssh/config File)

Instead of remembering long commands, you can define named host entries in your SSH configuration file.

Host myVM
    HostName 134.155.111.111
    User ubuntu
    IdentityFile ~/.ssh/myKey

You can now connect simply with:

ssh myVM

Explanation:

• Host — a nickname for your connection
• HostName — the actual IP address or DNS name of the instance
• User — the login username on the remote host
• IdentityFile — path to your private key (if not the default id_rsa)

This approach helps you manage multiple instances with short, readable aliases.

Performance and Graphical Features

These optional SSH settings can enhance usability and performance for specific use cases.

Enabling Compression

For slower or high-latency connections, enabling compression can improve SSH responsiveness and reduce data transfer size.

Host myVM
    ...
    Compression yes

Explanation:

• Compression yes — enables on-the-fly compression of SSH traffic.

This is most effective over slow or distant network links but may slightly increase CPU usage.

Enabling Graphical Applications (X11 Forwarding)

If you need to run graphical applications from your OpenStack instance (e.g., editors or plotting tools) and display them locally, you can enable X11 forwarding.

Host myVM
   ...  
   ForwardX11 yes

Explanation:

• ForwardX11 yes — forwards X11 (graphical) traffic from the remote host to your local display, provided an active X server is enabled on your local system.
• For connections to hosts you trust (e.g., your own OpenStack instances), certain compatibility issues with some GUI program can be avoided by the following alternative: ForwardX11Trusted yes

Reusing Existing SSH Connections (ControlMaster)

If you frequently connect to the same instance, SSH can reuse a single network connection instead of opening new ones each time. This reduces connection overhead and speeds up subsequent logins.

Host myVM
    ...
    ControlMaster auto
    ControlPersist 1h
    ControlPath ~/.ssh/master-myVM-%r@%h:%p

Explanation:

• ControlMaster auto — enables connection sharing automatically
• ControlPersist 1h — keeps the master connection open for one hour after the last session ends
• ControlPath ~/.ssh/master-myVM-%r@%h:%p — specifies the filename for the multiplexing socket. Here:

%r = remote user, %h = hostname, %p = port.

With these options, if you connect to myVM once, further SSH or SCP commands to the same host in the specified time window will reuse that connection and start instantly.

Connecting Through an Intermediate Host (ProxyJump)

Sometimes, you need to reach a server that is only accessible via an intermediate host (a jump host). ProxyJump automates this routing in a single SSH command.

Host myVM
    ...
    ProxyJump proxy

Explanation:

• ProxyJump proxy — routes the connection automatically through the jump host proxy.
• Other settings from your SSH configuration (keys, ControlMaster, etc.) are still applied to the final connection.

This simplifies connecting to hosts behind a firewall or in a private network.

Keeping Connections Alive

Long-running SSH sessions can sometimes time out due to network inactivity. To prevent this, configure SSH to send periodic keepalive messages.

Host myVM
    ...
    ServerAliveInterval 60
    ServerAliveCountMax 3
    TCPKeepAlive yes

Explanation:

• ServerAliveInterval 60 — sends a keepalive message every 60 seconds
• ServerAliveCountMax 3 — disconnects only after three unanswered keepalives (≈3 minutes)
• TCPKeepAlive yes — uses low-level TCP keepalive as an additional safeguard

This ensures stable, long-lasting sessions even over less reliable networks.

SSH Logging and Debugging

SSH can provide detailed messages about connection steps and authentication. Adjusting the log level in your configuration helps diagnose problems when connections fail or behave unexpectedly.

Host myVM
    ...
    LogLevel VERBOSE

Explanation:

SSH log levels control the amount of diagnostic information printed during a session.

• QUIET — no log messages.
• FATAL — fatal errors only.
• ERROR — all errors.
• INFO — minimal informational messages.
• VERBOSE / DEBUG / DEBUG1 — shows some debug info (authentication, key usage).
• DEBUG2 — very detailed debug messages.
• DEBUG3 — maximum verbosity; shows all SSH internal steps, key negotiation, and multiplexing.

Troubleshooting Frozen SSH Sessions

Occasionally, SSH master connections can freeze or hang, especially after network interruptions. In such cases, you can manually terminate or clean up the stale connection.

a) Identifying and killing master processes

List all relevant master sockets and their processes:

lsof -U 2>/dev/null | grep master-myVM

Terminate the corresponding processes:

kill -9 <PID>

b) Removing stale master socket files

Delete leftover socket files:

rm ~/.ssh/master-myVM-*

After cleanup, new SSH connections will automatically establish fresh master sessions.

Remote Development over SSH

Visual Studio Code (VS Code)

Visual Studio Code (VS Code) is a powerful, cross-platform integrated development environment available for Linux, macOS, and Windows. It has become the most widely used development platform worldwide, valued for its lightweight design and an extensive ecosystem of extensions that support virtually every programming language, toolchain, and workflow.

One such extension is Remote – SSH' (by Microsoft), which allows you to edit, build, and debug directly on a remote host while keeping the same familiar VS Code interface on your local machine. This approach ensures a consistent development experience across operating systems — the same editor, shortcuts, and extensions work identically on every platform — while all computation and file operations take place securely on the remote host.

Since both VS Code and its Remote-SSH extension have comprehensive official guides, this section provides only a brief Quickstart. It will help you integrate your bwCloud-OS VMs into a development environment in just a few steps.

⚠️ Note: When you connect via Remote-SSH for the first time, VS Code automatically installs a small server component on your VM (typically under ~/.vscode-server). Depending on your workload, this background service may consume noticeable resources — especially memory (RAM), which may even cause the VM to become unresponsive if its flavor is too small.

Setting Up VS Code and Remote-SSH

1. Install VS Code on your local machine: Follow the official installation guide for your operating system.

2. Install Remote-SSH extension: Open VS Code and go to the Extensions view ( Ctrl+Shift+X), search for Remote - SSH (by Microsoft) and click Install.

Connecting VS Code to Your VM

1. In VS Code, select Remote-SSH: Connect to Host from the Command Palette (F1, Ctrl+Shift+P) or by clicking on the Remote Quick Access status bar item in the lower left corner:

2. A list of your configured SSH hosts will appear, select the desired target.

Alternatively, you can first select Add New SSH Host and type your (tested) ssh command (e.g., ssh -i ~/.ssh/myKey ubuntu@134.155.108.71), VS Code will generate a corresponding entry in the .ssh/config file. Then you can select it.

3. After a moment, VS Code will connect to the SSH server and set itself up. After you are connected, you'll see in the status bar which host you are connected to:

Working with Your Remote VM

Once connected, you can use VS Code as you would on your local machine — with one key difference: everything you see and execute in that VS Code window belongs to and runs on the remote host.

For example:

• Opening a terminal (Menu → Terminal → New Terminal) starts a shell on the remote VM.
• The File Explorer displays the remote directory structure.
• You can transfer files easily:
  • Drag and drop from your local file manager into the remote Explorer to upload.
  • Right-click a file or folder in the remote Explorer and choose Download to copy it to your local system.