PROXYMNGR(1) X Version 11 (Release 6.6) PROXYMNGR(1)
NAME
proxymngr - proxy manager service
SYNOPSIS
proxymngr [-config filename] [-timeout seconds] [-retries #]
[-verbose]
DESCRIPTION
The proxy manager (proxymngr) is responsible for resolving
requests from xfindproxy (and other similar clients),
starting new proxies when appropriate, and keeping track of
all of the available proxy services. The proxy manager
strives to reuse existing proxies whenever possible.
There are two types of proxies that the proxy manager deals
with, managed and unmanaged proxies.
A managed proxy is a proxy that is started ``on demand'' by
the proxy manager.
An unmanaged proxy, on the other hand, is started either at
system boot time, or manually by a system administrator.
The proxy manager is made aware of its existence, but no
attempt is made by the proxy manager to start unmanaged
proxies.
The command line options that can be specified to proxymngr
are:
-config Used to override the default proxymngr config file.
See below for more details about the config file.
-timeout
Sets the number of seconds between attempts made by
the proxy manager to find an unmanaged proxy. The
default is 10.
-retries
Sets the maximum number of retries made by the proxy
manager to find an an unmanaged proxy. The default
is 3.
-verbose
Causes various debugging and tracing records to be
displayed as requests are received and proxies are
started.
Running the Proxy Manager
While it is possible to start the proxy manager by hand, a
single proxy manager can manage proxies for many users, so
it is most effective to configure it as a system daemon. To
configure the proxy manager daemon to be started at system
startup and stopped at system shutdown, execute the command:
chkconfig proxymngr on
To stop the proxy manager daemon on a running system,
execute the command:
/etc/init.d/proxymngr stop
Be aware that stopping the proxy manager will normally kill
all managed proxies as well.
To start the proxy manager daemon on a running system,
execute the command:
/etc/init.d/proxymngr start
Local users on the system where the proxy manager is running
can configure xfindproxy to access the proxy manager daemon
by setting the following variable in their shell
environment:
PROXY_MANAGER=local/proxyhost:/tmp/.ICE-unix/6500,tcp/proxyhost:6500
where "proxyhost" is the network name of the system where
the proxy manager is running. Remote users can access the
proxy manager by using the latter address:
PROXY_MANAGER=tcp/proxyhost:6500
An alternative to using the shell environment variable is to
specify either address using the -manager option to
xfindproxy:
xfindproxy -manager tcp/proxyhost:6500 ...
Proxy Manager Config File
The proxy manager maintains a local configuration file
describing the proxy services available. This configuration
file is installed in /usr/lib/X11/proxymngr/pmconfig during
the installation of proxymngr. The location of the
configuration file can be overwritten using the -config
command line option.
Aside from lines starting with an exclamation point for
comments, each line of the configuration file describes
either an unmanaged or managed proxy service.
For unmanaged proxies, the format is:
<service-name> unmanaged <proxy-address>
service-name is the name of the unmanaged proxy service, and
must not contain any spaces, for example ``XFWP''.
service-name is case insenstive.
proxy-address is the network address of the unmanaged proxy.
The format of the address is specific to the service-name.
For example, for the ``XFWP'' service, the proxy-address
might be ``firewall.x.org:100''.
If there is more than one entry in the config file with the
same unmanaged service-name, the proxy manager will try to
use the proxies in the order presented in the config file.
For managed proxies, the format is:
<service-name> managed <command-to-start-proxy>
service-name is the name of the managed proxy service, and
must not contain any spaces, for example ``LBX''. service-
name is case insensitive.
command-to-start-proxy is the command executed by the proxy
manager to start a new instance of the proxy. If command-
to-start-proxy contains spaces, the complete command should
be surrounded by single quotes. If desired, command-to-
start-proxy can be used to start a proxy on a remote
machine. The specifics of the remote execution method used
to do this is not specified here.
EXAMPLE
Here is a sample configuration file:
! proxy manager config file
!
! Each line has the format:
! <serviceName> managed <startCommand>
! or
! <serviceName> unmanaged <proxyAddress>
!
lbx managed /usr/bin/X11/lbxproxy
!
! substitute site-specific info
xfwp unmanaged firewall:4444
PROXY MANAGER DETAILS
When the proxy manager gets a request from xfindproxy (or
another similar client), its course of action will depend on
the service-name in question.
For a managed proxy service, the proxy manager will find out
if any of the already running proxies for this service can
handle a new request. If not, the proxy manager will
attempt to start up a new instance of the proxy (using the
command-to-start-proxy found in the config file). If that
fails, an error will be returned to the caller.
For an unmanaged proxy service, the proxy manager will look
in the config file to find all unmanaged proxies for this
service. If there is more than one entry in the config file
with the same unmanaged service-name, the proxy manager will
try to use the proxies in the order presented in the config
file. If none of the unmanged proxies can satisfy the
request, the proxy manager will timeout for a configurable
amount of time (specified by -timeout or default of 10) and
reattempt to find an unmanaged proxy willing to satisfy the
request. The number of retries can be specified by the
-retries argument, or a default of 3 will be used. If the
retries fail, the proxy manager has no choice but to return
an error to the caller (since the proxy manager can not
start unmanaged proxy services).
BUGS
proxy manager listen port should be configurable.
-timeout and -retries is not implemented in proxymngr.
proxymngr does not utilize the ``options'' and ``host''
fields in the proxy management protocol GetProxyAddr
request.
SEE ALSO
xfindproxy (1), xfwp (1), Proxy Management Protocol spec
V1.0
AUTHOR
Ralph Mor, X Consortium
Page 4 (printed 7/20/06)