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)