debian-atomic/apt-tool-blocking-implementation.md

APT Tool Blocking Implementation for Debian Atomic Systems

Overview

This document outlines how to implement blocking of traditional APT package management tools (apt-get, apt, dpkg) on Debian atomic systems, similar to how ublue-os blocks DNF/YUM on Fedora atomic systems. This ensures users use apt-ostree instead of traditional package management tools.

Why Block APT Tools?

System Integrity

• Atomic Updates: Ensures all software changes go through apt-ostree
• Rollback Capability: Maintains ability to rollback entire system states
• Package Consistency: Prevents mixing atomic and traditional package management
• Database Integrity: Avoids package database corruption

User Experience

• Clear Guidance: Provides immediate feedback on correct tool usage
• Consistency: Matches user expectations from other atomic systems (e.g., ublue-os)
• Documentation: Points users to proper atomic management commands

Implementation Strategy

Option 1: Wrapper Scripts (Recommended)

Replace APT binaries with wrapper scripts that display error messages and exit.

Option 2: Package Patching

Modify APT packages during the OSTree image build process.

Option 3: Binary Replacement

Replace APT binaries with custom error-displaying executables.

Recommended Implementation: Wrapper Scripts

1. Create Wrapper Scripts

apt-get-wrapper

#!/bin/bash
# /usr/bin/apt-get-wrapper

cat << 'EOF'
ERROR: Debian Atomic images utilize apt-ostree instead (and is discouraged to use).

This system uses atomic updates with apt-ostree. Please use:

  apt-ostree install <package>    # Install packages
  apt-ostree upgrade              # Upgrade system
  apt-ostree rollback            # Rollback changes
  apt-ostree status              # Check system status
  apt-ostree apply-live          # Apply changes immediately

For more information, see: https://docs.debian-atomic.org/
EOF

exit 1

apt-wrapper

#!/bin/bash
# /usr/bin/apt-wrapper

cat << 'EOF'
ERROR: Debian Atomic images utilize apt-ostree instead (and is discouraged to use).

This system uses atomic updates with apt-ostree. Please use:

  apt-ostree install <package>    # Install packages
  apt-ostree upgrade              # Upgrade system
  apt-ostree rollback            # Rollback changes
  apt-ostree status              # Check system status
  apt-ostree apply-live          # Apply changes immediately

For more information, see: https://docs.debian-atomic.org/
EOF

exit 1

dpkg-wrapper

#!/bin/bash
# /usr/bin/dpkg-wrapper

cat << 'EOF'
ERROR: Debian Atomic images utilize apt-ostree instead (and is discouraged to use).

Direct dpkg usage is not allowed on atomic systems. Please use:

  apt-ostree install <package>    # Install packages
  apt-ostree remove <package>     # Remove packages
  apt-ostree upgrade              # Upgrade system

For more information, see: https://docs.debian-atomic.org/
EOF

exit 1

2. Installation During OSTree Image Build

Build Process Integration

#!/bin/bash
# During OSTree image composition (atomic phase)

# Install APT packages normally first
apt-get install --download-only apt apt-utils dpkg

# Extract packages for modification
dpkg-deb -R apt_*.deb apt-extracted/
dpkg-deb -R dpkg_*.deb dpkg-extracted/

# Backup original binaries
mv apt-extracted/usr/bin/apt-get apt-extracted/usr/bin/apt-get.real
mv apt-extracted/usr/bin/apt apt-extracted/usr/bin/apt.real
mv dpkg-extracted/usr/bin/dpkg dpkg-extracted/usr/bin/dpkg.real

# Install wrapper scripts
install -m 755 apt-get-wrapper apt-extracted/usr/bin/apt-get
install -m 755 apt-wrapper apt-extracted/usr/bin/apt
install -m 755 dpkg-wrapper dpkg-extracted/usr/bin/dpkg

# Repackage and install
dpkg-deb -b apt-extracted/ apt-modified.deb
dpkg-deb -b dpkg-extracted/ dpkg-modified.deb
dpkg -i apt-modified.deb dpkg-modified.deb

# Clean up
rm -rf apt-extracted/ dpkg-extracted/ apt-modified.deb dpkg-modified.deb

Alternative: Post-Install Scripts

#!/bin/bash
# post-install script in package configuration

# Block APT tools after installation
mv /usr/bin/apt-get /usr/bin/apt-get.real
mv /usr/bin/apt /usr/bin/apt.real
mv /usr/bin/dpkg /usr/bin/dpkg.real

# Install wrapper scripts
install -m 755 apt-get-wrapper /usr/bin/apt-get
install -m 755 apt-wrapper /usr/bin/apt
install -m 755 dpkg-wrapper /usr/bin/dpkg

3. Preserve Essential Functionality

Keep Real Binaries Available

# Store real binaries with .real extension
/usr/bin/apt-get.real    # Original apt-get
/usr/bin/apt.real        # Original apt
/usr/bin/dpkg.real       # Original dpkg

# apt-ostree can use these internally
# Users cannot access them directly

Internal Tool Access

# apt-ostree can use real binaries internally
# Example: apt-ostree install package
# 1. Uses apt-get.real for package resolution
# 2. Uses dpkg.real for package installation
# 3. Manages OSTree commit creation

Integration with deb-bootc-compose

Configuration File Example

# deb-bootc-compose configuration
packages:
  - name: apt
    exclude: false
    post-install: |
      # Block APT tools
      mv /usr/bin/apt-get /usr/bin/apt-get.real
      mv /usr/bin/apt /usr/bin/apt.real
      install -m 755 /tmp/apt-get-wrapper /usr/bin/apt-get
      install -m 755 /tmp/apt-wrapper /usr/bin/apt
      
  - name: dpkg
    exclude: false
    post-install: |
      # Block dpkg
      mv /usr/bin/dpkg /usr/bin/dpkg.real
      install -m 755 /tmp/dpkg-wrapper /usr/bin/dpkg

files:
  - source: apt-get-wrapper
    destination: /tmp/apt-get-wrapper
    mode: "0755"
  - source: apt-wrapper
    destination: /tmp/apt-wrapper
    mode: "0755"
  - source: dpkg-wrapper
    destination: /tmp/dpkg-wrapper
    mode: "0755"

Build Script Integration

#!/bin/bash
# deb-bootc-compose build script

# Create wrapper scripts
cat > apt-get-wrapper << 'EOF'
#!/bin/bash
cat << 'END'
ERROR: Debian Atomic images utilize apt-ostree instead...
END
exit 1
EOF

cat > apt-wrapper << 'EOF'
#!/bin/bash
cat << 'END'
ERROR: Debian Atomic images utilize apt-ostree instead...
END
exit 1
EOF

cat > dpkg-wrapper << 'EOF'
#!/bin/bash
cat << 'END'
ERROR: Debian Atomic images utilize apt-ostree instead...
END
exit 1
EOF

# Make executable
chmod +x apt-get-wrapper apt-wrapper dpkg-wrapper

# Build OSTree image with blocking
deb-bootc-compose build --config atomic-config.yaml

Testing the Implementation

Verify Blocking Works

# Test on atomic system
$ apt-get update
ERROR: Debian Atomic images utilize apt-ostree instead...

$ apt install package
ERROR: Debian Atomic images utilize apt-ostree instead...

$ dpkg -i package.deb
ERROR: Debian Atomic images utilize apt-ostree instead...

Verify apt-ostree Still Works

# Test apt-ostree functionality
$ apt-ostree install package
$ apt-ostree status
$ apt-ostree upgrade

Verify Real Binaries Are Preserved

# Check real binaries exist
$ ls -la /usr/bin/apt*
/usr/bin/apt -> apt-wrapper
/usr/bin/apt-get -> apt-get-wrapper
/usr/bin/apt.real
/usr/bin/apt-get.real

$ ls -la /usr/bin/dpkg*
/usr/bin/dpkg -> dpkg-wrapper
/usr/bin/dpkg.real

Security Considerations

Permission Management

# Ensure wrapper scripts are not writable
chmod 755 /usr/bin/apt-get
chmod 755 /usr/bin/apt
chmod 755 /usr/bin/dpkg

# Ensure real binaries are protected
chmod 755 /usr/bin/apt-get.real
chmod 755 /usr/bin/apt.real
chmod 755 /usr/bin/dpkg.real

Integrity Verification

# Verify wrapper scripts haven't been modified
sha256sum /usr/bin/apt-get /usr/bin/apt /usr/bin/dpkg

# Check for unauthorized modifications
find /usr/bin -name "*.real" -exec ls -la {} \;

Troubleshooting

Common Issues

Wrapper Scripts Not Working

# Check permissions
ls -la /usr/bin/apt*

# Verify wrapper scripts are executable
file /usr/bin/apt-get /usr/bin/apt /usr/bin/dpkg

# Check for syntax errors
bash -n /usr/bin/apt-get

apt-ostree Cannot Access Real Binaries

# Verify real binaries exist
ls -la /usr/bin/*.real

# Check apt-ostree configuration
# Ensure it's configured to use .real binaries

Users Can Still Access APT Tools

# Check if wrappers are properly linked
which apt-get
readlink -f /usr/bin/apt-get

# Verify PATH order
echo $PATH

Recovery Procedures

Restore Original Functionality

# Emergency recovery (if needed)
mv /usr/bin/apt-get.real /usr/bin/apt-get
mv /usr/bin/apt.real /usr/bin/apt
mv /usr/bin/dpkg.real /usr/bin/dpkg

Reinstall Blocking

# Reinstall blocking after recovery
./install-apt-blocking.sh

Future Enhancements

Advanced Blocking

• Selective Blocking: Allow certain APT operations in specific contexts
• User Permissions: Different blocking levels for different user types
• Audit Logging: Log attempts to use blocked tools

Integration Improvements

• Automatic Updates: Update blocking when apt-ostree is updated
• Configuration Management: Make blocking configurable
• Monitoring: Alert when blocking is bypassed

Conclusion

Implementing APT tool blocking is essential for Debian atomic systems to maintain system integrity and provide clear user guidance. The wrapper script approach is recommended for its simplicity, reliability, and ease of maintenance.

This blocking should be implemented during the OSTree image build process (atomic phase) rather than in apt-ostree itself, ensuring the atomic system is properly configured from the ground up.

References

• ublue-os DNF/YUM Blocking Implementation
• rpm-ostree Documentation
• OSTree Documentation
• Debian Atomic Project