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