particle-os-tools/docs/apt-layer/rpm-ostree/man-pages/rpm-ostreed.conf.5.md

rpm-ostreed.conf(5) - rpm-ostree daemon configuration file

Name

rpm-ostreed.conf - rpm-ostree daemon configuration file

Synopsis

/etc/rpm-ostreed.conf

Description

This file configures the rpm-ostree daemon.

Options

All options are configured in the [Daemon] section. Available options are:

AutomaticUpdatePolicy=

Controls the automatic update policy. Currently "none", "check", "stage", "apply". "none" disables automatic updates. "check" downloads just enough metadata to check for updates and display them in rpm-ostree status. Defaults to "none". The rpm-ostreed-automatic.timer(8) unit determines the actual frequency of updates.

The "stage" policy downloads and unpacks the update, queuing it for the next boot. This leaves initiating a reboot to other automation tools. Only a small amount of work is left to be performed at shutdown time via the ostree-finalize-staged.service systemd unit.

Finally, the "apply" policy will currently always initiate a reboot. However, in the future it may apply userspace-only fixes without a physical reboot. Any reboots initiated via rpm-ostree will default to honoring active systemd inhibitors. For example, to temporarily suppress automatic "apply" updates while debugging a system, you can use systemd-inhibit bash; exiting the shell will lift the inhibitor.

Values:

• none - Disable automatic updates (default)
• check - Check for updates and display in status
• stage - Download and stage updates for next boot
• apply - Download, stage, and apply updates with reboot

IdleExitTimeout=

Controls the time in seconds of inactivity before the daemon exits. Use 0 to disable auto-exit. Defaults to 60.

Values:

• 0 - Disable auto-exit
• 60 - Exit after 60 seconds of inactivity (default)
• 300 - Exit after 5 minutes of inactivity

LockLayering=

Controls whether any mutation of the base OSTree commit is supported (for example, package overlays or overrides, initramfs overlays or regeneration). Defaults to false.

Values:

• true - Disable package layering and overrides
• false - Allow package layering and overrides (default)

Recommends=

When layering, whether to install weak dependencies. Defaults to true.

Values:

• true - Install weak dependencies during layering (default)
• false - Skip weak dependencies during layering

Example

Enabling the automatic updates "check" policy is a two step process. First, edit /etc/rpm-ostreed.conf to include AutomaticUpdatePolicy=check and then use rpm-ostree reload to reload the rpm-ostreed service. Next, enable the timer using systemctl enable rpm-ostreed-automatic.timer --now

When successful, the output from rpm-ostree status will display output similar to the following:

$ rpm-ostree status
State: idle; auto updates enabled (check; last run 22min ago)
...

Basic Configuration

# /etc/rpm-ostreed.conf
[Daemon]
AutomaticUpdatePolicy=check
IdleExitTimeout=60
LockLayering=false
Recommends=true

Disable Automatic Updates

# /etc/rpm-ostreed.conf
[Daemon]
AutomaticUpdatePolicy=none
IdleExitTimeout=300
LockLayering=false
Recommends=true

Enable Automatic Staging

# /etc/rpm-ostreed.conf
[Daemon]
AutomaticUpdatePolicy=stage
IdleExitTimeout=60
LockLayering=false
Recommends=true

Enable Automatic Application

# /etc/rpm-ostreed.conf
[Daemon]
AutomaticUpdatePolicy=apply
IdleExitTimeout=60
LockLayering=false
Recommends=true

Lock Package Layering

# /etc/rpm-ostreed.conf
[Daemon]
AutomaticUpdatePolicy=check
IdleExitTimeout=60
LockLayering=true
Recommends=false

Configuration Management

Reloading Configuration

After modifying the configuration file, reload the daemon:

# Reload daemon configuration
rpm-ostree reload

# Or restart the service
systemctl restart rpm-ostreed

Service Management

# Enable automatic updates timer
systemctl enable rpm-ostreed-automatic.timer --now

# Check timer status
systemctl status rpm-ostreed-automatic.timer

# Disable automatic updates
systemctl disable rpm-ostreed-automatic.timer

# Check service status
systemctl status rpm-ostreed

Configuration Validation

# Check configuration syntax
rpm-ostree reload

# View current configuration
systemctl show rpm-ostreed --property=Environment

Automatic Update Policies

Policy: none

Disables automatic updates completely. The system will not check for updates automatically.

Use cases:

• Development environments
• Air-gapped systems
• Manual update management

Configuration:

[Daemon]
AutomaticUpdatePolicy=none

Policy: check

Downloads metadata to check for updates and displays them in rpm-ostree status. Does not download or apply updates.

Use cases:

• Monitoring systems
• Update notification
• Manual update control

Configuration:

[Daemon]
AutomaticUpdatePolicy=check

Policy: stage

Downloads and stages updates for the next boot. Requires manual reboot to apply updates.

Use cases:

• Controlled deployments
• Batch updates
• Maintenance windows

Configuration:

[Daemon]
AutomaticUpdatePolicy=stage

Policy: apply

Downloads, stages, and applies updates with automatic reboot.

Use cases:

• Fully automated updates
• Edge devices
• Unattended systems

Configuration:

[Daemon]
AutomaticUpdatePolicy=apply

Security Considerations

LockLayering Security

When LockLayering=true, the system prevents:

• Package installation via rpm-ostree install
• Package removal via rpm-ostree uninstall
• Package overrides via rpm-ostree override
• Initramfs modifications

This provides additional security by preventing unauthorized package modifications.

Automatic Update Security

Automatic updates can be controlled via systemd inhibitors:

# Temporarily inhibit automatic updates
systemd-inhibit bash

# Check active inhibitors
systemctl show rpm-ostreed --property=Inhibitors

Troubleshooting

Configuration Issues

# Check configuration file syntax
cat /etc/rpm-ostreed.conf

# Validate configuration
rpm-ostree reload

# Check daemon logs
journalctl -u rpm-ostreed

Automatic Update Issues

# Check timer status
systemctl status rpm-ostreed-automatic.timer

# Check service status
systemctl status rpm-ostreed-automatic.service

# View timer logs
journalctl -u rpm-ostreed-automatic.timer

# View service logs
journalctl -u rpm-ostreed-automatic.service

Daemon Issues

# Check daemon status
systemctl status rpm-ostreed

# Restart daemon
systemctl restart rpm-ostreed

# View daemon logs
journalctl -u rpm-ostreed -f

Files

• /etc/rpm-ostreed.conf - Daemon configuration file
• /etc/systemd/system/rpm-ostreed.service - Daemon service unit
• /etc/systemd/system/rpm-ostreed-automatic.service - Automatic update service
• /etc/systemd/system/rpm-ostreed-automatic.timer - Automatic update timer

See Also

• rpm-ostree(1) - Main rpm-ostree command-line tool
• rpm-ostreed-automatic.service(8) - Automatic updates service
• rpm-ostreed-automatic.timer(8) - Automatic updates timer
• systemd.timer(5) - Systemd timer units
• systemd-inhibit(1) - Systemd inhibitors