Operating ClearPass from the CLI (appadmin)

Notes from reading documentation, not results from testing on a live system. Main source: HPE’s ClearPass Policy Manager 6.10.x CLI Reference Guide (rev. 01, 09/2021). Each point carries a page citation at the end; anything that could not be verified is marked.

The appadmin shell of ClearPass Policy Manager is not a router-style CLI: it is a narrow set of operational commands, some of which wipe the configuration without their names hinting at it at all. This note keeps only what is worth remembering: the backup → patch → rollback → upgrade sequence, the defaults that lose data, and the table of destructive commands.

The full command catalog is deliberately not copied here — looking it up directly in the CLI Reference Guide is more accurate and does not go stale across releases.

Prerequisites

• An appadmin account on the node you are working on. Some commands only run on the publisher (cluster set-cluster-passwd, cluster set-standby-publisher, cluster sync-cluster-passwd)¹.
• A fallback console session for any command that touches the network or partitions — see the destructive-commands table below.
• A backup kept off the target server. This is not generic advice: system factory-reset also deletes the backups stored on that same server¹.

Steps

1. Back up before anything else

backup [-f <file-name>] [-c] [-l] [-r] [-w] [-P] — with no arguments, the system picks a file name and backs up the configuration¹.

Flag	What it takes
-c	configuration data
-l	session log data
-r	Insight data
-w	only the most recent week of log database records
-P	does not include the password fields of the configuration DB in the backup

-P matters when the backup will leave your control (sent to a partner, put in a shared repository): by default the backup contains password fields.

2. Patching

system update -i <source> installs a patch; -f reinstalls when the first attempt failed; system update -l lists installed patches¹. The source can be SCP, HTTPS, HTTP or a file already uploaded to the machine.

3. Upgrading

system upgrade <source> [-w] [-l] [-L]¹:

Flag	Access Tracker records after the upgrade
-w	restores the most recent week
-l	restores everything from the current version
-L	no backup and no restore
(no flag)	backed up but NOT restored

The default is the trap: without a flag, Access Tracker records are still backed up but not brought back¹ — open Access Tracker after the upgrade and it is completely empty, which is easy to mistake for data loss.

Offline upgrade: download the file from Aruba Support Center → Administration → Agents and Software Updates → Software Updates → Import Updates → and only then run system upgrade <local-path> in the CLI¹.

4. Boot images and the two partitions

system boot-image -l lists installed images with their index and an [Active] marker; system boot-image -a <index> sets the active image — you must reboot for the new image to run¹.

5. Common cluster commands

• cluster list — lists nodes, communication mode (IPv4/IPv6), HA state, standby publisher and failover wait time¹.
• cluster make-subscriber -i <IP> with -b to skip the publisher backup, -l to restore the local log database, -V to skip publisher certificate validation¹.
• cluster drop-subscriber [-f] [-i <IP>] -s — -f forces removal even of a dead node, -s prevents the database reset on the dropped node. Without -i, the current node leaves the cluster itself if it is a subscriber¹.
• cluster set-standby-publisher -i <IP> -t <minutes> — failover wait time defaults to 10 minutes, deliberately so the standby does not take over when the publisher is merely rebooting¹.
• cluster diagnostics uses port 7432, and measures both the database connection time and the HTTPS API call time to the publisher¹.
• cluster make-publisher and cluster make-subscriber: do not close the shell or interrupt the command midway¹.

6. SSH account lockout

ssh lockout count <n> | duration <N minutes> | mode <basic|advanced> | reset¹:

• Off by default; issuing count or duration is what turns it on.
• count defaults to 5 failures, accepts values 1–1000.
• Per node — a multi-node cluster must be configured on every node.
• The configuration and lockout state survive reboot, update and upgrade; cluster reset-database does not touch this feature.
• While locked out: console login still works, SSH with a public key still works, only password SSH is blocked. Further failed attempts push back the unlock time, counted from the last failure.
• Lockout/unlock/failed-login events all go to Event Viewer.

Unverified. The document contradicts itself here: the parameter section says count defaults to 5, but the behavior description just above says the account is locked after three consecutive failures. Which one is right has not been verified — check with show ssh on a real system before relying on this number.

7. Services

service <action> <service-name> with action list | start | stop | restart | status¹. service list prints the full real service names (cpass-radius-server, cpass-tacacs-server, cpass-policy-server, cpass-radsec, cpass-dbwrite-server, cpass-domain-server@<domain-name>, cpg-background…), so when you need the exact name, run service list rather than copying it from the documentation¹.

Verification

• show version — software version and hardware model¹.
• system update -l — list of installed patches with install date and cumulative patch description¹.
• system boot-image -l — which image is [Active]¹.
• cluster list — nodes, HA, standby publisher¹.
• cluster diagnostics -c <IP> / -s — throughput, configured MTU, ping latency, and two [OK] checks: database connection to the publisher and HTTPS connection to the host¹.
• show ssh — SSH account lockout configuration¹.

Rollback

system patch-rollback returns the system to the immediately previous installed version, meant for when a problem shows up in production after patching¹. The limits to know before counting on it:

• Supported only from Policy Manager 6.7 onward.
• It only rolls back the most recent cumulative patch within the same major version. Installed in the order 6.x.0 → 6.x.1 → 6.x.2, a rollback returns to the point just before 6.x.2 was installed.
• Install 6.x.3 on top of 6.x.0 and you can only roll back to 6.x.0, not to 6.x.2 — because 6.x.0 is the version that was installed before.
• It cannot roll back across a major version after an upgrade.
• To roll back from 6.10.x to 6.10.0 you must first download and install the 6.10.0_source-rollback-package from the Software Updates page.
• Rollback also removes the configuration and database changes made during the post-installation step of that patch.
• A reboot is required afterward.

When several hotfixes are in one cumulative patch, they can be rolled back one at a time down to the exact hotfix needed¹.

Data-destroying commands

These are dangerous because the command names do not say what happens:

Command	What actually happens
configure fips-mode <0|1>	Wipes the Policy Manager configuration, resets the database to defaults, shuts down all applications and reboots. Enabling or disabling FIPS both do this1
cluster reset-database	Erases the configuration, resets the local database to defaults1
system factory-reset	Factory defaults: data lost, license lost on the current partition, and the backups stored on the server lost too. Only on physical appliances, not on VMs, not on AWS/Azure1
system install-image	Installs a new image onto the second partition: data on that partition is erased, the license is not carried over, and after reboot every parameter has to be re-entered from the bootstrap screen. Physical appliances only1
system cleanup <days>	Deletes system/application logs, old authentication records, audit records, expired guest accounts, old automatic and manual backups, saved reports — and the on-screen warning also lists endpoints1
system morph-vm <model>	Morphing a VM to a larger size on 6.7+ erases all licenses (configuration is kept); TAC has to reactivate them. You need to power off, attach an extra disk, and adjust CPU/RAM to match the target model before running it1 — see ClearPass licensing
system refresh-network · configure mtu	May drop network connectivity and require logging in again; refresh-network also needs a reboot to take effect. Keep a console handy1
system reset-server-certificate	Resets the HTTPS (RSA/ECC), RADIUS/EAP or Database certificate — choosing 0 resets all three groups; services restart on their own1
cluster set-communication-mode <ipv4|ipv6>	Changes the address format for all cluster communication; the documentation requires resetting certificates on every node and rebooting each node, otherwise the cluster falls out of sync1
system update-luks-key	Sets a LUKS passphrase (at least 8 characters) in place of the default key. After that, every reboot or new session requires typing it in by hand — unattended restarts are no longer possible1

What is missing when running in the cloud

The CLI Reference Guide already notes that system factory-reset and system install-image do not exist on cloud platforms; another source confirms exactly that for Azure, along with a few other operational differences: the IP/subnet/gateway of the management and data ports cannot be changed, SPAN port settings are hidden, the web page footer shows a [Cloud] indicator, the Virtual IP tab still accepts input but has no effect, and Common Criteria mode is not supported². Details in Cloud identity in NAC.

Security-relevant commands that do not destroy data

• system admin-password-reset resets the Web UI admin password to the vendor’s default value (this note does not copy the default string — look it up in the original document). system apps-access-reset removes application access restrictions¹.
• system gen-recovery-key and system gen-support-key generate tokens that let a support engineer log in with the privileged arubasupport account; system start-rasession opens a time-limited Remote Assistance session (at most 12 hours), checked with system status-rasession and closed with system terminate-rasession¹. This is a legitimate privileged way in — it belongs in the control process, not only in the operations documentation.
• system create-api-client <Client_ID> <Client_Secret> creates an API client straight from the CLI, instead of the UI steps described in Integrating external systems through the API¹.
• dump logs, when log collection is scheduled, runs the services in DEBUG mode and only returns them to the default log level once collection is done¹ — schedule it and forget it, and you create load and fill the disk yourself.
• system export-endpoints-csv exports endpoints with profile details to a zip file downloadable under Administration → Server Manager → Local Shared Folders. Conversely, importing a zip file containing endpoint CSV is not supported through either the CLI or the UI; exporting/importing via XML at very large volumes (>250K) performs poorly, and the UI may hang and report running out of memory¹.
• configure hostname: a hostname containing a dot is treated as an FQDN, so the part before the first dot must be unique across devices¹.

Unverified. The source is the CLI Reference Guide release 6.10.x (rev.01, 09/2021). Command names and flags change between releases — re-check against the documentation for the release you are running before operating on production. This note does not copy passwords, tokens or secrets that appear in the document’s examples.

Related

• ClearPass Policy Manager · ClearPass Access Tracker
• Integrating external systems through the API — system create-api-client

Sources

Footnotes

1. ClearPass Policy Manager 6.10.x CLI Reference Guide (rev.01, 09/2021), PDF pp. 3–9, 18, 21, 38–39, 47–51, 61–80 ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹ ↩¹⁰ ↩¹¹ ↩¹² ↩¹³ ↩¹⁴ ↩¹⁵ ↩¹⁶ ↩¹⁷ ↩¹⁸ ↩¹⁹ ↩²⁰ ↩²¹ ↩²² ↩²³ ↩²⁴ ↩²⁵ ↩²⁶ ↩²⁷ ↩²⁸ ↩²⁹ ↩³⁰ ↩³¹ ↩³² ↩³³ ↩³⁴ ↩³⁵ ↩³⁶ ↩³⁷ ↩³⁸ ↩³⁹ ↩⁴⁰ ↩⁴¹

2. ClearPass Microsoft Azure Integration — Part 1 (community slides, 2021), PDF p. 21 ↩