[ViewVC] Annotation of: svn/hopm/trunk/README

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

BOPM (Blitzed Open Proxy Monitor) is an open proxy monitoring bot designed for
Bahamut and Hybrid based ircds.  The bot is designed to monitor an individual 
server (all servers on the network have to run their own bot) with a local o: 
line and monitor connections.  When a client connects to the server, BOPM will 
scan the connection for insecure proxies.  Insecure proxies are determined by 
attempting to connect the proxy back to another host (usually the IRC server in 
question).

BOPM is written ground-up in C language, concept derived from wgmon.  It
improves on wgmon with HTTP support, faster scanning (it can scan clients
simultaneously), better layout (scalability), and dnsbl support.


Requirements
------------

o An IRCd which presents connection notices in a format which BOPM
  recognises (see below).

o A host with full connectivity for all the ports you wish to scan.  i.e. is
  NOT transparently proxied -- many domestic internet connections have port 80
  transparently proxied and this produces completely unpredictable results,
  sometimes as severe as 100% of clients being K:lined!

o A unix OS with GNU Make, an ANSI C compiler, etc..  BOPM probably does
  compile and work on win32 under cygwin, but we won't support it.

o Permission from your users to portscan them for open proxies.


Compatibility
-------------

Bahamut (tested with 1.4.28 -> 1.4.34)
Hybrid (tested with 2.8/hybrid-5.3p8, ircd-hybrid-6.3 and ircd-hybrid-7)
Unreal (tested with 3.1.2 and 3.2)
Dancer (tested with 1.0.31)
Ultimate IRCD (tested with UltimateIRCd(Tsunami)-3.0(00).a22) - please
note, earlier versions of Ultimate IRCD are *not* supported

BOPM is designed for the Bahamut and Hybrid IRCds.   It is easily
suitable for any other ircd with little modification (connregex in bopm.conf).
However, if an ircd does not send IP's in a connection notice (bahamut sends
[IP]), BOPM will not be effective because the time it takes to resolve a
hostname would be a significant factor to BOPM's efficiency.

If you want to use BOPM but you don't think your ircd supports it then please
contact us.  As long as source is available for your ircd then we can almost
certainly make BOPM work with it.

Any questions regarding compatibility should be sent to the developers. If
feasible we might be able to add compatibility to multiple ircd types to the
project in the future.


Command Line Options
--------------------

-c <name>       Config name.  By default BOPM reads bopm.conf, "-c foo"
                will cause BOPM to read foo.conf.  The primary use for
                this is to run multiple BOPMs from one directory.

-d              Debug mode.  BOPM will not fork, and will write logs to stderr.
                Multiple -d increase debug level.


Operator Channel Commands
-------------------------

botnick check <host> [scanner]  -- Manually scan host for insecure proxies and output all errors.
                                   If scanner is not given, bopm will scan on all scanners.
                                   NOTE: this will NOT add a kline (or whatever) if it finds a
                                   proxy.  This is a change from 2.x.

botnick stats                   -- Output scan stats, uptime and client connection count.

botnick fdstat                  -- Output some into about file descriptors in use.

Also if several BOPMs are present in one channel they will all respond to !all,
for example !all stats (fixed in BOPM 3.1.0).


Rehashing BOPM 
--------------

A /kill to bopm will cause the process to restart, rehashing the configuration file
and ending all queued scans.


Logging
-------

Once started, BOPM logs all significant events to a file called "bopm.log"
which by default can be found at $HOME/bopm/var/bopm.log.  There is also a
config option to log all proxy scans initiated, which can be quite useful if
you receive an abuse report related to portscanning.

These log files, especially the scan log, can grow quite large.  It is
suggested that you arrange for these files to be rotated periodically.  An
example shell script is provided in the contrib/logrotate directory.  If you
prefer to use the log rotation facilities of your operating system then you
should send a USR1 signal to BOPM after moving its logfiles - this will cause
BOPM to reopen those files.


Support
-------

BOPM has a mailing list for general discussion and announcements.  CVS
commit emails are also sent there and that is also the place to mail your
patches (unless they are massive, in which case just post a URL).  You can
subscribe to this list from:

  http://lists.blitzed.org/listinfo/bopm

Also check if your question is answered on the BOPM FAQ:

  http://blitzed.org/bopm/faq.phtml

No IRC support currently exists for BOPM.  If you would like to run such a
support channel, please let us know so that we can list it here.


Compatibility Notes
-------------------

o Unreal Ircd

  For *older* versions of Unreal to work,  patches to fix the HCN connect 
  notices (found at http://www.blitzed.org/files/) must be applied.

  Unreal 3.1.3 seems to require opers to be global if they are to see
  connection notices.
    -- prince@avalon.zirc.org

  Later versions of Unreal require different user modes to be set on BOPM for
  it to see connection notices.  You will need to use

      mode = "+sc";

  in your bopm.conf.  Also later versions of Unreal no longer require patching
  as described above.
   -- prince@avalon.zirc.org

o IRCu

  IRCu does not present a banner to clients when they connect, so
  target_string, target_ip and target_port must use some other service besides
  ircd.  For those with root access to their servers, the following inetd.conf
  example is an easy fix for this:

  # BOPM proxy check string
  16667 stream  tcp nowait nobody /bin/echo echo Open Proxy Check

  target_string can then be set to "Open Proxy Check", and target_ip/target_port
  set to your IP and port 16667.

  If you don't want to do the above, you could use any other service on
  your machine that presents a banner.  We would recommend against using
  port 25 because it is common for providers to transparently proxy port
  25.

  Also, to see connect notices, your bopm should set itself umode "+s +16384".
  There is a config file item for setting umodes.


Credits
-------

Please see the CREDITS file.
Revision:	5052
Committed:	Mon Dec 22 11:56:03 2014 UTC (11 years, 6 months ago) by michael
File size:	6330 byte(s)
Log Message:	- Initial import of bopm 3.1.3
#	User	Rev	Content
1	michael	5052	Introduction
2			------------
3
4			BOPM (Blitzed Open Proxy Monitor) is an open proxy monitoring bot designed for
5			Bahamut and Hybrid based ircds. The bot is designed to monitor an individual
6			server (all servers on the network have to run their own bot) with a local o:
7			line and monitor connections. When a client connects to the server, BOPM will
8			scan the connection for insecure proxies. Insecure proxies are determined by
9			attempting to connect the proxy back to another host (usually the IRC server in
10			question).
11
12			BOPM is written ground-up in C language, concept derived from wgmon. It
13			improves on wgmon with HTTP support, faster scanning (it can scan clients
14			simultaneously), better layout (scalability), and dnsbl support.
15
16
17			Requirements
18			------------
19
20			o An IRCd which presents connection notices in a format which BOPM
21			recognises (see below).
22
23			o A host with full connectivity for all the ports you wish to scan. i.e. is
24			NOT transparently proxied -- many domestic internet connections have port 80
25			transparently proxied and this produces completely unpredictable results,
26			sometimes as severe as 100% of clients being K:lined!
27
28			o A unix OS with GNU Make, an ANSI C compiler, etc.. BOPM probably does
29			compile and work on win32 under cygwin, but we won't support it.
30
31			o Permission from your users to portscan them for open proxies.
32
33
34			Compatibility
35			-------------
36
37			Bahamut (tested with 1.4.28 -> 1.4.34)
38			Hybrid (tested with 2.8/hybrid-5.3p8, ircd-hybrid-6.3 and ircd-hybrid-7)
39			Unreal (tested with 3.1.2 and 3.2)
40			Dancer (tested with 1.0.31)
41			Ultimate IRCD (tested with UltimateIRCd(Tsunami)-3.0(00).a22) - please
42			note, earlier versions of Ultimate IRCD are not supported
43
44			BOPM is designed for the Bahamut and Hybrid IRCds. It is easily
45			suitable for any other ircd with little modification (connregex in bopm.conf).
46			However, if an ircd does not send IP's in a connection notice (bahamut sends
47			[IP]), BOPM will not be effective because the time it takes to resolve a
48			hostname would be a significant factor to BOPM's efficiency.
49
50			If you want to use BOPM but you don't think your ircd supports it then please
51			contact us. As long as source is available for your ircd then we can almost
52			certainly make BOPM work with it.
53
54			Any questions regarding compatibility should be sent to the developers. If
55			feasible we might be able to add compatibility to multiple ircd types to the
56			project in the future.
57
58
59			Command Line Options
60			--------------------
61
62			-c <name> Config name. By default BOPM reads bopm.conf, "-c foo"
63			will cause BOPM to read foo.conf. The primary use for
64			this is to run multiple BOPMs from one directory.
65
66			-d Debug mode. BOPM will not fork, and will write logs to stderr.
67			Multiple -d increase debug level.
68
69
70			Operator Channel Commands
71			-------------------------
72
73			botnick check <host> [scanner] -- Manually scan host for insecure proxies and output all errors.
74			If scanner is not given, bopm will scan on all scanners.
75			NOTE: this will NOT add a kline (or whatever) if it finds a
76			proxy. This is a change from 2.x.
77
78			botnick stats -- Output scan stats, uptime and client connection count.
79
80			botnick fdstat -- Output some into about file descriptors in use.
81
82			Also if several BOPMs are present in one channel they will all respond to !all,
83			for example !all stats (fixed in BOPM 3.1.0).
84
85
86			Rehashing BOPM
87			--------------
88
89			A /kill to bopm will cause the process to restart, rehashing the configuration file
90			and ending all queued scans.
91
92
93			Logging
94			-------
95
96			Once started, BOPM logs all significant events to a file called "bopm.log"
97			which by default can be found at $HOME/bopm/var/bopm.log. There is also a
98			config option to log all proxy scans initiated, which can be quite useful if
99			you receive an abuse report related to portscanning.
100
101			These log files, especially the scan log, can grow quite large. It is
102			suggested that you arrange for these files to be rotated periodically. An
103			example shell script is provided in the contrib/logrotate directory. If you
104			prefer to use the log rotation facilities of your operating system then you
105			should send a USR1 signal to BOPM after moving its logfiles - this will cause
106			BOPM to reopen those files.
107
108
109			Support
110			-------
111
112			BOPM has a mailing list for general discussion and announcements. CVS
113			commit emails are also sent there and that is also the place to mail your
114			patches (unless they are massive, in which case just post a URL). You can
115			subscribe to this list from:
116
117			http://lists.blitzed.org/listinfo/bopm
118
119			Also check if your question is answered on the BOPM FAQ:
120
121			http://blitzed.org/bopm/faq.phtml
122
123			No IRC support currently exists for BOPM. If you would like to run such a
124			support channel, please let us know so that we can list it here.
125
126
127			Compatibility Notes
128			-------------------
129
130			o Unreal Ircd
131
132			For older versions of Unreal to work, patches to fix the HCN connect
133			notices (found at http://www.blitzed.org/files/) must be applied.
134
135			Unreal 3.1.3 seems to require opers to be global if they are to see
136			connection notices.
137			-- prince@avalon.zirc.org
138
139			Later versions of Unreal require different user modes to be set on BOPM for
140			it to see connection notices. You will need to use
141
142			mode = "+sc";
143
144			in your bopm.conf. Also later versions of Unreal no longer require patching
145			as described above.
146			-- prince@avalon.zirc.org
147
148			o IRCu
149
150			IRCu does not present a banner to clients when they connect, so
151			target_string, target_ip and target_port must use some other service besides
152			ircd. For those with root access to their servers, the following inetd.conf
153			example is an easy fix for this:
154
155			# BOPM proxy check string
156			16667 stream tcp nowait nobody /bin/echo echo Open Proxy Check
157
158			target_string can then be set to "Open Proxy Check", and target_ip/target_port
159			set to your IP and port 16667.
160
161			If you don't want to do the above, you could use any other service on
162			your machine that presents a banner. We would recommend against using
163			port 25 because it is common for providers to transparently proxy port
164			25.
165
166			Also, to see connect notices, your bopm should set itself umode "+s +16384".
167			There is a config file item for setting umodes.
168
169
170			Credits
171			-------
172
173			Please see the CREDITS file.