.. _os-runtime-services: .. _os-manager-integration: ###################################### Orchestra Manager Platform Integration ###################################### This chapter defines the device-side requirements for out-of-the-box integration with the Orchestra Manager Platform. A Manager-ready image supplies the runtime needed for enrollment, authenticated management, application operations, system updates, and telemetry. Enrollment then supplies the device identity and the configuration specific to the selected Manager deployment. The OrchestraOS base image provides OpenSSH, Python, sudo, Docker, Compose, NetworkManager, WireGuard tools, Fluent Bit, Telegraf, and TPM2 interfaces. RAUC images additionally provide the system-update runtime. The deployment's matching Manager enrollment and provisioning assets complete this integration with endpoint configuration, credentials, access policy, and collection settings. Integration Requirements ======================== .. list-table:: Device capabilities and deployment inputs :header-rows: 1 :widths: 22 38 40 * - Capability - OrchestraOS baseline - Required Manager integration * - Enrollment and identity - Python, HTTPS client tools, certificate handling, and persistent storage. - The deployment's enrollment procedure, tenant authorization, unique device identity, and issued certificate chain. * - Management connectivity - NetworkManager and explicit kernel/user-space WireGuard support. - Assigned management address, relay/tunnel settings, keys, and routes returned by enrollment. * - Remote execution - OpenSSH, Python, sudo, and systemd. - Trusted SSH certificate authorities, account/principal mapping, and permissions for the approved Manager operations. * - Container operations - Docker and Compose, with daemon state under ``/data/docker``. - Platform-managed application definitions, matching target architecture, registry access, and persistent application storage policy. * - Metrics and inventory - Telegraf and its systemd service. - Approved inputs and any inventory helpers, device identification, authenticated output, and the deployment's ingestion endpoints. * - Device and application logs - Fluent Bit with journal input and TLS/provider capabilities. - Selected log sources, the Manager-compatible output format and transport, device identification, and ingestion credentials. * - Operating-system updates - RAUC service, platform slot configuration, and bundle verification. - Matching bundle compatibility, trusted signing certificates, delivery configuration, and post-boot health policy. * - Persistence - The data volume and, for rootfs-on-LVM images, the persistent ``/etc`` overlay. - Durable enrollment state, credentials, collector configuration, and application state with suitable ownership and update compatibility. Enrollment and Device Identity ============================== Enrollment must associate the device with the intended tenant and create the credentials used by device-facing Manager services. Use the enrollment assets and short-lived authorization supplied for that Manager deployment. Device private keys remain on the device; the resulting certificate chain and service configuration must persist across reboots and A/B rootfs updates. Hostname provisioning combines the gateway type, ``HOSTNAME_BASE`` (default ``orcos``), and a readable board serial number. This hostname is useful for operations, while the enrolled identity determines the managed device record. For virtual machines or hardware without a serial number, provide a unique identity through the enrollment procedure. Hardware-backed key storage requires the matching TPM or SoC integration and access permissions for the consuming services. The installed TPM2 packages and Fluent Bit provider support are capabilities on which enrollment can build; the deployment defines which key objects and certificate identities to use. Network Connectivity ==================== Before enrollment, the device needs a working uplink, DNS resolution, a usable clock for certificate validation, and access to the deployment's enrollment and trust endpoints. NetworkManager supplies wired, Wi-Fi, and cellular connection management; the reference drop-ins select iwd and dhcpcd. Set the appropriate carrier APN and SIM settings when using cellular connectivity; the supplied ``cthingsco`` APN is a reference value. The management path uses the address, relay endpoints, and WireGuard settings assigned during enrollment. Retain these settings and permit their transport through the device and upstream network policy. Manager must be able to reach the authorized SSH service over that management path after a reboot or uplink reconnection. .. list-table:: Network policy inputs :header-rows: 1 * - Traffic - Required reachability * - Enrollment and certificate services - Outbound access to the HTTPS endpoints and trust services designated by the deployment. * - Management overlay - WireGuard transport to the assigned relay endpoints and ports, plus the management routes supplied with that configuration. * - Remote administration - SSH access from the authorized Manager management path, normally to TCP port 22 unless the deployment changes the listener. * - Metrics and log delivery - Outbound authenticated connections to the configured ingestion endpoints. * - Application and update delivery - Access to the assigned container registries and system-update sources. * - Supporting services - DNS and the selected time-synchronization service through the allowed uplink or management network. Endpoint names, relay ports, routes, and proxy settings belong to the Manager deployment configuration. The default Fluent Bit Forward port ``24224`` is not a universal platform firewall requirement. .. _os-runtime-access: Management Account and Remote Execution ======================================= The management account must accept the SSH certificate authorities and principals selected by Manager and have the privileges needed by its approved jobs. Retain the Python runtime used by remote automation, and ensure that systemd service operations and required Docker access work under that account. Enrollment must configure certificate trust and account policy in addition to installing a static SSH public key. The reference ``ct`` account has password ``cthingsco``, passwordless sudo, and membership in device and Docker groups. Replace these development credentials and apply the deployment's management-account policy. The ``full-cmdline-sshkey`` image supplies a key-only SSH policy; minimal, Weston, and ``full-cmdline-sshpass`` images rely on their effective OpenSSH configuration. Inspect that configuration with ``sshd -T`` after enrollment. Logging and Metrics Configuration ================================= Manager provisioning must install the approved collection and output configuration for both agents, with the device identity and permissions needed by the receiving services. Use the enrolled certificate identity for mTLS where required by the deployment, and arrange renewal without losing service access. Fluent Bit ``5.0.5`` reads configuration from ``/etc/fluent-bit/fluent-bit.conf``. Its reference journal input uses the volatile cursor database ``/run/fluent-bit/journal.db`` and ``Read_From_Tail off``. The sample output is Forward, with its remote host commented out. Provision the Manager-compatible log format, destination, and authenticated transport; configure selected container logs when those are part of the managed service. Choose journal retention and replay handling to match the receiver. Telegraf ``1.38.4`` reads ``/etc/telegraf/telegraf.conf`` and the service's configuration directory ``/etc/telegraf/telegraf.d``. The supplied file enables host inputs at a ten-second interval and declares a sample InfluxDB output with example URLs and credentials commented out. Manager provisioning supplies the approved output, host/container inputs, and any structured inventory helpers. The ``telegraf`` service account needs access to those inputs and its credentials. Successful integration requires the platform to receive records under the correct device and tenant identity. A running collector or successful local collection test establishes only part of that requirement. Container and System-Update Operations ====================================== Docker and Compose provide the runtime used by Manager's container application operations. The enrolled management account must be able to perform the allowed operations, retrieve the assigned images, and apply application configuration. Keep Docker state under ``/data/docker`` and define persistent mounts for application data that must survive replacement or rollback. RAUC images provide the A/B system-update path described in :ref:`os-rauc-update-flow`. Manager integration must select compatible bundles, configure the applicable delivery service, and preserve the device's RAUC certificate trust. Where the deployment uses the installed hawkBit updater, provision its endpoint and authentication as part of that integration. After an OS update, the device must restore its enrolled identity, reconnect to the management path, resume collection, and apply the agreed slot-health decision. Boot-signing keys, RAUC bundle-signing trust, and Manager device identity serve different purposes and must have independent provisioning and renewal policies.