summaryrefslogtreecommitdiff
path: root/posts/2021-10-12-altruistic-angelshark.php
blob: b516d4b166a859fd5b10ba773629756a66b8f431 (plain) (blame)
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
<?php
$title = "Altruistic Angelshark";
if (isset($early) && $early) {
	return;
}
include($_SERVER['DOCUMENT_ROOT'] . '/includes/head.php');
?>

<p class="description">
	I finally got the opportunity to release a long-term project from work online
	as free and open-source software. Woohoo! It's called Altruistic Angelshark
	and here's what it's about.

	TLDR: <a href="https://github.com/adpllc/altruistic-angelshark">Here is the GitHub to a Communication Manager automation suite</a>.
</p>

<h2>Background</h2>

<p>
	Altruistic Angelshark is an automation library, command-line application, and
	HTTP web service for more easily performing CRUD operations on Avaya
	Communication Managers. If you're not from the world of voice/telephony IT,
	you should probably know the ACMs use a Precambrian mainframe interactive
	terminal interface to create, modify, and remove stations, extensions,
	hunt-groups, etc. Your only other choice is a graphical, also interactive,
	user interface that can perform bulk operations and generate reports in the
	form of Excel spreadsheets.
</p>

<h2>Impetus</h2>

<p>
	Neither the interactive, VT220-style terminal nor the GUI application (Avaya
	Site Administration) are very easy to work with. When I say that I mean
	they're not easy to automate over. At our company, it's important for us to be
	able to automatically clean up old stations in bulk, as an example. Or
	sometimes we want to automatically run audits on possible malformed data and
	even fix those entries when they're found. The terminal requires a user's
	input to constantly paginate through data, or tab through form fields to
	insert a new entity. The GUI is worse. While it does let you automatically run
	certain reports to extract useful data, it has to be running to do it. That
	means a dedicated Windows server, and not a headless one. It's also prone to crashing.
</p>

<p>
	Another issue with the tools available to us is we run more than one ACM at
	our company (about a dozen). The interactive terminal and GUI are only good for
	running one operation or "command" on one ACM at a time. This makes it
	annoying to, for example, search for a particular user's extension on all of
	the ACMs if you don't know which one it's on. In a worst-case scenario, that
	means logging into 12 different servers and running the same command.
</p>

<h2>OSSI: The Dark Magic Enabler</h2>

<p>
	Long story short, there's a proprietary protocol called OSSI. This protocol is
	the backbone of ASA, the GUI app. It's a terminal interface, but it's for
	machine reading and writing instead of interactive use. If you packet sniff
	ASA you can learn a lot about how it's getting its data and the different
	things you can use the OSSI terminal for. However, no documentation was made
	available to us on OSSI because Avaya guards it pretty closely. So, I had to
	improvise. We already had some knowledgable architects who knew a trick or
	two. There were also a couple of useful forums available online that gave us
	more information. Eventually I figured out enough to replicate 99% of what we
	were doing in ASA. Maybe more on that another time.
</p>

<h2>Architecting Angelshark, Altrusitically</h2>

<p>
	Angelshark can do anything ASA can do by reading and writing to an OSSI
	terminal over an SSH connection. It works on top of the SSH2 library, so you
	don't need an SSH client installed. It can also run commands on one or more
	ACMs at a time. All of your logins are stored in a config file.
</p>

<p>
	Angelshark's functionality is exposed in a couple of different forms. First,
	there's a command-line interface, which lets you write commands on STDIN, runs
	them on the ACMs they're intended for, and then writes their output on STDOUT.
	It can also automatically parse the output into JSON, CSV, or TSV. This is
	nice for quickly building Excel reports like ASA.
</p>

<p>
	Even better though (I think) is the Angelshark Daemon. This runs Angelshark
	as an HTTP service, listening for incoming requests. You can submit the same
	kinds of commands and which ACMs you want them to run on as JSON POSTs. It
	feeds those to a runner, which executes commands just like the CLI app. It then
	feeds the results back to you over JSON. You can use this functionality from
	the browser, in a script with <code>curl(1)</code>, or from pretty much
	anything that can make HTTP requests. The logins are all in a config file with
	the same format as the CLI. To speed things up, commands on separate ACMs are
	run in parallel. That way your output only takes as long as the longest running
	ACM.
</p>

<p>
	There are a couple of relevant projects that I found online which do something
	similar but don't take it quite as far. They either send OSSI commands from a
	file over an SSH client with <code>expect</code>-like functionality or
	automate over an interactive terminal.
</p>

<h2>Free and Open Source</h2>

<p>
	I got to thinking that this would be a great project to let other developers
	worldwide use. If it's helpful to us it's got to be helpful to someone else
	out there. I pitched the idea of open-sourcing Angelshark to management and
	they were a mix of enthusiastic and indifferent. "Sure, sounds fine," they
	said as long as nothing internal to the company be divulged with the project.
</p>

<p>
	<a href="https://github.com/adpllc/altruistic-angelshark">Here's the GitHub repo where Angelshark lives.</a>
</p>

<p>
	I'm pretty proud of this project. It's not a very large project, but that's one of the things I'm proud of. It went through a couple of iterations, and with each I actually ended up removing code that wasn't being used to solve the primary problem. It's the first time I've gotten the chance to release an internal project as FOSS and I'm super stoked. Hopefully someone else will benefit from its release. Maybe I'll delve into its inner workings in another post sometime.
</p>