apt-ostree/DBUS-TESTING.md

apt-ostree D-Bus Communication Testing

Overview

This document describes how to test the D-Bus communication between the apt-ostree client and daemon. The daemon architecture is crucial for apt-ostree functionality, and proper D-Bus communication ensures that privileged operations work correctly.

Test Scripts

1. Simple D-Bus Test (scripts/simple-dbus-test.sh)

A basic shell script that performs essential D-Bus communication tests:

# Make executable and run
chmod +x scripts/simple-dbus-test.sh
sudo ./scripts/simple-dbus-test.sh

Tests performed:

• Daemon service status check
• D-Bus service registration verification
• D-Bus introspection test
• Ping method test
• Client-daemon communication test

2. Comprehensive D-Bus Test (scripts/test-dbus-communication.sh)

A comprehensive test suite with 20 different tests:

# Make executable and run
chmod +x scripts/test-dbus-communication.sh
sudo ./scripts/test-dbus-communication.sh

Tests performed:

• Binary and service existence checks
• D-Bus service registration and introspection
• Method and property testing
• Authentication and authorization tests
• Service activation testing
• Client fallback behavior testing
• Signal monitoring

3. Python D-Bus Test (scripts/test-dbus-python.py)

A Python script for programmatic D-Bus testing:

# Make executable and run
chmod +x scripts/test-dbus-python.py
sudo python3 scripts/test-dbus-python.py

Tests performed:

• D-Bus connection establishment
• Object and interface retrieval
• Method invocation (Ping, GetStatus)
• Introspection data retrieval
• Properties testing

Manual Testing Commands

Basic D-Bus Commands

# Check if daemon is running
systemctl status apt-ostreed.service

# List D-Bus services
gdbus list --system | grep aptostree

# Test D-Bus introspection
gdbus introspect --system --dest org.aptostree.dev --object-path /org/aptostree/dev

# Test Ping method
gdbus call --system --dest org.aptostree.dev --object-path /org/aptostree/dev --method org.aptostree.dev.Daemon.Ping

# Test GetStatus method
gdbus call --system --dest org.aptostree.dev --object-path /org/aptostree/dev --method org.aptostree.dev.Daemon.GetStatus

Client-Daemon Communication

# Test client ping to daemon
apt-ostree daemon-ping

# Test client status from daemon
apt-ostree daemon-status

# Test client with daemon unavailable (fallback)
systemctl stop apt-ostreed.service
apt-ostree daemon-ping
systemctl start apt-ostreed.service

D-Bus Monitoring

# Monitor D-Bus signals (timeout after 10 seconds)
timeout 10s gdbus monitor --system --dest org.aptostree.dev

# Monitor daemon logs
journalctl -u apt-ostreed.service -f

Expected Test Results

Successful D-Bus Communication

When D-Bus communication is working correctly, you should see:

1. Daemon Service Status:

   ● apt-ostreed.service - apt-ostree System Management Daemon
   Loaded: loaded (/etc/systemd/system/apt-ostreed.service; enabled)
   Active: active (running)
   

2. D-Bus Service Registration:

   org.aptostree.dev
   

3. D-Bus Introspection:

   <!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
   "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
   <node>
     <interface name="org.aptostree.dev.Daemon">
       <method name="Ping">
         <arg name="response" type="s" direction="out"/>
       </method>
       <method name="GetStatus">
         <arg name="status" type="s" direction="out"/>
       </method>
       <!-- ... other methods ... -->
     </interface>
   </node>
   

4. Ping Method Response:

   ('pong',)
   

5. Client-Daemon Communication:

   Daemon is responding: pong
   

Common Issues and Solutions

Issue 1: Daemon Not Running

Symptoms:

• systemctl status apt-ostreed.service shows inactive
• D-Bus calls fail with "Service not found"

Solutions:

# Start the daemon
sudo systemctl start apt-ostreed.service

# Check logs for errors
journalctl -u apt-ostreed.service --no-pager -n 20

# Verify binary exists and is executable
ls -la /usr/libexec/apt-ostreed

Issue 2: D-Bus Service Not Registered

Symptoms:

• gdbus list --system doesn't show org.aptostree.dev
• D-Bus introspection fails

Solutions:

# Check D-Bus configuration files
ls -la /etc/dbus-1/system.d/org.aptostree.dev.conf
ls -la /usr/share/dbus-1/system-services/org.aptostree.dev.service

# Reload D-Bus configuration
sudo systemctl reload dbus

# Restart the daemon
sudo systemctl restart apt-ostreed.service

Issue 3: Permission Denied

Symptoms:

• D-Bus calls fail with "Permission denied"
• Polkit authentication prompts

Solutions:

# Check Polkit policy
ls -la /usr/share/polkit-1/actions/org.aptostree.dev.policy

# Test with authentication
pkexec gdbus call --system --dest org.aptostree.dev --object-path /org/aptostree/dev --method org.aptostree.dev.Daemon.Ping

Issue 4: Client Fallback Not Working

Symptoms:

• Client hangs when daemon is unavailable
• No graceful fallback to direct operations

Solutions:

# Check client implementation
# Ensure client has timeout and fallback logic
# Test with daemon stopped
sudo systemctl stop apt-ostreed.service
apt-ostree daemon-ping
sudo systemctl start apt-ostreed.service

Testing Checklist

Pre-Test Setup

• Daemon binary installed at /usr/libexec/apt-ostreed
• Systemd service files installed
• D-Bus configuration files installed
• Polkit policy files installed
• OSTree repository initialized

Basic Tests

• Daemon service starts successfully
• D-Bus service is registered
• D-Bus introspection works
• Ping method responds correctly
• GetStatus method returns status

Advanced Tests

• Client-daemon communication works
• Authentication and authorization work
• Service activation works
• Client fallback works when daemon unavailable
• D-Bus signals are properly emitted

Integration Tests

• Package installation via daemon
• System status via daemon
• Rollback operations via daemon
• Automatic updates via daemon

Troubleshooting

Debug Mode

Enable debug logging in the daemon configuration:

# Edit daemon config
sudo nano /etc/apt-ostree/apt-ostreed.conf

# Add debug logging
[Daemon]
LogLevel=debug
LogFile=/var/log/apt-ostree/debug.log

# Restart daemon
sudo systemctl restart apt-ostreed.service

D-Bus Debug Mode

Enable D-Bus debug logging:

# Set environment variable
export DBUS_VERBOSE=1

# Run D-Bus commands with debug output
gdbus call --system --dest org.aptostree.dev --object-path /org/aptostree/dev --method org.aptostree.dev.Daemon.Ping

Systemd Debug Mode

Enable systemd debug logging:

# Enable debug logging
sudo systemctl --log-level=debug status apt-ostreed.service

# View detailed logs
journalctl -u apt-ostreed.service --no-pager -n 50

Success Criteria

D-Bus communication is considered successful when:

1. ✅ Daemon Service: Running and healthy
2. ✅ D-Bus Registration: Service properly registered
3. ✅ Method Calls: All D-Bus methods respond correctly
4. ✅ Client Communication: Client can communicate with daemon
5. ✅ Authentication: Proper authorization works
6. ✅ Fallback: Client handles daemon unavailability gracefully
7. ✅ Integration: All apt-ostree commands work via daemon

Next Steps

After successful D-Bus testing:

1. Test Privileged Operations: Verify package installation works via daemon
2. Test Automatic Updates: Verify automatic update services work
3. Test Integration: Test complete workflows with daemon support
4. Performance Testing: Measure D-Bus communication performance
5. Security Testing: Verify proper authorization and sandboxing

The D-Bus communication is the foundation of the apt-ostree daemon architecture. Successful testing ensures that the client and daemon can communicate properly for all privileged operations.