Command reference for Site Selector

This chapter describes how to use the following Site Selector sscontrol commands:

You can enter a minimized version of the sscontrol 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 enter sscontrol he f instead of sscontrol help file.

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

sscontrol advisor -- control the advisor

Read syntax diagramSkip visual syntax diagram>>-sscontrol--advisor--+-connecttimeout--name--+-port----------+--seconds-------+-><
                       |                       '-sitename:port-'                |
                       +-interval--name--+-port----------+--seconds-------------+
                       |                 '-sitename:port-'                      |
                       +-list---------------------------------------------------+
                       +-loglevel--name--+-port----------+--level---------------+
                       |                 '-sitename:port-'                      |
                       +-logsize--name--+-port----------+--+-size | unlimited-+-+
                       |                '-sitename:port-'  '-bytes------------' |
                       +-receivetimeout--name--+-port----------+--seconds-------+
                       |                       '-sitename:port-'                |
                       +-report--name--+-port----------+------------------------+
                       |               '-sitename:port-'                        |
                       +-retries--name--+-port----------+--numretries-----------+
                       |                '-sitename:port-'                       |
                       +-start--name--+-port----------+--+----------+-----------+
                       |              '-sitename:port-'  '-log file-'           |
                       +-status--name--+-port----------+------------------------+
                       |               '-sitename:port-'                        |
                       +-stop--name--+-port----------+--------------------------+
                       |             '-sitename:port-'                          |
                       +-timeout--name--+-port----------+-----------------------+
                       |                '-sitename:port-'                       |
                       '-version--name--+-port----------+--seconds--------------'
                                        '-sitename:port-'
 

connecttimeout
Set how long an advisor waits before reporting that a connect to a server fails. For more information, see Advisor connect timeout and receive timeout for servers.
name
The name of the advisor. Possible values include http, https, ftp, sip, ssl, smtp, imap, pop3, ldap, ldaps, nntp, telnet, connect, ping, WLM, and WTE. Names of customized advisors are of the format xxxx, where ADV_xxxx is the name of the class that implements the custom advisor.
port
The number of the port that the advisor is monitoring.
seconds
A positive integer representing the time in seconds that the advisor waits before reporting that a connect to a server has failed. The default is 3 times the value specified for the advisor interval.
interval
Set how often the advisor queries the servers for information.
seconds
A positive integer representing the number of seconds between status requests to the servers. The default is 7.
list
Show list of advisors 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 possible values are:
  • 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 wraps; when the file reaches the specified size, the subsequent entries overwrite 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 must choose the log size, because you can quickly run out of space when logging at the higher levels.
size | unlimited
The maximum size in bytes for the advisor log file. You can specify either a positive number greater than zero, or unlimited. The log file may not reach the exact maximum size before being overwritten because the log entries vary in size. The default value is 1 MB.
receivetimeout
Set how long an advisor waits before reporting that a receive from a server fails. For more information, see Advisor connect timeout and receive timeout for servers.
seconds
A positive integer representing the time in seconds that the advisor waits before reporting that a receive from a server has failed. The default is 3 times the value specified for the advisor interval.
report
Display a report on the state of the advisor.
retries
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:
Advisor Name Protocol Port
Connect n/a user-defined
db2 private 50000
ftp FTP 21
http HTTP 80
https SSL 443
imap IMAP 143
ldap LDAP 389
ldaps SSL 443
nntp NNTP 119
PING PING N/A
pop3 POP3 110
sip SIP 5060
smtp SMTP 25
ssl SSL 443
telnet Telnet 23
name
The advisor name.
sitename:port
The sitename value is optional on the advisor commands; however, the port value is required. If the sitename value is not specified, the advisor starts running on all available sitenames configured. If you specify a sitename, the advisor starts running for only the sitename you specify. Additional sitenames are separated by a plus sign (+).
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 stored, see Changing the log file paths.

You can start only one advisor for each sitename.

status
Display the current status and defaults of all the global values in an advisor.
stop
Stop the advisor.
timeout
Set the number of seconds that the manager considers information from the advisor as valid. If the manager finds that the advisor information is older than this timeout period, the manager does 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 uses that information about the server, even after the advisor information times out.
seconds
A positive number representing the number of seconds or unlimited. The default value is unlimited.
version
Display the current version of the advisor.

Examples

sscontrol file -- manage configuration files

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

delete
Delete the file.
file.ext
A configuration file.

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

appendload
Append a configuration file to the current configuration and load into the Site Selector.
report
Report on the available file or files.
save
Save the current configuration for Site Selector to the file.
Note:
Files are saved into and loaded from the following directories:
  • AIX, HP-UX, Linux, and Solaris operating systems: /opt/ibm/edge/lb/servers/configurations/ss
  • Windows operating systems: <install_root>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
Load a new configuration file into Site Selector. The new configuration file will replace the current configuration.

Examples

sscontrol help -- display or print help for this command

Read syntax diagramSkip visual syntax diagram>>-sscontrol--help--+-advisor----+-----------------------------><
                    +-file-------+
                    +-help-------+
                    +-host-------+
                    +-logstatus--+
                    +-manager----+
                    +-metric-----+
                    +-nameserver-+
                    +-rule-------+
                    +-server-----+
                    +-set--------+
                    +-sitename---+
                    '-status-----'
 

Examples

sscontrol logstatus -- display server log settings

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

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

sscontrol manager -- control the manager

Read syntax diagramSkip visual syntax diagram>>-sscontrol--manager--+-interval--seconds----------------------+-><
                       +-loglevel--level------------------------+
                       +-logsize--+-unlimited-+-----------------+
                       |          '-bytes-----'                 |
                       +-metric set--+-loglevel--level--------+-+
                       |             '-logsize--+-unlimited-+-' |
                       |                        '-bytes-----'   |
                       +-reach set--+-interval--seconds------+--+
                       |            +-loglevel--level--------+  |
                       |            '-logsize--+-unlimited-+-'  |
                       |                       '-bytes-----'    |
                       +-report--sitename+sn2+...+snN-----------+
                       +-restart--message-----------------------+
                       +-sensitivity--weight--------------------+
                       +-smoothing--smoothing index-------------+
                       +-start--+----------------------+--------+
                       |        '-logfile--metric_port-'        |
                       +-status---------------------------------+
                       +-stop-----------------------------------+
                       '-version--------------------------------'
 

interval
Set how often the manager updates the weights of the servers.
seconds
A positive number in seconds that represents how often the manager updates weights. 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 possible values are:
  • 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 wraps; 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 must 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 unlimited. The log file may not reach the exact maximum size before being overwritten because the log entries 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 positive number greater than zero, or unlimited. The default logsize is 1.
reach set
Sets the interval, loglevel, and logsize for the reach advisor.
report
Display a statistics snapshot report.
sitename
The sitename you want displayed in the report. This is an unresolvable hostname that the client will request. The sitename must be a fully qualified domain name.
Note:
Additional sitenames 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 0 to 100 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 causes server weights to change less drastically as network conditions change. A lower index causes 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 uses 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 and defaults of all the global values in the manager.
stop
Stop the manager.
version
Display the current version of the manager.

Examples

sscontrol metric -- configure system metrics

Read syntax diagramSkip visual syntax diagram>>-sscontrol--metric--+-add--sitename+sn2+...+snN:metric+metric1+...+metricN--------------+-><
                      +-remove--sitename+sn2+...+snN:metric+metric1+...+metricN-----------+
                      +-proportions--sitename+sn2+...+snN:proportion1 prop2 prop3...propN-+
                      '-status--sitename+sn2+...+snN metric+metric1+...+metricN-----------'
 

add
Add the specified metric.
sitename
The configured sitename. Additional sitenames 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
Proportions determines the significance of each metric as compared to the others when they are combined into a single system load for a server.
status
Display the current server values for this metric.

Examples

sscontrol nameserver -- control the NameServer

Read syntax diagramSkip visual syntax diagram>>-sscontrol--nameserver--+-start--+----------------------+-+--><
                          |        '-bindaddress--address-' |
                          +-stop----------------------------+
                          '-status--------------------------'
 

start
Starts the name server.
bindaddress
Starts the nameserver bound to the specified address. The nameserver responds only to a request destined for this address.
address
An address (IP or symbolic) configured on the Site Selector machine.
stop
Stops the name server.
status
Displays the status of the name server.

sscontrol rule -- configure rules

Read syntax diagramSkip visual syntax diagram>>-sscontrol--rule--+-add--sitename+sn2+...+snN:rule+r2+...+rN--type--value--| value |--| opts |-+-><
                    +-dropserver--sitename+sn2+...+snN:rule+r2+...+rN--server+s2+...+snN---------+
                    +-remove--sitename+sn2+...+snN:rule+r2+...+rN--------------------------------+
                    +-set--sitename+sn2+...+snN:rule+r2+...+rN--| value |--| opts |--------------+
                    +-status--sitename+sn2+...+snN:rule+r2+...+rN--------------------------------+
                    '-useserver--sitename+sn2+...+snN:rule+r2+...+rN--server+s2+...+snN----------'
 
opts:
 
|--+---------------------------------+--------------------------|
   +-beginrange--low--endrange--high-+
   +-priority--value-----------------+
   '-metricname--value---------------'
 

add
Add this rule to a sitename.
sitename
An unresolvable hostname that the client will request. The sitename must be a fully qualified domain name. Additional sitenames 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.
metricall
The rule is based on the current metric value for all the servers in the server set.
metricavg
The rule is based on the average of the current metric values for all the servers in the server set.
time
The rule is based on the time of day.
true
This rule is always true. Think of it as an else statement in programming logic.
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.
metricall
An integer. The default is 100.
metricavg
An integer. The default is 100.
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.
metricall
An integer. The default is 2 to the 32nd power minus 1.
metricavg
An integer. 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, Site Selector sets 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 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).
metricname
Name of the metric measured for a rule.
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.
Note:
Additional sitenames are separated by a plus sign (+).
remove
Remove one or more rules, separated from one another by plus signs.
set
Set values for this rule.
status
Display all the values of one or more rules.
useserver
Insert server into a rule set.

Examples

sscontrol server -- configure servers

Read syntax diagramSkip visual syntax diagram>>-sscontrol--server--+-add--sitename+sn2+...+snN:server+s2+...+sN--+------------------------+-+-><
                      |                                             +-metricaddress--address-+ |
                      |                                             '-weight--value----------' |
                      +-down--sitename+sn2+...+snN:server+s2+...+sN----------------------------+
                      +-remove--sitename+sn2+...+snN:server+s2+...+sN--------------------------+
                      +-set--sitename+sn2+...+snN:server+s2+...+sN--+------------------------+-+
                      |                                             +-metricaddress--address-+ |
                      |                                             '-weight--value----------' |
                      +-status--sitename+sn2+...+snN:server+s2+...+sN--------------------------+
                      '-up--sitename+sn2+...+snN:server+s2+...+sN------------------------------'
 

add
Add this server.
sitename
An unresolvable hostname that the client requests. The sitename must be a fully qualified domain name. Additional sitenames are separated by a plus sign (+).
server
The IP address of the TCP server machine as either a symbolic name or in IP address format.
Note:
Additional servers are separated by a plus sign (+).
metricaddress
The address of the metric server.
address
The address of the server as either a symbolic name or in IP address format.
weight
A number from 0-100 (not to exceed the specified sitename's maximum weightbound value) representing the weight for this server. Setting the weight to zero will prevent any new requests from being sent to the server. The default is one-half the specified sitename’s maximum weightbound value. If the manager is running, this setting will be quickly overwritten.
value
The server weight value.
down
Mark this server down. This command prevents any other request from being resolved to that server.
remove
Remove this server.
set
Set values for this server.
status
Show status of the servers.
up
Mark this server up. Site Selector will now resolve new requests to that server.

Examples

sscontrol set -- configure server log

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

loglevel
The level at which the ssserver logs its activities.
level
The default value of loglevel is 0. The possible values are:
  • 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.

sscontrol sitename -- configure a sitename

Read syntax diagramSkip visual syntax diagram>>-sscontrol--sitename--+-add--sitename+sn2+...+snN--+----------------------------------------+-+-><
                        |                            +-cachelife--value-----------------------+ |
                        |                            +-networkproximity--yes | no-------------+ |
                        |                            +-proportions--cpu--memory--port--metric-+ |
                        |                            +-proximitypercentage--value-------------+ |
                        |                            +-stickytime--time-----------------------+ |
                        |                            +-ttl--time------------------------------+ |
                        |                            +-waitforallresponses--yes | no----------+ |
                        |                            '-weightbound--weight--------------------' |
                        +-remove--sitename+sn2+...+snN------------------------------------------+
                        +-set--sitename+sn2+...+snN--+----------------------------------------+-+
                        |                            +-cachelife--value-----------------------+ |
                        |                            +-networkproximity--yes | no-------------+ |
                        |                            +-proportions--cpu--memory--port--metric-+ |
                        |                            +-proximitypercentage--value-------------+ |
                        |                            +-stickytime--time-----------------------+ |
                        |                            +-ttl--time------------------------------+ |
                        |                            +-waitforallresponses--yes | no----------+ |
                        |                            '-weightbound--weight--------------------' |
                        '-status--sitename+sn2+...+snN------------------------------------------'
 

add
Add a new sitename.
sitename
An irresolvable host name, requested by the client. Additional sitenames are separated by a plus sign (+).
cachelife
The amount of time a proximity response is valid and saved in the cache. The default is 1800. See Using the Network Proximity feature for more information.
value
A positive number representing the number of seconds a proximity response is valid and saved in the cache.
networkproximity
Determines each server's network proximity to the requesting client. Use this proximity response in the load balancing decision. Set the proximity on or off. See Using the Network Proximity feature for more information.
value
The choices are yes or no. The default is no, which means network proximity is turned off.
proportions
Set the proportion of importance for cpu, memory, port (information from any advisors), and system metrics for the Metric Server that are used by the manager to set server weights. Each of these values is expressed as a percentage of the total and the total is always 100.
cpu
The percentage of CPU in use on each load balanced server machine (input from Metric Server agent).
memory
The percentage of memory in use (input from Metric Server agent) on each load balanced server
port
The input from advisors listening on the port.
system
The input from the Metric Server.
proximitypercentage
Sets the importance of the proximity response versus the health of the server (manager weight). See Using the Network Proximity feature for more information.
value
The default is 50.
stickytime
The interval during which a client will receive the same server ID previously returned for the first request. The default value of stickytime is 0, which signifies that the sitename is not sticky.
time
A positive, non-zero number representing the number of seconds during which the client receives the same server ID previously returned for the first request.
ttl
Sets the time to live. This indicates how long another nameserver will cache the resolved response. The default value is 5.
value
A positive number representing the number of seconds the nameserver will cache the resolved response.
waitforallresponses
Sets whether to wait for all proximity responses from the servers before responding to the client request. See Using the Network Proximity feature for more information.
value
The choices are yes or no. The default is yes.
weightbound
A number representing the maximum weight that can be set for servers on this sitename. The weightbound value set for the sitename may be overridden for individual servers using server weight. The default value of sitename weightbound is 20.
weight
The value of weightbound.
set
Set the properties of the sitename.
remove
Remove this sitename.
status
Show current status of a specific sitename.

Examples

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

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

Examples