SSH access: open a terminal inside your running service

What this covers

SSH access lets you open a terminal inside the container your service is already running, from your own machine. It is for the questions a log line cannot answer: is that file actually where you think it is, what does this environment variable really contain, does the database respond from inside this container.

It is available on paid plans. On a free plan the SSH Access page in your dashboard shows what the feature does and which plan includes it.

Before you connect

You need two things: an SSH key, and a service that is running.

An SSH key is a pair of files. The public half is safe to share and is what you add to Voroa; the private half stays on your machine and is never sent anywhere. If you do not already have one, make one:

ssh-keygen -t ed25519 -C "you@example.com"

Press Enter to accept the default location. That writes two files - ~/.ssh/id_ed25519 (private, keep it) and ~/.ssh/id_ed25519.pub (public, the one you paste).

Add the public key in your dashboard: open any service, choose SSH Access, and use Add key. Paste the contents of the .pub file. A key is added once and works for every service in that workspace.

Only you can see or delete the keys you add. A teammate’s keys are not listed on your page, and yours are not on theirs.

Connecting

The SSH Access page shows the exact command for that service. It looks like this:

ssh svc-a1b2c3d4e5f6g7h8i9j0k1l2@ssh.getvoroa.com -p 2222

The address is the same for every service. The username is what selects which one - it is that service’s own identifier, which you can also see in its dashboard URL. Copy the command from the page rather than typing it.

The first time you connect, your SSH client asks whether you trust the server and shows a fingerprint. The same fingerprint is shown on the SSH Access page, so you can compare the two before answering yes.

There is no SSH password

Voroa does not offer password login over SSH, and never asks you to set one. Access is by key only.

This is deliberate. A password on an internet-facing port is guessed at constantly, and a password we stored would be one we could never show you again anyway. Your key is the whole of your login: add it once, delete it when you replace the laptop.

What a session can do

You get a shell inside the container that is already serving your traffic - not a fresh copy of it. So the files, the environment and the processes you see are the real ones.

A few things are worth knowing before you rely on it:

• Anything you write outside a persistent disk is lost on the next deploy. A container is rebuilt from your repository each time. A shell is not a backup, and it is not a place to keep files.
• The session shares your service’s memory and processor limits. A heavy command inside a shell competes with the service itself, and a runaway one can exhaust that service’s own limits.
• Changes you make by hand are not deployed. Editing a file inside the container fixes this container until the next deploy and nothing after that. Commit the change instead.
• A session ends when you disconnect, after 30 minutes with no activity, or after 8 hours. Ending a session closes your terminal; a process you started in the background (for example with nohup) keeps running inside your service until the next deploy or restart.
• You can have four terminals open on one service (ten across the workspace). Past that you will see “Too many SSH sessions are open for this service” - close one and try again. The limit is there so a runaway script cannot open shells without end; it is not something to buy more of.

When a connection is refused

Every refusal reads the same way to your SSH client - Permission denied (publickey) - so the reason is in your dashboard rather than in the message. Work down this list:

• Your service is not running. SSH connects to a running container. If the service is stopped or its last deploy failed, start or redeploy it first. The SSH Access page tells you when this is the case.
• “SSH is temporarily unavailable for this service. Try again in a few minutes.” Your key and access are fine; the shell could not be reached for a moment. Wait a few minutes and connect again. If it keeps happening, contact support and include the time you tried.
• “This SSH connection is older than 8 hours. Reconnect to continue.” You opened a new terminal on an SSH connection that has been open for more than 8 hours (common with ControlMaster / ControlPersist in your SSH config). Close that connection - for example ssh -O exit svc-...@ssh.getvoroa.com -p 2222
  • and connect again.
• The key is not added, or you added the wrong half. Check the SSH Access page lists a key whose fingerprint matches the one your machine offers: run ssh-keygen -lf ~/.ssh/id_ed25519.pub and compare.
• You changed your password recently. Changing an account password signs out every device and also retires SSH keys added before the change. Add the key again.
• Your plan does not include SSH. The SSH Access page says so plainly, and names the plans that do.
• Your role does not include SSH. A workspace admin decides which roles may open a shell.
• You were removed from the workspace. Access ends with membership, even though the key still exists on your machine.

To see more detail about what your client is doing, add -v:

ssh -v svc-...@ssh.getvoroa.com -p 2222

Ending access

Delete a key from the SSH Access page. Any session already open using that key closes within a minute - deleting a key is not only about future connections.

Delete a key whenever a laptop is replaced, lost, or leaves your team. There is no need to rotate a key on a schedule; there is every reason to remove one you no longer control.

Related

• SSH and shell access to a running service