source: mainline/uspace/srv/net/documentation.txt@ 21580dd

/**

\mainpage Networking and TCP/IP Stack for HelenOS system

\section introduction Introduction

<p>
For the microkernel HelenOS a completely new networking stack was designed.
The networking stack was intended to implement current basic standards of the TCP/IP Stack.
Only the minimalistic functionality allowing the stack to function was to be implemented.
The networking stack is written in C.
</p>
<p>
Please see
</p>
<ul>
        <li>\ref build</li>
        <li>\ref software</li>
        <li>\ref running</li>
        <li>\ref testing</li>
</ul>

\page build Build from sources

<p>
To compile the HelenOS from sources (the cross compilers from the <code>build/</code> directory are recommended):
</p>
<ol>
        <li>change the working directory to the HelenOS source directory</li>
        <li>run <code># make config</code></li>
        <li>check/change the configuration</li>
        <li>save and exit the configuration tool</li>
        <li>run <code># make</code></li>
</ol>
<p>
The <code>image.iso</code> should be created on success.
</p>

\page running Running the HelenOS with networking

\section netstart Starting the networking

<p>
After starting the HelenOS boot image in <em>Qemu</em>, the command line appears.
To run <em>Qemu</em> a script <code>contrib/conf/qemu.sh</code> for Linux or <code>contrib/conf/qemu.bat</code> for Windows in the HelenOS source directory can be used.
The provided scripts set the needed arguments:
<br><code>-vga std -M isapc -net nic,model=ne2k_isa -net user -redir udp:8080::8080 -redir udp:8081::8081 -boot d -cdrom image.iso</code><br>
Additional arguments may be specified on the command line, they override these set.
</p>

<p>
The networking stack is started and initialized by running a command
<br><code># netstart</code><br>
The networking stack is then started and configured network interfaces are enabled.
The current configuration is printed out.
Since that networking applications can be run using the command line as well.
</p>

\section network Qemu network

<p>
In the common mode <em>Qemu</em> creates a simple network with a gateway and settles the guest system in.
The network is 10.0.2.*, the gateway's address 10.0.2.2 and the guest system has 10.0.2.15.
%Even this simple setting was a bit hard to find in the documentation.
Therefore a static configuration is possible and no additional DHCP nor BOOTP implementations are necessary.
On the other hand the guest system is behind a firewall.
<em>Qemu</em> may be configured to forward some ports to the guest system and allows all outgoing traffic except ICMP and ARP protocols, so you can ping only the gateway.
</p>

\section applications Applications

<p>
A few networking applications are located in the app/ directory.
Common functions for parsing command line arguments and printing textual networking error messages are located in that directory as well.
The networking applications should be built with the libsocket library located in the socket/libsocket.a file.
They can use functions and definitions from the include/socket.h header file which contains socket API and further includes:
</p>
<ul>
        <li>include/byteorder.h containing byte order manipulation,</li>
        <li>include/in.h containing IPv4 socket address structure,</li>
        <li>include/in6.h containing IPv6 socket address structure,</li>
        <li>include/inet.h containing socket address structure and parsing functions,</li>
        <li>include/socket codes.h containing address and protocol families and socket types and option levels, and</li>
        <li>include/socket errno.h containing socket and general error codes.</li>
</ul>

\page software Software prerequisites

<p>
The networking and TCP/IP stack is implemented for the ia32 architecture on top of HelenOS 0.4.1 (Escalopino), the most current stable release of HelenOS.
So far the only one operational network interface supported is in Qemu 0.10.2 and newer.
To run <em>Qemu</em> a script contrib/conf/qemu.sh for Linux or contrib/conf/qemu.bat for Windows in the HelenOS source directory can be used.
The qemu and its libraries have to be installed and in the path.
These scripts set all the necessary parameters
with some ports redirected from the local host to the guest system.
For testing purposes at least a low level communication application is recommended, N.E.T., netcat etc.
</p>
<p>
In order to build HelenOS and the networking stack from sources a few tools are
required:
<ul>
        <li>binutils in version 2.19.1,</li>
        <li>gcc–core in version 4.3.3 11,</li>
        <li>gcc–objc in version 4.3.3, and</li>
        <li>gcc–g++ in version 4.3.3.</li>
</ul>
<p>
All these can be downloaded and installed as cross–compilers on Linux using a script contrib/toolchain.sh in the HelenOS source directory.
In addition rats, a static source code analyzer, and Doxygen, a documentation generator, were used.
All development was tracked in the HelenOS subversion repository.
</p>
<ul>
        <li>HelenOS website: <a href="http://www.helenos.org/" title="HelenOS website">http://www.helenos.org/</a></li>
        <li><em>Qemu</em> website: <a href="http://www.qemu.org/" title="Qemu website">http://www.qemu.org/</a></li>
        <li><em>binutils</em> website: <a href="http://www.gnu.org/software/binutils/" title="binutils website">http://www.gnu.org/software/binutils/</a></li>
        <li><em>GCC</em> website: <a href="http://gcc.gnu.org/" title="GCC website">http://gcc.gnu.org/</a></li>
        <li><em>RATS</em> website: <a href="http://www.fortify.com/security-resources/rats.jsp" title="RATS website">http://www.fortify.com/security-resources/rats.jsp</a></li>
        <li><em>Doxygen</em> website: <a href="http://www.stack.nl/ dimitri/doxygen/index.html" title="Doxygen website">http://www.stack.nl/ dimitri/doxygen/index.html</a></li>
        <li><em>Subversion</em> website: <a href="http://subversion.tigris.org/" title="Subversion website">http://subversion.tigris.org/</a></li>
</ul>

\page testing Testing scenarios

<p>
The scenarios contain the following shortcuts:
</p>
<ul>
        <li>g for the quest system, HelenOS in <em>Qemu</em></li>
        <li>h for the host system</li>
        <li>n for the <em>NET</em> application</li>
        <li>e for echo echo application run in HelenOS</li>
</ul>

\section scenarios Testing scenarios
<ul>
        <li>UDP
                <ol>
                        <li>g #netstart</li>
                        <li>h wine net.exe (->n) (or net.exe)</li>
                        <li>n set 127.0.0.1:8080 address and port, BuiltinUDP protocol</li>
                        <li>n send some data (an ARP will be generated and the original packet gets lost)</li>
                        <li>n send some data (the port is unreachable and the packet is discarded)</li>
                        <li>g #echo -p 8080 -c 3 -v (->e)</li>
                        <li>g prints Listening</li>
                        <li>n send some data</li>
                        <li>e prints received data</li>
                        <li>h prints reply</li>
                        <li>n click disconnect</li>
                        <li>n set :8081 port</li>
                        <li>n send some data</li>
                        <li>n click disconnect</li>
                        <li>n set :8080 port</li>
                        <li>count-1 times:
                                <ol>
                                        <li>n send some data</li>
                                        <li>e prints received data</li>
                                        <li>h prints reply</li>
                                </ol>
                        </li>
                        <li>e prints Exiting</li>
                        <li>e quits</li>
                        <li>n send some data (the port is unreachable and the packet is discarded)</li>
                </ol>
        </li>
        <li>ICMP echo to 10.0.2.2
                <ol>
                        <li>g #netstart</li>
                        <li>g #ping 10.0.2.2 (->p)</li>
                        <li>g prints ARP request for 10.0.2.2</li>
                        <li>g prints ARP reply from 10.0.2.2</li>
                        <li>p prints timeouted</li>
                        <li>p prints round trip time</li>
                        <li>p prints round trip time</li>
                        <li>p quits</li>
                </ol>
        </li>
        <li>ICMP echo to 127.0.0.1
                <ol>
                        <li>g #netstart</li>
                        <li>g #ping 127.0.0.1 (->p)</li>
                        <li>p prints round trip time</li>
                        <li>p prints round trip time</li>
                        <li>p prints round trip time</li>
                        <li>p quits</li>
                </ol>
        </li>
        <li>ICMP with no internet on the host system (!)
                <ol>
                        <li>g #netstart</li>
                        <li>g #ping 123.123.123.3 (->p)</li>
                        <li>g prints ARP request for 10.0.2.2</li>
                        <li>g prints ARP reply from 10.0.2.2</li>
                        <li>p prints timeouted</li>
                        <li>p prints destination unreachable</li>
                        <li>p prints destination unreachable</li>
                        <li>p quits</li>
                </ol>
        </li>
</ul>

*/