Updated readthedoc with changes of UDS

Relates to: #997 The readthedocs pages and diagrams have been updated to reflect the changes done to support Unix Domain Sockets (UDS) and TCP/IP with UDS in parallel. Signed-off-by: Michael Engel <[email protected]>
eclipse-bluechi · Dec 19, 2024 · e01b99b · e01b99b
1 parent 98e62f4
commit e01b99b
Show file tree

Hide file tree

Showing 10 changed files with 148 additions and 131 deletions.
diff --git a/doc/diagrams.drawio.xml b/doc/diagrams.drawio.xml
diff --git a/doc/docs/api/client_generation.md b/doc/docs/api/client_generation.md
@@ -1,4 +1,5 @@
 <!-- markdownlint-disable-file MD013 -->
+
 # Generating BlueChi clients
 
 BlueChi provides [introspection data](https://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format) for its public API. These XML files are located in the [data directory](https://github.com/eclipse-bluechi/bluechi/tree/main/data) of the project and can be also be used as input to generate clients.
@@ -49,7 +50,7 @@ The `bluechi` python package consists of two subpackages:
 - `api`: auto-generated code based the BlueChi D-BUS API description
 - `ext`: custom written code to simplify common tasks
 
-Functions from the auto-generated `api` subpackage reduce boilerplate code. It also removes the need to explicitly specify the D-Bus name, paths and interfaces and offers abstracted and easy to use functions. For example, lets compare the python code for listing all nodes.
+Functions from the auto-generated `api` subpackage reduce boilerplate code. It also removes the need to explicitly specify the D-Bus name, paths and interfaces and offers abstracted and easy to use functions. For example, let's compare the python code for listing all nodes.
 
 Using the auto-generated bindings, the code would look like this:
 

diff --git a/doc/docs/assets/img/bluechi_architecture_overview.png b/doc/docs/assets/img/bluechi_architecture_overview.png
diff --git a/doc/docs/cross_node_dependencies/usage.md b/doc/docs/cross_node_dependencies/usage.md
@@ -1,4 +1,5 @@
 <!-- markdownlint-disable-file MD010 MD013 MD014 MD024 MD034 MD046 -->
+
 # Using Proxy Services
 
 This section describes different scenarios of cross-node dependencies between services, how to resolve them using BlueChi's proxy service feature and which systemd mechanisms to use for the desired behaviour. As a baseline, the term `source.service` will be used for the systemd service that depends on a remote service, which will be referred to as `target.service`.
@@ -7,17 +8,18 @@ This section describes different scenarios of cross-node dependencies between se
 
 !!! Note
 
-    This section focuses on the systemd and BlueChi mechanisms to define dependencies enforcing certain behaviour. For an introduction to proxy services with an example application, please refer to the `Getting started guide` with the [cross-node dependency example](../getting_started/cross_node_dependencies.md). 
+    This section focuses on the systemd and BlueChi mechanisms to define dependencies enforcing certain behaviour. For an introduction to proxy services with an example application, please refer to the `Getting started guide` with the [cross-node dependency example](../getting_started/cross_node_dependencies.md).
 
 ## Stop source service when starting target service fails
 
 If the `source.service` requires the `target.service` to be in an **active state** and otherwise stops, this can be ensured by using `Requires=`. The failure of `target.service` is simulated by just executing `/bin/false`, returning exit code 1.
 
 === "source.service"
-    ```systemd
-    [Unit]
-    Requires=bluechi-proxy@worker2_target.service
-    After=bluechi-proxy@worker2_target.service
+
+````systemd
+[Unit]
+Requires=bluechi-proxy@worker2_target.service
+After=bluechi-proxy@worker2_target.service
 
     [Service]
     Type=simple
@@ -26,17 +28,17 @@ If the `source.service` requires the `target.service` to be in an **active state
     ```
 
 === "target.service"
-    ```systemd
-    [Unit]
-    Description=Target service
+```systemd
+[Unit]
+Description=Target service
 
     [Service]
     Type=simple
     ExecStart=/bin/false
     RemainAfterExit=yes
     ```
 
-Lets try out the example services from above:
+Let's try out the example services from above:
 
 ```bash
 $ bluechictl start main source.service
@@ -51,7 +53,7 @@ UNIT		| LOADED	| ACTIVE	| SUBSTATE	| FREEZERSTATE	| ENABLED	|
 ------------------------------------------------------------------------------------------------
 target.service	| loaded	| failed	| failed	| running	| static	|
 
-```
+````
 
 !!! Note
 
@@ -62,10 +64,11 @@ target.service	| loaded	| failed	| failed	| running	| static	|
 In order to automatically stop the `target.service` when the requiring `source.service` has been stopped, systemd's `StopWhenUnneeded=yes` can be used in the `[Unit]` section of the `target.service` as shown in the snippets below:
 
 === "source.service"
-    ```systemd
-    [Unit]
-    Wants=bluechi-proxy@worker2_target.service
-    After=bluechi-proxy@worker2_target.service
+
+````systemd
+[Unit]
+Wants=bluechi-proxy@worker2_target.service
+After=bluechi-proxy@worker2_target.service
 
     [Service]
     Type=simple
@@ -74,17 +77,17 @@ In order to automatically stop the `target.service` when the requiring `source.s
     ```
 
 === "target.service"
-    ```systemd
-    [Unit]
-    StopWhenUnneeded=yes
+```systemd
+[Unit]
+StopWhenUnneeded=yes
 
     [Service]
     Type=simple
     ExecStart=/bin/true
     RemainAfterExit=yes
     ```
 
-Lets try out the example services from above:
+Let's try out the example services from above:
 
 ```bash
 # start the source service and check status
@@ -112,7 +115,7 @@ $ bluechictl status worker2 target.service
 UNIT			| LOADED	| ACTIVE	| SUBSTATE	| FREEZERSTATE	| ENABLED	|
 ---------------------------------------------------------------------------------
 target.service	| loaded	| inactive	| dead		| running	| static	    |
-```
+````
 
 !!! Note
 
@@ -123,10 +126,11 @@ target.service	| loaded	| inactive	| dead		| running	| static	    |
 If the `target.service` enters a **failed** or **inactive** state at some point in time, the `source.service` is able to restart it by using `Upholds=` as shown in the snippet below.
 
 === "source.service"
-    ```systemd
-    [Unit]
-    Upholds=bluechi-proxy@worker2_target.service
-    After=bluechi-proxy@worker2_target.service
+
+````systemd
+[Unit]
+Upholds=bluechi-proxy@worker2_target.service
+After=bluechi-proxy@worker2_target.service
 
     [Service]
     Type=simple
@@ -135,16 +139,16 @@ If the `target.service` enters a **failed** or **inactive** state at some point
     ```
 
 === "target.service"
-    ```systemd
-    [Unit]
-    StopWhenUnneeded=yes
+```systemd
+[Unit]
+StopWhenUnneeded=yes
 
     [Service]
     Type=simple
     ExecStart=/bin/sleep 5
     ```
 
-Lets try out the example services from above:
+Let's try out the example services from above:
 
 ```bash
 $ bluechictl start main source.service
@@ -158,7 +162,7 @@ $ bluechictl status worker2 target.service
 UNIT		    | LOADED	| ACTIVE	    | SUBSTATE	| FREEZERSTATE	| ENABLED	|
 -------------------------------------------------------------------------------------
 target.service	| loaded	| active	    | running	| running	    | static	|
-```
+````
 
 !!! Note
 

diff --git a/doc/docs/getting_started/cross_node_dependencies.md b/doc/docs/getting_started/cross_node_dependencies.md
@@ -1,4 +1,5 @@
 <!-- markdownlint-disable-file MD010 MD013 MD014 MD024 MD046 -->
+
 # Resolving cross-node dependencies
 
 In practice, it is a common scenario that a service running on Node A requires another service to run on Node B. Consider the following example:
@@ -40,7 +41,7 @@ Reload the systemd controller configuration so it can find the newly created ser
 $ systemctl daemon-reload
 ```
 
-Lets verify that the service works as expected. First, start the service via:
+Let's verify that the service works as expected. First, start the service via:
 
 ```bash
 $ systemctl start bluechi-cdn.service
@@ -51,20 +52,20 @@ Then submit a query to it. The response should be an HTML page that contains the
 ```html
 $ curl localhost:9000
 
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
 <html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
-<title>Directory listing for /</title>
-</head>
-<body>
-<h1>Directory listing for /</h1>
-<hr>
-<ul>
-<li><a href="bluechi_architecture.jpg">bluechi_architecture.jpg</a></li>
-</ul>
-<hr>
-</body>
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <title>Directory listing for /</title>
+  </head>
+  <body>
+    <h1>Directory listing for /</h1>
+    <hr />
+    <ul>
+      <li><a href="bluechi_architecture.jpg">bluechi_architecture.jpg</a></li>
+    </ul>
+    <hr />
+  </body>
 </html>
 ```
 
@@ -126,7 +127,7 @@ if __name__ == "__main__":
         server.handle_request()
 ```
 
-Lets create a new systemd unit to wrap the `service.py`. Copy and paste the following unit definition into `/etc/systemd/system/bluechi-webservice.service`:
+Let's create a new systemd unit to wrap the `service.py`. Copy and paste the following unit definition into `/etc/systemd/system/bluechi-webservice.service`:
 
 ```systemd
 [Unit]
@@ -144,13 +145,15 @@ ExecStart=/usr/bin/python3 /tmp/bluechi-webservice/service.py 9000 192.168.178.5
 Start the service via `systemctl` to verify it works as expected:
 
 ```html
-$ systemctl start bluechi-webservice.service
-$ curl localhost:9000
+$ systemctl start bluechi-webservice.service $ curl localhost:9000
 
 <html>
-    <body>
-        <img src="http://192.168.178.55:9000/bluechi_architecture.jpg" alt="bluechi_architecture" />
-    </body>
+  <body>
+    <img
+      src="http://192.168.178.55:9000/bluechi_architecture.jpg"
+      alt="bluechi_architecture"
+    />
+  </body>
 </html>
 ```
 
@@ -162,7 +165,7 @@ $ systemctl stop bluechi-webservice.service
 
 ## Resolving the dependency via BlueChi
 
-After implementing both applications, lets ensure that starting the webservice will also start the CDN. Add the following lines to `bluechi-webservice.service` in the `[Unit]` section:
+After implementing both applications, let's ensure that starting the webservice will also start the CDN. Add the following lines to `bluechi-webservice.service` in the `[Unit]` section:
 
 ```systemd
 Wants=bluechi-proxy@pi_bluechi-cdn.service

diff --git a/doc/docs/getting_started/examples_bluechictl.md b/doc/docs/getting_started/examples_bluechictl.md
@@ -1,4 +1,5 @@
 <!-- markdownlint-disable-file MD010 MD013 MD014 MD024 MD046 -->
+
 # Examples on how to use BlueChi
 
 For the examples in this section the a [multi-node setup](./multi_node.md) is assumed to be running and uses [bluechictl](../man/bluechictl.md) to interact with BlueChi. In order to leverage the full potential of BlueChi, e.g. by writing custom applications, please refer to the section describing how to [use BlueChi's D-Bus API](../api/examples.md).
@@ -42,7 +43,7 @@ Subscribing to node '*' and unit '*'
 !!! Note
 
     When a unit subscription with a wildcard `*` exists, BlueChi emits `virtual` events for the unit with name `*` on
-    
+
     - creation of the wildcard subscription
     - node in the the wildcard subscription dis-/connects
 
@@ -55,19 +56,19 @@ In addition to monitoring units, BlueChi's APIs can be used to query and monitor
 ```bash
 $ bluechictl status
 
-NODE                          | STATE     | LAST SEEN                   
+NODE                          | STATE     | LAST SEEN
 =========================================================================
-laptop                        | online    | now                         
-pi                            | online    | now                         
+laptop                        | online    | now
+pi                            | online    | now
 ```
 
 Assuming node `pi` would go offline, the output would immediately change to something like this:
 
 ```bash
-NODE                          | STATE     | LAST SEEN                   
+NODE                          | STATE     | LAST SEEN
 =========================================================================
-laptop                        | online    | now                         
-pi                            | online    | 2023-10-06 08:38:20,000+0200                         
+laptop                        | online    | now
+pi                            | online    | 2023-10-06 08:38:20,000+0200
 ```
 
 It is also possible to show the status of a specific node
@@ -94,9 +95,9 @@ Done
 
 !!! Note
 
-    Starting a systemd unit via BlueChi's D-Bus API queues a job to start that unit in systemd. `bluechictl start` also waits for this job to be completed. This also applies to other operations like **stop**. 
+    Starting a systemd unit via BlueChi's D-Bus API queues a job to start that unit in systemd. `bluechictl start` also waits for this job to be completed. This also applies to other operations like **stop**.
 
-Lets stop the `httpd` service:
+Let's stop the `httpd` service:
 
 ```bash
 $ bluechictl stop pi httpd

diff --git a/doc/docs/getting_started/multi_node.md b/doc/docs/getting_started/multi_node.md
@@ -1,4 +1,5 @@
 <!-- markdownlint-disable-file MD010 MD013 MD014 MD024 MD046 -->
+
 # Setup: Multi node
 
 BlueChi is intended for multi-node environments with a predefined number of nodes. This section describes how to set it up based on an example with two machines - a laptop and a raspberry pi. The diagram below depicts the desired state of the system:
@@ -7,32 +8,35 @@ BlueChi is intended for multi-node environments with a predefined number of node
 
 ## Installation and configuration
 
-The main node will be the **laptop**. So first of all, lets install the controller, the agent and the CLI tool as well as the SELinux policy on it:
+The main node will be the **laptop**. So first of all, let's install the controller, the agent and the CLI tool as well as the SELinux policy on it:
 
 ```bash
-dnf install bluechi bluechi-agent bluechi-ctl bluechi-selinux 
+dnf install bluechi bluechi-agent bluechi-ctl bluechi-selinux
 ```
 
 The **raspberry pi** will be (one of) the managed node in this example. Therefore, only install the agent and the SELinux policy on it:
 
 ```bash
-dnf install bluechi-agent bluechi-selinux 
+dnf install bluechi-agent bluechi-selinux
 ```
 
 Once the installations succeeded, BlueChi needs to be configured on both machines.
 
 ### Configuring the main node
 
-Lets start with the main node (the **laptop** in this case). The configuration of the controller running on the **laptop** is similar to the [single node setup](#installation-and-configuration) with the exception of adding **pi** as another node to it:
+Let's start with the main node (the **laptop** in this case). The configuration of the controller running on the **laptop** is similar to the [single node setup](#installation-and-configuration) with two exceptions:
+
+- **pi** needs to be added as another node
+- **pi** is a remote agent and will connect to BlueChi via TCP/IP. By default, the privileged port 842 is used. To avoid any firewall issues for this demo, let's overwrite this setting and use the port **2020**.
 
 ```bash
 echo -e "[bluechi-controller]\nControllerPort=2020\nAllowedNodeNames=$(hostname),pi\n" > /etc/bluechi/controller.conf.d/1.conf
 ```
 
-Lets also create the configuration for the agent on the **laptop** changing the port:
+Let's also create the configuration for the local agent on the **laptop** to use the Unix Domain Socket:
 
 ```bash
-echo -e "[bluechi-agent]\nControllerPort=2020\n" > /etc/bluechi/agent.conf.d/1.conf
+echo -e "[bluechi-agent]\nControllerAddress=unix:path=/run/bluechi/bluechi.sock\n" > /etc/bluechi/agent.conf.d/1.conf
 ```
 
 ### Configuring the managed node
@@ -57,7 +61,7 @@ ControllerPort=2020
 
 ## Running BlueChi
 
-After [installation and configuration](#installation-and-configuration) has been completed, lets start the systemd services.
+After [installation and configuration](#installation-and-configuration) has been completed, let's start the systemd services.
 
 Starting the controller and agent on the main node (**laptop**):
 
@@ -75,15 +79,17 @@ Once the services are up and running, the journald logs on the **laptop** should
 
 ```bash
 $ journalctl -u bluechi-controller
-
-Sep 14 14:51:58 laptop systemd[1]: Started BlueChi systemd service controller daemon.
-Sep 01 14:51:58 laptop bluechi[3750775]: 2023-09-14 14:51:58,685+0200 INFO        ../src/controller/controller.c:924 controller_start        msg="Starting bluechi 0.7.0"
-Sep 01 14:51:58 laptop bluechi[3750775]: 2023-09-14 14:51:58,928+0200 INFO        ../src/controller/node.c:870 node_method_register    msg="Registered managed node from fd 8 as 'laptop'"
-Sep 01 14:52:02 laptop bluechi[3750775]: 2023-09-14 14:52:02,534+0200 INFO        ../src/controller/node.c:870 node_method_register    msg="Registered managed node from fd 9 as 'pi'"
+Dec 18 08:03:03 localhost systemd[1]: Started BlueChi Controller systemd service
+Dec 18 08:03:03 localhost bluechi-controller[680]: Starting bluechi-controller 0.10.0-0
+Dec 17 16:13:43 localhost bluechi-controller[2539]: Waiting for connection requests on port 842...
+Dec 17 16:13:43 localhost bluechi-controller[2539]: Waiting for connection requests on socket /run/bluechi/bluechi.sock...
+Dec 18 08:03:03 localhost bluechi-controller[680]: Heartbeat disabled since configured interval '0' is <=0
+Dec 18 08:03:03 localhost bluechi-controller[680]: Registered managed node from fd 9 as 'local'
+Dec 18 08:03:03 localhost bluechi-controller[680]: Registered managed node from fd 10 as 'pi'
 ...
 ```
 
-Lets use `bluechictl` on the main node to list all units:
+Let's use `bluechictl` on the main node to list all units:
 
 ```bash
 # list all units on the laptop