.. _security_updates: **************** Security Updates **************** XiVO, MDS and XiVO CC are shipped with a configuration for automatic Debian security updates, through the ``xivo-security-updates`` package which pulls in ``unattended-upgrades`` and ``needrestart``. **Automatic security updates are enabled by default on XiVO CC, and disabled by default on XiVO and MDS.** When enabled, only packages coming from the Debian security repository are installed. XiVO, PostgreSQL and Docker packages, Debian point releases and ``stable-updates`` packages are never installed automatically. Enable or disable security updates ================================== #. Create :file:`/etc/apt/apt.conf.d/99xivo-local` with: * on XiVO and MDS, to enable them:: APT::Periodic::Unattended-Upgrade "1"; * on XiVO CC, to disable them:: APT::Periodic::Unattended-Upgrade "0"; #. When enabled, optionally adapt the rest of the configuration: the :ref:`maintenance window `, the :ref:`alert mail ` and the :ref:`reboot policy `. Check the result as described in :ref:`security_updates_check`. Behavior once enabled ===================== * Security updates are installed every Monday at 21:30, with a random delay of up to 30 minutes. A machine that is off during this window waits for the next one. * The machine never reboots automatically. When a kernel update is installed, :file:`/var/run/reboot-required` and :file:`/var/run/reboot-required.pkgs` are created. * No service is restarted automatically. ``needrestart`` only lists the services still running on an upgraded library; they must be restarted manually. A :ref:`dedicated mail ` names them. * Unused old kernels are removed automatically. No other package is removed automatically. * When updates are installed, a mail is sent to ``root`` and the result is logged to syslog. Whether security updates are enabled or not, ``xivo-upgrade``, ``xivocc-upgrade`` and ``mds-upgrade`` ensure ``needrestart`` runs in list-only mode: they never ask about service restarts and never restart a service by themselves. Configuration files =================== The following files are shipped by ``xivo-security-updates`` unless stated otherwise, and are **overwritten on every upgrade**. They must not be edited: * :file:`/etc/apt/apt.conf.d/52xivo-unattended-upgrades` * :file:`/etc/apt/apt.conf.d/53xivocc-unattended-upgrades` (XiVO CC only, shipped by ``xivocc-installer``) * :file:`/etc/needrestart/conf.d/50-xivo.conf` * :file:`/etc/systemd/system/apt-daily-upgrade.timer.d/50-xivo.conf` * :file:`/etc/unattended-upgrades/plugins/xivo_restart_notification.py` Put your changes in the following files instead, which are never written by the package: * :file:`/etc/apt/apt.conf.d/99xivo-local` * :file:`/etc/needrestart/conf.d/99-local.conf` * the :file:`override.conf` created by ``systemctl edit apt-daily-upgrade.timer`` .. _security_updates_mail: Change the alert mail --------------------- Add to :file:`/etc/apt/apt.conf.d/99xivo-local`:: Unattended-Upgrade::Mail "admin@example.com"; To receive a mail only when an update fails, also add:: Unattended-Upgrade::MailReport "only-on-error"; The :ref:`services to restart mail ` goes to the same address, and is not affected by ``MailReport``. .. _security_updates_restart_mail: Services to restart mail ------------------------ After security updates are installed, if some services still run on an upgraded library, an additional mail is sent with the subject ``[] Services to restart after security upgrade``. It contains: * the upgraded packages, * the services to restart, * the commands to restart them, for example ``systemctl restart asterisk.service xivo-dird.service``. Entries that cannot be restarted with ``systemctl``, such as ``systemd-manager``, are given with their ``needrestart`` script, for example :file:`/etc/needrestart/restart.d/systemd-manager`. No mail is sent when no service needs a restart. A pending kernel update is not reported in this mail, see :file:`/var/run/reboot-required` instead. Services that are not restarted stay listed: the mail is sent again on every later run that installs a security update, even an unrelated one, until they are restarted. .. warning:: Restarting a telephony service drops its ongoing calls: plan the restart. .. warning:: When ``dbus`` is listed, its command is given apart: :file:`/etc/needrestart/restart.d/dbus.service` logs out all users, including your own session, and restarts every service that depends on ``dbus``. This mail is sent to the :ref:`alert mail ` address. To disable it, empty this address in :file:`/etc/apt/apt.conf.d/99xivo-local`, which also disables the mail listing the installed updates:: Unattended-Upgrade::Mail ""; .. _security_updates_window: Change the maintenance window ----------------------------- Run ``systemctl edit apt-daily-upgrade.timer`` and write:: [Timer] OnCalendar= OnCalendar=Sat *-*-* 03:00 The empty ``OnCalendar=`` line is mandatory, otherwise the new window is added to the default one. Check the result with:: systemctl show apt-daily-upgrade.timer -p TimersCalendar .. _security_updates_reboot: Enable automatic reboot ----------------------- Activate ``Automatic-Reboot`` in :file:`/etc/apt/apt.conf.d/99xivo-local` and carefully choose a reboot time:: Unattended-Upgrade::Automatic-Reboot "true"; Unattended-Upgrade::Automatic-Reboot-Time "03:00"; .. warning:: A reboot drops all ongoing calls. Exclude a package ----------------- Add to :file:`/etc/apt/apt.conf.d/99xivo-local`:: Unattended-Upgrade::Package-Blacklist { "openssh-"; }; Entries are regular expressions matched against the package name. .. warning:: Do not exclude ``linux-image-``: the kernel fix would not be installed and :file:`/var/run/reboot-required.pkgs` would not report it. .. _security_updates_check: Check the configuration ======================= Show the allowed origins (a single pattern, with ``label=Debian-Security``):: apt-config dump Unattended-Upgrade::Origins-Pattern Show what would be installed, without installing anything:: unattended-upgrade --dry-run --debug References ========== Refer to: * `unattended-upgrade(8), Debian trixie manpage `_ * `Default unattended-upgrades configuration (50unattended-upgrades.Debian, v2.12 / trixie) `_: lists all available options and their default values. * `apt.conf(5), Debian trixie manpage `_