sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-08-24 16:51:26 +02:00
Code Issues Packages Projects Releases Wiki Activity

Add docs for logging env vars and log rotation troubleshooting (#763)

Browse Source 
Adds docs for env variables for logging (including the new NB_LOG_DISABLE_ROTATION) and troubleshooting using external logging rotation (describing also new detection behavior).
This commit is contained in:
Theodor Midtlien
2026-06-04 17:37:15 +02:00
committed by GitHub
parent d7d9e75e5b
commit 711faa386e
2 changed files with 47 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
src/pages/client/environment-variables.mdx
View File

@@ -112,6 +112,14 @@ These control the exponential backoff when the client loses its connection to th
|---|---|---|
| `NB_MANAGEMENT_GRPC_MAX_MSG_SIZE` | All | Maximum size (in bytes) of a single gRPC message from the management server. Increase this when the network map (peers, firewall rules, routes, DNS config) exceeds the default 4 MB gRPC limit. |
## Logging
| Variable | Platform | Description |
|---|---|---|
| `NB_LOG_FORMAT` | All | Override the log output format. Accepted values: `json` (one JSON object per line) or `syslog` (compact format used when logging to syslog). Anything else falls back to the default human-readable text formatter. The `syslog` value is also selected automatically when the log destination is set to `syslog`. |
| `NB_LOG_MAX_SIZE_MB` | All | Maximum size in megabytes of a single log file before NetBird's built-in rotation triggers (default: `15`). Only effective when the built-in rotation is active, see `NB_LOG_DISABLE_ROTATION` and [Log rotation](/help/troubleshooting-client#log-rotation). |
| `NB_LOG_DISABLE_ROTATION` | All | Set to `true` to disable NetBird's built-in log rotation. NetBird will write to the configured log file directly and leave rotation to an external tool (e.g. system `logrotate` on Linux). On Linux, NetBird also auto-disables its own rotation when it detects a `logrotate` config that mentions `netbird`, this variable lets you force the same behavior on other platforms or when the auto-detection misses your config. Also see [Log rotation troubleshooting](/help/troubleshooting-client#log-rotation). |
## Other
| Variable | Platform | Description |

39
src/pages/help/troubleshooting-client.mdx
View File

@@ -94,6 +94,45 @@ By default, client logs are located in the `/var/log/netbird/client.log` file on
You can analyze the logs to identify the root cause of the problem. If you need help, open
a [github issue](https://github.com/netbirdio/netbird/issues/new/choose) and attach the logs.
### Log rotation
NetBird rotates `client.log` itself by default, old files are written next to the active log as gzipped archives (e.g. `client-2025-04-01T12-00-00.000.log.gz`). The maximum size of the active file is controlled by [`NB_LOG_MAX_SIZE_MB`](/client/environment-variables#logging) (default: 15 MB).
Running NetBird's built-in rotation **and** the `logrotate` service for Linux on the same file causes problems where the log file might become corrupted and logs lost. To avoid this, NetBird scans `/etc/logrotate.conf` and `/etc/logrotate.d/*` on Linux startup. If any non-comment line mentions `netbird`, the client logs a warning and disables its own rotation, letting `logrotate` own the file. You will see a line like this in `netbird.err` or the console:
```text
log rotation conflict detected in: "/etc/logrotate.d/netbird", rotation is disabled
```
<Note>
To use `logrotate`, we require `copytruncate` and not `create` to be set in the config file, otherwise the daemon needs to be restarted for the new log file to be opened after rotation.
Netbird supports `compress`, `delaycompress` and `nocompress`.
</Note>
On macOS and BSD systems, the equivalent of `logrotate` is `newsyslog`, configured via `/etc/newsyslog.conf` or files in `/etc/newsyslog.d/`. NetBird does not auto-detect `newsyslog` configurations, so if you want `newsyslog` to manage `client.log` you must set [`NB_LOG_DISABLE_ROTATION=true`](/client/environment-variables#logging) on the daemon to disable the built-in rotation. An example `/etc/newsyslog.d/netbird.conf` entry:
```text
# logfilename [owner:group] mode count size when flags
/var/log/netbird/client.log root:wheel 600 10 15360 * Z
```
The `Z` flag tells `newsyslog` to gzip rotated files, which the debug bundle can read.
<Note>
`newsyslog` rotates by renaming the active file and creating a new one (analogous to `logrotate`'s default `create` mode, not `copytruncate`). After rotation, the netbird daemon still holds the file descriptor of the renamed file and will keep writing to it until restarted. Restart the daemon after `newsyslog` runs, or write logs to syslog instead and let `newsyslog` manage the syslog file.
</Note>
If you want to force disable log rotation (for example if your `logrotate` config lives outside `/etc/logrotate.d/` or does not contain the literal string `netbird`, or you are using `newsyslog` or another external rotator), set [`NB_LOG_DISABLE_ROTATION=true`](/client/environment-variables#logging) on the daemon. When the env flag is set, `netbird.err` or the console will show:
```text
log rotation is disabled by env flag
```
<Warning>
If you disable built-in rotation without configuring an external rotator, `client.log` will grow without bound. Make sure something is rotating the file before turning rotation off.
</Warning>
### Debug bundle
A debug archive containing the recent logs and the status at the time of execution can be generated with the following