doc/actions/mirred-usage

   1
   2 Very funky action. I do plan to add to a few more things to it
   3 This is the basic stuff. Idea borrowed from the way ethernet switches
   4 mirror and redirect packets. The main difference with say a vannila
   5 ethernet switch is that you can use u32 classifier to select a
   6 flow to be mirrored. High end switches typically can select based
   7 on more than just a port (eg a 5 tuple classifier). They may also be
   8 capable of redirecting.
   9
  10 Usage:
  11
  12 mirred <DIRECTION> <ACTION> [index INDEX] <dev DEVICENAME>
  13 where:
  14 DIRECTION := <ingress | egress>
  15 ACTION := <mirror | redirect>
  16 INDEX is the specific policy instance id
  17 DEVICENAME is the devicename
  18
  19 Direction:
  20 - Ingress is not supported at the moment. It will be in the
  21 future as well as mirror/redirecting to a socket.
  22
  23 Action:
  24 - Mirror takes a copy of the packet and sends it to specified
  25 dev ("port" in ethernet switch/bridging terminology)
  26 - redirect
  27 steals the packet and redirects to specified destination dev.
  28
  29 What NOT to do if you dont want your machine to crash:
  30 ------------------------------------------------------
  31
  32 Do not create loops!
  33 Loops are not hard to create in the egress qdiscs.
  34
  35 Here are simple rules to follow if you dont want to get
  36 hurt:
  37 A) Do not have the same packet go to same netdevice twice
  38 in a single graph of policies. Your machine will just hang!
  39 This is design intent _not a bug_ to teach you some lessons.
  40
  41 In the future if there are easy ways to do this in the kernel
  42 without affecting other packets not interested in this feature
  43 I will add them. At the moment that is not clear.
  44
  45 Some examples of bad things NOT to do:
  46 1) redirecting eth0 to eth0
  47 2) eth0->eth1-> eth0
  48 3) eth0->lo-> eth1-> eth0
  49
  50 B) Do not redirect from one IFB device to another.
  51 Remember that IFB is a very specialized case of packet redirecting
  52 device. Instead of redirecting it puts packets at the exact spot
  53 on the stack it found them from.
  54 Redirecting from ifbX->ifbY will actually not crash your machine but your
  55 packets will all be dropped (this is much simpler to detect
  56 and resolve and is only affecting users of ifb as opposed to the
  57 whole stack).
  58
  59 In the case of A) the problem has to do with a recursive contention
  60 for the devices queue lock and in the second case for the transmit lock.
  61
  62 Some examples:
  63 -------------
  64
  65 1) Mirror all packets arriving on eth0 to be sent out on eth1.
  66 You may have a sniffer or some accounting box hooked up on eth1.
  67
  68 ---
  69 tc qdisc add dev eth0 ingress
  70 tc filter add dev eth0 parent ffff: protocol ip prio 10 u32 \
  71 match u32 0 0 flowid 1:2 action mirred egress mirror dev eth1
  72 ---
  73
  74 If you replace "mirror" with "redirect" then not a copy but rather
  75 the original packet is sent to eth1.
  76
  77 2) Host A is hooked  up to us on eth0
  78
  79 # redirect all packets arriving on ingress of lo to eth0
  80 ---
  81 tc qdisc add dev lo ingress
  82 tc filter add dev lo parent ffff: protocol ip prio 10 u32 \
  83 match u32 0 0 flowid 1:2 action mirred egress redirect dev eth0
  84 ---
  85
  86 On host A start a tcpdump on interface connecting to us.
  87
  88 on our host ping -c 2 127.0.0.1
  89
  90 Ping would fail since all packets are heading out eth0
  91 tcpudmp on host A would show them
  92
  93 if you substitute the redirect with mirror above as in:
  94 tc filter add dev lo parent ffff: protocol ip prio 10 u32 \
  95 match u32 0 0 flowid 1:2 action mirred egress mirror dev eth0
  96
  97 Then you should see the packets on both host A and the local
  98 stack (i.e ping would work).
  99
 100 3) Even more funky example:
 101
 102 #
 103 #allow 1 out 10 packets on ingress of lo to randomly make it to the
 104 # host A (Randomness uses the netrand generator)
 105 #
 106 ---
 107 tc filter add dev lo parent ffff: protocol ip prio 10 u32 \
 108 match u32 0 0 flowid 1:2 \
 109 action drop random determ ok 10\
 110 action mirred egress mirror dev eth0
 111 ---
 112
 113 4)
 114 # for packets from 10.0.0.9 going out on eth0 (could be local
 115 # IP or something # we are forwarding) -
 116 # if exceeding a 100Kbps rate, then redirect to eth1
 117 #
 118
 119 ---
 120 tc qdisc add dev eth0 handle 1:0 root prio
 121 tc filter add dev eth0 parent 1:0 protocol ip prio 6 u32 \
 122 match ip src 10.0.0.9/32 flowid 1:16 \
 123 action police rate 100kbit burst 90k ok \
 124 action mirred egress mirror dev eth1
 125 ---
 126
 127 A more interesting example is when you mirror flows to a dummy device
 128 so you could tcpdump them (dummy by defaults drops all packets it sees).
 129 This is a very useful debug feature.
 130
 131 Lets say you are policing packets from alias 192.168.200.200/32
 132 you dont want those to exceed 100kbps going out.
 133
 134 ---
 135 tc qdisc add dev eth0 handle 1:0 root prio
 136 tc filter add dev eth0 parent 1: protocol ip prio 10 u32 \
 137 match ip src 192.168.200.200/32 flowid 1:2 \
 138 action police rate 100kbit burst 90k drop
 139 ---
 140
 141 If you run tcpdump on eth0 you will see all packets going out
 142 with src 192.168.200.200/32 dropped or not (since tcpdump shows
 143 all packets being egressed).
 144 Extend the rule a little to see only the packets making it out.
 145
 146 ---
 147 tc qdisc add dev eth0 handle 1:0 root prio
 148 tc filter add dev eth0 parent 1: protocol ip prio 10 u32 \
 149 match ip src 192.168.200.200/32 flowid 1:2 \
 150 action police rate 10kbit burst 90k drop \
 151 action mirred egress mirror dev dummy0
 152 ---
 153
 154 Now fire tcpdump on dummy0 to see only those packets ..
 155 tcpdump -n -i dummy0 -x -e -t
 156
 157 Essentially a good debugging/logging interface (sort of like
 158 BSDs speacialized log device does without needing one).
 159
 160 If you replace mirror with redirect, those packets will be
 161 blackholed and will never make it out.
 162
 163 cheers,
 164 jamal