server task create
Creates a WebSEAL junction point.
Requires authentication (administrator ID and password) to use this command.
Syntax
- For local junctions:
- server task instance_name-webseald-host_name create –t type –d dir [options] junction_point
- For non-local junctions:
- server task instance_name-webseald-host_name create –t type –h host_name [options] junction_point
Options
- –d dir
- Specifies the local directory to the junction. This option is
required if the junction type is local.
This option is valid only with junctions that were created with the type of local.
- –h host_name
- Specifies the DNS host name or IP address of the target server.
This option is 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 {resource | resource_group}
- Specifies the name of the resource or resource group. This option is required only when the –b gso option is used. This option is valid for all junctions except for the type of local.
- 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 machine where the WebSEAL server is installed.
For example, the configured name of a single WebSEAL server instance is default. The host machine 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.
- junction_point
- Specifies the name of the directory in the WebSEAL protected object space where the document space of the server is mounted.
- options
- Specifies the options that you can use with the server
task create command. (Optional) These options include:
- –a address
- Specifies the local IP address that WebSEAL uses to communicate
with the target back-end server. If this option is not provided, WebSEAL
uses the default address as determined by the operating system.
If an address is supplied for a particular junction, WebSEAL is modified to bind to this local address for all communication with the junctioned server.
- –A
- Enables or disables lightweight third-party authentication mechanism
(LTPA) junctions. This option requires the –F and –Z options.
The –A, –F, and –Z options
all must be used together.
This option is valid for all junctions except for the type of local.
- –2
- You 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 the HTTP BA authentication
information to the server, which is one of the following values:
- filter (default)
- ignore
- supply
- gso
- –B
- Indicates that WebSEAL uses the BA header information to authenticate
to the server and to provide mutual authentication over SSL. This
option requires the –U and –W options.
This option is valid only with junctions that were created with the type of ssl or sslproxy.
- –c header_type
- Inserts the Security Access Manager client
identity in HTTP headers across the junction. The header_type argument
can include any combination of the Security Access Manager 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
Specifying –c all is the same as specifying –c iv_user,iv_groups,iv_creds.
This option is valid for all junctions except for the type of local.
- –C
- Indicates single sign-on from a front-end WebSEAL server to a
back-end WebSEAL server. The –C option is not
mutual authentication.
This option is valid only with junctions that were created with the type of ssl or sslproxy.
- –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.
- –e encoding_type
- Specifies the encoding to use when HTTP headers are generated
for junctions. This encoding applies to headers that are generated
with both the –c junction option and tag-value.
The following values for encoding are supported:
- 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.
This option is valid for all junctions except for the type of local.
- –f
- Forces the replacement of an existing junction.
This option is used for junctions that were created with any junction type.
- –F keyfile
- Specifies the location of the key file that is 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.
This option is valid for all junctions except for the type of local.
- –H host_name
- Specifies the 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,
This option is valid only with junctions that were created with the type of tcpproxy or sslproxy.proxy.www.example.com
- –i
- Indicates 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 that is 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
This option is valid for all junctions except for the type of local. Local junctions are not case-sensitive only on Win32 platforms; all other platforms are case-sensitive.
- –I
- Ensures a unique Set-Cookie header name attribute when the –j option
is used to modify server-relative URLs in requests.
This option is valid for all junctions except for the type of local.
- –j
- Supplies junction identification in a cookie to handle script-generated
server-relative URLs.
This option is valid for all junctions except for the type of local.
- –J trailer,inhead,onfocus,xhtml10
- Controls the junction cookie JavaScript block.
Use –J trailer to append the junction cookie JavaScript to HTML page returned from back-end server.
Use –J inhead to insert the Javascript block between <head> </head> tags for HTML 4.01 compliance.
Use –J onfocus to use the onfocus event handler in the JavaScript to ensure that the correct junction cookie is used in a multiple-junction/multiple-browser-window scenario.
Use –J xhtml10 to insert a JavaScript block that is HTML 4.01 and XHTML 1.0 compliant.
- –k
- Sends WebSEAL session cookies to the junction server. By default,
cookies are removed from requests that are sent to the server.
This option is valid for all junctions except for the type of local.
- –K "key_label"
- Specifies the key label of the client personal certificate that
WebSEAL must present to the server. Use of this option allows the
junction server to authenticate the WebSEAL server by using client
certificates.
This option is valid only with junctions that were created with the type of ssl and sslproxy.
- –l percent
- Defines the soft limit for consumption of worker threads.
This option is valid for all junctions except for the type of local.
- –L percent
- Defines the hard limit for consumption of worker threads.
This option is valid for all junctions except for the type of local.
- –n
- Indicates that no modifications of the names of non-domain cookies
are to be made. Use when client side scripts depend on the names of
cookies.
WebSEAL modifies the names of non-domain cookies that are returned from the junction to prefix with AMWEBJCT!junction_point. WebSEAL does this action by default, if a junction is listed in the JMT or if the –j junction option is used.
This option is valid for all junctions except for the type of local.
- –p port
- Specifies the TCP port of the back end third-party server. The
default value is 80 for TCP junctions and 443 for SSL junctions.
This option is valid for all junctions except for the type of local.
- –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 –P option
is required when the –H option is used.
This option is also valid for mutual junctions to specify the HTTPS port of the back-end third-party server.
- –q path
- Specifies the relative path for the query_contents script. By default,
Security Access Manager 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 back end Windows servers.
If you want to set Security Access Manager to not get any query_contents data from the junctioned server, you can specify this option as "-q disabled".
This option is valid for all junctions except for the type of local.
- –r
- Inserts the incoming IP address into the HTTP header across the junction. This option is valid for all junctions except for the type of local.
- –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. This option is valid for all junctions except for the type of local.
- –s
- Indicates that the junction support stateful applications. By default, junctions are not stateful. This option is valid for all junctions except for the type of local.
- –S path
- Specifies the location of the forms single sign-on configuration file. This option is valid for all junctions except for the type of local.
- –t type
- Specifies the type of junction; must be one of the following types:
- tcp
- tcpproxy
- ssl
- sslproxy
- local
- –u uuid
- Specifies the Universally Unique Identifier (UUID) of a server that is connected to WebSEAL by using a stateful junction (–s option). This option is valid for all junctions except for the type of local.
- –U "user_name"
- Specifies the WebSEAL server user name. This option requires the –B and –W options. WebSEAL uses the BA header information to authenticate to the server and to provide mutual authentication over SSL. This option is valid only with junctions that were created with the type of ssl or sslproxy.
- –v virtual_hostname[:HTTP-port]
- Specifies the virtual host name for the server. This option supports multiple virtual hosts that are served from the same Web server. Use –v when the junction server expects a host name header different from the DNS name of the server. This option is valid for all junctions except for the type of local. For mutual junctions, this value corresponds to the virtual host that is used for HTTP requests.
- –V virtual_hostname[:HTTPS-port]
- Specifies the virtual host name for the back-end server. This option supports multiple virtual hosts that are served from the same Web server. Use –V when the back-end junction server expects a host name header that is different from the DNS name of the server. This option is used only for mutual junctions and corresponds to the virtual host that is used for HTTPS requests.
- –w
- Indicates Microsoft Windows 32-bit (Win32) file system
support. This option:
- Provides all the functionality that is provided by the –i junction option.
- Disallows requests that contain file names that might be interpreted as Win32 file name aliases.
- –W "password"
- Specifies the WebSEAL server password. This option requires the –B and –U options. WebSEAL uses the BA header information to authenticate to the server and to provide mutual authentication over SSL. This option is valid only with junctions that were created with the type of ssl or sslproxy.
- –x
- Creates a path junction that is not apparent.
This option is valid for all junctions except for the type of local.
- –Y
- Enables Tivoli® Federated
Identity Manager single sign-on (SSO) for the junction.
Indicates that Kerberos SSO is enabled for the junction. Before you use this command, configure the WebSEAL configuration file to support Kerberos single sign-on over junctions.
- –Z keyfile_pwd
- Specifies the password of the key file that is 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. This option is valid for all junctions except for the type of local.
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/junction_point 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 Security Access Manager error messages by decimal or hexadecimal codes.
- This command is available only when WebSEAL is installed.
- For more information about creating a junctioned server, see the Administering topics in the IBM Knowledge Center.
- For more information about gathering statistics, see the Auditing topics in the IBM Knowledge Center.
Examples
- The following example creates a basic WebSEAL junction /pubs on
the default-webseald-cruz WebSEAL server. The junction
type is TCP, and the host name is doc.tivoli.com:
Output is like:pdadmin> server task default-webseald-cruz create -t tcp \ -h doc.tivoli.com /pubs
Created junction at /pubs
- The following example creates a new local junction / to replace
the current junction point. The –f option is
required to force a new junction that overwrites an existing junction
at the /tmp/docs directory:
Output is like:pdadmin> server task default-webseald-cruz create -t local \ -f -d /tmp/docs /
Created junction at /
- The following example limits worker thread consumption on a per
junction basis with a:
- Soft thread limit of 60.
- Hard thread limit of 80.
pdadmin> server task default-webseald-cruz create -t tcp \ -h cruz.dallas.ibm.com -l 60 -L 80 /myjunction