Skip to content

proxy command group

proxy manages the global administrator egress-proxy configuration for {{ product_name }}. The configuration controls how administrator-facing runtime traffic (for example CRL and OCSP fetches) leaves the network: the URI policy that constrains destinations, the proxy transport mode, and optional proxy authentication.

The proxy commands are remote gRPC calls. Before running any of them you must create a host profile with profile hosts create and authenticate with profile authn login. Use the global -p/--profile option (default default-admin) before the command path to select a host profile for a single invocation.

Partial-merge update model

proxy update performs a read-modify-write: it first reads the current configuration, applies only the options you supply on top, and sends the merged result back. Options you omit are left unchanged. There is no separate create command; proxy update both initializes and edits the configuration.

Commands in this group

Command Purpose
proxy view Display the current administrator proxy configuration
proxy update Apply a partial update to the administrator proxy configuration
proxy backup Back up the configuration to a binary .pb file or screen
proxy restore Restore the configuration from a binary .pb backup

Typical workflow

  1. Inspect the current configuration with proxy view.
  2. Apply changes with proxy update (only the supplied options are merged in).
  3. Capture a backup before larger changes with proxy backup.
  4. Roll back when needed with proxy restore.

Group help

bin/admin.sh proxy --help

proxy view

Display the current global administrator egress-proxy configuration. The authentication password is never returned; the reply reports only whether one is configured.

Syntax

bin/admin.sh proxy view [options]

Required options

This command has no command-specific required options.

Optional options

Show optional options
Option Default Description
-f, --out-format YAML Output format: JSON or YAML

Example

bin/admin.sh proxy view -f json

proxy update

Apply a partial update to the administrator proxy configuration. Every option below is optional; an option you do not supply leaves its current value unchanged. Supplying --proxy-auth-password replaces the stored credential, and omitting it preserves the stored password.

Syntax

bin/admin.sh proxy update [options]

Required options

This command has no command-specific required options. Supply only the options whose values you want to change.

Optional options

Show optional options
Option Default Description
--proxy-name unchanged Proxy profile name
--proxy-uri-policy-mode unchanged URI policy mode (PROXY_URI_POLICY_MODE_HTTP_HTTPS_ONLY, PROXY_URI_POLICY_MODE_ALLOWLIST_HOSTS, PROXY_URI_POLICY_MODE_ALLOWLIST_SUFFIXES, PROXY_URI_POLICY_MODE_CUSTOM)
--proxy-uri-allowed-hosts unchanged Comma-separated allowed URI hosts; when supplied, replaces the whole list
--proxy-uri-allowed-suffixes unchanged Comma-separated allowed URI host suffixes; when supplied, replaces the whole list
--proxy-uri-allowed-ports unchanged Comma-separated allowed URI destination ports (1-65535); when supplied, replaces the whole list
--[no-]proxy-uri-deny-private-networks unchanged Deny proxying to private-network targets
--proxy-mode unchanged Proxy transport mode (PROXY_MODE_SYSTEM_DEFAULT, PROXY_MODE_NO_PROXY, PROXY_MODE_HTTP_PROXY, PROXY_MODE_DUAL_PROXY, PROXY_MODE_CUSTOM)
--proxy-http-host unchanged HTTP proxy host
--proxy-http-port unchanged HTTP proxy port
--proxy-https-host unchanged HTTPS proxy host
--proxy-https-port unchanged HTTPS proxy port
--[no-]proxy-auth-enabled unchanged Enable proxy authentication
--proxy-auth-username unchanged Proxy authentication username
--proxy-auth-password unchanged Proxy authentication password (replaces stored value; omit to preserve it)
-f, --out-format YAML Output format: JSON or YAML

Merge semantics and recommended option pairings

  • The update is a partial merge: omitted options keep their current value, so you only need to pass the fields you want to change.
  • List options (--proxy-uri-allowed-hosts, --proxy-uri-allowed-suffixes, --proxy-uri-allowed-ports) replace the entire stored list when supplied; pass the complete intended set.
  • For a working configuration, pair the values that belong together:
    • --proxy-uri-policy-mode PROXY_URI_POLICY_MODE_ALLOWLIST_HOSTS with --proxy-uri-allowed-hosts.
    • --proxy-uri-policy-mode PROXY_URI_POLICY_MODE_ALLOWLIST_SUFFIXES with --proxy-uri-allowed-suffixes.
    • --proxy-mode PROXY_MODE_HTTP_PROXY with --proxy-http-host and --proxy-http-port.
    • --proxy-mode PROXY_MODE_DUAL_PROXY with --proxy-http-host, --proxy-http-port, --proxy-https-host, and --proxy-https-port.
    • --proxy-auth-enabled with --proxy-auth-username and --proxy-auth-password.
  • Omitting --proxy-auth-password preserves the stored password; supplying it replaces the stored value.

Example (HTTP proxy + host allowlist)

bin/admin.sh proxy update \
  --proxy-name default-admin-proxy \
  --proxy-uri-policy-mode PROXY_URI_POLICY_MODE_ALLOWLIST_HOSTS \
  --proxy-uri-allowed-hosts api.example.com,ocsp.example.com \
  --proxy-uri-allowed-ports 443,8443 \
  --proxy-uri-deny-private-networks \
  --proxy-mode PROXY_MODE_HTTP_PROXY \
  --proxy-http-host proxy-http.example.com \
  --proxy-http-port 8080 \
  -f json

Example (dual proxy with authentication)

bin/admin.sh proxy update \
  --proxy-name default-admin-proxy \
  --proxy-uri-policy-mode PROXY_URI_POLICY_MODE_ALLOWLIST_SUFFIXES \
  --proxy-uri-allowed-suffixes example.com,internal.example \
  --proxy-mode PROXY_MODE_DUAL_PROXY \
  --proxy-http-host proxy-http.example.com \
  --proxy-http-port 8080 \
  --proxy-https-host proxy-https.example.com \
  --proxy-https-port 8443 \
  --proxy-auth-enabled \
  --proxy-auth-username svc-proxy \
  --proxy-auth-password 's3cr3t' \
  -f yaml

proxy backup

Back up the global administrator proxy configuration to a binary protobuf (.pb) artifact. The backup never contains the authentication password; it is redacted server-side. When you print to screen, the binary payload is Base64-encoded so it can be captured from the console.

Syntax

bin/admin.sh proxy backup [options]

Required output mode options (choose exactly one)

Option Description Example
-o, --output-file Write the .pb backup to a file (creates or truncates) -o ./admin-proxy.pb
-s, --print-to-screen Print the Base64-encoded .pb backup to the console -s true

Backup output rule

Supply exactly one of -o/--output-file or -s/--print-to-screen.

Optional options

Show optional options
Option Default Description
-f, --out-format YAML Output format used for error reporting: JSON or YAML

Example

bin/admin.sh proxy backup -o ./admin-proxy.pb

proxy restore

Restore the global administrator proxy configuration from a binary protobuf (.pb) backup produced by proxy backup. The stored authentication password is preserved unless the backup carries one.

Syntax

bin/admin.sh proxy restore [options]

Required options

Option Description Example
-i, --input-file Binary .pb proxy backup file to restore -i ./admin-proxy.pb

Optional options

Show optional options
Option Default Description
-f, --out-format YAML Output format: JSON or YAML

Example

bin/admin.sh proxy restore -i ./admin-proxy.pb -f json

Standard CLI options are documented in Global options.

FAQ

Do I need to log in before running proxy commands?

Yes. The proxy commands are remote gRPC calls, so create a host profile with profile hosts create and authenticate with profile authn login first.

Is there a proxy create command?

No. proxy update both initializes and edits the configuration through a partial merge, so use it for the first setup and for later changes.

Does proxy update overwrite the whole configuration?

No. It reads the current configuration, applies only the options you supply, and writes the merged result. List options such as --proxy-uri-allowed-hosts replace their entire list when supplied.

Is the proxy authentication password included in backups?

No. The password is redacted server-side and is never written to a proxy backup artifact.