From 749d535137849125e45c7f9b851e51357940845c Mon Sep 17 00:00:00 2001 From: Alexander Stephan Date: Tue, 16 Jun 2026 13:03:04 +0000 Subject: [PATCH 3/3] DOC: server: document 'option server-rename', global 'server-rename', and 'set server name' CLI command Add documentation for: - 'server-rename' in the global section keyword list and reference - 'option server-rename' in the backend keyword table and alphabetical reference section of configuration.txt - 'set server / name ' in management.txt --- doc/configuration.txt | 40 ++++++++++++++++++++++++++++++++++++++++ doc/management.txt | 30 ++++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+) diff --git a/doc/configuration.txt b/doc/configuration.txt index 2c00c8680..6ee547ca7 100644 --- a/doc/configuration.txt +++ b/doc/configuration.txt @@ -1817,6 +1817,7 @@ The following keywords are supported in the "global" section : - presetenv - prealloc-fd - resetenv + - server-rename - set-dumpable - set-var - setenv @@ -3209,6 +3210,14 @@ server-state-file configuration. See also "server-state-base" and "show servers state", "load-server-state-from-file" and "server-state-file-name" +server-rename + Enable runtime renaming of servers via the CLI for all backends globally. + When set, it allows the name of any server to be changed at runtime using + the CLI command "set server / name " without + requiring "option server-rename" in each backend individually. This option + supports the "no" prefix to disable it. See also: 'option server-rename' + for per-backend control. + set-dumpable [ on | off | libs ] This option helps choose the core dump behavior in case of process crash. Available options are: @@ -6187,6 +6196,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 @@ -6274,6 +6284,36 @@ use-server - - X X 4.2. Alphabetically sorted keywords reference + +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 'server-rename' is set in the global 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: 'server-rename' in the global section, 'set server / name' in the management guide (doc/management.txt). --------------------------------------------- This section provides a description of each keyword and its usage. diff --git a/doc/management.txt b/doc/management.txt index ee36f7037..5afc85bbe 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 'server-rename' is set in the global 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