Incorrectly had a link to cockpit-spawn which was the current file, it
should've been cockpit-dbus file instead.
Signed-off-by: Freya Gustavsson <freya@venefilyn.se>
We had set the cockpit-version attribute from the antora file which is
used by playbooks. This makes the attribute become locked and can't be
modified beforehand (that easily).
Proper usage, for us at least, is to update the cockpit-version through
an extension in cockpit-docs repo instead. This is only really a hack we
have to do due to publishing through tags instead of branches.
Signed-off-by: Freya Gustavsson <freya@venefilyn.se>
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>
Several files, including the deployment guide index page, link to the
old AsciiDoc guide on our website whereas our new docs site is published
under docs subdomain using Antora. While these links will work in the
future thanks to redirects we should update the links where we can to
avoid this unnecessary redirect.
Other changes include changing links from being header anchors within a
single-page to a multi-page navigation with asciidoctor's xref. This
change only applies to links within the same module and doesn't change
any links from guide to manpage for example. That will be tackled in a
future commit as it also has to deal with compiling to manpages.
Signed-off-by: Freya Gustavsson <freya@venefilyn.se>
Our `manifest.json` is currently only documented through our docs, and
in there it can be quite confusing. We tend to instead copy from other
repos or pages and I assume other projects do too. But modifying it can
be tedious.
Setting this JSON schema as a `$schema` property in your `manifest.json`
file will make all properties validated against.
For usage within manifest files the schema will be published under
Antora as an attachment and will therefore be versioned. This can be
accessed using the following for example:
- https://docs.cockpit-project.org/cockpit-guide/latest/_attachments/schema.json
- https://docs.cockpit-project.org/cockpit-guide/363/_attachments/schema.json
Assisted-by: AI
Signed-off-by: Freya Gustavsson <freya@venefilyn.se>
There was a mismatch between old docs and the new Antora docs in the
navigation structure. This fixes that and makes a slight modification
where the manual pages are listed separately from the deployment guide.
Signed-off-by: Freya Gustavsson <freya@venefilyn.se>
To preview Antora on this repo is just a few commands, lets add it to
the doc README so it makes it easier to work with.
Signed-off-by: Freya Gustavsson <freya@venefilyn.se>
These channel options are no longer implemented in the Python bridge and
would require writing certificates passed from JavaScript to a temporary
file as `load_cert_chain` does not support passing data via
string/bytes.
No known plugins used this option, most of them talk to a local UNIX
socket.
Related: https://github.com/python/cpython/issues/118557
Previously, only the Shell would participate in implementing session
idle timeouts. This means that a session was not guaranteed to time
out when the browser decided to suspend JavaScript execution.
Now the main actor for session idle timeout is the bridge: When
JavaScript starts, it will instruct the bridge to start the session
idle timeout timer. When it expires, the bridge will exit and end the
session even if JavaScript has been stopped.
While waiting for the timers to elapse, the bridge will send events
out over a new "session-control" channel type that inform the pages
when the final countdown has started, and when it is time to logout.
User activity is also reported over such a channel.
As part of a previous PR we dropped `py-asciidoc` completely in favor of
pre-bundling the documentation for distros where AsciiDoctor is not
available. At the time none of the code for building with `asciidoc` was
removed as I was unsure whether we'd need `py-asciidoc` or not.
With little reason to keep `py-asciidoc` as the maintenance burden to be
compatible with both `py-asciidoc` and `asciidoctor` is high, and it
making the integration with Antora more difficult, this commit drops all
code related to the Automake config and technical implmenetation
differences between the two.
This also drops the leveloffset helper as it was added as a way to
handle `py-asciidoc` and `asciidoctor` discrepancies when it comes to
going up and down the level offset for headings. Since we no longer use
AsciiDoc this is no longer relevant and can be dropped completely.
Related-to: https://github.com/cockpit-project/cockpit/pull/22693
Signed-off-by: Freya Gustavsson <freya@venefilyn.se>
Adds Antora configuration so that a dedicated Cockpit Doc repo can
access the various docs in Cockpit as well as an `antora-playbook.yml`
file for local development purposes (without relying on Cockpit Doc).
Partials in manpages were also renamed and restructured as Antora has a
dedicated partial import mechanism to allow for more functionality.
There were a few links in the nav files thar were not valid or pointed
to wrong files. Most of these were just naming mismatches and has been
changed to work with Antora. Nav files themselves also got the section
anchors removed as there is little reason to showcase specific
navigation items - instead section anchors should be used within pages
themselves.
Related-to: https://docs.antora.org/antora/latest/family-directories/
Signed-off-by: Freya Gustavsson <freya@venefilyn.se>
Antora uses a dedicated folder structure which we need to adhere to for
it to work as it should. Makefiles has moved to `doc/` root to simplify
the approach needed with Antora and AsciiDoctor.
Existing bundling of documentation with help of AsciiDoctor works as
normal and does not interfere with the directory change.
Signed-off-by: Freya Gustavsson <freya@venefilyn.se>
Anaconda wants to allow users to remotely log in Cockpit's WebUI
using a PIN for authentication. Instead of adding an Anaconda mode to
`cockpit.conf` allow Anaconda to bring its own login.html, JavaScript
and CSS. This gives Anaconda full flexibility over the login process
combined with implementing their own handler for basic auth.
That has been deprecated since 2019 when we introduced cockpit-tls in
commit ace21c8879. It's now getting in the way with the upcoming
support for post-quantum certificates, which we'll only do in c-tls.
Now the only thing that the `--no-tls` option does is to disable the TLS
redirection.
Part of https://issues.redhat.com/browse/COCKPIT-1330
While the existing document describes the protocol, it is hard to see
how all the moving parts communicate together. Describe the steps for
user/password, Kerberos, and client certificate authentication schemes.
Assisted-By: Claude code (initial mermaid diagram and proofreading)
With this we can get rid of asciidoc-py dependency altogether and
instead rely on the docs being prebundled before installation.
Include the built guide and manpages into the release tarball for that.
Fixes#22670https://issues.redhat.com/browse/COCKPIT-1370
Signed-off-by: Freya Gustavsson <freya@venefilyn.se>
Co-Authored-By: Martin Pitt <mpitt@redhat.com>
Regressed during migration from DocBook to AsciiDoc, version should now
show up correctly in the documentation pages themselves.
Fixes: https://github.com/cockpit-project/cockpit/issues/22671
Signed-off-by: Freya Gustavsson <freya@venefilyn.se>
As we now use AsciiDoc we can remove the DocBook files completely to
prevent confusion and mixups in the future.
Due to not having any docbook files left we can also remove
`convert.py`.
Co-authored-by: Aleksandra Fedorova <afedorova@redhat.com>
Signed-off-by: Freya Gustavsson <freya@venefilyn.se>
With the created AsciiDoc files for documentation we can now update our
build structure to generate the HTML and Manpage files both during build
and package distribution.
Changes
- Uses AsciiDoctor or asciidoc-py and a2x to generate HTML and Manpages.
- Generated HTML and Manpage files moved to `doc/output/`.
- Support packaging docs on all distributions Cockpit deploys to.
- Add package dependencies for AsciiDoctor and asciidoc-py.
- Safety fallback in automake file to search for either asciidoctor or
asciidoc-py in terms of priority.
Known issues
- Links in guide pages goes to new files for the pages themselves, which
meant we now generate HTML files for all `.adoc` files and not just
`index.html`.
With the removal of fonts we also managed to break the build pipeline
that automake generated for us. As the doc guide fonts make rule was
removed, which relied on `$(DIST_STAMP)` rule, automake optimized the
build process and in turn broke the workflow. As a workaround the
`$(DIST_STAMP)` rule was added to the index rule as a dep to help
automake generate it the way we want it.
As the workaround is a hack and not a real solution, this needs to be
fixed in another PR to make sure these dependency issues do not occur if
we were to remove `$(DIST_STAMP)` from a rule.
We also need the `$(DIST_STAMP)` to appear last in the doc generation or
something, likely race condition, may cause the `index.html` to only
contain `{}`.
Related-to: https://github.com/cockpit-project/cockpit/issues/22648
Related-to: https://github.com/cockpit-project/cockpit/issues/22647
Co-authored-by: Aleksandra Fedorova <afedorova@redhat.com>
Signed-off-by: Freya Gustavsson <freya@venefilyn.se>
Several improvements as well as a bug fix relating to AsciiDoc
generation for both `asciidoc-py` and `asciidoctor`.
Within AsciiDoctor to handle nested includes we can use relative
leveloffsets to have headers increase or decrease in size. The older
asciidoc-py does not have relative `leveloffset`s and we instead have to
rely on asciidoc counter to increase the offset and an eval to decrease
the offset. AsciiDoctor does not support modifying `leveloffset` through
eval, which means we need a helper module and a custom attribute, in
this case `asciidoctor`, to use either relative leveloffsets or
leveloffset eval.
Generated AsciiDoc files have been refined further by
- Splitting files out to multiple files and included them inline to be
able to support pages like `/guide.html` and `/development.html`
- Creating attributes for the head of each AsciiDoc manpage file
- Generated monospace code moved from \`code\` to \`+code+\`
- Header levels adjusted to keep one h1 and decreasing headings
- Page titles adjusted to be the recommendation from AsciiDoctor with
capitalization and titles.
- Manpage AsciiDoc files renamed to be the same as the output file for
easier conversion. Converted result is the same.
Co-authored-by: Aleksandra Fedorova <afedorova@redhat.com>
Signed-off-by: Freya Gustavsson <freya@venefilyn.se>
When converting the AsciiDoc manpages to HTML it is much easier if we
already include the section number in the filename before converting.
That way we are consistent with how we currently have it in production
and also make it easier for ourselves to only see the file extension
change and not the filename.
Website guide also had several docbook pages that were converted as-is
which had a different name when generated to HTML. Those were renamed to
reflect the new name or fix the minor naming issues.
Signed-off-by: Freya Gustavsson <freya@venefilyn.se>
Initial conversion done using a script in `doc/convert.py` that takes
the DocBook XML files and generates it to AsciiDoc files.
Co-authored-by: Aleksandra Fedorova <afedorova@redhat.com>
Signed-off-by: Freya Gustavsson <freya@venefilyn.se>
This allows administrators to customize Cockpit's branding without
messing around in /usr. Add XDG_CONFIG_DIRS/cockpit/branding/ (i.e.
usually in /etc/cockpit/branding) to the front of the search list, so
that it gets prefered over XDG_DATA_DIRS.
Fixes#21338https://issues.redhat.com/browse/RHEL-102556
This has no effect right now, as the only things that current
branding.scss affects are the login page (`#brand` and `#badge`) and the
shell (`--ct-color-host-accent`). But we want to make branding more
customizable with e.g. [1], which should apply to all pages
consistently.
In particular, this also allows Anaconda to customize/brand the storage
page [2].
Document the possibility of customization and test this with setting
`--pf-t--global--color--brand--default`.
Part of #21338
[1] https://www.patternfly.org/design-foundations/colors/#brand-colors
[2] https://github.com/rhinstaller/anaconda-webui/pull/951
When trying to log in with a shell that does not understand `exit 71`
(our litmus test for "reasonable shell"), this was previously really
hard to understand/debug: The journal did not show anything bad other
than that the session only lasted a blink of an eye, and the login page
just said "permission denied".
Log a proper warning to the journal that explains what happens.
Let the login page show "Unsupported shell. Check the journal for
details." We are past authentication at this point, so we can afford
giving away that piece of information.
This does not really work on Arch, where /etc/pam.d/system-login
enforces `pam_shells`. So any "odd" shell already gets rejected in the
`auth` stage, and the session (and thus this shell validity check) does
not even start. That was also the reason for the tow alternative
`error-title` matches before.
Fixes#20741
This was previously merged and released without a note indicating which
version it was added in (286).
Related-to: #18291
Signed-off-by: Freya Gustavsson <freya@venefilyn.se>
Extend `fsreplace1` to allow setting the file mode, this is not required
for cockpit-files but can be used in Cockpit itself. It expects the
same octal number as fsinfo returns in its file entries.
Cockpit-files wants to support uploading or creating a file owned by the
current directory which might be different from the logged in user.
For example as superuser uploading a database into `/var/lib/postgresql`
which would be owned by `postgres` and the database file should receive
the same permissions.
Since `cockpit.init()` has been introduced Cockpit pages no longer have
to retrieve the user via `cockpit.user()` as it is directly available on
`cockpit.info`.
This is a regression from our port of the bridge from C to Python. The C
bridge had a limit and as fsread1 is not blocking implemented this
prevents issues of accidentally reading /dev/zero or /dev/sda which will
fill up ram endlessly.
For existing `fsread1` users (cockpit-files) to keep relying on an
unlimited mode `max_read_size` now supports passing `-1` which removes
the limit.
