diff options
Diffstat (limited to 'man/net.7')
| -rw-r--r-- | man/net.7 | 113 |
1 files changed, 113 insertions, 0 deletions
diff --git a/man/net.7 b/man/net.7 new file mode 100644 index 0000000..0f8c360 --- /dev/null +++ b/man/net.7 @@ -0,0 +1,113 @@ +.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. |