Getting Started with Cockpit
Getting Started with Cockpit
Abstract
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:
- Installing the cockpit packages.
- Opening the port for Cockpit.
- 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:
- Installed Red Hat Enterprise Linux. If required, see the Installation Guide.
- Enabled networking. If required, see the Networking Guide.
- 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:
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.
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.
Allow external connections to port 9090 through the firewall:
# firewall-cmd --add-port=9090/tcp # firewall-cmd --permanent --add-port=9090/tcp
Enable and start the
cockpit.socketservice:$ sudo systemctl enable cockpit.socket $ sudo systemctl start cockpit.socket
- 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
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:9090orhostname:9090.NoteIf 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 Advanced → Add Exception → Confirm Security Exception. After that, you will see the login screen.
- 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.
Choose a new password and click Login.
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:
-
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). - 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:
In the
/etc/pam.d/sshdfile, right after the lastauthline, add this line:auth required <your_PAM_module>
Substitute
<your_PAM_module>with the PAM module used by your application.-
In the
/etc/ssh/sshd_configfile, setChallengeResponseAuthenticationtoyes. -
Restart the
sshdservice with thesystemctl restart shhdcommand.
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.
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.
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.
Networking: See networking interfaces (for example, eth0) and active graphs of sent and received data.
Accounts: Shows which administrative (root) and other users (for example, alan, djohnson) have accounts on the system.
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.
Select a service to view its details:
Diagnostic reports: Collects system configuration and diagnostics information and prepares a report in the .xz compressed format.
You can then download the report locally to your system:
Kernel dump configuration: Shows kdump status and configuration and allows to crash the kernel to test kdump.
SELinux: Shows whether SELinux is enabled and lists access control errors.
Click on an error to see detailed information about it, proposed solution, and audit log:
Subscriptions: Displays installed Red Hat products and subscriptions.
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.
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:
- From the "Dashboard" tab next to the system name, click the plus button.
- Enter IP of the server you are adding and choose a color label for it.
Click the "Add" button.
Log in to the system with a user name and password:
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.
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-bridgepackage and all relevant subpackages to interact with the system, such ascockpit-system, installed. The packages should be the same version as in the Cockpit server.
To connect to an alternate host:
- Type in your username and password from that alternate host and click Other Options.
- In the entry field type the IP address of the new host and click Log In.
- 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.
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:
If required, create the /etc/systemd/system/websocket.cockpit.d/ directory and its parent directories:
# mkdir -p /etc/systemd/system/websocket.cockpit.d/
Create the /etc/systemd/system/websocket.cockpit.d/listen.conf file with these contents:
[Socket] ListenStream=9898
Allow the new port through the firewall:
# firewall-cmd --add-port=9898/tcp # firewall-cmd --permanent --add-port=9898/tcp
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
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.
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:
Pull the cockpit-ws image:
# atomic install rhel7/cockpit-ws
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.
Software Updates: Shows the available OSTrees on the system. You can also check for a newer tree, or roll back to a previous version.
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".
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.
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:
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.
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:
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.