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

未关闭
  • 哪里不对？
#324 5 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

还没有人认领这个 Issue。

评估

难度
3/5
预计耗时
1-2 天
新手友好度
68/100
Issue 类型
文档
描述清晰度
基本清楚
活跃度
活跃
领域
documentation

调研方向

先查看 3.16 的 persist-name() 参考文档和 3.36 的 syslog() 目标选项页面，然后在此文档仓库中找到对应页面。复现 issue 中记录的 TCP 主机/端口和协议重新加载案例，并在 3.36 Administration Guide 中清楚记录 persist-name()、keep-alive()、它们的交叉引用以及重新连接行为后完成。

由索引模型根据 Issue 内容生成。

描述

bug documentation

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:

  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.
主要语言
JavaScript
星标
6
派生
14
平均合并
1 天 14 小时
30 天内合并 PR
2

环境准备

这个项目没有提供开发容器、Dockerfile 或贡献指南，环境需要你自己搭建：先看它的 README，通用步骤见我们的新手贡献指南。

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

syslog-ng/syslog-ng.github.io 的其他 Issue

查看 syslog-ng/syslog-ng.github.io 的全部 Issue

相似的 Issue

更多 JavaScript Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。