Wiki » History » Version 16

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