'\" t
.\"     Title: cockpit.conf
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 03/04/2021
.\"    Manual: cockpit.conf
.\"    Source: cockpit
.\"  Language: English
.\"
.TH "COCKPIT\&.CONF" "5" "03/04/2021" "cockpit" "cockpit.conf"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
cockpit.conf \- Cockpit configuration file
.SH "DESCRIPTION"
.PP
Cockpit can be configured via /etc/cockpit/cockpit\&.conf\&. 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\&.\&.
.PP
Note: The port that cockpit listens on cannot be changed in this file\&. To change the port change the systemd
cockpit\&.socket
file\&.
.SH "WEBSERVICE"
.PP
\fBOrigins\fR
.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\&.
.sp
.if n \{\
.RS 4
.\}
.nf
[WebService]
Origins = https://somedomain1\&.com https://somedomain2\&.com:9090
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBProtocolHeader\fR
.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\&.
.sp
.if n \{\
.RS 4
.\}
.nf
[WebService]
ProtocolHeader = X\-Forwarded\-Proto
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBLoginTitle\fR
.RS 4
Set the browser title for the login screen\&.
.RE
.PP
\fBLoginTo\fR
.RS 4
When set to
true
the
\fIConnect to\fR
option on the login screen is visible and allows logging into another server\&. If this option is not specified then it will be automatically detected based on whether the
\fBcockpit\-ssh\fR
process is available or not\&.
.RE
.PP
\fBRequireHost\fR
.RS 4
When set to
true
cockpit will require users to use the
\fIConnect to\fR
option to specify the host to log into\&.
.RE
.PP
\fBMaxStartups\fR
.RS 4
Same as the
\fBsshd\fR
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\&.
.sp
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)\&.
.RE
.PP
\fBAllowUnencrypted\fR
.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
/ping)\&. Defaults to false\&.
.RE
.PP
\fBUrlRoot\fR
.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\&.
/cockpit/
and
/cockpit+
are reserved and should not be used\&. For example
/cockpit\-new/
is ok\&.
/cockpit/
and
/cockpit+new/
are not\&.
.RE
.PP
\fBClientCertAuthentication\fR
.RS 4
If true, enable TLS client certificates for authenticating users\&. Commonly these are provided by a smart card, but it\*(Aqs equally possible to import certificates directly into the web browser\&. Please see the
\m[blue]\fBCertificate/smart card authentication\fR\m[]\&\s-2\u[1]\d\s+2
section in the Cockpit guide for details\&.
.RE
.PP
\fBShell\fR
.RS 4
The relative URL to top level component to display in Cockpit once logged in\&. Defaults to
/shell/index\&.html
.RE
.SH "LOG"
.PP
\fBFatal\fR
.RS 4
The kind of log messages in the bridge to treat as fatal\&. Separate multiple values with spaces\&. Relevant values are:
criticals
and
warnings\&.
.RE
.SH "OAUTH"
.PP
Cockpit can be configured to support the
\m[blue]\fBimplicit grant\fR\m[]\&\s-2\u[2]\d\s+2
OAuth authorization flow\&. 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 a to be configured to verify and allow
Bearer
tokens\&.
.PP
\fBURL\fR
.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
.PP
\fBErrorParam\fR
.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
error_description
.RE
.PP
\fBTokenParam\fR
.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
access_token
.RE
.SH "SESSION"
.PP
\fBBanner\fR
.RS 4
The contents of the specified file (commonly
/etc/issue) are shown on the login page\&. By default, no banner is displayed\&.
.RE
.PP
\fBIdleTimeout\fR
.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
0
to disable session timeout\&.
.sp
.if n \{\
.RS 4
.\}
.nf
[Session]
IdleTimeout=15
.fi
.if n \{\
.RE
.\}
When not specified, there is no idle timeout by default\&.
.RE
.SH "BUGS"
.PP
Please send bug reports to either the distribution bug tracker or the
\m[blue]\fBupstream bug tracker\fR\m[]\&\s-2\u[3]\d\s+2\&.
.SH "AUTHOR"
.PP
Cockpit has been written by many
\m[blue]\fBcontributors\fR\m[]\&\s-2\u[4]\d\s+2\&.
.SH "SEE ALSO"
.PP
\fBcockpit-ws\fR(8),
\fBcockpit-tls\fR(8)
.SH "NOTES"
.IP " 1." 4
Certificate/smart card authentication
.RS 4
\%https://cockpit-project.org/guide/latest/cert-authentication.html
.RE
.IP " 2." 4
implicit grant
.RS 4
\%https://tools.ietf.org/html/rfc6749#section-4.2
.RE
.IP " 3." 4
upstream bug tracker
.RS 4
\%https://github.com/cockpit-project/cockpit/issues/new
.RE
.IP " 4." 4
contributors
.RS 4
\%https://github.com/cockpit-project/cockpit/
.RE