SSH command line

Prev Next

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.

Network diagram showing connections between clients, Connectors, and Gateways with IP addresses.

Connector

For Express:

  1. Edit the Connector function on your Connector appliance. Refer to Adding a Connector.

  2. Add a local resource as the static IP address of the Connector with a /32 subnet for IPv4 or /128 for IPv6.

For Advanced:

  1. Edit the Connector function on your Connector appliance. Refer to Adding a Connector.

  2. 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.

  3. Disable Source NAT from Local Resources. This makes the Connector reachable by the secondary IP address.

  4. Add a client—specify a name and define the local resources as the secondary IP address of the Connector with a /32 subnet for IPv4 or /128 for 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:

  1. In the user entitlement, select Enable Monitoring so the client hunts for the Connector's Gateway to ensure a rendezvous.

  2. Create a Connector entitlement to allow down traffic from the user's tunnel IP address—for example, TCP down from 192.168.1.20 on port 22.

Policy

Confirm that your user policy includes the TCP up entitlement.

For Advanced:

  1. Create a Connector SSH policy. To apply the policy only to that Connector client, assign it using: identity provider is Connector AND userclientName is the name.

  2. 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:

  1. Copy /home/cz/.ssh/authorized_keys to a new location such as temp/new_keys.

  2. Edit the new file to add the new key and save it.

    NOTE

    Each line can contain only one key.

  3. 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.