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

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

HOPM (Hybrid Open Proxy Monitor) is an open proxy monitoring bot designed for
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 operator {}
block and monitor connections. When a client connects to the server, HOPM 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).

HOPM 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 HOPM
  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, a C99 compiler, etc..

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


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

ircd-hybrid 8.2.x
ircd-ratbox 3.0.x
ircu 2.10.x
InspIRCd 2.0.x
UnrealIRCd 3.2.x
ngIRCd 22
Bahamut 2.0.x
Charybdis 3.4.x

HOPM is designed for ircd-hybrid based ircds. It is easily suitable for any
other ircd with little modification (connregex in hopm.conf). However, if an
ircd does not send IP addresses in a connection notice, HOPM will not be
effective because the time it takes to resolve a hostname would be a
significant factor to HOPM's efficiency.


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

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

-d              Debug mode. HOPM 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, HOPM will scan on all scanners.
                                   NOTE: this will NOT add a kline (or whatever) if it finds a
                                   proxy.

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

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

botnick protocols               -- Output configured scanners and their associated protocols/ports.

Also if several HOPMs are present in one channel they will all respond to !all,
for example !all stats.


Rehashing HOPM
--------------

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


Logging
-------

Once started, HOPM logs all significant events to a file called "hopm.log"
which by default can be found at $HOME/hopm/var/hopm.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 HOPM after moving its logfiles - this will cause
HOPM to reopen those files.


Support
-------

  * Bug Reports:
    - bugs@ircd-hybrid.org
  * IRC contact:
    - #ircd-coders on irc.ircd-hybrid.org
Revision:	5712
Committed:	Tue Mar 17 18:43:27 2015 UTC (11 years, 4 months ago) by michael
File size:	3843 byte(s)
Log Message:	- Added 'protocols' command which dumps a list of configured scanners and their associated protocols/ports to a channel
#	User	Rev	Content
1	michael	5052	Introduction
2			------------
3
4	michael	5060	HOPM (Hybrid Open Proxy Monitor) is an open proxy monitoring bot designed for
5	michael	5146	Hybrid based ircds. The bot is designed to monitor an individual server (all
6	michael	5060	servers on the network have to run their own bot) with a local operator {}
7	michael	5146	block and monitor connections. When a client connects to the server, HOPM will
8			scan the connection for insecure proxies. Insecure proxies are determined by
9	michael	5104	attempting to connect the proxy back to another host (usually the IRC server in
10	michael	5052	question).
11
12	michael	5146	HOPM is written ground-up in C language, concept derived from wgmon. It
13	michael	5052	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	michael	5060	o An IRCd which presents connection notices in a format which HOPM
21	michael	5052	recognises (see below).
22
23	michael	5146	o A host with full connectivity for all the ports you wish to scan. i.e. is
24	michael	5052	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	michael	5060	o A unix OS with GNU Make, a C99 compiler, etc..
29	michael	5052
30			o Permission from your users to portscan them for open proxies.
31
32
33			Compatibility
34			-------------
35
36	michael	5655	ircd-hybrid 8.2.x
37			ircd-ratbox 3.0.x
38	michael	5658	ircu 2.10.x
39	michael	5655	InspIRCd 2.0.x
40			UnrealIRCd 3.2.x
41			ngIRCd 22
42			Bahamut 2.0.x
43			Charybdis 3.4.x
44
45	michael	5146	HOPM is designed for ircd-hybrid based ircds. It is easily suitable for any
46	michael	5108	other ircd with little modification (connregex in hopm.conf). However, if an
47			ircd does not send IP addresses in a connection notice, HOPM will not be
48			effective because the time it takes to resolve a hostname would be a
49			significant factor to HOPM's efficiency.
50	michael	5052
51
52			Command Line Options
53			--------------------
54
55	michael	5361	-c <name> Config name. By default HOPM reads hopm.conf, "-c foo"
56			will cause HOPM to read foo.conf. The primary use for
57			this is to run multiple HOPMs from one directory.
58	michael	5052
59	michael	5361	-d Debug mode. HOPM will not fork, and will write logs to stderr.
60			Multiple -d increase debug level.
61	michael	5052
62
63			Operator Channel Commands
64			-------------------------
65
66			botnick check <host> [scanner] -- Manually scan host for insecure proxies and output all errors.
67	michael	5343	If scanner is not given, HOPM will scan on all scanners.
68	michael	5052	NOTE: this will NOT add a kline (or whatever) if it finds a
69	michael	5060	proxy.
70	michael	5052
71			botnick stats -- Output scan stats, uptime and client connection count.
72
73	michael	5712	botnick fdstat -- Output some info about file descriptors in use.
74	michael	5052
75	michael	5712	botnick protocols -- Output configured scanners and their associated protocols/ports.
76
77	michael	5060	Also if several HOPMs are present in one channel they will all respond to !all,
78	michael	5104	for example !all stats.
79	michael	5052
80
81	michael	5104	Rehashing HOPM
82	michael	5052	--------------
83
84	michael	5343	A /kill to HOPM will cause the process to restart, rehashing the configuration file
85	michael	5052	and ending all queued scans.
86
87
88			Logging
89			-------
90
91	michael	5060	Once started, HOPM logs all significant events to a file called "hopm.log"
92	michael	5146	which by default can be found at $HOME/hopm/var/hopm.log. There is also a
93	michael	5052	config option to log all proxy scans initiated, which can be quite useful if
94			you receive an abuse report related to portscanning.
95
96	michael	5146	These log files, especially the scan log, can grow quite large. It is
97			suggested that you arrange for these files to be rotated periodically. An
98			example shell script is provided in the contrib/logrotate directory. If you
99	michael	5052	prefer to use the log rotation facilities of your operating system then you
100	michael	5060	should send a USR1 signal to HOPM after moving its logfiles - this will cause
101			HOPM to reopen those files.
102	michael	5052
103
104			Support
105			-------
106
107	michael	5060	* Bug Reports:
108			- bugs@ircd-hybrid.org
109			* IRC contact:
110			- #ircd-coders on irc.ircd-hybrid.org