Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Wednesday, July 27, 2022

sysobjadm (8)


sysobjadm - administrative command for the system object database


/usr/sbin/sysobjadm [-R rootpath] initialize
/usr/sbin/sysobjadm [-R rootpath] restore [-l] [-f file] [name]
/usr/sbin/sysobjadm [-R rootpath] regenaux
/usr/sbin/sysobjadm [-R rootpath] dump [search]
/usr/sbin/sysobjadm [-R rootpath] dump [class]
/usr/sbin/sysobjadm [-R rootpath] device-list [-P] [-I] [-i] [-a]
                    [-u uuid | -p path | -d driver]
/usr/sbin/sysobjadm [-R rootpath] device-remove
                    -u uuid | -p path | -d driver [-i]
/usr/sbin/sysobjadm [-R rootpath] device-set-instance
                    -u uuid | -p path <instance>


The sysobjadm command is the administrative command that interacts with the system object daemon (sysobjd) and the system object database itself.

The subcommands that deal with initializing or restoring the database should not be necessary under normal system operation. Unless an alternate root is specified, they should not be run while sysobjd is running; sysobjadm checks for this.

Additionally, a reboot is required after running most of these subcommands if no alternate root is specified. Normally, the expected sequence of commands for the initialize and restore commands is:

# svcadm disable -t sysobj        [if the sysobj SMF service is running]
# sysobjadm {backup|restore} ...
# reboot


The following global option is supported:


Specifies an alternate root path (base dir) to be used. This can be used to do maintenance of the system object database on a different boot environment. For more information, see the beadm(8) man page.

Sub Commands


Creates a new, empty database.

restore [–l] [–f file] [name]

Restores the database from a backup file. The –l option lists all available backup files created by the standard sysobjd backup mechanism.

The backup file can be specified in two ways:

  • Through –f <file> for a non-standard backup file. For example, copied to a non-standard location by the system administrator.

  • Using the <name> parameter, which selects a file from the standard location.

After restoring the database, all auxiliary files (if any), generated by sysobjd plugins, will be regenerated using the restored database.

dump [search]

Prints all aliases and properties of system objects. The optional <search> parameter specifies the class of objects to be printed. If it is omitted, all objects will be printed. The <search> parameter has the same syntax as the search string specified to sysobj_lookup(3SYSOBJ).

This subcommand can be run by an unprivileged user, although the user should be aware that not all classes of objects might be accessible without privileges.


Regenerates any auxiliary files as managed by sysobjd plugins. If the daemon is not running, or an alternate root is specified, sysobjadm loads the plugins itself, and instructs them to rewrite the files. This command can be used if the generated files got out of sync with the database, which is not expected to happen under normal system operation.


These are the subcommands specified by the sysobj device plugin. These commands are not expected to be used commonly; instead they act as replacements for the rare case where the system administrator might have edited the path_to_inst file. For more information, see the path_to_inst(5) man page. Since these commands manipulate vital device metadata, they should be used with care.

A 'running device' in this section refers to a situation where the command is executed on the main database ( if –R option is not specified), and the specified device is active. When executed on the current boot environment (for example, without –R option), a reconfigure boot (reboot -- -r) is likely needed to make sure /dev and /devices are in sync.

device-list [–P] [–I] [–i] [–a] [–u uuid | –p path | –d driver]

Lists device objects in the database, prints their UUID, driver, instance and state (active or inactive). If –P option is specified, the device path is printed instead of the UUID.

If –I option is specified, the format of path_to_inst is mimicked, printing the path, driver and instance. The –I flag is mutually exclusive with the –P flag.

If –u, –p or –d option is not specified, this will list all device objects, else only devices with the specified UUID, path or driver will be listed.

With the –a option, only active devices are listed. With the –i option, only inactive devices (currently not in the system) are listed. Without either of these options, all devices are listed.

It is important to note that when the global –R option is specified, the active/inactive state reflects the state the device had when the database in the alternate root path was last active and not the current state.

device-remove –u uuid | –p path
device-remove –d driver [–i]

Removes a device from the database, specified by device path or UUID. To remove a running device, the sysobj service must be disabled, and the command should be followed by a reboot. The second form of the command removes all devices with the specified device driver from the database, removing all inactive devices only if –i option is specified.

See the device-list command for what the device active/inactive state means in the case of the use of the global –R flag.

device-set-instance –u uuid | –p path <instance>

Sets the instance number for a device. If done on an running device, this command should be run with the sysobj service disabled, and followed by a reboot.


This example displays how a number of old device entries can be removed, and then the remaining device instances can be reassigned to have low, contiguous instance numbers. This example uses the USB 'hid' driver as an example, removing old instances of the mouse/keyboard devices.

# svcadm disable -t sysobj
# sysobjadm device-list -d hid
002f2bf6-bb28-4e6c-b484-9e59e7b376c9   hid    10    inactive
3dbaed01-1165-4003-8ca7-c7c1f0d03c7c   hid    12    inactive
41a60dfd-c584-4e47-b370-feae64a06539   hid    13    active
39b2cd4c-ae80-4028-843b-b205629c8e41   hid     9    active
# sysobjadm device-remove -d hid -i
# sysobjadm device-list -d hid
41a60dfd-c584-4e47-b370-feae64a06539   hid    13   active
39b2cd4c-ae80-4028-843b-b205629c8e41   hid     9   active
# sysobjadm device-list -P -d hid
/pci@0,0/pci1028,498@1a/hub@1/device@4/input@1     hid   13   active
/pci@0,0/pci1028,498@1d/hub@1/device@5/keyboard@0  hid    9   active
# sysobjadm device-set-instance -u 41a60dfd-c584-4e47-b370-feae64a06539 0
# sysobjadm device-set-instance -u 39b2cd4c-ae80-4028-843b-b205629c8e41 1
# reboot

[after reboot]

# sysobjadm device-list -d hid
41a60dfd-c584-4e47-b370-feae64a06539  hid      0   active
39b2cd4c-ae80-4028-843b-b205629c8e41  hid      1   active

This example shows how sysobjadm(8) can be used to fix a duplicate instance number problem, if for example two devices have been in error assigned the same instance number. In this case, two sd devices have been assigned the instance number 1.

# svcadm disable -t sysobj
# sysobjadm device-list -I
"/pseudoscsibus/pseudoscsibus@0,0/pseudoscsi@0/sd@0,0" 1 "sd"
"/pseudoscsibus/pseudoscsibus@0,0/pseudoscsi@0/sd@1,0" 1 "sd"
# sysobjadm device-set-instance -p /pseudoscsibus/pseudoscsibus@0,0/pseudoscsi@0/sd@1,0 2
# reboot

[ after reboot ]

# sysobjadm device-list -I
"/pseudoscsibus/pseudoscsibus@0,0/pseudoscsi@0/sd@0,0" 1 "sd"
"/pseudoscsibus/pseudoscsibus@0,0/pseudoscsi@0/sd@1,0" 2 "sd"

This example is the same as above, but illustrates how sysobjadm(8) can be used to repair a duplicate instance assignment on a mounted root image.

[ mount alternate root image on /mnt ]

# sysobjadm -R /mnt device-list -I
"/pseudoscsibus/pseudoscsibus@0,0/pseudoscsi@0/sd@0,0" 1 "sd"
"/pseudoscsibus/pseudoscsibus@0,0/pseudoscsi@0/sd@1,0" 1 "sd"
# sysobjadm -R /mnt device-set-instance -p /pseudoscsibus/pseudoscsibus@0,0/pseudoscsi@0/sd@1,0 2
# sysobjadm -R /mnt device-list -I
"/pseudoscsibus/pseudoscsibus@0,0/pseudoscsi@0/sd@0,0" 1 "sd"
"/pseudoscsibus/pseudoscsibus@0,0/pseudoscsi@0/sd@1,0" 2 "sd"
# bootadm update-archive -R /mnt

[ unmount alternate root image on /mnt ]

It is possible to import path_to_inst into sysobj directly. The path_to_inst file can be a known good copy restored from a backup or an updated version of the file provided by the administrator. Note: sysobj will itself import the path_to_inst file on the machine if it determines that the kdevdata file is corrupted or missing.

# svcadm disable -t sysobj
[ restore or otherwise fix /etc/devices/path_to_inst ]
# rm /etc/devices/kdevdata
# bootadm update-archive
# reboot

[ after reboot ]

WARNING: kdevdata file bad or not found; falling back to path_to_inst
sysobj: inconsistent boot data; regenerating
sysobj: rebooting the system

Bootstrapping is the process of generating a path_to_inst with instance assignments for the set of devices installed on a system. This process is used by Solaris for installation and can also be used as an administrative recovery procedure.

# svcadm disable -t sysobj
# rm /etc/devices/kdevdata
# mv /etc/devices/path_to_inst /etc/devices/path_to_inst.original
# echo '#path_to_inst_bootstrap_1' > /etc/devices/path_to_inst
# bootadm update-archive
# reboot

[ after reboot ]

WARNING: kdevdata file bad or not found; rebuilding
sysobj: inconsistent boot data; regenerating
sysobj: rebooting the system

Exit Status

The following exit values are returned:


Successful completion.


A fatal error occurred. One or more error messages are displayed on standard error. The exit code is an error code as specified in Intro(2). For invalid command line arguments, EINVAL is returned, and other exit codes depend on the command.


See attributes(7) for descriptions of the following attributes:

Interface Stability

See Also

sysobjd(8), libsysobj(3LIB), svcadm(8), beadm(8)