cz-setup and cz-config commands

Prev Next

These commands are run from the SSH command line.


cz-setup

You can run cz-setup at any time on a seeded appliance. You can also use it to create the first Controller. To use cz-setup, you must be root:

sudo cz-setup

AppGate setup screen showing options to change password and configure settings.

The following table describes available actions:

Action

Description

passwd

Change the cz user password. This applies only if password authentication is in use.

log levels

Changes the daemon log level on the appliance. For more information, refer to Daemon logs.

nics

Assigns eth0, eth1, and so on to the network cards found in the system. This assignment happens automatically, but you may need to use this action when adding or changing cards in an existing system.


cz-config commands

cz-config <action> is a family of commands to manage and configure the appliance at runtime. To see the full list of commands, enter cz-config --help. To see help for a specific command, enter cz-config <action> --help.

To use cz-config, you must be root:

sudo cz-config <action>

The following table describes available commands:

Subject

Action

Description

Alternative default route

set gateway/vpn/overrideRouteVia/ipv4 10.10.10.10
set gateway/vpn/overrideRouteVia/ipv6 ::1

del gateway/vpn/overrideRouteVia​

Overrides the Alternative default route for all user traffic setting in Sites. This is useful when some Gateways on a Site are in different physical locations. To undo the override, use the del option..

App discovery - disable

set -j gateway/disableAppDiscovery true

Stops the Gateway from sending app discovery data. The default is false.

App health slow-script thresholds

set -j gateway/appHealth/appHealthLongRunningScriptWatermark <value>

set -j gateway/appHealth/appHealthLongRunningScriptCleanoutTTLSeconds <value>

appHealthLongRunningScriptWatermark sets the percentage of users with slow scripts (0–100) before the Gateway raises a warning; the default is 50. appHealthLongRunningScriptCleanoutTTLSeconds sets the time to live, in seconds, of slow-script entries; the minimum is 60 and the default is 1200.

Appliance customization

set -j customization/enabled true/false

Enables or disables appliance customizations.

Appliance hardening

set -j hardening/auditd true
set -j hardening/blacklistUsbStorage true
set -j hardening/hardenSSH true
set -j hardening/hardenJournalDirectory true

auditd enables the auditd service. blacklistUsbStorage adds the usb-storage kernel module to the denylist. hardenSSH applies a stricter sshd configuration. hardenJournalDirectory applies stricter permissions to the journal directory. The default for each setting is false.

Appliance OS hostname

set osHostname foo.example.com

Changes the internal hostname (osHostname) used by the system. This is normally set to the appliance hostname. If an IP address (for example, 1.2.4.8) was used for the appliance hostname, appgate-1_2_4_8 is generated instead. Use this command to change the osHostname if needed.

Appliance status

status

Shows metadata and status of the current appliance.

Appliance upgrade

upgrade

Upgrades the appliance. See Upgrading an appliance for more information.

Appliance wipe

wipe-appliance --force

Wipes the appliance and returns it to a waiting_config state. Re-seeding is required after running this command.

Asymmetric routing

set -j networking/allowAsymmetricRouting '["eth1"]'

Allows asymmetric routing on the listed network interfaces. The default is an empty list.

Audit logging

set -j audit/enabled false

Enables or disables audit logs. Setting this to false stops audit logs from all daemons. The default is true.

AWS name resolution

set -j gateway/nameResolution/aws/resolveRemote true

set -j gateway/nameResolution/aws/maxJitterAccounts <seconds>

resolveRemote fetches only AWS load balancer metadata; the default is false. maxJitterAccounts sets the jitter, in seconds, for AWS account updates; the default is 15.

Browser SSH and RDP session limits

set -j gateway/maxSshSessions <value>

set -j gateway/maxRdpSessions <value>

Sets the maximum number of browser-based SSH and RDP sessions (guacd) on the Gateway. The default is 1000 for SSH and 100 for RDP. Setting the value to 0 turns off the session type.

Certificate add

keytool import --alias certname --certificate /path/to/cert

Adds additional certificates to Java using keytool. --alias ALIAS specifies the alias for the certificate. --certificate FILENAME specifies the file containing the certificate. Use - to read from stdin..

Claroty CTD name resolution

set -j gateway/nameResolution/clarotyCtd/resolveRemote true

Resolves each name against Claroty CTD. The default is false.

Client request rate limiting

set -j controller/clientRequestRateLimitFactor X

del controller/clientRequestRateLimitFactor

Limits the rate of client requests to the Controller. X accepts the following values: a positive number sets the rate limit to X × vCPU count (for example, X=4 on a four-vCPU appliance limits to 16 requests per second); a negative number sets an absolute rate limit (for example, X=-10 limits to 10 requests per second); 0 disables rate limiting. The rate limit is calculated as an average over a two-second sliding window, which allows bursts as long as the average stays below the limit. The default is 0 (disabled). To remove the rate limit factor, use the del option.

Configuration apply

apply

Reapplies the current configuration.

Configuration rollback

rollback-configuration

Rolls back to the previous configuration received from the Controller. The previous configuration is always retained; this command makes it the current configuration.

Configuration update

pull-configuration

Forces the appliance to pull a new configuration from the Controller. If the appliance is a Controller, it reapplies the configuration already registered within it.

Connection rate limiting

set -j controller/clientRateLimitFactor X
set -j gateway/clientRateLimitFactor X

del controller/clientRateLimitFactor
del gateway/clientRateLimitFactor

Limits the rate of new client connections to Controllers and Gateways. X accepts the following values: a positive number sets the rate limit to X × vCPU count (for example, X=4 on a four-vCPU appliance limits to 16 connections per second); a negative number sets an absolute rate limit (for example, X=-10 limits to 10 connections per second); 0 disables rate limiting. The rate limit is calculated as an average over a five-second sliding window, which allows bursts as long as the average stays below the limit. The default is 4 for both Gateways and Controllers. If both a Controller and Gateway rate limit factor are set on the same appliance, the Controller value is used. To remove the rate limit factor, use the del option.

Connection state limits

set -j gateway/connectionStateLimit <value>

set -j gateway/connectionStateTimeout <value>

connectionStateLimit sets the maximum number of connection states on the Gateway. connectionStateTimeout sets the maximum time connection states are kept. Both default to null (not set).

Connector status

connector status

Shows the status and configuration of the Connector, including VRRP high availability configuration.

Connector HA

vrrp status

set vrrp/advert_int 2

set vrrp/nopreempt False

Displays the Virtual Router Redundancy Protocol (VRRP) NIC configuration, including the virtual IP in use. advert_int sets the advertisement interval in seconds; the default is three seconds and must match on all hosts sharing the virtual IP. nopreempt allows a lower-priority machine to maintain the primary role even when a higher-priority machine comes back online; the default is True.

Controller BDR allowed IPs

set -j controller/bdrAllowedIps '["10.0.0.5", "10.0.0.6"]'

Limits the source IP addresses allowed for BDR database replication. An empty list allows all source IPs. The default is an empty list.

Controller DB replication

bdr

Commands related to BDR database replication troubleshooting. See Appliance commands reference for more information.

Controller hostname check

set -j controller/checks/uniqueHostname false

Checks that the Controller hostname resolves to one IP address. The default is true.

Controller maintenance mode

set -j controller/maintenance true

Runs the Controller in read-only mode. The default is false.

Controller switch CA

ca-switch

Triggers an appliance CA certificate switch

Controller switch CA status

ca-switch-status

Shows the appliance CA certificate switch status.

Controller nearest Site

set -j controller/localSiteIsAlwaysNearest true

Includes local Sites in nearest site detection, even when Use for nearest site selection is not enabled in the Site. The default is false.

CRL update

update-crl

Checks the CRL Distribution Point URL and downloads the latest CRL. See Internal certificates for more information.

CZ user

user

Settings for the default cz user.

Daemon log levels

set logLevels/<daemon> DEBUG

Sets the log level for a daemon. Valid levels are DEBUG, INFO, WARNING, ERROR, and CRITICAL; enter the level as a string without -j. The default is INFO, except coredns and nginx@main, which default to ERROR. <daemon> accepts coredns, proxyd, configd, replicationd, nginx@main, nginx@admin, agentx, controllerd, vpnd, gonamed, guacd, had, nginx@urlaccess, sessiond, logd, connector, clientd, nginx@portal, webd, dbd, staffetta, geoip, and otel_collector.

NOTE

Changing a log level may restart the daemon.

Detect termination of client-appliance connections

set -j reportBogusTLS/enabled true

Detects man-in-the-middle (MitM) issues caused by firewalls or network devices terminating the client connection. When a TLS connection lacks the expected extensions, the appliance raises a five-minute warning that includes the source IP and port to help identify misconfigured devices. .

NOTE

This command generates significant system activity during normal operations. Use it only when troubleshooting.

Disk partitions

switch-partition

Changes the partition in use. When an appliance is upgraded, the previous version is retained on a separate partition. Use this command to revert the system to its previous state after an unsuccessful upgrade.

DNAT Connectors

set -j dnatConnectors '{"<connector>": true}'

Sets the listed Connectors to DNAT mode. The default is null.

DNS proxy minimum TTL

set -j gateway/dnsProxy/minTTL <seconds>

Sets the minimum time to live (TTL), in seconds, on client DNS proxy responses. The default is null (not set).

DNS resolver options

set -j dnsOptions '["single-request-reopen"]'

Sets extra options in resolv.conf. The default is ["single-request-reopen"].

Gateway default VPN policy

set networking/vpnDefaultPolicy Mark

Sets how the Gateway handles packets that do not match any rule. Valid values are Drop and Mark. The default is Drop.

Gateway Java heap

set -j gateway/maxJavaHeapPercentage <value>

Sets the percentage of memory available to the sessiond Java heap. Valid values are 25–75. The default is null (not set).

GCP OS Login

set -j oslogin/instanceEnabled true

Enables Google Cloud Platform (GCP) OS Login for the host instance. The default is false.

GeoIP edition

set geoip/maxmind/editionId <edition>

Sets the MaxMind GeoIP edition. The default is GeoIP2-City.

GRUB edit lock

set -j kernel/lockGrubEdit true

Blocks editing of GRUB entries at boot. The default is false.

IPv6 disable

set kernel/cmdlineOptions "ipv6.disable=1"

Disables IPv6 in the kernel. The appliance must be rebooted for this to take effect.

Kernel sysctl overrides

set -j kernel/sysctlOverrides '{"net.core.somaxconn": 4096}'

Overrides kernel sysctl values. The default is an empty object.

Log download

collect-logs

Collects appliance logs in the same way as the admin UI. Useful when the Controller is unavailable. Use -h to show optional arguments.

Log forwarding to ZTP

set -j logd/ztp/advisor/forwardLogs false

Forwards logs to the advisor ecosystem. The default is true.

Log limiting

set -j audit/maxLogsOnDisk <value>

Sets the maximum number of log records that logd saves to disk. The default is 100,000.

logd REST forwarding

set -j logd/enableRest false

set -j logd/restServerConcurrentMessageLimit <value>

set -j logd/restServerConcurrentBatchTimeout <value>

enableRest set to false limits logd to legacy RELP forwarders; the default is true. restServerConcurrentMessageLimit sets the maximum number of concurrent messages; the default is 16000. restServerConcurrentBatchTimeout sets the wait timeout before starting a new batch; the default is 10.

Management network interface

set -j networking/managementNic '{"nic": "eth1", "routes": [{"address": "10.97.235.67", "netmask": 32, "gateway": "10.97.174.3"}]}'

set -j networking/managementNic '{"nic": "eth1", "routes": [{"address": "10.97.235.67", "netmask": 32, "gateway": "10.97.174.3"}], "services": ["icmp", "api"]}'

set -j networking/managementNic '{"nic": "eth1", "routes": [{"address": "10.97.235.67", "netmask": 32, "gateway": "10.97.174.3"}], "services": ["icmp", "api", ["custom-service", "tcp", 6666]]}'

del networking/managementNic

Routes the following services to the specified management interface: SSH, ICMP, SNMP, and Prometheus. These services are no longer available through the normal network interface when this command is used without the services option. When services is specified, only the listed services are routed. To include the admin API in addition to the defaults, specify: ssh, icmp, snmp, prometheus, and api. To add a custom protocol, specify a name, protocol (TCP or UDP), and port. To remove the management interface configuration, use the del option.

Martian packet logging

set -j networking/logMartians true

Logs IPv4 packets with impossible addresses. The default is false.

Message of the day

set motd/message "<text>"

set motd/issue "<text>"

set motd/issue.net "<text>"

message sets a custom message of the day. issue sets the content of /etc/issue. issue.net sets the content of /etc/issue.net. The default for issue and issue.net is the standard authorized-use banner.

NAT traversal

set -j natt/stunKeepaliveInterval <seconds>

set -j natt/stunPoolSize <value>

set -j natt/relaySessionsThreshold <value>

set -j natt/relayThroughputBitsPerSecondThreshold <value>

stunKeepaliveInterval sets the STUN keepalive interval, in seconds, for NAT mappings; the default is 15. stunPoolSize sets the number of pre-opened STUN UDP sockets per Connection Broker; the value must be greater than 0 and the default is 500. relaySessionsThreshold sets the relay sessions statistics threshold; the default is 1000. relayThroughputBitsPerSecondThreshold sets the relay throughput statistics threshold; the default is 8000000000.

Network interface assignment

set -j nicAssignments '[{"name": "eth0", "mac": "aa:bb:cc:dd:ee:ff"}]'

Pins an ethN interface name to a MAC address. The default is an empty list.

NIAP compliance mode

set -j logd/niapComplianceMode true

Uses the WolfSSL FIPS TLS stack for logd to meet NIAP requirements. The default is false.

OpenSearch

set -j runOpensearch true

Runs OpenSearch on the appliance. The default is false.

Post-quantum hybrid encryption

set tls/pq true -j

Enables post-quantum hybrid encryption.

Replication retries

set -j replicationd/retryLimit <value>

set -j replicationd/retryBackoffSeconds <seconds>

set -j replicationd/replicationIntervalSeconds <seconds>

retryLimit sets the maximum number of connection attempts per replication job; the default is 3. retryBackoffSeconds sets the backoff between attempts; the default is 5. replicationIntervalSeconds sets the interval between replication runs; the default is 900.

Resolver error calls before clearing the address cache

set -j gateway/nameResolution/nameMaxAllowedErrors <value>

Sets the number of allowed error calls before the address cache is cleared. The default is 10 error calls. The time before clearing is a multiple of the update interval of each resolver.

Rotate claims keys

rotate-claims-keys

Rotates the keys used to encrypt claims tokens.

Routing tables

set -j networking/customRoutingTables '[{"name": "<name>", "id": <id>, "routes": [...], "rules": [{"src": ..., "iif": ..., "fwmark": ..., "ip_version": ...}]}]'

Adds extra routing tables. Each table id must be unique. The default is an empty list.

Scripts HTTP use

set -j policyEvaluator/allowUnsafeHttp true

set -j policyEvaluator/allowUnsafeHttpRedirection true

Enables HTTP for external calls from the JavaScript engine used in Controllers and Gateways when running scripts.

SSH authentication attempts

set -j sshServer/max_auth_tries <value>

Sets the maximum number of SSH authentication attempts (sshd MaxAuthTries). The default is 4.

SSH keys regenerate

regenerate-ssh-keys

Regenerates the SSH host keys.

SPA add rules

set -j spa/allowTcpSubnets '["192.168.1.0/24", "2010:2000:4e43:d406:8055:408d:e018:b360"]'

Adds IPv4 and/or IPv6 subnets to iptables when a valid SPA packet is received, in addition to the original IP address. This applies when an IP is authorized with SPA in UDP-TCP mode. For example, with subnets 192.168.1.0/24 and 2010:2000:4e43:d406:8055:408d:e018:b360 configured, authorizing IP 74.73.54.4 adds 74.73.54.4, 192.168.1.0/24, and 2010:2000:4e43:d406:8055:408d:e018:b360 to iptables.

SPA add mapped rules

set -j spa/allowMappedTcpSubnets '["10.10.0.0/16", "11.11.11.0/24"]'

Adds mapped IPv4 and/or IPv6 subnets to iptables instead of the original IP address when a valid SPA packet is received in UDP-TCP mode. For example, with subnets 10.10.0.0/16 and 11.11.11.0/24 configured, authorizing IP 74.73.54.4 adds 10.10.54.4 and 11.11.11.4 to iptables.

SPA get rules

get spa

Shows the currently configured subnets and mapped subnets added to iptables when a valid SPA packet is received in UDP-TCP mode.

Spectre/Meltdown mitigations

set kernel/cmdlineOptions mitigations=off

Removes x86 architecture mitigations. Mitigations are not required when the machine running the appliance is dedicated rather than shared. Removing them can produce significant performance improvements. AppGate ZTNA appliances ship with mitigations off by default.

NOTE

The appliance must be rebooted after running this command. This command removes mitigations only from the AppGate ZTNA appliance. To realize the full performance benefit, mitigations must also be removed from the host.

sysstat collection

set -j sysstat/enabled true

set -j sysstat/interval <minutes>

enabled turns on sysstat (sar) collection; the default is false. interval sets the collection interval in minutes; the default is 10.

Telemetry collector

set telemetry/journaldReceiverPriority <priority>

set -j telemetry/queueSize <value>

set -j telemetry/retryPeriod <seconds>

set -j telemetry/applianceWarningEnabled false

set -j telemetry/queuePressureWarningThreshold <value>

set -j telemetry/tailSamplingDecisionWait <seconds>

set -j telemetry/tailSamplingNumTraces <value>

journaldReceiverPriority sets the minimum journald priority collected (debug, info, warning, or err); the default is warning. queueSize sets the exporter queue size in items; the default is 100000. retryPeriod sets the maximum retry time per batch in seconds, where 0 retries forever; the default is 600. applianceWarningEnabled raises warnings about collector pipeline health; the default is true. queuePressureWarningThreshold sets the queue ratio (0–1) that raises a warning; the default is 0.7. tailSamplingDecisionWait sets the wait in seconds before a trace sampling decision; the default is 30. tailSamplingNumTraces sets the maximum number of traces kept for sampling; the default is 50000.

Auto suspend (under heavy load)

get gateway/suspendWatermarks

get gateway/suspendWatermarks/numberOfSessions

set -j gateway/suspendWatermarks/numberOfSessions/high 50

set -j gateway/suspendWatermarks/numberOfSessions/low 40

set -j gateway/suspendWatermarks/numberOfSessions/enabled false

del gateway/suspendWatermarks/numberOfSessions

Gets all watermarks for auto-suspend;

gets a specific watermark; sets the high threshold for a specific watermark; sets the low threshold for a specific watermark; disables a specific watermark; restores the defaults for a specific watermark.

Connection Broker auto suspend (under heavy load)

get connectionBroker/suspendWatermarks

set -j connectionBroker/suspendWatermarks/<measure> '{"low":<value>,"high":<value>,"enabled":true}'

del connectionBroker/suspendWatermarks/<measure>

Automatically suspends the Connection Broker when a measure reaches its high watermark. <measure> accepts systemMemoryUsage (default high 85%, low 70%), relaySessions (default high 5000, low 4500), and relayThroughputBitsPerSecond (default high 1, low 0; disabled by default). The high value must be greater than the low value. To restore the defaults for a measure, use the del option.

Gateway auto suspend measures

set -j gateway/suspendWatermarks/<measure> '{"low":<value>,"high":<value>,"enabled":true}'

Sets all thresholds for one Gateway auto-suspend measure in one command. The Gateway suspends when any measure reaches its high value and resumes when all measures are at their low value. <measure> accepts numberOfSessions (default high 8000, low 7500), eventQueueUsage (default high 70%, low 50%), javaHeapUsage (default high 90%, low 75%), and systemMemoryUsage (default high 85%, low 70%). The high value must be greater than the low value.

URL access override

set -j gateway/forwardToNginx true/false

Overrides URL access handling on a Gateway. Setting this to false causes all HTTP up actions to fall back to TCP up actions for the given Gateway. Entitlement tokens must be renewed for the change to take effect. Size and number of Gateways should be specified for the expected load rather than using this setting for normal operations.

URL access shared memory

set gateway/urlAccessSharedMemorySize 64m

Sets the nginx URL access shared memory size on the Gateway. The default is 64m.