Author: Matt Pilcicki
Basic runtimes, runtime cluster, and runtime clouds are all quite configurable. Not only are there a multitude of settings for the runtime engine itself, but the Java Virtual Machines they run in are also configurable. There are multiple places to configure the same settings and it can sometimes get confusing about what are the "right" ways to configure runtimes. This article will provide some clarity and best practices concerning runtime properties.
The following are some of the types of properties concerning configuring parts of the runtime. Account Properties are only applicable to runtime clouds. Forked Execution Properties are only applicable to runtime clusters and runtime clouds. runtime cloud Attachments will be missing many of these menus as they are set from the cloud parent. These properties are not to be confused with things like Process Properties or Dynamic Process Properties which apply to processes but can be persisted and configured in runtime Management Deployed Processes for use by the process it is associated with. Though this article specifically outlines properties and methods found in runtime Management and File Systems for dealing with basic runtimes, runtime cluster, and Clouds, some of these properties and strategies may also be applicable to API Gateway runtimes available through API Management. See our documentation on API Gateway Settings here: https://help.boomi.com/bundle/api_management/page/api-API_Gateway_settings.html
The guidance in this article will at first follow the menus in runtime Management under Settings and Configuration. First explaining the meaning of these menus, then information on how to set these properties.
The Properties tab is available for all runtimes aside from runtime cloud Attachments. These are the main configuration pages for runtimes. Here you will set properties which are mostly contained with in the following directories:
<runtime dir>/bin/atom.vmoptions
and
<runtime dir>/conf/container.properties
Basic Properties are just a few properties for initial configuration of your runtime. Here you can set some items like name and host name, options for how long data on your runtime must remain before being purged from disk, how long the runtime or its nodes will wait for a process before force restarting, how much heap a runtime or each of its nodes uses, override the machine default file encoding, and set a temporary directory. Documentation for these items can be found here: https://help.boomi.com/bundle/integration/page/r-atm-Properties_panel_Basic_tab.html
Advanced Properties are where you can really get into customizing the configuration of your runtime. This area is the GUI where you will be able to customize many aspects of your runtime including how it runs, if JMX is exposed to outside traffic, Node Configuration for runtime clusters and runtime clouds, options for Forked JVMs, Networking options, runtime Orchestration, Purge Options, Execution Quotas, Java Options, and much more.
To add a property here, find your property from the drop down menu, select it, then click "Add a Property". The property will now appear in the list of properties below the drop down. Assign a value to the property. When you are done adding and configuring, be sure to click save at the bottom of the screen. This will now ask if you would like to restart the runtime to apply the properties. You can decide whether you would like to manually restart later or not. Most, but not all, properties require you to restart the runtime for changes to take affect. This is because the JVM needs to apply these properties at initialization.
You can find more information on Advanced Properties in our documentation. Here you will find a description of the property, the format for entering the property(text, checkbox, etc.), the default of the property, and the full text of the property as it will appear in configuration files(ex. com.boomi.runtime.accountsDirs or -Dsun.net.client.defaultConnectTimeout): https://help.boomi.com/bundle/integration/page/r-atm-Properties_panel_Advanced_tab.html
The Custom Properties section is where you are allowed to specify properties which you are not able to set through any other GUI section for the runtime. These will be stored in one of two file locations and will typically require a restart to take affect. In some cases there are even some properties which will not be allowed to be set via the UI even in Customer Properties. For information on these properties, see the section on Restricted Properties. Documentation for the Custom Properties tab can be found here: https://help.boomi.com/bundle/integration/page/r-atm-Properties_panel_Custom_tab.html
System Settings are settings that will apply to the JVM and what arguments it spins up with. Most settings here are specific to Java or libraries used by Java and would be found in the documentation for Java and certain libraries or applications. Some system settings can be set through Advanced and Basic Properties, however, many are not included, this sections gives a way to add these properties through the GUI. Most of the properties will start with -D, -X, or -XX. Information on System Properties with Java can be found at this link: https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html. We will not attempt to explain all Java System Properties, as aside from those mentioned in the documentation, there are even more which may be specific to a certain library or application which are not documented by Oracle. Typically you will be made aware of certain application specific Properties during research into an issue you are troubleshooting, such as the need to set a timeout for a certain connection protocol.
These properties will be stored in:
<runtime dir>/bin/atom.vmoptions
When it comes to runtime Properties, some properties may not be documented but their use suggested by Boomi Support to resolve an issue. Otherwise this section may generally go unused. runtime Properties generally start with com.boomi for example com.boomi.container.accountsDirs. These properties will be stored in:
<runtime dir>/conf/container.properties
Account Properties are visible only for Clouds and their Attachments. You will not see this on runtime clusters or basic runtimes. Basic and Advanced properties are stored in an Account Properties file within a directory on the Cloud that is specific to that account. The Cloud Attachment Quotas are stored in a limits directory of the Cloud. These properties are specific ONLY to the attachment of the Cloud you are viewing. These will not affect any other users of the same Cloud. Documentation for these properties can be found here: https://help.boomi.com/bundle/integration/page/r-atm-Account_Properties_panel.html
Here you are able to set a few basic properties, Cloud Name and a few purge options.
Advanced contains a few more options of properties which you can set for your attachment only. Most of these properties have to do with purge settings and when certain, more granular, account items are purged. These individual settings will override the property set in the basic tab, which will set all purge properties to the same if not overridden. One other property to note is the Low Latency Warning Threshold, which can be used to display processes which were successful but ran longer than expected. This can be useful to detect trouble before processes start running long enough to fail and is usually indicative of an issue with the runtime.
Cloud Attachment Quotas can be used to view a whole bunch of settings for your Cloud Attachment. You cannot edit these properties from this screen, even if you are the Cloud owner, these Properties are edited from the Cloud Management screen of the owner account. If your account is not the owner of the Cloud, you will not be able to edit these at all and will need to request the Cloud owner edit them for you. Information of these properties can be found here: https://help.boomi.com/bundle/integration/page/r-atm-Attachment_Quotas_tab.html. A few commonly used properties are below:
Execution worker Warmup Enabled - Allows new execution workers to spinup before the only execution workers retire, this avoids any downtime
Execution workers - Sets maximum number of execution workers available to your Account Attachment
Minimum execution workers - Sets a minimum number of execution workers that must be running for your attachment at any given time
Default HTTP Workload - Can change what mode some Listener Processes will run in as well as where they will run(execution worker vs Forked Execution)
Some of these properties will require a restart of the cloud when changed.
Forked Execution Properties are only available in runtime clusters and Clouds and will only make a difference if that runtime is setup for Forked Executions. To know if a Cloud or runtime cluster is setup for forked executions, consult the runtime's Advanced Properties. Find the property Execute Processes as Forked JVMs. If this property is set to MULTI_PROCESS, it is running Forked Executions. If the property is MULTI_THREAD, it is not running Forked Execution. If you do not see the property at all, the runtime is using the default value. Clouds default to using Forked Executions, runtime clusters do not. For more information on how to set this property, see: https://help.boomi.com/bundle/integration/page/t-atm-Enabling_or_disabling_forked_execution_in_a_runtime cluster.html.
Forked Execution Properties will apply to ALL Forked Executions, not just a single account attachment. These properties are stored in a corresponding vmoptions file which is prepended with either procrunner, procworker, or procbrowser. The file is then combined with a template Bash or Powershell script which creates the final Bash or Powershell script that will use the properties when spinning up one of these JVMs. Given the way in which the scripts are created, editing the file directly on the File System will do nothing without hitting Save in the Boomi Platform after loading the screen and seeing the new properties. The Properties populated in the Platform come from the corresponding vmoptions file, so if you have changed the file directly on the File System, the Properties shown in the Platform could be out of sync with reality, ultimately, the current version of the corresponding Bash or Powershell script contain the Properties which will be used at spinup of that JVM. Documentation on Forked Execution Properties can be found here: https://help.boomi.com/bundle/integration/page/t-atm-Setting_forked_execution_properties_for_a_runtime cluster.html The location of this file is below:
<runtime dir>/bin/proc<type>.vmoptions
Here we are able to set Heap sizes for each of the different Forked JVMs a Multi-Process runtime can run. Runner Heap will cover Forked Executions which are not running in Workers. Worker Heap Size will apply to execution workers. Browser Heap Size will apply to JVMs for Browser operations, such as testing a connection or importing an operation in the Build tab using that Cloud.
The Advanced Properties Screen allows setting a few more vmoptions specific to Forked Executions.
Similar to other Custom Properties, you can set other properties you are not able to anywhere else in the GUI. These will still only be stored in a vmoptions file, there is not an option to specify runtime Properties.
This panel is used to set properties having to do with the Shared Web Server. These properties will not appear in the file until one is overridden in the Platform or manually added. These Properties are stored in various files but also involve to Platform, therefore, it is not a good idea to try and set these through the File System. Setting in the Platform will also allow the changes to take affect after restarting only the plugin, whereas setting on the File System may or may not take affect after only a full Runtime Restart depending on the property. Updating these Properties in the File System will also not reflect as changed in the GUI and will cause things the Platform display to be out of sync with the actual Properties. User Management should also all be done through the Platform. Documentation for all three panels can be found here: https://help.boomi.com/bundle/integration/page/r-atm-Shared_Web_Server_panel.html
Here we are able to set many properties around networking and authentication for the runtime Shared Web Server.
User Management will only be visible when using API Type of Intermediate or Advanced. This screen is used to configure users for your Shared Web Server. Here you will be able to get a username and token to use as well as control access based on Listener Process as well as Incoming IP Address.
CORS Configuration will only be available when using an API Type of Advanced. More information on CORS Configuration can be found in our documentation mentioned above, as well as our Community at: https://community.boomi.com/s/article/Setting-up-CORS-for-API-component-interaction
This tab is used just to set the MLLP Port for your MLLP Server, which listens for inbound HL7 Documents. Documentation for this panel can be found here: https://help.boomi.com/bundle/integration/page/r-atm-MLLP_Server_Settings_panel.html
This Panel can be used to set several properties pertaining to the Native basic runtime Queue. These properties are runtime properties and as such are stored in the following file:
<runtime dir>/conf/container.properties
These properties will not appear in the file until one is overridden in the Platform. These Properties also involve the Platform, therefore, it is not a good idea to try and set these through the File System. Setting in the Platform will also allow the changes to take affect after restarting only the plugin, whereas setting on the File System may or may not take affect after only a full Runtime Restart depending on the property. Updating these Properties in the File System will also not reflect as changed in the GUI and will cause things the Platform display to be out of sync with the actual Properties. Documentation for these settings can be found here: https://help.boomi.com/bundle/integration/page/t-atm-Configuring_the_Shared_Queue_Server.html
Counters are persisted increments used within processes. These are used with EDI documents for certain control numbers, as well as with the Parameter Value type of Sequential Value. These are persisted on the File System and as such can be altered from runtime Management . Use the counters screen to view and alter these values. Remember that these counters can be incremented by processes run in test mode and deployed mode. It is best not to use counters in processes which are allowed to run more than one at one time, especially on multi-node Runtimes, this can lock up the file and cause huge performance issues. The files for these counters live in the following directories:
Basic runtimes and runtime clusters:
<runtime dir>/counter
Clouds:
<runtime dir>/accounts/<corresponding account dir>/counter
Trading Partner counter names are made up of your business trading partner component Id, your trading partner's component Id both without dashes, and the extension is the control number for that incremented value. Counter Documentation for the Counter Panel can be found here: https://help.boomi.com/bundle/integration/page/r-atm-Counters_panel.html
As you have probably gathered from above, there are multiple ways to set many of the properties for configuration of your runtime. The sections below outline methods available for use in setting runtime properties.
This is the most comprehensive, supported way to set Runtime properties. This would also be the preferred way to set properties in most scenarios. In some cases, this is the only way to correctly set certain properties. The content above in all sections is linked to documentation for those respective settings for the UI. Typically when you set a Property in the Platform, it will send a message to the Runtime indicating the Properties that have been updated and the Runtime will then save it to the respective files. When viewing the properties in the Platform, the Platform will request the Runtime to send information on the properties stored on the File System, and will load those values in the UI. In some cases, like with Shared Web Server Settings, the property value is stored on the Runtime and the Platform as well and so the property might not be loaded from the files of the Runtime.
This is the most comprehensive, supported way to set runtime properties. This would also be the preferred way to set properties in most scenarios. In some cases, this is the only way to correctly set certain properties. The content above in all sections is linked to documentation for those respective settings for the UI. Typically when you set a Property in the Platform, it will send a message to the runtime indicating the Properties that have been updated and the runtime will then save it to the respective files. When viewing the properties in the Platform, the Platform will request the runtime to send information on the properties stored on the File System, and will load those values in the UI. In some cases, like with Shared Web Server Settings, the property value is stored on the runtime and the Platform as well and so the property might not be loaded from the files of the runtime.
Almost all properties which can be set in the UI can be set or changed on the File System. The exception being those noted in the content above, which involve Platform storage as well. This is not the preferred way of setting these properties, however, there are a few reasons it would be necessary.
1. Your runtime has lost communication to the Platform or will not start, and a property change will fix it. In this case, there is no way for the Platform to tell the runtime to take changes. In order to get the runtime working properly, you would want to change the property in the file and then restart or start the runtime. Sometimes misconfiguring settings (such as adding JMX password requirements without a password file) from the UI and restarting the runtime only to have it not appear online can cause an issue like this, you would not be able to fix it from the Platform.
2. You have automated deployment of your runtime and would like it to have certain settings present when the install automation is complete. In this case, you would want to use the files to set their appropriate values, as automating through the Platform would not be feasible(would require a lot of work with Selenium!)
3. The last scenario will be included in the next section, Restricted Properties
Remember that like the Platform, setting these settings on the File System will likely require a restart of the runtime.
Restricted Properties
There is a list of Properties which are not able to be set via Custom Properties. Trying to set them through the GUI will result in a message which says "You are not allowed to set this property." and trying to save this property will fail. In most cases, these properties are able to be set through the UI elsewhere in Boomi Enterprise Platform, such as most Shared Web Server and Queue Properties. Some, however, cannot be set elsewhere in the UI and therefore cannot be set in the UI at all. In this case, you have no choice but to set these properties on the File System in the container.properties file. A list of a few common properties which may need to be set through the file are below:
com.boomi.container.sharedServer.http.ssl.excludedProtocols
com.boomi.container.sharedServer.http.ssl.includedProtocols
com.boomi.container.sharedServer.http.ssl.excludedCipherSuites
com.boomi.container.sharedServer.http.ssl.includedCipherSuites
You may notice from time to time that certain System Properties, especially those pertaining to security, are not affecting change on your JVM after a restart. In this case you may be able to try setting these settings in the JRE or JDK that your runtime is using to run. Java has a security file which allows setting or changing of some settings, many having to do with what algorithms or keys will be used in connections that are made from that JVM. Security Files can be found at the following locations:
Java 11
<jdkDir>/conf/java.security
Java 8
<jdkDir>/jre/lib/security/java.security
Some documentation on Java security can be found here: https://docs.oracle.com/en/java/javase/11/security/java-security-overview.html#GUID-2EF91196-D468-4D0F-8FDC-DA2BEA165D10 for Java 11 and https://docs.oracle.com/javase/8/docs/technotes/guides/security/overview/jsoverview.html for Java 8
Written by Matt Pilcicki
Matt is a Senior Community Software Engineer. Matt has held many positions at Boomi from Support to Research and Development and enjoys learning as much as he can about Boomi and the services and technologies with which it interacts!