nagioscli

A CLI tool to manage Nagios Core via HTTP REST API.

Features

• Query host and service status
• List all problems (warning, critical, unknown)
• Force immediate checks
• Acknowledge problems
• List hosts and services
• JSON output support
• Multiple authentication methods:
  • Basic auth (password, environment variable)
  • Password manager (pass) integration
  • Vouch Proxy (SSO/OAuth) support
  • Nginx API token (for CLI/automation)
• VS Code extension: host and service problems in the sidebar, status detail with plugin output, force check, acknowledge — reads the same nagioscli.ini (see VS Code extension)

Installation

# From PyPI
pip install nachos

# From source
pip install git+https://github.com/lduchosal/nagioscli.git

# Development
git clone https://github.com/lduchosal/nagioscli.git
cd nagioscli
pdm install

VS Code extension

Each GitHub release attaches nagioscli-vscode-<version>.vsix (no Marketplace):

gh release download v<version> -R lduchosal/nagioscli -p '*.vsix'
code --install-extension nagioscli-vscode-<version>.vsix

It finds nagioscli.ini from the workspace folder upwards (then ~/.nagioscli.ini, /usr/local/etc/nagioscli.ini) and honours every [auth] method (including pass_path and the nagioscli login Vouch token) and the [settings] like the CLI. The tree and the open status documents refresh every 60 s (nagioscli.autoRefreshSeconds). Details: vscode/README.md.

Quick Start

Configuration

Create nagioscli.ini in the current directory or ~/.nagioscli.ini:

[nagios]
url = http://nagios.example.com/nagios
username = nagiosadmin

[auth]
method = pass_path
pass_path = nagios/admin

[settings]
timeout = 30

Basic Usage

# List all problems
nagioscli problems

# Query service status
nagioscli status service web01.example.com HTTP

# Query host status
nagioscli status host web01.example.com

# Force service check
nagioscli check web01.example.com HTTP

# Force check of every service in error (warning/critical/unknown),
# optionally filtered by service name, across all hosts
nagioscli check-problems
nagioscli check-problems PKGVULN

# Acknowledge a problem
nagioscli ack web01.example.com HTTP "Working on it"

# List all hosts
nagioscli hosts

# List services for a host
nagioscli services web01.example.com

Commands

Output Options

# JSON output
nagioscli problems --json

# Quiet mode (exit codes only)
nagioscli problems --quiet

# Verbose debugging
nagioscli problems -v
nagioscli problems -vv
nagioscli problems -vvv

Configuration Options

Authentication Methods

nagioscli supports multiple authentication methods for different environments.

Basic Auth - Password in config file

[nagios]
url = http://nagios.example.com/nagios
username = admin
password = secret

Basic Auth - Password from pass (password-store)

[nagios]
url = http://nagios.example.com/nagios
username = admin

[auth]
method = pass_path
pass_path = nagios/admin

Basic Auth - Password from environment variable

[nagios]
url = http://nagios.example.com/nagios
username = admin

[auth]
method = env_var
env_var = NAGIOS_PASSWORD

Vouch Proxy (SSO/OAuth)

For Nagios behind Vouch Proxy with SSO authentication:

# Interactive login - opens browser, paste cookie from DevTools
nagioscli login

The token is cached in ~/.nagioscli_token and used automatically.

Alternatively, set the cookie directly in config:

[nagios]
url = https://nagios.example.com/nagios
username = admin

[auth]
method = vouch_cookie
vouch_cookie = H4sIAAAA...

To get the cookie value manually:

1. Open browser to your Nagios URL
2. Authenticate via SSO
3. Open DevTools (F12) → Application → Cookies
4. Copy the VouchCookie value

To logout and clear the cached token:

nagioscli logout

Nginx API Token

For Nagios behind nginx with Vouch Proxy, you can use a static API token for CLI/automation access without requiring interactive browser authentication.

This method requires nginx to be configured to accept X-API-Key header and map it to a Nagios user.

[nagios]
url = https://nagios.example.com/nagios
username = claude

[auth]
method = nginx_token
nginx_token = your-secret-token-here

[settings]
timeout = 30
verify_ssl = false

nginx configuration:

Add to your nginx http block:

map $http_x_api_key $api_user {
    default "";
    "your-secret-token-here" "claude";
}

map $http_x_api_key $api_key_valid {
    default 0;
    "your-secret-token-here" 1;
}

Update your CGI location to check for API key:

location @cgi_api {
    try_files $uri =404;
    include fastcgi_params;
    fastcgi_pass unix:/var/run/fcgiwrap/nagios.socket;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param REMOTE_USER $api_user;
}

location ~ \.cgi$ {
    if ($api_key_valid) {
        error_page 418 = @cgi_api;
        return 418;
    }

    # Vouch authentication fallback
    auth_request /vouch/validate;
    # ...
}

This allows:

• Browser users: Authenticate via Vouch/ADFS SSO
• CLI/automation: Authenticate via static API token

Exit Codes

Development

# Clone and setup
git clone https://github.com/lduchosal/nagioscli.git
cd nagioscli
pdm install -G dev

# Run tests
pdm test

# Lint and format
pdm lint
pdm format

# Type check
pdm typecheck

# Build
pdm build

# VS Code extension (vscode/, Node >= 20)
pdm run vscode-install    # npm ci
pdm run vscode-check      # biome + tsc --noEmit + node --test (coverage gate)
pdm run vscode-package    # vscode/nagioscli-vscode-<version>.vsix

# Full local quality gate, no release
./publish.sh --quality

Architecture

nagioscli/
├── cli/                    # Click CLI interface
│   ├── commands/           # Individual commands
│   ├── decorators.py       # Common CLI options
│   └── handlers.py         # Error handlers
├── core/                   # Core business logic
│   ├── auth.py             # Authentication
│   ├── client.py           # Nagios HTTP client
│   ├── config.py           # Configuration
│   ├── encoding.py         # Tolerant response decoding
│   ├── exceptions.py       # Custom exceptions
│   └── models.py           # Data models
└── services/               # Business services

License

MIT License - see LICENSE for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

Related Projects

• check_msdefender - Nagios plugin for Microsoft Defender