--- title: "cz-setup and cz-config commands" slug: "cz-setup-and-cz-config-commands-v7-0" description: "Commands for cz-setup and cz-config that are run from the SSH command line." tags: ["cz-config", "cz-setup", "Appliance Configuration"] updated: 2026-11-19T17:05:21Z published: 2026-11-19T17:05:21Z canonical: "support.appgate.com/cz-setup-and-cz-config-commands-v7-0" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.appgate.com/llms.txt > Use this file to discover all available pages before exploring further. # cz-setup and cz-config commands 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](/v1/docs/configuring-the-first-controller-v7-0). To use `cz-setup`, you must be root: `sudo cz-setup` ![AppGate setup screen showing options to change password and configure settings.](https://cdn.us.document360.io/e7482ce5-acfa-4c3b-b76c-b6c32472644a/Images/Documentation/ag52-config_after.png?sv=2026-02-06&spr=https&st=2026-11-21T21%3A40%3A06Z&se=2026-11-21T22%3A40%3A06Z&sr=b&sp=r&sig=6VJWg%2BSyDZcmlYagk1f8VZ0683C3YGEw7HefMspQMy4%3D) 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](/v1/docs/daemon-logs-v7-0). | | `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](/v1/docs/sdpctl-v7-0) for more information. | | Appliance wipe | `wipe-appliance --force` | Wipes the appliance and returns it to a `waiting_config` state. [Re-seeding](/v1/docs/activating-an-appliance-v7-0#manually-seeding-an-appliance) 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](/v1/docs/appliance-commands-reference-v7-0#advanced-bdr-commands) 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](/v1/docs/internal-certificates-v7-0) 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] > 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] > 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.](/v1/docs/post-quantum-hybrid-mode-v7-0) | | 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](/v1/docs/advanced-external-https-calls-v7-0) 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] > 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](/v1/docs/high-availability-ha-v7-0#autosuspend); 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`. |