Description: 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.

# The ControlProxy Manual

### Jelmer Vernooij

`<jelmer@samba.org>`

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.

## Chapter 1. Introduction

## What is ctrlproxy?

Ctrlproxy is an 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.

Any conversations (or parts of them) that happen on IRC while the user is disconnected can then be sent when the user connects again or asks for them explicitly.

It is also be possible to log into CtrlProxy from multiple locations simultaneously while using one and the same nick name on IRC.

## Features

- 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

## Requirements

- GNU glib

- GNUTLS (for SSL support)

## Chapter 2. Installation

## Precompiled packages

Most Linux distributions come with a packaged version of CtrlProxy. ctrlproxy is also included in the BSD ports collection.

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

## Supported platforms

CtrlProxy should run on pretty much all POSIX-compatible platforms. A version for Windows might be released in the future.

## Obtaining the source code

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

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

### Downloading from Bazaar

Ctrlproxy Bazaar can be accessed by running:

    $ bzr get http://people.samba.org/bzr/jelmer/ctrlproxy/trunk ctrlproxy-trunk
    ...

Make sure you run the `autogen.sh` in the source directory so that the `configure` script is generated correctly.

## Compiling from source

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.

Once ctrlproxy has been built, find your system administrator or become root yourself and run make install.

## Chapter 3. Configuration

CtrlProxy is configured by a set of plain-text files that live in the `.ctrlproxy` directory in the users' home directory.

## Quick setup

By running ctrlproxy with the `--init` 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 [57000]: 57000
    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.

## Chapter 4. Replication

Replication (short for 'backlog replication') is the system that stores IRC lines and then sends them to the user once they connect to the proxy.

Additionally, there is a `BACKLOG' command available through the administration interface.

The replication setting in ctrlproxy selects what lines will be sent to the client upon connect. The following methods are available:

## Simple replication

All lines that were sent after the last time you disconnected a client are stored and sent to a client that connects to ctrlproxy.

## Since last disconnect

All lines that were sent after the last time you disconnected a client are stored and sent to a client that connects to ctrlproxy.

## Time reporting

If the `time_report` option is set to true, ctrlproxy will print the time before every message. Such messages are very useful for backlogs. That way, you can know at approximately which time lines were written.

## Chapter 5. Remote administration

CtrlProxy supports remote administration through IRC. Commands can be executed by either using the /CTRLPROXY command in your IRC client, sending them to the nick `ctrlproxy` on a network or by connecting to the admin network, which is built into CtrlProxy.

It is also possible to use this interface from the command-line on the machine where CtrlProxy is running by using the ctrlproxy-admin command.

The syntax for the commands is very simple: the command should be followed by one or arguments, separated by spaces. Quoting is not supported. Those familiar with NickServ or ChanServ will already be used to this syntax.

## Commands

The following commands are available:

## network add - Adds a new network

Syntax:

    network add <name>

Add a new network with the specified name.

## addserver - Adds a new server to the specified network.

Syntax:

    ADDSERVER <network> <host>[:<port>] [<password>]

Example: addserver OPN irc.freenode.net:6667

## backlog - Send backlog for a single channel or network.

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.

## charset - Change client charset

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.

## connect - Connect to a network

Syntax:

    CONNECT <network>

Connect to the specified network. Ctrlproxy will connect to the first known server for this network.

## network del - Delete a network

Syntax:

    network del <network>

Remove the specified network. The network may not be connected.

## die - Close ctrlproxy

Syntax:

    DIE

Disconnect all clients and servers and exit ctrlproxy.

## disconnect - Disconnect from a network

Syntax:

    DISCONNECT <network>

Disconnect from the specified network.

## detach - Detach the current client

Syntax:

    DETACH

Detach client from the proxy.

## echo - Echo specified text

Syntax:

    ECHO <text>

Repeats specified text. Useful mainly for debugging.

## network list - Print list of networks

Syntax:

    network list

Prints out a list of all networks ctrlproxy is connected to at the moment.

## set log_level - Change or display log level

Syntax:

    set log_level [<level>]

View or change the CtrlProxy internal log level.

## set report-time - Change whether time should be printed when displaying backlog

Syntax:

    set report-time [<true|false>]

Whether or not time should be displayed when sending backlog to the user.

## set motd-file - Change or display the MOTD path

Syntax:

    set log_level [<level>]

View or change the path of the message-of-the-day clients see when they log on.

## set - Change settings

Syntax:

    set [<name> [<value>]]

List, view or change internal settings.

Specifying no argument will list all available settings.

## nextserver - Connect to next server in network

Syntax:

    NEXTSERVER [<NETWORK>]

Makes the specified network disconnect from the current server and go to the next one.

## saveconfig - Save configuration

Syntax:

    SAVECONFIG [<path>]

Save the (updated) configuration to the location it was loaded from (usually `$HOME/.ctrlproxy/`).

## startlistener - Add a new listener

Syntax:

    STARTLISTENER [<address>:]<port> <password> [<network>]

Add listener on specified port

## stoplistener - Stop listener

Syntax:

    STOPLISTENER [<address>:]<port>

Stop listener on specified port

## listlistener - List existing listeners

Syntax:

    LISTLISTENER

List all listeners

## help - Print help

Syntax:

    HELP [<topic>]

Prints out list of available commands.

## Example commands

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

    network add OFTC
    addserver OFTC irc.oftc.net
    connect OFTC

## Chapter 6. Logging

CtrlProxy has various means for logging conversions to file.

## Logging in irssi-style format

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`.

## Logging in a custom format

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.

### Substitutes

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:

h

  Current time of day, hours field.

M

  Current time of day, number of minutes.

s

  Current time of day, number of seconds.

n

  Nick originating the line (saying the message, doing the kick, quitting, joining, etc).

u

  Hostmask of the user originating the line.

N

  Name of the current IRC network.

S

  Name of the server (as set by the transport).

%

  Percent sign

0,1,2,3,4,5,6,7,8,9

  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.

#### join

%c

  Name of the channel the user joins.

#### part

%c

  Name of the channel the user is leaving.

%m

  Comment

#### kick

%t

  Nick of the user that is being kicked.

%c

  Channel the user is being kicked from.

%r

  Reason the user is being kicked.

#### quit

%m

  Comment.

#### topic/notopic

%c

  Name of the channel of which the topic is being changed.

%t

  The new topic. Only set for 'topic', not for 'notopic'.

#### mode

%c

  Name of user or channel of which the mode is being changed.

%p

  Change in the mode, e.g. `+oie`

%t

  Target of which the mode is being changed.

To retrieve any additional arguments for a MODE command, use `%1`, `%2`, etc.

#### notice/privmsg/action

%t

  Name of channel or nickname of user to which the notice/privmsg/ or action is being sent.

%m

  Message that is being sent.

#### nick

%r

  New nickname the user is changing his/her name to.

## Chapter 7. Connecting to CtrlProxy

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 let us know on the CtrlProxy IRC channel if you find a client that is not working.

## irssi

Configure the `port` and `password` settings in `~/.ctrlproxy/config` and run the following commands in irssi:

    			/set proxy_address ctrlproxy-host
    			/set proxy_password ctrlproxy-password
    			/set proxy_port ctrlproxy-port
    			/set use_proxy ON

You should now be able to connect to any networks as you normally would with irssi.

## xchat

Configure socks in xchat to point at the host and port ctrlproxy is listening on. If you specified a password in the ctrlproxy configuration, specify it here as well. CtrlProxy will ignore the username that is sent by xchat.

## BitchX

Configure socks in BitchX:

    			/SET socks_host ctrlproxy-host

and, if you're running ctrlproxy on a port different than 1080:

    			/SET socks_port ctrlproxy-port

## Other clients with SOCKS support

Clients with SOCKS support can simply configure ctrlproxy as if it was an ordinary SOCKS proxy. The username sent by the client is ignored by CtrlProxy, the password has to match the password configured in ctrlproxy's configuration.

## Other clients

Other clients can connect to ctrlproxy as if they were connecting to a standard IRC server.

The client should log in with the password that was configured in the configuration file, followed by a colon and the name of the network to connect to.

For example, the password to use to login to the network Freenode with the ctrlproxy password set to `geheim` would be: `geheim:Freenode`.

## Chapter 8. About

CtrlProxy was written by Jelmer Vernooij with the help from various other people. See the AUTHORS file in the tarball for details.

The CtrlProxy homepage can be found at http://www.ctrlproxy.org/.