LU-8311 doc: add NIDs examples to mkfs.lustre and mount.lustre

This patch adds examples of how NIDs can be specified on
mkfs.lustre and mount command lines.

Test-Parameters: trivial

Signed-off-by: Jian Yu <jian.yu@intel.com>
Change-Id: I93a8f843755582f94844504f604409dd43b617f9
Reviewed-on: http://review.whamcloud.com/23355
Tested-by: Jenkins
Reviewed-by: Andreas Dilger <andreas.dilger@intel.com>
Tested-by: Maloo <hpdd-maloo@intel.com>
Reviewed-by: Zhiqi Tao <zhiqi.tao@intel.com>
Reviewed-by: Oleg Drokin <oleg.drokin@intel.com>

diff --git a/lustre/doc/mkfs.lustre.8 b/lustre/doc/mkfs.lustre.8
index 55b245e..7f2458a 100644 (file)
--- a/lustre/doc/mkfs.lustre.8
+++ b/lustre/doc/mkfs.lustre.8
@@ -160,6 +160,17 @@ Print more information.
 .BI \--version
 Output build version of the mkfs.lustre utiltiy.
 
 .BI \--version
 Output build version of the mkfs.lustre utiltiy.
 

+.SH NID
+A Lustre network identifier (NID) is used to uniquely identify a Lustre network
+endpoint by node ID and network type. The format of the NID is:
+\fInetwork_id@network_type\fR.
+If a node has multiple network interfaces, it may have multiple NIDs, which must
+all be identified so other nodes can choose the NID that is appropriate for
+their network interfaces. Typically, NIDs are specified in a list delimited by
+commas (,). However, when failover nodes are specified, the NIDs are delimited
+by a colon (:) or by repeating a keyword such as \fI--mgsnode=\fR or
+\fI--servicenode=\fR.
+

 .SH EXAMPLES
 .TP
 .B mkfs.lustre --fsname=testfs --index=0 --mdt --mgs /dev/sda1
 .SH EXAMPLES
 .TP
 .B mkfs.lustre --fsname=testfs --index=0 --mdt --mgs /dev/sda1


@@ -168,6 +179,13 @@ Combined MGS and MDT for filesystem 'testfs' on node e.g. cfs21
 .B mkfs.lustre --fsname=testfs --index=0 --ost --mgsnode=cfs21@tcp0 /dev/sdb
 OST for filesystem 'testfs' on any node using the above MGS.
 .TP
 .B mkfs.lustre --fsname=testfs --index=0 --ost --mgsnode=cfs21@tcp0 /dev/sdb
 OST for filesystem 'testfs' on any node using the above MGS.
 .TP

+.B mkfs.lustre --fsname=testfs --index=0 --mdt --mgs --servicenode=cfs21@tcp0,cfs21ib@o2ib0 --servicenode=cfs22@tcp0,cfs22ib@o2ib0 /dev/sda1
+Combined MGS and MDT for filesystem 'testfs' on failover pair cfs21 and cfs22.
+.TP
+.B mkfs.lustre --fsname=testfs --index=0 --ost --mgsnode=cfs21@tcp0,cfs21ib@o2ib0:cfs22@tcp0,cfs22ib@o2ib0 --failnode=cfs24@tcp0,cfs24ib@o2ib0 /dev/sdb
+OST for filesystem 'testfs' using the above MGS and having a failover partner
+cfs24.
+.TP

 .B mkfs.lustre --mgs /dev/sda1
 Standalone MGS on e.g. node cfs22
 .TP
 .B mkfs.lustre --mgs /dev/sda1
 Standalone MGS on e.g. node cfs22
 .TP

diff --git a/lustre/doc/mount.lustre.8 b/lustre/doc/mount.lustre.8
index db88cd6..a31adcc 100644 (file)
--- a/lustre/doc/mount.lustre.8
+++ b/lustre/doc/mount.lustre.8
@@ -157,11 +157,19 @@ maximum of 'timeout' seconds.  The default hard recovery timeout is set to
 .B mount -t lustre cfs21@tcp0:/testfs /mnt/myfilesystem
 Start a client for the Lustre filesystem 'testfs' at the mount point
 /mnt/myfilesystem. The Management Service is running on a node reachable
 .B mount -t lustre cfs21@tcp0:/testfs /mnt/myfilesystem
 Start a client for the Lustre filesystem 'testfs' at the mount point
 /mnt/myfilesystem. The Management Service is running on a node reachable

-from this client via the nid cfs21@tcp0.
+from this client via the NID cfs21@tcp0.

 .TP
 .B mount -t lustre cfs21@tcp0:/testfs/dir /mnt/myfilesystem
 Like above example, but mount subdirectory 'dir' as fileset.
 .TP
 .TP
 .B mount -t lustre cfs21@tcp0:/testfs/dir /mnt/myfilesystem
 Like above example, but mount subdirectory 'dir' as fileset.
 .TP

+.B mount -t lustre cfs21@tcp0,cfs21ib@o2ib0:cfs22@tcp0,cfs22ib@o2ib0:/testfs/dir /mnt/myfilesystem
+Like above example, but the Management Service is running on one of the service
+nodes cfs21 and cfs22, which are two different hosts separated by a colon and
+served as a failover pair. Lustre tries the first one, and if that fails, it
+tries the second one. On each service node, the comma-separated NIDs refer to
+different interfaces on the same host, and the Lustre client chooses the best
+one for communication based on which network interfaces it has locally.
+.TP

 .B mount -t lustre /dev/sda1 /mnt/test/mdt
 Start the Lustre metadata target service from /dev/sda1 on mountpoint /mnt/test/mdt.
 .TP
 .B mount -t lustre /dev/sda1 /mnt/test/mdt
 Start the Lustre metadata target service from /dev/sda1 on mountpoint /mnt/test/mdt.
 .TP