From 7ecb8930235e6e7ab35cae08d257a4dbf406fa7b Mon Sep 17 00:00:00 2001 From: 53hornet Date: Tue, 12 Oct 2021 21:06:30 -0400 Subject: add angelshark post, add tarpit draft --- posts/2021-10-12-altruistic-angelshark.php | 127 +++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 posts/2021-10-12-altruistic-angelshark.php (limited to 'posts') 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 @@ + + +

+ 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: Here is the GitHub to a Communication Manager automation suite. +

+ +

Background

+ +

+ 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. +

+ +

Impetus

+ +

+ 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. +

+ +

+ 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. +

+ +

OSSI: The Dark Magic Enabler

+ +

+ 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. +

+ +

Architecting Angelshark, Altrusitically

+ +

+ 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. +

+ +

+ 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. +

+ +

+ 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 curl(1), 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. +

+ +

+ 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 expect-like functionality or + automate over an interactive terminal. +

+ +

Free and Open Source

+ +

+ 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. +

+ +

+ Here's the GitHub repo where Angelshark lives. +

+ +

+ 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. +

-- cgit v1.2.3