zonemgr - API for Zones administration
interface ZoneManager Result create(string name, string path, string template); Result delete(string name); Result importConfig(boolean noexecute, string name, string[] configuration); interface ZoneInfo string brand ; integer id ; string uuid ; string name ; boolean isGlobal ; interface Zone string[] auxstate ; string brand ; integer id ; string uuid ; string name ; string state ; cancelConfig(); string exportConfig(boolean includeEdits, boolean liveMode); update(boolean noexecute, string[] commands); editConfig(boolean liveMode); commitConfig(); boolean configIsLive(); boolean configIsStale(); addResource(Resource resource, Resource scope); reloadConfig(boolean liveMode); removeResources(Resource filter, Resource scope); Resource[] getResources(Resource filter, Resource scope); Property[] getResourceProperties(Resource filter, string[] properties); setResourceProperties(Resource filter, Property[] properties); clearResourceProperties(Resource filter, string[] properties); Result apply(string[] options); Result attach(string[] options); Result boot(string[] options); Result clone(string[] options); Result detach(string[] options); Result halt(string[] options); Result install(string[] options); Result mark(string[] options); Result migrate(string[] options); Result move(string[] options); Result rename(string[] options); Result ready(string[] options); Result reboot(string[] options); Result savecore(string[] options); Result shutdown(string[] options); Result suspend(string[] options); Result uninstall(string[] options); Result verify(string[] options);
ZONEMGR(3rad) RAD Module Definitions ZONEMGR(3rad) NAME zonemgr - API for Zones administration SYNOPSIS interface ZoneManager Result create(string name, string path, string template); Result delete(string name); Result importConfig(boolean noexecute, string name, string[] configuration); interface ZoneInfo string brand ; integer id ; string uuid ; string name ; boolean isGlobal ; interface Zone string[] auxstate ; string brand ; integer id ; string uuid ; string name ; string state ; cancelConfig(); string exportConfig(boolean includeEdits, boolean liveMode); update(boolean noexecute, string[] commands); editConfig(boolean liveMode); commitConfig(); boolean configIsLive(); boolean configIsStale(); addResource(Resource resource, Resource scope); reloadConfig(boolean liveMode); removeResources(Resource filter, Resource scope); Resource[] getResources(Resource filter, Resource scope); Property[] getResourceProperties(Resource filter, string[] properties); setResourceProperties(Resource filter, Property[] properties); clearResourceProperties(Resource filter, string[] properties); Result apply(string[] options); Result attach(string[] options); Result boot(string[] options); Result clone(string[] options); Result detach(string[] options); Result halt(string[] options); Result install(string[] options); Result mark(string[] options); Result migrate(string[] options); Result move(string[] options); Result rename(string[] options); Result ready(string[] options); Result reboot(string[] options); Result savecore(string[] options); Result shutdown(string[] options); Result suspend(string[] options); Result uninstall(string[] options); Result verify(string[] options); DESCRIPTION API com.oracle.solaris.rad.zonemgr This API provides functionality for the configuration and administration of Zones subsystem. The API provides a snapshot of the state of zones. The snapshot can be updated externally, either in another RAD session or by some other mechanism. This means that operations like commitConfig() may fail due to the changes introduced by other agents. The API detects and reports the creation and deletion of zones as well as configuration changes for individual zones. Some zones properties are accessed more frequently than others, for example, name. These properties are specifically exported as properties of the RAD interface as well as included in the list of zone properties. Three properties, id, state and auxstate, are not part of the configuration snapshot. These properties can vary without invalidating the integrity of the snapshot. These properties are documented as dynamic. The following sample Python clients illustrate some simple interactions with the module. Example 1. Retrieve a zones list, print 'pool' of first zone import rad.client as radcli import rad.connect as radcon import rad.bindings.com.oracle.solaris.rad.zonemgr_1 as zbind with radcon.connect_unix() as rc: zones = rc.list_objects(zbind.Zone()) zone0 = rc.get_object(zones[0]) for prop in zone0.getResourceProperties(zbind.Resource('global')): if prop.name == "pool": print "Zone: %s, pool: %s" % (zone0.name, prop.value) break Example 2. Listen to stateChange events import signal import rad.client as radcli import rad.connect as radcon import rad.bindings.com.oracle.solaris.rad.zonemgr_1 as zbind def handler(event, payload, user): print "event: %s" % str(event) print "payload: %s" % str(payload) print "zone: %s" % str(payload.zone) print "old: %s" % str(payload.oldstate) print "new: %s" % str(payload.newstate) with radcon.connect_unix() as rc: mgr = rc.get_object(zbind.ZoneManager()) rc.subscribe(mgr, "stateChange", handler) signal.pause() Example 3. Listen to configChange event of first zone import signal import rad.client as radcli import rad.connect as radcon import rad.bindings.com.oracle.solaris.rad.zonemgr_1 as zbind def handler(event, payload, user): print "event: %s" % str(event) print "payload: %s" % str(payload) print "zone: %s" % str(payload.zone) with radcon.connect_unix() as rc: zones = rc.list_objects(zbind.Zone()) zone0 = rc.get_object(zones[0]) print "Waiting for configuration change event on %s" % zone0.name rc.subscribe(zone0, "configChange", handler) signal.pause() Example 4. Find zone test0 and print out its brand import rad.client as radcli import rad.connect as radcon import rad.bindings.com.oracle.solaris.rad.zonemgr_1 as zbind with radcon.connect_unix() as rc: pat = radcli.ADRGlobPattern({"name" : "test0"}) test0 = rc.get_object(zbind.Zone(), pat) for prop in test0.getResourceProperties(zbind.Resource('global')): if prop.name == "brand": print "Zone: %s, brand: %s" % (test0.name, prop.value) break Example 5. Find zone with id 2 and print out its name import rad.client as radcli import rad.connect as radcon import rad.bindings.com.oracle.solaris.rad.zonemgr_1 as zbind import sys with radcon.connect_unix() as rc: zones = rc.list_objects(zbind.Zone(), radcli.ADRGlobPattern({"id" : "2"})) try: test0 = rc.get_object(zones[0]) except: print "Can't find a zone with that id" sys.exit(1) print "Zone: %s, id: %d" % (test0.name, test0.id) Example 6. Boot zone test0 import rad.client as radcli import rad.connect as radcon import rad.bindings.com.oracle.solaris.rad.zonemgr_1 as zbind with radcon.connect_unix() as rc: pat = radcli.ADRGlobPattern({"name" : "test0"}) test0 = rc.get_object(zbind.Zone(), pat) test0.boot(None) INTERFACES interface ZoneManager Manage the zone in which this instance is executing. Create and delete zones. Changes in the state of zones can be monitored through the StateChange event. ZoneManager Methods Result create(string name, string path, string template) Create a zone based on the default template or the specified template. Create a zone with the supplied name and path. If a template is supplied, it should be the name of a template, such as SYSblank. Arguments: name path (nullable) template (nullable) Result: Result Error: Result Result delete(string name) Delete a zone. Arguments: name Result: Result Error: Result Result importConfig(boolean noexecute, string name, string[] configuration) Create a zone using the exported definition of another zone. The supplied configuration must be in a format that could be used in a zonecfg command file - e.g. output of zonecfg export. Arguments: noexecute -- If true, do not execute the commands, but verify that they would result in a legal zone configuration. name configuration -- Command details Result: Result Error: Result ZoneManager Events StateChange stateChange interface ZoneInfo Report on the zone in which this instance is executing. Information about the current zone can be accessed. ZoneInfo Properties string brand (read-only) The brand of the zone in which this interface is executing. integer id (read-only) The ID of the zone in which this interface is executing. string uuid (read-only, nullable) The UUID of the zone in which this interface is executing. Read Error: Result string name (read-only) The name of the zone in which this instance is executing. boolean isGlobal (read-only) Is this instance executing in a global zone? interface Zone Operations that affect a single zone. Represents an individual zone. All zone configuration and administrative actions are represented in this interface. Changes of the zone configuration can be monitored through the configChange event. Zone Properties string[] auxstate (read-only, nullable) The list of zone auxiliary states. This property is dynamic, can be modified externally, and can be empty. Read Error: Result string brand (read-only) The brand of the zone. This is equivalent to the "brand" property in the global resource. integer id (read-only) The ID of the zone. This property is dynamic and can be modified externally. If a zone reboots, the zone ID will change. string uuid (read-only, nullable) The UUID of the zone. Read Error: Result string name (read-only) The name of the zone. This is equivalent to the "name" property in the global resource. string state (read-only) The state of the zone. This property is dynamic and can be modified externally. If a zone is booted, the zone state will change. See zones(5) for zone states reference. Zone Methods cancelConfig() Resets any configuration changes done after editConfig(). After the changes are reset, call editConfig() again to begin a new set of modifications. Note that this method will also reread the configuration by using reloadConfig(). Can return NOT_EDITING error if editConfig() has not already been called successfully. This method resets the session liveMode to false. Error: Result string exportConfig(boolean includeEdits, boolean liveMode) Return the exported output for this zone. Return a string containing the exported form of the configuration. The output matches the configuration snapshot. Arguments: includeEdits (nullable) -- If true (default if omitted), then the exported configuration will contain the in-flight modifications (if any were made) in the current session, otherwise only the committed on-disk configuration is exported. liveMode (nullable) -- If set to true, live (running) zone configuration is exported as seen at the time of this method call. If not specified, this method honors the session's liveMode. If the zone is not running yet live mode was requested, INVALID_ZONE_STATE error will be raised. Result: string Error: Result update(boolean noexecute, string[] commands) Process the supplied commands to update the zone. Process the list of commands. A SNAPSHOT_ERROR may result, in which case the configuration is unchanged. If the client still wishes to update the configuration after a SNAPSHOT_ERROR is returned they must refresh their snapshot of zone configuration using reloadConfig() method. (Before calling update() on the refreshed Zone object they should verify that their planned changes are still applicable to the zone configuration.) Arguments: noexecute -- If true, do not execute the commands, but verify that they would result in a legal zone configuration. commands -- Each element is a command, recognizable by zonecfg(1M). Failure of any command results in no changes to the zone. Error: Result editConfig(boolean liveMode) Initiate zone configuration editing. Calling this method will initiate a configuration modification transaction. It will also update the configuration snapshot if a new on-disk configuration is found. Each configuration editing transaction must either be canceled by a call to cancelConfig(), or changes must be committed using commitConfig(). There can be only one configuration editing transaction open at one time, so a subsequent call to editConfig() without calling cancelConfig() or succesfully calling commitConfig() first will result in an ALREADY_EDITING error. Arguments: liveMode (nullable) -- If set to true, Live Zone Reconfiguration mode is enabled (session liveMode is set to true) and all changes made to the configuration will be applied live to the running zone at the time commitConfig() is called. Can return INVALID_ZONE_STATE if the zone is not running. Error: Result commitConfig() Tries to save the configuration changes made by addResource(), removeResources() and setResourceProperties(), clearResourceProperties() since the last call to editConfig(). If external changes were made subsequent to editConfig(), no changes are saved and SNAPSHOT_ERROR is returned, indicating that the user should either abandon the changed configuration or call editConfig() to reread the current zone configuration, redo the changes, and try to save again. See the SNAPSHOT_ERROR description for more information. A NOT_EDITING error can be returned if editConfig() has not already been called successfully. The configuration is applied to running zone if the session's liveMode was set to true. However if the zone was not running any more, the INVALID_ZONE_STATE error will be raised. The session liveMode is not reset. Error: Result boolean configIsLive() Returns session's liveMode setting as set by preceding editConfig() or reloadConfig() method calls. Result: boolean boolean configIsStale() Checks whether a configuration snapshot captured by the instance is stale, meaning that changes to the zone configuration were done by an external process in the interim. Result: boolean Error: Result addResource(Resource resource, Resource scope) Queue a resource for addition to the zone configuration. While the change to the configuration is not saved until a successful call is made to commitConfig(), this resource is accessible by getResources(), getResourceProperties(), and setResourceProperties(), as well as by removeResources() methods. Returns RESOURCE_ALREADY_EXISTS if the resource being added is not unique. The NOT_EDITING error can be returned if editConfig() has not yet been called successfully. Example 7. Adding dedicated-cpu resource using addResource() ... zone0.addResource(zbind.Resource('dedicated-cpu', [zbind.Property('ncpus', '3-4'), zbind.Property('importance', '1')])) Example 8. Adding mac resource to particular anet ... zone0.addResource(zbind.Resource('mac'), zbind.Resource('anet', [Property('id', '3')])) Arguments: resource scope (nullable) -- Specify where to add the new resource to. See mac in anet resource example above. Error: Result reloadConfig(boolean liveMode) Reload zone configuration snapshot. This method should be used to reload the configuration snapshot from the on-disk zone configuration, which could have been changed by an external process. All uncommitted edits will be discarded. Arguments: liveMode (nullable) -- If specified, the session liveMode will be set. If not specified, this method honors the session's liveMode as set previously by editConfig() or reloadConfig(). INVALID_ZONE_STATE error can be raise if live reconfiguration was requested but the zone was not running. Error: Result removeResources(Resource filter, Resource scope) Delete resource(s) matching filter from the zone configuration. This method can fail with RESOURCE_NOT_FOUND if the filter does not match any resource. A NOT_EDITING error can be returned if editConfig() has not yet been called successfully. Arguments: filter scope (nullable) -- Specify where to remove the resource(s) from. Used for example to remove non-primary mac address(es) from a particular anet resource. Error: Result Resource[] getResources(Resource filter, Resource scope) Return a list of zero or more resources matching given filter. Arguments: filter (nullable) -- If NULL, all resources are returned. The INVALID_ARGUMENT error is returned if filter type is empty. The RESOURCE_UNKNOWN error is returned if filter type is an unknown resource type. Refer to zonecfg(1M) for a list of valid resource types. scope (nullable) -- Specify where to get the resource(s) from. Used for example to get a list of non-primary mac addresses for a particular anet resource. Result: Resource[] Error: Result Property[] getResourceProperties(Resource filter, string[] properties) Returns a list of zero or more properties of a given resource. This method can fail with RESOURCE_NOT_FOUND if filter does not match any resource, with RESOURCE_TOO_MANY if more than one resource matches, or with RESOURCE_UNKNOWN if filter type is not a known resource type. Arguments: filter properties (nullable) -- Names of the properties the caller is interested in. If NULL, all properties are returned. Result: Property[] Error: Result setResourceProperties(Resource filter, Property[] properties) Set property values of given resource. This method can fail with RESOURCE_NOT_FOUND if the filter does not match any resource, RESOURCE_UNKNOWN in the case of an invalid filter type, or RESOURCE_TOO_MANY if more than one resource matches. If an error occurs when setting the properties, the SYSTEM_ERROR is returned and Result.str should be inspected to obtain detailed information about the failure. The PROPERTY_UNKNOWN error can be returned if a property of the given name did not exist in that particular resource and the INVALID_ARGUMENT error can be returned if properties argument is an empty list. The NOT_EDITING error can be returned if editConfig() has not yet been called successfully. Example 9. Setting simple global variable import rad.client as radcli import rad.connect as radcon import rad.bindings.com.oracle.solaris.rad.zonemgr_1 as zbind with radcon.connect_unix() as rc: zones = rc.list_objects(zbind.Zone()) zone0 = rc.get_object(zones[0]) zone0.editConfig() zone0.setResourceProperties(zbind.Resource('global'), [zbind.Property('autoboot', 'false')]) Example 10. Setting multiple simple variables in particular anet resource ... zone0.setResourceProperties( zbind.Resource('anet', [zbind.Property('linkname', 'net1')]), [zbind.Property('mac-address', 'auto'), zbind.Property('mtu', '1400')]) In the following example please notice the listvalue named argument that needs to be used when constructing Property with list of simple value. See zonecfg(1m) manual page for detailed information about individual resources and properties. Example 11. Setting list of options to dir=/storage filesystem ... zone0.setResourceProperties( zbind.Resource('fs', [zbind.Property('dir', '/storage')]), [zbind.Property('options', listvalue=['ro', 'nodevices'])]) Next example shows how to find particular non-primary mac address in an anet resource and set its properties. Please note this example is supposed to work on solaris-kz branded zones only. Example 12. Setting mac-address property of a non-primary mac in anet ... anet = zone0.getResources(zbind.Resource('anet', [zbind.Property('id', '0')])) macs = zone0.getResources(zbind.Resource('mac', [zbind.Property('id', '1')]), anet[0]) zone0.setResourceProperties(macs[0], [zbind.Property('mac-address', '0:8:20:9e:eb:8c')]) Arguments: filter properties Error: Result clearResourceProperties(Resource filter, string[] properties) Clear property values of given resource. This method can fail with RESOURCE_NOT_FOUND if the filter does not match any resource or RESOURCE_TOO_MANY if more than one resource matches. The PROPERTY_UNKNOWN error can be returned if a property of the given name did not exist in that particular resource and the INVALID_ARGUMENT error can be returned if the properties argument is an empty list. A NOT_EDITING error can be returned if editConfig() has not yet been called successfully. Arguments: filter properties -- Names of the properties to clear. Error: Result Result apply(string[] options) Apply configuration to the running zone. Can fail with INVALID_ZONE_STATE if the zone is not running. Arguments: options (nullable) -- Command options as described in zoneadm(1m). Result: Result Error: Result Result attach(string[] options) Attach a zone This method is equivalent to using zoneadm(1M) attach on a zone. Arguments: options (nullable) -- Command options. Result: Result Error: Result Result boot(string[] options) Boot a zone This method is equivalent to using zoneadm(1M) boot on a zone. Arguments: options (nullable) -- Command options. Result: Result Error: Result Result clone(string[] options) Clone a zone This method is equivalent to using zoneadm(1M) clone on a zone. Arguments: options (nullable) -- Command options. Result: Result Error: Result Result detach(string[] options) Detach a zone This method is equivalent to using zoneadm(1M) detach on a zone. Arguments: options (nullable) -- Command options. Result: Result Error: Result Result halt(string[] options) Halt a zone This method is equivalent to using zoneadm(1M) halt on a zone. Arguments: options (nullable) Result: Result Error: Result Result install(string[] options) Install a zone This method is equivalent to using zoneadm(1M) install on a zone. Arguments: options (nullable) Result: Result Error: Result Result mark(string[] options) Mark a zone incomplete This method is equivalent to using zoneadm(1M) mark on a zone. Arguments: options (nullable) Result: Result Error: Result Result migrate(string[] options) Migrate a zone to a different system. This method is equivalent to using zoneadm(1M) migrate on a zone. Note that the RAD URI specified must not require interactive authentication (e.g. a password prompt). Available since version 1.1. Arguments: options (nullable) -- Command options. Result: Result Error: Result Result move(string[] options) Move a zone This method is equivalent to using zoneadm(1M) move on a zone. Arguments: options (nullable) Result: Result Error: Result Result rename(string[] options) Rename a zone This method is equivalent to using zoneadm(1M) rename on a zone. Arguments: options (nullable) -- Command options. Result: Result Error: Result Result ready(string[] options) Ready a zone This method is equivalent to using zoneadm(1M) ready on a zone. Arguments: options (nullable) Result: Result Error: Result Result reboot(string[] options) Reboot a zone This method is equivalent to using zoneadm(1M) reboot on a zone. Arguments: options (nullable) Result: Result Error: Result Result savecore(string[] options) Save crash dump of a zone This method is equivalent to using zoneadm(1M) savecore on a zone. Arguments: options (nullable) Result: Result Error: Result Result shutdown(string[] options) Shutdown a zone This method is equivalent to using zoneadm(1M) shutdown on a zone. Arguments: options (nullable) Result: Result Error: Result Result suspend(string[] options) Suspend a zone This method is equivalent to using zoneadm(1M) suspend on a zone. Arguments: options (nullable) Result: Result Error: Result Result uninstall(string[] options) Uninstall a zone This method is equivalent to using zoneadm(1M) uninstall on a zone. Arguments: options (nullable) Result: Result Error: Result Result verify(string[] options) Verify a zone This method is equivalent to using zoneadm(1M) verify on a zone. Arguments: options (nullable) -- Command options Result: Result Error: Result Zone Events ConfigChange configChange ENUMERATED TYPES enum ErrorCode Errors NONE (0) No error FRAMEWORK_ERROR (1) An error occurred within the RAD framework SNAPSHOT_ERROR (2) The user accesses the zone configuration details through a snapshot. This snapshot is captured when the user references a Zone instance. If the framework detects that the user intends to perform an operation that would be inconsistent with external changes made after the creation of the snapshot, the operation fails and this error is returned. COMMAND_ERROR (3) An error occurred in the requested operation RESOURCE_ALREADY_EXISTS (4) Resource cannot be added because the resource already exists. RESOURCE_NOT_FOUND (5) Unable to find a resource matching given filter. RESOURCE_TOO_MANY (6) If the filter provided matches more than one resource, this error can be returned by methods that operate on one particular resource. RESOURCE_UNKNOWN (7) The resource of the particular type is not known. ALREADY_EDITING (8) This error is returned by editConfig() when there was a prior call to editConfig(), and an active zone configuration editing session still exists. The session has not been cancelled by cancelConfig(), or committed by a successful commitConfig() call. PROPERTY_UNKNOWN (9) The property does not exist in the particular resource. NOT_EDITING (10) Calling configuration modification methods is not allowed outside of transaction. SYSTEM_ERROR (11) -- System error. This error code is a result of an error in a low-level system component or library where it's impractical to expose that particular error code through the Zone interface. Detailed information about the error, if available, will be made available through str field of the Result structure. INVALID_ARGUMENT (12) Invalid method argument(s). INVALID_ZONE_STATE (13) This error is raised in case Live Zone Reconfiguration mode was requested, but the zone in question wasn't running. enum PropertyValueType The type of property. PROP_COMPLEX is obsolete and is never used. PROP_SIMPLE (0) PROP_LIST (1) PROP_COMPLEX (2) STRUCTURE TYPES struct Result -- An error occurred for the given operation. Example 13. Retrieve an error information from the structure. import rad.client as rad ... try: test0.cancelConfig() except rad.ObjectError as e: result = e.get_payload() print("Result.code = %s" % result.code) Fields: ErrorCode code (nullable) -- See ErrorCode structure help for description of individual error codes. string str (nullable) -- String representation of the actual error possibly including the information gathered from the low-level error. string stdout (nullable) -- Contents of the standard output of a subprocess. See help for a given method for more information about whether stdout contents is set. string stderr (nullable) -- Contents of the standard error of a subprocess. See help for a given method for more information about whether stderr contents is set. struct ConfigChange The payload of a configChange event. Fields: string zone struct StateChange The payload of a stateChange event. Fields: string zone string oldstate string newstate struct Property A Resource property. complexvalue is obsolete and never used. Fields: string name string value (nullable) PropertyValueType type (nullable) string[] listvalue (nullable) string[] complexvalue (nullable) struct Resource -- A zone resource. This structure is used for storing information about an individual zone configuration resource. The structure can also be used for filtering resources in methods such as getResources(), removeResources(), getResourceProperties() and setResourceProperties. The rules for matching individual configuration resources are as follows: 1. Resources are matched based on the filter's type attribute first. 2. If the properties attribute of the filter is NULL (or is an empty array), then no additional filtering is done. 3. If the properties attribute is a non-empty array of property elements, the resource is first checked to determine if it contains a property of this name. Then a check is performed to confirm that the property simple value matches (that is, the value attribute of the property in the filter object is not NULL) 4. Step 3 is evaluated for each Property in the filter object. If all checks evaluate to true (that is, property is present and possibly has the requested value if specified in the filter object), then the Resource is added to the list of matches. See examples and specific documentation for individual methods which accept Resource as filter argument. Fields: string type Property[] properties (nullable) string parent (nullable) -- Private implementation detail to supported hierarchically nested resources. Version: (1.2) ATTRIBUTES See attributes(5) for descriptions of the following attributes: +--------------------+-------------------------+ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | +--------------------+-------------------------+ |Availability | system/management/rad/* | +--------------------+-------------------------+ |Interface Stability | Private | +--------------------+-------------------------+ SEE ALSO rad(1M) SunOS 5.11 2017-05-17 ZONEMGR(3rad)