server task virtualhost add

Adds an additional installed WebSEAL server or server instance to an existing virtual host junction.

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

Syntax

server task instance_name-webseald-host_name virtualhost add –h host_name [options] vhost_label

Options

–h host_name

Specifies the DNS host name or IP address of the target server. Valid values for host_name include any valid IP host name. This option is required. For example:

www.example.com

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL server 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 server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.

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

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

options

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

–D "dn"

Specifies the distinguished name of the 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:

proxy.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 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

Specifies the TCP port of the 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 not being used.

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

–q path

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. Required for Windows™ virtual hosts.

This option is valid for all junction types except localtcp and localssl.

–u uuid

Specifies the UUID of this 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.

–w

Indicates Microsoft™ Windows 32 bit (Win32) file system support.

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

–y priority

The priority for the server (1-9). Default is 9.

vhost_label

Specifies the label name of the virtual host junction.

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/@vhost_label object. For example, the sec_master administrative user is given this permission by default.

Return codes

0: The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns 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. This reference provides a list of the Verify Identity Access error messages by decimal or hexadecimal codes.

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

Example

The following example adds a server with host name xyz.ibm.com to an existing virtual host junction with the label support-vhost-http, on the WebSEAL server abc.ibm.com:

pdadmin> server task default-webseald-abc.ibm.com virtualhost add \
-h xyz.ibm.com support-vhost-http