1===============
2Obtaining ICPLD
3===============
4
5If you are running FreeBSD, icpld is available through the
6porting system.
7
8ICPLD is currently available from
9http://www.ibiblio.org/icpld/icpld-1.1.5.tar.bz2 .
10It is also mirrored at http://www.northernmost.org/icpld/
11
12ICPLD is mirrored at other locations, but for the
13latest official release, stick to one of the two above URLS. I strongly dislike
14recieving e-mails concerning months old versions.
15
16===============
17What is ICPLD?
18===============
19
20ICPLD aka. Internet Connection Performance Logging Daemon (nifty name, huh?)
21is a daemon which, by sending ICMP requests to an ip of your
22choice, controls whether your networking connection is up or not. As of version
230.6.0 ICPLD supports both IPv4 and IPv6 networks.
24It will log any failed attempts to contact the peering
25machine, and stamp a log as soon as a reply is received.
26It keeps track of when the connection was unavailable, as well as for how
27long. Both totally down, as well as at each occasion of interrupted connection.
28
29=================
30Installing ICPLD
31=================
32
33See INSTALL
34
35====================
36Where will it work?
37====================
38
39ICPLD is known to build and function properly at the following OS's
40and platforms:
41
42Linux
43FreeBSD
44NetBSD
45OpenBSD
46Solaris
47MacOSX
48
49And probably most other somewhat normal UNIX like systems.
50You got it running on some alien OS? Contact me, I'd love to know.
51
52================================
53How to use ICPLD & How it works
54================================
55
56I wrote this program, due to issues with my ISP. It was during a period
57of time incredibly unstable, and didn't perform well at all. So before I
58called them up, I let ICPLD run a few days. Thanks to this information,
59rather than "It goes down every now and then, and stays
60down for a while", they could see patterns, and solve the issue rather
61quickly. Well, to the topic; It's recommended to run ICPLD towards a
62host that's aware of this, as constant ICMP requests might be less
63appreciated by some administrators. This is when the -dinterval switch
64comes in handy, as you can use another interval for checking, once
65the connection is down. And when a working connection is
66detected, icpld will fall back to either the default interval, or
67the one specified with -interval. -dinterval should, however, NOT be
68lower than 3 seconds, as the timeout for two ICMP packets is ~3
69seconds. Setting dinterval lower, will spawn a pinging process, faster
70than the old one has been terminated.
71
72When reading the following, note that IPv4 is the "normal" ip standard of today.
73For you who is not in any way using IPv6, or even knowing what it is
74may completely disregard everything concerning this. Just read IPv4 as 'a normal ip'
75and you will be all right.
76
77The normal way to use ICPLD for IPv4 without the configuration file is as follows:
78icpld -ip ip.of.the.target -fbip ip.of.another.target
79
80The equivalent use with IPv6 would be:
81icpld -ip6 ip.of.the.target -fbip6 ip.of.another.target
82
83(Note that all operations that is available with IPv4 is available
84 with IPv6 as well, simply add '6' at the end of the option.
85 For instance, if you want to specify another log file for the
86 IPv6 monitoring, you add the -logfile6 switch. Alternatively
87 you specify it in the config file with the logFile6= option.
88 See manpage for further information concerning the use of
89 different options)
90
91This will fork icpld to the background, and send an ICMP request every
9210 seconds to ip.of.the.target. If a reply isn't received within an
93appropriate amount of time from either the ip or the fbip, the
94connection is considered broken and a stamp with the time and date is
95put in the log.
96
97The log may be read by executing
98icpld -log
99The log file is by default stored in ~/.icpld/log
100
101Another example would be:
102icpld -ip 192.168.0.1 -fbip 192.168.0.2 -ip6 ::1 -interval 15 -dinterval 5
103Which would check if 192.168.0.1 and 192.168.0.2 is available every
10415 seconds. If they are considered down (doesn't reply), icpld will
105try every 5 seconds. It would perform the same operations with the IPv6
106ip, and would log to the same file (~/.icpld/log)
107
108It is however recommended to use a configuration file since
109it saves a lot of time on regular usage.
110
111Please note that the log will not be 100% accurate, due to
112timeout time and interval (the lower the interval, the higher accuracy
113you will obtain, as well as higher traffic). It is roughly a few
114seconds differing at each occasion.
115
116There are several other options available, please
117see 'icpld --help', or 'man icpld' for further information on these.
118
119==========================================
120I have; found a bug, had an idea, a tips,
121had enough of you and want to flame you.
122==========================================
123
124Feedback is always welcomed by most developers.
125Please see http://northernmost.org/new/contact.php
126
127==========================
128Release specific comments
129==========================
130
131See NEWS
132
133===========
134Thanks to
135===========
136
137Jonas Olsson <impcat@fearmuffs.net> for general ideas, testing, lending
138me OpenBSD machines as well as writing the startup-script for
139the FreeBSD-port (found in contrib/ )
140
141Martin Nilsson <orko@kladdkaka.nu> for help with general ideas (and complaints :-)
142
143L�on Keijser <l.keijser@chello.nl> for the code which counts the number of interruptions
144
145Pete Wilson <pete@pwilson.net> for the code base thanks to which the -log option work as it does
146(see src/displog.cpp footer and source comments for further info)
147
148Elliott Lockwood <elliot_ca@hotmail.com> for the OpenBSD port
149
150Hans Ulrich Niedermann <gp@n-dimensional.de> (#devtools on irc.freenode.net) for the tricky parts of
151configure.in
152
153Tom Angle <tangle@hclg.org> for providing the slackware package
154(http://www.ibiblio.org/icpld/download/binaries/slackware)
155
156Klaus-J. Luksch <cyberclaus@gmx.net> for the init script for SuSe (found in contrib/ )
157
158Anonymous and slightly excentric person for the contrib/icpld.initd script
159