diff options
| -rw-r--r-- | README.md | 12 | ||||
| -rw-r--r-- | angelsharkcli/README.md | 107 | ||||
| -rw-r--r-- | angelsharkd/README.md | 230 | ||||
| -rw-r--r-- | asa.cfg.sample | 1 |
4 files changed, 344 insertions, 6 deletions
@@ -27,17 +27,17 @@ sure you're using (for example) `./angelsharkcli` for \*nix and ## Installation `angelsharkcli` is available as a prebuilt binary for many platforms in the -GitHub releases. You may also build it from scratch with +GitHub releases. To install `angelsharkcli` from source, use [`cargo`](https://rustup.rs): -```sh -cargo install --path angelsharkcli +``` +cargo install --git https://github.com/adpllc/altruistic-angelshark.git angelsharkcli ``` -To build and install `angelsharkd`: +To install `angelsharkd` from source: -```sh -cargo install --path angelsharkd +``` +cargo install --git https://github.com/adpllc/altruistic-angelshark.git angelsharkd ``` ## Quick Examples diff --git a/angelsharkcli/README.md b/angelsharkcli/README.md new file mode 100644 index 0000000..e314568 --- /dev/null +++ b/angelsharkcli/README.md @@ -0,0 +1,107 @@ +# `angelsharkcli` + +This program accepts OSSI-formatted commands as input and writes the results +back out to the user. Input is read from STDIN, output is written to STDOUT (if +printing is being used) and errors are written to STDERR. + +## Help + +``` +$ angelsharkcli -h +Altruistic Angelshark CLI 0.1.0 +Adam T. Carpenter <adam.carpenter@adp.com> + +Reads STDIN and parses all lines as commands to be fed to one or more ACMs. When it reaches EOF, it stops parsing and +starts executing the command(s) on the ACM(s). What it does with the output can be configured with subcommands and +flags. If you like keeping your commands in a file, consider using the `<` to read it on STDIN. The default behavior is +to run commands but print no output (for quick changes). Errors are printed on STDERR. + +USAGE: + angelsharkcli [OPTIONS] [SUBCOMMAND] + +FLAGS: + -h, --help Prints help information + -V, --version Prints version information + +OPTIONS: + -l, --login-file <config> Set ACM login configuration file [default: ./asa.cfg] + +SUBCOMMANDS: + help Prints this message or the help of the given subcommand(s) + man Prints command manual pages via `ossim` term + print Prints command output to STDOUT (or files) in a useful format + test Prints parsed logins and inputs but does not run anything +``` + +## Input Syntax + +The input syntax loosely follows that of the OSSI protocol, with one slight +modification to allow for ACM selection. One command is made up of multiple +lines and the program accepts one or more commands. Every line begins with a +single character (a, c, f, d, or t) with the following meanings. + +- `a` Signifies one or more ACM names to run the command on. Accepts multiple + values, either as tab-separated entries on the same line or as completely + separate lines, each of which must start with `a`. +- `c` The command to be run. Only one of these per terminated body of input. + Shorthands are supported. +- `f` Signifies one or more optional fields to be displayed or mutated. If you + want to limit the output of list or display commands to particular fields, you + can include them here. These are also used for change commands to specify + which fields of data are to be mutated. Accepts multiple values, either as + tab-sepaated entries on the same line or as completely separate lines, each of + which must start with `f`. +- `d` Signifies one or more data entries to be inserted into provided fields for + a change command. Accepts multiple values, either as tab-separated entries on + the same line or as completely separate lines, each of which must start with + `d`. +- `t` Is the terminator, and signifies the end of one command. Since you can + input many commands, use `t` on its own line to separate them. Every command + must end with a `t`, even if you're just sending one command. + +Example: + +```plain +aCM01 CM02 +clist station +f8003ff00 +t +``` + +Example with multiple fields and data insertion: + +```plain +aCM01 +aCM02 +ccha stat 17571230000 +f8003ff00 0031ff00 +dCarpenter, Adam +d1002 +t +``` + +## Login Configuration + +The program expects a file called 'asa.cfg' to be in the PWD at runtime. You can +change the location and name of this file with the CLI options (invoke the +program with `--help`). The syntax of this file is as follows: + +```plain +<acm name> <username>:<password>@<address>:<port> +...(repeated if desired for multiple ACMs) +``` + +The ACM name is a name you give to that login information to be provided in the +input later. It can be anything (e.g. CM11). The username and password are known +working credentials for that ACM. The address is the physical host or IP address +for that ACM. The port is the SSH port directly into SAT. The default port, if +none is provided, is 5022. + +You can download a [sample `asa.cfg.sample`](/asa.cfg.sample) to start with. + +Example: + +```plain +CM01 myuser:p@$$w0rd@10.0.0.1:5022 +CM02 myuser:p@$$w0rd@10.0.0.2:5022 +``` diff --git a/angelsharkd/README.md b/angelsharkd/README.md new file mode 100644 index 0000000..88471de --- /dev/null +++ b/angelsharkd/README.md @@ -0,0 +1,230 @@ +# `angelsharkd` + +This program listens for HTTP connections. It accepts OSSI commands in JSON +format and returns OSSI output in JSON format. Below are examples of how to use +the available endpoints. + +## Endpoints + +- `GET /` greeting and version number +- `POST /ossi` run OSSI commands + +## Running Commands via `POST /ossi` + +Runs provided command(s) on configured ACM(s) and returns the results. + +The input syntax loosely follows that of the Avaya OSSI protocol (with one +slight modification to allow for ACM specification). For more information, read +the team documentation on the protocol. + +Input is a JSON array of objects. Every one of those objects is a single command +to be run. The fields of that object determine the properties of the OSSI +command to be constructed. The fields are as follows: + +- `"acms"`: An array of one or more configured ACM names to run the command on. + Required. +- `"command"`: A string representing the command to be run. Required. +- `"fields"`: An array of field hex addresses. Optional. Used for shortening + output data entries or naming field data to be mutated. +- `"datas"`: An array of strings. For change commands, there must be as many + `datas` as `fields`. + +Request Template: + +```json +{ + "acms": [ + "<configured ACM name>", + ... + ], + "command": "<command to be run>", + "fields": [ + "<optional field hex address>", + ... + ], + "datas": [ + "<optional replacement data>", + ... + ] +} +``` + +Output is a JSON array of results. It mostly mimics the request syntax although +every element of the array is for a single command run on a single ACM. It also +accounts for errors at the OSSI level. Every object has the following fields: + +- `"acm"`: The ACM the command was run on. +- `"command"`: The command that was run. +- `"fields"`: An array of field hex addresses ordinally corresponding to the + data entries. +- `"datas"`: An array of arrays of strings. Every inner array is a single data + entry. +- `"error"`: A string. Empty if there was no error. Populated if SAT failed to + run the command. + +Response Template: + +```json +[ + { + "acm": "<ACM command was run on>", + "command": "<command that was run>", + "fields": [ + "<field hex address>", + ... + ], + "datas": [ + [ + "<entry data>", + ... + ], + ... + ], + "error": "" + } +] +``` + +Here are some examples. + +`POST /ossi` + +```json +[ + { + "acms": ["CM01"], + "command": "list stat 17571230009" + } +] +``` + +`200 OK` + +```json +[ + { + "acm": "CM01", + "command": "list stat 17571230009", + "fields": [ + "8005ff00", + "8004ff00", + "8003ff00", + "0031ff00", + "8007ff00", + "8001ff00", + "0033ff00", + "4e22ff00", + "004fff00", + "700dff00", + "6a01ff00", + "0019ff00", + "ce2aff00", + "8002ff00", + "4a3bff00", + "0032ff00" + ], + "datas": [ + [ + "17571230000", + "S9999", + "Carpenter, Adam", + "1234", + "5678", + "5", + "", + "", + "1234", + "", + "no", + "", + "", + "1", + "1", + "" + ] + ], + "error": "" + } +] +``` + +`POST /ossi` + +```json +[ + { + "acms": ["CM01"], + "command": "cha stat 17571230000", + "fields": ["8003ff00"], + "datas": ["Carpenter, Adam T."] + } +] +``` + +`200 OK` + +```json +[ + { + "acm": "CM01", + "command": "cha stat 17571230009", + "fields": [], + "datas": [[]], + "error": "" + } +] +``` + +### To Panic or Not to Panic (Query Strings) + +This endpoint accepts a single query string in the form of `?panicky=true`. By +default, any execution errors are simply filtered out of the output. This +ensures that the output is always valid OSSI JSON. If you would rather get an +error response for any Angelshark-related errors (not SAT errors), you can set +this parameter. + +More examples. + +`POST /ossi` + +```json +[ + { + "acms": ["CM01"], + "command": "list stat nonexistent" + } +] +``` + +`200 OK` + +```json +[] +``` + +`POST /ossi?panicky=true` + +```json +[ + { + "acms": ["CM01"], + "command": "list stat nonexistent" + } +] +``` + +`500 Internal Server Error` + +```plain +Unable to execute command -- ACM didn't feel like it today.... +``` + +## Login Configuration + +See [`angelshark.toml.sample`](/samples/angelshark.toml.sample) to get an idea +of how to configure `angelsharkd`. + +## Logging + +`angelsharkd` writes standard access logs to STDOUT every time it responds to a +request. Inner `libangelshark` errors may be written to STDOUT. diff --git a/asa.cfg.sample b/asa.cfg.sample new file mode 100644 index 0000000..426471f --- /dev/null +++ b/asa.cfg.sample @@ -0,0 +1 @@ +example example_user:example_pass@192.168.1.1:5022
\ No newline at end of file |