.. _remote-file-management: Remote File Management ====================== The TEG gateway supports remote file management via ThingsBoard shared attributes. This mechanism allows configuration and system files on the gateway device to be created, updated, monitored, and synchronized in a controlled and traceable way. The approach is designed to be robust against intermittent connectivity and to support both read-only mirroring and file writing. The remote file management mechanism follows a *server-authoritative* model. ThingsBoard shared attributes define the desired state of all managed files. The TEG gateway never propagates local file changes upstream, except for mirroring file content and reporting synchronization status. Shared Attributes ----------------- Shared attributes are used to push file metadata and file content from ThingsBoard to the TEG gateway. The central element is the ``FILES`` attribute, which defines which files are managed and how they should be handled. Actual file content is transferred separately using dedicated attributes. Initialize the ``FILES`` Attribute ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``FILES`` attribute is a JSON object containing metadata entries for each managed file. Each entry defines the target path on the TEG gateway, the encoding used for file transfer, and optional behavior flags. Supported metadata fields: - ``path`` Target location on the TEG gateway filesystem. Can be absolute or relative. Locally defined environment variables such as ``$DATA_PATH`` are expanded at runtime. - ``encoding`` Encoding used when transferring file content. Supported values are ``text``, ``json``, and ``base64``. Base64 is recommended for files containing line breaks or special characters. - ``write_version`` (optional) Monotonically increasing version number used to ensure that the latest file version is applied after temporary disconnections. - ``restart_controller_on_change`` (optional) Boolean flag indicating whether the controller software should be restarted after a successful file update. Only the managed controller is restarted when this flag is set. The TEG gateway process itself continues running and is not restarted. Example: Managing a controller configuration file and the system crontab .. code-block:: json { "crontab": { "path": "/var/spool/cron/crontabs/root", "encoding": "base64", "write_version": 1 }, "controller_config": { "path": "$DATA_PATH/config.json", "encoding": "json", "write_version": 1, "restart_controller_on_change": true } } When a new entry is added to the ``FILES`` attribute, the TEG gateway evaluates whether a corresponding ``FILE_CONTENT_`` attribute exists. - If file content is available, the file is created or updated accordingly. - If no file content attribute exists, the file is treated as read-only and its current content is mirrored back to ThingsBoard. Read-only mirroring is intended for observability and auditing of files that are not actively managed by the TEG gateway, for example log files, system files or configuration files modified by other services. In both cases, the TEG gateway creates a client attribute named ``FILE_READ_`` containing the latest local file content which can be accessed in ThingsBoard and included in Dashboards. Populate ``FILE_CONTENT_`` Attributes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File content is defined in ThingsBoard using a dedicated shared attribute named ``FILE_CONTENT_``. The encoding must match the encoding defined in the corresponding ``FILES`` entry. Use case: Create or update a json-based configuration file """""""""""""""""""""""""""""""""""""""""""""""""""""""""" To manage the controller configuration, a shared attribute ``FILE_CONTENT_controller_config`` is created and populated with JSON-encoded configuration data. .. code-block:: json { "setting1": "value1", "setting2": "value2" } After applying the update, the TEG gateway mirrors the current file content into the client attribute ``FILE_READ_controller_config``. Use case: Update the system crontab """"""""""""""""""""""""""""""""""" System-level files such as the OS crontab can be managed in the same way. In this case, content is base64-encoded to preserve formatting and special characters. Here a shared attribute ``FILE_CONTENT_crontab`` is created with the base64-encoded content of the desired crontab file. .. code-block:: text U0hFTEw9L2Jpbi9iYXNoClBBVEg9L3Vzci9sb2NhbC9zYmluOi91c3IvbG9jYWwvYmluOi91c3IvbG9jYWwvYmluOi91c3Ivc2JpbjovdXNyL2Jpbjovc2JpbjovYmluCkhPTUU9L3Jvb3QKCiMgRG9ja2VyCkBkYWlseSBkb2NrZXIgc3lzdGVtIHBydW5lIC1hIC0tZm9yY2UgLS1maWx0ZXIgInVudGlsPTg3NjBoIgoKIyBEZWxldGUgb2xkIGxvZyBmaWxlcyAob2xkZXIgdGhhbiAxMDAgZGF5cykKQGRhaWx5IC91c3IvYmluL2ZpbmQgL2hvbWUvcGkvY29udHJvbGxlci9sb2dzLyAtdHlwZSBmIC1tdGltZSArMTAwIC1kZWxldGUK After the update is applied, the TEG gateway mirrors the current crontab content encoded as ``base64`` into the client attribute ``FILE_READ_crontab``. Client Attributes ----------------- Client attributes are used to report file content back to ThingsBoard and preserve synchronization status. For each file defined in the ``FILES`` attribute: - A client attribute ``FILE_READ_`` mirrors the latest local file content. - A global client attribute ``FILE_HASHES`` is updated after file creation or modification. File Hashes and Synchronization ------------------------------- The ``FILE_HASHES`` attribute is used to ensure consistency between ThingsBoard and the TEG gateway. The TEG gateway periodically computes a hash for each managed local file and compares it against the corresponding entry in ``FILE_HASHES``. Each entry includes both the hash and the associated ``write_version``. If a mismatch is detected: - The TEG gateway requests the latest content from ``FILE_CONTENT_``. - If the shared attribute is missing or empty, no action is taken. - If a managed file was modified locally, the detected hash mismatch causes the TEG gateway to re-apply the remote file content, restoring the desired state defined in ThingsBoard. If a file update fails, for example due to invalid encoding, insufficient permissions, or temporary I/O errors, the TEG gateway logs the error locally and does not update the corresponding hash entry. This allows the issue to be diagnosed and retried without leaving the system in an inconsistent state. Example: ``FILE_HASHES`` client attribute .. code-block:: json { "crontab": { "hash": "5eaad668b8e694ec58f0873830110d5f", "write_version": 2 }, "controller_config": { "hash": "9368caefc2b90f334671fb96e41ecbe1", "write_version": 3 } }