Ports on a PaaS: Running an IRC Bouncer on Stackato

 In case you missed it, ZNC is now available on the Stackato App Store along with the source code on Github. ZNC is a feature rich IRC bouncer written in C++. This sample application shows off Harbor, Stackato's port forwarding service.

What is an IRC Bouncer?

An IRC bouncer is a proxy between an IRC client and its destination network. This design solves a problem often faced by many IRC users-- persistence. When you’re not actively connected to the server, you’ll miss all messaging activity that happened. This is the problem IRC bouncers like ZNC and services like IRCCloud are meant to solve. An IRC bouncer, however, will remain connected to the server and log the messages so that you can reattach to the IRC bouncer and replay the messages you missed.

Deploying ZNC on Stackato

Running ZNC on Stackato is easy, just press "Deploy App" from the App Store, or if using the command line just run 'stackato push'. The app has already been set up with the web admin module, an initial admin user, and some basic configuration.

One setting that you can configure is called a listener, a port which ZNC listens on. In a given ZNC configuration more than one listener may be defined, each allowing for a different protocol. In our configuration of ZNC we use a dual listener setup. Stackato is able to achieve this multi-port behavior thanks to the Harbor service introduced by Stackato 2.8 in early 2013. One listener uses the HTTP(S) port assigned to an application by default and the other listens on the port provisioned by the Harbor service. Then using ZNC's AllowWeb and AllowIRC listener directives we can restrict the network traffic type for each port.

Harbor

The Harbor service allows provisioning of additional ports to applications. It then maintains a mapping of those ports so traffic can be relayed to and from the associated applications, similar to the Stackato router. Where Harbor differs is in the type of traffic it can communicate. The router only supports TCP traffic over HTTP(S). Harbor is capable of routing both TCP and UDP traffic with, or without, any protocol. Meaning arbitrary bits may be forwarded through a port managed by Harbor.

Provisioning a Harbor service for our ZNC app is done by simply including the following snippet in the manifest.yml file:

applications:
- name: znc
...
services:
  ${name}-port:
    type: harbor
...

${name}-port

The `${name}-port` portion assigns a name to this instance of the Harbor service and uses the key substituion feature (available in both manifest.yml and stackato.yml) as part of its syntax. When evaluated, this equates to "znc-port" being the name of the provisioned Harbor service instance.

A Harbor service has two ports associated with it, an internal and external port. The internal port is used by apps binding to the service directly, whereas the external port is used for all external communication. In our configuration, the Harbor port is used to listen for IRC traffic. This means that when we connect to the IRC bouncer using a client, we specify the external port as part of the address.

More information can be found in the Harbor documentation, available from both an end-user and admin perspective.

Using ZNC

The following example uses XChat as the IRC client and assumes ZNC has been deployed to http://znc.stackato-5wtk.local on a local Stackato VM. (you can replace this with the hostname of your own ZNC instance on Stackato).

1. Navigate to http://znc.stackato-5wtk.local/ where you’ll find the web interface.

2. Login with username "admin" and password "stackato".

3. Select "Your Settings" and add a new Network.

Assign a name (e.g. myFreenode) to the network and provide the address of the server the IRC bouncer will connect to. Our IRC bouncer will be connecting to Freenode for this example.

Save the network information. When you are redirected back to the user page you will now see the network added.

4."Edit" the network and add a new channel.

Specify a channel on the network to connect to (e.g. #test).

5. Open XChat and add the ZNC instance as a new network. A network named "ZNC" is created in this case.

Set the network address as the same one that is running the ZNC instance and the port value as the external Harbor port. Next select "Connect to selected server only" and deselect the "Use global user information" option. Pass in $user/$network:$password as the server password (e.g. admin/myFreenode:stackato).

The external Harbor port and hostname are made available to the application through environment variables and can be found using the web console or command line interface. When using the command line run the `stackato service znc-port` command. If using the web console, navigate to your application's page and select "Services", "znc-port", then "Credentials".

6. Connect to the ZNC network. It should automatically join the #test channel on Freenode

7. Disconnect your client from the IRC bouncer. Wait a bit for messages to be exchanged by others. During the wait, read more great ActiveState blogs. When you reconnect to the IRC bouncer, a replay of the messages that you’ve missed will be shown.

Conclusion

And that’s how you can run ZNC on Stackato. Run your own ZNC IRC Bouncer now by downloading Stackato and never miss the action on IRC again. To learn more about other features specific to ZNC visit their wiki.