1..
2  Copyright (C) 2014-2018 Red Hat, Inc.
3
4  This copyrighted material is made available to anyone wishing to use,
5  modify, copy, or redistribute it subject to the terms and conditions of
6  the GNU General Public License v.2, or (at your option) any later version.
7  This program is distributed in the hope that it will be useful, but WITHOUT
8  ANY WARRANTY expressed or implied, including the implied warranties of
9  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
10  Public License for more details.  You should have received a copy of the
11  GNU General Public License along with this program; if not, write to the
12  Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
13  02110-1301, USA.  Any Red Hat trademarks that are incorporated in the
14  source code or documentation are not subject to the GNU General Public
15  License and may only be used or replicated with the express permission of
16  Red Hat, Inc.
17
18###############
19 DNF Automatic
20###############
21
22==========
23 Synopsis
24==========
25
26``dnf-automatic [<config file>]``
27
28=============
29 Description
30=============
31
32Alternative CLI to ``dnf upgrade`` with specific facilities to make it suitable to be executed automatically and regularly from systemd timers, cron jobs and similar.
33
34The operation of the tool is usually controlled by the configuration file or the function-specific timer units (see below). The command only accepts a single optional argument pointing to the config file, and some control arguments intended for use by the services that back the timer units. If no configuration file is passed from the command line, ``/etc/dnf/automatic.conf`` is used.
35
36The tool synchronizes package metadata as needed and then checks for updates available for the given system and then either exits, downloads the packages or downloads and applies the packages. The outcome of the operation is then reported by a selected mechanism, for instance via the standard output, email or MOTD messages.
37
38The systemd timer unit ``dnf-automatic.timer`` will behave as the configuration file specifies (see below) with regard to whether to download and apply updates. Some other timer units are provided which override the configuration file with some standard behaviours:
39
40- dnf-automatic-notifyonly
41- dnf-automatic-download
42- dnf-automatic-install
43
44Regardless of the configuration file settings, the first will only notify of available updates. The second will download, but not install them. The third will download and install them.
45
46===================
47 Run dnf-automatic
48===================
49
50You can select one that most closely fits your needs, customize ``/etc/dnf/automatic.conf`` for any specific behaviors, and enable the timer unit.
51
52For example: ``systemctl enable --now dnf-automatic-notifyonly.timer``
53
54===========================
55 Configuration File Format
56===========================
57
58The configuration file is separated into topical sections.
59
60----------------------
61``[commands]`` section
62----------------------
63
64Setting the mode of operation of the program.
65
66``apply_updates``
67    boolean, default: False
68
69    Whether packages comprising the available updates should be applied by ``dnf-automatic.timer``, i.e. installed via RPM. Implies ``download_updates``. Note that if this is set to ``False``, downloaded packages will be left in the cache till the next successful DNF transaction. Note that the other timer units override this setting.
70
71``download_updates``
72    boolean, default: False
73
74    Whether packages comprising the available updates should be downloaded by ``dnf-automatic.timer``. Note that the other timer units override this setting.
75
76``network_online_timeout``
77    time in seconds, default: 60
78
79    Maximal time dnf-automatic will wait until the system is online. 0 means that network availability detection will be skipped.
80
81``random_sleep``
82    time in seconds, default: 0
83
84    Maximal random delay before downloading.  Note that, by default, the ``systemd`` timers also apply a random delay of up to 1 hour.
85
86.. _upgrade_type_automatic-label:
87
88``upgrade_type``
89    either one of ``default``, ``security``, default: ``default``
90
91    What kind of upgrades to look at. ``default`` signals looking for all available updates, ``security`` only those with an issued security advisory.
92
93----------------------
94``[emitters]`` section
95----------------------
96
97Choosing how the results should be reported.
98
99.. _emit_via_automatic-label:
100
101``emit_via``
102    list, default: ``email, stdio, motd``
103
104    List of emitters to report the results through. Available emitters are ``stdio`` to print the result to standard output, ``command`` to send the result to a custom command, ``command_email`` to send an email using a command, and ``email`` to send the report via email and ``motd`` sends the result to */etc/motd* file.
105
106``system_name``
107    string, default: hostname of the given system
108
109    How the system is called in the reports.
110
111---------------------
112``[command]`` section
113---------------------
114
115The command emitter configuration. Variables usable in format string arguments are ``body`` with the message body.
116
117``command_format``
118    format string, default: ``cat``
119
120    The shell command to execute.
121
122``stdin_format``
123    format string, default: ``{body}``
124
125    The data to pass to the command on stdin.
126
127---------------------------
128``[command_email]`` section
129---------------------------
130
131The command email emitter configuration. Variables usable in format string arguments are ``body`` with message body, ``subject`` with email subject, ``email_from`` with the "From:" address and ``email_to`` with a space-separated list of recipients.
132
133``command_format``
134    format string, default: ``mail -Ssendwait -s {subject} -r {email_from} {email_to}``
135
136    The shell command to execute.
137
138``email_from``
139    string, default: ``root``
140
141    Message's "From:" address.
142
143``email_to``
144    list, default: ``root``
145
146    List of recipients of the message.
147
148``stdin_format``
149    format string, default: ``{body}``
150
151    The data to pass to the command on stdin.
152
153-------------------
154``[email]`` section
155-------------------
156
157The email emitter configuration.
158
159``email_from``
160    string, default: ``root``
161
162    Message's "From:" address.
163
164``email_host``
165    string, default: ``localhost``
166
167    Hostname of the SMTP server used to send the message.
168
169``email_to``
170    list, default: ``root``
171
172    List of recipients of the message.
173
174------------------
175``[base]`` section
176------------------
177
178Can be used to override settings from DNF's main configuration file. See :doc:`conf_ref`.
179