NETLOOM-CLEARPASS(7)

NAME
netloom-clearpass - ClearPass plugin reference for netloom.

SYNOPSIS

    netloom load clearpass
    netloom server use <profile>
    netloom cache update
    netloom <module> <service> <action> [options]

DESCRIPTION
netloom-clearpass documents the bundled ClearPass plugin for netloom(1). The plugin targets HPE Aruba ClearPass Policy Manager and discovers the API surface dynamically from the documentation endpoints exposed by the selected server. Because of that, available modules, services, actions, request fields, and response metadata can vary between deployments and software versions. Use this manual for the ClearPass-specific behavior that does not belong in the shared netloom(1) manual: configuration layout, authentication methods, discovery workflow, privilege-aware catalog behavior, filtering conventions, and the profile-to-profile copy and diff workflows.

CONFIGURATION
The ClearPass plugin stores configuration under:

    ~/.config/netloom/plugins/clearpass/
Important files and directories:

defaults.env
    Plugin-wide defaults such as the active profile, TLS verification, timeout, and path overrides.

profiles/<profile>.env
    Per-profile connection settings such as NETLOOM_SERVER.

credentials/<profile>.env
    Per-profile authentication settings such as NETLOOM_CLIENT_ID, NETLOOM_CLIENT_SECRET_REF, NETLOOM_CLIENT_SECRET, NETLOOM_API_TOKEN, or NETLOOM_API_TOKEN_FILE. A typical layout looks like:

    ~/.config/netloom/plugins/clearpass/defaults.env
    ~/.config/netloom/plugins/clearpass/profiles/dev.env
    ~/.config/netloom/plugins/clearpass/credentials/dev.env
Minimal profile connection settings:

    NETLOOM_SERVER=clearpass.example.com:443
Minimal OAuth client credentials:

    NETLOOM_CLIENT_ID=dev-client-id
    NETLOOM_CLIENT_SECRET_REF=dev/client-secret
Direct NETLOOM_* environment variables still override profile files when set in the current shell session.

AUTHENTICATION
The ClearPass plugin supports three practical authentication paths.

OAuth client credentials
    Uses NETLOOM_SERVER, NETLOOM_CLIENT_ID, and either NETLOOM_CLIENT_SECRET_REF or NETLOOM_CLIENT_SECRET.

Direct bearer token
    Uses NETLOOM_API_TOKEN.

Token file
    Uses NETLOOM_API_TOKEN_FILE. The file may contain either a raw token or JSON with an access_token field. When a login secret is needed, the runtime checks in this order:

    1.  NETLOOM_API_TOKEN

    2.  NETLOOM_API_TOKEN_FILE

    3.  keychain-resolved NETLOOM_CLIENT_SECRET_REF

    4.  plaintext NETLOOM_CLIENT_SECRET

KEYCHAIN SETUP
When NETLOOM_CLIENT_SECRET_REF is configured, the runtime resolves the client secret from the OS keychain with:

    service
        netloom/clearpass

    username
        the literal value of NETLOOM_CLIENT_SECRET_REF.
Typical setup:

    python -m keyring set netloom/clearpass dev/client-secret

    NETLOOM_CLIENT_ID=dev-client-id
    NETLOOM_CLIENT_SECRET_REF=dev/client-secret
To inspect the backend that Python keyring sees:

    python -m keyring diagnose
    python -m keyring --help
To verify a stored secret:

    python -m keyring get netloom/clearpass dev/client-secret
In headless Linux or WSL-style environments, a keyring backend may need to be installed and unlocked explicitly. One workable pattern is:

    sudo apt install -y gnome-keyring
    dbus-run-session -- bash
    echo 'choose-a-keyring-password' | gnome-keyring-daemon --unlock
    python -m keyring set netloom/clearpass dev/client-secret
If NETLOOM_CLIENT_SECRET_REF is configured but no usable backend exists, the runtime only falls back to plaintext NETLOOM_CLIENT_SECRET when that plaintext value is also configured.

DISCOVERY AND CACHE
The ClearPass plugin discovers API structure from documentation endpoints such as:

/api-docs
    Top-level module and service discovery.

/api/apigility/documentation/<Module-v1>
    Action metadata, request field hints, and endpoint details for a module. Refresh discovery metadata when the ClearPass server is upgraded, when API features change, or when help/completion looks stale:

    netloom cache clear
    netloom cache update
The resulting cache powers shell completion, context-aware help, and command validation.

PRIVILEGE-AWARE CATALOG
During netloom cache update the ClearPass plugin also queries:

/api/oauth/privileges
    Effective runtime privileges for the authenticated API client. The plugin keeps the full discovered catalog, then builds a stricter default visible view from verified privilege mappings. This makes normal help, completion, and command discovery better match what the current API client can actually access. Normal CLI behavior uses the visible catalog. To troubleshoot or inspect the retained full discovery data, use:

    netloom --catalog-view=full ?
    netloom --catalog-view=full <module> <service> ?
    netloom --catalog-view=full <module> <service> <action> ?

FILTERING
When an endpoint supports server-side filtering, the ClearPass plugin accepts either shorthand filters or full JSON expressions. Shorthand examples:

    --filter=name:equals:TEST
    --filter=name:contains:guest
    --filter=id:in:1,2,3
    --filter=enabled:exists:true
Supported shorthand operators:

    equals
    not-equals
    contains
    in
    not-in
    gt
    gte
    lt
    lte
    exists
Useful JSON patterns include:

    {"key":{"$eq":"value"}}
    {"key":{"$contains":"value"}}
    {"key":{"$in":["value1","value2"]}}
    {"$and":[filter1,filter2]}
    {"$or":[filter1,filter2]}
    {"$not":{filter}}
Advanced JSON examples:

    --filter='{"name":{"$contains":"TEST"}}'
    --filter='{"$and":[{"name":{"$contains":"TEST"}},{"status":{"$eq":"Known"}}]}'
Shell quoting matters because JSON expressions are passed as strings.

COPY WORKFLOW
The ClearPass plugin supports copying resources between named profiles without manual export and replay steps. Preferred syntax:

    netloom <module> <service> copy --from=SOURCE --to=TARGET [options]
Useful options include:

--dry-run
    Preview planned writes without changing the target profile.

--match-by=auto|name|id
    Choose how target objects are matched.

--on-conflict=fail|skip|update|replace
    Choose the write strategy when a match already exists.

--save-source=FILE
    Save fetched source objects. If omitted, a generated file under NETLOOM_OUT_DIR is still written.

--save-payload=FILE
    Save normalized write payloads. If omitted, a generated file under NETLOOM_OUT_DIR is still written.

--save-plan=FILE
    Save the planned operations. If omitted, a generated file under NETLOOM_OUT_DIR is still written. The plugin normalizes payloads before replaying them so response-only metadata, links, IDs, and similar API noise are not sent back as write input.

DIFF WORKFLOW
The ClearPass plugin also supports read-only comparison between two named profiles. Preferred syntax:

    netloom <module> <service> diff --from=SOURCE --to=TARGET [options]
Useful options include:

--match-by=auto|name|id
    Choose how source and target objects are matched.

--all
    Compare the full selected collection on both profiles.

--filter=JSON|FIELD:OP:VALUE
    Compare the same filtered selection on both profiles.

--fields=FIELD1,FIELD2
    Restrict the comparison to named fields when supported by the selected action.

--ignore-fields=FIELD1,FIELD2
    Ignore named fields when comparing items.

--out=FILE
    Write the JSON diff report to an explicit file. If omitted, a generated timestamped file under NETLOOM_OUT_DIR is still written.

--show-all
    Disable console preview caps and print every listed diff item and changed field.

--max-items=N
    Adjust the console preview cap for listed items and changed fields. Broad selectors such as --all and --filter produce symmetric reports with same, different, only_in_source, and only_in_target statuses. Narrow selectors such as --id and --name stay source-scoped and primarily answer whether the chosen source object matches an object in the target profile.

TROUBLESHOOTING
If a profile is not behaving as expected, start with:

    netloom server show
If help or completion looks incomplete, refresh the cache:

    netloom cache update
If a module or service seems to be missing for the current API client, inspect the retained catalog:

    netloom --catalog-view=full ?

EXAMPLES
List endpoints:

    netloom identities endpoint list --limit=10
Filter endpoints by name:

    netloom identities endpoint list --filter=name:contains:guest
Get one network device by id:

    netloom policyelements network-device get --id=1001
Copy matching network devices from one profile to another:

    netloom policyelements network-device copy --from=dev --to=prod --all --dry-run
Compare roles between two profiles:

    netloom policyelements role diff --from=lab --to=prod --all
Use action-specific help:

    netloom policyelements network-device add ?

FILES

~/.config/netloom/plugins/clearpass/defaults.env
    ClearPass-wide defaults.

~/.config/netloom/plugins/clearpass/profiles/
    Profile-specific connection settings.

~/.config/netloom/plugins/clearpass/credentials/
    Profile-specific credentials.

~/.cache/netloom/
    Default cache location used for discovered ClearPass API metadata.

SEE ALSO
netloom(1)