RPi Build Logger

Comprehensive logging system for Raspberry Pi that captures system changes, command history, and package operations with git versioning. Designed to survive power outages and handle multiple concurrent terminal sessions.

Features

• Real-time command logging - Every command logged immediately with timestamp and working directory
• Session-isolated history - Multiple terminals won't conflict or overwrite each other
• Package operation tracking - All apt/dpkg operations logged automatically
• Daily system snapshots - Complete system state captured daily via anacron
• Git versioning - All logs automatically committed to git
• Power-loss resistant - Logs written immediately, not on shell exit
• Multi-terminal safe - Each terminal session gets its own history file

What Gets Logged

1. Command History

• Real-time log: history/realtime_commands.log

  • Format: 2025-11-06 11:15:23 [PID:2228] [PWD:/home/user/code] sudo apt install vim
  • Logged immediately after each command
  • Includes timestamp, process ID, working directory, and command

• Session-specific history: history/session_PID_TIMESTAMP.history

  • Each terminal session gets its own file
  • Prevents race conditions between concurrent terminals
  • Includes bash timestamp format

• Daily merged history: history/YYYY-MM-DD_merged_history.txt

  • All session histories merged into daily snapshot
  • Generated by anacron

2. Package Operations

• APT operations log: logs/apt_operations.log
  • Format: 2025-11-06 11:35:47 | INSTALL | vim | 9.0.1234 | arm64
  • Captures: install, upgrade, downgrade, reinstall, remove
  • Includes the command that triggered the operation
  • Works for scripts, not just manual commands

3. System Information

• Daily snapshot: logs/YYYY-MM-DD_sysinfo.txt
  • Complete package list with versions
  • Loaded kernel modules
  • Disk usage
  • Memory usage
  • System information

How It Works

Three-Tier Commit Strategy

The system uses multiple backup mechanisms to ensure no data is lost:

1. anacron daily job - Runs once per day, catches up on boot if system was off

   • Creates daily system snapshot
   • Merges all session histories
   • Commits all changes to git

2. systemd shutdown hook - Runs during graceful shutdown/reboot

   • Commits any uncommitted changes
   • Only fires on clean shutdowns

3. Shell EXIT trap - Runs when you log out normally

   • Tertiary backup for clean logouts
   • Catches normal shell exits

Handling Edge Cases

Multiple Concurrent Terminals:

• Each terminal gets unique history file: session_PID_TIMESTAMP.history
• No race conditions or overwrites
• All sessions merged into daily snapshot

Power Loss/Network Outage:

• Commands logged immediately via PROMPT_COMMAND
• anacron catches up on next boot
• Maximum data loss: Time since last boot/shutdown/logout

System Not Running at Midnight:

• anacron runs daily jobs on next boot if missed
• No manual intervention needed

Installation

Quick Install

git clone https://github.com/YOUR_USERNAME/rpi-build-logger.git
cd rpi-build-logger
./install.sh

The installer will:

1. Install anacron if not present
2. Set up APT logging hooks
3. Create systemd shutdown service
4. Configure your .bashrc
5. Initialize the build-notes git repository
6. Test the complete setup

Custom Installation

If you want to customize the installation:

./install.sh --dir /path/to/logs --no-backup

Options:

• --dir PATH - Specify custom log directory (default: ~/build-notes)
• --no-backup - Skip backing up existing .bashrc
• --user USER - Install for specific user (default: current user)

File Structure

After installation, your ~/build-notes directory will contain:

build-notes/
├── logs/
│   ├── YYYY-MM-DD_sysinfo.txt          # Daily system snapshots
│   └── apt_operations.log               # Package operation log
├── history/
│   ├── realtime_commands.log            # Real-time command log
│   ├── session_*.history                # Active session histories
│   ├── YYYY-MM-DD_merged_history.txt   # Daily merged histories
│   └── archived/                        # Old session files
├── configs/                             # Config backups (optional)
├── scripts/                             # Custom scripts (optional)
└── .git/                                # Git repository

Usage

Starting a New Shell

After installation, start a new shell or log out and back in:

exec bash

The logging will start automatically.

Viewing Logs

Recent commands with context:

tail -20 ~/build-notes/history/realtime_commands.log

Package operations:

cat ~/build-notes/logs/apt_operations.log

Today's system snapshot:

cat ~/build-notes/logs/$(date +%F)_sysinfo.txt

Git history:

cd ~/build-notes
git log --oneline

Searching Logs

Find when you installed a package:

grep -i "nginx" ~/build-notes/logs/apt_operations.log

Find commands run in specific directory:

grep "PWD:/home/user/myproject" ~/build-notes/history/realtime_commands.log

See what changed between dates:

cd ~/build-notes
git diff <old-commit> <new-commit>

Manual Operations

Force a Snapshot Now

sudo /etc/cron.daily/build-notes-snapshot

Force a Git Commit

cd ~/build-notes
git add .
git commit -m "Manual snapshot: $(date)"

View anacron Status

systemctl status anacron

View Shutdown Service Status

systemctl status build-notes-commit.service

Components

Scripts Installed

File	Location	Purpose
apt-logger.sh	/usr/local/bin/	Logs APT package operations
build-notes-snapshot	/etc/cron.daily/	Daily snapshot via anacron
build-notes-shutdown-commit.sh	/usr/local/bin/	Git commit on shutdown

Configuration Files

File	Location	Purpose
99build-notes-logger	/etc/apt/apt.conf.d/	APT hook configuration
build-notes-commit.service	/etc/systemd/system/	Systemd shutdown service
.bashrc modifications	~/.bashrc	Command logging setup

Troubleshooting

Commands Not Being Logged

1. Check if new shell has loaded config:

   echo $BUILD_NOTES_DIR

   Should output: /home/user/build-notes

2. Check if realtime log exists:

   ls -l ~/build-notes/history/realtime_commands.log

3. Start a fresh shell:

   exec bash

Package Operations Not Logged

1. Check if APT hook exists:

   ls -l /etc/apt/apt.conf.d/99build-notes-logger

2. Check if logger script exists:

   ls -l /usr/local/bin/apt-logger.sh

3. Test manually:

   sudo apt install --reinstall -y tree
   cat ~/build-notes/logs/apt_operations.log

anacron Not Running

1. Check anacron status:

   systemctl status anacron

2. Check if daily script exists:

   ls -l /etc/cron.daily/build-notes-snapshot

3. Run manually to test:

   sudo /etc/cron.daily/build-notes-snapshot

Shutdown Service Not Working

1. Check service status:

   systemctl status build-notes-commit.service

2. Check if enabled:

   systemctl is-enabled build-notes-commit.service

3. Re-enable if needed:

   sudo systemctl daemon-reload
   sudo systemctl enable build-notes-commit.service

Uninstallation

To completely remove the logging system:

./uninstall.sh

This will:

• Remove all installed scripts
• Remove APT hooks
• Remove systemd service
• Remove .bashrc modifications (restores backup)
• Optionally delete the build-notes directory

Requirements

• Debian/Ubuntu-based system (tested on Raspberry Pi OS)
• Bash shell
• Git
• sudo privileges
• anacron (installed automatically)

Contributing

Contributions welcome! Please feel free to submit issues or pull requests.

License

MIT License - Feel free to use and modify for your needs.

Author

Created for tracking Raspberry Pi system changes and software installations.