293 useradd/del/mod should be ZFS-aware

[illumos-gate.git] / usr / src / man / man1m / add_drv.1m

'\" te
.\"  Copyright (c) 2005 Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH ADD_DRV 1M "Dec 1, 2005"
.SH NAME
add_drv \- add a new device driver to the system
.SH SYNOPSIS
.LP
.nf
\fBadd_drv\fR [\fB-b\fR \fIbasedir\fR] [\fB-c\fR \fIclass_name\fR]
     [\fB-i\fR '\fIidentify_name\fR...'] [\fB-m\fR '\fIpermission\fR','...']
     [\fB-p\fR '\fIpolicy\fR'] [\fB-P\fR \fIprivilege\fR] [\fB-n\fR] [\fB-f\fR] [\fB-v\fR] \fIdevice_driver\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBadd_drv\fR command is used to inform the system about newly installed
device drivers.
.sp
.LP
Each device on the system has a name associated with it. This name is
represented by the \fBname\fR property for the device. Similarly, the device
may also have a list of driver names associated with it. This list is
represented by the \fBcompatible\fR property for the device.
.sp
.LP
The system determines which devices will be managed by the driver being added
by examining the contents of the \fBname\fR property and the \fBcompatible\fR
property (if it exists) on each device. If the value in the \fBname\fR property
does not match the driver being added, each entry in the \fBcompatible\fR
property is tried, in order, until either a match occurs or there are no more
entries in the \fBcompatible\fR property.
.sp
.LP
In some cases, adding a new driver may require a reconfiguration boot. See the
\fBNOTES\fR section.
.sp
.LP
Aliases might require quoting (with double-quotes) if they contain numbers. See
\fBEXAMPLES\fR.
.SS "The \fB/etc/minor_perm\fR File"
.sp
.LP
\fBadd_drv\fR and \fBupdate_drv\fR(1M) read the \fB/etc/minor_perm\fR file to
obtain permission information. The permission specified is applied to matching
minor nodes created when a device bound to the driver is attached. A minor
node's permission may be manually changed by \fBchmod\fR(1). For such nodes,
the specified permissions apply, overriding the default permissions specified
via \fBadd_drv\fR or \fBupdate_drv\fR(1M).
.sp
.LP
The format of the \fB/etc/minor_perm\fR file is as follows:
.sp
.in +2
.nf
\fIname\fR\fB:\fR\fIminor_name permissions owner group\fR
.fi
.in -2
.sp

.sp
.LP
\fIminor_name\fR may be the actual name of the minor node, or contain shell
metacharacters to represent several minor nodes (see \fBsh\fR(1)).
.sp
.LP
For example:
.sp
.in +2
.nf
sd:* 0640 root sys
zs:[a-z],cu 0600 uucp uucp
mm:kmem 0640 root bin
.fi
.in -2
.sp

.sp
.LP
The first line sets all devices exported by the \fBsd\fR node to \fB0640\fR
permissions, owned by \fBroot\fR, with group \fBsys\fR. In the second line,
devices such as \fBa,cu\fR \fBand\fR \fBz,cu\fR exported by the \fBzs\fR driver
are set to \fB0600\fR permission, owned by \fBuucp\fR, with group \fBuucp\fR.
In the third line the \fBkmem\fR device exported by the \fBmm\fR driver is set
to \fB0640\fR permission, owned by \fBroot\fR, with group \fBbin\fR.
.SS "Running \fBadd_drv\fR from a \fBpostinstall\fR Script"
.sp
.LP
When running \fBadd_drv\fR from within the context of a package's postinstall
script, you must consider whether the package is being added to a system image
or to a running system. When a package is being installed on a system image,
the \fBBASEDIR\fR variable refers to the image's base directory. In this
situation, \fBadd_drv\fR should be invoked with \fB-b\fR \fB$BASEDIR\fR. This
causes \fBadd_drv\fR only to update the image's system files; a reboot of the
system or client would be required to make the driver operational.
.sp
.LP
When a package is being installed on the running system itself, the system
files need to be updated, as in the case above. However, the running kernel can
be informed of the existence of the new driver without requiring a reboot. To
accomplish this, the postinstall script must invoke \fBadd_drv\fR without the
\fB-b\fR option. Accordingly, \fBpostinstall\fR scripts invoking \fBadd_drv\fR
should be written thusly:
.sp
.in +2
.nf
if [ "${BASEDIR:=/}" = "/" ]
then
        ADD_DRV="add_drv"
else
        ADD_DRV="add_drv -b ${BASEDIR}"
fi
$ADD_DRV [<options>] \fI<driver>\fR
.fi
.in -2
.sp

.sp
.LP
\&...or, alternatively:
.sp
.in +2
.nf
if [ "${BASEDIR:=/}" != "/" ]
then
         BASEDIR_OPT="-b $BASEDIR"
fi
         add_drv $BASEDIR_OPT [<options>] \fI<driver>\fR
.fi
.in -2
.sp

.sp
.LP
The \fB-b\fR option is described below.
.SH OPTIONS
.sp
.ne 2
.na
\fB\fB-b\fR \fIbasedir\fR\fR
.ad
.RS 26n
Installs the driver on the system with a root directory of \fIbasedir\fR rather
than installing on the system executing \fBadd_drv\fR. This option is typically
used in package post-installation scripts when the package is not being
installed on the system executing the \fBpkgadd\fR command. The system using
\fIbasedir\fR as its root directory must reboot to complete the driver
installation.
.LP
Note -
.sp
.RS 2
The root file system of any non-global zones must not be referenced with the
\fB-b\fR option. Doing so might damage the global zone's file system, might
compromise the security of the global zone, and might damage the non-global
zone's file system. See \fBzones\fR(5).
.RE
.RE

.sp
.ne 2
.na
\fB\fB-c\fR \fIclass_name\fR\fR
.ad
.RS 26n
The driver being added to the system exports the class \fIclass_name\fR.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.RS 26n
Normally if a reconfiguration boot is required to complete the configuration of
the driver into the system, \fBadd_drv\fR will not add the driver. The force
flag forces \fBadd_drv\fR to add the driver even if a reconfiguration boot is
required. See the \fB-v\fR flag.
.RE

.sp
.ne 2
.na
\fB\fB-i\fR \fB\&'\fR\fIidentify_name\fR\fB\&'\fR\fR
.ad
.RS 26n
A white-space separated list of aliases for the driver \fIdevice_driver\fR.
.RE

.sp
.ne 2
.na
\fB\fB-m\fR \fB\&'\fR\fIpermission\fR\fB\&'\fR\fR
.ad
.RS 26n
Specify the file system permissions for device nodes created by the system on
behalf of \fIdevice_driver\fR.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR\fR
.ad
.RS 26n
Do not try to load and attach \fIdevice_driver\fR, just modify the system
configuration files for the \fIdevice_driver\fR.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR '\fIpolicy\fR\fB\&'\fR\fR
.ad
.RS 26n
Specify an additional device security policy.
.sp
The device security policy constists of several whitespace separated tokens:
.sp
.in +2
.nf
{\fIminorspec\fR {token=value}+}+
.fi
.in -2
.sp

\fIminorspec\fR is a simple wildcard pattern for a minor device. A single
\fB*\fR matches all minor devices. Only one \fB*\fR is allowed in the pattern.
.sp
Patterns are matched in the following order:
.RS +4
.TP
.ie t \(bu
.el o
entries without a wildcard
.RE
.RS +4
.TP
.ie t \(bu
.el o
entries with wildcards, longest wildcard first
.RE
The following tokens are defined: \fBread_priv_set\fR and \fBwrite_priv_set\fR.
\fBread_priv_set\fR defines the privileges that need to be asserted in the
effective set of the calling process when opening a device for reading.
\fBwrite_priv_set\fR defines the privileges that need to be asserted in the
effective set of the calling process when opening a device for writing. See
\fBprivileges\fR(5).
.sp
A missing minor spec is interpreted as a \fB*\fR.
.RE

.sp
.ne 2
.na
\fB\fB-P\fR '\fIprivilege\fR\fB\&'\fR\fI\fR\fR
.ad
.RS 26n
Specify additional, comma separated, privileges used by the driver. You can
also use specific privileges in the device's policy.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.RS 26n
The verbose flag causes \fBadd_drv\fR to provide additional information
regarding the success or failure of a driver's configuration into the system.
See the \fBEXAMPLES\fR section.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRAdding SUNW Example Driver to the System
.sp
.LP
The following example adds the \fBSUNW,example\fR driver to a 32-bit system,
with an alias name of \fBSUNW,alias\fR. It assumes the driver has already been
copied to \fB/usr/kernel/drv\fR.

.sp
.in +2
.nf
example# add_drv \fB-m\fR '* 0666 bin bin','a 0644 root sys' \e
      \fB-p\fR 'a write_priv_set=sys_config  * write_priv_set=none' \e
      \fB-i\fR 'SUNW,alias' SUNW,example
.fi
.in -2
.sp

.sp
.LP
Every minor node created by the system for the \fBSUNW,example\fR driver will
have the permission \fB0666\fR, and be owned by user \fBbin\fR in the group
\fBbin\fR, except for the minor device \fBa\fR, which will be owned by
\fBroot\fR, group \fBsys\fR, and have a permission of \fB0644\fR. The specified
device policy requires no additional privileges to open all minor nodes, except
minor device \fBa\fR, which requires the \fBsys_config\fR privilege when
opening the device for writing.

.LP
\fBExample 2 \fRAdding Driver to the Client \fB/export/root/sun1\fR
.sp
.LP
The following example adds the driver to the client \fB/export/root/sun1\fR.
The driver is installed and loaded when the client machine, \fBsun1\fR, is
rebooted. This second example produces the same result as the first, except the
changes are on the diskless client,  \fBsun1\fR, and the client must be
rebooted for the driver to be installed.

.sp
.in +2
.nf
example# add_drv \fB-m\fR '* 0666 bin bin','a 0644 root sys' \e
        \fB-i\fR 'SUNW,alias' -b /export/root/sun1 \e
        SUNW,example
.fi
.in -2
.sp

.sp
.LP
See the note in the description of the \fB-b\fR option, above, specifying the
caveat regarding the use of this option with the Solaris zones feature.

.LP
\fBExample 3 \fRAdding Driver for a Device Already Managed by an Existing
Driver
.sp
.LP
The following example illustrates the case where a new driver is added for a
device that is already managed by an existing driver. Consider a device that is
currently managed by the driver \fBdumb_framebuffer\fR. The \fBname\fR and
\fBcompatible\fR properties for this device are as follows:

.sp
.in +2
.nf
name="display"
compatible="whizzy_framebuffer", "dumb_framebuffer"
.fi
.in -2
.sp

.sp
.LP
If \fBadd_drv\fR is used to add the \fBwhizzy_framebuffer\fR driver, the
following will result.

.sp
.in +2
.nf
example# add_drv whizzy_framebuffer
Error: Could not install driver (whizzy_framebuffer)
Device managed by another driver.
.fi
.in -2
.sp

.sp
.LP
If the \fB-v\fR flag is specified, the following will result.

.sp
.in +2
.nf
example# add_drv -v whizzy_framebuffer
Error: Could not install driver (whizzy_framebuffer)
Device managed by another driver.
Driver installation failed because the following
entries in /devices would be affected:

        /devices/iommu@f,e0000000/sbus@f,e0001000/display[:*]
        (Device currently managed by driver "dumb_framebuffer")

The following entries in /dev would be affected:

        /dev/fbs/dumb_framebuffer0
.fi
.in -2
.sp

.sp
.LP
If the \fB-v\fR and \fB-f\fR flags are specified, the driver will be added
resulting in the following.

.sp
.in +2
.nf
example# add_drv -vf whizzy_framebuffer
A reconfiguration boot must be performed to complete the
installation of this driver.

The following entries in /devices will be affected:

        /devices/iommu@f,e0000000/sbus@f,e0001000/display[:*]
        (Device currently managed by driver "dumb_framebuffer"

The following entries in /dev will be affected:

        /dev/fbs/dumb_framebuffer0
.fi
.in -2
.sp

.sp
.LP
The above example is currently only relevant to devices exporting a generic
device name.

.LP
\fBExample 4 \fRUse of Double Quotes in Specifying Driver Alias
.sp
.LP
The following example shows the use of double quotes in specifying a driver
alias that contains numbers.

.sp
.in +2
.nf
example# add_drv -i '"pci10c5,25"' smc
.fi
.in -2
.sp

.SH EXIT STATUS
.sp
.LP
\fBadd_drv\fR returns \fB0\fR on success and \fB1\fR on failure.
.SH FILES
.sp
.ne 2
.na
\fB\fB/kernel/drv\fR\fR
.ad
.sp .6
.RS 4n
32-bit boot device drivers
.RE

.sp
.ne 2
.na
\fB\fB/kernel/drv/sparcv9\fR\fR
.ad
.sp .6
.RS 4n
64-bit SPARC boot device drivers
.RE

.sp
.ne 2
.na
\fB\fB/kernel/drv/amd64\fR\fR
.ad
.sp .6
.RS 4n
64-bit x86 boot device drivers
.RE

.sp
.ne 2
.na
\fB\fB/usr/kernel/drv\fR\fR
.ad
.sp .6
.RS 4n
other 32-bit drivers that could potentially be shared between platforms
.RE

.sp
.ne 2
.na
\fB\fB/usr/kernel/drv/sparcv9\fR\fR
.ad
.sp .6
.RS 4n
other 64-bit SPARC drivers that could potentially be shared between platforms
.RE

.sp
.ne 2
.na
\fB\fB/usr/kernel/drv/amd64\fR\fR
.ad
.sp .6
.RS 4n
other 64-bit x86 drivers that could potentially be shared between platforms
.RE

.sp
.ne 2
.na
\fB\fB/platform/`uname\fR \fB-i`/kernel/drv\fR\fR
.ad
.sp .6
.RS 4n
32-bit platform-dependent drivers
.RE

.sp
.ne 2
.na
\fB\fB/platform/`uname\fR \fB-i`/kernel/drv/sparcv9\fR\fR
.ad
.sp .6
.RS 4n
64-bit SPARC platform-dependent drivers
.RE

.sp
.ne 2
.na
\fB\fB/platform/`uname\fR \fB-i`/kernel/drv/amd64\fR\fR
.ad
.sp .6
.RS 4n
64-bit x86 platform-dependent drivers
.RE

.sp
.ne 2
.na
\fB\fB/etc/driver_aliases\fR\fR
.ad
.sp .6
.RS 4n
driver aliases file
.RE

.sp
.ne 2
.na
\fB\fB/etc/driver_classes\fR\fR
.ad
.sp .6
.RS 4n
driver classes file
.RE

.sp
.ne 2
.na
\fB\fB/etc/minor_perm\fR\fR
.ad
.sp .6
.RS 4n
minor node permissions
.RE

.sp
.ne 2
.na
\fB\fB/etc/name_to_major\fR\fR
.ad
.sp .6
.RS 4n
major number binding
.RE

.sp
.ne 2
.na
\fB\fB/etc/security/device_policy\fR\fR
.ad
.sp .6
.RS 4n
device policy
.RE

.sp
.ne 2
.na
\fB\fB/etc/security/extra_privs\fR\fR
.ad
.sp .6
.RS 4n
device privileges
.RE

.SH SEE ALSO
.sp
.LP
\fBboot\fR(1M), \fBchmod\fR(1), \fBdevfsadm\fR(1M), \fBkernel\fR(1M),
\fBmodinfo\fR(1M), \fBrem_drv\fR(1M), \fBupdate_drv\fR(1M),
\fBdriver.conf\fR(4), \fBsystem\fR(4), \fBattributes\fR(5),
\fBprivileges\fR(5), \fBdevfs\fR(7FS), \fBddi_create_minor_node\fR(9F)
.sp
.LP
\fI\fR
.SH NOTES
.sp
.LP
It is possible to add a driver for a device already being managed by a
different driver, where the driver being added appears in the device's
\fBcompatible\fR list before the current driver. In such cases, a
reconfiguration boot is required (see \fBboot\fR(1M) and \fBkernel\fR(1M)).
After the reconfiguration boot, device links in \fB/dev\fR and references to
these files may no longer be valid (see the \fB-v\fR flag). If a
reconfiguration boot would be required to complete the driver installation,
\fBadd_drv\fR will fail unless the \fB-f\fR option is specified. See
\fBExample\fR \fB3\fR in the \fBEXAMPLES\fR section.
.sp
.LP
With the introduction of the device policy several drivers have had their minor
permissions changed and a device policy instated. The typical network driver
should use the following device policy:
.sp
.in +2
.nf
add_drv -p 'read_priv_set=net_rawaccess\e
   write_priv_set=net_rawaccess' -m '* 666 root sys'\e
   mynet
.fi
.in -2
.sp

.sp
.LP
This document does not constitute an API. \fB/etc/minor_perm\fR,
\fB/etc/name_to_major\fR, \fB/etc/driver_classes\fR, and \fB/devices\fR may not
exist or may have different contents or interpretations in a future release.
The existence of this notice does not imply that any other documentation that
lacks this notice constitutes an API.
.sp
.LP
\fB/etc/minor_perm\fR can only be updated by \fBadd_drv\fR(1M),
\fBrem_drv\fR(1M) or \fBupdate_drv\fR(1M).
.sp
.LP
In the current version of \fBadd_drv\fR, the use of double quotes to specify an
alias is optional when used from the command line. However, when using
\fBadd_drv\fR from packaging scripts, you should continue to use double quotes
to specify an alias.
.SH BUGS
.sp
.LP
Previous versions of \fBadd_drv\fR accepted a pathname for \fIdevice_driver\fR.
This feature is no longer supported and results in failure.