<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
Copyright (C) 2018 Red Hat, Inc.

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the
Free Software Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.
-->

<refentry id="rpm-ostreed.conf">

  <refentryinfo>
    <title>rpm-ostreed.conf</title>
    <productname>rpm-ostree</productname>

    <authorgroup>
      <author>
        <contrib>Developer</contrib>
        <firstname>Jonathan</firstname>
        <surname>Lebon</surname>
        <email>jlebon@redhat.com</email>
      </author>
    </authorgroup>
  </refentryinfo>

  <refmeta>
    <refentrytitle>rpm-ostreed.conf</refentrytitle>
    <manvolnum>5</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>rpm-ostreed.conf</refname>
    <refpurpose>rpm-ostree daemon configuration file</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <para><filename>/etc/rpm-ostreed.conf</filename></para>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para>
      This file configures the rpm-ostree daemon.
    </para>
  </refsect1>

  <refsect1>
    <title>Options</title>

    <para>
      All options are configured in the "[Daemon]" section. Available options are:
    </para>

    <variablelist>
      <varlistentry>
        <term><varname>AutomaticUpdatePolicy=</varname></term>

        <listitem>
        <para>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 <command>rpm-ostree status</command>. Defaults to
        "none". The <citerefentry><refentrytitle>rpm-ostreed-automatic.timer</refentrytitle><manvolnum>8</manvolnum></citerefentry>
        unit determines the actual frequency of updates.</para>
        <para>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 <literal>ostree-finalize-staged.service</literal> systemd unit.
        </para>
        <para>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 <literal>systemd-inhibit bash</literal>; exiting the shell will lift the inhibitor.
        </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><varname>IdleExitTimeout=</varname></term>

        <listitem>
        <para>Controls the time in seconds of inactivity before the daemon exits. Use 0 to
        disable auto-exit. Defaults to 60.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><varname>LockLayering=</varname></term>

        <listitem>
        <para>Controls whether any mutation of the base OSTree commit is
        supported (for example, package overlays or overrides, initramfs
        overlays or regeneration). Defaults to false.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><varname>Recommends=</varname></term>

        <listitem>
        <para>When layering, whether to install weak dependencies. Defaults to true.</para>
        </listitem>
      </varlistentry>
    <!--
      <varlistentry>
        <term><varname>OptionName=</varname></term>

        <listitem>
        <para>Template for adding option names. Values are enumerated like "val1",
        "val2".</para>
        </listitem>
      </varlistentry>
    -->
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Example</title>

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

    <para>When successful, the output from <command>rpm-ostree status</command> will
    display output similar to the following:</para>

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

  <refsect1>
    <title>See Also</title>

    <para>
      <citerefentry><refentrytitle>rpm-ostree</refentrytitle><manvolnum>1</manvolnum></citerefentry>
      <citerefentry><refentrytitle>rpm-ostreed-automatic.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
      <citerefentry><refentrytitle>rpm-ostreed-automatic.timer</refentrytitle><manvolnum>8</manvolnum></citerefentry>
    </para>
  </refsect1>

</refentry>
