'\" t
.\"     Title: cockpit-ws
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 02/20/2019
.\"    Manual: cockpit-ws
.\"    Source: cockpit
.\"  Language: English
.\"
.TH "COCKPIT\-WS" "8" "02/20/2019" "cockpit" "cockpit-ws"
.\" -----------------------------------------------------------------
.\" * 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-ws \- Cockpit web service
.SH "SYNOPSIS"
.HP \w'\fBcockpit\-ws\fR\ 'u
\fBcockpit\-ws\fR [\fB\-\-help\fR] [\fB\-\-port\fR\ \fIPORT\fR] [\fB\-\-address\fR\ \fIADDRESS\fR] [\fB\-\-no\-tls\fR] [\fB\-\-local\-ssh\fR] [\fB\-\-local\-session\fR\ \fIBRIDGE\fR]
.SH "DESCRIPTION"
.PP
The
\fBcockpit\-ws\fR
program is the web service component used for communication between the browser application and various configuration tools and services like
\fBcockpit-bridge\fR(8)\&.
.PP
Users or administrators should never need to start this program as it automatically started by
\fBsystemd\fR(1)
on bootup\&.
.SH "TRANSPORT SECURITY"
.PP
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\&.
.PP
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\&.
.PP
If there is no TLS certificate, a self\-signed certificate is automatically generated using
\fBopenssl\fR
and stored in the
0\-self\-signed\&.cert
file\&.
.PP
When enrolling into a FreeIPA domain, an SSL certificate is requested from the IPA server and stored in
10\-ipa\&.cert\&.
.PP
To check which certificate
\fBcockpit\-ws\fR
will use, run the following command\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ sudo remotectl certificate
.fi
.if n \{\
.RE
.\}
.PP
If using
certmonger
to manage certificates, following command can be used to automatically prepare concatenated
\&.cert
file:
.sp
.if n \{\
.RS 4
.\}
.nf
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}"
.fi
.if n \{\
.RE
.\}
.SH "TIMEOUT"
.PP
When started via
\fBsystemd\fR(1)
then
\fBcockpit\-ws\fR
will exit after 90 seconds if nobody logs in, or after the last user is disconnected\&.
.SH "OPTIONS"
.PP
\fB\-\-help\fR
.RS 4
Show help options\&.
.RE
.PP
\fB\-\-port\fR \fIPORT\fR
.RS 4
Serve HTTP requests
\fIPORT\fR
instead of port 9090\&. Usually Cockpit is started on demand by
\fBsystemd\fR
socket activation, and this option has no effect\&. Update the
ListenStream
directive
cockpit\&.socket
file in the usual
\fBsystemd\fR
manner\&.
.RE
.PP
\fB\-\-address\fR \fIADDRESS\fR
.RS 4
Bind to address
\fIADDRESS\fR
instead of binding to all available addresses\&. Usually Cockpit is started on demand by
\fBsystemd\fR
socket activation, and this option has no effect\&. In that case, update the
ListenStream
directive in the
cockpit\&.socket
file in the usual
\fBsystemd\fR
manner\&.
.RE
.PP
\fB\-\-no\-tls\fR
.RS 4
Don\*(Aqt use TLS\&.
.RE
.PP
\fB\-\-local\-ssh\fR
.RS 4
Normally
\fBcockpit\-ws\fR
uses
\fBcockpit\-session\fR
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\&.
.RE
.PP
\fB\-\-local\-session\fR \fIBRIDGE\fR
.RS 4
Skip all authentication and
\fBcockpit\-session\fR, and launch the
\fBcockpit\-bridge\fR
specified in
\fIBRIDGE\fR
in the local session\&. If the
\fIBRIDGE\fR
is specified as
\fB\-\fR
then expect an already running bridge that is connected to stdin and stdout of this
\fBcockpit\-ws\fR
process\&. This allows the web server to run as any unprivileged user in an already running session\&.
.sp
This mode implies
\-\-no\-tls, thus you need to use http:// URLs with this\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBWarning\fR
.ps -1
.br
If you use this, you
\fIhave to isolate the opened TCP port\fR
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!
.sp .5v
.RE
.RE
.SH "ENVIRONMENT"
.PP
The
\fBcockpit\-ws\fR
process will use the
XDG_CONFIG_DIRS
environment variable from the
\m[blue]\fBXDG basedir spec\fR\m[]\&\s-2\u[1]\d\s+2
to find its
\fBcockpit.conf\fR(5)
configuration file\&.
.PP
In addition the
XDG_DATA_DIRS
environment variable from the
\m[blue]\fBXDG basedir spec\fR\m[]\&\s-2\u[1]\d\s+2
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\&.
.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[2]\d\s+2\&.
.SH "AUTHOR"
.PP
Cockpit has been written by many
\m[blue]\fBcontributors\fR\m[]\&\s-2\u[3]\d\s+2\&.
.SH "SEE ALSO"
.PP
\fBcockpit.conf\fR(5)
,
\fBsystemd\fR(1)
.SH "NOTES"
.IP " 1." 4
XDG basedir spec
.RS 4
\%https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
.RE
.IP " 2." 4
upstream bug tracker
.RS 4
\%https://github.com/cockpit-project/cockpit/issues/new
.RE
.IP " 3." 4
contributors
.RS 4
\%https://github.com/cockpit-project/cockpit/
.RE