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