# OpenSSH Guide	{#idm72682672}

## Using and configuring OpenSSH on Fedora

###

### Scott Radvan

Red Hat<br />
 Engineering Content Services<br />

&lt;[sradvan@redhat.com](mailto:sradvan@redhat.com)&gt;

### Eric Christensen

Fedora<br />
 Documentation Project<br />

&lt;[sparks@fedoraproject.org](mailto:sparks@fedoraproject.org)&gt;

Copyright © 2010,2013 Fedora Contributors.

The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at <http://creativecommons.org/licenses/by-sa/3.0/>. The original authors of this document, and Red Hat, designate the Fedora Project as the "Attribution Party" for purposes of CC-BY-SA. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

For guidelines on the permitted uses of the Fedora trademarks, refer to [https://fedoraproject.org/wiki/Legal:Trademark\_guidelines](https://fedoraproject.org/wiki/Legal:Trademark_guidelines).

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

Java® is a registered trademark of Oracle and/or its affiliates.

XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.

All other trademarks are the property of their respective owners.

Abstract

The Fedora OpenSSH Guide assists both new and experienced users to understand, use, configure, and secure the OpenSSH implementation of SSH (Secure Shell) in Fedora.

----

# Preface	{#pref-OpenSSH_Guide-Preface}

## 1\. Document Conventions	{#idm56140448}

This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.

### 1\.1. Typographic Conventions	{#idm56072176}

Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.

`Mono-spaced Bold`

Used to highlight system input, including shell commands, file names and paths. Also used to highlight keys and key combinations. For example:

> To see the contents of the file `my_next_bestselling_novel` in your current working directory, enter the **cat my\_next\_bestselling\_novel** command at the shell prompt and press **Enter** to execute the command.

The above includes a file name, a shell command and a key, all presented in mono-spaced bold and all distinguishable thanks to context.

Key combinations can be distinguished from an individual key by the plus sign that connects each part of a key combination. For example:

> Press **Enter** to execute the command.
>
> Press **Ctrl**+**Alt**+**F2** to switch to a virtual terminal.

The first example highlights a particular key to press. The second example highlights a key combination: a set of three keys pressed simultaneously.

If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in `mono-spaced bold`. For example:

> File-related classes include `filesystem` for file systems, `file` for files, and `dir` for directories. Each class has its own associated set of permissions.

Proportional Bold

This denotes words or phrases encountered on a system, including application names; dialog-box text; labeled buttons; check-box and radio-button labels; menu titles and submenu titles. For example:

> Choose System → Preferences → Mouse from the main menu bar to launch Mouse Preferences. In the Buttons tab, select the Left-handed mouse check box and click Close to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).
>
> To insert a special character into a gedit file, choose Applications → Accessories → Character Map from the main menu bar. Next, choose Search → Find… from the Character Map menu bar, type the name of the character in the Search field and click Next. The character you sought will be highlighted in the Character Table. Double-click this highlighted character to place it in the Text to copy field and then click the Copy button. Now switch back to your document and choose Edit → Paste from the gedit menu bar.

The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all distinguishable by context.

**_`Mono-spaced Bold Italic`_** or _`Proportional Bold Italic`_

Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:

> To connect to a remote machine using ssh, type **ssh _`username`_@_`domain.name`_** at a shell prompt. If the remote machine is `example.com` and your username on that machine is john, type **ssh john@example.com**.
>
> The **mount -o remount _`file-system`_** command remounts the named file system. For example, to remount the `/home` file system, the command is **mount -o remount /home**.
>
> To see the version of a currently installed package, use the **rpm -q _`package`_** command. It will return a result as follows: **_`package-version-release`_**.

Note the words in bold italics above: username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.

Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:

> Publican is a _DocBook_ publishing system.

### 1\.2. Pull-quote Conventions	{#idm46047632}

Terminal output and source code listings are set off visually from the surrounding text.

Output sent to a terminal is set in `mono-spaced roman` and presented thus:

	books        Desktop   documentation  drafts  mss    photos   stuff  svn
	books_tests  Desktop1  downloads      images  notes  scripts  svgs

Source-code listings are also set in `mono-spaced roman` but add syntax highlighting as follows:

	package org.jboss.book.jca.ex1;

	import javax.naming.InitialContext;

	public class ExClient
	{
	   public static void main(String args[])
	       throws Exception
	   {
	      InitialContext iniCtx = new InitialContext();
	      Object         ref    = iniCtx.lookup("EchoBean");
	      EchoHome       home   = (EchoHome) ref;
	      Echo           echo   = home.create();

	      System.out.println("Created Echo");

	      System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));
	   }
	}

### 1\.3. Notes and Warnings	{#idm55167040}

Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.

### Note

Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.

### Important

Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring a box labeled “Important” will not cause data loss but may cause irritation and frustration.

### Warning

Warnings should not be ignored. Ignoring warnings will most likely cause data loss.

## 2\. We want feedback	{#idm60494240}

If you find errors or have suggestions for improvement, we want your advice. Submit a report in Bugzilla against the product `Fedora` and the component `OpenSSH_Guide`. The following link automatically loads this information for you: [http://bugzilla.redhat.com/](https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&component=OpenSSH_Guide).

In Bugzilla:

1. Provide a short summary of the error or your suggestion in the `Summary` field.

1. Copy the following template into the `Description` field and give us the details of the error or suggestion as specifically as you can. If possible, include some surrounding text so we know where the error occurs or the suggestion fits.

	Document URL:

	Section number and name:

	Error or suggestion:

	Additional information:

1. Click the Submit Bug button.

# Chapter 1. Introduction	{#chap-OpenSSH_Guide-Introduction}

This chapter introduces _SSH_ (_Secure Shell_), its implementation in the Fedora distribution, how to confirm its installation details, its license, and general details about _OpenSSH_.

## 1\.1. What is SSH?	{#sect-OpenSSH_Guide-Introduction-What_Is_SSH}

SSH is a network protocol that allows secure, encrypted data exchange between two networked hosts or devices. It is primarily used for remote access and configuration of Unix-like operating systems, including GNU/Linux distributions such as Fedora. The nature of Unix-like operating systems is such that the system can be configured nearly completely from the _command line interface_ (_CLI_), whether the administrator or user is physically located at the machine, or from the other side of the planet. The ability to perform configuration remotely in a secure manner is paramount which is why SSH and its derivatives are some of the most pervasive and common protocols found on Unix-like operating systems today.

SSH was first invented in 1995 by Tatu Ylönen, at the Helsinki University of Technology in Finland. This initial implementation is now known as _SSH-1_. Shortly thereafter, an effort was launched to make SSH an Internet standard under the _[Internet Engineering Task Force](http://www.ietf.org/about/)_ (_IETF_) guidelines. This led to the development of an updated protocol, known as _SSH-2_ which, in 1999, the OpenBSD team adopted, refined and continually develops and releases under the name OpenSSH.

## 1\.2. What is OpenSSH?	{#sect-OpenSSH_Guide-Introduction-OpenSSH}

OpenSSH is a free implementation of the SSH tools. It is developed by two developer teams: one that develops it solely for the OpenBSD operating system itself, and another that makes a portable version that can be run on several other operating systems. This portable version is what makes its way into Fedora. Refer to the following list for the [supported operating systems](http://www.openssh.com/faq.html#1.3):

* OpenBSD

* NetBSD

* FreeBSD

* AIX

* HP-UX

* IRIX

* Linux

* NeXT

* SCO

* SNI/Reliant Unix

* Solaris

* Digital Unix/Tru64/OSF

* Mac OS X

* Cygwin

OpenSSH is not only included in general purpose operating systems, but also in several commercial products. The list of [known organizations](http://www.openssh.com/users.html) incorporating OpenSSH into their products includes Cisco, Juniper Networks, Nokia, Apple, and Novell.

OpenSSH is a widely-used and important suite of tools. Providing the ability to securely communicate between and configure hosts, it is released under a free license and has seen adoption across many industry sectors.

## 1\.3. How do I get it?	{#sect-OpenSSH_Guide-Introduction-Getting_it}

OpenSSH is included in a default Fedora installation, unless manually excluded. To confirm that you already have it installed, run the **rpm -qa | grep openssh** command. The output shown here may differ slightly from your output:

	$ rpm -qa | grep openssh

	openssh-clients-6.1p1-6.fc18.x86_64
	openssh-server-6.1p1-6.fc18.x86_64
	openssh-6.1p1-6.fc18.x86_64

The above command queried the RPM package database and the output shows the OpenSSH RPM packages that are installed on the system. Run the **ssh -V** (upper-case 'V') command as another way to find out the installed version:

	$ ssh -V

	OpenSSH_6.1p1, OpenSSL 1.0.1e-fips 11 Feb 2013

If you do not have the openssh package installed, you can install it with the **yum** command. Perform the following command as the root user and follow the instructions to install openssh:

	# yum install openssh

## 1\.4. Why use it?	{#sect-OpenSSH_Guide-Introduction-Why_Use_it}

The OpenSSH suite consists of several tools, which replace older, more insecure tools, as shown in the following table:

Table 1.1. OpenSSH tool replacements

|Old Tool|Replacement|
|-|
|**rlogin, telnet**|**ssh**|
|**rcp**|**scp**|
|**ftp**|**sftp**|

<br />

The above table shows the main networking tools provided by the OpenSSH suite. The older tools in the above table are much less secure as they transmit credentials (such as username and password) in clear text over the network or Internet. These details could potentially be extracted from the data stream and leave the hosts vulnerable to unauthorized access. The encrypted data streams in the OpenSSH tools listed in the table provide an extra layer of security to protecting network details by encrypting the entire transmission, including passwords. This is an important attribute when transmitting credentials over a network, and especially over an untrusted network (such as the Internet).

## 1\.5. License	{#sect-OpenSSH_Guide-Introduction-License}

OpenSSH is released under the free and permissive BSD License. It can be used for any and all purposes, including commercial use.

# Chapter 2. OpenSSH Features	{#chap-OpenSSH_Guide-Features}

This chapter further explains OpenSSH, its features, its included utilities, commands, and their use/purpose.

## 2\.1. Current Features	{#sect-OpenSSH_Guide-Features-Current_Features}

OpenSSH has [many features](http://openssh.com/features.html) that make it the defacto standard for managing computer systems including: strong encryption, X11 forwarding, port forwarding, and strong authentication options including PKI just to name a few.

## 2\.2. The OpenSSH suite	{#sect-OpenSSH_Guide-Features-SSH_Suite}

The OpenSSH suite consists of both server and client tools. A client makes a connection to another machine by connecting to the `sshd` server on the target machine. This section provides a list of the most common tools and commands, briefly describes their function, and shows the Fedora package that provides each tool.

* **scp** - copies files between hosts on a network. It uses **ssh** for data transfer, and uses the same authentication and provides the same security as **ssh**. Provided by the openssh-clients package.

* **sftp** - an interactive file transfer program, similar to **ftp**, but performs all operations over an encrypted **ssh** channel. It can also use many other features of **ssh**, such as public key authentication and compression. Provided by the openssh-clients package.

* **slogin** - a symbolic link to the **ssh** command. Provided by the openssh-clients package.

* **ssh** - the main client program, used for logging into a remote machine and for executing commands on a remote machine. Intended to replace **rlogin** and **rsh**, it provides a secure and encrypted channel between two hosts over a network. Also used as a subsystem to other commands listed here. When using **ssh**, the key exchange and encryption is fully established before credentials (such as username and password) are transmitted. Provided by the openssh-clients package.

* **ssh-add** - adds cryptography and digital signature algorithm (RSA and DSA) identities to the **ssh-agent** authentication agent. Provided by the openssh-clients package.

* **ssh-agent** - a program to hold private keys used for public key authentication. The idea is that **ssh-agent** is started in the beginning of a session, and all other windows or programs are started as clients to it. Provided by the openssh-clients package.

* **ssh-copyid** - a script that uses **ssh** to log into a remote machine and installs your own public key into a remote machine's list of authorized keys. This action provides the ability for future logins with key-based authentication. Provided by the openssh-clients package.

* **ssh-keygen** - a utility that can generate, manage and convert authentication keys. Provided by the openssh package.

* **ssh-keyscan** - a utility for gathering the public ssh host keys of a number of hosts. It can contact several hosts in parallel and is very fast in scanning a collection of hosts for their host keys. Provided by the openssh-clients package.

# Chapter 3. Security	{#chap-OpenSSH_Guide-Security}

This chapter describes the security benefits of using OpenSSH; and shows SSH encryption in action, compared to telnet.

## 3\.1. Benefits	{#sect-OpenSSH_Guide-Security-Benefits}

The primary benefit of using OpenSSH is security. SSH provides encryption when remotely connecting to and configuring a host, and allows the same functionality as the older, less secure tools, and adds more features over them.

OpenSSH is found on several different operating systems, and is interoperable - you are able to expect the capability of running OpenSSH on any Linux machine, and its implementation is very similar in Fedora compared to other Linux distributions.

## 3\.2. SSH Vs. Telnet	{#sect-OpenSSH_Guide-Security-OpenSSH_In_Action}

When using a network connection, essential and complex communication protocols such as TCP (Transmission Control Protocol) and UDP (User Datagram Protocol) take place mostly "behind-the-scenes" and are hidden beneath the user interface. Below the difference between Telnet's insecure, clear-text authentication and the encrypted authentication used by OpenSSH is shown by capturing and analyzing some of the underlying data transfer.

The following image shows a sample packet of connecting to a host via Telnet. Note that the password, **password1**, is clearly displayed in the data stream. This could easily expose the password to anybody analyzing the raw data on the network, leaving a host and its services vulnerable to attack.

![][1]

Compare the above image to the following image, which is a sample of connecting via OpenSSH. As OpenSSH uses encryption when providing credentials, the output is scrambled and is incomprehensible to anybody analyzing the raw packet data.

![][2]

This feature alone is the main reason why utilities such as **telnet** and **rlogin** are considered insecure and outdated. Providing encryption before credentials are sent, OpenSSH can allow for stronger security when communicating over any network, but most importantly over unknown, or untrusted ones.

# Chapter 4. Client Use	{#chap-OpenSSH_Guide-Client_Use}

This chapter describes using and configuring OpenSSH from the client, or user endpoint; TCP flow; connecting without a password; copying files with scp/sftp; running commands on remote systems; and ssh terminal output.

## 4\.1. Config File	{#sect-OpenSSH_Guide-Client_Use-Config_File}

The file for the system-wide client configuration is located at `/etc/ssh/ssh_config`. Open it with your favorite text editor to see the available options. Changes to this file are not necessary for most common uses of **ssh** and its server component, `sshd`; however, to change an option, either comment out the option (with a '#' symbol at the front of the line) to disable the option, or remove the '#' symbol at the start of the line and add an argument to enable the option to your specification.

The ssh\_config manual page (**man ssh\_config**) contains all available options and the effect they have on the system.

## 4\.2. Connection Example	{#sect-OpenSSH_Guide-Connection_Example}

This section provides an example of connecting to a remote host via the **ssh** command. Line numbers have been added here to help explain the actions taken.

	1.  [user1@localhost ~]$ ssh foo.example.com
	2.  The authenticity of host 'foo.example.com (10.0.0.1)' can't be established.
	3.  RSA key fingerprint is eb:63:02:da:88:e5:a6:fc:71:31:15:0b:cd:56:5d:3f.
	4.  Are you sure you want to continue connecting (yes/no)? yes
	5.  Warning: Permanently added 'foo.example.com,10.0.0.1' (RSA) to the list of known hosts.
	6.  user1@foo.example.com's password: *********
	7.  [user1@foo ~]$

* Line 1 shows that the **user1** user on the client system is initiating an SSH connection to a server with the **ssh** command. The server's domain name is **foo.example.com**, but its IP address (10.0.0.1) could be used instead.

* Line 2, 3 and 4 check the key fingerprint of the remote host against local copies, if they exist, in the `~/home/user1/.ssh/known_hosts` file. If none exist for this host, as occurs in the above example, the user is then prompted, after displaying the fingerprint, whether or not to add this record in the same **known\_hosts** file by entering **yes** or **no**.

* Line 5 displays the result, in this case, that the fingerprint has been added to the local file. This mapping will be used in the future when connecting to this host.

* Line 6 in this example shows where the password for **user1@foo.example.com** is entered.

* Line 7 shows the prompt of the remote machine after authentication has been successful. At this point, no matter what authentication technique is in use, the user has access to the remote machine, and it can be configured as though it were a local connection. Of course, the limit of what the user has access to on the remote machine is still dependent on regular permissions and controls.

The following can happen and is possibly not good: TBD..

	@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
	@    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 the RSA host key has just been changed.
	The fingerprint for the RSA key sent by the remote host is
	eb:62:1a:da:38:f5:e6:ec:10:31:17:0b:cf:56:5d:3f.
	Please contact your system administrator.
	Add correct host key in /home/user1/.ssh/known_hosts to get rid of this message.
	Offending key in /home/user/.ssh/known_hosts:11
	RSA host key for foo.example.com has changed and you have requested strict checking.
	Host key verification failed.

# Chapter 5. Server Use	{#chap-OpenSSH_Guide-Server_Use}

Setting up OpenSSH on your server isn't difficult. Most settings are found in the `/etc/ssh/sshd_config` file. It is important to understand the settings in the file, however, as failure to properly configure OpenSSH could lead to your system being vulnerable to attack.

## 5\.1. Server Config	{#sect-OpenSSH_Guide-Server_Use-Server_config}

In your `/etc/ssh/sshd_config` you will see several settings (and some you will not see) for setting up OpenSSH as a service. Information on all possible choices within the `/etc/ssh/sshd_config` can be found by **man sshd\_config**.

The main `/etc/ssh/sshd_config` choices to address include the following:

_Protocol 2_ - Because protocol version 1 contains security vulnerabilities you should make sure that Protocol 2 is the only protocol to be used. To do this make sure that Protocol 2 is uncommented and _Protocol 1_ isn't in the configuration.

_PermitRootLogin_ - Configure remote root login options as follows:

|**yes** Enables access with password and public key|
|**no** Disables all direct remote logins as root|
|**without-password** Allows access with public key authentication only|
|**forced-commands-only** Allows access with public key authentication and only runs configured commands from `~/.ssh/authorized_keys` (in the form of: **allowed-command-name ssh-dsa public-key-string**)|

_PermitEmptyPasswords_ - To explicitly disallow remote login from accounts with empty passwords set this to **no**.

_Banner_ - Text you want displayed on the screen when someone connects to your server. This should point to a file.

_Ciphers_ - Ciphers that OpenSSH will use. The ciphers must be comma-separated for example: **aes128-ctr,blowfish-cbc**. The supported ciphers for Protocol 2 are “3des-cbc”, “aes128-cbc”, “aes192-cbc”, “aes256-cbc”, “aes128-ctr”, “aes192-ctr”, “aes256-ctr”, “arcfour128”, “arcfour256”, “arcfour”, “blowfish-cbc”, and “cast128-cbc”.

_AllowUsers_ - Usernames that can login using SSH listed for example: user1 user2.

_DenyUsers_ - Usernames that cannot login using SSH listed for example: user1 user2.

### Important

You must restart the **sshd** service after editing the configuration files before the settings take place.

## 5\.2. Cryptographic Logon	{#sect-OpenSSH_Guide-Server_Use-Configuring_Cryptographic_Logon}

In this day of hightened security concerns and massive computing power it is more important than ever to utilize every tool we have to prevent unauthorized access to our systems. We've relied on passwords for years and we've learned that users typically don't do a good job with maintaining strong, hack-resistant words and phrases instead gravitating towards simple words or sports team names that are increadibly easy to guess. Enter Public Key Infrastructure (PKI) cryptography for authenticating your users.

Setting up PKI authentication requires changing a couple settings in your `/etc/ssh/sshd_config`. The following commands should be modified to activate PKI authentication:

|_PubkeyAuthentication_ - Uncomment and set to **yes**.|
|_AuthorizedKeysFile_ - Uncomment this as well and make sure it is set to **.ssh/authorized\_keys**.|

### Important

You must restart the **sshd** service after editing the configuration files before the settings take place.

By changing those two settings you have activated PKI authentication! When users put their public key in their `~/.ssh/authorized_keys` the system will try to authenticate them using that key before asking for a password. Want to require the key and not allow users to authenticate with a password? Just change **PasswordAuthentication** to **no** and after restarting the **sshd** service your system should only let people login using their PKI certificates.

# Appendix A. Revision History	{#appe-OpenSSH_Guide-Revision_History}

|**Revision History**|
|Revision 0.2-1|Sun Apr 3 2011|Eric Christensen|
||Added to the Server Use section.|
|Added Cryptographic Logon to the Server Use section.||
|Revision 0.1-1|Wed May 12 2010|Scott Radvan|
||Initial creation of book by publican||

# Index	{#idm36242912}

### F

feedback
:    contact information for this manual, [We want feedback](#idm60494240)

  [1]: ./images/sniff_telnet.png
  [2]: ./images/sniff_ssh.png