sshtemp

Template-driven SSH automation using Paramiko invoke_shell. Built for network devices (prompts, jump hosts, captures, configuration) and works on Linux-style interactive shells.

Requires Python 3.11+.

Source: https://github.com/umurarslan/sshtemp

AI assistants writing templates: follow skills/sshtemp.md.

pip install sshtemp

Quick start

from sshtemp import ssht

TEMPLATE = r"""
_HOST: 10.0.0.1
_USERNAME: admin
_PASSWORD: NokiaSros1!
_EXPECT: #\s*$
_CAPTURE:show_version
show version
_END
"""

result = ssht(TEMPLATE)
if result.success:
    print(result.captures["show_version"])
else:
    print("unsuccessful:", result.error)
for warning in result.warnings:
    print(f"warning: {warning}")

ssht() never raises. Check result.success, then result.error / result.warnings, then result.captures. Pass save_to_disk=True to write capture files and sshtemp.log under result.output_dir.

CLI writes an output folder for a run. ${VAR} in .txt files is filled from the environment, or prompted if missing:

sshtemp my_template.txt
sshtemp --check my_template.txt
sshtemp -p 4 my_template.txt

Full flags, result fields, and the template language: Advanced.

Examples

Lab IPs and passwords — adapt them. These files are in the repository examples/, not in the pip package.

sshtemp --check examples/01-basic-nokia_sros-cli.txt
export JUMP_PASSWORD=clab
export DEVICE_PASSWORD=NokiaSros1!
sshtemp examples/03-other-jumpserver-nokia_sros-cli.txt
sshtemp -p 2 examples/04-parallel-jumpserver-nokia_sros-cli.txt

Default host_key_policy is auto (unknown SSH host keys are accepted) for the Paramiko _HOST: hop only. Nested ssh in the template is yours to lock down. Details: Security.

Advanced

• CLI
• API
• Result
• Template language
• Jump host example
• Defaults
• Logging
• Secrets
• Security
• Parallel execution
• Troubleshooting

CLI

sshtemp my_template.txt
sshtemp my_template.txt -v
sshtemp my_template.txt -o output/lab
sshtemp --host-key-policy reject my_template.txt
sshtemp -p 4 my_template.txt
sshtemp --check my_template.txt

--check does not split on _HOST: or inject sticky settings. A file can pass --check and still fail sshtemp -p N. If both --check and -p are set, only --check runs.

Exit 0 prints output: <path> on stdout. Warnings and failures go to stderr (partial capture names, failed line number when available; for -p, each failed section then a summary of the first failure). Without -o, a run creates output_YYYYMMDD-HHMMSS-ffffff/ in the current directory (ffffff is microseconds). --check, an unreadable template, a missing ${VAR}, and a parallel prep error stop before that folder is created. Repeated capture names in one run are appended.

API

ssht(
    template,
    directive_prefix="_",
    *,
    log_id=None,
    verbose=False,
    save_to_disk=False,
    output_dir=None,
    host_key_policy="auto",
    manage_logging=True,
) -> SshTempResult

A multi-line string is an inline template. A single-line string is a file path, so an inline template must contain a newline. ${VAR} is not expanded by ssht() — see Secrets.

ssht() never raises. Fatal problems set result.success=False and result.error. Exception classes in sshtemp.exceptions are internal.

ssht_parallel() takes the same template / verbose / save_to_disk / output_dir / host_key_policy / directive_prefix as ssht(), plus required max_workers. It has no log_id or manage_logging. See Parallel execution.

validate_template

from sshtemp import validate_template

result = validate_template(template_text)
if not result.valid:
    for issue in result.issues:
        print(issue)
for warning in result.warnings:
    print(f"warning: {warning}")

Takes inline text, not a file path. Same sequential checks as sshtemp --check (placeholders allowed; no parallel prep). Syntax problems are errors (result.valid is False). Missing _EXPECT is a warning. --check prints warnings to stderr and still exits 0 when syntax is valid. ssht() copies validation warnings into result.warnings before SSH starts.

Result

1. result.success is False → result.error.
2. result.warnings is not empty → _ERROR with _ERRORFAIL: off; no _EXPECT; or a capture saved because the run failed before _END.
3. Otherwise → result.captures (and result.output_dir when save_to_disk=True).

The same capture name twice in one run appends. Warnings and errors are also logged (stderr, plus sshtemp.log when save_to_disk=True).

Template language

Lines are processed top to bottom. Directive names are exact: _ENDING is not _END.

Connect settings tell Paramiko how to open the session. They are reused on a later _HOST: if omitted. Session settings stay until you change them. Scoped directives apply to the next command, a capture block, or a single line.

Connect

Not applied to nested ssh inside the shell.

Jump host: _HOST is the jump box. Reach devices with a normal ssh admin@device command. _HOST / result.host do not change nested SSH targets.

Reconnect: Only _HOST: reopens Paramiko. Changing _USERNAME:, _PASSWORD:, or _PORT: stores the value until the next _HOST:.

After invoke_shell (including reconnect) the engine reads login MOTD before the first command. That text is not captured and is not checked against _ERROR. Nested ssh is a normal command — _EXPECT applies to that command’s output. Set _EXPECT (and _SETTLE if the banner is slow) before the first command you care about.

Session (sticky)

Clear _ERROR: after a configure block so later show / backup lines are not checked.

_WAIT / _RETRY

Scope: next command only, then defaults; or the whole _CAPTURE block when placed immediately before _CAPTURE (reset after _END).

_WAIT: 120
_CAPTURE:backup
admin display-config
_END
configure

admin display-config uses 120s; configure uses 20s.

_RETRY re-sends the same line. Use it for show / admin display-config. Do not set it above 1 for configuration, commits, or a password sent as a plain line.

One-shot and auto-response

Capture

_CAPTURE:config_backup
admin display-config
_END

_CAPTURE:name sets the name (and file name under the output folder). _CAPTURE without a name uses capture_0.txt, capture_1.txt, …. Subfolders are allowed (version/10.1.1.1.txt). Absolute paths and .. are rejected when writing files (not part of --check). Close every block before the next _HOST:.

If the run fails before _END, output so far is still in result.captures (and on disk when save_to_disk=True) with a “saved partially” warning.

For a large dump: paging off (environment no more on Nokia classic CLI), then _WAIT: 120 / _RETRY: 2 immediately before _CAPTURE, and keep _ERROR off until configure.

Any non-directive line is sent to the shell with a trailing newline.

Jump host example

_HOST: 172.29.112.112
_USERNAME: clab
_PASSWORD: clab
_PORT: 2222
_EXPECT: #\s*$

_IF: continue connecting
_THEN: yes
_IF: .*assword:
_THEN: NokiaSros1!
ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null admin@10.0.0.3
environment no more

_WAIT: 120
_RETRY: 2
_CAPTURE:running_config
admin display-config
_END

_ERROR:(?i)(critical:|error:|minor:|major:)
configure
    port 1/1/1
        description "lab"
exit all
_ERROR:

Defaults

Logging

• verbose=False: WARNING and ERROR. _RETRY misses log as sshtemp.command_retry (WARNING), including output_preview (can contain a password echo).
• verbose=True: also INFO for commands, captures, expect / if-then. A password sent as a plain template line can appear in command=.
• Log file lines have a UTC timestamp; stderr does not.
• _LOGID: / log_id= prefixes every line.

Attach your own handler to the sshtemp logger (not the root). Records do not propagate. Your handler’s level applies; verbose only changes sshtemp’s own handlers.

import logging

handler = logging.FileHandler("myapp.log")
handler.setLevel(logging.INFO)
logging.getLogger("sshtemp").addHandler(handler)

Secrets

Keep passwords out of git.

CLI — ${VAR} in .txt files:

_PASSWORD: ${jump_server_password}

export jump_server_password='clab'
sshtemp router.txt

Names: letter or _, then letters, digits, _. Hyphens are a validation error. ${VAR} on _# lines is not substituted. Missing values are prompted (masked). Linux: name match is case-sensitive. Windows: case-insensitive. --check does not read the environment.

Python — ssht() does not expand ${VAR}:

import os
from sshtemp import ssht

password = os.environ["NOKIA_PASSWORD"]
result = ssht(rf"""
_HOST: 10.0.0.1
_USERNAME: admin
_PASSWORD: {password}
_EXPECT: #\s*$
show version
""")

Security

sshtemp is a thin Paramiko wrapper. Trust, credentials, and network safety are your responsibility.

Parallel execution

ssht_parallel() / sshtemp -p N run each _HOST section concurrently. Sequential ssht() is unchanged.

ssht_parallel(
    template,
    max_workers,
    directive_prefix="_",
    *,
    verbose=False,
    save_to_disk=False,
    output_dir=None,
    host_key_policy="auto",
) -> SshTempParallelResult

No log_id — set _LOGID: in each section. Logging is configured by the orchestrator (manage_logging is not a parameter).

from sshtemp import ssht_parallel

result = ssht_parallel(template, max_workers=4, save_to_disk=True)
if result.success:
    for section_result in result.results:
        print(section_result.host, section_result.captures)
else:
    print(result.error)

ssht_parallel() never raises. result.results is one SshTempResult per section, in template order. There is no merged capture dict. All sections are started; one failure does not cancel the others.

Workers share one log file when save_to_disk=True. Use unique capture names per device and _LOGID: per section. The orchestrator configures logging once; workers use manage_logging=False.

Template preparation

1. Split on each _HOST: line.
2. For later sections, insert missing stickies right after that section’s _HOST: from earlier sections.

Injected when missing: _USERNAME, _PASSWORD, _PORT, _TIMEOUT, _SHELL, _SETTLE, _RECV_BUFFER, _ENCODING, _EXPECT.

Not injected: _LOGID, _ERROR / _ERRORFAIL, _WAIT / _RETRY, _IF / _THEN. Wrap configure _ERROR: … _ERROR: in each section.

Each section must have balanced _CAPTURE / _END. Blank lines and _# comments may appear before the first _HOST:. Any other content there is a parallel-only error (--check does not catch it).

Troubleshooting

Tests

python -m unittest discover -s tests -p "test_*.py"