cockpit-ws(8)

1COCKPIT-WS(8)                     cockpit-ws                     COCKPIT-WS(8)
2
3
4

NAME

6       cockpit-ws - Cockpit web service
7

SYNOPSIS

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

DESCRIPTION

13       The cockpit-ws program is the web service component used for
14       communication between the browser application and various configuration
15       tools and services like cockpit-bridge(8).
16
17       Users or administrators should never need to start this program as it
18       automatically started by systemd(1) on bootup.
19

TRANSPORT SECURITY

21       To specify the TLS certificate the web service should use, simply drop
22       a file with the extension .cert in the /etc/cockpit/ws-certs.d
23       directory. If there are multiple files in this directory, then the
24       highest priority one is chosen after sorting.
25
26       The .cert file should contain at least two OpenSSL style PEM blocks.
27       First one or more BEGIN CERTIFICATE blocks for the server certificate
28       and intermediate certificate authorities and a last one containing a
29       BEGIN PRIVATE KEY or similar. The key may not be encrypted.
30
31       If there is no TLS certificate, a self-signed certificate is
32       automatically generated using openssl and stored in the
33       0-self-signed.cert file.
34
35       When enrolling into a FreeIPA domain, an SSL certificate is requested
36       from the IPA server and stored in 10-ipa.cert.
37
38       To check which certificate cockpit-ws will use, run the following
39       command.
40
41           $ sudo remotectl certificate
42
43       If using certmonger to manage certificates, following command can be
44       used to automatically prepare concatenated .cert file:
45
46           CERT_FILE=/etc/pki/tls/certs/$(hostname).pem
47           KEY_FILE=/etc/pki/tls/private/$(hostname).key
48
49           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}"
50

TIMEOUT

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

OPTIONS

56       --help
57           Show help options.
58
59       --port PORT
60           Serve HTTP requests PORT instead of port 9090. Usually Cockpit is
61           started on demand by systemd socket activation, and this option has
62           no effect. Update the ListenStream directive cockpit.socket file in
63           the usual systemd manner.
64
65       --address ADDRESS
66           Bind to address ADDRESS instead of binding to all available
67           addresses. Usually Cockpit is started on demand by systemd socket
68           activation, and this option has no effect. In that case, update the
69           ListenStream directive in the cockpit.socket file in the usual
70           systemd manner.
71
72       --no-tls
73           Don't use TLS.
74
75       --for-tls-proxy
76           Tell cockpit-ws that it is running behind a local reverse proxy
77           that does the TLS termination. Then Cockpit puts https:// URLs into
78           the default Content-Security-Policy, and accepts only https://
79           origins, instead of http: ones by default. However, if Origins is
80           set in the cockpit.conf(5) configuration file, it will override
81           this default.
82
83           This option implies --no-tls.
84
85       --local-ssh
86           Normally cockpit-ws uses cockpit-session and PAM to authenticate
87           the user and start a user session. With this option enabled, it
88           will instead authenticate via SSH at 127.0.0.1 port 22.
89
90       --local-session BRIDGE
91           Skip all authentication and cockpit-session, and launch the
92           cockpit-bridge specified in BRIDGE in the local session. If the
93           BRIDGE is specified as - then expect an already running bridge that
94           is connected to stdin and stdout of this cockpit-ws process. This
95           allows the web server to run as any unprivileged user in an already
96           running session.
97
98           This mode implies --no-tls, thus you need to use http:// URLs with
99           this.
100
101               Warning
102               If you use this, you have to isolate the opened TCP port
103               somehow (for example in a network namespace), otherwise all
104               other users (or even remote machines if the port is not just
105               listening on localhost) can access the session!
106

ENVIRONMENT

108       The cockpit-ws process will use the XDG_CONFIG_DIRS environment
109       variable from the XDG basedir spec[1] to find its cockpit.conf(5)
110       configuration file.
111
112       In addition the XDG_DATA_DIRS environment variable from the XDG basedir
113       spec[1] can be used to override the location to serve static files
114       from. These are the files that are served to a non-logged in user.
115

BUGS

117       Please send bug reports to either the distribution bug tracker or the
118       upstream bug tracker[2].
119

AUTHOR

121       Cockpit has been written by many contributors[3].
122

NOTES

127        1. XDG basedir spec
128           https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
129
130        2. upstream bug tracker
131           https://github.com/cockpit-project/cockpit/issues/new
132
133        3. contributors
134           https://github.com/cockpit-project/cockpit/
135
136
137
138cockpit                           06/12/2019                     COCKPIT-WS(8)