Show run.asc syntax highlighted
EmRun Reference
===============
The EmStar Team <emstar-design at cens dot ucla dot edu>
$Id: run.asc,v 1.18 2004/10/14 01:24:24 girod Exp $
EmRun is a service responsible for starting, stopping, and managing an
EmStar system. It processes a config file that specifies how the
EmStar services are "wired" together, and starts the system up in
dependency order, maximizing parallelism. EmRun also maintains a
control channel to each child process that enables it to monitor
process health (e.g. to respawn dead or stuck processes), initiate
graceful shutdown, and receive notification when starting up that
initialization is complete. Log messages emitted by EmStar services
are processed centrally by EmRun and are exposed to interactive
clients as in-memory logrings with runtime-configurable loglevels.
Using EmRun
-----------
When you're only running one or two EmStar modules, it is sometimes
easier to run them separately in separate terminals. However, as the
number of modules and the complexity of the dependency graph grows,
and when you want to deploy EmStar software, the advantages of EmRun
rapidly become apparent.
Paths and Directory Hierarchies
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The link:make.html[EmStar build system]
wiki:EasyBuild_Reference[EasyBuild Reference] constructs a directory
hierarchy containing all of the executables and libraries. In order
to simplify startup in different configurations, we retain this
hierarchy in deployments. This approach means that if all of the
pathnames are expressed relative to the root of the "platform"
directory, they will work the same in all cases, whether in a
deployment, simulation, or emulation. A similar approach is used to
store the EmRun configuration files (called "emruntabs", files ending
in the suffix `.run`) in the same hierarchy.
Starting EmRun
~~~~~~~~~~~~~~
EmRun is typically started with the working directory set to the root
of the platform directory, as seen in the example below. In this
example, we start up a system defined by the emruntab `ping-ls.run`,
and then kill it using `^C`. The emruntab file wires together a whole
stack of EmStar network modules, and starts up a "ping" daemon on top.
When EmRun is run in the foreground, it outputs log messages above a
certain threshold to standard output. This threshold is configurable
using the `-o` option.
------
$ cd emstar/obj.i686-linux
$ emrun/emrun emrun/emrun link/examples/ping-ls.run
Wed Mar 3 21:14:43.903: emrun: emproxy launched, pid 30380
Wed Mar 3 21:14:43.905: emrun: udp0 launched, pid 30381
Wed Mar 3 21:14:44.050: emrun: ls0 launched, pid 30385
Wed Mar 3 21:14:44.051: udp0: connecting udp0 to eth0 port 6950
Wed Mar 3 21:14:44.185: emrun: neighbors_ls0 launched, pid 30389
Wed Mar 3 21:14:44.263: neighbors_ls0: send period set to 5000 (will be randomized)
Wed Mar 3 21:14:44.273: neighbors_ls0: neighbor_update_init: using linkstats /dev/link/ls0:
Wed Mar 3 21:14:44.274: emrun: bl0 launched, pid 30393
Wed Mar 3 21:14:44.275: neighbors_ls0: running, sending with period 5790 to /dev/link/ls0
Wed Mar 3 21:14:44.394: emrun: frag0 launched, pid 30398
Wed Mar 3 21:14:44.395: bl0: starting up blacklist daemon
Wed Mar 3 21:14:44.568: frag0: fragd_update_mtu: MTU of bl0 is 1487
Wed Mar 3 21:14:44.569: emrun: pingd_frag0 launched, pid 30401
Wed Mar 3 21:14:44.641: pingd_frag0: main: listening to /dev/link/frag0
^C
Wed Mar 3 21:14:47.849: emrun: got SIGINT... shutting down
Wed Mar 3 21:14:47.850: pingd_frag0: pingd_shutdown: ping daemon shutting down
Wed Mar 3 21:14:47.852: emrun: emproxy (pid 30380) finished, exit status 0
Wed Mar 3 21:14:47.854: emrun: pingd_frag0 (pid 30401) finished, exit status 0
Wed Mar 3 21:14:47.856: emrun: frag0 (pid 30398) finished, exit status 0
Wed Mar 3 21:14:47.858: emrun: bl0 (pid 30393) finished, exit status 0
Wed Mar 3 21:14:47.860: emrun: neighbors_ls0 (pid 30389) finished, exit status 0
Wed Mar 3 21:14:47.862: emrun: ls0 (pid 30385) finished, exit status 0
Wed Mar 3 21:14:47.865: udp0: udp_shutdown: shutting down udp0
Wed Mar 3 21:14:47.868: emrun: udp0 (pid 30381) finished, exit status 0
Wed Mar 3 21:14:47.871: emrun: shutdown complete
------
EmRun Command Line Options
~~~~~~~~~~~~~~~~~~~~~~~~~~
EmRun's usage information is shown below. The -t and -E options are
helpful for debugging your config files. The -l, -o, and -s control
the levels at which error messages are logged to the the in-memory
logrings, standard output, and syslog respectively. Arguments
following the config file argument are accessible from within the
emruntab. Similar to shell scripts, $1, $2, $3, etc. are expanded to
access the trailing arguments to EmRun.
EmRun supports two options that are useful to switching between
debugging and deployment. The `--deployment` option sets certain
default options that are appropriate to deployment: by default it will
*not* generate core files, and it will discard log information left
over from terminated processes. If `--deployment` is not enabled,
core files and preserving logs are the defaults. The `--norespawn`
option is also useful for debugging. This turns off auto-respawn on
all processes, so that the system will tend to stop when something
goes wrong.
-------
$ emrun/emrun -h
emrun release: None
usage: emrun [-t] [-E] [--deployment] [--norespawn] [-l logring_level]
[-o stdout_level] [-s syslog_level] <inittab> [$1...]
-t: Test configuration only: parse and print the process list
-E: Preprocess only: do not parse; print after macro pre-processing
The --deployment option enables 'deployment' mode defaults:
* 'once' processes don't default to 'noclean'
* all processes default to no-core
The --norespawn option sets all 'daemon' processes to 'once'
The -l, -o, -s options are minimum level of log messages that should be:
-l: Inserted into emrun's logrings (/dev/emrun/log...), default OFF
-o: Printed to stdout, default NOTICE
-s: Sent to syslog(); default OFF
inittab: filenames with specifications of processes to run
$1, $2, $3...: Config file substitutions, like in the shell (see documentation)
-------
EmRun also supports a number of arguments that are common to all
EmStar modules, such as `--daemon` to 'daemonize'.
Interacting With EmRun
~~~~~~~~~~~~~~~~~~~~~~
One of the primary advantages to using EmStar is its interactive
nature. EmRun provides a number of device interfaces that enable you to
interact with and control a running system. These interfaces include:
- `/dev/emrun/status`: Reports the current state of all processes
managed by emrun.
- `/dev/emrun/command`: Command interface for controlling EmRun.
- `/dev/emrun/last_msg`: Lists the last time each process was terminated
and why, as well as the last log message before death.
- `/dev/emlog/<process>/...`: Per-process in-memory logrings. The `-f`
versions can be used to stream the continuous log to a file with `cat`;
the non `-f` versions dump recent messages.
- `/dev/emrun/emview_config`: Reports configuration information used
to automatically configure the EmView visualizer.
-----
[girod@seagull emrun]$ cat status
Process Name Type Log Level Current Status Command
------------ -------- ------------ ------------------- -------------
emproxy daemon Default running, pid 28851 emproxy/emproxy
udp0 daemon Default running, pid 28852 link/udpd --provides udp0
ls0 daemon Default running, pid 28862 link/linkstatsd --uses udp0 --provides ls0
neighbors_ls0 daemon Default running, pid 28872 link/neighbord --uses ls0 -p 5000
bl0 daemon Default running, pid 28876 link/blacklistd --uses ls0 --provides bl0 --neighbors ls0
frag0 daemon Default running, pid 28889 link/fragd --uses bl0 --provides frag0
pingd_frag0 daemon Default running, pid 28896 link/examples/pingd --uses frag0
Default loglevels
-----------------.
Console: NOTICE
Logring: INFORMATIONAL
Syslog : OFF
-----
EmRun Config Files
------------------
EmRun Process Blocks
~~~~~~~~~~~~~~~~~~~~
EmRun uses a C-like syntax, composed of a sequence of `process`
blocks. Each `process` block tells EmRun what it needs to know to
start up that process, which other processes it depends on, and what
to do it the process exits unexpectedly.
The syntax for a `process` block is:
process <tag> {
<key> = <value>;
...
}
Where `<tag>` is a logical name for the process, and the key/value
pairs describe how to run the process. There are only two required
fields:
type = <respawn-type>;
cmd = "<command line string>";
where type is one of the following:
* `once`: Run the process once, do not respawn.
* `daemon`: Respawn the process whenever it dies.
* `boot`: Run the process once, serially, at boot only.
The command string may contain command line arguments but may not do
pipes, I/O redirection, or other syntax that is interpreted by the
shell. One way around this is to use `sh`, e.g.
cmd = "sh -c my_program > /tmp/output";
However, this will mean that your program will not be able to
establish a control channel to EmRun, and so won't be shut down
gracefully, etc.
There are several other key/value entries that can be included
in a `process` block:
* `emview`: Specifies a command to emview that will enable
visualization for that module.
* `waitfor`: Specifies a dependency on another process tag or
device file. EmRun will not start up a process until all
`waitfor` keys have been satisfied.
* `nice`: Set the "nice" level for this process.
* `loglevel`: Set the default loglevel for this process. Accepts
names (e.g. LOG_DEBUG_10, LOG_WARNING, etc) as arguments.
There are also some flags (keys without values) that can be added
to a process block:
* `no-sim`: Prevents a process from being run when in sim mode.
* `sim-only`: Only runs this process when in sim mode.
* `noclean`: Prevents a `once` process from having its logs
thrown out when it exits.
* `allow-core`: Generates cores on `SIGSEGV`, etc. Note, this
also requires a call to `ulimit` to enable cores before starting
EmRun.
* `no-core`: Disables generation of cores.
* `realtime`: Sets realtime bit (EmRun must have root permissions).
* `no-timewarp`: Disables "timewarp" feature for this process.
EmRun Includes and Macros
~~~~~~~~~~~~~~~~~~~~~~~~~
EmRun supports include files and a simple macro language. Include
files are invoked by
include <filename>
The filenames are parsed relative to the including file, or if that
fails, relative to the root of the build directory. For complete
transparency between deployment and other modes, it is preferred to
add `copy` targets to the build that copy `.run` files over into the
build directory, and thus for all `.run` files and includes to be
referenced through relative paths in that hierarchy. By doing this,
you can use the automated `--copy-deps` feature of EmRun to construct
a working build for your application.
Most EmRun modules can be instantiated by macros provided in a `.run`
file in the module's `include` directory. For example, to start
motenic:
include mote/mote.run
&mote_hostmote_bmac(/dev/ttyS0,mica2,0);
&mote_motenic(mote0,0,show="leds");
This includes `mote.run`, which defines several macros. (Note, that
the source for `mote/mote.run` is in `mote/include/mote.run`, but it
gets copied over to `obj.<platform>/mote/mote.run` during the build;
this provides transparency from deployment to simulation.) Then, it
instantiates macros to start up `hostmoted` and `motenicd`. The
advantage of using macros is that the complexity of correctly
configuring the `process` blocks is simplified to a few arguments.
For example, `process` block macros often include `emview` directives
that automatically configure the visualization, run the right command
line with reasonable defaults, and configure the proper `waitfor`
dependencies. Macros can also instantiate other macros and
sub-include files to bring in dependencies. For instance, most macros
automatically include `emproxy`.
EmRun macros are typically defined in `.run` files in the `include`
directories. Comments in the `.run` files, examples, and even
documentation can be used to determine how to correctly invoke the
macros.
When in doubt about what these macros do, you can always run `emrun
-E` to expand the macros into a pretty-printed `.run` file.
EmRun Variables
~~~~~~~~~~~~~~~
EmRun files can access environment variables, command line arguments,
and also set and modify their own variables.
For the most part, these variables work similarly to shell scripting.
Environment variables are accessed using the standard `$(ENVVAR)`
syntax. Command line arguments are accessed as `$1`, `$2`, etc.
Local variables are created by
set var = "value";
After which the value will be substituted for `$var`. All variables
substitutions take place within strings (i.e. inside double quotes).
In some cases quotes are needed to perform variable substitution, for
instance in the case of creating a process tag. In the following
example from link/include/link.run, the process tag is constructed
from a macro argument, and must be placed in quotes to parse
correctly:
macro link_neighbors(uses,period,show) {
# requires emproxy
&emproxy();
process "neighbors_$uses" {
type = daemon;
waitfor = $uses;
cmd = "link/neighbord --uses $uses -p $period";
emview = "module=Link/Neighbors:dev=$uses:links=>80,80,1,blue,show:$show";
}
}
(Note that the `link_neighbors` macro includes `emproxy` as a
dependency. EmRun will ignore duplicate `process` blocks, as long as
they are identical. This enables many module macros to include
`emproxy` without interfering with each other.)
See more files for this project here