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

-------------------------------------------

//cockpit//      

-------------------------------------------

=== Introduction ===
This tutorial covers how to set up Cockpit on Debian. The approach here assumes that Cockpit will be installed in one of two different ways:

  * Bare Metal - only ssh is open
  * Virtual Machine - ssh and 80/443 are open for the reverse proxy

In both scenarios, we use the apache location package to limit url requests to approved IPs. 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 [[https://wiki.haacksnetworking.org/doku.php?id=computing:apachesurvival|Apache Survival]] first and come back. If you are ready to go, then this tutorial will cover:

  * Installation 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

=== Install Cockpit & Configure Apache ===
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:

<code>
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"
</code>

The cert is now built and ''domain.com'' should now 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
  sudo a2enmod authz_host
  apache2ctl configtest
  systemctl reload apache2
  
Now, we will go ahead and swap the default virtual hosts with the reverse proxy configurations. Open the ''domain.com.conf'' vhost in ''/etc/apache2/sites-enabled'' and change it to:

<code>
<VirtualHost *:80>
    ServerName domain.com
    
    <Location />
        Require ip 96.40.208.144
        Require ip 2601:8c3:8684:a3f1::b2c
    </Location>
    
    RewriteEngine On
    RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
</VirtualHost>
</code>

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

<code>
<IfModule mod_ssl.c>
    <VirtualHost *:443>
        ServerName domain.com
        
        <Location />
            Require ip 96.40.208.144
            Require ip 2601:8c3:8684:a3f1::b2c
        </Location>
        
        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>
</code>

These configs were built using the examples on Cockpit's documentation for reverse proxy configurations. Make sure to edit the IPs above to IPs you actually have. Additionally, I recommend adding some more for a dedicated VPS, etc., and/or another backup server. You can always foxy proxy through ssh and SOCKS to access the host, so more IPs are safer and avoid you accidentally locking yourself out. Once they are built, make sure to configure Cockpit to trust the domain as an origin. Open ''sudo nano /etc/cockpit/cockpit.conf'' and drop in the following:

<code>
[WebService]
AllowUnencrypted = true
Address = 0.0.0.0
Origins = https://*.haacksnetworking.org http://127.0.0.1:9090
ProtocolHeader = X-Forwarded-Proto
ForwardedForHeader = X-Forwarded-For
</code>

This instructs Cockpit's internal web socket system to trust the domain/origin and the web socket reverse proxy that we configured in apache (since it differs from the listener on localhost). //Adjust the domain and subdomain wildcard to fit your actual domain//. Restart the server or minimally restart cockpit+apache. Once they are restarted and their status healthy, navigate to ''domain.com'' in a browser and it should redirect to TLS and show the Cockpit landing page. If not, trace over the steps above and fix your work before proceeding. 

=== Discussion on Access to Cockpit ===

There's a lot of debate about whether production servers that run virtualized services (VMs, containers, etc.) should be publicly exposed. Now, if you fully trust your server and Cockpit's web auth, no need to continue. For most folks, however, retaining ssh access and locking everything else down is usually the go to ... meaning that 80/443 will be closed. Additionally, as already shown above, we are letting the web server (apache) further restrict url requests with the location package. At first, this might seem like we are locking down the web server that we need to access the service, but/and we are actually tunneling through ssh instead. Additionally, the addition of TLS - while not adding any security benefit to the ssh tunnel - avoids the web browser barf you get on IPs, localhost endpoints, etc., and gives you an easy to remember domain. Okay, let's install ufw and open ssh and leave everything else closed.

  sudo apt install ufw
  sudo ufw reset
  sudo ufw allow 22
  
Now that that is done, we need to make a special certbot entry in cron that uses a pre/post hook in order to briefly open port 80 for renewal and then close it again. To do that, let's edit our ''sudo crontab -e'' entry as follows:

  30 2 * * 1 certbot renew --apache --pre-hook "ufw allow 80/tcp" --post-hook "ufw delete allow 80/tcp" >> /var/log/le-renew.log 2>&1

This adjusted script briefly opens up 80 every 30 days to see if the cert needs renewal. After it checks, it closes the port back up. At this point, one might realize, what value is Let's Encrypt even providing here? If 80/443 are closed and you are running everything through ssh. As I mentioned above, the addition of TLS removes browser complaints and provides an easy to remember domain for access, but/and, if I make a mistake or ufw fails, etc., then Cockpit faces the public with not only TLS, but with the location restrictions stated above. This ensures that Cockpit is triple protected: ssh tunnel, ufw, and apache locations. To access the Cockpit web interface, we first ssh into the host with the ''-D'' flag:

  ssh -D 8090 root@domain.com 

Once you are logged in, configure your Firefox's network settings to use SOCKS5 proxy with localhost and port 8090. //Using 8090 or something non-standard is helpful as containers and/or other services might already be bound to 8080//. You can now enter domain.com into your browser and your Cockpit instance will just work. If you check from another location, it won't work because 80/443 are closed (or your IPs are not approved). It's using the reverse proxy but accessing it locally (via the ssh tunnel), which is automatically trusted by apache. If changing Firefox's network settings proves inconvenient or cumbersome, you can setup a proxy with the foxyproxy addon for Firefox:

{{ :computing:screenshot_20261009_205620.png?direct&800 |}}

Of course, you could have skipped the apache configuration entirely and just run the ssh proxy and accessed Cockpit via localhost:9090 and/or 127.0.0.1:9090 but then you have to edit Firefox's developer settings to allow "localhost hijacking" or Firefox will get confused over which 'local' host is intended? Especially with reverse proxies, some internal web service assets will be originating from localhost (since they are behind the reverse proxy lol) and thus Firefox gets confused. There are also associated security concerns. However, if you want to avoid the apache part and just ssh with SOCKS, set the following to true:

{{ :computing:screenshot_from_2026-03-29_13-28-00.png?direct |}}

Set this value to true and you can then access Cockpit via localhost:9090 without any issues. Before doing this, however, be aware of the risks/dangers of this approach. Just search //localhost hijacking// if you need to read up on it. I personally use the reverse proxy with apache, which although overkill, also results in avoiding this flag / dev mode hack. Other solutions involve binding Cockpit to a local IP and then proxying into the host and accessing via that IP:9090, or simply using the Cockpit flatpak, which connects via ssh and runs the Cockpit web socketing system internally, and even allows folks to connect to instances without Cockpit installed and get that familiar form factor:

  * [[https://cockpit-project.org/faq.html|Using Cockpit ]]

In conclusion, this tutorial allows for secure web browser access with no browser barf or work arounds. The cert renews on schedule and briefly opens port 80 during that process. If something goes wrong, TLS is ready and secure if ufw or location packages fail. Additionally, since ssh is open by default, one can also simply use the official Cockpit flatpak. However, it's nice to not have to rely on the flatpak and this tutorial solves that. Another thing that users might desire is a custom fail2ban jail that will work with the reverse proxy. First, open and create the filter logic:

<code>
nano /etc/fail2ban/filter.d/cockpit-apache.conf
[Definition]
failregex = ^.*cockpit-session\[\d+\]: pam_unix\(cockpit:auth\): authentication failure; .* rhost=<HOST> .*
ignoreregex =
</code>

Now, create the jail:

<code>
nano /etc/fail2ban/jail.local
[cockpit-apache]
enabled      = true
port         = http,https
filter       = cockpit-apache
backend      = systemd
journalmatch = _COMM=cockpit-session
logpath      = /var/log/journal
maxretry     = 3
</code>

The pcp logging tool has a cranky timer:

  apt install pcp python3-pcp cockpit-bridge
  systemctl enable --now pmlogger.service
  systemctl enable --now pmlogger_daily.timer
  systemctl enable --now pmlogger_check.timer
  systemctl restart pmlogger
  systemctl status pmlogger_daily.timer
  systemctl list-timers | grep pmlogger
  systemctl reset-failed pmlogger_daily.service



 --- //[[alerts@haacksnetworking.org|oemb1905]] 2026/10/19 14:50//