cockpit-tls

Serve HTTP requests to a specific port instead of port 9090

$ cockpit-tls --port [port]

$ cockpit-tls --help

cockpit-tls [OPTIONS]

--self-signed
    Generates a new self-signed TLS certificate for the Cockpit web console. This option is useful for initial setup or testing environments where a trusted Certificate Authority (CA) certificate is not immediately required or available.

--host
    Specifies the hostname for which the self-signed certificate will be issued when used with --self-signed. If omitted, the system's current hostname is used by default.

--cert
    Specifies the full path to an existing TLS certificate file (e.g., fullchain.pem, .crt, .pem). This option must be used in conjunction with the --key option.

--key
    Specifies the full path to the private key file that corresponds to the certificate provided with the --cert option. This option is mandatory when --cert is used.

--help
    Displays a brief help message summarizing the command's usage and options, then exits.

--version
    Displays the version information of the cockpit-tls command and then exits.

cockpit-tls is a specialized utility command designed to configure Transport Layer Security (TLS) certificates for the Cockpit web console. Cockpit serves as a web-based graphical interface for Linux servers, enabling administrators to manage system services, storage, networking, and more directly through a browser. Ensuring secure communication between the client's browser and the Cockpit server is paramount, and cockpit-tls facilitates this by managing the SSL/TLS certificates utilized by the cockpit-ws service.

This command simplifies certificate management tasks, allowing users to generate self-signed certificates for quick setup and testing, or to install and configure Cockpit to use pre-existing certificates and their corresponding private keys. It can also help integrate with system-wide certificate management solutions. By automating much of the TLS configuration process, cockpit-tls ensures that the Cockpit interface is securely accessible via HTTPS, placing certificates typically in the /etc/cockpit/ws-certs.d/ directory for the cockpit-ws daemon to pick up.

When generating certificates with --self-signed, these certificates will not be trusted by standard web browsers, which will result in security warnings. Self-signed certificates are suitable only for testing or internal, trusted networks.

It is crucial to ensure that the certificate and key files specified with --cert and --key have appropriate file permissions, allowing the cockpit-ws service (which typically runs under a dedicated user or group) to read them. Incorrect permissions will prevent Cockpit from establishing a secure connection.

After making any changes to the TLS configuration using cockpit-tls or by manually placing certificate files, it is necessary to restart or reload the cockpit.socket or cockpit.service systemd units for the new certificates to be loaded and take effect.

The cockpit-ws daemon, which serves the Cockpit web interface, primarily looks for TLS certificates in the /etc/cockpit/ws-certs.d/ directory. Certificates within this directory are loaded in alphanumeric order based on their filenames. This means that a certificate named 00-custom.cert will be preferred over 10-another.cert or the default 99-self-signed.cert. This design allows administrators to easily override default or automatically generated certificates by simply placing a higher-priority custom certificate file in this location.

After utilizing cockpit-tls to modify the TLS configuration or after manually placing new certificate files in the designated directory, it is essential to instruct the Cockpit service to reload its configuration. This is typically achieved by reloading or restarting the relevant systemd units. You can reload the socket unit with sudo systemctl reload cockpit.socket, or restart the main service with sudo systemctl restart cockpit.service to ensure the new certificates are loaded and used by the cockpit-ws daemon for secure connections.

Cockpit, the web-based server management tool, was initially released by Red Hat in 2014. From its inception, secure web access has been a core requirement, making the management of TLS certificates an integral part of its design. The cockpit-tls utility, or similar mechanisms for certificate configuration, has been consistently developed to simplify this process. While its exact implementation details might vary slightly across different Linux distributions or Cockpit versions (sometimes appearing as a direct script, a symbolic link, or its functionality being absorbed into other Cockpit components), its primary objective remains the same: to provide a straightforward method for setting up and updating TLS certificates for the Cockpit web service. Over time, it has evolved to support various certificate sources, from basic self-signed options to integrating with more advanced, automated certificate management practices.

cockpit(8), cockpit-ws(8), systemctl(1), openssl(1), certbot(1)