GUI operation
The GUI is a just a Perl/Tk front end (localProxy.pl) to the Perl program
(the 'back end', or 'engine', in localProxy2.pl) which does all the work.
The back end may not be running on the same computer as the GUI (use 'Connect'
to connect and disconnect from the various back ends you may have running).
Start the GUI in your preferred manner:
- Double-click the localProxy.pl file, or a shortcut to it.
- Run localProxy.pl in a command window
- Run localProxy.pl from the 'Start' menu
You will see two icons open on your task bar. The first is the GUI log
window, and the second is the real GUI graphics window. The first of these
(will stay minimized and) is the log window for the GUI. This is the place
to look for messages when the GUI doesn't seem to do what you expected.
Otherwise, this window may be ignored. The graphics window will open up
on the screen. Die-hard command line users (and Unix system shell users
without Tk) may run the back end (localProxy2.pl) directly (try it with
-h, for help, or use the usual perldoc to see embedded documentation). The
GUI window displayed is, by default, the simple one. The advanced window
(click 'Advanced') offers most of the options described below.
Normal use
Select a configuration to use, or use 'AutoConfigure' (and follow the instructions).
Click 'Start services'
Wait for that button to turn green
LP is then ready for use
Configure your browser to use the HTTP proxy on localhost, port 10080 and
browse the uncensored web, or convince your Usenet News client (Outlook
Express, maybe?) that there's a news server on localhost, port 10119 and
see some real uncensored Usenet News - the best resource the Internet has
to offer, IMHO.
By default, LP as distributed builds a proxy autoconfiguration service - http://<back
end address>:10079/proxy.pac. This service does some ad-zapping, different
LP services for certain hosts (e.g. PROPFIND proxies for hosts like hotmail.com),
etc. Hard to debug when it goes wrong.
First time only, or to reinitialize your entire network configuration
If you know any proxies that your ISP has given you to use, enter them
in the 'Proxy hints (fqdn/IP) for AutoConfig and Test/merge' field. The
format could be something like:
proxy1.emirates.net.ae:8080, 194.170.1.234:8080
Press 'AutoConfigure' and wait for the firewall rules to be analyzed.
A message box will inform you that the AutoConfiguration is finished (but
you should be aware that the proxies you specified may still be under test
- see below). If this is your first use of LP, you probably should wait
for the proxy tests to complete, but otherwise you may proceed (the firewall
data is known, but the updated proxy speed data will not be available until
the next build after the tests complete).
When the 'auto' configuration appears in the configuration list, select
it.
Click 'Start services'
Refresh your network configuration (proxy tests etc.)
This should be done periodically, especially if I can't reach these proxies
to test (because of firewall blocks, for example).
This is (for now) the *only* way that dead proxies you have merged into your
configuration can be 'demoted' properly and eventually (after about 3 non-connection
results) disabled.
Enter any proxies you know of in the 'Proxy hints (fqdn/IP) for AutoConfig
and Test/merge' field using the format above.
Click the 'Test and merge user proxies' button. The proxies you entered will
be tested and the results merged into the currently selected configuration.
Watch the GUI log window to see when these tests are complete. Note that
although the GUI is busy, the localProxy engine is still running and usable
while these proxy tests are being done (that may take a minute or two per
proxy).
Be careful with this. If you add a proxy here, and even one test result is
positive on one occasion, it will be merged into your configuration.
After that, localProxy will assume you have access to that subnet (you told
it that proxy was part of your configuration, after all). This will continue
until you retest (several times) and localProxy (actually mergeHosts.pl)
is able to disable the proxy in your configuration. A quicker way is to simply
edit it out of the XML file.
Advanced use
Before running the back end, you may enter the port numbers for any services
you wish to leave out of the build into the 'Build config without these services'
field (see below).
When running ...
Select a service. The commStrats should appear in the next window.
Select a commStrat. The layer 0 and layer 1 windows will fill with proxies.
You may enable/disable localProxy services, commStrats, or proxies, by
selecting the entry you wish to disable and then clicking in the neighboring
checkbox ('this ... is disabled').
You may disable/enable all of them at once using the 'Disable/enable all'
checkbox. Layer 0 and 2 hosts (proxies or redirectors) should always have
ports which are directly accessible from where you are (port 8000, 12000
etc.). The program checks for this when you do an 'AutoConfigure', or as
you browse. Press 'Start services' to start the localProxy back end in another
window (minimized on the task bar). On Windows systems, it might have a
small yellow ball in it. Don't confuse it with the other one which started
when you started the GUI. Both of these will show log messages, one from
from localProxy (the GUI) and the other from the back end (localProxy2.pl).
You cannot enter commands in either of these windows. Advanced users will
try ctrl-break in the localProxy2 log window, and this will work (it will
toggle debug mode), but note that it will close the GUI. I guess this is
handy if you want to run localProxy, modify the configuration and then close
down the GUI and it's log window.
GUI options
Some of the GUI options are:
- 'Get statistics' - will query the back end directly and display a list
of errors, access denied, timeouts etc. sorted by service/commStrat/host.
- 'Run setup script' - This will look for a file called script-<config
name> (.bat extension is added on Windows systems) and run it in the default
command shell. Normally, one would make this a Perl script, to login
to remote shells and run redirectors etc. which the LP build will use.
- 'Show running config' - will query the back end directly and display
the *complete* running configuration. This is the data which will be saved
in config-last.xml when the back end is shut down. The data is displayed
in the form of a scrollable tree. All data in use is available here. The
most interesting bits are the numeric only keys ('nodes' in the tree). The
top level ones (like 22, 53, 10022, 10080 etc.) are the services being offered
by localProxy. Under each of those are the (numeric only, again) active
commStrats. Under those are the active layers (0 and 1 only). Under each
of those are the indexes of the hosts/services in use. Under each index is
the host information, including enabled status, address:port, speed, error
etc. The overall error statistics are available from the top level under
'pathStats'.
- 'Log all' - will log *all* data (including binary, stringified appropriately)
passing through localProxy. Very enlightening sometimes. If you don't have
a network sniffer, you need this. All incoming data is always logged; outgoing
data is logged as well, when it has been changed by localProxy (e.g. commStrat
2 URL modifications).
- 'Train me' - will start a web browser with a random URL. This will
refresh 5 seconds after each page is done. Usually, the browser stops after
a few pages because of some error or a page which doesn't completely finish.
Clicking this several times should start a few browser windows and exercise
localProxy well. If only one starts up, check the 'reuse windows for launching
shortcuts' in the (Internet Explorer) browser settings.
- 'Build Config without these services'
This field allows the user to temporarily disable the building of the
specified services at the next localProxy build, if the selected config
is not a prebuilt one (i.e. not 'last', 'saved' or 'auto'). For example,
User0 has a DNS service enabled all the time, but I normally would not build
it in. If I disable it in the config, then I must reenable it there whenever
I want to use it, but if I disable it in the GUI, it can be allowed to build
the next time by just removing that entry (or leaving it empty). To do this,
I can just enter 53 in that field.
As another example, I have an anonymous HTTP proxy (on 10082) enabled by
default in the 'wayne-dialup' configuration. There is also a PROPFIND service
enabled by default (10077). To build without these, I can enter 10082, 10077
into this field and LP back end will not waste time sorting proxies for
these services. Some memory resources will be saved as well.
Note 1: This is not the way to do it if you want to disable these services
permanently. Do that by setting 'isEnabled' to 0 in your configuration file,
or by overloading the 'isEnabled' value in services.xml with 0.
Note 2: This is not the same as disabling a service using the checkboxes
over the other side of the GUI window (they can be used to disable and enable
services, commStrats, proxies when the LP back end is already running).
- 'Proxy string (fqdn/IP) for AutoConfigure and Test/merge'
When the autoconfiguration happens, LP uses whatever information it has
to find your proxies, name servers, gateways, firewall subnets etc. In many
cases, none of that information can lead it to discovering your proxies.
You may enter 'hints' for this purpose in this field. LP will ensure that
your firewall subnets include these addresses, and will ensure that these
proxies are checked and the results merged into your new 'auto' configuration.
This field also allows users to enter proxies to be tested and added to the
current configuration. This option is for use mainly by users who have ISP
proxies which are untestable from outside (so the localProxy database capabilities
are not reliable).
- 'Uncensored' - 'Raw/Censored'
At startup, localProxy offers a non-censoring HTTP proxy service on the
default proxy port (10080). This service is the one normally used by browsers.
This button will change that default service to a raw (and probably censored)
HTTP proxy service which uses your ISP proxies directly. One might do this
because they are fast, and switch back to uncensored mode when you need to.
Or simply to test what happens when localProxy is 'out of circuit'. You must
have built the running configuration with a 'rawHttpProxy' service class
to be able to use this button. No web browser changes are required. See comments
on the 'Anonymous' button for extra details. Note that, unlike most buttons,
these indicate the *current* state, not the state to which you move after
pressing.
- 'Anonymous' - 'Not anonymous'
This button will make your browsing anonymous. You must have built with
both the 'non-censoring HTTP proxy' service and the 'anonymous HTTP proxy'
service. The button simply swaps the two services so that your browser (assuming
it's proxy is on 10080) now uses the service built using anonymous commStrats
and proxies. See comments on the 'Uncensored' button for more details.
- 'last' configuration (not a button)
When localProxy2 shuts down (the 'stop services' button), it saves all
of it's parameters in a file like config-last.xml (one file for all configurations).
This config will start the back end and tell it to read that last file back
in. The speeds are restored and localProxy will continue as before with
the exception that the speeds are all marked with a larger 'error'
than previously, so all hosts will get tried more often than you might expect.
The idea behind this is that the network dynamics *will* have changed
since the last session, so localProxy should reexamine any speeds it reloaded,
at least once.
- 'Save running configuration'
Similar to 'last', but this one is created whenever you press 'Save running
configuration' in the GUI.
This option also creates a file called 'localInfo-saved.xml' which contains
any proxies localProxy could not connect to duting the build, or during it's
use. This file can be checked using statProxy and the results merged back
into the configuration file to ensure the most up to date build information
for localProxy's next build.
- 'Add plugin service'
This can be used to add a new service to a running localProxy back end. The
window which pops up asks for the service type (a list from services.xml),
the local (to the back end) port to listen for requests on, the remote service:port
for the service, and a user-friendly name for the new service. The remote
service:port may be left empty for any services (e.g. a new httpProxy service,
which will use multiple proxies in the final layer). In this case, it defaults
to the values I have entered into services.xml. Similarly, if the just port
is left out, the default will be used. There's an example here.
- 'Connect/Disconnect' - The back end and the GUI are entirely separate
programs, and may run on different computers. This allows a single GUI to
connect and control multiple back ends. Note that *if* the GUI is connected,
and the user clicks 'Exit', the connected back end will be shut down.
- 'Debug level' - The LP back end has extensive debugging output available.
This controls the verbosity of that output. Set to debug level three for reporting
errors, please.
- 'Freeze' - Several sliders are presented. One for the selected service,
one for the selected layer 0 host currently selected service.commStrat and
one for the selected layer 1 host for the currently selected service.commStrat.
The freeze level determines how careful LP is in selecting the fastest of
these items to use. At the lowest level, LP places no emphasis at all on selecting
higer speed proxies, while at the higher values, it will almost always select
only the highest (effective) speed service and/or proxy. Level 2 (default)
is a good compromise.
- 'Authentication' - This button allows the user to see the challenges
received by the back end, and to edit a username and password into the back
end running database. The edited challenge line may be copied to the user
configuration for automatic use in all future LP builds.
- 'Disable/enable all' - This allows the user to quickly disable *all*
services, commStrats, and hosts in use by LP. The normal use would be to then
enable just the service, commStrat(s) and host(s) the user wants to use.
Note that use of this check box again will enable everything, even those services,
commStrats, or hosts that LP disabled at build time (for example, when there
were no available hosts). This may cause warnings later.
- 'This (Service|CommStrat|Layer 0 host|Layer 1 host) disabled' -
Should be checked to disable the selected item. Useful for testing, and to
disable commStrat 2 when necessary. If the user knows, in advance, that a
selected proxy will not work properly, or sees in the logs that LP needs
help, then this can be used to disable such a proxy (but the right way is
to use statProxy to test that proxy, mergeHosts the results to the user config
file, restart - send the statProxy results to me for inclusion in the main
database please!).