server task virtualhost create

Creates a virtual host junction.

Requires authentication (administrator ID and password) to use.

For local junctions:

server task instance-webseald-host virtualhost create -t type -d dir -v virtual_host_name [options] vhost_label

For non-local junctions:

server task instance-webseald-host virtualhost create -t type -h host_name [options] vhost_label

Options

-d dir

Local directory for a local virtual host junction.

Required for localtcp and localssl junction types.

-h host_name

DNS host name or IP address of the target server. Valid only for non-local junctions; local junctions do not need a host name. Valid values for host_name include any valid IP host name. For example:

www.example.com

-t type

Type of virtual host junction. Required and must be one of the following types:

• tcp
• tcpproxy
• ssl
• sslproxy
• localtcp
• localssl

-v virtual_host_name[:port]

WebSEAL selects a virtual host junction to process a request if the HTTP Host header of the request matches:

• The virtual host name by the -v option and
• The port number specified by the -v option.

The -v option also specifies the value of the Host header of the request sent to the server.

The port number is required if the virtual host uses a non-standard port for the protocol. Standard port for TCP is 80; standard port for SSL is 443.

If -v is not specified for tcp, ssl, tcpproxy, and sslproxy type junctions, the junction is selected from the information that is contained in the -h host_name and -p port options.

The -v option is required for localtcp and localssl type junctions

instance-webseald-host

Full server name of the installed WebSEAL server instance. 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 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

Options we can use with the server task virtualhost create command. (Optional) These options include:

-A

Enables a virtual host junction to support the lightweight third-party authentication mechanism (LTPA). Requires the -F and -Z options. The -A, -F, and -Z options all must be used together.

Valid for all junction types except localtcp and localssl.

-2

We can use this option with the -A option to specify that LTPA version 2 cookies (LtpaToken2) are used. The -A option without the -2 option specifies that LTPA version 1 cookies (LtpaToken) are used.

-b BA_value

Defines how the WebSEAL server passes client identity information in HTTP basic authentication (BA) headers to the virtual host, which is one of the following values:

• filter
• ignore
• supply
• gso

Valid for all junction types except localtcp and localssl. Default is filter.

-B

WebSEAL uses the BA header information to authenticate to the virtual host and to provide mutual authentication over SSL. Requires the -U and -W options.

Valid only with junctions that were created with the type of ssl or sslproxy.

-c header_type

Inserts the ISAM client identity in HTTP headers across the virtual host junction. The header_type argument can include any combination of the listed Security Verify Access HTTP header types:

• {iv_user|iv_user-l}
• iv_groups
• iv_creds
• all

The header types must be comma-separated, and cannot have a space between the types. For example: -c iv_user,iv_groups

Specify -c all is the same as specifying -c iv_user,iv_groups,iv_creds.

Valid for all junction types except localtcp and localssl.

-C

Supports mutual authentication by enabling the front-end WebSEAL server to pass its identity information to the back-end WebSEAL server. The front-end WebSEAL server passes information in a Basic Authentication (BA) header. Additionally, the -C option enables the single sign-on functionality provided by the -c option.

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

-D "dn"

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=Minneapolis,
ST=Texas,C=US"

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

-e encoding_type

Encoding to use when HTTP headers is generated for virtual host junctions. This encoding applies to headers generated with both the -c junction option and tag-value. Possible values for encoding are as follows:

utf8_bin

WebSEAL sends the headers in UTF-8.

utf8_uri

WebSEAL sends the headers in UTF-8 but URI also encodes them. This behavior is the default behavior.

lcp_bin

WebSEAL sends the headers in the local code page of the WebSEAL server.

lcp_uri

WebSEAL sends the headers in the local code page of the WebSEAL server, but URI also encodes them.

Valid for all junction types except localtcp and localssl.

-f

Forces the replacement (overwrite) of an existing virtual host junction.

This option is used for junctions that were created with any junction type.

-F "keyfile"

Location of the key file used to encrypt LTPA cookie data.

The -F option requires -A and -Z options. The -A, -F, and -Z options all must be used together.

Valid for all junction types except localtcp and localssl.

-g vhost_label

The -g option causes a second more virtual host junction to share a protected object space as the initial virtual host junction.

This option is appropriate for junction pairs only (two junctions by using complementary protocols). The option does not support the association of more than two junctions.

-H host_name

DNS host name or IP address of the proxy server. The -P option also supports proxy server junctions. Valid values for host_name include any valid IP host name. For example:

proxy.www.example.com

Valid only with junctions that were created with the type of tcpproxy or sslproxy.

-i

That the WebSEAL junction does not treat URLs as case-sensitive. To correctly authorize requests for junctions that are not case-sensitive, WebSEAL does the authorization check on a lowercase version of the URL. For example, a web server running on a Windows operating system treats requests for INDEX.HTM and index.htm as requests for the same file. Junctions to such a web server must be created with the -i or -w option. ACLs or POPs that are attached to objects beneath the junction point must use the lowercase object name. An ACL attached to /junction/index.htm applies to all the following requests if the -i or -w option is used:

• /junction/INDEX.HTM
• /junction/index.htm
• /junction/InDeX.HtM

Valid for all junction except for the type of localtcp and localssl. Local junctions are not case-sensitive only on Win32 platforms; all other platforms are case-sensitive.

-k

Sends WebSEAL session cookies to the back-end virtual host. By default, cookies are removed from requests that are sent to the server.

Valid for all junction types except localtcp and localssl.

-K "key_label"

Key label of the client-side certificate that WebSEAL must present to the server. Use of this option allows the virtual host to authenticate the WebSEAL server by using client certificates.

Valid only with junctions that were created with the type of ssl and sslproxy.

-l percent

Soft limit for consumption of worker threads.

Valid for all junction types except localtcp and localssl.

-L percent

Hard limit for consumption of worker threads.

Valid for all junction types except localtcp and localssl.

-p port

Specifies the TCP port of the third-party server. Default is 80 for TCP junctions and 443 for SSL junctions.

Valid for all junction types except localtcp and localssl.

-P port

Specifies the TCP port number for the HTTP proxy server. The -P option is required when the -H option is used.

Valid only with junctions that were created with the type of tcpproxy or sslproxy.

-q -S

Relative path for the query_contents script. By default, Security Verify Access looks for the query_contents script in the /cgi_bin directory. If this directory is different or the query_contents file name is renamed, this option indicates to WebSEAL the new URL to the file. Required for Windows virtual hosts.

Valid for all junction types except localtcp and localssl.

-r

Inserts the incoming IP address into the HTTP header across the junction.

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

-R

Allows the request to proceed but provides the rule failure reason to the junction in an HTTP header. If the -R option is not used and a rule failure occurs, WebSEAL does not allow the request to proceed.

Valid for all junction types except localtcp and localssl.

-s

That the virtual host junction support stateful applications. By default, virtual host junctions are not stateful.

Valid for all junction types except localtcp and localssl.

-S

The location of the forms single sign-on configuration file.

Valid for all junction types except localtcp and localssl.

-T {resource | resource_group}

Name of the GSO resource or resource group. Required only when the -b gso option is used.

Valid for all junction types except localtcp and localssl.

-u uuid

Universally Unique Identifier (UUID) of a server that is connected to WebSEAL by using a stateful virtual host junction (-s option).

Valid for all junction types except localtcp and localssl.

-U "user_name"

Specifies the WebSEAL server user name. Requires the -B and -W options. WebSEAL uses the BA header information to authenticate to the virtual host and to provide mutual authentication over SSL.

Valid only with junctions that were created with the type of ssl or sslproxy.

-w

Indicates Microsoft Windows 32 bit (Win32) file system support. This option provides all the functionality provided by the -i junction option. The option disallows requests containing file names that might be interpreted as Win32 file name aliases.

Valid for all junction types except localtcp and localssl. Local junctions prohibit URLs that contain Win32 file name aliases on Win32 but allow such URLs on other platforms.

-W "password"

Specifies the WebSEAL server password. Requires the -B and -U options. WebSEAL uses the BA header information to authenticate to the virtual host and to provide mutual authentication over SSL.

Valid only with junctions that were created with the type of ssl or sslproxy.

-Y

Enables the Federation Runtime single sign-on (SSO) for the junction. Before we use this option, we must first configure the WebSEAL configuration file to support the Federation Runtime single sign-on over junctions.

-z replica_set

Replica set, as follows:

For SMS environments:

Sessions on the virtual host junction are managed under the specified replica set. Group or separate login sessions among multiple virtual hosts.

For non-SMS environments:

Sessions on the virtual host junction are managed under the specified replica set. Controls the partitioning of the WebSEAL session cache. The virtual host can be part of the same replica set as any standard junction assigned to that same replica set. Standard junctions are assigned to replica sets through the standard-junction-replica-set entry of the [session] stanza.

-Z keyfile_pwd

Password of the key file used to encrypt LTPA cookie data. This option requires the -A and -F options. The -A, -F, and -Z options all must be used together.

Valid for all junction types except localtcp and localssl.

vhost_label

Label name of the virtual host junction.

Authorization

Users and groups that require access to this command must be given the s (server administration) 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. See "Error messages" in the IBM Knowledge Center. This reference provides a list of the ISAM error messages by decimal or hexadecimal codes.

This command is available only when WebSEAL is installed.

For information about gathering statistics, see the Troubleshooting topics in the IBM Knowledge Center.

Example

Create an SSL type virtual host junction with the vhost-xy-https label. This junction serves the virtual host x.y.com on the junctioned server cruz1.ibm.com. WebSEAL responds to the Host: x.y.com header in SSL (HTTPS) requests by forwarding the requests across this virtual host junction:

pdadmin> server task default-webseald-abc.ibm.com virtualhost create \
-t ssl -h cruz1.ibm.com -v x.y.com vhost-xy-https

See also

server task virtualhost add
server task virtualhost delete
server task virtualhost list
server task virtualhost remove
server task virtualhost show

Parent topic: pdadmin commands