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