1 IP(7P) Protocols IP(7P)
2
3
4
5 NAME
6 ip, IP - Internet Protocol
7
8 SYNOPSIS
9 #include <sys/socket.h>
10
11
12 #include <netinet/in.h>
13
14
15 s = socket(AF_INET, SOCK_RAW, proto);
16
17
18 t = t_open ("/dev/rawip", O_RDWR);
19
20
21 DESCRIPTION
22 IP is the internetwork datagram delivery protocol that is central to
23 the Internet protocol family. Programs may use IP through higher-level
24 protocols such as the Transmission Control Protocol (TCP) or the User
25 Datagram Protocol (UDP), or may interface directly to IP. See tcp(7P)
26 and udp(7P). Direct access may be by means of the socket interface,
27 using a "raw socket," or by means of the Transport Level Interface
28 (TLI). The protocol options defined in the IP specification may be set
29 in outgoing datagrams.
30
31
32 Packets sent to or from this system may be subject to IPsec policy. See
33 ipsec(7P) for more information.
34
35 APPLICATION PROGRAMMING INTERFACE
36 The STREAMS driver /dev/rawip is the TLI transport provider that
37 provides raw access to IP.
38
39
40 Raw IP sockets are connectionless and are normally used with the
41 sendto() and recvfrom() calls (see send(3SOCKET) and recv(3SOCKET)),
42 although the connect(3SOCKET) call may also be used to fix the
43 destination for future datagram. In this case, the read(2) or
44 recv(3SOCKET) and write(2) or send(3SOCKET) calls may be used. If proto
45 is IPPROTO_RAW or IPPROTO_IGMP, the application is expected to include
46 a complete IP header when sending. Otherwise, that protocol number
47 will be set in outgoing datagrams and used to filter incoming datagrams
48 and an IP header will be generated and prepended to each outgoing
49 datagram. In either case, received datagrams are returned with the IP
50 header and options intact.
51
52
53 If an application uses IP_HDRINCL and provides the IP header contents,
54 the IP stack does not modify the following supplied fields under any
55 conditions: Type of Service, DF Flag, Protocol, and Destination
56 Address. The IP Options and IHL fields are set by use of IP_OPTIONS,
57 and Total Length is updated to include any options. Version is set to
58 the default. Identification is chosen by the normal IP ID selection
59 logic. The source address is updated if none was specified and the TTL
60 is changed if the packet has a broadcast destination address. Since an
61 applicaton cannot send down fragments (as IP assigns the IP ID),
62 Fragment Offset is always 0. The IP Checksum field is computed by IP.
63 None of the data beyond the IP header are changed, including the
64 application-provided transport header.
65
66
67 The socket options supported at the IP level are:
68
69 IP_OPTIONS
70 IP options for outgoing datagrams. This socket
71 option may be used to set IP options to be
72 included in each outgoing datagram. IP options to
73 be sent are set with setsockopt() (see
74 getsockopt(3SOCKET)). The getsockopt(3SOCKET)
75 call returns the IP options set in the last
76 setsockopt() call. IP options on received
77 datagrams are visible to user programs only using
78 raw IP sockets. The format of IP options given in
79 setsockopt() matches those defined in the IP
80 specification with one exception: the list of
81 addresses for the source routing options must
82 include the first-hop gateway at the beginning of
83 the list of gateways. The first-hop gateway
84 address will be extracted from the option list
85 and the size adjusted accordingly before use. IP
86 options may be used with any socket type in the
87 Internet family.
88
89
90 IP_SEC_OPT
91 Enable or obtain IPsec security settings for this
92 socket. For more details on the protection
93 services of IPsec, see ipsec(7P).
94
95
96 IP_ADD_MEMBERSHIP
97 Join a multicast group.
98
99
100 IP_DROP_MEMBERSHIP
101 Leave a multicast group.
102
103
104 IP_BOUND_IF
105 Limit reception and transmission of packets to
106 this interface. Takes an integer as an argument.
107 The integer is the selected interface index.
108
109
110
111 The following option takes in_pktinfo_t as the parameter:
112
113 IP_PKTINFO
114
115 Set the source address and/or transmit interface of the packet(s).
116 Note that the IP_BOUND_IF socket option takes precedence over the
117 interface index passed in IP_PKTINFO.
118
119 struct in_pktinfo {
120 unsigned int ipi_ifindex;/* send/recv interface index */
121 struct in_addr ipi_spec_dst;/* matched source addr. */
122 struct in_addr ipi_addr;/* src/dst addr. in IP hdr */
123 } in_pktinfo_t;
124
125 When passed in (on transmit) via ancillary data with IP_PKTINFO,
126 ipi_spec_dst is used as the source address and ipi_ifindex is used
127 as the interface index to send the packet out.
128
129
130
131 The following options are boolean switches controlling the reception of
132 ancillary data:
133
134
135 IP_RECVDSTADDR
136 When enabled on a SOCK_DGRAM socket, enables
137 receipt of the destination IP address of the
138 incoming packet. Returns inaddr_t as ancillary
139 data.
140
141
142 IP_RECVIF
143 Enable/disable receipt of the inbound interface
144 index. Returns uint_t as ancillary data.
145
146
147 IP_RECVOPTS
148 When enabled on a SOCK_DGRAM socket, enables
149 receipt of the IP options from the incoming
150 packet. Returns variable-length IP options, up to
151 40 bytes, as ancillary data.
152
153
154 IP_RECVPKTINFO
155 Enable/disable receipt of the index of the
156 interface the packet arrived on, the local
157 address that was matched for reception, and the
158 inbound packet's actual destination address.
159 Takes boolean as the parameter. Returns
160 in_pktinfo_t as ancillary data.
161
162
163 IP_RECVSLLA
164 When enabled on a SOCK_DGRAM socket, enables
165 receipt of the source link-layer address for the
166 incoming packet. Returns struct sockaddr_dl as
167 ancillary data.
168
169
170 IP_RECVTTL
171 When enabled on a SOCK_DGRAM socket, the IP TTL
172 (time to live) field for an incoming datagram is
173 returned as uint8_t in ancillary data.
174
175
176 IP_RECVTOS
177 When enabled, the IP TOS (type of service) field
178 is returned as uint8_t in ancillary data. For
179 SOCK_DGRAM sockets, the ancillary data item is
180 included for every call to recvmsg(). For
181 SOCK_STREAM sockets, where there is no direct
182 mapping between received TCP segments and receive
183 operations, the ancillary data item will only be
184 present when the value has changed.
185
186
187
188 The following options take a struct ip_mreq as the parameter. The
189 structure contains a multicast address which must be set to the CLASS-D
190 IP multicast address and an interface address. Normally the interface
191 address is set to INADDR_ANY which causes the kernel to choose the
192 interface on which to join.
193
194 IP_BLOCK_SOURCE
195 Block multicast packets whose source
196 address matches the given source address.
197 The specified group must be joined
198 previously using IP_ADD_MEMBERSHIP or
199 MCAST_JOIN_GROUP.
200
201
202 IP_UNBLOCK_SOURCE
203 Unblock (begin receiving) multicast
204 packets which were previously blocked
205 using IP_BLOCK_SOURCE.
206
207
208 IP_ADD_SOURCE_MEMBERSHIP
209 Begin receiving packets for the given
210 multicast group whose source address
211 matches the specified address.
212
213
214 IP_DROP_SOURCE_MEMBERSHIP
215 Stop receiving packets for the given
216 multicast group whose source address
217 matches the specified address.
218
219
220
221 The following options take a struct ip_mreq_source as the parameter.
222 The structure contains a multicast address (which must be set to the
223 CLASS-D IP multicast address), an interface address, and a source
224 address.
225
226 MCAST_JOIN_GROUP
227 Join a multicast group. Functionally
228 equivalent to IP_ADD_MEMBERSHIP.
229
230
231 MCAST_BLOCK_SOURCE
232 Block multicast packets whose source
233 address matches the given source address.
234 The specified group must be joined
235 previously using IP_ADD_MEMBERSHIP or
236 MCAST_JOIN_GROUP.
237
238
239 MCAST_UNBLOCK_SOURCE
240 Unblock (begin receiving) multicast packets
241 which were previously blocked using
242 MCAST_BLOCK_SOURCE.
243
244
245 MCAST_LEAVE_GROUP
246 Leave a multicast group. Functionally
247 equivalent to IP_DROP_MEMBERSHIP.
248
249
250 MCAST_JOIN_SOURCE_GROUP
251 Begin receiving packets for the given
252 multicast group whose source address
253 matches the specified address.
254
255
256 MCAST_LEAVE_SOURCE_GROUP
257 Stop receiving packets for the given
258 multicast group whose source address
259 matches the specified address.
260
261
262
263 The following options take a struct group_req or struct
264 group_source_req as the parameter. The `group_req structure contains an
265 interface index and a multicast address which must be set to the CLASS-
266 D multicast address. The group_source_req structure is used for those
267 options which include a source address. It contains an interface index,
268 multicast address, and source address.
269
270 IP_MULTICAST_IF
271 The outgoing interface for multicast packets. This
272 option takes a struct in_addr as an argument, and
273 it selects that interface for outgoing IP
274 multicast packets. If the address specified is
275 INADDR_ANY, it uses the unicast routing table to
276 select the outgoing interface (which is the
277 default behavior).
278
279
280 IP_MULTICAST_TTL
281 Time to live for multicast datagrams. This option
282 takes an unsigned character as an argument. Its
283 value is the TTL that IP uses on outgoing
284 multicast datagrams. The default is 1.
285
286
287 IP_MULTICAST_LOOP
288 Loopback for multicast datagrams. Normally
289 multicast datagrams are delivered to members on
290 the sending host (or sending zone). Setting the
291 unsigned character argument to 0 causes the
292 opposite behavior, meaning that when multiple
293 zones are present, the datagrams are delivered to
294 all zones except the sending zone.
295
296
297 IP_TOS
298 This option takes an integer argument as its input
299 value. The least significant 8 bits of the value
300 are used to set the Type Of Service field in the
301 IP header of the outgoing packets.
302
303
304 IP_NEXTHOP
305 This option specifies the address of the onlink
306 nexthop for traffic originating from that socket.
307 It causes the routing table to be bypassed and
308 outgoing traffic is sent directly to the specified
309 nexthop. This option takes an ipaddr_t argument
310 representing the IPv4 address of the nexthop as
311 the input value. The IP_NEXTHOP option takes
312 precedence over IPOPT_LSRR. IP_BOUND_IF and
313 SO_DONTROUTE take precedence over IP_NEXTHOP. This
314 option has no meaning for broadcast and multicast
315 packets. The application must ensure that the
316 specified nexthop is alive. An application may
317 want to specify the IP_NEXTHOP option on a TCP
318 listener socket only for incoming requests to a
319 particular IP address. In this case, it must avoid
320 binding the socket to INADDR_ANY and instead must
321 bind the listener socket to the specific IP
322 address. In addition, typically the application
323 may want the incoming and outgoing interface to be
324 the same. In this case, the application must
325 select a suitable nexthop that is onlink and
326 reachable via the desired interface and do a
327 setsockopt (IP_NEXTHOP) on it. Then it must bind
328 to the IP address of the desired interface.
329 Setting the IP_NEXTHOP option requires the
330 PRIV_SYS_NET_CONFIG privilege.
331
332
333
334 The multicast socket options (IP_MULTICAST_IF, IP_MULTICAST_TTL,
335 IP_MULTICAST_LOOP and IP_RECVIF) can be used with any datagram socket
336 type in the Internet family.
337
338
339 At the socket level, the socket option SO_DONTROUTE may be applied.
340 This option forces datagrams being sent to bypass routing and
341 forwarding by forcing the IP Time To Live field to 1, meaning that the
342 packet will not be forwarded by routers.
343
344
345 Raw IP datagrams can also be sent and received using the TLI
346 connectionless primitives.
347
348
349 Datagrams flow through the IP layer in two directions: from the network
350 up to user processes and from user processes down to the network.
351 Using this orientation, IP is layered above the network interface
352 drivers and below the transport protocols such as UDP and TCP. The
353 Internet Control Message Protocol (ICMP) is logically a part of IP. See
354 icmp(7P).
355
356
357 IP provides for a checksum of the header part, but not the data part,
358 of the datagram. The checksum value is computed and set in the process
359 of sending datagrams and checked when receiving datagrams.
360
361
362 IP options in received datagrams are processed in the IP layer
363 according to the protocol specification. Currently recognized IP
364 options include: security, loose source and record route (LSRR), strict
365 source and record route (SSRR), record route, and internet timestamp.
366
367
368 By default, the IP layer will not forward IPv4 packets that are not
369 addressed to it. This behavior can be overridden by using routeadm(1M)
370 to enable the ipv4-forwarding option. IPv4 forwarding is configured at
371 boot time based on the setting of routeadm(1M)'s ipv4-forwarding
372 option.
373
374
375 For backwards compatibility, IPv4 forwarding can be enabled or disabled
376 using ndd(1M)'s ip_forwarding variable. It is set to 1 if IPv4
377 forwarding is enabled, or 0 if it is disabled.
378
379
380 Additionally, finer-grained forwarding can be configured in IP. Each
381 interface can be configured to forward IP packets by setting the
382 IFF_ROUTER interface flag. This flag can be set and cleared using
383 ifconfig(1M)'s router and router options. If an interface's IFF_ROUTER
384 flag is set, packets can be forwarded to or from the interface. If it
385 is clear, packets will neither be forwarded from this interface to
386 others, nor forwarded to this interface. Setting the ip_forwarding
387 variable sets all of the IPv4 interfaces' IFF_ROUTER flags.
388
389
390 For backwards compatibility, each interface creates an
391 <ifname>:ip_forwarding /dev/ip variable that can be modified using
392 ndd(1M). An interface's :ip_forwarding ndd variable is a boolean
393 variable that mirrors the status of its IFF_ROUTER interface flag. It
394 is set to 1 if the flag is set, or 0 if it is clear. This interface
395 specific <ifname> :ip_forwarding ndd variable is obsolete and may be
396 removed in a future release of Solaris. The ifconfig(1M) router and
397 -router interfaces are preferred.
398
399
400 The IP layer sends an ICMP message back to the source host in many
401 cases when it receives a datagram that can not be handled. A "time
402 exceeded" ICMP message is sent if the "time to live" field in the IP
403 header drops to zero in the process of forwarding a datagram. A
404 "destination unreachable" message is sent if a datagram can not be
405 forwarded because there is no route to the final destination, or if it
406 can not be fragmented. If the datagram is addressed to the local host
407 but is destined for a protocol that is not supported or a port that is
408 not in use, a destination unreachable message is also sent. The IP
409 layer may send an ICMP "source quench" message if it is receiving
410 datagrams too quickly. ICMP messages are only sent for the first
411 fragment of a fragmented datagram and are never returned in response to
412 errors in other ICMP messages.
413
414
415 The IP layer supports fragmentation and reassembly. Datagrams are
416 fragmented on output if the datagram is larger than the maximum
417 transmission unit (MTU) of the network interface. Fragments of received
418 datagrams are dropped from the reassembly queues if the complete
419 datagram is not reconstructed within a short time period.
420
421
422 Errors in sending discovered at the network interface driver layer are
423 passed by IP back up to the user process.
424
425
426 Multi-Data Transmit allows more than one packet to be sent from the IP
427 module to another in a given call, thereby reducing the per-packet
428 processing costs. The behavior of Multi-Data Transmit can be
429 overrideen by using ndd(1M) to set the /dev/ip variable,
430 ip_multidata_outbound to 0. Note, the IP module will only initiate
431 Multi-Data Transmit if the network interface driver supports it.
432
433 PACKET EVENTS
434 Through the netinfo framework, this driver provides the following
435 packet events:
436
437 Physical in
438 Packets received on a network interface from an
439 external source.
440
441
442 Physical out
443 Packets to be sent out a network interface.
444
445
446 Forwarding
447 Packets being forwarded through this host to another
448 network.
449
450
451 loopback in
452 Packets that have been sent by a local application to
453 another.
454
455
456 loopback out
457 Packets about to be received by a local application
458 from another.
459
460
461
462 Currently, only a single function may be registered for each event. As
463 a result, if the slot for an event is already occupied by someone else,
464 a second attempt to register a callback fails.
465
466
467 To receive packet events in a kernel module, it is first necessary to
468 obtain a handle for either IPv4 or IPv6 traffic. This is achieved by
469 passing NHF_INET or NHF_INET6 through to a net_protocol_lookup() call.
470 The value returned from this call must then be passed into a call to
471 net_register_hook(), along with a description of the hook to add. For a
472 description of the structure passed through to the callback, please
473 see hook_pkt_event(9S). For IP packets, this structure is filled out as
474 follows:
475
476 hpe_ifp
477 Identifier indicating the inbound interface for packets
478 received with the "physical in" event.
479
480
481 hpe_ofp
482 Identifier indicating the outbound interface for packets
483 received with the "physical out" event.
484
485
486 hpe_hdr
487 Pointer to the start of the IP header (not the ethernet
488 header).
489
490
491 hpe_mp
492 Pointer to the start of the mblk_t chain containing the IP
493 packet.
494
495
496 hpe_mb
497 Pointer to the mblk_t with the IP header in it.
498
499
500 NETWORK INTERFACE EVENTS
501 In addition to events describing packets as they move through the
502 system, it is also possible to receive notification of events relating
503 to network interfaces. These events are all reported back through the
504 same callback. The list of events is as follows:
505
506 plumb
507 A new network interface has been instantiated.
508
509
510 unplumb
511 A network interface is no longer associated with this
512 protocol.
513
514
515 up
516 At least one logical interface is now ready to
517 receive packets.
518
519
520 down
521 There are no logical interfaces expecting to receive
522 packets.
523
524
525 address change
526 An address has changed on a logical interface.
527
528
529 SEE ALSO
530 ifconfig(1M), routeadm(1M), ndd(1M), read(2), write(2),
531 socket.h(3HEAD), bind(3SOCKET), connect(3SOCKET), getsockopt(3SOCKET),
532 recv(3SOCKET), send(3SOCKET), defaultrouter(4), icmp(7P), if_tcp(7P),
533 inet(7P), ip(7P), ip6(7P), ipsec(7P), routing(7P), tcp(7P), udp(7P),
534 net_hook_register(9F), hook_pkt_event(9S)
535
536
537 Braden, R., RFC 1122, Requirements for Internet Hosts - Communication
538 Layers, Information Sciences Institute, University of Southern
539 California, October 1989.
540
541
542 Postel, J., RFC 791, Internet Protocol - DARPA Internet Program
543 Protocol Specification, Information Sciences Institute, University of
544 Southern California, September 1981.
545
546 DIAGNOSTICS
547 A socket operation may fail with one of the following errors returned:
548
549 EACCES
550 A bind() operation was attempted with a "reserved"
551 port number and the effective user ID of the process
552 was not the privileged user.
553
554 Setting the IP_NEXTHOP was attempted by a process
555 lacking the PRIV_SYS_NET_CONFIG privilege.
556
557
558 EADDRINUSE
559 A bind() operation was attempted on a socket with a
560 network address/port pair that has already been bound
561 to another socket.
562
563
564 EADDRNOTAVAIL
565 A bind() operation was attempted for an address that
566 is not configured on this machine.
567
568
569 EINVAL
570 A sendmsg() operation with a non-NULL msg_accrights
571 was attempted.
572
573
574 EINVAL
575 A getsockopt() or setsockopt() operation with an
576 unknown socket option name was given.
577
578
579 EINVAL
580 A getsockopt() or setsockopt() operation was attempted
581 with the IP option field improperly formed; an option
582 field was shorter than the minimum value or longer
583 than the option buffer provided.
584
585
586 EISCONN
587 A connect() operation was attempted on a socket on
588 which a connect() operation had already been
589 performed, and the socket could not be successfully
590 disconnected before making the new connection.
591
592
593 EISCONN
594 A sendto() or sendmsg() operation specifying an
595 address to which the message should be sent was
596 attempted on a socket on which a connect() operation
597 had already been performed.
598
599
600 EMSGSIZE
601 A send(), sendto(), or sendmsg() operation was
602 attempted to send a datagram that was too large for an
603 interface, but was not allowed to be fragmented (such
604 as broadcasts).
605
606
607 ENETUNREACH
608 An attempt was made to establish a connection by means
609 of connect(), or to send a datagram by means of
610 sendto() or sendmsg(), where there was no matching
611 entry in the routing table; or if an ICMP "destination
612 unreachable" message was received.
613
614
615 ENOTCONN
616 A send() or write() operation, or a sendto() or
617 sendmsg() operation not specifying an address to which
618 the message should be sent, was attempted on a socket
619 on which a connect() operation had not already been
620 performed.
621
622
623 ENOBUFS
624 The system ran out of memory for fragmentation buffers
625 or other internal data structures.
626
627
628 ENOBUFS
629 SO_SNDBUF or SO_RCVBUF exceeds a system limit.
630
631
632 EINVAL
633 Invalid length for IP_OPTIONS.
634
635
636 EHOSTUNREACH
637 Invalid address for IP_MULTICAST_IF.
638
639 Invalid (offlink) nexthop address for IP_NEXTHOP.
640
641
642 EINVAL
643 Not a multicast address for IP_ADD_MEMBERSHIP and
644 IP_DROP_MEMBERSHIP.
645
646
647 EADDRNOTAVAIL
648 Bad interface address for IP_ADD_MEMBERSHIP and
649 IP_DROP_MEMBERSHIP.
650
651
652 EADDRINUSE
653 Address already joined for IP_ADD_MEMBERSHIP.
654
655
656 ENOENT
657 Address not joined for IP_DROP_MEMBERSHIP.
658
659
660 ENOPROTOOPT
661 Invalid socket type.
662
663
664 EPERM
665 No permissions.
666
667
668 NOTES
669 Raw sockets should receive ICMP error packets relating to the protocol;
670 currently such packets are simply discarded.
671
672
673 Users of higher-level protocols such as TCP and UDP should be able to
674 see received IP options.
675
676
677
678 September 18, 2020 IP(7P)