def element_action(id, action, params=None): #@ReservedAssignment
"""
Performs an action on the element and possibly on its children too.
The actions that are supported by the element depend on the element
*type* and *state* and can be obtained using :py:func:`~element_info`.
Note that actions are not restricted to one element. Actions on a parent
element might (and in reality often will) also cover the child elements.
Parameter *id*:
The parameter *id* identifies the element by giving its unique id.
Parameter *action*:
The parameter *action* is the action to execute on the element.
Parameter *params*:
The parameters for the action (if needed) can be given as the parameter
*params*. This parameter must be a dict if given.
Return value:
The return value of this method is **not the info dict of the element**.
Instead this method returns the result of the action. Changes of the
action to the element can be checked using :py:func:`~element_info`.
Exceptions:
If the given element does not exist or belongs to another owner
an exception *element does not exist* is raised.
Various other exceptions can be raised, depending on the element type
and state.
"""
if not params: params = {}
elem = get_element_info(id)
getCurrentUserInfo().check_may_run_element_action(elem, action, params)
return elem.action(action, params)
def connection_action(id, action, params=None): #@ReservedAssignment
"""
Performs an action on the connection.
The actions that are supported by the connection depend on the connection
*state* and can be obtained using :py:func:`~connection_info`.
Parameter *id*:
The parameter *id* identifies the connection by giving its unique id.
Parameter *action*:
The parameter *action* is the action to execute on the connection.
Parameter *params*:
The parameters for the action (if needed) can be given as the parameter
*params*. This parameter must be a dict if given.
Return value:
The return value of this method is **not the info dict of the
connection**. Instead this method returns the result of the action.
Changes of the action to the connection can be checked using
:py:func:`~connection_info`.
Exceptions:
If the given connection does not exist or belongs to another owner
an exception *connection does not exist* is raised.
Various other exceptions can be raised, depending on the connection type
and state.
"""
if not params: params = {}
conn = get_connection_info(id)
getCurrentUserInfo().check_may_run_connection_action(conn, action, params)
return conn.action(action, params)
def debug_stats(tomato_module=Config.TOMATO_MODULE_BACKEND_API): getCurrentUserInfo().check_may_view_debugging_info() if is_self(tomato_module): return _debug_stats_withoutauth() else: api = get_tomato_inner_proxy(tomato_module) return api.debug_stats()
def errorgroup_list(show_empty=False):
"""
Returns a list of all error groups.
"""
getCurrentUserInfo().check_may_view_debugging_info()
return get_backend_debug_proxy().errorgroup_list(
show_empty, as_user=getCurrentUserInfo().get_username())
def debug_stats(tomato_module=Config.TOMATO_MODULE_BACKEND_API):
getCurrentUserInfo().check_may_view_debugging_info()
if is_self(tomato_module):
return _debug_stats_withoutauth()
else:
api = get_tomato_inner_proxy(tomato_module)
return api.debug_stats()
def connection_action(id, action, params=None): #@ReservedAssignment
"""
Performs an action on the connection.
The actions that are supported by the connection depend on the connection
*state* and can be obtained using :py:func:`~connection_info`.
Parameter *id*:
The parameter *id* identifies the connection by giving its unique id.
Parameter *action*:
The parameter *action* is the action to execute on the connection.
Parameter *params*:
The parameters for the action (if needed) can be given as the parameter
*params*. This parameter must be a dict if given.
Return value:
The return value of this method is **not the info dict of the
connection**. Instead this method returns the result of the action.
Changes of the action to the connection can be checked using
:py:func:`~connection_info`.
Exceptions:
If the given connection does not exist or belongs to another owner
an exception *connection does not exist* is raised.
Various other exceptions can be raised, depending on the connection type
and state.
"""
if not params: params = {}
conn = get_connection_info(id)
getCurrentUserInfo().check_may_run_connection_action(conn, action, params)
return conn.action(action, params)
def errordump_info(group_id, source, dump_id, include_data=False):
"""
Returns details for the given dump.
A dump is identified by its group_id, its source, and the dump_id on this source.
Parameter *group_id*:
A string. This is the group id of the dump group.
Parameter *source*:
A string. This is the source (i.e., a certain host, or the backend) of the dump.
Parameter *dump_id*:
The unique identifier of the dump to be queried.
Parameter *include_data*:
A boolean.
Every dump has environment data attached to it. This data may be big (i.e., >1MB).
By default, the data of a dump has most likely not been loaded from its source.
If include_data is False, this data will not be returned by this call.
If it is True, this data will first be fetched from the source, if needed, and included in this call's return.
Return value:
The return value of this method is the info dict of the dump.
If include_data is True, it will contain a data field, otherwise a data_available indicator.
"""
getCurrentUserInfo().check_may_view_debugging_info()
return get_backend_debug_proxy().errordump_info(group_id, source, dump_id, include_data)
def connection_modify(id, attrs): #@ReservedAssignment """ Modifies a connection, configuring it with the given attributes. The attributes that are supported by the connection depend on the connection *state* and can be obtained using :py:func:`~connection_info`. Additional to the attributes that are supported by the connection, all attributes beginning with an underscore (``_``) will be accepted. This can be used to store addition information needed by a frontend. Parameter *id*: The parameter *id* identifies the connection by giving its unique id. Parameter *attrs*: The attributes of the connection can be given as the parameter *attrs*. This parameter must be a dict of attributes. Return value: The return value of this method is the info dict of the connection as returned by :py:func:`connection_info`. This info dict will reflect all attribute changes. Exceptions: If the given connection does not exist or belongs to another owner an exception *connection does not exist* is raised. Various other exceptions can be raised, depending on the connection state. """ conn = get_connection_info(id) getCurrentUserInfo().check_may_modify_connection(conn) return conn.modify(attrs)
def errordump_info(group_id, source, dump_id, include_data=False):
"""
Returns details for the given dump.
A dump is identified by its group_id, its source, and the dump_id on this source.
Parameter *group_id*:
A string. This is the group id of the dump group.
Parameter *source*:
A string. This is the source (i.e., a certain host, or the backend) of the dump.
Parameter *dump_id*:
The unique identifier of the dump to be queried.
Parameter *include_data*:
A boolean.
Every dump has environment data attached to it. This data may be big (i.e., >1MB).
By default, the data of a dump has most likely not been loaded from its source.
If include_data is False, this data will not be returned by this call.
If it is True, this data will first be fetched from the source, if needed, and included in this call's return.
Return value:
The return value of this method is the info dict of the dump.
If include_data is True, it will contain a data field, otherwise a data_available indicator.
"""
getCurrentUserInfo().check_may_view_debugging_info()
return get_backend_debug_proxy().errordump_info(group_id, source, dump_id, include_data)
def element_action(id, action, params=None): #@ReservedAssignment
"""
Performs an action on the element and possibly on its children too.
The actions that are supported by the element depend on the element
*type* and *state* and can be obtained using :py:func:`~element_info`.
Note that actions are not restricted to one element. Actions on a parent
element might (and in reality often will) also cover the child elements.
Parameter *id*:
The parameter *id* identifies the element by giving its unique id.
Parameter *action*:
The parameter *action* is the action to execute on the element.
Parameter *params*:
The parameters for the action (if needed) can be given as the parameter
*params*. This parameter must be a dict if given.
Return value:
The return value of this method is **not the info dict of the element**.
Instead this method returns the result of the action. Changes of the
action to the element can be checked using :py:func:`~element_info`.
Exceptions:
If the given element does not exist or belongs to another owner
an exception *element does not exist* is raised.
Various other exceptions can be raised, depending on the element type
and state.
"""
if not params: params = {}
elem = get_element_info(id)
getCurrentUserInfo().check_may_run_element_action(elem, action, params)
return elem.action(action, params)
def topology_modify(id, attrs): #@ReservedAssignment """ Modifies a topology, configuring it with the given attributes. Currently the only supported attribute for topologies is ``name``. Additional to the attributes that are supported by the topology, all attributes beginning with an underscore (``_``) will be accepted. This can be used to store addition information needed by a frontend. Parameter *id*: The parameter *id* identifies the topology by giving its unique id. Parameter *attrs*: The attributes of the topology can be given as the parameter *attrs*. This parameter must be a dict of attributes. Return value: The return value of this method is the info dict of the topology as returned by :py:func:`topology_info`. This info dict will reflect all attribute changes. """ topl = get_topology_info(id) getCurrentUserInfo().check_may_modify_topology(topl) return topl.modify(attrs)
def debug_throw_error(tomato_module=None, data=None):
"""
throw an error that is then dumped.
:return:
"""
getCurrentUserInfo().check_allow_active_debugging()
if tomato_module is None:
tomato_module = Config.TOMATO_MODULE_BACKEND_API
UserError.check(tomato_module != Config.TOMATO_MODULE_BACKEND_ACCOUNTING,
code=UserError.INVALID_VALUE,
message="backend_accounting does not support dumps")
UserError.check(tomato_module in Config.TOMATO_BACKEND_MODULES,
code=UserError.INVALID_VALUE,
message="bad tomato module",
data={"tomato_module": tomato_module})
if is_self(tomato_module):
try:
InternalError.check(False,
code=InternalError.UNKNOWN,
message="Test Dump",
todump=True,
data=data)
except:
wrap_and_handle_current_exception(re_raise=True)
else:
get_tomato_inner_proxy(tomato_module).debug_throw_error(data=data)
def connection_modify(id, attrs): #@ReservedAssignment
"""
Modifies a connection, configuring it with the given attributes.
The attributes that are supported by the connection depend on the connection
*state* and can be obtained using :py:func:`~connection_info`.
Additional to the attributes that are supported by the connection,
all attributes beginning with an underscore (``_``) will be accepted.
This can be used to store addition information needed by a frontend.
Parameter *id*:
The parameter *id* identifies the connection by giving its unique id.
Parameter *attrs*:
The attributes of the connection can be given as the parameter *attrs*.
This parameter must be a dict of attributes.
Return value:
The return value of this method is the info dict of the connection as
returned by :py:func:`connection_info`. This info dict will reflect all
attribute changes.
Exceptions:
If the given connection does not exist or belongs to another owner
an exception *connection does not exist* is raised.
Various other exceptions can be raised, depending on the connection
state.
"""
conn = get_connection_info(id)
getCurrentUserInfo().check_may_modify_connection(conn)
return conn.modify(attrs)
def debug_debug_internal_api_call(_tomato_module,
_command,
args=None,
kwargs=None,
profile=True):
"""
debug an internal API call
use lib.debug.DebugResult.unmarshal on the result to get more functionality
:param _tomato_module:
:param _command:
:param args:
:param kwargs:
:param profile:
:return:
"""
getCurrentUserInfo().check_may_view_debugging_info()
if is_self(_tomato_module):
from .. import api
func = getattr(api, _command)
result = run(func, args, kwargs, profile)
return result.marshal()
else:
return get_tomato_inner_proxy(
_tomato_module).debug_debug_internal_api_call(_command,
args=None,
kwargs=None,
profile=True)
def topology_set_permission(id, user, role): #@ReservedAssignment """ Grants/changes permissions for a user on a topology. See :doc:`permissions` for further information about available roles and their meanings. You may not change your own role. Parameter *id*: The parameter *id* identifies the topology by giving its unique id. Parameter *user*: The name of the user. Parameter *role*: The name of the role for this user. If the user already has a role, if will be changed. """ if role is None: role = Role.null topl = get_topology_info(id) UserError.check(topl.exists(), code=UserError.ENTITY_DOES_NOT_EXIST, message="Topology with that name does not exist") UserError.check(get_backend_users_proxy().user_exists(user), code=UserError.ENTITY_DOES_NOT_EXIST, message="User with that name does not exist") UserError.check(topl.existsRole(role), code=UserError.INVALID_VALUE, message="Role with that name does not exist") getCurrentUserInfo().check_may_grant_permission_for_topologies(topl, role, user) return topl.set_permission(user, role)
def site_remove(name): """ Removes site with given name :param name: Name of the site which should be removed :return: null """ getCurrentUserInfo().check_may_delete_site(get_site_info(name)) return get_site_info(name).remove()
def organization_remove(name): """ Removes the organization with the given name, if no user and no site still exist which belong to this organization :param name: Name of the organization :return: null """ getCurrentUserInfo().check_may_delete_organization(name) get_organization_info(name).remove()
def organization_usage(name): #@ReservedAssignment """ Returns a list of usage measurements for an organization :param name: Name of the organization :return: List of usage measurements for the given organization """ getCurrentUserInfo().check_may_view_organization_usage(name) return get_organization_info(name).get_usage(hide_no_such_record_error=True)
def site_remove(name):
"""
Removes site with given name
:param name: Name of the site which should be removed
:return: null
"""
getCurrentUserInfo().check_may_delete_site(get_site_info(name))
return get_site_info(name).remove()
def host_users(name): """ List all user that are connected to an element running on the host :param name: Name of the host :return: List of users """ getCurrentUserInfo().check_may_list_host_users(get_host_info(name)) return get_backend_core_proxy().host_users(name)
def organization_remove(name): """ Removes the organization with the given name, if no user and no site still exist which belong to this organization :param name: Name of the organization :return: null """ getCurrentUserInfo().check_may_delete_organization(name) get_organization_info(name).remove()
def host_remove(name): """ Removes the host with the given name, if the host has no elements :param name: Name of the host to be removed """ host = get_host_info(name) getCurrentUserInfo().check_may_delete_host(host) host.remove()
def organization_modify(name, attrs): """ This function provides a convenient way of modifying attributes of an existing organization. :param name: Name of the organization which should be modified :param attrs: Dict with attributes that should be changed for the given organization :return: 'organization_info' of the organization with the provided name """ getCurrentUserInfo().check_may_modify_organization(name) return get_organization_info(name).modify(attrs)
def organization_modify(name, attrs): """ This function provides a convenient way of modifying attributes of an existing organization. :param name: Name of the organization which should be modified :param attrs: Dict with attributes that should be changed for the given organization :return: 'organization_info' of the organization with the provided name """ getCurrentUserInfo().check_may_modify_organization(name) return get_organization_info(name).modify(attrs)
def organization_usage(name): #@ReservedAssignment
"""
Returns a list of usage measurements for an organization
:param name: Name of the organization
:return: List of usage measurements for the given organization
"""
getCurrentUserInfo().check_may_view_organization_usage(name)
return get_organization_info(name).get_usage(
hide_no_such_record_error=True)
def host_usage(name): #@ReservedAssignment """ Returns a list of usage measurements for a specific host :param name: Name of the host :return: List of usage measurements for the given host """ host = get_host_info(name) getCurrentUserInfo().check_may_view_host_usage(host) return host.get_usage(hide_no_such_record_error=True)
def errorgroup_remove(group_id):
"""
Remove a dump.
Parameter *dump_id*:
The unique identifier of the group to be removed.
"""
getCurrentUserInfo().check_may_view_debugging_info()
get_backend_debug_proxy().errorgroup_remove(group_id)
def site_modify(name, attrs):
"""
Modifies the given attributes of the site with the given name
:param name: Name of the site which should be modified
:param attrs: Attributes which should be modified
:return: Site_info of the modified site
"""
getCurrentUserInfo().check_may_modify_site(get_site_info(name))
return get_site_info(name).modify(attrs)
def site_modify(name, attrs): """ Modifies the given attributes of the site with the given name :param name: Name of the site which should be modified :param attrs: Attributes which should be modified :return: Site_info of the modified site """ getCurrentUserInfo().check_may_modify_site(get_site_info(name)) return get_site_info(name).modify(attrs)
def debug_debug_internal_api_call(_tomato_module, _command, args=None, kwargs=None, profile=True): getCurrentUserInfo().check_may_view_debugging_info() if is_self(_tomato_module): from .. import api func = getattr(api, _command) result = run(func, args, kwargs, profile) return result.marshal() else: return get_tomato_inner_proxy(_tomato_module).debug_debug_internal_api_call(_command, args=None, kwargs=None, profile=True)
def errorgroup_remove(group_id):
"""
Remove a dump.
Parameter *dump_id*:
The unique identifier of the group to be removed.
"""
getCurrentUserInfo().check_may_view_debugging_info()
get_backend_debug_proxy().errorgroup_remove(group_id)
def errorgroup_favorite(group_id, is_favorite):
"""
Add or remove the group to favorites of the current user
:param group_id: group to add/remove
:param is_favorite: True to add, False to remove.
:return: None
"""
getCurrentUserInfo().check_may_view_debugging_info()
get_backend_debug_proxy().errorgroup_favorite(getCurrentUserInfo().get_username(), group_id, is_favorite)
def errorgroup_hide(group_id):
"""
Hide an errorgroup.
It will be shown as soon as a new dump is inserted.
:param group_id: the group ID
:return: None
"""
getCurrentUserInfo().check_may_view_debugging_info()
get_backend_debug_proxy().errorgroup_hide(group_id)
def errorgroup_hide(group_id):
"""
Hide an errorgroup.
It will be shown as soon as a new dump is inserted.
:param group_id: the group ID
:return: None
"""
getCurrentUserInfo().check_may_view_debugging_info()
get_backend_debug_proxy().errorgroup_hide(group_id)
def errorgroup_favorite(group_id, is_favorite):
"""
Add or remove the group to favorites of the current user
:param group_id: group to add/remove
:param is_favorite: True to add, False to remove.
:return: None
"""
getCurrentUserInfo().check_may_view_debugging_info()
get_backend_debug_proxy().errorgroup_favorite(getCurrentUserInfo().get_username(), group_id, is_favorite)
def debug_stats(tomato_module=Config.TOMATO_MODULE_BACKEND_API):
getCurrentUserInfo().check_may_view_debugging_info()
if is_self(tomato_module):
return {
"scheduler": scheduler.info(),
"threads": map(traceback.extract_stack, sys._current_frames().values())
}
else:
api = get_tomato_inner_proxy(tomato_module)
return api.debug_stats()
def host_modify(name, attrs): """ Modifies the host with the given name and the provided attributes :param name: Name of the host :param attrs: Attribute list to be changed :return: host info object of the modified host """ host = get_host_info(name) getCurrentUserInfo().check_may_modify_host(host) return host.modify(attrs)
def topology_info(id, full=False): #@ReservedAssignment
"""
Retrieves information about a topology.
Parameter *id*:
The parameter *id* identifies the topology by giving its unique id.
Parameter *full*:
If this parameter is ``True``, the fields ``elements`` and
``connections`` will be a list holding all information of
:py:func:`~backend.tomato.api.elements.element_info`
and :py:func:`~backend.tomato.api.connections.connection_info`
for each component.
Otherwise these fields will be lists holding only the ids of the
respective objects.
Return value:
The return value of this method is a dict containing information
about this topology:
``id``
The unique id of the topology.
``elements``
A list with all elements. Depending on the parameter *full* this list
includes the full information of the elements as given by
:py:func:`~backend.tomato.api.element.element_info` or only the id of the
element.
``connections``
A list with all connections. Depending on the parameter *full* this list
includes the full information of the connections as given by
:py:func:`~backend.tomato.api.connection.connection_info` or only the id
of the connection.
``attrs``
A dict of attributes of this topology. If this topology does not have
attributes, this field is ``{}``.
``usage``
The latest usage record of the type ``5minutes``. See
:doc:`/docs/accountingdata` for the contents of the field.
``permissions``
A dict with usernames as the keys and permission levels as values.
"""
topl = get_topology_info(id)
UserError.check(topl.exists(), code=UserError.ENTITY_DOES_NOT_EXIST, message="Topology with that name does not exist")
getCurrentUserInfo().check_may_view_topology(topl)
if full:
return get_backend_core_proxy().topology_info(id, full)
else:
return topl.info(update=True)
def errordumps_force_refresh():
"""
Force a refresh of dumps.
This is done automatically in a longer interval.
To get instant access to all dumps, call this function.
Return value:
The time in seconds it takes until all dumps should be collected.
"""
getCurrentUserInfo().check_may_view_debugging_info()
return get_backend_debug_proxy().errordumps_force_refresh()
def topology_create(): """ Creates an empty topology. Return value: The return value of this method is the info dict of the new topology as returned by :py:func:`topology_info`. This info dict also contains the topology id that is needed for further manipulation of that object. """ getCurrentUserInfo().check_may_create_topologies() return TopologyInfo.create(getCurrentUserName())
def debug_stats(tomato_module=Config.TOMATO_MODULE_BACKEND_API):
getCurrentUserInfo().check_may_view_debugging_info()
if is_self(tomato_module):
return {
"scheduler": scheduler.info(),
"threads": map(traceback.extract_stack,
sys._current_frames().values())
}
else:
api = get_tomato_inner_proxy(tomato_module)
return api.debug_stats()
def errordumps_force_refresh():
"""
Force a refresh of dumps.
This is done automatically in a longer interval.
To get instant access to all dumps, call this function.
Return value:
The time in seconds it takes until all dumps should be collected.
"""
getCurrentUserInfo().check_may_view_debugging_info()
return get_backend_debug_proxy().errordumps_force_refresh()
def account_send_notification(name, subject, message, ref=None, from_support=False, subject_group=None): """ Sends an email to the account and also sends a message via the internal message system :param str ref arbitrary string for referencing :param str subject_group arbitrary string to reference desired subject_group for this message """ if from_support: fromUser = None else: fromUser = getCurrentUserName() getCurrentUserInfo().check_may_send_message_to_user(get_user_info(name)) api = get_backend_users_proxy() api.send_message(name, subject, message, fromUser=fromUser, ref=ref, subject_group=subject_group)
def host_create(name, site, attrs=None): """ Used to create a host on the given site with the provided name :param name: Name of the host :param site: Name of the site, the host should be located at :param attrs: dict with at least two key, value pairs: 'rpcurl' like this: 'rpcurl': "ssl+jsonrpc://%s:8003" % host_address 'address' :return: Returns the host info of the newly created host """ site_info = get_site_info(site) getCurrentUserInfo().check_may_create_hosts(site_info) return HostInfo.create(name, site_info, attrs)
def site_create(name, organization, label="", attrs=None):
"""
Creates a site and returns site_info for the newly created site
:param name: Name for the new site. May not be a duplicate of an existing site
:param organization: The organization to which this site belongs
:param label: An optional label for this site
:param attrs: Optional attributes for this site
:return: Site_info for the newly created site
"""
if attrs is None: attrs = {}
getCurrentUserInfo().check_may_create_sites(organization)
return SiteInfo.create(name, organization, label, attrs)
def account_list(organization=None, with_flag=None):
"""
Retrieves information about all accounts.
Return value:
A list with information entries of all accounts. Each list entry contains
exactly the same information as returned by :py:func:`account_info`.
"""
if organization is None:
getCurrentUserInfo().check_may_list_all_users()
else:
getCurrentUserInfo().check_may_list_organization_users(organization)
return get_user_list(organization, with_flag)
def account_list(organization=None, with_flag=None): """ Retrieves information about all accounts. Return value: A list with information entries of all accounts. Each list entry contains exactly the same information as returned by :py:func:`account_info`. """ if organization is None: getCurrentUserInfo().check_may_list_all_users() else: getCurrentUserInfo().check_may_list_organization_users(organization) return get_user_list(organization, with_flag)
def site_create(name, organization, label="", attrs=None):
"""
Creates a site and returns site_info for the newly created site
:param name: Name for the new site. May not be a duplicate of an existing site
:param organization: The organization to which this site belongs
:param label: An optional label for this site
:param attrs: Optional attributes for this site
:return: Site_info for the newly created site
"""
if attrs is None: attrs = {}
getCurrentUserInfo().check_may_create_sites(organization)
return SiteInfo.create(name, organization, label, attrs)
def topology_usage(id): #@ReservedAssignment """ Retrieves aggregated usage statistics for a topology. Parameter *id*: The parameter *id* identifies the topology by giving its unique id. Return value: Usage statistics for the given topology according to :doc:`/docs/accountingdata`. """ target_topology = get_topology_info(id) getCurrentUserInfo().check_may_view_topology_usage(target_topology) return target_topology.get_usage(hide_no_such_record_error=True)
def topology_remove(id): #@ReservedAssignment """ Removes and empty topology. Return value: The return value of this method is ``None``. Exceptions: The topology must not contain elements or connections, otherwise the call will fail. """ topl = get_topology_info(id) getCurrentUserInfo().check_may_remove_topology(topl) topl.remove()
