NGINX Unit
v. 1.18.0

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 Unit installation:

$ unitd --help

    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.18.0 [/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 log has two verbosity modes: common and debug; steps to enable the latter vary by install method.

Warning

Debug log is meant for developers; it grows rapidly, so enable it only for detailed reports and inspection.

Installing From Our Repos§

Our repositories provide a debug version of unitd called unitd-debug within the unit package:

# unitd-debug <command line options>

Running From Docker Images§

To enable debug-level logging when using our Docker images:

$ docker run -d nginx/unit:1.18.0-full 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.18.0-full

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.

Building From Source§

To enable debug-level logging when installing from source, use the --debug option:

$ ./configure --debug <other options>

Then recompile and reinstall Unit and your specific language modules.

Core Dumps§

Core dumps help developers to resolve Unit crashes; providing them with your feedback is recommended. 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).

Warning

Disable core dumping on live production systems to avoid wasting disk space.

Systemd Service§

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

Manual Setup§

Linux§

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 and 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

FreeBSD§

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 installed as a service:

# service unitd restart

If 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§

Post your questions to our mailing list at unit@nginx.org; to subscribe, email unit-subscribe@nginx.org or sign up here. You can also visit our GitHub repo to report an issue, suggest a feature, or share a problem.

In addition, we offer commercial support.