vdemo

[[OldAiDocumentation|Documentation from old AI Trac]]

{{toc}}

h2. Shell environment

Every component shell script is executed within a shell environment that has loaded ~/.bashrc (as a non-interactive shell) as well as the vdemo master shell script provided as argument to vdemo2 commandline.

Additionally, all variables from the local environment that are listed within the shell variable $VDEMO_exports, will be exported to the remote shell environments.

h2. Component List Syntax

<pre>

COMPONENT LIST	

   Options:

      -w <n> wait n seconds for process to start completely

      -c     run check every second during wait and break if component is running

      -W <n> set delay when an asynchronous check is performed in case -w is not specified

      -l     activate initial logging for the component

      -x     use own X server for the component

      -n     do not include in level/group/auto start

      -g <s> allow to define a group (string: name of group)

      -L <n> component level, affects starting order (numeric: level)

      -d <n> detach time, automatically detaches screen after n seconds, or

             leaves it open all the time (-1), default is 10 seconds

      -t     title of the component / provide unique names for multiple instances on the same host

      -v     export variable varname=var to component script

      -Q     Stop the whole vdemo system in a clean fashion in case the respective components

             stops on its own (or is killed externally) but not when the stop button is pressed

      -R     auto-restart the component if it dies

      -r     auto-restart the component if it dies - after a confirmation dialog

</pre>

h2. Component Functions

h3. component

Called to start the component. All variables to be used in this function, either need to be exported to the environment beforehand or defined locally within the function.

Several processes can be launched in the @component@ function (and send to background). However, the main process should be launched last and *must not* be send to background.

The component is considered as stopped if the component function terminates, i.e. the last process terminates.

h3. stop_component

Stopping of components often needs to be customized to adapt to the special requirements of more complex components, starting several processes.

The default behaviour is to call @vdemo_stop_signal_children $1 SIGINT 2@, where $1 is the title of the component provided as an argument by vdemo, @SIGINT@ is the signal to use for stopping, and 2 is a 2sec timeout to wait for the processes to be stopped. 

This function sends the given signal to all top-level processes spawned in the function @component@.

However, some processes ignore SIGINT or take longer to shutdown. In this case you should customize the stopping behaviour, specifying an own @stop_component@ function.

An important example are shell scripts which are launched from the @component@ function: bash doesn't react to @SIGINT@ at all. Sending a @SIGTERM@ quits bash, but leaves launched child processes open.

A prominent example is MaryServer, which is launching java from a bash script within the @component@ function. This component requires the following stop function:

<pre>

function stop_component {

	local PIDS=$(all_children --filter bash\|tee\|screen $(vdemo_pidFromScreen $1))

	echo "killing processes $PIDS"

	kill -SIGINT $PIDS > /dev/null 2>&1

	for i in {1..50}; do

		sleep 0.1

		kill -0 $PIDS > /dev/null 2>&1 || break

	done

}

</pre>

The function @all_children@ provided by @vdemo@ lists all PIDs of the component's screen process and its children, eventually filtering out the given command names.

Subsequently, these processes can be killed. The loop waits for actual termination of those processes (with a timeout of 5s = 50*0.1s).

h3. on_check

Typically a component is considered to be running, when its corresponding screen process is alive. However, some components might be broken/not responding although there are still running.

To this end, the function @on_check@ can be provided. If present, the function is called additionally to the screen-process-alive test and its _return value_ is used to judge the state of the component.

If non-zero, the component is considered to be in an error state. A typical example is to check for responsiveness of a specific port:

<pre>

function on_check {

	nc -w 1 -z 0.0.0.0 "$SPREAD_PORT"

}

</pre>

Vice-versa, components might be running independently from vdemo, and thus often interfere with a demo. In this case on_check would indicate a running component, although no screen process is present. This is indicated in vdemo with orange component color. The following indicator colors are used:

table{border:0px}.

|{background:lightgray}.check|unknown|

|{background:yellow}.check|starting|

|{background:green}.check|running + responding|

|{background:orange}.check|responding, but not started from vdemo|

|{background:pink}.check|running, but not responding|

|{background:red}.check|not running|

h2. Spread configuration

To facilitate creation of spread configuration files, a spread configuration is automatically generated when no SPREAD_CONFIG environment variable is defined in the master script.

To this end, all machines where a spread daemon should be started, are grouped into segments using the _first_ three IP octets. For each segment an own spread multicast group is created

using the multicast IP address 225.xxx.yyy.zzz where the three octets xxx.yyy.zzz are the _last_ three IP octets of the first machine within a segment.

This way, we hope to ensure, that every setup configuration obtains its own multicast groups.

h2. vdemo2 commandline options

<pre>

-a  --auto               automatically start all components

-l  --log                enable logging for all components

-d  --detach time        set default detach time in seconds

                          0: start detached

                         <0: never detach

-r  --logrotate          enable log rotation

-v  --verbose [level]    set verbosity [level]

                         >0: increasing verbosity

                         -1: also suppress message boxes

-Q  --quit <components>  space separated list of components to quit vdemo on

</pre>