def list_users(self, **kwargs):
"""
list user accounts
Args:
k: .master
"""
parse_api_params(kwargs)
return eva.users.list_users()
def list_notifiers(self, **kwargs):
"""
list notifiers
Args:
k: .master
"""
parse_api_params(kwargs)
result = []
for n in eva.notify.get_notifiers():
result.append(n.serialize())
return sorted(result, key=lambda k: k['id'])
def shutdown_core(self, **kwargs):
"""
shutdown the controller
Controller process will be exited and then (should be) restarted by
watchdog. This allows to restart controller remotely.
Args:
k: .master
"""
parse_api_params(kwargs)
os.system('touch {}/{}_reload'.format(eva.core.dir_var,
eva.core.product.code))
background_job(eva.core.sighandler_term)()
return True, api_result_accepted
def save(self, **kwargs):
"""
save database and runtime configuration
All modified items, their status, and configuration will be written to
the disk. If **exec_before_save** command is defined in the
controller's configuration file, it's called before saving and
**exec_after_save** after (e.g. to switch the partition to write mode
and back to read-only).
Args:
k: .sysfunc=yes
"""
parse_api_params(kwargs)
return eva.core.do_save()
def file_set_exec(self, **kwargs):
"""
set file exec permission
Args:
k: .master
.i: relative path (without first slash)
e: *false* for 0x644, *true* for 0x755 (executable)
"""
i, e = parse_api_params(kwargs, 'ie', 'SB')
self._check_file_name(i)
if not os.path.isfile(eva.core.dir_runtime + '/' + i):
raise self._file_not_found(i)
try:
if e: perm = 0o755
else: perm = 0o644
eva.core.prepare_save()
try:
os.chmod(eva.core.dir_runtime + '/' + i, perm)
finally:
eva.core.finish_save()
return True
except:
eva.core.log_traceback()
raise FunctionFailed
def file_put(self, **kwargs):
"""
put file to runtime folder
Puts a new file into runtime folder. If the file with such name exists,
it will be overwritten. As all files in runtime are text, binary data
can not be put.
Args:
k: .master
.i: relative path (without first slash)
m: file content
"""
i, m = parse_api_params(kwargs, 'im', 'Ss')
self._check_file_name(i)
try:
raw = '' if m is None else m
eva.core.prepare_save()
try:
with open(eva.core.dir_runtime + '/' + i, 'w') as fd:
fd.write(raw)
return True
finally:
eva.core.finish_save()
except:
eva.core.log_traceback()
raise FunctionFailed
def log_rotate(self, **kwargs):
"""
rotate log file
Equal to kill -HUP <controller_process_pid>.
Args:
k: .sysfunc=yes
"""
parse_api_params(kwargs)
try:
eva.core.reset_log()
except:
eva.core.log_traceback()
raise FunctionFailed
return True
def list_keys(self, **kwargs):
"""
list API keys
Args:
k: .master
"""
parse_api_params(kwargs)
result = []
for _k in eva.apikey.keys:
r = eva.apikey.serialized_acl(_k)
r['dynamic'] = eva.apikey.keys[_k].dynamic
result.append(r)
return sorted(sorted(result, key=lambda k: k['key_id']),
key=lambda k: k['master'],
reverse=True)
def setup_mode(self, **kwargs):
setup = parse_api_params(kwargs, ('setup', ), 'B')
if not config.api_setup_mode:
return False
if setup:
eva.core.setup_on(config.api_setup_mode)
else:
eva.core.setup_off()
return True
def get_user(self, **kwargs):
"""
get user account info
Args:
k: .master
.u: user login
"""
u = parse_api_params(kwargs, 'u', 'S')
return eva.users.get_user(u)
def destroy_user(self, **kwargs):
"""
delete user account
Args:
k: .master
.u: user login
"""
u = parse_api_params(kwargs, 'u', 'S')
tokens.remove_token(user=u)
return eva.users.destroy_user(u)
def destroy_key(self, **kwargs):
"""
delete API key
Args:
k: .master
.i: API key ID
"""
i = parse_api_params(kwargs, 'i', 'S')
tokens.remove_token(key_id=i)
return eva.apikey.delete_api_key(i)
def set_user_key(self, **kwargs):
"""
assign API key to user
Args:
k: .master
.u: user login
a: API key to assign (key id, not a key itself)
"""
u, a = parse_api_params(kwargs, 'ua', 'SS')
tokens.remove_token(user=u)
return eva.users.set_user_key(u, a)
def set_user_password(self, **kwargs):
"""
set user password
Args:
k: .master
.u: user login
p: new password
"""
u, p = parse_api_params(kwargs, 'up', 'SS')
tokens.remove_token(user=u)
return eva.users.set_user_password(u, p)
def get_notifier(self, **kwargs):
"""
get notifier configuration
Args:
k: .master
.i: notifier ID
"""
i = parse_api_params(kwargs, 'i', 'S')
try:
return eva.notify.get_notifier(i, get_default=False).serialize()
except:
raise ResourceNotFound
def set_cvar(self, **kwargs):
"""
set the value of user-defined variable
Args:
k: .master
.i: variable name
Optional:
v: variable value (if not specified, variable is deleted)
"""
i, v = parse_api_params(kwargs, 'iv', 'S.')
return eva.core.set_cvar(i, v)
def notify_leaving(self, **kwargs):
"""
notify cloud about leaving. event will be sent at server restart
Args:
k: .master
.i: notifier ID
"""
i = parse_api_params(kwargs, 'i', 's')
n = eva.notify.get_notifier(i)
if not n:
raise ResourceNotFound
eva.notify.mark_leaving(n)
return True
def regenerate_key(self, **kwargs):
"""
regenerate API key
Args:
k: .master
.i: API key ID
Returns:
JSON dict with new key value in "key" field
"""
i, save = parse_api_params(kwargs, 'iS', 'Sb')
tokens.remove_token(key_id=i)
return eva.apikey.regenerate_key(i, save)
def log_critical(self, **kwargs):
"""
put critical message to log file
An external application can put a message in the logs on behalf of the
controller.
Args:
k: .sysfunc=yes
m: message text
"""
m = parse_api_params(kwargs, 'm', '.')
if m: logging.critical(m)
return True
def set_key_prop(self, **kwargs):
"""
set API key permissions
Args:
k: .master
.i: API key ID
p: property
v: value (if none, permission will be revoked)
save: save configuration immediately
"""
i, p, v, save = parse_api_params(kwargs, 'ipvS', 'SS.b')
tokens.remove_token(key_id=i)
key = eva.apikey.keys_by_id.get(i)
if not key: raise ResourceNotFound
return key.set_prop(p, v, save)
def lock(self, **kwargs):
"""
acquire lock
Locks can be used similarly to file locking by the specific process.
The difference is that SYS API tokens can be:
* centralized for several systems (any EVA server can act as lock
server)
* removed from outside
* automatically unlocked after the expiration time, if the initiator
failed or forgot to release the lock
used to restrict parallel process starting or access to system
files/resources. LM PLC :doc:`macro</lm/macros>` share locks with
extrnal scripts.
.. note::
Even if different EVA controllers are working on the same server,
their lock tokens are stored in different bases. To work with the
token of each subsystem, use SYS API on the respective
address/port.
Args:
k: .allow=lock
.l: lock id
Optional:
t: maximum time (seconds) to acquire lock
e: time after which lock is automatically released (if absent,
lock may be released only via unlock function)
"""
l, t, e = parse_api_params(kwargs, 'lte', 'S.n',
{'t': eva.core.config.timeout})
if not l in locks:
locks[l] = threading.Lock()
logging.debug(
'acquiring lock %s, timeout = %s, expires = %s' % \
(l, t, e))
if not locks[l].acquire(timeout=t):
raise FunctionFailed('Unable to acquire lock')
if e:
lock_expire_time[l] = time.time() + e
return True
def user_set(self, **kwargs):
"""
.set user property
Args:
k: .master
.u: user login
p: property (password or key)
v: value
"""
u, p, v = parse_api_params(kwargs, 'upv', 'SSS')
tokens.remove_token(user=u)
if p == 'password':
return eva.users.set_user_password(u, v)
elif p == 'key':
return eva.users.set_user_key(u, v)
else:
raise InvalidParameter('Property unknown: {}'.format(p))
def get_lock(self, **kwargs):
"""
get lock status
Args:
k: .allow=lock
.l: lock id
"""
l = parse_api_params(kwargs, 'l', 'S')
try:
result = format_resource_id('lock', l)
result['locked'] = locks[l].locked()
return result
except KeyError:
raise ResourceNotFound
except Exception as e:
raise
raise FunctionFailed(e)
def create_user(self, **kwargs):
"""
create user account
.. note::
All changes to user accounts are instant, if the system works in
read/only mode, set it to read/write before performing user
management.
Args:
k: .master
.u: user login
p: user password
a: API key to assign (key id, not a key itself)
"""
u, p, a = parse_api_params(kwargs, 'upa', 'SSS')
return eva.users.create_user(u, p, a)
def list_key_props(self, **kwargs):
"""
list API key permissions
Lists API key permissons (including a key itself)
.. note::
API keys, defined in etc/<controller>_apikeys.ini file can not be
managed with API.
Args:
k: .master
.i: API key ID
save: save configuration immediately
"""
i = parse_api_params(kwargs, 'i', 'S')
key = eva.apikey.keys_by_id.get(i)
return None if not key or not key.dynamic else key.serialize()
def create_key(self, **kwargs):
"""
create API key
API keys are defined statically in etc/<controller>_apikeys.ini file as
well as can be created with API and stored in user database.
Keys with master permission can not be created.
Args:
k: .master
.i: API key ID
save: save configuration immediately
Returns:
JSON with serialized key object
"""
i, save = parse_api_params(kwargs, 'iS', 'Sb')
return eva.apikey.add_api_key(i, save)
def disable_notifier(self, **kwargs):
"""
disable notifier
.. note::
The notifier is disabled until controller restart. To disable
notifier permanently, use notifier management CLI.
Args:
k: .master
.i: notifier ID
"""
i = parse_api_params(kwargs, 'i', 'S')
try:
eva.notify.get_notifier(i).enabled = False
except:
raise ResourceNotFound
return True
def set_debug(self, **kwargs):
"""
switch debugging mode
Enables and disables debugging mode while the controller is running.
After the controller is restarted, this parameter is lost and
controller switches back to the mode specified in the configuration
file.
Args:
k: .master
debug: true for enabling debug mode, false for disabling
"""
debug = parse_api_params(kwargs, ('debug', ), 'B')
if debug:
eva.core.debug_on()
else:
eva.core.debug_off()
return True
def file_get(self, **kwargs):
"""
get file contents from runtime folder
Args:
k: .master
.i: relative path (without first slash)
"""
i = parse_api_params(kwargs, 'i', 'S')
self._check_file_name(i)
if not os.path.isfile(eva.core.dir_runtime + '/' + i):
raise self._file_not_found(i)
try:
i = eva.core.dir_runtime + '/' + i
with open(i) as fd:
data = fd.read()
return data, os.access(i, os.X_OK)
except:
eva.core.log_traceback()
raise FunctionFailed
def unlock(self, **kwargs):
"""
release lock
Releases the previously acquired lock.
Args:
k: .allow=lock
.l: lock id
"""
l = parse_api_params(kwargs, 'l', 'S')
logging.debug('releasing lock %s' % l)
try:
locks[l].release()
return True
except RuntimeError:
return True
except KeyError:
raise ResourceNotFound
except Exception as e:
raise FunctionFailed(e)
