Whamcloud - gitweb
0d1b7121dacaa392d1c16c9e155ef764f1596f4f
[fs/lustre-release.git] / lustre / doc / lnetctl.8
1 .
2 .TH lnetctl 8 "2017 Jan 12" Lustre "configuration utilities"
3 .
4 .SH "SYNOPSIS"
5 \fBlnetctl\fR
6 .
7 .br
8 .B lnetctl --list-commands
9 .br
10 \fBlnetctl\fR \fB<cmd> <subcmd> [optional parameters]\fR
11 .
12 .br
13 .SH "DESCRIPTION"
14 \fBlnetctl\fR is used to configure LNet parameters allowing various configuration
15 and debugging features to be accessed\.
16 .
17 .P
18 \fBlnetctl\fR can be invoked in interactive mode by issuing lnetctl command\.
19 After that, commands are issued as below\.
20 .
21 .P
22 To get a complete listing of available commands, type
23 .B --list-commands
24 at the lnetctl prompt\. To get basic help on the meaning and syntax of a command
25 type \fB<command>\fR \-\-help\.
26 .
27 .P
28 For non\-interactive use the \fBlnetctl\fR utility can be invoked from the
29 command line as follows:
30 .
31 .P
32 lnetctl \fIcommand\fR \fIsubcommand\fR [optional parameters]
33 .
34 .SS "LNet Initialization:"
35 .
36 .TP
37 \fBlnetctl lnet\fR configure [\-\-all]
38 Brings up the LNet Network Interface (NI) system\. If the \-\-all option is
39 provided it will load network interfaces defined in the modprobe files\.
40 Otherwise, it doesn\'t initialize any networks by default\.
41 .
42 .TP
43 \fBlnetctl lnet\fR unconfigure
44 Brings down the LNet Network Interface (NI) system including any configured
45 networks\.
46 .
47 .SS "Network Configuration"
48 .
49 .TP
50 \fBlnetctl net\fR add
51 Configures a network interface either given the network name and physical
52 interface device name, or given the ip2net parameter\. Other parameters
53 are optional\.
54 .
55 .br
56 \-\-net: net name (e.g. tcp0)
57 .
58 .br
59 \-\-if: physical interface (e.g. eth0)
60 .
61 .br
62 \-\-ip2net: specify networks based on IP address patterns
63 .
64 .br
65 \-\-peer\-timeout: time to wait before declaring a peer dead (in seconds).
66 Default value for o2iblnd and socklnd is 180 seconds.
67 .
68 .br
69 \-\-peer\-credits: define the max number of in\-flight messages per peer.
70 .
71 .br
72 \-\-peer\-buffer\-credits: the max number of routed in\-flight messages
73 per peer.
74 .
75 .br
76 \-\-credits: The total number of in\-flight messages over a network interface.
77 .
78 .br
79 \-\-cpt: The CPU partitions on which the created network interface is bound to.
80 Refer to the Lustre Manual Section "Binding Network Interface Against CPU
81 Partitions" for more details. For example to bind a Network Interface to
82 CPU partitions 0 and 1, you would specify this parameter as \-\-cpt [0,
83 1]
84 .
85 .br
86
87 .
88 .TP
89 \fBlnetctl net\fR del
90 Delete a network interface given the network name\.
91 .
92 .br
93 \-\-net: net name (e.g. tcp0)
94 .
95 .br
96
97 .
98 .TP
99 \fBlnetctl net\fR show
100 Show all currently configured network interfaces if no parameters given or filter
101 on the network name\. More details can be shown by specifying the \-\-verbose
102 parameter\.
103 .
104 .br
105 \-\-net: net name (e.g. tcp0) to filter on
106 .
107 .br
108 \-\-verbose: display detailed output per network
109
110 .
111 .SS "Peer Configuration"
112 .TP
113 \fBlnetctl peer\fR add
114 Configure an LNET peer with at least one supplied NID\.  The primary NID must be specified.  By default, peers are marked as multi-rail capable\.
115 .
116 .br
117 .
118 \-\-nid: one or more peer NIDs to add to the peer\.
119 .
120 .br
121 .
122 \-\-prim_nid: Primary NID of the peer\.
123 .
124 .br
125 \-\-non_mr: create this peer as not Multi-Rail capable\.
126 .
127 .br
128 \-\-lock_prim: lock primary NID of the peer for the purpose of identification with Lustre\.
129 .
130 .br
131
132 .TP
133 \fBlnetctl peer\fR del
134 Delete a peer NID.  The primary NID must be specified.  If the removed NID is the primary NID, the peer entry will be deleted.
135 .
136 .br
137 .
138 \-\-nid: one or more peer NIDs to remove from the peer\.
139 .
140 .br
141 .
142 \-\-prim_nid: Primary NID of the peer\.
143 .
144 .br
145 \-\-force: optional, use to delete a peer with primary NID locked\.
146 .
147 .br
148
149 .TP
150 \fBlnetctl peer\fR show
151 Show configured peers.  By default, lists all peers and associated NIDs.
152 .
153 .br
154 .
155 \-\-nid: list of primary nids to filter on
156 .
157 .br
158 .
159 \-\-verbose: Include extended statistics, including credits and counters.
160 .
161 .br
162
163 .
164 .SS "Route Configuration"
165 .
166 .TP
167 \fBlnetctl route\fR add
168 Add a route\.
169 .
170 .br
171 \-\-net: net name (e.g. tcp0)
172 .
173 .br
174 \-\-gateway: gateway nid (e.g. 10\.1\.1\.2@tcp)
175 .
176 .br
177 \-\-hop: number to final destination (1 < hops < 255)
178 .
179 .br
180 \-\-priority: priority of route (0 \- highest prio)
181 .
182 .br
183
184 .
185 .TP
186 \fBlnetctl route\fR del
187 Delete a route specified via the network and gateway\.
188 .
189 .br
190 \-\-net: net name (e.g. tcp0)
191 .
192 .br
193 \-\-gateway: gateway nid (e.g. 10\.1\.1\.2@tcp)
194 .
195 .br
196
197 .
198 .TP
199 \fBlnetctl route\fR show
200 Show all currently configured routes if no parameters given, or filter on
201 given parameters\. More details can be shown by specifying the \-\-verbose
202 parameter\.
203 .
204 .br
205 \-\-net: net name (e.g. tcp0) to filter on
206 .
207 .br
208 \-\-gateway: gateway nid (e.g. 10\.1\.1\.2@tcp) to filter on
209 .
210 .br
211 \-\-hop: number to final destination (1 < hops < 255) to filter on
212 .
213 .br
214 \-\-priority: priority of route (0 \- highest prio to filter on)
215 .
216 .br
217 \-\-verbose: display detailed output per route
218 .
219 .br
220
221 .
222 .SS "Routing Information"
223 .
224 .TP
225 \fBlnetctl routing\fR show
226 Show router buffers values as well as show the status of routing (IE: whether
227 the node is set to be a router)
228 .
229 .SS "Value Setting"
230 Individual values can be set using the \fBlnetctl set\fR command\.
231 .
232 .TP
233 \fBlnetctl set\fR tiny_buffers \fIvalue\fR
234 Set the number of tiny buffers in the system\. This is the total number of tiny
235 buffers for all CPU partitions\.
236 .
237 .TP
238 \fBlnetctl set\fR small_buffers \fIvalue\fR
239 Set the number of small buffers in the system\. This is the total number of
240 small buffers for all CPU partitions\.
241 .
242 .TP
243 \fBlnetctl set\fR large_buffers \fIvalue\fR
244 Set the number of large buffers in the system\. This is the total number of
245 large buffers for all CPU partitions\.
246 .
247 .TP
248 \fBlnetctl set\fR routing \fI[0, 1]\fR
249 0 value indicates to disable routing\. 1 value indicates to enable routing\.
250 When routing is disabled the values of the buffers that might have been changed
251 are not remembered, and the next time routing is enabled the default buffer
252 count will be used\.
253 .
254 .TP
255 \fBlnetctl set\fR drop_asym_route \fI[0, 1]\fR
256 0 value indicates to accept asymmetrical route messages\. 1 value indicates to
257 drop them\. Asymmetrical route is when a message from a remote peer is coming
258 through a router that would not be used by this node to reach the remote peer\.
259 .
260 .TP
261 \fBlnetctl set\fR response_tracking \fI[0, 1, 2, 3]\fR
262 Set the behavior of response tracking\.
263   0 - Only LNet pings and discovery pushes utilize response tracking\.
264   1 - GETs are eligible for response tracking\.
265   2 - PUTs are eligible for response tracking\.
266   3 - Both PUTs and GETs are eligible for response tracking (default)\.
267   Note: Regardless of the value of the response_tracking parameter LNet
268         pings and discovery pushes always utilize response tracking\.
269 .
270 .TP
271 \fBlnetctl set\fR recovery_limit \fIvalue\fR
272 Set how long LNet will attempt to recover unhealthy peer interfaces\.
273   0 - Recover indefinitely (default)\.
274   >0 - Recover for the specified number of seconds\.
275 .
276 .TP
277 \fBlnetctl set\fR max_recovery_ping_interval \fIvalue\fR
278 Set the maximum recovery ping interval.
279 The recovery ping mechanism increases the next scheduled recovery ping attempt
280 timeout exponentially (base 2) until it is equal to the value set.
281 The default value is 900.
282 .
283 .SS "Import and Export YAML Configuration Files"
284 LNet configuration can be represented in YAML format\. A YAML configuration
285 file can be passed to the lnetctl utility via the \fBimport\fR command\. The
286 lnetctl utility will attempt to configure all elements defined in the YAML
287 file\.
288 .
289 .P
290 Similarly the \fBexport\fR command can be used to dump all supported LNet
291 configuration to stdout\. The output can be redirected to a file\.
292 .
293 .TP
294 \fBlnetctl import\fR \fIFILE\fR:
295
296 .
297 .TP
298 \fBlnetctl import\fR < \fIFILE\fR
299 \fBimport\fR command uses the specified YAML configuration file to configure
300 LNet parameters defined within\. The import command by default adds the LNet
301 parameters defined in the YAML file, but this default behavior can be
302 overwritten by specifying the desired behavior\.
303 .
304 .br
305 \-\-add: add configuration
306 .
307 .br
308 \-\-del: delete configuration
309 .
310 .br
311 \-\-show: show configuration
312 .
313 .br
314 \-\-exec: execute command
315 .
316 .br
317 \-\-help: display this help
318 .
319 .TP
320 \fBlnetctl export\fR \fIFILE\fR:
321
322 .
323 .TP
324 \fBlnetctl export\fR > \fIFILE\fR
325 \fBexport\fR command dumps the LNet configuration, state information, and stats
326 in YAML format to stdout, which can be redirected to a normal file\. The output
327 of the \fBexport\fR command can be used as input to the \fBimport\fR command\.
328 .
329 .br
330 \-\-backup: dump only elements necessary to recreate the current configuration.
331 .
332 .br
333 \-\-help: display this help
334 .
335 .SS "LNet Statistics"
336 .
337 .TP
338 \fBlnetctl stats\fR show
339 Show LNET statistics
340 .
341 .br
342 \-> Number of messages allocated
343 .
344 .br
345 \-> Maximum number of messages allocated
346 .
347 .br
348 \-> Number of errors encountered
349 .
350 .br
351 \-> Number of messages sent
352 .
353 .br
354 \-> Number of messages received
355 .
356 .br
357 \-> Number of messages routed
358 .
359 .br
360 \-> Total size in bytes of messages sent
361 .
362 .br
363 \-> Total size in bytes of messages received
364 .
365 .br
366 \-> Total size in bytes of messages routed
367 .
368 .br
369 \-> Total size in bytes of messages dropped
370 .
371 .br
372
373 .
374 .SS "Showing Peer Credits"
375 .
376 .TP
377 \fBlnetctl peer_credits\fR
378 Show details on configured peer credits
379 .
380 .br
381 \-> Peer nid
382 .
383 .br
384 \-> State
385 .
386 .br
387 \-> Reference count on the peer
388 .
389 .br
390 \-> Maximum transmit credits
391 .
392 .br
393 \-> Available transmit credits
394 .
395 .br
396 \-> Available router credits
397 .
398 .br
399 \-> Minimum router credits\.
400 .
401 .SS "UDSP Configuration"
402 .
403 .TP
404 \fBlnetctl udsp\fR add
405 Add user-defined selection policy.
406 .
407 .br
408 .
409 .TP
410 Adding a local network udsp.
411 .
412 .br
413 If multiple local networks are available, each one can be assigned a priority\.
414 The one with the highest priority is selected to send on\.
415 NID and network matching is using NID-range syntax, please see the manual for more detail\.
416 .
417 .br
418 \-\-src : network in NID-range syntax (e.g. tcp0 or tcp[1-3])
419 .
420 .br
421 \-\-<priority> <priority value>: optional priority value in [0-255], 0 as the highest
422 .
423 .br
424 \-\-<idx>: The index of where to insert the rule\. By default append to the end of the list
425 .
426 .br
427 .
428 .TP
429 Adding a local NID udsp.
430 .
431 .br
432 Assign priority to local NIDs\. After a local network is chosen, the NI with highest priority is selected\.
433 .
434 .br
435 \-\-src: NID in NID-range syntax (e.g. 10.1.1.2@tcp or 10.1.1.*@tcp)
436 .
437 .br
438 \-\-<priority> <priority value>: optional priority value in [0-255], 0 as the highest
439 .
440 .br
441 \-\-<idx>: The index of where to insert the rule\. By default append to the end of the list
442 .
443 .br
444 .
445 .TP
446 Adding a peer NID udsp.
447 .
448 .br
449 Assign priority to peer NIDs. Peer NID with highest priority is selected to send to\.
450 .
451 .br
452 \-\-dst: NID in NID-range syntax (e.g. 10.1.1.2@tcp)
453 .
454 .br
455 \-\-<priority> <priority value>: optional priority value in [0-255], 0 as the highest
456 .
457 .br
458 \-\-<idx>: The index of where to insert the rule\. By default append to the end of the list
459 .
460 .br
461 .
462 .TP
463 Adding a NID pair udsp.
464 .
465 .br
466 The local NIDs which match the rule are added on a list on the peer NIs matching the rule\.
467 When selecting the peer NI, the one with the local NID being used on its list is preferred\.
468 .
469 .br
470 \-\-dst: NID in NID-range syntax (e.g. 10.1.1.1@tcp)
471 .
472 .br
473 \-\-src: NID in NID-range syntax (e.g. 10.1.1.2@tcp)
474 .
475 .br
476 \-\-<idx>: The index of where to insert the rule\. By default append to the end of the list
477 .
478 .br
479 .
480 .TP
481 Adding a Peer Router udsp.
482 .
483 .br
484 The router NIDs matching the rule are added on a list on the peer NIs matching the rule\.
485 When sending to a remote peer, the router which has its nid on the peer NI list is preferred\.
486 .
487 .br
488 \-\-dst: peer NID in NID-range syntax (e.g. 10.1.1.1@tcp)
489 .
490 .br
491 \-\-rte: router NID in NID-range syntax (e.g. 10.1.2.1@tcp)
492 .
493 .br
494 \-\-<idx>: The index of where to insert the rule\. By default append to the end of the list
495 .
496 .br
497 .
498 .TP
499 \fBlnetctl udsp\fR del
500 Delete user-defined selection policy.
501 .
502 .br
503 \-\-idx: The index of the rule to delete\.
504 .
505 .br
506 .TP
507 \fBlnetctl udsp\fR show
508 Show all user-defined selection policies in the system\. The policies are dumped in YAML form\.
509 .
510 .SS "Debugging"
511 .
512 .TP
513 \fBlnetctl debug\fR recovery
514 List NIDs on recovery queue
515 .
516 .br
517 \-\-local : list NIDs on local recovery queue
518 .
519 .br
520 \-\-peer : list NIDs on peer recovery queue
521 .
522 .br
523 .
524 .TP
525 \fBlnetctl debug\fR peer
526 Dump peer debug info to debug log and console
527 .
528 .br
529 \-\-nid : peer's NID
530 .
531 .br
532 .
533 .SH "OPTIONS"
534 .TP
535 .B --list-commands
536 Output a list of the commands supported by the lnetctl utility
537 .SH "EXAMPLES"
538 .
539 .SS "Initializing LNet after load"
540 .
541 .IP "\(bu" 4
542 lnetctl lnet configure
543 .
544 .IP "\(bu" 4
545 lnetctl lnet configure \-\-all
546 .
547 .IP "" 0
548 .
549 .SS "Shutting down LNet"
550 .
551 .IP "\(bu" 4
552 lnetctl lnet unconfigure
553 .
554 .IP "" 0
555 .
556 .SS "Add network"
557 .
558 .IP "\(bu" 4
559 lnetctl net add \-\-net tcp0 \-\-if eth0
560 .
561 .IP "\(bu" 4
562 lnetctl net add \-\-ip2net "tcp0(eth0) 192\.168\.0\.[2,4]; tcp0 192\.168\.0\.*;
563 o2ib0 132\.6\.[1\-3]\.[2\-8/2]"
564 .
565 .IP "" 0
566 .
567 .SS "Delete network"
568 .
569 .IP "\(bu" 4
570 lnetctl net del \-\-net tcp0
571 .
572 .IP "" 0
573 .
574 .SS "Show network"
575 .
576 .TP
577 lnetctl net show \-\-verbose:
578
579 .
580 .P
581 net:
582 .
583 .br
584         \- nid: 0@lo
585 .
586 .br
587           status: up
588 .
589 .br
590           tunables:
591 .
592 .br
593                 peer_timeout: 0
594 .
595 .br
596                 peer_credits: 0
597 .
598 .br
599                 peer_buffer_credits: 0
600 .
601 .br
602                 credits: 0
603 .
604 .br
605         \- nid: 192\.168\.205\.130@tcp1
606 .
607 .br
608           status: up
609 .
610 .br
611           interfaces:
612 .
613 .br
614                 0: eth3
615 .
616 .br
617                 1: eth4
618 .
619 .br
620           tunables:
621 .
622 .br
623                 peer_timeout: 180
624 .
625 .br
626                 peer_credits: 8
627 .
628 .br
629                 peer_buffer_credits: 0
630 .
631 .br
632                 credits: 256
633 .
634 .br
635 .
636 .SS "Add route"
637 .
638 .IP "\(bu" 4
639 lnetctl route add \-\-net tcp0 \-\-gateway 10\.10\.10\.1@tcp1 \-\-hop 1
640 \-\-priority 1
641 .
642 .IP "" 0
643 .
644 .SS "Delete route"
645 .
646 .IP "\(bu" 4
647 lnetctl route del \-\-net tcp0 \-\-gateway 10\.10\.10\.1@tcp1
648 .
649 .IP "" 0
650 .
651 .SS "Show route"
652 .
653 .IP "\(bu" 4
654 lnetctl route show \-\-verbose
655 .
656 .IP "" 0
657 .
658 .P
659 route:
660 .
661 .br
662         \- net: tcp
663 .
664 .br
665           gateway: 192\.168\.205\.131@tcp1
666 .
667 .br
668           hop: 1
669 .
670 .br
671           priority: 0 state: down
672 .
673 .br
674 .
675 .SS "Show routing"
676 .
677 .IP "\(bu" 4
678 lnetctl routing show
679 .
680 .IP "" 0
681 .
682 .P
683 routing:
684 .
685 .br
686         \- cpt[0]:
687 .
688 .br
689           tiny:
690 .
691 .br
692                 npages: 0
693 .
694 .br
695                 nbuffers: 2048
696 .
697 .br
698                 credits: 2048
699 .
700 .br
701                 mincredits: 2048
702 .
703 .br
704           small:
705 .
706 .br
707                 npages: 1
708 .
709 .br
710                 nbuffers: 16384
711 .
712 .br
713                 credits: 16384
714 .
715 .br
716                 mincredits: 16384
717 .
718 .br
719           large:
720 .
721 .br
722                 npages: 256
723 .
724 .br
725                 nbuffers: 1024
726 .
727 .br
728                 credits: 1024
729 .
730 .br
731                 mincredits: 1024
732 .
733 .br
734         \- enable: 1
735 .
736 .SS "Setting variables"
737 .
738 .IP "\(bu" 4
739 lnetctl set tiny_buffers 2048
740 .
741 .IP "\(bu" 4
742 lnetctl set small_buffers 16384
743 .
744 .IP "\(bu" 4
745 lnetctl set large_buffers 256
746 .
747 .IP "\(bu" 4
748 lnetctl set routing 1
749 .
750 .IP "" 0
751 .
752 .SS "Importing YAML files for configuring"
753 .
754 .IP "\(bu" 4
755 lnetctl import lnet\.conf
756 .
757 .IP "\(bu" 4
758 lnetctl import < lnet\.conf
759 .
760 .IP "" 0
761 .
762 .SS "Exporting LNet Configuration"
763 .
764 .IP "\(bu" 4
765 lnetctl export lnet\.conf
766 .
767 .IP "\(bu" 4
768 lnetctl export > lnet\.conf
769 .
770 .IP "" 0
771 .
772 .SS "Showing LNet Stats"
773 .
774 .IP "\(bu" 4
775 lnetctl stats show
776 .
777 .IP "" 0
778 .
779 .P
780 statistics:
781 .
782 .br
783         msgs_alloc: 0
784 .
785 .br
786         msgs_max: 1
787 .
788 .br
789         errors: 0
790 .
791 .br
792         send_count: 89
793 .
794 .br
795         recv_count: 0
796 .
797 .br
798         route_count: 0
799 .
800 .br
801         drop_count: 19
802 .
803 .br
804         send_length: 0
805 .
806 .br
807         recv_length: 0
808 .
809 .br
810         route_length: 0
811 .
812 .br
813         drop_length: 0
814 .
815 .br
816 .
817 .SS "Showing peer information"
818 .
819 .IP "\(bu" 4
820 lnetctl peer show
821 .
822 .IP "" 0
823 .
824 .P
825 peer:
826 .
827 .br
828     \- primary nid: 10\.148\.0\.8@o2ib
829 .
830 .br
831       Multi\-Rail: True
832 .
833 .br
834       peer ni:
835 .
836 .br
837         \- nid: 10\.148\.0\.8@o2ib
838 .
839 .br
840           state: NA
841 .
842 .br
843     \- primary nid: 10\.148\.0\.20@o2ib
844 .
845 .br
846       Multi\-Rail: True
847 .
848 .br
849       peer ni:
850 .
851 .br
852         \- nid: 10\.148\.0\.20@o2ib
853 .
854 .br
855           state: NA
856 .
857 .br
858         \- nid: 10\.148\.0\.25@o2ib
859 .
860 .br
861           state: NA
862 .
863 .br
864 .
865 .SS "Adding a UDSP"
866 .
867 .IP "\(bu" 4
868 lnetctl udsp add \-\-src tcp \-\-priority 1
869 .
870 .IP "" 0
871 .
872 .P
873 .
874 .SS "Deleting a UDSP"
875 .
876 .IP "\(bu" 4
877 lnetctl udsp del \-\-idx 0
878 .
879 .IP "" 0
880 .
881 .P
882 .SS "Show UDSPs"
883 .
884 .IP "\(bu" 4
885 lnetctl udsp show
886 .
887 .IP "" 0
888 .
889 .P
890 udsp:
891 .
892 .br
893     \- idx: 0
894 .
895 .br
896     src: tcp
897 .
898 .br
899     dst: NA
900 .
901 .br
902     rte: NA
903 .
904 .br
905     action:
906 .
907 .br
908         priority: 0
909 .
910 .br
911
912 .SH SEE ALSO
913 .BR lustre (7)
914