Command reference for Dispatcher and CBR

This chapter describes how to use the Dispatcher dscontrol commands. It is also a command reference for CBR.

For previous versions, when the product was known as Network Dispatcher, the Dispatcher control command name was ndcontrol. The Dispatcher control command name is now dscontrol. Ensure you update all previous script files to use dscontrol (not ndcontrol) for configuring Dispatcher.

CBR uses a subset of the Dispatcher commands listed in this command reference. When using these syntax diagrams for CBR, substitute cbrcontrol for dscontrol. For information, see Configuration differences between CBR and Dispatcher.

The following list contains the commands noted in this chapter:

You can enter a minimized version of the dscontrol command parameters. You only need to enter the unique letters of the parameters. For example, to get help on the file save command, you can type dscontrol he f instead of dscontrol help file.

To start up the command-line interface: issue dscontrol to receive a dscontrol command prompt.

To end the command line interface: issue exit or quit.

The command parameter values must be entered in English characters. The only exceptions are host names (used in cluster, server, and highavailability commands) and file names (used in file commands).

Configuration differences between CBR and Dispatcher

The CBR command line interface is a subset of the command line interface of Dispatcher. For CBR, substitute the cbrcontrol command instead of dscontrol to configure the component.

Note:
The Content Based Routing (CBR) component is available on all supported platforms except those running a 64-bit JVM. Alternatively, you can use the cbr forwarding method of Load Balancer's Dispatcher component to provide content-based routing without the use of Caching Proxy. See Dispatcher's content-based routing (cbr forwarding method) for more information.

Some of the commands that are omitted in CBR are listed below.

  1. highavailability
  2. subagent
  3. executor
  4. cluster
  5. port
  6. rule add {c:p:r} type port
  7. server

dscontrol advisor -- control the advisor

Read syntax diagramSkip visual syntax diagram>>-dscontrol--advisor--+-connecttimeout--name--+-port---------+--timeoutseconds-+-><
                       |                       '-cluster:port-'                 |
                       +-interval--name--+-port---------+--seconds--------------+
                       |                 '-cluster:port-'                       |
                       +-list---------------------------------------------------+
                       +-loglevel--name--+-port---------+--level----------------+
                       |                 '-cluster:port-'                       |
                       +-logsize--name--+-port---------+--+-unlimited---------+-+
                       |                '-cluster:port-'  '-number of records-' |
                       +-receivetimeout--name--+-port---------+--timeoutseconds-+
                       |                       '-cluster:port-'                 |
                       +-report--name--+-port---------+-------------------------+
                       |               '-cluster:port-'                         |
                       +-retries--name--+-port---------+--numretries------------+
                       |                '-cluster:port-'                        |
                       +-start--name--+-port---------+--+----------+------------+
                       |              '-cluster:port-'  '-log file-'            |
                       +-status--name--+-port---------+-------------------------+
                       |               '-cluster:port-'                         |
                       +-stop--name--+-port---------+---------------------------+
                       |             '-cluster:port-'                           |
                       +-timeout--name--+-port---------+--+-unlimited-+---------+
                       |                '-cluster:port-'  '-seconds---'         |
                       '-version--name--+-port---------+------------------------'
                                        '-cluster:port-'
 

connecttimeout
Set how long an advisor waits before reporting that a connect to a server for a particular port on a server (a service) fails. For more information, see Advisor connect timeout and receive timeout for servers.
name
The name of the advisor. Possible values include connect, db2, dns, ftp, http, https, cachingproxy, imap, ldap, nntp, ping, pop3, self, sip, smtp, ssl, ssl2http, telnet, and wlm.

See List of advisors for more information on the advisors that Load Balancer provides.

Names of customized advisors are of the format xxxx, where ADV_xxxx is the name of the class that implements the custom advisor. See Create custom (customizable) advisors for more information.

port
The number of the port that the advisor is monitoring.
cluster:port
The cluster value is optional on the advisor commands, but the port value is required. If the cluster value is not specified, then the advisor will start running on the port for all clusters. If you specify a cluster, then the advisor will start running on the port, but only for the cluster you have specified. See Starting and stopping an advisor for more information.

The cluster is the address in IP address format or symbolic name. The port is the number of the port that the advisor is monitoring.

timeoutseconds
A positive integer representing the timeout in seconds at which the advisor waits before reporting that a connect to a server fails. The default is 3 times the value specified for the advisor interval.
interval
Set how often the advisor will query the servers for information.
seconds
A positive integer representing the number of seconds between requests to the servers about their current status. The default is 7.
list
Show list of advisors that are currently providing information to the manager.
loglevel
Set the logging level for an advisor log.
level
The number of the level (0 to 5). The default is 1. The higher the number, the more information that is written to the advisor log. The following are the possible values: 0 is None, 1 is Minimal, 2 is Basic, 3 is Moderate, 4 is Advanced, 5 is Verbose.
logsize
Set the maximum size of an advisor log. When you set a maximum size for the log file, the file will wrap; when the file reaches the specified size, the subsequent entries are written from the top of the file, overwriting the previous log entries. Log size cannot be set smaller than the current size of the log. Log entries are time-stamped so you can tell the order in which they were written. The higher you set the log level, the more carefully you should choose the log size, because you can quickly run out of space when logging at the higher levels.
number of records
The maximum size in bytes for the advisor log file. You can specify either a positive number greater than zero, or the word unlimited. The log file may not reach the exact maximum size before overwriting because the log entries themselves vary in size. The default value is 1 MB.
receivetimeout
Set how long an advisor waits before reporting that a receive from a particular port on a server (a service) fails. For more information, see Advisor connect timeout and receive timeout for servers.
timeoutseconds
A positive integer representing the timeout in seconds at which the advisor waits before reporting that a receive from a server fails. The default is 3 times the value specified for the advisor interval.
report
Display a report on the state of the advisor.
retry
Retry sets the number of retries that an advisor can make before marking a server down.
numretries
An integer greater than or equal to zero. This value should be no larger than 3. If retries keyword is not configured, the number of retries defaults to zero.
start
Start the advisor. There are advisors for each protocol. The default ports are as follows:
Advisor Name Protocol Port
cachingproxy HTTP (via Caching Proxy) 80
connect ICMP 12345
db2 private 50000
dns DNS 53
ftp FTP 21
http HTTP 80
https SSL 443
imap IMAP 143
ldap LDAP 389
nntp NNTP 119
ping PING 0
pop3 POP3 110
self private 12345
sip SIP 5060
smtp SMTP 25
ssl SSL 443
ssl2http SSL 443
telnet Telnet 23
WLM private 10,007
Note:
The FTP advisor should advise only on the FTP control port (21). Do not start an FTP advisor on the FTP data port (20).
log file
File name to which the management data is logged. Each record in the log is time-stamped.

The default file is advisorname_port.log, for example, http_80.log. To change the directory where the log files are kept, see Changing the log file paths. The default log files for cluster (or site) specific advisors are created with the cluster address, for example, http_127.40.50.1_80.log.

status
Display the current status of all the values in an advisor that can be set globally and their defaults.
stop
Stop the advisor.
timeout
Set the number of seconds for which the manager will consider information from the advisor as valid. If the manager finds that the advisor information is older than this timeout period, the manager will not use that information in determining weights for the servers on the port the advisor is monitoring. An exception to this timeout is when the advisor has informed the manager that a specific server is down. The manager will use that information about the server even after the advisor information has timed out.
seconds
A positive number representing the number of seconds or the word unlimited. The default value is unlimited.
version
Display the current version of the advisor.

Examples

dscontrol binlog -- control the binary log file

Read syntax diagramSkip visual syntax diagram>>-dscontrol--binlog--+-start----------------------+-----------><
                      +-stop-----------------------+
                      +-set--+-retention--hours--+-+
                      |      '-interval--seconds-' |
                      '-status---------------------'
 

start
Starts the binary log.
stop
Stops the binary log.
set
Sets fields for binary logging. For more information on setting fields for binary logging, see Using binary logging to analyze server statistics.
retention
The number of hours that binary log files are kept. The default value for retention is 24.
hours
The number of hours.
interval
The number of seconds between log entries. The default value for interval is 60.
seconds
The number of seconds.
status
Shows the retention and intervals of the binary log.

dscontrol cluster -- configure clusters

Read syntax diagramSkip visual syntax diagram>>-dscontrol--cluster--+-add--cluster+c2+...;;--+----------------------------------------+-+-><
                       |                      +-address--address-----------------------+ |
                       |                      +-proportions--active--new--port--system-+ |
                       |                      +-maxports--size-------------------------+ |
                       |                      +-maxservers--size-----------------------+ |
                       |                      +-stickytime--time-----------------------+ |
                       |                      +-weightbound--weight--------------------+ |
                       |                      +-porttype--type-------------------------+ |
                       |                      +-primaryhost--address-------------------+ |
                       |                      +-staletimeout--staletimeout-------------+ |
                       |                      '-sharedbandwidth--size------------------' |
                       +-set--cluster+c2+...;;--+-proportions--active--new--port--system-+-+
                       |                      +-maxports--size-------------------------+ |
                       |                      +-maxservers--size-----------------------+ |
                       |                      +-stickytime--time-----------------------+ |
                       |                      +-weightbound--weight--------------------+ |
                       |                      +-porttype--type-------------------------+ |
                       |                      +-primaryhost--address-------------------+ |
                       |                      +-staletimeout--staletimeout-------------+ |
                       |                      '-sharedbandwidth--size------------------' |
                       +-remove--cluster-------------------------------------------------+
                       +-report--cluster-------------------------------------------------+
                       '-status--cluster-------------------------------------------------'
 

add
Add this cluster. You must define at least one cluster.
cluster
The cluster name or address to which clients connect. The cluster value is either a symbolic name or in IP address format. A cluster value of 0.0.0.0 can be used to specify a wildcard cluster. See Use wildcard cluster to combine server configurations for more information.

With the exception of the dscontrol cluster add command, you can use a colon (:) to act as a wild card. For example, the following command, dscontrol cluster set : weightbound 80, will result in setting a weightbound of 80 to all clusters.

Note:
Additional clusters are separated by a plus sign (+).
address
The unique IP address of the TCP machine as either a host name or in IP address format. If the cluster value is unresolvable, you must provide this IP address of the physical machine.
Note:
Address only applies to the Dispatcher component.
address
Value of the address of the cluster.
proportions
At the cluster level, set the proportion of importance for active connections (active), new connections (new), information from any advisors (port), and information from a system monitoring program such as Metric Server (system) that are used by the manager to set server weights. Each of these values, described below, is expressed as a percentage of the total and they therefore always total 100. For more information see, Proportion of importance given to status information.
active
A number from 0-100 representing the proportion of weight to be given to the active connections. The default is 50.
new
A number from 0-100 representing the proportion of weight to be given to the new connections. The default is 50.
port
A number from 0-100 representing the proportion of weight to be given to the information from advisors. The default is 0.
Note:
When an advisor is started and if the port proportion is 0, Load Balancer automatically sets this value to 1 in order for the manager to use the advisor information as input for calculating server weight.
system
A number from 0-100 representing the proportion of weight to be given to the information from the system metrics, such as from Metric Server. The default is 0.
maxports
The maximum number of ports. The default value of maxports is 8.
size
The number of ports allowed.
maxservers
The default maximum number of servers per ports. This may be overridden for individual ports using port maxservers . The default value of maxservers is 32.
size
The number of servers allowed on a port.
stickytime
The default stickytime for ports to be created. This may be overridden for individual ports using port stickytime. The default value of stickytime is 0.
Note:
For the Dispatcher's cbr forwarding method, if you set stickytime (to a nonzero value), then port stickytime is enabled if the port is SSL (not HTTP). If stickytime for ports to be created is non-zero and the new port added is SSL, SSL ID affinity is enabled for the port. To disable SSL ID affinity on the port, you will need to explicitly set the port stickytime to 0.
time
The value of stickytime in seconds.
weightbound
The default port weight bound. This may be overridden for individual ports using port weightbound. The default value of weightbound is 20.
weight
The value of weightbound.
porttype
The default port type. This may be overridden for individual ports using port porttype.
type
Possible values are tcp, udp, and both.
primaryhost
The NFA address of this Dispatcher machine or the NFA address of the backup Dispatcher machine. In a mutual high availability configuration, a cluster is associated with either the primary or the backup machine.

If you change the primaryhost of a cluster after the primary and backups are already started and running mutual high availability, you also must force the new primary host to takeover. And, you need to update the scripts and manually unconfigure and configure the cluster correctly. See Mutual high availability for more information.

address
The address value of the primaryhost. The default is the NFA address of this machine.
staletimeout
The number of seconds during which there can be no activity on a connection before that connection is removed. The default for FTP is 900; the default for Telnet is 259,200. The default for all other protocols is 300. This may be overridden for individual ports using port staletimeout. See Using stale timeout value for more information.
staletimout
The staletimeout value.
sharedbandwidth
The maximum amount of bandwidth (in kilobytes per second) that can be shared at the cluster level. For more information on shared bandwidth, see Using rules based on reserved bandwidth and shared bandwidth and Shared bandwidth rule.
Note:
Shared bandwidth applies to the Dispatcher component.
size
The size of sharedbandwidth is an integer value. The default is zero. If the value is zero, then bandwidth cannot be shared at the cluster level.
set
Set the properties of the cluster.
remove
Remove this cluster.
report
Show the internal fields of the cluster.
Note:
Report applies to the Dispatcher component.
status
Show current status of a specific cluster.

Examples

dscontrol executor -- control the executor

Read syntax diagramSkip visual syntax diagram>>-dscontrol--executor--+-report-----------------------------------------------------------+-><
                        +-set--+-nfa--IP address------------+------------------------------+
                        |      +-maxclusters--size----------+                              |
                        |      +-maxports--size-------------+                              |
                        |      +-fintimeout--fintimeout-----+                              |
                        |      +-hatimeout--time------------+                              |
                        |      +-hasynctimeout--time--------+                              |
                        |      +-maxservers--size-----------+                              |
                        |      +-mss--size------------------+                              |
                        |      +-staletimeout--staletimeout-+                              |
                        |      +-stickytime--time-----------+                              |
                        |      +-clientgateway--address-----+                              |
                        |      +-weightbound--weight--------+                              |
                        |      +-porttype--type-------------+                              |
                        |      +-wideportnumber--port-------+                              |
                        |      '-sharedbandwidth--size------'                              |
                        +-configure--interface_address+i2+...--+-------------------------+-+
                        |                                      '-interface_name--netmask-' |
                        +-unconfigure--interface_address-----------------------------------+
                        +-start------------------------------------------------------------+
                        +-status-----------------------------------------------------------+
                        '-stop-------------------------------------------------------------'
 

report
Display a statistics snapshot report. For example: total packets received, packets discarded, packets forwarded with errors, and so on.
Note:
Report applies to the Dispatcher component.
set
Set the fields of the executor.
nfa
Set the nonforwarding address. Any packet sent to this address will not be forwarded by the Dispatcher machine.
Note:
NFA applies to the Dispatcher component.
IP address
The Internet Protocol address as either a symbolic name or in dotted decimal format.
maxclusters
The maximum number of clusters that can be configured. The default value of maxclusters is 100.
size
The maximum number of clusters that can be configured.
maxports
The default value of maxports for clusters to be created. This may be overridden by the cluster set or cluster add command. The default value of maxports is 8.
size
The number of ports.
fintimeout
The number of seconds to keep a connection in memory after the connection has been put in the FIN state. The default fintimeout value is 30.
fintimeout
The fintimeout value.
Note:
Fintimeout applies to the Dispatcher component.
hatimeout
The number of seconds that the executor uses to timeout high availability heartbeats. The default value is 2.
Note:
The hatimeout value applies to the Dispatcher component.
time
The hatimeout value.
hasynctimeout
The number of seconds that the executor uses to timeout replication of connection records between the primary and backup machine. The default value is 50.

The timer is used to ensure that the primary and backup machines attempt to synchronize. However, if there are too many connections in existence, and the active machine continues to handle a significant incoming traffic load, then synchronization might not complete before the timer expires. As a result, Load Balancer attempts to resynchronize perpetually, and the two machines never synchronize. If this situation occurs, set hasynctimeout to a larger value than the default to give the two machines enough time to exchange information about existing connections. In order to set this timer, the hasynctimeout command must be issued after the dscontrol executor start command but before issuing the high availability commands (dscontrol highavailability).

Note:
The hasynctimeout value applies to the Dispatcher component.
time
The hasynctimeout value.
maxservers
The default maximum number of servers per port. This may be overridden by the cluster or port command. The default value of maxservers is 32.
mss
The maximum number of bytes in the data segment of the TCP/UDP connection. The number of bytes in the data segment and the header must add up to less than the number of bytes in the maximum transmission unit (MTU). The default value of mss is 1460.
Note:
Maximum segment size only applies to Dispatcher component's nat or cbr forwarding method.
size
The number of servers.
staletimeout
The number of seconds during which there can be no activity on a connection before that connection is removed. The default for FTP is 900; the default for Telnet is 259,200. The default for all other ports is 300. This may be overridden by the cluster or port command. See Using stale timeout value for more information.
staletimeout
The staletimeout value.
stickytime
The default port sticky time value for all future clusters. It may be overridden by the cluster or port command. The default stickytime value is 0.
time
The stickytime value in seconds.
clientgateway
Clientgateway is an IP address used for NAT/NAPT or Dispatcher's content-based routing. It is the router address through which traffic in the return direction is forwarded from Load Balancer to clients. Clientgateway must be set to a nonzero value before adding a port with a forwarding method of NAT/NAPT or Dispatcher's content-based routing. See Dispatcher's NAT/NAPT (nat forwarding method) and Dispatcher's content-based routing (cbr forwarding method) for more information.
Note:
Clientgateway only applies to the Dispatcher component.
address
The clientgateway address as either a symbolic name or in dotted decimal format. The default is 0.0.0.0.
weightbound
The default port weightbound value for all future ports. It may be overridden by the cluster or port command. The default weightbound value is 20.
weight
The weightbound value.
porttype
The default port porttype value for all future ports. It may be overridden by the cluster or port command.
Note:
Porttype applies to the Dispatcher component.
type
Possible values are tcp, udp, and both.
wideportnumber
An unused TCP port on each Dispatcher machine. The wideportnumber must be the same for all the Dispatcher machines. The default value of wideportnumber is 0, indicating that wide area support is not in use.
Note:
Wideportnumber applies to the Dispatcher component.
port
The value of wideportnumber.
sharedbandwidth
The maximum amount of bandwidth (in kilobytes per second) that can be shared at the executor level. For more information on shared bandwidth, see Using rules based on reserved bandwidth and shared bandwidth and Shared bandwidth rule.
Note:
Shared bandwidth applies to the Dispatcher component.
size
The size of sharedbandwidth is an integer value. The default is zero. If the value is zero, then bandwidth cannot be shared at the executor level.
configure
Configure an address (for example a cluster address, return address, or high availability heartbeat address) to the network interface card of the Dispatcher machine. This is also known as configuring an alias on the Dispatcher machine.
Note:
Configure applies to the Dispatcher component.
interface_address
The address as either a symbolic name or in IP address format.
Note:
Additional interface addresses are separated by a plus sign (+).
interface_name netmask
It is only required if the address does not match any subnet for existing addresses. The interface_name can be a value such as: en0, eth1, eri0. The netmask is the 32-bit mask used to identify the subnetwork address bits in the host portion of an IP address.
unconfigure
Deletes the alias address from the network interface card.
Note:
Unconfigure applies to the Dispatcher component.
start
Start the executor.
status
Display the current status of the values in the executor that can be set and their defaults.
stop
Stop the executor.
Note:
Stop applies to Dispatcher and CBR.

Examples

dscontrol file -- manage configuration files

Read syntax diagramSkip visual syntax diagram>>-dscontrol--file--+-delete--file[.ext]----------+------------><
                    +-appendload--file[.ext]------+
                    +-report----------------------+
                    +-save--file[.ext]--+-------+-+
                    |                   '-force-' |
                    '-newload--file[.ext]---------'
 

delete
Delete the file.
file[.ext]
A configuration file consisting of dscontrol commands.

The file extension (.ext) can be anything you like and can be omitted.

appendload
To update the current configuration, the appendload command runs the executable commands from your script file.
report
Report on the available file or files.
save
Save the current configuration for Load Balancer to the file.
Note:
Files are saved into and loaded from the following directories, where component is either dispatcher or cbr:
  • Linux and UNIX systems: /opt/ibm/edge/lb/servers/configurations/component
  • Windows platform: C:\Program Files\ibm\edge\lb\servers\configurations\component
force
To save your file to an existing file of the same name, use force to delete the existing file before saving the new file. If you do not use the force option, the existing file is not overwritten.
newload
Loads and runs a new configuration file into the Load Balancer. The new configuration file replaces the current configuration.

Examples

dscontrol help -- display or print help for this command

Read syntax diagramSkip visual syntax diagram>>-dscontrol--help--+-advisor----------+-----------------------><
                    +-binlog-----------+
                    +-cluster----------+
                    +-executor---------+
                    +-file-------------+
                    +-help-------------+
                    +-highavailability-+
                    +-host-------------+
                    +-logstatus--------+
                    +-manager----------+
                    +-metric-----------+
                    +-port-------------+
                    +-rule-------------+
                    +-server-----------+
                    +-set--------------+
                    +-status-----------+
                    '-subagent---------'
 

Examples

dscontrol highavailability -- control high availability

Note:
The dscontrol high availability syntax diagram only applies to the Dispatcher component.
Read syntax diagramSkip visual syntax diagram>>-dscontrol--highavailability--+-status--------------------------------------+-><
                                +-backup--+-add--+-primary-+--+-auto---+--p-+-+
                                |         |      +-backup--+  '-manual-'    | |
                                |         |      '-both----'                | |
                                |         '-delete--------------------------' |
                                +-reach--+-add----+--address--mask------------+
                                |        '-delete-'                           |
                                +-heartbeat--+-add--srcaddress--dstaddress-+--+
                                |            '-delete--address-------------'  |
                                '-takeover--+---------+-----------------------'
                                            '-address-'
 

status
Return a report on high availability. Machines are identified as having one of three status conditions or states:
Active
A given machine (either a primary, backup, or both) is routing packets.
Standby
A given machine (either a primary, backup, or both) is not routing packets; it is monitoring the state of an active Dispatcher.
Idle
A given machine is routing packets, and is not trying to establish contact with its partner Dispatcher.
In addition, the status keyword returns information about various substates:
Synchronized
A given machine has established contact with another Dispatcher.
Other substates
This machine is trying to establish contact with its partner Dispatcher but has not yet succeeded.
backup
Specify information for either the primary or backup machine.
add
Defines and runs the high availability functions for this machine.
primary
Identifies the Dispatcher machine that has a primary role.
backup
Identifies the Dispatcher machine that has a backup role.
both
Identifies the Dispatcher machine that has both a primary and backup role. This is the mutual high availability feature in which primary and backup roles are associated on a per cluster set basis. See Mutual high availability for more information.
auto
Specifies an automatic recovery strategy, in which the primary machine will resume routing packets as soon as it comes back into service.
manual
Specifies a manual recovery strategy, in which the primary machine does not resume routing packets until the administrator issues a takeover command.
p[ort]
An unused TCP port on both machines, to be used by Dispatcher for its heartbeat messages. The port must be the same for both the primary and backup machines.
delete
Removes this machine from high availability, so that it will no longer be used as a backup or primary machine.
reach
Add or delete target address for the primary and backup Dispatchers, the reach advisor sends out pings from both the backup and the primary Dispatchers to determine how reachable their targets are.
Note:
When configuring the reach target, you must also start the reach advisor. The reach advisor starts automatically by the manager function.
add
Adds a target address for the reach advisor.
delete
Removes a target address from the reach advisor.
address
IP address (IP address format or symbolic) of the target node.
mask
A subnet mask.
heartbeat
Defines a communication session between the primary and backup Dispatcher machines.
add
Tell the source Dispatcher the address of its partner (destination address).
srcaddress
Source address. The address (IP or symbolic) of this Dispatcher machine.
dstaddress
Destination address. The address (IP or symbolic) of the other Dispatcher machine.
Note:
The srcaddress and dstaddress must be the NFAs of the machines for at least one heartbeat pair.
delete
Removes the address pair from the heartbeat information. You can specify either the destination or source address of the heartbeat pair.
address
The address (IP or symbolic) of either the destination or source.
takeover
Simple high availability configuration (role of the Dispatcher machines are either primary or backup):
  • Takeover instructs a standby Dispatcher to become active and to begin routing packets. This will force the currently active Dispatcher to become standby. The takeover command must be issued on the standby machine and works only when the strategy is manual. The substate must be synchronized.
Mutual high availability configuration (role of each Dispatcher machine is both):
  • The Dispatcher machine with the mutual high availability feature contains two clusters which match its partner's. One of the clusters is considered the primary cluster (the partner's backup cluster), and the other is the backup cluster (the partner's primary cluster). Takeover instructs the Dispatcher machine to begin routing packets for the other machine's cluster(s). The takeover command can only be issued when the cluster(s) of the Dispatcher machine are in standby state and the substate is synchronized. This will force the partner's currently active cluster(s) to change to standby state. The takeover command works only when the strategy is manual. See Mutual high availability for more information.
Notes:
  1. Note that the roles of the machines (primary, backup, both) do not change. Only their relative status (active or standby) changes.
  2. There are three possible takeover scripts: goActive, goStandby, and goInOp. See Using scripts.
address
The takeover address value is optional. It should only be used when the role of the machine is both primary and backup (mutual high availability configuration). The address specified is the NFA of the Dispatcher machine which normally routes this cluster's traffic. When there is a takeover of both clusters, specify the Dispatcher's own NFA address.

Examples

dscontrol host -- configure a remote machine

Read syntax diagramSkip visual syntax diagram>>-dscontrol--host:--remote_host-------------------------------><
 

remote_host
The name of the remote Load Balancer machine being configured. When typing this command, make sure there is no space between host: and remote_host, for example:
dscontrol host:remote_host
After this command has been issued on the command prompt, enter any valid dscontrol command you want issued to the remote Load Balancer machine.

dscontrol logstatus -- display server log settings

Read syntax diagramSkip visual syntax diagram>>-dscontrol--logstatus----------------------------------------><
 

logstatus
Displays the server log settings (log file name, logging level, and log size).

Examples

To display the logstatus:

dscontrol logstatus

This command produces output similar to:


Dispatcher Log Status:
------------------------------
Log filename ............... C:\PROGRA~1\IBM\edge\lb\servers\logs\dispatcher
\server.log
Log level .................. 1
Maximum log size (bytes) ... 1048576

dscontrol manager -- control the manager

Read syntax diagramSkip visual syntax diagram>>-dscontrol--manager--+-interval--seconds----------------------+-><
                       +-loglevel--level------------------------+
                       +-logsize--+-unlimited-+-----------------+
                       |          '-bytes-----'                 |
                       +-metric set--+-loglevel--level--------+-+
                       |             '-logsize--+-unlimited-+-' |
                       |                        '-bytes-----'   |
                       +-quiesce--server--+-----+---------------+
                       |                  '-now-'               |
                       +-reach set--+-interval--seconds------+--+
                       |            +-loglevel--level--------+  |
                       |            '-logsize--+-unlimited-+-'  |
                       |                       '-bytes-----'    |
                       +-refresh--refresh cycle-----------------+
                       +-report--+----------------+-------------+
                       |         '-cluster+c2+...-'             |
                       +-restart--message-----------------------+
                       +-sensitivity--weight--------------------+
                       +-smoothing--smoothing index-------------+
                       +-start--+-----------------------+-------+
                       |        '-log file--metric_port-'       |
                       +-status---------------------------------+
                       +-stop-----------------------------------+
                       +-unquiesce--server----------------------+
                       '-version--------------------------------'
 

interval
Set how often the manager will update the weights of the servers to the executor, updating the criteria that the executor uses to route client requests.
seconds
A positive number representing in seconds how often the manager will update weights to the executor. The default is 2.
loglevel
Set the logging level for the manager log.
level
The number of the level (0 to 5). The higher the number, the more information that is written to the manager log. The default is 1. The following are the possible values: 0 is None, 1 is Minimal, 2 is Basic, 3 is Moderate, 4 is Advanced, 5 is Verbose.
logsize
Set the maximum size of the manager log. When you set a maximum size for the log file, the file will wrap; when the file reaches the specified size, the subsequent entries are written from the top of the file, overwriting the previous log entries. Log size cannot be set smaller than the current size of the log. Log entries are time stamped so you can tell the order in which they were written. The higher you set the log level, the more carefully you should choose the log size, because you can quickly run out of space when logging at the higher levels.
bytes
The maximum size in bytes for the manager log file. You can specify either a positive number greater than zero, or the word unlimited. The log file may not reach the exact maximum size before overwriting because the log entries themselves vary in size. The default value is 1 MB.
metric set
Sets the loglevel and logsize for the metric monitor log. The loglevel is the metric monitor logging level (0 - None,1 - Minimal,2 - Basic,3 - Moderate, 4 - Advanced, or 5 - Verbose). The default loglevel is 1. The logsize is the maximum number of bytes to be logged in the metric monitor log file. You can specify either a positive number greater than zero, or unlimited. The default logsize is 1 MB.
quiesce
Specify no more connections to be sent to a server except subsequent new connections from the client to the quiesced server if the connection is designated as sticky and stickytime has not expired. The manager sets the weight for that server to 0 in every port to which it is defined. Use this command if you want to do some quick maintenance on a server and then unquiesce it. If you delete a quiesced server from the configuration and then add it back, it will not retain its status prior to being quiesced. For more information, see Quiesce server connection handling.
server
The IP address of the server as either a symbolic name or in dotted decimal format.

Or, if you used server partitioning, use the logical server's unique name. See Server Partitioning: logical servers configured to one physical server (IP address) for more information.

now
Only use quiesce "now" if you have stickytime set and you want new connections sent to another server (other than the quiesced server) before stickytime expires. For more information, see Quiesce server connection handling.
reach set
Sets the interval, loglevel, and logsize for the reach advisor.
refresh
Set the number of intervals before querying the executor for a refresh of information about new and active connections.
refresh cycle
A positive number representing the number of intervals. The default is 2.
report
Display a statistics snapshot report.
cluster
The address of the cluster you want displayed in the report. The address can be either a symbolic name or in IP address format. The default is a manager report display for all the clusters.
Note:
Additional clusters are separated by a plus sign (+).
restart
Restart all servers (that are not down) to normalized weights (1/2 of maximum weight).
message
A message that you want written to the manager log file.
sensitivity
Set minimum sensitivity to which weights update. This setting defines when the manager should change its weighting for the server based on external information.
weight
A number from 1 to 100 to be used as the weight percentage. The default of 5 creates a minimum sensitivity of 5%.
smoothing
Set an index that smooths the variations in weight when load balancing. A higher smoothing index will cause server weights to change less drastically as network conditions change. A lower index will cause server weights to change more drastically.
index
A positive floating point number. The default is 1.5.
start
Start the manager.
log file
File name to which the manager data is logged. Each record in the log is time stamped.

The default file is installed in the logs directory. See Appendix C. Sample configuration files. To change the directory where the log files are kept, see Changing the log file paths.

metric_port
Port that Metric Server will use to report system loads. If you specify a metric port, you must specify a log file name. The default metric port is 10004.
status
Display the current status of all the values in the manager that can be set globally and their defaults.
stop
Stop the manager.
unquiesce
Specify that the manager can begin to give a weight higher than 0 to a server that was previously quiesced, in every port to which it is defined.
server
The IP address of the server as either a symbolic name or in dotted decimal format.
version
Display the current version of the manager.

Examples

dscontrol metric -- configure system metrics

Read syntax diagramSkip visual syntax diagram>>-dscontrol--metric--+-add--cluster+c2+...+cN:metric+metric1+...+metricN--------------+-><
                      +-remove--cluster+c2+...+cN:metric+metric1+...+metricN-----------+
                      +-proportions--cluster+c2+...+cN proportion1 prop2 prop3...propN-+
                      '-status--cluster+c2+...+cN:metric+metric1+...+metricN-----------'
 

add
Add the specified metric.
cluster
The address to which clients connect. The address can be either the host name of the machine, or the IP address notation format. Additional clusters are separated by a plus sign (+).
metric
The system metric name. This must be the name of an executable or script file in the metric server's script directory.
remove
Remove the specified metric.
proportions
Set the proportions for all the metrics associated with this object.
status
Display the current values of this metric.

Examples

dscontrol port -- configure ports

Read syntax diagramSkip visual syntax diagram>>-dscontrol--port--+-add--cluster:port--+----------------------+-+-><
                    |                    +-crossport--otherport-+ |
                    |                    +-maxservers--size-----+ |
                    |                    +-stickymask--value----+ |
                    |                    +-stickytime--time-----+ |
                    |                    +-method--type---------+ |
                    |                    +-staletimeout--value--+ |
                    |                    +-weightbound--weight--+ |
                    |                    +-porttype--type-------+ |
                    |                    +-protocol--type-------+ |
                    |                    '-reset--value---------' |
                    +-set--cluster:port--+-crossport--otherport-+-+
                    |                    +-maxservers--size-----+ |
                    |                    +-stickymask--value----+ |
                    |                    +-stickytime--time-----+ |
                    |                    +-staletimeout--value--+ |
                    |                    +-weightbound--weight--+ |
                    |                    +-porttype--type-------+ |
                    |                    +-maxhalfopen--value---+ |
                    |                    '-reset--value---------' |
                    +-remove--cluster:port------------------------+
                    +-report--cluster:port------------------------+
                    +-status--cluster:port------------------------+
                    '-halfopenaddressreport--cluster:port---------'
 

add
Add a port to a cluster. You must add a port to a cluster before you can add any servers to that port. If there are no ports for a cluster, all client requests are processed locally. You can add more than one port at one time using this command.
cluster
The address of the cluster as either a symbolic name or in IP address format. You can use a colon (:) to act as a wild card. For instance, the following command, dscontrol port add :80, will result in adding port 80 to all clusters.
Note:
Additional clusters are separated by a plus sign (+).
port
The number of the port. A port number value of 0 (zero) can be used to specify a wildcard port.
Note:
Additional ports are separated by a plus sign (+).
crossport
Crossport allows you to expand the sticky/affinity feature across multiple ports so that client requests received on different ports can still be sent to the same server for subsequent requests. For crossport value, specify the otherport number for which you want to share the cross port affinity feature. In order to use this feature, the ports must:
  • share the same cluster address
  • share the same servers
  • have the same (nonzero) stickytime value
  • have the same stickymask value
To remove the crossport feature, set the crossport value back to its own port number. For more information on cross port affinity feature, see Cross port affinity.
Note:
Crossport only applies to the Dispatcher component's MAC and NAT/NATP forwarding methods.
otherport
The value of crossport. The default value is the same as its own port number.
maxservers
The maximum number of servers. The default value of maxservers is 32.
size
The value of maxservers.
stickymask
The affinity address mask feature groups incoming client requests based on common subnet addresses. When a client request first makes a connection to the port, all subsequent requests from clients with the same subnet address (designated by that part of the IP address which is being masked) are directed to the same server. In order to enable stickymask, port stickytime must be a nonzero value. See Affinity address mask (stickymask) for more information.
Note:
The stickymask keyword only applies to the Dispatcher component.
value
The stickymask value is the number of high-order bits of the 32-bit IP address you want to mask. Possible values are: 8, 16, 24, and 32. The default value is 32, which disables the affinity address mask feature.
stickytime
The interval between the closing of one connection and the opening of a new connection during which a client will be sent back to the same server used during the first connection. After the sticky time, the client may be sent to a server different from the first.

For the Dispatcher component:

  • For Dispatcher's cbr forwarding method
    • You can only set stickytime (to a nonzero value) on an SSL (not HTTP) port because setting stickytime enables SSL ID affinity.
    • If you set the port stickytime, then the affinity type on the rule must be none (default). Rule-based affinity (passive cookie, URI) cannot co-exist when stickytime is set on the port.
  • For Dispatcher's mac and nat forwarding methods
    • If you set the port stickytime (to a nonzero value), then you cannot set an affinity type on the rule. Rule-based affinity cannot co-exist when stickytime is set on the port.
    • Setting a port stickytime value enables IP address affinity.

For the CBR component: If you set the port stickytime to a nonzero value, then the affinity type on the rule must be none (default). Rule-based affinity (passive cookie, URI, active cookie) cannot co-exist when stickytime is set on the port.

time
The port sticky time in number of seconds. Zero signifies that the port is not sticky.
method
The forwarding method. Possible forwarding methods are: mac forwarding, nat forwarding, or content-based routing (cbr) forwarding. You may not add a forwarding method of nat or cbr unless you first specify a nonzero IP address in the clientgateway parameter of the dscontrol executor command. See Dispatcher's NAT/NAPT (nat forwarding method) and Dispatcher's content-based routing (cbr forwarding method) for more information.
Notes:
  1. Method only applies to the Dispatcher component.
  2. If the backend server is on the same subnet as the return address, and if you are using the cbr forwarding method or the nat forwarding method, you must define the router address to be the backend server address.
  3. If you add a mac forwarding method, then you are required to specify the "protocol" parameter as either HTTP or SSL.
type
The forwarding method type. Possible values are: mac, nat, or cbr. The default is mac forwarding.
staletimeout
The number of seconds during which there can be no activity on a connection before that connection is removed. For the Dispatcher component, the default value is 900 for port 21 (FTP) and 259,200 for port 23 (Telnet). For all other Dispatcher ports and for all CBR ports, the default is 300. Staletimeout can also be set at the executor or cluster level. See Using stale timeout value for more information.
value
The value of staletimeout in number of seconds.
weightbound
Set the maximum weight for servers on this port. This affects how much difference there can be between the number of requests the executor will give each server. The default value is 20.
weight
A number from 1-100 representing the maximum weight bound.
porttype
The port type.
Note:
Porttype only applies to Dispatcher.
type
Possible values are tcp, udp, and both. The default value is both (tcp/udp).
protocol
The protocol type. For the Dispatcher component, this is a required parameter when specifying a "cbr" method on the port. If you select a port protocol type SSL, you should also specify a nonzero stickytime to enable SSL ID affinity. If you select HTTP protocol, you can establish server affinity using "content" rules. See Dispatcher's content-based routing (cbr forwarding method) for more information.
Note:
Protocol only applies to Dispatcher's cbr forwarding method.
type
Possible values are HTTP or SSL.
maxhalfopen
The threshold for maximum half-open connections. Use this parameter to detect possible denial of service attacks that result in a large number of half-opened TCP connections on servers.

A positive value indicates that a check is made to determine if the current half-open connections exceeds the threshold. If the current value is above the threshold, a call to an alert script is made. See Denial of service attack detection for more information.

Note:
maxhalfopen only applies to Dispatcher.
value
The value of maxhalfopen. The default is zero (no checking will be made).
reset
Reset allows you to specify whether Load Balancer will send TCP resets to down servers on the port. A TCP reset causes the connection to be immediately closed. See Sending TCP reset to a down server (Dispatcher component only) for more information.
Note:
Reset only applies to the Dispatcher component. The clientgateway on the dscontrol executor command must be set to a router address in order to use the reset keyword.
value
Possible values for reset are yes and no. The default is no (no TCP resets are made to down servers). When reset is yes, TCP resets are sent to down servers.
set
Set the fields of a port.
remove
Remove this port.
report
Report on this port.
status
Show status of servers on this port. If you want to see the status on all ports, do not specify a port with this command. Do not forget the colon, however.
numSeconds
The amount of time in seconds before resetting half-open connections.
halfopenaddressreport
Generates entries in the log (halfOpen.log) for all the client addresses (up to approximately 8000 address pairs) that have accessed servers that have any half open connnections. Also, statistical data is reported back to the command line, such as: total, largest, and average number of half-open connections, and the average half-open connection time (in seconds). See Denial of service attack detection for more information.

Examples

dscontrol rule -- configure rules

Read syntax diagramSkip visual syntax diagram>>-dscontrol--rule--+-add--cluster:port:rule--type--type--| opts |-+-><
                    +-dropserver--cluster:port:rule--server--------+
                    +-remove--cluster:port:rule--------------------+
                    +-report--cluster:port:rule--------------------+
                    +-set--cluster:port:rule--| opts |-------------+
                    +-status--cluster:port:rule--------------------+
                    '-useserver--cluster:port:rule--server+s2+...--'
 
opts:
 
|--+---------------------------------+--------------------------|
   +-beginrange--low--endrange--high-+
   +-priority--level-----------------+
   +-pattern--pattern----------------+
   +-tos--value----------------------+
   +-stickytime--time----------------+
   +-affinity--affinity_type---------+
   +-cookiename--value---------------+
   +-evaluate--level-----------------+
   '-sharelevel--level---------------'
 

add
Add this rule to a port.
cluster
The address of the cluster as either a symbolic name or in IP address format. You can use a colon (:) to act as a wild card. For instance, the following command, dscontrol rule add :80:RuleA type type, will result in adding RuleA to port 80 for all clusters.
Note:
Additional clusters are separated by a plus sign (+).
port
The number of the port. You can use a colon (:) to act as a wild card. For instance, the following command, dscontrol rule add clusterA::RuleA type type, will result in adding RuleA to all ports for ClusterA.
Note:
Additional ports are separated by a plus sign (+).
rule
The name you choose for the rule. This name can contain any alphanumeric character, underscore, hyphen, or period. It can be from 1 to 20 characters and cannot contain any blanks.
Note:
Additional rules are separated by a plus sign (+).
type
The type of rule.
type
Your choices for type are:
ip
The rule is based on the client IP address.
time
The rule is based on the time of day.
connection
The rule is based on the number of connections per second for the port. This rule will work only if the manager is running.
active
The rule is based on the number of active connections total for the port. This rule will work only if the manager is running.
port
The rule is based on the client port.
Note:
Port applies to the Dispatcher component.
service
This rule is based on the type of service (TOS) byte field in the IP header.
Note:
Service only applies to the Dispatcher component.
reservedbandwidth
This rule is based on the bandwidth (kilobytes per second) being delivered by a set of servers. For more information, see Using rules based on reserved bandwidth and shared bandwidth and Reserved bandwidth rule.
Note:
Reservedbandwidth only applies to the Dispatcher component.
sharedbandwidth
This rule is based on the amount of bandwidth (kilobytes per second) that is shared at the executor or cluster level. For more information, see Using rules based on reserved bandwidth and shared bandwidth and Shared bandwidth rule.
Note:
Sharedbandwidth only applies to the Dispatcher component.
true
This rule is always true. Think of it as an else statement in programming logic.
content
This rule describes a regular expression that will be compared to the client requested URLs. This is valid for Dispatcher and CBR.
beginrange
The lower value in the range used to determine whether or not the rule is true.
low
Depends on the type of rule. The kind of value and its default are listed here by the type of rule:
ip
The address of the client as either a symbolic name or in IP address format. The default is 0.0.0.0.
time
An integer. The default is 0, representing midnight.
connection
An integer. The default is 0.
active
An integer. The default is 0.
port
An integer. The default is 0.
reservedbandwidth
An integer (kilobytes per second). The default is 0.
endrange
The higher value in the range used to determine whether or not the rule is true.
high
Depends on the type of rule. The kind of value and its default are listed here by the type of rule:
ip
The address of the client as either a symbolic name or in IP address format. The default is 255.255.255.254.
time
An integer. The default is 24, representing midnight.
Note:
When defining the beginrange and endrange of time intervals, note that each value must be an integer representing only the hour portion of the time; portions of an hour are not specified. For this reason, to specify a single hour--say, the hour between 3:00 and 4:00 am-- you would specify a beginrange of 3 and an endrange also of 3. This will signify all the minutes beginning with 3:00 and ending with 3:59. Specifying a beginrange of 3 and an endrange of 4 would cover the two-hour period from 3:00 through 4:59.
connections
An integer. The default is 2 to the 32nd power minus 1.
active
An integer. The default is 2 to the 32nd power minus 1.
port
An integer. The default is 65535.
reservedbandwidth
An integer (kilobytes per second). The default is 2 to the 32nd power minus 1.
priority
The order in which the rules are reviewed.
level
An integer. If you do not specify the priority of the first rule you add, Dispatcher will set it by default to 1. When a subsequent rule is added, by default its priority is calculated to be 10 + the current lowest priority of any existing rule. For example, assume you have an existing rule whose priority is 30. You add a new rule and set its priority at 25 (which, remember, is a higher priority than 30). Then you add a third rule without setting a priority. The priority of the third rule is calculated to be 40 (30 + 10).
pattern
Specifies the pattern to be used for a content type rule.
pattern
The pattern to be used. For more information on valid values, see Appendix B. Content rule (pattern) syntax.
tos
Specifies the "type of service" (TOS) value used for the service type rule.
Note:
TOS only applies to the Dispatcher component.
value
The 8 character string to be used for the tos value, where valid characters are: 0 (binary zero), 1 (binary one), and x (do not care). For example: 0xx1010x. For more information, see Using rules based on type of service (TOS).
stickytime
Specifies the stickytime to be used for a rule. When setting the affinity parameter to "activecookie" on the rule command, stickytime should be set to a nonzero value to enable this affinity type. Stickytime on the rule does not apply to "passivecookie" or "uri" affinity rule types.

See Active cookie affinity for more information.

Note:
Rule stickytime only applies to the CBR component.
time
Time in seconds.
affinity
Specifies the affinity type to be used for a rule: active cookie, passive cookie, URI, or none.

An affinity type of "activecookie" enables load-balancing Web traffic with affinity to the same server based upon cookies generated by Load Balancer.

An affinity type of "passivecookie" enables load-balancing Web traffic with affinity to the same server based upon self-identifying cookies generated by the servers. You must use the cookiename parameter in conjunction with passive cookie affinity.

An affinity type of "URI" enables load-balancing Web traffic to caching-proxy servers in a manner which effectively increases the size of the cache.

See Active cookie affinity, Passive cookie affinity, and URI affinity for more information.

Note:
Affinity applies to rules configured with the Dispatcher component's cbr forwarding method and to the CBR component.
affinity_type
Possible values for affinity type are: none (default), activecookie, passivecookie, or uri.
cookiename
An arbitrary name set by the administrator that acts as an identifier to Load Balancer. It is the name that Load Balancer should look for in the client HTTP header request. The cookie name, along with the cookie value, acts as an identifier to Load Balancer allowing Load Balancer to send subsequent requests of a Web site to the same server machine. Cookie name is only applicable with "passive cookie" affinity.

See Passive cookie affinity for more information.

Note:
Cookie name applies to rules configured with the Dispatcher component's cbr forwarding method and to the CBR component.
value
The cookie name value.
evaluate
This option is available only in the Dispatcher component. Specifies whether to evaluate the rule's condition across all servers within the port or across servers within the rule. This option is only valid for rules that make their decisions based upon the characteristics of the servers, such as: connection, active, and reservedbandwidth rules. For more information, see Server evaluation option for rules.

For the connection type rule, you can also specify an evaluate option -- upserversonrule. By specifying upserversonrule, you can ensure that the remaining servers within the rule will not be overloaded if some of the servers in the server-set are down.

level
Possible values are port, rule, or upserversonrule. The default is port. upserversonrule is only available for the connection type rule.
sharelevel
This parameter is only for the shared bandwidth rule. Specifies whether to share bandwidth at the cluster level or executor level. Sharing bandwidth at the cluster level allows a port (or ports) to share a maximum amount of bandwidth across several ports within the same cluster. Sharing bandwidth at the executor level allows a cluster (or clusters) within the entire Dispatcher configuration to share a maximum amount of bandwidth. For more information see Shared bandwidth rule.
level
Possible values are executor or cluster.
dropserver
Remove a server from a rule set.
server
The IP address of the TCP server machine as either a symbolic name or in IP address format.

Or, if you used server partitioning, use the logical server's unique name. See Server Partitioning: logical servers configured to one physical server (IP address) for more information.

Note:
Additional servers are separated by a plus sign (+).
remove
Remove one or more rules, separated from one another by plus signs.
report
Display the internal values of one or more rules.
set
Set values for this rule.
status
Display the settable values of one or more rules.
useserver
Insert servers into a rule set.

Examples

dscontrol server -- configure servers

Read syntax diagramSkip visual syntax diagram>>-dscontrol--server--+-add--cluster:port:server--+-------------------------+-+-><
                      |                           +-address--address--------+ |
                      |                           +-collocated--value-------+ |
                      |                           +-sticky--value-----------+ |
                      |                           +-weight--value-----------+ |
                      |                           +-fixedweight--value------+ |
                      |                           +-cookievalue--value------+ |
                      |                           +-mapport--portvalue------+ |
                      |                           +-protocol--value---------+ |
                      |                           +-router--addr------------+ |
                      |                           +-returnaddress--addr-----+ |
                      |                           +-advisorrequest--string--+ |
                      |                           '-advisorresponse--string-' |
                      +-set--cluster:port:server--+-collocated--value-------+-+
                      |                           +-sticky--value-----------+ |
                      |                           +-weight--value-----------+ |
                      |                           +-fixedweight--value------+ |
                      |                           +-cookievalue--value------+ |
                      |                           +-protocol--value---------+ |
                      |                           +-router--addr------------+ |
                      |                           +-advisorrequest--string--+ |
                      |                           '-advisorresponse--string-' |
                      +-down--cluster:port:server-----------------------------+
                      +-remove--cluster:port:server---------------------------+
                      +-report--cluster:port:server---------------------------+
                      +-up--cluster:port:server-------------------------------+
                      '-status--cluster:port:server---------------------------'
 

add
Add this server.
cluster
The address of the cluster as either a symbolic name or in IP address format. You can use a colon (:) to act as a wild card. For instance, the following command, dscontrol server add :80:ServerA, will result in adding ServerA to port 80 on all clusters.
Note:
Additional clusters are separated by a plus sign (+).
port
The number of the port. You can use a colon (:) to act as a wild card. For instance, the following command, dscontrol server add ::ServerA, will result in adding ServerA to all clusters on all ports.
Note:
Additional ports are separated by a plus sign (+).
server
The server is the unique IP address of the TCP server machine as either a symbolic name or in IP address format.

Or, if you use a unique name that does not resolve to an IP address, you must provide the server address parameter on the dscontrol server add command. See Server Partitioning: logical servers configured to one physical server (IP address) for more information.

Note:
Additional servers are separated by a plus sign (+).
address
The unique IP address of the TCP server machine as either a host name or in IP address format. If the server is unresolvable, you must provide the address of the physical server machine. See Server Partitioning: logical servers configured to one physical server (IP address) for more information.
address
Value of the address of the server.
collocated
Collocated allows you to specify if the Dispatcher is installed on one of the server machines it is load balancing.
Note:
Collocated parameter is valid when using the Dispatcher's mac, nat, or cbr forwarding methods. Site Selector and CBR can be collocated on all platforms but do not require this keyword. For more information, see Using collocated servers.
value
Value of collocated: yes or no. Default is no.
sticky
Allows a server to override the stickytime setting on its port. With a default value of "yes," the server retains the normal affinity as defined at the port. With a value of "no," the client will not return to that server the next time it issues a request on that port regardless of the stickytime setting of the port. This is useful in certain situations when you are using rules. For more information, see port affinity override.
value
Value of sticky: yes or no. Default is yes.
weight
A number from 0-100 (but not to exceed the specified port's weightbound value) representing the weight for this server. Setting the weight to zero will prevent any new requests from being sent to the server, but will not end any currently active connections to that server. The default is one-half the specified port’s maximum weightbound value. If the manager is running, this setting will be quickly overwritten.
value
Value of the server weight.
fixedweight
The fixedweight option allows you to specify whether you want the manager to modify the server weight or not. If you set the fixedweight value to yes, when the manager runs it will not be allowed to modify the server weight. For more information, see Manager fixed weights.
value
Value of fixedweight: yes or no. Default is no.
cookievalue
Cookievalue is an arbitrary value that represents the server side of the cookie name/ cookie value pair. The cookie value, along with the cookie name, acts as an identifier allowing Load Balancer to send subsequent client requests to the same server. See Passive cookie affinity for more information.
Note:
Cookievalue is valid for Dispatcher (using cbr forwarding method) and CBR.
value
Value is any arbitrary value. Default is no cookie value.
mapport
Map the client request's destination port number (which is for Dispatcher) to the server's port number that Dispatcher uses to load balance the client's request. Allows Load Balancer to receive a client's request on one port and to transmit it to a different port on the server machine. With mapport you can load balance a client's requests to a server that may have multiple server daemons running.
Note:
Mapport applies to Dispatcher (using nat or cbr forwarding methods) and to CBR. For Dispatcher, see Dispatcher's NAT/NAPT (nat forwarding method) and Dispatcher's content-based routing (cbr forwarding method). For CBR, see Load balancing client-to-proxy in SSL and proxy-to-server in HTTP.
protocol
The valid values for protocol are HTTP and HTTPS. The default is HTTP.
Note:
Protocol only applies to the CBR component.
portvalue
Value of the map port number. The default is the client request's destination port number.
router
If you are setting up a wide area network, the address of the router to the remote server. Default is 0, indicating a local server. Note that when a server's router address is set to something other than zero (indicating a remote server), it cannot be reset to 0 to make the server local again. Instead, the server must be removed, then added again without a router address being a specified. Similarly, a server defined as local (router address = 0) cannot be made remote by changing the router address. The server must be removed and added again. See Configure wide area Dispatcher support for more information.
Note:
Router only applies to Dispatcher. If you are using nat or cbr forwarding methods, when you add a server to the configuration you must specify the router address.
addr
Value of the address of the router.
returnaddress
A unique IP address or hostname. It is an address configured on the Dispatcher machine that Dispatcher uses as its source address when load balancing the client's request to the server. This ensures that the server will return the packet to the Dispatcher machine in order to process the content of the request, rather than sending the packet directly to the client. (Dispatcher will then forward the IP packet on to the client.) You must specify the return address value when the server is added. Return address cannot be changed unless you remove the server and add it again. The return address cannot be the same as the cluster, server, or NFA address.
Note:
Returnaddress only applies to Dispatcher. When you use nat or cbr forwarding methods, you must define a return address for communication between Load Balancer and the back-end servers. The number of connections that Load Balancer can keep active with the back-end server is limited by the number of return addresses that are defined. Load Balancer uses ports that are based upon the return address only; not the return address and server combination. When all the available ports are in use, additional connections fail. In a busy environment, use multiple return addresses to prevent a shortage of available ports.
addr
Value of the return address.
advisorrequest
The HTTP or HTTPS advisor uses the advisor request string to query the health of the servers. It will only be valid for servers which are advised upon by the HTTP or HTTPS advisor. You must start the HTTP or HTTPS advisor in order for this value to be enabled. See Configuring the HTTP or HTTPS advisor using the request and response (URL) option for more information.
Note:
The advisorrequest applies to Dispatcher and CBR components.
string
Value of the string used by the HTTP or HTTPS advisor. The default is HEAD / HTTP/1.0.
Note:
If a blank is contained within the string --
  • When issuing the command from the dscontrol>> shell prompt, you must place quotes around the string. For example: server set cluster:port:server advisorrequest "head / http/1.0"
  • When issuing the dscontrol command from the operating system prompt, you must precede the text with "\" and follow the text with \"". For example: dscontrol server set cluster:port:server advisorrequest "\"head / http/1.0\""

advisorresponse
The advisor response string that the HTTP or HTTPS advisor scans for in the HTTP response. It will only be valid for servers that are advised upon by the HTTP or HTTPS advisor. You must start the HTTP or HTTPS advisor in order for this value to be enabled. See Configuring the HTTP or HTTPS advisor using the request and response (URL) option for more information.
Note:
The advisorresponse applies to Dispatcher and CBR components.
string
Value of the string used by the HTTP or HTTPS advisor. The default is null.
Note:
If a blank is contained within the string --
  • When issuing the command from the dscontrol>> shell prompt, you must place quotes around the string.
  • When issuing the dscontrol command from the operating system prompt, you must precede the text with "\" and follow the text with \"".
down
Mark this server down. This command breaks all active connections to that server and prevents any other connections or packets from being sent to that server.

When the server down command is used to bring a server offline, if the stickytime value is nonzero for that server, existing clients continue to be served by that server until stickytime expires. The server is not taken down until after the stickytime value expires.

remove
Remove this server.
report
Report on this server. The report contains the following information per server: current number of connections per second (CPS), kilobytes transferred in a one second interval (KBPS), total number of connections (Total), number of connections that are in the active state (Active), number of connections that are in the FIN state (FINed), and number of completed connections (Comp).
set
Set values for this server.
status
Show status of the servers.
up
Mark this server up. Dispatcher will now send new connections to that server.

Examples

dscontrol set -- configure server log

Read syntax diagramSkip visual syntax diagram>>-dscontrol--set--+-loglevel--level--------+------------------><
                   '-logsize--+-unlimited-+-'
                              '-size------'
 

loglevel
The level at which the dsserver logs its activities.
level
The default value of loglevel is 0. The range is 0-5. The following are the possible values: 0 is None, 1 is Minimal, 2 is Basic, 3 is Moderate, 4 is Advanced, 5 is Verbose.
logsize
The maximum number of bytes to be logged in the log file.
size
The default value of logsize is 1 MB.

dscontrol status -- display whether the manager and advisors are running

Read syntax diagramSkip visual syntax diagram>>-dscontrol--status-------------------------------------------><
 

Examples

dscontrol subagent -- configure SNMP subagent

Note:
dscontrol subagent command syntax diagrams applies to the Dispatcher component.
Read syntax diagramSkip visual syntax diagram>>-dscontrol--subagent--+-loglevel--level--------------------+-><
                        +-logsize--+-bytes-----+-------------+
                        |          '-unlimited-'             |
                        +-report-----------------------------+
                        +-start--+-------------------------+-+
                        |        '-community_name--logfile-' |
                        +-status-----------------------------+
                        +-stop-------------------------------+
                        '-version----------------------------'
 

loglevel
The level at which the subagent logs its activities to a file.
level
The number of the level (0 to 5). The higher the number, the more information that is written to the manager log. The default is 1. The following are the possible values: 0 is None, 1 is Minimal, 2 is Basic, 3 is Moderate, 4 is Advanced, 5 is Verbose.
logsize
Set the maximum size of the bytes to be logged in the subagent log. The default is 1 MB. When you set a maximum size for the log file, the file will wrap; when the file reaches the specified size, the subsequent entries are written from the top of the file, overwriting the previous log entries. Log size cannot be set smaller than the current size of the log. Log entries are time--stamped so you can tell the order in which they were written. The higher you set the log level, the more carefully you should choose the log size, because you can quickly run out of space when logging at the higher levels.
bytes
The maximum size in bytes for the subagent log file. You can specify either a positive number greater than zero, or the word unlimited. The log file may not reach the exact maximum size before overwriting because the log entries themselves vary in size. The default value is unlimited.
report
Display a statistics snapshot report.
start
Start the subagent.
community_name
The name of the SNMP value of community name that you can use as a security password. The default is public.

For Windows platform: The community name for the operating system is used.

log file
File name to which the SNMP subagent data is logged. Each record in the log is time stamped. The default is subagent.log. The default file is installed in the logs directory. See Appendix C. Sample configuration files. To change the directory where the log files are kept, see Changing the log file paths.
status
Display the current status of all the values in the SNMP subagent that can be set globally and their defaults.
version
Display the current version of the subagent.

Examples