[ViewVC] Annotation 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 does not support the "far connect" 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
============

* An IRCD, which presents connection notices in a format, which HOPM recognizes;

* 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;

* A UNIX OS with GNU make, a C99 compiler, etc.;

* Permission from your users to portscan them for open proxies;

* For HTTPS proxy detection, a working LibreSSL/OpenSSL library is required.


Compatibility
=============

* ircd-hybrid 8.2.x
* ircd-ratbox 3.0.x
* ircu 2.10.x
* InspIRCd 3.5.x
* UnrealIRCd 5.0.x
* ngIRCd 25
* 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>`     Configuration filename. By default, HOPM reads `hopm.conf`,
                `-c foo` will cause HOPM to read `foo.conf`. The primary use for
                this is to run multiple HOPM from one directory.

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


Operator channel commands
=========================

`<bot> check <host> [scanner]`  Manually scans host for insecure proxies and
                                outputs all errors. If scanner is not given,
                                HOPM will scan on all scanners. NOTE: this will
                                not add a kline if it finds a proxy.

`<bot> stats`                   Outputs scan stats, uptime and connection count.

`<bot> fdstat`                  Outputs info about file descriptors in use.

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


Rehashing HOPM
==============

A `/quote KILL` on HOPM will cause the process to restart, rehashing the
configuration file and ending all queued scans. The same can be achieved
with `kill -HUP` from the command line.


Logging
=======

Once started, HOPM logs all significant events to a file called `hopm.log`,
which by default can be found at `$HOME/hopm/var/log/hopm.log`. There is also a
configuration option, `scanlog`, 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. You should send a
`USR1` signal to HOPM after moving its logfiles -- this will cause HOPM to
reopen those files.


Contact information
===================

* Home page: https://www.ircd-hybrid.org
* Bug reports: bugs@ircd-hybrid.org
* IRC: #ircd-coders on irc.ircd-hybrid.org
* GitHub: https://github.com/ircd-hybrid/hopm

Anonymous SVN access is also available:
  Devel: `svn co svn://svn.ircd-hybrid.org/svnroot/hopm/trunk`
  Stable branch (1.1.x): `svn co svn://svn.ircd-hybrid.org/svnroot/hopm/branches/1.1.x`
Revision:	9725
Committed:	Mon Nov 16 10:14:58 2020 UTC (5 years, 8 months ago) by michael
File size:	3971 byte(s)
Log Message:	- Update NEWS and README files
#	User	Rev	Content
1	michael	5052	Introduction
2	michael	6564	============
3	michael	5052
4	michael	6564	HOPM (Hybrid Open Proxy Monitor) is an open-proxy monitoring bot designed to
5	michael	6521	monitor an individual server (all servers on the network have to run their own
6	michael	9725	bot if the IRCD does not support the "far connect" user mode) with a local
7	michael	6521	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	michael	5052
12	michael	6521	HOPM is written ground-up in C language and it is an improved fork of BOPM
13	michael	6564	(blitzed open proxy monitor), which is a concept derived from wgmon. It
14	michael	5052	improves on wgmon with HTTP support, faster scanning (it can scan clients
15	michael	6564	simultaneously), better layout (scalability) and DNSBL support.
16	michael	5052
17
18			Requirements
19	michael	6564	============
20	michael	5052
21	michael	6564	* An IRCD, which presents connection notices in a format, which HOPM recognizes;
22	michael	5052
23	michael	6564	* A host with full connectivity for all the ports you wish to scan. i.e. is NOT
24	michael	9725	transparently proxied -- many domestic internet connections have port 80
25	michael	6564	transparently proxied and this produces completely unpredictable results,
26			sometimes as severe as 100% of clients being K:lined;
27	michael	5052
28	michael	6564	* A UNIX OS with GNU make, a C99 compiler, etc.;
29	michael	5052
30	michael	6988	* Permission from your users to portscan them for open proxies;
31	michael	5052
32	michael	6988	* For HTTPS proxy detection, a working LibreSSL/OpenSSL library is required.
33	michael	5052
34	michael	6988
35	michael	5052	Compatibility
36	michael	6564	=============
37	michael	5052
38	michael	6564	* ircd-hybrid 8.2.x
39			* ircd-ratbox 3.0.x
40			* ircu 2.10.x
41	michael	9337	* InspIRCd 3.5.x
42			* UnrealIRCd 5.0.x
43			* ngIRCd 25
44	michael	6564	* Bahamut 2.0.x
45			* Charybdis 3.4.x
46	michael	5655
47	michael	6564	HOPM is easily suitable for any other IRCD with little modification (`connregex`
48	michael	9725	in `hopm.conf`). However, if an IRCD does not send IP addresses in a connection
49	michael	6521	notice, HOPM will not work.
50	michael	5052
51
52	michael	6564	Command-line options
53			====================
54	michael	5052
55	michael	9725	`-c <name>` Configuration filename. By default, HOPM reads `hopm.conf`,
56			`-c foo` will cause HOPM to read `foo.conf`. The primary use for
57	michael	6564	this is to run multiple HOPM from one directory.
58	michael	5052
59	michael	9725	`-d` Debug mode. HOPM will not fork and will write logs to `stderr`.
60			Multiple `-d` increase debug level.
61	michael	5052
62
63	michael	6564	Operator channel commands
64			=========================
65	michael	5052
66	michael	6564	`<bot> check <host> [scanner]` Manually scans host for insecure proxies and
67			outputs all errors. If scanner is not given,
68	michael	9725	HOPM will scan on all scanners. NOTE: this will
69			not add a kline if it finds a proxy.
70	michael	5052
71	michael	6564	`<bot> stats` Outputs scan stats, uptime and connection count.
72	michael	5052
73	michael	6564	`<bot> fdstat` Outputs info about file descriptors in use.
74	michael	5052
75	michael	9725	Also, if several HOPM are present in one channel, they will all respond to `!all`,
76	michael	6564	for example `!all stats`.
77	michael	5052
78
79	michael	5104	Rehashing HOPM
80	michael	6564	==============
81	michael	5052
82	michael	9725	A `/quote KILL` on HOPM will cause the process to restart, rehashing the
83	michael	8543	configuration file and ending all queued scans. The same can be achieved
84	michael	9725	with `kill -HUP` from the command line.
85	michael	5052
86
87			Logging
88	michael	6564	=======
89	michael	5052
90	michael	6564	Once started, HOPM logs all significant events to a file called `hopm.log`,
91	michael	8560	which by default can be found at `$HOME/hopm/var/log/hopm.log`. There is also a
92	michael	6564	configuration option, `scanlog`, to log all proxy scans initiated, which can be
93			quite useful if you receive an abuse report related to portscanning.
94	michael	5052
95	michael	9725	These log files, especially the `scan.log`, can grow quite large. It is suggested
96	michael	6564	that you arrange for these files to be rotated periodically. You should send a
97			`USR1` signal to HOPM after moving its logfiles -- this will cause HOPM to
98			reopen those files.
99	michael	5052
100
101	michael	6564	Contact information
102			===================
103	michael	5052
104	michael	9725	* Home page: https://www.ircd-hybrid.org
105	michael	6564	* Bug reports: bugs@ircd-hybrid.org
106			* IRC: #ircd-coders on irc.ircd-hybrid.org
107			* GitHub: https://github.com/ircd-hybrid/hopm
108
109			Anonymous SVN access is also available:
110			Devel: `svn co svn://svn.ircd-hybrid.org/svnroot/hopm/trunk`
111			Stable branch (1.1.x): `svn co svn://svn.ircd-hybrid.org/svnroot/hopm/branches/1.1.x`