Patch for WANIPv6FirewallControl:1 service
[igd2-for-linux:igd2-for-linux.git] / linuxigd2 / doc / INSTALL
1 Simple Quick Install Guide
2
3 This install guide is simply a quick helper to let people start testing the new
4 version.  It will be replaced soon with more thourough documentation.
5
6 Installation
7 ------------
8
9 This version of the linux-igd is written in C as opposed to previous version 
10 that was written in C++.  This was done at the requests of many embedded 
11 developers, as well as some of our developers.  The upnp sdk we now use
12 is libupnp-1.6.10, and is written in C as well.  Everything is a 
13 little more uniform now, and should create a smaller, leaner, faster device.
14
15 Step 1 -- Download and install libupnp-1.6.10 source from 
16 http://sourceforge.net/projects/pupnp.  Please install with source 
17 only as we haven't tested against any precompiled versions.  Also, as 
18 the "make install" doesn't quite work as expected, please follow these 
19 instructions to install it properly.
20
21 (Note: See below regarding installing on Fedora Core 5!)
22
23 1. tar -xvzf libupnp-1.6.10.tar.gz
24 2. cd libupnp-1.6.10
25 3. ./configure
26 4. make
27 5. make install
28
29 This process should install libupnp-1.6.10 to our liking (maybe not 
30 someone else's ;-)
31
32 Step 2 -- Obtain the igd2-for-linux software (if for some reason you're reading 
33 this outside the package you should have already gotten, 
34 http://gitorious.org/igd2-for-linux)
35
36 1. tar -xvzf linuxigd-1.0.tgz    (or whatever the version you have is, or CVS)
37 2. To compile using the iptables command to manipulate netfilter
38 tables, just say:
39
40    make 
41
42 To compile with libiptc (part of iptables-devel) to manipulte
43 netfilter tables, say: 
44
45    make HAVE_LIBIPTC=1
46
47 If libiptc is installed in a different directory than /usr/lib,
48 e.g. /usr/local/lib, set LIBIPTC_PREFIX:
49
50    make HAVE_LIBIPTC=1 LIBIPTC_PREFIX=/usr/local
51
52 If libupnp is installed in a different directory than /usr/lib, e.g. /usr/local/lib,
53 set LIBUPNP_PREFIX:
54
55    make LIBUPNP_PREFIX=/usr/local
56
57 3. make install                         (if CVS, remove etc/CVS directory, then do)
58
59 This will install linux-igd as /usr/sbin/upnpd. To install somewhere else,
60 set PREFIX:
61
62    make PREFIX=/usr/local install
63
64 IPv6 support
65 ------------
66
67 igd2-for-linux has been enhanced to be a dual-stack IPv4/IPv6 enabled device
68 that can be used by an IPv6 Control Point to open temporary pinholes in the
69 IPv6 firewall of an IGD:2 (thanks to the WANIPv6FirewallControl service). All
70 the actions defined in the WANIPv6FirewallControl specification have been
71 implemented.
72
73 To enable dual-stack capabilities, the following requirements must be fulfilled:
74    - the libupnp library must be installed and configured to support IPv6
75       (through a call to ./configure --enable-ipv6).
76
77    - ipv6, ip6t_LOG and nf_conntrack modules must be available. They are a part
78       of most of the 2.6.x kernel.
79
80    - ip6tables must be available. You can check this with "which ip6tables".
81
82 System Preparation before starting 
83 ----------------------------------
84
85 1. In order for device discovery to function properly, you must add a 
86 multicast route to the internal interface like so:
87
88 # route add -net 239.0.0.0 netmask 255.0.0.0 eth0      (or whatever your internal
89                                                         interface name is - here
90                                                         eth0)
91
92 2. If your internal interface is firewalled, then allow multicast packets, eg:
93
94 # iptables -t filter -I INPUT 1 -s 224.0.0.0/4 -j ACCEPT
95 # iptables -t filter -I INPUT 1 -d 224.0.0.0/4 -j ACCEPT
96
97 -- Also, if you'd like to see debug information, and please do, as it helps us 
98 resolve your conflicts, perform the following steps:
99
100 A. Add the following lines to bottom of your /etc/syslog.conf file
101
102 # UPnP IGD messages
103 local6.!=debug                                          /var/log/messages
104 local6.*                                                /var/log/upnpd
105
106 This will send all non-debug output to /var/log/messages, and all output including
107 debug output to /var/log/upnpd. Modify as you like.
108
109 B.  service syslog restart  
110                  (or on your system, maybe:
111                                  /etc/rc.d/init.d/syslog restart
112                   or 
113                                 killall -HUP syslog
114
115
116 Daemon Startup
117 --------------
118
119 Now you should be ready to run the daemon.  At this time, your FORWARD rule in 
120 iptables should be set to ACCEPT.  We'll add the forwarding rules back right 
121 away, but first someone needs to tell me what they are, my FORWARD is always 
122 accept.
123  
124 Start the daemon with the following:
125
126 upnpd <ext_ifname> <int_ifname>
127
128 Example: upnpd eth1 eth0          -- Where eth1 is my external interface name
129                                          and eth0 is my internal interface name.
130
131 Where the deamon isn't starting correctly, or exiting soon after with an
132 error, you can start it with 'upnpd -f <ext_ifname> <int_ifname>',
133 preventing it daemonizing into the background; error messages will be sent
134 to stderr also - this is good for testing, but don't forget to have the
135 multicast route setup for it to accept multicast requests.
136
137 To check and see if everything starts up ok, in /var/log/debug you should see 
138 a few debug messages followed by Advertisements Sent, and possibly some 
139 GetNATRSIPStatus and other messages.
140
141 Another way to check this is to look in your Windows XP client under Network 
142 Conections.  You should see an Icon for Internet Connection set to enabled 
143 in there.  If for some reason you don't, first try restarting the daemon.  If 
144 this doesn't work post a message to the forums and we'll try to help you.
145
146
147 REMINDERS and THANK YOUS
148 ------------------------
149 Truth is I can't remember everyone to thank, but I especially want to thank 
150 both Henri Manson and Anders Betner for their development and testing work.  
151 Also Eric Wirt, for helping us test, and providing the winning comments for 
152 switching to C, alongside many others contributing patches and help.
153
154 This is a work in progress.  This code is simply released now for others to 
155 help us debug some problems we are having.  Please, help us out by checking 
156 the forums, answering problems, and giving any advice and suggestions you can 
157 to the open source community.
158
159 Thanks a lot to the users, and to the over 10,000 downloads, and countless 
160 CVS checkouts.  If it weren't for the interest in the program, we wouldn't be 
161 touching it (ok maybe i would, when i got bored or something) :-)
162
163 Cheers all
164
165 Dime
166
167
168 -----------------------------------------------------------------------
169 Notes: Installing on Fedora Core 5
170
171 For Fedora Core 5 there are RPMs available for libupnp 1.3.1 and
172 iptables 1.3.5:
173
174 # yum install iptables-devel libupnp libupnp-devel
175
176 The files are installed in /usr/lib and /usr/include.
177
178 One thing about iptables-devel is that it includes libiptc.a, but not
179 the corresponding header files: ipt_kernel_headers.h and
180 libiptc.h. You will have to get hold of them from a source tarball,
181 e.g.
182 http://www.netfilter.org/projects/iptables/files/iptables-1.3.5.tar.bz2.
183
184 Unpack the source, find the two header files, and place them in an
185 include directory beside linux-igd, like this:
186
187 $ ls ../include/libiptc/
188 ipt_kernel_headers.h  libiptc.h
189
190 After that all you have to do is compile upnpd:
191
192 $ make HAVE_LIBIPTC=1
193
194 And as root:
195
196 # make install
197
198 /Magnus