contrib/ipfilter/ipsend/ipsend.5

   1 .\" $FreeBSD$
   2 .TH IPSEND 5
   3 .SH NAME
   4 ipsend \- IP packet description language
   5 .SH DESCRIPTION
   6 The \fBipsend\fP program expects, with the \fB-L\fP option, input to be a
   7 text file which fits the grammar described below.  The purpose of this
   8 grammar is to allow IP packets to be described in an arbitary way which
   9 also allows encapsulation to be so done to an arbitary level.
  10 .SH GRAMMAR
  11 .LP
  12 .nf
  13 line ::= iface | arp | send | defrouter | ipv4line .
  14
  15 iface ::= ifhdr "{" ifaceopts "}" ";" .
  16 ifhdr ::= "interface" | "iface" .
  17 ifaceopts ::= "ifname" name | "mtu" mtu | "v4addr" ipaddr |
  18               "eaddr" eaddr .
  19
  20 send ::= "send" ";" | "send" "{" sendbodyopts "}" ";" .
  21 sendbodyopts ::= sendbody [ sendbodyopts ] .
  22 sendbody ::= "ifname" name | "via" ipaddr .
  23
  24 defrouter ::= "router" ipaddr .
  25
  26 arp ::= "arp" "{" arpbodyopts "}" ";" .
  27 arpbodyopts ::= arpbody [ arpbodyopts ] .
  28 arpbody ::= "v4addr" ipaddr | "eaddr" eaddr .
  29
  30 bodyline ::= ipv4line | tcpline | udpline | icmpline | dataline .
  31
  32 ipv4line ::= "ipv4" "{" ipv4bodyopts "}" ";" .
  33 ipv4bodyopts ::= ipv4body [ ipv4bodyopts ] | bodyline .
  34 ipv4body ::= "proto" protocol | "src" ipaddr | "dst" ipaddr |
  35              "off" number | "v" number | "hl" number| "id" number |
  36              "ttl" number | "tos" number | "sum" number | "len" number |
  37              "opt" "{" ipv4optlist "}" ";" .
  38 ipv4optlist ::= ipv4option [ ipv4optlist ] .
  39 ipv4optlist = "nop" | "rr" | "zsu" | "mtup" | "mtur" | "encode" | "ts" |
  40               "tr" | "sec" | "lsrr" | "e-sec" | "cipso" | "satid" |
  41               "ssrr" | "addext" | "visa" | "imitd" | "eip" | "finn" |
  42               "secclass" ipv4secclass.
  43 ipv4secclass := "unclass" | "confid" | "reserv-1" | "reserv-2" |
  44                 "reserv-3" | "reserv-4" | "secret" | "topsecret" .
  45
  46 tcpline ::= "tcp" "{" tcpbodyopts "}" ";" .
  47 tcpbodyopts ::= tcpbody [ tcpbodyopts ] | bodyline .
  48 tcpbody ::= "sport" port | "dport" port | "seq" number | "ack" number |
  49             "off" number | "urp" number | "win" number | "sum" number |
  50             "flags" tcpflags | data .
  51
  52 udpline ::= "udp" "{" udpbodyopts "}" ";" .
  53 udpbodyopts ::= udpbody [ udpbodyopts ] | bodyline .
  54 udpbody ::= "sport" port | "dport" port | "len" number | "sum" number |
  55             data .
  56
  57 icmpline ::= "icmp" "{" icmpbodyopts "}" ";" .
  58 icmpbodyopts ::= icmpbody [ icmpbodyopts ] | bodyline .
  59 icmpbody ::= "type" icmptype [ "code" icmpcode ] .
  60 icmptype ::= "echorep" | "echorep" "{" echoopts "}" ";" | "unreach" |
  61              "unreach" "{" unreachtype "}" ";" | "squench" | "redir" |
  62              "redir" "{" redirtype "}" ";" | "echo" "{" echoopts "}" ";" |
  63              "echo" | "routerad" | "routersol" | "timex" |
  64              "timex" "{" timextype "}" ";" | "paramprob" |
  65              "paramprob" "{" parapptype "}" ";" | "timest" | "timestrep" |
  66              "inforeq" | "inforep" | "maskreq" | "maskrep" .
  67
  68 echoopts ::= echoopts [ icmpechoopts ] .
  69 unreachtype ::= "net-unr" | "host-unr" | "proto-unr" | "port-unr" |
  70              "needfrag" | "srcfail" | "net-unk" | "host-unk" | "isolate" |
  71              "net-prohib" | "host-prohib" | "net-tos" | "host-tos" |
  72              "filter-prohib" | "host-preced" | "cutoff-preced" .
  73 redirtype ::= "net-redir" | "host-redir" | "tos-net-redir" |
  74               "tos-host-redir" .
  75 timextype ::= "intrans" | "reass" .
  76 paramptype ::= "optabsent" .
  77
  78 data    ::= "data" "{" databodyopts "}" ";" .
  79 databodyopts ::= "len" number | "value" string | "file" filename .
  80
  81 icmpechoopts ::= "icmpseq" number | "icmpid" number .
  82 .fi
  83 .SH COMMANDS
  84 .PP
  85 Before sending any packets or defining any packets, it is necessary to
  86 describe the interface(s) which will be used to send packets out.
  87 .TP
  88 .B interface
  89 is used to describe a network interface.  The description included need
  90 not match the actual configuration currently employed by the operating
  91 system.
  92 .TP
  93 .B send
  94 is used to actually send out a packet across the network.  If the
  95 destination is not specified, it will attempt to send the packet
  96 directly out on the network to the destination without routing it.
  97 .TP
  98 .B router
  99 configures the default router for ipsend, as distinct from the default
 100 route installed in the kernel.
 101 .TP
 102 .B ipv4
 103 is used to describe an IP (version 4) packet.  IP header fields can be
 104 specified, including options, followed by a data section which may contain
 105 further protocol headers.
 106 .SH IPv4
 107 .TP
 108 .B hl <number>
 109 manually specifies the IP header length (automatically adjusts with the
 110 presence of IP options and defaults to 5);
 111 .TP
 112 .B v <number>
 113 set the IP version.  Default is 4.
 114 .TP
 115 .B tos <number>
 116 set the type of service (TOS) field in the IP header.  Default is 0.
 117 .TP
 118 .B len <number>
 119 manually specifies the length of the IP packet.  The length will automatically
 120 be adjusted to accommodate data or further protocol headers.
 121 .TP
 122 .B off <number>
 123 sets the fragment offset field of the IP packet.  Default is 0.
 124 .TP
 125 .B ttl <number>
 126 sets the time to live (TTL) field of the IP header.  Default is 60.
 127 .TP
 128 .B proto <protocol>
 129 sets the protocol field of the IP header.  The protocol can either be a
 130 number or a name found in \fB/etc/protocols\fP.
 131 .TP
 132 .B sum
 133 manually specifies the checksum for the IP header.  If left unset (0), it
 134 will be calculated prior to being sent.
 135 .TP
 136 .B src
 137 manually specifies the source address of the IP header.  If left unset, it
 138 will default to the host's IP address.
 139 .TP
 140 .B dst
 141 sets the destination of the IP packet.  The default is 0.0.0.0.
 142 .TP
 143 .B opt
 144 is used to include IP options in the IP header.
 145 .TP
 146 .B tcp
 147 is used to indicate the a TCP protocol header is to follow.  See the \fBTCP\fP
 148 section for TCP header options.
 149 .TP
 150 .B udp
 151 is used to indicate the a UDP protocol header is to follow.  See the \fBUDP\fP
 152 section for UDP header options.
 153 .TP
 154 .B icmp
 155 is used to indicate the a ICMP protocol header is to follow.  See the
 156 \fBICMP\fP section for ICMP header options.
 157 .TP
 158 .B data
 159 is used to indicate that raw data is to be included in the IP packet.  See the
 160 \fBDATA\fP section for details on options available.
 161 .SH "IPv4 Options"
 162 these keywords indicate that the relevant IP option should be added to the
 163 IP header (the header length field will be adjusted appropriately).
 164 .TP
 165 .B nop
 166 No Operation [RFC 791] (space filler).
 167 .TP
 168 .B rr <number>
 169 Record Router [RFC 791].  The number given specifies the number of
 170 \fBbytes\fP to be used for storage.  This should be a multiple of 4 for
 171 proper operation.
 172 .TP
 173 .B zsu
 174 Experimental Measurement.
 175 .TP
 176 .B mtup [RFC 1191].
 177 MTU Probe.
 178 .TP
 179 .B mtur [RFC 1191].
 180 MTU Ready.
 181 .TP
 182 .B encode
 183 .TP
 184 .B ts
 185 Timestamp [RFC 791].
 186 .TP
 187 .B tr
 188 Traceroute [RFC 1393].
 189 .TP
 190 .B "sec-class <security-level>, sec"
 191 Security [RFC 1108].  This option specifies the security label for the packet.
 192 Using \fBsec\fP sets up the framework of the security option but unless
 193 \fBsec-class\fP is given, the level may not be set.
 194 .TP
 195 .B "lsrr <ip-address>"
 196 Loose Source Route [RFC 791].
 197 .TP
 198 .B e-sec
 199 Extended Security [RFC 1108].
 200 .TP
 201 .B cipso
 202 Commercial Security.
 203 .TP
 204 .B satid
 205 Stream ID [RFC 791].
 206 .TP
 207 .B "ssrr <ip-address>"
 208 Strict Source Route [RFC 791].
 209 .TP
 210 .B addext
 211 Address Extension
 212 .TP
 213 .B visa
 214 Experimental Access Control.
 215 .TP
 216 .B imitd
 217 IMI Traffic Descriptor.
 218 .TP
 219 .B eip
 220 [RFC 1358].
 221 .TP
 222 .B finn
 223 Experimental Flow Control.
 224 .SH TCP
 225 .TP
 226 .B sport <port>
 227 sets the source port to the number/name given.  Default is 0.
 228 .TP
 229 .B dport <port>
 230 sets the destination port to the number/name given.  Default is 0.
 231 .TP
 232 .B seq <number>
 233 sets the sequence number to the number specified.  Default is 0.
 234 .TP
 235 .B ack <number>
 236 sets the acknowledge number to the number specified.  Default is 0.
 237 .TP
 238 .B off <number>
 239 sets the offset value for the start of data to the number specified.  This
 240 implies the size of the TCP header.  It is automatically adjusted if TCP
 241 options are included and defaults to 5.
 242 .TP
 243 .B urp <number>
 244 sets the value of the urgent data pointer to the number specified.  Default
 245 is 0.
 246 .TP
 247 .B win <number>
 248 sets the size of the TCP window to the number specified.  Default is 4096.
 249 .TP
 250 .B sum <number>
 251 manually specifies the checksum for the TCP pseudo-header and data.  If left
 252 unset, it defaults to 0 and is automatically calculated.
 253 .TP
 254 .B flags <tcp-flags>
 255 sets the TCP flags field to match the flags specified.  Valid flags are
 256 "S" (SYN), "A" (ACK), "R" (RST), "F" (FIN), "U" (URG), "P" (PUSH).
 257 .TP
 258 .B opt
 259 indicates that TCP header options follow.  As TCP options are added to the
 260 TCP header, the \fBoff\fP field is updated to match.
 261 .TP
 262 .B data
 263 indicates that a data section is to follow and is to be included as raw
 264 data, being appended to the header.
 265 .SH "TCP options"
 266 With a TCP header, it is possible to append a number of header options.
 267 The TCP header offset will be updated automatically to reflect the change
 268 in size.  The valid options are: \fBnop\fP No Operation,
 269 \fBeol\fP End Of (option) List, \fBmss [ size ]\fP Maximum Segment Size - this
 270 sets the maximum receivable size of a packet containing data,
 271 \fBwscale\fP Window Scale, \fBts\fP Timestamp.
 272 .SH UDP
 273 .TP
 274 .B sport <port>
 275 sets the source port to the number/name given.  Default is 0.
 276 .TP
 277 .B dport <port>
 278 sets the destination port to the number/name given.  Default is 0.
 279 .TP
 280 .B len <number>
 281 manually specifies the length of the UDP header and data.  If left unset,
 282 it is automatically adjusted to match the header presence and any data if
 283 present.
 284 .TP
 285 .B sum <number>
 286 manually specifies the checksum for the UDP pseudo-header and data.  If left
 287 unset, it defaults to 0 and is automatically calculated.
 288 .TP
 289 .B data
 290 indicates that a data section is to follow and is to be included as raw
 291 data, being appended to the header.
 292 .SH ICMP
 293 .TP
 294 .B type <icmptype>
 295 sets the ICMP type according the to the icmptype tag.  This may either be
 296 a number or one of the recognised tags (see the \fBICMP TYPES\fP section for a
 297 list of names recognised).
 298 .TP
 299 .B code <icmpcode>
 300 sets the ICMP code.
 301 .TP
 302 .B data
 303 indicates that a data section is to follow and is to be included as raw
 304 data, being appended to the header.
 305 .SH DATA
 306 Each of the following extend the packet in a different way.  \fBLen\fP just
 307 increases the length (without adding any content), \fBvalue\fP uses a string
 308 and \fBfile\fP a file.
 309 .TP
 310 .B len <number>
 311 extend the length of the packet by \fBnumber\fP bytes (without filling those
 312 bytes with any particular data).
 313 .TP
 314 .B value <string>
 315 indicates that the string provided should be added to the current packet as
 316 data.  A string may be a consecutive list of characters and numbers (with
 317 no white spaces) or bounded by "'s (may not contain them, even if \\'d).
 318 The \\ character is recognised with the appropriate C escaped values, including
 319 octal numbers.
 320 .TP
 321 .B file <filename>
 322 reads data in from the specified file and appends it to the current packet.
 323 If the new total length would exceed 64k, an error will be reported.
 324 .SH "ICMP TYPES"
 325 .TP
 326 .B echorep
 327 Echo Reply.
 328 .TP
 329 .B "unreach [ unreachable-code ]"
 330 Generic Unreachable error.  This is used to indicate that an error has
 331 occurred whilst trying to send the packet across the network and that the
 332 destination cannot be reached.  The unreachable code names are:
 333 \fBnet-unr\fP network unreachable, \fBhost-unr\fP host unreachable,
 334 \fBproto-unr\fP protocol unreachable, \fBport-unr\fP port unreachable,
 335 \fBneedfrag\fP, \fBsrcfail\fP source route failed,
 336 \fBnet-unk\fP network unknown, \fBhost-unk\fP host unknown,
 337 \fBisolate\fP, \fBnet-prohib\fP administratively prohibited contact with
 338 network,
 339 \fBhost-prohib\fP administratively prohibited contact with host,
 340 \fBnet-tos\fP network unreachable with given TOS,
 341 \fBhost-tos\fP host unreachable with given TOS,
 342 \fBfilter-prohib\fP packet prohibited by packet filter,
 343 \fBhost-preced\fP,
 344 \fBcutoff-preced\fP.
 345 .TP
 346 .B squench
 347 Source Quence.
 348 .TP
 349 .B "redir [ redirect-code ]"
 350 Redirect (routing).  This is used to indicate that the route being chosen
 351 for forwarding the packet is suboptimal and that the sender of the packet
 352 should be routing packets via another route.  The redirect code names are:
 353 \fBnet-redir\fP redirect packets for a network,
 354 \fBhost-redir\fP redirect packets for a host,
 355 \fBtos-net-redir\fP redirect packets for a network with a given TOS,
 356 \fBtos-host-redir\fP redirect packets for a host with a given TOS.
 357 .TP
 358 .B echo
 359 Echo.
 360 .TP
 361 .B routerad
 362 Router Advertisement.
 363 .TP
 364 .B routersol
 365 Router solicitation.
 366 .TP
 367 .B "timex [ timexceed-code ]"
 368 Time Exceeded.  This is used to indicate that the packet failed to reach the
 369 destination because it was in transit too long (i.e. ttl reached 0).  The
 370 valid code names are: \fBintrans\fP,
 371 \fBreass\fP could not reassemble packet from fragments within a given time.
 372 .TP
 373 .B "paramprob [ paramprob-code ]"
 374 Parameter problem.  There is only one available parameter problem code name:
 375 \fBoptabsent\fP.
 376 .TP
 377 .B timest
 378 Time stamp request.
 379 .TP
 380 .B "timestrep [ { timestamp-code } ]"
 381 Time stamp reply.  In a timestamp reply, it is possible to supply the
 382 following values: \fBrtime\fP, \fBotime\fP, \fBttime\fP.
 383 .TP
 384 .B inforeq
 385 Information request.
 386 .TP
 387 .B inforep
 388 Information reply.
 389 .TP
 390 .B maskreq
 391 Address mask request.
 392 .TP
 393 .B maskrep
 394 Address mask reply.
 395 .SH FILES
 396 /etc/hosts
 397 .br
 398 /etc/protocols
 399 .br
 400 /etc/services
 401 .SH SEE ALSO
 402 ipsend(1), iptest(1), hosts(5), protocols(5), services(5)