NAME¶
ng_patch —
trivial mbuf data modifying
netgraph node type
SYNOPSIS¶
#include <netgraph/ng_patch.h>
DESCRIPTION¶
The
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
value) is not used. There may be several modification
operations, they are all applied to a packet sequentially in order they were
specified by user. Data payload of packet is viewed as array of bytes, with
zero offset corresponding to the very first byte of packet headers, and
length bytes beginning from
offset
are taken as a single integer in network byte order.
HOOKS¶
This node type has two hooks:
- in
- Packets received on this hook are modified according to
rules specified in config and then forwarded to out
hook, if it exists and connected. Otherwise they are reflected back to the
in hook.
- out
- Packets received on this hook are forwarded to
in hook without any changes.
CONTROL MESSAGES¶
This node type supports the generic control messages, plus the following:
NGM_PATCH_SETCONFIG
(setconfig
)
- This command sets the sequence of modify operations that
will be applied to incoming data on a hook. The following
struct ng_patch_config must be supplied as an
argument:
struct ng_patch_op {
uint64_t value;
uint32_t offset;
uint16_t length; /* 1,2,4 or 8 bytes */
uint16_t mode;
};
/* 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;
struct ng_patch_op ops[];
};
The 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 ng_patch
node does not do any checksum correction by itself.
NGM_PATCH_GETCONFIG
(getconfig
)
- This control message obtains current set of modify
operations, returned as struct ng_patch_config.
NGM_PATCH_GET_STATS
(getstats
)
- Returns node statistics as a struct
ng_patch_stats.
NGM_PATCH_CLR_STATS
(clrstats
)
- Clear node statistics.
NGM_PATCH_GETCLR_STATS
(getclrstats
)
- This command is identical to
NGM_PATCH_GET_STATS
, except that the statistics
are also atomically cleared.
SHUTDOWN¶
This node shuts down upon receipt of a
NGM_SHUTDOWN
control message, or when all hooks have been disconnected.
EXAMPLES¶
The
ng_patch node allows to modify TTL and TOS/DSCP fields in
IP packets. Suppose you have two adjacent simplex links to 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 link by 2 to ensure the TTL will not reach
zero there. So you setup
ipfw(8) rule with
netgraph action to inject packets going to other end of
simplex link by the following
ngctl(8) script:
/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=[ \
{ mode=2 value=3 length=1 offset=8 } ] }
SEQ
/sbin/ipfw add 150 netgraph 200 ip from any to simplex.remote.net
Here “
ttl_add
” node of type
ng_patch configured to add (mode
NG_PATCH_MODE_ADD
) a
value of 3
to a one-byte TTL field, which is 9th byte of IP packet header.
Another example would be two consecutive modifications of packet TOS field: say,
you need to clear the
IPTOS_THROUGHPUT
bit and set the
IPTOS_MINCOST
bit. So you do:
/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=[ \
{ mode=7 value=0xf7 length=1 offset=1 } \
{ mode=8 value=0x02 length=1 offset=1 } ] }
SEQ
/sbin/ipfw add 160 netgraph 600 ip from any to any not dst-port 80
This first does
NG_PATCH_MODE_AND
clearing the fourth
bit and then
NG_PATCH_MODE_OR
setting the third bit.
In both examples the
csum_flags field indicates that IP
checksum (but not TCP or UDP checksum) should be recalculated before transmit.
Note: one should ensure that packets are returned to ipfw after processing
inside
netgraph(4), by setting appropriate
sysctl(8) variable:
sysctl net.inet.ip.fw.one_pass=0
SEE ALSO¶
netgraph(4),
ng_ipfw(4),
ngctl(8)
HISTORY¶
The
ng_patch node type was implemented in
FreeBSD 8.1.
AUTHORS¶
Maxim Ignatenko ⟨gelraen.ua@gmail.com⟩.
This manual page was written by
Vadim Goncharov ⟨vadimnuclight@tpu.ru⟩.
BUGS¶
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).
!!! WARNING !!!
Output path of the IP stack assumes correct fields and lengths in the packets -
changing them by mistake to incorrect values can cause unpredictable results
including kernel panics.