ssh_signal
Send POSIX signals (TERM, KILL, INT, etc.) to a remote SSH job, using channel signal or PID-based kill fallback. Optionally wait for job exit and return exit status.
Instructions
Deliver a POSIX signal (TERM, KILL, INT, HUP, QUIT, USR1, USR2, STOP, CONT, and a few others) to a job started by ssh_spawn. Use TERM (polite, the default) for graceful shutdown; use KILL only when TERM fails to stop the job within a reasonable window.
Delivery strategy: we first try paramiko's in-channel send_signal (often ignored by OpenSSH sshd), then fall back to 'kill - ' on a fresh SSH session using the PID captured at spawn time. Both paths are attempted unless use_pid_fallback=False.
Pass wait_ms > 0 to block up to that many milliseconds waiting for the job to actually exit; the response then includes the real exit_status. Otherwise we return immediately with still_running indicating whether the signal took effect within the fire-and-forget window.
Common patterns:
Polite stop, wait up to 5 s:
ssh_signal(job_id, 'TERM', wait_ms=5000)
Hard kill, don't wait (verify via ssh_tail later):
ssh_signal(job_id, 'KILL')
Interrupt (like Ctrl-C):
ssh_signal(job_id, 'INT')
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | The id returned by ``ssh_spawn``. | |
| signal | No | Signal name (``"TERM"``, ``"SIGTERM"``, ``"kill"``, …) or POSIX number (``9``, ``"9"``). Case-insensitive. Defaults to ``"TERM"`` — the polite choice. | TERM |
| wait_ms | No | If > 0, after delivering the signal we block up to this many milliseconds for the job's done_event to fire, and report the real ``exit_status`` in the response. Capped internally at 30000 ms. A value of 0 (default) returns immediately. | |
| use_channel | No | When True (default), try paramiko's in-channel ``send_signal`` first. Set to False to skip this path entirely — occasionally useful on a server known to reject it in ways that leave the channel in a bad state. | |
| use_pid_fallback | No | When True (default), open a fresh SSH session and run ``kill -<SIG> <pid>``. Requires the job to have been spawned with PID capture enabled (which is always the case via ssh_spawn). Set to False if you specifically want to verify whether ``channel.send_signal`` alone works on your server. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||