1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
|
# `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": ["<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.
```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
`angelsharkd` uses the same login configuration file syntax as `angelsharkcli`.
See the
[`angelsharkcli` README for more information](/angelsharkcli/README.md#login-configuration).
You can download a [sample `asa.cfg.sample`](/asa.cfg.sample) to start with.
## Logging
`angelsharkd` continuously writes logs to STDERR. In debug mode, additional,
potentially sensitive information is also logged, including request parameters.
|
