Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de 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

Abierto
  • ¿Algo no está bien?
#324 5 comentarios 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
3/5
Tiempo estimado
1-2 días
Aptitud para principiantes
68/100
Tipo de issue
Documentación
Claridad
Bastante claro
Estado de actividad
Activo
Área
documentation

Línea de trabajo

Comienza con la referencia de persist-name() de 3.16 y la página de opciones de destino de syslog() de 3.36; después, localiza sus páginas correspondientes en este repositorio de documentación. Reproduce los casos de recarga de host/puerto TCP y del protocolo documentados en el issue, y termina cuando persist-name(), keep-alive(), sus referencias cruzadas y el comportamiento de reconexión estén claramente documentados en la 3.36 Administration Guide.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.
Lenguaje dominante
JavaScript
Estrellas
6
Forks
15
Merge medio
6 d 1 h
PR fusionados (30 d)
3

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de syslog-ng/syslog-ng.github.io

Todos los issues de syslog-ng/syslog-ng.github.io

Issues similares

Más issues de JavaScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.