Starting and stopping Caching Proxy

Caching Proxy is designed to run continuously as a background process with minimal operator intervention. Typically, the proxy server starts during the boot cycle of the machine and is stopped only when maintenance is required. The proxy server may be manually started when necessary. The proxy server can also be passed a restart instruction, which effectively stops then starts the proxy server without disrupting active client connections.

Automatic startup and shutdown on Linux and UNIX systems

On Linux and UNIX systems, an ibmproxy initialization script and associated symbolic links are placed in the appropriate /etc/ directories when Caching Proxy is installed. These scripts are then integrated into the startup and shutdown routines of the operating system. You can change the configuration settings for automatic restart by editing the ibmproxy script and changing the ibmproxy command options.

Note:
Solaris file descriptor limit

It is possible that the Caching Proxy initialization script can fail to set the desired maximum number of file descriptors due to the Solaris systemwide limit on file descriptors. If the systemwide maximum is less than the setting in the Caching Proxy initialization script, then the systemwide limit is used. You can change the file descriptor limit to avoid proxy performance problems that can result from too low a value (less than 1024). Issue the ulimit command to view the number of descriptors that are currently available. If the value is less than 1024, increase the file descriptor limit. To increase the file descriptor limit to 1024, add the following line to the /etc/system file:

set rlim_fd_cur=0x400

Disabling automatic startup and shutdown

To disable automatic startup and shutdown:

Manual startup on Linux and UNIX systems

Regardless of the startup method, the ibmproxy command is eventually invoked, either directly from the command prompt or from within a script. For a detailed description of the ibmproxy command, refer to ibmproxy command. Examples of only the most commonly used arguments follow.

On AIX:

On HP-UX:

On Linux:

Note:
Refer to the support site for IBM WebSphere Application Server for information on running ibmproxy in a Security Enhanced Linux environment on RHEL systems: http://www-01.ibm.com/support/docview.wss?uid=swg21369929.

On Solaris:

Startup as a Windows service

If Caching Proxy is installed as a Windows service, it is started like any other Windows service:

  1. Click Start -> Control Panel.
  2. In the Control Panel window, double-click Administrative Tools -> Services.
  3. In the Services window, highlight Caching Proxy.
  4. Click Start to initiate the Caching Proxy service.

If Caching Proxy is installed as a service, it can be configured to start up automatically when Windows starts. In that case, you do not have to log on before the proxy can serve requests. To have your proxy start automatically:

  1. Click Start -> Control Panel.
  2. In the Control Panel window, double-click Administrative Tools -> Services.
  3. In the Services window, highlight Caching Proxy.
  4. Click the Automatic radio button, then click Start to initiate the Caching Proxy service automatically when Windows starts.

Refreshing the PATH environment variable

If Caching Proxy is marked as Started in the Services window, but the proxy is not working, the machine might not have been restarted after the proxy was installed. If the Caching Proxy service is set to interact with the desktop, failure to restart can also cause the following error message to appear in a pop-up box: Message catalog error: the message catalog could not be loaded or is invalid

The machine must be restarted so that the value of the PATH environment variable is refreshed in the Windows registry. If the registry is not refreshed, it is possible for the PATH variable to show the correct Caching Proxy and GSK7 paths but to function incorrectly.

Note:
A potential conflict exists for Windows systems when both Caching Proxy and another application, such as a network file system, run as services. Caching Proxy sometimes cannot interpret a path containing a remote drive owned by a file system application that also is running as a service.

The problem can occur if the path for the file system service appears before the path for the Caching Proxy service in the Windows PATH environment variable. Altering the PATH variable to put file system services near the end of the setting can solve this problem.

This problem does not affect remote drives controlled by applications that do not run as Windows services. For example, Caching Proxy can access shared drives on other Windows machines that are visible through a local area network (LAN).

Startup as a Windows application

Using the Start menu

When Caching Proxy is installed as a Windows application, the installation procedure creates a Caching Proxy entry as a submenu of the Start menu. To start Caching Proxy as an application, click Start -> Programs -> IBM WebSphere -> Edge Components -> Caching Proxy.

This startup procedure runs the proxy server with the current configuration settings. If you want to specify other settings at startup time, use the command startup procedure (see the next section).

Using the command prompt

To start the server from any Windows or DOS command prompt, use the ibmproxy command. If you have not shut down and restarted Windows since you installed the server, enter the full path name for this command, as follows, (by default):

C:\Program Files\IBM\edge\cachingproxy\cp\bin\ibmproxy.exe

The ibmproxy command starts the server with the current configuration settings. If you have not changed the server configuration since installation, the current configuration is based on the information you entered during installation and on the default options.

The ibmproxy command starts the server as an application, even if you have installed Caching Proxy to run as a service. To force the server to run as an application, you can also specify the command option -noservice. Other command options change the configuration settings at run time.

Starting multiple proxy servers

Multiple instances of the proxy server can run concurrently, but each binding IP address and listening port pair (HostName/IP, PORT) must be unique. You must also enable the BindSpecific directive in the configuration files. Additionally, when multiple instances of the proxy are running on a single system, you must define the following directives for each proxy instance:

On AIX systems, only one instance can be started with SRC. Unique configuration files must be specified for all instances of the server because the configuration file identifies a port number, and this number must be different for each server on a particular machine. To start an additional instance of the server (when at least one is already running), enter the following command:

where other_config_file is a unique configuration file.

When starting multiple instances of the server, record the process ID that is displayed for each instance. These IDs are required to stop specific instances of the server.

Note:
On Linux systems running multiple instances of the server, the command /etc/rc.d/init.d/ibmproxy stop stops only the last server that was started. Other instances must be stopped separately. Refer to Manual shutdown on Linux and UNIX systems for related information.

Starting ibmproxy as a non-root user on UNIX systems

You can run IBM Caching Proxy as a non-root process on a UNIX system, but there are some configuration changes that you need to make so Caching Proxy can work correctly. To set up Caching Proxy to run as a non-root user:

  1. Configure Caching Proxy to use only non-standard ports above 1024. For example, you can use the following ports with Caching Proxy as a non-root process:
    Port  8080
    SSLPort 1443
    Note:
    This step is required for every directive in the configuration file that uses port numbers. If you try running the process as non-root user on ports below 1024, you might get port bind errors or permission denied errors.
  2. Review the settings for the USERID and GROUPID directives. If you change the server defaults for the user ID, group ID, or log directory paths, create the new directories and update the permissions and ownership of the directories.

Manual shutdown on Linux and UNIX systems

To stop the server:

Table 2. Start and stop methods for Linux and UNIX systems
Start method Stop method
From /etc/inittab (On AIX) Enter stopsrc -s ibmproxy
From /sbin/init.d (On HP-UX) Enter /sbin/init.d/ibmproxy stop
From /etc/init.d (On Linux) Enter /etc/init.d/ibmproxy stop
ibmproxy
  1. Find the ibmproxy process ID: On AIX, enter ps -aef | grep "ibmproxy". On Linux, enter ps -aux | grep ibmproxy | grep server_ID. On Solaris and HP-UX, enter ps -ef | grep "ibmproxy"
  2. Stop the ibmproxy process: Enter kill process_id

To stop all servers on this machine: Enter killall ibmproxy

ibmproxy -nobg Enter ctrl-c
ibmproxy -r -other_config_file(On AIX) Enter stopsrc -s ibmproxy -p process_id
ibmproxy -r -other_config_file(On Linux)
  1. Find the ibmproxy process ID: Enter ps aux | grep ibmproxy | grep process_id
  2. Stop the ibmproxy process: Enter kill process_id
Note:
If you have started transparent proxy, also unload the transparent proxy kernel extension and the associated firewall rules after stopping the Caching Proxy server. As root, enter the following command:
ibmproxy -unload 

To stop the server at a root prompt, enter:

Limitations of the shutdown commands

You can experience the following limitations when using the shutdown commands:

Manual shutdown on a Windows system

You can stop the Caching Proxy server in the same ways that you stop other Windows programs.

If the proxy is installed as a service:

  1. Click Start -> Control Panel.
  2. In the Control Panel window, double-click Administrative Tools -> Services.
  3. In the Services window, highlight Caching Proxy.
  4. Click Stop to stop the Caching Proxy service.

If the proxy is not installed as a service, do any of the following to stop Caching Proxy:

Restarting after configuration changes

After changing the server configuration (by using the Configuration and Administration forms or by editing the ibmproxy.conf file), you must restart the server before the changes take effect. In most cases, you can restart the server without stopping it first. But some settings are not refreshed by a simple restart. For more information, see Table 6.

To restart the server without stopping it first, click the Restart button on any Configuration and Administration form, or type the following: ibmproxy -restart