server task add

The server task add command adds an additional back-end application server to an existing WebSEAL junction.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name add -h host_name [options] junction_point

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.

For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

junction_point

Specifies the name of the directory in the WebSEAL protected object space where the document space of the back-end server is mounted.

options

Specifies the options that you can use with the server task add command. These options include:

-D "dn"

Specifies the distinguished name of the back-end server certificate. This value, matched with the actual certificate DN, enhances authentication and provides mutual authentication over SSL. For example, the certificate for www.example.com might have a DN of

"CN=WWW.EXAMPLE.COM,OU=Software,O=example.com\, Inc,L=Austin,
ST=Texas,C=US"

This option is valid only with junctions that were created with the type of ssl or sslproxy.

-H host_name

Specifies the DNS host name or IP address of the proxy server. Valid values for host_name include any valid IP host name. For example:

www.example.com

This option is used for junctions that were created with the type of tcpproxy or sslproxy.

–i

Indicates that the WebSEAL server does not treat URLs as case-sensitive. This option is used for junctions that were created with the type of tcp or ssl.

-p port

Specifies the TCP port of the back-end server. The default value is 80 for TCP junctions and 443 for SSL junctions. This option is used for junctions that were created with the type of tcp or ssl.

-P port

For proxy junctions that were created with the type of tcpproxy or sslproxy this option specifies the TCP port number for the HTTP proxy server. The default value is 7138.

For port, use any valid port number. A valid port number is any positive number that is allowed by TCP/IP and that is not currently being used by another application. Use the default port number value, or use a port number that is greater than 1000 that is currently not being used.

This option is also valid for mutual junctions to specify the HTTPS port of the back-end third-party server.

-q url

Required option for back-end Windows™ servers. Specifies the relative path for the query_contents script. By default, Verify Identity Access looks for this script in the /cgi_bin subdirectory. If this directory is different or the query_contents file is renamed, use this option to indicate to WebSEAL the new URL to the file.

This option is used for junctions that were created with the type of tcp or ssl.

-u uuid

Specifies the UUID of this back-end server when connected to WebSEAL over a stateful junction that was using the –s option. This option is used for junctions that were created with the type of tcp or ssl.

-v virtual_hostname

Specifies the virtual host name represented on the back-end server. This option supports a virtual host setup on the back-end server. Use this option when the back-end junction server expects a host name header, because you are junctioning to one virtual instance of that server. The default HTTP header request from the browser does not know that the back-end server has multiple names and multiple virtual servers. You must configure WebSEAL to supply that extra header information in requests destined for a back-end server set up as a virtual host. This option is used for junctions that were created with the type of tcp or ssl.

-V virtual_hostname

Virtual host name represented on the back-end server. This option supports a virtual host setup on the back-end server. This option is only used for mutual junctions and corresponds to the virtual host which is used for HTTPS requests.

You use –V when the back-end junction server expects a host name header because you are junctioning to one virtual instance of that server. The default HTTPS header request from the browser does not know that the back-end server has multiple names and multiple virtual servers. You must configure WebSEAL to supply that extra header information in requests destined for a back-end server set up as a virtual host.

-w: Indicates Microsoft™ Windows file system support.
This option is used for junctions that were created with the type of tcp or ssl.

-h host_name

Required option. Specifies the DNS host name or IP address of the target back-end application server. Valid values for host_name include any valid IP host name. For example:

www.example.com

Authorization

Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user has permission by default.

Note: This command is available only when WebSEAL is installed.

Return codes

0: The command completed successfully. For WebSEAL server task commands, the return code will be 0 when the command is sent to the WebSEAL server without errors.
Note: Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.
1: The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Verify Identity Access error messages by decimal or hexadecimal codes.

Examples

The following example creates a new junction for the WebSEAL server named WS1 to the back-end server named APP1 and adds another back-end server named APP2 to the same junction point:

pdadmin> server task default-webseald-WS1 create -t tcp -h APP1 -s /mnt

pdadmin> server task default-webseald-WS1 add -h APP2 /mnt