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.

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()#

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()`#