README
1dircproxy: Detachable IRC Proxy Server
2-------------------------------------
3
4----------------------------------------------
5WARNING : 1.2.0-RC1 is currently unstable
6----------------------------------------------
7
8dircproxy is an IRC proxy server ("bouncer") designed for people
9who use IRC from lots of different workstations or clients, but wish
10to remain connected and see what they missed while they were away.
11You connect to IRC through dircproxy, and it keeps you connected to
12the server, even after you detach your client from it. While you're
13detached, it logs channel and private messages as well as important
14events, and when you re-attach it'll let you know what you missed.
15
16This can be used to give you roughly the same functionality as
17using ircII and screen together, except you can use whatever IRC
18client you like, including X ones!
19
20
21Features
22========
23
24 o Runs on console, as a daemon or from inetd.
25 o Able to proxy many simultaneous users and IRC connections.
26 o Uses IRC server passwords to authenticate.
27 o Remains connected to server when you detach. To reattach you just
28 use the IRC server password again, no special commands!
29 o Completely non-blocking throughout.
30 o Can connect to servers that also require a password.
31 o Can have a list of servers on the same network to connect to, it
32 will cycle this list.
33 o Throttles data sent to server to ensure you are never flooded
34 off.
35 o Can check servers to make sure they don't become "stoned".
36 o Reconnects to servers if connection is dropped.
37 o Can automatically join channels for you on first attach.
38 o Rejoins channels if you are kicked off.
39 o Can leave channels when you detach and rejoin when you come back.
40 o Can take measures to ensure you don't appear "idle" on IRC.
41 o Drop's unwanted user modes when you detached, if you forget to
42 de-opper yourself.
43 o Will refuse to connect to servers that set certain modes
44 such as +r.
45 o Can bind to any IP on your host to change your appearance on IRC.
46 o Can change what username is presented on IRC without affecting
47 other users its proxying for.
48 o Can send a message to all channels to indicate when you detach
49 and reattach.
50 o Can change your nickname when you detach.
51 o Sets you /AWAY when you detach, if you forget to do so.
52 o Fully configurable logging support so when you reattach you
53 can see what you missed.
54 o Can limit the size of log files to avoid eating diskspace.
55 o Log text recalled to your client is sent so your client sees
56 it as ordinary IRC text.
57 o Can timestamp text in log files so you know when it was sent,
58 also can adjust the timestamp you see depending on how long ago
59 it was sent.
60 o Can make permanent log files for your own use of everything
61 on channels or all private messages.
62 o Can pass log text to a program of your choice (to send you
63 an SMS for example).
64 o Can adjust log timestamps depending on timezone difference
65 between you and dircproxy.
66 o Can proxy DCC chat and sends through itself.
67 o Can capture DCC sends and store them on the dircproxy machine
68 while you're detached, and even while you're attached.
69 o Captured DCC sends can be made subject to a size limit and have
70 the sender's nickname included in the filename.
71 o Can tunnel DCC sends and chats through ssh tunnels.
72 See the included README.dcc-via-ssh for more information.
73 o Customisable message of the day for users which can include
74 stats about log file sizes.
75 o /DIRCPROXY command interface for users to do extra things with
76 the proxy. Fully documented through /DIRCPROXY HELP command, and
77 the admin can enable and disable any command on
78 a user-by-user basis.
79 o Host and password based security.
80 o Easy to configure and get running.
81
82All of dircproxy's features are completely configurable and can be
83enabled, disabled and adjusted through the configuration file.
84
85
86Installation
87============
88
89See the file INSTALL for building and installation instructions.
90
91
92Running dircproxy
93=================
94
95
96Once you have installed and configured dircproxy, you can run it
97from the console. It will automatically enter the background
98(unless you supply the '-D' parameter) and begin listening for
99incoming connections.
100
101You should not need to modify your IRC client or add any
102special scripts to support dircproxy. Authentication is done
103using the standard IRC server password, your IRC client should
104support this. If you're not sure, try something like '/server
105localhost:57000:password' from your IRC client's console.
106
107Connect to it with your IRC client, supplying the same password as
108you set in the config file, dircproxy will then connect to the IRC
109server for you and begin proxying your session.
110
111When you detach, dircproxy will remain running and remain connected
112to the IRC server, logging any channel or private messages for you
113until your return.
114
115To re-attach, just connect with your IRC client, again supplying
116the password. dircproxy will see you have left a session running and
117re-attach you to that instead of creating a new one. Messages you
118missed while you were away will be sent to you in such a way that
119they will fill your IRC windows as if they'd just arrived.
120
121
122You can also run dircproxy from inetd if you wish, although their
123are very few reasons to do this. See the file README.inetd for
124more information on this feature.
125
126
127Adjusting the Proxy
128===================
129
130While you are connected to the proxy you may perform a number of
131actions to adjust your proxy session using the '/dircproxy' command.
132For example, to end your proxy session, disconnecting you from the
133server, use '/dircproxy quit'. For more information on what other
134commands are available, see '/dircproxy help'.
135
136
137More Information
138================
139
140The dircproxy home page is at:
141
142 http://code.google.com/p/dircproxy/
143
144
145Please submit bug reports at:
146
147 http://code.google.com/p/dircproxy/issues/entry
148
149Also join us on the #dircproxy IRC channel on irc.freenode.org
150
151
152dircproxy is distributed according to the GNU General Public License.
153See the file COPYING for details.
154
155
156Copyright (C) 2000-2003 Scott James Remnant <scott at netsplit dot com>
157
158Copyright (C) 2004-2008 Francois Harvey <contact at francoisharvey dot ca>
159
160Copyright (C) 2008-2009 Noel Shrum <noel dot w8tvi at gmail dot com>
161 Francois Harvey <contact at francoisharvey dot ca>
162
163
README.dcc-via-ssh
1Tunneling DCC over ssh using dircproxy
2---------------------------------------
3
4WARNING, THIS IS NOT EASY TO DO.
5Don't read any further unless you are a fully qualified UNIX guru,
6complete with the long hair and sandals.
7
8
9Why do this?
10============
11
12DCC chats and sends will not work if your desktop is behind a
13firewall if that firewall prevents you from freely accessing the
14Internet, or prevents people from connecting to you.
15
16There are normal three ways around this.
17
18 o Placing rules in the firewall that allow certain ports such as IRC
19 through, and using the `dcc_proxy_ports` config option to limit
20 dircproxy's port range to that which you've allowed.
21
22 You probably don't have that kind of access to the firewall though,
23 or wouldn't be allowed to if you did.
24
25 o Install dircproxy on the firewall itself, so it can freely proxy
26 between both networks without being affected by the rules on the
27 firewall.
28
29 Again, you probably don't have that kind of access. Its also not
30 good practice anyway.
31
32 o Piggy back your IRC traffic on something that the firewall does
33 let through.
34
35 Most firewalls let ssh traffic through, at least in the out-bound
36 direction, and that's perfect. This is what this file tells you
37 how to do.
38
39
40What do I need?
41===============
42
43For this to work, the firewall must allow ssh traffic through
44and must allow connections to be made from inside the firewall
45to outside. It probably does, or you can probably persuade the
46firewall admin to let ssh through, its secure after all.
47
48
49You will also need two UNIX machines, one inside the firewall and
50one outside.
51
52The inside one must have dircproxy installed and ssh installed.
53The best choice is probably your desktop if that runs UNIX.
54(You *could* use a Windows machine if you can get dircproxy to
55compile on it and use something like SecureCRT of F-Secure SSH to
56do the tunnels).
57
58The outside machine must also have dircproxy installed, and must
59have the ssh daemon (sshd) installed and running.
60
61
62Setting up the Tunnels
63======================
64
65You'll need three different tunnels across the firewall from
66the machine inside to the machine outside. One to forward the
67IRC connection itself, and a further two for DCC traffic, one
68for incoming and one for outgoing. You can do this with one ssh
69command, specifying all three tunnels at the same time. (Replace
70'outside.firewall' with the hostname of the machine outside).
71
72 $ ssh -L 57010:localhost:57000 \
73 -L 57110:localhost:57100 \
74 -R 57110:localhost:57100 outside.firewall
75
76This will actually start a shell on the remote machine. Exiting from
77it will end the tunnels. For safety you may want to run this under
78screen or something (if you've got that), as it doesn't run in the
79background either. Its perfectly safe to close the tunnels while you
80are detatched though - so you could put these in a shell script or
81something instead and just run that when you want to attach.
82
83
84Configuring dircproxy on the Outside machine
85============================================
86
87This will be the master dircproxy, connecting to the IRC server
88itself and doing all the normal things such as logging etc.
89Configure it as you normally would, except for the following two
90options which need to be set as shown.
91
92 dcc_proxy_ports 57100
93 dcc_tunnel_outgoing 57110
94
95This tells dircproxy to listen for DCC connections on port 57100,
96which is pointed to by a tunnel, and that all outgoing DCCs from you
97(which require a connection to you) should be sent through the tunnel
98on port 57110.
99
100This dircproxy is probably best run as a daemon (i.e. normally).
101
102
103Configuring dircproxy on the Inside machine
104===========================================
105
106This dircproxy will be a simple slave, forwarding to the one outside
107without doing anything clever. The configuration file should be left
108untouched, only add a connection class, which should look like this.
109
110 connection {
111 password "encpass"
112 server "localhost:57010:pass"
113
114 disconnect_on_detach yes
115
116 dcc_proxy_ports 57100
117 dcc_tunnel_incoming 57110
118 }
119
120Replace "encpass" with an encrypted password that should match
121that you configure the IRC client with, and replace "pass" with
122the unencrypted version of whatever you set the password to on the
123dircproxy outside the firewall.
124
125This tells dircproxy that incoming DCC requests to you (which require
126you to connect to the remote server) should be sent through the tunnel
127on port 57110.
128
129You can run this dircproxy as a daemon or from inetd, whichever
130suits you best.
131
132
133Using dircproxy now
134===================
135
136Connect your IRC client to the dircproxy inside the firewall.
137This will then connect through the tunnels to the dircproxy outside
138the firewall which will connect to the IRC server for you.
139
140When you detach your IRC client, the dircproxy inside the firewall
141will disconnect from the one on the outside. This means you can
142also exit the ssh session running the tunnels (thereby closing them).
143When you want to reconnect, just start up the tunnels and dircproxy
144again before you do (having left the one outside well alone). This
145means that if you are using your desktop, you can still switch it off
146over night etc without worrying about loosing your IRC link.
147
148Small note: Because you can only use one listening port, you will only
149be able to have one queued DCC request at a time. Others will be
150rejected until the outstanding request either times out or is
151accepted by you.
152
153Another worthy note is that when using tunnels, you will see two sets
154of messages from dircproxy informing you of its connections to remote
155peers. The first set is the link between the two proxies being
156established, the second set is the link being established to the
157remote peer itself. This is normal and nothing to worry about.
158
159
160Copyright (C) 2000-2003 Scott James Remnant <scott at netsplit dot com>
161
162Copyright (C) 2004-2008 Francois Harvey <contact at francoisharvey dot ca>
163
164Copyright (C) 2008-2009 Noel Shrum <noel dot w8tvi at gmail dot com>
165 Francois Harvey <contact at francoisharvey dot ca>
166
167
README.inetd
1Running dircproxy from inetd
2----------------------------
3
4If you are so inclined, you can run dircproxy from the standard
5UNIX inetd daemon. This means you can do things like wrap it with
6tcpd etc and add all your own perverse security restrictions on top.
7However you loose the automatic ability to detach and reattach to
8your session, which makes it slightly more inconvenient to use.
9
10
11To run from inetd add a line to /etc/services for the port you
12want to listen on, and give it a service name of "dircproxy".
13This is actually good practice anyway.
14
15dircproxy 57000/tcp # Detachable IRC Proxy
16
17
18Now add a line to /etc/inetd.conf for dircproxy. You'll need to
19decide a username to run dircproxy as, "nobody" will probably do,
20don't run dircproxy as "root" unless you plan to use the
21"switch_user" configuration directive! Also change the PATH/TO
22to point to where you installed dircproxy. The -I parameter tells
23it its running from inetd. You can specify any other options here,
24such as to specify the configuration file (dircproxy will only
25check the system-wide configuration file when running under inetd).
26
27dircproxy stream tcp nowait USERNAME /PATH/TO/dircproxy dircproxy -I
28
29
30You can connect to it as normal, however when you disconnect you will
31be disconnected from IRC too, and won't be able to reattach to your
32session. To keep your session connected use the /DIRCPROXY PERSIT
33command. This will tell you which port you can reconnect to your
34session at.
35
36
37Copyright (C) 2000-2003 Scott James Remnant <scott at netsplit dot com>
38
39Copyright (C) 2004-2008 Francois Harvey <contact at francoisharvey dot ca>
40
41Copyright (C) 2008-2009 Noel Shrum <noel dot w8tvi at gmail dot com>
42 Francois Harvey <contact at francoisharvey dot ca>
43
44
README.ssl
1
2
3NO SSL IN 1.2.X RELEASE
4
5SSL IS PLANNED IN 1.3.X RELEASE
6
7
8--------------------------
9[ Using SSL with dircproxy ]
10 --------------------------
11
12* DISCLAIMER :
13*
14* THIS IS AN UNSTABLE DEVELOPMENT RELEASE OF DIRCPROXY. IT HAS HIGHER
15* THAN USUAL RISK OF DESTROYING YOUR SYSTEM OR LOSING YOUR DATA OR
16* CORRUPTING YOUR BOX.
17*
18* DO NOT USE IT IF YOU DO NOT ACCEPT THE RISKS
19*
20* RESPONSABILITY OF DIRCPROXY STAFF COULD NOT BE ENGAGED IN ANY CASE
21
22
23What has changed in this branch
24===============================
25
26This branch adds SSL support for both client-side and server-side.
27Both features may be used independently.
28
29 o Client-side : dircproxy connects to SSL-enabled servers, allowing
30 you to identify the IRC server you are connecting to, eventually
31 identifying yourself to the server and securing communications with
32 a crypted socket.
33 o Server-side : dircproxy offers SSL services, allowing you to identify
34 the dircproxy server you are connecting to, eventually identifying
35 yourself to the server and securing communications with a crypted socket.
36
37These changes are useful for people worried about their talk privacy.
38
39What has been done
40==================
41
42- Client-side :
43 o Connecting to any SSL-enabled server, using the "server_ssl" var in
44 config-file
45
46- Server-side :
47 o Presenting the certificate to any client and allow any client to connect
48
49What needs to be done
50=====================
51
52[P] = Priority [E] = Enhancement
53
54- Client-side :
55 o [E] Checking the certificate validity (date, server name, fingerprint)
56 o [E] Allow users to manually validate certificate
57 o [E] Allow dircproxy to present a certificate to identify user on server
58
59- Server-side :
60 o [P] dircproxy hangs when SSL is enabled and client connects without
61 SSL (due to "while(SSL_accept(p->cliSSL.ssl) != 1);" in irc_net.c on
62 line 235, need to find a smarter way to handle this)
63 o [E] Allow user to present a certificate to identify user on server
64
65How to use dircproxy-SSL
66========================
67
68- Client-side : Add 'server_ssl yes' (without quotes) to your config file
69 and dircproxy will connect to server using a SSL socket
70
71- Server-side : Add 'pk_file "/path/to/privkey.pem"' and
72 'cert_file "/path/to/cacert.pem"' (both without simple quotes) and
73 dircproxy will present the certificate to connecting users.
74
75To generate a test certificate with OpenSSL (http://www.openssl.org/),
76generate a private key with "openssl genrsa -out privkey.pem 2048" then
77generate a self-signed certificate
78"openssl req -new -x509 -key privkey.pem -out cacert.pem -days 1095"
79
80* BEWARE NOT TO USE SELF-SIGNED CERTIFICATE IN PRODUCTION ENVIRONMENT *
81
82
83More Information
84================
85
86The dircproxy home page is at:
87 http://code.google.com/p/dircproxy/
88
89Please submit bug reports at:
90 http://code.google.com/p/dircproxy/issues/list
91
92Also join us on the #dircproxy IRC channel on irc.freenode.net.
93
94dircproxy is distributed according to the GNU General Public License.
95See the file COPYING for details.
96
97
98Copyright (C) 2000-2003 Scott James Remnant <scott at netsplit dot com>
99
100Copyright (C) 2004-2008 Francois Harvey <contact at francoisharvey dot ca>
101
102Copyright (C) 2008-2009 Noel Shrum <noel dot w8tvi at gmail dot com>
103 Francois Harvey <contact at francoisharvey dot ca>
104
105