Abstract
This document is still a work-in-progress. We're doing our best to keep it up-to-date and understandable, but please don't hesitate to contact us if you have comments or questions.
All comments, questions and updates are welcome at jelmer@vernstok.nl.
Table of Contents
Table of Contents
CtrlProxy is a project I started because running irssi in screen on my server didn't work very well over high latency connections when I was away from home.
The structure of ctrlproxy is very modular and it is easily extendible.
Ctrlproxy is a so-called IRC proxy or BNC (bouncer). It keeps a permanent connection to one or more IRC servers. The user can then connect and disconnect his/her IRC client to the bouncer without actually disconnecting from the 'real' IRC server.
Connect to one server with many clients under one nick transparently
Connect to multiple servers using only one process
CTCP support when no client is attached
irssi-style logging support
Transparent detaching and attaching of clients
Password support
Replication support
Auto-Away support
Keeping track of events occuring
Direct, inetd-style interfacing with local IRC servers (such as bitlbee)
Responses to queries are only sent to the originator of the query
SSL/GNUTLS support
Table of Contents
Some distributions come with a packaged version of ctrlproxy. Wilmer van der Gaast is maintaining the Debian ctrlproxy package and Aron Griffis maintains the gentoo package of ctrlproxy.
ctrlproxy is included with the BSD ports collection.
If you already have a packaged version of ctrlproxy installed, you can skip this chapter.
CtrlProxy should run on pretty much all POSIX-compatible platforms. A version for Windows might be released in the future.
The source of ctrlproxy can be downloaded from the ctrlproxy homepage. The source files available there can be unpacked using tar and gzip:
$
tar xvgz ctrlproxy-3.0.tar.gz
ctrlproxy-3.0/AUTHORS ...
If you wish to use the bleeding-edge version of ctrlproxy, you can download the sources from Bazaar.
First, run the configure
script:
$
./configure
If this script does not detect all libraries and headers, while
they are present, specify the locations using command line arguments
to configure
. Run ./configure --help for details.
After configure
has finished, run make.
Now that ctrlproxy has been built, find your system administrator or become root yourself and run make install.
Table of Contents
CtrlProxy is configured by a set of plain-text files that
live in the .ctrlproxy
directory in the users' home
directory.
By running ctrlproxy with the <param>--init</param> argument, you can quickly create a configuration file.
gwalcmai:~%ctrlproxy --init
Please specify port the administration interface should listen on. Prepend with a colon to listen on a specific address. Example: localhost:6668 Port [6680]:6680
Please specify a password for the administration interface: Configuration created in /home/jelmer/.ctrlproxy.
Once you have created a configuration file, you can hand-edit
the files in ~/.ctrlproxy
or connect to administration
port as specified above using your IRC client and use the admin interface.
Table of Contents
Replication (short for 'backlog replication') is the system that stores certain IRC lines and then sends them to the user at a certain moment.
Additionally, there is a `BACKLOG' command available thru remote administration.
All lines that were sent after the last time you disconnected a client are stored and sent to a client that connects to ctrlproxy.
All lines that were sent after the last time you disconnected a client are stored and sent to a client that connects to ctrlproxy.
Table of Contents
CtrlProxy supports remote administration thru IRC.
Commands can be executed by either using the /CTRLPROXY command in
your IRC client or sending them to the nick
ctrlproxy
on a network.
The syntax for the commands is very simple: the command should be followed by one or arguments, seperated by spaces. Quoting is not supported. Those familiar with NickServ or ChanServ will already be used to this syntax.
The following commands are available:
Syntax:
ADDSERVER <network> <host>[:<port>] [<password>]
Example: addserver OPN irc.freenode.net:6667
Syntax:
BACKLOG [<channel>]
Without any arguments, the BACKLOG command replicates all the backlogs for the current network.
With one argument, the name of a channel, all lines on that channel are replicated.
Syntax:
CHARSET <charset>
Change the character set that ctrlproxy should expect the client to send data in.
See the output of iconv -l for a list of possible character sets.
Syntax:
CONNECT <network>
Connect to the specified network. Ctrlproxy will connect to the first known server for this network.
Syntax:
DELNETWORK <network>
Remove the specified network. The network may not be connected.
Syntax:
DISCONNECT <network>
Disconnect from the specified network.
Syntax:
LISTNETWORKS
Prints out a list of all networks ctrlproxy is connected to at the moment.
Syntax:
LOG_LEVEL [<level>]
Change log level if specified. If not specified will print the current log level.
Syntax:
NEXTSERVER [<NETWORK>]
Makes the specified network disconnect from the current server and go to the next one.
Syntax:
SAVECONFIG [<path>]
Save the (updated) configuration to the location it was loaded from (usually $HOME/.ctrlproxy/
).
Syntax:
STARTLISTENER [<address>:]<port> <password> [<network>]
Add listener on specified port
Table of Contents
CtrlProxy has various means for logging conversions to file.
By setting log_irssi_path
to a directory,
ctrlproxy will write log files to that directory in the same format
as is default in irssi.
Each channel or nick gets it's own seperate log file, which is located in a directory with the name of the IRC network.
If no directory is specified, data will be logged to $HOME/.ctrlproxy/log_irssi/$NETWORK/$CHANNEL
.
Module that writes logs to one or more files using a defined format.
This module may be used to write out log files that can be parsed by scripts or bots or logs in the same format as your favorite IRC client.
The configuration values define the syntax that is used to write out log file lines. In these configuration values, values beginning with a '%' can be substituted.
The following characters are allowed after a percent sign for all types of lines:
Current time of day, hours field.
Current time of day, number of minutes.
Current time of day, number of seconds.
Nick originating the line (saying the message, doing the kick, quitting, joining, etc).
Hostmask of the user originating the line.
Name of the current IRC network.
Name of the server (as set by the transport).
Percent sign
Substituted with the respective argument in the IRC line.
Replaced by channel name if the message is directed to a channel, the nick name to which the message is being sent, or the name of the sender of the message when the receiver is the user running ctrlproxy.
This substitute will be the name of the first channel on which the user is active if the line type is NICK or QUIT.
Each type of line also has some variables of it's own that it substitutes.
Nick of the user that is being kicked.
Channel the user is being kicked from.
Reason the user is being kicked.
Name of the channel of which the topic is being changed.
The new topic. Only set for 'topic', not for 'notopic'.
Name of user or channel of which the mode is being changed.
Change in the mode, e.g. +oie
Target of which the mode is being changed.
To retrieve any additional arguments for a MODE command,
use %1
, %2
, etc.
Name of channel or nickname of user to which the notice/privmsg/ or action is being sent.
Message that is being sent.
This chapter contains some brief information on how to configure various IRC clients for use with CtrlProxy.
All IRC clients should be able to work with ctrlproxy (ctrlproxy acts just like any other IRC server and follows the RFC's). Please contact the mailinglist if you find that a client is not working well together with ctrlproxy.
Use ctrlproxy with the listener module and run the following commands:
/set proxy_addressctrlproxy-host
/set proxy_passwordctrlproxy-password
/set use_proxy ON
and, if you're running ctrlproxy on a different port than 1080:
/set proxy_port ctrlproxy-port
Use ctrlproxy with the socks module and configure socks in xchat.
If you are using the listener module, make sure you enter a password.