COCKPIT.CONF(5)

📦
version 370 · 15 versions
, in arch rolling, centos-stream 10, centos-stream 9, fedora 43, fedora 44

💅 COCKPIT.CONF 💅

okay bestie, buckle up, because cockpit.conf is a whole manual — it's section 5 of the cockpit docs, and it's basically the little config file that runs the whole vibe ✨

🌸 NAME 🌸

cockpit.conf — the Cockpit configuration file. yes that's it, that's the name, slay 🎀

🦋 DESCRIPTION 🦋

So here's the tea: Cockpit can be configured via /etc/cockpit/cockpit.conf. BUT — and this is the plot twist — if $XDG_CONFIG_DIRS is set, then the first path containing a ../cockpit/cockpit.conf is used instead. And all the other configuration files and directories get searched for in the same way, fr fr.

This file is literally not required and you might have to create it manually yourself (not me having to touch a config file in the year of our lord 😭). It has INI file syntax, which means it's just key / value pairs grouped into topical groups. There's examples below, go look, they're cute.

⚠️ Note: the port that cockpit listens on cannot be changed in this file. To change the port, change the systemd cockpit.socket file. that's the rules bestie, i don't make them 💀

✨ WEBSERVICE ✨

🌈 Origins

By default cockpit will not accept crossdomain websocket connections, no cap. Use this setting to allow access from alternate domains. Origins should include scheme, host and port, if necessary. Wildcards and glob expressions are permitted 👑. IPv6 addresses must have their brackets escaped with backslashes (e.g. \[::1\]) as they are matched using fnmatch().

[WebService]
Origins = https://somedomain1.com https://somedomain2.com:9090 https://*.somedomain3.com https://\[::1\]:9090

🔥 ProtocolHeader

Configure cockpit to look at the contents of this header to determine if a connection is using tls. This should only be used when cockpit is behind a reverse proxy, and care should be taken to make sure that incoming requests cannot set this header. (important!! like, actually important 💅)

[WebService]
ProtocolHeader = X-Forwarded-Proto

🫶 ForwardedForHeader

Configure cockpit to look at the contents of this header to determine the real origin of a connection. This should only be used when cockpit is behind a reverse proxy, and care should be taken to make sure that incoming requests cannot set this header. (yes this is the same warning as above, and yes it still matters, iykyk)

[WebService]
ForwardedForHeader = X-Forwarded-For

🎀 LoginTitle

Sets the browser title for the login screen. little browser tab moment ✨

🦋 LoginTo

When set to true, the Connect to option on the login screen is visible and allows logging into another server. When set to false, direct remote logins are disallowed. If this option is not specified, then it will be automatically detected based on whether the cockpit-bridge package is installed and the ssh program is available.

If cockpit-ws is exposed to the public internet, and also has access to a private internal network, it is recommended to explicitly set LoginTo=false. This prevents unauthenticated remote attackers from scanning the internal network for existing machines and open ports. (pleaseee do this one, it's giving security main character energy 🔥)

🌸 RequireHost

When set to true, cockpit will require users to use the Connect to option to specify the host to log into.

⭐ AllowMultiHost

When set to true, cockpit will allow users to connect to multiple hosts in one session. The default is OS specific.

When connecting to multiple servers, JavaScript runs without isolation. All systems will be vulnerable to potential attacks from other connected hosts. Enable this option only when all hosts are trusted. 💀 not me stressing about this one

👑 MaxStartups

Same as the sshd configuration option by the same name. Specifies the maximum number of concurrent login attempts allowed. Additional connections will be dropped until authentication succeeds or the connections are closed. Defaults to 10.

Alternatively, random early drop can be enabled by specifying the three colon separated values start:rate:full (e.g. "10:30:60"). Cockpit will start refusing authentication attempts with a probability of rate/100 (30%) if there are currently start (10) unauthenticated connections. The probability increases linearly and all connection attempts are refused if the number of unauthenticated connections reaches full (60). math ate, honestly 🧮✨

💜 MaxConcurrentConnections

Limits the number of concurrent HTTP connections on the Cockpit port. Connection attempts that exceed this limit are rejected early on without reading a single byte. This can be used during brute-force attacks. It differs from MaxStartups, which protects against too many concurrent authentication attempts. Defaults to 500.

🍓 AllowUnencrypted

If true, cockpit will accept unencrypted HTTP connections. Otherwise, it redirects all HTTP connections to HTTPS. Exceptions are connections from localhost and for certain URLs (like /ping). Defaults to false.

🌈 UrlRoot

The root URL where you will be serving cockpit. When provided, cockpit will expect all requests to be prefixed with the given url. This is mostly useful when you are using cockpit behind a reverse proxy, such as nginx. /cockpit/ and /cockpit+ are reserved and should not be used. For example /cockpit-new/ is ok. /cockpit/ and /cockpit+new/ are not. read it twice, bestie 📖

🧚 ClientCertAuthentication

If true, enable TLS client certificates for authenticating users. Commonly these are provided by a smart card, but it's equally possible to import certificates directly into the web browser. Please see the "Certificate/smart card authentication" section in the Cockpit guide for details — [https://docs.cockpit-project.org/cockpit-guide/latest/guide/cert-authentication.html](https://docs.cockpit-project.org/cockpit-guide/latest/guide/cert-authentication.html).

💖 Shell

The relative URL to top level component to display in Cockpit once logged in. Defaults to /shell/index.html.

🎀 CustomLoginPage

Load the login page from an alternative directory. The directory must contain a login.html and optionally a po.js file for translations. When not set, the hardcoded $prefix/share/cockpit/static directory is used.

💅 LOG 💅

🌸 Fatal

The kind of log messages in the bridge to treat as fatal. Separate multiple values with spaces. Relevant values are: criticals and warnings.

🔥 OAUTH 🔥

Cockpit can be configured to support the implicit grant OAuth authorization flow ([https://tools.ietf.org/html/rfc6749#section-4.2](https://tools.ietf.org/html/rfc6749#section-4.2)). When successful, the resulting oauth token will be passed to cockpit-ws using the Bearer auth-scheme. For a login to be successful, cockpit will also need to be configured to verify and allow Bearer tokens.

⭐ URL

This is the url that cockpit will redirect the users browser to when it needs to obtain an oauth token. Cockpit will add a redirect_uri parameter to the url with the location of where the oauth provider should redirect to once a token has been obtained.

🦋 ErrorParam

When a oauth provider redirects a user back to cockpit, look for this parameter in the querystring or fragment portion of the url to find a error message. When not provided, it will default to error_description.

🌈 TokenParam

When a oauth provider redirects a user back to cockpit, look for this parameter in the querystring or fragment portion of the url to find the access token. When not provided, it will default to access_token.

🫶 SESSION 🫶

The contents of the specified file (commonly /etc/issue) are shown on the login page. By default, no banner is displayed.

👑 IdleTimeout

Time in minutes after which session expires and user is logged out if no user action has been performed in the given time. This idle timeout only applies to interactive password logins. With non-interactive authentication methods like Kerberos, OAuth, or certificate login, the browser cannot forget credentials, and thus automatic logouts are not useful for protecting credentials of forgotten sessions. Set to 0 to disable session timeout. (yes bestie, 0 means never, icon behaviour honestly)

[Session]
IdleTimeout=15

When not specified, there is no idle timeout by default.

💜 WarnBeforeConnecting

Whether to warn before connecting to remote hosts from the Shell. Defaults to true.

[Session]
WarnBeforeConnecting=false

😭 BUGS 😭

Please send bug reports to either the distribution bug tracker or the upstream bug tracker — [https://github.com/cockpit-project/cockpit/issues/new](https://github.com/cockpit-project/cockpit/issues/new). they wanna hear from you fr fr 🫶

🌟 AUTHOR 🌟

Cockpit has been written by many contributors — [https://github.com/cockpit-project/cockpit](https://github.com/cockpit-project/cockpit). legends, all of them 👑

💫 SEE ALSO 💫

okay that's the whole page, you ate it, periodt 💅✨

this little love letter to cockpit.conf is straight out of cockpit, dated 2026-10-22 — go forth and configure responsibly, bestie 🎀🦋💖

📦 where this page comes from