agama-project · imobachgs · May 9, 2024 · May 9, 2024 · May 9, 2024 · May 9, 2024
diff --git a/README.md b/README.md
diff --git a/STATUS.md b/STATUS.md
@@ -0,0 +1,46 @@
+# Agama Status
+
+## CI and checks
+
+[![CI - Rust](https://github.com/openSUSE/agama/actions/workflows/ci-rust.yml/badge.svg)](https://github.com/openSUSE/agama/actions/workflows/ci-rust.yml)
+[![CI - Service](https://github.com/openSUSE/agama/actions/workflows/ci-service.yml/badge.svg)](https://github.com/openSUSE/agama/actions/workflows/ci-service.yml)
+[![CI - Web](https://github.com/openSUSE/agama/actions/workflows/ci-web.yml/badge.svg)](https://github.com/openSUSE/agama/actions/workflows/ci-web.yml)
+[![CI - Rubocop](https://github.com/openSUSE/agama/actions/workflows/ci-rubocop.yml/badge.svg)](https://github.com/openSUSE/agama/actions/workflows/ci-rubocop.yml)
+[![CI - Documentation Check](https://github.com/openSUSE/agama/actions/workflows/ci-doc-check.yml/badge.svg)](https://github.com/openSUSE/agama/actions/workflows/ci-doc-check.yml)
+[![CI - Integration Tests](https://github.com/openSUSE/agama/actions/workflows/ci-integration-tests.yml/badge.svg)](https://github.com/openSUSE/agama/actions/workflows/ci-integration-tests.yml)
+[![Coverage Status](https://coveralls.io/repos/github/openSUSE/agama/badge.svg?branch=master)](https://coveralls.io/github/openSUSE/agama?branch=master)
+[![GitHub Pages](https://github.com/openSUSE/agama/actions/workflows/github-pages.yml/badge.svg)](https://github.com/openSUSE/agama/actions/workflows/github-pages.yml)
+
+## Translations
+
+[![Weblate Update POT](https://github.com/openSUSE/agama/actions/workflows/weblate-update-pot.yml/badge.svg)](https://github.com/openSUSE/agama/actions/workflows/weblate-update-pot.yml)
+[![Weblate Merge PO](https://github.com/openSUSE/agama/actions/workflows/weblate-merge-po.yml/badge.svg)](https://github.com/openSUSE/agama/actions/workflows/weblate-merge-po.yml)
+[![Weblate Merge Product PO](https://github.com/openSUSE/agama/actions/workflows/weblate-merge-products-po.yml/badge.svg)](https://github.com/openSUSE/agama/actions/workflows/weblate-merge-products-po.yml)
+[![Translation Status](https://l10n.opensuse.org/widgets/agama/-/agama-web/svg-badge.svg)](https://l10n.opensuse.org/engage/agama/)
+
+## Packages
+
+### [OBS systemsmanagement:Agama:Staging](https://build.opensuse.org/project/show/systemsmanagement:Agama:Staging)
+
+[![Submit agama](https://github.com/openSUSE/agama/actions/workflows/obs-staging-rust.yml/badge.svg)](https://github.com/openSUSE/agama/actions/workflows/obs-staging-rust.yml)
+[![Submit cockpit-agama](https://github.com/openSUSE/agama/actions/workflows/obs-staging-web.yml/badge.svg)](https://github.com/openSUSE/agama/actions/workflows/obs-staging-web.yml)
+[![Submit rubygem-agama-yast](https://github.com/openSUSE/agama/actions/workflows/obs-staging-service.yml/badge.svg)](https://github.com/openSUSE/agama/actions/workflows/obs-staging-service.yml)
+[![Submit cockpit-agama-playwright](https://github.com/openSUSE/agama/actions/workflows/obs-staging-playwright.yml/badge.svg)](https://github.com/openSUSE/agama/actions/workflows/obs-staging-playwright.yml)
+
+[![OBS Staging/agama](https://img.shields.io/obs/systemsmanagement:Agama:Staging/agama/openSUSE_Tumbleweed/x86_64?label=Package%20agama)](https://build.opensuse.org/package/show/systemsmanagement:Agama:Staging/agama)
+[![OBS Staging/cockpit-agama](https://img.shields.io/obs/systemsmanagement:Agama:Staging/cockpit-agama/openSUSE_Tumbleweed/x86_64?label=Package%20cockpit-agama)](https://build.opensuse.org/package/show/systemsmanagement:Agama:Staging/cockpit-agama)
+[![OBS Staging/rubygem-agama-yast](https://img.shields.io/obs/systemsmanagement:Agama:Staging/rubygem-agama-yast/openSUSE_Tumbleweed/x86_64?label=Package%20rubygem-agama-yast)](https://build.opensuse.org/package/show/systemsmanagement:Agama:Staging/rubygem-agama-yast)
+[![OBS Staging/agama-products-opensuse](https://img.shields.io/obs/systemsmanagement%3AAgama%3AStaging/agama-products-opensuse/openSUSE_Tumbleweed/x86_64?label=Package%20agama-products-opensuse)](https://build.opensuse.org/package/show/systemsmanagement:Agama:Staging/agama-products-opensuse)
+[![OBS Staging/cockpit-agama-playwright](https://img.shields.io/obs/systemsmanagement:Agama:Staging/cockpit-agama-playwright/openSUSE_Tumbleweed/x86_64?label=Package%20cockpit-agama-playwright)](https://build.opensuse.org/package/show/systemsmanagement:Agama:Staging/cockpit-agama-playwright)
+[![OBS Staging/agama-live](https://img.shields.io/obs/systemsmanagement:Agama:Staging/agama-live:openSUSE/images/x86_64?label=Live%20ISO)](https://build.opensuse.org/package/show/systemsmanagement:Agama:Staging/agama-live)
+
+### [OBS systemsmanagement:Agama:Devel](https://build.opensuse.org/project/show/systemsmanagement:Agama:Devel)
+
+![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/openSUSE/agama?label=Version&sort=semver)
+[![Release](https://github.com/openSUSE/agama/actions/workflows/obs-release.yml/badge.svg)](https://github.com/openSUSE/agama/actions/workflows/obs-release.yml)
+
+[![OBS Devel/agama](https://img.shields.io/obs/systemsmanagement:Agama:Devel/agama/openSUSE_Tumbleweed/x86_64?label=Package%20agama)](https://build.opensuse.org/package/show/systemsmanagement:Agama:Devel/agama)
+[![OBS Devel/cockpit-agama](https://img.shields.io/obs/systemsmanagement:Agama:Devel/cockpit-agama/openSUSE_Tumbleweed/x86_64?label=Package%20cockpit-agama)](https://build.opensuse.org/package/show/systemsmanagement:Agama:Devel/cockpit-agama)
+[![OBS Devel/rubygem-agama-yast](https://img.shields.io/obs/systemsmanagement:Agama:Devel/rubygem-agama-yast/openSUSE_Tumbleweed/x86_64?label=Package%20rubygem-agama-yast)](https://build.opensuse.org/package/show/systemsmanagement:Agama:Devel/rubygem-agama-yast)
+[![OBS Devel/agama-live](https://img.shields.io/obs/systemsmanagement:Agama:Devel/agama-live:openSUSE/images/x86_64?label=Live%20ISO)](https://build.opensuse.org/package/show/systemsmanagement:Agama:Devel/agama-live)
+
diff --git a/autoinstallation/systemd/agama-auto.service b/autoinstallation/systemd/agama-auto.service
@@ -5,8 +5,7 @@ After=dbus.socket
 # it needs to NetworkManager, so it has access to it
 After=NetworkManager.service
 # it needs agama, of course
-After=agama.service
-Requires=agama.service
+After=agama-web-server.service
 
 [Service]
 ExecStart=/usr/bin/auto.sh

diff --git a/doc/architecture.md b/doc/architecture.md
@@ -0,0 +1,98 @@
+# Agama's architecture
+
+On the surface, Agama implements a typical client-server architecture. The server offers an HTTP/
+JSON API with a WebSocket to send messages to the connected clients. The web and the command-line
+interfaces, part of Agama, connect to that server.
+
+However, things are more complex, and the server comprises different pieces, as described in this
+document.
+
+## Components
+
+On the server side, Agama is composed by:
+
+* **Agama server**: from a user's perspective, this is the core of Agama. It is responsible for:
+  * Implementing (part of) the installation logic. A good share of this logic is delegated to
+    **Agama YaST**.
+  * Offering an HTTP and WebSocket (HTTP/WS) interface.
+  * Making the **web-based user interface** available to the browsers.
+
+* **Agama YaST service**: it is written in Ruby and has direct access to YaST libraries.  This
+  component implements complex parts, like storage and software handling. Communication with the
+  Agama web server happens over D-Bus.
+
+* **Agama D-Bus service**: implements a minimal API to allow **Agama YaST server** to talk to the web
+server. It is expected to be replaced by direct communication in the future.
+
+On the client side, these are the main components:
+
+* **Web user interface (old `cockpit-agama`)**: Agama's graphical user interface. The **Agama web
+server** makes this React application available to browsers.
+
+* **Command-Line Interface (`agama-cli`)**: it allows interaction with Agama and drives the
+auto-installation process.
+
+* **Auto-installation (`autoinstallation`)**: it is composed of a Systemd service (`agama-auto`) and
+a script that relies on `agama-cli` binary.
+
+The following diagram could be better, but it represents the main components and their interactions.
+
+```mermaid
+flowchart LR
+  subgraph Clients
+    Browser
+    CLI
+    auto
+  end
+
+  subgraph Agama Server
+    subgraph Web["Web Server"]
+      direction TB
+      UI["Web UI"]
+      API["HTTP/WS API"]
+      WS["WebSocket"]
+    end
+
+    Web <--"Channel" --> Rust
+  end
+  Rust <-- "D-Bus" --> YaST["Agama YaST"]
+
+  Browser --> UI
+  Browser --> API
+  Browser <---> WS
+  CLI --> API
+  CLI <---> WS
+  auto --> CLI
+```
+
+## Encryption
+
+In the case of a remote installation, the communication between the clients and the server must be
+encrypted. Connecting to port 80 (HTTP) redirects the client to port 443 (HTTPS).
+
+About the certificate, Agama uses a self-signed certificate unless the user injects its own.
+
+## Authentication
+
+The HTTP interface allows authentication specifying the root password that will be checked
+against PAM.
+
+On successful authentication, the server generates a [JSON Web Token][jwt] that the client
+will include in the subsequent requests. The web client stores the token in an HTTP-only
+cookie[^http-only] and the CLI uses a file with restricted permissions.
+
+[^http-only]: HTTP-only cookies cannot be accessed by client-side JavaScript.
+
+## Skipping the authentication
+
+When using Agama locally in the installation media, it would be unpleasant to ask for a password.
+For that reason, Agama implements a mechanism to skip the authentication step. This mechanism is
+documented in the [security document](./agama-security.md).
+
+## Links
+
+* https://bugzilla.suse.com/show_bug.cgi?id=1219688
+* https://cheatsheetseries.owasp.org/cheatsheets/JSON_Web_Token_for_Java_Cheat_Sheet.html
+
+[http-auth]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication
+[jwt]: https://jwt.io
diff --git a/doc/avahi.md b/doc/avahi.md
@@ -0,0 +1,90 @@
+#### Avahi/mDNS
+
+Agama's Live ISO is configured to use mDNS (sometimes called Avahi, Zeroconf, Bonjour) for hostname
+resolution. The reason is that it might be quite difficult to find out which URL should be used for
+connecting to a running Agama installer.
+
+This document explains how this feature works and offers a few hints for fix potential problems.
+
+>[!WARNING]
+> Do not use the `.local` hostnames in untrusted networks (like public WiFi networks, shared
+> networks), it is a security risk. An attacker can easily send malicious responses for the `.local`
+> hostname resolutions and point you to a wrong Agama instance which could for example steal your
+> root password!
+
+##### Firewall Configuration
+
+If you cannot connect to a server using the `.local` domain then maybe the
+firewall is blocking the traffic. Then you need to enable the mDNS traffic using
+these commands:
+
+```shell
+# enable the mDNS traffic in the current run
+firewall-cmd --zone=public --add-service=mdns
+# make the change permanent
+firewall-cmd --permanent --zone=public --add-service=mdns
+```
+
+##### Using mDNS
+
+The Live ISO by default uses the `agama.local` hostname. To connect to the
+running instance simply type `https://agama.local` in your browser. In most
+browsers the HTTPS is the default protocol so usually it is enough to just type
+`agama.local`.
+
+If you run multiple Agama instances, each one will have a different name. The server
+appends a number to make it unique. So the second Agama instance gets the
+`agama-2.local` hostname.
+
+If you are not sure whether there are multiple Agama instances running you scan
+the network, see the [service advertising](#service-advertising) below.
+
+Alternatively you can set a different hostname for each instance manually. Use
+the `hostname=` boot option to set a different hostname. For example set
+`hostname=foo`, `hostname=bar` and then use `https://foo.local`,
+`https://bar.local` URLs in the web browser to connect to the respective
+instance.
+
+It is possible to change the hostname later if needed:
+
+```shell
+# set the new hostname
+hostnamectl hostname <hostname>
+# restart the avahi daemon server
+systemctl restart avahi-daemon
+```
+
+The mDNS resolution also works for other services like ping or SSH. So you can
+use commands like:
+
+```shell
+ping agama.local
+ssh [email protected]
+```
+
+##### Fallback
+
+The mDNS approach is just an addition, one more possibility how to connect to
+the machine. If it does not work for you then you can always use the old good
+classic IP address approach.
+
+##### Service Advertising
+
+The Agama Live ISO also uses Avahi service advertising. With this you can easily
+search for all running Agama instances in the local network:
+
+```shell
+avahi-browse -t -r _agama._sub._https._tcp
+```
+
+The command will print the found servers and their hostnames and IP addresses.
+
+##### Notes
+
+- mDNS works only in the same local network, it does not work over internet
+  or separate network segments.
+- mDNS might not be supported in all systems or it might be blocked by firewall.
+- On mobile phones with Android OS mDNS is supported since Android version 12.
+  (but this might be vendor dependent...).
+
+
diff --git a/doc/debugging.md b/doc/debugging.md