portage configuration

The jc-gentoo-portage repository houses an opinionated, performance-oriented Gentoo Portage (/etc/portage) configuration.

This repository can be used as an inspiration to build a lean and fast Gentoo operating system.

Features:

Maximizes execution performance across the system by globally enabling xs, asm, orc, jit, and threads, forcing packages to use hand-written assembly routines and JIT compilation loops.
Disables telemetry and remote RPC calls by globally setting -telemetry, -geoclue, -geolocation, -cloudproviders, -google, and -gnome-online-accounts.
Optimizes Rust compiler outputs by enforcing modern instruction sets via target-cpu=native, opt-level=3, and strip=symbols.
Links long-running daemons and high-throughput parsing utilities against jemalloc to guarantee flat memory profiles and predictable multi-threaded performance during extended uptimes.
Prunes legacy hardware probing and obsolete I/O interfaces by globally disabling optical media (-cdrom, -dvd, -dvdr, -css) and deprecated X11 video rendering (-xv).
Removes documentation bloat by globally disabling -doc, -gtk-doc, and -handbook. This instructs the build system to skip the generation of extraneous HTML manuals and localized help files, reducing compilation times and the final disk footprint.
Optimizes the linker aggressively using -Wl,-O2 -Wl,--sort-common -Wl,--as-needed -Wl,-z,pack-relative-relocs to compress relocation tables, drop unused dependencies, and group global variables by alignment for faster binary loads.
Standardizes the multimedia stack exclusively on PipeWire while enforcing hardware-accelerated video decoding.
Restricts the GNOME desktop by stripping network discovery protocols from file managers (-samba, -ads, -acl).
Isolates high-load compilation processes to background resources using PORTAGE_SCHEDULING_POLICY="idle", PORTAGE_IONICE_COMMAND="ionice -c 3 \${PID}", and a custom notmpfs.conf to prevent Out of Memory errors on massive packages.
Compiles binary packages and man pages using maximum compression via BINPKG_COMPRESS_FLAGS_ZSTD="-19 -T0", utilizing all CPU threads.

Installation

Step 1: Ensure the system is set to the compatible 23.0 systemd desktop profile

eselect profile set default/linux/amd64/23.0/desktop/systemd

(This ensures that the base system dependencies, compiler configurations, and default USE flags are aligned for a modern systemd-based graphical desktop environment.)

Step 2: Install requirements

emerge -av app-portage/cpuid2cpuflags app-arch/zstd dev-vcs/git

(cpuid2cpuflags is required to detect your host processor’s hardware capabilities. zstd is installed to provide high-speed compression for Portage build operations and binary packages, and git is required to clone this repository.)

Step 3: Clone the Repository

git clone https://github.com/jamescherti/jc-gentoo-portage /etc/portage

Step 4: Run /etc/portage/scripts/init-portage

/etc/portage/scripts/init-portage

(This script creates /var/portage-notmpfs to prevent compilation failures for massive packages that run out of space when building in RAM. It also generates /etc/portage/make-local.conf, which establishes a safe, untracked location for machine-specific overrides. By default, it populates this file with a MAKEOPTS setting configured to use half of your system’s processors. Finally, the script uses the cpuid2cpuflags command to dynamically query your hardware for supported instruction sets, such as AVX2 or SSE4, and writes them to /etc/portage/package.use/00my-cpu-flags. This ensures that all subsequently compiled software is fully optimized for your specific processor.)

Step 5: Create make.profile

cd /etc/portage
ln -sf ../../var/db/repos/gentoo/profiles/default/linux/amd64/23.0/desktop/systemd make.profile

(Portage relies on the make.profile symlink to determine which system profile is currently active. Creating this link manually ensures Portage resolves the dependency graph and default variables accurately from the downloaded Gentoo repository tree.)

Step 6: Recompile GCC using this Portage configuration, which enables Profile-Guided Optimization (PGO) and Link-Time Optimization (LTO) to maximize compilation throughput

emerge -av sys-devel/gcc

Step 7: Begin customizing `/etc/portage`

Begin customizing /etc/portage to fit your specific requirements and install packages using emerge.

Repository Structure

To effectively customize this configuration, you need to understand its layout:

make.conf: The primary configuration file. It contains global compiler flags (CFLAGS, CXXFLAGS), MAKEOPTS, global USE flags, and FEATURES.
package.use/: A directory containing modular files that define USE flags on a per-package basis. Files are categorized logically (e.g., gnome, sound-server, optimize).
package.accept_keywords/: Allows the installation of specific testing or unstable packages on a stable system.
package.mask/ and package.unmask/: Used to block or allow specific package versions.

Customizing USE Flags (package.use)

The package.use/ directory is modular. You should read through the files and remove entries for software you do not intend to install. If you need a feature that is disabled globally in make.conf (like nls or bluetooth), do not enable it globally. Instead, enable it only for the specific package that requires it by creating a new entry in package.use/.

Force English

For users who don’t need localization, setting -nls, -cjk, and -ibus globally forces interfaces to English, which skips the compilation of thousands of unneeded localization files:

File: /etc/portage/package.use/00my-just-english

# Global exclusion of the Intelligent Input Bus (IBUS).
#
# Justification:
# - Performance: Prevents unnecessary background daemon processes.
# - Footprint: Eliminates complex dependencies and reduces system bloat.
# - Security: Minimizes the attack surface by removing unused system services.
#
# Note:
# This assumes that no specialized Input Method Editors (IME) are required for
# non-Latin script input. If localized language support is needed in the future,
# this flag must be re-evaluated.
*/* -ibus

# The exclusion of nls (Native Language Support) is a deliberate choice to
# simplify the dependency graph and simplify the package installation process.
# By setting USE="-nls", you instruct Portage to ignore internationalization
# libraries and omit the compilation of localized message files, ensuring that
# all software interfaces default to English. This configuration is particularly
# beneficial on Gentoo because it prevents unnecessary interactions with the
# gettext utility and significantly reduces the total number of files installed
# across your system. Consequently, your updates will finish faster, and you
# will regain valuable disk space that would otherwise be occupied by dozens of
# translation files you do not need, resulting in a cleaner and more efficient
# OS environment.
#
# cjk: cjk (Chinese, Japanese, Korean), safe to disable globally.
*/* -nls -cjk

Disable smartcard

File: /etc/portage/package.use/00my-no-smartcard

# Disabling smartcard support prevents packages like app-crypt/gnupg and
# net-misc/openssh from linking against smartcard-reading libraries.
#
# Warning: Do not apply this mask if you rely on a physical hardware token (such
# as a YubiKey or Nitrokey) for SSH authentication, GPG commit signing, or LUKS
# disk decryption.
*/* -smartcard

NVIDIA GPU

File: /etc/portage/package.use/00my-hw-gpu-nvidia

*/* VIDEO_CARDS: -* nvidia

# Opts into native NVIDIA hardware video encoding/decoding
*/* nvenc nvdec vdpau

# Enables VA-API support across applications.
*/* vaapi

Intel CPU

File: /etc/portage/package.use/00my-hw-cpu-intel

# Tells Portage to only install the microcode files necessary for the host CPU.
sys-firmware/intel-microcode hostonly

# Enables VA-API support across applications.
*/* vaapi

# Enable Intel Quick Sync Video
# Ensure every media application on the system compiles with Intel Quick Sync
# Video support if the package supports it. For a dual-GPU setup containing an
# Intel iGPU and an NVIDIA discrete card, the primary benefit is systematic
# workload isolation. It allows offloading everyday video decoding and
# background encoding tasks across all applications (such as media players,
# transcoders, and broadcasting tools) directly to the Intel processor. This
# strategy keeps the NVIDIA card completely free from media processing overhead,
# reserving its full hardware capacity for demanding tasks like 3D rendering or
# compute workloads, while avoiding the need to configure flags on a per-package
# basis.
*/* qsv

Intel Integrated graphics

File: /etc/portage/package.use/00my-hw-intel-integrated-graphics

*/* VIDEO_CARDS: -* intel

# Enables VA-API support across applications. This allows the Intel integrated GPU
# to handle hardware acceleration paths natively via Intel Quick Sync.
*/* vaapi

# Enable Intel Quick Sync Video
# Ensure every media application on the system compiles with Intel Quick Sync
# Video support if the package supports it. For a dual-GPU setup containing an
# Intel iGPU and an NVIDIA discrete card, the primary benefit is systematic
# workload isolation. It allows offloading everyday video decoding and
# background encoding tasks across all applications (such as media players,
# transcoders, and broadcasting tools) directly to the Intel processor. This
# strategy keeps the NVIDIA card completely free from media processing overhead,
# reserving its full hardware capacity for demanding tasks like 3D rendering or
# compute workloads, while avoiding the need to configure flags on a per-package
# basis.
*/* qsv

# Disable VDPAU backend
*/* -vdpau

Intel audio + USB audio

File: /etc/portage/package.use/00my-hw-audio-intel

# Intel audio + USB audio
*/* ALSA_CARDS: -* hda-intel usb-audio

Scanner: Disabling all sane backends

For users who use scanners requiring proprietary drivers, such as those from Brother, it is recommended to disable all SANE backends.

File: /etc/portage/package.use/00my-hw-scanner

# Disable all sane backends
*/* SANE_BACKENDS: -*

systemd-boot and dracut for sys-kernel/gentoo-kernel or sys-kernel/gentoo-kernel-bin users

The systemd-boot makes installkernel manage bootctl entries dynamically using the Boot Loader Specification (BLS). This creates individual menu options for each installed kernel version, providing an automatic fallback if a new kernel fails to boot.

First, edit /etc/kernel/install.conf and add the following lines to define the kernel installation layout:

layout=bls
initrd_generator=dracut
uki_generator=none

Next, edit /etc/portage/package.use/00my-systemd-boot to apply the required USE flags. This enables dracut and systemd-boot for installkernel and sets the dist-kernel flag globally. Add the following lines:

sys-kernel/installkernel dracut systemd-boot
sys-apps/systemd boot

# When dist-kernel is set, Portage will automatically trigger Dracut to
# build the initramfs and automatically rebuild out-of-tree modules
# (like nvidia-drivers) whenever a new sys-kernel/gentoo-kernel is installed.
*/* dist-kernel

Dracut + NVIDIA: Force NVIDIA Driver Inclusion in the Early Boot Sequence

By default, Dracut may omit out-of-tree drivers during initramfs generation. Force the inclusion of the essential NVIDIA kernel components, including the core driver, modesetting controls, unified virtual memory, and direct rendering manager layers, directly into the early boot image. This step also ensures the open-source Nouveau driver is explicitly omitted to prevent conflicts.

First, edit /etc/dracut.conf.d/nvidia.conf and add the following lines to bind the required drivers:

add_drivers+=" nvidia nvidia_modeset nvidia_uvm nvidia_drm "
omit_drivers+=" nouveau "

Next, regenerate all of your initramfs images to apply the configuration. Run your bootloader or kernel management tool to trigger the rebuilding process, or execute your system’s standard initramfs generation utility with the force flag to ensure the changes are baked into the early boot sequence.

Customizing /etc/portage/make-local.conf

The jc-gentoo-portage repository tracks the primary make.conf file via Git. Modifying make.conf directly to add hardware specifics will cause merge conflicts whenever git pull is executed to update the repository with upstream changes.

To prevent this, the provided make.conf automatically sources /etc/portage/make-local.conf at the end of its execution. By placing all system-specific overrides (such as GOAMD64, MAKEOPTS, or CFLAGS) inside make-local.conf, these settings successfully override the global defaults while keeping the Git working tree clean. This allows upstream updates to be applied without manual conflict resolution.

Open /etc/portage/make-local.conf and modify the variables to match your system resources. For example, modify MAKEOPTS based on your CPU core count and available RAM. A common rule is -jN -lN where N is your logical CPU core count.

Go Compiler Optimizations (GOAMD64)

The GOAMD64 environment variable specifies the microarchitecture level of the amd64 (x86-64) architecture that the Go compiler targets. Setting GOAMD64="v3" inside /etc/portage/make-local.conf forces the Go compiler to generate machine code leveraging newer CPU instructions, such as AVX2, BMI1, BMI2, F16C, FMA, LZCNT, MOVBE, and OSXSAVE.

While C and C++ compiler optimizations are managed via CFLAGS and CXXFLAGS (e.g., -march=x86-64-v3), the Go compiler ignores these flags. Many modern utilities packaged in Gentoo are written in Go (including Docker, Kubernetes, and Terraform). When Portage builds these packages from source, the ebuilds read Go-specific environment variables.

To determine the correct target level for a specific hardware setup, processor capabilities must be inspected. CPU flags can be checked by running grep -m 1 '^flags' /proc/cpuinfo and matching them against the following levels:

v1: The baseline x86-64 architecture. This is appropriate for distributing compiled binaries to unknown hardware or for processors older than 2008.
v2: Requires popcnt and sse4_2. This is intended for older processors released around 2008 to 2013, such as Intel Nehalem or AMD Jaguar.
v3: Requires avx2. This is intended for modern processors released after 2014, such as Intel Haswell or AMD Excavator.
v4: Requires avx512f. This is intended for the latest enterprise or high-end desktop processors, such as Intel Skylake-X or AMD Zen 4.

Once the highest supported level is identified, the variable can be appended to the local configuration:

echo 'GOAMD64="v3"' >> /etc/portage/make-local.conf

Explicitly declaring GOAMD64="v3" in /etc/portage/make-local.conf ensures Portage applies hardware-specific optimizations to all compiled Go binaries. If this variable is omitted, the Go compiler defaults to v1, generating universally compatible but unoptimized code. A higher tier should only be set if the target processor explicitly supports the required instruction sets.

FEATURES: buildpkg

If you manage multiple identical or similar Gentoo machines, use FEATURES="buildpkg" on your fastest machine to compile binaries once, then distribute them to your other machines using emerge --usepkg.

echo 'FEATURES="$FEATURES buildpkg"' >> /etc/portage/make-local.conf

Other customizations

Install the latest testing kernel

Unmask the testing versions (~amd64) of the Gentoo distribution kernels. This allows Portage to look past the stable tree and fetch the latest upstream kernel updates.

First, edit /etc/portage/package.accept_keywords/00my-latest-gentoo-kernel and add the following lines to accept the testing keywords:

sys-kernel/gentoo-kernel-bin ~amd64
sys-kernel/gentoo-kernel ~amd64
virtual/dist-kernel ~amd64

Next, run your standard package upgrade command to pull in the new kernel version, and use your system’s kernel selection utility to set the newly installed kernel as the default.

Then run:

emerge --ask --with-bdeps=y --update --deep --changed-use @world

Finally, use eselect kernel list and eselect kernel set <version> to select the newly installed kernel.

Temporary File Systems (tmpfs) Optimization

Gentoo compiles the majority of software from source code via Portage, a process that generates a significant volume of intermediate build artifacts. By default, Portage writes these temporary files to the physical storage device at /var/tmp/portage.

Shifting high-volume compilation I/O operations into memory substantially reduces solid-state drive wear while exploiting the superior read and write speeds of RAM to eliminate storage bottlenecks.

To extend hardware longevity and minimize extraneous disk writes across the entire operating environment, offload the standard system temporary directories to RAM. Append these corresponding entries to /etc/fstab:

tmpfs    /tmp        tmpfs    rw,nodev,nosuid,size=8G    0 0
tmpfs    /var/tmp    tmpfs    rw,nodev,nosuid,size=8G    0 0

Configuring the following entry in /etc/fstab mounts the directory as a tmpfs allocation. The size parameter establishes a hard limit on memory consumption to prevent resource exhaustion during the build process.

tmpfs    /var/tmp/portage     tmpfs     size=16G,uid=portage,gid=portage,mode=775,nosuid,noatime,nodev    0  0

Storage Optimization & Encryption (LUKS / SSD)

For systems utilizing an encrypted root filesystem on solid-state storage (SSD/NVMe), specialized kernel parameters are required to maintain storage performance.

By default, dm-crypt/LUKS containers block TRIM requests for security reasons, which can degrade SSD performance and longevity over time. If sys-kernel/genkernel is used to manage the initramfs, append the following parameter to the bootloader kernel command line (e.g., in grub.cfg or refind.conf):

root_trim=yes

This parameter instructs the initramfs script to pass the --allow-discards option to cryptsetup during the initial phase of the boot sequence. This allows the root filesystem to successfully pass discard/TRIM commands through the encryption layer down to the underlying physical controller.

This parameter is unique to genkernel. If the initramfs is built using sys-kernel/dracut, this flag will be ignored; standard Dracut configuration or the rd.luks.options=discard kernel parameter must be used instead.

Enabling TRIM on an encrypted device exposes disk usage patterns and filesystem layout to an attacker with physical access to the drive. For standard operational profiles, the performance and hardware longevity benefits outweigh this minor metadata leakage.

Using the Ninja Build System

Ninja is a efficient build system that evaluates dependencies rapidly and execute multiple build tasks concurrently. Replacing standard make with Ninja provides performance improvements during the compilation phase, particularly for large C and C++ projects.

Benefits of using Ninja:

Faster dependency resolution and startup time.
Improved management of parallel build processes.
Noticeably reduced compilation times for heavy packages.

To configure Portage to use Ninja globally for CMake-based ebuilds, you must install the package and declare it as the default generator.

Install Ninja:

emerge -av dev-build/ninja

Append the generator variable to your local configuration:

echo 'CMAKE_MAKEFILE_GENERATOR="ninja"' >> /etc/portage/make-local.conf

This configuration ensures that any package using CMake will use Ninja instead of traditional make to process the build.

Maintenance

After applying this configuration or making your own modifications, you must instruct Portage to evaluate the dependency tree and apply the changes to your live system.

Apply the new USE flags and update the system:

emerge --ask --verbose --update --deep --newuse @world

Then remove orphaned dependencies that are no longer required:

emerge --ask --depclean

License

The jc-gentoo-portage files were written by James Cherti and are distributed under terms of the MIT license.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

A Shell Script that Configures the GNOME Desktop Programmatically

License

The jc-gnome-settings repository provides the jc-gnome-settings.sh script, which holds James Cherti’s settings to customize the GNOME desktop environment, including window management, notifications, desktop behavior, keyboard settings, and more, to enhance the user experience.

Requirements

gsettings

Usage

Clone the repository:

git clone https://github.com/jamescherti/jc-gnome-settings

Navigate to the repository directory:

cd jc-gnome-settings

Run the script to configure GNOME:

./jc-gnome-settings.sh

Author and License

The jc-gnome-settings tool has been written by James Cherti and is distributed under terms of the MIT license.

A Shell Script that Automates XFCE Desktop Configuration

License

The jc-xfce-settings project provides the jc-xfce-settings.sh script, which holds James Cherti’s settings to customize the XFCE desktop environment, including window management, notifications, desktop behavior, keyboard settings, and more, to enhance the user experience.

(The jc-xfce-settings.sh script was created with the help of watch-xfce-xfconf)

Requirements

The XFCE Desktop Environment,
and xfconf-query utility that is part of XFCE.

Usage

Clone the repository:

git clone https://github.com/jamescherti/jc-xfce-settings

Navigate to the repository directory:

cd jc-xfce-settings

Run the script to configure XFCE:

./jc-xfce-settings.sh

Features

Title Bar Customization: Simplifies button layout for easier window management.
Font and Display Settings: Enables anti-aliasing, hinting, and configures RGBA rendering.
File Manager (Thunar): Optimizes behavior for thumbnailing, single-click navigation, and directory-specific settings.
Keyboard Tweaks: Adjusts key repeat delay and rate for a smoother typing experience.
Notifications: Sets notification theme, position, and timeout duration.
Desktop Behavior: Disables unnecessary desktop icons and menus for a cleaner workspace.
Session Management: Disables session saving for a faster logout experience.
Window Management: Configures snapping, shadow effects, focus behavior, and workspace interactions.
Compositor Settings: Adjusts transparency and disables unneeded effects.

Author and License

The jc-xfce-settings tool has been written by James Cherti and is distributed under terms of the MIT license.

update-iptables – A low-level Linux firewall for advanced users

The update-iptables script implements a firewall for managing network traffic and routing.

It supports a modular configuration model through drop-in scripts located in /etc/update-iptables.d/. Each file is a shell script executed sequentially during firewall initialization.

This low-level firewall script is intended for Linux system administrators who require precise control over packet states, network address translation, and custom routing chains. Rules are defined directly through iptables without the abstraction layers commonly introduced by modern firewall management tools.

If this low-level firewall proves useful, please support the project by ⭐ starring update-iptables on GitHub, helping more developers discover it.

Requirements

bash
iptables (iptables, ip6tables, and iptables-save)
Optional: diff and cmp

Installation

Install update-iptables system-wide with the following commands:

git clone https://github.com/jamescherti/update-iptables
cd update-iptables
sudo ./install.sh
````

Enable the firewall service at boot:

systemctl enable update-iptables


## Usage

By default, `update-iptables` **blocks all traffic**, including input, output, and forwarding, except for connections on the loopback interface.

### Adding Custom Rules

Custom rules can be added by creating a `.rules` script in the `/etc/update-iptables.d/` directory. Files in this directory are sourced sequentially during firewall initialization, allowing modular and organized rule management.

Create a new file in `/etc/update-iptables.d/` with a descriptive name, ending with `.rules`. For example:

```bash
sudo nano /etc/update-iptables.d/10-my-rules.rules

Add your iptables commands in the file. For example:

# Set the default policy of the INPUT, OUTPUT, and FORWARD chains to DROP. This
# establishes a default-deny firewall policy for both IPv4 and IPv6.
ui_set_drop_policy

# Drop any traffic with an INVALID state match and TCP packets with illogical
# flag combinations, such as SYN and FIN or SYN and RST being set
# simultaneously.
ui_drop_invalid

# Accept traffic belonging to already established connections or packets related
# to them. This rule ensures that once a connection has been permitted by a
# specific rule, all subsequent packets for that session are processed quickly
# and efficiently without re-evaluating the entire rule set.
#
# (Add UI_FORWARD if the system is acting as a router, gateway, or host for
# virtual machines and containers, such as Docker, libvirt, that require network
# access.)
ui_allow_established UI_INPUT UI_OUTPUT

# Allow all legitimate internal traffic on the 'lo' interface,
# which is required for local applications and services to communicate.
# This function also drops packets on non-loopback interfaces that spoof loopback
# IP addresses (127.0.0.0/8 and ::1/128) to protect the system from
# external manipulation and network pollution.
ui_allow_loopback

# Accept all incoming ICMP echo requests, also known as pings. Only the first
# packet will count as new, the others will be handled by the RELATED,
# ESTABLISHED rule. Since the computer is not a router, no other ICMP with
# state NEW needs to be allowed.
ui_input_allow_ping

# Permit outbound network traffic for a specific list of local system users.
# (Usernames that do not exist on the host are silently ignored.)
ui_allow_output_users systemd-timesync sockd proxy root alpm

# SSH
iptables -A UI_INPUT -p tcp --dport 22 -m conntrack --ctstate NEW,ESTABLISHED -j ACCEPT

Reload the firewall to apply the new rules:

sudo systemctl restart update-iptables

The new rule will be integrated automatically, respecting the modular structure of the firewall.

Features

Low-level iptables control: Defines firewall rules directly using iptables and ip6tables without intermediate management layers.
Modular configuration: Supports drop-in rule scripts located in /etc/update-iptables.d/. Files with the .rules extension are sourced sequentially, allowing incremental and organized firewall configuration.
Stateful firewall rules: Uses connection tracking (conntrack) to manage NEW, ESTABLISHED, RELATED, and INVALID packet states.
IPv4 and IPv6 support: Applies rules consistently to both iptables and ip6tables.
Custom rule chains: Introduces dedicated chains (UI_INPUT, UI_OUTPUT, UI_FORWARD, UI_PREROUTING, UI_POSTROUTING) to isolate managed rules from system chains.
Per-user network policies: Allows outgoing traffic to be restricted or permitted based on the Unix user ID using the owner module.
Secure default policy: Uses restrictive default policies (DROP) until rules are successfully applied.
Automatic rule validation and rollback behavior: In case of failure during execution, all policies are locked down to DROP to avoid leaving the system in an insecure state.
Packet logging support: Optional logging chains record packets passing through firewall chains with rate limiting.
Spoofing and malformed packet protection: Drops packets with invalid connection states, suspicious TCP flag combinations, and spoofed source addresses.
Localhost protection rules: Ensures correct handling of loopback traffic while preventing spoofed loopback packets from external interfaces.
Rule diff inspection: Saves firewall rules before and after execution and optionally displays a diff when changes occur.
Verbose execution mode: Displays executed iptables commands when verbose mode is enabled.
Safe rule flushing: Supports cooperative flushing of managed chains or full firewall reset through command-line options.

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program.

The Importance of Backups: Why Failing to Create or Test Them Leads to Regret

Data loss is an inevitable reality in the digital age. It is not a matter of “if,” but “when.” Whether you’re managing critical infrastructure for a large enterprise or simply storing personal documents, photos, and legal files on your own computer, the risk of data loss is ever-present. Despite this, many people and organizations fail to prioritize backups until it is too late.

Throughout my career as an IT specialist, I have witnessed this problem repeatedly. The pattern is always the same: individuals and companies lose data, panic ensues, and attempts are made to recover what could have been easily protected with minimal cost and effort.

Data loss

On a daily basis, I encounter numerous instances of data loss across various sectors. Companies pay for bare-metal servers or cloud compute instances to run their production workloads, but when these systems crash, experience filesystem corruption, or are compromised by security breaches, the response is typically one of outrage. Support tickets are submitted with complaints that their data is lost, with no backups, no snapshots, and no contingency plan in place.

This issue is not exclusive to large enterprises. Consider personal devices. How many individuals store years of important tax records, legal documents, irreplaceable family photos, or critical work files on their laptops, with no backup strategy whatsoever? Hardware failure, malware attacks, accidental deletion, theft, and simple human error can result in irreversible data loss in an instant.

Some of the cases I handled…

The cases I handled professionally can be truly staggering. For example, I worked with a client paying tens of thousands of dollars per month for a bare-metal server to host highly sensitive data, yet they had no backup strategy in place. When hardware failure inevitably occurred, the result was outrage, threats of legal action, and attempts to assign blame. Unfortunately, without a backup policy, disaster recovery plan, and monitoring system in place, these situations are often beyond repair.

In this particular instance, I worked closely with the client to establish a comprehensive backup procedure. This involved selecting an appropriate backup solution adapted to their infrastructure, setting up regular backups, and ensuring the backups were stored securely and off-site. Additionally, we implemented a monitoring system to alert the client to any potential issues before they became critical. The result is now a much more resilient system, where data loss is no longer a risk, and the client has a clear disaster recovery plan in place.

To make matters worse, I’ve witnessed scenarios where the financial cost of data loss has reached tens of thousands of dollars per day. This is not a matter of insufficient resources. It’s a matter of misplaced priorities and negligence. For a fraction of the cost of their monthly expenses, these individuals and organizations could have secured a robust backup solution that would have prevented the catastrophe.

The reality is simple: backups are inexpensive. Data loss, on the other hand, is costly, stressful, and often irreversible. The barriers to implementing reliable, automated backup solutions today are negligible. Whether you choose cloud storage, external drives, remote servers, the tools are readily available, and there is no excuse for neglecting to protect your data.

Restores have to be tested

It is a common misconception that having a backup in place means data is secure, simply because a tool reports, “Your backups were successful.” However, the true test of a backup’s reliability occurs when it is needed most, during a restore attempt. This is when many realize that despite the “successful” alert, the backup may be incomplete, corrupted, or otherwise unusable.

It is concerning that many individuals in technical roles lack the necessary expertise to properly set up and manage infrastructure within an organization. While foundational knowledge is readily available through online resources, there is a tendency for some to set up systems with minimal effort, a few clicks, and the system is presumed to be functioning. However, the true measure of proficiency in IT infrastructure lies not in the ability to configure a system, but in the ability to resolve issues when things inevitably fail.

Conclusion

If you are reading this, I encourage you to take a moment to assess your backup strategy. If you do not have one, create one today. If you already have a backup system in place, ensure that it is functioning correctly. Whether you are managing a business with critical client data or simply safeguarding personal files on your laptop, the importance of backups cannot be overstated.

Feel free to share your own experiences with data loss, lessons learned, or helpful backup solutions in the comments.

Pathaction | A universal Makefile for any file in the filesystem: Rule-driven commands for any file or directory

The pathaction tool is a flexible command-line utility for running commands on files and directories. Pass a file path as an argument, and the tool handles the rest, whether you are working with code, media, or configurations.

Think of pathaction like a Makefile for any file or directory in the filesystem. It uses a .pathaction.yaml file to determine which command to run, and you can use Jinja2 templating to make those commands dynamic. You can also use tags to define multiple actions for the exact same file type. For example, you can set up one tag to run a script, another to debug it, and a third to run a linter.

This tool is built for software engineers who manage multiple projects across diverse environments. It eliminates the cognitive load of switching between different build tools, environment configurations, and deployment methods. Run a single unified command on any file and trust that it gets handled correctly.

If this tool helps your workflow, please show your support by ⭐ starring pathaction on GitHub and sharing it on your website, blog, Mastodon, Reddit, X, LinkedIn, or other social media platforms to help more Git users discover its benefits.

Example

You can execute a file with the following commands:

pathaction -t main file.py

Or:

pathaction -t edit another-file.jpg

The -t option specifies the tag, allowing you to apply a tagged rule.

Here is an example of what a .pathaction.yaml rule-set file looks like:

---
actions:
  - path_match: "*.py"
    tags: main
    command:
      - "python"
      - "{{ file }}"

  - path_match: "*.jpg"
    tags:
      - edit
      - show
    command: "gimp {{ file|quote }}"

There are many ways to match paths, including using regular expressions and MIME types. See below for more details.

Editor Plugins

Emacs: pathaction.el
Vim: vim-pathaction
Other editors: Contributions are welcome.

Installation

Here is how to install pathaction using pip:

pip install --user pathaction

The pip command above will install the pathaction executable in the directory ~/.local/bin/.

(Python requirements: jinja2, schema, PyYAML.)

Optional Dependencies

The pathaction CLI offers optional dependencies that extend its functionality. These extras can be installed according to environment requirements.

Colored Terminal Output (colors): Installs colorama to provide consistent cross-platform ANSI color support. This enhances the readability of standard output and error messages.

pip install "pathaction[colors]"

Custom Process Title (proctitle): Installs setproctitle to rename the running process from python to pathaction. This simplifies identification in system monitoring tools such as top, htop, and ps.

pip install "pathaction[proctitle]"

To install both extras at once, use a comma-separated list:

pip install "pathaction[colors,proctitle]"

Getting Started

1. Authorize your working directory

By default, pathaction does not read rule-set files from arbitrary directories for security reasons. The allowed directories must be explicitly permitted. To allow pathaction to load rules from your projects folder and its subdirectories, run:

pathaction --allow-dir ~/projects

2. Create a rule-set file

Navigate to your project root and create a .pathaction.yaml file (e.g., ~/projects/my-app/.pathaction.yaml). Here is a basic example to run Python files:

---
actions:
  - path_match: "*.py"
    tags: main
    command:
      - "python"
      - "{{ file }}"

3. Execute the file

Now, instead of manually invoking the Python interpreter, you can pass the file directly to pathaction. It will read the rule, match the .py extension, and execute the command.

pathaction ~/projects/my-app/dir1/dir2/file.py

Because the default tag is main, pathaction automatically targets the block we just defined.

You can also specify the tag:

pathaction -t main ~/projects/my-app/dir1/dir2/file.py

Comprehensive Examples

The real value of pathaction comes from defining complex, multi-tag workflows across different file types. Here are detailed examples of how to configure .pathaction.yaml for various scenarios.

Example 1: Full Python and Bash Workflow

Instead of memorizing different tools and their command-line arguments, you can define them as actions.

---
actions:
  # Execute the Python script
  - path_match: "*.py"
    tags: main
    command:
      - "python"
      - "{{ file }}"

  # Run tests
  - path_match: "*.py"
    tags: test
    command: "pytest -v {{ file|quote }}"

  # Type checking
  - path_match: "*.py"
    tags: typecheck
    command: "mypy {{ file|quote }}"

  # Execute Bash shell scripts
  - path_match: "*.sh"
    tags:
      - main
    command: "bash {{ file|quote }}"

You can invoke these specific actions by passing the -t (tag) flag:

pathaction -t typecheck src/utils.py
pathaction -t test src/test_utils.py

Example 2: Managing Infrastructure with Ansible

You can set up rules to apply Ansible playbooks directly.

---
actions:
  - path_match: "*playbook.yml"
    tags: main
    command: "ansible-playbook -i inventory.ini {{ file|quote }}"

Example 3: C/C++ Compilation and Execution

You can use pathaction to compile files on the fly and put the output binary in the correct directory.

---
actions:
  # Compile C++ source code
  - path_match: "*.cpp"
    tags: build
    cwd: "{{ file|dirname }}"
    command: "g++ -Wall -O2 {{ file|quote }} -o {{ file|basename|replace('.cpp', '') }}"

  # Run the compiled binary
  - path_match: "*.cpp"
    tags: run
    cwd: "{{ file|dirname }}"
    command: "./{{ file|basename|replace('.cpp', '') }}"

Command-Line Arguments

The pathaction utility accepts several arguments to control execution behavior:

-t, --tag: Execute the action associated with this tag (default is main).
-b, --confirm-before: Prompt for confirmation before executing the defined action.
-a, --confirm-after: Ask the user if they want to execute the action again after it finishes (respects the confirm_after_timeout configuration).
-l, --list: List all the .pathaction.yaml configuration files that apply to the given file path. Useful for debugging rule resolution.
-d, --allow-dir: Permanently allow pathaction to execute rules from the provided directory and its subdirectories.
--disallow-dir: Revoke access and remove a specific directory from your allowed list.
--list-allowed-dirs: Print a list of all permanently allowed directories.

Configuration Guide (.pathaction.yaml)

The rule-sets cascade hierarchically. When you execute a file, pathaction looks for .pathaction.yaml in the file’s current directory, and then walks up the filesystem tree (parent directories) to find and merge all other .pathaction.yaml files. This loading behavior is similar to that of a .gitignore file. In case of conflicting rules or configurations, priority is given to the rule set that is located in the directory closest to the specified file.

Each rule defined in the rule-set file must include at least the matching rule and the command.

Match Methods

You can target files using various matching strategies. Every match method also has a corresponding _exclude variant (e.g., path_match_exclude) to explicitly ignore files that would otherwise match.

path_match: Standard glob pattern matching (e.g., *.py).
path_match_case: Case-sensitive glob pattern matching.
path_regex: Regular expression path matching (case-insensitive by default).
path_regex_case: Case-sensitive regular expression matching.
mimetype: Strict MIME type matching (e.g., text/x-python).
mimetype_match: Glob pattern matching for MIME types (e.g., text/*).
mimetype_regex: Regular expression matching for MIME types.

Action Configuration

An action block can include the following optional attributes:

tags: A string or list of strings indicating the tag names.
comment: An informative string describing what the action does.
timeout: An integer specifying the maximum execution time in seconds.
cwd: The current working directory for the command.
stdout: Redirect the standard output of the command to the specified file path.
stderr: Redirect the standard error of the command to the specified file path. (If both stdout and stderr point to the exact same file path, they are combined).
shell: Boolean indicating if the command should be executed within a shell environment.
command / list_commands: The command string/array to execute. These two are mutually exclusive.

Global Options

You can define an options block at the root of your .pathaction.yaml to specify execution defaults:

shell_path: The absolute path to the shell executable used when shell: true (defaults to the user’s login shell).
verbose: Enable verbose logging.
debug: Enable debug mode.
timeout: A global timeout constraint in seconds.
confirm_after_timeout: The timeout in seconds when waiting for user input during a --confirm-after prompt.
last: If set to true, pathaction stops loading configurations from higher parent directories.

Jinja2 Variables and Filters

Jinja2 Variables

Variable	Description
`{{ file }}`	Replaced with the full absolute path to the targeted file.
`{{ cwd }}`	Refers to the current working directory of the matched action.
`{{ env }}`	Represents the operating system environment variables (dictionary).
`{{ pathsep }}`	Denotes the path separator (e.g., `/` on Linux, `\` on Windows).

Jinja2 Filters

quote: Escapes a string for use as a shell argument by wrapping it in single quotes and escaping internal single quotes. This prevents shell injection vulnerabilities. Example: "/home/user/my file.txt" | quote evaluates to '/home/user/my file.txt'.
basename: Extracts the trailing filename or leaf component of a filesystem path. Example: "/home/user/src/main.py" | basename evaluates to "main.py".
dirname: Returns the parent directory portion of a filesystem path. Example: "/home/user/src/main.py" | dirname evaluates to "/home/user/src".
file_only_dirname: Returns the parent directory if the path is a file, or returns the path itself if it is already a directory.
realpath: Resolves all symbolic links, relative segments (like ..), and duplicate separators to return the canonical absolute path. Example: "/usr/bin/../local/bin/python" | realpath evaluates to "/usr/local/bin/python".
abspath: Converts a relative path into an absolute path by prefixing it with the current working directory. Example: "src/main.py" | abspath evaluates to "/home/user/project/src/main.py".
relpath: Computes the relative path between two directories.
joinpath: Combines one or more path segments using the system filesystem separator. Example: "/var/log" | joinpath("nginx", "error.log") evaluates to "/var/log/nginx/error.log".
joincmd: Converts an array of command-line tokens into a single properly escaped shell command string. Example: ["grep", "-i", "error log"] | joincmd evaluates to 'grep -i "error log"'.
splitcmd: Parses a raw shell command string into an array of distinct arguments while honoring quotation rules and escape sequences. Example: "git commit -m 'initial release'" | splitcmd evaluates to ["git", "commit", "-m", "initial release"].
expanduser: Replaces a leading tilde notation (~ or ~user) with the absolute path of the corresponding user home directory. Example: "~/config/tmux.conf" | expanduser evaluates to "/home/user/config/tmux.conf".
expandvars: Substitutes environment variables within a string matching $VARIABLE or ${VARIABLE} with their current active system values. Example: "$HOME/.config" | expandvars evaluates to "/home/user/.config".
shebang: Inspects a file and extracts the first line directly if it begins with an executable script prefix (#!). Example: "/home/user/script.sh" | shebang evaluates to "#!/usr/bin/env bash".
shebang_list: Extracts the shebang line from a file, discards the initial #! marker, and parses the remaining contents into a clean token array. Example: "/home/user/script.sh" | shebang_list evaluates to ["/usr/bin/env", "bash"].
shebang_quote: Extracts the shebang line from a file, strips the #! marker, and returns the runtime interpreter directive as a safely balanced, shell-quoted string. Example: "/home/user/script.sh" | shebang_quote evaluates to "/usr/bin/env bash".
which: Searches the system environment variable PATH to locate the absolute path of an executable binary. Raises an error if the binary cannot be found. Example: "emacs" | which evaluates to "/usr/bin/emacs".
startswith: Evaluates to true if the string starts with the given prefix.
endswith: Evaluates to true if the string ends with the given suffix.

Frequently Asked Questions

Does pathaction walk the filesystem from the current directory to the top in search of .pathaction.yaml ruleset files?

Pathaction walks from the directory containing the file passed to it and merges .pathaction.yaml rules from all allowed parent directories.

There is a security measure by default: loading rules is allowed only in directories that have been explicitly permitted using pathaction --allow-dir ~/dir/projects/, which enables access to ~/dir/projects/ and all its subdirectories. If the entire home directory is allowed with pathaction --allow-dir ~/, rules can be loaded from any directory within the home directory.

What are the differences between make and pathaction?

The make tool centers on targets and dependency tracking, making it good for compiling software based on file timestamps. In contrast, the pathaction tool acts as a universal file execution router. Passing a file path directly to Pathaction determines the correct command to run based on defined file extensions or patterns.

While make relies on project-specific files with strict syntax, Pathaction uses YAML files that cascade hierarchically across your filesystem. Much like how Git handles ignore files, Pathaction loads and merges all .pathaction.yaml rule-set files found in parent directories. This allows you to define rules in your home directory that can be overridden by specific settings within individual project folders.

For example, a Python script in ~/project_a can be routed to a local virtual environment, while a Python script in ~/project_a/project_b can trigger a Docker execution simply by defining different .pathaction.yaml files in those directories. Pathaction loads and merges all .pathaction.yaml ruleset files found in parent directories. This means that any rule in ~/project_a/project_b/.pathaction.yaml that does not match a file falls back to the rules defined in ~/project_a/.pathaction.yaml, similar to how Git handles .gitignore files.

What is the difference between Pathaction and a command such as `find | xargs`?

It is very different from find | xargs. The pathaction tool functions like a customizable, developer-focused xdg-open. It acts as the intelligent router that receives each file path and automatically determines the correct command to execute based on your defined rules. Just as xdg-open relies on rigid system MIME types to launch GUI applications, Pathaction uses your hierarchical .pathaction.yaml configurations and Jinja2 templating to dynamically run commands.

How is pathaction different from a shebang?

Shebangs are fine for basic execution, but they have limitations that Pathaction was built to address.

A shebang only defines how to execute a script. It cannot tell your system how to lint, format, debug, or test files. With pathaction, you can use tags. Passing pathaction -t main file.py executes it, while passing pathaction -t test file.py can run it through pytest.

How is pathaction different from xdg-open?

File associations such as xdg-open apply globally. Pathaction uses cascading YAML files similar to how Git handles .gitignore files. A Python script in ~/project_a can be routed to a local virtual environment, while a Python script in ~/project_a/project_b can trigger a Docker execution simply by defining different .pathaction.yaml files in those directories. Pathaction loads and merges all .pathaction.yaml ruleset files found in parent directories. This means that any rule in ~/project_a/project_b/.pathaction.yaml that does not match a file falls back to the rules defined in ~/project_a/.pathaction.yaml.

In addition to that, Pathaction uses Jinja2 templating, allowing you to dynamically build complex shell commands based on the file name, its parent directory, or environment variables.

How does the author use pathaction?

The author’s .pathaction.yaml rules function as a universal bridge across distinct software environments.

For Python, Bash, C, C++, and related languages, rules are defined to install dependencies, build projects, execute binaries, run test suites, and launch debuggers.
For Ansible, rules automatically upload playbooks to remote servers, execute them, and validate their results.
For Emacs, rules integrate file-based actions directly with editor workflows, enabling evaluation, compilation, or linting based on context.
For Vim, rules provide similar editor integration, allowing files to trigger build, run, or formatting actions without manual command construction.

Pathaction operates as an IDE-like action layer for the filesystem. Instead of embedding logic inside each editor or build system, actions are described declaratively and applied uniformly across tools.

The primary advantage is cognitive simplicity. There is no need to memorize complex command-line flags or tool-specific invocation patterns. A file is passed to Pathaction with a semantic tag such as main, install, or debug, and the corresponding rule determines how the operation is executed.

License

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

13 Useful GNOME Shell Extensions for a Better Desktop Experience (Available in the official Debian repositories or on the GNOME Extensions website for other distributions)

GNOME Shell offers a clean and modern UI, but it often lacks functionality desired by power users and those coming from other desktop environments.

GNOME Shell extensions provide a way to restore or add features to your desktop. In this article, you’ll explore some of the most useful GNOME Shell extensions available directly from the official Debian repositories via apt (available in Debian Bookworm and newer).

For users running distributions other than Debian, this article provides a link to the GNOME Shell Extensions page for each extension, allowing installation on any supported distribution.

Extension Management

The GNOME Shell Extension Prefs tool offers a graphical interface for enabling, disabling, and configuring GNOME Shell extensions. It can be installed using the following command:

sudo apt install gnome-shell-extension-prefs

After installation, GNOME Shell extensions can be enabled and configured using the gnome-extensions-app command.

Productivity

gnome-shell-extension-caffeine

The Caffeine extension prevents the system from locking the screen or entering suspend mode while it is active or when an application switches to fullscreen mode. This extension is useful during presentations, video playback, or gaming sessions, where uninterrupted screen activity is required.