Arch Linux Update & Backup Utility (Carbon V7)

A robust, enterprise-grade maintenance, dotfiles backup, and remote monitoring suite for Arch GNU/Linux. Carbon V7 combines the flexibility of interactive terminal user interfaces (TUI) with silent, scriptable headless CLI execution. It automates system updates, AUR synchronization, mirrorlist optimization, Docker container updates, system configuration backups, and remote push alerting via NTFY.

Key Features

🖥️ Dual Operational Modes: Launch an interactive, mouse-friendly checklist interface (styled via .dialogrc), or execute headless commands with specific flags for automated scripts and cron jobs.
🔐 GUI Sudo Elevation & Memory Hygiene: Integrated --passwordbox prompt matching your TUI theme when privilege elevation is needed. Automatically scrubs credentials from memory immediately after verification (unset pass) and starts a non-interactive background keepalive loop to prevent timeouts during long compilation jobs.
⚡ Full System Lifecycle Management:
- Official repository upgrades via pacman
- AUR package builds via yay
- Mirrorlist optimization via reflector
- Pacman cache cleanup via paccache
- Docker container updates via Watchtower
- Gemini CLI global npm updates
🗄️ Registry-Based Dotfile & System Sync: Track arbitrary user configuration files, custom shell scripts, and root system paths (/etc/systemd/system/, /usr/local/bin/, etc.) in a unified database (registry.db), automatically syncing them to a git repository with package lists (pkglist.txt, aur_pkglist.txt).
📲 Real-Time Remote Notifications (NTFY): Dispatches native Markdown push notifications to mobile devices, web browsers, and desktop clients with execution duration, host IP discovery (ip route), service completion indicators, and actionable GitHub repository buttons.
📜 Configurable Persistent Logging & Rotation: Automatically captures all execution output into timestamped logs and enforces rolling retention limits (LOG_RETENTION_COUNT=50) to keep your filesystem clean.
🛡️ Secret Protection: Automatic sanitization ensures local environment files (.env) are excluded from repository synchronizations and git pushes, only allowing template samples (sample.env).

Prerequisites & Dependencies

The utility automatically checks for the availability of optional tools and gracefully degrades or skips steps if a tool is not installed.

Required Base Packages

bash (v4.0+): Primary shell runtime.
sudo: Privilege elevation for system maintenance.
pacman: Arch Linux package manager.
coreutils, iproute2, awk, grep, sed: Standard utilities (included by default on Arch base installations).

Optional Service Dependencies

Package	Purpose	Used When
`dialog`	Renders the primary TUI checklist and GUI sudo elevation box	Interactive mode without flags (falls back to `whiptail` if omitted)
`reflector`	Retrieves and sorts the fastest HTTPS mirrors by country	`-m` flag / Mirrorlist option
`yay`	AUR helper for foreign package upgrades	`-a` flag / AUR option
`pacman-contrib`	Provides `paccache` for intelligent package cache pruning	`-k` flag / Cache cleaning option
`rsync`	High-performance directory tree and dotfile backup synchronization	`-d` flag / Dotfiles sync
`git`	Version control for dotfiles tracking, automated commits & pushes	`-d` flag / Dotfiles sync
`curl`	HTTP/HTTPS client to deliver NTFY push notification payloads	Remote alerting engine
`docker`	Container engine updated using Watchtower (`containrrr/watchtower`)	`-c` flag / Docker option
`nodejs` & `npm`	JavaScript runtime and package manager for `@google/gemini-cli`	`-g` flag / Gemini CLI option

Quick Installation

Install all standard dependencies in one command:

# Core recommended utilities and service tools
sudo pacman -S --needed dialog reflector pacman-contrib rsync git curl

# AUR helper (if not already installed)
# e.g., git clone https://aur.archlinux.org/yay-bin.git && cd yay-bin && makepkg -si

Quick Start

1. Clone the Repository

git clone https://github.com/SandfordAE/Carbon.git ~/Arch_Update
cd ~/Arch_Update

2. Make Scripts Executable

chmod +x update_arch.sh tests/*.sh

3. Initialize Your Configuration

Copy the provided environment template to .env:

cp sample.env .env

Edit .env to configure your dotfiles directory, notification topics, and preferred mirror country.

4. Run the Utility

# Launch interactive TUI checklist
./update_arch.sh

# Or run headless with specific operations
./update_arch.sh -mpad

NTFY Push Notifications Guide

What is NTFY?

ntfy (pronounced notify) is a free, open-source HTTP-based pub-sub notification service. It allows scripts and applications to send push notifications directly to your phone, tablet, or desktop browser using simple HTTP requests without creating accounts, generating proprietary API keys, or installing heavy agents.

Free native companion apps are available on:

Android: Google Play or F-Droid
iOS: App Store
Web App: ntfy.sh/app (supports browser desktop notifications)

Option A: Public Server (Zero Setup)

You can use the official public server without deploying any infrastructure:

Install the ntfy app on your phone.
Subscribe to a unique, hard-to-guess topic name (e.g., arch_alerts_x9k27).

Set your .env configuration:

NTFY_SERVER=https://ntfy.sh
NTFY_TOPIC=arch_alerts_x9k27

Option B: Self-Hosted NTFY with Docker (Quickstart)

If you prefer hosting your own notification server, you can deploy a lightweight NTFY container in seconds.

Using Docker CLI:

docker run -d \
  --name ntfy \
  --restart unless-stopped \
  -p 8080:80 \
  -v /var/cache/ntfy:/var/cache/ntfy \
  -v /etc/ntfy:/etc/ntfy \
  binwiederhier/ntfy serve \
  --cache-file /var/cache/ntfy/cache.db

Using Docker Compose (`docker-compose.yml`):

services:
  ntfy:
    image: binwiederhier/ntfy:latest
    container_name: ntfy
    restart: unless-stopped
    ports:
      - "8080:80"
    volumes:
      - ./ntfy_cache:/var/cache/ntfy
      - ./ntfy_config:/etc/ntfy
    command: serve --cache-file /var/cache/ntfy/cache.db

Configure `.env` for your Self-Hosted Instance:

NTFY_SERVER=http://192.168.1.100:8080   # Or your public domain (e.g., https://ntfy.example.com)
NTFY_TOPIC=my_arch_updates
NTFY_TOKEN=                             # Optional: Access token if authentication is enabled
NTFY_USER=                              # Optional: Basic auth username
NTFY_PASSWORD=                          # Optional: Basic auth password
NTFY_INSECURE=false                     # Set to true if using self-signed certificates

Testing Notifications

Verify your NTFY configuration at any time without running a complete system update:

bash tests/test_ntfy.sh

Configuration Reference (.env)

All settings are configured using environment variables. When ./update_arch.sh executes, it looks for a local .env file in the script root.

Variable	Description	Default
`DOTFILES_DIR`	Path to your tracked dotfiles git repository	`$HOME/.dotfiles`
`REGISTRY_FILE`	Location of the registry database	`$DOTFILES_DIR/registry.db`
`REPO_FILES_DIR`	Subdirectory inside `DOTFILES_DIR` storing synchronized configurations	`$DOTFILES_DIR/dotFiles_BAK`
`PKG_DIR`	Subdirectory where native & AUR package lists are saved	`$DOTFILES_DIR/packages`
`LOG_DIR`	Subdirectory where timestamped run logs are stored	`$DOTFILES_DIR/logs`
`LOG_RETENTION_COUNT`	Number of recent logs to retain before rotation deletes old logs	`50`
`REFLECTOR_COUNTRY`	Default country code for mirrorlist optimization	`GB`
`NTFY_SERVER`	Server URL (public `https://ntfy.sh` or self-hosted endpoint)	`https://ntfy.sh`
`NTFY_TOPIC`	Notification topic channel name (leave empty to disable alerts)	empty
`NTFY_TOKEN`	Bearer token for protected NTFY topics	empty
`NTFY_USER`	HTTP Basic Auth username	empty
`NTFY_PASSWORD`	HTTP Basic Auth password	empty
`NTFY_INSECURE`	Set to `true` to allow untrusted/self-signed SSL certificates	`false`

🔒 Security Notice: .env is ignored by git (.gitignore). Never commit production credentials, tokens, or private topics.

CLI Flags & Usage

Usage: ./update_arch.sh [-mpadgck] [-r <path>] [-u <path>] [-y <country>] [-h]

Command Options

Flag	Description
`-m`	Optimize pacman mirrorlist via `reflector`
`-p`	Run Pacman system update (`pacman -Syu`) and clean cache
`-a`	Upgrade AUR packages using `yay`
`-d`	Synchronize registered dotfiles, system paths, and package lists
`-g`	Upgrade Gemini CLI (`@google/gemini-cli`) globally via npm
`-c`	Upgrade Docker containers via Watchtower (`containrrr/watchtower`)
`-k`	Prune package cache using `paccache` (or `pacman -Sc`)
`-y <country>`	Override default reflector country code (e.g., `-y US`)
`-r <path>`	Register a file or directory into the tracking database
`-u <path>`	Unregister a file or directory from the tracking database
`-h`	Display the interactive help screen

Examples

1. Launch Interactive TUI (default when run with no arguments):

./update_arch.sh

2. Complete Headless Maintenance Run:

# Update mirrors for Germany, update Pacman, AUR, and sync dotfiles
./update_arch.sh -y DE -mpad

3. Routine Fast Maintenance:

# Upgrade native packages, AUR, and clean package cache
./update_arch.sh -pak

Registry & Backup Architecture

File and Directory Registration

Rather than manually managing symlinks or maintaining ad-hoc backup scripts, Carbon V7 uses a dynamic registry (registry.db).

Register a user configuration:

./update_arch.sh -r ~/.config/kitty/kitty.conf

Register an entire directory:
```
./update_arch.sh -r ~/.config/hypr
```

Unregister an item:

./update_arch.sh -u ~/.config/kitty/kitty.conf

System Paths & Permission Handling

When registering absolute system paths (e.g., /etc/systemd/system, /etc/pacman.conf, /usr/local/bin), the script:

Elevates privileges via sudo to read restricted directories.
Mirrors the path into $REPO_FILES_DIR/system/.
Automatically fixes destination ownership so files can be committed and managed by non-root git users.

Automated Package Backups

Whenever dotfiles synchronization (-d) is triggered, the utility captures installed package states into:

$DOTFILES_DIR/packages/pkglist.txt (Native packages: pacman -Qqen)
$DOTFILES_DIR/packages/aur_pkglist.txt (AUR packages: pacman -Qqem)

If changes are detected, Carbon stages, commits with an automated timestamped message, and pushes updates to your dotfiles git remote.

Repository Structure

Arch_Update/
├── update_arch.sh          # Main production maintenance script (Version 7)
├── sample.env              # Environment variable configuration template
├── .dialogrc               # High-contrast "Murdered Out" TUI theme profile
├── .gitignore              # Repository exclusion rules (protects .env files)
├── LICENSE                 # MIT License
├── README.md               # Complete project documentation
├── tests/                  # Verification and test suites
│   ├── test_dialog.sh      # TUI dialog rendering and theme verification test
│   └── test_ntfy.sh        # NTFY notification payload test script
└── archive/                # Historical version progression
    ├── .dialogrc1-4        # Alternative dialog color profiles
    ├── sample.env.v5-v6    # Historical environment templates
    └── update_arch_v1-v7.sh# Version progression archive (v1.0 through v7.0)

Evolution & Versions

Version 1 (update_arch_v1.sh): Sequential command automation (pacman, AUR updates, cache cleanup).
Version 2 (update_arch_v2.sh): Reflector mirror rating, Watchtower container updates, and Gemini CLI management.
Version 3 (update_arch_v3.sh): Package list backups (pkglist.txt, aur_pkglist.txt) and basic config copying.
Version 4 & 4.5 (update_arch_v4.sh / v4.5): Dual-mode interface introduced (CLI flags vs interactive dialog/whiptail TUI).
Version 5 (update_arch_v5.sh): Dynamic registry database (-r, -u), full directory rsync support, and automated git push integration.
Version 6 (update_arch_v6.sh): Rich Markdown alerts via NTFY, local IP detection, persistent timestamped logging with automated log rotation, and root system path synchronization.
Version 6.5 (update_arch_v6.5.sh): GUI Sudo authentication with theme-matched --passwordbox, instant memory scrubbing, and background sudo keepalive.
Version 7 (update_arch.sh - Latest): Integrated checklist Help screen (-h), universal Markdown notification styling (✔️), and refined terminal navigation.

License

This project is licensed under the MIT License. Feel free to modify and adapt it for your own Arch Linux installations.

Navigation Menu

Repository navigation

About

Repository files navigation

Arch Linux Update & Backup Utility (Carbon V7)

Table of Contents

Key Features

Prerequisites & Dependencies

Required Base Packages

Optional Service Dependencies

Quick Installation

Quick Start

1. Clone the Repository

2. Make Scripts Executable

3. Initialize Your Configuration

4. Run the Utility

NTFY Push Notifications Guide

What is NTFY?

Option A: Public Server (Zero Setup)

Option B: Self-Hosted NTFY with Docker (Quickstart)

Using Docker CLI:

Using Docker Compose (`docker-compose.yml`):

Configure `.env` for your Self-Hosted Instance:

Testing Notifications

Configuration Reference (.env)

CLI Flags & Usage

Command Options

Examples

Registry & Backup Architecture

File and Directory Registration

System Paths & Permission Handling

Automated Package Backups

Repository Structure

Evolution & Versions

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
archive		archive
tests		tests
.dialogrc		.dialogrc
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
sample.env		sample.env
update_arch.sh		update_arch.sh

Latest commit

History

Folders and files

Repository files navigation

Arch Linux Update & Backup Utility (Carbon V7)

Table of Contents

Key Features

Prerequisites & Dependencies

Required Base Packages

Optional Service Dependencies

Quick Installation

Quick Start

1. Clone the Repository

2. Make Scripts Executable

3. Initialize Your Configuration

4. Run the Utility

NTFY Push Notifications Guide

What is NTFY?

Option A: Public Server (Zero Setup)

Option B: Self-Hosted NTFY with Docker (Quickstart)

Using Docker CLI:

Using Docker Compose (docker-compose.yml):

Configure .env for your Self-Hosted Instance:

Testing Notifications

Configuration Reference (.env)

CLI Flags & Usage

Command Options

Examples

Registry & Backup Architecture

File and Directory Registration

System Paths & Permission Handling

Automated Package Backups

Repository Structure

Evolution & Versions

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Using Docker Compose (`docker-compose.yml`):

Configure `.env` for your Self-Hosted Instance: