382 lines
11 KiB
Groff
382 lines
11 KiB
Groff
.Dd June 11, 2017
|
|
.Dt IF 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm if
|
|
.Nd network interface
|
|
.Sh SYNOPSIS
|
|
.In sys/ioctl.h
|
|
.In net/if.h
|
|
.Sh DESCRIPTION
|
|
Network interfaces are devices that provide transmission and receipt of network
|
|
packets.
|
|
The name of a network interface is the name of the device driver followed by the
|
|
driver instance number, and each network interface have an unique index number
|
|
distinct from the driver instance number.
|
|
The name length is restricted to
|
|
.Dv IF_NAMESIZE
|
|
bytes including the trailing nul byte.
|
|
Network interfaces are exposed in the filesystem as
|
|
.Pa /dev/ Ns Ar name Ns Ar X
|
|
devices, where
|
|
.Ar name
|
|
is the driver name, and the
|
|
.Ar X
|
|
number denotes which device using that driver.
|
|
Each driver is documented with a manual page with the driver's name in section
|
|
4 of the manual.
|
|
.Pp
|
|
The state of the network interface can be awaited with
|
|
.Xr poll 2
|
|
where the
|
|
.Dv POLLIN
|
|
and
|
|
.Dv POLLOUT
|
|
events are signaled when the network is up
|
|
.Dv ( IF_STATUS_FLAGS_UP ) .
|
|
.Sh LINK LAYER
|
|
Network interfaces abstracts a hardware device or a software device as a link
|
|
layer protocol:
|
|
.Bl -tag -width "12345678"
|
|
.It Ethernet Controller Pq Dv IF_TYPE_ETHERNET
|
|
Packets are received and transmitted with the Ethernet
|
|
.Xr ether 4
|
|
link layer protocol.
|
|
The
|
|
.Va type
|
|
field of
|
|
.Vt struct if_info
|
|
is set to
|
|
.Dv IF_TYPE_ETHERNET
|
|
and the
|
|
.Va addr
|
|
field contains the 6-byte Ethernet address assigned to the Ethernet controller.
|
|
.It Loopback Device Pq Dv IF_TYPE_LOOPBACK
|
|
The software loopback device
|
|
.Xr lo 4
|
|
on the local host receives any packets transmitted on it.
|
|
The
|
|
.Va type
|
|
field of
|
|
.Vt struct if_info
|
|
is set to
|
|
.Dv IF_TYPE_LOOPBACK
|
|
and the
|
|
.Va addr
|
|
field is unused.
|
|
.El
|
|
.Sh NETWORK LAYER
|
|
Network layer protocols are layered on top of the link layer:
|
|
.Bl -tag -width "12345678"
|
|
.It Internet Protocol version 4 Pq Dv AF_INET
|
|
The Internet Protocol version 4
|
|
.Xr ip 4
|
|
provides the network layer of the Internet Protocol version 4 protocol family
|
|
.Xr inet 4 ,
|
|
containing transport protocols such as the Transmission Control Protocol
|
|
.Xr tcp 4 ,
|
|
and the User Datagram Protocol
|
|
.Xr udp 4 .
|
|
When combined with the Ethernet link layer, the Address Resolution Protocol
|
|
.Xr arp 4
|
|
is used to resolve network layer addresses into link layer addresses.
|
|
.El
|
|
.Sh CONFIGURATION
|
|
The static information about a network interface is stored in
|
|
.Vt struct if_info :
|
|
.Bd -literal
|
|
struct if_info {
|
|
unsigned int linkid;
|
|
int type;
|
|
int features;
|
|
size_t addrlen;
|
|
char name[IF_NAMESIZE];
|
|
unsigned char addr[IF_HWADDR_MAXSIZE];
|
|
};
|
|
.Ed
|
|
.Pp
|
|
.Va linkid
|
|
is the network interface's index number.
|
|
.Va type
|
|
is the link layer protocol.
|
|
.Va features
|
|
is a bit mask of the features provided by the network interface:
|
|
.Bl -tag -width "12345678"
|
|
.It IF_FEATURE_ETHERNET_CRC_OFFLOAD
|
|
The Ethernet CRC32 checksum is computed in hardware.
|
|
.El
|
|
.Pp
|
|
.Va addrlen
|
|
is the size of the interface's assigned hardware address stored in the
|
|
.Va addr
|
|
field.
|
|
.Va name
|
|
is the nul-terminated string name of the network interface.
|
|
.Pp
|
|
The status information about a network interface is stored in
|
|
.Vt struct if_status :
|
|
.Bd -literal
|
|
struct if_status {
|
|
int flags;
|
|
size_t mtu;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
.Va flags
|
|
is a bit mask of network interface status conditions:
|
|
.Bl -tag -width "12345678"
|
|
.It IF_STATUS_FLAGS_UP
|
|
The network interface link is up and packets can be received and transmitted.
|
|
.El
|
|
.Pp
|
|
.Va mtu
|
|
is the maximum transmission unit of the network layer datagram that can be
|
|
sent or transmitted on the link layer.
|
|
.Pp
|
|
The configuration of the network interface is stored in
|
|
.Vt if_config :
|
|
.Bd -literal
|
|
struct if_config_ether {
|
|
struct ether_addr address;
|
|
};
|
|
|
|
struct if_config_inet {
|
|
struct in_addr address;
|
|
struct in_addr router;
|
|
struct in_addr subnet;
|
|
};
|
|
|
|
struct if_config {
|
|
struct if_config_ether ether;
|
|
struct if_config_inet inet;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
.Va ether
|
|
is the configuration of the
|
|
.Xr ether 4
|
|
link layer protocol where
|
|
.Va address
|
|
is the Ethernet address that received packets must have as the destination
|
|
address and the address used as the source address in transmitted packets.
|
|
.Va address
|
|
defaults on network interface creation to the value of the
|
|
.Va addr
|
|
field of the network interface's
|
|
.Va struct if_info .
|
|
.Pp
|
|
.Va inet
|
|
is the configuration of the
|
|
.Xr ip 4
|
|
network layer protocol where
|
|
.Va address
|
|
is the local address,
|
|
.Va router
|
|
is the default route, and
|
|
.Va subnet
|
|
is the subnet mask.
|
|
The protocol is disabled if
|
|
.Va address
|
|
is set to the any address
|
|
.Pq 0.0.0.0 .
|
|
.Pp
|
|
Configuration changes to the local addresses or routing information will cause
|
|
the remote side of existing sockets to become unreachable where paths are no
|
|
longer configured.
|
|
Currently outgoing packets are unaffected by configuration changes when they
|
|
have left the appropriate network layers.
|
|
Outgoing packets may be queued for a short period in queues such as
|
|
the data link layer address resolution queue or in the transmission queue.
|
|
.Sh IOCTLS
|
|
Network interfaces provide the following
|
|
.Xr ioctl 2
|
|
requests defined in
|
|
.In sys/ioctl.h :
|
|
.Bl -tag -width "12345678"
|
|
.It Dv IOCGETTYPE Fa "void"
|
|
Return the device
|
|
.Fa type
|
|
that as a parameter to the
|
|
.Dv IOC_TYPE(int type)
|
|
macro returns
|
|
.Dv IOC_TYPE_NETWORK_INTERFACE
|
|
if the device is a network interface.
|
|
.It Dv NIOC_GETCONFIG Fa "struct if_config *"
|
|
Retrieve the network interface configuration for all protocols atomically.
|
|
.It Dv NIOC_GETCONFIG_ETHER Fa "struct if_config_ether *"
|
|
Retrieve the Ethernet configuration.
|
|
.It Dv NIOC_GETCONFIG_INET Fa "struct if_config_inet *"
|
|
Retrieve Internet Protocol version 4 configuration.
|
|
.It Dv NIOC_GETINFO Fa "struct if_info *"
|
|
Retrieve the network interface static information.
|
|
.It Dv NIOC_GETSTATUS Fa "struct if_status *"
|
|
Retrieve the network interface status.
|
|
.It Dv NIOC_SETCONFIG Fa "const struct if_config *"
|
|
Set the network interface configuration for all protocols atomically.
|
|
.It Dv NIOC_SETCONFIG_ETHER Fa "const struct if_config_ether *"
|
|
Set the Ethernet configuration.
|
|
.It Dv NIOC_SETCONFIG_INET Fa "const struct if_config_inet *"
|
|
Set the Internet Protocol version 4 configuration.
|
|
.El
|
|
.Sh SOCKET OPTIONS
|
|
Sockets are made with
|
|
.Xr socket 2
|
|
by requesting the desired network layer protocol and the desired transport layer
|
|
protocol.
|
|
These
|
|
.Xr setsockopt 2 /
|
|
.Xr getsockopt 2
|
|
options of level
|
|
.Dv SOL_SOCKET
|
|
control aspects related to the network interface and are defined in
|
|
.In sys/socket.h :
|
|
.Bl -tag -width "12345678"
|
|
.It Dv SO_BINDTODEVICE Fa "char[]"
|
|
Set the network interface the socket is bound to by looking up the string value
|
|
(which need not be nul-terminated) as an network interface name, and then
|
|
binding the socket to that network interface index number; or failing with
|
|
.Er ENODEV
|
|
if no such device exists.
|
|
Gets the name of the network interface the socket is bound to, by looking up the
|
|
network interface index number the socket is bound to, and copying out the name
|
|
of that network interface; or copying out the empty string if so no such device
|
|
exists.
|
|
If bound to a network interface, a socket will only receive from and transmit on
|
|
that network interface.
|
|
(Initially the empty string)
|
|
.It Dv SO_BINDTOINDEX Fa "unsigned int"
|
|
Sets the network interface the socket is bound to by the network interface index
|
|
number, not verifying such an network interface exists, returning with the error
|
|
.Er EINVAL
|
|
if the requested index number exceeds
|
|
.Dv UINT_MAX .
|
|
Gets the index number of the network interface the socket is bound to.
|
|
Index 0 means no network interface.
|
|
If bound to a network interface, a socket will only receive from and transmit on
|
|
that network interface.
|
|
(Initially 0)
|
|
.It Dv SO_BROADCAST Fa "int"
|
|
Sending to a broadcast address is allowed when set to 1, sending to a broadcast
|
|
address will fail with
|
|
.Er EACCESS
|
|
when set to 0.
|
|
This option is boolean, setting it to non-zero is the same as setting it to 1.
|
|
This option only pertains to datagram sockets.
|
|
(Initially 0)
|
|
.It Dv SO_DEBUG Fa "int"
|
|
Whether the socket is in debug mode.
|
|
This option is not implemented.
|
|
This option is boolean, setting it to non-zero is the same as setting it to 1.
|
|
Attempting to set it to non-zero will fail with
|
|
.Er EPERM .
|
|
(Initially 0)
|
|
.It Dv SO_DOMAIN Fa "sa_family_t"
|
|
The socket domain (the address family).
|
|
This option can only be read.
|
|
The initial value is set when making the socket.
|
|
.It Dv SO_DONTROUTE Fa "int"
|
|
Whether to bypass the routing table and only send on the local network.
|
|
This option is not implemented.
|
|
This option is boolean, setting it to non-zero is the same as setting it to 1.
|
|
Attempting to set it to non-zero will fail with
|
|
.Er EPERM .
|
|
(Initially 0)
|
|
.It Dv SO_ERROR Fa "int"
|
|
The asynchronous pending error
|
|
(an
|
|
.Xr errno 3
|
|
value).
|
|
Cleared to 0 when read unless the error is permanent.
|
|
This option can only be read.
|
|
(Initially 0)
|
|
.It Dv SO_PROTOCOL Fa "int"
|
|
The socket protocol.
|
|
This option can only be read.
|
|
The initial value is set when making the socket.
|
|
.It Dv SO_RCVBUF Fa "int"
|
|
How many bytes the receive queue can use.
|
|
Setting this option to a value beyond the socket's hard limit will instead set
|
|
this option to the hard limit.
|
|
The initial value depends on the socket protocol.
|
|
.It Dv SO_REUSEADDR Fa "int"
|
|
Don't fail to
|
|
.Xr bind 2
|
|
the second socket with
|
|
.Er EADDRINUSE
|
|
when one socket is bound to the any address and a port and the other socket is
|
|
bound to another address and that port, whenever this option is set to 1.
|
|
This option is boolean, setting it to non-zero is the same as setting it to 1.
|
|
(Initially 0)
|
|
.It Dv SO_SNDBUF Fa "int"
|
|
How many bytes the send queue can use.
|
|
Setting this option to a value beyond the socket's hard limit will instead set
|
|
this option to the hard limit.
|
|
The initial value depends on the socket protocol.
|
|
.It Dv SO_TYPE Fa "int"
|
|
The socket type.
|
|
This option can only be read.
|
|
The initial value is set when making the socket.
|
|
.El
|
|
.Sh IMPLEMENTATION NOTES
|
|
Network packets waiting to be transmitted or received have 384 dedicated pages
|
|
of backing memory (allocated on first use).
|
|
If more packets are needed, available system memory is used up to a limit of
|
|
1/16 of the total system memory.
|
|
If no memory is available for another network packet or the limit is hit,
|
|
received packets may be dropped and transmitted packets may be dropped or
|
|
temporarily fail with
|
|
.Er ENOBUFS .
|
|
.Sh SEE ALSO
|
|
.Xr getsockopt 2 ,
|
|
.Xr ioctl 2 ,
|
|
.Xr setsockopt 2 ,
|
|
.Xr getifaddrs 3 ,
|
|
.Xr if_nameindex 3 ,
|
|
.Xr arp 4 ,
|
|
.Xr ether 4 ,
|
|
.Xr inet 4 ,
|
|
.Xr ip 4 ,
|
|
.Xr lo 4 ,
|
|
.Xr kernel 7 ,
|
|
.Xr dhclient 8 ,
|
|
.Xr ifconfig 8
|
|
.Sh STANDARDS
|
|
.St -p1003.1-2008
|
|
only specifies a minimal
|
|
.In net/if.h
|
|
with
|
|
.Dv IF_NAMESIZE ,
|
|
.Vt struct if_nameindex
|
|
and the
|
|
.Xr if_nameindex 3
|
|
family of functions.
|
|
.Pp
|
|
.St -p1003.1-2008
|
|
specifies the socket options
|
|
.Dv SO_ACCEPTCONN ,
|
|
.Dv SO_BROADCAST ,
|
|
.Dv SO_DEBUG ,
|
|
.Dv SO_DONTROUTE ,
|
|
.Dv SO_ERROR ,
|
|
.Dv SO_KEEPALIVE ,
|
|
.Dv SO_LINGER ,
|
|
.Dv SO_OOBINLINE ,
|
|
.Dv SO_RCVBUF ,
|
|
.Dv SO_RCVLOWAT ,
|
|
.Dv SO_RCVTIMEO ,
|
|
.Dv SO_REUSEADDR ,
|
|
.Dv SO_SNDBUF ,
|
|
.Dv SO_SNDLOWAT ,
|
|
.Dv SO_SNDTIMEO ,
|
|
and
|
|
.Dv SO_TYPE
|
|
in
|
|
.In sys/socket.h
|
|
.Sh HISTORY
|
|
Network interfaces as described here originally appeared in Sortix 1.1, except
|
|
when noted otherwise.
|
|
.Pp
|
|
The
|
|
.Dv SO_BINDTODEVICE
|
|
socket option is also found on Linux.
|