Configuring Adapters

In order to connect your Hubot to an actual chat server, you need to configure an adapter. You have already encountered the default shell adapter when you ran bin/hubot to get the text prompt. Now we will look through most of available adapters and learn to configure them.

Choosing The Chat Service

If you’re in a stage of making a decision which chat service should you choose for your DevOps Chat, the following table may help you make the right choice.

First, let’s find out how to connect to your favorite chat service, and then we will put everything together into a deployable, bulletproof solution.

You should know that you have to register a user for Hubot for the service you want to use. This book does not cover chat service account registrations. IRC is an exception, where only a nickname is enough, yet you still can register it so nobody else can take it.

Campfire

If you’re wondering where is Campfire’s free plan - as of the writing of this book it was hidden - you had to start a basic 30-day trial and then go to Account page and downgrade your plan to Free.

Campfire is the native habitat of Hubot - it has a built in adapter and perfect integration. When registering an account for your Hubot, don’t worry that hubot username is taken, your bot will respond to whatever alias you give it.

To get Hubot on Campfire room, first create a regular user account for it, then run bin/hubot -a campfire and provide three environmental variables:

• HUBOT_CAMPFIRE_ACCOUNT - Your account name that appears in URL. I’ve registered Hubotorium, and my chat URL is https://hubotorium.campfirenow.com, therefore account is hubotorium.
• HUBOT_CAMPFIRE_TOKEN - API authentication token that you can find in your account info. You can find it by clicking My info, it looks like this: 3a5c1b47dd76db2e950fce12ac62d4f555a17961.
• HUBOT_CAMPFIRE_ROOMS - comma separated list of room IDs you want Hubot to join. You can find out your room id by entering it in your browser, it appears in the url: https://hubotorium.campfirenow.com/room/585163 - it’s the number 585163 in my case. If there are two rooms, you would list them like this: 585163,585164

We can use your first-hubot instance to go to Campfire right away.

hubot@botserv:~/first-hubot$ HUBOT_CAMPFIRE_ACCOUNT=hubotorium \  HUBOT_CAMPFIRE_TOKEN=3a5c1b47dd76db2e950fce12ac62d4f555a17961 \  HUBOT_CAMPFIRE_ROOMS=585163,585164 \  bin/hubot --adapter campfire --name hubot 

Your bot should join the rooms right away. If it doesn’t here are a couple of tips for troubleshooting problems.

Troubleshooting

If you provide bad HUBOT_CAMPFIRE_ACCOUNT, the error looks like this:

ERROR Campfire HTTPS status code: 404 ERROR Campfire HTTPS response data: 

Bad HUBOT_CAMPFIRE_ROOMS will give you this:

ERROR Campfire HTTPS status code: 404 ERROR Campfire HTTPS response data: ERROR Campfire error on room 58516: Access Denied User ERROR Streaming connection closed for room 58516. :( 

And incorrect HUBOT_CAMPFIRE_TOKEN will show no signs of error, but Hubot will simply not appear in your chatrooms.

HipChat

Before proceeding, log in to HipChat with your bot’s user and set the @mention name to @hubot in account settings. HipChat adapter ignores the name setting you provide when starting Hubot, instead it reacts to whatever the @mention name is.

HipChat adapter requires a couple of extra system dependencies, so make sure you install them first. Do it with sudo or as root.

root@botserv:~# apt-get install libexpat1-dev libicu-dev 

Then, back as hubot user, install hubot-hipchat node module.

hubot@botserv:~/first-hubot$ npm install --save hubot-hipchat 

--save option tells npm to update package.json, you can look what was added in there.

hubot@botserv:~/first-hubot$ grep hubot-hipchat package.json     "hubot-hipchat": "~2.6.4" 

Dependencies are now settled.

There are two environmental variables you have to provide for HipChat adapter:

• HUBOT_HIPCHAT_JID - Jabber ID of Hubot’s HipChat account. You can find it in Account settings, under XMPP/Jabber info. It should look like [email protected].
• HUBOT_HIPCHAT_PASSWORD - The password of Hubot’s HipChat account.

Aditional configuration options are available, you can find them documented pretty well at .

Successful connection to HipChat should look like this:

hubot@botserv:~/first-hubot$ HUBOT_HIPCHAT_JID=[email protected] \  HUBOT_HIPCHAT_PASSWORD=MySuperSecretPassword123 \  bin/hubot -a hipchat INFO Connecting HipChat adapter... INFO Connected to hipchat.com as @hubot INFO Joining [email protected] 

Now your bot should join all rooms, say @hubot help to interact with it.

Troubleshooting

Providing incorrect HUBOT_HIPCHAT_JID or HUBOT_HIPCHAT_PASSWORD will result in Hubot hanging on the following message:

INFO Connecting HipChat adapter... 

IRC

To install IRC Hubot adapter, run:

hubot@botserv:~/first-hubot$ npm install --save hubot-irc 

It now appears in your package.json:

hubot@botserv:~/first-hubot$ grep hubot-irc package.json     "hubot-irc": "~0.1.24" 

Configuration is done using the following environmental variables:

• HUBOT_IRC_SERVER - IRC server address, i.e.: irc.freenode.net
• HUBOT_IRC_PORT - IRC server port number
• HUBOT_IRC_ROOMS - comma separated list of IRC channels to join, i.e.: #hubotorium,#hubot
• HUBOT_IRC_NICK - IRC nickname for your bot
• HUBOT_IRC_USESSL - Set to true to use SSL encryption. You really want that.
• HUBOT_IRC_SERVER_FAKE_SSL - Set to true if you use private server with self signed SSL certificate.
• HUBOT_IRC_UNFLOOD - When set to true, Hubot will throttle it’s messages, so IRC server doesn’t kick it out for flooding.

More configuration options are described in .

To connect to Freenode using SSL, you would have to do this:

hubot@botserv:~/first-hubot$ HUBOT_IRC_SERVER=irc.freenode.net \  HUBOT_IRC_PORT=6697 \  HUBOT_IRC_ROOMS="#hubotorium" \  HUBOT_IRC_NICK=hubot5000 \  HUBOT_IRC_UNFLOOD=true \  HUBOT_IRC_USESSL=true \  bin/hubot --adapter irc hubot5000 has joined #hubotorium hubot5000 has joined #hubot 

You can use tab completion to call your Hubot:

<spajus> hubot5000, the rules <hubot5000> 1. A robot may not injure a human being or, through inaction, all\ ow a human being to come to harm. <hubot5000> 2. A robot must obey any orders given to it by human beings, exce\ pt where such orders would conflict with the First Law. <hubot5000> 3. A robot must protect its own existence as long as such protect\ ion does not conflict with the First or Second Law. 

Troubleshooting

IRC adapter is hard to troubleshoot, since it gives no output if something goes wrong and just hangs indefinitely. You have to make sure server host and port are defined correctly, and the nickname you are trying to use is not taken by anyone.

XMPP/Jabber

The XMPP/Jabber adapter has the same prerequirements as HipChat adapter - use sudo or root user to install the dependencies. You can also use it to connect to , and it will work better than their own native adapter.

root@botserv:~# apt-get install libexpat1-dev libicu-dev 

Then install hubot-xmpp node module.

hubot@botserv:~/first-hubot$ npm install --save hubot-xmpp 

Check if it was added to your package.json:

hubot@botserv:~/first-hubot$ grep hubot-xmpp package.json     "hubot-xmpp": "~0.1.8" 

These are the environmental variables you may need to set:

• HUBOT_XMPP_HOST - hostname of XMPP server. Can be an IP address, or a domain name.
• HUBOT_XMPP_PORT - XMPP server port. Usually 5222.
• HUBOT_XMPP_USERNAME - bot username in user@server format.
• HUBOT_XMPP_ROOMS - comma separated list of rooms, in [email protected] format.

More options are documented at .

Let’s run it.

hubot@botserv:~/first-hubot$ HUBOT_XMPP_USERNAME="hubot@botserv" \  HUBOT_XMPP_PASSWORD="SuperSecret123" \  HUBOT_XMPP_ROOMS="[email protected],[email protected]" \  HUBOT_XMPP_HOST="127.0.0.1" \  HUBOT_XMPP_PORT=5222 \  bin/hubot --adapter xmpp --name hubot INFO { username: 'hubot@botserv',   password: '********',   host: '127.0.0.1',   port: '5222',   rooms:    [ { jid: '[email protected]', password: false },      { jid: '[email protected]', password: false } ],   keepaliveInterval: 30000,   legacySSL: undefined,   preferredSaslMechanism: undefined } INFO Hubot XMPP client online INFO Hubot XMPP sent initial presence 

Hubot should now join your chatrooms. You can use tab completion to give commands:

(11:35:42 AM) hubot entered the room. (11:35:58 AM) spajus: hubot ping (11:35:58 AM) hubot: PONG 

XMPP adapter allows giving a different name to your hubot, use --name <name> to do so.

Troubleshooting

If you use Openfire XMPP server, you will have to disable TLS security, current version of hubot-xmpp does not play well with it. To do that, go to Openfire administration panel, “Server Settings” -> “Security Settings” and in “Client Connection Security” section click “Custom” and set “Old SSL method” and “TLS method” to Not Available.

If you set wrong HUBOT_XMPP_HOST or HUBOT_XMPP_PORT, you will see Reconnect in 0 looping in Hubot’s output.

Incorrect HUBOT_XMPP_USERNAME or HUBOT_XMPP_PASSWORD will give you this:

ERROR XMPP authentication failure 

If you don’t set a correct room name, i.e. skip the trailing @conference.server, you will get this:

ERROR [xmpp error][<presence to="hubot@botserv/e1b17544" from="fun/hubot" typ\ e="error" xmlns:stream="http://etherx.jabber.org/streams"><error code="404" t\ ype="cancel"><remote-server-not-found xmlns="urn:ietf:params:xml:ns:xmpp-stan\ zas"/></error></presence>] 

Slack

is becoming increasingly popular lately. It is similar to HipChat, but has more lively interface and a bunch of integrations. You can also use it for free with limited number of integrations and history limit of 10,000 lines.

Troubles With Official Integration

There is an official Hubot integration via adapter, but you may find it rather unusable for several reasons:

• It communicates with Hubot over HTTP endpoint, meaning you have to expose your server’s open port to public, and there is no way to whitelist Slack’s IP range, because they’re running on Amazon’s AWS. That’s a red flag for those who care about their security.
• When Hubot is offline, Slack notices that it’s HTTP endpoint is not responding and automatically disables the integration. You will have to reenable it manually. This becomes very annoying, since Slack flips the switch even when Hubot is restarting.
• With official Slack Hubot integration, Hubot cannot be invited to join private channels and cannot be talked to directly via private message.

We will not waste our time setting up the official integration, but will move on directly to the good stuff.

Slack Over XMPP

Fortunately, Slack allows you to enable XMPP and IRC access to your team chat, and Hubot’s XMPP adapter works like a charm. Using Slack’s Administrator account, go to “Account” -> “Administration” -> “Settings” -> “Gateways”, check Enable XMPP gateway (SSL only) and click Save Settings.

Next, log in with your Hubot user, go to “Account” -> “Your Team” -> “Gateways” and look for “Getting Started: XMPP”. It will contain the details about your XMPP client configuration. Refer to “XMPP/Jabber” section above to install and configure hubot-xmpp adapter, and then feed it with Slack’s configuration. Here is an example for “yourteam”:

HUBOT_XMPP_USERNAME="[email protected]" HUBOT_XMPP_PASSWORD="yourteam.avUFcpc3G7N0Ot1pOV10" HUBOT_XMPP_ROOMS="[email protected],\ [email protected]" HUBOT_XMPP_HOST="yourteam.xmpp.slack.com" HUBOT_XMPP_PORT=5222 

This works perfectly and has no limitations whatsoever.

Skype

I’ve been running headless Skype with Hubot for over a year, and I assure you - if you choose this path, it will be hell. Skype will randomly loose connection with Hubot, randomly crash, hang in a loop and eat up CPU for no reason, Hubot will sometimes refuse to answer, you will experience lag and delays, and guys in Redmond will probably send every command you type directly to the NSA. I have tried multiple times to switch our company chat to something better, but people were too attached to it, so I was carrying this burden, until we finally switched to Slack. Boy did my life get easier. But if you really, really want (or rather are forced) to run Hubot on Skype, here goes nothing.

Installing Headless Skype

Instructions for installing Skype usually vary among different Linux distributions and Skype versions, so you should try finding the latest information. Debian has a decent .

I had to do this to get Skype on Debian Wheezy:

root@botserv:~# dpkg --add-architecture i386 root@botserv:~# apt-get update root@botserv:~# wget -O skype-install.deb http://www.skype.com/go/getskype-li\ nux-deb root@botserv:~# dpkg -i skype-install.deb root@botserv:~# apt-get -f install # Fix missing dependencies 

Then we have to install some more tools to run Skype in headless environment:

root@botserv:~# apt-get install xvfb screen x11vnc 

Start your headless Skype with hubot user in a detached screen:

hubot@botserv:~$ screen -d -m -S Skype xvfb-run -n 0 -s "-screen 0 800x600x16\ " /usr/bin/skype 

Now, the tricky part. SSH into your server with port forwarding, become hubot user, find headless Skype’s Xauthority file and start x11vnc on display :0, like this:

spajus@unbound:~$ ssh [email protected] -L 5900:localhost:5900 spajus@botserv:~$ sudo su - hubot hubot@botserv:~$ ps auxwwww | grep auth hubot     7453  0.0  0.9  75852  9392 pts/1    S+   Jan05   0:00 Xvfb :0 -scr\ een 0 800x600x16 -nolisten tcp -auth /tmp/xvfb-run.gZi7Bq/Xauthority hubot@botserv:~$ x11vnc -auth /tmp/xvfb-run.gZi7Bq/Xauthority -display :0 

Now you can use any VNC client from your computer to connect to localhost:5900 and control the headless Skype. You will have to do everything manually - log in, add contacts, get added to desired group chats. Keep the VNC window open, we’re not done yet.

Installing Skype Adapter

You don’t want to install this adapter from default packages, because it will most probably be outdated. Instead install it directly from GitHub.

hubot@botserv:~/first-hubot$ npm install --save https://github.com/netpro2k/h\ ubot-skype/tarball/master 

Check if it was added to your package.json:

hubot@botserv:~/first-hubot$ grep hubot-skype package.json     "hubot-skype": "https://github.com/netpro2k/hubot-skype/tarball/master" 

Now you have to install Skype4Py Python bindings for this adapter to work.

root@botserv:~# apt-get install python-pip root@botserv:~# pip install Skype4Py 

First Run with Skype

You will probably need to find the path to Xauthority file that was used by Xvfb to start headless Skype. In the example it’s /tmp/xvfb-run.gZi7Bq/Xauthority.

hubot@botserv:~$ ps auxwwww | grep auth hubot     7453  0.0  0.9  75852  9392 pts/1    S+   Jan05   0:00 Xvfb :0 -scr\ een 0 800x600x16 -nolisten tcp -auth /tmp/xvfb-run.gZi7Bq/Xauthority 

Run Hubot Skype for the first time, while keeping an eye on your VNC window.

hubot@botserv:~/first-hubot$ XAUTHORITY=/tmp/xvfb-run.gZi7Bq/Xauthority \  DISPLAY=:0 \  bin/hubot --adapter skype --name hubot 

In VNC a popup telling that “Another program wants to use Skype” will appear. Make sure you tick “Remember this selection” and allow it.

You should now be able to chat with your bot.

Tomas Varaneckas: hubot ping Hubot: PONG 

Troubleshooting

There are many things that can go wrong with this. Most notable are XAUTHORITY and DISPLAY settings. Make sure you have provided correct values, otherwise you will get this message:

Skype4Py.errors.SkypeAPIError: Could not open XDisplay 

Sometimes Hubot will stop responding, and it’s output will show “Lost connection to Skype”. Restarting Hubot alone will probably not help, so you will have to kill the existing instance of skype and start a fresh one, then start Hubot after 10 or 20 seconds. If you will try to start Hubot too early, it will fail to connect to Skype.

When it comes to scripting, you will run into trouble of determining the room name of your personal and group chats. Include in hubot-scripts.json and query the room name using hubot room info. You will learn more about including scripts in next chapter.

Tomas Varaneckas: hubot room info Hubot: This room is: #tomas.varaneckas/$hubot5000;4c1bd379c8db7f51 

You would have to provide #tomas.varaneckas/$hubot5000;4c1bd379c8db7f51 for a room name if you wanted Hubot to output something in there.