Shoes Off

Shoes-Off is a simple IRC bouncer written in EmacsLisp.

A bouncer is a program that runs on a remote host and provides a sort of proxy irc server. It connects to the real irc server with your nick and authentication details and let's you connect to it (with possibly no security, or different security).

This bouncer is written using rcirc to make the upstream connection.

Making it work

Install this or install from the package on marmalade.

You need to install this in the place you want a bouncer. Not on your local machine (you probably don't want a bouncer there).

Then define a config, you can customize the variable :

shoes-off-config

You can also just setq it with something like:

(setq shoes-off-config
      '((:username "bouncer-username"
         :password "bouncer-password"
         :server-alist (("irc.upstream.servername"
                         :nick "nick-at-the-irc-network"
                         :port 6667
                         :user-name "user-to-connect-to-the-irc-network"
                         :password "password-to-connect-to-the-irc-network"
                         :full-name "Full Name"
                         :channels ("#channel" "#otherchannel"))))))

Once that is done you need to start a shoes-off session. A session is the bouncer's upstream connection to the IRC.

M-x shoes-off-start-session [RET] bouncer-username [RET]

Will start the bouncer session.

Again on the bouncer, you need to start the bouncer server:

M-x shoes-off-start [RET] 6901 [RET]

6901 is a listener TCP port. It could be anything. Choose wisely.

Auto-starting the bouncer server

You can auto-start the bouncer server on session start by configuring the shoes-off-server-port variable to be the TCP port you want to start on.

Connecting to a running bouncer

To connect to the running bouncer you need to point your irc client at the port you selected and use the username and password from the shoes-off-config. Here's an rcirc example:

(rcirc-connect 
    "my-bouncer.example.org"                 ; hostname of bouncer
    6901                                     ; port you started the bouncer on
    "nick-at-the-irc-network"                ; the Nick to use (only used locally)
    "user-to-connect-to-the-irc-network"     ; the username to connect to bouncer
    "Full Name"                              ; full name (not used I think)
    '("#channel" "#otherchannel")            ; start channels (not used I think)
    "password-to-connect-to-the-irc-network"); the password to connect to bouncer

This will connect to the bouncer and everything should work.

Multiple sessions

Multiple upstream irc sessions can be bounced. This is done by specifying multiple servers in the server-alist and by connecting to services with a qualified username.

For example, give the config:

(setq shoes-off-config
      '((:username "bouncer-username"
         :password "bouncer-password"
         :server-alist 
             (("irc-one.upstream.servername"
                :nick "nick-at-the-irc-network"
                :port 6667
                :user-name "user-name-1"
                :password "password-1"
                :full-name "Full Name"
                :channels ("#channel" "#otherchannel"))
              ("irc-two.upstream.servername"
                :nick "nick-at-the-irc-network"
                :port 6667
                :user-name "user-name-2"
                :password "password-2"
                :full-name "Full Name"
                :channels ("#channelhere"))))))

You can connect to these with:

(rcirc-connect 
    "my-bouncer.example.org"                 
    6901
    "bouncer-nick"
    "bouncer-username@irc-one.upstream.servername"
    "Full Name"
    '("#channel" "#otherchannel")
    "password")

for the second one:

(rcirc-connect 
    "my-bouncer.example.org"                 
    6901
    "bouncer-nick"
    "bouncer-username@irc-two.upstream.servername"
    "Full Name"
    '("#channel" "#otherchannel")
    "password")

Unfortunately there is a bug at the moment, you can't do that exactly, you must qualify the hostnames, probably by adding host alises to your /etc/hosts file. I will find a way round this.

BUGS

Please report bugs or feature requests to GitHub.

I'm sure there are loads.

Security

WARNING this DOES expose your password to the bouncer box. I have made little attempt to secure this right now. IRC is not very secure anyway.

If you want secure IRC for your team consider SpikyIRC

FAQ

Q How does shoes-off configuration/authentication work?

A `shoes-off-start-session' is called for a user, that calls `shoes-off/get-config' with the username; this function may have a plugin implementation. It should return the username, password and server-alist for the user. The server-alist are illustrated above.

When shoes-off needs to check authentication it calls `shoes-off/auth-check' with a username-spec and a password; this function may also have a plugin implementation. If succesfull it should return a transformed name in the manner of `shoes-off/auth-check-impl'.

Different authentication systems can override the `shoes-off/get-config-plugin' and `shoes-off/auth-plugin' differently to ensure they can hold users and servers in whatever way they like.

Next steps

A lot of work needs to go into automating the startup. But alternately I may just setup a hosting service for bouncers.

Why is it called 'Shoes Off'?

Because you have to take your shoes off on a bouncey castle.

nicferrier/shoes-off