SSH gateway
Besides the web terminal, Casvisor can accept SSH connections itself, so people reach SSH assets with the tools they already use: ssh, scp, sftp, rsync, Xshell, or VS Code Remote. They sign in to the gateway with a public key they registered in Casvisor; Casvisor then logs in to the asset with the asset's own account, or one of its system accounts. The same permissions, command rules and session list apply as in the browser. For RDP, VNC, Telnet, MySQL and PostgreSQL assets it forwards a port, so mstsc and other clients can be used too.
Turning it on
The gateway listens on the port in sshGatewayPort:
- In
conf/app.confit is empty, which leaves the gateway off. - The Docker images set the environment variable
sshGatewayPort=2222, so the gateway is on in a container. Publish the port with-p 2222:2222. To turn it off, pass an empty value:-e sshGatewayPort=. - With
isDemoMode = truethe gateway stays off whatever the port.
sshGatewayHost is the host name shown to users in the commands they copy. Leave it empty to use the host name they opened Casvisor at, or set it when SSH is reached at a different name, for example ssh.example.com. See Configuration.
On first start the gateway creates its own Ed25519 host key and keeps it in the database, encrypted with credentialKey when that is set, so the key survives replacing the container and is the same on every Casvisor sharing the database. Its SHA-256 fingerprint is in the log line SSH gateway listening on port 2222 and on the SSH keys page; compare it with what ssh shows on the first connection.
The gateway is plain SSH on its own TCP port and does not pass through the HTTPS reverse proxy. See Behind a reverse proxy.
Registering a public key
The gateway only accepts public keys. There is no password sign-in, so it never sees the password of a Casvisor or Casdoor account, and the MFA of the web sign-in does not apply to it.
- If you have no key yet, create one with
ssh-keygen -t ed25519. - In Casvisor, open SSH keys (
/ssh-keys), click Add SSH key, and paste the content of~/.ssh/id_ed25519.pub.
Every user can manage their own keys there; administrators are not needed. A key can belong to only one user. The page lists each key's fingerprint and when it was last used, and deleting a key stops it from signing in at once.
At every connection the gateway reads the user again, from the built-in accounts or from Casdoor: a user who is forbidden, disabled or deleted, or who is not in allowedUsers, is refused even with a registered key. Their groups and administrator flag are also read fresh, rather than from an earlier web sign-in.
Connecting
The username tells the gateway which asset to open:
| Command | Opens |
|---|---|
ssh -p 2222 web-01@casvisor.example.com | The asset web-01 in your own organization |
ssh -p 2222 alice@web-01@casvisor.example.com | The same, with your Casvisor user name in front. It has to be the owner of the key. |
ssh -p 2222 alice@deploy@web-01@casvisor.example.com | The asset web-01 as its account deploy, see Choosing the account |
ssh -p 2222 other-org/web-01@casvisor.example.com | An asset of another organization. Only users of Casdoor's built-in organization can reach those. |
ssh -p 2222 alice@casvisor.example.com | With your own user name and no asset: a menu of the SSH assets you may connect to |
ssh -p 2222 -N -L 13389:win-01:3389 alice@casvisor.example.com | No shell: forwards localhost:13389 to the asset win-01, see Port forwarding to other assets |
The menu lists one line for every asset and account you may connect as, with its number, the asset's name, the account, the address and the display name. Type a number, an asset name, or <account>@<asset> to connect, or q to quit. It is meant for tools such as Xshell that save one host and one user name.
On Assets, SSH assets have a Copy SSH command button that copies the right command, with the port and host filled in, and the account when you may not use the asset's own.
Logging in works for SSH assets only, and only as an account Casvisor holds the username of: the gateway logs in to the asset with the stored account, its private key or password, and cannot ask for one. An asset without a username is refused with a message to ask the administrator. The asset's host key is pinned as in the web terminal; see Protocols.
Choosing the account
An asset can have system accounts besides its own, and a permission says which of them you may use. Name the account between your user name and the asset: alice@deploy@web-01. Your user name is required in this form, since deploy@web-01 would be read as the user deploy.
Without an account in the username, the gateway picks it:
- the asset's own account, if you may use it;
- otherwise, the one system account you may use;
- if you may use several system accounts but not the asset's own, it refuses and lists them: choose the account to connect to the asset: web-01 as with "ssh -p alice@@web-01@": deploy, readonly.
The actions you hold through the gateway, such as Upload, Download and Forward, are the ones the permissions give for the account you connected as. The session list shows the account.
Instead of typing the port every time, put the gateway in ~/.ssh/config:
Host web-01
HostName casvisor.example.com
Port 2222
User web-01Then ssh web-01, scp file web-01: and VS Code Remote all work with the name web-01.
If the connection is refused after the key has been accepted, the reason is printed as casvisor: ..., for example you have no permission to connect to the asset: web-01.
What works through it
| Use | Needs |
|---|---|
Interactive shell (ssh) | Connect |
Commands (ssh web-01 uptime) with their exit status, and a shell without a terminal (ssh -T) | Connect, Upload and Download |
sftp, and scp in OpenSSH 9.0 and later, which uses SFTP | Connect, and Upload to write or Download to read |
scp -O (the old scp protocol) | Connect, and Upload or Download depending on the direction |
rsync over SSH | Connect, and Upload or Download depending on the direction |
Local port forwarding (ssh -L) and Unix socket forwarding | Connect and Forward |
| VS Code Remote, which runs its server with a command and talks to it over a forwarded socket | Connect, Upload, Download and Forward |
A command on the ssh command line, and a shell without a terminal, pass the client's input and the asset's output through as they are, so a file can be piped in or out (ssh web-01 'cat backup.tar' > backup.tar), and no screen shows what a shell without a terminal runs. That is why they need Upload and Download. An interactive shell with a terminal needs only Connect: its commands are checked against the command rules and its screen is recorded.
File transfer lists which Upload or Download each file operation needs.
Forwarded connections are opened from the asset, as they would be with a direct SSH login, so ssh -L 5432:localhost:5432 reaches the database on the asset itself.
Always refused: remote port forwarding (ssh -R), agent forwarding (ssh -A) and X11 forwarding (ssh -X).
Port forwarding to other assets
RDP, VNC, Telnet, MySQL and PostgreSQL assets can be reached with the client you already use too, such as Remote Desktop Connection (mstsc), a VNC viewer, a Telnet client, mysql, psql or DBeaver: the gateway forwards a port on your machine to the asset.
ssh -p 2222 -N -L 13389:win-01:3389 alice@casvisor.example.comLeave it running and connect your client to localhost:13389. Windows 10 and later come with ssh.
- Sign in with your own user name and no asset, as for the menu.
- In
-L, write the asset's name where a host would go, and the asset's own port. Casvisor connects to the address stored on the asset, through its network gateway if it has one. Other ports are refused. An asset of another organization is writtenother-org/win-01. - It needs Connect and Forward on that asset.
- On Assets, assets other than SSH have a Copy port forwarding command button with the command filled in. It takes the local port 10000 above the asset's, 13389 for 3389, so that it does not clash with a service on your own machine; any free port works.
- One
sshcommand can carry several-Loptions, for several assets at once.
Unlike a connection from the browser, the bytes pass through as they are. Casvisor does not fill in the asset's account, so you log in to the asset with an account you know. The connection is not recorded or checked against command rules, SQL statements included, and the Copy, Paste, Upload and Download actions do not limit it. That is why it takes the Forward action, which administrators give only to the people who should have it.
Sessions, commands and the audit log
One SSH connection through the gateway is one session, however many shells, transfers and forwards it carries. Its user agent is the client's SSH version, such as SSH-2.0-OpenSSH_9.6. Administrators can stop it like any other session, and it is cut off when the permission that allows it is revoked. Interactive shells are recorded and can be watched live; a connection that only runs a command, transfers files or forwards ports has no recording.
A port forward to another asset is a session of its own, one for each asset, with the mode tunnel, for as long as the ssh command runs, however many connections the client opens through it. Administrators can stop it like any other session, which disconnects the ssh command, and it is cut off as soon as Connect or Forward on the asset is taken away.
Commands are recorded and checked against the command rules: commands typed in an interactive shell as in the web terminal, and commands given on the ssh command line as they were sent. The connection to the asset, each new forwarding destination, the first connection forwarded to another asset, and every file read or written over SFTP, along with new folders, renames, removals and links, go into the operation log.
Connecting
Users connect from the workbench, which lists the assets they may reach and opens each connection in a tab, or from an asset's Connect button, which opens it on a page of its own.
Network gateways
Reach assets in networks Casvisor cannot connect to directly, through an SSH jump host in that network or through an agent that connects out to Casvisor from inside it.