Creation of a virtual host junction

The virtualhost create command creates a new virtual host junction.

Operation: Creates a new virtual host junction.

Syntax:

virtualhost create -t type -h host-name options vhost-label

-t type

Type of virtual host junction. Specify tcp, ssl, tcpproxy, sslproxy, localtcp, or localssl.

Default port for –t tcp is 80. Default port for –t ssl is 443.

This parameter is required.

-h host-name

The DNS host name or IP address of the target back-end server. This parameter is required for tcp, ssl, tcpproxy, sslproxy type junctions.

options

See Table 1.

vhost-label

The name for the virtual host junction. This junction label is used to indicate the junction in the display of the protected object space. You can refer to a junction in the pdadmin utility by using this label.

This parameter is required.

See Creation of a remote type virtual host junction.

Table 1. Options on the virtualhost create command
Virtual host junction type	Parameter	Description
Virtual host option	–v `vhost-name`[:`port`]]	WebSEAL selects a virtual host junction to process a request if the request's HTTP Host header matches the virtual host name and port number specified by the -v option. The -v option is also used to specify the value of the Host header of the request sent to the back-end 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, then the junction is selected from the information in the -h `host` and -p `port` options. The -v option is required for localtcp and localssl type junctions. See Creation of a remote type virtual host junction.
Virtual host option	–g `vhost-label`	The -g option causes a second 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 with complementary protocols). The option does not support the association of more than two junctions. Optional. See Creation of a remote type virtual host junction.
Virtual host option	–I `aliases`	WebSEAL selects the virtual host junction for a request based on the HTTP host header contained within the request. The '-I' option can be used to specify additional aliased host headers which will be matched to this virtual host junction. The format of the host alias should be: `<host>:<port>`. Note: The port is required even if the default HTTP or HTTPS ports are used. Multiple host aliases may be specified, with each alias separated by a comma.
General option for TCP and SSL junction types	–a `address`	Specifies the local IP address that WebSEAL uses when it is communicating with the target back-end server. If this option is not provided, WebSEAL uses the default address as determined by the operating system. If you supply an address for a particular junction, WebSEAL binds to this local address for all communication with the junctioned server.
General option for TCP and SSL junction types	-E description	A description for the junction.
General option for TCP and SSL junction types	–f	Force the replacement (overwrite) of an existing virtual host junction. See Forcing a new junction.
General option for TCP and SSL junction types	–i	WebSEAL server treats URLs as case insensitive. See Support for URLs as not case-sensitive.
General option for TCP and SSL junction types	–p `port`	TCP port of the back-end third-party server. Default is 80 for TCP junctions. Use 443 for SSL junctions. See Creating TCP type standard junctions and Creating SSL type standard junctions.
General option for TCP and SSL junction types	–q `path`	Provides WebSEAL with the correct name of the query_contents program file and where to find the file. By default, the Windows™ file is called `query_contents.exe` and the UNIX™ file is called `query_contents.sh`. By default, WebSEAL looks for the file in the `cgi_bin` directory of the back-end web server. Required for back-end Windows and UNIX web servers. See Installing and configuring query_contents on Windows-based Web servers.
General option for TCP and SSL junction types	–T `resource/resource-group`	Name of GSO resource or resource group. Required for and used only with –b gso option. See Configuring a GSO-enabled WebSEAL junction.
General option for TCP and SSL junction types	–w	Windows 32-bit (Win32) file system support. See Junctions to Windows file systems.
General option for TCP and SSL junction types	-y `priority`	The priority for the server (1-9). Default is 9. See Adding multiple back-end servers to the same junction
Stateful junctions See Stateful junctions.	–s	Specifies that the virtual host junction support stateful applications. By default, junctions are not stateful.
Stateful junctions See Stateful junctions.	–u `UUID`	Specifies the UUID of a back-end server that is connected to WebSEAL with a stateful virtual host junction (–s).
Mutual authentication over Basic Authentication and SSL certificates See Mutually authenticated SSL junctions.	–B	WebSEAL uses BA header information to authenticate to back-end virtual host. Requires –U, and –W options.
Mutual authentication over Basic Authentication and SSL certificates See Mutually authenticated SSL junctions.	–D "`DN`"	Specify Distinguished Name of back-end server certificate. This value, matched with actual certificate DN enhances authentication.
Mutual authentication over Basic Authentication and SSL certificates See Mutually authenticated SSL junctions.	–K "`key-label`"	Key label of WebSEAL's client-side certificate, used to authenticate to back-end virtual host.
Mutual authentication over Basic Authentication and SSL certificates See Mutually authenticated SSL junctions.	–U "`username`"	WebSEAL user name. Use with –B to send BA header information to back-end server.
Mutual authentication over Basic Authentication and SSL certificates See Mutually authenticated SSL junctions.	–W "`password`"	WebSEAL password. Use with –B to send BA header information to back-end server.
Proxy junction (requires –t tcpproxy or –t sslproxy) See TCP and SSL proxy junctions.	–H `host-name`	The DNS host name or IP address of the proxy server.
Proxy junction (requires –t tcpproxy or –t sslproxy) See TCP and SSL proxy junctions.	–P `port`	The TCP port of the proxy server.
Supply identity information in HTTP headers	–b `BA-value`	Defines how the WebSEAL server passes client identity information in HTTP basic authentication (BA) headers to the back-end virtual host. One of: filter (default), ignore, supply, gso See Client identity in HTTP BA headers.
Supply identity information in HTTP headers	–c `header-types`	Insert client identity information specific to Verify Identity Access in HTTP headers across the virtual host junction. The `header-types` argument can include any combination of the following Verify Identity Access HTTP header types: iv-user, iv-user-l, iv-groups, iv-creds, all. See Client identity in HTTP headers (–c).
Supply identity information in HTTP headers	–e `encoding-type`	Specifies the encoding to use when you generate HTTP headers for virtual host junctions. This encoding applies to headers that are generated with both the –c junction option and tag-value. The following list shows the possible values for encoding: utf8_bin utf8_uri lcp_bin lcp_uri See UTF-8 encoding for HTTP header data.
Supply identity information in HTTP headers	–I	NOT VALID. This option is not valid because cookie handling is not required over virtual host junctions.
Supply identity information in HTTP headers	–j	NOT VALID. This option is not valid because the junction cookie solution is not required over virtual host junctions.
Supply identity information in HTTP headers	–J trailer[,onfocus]	NOT VALID. This option is not valid because the junction cookie solution is not required over virtual host junctions.
Supply identity information in HTTP headers	–k	Send session cookie to back-end virtual host. See Passing of session cookies to junctioned portal servers.
Supply identity information in HTTP headers	–n	NOT VALID. This option is not valid because the junction cookie solution is not required over virtual host junctions.
Supply identity information in HTTP headers	–r	Insert incoming IP address in HTTP header across the virtual host junction. See Client IP addresses in HTTP headers (–r).
Junction fairness	–l `percent-value`	Defines the soft limit for consumption of worker threads.
Junction fairness	–L `percent-value`	Defines the hard limit for consumption of worker threads.
WebSphere single signon (LTPA) junctions See Configuration of an LTPA junction.	–A	Enables virtual host junctions to support LTPA cookies (tokens). LTPA version 1 cookies (LtpaToken) and LTPA version 2 cookies (LtpaToken2) are both supported. LTPA version 1 cookies are specified by default. LTPA version 2 cookies must be specified with the additional -2 option. Also requires –F, and –Z options.
WebSphere single signon (LTPA) junctions See Configuration of an LTPA junction.	–2	Used with the -A option, this option specifies that LTPA version 2 cookies (LtpaToken2) are used. The -A option without the -2 option specifies that LTPA version 1 cookies (LtpaToken) are used.
WebSphere single signon (LTPA) junctions See Configuration of an LTPA junction.	–F "`keyfile`"	Name of the key file that is used to encrypt LTPA cookie data. Only valid with –A option.
WebSphere single signon (LTPA) junctions See Configuration of an LTPA junction.	–Z "`keyfile-password`"	Password for the key file that is used to encrypt LTPA cookie data. Only valid with –A option.
Tivoli Federated Identity Manager SSO junctions Single sign-on with the Security Token Service	`-Y`	Enables Tivoli® Federated Identity Manager single-signon (SSO) for the junction. Note: Before you use this option, you must first configure the WebSEAL configuration files to support Tivoli Federated Identity Manager single-signon over junctions.
WebSEAL-to-WebSEAL SSL junctions See WebSEAL-to-WebSEAL junctions over SSL.	–C	Mutual authentication between a front-end WebSEAL server and a back-end WebSEAL server over SSL. Requires –t ssl or –t sslproxy type.
Forms single signon See Forms single sign-on process flow.	–S `path`	Name of the forms single signon configuration file.
Transparent path junctions	–x	NOT VALID.
Distributed session cache	–z `replica-set-name`	For distributed session cache environments, this parameter is optional. Specifies the replica set that sessions on the virtual host junction are managed under. It is specified so that you can group or separate log in sessions among multiple virtual hosts. If -z is not used to specify the replica set for the virtual host junction, the virtual host junction is automatically assigned to a replica set. The assigned replica set matches its virtual host name. For example, if the virtual host name is vhostA.example.com, the replica set is named vhostA.example.com. The replica set used for the virtual host junction must be present in the [replica-sets] stanza of the WebSEAL configuration file. For environments that do not use the distributed session cache, this option is not applicable. See Advanced configuration for the distributed session cache.
SSL junction types	–O CN	Specifies the expected common name or subject alternative name, of the back-end server certificate. See Matching the common name (CN) and subject alternative name (SAN).