= Networking in HelenOS =
[[PageOutline(2-3)]]

== Introduction ==

HelenOS supports TCP/IP networking with IPv4. TCP, UDP, ICMP protocols are supported. There is basic (but not complete) support for IPv6. Various real and emulated Ethernet network adapters can be used (see below).

== Setting up real hardware ==

Make sure you have a supported network adapter, otherwise no special setup is necessary. Supported network adapters:

  * NE 2000 (ISA) - compatible
  * Intel PRO/1000 (1 Gbit)
  * Realtek RTL8139 (100 Mbit)
  * Realtek RTL8168/RTL8169 (1 Gbit)

== Setting up virtual hardware ==

 * [wiki:UsersGuide/RunningInQEMU#Networking QEMU]
 * [wiki:UsersGuide/RunningInVirtualBox#Networking VirtualBox]

== Network configuration ==

Network can be configured automatically via DHCP (IPv4) or manually.

=== Automatic network configuration ===

HelenOS will try to configure each Ethernet adapter it detects using DHCP. This behavior cannot be disabled at the moment. IPv4 address, default router and DNS server can be configured via DHCP - allowing to use networking without manual configuration.

=== Manual network configuration ===

In case automatic configuration is not available, you can configure networking from the command line.
You can check the currently configured addresses via the `inet list-addr` command:

{{{
/ # inet list-addr
Addr/Width                 Link-Name    Addr-Name Def-MTU
========================== ============ ========= =======
127.0.0.1/24               net/loopback v4a       1500   
::1/128                    net/loopback v6a       1500   
fe80::5054:ff:fe12:3456/64 net/eth1     v6a       1500   
}}}

Let's check the available IP links:
{{{
/ # inet list-link
Link-layer Address Link-Name    Def-MTU
================== ============ =======
00:00:00:00:00:00  net/loopback 1500   
52:54:00:12:34:56  net/eth1     1500   
}}}

`net/eth1` is one of the available links, in this case the first discovered Ethernet adapter.
Now, let's assume you want to configure net/eth1 to have address 192.168.1.4. This is simply achieved by typing:

{{{
/ # inet create-addr 192.168.1.4/24 net/eth1 myaddr
}}}
`myaddr` is a user-defined name given to the configured address. It is used to identify the address to other `inet` commands.

You may also want to configure the default gateway for your networked HelenOS system. Provided the gateway is at 192.168.1.1, type:

{{{
/ # inet create-sr 0.0.0.0/0 192.168.1.1 default
}}}

Your HelenOS system is now configured for networking. Note that `inet` understands also other commands that you can use to fix any potential problems with the configuration. To see the complete list, just type:

{{{
/ # inet -h
}}}

=== DNS configuration ===

IP address of your DNS server is configured via DHCP or manually using the command

{{{
dnscfg set-ns <server-address>
}}}

To verify your configuration works use {{{dnsres}}}.

=== SLIP configuration ===

To connect to another host using the SLIP protocol via a serial line

{{{
slip <serial-port-service> <link-name>
}}}

where {{{serial-port-device}}} is the location service name for the serial port (e.g. {{{devices/\hw\pci0\00:01.0\com1\a}}} and {{{link-name}}} is the name you want to give to the IP link (e.g. {{{net/slip0}}}).

=== IPv6 ===

Each Ethernet link automatically gets a link-local IPv6 address. You can also manually configure a globally routable address using {{{inet create}}}, e.g.

{{{
inet create 2001:0db8:0000:0000:0000:ff00:0042:8329 net/eth1 v6a
}}}

Router advertisements are not supported, nor is DHCPv6.

== Network utilities ==

=== Dnsres ===

{{{
dnsres <host-name>
}}}

Prints the specified host name, the canonical name of the host (only if {{{host-name}}} is an alias) and IP address of the host.

=== Ping ===

{{{
ping [-r] <host>
}}}

The {{{ping}}} command sends an ICMP Echo message to the specified host or IP address and displays the response (or timeout message). With the {{{-r}}} option it repeatedly sends the Echo message every second, until you terminate it with Ctrl-Q.

=== Nterm ===

{{{
nterm <host>:<port>
}}}

Connects to a socket via TCP and emulates a dumb terminal, similar to e.g. Netcat. This can be used for debugging (e.g. connect to an HTTP or FTP server, connect to netecho) or to connect to remcons in another HelenOS instance.

=== Netecho ===

UDP testing utility, similar to Netcat's UDP mode. It can either listen for messages on a local port and print them:

{{{
netecho -l <port>
}}}

or you can use it to send UDP messages, either from the command line:

{{{
netecho -d <host>:<port> <message1> [<message2>...]
}}}

or interactively

{{{
netecho -d <host>:<port>
}}}

== Network services ==

=== Web server (websrv) ===

{{{/app/websrv}}} is a trivial web server which serves the contents of the {{{/data/web}}} directory. You need to start it manually from the command line. By default it listens on port 8080 or you can change this by starting it with the {{{-p <port>}}} option.

=== Telnet server (remcons) ===

Is a telnet-like server. It is started automatically and listens on port 2223 and allows you to connect to the system from outside (e.g. from UN*X using the {{{telnet}}} command). It does not actually implement any Telnet protocol features (it just pipes the data through). It can only input and output text data, so pseudo-graphical applications (Tetris, Editor) and special keys won't work.