The author selected the Free and Open Source Fund to receive a donation as part of the Write for DOnations program.
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.
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_domainin 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:
Now, create a directory using the
- 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
Next, run the following two commands to ensure that you are running the latest version of
- sudo snap install core
- sudo snap refresh core
Now, install Certbot snap with the following command:
- sudo snap install --classic certbot
--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
- 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.
Note: A symbolic link works on Linux the same way that a shortcut works on Windows—it is a pointer from a location to the file.
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
Cockpit has a couple of requirements for using an SSL certificate:
- The certificate file must contain the certificate and the private key in the same file.
- This certificate and key file must be located in the
/etc/cockpit/ws-certs.ddirectory and end in
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"
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
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
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
post_hook = /etc/cockpit/certificate-renewal.sh
Next, test that the new configuration is working with the following command:
- sudo certbot renew --dry-run
--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:
OutputRunning 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 URLhttps://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
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.
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.