Reverse Proxy instance configuration planning

A Reverse Proxy instance is a unique Reverse Proxy server process with a unique configuration file and listening port. Reverse Proxy deployments support multiple Reverse Proxy instances.

To configure a Reverse Proxy instance, you must decide how to deploy the instance in your environment, and you must collect some information about the Security Verify Access deployment.

Unless stated otherwise, each of the following settings is required.

• Administrative user ID and passwordAdministrator name and password

  The authentication details for the Security Verify Access administrative user. By default, this is the sec_master user. You must have administrative user permissions to configure a Reverse Proxy instance.

• Domain

  The Security Verify Access domain.

• Host name

  The name by which the physical machine is known on the network. Typically this is expressed as a fully qualified domain name. During interactive installations, you can alternatively provide just the system name.

  Example fully qualified domain name:

  diamond.subnet2.example.com

  Example system name:

  diamond

  The host name that the Security Verify Access policy server uses to contact the appliance. The address that corresponds to this host name must match a management interface address of the appliance. Valid values include any valid host name or IP address.

• Instance name

  A unique name that identifies the Reverse Proxy instance. Multiple Reverse Proxy instances can be installed on one computer systemappliance. Each instance must have a unique name.

  Valid characters for instance names include the alphanumeric characters ([A-Z][a-z][0–9]) plus the following characters: underscore ( _ ), hyphen ( - ), and period ( . ). No other characters are valid.

  Example names: web1, web2, web_3, web-4, web.5

  The initial Reverse Proxy instance, which is configured during installation and configuration of Reverse Proxy, is assigned an instance name of default. However, this name can be modified by the administrator during the initial Reverse Proxy configuration.

  The choice of instance name is viewable after configuration. For example, the name of the configuration file for a Reverse Proxy instance has the following format:

  Reverse Proxyd-instance_name.conf

  For example:

  Reverse Proxyd-default.conf

  The instance name also affects how the full server name is listed during a pdadmin server list command. For this command, the full server name has the following format:

  instance_name-Reverse Proxyd-host_name

  For example, an instance_name of web1 installed on a host named diamond has the following full server name:

  web1-Reverse Proxyd-diamond

• Listening port

  This is the port through which the Reverse Proxy instance communicates with the Security Verify Access policy server. The default port number is 7234. This port number must be unique for every Reverse Proxy instance.

  The default port is typically used by the default (first) Reverse Proxy instance. The interactive installation automatically increments to the next available port. You can modify the port number if necessary.

  When installing using the command line or from a response file, specify another port. Any port number above 1024 is valid. Select a port that is not used for any other purpose. A common configuration selection is to increment the port number by one.

• IP address for the primary interface

  The unique IP address for the Reverse Proxy instance. The Reverse Proxy server listens on this IP address for incoming requests. You must also assign each Reverse Proxy instance a unique HTTP and HTTPS port.

• HTTP protocol and HTTP port

  Specifies whether to accept user requests across the HTTP protocol. If HTTP requests are accepted, the administratorIf you enable HTTP, you must assign a port number. The default port number is 80. This port is used by the default (first) instance. If this port is not available, the installation automatically increments to the next available port.

  When not using a logical network interface, specify another port number. Select a port that is not used for any other purpose. A common configuration selection is to increment the port number by one. For example, 81.

  When using a logical network interface, you can use the same port number (for example, 80).

• HTTPS protocol and HTTPS port

  Specifies whether to accept user requests across the HTTPS protocol. If HTTPS requests are accepted, the administratorIf you enable HTTPS, you must assign a port number. The default port number is 443. This port is used by the default (first) instance. If this port is not available, the installation automatically increments to the next available port.

  When not using a logical network interface, specify another port number. Select a port that is not used for any other purpose. A common configuration selection is to increment the port number by one. For example, 444.

  When using a logical network interface, you can use the same port number (for example, 443).

• Logical network interface and IP address

  This setting is optional. You can choose to use a logical network interface for the Reverse Proxy instance. This means that the Reverse Proxy instance receives a unique IP address. Use of this feature requires network hardware support for more than one IP address.

  When the networking hardware supports more than one IP address, you can specify a separate IP address for each Reverse Proxy instance.

  It is not necessary to specify a separate IP address. All Reverse Proxy instances can share one IP address. With this configuration, however, each Reverse Proxy instance must listen on unique HTTP and HTTPS ports.

  The following two tables illustrate configuration settings for two Reverse Proxy instances that share the same IP address:

  Table 1. Reverse Proxy instances sharing the same IPv4 address

  Instance	IPv4 address	HTTP port	HTTPS port
  default	1.2.3.4	80	443
  web1	1.2.3.4	81	444

  Table 2. Reverse Proxy instances sharing the same IPv6 address

  Instance	IPv6 address	HTTP port	HTTPS port
  default	fec0::1	80	443
  web1	fec0::1	81	444

  The following two tables illustrate configuration settings for two Reverse Proxy instances using unique IP addresses:

  Table 3. Reverse Proxy instances with unique IPv4 addresses

  Instance	IPv4 address	HTTP port	HTTPS port
  default	1.2.3.4	80	443
  web1	1.2.3.5	80	443

  Table 4. Reverse Proxy instances with unique IPv6 addresses

  Instance	IPv6 address	HTTP port	HTTPS port
  default	fec0::1	80	443
  web1	fec0::2	80	443

  Example network interface configuration considerations

  The following example scenario has the following conditions:

  • When the first (default) Reverse Proxy instance was configured, you selected not to use a logical network interface.
  • When configuring a new Reverse Proxy instance, you want to use a logical network interface.
  • When configuring this new Reverse Proxy instance, you want to use the same HTTP or HTTPS port for the logical network interface.

  When the first (default) Reverse Proxy instance is configured not to use a logical network interface, Reverse Proxy by default listens for all IP addresses on the specified port. Additional Reverse Proxy instances can be configured to listen for unique IP addresses on this same port. However:

  • Some operating systems require no change to the default Reverse Proxy configuration when you add new Reverse Proxy instances that listen for unique IP addresses on the same port.
  • Other operating systems require you to change the default Reverse Proxy instance interface to listen for a unique IP address rather than all IP addresses.

  In the second case, you must edit the configuration file for the default Reverse Proxy instance and specify a unique IP address. The Reverse Proxy configuration file for the default instance is Reverse Proxyd-default.conf.

  For example, using the default Reverse Proxy instance from the tables above, the following entry (an IPv4 example) must be added to the configuration file:

  [server]
  network-interface = 1.2.3.4

  The Reverse Proxy instance must then be stopped and restarted.

  Note that the change to the configuration file is needed only once. It is not needed when each additional Reverse Proxy instance is configured.

  Consult the documentation for your operating system to determine how it handles network interface configuration.

• SSL communication with LDAP serverUser registry - SSL communication

  Reverse Proxy communicates with the LDAP server during authentication procedures. Use of SSL during communication with the LDAP server is optional. However, use of SSL is highly recommended for security reasons in all production deployments. Disabling of SSL usage can be considered for temporary testing or prototyping environments.

  Note: This step is specific to use of an LDAP user registry. This step is not required when using other registry types.

  If you want to use secure SSL communication between a Reverse Proxy instance and the LDAP registry server, you must use the LDAP SSL key file for this purpose. This is the key file that was created and distributed during installation of the LDAP client. If the initial Reverse Proxy instance is set up to use secure SSL communication with LDAP, multiple instances can use the same key file.

  When enabling SSL communication between Reverse Proxy and the LDAP server, you must provide the following information:

  • SSL key file nameKey file name

    The file that contains the LDAP SSL certificate.

  • SSL key file password

    The password necessary to access the LDAP SSL key file.

  • SSL Certificate labelCertificate label

    The LDAP client certificate label. This is optional. When the client label is not specified, the default certificate contained in the keyfile is used. Specify the client label when the keyfile contains more than one certificate, and the certificate to be used is not the default certificate.

  • SSL LDAP server port numberPort

    The port number through which to communicate with the LDAP server. The default LDAP server port number is 636.

• Web document root directory

  The root directory of the hierarchy where the resources (protected objects) to be protected by Reverse Proxy will be created. The name of the directory can be any valid directory name.

  The directory used by the default (first) Reverse Proxy instance is:

  UNIX or Linux:

  installation_directory/pdweb/www-default/docs

  Windows:

  installation_directory\pdweb\www-default\docs

  Note that this directory could have been changed by the administrator during the configuration of the initial Reverse Proxy instance.

  When adding a new Reverse Proxy instance, a new Web document root directory is usually created for the instance.

  During an interactive installation, a new directory is suggested, based on the following syntax:

  UNIX or Linux:

  installation_directory/pdweb/www-instance_name/docs

  Windows:

  installation_directory\pdweb\www-instance_name\docs

  The administrator can accept this name or specify an alternative.

  When adding a Reverse Proxy instance by using the amwebcfg command line, or by using amwebcfg with a response file, the Web document root directory is created as follows:

  • When the Web document root is not specified on the command line or in the response file, amwebcfg automatically creates a new directory and adds the entry to the Reverse Proxy instance configuration file. The document root is built according to the following syntax:

    UNIX or Linux:

    installation_directory/pdweb/www-instance_name/docs

    Windows:

    installation_directory\pdweb\www-instance_name\docs

  • When the Web document root is specified on the command line or in the response file, amwebcfg adds the entry to the Reverse Proxy instance configuration file.
    Note: The directory must already exist. The amwebcfg utility will not create a new directory

  Sharing one Web document root directory across multiple instances

  Multiple Reverse Proxy instances can use the same Web document root directory. When you want to use this scenario, the best way to configure the document root for each new Reverse Proxy instance is as follows:

  1. Allow amwebcfg to create a new Web document root directory.
  2. When amwebcfg configuration completes, manually edit the Reverse Proxy configuration file and reassign the document root value to the preferred directory.

     [content] 
     doc-root = full_path_to_directory

  Each time a Web document root hierarchy is created, amwebcfg copies the contents of the html.tivoli directory hierarchy into the new Web document root. The contents of html.tivoli include an index.html file. This means that an existing index.html could get overwritten by the default (template) file from the html.tivoli directory. Manual editing of the Reverse Proxy configuration file as described above avoids this problem. After editing the configuration file, you can remove the unneeded Web document root (the one created automatically by amwebcfg).