Skip to content

Commit e63cfa1

Browse files
authored
fix(cli): keep SSH forwards owned by spawned process (NVIDIA#3759)
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
1 parent 36b0386 commit e63cfa1

4 files changed

Lines changed: 117 additions & 26 deletions

File tree

‎architecture/sandbox.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -726,7 +726,10 @@ sandbox workload directly. The relay supports:
726726
which selects `bash -c` instead of `bash -lc`. Note `bash -c` still reads
727727
`BASH_ENV` when the child environment sets it.
728728
- Tar-based file sync.
729-
- Port forwarding where supported by the CLI/TUI surface.
729+
- Port forwarding where supported by the CLI/TUI surface. CLI-owned forwards
730+
disable SSH connection sharing and automatic forking so the spawned process
731+
owns the listener. Background forwards are recorded by PID only after the
732+
listener is reachable; failed startup reaps the child.
730733
- Persistent HTTP and WebSocket service routing through gateway-managed
731734
`ServiceEndpoint` records. `CreateSandboxRequest.service_exposures` registers
732735
named or unnamed endpoints as part of sandbox creation, and the gateway

‎crates/openshell-cli/src/ssh.rs‎

Lines changed: 108 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -761,20 +761,11 @@ pub async fn sandbox_forward(
761761

762762
let session = ssh_session_config(server, name, tls, workspace, None).await?;
763763

764-
let mut command = TokioCommand::from(ssh_base_command(&session.proxy_command));
765-
command
766-
.arg("-N")
767-
.arg("-o")
768-
.arg("ExitOnForwardFailure=yes")
769-
.arg("-o")
770-
.arg(format!(
771-
"SetEnv=OPENSHELL_FORWARD_SANDBOX_ID={}",
772-
session.sandbox_id
773-
))
774-
.arg("-L")
775-
.arg(spec.ssh_forward_arg());
776-
777-
command.arg("sandbox");
764+
let mut command = TokioCommand::from(ssh_forward_command(
765+
&session.proxy_command,
766+
&session.sandbox_id,
767+
spec,
768+
));
778769

779770
if background {
780771
command
@@ -793,34 +784,43 @@ pub async fn sandbox_forward(
793784

794785
if background {
795786
let mut child = command.spawn().into_diagnostic()?;
796-
let pid = child.id().ok_or_else(|| {
797-
miette::miette!("ssh process did not expose a PID for background tracking")
798-
})?;
787+
let Some(pid) = child.id() else {
788+
terminate_owned_forward_child(&mut child).await;
789+
return Err(miette::miette!(
790+
"ssh process did not expose a PID for background tracking"
791+
));
792+
};
799793

800794
if let Err(err) = wait_for_forward_start(&mut child, spec)
801795
.await
802796
.wrap_err("ssh process started but local forward listener was not reachable")
803797
{
804-
terminate_owned_forward_child(&mut child);
798+
terminate_owned_forward_child(&mut child).await;
805799
return Err(err);
806800
}
807801

808-
track_background_forward_or_cleanup(
802+
let tracked = track_background_forward_or_cleanup(
809803
workspace,
810804
name,
811805
port,
812806
pid,
813807
&session.sandbox_id,
814808
&spec.bind_addr,
815-
|| terminate_owned_forward_child(&mut child),
816-
)?;
809+
|| {
810+
let _ = child.start_kill();
811+
},
812+
);
813+
if tracked.is_err() {
814+
let _ = child.wait().await;
815+
}
816+
tracked?;
817817
return Ok(());
818818
}
819819

820820
let status = {
821821
let mut child = command.spawn().into_diagnostic()?;
822822
if let Err(err) = wait_for_forward_start(&mut child, spec).await {
823-
let _ = child.kill().await;
823+
terminate_owned_forward_child(&mut child).await;
824824
return Err(err);
825825
}
826826
eprintln!("{}", foreground_forward_started_message(name, spec));
@@ -834,6 +834,30 @@ pub async fn sandbox_forward(
834834
Ok(())
835835
}
836836

837+
/// A forward must stay owned by the process we spawn so it can be reaped or
838+
/// tracked by PID. User SSH config may otherwise move it into a persistent mux.
839+
fn ssh_forward_command(proxy_command: &str, sandbox_id: &str, spec: &ForwardSpec) -> Command {
840+
let mut command = ssh_base_command(proxy_command);
841+
command
842+
.arg("-o")
843+
.arg("ControlMaster=no")
844+
.arg("-o")
845+
.arg("ControlPath=none")
846+
.arg("-o")
847+
.arg("ControlPersist=no")
848+
.arg("-o")
849+
.arg("ForkAfterAuthentication=no")
850+
.arg("-N")
851+
.arg("-o")
852+
.arg("ExitOnForwardFailure=yes")
853+
.arg("-o")
854+
.arg(format!("SetEnv=OPENSHELL_FORWARD_SANDBOX_ID={sandbox_id}"))
855+
.arg("-L")
856+
.arg(spec.ssh_forward_arg())
857+
.arg("sandbox");
858+
command
859+
}
860+
837861
/// Wait for the local listener, racing the probe against the `ssh` child
838862
/// exiting. An early exit (e.g. `ExitOnForwardFailure=yes` tearing down the
839863
/// session) means forwarding never came up, so it errors instead of waiting
@@ -859,7 +883,16 @@ async fn wait_for_forward_start(child: &mut Child, spec: &ForwardSpec) -> Result
859883
))
860884
}
861885
}
886+
}?;
887+
888+
if let Some(status) = child.try_wait().into_diagnostic()? {
889+
return Err(miette::miette!(
890+
"ssh exited with status {status} after local forward listener opened on {}:{}",
891+
forward_probe_host(spec),
892+
spec.port,
893+
));
862894
}
895+
Ok(())
863896
}
864897

865898
/// Poll the local endpoint until a connect succeeds or `wait_for` elapses. The
@@ -935,9 +968,10 @@ fn forward_probe_host(spec: &ForwardSpec) -> &str {
935968
}
936969
}
937970

938-
/// Best-effort cleanup for the SSH child this process spawned.
939-
fn terminate_owned_forward_child(child: &mut Child) {
940-
let _ = child.start_kill();
971+
/// Best-effort cleanup for the SSH child this process spawned. `kill` waits for
972+
/// the child to exit, so failed startup cannot leave an unreaped process.
973+
async fn terminate_owned_forward_child(child: &mut Child) {
974+
let _ = child.kill().await;
941975
}
942976

943977
/// Track a verified background forward, cleaning it up if PID-file persistence fails.
@@ -2434,6 +2468,55 @@ mod tests {
24342468
assert_eq!(forward_probe_host(&loopback), "127.0.0.1");
24352469
}
24362470

2471+
#[cfg(unix)]
2472+
#[test]
2473+
fn forward_ssh_command_overrides_user_multiplexing_and_forking() {
2474+
let _guard = TEST_ENV_LOCK
2475+
.lock()
2476+
.unwrap_or_else(std::sync::PoisonError::into_inner);
2477+
let dir = tempfile::tempdir().unwrap();
2478+
let config = dir.path().join("ssh_config");
2479+
fs::write(
2480+
&config,
2481+
format!(
2482+
"Host sandbox\n ControlMaster auto\n ControlPath {}/mux-%C\n ControlPersist yes\n ForkAfterAuthentication yes\n",
2483+
dir.path().display()
2484+
),
2485+
)
2486+
.unwrap();
2487+
2488+
let forward = ssh_forward_command(
2489+
"openshell ssh-proxy --sandbox demo",
2490+
"sandbox-id",
2491+
&ForwardSpec::new(18080),
2492+
);
2493+
let output = Command::new("ssh")
2494+
.arg("-F")
2495+
.arg(&config)
2496+
.arg("-G")
2497+
.args(forward.get_args())
2498+
.output()
2499+
.unwrap();
2500+
assert!(
2501+
output.status.success(),
2502+
"ssh -G failed: {}",
2503+
String::from_utf8_lossy(&output.stderr)
2504+
);
2505+
let effective = String::from_utf8(output.stdout).unwrap();
2506+
assert!(effective.lines().any(|line| line == "controlmaster false"));
2507+
assert!(effective.lines().any(|line| line == "controlpersist no"));
2508+
assert!(
2509+
effective
2510+
.lines()
2511+
.any(|line| line == "forkafterauthentication no")
2512+
);
2513+
assert!(
2514+
!effective
2515+
.lines()
2516+
.any(|line| { line.starts_with("controlpath ") && line != "controlpath none" })
2517+
);
2518+
}
2519+
24372520
#[tokio::test]
24382521
async fn wait_for_forward_listener_accepts_ready_listener() {
24392522
let listener = tokio::net::TcpListener::bind(("127.0.0.1", 0))

‎docs/how-it-works/sandboxes/overview.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -670,6 +670,8 @@ openshell forward start 8000 my-sandbox -d # run in background
670670
```
671671
672672
OpenShell prints the local URL only after the forward listener is reachable. Background forwards must be tracked locally so `openshell forward list` and `openshell forward stop` can manage them.
673+
CLI forwards run independently of SSH multiplexing settings in your SSH config.
674+
Foreground forwards end when the command exits; only background forwards appear in `forward list`.
673675
674676
List and stop active forwards:
675677

‎skills/openshell-cli/SKILL.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -689,6 +689,9 @@ openshell forward start 8080 my-app -d
689689
```
690690

691691
The service is now reachable at `localhost:8080`.
692+
CLI forwards ignore SSH multiplexing and automatic backgrounding settings in the
693+
user's SSH config. Only background forwards are tracked by `forward list` and
694+
managed by `forward stop`; foreground forwards end when the command exits.
692695

693696
Manage or iterate on the sandbox:
694697

0 commit comments

Comments
 (0)