Menu Close

Red Hat Connector Configuration Guide

Red Hat Insights 2022

Configuring and using the Red Hat connector feature

Red Hat Customer Content Services

Abstract

This guide is for Red Hat account users and system administrators who want to use the Red Hat connector feature to register Red Hat Enterprise Linux systems with Red Hat for services hosted on https://console.redhat.com/insights.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.

Providing feedback on Red Hat documentation

We appreciate your feedback on our documentation. To provide feedback, highlight text in a document and add comments.

Prerequisites

  • You are logged in to the Red Hat Customer Portal.
  • In the Red Hat Customer Portal, the document is in the Multi-page HTML viewing format.

Procedure

To provide your feedback, perform the following steps:

  1. Click the Feedback button in the top-right corner of the document to see existing feedback.

    Note

    The feedback feature is enabled only in the Multi-page HTML format.

  2. Highlight the section of the document where you want to provide feedback.
  3. Click the Add Feedback pop-up that appears near the highlighted text.

    A text box appears in the feedback section on the right side of the page.

  4. Enter your feedback in the text box and click Submit.

    A documentation issue is created.

  5. To view the issue, click the issue link in the feedback view.

Chapter 1. Introducing Red Hat connector

Red Hat connector provides an improved way of connecting your system to the cloud-based Red Hat Insights services, letting you manage your systems more efficiently from the Red Hat Hybrid Cloud Console. With Insights, you can proactively identify, prioritize, and resolve risks to security, compliance, performance, availability, and stability before they become urgent issues. You can manage your systems' settings through the Red Hat connector dashboard.

The Insights settings you select in the dashboard are applied to all RHEL systems in your account that have enabled the rhc connect utility. The dashboard settings control the following actions for your connected systems:

  • Connecting to Insights
  • Using OpenSCAP for Compliance policies
  • Enabling Red Hat Cloud Connector to fix issues directly from Insights
Note

Cloud Connector requires a Red Hat Smart Management subscription.

1.1. Red Hat connector features

The Red Hat connector utility, rhc, comes with all RHEL 8.5 and newer installations. The utility comprises a CLI utility for RHEL and a Red Hat connector dashboard accessed through the Red Hat Hybrid Cloud Console. The Red Hat connector daemon, rhcd, runs on the host and listens for messages from the Red Hat Hybrid Cloud Console. It also receives and executes remediation playbooks.

Accounts that are direct-connect systems can use the Red Hat Cloud Connector feature to resolve issues across your Red Hat infrastructure. This provides Red Hat Smart Management features without a Satellite subscription. A Red Hat Smart Management subscription is required.

1.2. Red Hat connector CLI utility

The Red Hat connector CLI provides users with options to manage the host connection with Insights. If Insights is enabled on the Configuration Dashboard, connecting with Red Hat connector will register the host using insights-clients in the background.

1.3. Configure User Access for connector users

Before account users can access certain features in the Insights for Red Hat Enterprise Linux application, they need to be added to the correct User Access group(s) in Red Hat Hybrid Cloud Console > User Access > Users. The privileges needed by a user depend on their need to perform the tasks described in the following subsections. At a high level, an Organization Administrator or User Access administrator performs the following steps to create new groups, or to add roles or members to existing groups:

  • Create a User Access group for each role; for example, Remediations administrators.
  • Add the role to the group; for example, Remediations administrator.
  • Add members to the group. All members of the group will have administrator privileges to execute direct remediations from Insights for RHEL.

Your organization might already have User Access groups with the proper roles added. Onboarding new members might be as easy as adding them to an existing group.

Note

Existing groups can be searched, as well as the roles included in each group, in Red Hat Hybrid Cloud Console > User Access > Groups.

1.3.1. User Access roles for users of the Red Hat connector dashboard

There are currently two roles that are relevant for connector dashboard users. These roles determine if a user can change settings or simply view them:

  • Red Hat connector administrator. Members in a group with this role can perform any operations in the rhc manager.
  • Red Hat connector viewer. This is a default permission for all users on your organization’s Red Hat Hybrid Cloud Console account, allowing anyone to see the current status of the configuration.

1.3.2. User Access roles for users of remediations in Red Hat Insights

There are two roles that are relevant for remediations users and determine whether a user can view remediations details or execute direct remediations from Insights for RHEL:

  • Remediations administrator. Members in a group with this role can perform any available operation against any remediations resource, including direct remediations.
  • Remediations user. Members in a group with this role can create, view, update, and delete operations against any remediations resource. This is a default permission given to all Red Hat Hybrid Cloud Console users on your account.

1.3.3. Additional resources

Chapter 2. Configuring Red Hat connector

Red Hat connector performs critical system tasks, such as retrieving the current configuration of various services supported by the Red Hat connector dashboard and updating the current configuration of services. It also maintains a history of configuration changes and ensures that newly connected hosts are kept up to date with the latest configuration.

Red Hat connector updates a host through a change in the dashboard and through a new Red Hat connector connection event from Inventory.

Note

Currently, settings can apply only to all hosts connected with the Red Hat connector feature. You cannot configure a host or group of hosts differently.

Before configuring your host to connect through Red Hat connector, review the configuration in the Red Hat connector dashboard. The dashboard settings determine your host’s configuration.

Configuring Red Hat connector comprises the following tasks:

  • Enabling a Red Hat Ansible repository
  • Installing Ansible
  • Installing the rhc-worker-playbook package
  • Running rhc connect

2.1. Setting up Red Hat connector

Prerequisites

  • RHEL 8.5 is installed.
  • The host must be registered and have a valid subscription.

    Note

    Simple content access is recommended.

  • You are logged in as root.

Procedure

  1. Enable the Ansible repository:

    # subscription-manager repos --enable ansible-2.9-for-rhel-8-x86_64-rpms
    
    Repository 'ansible-2.9-for-rhel-8-x86_64-rpms' is enabled for this system.
  2. Install Ansible and the rhc-worker-playbook package:

    # dnf -y install ansible rhc-worker-playbook
  3. Connect with the Red Hat connector utility:

    # rhc connect
    
    When prompted for your username and password, use your credentials from your Red Hat customer portal account.
    
    Connecting <$HOSTNAME> to Red Hat.
    This might take a few seconds.
    
    Username: <$USERNAME>
    Password: <$PASSWORD>
    
    ● Connected to Red Hat Subscription Management
    ● Activated the Red Hat connector daemon
    
    Manage your Red Hat connector systems: https://red.ht/connector

Verification

  1. Ensure you see a similar message for Ansible and the rhc-worker-playbook:

    Installed:
      ansible-2.9.27-1.el8ae.noarch                   python3-jmespath-0.9.0-11.el8.noarch                   rhc-worker-playbook-0.1.5-3.el8_4.x86_64                   sshpass-1.06-3.el8ae.x86_64
    
    Complete!
  2. You should see a similar message for Red Hat connector:

    ● This system is connected to Red Hat Subscription Management
    ● Activated the Red Hat connector daemon
    
    Manage your Red Hat connector systems: https://red.ht/connector
    Note

    The rhcd daemon does not write to a separate log file; it puts data in the systemd journal that is located in /var/log/journal. Use the journalctl command to view the log. Some messages are written to stdin/stdout.

2.2. Disconnecting from the dashboard

Use this procedure on each RHEL system that you want to remove from the Red Hat connector dashboard.

Important

Disconnecting through Red Hat connector also unregisters your host from the Red Hat Customer Portal.

Procedure

  1. Run rhc disconnect:

    # rhc disconnect
    
    Disconnecting iqe-e2e-rhc-vm-agmwwfgvet from console.redhat.com.
    This might take a few seconds.
    Note

    The rhc disconnect command detaches subscriptions and unregisters from Red Hat Subscription Management.

Verification

  1. You should see a similar message:

    Disconnecting <$HOSTNAME> from Red Hat.
    This might take a few seconds.
    
    ● Deactivated the Red Hat connector daemon
    ● Disconnected from Red Hat Subscription Management
    
    Manage your Red Hat connector systems: https://red.ht/connector

2.3. Using additional CLI options

View additional options for the rhc command.

Procedure

  1. Run rhc status to show the status:

    # rhc status
    Connection status for <$HOSTNAME>:
    ● Connected to Red Hat Subscription Manager
    ● The rhc daemon is active
    
    See all your connected systems: https://red.ht/connector
  2. Run ps and pipe through grep to display the connector rhcd process.

    # ps -u root | grep rhc
    PID TTY TIME COMMAND
    14992 ? 0:00 /usr/sbin/rhcd
  3. Run systemctl status rhcd to view the on/off status of the rhcd daemon.

    # systemctl status rhcd
  4. Enter rhc --help with no other options.

    $ rhc --help
    NAME:
       rhc - control the system's connection to console.redhat.com
    
    USAGE:
       rhc [global options] command [command options] [arguments...]
    
    VERSION:
       0.0.git.310.a47ac17
    
    COMMANDS:
       connect     Connects the system to console.redhat.com
       disconnect  Disconnects the system from console.redhat.com
       facts       Prints information about the system.
       status      Prints status of the system's connection to console.redhat.com
       help, h     Shows a list of commands or help for one command
    
    GLOBAL OPTIONS:
       --help, -h     show help (default: false)
       --version, -v  print the version (default: false)

2.4. Additional resources

Chapter 3. Using the Red Hat connector Dashboard

Manage RHEL system connections to Insights for Red Hat Enterprise Linux in the Red Hat connector dashboard. The RHEL systems in your account are visible in the dashboard after the Red Hat connector utility is enabled on each system. You control all connected RHEL systems and whether to use the Insights for RHEL services from the Red Hat connector dashboard.

Changes in the dashboard create a playbook that is pushed to all connected systems. The dashboard provides a log that shows you the playbook runs and all connected systems.

The dashboard provides a main on/off switch for the connection to Insights for RHEL. With the rhc command and the dashboard, there is no granular control over individual system connections, and there is no additional control over the data that is packaged on your systems and uploaded to Insights for RHEL.

To control the type of data that each system provides to Insights, you must use the insights-client command. For example, if you want to apply data obfuscation or data redaction to the system information that is sent to Insights, you must configure the obfuscation and redaction values on each system.

3.1. Opening the Red Hat connector dashboard

Use the Red Hat connector dashboard to view the number of connected systems and connection settings.

The first time you open the dashboard, it shows a pane for rhc command syntax that you can fill in and copy to simplify command entry on your RHEL systems if they are not already running the Red Hat connector utility. You can close this pane, but it cannot be reopened.

Prerequisites

  • You must have Red Hat connector viewer privileges, assigned in User Access, to perform this procedure.

Procedure

  1. Log in to your Red Hat organization account at Red Hat Hybrid Cloud Console.
  2. Click the gear icon and click Settings.
  3. Click Red Hat Connector tab to view the Red Hat connector dashboard. The dashboard shows the number of connected systems and the Red Hat Insights connection settings.

3.2. Editing settings in the Red Hat connector Dashboard

Use the Red Hat connector dashboard to edit Red Hat connector settings. You can enable settings to use OpenSCAP for compliance policies and Red Hat Cloud Connector to fix issues directly from Red Hat Insights. Enabling OpenSCAP automatically installs the OpenSCAP packages required to use the Compliance feature.

Figure 3.1. Red Hat connector Dashboard > Services

img rhc dashboard services

Prerequisites

  • You must have Red Hat connector administrator privileges, assigned in User Access, to perform this procedure.

Procedure

  1. Log in to your Red Hat organization account at Red Hat Hybrid Cloud Console.
  2. Click the gear icon and click Settings.
  3. Click the Red Hat Connector tab to view the dashboard Services tab. This tab shows the number of connected systems and the Red Hat Insights connection settings.
  4. Use the slider buttons to select Insights settings for your connected systems. The changes are applied to all connected systems and to all future systems that connect through the Red Hat connector utility.

3.3. Using Red Hat connector to remediate an issue

Red Hat Cloud Connector allows you to remediate your direct-connect RHEL systems from Red Hat Insights when you have Red Hat connector installed on your RHEL 8.5 system and a Red Hat Smart Management subscription.

3.3.1. Creating and updating a remediation playbook

There are multiple contexts within Insights from which you can create a remediation playbook or update an existing one. You can use the following Insights applications to create or update a playbook:

  • Advisor
  • Compliance
  • Patch
  • Vulnerability

3.3.2. Executing a remediation playbook

Execute a playbook directly from the Insights for RHEL application.

Prerequisites

  • You must have Remediations administrator privileges, assigned in User Access, to perform this procedure.

Procedure

  1. Click Remediations on the Red Hat connector dashboard. The Remediations page lists the playbook that is available to be executed.
  2. Open the playbook to review its details (Action, Systems, Activity) or directly trigger an execution.

    Figure 3.2. Remediations page

    img rhc remediations page
  3. Clicking Execute playbook displays a summary of the type of connection to use when pushing the playbook. Direct connection refers to the host connecting through the Red Hat connector client.

    Figure 3.3. Execute the playbook

    img rhc execute playbook

Verification

  1. The remediations playbook successfully executed.
  2. The issue was marked as resolved on Remediations.
  3. The issue was resolved on the system.

3.4. Additional resources

Chapter 4. Troubleshooting Red Hat connector issues

System logs are a great source of information when troubleshooting a Red Hat connector issue. In addition, it is helpful to be aware of any known issues.

4.1. Consulting and interpreting log files

Troubleshooting an issue often starts by looking at the logs to see what happened during a given event. You can consult logs by running one of two CLI commands:

# journalctl -u rhcd

or

# journalctl -u rhcd -f

4.2. Known issues

There are occasionally issues that the user or org admin should be aware of when working with their hosts.

The following known issues are documented for Red Hat connector:

  1. Red Hat connector is stuck in the checking status if a Red Hat Satellite-connected system is also in the remediation plan.

    If you have a remediation plan that contains one or more Red Hat connector systems and one or more Red Hat Satellite-connected systems, when you click the Execute Playbook button on the Red Hat connector dashboard. the Red Hat connector system will be stuck at checking. You will not be able to execute the remediation plan on the Red Hat connector system.

    Note

    Red Hat verified this issue using the Vulnerability service. It has not been verified with every service on the Red Hat connector dashboard.

    Here are the four possible scenarios:

  2. The insights-client command is not invoked after executing remediation with Red Hat connector.

    Playbooks generated by Remediations generally have the following structure:

  3. The Red Hat connector throws a serialization error after executing a remediations playbook.

    Each time a remediations playbook is executed through Red Hat connector, the following log entry displays:

    [rhcd] 2021/10/01 16:49:37 /builddir/build/BUILD/rhc-0.2.0/cmd/yggd/grpc.go:168: cannot send message 0e8eb387-acf2-48f9-8975-e6165f0fb2b3: rpc error: code = Internal desc = Failed to serialize response!

    See rhc throws serialization error after executing remediations playbook for more information.

  4. Users who do not have the Red Hat connector administrator role should not be able to update Red Hat connector settings

    A user who has only the Red Hat connector viewer RBAC role should not be able to update Red Hat connector settings on the Red Hat Hybrid Cloud Console. Currently, the Save changes button remains enabled, which allows an unauthorized user to update the settings.

    This bug affects the UI and the backend service because the playbook execution to update the settings in the connected systems is triggered by the Config Manager service when Save Changes is pressed.

    See Users who doesn’t have RHC administrator role shouldn’t be able to update RHC settings for more information.

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.