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)