-
Notifications
You must be signed in to change notification settings - Fork 43
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Agama's repository contains many documents related to different parts of the project. As we do not have a documentation site (yet), it is rather easy to forget about them. As a consequence, a few of them are really outdated. Things got worse when we merged the new architecture into the `master` branch. This PR tries to update (or remove, in some cases) those documents. Additionally, we took the opportunity to reduce the size of the `README.md,` which was simply too long.
- Loading branch information
Showing
22 changed files
with
389 additions
and
1,331 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
| # Agama Status | ||
|
|
||
| ## CI and checks | ||
|
|
||
| [](https://github.com/openSUSE/agama/actions/workflows/ci-rust.yml) | ||
| [](https://github.com/openSUSE/agama/actions/workflows/ci-service.yml) | ||
| [](https://github.com/openSUSE/agama/actions/workflows/ci-web.yml) | ||
| [](https://github.com/openSUSE/agama/actions/workflows/ci-rubocop.yml) | ||
| [](https://github.com/openSUSE/agama/actions/workflows/ci-doc-check.yml) | ||
| [](https://github.com/openSUSE/agama/actions/workflows/ci-integration-tests.yml) | ||
| [](https://coveralls.io/github/openSUSE/agama?branch=master) | ||
| [](https://github.com/openSUSE/agama/actions/workflows/github-pages.yml) | ||
|
|
||
| ## Translations | ||
|
|
||
| [](https://github.com/openSUSE/agama/actions/workflows/weblate-update-pot.yml) | ||
| [](https://github.com/openSUSE/agama/actions/workflows/weblate-merge-po.yml) | ||
| [](https://github.com/openSUSE/agama/actions/workflows/weblate-merge-products-po.yml) | ||
| [](https://l10n.opensuse.org/engage/agama/) | ||
|
|
||
| ## Packages | ||
|
|
||
| ### [OBS systemsmanagement:Agama:Staging](https://build.opensuse.org/project/show/systemsmanagement:Agama:Staging) | ||
|
|
||
| [](https://github.com/openSUSE/agama/actions/workflows/obs-staging-rust.yml) | ||
| [](https://github.com/openSUSE/agama/actions/workflows/obs-staging-web.yml) | ||
| [](https://github.com/openSUSE/agama/actions/workflows/obs-staging-service.yml) | ||
| [](https://github.com/openSUSE/agama/actions/workflows/obs-staging-playwright.yml) | ||
|
|
||
| [](https://build.opensuse.org/package/show/systemsmanagement:Agama:Staging/agama) | ||
| [](https://build.opensuse.org/package/show/systemsmanagement:Agama:Staging/cockpit-agama) | ||
| [](https://build.opensuse.org/package/show/systemsmanagement:Agama:Staging/rubygem-agama-yast) | ||
| [](https://build.opensuse.org/package/show/systemsmanagement:Agama:Staging/agama-products-opensuse) | ||
| [](https://build.opensuse.org/package/show/systemsmanagement:Agama:Staging/cockpit-agama-playwright) | ||
| [](https://build.opensuse.org/package/show/systemsmanagement:Agama:Staging/agama-live) | ||
|
|
||
| ### [OBS systemsmanagement:Agama:Devel](https://build.opensuse.org/project/show/systemsmanagement:Agama:Devel) | ||
|
|
||
|  | ||
| [](https://github.com/openSUSE/agama/actions/workflows/obs-release.yml) | ||
|
|
||
| [](https://build.opensuse.org/package/show/systemsmanagement:Agama:Devel/agama) | ||
| [](https://build.opensuse.org/package/show/systemsmanagement:Agama:Devel/cockpit-agama) | ||
| [](https://build.opensuse.org/package/show/systemsmanagement:Agama:Devel/rubygem-agama-yast) | ||
| [](https://build.opensuse.org/package/show/systemsmanagement:Agama:Devel/agama-live) | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 root@agama.local | ||
| ``` | ||
|
|
||
| ##### 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...). | ||
|
|
||
|
|
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.