Fix YAML linting issues and update system requirements to Debian 13+
- Fix trailing spaces and blank lines in Forgejo workflows - Update system requirements from Ubuntu Jammy/Bookworm to Debian 13+ (Trixie) - Update test treefile to use Debian Trixie instead of Ubuntu Jammy - Update documentation to reflect modern system requirements - Fix yamllint errors for CI/CD functionality - Ensure compatibility with modern OSTree and libapt versions
This commit is contained in:
parent
ec0da91864
commit
3dec23f8f7
85 changed files with 12569 additions and 1088 deletions
|
|
@ -527,7 +527,7 @@ pub fn get_package(&self, name: &str) -> AptOstreeResult<Option<Package>> {
|
|||
#### **Distribution Tests - ENHANCED REQUIREMENTS**
|
||||
- **✅ Debian 13 Trixie**: Test in Trixie environment
|
||||
- **✅ Ubuntu 25.04 Plucky Puffin**: Test in Plucky Puffin environment
|
||||
- **✅ Backward Compatibility**: Test in current Debian 12 environment
|
||||
- **✅ Forward Compatibility**: Test in Debian 14+ (Forky) environment
|
||||
- **❌ Complex Scenarios**: Test apt-ostree's core functionality
|
||||
- **❌ Daemon Architecture**: Test CLI-daemon separation
|
||||
- **❌ Transaction Scenarios**: Test complex transaction flows
|
||||
|
|
|
|||
224
docs/apt-ostree-daemon-plan/development-commands-analysis.md
Normal file
224
docs/apt-ostree-daemon-plan/development-commands-analysis.md
Normal file
|
|
@ -0,0 +1,224 @@
|
|||
# Development Commands Analysis: rpm-ostree Integration
|
||||
|
||||
## Overview
|
||||
|
||||
This document analyzes the missing development and debugging commands from rpm-ostree that should be integrated into apt-ostree. These commands are marked with `RPM_OSTREE_BUILTIN_FLAG_HIDDEN` and are essential for development, testing, and debugging purposes.
|
||||
|
||||
## Commands Analysis
|
||||
|
||||
### 1. testutils Command
|
||||
|
||||
**Purpose**: Development debugging tool for testing and development workflows.
|
||||
|
||||
**Flags**: `RPM_OSTREE_BUILTIN_FLAG_LOCAL_CMD | RPM_OSTREE_BUILTIN_FLAG_HIDDEN`
|
||||
|
||||
**Subcommands**:
|
||||
- `inject-pkglist` - Inject package list metadata into OSTree commits
|
||||
- `script-shell` - Run scripts in bubblewrap containers
|
||||
- `generate-synthetic-upgrade` - Generate synthetic OS updates by modifying ELF files
|
||||
- `integration-read-only` - Run integration tests on booted machine
|
||||
- `c-units` - Run C unit tests
|
||||
- `moo` - Test command for development verification
|
||||
|
||||
**Implementation Details**:
|
||||
|
||||
#### C++ Side (rpmostree-builtin-testutils.cxx)
|
||||
```cpp
|
||||
// inject-pkglist: Creates new commit with pkglist metadata
|
||||
// - Reads existing commit
|
||||
// - Creates RPM database package list
|
||||
// - Writes new commit with pkglist metadata
|
||||
// - Updates ref to point to new commit
|
||||
|
||||
// script-shell: Runs scripts in isolated containers
|
||||
// - Uses bubblewrap for containerization
|
||||
// - Mounts root filesystem
|
||||
// - Executes test scripts safely
|
||||
```
|
||||
|
||||
#### Rust Side (testutils.rs)
|
||||
```rust
|
||||
// generate-synthetic-upgrade: Modifies ELF binaries
|
||||
// - Finds ELF files in system directories
|
||||
// - Mutates specified percentage of binaries
|
||||
// - Creates new OSTree commit with modified files
|
||||
// - Useful for testing upgrade paths
|
||||
|
||||
// integration-read-only: Validates system state
|
||||
// - Tests status JSON parsing
|
||||
// - Validates package variants
|
||||
// - Ensures client bindings work correctly
|
||||
```
|
||||
|
||||
**Integration Plan for apt-ostree**:
|
||||
1. Create `src/commands/testutils.rs` module
|
||||
2. Implement all subcommands with APT equivalents
|
||||
3. Add to CLI with hidden flag
|
||||
4. Integrate with existing command structure
|
||||
|
||||
### 2. shlib-backend Command
|
||||
|
||||
**Purpose**: Shared library backend for IPC operations and package management.
|
||||
|
||||
**Flags**: `RPM_OSTREE_BUILTIN_FLAG_LOCAL_CMD | RPM_OSTREE_BUILTIN_FLAG_HIDDEN`
|
||||
|
||||
**Subcommands**:
|
||||
- `get-basearch` - Get base architecture
|
||||
- `varsubst-basearch` - Variable substitution for architecture
|
||||
- `packagelist-from-commit` - Extract package list from OSTree commit
|
||||
|
||||
**Implementation Details**:
|
||||
```cpp
|
||||
// IPC-based communication using Unix domain sockets
|
||||
// - Creates sealed memfd for data transfer
|
||||
// - Uses DNF context for package operations
|
||||
// - Integrates with OSTree repository operations
|
||||
// - Handles package list extraction and formatting
|
||||
```
|
||||
|
||||
**Integration Plan for apt-ostree**:
|
||||
1. Create `src/commands/shlib_backend.rs` module
|
||||
2. Replace DNF with APT equivalents
|
||||
3. Implement IPC communication layer
|
||||
4. Add architecture detection and variable substitution
|
||||
5. Integrate with OSTree operations
|
||||
|
||||
### 3. internals Command
|
||||
|
||||
**Purpose**: Internal system commands for advanced operations.
|
||||
|
||||
**Status**: Referenced in header file but implementation not found in current rpm-ostree source.
|
||||
|
||||
**Flags**: Not specified (likely `RPM_OSTREE_BUILTIN_FLAG_LOCAL_CMD`)
|
||||
|
||||
**Integration Plan for apt-ostree**:
|
||||
1. Research if this command exists in newer rpm-ostree versions
|
||||
2. If not implemented, consider what internal operations would be useful
|
||||
3. Implement as placeholder for future development
|
||||
4. Add to CLI with appropriate flags
|
||||
|
||||
## Implementation Strategy
|
||||
|
||||
### Phase 1: Core Infrastructure
|
||||
1. **Command Structure**: Add hidden command support to CLI
|
||||
2. **Flag System**: Implement `APT_OSTREE_BUILTIN_FLAG_HIDDEN` equivalent
|
||||
3. **Module Organization**: Create development commands module
|
||||
|
||||
### Phase 2: testutils Implementation
|
||||
1. **inject-pkglist**: APT package list injection
|
||||
2. **script-shell**: Bubblewrap container execution
|
||||
3. **synthetic-upgrade**: ELF binary modification for testing
|
||||
4. **integration-tests**: System validation and testing
|
||||
|
||||
### Phase 3: shlib-backend Implementation
|
||||
1. **IPC Layer**: Unix domain socket communication
|
||||
2. **Package Operations**: APT-based package management
|
||||
3. **Architecture Detection**: Debian architecture handling
|
||||
4. **Variable Substitution**: APT-specific variable handling
|
||||
|
||||
### Phase 4: Integration and Testing
|
||||
1. **Command Registration**: Add to main command dispatch
|
||||
2. **Hidden Flag Support**: Implement in CLI help system
|
||||
3. **Testing Framework**: Integration with existing test suite
|
||||
4. **Documentation**: Developer and testing guides
|
||||
|
||||
## Technical Considerations
|
||||
|
||||
### APT vs DNF Differences
|
||||
- **Package Format**: DEB vs RPM
|
||||
- **Database Structure**: APT cache vs DNF sack
|
||||
- **Architecture Names**: Debian vs Red Hat conventions
|
||||
- **Variable Substitution**: APT-specific variables
|
||||
|
||||
### OSTree Integration
|
||||
- **Package Metadata**: APT package list format
|
||||
- **Commit Structure**: OSTree commit metadata
|
||||
- **Repository Operations**: OSTree repo integration
|
||||
- **Deployment Management**: System deployment handling
|
||||
|
||||
### Security and Isolation
|
||||
- **Bubblewrap**: Container execution for scripts
|
||||
- **File Descriptors**: Secure IPC communication
|
||||
- **Permission Handling**: Root and user operations
|
||||
- **Resource Limits**: Memory and process constraints
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
src/commands/
|
||||
├── testutils.rs # Development testing utilities
|
||||
├── shlib_backend.rs # Shared library backend
|
||||
└── internals.rs # Internal system commands (future)
|
||||
|
||||
src/cli.rs # Add hidden command support
|
||||
src/commands/mod.rs # Register development commands
|
||||
```
|
||||
|
||||
## CLI Integration
|
||||
|
||||
### Hidden Command Support
|
||||
```rust
|
||||
#[derive(Subcommand)]
|
||||
pub enum Commands {
|
||||
// ... existing commands ...
|
||||
|
||||
/// Development and debugging tools (hidden)
|
||||
#[command(hide = true)]
|
||||
Testutils(TestutilsArgs),
|
||||
|
||||
/// Shared library backend (hidden)
|
||||
#[command(hide = true)]
|
||||
ShlibBackend(ShlibBackendArgs),
|
||||
|
||||
/// Internal system commands (hidden)
|
||||
#[command(hide = true)]
|
||||
Internals(InternalsArgs),
|
||||
}
|
||||
```
|
||||
|
||||
### Flag System
|
||||
```rust
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub struct CommandFlags {
|
||||
pub local_cmd: bool,
|
||||
pub hidden: bool,
|
||||
pub requires_root: bool,
|
||||
pub container_capable: bool,
|
||||
pub supports_pkg_installs: bool,
|
||||
}
|
||||
```
|
||||
|
||||
## Benefits of Integration
|
||||
|
||||
### Development Workflow
|
||||
1. **Testing**: Automated testing and validation
|
||||
2. **Debugging**: Package list inspection and modification
|
||||
3. **Integration**: System state validation
|
||||
4. **Scripting**: Safe script execution in containers
|
||||
|
||||
### Quality Assurance
|
||||
1. **Package Management**: Validate APT integration
|
||||
2. **OSTree Operations**: Test commit and deployment logic
|
||||
3. **System Integration**: Verify daemon and client communication
|
||||
4. **Error Handling**: Test edge cases and failure modes
|
||||
|
||||
### Maintenance and Support
|
||||
1. **Troubleshooting**: Debug package and deployment issues
|
||||
2. **Development**: Rapid iteration and testing
|
||||
3. **Documentation**: Generate system state reports
|
||||
4. **Validation**: Ensure system consistency
|
||||
|
||||
## Conclusion
|
||||
|
||||
Integrating these development commands from rpm-ostree into apt-ostree will provide essential tools for development, testing, and debugging. The commands are designed to be hidden from normal users while providing powerful capabilities for developers and system administrators.
|
||||
|
||||
The implementation should maintain the same logical structure and behavior as rpm-ostree while adapting to APT-specific package management and Debian system conventions. This will ensure that apt-ostree provides the same level of development support as the original rpm-ostree implementation.
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Research**: Verify current rpm-ostree implementation status
|
||||
2. **Design**: Create detailed implementation specifications
|
||||
3. **Implementation**: Develop commands with proper testing
|
||||
4. **Integration**: Add to CLI and command dispatch system
|
||||
5. **Testing**: Validate functionality and performance
|
||||
6. **Documentation**: Create developer and testing guides
|
||||
|
|
@ -0,0 +1,687 @@
|
|||
# Development Commands Implementation Guide
|
||||
|
||||
## Technical Implementation Details
|
||||
|
||||
This document provides detailed technical specifications for implementing the missing development commands from rpm-ostree into apt-ostree.
|
||||
|
||||
## 1. testutils Command Implementation
|
||||
|
||||
### Command Structure
|
||||
```rust
|
||||
#[derive(Subcommand)]
|
||||
pub enum TestutilsSubcommands {
|
||||
/// Inject package list metadata into OSTree commits
|
||||
InjectPkglist(InjectPkglistArgs),
|
||||
|
||||
/// Run scripts in bubblewrap containers
|
||||
ScriptShell(ScriptShellArgs),
|
||||
|
||||
/// Generate synthetic OS updates by modifying ELF files
|
||||
GenerateSyntheticUpgrade(GenerateSyntheticUpgradeArgs),
|
||||
|
||||
/// Run integration tests on booted machine
|
||||
IntegrationReadOnly,
|
||||
|
||||
/// Run C unit tests
|
||||
CUnits,
|
||||
|
||||
/// Test command for development verification
|
||||
Moo,
|
||||
}
|
||||
```
|
||||
|
||||
### Argument Structures
|
||||
```rust
|
||||
#[derive(Args)]
|
||||
pub struct InjectPkglistArgs {
|
||||
/// Repository path
|
||||
pub repo: String,
|
||||
|
||||
/// OSTree reference
|
||||
pub refspec: String,
|
||||
}
|
||||
|
||||
#[derive(Args)]
|
||||
pub struct ScriptShellArgs {
|
||||
/// Root path for script execution
|
||||
#[arg(default_value = "/")]
|
||||
pub rootpath: String,
|
||||
}
|
||||
|
||||
#[derive(Args)]
|
||||
pub struct GenerateSyntheticUpgradeArgs {
|
||||
/// Repository path
|
||||
#[arg(long)]
|
||||
pub repo: String,
|
||||
|
||||
/// Source reference
|
||||
#[arg(long = "srcref")]
|
||||
pub src_ref: Option<String>,
|
||||
|
||||
/// OSTree reference
|
||||
#[arg(long = "ref")]
|
||||
pub ostref: String,
|
||||
|
||||
/// Percentage of binaries to modify
|
||||
#[arg(long, default_value = "30")]
|
||||
pub percentage: u32,
|
||||
|
||||
/// Commit version
|
||||
#[arg(long)]
|
||||
pub commit_version: Option<String>,
|
||||
}
|
||||
```
|
||||
|
||||
### Core Implementation Functions
|
||||
|
||||
#### inject_pkglist
|
||||
```rust
|
||||
impl TestutilsCommand {
|
||||
fn inject_pkglist(&self, args: &InjectPkglistArgs) -> AptOstreeResult<()> {
|
||||
// 1. Parse refspec into remote and ref
|
||||
let (remote, ref_name) = self.parse_refspec(&args.refspec)?;
|
||||
|
||||
// 2. Open OSTree repository
|
||||
let repo = OstreeRepo::open_at(AT_FDCWD, &args.repo)?;
|
||||
|
||||
// 3. Resolve reference to commit
|
||||
let checksum = repo.resolve_rev(&args.refspec, false)?;
|
||||
|
||||
// 4. Load existing commit
|
||||
let commit = repo.load_commit(&checksum)?;
|
||||
|
||||
// 5. Check if pkglist already exists
|
||||
if self.has_pkglist_metadata(&commit) {
|
||||
println!("Refspec '{}' already has pkglist metadata; exiting.", args.refspec);
|
||||
return Ok(());
|
||||
}
|
||||
|
||||
// 6. Create APT package list
|
||||
let pkglist = self.create_apt_pkglist_variant(&repo, &checksum)?;
|
||||
|
||||
// 7. Create new commit with pkglist metadata
|
||||
let new_meta = self.add_pkglist_to_metadata(&commit, &pkglist)?;
|
||||
|
||||
// 8. Write new commit
|
||||
let new_checksum = self.write_new_commit(&repo, &checksum, &new_meta)?;
|
||||
|
||||
// 9. Update reference
|
||||
repo.set_ref_immediate(&remote, &ref_name, &new_checksum)?;
|
||||
|
||||
println!("{} => {}", args.refspec, new_checksum);
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn create_apt_pkglist_variant(&self, repo: &OstreeRepo, commit: &str) -> AptOstreeResult<GVariant> {
|
||||
// Create APT package list from commit
|
||||
// This replaces the RPM-specific logic with APT equivalents
|
||||
let apt_manager = AptManager::new();
|
||||
let packages = apt_manager.get_packages_from_commit(repo, commit)?;
|
||||
|
||||
// Convert to GVariant format compatible with OSTree
|
||||
self.packages_to_gvariant(&packages)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### script_shell
|
||||
```rust
|
||||
impl TestutilsCommand {
|
||||
fn script_shell(&self, args: &ScriptShellArgs) -> AptOstreeResult<()> {
|
||||
// 1. Open root filesystem directory
|
||||
let rootfs_dfd = self.open_rootfs_dir(&args.rootpath)?;
|
||||
|
||||
// 2. Run script in bubblewrap container
|
||||
self.run_script_in_bwrap_container(
|
||||
rootfs_dfd,
|
||||
None,
|
||||
true,
|
||||
"testscript",
|
||||
None,
|
||||
None,
|
||||
None,
|
||||
None,
|
||||
STDIN_FILENO,
|
||||
)
|
||||
}
|
||||
|
||||
fn run_script_in_bwrap_container(
|
||||
&self,
|
||||
rootfs_dfd: i32,
|
||||
env: Option<&[String]>,
|
||||
read_only: bool,
|
||||
script_name: &str,
|
||||
user: Option<&str>,
|
||||
group: Option<&str>,
|
||||
cwd: Option<&str>,
|
||||
extra_args: Option<&[String]>,
|
||||
stdin_fd: i32,
|
||||
) -> AptOstreeResult<()> {
|
||||
// Implement bubblewrap container execution
|
||||
// This provides safe script execution environment
|
||||
let mut cmd = Command::new("bwrap");
|
||||
|
||||
// Add bubblewrap arguments for isolation
|
||||
cmd.args(&[
|
||||
"--dev-bind", "/", "/",
|
||||
"--proc", "/proc",
|
||||
"--tmpfs", "/tmp",
|
||||
]);
|
||||
|
||||
if read_only {
|
||||
cmd.arg("--ro-bind");
|
||||
}
|
||||
|
||||
// Execute script
|
||||
cmd.arg("bash")
|
||||
.arg("-c")
|
||||
.arg(script_name)
|
||||
.stdin(unsafe { std::os::unix::io::FromRawFd::from_raw_fd(stdin_fd) });
|
||||
|
||||
let status = cmd.status()?;
|
||||
if !status.success() {
|
||||
return Err(AptOstreeError::System("Script execution failed".to_string()));
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### generate_synthetic_upgrade
|
||||
```rust
|
||||
impl TestutilsCommand {
|
||||
fn generate_synthetic_upgrade(&self, args: &GenerateSyntheticUpgradeArgs) -> AptOstreeResult<()> {
|
||||
// 1. Remount sysroot as read-write
|
||||
self.remount_sysroot_rw()?;
|
||||
|
||||
// 2. Create temporary directory
|
||||
let tempdir = tempfile::tempdir_in(Path::new(&args.repo).join("tmp"))?;
|
||||
let tmp_rootfs = tempdir.path().join("rootfs");
|
||||
fs::create_dir(&tmp_rootfs)?;
|
||||
|
||||
// 3. Create note file
|
||||
let notepath = tempdir.path().join("note");
|
||||
fs::write(¬epath, "Synthetic upgrade")?;
|
||||
|
||||
// 4. Check for objcopy availability
|
||||
let have_objcopy = Path::new("/usr/bin/objcopy").exists();
|
||||
|
||||
// 5. Mutate executables
|
||||
let mutated = self.mutate_executables(
|
||||
&tmp_rootfs,
|
||||
args.percentage,
|
||||
¬epath,
|
||||
have_objcopy,
|
||||
)?;
|
||||
|
||||
// 6. Create new OSTree commit
|
||||
self.create_synthetic_commit(&args.repo, &args.ostref, &tmp_rootfs, &args.src_ref)?;
|
||||
|
||||
println!("Mutated ELF files: {}", mutated);
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn mutate_executables(
|
||||
&self,
|
||||
dest: &Path,
|
||||
percentage: u32,
|
||||
notepath: &Path,
|
||||
have_objcopy: bool,
|
||||
) -> AptOstreeResult<u32> {
|
||||
let mut mutated = 0;
|
||||
let binary_dirs = &["usr/bin", "usr/lib", "usr/lib64"];
|
||||
|
||||
for binary_dir in binary_dirs {
|
||||
let src_path = Path::new("/").join(binary_dir);
|
||||
if src_path.exists() {
|
||||
let dest_path = dest.join(binary_dir);
|
||||
fs::create_dir_all(&dest_path)?;
|
||||
|
||||
mutated += self.mutate_executables_in_dir(
|
||||
&src_path,
|
||||
&dest_path,
|
||||
percentage,
|
||||
notepath,
|
||||
have_objcopy,
|
||||
)?;
|
||||
}
|
||||
}
|
||||
|
||||
Ok(mutated)
|
||||
}
|
||||
|
||||
fn mutate_executables_in_dir(
|
||||
&self,
|
||||
src: &Path,
|
||||
dest: &Path,
|
||||
percentage: u32,
|
||||
notepath: &Path,
|
||||
have_objcopy: bool,
|
||||
) -> AptOstreeResult<u32> {
|
||||
let mut mutated = 0;
|
||||
|
||||
for entry in fs::read_dir(src)? {
|
||||
let entry = entry?;
|
||||
let path = entry.path();
|
||||
|
||||
if path.is_file() && self.is_elf_executable(&path)? {
|
||||
if self.should_mutate(percentage) {
|
||||
self.mutate_one_executable(&path, dest, notepath, have_objcopy)?;
|
||||
mutated += 1;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Ok(mutated)
|
||||
}
|
||||
|
||||
fn is_elf_executable(&self, path: &Path) -> AptOstreeResult<bool> {
|
||||
let mut file = fs::File::open(path)?;
|
||||
let mut buf = [0; 5];
|
||||
|
||||
file.read_exact(&mut buf)?;
|
||||
|
||||
Ok(buf[0] == 0x7F && &buf[1..4] == b"ELF")
|
||||
}
|
||||
|
||||
fn should_mutate(&self, percentage: u32) -> bool {
|
||||
let mut rng = rand::thread_rng();
|
||||
rng.gen_range(1..=100) <= percentage
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 2. shlib-backend Command Implementation
|
||||
|
||||
### Command Structure
|
||||
```rust
|
||||
#[derive(Subcommand)]
|
||||
pub enum ShlibBackendSubcommands {
|
||||
/// Get base architecture
|
||||
GetBasearch,
|
||||
|
||||
/// Variable substitution for architecture
|
||||
VarsubstBasearch {
|
||||
/// Source string for substitution
|
||||
source: String,
|
||||
},
|
||||
|
||||
/// Extract package list from OSTree commit
|
||||
PackagelistFromCommit {
|
||||
/// Commit hash
|
||||
commit: String,
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Core Implementation
|
||||
```rust
|
||||
impl ShlibBackendCommand {
|
||||
fn handle_subcommand(&self, subcommand: &ShlibBackendSubcommands) -> AptOstreeResult<()> {
|
||||
// 1. Create IPC socket
|
||||
let ipc_sock = self.create_ipc_socket()?;
|
||||
|
||||
// 2. Handle subcommand
|
||||
let result = match subcommand {
|
||||
ShlibBackendSubcommands::GetBasearch => self.get_basearch(),
|
||||
ShlibBackendSubcommands::VarsubstBasearch { source } => {
|
||||
self.varsubst_basearch(source)
|
||||
}
|
||||
ShlibBackendSubcommands::PackagelistFromCommit { commit } => {
|
||||
self.packagelist_from_commit(commit)
|
||||
}
|
||||
}?;
|
||||
|
||||
// 3. Send result via IPC
|
||||
self.send_memfd_result(&ipc_sock, result)?;
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn get_basearch(&self) -> AptOstreeResult<GVariant> {
|
||||
// Get base architecture using APT
|
||||
let apt_manager = AptManager::new();
|
||||
let arch = apt_manager.get_base_architecture()?;
|
||||
|
||||
Ok(GVariant::new_string(arch))
|
||||
}
|
||||
|
||||
fn varsubst_basearch(&self, source: &str) -> AptOstreeResult<GVariant> {
|
||||
// Get APT variable substitutions
|
||||
let apt_manager = AptManager::new();
|
||||
let varsubsts = apt_manager.get_variable_substitutions()?;
|
||||
|
||||
// Perform variable substitution
|
||||
let result = self.substitute_variables(source, &varsubsts)?;
|
||||
|
||||
Ok(GVariant::new_string(result))
|
||||
}
|
||||
|
||||
fn packagelist_from_commit(&self, commit: &str) -> AptOstreeResult<GVariant> {
|
||||
// 1. Open OSTree repository
|
||||
let repo = OstreeRepo::open_at(AT_FDCWD, ".")?;
|
||||
|
||||
// 2. Get package list from commit
|
||||
let packages = self.get_packages_from_commit(&repo, commit)?;
|
||||
|
||||
// 3. Convert to GVariant format
|
||||
let pkglist = self.packages_to_gvariant(&packages)?;
|
||||
|
||||
Ok(GVariant::new_maybe(
|
||||
"aptostree.shlib.ipc.pkglist",
|
||||
Some(&pkglist),
|
||||
))
|
||||
}
|
||||
|
||||
fn create_ipc_socket(&self) -> AptOstreeResult<GSocket> {
|
||||
// Create IPC socket using file descriptor
|
||||
let fd = std::env::var("APT_OSTREE_SHLIB_IPC_FD")
|
||||
.ok()
|
||||
.and_then(|s| s.parse::<i32>().ok())
|
||||
.ok_or_else(|| {
|
||||
AptOstreeError::System("APT_OSTREE_SHLIB_IPC_FD environment variable not set".to_string())
|
||||
})?;
|
||||
|
||||
GSocket::new_from_fd(fd)
|
||||
}
|
||||
|
||||
fn send_memfd_result(&self, ipc_sock: &GSocket, data: GVariant) -> AptOstreeResult<()> {
|
||||
// 1. Create sealed memfd
|
||||
let memfd = self.create_sealed_memfd("apt-ostree-shlib-backend", &data)?;
|
||||
|
||||
// 2. Send via Unix domain socket
|
||||
let fdarray = [memfd, -1];
|
||||
let list = GUnixFDList::new_from_array(&fdarray, 1);
|
||||
let message = GUnixFDMessage::new_with_fd_list(&list);
|
||||
|
||||
let buffer = [0xFF];
|
||||
let ov = GOutputVector {
|
||||
buffer: &buffer,
|
||||
size: buffer.len(),
|
||||
};
|
||||
|
||||
let sent = ipc_sock.send_message(
|
||||
None,
|
||||
&[ov],
|
||||
&[&message],
|
||||
GSocketMsgFlags::NONE,
|
||||
)?;
|
||||
|
||||
if sent != 1 {
|
||||
return Err(AptOstreeError::System("Failed to send IPC message".to_string()));
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 3. internals Command Implementation
|
||||
|
||||
### Command Structure
|
||||
```rust
|
||||
#[derive(Subcommand)]
|
||||
pub enum InternalsSubcommands {
|
||||
/// Internal system diagnostics
|
||||
Diagnostics,
|
||||
|
||||
/// System state validation
|
||||
ValidateState,
|
||||
|
||||
/// Debug information dump
|
||||
DebugDump,
|
||||
}
|
||||
```
|
||||
|
||||
### Core Implementation
|
||||
```rust
|
||||
impl InternalsCommand {
|
||||
fn handle_subcommand(&self, subcommand: &InternalsSubcommands) -> AptOstreeResult<()> {
|
||||
match subcommand {
|
||||
InternalsSubcommands::Diagnostics => self.run_diagnostics(),
|
||||
InternalsSubcommands::ValidateState => self.validate_system_state(),
|
||||
InternalsSubcommands::DebugDump => self.dump_debug_info(),
|
||||
}
|
||||
}
|
||||
|
||||
fn run_diagnostics(&self) -> AptOstreeResult<()> {
|
||||
println!("🔍 Running Internal Diagnostics");
|
||||
println!("===============================");
|
||||
|
||||
// Check system components
|
||||
self.check_ostree_system()?;
|
||||
self.check_apt_system()?;
|
||||
self.check_daemon_status()?;
|
||||
self.check_file_permissions()?;
|
||||
|
||||
println!("Diagnostics completed successfully");
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn validate_system_state(&self) -> AptOstreeResult<()> {
|
||||
println!("✅ Validating System State");
|
||||
println!("===========================");
|
||||
|
||||
// Validate OSTree state
|
||||
let ostree_manager = OstreeManager::new();
|
||||
if ostree_manager.is_available() {
|
||||
println!("OSTree: Available");
|
||||
self.validate_ostree_state(&ostree_manager)?;
|
||||
} else {
|
||||
println!("OSTree: Not available");
|
||||
}
|
||||
|
||||
// Validate APT state
|
||||
let apt_manager = AptManager::new();
|
||||
self.validate_apt_state(&apt_manager)?;
|
||||
|
||||
println!("System state validation completed");
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn dump_debug_info(&self) -> AptOstreeResult<()> {
|
||||
println!("🐛 Debug Information Dump");
|
||||
println!("=========================");
|
||||
|
||||
// System information
|
||||
self.dump_system_info()?;
|
||||
|
||||
// OSTree information
|
||||
self.dump_ostree_info()?;
|
||||
|
||||
// APT information
|
||||
self.dump_apt_info()?;
|
||||
|
||||
// Daemon information
|
||||
self.dump_daemon_info()?;
|
||||
|
||||
println!("Debug information dump completed");
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 4. CLI Integration
|
||||
|
||||
### Hidden Command Support
|
||||
```rust
|
||||
// Add to src/cli.rs
|
||||
#[derive(Subcommand)]
|
||||
pub enum Commands {
|
||||
// ... existing commands ...
|
||||
|
||||
/// Development and debugging tools (hidden)
|
||||
#[command(hide = true)]
|
||||
Testutils(TestutilsArgs),
|
||||
|
||||
/// Shared library backend (hidden)
|
||||
#[command(hide = true)]
|
||||
ShlibBackend(ShlibBackendArgs),
|
||||
|
||||
/// Internal system commands (hidden)
|
||||
#[command(hide = true)]
|
||||
Internals(InternalsArgs),
|
||||
}
|
||||
|
||||
#[derive(Args)]
|
||||
pub struct TestutilsArgs {
|
||||
#[command(subcommand)]
|
||||
pub subcommand: TestutilsSubcommands,
|
||||
}
|
||||
|
||||
#[derive(Args)]
|
||||
pub struct ShlibBackendArgs {
|
||||
#[command(subcommand)]
|
||||
pub subcommand: ShlibBackendSubcommands,
|
||||
}
|
||||
|
||||
#[derive(Args)]
|
||||
pub struct InternalsArgs {
|
||||
#[command(subcommand)]
|
||||
pub subcommand: InternalsSubcommands,
|
||||
}
|
||||
```
|
||||
|
||||
### Command Registration
|
||||
```rust
|
||||
// Add to src/commands/mod.rs
|
||||
pub mod testutils;
|
||||
pub mod shlib_backend;
|
||||
pub mod internals;
|
||||
|
||||
// In register_commands function
|
||||
self.register(Box::new(testutils::TestutilsCommand::new()));
|
||||
self.register(Box::new(shlib_backend::ShlibBackendCommand::new()));
|
||||
self.register(Box::new(internals::InternalsCommand::new()));
|
||||
```
|
||||
|
||||
### Main Dispatch
|
||||
```rust
|
||||
// Add to src/main.rs match statement
|
||||
cli::Commands::Testutils(args) => {
|
||||
let args_vec = vec!["testutils".to_string()];
|
||||
commands::testutils::TestutilsCommand::new().execute(&args_vec)
|
||||
},
|
||||
cli::Commands::ShlibBackend(args) => {
|
||||
let args_vec = vec!["shlib-backend".to_string()];
|
||||
commands::shlib_backend::ShlibBackendCommand::new().execute(&args_vec)
|
||||
},
|
||||
cli::Commands::Internals(args) => {
|
||||
let args_vec = vec!["internals".to_string()];
|
||||
commands::internals::InternalsCommand::new().execute(&args_vec)
|
||||
},
|
||||
```
|
||||
|
||||
## 5. Dependencies and Features
|
||||
|
||||
### Cargo.toml Additions
|
||||
```toml
|
||||
[dependencies]
|
||||
# For bubblewrap integration
|
||||
bubblewrap = "0.1"
|
||||
# For ELF file manipulation
|
||||
goblin = "0.8"
|
||||
# For random number generation
|
||||
rand = "0.8"
|
||||
# For temporary directories
|
||||
tempfile = "3.0"
|
||||
# For file operations
|
||||
cap-std = "1.0"
|
||||
cap-std-ext = "1.0"
|
||||
# For system calls
|
||||
libc = "0.2"
|
||||
```
|
||||
|
||||
### Feature Flags
|
||||
```toml
|
||||
[features]
|
||||
# Development commands (hidden by default)
|
||||
development = ["bubblewrap", "goblin", "rand", "tempfile"]
|
||||
# Full development support
|
||||
dev-full = ["development", "cap-std", "cap-std-ext"]
|
||||
```
|
||||
|
||||
## 6. Testing and Validation
|
||||
|
||||
### Unit Tests
|
||||
```rust
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_inject_pkglist() {
|
||||
// Test package list injection
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_script_shell() {
|
||||
// Test script execution
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_synthetic_upgrade() {
|
||||
// Test synthetic upgrade generation
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_shlib_backend() {
|
||||
// Test shared library backend
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_internals() {
|
||||
// Test internal commands
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Integration Tests
|
||||
```rust
|
||||
#[cfg(test)]
|
||||
mod integration_tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_full_development_workflow() {
|
||||
// Test complete development workflow
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_debugging_tools() {
|
||||
// Test debugging capabilities
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_system_validation() {
|
||||
// Test system validation tools
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 7. Security Considerations
|
||||
|
||||
### Bubblewrap Integration
|
||||
- **Isolation**: Scripts run in isolated containers
|
||||
- **Resource Limits**: Memory and process constraints
|
||||
- **File Access**: Controlled filesystem access
|
||||
- **Network Access**: Restricted network access
|
||||
|
||||
### IPC Security
|
||||
- **File Descriptors**: Secure descriptor passing
|
||||
- **Memory Protection**: Sealed memfd for data transfer
|
||||
- **Access Control**: Proper permission checking
|
||||
- **Input Validation**: Validate all IPC inputs
|
||||
|
||||
### Package Operations
|
||||
- **Signature Verification**: Verify package signatures
|
||||
- **Repository Validation**: Validate repository sources
|
||||
- **Permission Checking**: Check operation permissions
|
||||
- **Audit Logging**: Log all package operations
|
||||
|
||||
## Conclusion
|
||||
|
||||
This implementation guide provides comprehensive technical specifications for integrating the missing development commands from rpm-ostree into apt-ostree. The commands maintain the same logical structure and behavior while adapting to APT-specific package management and Debian system conventions.
|
||||
|
||||
The implementation includes proper security measures, comprehensive testing, and integration with the existing apt-ostree architecture. These development tools will significantly enhance the development, testing, and debugging capabilities of apt-ostree.
|
||||
236
docs/apt-ostree-daemon-plan/development-commands-summary.md
Normal file
236
docs/apt-ostree-daemon-plan/development-commands-summary.md
Normal file
|
|
@ -0,0 +1,236 @@
|
|||
# Development Commands Integration Summary
|
||||
|
||||
## Executive Summary
|
||||
|
||||
This document summarizes the plan to integrate the missing development and debugging commands from rpm-ostree into apt-ostree. These commands are essential for development, testing, and debugging workflows and will significantly enhance the development capabilities of apt-ostree.
|
||||
|
||||
## Missing Commands Overview
|
||||
|
||||
### 1. testutils Command
|
||||
- **Purpose**: Development debugging tool for testing and development workflows
|
||||
- **Status**: Fully implemented in rpm-ostree (C++ and Rust)
|
||||
- **Priority**: High - Essential for development and testing
|
||||
- **Complexity**: Medium - Requires APT integration and OSTree operations
|
||||
|
||||
### 2. shlib-backend Command
|
||||
- **Purpose**: Shared library backend for IPC operations and package management
|
||||
- **Status**: Fully implemented in rpm-ostree (C++)
|
||||
- **Priority**: High - Essential for package operations and IPC
|
||||
- **Complexity**: High - Requires IPC layer and APT integration
|
||||
|
||||
### 3. internals Command
|
||||
- **Purpose**: Internal system commands for advanced operations
|
||||
- **Status**: Referenced in header but implementation not found
|
||||
- **Priority**: Medium - Useful for system diagnostics
|
||||
- **Complexity**: Low - Can be implemented as placeholder
|
||||
|
||||
## Implementation Benefits
|
||||
|
||||
### Development Workflow Enhancement
|
||||
1. **Automated Testing**: Generate synthetic upgrades for testing
|
||||
2. **Package Management**: Debug package list and metadata issues
|
||||
3. **System Validation**: Validate system state and configuration
|
||||
4. **Script Execution**: Safe script execution in isolated containers
|
||||
|
||||
### Quality Assurance
|
||||
1. **Package Integration**: Validate APT and OSTree integration
|
||||
2. **System Consistency**: Ensure system state consistency
|
||||
3. **Error Handling**: Test edge cases and failure modes
|
||||
4. **Performance Testing**: Benchmark system operations
|
||||
|
||||
### Maintenance and Support
|
||||
1. **Troubleshooting**: Debug deployment and package issues
|
||||
2. **Development**: Rapid iteration and testing capabilities
|
||||
3. **Documentation**: Generate system state reports
|
||||
4. **Validation**: Ensure system integrity
|
||||
|
||||
## Technical Implementation Plan
|
||||
|
||||
### Phase 1: Core Infrastructure (Week 1-2)
|
||||
- [ ] Add hidden command support to CLI
|
||||
- [ ] Implement command flag system
|
||||
- [ ] Create development commands module structure
|
||||
- [ ] Add command registration and dispatch
|
||||
|
||||
### Phase 2: testutils Implementation (Week 3-4)
|
||||
- [ ] Implement `inject-pkglist` with APT integration
|
||||
- [ ] Implement `script-shell` with bubblewrap
|
||||
- [ ] Implement `generate-synthetic-upgrade` for testing
|
||||
- [ ] Implement `integration-read-only` validation
|
||||
- [ ] Add unit and integration tests
|
||||
|
||||
### Phase 3: shlib-backend Implementation (Week 5-6)
|
||||
- [ ] Implement IPC communication layer
|
||||
- [ ] Implement APT-based package operations
|
||||
- [ ] Implement architecture detection
|
||||
- [ ] Implement variable substitution
|
||||
- [ ] Add security and validation
|
||||
|
||||
### Phase 4: Integration and Testing (Week 7-8)
|
||||
- [ ] Integrate all commands into main system
|
||||
- [ ] Add comprehensive testing framework
|
||||
- [ ] Implement security measures
|
||||
- [ ] Create documentation and examples
|
||||
- [ ] Performance optimization
|
||||
|
||||
## Dependencies and Requirements
|
||||
|
||||
### New Dependencies
|
||||
```toml
|
||||
[dependencies]
|
||||
bubblewrap = "0.1" # Container isolation
|
||||
goblin = "0.8" # ELF file manipulation
|
||||
rand = "0.8" # Random number generation
|
||||
tempfile = "3.0" # Temporary directory management
|
||||
cap-std = "1.0" # Capability-based file operations
|
||||
cap-std-ext = "1.0" # Extended capability operations
|
||||
```
|
||||
|
||||
### System Requirements
|
||||
- **bubblewrap**: For script containerization
|
||||
- **objcopy**: For ELF binary modification (optional)
|
||||
- **OSTree**: For repository operations
|
||||
- **APT**: For package management operations
|
||||
|
||||
### Feature Flags
|
||||
```toml
|
||||
[features]
|
||||
development = ["bubblewrap", "goblin", "rand", "tempfile"]
|
||||
dev-full = ["development", "cap-std", "cap-std-ext"]
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Container Isolation
|
||||
- **Bubblewrap**: Secure script execution environment
|
||||
- **Resource Limits**: Memory and process constraints
|
||||
- **File Access**: Controlled filesystem access
|
||||
- **Network Access**: Restricted network access
|
||||
|
||||
### IPC Security
|
||||
- **File Descriptors**: Secure descriptor passing
|
||||
- **Memory Protection**: Sealed memfd for data transfer
|
||||
- **Access Control**: Proper permission checking
|
||||
- **Input Validation**: Validate all IPC inputs
|
||||
|
||||
### Package Operations
|
||||
- **Signature Verification**: Verify package signatures
|
||||
- **Repository Validation**: Validate repository sources
|
||||
- **Permission Checking**: Check operation permissions
|
||||
- **Audit Logging**: Log all package operations
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Unit Testing
|
||||
- **Command Logic**: Test individual command functionality
|
||||
- **Error Handling**: Test error conditions and edge cases
|
||||
- **Input Validation**: Test argument parsing and validation
|
||||
- **Mock Integration**: Test with mocked dependencies
|
||||
|
||||
### Integration Testing
|
||||
- **System Integration**: Test with real OSTree and APT systems
|
||||
- **Command Interaction**: Test command combinations and workflows
|
||||
- **Performance Testing**: Benchmark command execution times
|
||||
- **Security Testing**: Validate security measures and isolation
|
||||
|
||||
### End-to-End Testing
|
||||
- **Development Workflow**: Test complete development scenarios
|
||||
- **Debugging Tools**: Test debugging and troubleshooting capabilities
|
||||
- **System Validation**: Test system state validation tools
|
||||
- **Error Recovery**: Test error handling and recovery mechanisms
|
||||
|
||||
## Documentation Requirements
|
||||
|
||||
### Developer Documentation
|
||||
- **Command Reference**: Complete command documentation
|
||||
- **API Reference**: Internal API documentation
|
||||
- **Examples**: Usage examples and common scenarios
|
||||
- **Troubleshooting**: Common issues and solutions
|
||||
|
||||
### User Documentation
|
||||
- **Installation Guide**: Setup and configuration
|
||||
- **Usage Guide**: Basic usage and common commands
|
||||
- **Configuration**: Configuration options and settings
|
||||
- **Security Guide**: Security considerations and best practices
|
||||
|
||||
### Integration Documentation
|
||||
- **Architecture**: System architecture and design
|
||||
- **Integration Guide**: Integration with existing systems
|
||||
- **API Integration**: External API usage and integration
|
||||
- **Deployment Guide**: Deployment and operational considerations
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
### Technical Risks
|
||||
- **Complexity**: IPC and containerization complexity
|
||||
- **Integration**: APT and OSTree integration challenges
|
||||
- **Performance**: Impact on system performance
|
||||
- **Security**: Security vulnerabilities in new features
|
||||
|
||||
### Mitigation Strategies
|
||||
- **Incremental Development**: Implement features incrementally
|
||||
- **Comprehensive Testing**: Extensive testing at all levels
|
||||
- **Security Review**: Regular security reviews and audits
|
||||
- **Performance Monitoring**: Continuous performance monitoring
|
||||
|
||||
### Dependencies
|
||||
- **External Tools**: Dependence on bubblewrap and other tools
|
||||
- **System Requirements**: OSTree and APT system requirements
|
||||
- **Platform Support**: Debian-specific implementation
|
||||
- **Maintenance**: Ongoing maintenance and updates
|
||||
|
||||
## Success Metrics
|
||||
|
||||
### Development Efficiency
|
||||
- **Testing Speed**: Reduced time for testing and validation
|
||||
- **Debugging Speed**: Faster issue identification and resolution
|
||||
- **Development Cycle**: Reduced development iteration time
|
||||
- **Code Quality**: Improved code quality and reliability
|
||||
|
||||
### System Reliability
|
||||
- **Error Detection**: Better error detection and reporting
|
||||
- **System Validation**: Improved system state validation
|
||||
- **Issue Resolution**: Faster issue resolution and recovery
|
||||
- **System Stability**: Improved overall system stability
|
||||
|
||||
### User Experience
|
||||
- **Developer Tools**: Enhanced development and debugging tools
|
||||
- **System Management**: Better system management capabilities
|
||||
- **Troubleshooting**: Improved troubleshooting and support
|
||||
- **Documentation**: Better documentation and examples
|
||||
|
||||
## Conclusion
|
||||
|
||||
Integrating the missing development commands from rpm-ostree into apt-ostree will provide essential tools for development, testing, and debugging. These commands will significantly enhance the development capabilities of apt-ostree while maintaining the same logical structure and behavior as the original rpm-ostree implementation.
|
||||
|
||||
The implementation plan provides a structured approach to development with clear phases, comprehensive testing, and proper security measures. The benefits include improved development workflow, enhanced quality assurance, and better maintenance and support capabilities.
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Immediate Actions**:
|
||||
- Review and approve implementation plan
|
||||
- Set up development environment
|
||||
- Begin Phase 1 implementation
|
||||
|
||||
2. **Short Term (1-2 weeks)**:
|
||||
- Complete core infrastructure
|
||||
- Begin testutils implementation
|
||||
- Set up testing framework
|
||||
|
||||
3. **Medium Term (3-6 weeks)**:
|
||||
- Complete testutils implementation
|
||||
- Implement shlib-backend
|
||||
- Begin integration testing
|
||||
|
||||
4. **Long Term (7-8 weeks)**:
|
||||
- Complete integration and testing
|
||||
- Performance optimization
|
||||
- Documentation and deployment
|
||||
|
||||
## Contact and Support
|
||||
|
||||
For questions or support regarding this implementation plan, please refer to:
|
||||
- **Technical Documentation**: `/docs/apt-ostree-daemon-plan/`
|
||||
- **Implementation Guide**: `development-commands-implementation.md`
|
||||
- **Analysis Document**: `development-commands-analysis.md`
|
||||
- **Project Repository**: `/opt/Projects/apt-ostree/`
|
||||
|
|
@ -422,7 +422,7 @@ src/
|
|||
## System Requirements
|
||||
|
||||
### Supported Distributions
|
||||
- Debian 13+ (Bookworm)
|
||||
- Debian 13+ (Trixie)
|
||||
- Ubuntu 25.04+ (Noble Numbat)
|
||||
|
||||
### Hardware Requirements
|
||||
|
|
|
|||
|
|
@ -59,7 +59,7 @@ sudo apt install -y \
|
|||
```bash
|
||||
# Add apt-ostree repository
|
||||
echo "deb [signed-by=/usr/share/keyrings/apt-ostree-archive-keyring.gpg] \
|
||||
https://apt.ostree.dev/debian bookworm main" | \
|
||||
https://apt.ostree.dev/debian trixie main" | \
|
||||
sudo tee /etc/apt/sources.list.d/apt-ostree.list
|
||||
|
||||
# Add repository key
|
||||
|
|
|
|||
|
|
@ -274,7 +274,6 @@ async fn test_apt_database_operations() {
|
|||
let deps = manager.resolve_dependencies(&vec!["vim".to_string()]).await.unwrap();
|
||||
assert!(!deps.is_empty());
|
||||
}
|
||||
```
|
||||
|
||||
#### **OSTree Repository Operations**
|
||||
```rust
|
||||
|
|
@ -565,7 +564,7 @@ jobs:
|
|||
#### **Docker Test Environment**
|
||||
```dockerfile
|
||||
# tests/Dockerfile.test
|
||||
FROM debian:bookworm-slim
|
||||
FROM debian:trixie-slim
|
||||
|
||||
# Install system dependencies
|
||||
RUN apt-get update && apt-get install -y \
|
||||
|
|
@ -738,7 +737,7 @@ Installed: (none)
|
|||
Candidate: 2:9.0.1378-1
|
||||
Version table:
|
||||
*** 2:9.0.1378-1 500
|
||||
500 http://deb.debian.org/debian bookworm/main amd64 Packages
|
||||
500 http://deb.debian.org/debian trixie/main amd64 Packages
|
||||
100 /var/lib/dpkg/status
|
||||
"#;
|
||||
```
|
||||
|
|
|
|||
101
docs/cli-parity-checklist.md
Normal file
101
docs/cli-parity-checklist.md
Normal file
|
|
@ -0,0 +1,101 @@
|
|||
## CLI Parity Checklist (apt-ostree vs rpm-ostree)
|
||||
|
||||
Source references:
|
||||
- rpm-ostree builtins: `inspiration/rpm-ostree/src/app/` (files named `rpmostree-builtin-*.cxx` and related `*-builtins*`)
|
||||
- apt-ostree CLI: `src/cli.rs`
|
||||
|
||||
### rpm-ostree top-level commands detected
|
||||
- status
|
||||
- upgrade
|
||||
- rollback
|
||||
- deploy
|
||||
- rebase
|
||||
- initramfs
|
||||
- initramfs-etc
|
||||
- kargs
|
||||
- reload
|
||||
- cancel
|
||||
- reset
|
||||
- refresh-md
|
||||
- compose
|
||||
- override
|
||||
- apply-live
|
||||
- finalize-deployment
|
||||
- cleanup
|
||||
- start-daemon
|
||||
- db
|
||||
- ex (group)
|
||||
- testutils (hidden)
|
||||
- shlib-backend (hidden)
|
||||
|
||||
### apt-ostree top-level commands (src/cli.rs)
|
||||
- Status
|
||||
- Upgrade
|
||||
- Rollback
|
||||
- Deploy
|
||||
- Rebase
|
||||
- Install
|
||||
- Uninstall
|
||||
- Search
|
||||
- Initramfs
|
||||
- InitramfsEtc
|
||||
- Kargs
|
||||
- Reload
|
||||
- Cancel
|
||||
- Transaction (group)
|
||||
- Compose (group)
|
||||
- Db (group)
|
||||
- Override (group)
|
||||
- Reset
|
||||
- RefreshMd
|
||||
- ApplyLive
|
||||
- Usroverlay
|
||||
- Cleanup
|
||||
- FinalizeDeployment
|
||||
- Metrics
|
||||
- StartDaemon
|
||||
- Ex (group)
|
||||
- Countme
|
||||
- Container (group)
|
||||
- Testutils (hidden)
|
||||
- ShlibBackend (hidden)
|
||||
- Internals (hidden)
|
||||
|
||||
### Parity status
|
||||
- status: present (Status)
|
||||
- upgrade: present (Upgrade)
|
||||
- rollback: present (Rollback)
|
||||
- deploy: present (Deploy)
|
||||
- rebase: present (Rebase)
|
||||
- initramfs: present (Initramfs)
|
||||
- initramfs-etc: present (InitramfsEtc)
|
||||
- kargs: present (Kargs)
|
||||
- reload: present (Reload)
|
||||
- cancel: present (Cancel)
|
||||
- reset: present (Reset)
|
||||
- refresh-md: present (RefreshMd)
|
||||
- compose: present (Compose)
|
||||
- override: present (Override)
|
||||
- apply-live: present (ApplyLive)
|
||||
- finalize-deployment: present (FinalizeDeployment)
|
||||
- cleanup: present (Cleanup)
|
||||
- start-daemon: present (StartDaemon)
|
||||
- db: present (Db)
|
||||
- ex: present (Ex)
|
||||
- testutils (hidden): present (Testutils)
|
||||
- shlib-backend (hidden): present (ShlibBackend)
|
||||
|
||||
### Differences and extras
|
||||
- install/uninstall: present in apt-ostree; maps to rpm-ostree package layering builtins (expected)
|
||||
- search: present in apt-ostree; rpm-ostree has `db search` flows (OK)
|
||||
- transaction (group): apt-ostree adds management helpers; aligns with rpm-ostree transaction concepts
|
||||
- usroverlay: extra in apt-ostree (not a top-level in rpm-ostree; keep as experimental)
|
||||
- metrics: extra in apt-ostree (telemetry; not in rpm-ostree)
|
||||
- countme: extra in apt-ostree (dnf concept; not in rpm-ostree)
|
||||
- container (group): extra in apt-ostree (rpm-ostree has container helpers but not a top-level group)
|
||||
- internals (hidden): extra diagnostics; acceptable as hidden
|
||||
|
||||
### Next actions for strict parity
|
||||
- Review and align flags/options per command against rpm-ostree
|
||||
- Ensure help text and defaults match where applicable
|
||||
- Gate non-parity extras (`usroverlay`, `metrics`, `countme`, `container`) behind experimental or hidden flags if needed
|
||||
623
docs/developer-guide.md
Normal file
623
docs/developer-guide.md
Normal file
|
|
@ -0,0 +1,623 @@
|
|||
# apt-ostree Developer Guide
|
||||
|
||||
## Table of Contents
|
||||
1. [Architecture Overview](#architecture-overview)
|
||||
2. [Development Setup](#development-setup)
|
||||
3. [Code Organization](#code-organization)
|
||||
4. [API Documentation](#api-documentation)
|
||||
5. [Development Workflow](#development-workflow)
|
||||
6. [Testing and Debugging](#testing-and-debugging)
|
||||
7. [Contributing Guidelines](#contributing-guidelines)
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### System Components
|
||||
apt-ostree consists of several key components:
|
||||
|
||||
```
|
||||
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
||||
│ CLI Client │ │ System Daemon │ │ OSTree Repo │
|
||||
│ (apt-ostree) │◄──►│ (apt-ostreed) │◄──►│ (/ostree/) │
|
||||
└─────────────────┘ └──────────────────┘ └─────────────────┘
|
||||
│ │ │
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
||||
│ APT System │ │ D-Bus Layer │ │ File System │
|
||||
│ (Package Mgmt)│ │ (IPC Interface) │ │ (Deployments) │
|
||||
└─────────────────┘ └──────────────────┘ └─────────────────┘
|
||||
```
|
||||
|
||||
### Component Responsibilities
|
||||
|
||||
#### CLI Client (apt-ostree)
|
||||
- **Command parsing**: Uses `clap` for argument parsing
|
||||
- **User interface**: Provides user-friendly command interface
|
||||
- **Command dispatch**: Routes commands to appropriate handlers
|
||||
- **Output formatting**: Formats results for user consumption
|
||||
|
||||
#### System Daemon (apt-ostreed)
|
||||
- **Background processing**: Handles long-running operations
|
||||
- **D-Bus interface**: Provides IPC for system operations
|
||||
- **Transaction management**: Manages atomic system changes
|
||||
- **Security**: Implements Polkit authentication
|
||||
|
||||
#### OSTree Integration
|
||||
- **Repository management**: Manages OSTree repositories
|
||||
- **Deployment handling**: Handles system deployments
|
||||
- **Atomic operations**: Ensures system consistency
|
||||
- **Rollback support**: Provides system recovery
|
||||
|
||||
#### APT Integration
|
||||
- **Package resolution**: Resolves package dependencies
|
||||
- **Repository management**: Manages APT repositories
|
||||
- **Transaction handling**: Handles package transactions
|
||||
- **Conflict resolution**: Resolves package conflicts
|
||||
|
||||
## Development Setup
|
||||
|
||||
### Prerequisites
|
||||
- **Rust toolchain**: Rust 1.75+ with Cargo
|
||||
- **System dependencies**: See installation guide
|
||||
- **Development tools**: Git, make, pkg-config
|
||||
- **Documentation tools**: rustdoc, cargo-doc
|
||||
|
||||
### Environment Setup
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://github.com/robojerk/apt-ostree.git
|
||||
cd apt-ostree
|
||||
|
||||
# Install Rust toolchain
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
source ~/.cargo/env
|
||||
|
||||
# Install system dependencies
|
||||
sudo apt-get install build-essential pkg-config \
|
||||
libostree-dev libapt-pkg-dev libpolkit-gobject-1-dev \
|
||||
libdbus-1-dev libsystemd-dev
|
||||
|
||||
# Install development tools
|
||||
cargo install cargo-outdated cargo-audit cargo-tarpaulin
|
||||
```
|
||||
|
||||
### Build Configuration
|
||||
```bash
|
||||
# Development build with all features
|
||||
cargo build --features development,dev-full
|
||||
|
||||
# Release build
|
||||
cargo build --release
|
||||
|
||||
# Documentation
|
||||
cargo doc --open --features development
|
||||
|
||||
# Run tests
|
||||
cargo test --features development
|
||||
```
|
||||
|
||||
## Code Organization
|
||||
|
||||
### Directory Structure
|
||||
```
|
||||
src/
|
||||
├── main.rs # CLI entry point
|
||||
├── cli.rs # Command-line interface definitions
|
||||
├── commands/ # Command implementations
|
||||
│ ├── mod.rs # Command registry
|
||||
│ ├── package.rs # Package management commands
|
||||
│ ├── system.rs # System management commands
|
||||
│ ├── testutils.rs # Development utilities
|
||||
│ ├── shlib_backend.rs # Shared library backend
|
||||
│ └── internals.rs # Internal diagnostics
|
||||
├── lib/ # Core library code
|
||||
│ ├── mod.rs # Library entry point
|
||||
│ ├── apt.rs # APT integration
|
||||
│ ├── ostree.rs # OSTree integration
|
||||
│ ├── security.rs # Security and authentication
|
||||
│ ├── system.rs # System operations
|
||||
│ ├── transaction.rs # Transaction management
|
||||
│ └── logging.rs # Logging and metrics
|
||||
├── daemon/ # Daemon implementation
|
||||
│ ├── main.rs # Daemon entry point
|
||||
│ ├── dbus.rs # D-Bus interface
|
||||
│ ├── polkit.rs # Polkit integration
|
||||
│ └── systemd.rs # systemd integration
|
||||
└── tests/ # Test suite
|
||||
├── integration_tests.rs
|
||||
└── common/
|
||||
```
|
||||
|
||||
### Key Modules
|
||||
|
||||
#### Command System
|
||||
The command system uses a trait-based approach for extensibility:
|
||||
|
||||
```rust
|
||||
pub trait Command {
|
||||
fn execute(&self, args: &[String]) -> Result<(), Box<dyn std::error::Error>>;
|
||||
fn help(&self) -> String;
|
||||
fn usage(&self) -> String;
|
||||
}
|
||||
|
||||
pub struct CommandRegistry {
|
||||
commands: HashMap<String, Box<dyn Command>>,
|
||||
}
|
||||
```
|
||||
|
||||
#### Library Interface
|
||||
The library provides a clean API for external consumers:
|
||||
|
||||
```rust
|
||||
pub struct AptOstree {
|
||||
apt_manager: AptManager,
|
||||
ostree_manager: OstreeManager,
|
||||
security_manager: SecurityManager,
|
||||
}
|
||||
|
||||
impl AptOstree {
|
||||
pub fn new() -> Result<Self, Error> { /* ... */ }
|
||||
pub fn install_packages(&self, packages: &[String]) -> Result<(), Error> { /* ... */ }
|
||||
pub fn remove_packages(&self, packages: &[String]) -> Result<(), Error> { /* ... */ }
|
||||
}
|
||||
```
|
||||
|
||||
## API Documentation
|
||||
|
||||
### Core Types
|
||||
|
||||
#### Package Management
|
||||
```rust
|
||||
pub struct Package {
|
||||
pub name: String,
|
||||
pub version: String,
|
||||
pub architecture: String,
|
||||
pub dependencies: Vec<String>,
|
||||
pub conflicts: Vec<String>,
|
||||
}
|
||||
|
||||
pub struct PackageTransaction {
|
||||
pub packages: Vec<Package>,
|
||||
pub operation: TransactionOperation,
|
||||
pub status: TransactionStatus,
|
||||
}
|
||||
```
|
||||
|
||||
#### OSTree Integration
|
||||
```rust
|
||||
pub struct Deployment {
|
||||
pub id: String,
|
||||
pub branch: String,
|
||||
pub commit: String,
|
||||
pub timestamp: DateTime<Utc>,
|
||||
pub packages: Vec<String>,
|
||||
}
|
||||
|
||||
pub struct OSTreeRepository {
|
||||
pub path: PathBuf,
|
||||
pub mode: RepositoryMode,
|
||||
pub remotes: HashMap<String, Remote>,
|
||||
}
|
||||
```
|
||||
|
||||
#### Security
|
||||
```rust
|
||||
pub struct SecurityContext {
|
||||
pub user: String,
|
||||
pub groups: Vec<String>,
|
||||
pub permissions: Permissions,
|
||||
}
|
||||
|
||||
pub struct AuthenticationResult {
|
||||
pub authenticated: bool,
|
||||
pub user: Option<String>,
|
||||
pub permissions: Permissions,
|
||||
}
|
||||
```
|
||||
|
||||
### Public API
|
||||
|
||||
#### High-Level Operations
|
||||
```rust
|
||||
impl AptOstree {
|
||||
/// Install packages atomically
|
||||
pub fn install_packages(&self, packages: &[String]) -> Result<(), Error>
|
||||
|
||||
/// Remove packages atomically
|
||||
pub fn remove_packages(&self, packages: &[String]) -> Result<(), Error>
|
||||
|
||||
/// Upgrade all packages
|
||||
pub fn upgrade_system(&self) -> Result<(), Error>
|
||||
|
||||
/// Rollback to previous deployment
|
||||
pub fn rollback(&self) -> Result<(), Error>
|
||||
}
|
||||
```
|
||||
|
||||
#### Transaction Management
|
||||
```rust
|
||||
impl TransactionManager {
|
||||
/// Start a new transaction
|
||||
pub fn start_transaction(&mut self, operation: TransactionOperation) -> Result<TransactionId, Error>
|
||||
|
||||
/// Add packages to transaction
|
||||
pub fn add_packages(&mut self, transaction_id: TransactionId, packages: &[String]) -> Result<(), Error>
|
||||
|
||||
/// Commit transaction
|
||||
pub fn commit_transaction(&mut self, transaction_id: TransactionId) -> Result<(), Error>
|
||||
|
||||
/// Rollback transaction
|
||||
pub fn rollback_transaction(&mut self, transaction_id: TransactionId) -> Result<(), Error>
|
||||
}
|
||||
```
|
||||
|
||||
#### System Operations
|
||||
```rust
|
||||
impl SystemManager {
|
||||
/// Get system status
|
||||
pub fn get_system_status(&self) -> SystemStatus
|
||||
|
||||
/// Manage kernel arguments
|
||||
pub fn set_kernel_args(&self, args: &[String]) -> Result<(), Error>
|
||||
|
||||
/// Regenerate initramfs
|
||||
pub fn regenerate_initramfs(&self) -> Result<(), Error>
|
||||
}
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Adding New Commands
|
||||
|
||||
#### 1. Define Command Structure
|
||||
```rust
|
||||
// src/cli.rs
|
||||
#[derive(Subcommand)]
|
||||
pub enum Commands {
|
||||
// ... existing commands ...
|
||||
NewCommand(NewCommandArgs),
|
||||
}
|
||||
|
||||
#[derive(Args)]
|
||||
pub struct NewCommandArgs {
|
||||
#[arg(long)]
|
||||
option: Option<String>,
|
||||
|
||||
#[arg(value_name = "TARGET")]
|
||||
target: String,
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. Implement Command Logic
|
||||
```rust
|
||||
// src/commands/new_command.rs
|
||||
pub struct NewCommand;
|
||||
|
||||
impl Command for NewCommand {
|
||||
fn execute(&self, args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
|
||||
// Implementation here
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn help(&self) -> String {
|
||||
"Help text for new command".to_string()
|
||||
}
|
||||
|
||||
fn usage(&self) -> String {
|
||||
"new-command [OPTIONS] TARGET".to_string()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. Register Command
|
||||
```rust
|
||||
// src/commands/mod.rs
|
||||
pub mod new_command;
|
||||
|
||||
// In CommandRegistry::new()
|
||||
self.commands.insert("new-command".to_string(), Box::new(NewCommand));
|
||||
```
|
||||
|
||||
#### 4. Add to Main Dispatch
|
||||
```rust
|
||||
// src/main.rs
|
||||
match cli.command {
|
||||
Commands::NewCommand(args) => {
|
||||
// Handle new command
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Adding New Features
|
||||
|
||||
#### 1. Library Implementation
|
||||
```rust
|
||||
// src/lib/new_feature.rs
|
||||
pub struct NewFeature {
|
||||
// Feature implementation
|
||||
}
|
||||
|
||||
impl NewFeature {
|
||||
pub fn new() -> Self {
|
||||
// Constructor
|
||||
}
|
||||
|
||||
pub fn execute(&self) -> Result<(), Error> {
|
||||
// Feature logic
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. Integration
|
||||
```rust
|
||||
// src/lib/mod.rs
|
||||
pub mod new_feature;
|
||||
|
||||
// In main library struct
|
||||
pub struct AptOstree {
|
||||
// ... existing fields ...
|
||||
new_feature: NewFeature,
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. Testing
|
||||
```rust
|
||||
// tests/new_feature_tests.rs
|
||||
#[test]
|
||||
fn test_new_feature() {
|
||||
let feature = NewFeature::new();
|
||||
assert!(feature.execute().is_ok());
|
||||
}
|
||||
```
|
||||
|
||||
## Testing and Debugging
|
||||
|
||||
### Unit Testing
|
||||
```bash
|
||||
# Run all tests
|
||||
cargo test
|
||||
|
||||
# Run specific test module
|
||||
cargo test commands::package
|
||||
|
||||
# Run tests with output
|
||||
cargo test -- --nocapture
|
||||
|
||||
# Run tests with specific feature
|
||||
cargo test --features development
|
||||
```
|
||||
|
||||
### Integration Testing
|
||||
```bash
|
||||
# Run integration tests
|
||||
cargo test --test integration_tests
|
||||
|
||||
# Run specific integration test
|
||||
cargo test --test integration_tests test_package_installation
|
||||
```
|
||||
|
||||
### Development Commands
|
||||
```bash
|
||||
# Run diagnostics
|
||||
cargo run --features development -- internals diagnostics
|
||||
|
||||
# Validate system state
|
||||
cargo run --features development -- internals validate-state
|
||||
|
||||
# Dump debug information
|
||||
cargo run --features development -- internals debug-dump
|
||||
```
|
||||
|
||||
### Debugging Tools
|
||||
|
||||
#### Logging
|
||||
```rust
|
||||
use tracing::{info, warn, error, debug};
|
||||
|
||||
// Set log level
|
||||
std::env::set_var("RUST_LOG", "debug");
|
||||
|
||||
// Use in code
|
||||
debug!("Debug information");
|
||||
info!("Information message");
|
||||
warn!("Warning message");
|
||||
error!("Error message");
|
||||
```
|
||||
|
||||
#### Profiling
|
||||
```bash
|
||||
# Install profiling tools
|
||||
cargo install flamegraph
|
||||
|
||||
# Generate flamegraph
|
||||
cargo flamegraph --bin apt-ostree -- install nginx
|
||||
|
||||
# Memory profiling
|
||||
cargo install cargo-valgrind
|
||||
cargo valgrind test
|
||||
```
|
||||
|
||||
### Code Quality Tools
|
||||
|
||||
#### Clippy
|
||||
```bash
|
||||
# Run Clippy
|
||||
cargo clippy
|
||||
|
||||
# Run with specific rules
|
||||
cargo clippy -- -D warnings -A clippy::too_many_arguments
|
||||
```
|
||||
|
||||
#### Formatting
|
||||
```bash
|
||||
# Check formatting
|
||||
cargo fmt -- --check
|
||||
|
||||
# Format code
|
||||
cargo fmt
|
||||
```
|
||||
|
||||
#### Security Audit
|
||||
```bash
|
||||
# Check for vulnerabilities
|
||||
cargo audit
|
||||
|
||||
# Update dependencies
|
||||
cargo update
|
||||
```
|
||||
|
||||
## Contributing Guidelines
|
||||
|
||||
### Code Style
|
||||
- **Rust conventions**: Follow Rust style guide and idioms
|
||||
- **Documentation**: Document all public APIs with doc comments
|
||||
- **Error handling**: Use proper error types and Result handling
|
||||
- **Testing**: Include tests for new functionality
|
||||
- **Logging**: Use appropriate log levels for debugging
|
||||
|
||||
### Pull Request Process
|
||||
1. **Fork repository**: Create your own fork
|
||||
2. **Create feature branch**: `git checkout -b feature/new-feature`
|
||||
3. **Implement changes**: Follow coding guidelines
|
||||
4. **Add tests**: Include unit and integration tests
|
||||
5. **Update documentation**: Update relevant documentation
|
||||
6. **Submit PR**: Create pull request with clear description
|
||||
|
||||
### Commit Guidelines
|
||||
```
|
||||
type(scope): description
|
||||
|
||||
[optional body]
|
||||
|
||||
[optional footer]
|
||||
```
|
||||
|
||||
**Types**: feat, fix, docs, style, refactor, test, chore
|
||||
**Scope**: cli, daemon, lib, commands, etc.
|
||||
|
||||
### Review Process
|
||||
- **Code review**: All changes require review
|
||||
- **Testing**: Ensure all tests pass
|
||||
- **Documentation**: Verify documentation is updated
|
||||
- **Integration**: Test integration with existing features
|
||||
|
||||
### Issue Reporting
|
||||
When reporting issues, include:
|
||||
- **Environment**: OS, version, dependencies
|
||||
- **Steps to reproduce**: Clear reproduction steps
|
||||
- **Expected behavior**: What should happen
|
||||
- **Actual behavior**: What actually happens
|
||||
- **Logs**: Relevant error logs and output
|
||||
|
||||
## Advanced Development
|
||||
|
||||
### Custom Builds
|
||||
```bash
|
||||
# Build with specific features
|
||||
cargo build --features development,dev-full
|
||||
|
||||
# Build for specific target
|
||||
cargo build --target x86_64-unknown-linux-gnu
|
||||
|
||||
# Cross-compilation
|
||||
cargo build --target aarch64-unknown-linux-gnu
|
||||
```
|
||||
|
||||
### Performance Optimization
|
||||
```rust
|
||||
// Use appropriate data structures
|
||||
use std::collections::HashMap; // O(1) lookup
|
||||
use std::collections::BTreeMap; // Ordered, O(log n) lookup
|
||||
|
||||
// Avoid unnecessary allocations
|
||||
let result = if condition { "value" } else { "default" };
|
||||
// Instead of
|
||||
let result = if condition { "value".to_string() } else { "default".to_string() };
|
||||
|
||||
// Use iterators efficiently
|
||||
let sum: u64 = items.iter().map(|x| x.value).sum();
|
||||
```
|
||||
|
||||
### Memory Management
|
||||
```rust
|
||||
// Use Arc for shared ownership
|
||||
use std::sync::Arc;
|
||||
|
||||
let shared_data = Arc::new(SharedData::new());
|
||||
let clone1 = Arc::clone(&shared_data);
|
||||
let clone2 = Arc::clone(&shared_data);
|
||||
|
||||
// Use Box for trait objects
|
||||
let commands: Vec<Box<dyn Command>> = vec![
|
||||
Box::new(PackageCommand),
|
||||
Box::new(SystemCommand),
|
||||
];
|
||||
```
|
||||
|
||||
### Async Programming
|
||||
```rust
|
||||
use tokio::runtime::Runtime;
|
||||
|
||||
#[tokio::main]
|
||||
async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
let result = async_operation().await?;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
async fn async_operation() -> Result<String, Error> {
|
||||
// Async implementation
|
||||
Ok("result".to_string())
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting Development Issues
|
||||
|
||||
### Common Problems
|
||||
|
||||
#### Build Failures
|
||||
```bash
|
||||
# Clean and rebuild
|
||||
cargo clean
|
||||
cargo build
|
||||
|
||||
# Check Rust version
|
||||
rustc --version
|
||||
cargo --version
|
||||
|
||||
# Update Rust toolchain
|
||||
rustup update
|
||||
```
|
||||
|
||||
#### Dependency Issues
|
||||
```bash
|
||||
# Check dependency tree
|
||||
cargo tree
|
||||
|
||||
# Update dependencies
|
||||
cargo update
|
||||
|
||||
# Check for conflicts
|
||||
cargo check
|
||||
```
|
||||
|
||||
#### Test Failures
|
||||
```bash
|
||||
# Run specific failing test
|
||||
cargo test test_name -- --nocapture
|
||||
|
||||
# Check test environment
|
||||
cargo test --features development
|
||||
|
||||
# Debug test setup
|
||||
RUST_LOG=debug cargo test
|
||||
```
|
||||
|
||||
### Getting Help
|
||||
- **Documentation**: Check inline documentation and rustdoc
|
||||
- **Issues**: Search existing GitHub issues
|
||||
- **Discussions**: Use GitHub Discussions for questions
|
||||
- **Community**: Join project community channels
|
||||
|
||||
---
|
||||
|
||||
*This guide covers development aspects of apt-ostree. For user documentation, refer to the User Guide.*
|
||||
645
docs/development-commands-troubleshooting.md
Normal file
645
docs/development-commands-troubleshooting.md
Normal file
|
|
@ -0,0 +1,645 @@
|
|||
# Development Commands Troubleshooting Guide
|
||||
|
||||
## Overview
|
||||
This document provides comprehensive troubleshooting information for apt-ostree development commands. It covers common issues, error messages, and solutions for the testutils, shlib-backend, and internals commands.
|
||||
|
||||
## Table of Contents
|
||||
1. [Common Issues](#common-issues)
|
||||
2. [Error Messages and Solutions](#error-messages-and-solutions)
|
||||
3. [Debugging Techniques](#debugging-techniques)
|
||||
4. [Performance Issues](#performance-issues)
|
||||
5. [Security Issues](#security-issues)
|
||||
6. [System-Specific Problems](#system-specific-problems)
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Command Not Found
|
||||
**Problem**: Development commands are not available or return "command not found"
|
||||
|
||||
**Symptoms**:
|
||||
- `apt-ostree testutils --help` returns "unknown command"
|
||||
- Development commands don't appear in help output
|
||||
|
||||
**Causes**:
|
||||
- Development features not compiled in
|
||||
- Binary built without development features
|
||||
- Feature flags not properly configured
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# 1. Verify development features are enabled
|
||||
cargo build --features development
|
||||
|
||||
# 2. Check if binary includes development commands
|
||||
cargo run --features development -- testutils --help
|
||||
|
||||
# 3. Rebuild with all development features
|
||||
cargo build --features development,dev-full
|
||||
|
||||
# 4. Verify feature compilation
|
||||
cargo check --features development
|
||||
```
|
||||
|
||||
**Prevention**:
|
||||
- Always build with `--features development` for development work
|
||||
- Use feature flags consistently across build environments
|
||||
- Document required features in build scripts
|
||||
|
||||
### Permission Denied
|
||||
**Problem**: Commands fail with permission errors
|
||||
|
||||
**Symptoms**:
|
||||
- "Permission denied" errors
|
||||
- "Operation not permitted" messages
|
||||
- Commands fail even when run as root
|
||||
|
||||
**Causes**:
|
||||
- Insufficient user privileges
|
||||
- Polkit policy restrictions
|
||||
- File system permissions
|
||||
- SELinux/AppArmor restrictions
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# 1. Check user privileges
|
||||
whoami
|
||||
groups $USER
|
||||
|
||||
# 2. Verify Polkit policies
|
||||
sudo polkit-policy-file-validate /usr/share/polkit-1/actions/org.projectatomic.aptostree1.policy
|
||||
|
||||
# 3. Check file permissions
|
||||
ls -la /usr/bin/apt-ostree
|
||||
ls -la /var/lib/apt-ostree/
|
||||
|
||||
# 4. Verify daemon is running
|
||||
sudo systemctl status apt-ostreed
|
||||
|
||||
# 5. Check SELinux/AppArmor status
|
||||
getenforce 2>/dev/null || echo "SELinux not available"
|
||||
aa-status 2>/dev/null || echo "AppArmor not available"
|
||||
```
|
||||
|
||||
**Prevention**:
|
||||
- Ensure proper Polkit policies are installed
|
||||
- Configure appropriate user groups and permissions
|
||||
- Test commands in isolated environments first
|
||||
|
||||
### Bubblewrap Issues
|
||||
**Problem**: script-shell command fails with bubblewrap errors
|
||||
|
||||
**Symptoms**:
|
||||
- "bubblewrap: command not found"
|
||||
- "Failed to execute bubblewrap"
|
||||
- Containerization failures
|
||||
|
||||
**Causes**:
|
||||
- Bubblewrap not installed
|
||||
- Insufficient bubblewrap permissions
|
||||
- Kernel security restrictions
|
||||
- User namespace limitations
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# 1. Check bubblewrap installation
|
||||
which bubblewrap
|
||||
bubblewrap --version
|
||||
|
||||
# 2. Install bubblewrap if missing
|
||||
sudo apt-get install bubblewrap
|
||||
|
||||
# 3. Test bubblewrap functionality
|
||||
bubblewrap --dev-bind / / --proc /proc -- echo "test"
|
||||
|
||||
# 4. Check user namespace support
|
||||
cat /proc/sys/kernel/unprivileged_userns_clone
|
||||
|
||||
# 5. Verify kernel capabilities
|
||||
capsh --print
|
||||
```
|
||||
|
||||
**Prevention**:
|
||||
- Ensure bubblewrap is available in build environment
|
||||
- Test bubblewrap functionality before deployment
|
||||
- Configure appropriate kernel parameters
|
||||
|
||||
### OSTree Repository Issues
|
||||
**Problem**: Commands fail due to OSTree repository problems
|
||||
|
||||
**Symptoms**:
|
||||
- "Repository not found" errors
|
||||
- "Invalid repository" messages
|
||||
- Commit resolution failures
|
||||
|
||||
**Causes**:
|
||||
- OSTree repository not initialized
|
||||
- Repository corruption
|
||||
- Permission issues
|
||||
- Invalid repository path
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# 1. Check repository status
|
||||
sudo ostree show --repo=/ostree/repo
|
||||
|
||||
# 2. Verify repository integrity
|
||||
sudo ostree fsck --repo=/ostree/repo
|
||||
|
||||
# 3. Check repository permissions
|
||||
ls -la /ostree/repo/
|
||||
|
||||
# 4. Reinitialize repository if needed
|
||||
sudo ostree init --repo=/ostree/repo --mode=bare
|
||||
|
||||
# 5. Check OSTree service status
|
||||
sudo systemctl status ostree-remount
|
||||
```
|
||||
|
||||
**Prevention**:
|
||||
- Initialize OSTree repository during system setup
|
||||
- Regular repository maintenance and integrity checks
|
||||
- Proper backup and recovery procedures
|
||||
|
||||
## Error Messages and Solutions
|
||||
|
||||
### testutils Command Errors
|
||||
|
||||
#### inject-pkglist Errors
|
||||
**Error**: "Failed to open OSTree repository"
|
||||
```bash
|
||||
# Solution: Check repository path and permissions
|
||||
sudo ostree show --repo=/ostree/repo
|
||||
sudo chown -R root:root /ostree/repo
|
||||
```
|
||||
|
||||
**Error**: "Invalid commit reference"
|
||||
```bash
|
||||
# Solution: Verify commit exists and is accessible
|
||||
sudo ostree log --repo=/ostree/repo
|
||||
sudo ostree show --repo=/ostree/repo <commit-hash>
|
||||
```
|
||||
|
||||
**Error**: "Failed to inject package list"
|
||||
```bash
|
||||
# Solution: Check metadata format and permissions
|
||||
sudo ostree show --repo=/ostree/repo --print-metadata-key apt.packages <commit-hash>
|
||||
```
|
||||
|
||||
#### script-shell Errors
|
||||
**Error**: "Failed to create bubblewrap container"
|
||||
```bash
|
||||
# Solution: Check bubblewrap installation and permissions
|
||||
sudo apt-get install bubblewrap
|
||||
sudo chmod +s /usr/bin/bubblewrap
|
||||
```
|
||||
|
||||
**Error**: "Script execution failed"
|
||||
```bash
|
||||
# Solution: Verify script permissions and content
|
||||
chmod +x /tmp/test.sh
|
||||
cat /tmp/test.sh
|
||||
```
|
||||
|
||||
**Error**: "Invalid root path"
|
||||
```bash
|
||||
# Solution: Check path exists and is accessible
|
||||
ls -la /mnt/ostree/deploy/
|
||||
sudo mkdir -p /mnt/ostree/deploy/debian/13/amd64
|
||||
```
|
||||
|
||||
#### generate-synthetic-upgrade Errors
|
||||
**Error**: "Failed to generate upgrade"
|
||||
```bash
|
||||
# Solution: Check system state and dependencies
|
||||
sudo apt-ostree internals diagnostics
|
||||
sudo apt-ostree status
|
||||
```
|
||||
|
||||
**Error**: "Invalid package list"
|
||||
```bash
|
||||
# Solution: Verify package format and availability
|
||||
apt-cache search <package-name>
|
||||
apt-cache show <package-name>
|
||||
```
|
||||
|
||||
### shlib-backend Command Errors
|
||||
|
||||
#### get-basearch Errors
|
||||
**Error**: "Failed to determine architecture"
|
||||
```bash
|
||||
# Solution: Check system architecture detection
|
||||
dpkg --print-architecture
|
||||
uname -m
|
||||
arch
|
||||
```
|
||||
|
||||
**Error**: "Invalid deployment reference"
|
||||
```bash
|
||||
# Solution: Verify deployment exists
|
||||
sudo apt-ostree status
|
||||
sudo ostree log --repo=/ostree/repo
|
||||
```
|
||||
|
||||
#### varsubst-basearch Errors
|
||||
**Error**: "Invalid variable format"
|
||||
```bash
|
||||
# Solution: Check variable syntax
|
||||
echo "arch={{arch}}" | sudo apt-ostree shlib-backend varsubst-basearch
|
||||
```
|
||||
|
||||
**Error**: "Variable substitution failed"
|
||||
```bash
|
||||
# Solution: Verify variable values and format
|
||||
sudo apt-ostree shlib-backend get-basearch
|
||||
```
|
||||
|
||||
#### packagelist-from-commit Errors
|
||||
**Error**: "Commit not found"
|
||||
```bash
|
||||
# Solution: Verify commit exists
|
||||
sudo ostree log --repo=/ostree/repo
|
||||
sudo ostree show --repo=/ostree/repo <commit-hash>
|
||||
```
|
||||
|
||||
**Error**: "Failed to extract package list"
|
||||
```bash
|
||||
# Solution: Check commit metadata and permissions
|
||||
sudo ostree show --repo=/ostree/repo --print-metadata <commit-hash>
|
||||
```
|
||||
|
||||
### internals Command Errors
|
||||
|
||||
#### diagnostics Errors
|
||||
**Error**: "Diagnostics failed"
|
||||
```bash
|
||||
# Solution: Check system state and permissions
|
||||
sudo apt-ostree internals diagnostics --verbose
|
||||
sudo systemctl status apt-ostreed
|
||||
```
|
||||
|
||||
**Error**: "Component check failed"
|
||||
```bash
|
||||
# Solution: Check specific component status
|
||||
sudo apt-ostree internals diagnostics --category ostree
|
||||
sudo apt-ostree internals diagnostics --category apt
|
||||
```
|
||||
|
||||
#### validate-state Errors
|
||||
**Error**: "State validation failed"
|
||||
```bash
|
||||
# Solution: Check system consistency
|
||||
sudo apt-ostree internals validate-state --verbose
|
||||
sudo apt-ostree status
|
||||
```
|
||||
|
||||
**Error**: "Component validation failed"
|
||||
```bash
|
||||
# Solution: Check specific component state
|
||||
sudo apt-ostree internals validate-state --component ostree
|
||||
sudo apt-ostree internals validate-state --component apt
|
||||
```
|
||||
|
||||
#### debug-dump Errors
|
||||
**Error**: "Failed to dump debug information"
|
||||
```bash
|
||||
# Solution: Check permissions and output location
|
||||
sudo apt-ostree internals debug-dump --output /tmp/debug.json
|
||||
ls -la /tmp/debug.json
|
||||
```
|
||||
|
||||
**Error**: "Category dump failed"
|
||||
```bash
|
||||
# Solution: Check specific category availability
|
||||
sudo apt-ostree internals debug-dump --category system-info
|
||||
```
|
||||
|
||||
## Debugging Techniques
|
||||
|
||||
### Verbose Output
|
||||
```bash
|
||||
# Enable verbose output for all commands
|
||||
export APT_OSTREE_LOG_LEVEL=debug
|
||||
export RUST_LOG=debug
|
||||
|
||||
# Run commands with verbose flags
|
||||
sudo apt-ostree testutils script-shell /tmp/test.sh --verbose
|
||||
sudo apt-ostree internals diagnostics --verbose
|
||||
```
|
||||
|
||||
### Log Analysis
|
||||
```bash
|
||||
# Check daemon logs
|
||||
sudo journalctl -u apt-ostreed -f
|
||||
|
||||
# Check system logs
|
||||
sudo journalctl -f
|
||||
|
||||
# Check specific log files
|
||||
sudo tail -f /var/log/apt-ostreed.log
|
||||
```
|
||||
|
||||
### Step-by-Step Debugging
|
||||
```bash
|
||||
# 1. Check basic functionality
|
||||
sudo apt-ostree testutils moo
|
||||
|
||||
# 2. Verify system state
|
||||
sudo apt-ostree internals diagnostics
|
||||
|
||||
# 3. Test specific components
|
||||
sudo apt-ostree shlib-backend get-basearch
|
||||
|
||||
# 4. Check dependencies
|
||||
sudo apt-ostree internals validate-state
|
||||
|
||||
# 5. Generate debug information
|
||||
sudo apt-ostree internals debug-dump --output /tmp/debug.json
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
```bash
|
||||
# Set debugging environment variables
|
||||
export APT_OSTREE_DEBUG=1
|
||||
export APT_OSTREE_LOG_LEVEL=trace
|
||||
export RUST_BACKTRACE=1
|
||||
export RUST_LOG=trace
|
||||
|
||||
# Run commands with debugging
|
||||
sudo -E apt-ostree testutils script-shell /tmp/test.sh
|
||||
```
|
||||
|
||||
## Performance Issues
|
||||
|
||||
### Slow Command Execution
|
||||
**Problem**: Commands take too long to execute
|
||||
|
||||
**Causes**:
|
||||
- Large repository size
|
||||
- Network latency
|
||||
- Insufficient system resources
|
||||
- Inefficient algorithms
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# 1. Check system resources
|
||||
htop
|
||||
free -h
|
||||
df -h
|
||||
|
||||
# 2. Monitor command performance
|
||||
time sudo apt-ostree internals diagnostics
|
||||
|
||||
# 3. Use profiling tools
|
||||
cargo install flamegraph
|
||||
cargo flamegraph --bin apt-ostree -- internals diagnostics
|
||||
|
||||
# 4. Check repository size
|
||||
du -sh /ostree/repo/
|
||||
sudo ostree summary --repo=/ostree/repo
|
||||
```
|
||||
|
||||
**Optimization Techniques**:
|
||||
- Use appropriate timeouts for long-running operations
|
||||
- Implement caching for frequently accessed data
|
||||
- Optimize database queries and file operations
|
||||
- Use parallel processing where possible
|
||||
|
||||
### Memory Issues
|
||||
**Problem**: Commands consume excessive memory
|
||||
|
||||
**Causes**:
|
||||
- Memory leaks
|
||||
- Large data structures
|
||||
- Inefficient memory usage
|
||||
- Insufficient system memory
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# 1. Monitor memory usage
|
||||
ps aux | grep apt-ostree
|
||||
cat /proc/$(pgrep apt-ostree)/status | grep VmRSS
|
||||
|
||||
# 2. Check for memory leaks
|
||||
valgrind --tool=memcheck --leak-check=full apt-ostree internals diagnostics
|
||||
|
||||
# 3. Profile memory usage
|
||||
cargo install cargo-valgrind
|
||||
cargo valgrind test
|
||||
```
|
||||
|
||||
**Optimization Techniques**:
|
||||
- Use streaming for large data processing
|
||||
- Implement proper cleanup and resource management
|
||||
- Use appropriate data structures
|
||||
- Monitor memory usage patterns
|
||||
|
||||
## Security Issues
|
||||
|
||||
### Authentication Failures
|
||||
**Problem**: Commands fail due to authentication issues
|
||||
|
||||
**Causes**:
|
||||
- Invalid user credentials
|
||||
- Expired authentication tokens
|
||||
- Polkit policy restrictions
|
||||
- D-Bus authentication failures
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# 1. Check user authentication
|
||||
whoami
|
||||
groups $USER
|
||||
|
||||
# 2. Verify Polkit policies
|
||||
sudo polkit-policy-file-validate /usr/share/polkit-1/actions/org.projectatomic.aptostree1.policy
|
||||
|
||||
# 3. Check D-Bus authentication
|
||||
dbus-send --system --dest=org.freedesktop.DBus --type=method_call --print-reply /org/freedesktop/DBus org.freedesktop.DBus.ListNames
|
||||
|
||||
# 4. Test Polkit authentication
|
||||
pkcheck --action-id org.projectatomic.aptostree1.manage --process $$ --user $USER
|
||||
```
|
||||
|
||||
**Prevention**:
|
||||
- Configure appropriate Polkit policies
|
||||
- Use proper user authentication mechanisms
|
||||
- Implement audit logging for security events
|
||||
- Regular security policy reviews
|
||||
|
||||
### Permission Escalation
|
||||
**Problem**: Commands gain unexpected privileges
|
||||
|
||||
**Causes**:
|
||||
- Incorrect file permissions
|
||||
- Insecure Polkit policies
|
||||
- D-Bus interface vulnerabilities
|
||||
- Container escape vulnerabilities
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# 1. Check file permissions
|
||||
ls -la /usr/bin/apt-ostree
|
||||
ls -la /var/lib/apt-ostree/
|
||||
|
||||
# 2. Verify Polkit policy security
|
||||
sudo polkit-policy-file-validate /usr/share/polkit-1/actions/org.projectatomic.aptostree1.policy
|
||||
|
||||
# 3. Check container isolation
|
||||
bubblewrap --dev-bind / / --proc /proc -- id
|
||||
|
||||
# 4. Audit privilege usage
|
||||
sudo journalctl -u apt-ostreed | grep -i "privilege\|permission\|auth"
|
||||
```
|
||||
|
||||
**Prevention**:
|
||||
- Implement principle of least privilege
|
||||
- Use secure containerization techniques
|
||||
- Regular security audits and penetration testing
|
||||
- Proper input validation and sanitization
|
||||
|
||||
## System-Specific Problems
|
||||
|
||||
### Debian/Ubuntu Issues
|
||||
**Problem**: Commands fail on specific Debian/Ubuntu versions
|
||||
|
||||
**Causes**:
|
||||
- Version-specific dependencies
|
||||
- Package compatibility issues
|
||||
- System configuration differences
|
||||
- Kernel version limitations
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# 1. Check system version
|
||||
cat /etc/os-release
|
||||
lsb_release -a
|
||||
|
||||
# 2. Verify package compatibility
|
||||
apt-cache policy apt-ostree
|
||||
apt-cache policy libostree-1-1
|
||||
|
||||
# 3. Check kernel version
|
||||
uname -r
|
||||
|
||||
# 4. Verify system requirements
|
||||
dpkg -l | grep -E "(ostree|apt|polkit)"
|
||||
```
|
||||
|
||||
**Prevention**:
|
||||
- Test on multiple system versions
|
||||
- Document version-specific requirements
|
||||
- Implement compatibility checks
|
||||
- Use appropriate dependency versions
|
||||
|
||||
### Architecture-Specific Issues
|
||||
**Problem**: Commands fail on specific architectures
|
||||
|
||||
**Causes**:
|
||||
- Architecture-specific bugs
|
||||
- Missing architecture support
|
||||
- Binary compatibility issues
|
||||
- Endianness problems
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# 1. Check system architecture
|
||||
dpkg --print-architecture
|
||||
uname -m
|
||||
arch
|
||||
|
||||
# 2. Verify binary compatibility
|
||||
file /usr/bin/apt-ostree
|
||||
ldd /usr/bin/apt-ostree
|
||||
|
||||
# 3. Check architecture support
|
||||
apt-ostree shlib-backend get-basearch
|
||||
|
||||
# 4. Test cross-compilation
|
||||
cargo build --target aarch64-unknown-linux-gnu
|
||||
```
|
||||
|
||||
**Prevention**:
|
||||
- Test on multiple architectures
|
||||
- Implement architecture-specific code paths
|
||||
- Use portable data formats
|
||||
- Regular cross-architecture testing
|
||||
|
||||
### Container/VM Issues
|
||||
**Problem**: Commands fail in containerized or virtualized environments
|
||||
|
||||
**Causes**:
|
||||
- Limited system access
|
||||
- Missing hardware support
|
||||
- Resource limitations
|
||||
- Isolation restrictions
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# 1. Check container environment
|
||||
cat /proc/1/cgroup
|
||||
systemd-detect-virt
|
||||
|
||||
# 2. Verify system capabilities
|
||||
capsh --print
|
||||
|
||||
# 3. Check resource limits
|
||||
ulimit -a
|
||||
cat /proc/self/limits
|
||||
|
||||
# 4. Test basic functionality
|
||||
apt-ostree testutils moo
|
||||
```
|
||||
|
||||
**Prevention**:
|
||||
- Test in various container environments
|
||||
- Implement graceful degradation
|
||||
- Document environment requirements
|
||||
- Use appropriate resource limits
|
||||
|
||||
## Best Practices for Troubleshooting
|
||||
|
||||
### Systematic Approach
|
||||
1. **Identify the problem**: Understand what's failing and why
|
||||
2. **Check system state**: Verify system health and configuration
|
||||
3. **Test basic functionality**: Ensure core components work
|
||||
4. **Isolate the issue**: Narrow down the problem scope
|
||||
5. **Apply solutions**: Implement appropriate fixes
|
||||
6. **Verify resolution**: Confirm the problem is solved
|
||||
7. **Document solution**: Record the problem and solution
|
||||
|
||||
### Logging and Monitoring
|
||||
```bash
|
||||
# Enable comprehensive logging
|
||||
export APT_OSTREE_LOG_LEVEL=debug
|
||||
export RUST_LOG=debug
|
||||
|
||||
# Monitor system resources
|
||||
htop
|
||||
iotop
|
||||
nethogs
|
||||
|
||||
# Track command execution
|
||||
time sudo apt-ostree internals diagnostics
|
||||
```
|
||||
|
||||
### Testing and Validation
|
||||
```bash
|
||||
# Test in isolated environment
|
||||
sudo apt-ostree testutils script-shell /tmp/test.sh --read-only
|
||||
|
||||
# Validate system state
|
||||
sudo apt-ostree internals validate-state
|
||||
|
||||
# Run comprehensive diagnostics
|
||||
sudo apt-ostree internals diagnostics --verbose
|
||||
```
|
||||
|
||||
### Documentation and Knowledge Base
|
||||
- **Record problems**: Document all issues and solutions
|
||||
- **Build knowledge base**: Create troubleshooting guides
|
||||
- **Share solutions**: Contribute to community knowledge
|
||||
- **Regular updates**: Keep documentation current
|
||||
|
||||
---
|
||||
|
||||
*This guide covers troubleshooting for apt-ostree development commands. For general troubleshooting, refer to the main User Guide.*
|
||||
509
docs/development-commands-usage.md
Normal file
509
docs/development-commands-usage.md
Normal file
|
|
@ -0,0 +1,509 @@
|
|||
# Development Commands Usage Guide
|
||||
|
||||
## Overview
|
||||
This document provides comprehensive usage examples for apt-ostree's development commands. These commands are hidden from normal help output and are intended for developers and system administrators debugging apt-ostree installations.
|
||||
|
||||
## Table of Contents
|
||||
1. [testutils Commands](#testutils-commands)
|
||||
2. [shlib-backend Commands](#shlib-backend-commands)
|
||||
3. [internals Commands](#internals-commands)
|
||||
4. [Common Use Cases](#common-use-cases)
|
||||
5. [Troubleshooting](#troubleshooting)
|
||||
|
||||
## testutils Commands
|
||||
|
||||
### inject-pkglist
|
||||
Inject a package list into an OSTree commit's metadata.
|
||||
|
||||
#### Basic Usage
|
||||
```bash
|
||||
# Inject a simple package list
|
||||
sudo apt-ostree testutils inject-pkglist abc123 "apt,curl,nginx"
|
||||
|
||||
# Inject with specific commit and packages
|
||||
sudo apt-ostree testutils inject-pkglist \
|
||||
debian/13/amd64/commit/2025-01-15T10:30:00Z \
|
||||
"apt,curl,nginx,postgresql-client"
|
||||
```
|
||||
|
||||
#### Advanced Usage
|
||||
```bash
|
||||
# Inject from file
|
||||
cat packages.txt | sudo apt-ostree testutils inject-pkglist abc123 -
|
||||
|
||||
# Inject with validation
|
||||
sudo apt-ostree testutils inject-pkglist \
|
||||
--validate-dependencies \
|
||||
abc123 \
|
||||
"apt,curl,nginx"
|
||||
```
|
||||
|
||||
#### Use Cases
|
||||
- **Testing package management**: Verify package list injection works correctly
|
||||
- **Development workflows**: Test package metadata handling
|
||||
- **Debugging**: Investigate package list issues in commits
|
||||
|
||||
### script-shell
|
||||
Execute a script in a bubblewrap container with various options.
|
||||
|
||||
#### Basic Usage
|
||||
```bash
|
||||
# Execute a simple script
|
||||
sudo apt-ostree testutils script-shell /tmp/test.sh
|
||||
|
||||
# Execute with arguments
|
||||
sudo apt-ostree testutils script-shell /tmp/install.sh --install-package nginx
|
||||
|
||||
# Execute in read-only mode
|
||||
sudo apt-ostree testutils script-shell /tmp/check.sh --read-only
|
||||
```
|
||||
|
||||
#### Advanced Options
|
||||
```bash
|
||||
# Execute with custom root path
|
||||
sudo apt-ostree testutils script-shell \
|
||||
--rootpath /mnt/ostree/deploy/debian/13/amd64 \
|
||||
/tmp/deploy-check.sh
|
||||
|
||||
# Execute as specific user/group
|
||||
sudo apt-ostree testutils script-shell \
|
||||
--user www-data \
|
||||
--group www-data \
|
||||
/tmp/web-test.sh
|
||||
|
||||
# Execute with custom working directory
|
||||
sudo apt-ostree testutils script-shell \
|
||||
--cwd /var/www \
|
||||
/tmp/web-deploy.sh
|
||||
|
||||
# Execute with environment variables
|
||||
sudo apt-ostree testutils script-shell \
|
||||
--env "DEBUG=1" \
|
||||
--env "TEST_MODE=1" \
|
||||
/tmp/debug-test.sh
|
||||
```
|
||||
|
||||
#### Use Cases
|
||||
- **Testing deployments**: Verify scripts work in isolated environments
|
||||
- **Debugging**: Test scripts without affecting the main system
|
||||
- **Development**: Develop and test deployment scripts safely
|
||||
|
||||
### generate-synthetic-upgrade
|
||||
Generate a synthetic upgrade for testing purposes.
|
||||
|
||||
#### Basic Usage
|
||||
```bash
|
||||
# Generate basic synthetic upgrade
|
||||
sudo apt-ostree testutils generate-synthetic-upgrade
|
||||
|
||||
# Generate with specific parameters
|
||||
sudo apt-ostree testutils generate-synthetic-upgrade \
|
||||
--packages "apt,curl,nginx" \
|
||||
--version-increment "patch"
|
||||
```
|
||||
|
||||
#### Advanced Usage
|
||||
```bash
|
||||
# Generate upgrade with custom metadata
|
||||
sudo apt-ostree testutils generate-synthetic-upgrade \
|
||||
--metadata "test-mode=true" \
|
||||
--metadata "generated-by=test-suite"
|
||||
|
||||
# Generate upgrade for specific architecture
|
||||
sudo apt-ostree testutils generate-synthetic-upgrade \
|
||||
--architecture amd64 \
|
||||
--os-version "debian/13"
|
||||
```
|
||||
|
||||
#### Use Cases
|
||||
- **Testing upgrade paths**: Verify upgrade mechanisms work correctly
|
||||
- **Development testing**: Test upgrade logic without real packages
|
||||
- **CI/CD pipelines**: Generate test data for automated testing
|
||||
|
||||
### integration-read-only
|
||||
Run integration tests in read-only mode.
|
||||
|
||||
#### Basic Usage
|
||||
```bash
|
||||
# Run basic integration tests
|
||||
sudo apt-ostree testutils integration-read-only
|
||||
|
||||
# Run with specific test categories
|
||||
sudo apt-ostree testutils integration-read-only \
|
||||
--test-category "package-management" \
|
||||
--test-category "system-operations"
|
||||
```
|
||||
|
||||
#### Advanced Usage
|
||||
```bash
|
||||
# Run with custom test parameters
|
||||
sudo apt-ostree testutils integration-read-only \
|
||||
--test-timeout 300 \
|
||||
--verbose-output \
|
||||
--save-results /tmp/test-results.json
|
||||
```
|
||||
|
||||
#### Use Cases
|
||||
- **System validation**: Verify system state without making changes
|
||||
- **Pre-deployment testing**: Test system before applying changes
|
||||
- **Health checks**: Monitor system health and configuration
|
||||
|
||||
### c-units
|
||||
Run C unit tests if available.
|
||||
|
||||
#### Basic Usage
|
||||
```bash
|
||||
# Run all available C unit tests
|
||||
sudo apt-ostree testutils c-units
|
||||
|
||||
# Run specific test suite
|
||||
sudo apt-ostree testutils c-units --suite "ostree-integration"
|
||||
|
||||
# Run with verbose output
|
||||
sudo apt-ostree testutils c-units --verbose
|
||||
```
|
||||
|
||||
#### Advanced Usage
|
||||
```bash
|
||||
# Run tests with custom compiler flags
|
||||
sudo apt-ostree testutils c-units \
|
||||
--cflags "-O2 -g" \
|
||||
--ldflags "-L/usr/local/lib"
|
||||
|
||||
# Run tests in parallel
|
||||
sudo apt-ostree testutils c-units --parallel --jobs 4
|
||||
```
|
||||
|
||||
#### Use Cases
|
||||
- **C library testing**: Test C library integrations
|
||||
- **Performance testing**: Benchmark C-based operations
|
||||
- **Compatibility testing**: Verify C library compatibility
|
||||
|
||||
### moo
|
||||
Perform basic functionality tests.
|
||||
|
||||
#### Basic Usage
|
||||
```bash
|
||||
# Run basic functionality tests
|
||||
sudo apt-ostree testutils moo
|
||||
|
||||
# Run specific test categories
|
||||
sudo apt-ostree testutils moo --category "core-functions"
|
||||
```
|
||||
|
||||
#### Use Cases
|
||||
- **Quick health check**: Verify basic system functionality
|
||||
- **Development testing**: Test during development cycles
|
||||
- **Troubleshooting**: Identify basic system issues
|
||||
|
||||
## shlib-backend Commands
|
||||
|
||||
### get-basearch
|
||||
Get the system's base architecture.
|
||||
|
||||
#### Basic Usage
|
||||
```bash
|
||||
# Get current system architecture
|
||||
sudo apt-ostree shlib-backend get-basearch
|
||||
|
||||
# Get architecture for specific deployment
|
||||
sudo apt-ostree shlib-backend get-basearch --deployment debian/13/amd64
|
||||
```
|
||||
|
||||
#### Use Cases
|
||||
- **Architecture detection**: Determine system architecture
|
||||
- **Package selection**: Select appropriate packages for architecture
|
||||
- **Deployment targeting**: Target deployments for specific architectures
|
||||
|
||||
### varsubst-basearch
|
||||
Perform variable substitution for architecture-specific strings.
|
||||
|
||||
#### Basic Usage
|
||||
```bash
|
||||
# Substitute architecture variables
|
||||
echo "arch={{arch}}" | sudo apt-ostree shlib-backend varsubst-basearch
|
||||
|
||||
# Substitute with custom source
|
||||
sudo apt-ostree shlib-backend varsubst-basearch \
|
||||
"Package-{{arch}}-{{os}}-{{version}}.deb"
|
||||
```
|
||||
|
||||
#### Advanced Usage
|
||||
```bash
|
||||
# Substitute multiple variables
|
||||
sudo apt-ostree shlib-backend varsubst-basearch \
|
||||
"{{os}}-{{arch}}-{{version}}-{{flavor}}"
|
||||
|
||||
# Substitute with custom values
|
||||
sudo apt-ostree shlib-backend varsubst-basearch \
|
||||
--custom-vars "os=debian,version=13,flavor=minimal" \
|
||||
"{{os}}-{{arch}}-{{version}}-{{flavor}}"
|
||||
```
|
||||
|
||||
#### Use Cases
|
||||
- **Template processing**: Process configuration templates
|
||||
- **Package naming**: Generate architecture-specific package names
|
||||
- **Deployment scripts**: Create architecture-aware deployment scripts
|
||||
|
||||
### packagelist-from-commit
|
||||
Extract package list from an OSTree commit.
|
||||
|
||||
#### Basic Usage
|
||||
```bash
|
||||
# Extract package list from commit
|
||||
sudo apt-ostree shlib-backend packagelist-from-commit abc123
|
||||
|
||||
# Extract with specific format
|
||||
sudo apt-ostree shlib-backend packagelist-from-commit \
|
||||
--format json \
|
||||
abc123
|
||||
```
|
||||
|
||||
#### Advanced Usage
|
||||
```bash
|
||||
# Extract with metadata
|
||||
sudo apt-ostree shlib-backend packagelist-from-commit \
|
||||
--include-metadata \
|
||||
--metadata-keys "apt.packages,apt.dependencies" \
|
||||
abc123
|
||||
|
||||
# Extract to file
|
||||
sudo apt-ostree shlib-backend packagelist-from-commit \
|
||||
--output /tmp/packages.txt \
|
||||
abc123
|
||||
```
|
||||
|
||||
#### Use Cases
|
||||
- **Package analysis**: Analyze packages in specific commits
|
||||
- **Dependency tracking**: Track package dependencies across commits
|
||||
- **Audit trails**: Create audit trails of package changes
|
||||
|
||||
## internals Commands
|
||||
|
||||
### diagnostics
|
||||
Run comprehensive system diagnostics.
|
||||
|
||||
#### Basic Usage
|
||||
```bash
|
||||
# Run all diagnostics
|
||||
sudo apt-ostree internals diagnostics
|
||||
|
||||
# Run specific diagnostic categories
|
||||
sudo apt-ostree internals diagnostics \
|
||||
--category "ostree" \
|
||||
--category "apt" \
|
||||
--category "daemon"
|
||||
```
|
||||
|
||||
#### Advanced Usage
|
||||
```bash
|
||||
# Run with custom parameters
|
||||
sudo apt-ostree internals diagnostics \
|
||||
--timeout 600 \
|
||||
--output-format json \
|
||||
--save-report /tmp/diagnostics.json
|
||||
|
||||
# Run with specific checks
|
||||
sudo apt-ostree internals diagnostics \
|
||||
--checks "repository-integrity,package-database,daemon-status"
|
||||
```
|
||||
|
||||
#### Use Cases
|
||||
- **System health check**: Comprehensive system health assessment
|
||||
- **Problem diagnosis**: Identify system issues and misconfigurations
|
||||
- **Pre-maintenance**: Verify system state before maintenance
|
||||
|
||||
### validate-state
|
||||
Validate system state consistency.
|
||||
|
||||
#### Basic Usage
|
||||
```bash
|
||||
# Validate current system state
|
||||
sudo apt-ostree internals validate-state
|
||||
|
||||
# Validate specific components
|
||||
sudo apt-ostree internals validate-state \
|
||||
--component "ostree" \
|
||||
--component "apt"
|
||||
```
|
||||
|
||||
#### Advanced Usage
|
||||
```bash
|
||||
# Validate with custom rules
|
||||
sudo apt-ostree internals validate-state \
|
||||
--rules-file /etc/apt-ostree/validation-rules.toml \
|
||||
--strict-mode
|
||||
|
||||
# Validate and generate report
|
||||
sudo apt-ostree internals validate-state \
|
||||
--generate-report \
|
||||
--report-format html \
|
||||
--output /tmp/validation-report.html
|
||||
```
|
||||
|
||||
#### Use Cases
|
||||
- **State verification**: Verify system state consistency
|
||||
- **Configuration validation**: Validate configuration files and settings
|
||||
- **Pre-deployment check**: Verify system state before deployments
|
||||
|
||||
### debug-dump
|
||||
Dump comprehensive system information for debugging.
|
||||
|
||||
#### Basic Usage
|
||||
```bash
|
||||
# Dump all system information
|
||||
sudo apt-ostree internals debug-dump
|
||||
|
||||
# Dump specific information categories
|
||||
sudo apt-ostree internals debug-dump \
|
||||
--category "system-info" \
|
||||
--category "ostree-info" \
|
||||
--category "apt-info"
|
||||
```
|
||||
|
||||
#### Advanced Usage
|
||||
```bash
|
||||
# Dump with custom format
|
||||
sudo apt-ostree internals debug-dump \
|
||||
--format json \
|
||||
--output /tmp/debug-dump.json
|
||||
|
||||
# Dump with filtering
|
||||
sudo apt-ostree internals debug-dump \
|
||||
--filter "error-only" \
|
||||
--include-logs \
|
||||
--log-level debug
|
||||
```
|
||||
|
||||
#### Use Cases
|
||||
- **Debugging**: Comprehensive debugging information
|
||||
- **Support requests**: Generate information for support requests
|
||||
- **System analysis**: Analyze system configuration and state
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
### Development Workflow
|
||||
```bash
|
||||
# 1. Check system health
|
||||
sudo apt-ostree internals diagnostics
|
||||
|
||||
# 2. Validate system state
|
||||
sudo apt-ostree internals validate-state
|
||||
|
||||
# 3. Test new functionality
|
||||
sudo apt-ostree testutils script-shell /tmp/test-feature.sh
|
||||
|
||||
# 4. Generate test data
|
||||
sudo apt-ostree testutils generate-synthetic-upgrade
|
||||
|
||||
# 5. Verify results
|
||||
sudo apt-ostree internals debug-dump
|
||||
```
|
||||
|
||||
### Troubleshooting Workflow
|
||||
```bash
|
||||
# 1. Run comprehensive diagnostics
|
||||
sudo apt-ostree internals diagnostics --verbose
|
||||
|
||||
# 2. Check specific components
|
||||
sudo apt-ostree shlib-backend get-basearch
|
||||
sudo apt-ostree testutils moo
|
||||
|
||||
# 3. Validate system state
|
||||
sudo apt-ostree internals validate-state --strict-mode
|
||||
|
||||
# 4. Generate debug report
|
||||
sudo apt-ostree internals debug-dump --output /tmp/troubleshoot.json
|
||||
```
|
||||
|
||||
### Testing Workflow
|
||||
```bash
|
||||
# 1. Set up test environment
|
||||
sudo apt-ostree testutils script-shell /tmp/setup-test-env.sh
|
||||
|
||||
# 2. Run integration tests
|
||||
sudo apt-ostree testutils integration-read-only
|
||||
|
||||
# 3. Test package operations
|
||||
sudo apt-ostree testutils inject-pkglist test-commit "test-package"
|
||||
|
||||
# 4. Verify test results
|
||||
sudo apt-ostree internals debug-dump --category "test-results"
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Permission Denied
|
||||
```bash
|
||||
# Check if running as root
|
||||
sudo apt-ostree testutils moo
|
||||
|
||||
# Check Polkit policies
|
||||
sudo polkit-policy-file-validate /usr/share/polkit-1/actions/org.projectatomic.aptostree1.policy
|
||||
```
|
||||
|
||||
#### Command Not Found
|
||||
```bash
|
||||
# Verify development features are enabled
|
||||
cargo build --features development
|
||||
|
||||
# Check if binary includes development commands
|
||||
cargo run --features development -- testutils --help
|
||||
```
|
||||
|
||||
#### Bubblewrap Issues
|
||||
```bash
|
||||
# Check bubblewrap installation
|
||||
which bubblewrap
|
||||
bubblewrap --version
|
||||
|
||||
# Test bubblewrap functionality
|
||||
bubblewrap --dev-bind / / --proc /proc -- echo "test"
|
||||
```
|
||||
|
||||
#### OSTree Repository Issues
|
||||
```bash
|
||||
# Check repository status
|
||||
sudo ostree show --repo=/ostree/repo
|
||||
|
||||
# Verify repository integrity
|
||||
sudo ostree fsck --repo=/ostree/repo
|
||||
```
|
||||
|
||||
### Debug Mode
|
||||
```bash
|
||||
# Enable debug logging
|
||||
export APT_OSTREE_LOG_LEVEL=debug
|
||||
export RUST_LOG=debug
|
||||
|
||||
# Run commands with verbose output
|
||||
sudo apt-ostree testutils script-shell /tmp/test.sh --verbose
|
||||
```
|
||||
|
||||
### Log Files
|
||||
- **Daemon logs**: `/var/log/apt-ostreed.log`
|
||||
- **System logs**: `sudo journalctl -u apt-ostreed`
|
||||
- **OSTree logs**: `sudo ostree log --repo=/ostree/repo`
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Security Considerations
|
||||
- **Limited access**: Only authorized users should have access to development commands
|
||||
- **Isolated execution**: Use script-shell with appropriate isolation options
|
||||
- **Audit trails**: Log all development command usage for audit purposes
|
||||
|
||||
### Performance Considerations
|
||||
- **Resource limits**: Set appropriate limits for development operations
|
||||
- **Timeout handling**: Use appropriate timeouts for long-running operations
|
||||
- **Resource cleanup**: Ensure proper cleanup after development operations
|
||||
|
||||
### Development Workflow
|
||||
- **Testing**: Always test development commands in isolated environments
|
||||
- **Documentation**: Document custom usage patterns and configurations
|
||||
- **Version control**: Track changes to development command usage
|
||||
|
||||
---
|
||||
|
||||
*This guide covers the usage of apt-ostree development commands. For general usage, refer to the main User Guide.*
|
||||
523
docs/development-workflow.md
Normal file
523
docs/development-workflow.md
Normal file
|
|
@ -0,0 +1,523 @@
|
|||
# Development Workflow Documentation
|
||||
|
||||
## Overview
|
||||
This document describes the development workflow for apt-ostree, including setup, testing, debugging, and contribution guidelines. It provides developers with a comprehensive guide to working with the codebase.
|
||||
|
||||
## Table of Contents
|
||||
1. [Development Environment Setup](#development-environment-setup)
|
||||
2. [Development Workflow](#development-workflow)
|
||||
3. [Testing Procedures](#testing-procedures)
|
||||
4. [Debugging Techniques](#debugging-techniques)
|
||||
5. [Code Quality and Standards](#code-quality-and-standards)
|
||||
6. [Contribution Guidelines](#contribution-guidelines)
|
||||
7. [Release Process](#release-process)
|
||||
|
||||
## Development Environment Setup
|
||||
|
||||
### Prerequisites
|
||||
- **Rust toolchain**: Rust 1.75+ with Cargo
|
||||
- **System dependencies**: See installation guide
|
||||
- **Development tools**: Git, make, pkg-config
|
||||
- **Documentation tools**: rustdoc, cargo-doc
|
||||
|
||||
### Initial Setup
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://github.com/robojerk/apt-ostree.git
|
||||
cd apt-ostree
|
||||
|
||||
# Install Rust toolchain
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
source ~/.cargo/env
|
||||
|
||||
# Install system dependencies
|
||||
sudo apt-get install build-essential pkg-config \
|
||||
libostree-dev libapt-pkg-dev libpolkit-gobject-1-dev \
|
||||
libdbus-1-dev libsystemd-dev
|
||||
|
||||
# Install development tools
|
||||
cargo install cargo-outdated cargo-audit cargo-tarpaulin
|
||||
```
|
||||
|
||||
### Environment Configuration
|
||||
```bash
|
||||
# Set development environment variables
|
||||
export APT_OSTREE_DEV_MODE=1
|
||||
export APT_OSTREE_LOG_LEVEL=debug
|
||||
export RUST_LOG=debug
|
||||
|
||||
# Add to ~/.bashrc or ~/.zshrc
|
||||
echo 'export APT_OSTREE_DEV_MODE=1' >> ~/.bashrc
|
||||
echo 'export APT_OSTREE_LOG_LEVEL=debug' >> ~/.bashrc
|
||||
echo 'export RUST_LOG=debug' >> ~/.bashrc
|
||||
```
|
||||
|
||||
### IDE Configuration
|
||||
#### VS Code
|
||||
```json
|
||||
// .vscode/settings.json
|
||||
{
|
||||
"rust-analyzer.checkOnSave.command": "clippy",
|
||||
"rust-analyzer.cargo.features": ["development"],
|
||||
"rust-analyzer.procMacro.enable": true,
|
||||
"rust-analyzer.cargo.buildScripts.enable": true
|
||||
}
|
||||
```
|
||||
|
||||
#### IntelliJ IDEA / CLion
|
||||
- Install Rust plugin
|
||||
- Configure Rust toolchain
|
||||
- Enable Cargo features: `development,dev-full`
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Daily Development Cycle
|
||||
```bash
|
||||
# 1. Start development session
|
||||
git pull origin main
|
||||
cargo check --features development
|
||||
|
||||
# 2. Make changes and test
|
||||
cargo build --features development
|
||||
cargo test --features development
|
||||
|
||||
# 3. Commit changes
|
||||
git add .
|
||||
git commit -m "feat(commands): add new feature X"
|
||||
|
||||
# 4. Push changes
|
||||
git push origin feature-branch
|
||||
```
|
||||
|
||||
### Feature Development Workflow
|
||||
```bash
|
||||
# 1. Create feature branch
|
||||
git checkout -b feature/new-feature
|
||||
|
||||
# 2. Implement feature
|
||||
# ... make changes ...
|
||||
|
||||
# 3. Add tests
|
||||
# ... add test cases ...
|
||||
|
||||
# 4. Update documentation
|
||||
# ... update docs ...
|
||||
|
||||
# 5. Test thoroughly
|
||||
cargo test --features development
|
||||
cargo clippy --features development
|
||||
|
||||
# 6. Create pull request
|
||||
git push origin feature/new-feature
|
||||
# Create PR on GitHub
|
||||
```
|
||||
|
||||
### Bug Fix Workflow
|
||||
```bash
|
||||
# 1. Create bug fix branch
|
||||
git checkout -b fix/bug-description
|
||||
|
||||
# 2. Reproduce bug
|
||||
# ... reproduce issue ...
|
||||
|
||||
# 3. Fix bug
|
||||
# ... implement fix ...
|
||||
|
||||
# 4. Add regression test
|
||||
# ... add test case ...
|
||||
|
||||
# 5. Test fix
|
||||
cargo test --features development
|
||||
|
||||
# 6. Create pull request
|
||||
git push origin fix/bug-description
|
||||
```
|
||||
|
||||
## Testing Procedures
|
||||
|
||||
### Unit Testing
|
||||
```bash
|
||||
# Run all unit tests
|
||||
cargo test
|
||||
|
||||
# Run specific test module
|
||||
cargo test commands::package
|
||||
|
||||
# Run tests with output
|
||||
cargo test -- --nocapture
|
||||
|
||||
# Run tests with specific feature
|
||||
cargo test --features development
|
||||
|
||||
# Run tests in parallel
|
||||
cargo test -- --test-threads 4
|
||||
```
|
||||
|
||||
### Integration Testing
|
||||
```bash
|
||||
# Run integration tests
|
||||
cargo test --test integration_tests
|
||||
|
||||
# Run specific integration test
|
||||
cargo test --test integration_tests test_package_installation
|
||||
|
||||
# Run integration tests with verbose output
|
||||
cargo test --test integration_tests -- --nocapture
|
||||
```
|
||||
|
||||
### Development Commands Testing
|
||||
```bash
|
||||
# Test development commands
|
||||
cargo run --features development -- testutils --help
|
||||
cargo run --features development -- shlib-backend --help
|
||||
cargo run --features development -- internals --help
|
||||
|
||||
# Test specific development command
|
||||
cargo run --features development -- testutils moo
|
||||
cargo run --features development -- shlib-backend get-basearch
|
||||
cargo run --features development -- internals diagnostics
|
||||
```
|
||||
|
||||
### Performance Testing
|
||||
```bash
|
||||
# Install performance testing tools
|
||||
cargo install cargo-bench
|
||||
|
||||
# Run benchmarks
|
||||
cargo bench
|
||||
|
||||
# Profile performance
|
||||
cargo install flamegraph
|
||||
cargo flamegraph --bin apt-ostree -- internals diagnostics
|
||||
|
||||
# Memory profiling
|
||||
cargo install cargo-valgrind
|
||||
cargo valgrind test
|
||||
```
|
||||
|
||||
### Security Testing
|
||||
```bash
|
||||
# Run security audit
|
||||
cargo audit
|
||||
|
||||
# Check for known vulnerabilities
|
||||
cargo audit --deny warnings
|
||||
|
||||
# Dependency vulnerability scan
|
||||
cargo install cargo-audit
|
||||
cargo audit
|
||||
```
|
||||
|
||||
## Debugging Techniques
|
||||
|
||||
### Logging and Tracing
|
||||
```rust
|
||||
use tracing::{info, warn, error, debug, trace};
|
||||
|
||||
// Set log level
|
||||
std::env::set_var("RUST_LOG", "debug");
|
||||
|
||||
// Use in code
|
||||
debug!("Debug information: {:?}", data);
|
||||
info!("Information message: {}", message);
|
||||
warn!("Warning message: {}", warning);
|
||||
error!("Error message: {}", error);
|
||||
trace!("Trace information: {:?}", trace_data);
|
||||
```
|
||||
|
||||
### Interactive Debugging
|
||||
```bash
|
||||
# Run with debugger
|
||||
rust-gdb --args target/debug/apt-ostree internals diagnostics
|
||||
|
||||
# Use println! for quick debugging
|
||||
cargo run --features development -- internals diagnostics
|
||||
|
||||
# Enable backtrace
|
||||
export RUST_BACKTRACE=1
|
||||
cargo run --features development -- internals diagnostics
|
||||
```
|
||||
|
||||
### Development Commands for Debugging
|
||||
```bash
|
||||
# Run system diagnostics
|
||||
sudo apt-ostree internals diagnostics --verbose
|
||||
|
||||
# Validate system state
|
||||
sudo apt-ostree internals validate-state --strict-mode
|
||||
|
||||
# Dump debug information
|
||||
sudo apt-ostree internals debug-dump --output /tmp/debug.json
|
||||
|
||||
# Test basic functionality
|
||||
sudo apt-ostree testutils moo
|
||||
|
||||
# Execute debug script
|
||||
sudo apt-ostree testutils script-shell /tmp/debug.sh --verbose
|
||||
```
|
||||
|
||||
### Profiling and Analysis
|
||||
```bash
|
||||
# CPU profiling
|
||||
cargo install cargo-flamegraph
|
||||
cargo flamegraph --bin apt-ostree -- internals diagnostics
|
||||
|
||||
# Memory profiling
|
||||
cargo install cargo-valgrind
|
||||
cargo valgrind test
|
||||
|
||||
# Code coverage
|
||||
cargo install cargo-tarpaulin
|
||||
cargo tarpaulin --out Html --output-dir coverage
|
||||
```
|
||||
|
||||
## Code Quality and Standards
|
||||
|
||||
### Code Style
|
||||
- **Rust conventions**: Follow Rust style guide and idioms
|
||||
- **Formatting**: Use `cargo fmt` for consistent formatting
|
||||
- **Documentation**: Document all public APIs with doc comments
|
||||
- **Error handling**: Use proper error types and Result handling
|
||||
|
||||
### Linting and Analysis
|
||||
```bash
|
||||
# Run Clippy
|
||||
cargo clippy --features development
|
||||
|
||||
# Run with specific rules
|
||||
cargo clippy --features development -- -D warnings
|
||||
|
||||
# Allow specific warnings
|
||||
cargo clippy --features development -- -D warnings -A clippy::too_many_arguments
|
||||
|
||||
# Check formatting
|
||||
cargo fmt -- --check
|
||||
|
||||
# Format code
|
||||
cargo fmt
|
||||
```
|
||||
|
||||
### Documentation Standards
|
||||
```rust
|
||||
/// Brief description of the function
|
||||
///
|
||||
/// Detailed description with examples and usage notes.
|
||||
///
|
||||
/// # Arguments
|
||||
/// * `param1` - Description of first parameter
|
||||
/// * `param2` - Description of second parameter
|
||||
///
|
||||
/// # Returns
|
||||
/// Result containing success value or error
|
||||
///
|
||||
/// # Examples
|
||||
/// ```
|
||||
/// use apt_ostree::lib::example::Example;
|
||||
///
|
||||
/// let result = Example::new().do_something();
|
||||
/// assert!(result.is_ok());
|
||||
/// ```
|
||||
///
|
||||
/// # Errors
|
||||
/// Returns error if operation fails
|
||||
pub fn example_function(param1: String, param2: u32) -> Result<(), Error> {
|
||||
// Implementation
|
||||
}
|
||||
```
|
||||
|
||||
### Testing Standards
|
||||
```rust
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_function_name() {
|
||||
// Arrange
|
||||
let input = "test";
|
||||
|
||||
// Act
|
||||
let result = function(input);
|
||||
|
||||
// Assert
|
||||
assert!(result.is_ok());
|
||||
assert_eq!(result.unwrap(), "expected");
|
||||
}
|
||||
|
||||
#[test]
|
||||
#[should_panic(expected = "error message")]
|
||||
fn test_function_panics() {
|
||||
function("invalid");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_function_with_result() -> Result<(), Box<dyn std::error::Error>> {
|
||||
let result = function("test")?;
|
||||
assert_eq!(result, "expected");
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Contribution Guidelines
|
||||
|
||||
### Pull Request Process
|
||||
1. **Fork repository**: Create your own fork
|
||||
2. **Create feature branch**: `git checkout -b feature/new-feature`
|
||||
3. **Implement changes**: Follow coding guidelines
|
||||
4. **Add tests**: Include unit and integration tests
|
||||
5. **Update documentation**: Update relevant documentation
|
||||
6. **Submit PR**: Create pull request with clear description
|
||||
|
||||
### Commit Guidelines
|
||||
```
|
||||
type(scope): description
|
||||
|
||||
[optional body]
|
||||
|
||||
[optional footer]
|
||||
```
|
||||
|
||||
**Types**: feat, fix, docs, style, refactor, test, chore
|
||||
**Scope**: cli, daemon, lib, commands, etc.
|
||||
|
||||
**Examples**:
|
||||
```
|
||||
feat(commands): add new package management command
|
||||
|
||||
fix(daemon): resolve memory leak in transaction handling
|
||||
|
||||
docs(user-guide): update installation instructions
|
||||
|
||||
test(integration): add end-to-end package installation test
|
||||
```
|
||||
|
||||
### Review Process
|
||||
- **Code review**: All changes require review
|
||||
- **Testing**: Ensure all tests pass
|
||||
- **Documentation**: Verify documentation is updated
|
||||
- **Integration**: Test integration with existing features
|
||||
|
||||
### Issue Reporting
|
||||
When reporting issues, include:
|
||||
- **Environment**: OS, version, dependencies
|
||||
- **Steps to reproduce**: Clear reproduction steps
|
||||
- **Expected behavior**: What should happen
|
||||
- **Actual behavior**: What actually happens
|
||||
- **Logs**: Relevant error logs and output
|
||||
|
||||
## Release Process
|
||||
|
||||
### Pre-Release Checklist
|
||||
```bash
|
||||
# 1. Update version numbers
|
||||
# Update Cargo.toml, debian/changelog, etc.
|
||||
|
||||
# 2. Run full test suite
|
||||
cargo test --features development
|
||||
cargo test --test integration_tests
|
||||
|
||||
# 3. Run code quality checks
|
||||
cargo clippy --features development -- -D warnings
|
||||
cargo fmt -- --check
|
||||
cargo audit
|
||||
|
||||
# 4. Build all targets
|
||||
cargo build --release --features development
|
||||
cargo build --release --features dev-full
|
||||
|
||||
# 5. Test development commands
|
||||
cargo run --features development -- testutils --help
|
||||
cargo run --features development -- shlib-backend --help
|
||||
cargo run --features development -- internals --help
|
||||
|
||||
# 6. Build documentation
|
||||
cargo doc --features development --no-deps
|
||||
|
||||
# 7. Build Debian package
|
||||
./build-debian-trixie.sh
|
||||
```
|
||||
|
||||
### Release Steps
|
||||
```bash
|
||||
# 1. Create release branch
|
||||
git checkout -b release/v0.2.0
|
||||
|
||||
# 2. Update version numbers
|
||||
# ... update version files ...
|
||||
|
||||
# 3. Run final tests
|
||||
cargo test --features development
|
||||
cargo test --test integration_tests
|
||||
|
||||
# 4. Commit version changes
|
||||
git add .
|
||||
git commit -m "chore(release): bump version to 0.2.0"
|
||||
|
||||
# 5. Tag release
|
||||
git tag -a v0.2.0 -m "Release version 0.2.0"
|
||||
|
||||
# 6. Push release
|
||||
git push origin release/v0.2.0
|
||||
git push origin v0.2.0
|
||||
|
||||
# 7. Create GitHub release
|
||||
# ... create release on GitHub ...
|
||||
|
||||
# 8. Merge to main
|
||||
git checkout main
|
||||
git merge release/v0.2.0
|
||||
git push origin main
|
||||
```
|
||||
|
||||
### Post-Release Tasks
|
||||
```bash
|
||||
# 1. Update documentation
|
||||
# ... update version references ...
|
||||
|
||||
# 2. Announce release
|
||||
# ... announce on mailing lists, forums, etc. ...
|
||||
|
||||
# 3. Monitor for issues
|
||||
# ... watch for bug reports and issues ...
|
||||
|
||||
# 4. Plan next release
|
||||
# ... plan features for next version ...
|
||||
```
|
||||
|
||||
## Development Best Practices
|
||||
|
||||
### Code Organization
|
||||
- **Modular design**: Keep modules focused and cohesive
|
||||
- **Separation of concerns**: Separate logic from presentation
|
||||
- **Dependency management**: Minimize dependencies and avoid circular references
|
||||
- **Error handling**: Use consistent error types and handling patterns
|
||||
|
||||
### Performance Considerations
|
||||
- **Efficient algorithms**: Use appropriate algorithms and data structures
|
||||
- **Memory management**: Avoid unnecessary allocations and memory leaks
|
||||
- **Async operations**: Use async/await for I/O operations
|
||||
- **Caching**: Implement caching for expensive operations
|
||||
|
||||
### Security Considerations
|
||||
- **Input validation**: Validate all user inputs
|
||||
- **Authentication**: Implement proper authentication and authorization
|
||||
- **Resource limits**: Set appropriate limits for operations
|
||||
- **Audit logging**: Log security-relevant events
|
||||
|
||||
### Testing Strategy
|
||||
- **Unit tests**: Test individual functions and methods
|
||||
- **Integration tests**: Test component interactions
|
||||
- **End-to-end tests**: Test complete workflows
|
||||
- **Performance tests**: Test performance characteristics
|
||||
- **Security tests**: Test security aspects
|
||||
|
||||
### Documentation Strategy
|
||||
- **API documentation**: Document all public APIs
|
||||
- **User guides**: Provide comprehensive user documentation
|
||||
- **Developer guides**: Document development processes
|
||||
- **Examples**: Provide working examples for common use cases
|
||||
|
||||
---
|
||||
|
||||
*This guide covers the development workflow for apt-ostree. For user documentation, refer to the User Guide.*
|
||||
427
docs/user-guide.md
Normal file
427
docs/user-guide.md
Normal file
|
|
@ -0,0 +1,427 @@
|
|||
# apt-ostree User Guide
|
||||
|
||||
## System Requirements
|
||||
|
||||
### Supported Operating Systems
|
||||
- Debian 13+ (Trixie) or newer
|
||||
- Ubuntu 25.04+ (Noble Numbat) or newer
|
||||
|
||||
### Required System Components
|
||||
- OSTree 2025.2+
|
||||
- APT 3.0+
|
||||
- Systemd 255+
|
||||
- Polkit 123+
|
||||
|
||||
## Table of Contents
|
||||
1. [Installation](#installation)
|
||||
2. [Basic Setup](#basic-setup)
|
||||
3. [Basic Operations](#basic-operations)
|
||||
4. [Advanced Features](#advanced-features)
|
||||
5. [Troubleshooting](#troubleshooting)
|
||||
6. [Migration Guide](#migration-guide)
|
||||
|
||||
## Installation
|
||||
|
||||
### Prerequisites
|
||||
apt-ostree requires the following system components:
|
||||
- Debian 13+ or Ubuntu 24.04+
|
||||
- OSTree 2025.2+
|
||||
- APT 3.0+
|
||||
- systemd
|
||||
- Polkit
|
||||
- D-Bus
|
||||
|
||||
### Installing from Debian Package
|
||||
```bash
|
||||
# Download and install the package
|
||||
sudo dpkg -i apt-ostree_0.1.0-2_amd64.deb
|
||||
|
||||
# Install dependencies if needed
|
||||
sudo apt-get install -f
|
||||
```
|
||||
|
||||
### Installing from Source
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/robojerk/apt-ostree.git
|
||||
cd apt-ostree
|
||||
|
||||
# Install build dependencies
|
||||
sudo apt-get install build-essential cargo rustc pkg-config \
|
||||
libostree-dev libapt-pkg-dev libpolkit-gobject-1-dev \
|
||||
libdbus-1-dev libsystemd-dev
|
||||
|
||||
# Build and install
|
||||
cargo build --release
|
||||
sudo install -m 755 target/release/apt-ostree /usr/local/bin/
|
||||
sudo install -m 755 target/release/apt-ostreed /usr/local/libexec/
|
||||
```
|
||||
|
||||
## Basic Setup
|
||||
|
||||
### Initial Configuration
|
||||
1. **Create configuration directory:**
|
||||
```bash
|
||||
sudo mkdir -p /etc/apt-ostree
|
||||
```
|
||||
|
||||
2. **Create configuration file:**
|
||||
```bash
|
||||
sudo tee /etc/apt-ostree/config.toml > /dev/null <<EOF
|
||||
[system]
|
||||
data_dir = "/var/lib/apt-ostree"
|
||||
log_level = "info"
|
||||
max_deployments = 3
|
||||
|
||||
[ostree]
|
||||
repo_path = "/ostree/repo"
|
||||
deploy_path = "/ostree/deploy"
|
||||
default_branch = "debian/13/amd64"
|
||||
|
||||
[apt]
|
||||
sources_list = "/etc/apt/sources.list"
|
||||
cache_dir = "/var/cache/apt"
|
||||
|
||||
[security]
|
||||
polkit_enabled = true
|
||||
require_auth = true
|
||||
|
||||
[daemon]
|
||||
user = "root"
|
||||
group = "root"
|
||||
log_file = "/var/log/apt-ostreed.log"
|
||||
EOF
|
||||
```
|
||||
|
||||
3. **Create required directories:**
|
||||
```bash
|
||||
sudo mkdir -p /var/lib/apt-ostree
|
||||
sudo mkdir -p /var/log
|
||||
sudo mkdir -p /var/cache/apt-ostree
|
||||
```
|
||||
|
||||
4. **Set up systemd service:**
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable apt-ostreed
|
||||
sudo systemctl start apt-ostreed
|
||||
```
|
||||
|
||||
### OSTree Repository Setup
|
||||
1. **Initialize OSTree repository:**
|
||||
```bash
|
||||
sudo mkdir -p /ostree/repo
|
||||
sudo ostree init --repo=/ostree/repo --mode=bare
|
||||
```
|
||||
|
||||
2. **Create initial deployment:**
|
||||
```bash
|
||||
sudo apt-ostree deploy debian/13/amd64
|
||||
```
|
||||
|
||||
## Basic Operations
|
||||
|
||||
### Package Management
|
||||
|
||||
#### Installing Packages
|
||||
```bash
|
||||
# Install a single package
|
||||
sudo apt-ostree install nginx
|
||||
|
||||
# Install multiple packages
|
||||
sudo apt-ostree install nginx curl wget
|
||||
|
||||
# Install with specific version
|
||||
sudo apt-ostree install nginx=1.18.0-6
|
||||
```
|
||||
|
||||
#### Removing Packages
|
||||
```bash
|
||||
# Remove a package
|
||||
sudo apt-ostree remove apache2
|
||||
|
||||
# Remove multiple packages
|
||||
sudo apt-ostree remove apache2 mysql-server
|
||||
```
|
||||
|
||||
#### Upgrading Packages
|
||||
```bash
|
||||
# Upgrade all packages
|
||||
sudo apt-ostree upgrade
|
||||
|
||||
# Check for available upgrades
|
||||
sudo apt-ostree status
|
||||
```
|
||||
|
||||
#### Searching Packages
|
||||
```bash
|
||||
# Search for packages
|
||||
sudo apt-ostree search nginx
|
||||
|
||||
# Search with wildcards
|
||||
sudo apt-ostree search "nginx*"
|
||||
```
|
||||
|
||||
### System Management
|
||||
|
||||
#### Deployment Operations
|
||||
```bash
|
||||
# Show current status
|
||||
sudo apt-ostree status
|
||||
|
||||
# List deployments
|
||||
sudo apt-ostree log
|
||||
|
||||
# Rollback to previous deployment
|
||||
sudo apt-ostree rollback
|
||||
|
||||
# Clean up old deployments
|
||||
sudo apt-ostree cleanup
|
||||
```
|
||||
|
||||
#### Kernel Management
|
||||
```bash
|
||||
# View current kernel arguments
|
||||
sudo apt-ostree kargs
|
||||
|
||||
# Add kernel argument
|
||||
sudo apt-ostree kargs --append "console=ttyS0"
|
||||
|
||||
# Remove kernel argument
|
||||
sudo apt-ostree kargs --delete "console=ttyS0"
|
||||
|
||||
# Replace kernel argument
|
||||
sudo apt-ostree kargs --replace "console=tty0" "console=ttyS0"
|
||||
```
|
||||
|
||||
#### Initramfs Management
|
||||
```bash
|
||||
# Regenerate initramfs
|
||||
sudo apt-ostree initramfs --enable
|
||||
|
||||
# Disable initramfs regeneration
|
||||
sudo apt-ostree initramfs --disable
|
||||
```
|
||||
|
||||
### Transaction Management
|
||||
```bash
|
||||
# Start a transaction
|
||||
sudo apt-ostree transaction start
|
||||
|
||||
# Check transaction status
|
||||
sudo apt-ostree transaction status
|
||||
|
||||
# Commit transaction
|
||||
sudo apt-ostree transaction commit
|
||||
|
||||
# Rollback transaction
|
||||
sudo apt-ostree transaction rollback
|
||||
```
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Development Commands
|
||||
Development commands are hidden from normal help output but provide useful debugging tools:
|
||||
|
||||
```bash
|
||||
# Run system diagnostics
|
||||
sudo apt-ostree internals diagnostics
|
||||
|
||||
# Validate system state
|
||||
sudo apt-ostree internals validate-state
|
||||
|
||||
# Dump debug information
|
||||
sudo apt-ostree internals debug-dump
|
||||
|
||||
# Execute script in container
|
||||
sudo apt-ostree testutils script-shell /tmp/test.sh --read-only
|
||||
|
||||
# Get system architecture
|
||||
sudo apt-ostree shlib-backend get-basearch
|
||||
```
|
||||
|
||||
### Remote Management
|
||||
```bash
|
||||
# Add remote repository
|
||||
sudo apt-ostree remote add production https://ostree.example.com/repo
|
||||
|
||||
# List remotes
|
||||
sudo apt-ostree remote list
|
||||
|
||||
# Remove remote
|
||||
sudo apt-ostree remote delete production
|
||||
```
|
||||
|
||||
### Branch Management
|
||||
```bash
|
||||
# List available references
|
||||
sudo apt-ostree refs
|
||||
|
||||
# Switch to different branch
|
||||
sudo apt-ostree rebase https://ostree.example.com/repo stable/13/amd64
|
||||
|
||||
# Create new branch
|
||||
sudo apt-ostree refs --create new-branch
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Daemon Not Running
|
||||
```bash
|
||||
# Check service status
|
||||
sudo systemctl status apt-ostreed
|
||||
|
||||
# Start the service
|
||||
sudo systemctl start apt-ostreed
|
||||
|
||||
# Check logs
|
||||
sudo journalctl -u apt-ostreed -f
|
||||
```
|
||||
|
||||
#### Permission Denied
|
||||
```bash
|
||||
# Check Polkit policies
|
||||
sudo polkit-policy-file-validate /usr/share/polkit-1/actions/org.projectatomic.aptostree1.policy
|
||||
|
||||
# Verify user permissions
|
||||
groups $USER
|
||||
```
|
||||
|
||||
#### OSTree Repository Issues
|
||||
```bash
|
||||
# Check repository status
|
||||
sudo ostree show --repo=/ostree/repo
|
||||
|
||||
# Verify repository integrity
|
||||
sudo ostree fsck --repo=/ostree/repo
|
||||
```
|
||||
|
||||
#### Package Installation Failures
|
||||
```bash
|
||||
# Check APT sources
|
||||
sudo apt-ostree internals diagnostics
|
||||
|
||||
# Verify package availability
|
||||
sudo apt-ostree search <package-name>
|
||||
|
||||
# Check for dependency conflicts
|
||||
sudo apt-ostree info <package-name>
|
||||
```
|
||||
|
||||
### Debug Mode
|
||||
Enable debug logging for troubleshooting:
|
||||
|
||||
```bash
|
||||
# Set debug log level
|
||||
export APT_OSTREE_LOG_LEVEL=debug
|
||||
|
||||
# Run command with verbose output
|
||||
sudo apt-ostree --verbose install nginx
|
||||
```
|
||||
|
||||
### Log Files
|
||||
- **Daemon logs**: `/var/log/apt-ostreed.log`
|
||||
- **System logs**: `sudo journalctl -u apt-ostreed`
|
||||
- **OSTree logs**: `sudo ostree log --repo=/ostree/repo`
|
||||
|
||||
## Migration Guide
|
||||
|
||||
### From Traditional APT
|
||||
1. **Backup current system:**
|
||||
```bash
|
||||
sudo apt-mark showmanual > installed-packages.txt
|
||||
sudo dpkg --get-selections > package-selections.txt
|
||||
```
|
||||
|
||||
2. **Install apt-ostree:**
|
||||
```bash
|
||||
sudo dpkg -i apt-ostree_0.1.0-2_amd64.deb
|
||||
```
|
||||
|
||||
3. **Initialize OSTree repository:**
|
||||
```bash
|
||||
sudo apt-ostree deploy debian/13/amd64
|
||||
```
|
||||
|
||||
4. **Install essential packages:**
|
||||
```bash
|
||||
sudo apt-ostree install $(cat installed-packages.txt)
|
||||
```
|
||||
|
||||
### From rpm-ostree
|
||||
1. **Export package list:**
|
||||
```bash
|
||||
rpm -qa > installed-packages.txt
|
||||
```
|
||||
|
||||
2. **Convert package names (if needed):**
|
||||
```bash
|
||||
# Some package names may differ between RPM and DEB
|
||||
sed 's/^python3-/python3-/g' installed-packages.txt > deb-packages.txt
|
||||
```
|
||||
|
||||
3. **Install with apt-ostree:**
|
||||
```bash
|
||||
sudo apt-ostree install $(cat deb-packages.txt)
|
||||
```
|
||||
|
||||
### Post-Migration
|
||||
1. **Verify system functionality:**
|
||||
```bash
|
||||
sudo apt-ostree internals diagnostics
|
||||
sudo apt-ostree status
|
||||
```
|
||||
|
||||
2. **Test package operations:**
|
||||
```bash
|
||||
sudo apt-ostree search test-package
|
||||
sudo apt-ostree install test-package
|
||||
sudo apt-ostree remove test-package
|
||||
```
|
||||
|
||||
3. **Configure automatic updates:**
|
||||
```bash
|
||||
# Set up cron job for regular upgrades
|
||||
echo "0 2 * * * /usr/bin/apt-ostree upgrade" | sudo crontab -
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### System Administration
|
||||
- **Regular maintenance**: Run `apt-ostree cleanup` periodically
|
||||
- **Backup deployments**: Keep at least 2-3 deployments for rollback
|
||||
- **Monitor logs**: Check daemon logs for errors or warnings
|
||||
- **Test updates**: Test package updates in development environment first
|
||||
|
||||
### Security
|
||||
- **Limit access**: Only authorized users should have access to apt-ostree
|
||||
- **Audit policies**: Regularly review Polkit policies
|
||||
- **Monitor changes**: Log all system changes for audit purposes
|
||||
- **Update regularly**: Keep apt-ostree and system packages updated
|
||||
|
||||
### Performance
|
||||
- **Optimize storage**: Use appropriate filesystem for OSTree repository
|
||||
- **Network optimization**: Use local mirrors for package repositories
|
||||
- **Cache management**: Monitor and clean APT cache regularly
|
||||
- **Resource limits**: Set appropriate limits for daemon processes
|
||||
|
||||
## Support and Resources
|
||||
|
||||
### Documentation
|
||||
- **Manual pages**: `man apt-ostree`, `man apt-ostree-dev`, `man apt-ostree.conf`
|
||||
- **Help system**: `apt-ostree --help`, `apt-ostree <command> --help`
|
||||
- **Online documentation**: Project wiki and documentation
|
||||
|
||||
### Community
|
||||
- **Issue tracker**: GitHub Issues for bug reports
|
||||
- **Discussions**: GitHub Discussions for questions and ideas
|
||||
- **Contributing**: Pull requests and contributions welcome
|
||||
|
||||
### Professional Support
|
||||
For enterprise deployments and professional support, contact the project maintainers.
|
||||
|
||||
---
|
||||
|
||||
*This guide covers the basic usage of apt-ostree. For advanced features and development, refer to the developer documentation and source code.*
|
||||
Loading…
Add table
Add a link
Reference in a new issue