Add asciidoc guide

doc/guide/asciidoc/Makefile

@@ -0,0 +1,12 @@
+all: render_html render_man
+
+render_html:
+	mkdir -p output/html
+	asciidoctor -b html5 -D output/html cockpit-guide.adoc
+
+render_man:
+	mkdir -p output/html
+	asciidoctor -b manpage -D output/man ./man/*.adoc
+
+clean:
+	rm -rf output/

doc/guide/asciidoc/cockpit-guide.adoc

@@ -1,4 +1,5 @@
 :toc: left
+:toclevels: 3
 
 [[guide]]
 == Deployment Guide
@@ -11,47 +12,79 @@ Latest version available at https://cockpit-project.org/guide/latest/
 [[cockpit-manual]]
 === Manual pages
 
-//      include::../man/cockpit.conf.adoc[leveloffset=1]
-//      include::../man/cockpit-ws.adoc[leveloffset=1]
-//      include::../man/cockpit-tls.adoc[leveloffset=1]
-//      include::../man/cockpit-desktop.adoc[leveloffset=1]
-//      include::../man/cockpit-bridge.adoc[leveloffset=1]
+include::man/cockpit.adoc[leveloffset=+3]
 
-include::https.adoc[leveloffset=1]
-include::listen.adoc[leveloffset=1]
-include::startup.adoc[leveloffset=1]
-include::multi-host.adoc[leveloffset=1]
-include::authentication.adoc[leveloffset=1]
-include::sso.adoc[leveloffset=1]
-include::cert-authentication.adoc[leveloffset=1]
-include::privileges.adoc[leveloffset=1]
+include::man/cockpit.conf.adoc[leveloffset=+3]
+
+// include::man/cockpit-ws.adoc[leveloffset=+3]
+
+// include::man/cockpit-tls.adoc[leveloffset=+3]
+
+include::man/cockpit-desktop.adoc[leveloffset=+3]
+
+// include::man/cockpit-bridge.adoc[leveloffset=+3]
+
+
+include::https.adoc[leveloffset=+1]
+
+include::listen.adoc[leveloffset=+1]
+
+include::startup.adoc[leveloffset=+1]
+
+include::multi-host.adoc[leveloffset=+1]
+
+include::authentication.adoc[leveloffset=+1]
+
+include::sso.adoc[leveloffset=+1]
+
+include::cert-authentication.adoc[leveloffset=+1]
+
+include::privileges.adoc[leveloffset=+1]
 
 
 [[features]]
 == Feature Internals
 
-include::feature-systemd.adoc[leveloffset=1]
-include::feature-journal.adoc[leveloffset=1]
-include::feature-networkmanager.adoc[leveloffset=1]
-include::feature-firewall.adoc[leveloffset=1]
-include::feature-storaged.adoc[leveloffset=1]
-include::feature-users.adoc[leveloffset=1]
-include::feature-realmd.adoc[leveloffset=1]
-include::feature-terminal.adoc[leveloffset=1]
-include::feature-pcp.adoc[leveloffset=1]
-include::feature-machines.adoc[leveloffset=1]
-include::feature-selinux.adoc[leveloffset=1]
-include::feature-tuned.adoc[leveloffset=1]
-include::feature-sosreport.adoc[leveloffset=1]
-include::feature-packagekit.adoc[leveloffset=1]
+include::feature-systemd.adoc[leveloffset=+1]
+
+include::feature-journal.adoc[leveloffset=+1]
+
+include::feature-networkmanager.adoc[leveloffset=+1]
+
+include::feature-firewall.adoc[leveloffset=+1]
+
+include::feature-storaged.adoc[leveloffset=+1]
+
+include::feature-users.adoc[leveloffset=+1]
+
+include::feature-realmd.adoc[leveloffset=+1]
+
+include::feature-terminal.adoc[leveloffset=+1]
+
+include::feature-pcp.adoc[leveloffset=+1]
+
+include::feature-machines.adoc[leveloffset=+1]
+
+include::feature-selinux.adoc[leveloffset=+1]
+
+include::feature-tuned.adoc[leveloffset=+1]
+
+include::feature-sosreport.adoc[leveloffset=+1]
+
+include::feature-packagekit.adoc[leveloffset=+1]
 
 
 [[development]]
 == Developer Guide
 
-include::embedding.adoc[leveloffset=1]
-include::packages.adoc[leveloffset=1]
-include::urls.adoc[leveloffset=1]
-include::api-base1.adoc[leveloffset=1]
-include::api-shell.adoc[leveloffset=1]
-include::api-system.adoc[leveloffset=1]
+include::embedding.adoc[leveloffset=+1]
+
+include::packages.adoc[leveloffset=+1]
+
+include::urls.adoc[leveloffset=+1]
+
+include::api-base1.adoc[leveloffset=+1]
+
+include::api-shell.adoc[leveloffset=+1]
+
+include::api-system.adoc[leveloffset=+1]

doc/guide/asciidoc/man/cockpit-bridge.adoc

@@ -0,0 +1,60 @@
+cockpit
+
+cockpit-bridge
+
+1
+
+cockpit-bridge
+
+Cockpit Host Bridge
+
+cockpit-bridge
+
+--help
+
+--packages
+
+[[cockpit-bridge-description]]
+== DESCRIPTION
+
+The `cockpit-bridge` program is used by Cockpit to relay messages and
+commands from the Web front end to the server. Among other things it
+relays DBus, and spawns processes on behalf of the Web user interface.
+
+This program is not routinely run by users or administrators. It is in
+the `$PATH` so that Cockpit can find it when connecting between hosts.
+However there are some diagnostics available when running from the
+command line.
+
+[[cockpit-bridge-options]]
+== OPTIONS
+
+`--help`::
+  Show help options.
+`--interact=boundary`::
+  Interact with the raw cockpit1 protocol. Useful for debugging and
+  testing. Specify a `boundary` which should be on an empty line between
+  messages.
+`--packages`::
+  List all available Cockpit packages and exit. Note this includes
+  packages available to the user running this command.
+`--version`::
+  Show Cockpit version information.
+
+[[cockpit-bridge-bugs]]
+== BUGS
+
+Please send bug reports to either the distribution bug tracker or the
+https://github.com/cockpit-project/cockpit/issues/new[upstream bug
+tracker].
+
+[[cockpit-bridge-author]]
+== AUTHOR
+
+Cockpit has been written by many
+https://github.com/cockpit-project/cockpit/[contributors].
+
+[[cockpit-bridge-also]]
+== SEE ALSO
+
+`cockpit-ws(8)`

doc/guide/asciidoc/man/cockpit-desktop.adoc

@@ -0,0 +1,64 @@
+= cockpit-desktop(1)
+:doctype: manpage
+
+== NAME
+
+cockpit-desktop - Cockpit Desktop integration
+
+== SYNOPSIS
+
+*cockpit-desktop* {URLPATH} [SSH_HOST]
+
+[[cockpit-desktop-description]]
+== DESCRIPTION
+
+The `cockpit-desktop` program provides secure access to Cockpit pages in
+an already running desktop session. It starts a web server
+(`cockpit-ws`) and a web browser in an isolated network namespace, and a
+`cockpit-bridge(8)` in the running user session.
+
+This avoids having to log into Cockpit, and having to enable
+`cockpit.socket` system-wide. The network isolation ensures that no
+other user, and not even other processes in the user's session, can
+access this local web server.
+
+`URLPATH` is the Cockpit page to open, i. e. the path component of
+Cockpit URLs. It is highly recommended to only open a
+https://cockpit-project.org/guide/latest/embedding.html[particular page
+frame], not the entire Cockpit navigation and menu. For example, the
+path `/cockpit/@localhost/storage/index.html` will open the Storage
+page. It is also possible to give abbreviated forms of urls, such as
+"`storage`" or "`network/firewall`".
+
+`SSH_HOST` is an optional SSH remote host specification (`hostname` or
+`username@hostname`). If given, `cockpit-bridge` will be started on the
+remote host through `ssh(1)` instead, i. e. the Cockpit web browser will
+show that remote host. Note that this is more of an experimental/demo
+feature.
+
+[[cockpit-desktop-environment]]
+== ENVIRONMENT
+
+The `BROWSER` environment variable specifies the browser command (and
+possibly options) that will be used to open the requested Cockpit page.
+If not set, `cockpit-desktop` attempts to use an internal minimalistic
+WebKit browser, and failing that, will attempt to detect some reasonable
+alternatives.
+
+[[cockpit-desktop-bugs]]
+== BUGS
+
+Please send bug reports to either the distribution bug tracker or the
+https://github.com/cockpit-project/cockpit/issues/new[upstream bug
+tracker].
+
+[[cockpit-desktop-author]]
+== AUTHOR
+
+Cockpit has been written by many
+https://github.com/cockpit-project/cockpit/[contributors].
+
+[[cockpit-desktop-also]]
+== SEE ALSO
+
+`cockpit-ws(8)`, `cockpit-bridge(1)`

doc/guide/asciidoc/man/cockpit-tls.adoc

@@ -0,0 +1,137 @@
+cockpit
+
+cockpit-tls
+
+8
+
+cockpit-tls
+
+TLS proxy for Cockpit web service
+
+cockpit-tls
+
+--help
+
+--port
+
+PORT
+
+--no-tls
+
+--idle-timeout
+
+SECONDS
+
+[[cockpit-tls-description]]
+== DESCRIPTION
+
+The `cockpit-tls` program is a TLS terminating HTTP proxy for
+`cockpit-ws(8)`. It manages a set of isolated cockpit-ws instances, one
+per TLS client certificate, plus one for TLS without a client
+certificate, and one for unencrypted HTTP. With that, one session cannot
+tamper with another one through possible security vulnerability
+exploits.
+
+Users or administrators should never need to start this program as it
+automatically started by `systemd(1)` via socket activation.
+
+[[cockpit-tls-transport]]
+== 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, or below `$XDG_CONFIG_DIRS` if set (see
+link:./cockpit.conf.5.html[cockpit.conf]). 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 second one containing a
+`BEGIN PRIVATE KEY` or similar. The key must not be encrypted.
+
+If there is no TLS certificate, a self-signed certificate is
+automatically generated using `sscg` (if available) or `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 /usr/libexec/cockpit-certificate-ensure --check
+....
+
+Or, on Debian-based systems:
+
+....
+$ sudo /usr/lib/cockpit/cockpit-certificate-ensure --check
+....
+
+If using `certmonger` to manage certificates, following command can be
+used to generate a certificate/key pair:
+
+....
+CERT_FILE=/etc/cockpit/ws-certs.d/50-certmonger.crt
+KEY_FILE=/etc/cockpit/ws-certs.d/50-certmonger.key
+
+getcert request -f ${CERT_FILE} -k ${KEY_FILE} -D $(hostname --fqdn)
+....
+
+[[cockpit-tls-options]]
+== OPTIONS
+
+`--help`::
+  Show help options.
+`--port` <PORT>::
+  Serve HTTP requests on <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.
+`--no-tls`::
+  Don't use TLS. Certificates will not be read, and https connections
+  denied. Then `cockpit-tls` will only manage a single cockpit-ws
+  instance, and thus not do anything different than running
+  `cockpit-ws --no-tls` directly. Only use this for debugging or
+  testing.
+`--idle-timeout` <SECONDS>::
+  If greater than 0, exit if no connections have happened for the given
+  number of seconds, i. e. the server is idle. If not given, the default
+  is 90.
+
+[[cockpit-tls-environment]]
+== ENVIRONMENT
+
+The `cockpit-tls` program expects the `RUNTIME_DIRECTORY` environment
+variable to be set to an empty directory (preferably in `/run/`) that is
+only accessible by the system user under which it is running. This
+contains the Unix sockets for communicating with the `cockpit-ws`
+instances, and in the future, state information about client
+certificates. This variable is normally set by the `cockpit.service`
+systemd unit.
+
+In addition, `cockpit-tls` 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 certificates and the `cockpit.conf(5)`
+configuration file.
+
+[[cockpit-tls-bugs]]
+== BUGS
+
+Please send bug reports to either the distribution bug tracker or the
+https://github.com/cockpit-project/cockpit/issues/new[upstream bug
+tracker].
+
+[[cockpit-tls-author]]
+== AUTHOR
+
+Cockpit has been written by many
+https://github.com/cockpit-project/cockpit/graphs/contributors[contributors].
+
+[[cockpit-tls-also]]
+== SEE ALSO
+
+`cockpit-ws(8)` , `cockpit.conf(5)` , `systemd(1)`