Network
In this article, we will discuss networking on Cosmos Gen3: how to bring the network stack up and send and receive packets. The available protocols are ARP, IPv4, IPv6, UDP, TCP, DHCP and DNS, and three packages build on TCP: a Telnet server, an FTP server, and an HTTP client and server, https:// included.
The main differences if you come from Gen2:
| Gen2 | Gen3 | |
|---|---|---|
| TCP | Standard System.Net.Sockets (plugged) |
Standard System.Net.Sockets (plugged) |
| UDP | Cosmos-specific UdpClient class |
Standard System.Net.Sockets.UdpClient (plugged) |
| DHCP | Cosmos client class | Cosmos client class (Cosmos.Kernel.System.Network) |
| DNS | Cosmos client class | Standard System.Net.Dns (plugged), or the Cosmos DnsClient |
| NIC drivers | RTL8168, E1000, PCNET | Intel E1000E over the driver kit (any machine with a PCI host node; QEMU's default q35 NIC on x64), which also binds the 8254x e1000 of QEMU and VirtualBox (82540EM) and VMware (82545EM), virtio-net over the driver kit (PCI on both architectures, MMIO on ARM64) |
None of these protocols implements every feature of its RFC. If you find bugs or something abnormal, please submit an issue on our repository.
Enable networking in your kernel
Network support is behind a feature switch. Make sure your kernel's .csproj does not turn it off (it defaults to true):
<PropertyGroup>
<CosmosEnableNetwork>true</CosmosEnableNetwork>
</PropertyGroup>
At boot a NIC reaches NetworkManager through the driver kit, whichever it is; both drivers ship in Cosmos.Kernel.Drivers, which every kernel carries. An Intel E1000E is bound by E1000EDriver: the PCI host driver publishes the function, the driver brings it up and publishes an interface named e1000e, and the manager's consumer registers it (Writing a Driver). A virtio-net device is bound by VirtioNetDriver over either transport: the virtio PCI transport driver publishes a virtio node beneath the function, the virtio MMIO transport driver one beneath the virt machine's slot, and the same leaf driver binds both and publishes an interface named virtio-net (Virtio devices). The first interface a kit driver publishes is the primary, in the order the driver stage binds them. On x64 cosmos run needs no extra flags: QEMU's q35 default NIC is an e1000e. On ARM64 attach a virtio NIC explicitly:
$ cosmos run # x64: default e1000e NIC, user-mode networking
$ cosmos run --nic virtio-net-pci # x64 or arm64: virtio NIC over PCI
$ cosmos run --nic virtio-net-device # arm64: virtio NIC over MMIO
A virtio PCI function delivers its interrupts as MSI-X messages, which on ARM64 the GICv3 ITS routes (-M virt,gic-version=3); cosmos run launches ARM64 with QEMU's default GICv2, which has no ITS, so there the PCI NIC is published with no interrupt entry and VirtioNetDriver runs it polled, draining its receive queue every 50 ms. --nic virtio-net-pci therefore works on the default ARM64 launch too, while the MMIO NIC runs on its GIC line and is the interrupt-driven choice there.
With QEMU user-mode networking (the default), your kernel lives in a private 10.0.2.0/24 network: the host is reachable at 10.0.2.2, QEMU's built-in DHCP server assigns addresses, and outbound UDP/TCP is NATed to the real network.
These are the usings the snippets below rely on:
using System.Net;
using System.Net.Sockets;
using System.Text;
using Cosmos.Kernel.System.Network;
using Cosmos.Kernel.System.Timers;
The network device
NetworkManager owns the detected NICs. Check that a device is there and ready before configuring anything:
if (NetworkManager.DeviceCount > 0)
{
Console.WriteLine("Device: " + NetworkManager.Name);
Console.WriteLine("MAC: " + NetworkManager.MacAddress?.ToString());
Console.WriteLine("Link up: " + NetworkManager.LinkUp);
Console.WriteLine("Ready: " + NetworkManager.Ready);
}
Those properties report the primary adapter, which is the one the ring uses when nothing else is named. With more than one NIC, enumerate them and pick a different primary:
for (int i = 0; i < NetworkManager.DeviceCount; i++)
{
NetworkAdapter adapter = NetworkManager.GetAdapter(i);
Console.WriteLine($"[{i}] {adapter.Name} {adapter.MacAddress} link={adapter.LinkUp}");
}
NetworkAdapter second = NetworkManager.GetAdapter(1);
if (second.IsValid)
{
NetworkManager.Primary = second;
}
A NetworkAdapter is a handle, not the device: it carries the registration index, so a default-constructed one names nothing and IsValid is false. GetAdapter answers with such a handle for an index no device occupies, which is why the assignment above is guarded: the Primary setter throws ArgumentException on a handle that names nothing, and QEMU gives the kernel a single NIC by default, so GetAdapter(1) names nothing there.

Configure IPv4
Like on any operating system, the kernel needs an IPv4 configuration (address, subnet mask, gateway) before it can talk to the network. It can be obtained dynamically through DHCP or set manually.
There is no separate stack-initialization step. Configuring an address is what brings the stack up: it maps the address and the MAC to the device. NetworkStack.RemoveAllConfigIP() reverses it.
Dynamically through DHCP
DhcpClient.SendDiscoverPacket() runs the whole DISCOVER → OFFER → REQUEST → ACK exchange and applies the resulting configuration. It returns the elapsed milliseconds, or -1 on timeout:
DhcpClient dhcpClient = new();
if (dhcpClient.SendDiscoverPacket() != -1)
{
IPConfig? config = NetworkManager.Primary.IPConfig;
if (config is not null)
{
Console.WriteLine("IP address: " + config.Address.ToString());
Console.WriteLine("Subnet: " + config.SubnetMask.ToString());
Console.WriteLine("Gateway: " + config.DefaultGateway.ToString());
}
}
else
{
Console.WriteLine("DHCP timed out");
}

Manually
if (!IPConfig.Enable(
new Address4(192, 168, 1, 69), // local address
new Address4(255, 255, 255, 0), // subnet mask
new Address4(192, 168, 1, 254))) // gateway
{
Console.WriteLine("No adapter to configure");
}
That configures the primary adapter. To configure a specific one, pass its handle. Enable returns false when the handle names no device, which is what an index past the last adapter gives you:
NetworkAdapter second = NetworkManager.GetAdapter(1);
if (second.IsValid
&& IPConfig.Enable(second,
new Address4(192, 168, 2, 69),
new Address4(255, 255, 255, 0),
new Address4(192, 168, 2, 254)))
{
Console.WriteLine("Configured the second adapter");
}
DHCP configures one adapter at a time. new DhcpClient() runs the exchange on the primary adapter and new DhcpClient(adapter) on the one the handle names; the other adapters keep their configuration either way. SendReleasePacket() gives that adapter's address back to the server and leaves it unconfigured:
NetworkAdapter second = NetworkManager.GetAdapter(1);
if (second.IsValid && new DhcpClient(second).SendDiscoverPacket() != -1)
{
Console.WriteLine("Second adapter: " + second.IPConfig?.Address.ToString());
}
Read the configuration back
Each adapter carries the configuration in force on it, or null while it is unconfigured:
Console.WriteLine(NetworkManager.Primary.IPConfig?.Address.ToString());
Console.WriteLine(NetworkManager.GetAdapter(1).IPConfig?.SubnetMask.ToString());
IPv6
The IPv4 configuration also brings up a link-local IPv6 address on the device: fe80::/64 with the interface identifier derived from its MAC address (RFC 4291 Appendix A). On QEMU's default NIC that is fe80::5054:ff:fe12:3456. Neighbor Discovery resolves on-link addresses the way ARP does for IPv4, and ICMPv6 echo works in both directions.
Address6? linkLocal = NetworkManager.Primary.LinkLocalAddress; // null until the device is configured
Icmpv6Client ping = new();
ping.Connect(new Address6(0xFEC0_0000, 0, 0, 2)); // QEMU user networking answers on fec0::2
ping.SendEcho();
Cosmos.Kernel.System.Network.EndPoint from = new(Address6.Zero, 0);
int elapsedMs = ping.Receive(ref from, 5000); // -1 on timeout
ping.Close();
| IPv4 | IPv6 | |
|---|---|---|
| Address | IPConfig.Enable or DHCP |
Link-local, derived from the MAC |
| Resolution | ARP | Neighbor Discovery (solicitation and advertisement) |
| Ping | IcmpClient |
Icmpv6Client |
| UDP and TCP | UdpPacket, TcpPacket |
The same two classes, checksummed over the IPv6 pseudo-header |
| DNS | DnsClient, A records |
The same client, AAAA records |
What IPv6 does not cover yet: addresses beyond link-local (Router Advertisements are ignored, no SLAAC or DHCPv6, so only on-link destinations are reachable), and AddressFamily.InterNetworkV6 on the .NET socket classes.
UDP
UDP goes through the standard .NET System.Net.Sockets.UdpClient; no Cosmos-specific class is needed. Cosmos.Kernel.System.Network has a UdpClient of its own (the packet-level client), so with both namespaces imported, as above, name the .NET one in full. Sends go out immediately; for receives, poll Available (a receive with nothing pending would block):
var udpClient = new System.Net.Sockets.UdpClient(4242);
/* Send data: 10.0.2.2 is the host under QEMU user networking */
byte[] message = Encoding.ASCII.GetBytes("Hello from CosmosOS!");
udpClient.Send(message, message.Length, new IPEndPoint(IPAddress.Parse("10.0.2.2"), 4242));
/* Receive data */
IPEndPoint remote = new(IPAddress.Any, 0);
while (udpClient.Available == 0)
{
TimerManager.Wait(100);
}
byte[] data = udpClient.Receive(ref remote);
Console.WriteLine("Received '" + Encoding.ASCII.GetString(data) + "' from " + remote.Address);
udpClient.Close();

TCP client
TCP also goes through the standard .NET classes: TcpClient, TcpListener and NetworkStream.
var tcpClient = new TcpClient();
tcpClient.Connect(IPAddress.Parse("10.0.2.2"), 4343);
NetworkStream stream = tcpClient.GetStream();
/* Send data */
byte[] message = Encoding.ASCII.GetBytes("Hello from CosmosOS!");
stream.Write(message, 0, message.Length);
/* Receive data */
while (!stream.DataAvailable)
{
TimerManager.Wait(100);
}
byte[] buffer = new byte[tcpClient.ReceiveBufferSize];
int bytesRead = stream.Read(buffer, 0, buffer.Length);
Console.WriteLine("Received '" + Encoding.ASCII.GetString(buffer, 0, bytesRead) + "'");
tcpClient.Close();
Read waits for data as it does in .NET: it returns once bytes have arrived, and 0 only once the peer has closed the connection, so the DataAvailable loop is optional. Set ReadTimeout (the socket's ReceiveTimeout) to bound the wait, past which Read throws an IOException.

TCP server
TcpListener accepts incoming connections. Poll Pending() to avoid blocking in AcceptTcpClient():
var listener = new TcpListener(IPAddress.Any, 4444);
listener.Start();
Console.WriteLine("Listening on port 4444...");
while (!listener.Pending())
{
TimerManager.Wait(100);
}
TcpClient client = listener.AcceptTcpClient();
Console.WriteLine("Client connected!");
NetworkStream stream = client.GetStream();
while (!stream.DataAvailable)
{
TimerManager.Wait(100);
}
byte[] buffer = new byte[client.ReceiveBufferSize];
int bytesRead = stream.Read(buffer, 0, buffer.Length);
Console.WriteLine("Received '" + Encoding.ASCII.GetString(buffer, 0, bytesRead) + "'");
/* Echo it back */
stream.Write(buffer, 0, bytesRead);
client.Close();
listener.Stop();
To reach a listener inside QEMU user networking from your host, forward a host port to the guest with cosmos run --hostfwd tcp::4444-:4444 (repeatable; plain QEMU spells it -nic user,model=e1000e,hostfwd=tcp::4444-:4444), then connect to localhost:4444 on the host.
For an interactive shell over the network, the Cosmos.Network.Telnet package's TelnetServer gives every client a console session of its own (Console Sessions and Telnet).

FTP server
The Cosmos.Network.Ftp package serves a directory of the VFS over FTP. Version 2 is the Gen3 one; 1.x is for Gen2. Add <PackageReference Include="Cosmos.Network.Ftp" Version="2.0.0" /> to your kernel and start the server once the network is configured and a filesystem is mounted:
using System.Threading;
using Cosmos.Network.Ftp;
FtpServer server = new("/mnt");
new Thread(server.Listen).Start(); // Listen() serves every client until server.Close()
Clients see /mnt as / and cannot leave it. Leaving Authenticate unset lets any user name in with any password; set it to check credentials. Transfers are passive, on ports 50000 to 50009 by default (PassivePortMin and PassivePortMax), so under QEMU user networking forward those as well as the control port: cosmos run --hostfwd tcp::2121-:21 --hostfwd tcp::50000-:50000 ..., then curl ftp://localhost:2121/. A PASV reply names the guest's own address, 10.0.2.15, which the host cannot reach: curl ignores it, but FileZilla connects to it, so set PassiveAddress = IPAddress.Loopback for PASV to name 127.0.0.1 instead.
HTTP and HTTPS
HTTP is the protocol of the web and of most online APIs, and nearly all of it now travels encrypted as https://. The Cosmos.Network.Http package gives your kernel an HTTP/1.1 client and server for both. It is .NET nanoFramework's System.Net.Http ported to Gen3, so its HttpClient waits for the response inside calls such as Get and GetString, nanoFramework's equivalents of the desktop's GetAsync and GetStringAsync.
Add the package with a second line that takes System.Net.Http out of the implicit usings, because the Cosmos SDK turns ImplicitUsings on, and the .NET HttpClient that namespace brings would make every use of the package's HttpClient an ambiguous reference (CS0104):
<ItemGroup>
<PackageReference Include="Cosmos.Network.Http" Version="3.0.0" />
<Using Remove="System.Net.Http" />
</ItemGroup>
The package also declares its own HttpListener, HttpStatusCode and other types that System.Net has, so for the same reason a file that uses the package does not import System.Net, although the list of usings at the top of this page does.
Fetch a page
A host name needs a nameserver, which DHCP registers when the server's acknowledgement names one; with a manual configuration, add one as the DNS section below shows. Once the network is configured, the client fetches a page in one call:
using Cosmos.Network.Http;
using HttpClient client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
using HttpResponseMessage response = client.Get("https://example.com/");
Console.WriteLine("GET https://example.com/: " + (int)response.StatusCode + " " + response.ReasonPhrase);
Console.WriteLine("Content-Type: " + response.Content.Headers.ContentType);
string html = response.Content.ReadAsString();
int start = html.IndexOf("<title>") + "<title>".Length;
Console.WriteLine("Title: " + html.Substring(start, html.IndexOf("</title>") - start));

Get returns the response whatever its status, as Post, Put, Patch, Delete and Send do, and that includes a redirect: the client follows none, so a 3xx comes back as the response, with its Location in its headers. GetString and GetByteArray return the body alone, which leaves them no way to report the status, so they throw an HttpRequestException for an error status such as 404. Dispose each response, as the using declaration does, so that its connection is closed or goes back to the pool for the next request.
Every other failure is an HttpRequestException too, whichever call made the request: a refused connection, a name that does not resolve, a refused certificate or a response cut short. Its innermost exception says why.
Set Timeout. It is infinite by default, as on nanoFramework, so a server that stops answering holds the calling thread for the five minutes each read of the socket may wait. Timeout shortens that wait for every read, of the response's head and of its body, so a server that goes silent fails the call with an HttpRequestException once that long has passed without data. A server that keeps sending, however slowly, is not cut off.
An https:// address runs TLS inside the package, in BouncyCastle's managed code, because the BCL's SslStream calls OpenSSL, which a kernel does not have. The client goes on only with a server whose certificate chain leads to one of Mozilla's root certificates, which the package embeds, and whose certificate names the host the client asked for. The first handshake takes longer than the next ones, because it parses those root certificates first.
Three properties of the client change what it offers and whom it trusts. SslProtocols is TLS 1.2 alone, as on nanoFramework, and SslProtocols.None offers TLS 1.3 as well; the property takes .NET's own SslProtocols enum, so the file needs using System.Security.Authentication;. HttpsAuthentCert takes the certificate of your own certificate authority, as the package's X509Certificate (PEM or DER), and that client then trusts the servers it signed instead of Mozilla's roots. SslVerification = SslVerification.NoVerification skips the check altogether, which lets anyone between the kernel and the server pose as the server and read the traffic, so keep it to tests.
Whatever the settings, the kernel supplies two things to the exchange. The session keys come from BouncyCastle's generator, which seeds itself from RandomNumberGenerator, the kernel CSPRNG in Cosmos (Random numbers). The certificate dates are compared with DateTime.UtcNow, so the kernel's clock has to be right. Under QEMU it is, because QEMU's RTC holds UTC.
Serve requests
HttpListener is the server half. GetContext accepts connections and hands back the next request, and it does not return until a request has arrived or the listener has stopped, so the loop runs on a thread of its own rather than in Run(), which it would otherwise hold for as long as no request comes:
using System.Text;
using System.Threading;
using Cosmos.Network.Http;
HttpListener listener = new HttpListener("http", 8080);
listener.Start();
new Thread(() =>
{
while (listener.IsListening)
{
HttpListenerContext context = listener.GetContext();
if (context == null)
{
break; // Stop() or Close() was called from another thread
}
byte[] body = Encoding.UTF8.GetBytes("Hello from Cosmos! You asked for " + context.Request.RawUrl + "\n");
HttpListenerResponse response = context.Response;
response.ContentType = "text/plain";
response.ContentLength64 = body.Length;
response.OutputStream.Write(body, 0, body.Length);
response.Close();
}
}).Start();
The thread that calls GetContext serves every connection, TLS handshakes included, without waiting on any one client. Handle each request it returns on that same thread, because the listener keeps its sockets to the thread that serves it: closing a response hands a kept-alive connection back to the list GetContext watches.
Stop() may come from another thread. A GetContext waiting for a request then returns null within 50 ms, and a thread busy with one finds IsListening false once it has answered, so the loop ends either way.
To reach the server under QEMU user networking, forward its port and query it from your host:
$ cosmos run --hostfwd tcp::8080-:8080 # in one terminal
$ curl http://localhost:8080/hello # in another
Hello from Cosmos! You asked for /hello
A listener created with the "https" prefix serves https:// once HttpsCert holds a certificate and its private key, PEM or DER, and it offers TLS 1.3 and 1.2 by default. With the certificate and its key in two strings of PEM text, the listener is created like this, then started and served with the same loop as above:
HttpListener listener = new HttpListener("https", 443)
{
HttpsCert = new X509Certificate2(certificatePem, privateKeyPem, null),
};
That X509Certificate2 is the package's class, not the one in System.Security.Cryptography.X509Certificates, because .NET's parses certificates through OpenSSL too. Its constructor takes the key as its second argument and the key's password as its third, null for a key that is not encrypted. Forwarded the same way (--hostfwd tcp::8443-:443), the listener answers curl --cacert cert.pem https://localhost:8443/ when cert.pem is a certificate that names localhost.
DNS
Two APIs resolve a name: the standard System.Net.Dns, and the Cosmos DnsClient. Register a nameserver with either one, because there is no resolv.conf to read one from and DHCP is what normally supplies it:
DnsConfig.Add(new Address4(1, 1, 1, 1)); // Cloudflare public DNS
IPAddress[] addresses = Dns.GetHostAddresses("github.com");
Console.WriteLine("github.com resolved to " + addresses[0].ToString());
System.Net.Dns reaches the Cosmos resolver through a plug on the platform layer that every one of its entry points funnels into, so the blocking overloads all work from that one plug. Two details differ from a desktop runtime: a failed lookup throws SocketException where the Cosmos client returns null, and Dns.GetHostName() reports DnsConfig.HostName, which nothing sets for you.
The Cosmos DnsClient is the other way in, and the one to use when you want the reply packet or the whole answer list:
DnsConfig.Add(new Address4(1, 1, 1, 1)); // Cloudflare public DNS
var dnsClient = new DnsClient();
dnsClient.Connect(new Address4(1, 1, 1, 1));
/* Query a single domain name */
dnsClient.SendQuery("github.com");
/* Receive the answer (5 s timeout) */
Address? address = dnsClient.Receive(5000);
if (address != null)
{
Console.WriteLine("github.com resolved to " + address.ToString());
}
dnsClient.Close();
DNS is one protocol at both IP versions, so DnsClient serves both. Two things vary independently: the server address passed to Connect decides which version carries the query, and the record type passed to SendQuery decides which address family the answer holds. An IPv4 query can ask for an IPv6 address, and the reverse:
using Cosmos.Kernel.System.Network.Protocols.Dns; // DnsRecordType, part of the packet seam (COSMOS0002)
/* Ask for the IPv6 address, over whichever version reaches the server */
dnsClient.SendQuery("github.com", DnsRecordType.AAAA);
/* Every address record for the name, after any CNAME chain */
List<Address>? all = dnsClient.ReceiveAll(5000);
DHCP is the opposite case and stays IPv4-only: DHCPv6 is a different protocol, not this one over IPv6, sharing neither its ports, its message types, nor its option codes.

Crafting packets
The packet types behind the clients are public as an experimental seam: a kernel can build protocol packets itself, transmit them through the stack, and receive the parsed packet objects instead of payload bytes. The seam carries the COSMOS0002 diagnostic (Public API Tracking); referencing it is a build error until the kernel project acknowledges the missing compatibility promise:
<PropertyGroup>
<NoWarn>$(NoWarn);COSMOS0002</NoWarn>
</PropertyGroup>
The seam has three parts:
| Part | Members |
|---|---|
| Packet types | EthernetPacket, ArpRequestEthernet/ArpReplyEthernet, InternetPacket, IPPacket, IcmpEchoRequest/IcmpEchoReply, UdpPacket, DhcpDiscover/DhcpRequest/DhcpRelease, DnsPacketQuery/DnsPacketAnswer, TcpPacket |
| Transmit and inject | NetworkStack.Send(InternetPacket) queues a built packet and resolves its neighbor address; NetworkStack.HandlePacket injects a raw frame into the receive path |
| Packet-level client I/O | UdpClient.Send(UdpPacket) / UdpClient.ReceivePacket(timeout), IcmpClient.Send(IcmpPacket) / IcmpClient.ReceivePacket(timeout) |
The packet types make up the Cosmos.Kernel.System.Network.Protocols subtree: EthernetPacket and InternetPacket at its root, then one namespace per protocol (Arp, Dns, IPv4 with IPv4.Dhcp under it, Tcp, Udp). The transmit, inject and client members stay on their stable types in Cosmos.Kernel.System.Network.
The seam is for building and reading the packet types the stack already
speaks, not for adding new ones: their wire fields, header checksum helpers
and the InitializeFields parse hook are internal to the stack, so a kernel
constructs a packet and reads its properties rather than deriving its own.
UdpPacket and TcpPacket serve both IP versions from one class. They do
not derive from IPPacket; they hold the packet that carries them in a
Network property, typed as the version-neutral InternetPacket. Build one
by passing two addresses of the same version, and hand packet.Network to
NetworkStack.Send:
using Cosmos.Kernel.System.Network.Protocols.Udp;
UdpPacket datagram = new UdpPacket(localIp, remoteIp, 5000, 4242, payload);
NetworkStack.Send(datagram.Network);
A mismatched pair of addresses throws ArgumentException rather than
truncating one of them.
A crafted echo request, correlated with its reply by the identifier and sequence number the caller chose:
using Cosmos.Kernel.System.Network;
using Cosmos.Kernel.System.Network.Protocols.IPv4;
IPConfig? config = NetworkManager.Primary.IPConfig;
if (config is null)
{
Console.WriteLine("The primary adapter has no IPv4 configuration.");
return;
}
Address localIp = config.Address;
Address gateway = config.DefaultGateway;
IcmpClient icmp = new IcmpClient();
icmp.Connect(gateway);
IcmpEchoRequest request = new IcmpEchoRequest(localIp, gateway, id: 0x1234, sequence: 7);
if (!NetworkStack.Send(request))
{
Console.WriteLine("No interface carries " + localIp.ToString());
return;
}
if (icmp.ReceivePacket(5000) is IcmpEchoReply reply
&& reply.IcmpId == 0x1234 && reply.IcmpSequence == 7)
{
Console.WriteLine("reply from " + reply.SourceIP.ToString());
}
icmp.Close();
The contract the packet types actually implement:
- A build constructor writes the complete frame, including lengths and checksums, at construction time; nothing is recomputed later, so header bytes must not be modified after construction.
- Header properties are snapshots parsed from
RawDataat construction; writing toRawDatadoes not refresh them. - A parse constructor (
new XxxPacket(byte[])) aliases the caller's array without copying. NetworkStack.Sendresolves the sending device from the packet's source IP and returnsfalsewhen no configured interface matches it; the destination MAC is resolved by ARP over IPv4 and by Neighbor Discovery over IPv6, unless the destination is a broadcast or a multicast group.- The UDP checksum differs by version, and it is the one field that does. A build constructor that receives the payload writes the checksum; one that takes only a length leaves the field zero, which means "not computed" over IPv4 and is illegal over IPv6, so call
WriteChecksum()once the payload is in place. - A protocol only IPv4 carries is a subclass of
IPPacket: pass the protocol number and payload length to a build constructor and write the payload atDataOffset. A protocol both versions carry composes anInternetPacketinstead, the wayUdpPacketandTcpPacketdo.
Current limitations
System.Net.Dnsresolves A records only.IPAddressholds four bytes in the plugs, so there is nothing an AAAA answer could be returned in andAddressFamily.InterNetworkV6is refused outright. The CosmosDnsClienthas no such limit and returnsAddress6for an AAAA record.- Reverse lookups are not supported.
Dns.GetHostEntry(IPAddress)needs a PTR query againstin-addr.arpa, which the resolver does not send, so it throws rather than returning a name. - The asynchronous
Dnsoverloads are unverified.GetHostAddressesAsyncand theBegin/Endpairs reach the same plug, but they get there by queueing the blocking call to the thread pool, which this kernel has not been exercised against. The blocking overloads are the tested path. - IPv6 stops at the link. There is a link-local address, Neighbor Discovery, ICMPv6 echo, and UDP and TCP now ride IPv6 through the same packet classes as IPv4, but there is no routing table, so every destination has to be on the link. No SLAAC or DHCPv6, no address configuration beyond the link-local address, and
IPAddressstays IPv4-only in the socket plugs, so the standard .NET socket classes reach IPv4 only. - TLS is not part of the kernel, because the BCL's
SslStreamcalls OpenSSL, which a kernel does not have.https://goes through the Cosmos.Network.Http package instead (HTTP and HTTPS), which speaks HTTP/1.1 only, checks no certificate revocation, and reaches IPv4 only, as the standard socket classes it is built on do. - Several NICs are registered and configured, and outbound packets are routed by matching the source address against each interface's configuration, so
NetworkManager.Primarydecides only where the unrouted helpers (NetworkManager.Send, the no-handleIPConfig.Enable) go. - An interface the driver kit withdraws leaves the manager's table, but its IP configuration is not removed and
NetworkAdapterhandles stay positional, so a handle taken before the withdrawal may name the device that moved into its slot. - Half-close is not supported:
Close()on an established TCP connection expects the peer to answer the FIN handshake within 5 seconds and throws if it keeps the connection open. - On the Cosmos
UdpClientandIcmpClient,Close()andDispose()are not the same door.Close()stops delivery to the client and anIcmpClientreopens with anotherConnect();Dispose()(including the one ausingblock runs) retires the client for good, and every other member throwsObjectDisposedExceptionafterwards.
How it works
Your code calls the standard .NET socket classes, whose PAL bottoms out in Socket-level plugs in Cosmos.Kernel.Plugs (SocketPlug, TcpClientPlug, TcpListenerPlug, UdpClientPlug, NetworkStreamPlug, and NameResolutionPalPlug for Dns). Those delegate to the Cosmos network stack (the TCP state machine and UDP layer over both IP versions, with ARP and Ethernet under IPv4 and ICMPv6 and Neighbor Discovery under IPv6), which sends and receives frames through the network device registered with NetworkManager: an interface a driver kit driver published, the E1000E's or the virtio-net's. A frame the kit driver receives is handed to the stack on the kit's worker thread, with interrupts on. The stack serializes itself with a lock of its own, which the receive path holds while it handles a frame and which every other entry point (the clients, the socket plugs) takes around what it shares with that path. It is a blocking lock, and it is never held while the stack waits for the network: a lock contended under it is an ordinary wait. The Cosmos DhcpClient and DnsClient sit directly on the Cosmos UDP layer, DhcpClient over IPv4 only.
TcpClient / TcpListener / UdpClient / NetworkStream (stock BCL)
│
Socket plugs (Cosmos.Kernel.Plugs)
│
Cosmos TCP state machine / UDP (Cosmos.Kernel.System.Network)
│ DhcpClient / DnsClient ride UDP directly
IPv4 / ARP and IPv6 / Neighbor Discovery / Ethernet
│
Network device (e1000e or virtio-net, over the driver kit)
Summary
| Task | Call |
|---|---|
| Check that a NIC is ready | NetworkManager.DeviceCount, NetworkManager.Ready |
| List the adapters | NetworkManager.GetAdapter(index) |
| Pick the primary adapter | NetworkManager.Primary |
| Configure IPv4 through DHCP | DhcpClient.SendDiscoverPacket() |
| Configure IPv4 by hand | IPConfig.Enable(address, subnetMask, defaultGateway) |
| Read an adapter's configuration | NetworkAdapter.IPConfig |
| Read the IPv6 link-local address | NetworkAdapter.LinkLocalAddress |
| Ping an IPv6 address | Icmpv6Client.Connect(dest), SendEcho(), Receive(ref source, timeout) |
| Send and receive UDP datagrams | System.Net.Sockets.UdpClient |
| Connect to a TCP server | TcpClient.Connect(address, port), TcpClient.GetStream() |
| Accept TCP connections | TcpListener.Start(), Pending(), AcceptTcpClient() |
| Fetch a page over HTTP or HTTPS | HttpClient.Get(requestUri), HttpClient.GetString(requestUri) |
| Serve HTTP requests | new HttpListener("http", port), Start(), GetContext() |
| Serve HTTPS | new HttpListener("https", port), HttpListener.HttpsCert |
| Register a nameserver | DnsConfig.Add(nameserver) |
| Resolve a name | Dns.GetHostAddresses(hostNameOrAddress) |
| Read every address record of a name | DnsClient.SendQuery(url), DnsClient.ReceiveAll(timeout) |
| Send a packet you built | NetworkStack.Send(packet) |