'\" te .\" Copyright (C) 2004, 2009 Sun Microsystems, Inc. All Rights Reserved .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] .TH ipqosconf 1M "18 Dec 2008" "SunOS 5.11" "System Administration Commands" .SH NAME ipqosconf \- configure the IPQoS facility .SH SYNOPSIS .LP .nf \fB/usr/sbin/ipqosconf\fR .fi .LP .nf \fB/usr/sbin/ipqosconf\fR \fB-a\fR \fIconf_file\fR [\fB-vs\fR] .fi .LP .nf \fB/usr/sbin/ipqosconf\fR \fB-c\fR .fi .LP .nf \fB/usr/sbin/ipqosconf\fR \fB-f\fR .fi .LP .nf \fB/usr/sbin/ipqosconf\fR \fB-l\fR .fi .LP .nf \fB/usr/sbin/ipqosconf\fR \fB-L\fR .fi .SH DESCRIPTION .sp .LP The \fBipqosconf\fR utility configures the Quality of Service facility of the Internet Protocol (\fBIP\fR). Only superusers can use this command. .sp .LP Without arguments, \fBipqosconf\fR displays the actual \fBIPQoS\fR configuration. .sp .LP Configuration is not preserved across reboot. You must apply the configuration every time that the machine reboots. To apply the configuration early in the boot phase, you can populate the \fB/etc/inet/ipqosinit.conf\fR file, which is then read from the \fBsvc:/network/initial:default\fR service. .SH OPTIONS .sp .LP The following options are supported: .sp .ne 2 .mk .na \fB\fB-a\fR \fIconf_file\fR\fR .ad .RS 16n .rt Apply the configuration in \fIconf_file\fR. If the \fIconf_file\fR is \fB\(mi\fR, \fBipqosconf\fR reads from standard input. .RE .sp .ne 2 .mk .na \fB\fB-c\fR\fR .ad .RS 16n .rt Populate the boot file with the current configuration. .RE .sp .ne 2 .mk .na \fB\fB-f\fR\fR .ad .RS 16n .rt Flush the configuration. .RE .sp .ne 2 .mk .na \fB\fB-l\fR\fR .ad .RS 16n .rt List the current applied configuration. .RE .sp .ne 2 .mk .na \fB\fB-L\fR\fR .ad .RS 16n .rt List the current configuration in verbose mode. .sp In addition to the information that the \fB-l\fR option provides, the \fB-L\fR option provides filters and classes configured through other means than the \fBiqposconf\fR command. This option also provides the full set of filters that were created by \fBipqosconf\fR by representing a multi-homed host in a configuration file .RE .sp .ne 2 .mk .na \fB\fB-s\fR\fR .ad .RS 16n .rt Log messages to \fBsyslog\fR during an \fB-a\fR operation. .RE .sp .ne 2 .mk .na \fB\fB-v\fR\fR .ad .RS 16n .rt Toggle verbose mode during an \fB-a\fR operation. .sp The \fB-v\fR option causes all messages to go to the console in addition to their normal destination. Messages intended to go to \fBsyslog\fR, because the \fB-s\fR flag is set or because it is a log message, still go to \fBsyslog\fR as well as the console. .RE .SH CONFIGURATION FILE .sp .LP The configuration file is composed of a format version and a succession of configuration (action) blocks. There are different configuration blocks for each type of action that is being configured. .SS "Format Version" .sp .LP The first line of the configuration file specifies the format version contained in the configuration file. .sp .LP The following entry specifies the format version: .sp .in +2 .nf fmt_version \fIx\fR.\fIx\fR .fi .in -2 .sp .LP where \fIx\fR.\fIx\fR is the format version. \fB1.0\fR is the only supported version. .SS "Configuration Blocks" .sp .LP Following the format version, are a succession of configuration (action) blocks that are different for each type of action being configured. A configuration block always has the following structure: .sp .in +2 .nf action { name action_name module module_name params_clause | "" cf_clauses } action_name ::= string module_name ::= ipgpc | dlcosmk | dscpmk | flowacct | tswtclmt | tokenmt params_clause ::= params { parameters params_stats | "" } parameters ::= prm_name_value parameters | "" prm_name_value ::= \fIparam_name\fR \fIparam_value\fR .fi .in -2 .sp .SS "Modules" .sp .LP The \fIparam_name\fR and the types of \fIparam_value\fR are specific to a given module. .sp .in +2 .nf params_stats ::= global_stats boolean cf_clauses ::= class_clause cf_clauses | filter_clause cf_clauses | "" class_clause ::= class { name class_name next_action next_action_name class_stats | "" } class_name ::= string next_action_name ::= string class_stats ::= enable_stats boolean boolean ::= TRUE | FALSE filter_clause ::= filter { name filter_name class class_name parameters } filter_name ::= string .fi .in -2 .sp .sp .LP There must be exactly one configuration block belonging to module \fBipgpc\fR. The action must be named \fBipgpc.classify\fR. All other actions should be reachable from \fBipgpc\fR by way of parameters of type action or the next_action of a class. .sp .LP The set of types that are used for parameters of the different modules are: .sp .in +2 .nf action ::= string protocol ::= 1..255 port ::= 1..65535 uint8 ::= 0..255 uint32 ::= 0..4294967296 int32 ::= -2147483648..2147483648 address ::= ifname ::= enum ::= string | { string_list } boolean ::= TRUE | FALSE integer_array ::= { range_value_list } map_index ::= uint32 address ::= ip_address | ip_node_name user ::= uid | username uid ::= 0..65535 username ::= string string_list ::= string sl_entrys sl_entrys ::= ',' string sl_entrys | "" range_value_list ::= range_value_entry range_value_entrys range_value_entry ::= range ':' integer_array_value range ::= uint32 '-' uint32 integer_array_value ::= string | integer_array_number integer_array_number ::= uint8 | uint32 range_value_entrys ::= ';' range_value_entry range_value_entrys | "" ip_node_name ::= string ip_address ::= v4_address | v6_address v4_address ::= v4_ip_address / v4_cidr_mask | v4_ip_address v4_cidr_mask ::= 1-32 v6_address ::= v6_ip_address / v6_cidr_mask | v6_ip_address v6_cidr_mask ::= 1-128 .fi .in -2 .sp .sp .LP METER module tokenmt configuration syntax: .sp .in +2 .nf red_action_name action yellow_action_name action green_action_name action committed_rate uint32 committed_burst uint32 peak_rate uint32 peak_burst uint32 color_aware boolean color_map integer_array global_stats boolean .fi .in -2 .sp .sp .LP METER module tswtclmt configuration syntax: .sp .in +2 .nf red_action_name action yellow_action_name action green_action_name action committed_rate uint32 peak_rate uint32 window uint32 global_stats boolean .fi .in -2 .sp .sp .LP MARKER module dscpmk configuration syntax: .sp .in +2 .nf next_action action dscp_map int_array dscp_detailed_stats boolean global_stats boolean .fi .in -2 .sp .sp .LP MARKER module dlcosmk configuration syntax: .sp .in +2 .nf next_action action cos map_index global_stats boolean .fi .in -2 .sp .LP CLASSIFIER module ipgpc configuration syntax: .sp .in +2 .nf user user projid int32 if_name ifname direction enum { LOCAL_IN, LOCAL_OUT, FWD_IN, FWD_OUT} protocol protocol dsfield uint8 dsfield_mask uint8 saddr address daddr address sport port dport port priority uint32 precedence uint32 ip_version enum { V4, V6 } global_stats boolean .fi .in -2 .sp .sp .LP ACCOUNTING module flowacct configuration syntax: .sp .in +2 .nf next_action action timer uint32 timeout uint32 max_limit uint32 .fi .in -2 .sp .SS "Types" .sp .ne 2 .mk .na \fB\fIaction\fR\fR .ad .RS 17n .rt A string of characters with a matching action definition. The character string can be up to twenty three characters in length. To allow for spaces the string needs to be enclosed in quotes and cannot span lines. Two special actions are pre-defined and can not have an explicit action definition. The two pre-defined actions are \fBcontinue\fR and \fBdrop\fR. continue causes the packet that is passed to it to continue normal processing. \fBdrop\fR causes the packet that is passed to it to be dropped. .RE .sp .ne 2 .mk .na \fB\fIaddress\fR\fR .ad .RS 17n .rt A machine name or address recognized by \fBgetipnodebyname\fR(3SOCKET). If a machine name is specified, and \fBip_version\fR has been defined, the query is done using that address family. If a machine name is not specified and \fBip_version\fR has not been defined, the query is done using the \fBAI_DEFAULT\fR flag to \fBgetipnodebyname()\fR(\fB\&..AF_INET6..\fR). \fBCIDR\fR address masks following an IP address are allowed. Specify the \fBCIDR\fR address masks as \fB1\fR-\fB32\fR (for \fBv4\fR) or \fB1\fR-\fB128\fR (for \fBv6\fR). \fBCIDR\fR addresses are disallowed for node names. .RE .sp .ne 2 .mk .na \fB\fIenum\fR\fR .ad .RS 17n .rt Either one of the supported values or comma delimited list of support values, enclosed in curly braces. .RE .sp .ne 2 .mk .na \fB\fIifname\fR\fR .ad .RS 17n .rt A non-\fINULL\fR, existing interface name recognized by the \fBSIOGLIFINDEX\fR socket ioctl. .RE .sp .ne 2 .mk .na \fB\fIinteger_array\fR\fR .ad .RS 17n .rt A comma delimited set of \fIrange\fR/\fIvalue\fR pairs, enclosed in curly braces. .sp Specify \fIrange\fR in the format \fIx\fR-\fIy\fR, where \fIx\fR and \fIy\fR are integers that denote the range of array indexes to which the value applies. The minimum value for both \fIx\fR and \fIy\fR is \fB0\fR. The maximum value for \fIx\fR is particular to the parameter. Any array indexes not referred to in the set of ranges are left at their previous value. .RE .sp .ne 2 .mk .na \fB\fImap_index\fR\fR .ad .RS 17n .rt A non-negative integer used as an index into any maps associated with a parameter of this type. .sp The maximum value of this type is dictated by the number of entries in the associated maps. The index starts at \fB0\fR. .RE .sp .ne 2 .mk .na \fB\fIport\fR\fR .ad .RS 17n .rt Either a service name recognized by \fBgetservbyname\fR(3SOCKET) or an integer \fB1\fR-\fB65535\fR. .RE .sp .ne 2 .mk .na \fB\fIprotocol\fR\fR .ad .RS 17n .rt Either a protocol name recognized by \fBgetprotobyname\fR(3SOCKET) or an integer \fB1\fR-\fB255\fR. .RE .sp .ne 2 .mk .na \fB\fIstring\fR\fR .ad .RS 17n .rt A character string. Enclose \fIstring\fR in quotes. \fIstring\fR cannot span multiple lines. .RE .sp .ne 2 .mk .na \fB\fIuser\fR\fR .ad .RS 17n .rt Either a valid user ID or username for the system that is being configured. .RE .SS "Parameters" .sp .LP The configuration file can contain the following parameters .sp .ne 2 .mk .na \fBcolor_aware\fR .ad .RS 23n .rt A value of \fBTRUE\fR or \fBFALSE\fR, indicating whether or not the configured action takes account of the previous packet coloring when classifying. .RE .sp .ne 2 .mk .na \fBcolor_map\fR .ad .RS 23n .rt An integer array that defines which values of the \fBdscp\fR field correspond with which colors for when the \fBcolor_aware\fR parameter is set to \fBTRUE\fR. .RE .sp .ne 2 .mk .na \fBcommitted_burst\fR .ad .RS 23n .rt The committed burst size in bits. .RE .sp .ne 2 .mk .na \fBcommitted_rate\fR .ad .RS 23n .rt The committed rate in bits per second. .RE .sp .ne 2 .mk .na \fBcos\fR .ad .RS 23n .rt The value used to determine the underlying driver level priority applied to the packet which is defined in \fB802.1D\fR. .RE .sp .ne 2 .mk .na \fBdaddr\fR .ad .RS 23n .rt The destination address of the datagram. .RE .sp .ne 2 .mk .na \fBdirection\fR .ad .RS 23n .rt The value used to build a filter matching only part of the traffic. .sp This parameter is of type \fBenum\fR with valid values of \fBLOCAL_IN\fR (local bound traffic), \fBLOCAL_OUT\fR (local sourced traffic), \fBFWD_IN\fR (forwarded traffic entering the system), and \fBFWD_OUT\fR (forwarded traffic exiting the system). .RE .sp .ne 2 .mk .na \fBdport\fR .ad .RS 23n .rt The destination port of the datagram. .RE .sp .ne 2 .mk .na \fBdscp_detailed_stats\fR .ad .RS 23n .rt A value of \fBTRUE\fR or \fBFALSE\fR that determines whether detailed statistics are switched on for this \fBdscp\fR action. .sp Specify \fBTRUE\fR to switch on or \fBFALSE\fR to switch off. .RE .sp .ne 2 .mk .na \fBdscp_map\fR .ad .RS 23n .rt The \fIinteger_array\fR that supplies the values that IP packets with a given \fBdscp\fR value have their dscp re-marked with. .sp The existing value is used to index into the array where the new value is taken from. The array is of size \fB64\fR, meaning valid indexes are \fB0\fR-\fB63\fR and valid values are also \fB0\fR-\fB63\fR. .RE .sp .ne 2 .mk .na \fBdsfield\fR .ad .RS 23n .rt The \fBDS\fR field of the \fBIP\fR datagram header. This is an 8-bit value, with each bit position corresponding with the same one in the header; this enables matches to be done on the CU bits. If you specify this parameter, you must also specify the \fBdsfield_mask\fR parameter. .RE .sp .ne 2 .mk .na \fB\fBdsfield_mask\fR\fR .ad .RS 23n .rt The mask applied to the \fBdsfield\fR parameter to determine the bits against which to match. This is an 8-bit value, with each bit position corresponding with the same one in the \fBdsfield\fR parameter. .RE .sp .ne 2 .mk .na \fBglobal_stats\fR .ad .RS 23n .rt A value of \fBTRUE\fR or \fBFALSE\fR to enable or disable the statistic collection for this action. .RE .sp .ne 2 .mk .na \fBgreen_action_name\fR .ad .RS 23n .rt The action to be executed for packets that are deemed to be green. .RE .sp .ne 2 .mk .na \fBif_name\fR .ad .RS 23n .rt The name of an interface recognized by the \fBSIOGLIFINDEX\fR ioctl. This parameter is of type \fBifname\fR. .RE .sp .ne 2 .mk .na \fBip_version\fR .ad .RS 23n .rt This parameter is of type \fBenum\fR and has valid values of \fBV4\fR and \fBV6\fR. .sp If it is set to \fBV4\fR only then only \fBipv4\fRaddresses are requested for a specified hostname. If it is set to \fBV6\fR, only \fBipv6\fR addresses are returned if there are any, otherwise \fBv4\fR mapped \fBv6\fR addresses are returned. If both \fBV4\fR and \fBV6\fR are specified, or if \fBip_version\fR is not specified, then both \fBipv4\fR and \fBipv6\fR addresses are requested for a specified hostname. .RE .sp .ne 2 .mk .na \fBmax_limit\fR .ad .RS 23n .rt The maximum number of flow entries present at one time in the \fBflowacct\fR actions in the memory resident table. .RE .sp .ne 2 .mk .na \fBnext_action\fR .ad .RS 23n .rt The action to be executed when the current action is complete. .sp This value can be either the name of an action defined in the configuration file, or one of the two special action types: \fBdrop\fR and \fBcontinue\fR. .RE .sp .ne 2 .mk .na \fBpeak_burst\fR .ad .RS 23n .rt The peak burst size, for a two rate meter, or excess burst size, for a single rate meter, in bits. .RE .sp .ne 2 .mk .na \fBpeak_rate\fR .ad .RS 23n .rt The peak rate in bits per second. .RE .sp .ne 2 .mk .na \fBprecedence\fR .ad .RS 23n .rt An integer that is used to order filters. If there are two matching filters that have the same priority value, the one with the lower precedence value is the one matched. This parameter should be used because the order of the filters in a configuration file has no influence on their relative precedence. .RE .sp .ne 2 .mk .na \fBpriority\fR .ad .RS 23n .rt An integer that represents the relative priority of a filter. If there are two matching filters, the one with the higher priority value is the one matched. Multiple filters can have the same priority. .RE .sp .ne 2 .mk .na \fBprojid\fR .ad .RS 23n .rt The project ID of the process sending the data. This value is always \fB-1\fR for received traffic. .RE .sp .ne 2 .mk .na \fBprotocol\fR .ad .RS 23n .rt The Upper Layer Protocol against which this entry is matched. .RE .sp .ne 2 .mk .na \fBred_action_name\fR .ad .RS 23n .rt The action to be executed for packets that are determined to be red. .RE .sp .ne 2 .mk .na \fBsaddr\fR .ad .RS 23n .rt The source address of the datagram. .RE .sp .ne 2 .mk .na \fBsport\fR .ad .RS 23n .rt The source port of the datagram. .RE .sp .ne 2 .mk .na \fBtimeout\fR .ad .RS 23n .rt The timeout in milliseconds after which flows are written to the accounting file. .RE .sp .ne 2 .mk .na \fBtimer\fR .ad .RS 23n .rt The period in milliseconds at which timed-out flows are checked for. .RE .sp .ne 2 .mk .na \fBuser\fR .ad .RS 23n .rt The user ID or username of the process sending the data. This value is always \fB-1\fR for received traffic. .RE .sp .ne 2 .mk .na \fBwindow\fR .ad .RS 23n .rt The window size in ms. .RE .sp .ne 2 .mk .na \fByellow_action_name\fR .ad .RS 23n .rt The action to be executed for packets that are determined to be yellow. .RE .SH SECURITY .sp .LP None. .SH EXAMPLES .LP \fBExample 1 \fRSending All Traffic From eng to the AF 1 Class of Service .sp .LP This example sends all traffic from \fBeng\fR to the \fBAF 1\fR class of service. It is documented in four separate steps: .sp .LP The following step creates a \fBtokenmt\fR action with three outcomes: .sp .in +2 .nf #meter for class 1. action { name AF_CL1 module tokenmt params{ committed_rate 64 committed_burst 75 peak_burst 150 global_stats TRUE red_action_name drop yellow_action_name markAF12 green_action_name markAF11 } } .fi .in -2 .sp .sp .LP The following step creates two \fBdscpmk\fR actions: .sp .in +2 .nf #class 1, low drop precedence. action { name markAF11 module dscpmk params{ dscp_map {0-63:28} dscp_detailed_stats TRUE global_stats TRUE next_action acct1 } } #class 1, medium drop precedence. action { name markAF12 module dscpmk params { dscp_map {0-63:30} dscp_detailed_stats TRUE global_stats TRUE next_action acct1 } } .fi .in -2 .sp .sp .LP The following step creates an accounting action: .sp .in +2 .nf #billing for transmitted class 1 traffic. action { name acct1 module flowacct params { timer 10 timeout 30 global_stats TRUE max_limit 1024 next_action continue } } .fi .in -2 .sp .sp .LP The following step creates an \fBipgpc\fR action: .sp .in +2 .nf #traffic from eng sent, traffic from ebay dropped. action { name ipgpc.classify module ipgpc class { name from_eng enable_stats TRUE next_action AF_CL1 } class { name from_ebay enable_stats TRUE next_action drop } filter { name from_eng saddr eng-subnet class from_eng } filter { name from_ebay saddr ebay-subnet class from_ebay } } .fi .in -2 .sp .SH FILES .sp .ne 2 .mk .na \fB\fB/etc/inet/ipqosinit.conf\fR\fR .ad .sp .6 .RS 4n Contains the \fBIPQoS\fR configuration loaded at boot time. If this file exists, it is read from the \fBnetwork/initial:default\fR service. .RE .sp .ne 2 .mk .na \fB\fB/etc/inet/ipqosconf.1.sample\fR\fR .ad .sp .6 .RS 4n Sample configuration file for an application server .RE .sp .ne 2 .mk .na \fB\fB/etc/inet/ipqosconf.2.sample\fR\fR .ad .sp .6 .RS 4n Sample configuration file that meters the traffic for a specified application .RE .sp .ne 2 .mk .na \fB\fB/etc/inet/ipqosconf.3.sample\fR\fR .ad .sp .6 .RS 4n Sample configuration file that marks the ethernet headers of web traffic with a given user priority .RE .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPEATTRIBUTE VALUE _ Interface StabilityEvolving .TE .SH SEE ALSO .sp .LP \fBsyslog\fR(3C), \fBgetipnodebyname\fR(3SOCKET), \fBgetprotobyname\fR(3SOCKET), \fBgetservbyname\fR(3SOCKET), \fBattributes\fR(5), \fBdlcosmk\fR(7IPP), \fBdscpmk\fR(7IPP), \fBflowacct\fR(7IPP), \fBipgpc\fR(7IPP), \fBipqos\fR(7IPP), \fBtokenmt\fR(7IPP), \fBtswtclmt\fR(7IPP) .SH DIAGNOSTICS .sp .LP \fBipqosconf\fR sends messages to \fBsyslog\fR of facility user, severity notice when any changes are made to the \fBIPQoS\fR configuration. .sp .LP Errors that occur during an \fBipqosconf\fR operation send an error message to the console by default. For the application of a new configuration if the \fB-s\fR option is set then these messages are sent to \fBsyslog\fR as facility user, severity error instead. If the \fB-v\fR option is present during an application then all error and change notificationmessages are sent to the console as well as their default destination.