From 4969b2891f8df93f78b94dc44dbf0543465255f5 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Fri, 10 Sep 2021 23:29:11 +0000 Subject: Fix, test and document nsssd-switch Signed-off-by: Laurent Bercot --- doc/nsssd-switch.html | 135 ++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 119 insertions(+), 16 deletions(-) (limited to 'doc/nsssd-switch.html') diff --git a/doc/nsssd-switch.html b/doc/nsssd-switch.html index 9f5672c..bd6f63b 100644 --- a/doc/nsssd-switch.html +++ b/doc/nsssd-switch.html @@ -36,7 +36,7 @@ configuration on the command line.

Interface 

-     s6-ipcserver -l0 /run/service/nsssd/s nsssd-switch bitfield1 backend1... "" bitfield2 backend2... "" ...
+     s6-ipcserver -l0 /run/service/nsssd/s nsssd-switch [ -t timeout ] bitfield1 backend1... "" bitfield2 backend2... "" ...

@@ -52,35 +52,132 @@ configuration on the command line.

+

Exit codes

-

Notes

+

+ These exit codes are not important because only the super-server can see them. +

+ +
    +
  • 0: normal exit or timeout while waiting for a client query
    • +
  • 100: wrong usage
    • +
  • 111: system call failed or timeout during a nsss protocol exchange
    • +
+ +

Options

+ +
    +
  • -t timeout : enforce a limit of +timeout milliseconds when communicating with a backend. If a +backend fails to answer a query under timeout milliseconds, +nsssd-switch will return a failure code to the client, and +the backend will be considered permanently failed. The default is 0, +meaning no such timeout - backends can take as much time as they want +to answer queries.
    • +
+ +

Environment variables

- nsssd-switch is not meant to be called directly; instead, it is expected to be run from -a script as a part of a "nsssd" -local service. + nsssd-switch can read a number x in the NSSSD_TIMEOUT +environment variable. If this variable is present and valid, it means that +nsssd-switch will die if x milliseconds elapse without +the client reading or writing during a nsss protocol exchange, which usually +means the client either is not speaking the protocol correctly or has become +unresponsive. It is a safety measure to avoid having nsssd processes +sticking around forever when a client is buggy. +

+ +

+ Note that the NSSSD_TIMEOUT variable refers to a timeout during an exchange +with the client, while the argument to the -t option refers +to a timeout enforced on the backends.

+

Bitfields

+

+ A bitfield is a value between 0 and 7, representing 3 bits. If a +bit is 0, it means that the query resolution will continue to the next +backend if the corresponding failure condition is triggered. If the +bit is 1, it means that the failure will instantly be reported to the client +and the query will not be transmitted to the next backend in the chain. +

+ + + +

+ So, for instance, a bitfield of 5 means: report failure to the client if the +current backend is in a failed state or if a requested entry cannot be found. +Proceed to the next backend if the current backend reports failure when +processing a query. +

+ +

+ This format allows the administrator to configure various fallback strategies. +Note that in case of success, the requested data is immediately returned to the +client. nsssd-switch does not provide the equivalent of the merge +directive in /etc/nsswitch.conf. +

+ +

Notes

+ +