diff --git a/doc/docs/ansible/index.md b/doc/docs/tools/ansible.md similarity index 98% rename from doc/docs/ansible/index.md rename to doc/docs/tools/ansible.md index c12190ba8a..11d716b357 100644 --- a/doc/docs/ansible/index.md +++ b/doc/docs/tools/ansible.md @@ -1,5 +1,5 @@ -# 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 new file mode 100644 index 0000000000..391ca1f3f2 --- /dev/null +++ b/doc/docs/tools/bluechi-is-online.md @@ -0,0 +1,61 @@ + + +# 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 index f36fa2b884..d9fa481f7d 100644 --- 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 index 41790bb57d..970ff475bc 100644 --- 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