{section}
{column}

{warning}This version must be installed on [Petals ESB 5.4.0|petalsesb540:Petals ESB 5.4.0]+{warning}

{column:width=40%}
{panel:title=Table of contents}{toc:outline=true}{panel}
{panel:title=Contributors}{contributors:order=name|mode=list|showAnonymous=true|showCount=true|showLastTime=true}{panel}
{column}
{section}

h1. Setting up a simple domain-to-domain propagation

Let's consider two domains A and B.
The number of containers in each of the domain is not important here: we must only select for each one container onto which the Gateway BC and its SU will deployed.

The domain A will act as the provider domain and will thus declare in its SU a set of Consumes as well as information needed to identify the consumer domain.

The domain B will act as the consumer domain and will thus declare in its SU the information needed to connect to the provider domain.

Let's consider that A will propagate several services:
* One denoted only by its interface name {{Interface1}} (hence it will matches all endpoints of that interface, potentially with different service name and of course with different endpoint names).
* One denoted by its interface name {{Interface2}} and service name {{Service2}} (hence it will matches all endpoints of that interface and service name).
* One denoted by its interface name {{Interface3}}, service name {{Service3}} and endpoint name {{endpoint3}} (hence it will match exactly one endpoint).

h2. Provider Domain A

For the provider domain, it is necessary to both define a Consumes SU and a transport listener at the component level.

h3. Consumes SU

The Consumes SU deployed on the Domain A is as follow:

{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi version="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:cdk="http://petals.ow2.org/components/extensions/version-5" xmlns:g="http://petals.ow2.org/components/petals-bc-gateway/version-1.0"
xmlns:test="http://test/">

<jbi:services binding-component="true">

<jbi:consumes interface-name="test:Interface1">

<!-- CDK specific elements -->
<cdk:mep xsi:nil="true" />

<!-- Component specific elements -->
<g:consumer domain="domainB" />

</jbi:consumes>

<jbi:consumes interface-name="test:Interface2" service-name="test:Service2">

<!-- CDK specific elements -->
<cdk:mep xsi:nil="true" />

<!-- Component specific elements -->
<g:consumer domain="domainB" />

</jbi:consumes>

<jbi:consumes interface-name="test:Interface3" service-name="test:Service3" endpoint-name="endpoint3">

<!-- CDK specific elements -->
<cdk:mep xsi:nil="true" />

<!-- Component specific elements -->
<g:consumer domain="domainB" />

</jbi:consumes>

<g:consumer-domain id="domainB" transport="transport1">
<g:auth-name>UniquelySharedBetweenA&B</g:auth-name>
</g:consumer-domain>

</jbi:services>
</jbi:jbi>
{code}

Here we see we chose to use the authentication name {{UniquelySharedBetweenA&B}} and the consumer domain will need to know this information.

{warning}The authentication name is +NOT+ meant to introduce security in the use of the Gateway BC: for that it is necessary to use [SSL|#ssl]!{warning}

h3. Component's Transport Listener

As we can see the Consumes SU relies on the existence of a transport called {{transport1}}.
By default there is no pre-configured transport listener on the Gateway BC but there is multiple ways to define them statically (see [#component-configuration] below) or dynamically with Petals CLI (see [petalsclisnapshot:Petals BC Gateway tooling]).

For example, we can use the following CLI command to create the transport listener before deploying the Consumes SU:
{code}
> bc-gateway.add-transport-listener -i transport1 -p 7500
{code}

Here we chose the port {{7500}} and the consumer domain will need to know this information.

h2. Consumer Domain B

For the consumer domain, it is only necessary to define a Provides SU based on the previously gathered information (authentication name, port) and hostname of the provider domain BC Gateway.
The Provides SU deployed on the Domain B is as follow:

{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi version="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:cdk="http://petals.ow2.org/components/extensions/version-5" xmlns:g="http://petals.ow2.org/components/petals-bc-gateway/version-1.0">

<jbi:services binding-component="true">

<g:provider-domain id="domainA">
<g:remote-ip>domainA-hostname</g:remote-ip>
<g:remote-port>7500</g:remote-port>
<g:remote-auth-name>UniquelySharedBetweenA&B</g:remote-auth-name>
</g:provider-domain>

</jbi:services>
</jbi:jbi>
{code}

h2. Examples of Service Propagations

If we start with one container for A and one container for B without anything on them and after:
* deploying the Gateway BC on each of the container of A and B.
* adding the transport listener on the Gateway BC of A.
* deploying the Consumes SU on the Gateway BC of A and the Provides SU on the Gateway BC of B.

{tip}The order of deployment is not very important as by default, the Provides SU will try to reconnect until it succeeds.{tip}

We can see that no endpoints have been deployed on B: this is expected because A will only propagate existing endpoints.

Now if we deploy some endpoints on domain A:
* {{InterfaceX:ServiceX:endpointX}}, then no endpoint will be activated on B.
* {{Interface1:Service1a:endpoint1a}}, then {{Interface1:Service1a:xxx}} will be activated on B.
* {{Interface1:Service1a:*endpoint1a*}} and {{Interface1:Service1a:*endpoint1b*}}, then {{Interface1:Service1a:xxx}} will be activated on B.
* {{Interface1:*Service1a*:endpoint1a}} and {{Interface1:*Service1b*:endpoint1b}}, then {{Interface1:*Service1a*:xxx}} and {{Interface1:*Service1b*:xxx}} will be activated on B.
* {{Interface2:*Service2*:endpoint2a}} and {{Interface1:*Service2b*:endpoint2b}}, then only {{Interface1:*Service2*:xxx}} will be activated on B.
* {{Interface3:Service3:endpoint3}}, then {{Interface3:Service3:xxx}} will be activated on B.
* Etc.

We can notice that the endpoint name is never propagated because it is considered that the endpoint is only a technical information to locate an endpoint in a domain.

We can also notice that what matters is always the pair interface and service name, and in case no service name is specified in the Consumes SU, then each existing service in the provider domain will be propagated as its own service.

{anchor:ssl}
h1. Using SSL to authenticate and encrypt exchanges between domains

In order to secure connections between provider and consumer domain, it is possible to rely on SSL.
SSL itself takes care of the encryption, but it is necessary for the provider domain, and optionally for the consumer domain, to have a certificate shared between parties to authenticate them.
There can't thus be encryption without authentication of at least the provider domain and ideally also of the consumer domain!

h2. Authenticating only the Provider Domain

For a provider domain, using SSL means to define a certificate that consumer domains that connect to it can use to authenticate it.
The certificate is a public information and the provider domain owns also a private key that it can use to answers authentication challenges from the consumer domain.

h3. Provider Domain A

On the provider side, the {{consumer-domain}} element must be updated with the following parameters:
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi ...>

<jbi:services binding-component="true">
...

<g:consumer-domain id="domainB" transport="transport1">
<g:auth-name>UniquelySharedBetweenA&B</g:auth-name>
<g:certificate>path/to/a/certificate+provider.crt</g:certificate>
<g:key>path/to/the/key.pem</g:key>
<g:passphrase>secret-to-unlock-the-key<g:passphrase>
</g:consumer-domain>

</jbi:services>
</jbi:jbi>
{code}

Note that this means that setting up SSL is done per consumer domain that will connect to this SU, but nothing prevent us to configure the same certificate for multiple consumer domains of course!

h3. Consumer Domain B

On the consumer side, the {{consumer-domain}} element must be updated with the following parameters:
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi ...">

<jbi:services binding-component="true">

<g:provider-domain id="domainA">
<g:remote-ip>domainA-hostname</g:remote-ip>
<g:remote-port>7500</g:remote-port>
<g:remote-auth-name>UniquelySharedBetweenA&B</g:remote-auth-name>
<g:remote-certificate>path/to/the/certificate-provider.crt</g:remote-certificate>
</g:provider-domain>

</jbi:services>
</jbi:jbi>
{code}

h2. Authenticating both the Provider and Consumer domains

Optionally, it is also possible to superpose on this basic SSL setup the use of a certificate that the provider domain will use to authenticate the consumer domain.
The later will also own a private key then.

h3. Provider Domain A

On the provider side, the {{consumer-domain}} element must be updated with the following parameters:
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi ...>

<jbi:services binding-component="true">
...

<g:consumer-domain id="domainB" transport="transport1">
<g:auth-name>UniquelySharedBetweenA&B</g:auth-name>
<g:certificate>path/to/a/certificate-provider.crt</g:certificate>
<g:key>path/to/the/key.pem</g:key>
<g:passphrase>secret-to-unlock-the-key<g:passphrase>
<g:remote-certificate>path/to/the/certificate-consumer.crt
</g:consumer-domain>

</jbi:services>
</jbi:jbi>
{code}

This means that even if multiple Provides SUs connects to this provider domain, they all must use the same certificate as it is a mean to authenticate a consumer domain and not an individual node of this domain.

h3. Consumer Domain B

On the consumer side, the {{consumer-domain}} element must be updated with the following parameters:
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi ...">

<jbi:services binding-component="true">

<g:provider-domain id="domainA">
<g:remote-ip>domainA-hostname</g:remote-ip>
<g:remote-port>7500</g:remote-port>
<g:remote-auth-name>UniquelySharedBetweenA&B</g:remote-auth-name>
<g:remote-certificate>path/to/the/certificate-provider.crt</g:remote-certificate>
<g:certificate>path/to/a/certificate-consumer.crt</g:certificate>
<g:key>path/to/the/key.pem</g:key>
<g:passphrase>secret-to-unlock-the-key<g:passphrase>
</g:provider-domain>

</jbi:services>
</jbi:jbi>
{code}

h1. Service Unit Configuration

h2. Consumes SU

In a Consumes SU, one must declare at least one '{{consumer-domain}}' and some '{{consumes}}' element to determine the services to be propagated to one or several of these consumer domains.

The '{{consumes}}' element can't override each other for the same '{{consumer-domain}}':
* If there is a '{{consumes}}' of type {{Interface:Service:endpoint}}, then there can't be another '{{consumes}}' of type {{Interface:Service:endpoint}}, {{Interface:Service:}} or {{Interface::}} defined for the same {{consumer-domain}}.
* If there is a '{{consumes}}' of type {{Interface:Service:}}, then there can't be another '{{consumes}}' of type {{Interface:Service:}} or {{Interface::}} defined for the same '{{consumer-domain}}'.
* If there is a '{{consumes}}' of type {{Interface::}}, then there can't be another '{{consumes}}' of type {{Interface::}} defined for the same '{{consumer-domain}}'.

h2. Configuration

All needed information must be defined in the service-unit JBI descriptor. This JBI descriptor is configured through parameters divided in following groups:
* *JBI parameters* that defines the service provider identification,
* *CDK parameters* that are parameters driving the service consumer implementation at CDK layer,
* *CDK interceptor parameters* that are parameters driving interceptors at CDK layer,
* *Dedicated parameters* that are parameters driving the service consumer implementation at component layer:
** Defining the provider domain linked to the current consumer domain.

h3. CDK parameters defining service consumer implementation

h4. Definition of the provider domain linked to the current consumer domain

A consumer domain is defined through a sub-element '{{consumer-domain}}' under the JBI element'{{services}}.

{center}{*}Configuration of a {{consumer-domain}} element*{center}
{table-plus}
|| +Attribute+ or element || Description || Default value || Required || Support of placeholders ||
| +id+ | A unique name (in the SU) to identify this consumer domain configuration | \- | Yes | Yes |
| +transport+ | The identifier of a transport listener configured in the component | \- | Yes | Yes |
| auth-name | A unique name (in the transport listener) to be shared with the consumer domain that will connect to this SU | \- | Yes | Yes |
| remote-certificate | The path to a shared SSL certificate (X.509 certificate in PEM format) used to authenticate the consumer domain that will connect to this SU (relative path means in the SU, absolute path means on the filesystem) | \- | No | Yes |
| certificate | The path to a shared SSL certificate used to secure the connections (relative path means in the SU, absolute path means on the filesystem) | \- | Yes if {{remote-certificate}} is specified | Yes |
| key | The path to a private SSL key (PKCS#8 private key in PEM format) for the SSL certificate specified with {{certificate}} (relative path means in the SU, absolute path means on the filesystem) | \- | Yes if {{certificate}} is specified, else ignored | Yes |
| passphrase | The passphrase to unlock the SSL key specified with {{key}} | \- | Only if {{key}} is specified and needs a passphrase, else ignored | Yes |
| +propagation-polling-max-delay+ | The maximum delay between polling done by this SU to check new or removed endpoints in the domain (a 0 or negative value means no polling) in milliseconds| {{5000}} | Yes | Yes |
| +propagation-polling-acceleration+ | The polling starts at 5sec and is multiplied by this factor after each polling until the maximum delay is attained (a value equals to 1 or less means no acceleration, i.e., the delay is always at the configured maximum) | 2.0 | Yes | Yes |
{table-plus}

h4. Service consumer
To link a service consumer to an external service proBy default all service providers are exported with their current names to all consumer domains. You can select which service provider is exported in a given provider domain, evantually rewriting its names. Please use the following parameters of the element '{{provides}}':

{table-plus}
|| Element || Description || Default value || Required || Support of placeholders ||
| consumer | The identifier of a {{consumer-domain}} element specified in the SU | Yes (and more than once) | No |
{table-plus}

Note that in {{consumes}} elements for the Gateway BC, it has no meaning to specify a {{mep}} or an {{operation}}: they will be ignored, thus it is recommended to always set the {{mep}} to {{nil}} (because it is required to specify it):
{code:lang=xml}
<cdk:mep xsi:nil="true" />
{code}

h1. Provides SU

In a Provides SU, one must declare at least one {{provider-domain}} and optionally some {{provides}} element to determine how the services are being propagated from one of the provider domains.

The '{{provides}}' element must have a '{{provider}}' element and these can't override each other for the same '{{provider-domain}}':
* If there is a '{{provides}}' with a '{{provider}}' of type {{Interface:Service:endpoint}}, then there can't be another '{{provides}}' with a '{{provider}}' of type {{Interface:Service:endpoint}} or {{Interface:Service:}} defined for the same '{{provider-domain}}'.
* If there is a '{{provides}}' with a '{{provider}}' of type {{Interface:Service:}}, then there can't be another '{{provides}}' with a '{{provider}}' of type {{Interface:Service:}} defined for the same '{{provider-domain}}'.

h2. Configuration

All needed information must be defined in the service-unit JBI descriptor. This JBI descriptor is configured through parameters divided in following groups:
* *JBI parameters* that defines the service provider identification,
* *CDK parameters* that are parameters driving the service consumer implementation at CDK layer,
* *CDK interceptor parameters* that are parameters driving interceptors at CDK layer,
* *Dedicated parameters* that are parameters driving the service consumer implementation at component layer:
** Defining the provider domain,
** Defining the service providers exported.

h3. CDK parameters defining service consumer implementation

h4. Provider domain definition

A provider domain is defined through a sub-element '{{provider-domain}}' under the JBI element'{{services}}.

{center}{*}Configuration of a {{provider-domain}} element*{center}
{table-plus}
|| +Attribute+ or element || Description || Default value || Required || Support of placeholders ||
| +id+ | A unique name (in the SU) to identify this provider domain configuration | \- | Yes | Yes |
| remote-ip | The ip or hostname of the remote provider domain gateway | \- | Yes | Yes |
| remote-port | The port of the remote provider domain gateway | {{7500}} | Yes | Yes |
| remote-auth-name | A name to be shared with the provider domain that this SU will connect to | \- | Yes | Yes |
| certificate | The path to a shared SSL certificate used to authenticate me (relative path means in the SU, absolute path means on the filesystem) | \- | No | Yes |
| key | The path to a private SSL key (PKCS#8 private key in PEM format) for the SSL certificate specified with {{certificate}} (relative path means in the SU, absolute path means on the filesystem) | \- | Yes if {{certificate}} is specified, else ignored | Yes |
| passphrase | The passphrase to unlock the SSL key specified with {{key}} | \- | Yes if {{key}} is specified and needs a passphrase, else ignored | Yes |
| remote-certificate | The path to a shared SSL certificate (X.509 certificate in PEM format) used to authenticate the provider domain that this SU will connect to (relative path means in the SU, absolute path means on the filesystem) | \- | Yes if {{certificate}} is specified | Yes |
| +propagate-all+ | Set to {{false}} to propagate only the services declared as {{provides}} in the SU | {{true}} | Yes | Yes |
| +retry-delay+ | Delay between retry in case of disconnection in milliseconds | {{5000}} | Yes | Yes |
| +retry-max+ | Maximum retries before failing to connect (a negative value means infinite) | {{-1}} | Yes | Yes |
{table-plus}

h4. Service provider export

By default all service providers are exported with their current names to all consumer domains. You can select which service provider is exported in a given provider domain, evantually rewriting its names. Please use the following parameters of the element '{{provides}}':

{table-plus}
|| +Attribute+ or element || Description || Default value || Required || Support of placeholders ||
| +domain+ | The identifier of a {{provider-domain}} element specified in the SU | \- | Yes | No |
| provider-interface-name | The interface name of a service propagated by the provider domain that this SU will connect to (can be the same as the {{provides}}'s) | \- | Yes | No |
| provider-service-name | The service name of a service propagated by the provider domain that this SU will connect to (can be the same as the {{provides}}'s) | \- | Yes | No |
| provider-endpoint-name | The endpoint name of a service propagated by the provider domain that this SU will connect to | \- | No | No |
{table-plus}

h3. Service unit content

The service unit has to contain the following elements, packaged in the archive:
* the META-INF/jbi.xml descriptor file as described above.

{code}
service-unit.zip
+ META-INF
- jbi.xml (as defined above)
{code}

h3. Example

{code:xml}
<jbi:jbi version="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:cdk="http://petals.ow2.org/components/extensions/version-5" xmlns:jg="http://petals.ow2.org/components/petals-bc-gateway/version-1.0"
xmlns:hello="http://petals.ow2.org">

<jbi:services binding-component="true">

<jg:provider-domain id="gw-domain-1-0">
<jg:remote-auth-name>${domain.1.gateway.secret}</jg:remote-auth-name>
<jg:remote-ip>${domain.1.0.gateway.host}</jg:remote-ip>
<jg:remote-port>${domain.1.0.gateway.port}</jg:remote-port>
</jg:provider-domain>

<jg:provider-domain id="gw-domain-1-1">
<jg:remote-auth-name>${domain.1.gateway.secret}</jg:remote-auth-name>
<jg:remote-ip>${domain.1.1.gateway.host}</jg:remote-ip>
<jg:remote-port>${domain.1.1.gateway.port}</jg:remote-port>
</jg:provider-domain>

</jbi:services>
</jbi:jbi>
{code}

{anchor:component-configuration}
h1. Configuring the component

The component can be configured through the parameters of its JBI descriptor file. These parameters are divided in following groups:
* *JBI parameters* that have not to be changed otherwise the component will not work,
* *CDK parameters* that are parameters driving the processing of the CDK layer,
* and parameters dedicated to the Gateway part:
** consumer domain,
** provider domain.

{code:lang=xml}
<jbi:jbi xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5"
xmlns:jbi="http://java.sun.com/xml/ns/jbi" version="1.0"
xmlns:rest="http://petals.ow2.org/components/rest/version-1">

<jbi:component type="binding-component">
...
<petalsCDK:acceptor-pool-size />
<petalsCDK:acceptor-retry-number />
<petalsCDK:acceptor-retry-wait />
<petalsCDK:acceptor-stop-max-wait />
<petalsCDK:processor-pool-size />
<petalsCDK:processor-max-pool-size />
<petalsCDK:processor-keep-alive-time />
<petalsCDK:processor-stop-max-wait />
<petalsCDK:time-beetween-async-cleaner-runs />
<petalsCDK:properties-file />
<petalsCDK:monitoring-sampling-period />
<petalsCDK:activate-flow-tracing />
<petalsCDK:propagate-flow-tracing-activation />
...
<g:consumer-domains-max-pool-size />
<g:provider-domains-max-pool-size />
...
</jbi:component>
</jbi:jbi>
{code}

h2. CDK parameters

These parameters drive features proposed by the component and configure the Gateway part:
* consumer domain,
* provider domain.

h3. Parameters of the consumer domain part
{table-plus}
|| {color:#333333}Parameter{color} || {color:#333333}Description{color} || {color:#333333}Default{color} || {color:#333333}Required{color} || Scope ||
| provider-domains-max-pool-size | Max number of threads used for handling outgoing provider partner connections: while each outgoing provider partner connection handles one exchange at a time, this limits the number of concurrent exchange processing amongst all outgoing connection | 6 | No | Installation |
{table-plus}

h3. Parameters of the provider domain part
{table-plus}
|| {color:#333333}Parameter{color} || {color:#333333}Description{color} || {color:#333333}Default{color} || {color:#333333}Required{color} || Scope ||
| consumer-domains-max-pool-size | Max number of threads used for handling incoming consumer partner connections: while each incoming consumer partner connection handles one exchange at a time, this limits the number of concurrent exchange processing amongst all incoming connection | 6 | No | Installation |
{table-plus}

h1. Logging

The traces of Apache Netty itself can be activated through the logging configuration file of Petals ESB. The root logger for Netty is {{io.netty}}:
{code}
...
io.netty.level=INFO
...
{code}

h1. Business monitoring

The flow tracing propagation from a service provider implemented with this component to another service provider is driven by the parameter '{{propagate-flow-tracing-activation}}' of the associated service consumer definitions. If no parameter is defined at service consumer level, the component configuration parameter 'propagate-flow-tracing-activation' is used. Finally, by default, the flow tracing propagation is enabled.

h1. Monitoring the component

h2. Using metrics

Several probes providing metrics are included in the component, and are available through the JMX MBean '{{org.ow2.petals:type=custom,name=monitoring_*<component-id>*}}', where {{*<component-id>*}} is the unique JBI identifier of the component.

No dedicated metric is available.

h2. Receiving alerts

Several alerts are notified by the component through notification of the JMX MBean '{{org.ow2.petals:type=custom,name=monitoring_*<component-id>*}}', where {{*<component-id>*}} is the unique JBI identifier of the component.

{tip}To integrate these alerts with Nagios, see [petalsesbsnapshot:Receiving Petals ESB defects in Nagios].{tip}

No dedicated alert is available.