Haack's Wiki

This is an old revision of the document!

cockpit
Jonathan Haack
Haack's Networking
webmaster@haacksnetworking.org

cockpit

This tutorial covers how to set up Cockpit on Debian. The approach here assumes that Cockpit will be installed on bare metal being used in production, with only ssh exposed. This tutorial assumes you already have a sufficiently hardened and provisioned VPS/VM w/ a LAMP stack and some associated A/AAAA records ready to go. If not, go read Apache Survival first and come back. If you are ready to go, then this tutorial will cover:

Unordered List ItemInstallation of Cockpit + Preferred Packages
Setup of Apache Reverse Proxy; including setup for “with” and “without” 80/443 exposed/listening
Localhost w/ FoxyProxy
Official Cockpit Flatpak

Introduction

Let's install cockpit and then create an apache virtual host for it. After that, we will cut the cert, then swap the vhost configs with the reverse proxy config. Let's enable TLS modules and headers.

sudo apt install cockpit*
sudo apt remove cockpit-389-ds
sudo a2enmod ssl 
sudo a2enmod headers

After that, open sudo nano /etc/apache2/sites-available/domain.com.conf and change the ServerName field, and make a placeholder directory at /var/www/domain.com/public_html and make sure the WebRoot points properly to that directory. Add the vhost with a2ensite domain.com.conf and restart the service systemctl restart apache2. Once basic http is functional, build the cert:

sudo apt install certbot letsencrypt python3-certbot-apache
sudo certbot --authenticator standalone --installer apache -d domain.com --pre-hook "systemctl stop apache2" --post-hook "systemctl start apache2"

The cert is now built and domain.com should now show the “green lock” and have TLS enabled. If not, check your config and debug with sudo apache2ctl configtest and resolve that issue before proceeding. Once that's done and the page resolves with TLS, enable the proxy and swap the configs.

sudo a2enmod proxy_http
sudo a2enmod proxy
sudo a2enmod rewrite
sudo a2enmod proxy_wstunnel
apache2ctl configtest
systemctl reload apache2

Open the domain.com.conf vhost in /etc/apache2/sites-enabled and change it to:

<VirtualHost *:80>
    ServerName domain.com
    RewriteEngine On
    RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
</VirtualHost>

Open the domain.com-le-ssl.conf vhost in /etc/apache2/sites-enabled and change it to something like this:

<IfModule mod_ssl.c>
    <VirtualHost *:443>
        ServerName domain.com
        SSLCertificateFile /etc/letsencrypt/live/domain.com/fullchain.pem
        SSLCertificateKeyFile /etc/letsencrypt/live/domain.com/privkey.pem
        Include /etc/letsencrypt/options-ssl-apache.conf
        
        <IfModule mod_headers.c>
            Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"
        </IfModule>

        ProxyPreserveHost On
        ProxyRequests Off

        RewriteEngine On
        RewriteCond %{HTTP:Upgrade} =websocket [NC]
        RewriteRule /(.*)           ws://127.0.0.1:9090/$1 [P,L]
        RewriteCond %{HTTP:Upgrade} !=websocket [NC]
        RewriteRule /(.*)           http://127.0.0.1:9090/$1 [P,L]

        ProxyPass / http://127.0.0.1:9090/
        ProxyPassReverse / http://127.0.0.1:9090/

        RequestHeader set X-Forwarded-Proto "https"
    </VirtualHost>
</IfModule>

These configs were built using the examples on Cockpit's documentation for reverse proxy configurations.

The above firewall rules will differ depending on one's setup and there are certainly other ways to do this. Once this is done, let's set up apache to serve cockpit to the trusted IPs.

sudo apt install apache
sudo a2enmod proxy_http
sudo a2enmod proxy
sudo a2enmod rewrite
sudo a2enmod ssl
sudo a2enmod headers
sudo nano /etc/apache2/sites-available/000-default.conf
<enter the FQDN in the virtual host>
a2ensite 000-default.conf
sudo apache2ctl configtest

Once the host serves http requests without any issues, it's time to setup TLS. I prefer to use Let's Encrypt as follows:

sudo apt install certbot letsencrypt python3-certbot-apache
sudo certbot --authenticator standalone --installer apache -d fqdn.com --pre-hook "systemctl stop apache2" --post-hook "systemctl start apache2"

Once the host serves https requests without any issues, it's time to replace the virtual host you set up above with a reverse proxy configuration. You will also need to delete the virtual host that Let's Encrypt setup as it will no longer be necessary.

cd /etc/apache2/sites-enabled
rm 000-default-le-ssl.conf [name might differ]
sudo nano 000-default.conf

In the virtual host that opens up, enter something like the following:

<IfModule mod_ssl.c>
<VirtualHost *:443>
  ServerName fqdn.com
  Include /etc/letsencrypt/options-ssl-apache.conf
  ProxyPreserveHost On
  ProxyRequests Off
  ProxyPass / http://127.0.0.1:9090/ upgrade=websocket
  ProxyPassReverse / http://127.0.0.1:9090/
  SSLCertificateFile /etc/letsencrypt/live/fqdn.com/fullchain.pem
  SSLCertificateKeyFile /etc/letsencrypt/live/fqdn.com/privkey.pem
</VirtualHost>
</IfModule>

In addition to setting apache to serve external requests to cockpit, you also need to configure cockpit to recognize your fqdn.com as a trusted origin:

sudo nano /etc/cockpit/cockpit.conf

In that file, enter the following:

[WebService]
Origins = https://fqdn.com http://127.0.0.1:9090
ProtocolHeader = X-Forwarded-Proto
AllowUnencrypted = true

Now that your virtual host is setup as a reverse proxy and your origin is trusted by cockpit, you should restart apache with systemctl restart apache2 and navigate to your cockpit instance https://fqdn.com. If you did everything correctly, cockpit will render and you will not need to append 9090 to the fqdn.com. Additionally, since you specified the host itself in the firewall rules above, it will be able to renew your certificate files every 3 months.

— oemb1905 2025/02/15 14:32

Haack's Wiki

User Tools

Site Tools

Page Tools