1 # OpenWrt package feed for etherwake-nfqueue
4 ## Wake up computers on netfilter match
6 This repository contains the OpenWrt package feed for
7 [etherwake-nfqueue](https://github.com/mister-benjamin/etherwake-nfqueue),
8 a fork of the **etherwake** Wake-on-LAN client, with support to send magic
9 packets only after a queued packet is received from the Linux *nfnetlink_queue*
12 When running **etherwake-nfqueue** on a residential gateway or other type of
13 router, it can wake up hosts on its network based on packet filtering rules.
15 For instance, when your set-top box wants to record a TV programme and
16 tries to access a network share on your NAS, which is in sleep or standby mode,
17 **etherwake-nfqueue** can wake up your NAS. Or when you set up port forwarding
18 to a host on your home network, **etherwake-nfqueue** can wake up your host
19 when you try to access it over the Internet.
21 The documentation below is mostly OpenWrt specific. For more information on
22 etherwake-nfqueue itself and use case examples, please consult its
23 [Readme](https://github.com/mister-benjamin/etherwake-nfqueue/blob/master/README.md).
26 ## Building the package
28 Currently, no pre-built packages are provided. The following assumes that you
29 already have a working OpenWrt build system for your target device.
31 If you haven't, you can follow one of these guides:
33 * If you only want to compile packages, and no firmware image:
34 [Build system – Installation](https://openwrt.org/docs/guide-developer/build-system/install-buildsystem) and
35 [Using the SDK](https://openwrt.org/docs/guide-developer/using_the_sdk)
37 * To quickly build a firmware image off a development snapshot:
38 [Quick Image Building Guide](https://openwrt.org/docs/guide-developer/quickstart-build-images)
40 * Or when you are completely new to using build systems:
41 [Beginners guide to building your own firmware](https://openwrt.org/docs/guide-user/additional-software/beginners-build-guide)
45 **etherwake-nfqueue** depends on these OpenWrt packages:
48 * iptables-mod-nfqueue
50 They will be automatically selected and compiled for you. If they are not
51 installed on your target device, *opkg* will try to resolve dependencies with
52 packages in the repositories.
54 ### Adding the package feed
56 First, you need to add the **etherwake-nfqueue** package feed to your build
57 system. In the root directory of your OpenWrt build system, find the file
58 *feeds.conf* (or *feeds.conf.default* if the former shouldn't exist) and add
59 the following line to it:
62 src-git ethernfq https://github.com/mister-benjamin/etherwake-nfqueue-openwrt.git
65 Then update and install the package feed:
67 user@host:~/openwrt$ scripts/feeds update ethernfq
68 user@host:~/openwrt$ scripts/feeds install -a -p ethernfq
71 After that, enter OpenWrt's configuration menu
73 user@host:~/openwrt$ make menuconfig
75 and enable **etherwake-nfqueue** in the **Network** sub-menu. It can either be selected
76 as built-in (\*) or module (M), depending on your decision to include it into a
77 firmware image or just build the *opkg* package for installation.
79 Then you should be able to compile the package:
81 user@host:~/openwrt$ make package/etherwake-nfqueue/compile
84 The path of the resulting package depends on your selected *Target System*.
85 In case of the Linksys WRT1200AC, it can be found here:
87 bin/packages/arm_cortex-a9_vfpv3/ethernfq/etherwake-nfqueue_2019-09-10-67e9d4ca-1_arm_cortex-a9_vfpv3.ipk
93 One way to install the package is by simply copying it over to the device with *scp*:
95 user@host:~$ scp etherwake-nfqueue_2019-09-10-67e9d4ca-1_arm_cortex-a9_vfpv3.ipk root@gateway:~
97 And then, install it on the device:
99 root@gateway:~# opkg install etherwake-nfqueue_2019-09-10-67e9d4ca-1_arm_cortex-a9_vfpv3.ipk
107 After a fresh installation, no target is configured. Targets are referred
108 to as the hosts to wake up. Multiple targets can coexist.
110 Targets can be configured with OpenWrt's UCI.
112 For example, to add a target called **nas**, with MAC address
113 **00:25:90:00:d5:fd**, which is reachable over the VLAN configured
114 on **eth0.3**, issue this command sequence on your router:
117 uci add etherwake-nfqueue target
118 uci set etherwake-nfqueue.@target[-1].name=nas
119 uci set etherwake-nfqueue.@target[-1].mac=00:25:90:00:d5:fd
120 uci set etherwake-nfqueue.@target[-1].interface=eth0.3
124 For each target, one instance of **etherwake-nfqueue** will be started.
126 Each instance should bind to a different *nfnetlink_queue*. A queue can
127 be referenced by its queue number. Counting starts from 0, which is the default.
128 To use a different queue, provide the **nfqueue_num** option. The
129 following could have been added to the sequence above to use queue 1 instead
133 uci set etherwake-nfqueue.@target[-1].nfqueue_num=1
136 The necessity of a queue number will probably become clear, when the iptables
137 rules are configured in section [Setup firewall rules](#setup-firewall-rules).
139 The full list of options for a target is:
141 | Option | Required | Description |
142 | ----------- | -------- | ------------------------------------------------ |
143 | name | no | Name of the target, e.g. name=example |
144 | mac | yes | MAC address of the host to wake up, e.g. mac=00:22:44:66:88:aa |
145 | nfqueue_num | no | The queue number used for receiving filtered packets, default is nfqueue_num=0 |
146 | interface | no | The interface used for sending the magic packet, default is interface=eth0 |
147 | broadcast | no | Send magic packet to broadcast address, default is broadcast=off |
148 | password | no | Set a password (required by some adapters), e.g. password=00:22:44:66:88:aa or 192.168.1.1 |
149 | enabled | no | Optionally disable the target, default is enabled=true |
151 After committing your changes, the settings are persisted to
152 */etc/config/etherwake-nfqueue*. This is an illustrative example:
154 config etherwake-nfqueue 'setup'
160 option mac '00:25:90:00:d5:fd'
161 option interface 'eth0.3'
164 option name 'xyz-board'
165 option mac '00:25:90:00:d5:fc'
166 option nfqueue_num '1'
167 option enabled 'false'
170 option name 'ip-camera'
171 option mac '00:25:90:00:d5:fb'
172 option nfqueue_num '2'
173 option interface 'eth0.3'
174 option broadcast 'on'
175 option password '00:25:90:00:d5:fb'
178 When all target(s) are configured, restart the *etherwake-nfqueue* service:
180 /etc/init.d/etherwake-nfqueue restart
183 ### Setting up filters
185 Without any firewall rules which tell the kernel to match and add packets
186 to a *nfnetlink_queue*, **etherwake-nfqueue** will never send out a magic
187 packet to wake its target.
191 In order to let the *netfilter* framework of the kernel see the packets,
192 they need to pass through the router. This is usually not the case when
193 hosts are on the same subnet and don't require network layer routing.
194 The data will only pass through the router's switch on the link layer.
196 As a consequence, we can only use packets as a trigger which need to be
197 routed or bridged by the router. Packets being forwarded between WAN
198 and LAN are of that type. For other SOHO use cases, partitioning your
199 network by means of subnets or VLANs might be necessary. The latter
200 is often used to set up a DMZ.
204 * There's a mini howto referring to the **LuCI Web Interface**
205 *(Network -> Switch)* way of configuring VLANs:
206 [How-To: Creating an additional virtual switch on a typical home router](https://openwrt.org/docs/guide-user/network/vlan/creating_virtual_switches)
208 * The manual approach is documented here:
209 [VLAN](https://openwrt.org/docs/guide-user/network/vlan/switch_configuration)
211 Guides to setup a DMZ can be found here:
213 * [Guide to set up DMZ via LUCI](https://forum.openwrt.org/t/guide-to-set-up-dmz-via-luci/21616)
215 * [fw3 DMZ Configuration Using VLANs](https://openwrt.org/docs/guide-user/firewall/fw3_configurations/fw3_dmz)
217 The physical switch layout is device specific. E.g. the layout for the Linksys
218 WRT AC Series is documented
219 [here](https://oldwiki.archive.openwrt.org/toh/linksys/wrt_ac_series#switch_layout).
222 Using two LANs or VLANs with the same network address and bridging them again
223 is a trick to setup a transparent (or bridging) firewall on the same subnet.
224 This way, packets can be seen by *netfilter* on the router even if the
225 packets are not routed. Unfortunately this doesn't help when the host
226 which we want to wake up is offline, as the ARP requests for the destination
227 IP address are not answered and thus the client trying to reach out to its
228 destination will not send any *network layer* packets. We could use *arptables*
229 instead to wake the host when someone requests its MAC address, but this
230 would probably happen too often and no fine-grained control would be possible.
232 As a workaround, it might be possible to configure a static ARP entry on your
233 router (untested), e.g. with:
235 ip neigh add 192.168.0.10 lladdr 00:25:90:00:d5:fd nud permanent dev eth0.3
237 Note that this requires the *ip-full* OpenWrt package to be installed.
239 To make your firewall rules work with bridging, you need to install the
240 *kmod-br-netfilter* package and add `net.bridge.bridge-nf-call-iptables=1`
241 to */etc/sysctl.conf*.
244 #### Setup firewall rules
246 One way to setup custom firewall rules in OpenWrt is through its
247 */etc/firewall.user* script. This file can also be edited by means of
248 the **LuCI Web Interface** *(Network -> Firewall -> Custom Rules)*.
250 The file is interpreted as a shell script, so we can simply use **iptables**
251 to add our custom firewall rules.
255 # Internal uci firewall chains are flushed and recreated on reload, so
256 # put custom rules into the root chains e.g. INPUT or FORWARD or into the
257 # special user chains, e.g. input_wan_rule or postrouting_lan_rule.
260 Refer to [Packet flow](https://oldwiki.archive.openwrt.org/doc/uci/firewall#packet_flow)
261 for usable chains. In the example below, the chains *forwarding_lan_rule* and
262 *forwarding_wan_rule* are used. To inspect the rule sets of the different tables, one can
266 iptables --list # default is --table filter
267 iptables --table nat --list
268 iptables --table mangle --list
269 iptables --table raw --list # requires kmod-ipt-raw
272 The following is an example of what could be added to */etc/firewall.user*:
275 iptables --insert forwarding_lan_rule\
276 --protocol tcp --in-interface=br-lan --out-interface=eth0.3\
277 --destination 192.168.0.10 --destination-port 445\
278 --match conntrack --ctstate NEW\
279 --match limit --limit 3/hour --limit-burst 1\
280 --jump NFQUEUE --queue-num 0 --queue-bypass\
281 --match comment --comment "Wake up NAS on LAN SMB"
282 iptables --insert forwarding_lan_rule\
283 --protocol tcp --in-interface=br-lan --out-interface=eth0.3\
284 --destination 192.168.0.11 --match multiport --destination-ports 515,54921,631\
285 --match conntrack --ctstate NEW\
286 --match limit --limit 3/hour --limit-burst 1\
287 --jump NFQUEUE --queue-num 0 --queue-bypass\
288 --match comment --comment "Wake up NAS on print request"
289 iptables --insert forwarding_lan_rule\
290 --protocol udp --in-interface=br-lan --out-interface=eth0.3\
291 --destination 192.168.0.11 --destination-port 161\
292 --match conntrack --ctstate NEW\
293 --match limit --limit 3/hour --limit-burst 1\
294 --jump NFQUEUE --queue-num 0 --queue-bypass\
295 --match comment --comment "Wake up NAS on print request"
296 iptables --insert forwarding_wan_rule\
297 --protocol tcp --in-interface=eth1.2 --out-interface=eth0.3\
298 --destination 192.168.0.10 --destination-port 22\
299 --match conntrack --ctstate NEW\
300 --match limit --limit 3/hour --limit-burst 1\
301 --jump NFQUEUE --queue-num 0 --queue-bypass\
302 --match comment --comment "Wake up NAS on WAN SSH"
305 In this example, packets are filtered based on the protocol, their input
306 and output interfaces, their destination (IP address) and their destination
309 The option `--match conntrack --ctstate NEW` only matches packets of a new
310 connection and `--match limit --limit 3/hour --limit-burst 1` limits the
311 amount of packets that are matched. The latter option roughly matches
312 only one packet per 20 minutes. The intention here is to not be too intrusive
313 and avoid sending a lot of magic packets.
315 The `--jump NFQUEUE --queue-num 0` options tell the *netfilter*
316 framework to enqueue a matching packet to the NFQUEUE number 0. In this
317 example, all four rules send the matching packets into queue 0. The
318 additional option `--queue-bypass` helps in the situation, when
319 **etherwake-nfqueue** isn't running. Packets will then be handled
320 as if the rule wasn't present.
325 To disable targets, first find their index:
327 uci show etherwake-nfqueue
330 Then set its *enabled* option to false and restart the service.
331 For index 0, it can be done like this:
333 uci set etherwake-nfqueue.@target[0].enabled=false
334 /etc/init.d/etherwake-nfqueue restart
342 In order to see what's going on in syslog and get some debug output when
343 starting the service, enable etherwake-nfqueue's debug mode:
345 uci set etherwake-nfqueue.setup.debug=on
347 In another user session tail the log:
351 And then restart the service:
353 /etc/init.d/etherwake-nfqueue restart
356 ### Inspect netfilter
358 To inspect the working of your firewall rules, you can print statistics
359 of the chains you used, e.g.:
361 iptables --verbose --list forwarding_lan_rule
364 If you happen to have the *procps-ng-watch* package installed, you can watch
367 watch iptables --verbose --list forwarding_lan_rule
370 To see, if your queues are in place, use:
372 cat /proc/net/netfilter/nfnetlink_queue
375 ## Potential improvements
377 * Add **LuCI Web Interface** configuration frontend for *targets* and *filter rules*
378 * Add an option to set *nice* values for instances