Skip to main content
emisar

Nginx operations pack

v0.2.26

Operator pack for nginx — read-only status + access-log analysis, TLS cert probes, and narrow operator actions (test_config, reload, graceful quit, stop). Full restart is intentionally not included; use systemd for that.

18 allowed by default 3 need approval by default 1 denied by default
Pack ID
nginx
Vendor
emisar
OS
linux
Actions
22
Required binaries. Install these on the host before relying on the pack — an action that calls a missing one fails at run time.
nginx curl

Install

emisar pack install fetches this pack, re-validates it, and verifies its content hash against the --hash below — the exact bytes this page was rendered against, so a tampered copy is rejected — before copying it into the runner's packs dir. The command reloads a running daemon itself; no manual restart.

on the runner host 
sudo emisar pack install nginx --hash sha256:0261c68efbe84166ac565e6a13c85b68d31b608aad356d8f0d1c146f36b0e7bd

Setup

Operates on the local nginx instance on the runner host — no credentials needed. Status actions curl the stub_status endpoint at 127.0.0.1; config and signal actions run the nginx binary directly.

Environment

Set these on the runner host, then add each name to execution.inherit_env so the value reaches the action.

  • NGINX_ACCESS_LOG default /var/log/nginx/access.log

    Where this host's nginx access log lives, for the access-log actions. Set it when the log is outside /var/log/nginx — the actions' own log_path argument is deliberately contained to that directory, so this is how the host administrator, rather than a caller, declares a non-standard location.

  • NGINX_ERROR_LOG default /var/log/nginx/error.log

    Where this host's nginx error log lives, for error_tail. Same reasoning as NGINX_ACCESS_LOG .

Host access

Run these commands yourself on the runner host. Emisar shows and copies setup recipes; it never runs them.

Read protected Nginx configuration or signal its root-owned master.

nginx.config_dumpnginx.vhost_listnginx.upstream_listnginx.test_confignginx.reloadnginx.quit_gracefulnginx.stop_immediate

Run the Emisar service as root

Grant access 
sudo install -d -m 0755 /etc/systemd/system/emisar.service.d
printf '%s\n' '[Service]' 'User=root' 'Group=root' | sudo tee /etc/systemd/system/emisar.service.d/10-nginx-host-access.conf >/dev/null
sudo systemctl daemon-reload
sudo systemctl restart emisar
Verify access 
test "$(systemctl show emisar --property=User --value)" = root

Impact: Every Emisar action on this runner executes as root. Nginx actions can expose private configuration and can stop or reload the web server.

Read Nginx logs through the Debian or Ubuntu system log-reader group.

nginx.access_top_urlsnginx.access_top_clientsnginx.log_grep_5xxnginx.log_grep_4xxnginx.slow_requestsnginx.bytes_by_urlnginx.error_tail

Add the Emisar service user to adm

Grant access 
sudo usermod -aG adm emisar
sudo systemctl restart emisar
Verify access 
id -nG emisar | tr ' ' '\n' | grep -Fx adm
sudo -u emisar test -r /var/log/nginx/error.log

Impact: Every process running as emisar can read every host log granted to adm, not only Nginx logs. RHEL-family paths need an equivalent persistent log-reader grant.

Notes

  • Status actions require stub_status on; in a location reachable from 127.0.0.1; the url arg is loopback-only (127.0.0.1/localhost/[::1]) — pass a non-default port/path, not an off-host target.
  • Logs outside /var/log/nginx : set NGINX_ACCESS_LOG / NGINX_ERROR_LOG (and allowlist them in the runner's execution.inherit_env ). The log_path argument stays contained to /var/log/nginx because a caller — including an LLM — supplies it; the environment is host-administrator state, and anyone who can set it can already read the file. The official container image symlinks access.log to stdout, in which case no file exists to read at any path and the host's log collector owns it. For unrestricted /var/log access, install linux-core, whose name says so.

Verify it works

Runs nginx.active_version, a low-risk read that confirms the pack can reach its target. Run it on the host once the pack is installed; pack install runs it for you.

on the runner host 
sudo emisar pack verify nginx

Install and configure a pack walks through the whole sequence on a host.

Actions 22 total

View on GitHub
  • nginx.access_top_clients exec low Low — read-only or trivially reversible

    Top client IPs from access log

    Tail the access log and return the top N source IPs by hit count. Assumes the default combined log format (client IP in column 1). Use to spot abusive crawlers or single-host traffic spikes that hint at a misconfigured client. Read-only.

    View source on GitHub
  • nginx.access_top_urls exec low Low — read-only or trivially reversible

    Top URLs from access log

    Tail the access log, extract the request path, and return the top N by hit count. Assumes the default combined log format. Use to spot a noisy endpoint, a misbehaving crawler, or to size a cache. Read-only.

    View source on GitHub
  • nginx.active_version exec low Low — read-only or trivially reversible

    Active nginx version + build

    Run `nginx -V` and return the version + compile-time flags. Use to confirm which modules are compiled in (e.g. ngx_http_v2, ngx_http_realip) before recommending a config that depends on one. Read-only.

    View source on GitHub
  • nginx.bytes_by_url exec low Low — read-only or trivially reversible

    Top URLs by total bytes sent

    List top N URLs ordered by `$body_bytes_sent` summed per URL (column 10). Read-only.

    View source on GitHub
  • nginx.compiled_modules exec low Low — read-only or trivially reversible

    Compiled-in nginx modules

    Parse `nginx -V` to list `--with-*` and `--add-module` flags. Use to confirm a needed module (http_v2, realip, brotli) is present.

    View source on GitHub
  • nginx.config_dump exec high High — service-affecting

    Full loaded config (nginx -T)

    Dump the loaded config — main + all includes — via `nginx -T`. Config text can carry secrets (authorization headers set via proxy_set_header, credentials embedded in proxy_pass URLs or map/return directives). The runner's redaction is a fail-closed backstop, not a guarantee — it is pattern-bound and can miss a bespoke secret whose name and value match no rule.

    View source on GitHub
  • nginx.connections_now exec low Low — read-only or trivially reversible

    Active connections (stub_status)

    Hit the stub_status endpoint to get active/reading/writing/waiting counts. Cheaper than `nginx.status` (less parsing). Requires `stub_status on;` enabled. Loopback-only — the host is pinned to 127.0.0.1/localhost/[::1]; only the port and path vary.

    View source on GitHub
  • nginx.error_tail exec medium Medium — changes state, easily reversible

    Tail nginx error log

    Return the last N lines from /var/log/nginx/error.log. Use to spot upstream connect failures, SSL handshake errors, or worker crashes immediately after a reload. Read-only.

    View source on GitHub
  • nginx.log_grep_4xx exec medium Medium — changes state, easily reversible

    Recent 4xx responses from access log

    Grep the access log for 4xx status codes. Needs the log on disk — the official container image symlinks it to stdout, where the host's log collector owns it instead. Read-only.

    View source on GitHub
  • nginx.log_grep_5xx exec medium Medium — changes state, easily reversible

    Recent 5xx responses from access log

    Grep the access log for 5xx status codes (assumes combined log format). Needs the log on disk — the official container image symlinks it to stdout, where the host's log collector owns it instead. Read-only.

    View source on GitHub
  • nginx.master_pid exec low Low — read-only or trivially reversible

    nginx master PID

    Read /run/nginx.pid (or the configured pid path). Read-only.

    View source on GitHub
  • nginx.quit_graceful exec high High — service-affecting

    nginx graceful quit

    Stop nginx gracefully (`nginx -s quit`) — workers finish in-flight requests, then exit. No new connections accepted. Use to drain before host shutdown.

    View source on GitHub
  • nginx.reload exec high High — service-affecting

    nginx reload

    Send SIGHUP to the master process. Master parses the new config, spawns new workers, gracefully drains old workers. If the new config is invalid the master logs the error and keeps the old workers — the request is non-fatal. ALWAYS run `nginx.test_config` first.

    View source on GitHub
  • nginx.slow_requests exec low Low — read-only or trivially reversible

    Slowest requests (last N lines)

    List top N requests sorted by `$request_time`. Requires a log_format that includes `$request_time` as a specific column; default assumes column 11. Read-only.

    View source on GitHub
  • nginx.ssl_cert_expiry exec low Low — read-only or trivially reversible

    TLS cert expiry for one vhost

    Probe localhost:443 with SNI to read the cert expiry. Returns notBefore/notAfter and subject/issuer.

    View source on GitHub
  • nginx.ssl_chain_check exec low Low — read-only or trivially reversible

    TLS chain dump for one vhost

    Probe localhost:443 with SNI and dump the certificate chain. Use to confirm the intermediate cert is being served.

    View source on GitHub
  • nginx.status exec low Low — read-only or trivially reversible

    Nginx stub_status

    Fetch the nginx stub_status endpoint over loopback. Returns active connections, total requests, reading/writing/waiting counts. Requires `stub_status on;` in a location block reachable from 127.0.0.1. Loopback-only — the host is pinned to 127.0.0.1/localhost/[::1]; only the port and path vary. Read-only.

    View source on GitHub
  • nginx.stop_immediate exec critical Critical — data loss or irreversible

    nginx stop (immediate)

    Stop nginx immediately (`nginx -s stop`) — workers stop NOW. In-flight requests are dropped mid-byte. Prefer `nginx.quit_graceful` unless the server is hung.

    View source on GitHub
  • nginx.test_config exec low Low — read-only or trivially reversible

    nginx -t

    Run `nginx -t`. Validates the loaded config without applying. Use before every `nginx.reload`. A failing config returns non-zero exit and the error lines go to stderr.

    View source on GitHub
  • nginx.upstream_list exec low Low — read-only or trivially reversible

    List configured upstream blocks

    Grep `nginx -T` for `upstream` + `server` directives inside upstream blocks. Read-only.

    View source on GitHub
  • nginx.vhost_list exec low Low — read-only or trivially reversible

    List configured server_name + listen blocks

    Grep `nginx -T` output for `server_name` and `listen` directives — a compact view of every virtual host this nginx serves. Read-only.

    View source on GitHub
  • nginx.worker_count exec low Low — read-only or trivially reversible

    Live worker process count

    Count the workers spawned by the master via pgrep. Read-only.

    View source on GitHub
← Back to registry
Pack reference  Publish your own