gentoo-update 0.2.3

Gentoo Linux updater

Gentoo Updater

:warning: Important Update: Version 0.2.2 introduces breaking changes. The CLI has been completely rewritten and now features a subcommands structure. Please review the updated README below to understand the changes and ensure a smooth transition.

gentoo-update is a tool that automates updates on Gentoo Linux. By default it only installs security updates from GLSA, but it can also be used to update all packages on the system, i.e. @world.

This project originates from 2023 Google Summer of Code, more about it can be found in the blog post and Gentoo Forums.

gentoo-update has 3 main modules - updater, parser and notifier. Updater runs the update script and creates a log file. Parser reads the log file and composes a post-upgrade report which notifier then sends via email, IRC bot or mobile app.

Feature List

• updater
  • update security patches from GLSA by default, and optionally update @world
  • insert additional flags to @world update
  • do not start the update if available disk space is lower than a certain threshold
  • estimate update time
  • show package list before the update
• parser
  • show update status (success/failure) in the report
  • show package info after successful update: ebuilds, blocks, uninstalls etc.
  • detect different errors during an update
    • blocked Packages
    • USE flag conflicts
    • issues with Licenses
    • network issues during an update
    • OOM during an update
  • show disk usage before/after an update
• notifier
  • send update report via IRC bot
  • send update report via email using SendGrid
  • send update report via email using local relay
  • send update report via mobile app
  • send a short report with only the update status instead of a full report
• general
  • CLI: add option to choose from which log file to generate a report
  • CI/CD pipeline that will run gentoo_update on newly published stage3 Docker containers
  • comprehensive set of unit tests

Installation

gentoo-update is in GURU overlay, and can be installed using emerge. First, enable the overlay:

emerge --ask app-eselect/eselect-repository
eselect repository enable guru
emerge --sync

All packages in GURU overlay need an ~arch keyword. For example, on amd64 architecture add it using:

echo 'app-admin/gentoo_update ~amd64' > /etc/portage/package.accept_keywords/gentoo_update

and then install it:

emerge --ask app-admin/gentoo_update

Alternatively, it can be installed with pip in a virtual environment:

python -m venv gentoo_update
source gentoo_update/bin/activate
python -m pip install gentoo_update

Usage

The updater creates a subdirectory in Portage's default PORTAGE_LOGDIR located at /var/log/portage/gentoo-update. However, if this variable is set to a different value in make.conf, it will use the new location instead of the default.

Here are some usage examples:

• Basic security update

gentoo-update update

• Full system update with extra update parameters

gentoo-update update -m full -a "--color=y --keep-going --exclude=glibc"

• Full system update, show elogs and news

gentoo-update update -m full -l -n

• Read last update report:

gentoo-update report

• Show the last 3 logs filenames, and generate a report for one of it:

# gentoo-update report -o 3
The last 3 log file filenames
log_2023-09-23-09-19
log_2023-10-02-20-19
log_2023-10-07-13-14
# gentoo-update report -r log_2023-10-02-20-19
==========> Gentoo Update Report <==========
update status: SUCCESS
......

• Send the last update report to an IRC channel:

export IRC_CHANNEL="#<irc_channel_name>"
export IRC_BOT_NICKNAME="<bot_name>"
export IRC_BOT_PASSWORD="<bot_password>"
gentoo-update report -s irc

• Send the last update report via email:

# install Sengrid library
# need to unmask these packages: dev-python/sendgrid, dev-python/python-http-client, dev-python/starkbank-ecdsa
emerge --ask dev-python/sendgrid

# export token and other info via env variables
export SENDGRID_TO='<to_address>'
export SENDGRID_FROM='<from_address>'
export SENDGRID_API_KEY='<api_key>'

# send the latest report, or a specific one
gentoo-update report -s email
gentoo-update report -r <log_name> -s email

Help

The detailed explanation of command flags can be found in CLI's help message:

gentoo-update --help

Information on testing can be found in tests directory readme.

To get help or request additional features feel free to create an issue in this GitHub repo. Or just contact me directly via email at [e-mail] or on IRC. I am also in most of the #gentoo IRC groups and my nick there is #LabBrat.