Using SSH to administer appliances
SSH is configured when an appliance is created and supports password or public key authentication. Cloud deployments support only the cloud-provided public key method. AppGate ZTNA appliances support passwordless sudo after you sign in. Passwordless sudo is available only when a public key is set for SSH access and no SSH password is set. Commands run on one appliance at a time, so if you want to change SSH keys on all members of the Collective, you must perform the change on each appliance individually.
Temporary file system
The AppGate ZTNA appliance file system is read-only except for /mnt/data. Some other directories are bound to /mnt/data to make them persistent. Any files saved outside these directories are deleted on reboot. The read-only file system serves two purposes:
It prevents interference with the AppGate ZTNA appliance, because all changes are lost on reboot.
It makes it straightforward to root-cause issues caused by third-party executables, because the system always returns to its original state.
AppGate ZTNA runs on OverlayFS, a temporary file system that reloads every time the system boots. Changes made from the command line to the running system are non-persistent, including any additional users created—these are deleted automatically if the appliance is rebooted.
Third party executables can be saved persistently. For other persistent changes, use cz-config or cz-iptables.
Restricting access to port 22
See System security - best practices for more information about securing SSH access to your appliance. You can disable the SSH server completely in appliance settings.
Port 22 access to a Connector with no static IP address
If a Connector is deployed on a network without a fixed or public IP address, you may be unable to reach port 22 on the appliance. In this case, configure port 22 access through the tunnel as described in System security - best practices.
To SSH to a Connector with no fixed or public IP address, a tunneled connection runs from the user's AppGate ZTNA client through a Gateway to the Connector, where it loops back to itself. The principle of operation is the same for Express and Advanced Connectors, but the implementation details differ.

Connector
For Express:
Edit the Connector function on your Connector appliance. Refer to Adding a Connector.
Add a local resource as the static IP address of the Connector with a
/32subnet for IPv4 or/128for IPv6.
For Advanced:
Edit the Connector function on your Connector appliance. Refer to Adding a Connector.
Identify a secondary static IP address and assign it as an IP alias on the existing network interface, or as a static IP on an additional network interface such as
eth1.Disable Source NAT from Local Resources. This makes the Connector reachable by the secondary IP address.
Add a client—specify a name and define the local resources as the secondary IP address of the Connector with a
/32subnet for IPv4 or/128for IPv6.
Site
Configure a Site where the user and Connector will rendezvous. The Connector's client and the user's client must rendezvous at the same Gateway. If a Site has more than one Gateway, this is handled automatically for Express Connectors. For Advanced Connectors, the entitlement handles it.
Identity Provider
Confirm that the built-in Connector identity provider has IP pools assigned for your use case (IPv4, IPv6, or both). The default IP pools can be configured to provide a larger range of IPs for virtual tunnel interfaces. Refer to IP pools for more information.
Entitlements
Create a user entitlement to allow up traffic to the IP address of the Connector—for example, TCP up to 192.168.8.250 on port 22.
For Advanced:
In the user entitlement, select Enable Monitoring so the client hunts for the Connector's Gateway to ensure a rendezvous.
Create a Connector entitlement to allow down traffic from the user's tunnel IP address—for example, TCP down from
192.168.1.20on port 22.
Policy
Confirm that your user policy includes the TCP up entitlement.
For Advanced:
Create a Connector SSH policy. To apply the policy only to that Connector client, assign it using: identity provider is
ConnectorANDuserclientNameis the name.Assign the Connector's TCP down entitlement to the SSH policy.
Client
Test access from the user client. The client should have access to port 22 on the Connector as configured in your entitlement.
Managing the SSH password
Changing the SSH password
Sign in to the appliance using SSH and run:
sudo cz-config passwd
This prompts you for your existing password and lets you enter a new one.
Removing the SSH password
To remove the SSH password, run:
sudo cz-config set -j users/0/nopasswd true
Preventing password guessing
To change the maximum number of authentication attempts permitted per connection, run:
sudo cz-config set -j sshServer/max_auth_tries 99
This setting maps to sshd's MaxAuthTries. Once the number of failures reaches half the configured value, additional failures are logged. The default is 6.
Disabling password authentication
Regardless of whether an SSH password is set, you can disable password authentication in the admin UI. Go to appliance settings, find the SSH Server section, and disable Password Authentication.
Managing the SSH key
Setting or changing the SSH key
When a new appliance is set up from the command line, the first Controller is seeded with a cz user password for SSH access. Cloud instances do not use this method — they require public key authentication. Public key authentication is stronger than password authentication, so change the first Controller's SSH authentication to use a public key.
Start by generating your SSH key pair.
Adding keys
To add an SSH key for the cz user on an appliance, run one of the following from the command line on the first Controller:
sudo cz-config user --authorized-keys "KEY"
where KEY is your ssh key pasted between the quotation marks (for example, "ssh-rsa AABBCCDD......").
sudo cz-config user --authorized-keys-file FILE
where FILE is the path to your SSH key file.
These commands overwrite any existing keys. To add a key without removing existing ones:
Copy
/home/cz/.ssh/authorized_keysto a new location such astemp/new_keys.Edit the new file to add the new key and save it.
NOTE
Each line can contain only one key.
Run
sudo cz-config user --authorized-keys-file FILE
Your SSH keys for the cz user are now active.
Pinning keys
To pin the keys and prevent the cloud provider from overriding them, run:
sudo cz-config user --pin {true,false}
The default is false.
You can now disable password authentication when connecting to the appliance using SSH.
Disabling password authentication
Go to appliance settings, find the SSH Server section, and disable Password Authentication.
Setting the SSH message of the day
To set a message of the day for SSH users, run:
sudo cz-config set motd/message "my message"
To remove the message, run:
sudo cz-config del motd/message
NOTE
If you use PuTTY, go to Window > Translation > Received data and set the encoding to UTF-8 to display the message correctly.