README

A Nagios integration add-on for spatie/laravel-health. This package extends Laravel Health to provide Nagios-compatible monitoring endpoints and output formatting.

What This Package Does

This add-on package provides:

🔍 Nagios-Compatible Health Check Endpoint - Exposes your Laravel Health checks in a format that Nagios can understand
🛡️ Bearer Token Authentication - Secure your health check endpoint with configurable bearer token authentication
📊 Performance Data Generation - Includes performance metrics for Nagios graphing and trending
🎯 Proper Status Codes - Returns appropriate HTTP status codes (200 for OK, 503 for failures)
⚙️ Configurable Output - Control what information is included in the Nagios output
🔄 Fresh Results Support - Option to force fresh health check execution via ?fresh parameter

Requirements

PHP 8.1+
Laravel 10.0+, 11.0+, or 12.0+
spatie/laravel-health ^1.0

Installation

You can install the package via composer:

composer require iabdullahsk/laravel-health-nagios

Note: This will automatically install spatie/laravel-health as a dependency if it's not already installed.

Publish Configuration (Optional)

php artisan vendor:publish --tag="nagios-config"
php artisan vendor:publish --tag="health-config"

The package will automatically register its service provider via Laravel's auto-discovery feature.

Configuration

Environment Variables

Add these environment variables to your .env file:

# Enable/disable the Nagios endpoint
NAGIOS_ENABLED=true

# Bearer token for authentication (required for security)
NAGIOS_HEALTH_BEARER_TOKEN=your-secret-token-here

# Custom endpoint URL (optional)
NAGIOS_HEALTH_URL=/health/nagios

# Whether to always run fresh health checks
NAGIOS_ALWAYS_SEND_FRESH_RESULTS=true

# Include detailed information in output
NAGIOS_INCLUDE_DETAILS=true

# Include performance data for graphing
NAGIOS_INCLUDE_PERFORMANCE_DATA=true

Configuration File

The published configuration file (config/nagios.php) provides additional options:

return [
    'enabled' => env('NAGIOS_ENABLED', false),
    'always_send_fresh_results' => env('NAGIOS_ALWAYS_SEND_FRESH_RESULTS', true),
    'enable_authentication' => env('NAGIOS_ENABLE_AUTHENTICATION', true),
    'bearer_token' => env('NAGIOS_HEALTH_BEARER_TOKEN'),
    'url' => env('NAGIOS_HEALTH_URL', '/health/nagios'),
    'middleware' => [
        Abdullah\LaravelHealthNagios\Http\Middleware\RequiresBearerToken::class,
    ],
    'include_details' => env('NAGIOS_INCLUDE_DETAILS', true),
    'include_performance_data' => env('NAGIOS_INCLUDE_PERFORMANCE_DATA', true),
];

Usage

Basic Setup

Once installed and configured, your Nagios health check endpoint will be automatically available at the configured URL (default: /health/nagios).

Example Output

When all checks pass (HTTP 200):

OK: 3 checks executed|'database'=1 'cache'=1 'queue'=1

database: Connection successful [OK]
cache: Cache working properly [OK]
queue: Jobs processing normally [OK]

When checks fail (HTTP 503):

CRITICAL: Connection failed|'database'=0 'cache'=1 'queue'=1

database: Connection failed [FAILED]
cache: Cache working properly [OK]
queue: Jobs processing normally [OK]

Testing the Endpoint

# Test with bearer token
curl -H "Authorization: Bearer your-secret-token-here" \
     http://your-app.com/health/nagios

# Force fresh results
curl -H "Authorization: Bearer your-secret-token-here" \
     "http://your-app.com/health/nagios?fresh"

Integration with Laravel Health

This package works seamlessly with all existing Laravel Health checks. Simply configure your health checks as normal:

// In your Laravel application (e.g., AppServiceProvider)
use Spatie\Health\Facades\Health;
use Spatie\Health\Checks\Checks\UsedDiskSpaceCheck;
use Spatie\Health\Checks\Checks\DatabaseCheck;
use Spatie\Health\Checks\Checks\RedisCheck;

Health::checks([
    UsedDiskSpaceCheck::new(),
    DatabaseCheck::new(),
    RedisCheck::new(),
    // ... other health checks
]);

All configured health checks will automatically appear in the Nagios output.

Security Considerations

Always use bearer token authentication in production environments
Use HTTPS for your health check endpoints
Restrict network access to your monitoring systems only
Use strong, unique tokens for authentication

Development

Running Tests

The package includes comprehensive tests using Pest, the same testing framework used by spatie/laravel-health.

Prerequisites

Make sure you have the development dependencies installed:

composer install

Running the Test Suite

# Run all tests
./vendor/bin/pest

# Run tests with coverage
./vendor/bin/pest --coverage

# Run specific test files
./vendor/bin/pest tests/ResultFormats/NagiosResultsFormatTest.php

# Run tests with verbose output
./vendor/bin/pest --verbose

Test Structure

The test suite includes:

Feature Tests (tests/Feature/): Test service provider registration and configuration
Unit Tests (tests/Unit/): Basic sanity checks and isolated component tests
HTTP Tests (tests/Http/Controllers/): Test the Nagios endpoint functionality
Format Tests (tests/ResultFormats/): Test Nagios output formatting

Test Coverage

The tests cover:

✅ Service provider registration and configuration loading
✅ Bearer token authentication middleware
✅ Nagios output formatting for different health check statuses
✅ HTTP endpoint responses and status codes
✅ Performance data generation
✅ Error handling for missing results

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add or update tests as needed
Ensure all tests pass (./vendor/bin/pest)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Style

The package follows PSR-12 coding standards. You can check your code style using:

# Install PHP CS Fixer (if not already installed)
composer require --dev friendsofphp/php-cs-fixer

# Check code style
./vendor/bin/php-cs-fixer fix --dry-run --diff

Troubleshooting

Common Issues

Endpoint returns 404:

Check that NAGIOS_ENABLED=true in your .env file
Verify that NAGIOS_HEALTH_BEARER_TOKEN is set
Ensure the URL is correct (default: /health/nagios)

Authentication fails:

Verify the bearer token in your request header: Authorization: Bearer your-token
Check that the token matches your NAGIOS_HEALTH_BEARER_TOKEN environment variable

No health check results:

Ensure you have configured health checks in your Laravel application
Try adding ?fresh=1 to force fresh results
Check Laravel logs for any health check errors

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details on how to contribute to this project.

Security Vulnerabilities

If you discover a security vulnerability, please send an e-mail to [your-email@example.com]. All security vulnerabilities will be promptly addressed.

iabdullahsk / laravel-health-nagios

Maintainers

Details

README

What This Package Does

Requirements

Installation

Publish Configuration (Optional)

Configuration

Environment Variables

Configuration File

Usage

Basic Setup

Example Output

Testing the Endpoint

Integration with Laravel Health

Security Considerations

Development

Running Tests

Prerequisites

Running the Test Suite

Test Structure

Test Coverage

Contributing

Code Style

Troubleshooting

Common Issues

Changelog

Contributing

Security Vulnerabilities

Credits

License

Related Packages