PSARC Questions Version 1.17 ------------------------------------------------------------------------ 1. What specifically is the proposal that we are reviewing? - What is the technical content of the project? Phase 1 of the Network Auto-Magic project described in 2007/132. Primary components of the phase include: * Profile repository, storing three different types of network data profiles: Network Configuration Profiles (NCPs), Locations, and External Network Modifiers (ENMs). * The profile repository API, made up of libnwam and netcfgd. * The UI components: nwamcfg and nwamadm, which make up the CLI; and a Gnome panel applet and a network configuration GUI application. * The profile daemon, nwamd. These components are described in detail in the Phase 1 Specification[1]. - Is this a new product, or a change to a pre-existing one? If it is a change, would you consider it a "major", "minor", or "micro" change? This is a change to an existing product. From the user's perspective, and in terms of the external interfaces presented, it should appear to be an evolutionary change, offering enhanced functionality but not changing the fundamental behavior. Under the hood, it is a more substantial change to the existing codebase. The current daemon will be largely rewritten, and the interaction with the GUI interface will be both modified and extended. - If your project is an evolution of a previous project, what changed from one version to another? * Network data profiles will be more fully supported: interfaces will be configured and system attributes will be updated automatically, according to the user's preferences, when underlying network conditions change. * User interfaces have been extended/added: the GUI introduced in phase 0.5 (PSARC 2008/482) will be enhanced and updated to the new daemon interface, and a new CLI will be delivered with this phase. - What is the motivation for it, in general as well as specific terms? (Note that not everyone on the ARC will be an expert in the area.) Phases 0 and 0.5 apply a simple, default policy with minimal user interaction. When things go as expected, and the default policy matches the user's desires, that's great. But if there are driver problems, for example, or if the user wants a different policy, the lack of UI is a serious problem. Additionally, the existing daemon state machine is fairly brittle, and can break down in the face of unexpected hardware behavior or network conditions. The phase 0.5 changes were focused on some short-term improvements in observability, and on offering users some very specific, commonly requested configuration knobs. This project will extend the configuration options available to users, and will also address the state machine stability issues. Finally, automatically configuring individual interfaces is only the first step in fully automatic network configuration; this phase of the project adds the ability to automatically configure higher level, system-wide network-related features, such as name services and basic security features, which makes the solution much more complete. - What are the expected benefits for Sun? More automatic/user-friendly network configuration is very important for Solaris adoption goals. Users with typical network requirements expect the network to "just work"; users wanting to set up more elaborate network configurations expect a consistent interface to do so. This phase of the project improves the robustness of the Solaris solution for the former group; and it provides that consistent inter- face expected by the latter group. - By what criteria will you judge its success? * Network and Location profiles can be created/changed/viewed using either the GUI or CLI. * Profiles will be activated/deactivated automatically by the system in response to changing network conditions. 2. Describe how your project changes the user experience, upon installation and during normal operation. - What does the user perceive when the system is upgraded from a previous release? On upgrade from a release in which an earlier phase of NWAM was enabled, earlier NWAM configuration will be automatically imported into a phase 1 profile, which will be active upon boot. The user should thus see only changes in the available information and configuration options from the new/enhanced UI; network configuration should be unchanged. On upgrade from a release in which NWAM was not present, behavior will depend on the installation vehicle. OpenSolaris installations will enable NWAM by default, in which case the user will not be asked network config questions during install, and will see network configuration performed automatically on boot (following the default NWAM policy of one interface active at a time, wired preferred over wireless). Solaris Nevada installations will not enable NWAM by default, so network configuration will work just as it did pre-NWAM. On upgrade from a release in which NWAM was present but disabled, NWAM will continue to be disabled. Beyond the question of upgrade behavior, though, it should be noted that the split between "network/physical:default" and "network/physical:nwam" configuration will continue to exist after the integration of this project. If the default instance of the network/physical service is enabled, the traditional network configuration scripts will run, setting up links and interfaces based on files such as /etc/hostname.*, /etc/dhcp.*, dladm.conf, etc., and network configuration will happen once, on boot. If the nwam instance is enabled, those files will be ignored, and nwam will perform dynamic network configuration based on configuration profiles (automatic or user-created) and available network resources. 3. What is its plan? - What is its current status? Has a design review been done? Are there multiple delivery phases? Review of the Phase 1 Specification[1] is in progress, as is development of the test suite and the ON and Desktop components. Integration into ON and Desktop consolidations is expected in February 2009. Future phases of the project will extend the set of network components that NWAM can configure, and enhance its policy management capabilities. 4. Are there related projects in Sun? - If so, what is the proposal's relationship to their work? Which not-yet- delivered Sun (or non-Sun) projects (libraries, hardware, etc.) does this project depend upon? What other projects, if any, depend on this one? N/A - Are you updating, copying or changing functional areas maintained by other groups? No. 5. How is the project delivered into the system? - Identify packages, directories, libraries, databases, etc. New ON components: NAME PACKAGE lib/svc/method/net-ipqos SUNWcsr lib/svc/method/net-location SUNWcsr lib/svc/method/net-netmask SUNWcsr usr/sbin/nwamadm SUNWcsr usr/sbin/nwamcfg SUNWcsr var/svc/manifest/network/network-ipqos.xml SUNWcsr var/svc/manifest/network/network-location.xml SUNWcsr var/svc/manifest/network/network-netmask.xml SUNWcsr New Desktop components: NAME PACKAGE nwam-manager-properties SUNWnwam-manager Existing ON components that will be modified: NAME PACKAGE lib/inet/nwamd SUNWcsr lib/libnwam.so.1 SUNWcslr lib/libnwam.so SUNWnwamintr* lib/llib-lnwam SUNWnwamintr* lib/llib-lnwam.ln SUNWnwamintr* lib/svc/method/net-nwam SUNWcsr lib/svc/method/net-svc SUNWcsr usr/include/libnwam.h SUNWnwamintu* var/svc/manifest/network/network-physical.xml SUNWcsr * SUNWnwamintr and SUNWnwamintu are internal packages that are not delivered to the WOS; they allow the contracted consolidation-private interfaces provided by libnwam to be consumed by the GUI components delivered to the desktop consolidation. Existing Desktop components that will be modified: NAME PACKAGE usr/lib/nwam-manager SUNWnwam-manager GConf keys SUNWnwam-manager-root 6. Describe the project's hardware platform dependencies. N/A 7. System administration - How will the project's deliverables be installed and (re)configured? pkgadd On upgrade from a version of Solaris which includes NWAM phase 0 or 0.5, the /etc/nwam/llp file will be read and translated into an NCP, which when activated on enable of the NWAM service will result in the same system behavior with NWAM phase 1. - How will the project's deliverables be uninstalled? pkgrm - Does it use inetd to start itself? No. - Does it need installation within any global system tables? No. - Does it use a naming service such as NIS, NIS+ or LDAP? Not directly, though it may indirectly obtain information from those services. Additionally, it will be able to manage the configuration of those services, and enable/disable them as specified by the user's policy. - What are its on-going maintenance requirements (e.g. Keeping global tables up to date, trimming files)? None. - How does this project's administrative mechanisms fit into Sun's system administration strategies? E.g., how does it fit under the Solaris Management Console (SMC) and Web-Based Enterprise Management (WBEM), how does it make use of roles, authorizations and rights profiles? Additionally, how does it provide for administrative audit in support of the Solaris BSM configuration? PSARC 2008/482, NWAM Phase 0.5, introduced the solaris.network.autoconf authorization. For this project, we will provide more granularity in this authorization by introducing: solaris.network.autoconf.read solaris.network.autoconf.write solaris.network.autoconf.refresh Refer to the Phase 1 Specification[1], section 6, for more details on the use of these authorizations. The 'Network Autoconf' profile, which was also introduced by NWAM Phase 0.5, will be updated to include 'solaris.network.autoconf.*', rather than just 'solaris.network.autoconf'. Thus any other profiles (such as 'Console User' and 'Network Management') which include 'Network Autoconf' will continue to have the same set of authorizations. If a user has created any profiles which directly include solaris.network.autoconf, those profiles will need to have similar updates made; however, use of the Network Autoconf profile is the preferred way to assign this authorization, so this should not be an issue for most users. - What tunable parameters are exported? Can they be changed without rebooting the system? Examples include, but are not limited to, entries in /etc/system and ndd(8) parameters. What ranges are appropriate for each tunable? What are the commitment levels associated with each tunable (these are interfaces)? No new tunables beyond the network/physical:nwam service properties introduced in earlier phases. 8. Reliability, Availability, Serviceability (RAS) - Does the project make any material improvement to RAS? The project simplifies network configuration, and enables the system to automatically react to changes in the network environment (e.g. if the ethernet connection is lost, it can bring up an alternate). Some of this is existing nwam behavior, but phase 1 will significantly extend the configuration options for users/administrators (allowing a wider variety of network configurations to be managed automatically). - How can users/administrators diagnose failures or determine operational state? (For example, how could a user tell the difference between a failure and very slow performance?) Use the SMF framework to observe high-level service state (there will be an NWAM service instance), or the GUI and/or nwamcfg(1M) and nwamadm(1M) to observe more detailed network state. - What are the project's effects on boot time requirements? None. - How does the project handle dynamic reconfiguration (DR) events? The insertion or removal of network interfaces will be noted and can result in automatic changes to the network configuration. - What mechanisms are provided for continuous availability of service? The functionality provided is in the form of an SMF service; it will be restarted as needed according to standard SMF behavior. - Does the project call panic()? Explain why these panics cannot be avoided. No. - How are significant administrative or error conditions transmitted? SNMP traps? Email notification? Mechanisms provided by the SMF framework: service state, service logs; syslog; and the GUI. - How does the project deal with failure and recovery? The component that actively manages configuration, nwamd is started by an SMF service, and thus benefits from its automatic restart mechanisms. When restarted, the daemon will differentiate between a "cold start" and a "warm start"; in the former, it will start from a blank page and create all network configuration from scratch, while in the latter, it will try to return to the current desired state with minimal change to the existing configuration. nwamd can function in a fully automatic mode if the GUI fails and cannot provide user input. Fully automatic mode is also useful in the case where a user is not logged in; in this case, nwamd will continue to manage the network configuration without user input. - Does it ever require reboot? If so, explain why this situation cannot be avoided. No. - How does your project deal with network failures (including partition and re- integration)? How do you handle the failure of hardware that your project depends on? A core feature of NWAM in general (that is not specific to this phase) is the ability to change the network configuration in response to changes in the available networks, so working around (by configuring other resources, for example) the failure of a network component is easily handled. - Can it save/restore or checkpoint and recover? Persistent configuration is saved under /etc/nwam/. - Can its files be corrupted by failures? Does it clean up any locks/files after crashes? Files can be corrupted; if the config files cannot be parsed, NWAM will fall back to its automatic mode, providing some measure of failsafe network connectivity. Library transactions will be atomic in that updates will be made to a temporary copy of the file, which will then be renamed to the actual file when all changes have been made. As the rename operation is atomic, this should prevent corruption due to partial updates to files. 9. Observability - Does the project export status, either via observable output (e.g., netstat) or via internal data structures (kstats)? One component of the GUI displays the current network state; the GUI and the CLI tools can display NWAM configuration status; and the SMF infrastructure provides high-level service instance status as well. - How would a user or administrator tell that this subsystem is or is not behaving as anticipated? Checking network state via the GUI, CLI, or existing command-line tools. - What statistics does the subsystem export, and by what mechanism? None. - What state information is logged? Significant failures are logged via syslog; debug level event tracking can also be enabled. Service-level failures are logged to standard service log files. - In principle, would it be possible for a program to tune the activity of your project? Yes, through the use of customized profiles specifying alternate network configuration policy. 10. What are the security implications of this project? - What security issues do you address in your project? The nwamd and netcfgd daemons run with privileges sufficient to manage network interfaces. Currently, nwamd must start with "all" privileges, as this is required by dhcpagent (which is indirectly started by nwamd) when it runs eventhook scripts. nwamd will acquire/drop privileges as needed, bracketing sections which need higher privileges, so that it will run with the minimum privileges needed at any given time. Requests to view or change the current or persistent configuration from unprivileged users are vetted by the daemons (with netcfgd managing changes to the persistent storage, and nwamd managing immediate change requests), which will use chkauthattr(3SECDB) to confirm that the user has sufficient authorizations to perform the requested operation. - The Solaris BSM configuration carries a Common Criteria (CC) Controlled Access Protection Profile (CAPP) -- Orange Book C2 -- and a Role Based Access Control Protection Profile (RBAC) -- rating, does the addition of your project effect this rating? E.g., does it introduce interfaces that make access or privilege decisions that are not audited, does it introduce removable media support that is not managed by the allocate subsystem, does it provide administration mechanisms that are not audited? No. - Is system or subsystem security compromised in any way if your project's configuration files are corrupt or missing? No. - Please justify the introduction of any (all) new setuid executables. N/A - Include a thorough description of the security assumptions, capabilities and any potential risks (possible attack points) being introduced by your project. A separate Security Questionnaire http://sac.sfbay/cgi-bin/bp.cgi?NAME=Security.bp is provided for more detailed guidance on the necessary information. Cases are encouraged to fill out and include the Security questionnaire (leveraging references to existing documentation) in the case materials. Projects must highlight information for the following important areas: - What features are newly visible on the network and how are they protected from exploitation (e.g. unauthorized access, eavesdropping) - If the project makes decisions about which users, hosts, services, ... are allowed to access resources it manages, how is the requestor's identity determined and what data is used to determine if the access granted. Also how this data is protected from tampering. - What privileges beyond what a common user (e.g. 'noaccess') can perform does this project require and why those are necessary. - What parts of the project are active upon default install and how it can be turned off. TBD 11. What is its UNIX operational environment: - Which Solaris release(s) does it run on? Solaris 11 - Environment variables? Exit status? Signals issued? Signals caught? (See signal(3HEAD).) N/A - Device drivers directly used (e.g. /dev/audio)? .rc/defaults or other resource/configuration files or databases? N/A - Does it use any "hidden" (filename begins with ".") or temp files? A door is created in /etc/svc/volatile When making updates to the configuration repository, changes are made to a temp file, which is then renamed to the real conf file name when all updates are complete (providing an atomic update to the actual file). Lingering temp files will be ignored/cleaned up the next time the file is written. - Does it use any locking files? No explicit locking files; however one file ('/etc/svc/volatile/nwamd_soft_reset') will be created and used to control restart behavior. Refer to section 7.2 of the Phase 1 Specification[1] for more details on the use of this file. - Command line or calling syntax: What options are supported? (please include man pages if available) Does it conform to getopt() parsing requirements? Refer to the nwamd(1M), nwamcfg(1M), and nwamadm(1M) man pages. - Is there support for standard forms, e.g. "-display" for X programs? Are these propagated to sub-environments? Yes. All the GUI applications conform to the GNOME HIG and its associated standard command-line arguments. Additional information can be found in the nwam-manager(1) and nwam-manager-properties(1) manpages, included in the case materials. - What shared libraries does it use? (Hint: if you have code use "ldd" and "dump -Lv")? ON components (nwamd/libnwam) libdladm.so.1 libinetcfg.so.1 libinetutil.so.1 libl.so.1 libnsl.so.1 libnvpair.so.1 libscf.so.1 libsocket.so.1 libsysevent.so.1 libtecla.so.1 libumem.so.1 libuutil.so.1 Desktop components libc.so.1 libgconf-2.so.4 libgdk_pixbuf-2.0.so.0 libglade-2.0.so.0 libglib-2.0.so.0 libgnome-2.so.0 libgnomeui-2.so.0 libgobject-2.0.so.0 libgthread-2.0.so.0 libgtk-x11-2.0.so.0 libinetcfg.so.1 libkstat.so.1 libnotify.so.1 libnsl.so.1 libnwam.so.1 libpthread.so.1 libsecdb.so.1 libsocket.so.1 - Identify and justify the requirement for any static libraries. N/A - Does it depend on kernel features not provided in your packages and not in the default kernel (e.g. Berkeley compatibility package, /usr/ccs, /usr/ucblib, optional kernel loadable modules)? No. - Is your project 64-bit clean/ready? If not, are there any architectural reasons why it would not work in a 64-bit environment? Does it interoperate with 64-bit versions? Yes. - Does the project depend on particular versions of supporting software (especially Java virtual machines)? If so, do you deliver a private copy? What happens if a conflicting or incompatible version is already or subsequently installed on the system? No. - Is the project internationalized and localized? The CLIs and GUI will use gettext(). - Is the project compatible with IPv6 interfaces and addresses? Yes. 12. What is its window/desktop operational environment? - Is it ICCCM compliant (ICCCM is the standard protocol for interacting with window managers)? Yes. - X properties: Which ones does it depend on? Which ones does it export, and what are their types? None other than those that GNOME depends on itself. - Describe your project's support for User Interface facilities including Help, Undo, Cut/Paste, Drag and Drop, Props, Find, Stop? Help will be supported, contextual where possible. Undo will only be supported where functionally possible - e.g. editing text, etc.; but not after a major change has been applied to the system such as reordering the NCUs or adding a rule, etc. It will be possible to manually undo the action, but not automatically. - How do you respond to property change notification and ICCCM client messages (e.g. Do you respond to "save workspace")? Session Management support will be using the GNOME standard mechanisms. - Which window-system toolkit/desktop does your project depend on? For automatic-mode behavior and command-line configuration, no window-system is required. The GUI configuration and notification tool depends on the GNOME/KDE tray mechanism. - Can it execute remotely? Is the user aware that the tool is executing remotely? Does it matter? The nwam-manager-properties tool can be used remotely; nwam-manager itself depends heavily upon the user's D-Bus session which currently doesn't support remote connections. In the case where the nwam-manager-properties tool is being used remotely, the user should be aware that it is executing remotely, as the tool is used to perform configuration on the system on which it is running. - Which X extensions does it use (e.g. SHM, DGA, Multi-Buffering? (Hint: use "xdpyinfo") Nothing extra beyond what the GNOME stack requires. - How does it use colormap entries? Can you share them? This is handled by the GNOME libraries. - Does it handle 24-bit operation? Yes. 13. What interfaces does your project import and export? - Please provide a table of imported and exported interfaces, including stability levels. Pay close attention to the classification of these interfaces in the Interface Taxonomy -- e.g., "Committed," "Uncommitted," and "*Private;" see: http://sac.sfbay/cgi-bin/bp.cgi?NAME=interface_taxonomy.bp Note: this interface table is for the ON components. In many cases, the GUI which is also included in this case is the consumer of the (contracted consolidation private) exported interfaces described here. Interfaces Imported Interface Classification Comments libdladm.so.1 Consolidation Private Interfaces Exported Interface Classification Comments libinetcfg.so.1 Consolidation private interfaces added to icfg_if_name existing library icfg_if_protocol icfg_is_loopback icfg_add_ipaddr icfg_remove_ipaddr icfg_plumb icfg_unplumb libnwam.so.1 Contr. consolidation configuration/event interface private consumed by CLI (in ON) and GUI (in Desktop); defined in phase 1 specification[1], section 5. libnwam.h Contr. consolidation library header file private /etc/nwam/ncp.conf[.new]Project private profile repository /etc/nwam/loc.conf[.new] /etc/nwam/enm.conf[.new] /etc/svc/volatile/nwam_soft_reset Project private reset behavior marker SMF services Volatile svc:/network/ipqos:default svc:/network/location:default svc:/network/netmask:default nwamadm(1M) nwamcfg(1M) cmdline syntax Committed configuration/management CLI cmd output Uncommitted nwam-manager(1) Uncommitted configuration/management GUI - Exported public library APIs and ABIs Protocols (public or private) Drag and Drop ToolTalk Cut/Paste N/A - Other interfaces N/A - What other applications should it interoperate with? How will it do so? N/A - Is it "pipeable"? How does it use stdin, stdout, stderr? The CLI components use getopt to parse stdin according to the semantics defined in the appropriate man pages (nwamadm.1M and nwamcfg.1M). stderr and stdout of these commands is human-readable (and uncommitted); it is not intended to be machine-parseable. - Explain the significant file formats, names, syntax, and semantics. Configuration files use a basic text format, described in section 4.4 of the design spec[1]. - Is there a public namespace? (Can third parties create names in your namespace?) How is this administered? NWAM uses the dladm secure object repository to store wireless keys; the naming scheme it uses for these objects constitutes a public namespace. Names are formatted as 'nwam-[essid]-[bssid]'. When NWAM is connecting to a secured WLAN, it will check for an appropriately named key before prompting the user for one; it does not care if the object was created via NWAM or external to NWAM. An interface to manage secure objects will be provided via the NWAM GUI. - Are the externally visible interfaces documented clearly enough for a non-Sun client to use them successfully? No, the API is currently private, and the files are not intended to be edited by hand, so there is not complete documentation for those. 14. What are its other significant internal interfaces inter-subsystem and inter-invocation)? - Protocols (public or private) - Private ToolTalk usage - Files - Other - Are the interfaces re-entrant? Door-based communication is used between several of the components: libnwam.so.1, netcfgd, nwamd, and the GUI. This interface is described in more detail in section 7 of the design spec[1]. 15. Is the interface extensible? How will the interface evolve? - How is versioning handled? libnwam.so.1 and its clients (GUI, CLI, and nwamd) are delivered together. - What was the commitment level of the previous version? Contracted Project Private. - Can this version co-exist with existing standards and with earlier and later versions or with alternative implementations (perhaps by other vendors)? - What are the clients over which a change should be managed? - How is transition to a new version to be accomplished? What are the consequences to ISV's and their customers? N/A 16. How do the interfaces adapt to a changing world? - What is its relationship with (or difficulties with) multimedia? 3D desktops? Nomadic computers? Storage-less clients? A networked file system model (i.e., a network-wide file manager)? Mobile systems are a primary target of this project; adapting the network configuration to take into account available connections is a core feature. For the typical mobile user, the network should just plain work, with no configuration required, when NWAM is enabled. NWAM will *not* change the existing behavior with respect to diskless clients and networked file systems. When the underlying network changes, NWAM will handle the low-layer network changes, but higher layer things like file system mounts will not be adjusted. This is an area which could be addressed by future projects. 17. Interoperability - If applicable, explain your project's interoperability with the other major implementations in the industry. In particular, does it interoperate with Microsoft's implementation, if one exists? - What would be different about installing your project in a heterogeneous site instead of a homogeneous one (such as Sun)? - Does your project assume that a Solaris-based system must be in control of the primary administrative node? N/A 18. Performance - How will the project contribute (positively or negatively) to "system load" and "perceived performance"? The project introduces an additional daemon (netcfgd) and Gnome applet that will be running by default. These will have a small impact on the system load, though that impact should be very minimal and is unlikely to introduce a user-perceptible change. - What are the performance goals of the project? How were they evaluated? What is the test or reference platform? The project is not intended or expected to impact performance, either positively or negatively. There could be small variations based on the additional daemon and applet, and increased memory usage as nwamd will be managing larger sets of configuration data, but the deltas should be trivial. - Does the application pause for significant amounts of time? No. Can the user interact with the application while it is performing long-duration tasks? Yes. - What is your project's MT model? How does it use threads internally? nwamd uses threads for the different tasks it performs, including scans on wireless interfaces, configuration of individual links and interfaces, monitoring various event sources, running the state machine. How does it expect its client to use threads? nwamd expects that the GUI client will use threads; at least one thread that listens for events and one that manages the UI. Users of NWAM in general are not expected/aren't required to be threaded. If it uses callbacks, can the called entity create a thread and recursively call back? No. - What is the impact on overall system performance? Near null. What is the average working set of this component? Currently 5636K How much of this is shared/sharable by other apps? Currently 4600K These numbers are based on very early versions of the code and will almost certainly change as development continues. They also do not take into account the GUI component. - Does this application "wake up" periodically? How often and under what conditions? What is the working set associated with this behavior? It "wakes up" when a change in system or network state is detected that requires re-evaluation of the current configuration. Working set with this behavior is much the same as the numbers referenced above, but as noted there, will almost certainly change. - Will it require large files/databases (for example, new fonts)? No. - Do files, databases or heap space tend to grow with time/load? What mechanisms does the user have to use to control this? What happens to performance/system load? The size of nwamd will scale with the number of links and interfaces and the size/level of detail of the user configuration. 19. Please identify any issues that you would like the ARC to address. N/A. 20. Appendices to include - One-Pager. - Prototype specification. - References to other documents. (Place copies in case directory.) Draft Man Pages included in the case directory: netcfgd(1M) nwamadm(1M) nwamcfg(1M) nwamd(1M) (changes to existing man page) nwam-manager(1) nwam-manager-properties(1) [1] Phase 1 Specification: http://opensolaris.org/os/project/nwam/p1spec/