This guide describes how to use the Airlock client utility — airsh.

You will learn how to:

  • Log in to the cluster and obtain a user certificate.
  • Connect to servers via SSH.
  • Work with Kubernetes clusters using kubectl.
  • Connect to databases.
  • Copy files, list nodes, and browse session recordings.

The full list of commands is also available via airsh help in the terminal.

Quick start

# Log in to the Airlock cluster. The certificate is saved to ~/.airsh/airlock.example.com
airsh login --proxy=airlock.example.com

# SSH connection to a node
airsh ssh user@node

# airsh ssh accepts the same arguments as OpenSSH:
airsh ssh -o ForwardAgent=yes user@node

# You can create a symlink:
ln -s /path/to/airsh /path/to/ssh
ssh user@host

# Remove certificates from the local machine:
airsh logout

Airlock is fully compatible with existing SSH workflows: simply run airsh login before starting work.

Installing airsh

Install the airsh binary of the same major version as the Airlock server in your cluster.

To find out the server version:

  • In the web interface, select your username in the top-right corner → Help & Support. The cluster version is shown under CLUSTER INFORMATION.
  • Via the API:
curl https://airlock.example.com/webapi/find | jq '.server_version'

User identification

A user’s identity in Airlock exists within the cluster. Nodes in the cluster may have different OS users. The Airlock administrator assigns permitted logins to each account.

When connecting to a remote node, specify the Airlock login (flag --user) and the OS login in the format login@host:

# Authenticate to cluster "work" as joe, log in to the node as root:
airsh ssh --proxy=work.example.com --user=joe root@node

Logging in to the cluster

To obtain a certificate, run:

# Full form:
airsh login --proxy=proxy_host:<https_proxy_port>

# Default ports:
airsh login --proxy=work.example.com

# Non-standard HTTPS port:
airsh login --proxy=work.example.com:5000
PortDescription
https_proxy_portHTTPS port of the proxy (default 443 or 3080)

The login command saves the certificate to ~/.airsh and to ssh-agent if it is running. By default, certificates are valid for 12 hours.

Run airsh login before other commands — then the --proxy flag can be omitted: airsh ssh user@host will work.

A cluster may support multiple identity sources. Use the --auth flag to select a connector:

# Local user admin:
airsh --proxy=proxy.example.com --auth=local --user=admin login

# SSO via GitHub (connector "github"):
airsh --proxy=proxy.example.com --auth=github login

With external authentication, airsh opens a browser. To suppress this:

airsh login --proxy=work.example.com --browser=none

The login URL will be printed to the terminal — copy it into a browser.

Viewing the certificate

airsh status

# > Profile URL:  https://proxy.example.com:3080
#   Logged in as: johndoe
#   Cluster:      proxy.example.com
#   Roles:        access, auditor, editor
#   Logins:       root, admin, guest
#   Kubernetes:   enabled
#   Valid until:  2017-04-25 15:02:30 -0700 PDT [valid for 1h0m0s]
#   Extensions:   permit-agent-forwarding, permit-port-forwarding, permit-pty

SSH-agent integration

If ssh-agent is running, airsh login saves the certificate to the agent. Verify:

ssh-add -L

To disable agent integration, pass --no-use-local-ssh-agent or set AIRLOCK_USE_LOCAL_SSH_AGENT=false.

Identity files

# Save certificate to file joe.pem:
airsh login --proxy=proxy.example.com --out=joe

# Use the file for login:
airsh ssh --proxy=proxy.example.com -i joe joe@db

For OpenSSH compatibility, add --format=openssh — files joe and joe-cert.pub will be created.

SSH access

Listing nodes

airsh ls

# Node Name     Address            Labels
# ---------     -------            ------
# turing        ⟵ Tunnel          os=linux
# graviton      10.1.0.7:3022      os=osx

# Filter by label:
airsh ls os=osx

Interactive shell

airsh ssh user@node
airsh ssh -p 6122 user@node ls
airsh ssh -o ForwardAgent=yes user@node

airsh ssh supports OpenSSH flags: -p, -l, -L, -A, and others.

Port forwarding

airsh ssh -L 5000:web.remote:80 node

The --local flag runs a local command through the tunnel:

airsh ssh -L 5000:example.com:80 --local node curl http://localhost:5000

Jump host

airsh ssh -J proxy.example.com telenode

Only one jump host is supported; with -J user@proxy, port forwarding is used instead of the Airlock proxy.

Node name resolution

  • By IP address or DNS.
  • By node name (nodename in the agent configuration).
  • By labels: airsh ssh os=osx (if there is only one matching node).

Copying files

airsh scp example.txt root@node:/path/to/dest
scp -P 61122 -r files root@node:/path/to/dest

Airlock supports SCP and SFTP protocols.

Session sharing

On the remote server, run:

airlock status
# Session ID : 7645d523-60cb-436d-b732-99c5df14b7c4
# Session URL: https://work:3080/web/sessions/7645d523-...

Another user can join:

airsh join <session_ID>

Joining sessions requires special permissions configured by the administrator.

Kubernetes access

List available clusters:

airsh kube ls

# Kube Cluster Name Labels                      Selected
# ----------------- --------------------------- --------
# mycluster         env=dev

Log in to a cluster:

airsh kube login mycluster
# Logged into kubernetes cluster "mycluster". Try 'kubectl version' to test the connection.

After airsh kube login, the kubeconfig is updated. Then use kubectl:

kubectl get pods

airsh kube login flags:

FlagDescription
--allGenerate kubeconfig for all available clusters
--asKubernetes user for impersonation
--as-groupsKubernetes group for impersonation
--clusterAirlock cluster name (for leaf clusters)
-n, --kube-namespaceDefault namespace

Database access

List available databases:

airsh db ls

# Name                    Description  Allowed Users   Labels  Connect
# mysql-server1           ...          [alice]         env=dev airsh db connect mysql-server1

Direct connection via airsh

For MySQL/MariaDB, the mysql client is required:

airsh db connect --db-user=alice --db-name=airlock_example mysql-server1

Local tunnel

For GUI clients or other database types, create a local tunnel:

airsh proxy db mysql-db --db-user=alice --tunnel
# Started authenticated tunnel for the MySQL database "mysql-db" on 127.0.0.1:49415.

# Connect:
mysql --port 49415 --host localhost --protocol TCP

With TLS routing:

airsh proxy db --port 10700 mysql-db
# Started DB proxy on 127.0.0.1:10700

Session recordings

airsh recordings ls

airsh play <session-id>

airsh configuration

Configuration files:

  • /etc/airsh.yaml — global configuration (overridden by AIRLOCK_GLOBAL_AIRSH_CONFIG).
  • ~/.airsh/config/config.yaml — user configuration.

User configuration takes precedence over global.

Aliases

aliases:
    "l": "airsh login --auth=local"
    "status": "airsh status --format=json"

Additional HTTP headers

add_headers:
  - proxy: "*.example.com"
    headers:
      foo: bar

Trusted clusters

airsh --proxy=work clusters

# Cluster Name     Status
# staging          online
# production       offline

airsh --proxy=work ls --cluster=production
airsh --proxy=work ssh --cluster=production db-1

Additional resources

    ←
    Access policies (RBAC) / Access to databases
    User guide / Access Requests
    →