How To Install Cockpit on Debian 10

The author selected the Free and Open Source Fund to receive a donation as part of the Write for DOnations program.

Introduction

Cockpit is a server administration dashboard that allows you to view the status of your server in real time. It provides information on CPU load, filesystem statistics, processes, and further information. One of Cockpit’s benefits is that it will not consume any server resources when you’re not logged in to the control panel—the service only starts when you browse to the control panel.

You can perform server administration tasks with Cockpit, such as managing users and troubleshooting network issues. You can also access a terminal from a browser on your computer or phone. Cockpit uses your system’s users for login and system management using sudo for privilege escalation. In this way Cockpit doesn’t introduce an additional layer of security considerations to your server by creating a second set of Cockpit-only users.

In this tutorial, you will deploy a secured Cockpit server administration dashboard on a Debian 10 server.

Prerequisites

Before you begin this guide, you’ll need the following:

• One Debian 10 server configured using the Initial Server Setup with Debian 10 guide. You should configure and enable the UFW firewall as described in the guide.
• A domain name that points to your server that you will use to access Cockpit. If you need information on pointing domain names please refer to the Domains and DNS guide. We will use the example domain name cockpit.your_domain in this tutorial. Your domain must point to your server before you start.

Log in to your server as the sudo-enabled non-root server to begin.

Step 1 — Installing Cockpit

In this step, you will install Cockpit and open the port that Cockpit uses in your firewall.

First, perform a system update using apt. This will ensure that your server has the latest packages and will avoid any errors during the Cockpit installation:

sudo apt update
sudo apt upgrade

Next, install Cockpit:

sudo apt install cockpit

Now, create a directory using the mkdir command:

sudo mkdir -p /usr/lib/x86_64-linux-gnu/udisks2/modules

You use the -p option so that mkdir will create several levels of directory with one invocation.

You created this directory to stop a harmless, but distracting warning, from displaying in your Cockpit instance. This warning appears because the udisks2 utility is unable to find the /usr/lib/x86_64-linux-gnu/udisks2/modules directory, which is not created by default unless additional udisks2 are installed.

Finally, open Cockpit’s access port 9090 and port 80 that you will use to obtain the SSL certificate in the next step:

sudo ufw allow 9090
sudo ufw allow 80

You have now installed Cockpit and opened the ports ready to use a signed SSL certificate for your domain. You will get this certificate in the next step.

Step 2 — Obtaining an SSL Certificate

In this step, you will get an SSL certificate issued by Let’s Encrypt using the Certbot utility. Certbot will register and download the certificate and will also automatically renew the certificate when it expires.

Certbot is distributed as an Ubuntu snap package. The snap utility is not installed by default on Debian 10, so you must install it as a part of the snapd package:

sudo apt install snapd

Next, run the following two commands to ensure that you are running the latest version of snap:

sudo snap install core
sudo snap refresh core

Now, install Certbot snap with the following command:

sudo snap install --classic certbot

The --classic option here installs the Certbot snap in classic mode—this reduces confinement and allows access to more of your system’s resources, which is necessary for Certbot to function correctly.

Next, create a symbolic link from /usr/bin/certbot to point to the snap-installed Certbot binary at /snap/bin/certbot with the ln utility:

sudo ln -s /snap/bin/certbot /usr/bin/certbot

You need to create this symbolic link because not all utilities on Linux are aware that they should look in /snap/bin/ for program files; whereas /usr/bin/ is a standard location for user-installed programs.

Now that you’ve installed the Certbot utility, you’ll use it to register and download the SSL certificate with the following command:

sudo certbot certonly --standalone --agree-tos --email your_email -d cockpit.your_domain

You’ve used the following options:

• certonly: Registers and downloads the SSL certificate without making other changes to the system.
• --standalone: Uses Certbot’s built-in web server to register the certificate.
• --agree-tos: Automatically agrees to the Terms of Service (ToS).
• --email your_email: Takes your email address to register the certificate. (This will only be used for expiry notices and security information.)
• -d cockpit.your_domain: Specifies the domain name that you want to use for your Cockpit instance.

When you run this command Certbot will ask you if you want to share your email address with the Electronic Frontier Foundation (the developers of the Certbot utility) for non-essential emails. You do not have to agree to this to register the SSL certificate, so enter Y for “yes” or N “no” to continue and register the certificate.

When the Certbot utility completes the registration, it will save your certificate files in /etc/letsencrypt/live/cockpit.your_domain.

Cockpit has a couple of requirements for using an SSL certificate:

1. The certificate file must contain the certificate and the private key in the same file.
2. This certificate and key file must be located in the /etc/cockpit/ws-certs.d directory and end in .cert.

As a result, you will need to create the certificate and key file with the SSL certificate you registered so you can use it with Cockpit. You will also need to configure Certbot to re-create this file when your certificate is renewed.

First, create the combined certificate and key file with the following command:

sudo bash -c "cat /etc/letsencrypt/live/cockpit.your_domain/fullchain.pem /etc/letsencrypt/live/cockpit.your_domain/privkey.pem >/etc/cockpit/ws-certs.d/cockpit.your_domain.cert"

You use sudo bash -c here because without it the command will fail. This is because the redirection > takes place in a different shell than the one that has the sudo permissions.

The cat command prints the contents of the certificate and key files to standard output, so this content is then redirected with > into a new file.

Next, you’ll create the post-renewal script that Certbot will run. This script will re-create the certificate and key file with the renewed certificate and restart the Cockpit service so it starts using it.

Open the script at /etc/cockpit/certificate-renewal.sh with a text editor:

sudo nano /etc/cockpit/certificate-renewal.sh

Add the following code into this file:

#!/usr/bin/env bash

echo "Recreating Cockpit SSL Certificate"
cat /etc/letsencrypt/live/cockpit.your_domain/fullchain.pem /etc/letsencrypt/live/cockpit.your_domain/privkey.pem > /etc/cockpit/ws-certs.d/cockpit.your_domain.cert

echo "Restarting Cockpit"
systemctl restart cockpit.socket

You’ve specified the following:

• #!/usr/bin/env bash: This is the shebang and tells Linux what program to use to execute the script. In this case, you stipulate the GNU Bash shell.
• echo: This command prints the message that follows. You will receive this when you test the certificate renewal.
• cat: This is the same command you ran to create the certified and key file earlier in the tutorial.
• systemctl restart cockpit.socket: This restarts Cockpit so that it uses the new certificate.

Make this certificate executable by changing its permissions with chmod:

sudo chmod 755 /etc/cockpit/certificate-renewal.sh

If you are unsure about Linux file permissions refer to An Introduction to Linux Permissions for more information.

Next you’ll configure Certbot to run this script when it renews the SSL certificate by adding a line to /etc/letsencrypt/renewal/cockpit.your_domain.conf.

Open this file with a text editor:

sudo nano /etc/letsencrypt/renewal/cockpit.your_domain.conf

Add the following line at the end of the [renewalparams] section:

post_hook = /etc/cockpit/certificate-renewal.sh

Next, test that the new configuration is working with the following command:

sudo certbot renew --dry-run

The --dry-run options tells Certbot to perform a certificate renewal, but without making any changes to your certificates. You will receive the following lines at the bottom of the output:

Output
Running post-hook command: /etc/cockpit/certificate-renewal.sh
Output from post-hook command certificate-renewal.sh:
Recreating Cockpit SSL Certificate
Restarting Cockpit

This tells you that the renewal script process is working correctly for when the SSL certificate renewal happens.

Finally, restart Cockpit to load the SSL certificate:

sudo systemctl restart cockpit.socket

You’ve now fully configured your Cockpit instance and you’re ready to log in.

Step 3 — Accessing Cockpit

You’ve configure the Cockpit interface to listen on port 9090, so you will need to specify this port at the end of the URL that you type into your browser. Here is the URL for your Cockpit instance:

Cockpit Login URL
https://cockpit.your_domain:9090

Cockpit does not keep a separate list of users, but instead uses the system’s users. These are the users that you create with the adduser command.

You can log in with the user that you created in the initial set up guide or create a new one following the same procedure.

The login form has a checkbox labeled Reuse my password for privileged tasks.

If you check this option you will be able to run commands that require sudo inside Cockpit as long as the user has sudo access rights.

The Cockpit interface has three main areas. The first is the real-time system information page. Browse to this page by locating the left-hand navigation panel and clicking on the meter icon.

Clicking on this will take you to real-time graphs showing you your server’s CPU, memory, network, and disk I/O.

The next section is the Detailed Information and Administration section. Navigate to this section by clicking on the server icon in the left-hand navigation panel.

This section of Cockpit provides detailed information about many aspects of your system, such as the logs and system files. You can also administer some parts of your server, like adding and removing users and managing the system’s storage. You will find the browser bash terminal in this section.

To edit your user’s Cockpit settings, click on your user icon at the top of the interface and select Account Settings. Here you can change the interface language, password, and email address.

You’ve now accessed your Cockpit instance from your browser.

Conclusion

In this tutorial, you installed Cockpit and secured your connection with an SSL certificate for your domain. You can now use your browser to view real-time resource use, administer, and access your server from a command prompt.

You can read more about extending your Cockpit instance with the help of the official documentation.