Contents of this README file:	
	
      + Introduction
      + Features
      +	How do I install it?
      +	Inetd operation
      +	Standalone operation
      +	Ipfwadm config for transparent operation  (Linux)
      + IPF config for transparent operation  (*BSD, HP-UX, Solaris)
      +	Broadcasting and the MOTD feature.
      +	Identd: Assigning UID/GID to client IP addresses
new:  +	Identd: Non-root operation
      +	Why is this better then IP masquerading?  (Linux)
      +	Credits & legal stuff

______________________________________________________________________________


Introduction
------------

This program is designed to proxy IRC connections, intercepting and proxying
both DCC CHAT and DCC SEND requests transparently to the user.

The program can be used in conjunction with the Linux transparent proxy
networking feature, and ipfwadm, to transparently proxy IRC sessions.  If
you aren't running Linux, you should be able to use the IPF package to get
the same functionality.


Features:
---------

  + Correct DCC CHAT and DCC SEND support.
  + Displays /etc/motd.irc after connecting the user to the IRC server.
  + Allows the local admin to send "broadcasts" to everyone using the proxy.
  + Blocks well known trojan horses such as 'script.ini'.
  + Can switch UID/GID depending on what IP address the client has, thus
    allowing you to use an unmodified ident daemon.


How do I install it?
--------------------

Edit the file config.h to suit your tastes and the local configuration.

Type 'make' at your favorite shell prompt.

If all goes well, the proxy should compile and you are ready to type 
'make install' to install the binary.

Your next step will be to either add the proxy to your inetd configuration
or run it in "standalone" mode.  Both methods are described below.

Hopefully, no modification of the source will be needed, but anything you
might want to customize is near the top of tile file.  The program itself is
written in ANSI C using the portable Berkeley sockets interface so it should
compile on almost all machines without change.

If it breaks on your system, let me know!


Inetd operation
---------------

For a low volume application, using inetd to start the proxy is very simple.
Just follow these steps:

1)	Add a line like the following to /etc/services.

	tircproxy      	tcp/7666       		# Transparent IRC Proxy

2)	Add a line like the following to /etc/inetd.conf.

	tircproxy	stream	tcp	nowait	root	/usr/sbin/tircproxy tircproxy  -o <visible-ip><real-irc-server> <port>

	or, if you have transparent proxying,

	tircproxy	stream	tcp	nowait	root	/usr/sbin/tircproxy tircproxy -o <visible-ip>

3)	Restart the inetd daemon, with one of the following commands:

		kill -HUP `cat /var/run/inetd.pid
	or	killall -HUP inetd


Step 2) tells inetd to accept requests on port 7666, and have tircproxy
connect to either a given server or the server the user tried to connect to,
if the transparent feature is used.

The <visible-ip> parameter is very important, this is the IP address that is
used to proxy DCC requests.  It must be able to talk to both the IRC server
and your hidden network, or if that is impossible you must use both the -o
and -i flags.

[ Note:  I have not tested this with transparent proxying! ]

[ Note:  Please read the chapter about non-root operation for a discussion of
  security issues - the above example assumes you will be running the proxy
  as root, which is actually rather unwise. ]


Standalone operation
--------------------

For high volume applications it's best to install the server as a standalone
server.  This prevents inetd having to start a new process for each new
request.  Just follow these steps:

1)	Add a line like the following to /etc/services.

	tircproxy      	tcp/7666       		# Transparent IRC Proxy

2)	Included in this package is a sample 'tircproxy.init' file for
	RedHat and other systems using the SysV style init sequence.  If you
	don't like it, then try adding the following lines to
	/etc/rc.d/rc.local or the equivalent:

	tircproxyd -s 7666 -o <valid IP address> -i <internal IP address> <irc server address> <port>

	or, if you are using transparent proxying,

	tircproxyd -s 7666 -o <valid IP address> -i <internal IP address>

This tells the proxy server to accept requests on port 7666.  The -o and -i
flags are very important if you want DCC to work correctly.

[ Note:  Please read the chapter about non-root operation for a discussion of
  security issues - the above example assumes you will be running the proxy
  as root, which is actually rather dangerous. ]



Ipfwadm config for transparent operation  (Linux)
-------------------------------------------------

To make IRC requests get proxied transparently, the ipfwadm filter rules
must be configured to pass IRC requests to the proxy that would normally
pass through to the outside world.  The Linux kernel must be compiled with
the TRANSPARENT_PROXY feature enabled, and you only get asked about this
feature if you have requested to be prompted about EXPERIMENTAL things.

The following lines would enable transparent proxying of all connections
from the 10.x.x.x network to the rest of the world, assuming the IRC servers
are on ports 6666, 6667, 6668 and 6669.

# ipfwadm -I -a accept -P tcp -S 10.0.0.0/8 -D 0.0.0.0/0 6666 -r 7666
# ipfwadm -I -a accept -P tcp -S 10.0.0.0/8 -D 0.0.0.0/0 6667 -r 7666
# ipfwadm -I -a accept -P tcp -S 10.0.0.0/8 -D 0.0.0.0/0 6668 -r 7666
# ipfwadm -I -a accept -P tcp -S 10.0.0.0/8 -D 0.0.0.0/0 6669 -r 7666

The following line will transparently proxy connections from 12.34.56.78 to
the server irc.super.org, on port 7000.

# ipfwadm -I -a accept -P tcp -S 12.34.56.78 -D irc.super.org 7000 -r 7666

Check the included tircproxy.init file for more examples.


IPF config for transparent operation  (*BSD, HP-UX, Solaris)
------------------------------------------------------------

To make IRC requests get proxied transparently, you must configure ipf
to redirect packets destined to the irc ports to the proxy.  You must
have IPF compiled into your kernel to do this and you must have a working
ipnat configuration. If you're running a recent version of FreeBSD, OpenBSD,
or NetBSD changes are you have IPF in the kernel already if not see .

The following lines would enable transparent proxying of all connections from
the 10.x.x.x network to the rest of the world, assuming the IRC servers    
are on ports 6666, 6667, 6668 and 6669, the proxy is running on port 7666 and
that your ethernet interface is named ep0.  

rdr ep0 10.0.0.0/8 port 6666 -> 127.0.0.1 port 7666 tcp
rdr ep0 10.0.0.0/8 port 6667 -> 127.0.0.1 port 7666 tcp
rdr ep0 10.0.0.0/8 port 6668 -> 127.0.0.1 port 7666 tcp
rdr ep0 10.0.0.0/8 port 6669 -> 127.0.0.1 port 7666 tcp

To transparently proxy to a specific server you need to either run the proxy
as a standalone server set to connect to a certain server and port or if you're
running it from inetd change the command line options in inetd.conf to match
the server and port you wish to have it connect to.


Broadcasting and the MOTD feature.
----------------------------------

The proxy server supports to different broadcasts, one is a MOTD sent
shortly after the connection is established, the other is a broadcast that
is sent when the server receives a HUP signal.

In the former case, the file /etc/motd.irc is dumped unchanged to the
client's socket, after the copy-loop has gone a couple of cycles.  In the
latter the file /tmp/ircbroadcast is dumped to the client's socket,
immediately after the proxy server receives a HUP signal.  This may or may
not interrupt the normal flow of traffic between the client and the IRC
server, I just don't know.. DCC connections are not interrupted.

Both files should therefore contain plain text, formatted the same way as
the IRC server itself formats its messages to the client.  No parsing or
rewriting is done by the proxy.

The following is an example of an /etc/motd.irc file:

:admin@isp.net 999 * :You are connected to the IRC network via
:admin@isp.net 998 * :Bjarni R. Einarsson's  transparent proxy
:admin@isp.net 997 * :server.  Have a nice day!
:bofh!admin@isp.net PRIVMSG #notice :You aren't REALLY on #notice, I'm just pulling your leg!

Note that the permissions of these files should allow anyone to read them,
because tircproxy should either be running as the user owning the connection,
or as a relatively powerless "dummy" user.


Identd: Assigning UID/GID to client IP addresses
------------------------------------------------

Note:  The following method only works if you run the proxy as root!

You can tell the proxy server to change UID/GID depending on what machine
(ip address) is connecting to it.  This will allow your current ident daemon
to correctly authenticate the user.

Assuming the user 'bob' always uses the machine 10.1.2.3, you can ensure
that his identity is correct on IRC in the following fashion:

1)	Create the user 'bob' on your proxy machine, if he doesn't exist
	already.  He does not need to have a valid shell, home directory or
	password for the proxy to work.

2)	Create a text file named /var/run/user-10.1.2.3 containing no text
	but the username 'bob'.  I would type: 
	
		echo bob >/var/run/user-10.1.2.3

I'm not sure /var/run/ is the "right" place to keep such files, if it
bothers you, you can redefine it in the Makefile.


Identd: Non-root operation
--------------------------

It is (as of verison 0.4.0) possible to run a fully functional tircproxy,
without root permissions.  This minimizes the security implications of any
bugs that might exist in tircproxy.

Without root permissions, the proxy will not be able to change UID/GID, so
the advice in the previous chapter is not sufficient to guarantee that the
ident replies will be correct.  The solution to this problem, is to install
oidentd-1.4+cdir, a patched version of Odin's (odin@ojnk.nu) ident daemon.
The patch enables tircproxy (and other subsystems) to communicate with the
oidentd.

(Note: Version 1.3 of oidentd was IIRC audited by the linux-security-audit
 team.  The changes between 1.3 and 1.4+cdir were small, so this should be a
 very secure choice for an ident daemon).

To run tircproxy as a normal user, follow these steps:

	1) Fetch and install oidentd-1.4+cdir from my ftp site or my 
	   web page, and compile both oidentd and tircproxy with support for
	   "CDIR" (a configuration directory).

	2) Decide what user tircproxy will run as.  It's best to create a
	   new user for this, and name the user "ircproxy".  Give "ircproxy"
	   an invalid shell and home directory (/dev/null springs to mind).

	3) Create a new group named "identd", and add both the identd user 
	   and "ircproxy" to the group.

	4) mkdir -p /var/oidentd
	   chgrp identd /var/oidentd
	   chmod ug+rw,o-rwx /var/oidentd
	   touch /var/oidentd/noident-ircproxy

	5) Make sure that tircproxy runs as the user "ircproxy", either by
	   altering the entry in /etc/inetd.conf, or by giving tircproxy the
	   argument "-r ircproxy".

	6) Follow the steps in the previous chapter, but instead of creating
	   the user-<ip> files in /var/run/, create them in /var/oidentd/.


Why is this better then IP masquerading?  (Linux)
-------------------------------------------------

Configuring IP masquerading properly can be very complicated in a mixed
hidden/visible IP enviroment.  Also, because IP masquerading only processes
packets once on their way throught the TCP/IP stack (in kernels 2.0.x at
least), clients behind the firewall cannot communicate with each other via
DCC. This may be corrected in future versions of Linux, but I didn't want to
wait.

Supposedly, solving things in user-space is a Good Thing (tm). :-)

Also, IP masquerading doesn't support all those neat-o features..


Credits & legal stuff
---------------------

I (the author) am Bjarni R. Einarsson <bre@mmedia.is>, a member of the
technical staff at one of Iceland's larger ISPs, Multimedia Consumer
Services.  Feel free to visit our web page, http://www.mmedia.is/ or my page
at http://www.mmedia.is/~bre/.

It is thanks to my coworker, Sibbi (sibbi@scour.org), that this program now
works on NetBSD with the IPF package.  He likes it when people visit his
home page at http://www.scour.org/.  :-)


The latest version of this package should always be at the follwing URL
http://www.mmedia.is/~bre/tircproxy/ with a name like tircproxy-x.x.x.tgz.
If the WWW gives you trouble, try ftp://ftp.mmedia.is/pub/linux/tircproxy/
or sunsite.


The first versions of tircproxy were heavily based on John Saunders'
<john@nlc.net.au> transparent HTTP proxy.  Without his excellent code, this
program would probably never have been written.


This program may be used and distributed according to the terms of the GNU
General Public License.  As is stated in the license, I make no guarantees
about what this program will and won't do.  If it breaks you get to keep both
halves.
