Wiki » History » Version 11

R. Haschke, 06/22/2015 11:27 PM

1 1 J. Wienke
[[OldAiDocumentation|Documentation from old AI Trac]]
2 1 J. Wienke
3 10 R. Haschke
4 10 R. Haschke
5 10 R. Haschke
h2. Shell environment
6 10 R. Haschke
7 10 R. Haschke
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.
8 10 R. Haschke
Additionally, all variables from the local environment that are listed within the shell variable $VDEMO_exports, will be exported to the remote shell environments.
9 10 R. Haschke
10 2 J. Wienke
h2. Component List Syntax
11 2 J. Wienke
12 2 J. Wienke
13 2 J. Wienke
14 2 J. Wienke
15 2 J. Wienke
      -w <n> wait n seconds for process to start completely
16 1 J. Wienke
      -c     run check every second during wait and break if component is running
17 3 R. Haschke
      -W <n> set delay when an asynchronous check is performed in case -w is not specified
18 1 J. Wienke
      -l     activate initial logging for the component
19 2 J. Wienke
      -x     use own X server for the component
20 3 R. Haschke
      -n     do not include in level/group/auto start
21 2 J. Wienke
      -g <s> allow to define a group (string: name of group)
22 2 J. Wienke
      -L <n> component level, affects starting order (numeric: level)
23 2 J. Wienke
      -d <n> detach time, automatically detaches screen after n seconds, or
24 2 J. Wienke
             leaves it open all the time (-1), default is 10 seconds
25 2 J. Wienke
      -t     title of the component / provide unique names for multiple instances on the same host
26 1 J. Wienke
      -v     export variable varname=var to component script
27 9 J. Wienke
      -Q     Stop the whole vdemo system in a clean fashion in case the respective components
28 9 J. Wienke
             stops on its own (or is killed externally) but not when the stop button is pressed
29 11 R. Haschke
      -R     auto-restart the component if it dies
30 11 R. Haschke
      -r     auto-restart the component if it dies - after a confirmation dialog
31 1 J. Wienke
32 1 J. Wienke
33 3 R. Haschke
h2. Component Functions
34 3 R. Haschke
35 3 R. Haschke
h3. component
36 3 R. Haschke
37 3 R. Haschke
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.
38 3 R. Haschke
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.
39 3 R. Haschke
The component is considered as stopped if the component function terminates, i.e. the last process terminates.
40 3 R. Haschke
41 3 R. Haschke
h3. stop_component
42 3 R. Haschke
43 3 R. Haschke
Stopping of components often needs to be customized to adapt to the special requirements of more complex components, starting several processes.
44 3 R. Haschke
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. 
45 3 R. Haschke
This function sends the given signal to all top-level processes spawned in the function @component@.
46 3 R. Haschke
47 3 R. Haschke
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.
48 3 R. Haschke
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.
49 3 R. Haschke
A prominent example is MaryServer, which is launching java from a bash script within the @component@ function. This component requires the following stop function:
50 3 R. Haschke
51 3 R. Haschke
52 4 R. Haschke
function stop_component {
53 3 R. Haschke
	local PIDS=$(all_children --filter bash\|tee\|screen $(vdemo_pidFromScreen $1))
54 3 R. Haschke
	echo "killing processes $PIDS"
55 3 R. Haschke
	kill -SIGINT $PIDS > /dev/null 2>&1
56 3 R. Haschke
	for i in {1..50}; do
57 3 R. Haschke
		sleep 0.1
58 3 R. Haschke
		kill -0 $PIDS > /dev/null 2>&1 || break
59 3 R. Haschke
60 4 R. Haschke
61 3 R. Haschke
62 3 R. Haschke
63 3 R. Haschke
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.
64 3 R. Haschke
Subsequently, these processes can be killed. The loop waits for actual termination of those processes (with a timeout of 5s = 50*0.1s).
65 3 R. Haschke
66 3 R. Haschke
h3. on_check
67 3 R. Haschke
68 3 R. Haschke
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.
69 6 R. Haschke
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.
70 5 R. Haschke
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:
71 5 R. Haschke
72 5 R. Haschke
73 5 R. Haschke
function on_check {
74 5 R. Haschke
	nc -w 1 -z "$SPREAD_PORT"
75 5 R. Haschke
76 5 R. Haschke
77 5 R. Haschke
78 3 R. Haschke
79 3 R. Haschke
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:
80 3 R. Haschke
81 3 R. Haschke
82 3 R. Haschke
83 3 R. Haschke
84 3 R. Haschke
|{background:green}.check|running + responding|
85 3 R. Haschke
|{background:orange}.check|responding, but not started from vdemo|
86 3 R. Haschke
|{background:pink}.check|running, but not responding|
87 3 R. Haschke
|{background:red}.check|not running|
88 7 R. Haschke
89 7 R. Haschke
h2. Spread configuration
90 7 R. Haschke
91 7 R. Haschke
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.
92 7 R. Haschke
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
93 1 J. Wienke
using the multicast IP address where the three octets xxx.yyy.zzz are the _last_ three IP octets of the first machine within a segment.
94 1 J. Wienke
This way, we hope to ensure, that every setup configuration obtains its own multicast groups.
95 10 R. Haschke
96 10 R. Haschke
h2. vdemo2 commandline options
97 10 R. Haschke
98 10 R. Haschke
99 10 R. Haschke
-a  --auto               automatically start all components
100 10 R. Haschke
-l  --log                enable logging for all components
101 10 R. Haschke
-d  --detach time        set default detach time in seconds
102 10 R. Haschke
                          0: start detached
103 10 R. Haschke
                         <0: never detach
104 10 R. Haschke
-r  --logrotate          enable log rotation
105 10 R. Haschke
-v  --verbose [level]    set verbosity [level]
106 10 R. Haschke
                         >0: increasing verbosity
107 10 R. Haschke
                         -1: also suppress message boxes
108 10 R. Haschke
-Q  --quit <components>  space separated list of components to quit vdemo on
109 10 R. Haschke