robojerk
306a68b89a
- Fix parallel execution logic to properly handle JoinHandle<Result<R, E>> types - Use join_all instead of try_join_all for proper Result handling - Fix double question mark (??) issue in parallel execution methods - Clean up unused imports in parallel and cache modules - Ensure all performance optimization modules compile successfully - Fix CI build failures caused by compilation errors
442 lines
8.8 KiB
Markdown
442 lines
8.8 KiB
Markdown
# 🔧 **apt-ostree Troubleshooting Guide**
|
|
|
|
## 🚨 **Common Issues and Solutions**
|
|
|
|
This guide provides solutions for common problems encountered when using apt-ostree. For detailed architecture information, refer to the relevant documents in the `architecture/` directory.
|
|
|
|
## 🔍 **Diagnostic Commands**
|
|
|
|
### **System Status Check**
|
|
```bash
|
|
# Check system status
|
|
apt-ostree status
|
|
|
|
# Check daemon status
|
|
systemctl status aptostreed
|
|
|
|
# Check OSTree status
|
|
ostree admin status
|
|
|
|
# Check system logs
|
|
journalctl -u aptostreed -f
|
|
```
|
|
|
|
### **Package Information**
|
|
```bash
|
|
# List installed packages
|
|
apt-ostree db list
|
|
|
|
# Check package overrides
|
|
apt-ostree override list
|
|
|
|
# Check user overlays
|
|
apt-ostree usroverlay list
|
|
|
|
# Check live updates
|
|
apt-ostree apply-live status
|
|
```
|
|
|
|
## ❌ **Common Error Messages**
|
|
|
|
### **Permission Denied Errors**
|
|
|
|
#### **Error**: `Permission denied` or `Operation not permitted`
|
|
**Cause**: Command requires root privileges or Polkit authorization
|
|
**Solution**:
|
|
```bash
|
|
# Run with sudo
|
|
sudo apt-ostree <command>
|
|
|
|
# Check Polkit policies
|
|
pkaction --action org.projectatomic.aptostree.<action>
|
|
|
|
# Verify user permissions
|
|
groups $USER
|
|
```
|
|
|
|
#### **Error**: `Polkit authorization denied`
|
|
**Cause**: User lacks required Polkit permissions
|
|
**Solution**:
|
|
```bash
|
|
# Check Polkit configuration
|
|
ls /usr/share/polkit-1/actions/org.projectatomic.aptostree.policy
|
|
|
|
# Verify policy installation
|
|
sudo apt install apt-ostree-polkit
|
|
|
|
# Check user session
|
|
loginctl show-user $USER
|
|
```
|
|
|
|
### **Daemon Connection Errors**
|
|
|
|
#### **Error**: `Failed to connect to daemon` or `Daemon not running`
|
|
**Cause**: aptostreed daemon is not running or not accessible
|
|
**Solution**:
|
|
```bash
|
|
# Start the daemon
|
|
sudo apt-ostree start-daemon
|
|
|
|
# Check daemon status
|
|
systemctl status aptostreed
|
|
|
|
# Check DBus connection
|
|
busctl --user list | grep aptostree
|
|
|
|
# Restart daemon
|
|
sudo systemctl restart aptostreed
|
|
```
|
|
|
|
#### **Error**: `DBus connection failed`
|
|
**Cause**: DBus communication issues
|
|
**Solution**:
|
|
```bash
|
|
# Check DBus service
|
|
systemctl status dbus
|
|
|
|
# Restart DBus
|
|
sudo systemctl restart dbus
|
|
|
|
# Check DBus logs
|
|
journalctl -u dbus -f
|
|
|
|
# Verify user session
|
|
loginctl show-user $USER
|
|
```
|
|
|
|
### **OSTree Errors**
|
|
|
|
#### **Error**: `OSTree repository not found` or `Invalid OSTree path`
|
|
**Cause**: OSTree repository is corrupted or missing
|
|
**Solution**:
|
|
```bash
|
|
# Check OSTree repository
|
|
ostree admin status
|
|
|
|
# Verify repository integrity
|
|
ostree fsck
|
|
|
|
# Check repository path
|
|
ls -la /ostree/repo/
|
|
|
|
# Reinitialize repository (if necessary)
|
|
sudo ostree admin init-fs /
|
|
```
|
|
|
|
#### **Error**: `Deployment not found` or `Invalid deployment`
|
|
**Cause**: OSTree deployment is corrupted or missing
|
|
**Solution**:
|
|
```bash
|
|
# List deployments
|
|
ostree admin status
|
|
|
|
# Check deployment paths
|
|
ls -la /ostree/deploy/
|
|
|
|
# Verify boot configuration
|
|
ls -la /boot/loader/entries/
|
|
|
|
# Check systemd-boot configuration
|
|
bootctl status
|
|
```
|
|
|
|
### **Package Management Errors**
|
|
|
|
#### **Error**: `Package not found` or `Package installation failed`
|
|
**Cause**: Package not available or dependency issues
|
|
**Solution**:
|
|
```bash
|
|
# Update package lists
|
|
sudo apt update
|
|
|
|
# Check package availability
|
|
apt-cache search <package>
|
|
|
|
# Check package dependencies
|
|
apt-cache show <package>
|
|
|
|
# Verify APT configuration
|
|
cat /etc/apt/sources.list
|
|
```
|
|
|
|
#### **Error**: `Package conflict detected`
|
|
**Cause**: Package conflicts with existing system
|
|
**Solution**:
|
|
```bash
|
|
# Check package conflicts
|
|
apt-ostree db diff
|
|
|
|
# List package overrides
|
|
apt-ostree override list
|
|
|
|
# Check user overlays
|
|
apt-ostree usroverlay list
|
|
|
|
# Resolve conflicts manually
|
|
sudo apt-ostree override reset <package>
|
|
```
|
|
|
|
### **Filesystem Errors**
|
|
|
|
#### **Error**: `Overlay mount failed` or `Filesystem error`
|
|
**Cause**: OverlayFS or filesystem issues
|
|
**Solution**:
|
|
```bash
|
|
# Check overlay support
|
|
cat /proc/filesystems | grep overlay
|
|
|
|
# Check mount points
|
|
mount | grep overlay
|
|
|
|
# Verify filesystem space
|
|
df -h
|
|
|
|
# Check for corrupted overlays
|
|
sudo apt-ostree usroverlay list
|
|
sudo apt-ostree usroverlay remove <overlay>
|
|
```
|
|
|
|
## 🛠️ **Recovery Procedures**
|
|
|
|
### **System Recovery**
|
|
|
|
#### **Recover from Failed Update**
|
|
```bash
|
|
# Check current status
|
|
apt-ostree status
|
|
|
|
# Rollback to previous deployment
|
|
sudo apt-ostree rollback --reboot
|
|
|
|
# If rollback fails, boot from previous deployment
|
|
# Edit bootloader configuration manually
|
|
```
|
|
|
|
#### **Recover Corrupted Repository**
|
|
```bash
|
|
# Stop daemon
|
|
sudo systemctl stop aptostreed
|
|
|
|
# Check repository integrity
|
|
sudo ostree fsck
|
|
|
|
# Repair repository
|
|
sudo ostree fsck --repair
|
|
|
|
# Restart daemon
|
|
sudo systemctl start aptostreed
|
|
```
|
|
|
|
#### **Recover from Boot Failure**
|
|
```bash
|
|
# Boot into recovery mode or previous deployment
|
|
# Check boot configuration
|
|
ls -la /boot/loader/entries/
|
|
|
|
# Verify deployment integrity
|
|
ostree admin status
|
|
|
|
# Reinstall bootloader if necessary
|
|
sudo bootctl install
|
|
```
|
|
|
|
### **Package Recovery**
|
|
|
|
#### **Remove Problematic Packages**
|
|
```bash
|
|
# List installed packages
|
|
apt-ostree db list
|
|
|
|
# Remove problematic package
|
|
sudo apt-ostree uninstall <package>
|
|
|
|
# Check for remaining issues
|
|
apt-ostree status
|
|
```
|
|
|
|
#### **Reset Package Overrides**
|
|
```bash
|
|
# List overrides
|
|
apt-ostree override list
|
|
|
|
# Reset specific override
|
|
sudo apt-ostree override reset <package>
|
|
|
|
# Reset all overrides
|
|
sudo apt-ostree reset --packages
|
|
```
|
|
|
|
#### **Clean User Overlays**
|
|
```bash
|
|
# List overlays
|
|
apt-ostree usroverlay list
|
|
|
|
# Remove specific overlay
|
|
sudo apt-ostree usroverlay remove <overlay>
|
|
|
|
# Clean all overlays
|
|
sudo apt-ostree cleanup --overlays
|
|
```
|
|
|
|
## 📊 **Performance Issues**
|
|
|
|
### **Slow Operations**
|
|
|
|
#### **Slow Package Installation**
|
|
**Symptoms**: Package installation takes unusually long time
|
|
**Solutions**:
|
|
```bash
|
|
# Check system resources
|
|
htop
|
|
iostat -x 1
|
|
|
|
# Check disk I/O
|
|
iotop
|
|
|
|
# Verify network connectivity
|
|
ping -c 3 deb.debian.org
|
|
|
|
# Check APT cache
|
|
apt-cache policy <package>
|
|
```
|
|
|
|
#### **Slow System Updates**
|
|
**Symptoms**: System updates are slow or hang
|
|
**Solutions**:
|
|
```bash
|
|
# Check OSTree repository size
|
|
du -sh /ostree/repo/
|
|
|
|
# Clean old deployments
|
|
sudo apt-ostree cleanup
|
|
|
|
# Check for pending transactions
|
|
apt-ostree status
|
|
|
|
# Restart daemon
|
|
sudo systemctl restart aptostreed
|
|
```
|
|
|
|
### **Memory Issues**
|
|
|
|
#### **High Memory Usage**
|
|
**Symptoms**: System becomes unresponsive, high memory usage
|
|
**Solutions**:
|
|
```bash
|
|
# Check memory usage
|
|
free -h
|
|
ps aux --sort=-%mem | head
|
|
|
|
# Check for memory leaks
|
|
valgrind --tool=memcheck apt-ostree status
|
|
|
|
# Restart daemon
|
|
sudo systemctl restart aptostreed
|
|
```
|
|
|
|
## 🔒 **Security Issues**
|
|
|
|
### **Authorization Problems**
|
|
|
|
#### **Polkit Policy Issues**
|
|
**Symptoms**: Commands fail with authorization errors
|
|
**Solutions**:
|
|
```bash
|
|
# Check Polkit policies
|
|
pkaction --action org.projectatomic.aptostree.status
|
|
|
|
# Verify policy installation
|
|
dpkg -l | grep apt-ostree
|
|
|
|
# Check user session
|
|
loginctl show-user $USER
|
|
|
|
# Reinstall Polkit policies
|
|
sudo apt install --reinstall apt-ostree-polkit
|
|
```
|
|
|
|
#### **User Permission Issues**
|
|
**Symptoms**: User cannot perform authorized operations
|
|
**Solutions**:
|
|
```bash
|
|
# Check user groups
|
|
groups $USER
|
|
|
|
# Verify sudo access
|
|
sudo -l
|
|
|
|
# Check Polkit configuration
|
|
cat /etc/polkit-1/rules.d/50-apt-ostree.rules
|
|
|
|
# Add user to appropriate groups
|
|
sudo usermod -a -G sudo $USER
|
|
```
|
|
|
|
## 📝 **Logging and Debugging**
|
|
|
|
### **Enable Debug Logging**
|
|
```bash
|
|
# Set debug environment
|
|
export RUST_LOG=debug
|
|
export RUST_BACKTRACE=1
|
|
|
|
# Run with debug output
|
|
apt-ostree --debug <command>
|
|
|
|
# Check system logs
|
|
journalctl -u aptostreed -f --since "1 hour ago"
|
|
```
|
|
|
|
### **Collect Debug Information**
|
|
```bash
|
|
# Collect system information
|
|
apt-ostree status --json > status.json
|
|
ostree admin status > ostree-status.txt
|
|
systemctl status aptostreed > daemon-status.txt
|
|
|
|
# Check configuration files
|
|
ls -la /etc/apt-ostree/
|
|
cat /etc/apt-ostree/config.toml
|
|
|
|
# Verify installation
|
|
dpkg -l | grep apt-ostree
|
|
```
|
|
|
|
## 🆘 **Getting Additional Help**
|
|
|
|
### **When to Seek Help**
|
|
- **System won't boot** after apt-ostree operations
|
|
- **Daemon won't start** or respond to commands
|
|
- **Package operations fail** consistently
|
|
- **Performance issues** that persist after troubleshooting
|
|
|
|
### **Information to Collect**
|
|
```bash
|
|
# System information
|
|
uname -a
|
|
cat /etc/os-release
|
|
apt-ostree --version
|
|
|
|
# Status information
|
|
apt-ostree status --json
|
|
ostree admin status
|
|
systemctl status aptostreed
|
|
|
|
# Log files
|
|
journalctl -u aptostreed --since "1 day ago" > daemon-logs.txt
|
|
journalctl --since "1 day ago" | grep apt-ostree > system-logs.txt
|
|
|
|
# Configuration files
|
|
ls -la /etc/apt-ostree/
|
|
cat /etc/apt-ostree/config.toml
|
|
```
|
|
|
|
### **Where to Get Help**
|
|
- **Architecture Documents**: Check relevant architecture documents
|
|
- **Implementation Guides**: Review development and deployment guides
|
|
- **Community Support**: Report issues and seek community help
|
|
- **Development Team**: Contact the development team for critical issues
|
|
|
|
---
|
|
|
|
*This troubleshooting guide covers common issues and solutions. For detailed architecture information and implementation details, refer to the documents in the `docs/apt-ostree-daemon-plan/architecture/` directory.*
|