1MiniUPnP project. 2(c) 2006-2014 Thomas Bernard 3Homepage : http://miniupnp.free.fr/ 4Mirror: http://miniupnp.tuxfamily.org/ 5github: https://github.com/miniupnp/miniupnp 6 7miniupnpd is still under active developpement. This documentation is 8likely to be a little outdated when you read it. So please go on the 9web forum http://miniupnp.tuxfamily.org/ if you need more information. 10 11================================ *BSD/pf ================================= 12To Build and Install : 13 14- use BSD make to compile. 15- you can first 'make config.h' then edit config.h to your preferences and 16 finally 'make' 17 Alternatively to editing config.h, options can be passed to genconfig.sh 18 For more details : 19 > ./genconfig.sh -h 20- add "rdr-anchor miniupnpd" or/and "anchor miniupnpd" lines to /etc/pf.conf 21 (Since OpenBSD 4.7, rdr-anchor lines are no longer used and should be 22 removed, leaving only the anchor lines). 23- some FreeBSD users reported that it is also necessary for them 24 to explicitly allow udp traffic on 239.0.0.0/8 by adding the two following 25 lines to /etc/pf.conf : 26 pass out on $int_if from any to 239.0.0.0/8 keep state 27 pass in on $int_if from any to 239.0.0.0/8 keep state 28- dont forget to " pfctl -f /etc/pf.conf " 29- you can check your modifications are taken into accout with 30 "pfctl -s nat" and "pfctl -s rule". Look for the "rdr-anchor miniupnpd" 31 (if applicable) and/or "anchor miniupnpd" lines. 32- install as root using : 33 # make install 34 or 35 # PREFIX=/usr/local make install 36- run as root : The daemon needs rights to modify pf rules. 37 38edit the /etc/miniupnpd.conf file to set options. Almost all options are also 39available through command line switches. 40To stop the daemon use : 41 > kill `cat /var/run/miniupnpd.pid` 42 43=========================== *BSD,*Solaris/ipf ============================= 44 45genconfig.sh and the Makefile try to detect wether ipf or pf should be 46used. If it fails, edit config.h and Makefile by hand. 47In Makefile, the FWNAME variable value should be pf or ipf. 48Installation steps are allmost the same as with pf. 49 50*Solaris users would be interested in reading informations from : 51http://blogs.sun.com/avalon/category/IPFilter 52 53============================= Mac OS X/ipfw =============================== 54 55- To enable non standard compilation options, 56 > ./genconfig.sh -h 57 Or edit config.h after it has been generated by genconfig.sh 58- use 'bsdmake' (if available) or 'make -f Makefile.macosx' to build 59 60============================== Mac OS X/pf ================================ 61 62Starting with Mac OS X 10.7 Lion, pf replaced ipfw as the OS X firewall. 63also bsdmake is not available anymore. 64Make sure you have installed the Xcode commande line tools (from the 65Xcode Preferences menu or using 'xcode-select --install' command) 66 67You'll need to download xnu sources : https://github.com/opensource-apple/xnu 68> INCLUDES="-I.../xnu/bsd -I.../xnu/libkern" make -f Makefile.macosx 69 70============================ Linux/netfilter ============================== 71To Build and install : 72 73- make sure you have libiptc available on your system : 74 if you are using debian, "apt-get install iptables-dev" 75 Some versions of the iptables-dev package don't include the 76 necessary files : read "how to get libiptc with its headers on debian" below. 77 In anycase, libiptc is available in iptables sources packages 78 from http://netfilter.org 79- edit and run netfilter/iptables_init.sh shell script. 80 This script must allways be run before the daemon 81 to set up intial rules and chains. 82- Build and edit the config.h file 83 > make -f Makefile.linux config.h 84 > vi config.h 85- Build the daemon 86 > make -f Makefile.linux 87 If not using iptables from your system, 88 > IPTABLESPATH=/path/to/iptables-1.4.1 make -f Makefile.linux 89- install as root using : 90 > make -f Makefile.linux install 91- A miniupnpd script should be installed to /etc/init.d 92 and the configuration files to /etc/miniupnpd 93- anytime, you can use the netfilter/iptables_flush.sh 94 script to flush all rules added by the daemon. 95- after killing the daemon, you can get back to 96 iptables initial state by runing the netfilter/iptables_removeall.sh 97 script. Don't forget to edit the script to your convinience. 98 99NOTE: a /etc/init.d/miniupnpd script will be installed. 100 If it suits you, you can use is with start, stop or restart argument. 101 # /etc/init.d/miniupnpd restart 102 103 104How to get libiptc with its headers on debian : 105(Note: that should be useless now that netfilter/tiny_nf_nat.h is included) 106- Use apt-get to get sources : 107 > apt-get source iptables 108 you should then have an iptables-x.x.x/ directory. 109- configure and compile : 110 > cd iptables-x.x.x/ 111 > ./configure --enable-static 112 > make 113- it is now possible to compile miniupnpd using the following command : 114 > IPTABLESPATH=/path/to/iptables-x.x.x make -f Makefile.linux 115 116=========================== Configuration ============================= 117Edit the /etc/miniupnpd.conf file to set options. Almost all options are 118also available through command line switches. 119 120Miniupnpd supports some kind of security check for allowing or disallowing 121redirection to be made. The UPnP permission rules are read from the 122miniupnpd.conf configuration file. 123When a new redirection is requested, permission rules are evaluated in 124top-down order and the first permission rule matched gives the response : 125redirection allowed or denied. If no rule is matching, the redirection is 126allowed, so it is a good practice to have a "catch all" deny permission 127rule at the end of your permission ruleset. 128Sample permission ruleset : 129allow 4662-4672 192.168.1.34/32 4662-4672 130deny 0-65535 192.168.1.34/32 0-65535 131allow 1024-65535 192.168.1.0/24 1024-65535 132deny 0-65535 0.0.0.0/0 0-65535 133With this ruleset, redirections are allowed only for host on the subnet 134192.168.1.0/255.255.255.0 for the ports 1024 or above. There is an exception 135for the host 192.168.1.34 for which only redirections from/to port 4662 to 1364672 are allowed. 137 138You can generate the uuid for your UPnP device with the uuidgen available 139under linux. The following following OpenBSD package is also providing 140a "uuid" tool : 141http://www.openbsd.org/4.0_packages/i386/uuid-1.5.0.tgz-long.html 142An web based uuid generator is also available : 143http://kruithof.xs4all.nl/uuid/uuidgen 144 145On linux systems, one could also use the command 146'cat /proc/sys/kernel/random/uuid' to generate an uuid. 147 148More simple, use the genuuid makefile target : 149> make genuuid 150or 151> make -f Makefile.linux genuuid 152This target is needed by the "install" target, so it is done automatically 153during install. 154 155To stop the daemon use : 156 # kill `cat /var/run/miniupnpd.pid` 157or if your linux system use /etc/init.d/ 158 # /etc/init.d/miniupnpd stop 159 160 161