Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

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

Đang mở
  • Có gì không ổn?
#324 5 bình luận 0 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

Đánh giá

Độ khó
3/5
Thời gian dự kiến
1-2 ngày
Mức phù hợp với người mới
68/100
Loại issue
Tài liệu
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Sôi nổi
Lĩnh vực
documentation

Hướng nghiên cứu

Bắt đầu với tài liệu tham chiếu về persist-name() của 3.16 và trang các tùy chọn đích đến của syslog() trong 3.36, sau đó tìm các trang tương ứng trong repository tài liệu này. Tái hiện các trường hợp reload TCP host/port và protocol được nêu trong issue, và hoàn tất khi persist-name(), keep-alive(), các tham chiếu chéo của chúng cùng hành vi reconnect được tài liệu hóa rõ ràng trong 3.36 Administration Guide.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.
Ngôn ngữ chính
JavaScript
Star
6
Fork
15
Merge trung bình
6 ngày 1 giờ
Pull request đã merge (30 ngày)
3

Chuẩn bị môi trường

Dự án này không cung cấp dev container, Dockerfile hay hướng dẫn đóng góp, nên bạn cần tự thiết lập môi trường: hãy bắt đầu từ README và xem hướng dẫn đóng góp lần đầu của chúng tôi để biết các bước chung.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của syslog-ng/syslog-ng.github.io

Tất cả issue của syslog-ng/syslog-ng.github.io

Issue tương tự

Thêm issue về JavaScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.