Configure an orchestrator

It’s likely you may never need to modify the default orchestrator configuration, but if you are advised to do so, or if you need to make configuration changes to accommodate custom SSL rules or proxies, this article provides a list of all available configuration options for the orchestrator.

Configuration options

All configuration options for the orchestrator are driven by a series of environment variables that are injected into the orchestrator’s running process by systemd, as specified in the .conf file located here: /opt/rapid7/orchestrator/etc/

• KOMAND_API_URL is the region-specific route for the orchestrator to speak to the Insight Platform. This should never be changed.
• KOMAND_EXEC_DBPATH is the default location on disk where some local storage of non-sensitive data occurs. This likely need not be changed.
• KOMAND_TRIGGER_RESPONSE_URL is a URL the orchestrator opens for local traffic only in order to receive responses from plugins configured to run as asynchronous triggers. This should never be changed.
• KOMAND_PLUGIN_REGISTRY_URL is the region-specific URL from which the orchestrator pulls down plugin images. This should never be changed.
• KOMAND_CA_CERT_MIRROR_ENABLED controls whether or not the orchestrator attempts to copy certain SSL certificates or authorities into the plugin containers in order to work with specialized SSL network configurations. If you’re not aware of any special SSL certificate or proxy configurations on your network, don’t change this setting. For more information on using this feature correctly, check out our Install private CA certificates article.
• KOMAND_CA_CERT_MIRROR_DIR is used in tandem with KOMAND_CA_CERT_MIRROR_ENABLED. This is the directory where your special certificate bundle lives in order to be copied into the plugins. If you’re not aware of any special SSL certificate or proxy configurations on your network, don’t change this setting. For more information on using this feature correctly, check out our Install private CA certificates article.
• KOMAND_DEBUG_LOGS enables debug logging for additional troubleshooting. This only needs to be changed if you’re experiencing issues and a support representative asks you to in order to further troubleshoot an issue.
• ORCHESTRATOR_STORAGE_STATS_ENABLED allows a richer amount of health data about the local disk to be captured and reported to the Insight Platform to enable better tracking of orchestrator health over time. We recommend you leave this enabled because it helps us understand any problems that may arise
• ORCHESTRATOR_ROLL_QUEUE enables a more advanced method of cleaning up the local disk of old data that is no longer needed. We recommend you always leave this enabled.
• HTTP_PROXY is the standard environment variable for http proxy environments. However, it must always be explicitly set in the orchestrator’s configuration file, or else the means by which the orchestrator is run will not natively ingest it from the existing OS environment. We recommend you only set this if you know you need to. See Configure Proxies documentation for more details.
• HTTPS_PROXY is the standard environment variable for https proxy environments. However, it must always be explicitly set in the orchestrator’s configuration file, because it’s not natively detected from the host operating system’s environment. We recommend you only set this if you know you need to. See Configure Proxies documentation for more details.
• NO_PROXY is the standard environment variable for bypassing proxies in proxy environments. However, it must always be explicitly set in the orchestrator’s configuration file, because it’s not natively detected from the host operating system’s environment. We recommend you only set this if you know you need to. See Configure Proxies documentation for more details.

Orchestrator files

This list of files used by the orchestrator may also help if you’re trying to perform a custom configuration, or if you need to debug an orchestrator issue.

• /opt/rapid7/orchestrator/var/enrollment
  • BoltDB File
  • This file contains the primary copy of the enrollment data used by the system.
• /opt/rapid7/orchestrator/etc/enrollment_text
  • Raw File
  • This file contains a backup copy of the enrollment data in order to make it easier to find.
• /opt/rapid7/orchestrator/var/keypair
  • BoltDB File
  • This file contains the public and private key pairs for managing encrypted credentials and request signatures.
• /opt/rapid7/orchestrator/etc/executor.conf
  • Raw File
  • This file is used by systemd to inject environment variables into the orchestrator to configure it.
• /opt/rapid7/orchestrator/var/cache/plugins/*
  • Directory Structure
  • Plugins can optionally reserve a directory under this file to do local caching of non-important data during some requests.
• /opt/rapid7/orchestrator/var/executordb
  • BoltDB File
  • Used by the orchestrator to hold in-flight message data, either from the cloud coming in, or a plugin result going out, until it can be acknowledged by the other system. In other words, this is a local cache of data to attempt to prevent data loss in the event of shutdowns or crashes. The file can tend to get large under heavily trafficked orchestrators, however, restarting the orchestrator shrinks the file each time.
• /opt/rapid7/orchestrator/etc/restartable-triggers
  • BoltDB File
  • This file contains a list of trigger configurations so that the current state of your activated workflow triggers is represented on the orchestrator so that it can know how to restart them if anything happens while they’re running.
• /opt/rapid7/orchestrator/etc/ trigger-statistics
  • BoltDB File
  • This contains some best-effort usage statistics on how often triggers are used. Some of this information may be sent to the cloud for internal statistics as well, but the data is not load-bearing for the operation of the orchestrator.
• /opt/rapid7/orchestrator/bolt-log
  • BoltDB File
  • This contains a copy of some internal log data.