YANPM/apps/agent/doc/troubleshooting.md

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.