## cockpit-ws 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(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.

## SEE ALSO

cockpit.conf(5) , systemd(1)