Update doc with new features (#31)

* Update README * update built man page * Bump version to 0.1.0
ThePrez · Mar 17, 2021 · dd09948 · dd09948
1 parent f8806f1
commit dd09948
Show file tree

Hide file tree

Showing 3 changed files with 198 additions and 108 deletions.
diff --git a/README.md b/README.md
@@ -20,6 +20,7 @@ Some of the features of the tool include:
 - Define custom groups for your services, and perform operations on those groups (by default, a group of "all" is defined)
 - Query basic performance attributes of the services
 - Assistance in providing/managing log files. This is a best-guess only and naively assumes the service uses stdout/stderr as its logging mechanism. Service Commander has its own primitive logging system that works well only for certain types of services
+- Ability to define manage ad hoc services specified on the command line
 
 # Important differences from other service management tools
 Service Commander's design is fundamentally different from other tools that accomplish similar tasks, like init.d, supervisord, and so on. Namely, the functions within Service Commander are intended to work regardless of:
@@ -36,9 +37,9 @@ Service Commander's unique design is intended to offer a great deal of flexibili
 # Installation
 
 ## Binary distribution (untested)
-You can install the binary distribution by copying the link to the `.rpm` file from the releases page of this project and using `yum` to install it. For instance, to install the v0.0.2 release:
+You can install the binary distribution by copying the link to the `.rpm` file from the releases page of this project and using `yum` to install it. For instance, to install the v0.1.0 release:
 ```
-yum install https://github.com/ThePrez/ServiceCommander-IBMi/releases/download/v0.0.2/sc-0.0.2-0.ibmi7.2.ppc64.rpm
+yum install https://github.com/ThePrez/ServiceCommander-IBMi/releases/download/v0.0.2/sc-0.1.0-0.ibmi7.2.ppc64.rpm
 ```
 Of note, this RPM has not yet been tested. Feel free to evaluate and submit an issue if you encounter any problems.
 
@@ -72,21 +73,17 @@ The performance information support (`perfinfo`) has additional requirements, in
     - IBM i 7.1 (and earlier): not supported
 
 # Basic usage
-This tool currently requires you to define any services of interest in `.yaml` files. These files can be stored in any of the following locations:
-- A global directory (/QOpenSys/etc/sc/services)
-- A user-specific directory($HOME/.sc/services)
-- If defined, whatever the value of the `services.dir` system property is. 
-The file name must be in the format of `service_name.yaml`, where "service_name" is the "simple name" of the service as to be used with this tool's CLI. The service name must consist of only lowercase letters, hyphens, and underscores.
 
 Usage of the command is summarized as:
 ```
-Usage: sc  [options] <operation> <service or group:group_name>
+Usage: sc  [options] <operation> <service(s)>
 
     Valid options include:
         -v: verbose mode
         --disable-colors: disable colored output
         --splf: send output to *SPLF when submitting jobs to batch (instead of log)
         --sampletime=x.x: sampling time(s) when gathering performance info (default is 1)
+        --ignore-globals: ignore globally-configured services
 
     Valid operations include:
         start: start the service (and any dependencies)
@@ -98,12 +95,20 @@ Usage: sc  [options] <operation> <service or group:group_name>
         perfinfo: print basic performance info about the service
         loginfo: get log file info for the service (best guess only)
         list: print service short name and friendly name
-
+        
+    Valid formats of the <service(s)> specifier include:
+        - the short name of a configured service
+        - A special value of "all" to represent all configured services (same as "group:all")
+        - A group identifier (e.g. "group:groupname")
+        - An ad hoc service specification by port (for instance, "port:8080")
+        - An ad hoc service specification by job name (for instance, "job:ZOOKEEPER")
+        - An ad hoc service specification by subsystem and job name (for instance, "job:QHTTPSVR/ADMIN2")
 ```
 The above usage assumes the program is installed with the above installation steps and is therefore
 launched with the `sc` script. Otherwise, if you've hand-built with maven (`mvn compile`), 
 you can specify arguments in `exec.args` (for instance, `mvn exec:java -Dexec.args='start kafka'`).
 
+
 # Usage examples
 Start the service named `kafka`:
 ```
@@ -133,6 +138,40 @@ List all services
 ```
 sc list group:all
 ```
+List jobs running on port 8080
+```
+sc jobinfo port:8080
+```
+Stop jobs running on port 8080
+```
+sc stop port:8080
+```
+
+# Configuring Services
+
+## Through YAML configuration files
+This tool allows you to define any services of interest in `.yaml` files. These files can be stored in any of the following locations:
+- A global directory (/QOpenSys/etc/sc/services)
+- A user-specific directory($HOME/.sc/services)
+- If defined, whatever the value of the `services.dir` system property is. 
+The file name must be in the format of `service_name.yaml` (or `service_name.yml`), where "service_name" is the "simple name" of the service as to be used with this tool's CLI. The service name must consist of only lowercase letters, numbers, hyphens, and underscores.
+
+## Ad hoc service definition
+Ad hoc services can be specified on the sc command line in the format `job:jobname` or `port:portname`. 
+In these instances, the operations will be performed on the specified jobs. This is determined by looking for
+jobs matching the given job name or listening on the given port. The job name can be specified either in
+`jobname` or `subsystem/jobname` format.
+
+If an existing service definition is found (configured via YAML, as in the preceding section) that matches the
+job name or port criteria, that service will be used. For instance, if you have a service configured to run on
+port 80, then specifying `sc info port:80` will show information about the service configured to run on port 80.
+
+Ad hoc service definition is useful for quick checks without the need to create a YAML definition. It's also
+useful if you do not recall the service name, but remember the job name or port. 
+
+It is also useful for cases where you just want to find out who (if anyone) is using a certain port. For instance,
+`sc jobinfo port:8080` will show you which job is listening on port 8080. Similarly, `sc stop port:8080` will kill
+whatever job is running on port 8080.
 
 # Demo (video)
 [![asciicast](https://asciinema.org/a/398648.svg)](https://asciinema.org/a/398648)

diff --git a/man/MAN.md b/man/MAN.md
@@ -2,25 +2,7 @@
 sc - a tool for managing configured services and applications
 
 # SYNOPSIS
-`sc  [options] <operation> <service or group:group_name>`
-```
-    Valid options include:
-        -v: verbose mode
-        --disable-colors: disable colored output
-        --splf: send output to *SPLF when submitting jobs to batch (instead of log)
-        --sampletime=x.x: sampling time(s) when gathering performance info (default is 1)
-
-    Valid operations include:
-        start: start the service (and any dependencies)
-        stop: stop the service (and dependent services)
-        restart: restart the service
-        check: check status of the service
-        info: print configuration info about the service
-        jobinfo: print which jobs the service is running in
-        perfinfo: print basic performance info about the service
-        loginfo: get log file info for the service (best guess only)
-        list: print service short name and friendly name
-```
+`sc  [options] <operation> <service(s)>`
 
 # DESCRIPTION
 
@@ -35,14 +17,6 @@ This tool can be used to manage a number of services, for instance:
 - Kafka, Zookeeper, ActiveMQ servers, etc
 - Jenkins
 
-
-## Basic usage
-This tool currently requires you to define any services of interest in `.yaml` files. These files can be stored in any of the following locations:
-- A global directory (/QOpenSys/etc/sc/services)
-- A user-specific directory($HOME/.sc/services)
-- If defined, whatever the value of the `services.dir` system property is. 
-The file name must be in the format of `service_name.yaml`, where "service_name" is the "simple name" of the service as to be used with this tool's CLI. The service name must consist of only lowercase letters, hyphens, and underscores.
-
 ## Current features
 Some of the features of the tool include:
 - The ability to specify dependencies (for instance, if one application or service dependds on another), and it will start any dependencies as needed
@@ -52,6 +26,7 @@ Some of the features of the tool include:
 - Define custom groups for your services, and perform operations on those groups (by default, a group of "all" is defined)
 - Query basic performance attributes of the services
 - Assistance in providing/managing log files. This is a best-guess only and naively assumes the service uses stdout/stderr as its logging mechanism. Service Commander has its own primitive logging system that works well only for certain types of services
+- Ability to define manage ad hoc services specified on the command line
 
 ## Important differences from other service management tools
 Service Commander's design is fundamentally different from other tools that accomplish similar tasks, like init.d, supervisord, and so on. Namely, the functions within Service Commander are intended to work regardless of:
@@ -65,6 +40,30 @@ Instead, this tool makes strong assumptions based on checks for a particular job
 
 Service Commander's unique design is intended to offer a great deal of flexibility and ease of management through the use of simple `.yaml` files.
 
+## Configuring services through YAML configuration files
+This tool allows you to define any services of interest in `.yaml` files. These files can be stored in any of the following locations:
+- A global directory (/QOpenSys/etc/sc/services)
+- A user-specific directory($HOME/.sc/services)
+- If defined, whatever the value of the `services.dir` system property is. 
+The file name must be in the format of `service_name.yaml` (or `service_name.yml`), where "service_name" is the "simple name" of the service as to be used with this tool's CLI. The service name must consist of only lowercase letters, numbers, hyphens, and underscores.
+
+## Ad hoc service definition
+Ad hoc services can be specified on the sc command line in the format `job:jobname` or `port:portname`. 
+In these instances, the operations will be performed on the specified jobs. This is determined by looking for
+jobs matching the given job name or listening on the given port. The job name can be specified either in
+`jobname` or `subsystem/jobname` format.
+
+If an existing service definition is found (configured via YAML, as in the preceding section) that matches the
+job name or port criteria, that service will be used. For instance, if you have a service configured to run on
+port 80, then specifying `sc info port:80` will show information about the service configured to run on port 80.
+
+Ad hoc service definition is useful for quick checks without the need to create a YAML definition. It's also
+useful if you do not recall the service name, but remember the job name or port. 
+
+It is also useful for cases where you just want to find out who (if anyone) is using a certain port. For instance,
+`sc jobinfo port:8080` will show you which job is listening on port 8080. Similarly, `sc stop port:8080` will kill
+whatever job is running on port 8080.
+
 ## Sample .yaml configuration files
 See the [samples](samples) directory for some sample service definitions. 
 
@@ -114,34 +113,37 @@ The performance information support (`perfinfo`) has additional requirements, in
  &nbsp; --[@ThePrez](https://github.com/ThePrez/), creator of Service Commander
 
 # OPTIONS
+
+Usage of the command is summarized as:
 ```
-sc  [options] <operation> <service or group:group_name>
+Usage: sc  [options] <operation> <service(s)>
+
     Valid options include:
         -v: verbose mode
         --disable-colors: disable colored output
         --splf: send output to *SPLF when submitting jobs to batch (instead of log)
         --sampletime=x.x: sampling time(s) when gathering performance info (default is 1)
+        --ignore-globals: ignore globally-configured services
 
     Valid operations include:
         start: start the service (and any dependencies)
         stop: stop the service (and dependent services)
         restart: restart the service
         check: check status of the service
         info: print configuration info about the service
+        jobinfo: print which jobs the service is running in
         perfinfo: print basic performance info about the service
         loginfo: get log file info for the service (best guess only)
         list: print service short name and friendly name
+        
+    Valid formats of the <service(s)> specifier include:
+        - the short name of a configured service
+        - A group identifier (e.g. "group:groupname")
+        - An ad hoc service specification by port (for instance, "port:8080")
+        - An ad hoc service specification by job name (for instance, "job:ZOOKEEPER")
+        - An ad hoc service specification by subsystem and job name (for instance, "job:QHTTPSVR/ADMIN2")
 ```
 
-
-Usage of the command is summarized as:
-```
-```
-The above usage assumes the program is installed with the above installation steps and is therefore
-launched with the `sc` script. Otherwise, if you've hand-built with maven (`mvn compile`), 
-you can specify arguments in `exec.args` (for instance, `mvn exec:java -Dexec.args='start kafka'`).
-
-
 # Automatically restarting a service if it fails
 Currently, this tool doees not have built-in monitoring and restart capabilities. This may be a future enhancement. In the meantime, one can use simple scripting to accomplish a similar task. For instance, to check every 40 seconds and ensure that the `navigator` service is running, you could submit a job like this (replace the sleep time, service name, and submitted job name to match your use case):
 ```
@@ -181,3 +183,11 @@ List all services
 ```
 sc list group:all
 ```
+List jobs running on port 8080
+```
+sc jobinfo port:8080
+```
+Stop jobs running on port 8080
+```
+sc stop port:8080
+```