openshift-docs/modules/ssh-agent-using.adoc

// Module included in the following assemblies:
//
// * installing/installing_alibaba/installing-alibaba-network-customizations.adoc
// * installing/installing_alibaba/installing-alibaba-vpc.adoc
// * installing/installing_aws/installing-aws-user-infra.adoc
// * installing/installing_aws/installing-aws-china.adoc
// * installing/installing_aws/installing-aws-customizations.adoc
// * installing/installing_aws/installing-aws-default.adoc
// * installing/installing_aws/installing-aws-government-region.adoc
// * installing/installing_aws/installing-aws-secret-region.adoc
// * installing/installing_aws/installing-aws-network-customizations.adoc
// * installing/installing_aws/installing-aws-private.adoc
// * installing/installing_aws/installing-aws-vpc.adoc
// * installing/installing_aws/installing-restricted-networks-aws-installer-provisioned.adoc
// * installing/installing_aws/installing-aws-outposts-remote-workers.adoc
// * installing/installing_azure/installing-azure-customizations.adoc
// * installing/installing_azure/installing-azure-default.adoc
// * installing/installing_azure/installing-azure-government-region.adoc
// * installing/installing_azure/installing-azure-private.adoc
// * installing/installing_azure/installing-azure-vnet.adoc
// * installing/installing_azure/installing-azure-user-infra.adoc
// * installing/installing_azure_stack_hub/installing-azure-stack-hub-default.adoc
// * installing/installing_azure_stack_hub/installing-azure-stack-hub-user-infra.adoc
// * installing/installing_bare_metal/installing-bare-metal.adoc
// * installing/installing_gcp/installing-gcp-customizations.adoc
// * installing/installing_gcp/installing-gcp-private.adoc
// * installing/installing_gcp/installing-gcp-default.adoc
// * installing/installing_gcp/installing-gcp-vpc.adoc
// * installing/installing_gcp/installing-restricted-networks-gcp-installer-provisioned.adoc
// * installing/installing_ibm_cloud_public/installing-ibm-cloud-customizations.adoc
// * installing/installing_ibm_cloud_public/installing-ibm-cloud-network-customizations.adoc
// * installing/installing_ibm_cloud_public/installing-ibm-cloud-vpc.adoc
// * installing/installing_ibm_cloud_public/installing-ibm-cloud-private.adoc
// * installing/installing_openstack/installing-openstack-installer-custom.adoc
// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc
// * installing/installing_openstack/installing-openstack-installer.adoc
// * installing/installing_aws/installing-restricted-networks-aws.adoc
// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc
// * installing/installing_platform_agnostic/installing-platform-agnostic.adoc
// * installing/installing_vmc/installing-restricted-networks-vmc.adoc
// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc
// * installing/installing_vmc/installing-vmc-user-infra.adoc
// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc
// * installing/installing_vmc/installing-vmc.adoc
// * installing/installing_vmc/installing-vmc-customizations.adoc
// * installing/installing_vmc/installing-vmc-network-customizations.adoc
// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc
// * installing/installing_vsphere/installing-vsphere.adoc
// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc
// * installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc
// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc
// * installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc
// * installing/installing_vsphere/installing-restricted-networks-installer-provisioned-vsphere.adoc
// * installing/installing_ibm_z/installing-ibm-z.adoc
// * installing/installing_ibm_z/installing-ibm-z-kvm.adoc
// * installing/installing_ibm_z/installing-ibm-power.adoc
// * installing/installing-rhv-restricted-network.adoc
// * installing/installing_nutanix/installing-nutanix-installer-provisioned.adoc
// * installing/installing-restricted-networks-nutanix-installer-provisioned.adoc


ifeval::["{context}" == "installing-restricted-networks-vsphere"]
:user-infra:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-vmc-user-infra"]
:user-infra:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-bare-metal"]
:user-infra:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-aws"]
:user-infra:
endif::[]
ifeval::["{context}" == "installing-gcp-customizations"]
:gcp:
endif::[]
ifeval::["{context}" == "installing-gcp-default"]
:gcp:
endif::[]
ifeval::["{context}" == "installing-gcp-network-customizations"]
:gcp:
endif::[]
ifeval::["{context}" == "installing-gcp-private"]
:gcp:
endif::[]
ifeval::["{context}" == "installing-gcp-vpc"]
:gcp:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-gcp-installer-provisioned"]
:gcp:
endif::[]
ifeval::["{context}" == "installing-bare-metal"]
:user-infra:
endif::[]
ifeval::["{context}" == "installing-vsphere"]
:user-infra:
endif::[]
ifeval::["{context}" == "installing-vmc-user-infra"]
:user-infra:
endif::[]
ifeval::["{context}" == "installing-aws-user-infra"]
:user-infra:
endif::[]
ifeval::["{context}" == "installing-azure-user-infra"]
:user-infra:
endif::[]
ifeval::["{context}" == "installing-openstack-installer-custom"]
:osp:
endif::[]
ifeval::["{context}" == "installing-openstack-installer-kuryr"]
:osp:
endif::[]
ifeval::["{context}" == "installing-openstack-installer"]
:osp:
endif::[]
ifeval::["{context}" == "installing-ibm-z"]
:ibm-z:
endif::[]
ifeval::["{context}" == "installing-ibm-z-kvm"]
:ibm-z-kvm:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-ibm-z"]
:ibm-z:
endif::[]
ifeval::["{context}" == "installing-rhv-default"]
:rhv:
endif::[]
ifeval::["{context}" == "installing-rhv-customizations"]
:rhv:
endif::[]
ifeval::["{context}" == "installing-platform-agnostic"]
:user-infra:
endif::[]

:_content-type: PROCEDURE
[id="ssh-agent-using_{context}"]
= Generating a key pair for cluster node SSH access

During an {product-title} installation, you can provide an SSH public key to the installation program. The key is passed to the {op-system-first} nodes through their Ignition config files and is used to authenticate SSH access to the nodes. The key is added to the `~/.ssh/authorized_keys` list for the `core` user on each node, which enables password-less authentication.

After the key is passed to the nodes, you can use the key pair to SSH in to the {op-system} nodes as the user `core`. To access the nodes through SSH, the private key identity must be managed by SSH for your local user.

If you want to SSH in to your cluster nodes to perform installation debugging or disaster recovery, you must provide the SSH public key during the installation process. The `./openshift-install gather` command also requires the SSH public key to be in place on the cluster nodes.

[IMPORTANT]
====
Do not skip this procedure in production environments, where disaster recovery and debugging is required.
====

ifndef::osp,ibm-z,ibm-z-kvm,rhv[]
[NOTE]
====
You must use a local key, not one that you configured with platform-specific
approaches such as
link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html[AWS key pairs].
====
endif::[]

ifdef::openshift-origin[]
[NOTE]
====
On clusters running {op-system-first}, the SSH keys specified in the Ignition config files are written to the `/home/core/.ssh/authorized_keys.d/core` file. However, the Machine Config Operator manages SSH keys in the `/home/core/.ssh/authorized_keys` file and configures *sshd* to ignore the `/home/core/.ssh/authorized_keys.d/core` file.
As a result, newly provisioned {product-title} nodes are not accessible using SSH until the Machine Config Operator reconciles the machine configs with the `authorized_keys` file. After you can access the nodes using SSH, you can delete the `/home/core/.ssh/authorized_keys.d/core` file.
====
endif::openshift-origin[]

.Procedure

. If you do not have an existing SSH key pair on your local machine to use for authentication onto your cluster nodes, create one. For example, on a computer that uses a Linux operating system, run the following command:
+
[source,terminal]
----
$ ssh-keygen -t ed25519 -N '' -f <path>/<file_name> <1>
----
<1> Specify the path and file name, such as `~/.ssh/id_ed25519`, of the new SSH key. If you have an existing key pair, ensure your public key is in the your `~/.ssh` directory.
+
[NOTE]
====
If you plan to install an {product-title} cluster that uses FIPS Validated / Modules in Process cryptographic libraries on the `x86_64` architecture, do not create a key that uses the `ed25519` algorithm. Instead, create a key that uses the `rsa` or `ecdsa` algorithm.
====

. View the public SSH key:
+
[source,terminal]
----
$ cat <path>/<file_name>.pub
----
+
For example, run the following to view the `~/.ssh/id_ed25519.pub` public key:
+
[source,termanal]
----
$ cat ~/.ssh/id_ed25519.pub
----

. Add the SSH private key identity to the SSH agent for your local user, if it has not already been added. SSH agent management of the key is required for password-less SSH authentication onto your cluster nodes, or if you want to use the `./openshift-install gather` command.
+
[NOTE]
====
On some distributions, default SSH private key identities such as `~/.ssh/id_rsa` and `~/.ssh/id_dsa` are managed automatically.
====
+
.. If the `ssh-agent` process is not already running for your local user, start it as a background task:
+
[source,terminal]
----
$ eval "$(ssh-agent -s)"
----
+
.Example output
[source,terminal]
----
Agent pid 31874
----
+
[NOTE]
====
If your cluster is in FIPS mode, only use FIPS-compliant algorithms to generate the SSH key. The key must be either RSA or ECDSA.
====

. Add your SSH private key to the `ssh-agent`:
+
[source,terminal]
----
$ ssh-add <path>/<file_name> <1>
----
<1> Specify the path and file name for your SSH private key, such as `~/.ssh/id_ed25519`
+
.Example output
[source,terminal]
----
Identity added: /home/<you>/<path>/<file_name> (<computer_name>)
----

.Next steps

* When you install {product-title}, provide the SSH public key to the installation program.
ifdef::user-infra[]
If you install a cluster on infrastructure that you provision, you must provide the key to the installation program.
endif::user-infra[]

ifeval::["{context}" == "installing-restricted-networks-vsphere"]
:!user-infra:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-vmc-user-infra"]
:!user-infra:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-bare-metal"]
:!user-infra:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-aws"]
:!user-infra:
endif::[]
ifeval::["{context}" == "installing-gcp-customizations"]
:!gcp:
endif::[]
ifeval::["{context}" == "installing-gcp-default"]
:!gcp:
endif::[]
ifeval::["{context}" == "installing-gcp-network-customizations"]
:!gcp:
endif::[]
ifeval::["{context}" == "installing-gcp-private"]
:!gcp:
endif::[]
ifeval::["{context}" == "installing-gcp-vpc"]
:!gcp:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-gcp-installer-provisioned"]
:!gcp:
endif::[]
ifeval::["{context}" == "installing-bare-metal"]
:!user-infra:
endif::[]
ifeval::["{context}" == "installing-vsphere"]
:!user-infra:
endif::[]
ifeval::["{context}" == "installing-vmc-user-infra"]
:!user-infra:
endif::[]
ifeval::["{context}" == "installing-aws-user-infra"]
:!user-infra:
endif::[]
ifeval::["{context}" == "installing-azure-user-infra"]
:!user-infra:
endif::[]
ifeval::["{context}" == "installing-openstack-installer-custom"]
:!osp:
endif::[]
ifeval::["{context}" == "installing-openstack-installer-kuryr"]
:!osp:
endif::[]
ifeval::["{context}" == "installing-openstack-installer"]
:!osp:
endif::[]
ifeval::["{context}" == "installing-ibm-z"]
:!ibm-z:
endif::[]
ifeval::["{context}" == "installing-ibm-z-kvm"]
:!ibm-z-kvm:
endif::[]
ifeval::["{context}" == "installing-rhv-default"]
:!rhv:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-ibm-z"]
:!ibm-z:
endif::[]
ifeval::["{context}" == "installing-rhv-customizations"]
:!rhv:
endif::[]
ifeval::["{context}" == "installing-platform-agnostic"]
:!user-infra:
endif::[]