REGISTRATION_ACL_FAILED error in IA log: cause and resolution

I've run into this error a handful of times and it confuses me each time because I never write down why it happens and what to do about it. Except this time. The circle has broken, I'm writing about what this error means, and what you can do about it. Or more actually, what you can ask someone to do about it. 

tl;dr: Open a support ticket to allow your IA to connect. 

The What:

This error occurs (generally) on new Integration Agent installs when you finally have all your settings figured out and configured properly and you have a pile of handfuls of hair as proof you've been working on installing the IA for a good while. Everything else has been pretty obvious, missing file here, invalid password there, but  REGISTRATION_ACL_FAILED! is rather not terribly informative but you realize it is preventing anything from going through your IA on to xMatters. 

The Why:

Essentially, this message is saying your IA hasn't been added to the access control list (ACL) by xMatters, so access is being denied. This is an added level of security in the security onion at xMatters. 

The How:

An xMatters support representative will need to add the Agent ID to the list of allowed agents. To make this happen:

1. Get the Agent ID, then
2. Create an xMatters support request.  Provide the Agent ID and ask for it to be added to the ACL.

To get the Agent ID:

1. Open a command window and navigate to <IAHome>/bin
2. Start the IA using the start_console executable. Starting the agent should take only a few seconds.
3. Use the `./iadmin get-status` command. This will interrogate the IA, and the output will include the Agent ID. For example:

[user@my-ia-host bin]$ ./iadmin.sh get-status
Version: 5.1.5 r81524
Release date: Mar 20, 2015
Agent started: Aug 30, 2015 6:25:39 PM
Agent ID: my-ia-host/111.11.11.111:8081

Integration Services:
... (lots of content omitted)

[user@my-ia-host bin]$