cockpit-ws

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

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

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. 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 last one containing a BEGIN PRIVATE KEY or similar. The key may not be encrypted.

If there is no TLS certificate, a self-signed certificate is automatically generated using 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 remotectl certificate

If using certmonger to manage certificates, following command can be used to automatically prepare concatenated .cert file:

CERT_FILE=/etc/pki/tls/certs/$(hostname).pem
KEY_FILE=/etc/pki/tls/private/$(hostname).key

getcert request -f ${CERT_FILE} -k ${KEY_FILE} -D $(hostname --fqdn) -C "sed -n w/etc/cockpit/ws-certs.d/50-from-certmonger.cert ${CERT_FILE} ${KEY_FILE}"

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`	Don't use TLS.
`--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. This option implies `--no-tls`.
`--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 If you use this, 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.