From 47ee16b37ea3cc75cb62aa0a5699c674d8160839 Mon Sep 17 00:00:00 2001 From: Alexander Stephan Date: Thu, 18 Jun 2026 14:42:18 +0000 Subject: [PATCH 3/3] DOC: server: document 'option server-rename' and 'set server name' CLI command Document the new 'option server-rename' backend directive and the 'set server / name ' CLI command in configuration.txt and management.txt respectively. --- doc/configuration.txt | 32 ++++++++++++++++++++++++++++++++ doc/management.txt | 30 ++++++++++++++++++++++++++++++ 2 files changed, 62 insertions(+) diff --git a/doc/configuration.txt b/doc/configuration.txt index 2c00c8680..123278475 100644 --- a/doc/configuration.txt +++ b/doc/configuration.txt @@ -6187,6 +6187,7 @@ option pgsql-check X - X X option prefer-last-server (*) X - X X option redispatch (*) X - X X option redis-check X - X X +option server-rename - - X X option smtpchk X - X X option socket-stats (*) X X X - option splice-auto (*) X X X X @@ -11566,6 +11567,37 @@ option redis-check See also : "option httpchk", "option tcp-check", "tcp-check expect" +option server-rename + Enable runtime renaming of servers via the CLI. + + May be used in the following contexts: tcp, http + + May be used in sections : defaults | frontend | listen | backend + no | no | no | yes + + When this option is enabled in a backend, it allows the name of any server in that backend to be changed at runtime using the CLI command: + set server / name + + Restrictions: + - The new name must be unique among all servers in the backend. + - The change is effective immediately for all runtime operations, stats, and logs. + - The new name is not persisted to the configuration file and will be lost on reload. + - Renaming is only available if 'option server-rename' is set in the backend + or in a defaults section. + - Some features that rely on static server names (such as certain stick-tables or external monitoring) may not recognize the new name until restart. + + Example: + backend myapp + option server-rename + server s1 10.0.0.1:80 + server s2 10.0.0.2:80 + + To rename server 's1' to 'blue': + echo "set server myapp/s1 name blue" | socat /var/run/haproxy.sock - + + See also: 'set server / name' in the management guide (doc/management.txt). + + option smtpchk option smtpchk Use SMTP health checks for server testing diff --git a/doc/management.txt b/doc/management.txt index ee36f7037..8d09d8c34 100644 --- a/doc/management.txt +++ b/doc/management.txt @@ -2688,6 +2688,36 @@ set server / ssl [ on | off ] (deprecated) This command is deprecated, create a new server dynamically with or without SSL instead, using the "add server" command. +set server / name + Change the name of a server at runtime (if 'option server-rename' + is enabled in the backend or a defaults section). + + The new name must be unique among all servers in the backend. The + change is effective immediately for all runtime operations, stats, + and logs, but is not persisted to the configuration file and will + be lost on reload. Some features that rely on static server names + (such as stick-tables or external monitoring) may not recognize + the new name until restart. + + There is no strict requirement that no sessions are active + before renaming. However, if there are active sessions, log entries + for those sessions may use either the old or new name, depending on + when the rename occurs relative to logging. This may result in split + or inconsistent logs for in-flight requests. If strict log consistency + is required, it is the user's responsibility to ensure all sessions + have finished before renaming (e.g., by draining or maintenance mode + and waiting for all connections to close). + + For most use cases, a clear naming scheme (such as srv1 → srv1-old, + srv1-new, or srv1*) allows correlating log entries before and after + the rename, even if some overlap occurs. Users should choose a naming + convention that fits their operational and troubleshooting needs. + + Example: + set server myapp/s1 name blue + + See also: 'option server-rename' in doc/configuration.txt. + set severity-output [ none | number | string ] Change the severity output format of the stats socket connected to for the duration of the current session. -- 2.43.7