1 files changed, 127 insertions, 0 deletions
diff --git a/posts/2021-10-12-altruistic-angelshark.php b/posts/2021-10-12-altruistic-angelshark.php
new file mode 100644
index 0000000..b0602ef
--- /dev/null
+++ b/posts/2021-10-12-altruistic-angelshark.php
@@ -0,0 +1,127 @@
+<?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>