SSH Basics

SSH stands for Secure Shell.

It is a network communication protocol that enables two computers to communicate (c.f http or hypertext transfer protocol, which is the protocol used to transfer hypertext such as web pages) and share data.

You typically would use ssh to communicate with an instance/server that is running your application over the internet.

You would want to ensure that when you send commands securely from your local machine to the instance/server

• In order to do this, you would need a private key, which is typically a .pem file
• It can be generated locally with ssh-keygen or via your cloud provider admin panel (e.g. AWS EC2 Key-pair)

Recommended Folder Structure

~/.ssh is the folder to store all your ssh configurations and private keys.

• ~ is shorthand for your "home" directory
• Depending on your OS (mac, flavour of linux), the full path would be:
  • mac: /users/<your-username>/
  • linux: /home/<your-username>/

/                     # Root Directory
  /~                  # Default User Home Directory
    /.ssh             # Hidden System Folder starting with a period (i.e. `.`)
      /personal       # directory to store your personal private and/or public keys files
      /project-1      # directory to store your project-1 private and/or public keys files
      /company-1      # directory to store your work with company-1 private and/or public keys files
      /company-2      # directory to store your work with company-2 private and/or public keys files

    /config           # text file that is the "master configuration" for ssh. It tells `ssh` how to connect to hosts (i.e. your servers/instances)

    /conf.d           # directory that stores other ssh configurations
      /personal       # configuration directory that will store personal related ssh configs
      /project-1      # configuration directory that will store project-1 related ssh configs
      /company-1     # configuration directory that will store work with company-1 related ssh configs
        /stage.config # text file that stores ssh configs in staging environments
        /prod.config  # text file that stores ssh configs in production environments
      /company-2     # configuration directory that will store work with company-2 related ssh configs

note

The period . in .ssh indicates that this file is hidden

In your termainal, try execution the following command:

• ls (list files and folders)

  • you would not see .ssh in the output

• ls -a

  • you woud see .ssh in the output
  • -a option means "all", so the output will include folders starting with .

Anatomy of a single SSH Config

The following shows a the options available in a typical SSH config.

Host <name of the server/instance>
 HostName <ip.address>
 IdentityFile <path/to/your/private_key_file.pem>
 User <user in your instance>
 ProxyJump <name of the bastion host>

The following uses QA environment as an example with placeholders replaced.

Host jodgig.qa.api          # to ssh into this host, you would execute `ssh stage.api`
 HostName 12.34.56.789  # HostName defines the ip address of your instnace/server
 IdentityFile ~/.ssh/jod/stage-john.pem # IdentityFile is your private key to connect
 User ubuntu # the user you are going to be when you connect to your instance/server
  ProxyJump jod.qa.haproxy # ProxyJump is used to connect to the load balancer which then connects to jodgig.qa.api

Config Key	Description	Example Values
Host	human readable customer name of your host. it can be an abbrevation of your the HostName	jodgig.qa.api, github
HostName	string that SSH will output over the network when attempting to esthablish a connection	12.34.56.78, github.com
IdentityFile	path to your private key that your host knows about	.ssh/conf.d/project-a/stage.pem
User	name of the user in your host instance.	ubuntu, root
ProxyJump	name of the bastion host. This is used to connect to the load balancer which then connects to your host instance.	jod.qa.haproxy

note

Different cloud providers have different default User values.

For example:

• AWS default is ubuntu when you use their Ubuntu AMI.
• Digital Ocean default is root.

You can see that we are defining the name of the "Host" to be jodgig.qa.api

• You can call it asd and you would be able to execute the command ssh asd

Connect to host

Connect to your host by executing the command in your terminal:

ssh jodgig.qa.api

Using VSCode to edit

You would want to use your code editor so that you can easily create/edit your ssh config files.

Via mouse-click

1. Open up VSCode
2. Open Folder
3. Ensure to select the folder to ~/.ssh

If you are using Project Manager or Project Dashboard extensions, you can add the folder there for easy access in the future

Via terminal

If you load VScode via terminal (e.g. WSL), you can simply execute code ~/.ssh