OliveTin

https://docs.olivetin.app
Admin
OliveTin provides a web interface for safely and simply executing predefined shell commands, making...
Tokens:120,444
Snippets:1,995
Trust Score:7.4
Update:2 months ago
Show doc for...
Tokens:
Raw
### Complete Configuration Example

Source: https://docs.olivetin.app/action_customization/enabledExpression.html

A full example demonstrating entity definitions, actions with enabledExpression, and dashboard integration.

```yaml
entities:
  - file: /etc/OliveTin/lights.yaml
    name: light

actions:
  - title: Turn On Light
    shell: /opt/smart-home/light-control.sh on {{ .CurrentEntity.id }}
    icon: 💡
    entity: light
    enabledExpression: "{{ eq .CurrentEntity.powered_on false }}"

  - title: Turn Off Light
    shell: /opt/smart-home/light-control.sh off {{ .CurrentEntity.id }}
    icon: 🔌
    entity: light
    enabledExpression: "{{ eq .CurrentEntity.powered_on true }}"

dashboards:
  - title: Light Controls
    contents:
      - title: Lights
        type: fieldset
        entity: light
        contents:
          - type: display
            title: |
              <strong>{{ .CurrentEntity.name }}</strong>
          - title: Turn On Light
          - title: Turn Off Light
```

```yaml
- id: kitchen
  name: Kitchen Light
  powered_on: false

- id: living_room
  name: Living Room Light
  powered_on: true
```

--------------------------------

### Startup Action for Package Installation

Source: https://docs.olivetin.app/action_execution/onstartup.html

Use execOnStartup to install system packages. Note that this requires OliveTin to be running with root privileges.

```yaml
actions:
  - title: Install dnsmasq
    shell: microdnf install bind-utils
    execOnStartup: true
```

--------------------------------

### Start OliveTin

Source: https://docs.olivetin.app/install/macos.html

Execute the binary from the terminal to start the application.

```shell
./OliveTin
```

--------------------------------

### Define Docker Control Actions

Source: https://docs.olivetin.app/action_examples/containers.html

Example configuration for stopping and starting a container using shell commands.

```yaml
actions:
  - title: Stop Plex
    shell: docker stop plex

  - title: Start plex
    shell: docker start plex
```

--------------------------------

### Enable and start OliveTin service

Source: https://docs.olivetin.app/install/linux_arch.html

Use systemctl to enable and start the OliveTin service.

```shell
user@host: systemctl enable --now OliveTin
```

--------------------------------

### GET /StartActionByGetAndWait

Source: https://docs.olivetin.app/llm-full.txt

Starts an action via GET and waits for it to complete.

```APIDOC
## GET /StartActionByGetAndWait

### Description
Starts an action via a GET request using the Action ID in the URL and waits for the execution to finish.

### Method
GET

### Endpoint
/StartActionByGetAndWait
```

--------------------------------

### Manual installation commands

Source: https://docs.olivetin.app/llm-full.txt

Commands required for setting up the OliveTin binary and configuration directories during a manual installation.

```bash
chmod +x /usr/local/bin/OliveTin
```

```bash
mkdir -p /etc/OliveTin
```

--------------------------------

### Start the OliveTin service

Source: https://docs.olivetin.app/install/podmandocker.html

Launch the created container.

```asciidoc
user@host: docker start olivetin
```

--------------------------------

### Install OliveTin via pamac

Source: https://docs.olivetin.app/install/linux_manjaro.html

Commands to update the PATH, install the required buf tool, install the OliveTin package, and create necessary configuration directories.

```bash
PATH=$PATH:~/go/bin/
pamac install buf
pamac install olivetin
sudo mkdir -p /etc/OliveTin/custom-webui/themes/
sudo mkdir -p /etc/OliveTin/entities/
```

--------------------------------

### View directory layout

Source: https://docs.olivetin.app/install/macos_service.html

The expected file structure after installation.

```asciidoc
/usr/local/bin/OliveTin
/usr/local/etc/OliveTin/
├── config.yaml
├── webui/
└── var/

/usr/local/var/log/olivetin.log   # service stdout/stderr
```

--------------------------------

### Install OliveTin via Helm

Source: https://docs.olivetin.app/install/helm.html

Add the official OliveTin Helm repository and install the chart into the cluster.

```shell
user@host: helm repo add olivetin https://olivetin.github.io/OliveTin-HelmChart/
user@host: helm install olivetin olivetin/olivetin
NAME: olivetin
LAST DEPLOYED: Tue Apr  1 23:19:09 2025
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None
```

--------------------------------

### Register and start the service

Source: https://docs.olivetin.app/install/macos_service.html

Copy the plist file to the LaunchDaemons directory, set ownership, and bootstrap the service.

```shell
sudo cp app.olivetin.olivetin.plist /Library/LaunchDaemons/
sudo chown root:wheel /Library/LaunchDaemons/app.olivetin.olivetin.plist
sudo launchctl bootstrap system /Library/LaunchDaemons/app.olivetin.olivetin.plist
```

--------------------------------

### GET /api/StartActionByGet

Source: https://docs.olivetin.app/api/method_StartAction.html

Starts an action by passing the Action ID directly in the URL.

```APIDOC
## GET /api/StartActionByGet

### Description
Starts an action by providing the Action ID in the URL.

### Method
GET

### Endpoint
/api/StartActionByGet

### Response
- **Execution Tracking ID** (string) - The ID used to track the execution of the action.
```

--------------------------------

### Using Shell

Source: https://docs.olivetin.app/action_execution/shellvsexec.html

Example configuration using the shell method to execute a command string.

```yaml
actions:
  - title: List files
	shell: ls -l /some/directory
```

--------------------------------

### Start the Windows Service

Source: https://docs.olivetin.app/install/windows_service.html

Initiate the registered service using the Service Control Manager.

```bash
sc.exe start OliveTin
```

--------------------------------

### Install OliveTin via RPM

Source: https://docs.olivetin.app/install/linux_fedora.html

Install the latest version of OliveTin directly from the project's GitHub releases.

```bash
root@host: rpm -U https://github.com/OliveTin/OliveTin/releases/latest/download/OliveTin_linux_amd64.rpm
```

--------------------------------

### GET /StartActionByGet

Source: https://docs.olivetin.app/llm-full.txt

Starts an action using the Action ID provided in the URL.

```APIDOC
## GET /StartActionByGet

### Description
Starts an action via a GET request using the Action ID in the URL.

### Method
GET

### Endpoint
/StartActionByGet
```

--------------------------------

### Test OliveTin Startup

Source: https://docs.olivetin.app/install/windows_service.html

Verify the application starts correctly by executing the binary directly from the command prompt.

```bash
./OliveTin.exe
```

--------------------------------

### GET /StartActionByGetAndWait

Source: https://docs.olivetin.app/llm-full.txt

Starts an action by ID and waits for it to complete.

```APIDOC
## GET /StartActionByGetAndWait

### Description
Starts an action using the Action ID in the URL and waits for the action to finish, returning the log entry.

### Method
GET

### Endpoint
/StartActionByGetAndWait
```

--------------------------------

### API Methods Reference

Source: https://docs.olivetin.app/api/method_StartActionAndWait.html

Summary of available methods to start actions in OliveTin.

```APIDOC
| Function | HTTP Method | Request Type | Response Type |
| --- | --- | --- | --- |
| StartAction | POST | OliveTin request object | Execution Tracking ID |
| StartActionByGet | GET | Action ID in the URL | Execution Tracking ID |
| StartActionAndWait | POST | OliveTin request object | Log Entry (waits for the action to finish) |
| StartActionByGetAndWait | GET | Action ID in the URL | Log Entry (waits for the action to finish) |
```

--------------------------------

### Install OliveTin via .deb package

Source: https://docs.olivetin.app/install/linux_deb.html

Download and install the latest OliveTin .deb package using wget and dpkg.

```bash
user@host: wget https://github.com/OliveTin/OliveTin/releases/latest/download/OliveTin_linux_amd64.deb
user@host: dpkg -i OliveTin_linux_amd64.deb
```

--------------------------------

### Using Exec

Source: https://docs.olivetin.app/action_execution/shellvsexec.html

Example configuration using the exec method to execute a command with an argument list.

```yaml
actions:
  - title: List files
	exec:
	  - ls
	  - -l
	  - /some/directory
```

--------------------------------

### Example output log file

Source: https://docs.olivetin.app/logs/saving.html

Raw stdout and stderr output from an execution.

```text
Sun 28 Apr 20:43:04 BST 2024
```

--------------------------------

### POST /StartAction

Source: https://docs.olivetin.app/llm-full.txt

Starts an action using an OliveTin request object.

```APIDOC
## POST /StartAction

### Description
Starts an action and returns an execution tracking ID.

### Method
POST

### Endpoint
/StartAction

### Request Body
- **OliveTin request object** (object) - Required - The action details to execute.
```

--------------------------------

### Install OliveTin via DNF

Source: https://docs.olivetin.app/install/linux_fedora.html

Install OliveTin from the official Fedora repositories. Note that this version may be outdated.

```bash
user@host: dnf install -y OliveTin
```

--------------------------------

### Define users with groups in config.yaml

Source: https://docs.olivetin.app/security/local.html

Configuration example showing how to assign users to specific groups.

```yaml
authLocalUsers:
  enabled: true
  users:
    - username: alice
      usergroup: admins
      password: $argon2id$v=19$m=65536,t=4,p=6$LnNW4sw+jZfa5Ex3YjfuHQ$vl8pjUJhxNmBxScV4lI3cgAZPkNB1rSrnX6ibgoAP8k

    - username: bob
      password: ...
      usergroup: admins

    - username: charlie
      password: ...
      usergroup: webmasters
```

--------------------------------

### Configure SSH setup action

Source: https://docs.olivetin.app/llm-full.txt

Use the built-in olivetin-setup-easy-ssh script to generate SSH keys and configuration. This script is exclusive to containerized environments.

```yaml
actions:
  - title: Setup SSH
    shell: olivetin-setup-easy-ssh
    popupOnStart: execution-dialog
```

--------------------------------

### Define entities in a YAML list

Source: https://docs.olivetin.app/entities/yaml.html

Example of a server configuration list in /etc/OliveTin/servers.yaml.

```yaml
- name: server1
  state: started
  hostname: server1.example.com
  ip: 192.168.0.1
- name: server2
  state: started
  hostname: server2.example.com
  ip: 192.168.0.2
- name: server3
  state: stopped
  hostname: server3.example.com
  ip: 192.168.0.3
```

--------------------------------

### Example output of password hash

Source: https://docs.olivetin.app/security/local.html

The expected format of the returned password hash.

```asciidoc
Your password hash is: $argon2id$v=19$m=65536,t=4,p=6$dlWTV1RL04/Nuvxzl94NAg$KsYXvCFE2Eu/jkXi/dbbZM3I/2b2VByTAwRIenUwdJk
```

--------------------------------

### POST /StartActionAndWait

Source: https://docs.olivetin.app/llm-full.txt

Starts an action and waits for it to complete.

```APIDOC
## POST /StartActionAndWait

### Description
Starts an action and waits for the execution to finish, returning the log entry.

### Method
POST

### Endpoint
/StartActionAndWait
```

--------------------------------

### Full OliveTin YAML Configuration

Source: https://docs.olivetin.app/llm-full.txt

A complete configuration example demonstrating log levels, ACLs, local user authentication, action definitions, and dashboard organization.

```yaml
logLevel: "INFO"

accessControlLists:
  - name: "noguests"
    permissions:
	  view: false
	  exec: false
	  logs: false
	matchUsernames: [ "guest" ]

  - name: "admins"
    permissions:
      view: true
      exec: true
      logs: true
    matchUsergroups: [ "admins" ]

authLocalUsers:
  enabled: true
  users:
    - username: "admin"
      usergroup: admins
      password: -- your password hash here --

actions:
  - title: "Date"
	shell: date

  - title: "Reboot"
    shell: reboot" # Note that this won't work inside a container
	acls:
	  - "noguests"
	  - "admins"

dashboards:
  - title: "Guest Dashboard"
    contents:
	  - title: "Date"

  - title: "Admin Dashboard"
    contents:
      - title: "Reboot"
```

--------------------------------

### POST /api/StartActionAndWait

Source: https://docs.olivetin.app/api/method_StartAction.html

Starts an action and waits for it to complete, returning the log entry.

```APIDOC
## POST /api/StartActionAndWait

### Description
Starts an action using an OliveTin request object and waits for the action to finish.

### Method
POST

### Endpoint
/api/StartActionAndWait

### Response
- **Log Entry** (string) - The output or log generated by the completed action.
```

--------------------------------

### POST /api/olivetin.api.v1.OliveTinApiService/Init

Source: https://docs.olivetin.app/security/api_keys.html

Example of calling the Init RPC method using a Bearer token for authentication.

```APIDOC
## POST /api/olivetin.api.v1.OliveTinApiService/Init

### Description
Calls the Init method of the OliveTin API service using a Bearer token for authentication.

### Method
POST

### Endpoint
https://olivetin.example.com:1337/api/olivetin.api.v1.OliveTinApiService/Init

### Request Headers
- **Authorization** (string) - Required - Must be in the format "Bearer <your-api-key>"
- **Content-Type** (string) - Required - Must be "application/json"

### Request Body
- **{}** (object) - Required - Empty request object for the Init call.

### Request Example
curl -sS -X POST \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  "https://olivetin.example.com:1337/api/olivetin.api.v1.OliveTinApiService/Init" \
  --data '{}'
```

--------------------------------

### Basic OliveTin configuration

Source: https://docs.olivetin.app/install/bsd.html

A minimal configuration file required for OliveTin to start successfully.

```yaml
actions:
  - title: "Hello world!"
    shell: echo 'Hello World!'
```

--------------------------------

### Example systemd_units.json file content

Source: https://docs.olivetin.app/solutions/systemd-control-panel/index.html

Sample structure of the JSON file generated by the systemctl and jq command.

```json
{"unit":"boot.mount","load":"loaded","active":"active","sub":"mounted","description":"/boot"}
{"unit":"podman.service","load":"loaded","active":"inactive","sub":"dead","description":"Podman API Service"}
{"unit":"upsilon-drone.service","load":"loaded","active":"active","sub":"running","description":"upsilon-drone"}
{"unit":"podman.socket","load":"loaded","active":"active","sub":"listening","description":"Podman API Socket"}
```

--------------------------------

### Apprise configuration file

Source: https://docs.olivetin.app/action_execution/aftercompletion.html

Example configuration for the apprise tool to define notification service URLs.

```yaml
urls:
  - tgram://bottoken/ChatID
```

--------------------------------

### POST /api/StartAction

Source: https://docs.olivetin.app/api/method_StartAction.html

Starts an action using an OliveTin request object and returns an Execution Tracking ID.

```APIDOC
## POST /api/StartAction

### Description
Starts an action using an OliveTin request object. This is the primary method used by the OliveTin web UI.

### Method
POST

### Endpoint
/api/StartAction

### Request Body
- **bindingId** (string) - Required - The ID of the action to trigger.
- **arguments** (array) - Optional - A list of objects containing 'name' and 'value' for action parameters.

### Response
- **Execution Tracking ID** (string) - The ID used to track the execution of the action.
```

--------------------------------

### Prometheus Metrics Output Example

Source: https://docs.olivetin.app/advanced_configuration/prometheus.html

Sample output showing the metrics exposed at the /metrics endpoint.

```text
# HELP olivetin_actions_requested_count The actions requested count
# TYPE olivetin_actions_requested_count counter
olivetin_actions_requested_count 0
# HELP olivetin_action_executions_total Total number of finished action executions grouped by result.
# TYPE olivetin_action_executions_total counter
olivetin_action_executions_total{result="success"} 0
olivetin_action_executions_total{result="failed"} 0
olivetin_action_executions_total{result="blocked"} 0
olivetin_action_executions_total{result="timeout"} 0
olivetin_action_executions_total{result="error"} 0
# HELP olivetin_action_execution_duration_seconds Action execution duration in seconds from start to finish.
# TYPE olivetin_action_execution_duration_seconds histogram
olivetin_action_execution_duration_seconds_bucket{le="0.1"} 0
# HELP olivetin_config_action_count Then number of actions in the config file
# TYPE olivetin_config_action_count gauge
olivetin_config_action_count 18
# HELP olivetin_config_reloaded_count The number of times the config has been reloaded
# TYPE olivetin_config_reloaded_count counter
olivetin_config_reloaded_count 1
```

--------------------------------

### Start an action using StartAction with arguments

Source: https://docs.olivetin.app/api/method_StartAction.html

Trigger an action with specific arguments by including them in the JSON request body.

```bash
user:host: curl 'http://olivetin.example.com/api/StartAction' --json '{"bindingId": "Ping_host", "arguments": [{"name": "host", "value": "example.com"},{"name": "count", "value": "1"}]}'
```

--------------------------------

### Configure olivetin-get-theme action

Source: https://docs.olivetin.app/reference/reference_themes_for_users.html

Add this action to your config.yaml to enable the theme installation command within the OliveTin UI.

```yaml
actions:
  - title: Get OliveTin Theme
    exec:
      - olivetin-get-theme
      - "{{ themeGitRepo }}"
      - "{{ themeFolderName }}"
    icon: theme
    arguments:
      - name: themeGitRepo
        title: Theme's Git Repository
        description: Find new themes at https://olivetin.app/themes
        type: url

      - name: themeFolderName
        title: Theme's Folder Name
        type: ascii_identifier
```

--------------------------------

### Example SOS Report Output

Source: https://docs.olivetin.app/llm-full.txt

A sample format of the SOS report generated by OliveTin for troubleshooting purposes.

```yaml
### SOSREPORT START (copy all text to SOSREPORT END)
# Build:
commit: nocommit
version: dev
date: nodate

# Runtime:
os: linux
osreleaseprettyname: PRETTY_NAME="Fedora Linux 37 (Workstation Edition)"
arch: amd64
incontainer: false
lastbrowseruseragent: ""

# Config:
countofactions: 7
loglevel: INFO

### SOSREPORT END  (copy all text from SOSREPORT START)
```

--------------------------------

### Example Results YAML File

Source: https://docs.olivetin.app/llm-full.txt

Structure of the YAML file generated when saving action results.

```yaml
datetimestarted: 2024-04-28T20:43:04.426754136+01:00  
datetimefinished: 2024-04-28T20:43:04.436596926+01:00  
stdout: |
    Sun 28 Apr 20:43:04 BST 2024  
stderr: ""  
timedout: false  
blocked: false  
exitcode: 0  
tags: []  
executionstarted: true  
executionfinished: true  
executiontrackingid: 5e2dc9e5-b6b3-445b-bff9-c2082b0bbbb2  
process:  
    pid: 4168638  
actiontitle: date  
actionicon: '&#x1F600;'  
actionid: d3cf6e25-8bab-432d-b4f9-e6f531b2b67b
```

--------------------------------

### Start an action by ID using curl

Source: https://docs.olivetin.app/api/method_StartActionByGet.html

Example of triggering an action with the ID 'pingGithub' via a GET request.

```bash
user@host: curl http://olivetin.example.com/api/StartActionByGet/pingGithub
```

--------------------------------

### GET /api/StartActionByGet

Source: https://docs.olivetin.app/llm-full.txt

Triggers an action by specifying the action ID in the URL. Does not support passing arguments.

```APIDOC
## GET /api/StartActionByGet

### Description
Allows triggering an action by specifying the action ID directly in the URL. Useful for quick integrations like QR codes or stream decks.

### Method
GET

### Endpoint
/api/StartActionByGet
```

--------------------------------

### SSH Key Generation Output

Source: https://docs.olivetin.app/llm-full.txt

Example output showing the successful generation of an RSA key pair.

```asciidoc
root@server-with-olivetin: ssh-keygen  
Generating public/private rsa key pair.  
Enter file in which to save the key (/root/.ssh/id_rsa): /opt/OliveTinSshKeys/id_rsa  
Enter passphrase (empty for no passphrase):  
Enter same passphrase again:  
Your identification has been saved in /opt/OliveTinSshKeys/id_rsa  
Your public key has been saved in /opt/OliveTinSshKeys/id_rsa.pub  
The key fingerprint is:  
SHA256:t+vGUn+MTeOtRDpxKanO3Cg63+gvAHslZCe3YVNnfWU root@server-with-olivetin  
The key's randomart image is:  
+---[RSA 3072]----+  
|         .. o.  E|  
|      + *  o  ...|  
|     o = +     . |  
|    . . o    . . |  
|     o oS . + +  |  
|    . o  ..o *o  |  
|     . . oo.o*.o |  
|      . +*o+oo= .|  
|      .=+BX .... |  
+----[SHA256------+
```

--------------------------------

### Register and start the service

Source: https://docs.olivetin.app/install/macos_service.html

Copy the plist file to the LaunchAgents directory and bootstrap the service into the user's launchd session.

```shell
cp app.olivetin.olivetin.plist ~/Library/LaunchAgents/
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/app.olivetin.olivetin.plist
```

--------------------------------

### Define entity data for OliveTin

Source: https://docs.olivetin.app/llm-full.txt

Example YAML file structure for entities used by OliveTin.

```yaml
- id: kitchen
  name: Kitchen Light
  powered_on: false

- id: living_room
  name: Living Room Light
  powered_on: true
```

--------------------------------

### GET /api/StartActionByGetAndWait

Source: https://docs.olivetin.app/api/method_StartAction.html

Starts an action by ID via URL and waits for it to complete.

```APIDOC
## GET /api/StartActionByGetAndWait

### Description
Starts an action by providing the Action ID in the URL and waits for the action to finish.

### Method
GET

### Endpoint
/api/StartActionByGetAndWait

### Response
- **Log Entry** (string) - The output or log generated by the completed action.
```

--------------------------------

### Start an action via OliveTin API

Source: https://docs.olivetin.app/llm-full.txt

Use these commands to trigger a specific action by its ID via the StartAction endpoint.

```bash
user@host: curl -X POST "http://olivetin.webapps.teratan.lan/api/StartAction" -d '{"actionId": "nuclear_reactor_shutdown"}'
```

```powershell
PS C:\Users\xcons> $json = '{"actionId": "deploy_attack_gnomes"}'
PS C:\Users\xcons> Invoke-RestMethod -Method "Post" -Uri "http://olivetinServer:1337/api/StartAction" -Body $json
```

--------------------------------

### Install OliveTin files

Source: https://docs.olivetin.app/install/macos_service.html

Create necessary directories and copy the binary, configuration, and web UI files to their system locations.

```shell
sudo mkdir -p /usr/local/bin /usr/local/etc/OliveTin/var /usr/local/var/log

sudo cp OliveTin   /usr/local/bin/OliveTin
sudo cp config.yaml /usr/local/etc/OliveTin/
sudo cp -R webui   /usr/local/etc/OliveTin/
```

--------------------------------

### Install OliveTin files

Source: https://docs.olivetin.app/install/macos_service.html

Create the necessary application directories and copy the binary, configuration, and web UI assets into the user's Library folder.

```shell
# Create the application folder and a place for logs
mkdir -p ~/Library/Application\ Support/OliveTin/var
mkdir -p ~/Library/Logs/OliveTin

# Copy in the binary, your config, and the bundled web UI
cp OliveTin   ~/Library/Application\ Support/OliveTin/
cp config.yaml ~/Library/Application\ Support/OliveTin/
cp -R webui   ~/Library/Application\ Support/OliveTin/
```

--------------------------------

### Configure Full Execution Dialog

Source: https://docs.olivetin.app/llm-full.txt

Displays command output along with execution metadata such as start time, end time, exit code, and duration.

```yaml
actions:
  - title: Check dmesg logs
    popupOnStart: execution-dialog
```

--------------------------------

### Download sample configuration

Source: https://docs.olivetin.app/install/podmandocker.html

Fetch the default configuration file into the host directory mapped to the container.

```shell
user@host: cd /etc/OliveTin/
user@host: curl -O https://raw.githubusercontent.com/OliveTin/OliveTin/main/config.yaml
```
Tokens:
Raw