User Tools

Site Tools


evergreen-user:configuring_a_proxy_for_the_staff_client

Why Use SSH Tunneling as a Proxy for the Staff Client?

Here are some reasons you might want to send the staff client's network traffic through an SSH proxy:

  • Firewalls may be preventing you from reaching the server. This may happen when you are connecting the staff client to a test server that should not be available generally, or it may be the result of network design priorities other than ease of use.
  • You may wish to improve security when staff client traffic is susceptible to eavesdropping. This is especially true when wireless is otherwise the best option for connecting a staff machine to the network.

How To Set Up an SSH Tunnel

You will need a server that allows you to log in via SSH and has network access to the Evergreen server you want to reach. You will use your username and password for that SSH server to set up a tunnel.

For Windows users, one good solution is PuTTY: a free telnet/ssh client. When setting up a PuTTY session:

Setting up an SSH tunnel in PuTTY

  1. Use the menu on the left to go to Connection > SSH > Tunnels.
  2. Enter 9999 in the "Source port".
  3. Choose "Dynamic". Do not enter anything in the Destination text entry box.
  4. Click the "Add" button. "D9999" will now appear in the "Forwarded ports" list.
  5. Use the menu on the left to go back to "Session", and enter the host name of the SSH server.
  6. A window will open up so that you can enter your username and password. Once you are logged in, the tunnel is open.

For other client operating systems, How to set up SSH (for the beginner) has excellent advice.

How to Configure the Evergreen Staff Client to Use the SSH Tunnel - SAFE METHODS

In order to tell the Evergreen Staff Client that all traffic should be sent through the SSH tunnel you just configured you have three options.

Log in without proxy, configure with about:config

If you can log in without the proxy temporarily, use about:config to configure the proxy. You will want to set the following options:

  • network.proxy.type - Set to 1 (default is system, which bypasses the other configurations)
  • network.proxy.socks - Set to localhost
  • network.proxy.socks_port - Set to 9999

Restart the client and you should be using the proxy.

Edit prefs.js

If you need the proxy to log in you can edit your local preferences. This is per-user. You will need to run the staff client at least once first.

In your profile folder you should have an AppData or Application Data folder, possibly with a Roaming folder. Inside of that should be a folder like this:

OpenILS\open_ils_staff_client\Profiles\bf8bsk0o.default

The last component will vary. Edit the prefs.js file to add the following lines, probably at the end of the file:

pref("network.proxy.type",1);
pref("network.proxy.socks","localhost");
pref("network.proxy.socks_port",9999);

Create a proxy.js defaults file

If you want a system-wide proxy, regardless of user, you can change the Evergreen defaults. Create a new file named proxy.js in the "defaults/preferences" folder for your client install:

proxy.js
// Proxy configuration
 
pref("network.proxy.type",1); // 5 is system, 4 is auto-detect.
pref("network.proxy.socks","localhost");
pref("network.proxy.socks_port",9999);

Start and/or restart your client and it should be using the proxy.

How to Configure the Evergreen Staff Client to Use the SSH Tunnel - DANGEROUS METHOD

AVOID THIS METHOD AT ALL COSTS
This method breaks upon upgrades of XulRunner itself and may cause automatic updates to fail on later versions of Evergreen.
I am leaving it here for reference purposes of how not to do this.

In order to tell the Evergreen Staff Client that all traffic should be sent through the SSH tunnel you just configured, edit the all.js file, usually located at C:\Program Files\Evergreen Staff Client\greprefs\all.js. Search this file for the word socks.

The SOCKS section of all.js, before changes

Make the following changes:

  1. Change the value of network.proxy.socks from "" to "localhost".
  2. Change the value of network.proxy.socks_port from 0 to 9999.

The SOCKS section of all.js, after changes

Save the all.js file.

If everything is working correctly, you should now be able to run the Evergreen Staff Client and all its data will be sent encrypted through the SSH tunnel you have just configured.

evergreen-user/configuring_a_proxy_for_the_staff_client.txt · Last modified: 2012/02/26 16:58 by tsbere

© 2008-2017 GPLS and others. Evergreen is open source software, freely licensed under GNU GPLv2 or later.
The Evergreen Project is a member of Software Freedom Conservancy.