Azure OSConfig is a modular security configuration stack for Linux Edge devices. OSConfig supports multi-authority device management over Azure Policy, as well as local management.
For more information on OSConfig see OSConfig North Star Architecture and OSConfig Management Modules.
For our code of conduct and contributing instructions see CONTRIBUTING. For our approach to security see SECURITY.
For the list of our published binary packages and instructions how to install them see devops/README.md.
OSConfig's C/C++ code currently targets compliance with C11.
Using the pre-defined devops/docker/ubuntu-24.04-amd64/Dockerfile we can simply use the RUN commands to install all needed pre-requisites. We also need to run sudo -i since many commands require root (some uneeded packages only used by CI were omitted).
sudo apt -y update && sudo apt-get -y install software-properties-common
sudo apt -y update && sudo apt-get -y install build-essential cmake git curl pkg-config tar unzip wget zipVerify that CMake is at least version 3.21 and gcc is at least version 4.4.7.
cmake --version
gcc --versionFor contributing to the project, also install the following prerequisites for pre-commit:
sudo apt-get install python3
pip3 install pre_commit
python3 -m pre_commit installCreate a folder build folder under the repo root /build
mkdir build && cd buildBuild with the following commands issued from under the build subfolder:
cmake ../src -DCMAKE_BUILD_TYPE=Release|Debug -DBUILD_TESTS=ON|OFF
cmake --build . --config Release|Debug --target installThe following OSConfig files are binplaced at build time:
| Source | Destination | Description |
|---|---|---|
| src/adapters/agent/ | /usr/bin/osconfig | The OSConfig Agent and the main control binary for OSConfig |
| src/platform/ | /usr/bin/osconfig-platform | The OSConfig Platform binary |
| src/adapters/agent/daemon/osconfig.json | /etc/osconfig/osconfig.json | The main configuration file for OSConfig |
| src/adapters/agent/daemon/osconfig.service | /etc/systemd/system/osconfig.service | The service unit for the OSConfig Agent |
| src/platform/daemon/osconfig-platform.service | /etc/systemd/system/osconfig-platform.service | The service unit for the OSConfig Platform |
| src/modules/deviceinfo/ | /usr/lib/osconfig/deviceinfo.so | The DeviceInfo module binary |
| src/modules/configuration/ | /usr/lib/osconfig/configuration.so | The Configuration module binary |
| src/modules/securitybaseline/ | /usr/lib/osconfig/securitybaseline.so | The SecurityBaseline module binary |
| src/common/telemetry/ | /var/lib/osconfig/telemetry | The OSConfig telemetry directory |
Enable and start OSConfig for the first time by enabling and starting the OSConfig Agent Daemon (osconfig):
sudo systemctl daemon-reload
sudo systemctl enable osconfig
sudo systemctl start osconfigThe 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.
The 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.
Other daemon control operations:
sudo systemctl status osconfig | osconfig-platform
sudo systemctl disable osconfig | osconfig-platform
sudo systemctl stop osconfig | osconfig-platformTo replace a service binary while OSConfig is running: stop the Agent daemon, rebuild, start the Agent daemon. To 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.
OSConfig logs to its own logs at /var/log/osconfig*.log*:
sudo cat /var/log/osconfig_agent.log
sudo cat /var/log/osconfig_platform.log
sudo cat /var/log/osconfig_commandrunner.log
sudo cat /var/log/osconfig_networking.log
sudo cat /var/log/osconfig_firewall.log
sudo cat /var/log/osconfig_tpm.log
...Each 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).
When OSConfig exists prematurely (crashes) the Agent's log (osconfig_agent.log) at the very end may contain an indication of that. For example:
[ERROR] OSConfig crash due to segmentation fault (SIGSEGV) during MpiGet to Firewall.FirewallRules
Only the root user can view these log files.
OSConfig 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.
OSConfig 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:
{
"ReportingIntervalSeconds": 30
}This interval is used for RC/DC processing.
Debug 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.
Generally it is not recommended to run OSConfig with debug logging enabled.
To 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:
{
"LoggingLevel": 7
}To disable debug logging, set "LoggingLevel" to 6 (informational logging, default).
OSConfig uses two local files as local digital twins in MIM JSON payload format:
/etc/osconfig/osconfig_desired.json contains desired configuration (to be applied to the device)
/etc/osconfig/osconfig_reported.json contains reported configuration (to be reported from the device)
This pair of files are called Reported Configuration (RC) and Desired Configuration (DC) or RC/DC.
Once created, only the root user can view these files or change the DC file.
By default, the reported configuration is locally saved to the DC file at /etc/osconfig/osconfig_reported.json (local reporting is enabled) and desired configuration is picked-up from the DC file at /etc/osconfig/osconfig_desired.json.
To disable 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 zero value:
{
"LocalManagement": 0
}To enable local management, set "LocalManagement" to 1.
Microsoft 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.