1.\" $OpenBSD: netintro.4,v 1.50 2017/11/16 15:35:07 tb Exp $ 2.\" $NetBSD: netintro.4,v 1.4 1995/10/19 08:03:40 jtc Exp $ 3.\" 4.\" Copyright (c) 1983, 1990, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)netintro.4 8.2 (Berkeley) 11/30/93 32.\" 33.Dd $Mdocdate: November 16 2017 $ 34.Dt NETINTRO 4 35.Os 36.Sh NAME 37.Nm netintro 38.Nd introduction to networking facilities 39.Sh SYNOPSIS 40.In sys/socket.h 41.In net/route.h 42.In net/if.h 43.Sh DESCRIPTION 44This section is a general introduction to the networking facilities 45available in the system. 46Documentation in this part of section 474 is broken up into three areas: 48.Em protocol families 49(domains), 50.Em protocols , 51and 52.Em network interfaces . 53.Pp 54All network protocols are associated with a specific 55.Em protocol family . 56A protocol family provides basic services to the protocol 57implementation to allow it to function within a specific 58network environment. 59These services may include packet fragmentation and reassembly, routing, 60addressing, and basic transport. 61A protocol family may support multiple methods of addressing, though 62the current protocol implementations do not. 63A protocol family is normally comprised of a number of protocols, one per 64.Xr socket 2 65type. 66It is not required that a protocol family support all socket types. 67A protocol family may contain multiple protocols supporting the same socket 68abstraction. 69.Pp 70A protocol supports one of the socket abstractions detailed in 71.Xr socket 2 . 72A specific protocol may be accessed either by creating a 73socket of the appropriate type and protocol family, or 74by requesting the protocol explicitly when creating a socket. 75Protocols normally accept only one type of address format, 76usually determined by the addressing structure inherent in 77the design of the protocol family/network architecture. 78Certain semantics of the basic socket abstractions are 79protocol specific. 80All protocols are expected to support the basic model for their particular 81socket type, but may, in addition, provide non-standard facilities or 82extensions to a mechanism. 83For example, a protocol supporting the 84.Dv SOCK_STREAM 85abstraction may allow more than one byte of out-of-band 86data to be transmitted per out-of-band message. 87.Pp 88A network interface is similar to a device interface. 89Network interfaces comprise the lowest layer of the 90networking subsystem, interacting with the actual transport 91hardware. 92An interface may support one or more protocol families and/or address formats. 93The 94.Sx SYNOPSIS 95section of each network interface entry gives a sample 96specification of the related drivers for use in providing a system description 97to the 98.Xr config 8 99program. 100The 101.Sx DIAGNOSTICS 102section lists messages which may appear on the console 103and/or in the system error log, 104.Pa /var/log/messages 105(see 106.Xr syslogd 8 ) , 107due to errors in device operation. 108.Pp 109Network interfaces may be collected together into interface groups. 110An interface group is a container that can be used generically when 111referring to any interface related by some criteria. 112When an action is performed on an interface group, such as packet 113filtering by the 114.Xr pf 4 115subsystem, the operation will be applied to each member interface in the 116group, if supported by the subsystem. 117The 118.Xr ifconfig 8 119utility can be used to view and assign membership of an interface to an 120interface group with the 121.Cm group 122modifier. 123.Sh PROTOCOLS 124The system currently supports the 125Internet protocols (IPv4 and IPv6), 126MPLS, 127and a few others. 128Raw socket interfaces are provided to the IP protocol 129layer of the 130Internet. 131Consult the appropriate manual pages in this section for more 132information regarding the support for each protocol family. 133.Sh ADDRESSING 134Associated with each protocol family is an address 135format. 136All network addresses adhere to a general structure, called a 137.Vt sockaddr , 138described below. 139However, each protocol imposes a finer, more specific structure, generally 140renaming the variant, which is discussed in the protocol family manual 141page alluded to above. 142.Bd -literal -offset indent 143struct sockaddr { 144 u_int8_t sa_len; /* total length */ 145 sa_family_t sa_family; /* address family */ 146 char sa_data[14]; /* actually longer */ 147}; 148.Ed 149.Pp 150The field 151.Va sa_len 152contains the total length of the structure, 153which may exceed 16 bytes. 154The following address values for 155.Va sa_family 156are known to the system 157(and additional formats are defined for possible future implementation): 158.Bd -literal 159#define AF_LOCAL 1 /* local to host */ 160#define AF_INET 2 /* internetwork: UDP, TCP, etc. */ 161#define AF_INET6 24 /* IPv6 */ 162#define AF_MPLS 33 /* Multiprotocol Label Switching */ 163.Ed 164.Pp 165The 166.Va sa_data 167field contains the actual address value. 168Note that it may be longer than 14 bytes. 169.Sh ROUTING 170.Ox 171provides some packet routing facilities. 172The kernel maintains a routing information database, which 173is used in selecting the appropriate network interface when 174transmitting packets. 175.Pp 176A user process (or possibly multiple co-operating processes) 177maintains this database by sending messages over a special kind 178of socket. 179This supplants fixed-size 180.Xr ioctl 2 Ns s 181used in earlier releases. 182.Pp 183This facility is described in 184.Xr route 4 . 185.Sh INTERFACES 186Each network interface in a system corresponds to a 187path through which messages may be sent and received. 188A network interface usually has a hardware device associated with it, 189though certain interfaces such as the loopback interface, 190.Xr lo 4 , 191do not. 192.Pp 193The following 194.Xr ioctl 2 195calls may be used to manipulate network interfaces. 196The 197.Xr ioctl 2 198is made on a socket (typically of type 199.Dv SOCK_DGRAM ) 200in the desired domain. 201Most of the requests 202take an 203.Vt ifreq 204structure pointer as their parameter. 205This structure is as follows: 206.Bd -literal 207struct ifreq { 208#define IFNAMSIZ 16 209 char ifr_name[IFNAMSIZ]; /* if name, e.g. "en0" */ 210 union { 211 struct sockaddr ifru_addr; 212 struct sockaddr ifru_dstaddr; 213 struct sockaddr ifru_broadaddr; 214 short ifru_flags; 215 int ifru_metric; 216 int64_t ifru_vnetid; 217 uint64_t ifru_media; 218 caddr_t ifru_data; 219 unsigned int ifru_index; 220 } ifr_ifru; 221#define ifr_addr ifr_ifru.ifru_addr /* address */ 222#define ifr_dstaddr ifr_ifru.ifru_dstaddr /* other end of p-to-p link */ 223#define ifr_broadaddr ifr_ifru.ifru_broadaddr /* broadcast address */ 224#define ifr_flags ifr_ifru.ifru_flags /* flags */ 225#define ifr_metric ifr_ifru.ifru_metric /* metric */ 226#define ifr_mtu ifr_ifru.ifru_metric /* mtu (overload) */ 227#define ifr_hardmtu ifr_ifru.ifru_metric /* hardmtu (overload) */ 228#define ifr_media ifr_ifru.ifru_media /* media options */ 229#define ifr_rdomainid ifr_ifru.ifru_metric /* VRF instance (overload) */ 230#define ifr_vnetid ifr_ifru.ifru_vnetid /* Virtual Net Id */ 231#define ifr_ttl ifr_ifru.ifru_metric /* tunnel TTL (overload) */ 232#define ifr_data ifr_ifru.ifru_data /* for use by interface */ 233#define ifr_index ifr_ifru.ifru_index /* interface index */ 234#define ifr_llprio ifr_ifru.ifru_metric /* link layer priority */ 235}; 236.Ed 237.Pp 238The supported 239.Xr ioctl 2 240requests are: 241.Bl -tag -width Ds 242.It Dv SIOCSIFADDR Fa "struct ifreq *" 243Set the interface address for a protocol family. 244Following the address assignment, the 245.Dq initialization 246routine for the 247interface is called. 248.Pp 249This call has been deprecated and superseded by the 250.Dv SIOCAIFADDR 251call, described below. 252.It Dv SIOCSIFDSTADDR Fa "struct ifreq *" 253Set the point-to-point address for a protocol family and interface. 254.Pp 255This call has been deprecated and superseded by the 256.Dv SIOCAIFADDR 257call, described below. 258.It Dv SIOCSIFBRDADDR Fa "struct ifreq *" 259Set the broadcast address for a protocol family and interface. 260.Pp 261This call has been deprecated and superseded by the 262.Dv SIOCAIFADDR 263call, described below. 264.It Dv SIOCGIFADDR Fa "struct ifreq *" 265Get the interface address for a protocol family. 266.It Dv SIOCGIFDSTADDR Fa "struct ifreq *" 267Get the point-to-point address for a protocol family and interface. 268.It Dv SIOCGIFBRDADDR Fa "struct ifreq *" 269Get the broadcast address for a protocol family and interface. 270.It Dv SIOCGIFDESCR Fa "struct ifreq *" 271Get the interface description, returned in the 272.Va ifru_data 273field. 274.It Dv SIOCSIFDESCR Fa "struct ifreq *" 275Set the interface description to the value of the 276.Va ifru_data 277field, limited to the size of 278.Dv IFDESCRSIZE . 279.It Dv SIOCSIFFLAGS Fa "struct ifreq *" 280Set the interface flags. 281If the interface is marked down, any processes currently routing packets 282through the interface are notified; some interfaces may be reset so that 283incoming packets are no longer received. 284When marked up again, the interface is reinitialized. 285.It Dv SIOCGIFFLAGS Fa "struct ifreq *" 286Get the interface flags. 287.It Dv SIOCGIFXFLAGS Fa "struct ifreq *" 288Get the extended interface flags. 289.It Dv SIOCGIFMTU Fa "struct ifreq *" 290Get the current MTU of the interface. 291.It Dv SIOCGIFHARDMTU Fa "struct ifreq *" 292Get the maximum hardware MTU of the interface. 293.It Dv SIOCSIFMEDIA Fa "struct ifreq *" 294Set the interface media settings. 295See 296.Xr ifmedia 4 297for possible values. 298.It Dv SIOCGIFMEDIA Fa "struct ifmediareq *" 299Get the interface media settings. 300The 301.Vt ifmediareq 302structure is as follows: 303.Bd -literal 304struct ifmediareq { 305 char ifm_name[IFNAMSIZ]; /* if name, e.g. "en0" */ 306 uint64_t ifm_current; /* current media options */ 307 uint64_t ifm_mask; /* don't care mask */ 308 uint64_t ifm_status; /* media status */ 309 uint64_t ifm_active; /* active options */ 310 int ifm_count; /* #entries in ifm_ulist array */ 311 uint64_t *ifm_ulist; /* media words */ 312}; 313.Ed 314.Pp 315See 316.Xr ifmedia 4 317for interpreting this value. 318.It Dv SIOCSIFMETRIC Fa "struct ifreq *" 319Set the interface routing metric. 320The metric is used only by user-level routers. 321.It Dv SIOCGIFMETRIC Fa "struct ifreq *" 322Get the interface metric. 323.It Dv SIOCSIFPRIORITY Fa "struct ifreq *" 324Set the interface routing priority. 325The interface routing priority influences the resulting routing priority of 326new static routes added to the kernel using the specified interface. 327The value is in the range of 0 to 16 with smaller numbers being better. 328.It Dv SIOCGIFPRIORITY Fa "struct ifreq *" 329Get the interface priority. 330.It Dv SIOCGIFRDOMAIN Fa "struct ifreq *" 331Get the interface routing domain. 332This identifies which routing table is used for the interface. 333.It Dv SIOCAIFADDR Fa "struct ifaliasreq *" 334An interface may have more than one address associated with it 335in some protocols. 336This request provides a means to add additional addresses (or modify 337characteristics of the primary address if the default address for the 338address family is specified). 339.Pp 340Rather than making separate calls to set destination or broadcast addresses, 341or network masks (now an integral feature of multiple protocols), a separate 342structure, 343.Vt ifaliasreq , 344is used to specify all three facets simultaneously (see below). 345One would use a slightly tailored version of this structure specific 346to each family (replacing each 347.Vt sockaddr 348by one 349of the family-specific type). 350One should always set the length of a 351.Vt sockaddr , 352as described in 353.Xr ioctl 2 . 354.Pp 355The 356.Vt ifaliasreq 357structure is as follows: 358.Bd -literal 359struct ifaliasreq { 360 char ifra_name[IFNAMSIZ]; /* if name, e.g. "en0" */ 361 struct sockaddr ifra_addr; 362 struct sockaddr ifra_dstaddr; 363#define ifra_broadaddr ifra_dstaddr 364 struct sockaddr ifra_mask; 365}; 366.Ed 367.It Dv SIOCDIFADDR Fa "struct ifreq *" 368This request deletes the specified address from the list 369associated with an interface. 370It also uses the 371.Vt ifaliasreq 372structure to allow for the possibility of protocols allowing 373multiple masks or destination addresses, and also adopts the 374convention that specification of the default address means 375to delete the first address for the interface belonging to 376the address family in which the original socket was opened. 377.It Dv SIOCGIFCONF Fa "struct ifconf *" 378Get the interface configuration list. 379This request takes an 380.Vt ifconf 381structure (see below) as a value-result parameter. 382The 383.Va ifc_len 384field should be initially set to the size of the buffer 385pointed to by 386.Va ifc_buf . 387On return it will contain the length, in bytes, of the 388configuration list. 389.Pp 390Alternately, if the 391.Va ifc_len 392passed in is set to 0, 393.Dv SIOCGIFCONF 394will set 395.Va ifc_len 396to the size that 397.Va ifc_buf 398needs to be to fit the entire configuration list and will not 399fill in the other parameters. 400This is useful for determining the exact size that 401.Va ifc_buf 402needs to be in advance. 403Note, however, that this is an extension 404that not all operating systems support. 405.Bd -literal 406struct ifconf { 407 int ifc_len; /* size of associated buffer */ 408 union { 409 caddr_t ifcu_buf; 410 struct ifreq *ifcu_req; 411 } ifc_ifcu; 412#define ifc_buf ifc_ifcu.ifcu_buf /* buffer address */ 413#define ifc_req ifc_ifcu.ifcu_req /* array of structures ret'd */ 414}; 415.Ed 416.It Dv SIOCIFCREATE Fa "struct ifreq *" 417Attempt to create the specified interface. 418.It Dv SIOCIFDESTROY Fa "struct ifreq *" 419Attempt to destroy the specified interface. 420.It Dv SIOCIFGCLONERS Fa "struct if_clonereq *" 421Get the list of clonable interfaces. 422This request takes an 423.Vt if_clonereq 424structure pointer (see below) as a value-result parameter. 425The 426.Va ifcr_count 427field should be set to the number of 428.Dv IFNAMSIZ Ns -sized 429strings that can fit in the buffer pointed to by 430.Va ifcr_buffer . 431On return, 432.Va ifcr_total 433will be set to the number of clonable interfaces, and the buffer pointed 434to by 435.Va ifcr_buffer 436will be filled with the names of clonable interfaces aligned on 437.Dv IFNAMSIZ 438boundaries. 439.Pp 440The 441.Vt if_clonereq 442structure is as follows: 443.Bd -literal 444struct if_clonereq { 445 int ifcr_total; /* total cloners (out) */ 446 int ifcr_count; /* room for this many in user buf */ 447 char *ifcr_buffer; /* buffer for cloner names */ 448}; 449.Ed 450.It Dv SIOCAIFGROUP Fa "struct ifgroupreq *" 451Associate the interface named by 452.Va ifgr_name 453with the interface group named by 454.Va ifgr_group . 455The 456.Vt ifgroupreq 457structure is as follows: 458.Bd -literal 459struct ifg_req { 460 char ifgrq_group[IFNAMSIZ]; 461}; 462 463struct ifgroupreq { 464 char ifgr_name[IFNAMSIZ]; 465 u_int ifgr_len; 466 union { 467 char ifgru_group[IFNAMSIZ]; 468 struct ifg_req *ifgru_groups; 469 } ifgr_ifgru; 470#define ifgr_group ifgr_ifgru.ifgru_group 471#define ifgr_groups ifgr_ifgru.ifgru_groups 472}; 473.Ed 474.It Dv SIOCGIFGROUP Fa "struct ifgroupreq *" 475Retrieve the list of groups for which an interface is a member. 476The interface is named by 477.Va ifgr_name . 478On enter, the amount of memory in which the group names will 479be written is stored in 480.Va ifgr_len , 481and the group names themselves will be written to the memory 482pointed to by 483.Va ifgr_groups . 484On return, the amount of memory actually written is returned in 485.Va ifgr_len . 486.Pp 487Alternately, if the 488.Va ifgr_len 489passed in is set to 0, 490.Dv SIOCGIFGROUP 491will set 492.Va ifgr_len 493to the size that 494.Va ifgr_groups 495needs to be to fit the entire group list and will not 496fill in the other parameters. 497This is useful for determining the exact size that 498.Va ifgr_groups 499needs to be in advance. 500.It Dv SIOCDIFGROUP Fa "struct ifgroupreq *" 501Remove the membership of the interface named by 502.Va ifgr_name 503from the group 504.Va ifgr_group . 505.El 506.Sh SEE ALSO 507.Xr netstat 1 , 508.Xr ioctl 2 , 509.Xr socket 2 , 510.Xr arp 4 , 511.Xr bridge 4 , 512.Xr ifmedia 4 , 513.Xr inet 4 , 514.Xr intro 4 , 515.Xr ip 4 , 516.Xr ip6 4 , 517.Xr lo 4 , 518.Xr mpe 4 , 519.Xr pf 4 , 520.Xr tcp 4 , 521.Xr udp 4 , 522.Xr hosts 5 , 523.Xr networks 5 , 524.Xr bgpd 8 , 525.Xr config 8 , 526.Xr ifconfig 8 , 527.Xr mrouted 8 , 528.Xr netstart 8 , 529.Xr ospfd 8 , 530.Xr ripd 8 , 531.Xr route 8 532.Sh HISTORY 533The 534.Nm 535manual appeared in 536.Bx 4.3 Tahoe . 537