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 .TP
 271 \fBlnetctl set\fR max_recovery_ping_interval \fIvalue\fR
 272 Set the maximum recovery ping interval.
 273 The recovery ping mechanism increases the next scheduled recovery ping attempt
 274 timeout exponentially (base 2) until it is equal to the value set.
 275 The default value is 900.
 276 .
 277 .SS "Import and Export YAML Configuration Files"
 278 LNet configuration can be represented in YAML format\. A YAML configuration
 279 file can be passed to the lnetctl utility via the \fBimport\fR command\. The
 280 lnetctl utility will attempt to configure all elements defined in the YAML
 281 file\.
 282 .
 283 .P
 284 Similarly the \fBexport\fR command can be used to dump all supported LNet
 285 configuration to stdout\. The output can be redirected to a file\.
 286 .
 287 .TP
 288 \fBlnetctl import\fR \fIFILE\fR:
 289
 290 .
 291 .TP
 292 \fBlnetctl import\fR < \fIFILE\fR
 293 \fBimport\fR command uses the specified YAML configuration file to configure
 294 LNet parameters defined within\. The import command by default adds the LNet
 295 parameters defined in the YAML file, but this default behavior can be
 296 overwritten by specifying the desired behavior\.
 297 .
 298 .br
 299 \-\-add: add configuration
 300 .
 301 .br
 302 \-\-del: delete configuration
 303 .
 304 .br
 305 \-\-show: show configuration
 306 .
 307 .br
 308 \-\-exec: execute command
 309 .
 310 .br
 311 \-\-help: display this help
 312 .
 313 .TP
 314 \fBlnetctl export\fR \fIFILE\fR:
 315
 316 .
 317 .TP
 318 \fBlnetctl export\fR > \fIFILE\fR
 319 \fBexport\fR command dumps the LNet configuration, state information, and stats
 320 in YAML format to stdout, which can be redirected to a normal file\. The output
 321 of the \fBexport\fR command can be used as input to the \fBimport\fR command\.
 322 .
 323 .br
 324 \-\-backup: dump only elements necessary to recreate the current configuration.
 325 .
 326 .br
 327 \-\-help: display this help
 328 .
 329 .SS "LNet Statistics"
 330 .
 331 .TP
 332 \fBlnetctl stats\fR
 333 Show LNET statistics
 334 .
 335 .br
 336 \-> Number of messages allocated
 337 .
 338 .br
 339 \-> Maximum number of messages allocated
 340 .
 341 .br
 342 \-> Number of errors encountered
 343 .
 344 .br
 345 \-> Number of messages sent
 346 .
 347 .br
 348 \-> Number of messages received
 349 .
 350 .br
 351 \-> Number of messages routed
 352 .
 353 .br
 354 \-> Total size in bytes of messages sent
 355 .
 356 .br
 357 \-> Total size in bytes of messages received
 358 .
 359 .br
 360 \-> Total size in bytes of messages routed
 361 .
 362 .br
 363 \-> Total size in bytes of messages dropped
 364 .
 365 .br
 366
 367 .
 368 .SS "Showing Peer Credits"
 369 .
 370 .TP
 371 \fBlnetctl peer_credits\fR
 372 Show details on configured peer credits
 373 .
 374 .br
 375 \-> Peer nid
 376 .
 377 .br
 378 \-> State
 379 .
 380 .br
 381 \-> Reference count on the peer
 382 .
 383 .br
 384 \-> Maximum transmit credits
 385 .
 386 .br
 387 \-> Available transmit credits
 388 .
 389 .br
 390 \-> Available router credits
 391 .
 392 .br
 393 \-> Minimum router credits\.
 394 .
 395 .SS "UDSP Configuration"
 396 .
 397 .TP
 398 \fBlnetctl udsp\fR add
 399 Add user-defined selection policy.
 400 .
 401 .br
 402 .
 403 .TP
 404 Adding a local network udsp.
 405 .
 406 .br
 407 If multiple local networks are available, each one can be assigned a priority\.
 408 The one with the highest priority is selected to send on\.
 409 NID and network matching is using NID-range syntax, please see the manual for more detail\.
 410 .
 411 .br
 412 \-\-src : network in NID-range syntax (e.g. tcp0 or tcp[1-3])
 413 .
 414 .br
 415 \-\-<priority> <priority value>: optional priority value in [0-255], 0 as the highest
 416 .
 417 .br
 418 \-\-<idx>: The index of where to insert the rule\. By default append to the end of the list
 419 .
 420 .br
 421 .
 422 .TP
 423 Adding a local NID udsp.
 424 .
 425 .br
 426 Assign priority to local NIDs\. After a local network is chosen, the NI with highest priority is selected\.
 427 .
 428 .br
 429 \-\-src: NID in NID-range syntax (e.g. 10.1.1.2@tcp or 10.1.1.*@tcp)
 430 .
 431 .br
 432 \-\-<priority> <priority value>: optional priority value in [0-255], 0 as the highest
 433 .
 434 .br
 435 \-\-<idx>: The index of where to insert the rule\. By default append to the end of the list
 436 .
 437 .br
 438 .
 439 .TP
 440 Adding a peer NID udsp.
 441 .
 442 .br
 443 Assign priority to peer NIDs. Peer NID with highest priority is selected to send to\.
 444 .
 445 .br
 446 \-\-dst: NID in NID-range syntax (e.g. 10.1.1.2@tcp)
 447 .
 448 .br
 449 \-\-<priority> <priority value>: optional priority value in [0-255], 0 as the highest
 450 .
 451 .br
 452 \-\-<idx>: The index of where to insert the rule\. By default append to the end of the list
 453 .
 454 .br
 455 .
 456 .TP
 457 Adding a NID pair udsp.
 458 .
 459 .br
 460 The local NIDs which match the rule are added on a list on the peer NIs matching the rule\.
 461 When selecting the peer NI, the one with the local NID being used on its list is preferred\.
 462 .
 463 .br
 464 \-\-dst: NID in NID-range syntax (e.g. 10.1.1.1@tcp)
 465 .
 466 .br
 467 \-\-src: NID in NID-range syntax (e.g. 10.1.1.2@tcp)
 468 .
 469 .br
 470 \-\-<idx>: The index of where to insert the rule\. By default append to the end of the list
 471 .
 472 .br
 473 .
 474 .TP
 475 Adding a Peer Router udsp.
 476 .
 477 .br
 478 The router NIDs matching the rule are added on a list on the peer NIs matching the rule\.
 479 When sending to a remote peer, the router which has its nid on the peer NI list is preferred\.
 480 .
 481 .br
 482 \-\-dst: peer NID in NID-range syntax (e.g. 10.1.1.1@tcp)
 483 .
 484 .br
 485 \-\-rte: router NID in NID-range syntax (e.g. 10.1.2.1@tcp)
 486 .
 487 .br
 488 \-\-<idx>: The index of where to insert the rule\. By default append to the end of the list
 489 .
 490 .br
 491 .
 492 .TP
 493 \fBlnetctl udsp\fR del
 494 Delete user-defined selection policy.
 495 .
 496 .br
 497 \-\-idx: The index of the rule to delete\.
 498 .
 499 .br
 500 .TP
 501 \fBlnetctl udsp\fR show
 502 Show all user-defined selection policies in the system\. The policies are dumped in YAML form\.
 503 .
 504 .br
 505 .
 506 .SH "OPTIONS"
 507 .TP
 508 .B --list-commands
 509 Output a list of the commands supported by the lnetctl utility
 510 .SH "EXAMPLES"
 511 .
 512 .SS "Initializing LNet after load"
 513 .
 514 .IP "\(bu" 4
 515 lnetctl lnet configure
 516 .
 517 .IP "\(bu" 4
 518 lnetctl lnet configure \-\-all
 519 .
 520 .IP "" 0
 521 .
 522 .SS "Shutting down LNet"
 523 .
 524 .IP "\(bu" 4
 525 lnetctl lnet unconfigure
 526 .
 527 .IP "" 0
 528 .
 529 .SS "Add network"
 530 .
 531 .IP "\(bu" 4
 532 lnetctl net add \-\-net tcp0 \-\-if eth0
 533 .
 534 .IP "\(bu" 4
 535 lnetctl net add \-\-ip2net "tcp0(eth0) 192\.168\.0\.[2,4]; tcp0 192\.168\.0\.*;
 536 o2ib0 132\.6\.[1\-3]\.[2\-8/2]"
 537 .
 538 .IP "" 0
 539 .
 540 .SS "Delete network"
 541 .
 542 .IP "\(bu" 4
 543 lnetctl net del \-\-net tcp0
 544 .
 545 .IP "" 0
 546 .
 547 .SS "Show network"
 548 .
 549 .TP
 550 lnetctl net show \-\-verbose:
 551
 552 .
 553 .P
 554 net:
 555 .
 556 .br
 557         \- nid: 0@lo
 558 .
 559 .br
 560           status: up
 561 .
 562 .br
 563           tunables:
 564 .
 565 .br
 566                 peer_timeout: 0
 567 .
 568 .br
 569                 peer_credits: 0
 570 .
 571 .br
 572                 peer_buffer_credits: 0
 573 .
 574 .br
 575                 credits: 0
 576 .
 577 .br
 578         \- nid: 192\.168\.205\.130@tcp1
 579 .
 580 .br
 581           status: up
 582 .
 583 .br
 584           interfaces:
 585 .
 586 .br
 587                 0: eth3
 588 .
 589 .br
 590                 1: eth4
 591 .
 592 .br
 593           tunables:
 594 .
 595 .br
 596                 peer_timeout: 180
 597 .
 598 .br
 599                 peer_credits: 8
 600 .
 601 .br
 602                 peer_buffer_credits: 0
 603 .
 604 .br
 605                 credits: 256
 606 .
 607 .br
 608 .
 609 .SS "Add route"
 610 .
 611 .IP "\(bu" 4
 612 lnetctl route add \-\-net tcp0 \-\-gateway 10\.10\.10\.1@tcp1 \-\-hop 1
 613 \-\-priority 1
 614 .
 615 .IP "" 0
 616 .
 617 .SS "Delete route"
 618 .
 619 .IP "\(bu" 4
 620 lnetctl route del \-\-net tcp0 \-\-gateway 10\.10\.10\.1@tcp1
 621 .
 622 .IP "" 0
 623 .
 624 .SS "Show route"
 625 .
 626 .IP "\(bu" 4
 627 lnetctl route show \-\-verbose
 628 .
 629 .IP "" 0
 630 .
 631 .P
 632 route:
 633 .
 634 .br
 635         \- net: tcp
 636 .
 637 .br
 638           gateway: 192\.168\.205\.131@tcp1
 639 .
 640 .br
 641           hop: 1
 642 .
 643 .br
 644           priority: 0 state: down
 645 .
 646 .br
 647 .
 648 .SS "Show routing"
 649 .
 650 .IP "\(bu" 4
 651 lnetctl routing show
 652 .
 653 .IP "" 0
 654 .
 655 .P
 656 routing:
 657 .
 658 .br
 659         \- cpt[0]:
 660 .
 661 .br
 662           tiny:
 663 .
 664 .br
 665                 npages: 0
 666 .
 667 .br
 668                 nbuffers: 2048
 669 .
 670 .br
 671                 credits: 2048
 672 .
 673 .br
 674                 mincredits: 2048
 675 .
 676 .br
 677           small:
 678 .
 679 .br
 680                 npages: 1
 681 .
 682 .br
 683                 nbuffers: 16384
 684 .
 685 .br
 686                 credits: 16384
 687 .
 688 .br
 689                 mincredits: 16384
 690 .
 691 .br
 692           large:
 693 .
 694 .br
 695                 npages: 256
 696 .
 697 .br
 698                 nbuffers: 1024
 699 .
 700 .br
 701                 credits: 1024
 702 .
 703 .br
 704                 mincredits: 1024
 705 .
 706 .br
 707         \- enable: 1
 708 .
 709 .SS "Setting variables"
 710 .
 711 .IP "\(bu" 4
 712 lnetctl set tiny_buffers 2048
 713 .
 714 .IP "\(bu" 4
 715 lnetctl set small_buffers 16384
 716 .
 717 .IP "\(bu" 4
 718 lnetctl set large_buffers 256
 719 .
 720 .IP "\(bu" 4
 721 lnetctl set routing 1
 722 .
 723 .IP "" 0
 724 .
 725 .SS "Importing YAML files for configuring"
 726 .
 727 .IP "\(bu" 4
 728 lnetctl import lnet\.conf
 729 .
 730 .IP "\(bu" 4
 731 lnetctl import < lnet\.conf
 732 .
 733 .IP "" 0
 734 .
 735 .SS "Exporting LNet Configuration"
 736 .
 737 .IP "\(bu" 4
 738 lnetctl export lnet\.conf
 739 .
 740 .IP "\(bu" 4
 741 lnetctl export > lnet\.conf
 742 .
 743 .IP "" 0
 744 .
 745 .SS "Showing LNet Stats"
 746 .
 747 .IP "\(bu" 4
 748 lnetctl stats show
 749 .
 750 .IP "" 0
 751 .
 752 .P
 753 statistics:
 754 .
 755 .br
 756         msgs_alloc: 0
 757 .
 758 .br
 759         msgs_max: 1
 760 .
 761 .br
 762         errors: 0
 763 .
 764 .br
 765         send_count: 89
 766 .
 767 .br
 768         recv_count: 0
 769 .
 770 .br
 771         route_count: 0
 772 .
 773 .br
 774         drop_count: 19
 775 .
 776 .br
 777         send_length: 0
 778 .
 779 .br
 780         recv_length: 0
 781 .
 782 .br
 783         route_length: 0
 784 .
 785 .br
 786         drop_length: 0
 787 .
 788 .br
 789 .
 790 .SS "Showing peer information"
 791 .
 792 .IP "\(bu" 4
 793 lnetctl peer show
 794 .
 795 .IP "" 0
 796 .
 797 .P
 798 peer:
 799 .
 800 .br
 801     \- primary nid: 10\.148\.0\.8@o2ib
 802 .
 803 .br
 804       Multi\-Rail: True
 805 .
 806 .br
 807       peer ni:
 808 .
 809 .br
 810         \- nid: 10\.148\.0\.8@o2ib
 811 .
 812 .br
 813           state: NA
 814 .
 815 .br
 816     \- primary nid: 10\.148\.0\.20@o2ib
 817 .
 818 .br
 819       Multi\-Rail: True
 820 .
 821 .br
 822       peer ni:
 823 .
 824 .br
 825         \- nid: 10\.148\.0\.20@o2ib
 826 .
 827 .br
 828           state: NA
 829 .
 830 .br
 831         \- nid: 10\.148\.0\.25@o2ib
 832 .
 833 .br
 834           state: NA
 835 .
 836 .br
 837 .
 838 .SS "Adding a UDSP"
 839 .
 840 .IP "\(bu" 4
 841 lnetctl udsp add \-\-src tcp \-\-priority 1
 842 .
 843 .IP "" 0
 844 .
 845 .P
 846 .
 847 .SS "Deleting a UDSP"
 848 .
 849 .IP "\(bu" 4
 850 lnetctl udsp del \-\-idx 0
 851 .
 852 .IP "" 0
 853 .
 854 .P
 855 .SS "Show UDSPs"
 856 .
 857 .IP "\(bu" 4
 858 lnetctl udsp show
 859 .
 860 .IP "" 0
 861 .
 862 .P
 863 udsp:
 864 .
 865 .br
 866     \- idx: 0
 867 .
 868 .br
 869     src: tcp
 870 .
 871 .br
 872     dst: NA
 873 .
 874 .br
 875     rte: NA
 876 .
 877 .br
 878     action:
 879 .
 880 .br
 881         priority: 0
 882 .
 883 .br
 884
 885 .SH SEE ALSO
 886 .BR lustre (7)
 887