Getting Started with Cockpit

Red Hat Enterprise Linux 7

Getting Started with Cockpit

Red Hat Enterprise Linux Documentation Team

Abstract

This guide demonstrates how to use the Cockpit web-based interface to manage Red Hat Enterprise Linux and Red Hat Enterprise Linux Atomic Host servers.

Chapter 1. Overview

Cockpit is a user-friendly web-based interface for administering servers. It allows monitoring system resources and adjusting configuration with ease.

1.1. What makes Cockpit unique?

  • Cockpit builds upon existing functionality.
  • There is no lock-in. Feel free to use other tools alongside Cockpit. Switch back and forth with ease.
  • Cockpit does not need special infrastructure or configuration. Once installed, it is ready to use.
  • When not in use, Cockpit uses no memory or CPU on the server.
  • Cockpit always updates its data to reflect the current state of the server, within seconds.
  • Cockpit stores no data or policy. People keep their system-wide permissions and use the system credentials.
  • Optionally take advantage of single sign-on with Kerberos.
  • Cockpit itself is not used for configuration management. However, Cockpit can interact with configuration management and custom server tools.

1.2. The role of this guide

This document helps you get started with Cockpit. It walks through installation, explains typical server configuration, and demonstrates the Cockpit interface in detail.

Chapter 2. Installing and Enabling Cockpit

A primary Cockpit server is the machine that runs a Cockpit service with the user interface. A secondary server is a machine that is administered using Cockpit. It is possible to add one or more secondary hosts to the primary server.

Setting up a primary Cockpit server involves:

  1. Installing the cockpit packages.
  2. Opening the port for Cockpit.
  3. Starting the cockpit service.

After setting up, you can connect to Cockpit in a browser by typing the hostname and port of the server. For example, from the primary host you can connect using localhost:9090.

For setting up a primary server on Red Hat Enterprise Linux Atomic Host, see Installing Cockpit on Atomic Host.

2.1. Prerequisites for a Cockpit server

Before setting up Cockpit, ensure that you have:

  1. Installed Red Hat Enterprise Linux. If required, see the Installation Guide.
  2. Enabled networking. If required, see the Networking Guide.
  3. Registered the system and attached subscription. If required, see the Registering the System and Attaching Subscriptions section of the System Administrator’s Guide.

2.2. Setting up the primary Cockpit server

To install and enable Cockpit:

  1. Enable the Extras and Optional repositories:

    # subscription-manager repos --enable=rhel-7-server-extras-rpms
    # subscription-manager repos --enable=rhel-7-server-optional-rpms

    This gives you access to supplementary Cockpit packages such as cockpit-dashboard.

  2. Install the cockpit and cockpit-dashboard packages:

    $ sudo yum install cockpit cockpit-dashboard

    The cockpit-dashboard package provides the "Dashboard" tab in the interface. This package is optional, but is assumed to be installed in this guide.

  3. Allow external connections to port 9090 through the firewall:

    #  firewall-cmd --add-port=9090/tcp
    #  firewall-cmd --permanent --add-port=9090/tcp
  4. Enable and start the cockpit.socket service:

    $ sudo systemctl enable cockpit.socket
    $ sudo systemctl start cockpit.socket
  5. Cockpit is now installed and running.

If you are installing Cockpit on a Red Hat Enterprise Linux Atomic Host system, see Installing Cockpit on Atomic Host.

2.3. Opening the Interface

  1. Open a web browser and enter the server’s IP address with port 9090 in the address bar. If the web browser is on the Cockpit server, open localhost:9090 or hostname:9090.

    Note

    If you use a self-signed certificate, the browser issues a warning. Carefully check the certificate before accepting the warning. Consider using a certificate signed by a certificate authority (CA). For more information on certificates, see the An Overview of Certificates and Security section of the RHEL System Administrator’s Guide.

    If you are sure you want to use self-signed certificates, then add this connection to the security exceptions. Click AdvancedAdd ExceptionConfirm Security Exception. After that, you will see the login screen.

    Sunset

  2. Log into the Cockpit interface with the same user name and password that you would normally use to log into the system.

2.4. Changing Expired Passwords

Cockpit supports changing expired passwords.

A fresh system installation with an expired password will prompt a password change during the first login. System administrators often use this feature to make sure users change their pre-assigned passwords to a custom password.

When logging in with an expired password, Cockpit prompts you to enter the current password a second time. Enter your current password and click Log In.

Sunset

Choose a new password and click Login.

Sunset

Note

If you have issues logging in to Cockpit and the prompt for changing the password is not shown, check the /etc/ssh/sshd_config file on the Cockpit Server. Make sure ChallengeResponseAuthentication is set to yes and restart sshd with the systemctl restart sshd command.

2.5. SSH two-factor authentication with Cockpit

Cockpit supports two-factor authentication. If you have protected your SSH server with two-factor authentication, the login screen will prompt you to enter your password and PIN pair.

Setting up SSH for two-factor authentication requires two components:

  1. A company’s authenticator application that provides one-time passwords or PIN numbers. An example application is Google Authenticator, which also has its own Pluggable Authentication Module (PAM).
  2. A server that validates the PINs from a dongle.

These two components are often implemented differently for different companies.

After setting up the authenticator application and the validation server, enable SSH two-factor authentication in Cockpit:

  1. In the /etc/pam.d/sshd file, right after the last auth line, add this line:

    auth       required         <your_PAM_module>

    Substitute <your_PAM_module> with the PAM module used by your application.

  2. In the /etc/ssh/sshd_config file, set ChallengeResponseAuthentication to yes.
  3. Restart the sshd service with the systemctl restart shhd command.

Cockpit will ask for your verification code the next time you log in.

Chapter 3. Using Cockpit

3.1. Getting to know the Cockpit interface

Once you have logged in, you will see the main Cockpit interface. It has the Dashboard tab on the top and a side menu with details for the selected system on the left. The Dashboard shows a list of all systems added to the Cockpit server with graphs for their CPU usage, memory usage, disk I/O, and network traffic.

Sunset

From Dashboard, you can select a system name, in this case primary-host, and have a look at the side menu:

System: Shows information about the system that Cockpit is running on. This includes CPU usage, memory usage, disk I/O, and network traffic, as well as hardware and operating system details.

Sunset

Logs: See messages produced by the systemd journal, including errors, warnings, and notices. The log is similar to the output of the journalctl command. The log displays newest entries first, with options to filter by type.

Sunset

Networking: See networking interfaces (for example, eth0) and active graphs of sent and received data.

Sunset

Accounts: Shows which administrative (root) and other users (for example, alan, djohnson) have accounts on the system.

Sunset

Services: Shows the systemd services running on the Cockpit server. You can see which are active/enabled or inactive. You can also see other systemd features: Targets, sockets, timers, and paths.

Sunset

Select a service to view its details:

Sunset

Diagnostic reports: Collects system configuration and diagnostics information and prepares a report in the .xz compressed format.

Sunset

You can then download the report locally to your system:

diagnostics report download

Kernel dump configuration: Shows kdump status and configuration and allows to crash the kernel to test kdump.

Sunset

SELinux: Shows whether SELinux is enabled and lists access control errors.

Sunset

Click on an error to see detailed information about it, proposed solution, and audit log:

Sunset

Subscriptions: Displays installed Red Hat products and subscriptions.

Sunset

Terminal: Opens an in-browser terminal with a command line session to the Cockpit system. In this terminal, you can run commands from your signed-in user account. For example, as root, you could run the systemctl start or dnf install commands.

Sunset

For Red Hat Enterprise Linux Atomic Host systems, there are additional features in the Cockpit interface. See Cockpit Interface Specific to Atomic Host.

3.1.1. Adding secondary systems

Once you log in to the primary server, you will be able to connect to secondary servers. These secondary systems need to have:

  • The cockpit packages installed.
  • An SSH server running and available on port 22 that supports password or key-based authentication.

To add a new secondary server:

  1. From the "Dashboard" tab next to the system name, click the plus button.
  2. Enter IP of the server you are adding and choose a color label for it.
  3. Click the "Add" button.

    Sunset

  4. Log in to the system with a user name and password:

    add host passwd

Configuring Key-Based Authentication

If you have keys generated on the primary server, you need to add them to the target server, in the ~/.ssh/authorized_keys file. If you do not have keys, use the following command:

$ ssh-keygen

Next, copy the contents of the ~/.ssh/id_rsa.pub file to the ~/.ssh/authorized_keys file on the target server. Then, return to the user interface on the primary server, click the top right corner menu with the user name on it, choose Authentication, and enable the preloaded key.

Sunset

After you type in the IP when adding the new system to the Dashboard, change the Authentication type to Use available credentials.

3.1.2. Logging into other systems through Cockpit

On the login screen, you can also choose an alternate host to connect to.

The alternate host needs to have:

  • SSH listening on port 443
  • the cockpit-bridge package and all relevant subpackages to interact with the system, such as cockpit-system, installed. The packages should be the same version as in the Cockpit server.

To connect to an alternate host:

  1. Type in your username and password from that alternate host and click Other Options.
  2. In the entry field type the IP address of the new host and click Log In.
  3. Provide the SSH fingerprint and click Log In again.

Now you are able to browse the new system. Cockpit uses SSH to authenticate you against that host, so you do not need to configure anything else on the new system.

Note

If the new machine is not known to Cockpit, and you get the Refusing to connect. Host is unknown error, use the following command to allow connections from unknown hosts:

ssh-keyscan -H [ip_address] >> /var/lib/cockpit/known_hosts

3.1.3. Logging into a system via a Bastion Host

On the Cockpit login screen you can choose an alternate host to connect to. Cockpit uses SSH to authenticate you against that host and to display the admin interface for that host.

Although browsers cannot use SSH directly to connect to machines or authenticate against them, Cockpit can make this happen. Only one host needs to have Cockpit listen on port 9090 available to browsers over TLS. Other hosts only need to have SSH accessible on the usual port 22.

3.2. Changing the Cockpit port

To change the Cockpit port:

  1. If required, create the /etc/systemd/system/websocket.cockpit.d/ directory and its parent directories:

    # mkdir -p /etc/systemd/system/websocket.cockpit.d/
  2. Create the /etc/systemd/system/websocket.cockpit.d/listen.conf file with these contents:

    [Socket]
    ListenStream=9898
  3. Allow the new port through the firewall:

    # firewall-cmd --add-port=9898/tcp
    # firewall-cmd --permanent --add-port=9898/tcp
  4. If you have SELinux enabled, change the default SELinux policy to allow the websm_port_t domain to listen on the TCP 9898 port:

    $ sudo semanage port -a -t websm_port_t -p tcp 9898

    If the port is already defined by some other part of the SELinux policy, use the -m argument instead of -a to modify the definition:

    $ sudo semanage port -m -t websm_port_t -p tcp 9898
    1. To make the changes take effect, run the following commands:

      $ sudo systemctl daemon-reload
      $ sudo systemctl restart cockpit.socket

You can now use the address with the newly assigned port in the web browser.

For changing port on a Red Hat Enterprise Linux Atomic Host system, see Changing the Cockpit port on Atomic Host.

3.3. Enabling more Cockpit features

You can add more Cockpit features by installing additional cockpit-* packages using yum.

Chapter 4. Cockpit on Red Hat Enterprise Linux Atomic Host

A Cockpit server can run on Red Hat Enterprise Linux Atomic Host, and Atomic Host servers can be monitored and administered using Cockpit. Additionally, Cockpit can control life cycle of container instances and manipulate container images.

Note

Cockpit does not yet support Kubernetes on Red Hat Enterprise Linux or Red Hat Enterprise Linux Atomic Host servers.

This chapter describes Cockpit features specific to Atomic Host.

4.1. Installing Cockpit on Atomic Host

To install Cockpit on Atomic Host:

  1. Pull the cockpit-ws image:

    # atomic install rhel7/cockpit-ws
  2. Run the cockpit-ws image:

    # atomic run rhel7/cockpit-ws

Now you can log into Cockpit. See Opening the Interface for instructions.

4.2. Cockpit Interface Specific to Atomic Host

In addition to information about systems presented in Getting to know the Cockpit interface, extra tabs appear on Atomic Host systems:

Containers: Lists all images available on the system, all running and non-running containers, combined CPU & memory usage graphs, and a storage usage bar. See Working with Containers for more information on using this tab.

Sunset

Software Updates: Shows the available OSTrees on the system. You can also check for a newer tree, or roll back to a previous version.

Sunset

4.2.1. Working with Containers

The Containers tab presents you with a UI to interact with your Atomic Host images and containers. Apart from the system resources graphs, there are lists of all images you have locally on the system as well as all running and non-running containers.

Download an image. Click the "Get new image" button from the images list to the right and enter an image name or a keyword. Choose an image and click "Download".

Sunset

Starting and stopping containers. From the "Containers" list, you can start and stop containers using the buttons on the right side. Use the drop-down menu to see all or filter out the non-running containers.

Sunset

Click on a container to inspect it. Shows the state, the command executed, the container’s and image’s IDs, a timestamp, as well as the container’s own terminal:

Sunset

Click on an image to inspect it. Shows the image’s ID, entrypoint and command, and a list of containers based on that image. You can also delete the image from here or run a container from it.

Sunset

Run a container. To run a container from an image, either click the triangle button from the right side of the list or choose the image first and then click "Run" from the top right corner. You can then enter the required data for the new container in the following dialog:

Sunset

You can select which command the container should run, and you can also link that container to other containers, which will allow them to interact. Exposing ports for specific services to be visible from the host is also possible.

4.3. Changing the Cockpit port on Atomic Host

To change the Cockpit port on Atomic Host:

atomic run rhel7/cockpit-ws --port 9898

4.4. Enabling more Cockpit features on Atomic Host

You can add more Cockpit features by installing additional cockpit-* packages using package layering.

Legal Notice

Copyright © 2017 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, 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 Software Collections 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.