man: start writing manpages

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.