From Zentific Wiki

Revision as of 21:02, 7 July 2010 by Mike (Talk | contribs)

(diff) ←Older revision | Current revision (diff) | Newer revision→ (diff)

Jump to: navigation, search

[edit] NameSpaces & Functions

[edit] Zentific

.hello() - used to perform basic check for the server. Should just return true. Clients can use it to see if the server is up.
.getConfig(key) - returns string: the config value for the given config option.
.getConfigPriv(key) - returns int: the privilege level required to see the config value for the given config option.
.setconfig(key, value) - returns boolean: sets a config entry for the given key to the given value
.getFrontendPlugins() - returns an array<string> of plugin names.
.modifyPlugin(string name, int enabled, int rpc, int frontend, int scheduler, int poller) - returns boolean. NOTE: using ints for param types until a possible bug with libzxr is resolved. will add a description field eventually.
.getAllPlugins() - returns an array<plugin>. Superuser gets enabled and disabled plugins, non-superusers receive only enabled plugins.

[edit] User

.getUser() - returns the user struct for the logged in user
.getUserByUID(int uid) - returns the user struct for the specified user id. Special Errors: InvalidIdentifier
.getUserByName(char name) - returns the user struct for the specified user name. Special Errors: InvalidIdentifier
.addUser(USER) - adds the new user to the database and returns boolean. Special Errors: InvalidIdentifier
.removeUser(UID) - removes the user from the database along with all privilege rules matching them
.getUsers() - returns an array of all UIDs. Only accessible by the SuperAdmin for Alpha (future delegation features will change this)
.getUserUID(char name) - requires superuser. returns a UID for the supplied username
.getUsername(int uid) - requires superuser. returns a name for the supplied UID
.isActive(int uid) - requires superuser. returns boolean
.isUser(char username) - requires superuser. returns boolean
.isSuperUser(int uid) - returns boolean
.isSuperUserByName(char name) - returns boolean
.setAttribute(char attribute, char value) - sets current user's data (possible attributes are type, name, active, uid). returns boolean
.setAttributeByUID(int uid, char attribute, char value) - sets user data (possible attributes are type, name, active, uid). returns boolean
.setPassword(char oldpass, char newpass) - allows user to change his/her password. valid oldpass required. returns boolean.
.setPasswordByUID(int uid, char newpass) - allows change of a specific user's password. specified by uid. superuser privilege required. returns boolean.
.login(char username, char password) - returns true or false regarding the success of the login. Special Errors: MaxLoginFailure
.logout() - logout for current user. returns boolean.
.logoutByUID() - forces logout for a specified user. returns boolean.
.addGroup(char name) - returns true or false for success of operation. Creates new group with given name
.groupExists(char name) - returns true or false for whether a user group with the given name exists or not
.removeGroup(char name) - returns true or false for success of operation.
.getGroups() - returns array of strings for all of the group names
.getGroupMembers(char name) - returns array of UIDs for all users in the given group
.addToGroup(uid user, char name) - adds the given user to the given group
.removeFromGroup(uid user, char name) - removes the given user from the given group
.renameGroup(char old_name, char new_name) - renames the group while maintaining all of the members
.getAlerts() - returns all alerts that are not marked as deleted that belong to the currently logged in user. An alert is a single element with properties of id (int), user (int, id of the user it is targeted for), acknowledged (boolean), deleted (boolean) and message (string).
.getAllAlerts() - admin only. Gets all alerts (deleted and not).

[edit] VM

.getVMs() - returns array of UUIDs that logged in user has access to
.getVMsFull() - returns array of VM structs for VMs that logged in user has access to. Functionally equivalent to calling getVMs and then calling getVM on each UUID.
.getVM(UUID) - returns a VM struct describing the specified VM
.getVMid(UUID) - returns int corresponding to the (non-unique, transient) id of the vm from the perspective of the virtualization platform. Special Errors: InvalidIdentifier
.getAllUsers(UUID) - returns array of user id's that have access to this VM as an admin or ROadmin. Special Errors: InvalidIdentifier
- SPECIAL REQUEST: make this return an array or object or something that tells me which access they have too (admin or ROadmin)
.getPrivilege(UUID, UID) - returns access level of the specified user to the specified VM. Special Errors: InvalidIdentifier
.grantPrivilege(UUID, UID, AccessLevel) - adds a rule that grants the given user access to the given VM at the given level. Special Errors: InvalidIdentifier
.grantGroupPrivilege(UUID, groupname, AccessLevel) - same as grantPrivilege but for groups
.revokePrivilege(UUID, UID, AccessLevel) - removes any rules that grant the given user access to the given VM at the given level. Special Errors: InvalidIdentifier
.revokeGroupPrivilege(UUID, groupname, AccessLevel) - same as removePrivilege but by group
.getVmParentNode(UUID) - returns parent node uuid. Special Errors: InvalidIdentifier.
.getVmParentAddress(UUID) - returns parent node id address. Special Errors: InvalidIdentifier
.getConsoleLockUsername(string uuid, string type) - returns name of user currently using the console. "Self" if calling user has another session open with another sessionid, name of locking user if calling user is privileged. note: will return name of another user (not the caller) only if that user has been delegated access rights to the vm. The second "type" parameter expects the type of console we want the lock information on and should be either the string "vnc" or the string "text". Special Errors: InvalidIdentifier
.getGraphicalConsolePort(string uuid) - returns port of currently active graphical console. note: requires (potentially delegated) access rights to the vm. NOTE: will need modification to support multiple frontend interface servers (current perspective operates upon the assumption of one host). Special Errors: InvalidIdentifier
.getTextConsolePort(string uuid) - returns port of currently active text console. note: requires (potentially delegated) access rights to the vm. NOTE: will need modification to support multiple frontend interface servers (current perspective operates upon the assumption of one host). Special Errors: InvalidIdentifier
.connectTextConsole(string uuid) - returns int == port number for connecting to console. Special Errors: InvalidIdentifier
.connectGraphicalConsole(string uuid) - returns int == port number for connecting to console. Special Errors: InvalidIdentifier
.disconnectTextConsole(string uuid) - returns boolean. Special Errors: InvalidIdentifier
.disconnectGraphicalConsole(string uuid) - returns boolean. Special Errors: InvalidIdentifier
.getVCPUs(string uuid) - returns int: number of virtual cpus assigned to the vm. Special Errors: InvalidIdentifier
.getVNCport(string uuid) - returns int: vnc console port number. not necessarily accessible; can be bound to localhost of parent node or otherwise firewalled - if not, accessible at parentnodehost:port. Special Errors: InvalidIdentifier
.getCPUtime(string uuid) - returns double: most recent observed value of vm's cpu time consumption. Special Errors: InvalidIdentifier
.getNETIFs(string uuid) - returns array of structs of type VIF: an array of virtual network interfaces; contains configuration data and most recent statistical values. Special Errors: InvalidIdentifier
.getNumNETIFs(string uuid) - returns int: number of virtual network interfaces currently associated with the given vm. Special Errors: InvalidIdentifier
.getDisks(string uuid) - returns array of structs of type DISK: an array of virtual disk devices; contains configuration data and most recent statistical values. Special Errors: InvalidIdentifier
.getNumDisks(string uuid) - returns int: number of virtual network interfaces currently associated with the given vm. Special Errors: InvalidIdentifier
.getMaxMemory(string uuid) - returns int: maximum amount of ram in kilobytes that can be assigned to the vm via ballooning. Special Errors: InvalidIdentifier
.getMemory(string uuid) - returns int: amount of ram in kilobytes assigned to the vm. Special Errors: InvalidIdentifier
.getUptime(string uuid) - returns int: current uptime in seconds. Special Errors: InvalidIdentifier

.getState(string uuid) - returns string: current state of the vm (s, c, p, d, b, r..) . Special Errors: InvalidIdentifier
.getType(string uuid) - returns string: type of virtual machine ('host', 'para', 'full', 'hybrid', 'other'), Special Errors: InvalidIdentifier
.getOS(string uuid) - returns string: observed os of vm. really only visible (right now) for xen paravirtual vms, using the 3.1 ABI and above. Special Errors: InvalidIdentifier
.getVNCpass(string uuid) - returns string: configured password for the vm vnc console. Special Errors: InvalidIdentifier
.getCPUpct(string uuid) - returns double: current CPU percent utilization (aggregate across all VCPUs). As with all such statistics may be outdated by some constant C equal to the polling period on the vm node. Special Errors: InvalidIdentifier
.getCPUpctHist(UUID) - returns double: array of CPU percentage values.
.getAvgCPUpct(UUID) - returns double: average value of CPU percentage.
.getUptimeStr(UUID) - returns string: localized string representation of the vm uptime (years, months, weeks, days, hours, minutes, seconds) since start date. Special Errors: InvalidIdentifier
.getTimeStarted(UUID) - returns string: localized string representation of the vm uptime (e.g. 4 months, 2 weeks, 3 days, 11 hours, 37 minutes, 53 seconds) since start date. Special Errors: InvalidIdentifier
.getTimeStarted(UUID) - returns string: localized string representation of the vm start time (e.g. 2008, May 12, 2:42PM). Special Errors: InvalidIdentifier
.getStateStr(UUID) - returns string: current state of the vm (shutdown, paused, dying, crashed, blocked/idle, running...). Special Errors: InvalidIdentifier
.saveConfig(VM) - returns boolean: save current VM config. Special Errors: InvalidIdentifier
.pause(UUID) - returns int: the job ID associated with the action to pause the given VM
.unpause(UUID) - returns int: the job ID associated with the action to unpause the given VM
.start(UUID) - returns int: the job ID associated with the action to create the given VM
.getNotes(UUID) - returns string: the string containing all user provided notes about the given VM
.saveNotes(string UUID, string notes) - returns boolean: saves user provided notes about the given VM
.getLog(UUID) - returns array<LOG>: array containing zentific log entries pertaining to the given VM (e.g. actions taken/observed)
.hasGraphicalConsole(uuid) - returns boolean; True if VM has graphical support (graphical frame buffer).
.hasTextConsole(uuid) - returns boolean; True if VM has support for serial / AJAX console.
.getSupportedConsoles(uuid) - returns array of strings; contains zero or more of 'text' and 'vnc'
.needsReboot(uuid) - returns a boolean flag indicating whether the VM needs to be rebooted for maintenance or update reasons
.getTemplates() - returns array<TEMPLATE> of available vm templates. Special Errors: InvalidIdentifier
.getTemplate(string name) - returns VM corresponding to requested vm templates. Special Errors: InvalidIdentifier
.addNetworkInterface(string uuid, NETIF vif) - adds an interface with the given options to the given vm. does NOT attach to a bridge. for that, use Network.attachVifToBridge() NOTE: Since we are approaching this from a cluster perspective, any VM that we migrate to a new node the administrator will need to ensure that a bridge with the same name exists on it. During install we will just list all of the bridges that exist on the Node that the VM is being deployed on initially.
.removeNetworkInterface(string uuid, string interfaceName) - remove the given interface from the given VM. QUESTION: should that be keyed off of MAC?

[edit] Node

.getNodes() - returns array of UUIDs to which the current user has access. TODO: privileges
.getNode(UUID) - returns a Node struct for the given UUID. Special Errors: InvalidIdentifier
.getAllUsers(UUID) - returns array of user id's that have access to this Node as an admin or ROAdmin. Special Errors: InvalidIdentifier
.getPrivilege(UUID, UID) - returns access level of the specified user to the specified Node. Special Errors: InvalidIdentifier
.grantPrivilege(UUID, UID, AccessLevel) - adds a rule that grants the given user access to the given Node at the given level. Special Errors: InvalidIdentifier
.revokePrivilege(UUID, UID, AccessLevel) - removes any rules that grant the given user access to the given Node at the given level. Special Errors: InvalidIdentifier
.enterMaintenanceMode(UUID) - suspend/pause/migrate all vms so that the host can be upgraded or repaired
.supportsHvm(UUID) - returns boolean if feature is available

[edit] Scheduler

.getJob(int) - returns job struct for provided jobid
.getJobs() - returns array<int> of job IDs
.getJobStatus(int) - returns int for status of provided job id
.getJobsStatus(Array<int>) - returns array of ints, 1 for each provided job id
.getJobsByUID(int) - returns array of job stucts associated with the given uid
.getJobsByUUID(strinng) - returns array of job stucts associated with the given uuid

[edit] Network

.getBridges(UUID) - returns an array of strings representing bridge names that are available on the specified node
.getBridge(uuid, name) - returns BRIDGE struct { id, name, node, description, vlans:array<int>, interface }. Interface is optional and is the name of the physical interface on the dom0 that the bridge is connected with. 'node' is the uuid of the node it is connected to.
.getNodeInterface(uuid, interfacename) - returns INTERFACE struct { nodeuuid, mac, ip, netmask, broadcast, mtu, rpackets, rerror, rdropped, rcollisions, rbytes, tpackets, terror, tdropped, tcollisions, tbytes, loopback, state, mode(promisc/not) }
.getNodeInterfaces(uuid) - returns array<string> of interface names
.createBridge(BRIDGE bridge) - pass it the new bridge object. Make sure that the node parameter of the bridge object is set. Admin Only.
.removeBridge(uuid, name) - uuid of a node, name of the bridge to remove.
.addVlan(uuid, bridgename, int vlanid) - assign a vlan to a bridge
.removeVlan(uuid, bridgename, int vlanid) - remove a vlan assignment from a bridge
.setDefaultBridge(uuid, bridgename) - superadmin only
.getDefaultBridge(uuid) - anybody can access. Returns bridge name
.getVmsByBridge(uuid, bridge_name) - get all of the Vms that are attached to the given bridge on the given node. This will allow us to destroy all interfaces attached to a bridge when we destroy a bridge and will also allow us to provide a "network" view to the user.
.isMacInUse(mac) - checks if their are any VIFs already set up with the given MAC address. returns boolean.
.generateMac() - generates a MAC address to use in a VIF. does checking in the background to make sure that no other colliding MAC exists.

[edit] Cluster

not implemented

[edit] Storage

.getLocations(uuid, mechanism) - takes the uuid of a node and a storage mechanism string ('lvm', 'phys', 'file', 'iscsi', etc) and generates a list of StorageLocation objects (id, title, hasObjects, allowNewObjects). For example, no phys mechanism will have hasObjects true because the location (e.g. /dev/sda) will be the last step in the lookup tree, whereas file based systems will because the you the "Location" is a folder and the objects would be files. allowNewObjects is only appropriate in conditions where hasObjects is true, and indicates whether users have to use only existing objects or whether they can create a new object in there.
.getObjects(uuid, string mechanism, int location) - takes the uuid of the node, the string name and the integer id of the location and lists all of the existing StorageObjects (id, location, name, shared, in_use, size, other) within that StorageLocation. "other" is used to specify special parameters. For example, a file can have an other "sparse" or "preallocated". "size" is a number and represents megabytes. "shared" is "none", "r", or "rw" to represent how this particular object can be shared between VMs
.getLocation(int id) - get a StorageLocation by it's unique ID
.getObject(int id) - get a StorageObject by it's unique ID

[edit] Values

UID - integer, user ID
UUID - Universally Unique Identifier, identifies virtual machine within a node and across a cluster. Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (36 characters including hyphens), [A-Fa-f0-9] Must be unique. Identifier for VMs and Nodes (and in time, storage/network)
AccessLevel - integer, represents SuperUser, Maintenance, Owner, Admin, ReadOnlyAdmin, None, or Node
JID - integer, identifies a job in the system

[edit] Types

Please see RPC API Types

[edit] Errors

NOT_AUTHORIZED

value: 1
meaning: user lacks sufficient privileges to call function

INVALID_SESSION

value: 2
meaning: user supplied non-existent or invalid session id

EXPIRED_SESSION

value: 3
meaning: time since last user's session refresh exceeded the configured timeout

VALID_SESSION

value: 4
meaning: the user's session is valid. an error condition unlikely to be thrown.
for steve's reference only. If you ever see this thrown as an exception then steve needs a flogging.

MAX_LOGIN_FAILURES

value: 5
meaning: user has exceeded the configured maximum number for authentication failures within the configured auth retry timeout.

INVALID_PARAMETER:

value:6
meaning: an invalid parameter was passed to the function throwing the error. (absent parameter, malformed parameter, out of bounds, etc). The error thrown will indicate the parameter in question. <MESSAGE type='INVALID_PARAMETER' param='uuid'>

DB_ERROR

value: 7
meaning: an error has occurred while interacting with the backend database. such errors may be database specific, are not exposed to the user, and can be found in server logs.

UNSPECIFIED_ERROR

value: 8
meaning: an unspecified error has occurred.

CONSOLE_LOCKED

value:9
meaning: the vm console is locked (used by another user). when thrown, call VM.getConsoleLockUsername for more information and VM.disconnectConsole to sever the existing connection.

SCHED_ERROR:

value:10
meaning: an interaction between the xmlrpc server and scheduler has failed (e.g. job insertion or signal dispatch to the scheduler).

VM_LOCKED:

value:11
meaning: the vm in question is locked by another user or the scheduler while it completes a task. this lock will be released upon completion. call VM.getVmLockReason for more information.

NO_ERROR:

value:100
meaning: no error condition has been encountered. an error condition unlikely to be thrown.
for steve's reference only. If you ever see this thrown as an exception then steve needs a flogging.

RPC API

From Zentific Wiki

Contents