bootc-docs/composefs-finalize-staged/bootc-composefs-finalize-staged-quick-reference.md

bootc composefs-finalize-staged - Quick Reference

Command Summary

Command	Purpose	Usage
composefs-finalize-staged	Finalize staged composefs deployments	bootc composefs-finalize-staged

Quick Commands

Basic Operations

# Execute composefs-finalize-staged command
bootc composefs-finalize-staged

# Check if command is available
bootc --help | grep composefs-finalize-staged

Systemd Service Operations

# Start service
systemctl start composefs-finalize-staged.service

# Enable service
systemctl enable composefs-finalize-staged.service

# Check service status
systemctl status composefs-finalize-staged.service

# Stop service
systemctl stop composefs-finalize-staged.service

# Restart service
systemctl restart composefs-finalize-staged.service

Service Monitoring

# Check service logs
journalctl -u composefs-finalize-staged.service

# Follow logs in real-time
journalctl -u composefs-finalize-staged.service -f

# Show recent logs
journalctl -u composefs-finalize-staged.service -n 100

# Show logs since specific time
journalctl -u composefs-finalize-staged.service --since "1 hour ago"

Common Options

Option	Purpose	Example
--help	Show help	bootc composefs-finalize-staged --help
--verbose	Verbose output	bootc composefs-finalize-staged -v
--quiet	Quiet output	bootc composefs-finalize-staged -q

Error Codes

Code	Meaning	Solution
0	Success	Command completed successfully
1	General error	Check logs for details
2	No staged deployment	Create staged deployment
3	Non-composefs deployment	Verify deployment type
4	EROFS mount error	Check EROFS image and mount point
5	ESP mount error	Check ESP partition and mount point

Common Issues

No Staged Deployment

# Error: No staged deployment found
# Solution: Check for staged deployment
ls -la /var/lib/composefs-transient-state/

# Create staged deployment if needed
echo "deployment-id" > /var/lib/composefs-transient-state/staged-deployment

Non-Composefs Deployment

# Error: Staged deployment is not a composefs deployment
# Solution: Check deployment type
cat /sysroot/composefs/*/deployment-id.origin

# Verify composefs configuration
grep -i composefs /sysroot/composefs/*/deployment-id.origin

EROFS Mount Error

# Error: Failed to mount EROFS image
# Solution: Check EROFS image
file /path/to/image.erofs

# Check mount point
ls -la /sysroot/

# Try manual mount
mount -t erofs /path/to/image.erofs /mnt/test

ESP Mount Error

# Error: Failed to mount ESP partition
# Solution: Check ESP partition
lsblk | grep -i efi

# Check mount point
ls -la /boot/efi/

# Try manual mount
mount /dev/sda1 /mnt/esp

Environment Variables

Variable	Purpose	Default
RUST_LOG	Log level	info
BOOTC_DEBUG	Debug mode	false
BOOTC_CONFIG	Config file	/etc/bootc/config.toml

Configuration Files

File	Purpose	Location
Main config	Bootc configuration	/etc/bootc/config.toml
Service file	Systemd service	/usr/lib/systemd/system/composefs-finalize-staged.service
Staged deployment	Staged deployment marker	/var/lib/composefs-transient-state/staged-deployment
Composefs state	Composefs state directory	/sysroot/composefs/

Log Files

File	Purpose	Location
System logs	System messages	/var/log/messages
Journal logs	Systemd journal	journalctl -u composefs-finalize-staged.service
Bootc logs	Bootc specific	/var/log/bootc/

Performance Tips

Optimize Operations

# Check system load
uptime

# Check memory usage
free -h

# Check disk usage
df -h /sysroot

# Check I/O usage
iotop -bn1 | head -20

Monitor System

# Check service status
systemctl is-active composefs-finalize-staged.service

# Check service logs
journalctl -u composefs-finalize-staged.service --since "1 hour ago"

# Check system performance
top -bn1 | head -20

Security Considerations

Root Privileges

• All composefs-finalize-staged operations require root privileges
• Use sudo or switch to root user
• Check current user with whoami

Sandboxing

• Service runs with systemd sandboxing
• ProtectHome=yes - restricts home directory access
• ReadOnlyPaths=/etc - prevents /etc modification

Access Control

• Command accesses EROFS images for pristine configuration
• Command accesses ESP partition for bootloader operations
• Command manages system state for deployment management

Best Practices

Regular Operations

• Use systemd service for execution
• Execute early in boot process
• Monitor service status and logs
• Implement proper error handling

Development

• Use in composefs-backend branch
• Test with staged deployments
• Document procedures
• Monitor system health

Production

• Set up monitoring
• Configure alerts
• Regular testing
• Document procedures

Troubleshooting Steps

1. Check service status

   systemctl status composefs-finalize-staged.service
   

2. Check service logs

   journalctl -u composefs-finalize-staged.service --since "1 hour ago"
   

3. Check staged deployment

   ls -la /var/lib/composefs-transient-state/
   cat /var/lib/composefs-transient-state/staged-deployment
   

4. Check composefs state

   ls -la /sysroot/composefs/
   

5. Check EROFS support

   modprobe erofs
   lsmod | grep erofs
   

6. Check ESP partition

   lsblk | grep -i efi
   ls -la /boot/efi/
   

Quick Scripts

Health Check

#!/bin/bash
systemctl is-active composefs-finalize-staged.service && echo "Service healthy"

Service Restart

#!/bin/bash
systemctl restart composefs-finalize-staged.service && echo "Service restarted"

Log Check

#!/bin/bash
journalctl -u composefs-finalize-staged.service -n 50

Staged Deployment Check

#!/bin/bash
[ -f "/var/lib/composefs-transient-state/staged-deployment" ] && echo "Staged deployment found" || echo "No staged deployment"

Integration Examples

Systemd Service

# Create service file
cat > /etc/systemd/system/composefs-finalize-staged.service << EOF
[Unit]
Description=Composefs Finalize Staged Deployment
Documentation=man:bootc(1)
DefaultDependencies=no

RequiresMountsFor=/sysroot
After=local-fs.target
Before=basic.target final.target
After=systemd-journal-flush.service
Conflicts=final.target

[Service]
Type=oneshot
RemainAfterExit=yes
ExecStop=/usr/bin/bootc composefs-finalize-staged
TimeoutStopSec=5m
ProtectHome=yes
ReadOnlyPaths=/etc
EOF

# Enable service
systemctl daemon-reload
systemctl enable composefs-finalize-staged.service

Cron Job

# Add to crontab
echo "0 2 * * * /usr/local/bin/composefs-finalize-staged-maintenance.sh" | crontab -

Monitoring

# Check service health
if ! systemctl is-active composefs-finalize-staged.service > /dev/null 2>&1; then
    echo "WARNING: Composefs finalize staged service not active"
    # Send alert
fi

Service Configuration

Service Dependencies

• RequiresMountsFor=/sysroot - Requires /sysroot to be mounted
• After=local-fs.target - Runs after local filesystems are mounted
• Before=basic.target final.target - Runs before basic and final targets
• After=systemd-journal-flush.service - Runs after journal is flushed

Service Security

• ProtectHome=yes - Protects home directory
• ReadOnlyPaths=/etc - Makes /etc read-only
• TimeoutStopSec=5m - 5-minute timeout for operations

Service Execution

• Type=oneshot - Runs once and exits
• RemainAfterExit=yes - Service remains active after completion
• ExecStop=/usr/bin/bootc composefs-finalize-staged - Command to execute

This quick reference provides essential information for using the bootc composefs-finalize-staged system effectively.