commands.adoc

qDup commands

Commands are the steps for qDup scripts. All of the comamnds can be created with a YAML key and scalar value, but some commands support mappings for more complex use cases.

- sh: cd /tmp/
- sh:
    command: rm -r test
    ignore-exit-code: true # will return error if test does not exist

Above is an example of the sh scalar and a more complicated mapping that sets the sh ignore-exit-code option.

Commands

Commands can be used in one of two ways:

• - command : <argumentString> Commands that support multiple arguments will try and parse the argumentString to identify the appropriate arguments.

• - command : { argumentName: argumentValue, …​} Arguments are explicitly mapped to the command’s declared argument names. This is the least ambiguous but most verbose and is rarely necessary.

Available commands

abort

Abort the run

add-prompt

Add a shell prompt

countdown

Count down a variable

ctrlC

Send ctrl+c to the ssh terminal

ctrl/

Send ctrl+/ to the ssh terminal

ctrlU

Send ctrl+U to the ssh terminal

ctrlZ

Send ctrl+Z to the ssh terminal

done

Tell qDup that the current stage is done

download

Download a file from the host

echo

Send the input to the console

exec

Send an exec command to the ssh terminal

for-each

Repeat the then command for each entry in the input

js

Run the javascript function

json

Evaluate a jsonpath expression against the input if the input is json

log

Write the message to the qDup run.log

parse

Use the parse library to parse the input

queue-download

Queue a file for download after the run or cleanup stage

read-signal

Read the current signal and invoke the then commands if it was signalled

read-state

Evaluate the state expression and invoke the then commands if it is not empty

regex

Match a Pattern to the input string

repeat-until

Repeat the then commands until the signal occurs

script

Run the named script

send-text

Send text to the current ssh terminal

set-signal

Set the expected number of signals for the named signal

sh

Send the sh command to the current ssh terminal

signal

Signal the named coordination point

sleep

Pause the current script for the desired duration

upload

Upload a local file to the remote host

wait-for

Wait for the named coordiation point to be fully signalled

xml

Perform the listed xml operations

Global options

The qDup commands require the top level command and can include some globally supported options.

silent

Does not include the command output in the qDup run.log. Mostly used with sh

- sh: tail -f server.log"
  silent: true

with

Add command specific state entries that will only be visible to the command and its children

- sh: echo "hello, ${{name}}"
  with:
    name: beth

watch

A list of commands that are invoked with each new line of output

- sh: tail -f server.log
  watch:
  - regex: ERROR
    then:
    - abort: error during start

then

A list of commands to run if this command exits normally. For example, regex will invoke the then commands it if matches, otherwise it invokes its else commands.

- sh: cd /tmp
  then:
  - sh: mkdir test

on-signal

A map of signal names and list of commands to run if the signal occurs while the parent command is running. This is primarily for long-running sh commands that may need to react to other scripts.

- sh: tail -f serer.log
  on-signal:
    READY:
    - ctrlC #end the tail when the server script signals READY

timer

A map of a duration to a list of commands to run if the current command is running after the duration. This too is promarily for long-running sh commands that need to have fixed time interactions.

- sh: collectStats.sh
  timer:
    60s:
    - ctrlC #only collect stats for 60s

prefix

Use a different state expression prefix. The default is ${{

- sh: echo "hello <<name}}"
  prefix: "<<"

suffix

use a different state expressing suffix. The default is }}

- sh: echo "hello ${{name>>"
  suffix: ">>"

separator

Use a different state expression separator. The default is :

- sh: echo "hello ${{name_friend}}"
  separator: "_"

js-prefix

Use a different javascript prefix. The default is =

- sh: echo ${{_ range(1,1)}}
  js-prefix: "_"

idle-timer

Set the idle checker timeout. This is mostly for long-running sh commands to avoid unecessary warning message.

- sh: doSometing.sh
  idle-timer: 30m #do not expect output for 30 minutes

state-scan

Set false to disable the static state analysis. qDup will abort if a state reference appears to occur before the value is defined but it cannot evaluate some expressions that are defined at runtime.

- sh: cat system.properties
- regex: (?<key>[^=]*)=(?<value>.*)
- sh: export ${{options.${{key}}}}="${{options.${{key}}.${{value}}"