The Signadot CLI provides a command-line interface to the Signadot API and support for running Local Workloads within Sandboxes.
Installing the CLI
To install the CLI, download and extract the latest release archive for your platform, or use Homebrew (on either macOS or Linux):
brew tap signadot/tap
brew install signadot-cli
The CLI can also be installed and run on-demand via its docker image
Upgrading the CLI
If you used brew, you can run the following commands to upgrade the CLI installation.
brew upgrade signadot-cli
The CLI reads configuration from a file stored at
This file contains information for using the CLI as an interface to Signadot API
and also for running Local Sandboxes. Some parameters in this file can also be
set via environment variables.
To talk to the Signadot API, the CLI needs your Signadot org name as well as a Signadot API key, which you can generate in the dashboard.
These values can be provided in a file stored at
Or you can provide them as environment variables:
Local configuration is intended for versions v0.5.0+ of the Signadot CLI.
To configure the CLI for running Local Workloads as part of sandboxes, you will
need to add a section
local to your config file. Here is a minimal
section to get up and running:
- cluster: staging # signadot cluster name
kubeContext: staging-context # kubecontext name for the cluster
It is comprised of a list of connections, each of which defines parameters for communicating directly with a single Kubernetes cluster.
clusterfield specifies the name of the Signadot cluster. You can find this value via the dashboard. This field will also correspond to the cluster field in the sandbox specification.
kubeContextfield specifies the name of the corresponding context in your kubeConfig file.
Advanced Local Configuration
type defines the connection method. It can be one of
ProxyAddress. If unspecified, it defaults to
uses Kubernetes Port
to access the cluster. Under the hood, it accesses a SOCKS5 proxy running as
part of the Signadot Operator.
type: ProxyAddress is intended for a case where a cluster administrator makes
the SOCKS5 proxy available to the local machine, for example by exposing a
LoadBalancer pointing to the SOCKS5 proxy within a VPN. When doing so, the
SOCKS5 proxy is given a TCP address. With
type: ProxyAddress, one does not
need to specify
For example, assuming a the SOCKS5 proxy is available at
- cluster: staging
outbound defines a parameter for excluding traffic destined to certain
addresses in the cluster from being routed to the cluster.
- cluster: ...
inbound defines the protocol used for tunneling requests to the local
workstation. It can be one of
xap is a Signadot developped
tunneling protocol and
ssh uses the on-the-wire protocol that the ssh command
uses for reverse tunneling.
- cluster: ...
MacOS Performance Bug
MacOS has a subtle bug with
the performance of its packet filter
pf when redirecting traffic, related to
TCP segmentation offloading, which is an optimization to compute tcp segments on a
network device instead of with the CPU.
By default, TCP segmentation offloading is on on MacOS. However when
MacOS is configured to redirect traffic with
pf, such offloading
causes severe performance penalties, particularly in the latency
of setting up TCP connections.
The Signadot CLI support for local workloads in sandboxes uses
to redirect traffic and is impacted by this bug.
If you are seeing performance issues on MacOS traffic from a workstation to a connected cluster, the fix is to disable TCP segmentation offloading, which can be done as follows:
sudo sysctl -w net.inet.tcp.tso=0
However, the above command only disables TSO until the next reboot. We recommend turning off TSO permanently on the machine, since testing has shown no negative impact in doing so.
To turn off TSO permanently on MacOS create a file /Library/LaunchDaemons/sysctl.plist (or add to it):
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
And then run
sudo launchctl load /Library/LaunchDaemons/sysctl.plist
On MacOS, if the cluster to which you'd like to connect is on a VPN which uses
a network interface other than
en0, you will need to specify the VPN interface
in the CLI configuration:
- cluster: cluster-on-vpn
You can find the VPN interface on MacOS using
ifconfig. It is typically a
which is up and has a peer defined. For example
% ifconfig utun6
utun6: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1500
inet 10.6.1.2 --> 10.6.1.1 netmask 0xffffffe0