zonesbridge - global zone connectivity
interface IO integer available(long token); close(long token); long openConsole(string zone); long openRad(string zone, string user); opaque read(long token, integer nbyte); write(long token, opaque buf); interface Util string[] getZones(ZoneState state);
ZONESBRIDGE(3rad) RAD Module Definitions ZONESBRIDGE(3rad)
NAME
zonesbridge - API for non-global zone connectivity
SYNOPSIS
interface IO
integer available(long token);
close(long token);
long openConsole(string zone);
long openRad(string zone,
string user);
opaque read(long token,
integer nbyte);
write(long token,
opaque buf);
interface Util
string[] getZones(ZoneState state);
DESCRIPTION
API com.oracle.solaris.rad.zonesbridge
This API provides rad(1m) 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(1m)
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(1m) 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
integer available(long token)
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:
token -- the token identifying the open connection to query, as
returned by openRad or openConsole
Result:
integer -- a non-negative integer
Error:
ZonesBridgeError
close(long token)
close a rad connection
Close a connection previously opened by openRad.
Arguments:
token -- the token identifying the open connection to close, as
returned by openRad or openConsole
Error:
ZonesBridgeError
long openConsole(string zone)
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:
Example 1. openConsole (Python)
import rad.client as radcli
import rad.connect as radcon
import rad.bindings.com.oracle.solaris.rad.zonesbridge as zbind
# Create a connection to the global zone
con = radcon.connect_unix()
# Get a native-looking python object that throws RAD exceptions
zio = con.get_object(zbind.IO())
# Open myzone's console
token = zio.openConsole("myzone")
# Monitor output on zone's console
while True:
input = zio.read(token, 1024)
if input is None:
break
print input,
Unlike openRad, openConsole does not require a rad(1m) 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:
zone -- the non-global zone to connect to
Result:
long -- a token used to read from and write to the console
Error:
ZonesBridgeError
long openRad(string zone, string user)
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:
Example 2. openRad (Python)
import rad.connect as radcon
# Create a connection to the global zone
gcon = radcon.connect_unix()
# Create a connection to zone "myzone" as user "talley"
# (if user is None or not specified, connect as root)
zcon = radcon.connect_zone(gcon, "myzone", "garypen")
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(1m) 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(1m) daemon requires the
solaris.zone.manage/zonename authorization.
Arguments:
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:
long -- a token used to read from and write to the new
connection
Error:
ZonesBridgeError
opaque read(long token, integer nbyte)
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:
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:
opaque (nullable) -- 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:
ZonesBridgeError
write(long token, opaque buf)
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:
token -- the token identifying the open connection to write to,
as returned by openRad or openConsole
buf -- the data to write
Error:
ZonesBridgeError
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
string[] getZones(ZoneState state)
get non-global zones in the given state
Gets the names of the non-global zones in the given state.
Arguments:
state -- the state of the returned zones
Result:
string[]
Error:
(no type)
ENUMERATED TYPES
enum ZonesBridgeErrorCode
NONE (0)
INVALID_TOKEN (1)
if the given token is invalid or refers to a closed connection
INVALID_ZONE (2)
if the given zone is invalid
INVALID_ZONE_PLATFORM (3)
if the given zone's platform is inappropriate for the requested
platform-specific operation
INVALID_ZONE_STATE (4)
if the given zone's state is inappropriate for the requested
operation
COMMAND_FAILED (5)
if a command to effect changes to or retrieve configuration
from the system fails
enum ZoneState
CONFIGURED (0)
INCOMPLETE (1)
INSTALLED (2)
READY (3)
RUNNING (4)
SHUTTING_DOWN (5)
DOWN (6)
MOUNTED (7)
STRUCTURE TYPES
struct ZonesBridgeError
Fields:
ZonesBridgeErrorCode errorCode
Version: (1.0)
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-31 ZONESBRIDGE(3rad)