stigkj / arson Goto Github PK

Arson is a gateway between 37signals' Campfire (
http://campfirenow.com/ ) and your own Jabber server, where campfire
rooms appear as MUC (multi-user chat) rooms.

Optionally, you can then use bitlbee and an IRC client to get all
your campfire in your IRC client.

Various bits of this were taken from various tutorials around the
web, but no more than a line or two from any of them has been left
untouched, so everything in here is Public Domain.

Arson will almost certainly be updated exactly enough to meet my
needs, and no further; feel free to send a pull request if you want
to add a feature.

Arson is written in Ruby.

          Requirements
          ------------

Gems
----
  
  sudo gem install broach
  sudo gem install daemons
  sudo gem install yajl-ruby
  sudo gem install xmpp4r

Other
-----

To follow the instructions below to the letter, you will need an
ejabberd instance on localhost.  Otherwise, configuring the campfire
component on your jabber server is up to you.

          Instructions
          ------------

Basic Setup
-----------

Get the code with:

  git clone git://github.com/rlpowell/arson.git

Copy ExampleArsonConfig.rb to ArsonConfig.rb and modify
ArsonConfig.rb to your liking; there are instructions in the
comments there.  It's Ruby code, so be mindful of the syntax.

Normally, though, you should only have to change the
JabberComponentSecret, the list of user config files, and the
LogFile.

Per-User Setup
--------------

In ArsonConfig.rb is the Configs array, which is a list of file
names.  Each of those files is taken as the configuration file for an
arson user.  The server needs to be run such that it can read those
files.  Configuration is only loaded on startup.

The files are YAML, and fairly straightforward; see example_arsonrc
for details.  Copy it to ~/.arsonrc (or wherever) and change it as
you like.

ejabberd Setup
--------------

Install ejabberd on the host you'll be running arson on.

Make an account for you on ejabberd like so:

  sudo ejabberdctl register USERNAME localhost PASSWORD

Add the following to your ejabberd.cfg, in the same place as the
example ejabberd_service that should already be there (in the
"listen" section):

- ------------------------------------

  {5347, ejabberd_service, [
                            {access, all},
                            {hosts, ["campfire.localhost"],
                                    [{password, "[COMPONENT PASSWORD]"}]
                            }
                            ]},

- ------------------------------------

Also make sure the lists of "hosts" includes "localhost".

Then restart the server ("sudo ejabberdctl restart", probably).

Execution
---------

It uses the Daemon gem, so it pretends to act like a normal UNIX
daemon.

Running "ruby arson.rb" will give you the execution options.

Start with:     ruby arson.rb start
Stop  with:     ruby arson.rb stop


          bitlbee/IRC Instructions
          ------------------------

You can use arson to get access to campfire in your IRC client by
using http://www.bitlbee.org/ , which is what I wrote it for in the
first place.

Old bitlbee (1.2.3 or so)
-------------------------

Create the account in bitlbee:

  account add jabber USERNAME@localhost PASSWORD

Start it up:

  account list
  account [account number] on

Join each room; this uses the jabber room name from the config file:

  join_chat [account number] [jabber room name]@campfire.localhost

New bitlbee (3.0 or so)
-----------------------

bitlbee 3.0 is better because it doesn't screw up the capitalization.

Create the account in bitlbee:

  account add jabber USERNAME@localhost PASSWORD

Start it up:

  account 0 on

Join each room; this uses the jabber room name from the config file:

  chat add 0 [email protected]

  /join #testing

Nick Issues
-----------

As of this writing (22 Feb 2011) there are issues with bitlbee 3.0.1
such that all the nicks in a Jabber MUC get lowercased.  In fact,
Jabber MUCs of the style that arson creates (non-anonymous) may not
work at all.  There's a bitlbee variable called "lcnicks" (use "help
set" to see how to set it) that should change this, but it's
ignored.

To make everything work OK, you should apply the patches at
http://bugs.bitlbee.org/bitlbee/ticket/757 and
http://bugs.bitlbee.org/bitlbee/ticket/415

          Acknowledgements & Legal
          ------------------------

This project wouldn't exist without the help of my friend Stephen
Weeks ( http://allalone.org/ ), who suggested the component solution
and explain how XMPP (aka Jabber) works to me.

I've used examples and code snippets from various places around the
web in making arson; not counting the various XEPs and RFCs, here's
an incomplete list:

  http://superjared.com/entry/new-projects/

  http://www.rubyfleebie.com/xmpp4r-a-real-world-example/

  http://www.mail-archive.com/[email protected]/msg01021.html

Having said that, none of the code I copied survives, and all the
arson code is licensed as show below.  I would appreciate
attribution, however.

Copyright (c) 2011 Robin Lee Powell

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.