dircproxy - Online in the Cloud

PROGRAM:

NAME

dircproxy - Detachable Internal Relay Chat Proxy Server

SYNOPSIS

dircproxy [-hvDI] [-f config_file] [-P listen_port] [-p pid_file]

DESCRIPTION

dircproxy is an IRC proxy server designed for people who use IRC from lots of different
workstations or clients, but wish to remain connected and see what they missed while they
were away.

You connect to IRC through dircproxy, and it keeps you connected to the server, even after
you detach your client from it. While you're detached, it logs channel and private
messages as well as important events, and when you re-attach it'll let you know what you
missed.

This can be used to give you roughly the same functionality as using ircII and screen(8)
together, except you can use whatever IRC client you like, including X ones!

Authentication is provided by a password, and optional hostname checking. This links it
to a connection class specified in the configuration file. Only one user may use a
connection class at one time, when that user detaches, the connection to the server is
kept open. When someone (usually the user) subsequently connects to dircproxy and
provides the same password, they are reconnected to the connection to the server, instead
of having a new connection created for them.

Multiple connection classes can be defined, allowing multiple people to use the same
proxy.

dircproxy can use either a .dircproxyrc file in the user's home directory, or a system-
wide dircproxyrc file. It will load the first it finds (home directory first, then
system-wide). If no configuration file is specified, it will not start.

OPTIONS

-f config_file
Specifies the configuration file to be used, overriding the default search list.

-h Displays a brief help message detailing the command-line arguments, then exits.

-v Displays the dircproxy version number, then exits.

-D Run in the foreground and do not fork into the background.

-I Use to indicate dircproxy is being run from the inetd(8) daemon. This implies -D.
For more information on running dircproxy under inetd(8), see the README.inetd
file.

-P listen_port
Specifies an alternate port to use, overriding the default and any value specified
in the configuration file.

-p pid_file
Specifies a file to write the process id to, overriding the default and any value
specified in the configuration file.

CONFIGURATION

The configuration file has the following format:

Empty lines and lines starting with '#' are comments.

Connection classes start with 'connection {' and end with '}'. They obtain default values
from all the entries above them in the configuration file, and may contain values of their
own.

Otherwise a line is of the format 'keywords arguments'. If the argument contains spaces
it should be contained in double quotes ('"with spaces"'). The possible keywords and
their meanings are as follows (note that the configuration file is not case-sensitive):

LOCAL OPTIONS

These options may not be placed inside a connection class as they affect the operation of
the entire dircproxy server.

listen_port
What port should dircproxy listen for connections from IRC clients on?

This can be a numeric port number, or a service name from /etc/services

pid_file
File to write the dircproxy process id to on startup. If you start this with a
"~/" then it refers to a file in a directory under your home directory.

none = Don't write pid file

client_timeout
Maxmimum amount of time (in seconds) a client can take to connect to dircproxy and
provide their password and nickname etc.

connect_timeout
Maximum amount of time (in seconds) a client has to provide a server to connect to
after they've logged in. This only applies if 'server_autoconnect' is 'no' for
that class.

dns_timeout
Maximum amount of time (in seconds) to wait for a reply from a DNS server. If the
time exceeds this then the lookup is cancelled.

GLOBAL OPTIONS

These options may be placed in a connection class, or outside of one. If they are outside
then they only affect those connection classes defined afterwards.

server_port
What port do we connect to IRC servers on if the server string doesn't explicitly
set one

This can be a numeric port number, or a service name from /etc/services

server_retry
How many seconds after disconnection or last connection attempt do we wait before
retrying again?

server_maxattempts
If we are disconnected from the server, how many times should we iterate the server
list before giving up and declaring the proxied connection dead?

0 = iterate forever

server_maxinitattempts
On first connection, how many times should we iterate the server list before giving
up and declaring the proxied connection dead?

0 = iterate forever. This isn't recommended.

server_keepalive
This checks whether the dircproxy to server connection is alive at the TCP level.
If no data is sent in either direction for a period of time, a TCP keepalive probe
is sent.

yes = send keepalive probes
no = don't send keepalive probes

server_pingtimeout
For some people, dircproxy doesn't notice that the connection to the server has
been dropped because the socket remains open. For example, those behind a NAT'd
firewall. dircproxy can ping the server and make sure it gets replies back. If
the time since the last reply was received exceeds the number of seconds below the
server is assumed to be "stoned" and dircproxy leaves it. If you have a high
latency connection to the server, it can wrongly assume the server is stoned
because the PINGs don't arrive in time. Either raise the value, or use the
'server_keepalive' option instead.

0 = don't send PINGs

server_throttle
To prevent you from being flooded off the IRC network, dircproxy can throttle the
connection to the server to prevent too much being sent within a certain time
period.

For this you specify a number of bytes, then optionally a time period in seconds
seperated by a colon. If the time period is ommitted then per second is assmued.

server_throttle 10 # 10 bytes per second
server_throttle 10:2 # 10 bytes per 2 seconds (5 per second)

0 = do not throttle the connection

server_autoconnect
Should dircproxy automatically connect to the first server in the list when you
connect. If you set this to 'no', then 'allow_jump' is automatically set to 'yes'.
If 'allow_jump_new' is also 'yes', then you can create connection classes with no
'server' lines.

yes = Automatically connect to the first server
no = Wait for a /DIRCPROXY JUMP from the client

channel_rejoin
If we are kicked off a channel, how many seconds do we wait before attempting to
rejoin.

-1 = Don't rejoin
0 = Immediately

channel_leave_on_detach
Should dircproxy automatically make you leave all the channels you were on when you
detach?

yes = Leave them
no = Remain on them

channel_rejoin_on_attach
If 'channel_leave_on_detach' is 'yes' then should dircproxy rejoin those channels
when you attach again?

yes = Rejoin the channels dircproxy automatically left
no = Leave permanently on detach

idle_maxtime
Set this to the maximum amount of time you want to appear idle for while on IRC, if
you set this then dircproxy will reset your idle time if it reaches this limit (in
seconds).

0 = Don't reset idle time

disconnect_existing_user
If, when you connect to dircproxy, another client is already using your connection
class (ie, if you forgot to close that one), then this option lets you
automatically kill that one off. Make sure you turn any "automatic reconnect to
server" options off before using this, otherwise you'll have a fight on your hands.

yes = Yes, disconnect
no = No, don't let me on

disconnect_on_detach
When you detach from dircproxy it usually keeps you connected to the server until
you connect again. If you don't want this, and you want it to close your server
connection as well, then set this.

yes = Close session on disconnection
no = Stay connected to server until reattachment

initial_modes
Which user modes should we automatically set when you first connect to a server.
Just in case you forget to do it yourself with your irc client.

Set to "" to not set any modes.

drop_modes
Which user modes to drop automatically when you detach, handy to limit the impact
that your client has while connected, or for extra security if you're an IRCop.

Set to "" to not drop any modes.

refuse_modes
Which user modes to refuse to accept from a server. If the server attempts to set
one of these, then the connection to it will be dropped and the next server in the
list will be tried.

A good setting for many people would be "+r", as most servers use that to mean your
connection is restricted. Don't set it to this if you're on DALnet however, DALnet
uses +r to indicate you have registered with NickServ (gee, thanks guys!).

Set to "" to not refuse any modes.

local_address
Local hostname to use when connecting to an IRC server. This provides the same
functionality as the ircII -H parameter.

none = Do not bind any specific hostname

away_message
If you don't explicitly set an /AWAY message before you detach, dircproxy can for
you, so people don't think you are really at your keyboard when you're not.

none = Do not set an away message for you

quit_message
If you don't explicitly give a message when you /DIRCPROXY QUIT, this will be used
instead. Also used for when you've sent dircproxy not to remain attached to the
server on detachment.

none = Use dircproxy version number as QUIT message

attach_message
dircproxy can send an announcement onto every channel you are on when you reattach
to it, just to let everyone know you are back. If you start this with "/ME " then
it will be sent as an ACTION CTCP message (just like the ircII /me command).

none = Do not announce attachment

detach_message
dircproxy can send an announcement onto every channel you are on when you detach
from it, just to let everyone know you are gone. If you start this with "/ME "
then it will be sent as an ACTION CTCP message (just like the ircII /me command).

none = Do not announce detachment

detach_nickname
Nickname to change to automatically after you detach, to indicate you are away for
example. If this contains a '*' character, then that character is replaced with
whataver your nickname was before you detached (ie "*_away" adds "_away" to the end
of your nickname);

none = Leave nickname as it is

nick_keep
Whether dircproxy should attempt to keep the nickname you last set using your
client. If this is 'yes' and your nickname is lost while your client is
disconnected, then it will keep on trying to get it back until a client connects
again.

yes = try to keep my nickname while I'm disconnected
no = if it changes, leave it

ctcp_replies
Whether dircproxy should reply to the standard set of CTCP messages while the
client is detached.

yes = reply to ctcp messages while client is detached
no = nothing but silence

chan_log_enabled
Whether logging of channel text to files should take place. If this is 'yes', then
you'll be able to recall channel text when you rejoin and see what you missed.

yes = Channel text is logged to files
no = Channel text is NOT logged to files

chan_log_always
Channel text will always be logged while you are offline, so when you come back you
can see what you missed. You can also, if you wish, log channel text while online,
so if you're only away a short time you can get an idea of any context etc.

This only applies if 'chan_log_enabled' is 'yes'.

yes = Log channel text while offline and online
no = Log channel text only while offline

chan_log_maxsize
To preserve your harddisk space, you can limit the size of a channel log file.
Once the log file reaches this number of lines, every line added will result in a
line removed from the top. If you know you are never going to want all that logged
information, this might be a good setting for you.

This only applies if 'chan_log_enabled' is 'yes'.

0 = No limit to log files

chan_log_recall
Number of lines from each channel log file to automatically recall to your IRC
client when you attach. If this is low, you may not get much useful information,
if this is high, it may take a long time for all the information to arrive.

This only applies if 'chan_log_enabled' is 'yes'.

-1 = Recall the whole log (not recommended if chan_log_always is yes)
0 = Don't automatically recall anything

chan_log_timestamp
Channel text can have a timestamp added to the front to let you know exactly when a
message was logged. These timestamps are displayed when you recall the log files,
or when automatially dumped.

This applies to ordinary channel logs if 'chan_log_enabled' is 'yes' and also to
the permanent copy if 'chan_log_copydir' is set to something other than 'none'.

yes = Include timestamp
no = Do not include timestamp

chan_log_relativetime
If 'chan_log_timestamp' is 'yes' then you also have the option of using intelligent
relative timestamps. If you do, the timestamp shown when log file information is
recalled depends on how old that line is, making sure it displays enough
information (including date if necessary). Otherwise dircproxy will just tell you
the time in HH:MM format which may not be as useful.

This does mean that the time itself won't be displayed in the log files themselves,
a timestamp is in place instead. This may cause problems if you're doing things
with the log files yourself.

yes = Do fancy relative timestamping
no = Do normal timestamping

chan_log_copydir
As well as dircproxy's own log files, it can also keep a permanent copy somewhere
for your use. dircproxy will append all channel text seen to this file, but will
not use it itself.

If you do define it, it'll add to each log as you use it. If you start with "~/"
then it will use a directory under your home directory.

This is done regardless of the 'chan_log_enabled' and 'chan_log_always' options,
although if those are off then you won't get that text recalled to your client,
despite it being in this file. The timestamping options do apply however.

none = Do not make a permanent copy

chan_log_program
Program to pipe channel text into. If given, dircproxy will run this program for
each log file entry giving the full source information as the first argument, the
destination as the second and the text as a single line on standard input.

The program can be anywhere in your $PATH, or you can start it with "~/" if its in
a directory under your home directory.

This is done regardless of the 'chan_log_enabled' and 'chan_log_always' options.

none = Do not pipe log messages to a program

other_log_enabled
Whether logging of server and private messages to files should take place. If this
is 'yes', then you'll be able to recall server and private messages when you
rejoined and see what you missed.

yes = Server/private messages are logged to files
no = Server/private messages are NOT logged to files

other_log_always
Server and private messages will always be logged while you are offline, so when
you come back you can see what you missed. You can also, if you wish, log these
messages while online, so if you're only away a short time you can get an idea of
any context etc.

This only applies if 'other_log_enabled' is 'yes'.

yes = Log server/private messages while offline and online
no = Log server/private messages only while offline

other_log_maxsize
To preserve your harddisk space, you can limit the size of the server/private
message log file. Once the log file reaches this number of lines, every line added
will result in a line removed from the top. If you know you are never going to
want all that logged information, this might be a good setting for you.

This only applies if 'other_log_enabled' is 'yes'.

0 = No limit to log file

other_log_recall
Number of lines from the server/private message log file to automatically recall to
your IRC client when you attach. If this is low, you may not get much useful
information, if this is high, it may take a long time for all the information to
arrive.

This only applies if 'other_log_enabled' is 'yes'.

-1 = Recall the whole log (not recommended if other_log_always is yes)
0 = Don't automatically recall anything

other_log_timestamp
Server and private messages can have a timestamp added to the front to let you know
exactly when a message was logged. These timestamps are displayed when you recall
the log files, or when automatially dumped.

This applies to the server/private message log if 'other_log_enabled' is 'yes' and
also the permanet copy if 'other_log_copydir' is set to something other than
'none'.

yes = Include timestamp
no = Do not include timestamp

other_log_relativetime
If 'other_log_timestamp' is 'yes' then you also have the option of using
intelligent relative timestamps. If you do, the timestamp shown when log file
information is recalled depends on how old that line is, making sure it displays
enough information (including date if necessary). Otherwise dircproxy will just
tell you the time in HH:MM format which may not be as useful.

This does mean that the time itself won't be displayed in the log files themselves,
a timestamp is in place instead. This may cause problems if you're doing things
with the log files yourself.

yes = Do fancy relative timestamping
no = Do normal timestamping

other_log_copydir
As well as dircproxy's own log file, it can keep a permanent copy somewhere for
your use. dircproxy will append all server and private messages seen to this file,
but will not use it itself.

If you do define it, it'll add to the log as it uses it. If you start with "~/"
then it will use a directory under your home directory.

This is done regardless of the 'other_log_enabled' and 'other_log_always' options,
although if those are off then won't get that text recalled to your client, despite
it being in this file. The timestamping options do apply however.

none = Do not make a permanent copy

other_log_program
Program to pipe server and private messages into. If given, dircproxy will run
this program for each log file entry giving the full source information as the
first argument, the destination as the second and the text as a single line on
standard input.

The program can be anywhere in your $PATH, or you can start it with "~/" if its in
a directory under your home directory.

This is done regardless of the 'other_log_enabled' and 'other_log_always' options.

none = Do not pipe log messages to a program

log_timeoffset
Difference in minutes from your IRC client to the dircproxy machine. So if you're
in GMT, but your dircproxy machine is in PST (which is 8 hours behind), then this
would be -(8 * 60) = -480. Used for log file timestamps.

0 = Don't adjust log timestamps.

log_events
Events you want dircproxy to log for you. This is a comma seperated list of event
names, prefixed with '+' to add the event to the list or '-' to remove an event.
You can also specify 'all' to log all events (the default) or 'none' to not log
anything.

Example, to just log text and action's:

log_events "none,+text,+action"

Example, to log everything but server messages:

log_events "all,-server"
# you don't need to specify 'all'
log_events -server

The possible events are:

text
Channel text and private messages

action
CTCP ACTION events (/me) sent to you or channels

ctcp
Whether to record whether a CTCP was sent to you

join
People (including you) joining channels

part
People (including you) leaving channels

kick
People (including you) being kicked from channels

quit
People quit''ing from IRC

nick
People (including you) changing nickname

mode
Changes in channel modes or your own personal mode

topic
Changes to the channel topic

client
You detaching and attaching

server
Connections and disconnections from servers

error
Problems and errors dircproxy encounters (recommended!)

dcc_proxy_incoming
Whether dircproxy should proxy DCC chat and send requests sent to you by others on
IRC.

yes = Proxy incoming requests.
no = Do not proxy incoming requests.

dcc_proxy_outgoing
Whether dircproxy should proxy DCC chat and send requests sent by you to others on
IRC.

yes = Proxy outgoing requests.
no = Do not proxy outgoing requests.

dcc_proxy_ports
Ports that dircproxy can use to listen for DCC connections on. This is for when
you're behind a firewall that only allows certain ports through, or when doing DCC-
via-ssh.

It is a comma seperated list of port numbers or ranges of ports, for example
'57100-57199,57400,57500,57600-57800'

any = Use any port given to us by the kernel.

dcc_proxy_timeout
Maxmimum amount of time (in seconds) to allow for both sides of a DCC proxy to be
connected.

dcc_proxy_sendreject
Whether to send a physical REJECT message via CTCP back to the source of the
request in event of failure.

yes = Send reject CTCP message back.
no = Do not send any message back.

dcc_send_fast
Whether to ignore the "acknowledgment" packets from the client and just send the
file to them as fast as possible. There should be no real danger in doing this.

yes = Send as fast as possible.
no = Wait for each packet to be acknowledged.

dcc_capture_directory
dircproxy can capture files sent via DCC and store them on the server. Especially
useful while you are detached, whether it does it while attached or not depends on
'dcc_capture_always'. This is the directory to store those captured files in.

If start with "~/" then it will use a directory under your home directory.

none = Do not capture files.

dcc_capture_always
If we're capturing DCC send's, should we do it while the client is connected as
well? If 'yes', then the client will never see the file, it'll be just stored on
the server with a notice sent to the client telling them where.

yes = Capture even when a client is connected.
no = Capture only when client detached.

dcc_capture_withnick
Whether to start the filename of the captured file with the nickname of the sender,
so you know who it came from.

yes = Start with nickname.
no = Do not alter the filename.

dcc_capture_maxsize
Maximum size (in kilobytes) that a captured file can be. If a captured file is
larger than this, or becomes larger than this, then the capture will be aborted and
the file removed from the disk. Prevents people from filling your disk up while
you're detached with a massive file.

0 = No limit to file size.

dcc_tunnel_incoming
Port of a local ssh tunnel leading to another dircproxy client that we should use
for incoming DCC requests. This should not be set if 'dcc_tunnel_outgoing' is set.

See the README.dcc-via-ssh file included with the dircproxy distribution for more
information.

This can be a numeric port number, or a service name from /etc/services

none = There is no tunnel.

dcc_tunnel_outgoing
Port of a local ssh tunnel leading to another dircproxy client that we should use
for outgoing DCC requests. This should not be set if 'dcc_tunnel_incoming' is set.

See the README.dcc-via-ssh file included with the dircproxy distribution for more
information.

This can be a numeric port number, or a service name from /etc/services

none = There is no tunnel.

switch_user
If you're running dircproxy as root, it can switch to a different "effective user
id" to create the server connection. This means that your system ident daemon (and
therefore IRC, if it queries it) will see your server connection as the user you
put here, instead of root.

This is most useful if you are sysadmin running a dircproxy server for multiple
people and want them to all appear as different usernames without using a hacked
identd. Because dircproxy is still running as root, it will have those privileges
for all operations, including the bind(2) for the 'local_address' config option if
you're using Secure Linux patches.

This can only be used if your system supports seteuid(2) and if you are running
dircproxy as the root user, and not just setuid. Attempting otherwise will
generate a warning as dircproxy starts.

This can be a numeric uid or a username from /etc/passwd.

none = Do not do this.

motd_logo
If this is yes, then the dircproxy logo and version number will be included in the
message of the day when you connect. Only the picky would turn this off, its
pretty!

yes = Show me the pretty logo
no = I don't like logos, I'm boring, I eat llamas.

motd_file
Custom message of the day file to send when users connect to dircproxy. The
contents of this file will be sent after the logo and before the stats. If you
start this with a "~/" then it refers to a file in a directory under your home
directory.

none = No custom motd

motd_stats
Display information on what channels you were on, and log file sizes etc in the
message of the day. This is handy, and lets you know how not only much information
you missed, but how much will be sent to you.

yes = Show the stats
no = They don't interest me, don't show them.

allow_persist
You can disable the /DIRCPROXY PERSIST command if you do not want people using your
proxy to be able to do that.

yes = Command enabled
no = Command disabled

allow_jump
You can disable the /DIRCPROXY JUMP command if you do not want people to do that.

yes = Command enabled
no = Command disabled

allow_jump_new
If the /DIRCPROXY JUMP commmand is enabled, then you can disable it being used to
jump to a server:port not in the list specified in the configuration file.

yes = Can jump to any server
no = Only ones in the config file

allow_host
You can disable the /DIRCPROXY HOST command if you do not want people to do that.

yes = Command enabled
no = Command disabled

allow_die
You can enable the /DIRCPROXY DIE command if you want people to be able to kill
your proxy. This isn't recommended as a global option, instead only enable it for
a specific connection class (ie yours).

yes = Command enabled
no = Command disabled

allow_users
You can enable the /DIRCPROXY USERS command if you want people to be able to see
who's using your proxy. This isn't recommended as a global option, instead only
enable it for a specific connection class (ie yours).

yes = Command enabled
no = Command disabled

allow_kill
You can enable the /DIRCPROXY KILL command if you want people to be able to
disconnect anyone using your proxy (including you!). This isn't recommended as a
global option, instead only enable it for a specific connection class (ie yours).

yes = Command enabled
no = Command disabled

Additionally, the following keywords may go only inside a connection class definition.
One 'password' and at least one 'server' (unless 'server_autoconnect' is 'no' and
'allow_jump_new' is 'yes') are mandatory.

password
Password required to use this connection class. This should be encrypted using
your system's crypt(3) function. It must be the same as the password supplied by
the IRC client on connection for this connection class to be used.

You can use the included dircproxy-crypt(1) utility to generate these passwords.

server Server to connect to. Multiple servers can be given, in which case they are
iterated when the connection to one is dropped. This has the following format:

[hostname[:[port][:password]]

from The connection hostname must match this mask, multiple masks can be specified to
allow more hosts to connect. The * and ? wildcards may be used.

join Channels to join when you first connect. Multiple channels can be given, either by
seperating the names with a comma, or by specifying multiple from the channel name
with a space.

Note: You must surround the list of channels with quotes to distinguish from
comments.

For clarification, this is the format of this line:

join "channel[ key][,channel[ key]]..."

SIGNALS

dircproxy will reread its configuration file whenever it receives the hangup signal,
SIGHUP.

Sending an interrupt signal, SIGINT, or a terminate signal, SIGTERM, will cause dircproxy
to exit cleanly.

NOTES

More information, including announcements of new releases, can be found at:

http://code.google.com/p/dircproxy/

Use dircproxy online using onworks.net services