diff options
author | Carpenter, Adam (CORP) <Adam.Carpenter@adp.com> | 2021-10-12 14:22:20 -0400 |
---|---|---|
committer | Carpenter, Adam (CORP) <Adam.Carpenter@adp.com> | 2021-10-12 14:22:20 -0400 |
commit | d8aa76522cc078b5784c94843be37f2875ad5966 (patch) | |
tree | bc871deb1cc7011bb2da6aa6768fd44ca4609dcc /README.md | |
parent | 816fc5d79bd9c3104363bcc8b575ad1576593260 (diff) | |
download | altruistic-angelshark-d8aa76522cc078b5784c94843be37f2875ad5966.tar.xz altruistic-angelshark-d8aa76522cc078b5784c94843be37f2875ad5966.zip |
ci: add github action, update readme
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 161 |
1 files changed, 161 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..1b66410 --- /dev/null +++ b/README.md @@ -0,0 +1,161 @@ +# Altruistic Angelshark + +[![Conventional git style](https://img.shields.io/badge/git%20style-conventional%20commit-blue)](https://conventionalcommits.org/) + +Angelshark is a collection of programs that make automating over Communication +Managers (ACMs) easier. It uses the OSSI protocol over SSH to run user commands +on one or more configurable ACMs. This functionality is exposed as a developer +library (`libangelshark`), a command line application (`angelsharkcli`), and an +HTTP daemon (`angelsharkd`). + +## Detailed User Guides + +These guides give an overview of the end-user Angelshark programs, their +capabilities, and common use cases. It assumes the user has familiarity with +using a shell and the command line. Some of the commands may be formatted for +\*nix, others for Windows. They should all be directly translatable, just make +sure you're using (for example) `./angelsharkcli` for \*nix and +`./angelsharkcli.exe` for Windows. + +- [`angelsharkcli`](angelsharkcli/README.md): a command line application for + running OSSI-formatted commands on one or more ACMs and parses the output data + into useful formats (CSV, JSON, etc.) +- [`angelsharkd`](angelsharkd/README.md): a HTTP service for running + OSSI-formatted commands formatted in JSON on one or more ACMs, by one or more + clients + +## Installation + +`angelsharkcli` is available as a prebuilt binary for many platforms in the +GitHub releases. You may also build it from scratch with +[`cargo`](https://rustup.rs): + +```sh +cargo install --path angelsharkcli +``` + +To build and install `angelsharkd`: + +```sh +cargo install --path angelsharkd +``` + +## Quick Examples + +Get the numbers and names of all stations on a single ACM via the CLI. + +```sh +$ printf 'aCM01\nclist stat\nf8005ff00\nf8003ff00\nt\n' | angelsharkcli print +17571230001 Doe, Jane +17571230002 Doe, John +17571230003 Conference Rm. 1 +``` + +Check three ACMs for a station and print it as JSON via the CLI. + +```sh +$ angelsharkcli print <<EOF +aCM01 +aCM02 +aCM03 +clist stat 17571230009 +f8005ff00 +f8003ff00 +t +EOF +angelsharkcli: ossi: error: 1 00000000 29cf No records match the specified query options +angelsharkcli: ossi: error: 1 00000000 29cf No records match the specified query options +[ + [ + "17571230009", + "Carpenter, Adam" + ] +] +``` + +Do the same thing over HTTP via `curl`. + +```sh +$ nohup angelsharkd & +nohup: ignoring input and appending output to 'nohup.out' +$ curl -X POST http://localhost:80/ossi \ + -H 'Content-Type: application/json' \ + -d '[ + { + "acms": [ "CM01", "CM02", "CM03" ], + "command": "list stat 17571230009", + "fields": ["8005ff00", "8003ff00"] + } +]' + +[ + { + "acm": "CM01", + "command": "list stat 17571230009", + "fields": [ "8005ff00", "8003ff00" ], + "datas": [ [ "17571230001", "Carpenter, Adam", ] ], + "error": "" + }, + { + "acm": "CM02", + "command": "list stat 17571230001", + "fields": [ "8005ff00", "8003ff00" ], + "datas": [ [] ], + "error": "1 00000000 29cf No records match the specified query options" + } + { + "acm": "CM03", + "command": "list stat 17571230001", + "fields": [ "8005ff00", "8003ff00" ], + "datas": [ [] ], + "error": "1 00000000 29cf No records match the specified query options" + } +] + +$ cat nohup.out +[2021-07-21T16:57:12Z INFO angelsharkd] Reading config... +[2021-07-21T16:57:12Z INFO angelsharkd] Initializing command runner... +[2021-07-21T16:57:12Z INFO angelsharkd] Starting server... +[2021-07-21T16:58:49Z INFO angelsharkd::activity_log] {"status":"200 OK","method":"POST","uri":"/ossi","commands":[{"acms":["CM01","CM02","CM03"],"command":"list stat 17571230009","fields":["8005ff00","8003ff00"],"datas":null}]} +``` + +## Why should I use Angelshark? Why might it be preferable to ASA or other projects? + +- Angelshark is cross-platform. It is available for Windows, Mac OSX, Linux, and + FreeBSD. Angelshark should run on anything that can compile it. If statically + linked, no runtime dependencies are required. +- It requires no graphical desktop to generate the same output as ASA, making it + more versatile for servers or containers. +- Angelshark executables are super-fast binaries and commands are run in + parallel across multiple ACMs to deliver output faster. +- Angelshark does not need or use waits or timeouts (such as one would see with + `expect` scripts). +- Angelshark can parse ACM output data into a variety of useful formats + including tab-delimited (TSV), CSV, and JSON. +- The command line is easily scripted with login configuration, command files, + and task schedulers such as Cron. It outputs tab-delimited data by default, + making it friendly for `sed`, `grep`, and `awk`. +- It is extensible, allowing developers to use the daemon or the library to + write their own software on top of Angelshark! +- Angelshark uses `libssh` internally and will work on platforms without an SSH + client, such as OpenSSH. + +``````plain + `r***` + _i?` .|v- + <x> ^x: + rx_ =]~ `-' + _^**^**=` -V, X]*<!~^*r* +:r*: rr**" '<*n ,nl`?#i `}~ *_ +H _r?r` (~ i"_n, l~~|? +5 `*(r` ``'_P` <` 0_ +P `*^^^^^^^^^^^>!=:,-`'-,,:=!~><<^^^^**^^^^<<~~!=:,,-'` !i H +5 `````.''-__,,,::" =.-q^*x +H :rrr>~!!==::,,,_--'.Z , y`6@= -e` r` +xr=**rr" n_ ??"!~]` !|? + .. `}r:` '(` ,Hx^^^^*- + -<***^^^^r(<H` }< + ` :(r~` '2, + `<****=` `vv + .!*^^^r` +`````` |