Comments are now allowed within the plugin block
[olsrd.git] / README-WIN32.txt
index 1397bfe..58ae54b 100644 (file)
-
-                        UniK OLSR for Windows
-                        ---------------------
-
-Welcome to the first Windows release. Let's have a quick look at how
-this version is different from the original Linux version.
-
-                        ***** Stability *****
-
-  While the Windows version looks pretty stable in basic scenarios, it
-  hasn't yet received the extensive testing by the OLSR community that
-  the Linux version has gone through. So, if you experience any
-  strange behaviour, it's probably my fault. In this case please bear
-  with me and send me a bug report via the OLSR-users mailing
-  list. I'll then do my best to find and fix the problem with your
-  assistance.
-
-                    ***** Configuration file *****
-
-  If you do not specify a configuration file, the OLSR server by
-  default attempts to use "olsrd.conf" in your Windows directory,
-  e.g. "C:\WINDOWS\olsrd.conf".
-
-                     ***** Interface naming *****
-
-  On Linux network interfaces have nice names like "eth0". In
-  contrast, Windows internally identifies network interfaces by pretty
-  awkward names, for example:
-
-    "{EECD2AB6-C2FC-4826-B92E-CAA53B29D67C}"
-
-  Hence, the Windows version implements its own naming scheme that
-  maps each internal name to a made-up name like "if03", which is
-  easier to memorize. Simply invoke the OLSR executable as follows to
-  obtain the OLSR server's view of your interfaces:
-
-    olsrd.exe -int
-
-  This lists the made-up interface names along with their current IP
-  addresses to enable you to find out which made-up interface name
-  belongs to which of your physical interfaces.
-
-  For techies: The made-up names consist of the string "if" followed
-  by a two-digit hex representation of the least significant byte of
-  the Windows-internal interface index, which should be different for
-  each interface and thus make each made-up name unique. Again, this
-  is undocumented and this assumption may be wrong in certain
-  cases. So, if the "-int" option reports two interfaces that have the
-  same name, please do let me know.
-
-                     ***** Running the GUI *****
-
-  The GUI is a GTK+ application and thus requires the GTK+ runtime
-  environment to work. The Windows port of GTK+ is available from the
-  following URL:
-
-    http://www.gimp.org/~tml/gimp/win32/downloads.html
-
-  You need to download the following packages or newer versions of
-  these packages:
-
-    - atk-1.6.0.zip
-    - gettext-runtime-0.13.1.zip
-    - glib-2.4.5.zip
-    - gtk+-2.4.7.zip
-    - libiconv-1.9.1.bin.woe32.zip
-    - pango-1.4.1.zip
-
-  Simply unzip the files into a directory that you've created,
-  e.g. into "GUI". Then copy the "olsrd-gui.exe" file into the "bin"
-  subdirectory, e.g. into "GUI\bin", and run it from there.
-
-                     ***** Missing features *****
-
-  The Windows version currently does not implement the following
-  features known from the Linux release.
-
-    * IPv6. This will probably be in version 0.4.7.
-
-    * Link layer statistics.
-
-    * WLAN interface detection. The Windows port does not recognize
-      whether an interface is a WLAN interface or a wired LAN
-      interface.  All specified interfaces are assumed to be WLAN
-      interfaces. So, for example, specifying a different HELLO
-      interval for wired interfaces does not currently work. Instead,
-      the HELLO interval for WLAN interfaces is always used.
-
-    * Gateway tunnelling. This is currently experimental on
-      Windows. It is intended to work reliably on Windows 2000 and
-      Windows XP in version 0.4.7. It is based on the ipinip.sys
-      device driver that comes with these operating systems, but which
-      is completely undocumented. I've figured out how to use the
-      device driver, but it looks like I've still missed one or two
-      little things. So, tunnelling might work on your OS version, but
-      it might as well not work. Unfortunately, currently I do not
-      even know why it works on some systems and fails on other
-      systems.
-
-      If you are brave, do the following, but be prepared for a BSOD
-      (blue screen of death) as a worst-case scenario. This is nothing
-      for the faint of the heart. :-) Never try this on production
-      systems.
-
-        * Start the IP-in-IP tunnel driver before running the OLSR
-          server:
-
-            net start ipinip
-
-        * When the OLSR server reports that the tunnel has been
-          established, find out, which interface index the tunnel
-          device has been assigned:
-
-            route print
-
-        * Let's assume that the interface index is 0x1234 and the
-          gateway's IP address is 1.2.3.4. Manually add a default
-          route through the other end of the tunnel:
-
-            route add 0.0.0.0 mask 0.0.0.0 1.2.3.4 if 0x1234
-
-        * Try to ping somebody beyond the gateway and let me know
-          whether it works. If it doesn't and if you have time, please
-          do a packet dump for me to determine whether IP-in-IP
-          packets are leaving your system and, if yes, what they look
-          like.
-
-      If you know of any freely available tunnel driver for Windows,
-      please let me know. We could then think about switching from the
-      native ipinip.sys driver to an alternative driver, perhaps one
-      that also works on Windows 9x.
-
-      If you are the Microsoft person that is responsible for the
-      tunnel driver, please have a look at my code in
-      src/win32/tunnel.* and tell me what I'm missing.
-
-    * Multiple interfaces in the same subnet. As they all share the
-      same subnet broadcast address, there's no way to tell Windows
-      which of these interfaces to send OLSR packets through. I guess
-      that we'll have to come up with a device driver that sits
-      between the TCP/IP stack and the network adapters and that
-      directs outbound OLSR packets to the correct interface after
-      they've been routed by the TCP/IP stack. Looks like there isn't
-      any other solution on Windows.
-
-  There are also some Windows-specific features that I currently work
-  on, but which have not made it into this release.
-
-    * A nice installation package based on Inno Setup 4. However,
-      there will always be a ZIP archive available, too, for those who
-      do not like installation packages.
-
-    * The option to run the OLSR server as a Windows service on
-      Windows NT, 2000, and XP.
-
-  These features will probably be in 0.4.7.
-
-                        ***** Compiling *****
-
-  To compile the Windows version you need a Cygwin installation with a
-  current version of GCC and Mingw32. Currently the OLSR server, the
-  GUI, and the dot_draw plugin compile. Each of the corresponding
-  subdirectories contains a shell script named "mkmf.sh" that takes
-  "Makefile.win32.in" as its input, appends the dependencies, and
-  outputs "Makefile.win32". Then simply say
-
-    make -f Makefile.win32 clean
-
-  to remove any compiled files or
-
-    make -f Makefile.win32 mclean
-
-  to remove any compiled files and the generated makefile. Say
-
-    make -f Makefile.win32
-
-  to compile the source code.
-
-  To compile the GUI you additionally need the development packages of
-  the GTK+ Windows port. They are available from the same URL as the
-  GTK+ runtime environment. You need the following packages or newer
-  versions of these packages:
-
-    - atk-dev-1.6.0.zip
-    - glib-dev-2.4.5.zip
-    - gtk+-dev-2.4.7.zip
-    - pango-dev-1.4.1.zip
-
-  Simply unzip the files into a directory that you've created and make
-  the variable "GTKBASE" in "Makefile.win32" point to this directory.
-
-Well, thanks for using the initial release of a piece of software and
-please bear with me if there are any problems. Please do also feel
-free to suggest any features that you'd like to see in future
-releases.
-
-Thomas Lopatic <thomas@lopatic.de>, 2004-08-24
+\r
+                         olsr.org for Windows\r
+                         --------------------\r
+\r
+Welcome to the Windows release of olsr.org. Let's have a quick look at\r
+how this version differs from the original Linux version.\r
+\r
+\r
+                        ***** Stability *****\r
+\r
+  While the Windows version looks pretty stable in basic scenarios, it\r
+  hasn't yet received the extensive testing by the OLSR community that\r
+  the Linux version has gone through. So, if you experience any\r
+  strange behaviour, it's probably my fault. In this case please bear\r
+  with me and use the issue tracker on SourceForge. I'll then do my\r
+  best to find and fix the problem with your assistance. The\r
+  SourceForge homepage for olsrd.org has the following URL.\r
+\r
+                http://sourceforge.net/projects/olsrd/\r
+\r
+\r
+                    ***** Configuration file *****\r
+\r
+  If you do not specify a configuration file, the OLSR server\r
+  ("olsrd.exe") by default attempts to use "olsrd.conf" in your\r
+  Windows directory, e.g. "C:\WINDOWS\olsrd.conf".\r
+\r
+\r
+                     ***** Interface naming *****\r
+\r
+  On Linux network interfaces have nice names like "eth0". In\r
+  contrast, Windows internally identifies network interfaces by pretty\r
+  awkward names, for example:\r
+\r
+    "{EECD2AB6-C2FC-4826-B92E-CAA53B29D67C}"\r
+\r
+  Hence, the Windows version implements its own naming scheme that\r
+  maps each internal name to a made-up name like "if03", which is\r
+  easier to memorize. Simply invoke the OLSR server as follows to\r
+  obtain its view of your interfaces:\r
+\r
+    olsrd.exe -int\r
+\r
+  This lists the made-up interface names along with their current IP\r
+  addresses to enable you to find out which made-up interface name\r
+  corresponds to which of your physical interfaces.\r
+\r
+  "+" in front of the IP addresses means that the OLSR server has\r
+  identified the interface as a WLAN interface. "-" indicates that the\r
+  OLSR server considers this interface to be a wired interface. "?"\r
+  means "no idea". Detection currently only works on NT, 2000, and\r
+  XP. Windows 9x and ME will always display "?".\r
+\r
+  For techies: The made-up names consist of the string "if" followed\r
+  by a two-digit hex representation of the least significant byte of\r
+  the Windows-internal interface index, which should be different for\r
+  each interface and thus make each made-up name unique. Again, this\r
+  is undocumented and this assumption may be wrong in certain\r
+  cases. So, if the "-int" option reports two interfaces that have the\r
+  same name, please do let me know.\r
+\r
+\r
+                     ***** Running the GUI *****\r
+\r
+  We now have a native Windows GUI. No more GTK+. Simply make sure\r
+  that "Switch.exe", "Shim.exe", and "olsrd.exe" are located in the\r
+  same directory and run "Switch.exe". "Shim.exe" is just an auxiliary\r
+  console application that is required by "Switch.exe".\r
+\r
+  The GUI is pretty self-explanatory. The three buttons on the lower\r
+  right of the GUI window start the OLSR server, stop the OLSR server,\r
+  and exit the GUI.\r
+\r
+  Use the "Settings" tab to specify the options that the GUI uses to\r
+  run the OLSR server "olsrd.exe". When you click "Start" the GUI\r
+  generates a temporary configuration file from the information given\r
+  by the "Settings" tab. This temporary configuration file is passed\r
+  to the OLSR server via its "-f" option. If you need options that\r
+  cannot be controlled via the "Settings" tab, simply add them to the\r
+  "Manual additions" text box as you would add them to a configuration\r
+  file, e.g. "HNA 192.168.0.0 255.255.255.0". The contents of this\r
+  text box are appended to the temporary configuration file when it is\r
+  generated.\r
+\r
+  "Offer Internet connection" is only available if you have an\r
+  Internet connection, i.e. if you have a default route configured. If\r
+  you tick this option, "HNA 0.0.0.0 0.0.0.0" is added to the\r
+  temporary configuration file, allowing other nodes in the OLSR\r
+  network to use your Internet connection.\r
+\r
+  Gateway tunnelling and IP version 6 cannot currently be selected, as\r
+  support for these features is not yet complete in the Windows\r
+  version.\r
+\r
+  The three buttons on the lower right of the "Settings" tab open\r
+  previously saved settings, save the current settings to a\r
+  configuration file, and reset the current settings to default\r
+  values. When opening a saved configuration file, the GUI adds lines\r
+  that it cannot interpret to the "Manual additions" text box.\r
+\r
+  If you start the GUI with the path to a configuration file as the\r
+  only command line argument, the GUI opens the given configuration\r
+  file and runs the OLSR server with this configuration. So, saving a\r
+  configuration file with a ".olsr" extension, for example, and making\r
+  "Switch.exe" the handler for ".olsr" files enables you to run the\r
+  OLSR server with a simple double click on the configuration file.\r
+\r
+  The "Output" tab shows the output of the currently running OLSR\r
+  server. When you click "Start" The GUI simply invokes the OLSR\r
+  server "olsrd.exe" and intercepts its console output. Use the four\r
+  buttons on the upper right of the tab to freeze the output, resume\r
+  frozen output, save the output to a file, or clear the output.\r
+\r
+  The "Nodes" tab contains information about the nodes that the OLSR\r
+  server currently knows about. If you click on the address of a node\r
+  in the "Node list" list box, the GUI populates the three "Node\r
+  information" list boxes on the right with the multi-point relays of\r
+  the selected node (MPR), the interfaces of the selected node (MID),\r
+  and the non-OLSR networks accessible via the selected node (HNA).\r
+\r
+  The "Routes" tab shows the routes that the currently running OLSR\r
+  server has added.\r
+\r
+\r
+                   ***** Running the GTK+ GUI *****\r
+\r
+  Please use the native Windows GUI instead. The GTK+ GUI is no longer\r
+  supported on Windows.\r
+\r
+\r
+                     ***** Missing features *****\r
+\r
+  The Windows version currently does not implement the following\r
+  features known from the Linux release.\r
+\r
+    * IPv6.\r
+\r
+    * Link layer statistics.\r
+\r
+    * Gateway tunnelling.\r
+\r
+  There are also some Windows-specific features that I currently work\r
+  on, but which have not made it into this release.\r
+\r
+    * The option to run the OLSR server as a Windows service on\r
+      Windows NT, 2000, and XP.\r
+\r
+\r
+                        ***** Compiling *****\r
+\r
+  To compile the Windows version of the OLSR server or the dot_draw\r
+  plugin you need a Cygwin installation with a current version of GCC\r
+  and Mingw32. Each of the corresponding subdirectories contains a\r
+  shell script named "mkmf.sh" that takes "Makefile.win32.in" as its\r
+  input, appends the dependencies, and outputs "Makefile.win32". Then\r
+  simply say\r
+\r
+    make -f Makefile.win32 clean\r
+\r
+  to remove any compiled files or\r
+\r
+    make -f Makefile.win32 mclean\r
+\r
+  to remove any compiled files and the generated makefile. Say\r
+\r
+    make -f Makefile.win32\r
+\r
+  to compile the source code.\r
+\r
+  The GUI has to be compiled with Visual C++ 6. Simply open the\r
+  "Frontend.dsw" workspace in the Visual C++ 6 IDE. Then compile\r
+  "Frontend" and "Shim", which creates "Switch.exe" and\r
+  "Shim.exe". Copy these two executables into the same directory as\r
+  "olsrd.exe" and you are ready to go.\r
+\r
+Well, thanks for using an early release of a piece of software and\r
+please bear with me if there are any problems. Please do also feel\r
+free to suggest any features that you'd like to see in future\r
+releases.\r
+\r
+Thomas Lopatic <thomas@lopatic.de>, 2004-09-15\r