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
まだ誰も着手していません。
評価
- 難易度
- 3/5
- 見積もり時間
- 1〜2日
- 初心者へのやさしさ
- 68/100
- issue の種類
- ドキュメント
- 明瞭さ
- おおむね明確
- 活発さ
- 活発
調査の方向性
3.16 の persist-name() リファレンスと 3.36 の syslog() の宛先オプションのページから始め、次にこのドキュメントリポジトリ内で対応するページを見つけます。issue に記載されている TCP ホスト/ポートとプロトコルのリロードのケースを再現し、persist-name()、keep-alive()、それらの相互参照、および再接続の動作が 3.36 Administration Guide に明確に記載されたら完了します。
索引モデルが issue の本文から書いたものです。
説明
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 fixedpersist-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 -tnstill 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.
- 主要言語
- JavaScript
- スター
- 6
- フォーク
- 14
- 平均マージ
- 6日 1時間
- マージ済み PR（30日）
- 3
環境構築
このプロジェクトには開発コンテナ、Dockerfile、コントリビューションガイドがありません。まず README を読み、一般的な手順ははじめてのコントリビューションガイドを参照してください。
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
syslog-ng/syslog-ng.github.io のほかの issue
-
documentation enhancement
難易度 2/5 1〜3時間 初心者へのやさしさ 68/100
syslog-ng/syslog-ng.github.io#306 · コメント 8 件 ·
-
documentation enhancement
難易度 4/5 3〜5日 初心者へのやさしさ 35/100
syslog-ng/syslog-ng.github.io#292 ·
-
documentation enhancement
難易度 4/5 3〜5日 初心者へのやさしさ 35/100
syslog-ng/syslog-ng.github.io#253 ·
-
bug
難易度 3/5 1〜2日 初心者へのやさしさ 35/100
syslog-ng/syslog-ng.github.io#235 ·
-
documentation enhancement
難易度 5/5 1週間以上 初心者へのやさしさ 35/100
syslog-ng/syslog-ng.github.io#215 ·
syslog-ng/syslog-ng.github.io の issue をすべて見る
似ている issue
-
難易度 2/5 1〜3時間 初心者へのやさしさ 68/100
awesome-dsh-plugin/awesome-dsh-plugin#9184 ·
メンテナーはふだん 1 日以内に返信
-
Cloudredirectオープン
難易度 1/5 1時間未満 初心者へのやさしさ 70/100
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 75/100
メンテナーはふだん 1 日以内に返信
-
0.2.1-rc.3 compatibility: 21 peer ranges enumerate exact versions, so rc.3 is rejected対応中かも このイシューにリンクされたプルリクエストがオープン中、またはマージ済みです。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 76/100
NanmiCoder/dsh-agent-teams#277 ·
メンテナーはふだん 1 日以内に返信
-
[ordering-review] workshop order graph: 1 confirmed ordering problem, 3 cycles are false positivesオープン
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
githubnext/gh-aw-workshop#4943 ·
メンテナーはふだん 1 日以内に返信