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.
@@ -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.