| Table of Contents |
|---|
Introduction
Some EAS development activities require that the developer access an EAS Linux VM from their Windows machine to perform certain tasks, for example, to administer an EAS VM, or to perform database queries. This page describes how to use PuTTY and Secure Shell (SSH) to access an EAS Linux VM from a Windows machine to achieve those ends.
PuTTY
Download PuTTY media from https://www.putty.org/, and install it on your Windows machine by following the instructions in the PuTTY Setup Wizard. There is also online documentation available, for example PuTTY 0.62.
All of the screenshots that follow are from PuTTY 0.62.
...
SSH
...
1 Run PuTTYgen.
2 Inspect the default parameter values, and then press the "Generate" button.
...
...
4 Replace the default value that is in the Key comment field with your email address, and then enter in the Key passphrase: field, and confirm, a passphrase that you will remember.
| Tip | ||
|---|---|---|
| ||
The file names that are used below follow an optional naming convention of starting with the user's initials (in this example "jd" for Jane Doe), followed by an indication of the scope of the key's applicability (in this example "eas" for the Enterprise Addressing System), to account for a given individual possibly having more than one private key.
|
...
5 Use the buttons to save both the public key (jd_eas_public_key.txt) and the private key (jd_eas_private_key.ppk) somewhere on your Windows machine. It is also worth selecting (right-click, Select All), and then saving, the public key from the Public key for pasting into OpenSSH authorized_keys file: field that is in the PuTTY Key Generator dialog (jd_eas_public_key_paste.txt).
6 Exit the PuTTY Key Generator dialog.
...
7 Request access to one or more EAS Linux VMs, and provide the public key file (jd_eas_public_key_paste.txt) to the EAS administrator who is fulfilling your request. For an example, see service request SER0159691.
SSH
PuTTY can be used to configure and save an SSH session. Navigate to "Chapter 2: Getting started with PuTTY" and read this short chapter before attempting to create an SSH session.
...
...
1 Run PuTTY.
...
...
3 Under the Auth category and in the Private key file for authentication: field, browse to the private key file (jd_eas_private_key.ppk) that was saved in Step 5 above.
4 The remainder of the configuration consists of default values, but if additional configuration is required, then "Chapter 4: Configuring PuTTY" should be consulted.
The following login session names should be used to maintain consistency with standard EAS nomenclature. The login session name for this example (eas-sf-dev-web) is highlighted in bold font in the table below.
...
eas-sf-dev-db
...
| Tip | ||
|---|---|---|
| ||
Database administrators are likely to only be interested in the database machines, so in that case, they will only need to create a subset of all of the possible EAS SSH login sessions:
|
5 Return to the Session category to save this login session. Enter the login session name in the Saved Sessions field, and then press the "Save" button.
6 Before the saved login session can be tested, an EAS administrator must place your public key on the target VM. This should already have been done in Step 7 above.
7 To test the saved login session, select the saved login session from the Saved Sessions list, press the "Load" button, and then press the "Open" button.
8 You will be prompted to log in to the target VM. Use the username that was given to you by the EAS administrator, and when prompted a second time, enter the passphrase that was used to create your private key in Step 4 above.
9 Congratulations, you should now be logged in to the target VM!
...
...
Create an SSH tunnel session if the intent is to access an EAS database from pgAdmin (or another database client product) running on your Windows machine. The SSH tunnel session in this example will be for the SF DEV DB VM (San Francisco data center, DEVelopment environment, eas DataBase server, Virtual Machine). The appropriate IP addresses will be provided by an EAS administrator for any tunnel sessions that you need to create. Sensitive information has been redacted in the screenshots that follow.
| Tip | ||
|---|---|---|
| ||
Both developers and database administrators will want to create SSH tunnel sessions. |
| Info | ||
|---|---|---|
| ||
It is possible that connections to more than one database may need to be active simultaneously, so these SSH tunnel sessions will take advantage of a concept called port forwarding. For example, a developer may be running pgAdmin from her Windows machine and wants to be connected to the development database (SF DEV DB) and the QA database (SF QA DB) at the same time. But both databases will be listening for requests on the same port (for example 5432 is the default port number for PostgreSQL) so the developer needs a way to send database requests from their Windows machine so that they go to the correct database. Port forwarding will let the developer specify that requests to the development database shall go out on local port number 5433 (for example) but get forwarded to port number 5432 on the development database machine. Similarly, requests to the QA database could go out on local port number 5434 but get forwarded to port number 5432 on the QA database machine. It may be helpful to read the first few paragraphs of "Section 3.5 Using port forwarding in SSH" before attempting to create an SSH tunnel session. |
1 Run PuTTY.
...
...
3 Under the Auth category and in the Private key file for authentication: field, browse to the private key file (jd_eas_private_key.ppk) that was saved in Step 5 above.
...
4 The following source port numbers should be used to prevent collisions among them on the Windows machine. The source port number for this example (5433) is highlighted in bold font in the table below.
...
5433
...
5 Under the Tunnels category, and in the Source port field, enter the desired source port number ("5433" in this example), and then in the Destination field, enter the desired destination port, "localhost:5432". (The value for the destination port is the same for all of the database VMs because all of the databases are listening on port number 5432.) Also confirm that the Local and Auto radio buttons are selected. Press the "Add" button to add this forwarded port to the SSH tunnel session.
6 The forwarded port was added to the SSH tunnel session.
7 The following tunnel session names should be used to maintain consistency with standard EAS nomenclature. The tunnel session name for this example (eas-sf-dev-db-tunnel) is highlighted in bold font in the table below.
...
8 Return to the Session category to save this tunnel session. Enter the tunnel session name in the Saved Sessions field, and press the "Save" button.
9 Before the saved tunnel session can be tested, an EAS administrator must place your public key on the target VM. This should already have been done in Step 7 above.
10 To test the saved tunnel session, select the saved tunnel session from the Saved Sessions list, press the "Load" button, and then press the "Open" button.
11 You will be prompted to log in to the target VM. Use the username that was given to you by the EAS administrator, and when prompted a second time, enter the passphrase that was used to create your private key in Step 4 above.
12 Congratulations, you should now have an open tunnel from the Windows machine to the target VM!
...