338 lines
11 KiB
Groff
338 lines
11 KiB
Groff
.\" $NetBSD: netintro.4,v 1.23 2009/12/05 20:11:02 pooka Exp $
|
|
.\"
|
|
.\" Copyright (c) 1983, 1990, 1991, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" @(#)netintro.4 8.2 (Berkeley) 11/30/93
|
|
.\"
|
|
.Dd September 7, 2006
|
|
.Dt NETINTRO 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm netintro
|
|
.Nd introduction to networking facilities
|
|
.Sh SYNOPSIS
|
|
.In sys/types.h
|
|
.In sys/socket.h
|
|
.In net/route.h
|
|
.In net/if.h
|
|
.Sh DESCRIPTION
|
|
This section is a general introduction to the networking facilities
|
|
available in the system.
|
|
Documentation in this part of section
|
|
4 is broken up into three areas:
|
|
.Em protocol families
|
|
(domains),
|
|
.Em protocols ,
|
|
and
|
|
.Em network interfaces .
|
|
.Pp
|
|
All network protocols are associated with a specific
|
|
.Em protocol family .
|
|
A protocol family provides basic services to the protocol implementation
|
|
to allow it to function within a specific network environment.
|
|
These services may include packet fragmentation and reassembly,
|
|
routing, addressing, and basic transport.
|
|
A protocol family may support multiple methods of addressing, though
|
|
the current protocol implementations do not.
|
|
A protocol family normally comprises a number of protocols, one per
|
|
.Xr socket 2
|
|
type.
|
|
It is not required that a protocol family support all socket types.
|
|
A protocol family may contain multiple protocols supporting the
|
|
same socket abstraction.
|
|
.Pp
|
|
A protocol supports one of the socket abstractions detailed in
|
|
.Xr socket 2 .
|
|
A specific protocol may be accessed either by creating a
|
|
socket of the appropriate type and protocol family, or
|
|
by requesting the protocol explicitly when creating a socket.
|
|
Protocols normally accept only one type of address format,
|
|
usually determined by the addressing structure inherent in
|
|
the design of the protocol family/network architecture.
|
|
Certain semantics of the basic socket abstractions are
|
|
protocol specific.
|
|
All protocols are expected to support the basic model for their
|
|
particular socket type, but may, in addition, provide non-standard
|
|
facilities or extensions to a mechanism.
|
|
For example, a protocol supporting the
|
|
.Dv SOCK_STREAM
|
|
abstraction may allow more than one byte of out-of-band
|
|
data to be transmitted per out-of-band message.
|
|
.Pp
|
|
A network interface is similar to a device interface.
|
|
Network interfaces comprise the lowest layer of the networking
|
|
subsystem, interacting with the actual transport hardware.
|
|
An interface may support one or more protocol families and/or address formats.
|
|
The
|
|
.Em SYNOPSIS
|
|
section of each network interface entry gives a sample specification
|
|
of the related drivers for use in providing a system description to the
|
|
.Xr config 1
|
|
program.
|
|
.Pp
|
|
The
|
|
.Em DIAGNOSTICS
|
|
section lists messages which may appear on the console
|
|
and/or in the system error log,
|
|
.Pa /var/log/messages
|
|
(see
|
|
.Xr syslogd 8 ) ,
|
|
due to errors in device operation.
|
|
.Sh PROTOCOLS
|
|
The system currently supports the Internet protocols and some of the
|
|
.Tn ISO OSI
|
|
protocols.
|
|
Raw socket interfaces are provided to the
|
|
.Tn IP
|
|
protocol layer of the Internet, and to the
|
|
.Tn IDP
|
|
protocol of Xerox
|
|
.Tn NS .
|
|
Consult the appropriate manual pages in this section for more
|
|
information regarding the support for each protocol family.
|
|
.Sh ADDRESSING
|
|
Associated with each protocol family is an address format.
|
|
All network address adhere to a general structure, called a sockaddr,
|
|
described below.
|
|
However, each protocol imposes finer and more specific structure,
|
|
generally renaming the variant, which is discussed in the protocol
|
|
family manual page alluded to above.
|
|
.Bd -literal -offset indent
|
|
struct sockaddr {
|
|
u_char sa_len;
|
|
u_char sa_family;
|
|
char sa_data[14];
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The field
|
|
.Ar sa_len
|
|
contains the total length of the of the structure, which may exceed 16 bytes.
|
|
The following address values for
|
|
.Ar sa_family
|
|
are known to the system
|
|
(and additional formats are defined for possible future implementation):
|
|
.Bd -literal
|
|
#define AF_LOCAL 1 /* local to host */
|
|
#define AF_INET 2 /* internetwork: UDP, TCP, etc. */
|
|
#define AF_NS 6 /* Xerox NS protocols */
|
|
#define AF_CCITT 10 /* CCITT protocols, X.25 etc */
|
|
#define AF_HYLINK 15 /* NSC Hyperchannel */
|
|
#define AF_ISO 18 /* ISO protocols */
|
|
.Ed
|
|
.Sh ROUTING
|
|
.Ux
|
|
provides some packet routing facilities.
|
|
The kernel maintains a routing information database, which
|
|
is used in selecting the appropriate network interface when
|
|
transmitting packets.
|
|
.Pp
|
|
A user process (or possibly multiple co-operating processes)
|
|
maintains this database by sending messages over a special kind
|
|
of socket.
|
|
This supplants fixed size
|
|
.Xr ioctl 2
|
|
used in earlier releases.
|
|
.Pp
|
|
This facility is described in
|
|
.Xr route 4 .
|
|
.Sh INTERFACES
|
|
Each network interface in a system corresponds to a
|
|
path through which messages may be sent and received.
|
|
A network interface usually has a hardware device associated with it,
|
|
though certain interfaces such as the loopback interface,
|
|
.Xr lo 4 ,
|
|
do not.
|
|
.Pp
|
|
The following
|
|
.Xr ioctl 2
|
|
calls may be used to manipulate network interfaces.
|
|
The
|
|
.Xr ioctl 2
|
|
is made on a socket (typically of type
|
|
.Dv SOCK_DGRAM )
|
|
in the desired domain.
|
|
Most of the requests supported in earlier releases
|
|
take an
|
|
.Ar ifreq
|
|
structure as its parameter.
|
|
This structure has the form
|
|
.Bd -literal
|
|
struct ifreq {
|
|
#define IFNAMSIZ 16
|
|
char ifr_name[IFNAMSIZ]; /* if name, e.g. "en0" */
|
|
union {
|
|
struct sockaddr ifru_addr;
|
|
struct sockaddr ifru_dstaddr;
|
|
struct sockaddr ifru_broadaddr;
|
|
short ifru_flags;
|
|
int ifru_metric;
|
|
void *ifru_data;
|
|
} ifr_ifru;
|
|
#define ifr_addr ifr_ifru.ifru_addr /* address */
|
|
#define ifr_dstaddr ifr_ifru.ifru_dstaddr /* other end of p-to-p link */
|
|
#define ifr_broadaddr ifr_ifru.ifru_broadaddr /* broadcast address */
|
|
#define ifr_flags ifr_ifru.ifru_flags /* flags */
|
|
#define ifr_metric ifr_ifru.ifru_metric /* metric */
|
|
#define ifr_data ifr_ifru.ifru_data /* for use by interface */
|
|
};
|
|
.Ed
|
|
.Pp
|
|
Calls which are now deprecated are:
|
|
.Bl -tag -width SIOCGIFBRDADDR
|
|
.It Dv SIOCSIFADDR
|
|
Set interface address for protocol family.
|
|
Following the address assignment, the ``initialization'' routine for
|
|
the interface is called.
|
|
.It Dv SIOCSIFDSTADDR
|
|
Set point to point address for protocol family and interface.
|
|
.It Dv SIOCSIFBRDADDR
|
|
Set broadcast address for protocol family and interface.
|
|
.El
|
|
.Pp
|
|
.Xr ioctl 2
|
|
requests to obtain addresses and requests both to set and
|
|
retrieve other data are still fully supported
|
|
and use the
|
|
.Ar ifreq
|
|
structure:
|
|
.Bl -tag -width SIOCGIFBRDADDR
|
|
.It Dv SIOCGIFADDR
|
|
Get interface address for protocol family.
|
|
.It Dv SIOCGIFDSTADDR
|
|
Get point to point address for protocol family and interface.
|
|
.It Dv SIOCGIFBRDADDR
|
|
Get broadcast address for protocol family and interface.
|
|
.It Dv SIOCSIFFLAGS
|
|
Set interface flags field.
|
|
If the interface is marked down, any processes currently routing
|
|
packets through the interface are notified; some interfaces may be
|
|
reset so that incoming packets are no longer received.
|
|
When marked up again, the interface is reinitialized.
|
|
.It Dv SIOCGIFFLAGS
|
|
Get interface flags.
|
|
.It Dv SIOCSIFMETRIC
|
|
Set interface routing metric.
|
|
The metric is used only by user-level routers.
|
|
.It Dv SIOCGIFMETRIC
|
|
Get interface metric.
|
|
.El
|
|
.Pp
|
|
There are two requests that make use of a new structure:
|
|
.Bl -tag -width SIOCGIFBRDADDR
|
|
.It Dv SIOCAIFADDR
|
|
An interface may have more than one address associated with it
|
|
in some protocols.
|
|
This request provides a means to add additional addresses (or modify
|
|
characteristics of the primary address if the default address for
|
|
the address family is specified).
|
|
Rather than making separate calls to set destination or broadcast
|
|
addresses, or network masks (now an integral feature of multiple
|
|
protocols) a separate structure,
|
|
.Ar ifaliasreq ,
|
|
is used to specify all three facets
|
|
simultaneously (see below).
|
|
One would use a slightly tailored version of this struct specific
|
|
to each family (replacing each sockaddr by one
|
|
of the family-specific type).
|
|
Where the sockaddr itself is larger than the
|
|
default size, one needs to modify the
|
|
.Xr ioctl 2
|
|
identifier itself to include the total size, as described in
|
|
.Xr ioctl 2 .
|
|
.It Dv SIOCDIFADDR
|
|
This requests deletes the specified address from the list
|
|
associated with an interface.
|
|
It also uses the
|
|
.Ar ifaliasreq
|
|
structure to allow for the possibility of protocols allowing
|
|
multiple masks or destination addresses, and also adopts the
|
|
convention that specification of the default address means
|
|
to delete the first address for the interface belonging to
|
|
the address family in which the original socket was opened.
|
|
.El
|
|
.Pp
|
|
Request making use of the
|
|
.Ar ifconf
|
|
structure:
|
|
.Bl -tag -width SIOCGIFBRDADDR
|
|
.It Dv SIOCGIFCONF
|
|
Get interface configuration list.
|
|
This request takes an
|
|
.Ar ifconf
|
|
structure (see below) as a value-result parameter.
|
|
The
|
|
.Ar ifc_len
|
|
field should be initially set to the size of the buffer
|
|
pointed to by
|
|
.Ar ifc_buf .
|
|
On return it will contain the length, in bytes, of the
|
|
configuration list.
|
|
.El
|
|
.Bd -literal
|
|
/*
|
|
* Structure used in SIOC[AD]IFADDR request.
|
|
*/
|
|
struct ifaliasreq {
|
|
char ifra_name[IFNAMSIZ]; /* if name, e.g. "en0" */
|
|
struct sockaddr ifra_addr;
|
|
struct sockaddr ifra_dstaddr;
|
|
#define ifra_broadaddr ifra_dstaddr
|
|
struct sockaddr ifra_mask;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
.Bd -literal
|
|
/*
|
|
* Structure used in SIOCGIFCONF request.
|
|
* Used to retrieve interface configuration
|
|
* for machine (useful for programs which
|
|
* must know all networks accessible).
|
|
*/
|
|
struct ifconf {
|
|
int ifc_len; /* size of associated buffer */
|
|
union {
|
|
void *ifcu_buf;
|
|
struct ifreq *ifcu_req;
|
|
} ifc_ifcu;
|
|
#define ifc_buf ifc_ifcu.ifcu_buf /* buffer address */
|
|
#define ifc_req ifc_ifcu.ifcu_req /* array of structures returned */
|
|
};
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr config 1 ,
|
|
.Xr ioctl 2 ,
|
|
.Xr socket 2 ,
|
|
.Xr intro 4 ,
|
|
.Xr routed 8
|
|
.Sh HISTORY
|
|
The
|
|
.Nm netintro
|
|
manual appeared in
|
|
.Bx 4.3 Tahoe .
|