Wiki » History » Version 12

R. Haschke, 06/25/2015 12:04 AM

1 1 J. Wienke
[[OldAiDocumentation|Documentation from old AI Trac]]
2 1 J. Wienke
3 10 R. Haschke
{{toc}}
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 12 R. Haschke
The variable @VDEMO_components@ is a colon-separated (@:@) list of components. Each component entry in turn is a comma-separated list of @component name@, @host@, @options@. The following component-specific options are available:
13 12 R. Haschke
14 1 J. Wienke
<pre>
15 12 R. Haschke
  -w <n> wait n seconds for process to start completely
16 12 R. Haschke
  -c     run check every second during wait and break if component is running
17 12 R. Haschke
  -W <n> set delay when an asynchronous check is performed in case -w is not specified
18 12 R. Haschke
  -l     activate initial logging for the component
19 12 R. Haschke
  -x     use own X server for the component
20 12 R. Haschke
  -n     do not include in level/group/auto start
21 12 R. Haschke
  -g <s> allow to define a group (string: name of group)
22 12 R. Haschke
  -L <n> component level, affects starting order (numeric: level)
23 12 R. Haschke
  -d <n> detach time, automatically detaches screen after n seconds, or
24 12 R. Haschke
         leaves it open all the time (-1), default is 10 seconds
25 12 R. Haschke
  -t     title of the component / provide unique names for multiple instances on the same host
26 12 R. Haschke
  -v     export variable varname=var to component script
27 12 R. Haschke
  -Q     Stop the whole vdemo system in a clean fashion in case the respective components
28 12 R. Haschke
         stops on its own (or is killed externally) but not when the stop button is pressed
29 12 R. Haschke
  -R     auto-restart the component if it dies
30 12 R. Haschke
  -r     auto-restart the component if it dies - after a confirmation dialog
31 11 R. Haschke
</pre>
32 12 R. Haschke
33 12 R. Haschke
To organize a plenty of components more clearly, they can be arranged on tabs. To this end, insert the name of the tab into the components list (again colon-separated from other components, but without comma-separated list of other infos). All subsequent components will show up on the most recently mentioned tab.
34 1 J. Wienke
35 3 R. Haschke
h2. Component Functions
36 3 R. Haschke
37 3 R. Haschke
h3. component
38 3 R. Haschke
39 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.
40 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.
41 3 R. Haschke
The component is considered as stopped if the component function terminates, i.e. the last process terminates.
42 3 R. Haschke
43 3 R. Haschke
h3. stop_component
44 3 R. Haschke
45 3 R. Haschke
Stopping of components often needs to be customized to adapt to the special requirements of more complex components, starting several processes.
46 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. 
47 3 R. Haschke
This function sends the given signal to all top-level processes spawned in the function @component@.
48 3 R. Haschke
49 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.
50 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.
51 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:
52 3 R. Haschke
53 3 R. Haschke
<pre>
54 4 R. Haschke
function stop_component {
55 3 R. Haschke
	local PIDS=$(all_children --filter bash\|tee\|screen $(vdemo_pidFromScreen $1))
56 3 R. Haschke
	echo "killing processes $PIDS"
57 3 R. Haschke
	kill -SIGINT $PIDS > /dev/null 2>&1
58 3 R. Haschke
	for i in {1..50}; do
59 3 R. Haschke
		sleep 0.1
60 3 R. Haschke
		kill -0 $PIDS > /dev/null 2>&1 || break
61 3 R. Haschke
	done
62 4 R. Haschke
}
63 3 R. Haschke
</pre>
64 3 R. Haschke
65 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.
66 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).
67 3 R. Haschke
68 3 R. Haschke
h3. on_check
69 3 R. Haschke
70 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.
71 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.
72 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:
73 5 R. Haschke
74 5 R. Haschke
<pre>
75 5 R. Haschke
function on_check {
76 5 R. Haschke
	nc -w 1 -z 0.0.0.0 "$SPREAD_PORT"
77 5 R. Haschke
}
78 5 R. Haschke
</pre>
79 5 R. Haschke
80 3 R. Haschke
81 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:
82 3 R. Haschke
83 3 R. Haschke
table{border:0px}.
84 3 R. Haschke
|{background:lightgray}.check|unknown|
85 3 R. Haschke
|{background:yellow}.check|starting|
86 3 R. Haschke
|{background:green}.check|running + responding|
87 3 R. Haschke
|{background:orange}.check|responding, but not started from vdemo|
88 3 R. Haschke
|{background:pink}.check|running, but not responding|
89 3 R. Haschke
|{background:red}.check|not running|
90 7 R. Haschke
91 7 R. Haschke
h2. Spread configuration
92 7 R. Haschke
93 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.
94 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
95 1 J. Wienke
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.
96 1 J. Wienke
This way, we hope to ensure, that every setup configuration obtains its own multicast groups.
97 10 R. Haschke
98 10 R. Haschke
h2. vdemo2 commandline options
99 10 R. Haschke
100 10 R. Haschke
<pre>
101 10 R. Haschke
-a  --auto               automatically start all components
102 10 R. Haschke
-l  --log                enable logging for all components
103 10 R. Haschke
-d  --detach time        set default detach time in seconds
104 10 R. Haschke
                          0: start detached
105 10 R. Haschke
                         <0: never detach
106 10 R. Haschke
-r  --logrotate          enable log rotation
107 10 R. Haschke
-v  --verbose [level]    set verbosity [level]
108 10 R. Haschke
                         >0: increasing verbosity
109 10 R. Haschke
                         -1: also suppress message boxes
110 10 R. Haschke
-Q  --quit <components>  space separated list of components to quit vdemo on
111 10 R. Haschke
</pre>