NAME

App::Bondage - A featureful IRC bouncer based on POE::Component::IRC

SYNOPSIS

my $bouncer = App::Bondage->new(
    Debug    => $debug,
    Work_dir => $work_dir,
);

DESCRIPTION

Bondage is an IRC bouncer. It acts as a proxy between multiple IRC servers and multiple IRC clients. It makes it easy to stay permanently connected to IRC. It is mostly made up of reusable components. Very little is made from scratch here. If it is, it will be made modular and reusable, probably as a POE::Component::IRC plugin. This keeps the code short and (hopefully) well tested by others.

Rationale

I wrote Bondage because no other IRC bouncer out there fit my needs. Either they were missing essential features, or they were implemented in an undesirable (if not buggy) way. I've tried to make Bondage stay out of your way and be as transparent as possible. It's supposed to be a proxy, after all.

FEATURES

Easy setup

Bondage is easy to get up and running. In the configuration file, you just have to specify the port it will listen on, the password, and some IRC server(s) you want Bondage to connect to. Everything else has sensible defaults, though you might want to use a custom nickname and pick some channels to join on connect.

Logging

Bondage can log both public and private messages for you. All log files are saved as UTF-8.

Stays connected

Bondage will reconnect to IRC when it gets disconnected or the IRC server stops responding.

Recall messages

Bondage can send you all the messages you missed since you detached, or it can send you all messages received since it connected to the IRC server, or neither. This feature is based on similar features found in miau, dircproxy, and ctrlproxy.

Auto-away

Bondage will set your status to away when no clients are attached.

Reclaim nickname

Bondage will periodically try to change to your preferred nickname if it is taken.

Flood protection

Bondage utilizes POE::Component::IRC's flood protection to ensure that you never flood yourself off the IRC server.

NickServ support

Bondage can identify with NickServ for you when needed.

Rejoins channels if kicked

Bondage can try to rejoin a channel if you get kicked from it.

Encrypted passwords

Bondage supports encrypted passwords in its configuration file for added security.

SSL support

You can connect to SSL-enabled IRC servers, and make Bondage require SSL for client connections.

IPv6 support

Bondage can connect to IPv6 IRC servers, and also listen for client connections via IPv6.

Cycles empty channels

Bondage can cycle (part and rejoin) channels for you when they become empty in order to gain ops.

CTCP replies

Bondage will reply to CTCP VERSION requests when you are offline.

CONFIGURATION

The following options are recognized in the configuration file which is called ~/.bondage/config.yml.

Global options

`listen_host`

(optional, default: "0.0.0.0")

The host that Bondage accepts connections from. This is the host you use to connect to Bondage.

`listen_port`

(required, no default)

The port Bondage binds to.

`listen_ssl`

(optional, default: false)

Set this to true if you want Bondage to require the use of SSL for client connections. You'll need to have ssl.crt and ssl.key files in Bondage's working directory. More information, see http://www.akadia.com/services/ssh_test_certificate.html

`password`

(required, no default)

The password you use to connect to Bondage. If it is 32 characters, it is assumed to be encrypted (see bondage -c);

`networks`

(required, no default)

This should contain a list of network names, each pointing to a list of relevant options as described in the following section.

networks:
  freenode:
    option1: value
    option2: value
  ircnet
    option1: value
    option2: value

Network-specific options

`bind_host`

(optional, default: "0.0.0.0")

The host that Bondage binds to and connects to IRC from. Useful if you have multiple IPs and want to choose which one to IRC from.

`server_host`

(required, no default)

The IRC server you want Bondage to connect to.

`server_port`

(optional, default: 6667)

The port on the IRC server you want to use.

`server_pass`

(optional, no default)

The IRC server password, if there is one.

`use_ssl`

(optional, default: false)

Set this to true if you want to use SSL to communicate with the IRC server.

`nickserv_pass`

(optional, no default)

Your NickServ password on the IRC network, if you have one. Bondage will identify with NickServ with this password on connect, and whenever you switch to your original nickname.

`nickname`

(optional, default: your UNIX user name)

Your IRC nick name.

`username`

(optional, default: your UNIX user name)

Your IRC user name.

`realname`

(optional, default: your UNIX real name, if any)

Your IRC real name, or email, or whatever.

`flood`

(optional, default: false)

Set to a true value to allow flooding (disables flood protection).

`channels`

(optional, no default)

A list of all your channels and their passwords.

channels:
  "chan1" : ""
  "chan2" : "password"
  "chan3" : ""

`recall_mode`

(optional, default: "missed")

How many channel messages you want Bondage to remember, and then send to you when you attach.

"missed": Bondage will only recall the channel messages you missed since the last time you detached from Bondage.

"none": Bondage will not recall any channel messages.

"all": Bondage will recall all channel messages.

Note: Bondage will always recall private messages that you missed while you were away, regardless of this option.

`log_public`

(optional, default: false)

Set to true if you want Bondage to log all your public messages. They will be saved as ~/.bondage/logs/some_network/#some_channel.log unless you set log_sortbydate to true.

`log_private`

(optional, default: false)

Set to true if you want Bondage to log all private messages. They will be saved as ~/.bondage/logs/some_network/some_nickname.log unless you set log_sortbydate to true.

`log_sortbydate`

(optional, default: false)

Set to true if you want Bondage to rotate your logs. E.g. a channel log file might look like ~/.bondage/logs/some_network/#channel/2008-01-30.log

`log_restricted`

(optional, default: false)

Set this to true if you want Bondage to restrict the read permissions on created log files/directories so other users won't be able to access them.

`log_dcc`

(optional, default: false)

Set this to true if you want Bondage to log DCC transactions.

`log_notices`

(optional, default: false)

Set this to true if you want Bondage to log NOTICEs in addition to PRIVMSGs.

`cycle_empty`

(optional, default: false)

Set to true if you want Bondage to cycle (part and rejoin) opless channels if they become empty.

`kick_rejoin`

(optional, default: false)

Set to true if you want Bondage to try to rejoin a channel (once) if you get kicked from it.

`away_poll`

(optional, default: false)

The interval, in seconds, in which to update information on channel members' away status.

Some IRC clients (e.g. xchat) periodically issue a WHO #channel to update the away status of channel members. Since Bondage caches this information and replies to such requests without contacting the IRC server, clients like xchat will not get up-to-date information about the away status. On the other hand, this saves lots of traffic if you don't care about that functionality. But if you do make use of it, set this value to, say, 300 (which is what xchat uses).

METHODS

`new`

Arguments:

'Work_dir', the working directory for the bouncer. Should include the config file. This option is required.

'Debug', set to 1 to enable debugging. Default is 0.

DEPENDENCIES

The following CPAN distributions are required:

YAML::XS
POE
POE-Component-Client-DNS
POE-Component-Daemon
POE-Component-IRC
POE-Component-SSLify (if you need SSL support)
POE-Filter-IRCD
Socket6 (if you need ipv6 support)

BUGS

Report all bugs, feature requests, etc, here: http://rt.cpan.org/Public/Dist/Display.html?Name=App%3A%3ABondage

TODO

Look into using POE::Component::Server::IRC as an intermediary for multiple clients.

Keep recall messages away from prying eyes, instead of in /tmp.

Generate QuakeNet-specific WHO replies without contacting the IRC server.

Add proper tests.

AUTHOR

Hinrik Örn Sigurðsson, hinrik.sig@gmail.com

LICENSE AND COPYRIGHT

This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

Rationale

FEATURES

Easy setup

Logging

Stays connected

Recall messages

Auto-away

Reclaim nickname

Flood protection

NickServ support

Rejoins channels if kicked

Encrypted passwords

SSL support

IPv6 support

Cycles empty channels

CTCP replies

CONFIGURATION

Global options

listen_host

listen_port

listen_ssl

password

networks

Network-specific options

bind_host

server_host

server_port

server_pass

use_ssl

nickserv_pass

nickname

username

realname

flood

channels

recall_mode

log_public

log_private

log_sortbydate

log_restricted

log_dcc

log_notices

cycle_empty

kick_rejoin

away_poll

METHODS

new

DEPENDENCIES

BUGS

TODO

AUTHOR

LICENSE AND COPYRIGHT

SEE ALSO

Module Install Instructions

`listen_host`

`listen_port`

`listen_ssl`

`password`

`networks`

`bind_host`

`server_host`

`server_port`

`server_pass`

`use_ssl`

`nickserv_pass`

`nickname`

`username`

`realname`

`flood`

`channels`

`recall_mode`

`log_public`

`log_private`

`log_sortbydate`

`log_restricted`

`log_dcc`

`log_notices`

`cycle_empty`

`kick_rejoin`

`away_poll`

`new`