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.

If you already have a packaged version of ctrlproxy installed, you can skip this chapter.

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-2.5.tar.gz
ctrlproxy-2.5/AUTHORS
...

If you wish to use the bleeding-edge version of ctrlproxy, you can download the sources from CVS.

$ cvs -d :pserver:anonymous@cvs.vernstok.nl:/cvs login

$ cvs -d :pserver:anonymous@cvs.vernstok.nl:/cvs co -r UNSTABLE ctrlproxy
ctrlproxy
ctrlproxy/AUTHORS
ctrlproxy/README
...

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 (get him/her to) run make install.

Contains various <plugin> elements, which each represent a plugin that can be loaded. When the autoload attribute is set, the plugin will be loaded when ctrlproxy starts.

The file attribute is required and should specify either an absolute path to a plugin or the name of a plugin in the default modules dir (something like /usr/lib/ctrlproxy).

The <plugin> element should contain plugin-specific elements. See the documentation for the individual plugins for details.

The <networks> element contains several <network> elements, each representing an IRC network.

Attributes that can be specified on a network element are:

	
	<ctrlproxy>
		<plugins>
			<plugin autoload="1" file="socket"/>
		</plugins>
		<networks>
			<network name="OPN" autoconnect="1">
				<listen>
					<ipv4 port="6667"/>
				</listen>
			</network>
		</networks>
	</ctrlproxy>
	
	

		
		<ctrlproxy>
			<networks>
				<network name="OPN">
					<channel name="#samba"/>
					<channel name="#samba-technical" autojoin="1"/>
				</network>
			</networks>
		</ctrlproxy>
		
		

	
	<ctrlproxy>
		<plugins>
			<plugin autoload="1" file="socket"/>
		</plugins>
		<networks>
			<network name="OPN" autoconnect="1">
				<servers>
					<ipv4 host="irc.freenode.net"/>
					<ipv6 host="irc.ipv6.freenode.net"/>
					<ipv4 host="irc.nl.linux.org"/>
				</servers>
			</network>
		</networks>
	</ctrlproxy>
	
	

	
	<ctrlproxy>
		<networks>
			<network name="OPN">
				<autosend>PRIVMSG nickserv :identify mysecretpassword</autosend>
				<autosend>PRIVMSG ctrlsoft :Hi! I'm using ctrlproxy!</autosend>
			</network>
		</networks>
	</ctrlproxy>
	
	

This module provides a simple interface for remote administration of ControlProxy. Commands can be executed by 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.

The following commands are supported:

Adding a new network called 'OFTC', listening for incoming connections on port 6667.

ADDNETWORK OFTC
ADDSERVER OFTC ipv4 host=irc.oftc.net
ADDLISTEN OFTC ipv4 port=6667
CONNECT OFTC

This module sets your IRC status to 'away' after you have been inactive('idle') for a certain period of time.

The following XML elements are supported:

		
		<ctrlproxy>
			<plugins>
				<plugin autoload="1" file="auto-away">
					<message time="600">I've been idle for 10 minutes, so I'm probably away. Please leave me a message. Thanks!</message>
				</plugin>
				<plugin autoload="1" file="socket"/>
			</plugins>

			<networks>
				<network name="OFTC">
					<servers><ipv4 host="irc.oftc.net"/></servers>
					<channel name="#flood.nl" autojoin="1"/>
				</network>
			</networks>
		</ctrlproxy>
	
	

Simple CTCP module that implements some basic CTCP commands. Use for this module is having CTCP support available when there is no client connected that can answer CTCP queries and providing the ability to detect ctrlproxy.

The following CTCP commands are supported:

Module that logs IRC data to the specified file in the same format that the irssi(1) IRC client uses.

Each channel or nick gets it's own seperate log file, which is located in a directory with the name of the IRC network.

The following XML elements are supported:

		
		<ctrlproxy>
			<plugins>
				<plugin autoload="1" file="log_irssi">
					<logfile>/home/jelmer/log/ctrlproxy</logfile>
				</plugin>
				<plugin autoload="1" file="socket"/>
			</plugins>

			<networks>
				<network name="OFTC">
					<servers><ipv4 host="irc.oftc.net"/></servers>
					<channel name="#flood"/>
				</network>
			</networks>
		</ctrlproxy>
		
	

Sends all messages to a new client that were sent since the last time the user wrote something.

The messages are stored in memory.

This module provides support for connecting to remote servers using IPv4, IPv6 and unix pipes, as well as listening for client connections using these connection types.

As this module is currently the only module providing connection support, it is essential for basic use of ctrlproxy.

Connecting or listening using SSL over IPv4 or IPv6 is supported when a SSL library was found at configure time.

When acting as a SSL server (e.g. waiting for connections from clients and communicating with them using SSL), ctrlproxy needs to have a certificate file and a private key file. This can be generated using the mksslcert.sh script distributed with ctrlproxy.

The following XML elements are supported:

After this module is loaded, the following three new elements are supported in <listen> and <servers>:

ipv4 and ipv6 support the following attributes:

When connecting, the pipe element can contain one member element <path> and several <arg> elements. These should contain a program with arguments to execute.

In listen mode, a file attribute (attribute, not element!) should be specified, containing the file name of the unix socket to create. If no file name is specified, one will be generated.

		
		<ctrlproxy>
			<plugins>
				<plugin autoload="1" file="socket">
					<sslcertfile>ctrlproxy.pem</sslcertfile>
					<sslkeyfile>ctrlproxy.pem</sslkeyfile>
				</plugin>
			</plugins>
			<networks>
				<network name="BEE">
					<servers>
						<pipe>
							<path>/usr/sbin/bitlbee</path>
						</pipe>
						<ipv4 host="localhost"/>
					</servers>
					<listen>
						<ipv4 ssl="1" port="6667"/>
				</network>
				<network name="DSR">
					<servers>
						<ipv6 host="irc.ipv6.distributed.net"/>
						<ipv4 host="irc.distributed.net" port="994" ssl="1"/>
					</servers>
					<listen>
						<ipv4 port="6668"/>
						<ipv6 port="6669" ssl="1"/>
					</listen>
				</network>
			</networks>
		</ctrlproxy>
	
	

This module sends all ctrlproxy log files to all connected clients using IRC NOTICE's.

Currently only messages from the main ctrlproxy process will be send as NOTICE's. Messages from plugins will be ignored.

This module keeps track of the number of times a certain expression is used and stores that data in a TDB-file. This TDB file can be read later with the printstats utility.

Expressions should be Perl-compatible regexes whenever pcre is found, normal regular expressions when only the POSIX regex functions are found. If no regex functionality was found, just 'plain' text should be specified.

The following XML elements are supported:

		
		<ctrlproxy>
			<plugin autoload="1" file="stats">
				<tdbfile>/home/jelmer/.ctrlproxy-stats.tdb</tdbfile>
				<pattern type="happy">[:;]([-]*)[\)D]</pattern>
				<pattern type="unhappy">[:;]([-]*)[\/\(]</pattern>
				<pattern type="foul">(shit|damn|fuck)</pattern>
				<pattern type="question">\?([^ ]*)$</pattern>
				<pattern type="exclamation">!([^ ]*)$</pattern>
				<pattern type="lines">(.*)</pattern>
				<pattern type="word">([^ ]+)</pattern>
				<pattern type="caps">^([^a-z]+)$</pattern>
				<pattern type="action">.ACTION .</pattern>
				<pattern type="violent">.ACTION .*(mept|slaat|kickt|kicks|duwt|slaps)</pattern>
			</plugin>
			<plugin autoload="1" file="socket"/>
	</plugins>
	<networks>
		<network autoconnect="1">
			<servers><ipv4 host="irc.freenode.net"/></servers>
			<channel name="#flood" autojoin="1"/>
		</network>
	</networks>
	</ctrlproxy>
	

One problem with ctrlproxy's multi-client support is the fact that when one client does a query (such as a WHOIS), all other clients get the answer. This module fixes that problem.

The following queries are intercepted by this module:

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:

Each type of line also has some variables of it's own that it substitutes.

The following XML elements are supported:

		
		<ctrlproxy>
			<plugins>
				<plugin autoload="1" file="log_custom">
					<logfile>/home/jelmer/log/ctrlproxy/%@</logfile>
					<join>%h%M%s -!- User %n [%u] has joined %c</join>
					<part>%h%M%s -!- User %n [%u] has left %c [%m]</part>
					<quit>%h%M%s -!- User %n [%u] has quit [%m]</quit>
					<action>%h%M%s * %n %m</action>
				</plugin>
				<plugin autoload="1" file="socket"/>
			</plugins>

			<networks>
				<network name="OFTC">
					<servers><ipv4 host="irc.oftc.net"/></servers>
					<channel name="#flood"/>
				</network>
			</networks>
		</ctrlproxy>
		
	

This module takes care of registration with NickServ and ghosting older connections.

		
		<ctrlproxy>
			<plugins>
				<plugin autoload="1" file="nickserv"/>
				<plugin autoload="1" file="socket"/>
			</plugins>

			<networks>
				<network name="OFTC">
					<servers><ipv4 host="irc.oftc.net"/></servers>
					<channel name="#flood.nl" autojoin="1"/>
					<nickserv>
						<nick name="foo" password="secret"/>
					</nickserv>
				</network>
			</networks>
		</ctrlproxy>
	
	

This module makes sure at most 1 message is sent to the server in a certain period of time.

A child element of a server element named "queue_speed" contains the number of milliseconds the client has to wait before sending a new message.

		
		<ctrlproxy>
			<plugins>
				<plugin autoload="1" file="antiflood"/>
				<plugin autoload="1" file="socket"/>
			</plugins>

			<networks>
				<network name="OFTC">
					<queuespeed>2200</queuespeed>
					<servers><ipv4 host="irc.oftc.net"/></servers>
					<channel name="#flood"/>
				</network>
			</networks>
		</ctrlproxy>
		
	

A module is in fact a shared library that's loaded at run-time, when the program is already running. The .so file can compiled with a command like:

$ gcc -shared -o foo.so input1.c input2.o input3.c
	

A message handling function is a function that is called whenever ctrlproxy receives an IRC message. The only argument this function should have would be a line struct.

Flags can be set on the line (the field in the struct to use is called 'options') to influence the handling of the packet by the rest of ctrlproxy. At the time of writing, the following two flags are available:

There is one other option that can be specified, but is only useful when sending your own messages:

...
add_filter("my_module", my_message_handler);
...
	

static gboolean my_message_handler(struct line *l);
	

Ctrlproxy uses GLib's logging functions. Read the related section in the GLib documentation for details.

The default replication function (default_replicate_function) of ctrlproxy is very basic. It only makes sure the client knows on which channels the user is, but does not do any replication of the messages that have been received.

To use your own replicate function instead, set the function pointer replicate_function to your replicate function.

The prototype for a replicate function is:

	void replicatef(struct network *s, struct transport_context *c);
	

The replication data should be sent to the specified transport_context.

This section covers everything related to the current (known) state information of the network the user is on.

struct nick {
	char *name;
	char mode;
};

struct channel {
	xmlNodePtr xmlConf;
	char *topic;
	char mode; 
	char *modes[255];
	char introduced;
	long limit;
	char *key;
	GList *nicks;
};

struct channel *find_channel(struct network *st, char *name);
	

struct nick *find_nick(struct channel *c, char *name);
	

GSList *gen_replication(struct network *s);
	

void default_replicate_function (struct network *, struct transport_context *);
extern void (*replicate_function) (struct network *, struct transport_context *);
	

extern GList *networks;
extern xmlNodePtr xmlNode_networks, xmlNode_plugins;
extern GList *plugins;
extern xmlDocPtr configuration;
extern GHookList data_hook; 

Pointers to various useful varables. The xmlNode_* variables point to the <networks> and <plugins> elements in the rc file.

configuration points to the top level XML document.

data_hook can be used to register a function that should be called whenever ctrlproxy receives or sends IRC messages.

plugins and networks contain lists to all “struct plugin”s and “struct network”s, respectively.

void network_add_listen(struct network *, xmlNodePtr);
	

void save_configuration();
	

void load_plugin(xmlNodePtr);
	

void unload_plugin(struct plugin *);
	

struct transport;
struct transport_context;

void register_transport(struct transport *);

struct transport_context *transport_connect(const char *name, xmlNodePtr p, receive_handler, disconnect_handler, void *data);

struct transport_context *transport_listen(const char *name, xmlNodePtr p, newclient_handler, void *data);

void transport_free(struct transport_context *);

int transport_write(struct transport_context *, char *l);

void transport_set_disconnect_handler(struct transport_context *, disconnect_handler);
typedef void (*disconnect_handler) (struct transport_context *, void *data);

void transport_set_receive_handler(struct transport_context *, receive_handler);
typedef void (*receive_handler) (struct transport_context *, char *l, void *data);

typedef void (*newclient_handler) (struct transport_context *, struct transport_context *, void *data);
void transport_set_newclient_handler(struct transport_context *, newclient_handler);

void transport_set_data(struct transport_context *, void *);

These functions all have to do with manipulating line structs. Pretty much all internal functions of ctrlproxy work with these instead of manipulating plain strings.

struct line {
	enum data_direction direction;
	int options;
	struct network *network;
	struct client *client;
	const char *origin;
	char **args; /* NULL terminated */
	size_t argc;
};

/* for the options fields */
#define LINE_IS_PRIVATE      1 
#define LINE_DONT_SEND       2 
#define LINE_STOP_PROCESSING 4

enum data_direction { UNKNOWN = 0, TO_SERVER = 1, FROM_SERVER = 2 };

struct line *linedup(struct line *l);

struct line * irc_parse_line(char *data);

struct line * virc_parse_line(char *origin, va_list ap);
struct line *irc_parse_line_args( char *origin, ... );
gboolean irc_send_args(struct transport_context *, ...);

char *irc_line_string(struct line *l);
char *irc_line_string_nl(struct line *l);

char *line_get_nick(struct line *l);

void free_line(struct line *l);

gboolean irc_sendf(struct transport_context *, char *fmt, ...);
struct line *irc_parse_linef( char *fmt, ... );

int irc_send_line(struct transport_context *, struct line *l);

void clients_send(struct network *, struct line *, struct transport_context *exception);

The following struct is passed to all transport functions.

struct transport_context {
	struct transport *functions;
	xmlNodePtr configuration;
	void *data;
	void *caller_data;
	disconnect_handler on_disconnect;
	receive_handler on_receive;
	newclient_handler on_new_client;
};

The configuration xmlNodePtr contains configuration for this specific instance of the transport. The data pointer can be used by the transport to store instance-specific data. The three 'handler' functions should be called whenever one of these events occur. Please note that you have to check for available data yourself. See the documentation about the main context in GLib for details on registering polling and idle functions.

A transport struct should contain function pointers to the following functions:

Each of the function pointers listed above can be set to NULL, to indicate that the function is not implemented.

The following callbacks, which are listed in transport_context should be called by your transport. The “data” argument in all of these calls should be the “callerdata” member field of the struct transport_context.