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 | {{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 | 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 | </pre> |
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 | Example |
36 | 14 | N. Köster | |
37 | 14 | N. Köster | <pre> |
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 | components: |
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 | moreComponents: |
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 | </pre> |
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 | <pre> |
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 | done |
79 | 4 | R. Haschke | } |
80 | 3 | R. Haschke | </pre> |
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 | <pre> |
92 | 5 | R. Haschke | function on_check { |
93 | 5 | R. Haschke | nc -w 1 -z 0.0.0.0 "$SPREAD_PORT" |
94 | 5 | R. Haschke | } |
95 | 5 | R. Haschke | </pre> |
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 | table{border:0px}. |
101 | 3 | R. Haschke | |{background:lightgray}.check|unknown| |
102 | 3 | R. Haschke | |{background:yellow}.check|starting| |
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 225.xxx.yyy.zzz 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 | <pre> |
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 | accepting: |
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 | </pre> |