Using OpenSSH Client Utilities

Perform common OpenSSH client tasks such as connecting to hosts, copying files, and performing agent, port, and X11 forwarding.

Use the OpenSSH client utilities to connect to a remote system, copy files between systems, remember passphrases, access through a bastion host, load GUI applications, and port forward.

Connecting to Another System Using the SSH Command

Use the ssh command to authenticate, run remote commands, and verify host keys.

By default, each time you use the OpenSSH utilities to connect to a remote system, you must provide a username and password. When you connect to an OpenSSH server for the first time, the OpenSSH client prompts you to confirm that you're connected to the correct system.

Use the ssh command to log in to a remote system or to run a command on a remote system:

ssh [options] [user@]host [command]

In the preceding example, host is the name of the remote OpenSSH server to which you want to connect.

For example, to log in to host04 by using the same username as that being used on the local system, run the following command:

ssh host04

To connect as a different user, specify the username and @ symbol before the remote host name, for example, run:

ssh joe@host04

To run a command on the remote system and return to the local shell, specify the command as an argument:

ssh joe@host04 ls $HOME/.ssh

The ssh command logs you in, runs the command, and then closes the connection.

Example of Connecting to a System

The following examples show how you would connect to a remote host, host04. You would need to confirm the command action before establishing the connection.

ssh host04

The following example output shows the expected output from the preceding command:

The authenticity of host 'host04 (192.0.2.104)'
can't be established.
ED25519 key fingerprint is SHA256:iunRrbwnhwqkUrahjaodhsngtzwtF+RFHEjiaUdYaP8I.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'host04,192.0.2.104' (ED25519) to the
list of known hosts.

When you type yes to accept the connection to the server, the client adds the server's public host key to the $HOME/.ssh/known_hosts file. When you next connect to the remote server, the client compares the key added to $HOME/.ssh/known_hosts to the one that the server supplies. If the keys do not match, you see a warning such as the following:


...
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
Someone could be eavesdropping on you right now (man-in-the-middle attack)!
It is also possible that a host key has just been changed.
The fingerprint for the ED25519 key sent by the remote host is
SHA256:fingerprint.
Please contact your system administrator.
Add correct host key in /home/user/.ssh/known_hosts to get rid of this message.
Offending ED25519 key in /home/user/.ssh/known_hosts:1
Host key for ipa has changed and you have requested strict checking.
Host key verification failed
...

Unless the remote server’s host key has changed for a known reason, such as an upgrade of either the SSH software or the server, avoid connecting to that machine until you have contacted its administrator about the situation.

For more information, see the ssh(1) manual page.

Setting SSH Client Configuration Options for a Host

Create host-specific entries in $HOME/.ssh/config for streamlined connections.

You can set up Host entries in the $HOME/.ssh/config file on a client system. Often usernames don't align on different systems. Sometimes you might use a different key pair to the usual key pair for a particular remote system. To connect more easily with the correct credentials, you can add a host entry similar to the following example:

Host server1
  Hostname server1.example.com
  User remote_user
  IdentityFile $HOME/.ssh/id_sshkeyexample

With the provided configuration entry, the user can run:

ssh server1

The SSH client connects to the remote server server1.example.com with the username remote_user and uses the private key file at $HOME/.ssh/id_sshkeyexample.

This configuration entry lets you connect with the correct credentials each time you want to connect. Without the configuration entry, you would need to enter the following:

ssh -i $HOME/.ssh/id_sshkeyexample remote_user@server1.example.com

You can use the $HOME/.ssh/config file to store other configuration options for any system that you connect to. For example, if you use the ForwardAgent or ProxyJump options often, consider adding entries for these for each host where you use them. See the ssh_config(5) manual page for more information.

Copying Files Between Systems Using the SCP and SFTP Commands

Transfer files securely with scp or interactively with sftp.

Using SCP

Note

In Oracle Linux 9 and Oracle Linux 10, the scp utility defaults to SSH File Transfer Protocol. For more information, see the Security section under the Deprecated Features chapter in Oracle Linux 9: Release Notes for Oracle Linux 9 and the scp(1) manual page.

With the scp command, you can copy files or directories between systems. scp establishes a connection, copies the files, and then closes the connection.

The following examples show how you can use the scp command.

Uploading a local file to a remote system
```
scp [options] local_file [user @]host[: remote_file]
```
The following examples show how to upload a file by using scp:
- Copy testfile to the home directory on host04.
```
scp testfile host04:
```
- Copy testfile to the same directory but change its name to new_testfile.
```
scp testfile host04:new_testfile
```
Downloading a file from a remote system to the local system
```
scp [options] [user@]host[:remote_file] local_file
```
Copying files recursively

The -r option recursively copies the contents of directories.

For example, to copy the directory remdir and its contents from the home directory on remote host04 to the local home directory, you would type:
```
scp -r host04:/home/user/remdir $HOME
```
Note that shell expansion of the $HOME variable can result in unintended file paths if used with the scp command to specify a path on a remote host. Always use the full path to the remote file in an scp command.

Using SFTP

The sftp command is a secure alternative to the ftp command that's used to transfer files between systems. Unlike the scp command, the sftp command provides functionality for you to browse the file system on the remote server before copying any files.

To open an FTP connection to a remote system over SSH, use the following command:

sftp [options] [user@]host

For example, you would open an FTP connection to the system, host04, as follows:

sftp host04

Connecting to host04...
guest@host04’s password: password
sftp>

Type sftp commands at the sftp> prompt.

In the following example, the put command is used to upload the file newfile from the local system to the remote system, then the ls command is used to list it:

sftp> put newfile
Uploading newfile to /home/guest/newfile
foo                                           100% 1198     1.2KB/s   00:01    
sftp> ls newfile
newfile

Type help or ? to display a list of available commands. Type bye, exit, or quit to close the connection and exit the sftp interactive session.

For more information, see the ssh(1) and sftp(1) manual pages.

Using the SSH Key Agent to Remember Passphrases

Load private keys into the SSH agent so you enter passphrases only once per session.

Use the SSH Key Agent to enter the passphrases for any of the SSH keys a single time throughout the login session. In this manner, you avoid the poor security practice of creating SSH keys without passphrases.

After you log in, check that the agent is started:
```
ps -ef | grep -i ssh-agent
```
If the agent is not started, start it by running the following command:
```
eval $(ssh-agent -s)
```
Run the ssh-add command to add any of the SSH keys to the agent. For example:
```
ssh-add $HOME/.ssh/id_sshkey
```
The command prompts you for the key passphrase. The passphrase applies through the entire login session. If you use the key to connect to another system, the prompt for a passphrase no longer appears.

Note

The error message Could not open a connection to your authentication agent indicates that the agent might not be running.
Repeat the command for each key that you want to add.
After adding the keys to the agent, you can open SSH connections to any systems that have the paired public key configured in the authorized_keys file, without being prompted for a passphrase. This behavior applies also to any scripts that are run as the user.

Using SSH Agent Forwarding for Access Through a Bastion Host

Forward the SSH agent through jump hosts without copying private keys to remote systems.

Caution

Enable agent forwarding with caution. Users with escalated privileges on the remote host can access the agent through the forwarded SSH session. Although malicious users can't access the keys directly, they can hijack the agent session and use the keys in the agent to connect to other systems. If you're connecting to a system that might have untrustworthy users, avoid using agent forwarding.

SSH Agent Forwarding is a powerful tool that can help you keep private keys centralized and safe. Avoid copying private keys to other systems as much as possible. SSH Agent Forwarding lets you connect to a remote system and then use the SSH client on that system to connect to another system by using the same key-based authentication but without you needing to copy the private key to the host that you first connected to.

Server-Side Configuration

Change the /etc/ssh/sshd_config file to configure SSH Agent forwarding. On the server, verify the AllowAgentForwarding parameter, which activates SSH agent forwarding and is enabled by default.

Client Configuration

To enable this functionality, you must use the ForwardAgent option when you make a connection to an intermediate system in the chain of hosts that you connect to. You must also have the private key already loaded into the SSH Agent on the primary client host. See Using the SSH Key Agent to Remember Passphrases.

To use SSH Agent Forwarding:

Check that the SSH Agent is running and that the SSH key is loaded. Run the following command on the client system to see what keys the agent has loaded:
```
ssh-add -L
```
Connect to a host using the ForwardAgent=yes option:
```
ssh -o ForwardAgent=yes server1.example.com
```
Use the SSH client on the remote host to connect to another server that has the public key configured in its authorized_keys:
```
ssh server2.example.com
```

Consider adding the ForwardAgent option to a Host configuration entry in the $HOME/.ssh/config file if you use this option often for a particular server. See Setting SSH Client Configuration Options for a Host for more information.

Using ProxyJump for Access Through a Jump Host

Route SSH connections through bastion hosts with the ProxyJump option.

SSH Agent forwarding lets clients connect from one server to the next using key-based authentication without copying the private key to each server in the chain. This approach isn't considered good security practice, because users with the appropriate privileges on the remote server could hijack the agent and use it to connect to other systems without requiring authentication.

Use the ProxyJump option in the OpenSSH client to configure access to remote servers using bastion and jump hosts. The ProxyJump functionality works similarly to an SSH tunnel or port forward, in that it proxies all traffic straight through the jump host. Unlike port forwarding, ProxyJump doesn't require server-side configuration, so only SSH access to the jump host is required.

Configuring ProxyJump

Define ProxyJump hosts in $HOME/.ssh/config or on the command line.

Jump hosts are configured in the $HOME/.ssh/config file. In the following example, the jump host at jumphost.example.com is connected to the internal network and jumps to the host at internal.example.com:

# File $HOME/.ssh/config with example of ProxyJump configuration

Host myjumphost
  HostName jumphost.example.com 

Host myremotehost
  HostName internal.example.com 
  ProxyJump myjumphost

To connect to the remote host via the jump server using the preceding $HOME/.ssh/config file, run the following command:

ssh myremotehost

If you're connecting to remote hosts spontaneously, and don't have ProxyJump settings configured for them in the $HOME/.ssh/config file, you can specify required jump and remote host details by using the following command options:

Using ssh -J

The -J flag is used to specify ProxyJump information on the command line. For example, you might run:
```
ssh -J jumphost.example.com internal.example.com
```
Using ssh -o

The -o flag provides a more general method (not limited to ProxyJump configuration) that can be used to pass options to the ssh command in the format that would be used in the $HOME/.ssh/config file. For example, you might run:
```
ssh -o 'ProxyJump=jumphost.example.com' internal.example.com
```

For more information, see Setting SSH Client Configuration Options for a Host and the ssh(1) and ssh_config(5) manual pages.

Using X11 Forwarding to Load Remote Graphical Applications

Enable X11 forwarding to display remote GUI applications on a local desktop.

X11 forwarding lets a user start graphical applications installed on a remote Linux system so that they display within the desktop environment of the local system. The remote system doesn't need to have an X11 server or graphical desktop environment running, but the local system must have an X11 compatible service running.

Server-Side Configuration

Change the /etc/ssh/sshd_config file to enable X11 forwarding. On the server, verify the following parameters:

X11Forwarding

Allows X11 forwarding. When omitted, the default is no. To enable X11 forwarding, add an entry that sets the value for this parameter to yes.
If you edit the configuration file, you must restart the service for the change to take effect:
```
sudo systemctl restart sshd
```
The remote system must also support running X11 applications and authenticate X11 sessions. The xorg-x11-xauth package is required for this purpose.
```
dnf install xorg-x11-xauth
```
If you have never run a graphical application on the remote server, the first time that you connect to the remote server using X11 forwarding, a warning message is displayed:
```
/usr/bin/xauth: file /home/user/.Xauthority does not exist
```
You can ignore this warning as the .Xauthority file is automatically created.

Client Configuration

Use the -Y option with the SSH client when you connect to a remote server:
```
ssh -Y user@server1.example.com
```
Run a graphical application over the SSH connection by typing the command directly from the SSH terminal. For example, if gedit is installed on the remote system, you might run the following command:
```
gedit &
```
Tip

Use the & operator, as shown in the preceding example, to start the process in the background so that the terminal remains available to you.

Setting Up Port Forwarding Over SSH

Create SSH tunnels for local, dynamic, or reverse port forwarding.

SSH port forwarding creates an encrypted SSH tunnel between a client and a server system.

Three types of SSH port forwarding are available:

Local Port Forwarding: Forwards a port from the client to the SSH server and then to the destination port.
Dynamic Port Forwarding: Creates a SOCKS proxy server for communications across a range of ports.
Reverse Port Forwarding: Forwards a port from the server to the client and then to the destination port.

Why Use Port Forwarding?

Port forwarding lets remote servers to access devices within a private local-area network (LAN) and conversely.

You can use port forwarding to access a service that's not exposed to the public network interface. You might set up a local port forward to access a service (such as a database) on a remote server. The database on the server isn't exposed to the public network interface, but you could create a tunnel from a local machine to the internal database server port. You can then connect to localhost and all traffic would get forwarded across the SSH tunnel to the remote database.

You can use reverse port forwarding to give someone outside the local network access to an internal service. For example, you might want to show a fellow developer a web application that you have developed on the local machine. Because the machine doesn't have a public IP, the other developer can't access the application over the internet. However, if you have access to a remote SSH server, you can set up reverse port forwarding to provide the developer access.

Server-Side Configuration

Edit the /etc/ssh/sshd_config file to configure SSH port forwarding. On the server, at a minimum verify the following parameters:

AllowTCPForwarding

Allows TCP port forwarding. When omitted, the default is yes which enables single TCP port forwards and SOCKS proxying
AllowStreamLocalForwarding

Allows forwarding of UNIX domain sockets. When omitted, the default is yes.

Local Port Forwarding

To create a direct TCP forward tunnel, use the ssh -L option:

ssh -L [bind_address:]port:destination:destination_port [user@]remote_ssh_server

bind_address is optional and assigns a local interface to listen for connections. If omitted, ssh only binds on the loopback interfaces. To bind on all interfaces, you can use 0.0.0.0 or ::.
port - The local port number. You can use any port number greater than 1024.
destination - The IP or hostname of the destination machine. If the destination is on the remote server itself, you can use localhost.
destination_port - Port on the destination machine.
[user@]remote_ssh_server - The remote SSH user and server IP address.

For example, you might run:

ssh -L 8080:localhost:8888 user@192.168.1.20

This command would open an SSH connection to the remote server at 192.168.1.20 and open a tunnel to the localhost port 8888.

Dynamic Port Forwarding

Use dynamic port forwarding to have the SSH client listen on a specified binding port and act as a SOCKS proxy server. You don't need to specify a destination host as all incoming connections on the specified port forward through the tunnel to a dynamic port on the destination machine.

To create a dynamic port forward, use the ssh -D option.

ssh -D [bind_address:]port [user@]remote_ssh_server

Reverse Port Forwarding

A reverse tunnel forwards any connection received on the remote SSH server to the local client network.

To create a reverse port forward, use the ssh -R option.

For local port reverse forwarding:

ssh -R [bind_address:]port:destination:destination_port [user@]remote_ssh_server

For dynamic port reverse forwarding:

ssh -R [bind_address:]port [user@]remote_ssh_server

Oracle Cloud Infrastructure Documentation

Using OpenSSH Client Utilities

Connecting to Another System Using the SSH Command

Example of Connecting to a System

Setting SSH Client Configuration Options for a Host

Copying Files Between Systems Using the SCP and SFTP Commands

Using SCP

Using SFTP

Using the SSH Key Agent to Remember Passphrases

Using SSH Agent Forwarding for Access Through a Bastion Host

Server-Side Configuration

Client Configuration

Using ProxyJump for Access Through a Jump Host

Configuring ProxyJump

Using X11 Forwarding to Load Remote Graphical Applications

Server-Side Configuration

Client Configuration

Setting Up Port Forwarding Over SSH

Why Use Port Forwarding?

Server-Side Configuration

Local Port Forwarding

Dynamic Port Forwarding

Reverse Port Forwarding