Introduction
This article will go through the basic usage of gentoo_update CLI
tool and the mobile app.
But before that, here is a demo of this project:
⚠️ CLI was rewritten in version 0.2.2 and the video is slightly outdated
Commands in this article were updated to the new CLI standard
Video will be updated soon 😼
gentoo_update CLI App
Installation
gentoo_update is available in GURU overlay and in PyPI.
Generally, installing the program from GURU overlay is the preferred method,
but PyPI will always have the most recent version.
Enable GURU and install with emerge:
# enable the repository and sync package tree
eselect repository enable guru
emerge --sync
# unmask package, since all packages in GURU are considered unstable
echo 'app-admin/gentoo_update ~amd64' > /etc/portage/package.accept_keywords/gentoo_update
# install
emerge --ask app-admin/gentoo_update
Alternatively, install from PyPI with pip:
python -m venv .venv_gentoo_update
source .venv_gentoo_update/bin/activate
python -m pip install gentoo_update
Update
gentoo_update provides 2 update modes - full and security. Full mode updates @world,
and security mode uses glsa-check to find security patches, and installs them if something
is found.
By default, when run without flags security mode is selected:
gentoo-update update
To update @world, run:
gentoo-update update --update-mode full
Full list of available parameters and flags can be accessed with the --help flag.
Further examples are detailed in the repository’s
readme file.
Once the update concludes, a log file gets generated at
/var/log/portage/gentoo_update/log_<date> (or whatever $PORTAGE_LOGDIR is set to).
This log becomes the basis for the update report when the report subcommand is used,
transforming the log details into a structured update report.
Send Report
The update report can be sent through three distinct methods: IRC bot, email, or mobile app.
IRC Bot Method
Begin by registering a user on an IRC server and setting a nickname as outlined in the
documentation.
After establishing a chat channel for notifications,
define the necessary environmental variables and execute the following commands:
export IRC_CHANNEL="#<irc_channel_name>"
export IRC_BOT_NICKNAME="<bot_name>"
export IRC_BOT_PASSWORD="<bot_password>"
gentoo-update report --send-report irc
Email via Sendgrid
To utilize Sendgrid, register for an account and generate an
API key).
After installing the Sendgrid Python library from GURU,
save the API key in the environmental variables and use the commands below:
emerge --ask dev-python/sendgrid
export SENDGRID_TO='recipient@email.com'
export SENDGRID_FROM='sender@email.com'
export SENDGRID_API_KEY='SG.****************'
gentoo-update report --send-report email
Email via local relay
gentoo-update works well with existing email relaying tools, such as msmtp.
Detailed guide on how to set it up can be found here.
After relay is up, output from the app can be piped to it like so:
echo -e "Subject: Gentoo Update Report\n\n$(gentoo-update report)" | msmtp -a default <target-email>@gmail.com
Notifications can also be sent via the mobile app. Details on this method will be elaborated in the following section.
gentoo_update Mobile App
Installation
Mobile app can either be installed from GitHub or Google Play Store.
Play Store
App can be found by searching gentoo_update in the Play Store, or by using
this link.
Manual Installation
For manual installation on an Android device, download the APK file from
Releases
tab on GitHub. Ensure you’ve enabled installation from
Unknown Sources
before proceeding.
Usage
The mobile app consists of three screens: Login, Reports, and Profile.
Upon first use, users will see the Login screen. To proceed, select the Anonymous Login button. This action generates an account with a unique user ID and token, essential for the CLI to send reports.
The Reports screen displays all reports sent using a specific token. Each entry shows the update status and report ID. For an in-depth view of any report, simply tap on it.
On the Profile screen, users can find their 8-character token,
which needs to be saved as the GU_TOKEN variable on the Gentoo instance.
This screen also shows the AES key status, crucial for decrypting the
client-side token as it’s encrypted in the database.
To log out, tap the Sign Out button.
Note: Since only Anonymous Login is available, once logged out,
returning to the same account isn’t possible.
Contacts
Preferred method for getting help or requesting a new feature for both CLI and mobile apps is by creating an issue in Github:
- gentoo_update CLI issues page
- Mobile app issues page
Or just contact me directly via labbrat_social@pm.me and IRC. I am in most of the #gentoo IRC groups and my nick is #LabBrat.