Multi Agent Seamless SSH Usage Guide

Seamless SSH allows you to connect to servers through QueryPie while preserving the native terminal experience.

This document describes how to use Seamless SSH, along with specs and support scope, based on version 10.2.8.

How to use

SSH config Setup

You can configure the SSH config file to use the existing ssh command.

1. Navigate to the .ssh directory and create or edit the config file.

cd ~/.ssh
vi config

1. Add the following settings to the config file, then save and exit (press :wq to save)

Host {{Server Name}}
  Hostname {{Server URL}}
  Port {{Server SSH Port}}
  ProxyCommand qpctl ssh-proxy %r %h %p develop.dev.querypie.io

1. If server URLs and ports do not overlap across servers, you can configure it as follows.

Host *
  ProxyCommand qpctl ssh-proxy %r %h %p develop.dev.querypie.io

1. Connect to the server using the simplified SSH command.

ssh {{Server Account}}@{{Server Name}}

Shell Alias Setup

You can configure an SSH Alias to use the existing ssh command.

1. Open your shell configuration file.

For Bash:

vi ~/.bashrc

For Zsh:

vi ~/.zshrc

1. Add the following line to the shell configuration file, then save and exit. (Press :wq to save)

alias qshdev='ssh -o ProxyCommand="qpctl ssh-proxy %r %h %p"'

1. Apply the changes to the current shell session.

For Bash:

source ~/.bashrc

For Zsh:

source ~/.zshrc

Or simply open a new terminal window.

1. Connect to the server using the alias.

qpctl host use develop.dev.querypie.io
qshdev {{Server Account}}@{{Server Name}}

Differences from the previous QueryPie User Agent

Base command

Seamless SSH runs using the following command installed with QueryPie Multi Agent.

qpctl ssh-proxy %r %h %p [QueryPie Host]

The command used by the previous User Agent was.

qpa ssh %r %h %p

How connection errors are displayed

If an error occurred when connecting to the QueryPie Proxy server during the connection stage, the previous User Agent displayed a dialog, which was not terminal-friendly.

Multi Agent has been changed to display error messages in the terminal .

$ qpctl ssh manual@core.dev.querypie.io
qpctl: error: Connection error: Timeout

Newly added features

Default host specification

Multi Agent requires entering the QueryPie Host to use Seamless SSH, which can be inconvenient.

We are adding a feature to specify a default server to use for the qpctl command.

• When a default server is specified, you do not need to enter the QueryPie Host in the qpctl ssh-proxy command.
• Even if a default server is specified, if you enter a QueryPie Host , that value will be used.

qpctl host list

Check the list of currently registered QueryPie Hosts.

$ qpctl host list
QueryPie Hosts:
 - https://nightly.dev.querypie.io
 - http://t8.ec2.querypie.io (current)
 - https://t3.qa.querypie.io
 - https://t4.qa.querypie.io
 - https://t8.qa.querypie.io
 - https://t12.qa.querypie.io

qpctl host use

Shows the list of registered QueryPie Hosts and lets you select one with the arrow keys

$ qpctl host use
Use the arrow keys to navigate: ↓ ↑ → ←
QueryPie Hosts
  ▸ https://nightly.dev.querypie.io
    http://t8.ec2.querypie.io (current)
    https://t3.qa.querypie.io
    https://t4.qa.querypie.io
↓   https://t8.qa.querypie.io

Selected https://t4.qa.querypie.io
✔ Host changed to https://t4.qa.querypie.io

qpctl host use {QueryPie Host}

$ qpctl host use nightly.dev.querypie.io
✔ Host changed to https://nightly.dev.querypie.io

⚠️ Experimental feature - Use qpctl directly ⚠️

To use Seamless SSH

• You can configure ~/.ssh/config, or
• Enter -o ProxyCommand=qpctl ssh-proxy … in the ssh command

The experience is not intuitive. If you have QueryPie Multi Agent installed, you can use the qpctl command directly for ssh connections.

1. Just add qpctl before the ssh command you want to use.

$ qpctl ssh ec2-user@core.dev.querypie.io -i ~/.ssh/querypie-dev.pem

1. For settings in ~/.ssh/config, just add qpctl as well.

$ cat ~/.ssh/config

Host core-dev
Hostname core.dev.querypie.io
User ec2-user
IdentityFile ~/.ssh/querypie-dev.pem

$ qpctl ssh core-dev

Support scope

Minimum supported version

OpenSSH 6.7 or later is required.

$ ssh -V
OpenSSH_9.8p1, LibreSSL 3.3.6

How it works

The qpctl command wraps the ssh client command and automatically adds the ProxyCommand option before executing.

1. qpctl ssh command_line
2. ssh -G command_line
   1. Extract username, hostname, port
3. ssh command_line -o ProxyCommand=“qpctl ssh-proxy username hostname port”

Unsupported features

Custom ProxyCommand

Because qpctl uses ProxyCommand, custom ProxyCommand cannot be used.

$ qpctl ssh ec2-user@core.dev.querypie.io -o ProxyCommand="..."
qpctl: error: ProxyCommand option is not supported

scp

scp is not supported yet.