Payload configuration

Often for more complex payloads you will want to give the user (or even just yourself) a simple way to change the payload behavior.

The easiest way to accomplish this is with standard variables.

Variables

Variables are assigned in payloads by setting a name to the value; for instance:

SETTING_ONE="abc"

Variables can be set to strings or numbers, or even the output of other commands:

# Set the variable SPACE to the output of the USB_FREE command
SPACE=$(USB_FREE)

More examples of advanced variable use are in the chapter "Quotes and Expansions": Variables are extremely powerful!

Simple tests

To actually use the results of a configuration option, there are multiple ways to test how it is set.

The simplest test is to compare if a variable is equal to a fixed value:

SETTING_ONE="Y"

if [ ${SETTING_ONE} = "Y" ]; then
    LED SUCCESS
fi

This can, of course, also be combined with the else construct:

SETTING_ONE="Y"

if [ ${SETTING_ONE} = "Y" ]; then
    LED SUCCESS
else
    LED FAIL
fi

Complex tests

More complex tests can be created with the case statement:

SETTING_ONE="A"

case "${SETTING_ONE}" in
    "A")
        echo "Option A"
        ;;
    "B")
        echo "Option B"
        ;;
    "C")
        echo "Option C"
        ;;
    *)
        echo "Unknown option"
        ;;
esac

The case test allows us to match multiple options with a default final option if nothing else matches.

Check the chapter "Flow Control" for more detailed information about the if and case tests!

Payload configuration

When making a payload that accepts configuration options, we recommend placing all the options at the top of the payload so that they are easy to find. This way, users of your payload (or your own future self who has forgotten all the complexities of the payload) can easily change the setup.

It's also a good idea to include a description of the configuration variable, and how to use it, as a comment.

Whenever possible, provide a default value that makes sense.

#!/bin/bash

# Title: Demo options
#
# Description: Generic demo payload 

# Configuration options

# REPEAT_COUNT - How many times do we attempt the payload?
REPEAT_COUNT=5

# NETWORK_INTERFACE - What network interface do we use?
NETWORK_INTERFACE="br-lan"

Since a payload does not typically run interactively (the user will never see the output of echo or similar), the LED command is the primary way to communicate errors. For example continuing the payload from above,

if [ "$REPEAT_COUNT" -le 3 ]; then
    LED FAIL
    exit 1
fi

Here we confirm the user has entered a sane configuration option, set the LED to error state, and exit the payload entirely.

Configuration names

There is no strict requirement when it comes to the naming of configuration variables, however it is a good idea to:

• Keep them entirely upper case. This makes it easy to spot them in the code.

• Give them meaningful names. This helps you remember them during the rest of the payload. Naming configuration variables A, B, and so on is certainly possible, but don't.