.\"Created by graziano obertelli <graziano@cs.ucsb.edu>
.\"
.TH nws_ctrl 1 "January 28, 2004" "nws_ctrl"

.SH NAME
nws_ctrl \- sends command to Network Weather Service processes

.SH SYNOPSIS
.B nws_ctrl 
[-t seconds][-P password][-f file][-s e,b,m][-VX][-v #] commands host [command-options]

.SH DESCRIPTION
This manual page explains the 
.B nws_ctrl
program. You can control NWS processes with
.B nws_ctrl.
The 
.B host
after the command is the recipient of the message, everything else after
that is options for the specific command.

Here is a list of commands you can specify 

.B test
.RS
test the NWS process returning a brief informative line (which nameserver
is used for registration and such). If the nws host is 'sick', it means
that it cannot talk reliably with the nameserver. Multiple hosts can be
specified.
.RE

.B register
.RS
direct the NWS process to register with a new NWS nameserver. The new NWS
nameserver is the only command option (has to be present).
.RE

.B memory
.RS
direct the NWS process to use a new NWS memory to store experiments. The
new NWS memory is the only command option (has to be present).
.RE

.B halt
.RS
directs the NWS process to exit.
.RE

.B stop
.RS
stop an activity. The only options allowed (a part from the host) is the
activity name to stop. If 
.I host
is a nameserver, query it to find who is responsible for the activity and
contact it to stop it.
.RE

.B start
.RS
start an activity on sensor
.I host.
The options here are the usual NWS format <attribute>:<name> and at least
.I name, controlName
and
.I skillName
have to be present. Others attribute are optional and depends on the
particular activity to be started.
.RE

.B log
.RS
directs the NWS process to suppress or resume error message output. It
accepts 1 options that can be 
.I error 
or
.I log
that specifies wich diagnostics needs to be toggle. No options meas all
diagnostics will be toggle.
.RE

.B skill
.RS
asks the remote sensor to execute a skill. The options that this command
accepts are a tab delimited list of attribute:value pair: the attribute
skillName has to be present. See 
.B EXAMPLES
on how to use it.
.RE

.B add
.RS
asks a remote sensor to add a new host to a running clique: the clique
needs to be already running. The first options is the clique name and the
second options is the host to add.
.RE

.B remove
.RS
asks a remote sensor to remove a new host to a running clique: the clique
needs to be already running. The first options is the clique name and the
second options is the host to remove.
.RE

.B ping
.RS
execute a single network test to the specified host (host needs to have a
running nws_sensor). The options
.I -s
can specify the parameters for the probe.
.RE

.B proxy
.RS
asks a nws proxy (host) measurement and forecast for the specific
resource (the first option) for all the hosts (all the other options are
the hosts). Returns n/a if the data for some hosts is unavailable. If you
specify 
.I -X
returns an XML document instead of a simple printout.
.RE

.B proxyFetch
.RS
asks a nws proxy (host) to start autofetching (monitoring) the specific
resource (the first option) for all the hosts (all the other options are
the hosts). 
.RE

.B
.SH OPTIONS
.BI -t\ timeout
.RS
wait to connect to host for only 
.I timeout.
seconds
.RE

.B -X
.RS
used only with the
.B proxy
command. Print the result as an XML document.
.RE

.BI -f\ file
.RS
after reading the command line, read 
.I file
for options.
.RE

.B -V
.RS
print the version number.
.RE

.B -s\ experiment,buffer,message
.RS
this options is useful only when using the 
.B ping
command: it instructs to use an experiment size of 
.I experiment
kB, with
.I buffer
kB and using
.I message
kB messages.
.RE

.B -v\ level
.RS
specifies the verbosity while issuing NWS commands. 
.I level
can be up to 5.
.RE

.B
.SH EXAMPLES
To test a list of hosts (say sensor A, B and nameserver C) you can 

.RS
nws_ctrl test A B C:8090
.RE

To have the remote sensor A to use the cpuMonitor skill (that monitor 2
resources) you can

.RS
nws_ctrl skill A skillName:cpuMonitor
.RE

and the output will be someting like

.RS
A:8060 currentCpu: 1.00
A:8060 availableCpu: 0.92
.RE

You can have network experiment (thus conducted without using a clique).
Say that you want to have sensor A test the network to sensor B using a
message size of 512 (KB), you can

.RS
nws_ctrl skill A skillName:tcpMessageMonitor size:512 target:B
.RE

and the output will be something like

.RS
A:8060 latencyTcp: 37.62
A:8060 bandwidthTcp: 0.23
.RE

The 'skill' command allow to use all the options that the nwsSkill
understants (ie you can use the 'nice' in cpuMonitor). 

.SH BUGS
.P
Bugs list is at 
.UR http://nws.cs.ucsb.edu
http://nws.cs.ucsb.edu.
.UE

.SH AUTHOR
NWS is an original idea of Rich Wolski Rich Wolski (rich@cs.ucsb.edu).

.P 
Graziano Obertelli (graziano@cs.ucsb.edu) currently maintains NWS and
wrote this man page.

.SH SEE ALSO
.BR nws_sensor(1),
.BR nws_search(1),
.BR nws_nameserver(1),
.BR nws_extract(1)