Arguments

Introduction to Arguments

Actions and commands that OliveTin runs, without arguments, are generally quite safe - only that command can be run, without modifications. However, many users need the flexibility to set options on that command - normally called command line arguments. In OliveTin, arguments are defined in a shell commands like echo {{ message }}, with a bit of extra configuration.

Examples of valid argument names are {{ personName }}, {{ customer_number }} and {{ ISBN11_code }}.

  • a-z (case insensitive)

  • _ is allowed

  • numbers are allowed (argument names can also start with numbers)

  • all other characters are invalid for argument names.

Important Safety Warning

Before you continue, it’s important to read through this safety warning.

OliveTin supports customization of command line arguments, but there is a element of risk. For example, if your command is echo {{ message }}, and you allow your users to set {{ message }} to the value "" && rm -rf / , then you’ve got real problems. For this reason, OliveTin tries to give you useful ways to restrict what users are allowed to enter - with argument types.

However, here are some important rules to try and follow with argument types;

  • Use the most restrictive argument types when possible - ascii and int. This will stop users entering argument values that might be used dangerously, but it’s not foolproof. For example, if you have a command like createSnapshot.sh --count {{ snapshotCount }}, and set snapshotCount to int, then at least users will only be able to enter integer numbers. However, nothing stops them entering crazy values like 9999.

  • Don’t give access to actions with arguments to people you don’t trust. Please don’t ever put your OliveTin install on the public internet!

Argument types

A full list of argument types are below;

Argument types reference table
Type Rendered as Allowed values

(default)

Textbox

If a type: is not set, and choices: is empty, then ascii will be used, and a warning will be logged. It is recommended that you set the type explicitly, rather than relying on defaults.

ascii

Textbox

a-z (case insensitive), 0-9, but no spaces or punctuation

ascii_identifier

Textbox

Like a DNS name, a-Z (case insensitive), 0-9, -, ., and _.

ascii_sentence

Textbox

a-z (case insensitive), 0-9, with spaces, . and ,.

email

Textbox

An email address.

very_dangerous_raw_string

Textbox

Anything. This is incredibly dangerous, as effectively people can type anything they like, including executing additional commands beyond what you specify. Absolutely should not be used unless your OliveTin instance can only be used by people you trust entirely.

regex:…​

Textbox

Version 2024.03.081 and above support custom regex patterns. See Custom regex arguments.

int

Textbox

Any number, made up of the characters 0 to 9. Negative numbers are not supported.

url

Textbox

A url, e.g. https://github.com/OliveTin

confirmation

Confirmation

A "hidden" argument that makes the action require a confirmation before launching. See confirmation arguments.

n/a, but choices used

Dropdown

A "hidden" argument that makes the action require a confirmation before launching.

Input: Textbox

Many times you need to customize how an action/shell command is run, with arguments. For example;

echo "Hello world"

In the example above, Hello world is an argument passed to the echo command. OliveTin allows you to add pre-defined, and free-text arguments to commands in this way. Below is the OliveTin version of the echo command shown above;

config.yaml
actions:
  - title: echo a message
    icon: smile
    shell: echo {{ message }}
    arguments:
      - name: message
        default: Hello World
        type: ascii_sentence

actions:
  - title: Print a message
    shell: echo {{ message }}
    arguments:
      - name: message
        description: The message you want to print out on the shell.
        title: Your Message
        default: Hello World
        type: ascii_sentence

This will give you a normal button, like this;

args1

However, when you click on it, you’ll get a prompt to enter arguments, like this;

args2

You’ll see that the type is set to ascii_sentence. This applies fairly safe input validation to arguments, so that only a-z, 0-9, spaces and .'s are allowed.

When you start the action, and it’s finished, go to the "logs" view to view the output of the command we’ve just run.

args3

Custom regex

OliveTin version 2024.02.081 and above support custom regex patterns for argument types. Here is an example to validate against any 3 letter word;

The regex pattern should be enclosed in single quotes, otherwise you will probably get a YAML error when starting OliveTin.
config.yaml
actions:
  - title: echo a message
    icon: smile
    shell: echo "{{ message }}"
    arguments:
      - name: message
        type: 'regex:^\w\w\w$'

The site http://regex101.com is a good place to test your regex patterns.

Suggestions

Argument inputs can also have "suggested" values, which can make it quicker to type commonly used options. The way that these are displayed will vary depending on your browser, as they are implemented as a modern HTML5 browser feature called "datalist".

Suggestions are configured like this;

Configuration example of input suggestions
actions:
  - title: Restart Docker Container
    icon: restart
    shell: docker restart {{ container }}
    arguments:
      - name: container
        title: Container name
        suggestions:
          - plex:
          - graefik:
          - grafana:
          - wifi-controller: WiFi Controller
          - firewall-controller: Firewall Controller

In the examples above, there are 5 suggestions. The first 3 suggestions contain a suggestion with a blank title. The last 2 suggestions contain a human readable title (eg: wifi-controller is the suggestion, and WiFi Controller is the title).

suggestions: is a yaml map, not a list. If you leave the title empty you must still end the suggestion with a ":".

Examples

arg suggestions firefox
Figure 1. Screenshot of input suggestions with Firefox on Linux.
arg suggestions chrome
Figure 2. Screenshot of input suggestions with Chrome on Linux.

Browser Support

datalist is widely supported now-a-days, but Firefox on Android notably lacks support; https://caniuse.com/datalist . See the upstream bug here; https://bugzilla.mozilla.org/show_bug.cgi?id=1535985 .

Input: Dropdowns

Predefined choices are normally the safest type of arguments, because users are limited to only enter values that you specify.

actions:
  - title: echo a message
    icon: smile
    shell: echo "{{ message }}"
    arguments:
      - name: message
        choices:
          - title: Hello
            value: Hello there!

          - title: Goodbye
            value: Aww, goodbye. :-(

Note that when predefined choices are used, the argument type is ignored.

This is what it looks like in the web interface;

args4

Then finally, when you execute this command, it would look something like this (remember that this is just a basic "echo" command).

args choices exec

Using Entities in Dropdowns

Dropdowns can also be populated with a list of entities, like this;

config.yaml
actions:
  - title: restart container
    shell: 'docker restart {{ containerToRestart }}'
    arguments:
      - name: containerToRestart
        entity: container
        title: 'Select Container'
        choices:
          - value: '{{ container.Names }}'
            title: '{{ container.Names }}'

entities:
  - file: entities/containers.json
    name: container

This is what it looks like in the web interface;

args choices entities

Input: Confirmation

The confirmation type argument is a special argument type, which simply disables the "Start" button until a checkbox is ticked. This can be useful if you have an action with no other arguments, but you want to prevent accidental button-clicks starting the action.

actions:
  - title: Delete old backups
    icon: ashtonished
    shell: rm -rf /opt/oldBackups/
    arguments:
      - type: confirmation
        title: Are you sure?!
action confirmation

Notice in the webui the "start" button is disabled.

Input: DateTime

OliveTin supports datetime pickers - note that these do NOT add your timezone, so it up to your scripts / commands to interpret which timezone is being used.

config.yaml
actions:
  - title: Print your favourite datetime!
    shell: echo {{ my_favourite_time }}
    arguments:
      - type: datetime
        title: My Favourite DateTime
arg datetime

The OliveTin server does try to parse and validate the date on the server side to prevent dangerous input, but there is no validation in the browser, beyond what your browser might do to prevent you from picking an invalid date.

This is safe, as what really matters is what the server allows to be passed to be executed - and that is checked.

Environment variables

All arguments are also passed as environment variables as well, which can be very useful when passing several arguments to a script, for example.

config.yaml
actions:
  - title: Print names of new files
    shell: /opt/newfile.py
    arguments:
      - name: filename
        type: unicode_identifier

      - name: filesizebytes
        type: unicode_identifier

      - name: fileisdir
        type: unicode_identifier

    execOnFileCreatedInDir:
      - /home/user/Downloads/

This is an example of a python script using the environment variables;

/opt/newfile.py
#!/usr/bin/env python

import os

print(os.environ['OLIVETIN'])
print(os.environ['FILENAME'])
print(os.environ['FILESIZEBYTES'])
print(os.environ['FILEISDIR'])

Notes

  1. Argument names are converted to uppercase for environment variables, name: filename becomes FILENAME.

  2. OliveTin also passes an environment variable called OLIVETIN which is always just set to 1, which allow for scripts to detect if they are being run within OliveTin.

  3. The environment variables are passed into the execution context which uses a shell (/bin/sh on Linux), so it is also possible to use them with the $ notation in the shell line, like this; shell: echo $FILENAME for example.