diff --git a/README.md b/README.md index e701981..1bab34d 100644 --- 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] +Usage: sc [options] 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] 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 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 index ae3a5f1..1b93e01 100644 --- a/man/MAN.md +++ b/man/MAN.md @@ -2,25 +2,7 @@ sc - a tool for managing configured services and applications # SYNOPSIS -`sc [options] ` -``` - 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] ` # 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,13 +113,17 @@ The performance information support (`perfinfo`) has additional requirements, in   --[@ThePrez](https://github.com/ThePrez/), creator of Service Commander # OPTIONS + +Usage of the command is summarized as: ``` -sc [options] +Usage: sc [options] + 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) @@ -128,20 +131,19 @@ sc [options] 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 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 +``` diff --git a/man/man.mansrc b/man/man.mansrc index 9af0393..2c81656 100644 --- a/man/man.mansrc +++ b/man/man.mansrc @@ -3,28 +3,7 @@ sc \- a tool for managing configured services and applications .SH SYNOPSIS .PP -\f[C]sc\ \ [options]\ \ \f[] -.IP -.nf -\f[C] -\ \ \ \ 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 -\f[] -.fi +\f[C]sc\ \ [options]\ \ \f[] .SH DESCRIPTION .PP Service Commander, a utility for unifying the daunting task of managing various services and applications running on IBM i. @@ -63,27 +42,6 @@ Kafka, Zookeeper, ActiveMQ servers, etc .PD .IP \[bu] 2 Jenkins -.SS Basic usage -.PP -This tool currently requires you to define any services of interest in \f[C]\&.yaml\f[] files. -These files can be stored in any of the following locations: -.IP \[bu] 2 -A global directory (/QOpenSys/etc/sc/services) -.PD 0 -.P -.PD -.IP \[bu] 2 -A user\-specific directory($HOME/.sc/services) -.PD 0 -.P -.PD -.IP \[bu] 2 -If defined, whatever the value of the \f[C]services.dir\f[] system property is. -.PD 0 -.P -.PD -The file name must be in the format of \f[C]service_name.yaml\f[], where \[lq]service_name\[rq] is the \[lq]simple name\[rq] of the service as to be used with this tool's CLI. -The service name must consist of only lowercase letters, hyphens, and underscores. .SS Current features .PP Some of the features of the tool include: @@ -121,6 +79,11 @@ 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 +.PD 0 +.P +.PD +.IP \[bu] 2 +Ability to define manage ad hoc services specified on the command line .SS Important differences from other service management tools .PP Service Commander's design is fundamentally different from other tools that accomplish similar tasks, like init.d, supervisord, and so on. @@ -149,6 +112,74 @@ A known limitation, therefore, is that Service Commander may mistake another job For example, if you configure a service that is supposed to be listening on port 80, Service Commander will assume that any job listening on port 80 is indeed that service. .PP Service Commander's unique design is intended to offer a great deal of flexibility and ease of management through the use of simple \f[C]\&.yaml\f[] files. +.SS Configuring services through YAML configuration files +.PP +This tool allows you to define any services of interest in \f[C]\&.yaml\f[] files. +These files can be stored in any of the following locations: +.IP \[bu] 2 +A global directory (/QOpenSys/etc/sc/services) +.PD 0 +.P +.PD +.IP \[bu] 2 +A user\-specific directory($HOME/.sc/services) +.PD 0 +.P +.PD +.IP \[bu] 2 +If defined, whatever the value of the \f[C]services.dir\f[] system property is. +.PD 0 +.P +.PD +The file name must be in the format of \f[C]service_name.yaml\f[] (or \f[C]service_name.yml\f[]), where \[lq]service_name\[rq] is the \[lq]simple name\[rq] 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. +.SS Ad hoc service definition +.PP +Ad hoc services can be specified on the sc command line in the format \f[C]job:jobname\f[] or \f[C]port:portname\f[]. +.PD 0 +.P +.PD +In these instances, the operations will be performed on the specified jobs. +This is determined by looking for +.PD 0 +.P +.PD +jobs matching the given job name or listening on the given port. +The job name can be specified either in +.PD 0 +.P +.PD +\f[C]jobname\f[] or \f[C]subsystem/jobname\f[] format. +.PP +If an existing service definition is found (configured via YAML, as in the preceding section) that matches the +.PD 0 +.P +.PD +job name or port criteria, that service will be used. +For instance, if you have a service configured to run on +.PD 0 +.P +.PD +port 80, then specifying \f[C]sc\ info\ port:80\f[] will show information about the service configured to run on port 80. +.PP +Ad hoc service definition is useful for quick checks without the need to create a YAML definition. +It's also +.PD 0 +.P +.PD +useful if you do not recall the service name, but remember the job name or port. +.PP +It is also useful for cases where you just want to find out who (if anyone) is using a certain port. +For instance, +.PD 0 +.P +.PD +\f[C]sc\ jobinfo\ port:8080\f[] will show you which job is listening on port 8080. +Similarly, \f[C]sc\ stop\ port:8080\f[] will kill +.PD 0 +.P +.PD +whatever job is running on port 8080. .SS Sample .yaml configuration files .PP See the directory for some sample service definitions. @@ -286,15 +317,19 @@ IBM i 7.1 (and earlier): not supported .PP \ \[em]\@ThePrez (https://github.com/ThePrez/), creator of Service Commander .SH OPTIONS +.PP +Usage of the command is summarized as: .IP .nf \f[C] -sc\ \ [options]\ \ +Usage:\ sc\ \ [options]\ \ + \ \ \ \ 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) @@ -302,29 +337,19 @@ sc\ \ [options]\ \ \ \ \ \ \ \ \ \ 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\ \ 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") \f[] .fi -.PP -Usage of the command is summarized as: -.IP -.nf -\f[C] -\f[] -.fi -.PP -The above usage assumes the program is installed with the above installation steps and is therefore -.PD 0 -.P -.PD -launched with the \f[C]sc\f[] script. -Otherwise, if you've hand\-built with maven (\f[C]mvn\ compile\f[]), -.PD 0 -.P -.PD -you can specify arguments in \f[C]exec.args\f[] (for instance, \f[C]mvn\ exec:java\ \-Dexec.args=\[aq]start\ kafka\[aq]\f[]). .SH Automatically restarting a service if it fails .PP Currently, this tool doees not have built\-in monitoring and restart capabilities. @@ -404,3 +429,19 @@ List all services sc\ list\ group:all \f[] .fi +.PP +List jobs running on port 8080 +.IP +.nf +\f[C] +sc\ jobinfo\ port:8080 +\f[] +.fi +.PP +Stop jobs running on port 8080 +.IP +.nf +\f[C] +sc\ stop\ port:8080 +\f[] +.fi