How to install and configure Cockpit on CenOS8

Served over HTTPS and behind a reverse proxy

4 min readJan 6, 2020

Cockpit is a web-based administration tool for your linux servers. With it you can manage and update your system, view logs, add users and ever run a terminal. All within a browser!

In this article I will show how to install Cockpit and hide it behind nginx so we can leverage Let’s Encrypt certificates and certbot.

This article assumes that your server has a public IP address and a DNS record associated with said IP. Of course you should also have administrative privileges. If the server resides within your corporate network, then most likely you’ll be able create a record yourself or request one from somebody else. In such scenario self-signed or CA-issued certificates will be the way to go. However, this article will not cover such use case.

For illustrative purposes I’ll use https://cockpit.example.com as a mock address for cockpit. Of course you should use an address that you own. Without further ado, the list of tasks is as follows:

Install and start cockpit
Install and configure nginx
Configure a server with proxy_pass for websocket
Use certbot to get a Let’s Encrypt certificate

Install and start Cockpit

The installation really boils down to two commands. The first one installs all of the required packages and the second one enables and starts cockpit. If you’re running a full version (as opposed to minimal), cockpit should be already installed.

# dnf install cockpit
# systemctl enable --now cockpit.socket

Note that what is started is not a service but a socket. By default Cockpit listens on port 9090 and serves its content over HTTPS using a self-signed certificate. This is of course not ideal and can be easily improved upon. Instructions on the official page contain additional instructions to allow traffic for cockpit firewalld service. I am purposefully not doing that, because nginx will accept all incoming connections on standard HTTP(S) ports. Thus we should only ensure that firewall will not block these. Direct traffic to cockpit can (and in most cases should) be blocked. To add rules for HTTP(S) run these commands:

# firewall-cmd --add-service=http --permanent
# firewall-cmd --add-service=https --permanent

Install and configure nginx

Installing nginx on CentOS is pretty straightforward when using official repos. If for any reason you’re using private or third-party repos, make sure to install proper version of nginx. Any version above 1.3 will be enough, since that version added support for websockets. After installation we can start configuring our reverse proxy. This article is pretty insightful and the last bit of config will be a good base for us. To what’s already there we must add an Origin header. This is important — without this cockpit will reject all connections from nginx.

After doing the described modifications, here’s the bare minimum that is required for this setup to work. There are some gotchas that you might encounter when configuring a more elaborate environment. For further reading and a more advanced configuration check out this wiki entry. You can safely put the following block into /etc/nginx/conf.d/cockpit.conf or directly into nginx.confif you so desire.

map $http_upgrade $connection_upgrade {
  default upgrade;
  '' close;
}upstream websocket {
  server localhost:9090;
}server {
  server_name cockpit.example.com;
  location / {
    proxy_pass http://websocket;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;        proxy_set_header Origin https://$host;
  }
}

Use certbot to get a Let’s Encrypt certificate

Let’s Encrypt provides the internet with free SSL certificates to secure your websites with. Configuration used to be quite tricky, but with the emergence of certbot, it became a walk in the park. It boils down to 3 steps: getting certbot, executing it and setting up a cron task.

Execution of certbot requires the most attention, since there is a decision to be made. We can either allow certbot to get a certificate for us and stop there or get a certificate and reconfigure nginx along the way. In our case nginx configuration is rather simple and leaves little room for error, so auto mode will do. If your configuration is more sophisticated, you might want to just get the cert and do the configuration yourself. All required steps can be found on certbot site. Also the main script is very user-friendly and will guide you through the process. It’s also a good idea to redirect traffic from http to https. When using auto mode, execute the following commands and restart nginx for good measure. Also make sure that you have python installed or else the job will fail.

$ wget https://dl.eff.org/certbot-auto
$ sudo -s
# mv certbot-auto /usr/local/bin/certbot-auto
# chown root /usr/local/bin/certbot-auto
# chmod 0755 /usr/local/bin/certbot-auto# /usr/local/bin/certbot-auto --nginx# echo "0 0,12 * * * root python -c 'import random; import time; time.sleep(random.random() * 3600)' && /usr/local/bin/certbot-auto renew" | tee -a /etc/crontab > /dev/null

Configure cockpit

There a two things that need to be done for cockpit to work behind a proxy. First of all we must set allowed Origins, so our requests will not be denied. The other thing would be to set the ProtocolHeader option, so cockpit will know that the connection is secure. The full configuration file is just three lines long. Paste them into /etc/cockpit/cockpit.conf and restart the socket.

[WebService]
Origins = https://cockpit.example.com wss://cockpit.example.com
ProtocolHeader = X-Forwarded-Proto

Conclusion

In this article I showed how to install cockpit and hide it behind nginx acting as a reverse proxy. The setup was fairly simple and should be enough to get you started on exploring cockpit and utilizing it to the fullest.