Commit 688bd3f8 authored by Russ Fish's avatar Russ Fish
Browse files

Regenerate the loghole tutorial page with the current loghole man page when it changes.

parent d992a09e
......@@ -1373,6 +1373,7 @@ done
#
......@@ -1961,17 +1962,17 @@ for ac_hdr in ulxmlrpcpp/ulxr_config.h
do
ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6
echo "configure:1964: checking for $ac_hdr" >&5
echo "configure:1966: checking for $ac_hdr" >&5
if eval "test \"`echo '$''{'ac_cv_header_$ac_safe'+set}'`\" = set"; then
echo $ac_n "(cached) $ac_c" 1>&6
else
cat > conftest.$ac_ext <<EOF
#line 1969 "configure"
#line 1971 "configure"
#include "confdefs.h"
#include <$ac_hdr>
EOF
ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
{ (eval echo configure:1974: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
{ (eval echo configure:1976: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
if test -z "$ac_err"; then
rm -rf conftest*
......@@ -2010,17 +2011,17 @@ for ac_hdr in linux/videodev.h
do
ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6
echo "configure:2013: checking for $ac_hdr" >&5
echo "configure:2015: checking for $ac_hdr" >&5
if eval "test \"`echo '$''{'ac_cv_header_$ac_safe'+set}'`\" = set"; then
echo $ac_n "(cached) $ac_c" 1>&6
else
cat > conftest.$ac_ext <<EOF
#line 2018 "configure"
#line 2020 "configure"
#include "confdefs.h"
#include <$ac_hdr>
EOF
ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
{ (eval echo configure:2023: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
{ (eval echo configure:2025: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
if test -z "$ac_err"; then
rm -rf conftest*
......@@ -2053,7 +2054,7 @@ done
# Extract the first word of "gtk-config", so it can be a program name with args.
set dummy gtk-config; ac_word=$2
echo $ac_n "checking for $ac_word""... $ac_c" 1>&6
echo "configure:2056: checking for $ac_word" >&5
echo "configure:2058: checking for $ac_word" >&5
if eval "test \"`echo '$''{'ac_cv_prog_GTK_CONFIG'+set}'`\" = set"; then
echo $ac_n "(cached) $ac_c" 1>&6
else
......@@ -2132,7 +2133,7 @@ fi
# SVR4 /usr/ucb/install, which tries to use the nonexistent group "staff"
# ./install, which can be erroneously created by make from ./install.sh.
echo $ac_n "checking for a BSD compatible install""... $ac_c" 1>&6
echo "configure:2135: checking for a BSD compatible install" >&5
echo "configure:2137: checking for a BSD compatible install" >&5
if test -z "$INSTALL"; then
if eval "test \"`echo '$''{'ac_cv_path_install'+set}'`\" = set"; then
echo $ac_n "(cached) $ac_c" 1>&6
......@@ -2193,7 +2194,7 @@ esac
# Extract the first word of "rsync", so it can be a program name with args.
set dummy rsync; ac_word=$2
echo $ac_n "checking for $ac_word""... $ac_c" 1>&6
echo "configure:2196: checking for $ac_word" >&5
echo "configure:2198: checking for $ac_word" >&5
if eval "test \"`echo '$''{'ac_cv_path_RSYNC'+set}'`\" = set"; then
echo $ac_n "(cached) $ac_c" 1>&6
else
......@@ -2358,7 +2359,8 @@ outfiles="$outfiles Makeconf GNUmakefile \
utils/spewconlog utils/webspewconlog utils/xlogin \
www/GNUmakefile www/defs.php3 www/dbdefs.php3 www/xmlrpc.php3 \
www/xmlrpcpipe.php3 \
www/swish.conf www/websearch www/garcia-telemetry/GNUmakefile \
www/swish.conf www/websearch \
www/garcia-telemetry/GNUmakefile www/tutorial/GNUmakefile \
vis/GNUmakefile vis/webvistopology vis/dbvistopology \
vis/prerender vis/prerender_all vis/render \
vis/floormap vis/webfloormap \
......
......@@ -797,7 +797,8 @@ outfiles="$outfiles Makeconf GNUmakefile \
utils/spewconlog utils/webspewconlog utils/xlogin \
www/GNUmakefile www/defs.php3 www/dbdefs.php3 www/xmlrpc.php3 \
www/xmlrpcpipe.php3 \
www/swish.conf www/websearch www/garcia-telemetry/GNUmakefile \
www/swish.conf www/websearch \
www/garcia-telemetry/GNUmakefile www/tutorial/GNUmakefile \
vis/GNUmakefile vis/webvistopology vis/dbvistopology \
vis/prerender vis/prerender_all vis/render \
vis/floormap vis/webfloormap \
......
......@@ -21,7 +21,7 @@ HTMLINSTALL = $(INSTALL_SBINDIR)/htmlinstall
include $(OBJDIR)/Makeconf
SUBDIRS = garcia-telemetry
SUBDIRS = garcia-telemetry tutorial
#
# Force dependencies to make sure configure regenerates if the .in file
......@@ -250,6 +250,9 @@ $(INSTALL_DIR)/opsdir/www/%: %
-mkdir -p $(patsubst %/,%,$(dir $@))
$(INSTALL_DATA) $(subst $$,\$$,$<) $(subst $$,\$$,$@)
clean: clean-subdirs
distclean: distclean-subdirs
# How to recursively descend into subdirectories to make general
# targets such as `all'.
%.MAKE:
......
#
# EMULAB-COPYRIGHT
# Copyright (c) 2000-2006 University of Utah and the Flux Group.
# All rights reserved.
#
SRCDIR = @srcdir@
TESTBED_SRCDIR = @top_srcdir@
OBJDIR = ../..
SUBDIR = www/tutorial
all: $(SRCDIR)/loghole.html
# We depend on the loghole.1 man page. It is formated into text and then
# html, and added to the end of the loghole web page.
#
# We also leave the checked-in loghole.html file, in order to avoid making a
# hard dependency on having man2html installed. There will be a warning, but
# not an error, if this fails. The original loghole.html will not be wiped out.
$(SRCDIR)/loghole.html: man1/loghole.1 $(SRCDIR)/loghole.html.head
-( man -M . 1 loghole > loghole-man.txt && \
man2html -bare < loghole-man.txt > loghole-man.html && \
cat $(SRCDIR)/loghole.html.head loghole-man.html > loghole.html.new && \
mv loghole.html.new $(SRCDIR)/loghole.html )
# Gotta have a man1 directory for man to search for .1 files.
man1:
mkdir man1
# Symlink the .1 source files into it for man to find.
# Add another layer of ../'s because it's a level lower in the tree.
# Don't error out if the symlink is already there.
man1/loghole.1: man1
- ln -s ../$(TESTBED_SRCDIR)/utils/loghole.1 man1/loghole.1
clean:
rm -rf man1 loghole-man.txt loghole-man.html loghole.html.new
......@@ -23,15 +23,16 @@ logs. <p>
You can learn more about the <b>loghole</b> utility by reading its man page on
<i>users.emulab.net</i>, included below.
<!-- Manpage converted by man2html 3.0.1
ops% man loghole > loghole-man.txt
bsd% man2html -bare < loghole-man.txt > loghole-man.html
-->
<!-- Generated by testbed/www/tutorial/GNUmakefile.in . -->
<PRE>
<!-- Manpage converted by man2html 3.0.1 -->
</PRE>
<H2>SYNOPSIS</H2><PRE>
<B>loghole</B> [<B>-hVdqva</B>] [<B>-e</B> <I>pid</I>/<I>eid</I>] [<B>-s</B> <I>server</I>] [<B>-P</B> <I>port</I>] <I>action</I> [<I>...</I>]
<B>loghole</B> <B>sync</B> [<I>node1</I> <I>node2</I> <I>...</I>]
<B>loghole</B> <B>sync</B> [<B>-nPs</B>] [<B>-r</B> <I>remotedir</I>] [<B>-l</B> <I>localdir</I>] [<I>node1</I> <I>node2</I> <I>...</I>]
<B>loghole</B> <B>validate</B>
......@@ -53,7 +54,7 @@ You can learn more about the <b>loghole</b> utility by reading its man page on
</PRE>
<H2>DESCRIPTION</H2><PRE>
The <B>loghole</B> utility downloads log files from certain directories on the
experimental nodes (e.g. "/local/logs") to the Emulab users machine.
experimental nodes (e.g. "/local/logs") to the Emulab <I>users</I> machine.
After downloading, it can also be used to produce and manage archives
of the log files. Using this utility to manage an experiment's log
files is encouraged because it will transfer the logs in a network-
......@@ -142,23 +143,52 @@ You can learn more about the <b>loghole</b> utility by reading its man page on
The <B>sync</B> action is used to synchronize the logholes on the nodes with
the experiment's log directory on the Emulab users machine. The action
will iterate through each node in the experiment and perform an
<B>rsync(1)</B> on the loghole directories for that node. Currently, the only
directories synced are "/var/emulab/logs" and "/local/logs". In addi-
tion, if any of the network links in the experiment are being traced,
the utility will create a directory for each link and setup symbolic
links to the <B>pcap(3)</B> files retrieved from the delay nodes.
<B>rsync(1)</B> on the loghole directories for that node. Currently, the
default set of directories that will be synced are "/var/emulab/logs"
and "/local/logs". In addition, if any of the network links in the
experiment are being traced, <B>loghole</B> will perform the following extra
steps:
1. Create a directory for each link.
2. Setup symbolic links to the <B>pcap(3)</B> files retrieved from the
delay nodes.
3. Run the pre-shaped <B>pcap(3)</B> files (e.g. *.recv.0) through tcp-
<B>trace(1)</B> to generate graphs viewable with <B>xplot(1)</B>. Note that
the processing will only be done for pcap files that were gener-
ated by a SNAPSHOT event sent to the tracemon agent. The "-s"
option is provided to automatically send this event for each
agent.
While the download is in progress, <B>loghole</B> will display some simple
statistics. The left-hand side of the display shows the number of
nodes remaining to be synced, in progress, and completed. The right-
hand side shows minimum, average, and maximum amount of time needed to
sync a node. Finally, a "spinner" on the far right is updated when the
currently active rsync log files have grown, which usually happens when
more files are being synced.
If <B>rsync(1)</B> encounters an error while running, it will automatically be
rerun after a short delay.
Optional arguments:
<I>node1</I> <I>...</I>
Specify a subset of virtual or physical nodes that should be
synchronized, otherwise all of the nodes will be synchronized.
<B>-r</B>, <B>--remote</B>=<I>remotedir</I>
An additional remote directory to sync. This option is addi-
tive, so you can download several additional directories.
<B>-l</B>, <B>--local</B>=<I>localdir</I>
The local directory to store the downloaded files. This
defaults to the experiment's log directory.
</PRE>
<H2>VALIDATE</H2><PRE>
The <B>validate</B> action is used to check that the logs were sync'd cor-
rectly. Currently, the following checks are performed:
<B>-n</B>, <B>--no-standard</B>
Flag that indicates that the standard logholes (i.e. "/var/emu-
lab/logs", "/local/logs") should not be downloaded.
<B>-P</B>, <B>--no-post</B>
Do not do any additional post-processing of the log files. Cur-
rently, the only post-processing is done on the pcap files gen-
program-agent logs
The stdout and stderr logs from program agents are checked by
......@@ -192,6 +222,22 @@ You can learn more about the <b>loghole</b> utility by reading its man page on
<B>-c</B>, <B>--comment</B>=<I>COMMENT</I>
Add a comment to the archive. This option can be used multiple
times to add more than one comment to the archive. The comments
will be displayed by the <I>show</I> action and can be useful for stor-
ing information about the experiment, for example, the input
parameters. If the argument to this option is is a single dash
(<B>-</B>) the comment will be read from standard in.
<B>-d</B>, <B>--delete</B>
After creating the archive, mark the experiment as <I>clean-on-sync</I>
so that any stale data is cleaned out before performing the next
<B>sync</B> operation. Currently, the mark is a file named ".cleanon-
sync" in the experiment log directory.
</PRE>
<H2>CHANGE</H2><PRE>
The <B>change</B> action is used to change the metadata of an existing ar-
chive. For example, if after analyzing the log files, you decide that
they represent "good" data, you can add a comment stating that fact and
mark the archive as not garbage collectable. The action takes the same
......@@ -201,20 +247,6 @@ You can learn more about the <b>loghole</b> utility by reading its man page on
</PRE>
<H2>LIST</H2><PRE>
The <B>list</B> action is used to get a brief summary of all of the log ar-
chives found in an experiment's log directory. The listing displays
the archive name, when it was created, and its GC status so you can get
an idea of when the experiment runs were performed and what will be
garbage collected.
<B>-O</B> Only list archives that are marked as 'keep until "i-delete"'.
<B>-1</B> Only list archives that are a day from their keep-atleast date.
<B>-!</B> Only list archives that are past their keep-atleast date.
<B>-X</B> Only list archives that are ready to be garbage collected.
<B>-o</B> List archives that do not match the above flags. In other
words, archives that will not be deleted at the next garbage
collection and are more than a day away from their keep-atleast
dates.
......@@ -248,26 +280,31 @@ You can learn more about the <b>loghole</b> utility by reading its man page on
ment are displayed. The default behavior is to display all of
the archives in an experiment.
</PRE>
<H2>CLEAN</H2><PRE>
The <B>clean</B> action is used to clean out log files from the experiment's
log directory and the log directories on the nodes. The default action
is to ask confirmation and then clean out all of the log files.
Available <B>clean</B> options:
<B>-f</B>, <B>--force</B>
Do not prompt for confirmation.
<B>-n</B>, <B>--nodes</B>
Only remove log files on the nodes.
<B>-e</B>, <B>--experiment</B>
Only remove log directories in the experiment's log directory.
<B>-r</B>, <B>--root</B>
Use sudo to run the clean as root on the nodes
</PRE>
<H2>GC</H2><PRE>
The <B>gc</B> action is used to garbage collect any archives in order to free
up space or reduce the total number of archives in an experiment. The
process for selecting files to be garbage collected is as follows:
1. If the total number of archives and their total size are below
the values specified by the <B>--keep-atmost</B> and <B>--keep-size</B>
options then no archives will be deleted, otherwise...
2. Any files that are marked as 'keep until "space-is-needed"' and
past their "keep-atleast" dates, will be deleted until the keep-
atmost and keep-size conditions are met. If deleting these
files does not meet these conditions then...
3. The oldest files that are marked 'keep until "space-is-needed"'
will be deleted until the keep-atmost and keep-size conditions
are met or there are no more files that can be deleted without
user intervention.
......@@ -309,20 +346,31 @@ You can learn more about the <b>loghole</b> utility by reading its man page on
To archive the newly recovered logs and print out just the name of the
new log file:
/local/logs
One of the log directories on experimental nodes that is auto-
matically sync'd. Users should place any logs/data they want
transferred back in this directory.
[vmars@users ~] loghole -e neptune/myexp -q archive
</PRE>
<H2>FILES</H2><PRE>
/proj/<I>pid</I>/exp/<I>eid</I>/logs
The log directory for an experiment.
/proj/<I>pid</I>/exp/<I>eid</I>/logs/<I>node</I>
The log directory for a node in the experiment.
/proj/<I>pid</I>/exp/<I>eid</I>/logs/<I>link</I>
The log directory for a traced LAN or link. The symbolic links
in these directories refer to the <B>pcap(3)</B> files for a node con-
nected to this LAN or link.
/var/emulab/logs
Another log directory on experimental nodes that is automati-
cally sync'd. This directory usually holds logs generated by
the Emulab software running on the node.
/proj/<I>pid</I>/exp/<I>eid</I>/logs/<I>link</I>/__all.recv.0
The <B>pcap(3)</B> file that contains a merge of all the pre-shaped
packets captured by the link trace agents on this LAN or link.
</PRE>
<H2>SEE ALSO</H2><PRE>
<B>event-sched(8)</B>, <B>tevc(1)</B>, <B>zip(1)</B>, <B>rsync(1)</B>, <B>pcap(3)</B>
<B>event-sched(8)</B>, <B>tevc(1)</B>, <B>zip(1)</B>, <B>rsync(1)</B>, <B>pcap(3)</B>, <B>mergecap(1)</B>, tcp-
<B>trace(1)</B>, <B>xplot(1)</B>
</PRE>
......
<!--
EMULAB-COPYRIGHT
Copyright (c) 2000-2005 University of Utah and the Flux Group.
All rights reserved.
-->
<center>
<h1>Loghole - Emulab Log Management Utility</h1>
</center>
The <b>loghole</b> utility downloads log files from certain directories on the
experimental nodes (e.g. "/local/logs") to the Emulab users machine. After
downloading, it can also be used to produce and manage archives of the log
files. <p>
Using this utility to manage an experiment's log files is encouraged
because it will transfer the logs in a network-friendly manner and is already
integrated with the rest of Emulab. For example, any programs executed using
the Emulab event-system will have their standard output/error automatically
placed in the "/local/logs" directory. The tool can also be used to preserve
multiple trials of an experiment by producing and managing zip archives of the
logs. <p>
You can learn more about the <b>loghole</b> utility by reading its man page on
<i>users.emulab.net</i>, included below.
<!-- Generated by testbed/www/tutorial/GNUmakefile.in . -->
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment