Configuring Unravel

This section provides the list of Directories and files that are comprised in an Unravel installation and the step-by-step instructions to do the following:

Whenever you install, upgrade, or change configurations, all the definition files are merged and the changes are applied.

Directories and files
Changing Unravel directories

All the Unravel configurations are located in the data directory. By default, the installer maintains the data directory under <Unravel installation directory>/data. However, if you want to provide a different directory for data, you can run the setup command as follows:

setup --data-directory /the/data/directory

This will configure unravel with all the components in the Unravel installation directory except for the data directory, which will be the directory from the location that you have provided.

Similarly, you can configure separate directories for all the Unravel directories such as run, tmp, services, and so on by providing a configuration file.

Managing Unravel configurations and services with manager tool

Unravel manager is a tool that provides a unified command-line method to manage all the Unravel configurations and services. It is the central point for interacting with Unravel on the command-line. After you have installed Unravel, the manager tool is available in the services and base directory as manager. You can use the manager tool for the following purposes:

  • Manage services

  • Upgrades and downgrades

  • Setting configurations and properties

  • Integrate all command-line tools such as healthcheck, autoconfig, AppStore apps, installation, and so on.

Whenever you configure any of the settings from the manager tool ensure to stop the manager,

The commands in the manager tool follows the verb-noun pattern.

  • All: Affects all services. For example, the stop all stops all the services while keeping the monitor up.

  • Alias

    • Informal names: stop unravel_sersor_1 or stop us_1 or stop us are equivalent .

    • Group services: stop ma will stop ma_1, ma_2, ma_3. stop etl will stop all ETL related services.

  • tier:n: To group services per dependency, ex: tier:2 depends on services from tier:1

  • CSL: A comma-separated list of services, aliases, etc. For example,  stop tier:4,ew,ngui stops all tier:4 services, all ew services, and the UI service.

Commands can also be chained. However, if any of the commands fail, the chain stops. For example, if you run the chained command: manager stop config auto refresh files start watch, it triggers the following actions:

  • Stops Unravel

  • Runs autoconfig in automatic mode.

  • Refreshes all scripts and configuration files

  • Starts Unravel

  • Displays the service watch.

Updating any setting from the manager tool
  1. Stop Unravel.

    manager stop
  2. Run the command to edit the configuration or service. For example, manager config.

  3. Refresh the files.

    manager refresh files
  4. Start Unravel.

    manager start

See Manager tool command reference

Editing Unravel properties

Use any of the following methods to edit the Unravel properties.

  • Automatic configuration

    Run manager config auto command to automatically pull in all the Hadoop configurations. You will be prompted to provide the location and credentials for Cloudera Manager or Ambari UI.

  • Manual configuration

    The manager config command is used to manually configure the properties from the configuration UI. To configure the properties manually:

    1. Stop Unravel

      manager stop
    2. From the installation directory, set individual properties manually, run manager config properties set KEY VALUES. For example:

      <Unravel installation directory>/manager config properties set com.unraveldata.client.rest.ssl.enabled true
    3. Refresh the files.

      manager refresh files
    4. Start Unravel

      manager start

Refer to Unravel properties for the list of Unravel properties.

Configuring custom ports

You can configure Unravel to use custom ports instead of the default ports. This configuration can be set from the Unravel manager tool. Run the manager help config ports command to view the help for config ports.

To configure custom ports, do the following:

  1. Stop Unravel.

    manager stop
  2. Display the list of ports and keys

    manager config ports show
  3. Set the port using the following command with the port and port key.

    manager config ports set <port key> <port>

    For example, if you run the following command NGUI listens on port 1234.

    manager config ports set hosts/host_main/instances/ngui_1/config/port 1234


    • Run manager config ports unset command to return the ports to its default values.

    • Run manager config ports remap to remap all the ports within a range.

      manager config ports remap begin<specify start range> end<specify end range>

      For example, if you run the following command all the ports get remapped between 5000 and 6000

      manager config ports remap 5000 6000
  4. Refresh the files.

    manager refresh files
  5. Start Unravel.

    manager start

See Manager tool command reference

Archiving services and configurations

The manager creates a backup of services and configurations in <Unravel installation directory>/data/conf_archives. In case you have lost any changes in the script or configurations, you can always look up in archives and recover the lost changes. Moreover, you can manually archive the configurations and services by running the following command:

<Unravel installation directory>/services/manager config archive
Manager tool commands reference

You can refer to this section for the manager tool commands:

Main actions

The table shows the main actions that are displayed when you run the manager tool. You can run any of these actions for setting up services and configurations.




Start Unravel.


Stop Unravel.


Restart Unravel


Report Unravel services.


Report Unravel services. Refreshes every two seconds.


Additional service management commands.


Configure Unravel


Refresh scripts and configurations.


Activate an Unravel version.


Unravel version information.


Verify that system configuration supports the currently running Unravel.


Verify the health of an Unravel installation.


Run Unravel scripts


Unravel API tools

Configuration commands




config unravel

Starts the autoconfig UI.

config auto

Starts autoconfig, which is the automatic mode.

URL, username, and password will be prompted, unless --cm-URL, --cm-username and --cm-password are passed.

config notebook

Configures and enables Jupyter notebook service.

config emdb enable

Configure unravel to use EMDB.

config archive

Archives the content of data/conf and services into a tar file and stored in data/conf_archives.

refresh <entity>

Refreshes the specified entity. Entity can be any of the following:

  • all

  • files

  • kafka

  • db

  • es


You must stop Unravel before you run refresh <entity>.

email configurations



config email

Configure email.

Installation and Upgrade commands




Shows the unravel version and components information.

verify <sensor|properties|files>

  • Sensor: Checks the cluster configuration and ensures that the sensor parameters are correct.

  • properties: Validates unravel.properties, checking for invalid, unknown, duplicate properties.

  • files: Verifies and reports on any unexpected changes to unravel components, scripts, and configuration.


Displays a list of available versions of Unravel for activation. This applies for upgrades, downgrades, and patches. The manager tool verifies the compatibility before making any changes.

activate <version>

Activates a specific version of unravel.


Uninstalls Unravel.

Custom ports configurations



help config ports

Open the config ports menu.

config ports show

Display currently defined port values.

config ports unset

Returns a custom port value to it's default value.

config ports uset

manager config ports remap begin<specify start range> end<specify end range>

Set range for Unravel ports.

Kerberos configurations



config kerberos enable|disable

Enable/disable the Kerberos support for Unravel. This requires regenerating files.

config kerberos set

Allows setting the Kerberos principal path to keytab and optional path to a custom krb5.conf

Also, refer to Changing Kerberos tokens or principal and Creating Active Directory Kerberos principals and keytabs for Unravel

Monitoring commands




Shows the status of all unravel services.

report <service>

Shows the status of the specified service.


Shows the status of all unravel services.

watch <service>

Shows the status of the specified service.

service list

Display detailed status information about the service.

service is-enabled <service>

Shows whether the service is enabled.

service is-running <service>

Shows whether the service is running.

service is-alive <service>

Shows whether the service is alive.


To run healthcheck.

Service management commands




Starts unravel and all the enabled services.

start <service>

Only starts the specified service.


Stops unravel and all the running services.

stop <service>

Stops only the specified service.


Run kill -9 to terminate all processes.


Restart all services.

restart <service>

Restart only a specific service.

service enable <service>

Temporarily enables a service, update unravel.yaml.

service disable

Permanently disables a service.

Security (TLS) configurations



config tls trust enable|disable

Enable or disable Unravel using a truststore to use when connecting to services secured with TLS. This requires regenerating files.

config tls trust add <path>

config tls trust --jks <path>

config tls trust --pem <path>

config tls trust --pkcs12 <path>

Imports certificates to trust. For example, autodetect format based on the extension.

Supported <format> are:

  • PEM

  • PKCS12

  • JKS

<path> is the path to the file to import.

config tls enable|disable

Enable/disable using a TLS for Unravel. This requires regenerating files.

config tls set <path>

config tls set --jks <path>

config tls set --pem <path>

config tls set --pkcs12 <path>

Set the certificate and key to use for TLS. First example autodetect format based on the extension.

Supported <format> are:

  • PEM

  • PKCS12

  • JKS

For PKCS12 and JKS, the user will be prompted for the password. <path> is the path to the file to import.

Tagging configurations



config tagging enable|disable

Enable/disable tagging support for UnravelThis requires regenerating files.

config tagging set

Allows setting the script and the method for tagging.

Other tool configurations



run <script>

Runs the Unravel scripts such as db_access.sh.

Customizing configurations

For advanced configurations of Unravel installation, contact Unravel Support.