# `angelsharkd` This program listens for HTTP requests. It accepts OSSI commands in JSON format and returns OSSI output in JSON format. Below are examples of how to use the available endpoints. ## `GET /` Current Running Version Returns the current running version of Angelshark. ``` GET / ``` ```json 200 OK { "daemon_version": "0.1.0" } ``` ## `POST /ossi` Run OSSI Command(s) 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": ["", "..."], "command": "", "fields": ["", "..."], "datas": ["", "..."] } ``` 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": "", "command": "", "fields": ["", "..."], "datas": [["", "..."], "..."], "error": "" } ] ``` Here are some examples. ```json POST / ossi[ { "acms": ["CM01"], "command": "list stat 17571230000" } ] ``` ```json 200 OK [ { "acm": "CM01", "command": "list stat 17571230000", "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": "" } ] ``` ```json POST / ossi[ { "acms": ["CM01"], "command": "cha stat 17571230000", "fields": ["8003ff00"], "datas": ["Carpenter, Adam T."] } ] ``` ```json 200 OK [ { "acm": "CM01", "command": "cha stat 17571230009", "fields": [], "datas": [[]], "error": "" } ] ``` ### `?panicky=true` Query Parameter for Error Handling This endpoint accepts a 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. ```json POST / ossi[ { "acms": ["fake"], "command": "list stat" } ] ``` ```json 200 OK [] ``` ```json POST /ossi?panicky=true [ { "acms": ["fake"], "command": "list stat" } ] ``` ```json 500 Internal Server Error { "reason": "Failed to open TCP stream to host. Make sure the config is correct and the host is otherwise reachable." } ``` ### `?no_cache=true` Query Parameter to Disable Caching By default, all responses are stored in a timed cache for thirty minutes. If you wish to bypass the cache (such as to validate the results of a recent change command), you can pass `?no_cache=true` as a query string parameter. Query parameters may be combined (ex. `?no_cache=true&panicky=true`). ## Configuration `angelsharkd` can be configured with a variety of environment variables set at runtime. - `ANGELSHARKD_ORIGIN`: origin for CORS preflight requests. This is required in release (not debug) mode. - `ANGELSHARKD_DEBUG`: enables debug mode. Extra logs will be written out and CORS will be turned off. - `ANGELSHARKD_LOGINS`: override ACM logins file from `./asa.cfg`. - `ANGELSHARKD_ADDR`: override socket address to listen on. Takes the format `127.0.0.1:8080`. ## Login Configuration TODO: ## Logging `angelsharkd` continuously writes logs to STDERR. In debug mode, additional, potentially sensitive information is also logged, including request parameters.