Creation of a virtual host junction

Create of a virtual host junction

The virtualhost create command creates a new virtual host junction.
Operation: Creates a new virtual host junction.
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. Required.

-h host-name

The DNS host name or IP address of the target back-end server. 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. We can refer to a junction in the pdadmin utility by using this label. Required.

See Creation of a remote type virtual host junction.

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 also specifies 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.

Virtual host option -g vhost-label The -g option causes a second, remote 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.

TCP and SSL -a address Local IP address that WebSEAL uses when it is communicating with the target back-end server. If not provided, WebSEAL uses the default address as determined by the operating system. If we supply an address for a particular junction, WebSEAL binds to this local address for all communication with the junctioned server.

TCP and SSL -E description A description for the junction.

TCP and SSL -f Force the replacement (overwrite) of an existing virtual host junction.

TCP and SSL -i WebSEAL server treats URLs as case insensitive.

TCP and SSL -p port TCP port of the back-end third-party server. Default is 80 for TCP junctions. Use 443 for SSL junctions.

TCP and SSL -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.

TCP and SSL -T resource/resource-group Name of GSO resource or resource group. Required for and used only with -b gso option.

TCP and SSL -w Windows 32-bit (Win32) file system support.

Stateful junctions -s The virtual host junction support stateful applications. By default, junctions are not stateful.

Stateful junctions -u UUID 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 -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 -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 -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 -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 -W "password" WebSEAL password. Use with -B to send BA header information to back-end server.

Proxy junction (requires -t tcpproxy or -t sslproxy) -H host-name The DNS host name or IP address of the proxy server.

Proxy junction (requires -t tcpproxy or -t sslproxy) -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

Supply identity information in HTTP headers -c header-types Insert client identity information specific to ISAM in HTTP headers across the virtual host junction. The header-types argument can include any combination of the following Security Verify Access HTTP header types: iv-user, iv-user-l, iv-groups, iv-creds, all.

Supply identity information in HTTP headers -e encoding-type Encoding to use when you generate HTTP headers for virtual host junctions. This encoding applies to headers 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

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.

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.

Junction fairness -l percent-value Soft limit for consumption of worker threads.

Junction fairness -L percent-value Hard limit for consumption of worker threads.

WebSphere single signon (LTPA) junctions -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 -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 -F "keyfile" Name of the key file used to encrypt LTPA cookie data. Only valid with -A option.

WebSphere single signon (LTPA) junctions -Z "keyfile-password" Password for the key file used to encrypt LTPA cookie data. Only valid with -A option.

Tivoli Federated Identity Manager SSO junctions -Y Enables Tivoli Federated Identity Manager single-signon (SSO) for the junction. Before we use this option, we must first configure the WebSEAL configuration files to support Tivoli Federated Identity Manager single-signon over junctions.

WebSEAL-to-WebSEAL SSL junctions -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 -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. Replica set that sessions on the virtual host junction are managed under. It is specified to 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.

Parent topic: Virtual Hosting

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 also specifies 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.
Virtual host option	-g vhost-label	The -g option causes a second, remote 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.
TCP and SSL	-a address	Local IP address that WebSEAL uses when it is communicating with the target back-end server. If not provided, WebSEAL uses the default address as determined by the operating system. If we supply an address for a particular junction, WebSEAL binds to this local address for all communication with the junctioned server.
TCP and SSL	-E description	A description for the junction.
TCP and SSL	-f	Force the replacement (overwrite) of an existing virtual host junction.
TCP and SSL	-i	WebSEAL server treats URLs as case insensitive.
TCP and SSL	-p port	TCP port of the back-end third-party server. Default is 80 for TCP junctions. Use 443 for SSL junctions.
TCP and SSL	-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.
TCP and SSL	-T resource/resource-group	Name of GSO resource or resource group. Required for and used only with -b gso option.
TCP and SSL	-w	Windows 32-bit (Win32) file system support.
Stateful junctions	-s	The virtual host junction support stateful applications. By default, junctions are not stateful.
Stateful junctions	-u UUID	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	-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	-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	-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	-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	-W "password"	WebSEAL password. Use with -B to send BA header information to back-end server.
Proxy junction (requires -t tcpproxy or -t sslproxy)	-H host-name	The DNS host name or IP address of the proxy server.
Proxy junction (requires -t tcpproxy or -t sslproxy)	-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
Supply identity information in HTTP headers	-c header-types	Insert client identity information specific to ISAM in HTTP headers across the virtual host junction. The header-types argument can include any combination of the following Security Verify Access HTTP header types: iv-user, iv-user-l, iv-groups, iv-creds, all.
Supply identity information in HTTP headers	-e encoding-type	Encoding to use when you generate HTTP headers for virtual host junctions. This encoding applies to headers 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
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.
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.
Junction fairness	-l percent-value	Soft limit for consumption of worker threads.
Junction fairness	-L percent-value	Hard limit for consumption of worker threads.
WebSphere single signon (LTPA) junctions	-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	-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	-F "keyfile"	Name of the key file used to encrypt LTPA cookie data. Only valid with -A option.
WebSphere single signon (LTPA) junctions	-Z "keyfile-password"	Password for the key file used to encrypt LTPA cookie data. Only valid with -A option.
Tivoli Federated Identity Manager SSO junctions	-Y	Enables Tivoli Federated Identity Manager single-signon (SSO) for the junction. Before we use this option, we must first configure the WebSEAL configuration files to support Tivoli Federated Identity Manager single-signon over junctions.
WebSEAL-to-WebSEAL SSL junctions	-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	-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. Replica set that sessions on the virtual host junction are managed under. It is specified to 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.