| Skip Navigation Links | |
| Exit Print View | |
|
man pages section 1M: System Administration Commands Oracle Solaris 11.1 Information Library |
| Skip Navigation Links | |
| Exit Print View | |
|
|
man pages section 1M: System Administration Commands Oracle Solaris 11.1 Information Library |
- establish and manipulate load balancing rules
ilbadm create-rule [-e] [-p] -i vip=value,port=value[,protocol=value]
-m lbalg=value,type=value[,proxy-src=ip-range][,pmask=mask]
[-h hc-name=value[,hc-port=value]]
[-t [conn-drain=N][,nat-timeout=N],[persist-timeout=N]]
-o servergroup=value nameilbadm show-rule [-e|-d] [-f |[-p] -o key[,key ...]] [name ...]
ilbadm delete-rule -a | name ...
ilbadm enable-rule [name ...]
ilbadm disable-rule [name ...]
ilbadm show-statistics [-p] -o field[,field] [-thAdvi]
[-r rulename] | [-s servername] [interval [count]]ilbadm create-servergroup [-s server=hostspec[:portspec...]] groupname
ilbadm delete-servergroup groupname
ilbadm show-servergroup [-s|-f|[-p] -o field[,field]] [[-v] name]
ilbadm enable-server server ...
ilbadm disable-server server ...
ilbadm show-server [[-p] -o field[,field...]] [rulename...]
ilbadm add-server -s server=value[,value ... ] name
ilbadm remove-server -s server=value[,value ... ] name
ilbadm create-healthcheck [-n] -h hc-test=value
[,hc-timeout=value][,hc-count=value][,hc-interval=value] hcnameilbadm delete-healthcheck hcname
ilbadm show-healthcheck [hcname ...]
ilbadm show-hc-result [rule-name]
ilbadm show-nat [count]
ilbadm show-persist [count]
ilbadm export-config filename
ilbadm import-config [-p] filename
The ilbadm command manipulates or displays information about Integrated Load Balancer (ILB) rules using the subcommands described below.
Rule names are case insensitive, but case is preserved as it is entered. Rule names are limited in length to 19 characters. Server names cannot exceed 14 characters.
All parseable output (invoked with the -p option) requires that the fields to be printed or displayed be specified with the -o option. Fields will be displayed in the same order they are encountered on the command line. Multiple fields are separated by the colon (:) character. If a colon or backslash (\) occurs in the displayed string itself, it will be preceded by a backslash. No headers will be displayed for parseable output.
Server IDs are generated by the system when a server is added, using either the create-servergroup or the add-server subcommands.
Server IDs are guaranteed to be unique within the server group. A rule can be attached to only one server group, with the result that serverIDs are unique for rules as well. Note that since more than one rule can attach to the same server group, the server ID alone is not sufficient to indicate a rule.
To be able to distinguish server IDs from hostnames, server IDs are prefixed with a leading underscore (_).
As noted below, the server group and heathcheck entities must be defined before they can be used in the create-rule subcommand.
Following are the ilbadm subcommands, along with their related options and operands. Note that subcommands have a normal and a short form; for example, create-rule and create-rl, saving you from having to type a few additional characters.
Creates a rule name with a set of specified characteristics. incoming and method_attributes are both specified as a set of key=value pairs. If name already exists, the command will fail. If a given tuple (virtual IP address, port(s), and protocol) matches another rule, the command will also fail. create-rule has the following options that control the overall effect of the command:
Enable the create-rule function. The default is that create-rule is disabled.
Create the rule as persistent (sticky). The default is that the rule exists only for the current session.
Keys and values are introduced by one-letter identifiers. These identifiers and their related keys and acceptable values are as follows.
Introduces the matching criteria for incoming packets.
(Virtual) destination IP address
Port number or name, for example, telnet or dns. A port can be specified by port number or symbolic name (as in /etc/services). Port number ranges are also supported.
TCP (the default) or UDP (see /etc/services).
Specifies the keys describing how to handle a packet.
The default is roundrobin, or its short form, rr. Other alternatives are: hash-ip (short form: hip), hash-ip-port (short form: hipp), hash-ip-vip (short form: hipv).
Refers to topology of network. Can be DSR (or dsr or d), NAT (or n or nat), HALF-NAT (or h or half-nat).
Required for full NAT only. Specifies the IP address range to use as the proxy source address range. The range is limited to ten IP addresses.
Optional. Has an alias of: stickiness. Specifies that this rule is to be persistent. The argument is a prefix length in CIDR notation; that is, 0–32 for IPv4 and 0–128 for IPv6. Use the -p option to specify this keyword.
Specifies destination(s) for packets that match the criteria specified by the -i “clause”. This identifier has one well-known argument:
Specify a single server group as target. The server group must already have been created.
The health check option has two arguments:
Specifies the name of a predefined health check method
Specifies the port(s) for the HC test program to check. The value can be keywords ALL or ANY, or a specific port number within the port range of the server group.
Specifies customized timers, in seconds. A value of 0 means to use the system default value. The following are valid modifiers for -t:
If a server's type is NAT or HALF-TYPE, conn-drain is the timeout after which the server's connection state is deleted following the server's removal from a rule. This deletion occurs even if the server is not idle.
The default for TCP is that the connection state remains stable until the connection is gracefully shutdown. The default for UDP is that the connection state remains stable until the connection has been idle for the period nat-timeout.
Applies only to NAT and half-NAT type connections. If such a connection is idle for the nat-timeout period, the connection state will be removed. The default is 120 for TCP and 60 UDP.
When persistent mapping is enabled, if a numeric-only mapping has not been used for persist-timeout seconds, the mapping will be removed. The default is 60.
Note that server group and health check must be defined before they can be used in create-rule.
Remove all information pertaining to rule name. If name does not exist, command will fail. delete-rule has one option:
Delete all rules. (name is ignored.)
Enables a named rule, or all rules, if no name is specified). Enabling rules that are already enabled has no effect.
Disables a named rule, or all rules, if no name is specified. Disabling rules that are already disabled has no effect.
Displays statistics, the output of which is subject to the use of the options described below. The syntax and semantics of this subcommand are modeled on vmstat(1M).
Prepend a timestamp with every sample.
Display the delta over entire interval. The default is changes per second. Cannot be used with the -a option.
Display absolute numbers. That is, numbers since module initialization, rule creation, and server addition. Cannot be used with the -d option.
Display statistics only for the specified rulename. In combination with the -i option, display a line for each server.
Display statistics only for server. In combination with the -i option, display a line for each rule.
Itemize the information displayed by the -r and -s options. These are the only options with which -i is valid. Does not work with the -v option.
Display additional details for droppages. Note that, when the rule name is specified, drops are counted per rule and not per server. Does not work with the -i option.
Display parseable format. Requires use of -o option.
Can be one or more from the list below. field can be uppercase or lowercase.
Packets processed.
Bytes processed.
Unprocessed packets.
Unprocessed bytes.
Packets dropped.
Bytes dropped.
ICMP echo requests processed.
ICMP echo requests dropped.
ICMP fragmentation needed; message processed.
Fragmentation needed; message dropped.
Packets dropped because of out-of-memory condition.
Packets dropped in NAT mode because no source port was available.
Note that when a question mark (?) is displayed as a column entry, it indicates that the proper value cannot be determined, most often because a rule or server was added or deleted.
Note that headers are displayed once for each ten samples. The timestamp format follows the date(1) format for the C locale. Neither the addition nor removal of a rule is detected.
Displays characteristics of the specified rules, or all, if no rule is specified. The subcommand has the following options:
Display only disabled rules.
Display only enabled rules.
Display a full list.
Display output for field(s). Cannot be used with -f option.
Display parsable output in the format described in “Description”. Requires the -o option.
Note that the -o (with or without -p) and -f options are mutually exclusive.
Displays NAT table information. If count is specified, displays count entries from the NAT table. If no count is specified, displays the entire NAT table.
count
No assumptions should be made about the relative positions of elements in consecutive runs of this command. For example, executing show-nat 10 twice is not guaranteed to display the same ten items twice, especially on a busy system.
Display format:
T: IP1 > IP2 >>> IP3 > IP4
These items are described as follows:
The transport protocol used in this entry.
The client's IP address and port.
The VIP and port.
If half NAT mode, the client's IP address and port. If full NAT mode, the NAT'ed client's IP address and port.
The backend server's IP address and port.
Displays persistence table information. If count is specified, displays count entries from the table. If no count is specified, displays the entire persistence table.
No assumptions should be made about the relative positions of elements in consecutive runs of this command. For example, executing show-persist 10 twice is not guaranteed to display the same ten items twice, especially on a busy system.
Display format:
R: IP1 --> IP2
These items are described as follows:
The rule this persistence entry is tied to.
The client's IP address and port.
The backend server's IP address.
Exports the current configuration in a format suitable for re-import using ilbadm import. If no filename is specified, the subcommand writes to stdout.
Reads configuration contents of a file. By default, this overrides any existing configuration. If no filename is specified, the subcommand reads from stdin. This subcommand has the following option:
Preserve existing configuration and do incremental import.
Creates a server group. Additional servers can be added later using the add-server subcommand. Server groups are the only entity that can be used during rule creation to indicate back-end servers. If the specified server group is associated with one or more rules, the server is enabled when it is added. This subcommand has the following option and operands:
Specifies a list of servers to be added to the server group.
hostspec is a hostname or IP address. IPv6 addresses must be enclosed in brackets ([]) to distinguish them from “:portspec”
portspec is a service name or port number. If the port number is not specified, a number in the range 1–65535 is used.
Disable one or more server(s). That is, tell the kernel not to forward traffic to this server. disable-server applies to all rules that are attached to the server group this server is part of.
server is a server ID.
Reenables disabled servers.
Displays servers associated with named rules, or all servers if no rulename is specified. The subcommand has the following options.
Display only the specified fields.
Display fields in parsable format. Requires the -o option.
Deletes a server group.
Lists a server group, or all server groups, if no name is specified. The subcommand has the following options:
Display output for field(s).
Display parsable output in the format described in “Description”. Requires the -o option.
Add specified server(s) to servergroup. See description of create-servergroup for definition of value.
See create-servergroup.
Performing an add-server to a server group immediately after performing a remove-server on that server group might fail because of incomplete connection draining. Refer to the description of the remove-server subcommand for instructions on how to avoid this failure.
Remove specified server(s) from servergroup.
One or more of a server ID.
If a server is being used by a NAT/half-NAT rule, it is recommended that the server be disabled (using disable-server) before removal. By disabling a server, the server enters the connection-draining state. After all of the connections are drained, the server can then be removed by remove-server. If the conn-drain timeout value is set, the connection-draining state will be finished upon conclusion of the timeout period. Note that the default conn-drain timeout is 0, meaning it will keep waiting until a connection is gracefully shut down.
Sets up a health check object for rules to use. All servers associated with a rule are checked using the same test. A health check event of a server consists of one to hc-count number of hc-test executions. If an hc-test's result shows a server to be unresponsive, further hc-test checks are made, up to hc-count invocations, before a server is considered to be down.
The hc-test is performed hc-count times until it succeeds or hc-timeout has expired. For a given rule, all servers are checked using the same test. The tests are as follows:
PING, TCP, external method (script or binary). An external method should be specified with a full path name.
Threshold at which a test is considered failed following interim failures of hc-test. If you kill an hc-test test, the result is considered a failure. The default value is five seconds.
Maximum number of attempts to run hc-test before marking a server as down. The default value is three iterations.
Interval between invocations of hc-test. This value must be greater than hc-timeout times hc-count. The default value is 30 seconds.
The following arguments are passed to external methods:
VIP (literal IPv4 or IPv6 address).
Server IP (literal IPv4 or IPv6 address).
Protocol (UDP, TCP as a string).
The load balance mode, DSR, NAT, HALF_NAT.
Numeric port.
Maximum time (in seconds) the method should wait before returning failure. If the method runs for longer, it can be killed, and the test considered failed.
External methods should return 0 (or the round-trip time to the back end server, in microseconds) for success and -1 if the server is considered down.
Before higher layer health check(s), TCP, UDP, and external tests start, a default ping test is performed first. The higher layer test will not be performed if ping fails. You can turn off the default ping check for these high layer health checks by through use of -n.
Disable default ping test for high layer health check tests.
Delete the named health check object(s) (hcname). If the given health check object is associated with enabled rule(s), deletion of the object will fail.
List the health check information for the specified health check (hcname). If no health check is specified, list information for all existing health checks.
List the health check result for the servers that are associated with rule-name. If rule-name is not given, the health check results for all servers are displayed.
Example 1 Configuring NAT Mode
The following commands create a rule with health check and timers set (port range shifting and session persistence).
# ilbadm create-healthcheck -h hc-test=tcp,hc-timeout=2,hc-count=3, \
hc-interval=10 hc1
# ilbadm create-servergroup -s \
server=60.0.0.10:6000-6009,60.0.0.11:7000-7009 sg1
# ilbadm create-rule -e -i vip=81.0.0.10,port=5000-5009,protocol=tcp \
-m lbalg=rr,type=NAT,proxy-src=60.0.0.101-60.0.0.104, \
pmask=24 \
-h hc-name=hc1 \
-t conn-drain=180,nat-timeout=180,persist-timeout=180 \
-o servergroup=sg1 rule1The following command creates a rule with the default timer values and without health check.
# ilbadm create-servergroup -s server=60.0.0.10 sg1
# lbadm create-rule -e -i vip=81.0.0.10,port=5000 \
-m lbalg=rr,type=NAT,proxy-src=60.0.0.105 \
-o servergroup=sg1 rule1
# ilbadm add-server -e -s server=60.0.0.11sg1
# ilbadm enable-rule rule1Example 2 Configuring Half-NAT Mode
The following command configures half-NAT mode and exemplifies port range collapsing.
# ilbadm create-servergroup sg1
# ilbadm create-rule -e -i vip=81.0.0.10,port=5000-5009 \
-m lbalg=rr,type=h -o servergroup=sg1 rule1
# ilbadm add-server -s server=60.0.0.10:6000,60.0.0.11:7000 sg1Example 3 Configuring DSR Mode and Preparing Two Sets of Rules
The following command establishes two sets of rules to enable load balancing between HTTP and FTP traffic. Note both types of traffic traverse interface 60.0.0.10.
# ilbadm create-servergroup -s servers=60.0.0.9,60.0.0.10 websg
# ilbadm create-servergroup -s servers=60.0.0.10,60.0.0.11 ftpgroup
# ilbadm create-rule -e -i vip=81.0.0.10,port=80 \
-m lbalg=hash-ip-port,type=DSR \
-o servergroup=websg webrule
# ilbadm create-rule -e -i vip=81.0.0.10,port=ftp \
-m lbalg=hash-ip-port,type=DSR,pmask=24 \
-o servergroup=ftpgroup ftprule
# ilbadm create-rule -e -p -i vip=81.0.0.10,port=ftp-data \
-m lbalg=hash-ip-port,type=DSR,pmask=24 \
-o servergroup=ftpgroup ftpdataruleExample 4 Deleting Rule, Server Group, and Health Check
The following commands delete the rule, server group, and health check established in the first example.
# ilbadm ilbadm delete-rule -a # ilbadm delete-servergroup sg1 # ilbadm delete-healthcheck hc1
Example 5 Display a List of Rules
The following command displays a list of rules.
# ilbadm show-rule
RULENAME STATUS LBALG TYPE PROTOCOL VIP PORT
r2 E hash-ip NAT TCP 45.0.0.10 81
r1 E hash-ip NAT TCP 45.0.0.10 80
# ilbadm show-rule -f
RULENAME: rule1
STATUS: E
PORT: 80
PROTOCOL: TCP
LBALG: roundrobin
TYPE: HALF-NAT
PROXY-SRC: --
PERSIST: --
HC-NAME: hc1
HC-PORT: ANY
CONN-DRAIN: 0
NAT-TIMEOUT: 120
PERSIST-TIMEOUT: 60
SERVERGROUP: sg1
VIP: 80.0.0.2
SERVERS: _sg1.0,_sg1.1Example 6 Exporting and Importing Rules
The following commands show how to export rules to and import rules from stdout, and to/from a file.
# ilbadm export-config
create-servergroup ftpgroup
add-server -s server=10.1.1.3:21 ftpgroup
add-server -s server=10.1.1.4:21 ftpgroup
create-servergroup webgroup_v6
add-server -s server=[2000::ff]:80 webgroup_v6
create-rule -e protocol=tcp,VIP=1.2.3.4,port=ftp \
-m lbalg=roundrobin,type=DSR \
-o servergroup=ftpgroup rule4
create-rule protocol=tcp,VIP=2003::1,port=ftp \
-m lbalg=roundrobin,type=DSR \
-o servergroup=ftpgroup6 rule3
create-rule -e protocol=tcp,VIP=2002::1,port=http \
-m lbalg=roundrobin,type=DSR \
-o serverrgroup=webgrp_v6 RULE-allThe following command exports rules to a file.
# ilbadm export-config /tmp/ilbrules
Following this command, /tmp/ilbrules contains the output displayed in the previous command.
The following command imports rules from a file.
# ilbadm import-config /tmp/ilbrules
This command replaces whatever rules were in place with the contents of /tmp/ilbrules.
The following command imports rules from stdin.
# cat /tmp/ilbrules | ilbadm import-config
The effect of this command is identical to the effect of the preceding command.
Example 7 Creating a Single Health Check
The following command creates a single health check.
# ilbadm create-healthcheck -h hc-timeout=3,hc-count=2,hc-interval=8,\
hc-test=tcp hc1Example 8 Listing All Healthchecks
The following command lists all extant health checks.
# ilbadm show-healthcheck HCNAME TIMEOUT COUNT INTERVAL DEF_PING TEST hc1 2 1 10 Y tcp hc2 2 1 10 N /usr/local/bin/probe
Example 9 Deleting a Single Health Check
The following command deletes a single health check.
# ilbadm delete-healthcheck hc1
Example 10 Displaying Statistics
The following command displays statistics at an interval of one seconds, for three iterations.
# ilbadm show-stats -A 1 3 PKT_P BYTES_P PKT_U BYTES_U PKT_D BYTES_D 0 0 0 0 4 196 0 0 0 0 4 196 0 0 0 0 4 196
The following is the command you would use to display statistics in verbose mode at intervals of one second. Output is too wide to fit within the page boundary.
# ilbadm show-stats -v 1
The following command displays statistics for rule r1 at an interval of one second for three iterations.
# ilbadm show-stats -A -r r1 1 3 PKT_P BYTES_P PKT_U BYTES_U PKT_D BYTES_D 0 0 0 0 4 196 0 0 0 0 4 196 0 0 0 0 4 196
The following command displays statistics for rule r1 for each of its servers, for an interval of one second and a count of 3.
# ilbadm show-stats -A -r r1 -i 1 3 SERVERNAME PKT_P BYTES_P _sg1.0 0 0 _sg1.1 0 0 _sg1.2 0 0 _sg1.0 0 0 _sg1.1 0 0 _sg1.2 0 0 _sg1.0 0 0 _sg1.1 0 0 _sg1.2 0 0
The following command displays itemized statistics, with timestamps, for server _sg1.0, at an interval of one second and a count of 3.
# ilbadm show-stats -A -s _sg1.0 -it 1 3 RULENAME PKT_P BYTES_P TIME r1 0 0 2009-07-20:16.10.20 r1 0 0 2009-07-20:16.10.21 r1 0 0 2009-07-20:16.10.22
The following command displays statistics with specific option fields, at an interval of one second and a count of 3.
# ilbadm show-stats -o BYTES_D,TIME 1 3 BYTES_D TIME 196 2009-07-20:16.14.25 0 2009-07-20:16.14.26 0 2009-07-20:16.14.27
Example 11 Displaying Health Check Results
The following command displays the results of a health check.
# ilbadm show-hc-result rule1 RULENAME HCNAME SERVERID STATUS FAIL LAST NEXT RTT rule1 hc1 _sg1.0 dead 6 04:45:17 04:45:30 698 rule1 hc1 _sg1.1 alive 0 04:45:11 04:45:25 260 rule1 hc1 _sg1.2 unreach 6 04:45:17 04:45:30 0
Example 12 Displaying the NAT Table
The following command displays the NAT table.
# ilbadm show-nat 5 UDP: 124.106.235.150.53688>85.0.0.1.1024>>>82.0.0.39.4127>82.0.0.56.1024 UDP: 71.159.95.31.61528> 85.0.0.1.1024>>> 82.0.0.39.4146> 82.0.0.55.1024 UDP: 9.213.106.54.19787> 85.0.0.1.1024>>> 82.0.0.40.4114> 82.0.0.55.1024 UDP: 118.148.25.17.26676> 85.0.0.1.1024>>>82.0.0.40.4112> 82.0.0.56.1024 UDP: 69.219.132.153.56132>85.0.0.1.1024>>>82.0.0.39.4134> 82.0.0.55.1024
In actual ilbadm output, spaces are interspersed for greater readability.
Example 13 Displaying the Persistence Table
The following command displays the persistence table.
# ilbadm show-persist 5 rule2: 124.106.235.150 --> 82.0.0.56 rule3: 71.159.95.31 --> 82.0.0.55 rule3: 9.213.106.54 --> 82.0.0.55 rule1: 118.148.25.17 --> 82.0.0.56 rule2: 69.219.132.153 --> 82.0.0.55
Example 14 Displaying Server Groups
The following command displays basic information about server groups.
# ilbadm show-servergroup sg1: id:sg1.2 35.0.0.4:80 sg1: id:sg1.1 35.0.0.3:80 sg1: id:sg1.0 35.0.0.2:80 sg2: id:sg2.3 35.0.0.5:81 sg2: id:sg2.2 35.0.0.4:81 sg2: id:sg2.1 35.0.0.3:81 sg2: id:sg2.0 35.0.0.2:81
The following command displays all available information about server groups.
# ilbadm show-servergroup -o all sgname serverID minport maxport IP_address sg1 _sg1.0 -- -- 1.1.1.1 sg2 _sg2.1 -- -- 1.1.1.6 sg3 _sg3.0 9001 9001 1.1.1.1 sg3 _sg3.1 9001 9001 1.1.1.2 sg3 _sg3.2 9001 9001 1.1.1.3 sg3 _sg3.3 9001 9001 1.1.1.4 sg3 _sg3.4 9001 9001 1.1.1.5 sg3 _sg3.5 9001 9001 1.1.1.6 sg3 _sg3.6 9001 9001 1.1.1.11 sg3 _sg3.7 9001 9001 1.1.1.12 sg3 _sg3.8 9001 9001 1.1.1.13 sg3 _sg3.9 9001 9001 1.1.1.14 sg3 _sg3.10 9001 9001 1.1.1.15 sg3 _sg3.11 9001 9001 1.1.1.16 sg4 _sg4.0 9001 9006 1.1.1.1 sg4 _sg4.1 9001 9006 1.1.1.6
Example 15 List Servers Associated with a Rule
The following command lists the servers that are associated with a rule.
# ilbadm show-server r1 SERVERID ADDRESS PORT RULENAME STATUS SERVERGROUP _sg1.0 35.0.0.10 80 rule1 E sg1 _sg1.1 35.0.0.11 80 rule1 E sg1 _sg1.2 35.0.0.12 80 rule1 D sg1
See attributes(5) for descriptions of the following attributes:
|
|