ActiveSpaces Enabler Runtime Context Variables

When you run an as-agent from the command line, specify options that tell the as-agent the name of the metaspace to connect to, the discovery URL for the metaspace, the member name to use for the as-agent, and so on. To run as-agents from the TIBCO Silver Fabric environment, ActiveSpaces Enabler maps the as-agent command line options to Component Runtime Context Variables. The following is a list of the as-agent command line options and how they have been mapped to Component Runtime Context Variables.

.

Table 3 Enabler Runtime Context Variables

Command Line Option	Runtime Context Variable	Default
-metaspace <metaspace_name>	AS_METASPACE	“ms”
-member_name <member_name>	AS_MEMBER_NAME_PREFIX	<component_name>
-discovery <url /url_list>	AS_DISCOVERY
	AS_DISCOVERY_PORT	52000
	AS_DISCOVERY_MULTICAST_ADDRESS	239.8.8.8
	AS_MULTICAST_DISCOVERY_URL	tibpgm://<AS_DISCOVERY_PORT>/<engine_IP_address>; <AS_DISCOVERY_MULTICAST_ADDRESS>
	AS_NUM_DISCOVERY_NODES	0
	AS_TOTAL_DISCOVERY_NODES	0
	AS_SHARED_DISCOVERY_DIR
	AS_FIND_DISCOVERY_MAX	5
	AS_FIND_DISCOVERY_WAIT	30 seconds
	AS_DISCOVERY_NODE_RECOVERY _TRIES	0
-listen <url>	AS_LISTEN
	AS_LISTEN_PORT	5700
-remote_listen <url>	AS_REMOTE_LISTEN AS_REMOTE_LISTEN_PORT	-32768
-data_store <directory_path>	AS_DATA_STORE
-autojoin.role <role>	AS_AUTOJOIN_ROLE
-log <file_path>	AS_LOG
-log_debug <log_level>	AS_LOG_DEBUG	3 (INFO)
-log_limit <limit>	AS_LOG_LIMIT	-1 (no limit)
-log_count <count>	AS_LOG_COUNT	1
-log_append <boolean>	AS_LOG_APPEND	true
-debug <log_level>	AS_DEBUG	3 (INFO)
-worker_thread_count <count>	AS_WORKER_THREAD_COUNT	32
-rx_buffer_size <size>	AS_RX_BUFFER_SIZE	2 MB
-member_timeout	AS_MEMBER_TIMEOUT	30000
-cluster_suspend_threshold	AS_CLUSTER_SUSPEND_THRESHOLD	-1
-monitor_system <boolean>	AS_MONITOR_SYSTEM	false
-input <script_path>	AS_INPUT
-security_policy	AS_SECURITY_POLICY
-security_token	AS_SECURITY_TOKEN
-identity_password	AS_IDENTITY_PASSWORD
-authentication_domain	AS_AUTHENTICATION_DOMAIN
-authentication_username	AS_AUTHENTICATION_USERNAME
-authentication_password	AS_AUTHENTICATION_PASSWORD
-authentication_keyfile	AS_AUTHENTICATION_KEYFILE
-site_name	AS_SITE_NAME
-system_seeder	AS_SYSTEM_SEEDER

 

For the following settings, use only characters that can be used in a file or directory name, and do not use spaces:

•	Component Name

•	AS_METASPACE

•	AS_MEMBER_NAME_PREFIX

Some variables that are used internally by ActiveSpaces Enabler appear in the list of Component Runtime Context Variables. Do not add the following Runtime Context Variables to a component configuration:

•

AS_BASE

•

AS_HOME

Notice that most of the as-agent command line options map to a Runtime Context Variable of the same name, with “AS_” prepended. For example, the -metaspace command line option maps to the AS_METASPACE Runtime Context Variable. These directly mapped Runtime Context Variables are used and behave in the same way as if they were specified as as-agent command line options.

For some as-agent command line options, there is a mapping of the command line option to a Runtime Context Variable with a slightly different name. For other as-agent command line options, there are several Runtime Context Variables listed.

The following sections provide information about the use of these Runtime Context Variables.

Metaspace Member Names

With ActiveSpaces, each metaspace member must have a unique member name. Since multiple instances of an as-agent can be run by a single component configuration that uses ActiveSpaces Enabler, each component instance that is started has the following member name format:

<member_name_prefix>-<component instance number>

You can specify the member name prefix by using the AS_MEMBER_NAME_PREFIX Runtime Context Variable.

If a member_name_prefix is not specified, the name of the Component is used as the member name prefix.

When using ActiveSpaces Enabler, Silver Fabric reuses component instance numbers when component instances go down and come back up. So if four instances of a component are started, they have names in which 0 through 3 are appended to the member name prefix. If any of the instances go down and come back up, you will still have instances whose member names end in 0 through 3.

 

ActiveSpaces Enabler cannot catch member name prefixes that are not unique between components that connect to the same metaspace. If you specify a member name prefix instead of allowing ActiveSpaces Enabler to use the default member name prefix, ensure that you specify a unique member name prefix.

Depending on the scenario, it might not be possible for ActiveSpaces Enabler to provide a meaningful error to help you figure out why your component instances are failing to run.

 

When using shared-nothing persistence, directories and files are created based on the member name. So member name prefixes should only contain characters that are valid for directory and file names on the system you are running on.

Listen URL

When an as-agent is deployed from the command line, the following default listen URL is used:

tcp://<host_ip_address>:<first free TCP port beginning from port 50000>

When deploying as-agents using a TIBCO Silver Fabric Component, if a single listen URL is specified, errors are generated for each subsequent as-agent started on the same machine, because the first as-agent started usese the port specified in the listen URL and the listen port is no longer available.

For this reason, when configuring components with ActiveSpaces Enabler, specify only the beginning TCP listen port to use instead of the complete listen URL. When component instances are started, the complete listen URL is composed using the following information:

•	The host IP address of the engine on which the as-agent is started

•	A TCP port starting from the port you specify as the value for the AS_LISTEN_PORT Runtime Context Variable. If you do not specify a value for AS_LISTEN_PORT, a default value of 57000 is used.

• AS_LISTEN can be used to specify the entire listen URL. If a value for AS_LISTEN is specified, AS_LISTEN_PORT is ignored. • When running multiple components on the same machine, ensure that AS_LISTEN_PORT specifies a different range of port numbers for each component; otherwise port conflicts occurs.

Remote Listen URL

The remote listen URL is used to specify the IP address and port on which an as-agent listens for connections from remote clients. When using ActiveSpaces Enabler, the AS_REMOTE_LISTEN Runtime Context Variable is used to specify the remote listen URL. If you specify a value for AS_REMOTE_LISTEN, then that same value is used for every as-agent started using that component configuration. You could run into port conflicts if these as-agents end up running on the same machine.

When running as-agents in the cloud, you might not be able to use AS_REMOTE_LISTEN unless you use Elastic IP addresses, because you will not know ahead of time the IP address of the engine an as-agent will be started on.

Therefore, in most cases you should use the Runtime Context Variable AS_REMOTE_LISTEN_PORT instead of AS_REMOTE_LISTEN to compose the remote listen URL.

When you use AS_REMOTE_LISTEN_PORT, the remote listen URL is constructed as follows:

tcp://<engine IP address>:<AS_REMOTE_LISTEN_PORT>

For each instance of a component that is started, AS_REMOTE_LISTEN_PORT increments to prevent port conflicts. You will notice that when you add AS_REMOTE_LISTEN_PORT to your component configuration, it is set to a negative number. You must set this value to a positive port number for AS_REMOTE_LISTEN_PORT to be recognized by the enabler.

If neither AS_REMOTE_LISTEN_PORT nor AS_REMOTE_LISTEN is added to your component configuration, then a remote listen URL is not included when starting up as-agents using the component configuration.

Metaspace Discovery URL

Several runtime context variables related to specifying the metaspace discovery URL when starting as-agents in the Silver Fabric environment. By default, Pragmatic General Multicast (PGM) multicast transport is used for discovery if none of the discovery related Runtime Context Variables are configured. The default PGM discovery URL has the form:

tibpgm://<AS_DISCOVERY_PORT>/<engine IP address>;<AS_DISCOVERY_MULTICAST_ADDRESS>

where:

•	AS_DISCOVERY_PORT defaults to 52000

•	AS_DISCOVERY_MULTICAST_ADDRESS defaults to 239.8.8.8

When running in the cloud, using PGM for discovery will not work, because multicast is not supported in the cloud.

AS_DISCOVERY runtime context variable is used to configure a specific discovery URL that all as-agents started using this component configuration use. See the TIBCO ActiveSpaces Developer's Guide for more detailed information on discovery URLs.

If a component does not configure AS_DISCOVERY and another component on which it depends exports its AS_DISCOVERY setting, the exported AS_DISCOVERY setting is used by the component that did not configure its own AS_DISCOVERY setting. This scenario is likely to occur when using TCP for discovery in the cloud. See the next section for more information.

TCP Discovery in the Cloud

You must use TCP discovery when running as-agents in the cloud. A TCP discovery URL has the form:

tcp://<IP1[:port1]>;<IP2[:port2];...

When using TCP discovery for as-agents configured to run in the cloud, it is not possible to know ahead of time what the IP address of your cloud machine will be unless you use something like elastic IP addresses.

In cases where the IP address of the cloud machine is not known ahead of time, ActiveSpaces Enabler dynamically determines the TCP discovery URL in the following cases:

•	AS_DISCOVERY is not configured

•	AS_SHARED_DISCOVERY_DIR and AS_NUM_DISCOVERY_NODES are configured

AS_SHARED_DISCOVERY_DIR specifies a directory on a shared drive where each as-agent about to be started can register its listen address and port. When the number of as-agents that have registered reaches the amount specified in AS_NUM_DISCOVERY_NODES, the ActiveSpaces Enabler uses the listen addresses and ports of those as-agents to calculate and publish the discovery URL in AS_DISCOVERY Runtime Context Variable so that dependent components can use the dynamically determined discovery URL.

Use AS_TOTAL_DISCOVERY_NODES when you have multiple components in your stack and you only want a certain number of discovery nodes from each component to be used. In this case, AS_NUM_DISCOVERY_NODES is used to determine the number of as-agents from each component to use as discovery nodes, and AS_TOTAL_DISCOVERY_NODES is used to specify the total number of discovery nodes needed for the complete discovery URL.

The following configuration scenarios are useful for understanding the expected behavior of the ActiveSpaces Enabler when you configure AS_NUM_DISCOVERY_NODES and AS_TOTAL_DISCOVERY_NODES.

If a component is configured as follows:

AS_NUM_DISCOVERY_NODES = 0

AS_TOTAL_DISCOVERY_NODES = 4

then none of the as-agents started by this component are used as discovery nodes. ActiveSpaces Enabler waits until the full discovery URL has been determined by the other components in the stack before starting any as-agents using this component configuration.

If a component is configured as follows:

AS_NUM_DISCOVERY_NODES = 2

AS_TOTAL_DISCOVERY_NODES = 2

then the first two instances of this component are used to determine the discovery URL for the metaspace.

None of the other components that want to join this metaspace should set any of the discovery URL related Runtime Context Variables. AS_DISCOVERY is exported by this component and is picked up by other components in the stack for which a dependency rule on this component has been configured.

 

When configuring dependency rules, remember to clear the Shutdown dependency option. If it is selected and a discovery node goes down, any dependent component instances will also be shut down.

 

If a component is configured as follows:

AS_NUM_DISCOVERY_NODES = 2

AS_TOTAL_DISCOVERY_NODES = 4

then the first two instances of this component are used as discovery nodes. ActiveSpaces Enabler waits until the total number of discovery nodes have been registered by other components. When the total number of discovery nodes is reached, the full discovery URL can be determined and all as-agents start up using the full discovery URL.

If a component is configured as follows:

AS_NUM_DISCOVERY_NODES = 2

AS_TOTAL_DISCOVERY_NODES = 0

then the setting from AS_NUM_DISCOVERY_NODES is used for AS_TOTAL_DISCOVERY_NODES and the first two instances of this component are used to determine the discovery URL for the metaspace.

Even though ActiveSpaces Enabler dynamically determines the discovery URL when running in the cloud, if a discovery node goes down and does not come back up on the same IP address, you will lose that discovery node. If the discovery node comes back up on a different IP address, it will now be considered a member of the metaspace but not a discovery node. If you lose all of your discovery nodes, metaspace members will not be able to connect to the metaspace. If this happens, stop your stack and start it again.

 

Note the following about AS_DISCOVERY_NODE_RECOVERY_TRIES: • Use AS_DISCOVERY_NODE_RECOVERY_TRIES to designate the number of times to restart a discovery node. The default value, which is 0, designates that no discovery nodes will be restarted. • When you use AS_DISCOVERY_NODE_RECOVERY_TRIES, the enabler will restart the component instance and attempts to recover the discovery node on an engine using the same IP address as the engine the discovery node originally ran on. If the discovery node cannot be recovered, the metaspace member runs as a non-discovery node. However, if the discovery node restarts on an engine with a different IP address, it starts as a non-discovery node member of the metaspace.

The runtime context variables AS_FIND_DISCOVERY_MAX and AS_FIND_DISCOVERY_WAIT are used to control how long to wait for the discovery URL to be determined. AS_FIND_DISCOVERY_MAX is the number of times the enabler loops looking for the total number of discovery nodes to have registered themselves. AS_FIND_DISCOVERY_WAIT is the number of seconds the enabler waits before looking again for all of the discovery nodes.

If you are running your components on different machines and some machines run faster than others, you might need to increase AS_FIND_DISCOVERY_WAIT or AS_FIND_DISCOVERY_MAX to increase the amount of time allowed for determining the discovery URL.

Cross-site Replication

Cross-site replication is used to dynamically backup changes to the data in your metaspace to another metaspace in a different geographical location.

The runtime context variable AS_SITE_NAME can be used to specify the ActiveSpaces site name. You can pass an argument -site_name <string> to the as-agent.

The runtime context variable AS_SYSTEM_SEEDER is a setting, that allows you to set if the as-agent seeds any internal system spaces.You can add the variable AS_SYSTEM_SEEDER to component, and configure its value. If you set its value to False, the non-leach as-agents do not seed the cross-site related system spaces.

You can refer TIBCO ActiveSpaces® Administration for more details.

Security

You cannot use ActiveSpaces enabler to deploy as-agents that use security in the cloud, unless you use static IP addresses. These IP addresses are similar to those provided with Amazon's Elastic IP addresses.

ActiveSpaces requires the use of TCP discovery to apply security to metaspaces. The Metaspace Access List in the security policy and token files requires the metaspace name and full discovery URL. So the discovery URL must be known in advance and cannot be dynamically determined at runtime as described in TCP Discovery in the Cloud.

AS_SECURITY_POLICY specifies the full path to the security policy file. This file needs to be accessible to each as-agent being started as a security domain controller for the metaspace. If a single component configuration is being used to start multiple as-agents which will act as security domain controllers running on different machines, a shared drive should be used to store the security policy file so that all instances of as-agents being deployed will have access to the security policy file as configured in the AS_SECURITY_POLICY configuration setting.

At least one security domain controller must be a discovery node so that security can be provided as other members try to join the metaspace.

The security policy file can be uploaded to component as a content file. For more details refer Security Runtime Context Variable.

AS_IDENTITY_PASSWORD specifies the policy's security domain's identity password if the identity is encrypted.

For component configured as security domain requester, set below security runtime context variables:

• AS_SECURITY_TOKEN

• AS_IDENTITY_PASSWORD

When you are using static discovery URL for the security domain controller component, you must update the discovery URL in the policy file manually.

At least one security domain controller must be a discovery node so that security can be provided as other members try to join the metaspace.

AS_SECURITY_TOKEN specifies the full path to the security token file. This must be accessible to each as-agent being started as a security domain requester for the metaspace. If a single component configuration is being used to start multiple as-agents which are security domain requesters running on different machines, a shared drive should be used to store the security token file. Then all instances of as-agents that are deployed, have access to the security token file as configured in the AS_SECURITY_TOKEN configuration setting. The security token file can be uploaded to component as a content file. For more details refer Security Runtime Context Variable.

AS_IDENTITY_PASSWORD specifies the policy's security domain's or the token's identity password if the identity is encrypted. When security domain controller is using user authentication, add below security runtime context variables to security domain requester component:

• AS_AUTHENTICATION_DOMAIN

• AS_AUTHENTICATION_USERNAME

• AS_AUTHENTICATION_PASSWORD

AS_AUTHENTICATION_DOMAIN specifies the name of the windows domain to log into. If local/ntlm account (as per the controller), “.” can be used. If not windows, it is ignored.

AS_AUTHENTICATION_USERNAME specifies the authentication username of the user account to be logged in as.

AS_AUTHENTICATION_PASSWORD specifies the authentication password of the user account to be logged in as or password for user account.

When security domain controller is using certificate authentication, add below security runtime context variables to security domain requester component:

• AS_AUTHENTICATION_KEYFILE

• AS_AUTHENTICATION_PASSWORD

AS_AUTHENTICATION_KEYFILE specifies the pkcs12 keyfile location of the user to be logged in as (sasl/external x509 ldap auth). The key file can be uploaded to component as a content file. For more details refer Security Runtime Context Variable.

AS_AUTHENTICATION_PASSWORD specifies the password of the pkcs12 key file.

By default, identity passwords and authentication passwords are visible in the engine log as part of the command to start up the as-agent. You should always use safe passwords when configuring your components. Safe passwords can be generated using the as-admin 'create safe_password' command. For more details refer TIBCO ActiveSpaces ® Administration Guide. To prevent the display of the command used to start up the as-agent in the engine logs, add the runtime context variable SHOW_PROCESS_COMMAND to your component configuration and set its value to false.

Figure 9 Security Runtime Context Variable

Uploading Content Files for Security

The security policy, token file and authentication key file can be uploaded and deployed with component. To upload the files and to set the runtime context variables perform the following steps:

1.	Set the value of AS_SECURITY_POLICY, AS_SECURITY_TOKEN and AS_IDENTIFICATION_KEYFILE as:

$CONTAINER_WORK_DIR/<RELATIVE_PATH>/<FILE_NAME>

Where,

$CONTAINER_WORK_DIR is a runtime context variable defined in ActiveSpaces enabler for work directory. Its default value is DSEngine/work/<hostname>-<instance>/fabric.

<RELATIVE_PATH> is the relative path that is set when uploading content file to the component.

2.	Navigate to the Add/override/customize Enabler and Component-specific content files page in the component creation wizard, click Upload.

3.	Specify a string in the Relative Path field, and upload the file. If the Name field is kept blank, then the default file name is used.

Figure 10 Uploading Component Specific Certificate File

 

Figure 11 Uploading Component Specific Policy File

 

Figure 12 Uploading Component Specific Token File

 

Figure 13 Uploading Component Specific Key File

Restricting Transport Access

Using TIBCO ActiveSpaces security, you can restrict transport connections within a security domain to only “trusted” nodes. The full path of trusted certificate file set in the security policy file must be accessible to each as-agent being started as a security domain controller for the metaspace. The trusted certificate file can be located in a shared drive or can be uploaded to the component.

To configure the restricted transport access and to upload the trusted certificate file to component:

1.	Open the security policy file for the domain in a text editor.

2.	Edit the line that reads transport_access=false;cert_file=

as

transport_access=true;cert_file=%CONTAINER_WORK_DIR%/<RELATIVE_PAT

H>/<TRUSTED_CERTS_FILE_NAME>

Where,

%CONTAINER_WORK_DIR% is the placeholder container work directory for substitution

<RELATIVE_PATH> is the relative path set when uploading the trusted certificates file.

<TRUSTED_CERTS_FILE_NAME> is the name of the trusted certificates file.

3.	Upload the security policy file and trusted certificates file to Silver Fabric while creating the component.

4.	In the Edit the Configuration File wizard page, add container configuration

script shown as below:

<containerConfig>

<configFiles baseDir="${CONTAINER_WORK_DIR}/<RELATIVE_PATH>"

include="<SECURITY_POLICY_FILE_NAME>">

<regex pattern="%CONTAINER_WORK_DIR%"

replacement="${CONTAINER_WORK_DIR}"/>

</configFiles>

</containerConfig>

This script finds the security policy file from basiDir and substitutes the placeholder with the actual value.

Where,

<RELATIVE_PATH> is the relative path that is set when uploading the security policy file to component.

<SECURITY_POLICY_FILE_NAME> is the name of the security policy file uploaded to component.

Figure 14 Edit Configuration File

Alternative Memory Manager for Linux 64-bit

The Hoard memory manager is offered for the Linux 64-bit platform as an alternative to the operating system's native memory manager for use with ActiveSpaces. Using Hoard over the native manager can reduce memory fragmentation. Detailed information about Hoard can be found at http://.hoard.org

A runtime context variable AS_HOARD_SUPPORT is added to the TIBCO Silver Fabric Enabler for ActiveSpaces.

You can use the Add from Enabler button on the Component Wizard and select AS_HOARD_SUPPORT from the enabler specific context variable drop-down list. Click OK for the Hoard support.

By default, the hoard support is not provided and it will be OFF. To enable the usage of hoard, set the value to ON by adding AS_HOARD_SUPPORT variable from enabler, and updating its value to ON.

Figure 15 Hoard Support Runtime Context Variable