-
Notifications
You must be signed in to change notification settings - Fork 68
Documentation clean-up #1188
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Documentation clean-up #1188
Changes from all commits
Commits
Show all changes
14 commits
Select commit
Hold shift + click to select a range
29004e4
doc: remove some outdated documentation
imobachgs 042d88e
doc: remove references to the --generate-token option
imobachgs 488f8c1
doc: rename the security document
imobachgs 18d0d0e
doc: update the architecture documentation
imobachgs 6232966
doc: update the i18n documentation
imobachgs 46d00b6
doc: drop non-relevant information about networking
imobachgs 6c78af9
doc: drop the debugging.md document
imobachgs e006795
auto: start agama-auto after agama-web-server
imobachgs c30784e
doc: update the startup document
imobachgs 5c98ddc
doc: drop outdated Cockpit-related config options
imobachgs c689d9c
doc: reduce the main README.md file
imobachgs a9eea5b
doc: small documentation fixes
imobachgs b5fefc9
doc: small fixes to the architecture document
imobachgs 7872bf1
doc: update (and reduce) the rust/README.md file
imobachgs File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains hidden or 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 hidden or 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 hidden or 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 | ||
imobachgs marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| * 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 hidden or 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 [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...). | ||
|
|
||
|
|
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.