Brussels - II - enhanced network interface configuration via ipadm 1. Introduction ================ Network configuration on Solaris has always been needlessly complex. Tools like ifconfig(1M) are known to be severely overloaded, confusing and complex. This has been recorded in several places and to quote a few (a) the ON SAC opinion for PSARC 1997/184 stated, " .. the already complex ifconfig utility. The committee feels this project is making an already serious ease of use problem even worse. The steering committees are advised to initiate a project to create a new easier to use network interface configuration utility." (b) one of the comments in ifconfig.c, reads as below, " .. ifconfig(1M) is too overloaded and the code is so convoluted that it is "safer" not to re-architect the code to fix the above issue, hence this "hack." We may be better off to have a new command with better syntax for configuring network interface parameters..." PSARC 2001/544 made an attempt to provide a clean API for managing network interfaces through the libinetcfg library, but those interfaces were not extended over time to accommodate features such as IPMP and Stateful IPv6 Address Configuration. An additional drawback of libinetcfg was that the API did not solve the problem of the growing complexity of the ifconfig command itself. More recently, several projects have made steps towards shrinking ifconfig bloat by providing more intuitive and elegant interfaces for configuring ipsec and tunnel management through commands like ipssecconf(1M) and dladm(1M). This project completes that trend by migrating the remaining features into ipadm(1M) while providing a full set of parallel library interfaces as defined in the design document [1]. A related issue, not addressed by PSARC 2001/544, but recognized as a problem by customers, is the lack of simple administrative interfaces for persistent configuration of TCP/IP tunables. Specifically, the ndd(1M) tool lacks Stable interfaces and a well-defined mechanism for applying settings persistently across reboot. This project will introduce a tool, ipadm(1M) that will allow system administrators to persistently set TCP/IP tunables and will have a user- and library-interface that is consistent with corresponding dladm(1M) interfaces that are in use for Layer 2 of the networking stack. The set of tunables supported by ipadm will be constructed to include meaningful semantics that are competitive with, or improve upon, those available on other Operating Systems. The interfaces provided by this project will supersede the Consolidation Private interfaces defined in libinetcfg. Existing invocations to functions in libinetcfg will be converted to appropriate invocations of libipadm. 2. Brussels II - Network interface configuration ================================================= As part of the first phase of the project, we will deliver a tool, /sbin/ipadm that can do all of the following ** interface creation/deletion ** address management (add,delete,show) for static IPv4 & IPv6 addresses, DHCP, stateless/stateful IPv6 Address Configuration ** tunable management (set, get, reset) global (ndd) tunables, as well as per-interface tunables ** persistent configuration of all of the above parameters on reboot, following a model similar to that used for other network configuration tools like dladm and flowadm ** modify a critical subset of network configuration tools to link into the newly created library as proof of concept. This subset will minimally include ifconfig. ** Enhance the existing net-physical service and network_rcm to recognize and instantiate any configuration created using ipadm(1M) Architectural details of the CLI are available in [1]. See Appendix for the components that will be delivered in the subsequent putbacks. NOTE: ===== * Where possible, support for obsolete or meaningless ndd tunables will be removed from the system. Typical examples of such tunables are those pertaining to status reports (see CR 4616660). * Note that all the ndd tunables will *not* be converted blindly into ipadm tunables. Some may be consolidated, e.g., the various ndd tunables for "ip_respond_to_" tunables will be collapsed into one ipadm tunable that takes as input the icmp type, a "yes/no" action indicating whether to respond to the icmp type, and a "unicast/bcast/mcast" option qualifying the type of packets targeted. Section 4.4 for set of ndd tunables that would be supported by ipadm(1M). * However, since ndd(1m) has some history of usage for providing a means of tuning "customer-specials" (corner case tweaks for some subset of customers), and this needs to be done on a per-stack-instance basis, we will move all the 'other (not in section 4.4)' tunables (ip/tcp/udp/sctp) as 'private' tunables with Volatile stability that may be used with ipadm set/get prop commands. The Project team believes that taking this course of action is more beneficial as it would ensure usage of only one tool for tunable management, going forward, which is ipadm(1m), as against two tools. 3. Interfaces delivered by PSARC 2009/306 ========================================== The following interfaces will be delivered as part of the first putback: ------------------------------------------------------------------------------ Interface Classification Comments ------------------------------------------------------------------------------ /sbin/ipadm Committed See 2, 3, 4, 5, 6, 7, 8, 9, 10 & 11 of [1] ipadm parsable output Committed See [2] All other ipadm output Uncommitted See [2] solaris.network.interface.config Committed Needed to configure network interfaces. /lib/libipadm.so Consolidation Contains library interfaces Private that map to ipadm subcommands. IP interface properties Committed see [2] for supported interface properties and their descriptions IP address properties Committed see [2] for supported address properties and their descriptions. getifaddrs Committed Section 6 of [1]. These API's freeifaddrs Committed will be part of libsocket.so /usr/include/ifaddrs.h Committed SIOCSETPROP Consolidation (modified) Private See 13 of [1] SIOCGETPROP Consolidation Private mod_ioc_prop_t Consolidation See 13 of [1] Private IP module properties Committed See [3] for supported properties and their their descriptions TCP module properties Committed Same as above UDP module properties Committed Same as above SCTP module properites Committed Same as above /lib/inet/ipmgmtd Project Private See 14.1 of [1] svc:/network/ip-interface-managment:default Project Private See 14.2 of [1] /etc/ipadm/ipadm.conf Project Private /sbin/netstart Committed See 15.1 of [1] and [4] 4. References (enclosed in case directory) ======================================== [1] "Brussels II - ipadm and libipadm" design document - brussels2_design.pdf [2] ipadm MAN page - ipadm.1m.txt [3] Summary of protocol module properties supported by 'ipadm(1M)' - brussels2_prop.txt [4] netstart.1m.txt [5] privileges.man.txt.diff Appendix: ========== Following the delivery of this component, in the subsequent phases of the project, following components may be delivered. * support for IPMP in ipadm, * transition tools, including conversion scripts to convert existing ad-hoc persistence mechanisms like /etc/hostname.intf to the format used for the ipadm(1M) repository * conversion of several ON network configuration tools to link into libipadm.so.1 Each of the above components will be separately delivered and will be represented by separate PSARC cases. IPMP subcommand support ======================== This component will provide support for IPMP configuration using ipadm and is described in Section 12 of [1]. In conjunction with ipmpstat (delivered by PSARC 2007/272) ipadm and ipmpstat will provide a user-friendly API for configuring IPMP and querying IPMP state in the system. Transition existing /etc/hostname.intf configuration to ipadm ============================================================== This case will initiate the adoption of ipadm by modifying interface start-up services like svc:/network/phyiscal:default and network_rcm to first parse the /etc/hostname.intf files, followed by a query of the ipadm repository (using ipadm_if_info()) to instantiate existing ipadm configuration. However, since the ultimate objective is to eradicate /etc/hotname.intf usage, the "Transition" component of ipadm will provide the necessary scripts to convert /etc/hostname.intf configuration to ipadm configuration, along with appropriate methods for alerting the administrator about the modification.