diff options
Diffstat (limited to 'static/freebsd/man4/ng_patch.4')
| -rw-r--r-- | static/freebsd/man4/ng_patch.4 | 271 |
1 files changed, 271 insertions, 0 deletions
diff --git a/static/freebsd/man4/ng_patch.4 b/static/freebsd/man4/ng_patch.4 new file mode 100644 index 00000000..9c0d7a8e --- /dev/null +++ b/static/freebsd/man4/ng_patch.4 @@ -0,0 +1,271 @@ +.\" Copyright (c) 2010 Maxim Ignatenko <gelraen.ua@gmail.com> +.\" Copyright (c) 2010 Vadim Goncharov <vadimnuclight@tpu.ru> +.\" Copyright (c) 2015 Dmitry Vagin <daemon.hammer@ya.ru> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd November 17, 2015 +.Dt NG_PATCH 4 +.Os +.Sh NAME +.Nm ng_patch +.Nd "trivial mbuf data modifying netgraph node type" +.Sh SYNOPSIS +.In netgraph/ng_patch.h +.Sh DESCRIPTION +The +.Nm patch +node performs data modification of packets passing through it. +Modifications are restricted to a subset of C language operations +on unsigned integers of 8, 16, 32 or 64 bit size. +These are: set to new value (=), addition (+=), subtraction (-=), +multiplication (*=), division (/=), negation (= -), +bitwise AND (&=), bitwise OR (|=), bitwise eXclusive OR (^=), +shift left (<<=), shift right (>>=). +A negation operation is the one exception: integer is treated as signed +and second operand (the +.Va value ) +is not used. +If there is more than one modification operation, they are applied +to packets sequentially in the order they were specified by the user. +The data payload of a packet is viewed as an array of bytes, with a zero offset +corresponding to the very first byte of packet headers, and the +.Va length +bytes beginning from +.Va offset +as a single integer in network byte order. +An additional offset can be optionally +requested at configuration time to account for packet type. +.Sh HOOKS +This node type has two hooks: +.Bl -tag -width ".Va out" +.It Va in +Packets received on this hook are modified according to rules specified +in the configuration and then forwarded to the +.Ar out +hook, if it exists. +Otherwise they are reflected back to the +.Ar in +hook. +.It Va out +Packets received on this hook are forwarded to the +.Ar in +hook without any changes. +.El +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_PATCH_SETDLT Pq Ic setdlt +Sets the data link type on the +.Va in +hook (to help calculate relative offset). Currently, supported types are +.Cm DLT_RAW +(raw IP datagrams, no offset applied, the default) and +.Cm DLT_EN10MB +(Ethernet). DLT_ definitions can be found in +.In net/bpf.h . +If you want to work on the link layer header you must use no additional offset by specifying +.Cm DLT_RAW . +If +.Cm EN10MB +is specified, then the optional additional offset will take into account the Ethernet header and a QinQ header if present. +.It Dv NGM_PATCH_GETDLT Pq Ic getdlt +This control message returns the data link type of the +.Va in +hook. +.It Dv NGM_PATCH_SETCONFIG Pq Ic setconfig +This command sets the sequence of modify operations +that will be applied to incoming data on a hook. +The following +.Vt "struct ng_patch_config" +must be supplied as an argument: +.Bd -literal -offset 4n +struct ng_patch_op { + uint32_t offset; + uint16_t length; /* 1,2,4 or 8 bytes */ + uint16_t mode; + uint64_t value; +}; +/* Patching modes */ +#define NG_PATCH_MODE_SET 1 +#define NG_PATCH_MODE_ADD 2 +#define NG_PATCH_MODE_SUB 3 +#define NG_PATCH_MODE_MUL 4 +#define NG_PATCH_MODE_DIV 5 +#define NG_PATCH_MODE_NEG 6 +#define NG_PATCH_MODE_AND 7 +#define NG_PATCH_MODE_OR 8 +#define NG_PATCH_MODE_XOR 9 +#define NG_PATCH_MODE_SHL 10 +#define NG_PATCH_MODE_SHR 11 + +struct ng_patch_config { + uint32_t count; + uint32_t csum_flags; + uint32_t relative_offset; + struct ng_patch_op ops[]; +}; +.Ed +.Pp +The +.Va csum_flags +can be set to any combination of CSUM_IP, CSUM_TCP, CSUM_SCTP and CSUM_UDP +(other values are ignored) for instructing the IP stack to recalculate the +corresponding checksum before transmitting packet on output interface. +The +.Nm +node does not do any checksum correction by itself. +.Pp +The +.Va offset +value for the +.Vt ng_patch_op +structure is calculated from zero by default (the first byte of +packet headers). +If +.Va relative_offset +is enabled (set to 1) during configuration, the operation will have an +additional amount added to the offset based on the data link type. +.It Dv NGM_PATCH_GETCONFIG Pq Ic getconfig +This control message returns the current set of modify operations, +in the form of a +.Vt "struct ng_patch_config" . +.It Dv NGM_PATCH_GET_STATS Pq Ic getstats +Returns the node's statistics as a +.Vt "struct ng_patch_stats" . +.It Dv NGM_PATCH_CLR_STATS Pq Ic clrstats +Clears the node's statistics. +.It Dv NGM_PATCH_GETCLR_STATS Pq Ic getclrstats +This command is identical to +.Dv NGM_PATCH_GET_STATS , +except that the statistics are also atomically cleared. +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +.Sh EXAMPLES +This +.Nm +node was designed to modify TTL and TOS/DSCP fields in IP packets. +As an example, +suppose you have two adjacent simplex links to a remote network +(e.g.\& satellite), so that the packets expiring in between +will generate unwanted ICMP-replies which have to go forth, not back. +Thus you need to raise TTL of every packet entering link by 2 +to ensure the TTL will not reach zero there. +To achieve this you can set an +.Xr ipfw 8 +rule to use the +.Cm netgraph +action to inject packets which are going to the simplex link into the patch node, by using the +following +.Xr ngctl 8 +script: +.Bd -literal -offset 4n +/usr/sbin/ngctl -f- <<-SEQ + mkpeer ipfw: patch 200 in + name ipfw:200 ttl_add + msg ttl_add: setconfig { count=1 csum_flags=1 ops=[ \e + { mode=2 value=3 length=1 offset=8 } ] } +SEQ +/sbin/ipfw add 150 netgraph 200 ip from any to simplex.remote.net +.Ed +.Pp +Here the +.Dq Li ttl_add +node of type +.Nm +is configured to add (mode +.Dv NG_PATCH_MODE_ADD ) +a +.Va value +of 3 to a one-byte TTL field, which is 9th byte of IP packet header. +.Pp +Another example would be two consecutive modifications of packet TOS +field: say, you need to clear the +.Dv IPTOS_THROUGHPUT +bit and set the +.Dv IPTOS_MINCOST +bit. +So you do: +.Bd -literal -offset 4n +/usr/sbin/ngctl -f- <<-SEQ + mkpeer ipfw: patch 300 in + name ipfw:300 tos_chg + msg tos_chg: setconfig { count=2 csum_flags=1 ops=[ \e + { mode=7 value=0xf7 length=1 offset=1 } \e + { mode=8 value=0x02 length=1 offset=1 } ] } +SEQ +/sbin/ipfw add 160 netgraph 300 ip from any to any not dst-port 80 +.Ed +.Pp +This first does +.Dv NG_PATCH_MODE_AND +clearing the fourth bit and then +.Dv NG_PATCH_MODE_OR +setting the third bit. +.Pp +In both examples the +.Va csum_flags +field indicates that IP checksum (but not TCP or UDP checksum) should be +recalculated before transmit. +.Pp +Note: one should ensure that packets are returned to ipfw after processing +inside +.Xr netgraph 4 , +by setting appropriate +.Xr sysctl 8 +variable: +.Bd -literal -offset 4n +sysctl net.inet.ip.fw.one_pass=0 +.Ed +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ng_ipfw 4 , +.Xr ngctl 8 +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 8.1 . +.Sh AUTHORS +.An "Maxim Ignatenko" Aq gelraen.ua@gmail.com . +.Pp +Relative offset code by +.An "DMitry Vagin" +.Pp +This manual page was written by +.An "Vadim Goncharov" Aq vadimnuclight@tpu.ru . +.Sh BUGS +The node blindly tries to apply every patching operation to each packet +(except those which offset if greater than length of the packet), +so be sure that you supply only the right packets to it (e.g. changing +bytes in the ARP packets meant to be in IP header could corrupt +them and make your machine unreachable from the network). +.Pp +.Em !!! WARNING !!! +.Pp +The output path of the IP stack assumes correct fields and lengths in the +packets - changing them by to incorrect values can cause +unpredictable results including kernel panics. |