Incorrect section
persist-name() global option documentation, stable reference (3.16 guide):
Note: No equivalent, clearly relevant documentation for persist-name() could be located in the syslog-ng OSE 3.36 Administration Guide. persist-name() appears to be the correct mechanism for a case where two destinations share the same host, port, and protocol but differ only in template — without an explicit persist-name() on each, syslog-ng fails. The 3.16 URL above is cited as the clearest available reference for this option's documented purpose.
Related, for cross-reference: keep-alive() on the syslog() destination options page:
Description of the problem
Version tested: syslog-ng 3 (3.36.1)
The persist-name() documentation describes it solely as a way to avoid the startup error "Error checking the uniqueness of the persist names, please override it with persist-name option. Shutting down." when two identical driver instances collide. It does not document that, for destination drivers, persist-name() is also the key syslog-ng uses to decide whether to preserve an existing connection across a config reload (SIGHUP) rather than tearing it down and reconnecting.
In testing on 3.36.1, a syslog() destination configured with a fixed persist-name() kept its connection alive across a reload when only the destination's host/port was changed in the new config — traffic continued flowing to the old endpoint, while syslog-ng's own stats reported the new endpoint (since stats are generated from the live config rather than the actual connected socket; confirmed via netstat -tn showing the socket still connected to the previous endpoint). Forcing a genuine reconnect in this scenario required explicitly setting keep-alive(no) on the destination for that reload — this requirement, and its causal link to persist-name(), is not documented anywhere.
Notably, when the destination's transport protocol was changed (TCP⇄UDP) — with or without a simultaneous host/port change — the connection was correctly torn down and re-established on the same reload, with no keep-alive(no) override needed. This shows the reload/reconnect behavior is inconsistent depending on which parameter changes, which is not explained anywhere in the current persist-name() or keep-alive() documentation.
Proposed solution
Add an explicit, dedicated persist-name() reference page for the syslog-ng OSE 3.36 Administration Guide, as none currently exists. That page should note that for destination drivers, this value also determines whether the underlying connection is preserved across a reload — and that changing connection-relevant parameters (host/port) while keeping persist-name() constant will not force a reconnect on its own; keep-alive(no) must be set explicitly to force reconnection in that case. Also clarify why a protocol change behaves differently (forcing a reconnect regardless of persist-name()/keep-alive()), since this asymmetry is not documented. Cross-reference keep-alive() from this note, and vice versa, since the two options jointly determine reload/reconnect behavior.
Reproduction steps supporting this report:
- Configure a
syslog() destination with a fixed persist-name() pointed at server A over TCP.
- Confirm connection via
netstat -tn.
- Change only the destination's server/port (protocol unchanged) to server B; reload (SIGHUP).
- Observe:
netstat -tn still shows the connection to server A; syslog-ng stats report server B.
- Add
keep-alive(no) to the destination; repeat step 3 — connection now correctly moves to the new server.
- Separately, change only the destination's protocol (TCP → UDP), with
keep-alive() unset — observe the connection is correctly torn down and re-established, unlike step 3/4.
Incorrect section
persist-name()global option documentation, stable reference (3.16 guide):Note: No equivalent, clearly relevant documentation for
persist-name()could be located in the syslog-ng OSE 3.36 Administration Guide.persist-name()appears to be the correct mechanism for a case where two destinations share the same host, port, and protocol but differ only in template — without an explicitpersist-name()on each, syslog-ng fails. The 3.16 URL above is cited as the clearest available reference for this option's documented purpose.Related, for cross-reference:
keep-alive()on thesyslog()destination options page:Description of the problem
Version tested: syslog-ng 3 (3.36.1)
The
persist-name()documentation describes it solely as a way to avoid the startup error"Error checking the uniqueness of the persist names, please override it with persist-name option. Shutting down."when two identical driver instances collide. It does not document that, for destination drivers,persist-name()is also the key syslog-ng uses to decide whether to preserve an existing connection across a config reload (SIGHUP) rather than tearing it down and reconnecting.In testing on 3.36.1, a
syslog()destination configured with a fixedpersist-name()kept its connection alive across a reload when only the destination's host/port was changed in the new config — traffic continued flowing to the old endpoint, while syslog-ng's own stats reported the new endpoint (since stats are generated from the live config rather than the actual connected socket; confirmed vianetstat -tnshowing the socket still connected to the previous endpoint). Forcing a genuine reconnect in this scenario required explicitly settingkeep-alive(no)on the destination for that reload — this requirement, and its causal link topersist-name(), is not documented anywhere.Notably, when the destination's transport protocol was changed (TCP⇄UDP) — with or without a simultaneous host/port change — the connection was correctly torn down and re-established on the same reload, with no
keep-alive(no)override needed. This shows the reload/reconnect behavior is inconsistent depending on which parameter changes, which is not explained anywhere in the currentpersist-name()orkeep-alive()documentation.Proposed solution
Add an explicit, dedicated
persist-name()reference page for the syslog-ng OSE 3.36 Administration Guide, as none currently exists. That page should note that for destination drivers, this value also determines whether the underlying connection is preserved across a reload — and that changing connection-relevant parameters (host/port) while keepingpersist-name()constant will not force a reconnect on its own;keep-alive(no)must be set explicitly to force reconnection in that case. Also clarify why a protocol change behaves differently (forcing a reconnect regardless ofpersist-name()/keep-alive()), since this asymmetry is not documented. Cross-referencekeep-alive()from this note, and vice versa, since the two options jointly determine reload/reconnect behavior.Reproduction steps supporting this report:
syslog()destination with a fixedpersist-name()pointed at server A over TCP.netstat -tn.netstat -tnstill shows the connection to server A; syslog-ng stats report server B.keep-alive(no)to the destination; repeat step 3 — connection now correctly moves to the new server.keep-alive()unset — observe the connection is correctly torn down and re-established, unlike step 3/4.