cockpit(1)

Name

cockpit - Cockpit

Description

Cockpit is a web accessible interactive admin interface for Linux machines. Cockpit can usually be accessed on port 9090 of the machine it’s installed on. Cockpit starts on demand. Use your system credentials to log in.

Components

The cockpit-ws web service listens on port 9090 and is started on demand by systemd. The Cockpit web service authenticates the user, loads Cockpit into the browser, and starts cockpit-bridge in a Linux user session.

The cockpit-bridge provides Cockpit in the web browser with access to the system APIs. It does this over its standard in and standard out. The bridge is started like a shell once per Linux user session.

Bugs

Please send bug reports to either the distribution bug tracker or the upstream bug tracker.

Author

Cockpit has been written by many contributors.

See also

cockpit-tls(8) , cockpit.bridge(1) , systemd(1), Cockpit guide

cockpit.conf(5)

Name

cockpit.conf - Cockpit configuration file

Description

Cockpit can be configured via /etc/cockpit/cockpit.conf. If $XDG_CONFIG_DIRS is set, then the first path containing a ../cockpit/cockpit.conf is used instead. Other configuration files and directories are searched for in the same way.

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.

Note: The port that cockpit listens on cannot be changed in this file. To change the port change the systemd cockpit.socket file.

WebService

Origins

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. \[::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. 

[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. 

[WebService]
ForwardedForHeader = X-Forwarded-For
LoginTitle

Set the browser title for the login screen.

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.

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.

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).

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.

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.

Shell

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

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. 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.

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

Banner

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. 

[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.

Author

Cockpit has been written by many contributors.

See also

cockpit-ws(8), cockpit-tls(8)

cockpit-ws(8)

Name

cockpit-ws - Cockpit web service

Synopsis

cockpit-ws [--help] [--port PORT] [--address ADDRESS] [--no-tls] [--for-tls-proxy] [--local-ssh] [--local-session BRIDGE]

Description

The cockpit-ws program is the web service component used for communication between the browser application and various configuration tools and services like cockpit-bridge(1).

Users or administrators should never need to start this program as it automatically started by systemd(1) on bootup, through cockpit-tls(8).

Transport security

cockpit-ws is normally run behind the cockpit-tls TLS terminating proxy, and only deals with unencrypted HTTP by itself. But for backwards compatibility it can also handle TLS connections by itself when being run directly. For details how to configure certificates, please refer to the cockpit-tls(8) documentation.

Timeout

When started via systemd(1) then cockpit-ws will exit after 90 seconds if nobody logs in, or after the last user is disconnected.

Options

--help

Show help options.

--port PORT

Serve HTTP requests PORT instead of port 9090. Usually Cockpit is started on demand by systemd socket activation, and this option has no effect. Update the ListenStream directive cockpit.socket file in the usual systemd manner.

--address ADDRESS

Bind to address ADDRESS instead of binding to all available addresses. Usually Cockpit is started on demand by systemd socket activation, and this option has no effect. In that case, update the ListenStream directive in the cockpit.socket file in the usual systemd manner.

--no-tls

Disable http to https redirection.

--for-tls-proxy

Tell cockpit-ws that it is running behind a local reverse proxy that does the TLS termination. Then Cockpit puts https:// URLs into the default Content-Security-Policy, and accepts only https:// origins, instead of http: ones by default. However, if Origins is set in the cockpit.conf(5) configuration file, it will override this default.

--local-ssh

Normally cockpit-ws uses cockpit-session and PAM to authenticate the user and start a user session. With this option enabled, it will instead authenticate via SSH at 127.0.0.1 port 22.

--local-session BRIDGE

Skip all authentication and cockpit-session, and launch the cockpit-bridge specified in BRIDGE in the local session. If the BRIDGE is specified as - then expect an already running bridge that is connected to stdin and stdout of this cockpit-ws process. This allows the web server to run as any unprivileged user in an already running session.

This mode implies --no-tls, thus you need to use http:// URLs with this.

Warning

With --local-session BRIDGE, you have to isolate the opened TCP port somehow (for example in a network namespace), otherwise all other users (or even remote machines if the port is not just listening on localhost) can access the session!

Environment

The cockpit-ws process will use the XDG_CONFIG_DIRS environment variable from the XDG basedir spec to find its cockpit.conf(5) configuration file.

In addition the XDG_DATA_DIRS environment variable from the XDG basedir spec can be used to override the location to serve static files from. These are the files that are served to a non-logged in user.

Bugs

Please send bug reports to either the distribution bug tracker or the upstream bug tracker.

Author

Cockpit has been written by many contributors.

See also

cockpit-tls(8) , cockpit.conf(5) , systemd(1)

cockpit-tls(8)

Name

cockpit-tls - TLS proxy for Cockpit web service

Synopsis

cockpit-tls [--help] [--port PORT] [--no-tls] [--idle-timeout SECONDS]

Description

The cockpit-tls program is a TLS terminating HTTP proxy for cockpit-ws(8). It manages a set of isolated cockpit-ws instances, one per TLS client certificate, plus one for TLS without a client certificate, and one for unencrypted HTTP. With that, one session cannot tamper with another one through possible security vulnerability exploits.

Users or administrators should never need to start this program as it automatically started by systemd(1) via socket activation.

Transport security

To specify the TLS certificate the web service should use, simply drop a file with the extension .cert in the /etc/cockpit/ws-certs.d directory, or below $XDG_CONFIG_DIRS if set (see cockpit.conf). If there are multiple files in this directory, then the highest priority one is chosen after sorting.

The .cert file should contain at least two OpenSSL style PEM blocks. First one or more BEGIN CERTIFICATE blocks for the server certificate and intermediate certificate authorities and a second one containing a BEGIN PRIVATE KEY or similar. The key must not be encrypted.

If there is no TLS certificate, a self-signed certificate is automatically generated using sscg (if available) or openssl and stored in the 0-self-signed.cert file.

When enrolling into a FreeIPA domain, an SSL certificate is requested from the IPA server and stored in 10-ipa.cert.

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

$ sudo /usr/libexec/cockpit-certificate-ensure --check

Or, on Debian-based systems:

$ sudo /usr/lib/cockpit/cockpit-certificate-ensure --check

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

CERT_FILE=/etc/cockpit/ws-certs.d/50-certmonger.crt
KEY_FILE=/etc/cockpit/ws-certs.d/50-certmonger.key

getcert request -f ${CERT_FILE} -k ${KEY_FILE} -D $(hostname --fqdn)

Options

--help

Show help options.

--port PORT

Serve HTTP requests on PORT instead of port 9090. Usually Cockpit is started on demand by systemd socket activation, and this option has no effect. Update the ListenStream directive cockpit.socket file in the usual systemd manner.

--no-tls

Don’t use TLS. Certificates will not be read, and https connections denied. Then cockpit-tls will only manage a single cockpit-ws instance, and thus not do anything different than running cockpit-ws --no-tls directly. Only use this for debugging or testing.

--idle-timeout SECONDS

If greater than 0, exit if no connections have happened for the given number of seconds, i. e. the server is idle. If not given, the default is 90.

Environment

The cockpit-tls program expects the RUNTIME_DIRECTORY environment variable to be set to an empty directory (preferably in /run/) that is only accessible by the system user under which it is running. This contains the Unix sockets for communicating with the cockpit-ws instances, and in the future, state information about client certificates. This variable is normally set by the cockpit.service systemd unit.

In addition, cockpit-tls will use the XDG_CONFIG_DIRS environment variable from the XDG basedir spec to find its certificates and the cockpit.conf(5) configuration file.

Bugs

Please send bug reports to either the distribution bug tracker or the upstream bug tracker.

Author

Cockpit has been written by many contributors.

See also

cockpit-ws(8) , cockpit.conf(5) , systemd(1)

cockpit-desktop(1)

Name

cockpit-desktop - Cockpit Desktop integration

Synopsis

cockpit-desktop URLPATH [SSH_HOST]

Description

The cockpit-desktop program provides secure access to Cockpit pages in an already running desktop session. It starts a web server (cockpit-ws) and a web browser in an isolated network namespace, and a cockpit-bridge(8) in the running user session.

This avoids having to log into Cockpit, and having to enable cockpit.socket system-wide. The network isolation ensures that no other user, and not even other processes in the user’s session, can access this local web server.

URLPATH is the Cockpit page to open, i. e. the path component of Cockpit URLs. It is highly recommended to only open a particular page frame, not the entire Cockpit navigation and menu. For example, the path /cockpit/@localhost/storage/index.html will open the Storage page. It is also possible to give abbreviated forms of urls, such as “/storage” or “/network/firewall”.

SSH_HOST is an optional SSH remote host specification (hostname or username@hostname). If given, cockpit-bridge will be started on the remote host through ssh(1) instead, i. e. the Cockpit web browser will show that remote host. Note that this is more of an experimental/demo feature.

Environment

The BROWSER environment variable specifies the browser command (and possibly options) that will be used to open the requested Cockpit page. If not set, cockpit-desktop attempts to use an internal minimalistic WebKit browser, and failing that, will attempt to detect some reasonable alternatives.

Bugs

Please send bug reports to either the distribution bug tracker or the upstream bug tracker.

Author

Cockpit has been written by many contributors.

See also

cockpit-ws(8), cockpit-bridge(1)

cockpit-bridge(1)

Name

cockpit-bridge - Cockpit Host Bridge

Synopsis

cockpit-bridge [--help] [--packages]

Description

The cockpit-bridge program is used by Cockpit to relay messages and commands from the Web front end to the server. Among other things it relays DBus, and spawns processes on behalf of the Web user interface.

This program is not routinely run by users or administrators. It is in the $PATH so that Cockpit can find it when connecting between hosts. However there are some diagnostics available when running from the command line.

Options

--help

Show help options.

--interact=boundary

Interact with the raw cockpit1 protocol. Useful for debugging and testing. Specify a boundary which should be on an empty line between messages.

--packages

List all available Cockpit packages and exit. Note this includes packages available to the user running this command.

--version

Show Cockpit version information.

Bugs

Please send bug reports to either the distribution bug tracker or the upstream bug tracker.

Author

Cockpit has been written by many contributors.

See also

cockpit-ws(8)

pam_ssh_add(8)

Name

pam_ssh_add - PAM module to auto load ssh keys into an agent

Description

pam_ssh_add provides authentication and session modules that allow users to start their session with a running ssh-agent with as many ssh keys loaded as possible.

If used, the authentication module simply stores the authentication token for later use by the session module. Because this module performs no actual authentication it returns PAM_CRED_INSUFFICIENT on success and should always be accompanied by an actual authentication module in your pam configuration.

By default the session module will start a new ssh-agent and run ssh-add, loading any keys that exist in the default path for the newly logged in user. If any keys prompt for a password, and a authentication token was successfully stored, that token will be provided as the password.

Options

debug

This option will turn on debug logging to syslog.

Examples

        auth     required  pam_unix.so
        auth     optional  pam_ssh_add.so
        session  optional  pam_ssh_add.so

Bugs

Please send bug reports to either the distribution bug tracker or the upstream bug tracker.

Author

Cockpit has been written by many contributors.