'\" t
.\"     Title: cockpit.conf
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.26
.\"      Date: 2026-08-27
.\"    Manual: cockpit
.\"    Source: cockpit
.\"  Language: English
.\"
.TH "COCKPIT.CONF" "5" "2026-08-27" "cockpit" "cockpit"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAME"
cockpit.conf \- Cockpit configuration file
.SH "DESCRIPTION"
.sp
Cockpit can be configured via /etc/cockpit/cockpit.conf. If
\fB$XDG_CONFIG_DIRS\fP is set, then the first path containing a
\fB../cockpit/cockpit.conf\fP is used instead. Other configuration files
and directories are searched for in the same way.
.sp
This file is not required and may need to be created manually. The file
has a INI file syntax and thus contains key / value pairs, grouped into
topical groups. See the examples below for details.
.sp
Note: The port that cockpit listens on cannot be changed in this file.
To change the port change the systemd \fBcockpit.socket\fP file.
.SH "WEBSERVICE"
.sp
\fBOrigins\fP
.RS 4
By default cockpit will not accept crossdomain websocket connections.
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. \f(CR\(rs[::1\(rs]\fP) as they are matched using \f(CRfnmatch()\fP.

.br
.RE
.sp
.if n .RS 4
.nf
.fam C
[WebService]
Origins = https://somedomain1.com https://somedomain2.com:9090 https://*.somedomain3.com https://\(rs[::1\(rs]:9090
.fam
.fi
.if n .RE
.sp
\fBProtocolHeader\fP
.RS 4
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.

.br
.RE
.sp
.if n .RS 4
.nf
.fam C
[WebService]
ProtocolHeader = X\-Forwarded\-Proto
.fam
.fi
.if n .RE
.sp
\fBForwardedForHeader\fP
.RS 4
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.

.br
.RE
.sp
.if n .RS 4
.nf
.fam C
[WebService]
ForwardedForHeader = X\-Forwarded\-For
.fam
.fi
.if n .RE
.sp
\fBLoginTitle\fP
.RS 4
Set the browser title for the login screen.
.RE
.sp
\fBLoginTo\fP
.RS 4
When set to \f(CRtrue\fP the \fIConnect to\fP option on the login screen is
visible and allows logging into another server. When set to \f(CRfalse\fP,
direct remote logins are disallowed. If this option is not specified
then it will be automatically detected based on whether the
\fBcockpit\-bridge\fP package is installed and the \fBssh\fP program is
available.
.br

.br
If cockpit\-ws is exposed to the public internet, and also has access
to a private internal network, it is recommended to explicitly set
\fBLoginTo=false\fP. This prevents unauthenticated remote attackers from
scanning the internal network for existing machines and open ports.
.RE
.sp
\fBRequireHost\fP
.RS 4
When set to \f(CRtrue\fP cockpit will require users to use the \fIConnect
to\fP option to specify the host to log into.
.RE
.sp
\fBAllowMultiHost\fP
.RS 4
When set to \f(CRtrue\fP, cockpit will allow users to connect to multiple
hosts in one session. The default is OS specific.
.br

.br
When connecting to multiple servers, JavaScript runs without
isolation. All systems will be vulnerable to potential attacks from
other connected hosts. Enable this option \fIonly\fP when all hosts are
trusted.
.RE
.sp
\fBMaxStartups\fP
.RS 4
Same as the \fBsshd\fP 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.
.br

.br
Alternatively, random early drop can be enabled by specifying the
three colon separated values \fBstart:rate:full\fP (e.g. "10:30:60").
Cockpit will start refusing authentication attempts with a probability
of \fBrate/100\fP (30%) if there are currently \fBstart\fP (10)
unauthenticated connections. The probability increases linearly and
all connection attempts are refused if the number of unauthenticated
connections reaches \fBfull\fP (60).
.RE
.sp
\fBAllowUnencrypted\fP
.RS 4
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 \fB/ping\fP). Defaults to
false.
.RE
.sp
\fBUrlRoot\fP
.RS 4
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. \f(CR/cockpit/\fP and \f(CR/cockpit+\fP are reserved and should not
be used. For example \f(CR/cockpit\-new/\fP is ok. \f(CR/cockpit/\fP and
\f(CR/cockpit+new/\fP are not.
.RE
.sp
\fBClientCertAuthentication\fP
.RS 4
If true, enable TLS client certificates for authenticating users.
Commonly these are provided by a smart card, but it\(cqs equally possible
to import certificates directly into the web browser. Please see the
\c
.URL "https://docs.cockpit\-project.org/cockpit\-guide/latest/guide/cert\-authentication.html" "Certificate/smart
card authentication"  section in the Cockpit guide for details.
.RE
.sp
\fBShell\fP
.RS 4
The relative URL to top level component to display in Cockpit once
logged in. Defaults to \f(CR/shell/index.html\fP
.RE
.sp
\fBCustomLoginPage\fP
.RS 4
Load the login page from an alternative directory. The directory must
contain a \f(CRlogin.html\fP and optionally a \f(CRpo.js\fP file for translations.
When not set, the hardcoded \f(CR$prefix/share/cockpit/static\fP directory is used.
.RE
.SH "LOG"
.sp
\fBFatal\fP
.RS 4
The kind of log messages in the bridge to treat as fatal. Separate
multiple values with spaces. Relevant values are: \fBcriticals\fP and
\fBwarnings\fP.
.RE
.SH "OAUTH"
.sp
Cockpit can be configured to support the
.URL "https://tools.ietf.org/html/rfc6749#section\-4.2" "implicit grant" ""
OAuth
authorization flow. When successful the resulting oauth token will be
passed to cockpit\-ws using the \fBBearer\fP auth\-scheme. For a login to be
successful, cockpit will also need a to be configured to verify and
allow \fBBearer\fP tokens.
.sp
\fBURL\fP
.RS 4
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.
.RE
.sp
\fBErrorParam\fP
.RS 4
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
\fBerror_description\fP
.RE
.sp
\fBTokenParam\fP
.RS 4
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
\fBaccess_token\fP
.RE
.SH "SESSION"
.sp
\fBBanner\fP
.RS 4
The contents of the specified file (commonly \fB/etc/issue\fP) are shown
on the login page. By default, no banner is displayed.
.RE
.sp
\fBIdleTimeout\fP
.RS 4
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 \fB0\fP
to disable session timeout.

.br
.RE
.sp
.if n .RS 4
.nf
.fam C
[Session]
IdleTimeout=15
.fam
.fi
.if n .RE
.sp

.RS 4
When not specified, there is no idle timeout by default.
.RE
.sp
\fBWarnBeforeConnecting\fP
.RS 4
Whether to warn before connecting to remote hosts from the Shell.
Defaults to true.

.br
.RE
.sp
.if n .RS 4
.nf
.fam C
[Session]
WarnBeforeConnecting=false
.fam
.fi
.if n .RE
.SH "BUGS"
.sp
Please send bug reports to either the distribution bug tracker or the \c
.URL "https://github.com/cockpit\-project/cockpit/issues/new" "upstream bug tracker" "."
.SH "AUTHOR"
.sp
Cockpit has been written by many
.URL "https://github.com/cockpit\-project/cockpit" "contributors" "."
.SH "SEE ALSO"
.sp
\fBcockpit\-ws\fP(8), \fBcockpit\-tls\fP(8)