PHPackages                             purplespider/kirby-monitoring-client - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. purplespider/kirby-monitoring-client

ActiveKirby-plugin[Logging & Monitoring](/categories/logging)

purplespider/kirby-monitoring-client
====================================

Kirby CMS monitoring client plugin compatible with the BiffBangPow Silverstripe monitoring server.

v1.0.0(3w ago)03MITPHPPHP >=7.4

Since May 13Pushed 3w agoCompare

[ Source](https://github.com/purplespider/kirby-monitoring-client)[ Packagist](https://packagist.org/packages/purplespider/kirby-monitoring-client)[ RSS](/packages/purplespider-kirby-monitoring-client/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (1)Versions (2)Used By (0)

Kirby Monitoring Client
=======================

[](#kirby-monitoring-client)

A monitoring plugin for Kirby CMS that provides compatibility with the [BiffBangPow Silverstripe Monitoring Server](https://github.com/BiffBangPow/silverstripe-monitoring-client).

Features
--------

[](#features)

- 🔐 **Secure encryption** using libsodium
- 🚦 **Rate limiting** (1 request per minute)
- 🔑 **API key authentication**
- 🌐 **IP whitelist support**
- 📊 **Modular reporting system**

Requirements
------------

[](#requirements)

- Kirby 3.x, 4.x, or 5.x
- PHP 7.4+ with sodium extension enabled
- Composer (for package version reporting)

Installation
------------

[](#installation)

### Via Composer (recommended)

[](#via-composer-recommended)

```
composer require purplespider/kirby-monitoring-client
```

This installs the plugin into `site/plugins/monitoring-client/` automatically via the `getkirby/composer-installer`.

### Manual Installation

[](#manual-installation)

1. Download this repository
2. Copy the files to `site/plugins/monitoring-client/`
3. Configure environment variables (see Configuration)

### Via Git Submodule

[](#via-git-submodule)

```
git submodule add https://github.com/purplespider/kirby-monitoring-client site/plugins/monitoring-client
```

Configuration
-------------

[](#configuration)

### Required Environment Variables

[](#required-environment-variables)

Add these to your `.env` file or server environment:

```
# API key for authentication (provided by monitoring server)
MONITORING_API_KEY=your-api-key-here

# Unique client identifier (provided by monitoring server)
MONITORING_UUID=unique-client-uuid

# Encryption keys (provided by monitoring server)
MONITORING_ENC_SECRET=your-encryption-secret
MONITORING_ENC_SALT=your-encryption-salt
```

### Optional Environment Variables

[](#optional-environment-variables)

```
# Restrict access to specific IP address or range
MONITORING_VALID_IP=192.168.1.100

# Or use CIDR notation
MONITORING_VALID_IP=192.168.1.0/24

# Or use wildcards
MONITORING_VALID_IP=192.168.*.*
```

### Plugin Configuration

[](#plugin-configuration)

Add to your `site/config/config.php`:

```
return [
    'monitoring.client' => [
        // Endpoint path (default: 'montoro')
        'endpoint' => 'montoro',

        // Enable/disable modules
        'modules' => [
            'kirby_config' => true,  // Kirby configuration info
            'system_info' => true,   // System and server info
            'packages' => true,      // Composer package versions
        ],

        // System info module configuration
        'system_info' => [
            // Discover public IP address
            'discover_public_ip' => false,

            // Environment variables to report
            'env_variables' => [
                'SMTP_HOST',
                'SMTP_PORT',
            ]
        ],

        // Package versions configuration
        'packages' => [
            // Filter to specific packages (empty = all packages)
            'included_packages' => [
                'getkirby/cms',
            ]
        ]
    ]
];
```

Usage
-----

[](#usage)

Once configured, the monitoring endpoint will be available at:

```
https://yourdomain.com/montoro

```

The monitoring server will make POST requests to this endpoint with the API key:

```
curl -X POST https://yourdomain.com/montoro \
  -d "key=your-api-key"
```

Modules
-------

[](#modules)

### Kirby Configuration Module

[](#kirby-configuration-module)

Reports:

- Site name
- Kirby version
- Base URL
- Multilang status
- Debug mode status
- Environment type

### System Information Module

[](#system-information-module)

Reports:

- PHP version
- Host IP address
- Memory limit
- Upload max filesize
- Max execution time
- POST max size
- Database type and name (if configured)
- Environment variables (if configured)
- Public IP address (if enabled)

### Package Versions Module

[](#package-versions-module)

Reports:

- All installed Composer packages and versions
- Can be filtered to specific packages

Security
--------

[](#security)

### Rate Limiting

[](#rate-limiting)

The endpoint is rate-limited to **1 request per minute** per client IP address. This prevents abuse and excessive requests.

### Authentication

[](#authentication)

Requests must include a valid API key via the `key` POST parameter. Invalid requests return a 404 error (in production) or 400 error (in debug mode).

### IP Whitelisting

[](#ip-whitelisting)

Optionally restrict access to specific IP addresses or ranges using the `MONITORING_VALID_IP` environment variable.

Supported formats:

- Exact IP: `192.168.1.100`
- CIDR notation: `192.168.1.0/24`
- Wildcards: `192.168.*.*`

### Encryption

[](#encryption)

All response data is encrypted using libsodium's `sodium_crypto_secretbox` with:

- Random nonce for each request
- 50-character integrity hash
- Encryption keys from environment variables

The monitoring server decrypts the response using the same keys.

Response Format
---------------

[](#response-format)

The endpoint returns encrypted data in plain text format:

```
[encrypted_ciphertext][nonce_hex][hash]

```

When decrypted and unserialized by the monitoring server, the data structure is:

```
[
    'clientid' => 'unique-uuid',
    'kirbyconfig' => [...],
    'systeminfo' => [...],
    'packages' => [...]
]
```

Troubleshooting
---------------

[](#troubleshooting)

### 404 Error

[](#404-error)

- Check that environment variables are set correctly
- Verify the API key is correct
- Check IP whitelist configuration
- Enable debug mode to see detailed errors

### Rate Limit Errors

[](#rate-limit-errors)

Wait 1 minute between requests. The rate limit cache is stored in `site/cache/monitoring/`.

### Encryption Errors

[](#encryption-errors)

- Verify `MONITORING_ENC_SECRET` and `MONITORING_ENC_SALT` are set
- Ensure PHP sodium extension is enabled
- Check that keys match the monitoring server

### Composer Lock Not Found

[](#composer-lock-not-found)

The plugin looks for `composer.lock` in:

1. Project root (parent of `index.php`)
2. `index.php` directory
3. Kirby root directory

Ensure `composer.lock` exists in one of these locations.

Debug Mode
----------

[](#debug-mode)

Enable debug mode in your Kirby config to see detailed error messages:

```
return [
    'debug' => true,
];
```

**Important:** Never enable debug mode in production as it may expose sensitive information.

Compatibility
-------------

[](#compatibility)

This plugin is designed to be compatible with the BiffBangPow Silverstripe Monitoring Server. It uses the same:

- Encryption algorithm (libsodium)
- Authentication method (API key)
- Rate limiting (1 request per minute)
- Response format (serialized + encrypted)
- Endpoint path (`/montoro`)

Development
-----------

[](#development)

### Creating Custom Modules

[](#creating-custom-modules)

Create a class implementing `MonitoringClient\Modules\ModuleInterface`:

```