docs: Add comprehensive documentation and update planning
- Add docs/README.md with project overview and current status - Add docs/architecture.md with detailed architecture documentation - Add docs/development.md with development guide for contributors - Update .notes/todo.md to reflect architecture fix completion - Update .notes/plan.md with completed phases and next priorities Architecture fixes (daemon and dbus), bubblewrap integration are now complete. Ready for OCI integration phase.
This commit is contained in:
robojerk
parent
1cc175c110
commit
97a9c40d7e
33 changed files with 4488 additions and 118 deletions
310
DBUS-TESTING.md
Normal file
310
DBUS-TESTING.md
Normal file
|
|
@ -0,0 +1,310 @@
|
|||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
```xml
|
||||
<!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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue