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.
Altruistic Angelshark is an automation library, command-line application, and RESTful 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.
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 pretty crash-prone.
Another issue with the tools available to us is we run more than one ACM at our company (think > 10). 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 11 different servers and running the same command.
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.
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 methods. 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, or from pretty much
anything that can make HTTP requests. The logins are all in a config file
local to Angelshark and commands are queued. That way multiple users don't
have to share passwords and won't overload the ACMs. 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.
This second method was something that I was also interested in implementing.
In ASA you can dump terminal screenshots for an entire command's output. Some
of my team members had tools in place that relied on this. A third sub-project
of Altruistic Angelshark is asa-cli, and it does exactly that.
For any list or display command, it emulates a VT220
terminal and dumps all pages of output to STDOUT.
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.
Rust, libssh, HTTP, etc.