release/src/router/miniupnpd/INSTALL

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