Nlb

Applies To: Windows Server 2003, Windows Server 2003 R2, Windows Server 2003 with SP1, Windows Server 2003 with SP2

Nlb

After you have installed and configured Network Load Balancing, you can control its operations and modify parameter settings using the Network Load Balancing control program, nlb.exe, that is installed in the systemroot\System32 folder. To simplify and centralize system administration, you can run nlb.exe either on the cluster hosts or on any remote computer running a member of the Windows Server 2003 family that can access the cluster over a local or wide area network. However, certain actions, such as modifying parameters, can be performed only on the cluster hosts.

In order to run nlb.exe from a remote computer, remote control must be enabled. The Network Load Balancing remote control option presents many security risks, including the possibility of data tampering, denial of service and information disclosure. You should only use remote control on a secure computer within your firewall. Because of the many security risks remote control presents, it is strongly recommended that you do not enable the remote control feature and instead use other remote management tools such as Network Load Balancing Manager or Windows Management Instrumentation (WMI).

If you choose to enable remote control it is vital that you restrict access by specifying a strong remote control password. It is recommended that you use a firewall to protect the Network Load Balancing UDP control ports (the ports receiving remote control commands) in order to shield them from outside intrusion. By default, these are ports 1717 and 2504 at the cluster IP address. For more information about strong passwords, see Strong passwords.

Because it is a shell-based program, nlb.exe program can be incorporated into administrative scripts.

Syntax

nlb Command [Remote Options][/h]

Parameters

  • Command
    Specifies the Network Load Balancing action to perform. The following table lists the possible values.
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<thead>
<tr class="header">
<th>Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><p><strong>help</strong></p></td>
<td><p>Displays the online Help.</p></td>
</tr>
<tr class="even">
<td><p><strong>suspend</strong> [{<em>Cluster</em>[<strong>:</strong><em>Host</em>] | <strong>all</strong> {<strong>local</strong> | <strong>global</strong>}}]</p></td>
<td><p>Suspends all cluster operations until the resume command is issued. Suspend temporarily stops cluster operations if they were previously started. The purpose of this command is to override any remote control commands that might be issued. All subsequent cluster-control commands except resume and query are ignored. The optional parameters allow the command to address a specific cluster, a specific cluster on a specific host, all clusters on the local computer, or all global computers that are part of the cluster.</p></td>
</tr>
<tr class="odd">
<td><p><strong>resume</strong> [{<em>Cluster</em>[<strong>:</strong><em>Host</em>] | <strong>all</strong> {<strong>local</strong> | <strong>global</strong>}}]</p></td>
<td><p>Resumes cluster operations after a previous suspend command. This does not restart cluster operations, but enables use of cluster-control commands, including remote control commands. The optional parameters allow the command to address a specific cluster, a specific cluster on a specific host, all clusters on the local computer, or all global computers that are part of the cluster.</p></td>
</tr>
<tr class="even">
<td><p><strong>start</strong> [{<em>Cluster</em>[<strong>:</strong><em>Host</em>] | <strong>all</strong> {<strong>local</strong> | <strong>global</strong>}}]</p></td>
<td><p>Starts cluster operations on the specified hosts. This enables all ports that might have been previously disabled. The optional parameters allow the command to address a specific cluster, a specific cluster on a specific host, all clusters on the local computer, or all global computers that are part of the cluster.</p></td>
</tr>
<tr class="odd">
<td><p><strong>stop</strong> [{<em>Cluster</em>[<strong>:</strong><em>Host</em>] | <strong>all</strong> {<strong>local</strong> | <strong>global</strong>}}]</p></td>
<td><p>Stops cluster operations on the specified hosts. The optional parameters allow the command to address a specific cluster, a specific cluster on a specific host, all clusters on the local computer, or all global computers that are part of the cluster.</p></td>
</tr>
<tr class="even">
<td><p><strong>drainstop</strong> [{<em>Cluster</em>[<strong>:</strong><em>Host</em>] | <strong>all</strong> {<strong>local</strong> | <strong>global</strong>}}]</p></td>
<td><p>Disables all new traffic handling on the specified hosts. While draining, hosts continue to service opened connections and stop their cluster operations when there are no more active connections. Draining mode can be terminated by explicitly stopping cluster mode with the stop command or by restarting new traffic handling with the start command. The optional parameters allow the command to address a specific cluster, a specific cluster on a specific host, all clusters on the local computer, or all global computers that are part of the cluster.</p></td>
</tr>
<tr class="odd">
<td><p><strong>enable</strong> {<em>vip</em>[{<strong>:</strong><em>Port</em> | <strong>:all</strong>}] | <strong>all</strong>[{<strong>:</strong><em>Port</em> | <strong>:all</strong>}]} {<em>Cluster</em>[<strong>:</strong>{<em>Host</em>]| <strong>all</strong> {<strong>local</strong> | <strong>global</strong>}}}</p></td>
<td><p>Enables traffic handling for the rule whose port range contains the specified port. The first set of optional parameters allow the command to address every virtual IP address (vip), or specific vips on a specific port rule or on all ports. The second set of optional parameters allow the command to address a specific cluster, a specific cluster on a specific host, all clusters on the local computer, or all global computers that are part of the cluster. All ports specified by the port rule are affected. If all is specified for the port, this command is applied to the ports covered by all port rules. This command has no effect if the specified hosts have not started cluster operations.</p></td>
</tr>
<tr class="even">
<td><p><strong>disable</strong> {<em>vip</em>[{<strong>:</strong><em>Port</em> | <strong>:all</strong>}] | <strong>all</strong>[{<strong>:</strong><em>Port</em> | <strong>:all</strong>}]} {<em>Cluster</em>[<strong>:</strong>{<em>Host</em>]| <strong>all</strong> {<strong>local</strong> | <strong>global</strong>}}}</p></td>
<td><p>Disables and immediately blocks all traffic handling for the rule whose port range contains the specified port. The first set of optional parameters allow the command to address every virtual IP address (vip), or specific vips on a specific port rule or on all ports. The second set of optional parameters allow the command to address a specific cluster, a specific cluster on a specific host, all clusters on the local computer, or all global computers that are part of the cluster. All ports specified by the port rule are affected. If all is specified for the port, this command is applied to the ports covered by all port rules. All active connections on the specified hosts are blocked. To maintain active connections, use the drain function instead. This has no effect if the specified hosts have not started cluster operations.</p></td>
</tr>
<tr class="odd">
<td><p><strong>drain</strong> {<em>vip</em>[{<strong>:</strong><em>Port</em> | <strong>:all</strong>}] | <strong>all</strong>[{<strong>:</strong><em>Port</em> | <strong>:all</strong>}]} {<em>Cluster</em>[<strong>:</strong>{<em>Host</em>]| <strong>all</strong> {<strong>local</strong> | <strong>global</strong>}}}</p></td>
<td><p>Disables new traffic handling for the rule whose port range contains the specified port. The first set of optional parameters allow the command to address every virtual IP address (vip), or specific vips on a specific port rule or on all ports. The second set of optional parameters allow the command to address a specific cluster, a specific cluster on a specific host, all clusters on the local computer, or all global computers that are part of the cluster. All ports specified by the port rule are affected. If all is specified for the port, this command is applied to the ports covered by all port rules. New connections to the specified hosts are not allowed, but all active connections are maintained. To disable active connections, use the disable command instead. This command has no effect if the specified hosts have not started cluster operations.</p></td>
</tr>
<tr class="even">
<td><p><strong>query</strong> [{<em>Cluster</em>[<strong>:</strong><em>Host</em>]| <strong>all</strong> {<strong>local</strong> | <strong>global</strong>}}]</p></td>
<td><p>Displays the current cluster state and the list of host priorities for the current members of the cluster. The possible states are: Unknown. The responding host has not started cluster operations and cannot determine the cluster's state. Converging. The cluster is currently attempting to converge to a consistent state. Prolonged convergence usually indicates a problem with cluster parameters. If this occurs, check the event logs on the cluster hosts for Network Load Balancing messages warning you about the source of the problem. Draining. The cluster has converged, and the responding host is draining active connections in response to a drainstop command. Converged as default. The cluster has converged, and the responding host is the current default (the highest priority host without a drainstop command in progress). The default host handles network traffic for all of the TCP/UDP ports not covered by the port rules. Converged. The cluster has converged, and the responding host is not the default host.</p>
<p>The optional parameters allow the command to address a specific cluster, a specific cluster on a specific host, all clusters on the local computer, or all global computers that are part of the cluster.</p></td>
</tr>
<tr class="odd">
<td><p><strong>queryport</strong> [{<em>vip</em>:]<em>Port</em> [<em>Cluster</em>[<strong>:</strong><em>Host</em>] | <strong>all</strong> [{<strong>local</strong> | <strong>global</strong>}]}]</p></td>
<td><p>Displays information about a given port rule. The first parameter specifies which port rule to query. Specify the port rule by using a port number that is within the range of the port rule that you want to query. If necessary, you can also specify a virtual IP address (VIP). The default is all VIPs. However, if a particular port rule is assigned to only a specific VIP (as opposed to all VIPs) you must specify the appropriate VIP in order for the port rule to be found by this command.</p>
<p>The second set of optional parameters allow the command to address a specific cluster, a specific cluster on a specific host, all clusters on the local computer, or all global computers that are part of the cluster.</p>
<p>The information returned includes:</p>
<ul>
<li>Information regarding if the port rule was found or an indication that the port rule was not found<br />
<br />
</li>
<li>The state of the port rule (Enabled, Disabled or Draining)<br />
<br />
</li>
<li>A count of packets accepted and dropped on that port rule. These counters are reset each time the cluster reconverges. For example, if you add a host to the cluster, you should see the counters reset on all hosts in the cluster. These counters can be used as a very coarse method of calculating load balance. For example, if a particular host has accepted 5000 packets and has dropped about 10000 packets, then that host is handling approximately 33% of the load for this port rule. Be aware that these numbers are dependent on a variety of factors and should only be used as a very rough estimate of actual load weight.<br />
<br />
</li>
</ul></td>
</tr>
<tr class="even">
<td><p><strong>reload</strong> [{<em>Cluster</em> | <strong>all</strong>}] (local only)</p></td>
<td><p>Reloads the Network Load Balancing driver's current parameters from the registry. Cluster operations on the local host are automatically stopped and restarted if necessary. If an error exists in the parameters, the host will not join the cluster, and a warning is displayed. If this should occur, open the Network Load Balancing Properties dialog box to fix the problem.</p></td>
</tr>
<tr class="odd">
<td><p><strong>display</strong> [{<em>Cluster</em> | <strong>all</strong>}] (local only)</p></td>
<td><p>Displays extensive information about your current Network Load Balancing parameters, cluster state, and past cluster activity. The last several event log records produced by Network Load Balancing are shown, including the binary data attached to those records. This command is designed to assist in technical support and debugging.</p>
<p>The registry information retrieved by the <strong>display</strong> command shows what the next state of Network Load Balancing would be if a reload or some other operation that causes the driver to read the registry were to be performed. The registry information might or might not be the current state of Network Load Balancing.</p></td>
</tr>
<tr class="even">
<td><p><strong>params</strong> [{<em>Cluster</em> | <strong>all</strong>}] (local only)</p></td>
<td><p>Displays information about your current Network Load Balancing configuration. This command is similar to the <strong>display</strong> command, however, instead of retrieving the information from the registry, the <strong>params</strong> command queries directly from the kernel-mode driver. The information displayed is therefore the current state of Network Load Balancing. (The registry information retrieved by the <strong>display</strong> command shows what the next state of Network Load Balancing would be if a reload or some other operation that causes the driver to read the registry were to be performed. The registry information might or might not be the current state of Network Load Balancing.) In addition to the configuration information, <strong>nlb params</strong> displays state variables from the kernel, including the current number of connections being maintained by Network Load Balancing and the number of dynamic allocations that have been necessary for connection tracking.</p></td>
</tr>
<tr class="odd">
<td><p><strong>ip2mac</strong><em>Cluster</em></p></td>
<td><p>Displays the media access control address corresponding to the specified cluster name or IP address. If multicast support is enabled, the multicast media access control address is used by Network Load Balancing for cluster operations. Otherwise, the unicast media access control address is used. This command is useful for creating a static ARP entry in the router if necessary.</p></td>
</tr>
</tbody>
</table>
  • [ remote options]
    Specifies the remote options when using remote control operations. The following table describes the possible options.

    Value Description

    /PASSWPassword

    Specifies the remote control password

    /PORTPort

    Specifies the cluster's remote control UDP port.

    /local

    Perform the operations only on the local computer.

  • /?
    Displays help at the command prompt.

Remarks

  • The nlb.exe command replaces wlbs.exe. WLBS stands for Windows NT Load Balancing Service, the former name of Network Load Balancing in Windows NT 4.0. For reasons of backward compatibility, WLBS continues to be used in certain instances.

  • The cluster parameter can be either the cluster's full Internet name or the cluster's primary IP address. For more information, see Network Load Balancing parameters.

    You can omit the cluster option when running nlb.exe directly on a cluster host. In this instance, the command applies only to the local cluster host.

    To address the cluster as a whole or a different host within the cluster, you must also specify the target cluster, or target cluster and specific host together.

  • The host parameter specifies which host within the cluster to which the command should be applied. If the host parameter is omitted, the command applies to all hosts within the cluster.

    You can specify host name using the internet host name, the IP address, or the unique host priorities assigned in the Network Load Balancing Properties dialog box. You can use the special host priority value 0 (zero) to refer to the default host within a cluster.

    You can omit the host option when running nlb.exe directly on a cluster host. In this instance, the command applies only to the local cluster host.

    To address the cluster as a whole or a different host within the cluster, you must also specify the target cluster, or target cluster and specific host together.

  • Some commands can be invoked only on the cluster hosts (designated above as "local only").

  • Network Load Balancing hosts can be configured to join the cluster automatically upon startup or to wait for the nlb start command by enabling the initial host state option in the Network Load Balancing Properties dialog box. You can use this command with the nlb stop command to change cluster parameters for the local host without taking the entire cluster offline. For more information, see Network Load Balancing parameters.

  • You can modify the Network Load Balancing parameters (for example, to add a port rule) without disrupting the cluster's service to the clients. To do this, take a host out of the cluster, update its parameters, and then return it to the cluster. During this process, other cluster hosts will detect inconsistencies in the rules, and they will handle these inconsistencies in a manner that minimizes disruption of service to the clients. For more information about how inconsistencies are handled by Network Load Balancing, see Error detection and handling.

  • You can use the nlb disable and nlb enable commands to customize your cluster responses to various failures. For example, if your SNMP monitoring program indicates that a Web server program on one of the hosts has failed, you can issue the command nlb disable 80 to prevent that host from accepting any further client requests to the specified Web server port, causing other cluster hosts to handle its load. After the Web server has been restarted, the nlb enable 80 command can be issued to allow the host to resume handling a portion of the cluster's network load for this port.

Examples

The following table provides some examples of how these commands are used:

Example Description

nlb help

Returns Help information.

nlb query <mycluster>

Queries the status of all hosts in mycluster.

nlb stop

Stops cluster operations for the local cluster host.

nlb stop <mycluster>

Stops cluster operations for all cluster hosts in mycluster.

nlb start <mycluster>:2

Restarts cluster operations for host 2 in mycluster.

nlb disable 80

Disables the local host's handling of new network traffic for the Web server port (port 80).

nlb ip2mac <mycluster>

Displays media access control addresses corresponding to mycluster.

The following table summarizes the forms that the cluster and host parameters might take:

Cluster and host parameter Example Action

(omitted)

nlb stop

Invokes command on current cluster host.

Cluster

nlb stop <mycluster>

Invokes command on all cluster hosts.

Cluster : Host

nlb stop \

<mycluster>:<host1>

Invokes command on a specific cluster host.

The following table provides examples of different identification possibilities for clusters and hosts:

Example Description

<mycluster>:<host1>

Internet host names

<w>.<x>.<y>.<z>:<w>.<x>.<y>.<z>

IP addresses

<mycluster>:<w>.<x>.<y>.<z>

Mix of name and IP address

<mycluster>:1

Host 1 in mycluster

<mycluster>:0

Default host in mycluster

<mycluster>

All hosts in mycluster

Formatting legend

Format Meaning

Italic

Information that the user must supply

Bold

Elements that the user must type exactly as shown

Ellipsis (...)

Parameter that can be repeated several times in a command line

Between brackets ([])

Optional items

Between braces ({}); choices separated by pipe (|). Example: {even|odd}

Set of choices from which the user must choose only one

Courier font

Code or program output

See Also

Concepts

Network Load Balancing Clusters
Managing Network Load Balancing from the command line
Command-line reference A-Z
Command shell overview