Added new bluechi-is-online package and man page

Relates to: eclipse-bluechi#962

Signed-off-by: Michael Engel <[email protected]>

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}/[email protected]
 
 
+#######################
+### 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
 

doc/docs/man/bluechi-is-online.md

@@ -0,0 +1,2 @@
+<!-- markdownlint-disable-file MD041 -->
+--8<-- "man/bluechi-is-online.1.md:2"

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.

doc/man/meson.build

@@ -15,6 +15,7 @@ man1 = [
   'bluechi-agent',
   'bluechictl',
   'bluechi-proxy',
+  'bluechi-is-online',
 ]
 
 man5 = [

src/is-online/meson.build

@@ -24,4 +24,4 @@ executable(
 )
 
 # build test binaries
-# subdir('test')
+# subdir('test')