| .\" -*- nroff -*- |
| .\" Copyright 2007-2009 by Chelsio Communications. All Rights Reserved. |
| .TH COP "8" "August 2009" "cop 1.3" "Linux" |
| .SH "NAME" |
| cop \- compile offload policies |
| .SH "SYNOPSIS" |
| .B cop |
| [\fB\-dht\fR] [\fB\-o\fR \fIout_file\fR] [\fIpolicy_file\fR] |
| .SH "DESCRIPTION" |
| .BI cop |
| compiles offload policies into a simple program form that can be loaded into |
| the kernel and interpreted. These offload policies are used to determine |
| the \fIsettings\fR to be used for various connections based on matching |
| \fIfilter\fR specifications (see \fBFORMAT OF OFFLOAD POLICIES\fR below). |
| .PP |
| Policy rules are read either from \fIpolicy_file\fR or from standard input |
| if no file is supplied. Rules have priority in the order of their |
| appearance so list higher priority rules first. The first rule whose filter |
| matches a new connection is used to establish the settings for that |
| connection. |
| .SH "OPTIONS" |
| .TP |
| \fB\-d\fR |
| Enables debugging mode. Among other things this prints out a human-readable |
| version of the generated program. |
| .PP |
| .TP |
| \fB\-h\fR |
| Show usage information. |
| .PP |
| .TP |
| \fB\-o\fR \fIout_file\fR |
| Save the generated program into \fIout_file\fR. The program is not saved if |
| this option is omitted. |
| .PP |
| .TP |
| \fB\-t\fR |
| After generating the program enter test mode. In this mode the user is asked |
| to enter values for various TCP connection properties to try out the policies. |
| .PP |
| .SH "FORMAT OF OFFLOAD POLICIES" |
| Offload policies are specified in an ASCII file consisting of an unlimited |
| numbed of policy rules. Blank lines are ignored and comments are introduced by |
| \fB#\fR. Each rule consists of a filter part, which determines |
| what connections the policy applies to, and a settings part, which determines |
| whether matching connections will be offloaded and, if so, with what settings. |
| The two parts are separated by \fB=>\fR, i.e., the general form of a rule is |
| .PP |
| .RS |
| \fIfilter\fR \fB=>\fR \fIsettings\fR. |
| .RE |
| .PP |
| Filter expressions, which resemble tcpdump(1) patterns, are made up of |
| primary expressions. The following primary expressions are recognized: |
| .TP |
| [\fIqual\fR] \fBhost\fR \fIipaddr\fR |
| \fIipaddr\fR is an IP address and \fIqual\fR is one of \fBsrc\fR, |
| \fBdst\fR, \fBsrc or dst\fR, or \fBsrc and dst\fR. If no qualifier is supplied |
| it defaults to \fBsrc or dst\fR. \fBdest\fR is a synonym for \fBdst\fR. |
| Matches connections with the given source/destination addresses. |
| .TP |
| [\fIqual\fR] \fBnet\fR \fInetaddr\fR |
| \fInetaddr\fR is an IP network address in either CIDR notation |
| (\fBaddr\fR/\fBprefix\fR) or \fBaddr mask prefix\fR, and \fIqual\fR is as for |
| \fBhost\fR. Matches connections from/to the given network. |
| .TP |
| [\fIqual\fR] \fBport\fR \fIport\fR |
| \fIport\fR is a TCP port number or name listed in \fB/etc/services\fR, and |
| \fIqual\fR is as for \fBhost\fR. Matches connections with the given |
| source/destination ports. |
| .TP |
| \fBvers\fR \fIipversion\fR |
| matches connections of the given IP version. |
| .TP |
| \fBtos\fR \fIvalue\fR |
| matches connections with the given 8-bit TOS value. |
| .TP |
| \fBdscp\fR \fIvalue\fR |
| matches connections with the given 6-bit DSCP value. |
| .TP |
| \fBvlan\fR \fIvalue\fR |
| matches connections using the given VLAN tag (0-4095). |
| .TP |
| \fBlisten\fR |
| matches listening sockets. |
| .TP |
| \fBaopen\fR |
| matches active opens. |
| .TP |
| \fBpopen\fR |
| matches passive opens. |
| .TP |
| \fBmark\fR \fIvalue\fR |
| matches sockets with the given mark (as specified with the socket option |
| SO_MARK). |
| .PP |
| Primitive expressions can be combined with the operators \fBnot\fR, \fBand\fR, |
| \fBor\fR, and the ternary operator \fB?:\fR, listed in order of decreasing |
| precedence. \fB!\fR, \fB&&\fR, and \fB||\fR, are synonyms for the first three, |
| respectively. Expressions can be parenthesized with \fB()\fR. |
| |
| All primitives that accept a value take an optional comparison operator \fB==\fR |
| or \fB!=\fR. The default is \fB==\fR. Primitives with integer values |
| additionally can use inequality comparison operators \fB<\fR, \fB<=\fR, \fB>\fR, |
| and \fB>=\fR. These primitives also allow an optional mask of the form |
| \fB&\fR \fImask\fR before the relational operator. |
| |
| Note that you can omit a lot of this syntax, e.g., \fBand\fR can often be left |
| out and repetitive qualifiers can be combined (see the examples below). |
| |
| As a special case the filters \fB\-\fR, \fBall\fR, and \fBany\fR match all |
| connections. |
| |
| Offload settings determine whether connections are offloaded and some per |
| connection properties of those offloaded. The following settings can be |
| specified: |
| .TP |
| \fBoffload\fR |
| specifies that connections should be offloaded. It can be preceded by |
| \fBnot\fR or its synonym \fB!\fR to disable offloading. |
| .TP |
| \fBddp\fR |
| selects Direct Data Placement for a connection. |
| Preceded by \fBnot\fR or \fB!\fR it disables DDP. |
| .TP |
| \fBtstamp\fR or \fBtimestamp\fR |
| specifies that a connection should negotiate TCP timestamps. |
| Preceded by \fBnot\fR or \fB!\fR it disables timestamps. |
| .TP |
| \fBsack\fR |
| specifies that a connection should negotiate TCP SACK. |
| Preceded by \fBnot\fR or \fB!\fR it disables SACK. |
| .TP |
| \fBbind\fR \fIqueuenum\fR |
| binds connections to the specified queue. The special value \fBrandom\fR |
| selects a random queue. The special value \fBcpu\fR selects a queue determined |
| by the CPU id where the active or passive open is processed. |
| .TP |
| \fBclass\fR \fInum\fR |
| associates connections with the given scheduling class. |
| .TP |
| \fBcong\fR \fIcongestion_algorithm\fR |
| specifies that connection should use the given TCP congestion algorithm. |
| Possible values are \fBreno\fR, \fBtahoe\fR, \fBnewreno\fR, and \fBhighspeed\fR. |
| .PP |
| Note that all settings keywords are logically orthogonal \(em i.e. each |
| setting desired must be explicitly specified. For instance, in order to |
| specify that a rule should result in an offloaded DDP connection, both the |
| \fBoffload\fR and \fBddp\fR keywords nust be used. Also note that specific |
| hardware may not (and probably won't) support all possible settings |
| combinations, or may have different valid ranges, etc. \fBoffload\fR is |
| always understood. If no settings are specified \fB!offload\fR is assumed. |
| Consult the documentation for the hardware to determine which settings |
| combinations are allowed. |
| .SH ADAPTER-SPECIFIC NOTES: CHELSIO T3 |
| \fBChelsio T3-based adapters\fR do not support offloading IPv6 connections. |
| Only offloading adapters (those with TCAMs) can support offloading; thus |
| attempts to set offload policies on non-offload adapters will be rejected. |
| The parameter to the \fBclass\fR setting is limited to \fB8/nports\fR. |
| Policy rules involving \fBtstamp\fR and \fBsack\fR are not supported. |
| .PP |
| By default, absent a loaded Connection Offload Policy (COP), the Linux |
| \fBT3\fR offload driver module, \fBt3_tom\fR, automatically offloads all |
| connections and listeners of which it is capable. This leads to a "Chicken |
| and Egg" problem where \fBt3_tom\fR is loaded and starts offloading |
| connections and listeners \fIbefore\fR a COP can be loaded. |
| .PP |
| In order to address this issue, the \fBt3_tom\fR driver module supports a |
| \fBcop_managed_offloading\fR module parameter which controls its default |
| offloading behavior. When the \fBt3_tom\fR driver module is loaded into the |
| kernel with \fBcop_managed_offloading\fR set to a non-zero value, all |
| connection offloading decisions are managed under the sole purview of a COP. |
| As a consequence, if there is no COP loaded, then no connections, listeners, |
| etc. will be offloaded. And thus, when \fBt3_tom\fR is first loaded and |
| \fBcop_managed_offloadig\fR is set, no offloading will be done until the |
| first COP is loaded. See \fBmodprobe.conf\fR(5) for information on how to |
| establish default Linux module load parameters. |
| .PP |
| Note that loading a new COP cannot retroactively revoke offloading decisions |
| made by previous COPs. Think of this as \fIStare decisis\fR. In order to |
| reverse earlier offload decisions, the existing offloaded services must be |
| restarted with the new COP in effect. |
| .SH EXAMPLES |
| .B src host 102.50.50.1 => offload bind 0 |
| |
| .B dst host 167.32.1.3 => !offload |
| |
| .B host 68.3.127.238 or 68.3.127.239 => offload bind 7 !ddp class 1 |
| |
| .B dst net 168.192/16 or 121.101.2/24 => offload class 2 cong highspeed |
| |
| .B src host 102.60.60.3 and dst net 10.10/16 => !offload |
| |
| .B dst port 22 or 23 => offload bind 3 |
| |
| .B dst port http and dst net 10.4/16 => offload class 4 bind 6 |
| |
| .B src and dst port 80 => not offload |
| |
| .B vers 6 => !offload |
| |
| .B listen and (src port http or nfs) => offload |
| |
| .B listen and src port & 0xfc00 = 0 => offload |
| |
| .B dst port nfs && dscp != 0 && popen=> offload class 3 !!!ddp |
| |
| .B dst net 168.192/16 and mark 12 => offload |
| .SH BUGS |
| None known. |
| .SH "SEE ALSO" |
| .BR modprobe.conf (5), |
| .BR tcpdump (8). |
| .SH "AUTHOR" |
| .B cop |
| was written by Dimitris Michailidis. |
| .SH "AVAILABILITY" |
| .B cop |
| is available from Chelsio Communications. |
