VPN Setup

From sokwedb
Jump to navigation Jump to search

This page describes how to setup a computer so that it runs the SokweDB VPN, allowing programs on the computer to connect directly to the SokweDB database.

The estimated setup time is 15 minutes. Communication is involved so more than one sitting is required, increasing the total start-to-finish time beyond 15 minutes. The setup time may vary widely, depending on whether you read the entire section on digital identity, how much time you spend talking with the SokweDB administrator, how testing goes, and whether you setup on multiple computers. Time must also be spent on downloading, installing, configuring, and testing whatever database-aware programs you wish to have on your computer.

Note that once you have created a digital identity you should re-use it, on different computers, instead of creating multiple identities.

Navigating the Installation Process

The Initial VPN Setup section can be completed in one sitting, once the SokweDB administrator is in contact so you can get started and agree on a VPN login name. But testing and VPN use will have to wait for the administrator to setup the VPN's server-side.

The SokweDB VPN is constructed from the existing components of your computer's Operating System. This keep-it-simple approach means that there is no installation program, you will need to follow some instructions to get set-up. These involve some cutting and pasting of entire blocks of command lines, the details of which you need not be concerned. MS Windows users will also have to use the mouse to create a shortcut icon on the desktop. Worst-case, someone else can take remote-control of your computer and set things up for you.

When cutting and pasting, cut and paste entire blocks of text as presented in the document, not individual lines. After pasting into a terminal window, the "Enter" key on the keyboard must be pressed.

To simplify the creation of this page, mouse actions are described in writing. For example, writing "click on New->Shortcut" to describe the action of clicking the left mouse button on the "New" drop down menu and then clicking the "Shortcut" choice. You are free to edit this page and provide screenshots if you think it necessary.

Terminal windows must be opened and closed. The next sub-sections describe how to do that.

Opening a Terminal Window

On MS Windows
Click "Start" -> type "wt" -> click "Open"

Older Microsoft Windows installations did not ship Windows Terminal. Users on older systems can download Windows Terminal from the Microsoft Store: Click Search -> type "micosoft store" -> click on Microsoft Store -> Search -> type "windows terminal" -> Click the Install/Get button

On Mac OS/X
Finder -> Go -> Utilities -> Terminal

Closing a Terminal Window

MS Windows
Close the terminal window.
Mac OS/X
Just closing the terminal window does not stop the terminal program. You must "File -> Quit" the terminal program.

Initial VPN Setup

There are 5 steps to initial VPN setup:

  1. Agree on a VPN login name with your SokweDB administrator
  2. Create a digital identity
  3. Email Your Identity to the SokweDB Administrator
  4. Create a desktop icon
  5. Approve the VPN connection

Agree on a VPN Login Name

The VPN requires a login name to authenticate you. Both you and your SokweDGB administrator must know what it is, although it is written into files so neither of you need remember it after your VPN is set-up.

Contact your SokweDB administrator and agree on a VPN login name.

The name must meet Unix login name conventions. Best are names less than 32 characters long, beginning with a letter, consisting of only lower case letters, digits, the underscore character, and the dash character. (No spaces are allowed.)

The VPN login name is needed for the desktop icon creation step.

Having agreed on a VPN login name you can complete the VPN setup on your computer(s). (But note that until the SokweDB administrator has done the server-side setup you will not be able to use the VPN, instead receiving a "Permission denied (publickey)" message.)

Create a Digital Identity

If you already have an OpenSSH public/private key pair you don't need another. Skip this step and go directly to the next step.

About Your Digital Identity

Digital identities are like regular identities, you only want one. Or at least you only want one of any particular type, just as you might have both a driver's licence and a passport.

Feel free to skip the following sub-section unless you have interest.

How it Works

The process described here creates an identity known as a public/private key pair. This identity is stored in files in an OpenSSH compatible data format. These files contain plain text.

As you will see, this makes it easy to inform others of your identity by cutting and pasting the plain text into emails and the like. The recipient then knows who you are and can grant your identity access to protected resources.

Briefly, a key pair identity has two parts, a secret part and a public part, each stored in a separate file. The secret part should be kept safe and never be revealed. The public part can be shared with anyone, it is what identifies you to the other party.

In our application the public part acts like a lock. It protects against unauthorized access, preventing people who are not you from accessing database content. The private part acts like a key, opening the lock and giving you database access.

For added security it is possible to put a password on the secret key part, preventing its use without the password. We don't require this. Others do, so if you already have a key pair your secret key may be password protected.

Steps to Create a Public/Private Key Pair

This section presents text to be cut from here and pasted into a terminal window. When cutting and pasting, be sure to replace the marked text with appropriate identifying information, like your name.

Backup Your Digital Identity (Key Pair)

At this point it is a good idea to backup your identity. The section on installing the VPN on a 2nd computer says what files need copying. The section also, in effect, documents how to restore your identity from a backup.

Again, your private key (file id_ed25519) should be kept secret and secured. Anyone who has it can impersonate you. Keep your backup in a safe and secure place.

Note that USB sticks lose their memory if not plugged in every couple of years.

Email Your Identity to the SokweDB Administrator

Copy and paste your public key into an email to the SokweDB administrator. It wouldn't hurt to remind them of the VPN login name you have both agreed on. They will create a VPN user and get back to you when the server-side of your VPN is ready to use.

Follow these instructions if you don't know your public key.

You may now close the terminal window or otherwise stop the terminal program.

Create a Desktop Icon

You will use this icon to start the VPN. For convenience we are creating it on your desktop. Feel free to move it elsewhere.

Likewise, the icon image is the default. You may change it as desired.

Create a desktop icon on:

Approve the VPN Connection

The first time you use the VPN your computer asks to validate that the server connected to is the server which is expected (and not some malicious computer masquerading as same).

  • Start the VPN with the icon
  • The VPN's terminal window will ask:
The authenticity of host 'sokwe.janegoodall.org (20.119.86.26)' can't be established.
ED25519 key fingerprint is 
SHA256:10oDrQQDHNicqZn2BYBWQpUazSBCO6Hvabuz9GRMmqE.
This key is not known by any other names.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

If your display shows the above fingerprint (the part that begins with SHA256:..) there are no malicious actors and you may type yes. (Press the "Enter" key after.)

If the fingerprint is not exactly the same as that above say no and contact your SokweDB administrator.

NOTE: At this point the SokweDB administrator may or may not have set up the server-side of your VPN. If not, you will get a "Permission denied" message after answering yes or no.

Regardless of whether VPN startup is successful, once you approve the VPN connection by answering yes you will not have to do so again. Or at least not until you install the VPN on another computer.

When done, shut down the VPN and close the terminal.

You have completed the VPN setup. After your SokweDB administrator tells you the server-side is ready, test with your favorite PostgreSQL-aware desktop application.

Showing Your Identity (Your Public Key)

You can always retrieve your public key with the following steps:

  • On MS Windows:
type $HOME/.ssh/id_ed25519.pub
  • On Mac OS/X (or any system supporting bash):
cat ~/.ssh/id_ed25519.pub

The line printed, a long line beginning with "ssh-ed25519", is your public key.

Using the VPN From Multiple Computers

The VPN must be installed on each computer which uses it. This is usually best done by copying from your existing installation (not someone else's files). Don't share your identity or copy someone else's identity files!

Once you have created a digital identity you can re-use that identity on multiple computers. Creating multiple identities leads to confusion and is not recommended.

Take the following steps to use the VPN on another computer.

Copy your Identity

Copy (from a backup?) the identity you have on your old computer to your new computer.

Do not reveal your private key! Do not use a cloud service or other third party to copy your private key onto another computers.

How to copy files and folders between computers is beyond the scope of this document. Minimally, you must copy your public and private key files, the id_ed25519 and id_ed25519.pub files in your ~/.ssh/ folder. But if your second computer does not have a ~/.ssh/ folder, instead copy the entire folder and its contents. The folder to copy, where "YOU" is your login name on your computer, is:

On MS Windows (usually)
C:\Users\YOU\.ssh\

If you use Windows file explorer, the address bar will look something like This PC > OSDisk (C:) > Users > YOU. You can also copy the desktop icon that you created previously.

On Mac OS/X
/Users/YOU/.ssh/

Not only must the ~/.ssh/ folder structure be copied, but the permissions must be copied as well. If permissions are not copied your private key will not be secure and the VPN will then refuse to use it! This is a common cause of Permission denied (publickey) errors. If your copy method does not copy permissions, on Mac OS and Unix-like systems the permissions may be reset manually by running the following command in a terminal: 

chmod g=,o= ~/.ssh ~/.ssh/id_ed25519

It never hurts to run the above command.

Get a VPN Icon onto the New Computer

Copying the SokweDB VPN's icon between computers should usually work. If it does not, create a desktop icon from scratch on the new computer.

Approve the VPN Connection

Approve the VPN connection on the new computer.

Retrieved from "https://sokwe.janegoodall.org/w/index.php?title=VPN_Setup&oldid=336"