git: d00a527f1c - main - Use One Sentence Per Line in the Developers Handbook
Sergio Carlavilla Delgado
carlavilla at FreeBSD.org
Sun Jun 6 12:26:30 UTC 2021
The branch main has been updated by carlavilla:
URL: https://cgit.FreeBSD.org/doc/commit/?id=d00a527f1ce922091d779911eaedde4efd122ea1
commit d00a527f1ce922091d779911eaedde4efd122ea1
Author: Sergio Carlavilla Delgado <carlavilla at FreeBSD.org>
AuthorDate: 2021-06-06 12:19:15 +0000
Commit: Sergio Carlavilla Delgado <carlavilla at FreeBSD.org>
CommitDate: 2021-06-06 12:19:15 +0000
Use One Sentence Per Line in the Developers Handbook
---
.../en/books/developers-handbook/_index.adoc | 9 +-
.../content/en/books/developers-handbook/book.adoc | 9 +-
.../developers-handbook/introduction/_index.adoc | 13 +-
.../en/books/developers-handbook/ipv6/_index.adoc | 318 ++++--
.../developers-handbook/kernelbuild/_index.adoc | 10 +-
.../developers-handbook/kerneldebug/_index.adoc | 182 +++-
.../en/books/developers-handbook/l10n/_index.adoc | 82 +-
.../en/books/developers-handbook/parti.adoc | 2 +-
.../books/developers-handbook/policies/_index.adoc | 97 +-
.../books/developers-handbook/secure/_index.adoc | 115 ++-
.../books/developers-handbook/sockets/_index.adoc | 413 ++++++--
.../books/developers-handbook/testing/_index.adoc | 34 +-
.../en/books/developers-handbook/tools/_index.adoc | 468 ++++++---
.../en/books/developers-handbook/x86/_index.adoc | 1060 ++++++++++++++------
14 files changed, 2051 insertions(+), 761 deletions(-)
diff --git a/documentation/content/en/books/developers-handbook/_index.adoc b/documentation/content/en/books/developers-handbook/_index.adoc
index c30bf0645d..43db14ab19 100644
--- a/documentation/content/en/books/developers-handbook/_index.adoc
+++ b/documentation/content/en/books/developers-handbook/_index.adoc
@@ -48,12 +48,15 @@ include::../../../../shared/en/urls.adoc[]
endif::[]
[.abstract-title]
-[abstract]
Abstract
-Welcome to the Developers' Handbook. This manual is a _work in progress_ and is the work of many individuals. Many sections do not yet exist and some of those that do exist need to be updated. If you are interested in helping with this project, send email to the {freebsd-doc}.
+Welcome to the Developers' Handbook.
+This manual is a _work in progress_ and is the work of many individuals.
+Many sections do not yet exist and some of those that do exist need to be updated.
+If you are interested in helping with this project, send email to the {freebsd-doc}.
-The latest version of this document is always available from the link:https://www.FreeBSD.org[FreeBSD World Wide Web server]. It may also be downloaded in a variety of formats and compression options from the link:https://download.freebsd.org/ftp/doc/[FreeBSD FTP server] or one of the numerous link:{handbook}#mirrors-ftp/[mirror sites].
+The latest version of this document is always available from the link:https://www.FreeBSD.org[FreeBSD World Wide Web server].
+It may also be downloaded in a variety of formats and compression options from the link:https://download.freebsd.org/ftp/doc/[FreeBSD FTP server] or one of the numerous link:{handbook}#mirrors-ftp/[mirror sites].
'''
diff --git a/documentation/content/en/books/developers-handbook/book.adoc b/documentation/content/en/books/developers-handbook/book.adoc
index 1e85eb8196..f874755ccd 100644
--- a/documentation/content/en/books/developers-handbook/book.adoc
+++ b/documentation/content/en/books/developers-handbook/book.adoc
@@ -61,12 +61,15 @@ include::../../../../shared/en/urls.adoc[]
endif::[]
[.abstract-title]
-[abstract]
Abstract
-Welcome to the Developers' Handbook. This manual is a _work in progress_ and is the work of many individuals. Many sections do not yet exist and some of those that do exist need to be updated. If you are interested in helping with this project, send email to the {freebsd-doc}.
+Welcome to the Developers' Handbook.
+This manual is a _work in progress_ and is the work of many individuals.
+Many sections do not yet exist and some of those that do exist need to be updated.
+If you are interested in helping with this project, send email to the {freebsd-doc}.
-The latest version of this document is always available from the link:https://www.FreeBSD.org[FreeBSD World Wide Web server]. It may also be downloaded in a variety of formats and compression options from the link:https://download.freebsd.org/ftp/doc/[FreeBSD FTP server] or one of the numerous link:{handbook}#mirrors-ftp/[mirror sites].
+The latest version of this document is always available from the link:https://www.FreeBSD.org[FreeBSD World Wide Web server].
+It may also be downloaded in a variety of formats and compression options from the link:https://download.freebsd.org/ftp/doc/[FreeBSD FTP server] or one of the numerous link:{handbook}#mirrors-ftp/[mirror sites].
'''
diff --git a/documentation/content/en/books/developers-handbook/introduction/_index.adoc b/documentation/content/en/books/developers-handbook/introduction/_index.adoc
index c7c9ad74d0..35e8e65fca 100644
--- a/documentation/content/en/books/developers-handbook/introduction/_index.adoc
+++ b/documentation/content/en/books/developers-handbook/introduction/_index.adoc
@@ -37,9 +37,15 @@ toc::[]
[[introduction-devel]]
== Developing on FreeBSD
-So here we are. System all installed and you are ready to start programming. But where to start? What does FreeBSD provide? What can it do for me, as a programmer?
+So here we are.
+System all installed and you are ready to start programming.
+But where to start? What does FreeBSD provide? What can it do for me, as a programmer?
-These are some questions which this chapter tries to answer. Of course, programming has different levels of proficiency like any other trade. For some it is a hobby, for others it is their profession. The information in this chapter might be aimed toward the beginning programmer; indeed, it could serve useful for the programmer unfamiliar with the FreeBSD platform.
+These are some questions which this chapter tries to answer.
+Of course, programming has different levels of proficiency like any other trade.
+For some it is a hobby, for others it is their profession.
+The information in this chapter might be aimed toward the beginning programmer;
+indeed, it could serve useful for the programmer unfamiliar with the FreeBSD platform.
[[introduction-bsdvision]]
== The BSD Vision
@@ -64,7 +70,8 @@ From Scheifler & Gettys: "X Window System"
[[introduction-layout]]
== The Layout of /usr/src
-The complete source code to FreeBSD is available from our public repository. The source code is normally installed in [.filename]#/usr/src# which contains the following subdirectories:
+The complete source code to FreeBSD is available from our public repository.
+The source code is normally installed in [.filename]#/usr/src# which contains the following subdirectories:
[.informaltable]
[cols="1,1", frame="none", options="header"]
diff --git a/documentation/content/en/books/developers-handbook/ipv6/_index.adoc b/documentation/content/en/books/developers-handbook/ipv6/_index.adoc
index 6546bec79c..9596e12e78 100644
--- a/documentation/content/en/books/developers-handbook/ipv6/_index.adoc
+++ b/documentation/content/en/books/developers-handbook/ipv6/_index.adoc
@@ -36,18 +36,22 @@ toc::[]
[[ipv6-implementation]]
== IPv6/IPsec Implementation
-This section should explain IPv6 and IPsec related implementation internals. These functionalities are derived from http://www.kame.net/[KAME project]
+This section should explain IPv6 and IPsec related implementation internals.
+These functionalities are derived from http://www.kame.net/[KAME project]
[[ipv6details]]
=== IPv6
==== Conformance
-The IPv6 related functions conforms, or tries to conform to the latest set of IPv6 specifications. For future reference we list some of the relevant documents below (_NOTE_: this is not a complete list - this is too hard to maintain...).
+The IPv6 related functions conforms, or tries to conform to the latest set of IPv6 specifications.
+For future reference we list some of the relevant documents below (_NOTE_: this is not a complete list - this is too hard to maintain...).
For details please refer to specific chapter in the document, RFCs, manual pages, or comments in the source code.
-Conformance tests have been performed on the KAME STABLE kit at TAHI project. Results can be viewed at http://www.tahi.org/report/KAME/[http://www.tahi.org/report/KAME/]. We also attended University of New Hampshire IOL tests (http://www.iol.unh.edu/[http://www.iol.unh.edu/]) in the past, with our past snapshots.
+Conformance tests have been performed on the KAME STABLE kit at TAHI project.
+Results can be viewed at http://www.tahi.org/report/KAME/[http://www.tahi.org/report/KAME/].
+We also attended University of New Hampshire IOL tests (http://www.iol.unh.edu/[http://www.iol.unh.edu/]) in the past, with our past snapshots.
* RFC1639: FTP Operation Over Big Address Records (FOOBAR)
@@ -140,55 +144,91 @@ Conformance tests have been performed on the KAME STABLE kit at TAHI project. Re
[[neighbor-discovery]]
==== Neighbor Discovery
-Neighbor Discovery is fairly stable. Currently Address Resolution, Duplicated Address Detection, and Neighbor Unreachability Detection are supported. In the near future we will be adding Proxy Neighbor Advertisement support in the kernel and Unsolicited Neighbor Advertisement transmission command as admin tool.
+Neighbor Discovery is fairly stable.
+Currently Address Resolution, Duplicated Address Detection, and Neighbor Unreachability Detection are supported.
+In the near future we will be adding Proxy Neighbor Advertisement support in the kernel and Unsolicited Neighbor Advertisement transmission command as admin tool.
-If DAD fails, the address will be marked "duplicated" and message will be generated to syslog (and usually to console). The "duplicated" mark can be checked with man:ifconfig[8]. It is administrators' responsibility to check for and recover from DAD failures. The behavior should be improved in the near future.
+If DAD fails, the address will be marked "duplicated" and message will be generated to syslog (and usually to console).
+The "duplicated" mark can be checked with man:ifconfig[8].
+It is administrators' responsibility to check for and recover from DAD failures.
+The behavior should be improved in the near future.
-Some of the network driver loops multicast packets back to itself, even if instructed not to do so (especially in promiscuous mode). In such cases DAD may fail, because DAD engine sees inbound NS packet (actually from the node itself) and considers it as a sign of duplicate. You may want to look at #if condition marked "heuristics" in sys/netinet6/nd6_nbr.c:nd6_dad_timer() as workaround (note that the code fragment in "heuristics" section is not spec conformant).
+Some of the network driver loops multicast packets back to itself, even if instructed not to do so (especially in promiscuous mode).
+In such cases DAD may fail, because DAD engine sees inbound NS packet (actually from the node itself) and considers it as a sign of duplicate.
+You may want to look at #if condition marked "heuristics" in sys/netinet6/nd6_nbr.c:nd6_dad_timer() as workaround (note that the code fragment in "heuristics" section is not spec conformant).
Neighbor Discovery specification (RFC2461) does not talk about neighbor cache handling in the following cases:
. when there was no neighbor cache entry, node received unsolicited RS/NS/NA/redirect packet without link-layer address
. neighbor cache handling on medium without link-layer address (we need a neighbor cache entry for IsRouter bit)
-For first case, we implemented workaround based on discussions on IETF ipngwg mailing list. For more details, see the comments in the source code and email thread started from (IPng 7155), dated Feb 6 1999.
+For first case, we implemented workaround based on discussions on IETF ipngwg mailing list.
+For more details, see the comments in the source code and email thread started from (IPng 7155), dated Feb 6 1999.
-IPv6 on-link determination rule (RFC2461) is quite different from assumptions in BSD network code. At this moment, no on-link determination rule is supported where default router list is empty (RFC2461, section 5.2, last sentence in 2nd paragraph - note that the spec misuse the word "host" and "node" in several places in the section).
+IPv6 on-link determination rule (RFC2461) is quite different from assumptions in BSD network code.
+At this moment, no on-link determination rule is supported where default router list is empty (RFC2461, section 5.2, last sentence in 2nd paragraph - note that the spec misuse the word "host" and "node" in several places in the section).
-To avoid possible DoS attacks and infinite loops, only 10 options on ND packet is accepted now. Therefore, if you have 20 prefix options attached to RA, only the first 10 prefixes will be recognized. If this troubles you, please ask it on FREEBSD-CURRENT mailing list and/or modify nd6_maxndopt in [.filename]#sys/netinet6/nd6.c#. If there are high demands we may provide sysctl knob for the variable.
+To avoid possible DoS attacks and infinite loops, only 10 options on ND packet is accepted now.
+Therefore, if you have 20 prefix options attached to RA, only the first 10 prefixes will be recognized.
+If this troubles you, please ask it on FREEBSD-CURRENT mailing list and/or modify nd6_maxndopt in [.filename]#sys/netinet6/nd6.c#.
+If there are high demands we may provide sysctl knob for the variable.
[[ipv6-scope-index]]
==== Scope Index
-IPv6 uses scoped addresses. Therefore, it is very important to specify scope index (interface index for link-local address, or site index for site-local address) with an IPv6 address. Without scope index, scoped IPv6 address is ambiguous to the kernel, and kernel will not be able to determine the outbound interface for a packet.
+IPv6 uses scoped addresses.
+Therefore, it is very important to specify scope index (interface index for link-local address, or site index for site-local address) with an IPv6 address.
+Without scope index, scoped IPv6 address is ambiguous to the kernel, and kernel will not be able to determine the outbound interface for a packet.
-Ordinary userland applications should use advanced API (RFC2292) to specify scope index, or interface index. For similar purpose, sin6_scope_id member in sockaddr_in6 structure is defined in RFC2553. However, the semantics for sin6_scope_id is rather vague. If you care about portability of your application, we suggest you to use advanced API rather than sin6_scope_id.
+Ordinary userland applications should use advanced API (RFC2292) to specify scope index, or interface index.
+For similar purpose, sin6_scope_id member in sockaddr_in6 structure is defined in RFC2553.
+However, the semantics for sin6_scope_id is rather vague.
+If you care about portability of your application, we suggest you to use advanced API rather than sin6_scope_id.
-In the kernel, an interface index for link-local scoped address is embedded into 2nd 16bit-word (3rd and 4th byte) in IPv6 address. For example, you may see something like:
+In the kernel, an interface index for link-local scoped address is embedded into 2nd 16bit-word (3rd and 4th byte) in IPv6 address.
+For example, you may see something like:
[source,bash]
....
fe80:1::200:f8ff:fe01:6317
....
-in the routing table and interface address structure (struct in6_ifaddr). The address above is a link-local unicast address which belongs to a network interface whose interface identifier is 1. The embedded index enables us to identify IPv6 link local addresses over multiple interfaces effectively and with only a little code change.
+in the routing table and interface address structure (struct in6_ifaddr).
+The address above is a link-local unicast address which belongs to a network interface whose interface identifier is 1.
+The embedded index enables us to identify IPv6 link local addresses over multiple interfaces effectively and with only a little code change.
-Routing daemons and configuration programs, like man:route6d[8] and man:ifconfig[8], will need to manipulate the "embedded" scope index. These programs use routing sockets and ioctls (like SIOCGIFADDR_IN6) and the kernel API will return IPv6 addresses with 2nd 16bit-word filled in. The APIs are for manipulating kernel internal structure. Programs that use these APIs have to be prepared about differences in kernels anyway.
+Routing daemons and configuration programs, like man:route6d[8] and man:ifconfig[8], will need to manipulate the "embedded" scope index.
+These programs use routing sockets and ioctls (like SIOCGIFADDR_IN6) and the kernel API will return IPv6 addresses with 2nd 16bit-word filled in.
+The APIs are for manipulating kernel internal structure.
+Programs that use these APIs have to be prepared about differences in kernels anyway.
-When you specify scoped address to the command line, NEVER write the embedded form (such as ff02:1::1 or fe80:2::fedc). This is not supposed to work. Always use standard form, like ff02::1 or fe80::fedc, with command line option for specifying interface (like `ping6 -I ne0 ff02::1`). In general, if a command does not have command line option to specify outgoing interface, that command is not ready to accept scoped address. This may seem to be opposite from IPv6's premise to support "dentist office" situation. We believe that specifications need some improvements for this.
+When you specify scoped address to the command line, NEVER write the embedded form (such as ff02:1::1 or fe80:2::fedc).
+This is not supposed to work.
+Always use standard form, like ff02::1 or fe80::fedc, with command line option for specifying interface (like `ping6 -I ne0 ff02::1`).
+In general, if a command does not have command line option to specify outgoing interface, that command is not ready to accept scoped address.
+This may seem to be opposite from IPv6's premise to support "dentist office" situation.
+We believe that specifications need some improvements for this.
-Some of the userland tools support extended numeric IPv6 syntax, as documented in [.filename]#draft-ietf-ipngwg-scopedaddr-format-00.txt#. You can specify outgoing link, by using name of the outgoing interface like "fe80::1%ne0". This way you will be able to specify link-local scoped address without much trouble.
+Some of the userland tools support extended numeric IPv6 syntax, as documented in [.filename]#draft-ietf-ipngwg-scopedaddr-format-00.txt#.
+You can specify outgoing link, by using name of the outgoing interface like "fe80::1%ne0".
+This way you will be able to specify link-local scoped address without much trouble.
-To use this extension in your program, you will need to use man:getaddrinfo[3], and man:getnameinfo[3] with NI_WITHSCOPEID. The implementation currently assumes 1-to-1 relationship between a link and an interface, which is stronger than what specs say.
+To use this extension in your program, you will need to use man:getaddrinfo[3], and man:getnameinfo[3] with NI_WITHSCOPEID.
+The implementation currently assumes 1-to-1 relationship between a link and an interface, which is stronger than what specs say.
[[ipv6-pnp]]
==== Plug and Play
-Most of the IPv6 stateless address autoconfiguration is implemented in the kernel. Neighbor Discovery functions are implemented in the kernel as a whole. Router Advertisement (RA) input for hosts is implemented in the kernel. Router Solicitation (RS) output for endhosts, RS input for routers, and RA output for routers are implemented in the userland.
+Most of the IPv6 stateless address autoconfiguration is implemented in the kernel.
+Neighbor Discovery functions are implemented in the kernel as a whole.
+Router Advertisement (RA) input for hosts is implemented in the kernel.
+Router Solicitation (RS) output for endhosts, RS input for routers, and RA output for routers are implemented in the userland.
===== Assignment of link-local, and special addresses
-IPv6 link-local address is generated from IEEE802 address (Ethernet MAC address). Each of interface is assigned an IPv6 link-local address automatically, when the interface becomes up (IFF_UP). Also, direct route for the link-local address is added to routing table.
+IPv6 link-local address is generated from IEEE802 address (Ethernet MAC address).
+Each of interface is assigned an IPv6 link-local address automatically, when the interface becomes up (IFF_UP).
+Also, direct route for the link-local address is added to routing table.
Here is an output of netstat command:
@@ -200,17 +240,30 @@ fe80:1::%ed0/64 link#1 UC ed0
fe80:2::%ep0/64 link#2 UC ep0
....
-Interfaces that has no IEEE802 address (pseudo interfaces like tunnel interfaces, or ppp interfaces) will borrow IEEE802 address from other interfaces, such as Ethernet interfaces, whenever possible. If there is no IEEE802 hardware attached, a last resort pseudo-random value, MD5(hostname), will be used as source of link-local address. If it is not suitable for your usage, you will need to configure the link-local address manually.
+Interfaces that has no IEEE802 address (pseudo interfaces like tunnel interfaces, or ppp interfaces) will borrow IEEE802 address from other interfaces, such as Ethernet interfaces, whenever possible.
+If there is no IEEE802 hardware attached, a last resort pseudo-random value, MD5(hostname), will be used as source of link-local address.
+If it is not suitable for your usage, you will need to configure the link-local address manually.
-If an interface is not capable of handling IPv6 (such as lack of multicast support), link-local address will not be assigned to that interface. See section 2 for details.
+If an interface is not capable of handling IPv6 (such as lack of multicast support), link-local address will not be assigned to that interface.
+See section 2 for details.
-Each interface joins the solicited multicast address and the link-local all-nodes multicast addresses (e.g., fe80::1:ff01:6317 and ff02::1, respectively, on the link the interface is attached). In addition to a link-local address, the loopback address (::1) will be assigned to the loopback interface. Also, ::1/128 and ff01::/32 are automatically added to routing table, and loopback interface joins node-local multicast group ff01::1.
+Each interface joins the solicited multicast address and the link-local all-nodes multicast addresses (e.g., fe80::1:ff01:6317 and ff02::1, respectively, on the link the interface is attached).
+In addition to a link-local address, the loopback address (::1) will be assigned to the loopback interface.
+Also, ::1/128 and ff01::/32 are automatically added to routing table, and loopback interface joins node-local multicast group ff01::1.
===== Stateless address autoconfiguration on Hosts
-In IPv6 specification, nodes are separated into two categories: _routers_ and _hosts_. Routers forward packets addressed to others, hosts does not forward the packets. net.inet6.ip6.forwarding defines whether this node is router or host (router if it is 1, host if it is 0).
+In IPv6 specification, nodes are separated into two categories: _routers_ and _hosts_.
+Routers forward packets addressed to others, hosts does not forward the packets. net.inet6.ip6.forwarding defines whether this node is router or host (router if it is 1, host if it is 0).
-When a host hears Router Advertisement from the router, a host may autoconfigure itself by stateless address autoconfiguration. This behavior can be controlled by net.inet6.ip6.accept_rtadv (host autoconfigures itself if it is set to 1). By autoconfiguration, network address prefix for the receiving interface (usually global address prefix) is added. Default route is also configured. Routers periodically generate Router Advertisement packets. To request an adjacent router to generate RA packet, a host can transmit Router Solicitation. To generate a RS packet at any time, use the _rtsol_ command. man:rtsold[8] daemon is also available. man:rtsold[8] generates Router Solicitation whenever necessary, and it works great for nomadic usage (notebooks/laptops). If one wishes to ignore Router Advertisements, use sysctl to set net.inet6.ip6.accept_rtadv to 0.
+When a host hears Router Advertisement from the router, a host may autoconfigure itself by stateless address autoconfiguration.
+This behavior can be controlled by net.inet6.ip6.accept_rtadv (host autoconfigures itself if it is set to 1).
+By autoconfiguration, network address prefix for the receiving interface (usually global address prefix) is added.
+Default route is also configured. Routers periodically generate Router Advertisement packets.
+To request an adjacent router to generate RA packet, a host can transmit Router Solicitation.
+To generate a RS packet at any time, use the _rtsol_ command. man:rtsold[8] daemon is also available.
+man:rtsold[8] generates Router Solicitation whenever necessary, and it works great for nomadic usage (notebooks/laptops).
+If one wishes to ignore Router Advertisements, use sysctl to set net.inet6.ip6.accept_rtadv to 0.
To generate Router Advertisement from a router, use the man:rtadvd[8] daemon.
@@ -219,7 +272,8 @@ Note that, IPv6 specification assumes the following items, and nonconforming cas
* Only hosts will listen to router advertisements
* Hosts have single network interface (except loopback)
-Therefore, this is unwise to enable net.inet6.ip6.accept_rtadv on routers, or multi-interface host. A misconfigured node can behave strange (nonconforming configuration allowed for those who would like to do some experiments).
+Therefore, this is unwise to enable net.inet6.ip6.accept_rtadv on routers, or multi-interface host.
+A misconfigured node can behave strange (nonconforming configuration allowed for those who would like to do some experiments).
To summarize the sysctl knob:
@@ -238,30 +292,39 @@ To summarize the sysctl knob:
(out-of-scope of spec)
....
-RFC2462 has validation rule against incoming RA prefix information option, in 5.5.3 (e). This is to protect hosts from malicious (or misconfigured) routers that advertise very short prefix lifetime. There was an update from Jim Bound to ipngwg mailing list (look for "(ipng 6712)" in the archive) and it is implemented Jim's update.
+RFC2462 has validation rule against incoming RA prefix information option, in 5.5.3 (e).
+This is to protect hosts from malicious (or misconfigured) routers that advertise very short prefix lifetime.
+There was an update from Jim Bound to ipngwg mailing list (look for "(ipng 6712)" in the archive) and it is implemented Jim's update.
See <<neighbor-discovery,23.5.1.2>> in the document for relationship between DAD and autoconfiguration.
[[gif]]
==== Generic Tunnel Interface
-GIF (Generic InterFace) is a pseudo interface for configured tunnel. Details are described in man:gif[4]. Currently
+GIF (Generic InterFace) is a pseudo interface for configured tunnel.
+Details are described in man:gif[4]. Currently
* v6 in v6
* v6 in v4
* v4 in v6
* v4 in v4
-are available. Use man:gifconfig[8] to assign physical (outer) source and destination address to gif interfaces. Configuration that uses same address family for inner and outer IP header (v4 in v4, or v6 in v6) is dangerous. It is very easy to configure interfaces and routing tables to perform infinite level of tunneling. _Please be warned_.
+are available. Use man:gifconfig[8] to assign physical (outer) source and destination address to gif interfaces.
+Configuration that uses same address family for inner and outer IP header (v4 in v4, or v6 in v6) is dangerous.
+It is very easy to configure interfaces and routing tables to perform infinite level of tunneling.
+_Please be warned_.
-gif can be configured to be ECN-friendly. See <<ipsec-ecn,23.5.4.5>> for ECN-friendliness of tunnels, and man:gif[4] for how to configure.
+gif can be configured to be ECN-friendly.
+See <<ipsec-ecn,23.5.4.5>> for ECN-friendliness of tunnels, and man:gif[4] for how to configure.
-If you would like to configure an IPv4-in-IPv6 tunnel with gif interface, read man:gif[4] carefully. You will need to remove IPv6 link-local address automatically assigned to the gif interface.
+If you would like to configure an IPv4-in-IPv6 tunnel with gif interface, read man:gif[4] carefully.
+You will need to remove IPv6 link-local address automatically assigned to the gif interface.
[[ipv6-sas]]
==== Source Address Selection
-Current source selection rule is scope oriented (there are some exceptions - see below). For a given destination, a source IPv6 address is selected by the following rule:
+Current source selection rule is scope oriented (there are some exceptions - see below).
+For a given destination, a source IPv6 address is selected by the following rule:
. If the source address is explicitly specified by the user (e.g., via the advanced API), the specified address is used.
. If there is an address assigned to the outgoing interface (which is usually determined by looking up the routing table) that has the same scope as the destination address, the address is used.
@@ -271,16 +334,29 @@ This is the most typical case.
. If there is no address that satisfies the above condition, and destination address is site local scope, choose a site local address assigned to one of the interfaces on the sending node.
. If there is no address that satisfies the above condition, choose the address associated with the routing table entry for the destination. This is the last resort, which may cause scope violation.
-For instance, ::1 is selected for ff01::1, fe80:1::200:f8ff:fe01:6317 for fe80:1::2a0:24ff:feab:839b (note that embedded interface index - described in <<ipv6-scope-index,23.5.1.3>> - helps us choose the right source address. Those embedded indices will not be on the wire). If the outgoing interface has multiple address for the scope, a source is selected longest match basis (rule 3). Suppose 2001:0DB8:808:1:200:f8ff:fe01:6317 and 2001:0DB8:9:124:200:f8ff:fe01:6317 are given to the outgoing interface. 2001:0DB8:808:1:200:f8ff:fe01:6317 is chosen as the source for the destination 2001:0DB8:800::1.
+For instance, ::1 is selected for ff01::1, fe80:1::200:f8ff:fe01:6317 for fe80:1::2a0:24ff:feab:839b (note that embedded interface index - described in <<ipv6-scope-index,23.5.1.3>> - helps us choose the right source address.
+Those embedded indices will not be on the wire).
+If the outgoing interface has multiple address for the scope, a source is selected longest match basis (rule 3).
+Suppose 2001:0DB8:808:1:200:f8ff:fe01:6317 and 2001:0DB8:9:124:200:f8ff:fe01:6317 are given to the outgoing interface. 2001:0DB8:808:1:200:f8ff:fe01:6317 is chosen as the source for the destination 2001:0DB8:800::1.
-Note that the above rule is not documented in the IPv6 spec. It is considered "up to implementation" item. There are some cases where we do not use the above rule. One example is connected TCP session, and we use the address kept in tcb as the source. Another example is source address for Neighbor Advertisement. Under the spec (RFC2461 7.2.2) NA's source should be the target address of the corresponding NS's target. In this case we follow the spec rather than the above longest-match rule.
+Note that the above rule is not documented in the IPv6 spec. It is considered "up to implementation" item.
+There are some cases where we do not use the above rule.
+One example is connected TCP session, and we use the address kept in tcb as the source.
+Another example is source address for Neighbor Advertisement.
+Under the spec (RFC2461 7.2.2) NA's source should be the target address of the corresponding NS's target.
+In this case we follow the spec rather than the above longest-match rule.
-For new connections (when rule 1 does not apply), deprecated addresses (addresses with preferred lifetime = 0) will not be chosen as source address if other choices are available. If no other choices are available, deprecated address will be used as a last resort. If there are multiple choice of deprecated addresses, the above scope rule will be used to choose from those deprecated addresses. If you would like to prohibit the use of deprecated address for some reason, configure net.inet6.ip6.use_deprecated to 0. The issue related to deprecated address is described in RFC2462 5.5.4 (NOTE: there is some debate underway in IETF ipngwg on how to use "deprecated" address).
+For new connections (when rule 1 does not apply), deprecated addresses (addresses with preferred lifetime = 0) will not be chosen as source address if other choices are available.
+If no other choices are available, deprecated address will be used as a last resort.
+If there are multiple choice of deprecated addresses, the above scope rule will be used to choose from those deprecated addresses.
+If you would like to prohibit the use of deprecated address for some reason, configure net.inet6.ip6.use_deprecated to 0.
+The issue related to deprecated address is described in RFC2462 5.5.4 (NOTE: there is some debate underway in IETF ipngwg on how to use "deprecated" address).
[[ipv6-jumbo]]
==== Jumbo Payload
-The Jumbo Payload hop-by-hop option is implemented and can be used to send IPv6 packets with payloads longer than 65,535 octets. But currently no physical interface whose MTU is more than 65,535 is supported, so such payloads can be seen only on the loopback interface (i.e., lo0).
+The Jumbo Payload hop-by-hop option is implemented and can be used to send IPv6 packets with payloads longer than 65,535 octets.
+But currently no physical interface whose MTU is more than 65,535 is supported, so such payloads can be seen only on the loopback interface (i.e., lo0).
If you want to try jumbo payloads, you first have to reconfigure the kernel so that the MTU of the loopback interface is more than 65,535 bytes; add the following to the kernel configuration file:
@@ -288,16 +364,22 @@ If you want to try jumbo payloads, you first have to reconfigure the kernel so t
and recompile the new kernel.
-Then you can test jumbo payloads by the man:ping6[8] command with -b and -s options. The -b option must be specified to enlarge the size of the socket buffer and the -s option specifies the length of the packet, which should be more than 65,535. For example, type as follows:
+Then you can test jumbo payloads by the man:ping6[8] command with -b and -s options.
+The -b option must be specified to enlarge the size of the socket buffer and the -s option specifies the length of the packet, which should be more than 65,535.
+For example, type as follows:
[source,bash]
....
% ping6 -b 70000 -s 68000 ::1
....
-The IPv6 specification requires that the Jumbo Payload option must not be used in a packet that carries a fragment header. If this condition is broken, an ICMPv6 Parameter Problem message must be sent to the sender. specification is followed, but you cannot usually see an ICMPv6 error caused by this requirement.
+The IPv6 specification requires that the Jumbo Payload option must not be used in a packet that carries a fragment header.
+If this condition is broken, an ICMPv6 Parameter Problem message must be sent to the sender.
+specification is followed, but you cannot usually see an ICMPv6 error caused by this requirement.
-When an IPv6 packet is received, the frame length is checked and compared to the length specified in the payload length field of the IPv6 header or in the value of the Jumbo Payload option, if any. If the former is shorter than the latter, the packet is discarded and statistics are incremented. You can see the statistics as output of man:netstat[8] command with `-s -p ip6' option:
+When an IPv6 packet is received, the frame length is checked and compared to the length specified in the payload length field of the IPv6 header or in the value of the Jumbo Payload option, if any.
+If the former is shorter than the latter, the packet is discarded and statistics are incremented.
+You can see the statistics as output of man:netstat[8] command with `-s -p ip6' option:
[source,bash]
....
@@ -307,45 +389,72 @@ When an IPv6 packet is received, the frame length is checked and compared to the
1 with data size < data length
....
-So, kernel does not send an ICMPv6 error unless the erroneous packet is an actual Jumbo Payload, that is, its packet size is more than 65,535 bytes. As described above, currently no physical interface with such a huge MTU is supported, so it rarely returns an ICMPv6 error.
+So, kernel does not send an ICMPv6 error unless the erroneous packet is an actual Jumbo Payload, that is, its packet size is more than 65,535 bytes.
+As described above, currently no physical interface with such a huge MTU is supported, so it rarely returns an ICMPv6 error.
-TCP/UDP over jumbogram is not supported at this moment. This is because we have no medium (other than loopback) to test this. Contact us if you need this.
+TCP/UDP over jumbogram is not supported at this moment.
+This is because we have no medium (other than loopback) to test this. Contact us if you need this.
-IPsec does not work on jumbograms. This is due to some specification twists in supporting AH with jumbograms (AH header size influences payload length, and this makes it real hard to authenticate inbound packet with jumbo payload option as well as AH).
+IPsec does not work on jumbograms.
+This is due to some specification twists in supporting AH with jumbograms (AH header size influences payload length, and this makes it real hard to authenticate inbound packet with jumbo payload option as well as AH).
-There are fundamental issues in *BSD support for jumbograms. We would like to address those, but we need more time to finalize these. To name a few:
+There are fundamental issues in *BSD support for jumbograms.
+We would like to address those, but we need more time to finalize these.
+To name a few:
+
+* mbuf pkthdr.len field is typed as "int" in 4.4BSD, so it will not hold jumbogram with len > 2G on 32bit architecture CPUs.
+If we would like to support jumbogram properly, the field must be expanded to hold 4G + IPv6 header + link-layer header.
+Therefore, it must be expanded to at least int64_t (u_int32_t is NOT enough).
-* mbuf pkthdr.len field is typed as "int" in 4.4BSD, so it will not hold jumbogram with len > 2G on 32bit architecture CPUs. If we would like to support jumbogram properly, the field must be expanded to hold 4G + IPv6 header + link-layer header. Therefore, it must be expanded to at least int64_t (u_int32_t is NOT enough).
* We mistakingly use "int" to hold packet length in many places. We need to convert them into larger integral type. It needs a great care, as we may experience overflow during packet length computation.
* We mistakingly check for ip6_plen field of IPv6 header for packet payload length in various places. We should be checking mbuf pkthdr.len instead. ip6_input() will perform sanity check on jumbo payload option on input, and we can safely use mbuf pkthdr.len afterwards.
* TCP code needs a careful update in bunch of places, of course.
==== Loop Prevention in Header Processing
-IPv6 specification allows arbitrary number of extension headers to be placed onto packets. If we implement IPv6 packet processing code in the way BSD IPv4 code is implemented, kernel stack may overflow due to long function call chain. sys/netinet6 code is carefully designed to avoid kernel stack overflow, so sys/netinet6 code defines its own protocol switch structure, as "struct ip6protosw" (see [.filename]#netinet6/ip6protosw.h#). There is no such update to IPv4 part (sys/netinet) for compatibility, but small change is added to its pr_input() prototype. So "struct ipprotosw" is also defined. As a result, if you receive IPsec-over-IPv4 packet with massive number of IPsec headers, kernel stack may blow up. IPsec-over-IPv6 is okay. (Of-course, for those all IPsec headers to be processed, each such IPsec header must pass each IPsec check. So an anonymous attacker will not be able to do such an attack.)
+IPv6 specification allows arbitrary number of extension headers to be placed onto packets.
+If we implement IPv6 packet processing code in the way BSD IPv4 code is implemented, kernel stack may overflow due to long function call chain.
+sys/netinet6 code is carefully designed to avoid kernel stack overflow, so sys/netinet6 code defines its own protocol switch structure, as "struct ip6protosw" (see [.filename]#netinet6/ip6protosw.h#).
+There is no such update to IPv4 part (sys/netinet) for compatibility, but small change is added to its pr_input() prototype.
+So "struct ipprotosw" is also defined.
+As a result, if you receive IPsec-over-IPv4 packet with massive number of IPsec headers, kernel stack may blow up.
+IPsec-over-IPv6 is okay.
+(Of-course, for those all IPsec headers to be processed, each such IPsec header must pass each IPsec check.
+So an anonymous attacker will not be able to do such an attack.)
[[icmpv6]]
==== ICMPv6
-After RFC2463 was published, IETF ipngwg has decided to disallow ICMPv6 error packet against ICMPv6 redirect, to prevent ICMPv6 storm on a network medium. This is already implemented into the kernel.
+After RFC2463 was published, IETF ipngwg has decided to disallow ICMPv6 error packet against ICMPv6 redirect, to prevent ICMPv6 storm on a network medium.
+This is already implemented into the kernel.
==== Applications
For userland programming, we support IPv6 socket API as specified in RFC2553, RFC2292 and upcoming Internet drafts.
-TCP/UDP over IPv6 is available and quite stable. You can enjoy man:telnet[1], man:ftp[1], man:rlogin[1], man:rsh[1], man:ssh[1], etc. These applications are protocol independent. That is, they automatically chooses IPv4 or IPv6 according to DNS.
+TCP/UDP over IPv6 is available and quite stable.
+You can enjoy man:telnet[1], man:ftp[1], man:rlogin[1], man:rsh[1], man:ssh[1], etc.
+These applications are protocol independent.
+That is, they automatically chooses IPv4 or IPv6 according to DNS.
==== Kernel Internals
While ip_forward() calls ip_output(), ip6_forward() directly calls if_output() since routers must not divide IPv6 packets into fragments.
-ICMPv6 should contain the original packet as long as possible up to 1280. UDP6/IP6 port unreach, for instance, should contain all extension headers and the *unchanged* UDP6 and IP6 headers. So, all IP6 functions except TCP never convert network byte order into host byte order, to save the original packet.
+ICMPv6 should contain the original packet as long as possible up to 1280.
+UDP6/IP6 port unreach, for instance, should contain all extension headers and the *unchanged* UDP6 and IP6 headers.
+So, all IP6 functions except TCP never convert network byte order into host byte order, to save the original packet.
-tcp_input(), udp6_input() and icmp6_input() can not assume that IP6 header is preceding the transport headers due to extension headers. So, in6_cksum() was implemented to handle packets whose IP6 header and transport header is not continuous. TCP/IP6 nor UDP6/IP6 header structures do not exist for checksum calculation.
+tcp_input(), udp6_input() and icmp6_input() can not assume that IP6 header is preceding the transport headers due to extension headers.
+So, in6_cksum() was implemented to handle packets whose IP6 header and transport header is not continuous.
+TCP/IP6 nor UDP6/IP6 header structures do not exist for checksum calculation.
-To process IP6 header, extension headers and transport headers easily, network drivers are now required to store packets in one internal mbuf or one or more external mbufs. A typical old driver prepares two internal mbufs for 96 - 204 bytes data, however, now such packet data is stored in one external mbuf.
+To process IP6 header, extension headers and transport headers easily, network drivers are now required to store packets in one internal mbuf or one or more external mbufs.
+A typical old driver prepares two internal mbufs for 96 - 204 bytes data, however, now such packet data is stored in one external mbuf.
-`netstat -s -p ip6` tells you whether or not your driver conforms such requirement. In the following example, "cce0" violates the requirement. (For more information, refer to Section 2.)
+`netstat -s -p ip6` tells you whether or not your driver conforms such requirement.
+In the following example, "cce0" violates the requirement.
+(For more information, refer to Section 2.)
[source,bash]
....
@@ -358,19 +467,23 @@ Mbuf statistics:
0 two or more ext mbuf
....
-Each input function calls IP6_EXTHDR_CHECK in the beginning to check if the region between IP6 and its header is continuous. IP6_EXTHDR_CHECK calls m_pullup() only if the mbuf has M_LOOP flag, that is, the packet comes from the loopback interface. m_pullup() is never called for packets coming from physical network interfaces.
+Each input function calls IP6_EXTHDR_CHECK in the beginning to check if the region between IP6 and its header is continuous.
+IP6_EXTHDR_CHECK calls m_pullup() only if the mbuf has M_LOOP flag, that is, the packet comes from the loopback interface.
+m_pullup() is never called for packets coming from physical network interfaces.
Both IP and IP6 reassemble functions never call m_pullup().
[[ipv6-wildcard-socket]]
==== IPv4 Mapped Address and IPv6 Wildcard Socket
-RFC2553 describes IPv4 mapped address (3.7) and special behavior of IPv6 wildcard bind socket (3.8). The spec allows you to:
+RFC2553 describes IPv4 mapped address (3.7) and special behavior of IPv6 wildcard bind socket (3.8).
+The spec allows you to:
* Accept IPv4 connections by AF_INET6 wildcard bind socket.
* Transmit IPv4 packet over AF_INET6 socket by using special form of the address like ::ffff:10.1.1.1.
-but the spec itself is very complicated and does not specify how the socket layer should behave. Here we call the former one "listening side" and the latter one "initiating side", for reference purposes.
+but the spec itself is very complicated and does not specify how the socket layer should behave.
+Here we call the former one "listening side" and the latter one "initiating side", for reference purposes.
You can perform wildcard bind on both of the address families, on the same port.
@@ -390,15 +503,29 @@ The following sections will give you more details, and how you can configure the
Comments on listening side:
-It looks that RFC2553 talks too little on wildcard bind issue, especially on the port space issue, failure mode and relationship between AF_INET/INET6 wildcard bind. There can be several separate interpretation for this RFC which conform to it but behaves differently. So, to implement portable application you should assume nothing about the behavior in the kernel. Using man:getaddrinfo[3] is the safest way. Port number space and wildcard bind issues were discussed in detail on ipv6imp mailing list, in mid March 1999 and it looks that there is no concrete consensus (means, up to implementers). You may want to check the mailing list archives.
+It looks that RFC2553 talks too little on wildcard bind issue, especially on the port space issue, failure mode and relationship between AF_INET/INET6 wildcard bind.
+There can be several separate interpretation for this RFC which conform to it but behaves differently.
+So, to implement portable application you should assume nothing about the behavior in the kernel.
+Using man:getaddrinfo[3] is the safest way.
+Port number space and wildcard bind issues were discussed in detail on ipv6imp mailing list, in mid March 1999 and it looks that there is no concrete consensus (means, up to implementers).
+You may want to check the mailing list archives.
If a server application would like to accept IPv4 and IPv6 connections, there will be two alternatives.
-One is using AF_INET and AF_INET6 socket (you will need two sockets). Use man:getaddrinfo[3] with AI_PASSIVE into ai_flags, and man:socket[2] and man:bind[2] to all the addresses returned. By opening multiple sockets, you can accept connections onto the socket with proper address family. IPv4 connections will be accepted by AF_INET socket, and IPv6 connections will be accepted by AF_INET6 socket.
+One is using AF_INET and AF_INET6 socket (you will need two sockets).
+Use man:getaddrinfo[3] with AI_PASSIVE into ai_flags, and man:socket[2] and man:bind[2] to all the addresses returned.
+By opening multiple sockets, you can accept connections onto the socket with proper address family.
+IPv4 connections will be accepted by AF_INET socket, and IPv6 connections will be accepted by AF_INET6 socket.
-Another way is using one AF_INET6 wildcard bind socket. Use man:getaddrinfo[3] with AI_PASSIVE into ai_flags and with AF_INET6 into ai_family, and set the 1st argument hostname to NULL. And man:socket[2] and man:bind[2] to the address returned. (should be IPv6 unspecified addr). You can accept either of IPv4 and IPv6 packet via this one socket.
+Another way is using one AF_INET6 wildcard bind socket.
+Use man:getaddrinfo[3] with AI_PASSIVE into ai_flags and with AF_INET6 into ai_family, and set the 1st argument hostname to NULL.
+And man:socket[2] and man:bind[2] to the address returned.
+(should be IPv6 unspecified addr).
+You can accept either of IPv4 and IPv6 packet via this one socket.
-To support only IPv6 traffic on AF_INET6 wildcard binded socket portably, always check the peer address when a connection is made toward AF_INET6 listening socket. If the address is IPv4 mapped address, you may want to reject the connection. You can check the condition by using IN6_IS_ADDR_V4MAPPED() macro.
+To support only IPv6 traffic on AF_INET6 wildcard binded socket portably, always check the peer address when a connection is made toward AF_INET6 listening socket.
+If the address is IPv4 mapped address, you may want to reject the connection.
+You can check the condition by using IN6_IS_ADDR_V4MAPPED() macro.
To resolve this issue more easily, there is system dependent man:setsockopt[2] option, IPV6_BINDV6ONLY, used like below.
@@ -421,15 +548,23 @@ Advise to application implementers: to implement a portable IPv6 application (wh
* If you would like to connect to destination, use man:getaddrinfo[3] and try all the destination returned, like man:telnet[1] does.
* Some of the IPv6 stack is shipped with buggy man:getaddrinfo[3]. Ship a minimal working version with your application and use that as last resort.
-If you would like to use AF_INET6 socket for both IPv4 and IPv6 outgoing connection, you will need to use man:getipnodebyname[3]. When you would like to update your existing application to be IPv6 aware with minimal effort, this approach might be chosen. But please note that it is a temporal solution, because man:getipnodebyname[3] itself is not recommended as it does not handle scoped IPv6 addresses at all. For IPv6 name resolution, man:getaddrinfo[3] is the preferred API. So you should rewrite your application to use man:getaddrinfo[3], when you get the time to do it.
+If you would like to use AF_INET6 socket for both IPv4 and IPv6 outgoing connection, you will need to use man:getipnodebyname[3].
+When you would like to update your existing application to be IPv6 aware with minimal effort, this approach might be chosen.
+But please note that it is a temporal solution, because man:getipnodebyname[3] itself is not recommended as it does not handle scoped IPv6 addresses at all.
+For IPv6 name resolution, man:getaddrinfo[3] is the preferred API.
+So you should rewrite your application to use man:getaddrinfo[3], when you get the time to do it.
-When writing applications that make outgoing connections, story goes much simpler if you treat AF_INET and AF_INET6 as totally separate address family. {set,get}sockopt issue goes simpler, DNS issue will be made simpler. We do not recommend you to rely upon IPv4 mapped address.
+When writing applications that make outgoing connections, story goes much simpler if you treat AF_INET and AF_INET6 as totally separate address family.
+{set,get}sockopt issue goes simpler, DNS issue will be made simpler.
+We do not recommend you to rely upon IPv4 mapped address.
===== unified tcp and inpcb code
-FreeBSD 4.x uses shared tcp code between IPv4 and IPv6 (from sys/netinet/tcp*) and separate udp4/6 code. It uses unified inpcb structure.
+FreeBSD 4.x uses shared tcp code between IPv4 and IPv6 (from sys/netinet/tcp*) and separate udp4/6 code.
+It uses unified inpcb structure.
-The platform can be configured to support IPv4 mapped address. Kernel configuration is summarized as follows:
+The platform can be configured to support IPv4 mapped address.
+Kernel configuration is summarized as follows:
* By default, AF_INET6 socket will grab IPv4 connections in certain condition, and can initiate connection to IPv4 destination embedded in IPv4 mapped IPv6 address.
* You can disable it on entire system with sysctl like below.
@@ -438,7 +573,8 @@ The platform can be configured to support IPv4 mapped address. Kernel configurat
====== Listening Side
-Each socket can be configured to support special AF_INET6 wildcard bind (enabled by default). You can disable it on each socket basis with man:setsockopt[2] like below.
+Each socket can be configured to support special AF_INET6 wildcard bind (enabled by default).
+You can disable it on each socket basis with man:setsockopt[2] like below.
[.programlisting]
....
@@ -461,7 +597,10 @@ FreeBSD 4.x supports outgoing connection to IPv4 mapped address (::ffff:10.1.1.1
==== sockaddr_storage
-When RFC2553 was about to be finalized, there was discussion on how struct sockaddr_storage members are named. One proposal is to prepend "__" to the members (like "__ss_len") as they should not be touched. The other proposal was not to prepend it (like "ss_len") as we need to touch those members directly. There was no clear consensus on it.
+When RFC2553 was about to be finalized, there was discussion on how struct sockaddr_storage members are named.
+One proposal is to prepend "__" to the members (like "__ss_len") as they should not be touched.
+The other proposal was not to prepend it (like "ss_len") as we need to touch those members directly.
+There was no clear consensus on it.
As a result, RFC2553 defines struct sockaddr_storage as follows:
@@ -489,7 +628,8 @@ In December 1999, it was agreed that RFC2553bis should pick the latter (XNET) de
Current implementation conforms to XNET definition, based on RFC2553bis discussion.
-If you look at multiple IPv6 implementations, you will be able to see both definitions. As an userland programmer, the most portable way of dealing with it is to:
+If you look at multiple IPv6 implementations, you will be able to see both definitions.
+As an userland programmer, the most portable way of dealing with it is to:
. ensure ss_family and/or ss_len are available on the platform, by using GNU autoconf,
. have -Dss_family=__ss_family to unify all occurrences (including header file) into __ss_family, or
@@ -508,9 +648,11 @@ Now following two items are required to be supported by standard drivers:
. mbuf clustering requirement. In this stable release, we changed MINCLSIZE into MHLEN+1 for all the operating systems in order to make all the drivers behave as we expect.
. multicast. If man:ifmcstat[8] yields no multicast group for a interface, that interface has to be patched.
-If any of the drivers do not support the requirements, then the drivers cannot be used for IPv6 and/or IPsec communication. If you find any problem with your card using IPv6/IPsec, then, please report it to the {freebsd-bugs}.
+If any of the drivers do not support the requirements, then the drivers cannot be used for IPv6 and/or IPsec communication.
+If you find any problem with your card using IPv6/IPsec, then, please report it to the {freebsd-bugs}.
-(NOTE: In the past we required all PCMCIA drivers to have a call to in6_ifattach(). We have no such requirement any more)
+(NOTE: In the past we required all PCMCIA drivers to have a call to in6_ifattach().
+We have no such requirement any more)
=== Translator
@@ -532,23 +674,38 @@ IPsec is mainly organized by three components.
==== Policy Management
-The kernel implements experimental policy management code. There are two way to manage security policy. One is to configure per-socket policy using man:setsockopt[2]. In this cases, policy configuration is described in man:ipsec_set_policy[3]. The other is to configure kernel packet filter-based policy using PF_KEY interface, via man:setkey[8].
+The kernel implements experimental policy management code.
+There are two way to manage security policy.
+One is to configure per-socket policy using man:setsockopt[2].
+In this cases, policy configuration is described in man:ipsec_set_policy[3].
+The other is to configure kernel packet filter-based policy using PF_KEY interface, via man:setkey[8].
The policy entry is not re-ordered with its indexes, so the order of entry when you add is very significant.
==== Key Management
-The key management code implemented in this kit (sys/netkey) is a home-brew PFKEY v2 implementation. This conforms to RFC2367.
+The key management code implemented in this kit (sys/netkey) is a home-brew PFKEY v2 implementation.
+This conforms to RFC2367.
-The home-brew IKE daemon, "racoon" is included in the kit (kame/kame/racoon). Basically you will need to run racoon as daemon, then set up a policy to require keys (like `ping -P 'out ipsec esp/transport//use'`). The kernel will contact racoon daemon as necessary to exchange keys.
+The home-brew IKE daemon, "racoon" is included in the kit (kame/kame/racoon).
+Basically you will need to run racoon as daemon, then set up a policy to require keys (like `ping -P 'out ipsec esp/transport//use'`).
+The kernel will contact racoon daemon as necessary to exchange keys.
==== AH and ESP Handling
-IPsec module is implemented as "hooks" to the standard IPv4/IPv6 processing. When sending a packet, ip{,6}_output() checks if ESP/AH processing is required by checking if a matching SPD (Security Policy Database) is found. If ESP/AH is needed, {esp,ah}{4,6}_output() will be called and mbuf will be updated accordingly. When a packet is received, {esp,ah}4_input() will be called based on protocol number, i.e., (*inetsw[proto])(). {esp,ah}4_input() will decrypt/check authenticity of the packet, and strips off daisy-chained header and padding for ESP/AH. It is safe to strip off the ESP/AH header on packet reception, since we will never use the received packet in "as is" form.
+IPsec module is implemented as "hooks" to the standard IPv4/IPv6 processing.
+When sending a packet, ip{,6}_output() checks if ESP/AH processing is required by checking if a matching SPD (Security Policy Database) is found.
+If ESP/AH is needed, {esp,ah}{4,6}_output() will be called and mbuf will be updated accordingly.
+When a packet is received, {esp,ah}4_input() will be called based on protocol number, i.e., (*inetsw[proto])().
+{esp,ah}4_input() will decrypt/check authenticity of the packet, and strips off daisy-chained header and padding for ESP/AH.
+It is safe to strip off the ESP/AH header on packet reception, since we will never use the received packet in "as is" form.
-By using ESP/AH, TCP4/6 effective data segment size will be affected by extra daisy-chained headers inserted by ESP/AH. Our code takes care of the case.
+By using ESP/AH, TCP4/6 effective data segment size will be affected by extra daisy-chained headers inserted by ESP/AH.
+Our code takes care of the case.
-Basic crypto functions can be found in directory "sys/crypto". ESP/AH transform are listed in {esp,ah}_core.c with wrapper functions. If you wish to add some algorithm, add wrapper function in {esp,ah}_core.c, and add your crypto algorithm code into sys/crypto.
+Basic crypto functions can be found in directory "sys/crypto".
+ESP/AH transform are listed in {esp,ah}_core.c with wrapper functions.
+If you wish to add some algorithm, add wrapper function in {esp,ah}_core.c, and add your crypto algorithm code into sys/crypto.
Tunnel mode is partially supported in this release, with the following restrictions:
@@ -562,7 +719,8 @@ The IPsec code in the kernel conforms (or, tries to conform) to the following st
"old IPsec" specification documented in [.filename]#rfc182[5-9].txt#
-"new IPsec" specification documented in [.filename]#rfc240[1-6].txt#, [.filename]#rfc241[01].txt#, [.filename]#rfc2451.txt# and [.filename]#draft-mcdonald-simple-ipsec-api-01.txt# (draft expired, but you can take from link:ftp://ftp.kame.net/pub/internet-drafts/[ ftp://ftp.kame.net/pub/internet-drafts/]). (NOTE: IKE specifications, [.filename]#rfc241[7-9].txt# are implemented in userland, as "racoon" IKE daemon)
+"new IPsec" specification documented in [.filename]#rfc240[1-6].txt#, [.filename]#rfc241[01].txt#, [.filename]#rfc2451.txt# and [.filename]#draft-mcdonald-simple-ipsec-api-01.txt# (draft expired, but you can take from link:ftp://ftp.kame.net/pub/internet-drafts/[ ftp://ftp.kame.net/pub/internet-drafts/]).
+(NOTE: IKE specifications, [.filename]#rfc241[7-9].txt# are implemented in userland, as "racoon" IKE daemon)
Currently supported algorithms are:
@@ -608,16 +766,21 @@ The following algorithms are NOT supported:
** HMAC MD5 with 128bit crypto checksum + 64bit replay prevention ([.filename]#rfc2085.txt#)
** keyed SHA1 with 160bit crypto checksum + 32bit padding ([.filename]#rfc1852.txt#)
-IPsec (in kernel) and IKE (in userland as "racoon") has been tested at several interoperability test events, and it is known to interoperate with many other implementations well. Also, current IPsec implementation as quite wide coverage for IPsec crypto algorithms documented in RFC (we cover algorithms without intellectual property issues only).
+IPsec (in kernel) and IKE (in userland as "racoon") has been tested at several interoperability test events, and it is known to interoperate with many other implementations well.
+Also, current IPsec implementation as quite wide coverage for IPsec crypto algorithms documented in RFC (we cover algorithms without intellectual property issues only).
[[ipsec-ecn]]
==== ECN Consideration on IPsec Tunnels
ECN-friendly IPsec tunnel is supported as described in [.filename]#draft-ipsec-ecn-00.txt#.
-Normal IPsec tunnel is described in RFC2401. On encapsulation, IPv4 TOS field (or, IPv6 traffic class field) will be copied from inner IP header to outer IP header. On decapsulation outer IP header will be simply dropped. The decapsulation rule is not compatible with ECN, since ECN bit on the outer IP TOS/traffic class field will be lost.
+Normal IPsec tunnel is described in RFC2401.
+On encapsulation, IPv4 TOS field (or, IPv6 traffic class field) will be copied from inner IP header to outer IP header.
+On decapsulation outer IP header will be simply dropped.
+The decapsulation rule is not compatible with ECN, since ECN bit on the outer IP TOS/traffic class field will be lost.
-To make IPsec tunnel ECN-friendly, we should modify encapsulation and decapsulation procedure. This is described in http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt[ http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt], chapter 3.
+To make IPsec tunnel ECN-friendly, we should modify encapsulation and decapsulation procedure.
+This is described in http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt[ http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt], chapter 3.
IPsec tunnel implementation can give you three behaviors, by setting net.inet.ipsec.ecn (or net.inet6.ipsec6.ecn) to some value:
@@ -662,6 +825,7 @@ http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt[ http://www.aciri.org/f
==== Interoperability
-Here are (some of) platforms that KAME code have tested IPsec/IKE interoperability in the past. Note that both ends may have modified their implementation, so use the following list just for reference purposes.
+Here are (some of) platforms that KAME code have tested IPsec/IKE interoperability in the past.
+Note that both ends may have modified their implementation, so use the following list just for reference purposes.
Altiga, Ashley-laurent (vpcom.com), Data Fellows (F-Secure), Ericsson ACC, FreeS/WAN, HITACHI, IBM AIX(R), IIJ, Intel, Microsoft(R) Windows NT(R), NIST (linux IPsec + plutoplus), Netscreen, OpenBSD, RedCreek, Routerware, SSH, Secure Computing, Soliton, Toshiba, VPNet, Yamaha RT100i
diff --git a/documentation/content/en/books/developers-handbook/kernelbuild/_index.adoc b/documentation/content/en/books/developers-handbook/kernelbuild/_index.adoc
index e7fb85fa07..bf127de265 100644
--- a/documentation/content/en/books/developers-handbook/kernelbuild/_index.adoc
+++ b/documentation/content/en/books/developers-handbook/kernelbuild/_index.adoc
@@ -32,19 +32,23 @@ include::shared/en/urls.adoc[]
toc::[]
-Being a kernel developer requires understanding of the kernel build process. To debug the FreeBSD kernel it is required to be able to build one. There are two known ways to do so:
+Being a kernel developer requires understanding of the kernel build process.
+To debug the FreeBSD kernel it is required to be able to build one.
+There are two known ways to do so:
The supported procedure to build and install a kernel is documented in the link:{handbook}#kernelconfig-building[Building and Installing a Custom Kernel] chapter of the FreeBSD Handbook.
[NOTE]
====
-It is supposed that the reader of this chapter is familiar with the information described in the link:{handbook}#kernelconfig-building[Building and Installing a Custom Kernel] chapter of the FreeBSD Handbook. If this is not the case, please read through the above mentioned chapter to understand how the build process works.
+It is supposed that the reader of this chapter is familiar with the information described in the link:{handbook}#kernelconfig-building[Building and Installing a Custom Kernel] chapter of the FreeBSD Handbook.
+If this is not the case, please read through the above mentioned chapter to understand how the build process works.
====
[[kernelbuild-traditional]]
== Building the Faster but Brittle Way
-Building the kernel this way may be useful when working on the kernel code and it may actually be faster than the documented procedure when only a single option or two were tweaked in the kernel configuration file. On the other hand, it might lead to unexpected kernel build breakage.
+Building the kernel this way may be useful when working on the kernel code and it may actually be faster than the documented procedure when only a single option or two were tweaked in the kernel configuration file.
+On the other hand, it might lead to unexpected kernel build breakage.
[.procedure]
. Run man:config[8] to generate the kernel source code:
diff --git a/documentation/content/en/books/developers-handbook/kerneldebug/_index.adoc b/documentation/content/en/books/developers-handbook/kerneldebug/_index.adoc
index daea455841..817ef1f7de 100644
--- a/documentation/content/en/books/developers-handbook/kerneldebug/_index.adoc
+++ b/documentation/content/en/books/developers-handbook/kerneldebug/_index.adoc
@@ -38,13 +38,20 @@ toc::[]
[[kerneldebug-obtain]]
== Obtaining a Kernel Crash Dump
-When running a development kernel (e.g., FreeBSD-CURRENT), such as a kernel under extreme conditions (e.g., very high load averages, tens of thousands of connections, exceedingly high number of concurrent users, hundreds of man:jail[8]s, etc.), or using a new feature or device driver on FreeBSD-STABLE (e.g., PAE), sometimes a kernel will panic. In the event that it does, this chapter will demonstrate how to extract useful information out of a crash.
+When running a development kernel (e.g., FreeBSD-CURRENT), such as a kernel under extreme conditions (e.g., very high load averages, tens of thousands of connections, exceedingly high number of concurrent users, hundreds of man:jail[8]s, etc.),
+or using a new feature or device driver on FreeBSD-STABLE (e.g., PAE), sometimes a kernel will panic.
+In the event that it does, this chapter will demonstrate how to extract useful information out of a crash.
-A system reboot is inevitable once a kernel panics. Once a system is rebooted, the contents of a system's physical memory (RAM) is lost, as well as any bits that are on the swap device before the panic. To preserve the bits in physical memory, the kernel makes use of the swap device as a temporary place to store the bits that are in RAM across a reboot after a crash. In doing this, when FreeBSD boots after a crash, a kernel image can now be extracted and debugging can take place.
+A system reboot is inevitable once a kernel panics.
+Once a system is rebooted, the contents of a system's physical memory (RAM) is lost, as well as any bits that are on the swap device before the panic.
+To preserve the bits in physical memory, the kernel makes use of the swap device as a temporary place to store the bits that are in RAM across a reboot after a crash.
+In doing this, when FreeBSD boots after a crash, a kernel image can now be extracted and debugging can take place.
[NOTE]
====
-A swap device that has been configured as a dump device still acts as a swap device. Dumps to non-swap devices (such as tapes or CDRWs, for example) are not supported at this time. A "swap device" is synonymous with a "swap partition."
+A swap device that has been configured as a dump device still acts as a swap device.
+Dumps to non-swap devices (such as tapes or CDRWs, for example) are not supported at this time.
+A "swap device" is synonymous with a "swap partition."
====
Several types of kernel crash dumps are available:
@@ -63,11 +70,15 @@ Minidumps are the default dump type as of FreeBSD 7.0, and in most cases will ca
[[config-dumpdev]]
=== Configuring the Dump Device
-Before the kernel will dump the contents of its physical memory to a dump device, a dump device must be configured. A dump device is specified by using the man:dumpon[8] command to tell the kernel where to save kernel crash dumps. The man:dumpon[8] program must be called after the swap partition has been configured with man:swapon[8]. This is normally handled by setting the `dumpdev` variable in man:rc.conf[5] to the path of the swap device (the recommended way to extract a kernel dump) or `AUTO` to use the first configured swap device. The default for `dumpdev` is `AUTO` in HEAD, and changed to `NO` on RELENG_* branches (except for RELENG_7, which was left set to `AUTO`). On FreeBSD 9.0-RELEASE and later versions, bsdinstall will ask whether crash dumps should be enabled on the target system during the install process.
+Before the kernel will dump the contents of its physical memory to a dump device, a dump device must be configured.
+A dump device is specified by using the man:dumpon[8] command to tell the kernel where to save kernel crash dumps.
+The man:dumpon[8] program must be called after the swap partition has been configured with man:swapon[8].
+This is normally handled by setting the `dumpdev` variable in man:rc.conf[5] to the path of the swap device (the recommended way to extract a kernel dump) or `AUTO` to use the first configured swap device.
+The default for `dumpdev` is `AUTO` in HEAD, and changed to `NO` on RELENG_* branches (except for RELENG_7, which was left set to `AUTO`).
+On FreeBSD 9.0-RELEASE and later versions, bsdinstall will ask whether crash dumps should be enabled on the target system during the install process.
[TIP]
====
-
Check [.filename]#/etc/fstab# or man:swapinfo[8] for a list of swap devices.
====
@@ -87,16 +98,23 @@ Also, remember that the contents of [.filename]#/var/crash# is sensitive and ver
[[extract-dump]]
=== Extracting a Kernel Dump
-Once a dump has been written to a dump device, the dump must be extracted before the swap device is mounted. To extract a dump from a dump device, use the man:savecore[8] program. If `dumpdev` has been set in man:rc.conf[5], man:savecore[8] will be called automatically on the first multi-user boot after the crash and before the swap device is mounted. The location of the extracted core is placed in the man:rc.conf[5] value `dumpdir`, by default [.filename]#/var/crash# and will be named [.filename]#vmcore.0#.
+Once a dump has been written to a dump device, the dump must be extracted before the swap device is mounted.
+To extract a dump from a dump device, use the man:savecore[8] program.
+If `dumpdev` has been set in man:rc.conf[5], man:savecore[8] will be called automatically on the first multi-user boot after the crash and before the swap device is mounted.
+The location of the extracted core is placed in the man:rc.conf[5] value `dumpdir`, by default [.filename]#/var/crash# and will be named [.filename]#vmcore.0#.
-In the event that there is already a file called [.filename]#vmcore.0# in [.filename]#/var/crash# (or whatever `dumpdir` is set to), the kernel will increment the trailing number for every crash to avoid overwriting an existing [.filename]#vmcore# (e.g., [.filename]#vmcore.1#). man:savecore[8] will always create a symbolic link to named [.filename]#vmcore.last# in [.filename]#/var/crash# after a dump is saved. This symbolic link can be used to locate the name of the most recent dump.
+In the event that there is already a file called [.filename]#vmcore.0# in [.filename]#/var/crash# (or whatever `dumpdir` is set to), the kernel will increment the trailing number for every crash to avoid overwriting an existing [.filename]#vmcore# (e.g., [.filename]#vmcore.1#).
+man:savecore[8] will always create a symbolic link to named [.filename]#vmcore.last# in [.filename]#/var/crash# after a dump is saved.
+This symbolic link can be used to locate the name of the most recent dump.
-The man:crashinfo[8] utility generates a text file containing a summary of information from a full memory dump or minidump. If `dumpdev` has been set in man:rc.conf[5], man:crashinfo[8] will be invoked automatically after man:savecore[8]. The output is saved to a file in `dumpdir` named [.filename]#core.txt.N#.
+The man:crashinfo[8] utility generates a text file containing a summary of information from a full memory dump or minidump.
+If `dumpdev` has been set in man:rc.conf[5], man:crashinfo[8] will be invoked automatically after man:savecore[8].
+The output is saved to a file in `dumpdir` named [.filename]#core.txt.N#.
[TIP]
====
-
-If you are testing a new kernel but need to boot a different one in order to get your system up and running again, boot it only into single user mode using the `-s` flag at the boot prompt, and then perform the following steps:
+If you are testing a new kernel but need to boot a different one in order to get your system up and running again,
+boot it only into single user mode using the `-s` flag at the boot prompt, and then perform the following steps:
[source,bash]
....
@@ -106,12 +124,16 @@ If you are testing a new kernel but need to boot a different one in order to get
# exit # exit to multi-user
....
-This instructs man:savecore[8] to extract a kernel dump from [.filename]#/dev/ad0s1b# and place the contents in [.filename]#/var/crash#. Do not forget to make sure the destination directory [.filename]#/var/crash# has enough space for the dump. Also, do not forget to specify the correct path to your swap device as it is likely different than [.filename]#/dev/ad0s1b#!
+This instructs man:savecore[8] to extract a kernel dump from [.filename]#/dev/ad0s1b# and place the contents in [.filename]#/var/crash#.
+Do not forget to make sure the destination directory [.filename]#/var/crash# has enough space for the dump.
+Also, do not forget to specify the correct path to your swap device as it is likely different than [.filename]#/dev/ad0s1b#!
====
=== Testing Kernel Dump Configuration
-The kernel includes a man:sysctl[8] node that requests a kernel panic. This can be used to verify that your system is properly configured to save kernel crash dumps. You may wish to remount existing file systems as read-only in single user mode before triggering the crash to avoid data loss.
+The kernel includes a man:sysctl[8] node that requests a kernel panic.
+This can be used to verify that your system is properly configured to save kernel crash dumps.
+You may wish to remount existing file systems as read-only in single user mode before triggering the crash to avoid data loss.
[source,bash]
....
@@ -131,7 +153,9 @@ After rebooting, your system should save a dump in [.filename]#/var/crash# along
[NOTE]
====
-This section covers man:kgdb[1]. The latest version is included in the package:devel/gdb[]. An older version is also present in FreeBSD 11 and earlier.
+This section covers man:kgdb[1].
+The latest version is included in the package:devel/gdb[].
+An older version is also present in FreeBSD 11 and earlier.
====
To enter into the debugger and begin getting information from the dump, start kgdb:
@@ -141,14 +165,16 @@ To enter into the debugger and begin getting information from the dump, start kg
# kgdb -n N
....
-Where _N_ is the suffix of the [.filename]#vmcore.N# to examine. To open the most recent dump use:
+Where _N_ is the suffix of the [.filename]#vmcore.N# to examine.
+To open the most recent dump use:
[source,bash]
....
# kgdb -n last
....
-Normally, man:kgdb[1] should be able to locate the kernel running at the time the dump was generated. If it is not able to locate the correct kernel, pass the pathname of the kernel and dump as two arguments to kgdb:
+Normally, man:kgdb[1] should be able to locate the kernel running at the time the dump was generated.
+If it is not able to locate the correct kernel, pass the pathname of the kernel and dump as two arguments to kgdb:
[source,bash]
....
@@ -157,7 +183,12 @@ Normally, man:kgdb[1] should be able to locate the kernel running at the time th
You can debug the crash dump using the kernel sources just like you can for any other program.
-This dump is from a 5.2-BETA kernel and the crash comes from deep within the kernel. The output below has been modified to include line numbers on the left. This first trace inspects the instruction pointer and obtains a back trace. The address that is used on line 41 for the `list` command is the instruction pointer and can be found on line 17. Most developers will request having at least this information sent to them if you are unable to debug the problem yourself. If, however, you do solve the problem, make sure that your patch winds its way into the source tree via a problem report, mailing lists, or by being able to commit it!
+This dump is from a 5.2-BETA kernel and the crash comes from deep within the kernel.
+The output below has been modified to include line numbers on the left.
+This first trace inspects the instruction pointer and obtains a back trace.
+The address that is used on line 41 for the `list` command is the instruction pointer and can be found on line 17.
+Most developers will request having at least this information sent to them if you are unable to debug the problem yourself.
+If, however, you do solve the problem, make sure that your patch winds its way into the source tree via a problem report, mailing lists, or by being able to commit it!
[source,bash]
....
@@ -255,16 +286,19 @@ This dump is from a 5.2-BETA kernel and the crash comes from deep within the ker
[TIP]
====
-
-If your system is crashing regularly and you are running out of disk space, deleting old [.filename]#vmcore# files in [.filename]#/var/crash# could save a considerable amount of disk space!
+If your system is crashing regularly and you are running out of disk space,
+deleting old [.filename]#vmcore# files in [.filename]#/var/crash# could save a considerable amount of disk space!
====
[[kerneldebug-online-ddb]]
== On-Line Kernel Debugging Using DDB
-While `kgdb` as an off-line debugger provides a very high level of user interface, there are some things it cannot do. The most important ones being breakpointing and single-stepping kernel code.
+While `kgdb` as an off-line debugger provides a very high level of user interface, there are some things it cannot do.
+The most important ones being breakpointing and single-stepping kernel code.
-If you need to do low-level debugging on your kernel, there is an on-line debugger available called DDB. It allows setting of breakpoints, single-stepping kernel functions, examining and changing kernel variables, etc. However, it cannot access kernel source files, and only has access to the global and static symbols, not to the full debug information like `kgdb` does.
+If you need to do low-level debugging on your kernel, there is an on-line debugger available called DDB.
+It allows setting of breakpoints, single-stepping kernel functions, examining and changing kernel variables, etc.
+However, it cannot access kernel source files, and only has access to the global and static symbols, not to the full debug information like `kgdb` does.
To configure your kernel to include DDB, add the options
[.programlisting]
@@ -277,20 +311,32 @@ options KDB
options DDB
....
-to your config file, and rebuild. (See link:{handbook}/[The FreeBSD Handbook] for details on configuring the FreeBSD kernel).
+to your config file, and rebuild.
+(See link:{handbook}/[The FreeBSD Handbook] for details on configuring the FreeBSD kernel).
-Once your DDB kernel is running, there are several ways to enter DDB. The first, and earliest way is to use the boot flag `-d`. The kernel will start up in debug mode and enter DDB prior to any device probing. Hence you can even debug the device probe/attach functions. To use this, exit the loader's boot menu and enter `boot -d` at the loader prompt.
+Once your DDB kernel is running, there are several ways to enter DDB.
+The first, and earliest way is to use the boot flag `-d`.
+The kernel will start up in debug mode and enter DDB prior to any device probing.
+Hence you can even debug the device probe/attach functions.
+To use this, exit the loader's boot menu and enter `boot -d` at the loader prompt.
-The second scenario is to drop to the debugger once the system has booted. There are two simple ways to accomplish this. If you would like to break to the debugger from the command prompt, simply type the command:
+The second scenario is to drop to the debugger once the system has booted.
+There are two simple ways to accomplish this.
+If you would like to break to the debugger from the command prompt, simply type the command:
[source,bash]
....
# sysctl debug.kdb.enter=1
....
-Alternatively, if you are at the system console, you may use a hot-key on the keyboard. The default break-to-debugger sequence is kbd:[Ctrl+Alt+ESC]. For syscons, this sequence can be remapped and some of the distributed maps out there do this, so check to make sure you know the right sequence to use. There is an option available for serial consoles that allows the use of a serial line BREAK on the console line to enter DDB (`options BREAK_TO_DEBUGGER` in the kernel config file). It is not the default since there are a lot of serial adapters around that gratuitously generate a BREAK condition, for example when pulling the cable.
+Alternatively, if you are at the system console, you may use a hot-key on the keyboard.
+The default break-to-debugger sequence is kbd:[Ctrl+Alt+ESC].
+For syscons, this sequence can be remapped and some of the distributed maps out there do this, so check to make sure you know the right sequence to use.
+There is an option available for serial consoles that allows the use of a serial line BREAK on the console line to enter DDB (`options BREAK_TO_DEBUGGER` in the kernel config file).
+It is not the default since there are a lot of serial adapters around that gratuitously generate a BREAK condition, for example when pulling the cable.
-The third way is that any panic condition will branch to DDB if the kernel is configured to use it. For this reason, it is not wise to configure a kernel with DDB for a machine running unattended.
+The third way is that any panic condition will branch to DDB if the kernel is configured to use it.
+For this reason, it is not wise to configure a kernel with DDB for a machine running unattended.
To obtain the unattended functionality, add:
@@ -301,14 +347,17 @@ options KDB_UNATTENDED
to the kernel configuration file and rebuild/reinstall.
-The DDB commands roughly resemble some `gdb` commands. The first thing you probably need to do is to set a breakpoint:
+The DDB commands roughly resemble some `gdb` commands.
+The first thing you probably need to do is to set a breakpoint:
[source,bash]
....
break function-name address
....
-Numbers are taken hexadecimal by default, but to make them distinct from symbol names; hexadecimal numbers starting with the letters `a-f` need to be preceded with `0x` (this is optional for other numbers). Simple expressions are allowed, for example: `function-name + 0x103`.
+Numbers are taken hexadecimal by default, but to make them distinct from symbol names;
+hexadecimal numbers starting with the letters `a-f` need to be preceded with `0x` (this is optional for other numbers).
+Simple expressions are allowed, for example: `function-name + 0x103`.
To exit the debugger and continue execution, type:
@@ -334,7 +383,8 @@ If you want to remove a breakpoint, use
del address-expression
....
-The first form will be accepted immediately after a breakpoint hit, and deletes the current breakpoint. The second form can remove any breakpoint, but you need to specify the exact address; this can be obtained from:
+The first form will be accepted immediately after a breakpoint hit, and deletes the current breakpoint.
+The second form can remove any breakpoint, but you need to specify the exact address; this can be obtained from:
[source,bash]
....
@@ -364,7 +414,8 @@ This will step into functions, but you can make DDB trace them until the matchin
[NOTE]
====
-This is different from ``gdb``'s `next` statement; it is like ``gdb``'s `finish`. Pressing kbd:[n] more than once will cause a continue.
+This is different from ``gdb``'s `next` statement; it is like ``gdb``'s `finish`.
+Pressing kbd:[n] more than once will cause a continue.
====
To examine data from memory, use (for example):
@@ -377,7 +428,9 @@ To examine data from memory, use (for example):
x/s stringbuf
....
-for word/halfword/byte access, and hexadecimal/decimal/character/ string display. The number after the comma is the object count. To display the next 0x10 items, simply use:
+for word/halfword/byte access, and hexadecimal/decimal/character/ string display.
+The number after the comma is the object count.
+To display the next 0x10 items, simply use:
[source,bash]
....
*** 4742 LINES SKIPPED ***
More information about the dev-commits-doc-all
mailing list