release/src/router/miniupnpd/INSTALL

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