# Oculix

# Introduction

**Ver**. 03-06-2026

This document describes the functionality of the Oculix plugin and its integration with PandoraFMS. The Oculix plugin enables visual automation of transactions through screenshots, image comparison, and script execution, generating monitoring modules in PandoraFMS.

**Type**: Plug-in server

# Compatibility matrix

<table border="1" id="bkmrk-sistemas-donde-se-ha-1" style="width: 99.7531%;"><tbody><tr><td style="width: 55.2288%;">**Systems where tested**</td><td style="width: 44.7712%;">Rocky linux, WIndows2022</td></tr><tr><td style="width: 55.2288%;">**Systems where it works**</td><td style="width: 44.7712%;">Any linux and windows system</td></tr></tbody></table>

# Pre requisites

**1. Java Runtime Environment**  
The plugin runs an Oculix JAR file, so it is necessary to have Java installed and accessible in the system PATH. Java 17 or higher is recommended.

**2. Graphical environment**  
The plugin uses `mss` to take screenshots, so it requires a running X11 server (graphical environment). If running in a headless environment, a virtual X server such as `Xvfb` can be used.

**3. Write permissions**  
The plugin needs write permissions in the artifacts directory (`--artifacts`) to store screenshots, baseline images, and diffs.

**4. Tentacle (optional)**  
If the `tentacle` transfer mode is used, the `tentacle_client` binary must be installed and accessible on the system.

# Parameters

**Script execution parameters**

<table border="1" id="bkmrk---script-ruta-del-s" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 30%;"></col><col style="width: 70%;"></col></colgroup><tbody><tr><td>**--script**</td><td>Path to the Oculix script to execute. This parameter is mandatory.</td></tr><tr><td>**--jar**</td><td>Path to the Oculix JAR file. This parameter is mandatory.</td></tr><tr><td>**--conf**</td><td>Path to the .conf configuration file with Pandora and connection parameters. This parameter is mandatory.</td></tr><tr><td>**--workspace**</td><td>Working directory for Oculix script execution. Optional.</td></tr><tr><td>**--debug**</td><td>Debug level for Oculix execution. Default 1.</td></tr><tr><td>**--console**</td><td>Enables Oculix console mode. Activated with the flag.</td></tr><tr><td>**--native-access**</td><td>Enables `--enable-native-access=ALL-UNNAMED` in Java execution. Activated with the flag.</td></tr><tr><td>**--checkpoint**</td><td>Enables baseline logic: if no reference image exists, creates one from the current screenshot. Activated with the flag.</td></tr><tr><td>**--artifacts**</td><td>Directory where screenshots, baselines, and diffs are stored. Default "artifacts".</td></tr></tbody></table>

**Pandora configuration parameters (.conf file)**

<table border="1" id="bkmrk-parametros-conf" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 34.0551%;"></col><col style="width: 65.9449%;"></col></colgroup><tbody><tr><td>**agent\_name**</td><td>Name of the agent that will contain the modules. Default: "{script} Oculix".</td></tr><tr><td>**agents\_group\_name**</td><td>Agent group in PandoraFMS. Default "Oculix".</td></tr><tr><td>**module\_prefix**</td><td>Prefix for all modules created by the plugin.</td></tr><tr><td>**interval**</td><td>Agent monitoring interval in seconds. Default 300.</td></tr><tr><td>**show\_xml**</td><td>Output mode: 1 prints XML to console, 0 writes to file and transfers. Default 0.</td></tr><tr><td>**temporal**</td><td>Temporary directory for XML files. Default "/tmp".</td></tr><tr><td>**transfer\_mode**</td><td>Transfer mode: "tentacle" or "local". Default "tentacle".</td></tr><tr><td>**tentacle\_client**</td><td>Path to the tentacle\_client binary. Default "tentacle\_client".</td></tr><tr><td>**tentacle\_ip**</td><td>IP address of the tentacle server. Default "127.0.0.1".</td></tr><tr><td>**tentacle\_port**</td><td>Tentacle connection port. Default "41121".</td></tr><tr><td>**tentacle\_opts**</td><td>Extra options for tentacle connection.</td></tr><tr><td>**data\_dir**</td><td>PandoraFMS data directory for local transfer. Default "/var/spool/pandora/data\_in/".</td></tr></tbody></table>

# Manual execution

The plugin execution format is as follows:

```
./pandora_oculix.py --script <path to oculix script> \
--conf <path to .conf file> \
--jar <path to oculix JAR> \
[--workspace <working directory>] \
[--debug <debug level>] \
[--console] \
[--native-access] \
[--checkpoint] \
[--artifacts <artifacts directory>]
```

Example:

```
./pandora_oculix.exe --script scripts/login.ocx --conf oculix.conf --jar oculix.jar --debug 1
```

With baseline creation and console:

```
./pandora_oculix.exe --script scripts/login.ocx --conf oculix.conf --jar oculix.jar --console --checkpoint
```

<div class="page-break" id="bkmrk-">  
</div>

# Configuration in PandoraFMS

To configure the plugin in PandoraFMS, follow these steps:

**1. Upload the plugin to PandoraFMS, e.g. in the following path:**

```
/usr/share/pandora_server/util/plugin
```

**2. Upload the Oculix JAR and the required .ocx scripts to the server, in a path accessible by the plugin.**

**3. Create the .conf configuration file with Pandora parameters:**

```ini
[CONF]
agent_name=Oculix Login Test
agents_group_name=Oculix
module_prefix=
interval=300
agent_plugin=1
temporal=/tmp
transfer_mode=tentacle
tentacle_client=tentacle_client
tentacle_ip=127.0.0.1
tentacle_port=41121
tentacle_opts=
data_dir=/var/spool/pandora/data_in/
```

**4. Go to the plugins section and create a new one:**

Add a name, description, and timeout.

**5. Add the plugin path in the command and the necessary parameters for its execution.**

<p class="callout info">For each parameter, a macro must be configured. The macro syntax is: `_fieldx_`, where x is the positional number of the parameter.</p>

Example plugin command:

```
/usr/share/pandora_server/util/plugin/pandora_oculix.py --script _field1_ --jar _field2_ --conf _field3_
```

**6. Configure the macros above, adding the parameter value in each one:**

Example macros:

- \_field1\_ = /opt/oculix/scripts/login.ocx
- \_field2\_ = /opt/oculix/oculix.jar
- \_field3\_ = /opt/oculix/oculix.conf

**7. Once configured, a module must be created in an agent to run the plugin. In an agent's module menu, create a new plugin-type module:**

**8. In the module configuration menu, give it a name, select the previously configured plugin, and click "create".**

**9. The agent with the modules will be created on the next execution of the plugin.**

# Agent and modules generated by the plugin

The plugin creates an agent with the name specified in `agent_name` (default "{script} Oculix") containing the following modules:

<table border="1" id="bkmrk-modulos-generados" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 35%;"></col><col style="width: 20%;"></col><col style="width: 45%;"></col></colgroup><tbody><tr><td>**Module name**</td><td>**Type**</td><td>**Description**</td></tr><tr><td>{script\_name} status</td><td>generic\_proc</td><td>Script execution status. Value 1 if execution was successful, 0 if there was an error or visual difference.</td></tr><tr><td>{script\_name} time</td><td>generic\_data</td><td>Script execution time in seconds.</td></tr><tr><td>{script\_name} last\_image</td><td>async\_string</td><td>Screenshot in base64 format (PNG image). Only generated when the status is 0 (failure or visual difference).</td></tr></tbody></table>

Example: for a script called `login`, the generated modules would be:

```
login status
login time
login last_image
```