Troubleshooting§
Logging§
Unit maintains a single general-purpose log for diagnostics and troubleshooting (not to be confused with the access log). To find out its default location in your installation:
$ unitd -h
unit options:
...
--log FILE set log filename
default: "/path/to/unit.log"
The --log option overrides the default value;
if Unit is already running,
check whether this option is set:
$ ps ax | grep unitd
...
unit: main v1.29.1 [/path/to/unitd ... --log /path/to/unit.log ...]
If Unit isn’t running,
see its system startup scripts or configuration files
to check if --log is set,
and how.
Note
Mind that our Docker images forward their log output to the Docker log collector instead of a file.
Debug Log§
Unit’s log has two verbosity modes, common and debug; the steps to enable debug vary by install method.
Warning
Debug log is meant for developers; it grows rapidly, so enable it only for detailed reports and inspection.
Our repositories provide a debug version of unitd called unitd-debug within the unit package:
# unitd-debug <command line options>
To enable debug-level logging when using our Docker images:
$ docker run -d nginx/unit:1.29.1-minimal unitd-debug --no-daemon \
--control unix:/var/run/control.unit.sock
Another option is adding a new layer in a Dockerfile:
FROM nginx/unit:1.29.1-minimal
CMD ["unitd-debug","--no-daemon","--control","unix:/var/run/control.unit.sock"]
The CMD instruction above
replaces the default unitd executable
with its debug version.
To enable debug-level logging when
installing from source,
use the --debug option:
$ ./configure --debug <other options>
Then recompile and reinstall Unit and your language modules of choice.
Core Dumps§
Core dumps help us investigate crashes;
attach them when
reporting an issue.
For builds from
our repositories,
we maintain debug symbols in special packages;
they have the original packages’ names with the -dbg suffix appended,
such as unit-dbg.
Note
This section assumes you’re running Unit as root (recommended).
To enable saving core dumps
while running Unit as a systemd service
(for example, with
packaged installations),
adjust the
service settings
in /lib/systemd/system/unit.service:
[Service]
...
LimitCORE=infinity
LimitNOFILE=65535
Alternatively,
update the
global settings
in /etc/systemd/system.conf:
[Manager]
...
DefaultLimitCORE=infinity
DefaultLimitNOFILE=65535
Next, reload the service configuration and restart Unit to reproduce the crash condition:
# systemctl daemon-reload
# systemctl restart unit.service
After a crash, locate the core dump file:
# coredumpctl -1 # optional
TIME PID UID GID SIG COREFILE EXE
Mon 2020-07-27 11:05:40 GMT 1157 0 0 11 present /usr/sbin/unitd
# ls -al /var/lib/systemd/coredump/ # default, see also /etc/systemd/coredump.conf and /etc/systemd/coredump.conf.d/*.conf
...
-rw-r----- 1 root root 177662 Jul 27 11:05 core.unitd.0.6135489c850b4fb4a74795ebbc1e382a.1157.1590577472000000.lz4
Check the
core dump settings
in /etc/security/limits.conf,
adjusting them if necessary:
root soft core 0 # disables core dumps by default
root hard core unlimited # enables raising the size limit
Next, raise the core dump size limit with ulimit, then restart Unit to reproduce the crash condition:
# ulimit -c unlimited
# cd /path/to/unit/
# sbin/unitd # or sbin/unitd-debug
After a crash, locate the core dump file:
# ls -al /path/to/unit/working/directory/ # default location, see /proc/sys/kernel/core_pattern
...
-rw-r----- 1 root root 177662 Jul 27 11:05 core.1157
Check the
core dump settings
in /etc/sysctl.conf,
adjusting them if necessary:
kern.coredump=1
# must be set to 1
kern.corefile=/path/to/core/files/%N.core
# must provide a valid pathname
Alternatively, update the settings in runtime:
# sysctl kern.coredump=1
# sysctl kern.corefile=/path/to/core/files/%N.core
Next, restart Unit to reproduce the crash condition. If Unit is installed as a service:
# service unitd restart
If it’s installed manually:
# cd /path/to/unit/
# sbin/unitd
After a crash, locate the core dump file:
# ls -al /path/to/core/files/
...
-rw------- 1 root root 9912320 Jul 27 11:05 unitd.core
Getting Support§
| Support Channel | Details |
|---|---|
| GitHub | Visit our repo to submit issues, suggest features, ask questions, or see the roadmap. |
| Mailing lists | To post questions to unit@nginx.org and get notifications, including release news, email unit-subscribe@nginx.org or sign up here. To receive all OSS release announcements from NGINX, join the general mailing list here. |
| Security alerts | Please report security issues to security-alert@nginx.org, specifically mentioning NGINX Unit in the subject and following the CVSS v3.1 specification. |
In addition, we offer commercial support.