Last updated 10 July 2017. Created on 13 April 2016.
Edited by Christopher James Francis Rodgers. Log in to edit this page.

When you are done, you will have created both a 'public key', and a 'private key' at your webhost, and you will have downloaded a copy of the 'private key' to your computer. These are necessary for you to use, for example, a SSH client ('S'ecure 'Sh'ell program) like PuTTY for Windows, or for you to use a SFTP client ('Secure File Transfer Protocol' program) on your computer, since FTP (using a 'File Transfer Protocol' program) is not secure. You can then communicate with your webhost securely, or upload and download files securely.

These instructions will use as an example the 'Control Panel' at the webhost 'Bluehost', and yet, hopefully, your webhost will also have a Control Panel with similar, if not identical, capabilities and interface.

Login to your webhost,
and go to the 'Control Panel'

If you use 'Bluehost',
click the following link,
which will then first have you login,
and then will take you directly
to the Control Panel.
To login, you can use your
domain name as the 'username'.
The password is the one
for the primary webhosting account.

Bluehost CPanel:
https://my.bluehost.com/cgi/cpanel ⎘ 
(Link opens in a new tab/window.)

At your Webhost Control Panel

How to tell if you are
on a Secure webpage.

When you are at the Control Panel page,
look at the top of your browser window
in the address-bar, and make sure
that the URL begins with 'https://'
and not just 'http://'.

There should always be an 's' at the end
of 'http' to indicate that you are using
a 'secure' connection, and that you will be
sending information in an encoded form.

Click the icon "SSH/Shell Access"

On the Control Panel page,
look on the right-side for the heading
'Security'. If you are on a mobile device,
or if your browser window is narrow,
the 'Security' heading will be nearer to
the page bottom.

If icons are not displaying
under the heading 'Security',
click that blue "Security" bar to expand it
so that the various security icons
display below the security bar.

Click the icon "SSH/Shell Access".

Have patience for a few seconds
while the system is granting you access
to the SSH page.

On the 'SSH' page:

If the first sentence of the
second paragraph starts with,
"For security reasons, shell access
is not enabled by default.",
then you have not yet enabled SSH access
for your webhosting account,
but you will in the next section.

If, on the other hand,
near the page bottom,
you have the heading
'SSH Access is: Enabled',
then SSH Access has previously
been enabled for your webhosing account,
and you can jump down to section
At the Page 'SSH', with SSH Enabled" ⤵

Enabling SSH Access
(if it is not already enabled)

You need to have SSH access enabled,
so, if it is not yet enabled,
click the button "Manage SSH Access".

That will open a new browser tab
(or possibly a new browser window)
at the page 'SSH Access Settings'.

If the box to the right of 'SSH Status'
is displaying 'No shell' (or something similar),
click the downward pointing arrow
to the right of 'No shell',
and in the drop-down list,
click "Real shell (bash)" (or something similar).

There are only two choices.
One is for turning SSH access ON
('Real shell (Bash)',
and one choice is for turning it OFF
('No shell').

Click the button "submit".

The page 'SSH Access Settings' reloads,
and should display
'SSH Shell settings set to
/usr/local/cpanel/bin/jailshell successfully.'
(or something similar).

Close the browser tab (or window)
for this 'SSH Access Settings' page.

Back at the page: 'SSH':

If you just enabled SSH access,
then you need to refresh the page 'SSH'.

Refresh the page by clicking
the browser-top icon "⟳";
or by pressing the keyboard key 'F5'.

The page 'SSH' will reload, and
will be different from what is was.
Near the bottom it will have
the heading 'SSH Access is: Enabled'.


At the Page 'SSH', with SSH Enabled

Note your 'Hostname' and 'Username'

Make note of the page-bottom
'Hostname:', and 'Username',
because you will need those two items
for the programs you will use later
to connect to the webhost server,
as for example, 'Filezilla' for SFTP,
and 'PuTTY' for SSH.
(PuTTY is for Microsoft Windows only.)

The 'Password:' is the password
that you used for logging in
to your web-hosting account
to get to your Control Panel.

The basics

The paragraph under the heading
'Manage SSH Keys'
explains the basics of using a SSH key:

"Public and private keys are created together.
Public keys reside on the remote server,
while private keys reside on your
local computer or server. When you attempt
to log in to the remote server, SSH compares
the public and private keys. If they match,
SSH will allow you to log in."

Generating your SSH Keys

Under the heading 'Manage SSH Keys',
click the button "Manage SSH Keys".

At the page 'Manage SSH Keys',
under the heading 'Generate a new key.',
click "Generate a New Key".

At the page 'SSH Key Generator',
it displays:

"The system will now generate a public key:"

In fact, however, both a 'public' key,
and a 'private' key will be generated
at the same time.

'Key Name'
(The default is 'id_rsa'.)

This will be the filename
for both the public key,
and the private key.

In the case of the public key,
it will be created
with the filename extension '.pub'.

In the case of the private key,
it will be created without an extension.

Note aside:
File extensions

In case you did not know,
a filename extension is the 'period',
(also known as a 'dot',)
and the three or four characters
that follow the 'period'
at the end of most filenames.

In rare cases, a filename
will have no extension.
Later in these instructions,
when you will download
the private key file to your computer,
you will see that the file
'id_rsa' has no extension.

In other rare cases,
a filename will only have an extension,
and will not have characters preceding
the extension.
For example, the file '.htaccess',
which resides in the root
of all Drupal installations,
is a file with No 'name'--
the file has only an extension.


Critically important:
If you are using Windows,
set Windows to Display Hidden Files,
and to show All File Extensions.

By default, Windows hides certain files
that it classifies as worthy of being 'hidden'.
And, by default, Windows does not display
certain file extensions.

This is a completely unacceptable situation
for you as you work on your Drupal site,
and you should adjust Windows
to display all files,
and to Not hide file extensions.

Otherwise, for example, you will not be able
to tell whether or not a file that is displaying
to you as 'id_rsa', is actually in fact
a file named 'id_rsa'.pub', or 'id_rsa.txt'.

Also, another problem you will have
if your Windows system has extensions hidden,
is that a file that displays to you,
for example, as 'id_rsa.pub',
might actually be a file named 'id_rsa.pub.txt',
and you will have no way of knowing
why the file does not work for you.

For more information,
and a simple step-by-step guide
on how to make those Windows adjustments,
see the drupal.org page:
Set Windows to "Show hidden files, folders, or drives",
and to NOT "Hide extensions for known file types" ~ drupal.org

(This link opens in a new Tab/Window.)

Key Name

On the 'SSH Key Generator' page,
you can leave the 'Key Name'
as the default of "id_rsa".

The instructions that follow
will be based on using that default filename:
id_rsa

Key names other than 'id_rsa'

If you want to, you can use a 'key name'
other than the default of 'id_rsa'.

In that case, type the name you want to use
into the 'Key Name' text-box.

I do Not know what 'character' restrictions
might be associated with 'key' files,
and I do Not know whether certain characters
might cause compatibility problems
because of your use of certain characters.

But I do know that if you try to use 'spaces'
for the key's filename that you will
get an error with the notice, 'Invalid filename'.

So, to avoid problems in the future,
because of possible incompatibility,
I recommend the following to be safe:
- Use lower-case alphabetic characters (letters),
and do Not use upper-case alphabetic characters.
- Start the name with an alphabetic character.
- Only use lower-case alphabetic letters,
numerals, hyphens (dashes, "-"),
and the underscore character ("_").

'Key Password:'

This is a password that you will need to enter
when you use your SFTP client
(Secure File Transfer Protocol program)
at least once each time you use that program.
You will also need this password
for other SSH programs.

I recommend that you Do Not use
the main password that you use
to login to your web-hosting account.

If you see 'dots' in the password text-box,
it is a sign that you have a password
saved by your browser,
and which the browser has automatically inserted
into the password box
in the browser's attempt to help you out.

Unless you are sure that you know
what password is represented by those dots
(if you are seeing them),
be sure to delete all the dots
before entering a password.

After typing in a password,
you might then see a notice
as to the relative strength
of the password you entered.

For security reasons,
I would recommend that you use
a password with at least 16-characters.

I also recommend that you use
upper-case AND lower-case letters,
AND numerals ("0" to "9"),
AND also 'symbols' ("~!@#$%^&*()_+{}[]").

29-character limit? [2017.03.25]
Bluehost now has a new 29-character limit
on my main account password,
and so, from now on,
and to avoid any possible problems
from having a SSH Key password
that is too long,
I will limit my SSH Key password
to not more that 29-characters.

Make a note of this password, somewhere,
right now.

You are probably on this page because you
are intending on using the private key
immediately, but you may not use it again
for a long time, depending on your needs.

You might feel certain that you will remember it,
but if you don't, you will be forced
to re-experience this page again
sooner than you think. :o)

'Reenter Password:'

This text-box will always be blank.
That forces you to enter it again,
even if your browser had previously saved it,
and had entered it above
in the 'Key Password:' text-box.

Record the password

As mentioned just above,
record the password somewhere convenient,
because you will need to use it
every time you open your SFTP client
(your SFTP program),
and each time you give your SSH program (PuTTY)
a command to 'save', or to 'upload' a file.

'Key Type:': RSA (Default)

Near the top of the page is displayed:

[Quote]
"You can use the DSA or RSA encryption
algorithms to encrypt your key.
DSA performs quicker key generation
and signing, while RSA is faster for
key verification."

I really do not know what all that means.
I can tell you, however, that I have
never had a problem with keys
that I generated using 'RSA'.

'Key Size:'

The options are '1024', '2048', and '4096';
and the default choice is '2048'.

I have been using '4096'
for months now,
without any problem.

Click the button "Generate Key".

The page 'SSH Key Generator' will reload,
and it should report,
'The system successfully generated your key.'

Click the button, "<- Go Back"

Page: 'Manage SSH Keys'

You need to 'authorize' the Public Key.

Notice at the page bottom
that you have generated both
a 'Public' key, and a 'Private' key.

Under the heading 'Public Keys:',
at the far-right of the key's name,
click "Manage Authorization".

Page: 'Manage Authorization'

Click the button "Authorize".

Page: 'SSH Key Authorization'

This page should report,
'The key "id_rsa.pub" has been authorized.'.

Click the button "<- Go Back".

Page: 'Manage SSH Keys'

Under the heading 'Public Keys',
in the row for your public key 'id_rsa',
and under the column 'Authorization Status',
it should now display 'authorized'.

Download Private Key

You do 'not' need to download the 'public key',
but you do need to download the 'private key'.

Here on the "Manage SSH Keys" page,
under the heading 'Private Keys:',
and in the column 'Actions',
click the far-right choice
"View or Download".

Page: 'View or Download SSH Keys "id_rsa"'

Private SSH Key "id_rsa" Open Key:

Click the button "Download Key".

You want to 'Save' this download.
You do Not want it to 'Open with' anything.
(Or, in the case of your using
Internet Explorer as a browser,
you do Not want to 'Run' it.)

For more information on where your browser
saves your downloads, and how to change
the default location for your browser downloads,
go to the Google search: change browser download location.

In the case of my using the browser 'Firefox',
I get a pop-up window titled, 'Opening id_rsa',
with the radio-buttons: 'Open with' and 'Save File'.

That is because I have Firefox set to
"Always ask me where to save files".

Setting Firefox to
"Always ask me where to save files"

If your 'menu bar' is displaying,
click "Tools" > "Options".

If your 'menu bar' is Not displaying,
hold down one of the 'Alt' keys,
and press the key 'T', (for 'Tools'),
and click "Options".

You should now be at the left-column
default menu item 'General'.

On the right-side,
under the heading 'Downloads',
click the radio-button
"Always ask me where to save files".

The setting is automatically saved,
and there is no 'save' button,
so you can now close this tab.

Do whatever you normally do to save a file
onto your computer, as for example,
click the radio-button 'Save file',
or 'Download file', or whatever,
and then click the bottom-right button "OK".

Popup Window: 'Enter name of file to save to...',
(or similarly named window)

Take very careful note of the 'File name' line
at the bottom of this window.

If you have never saved a key
to your computer before,
you will probably have the 'File name:'
id_rsa

In my case, because I have previously downloaded
a public key, the 'File name:' is 'id_rsa.pub',
which is to say, the filename has the extension
'.pub'

Also, in my case, since I have 'Office' installed,
the line below the 'File name:' line,
titled 'Save as type:'
is displaying
'Microsoft Office Publisher Document(*.pub)'.

You want this file to be saved as only:
id_rsa

If your id_rsa filename ends
with the extension '.pub':

  • Option 1 of 2:

    Remove the file extension '.pub'.

    Put double quotation marks ("...")
    around the id_rsa filename, like this:
    "id_rsa"

  • Option 2 of 2:

    Remove the file extension '.pub'
    from the 'File name:' box,
    and for the line titled 'Save as type',
    set that second line to
    "All Files (*.*)".

    If you do not do one of those two things,
    the file could possibly be saved as
    something other than 'id_rsa'.

Click the bottom-right button "Save".

Verify file-name

It is important that you verify
that the downloaded file
was saved onto your computer as 'id_rsa',
and Not as 'id_rsa.pub',
because Filezilla, for example,
will not recognize the file as being proper
if you leave the '.pub' extension.

Assuming that Windows is now set to no longer
'Hide extensions for known file types',
navigate to the location on your computer
where you saved the key file,
and check its filename.

If the file was saved onto your computer
as 'id_rsa.pub', then just delete
the extension '.pub',
and accept/allow this change
at any 'warning' window that might pop up.

You are now done with the page
'View or Download SSH Keys "id_rsa"',
so click the button "<- Go back".

Double-check that the 'Public Keys:'
'Authorization Status' for id_rsa
is 'Authorized', (just in case
you might have forgotten
to do that earlier).

You can now logout of your webhost account.
Admittedly though, at home I usually just close
the webhost Control Panel tab/window
without bothering to logout.
I trust my son's cat well enough, and
the dogs are more than loyal.


The URL for this page is https://www.drupal.org/node/2705941

I myself am glad that I know how
to get back to this page when I want.
I do not have to remember the exact steps
that I originally stumbled around for hours
trying to figure out.

 

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.