User Tools

Site Tools


scenario_file_format

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
scenario_file_format [2017/10/20 11:21]
mimbert [Grammar]
scenario_file_format [2019/12/03 11:05] (current)
mimbert
Line 11: Line 11:
 The syntax of a yaml file may be checked with http://​www.yamllint.com/​ The syntax of a yaml file may be checked with http://​www.yamllint.com/​
 ====== Grammar ====== ====== Grammar ======
 +
 +We're progressively adding new capabilities to the CorteXlab platform. There is now two different syntaxes for the scenario file, the legacy syntax, where commands are run on the nodes, and the new syntax, where [[docker|docker]] containers are run on the nodes. Both syntaxes are allowed, even in the same scenario, but only one syntax is allowed per-node.
  
 The scenario.yaml file is structured as follows: The scenario.yaml file is structured as follows:
-  * It //MUST// contain a //description// key, value pair whose value is a string: ''​description:​ <​string>''​ +  * It //MUST// contain a ''​description'' ​key, value pair whose value is a string. 
-  * It //MUST// contain a //duration// key, value pair, whose value is an integer, the max experiment duration expressed in seconds: ''​duration:​ <​integer>''​ +  * It //MUST// contain a ''​duration'' ​key, value pair, whose value is an integer, the max experiment duration expressed in seconds. 
-  * It //MUST// contain a //nodes// key, whose value is a mapping (aka hash, or dictionnary): ''​nodes:''​. This mapping //MUST// contain: +  * It //MUST// contain a ''​nodes'' ​key, whose value is a mapping (aka hash, or dictionnary). This mapping //MUST// contain: 
-    * Nodes key, value pairs, whose keys are the node names (in the set //node1// to //node40//, and whose values are mappings: +    * Nodes key, value pairs, whose keys are the node names (in the set ''​node1'' ​to ''​node40''​), and whose values are mappings: 
-      * which //MUST// contain ​//command// key, value pair, whose value is the command ​line string which will be run on the corresponding ​node''​command: <​string>​''​. Note that any filesystem path may be absolute or relative. If relative, it will be relative to the task top directory on the node. Note also that minus does NO magic with filesystem permissions,​ thus if a script or binary is to be executed, it needs to have executable permissions set before creating the task. The //command// may also, if needed, contain a list of commands to be executed, instead of a single command. All the commands will be executed in parallel on the node. In this case, the syntax is multiline: <​code>​+      * which //MUST// contain ​**//ONLY ONE//** of the following:​ 
 +        * **(new syntax)** a ''​container'' ​key, value pair, whose value is a mapping with the following key, value pairs: 
 +          * ''​image''​ //​MANDATORY//​ a string, the name of the docker image, which must be accessible on a public docker repository (such as the docker hub). See [[docker images]] 
 +          * ''​command''​ //​OPTIONAL//​ a string, the command to run in the container, ​which overrides the image default command (see https://​docs.docker.com/​engine/​reference/​run/#​cmd-default-command-or-options https://​docs.docker.com/​engine/​reference/​builder/#​cmd) 
 +          * ''​exec''​ //​OPTIONAL//​ a string or array of strings: additionnal commands which are executed in the container (see https://​docs.docker.com/​engine/​reference/​commandline/​exec/​) 
 +          * ''​name''​ //​OPTIONAL//​ a string for specifying the container'​s name. If not given, a default name will be automatically generated, with the minus task number and the container rank on the node
 +        * **(old syntax)** a ''​command'' ​key, value pair, whose value is the command line string which will be run on the corresponding node. Note that any filesystem path may be absolute or relative. If relative, it will be relative to the task top directory on the node. Note also that minus does NO magic with filesystem permissions,​ thus if a script or binary is to be executed, it needs to have executable permissions set before creating the task. The ''​command'' ​may also, if needed, contain a list of commands to be executed, instead of a single command. All the commands will be executed in parallel on the node. In this case, the syntax is multiline: <​code>​
 nodes: nodes:
   node1:   node1:
Line 23: Line 31:
     - sleep 10000     - sleep 10000
     - ./my_script     - ./my_script
-</​code>​ In the usual case where only one command is given, its stdout/​stderr go to files //stdout.txt// and //stderr.txt//. In the case where more than one commands are given, their stdout/​stderr go to files //stdout<​X>​.txt// and //stderr<​X>​.txt//, where X is the command index (starting from zero). +</​code>​ In the usual case where only one command is given, its stdout/​stderr go to files ''​stdout.txt'' ​and ''​stderr.txt''​. In the case where more than one commands are given, their stdout/​stderr go to files ''​stdout<​X>​.txt'' ​and ''​stderr<​X>​.txt''​, where X is the command index (starting from zero). 
-      * which //MAY// contain a //passive// key, value pair, whose value is a boolean (default is ''​false''​). A minus task will terminate when the first of the following conditions occur: its //​duration//​ is exceeded or all its //active// nodes terminate.+      * which //MAY// contain a ''​passive'' ​key, value pair, whose value is a boolean (default is ''​false''​). A minus task will terminate when the first of the following conditions occur: its //​duration//​ is exceeded or all its //active// nodes terminate.
  
-Thus, an example scenario ​could be:+An example scenario ​(new syntax):<​code>​ 
 +description:​ Example of new syntax with docker containers 
 +duration: 120 
 +nodes: 
 +  node3: 
 +    container:​ 
 +    - image: m1mbert/​cxlb-gnuradio-3.8:​1.0 
 +    - image: m1mbert/​cxlb-gnuradio-3.8:​1.0 
 +      command: /​usr/​sbin/​sshd -p 2223 -D 
 +  node4: 
 +    container:​ 
 +      image: m1mbert/​openbts-xenial:​1.1 
 +</​code>​Note that in this example, on node3, two containers are instanciated,​ based on the same image. The first container does not specify a ''​command'',​ so the default command of the image is used, which is an ssh daemon listening on port 2222. The second container overrides the default command with an ssh daemon listening on port 2223 (if we try to instanciate two identical containers from this image, both ssh daemons will try to bind to port 2222 and the second one will fail)
  
-<​code>​+An example scenario (old syntax):<​code>​
 description:​ Dummy scenario example description:​ Dummy scenario example
 duration: 60 duration: 60
scenario_file_format.1508491314.txt.gz · Last modified: 2017/10/20 11:21 by mimbert