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