.TH "GCLOUD_BETA_COMPUTE_SSH" 1



.SH "NAME"
.HP
gcloud beta compute ssh \- SSH into a virtual machine instance



.SH "SYNOPSIS"
.HP
\f5gcloud beta compute ssh\fR [\fIUSER\fR@]\fIINSTANCE\fR [\fB\-\-command\fR=\fICOMMAND\fR] [\fB\-\-container\fR=\fICONTAINER\fR] [\fB\-\-dry\-run\fR] [\fB\-\-force\-key\-file\-overwrite\fR] [\fB\-\-plain\fR] [\fB\-\-ssh\-flag\fR=\fISSH_FLAG\fR] [\fB\-\-ssh\-key\-file\fR=\fISSH_KEY_FILE\fR] [\fB\-\-strict\-host\-key\-checking\fR=\fISTRICT_HOST_KEY_CHECKING\fR] [\fB\-\-troubleshoot\fR] [\fB\-\-zone\fR=\fIZONE\fR] [\fB\-\-internal\-ip\fR\ |\ \fB\-\-tunnel\-through\-iap\fR] [\fB\-\-network\fR=\fINETWORK\fR\ \fB\-\-region\fR=\fIREGION\fR\ :\ \fB\-\-dest\-group\fR=\fIDEST_GROUP\fR] [\fB\-\-ssh\-key\-expiration\fR=\fISSH_KEY_EXPIRATION\fR\ |\ \fB\-\-ssh\-key\-expire\-after\fR=\fISSH_KEY_EXPIRE_AFTER\fR] [\fIGCLOUD_WIDE_FLAG\ ...\fR] [\-\-\ \fISSH_ARGS\fR\ ...]



.SH "DESCRIPTION"

\fB(BETA)\fR \fBgcloud beta compute ssh\fR is a thin wrapper around the
\fBssh(1)\fR command that takes care of authentication and the translation of
the instance name into an IP address.

To use SSH to connect to a Windows VM, refer to this guide:
https://cloud.google.com/compute/docs/connect/windows\-ssh

The default network comes preconfigured to allow ssh access to all VMs. If the
default network was edited, or if not using the default network, you may need to
explicitly enable ssh access by adding a firewall\-rule:

.RS 2m
$ gcloud compute firewall\-rules create \-\-network=NETWORK \e
    default\-allow\-ssh \-\-allow=tcp:22
.RE

\fBgcloud beta compute ssh\fR ensures that the user's public SSH key is present
in the project's metadata. If the user does not have a public SSH key, one is
generated using \fBssh\-keygen(1)\fR (if the \f5\-\-quiet\fR flag is given, the
generated key will have an empty passphrase).

If the \f5\-\-region\fR and \f5\-\-network\fR flags are provided, then
\f5\-\-plain\fR and \f5\-\-tunnel\-through\-iap\fR are implied and an IP address
must be supplied instead of an instance name. This is most useful for connecting
to on\-prem resources.



.SH "EXAMPLES"

To SSH into 'example\-instance' in zone \f5\fIus\-central1\-a\fR\fR, run:

.RS 2m
$ gcloud beta compute ssh example\-instance \-\-zone=us\-central1\-a
.RE

You can also run a command on the virtual machine. For example, to get a
snapshot of the guest's process tree, run:

.RS 2m
$ gcloud beta compute ssh example\-instance \-\-zone=us\-central1\-a \e
    \-\-command="ps \-ejH"
.RE

When running a command on a virtual machine, a non\-interactive shell will
typically be used. (See the INVOCATION section of
https://linux.die.net/man/1/bash for an overview.) That behavior can be
overridden by specifying a shell to run the command, and passing the \f5\-t\fR
flag to SSH to allocate a pseudo\-TTY. For example, to see the environment
variables set during an interactive session, run:

.RS 2m
$ gcloud beta compute ssh example\-instance \-\-zone=us\-central1\-a \e
    \-\-command="bash \-i \-c env" \-\- \-t
.RE

If you are using the Google Container\-Optimized virtual machine image, you can
SSH into one of your containers with:

.RS 2m
$ gcloud beta compute ssh example\-instance \-\-zone=us\-central1\-a \e
    \-\-container=CONTAINER
.RE

You can limit the allowed time to ssh. For example, to allow a key to be used
through 2019:

.RS 2m
$ gcloud beta compute ssh example\-instance \-\-zone=us\-central1\-a \e
    \-\-ssh\-key\-expiration="2020\-01\-01T00:00:00:00Z"
.RE

Or alternatively, allow access for the next two minutes:

.RS 2m
$ gcloud beta compute ssh example\-instance \-\-zone=us\-central1\-a \e
    \-\-ssh\-key\-expire\-after=2m
.RE

To use the IP address of your remote VM (eg, for on\-prem), you must also
specify the \f5\-\-region\fR and \f5\-\-network\fR flags:

.RS 2m
$ gcloud beta compute ssh 10.1.2.3 \-\-region=us\-central1 \e
    \-\-network=default
.RE



.SH "POSITIONAL ARGUMENTS"

.RS 2m
.TP 2m
[\fIUSER\fR@]\fIINSTANCE\fR

Specifies the instance to SSH into.

\f5\fIUSER\fR\fR specifies the username with which to SSH. If omitted, the user
login name is used. If using OS Login, USER will be replaced by the OS Login
user.

\f5\fIINSTANCE\fR\fR specifies the name of the virtual machine instance to SSH
into.

.TP 2m
[\-\- \fISSH_ARGS\fR ...]

Flags and positionals passed to the underlying ssh implementation.


The '\-\-' argument must be specified between gcloud specific args on the left
and SSH_ARGS on the right. Example:

.RS 2m
$ gcloud beta compute ssh example\-instance \-\-zone=us\-central1\-a \-\- \e
\-vvv \-L 80:%INSTANCE%:80
.RE


.RE
.sp

.SH "FLAGS"

.RS 2m
.TP 2m
\fB\-\-command\fR=\fICOMMAND\fR

A command to run on the virtual machine.

Runs the command on the target instance and then exits.

.TP 2m
\fB\-\-container\fR=\fICONTAINER\fR

The name or ID of a container inside of the virtual machine instance to connect
to. This only applies to virtual machines that are using a Google
Container\-Optimized virtual machine image. For more information, see
https://cloud.google.com/compute/docs/containers.

.TP 2m
\fB\-\-dry\-run\fR

Print the equivalent scp/ssh command that would be run to stdout, instead of
executing it.

.TP 2m
\fB\-\-force\-key\-file\-overwrite\fR

If enabled, the gcloud command\-line tool will regenerate and overwrite the
files associated with a broken SSH key without asking for confirmation in both
interactive and non\-interactive environments.

If disabled, the files associated with a broken SSH key will not be regenerated
and will fail in both interactive and non\-interactive environments.

.TP 2m
\fB\-\-plain\fR

Suppress the automatic addition of \fBssh(1)\fR/\fBscp(1)\fR flags. This flag is
useful if you want to take care of authentication yourself or use specific
ssh/scp features.

.TP 2m
\fB\-\-ssh\-flag\fR=\fISSH_FLAG\fR

Additional flags to be passed to \fBssh(1)\fR. It is recommended that flags be
passed using an assignment operator and quotes. Example:

.RS 2m
$ gcloud beta compute ssh example\-instance \-\-zone=us\-central1\-a \e
    \-\-ssh\-flag="\-vvv" \-\-ssh\-flag="\-L 80:localhost:80"
.RE

This flag will replace occurences of \f5\fI%USER%\fR\fR, \f5\fI%INSTANCE%\fR\fR,
and \f5\fI%INTERNAL%\fR\fR with their dereferenced values. For example, passing
\f5\fI80:%INSTANCE%:80\fR\fR into the flag is equivalent to passing
\f5\fI80:162.222.181.197:80\fR\fR to \fBssh(1)\fR if the external IP address of
\'example\-instance' is 162.222.181.197.

If connecting to the instance's external IP, then \f5\fI%INSTANCE%\fR\fR is
replaced with that, otherwise it is replaced with the internal IP.
\f5\fI%INTERNAL%\fR\fR is always replaced with the internal interface of the
instance.

.TP 2m
\fB\-\-ssh\-key\-file\fR=\fISSH_KEY_FILE\fR

The path to the SSH key file. By default, this is
\f5\fI~/.ssh/google_compute_engine\fR\fR.

.TP 2m
\fB\-\-strict\-host\-key\-checking\fR=\fISTRICT_HOST_KEY_CHECKING\fR

Override the default behavior of StrictHostKeyChecking for the connection. By
default, StrictHostKeyChecking is set to 'no' the first time you connect to an
instance, and will be set to 'yes' for all subsequent connections.
\fISTRICT_HOST_KEY_CHECKING\fR must be one of: \fByes\fR, \fBno\fR, \fBask\fR.

.TP 2m
\fB\-\-troubleshoot\fR

If you can't connect to a virtual machine (VM) instance using SSH, you can
investigate the problem using the \f5\-\-troubleshoot\fR flag:

.RS 2m
$ gcloud beta compute ssh VM_NAME \-\-zone=ZONE \e
    \-\-troubleshoot [\-\-tunnel\-through\-iap]
.RE

The troubleshoot flag runs tests and returns recommendations for the following
types of issues:
.RS 2m
.IP "\(em" 2m
VM status
.IP "\(em" 2m
Network connectivity
.IP "\(em" 2m
User permissions
.IP "\(em" 2m
Virtual Private Cloud (VPC) settings
.IP "\(em" 2m
VM boot
.RE
.sp

If you specify the \f5\-\-tunnel\-through\-iap\fR flag, the tool also checks IAP
port forwarding.

.TP 2m
\fB\-\-zone\fR=\fIZONE\fR

Zone of the instance to connect to. If not specified and the
\f5\fIcompute/zone\fR\fR property isn't set, you might be prompted to select a
zone (interactive mode only).

To avoid prompting when this flag is omitted, you can set the
\f5\fIcompute/zone\fR\fR property:

.RS 2m
$ gcloud config set compute/zone ZONE
.RE

A list of zones can be fetched by running:

.RS 2m
$ gcloud compute zones list
.RE

To unset the property, run:

.RS 2m
$ gcloud config unset compute/zone
.RE

Alternatively, the zone can be stored in the environment variable
\f5\fICLOUDSDK_COMPUTE_ZONE\fR\fR.

.TP 2m

At most one of these can be specified:


.RS 2m
.TP 2m
\fB\-\-internal\-ip\fR

Connect to instances using their internal IP addresses rather than their
external IP addresses. Use this to connect from one instance to another on the
same VPC network, over a VPN connection, or between two peered VPC networks.

For this connection to work, you must configure your networks and firewall to
allow SSH connections to the internal IP address of the instance to which you
want to connect.

To learn how to use this flag, see
https://cloud.google.com/compute/docs/instances/connecting\-advanced#sshbetweeninstances.

.TP 2m
\fB\-\-tunnel\-through\-iap\fR

Tunnel the ssh connection through Cloud Identity\-Aware Proxy for TCP
forwarding.

To learn more, see the IAP for TCP forwarding documentation
(https://cloud.google.com/iap/docs/tcp\-forwarding\-overview).

.RE
.sp
.TP 2m
\fB\-\-network\fR=\fINETWORK\fR

Configures the VPC network to use when connecting via IP address or FQDN.

.TP 2m
\fB\-\-region\fR=\fIREGION\fR

Configures the region to use when connecting via IP address or FQDN.

.TP 2m
\fB\-\-dest\-group\fR=\fIDEST_GROUP\fR

Configures the destination group to use when connecting via IP address or FQDN.

.TP 2m

At most one of these can be specified:


.RS 2m
.TP 2m
\fB\-\-ssh\-key\-expiration\fR=\fISSH_KEY_EXPIRATION\fR

The time when the ssh key will be valid until, such as
"2017\-08\-29T18:52:51.142Z." This is only valid if the instance is not using OS
Login. See $ gcloud topic datetimes for information on time formats.

.TP 2m
\fB\-\-ssh\-key\-expire\-after\fR=\fISSH_KEY_EXPIRE_AFTER\fR

The maximum length of time an SSH key is valid for once created and installed,
e.g. 2m for 2 minutes. See $ gcloud topic datetimes for information on duration
formats.


.RE
.RE
.sp

.SH "GCLOUD WIDE FLAGS"

These flags are available to all commands: \-\-access\-token\-file, \-\-account,
\-\-billing\-project, \-\-configuration, \-\-flags\-file, \-\-flatten,
\-\-format, \-\-help, \-\-impersonate\-service\-account, \-\-log\-http,
\-\-project, \-\-quiet, \-\-trace\-token, \-\-user\-output\-enabled,
\-\-verbosity.

Run \fB$ gcloud help\fR for details.



.SH "NOTES"

This command is currently in beta and might change without notice. These
variants are also available:

.RS 2m
$ gcloud compute ssh
.RE

.RS 2m
$ gcloud alpha compute ssh
.RE