254 lines
9.7 KiB
XML
254 lines
9.7 KiB
XML
<refentry id="cockpit-ws.8">
|
|
|
|
<!--
|
|
This file is part of Cockpit.
|
|
|
|
Copyright (C) 2013 Red Hat, Inc.
|
|
|
|
Cockpit is free software; you can redistribute it and/or modify it
|
|
under the terms of the GNU Lesser General Public License as published by
|
|
the Free Software Foundation; either version 2.1 of the License, or
|
|
(at your option) any later version.
|
|
|
|
Cockpit is distributed in the hope that it will be useful, but
|
|
WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
Lesser General Public License for more details.
|
|
|
|
You should have received a copy of the GNU Lesser General Public License
|
|
along with Cockpit; If not, see <http://www.gnu.org/licenses/>.
|
|
-->
|
|
|
|
<refentryinfo>
|
|
<title>cockpit-ws</title>
|
|
<productname>cockpit</productname>
|
|
</refentryinfo>
|
|
|
|
<refmeta>
|
|
<refentrytitle>cockpit-ws</refentrytitle>
|
|
<manvolnum>8</manvolnum>
|
|
<refmiscinfo class="version"></refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>cockpit-ws</refname>
|
|
<refpurpose>Cockpit web service</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>cockpit-ws</command>
|
|
<arg><option>--help</option></arg>
|
|
<arg><option>--port</option> <replaceable>PORT</replaceable></arg>
|
|
<arg><option>--address</option> <replaceable>ADDRESS</replaceable></arg>
|
|
<arg><option>--no-tls</option></arg>
|
|
<arg><option>--for-tls-proxy</option></arg>
|
|
<arg><option>--local-ssh</option></arg>
|
|
<arg><option>--local-session</option> <replaceable>BRIDGE</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
|
|
<refsect1 id="cockpit-ws-description">
|
|
<title>DESCRIPTION</title>
|
|
<para>
|
|
The <command>cockpit-ws</command> program is the web service
|
|
component used for communication between the browser application
|
|
and various configuration tools and services like
|
|
<citerefentry>
|
|
<refentrytitle>cockpit-bridge</refentrytitle><manvolnum>1</manvolnum>
|
|
</citerefentry>.
|
|
</para>
|
|
<para>
|
|
Users or administrators should never need to start this program
|
|
as it automatically started by
|
|
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
|
on bootup, through
|
|
<citerefentry><refentrytitle>cockpit-tls</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 id="cockpit-ws-transport">
|
|
<title>TRANSPORT SECURITY</title>
|
|
<para>
|
|
<command>cockpit-ws</command> is normally run behind the <command>cockpit-tls</command>
|
|
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
|
|
<citerefentry><refentrytitle>cockpit-tls</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
|
documentation.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 id="cockpit-ws-timeout">
|
|
<title>TIMEOUT</title>
|
|
<para>
|
|
When started via
|
|
<citerefentry>
|
|
<refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum>
|
|
</citerefentry>
|
|
then <command>cockpit-ws</command> will exit after 90 seconds
|
|
if nobody logs in, or after the last user is disconnected.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 id="cockpit-ws-options">
|
|
<title>OPTIONS</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>--help</option></term>
|
|
<listitem>
|
|
<para>
|
|
Show help options.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>--port</option> <replaceable>PORT</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Serve HTTP requests <replaceable>PORT</replaceable> instead of port 9090.
|
|
Usually Cockpit is started on demand by <command>systemd</command> socket
|
|
activation, and this option has no effect. Update the
|
|
<literal>ListenStream</literal> directive <filename>cockpit.socket</filename>
|
|
file in the usual <command>systemd</command> manner.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>--address</option> <replaceable>ADDRESS</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Bind to address <replaceable>ADDRESS</replaceable> instead of binding to
|
|
all available addresses. Usually Cockpit is started on demand by
|
|
<command>systemd</command> socket activation, and this option has no effect.
|
|
In that case, update the <literal>ListenStream</literal> directive in the
|
|
<filename>cockpit.socket</filename> file in the usual <command>systemd</command> manner.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>--no-tls</option></term>
|
|
<listitem>
|
|
<para>
|
|
Don't use TLS.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>--for-tls-proxy</option></term>
|
|
<listitem>
|
|
<para>
|
|
Tell <command>cockpit-ws</command> that it is running behind a local reverse proxy that
|
|
does the TLS termination. Then Cockpit puts https:// URLs into the default
|
|
<literal>Content-Security-Policy</literal>, and accepts only https:// origins, instead of
|
|
http: ones by default. However, if <literal>Origins</literal> is set in the
|
|
<citerefentry>
|
|
<refentrytitle>cockpit.conf</refentrytitle><manvolnum>5</manvolnum>
|
|
</citerefentry>
|
|
configuration file, it will override this default.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>--proxy-tls-redirect</option></term>
|
|
<listitem>
|
|
<para>
|
|
Enable redirection of unencrypted http requests to https (TLS) in <option>--no-tls</option> mode.
|
|
Use this when running <command>cockpit-ws</command> behind a reverse http proxy that also
|
|
supports https, but does no redirection from http to https by itself.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>--local-ssh</option></term>
|
|
<listitem>
|
|
<para>
|
|
Normally <command>cockpit-ws</command> uses
|
|
<command>cockpit-session</command> and PAM to authenticate the user and start a
|
|
user session. With this option enabled, it will instead authenticate via SSH at
|
|
<literal>127.0.0.1</literal> port <literal>22</literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>--local-session</option> <replaceable>BRIDGE</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Skip all authentication and <command>cockpit-session</command>, and launch the
|
|
<command>cockpit-bridge</command> specified in <replaceable>BRIDGE</replaceable> in
|
|
the local session. If the <replaceable>BRIDGE</replaceable> is specified as
|
|
<command>-</command> then expect an already running bridge that is connected to
|
|
stdin and stdout of this <command>cockpit-ws</command> process. This allows the
|
|
web server to run as any unprivileged user in an already running session.
|
|
</para>
|
|
<para>
|
|
This mode implies <literal>--no-tls</literal>, thus you need to use http://
|
|
URLs with this.
|
|
</para>
|
|
<warning>
|
|
<para>
|
|
If you use this, you <emphasis>have to isolate the opened TCP port</emphasis>
|
|
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!
|
|
</para>
|
|
</warning>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1 id="cockpit-ws-environment">
|
|
<title>ENVIRONMENT</title>
|
|
<para>
|
|
The <command>cockpit-ws</command> process will use the <literal>XDG_CONFIG_DIRS</literal>
|
|
environment variable from the
|
|
<ulink url="https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG
|
|
basedir spec</ulink> to find its
|
|
<citerefentry>
|
|
<refentrytitle>cockpit.conf</refentrytitle><manvolnum>5</manvolnum>
|
|
</citerefentry>
|
|
configuration file.
|
|
</para>
|
|
<para>
|
|
In addition the <literal>XDG_DATA_DIRS</literal> environment variable from the
|
|
<ulink url="https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG
|
|
basedir spec</ulink>
|
|
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.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 id="cockpit-ws-bugs">
|
|
<title>BUGS</title>
|
|
<para>
|
|
Please send bug reports to either the distribution bug tracker or the
|
|
<ulink url="https://github.com/cockpit-project/cockpit/issues/new">upstream bug tracker</ulink>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 id="cockpit-ws-author">
|
|
<title>AUTHOR</title>
|
|
<para>Cockpit has been written by many
|
|
<ulink url="https://github.com/cockpit-project/cockpit/">contributors</ulink>.</para>
|
|
</refsect1>
|
|
|
|
<refsect1 id="cockpit-ws-also">
|
|
<title>SEE ALSO</title>
|
|
<para>
|
|
<citerefentry>
|
|
<refentrytitle>cockpit-tls</refentrytitle><manvolnum>8</manvolnum>
|
|
</citerefentry>
|
|
,
|
|
<citerefentry>
|
|
<refentrytitle>cockpit.conf</refentrytitle><manvolnum>5</manvolnum>
|
|
</citerefentry>
|
|
,
|
|
<citerefentry>
|
|
<refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum>
|
|
</citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|