ipvsman manages Linux IPVS services from YAML drop-ins.

Every invocation must either run the long-lived service (--service) or a one-shot action (for example --test, --list-services, --status-detailed).

# Validate config
ipvsman.py --test
# One-shot status
ipvsman.py --status-detailed --show-counters
# Daemon mode (e.g. under systemd)
ipvsman.py --service

# Lists
ipvsman.py --list-services
ipvsman.py --list-frontends
ipvsman.py --list-backends
ipvsman.py --list-healthchecks
# Manual checks
ipvsman.py --healthcheck-now
ipvsman.py --healthcheck-now-group dns-core
ipvsman.py --healthcheck-now-backend dns-core/10.0.0.10
# Filtered watch output
ipvsman.py --status-detailed --filter-group dns-core --watch 2

--service is mutually exclusive with one-shot actions (--test, --list-*, --status, --status-detailed, --reset, --healthcheck-now, ...).

Naming: backend resolve metrics mirror backend IP change — global ipvsman_backend_resolve_error_events_total, per-frontend ipvsman_backend_resolve_errors_total / ipvsman_backend_resolve_errors_last_timestamp_seconds. When live IPVS stats are enabled, scrape errors increment ipvsman_ipvs_stats_scrape_failures_total (counter).

Configured stats labels:

• service metrics: group, frontend
• real metrics: group, frontend, address, backend_port (address maps to configured backend address/hostname when available)

Healthcheck metrics:

• ipvsman_healthcheck_state (1 healthy, 0 unhealthy, -1 unknown)
• ipvsman_healthcheck_ready (1 ready, 0 not ready)
• Labels follow the same configured/route/both mode as stats labels.

Example alert (Prometheus):

groups:
 - name: ipvsman
 rules:
 - alert: IpvsmanIpvsStatsScrapeFailing
 expr: increase(ipvsman_ipvs_stats_scrape_failures_total[5m]) > 0
 for: 5m
 labels:
 severity: warning
 annotations:
 summary: ipvsman cannot read live IPVS stats for metrics

The directory passed to --config-dir (default /usr/local/etc/ipvsman) contains:

• groups/*.yaml
• backends/*.yaml
• backend-maps/*.yaml
• check-refs/*.yaml

Path rules for backend_files:

• only relative paths are allowed
• absolute paths are rejected
• path traversal outside that config directory is rejected

- group: dns-core
 vip: [192.0.2.1, 198.51.100.1]
 scheduler: wrr
 frontends:
 - name: dns-udp
 proto: udp
 port: domain
 - name: dns-tcp
 proto: tcp
 port: domain
 - name: doh
 proto: tcp
 port: https
 vip: [192.0.2.2]
 scheduler: rr
 backend_map_ref: dns_pool
 healthcheck:
 type: dns
 query_name: health.example.com
 query_type: A
 interval: 10
 timeout: 3
 rise: 2
 fall: 3

dns_pool:
 - ip: 10.0.0.10
 weight: 10
 port_map:
 "domain": 53
 - ip: 10.0.0.11
 weight: 10
 port_map:
 "*": 5353
 check_ref: registry-ns2

registry-ns2:
 ip: 192.168.1.100
 port: 9999
 type: http
 path: /status/ns2

API is off by default. Enable with --api-enable.

# API enabled (daemon)
ipvsman.py --service --api-enable --api-host 127.0.0.1 --api-port 9111
# Token from env
export IPVSMAN_API_TOKEN='replace-with-secret'
ipvsman.py --service --api-enable

Token resolution order:

• --api-token
• IPVSMAN_API_TOKEN
• unset (no auth required)

Security note:

• if --api-host is not localhost (127.0.0.1, localhost, ::1) and no token is set, startup logs an ALERT

Rate limiting:

• per-IP sliding window on all API routes
• default 300 requests/minute per client IP
• overflow returns 429 {"error":"rate limit"}

Read endpoints:

• GET /v1/services
• GET /v1/frontends
• GET /v1/backends
• GET /v1/healthchecks
• GET /v1/status/detailed
• POST /v1/healthchecks/run
• GET /openapi.json
• GET /openapi.yaml
• GET /metrics (only when API + metrics are both enabled)

Write endpoint:

• PUT /v1/config (requires --api-enable-write)
• writes to groups/api-put.yaml
• reloads desired snapshot atomically

Common response codes:

• 401 unauthorized
• 403 write disabled
• 404 not found
• 413 payload too large
• 422 validation failed
• 429 rate limit exceeded

Standalone metrics server:

ipvsman.py --service --prometheus-metrics --prometheus-host localhost --prometheus-port 9110

If API and metrics are both enabled, /metrics is served on API port (9111 by default).

Format support:

• default: Prometheus text (text/plain; version=0.0.4)
• OpenMetrics: send Accept: application/openmetrics-text

• systemd: the role ships a static unit file that runs ipvsman.py --service. /etc/default/ipvsman may provide optional IPVSMAN_API_TOKEN and optional IPVSMAN_EXTRA_ARGS.
• single-instance lock prevents duplicate daemon runs
• SIGHUP triggers reload (systemctl reload ipvsman)
• apply worker is single-threaded with queue coalescing
• config version is newest loaded file mtime
• live IPVS polling uses --stats-interval
• API PUT enforces --api-max-body-bytes

cd files
PYTHONPATH=. python3 -m unittest discover -s src/test -v

This is an AI-assisted project: most implementation and routine edits were produced with Cursor agents/assistants, while design and architecture decisions remain human-driven.