Waverley Blog

Get Connected to Waverley Client Services (WCS)

Introduction

Waverley Client Services (WCS) are a collection of secure web applications and content designed to give you transparent access to everything happening with your team. These services include:

  • Project wiki website
  • Bug tracking
  • Source control management
  • Email and mailing lists
  • And many more

These services are a private location for you to know everything going on with your projects. Our goal is to give you a powerful set of tools and communication paths so you are never in a position of not knowing where your projects stand.

Please follow all the instructions in this document carefully to ensure you have access to all services. These steps are quite extensive, but are a necessary part of providing a stable and secure foundation for all your projects. These instructions include support for Microsoft Windows, Mac OS X, and Linux platforms.

You will need the following information provided to you in your welcome email when following these instructions. Note that you will not be able to connect to WCS without first receiving this information. The string values for these are used throughout the instructions.

  • CLIENTNAME
  • USERNAME
  • USER_PASSWORD


Security


The security of your computer is of paramount importance. Waverley services are hardened against security breaches through the use of SSH tunnels for access to all services. This leaves the computer you just configured as the weakest link in the chain. It is critical that you keep your SSH private key and passphrase totally secure. A few steps you can take to ensure the security of these items include:

  • Use a very secure passphrase (or password) for your SSH private key. Use at least an 8 character, random, alphanumeric string that is generated by a trusted security application such as PasswordSafe for Windows, or CiphSafe for Mac OS X.
  • Keep any passwords you use in PasswordSafe or CiphSafe as well. It keeps everything in an encrypted file protected by a single passphrase. This of course must use a high quality passphrase as well.
  • Change your passphrase periodically.
  • Configure your screensaver to use a password. This will help prevent access to your computer by others.
  • Configure your computer to use a secure password when starting up. You may also want to configure a password in BIOS for PC systems. This can help prevent access in case of theft or loss.
  • Make sure your SSH private key is not accessible by anyone but yourself.
  • Immediately report any suspicion or loss of your computer to Waverley. We can disable access for that SSH key and issue you a new one.
  • Use separate SSH keys for different computers if you have more than one.

If you would like more details on our security and privacy policies, the latest information is always kept in your wiki website.


Setup SSH Connection


First, we must establish a secure connection for you to use whenever communicating with Waverley services. You will be using a secure tunnel enabled by the Secure Shell (SSH). SSH permits access from your computer using a unique digital certificate (or key) rather than a typical username and password. This technology permits unique identification of any user of the system, and encrypts all traffic sent over the Internet. All Waverley client services (websites, source control, email) are tunneled through this SSH connection.

Please follow the steps for your particular operating system:

Advanced users that fully understand the concepts and tools that can be used to enable SSH tunnels can skip immediately to the Advanced section.


Windows

  1. Download a copy of PuTTY from here. Be sure to select the latest release of the PuTTY Windows Installer program that includes all the PuTTY applications. It’s usually named something like putty-0.60-installer.exe. This package will contain the applications you need including putty, puttygen, and pageant.
  2. Run puttygen to create your SSH keys.
  3. Select SSH-2 DSA as the key type. Make sure 1024 is entered as the key size. Click the Generate button.
  4. Move your cursor around the blank area while the key is being generated to insert randomness.
  5. Enter a very secure passphrase in the Key Passphrase and Confirm Passphrase fields. Do not forget your passphrase, and make sure you follow the security guidelines mentioned earlier. Note that this passphrase is different than the password that was sent to you via email.
  6. Click the Save Public Key button. Create a folder called Waverley, and inside that create a folder called Keys. Save the SSH public key as a file called publickey and click the Save button.
  7. Click the Save Private Key button and save the SSH private key in the same folder as filename publickey you just saved. Be sure to keep your SSH private key very secure as access to it and your passphrase is critical to the security of our services.
  8. Select all the text in the Public Key for Pasting area and select Copy from the Edit menu to place a copy on your clipboard. You can also use the CTL+C keyboard shortcut. Be sure you select the entire text, as some of it will require scrolling.
  9. Send an email to email hidden; JavaScript is required and paste a copy of your SSH public key from the clipboard. You can select Paste from the Edit menu, or use the CTL+V keyboard shortcut.
  10. Quit the puttygen application.
  11. Run PuTTY to configure and open your SSH tunnel.
  12. In PuTTY Configuration, select the Session item on the left pane and enter clients.waverleysoftware.com for the Host Name and under Saved Sessions, 22 for Port, and SSH for Protocol.
  13. Select the Data item under the Connection item on the left pane and enter the USERNAME value sent to you via email for Auto-login Username.
  14. Select the SSH item under the Connection item on the left pane. Select the Protocol option Don’t start a shell or command at all.
  15. Select the Auth item under the SSH item under the Connection item on the left pane and click the Browse button to select your SSH private key. Select the SSH private key file you previously saved.
  16. Select the Tunnels item under the SSH item under the Connection item on the left pane and enter 8001 for Source Port, and select Dynamic. Click the Add button.
  17. If you’ve been provided an email account, select the Tunnels item under the SSH item under the Connection item on the left pane:
    • Enter 2143 for Source Port, localhost:143 for Destination, and select Local. Click the Add button.
    • Enter 2125 for Source Port, localhost:25 for Destination, and select Local. Click the Add button.
  18. Select the Session item on the left pane. Type clients.waverleysoftware.com in the Saved Sessions edit box and click the Save button.

Proceed to the next step only after you receive an email confirmation from Waverley that your SSH tunnel has been enabled.

  1. Click the Open button to start your SSH tunnel. Next time you run PuTTY, be sure to click the Load button before clicking the Open button.
  2. You will be prompted the first time you connect to the server to verify the RSA or DSA fingerprint. The value should be 6e:48:f8:c3:22:2b:c4:86:ec:f6:3c:e1:1f:41:f6:b6 (RSA), or 54:2f:82:c0:0c:c3:33:23:15:f5:1f:69:89:11:13:6e (DSA). Click the Yes button.
  3. You will be prompted for your passphrase whenever the tunnel is created. Use the passphrase you supplied when the tunnel was configured earlier. It is normal for the connection window to not echo the characters you are typing. Just type the passphrase and hit the Enter key. It is normal for a successful connection to report no errors or any status. You can minimize this window if you like.
  4. Now create a desktop shortcut to open the SSH tunnel whenever you need it. Click the Windows Start menu and navigate to the PuTTY application entry. Right click the PuTTY application entry and select Send To and Desktop (Create Shortcut). Now right click the new desktop shortcut and select Properties. Add the text -load “clients.waverleysoftware.com” to the end of the Target field (following the putty string and a space character). Make sure you include the quote characters also. Rename the shortcut clients.waverleysoftware.com and double click this icon whenever you want to create your SSH tunnel.
  5. Run pageant to have PuTTY cache your passphrase and avoid having to repeatedly enter it when creating your SSH tunnel.
  6. The application will add a system tray icon in the lower right that looks like a little hat. Right click on the icon and select Add Key.
  7. Select the SSH private key you created earlier and click the Open button.
  8. Enter the passphrase you created earlier when prompted.
  9. Congratulations, you’ve completed your SSH tunnel steps. Continue with the next section, Configure Browser Access.


Macintosh

  1. Go to the Finder and open an Applications window. Open the Utilities folder. Open the Terminal application.
  2. Type the command ssh-keygen -t dsa and hit the Entry key. Accept the suggested default value for the key file location by pressing the Enter key. Provide a secure passphrase to use whenever an SSH tunnel is created. Do not forget your passphrase, and make sure you follow the security guidelines mentioned earlier. It is normal for the cursor to not move while typing your passphrase. This will create your public and private keys.
  3. Type the command cp ~/.ssh/id_dsa.pub ~/Desktop and hit the Enter key. This will place a copy of your SSH public key on your Desktop.
  4. Send an email to email hidden; JavaScript is required and attach a copy of your SSH public key file (id_dsa.pub) from your Desktop.

Proceed to the next step only after you receive an email confirmation from Waverley that your SSH tunnel has been enabled.

  1. Open the Terminal application again if needed.
  2. Select the Shell menu and choose the New Remote Connection menu item.
  3. Select the Secure Shell (ssh) item listed under Service.
  4. Click the + button under the Server list.
  5. Enter clients.waverleysoftware.com as the server name and click the OK button.
  6. Enter ssh -l USERNAME -D 8001 -N clients.waverleysoftware.com in the command field. The USERNAME value was sent to you via email. Do not enter anything in the User field. If you were provided a Waverley email account, use the command ssh -l USERNAME -D 8001 -L 2143:localhost:143 -L 2125:localhost:25 -N clients.waverleysoftware.com instead, which provides secure port forwarding for IMAP and SMTP.
  7. Click the Connect button.
  8. You will be prompted the first time you connect to the server to verify the RSA or DSA fingerprint. The value should be 6e:48:f8:c3:22:2b:c4:86:ec:f6:3c:e1:1f:41:f6:b6 (RSA), or 54:2f:82:c0:0c:c3:33:23:15:f5:1f:69:89:11:13:6e (DSA). Enter Yes at the prompt and hit the Enter key to continue.
  9. You will be prompted for your passphrase whenever the tunnel is created. Use the passphrase you supplied when the tunnel was configured earlier. It is normal for the connection window to not echo the characters you are typing. Just type the passphrase and hit the Enter key. It is normal for a successful connection to report no errors or any status. You can minimize this window if you like.
  10. Now create a desktop shortcut to open the SSH tunnel whenever you need it. Select the Shell menu and choose the Export Settings menu item. Enter clients.waverleysoftware.com as the file name and save the file to the Desktop. Double click this icon whenever you want to create your SSH tunnel.
  11. Congratulations, you’ve completed your SSH tunnel steps. Continue with the next section, Configure Browser Access.


Advanced


For those that prefer command line access under platforms like Linux, Mac OS X, and Cygwin under Microsoft Windows, here are the steps to follow. You are also welcome to use any other SSH client that supports SSH version 2 and dynamic port forwarding.

  1. Create your SSH keys using ssh-keygen -t dsa.
  2. Email the generated SSH public key ~/.ssh/id_dsa.pub to email hidden; JavaScript is required.
  3. Wait for email confirmation from Waverley that the SSH tunnel has been enabled.
  4. Create the SSH tunnel using ssh -l USERNAME -D 8001 -N clients.waverleysoftware.com in the command field. The USERNAME value was sent to you via email. If you were provided a Waverley email account, use the command ssh -l USERNAME -D 8001 -L 2143:localhost:143 -L 2125:localhost:25 -N clients.waverleysoftware.com instead, which provides secure port forwarding for IMAP and SMTP.

If you’re using a Bash shell, you can setup an SSH config file entry as a shortcut for enabling your SSH tunnel. Place the following lines in your ~/.ssh/config file:

Host clients
 HostName clients.waverleysoftware.com
 LocalForward 59005 localhost:5900
 LocalForward 2143 localhost:143
 LocalForward 2125 localhost:25
 DynamicForward 8001

You can also create a shell script to automatically reconnect your SSH tunnel if it fails, such as when losing a network connection. Create a Bash script file in your path with the following contents. You can then execute the command sshit clients to start the SSH tunnel and keep it open.

#!/bin/bash

while [ 1 ]; do
    ssh $1
    sleep 3
done


Configure Browser Access


You now must configure website access using the SOCKS proxy we provide. This configuration will enable SSH tunneling of traffic to your Waverley client websites, while leaving all other website access using your current configuration.

Proxy Auto-Configuration (PAC) files were sent to you via email that can be used to route Waverley client website access through the SSH tunnel. You should have the following two files:

  • Waverley.pac
  • Waverley_Firefox.pac

You should create a folder called Waverley in your existing default documents folder. This would be My Documents in Windows XP or earlier, or Documents in Windows 7 and Mac OS X. Move the two PAC files into this folder. If you already are using a PAC file with your browser, please look in the Advanced section.

Please follow the steps for any browsers you are using:


Firefox

  1. Launch Firefox.
  2. Set Firefox options.
    • For Windows: Select Options from the Tools menu.
    • For Mac OS X: Select Preferences from the Firefox menu.
  3. Select the Advanced icon and then the Network tab.
  4. Click the Settings button in the Connection section.
  5. Choose the Automatic Proxy Configuration selection and enter the path to the Firefox PAC file. Replace ACCOUNTNAME with the account name on your computer where you placed the two PAC files (not the USERNAME sent to you via email). Note that the file: keyword is followed by 3, not 2, forward slash characters.
    • For Windows XP or earlier enter: file:///C:/Documents and Settings/ACCOUNTNAME/My Documents/Waverley/Waverley_Firefox.pac
    • For Windows 7 or Mac OS X enter: file:///Users/ACCOUNTNAME/Documents/Waverley/Waverley_Firefox.pac
  6. Click the Reload button. You can skip this step if the button is disabled.
  7. Click OK and then close the Preferences dialog.
  8. Enter the text about:config in the Location Bar (where you type URLs) and press the Enter key.
  9. Enter the text network.proxy.socks_remote_dns in the Filter field.
  10. Change the value for this field from false to true by double clicking the list entry for this value.
  11. If you already have a proxy configured, please see the Advanced section below.
  12. Visit http://CLIENTNAME.waverleysoftware.com and verify that your new settings work correctly. Replace CLIENTNAME with the value sent to you via email.
  13. Congratulations on getting everything configured correctly! See Next Steps for what comes next.


Safari for Macintosh

  1. Open System Preferences.
  2. Click the Network icon.
  3. Select Built-in Ethernet from the list on the left.
  4. Click the Advanced button and select the Proxies tab.
  5. Select Using a PAC File from the Configure Proxies dropdown list.
  6. Click the Choose File button.
  7. Select the location and name of the PAC file you saved previously called Waverley.pac.
  8. Click the OK button, then the Apply button.
  9. Select Airport (if available) from the list on the left and repeat steps 4 through 8 again.
  10. If you have created multiple Locations, make sure that the proxy setting is configured for every location you will be using when accessing Waverley client services. This would require repeating steps 3 through 9 for each location you have defined. If you only use Automatic, you can proceed to the next step, as nothing more is required.
  11. If you already have a proxy configured, please see the Advanced section below.
  12. Visit http://CLIENTNAME.waverleysoftware.com and verify that your new settings work correctly. Replace CLIENTNAME with the value sent to you via email.
  13. Congratulations on getting everything configured correctly! See Next Steps for what comes next.


Internet Explorer


Unfortunately Internet Explorer does not properly support SOCKS5 proxy forwarding with remote DNS resolution. Please use Firefox instead. You can download a copy of this most excellent web browser by visiting the Firefox website here. Once Firefox is installed, please continue with the steps for the Firefox browser here.

It may be possible to configure a third-party SOCKS proxy agent for use with Internet Explorer. This approach is untested, but we would love to hear from anyone that wants to experiment and is able to get some type of solution to work.


Advanced


If you already have a PAC file, you will need to manually edit the existing PAC file and add the necessary lines to proxy Waverley websites. Here are the additional lines needed in this case. These instructions assume that there are already a series of URL pattern matching checks to control which sites are forwarded via proxy servers. The keyword SOCKS will need to be changed to SOCKS5 if you are using Firefox.

else if (shExpMatch(url, "http://www.waverleysoftware.com*"))
    return "DIRECT";
else if (shExpMatch(url, "http://*.waverleysoftware.com*"))
    return "SOCKS localhost:8001";

If you already have a proxy manually configured, you will need to edit the existing PAC file to specify when the proxy server should be used. The following example assumes that you have an existing HTTP/Web proxy that should be used for all traffic. Replace hostname and port with your Web proxy settings.

else
    return "PROXY hostname:port";

Proxy Auto-Configuration (PAC) files are scripts that can be used to control when your browser uses proxy servers. The PAC file used for WCS looks like this:

function FindProxyForURL(url, host)
{
  // SOCKS proxy everything to clientname.waverleysoftware.com
  if (isPlainHostName(host))
    return "DIRECT";
  else if (shExpMatch(url, "http://www.waverleysoftware.com*"))
    return "DIRECT";
  else if (shExpMatch(url, "http://*.waverleysoftware.com*"))
    return "SOCKS localhost:8001";
  else
    return "DIRECT";
}

The script says to route traffic over your SSH tunnel whenever you access a URL that begins with your client WCS prefix. The traffic is actually routed through a SOCKS proxy so all your browser communication is handled smoothly. Note that you must change the string SOCKS to SOCKS5 when using Firefox. There is a bug in Firefox that prevents it from using the latest SOCKS v5 protocol unless the SOCKS5 keyword is explicitly used. You can read more about PAC files here, and SOCKS proxies here.


Next Steps


Congratulations on completing the necessary configuration steps. The next step is to visit your client wiki website. Follow this link to get started, replacing CLIENTNAME with the value sent to you via email.

  • http://CLIENTNAME.waverleysoftware.com/wiki/

You will find links and further details explaining all the services available to you as a Waverley client user. Please bookmark and use this website for all communication.

Your wiki account has been created for you using USERNAME and USER_PASSWORD sent to you via email. Make sure you login to the wiki to enable editing of pages. Other accounts also use the supplied USERNAME and USER_PASSWORD, except for Bugzilla, which uses your email address as your username.

Feel free to contact us at email hidden; JavaScript is required if you need any help getting things going.

Share and Enjoy:
  • Twitter
  • Facebook
  • LinkedIn
  • Technorati
  • Google Bookmarks
  • email
  • Print