1NLANR/DAST Multicast Beacon v1.4-0
2February 4, 2011
3Mitch Kutzko - mitch@dast.nlanr.net
4
5
6General installation notes
7
8 See INSTALL.
9
10
11
12Perl Requirements
13
14 If your Perl installation doesn't already have it, you'll need
15 to install Time::HiRes. (Darwin installs seem to be the only
16 ones I've tested under that don't already have it.)
17
18 You can use:
19
20 /usr/bin/perl -MCPAN -e shell
21
22 and at the prompt enter:
23
24 install Time::HiRes
25
26
27 to install Time::HiRes for those OS's. If it's the first time
28 you run CPAN, you'll have to go through the Perl Inquisition
29 while it figures out where and how to install what it needs, but
30 then it should be much simpler thereafter. I used all the
31 default values to the many, many questions when I installed to
32 the PowerPC I used for this, and it worked out fine.
33
34* The Beacon is a perl script. It requires Perl 5.6 or better.
35 You'll need to compile and install everything in the tarball
36 to get it to run.
37
38* This version of the Beacon generates five ten as output:
39 central_loss.html, local_loss.html, central_rtt.html, local_rtt.html,
40 central_jitter.html, local_jitter.html, frac_lost.html, beacon_info.html,
41 history.txt, and prevhistory.txt. Loss is the loss seen during
42 the interval between web refreshes. Frac is the
43 instantaneous fractional loss value for that particular
44 Receiver Report. Central_loss is a matrix of the interval
45 loss as seen by all the Beacons reporting their local data
46 back to a specified Central Server via TCP.
47
48* IMPORTANT: The Beacon isn't a web server, and doesn't play one on TV.
49 It's totally up to you to find a way to get the information it generates
50 served to the web if that's what you want to do.
51 However, for those that don't have the ability to serve their
52 own data, a copy of the data from multicast group 233.4.200.18, port 10004,
53 as seen by the DAST Central Beacon Server will generally be available
54 at: http://jhereg.ncsa.uiuc.edu and/or http://beacon.dast.nlanr.net.
55
56* The Beacon software (as well as a list of Known Issues) can be found at:
57 http://dast.nlanr.net/projects/beacon/
58
59* Unfortunately, as much as we'd like to, we don't have the time or
60 resources to help you debug what's wrong with your Perl install under
61 some OS, or help you figure out why you can't get the module to compile.
62 Those questions are left to the alert Beacon user. When you figure
63 out what was wrong, please send us mail at beacon@dast.nlanr.net,
64 and we'll add your problem and your solution to our Beacon FAQ. (So check
65 the FAQ first -- Maybe the solution to your problem is already there.)
66
67* The Beacon creates a file, "multicastbeacon.PID", in the output directory
68 to hold the process ID of the running copy of the Beacon so that duplicate
69 copies aren't started by accident.
70
71* There is a mailing list set up for discussion of the current Beacon at
72 beacon@dast.nlanr.net.
73
74
75* Anyone is welcome to use this version of the Beacon, but we ask two things.
76 First, that you credit NLANR and link back to the NLANR/DAST web page for
77 the Beacon (http://dast.nlanr.net/projects/beacon), and second, that you
78 give us feedback on how you're using the Beacon, and what bugs, comments,
79 ideas, or changes you have for it. Please share those with the listserv
80 at beacon@dast.nlanr.net. (You can subscribe by sending an email to
81 majordomo@dast.nlanr.net, with "subscribe beacon@dast.nlanr.net" in the
82 body. This list is publicly archived at
83 http://archive.ncsa.uiuc.edu/lists/beacon.)
84
85* Finally, NLANR would like to specifically acknoweldge the invaluable
86 assistance from LBL's Deb Agarwal in finding the problems with the old RTP
87 library, and providing the impetus to move to the new RTP library and
88 finaly get this release up and running. (Thanks, Deb!) Kudos also go
89 out to NCSA's Jon Dugan, for getting the new RTP library SWIG'd and
90 available to me on a next-day basis. (Thanks, Jon!) NLANR/DAST's
91 John Estabrook also resides in the "couldn't have done it without you"
92 category, for his help in solving some of the more esoteric and "interesting"
93 bugs found in the RTP library. (Thanks, John!)
94
95Enjoy!
96
97Mitch
98
99-----------------------
100
101Information about v1.4-0:
102
103This version requires Perl 5.6 or better, and does *not* require you to
104be root on the box you wish to install on. However, you do need to make
105and install Perl Module "Net::Multicast::Beacon", so if you don't have
106root, you'll have the additional step of needing to tell Perl where you
107installed the module.
108
109This version produces the following files as the main output:
110 central_loss.html
111 local_loss.html
112 fract_lost.html
113 central_rtt.html
114 local_rtt.html
115 central_jitter.html
116 local_jitter.html
117 beacon_info.html
118 history.txt
119 prevhistory.txt
120
121The "central_loss.html" file is the one you are mostly likely interested in.
122
123------------------------------------------------------------------------------
124
125Command Line Options/Examples:
126
127./beacon
128Starts Beacon using only settings from beacon.conf.
129
130./beacon -o /home/beacon/outputfiles
131Specifies the directory to write output HTML and txt files to.
132Don't specify a trailing slash.
133Config file entry: OUTPUTDIR
134
135./beacon --outputdir /home/beacon/outputfiles
136Same as previous.
137
138./beacon -n or ./beacon --noshutdownmsg
139Does NOT write a shutdown message to HTML files when Beacon is shutdown.
140Config file entry: NOSHUTDOWNMSG
141
142./beacon -c beacon.ncsa.uiuc.edu
143Specifies the (optional) Central Server to send TCP reports back to.
144
145./beacon --centralservername beacon.ncsa.uiuc.edu
146Same as previous.
147
148./beacon -i or ./beacon --showip
149Show Beacon IP addresses in the HTML output.
150Config file entry: SHOWIP
151
152./beacon -r or ./beacon --showreports
153Show count of RRs during each interval in the HTML output.
154Config file entry: SHOWREPORTS
155
156./beacon -s or ./beacon --showssrc
157Show unique SSRC ID numbers for each Beacon in the HTML output.
158Config file entry: SHOWSSRC
159
160./beacon -j\ or ./beacon --contactname
161Specify Beacon contact's name on command line.
162Config file entry: CONTACTNAME
163
164./beacon -k or ./beacon --contactinfo
165Specify Beacon contact's info (email, phone, etc.) on command line.
166Config file entry: CONTACTINFO
167
168./beacon -l or ./beacon --contactlocation
169Specify Beacon contact's physical location on command line.
170Config file entry: CONTACTLOCATION
171
172./beacon -w or ./beacon --writehistory
173Output statistics to CSV flat text file every 10 minutes.
174History file name is history.txt.
175Config file entry: WRITEHISTORY
176
177./beacon -e or ./beacon --erasehistory
178Erase existing history file at startup. If this option is not specified,
179output will be appended to the existing history file if there is one.
180Config file entry: ERASEHISTORY
181
182./beacon -y or ./beacon --silencetest
183Enables periodic Silence tests.
184Config file entry: SILENCETEST
185
186./beacon -z or ./beacon --bursttest
187Enables periodic Burst tests.
188Config file entry: BURSTTEST
189
190./beacon --notifyemail beaconadmin@xyz.edu
191Specifies the email address to send alarm notifications to.
192Not yet implemented.
193Config file entry: NOTIFYEMAIL
194
195./beacon -m beaconadmin@xyz.edu
196Same as previous.
197
198./beacon -a or ./beacon --background
199Causes Beacon process to run in background at startup.
200Config file entry: BACKGROUND
201
202./beacon -f 141.142.98.209
203Specifies which interface to use if more than one NIC is present.
204Config file entry: INTERFACE
205
206./beacon --interface 141.142.98.209
207Same as previous.
208
209./beacon -g 233.4.200.19 -p 10002 -t 127
210Specifies group, port, and ttl on command line, instead of using settings
211in beacon.conf.
212Config file entry: GROUP, PORT, TTL
213
214./beacon --group 233.4.200.19 --port 10002 --ttl 127
215Same as previous.
216
217./beacon -b or ./beacon.pl --becentralserver
218Act as a Central Beacon Server. Only one server is needed for multiple
219Beacons. To participate with an existing Central Server, you only need to
220run one Beacon that points to the existing Central Server.
221Config file entry: BECENTRALSERVER
222
223./beacon -q or ./beacon --syslog
224Writes output that would normally have gone to STDOUT to SysLog instead.
225For example, if you're running Linux, you'd look in
226/var/log/messages for that output.
227Config file entry: SYSLOG
228
229./beacon -d N or ./beacon --debug N
230Sets debug level of Beacon script to integer N. Only 1 and 2 are currently used.
231Config file entry: DEBUG
232
233./beacon -v or ./beacon --version
234Shows Beacon version information.
235
236./beacon -h or ./beacon --help
237Gives this message.
238
239
240------------------------------------------------------------------------------
241
242KNOWN BUGS, version 1.4-0
243
244* -make install- bug under Darwin
245
246 There's a problem we're currently looking into with the
247 autoconf/make machinery under the Darwin OS that doesn't
248 perform the actual -make install- correctly. The install
249 appears to run correctly under all other OSs we've tested.
250
251 The workaround is to go into the .../src directory after
252 the -make install- successfully completes and run a
253
254 chmod +x beacon
255
256 on the freshly made beacon executable. You can now run
257 it directly with
258
259 ./beacon
260
261 there in the .../src directory or copy it to /usr/local/bin
262 or wherever else you like to put it on your path manually.
263
264
265* True hostname of Central Server in beacon.conf bug
266
267 There is also a bug in the TCP connection machinery for
268 the TCP Central Server reports that currently requires
269 you to use the true hostname of the Central Server you
270 want to send reports to.
271
272 This is the CENTRALSERVERNAME setting in
273 .../src/beacon.conf.
274
275 For example, the actual hostname for the alias of
276 "beacon.ncsa.uiuc.edu" we're using as the Central Beacon
277 Server here at NCSA is "jhereg.ncsa.uiuc.edu". For the
278 moment, you must set
279
280 CENTRALSERVERNAME = jhereg.ncsa.uiuc.edu
281
282 to get your individual Beacons to connect correctly.
283 The "beacon.ncsa.uiuc.edu" alias won't work at the
284 moment.
285
286------------------------------------------------------------------------------
287
288Please share your comments, questions, bug reports, concerns, and feedback
289with us via the "beacon" listserv at beacon@dast.nlanr.net. You can
290subscribe to it by sending an email to "majordomo@dast.nlanr.net", with
291"subscribe beacon@dast.nlanr.net" in the body. This list is publicly
292archived at http://archive.ncsa.uiuc.edu/lists/beacon.
293
294Thanks!
295