{"id":27816926,"url":"https://github.com/azure/azure-osconfig","last_synced_at":"2025-05-01T14:24:05.098Z","repository":{"id":37079394,"uuid":"417240185","full_name":"Azure/azure-osconfig","owner":"Azure","description":"A modular services stack that facilitates remote Linux devices management over Azure","archived":false,"fork":false,"pushed_at":"2025-04-30T16:13:26.000Z","size":12913,"stargazers_count":27,"open_issues_count":10,"forks_count":33,"subscribers_count":11,"default_branch":"dev","last_synced_at":"2025-05-01T00:06:38.958Z","etag":null,"topics":["arc","automanage","azure","device-management","gitops","iot","linux","machine-configuration","microsoft","server"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Azure.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-10-14T18:24:52.000Z","updated_at":"2025-04-30T10:50:14.000Z","dependencies_parsed_at":"2024-01-03T18:26:26.899Z","dependency_job_id":"5fab44a0-c73a-4b69-acd8-d28e17369a9c","html_url":"https://github.com/Azure/azure-osconfig","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Azure%2Fazure-osconfig","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Azure%2Fazure-osconfig/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Azure%2Fazure-osconfig/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Azure%2Fazure-osconfig/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Azure","download_url":"https://codeload.github.com/Azure/azure-osconfig/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251887994,"owners_count":21660097,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arc","automanage","azure","device-management","gitops","iot","linux","machine-configuration","microsoft","server"],"created_at":"2025-05-01T14:24:04.175Z","updated_at":"2025-05-01T14:24:05.091Z","avatar_url":"https://github.com/Azure.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OSConfig\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.md)\n\nAzure OSConfig is a modular security configuration stack for Linux Edge devices. OSConfig supports multi-authority device management over Azure and Azure Portal/CLI, GitOps, as well as local management.\n\nFor more information on OSConfig see [OSConfig North Star Architecture](docs/architecture.md) and [OSConfig Management Modules](docs/modules.md).\n\nFor our code of conduct and contributing instructions see [CONTRIBUTING](CONTRIBUTING.md). For our approach to security see [SECURITY](SECURITY.md).\n\nFor the list of our published binary packages and instructions how to install them see [devops/README.md](devops/README.md).\n\n### C Standard\n\nOSConfig's C/C++ code currently targets compliance with C11.\n\n## Getting started\n\n### Prerequisites\n\nMake sure all dependencies are installed. For example, on Ubuntu:\n\n```bash\nsudo apt-get update\nsudo apt-get install -y git cmake build-essential curl libcurl4-openssl-dev libssl-dev uuid-dev libgtest-dev libgmock-dev rapidjson-dev\n```\n\nVerify that CMake is at least version 3.2.0 and gcc is at least version 4.4.7.\n\n```bash\ncmake --version\ngcc --version\n```\n\nFor IoT Hub management, you can install and configure the *Azure IoT Identity Service (AIS)* package as described at [azure.github.io/iot-identity-service/](https://azure.github.io/iot-identity-service/).\n\nFor contributing to the project, also install the following prerequisites for [pre-commit](https://pre-commit.com/):\n\n```bash\nsudo apt-get install python3\npip3 install pre_commit\npython3 -m pre_commit install\n```\n\n### Build\n\nCreate a folder build folder under the repo root /build\n\n```bash\nmkdir build \u0026\u0026 cd build\n```\n\nBuild with the following commands issued from under the build subfolder:\n\n```bash\ncmake ../src -DCMAKE_BUILD_TYPE=Release|Debug -Duse_prov_client=ON -Dhsm_type_symm_key=ON -DBUILD_TESTS=ON|OFF\ncmake --build . --config Release|Debug  --target install\n```\nThe following OSConfig files are binplaced at build time:\n\nSource | Destination | Description\n-----|-----|-----\n[src/adapters/pnp/](src/adapters/pnp/) | /usr/bin/osconfig | The OSConfig Agent and the main control binary for OSConfig\n[src/platform/](src/platform/) | /usr/bin/osconfig-platform | The OSConfig Platform binary\n[src/adapters/pnp/daemon/osconfig.conn](src/adapters/pnp/daemon/osconfig.conn) | /etc/osconfig/osconfig.conn | Holds manual IoT Hub device connection id string (optional)\n[src/adapters/pnp/daemon/osconfig.json](src/adapters/pnp/daemon/osconfig.json) | /etc/osconfig/osconfig.json | The main configuration file for OSConfig\n[src/modules/commandrunner/assets/osconfig_commandrunner.cache](src/modules/commandrunner/assets/osconfig_commandrunner.cache) | /etc/osconfig/osconfig_commandrunner.cache | Persistent cache for the CommandRunner module\n[src/adapters/pnp/daemon/osconfig.service](src/adapters/pnp/daemon/osconfig.service) | /etc/systemd/system/osconfig.service | The service unit for the OSConfig Agent\n[src/platform/daemon/osconfig-platform.service](src/platform/daemon/osconfig-platform.service) | /etc/systemd/system/osconfig-platform.service | The service unit for the OSConfig Platform\n[src/adapters/pnp/daemon/osconfig.toml](src/adapters/pnp/daemon/osconfig.toml) | /etc/aziot/identityd/config.d/osconfig.toml | The OSConfig Module configuration for AIS\n[src/modules/deviceinfo/](src/modules/deviceinfo/) | /usr/lib/osconfig/deviceinfo.so | The DeviceInfo module binary\n[src/modules/commandrunner/](src/modules/commandrunner/) | /usr/lib/osconfig/commandrunner.so | The CommandRunner module binary\n[src/modules/configuration/](src/modules/configuration/) | /usr/lib/osconfig/configuration.so | The Configuration module binary\n[src/modules/securitybaseline/](src/modules/securitybaseline/) | /usr/lib/osconfig/securitybaseline.so | The SecurityBaseline module binary\n\n### Enable and start OSConfig for the first time\n\nEnable and start OSConfig for the first time by enabling and starting the OSConfig Agent Daemon (`osconfig`):\n\n```bash\nsudo systemctl daemon-reload\nsudo systemctl enable osconfig\nsudo systemctl start osconfig\n```\n\nThe OSConfig Agent service is configured to be allowed to be restarted (automatically by systemd or manually by user) for a maximum number of 3 times at 5 minutes intervals. There is a total delay of 16 minutes before the OSConfig Agent service could be restarted again by the user unless the user reboots the device.\n\nThe OSCOnfig Management Platform Daemon (`osconfig-platform`) is automatically started and stopped by the OSConfig Agent service (`osconfig`) but also can be manually started and stopped separately by itself.\n\nOther daemon control operations:\n\n```bash\nsudo systemctl status osconfig | osconfig-platform\nsudo systemctl disable osconfig | osconfig-platform\nsudo systemctl stop osconfig  | osconfig-platform\n```\nTo replace a service binary while OSConfig is running: stop the Agent daemon, rebuild, start the Agent daemon.\nTo replace a service unit while the daemon is running: stop the Agent daemon, disable the Agent amnd Platform daemons, rebuild, reload daemons, start and enable the Agent daemon.\n\n## Logs\n\nOSConfig logs to its own logs at `/var/log/osconfig*.log*`:\n\n```bash\nsudo cat /var/log/osconfig_pnp_agent.log\nsudo cat /var/log/osconfig_platform.log\nsudo cat /var/log/osconfig_commandrunner.log\nsudo cat /var/log/osconfig_networking.log\nsudo cat /var/log/osconfig_firewall.log\nsudo cat /var/log/osconfig_tpm.log\n...\n```\n\nEach of these log files when it reaches maximum size (128 KB) gets rolled over to a file with the same name and a .bak extension (osconfig_agent.bak, for example).\n\nWhen OSConfig exists prematurely (crashes) the Agent's log (osconfig_pnp_agent.log) at the very end may contain an indication of that. For example:\n\n```\n[ERROR] OSConfig crash due to segmentation fault (SIGSEGV) during MpiGet to Firewall.FirewallRules\n```\nOnly the root user can view these log files.\n\n## Configuration\n\nOSConfig can be configured via `/etc/osconfig/osconfig.json`. After changing this configuration file, restart OSConfig to apply the configuration changes. Only the root user can view or edit this configuration file.\n\n### Enabling management via IoT Hub\n\nOriginally OSConfig was developed with the IoT Hub management channel by default and always enabled. Currently, this managament channel is by default disabled. You can enable it via the OSConfig general configuration file at `/etc/osconfig/osconfig.json`. Edit there the integer value named \"IotHubManagement\" to a non-zero value:\n\n```json\n{\n    \"IotHubManagement\": 0\n}\n```\n\n### Adjusting the reporting interval\n\nOSConfig periodically reports device data at a default time period of 30 seconds. This interval period can be adjusted between 1 second and 86,400 seconds (24 hours) via the OSConfig general configuration file at `/etc/osconfig/osconfig.json`. Edit there the integer value named \"ReportingIntervalSeconds\" to a value between 1 and 86400:\n\n```json\n{\n    \"ReportingIntervalSeconds\": 30\n}\n```\n\nThis interval is used for RC/DC, GitOps DC, and IoT Hub processing.\n\n### Enabling debug logging\n\nDebug logging means that OSConfig will log all input and output from and to all management authority channels, as well as all input and output from system commands executed by Agent, Platform and Modules.\n\nGenerally it is not recommended to run OSConfig with debug logging enabled.\n\nTo enable debug logging, edit the OSConfig general configuration file `/etc/osconfig/osconfig.json` and set there (or add if needed) an integer value named \"LoggingLevel\" to a value 7:\n\n```json\n{\n    \"LoggingLevel\": 7\n}\n```\n\nTo disable debug logging, set \"LoggingLevel\" to 6 (informational logging, default).\n\n## Local Management over RC/DC\n\nOSConfig uses two local files as local digital twins in MIM JSON payload format:\n\n`/etc/osconfig/osconfig_desired.json` contains desired configuration (to be applied to the device)\n\n`/etc/osconfig/osconfig_reported.json` contains reported configuration (to be reported from the device)\n\nThis pair of files are called Reported Configuration (RC) and Desired Configuration (DC) or RC/DC.\n\nOnce created, only the root user can view these files or change the DC file.\n\nBy default, the reported configuration is not saved locally to the DC file at `/etc/osconfig/osconfig_reported.json` (local reporting is disabled) and desired configuration is not picked-up from the DC file at `/etc/osconfig/osconfig_desired.json`.\n\nTo enable local management, edit the OSConfig general configuration file `/etc/osconfig/osconfig.json` and set there (or add if needed) an integer value named \"LocalManagement\" to a non-zero value:\n\n```json\n{\n    \"LocalManagement\": 1\n}\n```\nTo disable local management, set \"LocalManagement\" to 0.\n\n### Desired Configuration (DC) management over GitOps\n\nOSConfig can apply to the device desired configuration in MIM JSON payload format (same as for RC/DC) read from a Git repository and branch. The DC file must be named `osconfig_desired.json` and be placed in the root of the repository.\n\nBy default, desired configuration (DC) over GitOps is disabled and there are no configured Git repository or branch.\n\nTo enable GitOps DC management, edit the OSConfig general configuration file `/etc/osconfig/osconfig.json` and there:\n\n1. Set (or add if needed) a string value named \"GitRepositoryUrl\" to a string value containing the string that can be used to clone a Git repository, for example (this example uses OSConfig's own repository but can be anything):\n\n```json\n{\n    \"GitRepositoryUrl\": \"https://github.com/Azure/azure-osconfig\"\n}\n```\n\nFor HTTPS cloning of a private Git repository, add necessary credentials to the \"GitRepositoryUrl\" such as, for example: `https://\u003cusername\u003e:\u003cpassword\u003e@github.com/path/to/repo`. For SSH cloning, configure authetication separately on the device so OSConfig can use it.\n\n2. Set (or add if needed) a string value named \"GitBranch\" to a string value containing the Git branch name where the DC file is located, for example:\n\n```json\n{\n    \"GitBranch\": \"name/branch\"\n}\n```\n\nSet (or add if needed) an integer value named \"GitManagement\" to a non-zero value to enable GitOps DC management:\n\n```json\n{\n    \"GitManagement\": 1\n}\n```\nTo disable GitOps DC management, set \"GitManagement\" to 0.\n\nOSConfig clones locally the configured Git DC file and branch to `/etc/osconfig/gitops/osconfig_desired.json`. This Git clone is automatically deleted when the OSConfig Agent (Watcher) terminates. While active, the cloned DC file is protected for root user access only.\n\n### Changing the protocol OSConfig uses to connect to the IoT Hub\n\nThe networking protocol that OSConfig uses to connect to the IoT Hub is configured in the OSConfig general configuration file `/etc/osconfig/osconfig.json`:\n\n```json\n{\n    \"IotHubProtocol\": 2\n}\n```\n\nOSConfig currently supports the following protocol values:\n\nValue | Description\n-----|-----\n0 | Decided by OSConfig (currently this is MQTT)\n1 | MQTT\n2 | MQTT over Web Socket\n\n## HTTP proxy configuration\n\nWhen the configured IotHubProtocol value is set to value 2 (MQTT over Web Socket) OSConfig attempts to use the HTTP proxy information configured in one of the following environment variables, the first such variable that is locally present:\n\n1. `http_proxy`\n1. `https_proxy`\n1. `HTTP_PROXY`\n1. `HTTPS_PROXY`\n\nOSConfig supports the HTTP proxy configuration to be in one of the following formats:\n\n- `http://server:port`\n- `http://username:password@server:port`\n- `http://domain\\username:password@server:port`\n\nWhere the prefix is either lowercase `http` or uppercase `HTTP` and the username and password can contain `@` characters escaped as `\\@`.\n\nFor example: `http://username\\@mail.foo:p\\@ssw\\@rd@www.foo.org:100` where username is `username@mail.foo`, password is `p@ssw@rd`, the proxy server is `www.foo.org` and the port is 100.\n\nThe environment variable needs to be set for the root user account. For example, for a fictive proxy server, user and password, the environment variable `http_proxy` can be set for the root user manually via console with:\n\n```\nsudo -E su\nexport http_proxy=http://user:password@wwww.foo.org:100//\n```\n\nThe environment variable can also be set in the OSConfig service unit file by uncommenting and editing the following line in [src/adapters/pnp/daemon/osconfig.service](src/adapters/pnp/daemon/osconfig.service):\n\n```\n# Uncomment and edit next line to configure OSConfig with a proxy to connect to the IoT Hub\n# Environment=\"http_proxy=http://user:password@wwww.foo.org:100//\"\n```\n\nAfter editing the service unit file, stop and disable osconfig.service, rebuild OSConfig, then enable and start osconfig.service:\n\n```bash\nsudo systemctl stop osconfig.service\nsudo systemctl disable osconfig.service\ncd build\ncmake ../src -DCMAKE_BUILD_TYPE=Release|Debug -Duse_prov_client=ON -Dhsm_type_symm_key=ON -DBUILD_TESTS=ON|OFF\ncmake --build . --config Release|Debug  --target install\nsudo systemctl enable osconfig.service\nsudo systemctl start osconfig.service\n```\n\n---\n\nMicrosoft may collect performance and usage information which may be used to provide and improve Microsoft products and services and enhance users experience. To learn more, review the [privacy statement](https://go.microsoft.com/fwlink/?LinkId=521839\u0026clcid=0x409).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazure%2Fazure-osconfig","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fazure%2Fazure-osconfig","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazure%2Fazure-osconfig/lists"}