Creating a checker#

Introduction#

Bacularis provides a set of pre-installed checker plugins capable of validating many file and directory attributes.

In some situations, however, you may need to create a custom checker. A custom checker is useful when the built-in checkers do not cover the required attribute or when application-level validation is needed, such as importing a database dump, starting a virtual machine, or checking whether a service is available.

Location#

Because checkers are plugins, they are installed in the Plugins directory of the Common layer, for example:

/usr/share/bacularis/protected/Common/Plugins/MyOwnCheckerCheck.php

Each checker plugin is implemented as a PHP script.

The file name should correspond to the checker class defined inside it.

For example:

File:

MyOwnCheckerCheck.php

Class:

<?php
class MyOwnCheckerCheck extends BacularisCommonPluginBase
  implements IBacularisVerificationCheckPlugin
{
    // Checker method definitions
}

Interface#

Each checker must implement the following programming interface:

Bacularis\Common\Modules\IBacularisVerificationCheckPlugin

It is a simple PHP interface defined as follows:

<?php
interface IBacularisVerificationCheckPlugin extends IBacularisPlugin
{
    /**
     * Main check command.
     * It checks if item is valid or not.
     *
     * @param string $operator check operator
     * @param mixed $current_value item value to check
     * @param mixed $expected_value expected value
     * @return array current value, expected value and check result:
     *               true on success, false otherwise
     */
    public static function check(
        string $operator,
        $current_value,
        $expected_value
    ): array;

    /**
     * Get main plugin attribute.
     * Main attribute answers on question what the attribute is used
     * in the check action.
     * This is the first parameter defined in the verification rules.
     *
     * @return string main attribute
     */
    public static function getAttribute(): string;

    /**
     * Get all supported operators by plugin.
     *
     * @return array operator list
     */
    public static function getOperators(): array;

    /**
     * Get possible values to select.
     *
     * @return array values to select or type
     */
    public static function getValues(): array;

    /**
     * Get checker capabilities.
     * Capabilities define what data types is able to check and where
     * it can be used.
     *
     * @return array check capabilities
     */
    public static function getCapabilities(): array;

    /**
     * Get checker requirements.
     * Requirements define what this checker requires to correct working.
     *
     * @return array check requirements
     */
    public static function getRequirements(): array;
}

Required interface methods#

`check()`#

This is the main checker method. It performs the actual verification test.

It receives the following parameters:

$operator – the operator currently used for the verification condition. It must be one of the operators returned by IBacularisVerificationCheckPlugin::getOperators().
$current_value – although the parameter is named $current_value, for file-oriented checkers Bacularis passes the restored path that the checker should inspect.
$expected_value – the expected value used by the verification condition.

When the special internal ECV operator is used, $expected_value contains data retrieved from the Bacula Catalog for the selected path instead of a value entered by the user.

For example:

{
  "fileindex": 1,
  "jobid": 61091,
  "lstat": {
    "dev": 47,
    "inode": 1750377,
    "mode": "-rw-rw-r--",
    "nlink": 1,
    "uid": 1000,
    "gid": 1000,
    "rdev": 0,
    "size": 1191,
    "blocksize": 4096,
    "blocks": 8,
    "atime": 1785920119,
    "mtime": 1553164613,
    "ctime": 1774019557,
    "linkfi": 0,
    "flags": 0,
    "data": 2
  },
  "checksum": "Tfq1i5BByYaXbMi0U0pZ2g",
  "jobtdate": 1786005164
}

The internal ECV operator means Equal Catalog Value.

When this operator is used, $expected_value contains the Bacula Catalog metadata for the selected path instead of a user-entered value.

`getAttribute()`#

This method returns the name of the attribute checked by the plugin.

For example:

a checker that verifies file size can return Size,
a checker that verifies whether a file or directory exists can return Exists.

The attribute name does not directly affect the verification logic. Its main purpose is to identify the checker and describe to the user what property it verifies.

Because the attribute identifies the checker among all installed checker plugins, it should be unique.

Once used in Verification Rules, the attribute name should be treated as a stable identifier.

`getOperators`#

This method returns an array containing all operators supported by the checker.

These can include operators such as:

!=
==
>
<=

or any other operator implemented by the plugin.

Operators are returned in the following form:

[
    operator_name_1 => operator_description_1,
    operator_name_2 => operator_description_2
]

The array key is the internal operator value, while the array value is the description displayed to the user.

`getValues()`#

This method defines the type and default values of the expected-value field used by the checker.

The returned array depends on the HTML field type used in the Verification Rules form.

Examples follow.

Text field

['type' => 'text', 'values' => 0];

In this example, 0 is the default value of the text field.

Selection list

['type' => 'list', 'values' => [value1, value2, value3]];

`getCapabilities()`#

This method returns the capabilities required from the Restore Destination environment.

A checker is not executed on a Restore Destination that does not provide the capabilities required by the checker.

A Restore Destination must provide all capabilities returned by the checker.

The method returns an array containing the required capabilities.

All supported capabilities are defined in:

Bacularis\Common\Modules\RestoreDestinationCapability

Available values include:

file_check – an environment capable of checking file and directory attributes,
native_verify – an environment prepared for Native Bacula Verify,
plugin_check – an environment prepared for testing data restored from plugin-based backups,
custom_check – a general-purpose environment for checks that do not fit the other capability categories.

Examples

The following checker will not run because the Restore Destination does not provide the required capability:

Restore Destination Capabilities: native_verify, plugin_check
Checker Capabilities:             file_check

The following checker can run because the Restore Destination provides the required capability:

Restore Destination Capabilities: custom_check, file_check
Checker Capabilities:             file_check

`getRequirements()`#

This method defines additional requirements needed by the checker to operate correctly.

For example, consider a checker that verifies a MySQL database.

If MySQL is required on the Restore Destination, this method can be used to describe that requirement.

getRequirements() is currently informational and is not automatically enforced by Bacularis. A checker may use the returned information internally, but the framework does not install or automatically validate these dependencies.

Optional lifecycle methods#

A checker can optionally define two lifecycle methods used before and after the actual verification check.

`setUp()`#

The setUp() method is executed before check().

It can be used to prepare the environment required by the verification test.

For example, it can:

prepare a temporary database,
create directories,
prepare other resources required by the checker.

`tearDown()`#

The tearDown() method is executed after check().

It is intended for cleanup tasks after the verification test.

For example, it can:

remove temporary files,
stop a process,
remove temporary test resources,
perform other cleanup operations required by the checker.

Both lifecycle methods are optional and are used only when they are defined by the checker.

A checker does not need to implement them if no preparation or cleanup is required.

Optional checker interfaces#

A checker can implement additional interfaces to use optional checker features provided by Restore Verification.

These interfaces are not required for ordinary checker plugins. They are used only when a checker needs its own configuration or needs to store and analyze data from previous verification runs.

A checker can implement one or both optional interfaces together with the required checker interface:

<?php
class MyOwnCheckerCheck extends BacularisCommonPluginBase
  implements IBacularisVerificationCheckPlugin,
             IBacularisVerificationConfigPlugin,
             IBacularisVerificationDataPlugin
{
    // Checker method definitions
}

Checker configuration#

A checker that uses checker-specific configuration can implement:

Bacularis\Common\Modules\IBacularisVerificationConfigPlugin

The interface is defined as follows:

<?php
interface IBacularisVerificationConfigPlugin extends IBacularisPlugin
{
    public static function setCheckerConfig(array $config): void;
}

Checker configuration uses the common Bacularis plugin configuration mechanism. The configuration of a plugin instance contains general plugin properties and a parameters array with values defined by the plugin’s getParameters() method.

For example:

[
    'plugin' => 'MyOwnCheckerCheck',
    'enabled' => '1',
    'parameters' => [
        'threshold' => '10',
        'analysis-mode' => 'default'
    ],
    'name' => 'My checker configuration'
]

Implementing IBacularisVerificationConfigPlugin allows Bacularis to pass the selected plugin configuration to the checker before verification is performed.

`setCheckerConfig()`#

This method receives the complete checker plugin configuration.

Checker-specific values are stored under the parameters key. A checker can extract and store them for later use as follows:

private static $config = [];

public static function setCheckerConfig(array $config): void
{
    if (isset($config['parameters']) && is_array($config['parameters'])) {
        self::$config = $config['parameters'];
    } else {
        self::$config = $config;
    }
}

The checker can then read parameter values during verification:

$threshold = self::$config['threshold'] ?? 10;

The configuration can affect the behavior of check(), setUp(), tearDown(), or other checker methods.

A checker that does not require configurable behavior does not need to implement IBacularisVerificationConfigPlugin.

Checker history#

A checker that needs data from previous verification runs can implement:

Bacularis\Common\Modules\IBacularisVerificationDataPlugin

The interface is defined as follows:

<?php
interface IBacularisVerificationDataPlugin extends IBacularisPlugin
{
    public static function setHistory(array $history): void;

    public static function getState(array $result): array;

    public static function getHistorySize(): int;

    public static function getHistoryConfig(): array;
}

This interface enables a checker to keep checker-defined state between verification runs and use previous results when evaluating the current restored data.

The history mechanism is useful for checks where an absolute value is less meaningful than a change over time. For example, a checker can establish a normal baseline for a data set and detect significant differences during later verification runs.

Bacularis stores and delivers the historical checker state. The checker itself defines the meaning and structure of that state and is responsible for interpreting it.

`setHistory()`#

This method receives historical state from previous checker executions.

private static $history = [];

public static function setHistory(array $history): void
{
    self::$history = $history;
}

The checker can use this data during the current verification to calculate baselines, detect trends, compare previous values, or implement other history-based logic.

The structure of individual history entries is checker-specific. Bacularis does not interpret the data stored in them.

`getState()`#

This method returns the state produced by the current checker execution.

public static function getState(array $result): array
{
    return self::$state;
}

The $result parameter contains the result returned by check() for the current verification execution.

The returned array is stored by Bacularis and can be provided to future executions through setHistory().

The checker decides what information should be stored. It should normally contain only data that is useful for future comparisons or analysis rather than complete diagnostic output.

A checker can also return an empty array when there is no state that should be stored for the current execution.

`getHistorySize()`#

This method defines the maximum number of historical state entries that should be retained for the checker.

For example:

public static function getHistorySize(): int
{
    return 12;
}

The appropriate history size depends on the type of analysis performed by the checker. A larger history can provide a longer baseline, while a smaller history reacts more quickly to changes in the protected data.

`getHistoryConfig()`#

This method returns configuration properties that affect the meaning of the stored historical data.

For example:

public static function getHistoryConfig(): array
{
    return [
        'threshold' => self::$config['threshold'] ?? 10,
        'analysis-mode' => self::$config['analysis-mode'] ?? 'default'
    ];
}

Bacularis uses this information to distinguish history created with configuration settings that are relevant to historical analysis.

Only settings that change the meaning or interpretation of stored history should be returned. Options that do not affect historical data do not need to be included.

This is particularly important when a checker also implements IBacularisVerificationConfigPlugin. Changing a significant analysis parameter should not cause historical data created with incompatible settings to be silently treated as the same baseline.

History design#

The history mechanism intentionally keeps checker-specific logic inside the checker plugin.

Bacularis is responsible for storing, retrieving, and delivering history. The checker is responsible for:

defining the state structure,
deciding which values should be stored,
interpreting previous states,
building a baseline or other historical model,
deciding how historical information affects the current check.

This separation allows different checker plugins to use history in completely different ways without requiring the Restore Verification framework to understand the meaning of checker-specific data.

Inheritance#

Checker plugins can extend:

Bacularis\Common\Modules\BacularisCommonPluginBase

This is the base class for Common plugins and provides several methods that can be useful when implementing more advanced checkers.

Implementing IBacularisVerificationCheckPlugin is required for a checker plugin, while extending BacularisCommonPluginBase provides access to the common plugin base functionality.

Installation#

1. Copy the checker file#

Copy the completed checker PHP file to:

protected/Common/Plugins/

2. Register the checker module#

protected/application.xml

Add a module entry for the checker.

For example, for a checker named MyDbCheck:

<module
 id="mydbcheck_plugin"
 class="Bacularis\Common\Plugins\MyDbCheck"
/>

3. Verify attribute visibility#

After registering the checker, verify that its attribute is available when adding or editing Verification Rules.

Go to:

[Main menu] => [Page: Jobs] => [Tab: Restore Verification] => [SubTab: Verification rules]

The new checker attribute should now be available in the attribute list.

Creating a checker

Contents

Creating a checker#

Introduction#

Location#

Interface#

Required interface methods#

check()#

getAttribute()#

getOperators#

getValues()#

getCapabilities()#

getRequirements()#

Optional lifecycle methods#

setUp()#

tearDown()#

Optional checker interfaces#

Checker configuration#

setCheckerConfig()#

Checker history#

setHistory()#

getState()#

getHistorySize()#

getHistoryConfig()#

History design#

Inheritance#

Installation#

1. Copy the checker file#

2. Register the checker module#

3. Verify attribute visibility#

Related documentation#

`check()`#

`getAttribute()`#

`getOperators`#

`getValues()`#

`getCapabilities()`#

`getRequirements()`#

`setUp()`#

`tearDown()`#

`setCheckerConfig()`#

`setHistory()`#

`getState()`#

`getHistorySize()`#

`getHistoryConfig()`#