SALT Deployment File Reference

 

The following sections provide SALT Deployment File reference information:

•

Overview

•	SALT SALTDEPLOY Format

•	XML Schema

Overview

The SALT Deployment File (SALTDEPLOY) is an XML-based file used to define SALT GWWS server deployment information on a per Tuxedo machine basis. SALTDEPLOY does the following:

•	lists all necessary Web Service Definition Files (WSDF)

•	specifies how many GWWS servers are deployed on a Tuxedo machine

•	associates inbound and outbound Web Service access endpoints for each GWWS server.

SALTDEPLOY also provides a system section to configure global resources (for example certificates, plug-in load libraries, and so on).

SALT SALTDEPLOY Format

Figure B‑1 shows a graphical representation of the SALT SALTDEPLOY file format.

Figure B‑1 SALT Deployment File Format

XML Schema

An XML Schema is associated with a SALT SALTDEPLOY file. The XML Schema file that describes the SALT SALTDEPLOY file format is located in the following directory: $TUXDIR/udataobj/salt/saltdep.xsd.

SALT SALTDEPLOY Example

SALT SALTDEPLOY Element Descriptions

<Deployment>

 

SALT SALTDEPLOY Example

Listing B‑1 shows a sample SALT SALTDEPLOY File.

Listing B‑1 SALT SALTDEPLOY File Example

<Deployment xmlns="http://www.bea.com/Tuxedo/SALTDEPLOY/2007">

<WSDF>

<Import location="/home/myapp/bankapp.wsdf" />

<Import location="/home/myapp/amazon.wsdf" />

</WSDF>

<WSGateway>

<GWInstance id="GW1">

<Inbound>

<Binding ref="bankapp:bankapp_binding">

<Endpoint use="http1"/>

<Endpoint use="https1" />

</Binding>

</Inbound>

<Outbound>

<Binding ref="amazon:default_binding"/>

</Outbound>

<Properties>

<Property

name="socksAddrList"

value="proxy.server.com,10.123.10.10:1080"/>

</Properties>

</GWInstance>

</WSGateway>

<System>

<Certificate>

<PrivateKey>/home/user/cert.pem</PrivateKey>

</Certificate>

<Plugin>

<Interface library="/home/user/mydatahandler.so" />

</Plugin>

</System>

</Deployment>

 

SALT SALTDEPLOY Element Descriptions

SALTDEPLOYF format elements and their attributes are listed and described in the following section.

<Deployment>

The SALTDEPLOY file root element.

There is no attribute for this element.

Three sections must be defined within the <Deployment> element:

•	<WSDF> elements

•	<WSGateway> element

•	<System> element.

There can be only one <Deployment> element defined in a SALTDEPLOY file.

<WSDF>

Top element that encapsulates all imported WSDF files.

There is no attribute for this element.

<Import>

Specifies the WSDF to be imported in the SALTDEPLOY file. Multiple WSDF can be imported at the same time. Each WSDF file can only be imported once. Multiple WSDF with the same WSDF name cannot be imported in the same SALTDEPLOY file.

 

<Import> Attributes

Attribute	Description	Required
location	Specifies the WSDF local file path.	Yes

<WSGateway>

Top element that encapsulates all GWWS instance definitions.

There is no attribute for this element.

<GWInstance>

Specifies a single GWWS instance.

 

<GWInstance> Attributes

Attribute	Description	Required
id	Specifies the GWWS identifier. This attribute value may contain a maximum of 12 characters (excluding the terminating NULL character). The identifier value must be unique within the SALTDEPLOY file.	Yes

<Inbound>

Specifies inbound WSBinding objects for the GWWS server. Each inbound WSBinding object is specified using the <Binding> sub element.

There is no attribute for this element.

<HTTP>

Specifies a list of services accessible in REST mode. All Oracle Tuxedo service names specified in this element are callable using HTTP or REST mechanisms. Any URL specifying a service not present on this list results in a 404 error for the caller. Any URL specifying a service present on this list (for which an Oracle Tuxedo service is not advertised), results in a 451 error for the caller.

There is no attribute for this element.

<Network>

This element contains two attributes specifying http or https (for SSL), HTTP/REST listening endpoints.Only one <Network> element is allowed per GWWS instance.The http and https elements are optional, but at least one must be specified.The http and https attributes are constructed as follows:

<host>: The name or IP address of the HTTP/REST listening endpoint.

<port>: The port value of the HTTP/REST listening endpoint.

All HTTP/REST requests are performed by the same <host>:<port> combination (i.e., it is not possible to use more than one such combination per gateway, per protocol (http and https).

 

<Network> Attributes

Attribute	Description	Required
http	HTTP host and port listening endpoint for REST requests. Format is a string containing a <host>:<port> pair corresponding to: <host> = name or IP address of the HTTP/REST listening endpoint. <port> = port value of the HTTP/REST listening endpoint.	No*
https	SSL HTTP host and port listening endpoint specification. Same format as http attribute.	No*

* While not required, the <Network> element must contain either an http or https attribute.

<Service>

Specifies a single service callable using HTTP/REST mechanisms. The actual Oracle Tuxedo service called is further qualified by an HTTP method as specified using the <Method> element.

 

<Service> Attributes

Attribute	Description	Required
name	Name of Tuxedo service being advertised. Note: This is not the actual Oracle Tuxedo service configured using the <Method> element.	Yes
content-type	"JSON" represent "Content-Type: application/json", "XML" represent "Content-Type: application/xml". If request HTTP header has no content-type field, SALT will use the content-type attribute set here.	No
charset	Specifies the character encoding for the outgoing REST network message.	No

<Method>

Specifies the HTTP method mapping to Oracle Tuxedo services. This is designed to model CRUD methods (Create, Read, Update, Delete).

 

<Service> Attributes

Attribute	Description	Required
name	Method identifier, among GET, PUT, POST or DELETE. Any other value results in a configuration error.	Yes
service	Name of the Oracle Tuxedo service being mapped.	Yes
inputbuffer	Oracle Tuxedo buffer type/optionally subtype used for input conversion. Values are the same as all existing Oracle Tuxedo buffer types. For VIEW/VIEW32 buffer types, the notion of subtype is conveyed by using the notation: {VIEW|VIEW32}/<Subtype>, for example: VIEW32/customer.	Yes
reposservice	Reference to a metadata repository entry. This is used to associate interface data with an HTTP/REST service and method. One use is for the configuration tool to generate automatic test code based on service metadata (interface).	No

<Outbound>

Specifies outbound WSBinding objects for the GWWS server. Each outbound WSBinding object is specified using the <Binding> sub element.

There is no attribute for this element.

<Binding>

Specifies a concrete WSBinding object as either an inbound or outbound binding, depending on the parent element.

 

<Binding> Attributes

Attribute	Description	Required
ref	Specifies a concrete WSBinding object using the following Qualified Name format: “<WSDF_name>:<WSBinding_id>”	Yes

Note:

Please note the following maximum WSBinding object limitations for each GWWS server:

•	Each GWWS server may reference at most 64 inbound WSBinding objects.

•	Each GWWS server may reference at most 128 outbound WSBinding objects.

For TCP/IP addresses, one of the following formats is used as shown in Table B‑7.

 

Ipv4 and IPv6 Address Formats

IPv4	IPv6
//IP:port	//[IPv6 address]:port
//hostname:port_number	//hostname:port_number
//#.#.#.#:port_number	Hex format is not supported

For more information, see TMUSEIPV6 in the TUXENV(5) environment variable listing found in the Tuxedo 10g R3 Reference Guide, Section 5 - File Formats, Data Descriptions, MIBs, and System Processes Reference.

<Endpoint>

Specifies a single WSBinding objects endpoint reference.

If the referenced endpoint is specified as an inbound endpoint, the GWWS server creates the corresponding HTTP and/or HTTPS listen endpoint. At least one inbound endpoint must be specified for one inbound WSBinding object.

If the referenced endpoint is specified as an outbound endpoint, the GWWS server creates HTTP and/or HTTPS connections per SOAP requests for the outbound WSBinding object.

If an outbound endpoint is not specified for the outbound WSBinding object, the first 10 endpoints (at most) are auto-selected.

The referenced endpoint must already be defined in the WSDF.

 

<Endpoint> Attributes

Attribute	Description	Required
use	The referenced endpoint id defined in the WSDF.	Yes

Note:

Please note the following maximum endpoints limitations for each GWWS server:

•	Each GWWS server may create at most 128 inbound endpoints in all inbound WSBinding objects to accept SOAP requests.

•	Each GWWS server may create connectivity with at most 256 outbound endpoints in all outbound WSBinding objects.

<WSAddressing>

Specifies if Web Service Addressing is enabled for the outbound WSBinding object.

If this element is present, by default all SOAP messages are sent out with a Web Service Addressing message header.

 

<WSAddressing> Attributes

Attribute	Description	Required
version	Select WS-Addressing on-the-wire version to use 200408 for the "submission" version, and 200508 for version 1. If not defined, version defaults to 200408	No

The <WSAddressing> sub element <Endpoint> must be specified for the listen endpoint address if this element is present.

<Endpoint>

Specifies the WS-Addressing listen endpoint address for the referenced outbound WSBinding object.

 

<Endpoint> Attributes

Attribute	Description	Required
address	Specifies the WS-Addressing listen endpoint address. The address value must be in the following format: "http(s)://<host>:<port>/<context_path>" The GWWS server creates listen endpoints and usage for receiving WS-Addressing SOAP response messages.	Yes

<HTTP>

Specifies a list of outbound services accessible in REST mode.

<Service>

Specifies a outbound service callable using HTTP/REST mechanisms.

 

<Service> Attributes

Attribute	Description	Required
name	Name of Tuxedo service being advertised.	Yes
content-type	"JSON" represent "Content-Type: application/json", "XML" represent "Content-Type: application/xml". If request HTTP header has no content-type field, SALT will use the content-type attribute set here.	No
charset	Specifies the character encoding for the outgoing REST network message.	No

<TLogDevice>

One attribute "location" describes the location of the Transaction file. This is required if WS-TX transaction support is required.

<TLogName>

One attribute "id" describes the name of the transaction log inside a Transaction file. This is required if WS-TX transaction support is required.

<WSATEndpoint>

One attribute "address" describes the WS-AT protocol end point.

<MaxTran>

One attribute "value" describes the maximum number of concurrent WS-TX transactions allowed. This is bounded by Oracle Tuxedo MAXGTT.

<Properties>

Top element that encapsulates all GWWS server property settings using the <Property> sub element.

 

<Properties> Attributes

Attribute	Description	Required
socksAddrList	If necessary, endpoints can be grouped by GWInstance to achieve separation between proxy-using endpoints and non-proxy-using ones. Value: String type containing a list of proxy server URLs. For example: proxy.server1.com,10.123.1.1:1080.	Yes

<Property>

Specifies one GWWS property.

 

<Property> Attributes

Attribute	Description	Required
name	Specifies the property name. Table B‑14 lists all the GWWS server properties.	Yes
value	Specifies the property value.	Yes

 

GWWS <Property> List

Property	Description	Values
max_content_length	Enables the GWWS server to deny the HTTP requests when the content length is larger than the property setting. If not specified, the GWWS server does not check for it. The string value can be one of the following three formats: 1. Integer number in bytes. No suffix means the unit is bytes. 2. Float number in kilobytes. The suffix must be ‘K’. For instance, 10.4K, 40K, etc. 3. Float number in megabytes. The suffix must be ‘M’. For instance, 100M, 20.6M, etc.	The equivalent byte size value must be in [1 byte, 1G byte] range.
thread_pool_size	Specifies the maximum thread pool size for the GWWS server. Note: This value defines the maximum possible threads that may be spawned in the GWWS server. When the GWWS server is running, the actual spawned threads may be less than this value.	The valid value is in [1, 1024]. Default value: 16
timeout	Specifies the network time-out value, in seconds.	The valid value is in [1, 65535]. Default value: 300
max_backlog	Specifies the backlog listen socket value. It controls the maximum queue length of pending connections by operating system. Note: Generally no tuning is needed for this value.	The valid value is [1-255]. Default value: 16
enableMultiEncoding	Toggles on/off multiple encoding message support for the GWWS server. If multiple encoding support property is turned off, only UTF-8 HTTP / SOAP messages can be accepted by the GWWS server.	The valid values are “true”, “false”. Default value: false
enableSOAPValidation	Toggles on/off XML Schema validation for inbound SOAP request messages if the corresponding Tuxedo input buffer is associated with a customized XML Schema.	The valid values are “true”, “false”. Default value: false
internalEncoding	Mutually exclusive with enableMultiEncoding. Allows one-byte encodings such as the ISO-8859 series to map to non-MBSTRING types. When it is set to a value other than "keepSame", SALT converts text in payloads to/from the specified encoding between the Tuxedo side (encoding translated based on the value of internalEncoding attribute) and the network side (SOAP or REST). This property must not be used with multi-byte encodings and in conjunction with MBSTRING buffers or fields; otherwise, a runtime error is thrown.	The valid values are "keepSame", one-byte encoding name such as the ISO-8859.

<System>

Specifies global settings, including certificate information, plug-in interfaces.

<Certificate>

Specifies global certificate information using sub elements <PrivateKey>, <VerifyClient>, <TrustedCert> and <CertPath>.

There is no attribute for this element.

Note:

GWWS converts certificate to wallet when SEC_PRINCIPAL_PASSWORD is set. If only X509 certicates are used under HTTP, then there is no conversion.

<PrivateKey>

When using an Oracle wallet, specifes the location of a directory that contains an Oracle Wallet.

Notes:

SALT does not have the concept of a security principal name like Oracle Tuxedo does, so the Wallet is located in the specified directory and not in a subdirectory.

To configure server identity certificates (SALT deploy configuration file <PrivateKey> element ), it is required that the root certificate authority be present in the SSL configuration file. Proper configuration is:

•	root CA certificate

•	intermediate certificate(s) (if any)

•	server certificate

•	server private key

•	in PEM format.

When using the legacy security credentials format, specifies the PEM format private key file. The key file path is specified as the text value for this element. The server certificate is also stored in this private key file. The value of this element may contain a maximum of 256 characters (excluding the terminating NULL character).

With either security credential format, the password for the Oracle Wallet or the GWWS private key file is specifed in the TUXCONFIG file using the SEC_PRINCIPAL_PASSVAR="environment_variable_name" parameter. The TUXCONFIG file must also set the SEC_PRINCIPAL_NAME="any_non-null_string(not_used)" parameter so that SEC_PRINCIPAL_PASSVAR will be properly processed in the configuration file.

This element is mandatory if the parent <Certificate> element is configured.

<VerifyClient>

Specifies if Web service clients are required to send a certificate via HTTP over SSL connections. The valid element values are "true" and "false".

This element is optional. If not specified, the default value is "false".

<TrustedCert>

Specifies the file name of the trusted PEM format certificate files. The value of this element may contain a maximum of 256 characters (excluding the terminating NULL character).

This element is optional.

<CertPath>

Specifies the local directory where the trusted certificates are located. The value of this element may contain a maximum of 256 characters (excluding the terminating NULL character).

This element is optional.

Note:

If <VerifyClient> is set to “true”, or if WS-Addressing is used with SSL, trusted certificates must be stored in the directory setting with this element.

<Plugin>

Specifies the global plug-in load library information. Each <Interface> sub element specifies one plug-in library to be loaded.

There is no attribute for this element.

<Interface>

Specifies one particular plug-in interface or a plug-in library for all plug-in interfaces inside the library.

 

<Interface> Attributes

Attribute	Description	Required
library	Mandatory. Specifies a local shared library file path. This attribute value may contain a maximum of 256 characters (excluding the terminating NULL character).	Yes
params	Optional. Specifies a particular string value that is passed to the library when initialized by the GWWS server at boot time. This attribute value may contain a maximum of 256 characters (excluding the terminating NULL character).	No

Note:

For more information about how to develop a SALT plug-in interface, see “Using SALT Plug-ins” in the SALT Programming Web Services.