.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "CONDOR_SSH_TO_JOB" "1" "Apr 01, 2024" "" "HTCondor Manual"
.SH NAME
condor_ssh_to_job \- HTCondor Manual
.sp
create an ssh session to a running job
  
.SH SYNOPSIS
.sp
\fBcondor_ssh_to_job\fP [\fB\-help\fP ]
.sp
\fBcondor_ssh_to_job\fP [\fB\-debug\fP ] [\fB\-name\fP \fIschedd\-name\fP]
[\fB\-pool\fP \fIpool\-name\fP] [\fB\-ssh\fP \fIssh\-command\fP]
[\fB\-keygen\-options\fP \fIssh\-keygen\-options\fP]
[\fB\-shells\fP \fIshell1,shell2,...\fP] [\fB\-auto\-retry\fP ]
[\fB\-remove\-on\-interrupt\fP ] \fIcluster | cluster.process |
cluster.process.node\fP [\fIremote\-command\fP ]
.SH DESCRIPTION
.sp
\fIcondor_ssh_to_job\fP creates an \fIssh\fP session to a running job. The
job is specified with the argument. If only the job \fIcluster\fP id is
given, then the job \fIprocess\fP id defaults to the value 0.
.sp
\fIcondor_ssh_to_job\fP is available in Unix HTCondor distributions, and
works with two kinds of jobs: those in the vanilla, vm, java, local, or
parallel universes, and those jobs in the grid universe which use EC2
resources. It will not work with other grid universe jobs.
.sp
For jobs in the vanilla, vm, java, local, or parallel universes, the
user must be the owner of the job or must be a queue super user, and
both the \fIcondor_schedd\fP and \fIcondor_starter\fP daemons must allow
\fIcondor_ssh_to_job\fP access. If no \fIremote\-command\fP is specified, an
interactive shell is created. An alternate \fIssh\fP program such as \fIsftp\fP
may be specified, using the \fB\-ssh\fP option, for uploading and
downloading files.
.sp
The remote command or shell runs with the same user id as the running
job, and it is initialized with the same working directory. The
environment is initialized to be the same as that of the job, plus any
changes made by the shell setup scripts and any environment variables
passed by the \fIssh\fP client. In addition, the environment variable
\fB_CONDOR_JOB_PIDS\fP is defined. It is a space\-separated list of PIDs
associated with the job. At a minimum, the list will contain the PID of
the process started when the job was launched, and it will be the first
item in the list. It may contain additional PIDs of other processes that
the job has created.
.sp
The \fIssh\fP session and all processes it creates are treated by HTCondor
as though they are processes belonging to the job. If the slot is
preempted or suspended, the \fIssh\fP session is killed or suspended along
with the job. If the job exits before the \fIssh\fP session finishes, the
slot remains in the Claimed Busy state and is treated as though not all
job processes have exited until all \fIssh\fP sessions are closed. Multiple
\fIssh\fP sessions may be created to the same job at the same time. Resource
consumption of the \fIsshd\fP process and all processes spawned by it are
monitored by the \fIcondor_starter\fP as though these processes belong to
the job, so any policies such as \fI\%PREEMPT\fP that enforce a limit on
resource consumption also take into account resources consumed by the
\fIssh\fP session.
.sp
\fIcondor_ssh_to_job\fP stores ssh keys in temporary files within a newly
created and uniquely named directory. The newly created directory will
be within the directory defined by the environment variable \fBTMPDIR\fP\&.
When the ssh session is finished, this directory and the ssh keys
contained within it are removed.
.sp
See the HTCondor administrator\(aqs manual section on configuration for
details of the configuration variables related to
\fIcondor_ssh_to_job\fP\&.
.sp
An \fIssh\fP session works by first authenticating and authorizing a secure
connection between \fIcondor_ssh_to_job\fP and the \fIcondor_starter\fP
daemon, using HTCondor protocols. The \fIcondor_starter\fP generates an ssh
key pair and sends it securely to \fIcondor_ssh_to_job\fP\&. Then the
\fIcondor_starter\fP spawns \fIsshd\fP in inetd mode with its stdin and stdout
attached to the TCP connection from \fIcondor_ssh_to_job\fP\&.
\fIcondor_ssh_to_job\fP acts as a proxy for the \fIssh\fP client to
communicate with \fIsshd\fP, using the existing connection authorized by
HTCondor. At no point is \fIsshd\fP listening on the network for connections
or running with any privileges other than that of the user identity
running the job. If CCB is being used to enable connectivity to the
execute node from outside of a firewall or private network,
\fIcondor_ssh_to_job\fP is able to make use of CCB in order to form the
\fIssh\fP connection.
.sp
The login shell of the user id running the job is used to run the
requested command, \fIsshd\fP subsystem, or interactive shell. This is
hard\-coded behavior in \fIOpenSSH\fP and cannot be overridden by
configuration. This means that \fIcondor_ssh_to_job\fP access is
effectively disabled if the login shell disables access, as in the
example programs \fI/bin/true\fP and \fI/sbin/nologin\fP\&.
.sp
\fIcondor_ssh_to_job\fP is intended to work with \fIOpenSSH\fP as installed
in typical environments. It does not work on Windows platforms. If the
\fIssh\fP programs are installed in non\-standard locations, then the paths
to these programs will need to be customized within the HTCondor
configuration. Versions of \fIssh\fP other than \fIOpenSSH\fP may work, but they
will likely require additional configuration of command\-line arguments,
changes to the \fIsshd\fP configuration template file, and possibly
modification of the $(LIBEXEC)/condor_ssh_to_job_sshd_setup script
used by the \fIcondor_starter\fP to set up \fIsshd\fP\&.
.sp
For jobs in the grid universe which use EC2 resources, a request that
HTCondor have the EC2 service create a new key pair for the job by
specifying
\fI\%ec2_keypair_file\fP
causes \fIcondor_ssh_to_job\fP to attempt to connect to the corresponding
instance via \fIssh\fP\&. This attempts invokes \fIssh\fP directly, bypassing the
HTCondor networking layer. It supplies \fIssh\fP with the public DNS name of
the instance and the name of the file with the new key pair\(aqs private
key. For the connection to succeed, the instance must have started an
\fIssh\fP server, and its security group(s) must allow connections on port
22. Conventionally, images will allow logins using the key pair on a
single specific account. Because \fIssh\fP defaults to logging in as the
current user, the \fB\-l <username>\fP option or its equivalent for other
versions of \fIssh\fP will be needed as part of the \fIremote\-command\fP
argument. Although the \fB\-X\fP option does not apply to EC2 jobs, adding
\fB\-X\fP or \fB\-Y\fP to the \fIremote\-command\fP argument can duplicate the
effect.
.SH OPTIONS
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
\fB\-help\fP
Display brief usage information and exit.
.TP
\fB\-debug\fP
Causes debugging information to be sent to \fBstderr\fP, based on the
value of the configuration variable \fI\%TOOL_DEBUG\fP\&.
.TP
\fB\-name\fP \fIschedd\-name\fP
Specify an alternate \fIcondor_schedd\fP, if the default (local) one is
not desired.
.TP
\fB\-pool\fP \fIpool\-name\fP
Specify an alternate HTCondor pool, if the default one is not
desired. Does not apply to EC2 jobs.
.TP
\fB\-ssh\fP \fIssh\-command\fP
Specify an alternate \fIssh\fP program to run in place of \fIssh\fP, for
example \fIsftp\fP or \fIscp\fP\&. Additional arguments are specified as
\fIssh\-command\fP\&. Since the arguments are delimited by spaces, place
double quote marks around the whole command, to prevent the shell
from splitting it into multiple arguments to \fIcondor_ssh_to_job\fP\&.
If any arguments must contain spaces, enclose them within single
quotes. Does not apply to EC2 jobs.
.TP
\fB\-keygen\-options\fP \fIssh\-keygen\-options\fP
Specify additional arguments to the \fIssh_keygen\fP program, for
creating the ssh key that is used for the duration of the session.
For example, a different number of bits could be used, or a
different key type than the default. Does not apply to EC2 jobs.
.TP
\fB\-shells\fP \fIshell1,shell2,...\fP
Specify a comma\-separated list of shells to attempt to launch. If
the first shell does not exist on the remote machine, then the
following ones in the list will be tried. If none of the specified
shells can be found, \fI/bin/sh\fP is used by default. If this option is
not specified, it defaults to the environment variable \fBSHELL\fP
from within the \fIcondor_ssh_to_job\fP environment. Does not apply
to EC2 jobs.
.TP
\fB\-auto\-retry\fP
Specifies that if the job is not yet running, \fIcondor_ssh_to_job\fP
should keep trying periodically until it succeeds or encounters some
other error.
.TP
\fB\-remove\-on\-interrupt\fP
If specified, attempt to remove the job from the queue if
\fIcondor_ssh_to_job\fP is interrupted via a CTRL\-c or otherwise
terminated abnormally.
.TP
\fB\-X\fP
Enable X11 forwarding. Does not apply to EC2 jobs.
.TP
\fB\-x\fP
Disable X11 forwarding.
.UNINDENT
.UNINDENT
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ condor_ssh_to_job 32.0
Welcome to slot2@tonic.cs.wisc.edu!
Your condor job is running with pid(s) 65881.
$ gdb \-p 65881
(gdb) where
\&...
$ logout
Connection to condor\-job.tonic.cs.wisc.edu closed.
.EE
.UNINDENT
.UNINDENT
.sp
To upload or download files interactively with \fIsftp\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ condor_ssh_to_job \-ssh sftp 32.0
Connecting to condor\-job.tonic.cs.wisc.edu...
sftp> ls
\&...
sftp> get outputfile.dat
.EE
.UNINDENT
.UNINDENT
.sp
This example shows downloading a file from the job with \fIscp\fP\&. The
string \(dqremote\(dq is used in place of a host name in this example. It is
not necessary to insert the correct remote host name, or even a valid
one, because the connection to the job is created automatically.
Therefore, the placeholder string \(dqremote\(dq is perfectly fine.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ condor_ssh_to_job \-ssh scp 32 remote:outputfile.dat .
.EE
.UNINDENT
.UNINDENT
.sp
This example uses \fIcondor_ssh_to_job\fP to accomplish the task of
running \fIrsync\fP to synchronize a local file with a remote file in the
job\(aqs working directory. Job id 32.0 is used in place of a host name in
this example. This causes \fIrsync\fP to insert the expected job id in the
arguments to \fIcondor_ssh_to_job\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ rsync \-v \-e \(dqcondor_ssh_to_job\(dq 32.0:outputfile.dat .
.EE
.UNINDENT
.UNINDENT
.sp
Note that \fIcondor_ssh_to_job\fP was added to HTCondor in version 7.3.
If one uses \fIcondor_ssh_to_job\fP to connect to a job on an execute
machine running a version of HTCondor older than the 7.3 series, the
command will fail with the error message
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Failed to send CREATE_JOB_OWNER_SEC_SESSION to starter
.EE
.UNINDENT
.UNINDENT
.SH EXIT STATUS
.sp
\fIcondor_ssh_to_job\fP will exit with a non\-zero status value if it
fails to set up an ssh session. If it succeeds, it will exit with the
status value of the remote command or shell.
.SH AUTHOR
HTCondor Team
.SH COPYRIGHT
1990-2024, Center for High Throughput Computing, Computer Sciences Department, University of Wisconsin-Madison, Madison, WI, US. Licensed under the Apache License, Version 2.0.
.\" Generated by docutils manpage writer.
.