1.1. Description
Allocate a host to a user. Hosts must be in the Free state to be allocated, although users with Project Admin access can re-allocate hosts which are in the Allocated state to other users in their project. Domain Admin users can re-allocate machines between projects and users, although if a machine is reallocated to a user in another project, that user must also be a member of the destination project. The user must be authorized to allocate the host. The host must also not be in any of the following states: Immutable, Powercycle, Rebuild, or Rebuilding, or this method will fail.
1.2. URL
/cubit_api/1/alloc_host
1.3. Authentication
This method requires authentication using an API key.
1.4. Parameters
alloc_minutes ( zero or once )
Number of minutes for which to allocate the host. Must be a positive integer. If this parameter is
not specified, the host is allocated for an indefinite duration.
Type: Integer
alloc_proj ( zero or once )
The project to allocate the machine to. The alloc_user must be a valid CUBiT user in the project,
or else this method will fail. Only Domain Admins can change the project that a host is assigned to.
If not specified, the project is not changed. At least one of alloc_user or alloc_proj must
be specified.
Type: String
alloc_user ( zero or once )
Login name of user to allocate host to. Only Project Admins or better can specify a user other than
themselves. Other users can only allocate machines to themselves. If not specified, defaults to userid.
At least one of alloc_user or alloc_proj must be specified.
Type: String
force ( zero or once )
If the machine is currently in the Allocated state, the force option must be given to reassign the
host to another user. The force option is only available to Project Admins and above.
If the host is a virtual host, and any virtual guests of this host are in the Allocated state,
this option must also be used, or the entire allocation will fail. The only valid value for
this parameter is True.
Type: String
guests ( zero or once )
If the machine is a virtual host and has active virtual guests, setting this parameter to
True will move the virtual guests along with the virtual host. Because moving a virtual host
will move several hosts at once, we have a separate parameter to confirm this action.
The only valid value for this parameter is True. If the host has no virtual guests,
this option has no effect.
Type: String
host ( Required, once )
Fully qualified hostname to allocate.
Type: String
sig ( Required, once )
API authentication hash signature.
Type: String
userid ( Required, once )
The login name of the user initiating the request.
Type: String
1.5. Example Response
Successful host allocation:
<?xml version='1.0'?>
<cubit version='1'>
<status>OK</status>
</cubit>
If the user is unauthorized, or the host does not exist:
<?xml version='1.0'?>
<cubit version='1'>
<error>You are not authorized to allocate this host.</error>
</cubit>
If the host is allocated to a deleted project:
<?xml version='1.0'?>
<cubit version='1'>
<error>Cannot allocate host 'cu001.dev.cubitdemo.net' to a
deleted project 'look'</error>
</cubit>
1.6. Response Codes
- 200 - ok
- 400 - Login failed / Insufficient permissions
