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

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

HOPM (Hybrid Open Proxy Monitor) is an open proxy monitoring bot designed to
monitor an individual server (all servers on the network have to run their own
bot if the IRCD doesn't support 'farconnect' user mode) with a local
operator {} block and monitor connections. When a client connects to a 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 and it is an improved fork of BOPM
(blitzed open proxy monitor) which is a 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 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 work.


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.

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


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

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