| #ident "@(#)proposal.txt 1.2 06/08/07 SMI" 1. Proposal summary 2. Architecture 2.1 Big picture 2.2 HAL device tree 2.3 logindevperm 3. HAL 3.1 Information sources and events 3.2 Ownership == visibility 3.3 Privileged operations with methods 3.4 Administration and security 3.5 Zones 4. Volume managers 4.1 Features common to all volume managers 4.2 rmvolmgr 4.3 gnome-volume-manager 4.4 KDE and others 5. Command line interface 5.1 Removed commands 5.2 Volume mount/unmount 5.3 volcheck(1) 5.4 eject(1) 5.5 HAL commands 6. References Additional files in the materials directory: vold_transition.txt vold transition plan hal_and_dbus.txt overview of D-BUS and HAL q_and_a.txt answers to common questions interfaces.txt interface tables futures.txt future directions ====================================================================== Glossary: ACPI Advanced Configuration and Power Interface Industry-standard interface for OS-directed configuration and power management. ACPI obsoletes legacy power management BIOS code, Advanced Power Management (APM) and PNPBIOS interfaces. CDE Common Desktop Environment, an obsolete UNIX desktop environment. CVS Concurrent Versions System, a source version control system, widely used by open source projects. D-BUS Desktop Bus, a lightweight, socket-based IPC mechanism for system-application and application-application communication. DTU Desktop Unit, a Sun Ray appliance. .fdi Device Information File, XML document format for defining HAL device properties. FHS Filesystem Hierarchy Standard [2] hotpluggable A device attribute, means the device can be connected/ disconnected without rebooting the system and configured/ unconfigured automatically without user intervention. GDL Global Device List, a device list internal to HAL, accessible by applications through a well-defined D-BUS API. GNOME GNU Network Object Model Environment HAL Hardware Abstraction Layer, an interface between the system and desktop applications, that abstracts system's view of devices. Sometimes used to refer to the HAL daemon. JDS Java Desktop System, a GNOME-based desktop environment from Sun. removable A device attribute, means the mass storage device operates on physical media that can be manually removed (CDROM, floppy, flash card reader, etc). RM Removable Media, refers to either removable devices, or in some contexts, to removable+hotpluggable devices. TX Trusted Extensions, layered successor of Trusted Solaris UDI Unique Device Identifier, an ascii token used by HAL to uniquely identify a device. VM In the context of this document, VM is a volume manager: a program that mounts and unmounts volumes. A VM may perform additional functions, such as launch various applications depending on media type (Audio CD, Video DVD, etc). vold Volume Management daemon, removed by this project. ====================================================================== 1. Proposal summary It is proposed to remove vold from Nevada and replace it with a combination of open source HAL (Hardware Abstraction Layer) with Solaris extensions and several GUI and non-GUI volume managers. The new facility will be compatible with thin client technologies like Sun Ray, as well as accommodate Trusted Extensions and device allocation. The proposal enables adoption of the latest GNOME features in JDS4, such as GNOME Volume Manager, Nautilus, Battery Applet, etc. Compatibility with CDE is preserved. All proposed components are entirely in userland. No GUI is defined in this proposal. Requested binding: Minor. ====================================================================== 2. Architecture 2.1 Big picture Recognizing the fact that the requirements for removable device management span a wide range depending on a customer, the project components are loosely coupled to allow for a variety of configuration options. volume managers, apps, ... ^ | | | signals | | methods [session/unpriv] | | - - - - - - - - - - - - D-BUS - - - - - - - - - - - - - - - - - [system/priv] | | | v HAL --> addons/callouts/methods /...\ devfsadm, sunray devmgr, allocate, login/ttymon, ... HAL daemon plays a central role in collecting device information from disparate sources and presenting it to the clients in a consistent manner. The D-BUS IPC mechanism (LSARC/2006/368) is used for all communications. Applications running in the unprivileged domain can receive signals from HAL when new devices are discovered and request privileged operations, such as volume mount, by calling HAL methods. Note that HAL does not initiate actions on the newly discovered media. This decision is left to the users or helper programs acting on their behalf. We call such helpers removable volume managers (VM). Everything VMs do is also doable manually: e.g. when the OS recognizes a new disk, the user can run a command to mount it. VMs simply automate manual steps: they watch for new media and perform configurable actions on it. Different user environments, such as GNOME or KDE, can provide different volume managers to provide the most seamless RM experience possible. Environments without a HAL-compatible VM can use a generic Sun-supplied VM called rmvolmgr. See chapter 4 for more on VMs. 2.2 HAL device tree For an overview of HAL and D-BUS refer to chapter 6. The HAL device tree is similar to the Solaris device tree in that it consists of nodes and properties. HAL on Solaris will present local device tree and Sun Ray DTU device trees as branches of the generalized tree, e.g.: Computer Local USB controller PDA USB hub iPod FAT32 volume DTU IEEE802.080020cf428a USB controller USB disk UFS volume We propose to assign each device or branch an ownership property represented by user name. User applications will only "see" part of the tree that belongs to that user. For instance, a DTU branch could be owned by the user logged on this DTU; the 'Local' branch would be owned by the user logged on the workstation console; hub port branches could be statically assigned to the users in a multi-seat configuration; an allocate(1)-ed device would be owned by the respective user. Ownership can either be assigned or claimed. See 3.2 for additional info. A device entering user's visibility scope has the equivalent effect of hotplugging. This, for instance, allows the GUI to automatically work with allocate(1). 2.3 logindevperm HAL does not rely on logindevperm. The project at large does, but allows logindevperm to be disabled without the loss of functionality. To enable functionality like extracting Audio CD tracks or backing up with tar out of the box, we propose to give console user read-only access to the local disks with 'hotpluggable' (PSARC/2005/731) and 'removable-media' properties. Since logindevperm does not allow to filter devices by property, only by path, we propose to create two new | namespaces, /dev/hotpluggable and /dev/removable-media, have devfsadm | create secondary links to the disks with these properties and add the following entries to etc/logindevperm: | /dev/console 0400 /dev/removable-media/dsk/* | /dev/console 0400 /dev/removable-media/rdsk/* /dev/console 0400 /dev/hotpluggable/dsk/* /dev/console 0400 /dev/hotpluggable/rdsk/* Disabling these entries will not break automatic mounts or eject. It might affect applications that open devices directly and don't run set-uid or in a RBAC profile. ====================================================================== 3. HAL For a general overview see 'hal_and_dbus.txt' in the materials. | HAL specification with a complete list of properties and methods | is included in the materials, see hal-spec.html. | Note that D-BUS, and therefore HAL, will operate in local mode only | on Solaris, as specified in LSARC/2006/368 D-BUS Message Bus System. 3.1 Information sources and events HAL collects information from a variety of sources. Solaris device info is retrieved using libdevinfo(3LIB) and kept up to date using devfsadm sysevents. Sun Ray device info and events are retrieved using project private Sun Ray interfaces (Tamarack does not need a contract because HAL code for Sun Ray will be shipped in a separate shared module as part of SRSS). We also propose two new sysevent classes. Class: EC_TTY Subclasses: ESC_DEVPERM_LOGIN, ESC_DEVPERM_LOGOUT Attributes: DEV_NAME (DATA_TYPE_STRING) ESC_DEVPERM_LOGIN is sent after the login process changed all device permissions associated with the terminal identified by the DEV_NAME attribute. ESC_DEVPERM_LOGOUT is sent after these permissions are changed back. This does not affect pty, but should be considered for the virtual terminal project. The logout event will allow HAL to clean up device ownership at the end of session in case user applications did not do it explicitly by calling the HAL method (see 3.2). Class: EC_DEV_ALLOCATE Subclasses: ESC_ALLOCATE, ESC_DEALLOCATE Attributes: DEV_NAME (DATA_TYPE_STRING) USER (DATA_TYPE_STRING) ZONE (DATA_TYPE_STRING) ESC_ALLOCATE is sent when a device DEV_NAME is allocate(1)ed to the USER in the ZONE. ESC_DEALLOCATE is sent when the device is deallocated. This will allow HAL to automatically update ownership of the devices as they are allocated or deallocated. 3.2 Ownership == visibility As mentioned in 2.2, device ownership defines its visibility scope. Devices not owned by a user won't be visible and the effects of owning and disowning are equivalent to hot-plugging and unplugging from a user's perspective. Ownership can be either assigned or claimed. Devices not owned by any user will be automatically assigned to the reserved user 'daemon'. Ownership may be assigned in cases of device allocation, use logging into a Sun Ray DTU and in the future for multi-seat configurations. Ownership can be claimed by a user application by calling a HAL method. | We propose a new pair of methods Hal.Device.ClaimBranch()/UnclaimBranch(). | HAL will only allow this in the following cases: - device is local and user is logged on console; - device belongs to a Sun Ray DTU and user is logged into this DTU; - in all cases, a claim will be denied if device is allocatable. Typically a console session VM will claim the entire 'Local' branch and DTU session VMs will claim respective DTU branches. 3.3 Privileged operations with methods Depending on media type, users or volume managers can perform various actions on it. Some actions require extra privileges and HAL allows it through the use of methods. Right now the useful methods include self-explanatory Mount(), Unmount() and Eject(). We have also added ZpoolExport() and ZpoolImport() for ZFS. In the future, more methods might be available such as Format() and Partition(). Special applications like CD/DVD burning will continue to use profiles or least privilege-enhanced set-uid. There are multiple levels at which these actions can be restricted. - visibility scope (as discussed in 3.2); - access to methods can be denied through the hal.conf file; - HAL's PolicyKit controls the types of media and operations available to users or groups (see 'hal_and_dbus.txt' in the materials). 3.4 Administration and security HAL on Solaris is an SMF service with FMRI: svc:/system/hal Dependencies: svc:/system/dbus svc:/system/filesystem/local svc:/milestone/multi-user RBAC authorization and a profile will be added: solaris.smf.manage.hal:::Manage HAL Service States::help=SmfHALStates.html HAL Management:::Manage HAL:auths=solaris.smf.manage.hal;help=RtHALMngmnt.html HAL consists of several processes, typically: hald hald-runner hald-addon-storage hald-probe-volume ... hald-runner is basically an addon/callout launcher. After forking hald-runner, hald will drop unused privileges. hald-runner will assign | different privileges to the forked processes. These privileges will | be defined as HAL SMF service properties. hald requires the sys_devices privilege for full access to the device tree, and the ability to listen to sysevents, which at the moment require uid=0. Most device-oriented addons require file_dac_read and sys_devices. Mount()/Unmount() method addons obviously require sys_mount. | On each HAL method invocation an audit event will be logged. 3.5 Zones For the complete functionality, user session applications must be able to communicate with HAL over D-BUS using a unix domain socket. When HAL runs in a global zone and the user session runs in a local zone, this is not possible. In particular, this represents a problem for Trusted Extensions. We propose a near-term solution for initial Tamarack integration to simply emulate rmmount(1M) and action_filemgr.so (vold_transition.txt in the materials), since allocate(1) invokes rmmount(1M) directly. Effectively, user experienced will not change at all. Since g-v-m (4.3) will not be available in a zone, interactive JDS features will not be available to local zone sessions initially. For the long-term solution as a follow-up project we consider several possible solutions including implementing D-BUS on top of doors. ====================================================================== 4. Volume managers 4.1 Features common to all volume managers All volume managers should claim device ownership to ensure proper operation in multi-seat environments and avoid conflicts between each other. Volume managers operating on local devices should use /media as the mount root, according to the Filesystem Hierarchy Standard (FHS) [2]. By default, /media will be world-writable with a sticky bit set. Mount point names should use volume label when present. The filesystem(5) man page will be updated accordingly. Volume managers operating on non-local devices, such as Sun Ray sessions, or allocated devices, may opt for user-centric mount roots, such as $HOME/media or /media/. 4.2 rmvolmgr Rmvolmgr is the default RM volume manager that is only capable of mounting and unmounting volumes (zpool import/export for ZFS). Rmvolmgr is Solaris-specific and serves the following purposes: - to provide RM automount outside user sessions; - to facilitate backward compatibility with vold. - to help users who do not run the standard Gnome desktop; Multiple instances of rmvolmgr can be run simultaneously, for each user or user session. A system instance of rmvolmgr will be started at boot and manage unowned devices - it can be safely disabled if that is not required, but will be enabled by default to mimic vold behavior. To help vold transition, rmvolmgr also creates symlinks under /{cdrom,floppy,rmdisk} to the original mount points under /media. rmvolmgr will mimic vold's action_volmgr.so, to provide backwards compatibility with CDE (see vold_transition.txt for details). It will also mimic the old rmmount(1M) and will be usable by allocate(1). System rmvolmgr instance FMRI: svc:/system/filesystem/rmvolmgr 4.3 gnome-volume-manager JDS4 being the standard Solaris desktop environment, gnome-volume-manager (g-v-m) is the GUI that most users will use. While Tamarack enables g-v-m, it is not part of the project. Following is for information only. G-v-m is automatically started at the beginning of the GNOME session. It takes actions depending on media/content type: mounts and unmounts filesystems, launches applications on insertion of blank CD/DVD media, audio CD and video DVD, digital cameras and portable music players. Applications can be customized in Preferences or gconf editor under /desktop/gnome/volume_manager/ namespace. 4.4 KDE and others KDE developers are actively working on supporting HAL. Project team does not plan explicit support or testing of KDE, but will work with developers to make it possible. There is a number of standalone HAL-based volume managers, such as Ivman [10]. Users should be able to install them manually on Solaris. Other desktop environments can utilize rmvolmgr for simple non-interactive automount. ====================================================================== 5. Command line interface 5.1 Removed commands The following commands will be removed with vold: volrmmount(1) volcancel(1) volmissing(1) 5.2 Volume mount/unmount For simple mounting and unmounting a modified version of rmmount(1) and a new rmumount(1) command are introduced (see rmmount.1.txt in the materials). They will support mounting by device name, label and or mount point. For instance a typical iPod is labeled 'IPOD' so the user can simply utter 'rmmount IPOD' to mount all mountable partitions on the device. 5.3 volcheck(1) Floppy drives cannot report presence of media without attempting to access it. Therefore floppy devices cannot be safely polled like CDROM devices. The existing volcheck(1) command allows users to manually poll floppies and mount them if a new floppy was detected. The project team felt that this command should be preserved even after vold removal. volcheck(1) will be reimplemented to use HAL interfaces. When a user manually (re-)formats a disk with a HAL-unaware application, volcheck(1) will also get HAL to reprobe the device. 5.4 eject(1) We propose considers the following enhancements to eject(1): - Add an option to close CD tray (-t is compatible with Linux eject): -t The drive is given a CD-ROM tray close command. Not all devices support this command. - Remove -n and -p options: -n Displays the nickname to device name translation table. -p Does not try to call the eject_popup program. - Instead of a nickname, a volume label should be used. - Add an option to list ejectable devices: -l Displays paths and labels (if available) of ejectable devices. 5.5 HAL commands lshal A libhal-based command line utility that simply dumps the HAL device list with all properties. It is not an end-user tool, but like prtconf(1M), is useful for diagnosis and debug. hal-device hal-find-by-capability hal-find-by-property hal-get-property hal-set-property Commands for various HAL device operations. Also not intended for developers and system administrators. hal-fdi-validate Command to validate one or more .fdi files against DTD. Intended for system administrators. ====================================================================== 6. References [1] Tamarack internal and external pages: http://tamarack.sfbay http://opensolaris.org/os/project/tamarack [2] Filesystem Hierarchy Standard: http://www.pathname.com/fhs [3] Old vold design: http://tamarack.sfbay/vold.shtml [4] Project Utopia: http://kerneltrap.org/node/3450 [5] HAL docs: Home page: http://www.freedesktop.org/Software/hal Spec: http://tinyurl.com/kax7s http://opensolaris.org/os/project/tamarack/hal_re.html [6] Vold cases: PSARC/1992/008 volume_mgmt PSARC/1992/088 Averoigne PSARC/1993/469 Filemgr Interface LSARC/1999/598 dtfile full support for removable media devices PSARC/2005/672 vold EOF [7] Sun Ray cases: LSARC/2001/205 CDE Support for Sunray USB Storage LSARC/2003/749 CDE enhancements for accessing USB Storage managed by remote device services. [8] Tamarack related cases: PSARC/2005/672 vold EOF PSARC/2005/731 hotpluggable disk support PSARC/2005/520 cdrecord and friends into the WOS PSARC/2006/089 cdrecord privilege awareness LSARC/2006/202 GNOME 2.14 - Vermillion LSARC/2006/368 D-BUS Message Bus System [9] D-BUS tutorial: http://dbus.freedesktop.org/doc/dbus-tutorial.html [10] Ivman: http://ivman.sourceforge.net/