hegemony-steps-shell 0.48.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- hegemony_steps_shell/__init__.py +35 -0
- hegemony_steps_shell/docs/shell.execute.md +126 -0
- hegemony_steps_shell/docs/shell.file_download.md +164 -0
- hegemony_steps_shell/execute.py +468 -0
- hegemony_steps_shell/file_download.py +664 -0
- hegemony_steps_shell/templates.py +309 -0
- hegemony_steps_shell-0.48.0.dist-info/METADATA +40 -0
- hegemony_steps_shell-0.48.0.dist-info/RECORD +11 -0
- hegemony_steps_shell-0.48.0.dist-info/WHEEL +4 -0
- hegemony_steps_shell-0.48.0.dist-info/entry_points.txt +3 -0
- hegemony_steps_shell-0.48.0.dist-info/licenses/LICENSE-AGPL-3.0-or-later.txt +235 -0
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# SPDX-FileCopyrightText: 2025-2026 Rexonix s.r.o.
|
|
2
|
+
# SPDX-FileContributor: Jakub Trávník <jakub.travnik@gmail.com>
|
|
3
|
+
#
|
|
4
|
+
# SPDX-License-Identifier: AGPL-3.0-or-later
|
|
5
|
+
|
|
6
|
+
"""Remote shell execution step handlers for Hegemony.
|
|
7
|
+
|
|
8
|
+
The remote-shell paradigm: run commands on Linux/Unix hosts over an
|
|
9
|
+
exec-channel transport (SSH today; WinRM slots in behind the same
|
|
10
|
+
``ShellTransport`` surface). In the platform's images, so ``shell.*``
|
|
11
|
+
is in every editor; a deployment that must not run commands on hosts
|
|
12
|
+
builds its api and worker images without the wheel.
|
|
13
|
+
|
|
14
|
+
Registers under the ``hegemony.step_handlers`` entry-point group; the entry
|
|
15
|
+
point name is the claimed handler-id namespace prefix (``shell``).
|
|
16
|
+
Handlers reach every platform facility through ``ctx.services``.
|
|
17
|
+
"""
|
|
18
|
+
|
|
19
|
+
from __future__ import annotations
|
|
20
|
+
|
|
21
|
+
from hegemony_step_sdk import BaseHandler, StepHandlerRegistry
|
|
22
|
+
|
|
23
|
+
from .execute import ShellExecuteHandler
|
|
24
|
+
from .file_download import ShellFileDownloadHandler
|
|
25
|
+
|
|
26
|
+
ALL_HANDLERS: tuple[type[BaseHandler], ...] = (ShellExecuteHandler, ShellFileDownloadHandler)
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def register(registry: StepHandlerRegistry) -> None:
|
|
30
|
+
"""Entry point: register this wheel's handlers with the host registry."""
|
|
31
|
+
for handler_class in ALL_HANDLERS:
|
|
32
|
+
registry.register_handler_type(handler_class)
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
__all__ = ["ALL_HANDLERS", "register", *sorted(cls.__name__ for cls in ALL_HANDLERS)]
|
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
<!--
|
|
2
|
+
SPDX-FileCopyrightText: 2025-2026 Rexonix s.r.o.
|
|
3
|
+
SPDX-FileContributor: Jakub Trávník <jakub.travnik@gmail.com>
|
|
4
|
+
|
|
5
|
+
SPDX-License-Identifier: AGPL-3.0-or-later
|
|
6
|
+
-->
|
|
7
|
+
|
|
8
|
+
# Execute Shell
|
|
9
|
+
|
|
10
|
+
`shell.execute` runs a list of shell commands on each target host over the
|
|
11
|
+
device's remote-shell transport (SSH, resolved from the device's access
|
|
12
|
+
configuration). Unlike the interactive network-CLI steps, it uses exec-channel
|
|
13
|
+
semantics: every command returns a real exit code and separate stdout and
|
|
14
|
+
stderr, which makes it the right step for Linux/Unix hosts.
|
|
15
|
+
|
|
16
|
+
## Using It
|
|
17
|
+
|
|
18
|
+
Write the commands one per line. Each line is sent as its own exec-channel
|
|
19
|
+
command, in order, on every target device, and succeeds or fails on its own
|
|
20
|
+
exit code. Targets are chosen with the role-based target picker; there is no
|
|
21
|
+
additional-IP list for this step.
|
|
22
|
+
|
|
23
|
+
Command lines accept `{{ variable }}` templates for flow inputs and earlier
|
|
24
|
+
step results, resolved before the step runs. A rendered value becomes part of
|
|
25
|
+
the remote shell's command line, so every `{{ }}` value must end with the
|
|
26
|
+
`quote` filter, which turns it into one literal word:
|
|
27
|
+
`systemctl restart {{ inputs.service | quote }}`. Without it, an input such as
|
|
28
|
+
`nginx; rm -rf ~` would run a second command. The quoted value must also
|
|
29
|
+
stand where the shell reads words, not inside `'...'` or `"..."`, a `#`
|
|
30
|
+
comment, backticks or a here-document: there the quoting does not hold, and
|
|
31
|
+
`echo "{{ inputs.msg | quote }}"` would let a value containing `"` end the
|
|
32
|
+
string. `{% if %}` and `{% for %}` statements are fine where a value would
|
|
33
|
+
be (`{% if inputs.force %}--force{% endif %}`); `{% filter %}`,
|
|
34
|
+
`{% include %}`, imports and macros are not supported. Neither is Jinja's
|
|
35
|
+
whitespace control (`{{-`, `-}}`, `{%-`, `-%}`, `{#-`, `-#}`): it can remove
|
|
36
|
+
the line break between two lines, which would join them into one command. The
|
|
37
|
+
step refuses to run a line that breaks these rules, before anything is
|
|
38
|
+
rendered. Quoting
|
|
39
|
+
keeps a value one word; a command that runs its argument as code (`eval`,
|
|
40
|
+
`sh -c`, `ssh host`) still runs it.
|
|
41
|
+
|
|
42
|
+
The other safe way in is an environment variable: set
|
|
43
|
+
`SERVICE={{ inputs.service }}` under Environment Variables and write
|
|
44
|
+
`systemctl restart "$SERVICE"` in the command. `{{ device.* }}` refers to
|
|
45
|
+
the first target only, so with several targets use values that are the same
|
|
46
|
+
for every host.
|
|
47
|
+
|
|
48
|
+
The Interpreter field controls how each line is wrapped on the remote host.
|
|
49
|
+
The default runs the line as-is in the account's login shell. `sh` and `bash`
|
|
50
|
+
quote the line into `sh -c '...'` or `bash -c '...'`, which keeps pipelines
|
|
51
|
+
and quoting predictable regardless of the login shell. `pwsh` wraps the line
|
|
52
|
+
in `pwsh -NoProfile -Command '...'` for PowerShell hosts. Environment
|
|
53
|
+
variables are quoted and set for every command: with the default interpreter
|
|
54
|
+
they are exported in the login shell first (`export KEY=VALUE; ...`, so a
|
|
55
|
+
POSIX login shell is needed), with `sh` and `bash` they are prefixed as
|
|
56
|
+
`env KEY=VALUE`. Either way `"$KEY"` works anywhere in the line. With `pwsh`
|
|
57
|
+
they are set at the start of the PowerShell command
|
|
58
|
+
(`$env:KEY = '...'; ...`, the value as a PowerShell single-quoted string) and
|
|
59
|
+
read as `$env:KEY`. A `pwsh` line takes no `{{ }}` values: `| quote` is POSIX
|
|
60
|
+
quoting, and PowerShell also reads typographic quotes (‘ ’) as quotes, so a
|
|
61
|
+
value could end the string. Pass values to `pwsh` in Environment Variables. For
|
|
62
|
+
the same reason a line that takes `{{ }}` values needs the Interpreter written
|
|
63
|
+
out as the login shell, `sh` or `bash`, not as a template, which could render
|
|
64
|
+
to `pwsh`. Names are
|
|
65
|
+
written into the command line as they are, so they must be letters, digits
|
|
66
|
+
and `_`, not starting with a digit; the values are the quoted part. Their values
|
|
67
|
+
appear on the remote command line (for example in the host's process list),
|
|
68
|
+
so they are not a place for secrets.
|
|
69
|
+
|
|
70
|
+
"Stop on first failure" (on by default) skips a device's remaining commands
|
|
71
|
+
after the first non-zero exit code; turn it off to run every command and
|
|
72
|
+
collect all failures. Each command is limited by the per-command timeout
|
|
73
|
+
(60 seconds by default; steps saved with its old name,
|
|
74
|
+
`command_timeout_sec`, keep working). A command also stops when the step's
|
|
75
|
+
own timeout is 10 seconds away, and the remaining commands do not start, so
|
|
76
|
+
the step still returns the output it has. Max Parallel Devices controls the fan-out: 1 (the
|
|
77
|
+
default) processes hosts strictly one after another, higher values run up to
|
|
78
|
+
that many hosts concurrently (capped at 32). Results are always aggregated in
|
|
79
|
+
device order, and command output streams into the step's live log as it
|
|
80
|
+
arrives.
|
|
81
|
+
|
|
82
|
+
## SSH Compatibility
|
|
83
|
+
|
|
84
|
+
Allow legacy SSH algorithms defaults to off. Enable `allow_legacy_ssh` only
|
|
85
|
+
for older hosts which require weak algorithms or small host keys; it applies
|
|
86
|
+
to the host and jump host for this step. Host-key verification still applies,
|
|
87
|
+
and a failed secure connection never retries weakly. Prefer upgrading the
|
|
88
|
+
host; use legacy mode only on a trusted network. The setting needs a Hegemony
|
|
89
|
+
version that supports it for shell steps; an older one refuses the step rather
|
|
90
|
+
than connecting securely in its place.
|
|
91
|
+
|
|
92
|
+
To allow them for one old host in every step, set `allow_legacy_ssh` in the
|
|
93
|
+
host's SSH access configuration instead (the jump host has its own flag). It
|
|
94
|
+
covers that hop only and needs a Hegemony version that reads it.
|
|
95
|
+
|
|
96
|
+
## Output
|
|
97
|
+
|
|
98
|
+
Later steps can read `steps.NODE_ID.output.stdout` — the combined standard output
|
|
99
|
+
of all commands across all hosts, capped at 4096 characters. Full outputs are
|
|
100
|
+
preserved as `cli_output` evidence artifacts: one per command per device,
|
|
101
|
+
named after the command's first line (shortened to 80 characters) with the
|
|
102
|
+
device name appended when more than one host is targeted. Each artifact
|
|
103
|
+
records the device, the command, the exit code, and the captured stderr
|
|
104
|
+
(capped like the chainable stdout); a failed command's artifact shows its
|
|
105
|
+
stderr in place of stdout - or its stdout, when nothing was written to
|
|
106
|
+
stderr - and a host that
|
|
107
|
+
cannot be reached contributes an "Error" artifact with the connection message.
|
|
108
|
+
Metrics record `command_count` (configured commands), `device_count`, and
|
|
109
|
+
`total_executions` (commands actually run across all hosts).
|
|
110
|
+
|
|
111
|
+
## When It Fails
|
|
112
|
+
|
|
113
|
+
The step fails immediately — before contacting any host — when a command
|
|
114
|
+
line inserts a `{{ }}` value without `| quote` or inside quotes, a comment,
|
|
115
|
+
backticks or a here-document, or uses whitespace control, when a `pwsh` line
|
|
116
|
+
inserts a `{{ }}` value, or a line does under an Interpreter written as a
|
|
117
|
+
template, or when no target devices or no commands are
|
|
118
|
+
configured. Per host, it fails when the device has
|
|
119
|
+
no management host, when the shell connection cannot be opened, when a command
|
|
120
|
+
exits non-zero, or when a command times out or the transport raises an error
|
|
121
|
+
(which also skips that host's remaining commands). One failing host does not
|
|
122
|
+
stop the others: every host is still processed and its evidence kept, but all
|
|
123
|
+
hosts must succeed for the step to succeed. The error text lists each failing
|
|
124
|
+
host with its exit code and the first line of its error output. The connection
|
|
125
|
+
to each host is closed when its commands finish, whether they succeeded or
|
|
126
|
+
not.
|
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
<!--
|
|
2
|
+
SPDX-FileCopyrightText: 2026 Rexonix s.r.o.
|
|
3
|
+
SPDX-FileContributor: Jakub Trávník <jakub.travnik@gmail.com>
|
|
4
|
+
|
|
5
|
+
SPDX-License-Identifier: AGPL-3.0-or-later
|
|
6
|
+
-->
|
|
7
|
+
|
|
8
|
+
# Download File to Host
|
|
9
|
+
|
|
10
|
+
`shell.file_download` has each target Linux/Unix host download one file from
|
|
11
|
+
a file repository by itself, with `curl`, over HTTP or HTTPS: a release
|
|
12
|
+
archive, a package, a configuration bundle. The file does not pass through
|
|
13
|
+
the worker. For a network device, use `netcli.file_download` (Download File
|
|
14
|
+
to Device) instead.
|
|
15
|
+
|
|
16
|
+
## Using It
|
|
17
|
+
|
|
18
|
+
Pick the file with **File**; the step takes exactly one. Browse the file
|
|
19
|
+
repositories and pick it, or type a template that gives a file reference: a
|
|
20
|
+
run-form field of the "Repository file" type (`{{ inputs.package }}`), or
|
|
21
|
+
another download step's `{{ steps.NODE_ID.output.file }}`. A reference
|
|
22
|
+
names the file by its repository's name and its path there
|
|
23
|
+
(`{"repository": "Internal object storage", "path": "releases/app-release-1.4.2.tar.gz"}`).
|
|
24
|
+
The repository is looked up in the run's organization first, then in the
|
|
25
|
+
shared organization. Two files with the same path in one repository are
|
|
26
|
+
refused as ambiguous: remove or move one. A file the field names directly
|
|
27
|
+
cannot be deleted from the repository while the flow uses it.
|
|
28
|
+
|
|
29
|
+
**File by id (legacy)**, under the advanced settings, is how flows saved
|
|
30
|
+
before **File** name the file: by its stored id. Such flows keep working.
|
|
31
|
+
Set one of the two, not both. Naming a file by repository and path needs a
|
|
32
|
+
Hegemony version that supports it; an older one fails the step and says to
|
|
33
|
+
upgrade or use a file id.
|
|
34
|
+
|
|
35
|
+
**Destination Directory** is the directory the file goes into, as an absolute
|
|
36
|
+
path (`/var/tmp` by default). It must exist, and the account the step logs in
|
|
37
|
+
with must be able to write to it; the step does not create it and does not use
|
|
38
|
+
`sudo`. **Destination Filename** names the file there; left empty, the file
|
|
39
|
+
keeps the name it has in the repository. It is a file name only, with no
|
|
40
|
+
slash. Neither field may contain a line break or another control character.
|
|
41
|
+
Targets are chosen with the role-based target picker.
|
|
42
|
+
|
|
43
|
+
For each host, the step connects over the device's remote-shell transport
|
|
44
|
+
(SSH, resolved from the device's access configuration, as `shell.execute`
|
|
45
|
+
does), asks the platform for a download link, and runs on the host:
|
|
46
|
+
|
|
47
|
+
1. `test -d <destination>`: a directory of that name is refused, before
|
|
48
|
+
anything is downloaded.
|
|
49
|
+
2. `curl -fsS --max-time <timeout> -o <destination>.<random>.part <link>`
|
|
50
|
+
3. `sha256sum < <destination>.<random>.part`, when **Verify checksum** is on
|
|
51
|
+
(the default): the result must equal the stored file's SHA-256.
|
|
52
|
+
4. `mv -f <destination>.<random>.part <destination>`
|
|
53
|
+
5. `test -f <destination>`: the file must be there as a regular file.
|
|
54
|
+
|
|
55
|
+
So the file appears under its name only once it is complete and, with the
|
|
56
|
+
check on, verified. A download that fails or does not match leaves nothing
|
|
57
|
+
behind: the `.part` file is removed, as far as the host still answers. Every
|
|
58
|
+
transfer has a `.part` file of its own, so two runs staging the same file on
|
|
59
|
+
one host do not disturb each other; the one that finishes last provides the
|
|
60
|
+
file. An existing file of that name is replaced. The host needs `curl`, and
|
|
61
|
+
`sha256sum` for the check; turn **Verify checksum** off on a host without it.
|
|
62
|
+
|
|
63
|
+
Two limits follow from doing this with plain commands on the host:
|
|
64
|
+
|
|
65
|
+
- Use a destination directory that accounts you do not trust cannot write
|
|
66
|
+
to. An account that can replace files in the directory could swap the
|
|
67
|
+
download before it is moved into place, as it could swap the finished file
|
|
68
|
+
afterwards; the checksum check cannot rule that out. A shared directory
|
|
69
|
+
with the sticky bit (as `/tmp` and `/var/tmp` have, the default included)
|
|
70
|
+
stops other accounts from renaming or deleting the file, which is weaker:
|
|
71
|
+
it does not stop them from writing to a file whose permissions allow it.
|
|
72
|
+
For a file that matters, name a directory only the login account can write
|
|
73
|
+
to.
|
|
74
|
+
- A run that is cancelled while a host downloads can leave that host's
|
|
75
|
+
`<destination>.<random>.part` file behind. It is safe to delete.
|
|
76
|
+
|
|
77
|
+
The link looks like `<platform address>/dl/<token>/<filename>`. The token in
|
|
78
|
+
it opens that one file and nothing else. Each host gets a link of its own,
|
|
79
|
+
issued right before its download and ended right after it; an unused link
|
|
80
|
+
expires after ten minutes. While `curl` runs, the link is visible in the
|
|
81
|
+
host's process list to other accounts on that host. The platform records each
|
|
82
|
+
issued link in the audit log, with the run, the step and the file.
|
|
83
|
+
|
|
84
|
+
Hosts must be able to reach the platform at the address an administrator set
|
|
85
|
+
as `HEGEMONY_API_EXTERNAL_URL`. They do not need to reach the object store.
|
|
86
|
+
With an `https://` address the host must trust the platform's certificate.
|
|
87
|
+
|
|
88
|
+
**Transfer timeout** (one hour by default, at most 24 hours) limits one
|
|
89
|
+
host's download. The step's own timeout (two hours unless set) still covers
|
|
90
|
+
the whole step, so it must leave time for every host. **Max Parallel
|
|
91
|
+
Devices** controls the fan-out: 1 (the default) handles hosts one after
|
|
92
|
+
another, higher values up to that many at once (capped at 32).
|
|
93
|
+
|
|
94
|
+
## SSH Compatibility
|
|
95
|
+
|
|
96
|
+
Allow legacy SSH algorithms defaults to off. Enable `allow_legacy_ssh` only
|
|
97
|
+
for older hosts which require weak algorithms or small host keys; it applies
|
|
98
|
+
to the host and jump host for this step. Host-key verification still applies,
|
|
99
|
+
and a failed secure connection never retries weakly. Prefer upgrading the
|
|
100
|
+
host; use legacy mode only on a trusted network. The setting needs a Hegemony
|
|
101
|
+
version that supports it for shell steps; an older one refuses the step rather
|
|
102
|
+
than connecting securely in its place.
|
|
103
|
+
|
|
104
|
+
## Output
|
|
105
|
+
|
|
106
|
+
Later steps can read:
|
|
107
|
+
|
|
108
|
+
- `steps.NODE_ID.output.filename` and `steps.NODE_ID.output.file_id`: the
|
|
109
|
+
stored file.
|
|
110
|
+
- `steps.NODE_ID.output.dest_dir`, `steps.NODE_ID.output.dest_filename` and
|
|
111
|
+
`steps.NODE_ID.output.dest_path`: where it went (`dest_path` is the two
|
|
112
|
+
joined).
|
|
113
|
+
- `steps.NODE_ID.output.size_bytes`, `steps.NODE_ID.output.sha256` and
|
|
114
|
+
`steps.NODE_ID.output.md5`: the stored file's size and checksums. `md5` is
|
|
115
|
+
null for a file stored without one.
|
|
116
|
+
- `steps.NODE_ID.output.verified`: whether every host's copy passed the
|
|
117
|
+
checksum check.
|
|
118
|
+
- `steps.NODE_ID.output.transferred_count`: how many hosts completed the
|
|
119
|
+
download.
|
|
120
|
+
- `steps.NODE_ID.output.repository`, `steps.NODE_ID.output.path` and
|
|
121
|
+
`steps.NODE_ID.output.folder`: the file repository's name, the file's path in
|
|
122
|
+
it (folder and file name) and its folder (empty for the repository root).
|
|
123
|
+
`steps.NODE_ID.output.repository_id` is the repository's id.
|
|
124
|
+
- `steps.NODE_ID.output.content_type`, `steps.NODE_ID.output.sha512` and
|
|
125
|
+
`steps.NODE_ID.output.metadata`: the stored file's content type, SHA-512
|
|
126
|
+
(null for a file stored without one) and the metadata stored with it.
|
|
127
|
+
- `steps.NODE_ID.output.file`: a file reference to the same file
|
|
128
|
+
(`{"repository": ..., "path": ...}`). Another download step takes it as
|
|
129
|
+
its **File**: `{{ steps.NODE_ID.output.file }}`. The next step looks the
|
|
130
|
+
repository and path up again, so it gets whatever file is at that path
|
|
131
|
+
then. To get exactly the file this step downloaded, pass
|
|
132
|
+
`{{ steps.NODE_ID.output.file_id }}` as its **File by id (legacy)**
|
|
133
|
+
instead. `file` is null when the platform did not report where the file
|
|
134
|
+
is (an older platform given a file id); pass the id then too.
|
|
135
|
+
|
|
136
|
+
The repository keys need a Hegemony version that reports them; an older one
|
|
137
|
+
leaves them null when the step names the file by id.
|
|
138
|
+
|
|
139
|
+
Each host contributes a "File download" evidence artifact with the file's
|
|
140
|
+
details (repository, path and checksums included) and where it went. A host that fails contributes an "Error" artifact
|
|
141
|
+
instead; the download link never appears in either. Metrics record
|
|
142
|
+
`device_count`, `transferred_count` and `size_bytes`.
|
|
143
|
+
|
|
144
|
+
## When It Fails
|
|
145
|
+
|
|
146
|
+
The step fails immediately when no target devices are configured, when no
|
|
147
|
+
file or more than one is selected, when both File and File by id (legacy) are
|
|
148
|
+
set, when File is not a file reference, when Destination Directory is not an
|
|
149
|
+
absolute path, when Destination Directory or Destination Filename contains a
|
|
150
|
+
line break or another control character, when Destination Filename has a
|
|
151
|
+
directory part, and on a platform that cannot issue download links. Per host,
|
|
152
|
+
it fails when the device has no management host, when the connection fails,
|
|
153
|
+
when the file is not one the run's organization may read or its path is
|
|
154
|
+
ambiguous, when the platform cannot open files by repository and path, when the stored
|
|
155
|
+
file's name contains a control character or a directory part and no
|
|
156
|
+
Destination Filename is set, when the platform has no
|
|
157
|
+
`HEGEMONY_API_EXTERNAL_URL`, when `curl` fails (it is not installed, the host
|
|
158
|
+
cannot reach the platform, the directory does not exist or is not writable,
|
|
159
|
+
the disk is full, the transfer timed out), when the destination is a
|
|
160
|
+
directory, when the checksum cannot be
|
|
161
|
+
computed or does not match, when the file cannot be moved into place, and
|
|
162
|
+
when the destination is not a regular file after the move. One
|
|
163
|
+
failing host does not stop the others, but all must succeed for the step to
|
|
164
|
+
succeed.
|