Configure web browser (Janus Debugger only)

From m204wiki
Revision as of 19:15, 7 April 2023 by Ekern (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Set up your web browser to use the Debugger Client as a proxy server. Information follows for these individual browser types:

Chrome or Internet Explorer
Firefox
Lynx
Opera

You need the Janus Proxy port number you determined earlier in the preliminary tasks section. The default port is 8081, but you can change this by editing the debuggerConfig.xml file.

Once you define a proxy server for a browser:

  • The Debugger Client must be running in order to operate that browser.

You will need to turn off the proxy in order to use the browser without the Debugger Client. Automatic toggling of the proxy definition is a Client option available for the Chrome and Internet Explorer browsers (only). Otherwise, it may be more convenient to point one browser at the Debugger Client proxy and use a different browser for your other Internet access.

  • While you are debugging, you can use a second tab in your browser to access the Internet while another tab is occupied with User Language debugging. Secured (HTTPS) connections are not allowed. The occupied tab, the tab that invoked the Debugger, continues to remain unavailable for the duration of each debugging session.

Note: If it is not possible or not desirable to change the proxy settings on your web browser, an alternative way to debug web threads is to invoke the Debugger from a command you insert in procedures you run on Janus Web threads.

Chrome or Internet Explorer (IE)

The directions that follow describe Debugger Client modifications to the Internet Properties dialog box on the browser workstation, which affects both Chrome and IE Internet connections.

Note: These instructions were originally prepared for early Client versions that had no features built into the Client to control the browser. It is now recommended that you:

  • Use these instructions for the Client GUI or commands to use to set up Chrome or IE.
  • Do not manually modify the Internet Properties dialog box invoked from the browser except to specify proxy server bypass addresses.

For more information about the Internet Properties dialog box, see Navigating to and within the Internet Properties dialog box.

Automatically setting and removing the proxy definition

To invoke the proxy service automatically without having to manually define it each time (Chrome and Internet Explorer only; for other browsers, you must maintain proxy settings manually):

1. Select Preferences from the Debugger Client File menu to display the Preferences dialog box.

2. In the IE Options area, select the proxy option of IE Mode.

The initial IE Mode setting is none (browser settings are not maintained).

preferences23b

3. Click the Done button.

Now, whenever you start the Client, the Internet Explorer proxy settings are modified automatically, for all running browser instances.
The proxy maintenance feature remains on until you clear the checkbox (it persists between runs of the Client). When you shut down the Client or turn this feature off, the proxy modifications are removed, again for all instances of IE.
Only the following Local Area network (LAN) Settings dialog box settings (see Navigating to and within the Internet Properties dialog box) are modified, and then restored:
  • Use automatic configuration script (if specified) and Address values.
  • Use a proxy server . . . and its address and port.
The next subsection describes how to also include in the automatic maintenance any exception URLs specified to be bypassed by the proxy server.

The Client will automatically specify and enforce the proxy definition when the Client is started. When the Client is closed, the Client will restore the proxy settings to their state before the Client was started.

Handling addresses specified to bypass the proxy server

It is an option of the automatic proxy maintenance to clear and save at Client opening any settings in the "Do not use proxy server for addresses beginning with:" box (accessed this way). The settings for these exceptions are then restored when the Debugger Client is closed (or when the feature is disabled).

To enable this feature, you must select both the IE Mode option proxy and the Clear IE proxy override checkbox in the Debugger Client's Preferences dialog box. The feature is off by default.

Note: If you do enable this feature, then exception URLs you had specified in the Internet Properties "Do not use proxy server for addresses beginning with:" box will now be routed to and passed through the Debugger when the Client is running. If the feature is not enabled (Clear IE proxy override is not selected), the operating system handles these exception URLs and the Debugger never sees them.

In the not very likely event that you want both to enable this feature and to have the exception URLs processed by your original proxy server, you can select the Use existing IE proxy for URLs not to be debugged checkbox in the Preferences dialog box (in addition to the IE Mode option proxy and the Clear IE proxy override checkbox).
In this case, the Debugger will process the exception URLs and pass them to the original proxy server. In fact, this option is designed primarily for troubleshooting purposes, as the Debugger Client Audit Trail page will then contain information about the disposition of these URLs.

Using the Client as proxy exclusively for designated addresses

You can use the Debugger Client as a proxy server only for requests for the hosts (Onlines) specified in the Debugger configuration file, debuggerConfig.xml. The browser is directed to do this host filtering by a script you create (by Client command or UI checkbox). Once this feature is in effect, the Client will act as a proxy server for requests for hosts specified in the script but for no other browser requests.

The JavaScript script (debuggerInternalPac.js) is called a Proxy Auto Config (PAC) file, and it is created by default in the Client work-file folder. If no such work folder is configured, the Client installation folder is used.

The  Client will automatically:

  • Create the PAC script at Client startup.
  • Run the script each time the browser invokes a URL.
  • Remove the script location specification at Client shutdown.

By default, the Client uses a file mode URL format (file://) to locate the PAC file. The Client can also use an HTTP mode URL format (http://), storing the file on a web server. You select file or HTTP mode from the Client GUI or by Client command, as described below.

Note: Caution is recommended when working with PAC files. Errors are not well reported and have the potential to prevent the browser from operating. Be very careful if you edit or create your own PAC files.  Here is a good reference: https://developer.mozilla.org/en-US/docs/Web/HTTP/Proxy_servers_and_tunneling/Proxy_Auto-Configuration_PAC_file

Client steps to invoke the automatic creation and maintenance of a PAC file

  • From the Client GUI:

1. Select Preferences from the File menu, and locate the IE Options area.

2. In the IE Mode box, select either newPac or mergedPac:

  • newPac generates a PAC file from debuggerConfig.xml settings and it modifies the Internet Properties dialog box settings to point to the file. Any existing designated PAC file is ignored.
  • mergedPac generates a PAC file like newPac does, but it merges the freshly generated file with any existing PAC file.

Both newPac and mergedPac enable the PAC Options button if the following are true (as described in the next section, Setting up an HTTP server for PAC files):

  • A supporting web server is defined and running.  
  • The  HTTP file location is identified in the Debugger configuration file.

3. Click the PAC Options button to display the PAC Options dialog:

PacOptions

Select file://URL or http://URL to set the delivery mode for the PAC file. A file-mode URL is the default.

If http, The Client instantly tests an HTTP PUT and GET of a verification file to and from the designated PAC file HTTP server. The Client then displays a Status bar message like the following which reports the result of the test:

HTTP PAC files can be used. 

4. Click the Done button.  

  • By Client command:
Issue the setIEMode command.
Use the newPac parameter to ignore any existing PAC file, or use the mergedPac parameter to merge any existing PAC file with the PAC file freshly generated from the settings in the debuggerConfig.xml file.
If Build 63 or higher, the <http parameter gets the PAC file via HTTP. The default file parameter gets the PAC file from a folder on the local workstation. If you specify http, you must prepare a web server to service the PAC file; see the next section, Setting up an HTTP server for PAC files.
Whether you use the GUI or a Client command, no restart of the browser or the Client is necessary. The browser will run the script for each URL that is invoked from the browser.

Setting up an HTTP server for PAC files

If you will be using HTTP to access a PAC file, you must provide an HTTP (Web) server to hold the PAC files, and you must specify that server's location and port in the Client's configuration file.  

1. Provide a web server.

You can use any web server that supports HTTP PUT and GET. This section provides an example of how to set up a Janus Web Server to handle HTTP-based PAC files. This example is also supplied in a file in the Client's installation folder.
Note: Note that the PAC files are temporary: when the Client starts, a new PAC is generated and uploaded. This prevents the problem of HTTP PAC files being out of date, since they are workstation-based configuration files which can change at any time.
The following SOUL program takes one command line argument, a TCP/IP port number, and it creates a Janus Web server for uploading and serving PAC files:

begin   variables are undefined   local subroutine closeFile(%iFile is string len 8 input)   * Close the file whose name is passed.      %rc is float      $resetn('MSGCTL', 6, %rc)      $close('FILE ' with %iFile)      $resetn('MSGCTL', 0, %rc)   end subroutine   local function openFile(%iFile is string len 8 input) is float      * Open the file whose name is passed and return 0 for success or      * non-zero for failure.      %rc is float      $resetn('MSGCTL', 6, %rc)      openc file %iFile      $resetn('MSGCTL', 0, %rc)      return $status   end function         * Get and validate the command line argument: port number   %args is object stringlist   %args = %(system):arguments:unspace:parseLines(', ')   %portNumber is float     if (%args:count eq 0) then       print 'No port number specified'       stop   elseif (%args:count > 1) then       print 'Too many arguments'       stop   elseif (%args(1) is not like '/2-5(#)') then         print 'Invalid port number'       stop   else      %portNumber = %args(1)   end if   %pacRepo is string len 8 initial('JDPACREP')   %worker is object daemon auto new   %workForDaemon is object Stringlist auto new     * See if memory file for PAC repository is there, if not create it   if (%(local):openFile(%pacRepo) eq 0) then      printText Memory file {%pacRepo} already present      %(local):closeFile(%pacRepo)   else      printText creating memory file {%pacRepo}      text to %workForDaemon = new         ALLOCATE {%pacRepo} WITH MEMORY PAGES=300         CREATE {%pacRepo}         PARAMETER BSIZE=1, DSIZE=250         END         OPENC {%pacRepo}         IN {%pacRepo} INITIALIZE         CLOSE {%pacRepo}      end text      %worker:run(%workForDaemon):print   end if     * Set up a simple Janus web server with web rules for loading   * serving and listing PAC files generated by the debugger client.   %portName is string len 8 initial('JDPACSRV')   * Get rid of any earlier one, so this script can be rerun as needed     text to %workForDaemon = new     JANUS DRAIN {%portName}     JANUS DELETE {%portName}   end text   %worker:run(%workForDaemon)     * Create the server and its rules   text to %workForDaemon = new     * Create a web server     JANUS DEFINE {%portName} {%portNumber} WEBSERV 20 TRACE 7       * Allow PAC file upload via HTTP PUT of URL of format /pacman/xxx.js     JANUS WEB {%portName} -        ON PUT /PACMAN/*.JS OPEN FILE {%pacRepo} RECV *.JS BASE64     JANUS WEB {%portName} ALLOW PUT /PACMAN/*.JS     * Provide HTTP GET access for URLs of format /pacman/xxx.js     JANUS WEB {%portName} ON GET /PACMAN/*.JS OPEN FILE {%pacRepo} -        SEND *.JS BINARY EXPIRE +0       * Start the web server     JANUS START {%portName}   end text   %worker:run(%workForDaemon):print end

Since the PAC files are temporary, they are stored in an in-memory file (not persistent between runs) which does not need any disk files, DD cards, etc. The PAC files are stored as Model 204 procedures. The name of a PAC file procedure created by the Client (see the following sections) is based on the IP number of the Client workstation to avoid conflicts.

2. Update debuggerConfig.xml.

You do this by including the httpPacURL element in the debuggerConfig.xml file.
The following example element suits the sample program in the preceding step (note the use of PACMAN in that program's JANUS WEB commands):

<httpPacURL>http://pacServerHost:pacServerPortNum/pacman</httpPacURL> 

3. Restart the Client, or just issue the retryHttpPac command to test your setup.

The Client must not be in proxy mode if and when you issue the command.
Note: Only when the HTTP server is defined to accept and serve PAC files, and the Debugger Client configuration is updated to identify it, will the PAC Options button be enabled in the IE Options box in the Client's Preferences dialog box (for the newPac and mergedPac options).

Navigating to and within the Internet Properties dialog box

The following directions are provided primarily for information purposes. They show the controls that the Client modifies automatically for Chrome and IE, as described in the preceding subsections. It is recommended that you not make these modifications manually except for any proxy server bypass addresses.

To access the Internet Properties dialog box:

  • From Chrome:
  1. At the right end of the bar that contains the Omnibox navigation control, open the customization menu by clicking the three-stacked-lines icon:

chromeConfigIcon2

  1. In the menu, select Settings.
  2. At the bottom of the Settings tab, click the Show advanced settings... link.
  3. Find the Network section, then click the Change proxy settings... link.
For Windows users, this opens the Internet Properties (or Internet Options) dialog box.
  • From IE:
  1. From the Tools menu, select Internet Options.

To access the proxy server controls in the Internet Properties dialog box:

  1. Select the Connections tab, and click the LAN Settings button.
  2. In the Local Area network (LAN) Settings dialog box, locate the Proxy Server area, then select the "Use a proxy server" checkbox:
    1. In the Address box, the value the Client sets is: localhost.  
    2. In the Port box, the Client sets the proxy listening port number discussed in the introduction above.

To access the proxy server bypass for certain connections:  

  1. In the Local Area network (LAN) Settings dialog box Proxy Server area, click the Advanced button.
  2. In the Exceptions area, in the list box labeled "Do not use proxy server for addresses beginning with," specify the URLs of any locations the Debugger Client should ignore.

Note: You can set up the Client to automatically save and restore these addresses.

Firefox

To set up the proxy for Firefox browsers:

  1. From the Tools menu, select Options > Advanced > Network.
  2. In the Connection box, click Settings.
  3. In the Connection Settings dialog box, select Manual proxy configuration.
    1. In the HTTP Proxy box, specify localhost.
    2. In the adjacent Port box, specify the port number discussed in the introduction above.
    3. Use the No Proxy for box to specify domain names that the browser will access directly, that is, for which the Debugger proxy will be bypassed.
  4. Click OK.

Once defined, the proxy remains in effect whether the Debugger Client is operating or not.


Lynx

The Lynx character-mode browser is fast and handy for testing.  To make it use a proxy, set the environment variable http_proxy to the full URL of the Janus proxy.

Here is a Unix shell script example (running on a PC under Cygwin) that sets this variable and runs Lynx:

#!/bin/bash http_proxy=http://127.0.0.1:8081 export http_proxy env lynx 

Note: The http:// is required.

Once defined, the proxy remains in effect whether the Debugger Client is operating or not.

Opera

To set up the proxy:

  1. From the main Menu, select Settings > Preferences > Advanced > Network > Proxy Servers.
  2. Select the HTTP checkbox, and enter localhost and the proxy listening port number discussed in the introduction above.

Once defined, the proxy remains in effect whether the Debugger Client is operating or not.

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=Configure_web_browser_(Janus_Debugger_only)&oldid=119733"