zonesbridge-1 - global zone connectivity
#include <rad/client/1/zonesbridge.h> cc [ flag... ] file... -lzonesbridge1_client [ library... ] interface IO rc_err_t zonesbridge_IO_available(rc_instance_t *inst, long long token, int *result, zonesbridge_ZonesBridgeError_t **error); rc_err_t zonesbridge_IO_close(rc_instance_t *inst, long long token, zonesbridge_ZonesBridgeError_t **error); rc_err_t zonesbridge_IO_openConsole(rc_instance_t *inst, const char *zone, long long *result, zonesbridge_ZonesBridgeError_t **error); rc_err_t zonesbridge_IO_openRad(rc_instance_t *inst, const char *zone, const char *user, long long *result, zonesbridge_ZonesBridgeError_t **error); rc_err_t zonesbridge_IO_read(rc_instance_t *inst, long long token, int nbyte, rc_opaque_t **result, zonesbridge_ZonesBridgeError_t **error); rc_err_t zonesbridge_IO_write(rc_instance_t *inst, long long token, const rc_opaque_t *buf, zonesbridge_ZonesBridgeError_t **error); interface Util rc_err_t zonesbridge_Util_getZones(rc_instance_t *inst, zonesbridge_ZoneState_t state, char ***result, int *result_cnt); Enumerated Types enum ZonesBridgeErrorCode typedef enum zonesbridge_ZonesBridgeErrorCode { ZZBEC_NONE = 0, ZZBEC_INVALID_TOKEN = 1, ZZBEC_INVALID_ZONE = 2, ZZBEC_INVALID_ZONE_PLATFORM = 3, ZZBEC_INVALID_ZONE_STATE = 4, ZZBEC_COMMAND_FAILED = 5, } zonesbridge_ZonesBridgeErrorCode_t; enum ZoneState typedef enum zonesbridge_ZoneState { ZZS_CONFIGURED = 0, ZZS_INCOMPLETE = 1, ZZS_INSTALLED = 2, ZZS_READY = 3, ZZS_RUNNING = 4, ZZS_SHUTTING_DOWN = 5, ZZS_DOWN = 6, ZZS_MOUNTED = 7, } zonesbridge_ZoneState_t; Structured Types struct ZonesBridgeError typedef struct zonesbridge_ZonesBridgeError zonesbridge_ZonesBridgeError_t; struct zonesbridge_ZonesBridgeError { zonesbridge_ZonesBridgeErrorCode_t zzbe_errorCode; }; void zonesbridge_ZonesBridgeError_free(zonesbridge_ZonesBridgeError_t *in);
ZONESBRIDGE-1(3rad) RAD Module Definitions ZONESBRIDGE-1(3rad) NAME zonesbridge - API for non-global zone connectivity SYNOPSIS #include <rad/client/1/zonesbridge.h> cc [ flag... ] file... -lzonesbridge1_client [ library... ] interface IO rc_err_t zonesbridge_IO_available(rc_instance_t *inst, long long token, int *result, zonesbridge_ZonesBridgeError_t **error); rc_err_t zonesbridge_IO_close(rc_instance_t *inst, long long token, zonesbridge_ZonesBridgeError_t **error); rc_err_t zonesbridge_IO_openConsole(rc_instance_t *inst, const char *zone, long long *result, zonesbridge_ZonesBridgeError_t **error); rc_err_t zonesbridge_IO_openRad(rc_instance_t *inst, const char *zone, const char *user, long long *result, zonesbridge_ZonesBridgeError_t **error); rc_err_t zonesbridge_IO_read(rc_instance_t *inst, long long token, int nbyte, rc_opaque_t **result, zonesbridge_ZonesBridgeError_t **error); rc_err_t zonesbridge_IO_write(rc_instance_t *inst, long long token, const rc_opaque_t *buf, zonesbridge_ZonesBridgeError_t **error); interface Util rc_err_t zonesbridge_Util_getZones(rc_instance_t *inst, zonesbridge_ZoneState_t state, char ***result, int *result_cnt); Enumerated Types enum ZonesBridgeErrorCode typedef enum zonesbridge_ZonesBridgeErrorCode { ZZBEC_NONE = 0, ZZBEC_INVALID_TOKEN = 1, ZZBEC_INVALID_ZONE = 2, ZZBEC_INVALID_ZONE_PLATFORM = 3, ZZBEC_INVALID_ZONE_STATE = 4, ZZBEC_COMMAND_FAILED = 5, } zonesbridge_ZonesBridgeErrorCode_t; enum ZoneState typedef enum zonesbridge_ZoneState { ZZS_CONFIGURED = 0, ZZS_INCOMPLETE = 1, ZZS_INSTALLED = 2, ZZS_READY = 3, ZZS_RUNNING = 4, ZZS_SHUTTING_DOWN = 5, ZZS_DOWN = 6, ZZS_MOUNTED = 7, } zonesbridge_ZoneState_t; Structured Types struct ZonesBridgeError typedef struct zonesbridge_ZonesBridgeError zonesbridge_ZonesBridgeError_t; struct zonesbridge_ZonesBridgeError { zonesbridge_ZonesBridgeErrorCode_t zzbe_errorCode; }; void zonesbridge_ZonesBridgeError_free(zonesbridge_ZonesBridgeError_t *in); DESCRIPTION API com.oracle.solaris.rad.zonesbridge [1] This API provides rad(8) client connectivity to a non-global zone through its global zone. Two modes of connectivity are provided: 1. access to the non-global zone's local RAD agent Using the openRad method, clients can connect to a local rad(8) daemon running on a non-global zone, through an established, authenticated RAD connection to its global zone. This mode of connectivity is useful when a non-global zone: o has no network connectivity, or o has no dedicated management network interface, and chooses not to expose a remote rad(8) daemon on its service network 2. access to the non-global zone's console Using the openConsole method, RAD clients can access the consoles of non-global zones on the connected host. INTERFACES interface IO primary API for non-global zone connectivity The io interface provides connectivity to a zone. Handles to this type of object can be retrieved from the RAD server using an object name built with: 1. the "com.oracle.solaris.rad.zonesbridge" domain name 2. a key named "type" paired with a value of "IO" IO Methods rc_err_t zonesbridge_IO_available(rc_instance_t *inst, long long token, int *result, zonesbridge_ZonesBridgeError_t **error); get the number of bytes available Gets the number of bytes available to be read, without blocking, on the connection identified by the given token. Arguments: inst -- RAD instance token -- the token identifying the open connection to query, as returned by openRad or openConsole result -- a non-negative integer error rc_err_t zonesbridge_IO_close(rc_instance_t *inst, long long token, zonesbridge_ZonesBridgeError_t **error); close a rad connection Close a connection previously opened by openRad. Arguments: inst -- RAD instance token -- the token identifying the open connection to close, as returned by openRad or openConsole error rc_err_t zonesbridge_IO_openConsole(rc_instance_t *inst, const char *zone, long long *result, zonesbridge_ZonesBridgeError_t **error); open a connection to the console of the given non-global zone openConsole can be used to connect to a non-global zone's console: Unlike openRad, openConsole does not require a rad(8) daemon to be running on the non-global zone. Connecting to a zone's console requires the solaris.zone.manage/zonename authorization. Note that a zone's console is an exclusive resource that prohibits multiple simultaneous connections. Arguments: inst -- RAD instance zone -- the non-global zone to connect to result -- a token used to read from and write to the console error rc_err_t zonesbridge_IO_openRad(rc_instance_t *inst, const char *zone, const char *user, long long *result, zonesbridge_ZonesBridgeError_t **error); open a connection to the rad server on the given non-global zone openRad is rarely invoked directly. Instead, a connection is usually established through the RAD infrastructure: Here, the radcon.connect_zone utility method plumbs the connection to the non-global zone using an established, authenticated connection to the global zone. zcon is now authenticated as the given zone user and can be used to interact with the non-global zone's rad(8) daemon. Note that, for simplicity of example, gcon is created via the standard unix domain socket, an automatically authenticated connection. Connections to remote hosts or through other transports must be authenticated beforeradcon.connect_zone is called. Connecting to a zone's rad(8) daemon requires the solaris.zone.manage/zonename authorization. Arguments: inst -- RAD instance zone -- the non-global zone to connect to user (nullable) -- the user (local to the given zone) to connect as (root if not specified) result -- a token used to read from and write to the new connection error rc_err_t zonesbridge_IO_read(rc_instance_t *inst, long long token, int nbyte, rc_opaque_t **result, zonesbridge_ZonesBridgeError_t **error); read data Read up to nbyte bytes from the connection identified by the given token. If nbyte is non-positive, no bytes are read and a zero-length array is returned. Otherwise, this method will block until at least one byte is read. Arguments: inst -- RAD instance token -- the token identifying the open connection to read from, as returned by openRad or openConsole nbyte -- a number identifying the maximum number of bytes to read result -- the read data, or null if the connection identified by the given token is open but the end of the data stream has been reached error rc_err_t zonesbridge_IO_write(rc_instance_t *inst, long long token, const rc_opaque_t *buf, zonesbridge_ZonesBridgeError_t **error); write data Write the given bytes to the connection identified by the given token. If that connection is open but the end of the data stream has been reached, the written data is silently discarded. Arguments: inst -- RAD instance token -- the token identifying the open connection to write to, as returned by openRad or openConsole buf -- the data to write error IO Retrieve rc_err_t zonesbridge_IO__rad_get_name(adr_name_t **result, int n, ...); Obtain RAD name of a IO object. Arguments: result -- RAD name n -- Number of key-value pairs provided as variadic arguments ... -- Optional key-value pairs that compose the primary key rc_err_t zonesbridge_IO__rad_lookup(rc_conn_t *c, boolean_t strict, rc_instance_t **result, int n, ...); Lookup a IO instance. Construct a RAD name for the interface based on the provided key-value pairs and perform a lookup. If successful, instance reference is returned in the result. Arguments: c -- RAD connection handle strict -- Strict (B_TRUE) or relaxed (B_FALSE) versioning result -- RAD instance n -- Number of key-value pairs provided as variadic arguments ... -- Optional key-value pairs that compose the primary key rc_err_t zonesbridge_IO__rad_list(rc_conn_t *c, boolean_t strict, adr_pattern_scheme_t scheme, adr_name_t ***result, int *result_count, int n, ...); List RAD names of a available IO instances. Returns an array and array size of matching object names. Arguments: c -- RAD connection handle strict -- Strict (B_TRUE) or relaxed (B_FALSE) versioning scheme -- Apply glob (NS_GLOB) or regex (NS_REGEX) matching result -- Array of RAD names result_count -- Number of names in result array n -- Number of key-value pairs provided as variadic arguments ... -- Optional key-value pairs that compose the primary key interface Util utility API for zone-related functionality The util interface provides utility methods related to zone connectivity. Handles to this type of object can be retrieved from the RAD server using an object name built with: 1. the "com.oracle.solaris.rad.zonesbridge" domain name 2. a key named "type" paired with a value of "Util" Util Methods rc_err_t zonesbridge_Util_getZones(rc_instance_t *inst, zonesbridge_ZoneState_t state, char ***result, int *result_cnt); get non-global zones in the given state Gets the names of the non-global zones in the given state. Arguments: inst -- RAD instance state -- the state of the returned zones result result_cnt -- Number of items in result array Util Retrieve rc_err_t zonesbridge_Util__rad_get_name(adr_name_t **result, int n, ...); Obtain RAD name of a Util object. Arguments: result -- RAD name n -- Number of key-value pairs provided as variadic arguments ... -- Optional key-value pairs that compose the primary key rc_err_t zonesbridge_Util__rad_lookup(rc_conn_t *c, boolean_t strict, rc_instance_t **result, int n, ...); Lookup a Util instance. Construct a RAD name for the interface based on the provided key-value pairs and perform a lookup. If successful, instance reference is returned in the result. Arguments: c -- RAD connection handle strict -- Strict (B_TRUE) or relaxed (B_FALSE) versioning result -- RAD instance n -- Number of key-value pairs provided as variadic arguments ... -- Optional key-value pairs that compose the primary key rc_err_t zonesbridge_Util__rad_list(rc_conn_t *c, boolean_t strict, adr_pattern_scheme_t scheme, adr_name_t ***result, int *result_count, int n, ...); List RAD names of a available Util instances. Returns an array and array size of matching object names. Arguments: c -- RAD connection handle strict -- Strict (B_TRUE) or relaxed (B_FALSE) versioning scheme -- Apply glob (NS_GLOB) or regex (NS_REGEX) matching result -- Array of RAD names result_count -- Number of names in result array n -- Number of key-value pairs provided as variadic arguments ... -- Optional key-value pairs that compose the primary key ENUMERATED TYPES enum ZonesBridgeErrorCode typedef enum zonesbridge_ZonesBridgeErrorCode { ZZBEC_NONE = 0, ZZBEC_INVALID_TOKEN = 1, ZZBEC_INVALID_ZONE = 2, ZZBEC_INVALID_ZONE_PLATFORM = 3, ZZBEC_INVALID_ZONE_STATE = 4, ZZBEC_COMMAND_FAILED = 5, } zonesbridge_ZonesBridgeErrorCode_t; ZZBEC_NONE (0) ZZBEC_INVALID_TOKEN (1) -- if the given token is invalid or refers to a closed connection ZZBEC_INVALID_ZONE (2) -- if the given zone is invalid ZZBEC_INVALID_ZONE_PLATFORM (3) -- if the given zone's platform is inappropriate for the requested platform-specific operation ZZBEC_INVALID_ZONE_STATE (4) -- if the given zone's state is inappropriate for the requested operation ZZBEC_COMMAND_FAILED (5) -- if a command to effect changes to or retrieve configuration from the system fails enum ZoneState typedef enum zonesbridge_ZoneState { ZZS_CONFIGURED = 0, ZZS_INCOMPLETE = 1, ZZS_INSTALLED = 2, ZZS_READY = 3, ZZS_RUNNING = 4, ZZS_SHUTTING_DOWN = 5, ZZS_DOWN = 6, ZZS_MOUNTED = 7, } zonesbridge_ZoneState_t; ZZS_CONFIGURED (0) ZZS_INCOMPLETE (1) ZZS_INSTALLED (2) ZZS_READY (3) ZZS_RUNNING (4) ZZS_SHUTTING_DOWN (5) ZZS_DOWN (6) ZZS_MOUNTED (7) STRUCTURED TYPES struct ZonesBridgeError typedef struct zonesbridge_ZonesBridgeError zonesbridge_ZonesBridgeError_t; struct zonesbridge_ZonesBridgeError { zonesbridge_ZonesBridgeErrorCode_t zzbe_errorCode; }; void zonesbridge_ZonesBridgeError_free(zonesbridge_ZonesBridgeError_t *in); Fields: zzbe_errorCode VERSION 1.0 ATTRIBUTES See attributes(7) for descriptions of the following attributes: +--------------------+-----------------------+ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | +--------------------+-----------------------+ |Availability | system/management/rad | +--------------------+-----------------------+ |Interface Stability | Private | +--------------------+-----------------------+ SEE ALSO rad(8) NOTES 1. Accessing Python documentation for this module: $ pydoc rad.bindings.com.oracle.solaris.rad.zonesbridge_1 Solaris 11.4 2017-02-01 ZONESBRIDGE-1(3rad)