1aaa92801d16b885aaf53756269d3ea3b73f3b7e
[olsrd.git] / README-WIN32.txt
1
2                          olsr.org for Windows
3                          --------------------
4
5 Welcome to the Windows release of olsr.org. Let's have a quick look at
6 how this version differs from the original Linux version.
7
8
9                         ***** Stability *****
10
11   While the Windows version looks pretty stable in basic scenarios, it
12   hasn't yet received the extensive testing by the OLSR community that
13   the Linux version has gone through. So, if you experience any
14   strange behaviour, it's probably my fault. In this case please bear
15   with me and use the issue tracker on SourceForge. I'll then do my
16   best to find and fix the problem with your assistance. The
17   SourceForge homepage for olsrd.org has the following URL.
18
19                 http://sourceforge.net/projects/olsrd/
20
21
22                     ***** Configuration file *****
23
24   If you do not specify a configuration file, the OLSR server
25   ("olsrd.exe") by default attempts to use "olsrd.conf" in your
26   Windows directory, e.g. "C:\WINDOWS\olsrd.conf".
27
28
29                      ***** Interface naming *****
30
31   On Linux network interfaces have nice names like "eth0". In
32   contrast, Windows internally identifies network interfaces by pretty
33   awkward names, for example:
34
35     "{EECD2AB6-C2FC-4826-B92E-CAA53B29D67C}"
36
37   Hence, the Windows version implements its own naming scheme that
38   maps each internal name to a made-up name like "if03", which is
39   easier to memorize. Simply invoke the OLSR server as follows to
40   obtain its view of your interfaces:
41
42     olsrd.exe -int
43
44   This lists the made-up interface names along with their current IP
45   addresses to enable you to find out which made-up interface name
46   corresponds to which of your physical interfaces.
47
48   For techies: The made-up names consist of the string "if" followed
49   by a two-digit hex representation of the least significant byte of
50   the Windows-internal interface index, which should be different for
51   each interface and thus make each made-up name unique. Again, this
52   is undocumented and this assumption may be wrong in certain
53   cases. So, if the "-int" option reports two interfaces that have the
54   same name, please do let me know.
55
56
57                      ***** Running the GUI *****
58
59   We now have a native Windows GUI. No more GTK+. Simply make sure
60   that "Switch.exe", "Shim.exe", and "olsrd.exe" are located in the
61   same directory and run "Switch.exe". "Shim.exe" is just an auxiliary
62   console application that is required by "Switch.exe".
63
64   The GUI is pretty self-explanatory. The three buttons on the lower
65   right of the GUI window start the OLSR server, stop the OLSR server,
66   and exit the GUI.
67
68   Use the "Settings" tab to specify the options that the GUI uses to
69   run the OLSR server "olsrd.exe". When you click "Start" the GUI
70   generates a temporary configuration file from the information given
71   by the "Settings" tab. This temporary configuration file is passed
72   to the OLSR server via its "-f" option. If you need options that
73   cannot be controlled via the "Settings" tab, simply add them to the
74   "Manual additions" text box as you would add them to a configuration
75   file, e.g. "HNA 192.168.0.0 255.255.255.0". The contents of this
76   text box are appended to the temporary configuration file when it is
77   generated.
78
79   "Offer Internet connection" is only available if you have an
80   Internet connection, i.e. if you have a default route configured. If
81   you tick this option, "HNA 0.0.0.0 0.0.0.0" is added to the
82   temporary configuration file, allowing other nodes in the OLSR
83   network to use your Internet connection.
84
85   Gateway tunnelling and IP version 6 cannot currently be selected, as
86   support for these features is not yet complete in the Windows
87   version.
88
89   The three buttons on the lower right of the "Settings" tab open
90   previously saved settings, save the current settings to a
91   configuration file, and reset the current settings to default
92   values. When opening a saved configuration file, the GUI adds lines
93   that it cannot interpret to the "Manual additions" text box.
94
95   If you start the GUI with the path to a configuration file as the
96   only command line argument, the GUI opens the given configuration
97   file and runs the OLSR server with this configuration. So, saving a
98   configuration file with a ".olsr" extension, for example, and making
99   "Switch.exe" the handler for ".olsr" files enables you to run the
100   OLSR server with a simple double click on the configuration file.
101
102   The "Output" tab shows the output of the currently running OLSR
103   server. When you click "Start" The GUI simply invokes the OLSR
104   server "olsrd.exe" and intercepts its console output. Use the four
105   buttons on the upper right of the tab to freeze the output, resume
106   frozen output, save the output to a file, or clear the output.
107
108   The "Nodes" tab contains information about the nodes that the OLSR
109   server currently knows about. If you click on the address of a node
110   in the "Node list" list box, the GUI populates the three "Node
111   information" list boxes on the right with the multi-point relays of
112   the selected node (MPR), the interfaces of the selected node (MID),
113   and the non-OLSR networks accessible via the selected node (HNA).
114
115   The "Routes" tab shows the routes that the currently running OLSR
116   server has added.
117
118
119                    ***** Running the GTK+ GUI *****
120
121   Please use the native Windows GUI instead. The GTK+ GUI is no longer
122   supported on Windows.
123
124
125                      ***** Missing features *****
126
127   The Windows version currently does not implement the following
128   features known from the Linux release.
129
130     * IPv6.
131
132     * Link layer statistics.
133
134     * WLAN interface detection. The Windows port does not recognize
135       whether an interface is a WLAN interface or a wired LAN
136       interface. All specified interfaces are assumed to be WLAN
137       interfaces. So, for example, specifying a different HELLO
138       interval for wired interfaces does not currently work. Instead,
139       the HELLO interval for WLAN interfaces is always used.
140
141     * Gateway tunnelling. This is currently experimental on
142       Windows. It is intended to work reliably on Windows 2000 and
143       Windows XP in a later version. It is based on the ipinip.sys
144       device driver that comes with these operating systems, but which
145       is completely undocumented. I've figured out how to use the
146       device driver, but it looks like I've still missed one or two
147       little things. So, tunnelling might work on your OS version, but
148       it might as well not work. Unfortunately, currently I do not
149       even know why it works on some systems and fails on other
150       systems.
151
152       If you are brave, do the following, but be prepared for a BSOD
153       (blue screen of death) as a worst-case scenario. This is nothing
154       for the faint of the heart. :-) Never try this on production
155       systems.
156
157         * Start the IP-in-IP tunnel driver before running the OLSR
158           server:
159
160             net start ipinip
161
162         * When the OLSR server reports that the tunnel has been
163           established, find out, which interface index the tunnel
164           device has been assigned:
165
166             route print
167
168         * Let's assume that the interface index is 0x1234 and the
169           gateway's IP address is 1.2.3.4. Manually add a default
170           route through the other end of the tunnel:
171
172             route add 0.0.0.0 mask 0.0.0.0 1.2.3.4 if 0x1234
173
174         * Try to ping somebody beyond the gateway and let me know
175           whether it works. If it doesn't and if you have time, please
176           do a packet dump for me to determine whether IP-in-IP
177           packets are leaving your system and, if yes, what they look
178           like.
179
180       If you know of any freely available tunnel driver for Windows,
181       please let me know. We could then think about switching from the
182       native ipinip.sys driver to an alternative driver, perhaps one
183       that also works on Windows 9x.
184
185       If you are the Microsoft person that is responsible for the
186       tunnel driver, please have a look at my code in
187       src/win32/tunnel.* and tell me what I'm missing.
188
189     * Multiple interfaces in the same subnet. As they all share the
190       same subnet broadcast address, there's no way to tell Windows
191       which of these interfaces to send OLSR packets through. I guess
192       that we'll have to come up with a device driver that sits
193       between the TCP/IP stack and the network adapters and that
194       directs outbound OLSR packets to the correct interface after
195       they've been routed by the TCP/IP stack. Looks like there isn't
196       any other solution on Windows.
197
198   There are also some Windows-specific features that I currently work
199   on, but which have not made it into this release.
200
201     * The option to run the OLSR server as a Windows service on
202       Windows NT, 2000, and XP.
203
204
205                         ***** Compiling *****
206
207   To compile the Windows version of the OLSR server or the dot_draw
208   plugin you need a Cygwin installation with a current version of GCC
209   and Mingw32. Each of the corresponding subdirectories contains a
210   shell script named "mkmf.sh" that takes "Makefile.win32.in" as its
211   input, appends the dependencies, and outputs "Makefile.win32". Then
212   simply say
213
214     make -f Makefile.win32 clean
215
216   to remove any compiled files or
217
218     make -f Makefile.win32 mclean
219
220   to remove any compiled files and the generated makefile. Say
221
222     make -f Makefile.win32
223
224   to compile the source code.
225
226   The GUI has to be compiled with Visual C++ 6. Simply open the
227   "Frontend.dsw" workspace in the Visual C++ 6 IDE. Then compile
228   "Frontend" and "Shim", which creates "Switch.exe" and
229   "Shim.exe". Copy these two executables into the same directory as
230   "olsrd.exe" and you are ready to go.
231
232 Well, thanks for using an early release of a piece of software and
233 please bear with me if there are any problems. Please do also feel
234 free to suggest any features that you'd like to see in future
235 releases.
236
237 Thomas Lopatic <thomas@lopatic.de>, 2004-09-14