Added bluechi-is-online to readthedocs

Relates to: #962 Added new section for tooling, moved the ansible page to it and created bluechi-is-online page there, too. Signed-off-by: Michael Engel <[email protected]>
eclipse-bluechi · Nov 4, 2024 · 1c839d7 · 1c839d7
1 parent 536ccdd
commit 1c839d7
Show file tree

Hide file tree

Showing 4 changed files with 99 additions and 36 deletions.
diff --git a/doc/docs/ansible/index.md → doc/docs/tools/ansible.md b/doc/docs/ansible/index.md → doc/docs/tools/ansible.md
@@ -1,5 +1,5 @@
 <!-- markdownlint-disable-file MD013 MD033 -->
-# Ansible
+# Ansible Collection
 
 The BlueChi project offers an [Ansible collection](https://galaxy.ansible.com/ui/repo/published/eclipse_bluechi/bluechi/docs/) for effortless provisioning of BlueChi on systems.
 

diff --git a/doc/docs/tools/bluechi-is-online.md b/doc/docs/tools/bluechi-is-online.md
@@ -0,0 +1,61 @@
+<!-- markdownlint-disable-file MD013 MD033 MD046 -->
+
+# bluechi-is-online
+
+The BlueChi project offers with `bluechi-is-online` a CLI tool for checking and monitoring the connection state of BlueChi components in the system. It can be wrapped in systemd units so that other units can be started or stopped based on the connection state.
+
+!!! Note
+
+    For more information please refer to the [man page of bluechi-is-online](../man/bluechi-is-online.md).
+
+## Install bluechi-is-online on CentOS
+
+```bash
+sudo dnf install bluechi-is-online
+```
+
+## Verify Installation
+
+You can verify that the CLI tool has been installed by:
+
+```bash
+$ bluechi-is-online help
+bluechi-is-online checks and monitors the connection state of BlueChi components
+...
+```
+
+## Usage example
+
+=== "Stop service(s) when bluechi-agent loses connection"
+
+    ```bash
+    $ cat /etc/systemd/system/monitor-bluechi-agent.service
+    [Unit]
+    Description=Monitor bluechi-agents connection to controller
+
+    [Service]
+    Type=simple
+    ExecStart=/usr/local/bin/bluechi-is-online agent --wait=2000 --switch-timeout=2000 --monitor
+
+    $ cat /etc/systemd/system/workload.service
+    [Unit]
+    Description=Some workload that should stop running when bluechi-agent disconnects
+    BindsTo=monitor-bluechi-agent.service
+    After=monitor-bluechi-agent.service
+
+    [Service]
+    ...
+    ```
+
+=== "Start service(s) when bluechi-agent loses connection"
+
+    ```bash
+    $ cat /etc/systemd/system/handle-bluechi-agent-offline.service
+    [Unit]
+    Description=Handle BlueChi Agent going offline and start take-action.service
+    OnFailure=take-action.service
+
+    [Service]
+    Type=simple
+    ExecStart=/usr/local/bin/bluechi-is-online agent --wait=2000 --switch-timeout=2000 --monitor
+    ```
diff --git a/doc/man/bluechi-is-online.1.md b/doc/man/bluechi-is-online.1.md
@@ -37,7 +37,7 @@ If the `Status` is `up`, exit code is 0. Otherwise 1.
 **Options:**
 
 **--wait**
-Initial time in milliseconds to wait till the expected system status is `up`.
+Initial time in milliseconds to wait until the expected system status is `up`.
 
 **--monitor**
 If set, `bluechi-is-online` continuously monitors the system state after the initial `up` check succeeded.
@@ -51,7 +51,7 @@ If the `Status` is `online`, exit code is 0. Otherwise 1.
 **Options:**
 
 **--wait**
-Initial time in milliseconds to wait till the expected node status is `online`.
+Initial time in milliseconds to wait until the expected node status is `online`.
 
 **--monitor**
 If set, `bluechi-is-online` continuously monitors the node state after the initial `online` check succeeded.
@@ -65,13 +65,13 @@ If the `Status` is `online`, exit code is 0. Otherwise 1.
 **Options:**
 
 **--wait**
-Initial time in milliseconds to wait till the expected agent status is `online`.
+Initial time in milliseconds to wait until the expected agent status is `online`.
 
 **--monitor**
 If set, `bluechi-is-online` continuously monitors the agent state after the initial `online` check succeeded.
 
 **--switch-timeout**
-Time to wait till the agent is expected to connect again on a call to the `SwitchController` API method. In milliseconds.
+Time to wait until the agent is expected to connect again on a call to the `SwitchController` API method. In milliseconds.
 
 ## Exit Codes
 

diff --git a/doc/mkdocs.yml b/doc/mkdocs.yml
@@ -9,41 +9,43 @@ nav:
   - Home: index.md
   - Architecture: architecture.md
   - Getting Started:
-    - Installation: getting_started/installation.md
-    - Single Node Setup: getting_started/single_node.md
-    - Multi-Node Setup: getting_started/multi_node.md
-    - Using bluechictl: getting_started/examples_bluechictl.md
-    - Cross-node dependencies: getting_started/cross_node_dependencies.md
+      - Installation: getting_started/installation.md
+      - Single Node Setup: getting_started/single_node.md
+      - Multi-Node Setup: getting_started/multi_node.md
+      - Using bluechictl: getting_started/examples_bluechictl.md
+      - Cross-node dependencies: getting_started/cross_node_dependencies.md
   - BlueChi's API:
-    - Description: api/description.md
-    - Using the D-Bus API: api/examples.md
-    - Generating clients: api/client_generation.md
+      - Description: api/description.md
+      - Using the D-Bus API: api/examples.md
+      - Generating clients: api/client_generation.md
   - Monitoring:
-    - monitoring/index.md
-    - Peer Listener: monitoring/peers.md
+      - monitoring/index.md
+      - Peer Listener: monitoring/peers.md
   - Cross-Node Dependencies:
-    - cross_node_dependencies/index.md
-    - Proxy Services: cross_node_dependencies/proxy_services.md
-    - Using Proxy Services: cross_node_dependencies/usage.md
-  - Ansible:
-    - ansible/index.md
+      - cross_node_dependencies/index.md
+      - Proxy Services: cross_node_dependencies/proxy_services.md
+      - Using Proxy Services: cross_node_dependencies/usage.md
   - Security:
-    - security/index.md
-    - Securing connection with mTLS: security/securing_multi_node.md
-    - SELinux: security/selinux.md
+      - security/index.md
+      - Securing connection with mTLS: security/securing_multi_node.md
+      - SELinux: security/selinux.md
+  - Tooling:
+      - Ansible: tools/ansible.md
+      - bluechi-is-online: tools/bluechi-is-online.md
   - Configuration: configuration.md
   - MAN Pages:
-    - Binaries:
-      - bluechi-controller(1): man/bluechi-controller.md
-      - bluechi-agent(1): man/bluechi-agent.md
-      - bluechi-proxy(1): man/bluechi-proxy.md
-      - bluechictl(1): man/bluechictl.md
-    - Configuration:
-      - bluechi-controller.conf(5): man/bluechi-controller-conf.md
-      - bluechi-agent.conf(5): man/bluechi-agent-conf.md
-    - SELinux:
-      - bluechi-controller.selinux(8): man/bluechi-controller-selinux.md
-      - bluechi-agent.selinux(8): man/bluechi-agent-selinux.md
+      - Binaries:
+          - bluechi-controller(1): man/bluechi-controller.md
+          - bluechi-agent(1): man/bluechi-agent.md
+          - bluechi-proxy(1): man/bluechi-proxy.md
+          - bluechictl(1): man/bluechictl.md
+          - bluechi-is-online(1): man/bluechi-is-online.md
+      - Configuration:
+          - bluechi-controller.conf(5): man/bluechi-controller-conf.md
+          - bluechi-agent.conf(5): man/bluechi-agent-conf.md
+      - SELinux:
+          - bluechi-controller.selinux(8): man/bluechi-controller-selinux.md
+          - bluechi-agent.selinux(8): man/bluechi-agent-selinux.md
   - Additional Resources: resources.md
 
 theme:
@@ -72,8 +74,8 @@ markdown_extensions:
   - smarty
   - admonition
   - pymdownx.snippets:
-     base_path: ["doc"]
-     check_paths: True
+      base_path: ["doc"]
+      check_paths: True
   - pymdownx.superfences:
   - pymdownx.tabbed:
       alternate_style: true