Multi Agent: Seamless SSH Usage Guide

Seamless SSH is a feature that allows you to connect to servers via QueryPie while maintaining your existing terminal usability. This document outlines the usage, specifications, and support scope for Seamless SSH, based on QueryPie version 10.2.8.

How to Use

SSH Config Setup Method

To use your standard ssh commands, you can configure your SSH config file.

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

CODE

cd ~/.ssh
vi config

Add the following configuration to your config file, then save and exit (press :wq then Enter)

CODE

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

If your server URLs and ports do not overlap, you can also use a wildcard configuration:

CODE

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

Connect to your server using a simplified SSH command:

CODE

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

Shell Alias Setup Method

You can set up a shell alias to use your existing ssh commands.

Open your shell configuration file

For Bash shell:

CODE

vi ~/.bashrc

For Zsh shell:

CODE

vi ~/.zshrc

Add the following line to your shell configuration file, then save and exit (press :wq then Enter):

CODE

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

Apply the changes to your current shell session:

For Bash shell:

CODE

source ~/.bashrc

For Zsh shell:

CODE

source ~/.zshrc

Alternatively, you can open a new terminal window.

Connect to your server using the alias.

CODE

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

Differences from the Existing QueryPie User Agent

Basic Command

Seamless SSH operates using the qpctl ssh-proxy command, which is installed alongside the QueryPie Multi Agent.

CODE

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

Command for User Agent:

CODE

qpa ssh %r %h %p

Connection Error Display Method

Previously, if an error occurred while connecting to the QueryPie Proxy server, the User Agent would display a dialog box, which was not terminal-friendly.

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

CODE

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

Newly Added Features

Specify Default Host

Multi Agent previously required you to specify the QueryPie Host URL for Seamless SSH, which could be inconvenient.

A feature has been added to specify a default QueryPie Host for qpctl commands.

If a default host is specified, you do not need to enter the QueryPie Host in the qpctl ssh-proxy command.
If you explicitly provide a QueryPie Host in the command, that value will be used, overriding the default.

Resetting the app via Reset All Settings will also delete the default host setting.

qpctl host list

This command checks the list of currently registered QueryPie Hosts.

This is not necessarily the QueryPie Host currently selected in the Agent UI.

CODE

$ 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

This command displays the list of registered QueryPie Hosts and allows you to select one using the arrow keys.

CODE

$ 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

CODE

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

qpctl host use {QueryPie Host}

CODE

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

⚠️ Experimental Feature: Direct qpctl Usage ⚠️

Setting up ~/.ssh/config or typing ssh -o ProxyCommand="qpctl ssh-proxy ... can be cumbersome. Therefore, if you have QueryPie Multi Agent installed, you can use the qpctl command directly for SSH connection.

Simply prefix your usual ssh command with qpctl

CODE

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

This also works with host configurations defined in your ~/.ssh/config:

CODE

$ 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 version 6.7 or later is required.

CODE

$ ssh -V
OpenSSH_9.8p1, LibreSSL 3.3.6

How it Works

The qpctl command wraps your ssh client command, automatically appending the necessary ProxyCommand option.

qpctl ssh command_line
ssh -G command_line
1. username, hostname, port extraction
ssh command_line -o ProxyCommand=”qpctl ssh-proxy username hostname port”

Unsupported Features

Custom ProxyCommand

Since qpctl uses the ProxyCommand option internally, you cannot specify your own custom ProxyCommand when using qpctl ssh.

CODE

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

scp

The scp command is not yet supported with this Seamless SSH method.