From f81ab3f13691585be427d4af5f6eecf7b13e8704 Mon Sep 17 00:00:00 2001 From: Artem Blagodarenko Date: Tue, 3 Dec 2024 18:22:22 -0500 Subject: [PATCH] LU-930 man: add proper documentation for replace_nids command The current entry in the lctl.8 man page and manual entry are totally lacking in explanation of what the various NIDs mean. It should explain the behaviour of failover NIDs. A separate "lctl replace_nids" man page was created and some additional information added. Test-Parameters: trivial Signed-off-by: Artem Blagodarenko Change-Id: I35e8fa26c109811a7411a73cd40ad811c2256e1b Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/57270 Tested-by: jenkins Tested-by: Maloo Reviewed-by: Frederick Dilger Reviewed-by: Andreas Dilger Reviewed-by: Oleg Drokin --- lustre/doc/lctl-replace_nids.8 | 79 ++++++++++++++++++++++++++++++++++++++++++ lustre/doc/lctl.8 | 18 +++------- 2 files changed, 84 insertions(+), 13 deletions(-) create mode 100644 lustre/doc/lctl-replace_nids.8 diff --git a/lustre/doc/lctl-replace_nids.8 b/lustre/doc/lctl-replace_nids.8 new file mode 100644 index 0000000..94dbf88 --- /dev/null +++ b/lustre/doc/lctl-replace_nids.8 @@ -0,0 +1,79 @@ +.TH LCTL-REPLACE_NIDS 8 2025-02-06 "Lustre" +.SH NAME +lctl-replace_nids \- Replace LNet NIDs for an MDT or OST +.SH SYNOPSIS +.SY "lctl replace_nids" +.IR "DEVICE_NAME NODEA_NID1" [, NODEA_NID2 [: NODEB_NID1 , NODEB_NID2 ...]] +.YS +.SH DESCRIPTION +The +.B lctl replace_nids +command is used to replace Network Identifiers (NIDs) in a Lustre file system. +.PP +This is useful when a server's network address changes and you need to update +the file system configuration to reflect the new address. +.PP +This command must be run on the MGS node. Only MGS server should be started +(command execution returns error in another case). +.PP +To start the MGS service only: +.BI "mount -t lustre " MGT_DEVICE " -o nosvc " MOUNT_POINT +.PP +Note the +.B replace_nids +command removes any invalidated records in the configuration log. The previous +log is backed up with the suffix +.RB '.bak'. +.PP +Failover nids must be passed after +.RB ':' +symbol. More then one failover +can be set (every failover nids after +.RB ':' +symbol). +.PP +The +.B replace_nids +command differs from +.B tunefs.lustre --writeconf +in that it does not erase the entire configuration log, precluding the need to +"writeconf" all servers and re-specify all permanent parameter settings. +.SH OPTIONS +.TP +.I DEVICE_NAME +Device name there changes applied to. +.TP +.I NODEA_NID1 +Primary node first NID +.TP +.I NODEA_NID2 +Primary node second NID +.TP +.I NODEB_NID1 +Failover node first NID +.TP +.I NODEB_NID2 +Failover node second NID +.SH EXAMPLES +To replace an old NIDs for device lustre-MDT0000 with new one use the following +command: +.EX +.B # lctl replace_nids lustre-MDT0000 192.168.1.112@tcp1,\ + 169.254.161.205@tcp2:192.168.1.113@tcp1,\ + 169.254.161.206@tcp2:192.168.1.114@tcp1,\ + 169.254.161.207@tcp2 +.P +192.168.1.112@tcp1,169.254.161.205@tcp2 - primary NIDs +192.168.1.113@tcp1,169.254.161.206@tcp2 - NIDs of first failover node +192.168.1.114@tcp1,169.254.161.207@tcp2 - NIDs of second failover node +.EE +.SH AVAILABILITY +.B lctl replace_nids +is part of the +.BR lustre (7) +filesystem package since release 2.4.0 +.\" Added in commit v2_3_59_0-6aa30ff835 +.SH SEE ALSO +.BR lustre (7), +.BR lctl (8), +.BR tunefs.lustre (8) diff --git a/lustre/doc/lctl.8 b/lustre/doc/lctl.8 index 15ae282..9f2b6c4 100644 --- a/lustre/doc/lctl.8 +++ b/lustre/doc/lctl.8 @@ -62,19 +62,10 @@ Print all Network Identifiers on the local node. LNET must be running. From a list of nids for a remote node, show which interface communication will take place on. .TP -.BI replace_nids " DEVICENAME NID1"\fR[, NID2 \fR, NID3 : NID4 \fR, NID5 : NID6 \fR...] -Replace the LNET Network Identifiers for a given device, -as when the server's IP address has changed. -This command must be run on the MGS node. -Only MGS server should be started -(command execution returns error in another cases). -To start the MGS service only: -mount -t lustre -o nosvc -Note the replace_nids command skips -any invalidated records in the configuration log. -The previous log is backed up with the suffix '.bak'. -Failover nids must be passed after ':' symbol. -More than one failover can be set (every failover NID after ':' symbol). +.BI replace_nids " DEVICE_NAME NIDS_LIST" +Replace the LNet NIDs. See +.BR lctl-replace_nids (8) +for details. .TP .BI ping " NID TIMEOUT" Check LNET connectivity via an LNET ping. This will use the fabric @@ -444,6 +435,7 @@ filesystem package since release 0.5.0 .BR lctl-nodemap-add-offset (8), .BR lctl-nodemap-del-offset (8), .BR lctl-pcc (8), +.BR lctl-replace-nids (8), .BR lctl-set_param (8), .BR lctl-snapshot-create (8), .BR lctl-snapshot-destroy (8), -- 1.8.3.1