Sessions

A session is a target to connect to. Depending on its type it opens as a terminal, a file manager or a remote desktop. For database records see Databases.

Route

Every session has a route:

• Direct: the target is reachable from the network you are on.
• Through a VPN: if the VPN on the route is down, it is started when you connect.
• Through an SSH session: another saved SSH session is used as a hop. Hops can be chained.

quickssh add-ssh web --host 10.20.0.15 -u deploy --vpn acme
quickssh add-ssh db  --host 10.20.0.9  -u postgres --jump web
quickssh edit-ssh db --direct          # remove the hop

SSH

You can authenticate with a password, a key file or a pasted key; if none is given, ssh tries its own default keys.

In the terminal tab:

• File panel: the folder icon at the top right. The panel follows the directory you cd into in the terminal. You can upload and download files and folders.
• Server status bar: CPU, RAM, disk, network, disk I/O and (if present) GPU.
• Scrolling: drag the bar on the right or click its track. The mouse wheel and Shift+PageUp / Shift+PageDown also scroll through the history.
• Selection: drag to select; when you go above or below the area, the history scrolls by itself. To select a long output, click at its start, scroll, and Shift+click at its end. A double click selects a word, a triple click a line. In programs that use the mouse (vim, htop), hold Shift while selecting.
• Clipboard: with a selection, Ctrl+C copies all of it, including the part scrolled off the screen; without a selection it interrupts the program. Ctrl+V pastes. If the clipboard holds files, it offers to upload them.
• Macros: record the steps you repeat in a terminal, or paste a whole script with Macros → New macro. Each command in the pasted text becomes a step; comment lines (#) and empty lines are skipped, while heredocs (<<EOF … EOF), lines continued with \\ and if/for blocks stay a single step. Line numbers show while you type; a line without a number is the continuation of a command that wrapped because it didn't fit. When played, steps go in order: each is sent once the previous command has finished and the prompt is back. If a command asks for a password or a confirmation, the macro waits and continues after you answer. You can limit a macro to certain groups or servers (Scope); it is then offered only in terminals there. Macro names may contain capitals, digits and spaces.

To run a single command without any prompts:

quickssh exec web -- df -h /

Temporary access (agent)

With a small script (quickssh-agent) installed on the target, each connection gets its own key, which is deleted when the connection closes. No permanent password or key is stored for the target. The server prints the install command with quicksshd agent-setup; tick Temporary access in the session.

SFTP and FTP

File sessions open as a full-size file manager.

quickssh add-ssh archive --sftp --host 10.20.0.30 -u web --vpn acme
quickssh add-ssh site    --ftp --tls --host ftp.example.com -u web
quickssh fs ls archive /var/www
quickssh fs get archive /var/www/index.html .
quickssh fs put archive ./report.pdf /var/www

• You can upload files and folders by dragging and dropping them onto the window.
• An upload is tracked as a single transfer; progress is shown separately as file count and size.
• FTP connects only directly or through a VPN. Without TLS, the password and the files travel unencrypted; use FTPS or SFTP when you can.

Remote desktop (RDP)

RDP sessions open inside the app as tabs. The server connects to the target; only the picture reaches your computer.

quickssh add-ssh accounting --rdp --host 10.20.0.40 -u 'ACME\accounting' --vpn acme --ask-password

On first use the server downloads the image of the service that makes the connection. Since most RDP servers use self-signed certificates, certificate verification is off by default.

Editing, grouping, deleting

Save, Cancel and Delete stay fixed in the bar at the bottom of the record page. Deleting asks for confirmation.

quickssh show web
quickssh edit-ssh web --port 2222 --tag prod --rename front
quickssh group set Acme front db
quickssh rm front

You can't delete a session while other sessions use it as a hop.

Remote desktop: RDP and VNC

Connect to Windows remote desktops with RDP, and to Linux desktops, kiosk screens and embedded devices with VNC. In both cases the server connects to the target; only the picture reaches your computer, never the password. The session opens as a tab in the app; mouse, keyboard and clipboard work.

• In a VNC session most servers ask only for a password; you can leave the user name empty. The usual port is 5900 (5901 for display :1).
• To reach a screen running on this computer (e.g. a QEMU virtual machine listening on 127.0.0.1:5977), enter 127.0.0.1 as the host; if it has no password, leave the password field empty.
• VNC itself is not encrypted. If the target is not on the same network, connect through a VPN (add a VPN hop to the route).
• On the command line: quickssh add-ssh "Kiosk" --vnc --host 10.1.0.40 --port 5901 -u "".

Macros: parameters, progress and stopping

Parameters. A macro can ask you for values when it runs. Write [[QUICK_SSH_PARAMETER_NAME]] where the value goes in the command (for example useradd -m [[QUICK_SSH_PARAMETER_USERNAME]]). When you start the macro, a window asks for these values; what you type replaces the placeholder with leading and trailing spaces removed. In the Parameters card on the macro's edit page you can make a parameter optional; left empty, the placeholder becomes empty text. The values you enter are not logged, only the parameter names are.

Progress. The Macros panel next to the terminal shows the running macro's name, which step it is on and that step's command; the running macro is highlighted in the list. Only one macro runs on a server at a time: while one runs, others can't be started.

Stopping. Pressing the running macro again or Stop asks for confirmation. Once stopped, the remaining steps are not sent; the command running on the server at that moment is not interrupted and runs until it ends.

Name. You can rename a macro on its edit page; names may also contain characters like &, / and parentheses.

Names

Give sessions and VPN profiles any name you like: capitals, spaces, non-English letters ("Web Prod 2 (Internal)"). quickssh derives an internal name from it (web-prod-2-internal); if that internal name already exists, it appends a short id. The internal name is used on the command line, in permissions and in files, and never changes again; you can change the display name whenever you like. You'll find the internal name on the record's page under the name field and in the output of quickssh ls.