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 can 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 wanted maximum number of file descriptors due to the Solaris system wide limit on file descriptors. If the system wide maximum is less than the setting in the Caching Proxy initialization script, then the system wide 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:

  • On AIX® systems, remove the ibmproxy command from the initialization file.
  • On HP-UX systems, remove the following links to ibmproxy:
    • /sbin/rc1.d/K154ibmproxy
    • /sbin/rc2.d/S880ibmproxy
  • On Linux systems, remove the symbolic links to /etc/rc.d/init.d/ibmproxy in the run level subdirectories.

    On SUSE Linux, remove the following links to ibmproxy:

    • /etc/rc.d/rc3.d/S20ibmproxy
    • /etc/rc.d/rc3.d/K20ibmproxy
    • /etc/rc.d/rc4.d/S20ibmproxy
    • /etc/rc.d/rc4.d/K20ibmproxy
    • /etc/rc.d/rc5.d/S20ibmproxy
    • /etc/rc.d/rc5.d/K20ibmproxy
    On Red Hat Linux, remove the following links to ibmproxy:
    • /etc/rc.d/rc0.d/K54ibmproxy
    • /etc/rc.d/rc1.d/K54ibmproxy
    • /etc/rc.d/rc2.d/K54ibmproxy
    • /etc/rc.d/rc6.d/K54ibmproxy
    • /etc/rc.d/rc3.d/S88ibmproxy
    • /etc/rc.d/rc5.d/S88ibmproxy
  • On Solaris systems, remove the ibmproxy start command and its two kill scripts as follows:
    • Delete S88ibmproxy from the /etc/rc2.d directory.
    • Delete K54ibmproxy from the /etc/rc0.d directory.
    • Delete K54ibmproxy from the /etc/rc1.d directory.

Manual startup on Linux and UNIX systems

Regardless of the startup method, the ibmproxy command is eventually started, either directly from the command prompt or from within a script. Examples of only the most commonly used arguments follow.

On AIX:

  • To start the proxy server for the default locale, by using the startsrc command, enter the following:
    startsrc -s ibmproxy
  • To start the proxy server for any locale other than the default, by using the startsrc command, enter the following:
    startsrc -s ibmproxy -e "LC_ALL=locale"
  • To start the proxy server with the default runtime settings, without using the startsrc command, enter the following:
    ibmproxy
Note: If you use the startsrc command to manually start Caching Proxy on AIX, the Cyber Patrol plug-in does not work correctly. It depends on environment variables that are not read when Caching Proxy is started with this command.

On HP-UX:

  • To start the proxy server by running the initialization script, enter the following at a root prompt:
    /sbin/init.d/ibmproxy start
  • To start the proxy server as a background process without running the initialization script, enter the following at a root prompt:
    /usr/sbin/ibmproxy
  • To start the proxy server as a foreground process without running the initialization script, enter the following at a root prompt:
    /usr/sbin/ibmproxy -nobg

On Linux:

  • To start the proxy server by running the initialization script, enter the following at a root prompt:
    /etc/rc.d/init.d/ibmproxy start
  • To start the proxy server as a background process without running the initialization script, enter the following at a root prompt:
    /usr/sbin/ibmproxy
  • To start the proxy server as a foreground process without running the initialization script, enter the following at a root prompt:
    /usr/sbin/ibmproxy -nobg
  • To start the proxy server using a preexisting SQUID configuration file, squidConfig file, enter the following at a root prompt:
    squidConfig.file -r /etc/errors_icons.conf

    Where the errors_icons.conf file identifies the icons to use for designated file types when browsing directories.

On Solaris:

  • To start the proxy server by running the initialization script, enter the following at a root prompt:
    /etc/init.d/ibmproxy start
  • To start the proxy server as a background process without running the initialization script, enter the following at a root prompt:
    /usr/sbin/ibmproxy
  • To start the proxy server as a foreground process without running the initialization script, enter the following at a root prompt:
    /usr/sbin/ibmproxy -nobg

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 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 that contains a remote drive that is 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 that are 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:
                  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:
  • Port: The listening ports for each proxy instance.
  • HostName: The binding IP address for each proxy instance. If the HostName directive is not defined in the configuration file, the proxy binds to all of the available IP addresses.
  • ServerRoot: The home directory for each proxy instance.
  • PidFile: The process ID file for each proxy instance. This directive applies to Linux and UNIX operating systems only.
  • The log file directives: The logging files location for each proxy instance. (Log, LogArchive, LogFileFormat, LogToGUI, LogToSyslog.)

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 extra instance of the server (when at least one is already running), enter the following command:

  • On Linux and UNIX:
    ibmproxy -r other_config_file
                   
  • On Windows:
    ibmproxy -noservice -r other_config_file
                   

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 that are 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.

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.
    • To enable the server to write information to a user-defined log directory, set the permission for that directory to 755, and set USERID in the configuration file as the owner. For example, assume that you change the following:
      • USERID in the configuration file from the default to jdoe
      • The default logs directory to server_root/account
      Therefore, the server_root/account directory must have the permission 755 and be owned by jdoe.
    • Update the ownership and permissions for the following two files:
      • /opt/ibm/edge/cp/server_root/protect/webadmin.passwd
      • /opt/ibm/edge/cp/server_root/pub/en_US/reports/cacheagt.html

Manual shutdown on Linux and UNIX systems

To stop the server:
  • You must be either the user who started the process or the superuser root.
  • You must use the same method by which the server was started. The following table lists start methods and their associated stop methods.
Table 1. 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/rc.d/init.d (On Linux) Enter /etc/rc.d/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:
  • On AIX: stopsrc -s ibmproxy
  • On HP-UX: /sbin/init.d/ibmproxy stop
  • On Linux: /etc/rc.d/init.d/ibmproxy stop
  • On Solaris: /etc/init.d/ibmproxy stop

Limitations of the shutdown commands

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

  • AIX, HP-UX, and Linux

    On AIX, HP-UX, and Linux systems, the commands to stop the Caching Proxy system that is sometimes shut down only the Caching Proxy process. The AIX command that results in this behavior is the stopsrc -s ibmproxy command. The HP-UX and Linux command that results in this behavior is the ibmproxy -stop command.

    The PACD process, which is used by the LDAP server, might be left running after shutting down the proxy server. The PACD process can be safely shut down by using the kill command as follows:
    kill -15                            PACD_process_ID
                            
                         
  • Solaris

    Issuing the ibmproxy -stop command on a Solaris system does not have the same effect as the command does on other operating systems. Because of a limitation in Solaris code, the Server Termination plug-in step is not run when ibmproxy -stop is used on Solaris platforms.

    This limitation has implications for the proxy server software as well as for customer-implemented plug-ins.

    It is possible for the PACD process, which is used by the LDAP server, to continue running after the proxy server is shut down. The PACD process can be safely shut down by using the kill command as follows:
    kill -15                            PACD_process_ID
                            
                         

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:
  • Click the x icon in the upper right corner.
  • From the File menu, click Exit.
  • Press Alt + F4.

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.

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


Icon that indicates the type of topic Reference topic



Timestamp icon Last updated: March 23, 2018 0:18
File name: startsvr.html