path: root/usr/src/man/man8/ipqosconf.8

'\" 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 8 "Dec 18, 2008"
.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
.na
\fB\fB-a\fR \fIconf_file\fR\fR
.ad
.RS 16n
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
.na
\fB\fB-c\fR\fR
.ad
.RS 16n
Populate the boot file with the current configuration.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.RS 16n
Flush the configuration.
.RE

.sp
.ne 2
.na
\fB\fB-l\fR\fR
.ad
.RS 16n
List the current applied configuration.
.RE

.sp
.ne 2
.na
\fB\fB-L\fR\fR
.ad
.RS 16n
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
.na
\fB\fB-s\fR\fR
.ad
.RS 16n
Log messages to \fBsyslog\fR during an \fB-a\fR operation.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.RS 16n
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       ::=    <see the description section>
ifname        ::=    <interface name recognized by SIOGLIFINDEX ioctl>
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
<if present this signifies that this will be a two rate meter, not
   a single rate meter>
peak_burst              uint32
<this is the 'peak' burst size for a two rate meter, but
   the 'excess' burst size for a single rate meter>
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
.na
\fB\fIaction\fR\fR
.ad
.RS 17n
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
.na
\fB\fIaddress\fR\fR
.ad
.RS 17n
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
.na
\fB\fIenum\fR\fR
.ad
.RS 17n
Either one of the supported values or comma delimited list of support values,
enclosed in curly braces.
.RE

.sp
.ne 2
.na
\fB\fIifname\fR\fR
.ad
.RS 17n
A non-\fINULL\fR, existing interface name recognized by the \fBSIOGLIFINDEX\fR
socket ioctl.
.RE

.sp
.ne 2
.na
\fB\fIinteger_array\fR\fR
.ad
.RS 17n
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
.na
\fB\fImap_index\fR\fR
.ad
.RS 17n
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
.na
\fB\fIport\fR\fR
.ad
.RS 17n
Either a service name recognized by \fBgetservbyname\fR(3SOCKET) or an integer
\fB1\fR-\fB65535\fR.
.RE

.sp
.ne 2
.na
\fB\fIprotocol\fR\fR
.ad
.RS 17n
Either a protocol name recognized by \fBgetprotobyname\fR(3SOCKET) or an
integer \fB1\fR-\fB255\fR.
.RE

.sp
.ne 2
.na
\fB\fIstring\fR\fR
.ad
.RS 17n
A character string. Enclose \fIstring\fR in quotes. \fIstring\fR cannot span
multiple lines.
.RE

.sp
.ne 2
.na
\fB\fIuser\fR\fR
.ad
.RS 17n
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
.na
\fBcolor_aware\fR
.ad
.RS 23n
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
.na
\fBcolor_map\fR
.ad
.RS 23n
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
.na
\fBcommitted_burst\fR
.ad
.RS 23n
The committed burst size in bits.
.RE

.sp
.ne 2
.na
\fBcommitted_rate\fR
.ad
.RS 23n
The committed rate in bits per second.
.RE

.sp
.ne 2
.na
\fBcos\fR
.ad
.RS 23n
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
.na
\fBdaddr\fR
.ad
.RS 23n
The destination address of the datagram.
.RE

.sp
.ne 2
.na
\fBdirection\fR
.ad
.RS 23n
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
.na
\fBdport\fR
.ad
.RS 23n
The destination port of the datagram.
.RE

.sp
.ne 2
.na
\fBdscp_detailed_stats\fR
.ad
.RS 23n
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
.na
\fBdscp_map\fR
.ad
.RS 23n
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
.na
\fBdsfield\fR
.ad
.RS 23n
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
.na
\fB\fBdsfield_mask\fR\fR
.ad
.RS 23n
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
.na
\fBglobal_stats\fR
.ad
.RS 23n
A value of \fBTRUE\fR or \fBFALSE\fR to enable or disable the statistic
collection for this action.
.RE

.sp
.ne 2
.na
\fBgreen_action_name\fR
.ad
.RS 23n
The action to be executed for packets that are deemed to be green.
.RE

.sp
.ne 2
.na
\fBif_name\fR
.ad
.RS 23n
The name of an interface recognized by the \fBSIOGLIFINDEX\fR ioctl. This
parameter is of type \fBifname\fR.
.RE

.sp
.ne 2
.na
\fBip_version\fR
.ad
.RS 23n
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
.na
\fBmax_limit\fR
.ad
.RS 23n
The maximum number of flow entries present at one time in the \fBflowacct\fR
actions in the memory resident table.
.RE

.sp
.ne 2
.na
\fBnext_action\fR
.ad
.RS 23n
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
.na
\fBpeak_burst\fR
.ad
.RS 23n
The peak burst size, for a two rate meter, or excess burst size, for a single
rate meter, in bits.
.RE

.sp
.ne 2
.na
\fBpeak_rate\fR
.ad
.RS 23n
The peak rate in bits per second.
.RE

.sp
.ne 2
.na
\fBprecedence\fR
.ad
.RS 23n
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
.na
\fBpriority\fR
.ad
.RS 23n
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
.na
\fBprojid\fR
.ad
.RS 23n
The project ID of the process sending the data. This value is always \fB-1\fR
for received traffic.
.RE

.sp
.ne 2
.na
\fBprotocol\fR
.ad
.RS 23n
The Upper Layer Protocol against which this entry is matched.
.RE

.sp
.ne 2
.na
\fBred_action_name\fR
.ad
.RS 23n
The action to be executed for packets that are determined to be red.
.RE

.sp
.ne 2
.na
\fBsaddr\fR
.ad
.RS 23n
The source address of the datagram.
.RE

.sp
.ne 2
.na
\fBsport\fR
.ad
.RS 23n
The source port of the datagram.
.RE

.sp
.ne 2
.na
\fBtimeout\fR
.ad
.RS 23n
The timeout in milliseconds after which flows are written to the accounting
file.
.RE

.sp
.ne 2
.na
\fBtimer\fR
.ad
.RS 23n
The period in milliseconds at which timed-out flows are checked for.
.RE

.sp
.ne 2
.na
\fBuser\fR
.ad
.RS 23n
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
.na
\fBwindow\fR
.ad
.RS 23n
The window size in ms.
.RE

.sp
.ne 2
.na
\fByellow_action_name\fR
.ad
.RS 23n
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
.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
.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
.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
.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(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Evolving
.TE

.SH SEE ALSO
.sp
.LP
.BR syslog (3C),
.BR getipnodebyname (3SOCKET),
.BR getprotobyname (3SOCKET),
.BR getservbyname (3SOCKET),
.BR dlcosmk (4IPP),
.BR dscpmk (4IPP),
.BR flowacct (4IPP),
.BR ipgpc (4IPP),
.BR ipqos (4IPP),
.BR tokenmt (4IPP),
.BR tswtclmt (4IPP),
.BR attributes (7)
.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.