persist-name() has no dedicated reference page in the 3.36 Administration Guide, and its role in destination reload/reconnect behavior (interaction with keep-alive()) is undocumented

Incorrect section

persist-name() global option documentation, stable reference (3.16 guide):

• https://support.oneidentity.com/technical-documents/syslog-ng-open-source-edition/3.16/administration-guide/persist-name

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:

• https://syslog-ng.github.io/admin-guide/070_Destinations/300_syslog/000_syslog_destination_options.html

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:

1. Configure a syslog() destination with a fixed persist-name() pointed at server A over TCP.
2. Confirm connection via netstat -tn.
3. Change only the destination's server/port (protocol unchanged) to server B; reload (SIGHUP).
4. Observe: netstat -tn still shows the connection to server A; syslog-ng stats report server B.
5. Add keep-alive(no) to the destination; repeat step 3 — connection now correctly moves to the new server.
6. 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.

Start with the 3.16 persist-name() reference and the 3.36 syslog() destination options page, then locate their corresponding pages in this documentation repository. Reproduce the documented TCP host/port and protocol reload cases from the issue, and finish when persist-name(), keep-alive(), their cross-references, and the reconnect behavior are clearly documented in the 3.36 Administration Guide.