mirror of
https://github.com/cockpit-project/cockpit.git
synced 2026-11-03 21:49:50 -09:00
acf9af315c
Adds a new extension for AsciiDoctor in `doc/extensions/man-inline-macro.rb` followed by a README in the same directory. This changes the links to manpages during compilation from asciidoc files into HTML or Manpages so that links work within HTML pages as well as being properly formatted within manpages. This started as an initial workaround to handle Antora xref extension to AsciiDoctor wherein it introduces resource ids such as module, version, and component. Ultimately this breaks AsciiDoctor parsing of xref and makes it think that it is a strange URI and not a URL. However as Cockpit guide only has links to manpages and the fact that this also improves system manpages a macro `man` suits better. Using this is fairly straightforward, when you want to reference a manpage within the Cockpit Guide or within a manpage you define it using `man:manpage-name[sub-volume]` which will then be translated to an anchor link in HTML or bold text in Manpage format with the text `manpage-name(sub-volume)`. This does not fix the links within Antora and building them locally within Cockpit repo using our instructions in doc/README.md will make the links show as unformatted text `man:manpage-name[sub-volume]`. This is not an issue within our cockpit-docs repo as we have an extension there that replaces the manpage macros with the proper xref module link for Antora. See-also: https://docs.antora.org/antora/latest/page/xref/#structure See-also: https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/main/lib/man-inline-macro/extension.rb Related-to: https://github.com/cockpit-project/cockpit-docs/pull/8 Signed-off-by: Freya Gustavsson <freya@venefilyn.se>
104 lines
3.7 KiB
Text
104 lines
3.7 KiB
Text
= cockpit-ws(8)
|
|
|
|
== Name
|
|
|
|
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 man:cockpit-bridge[1].
|
|
|
|
Users or administrators should never need to start this program as it
|
|
automatically started by man:systemd[1] on bootup, through
|
|
man:cockpit-tls[8].
|
|
|
|
== Transport security
|
|
|
|
*cockpit-ws* is normally run behind the *cockpit-tls* 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 man:cockpit-tls[8] documentation.
|
|
|
|
== Timeout
|
|
|
|
When started via man: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*::
|
|
Disable http to https redirection.
|
|
*--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 man:cockpit.conf[5] configuration file, it will override
|
|
this default.
|
|
*--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]
|
|
====
|
|
With *--local-session* _BRIDGE_, 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
|
|
https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html[XDG
|
|
basedir spec] to find its man:cockpit.conf[5] configuration file.
|
|
|
|
In addition the *XDG_DATA_DIRS* environment variable from the
|
|
https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html[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
|
|
|
|
include::../partials/bugs.adoc[]
|
|
|
|
== Author
|
|
|
|
include::../partials/author.adoc[]
|
|
|
|
== See also
|
|
|
|
man:cockpit-tls[8] , man:cockpit.conf[5] , man:systemd[1]
|