.Dd May 21, 2024
.Dt NET 7
.Os Camellia
.Sh NAME
.Nm net
.Nd the network interface
.Sh DESCRIPTION
Networking in Camellia is handled via a structured filesystem,
usually mounted at
.Pa /net/ ,
the details of which are explained here.
.Ss Making outbounds connections
Outbounds connection are made by opening
.Pa /net/connect/SRC/DST/PROTO/PORT .
.Pp
.Ql SRC
and
.Ql DST
refer to network addresses \(em
.Xr netstack 4
currently only supports IPv4 addresses in the
.Xr inet_aton 3
format, but e.g.\&
.Xr socksfs 4
supports using domain names as destinations too.
If a program doesn't care which interface is used to send the packet,
.Ql SRC
should be set to
.Ql 0.0.0.0 .
.Ql PROTO
is either
.Ql tcp
or
.Ql udp ,
and
.Ql PORT
is the port.
.Pp
For example, opening
.Pa /net/connect/0.0.0.0/192.0.2.1/tcp/80
will make a connection to 192.0.2.1,
on TCP port 80,
using any interface (0.0.0.0).
.Pp
If using TCP,
the
.Xr open 2
call will block until the connection succeeds or fails.
Timeouts aren't currently implemented.
The received handle can be directly read and written to.
.Pp
The file must be opened in read-write mode for a connection to be made.
If
.Dv OPEN_RW
isn't set, the open call won't succeed.
.Ss Listening for incoming connections
Opening
.Pa /net/listen/ADDR/PROTO/PORT
blocks until a connection is received, or until an error.
The meanings of the path components are the same as for outbounds connections,
and the received handle can also be directly read and written to.
.Ss Other paths
.Xr netstack 4
exposes a few other files in
.Pa /net/ :
.Bl -tag -width /net/raw -offset 2 -compact
.It Pa /net/raw
When read, listens for the next Ethernet packet.
When written, sends a Ethernet packet.
.It Pa /net/arp
Contains the ARP cache.
Read-only.
.El
.Pp
They're implementation details and should not be relied on.
.Ss Other interfaces
.Xr root 4
provides
.Pa /dev/eth ,
which is used by
.Xr netstack 4
to interface with the NIC.
That path should be inaccessible to unprivileged programs.
.Pp
Apart from that,
.Pa /net/
is the only way to access the network \(em
which means that the standard filesystem security tools can be used to restrict
network access.
.Pp
The traditional
.Xr socket 3
interface is emulated by the libc.
.Sh EXAMPLES
.Xr netdog 1
can be used to make connections from the command line.
.Dl $ netdog /net/connect/0.0.0.0/192.0.2.1/tcp/80
.Dl $ netdog /net/listen/0.0.0.0/tcp/80
.Xr cat 1
won't work, because it tries to open the file as read-only.
.Pp
.Xr whitelist 4
can be used as a very barebones firewall.
.Dl $ whitelist /bin/httpd:ro /net/listen/0.0.0.0/tcp/80 /usr/www/:ro -- httpd
.Dl $ whitelist /bin/curl:ro /net/connect/0.0.0.0/192.0.2.1/ -- curl 192.0.2.1
.Sh SEE ALSO
.Xr curl 1 ,
.Xr netdog 1 ,
.Xr netstack 4 ,
.Xr socksfs 4
.Sh BUGS
There's currently no way to get metadata about the connection,
such as the local and remote IPs.