lce_service.remote_toolbox package

Remote Toolbox Module.

This module provides the shared layer every API built on the platform’s Remote Toolbox uses to run a command on a Data Collector and read its output back.

A command is queued in the platform’s spool table and picked up by the Remote Toolbox on the collector, which polls the database for its work, runs the command without a shell, and writes its output back to a log table shared by every toolbox tool. That makes every run two steps rather than one: the queued command has to reach the collector through a database update before any output exists. This is the same path the platform’s own toolbox tools take, through device_tools_run.inc and json_tools.inc.

What this layer adds over the platform’s path is enforcement and interpretation. A queued command is attributed to the user who queued it and its output is readable only by that user and only through the API for its tool. A job’s phase is derived from both the spool row and the output, since the toolbox can lose either signal. And output is paged with bounded records, except for a framed payload, which is reassembled whole.

class lce_service.remote_toolbox.FramedPayload(text: str | None, chunk_count: int, irregular_chunks: List[int], error: str | None)

Bases: NamedTuple

A payload a command wrote to standard output as a series of marked chunks.

Variables:

text – The chunks joined back together, without their markers or line terminators, or None when no chunk was found or the payload could not be read.
chunk_count – How many chunks were found.
irregular_chunks – The 1-based positions of chunks whose length the writer could not have produced: any but the last that is not exactly the chunk size, or a last one longer than it. Any listed here means part of the payload was lost or mangled in transit, whether or not the text that remains still parses.
error – A description of why the payload could not be read, or None.

chunk_count: int: Alias for field number 1

error: str | None: Alias for field number 3

irregular_chunks: List[int]: Alias for field number 2

text: str | None: Alias for field number 0

exception lce_service.remote_toolbox.InvalidToolboxRequestError(message: str)

Bases: ValueError

Exception raised when a request cannot be turned into a safe Remote Toolbox command.

Each API built on the Remote Toolbox subclasses this for its own validation errors, so an endpoint can report any of them, including the ones raised by this shared layer, as bad input with a single handler.

Parameters:: message – A descriptive error message explaining which value was rejected and what shape was expected, suitable for returning to the caller.

Bases: NamedTuple

Where a queued Remote Toolbox command is in its life, and how long it has been there.

The phase is derived from the spool row and the output rows together, because neither is reliable on its own. The toolbox swallows a failure to write any of its rows, so a job can finish without its completed row ever being written, and the spool row and the output rows are pruned independently, so either can outlive the other.

No phase means “stuck”. A job the collector never picks up stays queued, and a job the toolbox abandons, as it does when it cannot decode the queued command, stays running, both indefinitely. The two ages are reported so the caller can decide when to give up; how long is too long depends on the tool and on how far the collector is from the database.

Variables:

phase – One of “queued”, “running”, “finished” or “unknown”. Unknown means there is no spool row to read and no output to infer anything from.
state – The spool row’s state as found, or None when there is no spool row.
returncode – The spool row’s return code as found, or None. It is the exit status of the command the toolbox ran, which for some tools is a wrapper that exits 0 whatever happened, so it is reported rather than interpreted.
seconds_since_queued – Seconds since the command was queued, or None.
seconds_since_last_output – Seconds since the job last wrote any output row, or None when it has written none. Every row counts, including any the caller’s reads leave out, since those are output too.
last_output_id – The id of the job’s last output row, or None when it has written none. Used to tell whether a reader has caught up with a finished job.
completed – Whether the job’s last output row is the completed row the toolbox writes after everything else.

as_dict() → Dict[str, Any]

Returns the progress as it is reported to a caller, without the internal cursor.

Returns:: A dictionary of the phase, the raw spool fields and the two ages.

completed: bool: Alias for field number 6

last_output_id: int | None: Alias for field number 5

phase: str: Alias for field number 0

returncode: int | None: Alias for field number 2

seconds_since_last_output: int | None: Alias for field number 4

seconds_since_queued: int | None: Alias for field number 3

state: int | None: Alias for field number 1

class lce_service.remote_toolbox.LocalRun(rows: List[Dict[str, Any]], state: int, returncode: int | None, seconds_elapsed: int, seconds_since_last_output: int | None, timed_out: bool = False, output_limited: bool = False)

Bases: NamedTuple

The output and outcome of a Remote Toolbox command run on this host rather than queued.

The rows are the ones the Remote Toolbox would have written to the output table for the same command, numbered from one, so the readers that page, stitch and reassemble queued output read a local run by exactly the same rules.

Variables:

rows – The output rows in the order they were produced, each holding an id, a message type and a raw message.
state – The spool state the toolbox would have recorded: finished, or failed when the command could not be decoded or launched.
returncode – The command’s exit status, or None when it never ran or was killed.
seconds_elapsed – How long the run took.
seconds_since_last_output – How long before the run ended its last row was produced.
timed_out – Whether the command was killed for running past its timeout, in which case the rows end without the completed row.
output_limited – Whether the command wrote more than MAX_LOCAL_OUTPUT_BYTES, in which case every line past the limit was discarded.

framed_payload(marker: str, chunk_size: int, max_chars: int) → FramedPayload

Reassembles the payload the command wrote behind a marker, as read_framed_payload does.

Parameters:

marker – The marker that starts every chunk.
chunk_size – The length the writer cuts every chunk but the last to.
max_chars – The most characters of payload to reassemble.

Returns:

A FramedPayload.

output_limited: bool: Alias for field number 6

page(exclude_prefix: str | None = None) → OutputPage

Returns the whole run’s output as one page.

Every row is returned, since a local run has no request to page through later, but each record is still bounded as a queued run’s is, so the text is what a caller that read a queued run page by page would have joined together.

Parameters:: exclude_prefix – Leave out standard output rows starting with this marker, as a read of queued output does.
Returns:: An OutputPage holding every row, terminated unless the run timed out, and truncated when output past MAX_LOCAL_OUTPUT_BYTES was discarded.

progress(exclude_prefix: str | None = None) → JobProgress

Returns the run’s progress, as get_job_progress reports a queued run’s.

Parameters:: exclude_prefix – Leave out the same rows the page leaves out.
Returns:: A JobProgress for a run that has finished.

returncode: int | None: Alias for field number 2

rows: List[Dict[str, Any]]: Alias for field number 0

seconds_elapsed: int: Alias for field number 3

seconds_since_last_output: int | None: Alias for field number 4

state: int: Alias for field number 1

timed_out: bool: Alias for field number 5

exception lce_service.remote_toolbox.LocalRunLimitError(limit: int = 5)

Bases: RuntimeError

Exception raised when a local run is asked for while MAX_CONCURRENT_LOCAL_RUNS are running.

Parameters:: limit – The number of local runs that may execute at once.

class lce_service.remote_toolbox.OutputPage(lines: List[Dict[str, Any]], last_id: int, terminated: bool, truncated: bool, line_counts: Dict[str, int], chars: int = 0)

Bases: NamedTuple

One page of output from a queued Remote Toolbox command.

Variables:

lines – The output rows in the order the collector emitted them, each a dictionary holding the row id, the stream it came from and the decoded text.
last_id – The highest row id in this page, to be passed back as the cursor for the next page. Unchanged from the requested cursor when the page is empty.
terminated – True when the collector has finished running the command. This reports termination only and says nothing about whether the command succeeded.
truncated – True when this page did not exhaust the output that was available: more rows were waiting than the row budget allowed, or the records accepted reached the per response character cap with rows still left behind, or both. The caller should request the next page from last_id rather than assume the output ended.
line_counts – A count of rows per stream in this page.
chars – The characters the rows take in the JSON response, which a wait carries on from rather than encoding the rows again.

chars: int: Alias for field number 5

last_id: int: Alias for field number 1

line_counts: Dict[str, int]: Alias for field number 4

lines: List[Dict[str, Any]]: Alias for field number 0

terminated: bool: Alias for field number 2

truncated: bool: Alias for field number 3

exception lce_service.remote_toolbox.ToolboxJobNotAccessible(proc_id: int, message: str | None = None)

Bases: LookupError

Exception raised when a Remote Toolbox job cannot be read by the requesting user.

This error is deliberately raised with the same message for every reason a job is not readable: the job id was never issued, the job belongs to a different Remote Toolbox tool, the job was started by another user, or the job has no recorded owner at all. Distinguishing those cases would turn a read endpoint into an oracle for which job ids exist, and the rows it guards are shared with every other toolbox tool.

Parameters:

proc_id – The process id the caller asked for.
message – The message to report. Subclasses supply one naming what the caller asked for; it must not vary with the reason the job was refused.

lce_service.remote_toolbox.assert_job_readable(dbc: ~sl_mysql.silo_cursor.silo_cursor, proc_id: int, user: ~lce_service.sl1_models.User, tool_ids: ~typing.Set[int], not_accessible: ~typing.Type[~lce_service.remote_toolbox.core.ToolboxJobNotAccessible] = <class 'lce_service.remote_toolbox.core.ToolboxJobNotAccessible'>) → Dict[str, Any]

Verifies that a process id names a Remote Toolbox job of these tools that this user owns.

Two independent checks run here, in this order. The first confirms the job was queued as one of the tools the caller serves rather than some other Remote Toolbox tool, because the output table is shared by every tool and a rejected payload is echoed into it verbatim; without this check a caller walking process ids could read output belonging to a tool it was never granted. The second confirms the job belongs to the requesting user. The cheaper and broader check runs first so a mismatch is rejected before a second query is spent on the narrower one. The ownership row is matched on the job’s own tool, because every toolbox tool writes to that table, so an ownership row recorded for one tool can never authorise another.

Every rejection raises the same error with the same message, so the endpoint cannot be used to learn which process ids exist.

Parameters:

dbc – A silo_cursor instance used to read the spool and ownership rows.
proc_id – The process id returned when the command was queued.
user – The User instance requesting the output.
tool_ids – The Remote Toolbox tool ids the caller is allowed to read.
not_accessible – The ToolboxJobNotAccessible subclass to raise, so each API reports a refusal in its own terms.

Returns:

The job’s spool row, as get_job_status returns it, so the caller does not have to read it again.

Raises:

ToolboxJobNotAccessible – Raised, as the not_accessible type, when no such job exists, when the job belongs to a different Remote Toolbox tool, when the job has no recorded owner, or when the owner is another user.
DatabaseExecutionError – Raised when either check fails to execute.

lce_service.remote_toolbox.get_collecting_appliance(dbc: silo_cursor, appliance_identifier: Any) → Dict[str, Any]

Looks up a collecting appliance by numeric id or by name.

Only appliances that actually collect are returned. A Database Server is rejected even when the identifier matches, because a Remote Toolbox command queued against an appliance that does not collect is a command nothing runs.

Parameters:

dbc – A silo_cursor instance used to query the appliance table.
appliance_identifier – The numeric appliance id, or the appliance name.

Returns:

A dictionary holding the appliance id, name, ip and function.

Raises:

InvalidToolboxRequestError – Raised when the identifier is a value that is neither an id nor a name.
MissingResourceError – Raised when no collecting appliance matches the identifier.
DatabaseExecutionError – Raised when the appliance lookup fails to execute.

lce_service.remote_toolbox.get_collecting_appliances(dbc: silo_cursor) → List[Dict[str, Any]]

Lists every appliance that collects, and therefore runs Remote Toolbox commands.

A Database Server is excluded even though it is an appliance, because it does not collect and a command queued against one would never run.

Parameters:: dbc – A silo_cursor instance used to query the appliance table.
Returns:: One dictionary per collecting appliance, holding its id, name, ip and function, ordered by name.
Raises:: DatabaseExecutionError – Raised when the appliance lookup fails to execute.

lce_service.remote_toolbox.get_job_progress(dbc: silo_cursor, proc_id: int, job: Dict[str, Any] | None = None, exclude_prefix: str | None = None) → JobProgress

Works out where a queued Remote Toolbox command is, from its spool row and its output.

A job is finished when its last output row is the completed row, when its spool row holds a return code, or when its spool row is in a terminal state. Any one signal is enough, because the toolbox writes each of them separately and swallows a failure of any. The return code is the most dependable of the spool row’s two: it is only ever written when the command ends, whereas the state is written by more than one process and the updates can land out of order. A job is running once its spool row says it was launched or is running, or once it has written any output, and queued while its spool row still holds the state it was queued with and nothing has been written.

The last output row is read by id rather than by time, which is both what the index serves and what makes it the row the toolbox wrote last.

Parameters:

dbc – A silo_cursor instance used to read the spool and output rows.
proc_id – The process id returned when the command was queued.
job – The spool row, when the caller has already read it with get_job_status or assert_job_readable, so it is not read twice.
exclude_prefix – Leave out the same rows the caller’s output reads leave out, so the last output id is one the caller’s cursor can actually reach.

Returns:

A JobProgress describing the phase and how long the job has been in it.

Raises:

DatabaseExecutionError – Raised when the spool row or the output rows cannot be read.

lce_service.remote_toolbox.get_job_status(dbc: silo_cursor, proc_id: int) → Dict[str, Any]

Reads the platform’s spool row for a queued Remote Toolbox command.

The row is queued with a state of 1, which the toolbox moves to 3 when it starts and to 0 or 4 when the command ends, recording the command’s exit status alongside. How long ago the command was queued is computed by the database, because the spool row’s queue time is written in UTC while the platform’s other timestamps are local.

Parameters:

dbc – A silo_cursor instance used to read the spool row.
proc_id – The process id returned when the command was queued.

Returns:

A dictionary holding the state, return code, process, tool type and the seconds since the command was queued, or an empty dictionary when no spool row exists. The spool row and the output rows are pruned independently, so output can outlive the row that describes it.

Raises:

DatabaseExecutionError – Raised when the spool row cannot be read.

lce_service.remote_toolbox.get_output_page(dbc: silo_cursor, proc_id: int, after_id: int = 0, page_size: int | None = None, exclude_prefix: str | None = None) → OutputPage

Reads one page of output from a queued Remote Toolbox command.

Rows are ordered by their own id, which is the order the collector emitted them. The command’s standard output and standard error arrive interleaved within the same id sequence, so reading them as one ordered stream is the only way to preserve the order in which they were produced.

Completion is detected by the presence of a completed row in the stream. That row is written whether the command succeeded, failed, or was refused by the Remote Toolbox before it ran, so a terminated page is not a successful one. A completed row can also go missing, since the toolbox does not retry a write that fails, which is what is_output_complete covers.

An empty page with termination not yet reported means the collector has not produced more output, not that the command produced none. The command has to reach the collector through a database update before anything is written at all.

A page is bounded in size as well as in rows. Accumulation stops once the records accepted reach MAX_RESPONSE_CHARS, and the cursor stops with them, so the rows the cap left behind are returned by the next call rather than skipped.

Parameters:

dbc – A silo_cursor instance used to read the output rows.
proc_id – The process id returned when the command was queued.
after_id – Return only rows with an id greater than this. Pass the previous page’s last_id to continue where it stopped, or zero to read from the beginning.
page_size – The maximum number of rows to return, bounded by MAX_OUTPUT_PAGE_SIZE. Defaults to DEFAULT_OUTPUT_PAGE_SIZE.
exclude_prefix – Leave out standard output rows starting with this marker, for a command that writes a framed payload alongside its log. Those rows are read whole with read_framed_payload instead, so they neither spend the page budget nor get cut by the per record cap here.

Returns:

An OutputPage holding the rows, the cursor to resume from, whether the collector has finished, and whether the page stopped short of the available output because the row budget or the character cap was reached.

Raises:

DatabaseExecutionError – Raised when the output rows cannot be read.

lce_service.remote_toolbox.has_been_quiet(progress: JobProgress) → bool

Decides whether a job has written nothing for SETTLE_SECONDS.

A job that has written nothing at all is measured by its queue age instead.

Parameters:: progress – The job’s progress.
Returns:: True when the job has been quiet long enough for a batch in transit to have landed, or when there is nothing to measure from.

lce_service.remote_toolbox.is_job_settled(progress: JobProgress) → bool

Decides whether a job is finished and every row it will write has arrived.

A job whose last row is the completed row is settled, since that row is written after all the others. A job that finished by its spool row alone, its completed row lost, is settled once it has written nothing for SETTLE_SECONDS, which gives a batch still in transit from the collector time to land. One that wrote nothing at all is settled by its queue age instead.

Parameters:: progress – The job’s progress.
Returns:: True when the job’s output can be treated as complete.

lce_service.remote_toolbox.is_output_complete(page: OutputPage, progress: JobProgress) → bool

Decides whether a reader has seen every row a finished job will ever write.

A page that saw the completed row is complete, which is the signal the platform’s own viewer relies on. That row can be missing, though, since the toolbox does not retry a failed write, and a reader waiting for it would poll a finished job forever. So a settled job, as is_job_settled defines it, is also complete once the page holds everything that was waiting and its cursor has reached the job’s last row. Progress has to be read after the page for the second test to hold, since a row written between the two reads would otherwise be skipped.

Parameters:

page – The page just returned to the reader.
progress – The job’s progress, read after the page.

Returns:

True when the reader can stop polling.

lce_service.remote_toolbox.poll_job_output(connect: Callable[[], ContextManager[silo_cursor]], proc_id: int, authorize: Callable[[silo_cursor], Dict[str, Any] | None], after_id: int = 0, page_size: int | None = None, wait_seconds: float | None = None, exclude_prefix: str | None = None) → Tuple[OutputPage, JobProgress]

Serves one poll of a job: checks access, reads a page, and reads the job’s progress.

A poll with no wait, which is how a caller should normally poll, does all three on one connection, the way one request of the platform’s own viewer does. Only a wait opens more: each read of the wait gets its own connection, closed before the sleep, and progress is read on a last one once the wait ends.

Progress is always read after the page, never before, because is_output_complete relies on it: a row written between the two reads would otherwise be skipped by a reader told it had caught up. The one exception is the spool row authorize returns, which is reused on the first connection rather than read again.

Parameters:

connect – Opens a database connection for one read, such as db_manager.
proc_id – The process id returned when the command was queued.
authorize – Checks that the caller may read the job, given the first connection, and raises if not. Nothing is read before it returns. It returns the job’s spool row if it read one, or None to have it read here.
after_id – Return only rows with an id greater than this.
page_size – The maximum number of rows to return, bounded by MAX_OUTPUT_PAGE_SIZE.
wait_seconds – How long to wait for the collector to finish, bounded by MAX_WAIT_SECONDS. Defaults to no wait.
exclude_prefix – Leave out standard output rows starting with this marker, from the page and from the progress alike.

Returns:

The page and the progress read after it.

Raises:

ToolboxJobNotAccessible – Raised by authorize when the caller may not read the job.
DatabaseExecutionError – Raised when anything cannot be read.

lce_service.remote_toolbox.queue_toolbox_command(dbc: silo_cursor, module_id: int, command: str, user: User, tool_id: int, policy_id: int = -1, device_id: int = 0, description: str = 'Remote Toolbox command') → int

Queues one command for the Remote Toolbox on a collector and returns its process id.

The command is stored in the platform’s spool table under AES_ENCRYPT and is picked up by the Remote Toolbox running on the target appliance. The collector polls the database for its work, so nothing has to be reachable inbound on the collector for this to succeed, which is what makes the path usable for collectors behind a firewall or NAT.

Two writes happen here and both have to land on the same connection. The process id is read back with LAST_INSERT_ID, which is connection scoped, and the ownership row that authorises a later read is keyed by that id. The endpoint layer holds a single cursor for the request, so passing the same cursor through satisfies both.

Both writes are also one unit of work, and they are wrapped in a transaction to make them one. The platform’s cursor forces autocommit on, so without it the queued command is committed as soon as the procedure returns and the collector’s outbound poll can pick the job up before the ownership row exists; a later failure would then leave output in a table shared by every toolbox tool with nobody recorded as its owner, for the whole 31 day retention. Rows written inside a transaction are invisible to the collector’s connection until it commits, so the transaction prevents the orphan rather than narrowing the window on it. This is the same unit of work device_tools_run.inc commits for the platform’s own toolbox tools.

Everything that can be refused is refused before anything is queued. Every check is a pure in memory comparison and needs no round trip, and a queued command cannot be recalled, so checking after the procedure call would cost a command that really ran on a collector. A command that cannot be run as given, because it carries the toolbox marker or is too long to store, is reported as a request error rather than a database one, since it is the request that has to change.

Parameters:

dbc – A silo_cursor instance used to queue the command and record its ownership.
module_id – The appliance id of the collector the command should run on.
command – The command to run, without the Remote Toolbox marker, which is prepended here. The collector side toolbox takes the last occurrence of the marker and refuses a payload with anything before it, so a command that already carries the marker is refused rather than queued to be refused on the collector.
user – The User instance the queued command is attributed to. The user id is written to the ownership row and is what authorises reading the output later.
tool_id – The Remote Toolbox tool id, stored as the spool row’s Xtype and on the ownership row. Reads check both, so it is what keeps one tool’s output from being read through another tool’s endpoint.
policy_id – The policy the command acts on, stored as the spool row’s Xid, or NO_POLICY_ID when there is none.
device_id – The device the command acts on, stored on the ownership row, or NO_DEVICE_ID when there is none.
description – What the command is, in the caller’s terms, such as “collector log command”, used in every error message so a refusal reads as the API the caller used rather than as this shared layer.

Returns:

The process id the platform assigned to the queued command.

Raises:

InvalidToolboxRequestError – Raised when the command carries the Remote Toolbox marker, or is too long for the spool table to hold once encrypted.
DatabaseExecutionError – Raised when the appliance id would broadcast, when the user cannot be identified, when the command cannot be queued, when the platform does not report a usable process id, or when the ownership row cannot be written. A failure to record ownership is treated as a failure of the whole dispatch and rolls the queued command back with it, because output that nobody can be shown to own must not be left behind.

lce_service.remote_toolbox.read_framed_payload(dbc: silo_cursor, proc_id: int, marker: str, chunk_size: int, max_chars: int) → FramedPayload

Reassembles a payload a command wrote to standard output as a series of marked chunks.

Some commands write a structured result as fixed length chunks, each on its own line behind a marker, interleaved with their log. Reassembly has three rules the platform’s own viewer breaks. A chunk is cut at an arbitrary character, so only its line terminator is removed and never any other whitespace, which may belong to a string inside the payload. A chunk is longer than a display record, so it is decoded whole rather than through the per record cap. And the whole payload is bounded once, by max_chars, rather than per page.

The terminator removed is a newline, preceded by a carriage return if there is one. A payload whose own text could end a chunk with either would need a different framing; a JSON payload cannot, since JSON escapes both inside strings and the writer emits it on one line.

Reading a payload whole is only meaningful once the job has finished, since a running job may not have written every chunk yet. Callers check progress first.

Parameters:

dbc – A silo_cursor instance used to read the output rows.
proc_id – The process id returned when the command was queued.
marker – The marker that starts every chunk.
chunk_size – The length, in characters, the writer cuts every chunk but the last to. It is used only to report chunks that arrived at a length the writer could not have produced.
max_chars – The most characters of payload to reassemble.

Returns:

A FramedPayload. When no chunk exists, its text and error are both None.

Raises:

DatabaseExecutionError – Raised when the output rows cannot be read.

lce_service.remote_toolbox.run_toolbox_command_locally(command: str, timeout: float = 90.0, description: str = 'Remote Toolbox command', max_output_bytes: int = 33554432) → LocalRun

Runs a Remote Toolbox command on this host and records its output as the toolbox would.

The command is the one queue_toolbox_command would queue, so it is refused for the same reason: one that already carries the toolbox marker would be decoded differently from the command given. It is then decoded, launched and read the way the toolbox does it, without a shell.

Parameters:

command – The command to run, without the Remote Toolbox marker.
timeout – How long the command may run before it is killed.
description – What the command is, in the caller’s terms, for the error message.
max_output_bytes – The most bytes of the command’s output to keep.

Returns:

A LocalRun holding the rows the toolbox would have written and the outcome.

Raises:

InvalidToolboxRequestError – Raised when the command carries the Remote Toolbox marker.
LocalRunLimitError – Raised when MAX_CONCURRENT_LOCAL_RUNS are already running.

lce_service.remote_toolbox.stitch_output(page: OutputPage, combined: bool = False) → Dict[str, Any]

Joins a page’s rows back into the text the command wrote to each stream.

The toolbox reads the command’s standard output and standard error through separate pipes and stores each line it reads as a row, so the rows of one stream, in id order, join back into that stream’s text.

Each row is one line. A row that does not end in a newline, as a record cut by the per record cap or the last line of a command that ended without one does not, gets one, so that the next page’s first line cannot run onto it. The toolbox’s own marker rows are left out. A row of a stream the toolbox does not normally write is kept under its own name.

A page ends on a row boundary, so a caller that polls page after page appends each page’s text to what it already has.

Combined, every row of the page is joined into one text in the order the collector wrote it, the marker rows included, which is how the platform’s own toolbox viewer shows a job’s output. The streams are then not returned separately, so a combined page is no larger than a split one.

Parameters:

page – A page of output.
combined – Join every row into one text rather than splitting it by stream.

Returns:

A dictionary holding “output”, a dictionary of each stream’s text, which always has stdout and stderr, or, when combined, holding only “combined”.

lce_service.remote_toolbox.validate_collector_identifier(appliance_identifier: Any, error: Type[InvalidToolboxRequestError] = <class 'lce_service.remote_toolbox.core.InvalidToolboxRequestError'>) → None

Checks that a collector identifier is an id or a name, without looking the collector up.

A local run ignores the collector it is given, but a malformed one is still refused, so a request is refused for the same value whichever way it runs.

Parameters:

appliance_identifier – The collector identifier supplied by the caller, or None when none was given.
error – The InvalidToolboxRequestError subclass to raise.

Raises:

InvalidToolboxRequestError – Raised, as error, when the identifier is neither a whole number nor a non-blank string.

lce_service.remote_toolbox.validate_run_local(value: Any, error: Type[InvalidToolboxRequestError] = <class 'lce_service.remote_toolbox.core.InvalidToolboxRequestError'>) → bool

Validates the field that runs a Remote Toolbox tool on this host rather than queueing it.

Left out, a tool runs locally on an All-In-One, which is its own collector, and is queued everywhere else. A collector named for a local run is ignored, since the run reads this host.

Parameters:

value – The value as supplied, or None when the field was not given.
error – The InvalidToolboxRequestError subclass to raise.

Returns:

Whether to run the tool locally.

Raises:

InvalidToolboxRequestError – Raised, as error, when the value is not a boolean, 0 or 1.

lce_service.remote_toolbox package

Submodules