From 8ef115201cdf1803f44de5a67807b232c9ace961 Mon Sep 17 00:00:00 2001 From: Michael Engel Date: Fri, 18 Oct 2024 15:53:49 +0200 Subject: [PATCH] Added new bluechi-is-online package and man page Relates to: https://github.com/eclipse-bluechi/bluechi/issues/962 Signed-off-by: Michael Engel --- bluechi.spec.in | 52 +++++++++++++++++++++ doc/docs/man/bluechi-is-online.md | 2 + doc/man/bluechi-is-online.1.md | 78 +++++++++++++++++++++++++++++++ doc/man/meson.build | 1 + src/is-online/meson.build | 2 +- 5 files changed, 134 insertions(+), 1 deletion(-) create mode 100644 doc/docs/man/bluechi-is-online.md create mode 100644 doc/man/bluechi-is-online.1.md diff --git a/bluechi.spec.in b/bluechi.spec.in index e09716f072..b942f347a8 100644 --- a/bluechi.spec.in +++ b/bluechi.spec.in @@ -40,6 +40,10 @@ predefined number of nodes and with a focus on highly regulated environment such as those requiring functional safety (for example in cars). +########################## +### bluechi-controller ### +########################## + %package controller Summary: BlueChi service controller Requires: systemd @@ -90,6 +94,10 @@ This package contains the controller service. %{_unitdir}/bluechi-controller.socket +##################### +### bluechi-agent ### +##################### + %package agent Summary: BlueChi service controller agent Requires: systemd @@ -140,6 +148,10 @@ This package contains the node agent. %{_userunitdir}/bluechi-dep@.service +####################### +### bluechi-selinux ### +####################### + %package selinux Summary: BlueChi SELinux policy BuildArch: noarch @@ -180,6 +192,10 @@ if [ $1 -eq 0 ]; then fi +################### +### bluechi-ctl ### +################### + %package ctl Summary: BlueChi service controller command line tool Requires: %{name} = %{version}-%{release} @@ -204,6 +220,37 @@ This package contains the service controller command line tool. %{_mandir}/man1/bluechictl.* +######################### +### bluechi-is-online ### +######################### + +%package is-online +Summary: Command line tool to monitor the connection state of BlueChi's components +Recommends: bluechi-controller = %{version}-%{release} +Recommends: bluechi-agent = %{version}-%{release} + +%if 0%{?with_coverage} +Requires: bluechi-coverage = %{version}-%{release} +%endif + +%description is-online +BlueChi is a systemd service controller for multi-nodes environements with a +predefined number of nodes and with a focus on highly regulated environment +such as those requiring functional safety (for example in cars). +This package contains a command line tool for checking and monitoring the +connection state of BlueChi's core components. + +%files is-online +%doc README.md +%license LICENSE +%{_bindir}/bluechi-is-online +%{_mandir}/man1/bluechi-is-online.* + + +####################### +### python3-bluechi ### +####################### + %if %{with_python} %package -n python3-bluechi Summary: Python bindings for BlueChi @@ -228,6 +275,10 @@ API description and manually written code to simplify recurring tasks. %endif +######################## +### bluechi-coverage ### +######################## + %if 0%{?with_coverage} %package coverage Summary: Code coverage files for BlueChi @@ -244,6 +295,7 @@ will be used during integration tests when creating code coverage report. %endif + %prep %autosetup -S git_am diff --git a/doc/docs/man/bluechi-is-online.md b/doc/docs/man/bluechi-is-online.md new file mode 100644 index 0000000000..2baaaa6a78 --- /dev/null +++ b/doc/docs/man/bluechi-is-online.md @@ -0,0 +1,2 @@ + +--8<-- "man/bluechi-is-online.1.md:2" diff --git a/doc/man/bluechi-is-online.1.md b/doc/man/bluechi-is-online.1.md new file mode 100644 index 0000000000..f36fa2b884 --- /dev/null +++ b/doc/man/bluechi-is-online.1.md @@ -0,0 +1,78 @@ +% bluechi-is-online 1 + +## NAME + +bluechi-is-online - Command line tool to check and monitor the connection state of BlueChi's core components. + +## SYNOPSIS + +**bluechi-is-online** [*system|node|agent*] [*options*] + +## DESCRIPTION + +Eclipse BlueChi™ is a systemd service controller intended for multi-node environment with a predefined number of nodes and with a focus on highly regulated environment such as those requiring functional safety (for example in cars). + +`bluechi-is-online` is a command line tool to check and monitor the connection state of BlueChi's core components. It uses the public D-Bus API provided by `bluechi-controller` and/or `bluechi-agent`. + +**bluechi-is-online [OPTIONS]** + +## OPTIONS + +#### **--help**, **-h** + +Print usage statement and exit. + +#### **--version**, **-v** + +Print current bluechictl version + +## Commands + +### **bluechi-is-online** *system* [*options*] + +Checks the connection state of `bluechi-controller` and all expected `bluechi-agent`s. Runs on primary node. +Uses the D-Bus property `Status` of the `org.eclipse.bluechi.Controller` interface. +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`. + +**--monitor** +If set, `bluechi-is-online` continuously monitors the system state after the initial `up` check succeeded. + +### **bluechi-is-online** *node* [*node_name*] [*options*] + +Checks the connection state of a specific node. Runs on primary node. +Uses the D-Bus property `Status` of the `org.eclipse.bluechi.Node` interface. +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`. + +**--monitor** +If set, `bluechi-is-online` continuously monitors the node state after the initial `online` check succeeded. + +### **bluechi-is-online** *agent* [*options*] + +Checks the connection state of the `bluechi-agent` with the controller. Runs on any managed node. +Uses the D-Bus property `Status` of the `org.eclipse.bluechi.Agent` interface. +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`. + +**--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. + +## Exit Codes + +If the respective BlueChi component is online at the time of exiting, 0 is returned. Otherwise, 1 is returned. diff --git a/doc/man/meson.build b/doc/man/meson.build index 2396998966..199b2255bb 100644 --- a/doc/man/meson.build +++ b/doc/man/meson.build @@ -15,6 +15,7 @@ man1 = [ 'bluechi-agent', 'bluechictl', 'bluechi-proxy', + 'bluechi-is-online', ] man5 = [ diff --git a/src/is-online/meson.build b/src/is-online/meson.build index a8764fb600..7cf7a3b670 100644 --- a/src/is-online/meson.build +++ b/src/is-online/meson.build @@ -24,4 +24,4 @@ executable( ) # build test binaries -# subdir('test') +# subdir('test')