Portage log

The Portage log provides information when installing, updating, or removing packages.

When using emerge for building a package, it is not uncommon to notice messages coming from Portage itself. Since they may contain important information from Gentoo developers it is a good idea to read them, but often this is not immediately possible because they rapidly scroll out of the screen. This can be easily solved by enabling a Portage feature called elog, whose purpose is to save messages to disk for later review. But other logging capabilities exist as well...

Portage elog subsystem

The Portage elog subsystem keeps track of specific, ebuild-provided log messages that developers have put in the ebuilds to attract attention of the system administrator or root user. Often, these messages contain important or interesting information related to the build of said package.

Setup

Select which kind of information should be logged through the PORTAGE_ELOG_CLASSES variable. Possible values are info , warn , error , log , and qa :

PORTAGE_ELOG_CLASSES="log warn error"

Configuring for file-based storage

Portage can handle the elog events in a number of ways.

In order to save the elog events to disk, enable the save module in the PORTAGE_ELOG_SYSTEM variable:

# Warning: just 'save' won't show messages on emerging! Add 'echo' to save *AND* show.
#PORTAGE_ELOG_SYSTEM="save"
 
# Show messages after emerging *and* save
PORTAGE_ELOG_SYSTEM="echo save"

The messages will be saved in /var/log/portage/elog or in ${PORTAGE_LOGDIR}/elog if said variable is set.

In order to create per-category elog files, enable the split-elog Portage feature. It will force Portage to create category-based subdirectories of the /var/log/portage/elog location.

Additionally, to create per-category build logs, enable the split-log Portage feature. It will force Portage to create category-based subdirectories of the /var/log/portage/build location.

Script to lookup logs

When the logs are split up, it's a bit annoying to look through them one by one. Here's an example script to print them using the date:

#!/bin/bash

# This script is assuming that portage is configured to log in
# /var/log/portage/elog and that it's configured to split the logged files.
#
# If you want specific dates, run the script like so:
# GET_DATES="20230101 20230102" ./print_elog_messages.sh
#
# If you want all files to be printed, run the script like so:
# GET_ALL="true" ./print_elog_messages.sh
#
# If the script filename is different, adjust accordingly!

# Check if running as root and stop if it is.
current_user=$(whoami)
[ -z "$current_user" ] && echo "whoami returns an empty string" && exit 1
[ "$current_user" == "root" ] && echo "Don't run as root, there's no need!" && exit 1

# Set periods to check. These strings are interpreted by the "date" tool.
declare -a days=("today" "yesterday")

# Change the array to the custom dates if they're declared.
[ -n "$GET_DATES" ] && declare -a days=("$GET_DATES")

# If we're printing everything, there's no reason to loop multiple times and
# it would make sense to change the period to "all".
[ "$GET_ALL" == "true" ] && declare -a days=("all")

# Go through the periods set in the array "days" and format to find filenames
# containing YYYYmmdd, for example 20221215, since that's the format that's
# part of the filenames by default. After this, run the command cat with the
# found filenames as arguments, which adds the file contents
# to the terminal output. Remove the -n argument from cat if you don't want
# it to print the line numbers as well.
for val in ${days[@]}; do
	echo "          ===== $val ====="
	find /var/log/portage/elog -name \
		"*$([ "$GET_ALL" == "true" ] || date --date=$val +%Y%m%d)*" \
		-type f -print -exec cat -n '{}' \;
done

Configuring for e-mail

To mail logs to a recipient, enable the mail module. The mail option requires some additional variables to be set. Read /usr/share/portage/config/make.conf.example for more information.

Below, an example setup is shown which is hopefully self-explanatory:

# This will _only_ email; you may want to do "mail save" or similar instead.
PORTAGE_ELOG_SYSTEM="mail"
# First the mail-to address, then the SMTP server
PORTAGE_ELOG_MAILURI="log-intake@example.com mail.example.com"
PORTAGE_ELOG_MAILFROM="portage@$(hostname).example.com"
PORTAGE_ELOG_MAILSUBJECT="\${PACKAGE} is \${ACTION} on \${HOST}"

Another example with nullmailer or sendmail:

# This will _only_ email; you may want to do "mail save" or similar instead.
PORTAGE_ELOG_SYSTEM="mail"
# First the mail-to address, then the SMTP server
PORTAGE_ELOG_MAILURI="users@host /usr/sbin/sendmail"
PORTAGE_ELOG_MAILFROM="portage@$(hostname).example.com"
PORTAGE_ELOG_MAILSUBJECT="\${PACKAGE} is \${ACTION} on \${HOST}"

When configuring PORTAGE_ELOG_MAILURI, be aware that the port number behaves differently when STARTTLS is required.

# Syntax for PORTAGE_ELOG_MAILURI (if defined):
# address [[user:passwd@]mailserver[:port]]
# where address:    recipient address
#       user:       username for smtp auth (defaults to none)
#       passwd:     password for smtp auth (defaults to none)
#       mailserver: smtp server that should be used to deliver the mail (defaults to localhost)
#                                   alternatively this can also be the absolute path to a sendmail binary if you don't want to use smtp
#       port:       port to use on the given smtp server (defaults to 25, values > 100000 indicate that starttls should be used on (port-100000))

For example, if your mail server expects STARTTLS on port 587, you must specify 100587 in PORTAGE_ELOG_MAILURI. This triggers STARTTLS and internally maps the port to 587 with STARTTLS enabled.

Related software

The following is a list of elog related software packages:

• app-portage/elogv - Curses based utility to parse the contents of elogs.
• app-portage/elogviewer - Python based elog viewer.

Build logs

Package build logs can be saved to disk or mailed to a remote recipient, by setting variables in make.conf . This allows system administrators to review builds later.

By default, when emerge is running, Portage temporarily saves the build log of a package to /var/tmp/portage/<category>/<packagename-version>/temp/build.log . The build directory will be deleted when emerge finishes successfully, so successful build logs will be lost. If a build fails however, the logs will be retained, so the build.log will still be available for attaching to support tickets .

n.b. The build.log may be followed by an extra extension if compress-build-logs is set in FEATURES . The default PORTAGE_TMPDIR is /var/tmp , adjust path accordingly if it is set to something different in make.conf .

Always save build logs

To enable saving build logs, edit /etc/portage/make.conf and set PORTAGE_LOGDIR to a location where the log files should be stored:

PORTAGE_LOGDIR="/var/log/portage"

It is customary to choose /var/log/portage as the location for log files, because it is where the elog subsystem's elog directory would be if PORTAGE_LOGDIR has been previously empty or unset.

A number of FEATURES settings may be set in /etc/portage/make.conf which influence how Portage handles build logs:

• With binpkg-logs set, even binary package deployments will have their logs saved.
• When clean-logs is set, regular log file clean operations are executed. The command that is executed is defined by PORTAGE_LOGDIR_CLEAN and defaults to a retention of the files of 7 days.
• With split-elog set, elog notices are stored in category-named subdirectories of ${PORTAGE_LOGDIR}/elog
• WIth split-log set, build logs are stored in category-named subdirectories of ${PORTAGE_LOGDIR}/build

Until Portage version 2.3.53, PORTAGE_LOGDIR variable used to be named PORT_LOGDIR . This old name is now deprecated.

Cleaning up

When clean-logs is enabled in the FEATURES variable of /etc/portage/make.conf , Portage will execute the command defined by PORTAGE_LOGDIR_CLEAN after every build or unmerge operation. By default, the following command is used:

PORTAGE_LOGDIR_CLEAN="find \"\${PORTAGE_LOGDIR}\" -type f ! -name \"summary.log*\" -mtime +7 -delete"

When defining a custom command, do not forget to escape the PORTAGE_LOGDIR variable (or immediately hard code the right location).

Until Portage version 2.3.53, PORTAGE_LOGDIR_CLEAN variable used to be named PORT_LOGDIR_CLEAN . This old name is now deprecated.

Other Portage log files

Portage also can have log files in /var/log/emerge.log , and /var/log/emerge-fetch.log .

See also

• Elogv — a curses-based tool that parses the contents of elogs created by Portage.

External resources

• Sven Vermeulen . "Underestimated or underused: Portage (e)logging " , September 25th, 2013. Retrieved on May 30th, 2019.