updated angelshark

1 files changed, 119 insertions, 2 deletions

diff --git a/drafts/altrustic-angelshark.html b/drafts/altrustic-angelshark.html
index f90bb86..a5e6ce6 100644
--- a/drafts/altrustic-angelshark.html
+++ b/drafts/altrustic-angelshark.html
@@ -1,2 +1,119 @@
-I finally got the chance to open source a long-term project from work and
-release it into the outside world.
+<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.
+</p>
+
+<h2>Background</h2>
+
+<p>
+  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.
+</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 pretty
+  crash-prone.
+</p>
+
+<p>
+  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.
+</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 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.
+</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</code>, 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.
+</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>
+
+<p>
+  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 <code>asa-cli</code>, and it does exactly that.
+  For any <code>list</code> or <code>display</code> command, it emulates a VT220
+  terminal and dumps all pages of output to STDOUT.
+</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>
+
+<h2>Tooling and Development</h2>
+
+<p>Rust, libssh, HTTP, etc.</p>