28 lines
1.8 KiB
Markdown
28 lines
1.8 KiB
Markdown
# Troubleshooting
|
|
|
|
Common issues and how to resolve them
|
|
|
|
- Socket path exists but is not a socket
|
|
- Symptom: startup fails with an error that the socket path exists and is not a socket.
|
|
- Fix: remove the file at the socket path or choose a different `--sock` path.
|
|
|
|
- Permission denied on socket directory or socket
|
|
- Symptom: socket creation or permission setting logs warnings; clients cannot connect.
|
|
- Fix: ensure the socket directory exists and has correct ownership/group and that `sock_perm` and `sock_gid` are configured appropriately. Consider using `chown`/`chmod` from a privileged context.
|
|
|
|
- `nginx -t` fails with `/run/nginx.pid: Permission denied`
|
|
- Symptom: validation fails; output contains permission denied for `/run/nginx.pid`.
|
|
- Fixes (tried by the agent):
|
|
1. If available, provide a privileged validation wrapper (e.g. `/usr/local/sbin/yanpm-nginx-validate`) that runs `nginx -t` with appropriate privileges.
|
|
2. Ensure the agent-runner has permission to read the main nginx configuration and `/run/nginx.pid` or allow the agent to use a writable PID override.
|
|
|
|
- Fragment file not found during validation
|
|
- Symptom: validate returns 500 with message `Config file not found`.
|
|
- Fix: make sure the fragment has been written via `/write_config` to the agent's internal subdirectory under `NGINX_CONFIG_DIR`, using the same `config_name` and `timestamp` as the validate call.
|
|
|
|
- Wrapper or sudo not available
|
|
- Symptom: attempts to run `sudo -n /usr/local/sbin/yanpm-nginx-validate` fail.
|
|
- Fix: install a wrapper script that allows unprivileged `sudo -n` validation or configure proper permissions on nginx state files.
|
|
|
|
If none of the above solves the problem, collect the logs produced by the agent (it uses `tracing`/`tracing_subscriber`) and include the exact command outputs from the validation steps when asking for help.
|