Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le 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

Aperta
  • Qualcosa non va?
#324 5 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
3/5
Tempo stimato
1-2 giorni
Idoneità per principianti
68/100
Tipo di issue
Documentazione
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Ambito
documentation

Direzione di ricerca

Inizia con il riferimento a persist-name() della 3.16 e con la pagina delle opzioni di destinazione di syslog() della 3.36, quindi individua le pagine corrispondenti in questo repository della documentazione. Riproduci i casi di ricaricamento dell'host/porta TCP e del protocollo documentati nell'issue e termina quando persist-name(), keep-alive(), i relativi riferimenti incrociati e il comportamento di riconnessione sono chiaramente documentati nella 3.36 Administration Guide.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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.
Lingua principale
JavaScript
Stelle
6
Fork
15
Merge medio
4g 13h
PR unite (30g)
4

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di syslog-ng/syslog-ng.github.io

Tutte le issue di syslog-ng/syslog-ng.github.io

Issue simili

Altre issue su JavaScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.