> For the complete documentation index, see [llms.txt](https://documentation.hak5.org/packet-squirrel-mark-ii/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.hak5.org/packet-squirrel-mark-ii/advanced-payloads/payload-configuration.md).

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

```bash
SETTING_ONE="abc"
```

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

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

{% hint style="info" %}
More examples of advanced variable use are in the chapter "Quotes and Expansions":  Variables are extremely powerful!
{% endhint %}

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

```bash
SETTING_ONE="Y"

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

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

```bash
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:

```bash
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.

{% hint style="info" %}
Check the chapter "Flow Control" for more detailed information about the `if` and `case` tests!
{% endhint %}

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

```bash
#!/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,

```bash
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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://documentation.hak5.org/packet-squirrel-mark-ii/advanced-payloads/payload-configuration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.