# Configuration Reference This is the reference for the central config `/data/config.yaml` > **File location:** The container mounts `/data` as a writable volume.\ > **Hot-reload:** The Agent polls the file every tick; valid changes are applied automatically.\ > **UI Terminology:** In the Management Console UI, `protocolConverter:` is shown as "Bridges" and `dataFlow:` is shown as "Stand-alone Flows" ## YAML vs UI: Choose Your Workflow UMH Core supports both **direct YAML editing** and **Management Console UI** for configuration. Each approach has distinct advantages: ### YAML Configuration Benefits * **Version Control**: Every change is tracked with Git — see who changed what, when, and why * **GitOps Integration**: Automate deployments, rollbacks, and multi-environment promotion * **AI/LLM Integration**: Tools like Cursor and ChatGPT can generate, modify, and optimize configurations * **Templating Power**: Create and connect hundreds of machines with a few keystrokes using YAML anchors * **IDE Support**: Syntax highlighting, validation, autocomplete, and refactoring tools ### UI Configuration Benefits * **Zero Code**: Any OT person or business user can click and configure without YAML knowledge * **Input Validation**: Real-time validation prevents configuration errors before deployment * **Visual Guidance**: Wizards and forms guide users through complex protocol configurations * **Live Preview**: See the impact of changes before applying them ### The Best of Both Worlds **UMH Core provides two-way synchronization:** changes made in the UI are reflected in the YAML file, and YAML edits are shown in the UI. This means: * **OT teams** can use the UI for day-to-day operations * **IT teams** can use YAML for infrastructure-as-code workflows * **Both approaches** maintain full version control and auditability * **Scaling operations** benefit from templating while **individual adjustments** benefit from UI convenience > **Pro Tip**: Start with the UI to understand the configuration structure, then switch to YAML for advanced templating and automation. ## Terminology Reference | Current Term (UMH Core) | Legacy Term (UMH Classic) | YAML Key | Description | | ----------------------- | ------------------------- | -------------------- | ------------------------------------------------------- | | Bridge | Protocol Converter | `protocolConverter:` | Connects external devices to UNS with health monitoring | | Stand-alone Flow | Data Flow Component (DFC) | `dataFlow:` | Point-to-point data processing pipelines | | Stream Processor | Stream Processor | `dataFlow:` | Processes data within UNS (upcoming feature) | > **Note:** YAML configuration keys retain legacy names for backward compatibility. The Management Console UI uses the current terminology. ### Agent - Runtime & Device identity | Field | Type | Default | Purpose | | ------------------------------- | ------------------ | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `metricsPort` | `int` | **9102** | Exposes Prometheus metrics for the container. | | `location` | map `int → string` | – | Hierarchical location path (level0-4+) that identifies this instance. **Level 0 (enterprise) is mandatory**. Can follow ISA-95, KKS, or any organizational naming standard. | | `communicator.apiUrl` | `string` | – (console-managed) | HTTPS endpoint of the Management Console. | | `communicator.authToken` | `string` | – | API Key issued by the console. Can be set via `AUTH_TOKEN` env-var. | | `communicator.allowInsecureTLS` | `bool` | `false` | Skip TLS verification [https://github.com/united-manufacturing-hub/united-manufacturing-hub/blob/staging/umh-core/docs/production/corporate-firewalls.md](https://github.com/united-manufacturing-hub/united-manufacturing-hub/blob/staging/umh-core/docs/production/corporate-firewalls.md "mention"). Can be set via `ALLOW_INSECURE_TLS` env-var. | **Location levels** | Index | Generic Level | ISA-95 Example | KKS Example | Other Examples | | ----- | ------------- | ------------------ | --------------- | --------------- | | `0` | Enterprise | `enterprise` | `powerplant` | `acme-inc` | | `1` | Site/Region | `site`/`plant` | `unit-group` | `cologne-plant` | | `2` | Area/Zone | `area`/`line` | `unit` | `cnc-line` | | `3+` | Work Cell+ | `work-cell`, `plc` | `component-grp` | `plc123` | ```yaml agent: metricsPort: 9102 communicator: apiUrl: "https://api.management.umh.app" authToken: "${AUTH_TOKEN}" location: 0: acme-inc 1: plant1 2: press-shop ``` ### DataFlow - Stand-alone Flows A list of all [stand-alone flows](/usage/data-flows/stand-alone-flow.md) (UI: "Stand-alone Flows", YAML: `dataFlow:`). Each entry spins up one Benthos-UMH instance. | Field | Type | Required | Description | | ------------------------------------- | --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | `string` | ✔ | Unique within the file. | | `desiredState` | `active` \| `stopped` | ✔ | Agent will converge to this state. | | `dataFlowComponentConfig.debug_level` | `bool` | ✗ | Enable verbose logging. When `true`, enables DEBUG log level and detailed operational logging (e.g., input/output operations, processing steps, data transformations). When `false` (default), uses INFO log level. **Use only for troubleshooting** - debug logging generates significantly more log data and may impact performance. | | `dataFlowComponentConfig.benthos` | object | ✔ | Inline Benthos config (inputs, pipeline, outputs). | ```yaml dataFlow: - name: opcua-to-uns desiredState: active dataFlowComponentConfig: debug_level: false # Enable detailed logging for troubleshooting benthos: input: opcua: endpoint: "opc.tcp://192.168.0.50:4840" nodeIDs: ["ns=2;s=FolderNode"] pipeline: processors: - tag_processor: defaults: | msg.meta.location_path = "acme.plant1.press-shop.plc1" msg.meta.data_contract = "_raw" msg.meta.tag_name = "value" return msg; output: uns: {} # write into embedded Redpanda ``` **Quick field map** | Path | Notes | | --------------------- | ------------------------------------------------------------------------------ | | `input.*` | Any supported Benthos-UMH input (OPC UA, S7comm, Modbus, MQTT, Kafka, …). | | `pipeline.processors` | Standard Benthos processors **plus** `tag_processor` & `nodered_js`. | | `output.*` | Usually `uns: {}` for Unified Namespace. MQTT, HTTP, SQL, etc. also available. | *For complete input/output syntax see* [*Benthos-UMH Documentation*](https://docs.umh.app/benthos-umh) ### Bridge – Bridge from Device to UNS > 🚧 **Roadmap Item**: Bridges are under active development. Current functionality includes connection monitoring and basic read/write flows. A [**bridge**](/usage/data-flows/bridges.md) (UI: "Bridges", YAML: `protocolConverter:`) ingests data from a field device (e.g. OPC UA server, Siemens S7, Modbus controller) and pushes it into the Unified Namespace (UNS), and vice versa.\\ It combines a **connection probe** and two **stand-alone data flows (one for reading and one for writing)** under a single name and lifecycle. ```yaml protocolConverter: - name: press-opcua desiredState: active protocolConverterServiceConfig: debug_level: false # Enable detailed logging for troubleshooting location: 2: press1 config: connection: nmap: target: "{{ .IP }}" port: "{{ .PORT }}" dataflowcomponent_read: benthos: input: opcua: endpoint: "opc.tcp://{{ .IP }}:{{ .PORT }}" nodeIDs: ["ns=2;s=MachineFolder"] pipeline: processors: - tag_processor: defaults: | msg.meta.location_path = "{{ .location_path }}" msg.meta.data_contract = "_raw" msg.meta.tag_name = msg.meta.opcua_tag_name return msg; output: uns: {} variables: # Optional templating support IP: "192.168.0.50" PORT: "4840" ``` #### Key fields | Field | Description | | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | Unique ID for this converter instance | | `desiredState` | `active` to run immediately, or `stopped` to keep it defined but off. | | `protocolConverterServiceConfig.location` | Appended to the global `agent.location`. Optional, but useful to identify per-machine data. | | `protocolConverterServiceConfig.debug_level` | Enable verbose logging for troubleshooting. When `true`, enables DEBUG log level and protocol-specific debugging (e.g., OPC UA packet inspection via `OPC_DEBUG=1` environment variable, detailed connection diagnostics). When `false` (default), uses INFO log level. **Use only for troubleshooting** - debug logging generates significantly more log data and may impact performance. Disable after resolving issues. **Note:** Same structure as stand-alone flows - `debug_level` is a direct child of the service config, NOT inside `config:` wrapper. | | `template.connection.nmap` | TCP liveness check to decide if the device is reachable. | | `template.dataflowcomponent_read.benthos` | Benthos pipeline to pull and forward data. | | `template.dataflowcomponent_write.benthos` | Benthos pipeline to push and forward data. | | `variables` | Optional Go-template variables, referenced via `{{ .VARNAME }}` in the template. See [Template Variables Reference](/reference/variables.md#variables) for details. | ### Benthos-UMH Processors UMH Core includes specialized processors for industrial data: #### tag\_processor 🚧 > **🚧 Roadmap Item**: The current `tag_processor` implementation follows the benthos-umh pattern with tag names in payloads. With the next UMH Core release, `tag_processor` will be updated to align with the new data model where: > > * Tag names are only in topics (not in payloads) > * Metadata is not included in message payloads > * Output follows standard [timeseries payload format](/usage/unified-namespace/payload-formats.md) For current implementation details, see [Benthos-UMH Tag Processor Documentation](https://docs.umh.app/benthos-umh/processing/tag-processor). ```yaml pipeline: processors: - tag_processor: defaults: | msg.meta.location_path = "{{ .location_path }}"; msg.meta.data_contract = "_raw"; msg.meta.tag_name = "temperature"; return msg; ``` **Data Contract Guidelines:** * Use `_raw` for simple sensor data and initial device integration * Use explicit contracts (e.g., `_temperature`, `_pump`) with [data models](/usage/data-modeling.md) for structured enterprise data * **Migration from UMH Classic:** See [Migration from UMH Classic to UMH Core](/production/migration-from-classic.md) for `_historian` contract migration instructions For detailed documentation, see [Benthos-UMH Tag Processor](https://docs.umh.app/benthos-umh/processing/tag-processor). #### nodered\_js 🚧 Process data using Node-RED-style JavaScript: ```yaml processors: - nodered_js: code: | msg.payload = msg.payload * 1.8 + 32; // Convert C to F msg.topic = "temperature_fahrenheit"; return msg; ``` For complete documentation, see [Benthos-UMH Node-RED JavaScript Processor](https://docs.umh.app/benthos-umh/processing/node-red-javascript-processor). ### Industrial Input Protocols UMH Core supports 50+ industrial protocols via Benthos-UMH. For complete, up-to-date configuration examples, see [Benthos-UMH Input Documentation](https://docs.umh.app/benthos-umh/input/). **Popular protocols include:** * [OPC UA](https://docs.umh.app/benthos-umh/input/opc-ua-input) - Industry standard automation * [Modbus](https://docs.umh.app/benthos-umh/input/modbus) - TCP/RTU serial communication * [Siemens S7](https://docs.umh.app/benthos-umh/input/siemens-s7) - Direct PLC access * [Ethernet/IP](https://docs.umh.app/benthos-umh/input/ethernet-ip) - Allen-Bradley devices **UMH Core Integration Pattern:** ```yaml protocolConverter: - name: device-bridge protocolConverterServiceConfig: config: dataflowcomponent_read: benthos: input: # ANY benthos-umh protocol input pipeline: processors: - tag_processor: { /* UNS metadata setup */ } output: uns: {} ``` ### GraphQL API - Topic Browser 🚧 GraphQL API for querying Unified Namespace topics. | Field | Type | Default | Description | | ------------- | ---------- | ------- | --------------------------------- | | `enabled` | `bool` | `true` | Enable GraphQL API | | `port` | `int` | `8090` | HTTP port for GraphQL endpoint | | `debug` | `bool` | `false` | Enable GraphiQL playground at `/` | | `corsOrigins` | `[]string` | `[]` | CORS origins (empty = allow all) | ```yaml agent: graphql: enabled: true port: 8090 debug: false corsOrigins: - "http://localhost:3000" - "https://your-app.com" ``` **Endpoints:** * **GraphQL API:** `POST /graphql` * **GraphiQL Playground:** `GET /` (debug mode only) * **CORS Preflight:** `OPTIONS /graphql` For complete API reference, see [Topic Browser GraphQL API](/reference/http-api/topic-browser-graphql.md). ### Internal - Built-In Services (expert) UMH Core injects this section automatically. ```yaml internal: redpanda: desiredState: active redpandaServiceConfig: defaultTopicRetentionMs: 604800000 # 7 days maxCores: 1 memoryPerCoreInBytes: 2147483648 topicBrowser: desiredState: active # Topic Browser service (auto-enabled) ``` > **Do not edit** unless instructed by UMH support; invalid settings can brick the stack. ### Validation & tips * **YAML anchors** are supported – useful for re-using input or output snippets. * The Agent logs schema errors and refuses to activate a malformed DFC. ## Related Documentation * [**Bridges**](/usage/data-flows/bridges.md) - Device connectivity patterns * [**Stand-alone Flows**](/usage/data-flows/stand-alone-flow.md) - Custom data processing * [**Data Modeling**](/usage/data-modeling.md) - Structure your industrial data * [**State Machines**](/reference/state-machines.md) - Component lifecycle management ## External References * [**Benthos-UMH Documentation**](https://docs.umh.app/benthos-umh) - Complete protocol and processor reference * [**Management Console**](https://management.umh.app) - Web-based configuration interface --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.umh.app/reference/configuration-reference.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.