Wiki » History » Version 19

R. Haschke, 08/30/2017 04:52 PM

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 19 R. Haschke
  -w <n> timeout (seconds) for a process to become ready after start (default: 5s)
16 19 R. Haschke
         If zero or negative, vdemo will wait forever for this component, frequently checking it.
17 19 R. Haschke
  -W <n> time (seconds) when to check a component after start the first time
18 19 R. Haschke
         Only takes effect, when -w 0 is specified. 
19 12 R. Haschke
  -l     activate initial logging for the component
20 12 R. Haschke
  -x     use own X server for the component
21 12 R. Haschke
  -n     do not include in level/group/auto start
22 12 R. Haschke
  -g <s> allow to define a group (string: name of group)
23 12 R. Haschke
  -L <n> component level, affects starting order (numeric: level)
24 12 R. Haschke
  -d <n> detach time, automatically detaches screen after n seconds, or
25 12 R. Haschke
         leaves it open all the time (-1), default is 10 seconds
26 12 R. Haschke
  -t     title of the component / provide unique names for multiple instances on the same host
27 12 R. Haschke
  -v     export variable varname=var to component script
28 12 R. Haschke
  -Q     Stop the whole vdemo system in a clean fashion in case the respective components
29 12 R. Haschke
         stops on its own (or is killed externally) but not when the stop button is pressed
30 12 R. Haschke
  -R     auto-restart the component if it dies
31 12 R. Haschke
  -r     auto-restart the component if it dies - after a confirmation dialog
32 11 R. Haschke
</pre>
33 12 R. Haschke
34 14 N. Köster
h3. Tabs
35 14 N. Köster
36 14 N. Köster
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.
37 14 N. Köster
Example
38 14 N. Köster
39 14 N. Köster
<pre>
40 14 N. Köster
export VDEMO_components="
41 14 N. Köster
spreaddaemon,${PC_CORE_1},-l -w 0 -g spread -L 0:
42 14 N. Köster
spreaddaemon,${PC_CORE_2},-l -w 0 -g spread -L 0:
43 14 N. Köster
components:
44 14 N. Köster
device-manager,${PC_HOMEAUTOMATION},-l -g homeautomation -v DB_PATH=$datadir/db/device-db -L 1:
45 14 N. Köster
location-manager,${PC_HOMEAUTOMATION},-l -g homeautomation -v DB_PATH=$datadir/db/location-db -L 1:
46 14 N. Köster
moreComponents:
47 14 N. Köster
roscore,${PC_FLOBI_WARDROBE},-l -t roscore_wardrobe -w 4 -g flobi_w -L 1:
48 14 N. Köster
roscore,${PC_FLOBI_KITCHEN},-l -t roscore_kitchen -w 4 -g flobi_k -L 1:
49 14 N. Köster
"
50 14 N. Köster
</pre>
51 14 N. Köster
52 14 N. Köster
Please note that the $VDEMO_components variable *needs to start with a component and not a tab definition*!
53 1 J. Wienke
54 3 R. Haschke
h2. Component Functions
55 3 R. Haschke
56 3 R. Haschke
h3. component
57 3 R. Haschke
58 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.
59 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.
60 3 R. Haschke
The component is considered as stopped if the component function terminates, i.e. the last process terminates.
61 3 R. Haschke
62 3 R. Haschke
h3. stop_component
63 3 R. Haschke
64 3 R. Haschke
Stopping of components often needs to be customized to adapt to the special requirements of more complex components, starting several processes.
65 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. 
66 3 R. Haschke
This function sends the given signal to all top-level processes spawned in the function @component@.
67 3 R. Haschke
68 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.
69 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.
70 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:
71 3 R. Haschke
72 3 R. Haschke
<pre>
73 4 R. Haschke
function stop_component {
74 3 R. Haschke
	local PIDS=$(all_children --filter bash\|tee\|screen $(vdemo_pidFromScreen $1))
75 3 R. Haschke
	echo "killing processes $PIDS"
76 3 R. Haschke
	kill -SIGINT $PIDS > /dev/null 2>&1
77 3 R. Haschke
	for i in {1..50}; do
78 3 R. Haschke
		sleep 0.1
79 3 R. Haschke
		kill -0 $PIDS > /dev/null 2>&1 || break
80 3 R. Haschke
	done
81 4 R. Haschke
}
82 3 R. Haschke
</pre>
83 3 R. Haschke
84 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.
85 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).
86 3 R. Haschke
87 18 R. Haschke
h3. on_stop
88 18 R. Haschke
89 18 R. Haschke
After stopping a component using stop_component, some cleanup code can be executed by defining the function on_stop.
90 18 R. Haschke
91 18 R. Haschke
To summarize, when stopping a component, the following things happen:
92 18 R. Haschke
- stop_component is called (if defined, otherwise: vdemo_stop_signal_children $1 SIGINT 2)
93 18 R. Haschke
- if there are any remaining processes originally associated to that component, they will be killed
94 18 R. Haschke
- finally, on_stop will we called for some cleanup
95 18 R. Haschke
96 3 R. Haschke
h3. on_check
97 3 R. Haschke
98 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.
99 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.
100 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:
101 5 R. Haschke
102 5 R. Haschke
<pre>
103 5 R. Haschke
function on_check {
104 5 R. Haschke
	nc -w 1 -z 0.0.0.0 "$SPREAD_PORT"
105 5 R. Haschke
}
106 5 R. Haschke
</pre>
107 5 R. Haschke
108 3 R. Haschke
109 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:
110 3 R. Haschke
111 3 R. Haschke
table{border:0px}.
112 3 R. Haschke
|{background:lightgray}.check|unknown|
113 3 R. Haschke
|{background:yellow}.check|starting|
114 3 R. Haschke
|{background:green}.check|running + responding|
115 3 R. Haschke
|{background:orange}.check|responding, but not started from vdemo|
116 3 R. Haschke
|{background:pink}.check|running, but not responding|
117 3 R. Haschke
|{background:red}.check|not running|
118 7 R. Haschke
119 7 R. Haschke
h2. Spread configuration
120 7 R. Haschke
121 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.
122 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
123 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.
124 1 J. Wienke
This way, we hope to ensure, that every setup configuration obtains its own multicast groups.
125 10 R. Haschke
126 10 R. Haschke
h2. vdemo2 commandline options
127 10 R. Haschke
128 10 R. Haschke
<pre>
129 10 R. Haschke
-a  --auto               automatically start all components
130 10 R. Haschke
-l  --log                enable logging for all components
131 10 R. Haschke
-d  --detach time        set default detach time in seconds
132 10 R. Haschke
                          0: start detached
133 10 R. Haschke
                         <0: never detach
134 10 R. Haschke
-r  --logrotate          enable log rotation
135 10 R. Haschke
-v  --verbose [level]    set verbosity [level]
136 10 R. Haschke
                         >0: increasing verbosity
137 10 R. Haschke
                         -1: also suppress message boxes
138 16 R. Haschke
-f  --fifo <file>        create fifo for text-based remote-control of vdemo gui
139 16 R. Haschke
                         accepting:
140 16 R. Haschke
                         (start | stop | check) (<component> | <group> | ALL)
141 17 R. Haschke
-Q  --quit <components>  space separated list of components to quit vdemo on
142 10 R. Haschke
</pre>