= 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 [[https://github.com/nicferrier/shoes-off/issues|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 [[https://github.com/nfisher/SpikyIRC|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' andshoes-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.