Deployment Guide

Cockpit listens for both HTTP and HTTPS connections on the same port, by default 9090. If an HTTP connection is made, Cockpit will redirect that connection to HTTPS. There are some exceptions:

This behavior can be overridden by setting the AllowUnencrypted option in cockpit.conf.

Cockpit will load a certificate from the /etc/cockpit/ws-certs.d, directory, or below $XDG_CONFIG_DIRS if set (see cockpit.conf). It will use the last file with a .cert or .crt extension in alphabetical order. The file should contain one or more OpenSSL style BEGIN CERTIFICATE blocks for the server certificate and the intermediate certificate authorities.

The private key must be contained in a separate file with the same name as the certificate, but with a .key suffix instead. The key must not be encrypted.

If no certificate is found, a self-signed certificate is created and stored in the 0-self-signed.cert file. On some platforms, Cockpit will also generate a ca.crt in that directory, which may be safely imported into client browsers.

Cockpit will read the files as root, so they can have tight permissions.

To check which certificate cockpit-ws will use run the following command.

Or, on Debian-based systems:

If using certmonger to manage certificates, following command can be used to automatically prepare a certificate/key file pair:

This will not work on Red Hat Enterprise Linux 8 by default. Adjust the SELinux type of the certificate directory to cert_t to allow certmonger to write its certificates there:

On servers with systemd Cockpit starts on demand via socket activation. To change its port and/or address you should place the following content in the /etc/systemd/system/cockpit.socket.d/listen.conf file. Create the file and directories in that path which not already exist. The ListenStream option specifies the desired address and TCP port.

The FreeBind option is highly recommended when defining specific IP addresses. See the systemd.socket manpage for details.

In order for the changes to take effect, run the following commands:

If SELinux is protecting your server, then you will need to tell it to allow Cockpit to listen on the new port. Run the following command to do so. The last argument specifies the desired TCP port.

If the port is already defined by some other part of the SELinux policy, then you will need to use the -m argument to modify the definition. That’s the case with the 443 SSL port, which is typically defined as an http_port_t port.

The changes should take effect immediately.

If Firewalld is configured as your firewall, then you will need to tell it to allow Cockpit to receive connections on the new port. Run the following commands to do so. The last options specify the desired TCP port.

The cockpit-bridge process will exit when the user logs out. In addition, after 10 minutes of inactivity, the cockpit-ws process will exit on its own. The browser will automatically disconnect if it fails to hear from the cockpit-ws process for 30 seconds.

To make Cockpit available by default after system boot the cockpit.socket needs to be enabled:

If you wish to not have Cockpit available by default via a browser, then the cockpit.socket should be disabled:

The most common way to use Cockpit is to just log directly into the server that you want to access. This can be done if you have direct network access to port 9090 on that server.

By default the cockpit web service is installed on the base system and socket activated by systemd. In this setup access is controlled by a cockpit specific pam stack, generally located at /etc/pam.d/cockpit. By default this is configured to allow you to login with the username and password of any local account on the system. You can also setup a Kerberos based SSO solution or certificate/smart card authentication.

You can also disable authentication schemes to enforce authentication policies, or to suppress undesired browser GSSAPI authentication dialogs.

The web server can also be run from the cockpit/ws container. If you are running cockpit on a container host operating system like Fedora CoreOS this will be the only supported mode. In this setup, cockpit establishes an SSH connection from the container to the underlying host, meaning that it is up to your SSH server to grant access. To login with a local account, sshd will need to be configured to allow password based authentication. Alternatively you can setup a Kerberos based SSO solution.

Like sshd, cockpit can be configured to limit the number of concurrent login attempts allowed. This is done by adding a MaxStartups option to the WebService section of your cockpit.conf. Additional connections will be dropped until authentication succeeds or the connections are closed.

It is also possible to log into a secondary server without opening a session on the primary server. This is useful if you are not actually interested in the primary server and would only use it because you do not have direct network access to the secondary server.

In this case, cockpit-ws still runs on the primary server, but the credentials from the login screen are directly used with SSH to log into the secondary server given in the "Connect To" field of the login screen.

Thus, the PAM configuration and accounts on the primary server don’t matter at all. Often, the only purpose of the primary server is to sit on the boundary of your network and forward connections to internal machines.

In this case, the login page will prompt you to verify unknown SSH keys. Accepted keys will be remembered in the local storage of your browser.

Once you have a session on the primary server, it is possible connect to additional servers by using the host switching UI of the Cockpit Shell. This is useful if you have direct network access to the primary server, but not to the secondary server.

On the command line, you would log into the primary server and then use SSH to log into the secondary one. Cockpit does just the same, and uses SSH to log into the secondary server. Instead of running a interactive shell there, however, it starts a cockpit-bridge process.

Warning: Unlike with SSH on the command line though, this will also load and use the Cockpit pages (i.e. JavaScript) from the remote machine, which means that the remote machine can execute arbitrary code on your primary and all other connected secondary machines. Hence, only connect to machines which you trust.

Due to this security risk, this host switcher functionality is disabled by default, except on long-term stable Linux distributions (Red Hat Enterprise Linux 9, Debian 12, and Ubuntu 22.04/24.04 LTS). If you are comfortable with the security implications, you can enable it manually with the AllowMultiHost option in cockpit.conf.

These servers will need to be running an SSH server and be configured to support one of the following authentication methods.

To authenticate users, the server that Cockpit is running on must be joined to a domain. This can usually be accomplished using the realm join example.com command.

The domain must be resolvable by DNS. For instance, the SRV records of the kerberos server should be resolvable:

The server running Cockpit should have a fully qualified name that ends with the domain name.

There must be a valid Kerberos host key for the server in the /etc/krb5.keytab file. Alternatively, if you would like to use a different keytab, you can do so by placing it in /etc/cockpit/krb5.keytab, or below $XDG_CONFIG_DIRS if set (see cockpit.conf). It may be necessary to create a kerberos service principal and update the keytab if it is not present. Depending on your domain type different service names are required:

When joining an IPA domain with Cockpit and the ipa command line tool is available, both the service principal name and a /etc/cockpit/krb5.keytab get created automatically, so that Kerberos based single sign on into Cockpit works out of the box. If you want/need to do this by hand or in a script, first create or modify the HTTP/ service principal:

Then generate a key for that principal:

The following command can be used to list the /etc/cockpit/krb5.keytab:

Lastly accounts from the domain must be resolvable to unix accounts on the server running Cockpit. For example:

If you wish to delegate your kerberos credentials to Cockpit, and allow Cockpit to then connect to other machines using those credentials, you should enable delegation for the hosts running Cockpit, and in some cases the HTTP service as well. When joining an IPA domain, this is enabled by default.

Domain admins (usually the admins@example.com group) should normally also be able to administer any joined machine. Enable sudo access for that group with the following command on the IPA server, for version 4.7.1 and later:

On earlier FreeIPA versions, run these commands instead, as a domain admin on any joined machine:

Note that this does not change security properties; domain admins can give this privilege to themselves, so it is safe to enable by default.

The client side, where your web browser is running, should have a valid kerberos ticket in the current user session. A command like this will get one:

In addition your browser must be usually be configured to allow kerberos authentication for the domain.

Use a fully qualified server name (with the domain name at the end) to access Cockpit in your web browser.

If you wish to connect from one server to another in Cockpit using kerberos SSO, then you have to explicitly enable all sorts of things. For starters, make sure that delegated credentials are allowed by your domain (see above). Next when requesting your kerberos ticket make sure that forwardable tickets are requested:

Make sure that the forwardable flag F is present in your ticket:

Lastly configure your browser to allow delegated, forwardable kerberos credentials to be sent to Cockpit:

Generating the certificates for users is usually done with a certificate management system like certmonger or FreeIPA, which are not documented here. This command generates a simple key and certificate request for the "alice" user:

Now get this certificate request signed by the Certificate Authority of your Identity Management domain, to get a PEM certificate. Browsers and smart cart utilities accept PKCS#12 format for importing/transfer, so convert the certificate/key pair; it will ask for and protect it with a transfer password:

Don’t forget to clean up the key file when you do not need it any more:

You can now import alice.p12 directly into your browser, with giving the transfer password set above. Or put the certificate onto a smart card:

The recommended method to sign a user certificate request and associate it to a user is ipa cert-request:

Alternatively, if you are using a different CA, you can use ipa user-add-cert to associate the signed certificate to the user. This expects PEM format, but without the -----BEGIN/-----END markers:

See the FreeIPA User Certificates documentation for details.

The domain user certificates get imported into the userCertificate;binary LDAP attribute. The following commands convert the PEM certificate into binary DER form, create an LDIF file and apply it to the LDAP server running on the domain controller "dc.example.com":

At least some versions of Samba do not support the userCertificate;binary LDAP attribute, so the import has to happen in base64 PEM form into the textual userCertificate attribute instead. Also, Samba uses a slightly different user hierarchy:

As userCertificate is a text instead of binary field, you need to set up a certificate mapping rule in sssd.conf(5) in a [certmap/domain/rulename] section, for example:

Set the trusted Certificate Authority of your user certificates in sssd, either by copying the CA PEM file to /etc/sssd/pki/sssd_auth_ca_db.pem or setting the pam_cert_db_path configuration option to the path of the CA. If you use FreeIPA and its CA:

Certificate authentication needs to be enabled in cockpit.conf explicitly:

When enabling this mode, other authentication types commonly get disabled, so that only client certificate authentication will be accepted. By default, after a failed certificate authentication attempt, Cockpit’s normal login page will appear and permit other login types such as basic (passwords) or negotiate (Kerberos). For example, password authentication gets disabled with:

When using certificate authentication, all requests with a particular certificate will be handled by a separate and isolated instance of the cockpit-ws web server. This protects against possible vulnerabilities in the web server and prevents an attacker from impersonating another user. However, this introduces a potential Denial of Service: Some remote attacker could create a large number of certificates and send a large number of http requests to Cockpit with these.

To mitigate that, all cockpit-ws instances run in a system-cockpithttps.slice systemd slice unit which limits the collective resources of these web server instances: by default, this slice sets a limit of 200 threads (roughly 100 instances of cockpit-ws — in other words, a maximum of 100 parallel user sessions with different certificates) and a 75% (soft)/90% (hard) memory limit.

You are welcome to adjust these limits to your need through a drop-in. For example:

Once you logged into Cockpit with a certificate, you likely need to switch to administrative mode (root privileges through sudo), or connect to remote machines through SSH. If your user account has a password, that can be used for authenticating to sudo or ssh as usual.

Supported with FreeIPA only: As an alternative to password authentication, you can also declare the initial Cockpit certificate authentication as trusted for authenticating to SSH, sudo, or other services. For that purpose, Cockpit automatically creates an S4U2Proxy Kerberos ticket in the user session:

You can set up constrained delegation rules to enumerate which hosts (including its own) that ticket is trusted to access. For example, if the cockpit session runs on host myhost.example.com and should be trusted to access its own host (through sudo) and another host remote.example.com (through ssh), create a delegation like this:

In addition, you need to enable GSS (Kerberos) authentication in the corresponding services.

Caveat: The delegated S4U ticket is not yet forwarded to remote SSH hosts when connecting to them from Cockpit, so authenticating to sudo on the remote host with that ticket does not work. This will be provided in a future version.

Services like systemd and NetworkManager use Polkit to validate and escalate privileges. It is possible to customize these rules with files in /etc/polkit-1/rules.d.

Polkit rules files are javascript with specific methods and objects. For example, placing the following polkit rule to /etc/polkit-1/rules.d/10-operators.rule allows all users in the operators group to start, stop, restart and otherwise manage systemd services:

In order to allow a certain group to perform any administrative action you could add a rule like this: