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
```bash
#!/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
```bash
#!/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
```bash
#!/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
```bash
#!/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
```bash
#!/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
```bash
# 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
```bash
# 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
```yaml
# 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
```bash
#!/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
```bash
# 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
```bash
# Test apt-ostree functionality
$ apt-ostree install package
$ apt-ostree status
$ apt-ostree upgrade
```

### Verify Real Binaries Are Preserved
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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](https://github.com/ublue-os/bazzite)
- [rpm-ostree Documentation](https://coreos.github.io/rpm-ostree/)
- [OSTree Documentation](https://ostreedev.github.io/ostree/)
- [Debian Atomic Project](https://github.com/debian-atomic)