Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

roxctl CLI

Red Hat Advanced Cluster Security for Kubernetes 3.70

roxctl CLI

Red Hat OpenShift Documentation Team

Abstract

This document describes how to install and use the roxctl command-line interface, including the roxctl syntax and operations. It provides some common command examples.

Chapter 1. Getting started with the roxctl CLI

roxctl is a command-line interface (CLI) for running commands on Red Hat Advanced Cluster Security for Kubernetes. This topic describes roxctl syntax, operations, and provides some common examples.

1.1. Installing the roxctl CLI

You can install the roxctl CLI by downloading the binary. Or, you can run the roxctl CLI from a container image.

1.1.1. Installing the roxctl CLI by downloading the binary

You can install the roxctl CLI to interact with Red Hat Advanced Cluster Security for Kubernetes from a command-line interface. You can install roxctl on Linux, Windows, or macOS.

1.1.1.1. Installing the roxctl CLI on Linux

You can install the roxctl CLI binary on Linux by using the following procedure.

Procedure

  1. Download the latest version of the roxctl CLI: 

    $ curl -O https://mirror.openshift.com/pub/rhacs/assets/3.70.2/bin/Linux/roxctl
    Copy to clipboard

  2. Make the roxctl binary executable: 

    $ chmod +x roxctl
    Copy to clipboard

  3. Place the roxctl binary in a directory that is on your PATH:

    To check your PATH, execute the following command: 

    $ echo $PATH
    Copy to clipboard

Verification

  • Verify the roxctl version you have installed: 

    $ roxctl version
    Copy to clipboard
1.1.1.2. Installing the roxctl CLI on macOS

You can install the roxctl CLI binary on macOS by using the following procedure.

Procedure

  1. Download the latest version of the roxctl CLI: 

    $ curl -O https://mirror.openshift.com/pub/rhacs/assets/3.70.2/bin/Darwin/roxctl
    Copy to clipboard

  2. Remove all extended attributes from the binary: 

    $ xattr -c roxctl
    Copy to clipboard

  3. Make the roxctl binary executable: 

    $ chmod +x roxctl
    Copy to clipboard

  4. Place the roxctl binary in a directory that is on your PATH:

    To check your PATH, execute the following command: 

    $ echo $PATH
    Copy to clipboard

Verification

  • Verify the roxctl version you have installed: 

    $ roxctl version
    Copy to clipboard
1.1.1.3. Installing the roxctl CLI on Windows

You can install the roxctl CLI binary on Windows by using the following procedure.

Procedure

  • Download the latest version of the roxctl CLI: 

    $ curl -O https://mirror.openshift.com/pub/rhacs/assets/3.70.2/bin/Windows/roxctl.exe
    Copy to clipboard

Verification

  • Verify the roxctl version you have installed: 

    $ roxctl version
    Copy to clipboard

1.1.2. Running the roxctl CLI from a container

The roxctl client is the default entry point in Red Hat Advanced Cluster Security for Kubernetes roxctl image. To run the roxctl client in a container image:

Procedure

  1. Log in to the registry.redhat.io registry. 

    $ docker login registry.redhat.io
    Copy to clipboard

  2. Pull the latest container image for the roxctl CLI. 

    $ docker pull registry.redhat.io/advanced-cluster-security/rhacs-roxctl-rhel8:3.70.2
    Copy to clipboard

After you install the CLI, you can run it by using the following command: 

$ docker run -e ROX_API_TOKEN=$ROX_API_TOKEN \
  -it registry.redhat.io/advanced-cluster-security/rhacs-roxctl-rhel8:3.70.2 \
  -e $ROX_CENTRAL_ADDRESS <command>
Copy to clipboard

Verification

  • Verify the roxctl version you have installed. 

    $ docker run -it registry.redhat.io/advanced-cluster-security/rhacs-roxctl-rhel8:3.70.2 version
    Copy to clipboard

1.2. Authenticating using the roxctl CLI

For authentication, you can use an authentication token or your administrator password. Red Hat recommends using an authentication token in a production environment because each token is assigned specific access control permissions.

Use the following steps to generate an authentication token.

Procedure

  1. Navigate to the RHACS portal.
  2. Go to Platform Configuration → Integrations.
  3. Scroll down to the Authentication Tokens category, and click API Token.
  4. Click Generate Token.
  5. Enter a name for the token and select a role that provides the required level of access (for example, Continuous Integration or Sensor Creator).

  6. Click Generate.

    Important

    Copy the generated token and securely store it. You will not be able to view it again.

Note

After you have generated the authentication token, export it as ROX_API_TOKEN variable: 

$ export ROX_API_TOKEN=<api_token>
Copy to clipboard

You can also save the token in a file and use it with the --token-file option. For example: 

$ roxctl central debug dump --token-file <token_file>
Copy to clipboard
  • You cannot use both the -password (-p) and the --token-file options simultaneously.
  • If you have already set ROX_API_TOKEN variable, and specify the --token-file option, the roxctl CLI uses the specified token file for authentication.
  • If you have already set ROX_API_TOKEN variable, and specify the --password option, the roxctl CLI uses the specified password for authentication.

1.3. Using the roxctl CLI

Review the following sections to learn how to complete common tasks using the CLI.

Note

  • Export the following variables before using these commands: 

    $ export ROX_API_TOKEN=<api_token>
    Copy to clipboard
    $ export ROX_CENTRAL_ADDRESS=<address>:<port_number>
    Copy to clipboard
  • You can use the --help option to get more information about the commands.

1.3.1. Managing Central’s database

Central stores information about:

  • Activity observed in your clusters,
  • Information retrieved from integrated image registries or scanners, and
  • Red Hat Advanced Cluster Security for Kubernetes configuration.

You can back up and restore Central’s database by using the roxctl CLI.

Backing up Central database

Run the following command to back up Central’s database: 

$ roxctl -e "$ROX_CENTRAL_ADDRESS" central backup
Copy to clipboard
Restoring Central database

Run the following command to restore Central’s database: 

$ roxctl -e "$ROX_CENTRAL_ADDRESS" central db restore <backup_filename>
Copy to clipboard

1.3.2. Managing secured clusters

To secure a Kubernetes or an OpenShift Container Platform cluster, you must deploy Red Hat Advanced Cluster Security for Kubernetes services into the cluster. You can generate deployment files in the RHACS portal by navigating to the Platform Configuration → Clusters view, or you can use the roxctl CLI.

Generating Sensor deployment YAML file

Kubernetes

$ roxctl -e "$ROX_CENTRAL_ADDRESS" sensor generate k8s --name <cluster_name> --central "$ROX_CENTRAL_ADDRESS"
Copy to clipboard

OpenShift Container Platform

$ roxctl -e "$ROX_CENTRAL_ADDRESS" sensor generate openshift --name <cluster_name> --central "$ROX_CENTRAL_ADDRESS"
Copy to clipboard

Read the --help output to see other options that you might need to use depending on your system architecture.

Make sure that the endpoint you provide for --central can be reached from the cluster where you are deploying Red Hat Advanced Cluster Security for Kubernetes services.

Note

If you are using a non-gRPC capable load balancer, such as HAProxy, AWS Application Load Balancer (ALB), or AWS Elastic Load Balancing (ELB):

  • Use the WebSocket Secure (wss) protocol. To use wss, prefix the address with wss://, and

  • Add the port number after the address, for example: 

    $ roxctl sensor generate k8s --central wss://stackrox-central.example.com:443
    Copy to clipboard
Downloading Sensor bundle for existing clusters

Use the following command to download Sensor bundles for existing clusters by specifying a cluster name or ID. 

$ roxctl sensor get-bundle <cluster_name_or_id>
Copy to clipboard
Deleting cluster integration
$ roxctl -e "$ROX_CENTRAL_ADDRESS" cluster delete --name=<cluster_name>
Copy to clipboard
Important

Deleting cluster integration will not remove Red Hat Advanced Cluster Security for Kubernetes services running in the cluster. You can remove them by running the delete-sensor.sh script from the Sensor installation bundle.

1.3.3. Checking policy compliance

You can use the roxctl CLI to check deployment YAML files and images for policy compliance.

Configuring output format

When you check policy compliance by using the deployment check, image check, or image scan commands, you can specify the output format by using the -o option. This option determines how the output of a command is displayed in the terminal.

You can change the output format by adding the -o option to the command and specifying the format as json, table, csv, or junit.

For examle, the following command checks a deployment and then displays the result in csv format: 

$ roxctl -e "$ROX_CENTRAL_ADDRESS" \
  deployment check --file =<yaml_filename> \
  -o csv
Copy to clipboard
Note

When you do not specify the -o option for the output format, the following default behavior is used:

  • The format for the deployment check and the image check commands is table.
  • The default output format for the image scan command is json. This is the old JSON format output for compatibility with older versions of the CLI. To get the output in the new JSON format, specify the option with format, as -o json.

Different options are available to configure the output. The following table lists the options and the format in which they are available.

OptionDescriptionFormats

--compact-output

Use this option to display the JSON output in a compact format.

json

--headers

Use this option to specify custom headers.

table and csv

--no-header

Use this option to omit the header row from the output.

table and csv

--row-jsonpath-expressions

Use this option to specify GJSON paths to select specific items from the output. For example, to get the Policy name and Severity for a deployment check, use the following command: 

$ roxctl -e "$ROX_CENTRAL_ADDRESS" \
  deployment check --file=<yaml_filename> \
  -o table --headers POLICY-NAME,SEVERITY \
  --row-jsonpath-expressions="{results.#.violatedPolicies.#.name,results.#.violatedPolicies.#.severity}"
Copy to clipboard

table and csv

--merge-output

Use this options to merge table cells that have the same value.

table

headers-as-comment

Use this option to include the header row as a comment in the output.

csv

--junit-suite-name

Use this option to specify the name of the JUnit test suite.

junit

Checking deployment YAML files

The following command checks build-time and deploy-time violations of your security policies in YAML deployment files. Use this command to validate:

  • Configuration options in a YAML file, such as resource limits or privilege options; or
  • Aspects of the images used in a YAML file, such as components or vulnerabilities. 
$ roxctl -e "$ROX_CENTRAL_ADDRESS" deployment check --file=<yaml_filename>
Copy to clipboard
Checking images

The following command checks build-time violations of your security policies in images. 

$ roxctl -e "$ROX_CENTRAL_ADDRESS" image check --image=<image_name>
Copy to clipboard
Checking image scan results

You can also check the scan results for specific images.

The following command returns the components and vulnerabilities found in the image in JSON format. The format is defined in the API reference. 

$ roxctl -e "$ROX_CENTRAL_ADDRESS" image scan --image <image_name>
Copy to clipboard

To cause Red Hat Advanced Cluster Security for Kubernetes to re-pull image metadata and image scan results from the associated registry and scanner, add the --force option.

Note

To check specific image scan results, you must have a token with both read and write permissions for the Image resource. The default Continuous Integration system role already has the required permissions.

1.3.4. Debugging issues

Managing Central log level

Central saves information to its container logs.

Viewing the logs

You can see the container logs for Central by running:

Kubernetes

$ kubectl logs -n stackrox <central_pod>
Copy to clipboard

OpenShift Container Platform

$ oc logs -n stackrox <central_pod>
Copy to clipboard

Viewing current log level

You can change the log level to see more or less information in Central logs. Run the following command to view the current log level: 

$ roxctl -e "$ROX_CENTRAL_ADDRESS" central debug log
Copy to clipboard
Changing the log level

Run the following command to change the log level: 

$ roxctl -e "$ROX_CENTRAL_ADDRESS" central debug log --level=<log_level> 1
Copy to clipboard
1
The acceptable values for <log_level> are Panic, Fatal, Error, Warn, Info, and Debug.
Retrieving debugging information

To gather debugging information for investigating issues, run the following command: 

$ roxctl -e "$ROX_CENTRAL_ADDRESS" central debug dump
Copy to clipboard

Legal Notice

Copyright © 2022 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat, Inc.