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> |