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 in 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.
Rejoin channel 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.
Cycle 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 can be called ~/.bondage/config.EXT where EXT is an extension recognized by Config::Any.

listen_host

(optional, default: "0.0.0.0")

The host that Bondage> listens on and 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. More information: 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 letters, it is assumed to be encrypted (see bondage -c);

Note: The rest of the options are specific to the network block they appear in.

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.

channels

(optional, no default)

A list of all your channels and their passwords. Here's an example in YAML format:

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

recall_mode

(optional, default: "new")

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

"new": 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, and will only discard them when you leave the channel (wilfully).

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.

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.

DEPENDENCIES

The following CPAN distributions are required:

Config-Any
POE
POE-Component-Client-DNS
POE-Component-Daemon
POE-Component-IRC
POE-Component-SSLify (only if you need SSL support)
POE-Filter-IRCD
Socket6 (only 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

Exit cleanly when clients are attached.

DCC support.

Answer common client requests like WHO/MODE without asking the server, so other clients won't be bothered with unnecessary traffic.

Reload the configuration file upon being sent a SIGHUP and do something useful.

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

CONFIGURATION

DEPENDENCIES

BUGS

TODO

AUTHOR

LICENSE AND COPYRIGHT

SEE ALSO

Module Install Instructions