diff options
Diffstat (limited to 'usr/src/man/man4')
| -rw-r--r-- | usr/src/man/man4/Makefile | 17 | ||||
| -rw-r--r-- | usr/src/man/man4/ipf.4 | 562 | ||||
| -rw-r--r-- | usr/src/man/man4/ipmon.4 | 72 | ||||
| -rw-r--r-- | usr/src/man/man4/ipnat.4 | 295 | ||||
| -rw-r--r-- | usr/src/man/man4/ippool.4 | 159 |
5 files changed, 1105 insertions, 0 deletions
diff --git a/usr/src/man/man4/Makefile b/usr/src/man/man4/Makefile index d179643b98..6598c115a3 100644 --- a/usr/src/man/man4/Makefile +++ b/usr/src/man/man4/Makefile @@ -12,6 +12,7 @@ # # Copyright 2011, Richard Lowe # Copyright 2013 Nexenta Systems, Inc. All rights reserved. +# Copyright 2015, Joyent, Inc. # include $(SRC)/Makefile.master @@ -82,6 +83,10 @@ _MANFILES= Intro.4 \ ib.4 \ ike.config.4 \ ike.preshared.4 \ + ipf.4 \ + ipmon.4 \ + ipnat.4 \ + ippool.4 \ inet_type.4 \ inetd.conf.4 \ init.4 \ @@ -224,6 +229,10 @@ _MANLINKS= addresses.4 \ hosts.allow.4 \ hosts.deny.4 \ intro.4 \ + ipf.conf.4 \ + ipmon.conf.4 \ + ipnat.conf.4 \ + ippool.conf.4 \ md.cf.4 \ mdi_ib_cache.4 \ mdi_scsi_vhci_cache.4 \ @@ -264,6 +273,14 @@ rhosts.4 := LINKSRC = hosts.equiv.4 hosts.allow.4 := LINKSRC = hosts_access.4 hosts.deny.4 := LINKSRC = hosts_access.4 +ipf.conf.4 := LINKSRC = ipf.4 + +ipmon.conf.4 := LINKSRC = ipmon.4 + +ipnat.conf.4 := LINKSRC = ipnat.4 + +ippool.conf.4 := LINKSRC = ippool.4 + fbtab.4 := LINKSRC = logindevperm.4 md.cf.4 := LINKSRC = md.tab.4 diff --git a/usr/src/man/man4/ipf.4 b/usr/src/man/man4/ipf.4 new file mode 100644 index 0000000000..e93753881b --- /dev/null +++ b/usr/src/man/man4/ipf.4 @@ -0,0 +1,562 @@ +'\" te +.\" To view license terms, attribution, and copyright for IP Filter, the +.\" default path is /usr/lib/ipf/IPFILTER.LICENCE. If the Illumos operating +.\" environment has been installed anywhere other than the default, modify the +.\" given path to access the file at the installed location. +.\" Portions Copyright (c) 2015, Joyent, Inc. +.TH IPF 4 +.SH NAME +ipf, ipf.conf, ipf6.conf \- IP packet filter rule syntax +.SH DESCRIPTION +.PP +A rule file for \fBipf\fP may have any name or even be stdin. As +\fBipfstat\fP produces parsable rules as output when displaying the internal +kernel filter lists, it is quite plausible to use its output to feed back +into \fBipf\fP. Thus, to remove all filters on input packets, the following +could be done: +.nf + +\fC# ipfstat \-i | ipf \-rf \-\fP +.fi +.SH GRAMMAR +.PP +The format used by \fBipf\fP for construction of filtering rules can be +described using the following grammar in BNF: +\fC +.nf +filter-rule = [ insert ] action in-out [ options ] [ tos ] [ ttl ] + [ proto ] ip [ group ]. + +insert = "@" decnumber . +action = block | "pass" | log | "count" | skip | auth | call . +in-out = "in" | "out" . +options = [ log ] [ tag ] [ "quick" ] [ "on" interface-name [ dup ] + [ froute ] [ replyto ] ] . +tos = "tos" decnumber | "tos" hexnumber . +ttl = "ttl" decnumber . +proto = "proto" protocol . +ip = srcdst [ flags ] [ with withopt ] [ icmp ] [ keep ] . +group = [ "head" decnumber ] [ "group" decnumber ] . + +block = "block" [ return-icmp[return-code] | "return-rst" ] . +log = "log" [ "body" ] [ "first" ] [ "or-block" ] [ "level" loglevel ] . +tag = "tag" tagid . +skip = "skip" decnumber . +auth = "auth" | "preauth" . +call = "call" [ "now" ] function-name . +dup = "dup-to" interface-name [ ":" ipaddr ] . +froute = "fastroute" | "to" interface-name [ ":" ipaddr ] . +replyto = "reply-to" interface-name [ ":" ipaddr ] . +protocol = "tcp/udp" | "udp" | "tcp" | "icmp" | decnumber . +srcdst = "all" | fromto . +fromto = "from" [ "!" ] object "to" [ "!" ] object . + +return-icmp = "return-icmp" | "return-icmp-as-dest" . +return-code = "(" icmp-code ")" . +object = addr [ port-comp | port-range ] . +addr = "any" | nummask | host-name [ "mask" ipaddr | "mask" hexnumber ] . +addr = "any" | "<thishost>" | nummask | + host-name [ "mask" ipaddr | "mask" hexnumber ] . +port-comp = "port" compare port-num . +port-range = "port" port-num range port-num . +flags = "flags" flag { flag } [ "/" flag { flag } ] . +with = "with" | "and" . +icmp = "icmp-type" icmp-type [ "code" decnumber ] . +return-code = "(" icmp-code ")" . +keep = "keep" "state" [ "(" state-options ")" ] | "keep" "frags" . +loglevel = facility"."priority | priority . + +nummask = host-name [ "/" decnumber ] . +host-name = ipaddr | hostname | "any" . +ipaddr = host-num "." host-num "." host-num "." host-num . +host-num = digit [ digit [ digit ] ] . +port-num = service-name | decnumber . +state-options = state-opts [ "," state-options ] . + +state-opts = "age" decnumber [ "/" decnumber ] | "strict" | + "no-icmp-err" | "limit" decnumber | "newisn" | "sync" . +withopt = [ "not" | "no" ] opttype [ withopt ] . +opttype = "ipopts" | "short" | "frag" | "opt" optname . +optname = ipopts [ "," optname ] . +ipopts = optlist | "sec-class" [ secname ] . +secname = seclvl [ "," secname ] . +seclvl = "unclass" | "confid" | "reserv-1" | "reserv-2" | "reserv-3" | + "reserv-4" | "secret" | "topsecret" . +icmp-type = "unreach" | "echo" | "echorep" | "squench" | "redir" | + "timex" | "paramprob" | "timest" | "timestrep" | "inforeq" | + "inforep" | "maskreq" | "maskrep" | decnumber . +icmp-code = decumber | "net-unr" | "host-unr" | "proto-unr" | "port-unr" | + "needfrag" | "srcfail" | "net-unk" | "host-unk" | "isolate" | + "net-prohib" | "host-prohib" | "net-tos" | "host-tos" | + "filter-prohib" | "host-preced" | "cutoff-preced" . +optlist = "nop" | "rr" | "zsu" | "mtup" | "mtur" | "encode" | "ts" | + "tr" | "sec" | "lsrr" | "e-sec" | "cipso" | "satid" | "ssrr" | + "addext" | "visa" | "imitd" | "eip" | "finn" . +facility = "kern" | "user" | "mail" | "daemon" | "auth" | "syslog" | + "lpr" | "news" | "uucp" | "cron" | "ftp" | "authpriv" | + "audit" | "logalert" | "local0" | "local1" | "local2" | + "local3" | "local4" | "local5" | "local6" | "local7" . +priority = "emerg" | "alert" | "crit" | "err" | "warn" | "notice" | + "info" | "debug" . + +hexnumber = "0" "x" hexstring . +hexstring = hexdigit [ hexstring ] . +decnumber = digit [ decnumber ] . + +compare = "=" | "!=" | "<" | ">" | "<=" | ">=" | "eq" | "ne" | "lt" | + "gt" | "le" | "ge" . +range = "<>" | "><" . +hexdigit = digit | "a" | "b" | "c" | "d" | "e" | "f" . +digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" . +flag = "F" | "S" | "R" | "P" | "A" | "U" . +.fi +.PP +This syntax is somewhat simplified for readability, some combinations +that match this grammar are disallowed by the software because they do +not make sense (such as tcp \fBflags\fP for non-TCP packets). +.SH FILTER RULES +.PP +The "briefest" valid rules are (currently) no-ops and are of the form: +.nf + block in all + pass in all + log out all + count in all +.fi +.PP +Filter rules are checked in order, with the last matching rule +determining the fate of the packet (but see the \fBquick\fP option, +below). +.PP +Filters are installed by default at the end of the kernel's filter +lists, prepending the rule with \fB@n\fP will cause it to be inserted +as the n'th entry in the current list. This is especially useful when +modifying and testing active filter rulesets. See \fBipf\fP(1M) for more +information. +.SH ACTIONS +.PP +The action indicates what to do with the packet if it matches the rest +of the filter rule. Each rule MUST have an action. The following +actions are recognised: +.TP +.B block +indicates that the packet should be flagged to be dropped. In response +to blocking a packet, the filter may be instructed to send a reply +packet, either an ICMP packet (\fBreturn-icmp\fP), an ICMP packet +masquerading as being from the original packet's destination +(\fBreturn-icmp-as-dest\fP), or a TCP "reset" (\fBreturn-rst\fP). An +ICMP packet may be generated in response to any IP packet, and its +type may optionally be specified, but a TCP reset may only be used +with a rule which is being applied to TCP packets. When using +\fBreturn-icmp\fP or \fBreturn-icmp-as-dest\fP, it is possible to specify +the actual unreachable `type'. That is, whether it is a network +unreachable, port unreachable or even administratively +prohibited. This is done by enclosing the ICMP code associated with +it in parenthesis directly following \fBreturn-icmp\fP or +\fBreturn-icmp-as-dest\fP as follows: +.nf + block return-icmp(11) ... +.fi +.PP +Would return a Type-Of-Service (TOS) ICMP unreachable error. +.TP +.B pass +will flag the packet to be let through the filter. +.TP +.B log +causes the packet to be logged (as described in the LOGGING section +below) and has no effect on whether the packet will be allowed through +the filter. +.TP +.B count +causes the packet to be included in the accounting statistics kept by +the filter, and has no effect on whether the packet will be allowed through +the filter. These statistics are viewable with ipfstat(8). +.TP +.B call +this action is used to invoke the named function in the kernel, which +must conform to a specific calling interface. Customised actions and +semantics can thus be implemented to supplement those available. This +feature is for use by knowledgeable hackers, and is not currently +documented. +.TP +.B "skip <n>" +causes the filter to skip over the next \fIn\fP filter rules. If a rule is +inserted or deleted inside the region being skipped over, then the value of +\fIn\fP is adjusted appropriately. +.TP +.B auth +this allows authentication to be performed by a user-space program running +and waiting for packet information to validate. The packet is held for a +period of time in an internal buffer whilst it waits for the program to return +to the kernel the \fIreal\fP flags for whether it should be allowed through +or not. Such a program might look at the source address and request some sort +of authentication from the user (such as a password) before allowing the +packet through or telling the kernel to drop it if from an unrecognised source. +.TP +.B preauth +tells the filter that for packets of this class, it should look in the +pre-authenticated list for further clarification. If no further matching +rule is found, the packet will be dropped (the FR_PREAUTH is not the same +as FR_PASS). If a further matching rule is found, the result from that is +used in its instead. This might be used in a situation where a person +\fIlogs in\fP to the firewall and it sets up some temporary rules defining +the access for that person. +.PP +The next word must be either \fBin\fP or \fBout\fP. Each packet +moving through the kernel is either inbound (just been received on an +interface, and moving towards the kernel's protocol processing) or +outbound (transmitted or forwarded by the stack, and on its way to an +interface). There is a requirement that each filter rule explicitly +state which side of the I/O it is to be used on. +.SH OPTIONS +.PP +The list of options is brief, and all are indeed optional. Where +options are used, they must be present in the order shown here. These +are the currently supported options: +.TP +.B log +indicates that, should this be the last matching rule, the packet +header will be written to the \fBipl\fP log (as described in the +LOGGING section below). +.TP +.B tag tagid +indicates that, if this rule causes the packet to be logged or entered +in the state table, the tagid will be logged as part of the log entry. +This can be used to quickly match "similar" rules in scripts that post +process the log files for e.g. generation of security reports or accounting +purposes. The tagid is a 32 bit unsigned integer. +.TP +.B quick +allows "short-cut" rules in order to speed up the filter or override +later rules. If a packet matches a filter rule which is marked as +\fBquick\fP, this rule will be the last rule checked, allowing a +"short-circuit" path to avoid processing later rules for this +packet. The current status of the packet (after any effects of the +current rule) will determine whether it is passed or blocked. +.IP +If this option is missing, the rule is taken to be a "fall-through" +rule, meaning that the result of the match (block/pass) is saved and +that processing will continue to see if there are any more matches. +.TP +.B on +allows an interface name to be incorporated into the matching +procedure. Interface names are as printed by "netstat \-i". If this +option is used, the rule will only match if the packet is going +through that interface in the specified direction (in/out). If this +option is absent, the rule is taken to be applied to a packet +regardless of the interface it is present on (i.e. on all interfaces). +Filter rulesets are common to all interfaces, rather than having a +filter list for each interface. +.IP +This option is especially useful for simple IP-spoofing protection: +packets should only be allowed to pass inbound on the interface from +which the specified source address would be expected, others may be +logged and/or dropped. +.TP +.B dup-to +causes the packet to be copied, and the duplicate packet to be sent +outbound on the specified interface, optionally with the destination +IP address changed to that specified. This is useful for off-host +logging, using a network sniffer. +.TP +.B to +causes the packet to be moved to the outbound queue on the +specified interface. This can be used to circumvent kernel routing +decisions, and even to bypass the rest of the kernel processing of the +packet (if applied to an inbound rule). It is thus possible to +construct a firewall that behaves transparently, like a filtering hub +or switch, rather than a router. The \fBfastroute\fP keyword is a +synonym for this option. +.SH MATCHING PARAMETERS +.PP +The keywords described in this section are used to describe attributes +of the packet to be used when determining whether rules match or don't +match. The following general-purpose attributes are provided for +matching, and must be used in this order: +.TP +.B tos +packets with different Type-Of-Service values can be filtered. +Individual service levels or combinations can be filtered upon. The +value for the TOS mask can either be represented as a hex number or a +decimal integer value. +.TP +.B ttl +packets may also be selected by their Time-To-Live value. The value given in +the filter rule must exactly match that in the packet for a match to occur. +This value can only be given as a decimal integer value. +.TP +.B proto +allows a specific protocol to be matched against. All protocol names +found in \fB/etc/protocols\fP are recognised and may be used. +However, the protocol may also be given as a DECIMAL number, allowing +for rules to match your own protocols, or new ones which would +out-date any attempted listing. +.IP +The special protocol keyword \fBtcp/udp\fP may be used to match either +a TCP or a UDP packet, and has been added as a convenience to save +duplication of otherwise-identical rules. +.\" XXX grammar should reflect this (/etc/protocols) +.PP +The \fBfrom\fP and \fBto\fP keywords are used to match against IP +addresses (and optionally port numbers). Rules must specify BOTH +source and destination parameters. +.PP +IP addresses may be specified in one of two ways: as a numerical +address\fB/\fPmask, or as a hostname \fBmask\fP netmask. The hostname +may either be a valid hostname, from either the hosts file or DNS +(depending on your configuration and library) or of the dotted numeric +form. There is no special designation for networks but network names +are recognised. Note that having your filter rules depend on DNS +results can introduce an avenue of attack, and is discouraged. +.PP +There is a special case for the hostname \fBany\fP which is taken to +be 0.0.0.0/0 (see below for mask syntax) and matches all IP addresses. +Only the presence of "any" has an implied mask, in all other +situations, a hostname MUST be accompanied by a mask. It is possible +to give "any" a hostmask, but in the context of this language, it is +non-sensical. +.PP +The numerical format "x\fB/\fPy" indicates that a mask of y +consecutive 1 bits set is generated, starting with the MSB, so a y value +of 16 would give 0xffff0000. The symbolic "x \fBmask\fP y" indicates +that the mask y is in dotted IP notation or a hexadecimal number of +the form 0x12345678. Note that all the bits of the IP address +indicated by the bitmask must match the address on the packet exactly; +there isn't currently a way to invert the sense of the match, or to +match ranges of IP addresses which do not express themselves easily as +bitmasks (anthropomorphization; it's not just for breakfast anymore). +.PP +If a \fBport\fP match is included, for either or both of source and +destination, then it is only applied to +.\" XXX - "may only be" ? how does this apply to other protocols? will it not match, or will it be ignored? +TCP and UDP packets. If there is no \fBproto\fP match parameter, +packets from both protocols are compared. This is equivalent to "proto +tcp/udp". When composing \fBport\fP comparisons, either the service +name or an integer port number may be used. Port comparisons may be +done in a number of forms, with a number of comparison operators, or +port ranges may be specified. When the port appears as part of the +\fBfrom\fP object, it matches the source port number, when it appears +as part of the \fBto\fP object, it matches the destination port number. +See the examples for more information. +.PP +The \fBall\fP keyword is essentially a synonym for "from any to any" +with no other match parameters. +.PP +Following the source and destination matching parameters, the +following additional parameters may be used: +.TP +.B with +is used to match irregular attributes that some packets may have +associated with them. To match the presence of IP options in general, +use \fBwith ipopts\fP. To match packets that are too short to contain +a complete header, use \fBwith short\fP. To match fragmented packets, +use \fBwith frag\fP. For more specific filtering on IP options, +individual options can be listed. +.IP +Before any parameter used after the \fBwith\fP keyword, the word +\fBnot\fP or \fBno\fP may be inserted to cause the filter rule to only +match if the option(s) is not present. +.IP +Multiple consecutive \fBwith\fP clauses are allowed. Alternatively, +the keyword \fBand\fP may be used in place of \fBwith\fP, this is +provided purely to make the rules more readable ("with ... and ..."). +When multiple clauses are listed, all those must match to cause a +match of the rule. +.\" XXX describe the options more specifically in a separate section +.TP +.B flags +is only effective for TCP filtering. Each of the letters possible +represents one of the possible flags that can be set in the TCP +header. The association is as follows: +.LP +.nf + F - FIN + S - SYN + R - RST + P - PUSH + A - ACK + U - URG +.fi +.IP +The various flag symbols may be used in combination, so that "SA" +would represent a SYN-ACK combination present in a packet. There is +nothing preventing the specification of combinations, such as "SFR", +that would not normally be generated by law-abiding TCP +implementations. However, to guard against weird aberrations, it is +necessary to state which flags you are filtering against. To allow +this, it is possible to set a mask indicating which TCP flags you wish +to compare (i.e., those you deem significant). This is done by +appending "/<flags>" to the set of TCP flags you wish to match +against, e.g.: +.LP +.nf + ... flags S + # becomes "flags S/AUPRFS" and will match + # packets with ONLY the SYN flag set. + + ... flags SA + # becomes "flags SA/AUPRFS" and will match any + # packet with only the SYN and ACK flags set. + + ... flags S/SA + # will match any packet with just the SYN flag set + # out of the SYN-ACK pair; the common "establish" + # keyword action. "S/SA" will NOT match a packet + # with BOTH SYN and ACK set, but WILL match "SFP". +.fi +.TP +.B icmp-type +is only effective when used with \fBproto icmp\fP and must NOT be used +in conjunction with \fBflags\fP. There are a number of types, which can be +referred to by an abbreviation recognised by this language, or the numbers +with which they are associated can be used. The most important from +a security point of view is the ICMP redirect. +.SH KEEP HISTORY +.PP +The second last parameter which can be set for a filter rule is whether or not +to record historical information for that packet, and what sort to keep. The +following information can be kept: +.TP +.B state +keeps information about the flow of a communication session. State can +be kept for TCP, UDP, and ICMP packets. +.TP +.B frags +keeps information on fragmented packets, to be applied to later +fragments. +.PP +allowing packets which match these to flow straight through, rather +than going through the access control list. +.SH GROUPS +The last pair of parameters control filter rule "grouping". By default, all +filter rules are placed in group 0 if no other group is specified. To add a +rule to a non-default group, the group must first be started by creating a +group \fIhead\fP. If a packet matches a rule which is the \fIhead\fP of a +group, the filter processing then switches to the group, using that rule as +the default for the group. If \fBquick\fP is used with a \fBhead\fP rule, rule +processing isn't stopped until it has returned from processing the group. +.PP +A rule may be both the head for a new group and a member of a non-default +group (\fBhead\fP and \fBgroup\fP may be used together in a rule). +.TP +.B "head <n>" +indicates that a new group (number n) should be created. +.TP +.B "group <n>" +indicates that the rule should be put in group (number n) rather than group 0. +.SH LOGGING +.PP +When a packet is logged, with either the \fBlog\fP action or option, +the headers of the packet are written to the \fBipl\fP packet logging +pseudo-device. Immediately following the \fBlog\fP keyword, the +following qualifiers may be used (in order): +.TP +.B body +indicates that the first 128 bytes of the packet contents will be +logged after the headers. +.TP +.B first +If log is being used in conjunction with a "keep" option, it is recommended +that this option is also applied so that only the triggering packet is logged +and not every packet which thereafter matches state information. +.TP +.B or-block +indicates that, if for some reason the filter is unable to log the +packet (such as the log reader being too slow) then the rule should be +interpreted as if the action was \fBblock\fP for this packet. +.TP +.B "level <loglevel>" +indicates what logging facility and priority, or just priority with +the default facility being used, will be used to log information about +this packet using ipmon's -s option. +.PP +See ipl(4) for the format of records written +to this device. The ipmon(8) program can be used to read and format +this log. +.SH EXAMPLES +.PP +The \fBquick\fP option is good for rules such as: +\fC +.nf +block in quick from any to any with ipopts +.fi +.PP +which will match any packet with a non-standard header length (IP +options present) and abort further processing of later rules, +recording a match and also that the packet should be blocked. +.PP +The "fall-through" rule parsing allows for effects such as this: +.LP +.nf + block in from any to any port < 6000 + pass in from any to any port >= 6000 + block in from any to any port > 6003 +.fi +.PP +which sets up the range 6000-6003 as being permitted and all others being +denied. Note that the effect of the first rule is overridden by subsequent +rules. Another (easier) way to do the same is: +.LP +.nf + block in from any to any port 6000 <> 6003 + pass in from any to any port 5999 >< 6004 +.fi +.PP +Note that both the "block" and "pass" are needed here to effect a +result as a failed match on the "block" action does not imply a pass, +only that the rule hasn't taken effect. To then allow ports < 1024, a +rule such as: +.LP +.nf + pass in quick from any to any port < 1024 +.fi +.PP +would be needed before the first block. To create a new group for +processing all inbound packets on le0/le1/lo0, with the default being to block +all inbound packets, we would do something like: +.LP +.nf + block in all + block in quick on le0 all head 100 + block in quick on le1 all head 200 + block in quick on lo0 all head 300 +.fi +.PP + +and to then allow ICMP packets in on le0, only, we would do: +.LP +.nf + pass in proto icmp all group 100 +.fi +.PP +Note that because only inbound packets on le0 are used processed by group 100, +there is no need to respecify the interface name. Likewise, we could further +breakup processing of TCP, etc, as follows: +.LP +.nf + block in proto tcp all head 110 group 100 + pass in from any to any port = 23 group 110 +.fi +.PP +and so on. The last line, if written without the groups would be: +.LP +.nf + pass in on le0 proto tcp from any to any port = telnet +.fi +.PP +Note, that if we wanted to say "port = telnet", "proto tcp" would +need to be specified as the parser interprets each rule on its own and +qualifies all service/port names with the protocol specified. +.SH FILES +/dev/ipauth +.br +/dev/ipl +.br +/dev/ipstate +.br +/etc/hosts +.br +/etc/services +.SH SEE ALSO +\fBipnat\fR(4), \fBipf\fR(1M), \fBipfstat\fR(1M), \fBipfilter\fR(5) diff --git a/usr/src/man/man4/ipmon.4 b/usr/src/man/man4/ipmon.4 new file mode 100644 index 0000000000..9f38eb0551 --- /dev/null +++ b/usr/src/man/man4/ipmon.4 @@ -0,0 +1,72 @@ +'\" te +.\" To view license terms, attribution, and copyright for IP Filter, the +.\" default path is /usr/lib/ipf/IPFILTER.LICENCE. If the Illumos operating +.\" environment has been installed anywhere other than the default, modify the +.\" given path to access the file at the installed location. +.\" Portions Copyright (c) 2015, Joyent, Inc. +.TH IPMON 4 +.SH NAME +ipmon, ipmon.conf \- ipmon configuration file format +.SH DESCRIPTION +The format for files accepted by ipmon is described by the following grammar: +.LP +.nf +"match" "{" matchlist "}" "do" "{" doing "}" ";" + +matchlist ::= matching [ "," matching ] . +matching ::= direction | dstip | dstport | every | group | interface | + logtag | nattag | protocol | result | rule | srcip | srcport . + +dolist ::= doing [ "," doing ] . +doing ::= execute | save | syslog . + +direction ::= "in" | "out" . +dstip ::= "dstip" "=" ipv4 "/" number . +dstport ::= "dstport" "=" number . +every ::= "every" every-options . +execute ::= "execute" "=" string . +group ::= "group" "=" string | "group" "=" number . +interface ::= "interface" "=" string . +logtag ::= "logtag" "=" string | "logtag" "=" number . +nattag ::= "nattag" "=" string . +protocol ::= "protocol" "=" string | "protocol" "=" number . +result ::= "result" "=" result-option . +rule ::= "rule" "=" number . +srcip ::= "srcip" "=" ipv4 "/" number . +srcport ::= "srcport" "=" number . +type ::= "type" "=" ipftype . +ipv4 ::= number "." number "." number "." number . + +every-options ::= "second" | number "seconds" | "packet" | number "packets" . +result-option ::= "pass" | "block" | "short" | "nomatch" | "log" . +ipftype ::= "ipf" | "nat" | "state" . + +.fi +.PP +In addition, lines that start with a # are considered to be comments. +.SH OVERVIEW +.PP +The ipmon configuration file is used for defining rules to be executed when +logging records are read from +.B /dev/ipl. +.PP +At present, only IPv4 matching is available for source/destination address +matching. +.SH MATCHING +.PP +Each rule for ipmon consists of two primary segments: the first describes how +the log record is to be matched, the second defines what action to take if +there is a positive match. All entries of the rules present in the file are +compared for matches - there is no first or last rule match. +.SH FILES +/dev/ipl +.br +/dev/ipf +.br +/dev/ipnat +.br +/dev/ipstate +.br +/etc/ipmon.conf +.SH SEE ALSO +\fBipmon\fR(1M), \fBipfilter\fR(5) diff --git a/usr/src/man/man4/ipnat.4 b/usr/src/man/man4/ipnat.4 new file mode 100644 index 0000000000..d7f6143de0 --- /dev/null +++ b/usr/src/man/man4/ipnat.4 @@ -0,0 +1,295 @@ +'\" te +.\" To view license terms, attribution, and copyright for IP Filter, the +.\" default path is /usr/lib/ipf/IPFILTER.LICENCE. If the Illumos operating +.\" environment has been installed anywhere other than the default, modify the +.\" given path to access the file at the installed location. +.\" Portions Copyright (c) 2015, Joyent, Inc. +.TH IPNAT 4 +.SH NAME +ipnat, ipnat.conf \- IP NAT file format +.SH DESCRIPTION +The format for files accepted by ipnat is described by the following grammar: +.LP +.nf +ipmap :: = mapblock | redir | map . + +map ::= mapit ifname lhs "->" dstipmask [ mapicmp | mapport | mapproxy ] + mapoptions . +mapblock ::= "map-block" ifname lhs "->" ipmask [ ports ] mapoptions . +redir ::= "rdr" ifname rlhs "->" ip [ "," ip ] rdrport rdroptions . + +lhs ::= ipmask | fromto . +rlhs ::= ipmask dport | fromto . +dport ::= "port" portnum [ "-" portnum ] . +ports ::= "ports" numports | "auto" . +rdrport ::= "port" portnum . +mapit ::= "map" | "bimap" . +fromto ::= "from" object "to" object . +ipmask ::= ip "/" bits | ip "/" mask | ip "netmask" mask . +dstipmask ::= ipmask | "range" ip "-" ip . +mapicmp ::= "icmpidmap" "icmp" number ":" number . +mapport ::= "portmap" tcpudp portspec . +mapoptions ::= [ tcpudp ] [ "frag" ] [ age ] [ clamp ] . +rdroptions ::= rdrproto [ rr ] [ "frag" ] [ age ] [ clamp ] [ rdrproxy ] . + +object :: = addr [ port-comp | port-range ] . +addr :: = "any" | nummask | host-name [ "mask" ipaddr | "mask" hexnumber ] . +port-comp :: = "port" compare port-num . +port-range :: = "port" port-num range port-num . +rdrproto ::= tcpudp | protocol . + +rr ::= "round-robin" . +age ::= "age" decnumber [ "/" decnumber ] . +clamp ::= "mssclamp" decnumber . +tcpudp ::= "tcp/udp" | protocol . +mapproxy ::= "proxy" "port" port proxy-name '/' protocol +rdrproxy ::= "proxy" proxy-name . + +protocol ::= protocol-name | decnumber . +nummask ::= host-name [ "/" decnumber ] . +portspec ::= "auto" | portnumber ":" portnumber . +port ::= portnumber | port-name . +portnumber ::= number { numbers } . +ifname ::= 'A' - 'Z' { 'A' - 'Z' } numbers . + +numbers ::= '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' . +.fi +.PP +For standard NAT functionality, a rule should start with \fBmap\fP and then +proceeds to specify the interface for which outgoing packets will have their +source address rewritten. +.PP +Packets which will be rewritten can only be selected by matching the original +source address. A netmask must be specified with the IP address. +.PP +The address selected for replacing the original is chosen from an IP#/netmask +pair. A netmask of all 1's indicating a hostname is valid. A netmask of +31 1's (255.255.255.254) is considered invalid as there is no space for +allocating host IP#'s after consideration for broadcast and network +addresses. +.PP +When remapping TCP and UDP packets, it is also possible to change the source +port number. Either TCP or UDP or both can be selected by each rule, with a +range of port numbers to remap into given as \fBport-number:port-number\fP. +.SH COMMANDS +There are four commands recognised by IP Filter's NAT code: +.TP +.B map +that is used for mapping one address or network to another in an unregulated +round robin fashion; +.TP +.B rdr +that is used for redirecting packets to one IP address and port pair to +another; +.TP +.B bimap +for setting up bidirectional NAT between an external IP address and an internal +IP address and +.TP +.B map-block +which sets up static IP address based translation, based on a algorithm to +squeeze the addresses to be translated into the destination range. +.SH MATCHING +.PP +For basic NAT and redirection of packets, the address subject to change is used +along with its protocol to check if a packet should be altered. The packet +\fImatching\fP part of the rule is to the left of the "->" in each rule. +.PP +Matching of packets has now been extended to allow more complex compares. +In place of the address which is to be translated, an IP address and port +number comparison can be made using the same expressions available with +\fBipf\fP. A simple NAT rule could be written as: +.LP +.nf +map de0 10.1.0.0/16 -> 201.2.3.4/32 +.fi +.LP +or as +.LP +.nf +map de0 from 10.1.0.0/16 to any -> 201.2.3.4/32 +.fi +.LP +Only IP address and port numbers can be compared against. This is available +with all NAT rules. +.SH TRANSLATION +.PP +To the right of the "->" is the address and port specification which will be +written into the packet providing it has already successfully matched the +prior constraints. The case of redirections (\fBrdr\fP) is the simplest: +the new destination address is that specified in the rule. For \fBmap\fP +rules, the destination address will be one for which the tuple combining +the new source and destination is known to be unique. If the packet is +either a TCP or UDP packet, the destination and source ports come into the +equation too. If the tuple already exists, IP Filter will increment the +port number first, within the available range specified with \fBportmap\fP +and if there exists no unique tuple, the source address will be incremented +within the specified netmask. If a unique tuple cannot be determined, then +the packet will not be translated. The \fBmap-block\fP is more limited in +how it searches for a new, free and unique tuple, in that it will used an +algorithm to determine what the new source address should be, along with the +range of available ports - the IP address is never changed and nor does the +port number ever exceed its allotted range. +.SH ICMPIDMAP +.PP +ICMP messages can be divided into two groups: "errors" and "queries". ICMP +errors are generated as a response of another IP packet. IP Filter will take +care that ICMP errors that are the response of a NAT-ed IP packet are +handled properly. +.PP +For 4 types of ICMP queries (echo request, timestamp request, information +request and address mask request) IP Filter supports an additional mapping +called "ICMP id mapping". All these 4 types of ICMP queries use a unique +identifier called the ICMP id. This id is set by the process sending the +ICMP query and it is usually equal to the process id. The receiver of the +ICMP query will use the same id in its response, thus enabling the +sender to recognize that the incoming ICMP reply is intended for him and is +an answer to a query that he made. The "ICMP id mapping" feature modifies +these ICMP id in a way identical to \fBportmap\fP for TCP or UDP. +.PP +The reason that you might want this, is that using this feature you don't +need an IP address per host behind the NAT box, that wants to do ICMP queries. +The two numbers behind the \fBicmpidmap\fP keyword are the first and the +last icmp id number that can be used. There is one important caveat: if you +map to an IP address that belongs to the NAT box itself (notably if you have +only a single public IP address), then you must ensure that the NAT box does +not use the \fBicmpidmap\fP range that you specified in the \fBmap\fP rule. +.SH KERNEL PROXIES +.PP +IP Filter comes with a few, simple, proxies built into the code that is loaded +into the kernel to allow secondary channels to be opened without forcing the +packets through a user program. The current state of the proxies is listed +below, as one of three states: +.HP +Aging - protocol is roughly understood from +the time at which the proxy was written but it is not well tested or +maintained; +.HP +Developmental - basic functionality exists, works most of the time but +may be problematic in extended real use; +.HP +Experimental - rough support for the protocol at best, may or may not +work as testing has been at best sporadic, possible large scale changes +to the code in order to properly support the protocol. +.HP +Mature - well tested, protocol is properly +understood by the proxy; +.PP +The currently compiled in proxy list is as follows: +.HP +FTP - Mature +.HP +IRC - Experimental +.HP +rpcbind - Experimental +.HP +H.323 - Experimental +.HP +Real Audio (PNA) - Aging +.HP +IPsec - Developmental +.HP +netbios - Experimental +.HP +R-command - Mature + +.SH TRANSPARENT PROXIES +.PP +True transparent proxying should be performed using the redirect (\fBrdr\fP) +rules directing ports to localhost (127.0.0.1) with the proxy program doing +a lookup through \fB/dev/ipnat\fP to determine the real source and address +of the connection. +.SH LOAD-BALANCING +.PP +Two options for use with \fBrdr\fP are available to support primitive, +\fIround-robin\fP based load balancing. The first option allows for a +\fBrdr\fP to specify a second destination, as follows: +.LP +.nf +rdr le0 203.1.2.3/32 port 80 -> 203.1.2.3,203.1.2.4 port 80 tcp +.fi +.LP +This would send alternate connections to either 203.1.2.3 or 203.1.2.4. +In scenarios where the load is being spread amongst a larger set of +servers, you can use: +.LP +.nf +rdr le0 203.1.2.3/32 port 80 -> 203.1.2.3,203.1.2.4 port 80 tcp round-robin +rdr le0 203.1.2.3/32 port 80 -> 203.1.2.5 port 80 tcp round-robin +.fi +.LP +In this case, a connection will be redirected to 203.1.2.3, then 203.1.2.4 +and then 203.1.2.5 before going back to 203.1.2.3. In accomplishing this, +the rule is removed from the top of the list and added to the end, +automatically, as required. This will not effect the display of rules +using "ipnat -l", only the internal application order. +.SH EXAMPLES +.PP +This section deals with the \fBmap\fP command and its variations. +.PP +To change IP#'s used internally from network 10 into an ISP provided 8 bit +subnet at 209.1.2.0 through the ppp0 interface, the following would be used: +.LP +.nf +map ppp0 10.0.0.0/8 -> 209.1.2.0/24 +.fi +.PP +The obvious problem here is we're trying to squeeze over 16,000,000 IP +addresses into a 254 address space. To increase the scope, remapping for TCP +and/or UDP, port remapping can be used; +.LP +.nf +map ppp0 10.0.0.0/8 -> 209.1.2.0/24 portmap tcp/udp 1025:65000 +.fi +.PP +which falls only 527,566 `addresses' short of the space available in network +10. If we were to combine these rules, they would need to be specified as +follows: +.LP +.nf +map ppp0 10.0.0.0/8 -> 209.1.2.0/24 portmap tcp/udp 1025:65000 +map ppp0 10.0.0.0/8 -> 209.1.2.0/24 +.fi +.PP +so that all TCP/UDP packets were port mapped and only other protocols, such as +ICMP, only have their IP# changed. In some instances, it is more appropriate +to use the keyword \fBauto\fP in place of an actual range of port numbers if +you want to guarantee simultaneous access to all within the given range. +However, in the above case, it would default to 1 port per IP address, since +we need to squeeze 24 bits of address space into 8. A good example of how +this is used might be: +.LP +.nf +map ppp0 172.192.0.0/16 -> 209.1.2.0/24 portmap tcp/udp auto +.fi +.PP +which would result in each IP address being given a small range of ports to +use (252). In all cases, the new port number that is used is deterministic. +That is, port X will always map to port Y. +WARNING: It is not advisable to use the \fBauto\fP feature if you are map'ing +to a /32 (i.e. 0/32) because the NAT code will try to map multiple hosts to +the same port number, outgoing and ultimately this will only succeed for one +of them. +The problem here is that the \fBmap\fP directive tells the NAT +code to use the next address/port pair available for an outgoing connection, +resulting in no easily discernible relation between external addresses/ports +and internal ones. This is overcome by using \fBmap-block\fP as follows: +.LP +.nf +map-block ppp0 172.192.0.0/16 -> 209.1.2.0/24 ports auto +.fi +.PP +For example, this would result in 172.192.0.0/24 being mapped to 209.1.2.0/32 +with each address, from 172.192.0.0 to 172.192.0.255 having 252 ports of its +own. As opposed to the above use of \fBmap\fP, if for some reason the user +of (say) 172.192.0.2 wanted 260 simultaneous connections going out, they would +be limited to 252 with \fBmap-block\fP but would just \fImove on\fP to the next +IP address with the \fBmap\fP command. +/dev/ipnat +.br +/etc/services +.br +/etc/hosts +.SH SEE ALSO +\fBhosts\fR(4), \fBipf\fR(4), \fBservices\fR(4), \fBipf\fR(1M), +\fBipnat\fR(1M), \fBipfilter\fR(5) diff --git a/usr/src/man/man4/ippool.4 b/usr/src/man/man4/ippool.4 new file mode 100644 index 0000000000..1ff0e79129 --- /dev/null +++ b/usr/src/man/man4/ippool.4 @@ -0,0 +1,159 @@ +'\" te +.\" To view license terms, attribution, and copyright for IP Filter, the +.\" default path is /usr/lib/ipf/IPFILTER.LICENCE. If the Illumos operating +.\" environment has been installed anywhere other than the default, modify the +.\" given path to access the file at the installed location. +.\" Portions Copyright (c) 2015, Joyent, Inc. +.TH IPPOOL 4 +.SH NAME +ippool, ippool.conf \- IP Pool file format +.SH DESCRIPTION +The format for files accepted by ippool is described by the following grammar: +.LP +.nf +line ::= table | groupmap . +table ::= "table" role tabletype . +groupmap ::= "group-map" inout role number ipfgroup +tabletype ::= ipftree | ipfhash . + +role ::= "role" "=" "ipf" . +inout ::= "in" | "out" . + +ipftree ::= "type" "=" "tree" number "{" addrlist "}" . +ipfhash ::= "type" "=" "hash" number hashopts "{" hashlist "}" . + +ipfgroup ::= setgroup hashopts "{" grouplist "}" | + hashopts "{" setgrouplist "}" . +setgroup ::= "group" "=" groupname . + +hashopts ::= size [ seed ] | seed . + +size ::= "size" number . +seed ::= "seed" number . + +addrlist ::= [ "!" ] addrmask ";" [ addrlist ] . +grouplist ::= groupentry ";" [ grouplist ] | addrmask ";" [ grouplist ] . + +setgrouplist ::= groupentry ";" [ setgrouplist ] . + +groupentry ::= addrmask "," setgroup . + +hashlist ::= hashentry ";" [ hashlist ] . +hashentry ::= addrmask . + +addrmask ::= ipaddr | ipaddr "/" mask . + +mask ::= number | ipaddr . + +groupname ::= number | name . + +number ::= digit { digit } . + +ipaddr = host-num "." host-num "." host-num "." host-num . +host-num = digit [ digit [ digit ] ] . + +digit ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" . +name ::= letter { letter | digit } . +.fi +.PP +The IP pool configuration file is used for defining a single object that +contains a reference to multiple IP address/netmask pairs. A pool may consist +of a mixture of netmask sizes, from 0 to 32. +.PP +At this point in time, only IPv4 addressing is supported. +.SH OVERVIEW +.PP +The IP pool configuration file provides for defining two different mechanisms +for improving speed in matching IP addresses with rules. +The first, +.B table +, defines a lookup +.I table +to provide a single reference in a +filter rule to multiple targets and the second, +.B group-map +, provides a mechanism to target multiple groups from a single filter line. +.PP +The +.B group-map +command can only be used with filter rules that use the +.B call +command to invoke either +.B fr_srcgrpmap +or +.B fr_dstgrpmap +, to use the source or destination address, +respectively, for determining which filter group to jump to next for +continuation of filter packet processing. +.SH POOL TYPES +.PP +Two storage formats are provided: hash tables and tree structure. The hash +table is intended for use with objects all containing the same netmask or a +few different sized netmasks of non-overlapping address space and the tree +is designed for being able to support exceptions to a covering mask, in +addition to normal searching as you would do with a table. It is not possible +to use the tree data storage type with +.B group-map +configuration entries. +.SH POOL ROLES +.PP +When a pool is defined in the configruation file, it must have an associated +role. At present the only supported role is +.B ipf. +Future development will see futher expansion of their use by other sections +of IPFilter code. +.SH EXAMPLES +The following examples show how the pool configuration file is used with +the ipf configuration file to enhance the ability for the ipf configuration +file to be succinct in meaning. +.TP +1 +The first example shows how a filter rule makes reference to a specific +pool for matching of the source address. +.nf +pass in from pool/100 to any +.fi +.PP +The pool configuration, which matches IP addresses 1.1.1.1 and any +in 2.2.0.0/16, except for those in 2.2.2.0/24. +.PP +.nf +table role = ipf type = tree number = 100 + { 1.1.1.1/32; 2.2.0.0/16; !2.2.2.0/24 }; +.fi +.TP +2 +The following ipf.conf extract uses the +fr_srcgrpmap/fr_dstgrpmap lookups to use the +.B group-map +facility to lookup the next group to use for filter processing, providing +the +.B call +filter rule is matched. +.nf +call now fr_srcgrpmap/1010 in all +call now fr_dstgrpmap/2010 out all +pass in all group 1020 +block in all group 1030 +pass out all group 2020 +block out all group 2040 +.fi +.PP +A ippool configuration to work with the above ipf.conf file might +look like this: +.PP +.nf +group-map in role = ipf number = 1010 + { 1.1.1.1/32, group = 1020; 3.3.0.0/16, group = 1030; }; +group-map out role = ipf number = 2010 group = 2020 + { 2.2.2.2/32; 4.4.0.0/16; 5.0.0.0/8, group = 2040; }; +.fi +.SH FILES +/dev/iplookup +.br +/etc/ippool.conf +.br +/etc/hosts +.SH SEE ALSO +\fBippool\fR(1M), \fBhosts\fR(4), \fBipf\fR(4), \fBipf\fR(1M), \fBipnat\fR(1M), +\fBipfilter\fR(5) |