Initial commit: Comprehensive Debian bootc documentation
- Complete documentation for all bootc commands and subcommands - Debian-specific adaptations and workarounds - Manual installation methods to bypass bootc reliability issues - Technical guides with Rust source code analysis - Flowcharts and external command references - Hidden command documentation (bootc internals, state, etc.) - Composefs integration analysis - Base image creation guides (with and without bootc binary) - Management scripts and automation - Comprehensive troubleshooting and examples
This commit is contained in:
robojerk
commit
526f1c1afd
67 changed files with 34174 additions and 0 deletions
733
internals/bootc-internals-architecture.md
Normal file
733
internals/bootc-internals-architecture.md
Normal file
|
|
@ -0,0 +1,733 @@
|
|||
# bootc internals - Architecture and Implementation
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a deep dive into the architecture and implementation details of the `bootc internals` system, covering the Rust code structure, design patterns, and integration points.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
The bootc internals system is built on a modular architecture that provides internal-only operations for system maintenance, debugging, and integration. The system is designed to be:
|
||||
|
||||
- **Hidden**: Commands are not visible in regular help output
|
||||
- **Internal**: Intended for system administrators and developers
|
||||
- **Modular**: Each command is self-contained with clear responsibilities
|
||||
- **Integrated**: Seamlessly integrates with existing bootc infrastructure
|
||||
|
||||
## Core Components
|
||||
|
||||
### 1. Command Structure
|
||||
|
||||
The internals system is built around the `InternalsOpts` enum, which defines all available internal commands:
|
||||
|
||||
```rust
|
||||
#[derive(Debug, clap::Subcommand, PartialEq, Eq)]
|
||||
pub(crate) enum InternalsOpts {
|
||||
SystemdGenerator {
|
||||
normal_dir: Utf8PathBuf,
|
||||
early_dir: Option<Utf8PathBuf>,
|
||||
late_dir: Option<Utf8PathBuf>,
|
||||
},
|
||||
FixupEtcFstab,
|
||||
PrintJsonSchema {
|
||||
#[clap(long)]
|
||||
of: SchemaType,
|
||||
},
|
||||
#[clap(subcommand)]
|
||||
Fsverity(FsverityOpts),
|
||||
Fsck,
|
||||
Cleanup,
|
||||
Relabel {
|
||||
#[clap(long)]
|
||||
as_path: Option<Utf8PathBuf>,
|
||||
path: Utf8PathBuf,
|
||||
},
|
||||
OstreeExt { args: Vec<OsString> },
|
||||
Cfs { args: Vec<OsString> },
|
||||
OstreeContainer { args: Vec<OsString> },
|
||||
TestComposefs,
|
||||
LoopbackCleanupHelper { device: String },
|
||||
AllocateCleanupLoopback { file_path: Utf8PathBuf },
|
||||
BootcInstallCompletion { sysroot: Utf8PathBuf, stateroot: String },
|
||||
Reboot,
|
||||
#[cfg(feature = "rhsm")]
|
||||
PublishRhsmFacts,
|
||||
#[cfg(feature = "docgen")]
|
||||
DumpCliJson,
|
||||
DirDiff {
|
||||
pristine_etc: Utf8PathBuf,
|
||||
current_etc: Utf8PathBuf,
|
||||
new_etc: Utf8PathBuf,
|
||||
perform_merge: bool,
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Command Routing
|
||||
|
||||
Commands are routed through the main CLI dispatcher in `cli.rs`:
|
||||
|
||||
```rust
|
||||
match opt {
|
||||
Opt::Internals(opts) => match opts {
|
||||
InternalsOpts::SystemdGenerator { normal_dir, early_dir, late_dir } => {
|
||||
let unit_dir = &Dir::open_ambient_dir(normal_dir, cap_std::ambient_authority())?;
|
||||
crate::generator::generator(root, unit_dir)
|
||||
}
|
||||
InternalsOpts::Fsck => {
|
||||
let sysroot = &get_storage().await?;
|
||||
crate::fsck::fsck(&sysroot, std::io::stdout().lock()).await?;
|
||||
Ok(())
|
||||
}
|
||||
// ... other commands
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Module Architecture
|
||||
|
||||
### 1. Generator Module (`generator.rs`)
|
||||
|
||||
**Purpose**: Systemd integration and unit generation
|
||||
|
||||
**Key Functions**:
|
||||
- `fstab_generator_impl()` - Generate fstab editor service
|
||||
- `generate_fstab_editor()` - Create systemd unit file
|
||||
- `generator()` - Main generator entry point
|
||||
|
||||
**Implementation**:
|
||||
```rust
|
||||
pub(crate) fn fstab_generator_impl(root: &Dir, unit_dir: &Dir) -> Result<bool> {
|
||||
// Check if system is ostree-booted
|
||||
if !is_ostree_booted_in(root)? {
|
||||
return Ok(false);
|
||||
}
|
||||
|
||||
// Check /etc/fstab for anaconda stamp
|
||||
if let Some(fd) = root.open_optional("etc/fstab")? {
|
||||
let mut from_anaconda = false;
|
||||
for line in fd.lines() {
|
||||
let line = line?;
|
||||
if line.contains(BOOTC_EDITED_STAMP) {
|
||||
return Ok(false); // Already processed
|
||||
}
|
||||
if line.contains(FSTAB_ANACONDA_STAMP) {
|
||||
from_anaconda = true;
|
||||
}
|
||||
}
|
||||
|
||||
if from_anaconda {
|
||||
generate_fstab_editor(unit_dir)?;
|
||||
return Ok(true);
|
||||
}
|
||||
}
|
||||
Ok(false)
|
||||
}
|
||||
```
|
||||
|
||||
**Dependencies**:
|
||||
- `ostree_ext::container_utils::is_ostree_booted_in`
|
||||
- `cap_std::fs::Dir`
|
||||
- `rustix::fs::StatVfsMountFlags`
|
||||
|
||||
### 2. Filesystem Check Module (`fsck.rs`)
|
||||
|
||||
**Purpose**: System consistency checking
|
||||
|
||||
**Key Functions**:
|
||||
- `fsck()` - Main consistency check entry point
|
||||
- `fsck_ok()` - Return success result
|
||||
- `fsck_err()` - Return error result
|
||||
|
||||
**Implementation**:
|
||||
```rust
|
||||
pub async fn fsck(sysroot: &Storage, mut out: impl Write) -> Result<()> {
|
||||
let ostree = sysroot.get_ostree()?;
|
||||
let repo = ostree.repo();
|
||||
|
||||
// Run all registered fsck checks
|
||||
for check in FSCK_CHECKS {
|
||||
match check(sysroot).await {
|
||||
Ok(Ok(())) => writeln!(out, "✓ {}", check.name())?,
|
||||
Ok(Err(e)) => writeln!(out, "✗ {}: {}", check.name(), e)?,
|
||||
Err(e) => writeln!(out, "✗ {}: {}", check.name(), e)?,
|
||||
}
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
**Dependencies**:
|
||||
- `linkme::distributed_slice` - For check registration
|
||||
- `ostree_ext::composefs` - For composefs operations
|
||||
- `ostree_ext::ostree` - For OSTree operations
|
||||
|
||||
### 3. Composefs Control Module (`cfsctl.rs`)
|
||||
|
||||
**Purpose**: Composefs repository management
|
||||
|
||||
**Key Functions**:
|
||||
- `run_from_iter()` - Parse and execute cfsctl commands
|
||||
- `App::parse()` - Parse command line arguments
|
||||
- `Command` enum - Define available commands
|
||||
|
||||
**Implementation**:
|
||||
```rust
|
||||
pub async fn run_from_iter<I>(args: I) -> Result<()>
|
||||
where
|
||||
I: IntoIterator<Item = impl AsRef<OsStr>>,
|
||||
{
|
||||
let app = App::parse_from(args);
|
||||
let repo = if app.user {
|
||||
Repository::open_user()?
|
||||
} else if app.system {
|
||||
Repository::open_system()?
|
||||
} else if let Some(repo_path) = app.repo {
|
||||
Repository::open(repo_path)?
|
||||
} else {
|
||||
Repository::open_default()?
|
||||
};
|
||||
|
||||
match app.cmd {
|
||||
Command::Oci(oci_cmd) => match oci_cmd {
|
||||
OciCommand::ImportLayer { sha256, name } => {
|
||||
// Import layer implementation
|
||||
}
|
||||
OciCommand::LsLayer { name } => {
|
||||
// List layer implementation
|
||||
}
|
||||
// ... other OCI commands
|
||||
}
|
||||
Command::CreateFs { name, output } => {
|
||||
// Create filesystem implementation
|
||||
}
|
||||
Command::WriteBoot { name, output } => {
|
||||
// Write boot entries implementation
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Dependencies**:
|
||||
- `composefs::repository::Repository`
|
||||
- `composefs::fsverity::FsVerityHashValue`
|
||||
- `composefs_boot::write_boot`
|
||||
|
||||
### 4. Deploy Module (`deploy.rs`)
|
||||
|
||||
**Purpose**: Deployment operations and cleanup
|
||||
|
||||
**Key Functions**:
|
||||
- `fixup_etc_fstab()` - Fix /etc/fstab for composefs
|
||||
- `cleanup()` - Perform system cleanup
|
||||
- `switch_origin_inplace()` - In-place origin switching
|
||||
|
||||
**Implementation**:
|
||||
```rust
|
||||
pub(crate) fn fixup_etc_fstab(root: &Dir) -> Result<()> {
|
||||
let fstab_path = root.open("etc/fstab")?;
|
||||
let mut fstab_content = String::new();
|
||||
fstab_path.read_to_string(&mut fstab_content)?;
|
||||
|
||||
let mut lines = fstab_content.lines().collect::<Vec<_>>();
|
||||
let mut modified = false;
|
||||
|
||||
for line in lines.iter_mut() {
|
||||
if line.contains("ro") && !line.contains("ro,") {
|
||||
*line = line.replace("ro", "ro,");
|
||||
modified = true;
|
||||
}
|
||||
}
|
||||
|
||||
if modified {
|
||||
let mut fstab_file = root.create("etc/fstab")?;
|
||||
for line in lines {
|
||||
writeln!(fstab_file, "{}", line)?;
|
||||
}
|
||||
writeln!(fstab_file, "# {}", BOOTC_EDITED_STAMP)?;
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
**Dependencies**:
|
||||
- `cap_std::fs::Dir`
|
||||
- `std::io::Write`
|
||||
- `ostree_ext::ostree`
|
||||
|
||||
### 5. Block Device Module (`blockdev.rs`)
|
||||
|
||||
**Purpose**: Loopback device management
|
||||
|
||||
**Key Functions**:
|
||||
- `LoopbackDevice::new()` - Create loopback device
|
||||
- `run_loopback_cleanup_helper()` - Cleanup helper
|
||||
- `run_allocate_cleanup_loopback()` - Test allocation
|
||||
|
||||
**Implementation**:
|
||||
```rust
|
||||
pub struct LoopbackDevice {
|
||||
device: String,
|
||||
file: PathBuf,
|
||||
}
|
||||
|
||||
impl LoopbackDevice {
|
||||
pub fn new(file_path: &Path) -> Result<Self> {
|
||||
let output = Command::new("losetup")
|
||||
.args(["-f", "--show", file_path.to_str().unwrap()])
|
||||
.output()?;
|
||||
|
||||
if !output.status.success() {
|
||||
return Err(anyhow::anyhow!("Failed to create loopback device"));
|
||||
}
|
||||
|
||||
let device = String::from_utf8(output.stdout)?;
|
||||
let device = device.trim().to_string();
|
||||
|
||||
Ok(Self {
|
||||
device,
|
||||
file: file_path.to_path_buf(),
|
||||
})
|
||||
}
|
||||
|
||||
pub fn path(&self) -> &str {
|
||||
&self.device
|
||||
}
|
||||
}
|
||||
|
||||
impl Drop for LoopbackDevice {
|
||||
fn drop(&mut self) {
|
||||
let _ = Command::new("losetup")
|
||||
.args(["-d", &self.device])
|
||||
.output();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Dependencies**:
|
||||
- `std::process::Command`
|
||||
- `std::path::Path`
|
||||
- `anyhow::Result`
|
||||
|
||||
## Design Patterns
|
||||
|
||||
### 1. Command Pattern
|
||||
|
||||
Each internals command follows the command pattern, encapsulating a request as an object:
|
||||
|
||||
```rust
|
||||
trait InternalCommand {
|
||||
fn execute(&self) -> Result<()>;
|
||||
}
|
||||
|
||||
impl InternalCommand for SystemdGenerator {
|
||||
fn execute(&self) -> Result<()> {
|
||||
let unit_dir = &Dir::open_ambient_dir(&self.normal_dir, cap_std::ambient_authority())?;
|
||||
crate::generator::generator(&self.root, unit_dir)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Strategy Pattern
|
||||
|
||||
Different commands use different strategies for execution:
|
||||
|
||||
```rust
|
||||
enum ExecutionStrategy {
|
||||
Direct(DirectCommand),
|
||||
Proxy(ProxyCommand),
|
||||
Generator(GeneratorCommand),
|
||||
Test(TestCommand),
|
||||
}
|
||||
|
||||
impl ExecutionStrategy {
|
||||
fn execute(&self) -> Result<()> {
|
||||
match self {
|
||||
ExecutionStrategy::Direct(cmd) => cmd.execute_direct(),
|
||||
ExecutionStrategy::Proxy(cmd) => cmd.execute_proxy(),
|
||||
ExecutionStrategy::Generator(cmd) => cmd.execute_generator(),
|
||||
ExecutionStrategy::Test(cmd) => cmd.execute_test(),
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Factory Pattern
|
||||
|
||||
Commands are created using a factory pattern:
|
||||
|
||||
```rust
|
||||
struct CommandFactory;
|
||||
|
||||
impl CommandFactory {
|
||||
fn create_command(opts: &InternalsOpts) -> Box<dyn InternalCommand> {
|
||||
match opts {
|
||||
InternalsOpts::SystemdGenerator { .. } => {
|
||||
Box::new(SystemdGenerator::new(opts))
|
||||
}
|
||||
InternalsOpts::Fsck => {
|
||||
Box::new(FsckCommand::new())
|
||||
}
|
||||
// ... other commands
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### 1. Error Types
|
||||
|
||||
The system uses a hierarchical error structure:
|
||||
|
||||
```rust
|
||||
#[derive(thiserror::Error, Debug)]
|
||||
pub enum InternalError {
|
||||
#[error("System error: {0}")]
|
||||
System(String),
|
||||
|
||||
#[error("Permission error: {0}")]
|
||||
Permission(String),
|
||||
|
||||
#[error("Resource error: {0}")]
|
||||
Resource(String),
|
||||
|
||||
#[error("Configuration error: {0}")]
|
||||
Configuration(String),
|
||||
}
|
||||
|
||||
impl From<std::io::Error> for InternalError {
|
||||
fn from(err: std::io::Error) -> Self {
|
||||
InternalError::System(err.to_string())
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Error Context
|
||||
|
||||
All operations use error context for better debugging:
|
||||
|
||||
```rust
|
||||
#[context("Systemd generator")]
|
||||
pub(crate) fn generator(root: &Dir, unit_dir: &Dir) -> Result<()> {
|
||||
// Implementation with automatic error context
|
||||
}
|
||||
|
||||
#[context("Filesystem check")]
|
||||
pub async fn fsck(sysroot: &Storage, out: impl Write) -> Result<()> {
|
||||
// Implementation with automatic error context
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Error Recovery
|
||||
|
||||
The system implements error recovery strategies:
|
||||
|
||||
```rust
|
||||
pub async fn execute_with_retry<F, T>(mut operation: F, max_retries: usize) -> Result<T>
|
||||
where
|
||||
F: FnMut() -> Result<T>,
|
||||
{
|
||||
let mut last_error = None;
|
||||
|
||||
for attempt in 0..max_retries {
|
||||
match operation() {
|
||||
Ok(result) => return Ok(result),
|
||||
Err(e) => {
|
||||
last_error = Some(e);
|
||||
if attempt < max_retries - 1 {
|
||||
tokio::time::sleep(Duration::from_millis(100 * (attempt + 1) as u64)).await;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Err(last_error.unwrap())
|
||||
}
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### 1. Privilege Escalation
|
||||
|
||||
All internals commands require root privileges:
|
||||
|
||||
```rust
|
||||
pub(crate) fn require_root(is_container: bool) -> Result<()> {
|
||||
ensure!(
|
||||
rustix::process::getuid().is_root(),
|
||||
if is_container {
|
||||
"The user inside the container from which you are running this command must be root"
|
||||
} else {
|
||||
"This command must be executed as the root user"
|
||||
}
|
||||
);
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Input Validation
|
||||
|
||||
All inputs are validated before processing:
|
||||
|
||||
```rust
|
||||
pub(crate) fn validate_path(path: &Path) -> Result<()> {
|
||||
// Check for path traversal
|
||||
if path.components().any(|c| c == Component::ParentDir) {
|
||||
return Err(anyhow::anyhow!("Path traversal detected"));
|
||||
}
|
||||
|
||||
// Check for absolute paths
|
||||
if !path.is_absolute() {
|
||||
return Err(anyhow::anyhow!("Path must be absolute"));
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Resource Limits
|
||||
|
||||
Operations are limited to prevent resource exhaustion:
|
||||
|
||||
```rust
|
||||
pub(crate) fn with_resource_limits<F, T>(operation: F) -> Result<T>
|
||||
where
|
||||
F: FnOnce() -> Result<T>,
|
||||
{
|
||||
// Set memory limit
|
||||
let memory_limit = 1024 * 1024 * 1024; // 1GB
|
||||
let mut limits = rlimit::ResourceLimits::default();
|
||||
limits.set_memory_limit(memory_limit)?;
|
||||
limits.apply()?;
|
||||
|
||||
// Execute operation
|
||||
operation()
|
||||
}
|
||||
```
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### 1. Async Operations
|
||||
|
||||
All I/O operations are asynchronous:
|
||||
|
||||
```rust
|
||||
pub async fn cleanup_async(sysroot: &Storage) -> Result<()> {
|
||||
let ostree = sysroot.get_ostree()?;
|
||||
let repo = ostree.repo();
|
||||
|
||||
// Async repository operations
|
||||
let deployments = repo.list_deployments().await?;
|
||||
let unused_deployments = find_unused_deployments(deployments).await?;
|
||||
|
||||
for deployment in unused_deployments {
|
||||
repo.remove_deployment(deployment).await?;
|
||||
}
|
||||
|
||||
// Async garbage collection
|
||||
repo.garbage_collect().await?;
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Parallel Processing
|
||||
|
||||
Operations that can be parallelized are:
|
||||
|
||||
```rust
|
||||
pub async fn parallel_checks(sysroot: &Storage) -> Result<()> {
|
||||
let checks = vec![
|
||||
check_ostree_repo(sysroot),
|
||||
check_composefs_repo(sysroot),
|
||||
check_deployments(sysroot),
|
||||
check_configuration(sysroot),
|
||||
];
|
||||
|
||||
let results = futures::future::join_all(checks).await;
|
||||
|
||||
for result in results {
|
||||
result?;
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Caching
|
||||
|
||||
Frequently accessed data is cached:
|
||||
|
||||
```rust
|
||||
pub struct Cache {
|
||||
deployments: Option<Vec<Deployment>>,
|
||||
images: Option<Vec<Image>>,
|
||||
last_update: Option<Instant>,
|
||||
}
|
||||
|
||||
impl Cache {
|
||||
pub async fn get_deployments(&mut self, sysroot: &Storage) -> Result<&Vec<Deployment>> {
|
||||
if self.deployments.is_none() || self.should_refresh() {
|
||||
self.deployments = Some(sysroot.get_deployments().await?);
|
||||
self.last_update = Some(Instant::now());
|
||||
}
|
||||
|
||||
Ok(self.deployments.as_ref().unwrap())
|
||||
}
|
||||
|
||||
fn should_refresh(&self) -> bool {
|
||||
self.last_update
|
||||
.map(|last| last.elapsed() > Duration::from_secs(60))
|
||||
.unwrap_or(true)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### 1. Unit Tests
|
||||
|
||||
Each module has comprehensive unit tests:
|
||||
|
||||
```rust
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_systemd_generator() {
|
||||
let temp_dir = tempfile::tempdir().unwrap();
|
||||
let unit_dir = Dir::open_ambient_dir(temp_dir.path(), cap_std::ambient_authority()).unwrap();
|
||||
|
||||
// Test generator functionality
|
||||
let result = fstab_generator_impl(&root, &unit_dir);
|
||||
assert!(result.is_ok());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_fsck_operations() {
|
||||
let temp_sysroot = create_test_sysroot().unwrap();
|
||||
|
||||
// Test fsck functionality
|
||||
let result = fsck(&temp_sysroot, Vec::new()).await;
|
||||
assert!(result.is_ok());
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Integration Tests
|
||||
|
||||
End-to-end integration tests:
|
||||
|
||||
```rust
|
||||
#[tokio::test]
|
||||
async fn test_internals_integration() {
|
||||
// Setup test environment
|
||||
let test_env = TestEnvironment::new().await.unwrap();
|
||||
|
||||
// Test systemd generator
|
||||
let result = test_env.run_internals_command("systemd-generator", &["/tmp"]).await;
|
||||
assert!(result.is_ok());
|
||||
|
||||
// Test fsck
|
||||
let result = test_env.run_internals_command("fsck", &[]).await;
|
||||
assert!(result.is_ok());
|
||||
|
||||
// Test cleanup
|
||||
let result = test_env.run_internals_command("cleanup", &[]).await;
|
||||
assert!(result.is_ok());
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Performance Tests
|
||||
|
||||
Performance benchmarks:
|
||||
|
||||
```rust
|
||||
#[bench]
|
||||
fn bench_fsck_operations(b: &mut Bencher) {
|
||||
let sysroot = create_test_sysroot().unwrap();
|
||||
|
||||
b.iter(|| {
|
||||
let rt = tokio::runtime::Runtime::new().unwrap();
|
||||
rt.block_on(fsck(&sysroot, Vec::new()))
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### 1. Plugin System
|
||||
|
||||
A plugin system for extending internals functionality:
|
||||
|
||||
```rust
|
||||
pub trait InternalPlugin {
|
||||
fn name(&self) -> &str;
|
||||
fn execute(&self, args: &[String]) -> Result<()>;
|
||||
fn help(&self) -> &str;
|
||||
}
|
||||
|
||||
pub struct PluginManager {
|
||||
plugins: Vec<Box<dyn InternalPlugin>>,
|
||||
}
|
||||
|
||||
impl PluginManager {
|
||||
pub fn register_plugin(&mut self, plugin: Box<dyn InternalPlugin>) {
|
||||
self.plugins.push(plugin);
|
||||
}
|
||||
|
||||
pub fn execute_plugin(&self, name: &str, args: &[String]) -> Result<()> {
|
||||
let plugin = self.plugins.iter()
|
||||
.find(|p| p.name() == name)
|
||||
.ok_or_else(|| anyhow::anyhow!("Plugin not found: {}", name))?;
|
||||
|
||||
plugin.execute(args)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Configuration Management
|
||||
|
||||
Centralized configuration for internals commands:
|
||||
|
||||
```rust
|
||||
#[derive(Debug, Serialize, Deserialize)]
|
||||
pub struct InternalsConfig {
|
||||
pub fsck: FsckConfig,
|
||||
pub cleanup: CleanupConfig,
|
||||
pub generator: GeneratorConfig,
|
||||
}
|
||||
|
||||
#[derive(Debug, Serialize, Deserialize)]
|
||||
pub struct FsckConfig {
|
||||
pub enabled_checks: Vec<String>,
|
||||
pub timeout_seconds: u64,
|
||||
pub parallel_checks: bool,
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Monitoring Integration
|
||||
|
||||
Integration with monitoring systems:
|
||||
|
||||
```rust
|
||||
pub trait MetricsCollector {
|
||||
fn record_command_execution(&self, command: &str, duration: Duration, success: bool);
|
||||
fn record_error(&self, command: &str, error: &str);
|
||||
fn record_resource_usage(&self, command: &str, memory: u64, cpu: f64);
|
||||
}
|
||||
|
||||
pub struct PrometheusCollector {
|
||||
registry: Registry,
|
||||
}
|
||||
|
||||
impl MetricsCollector for PrometheusCollector {
|
||||
fn record_command_execution(&self, command: &str, duration: Duration, success: bool) {
|
||||
// Record metrics in Prometheus format
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This architecture document provides a comprehensive understanding of the bootc internals system's design, implementation, and future direction.
|
||||
727
internals/bootc-internals-examples-troubleshooting.md
Normal file
727
internals/bootc-internals-examples-troubleshooting.md
Normal file
|
|
@ -0,0 +1,727 @@
|
|||
# bootc internals - Examples and Troubleshooting
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides practical examples and troubleshooting guidance for the `bootc internals` system, covering common use cases, error scenarios, and debugging techniques.
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
### 1. System Maintenance
|
||||
|
||||
#### Daily Cleanup Operations
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Daily cleanup script for bootc systems
|
||||
|
||||
# Run filesystem consistency check
|
||||
echo "Running filesystem consistency check..."
|
||||
bootc internals fsck
|
||||
|
||||
# Perform cleanup operations
|
||||
echo "Performing cleanup operations..."
|
||||
bootc internals cleanup
|
||||
|
||||
# Check system status
|
||||
echo "Checking system status..."
|
||||
bootc status
|
||||
|
||||
# Log results
|
||||
echo "Maintenance completed at $(date)" >> /var/log/bootc-maintenance.log
|
||||
```
|
||||
|
||||
#### Weekly Deep Cleanup
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Weekly deep cleanup script
|
||||
|
||||
# Run comprehensive fsck
|
||||
echo "Running comprehensive filesystem check..."
|
||||
bootc internals fsck --verbose
|
||||
|
||||
# Clean up old deployments
|
||||
echo "Cleaning up old deployments..."
|
||||
bootc internals cleanup --aggressive
|
||||
|
||||
# Check for unused images
|
||||
echo "Checking for unused images..."
|
||||
bootc image list --unused
|
||||
|
||||
# Remove unused images
|
||||
echo "Removing unused images..."
|
||||
bootc image prune
|
||||
|
||||
# Log results
|
||||
echo "Deep cleanup completed at $(date)" >> /var/log/bootc-maintenance.log
|
||||
```
|
||||
|
||||
### 2. Development and Testing
|
||||
|
||||
#### Test Environment Setup
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Setup test environment for bootc development
|
||||
|
||||
# Create test directory
|
||||
mkdir -p /tmp/bootc-test
|
||||
cd /tmp/bootc-test
|
||||
|
||||
# Test composefs repository
|
||||
echo "Testing composefs repository..."
|
||||
bootc internals test-composefs
|
||||
|
||||
# Test loopback device allocation
|
||||
echo "Testing loopback device allocation..."
|
||||
bootc internals allocate-cleanup-loopback --file-path /tmp/test-image.img
|
||||
|
||||
# Test directory diff functionality
|
||||
echo "Testing directory diff..."
|
||||
bootc internals dir-diff \
|
||||
--pristine-etc /tmp/pristine-etc \
|
||||
--current-etc /tmp/current-etc \
|
||||
--new-etc /tmp/new-etc \
|
||||
--perform-merge
|
||||
|
||||
# Clean up test environment
|
||||
echo "Cleaning up test environment..."
|
||||
rm -rf /tmp/bootc-test
|
||||
```
|
||||
|
||||
#### Container Image Testing
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Test container image operations
|
||||
|
||||
# Test image pull
|
||||
echo "Testing image pull..."
|
||||
bootc internals ostree-ext container pull quay.io/myorg/test-image:latest
|
||||
|
||||
# Test image build
|
||||
echo "Testing image build..."
|
||||
bootc internals ostree-ext container build /path/to/containerfile
|
||||
|
||||
# Test image verification
|
||||
echo "Testing image verification..."
|
||||
bootc internals fsverity measure /path/to/image
|
||||
|
||||
# Test image deployment
|
||||
echo "Testing image deployment..."
|
||||
bootc internals ostree-ext container deploy quay.io/myorg/test-image:latest
|
||||
```
|
||||
|
||||
### 3. System Integration
|
||||
|
||||
#### Systemd Service Integration
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Setup systemd service for bootc internals
|
||||
|
||||
# Create service file
|
||||
cat > /etc/systemd/system/bootc-maintenance.service << EOF
|
||||
[Unit]
|
||||
Description=Bootc Maintenance Service
|
||||
After=multi-user.target
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
ExecStart=/usr/local/bin/bootc-maintenance.sh
|
||||
User=root
|
||||
Group=root
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
EOF
|
||||
|
||||
# Create timer file
|
||||
cat > /etc/systemd/system/bootc-maintenance.timer << EOF
|
||||
[Unit]
|
||||
Description=Bootc Maintenance Timer
|
||||
Requires=bootc-maintenance.service
|
||||
|
||||
[Timer]
|
||||
OnCalendar=daily
|
||||
Persistent=true
|
||||
|
||||
[Install]
|
||||
WantedBy=timers.target
|
||||
EOF
|
||||
|
||||
# Enable and start timer
|
||||
systemctl daemon-reload
|
||||
systemctl enable bootc-maintenance.timer
|
||||
systemctl start bootc-maintenance.timer
|
||||
|
||||
# Check timer status
|
||||
systemctl status bootc-maintenance.timer
|
||||
```
|
||||
|
||||
#### Monitoring Integration
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Setup monitoring for bootc internals
|
||||
|
||||
# Create monitoring script
|
||||
cat > /usr/local/bin/bootc-monitor.sh << 'EOF'
|
||||
#!/bin/bash
|
||||
|
||||
# Check system health
|
||||
HEALTH_STATUS=$(bootc internals fsck 2>&1 | grep -c "✗")
|
||||
if [ $HEALTH_STATUS -gt 0 ]; then
|
||||
echo "WARNING: Filesystem consistency issues detected"
|
||||
# Send alert to monitoring system
|
||||
curl -X POST "https://monitoring.example.com/alerts" \
|
||||
-d '{"service": "bootc", "status": "warning", "message": "Filesystem consistency issues"}'
|
||||
fi
|
||||
|
||||
# Check storage usage
|
||||
STORAGE_USAGE=$(df /var/lib/bootc | tail -1 | awk '{print $5}' | sed 's/%//')
|
||||
if [ $STORAGE_USAGE -gt 80 ]; then
|
||||
echo "WARNING: Storage usage is high: ${STORAGE_USAGE}%"
|
||||
# Run cleanup
|
||||
bootc internals cleanup
|
||||
fi
|
||||
|
||||
# Check deployment status
|
||||
DEPLOYMENT_STATUS=$(bootc status --format json | jq -r '.status.booted.state')
|
||||
if [ "$DEPLOYMENT_STATUS" != "active" ]; then
|
||||
echo "WARNING: Deployment status is not active: $DEPLOYMENT_STATUS"
|
||||
fi
|
||||
EOF
|
||||
|
||||
chmod +x /usr/local/bin/bootc-monitor.sh
|
||||
|
||||
# Add to crontab
|
||||
echo "*/5 * * * * /usr/local/bin/bootc-monitor.sh" | crontab -
|
||||
```
|
||||
|
||||
### 4. Debugging and Diagnostics
|
||||
|
||||
#### System Diagnostics
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Comprehensive system diagnostics
|
||||
|
||||
echo "=== Bootc System Diagnostics ==="
|
||||
echo "Date: $(date)"
|
||||
echo "Hostname: $(hostname)"
|
||||
echo "Uptime: $(uptime)"
|
||||
echo
|
||||
|
||||
echo "=== System Status ==="
|
||||
bootc status --format json | jq '.'
|
||||
echo
|
||||
|
||||
echo "=== Filesystem Check ==="
|
||||
bootc internals fsck
|
||||
echo
|
||||
|
||||
echo "=== Storage Usage ==="
|
||||
df -h /var/lib/bootc
|
||||
echo
|
||||
|
||||
echo "=== Memory Usage ==="
|
||||
free -h
|
||||
echo
|
||||
|
||||
echo "=== Process Information ==="
|
||||
ps aux | grep bootc
|
||||
echo
|
||||
|
||||
echo "=== Systemd Services ==="
|
||||
systemctl status bootc-* --no-pager
|
||||
echo
|
||||
|
||||
echo "=== Journal Logs ==="
|
||||
journalctl -u bootc-* --since "1 hour ago" --no-pager
|
||||
echo
|
||||
|
||||
echo "=== OSTree Status ==="
|
||||
ostree admin status
|
||||
echo
|
||||
|
||||
echo "=== Composefs Status ==="
|
||||
bootc internals cfs status
|
||||
echo
|
||||
|
||||
echo "=== Diagnostics Complete ==="
|
||||
```
|
||||
|
||||
#### Performance Analysis
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Performance analysis script
|
||||
|
||||
echo "=== Bootc Performance Analysis ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
echo "=== Command Execution Times ==="
|
||||
time bootc status
|
||||
time bootc internals fsck
|
||||
time bootc internals cleanup
|
||||
echo
|
||||
|
||||
echo "=== Resource Usage ==="
|
||||
echo "Memory usage:"
|
||||
ps aux | grep bootc | awk '{sum+=$6} END {print sum/1024 " MB"}'
|
||||
|
||||
echo "CPU usage:"
|
||||
top -bn1 | grep bootc | awk '{print $9}'
|
||||
|
||||
echo "Disk I/O:"
|
||||
iotop -bn1 | grep bootc
|
||||
echo
|
||||
|
||||
echo "=== System Load ==="
|
||||
uptime
|
||||
echo
|
||||
|
||||
echo "=== Performance Analysis Complete ==="
|
||||
```
|
||||
|
||||
## Troubleshooting Guide
|
||||
|
||||
### 1. Common Error Scenarios
|
||||
|
||||
#### Permission Denied Errors
|
||||
|
||||
**Error**: `Permission denied: This command must be executed as the root user`
|
||||
|
||||
**Cause**: Command executed without root privileges
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check current user
|
||||
whoami
|
||||
|
||||
# Switch to root
|
||||
sudo su -
|
||||
|
||||
# Or use sudo
|
||||
sudo bootc internals <command>
|
||||
```
|
||||
|
||||
**Prevention**:
|
||||
```bash
|
||||
# Check if running as root
|
||||
if [ "$EUID" -ne 0 ]; then
|
||||
echo "This script must be run as root"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
#### Filesystem Consistency Errors
|
||||
|
||||
**Error**: `✗ ostree-repo: Repository integrity check failed`
|
||||
|
||||
**Cause**: OSTree repository corruption
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check repository status
|
||||
ostree admin status
|
||||
|
||||
# Verify repository integrity
|
||||
ostree fsck
|
||||
|
||||
# If corruption detected, restore from backup
|
||||
ostree admin deploy --from-commit <backup-commit>
|
||||
|
||||
# Or reinstall if no backup available
|
||||
bootc install to-disk /dev/sda
|
||||
```
|
||||
|
||||
**Prevention**:
|
||||
```bash
|
||||
# Regular integrity checks
|
||||
bootc internals fsck
|
||||
|
||||
# Backup important deployments
|
||||
ostree admin pin <deployment-id>
|
||||
```
|
||||
|
||||
#### Storage Space Errors
|
||||
|
||||
**Error**: `No space left on device`
|
||||
|
||||
**Cause**: Insufficient storage space
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check storage usage
|
||||
df -h /var/lib/bootc
|
||||
|
||||
# Run cleanup
|
||||
bootc internals cleanup
|
||||
|
||||
# Remove old deployments
|
||||
ostree admin cleanup
|
||||
|
||||
# Check for large files
|
||||
du -sh /var/lib/bootc/* | sort -hr
|
||||
|
||||
# Remove unnecessary files
|
||||
rm -rf /var/lib/bootc/tmp/*
|
||||
```
|
||||
|
||||
**Prevention**:
|
||||
```bash
|
||||
# Monitor storage usage
|
||||
df -h /var/lib/bootc | awk 'NR==2 {print $5}' | sed 's/%//'
|
||||
|
||||
# Set up alerts
|
||||
if [ $STORAGE_USAGE -gt 80 ]; then
|
||||
echo "WARNING: Storage usage is high"
|
||||
bootc internals cleanup
|
||||
fi
|
||||
```
|
||||
|
||||
#### Systemd Generator Errors
|
||||
|
||||
**Error**: `Failed to generate systemd unit`
|
||||
|
||||
**Cause**: Systemd generator failure
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check systemd status
|
||||
systemctl status bootc-systemd-generator
|
||||
|
||||
# Check generator logs
|
||||
journalctl -u bootc-systemd-generator
|
||||
|
||||
# Manually run generator
|
||||
bootc internals systemd-generator /run/systemd/system
|
||||
|
||||
# Reload systemd
|
||||
systemctl daemon-reload
|
||||
```
|
||||
|
||||
**Prevention**:
|
||||
```bash
|
||||
# Regular generator testing
|
||||
bootc internals systemd-generator /tmp/test-units
|
||||
|
||||
# Check systemd configuration
|
||||
systemd-analyze verify /etc/systemd/system/bootc-*
|
||||
```
|
||||
|
||||
### 2. Debugging Techniques
|
||||
|
||||
#### Enable Debug Logging
|
||||
|
||||
```bash
|
||||
# Set debug log level
|
||||
export RUST_LOG=debug
|
||||
|
||||
# Run command with debug output
|
||||
bootc internals fsck
|
||||
|
||||
# Check debug logs
|
||||
journalctl -u bootc-* --since "1 hour ago" | grep DEBUG
|
||||
```
|
||||
|
||||
#### Verbose Output
|
||||
|
||||
```bash
|
||||
# Enable verbose output
|
||||
bootc internals fsck --verbose
|
||||
|
||||
# Check verbose logs
|
||||
journalctl -u bootc-* --since "1 hour ago" | grep -v INFO
|
||||
```
|
||||
|
||||
#### System Information
|
||||
|
||||
```bash
|
||||
# Gather system information
|
||||
uname -a
|
||||
lsb_release -a
|
||||
systemctl --version
|
||||
ostree --version
|
||||
bootc --version
|
||||
|
||||
# Check system configuration
|
||||
cat /etc/os-release
|
||||
cat /proc/version
|
||||
cat /proc/cpuinfo | head -20
|
||||
```
|
||||
|
||||
#### Network Diagnostics
|
||||
|
||||
```bash
|
||||
# Check network connectivity
|
||||
ping -c 3 registry.example.com
|
||||
|
||||
# Check DNS resolution
|
||||
nslookup registry.example.com
|
||||
|
||||
# Check firewall rules
|
||||
iptables -L
|
||||
firewall-cmd --list-all
|
||||
|
||||
# Check proxy settings
|
||||
echo $HTTP_PROXY
|
||||
echo $HTTPS_PROXY
|
||||
```
|
||||
|
||||
### 3. Recovery Procedures
|
||||
|
||||
#### System Recovery
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# System recovery script
|
||||
|
||||
echo "=== Bootc System Recovery ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Check system status
|
||||
echo "Checking system status..."
|
||||
bootc status
|
||||
|
||||
# Check filesystem integrity
|
||||
echo "Checking filesystem integrity..."
|
||||
bootc internals fsck
|
||||
|
||||
# If errors found, attempt repair
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "Filesystem errors detected, attempting repair..."
|
||||
|
||||
# Try to repair OSTree repository
|
||||
ostree fsck --repair
|
||||
|
||||
# If repair fails, restore from backup
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "Repair failed, restoring from backup..."
|
||||
ostree admin deploy --from-commit <backup-commit>
|
||||
fi
|
||||
fi
|
||||
|
||||
# Clean up system
|
||||
echo "Cleaning up system..."
|
||||
bootc internals cleanup
|
||||
|
||||
# Verify system is working
|
||||
echo "Verifying system is working..."
|
||||
bootc status
|
||||
bootc internals fsck
|
||||
|
||||
echo "Recovery complete"
|
||||
```
|
||||
|
||||
#### Data Recovery
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Data recovery script
|
||||
|
||||
echo "=== Bootc Data Recovery ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Check for available backups
|
||||
echo "Checking for available backups..."
|
||||
ls -la /var/lib/bootc/backups/
|
||||
|
||||
# List available deployments
|
||||
echo "Available deployments:"
|
||||
ostree admin status
|
||||
|
||||
# Check deployment history
|
||||
echo "Deployment history:"
|
||||
ostree log <deployment-id>
|
||||
|
||||
# Attempt to recover specific deployment
|
||||
echo "Attempting to recover deployment..."
|
||||
ostree admin deploy <deployment-id>
|
||||
|
||||
# Verify recovery
|
||||
echo "Verifying recovery..."
|
||||
bootc status
|
||||
```
|
||||
|
||||
### 4. Performance Optimization
|
||||
|
||||
#### System Optimization
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# System optimization script
|
||||
|
||||
echo "=== Bootc System Optimization ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Optimize OSTree repository
|
||||
echo "Optimizing OSTree repository..."
|
||||
ostree admin cleanup
|
||||
|
||||
# Optimize composefs repository
|
||||
echo "Optimizing composefs repository..."
|
||||
bootc internals cfs optimize
|
||||
|
||||
# Clean up temporary files
|
||||
echo "Cleaning up temporary files..."
|
||||
bootc internals cleanup
|
||||
|
||||
# Optimize systemd services
|
||||
echo "Optimizing systemd services..."
|
||||
systemctl daemon-reload
|
||||
systemctl restart bootc-*
|
||||
|
||||
# Check system performance
|
||||
echo "Checking system performance..."
|
||||
bootc internals fsck
|
||||
df -h /var/lib/bootc
|
||||
free -h
|
||||
```
|
||||
|
||||
#### Storage Optimization
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Storage optimization script
|
||||
|
||||
echo "=== Bootc Storage Optimization ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Check storage usage
|
||||
echo "Current storage usage:"
|
||||
df -h /var/lib/bootc
|
||||
|
||||
# Remove old deployments
|
||||
echo "Removing old deployments..."
|
||||
ostree admin cleanup --keep=3
|
||||
|
||||
# Remove unused images
|
||||
echo "Removing unused images..."
|
||||
bootc image prune
|
||||
|
||||
# Compress repository
|
||||
echo "Compressing repository..."
|
||||
ostree admin cleanup --compress
|
||||
|
||||
# Check optimized storage usage
|
||||
echo "Optimized storage usage:"
|
||||
df -h /var/lib/bootc
|
||||
```
|
||||
|
||||
### 5. Monitoring and Alerting
|
||||
|
||||
#### Health Check Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Health check script
|
||||
|
||||
HEALTH_STATUS=0
|
||||
|
||||
echo "=== Bootc Health Check ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Check system status
|
||||
echo "Checking system status..."
|
||||
if ! bootc status > /dev/null 2>&1; then
|
||||
echo "ERROR: System status check failed"
|
||||
HEALTH_STATUS=1
|
||||
fi
|
||||
|
||||
# Check filesystem integrity
|
||||
echo "Checking filesystem integrity..."
|
||||
if ! bootc internals fsck > /dev/null 2>&1; then
|
||||
echo "ERROR: Filesystem integrity check failed"
|
||||
HEALTH_STATUS=1
|
||||
fi
|
||||
|
||||
# Check storage usage
|
||||
echo "Checking storage usage..."
|
||||
STORAGE_USAGE=$(df /var/lib/bootc | tail -1 | awk '{print $5}' | sed 's/%//')
|
||||
if [ $STORAGE_USAGE -gt 90 ]; then
|
||||
echo "ERROR: Storage usage is critical: ${STORAGE_USAGE}%"
|
||||
HEALTH_STATUS=1
|
||||
elif [ $STORAGE_USAGE -gt 80 ]; then
|
||||
echo "WARNING: Storage usage is high: ${STORAGE_USAGE}%"
|
||||
fi
|
||||
|
||||
# Check memory usage
|
||||
echo "Checking memory usage..."
|
||||
MEMORY_USAGE=$(free | grep Mem | awk '{printf "%.0f", $3/$2 * 100.0}')
|
||||
if [ $MEMORY_USAGE -gt 90 ]; then
|
||||
echo "ERROR: Memory usage is critical: ${MEMORY_USAGE}%"
|
||||
HEALTH_STATUS=1
|
||||
elif [ $MEMORY_USAGE -gt 80 ]; then
|
||||
echo "WARNING: Memory usage is high: ${MEMORY_USAGE}%"
|
||||
fi
|
||||
|
||||
# Check systemd services
|
||||
echo "Checking systemd services..."
|
||||
if ! systemctl is-active bootc-* > /dev/null 2>&1; then
|
||||
echo "ERROR: Some bootc services are not active"
|
||||
HEALTH_STATUS=1
|
||||
fi
|
||||
|
||||
# Report health status
|
||||
if [ $HEALTH_STATUS -eq 0 ]; then
|
||||
echo "Health check passed"
|
||||
else
|
||||
echo "Health check failed"
|
||||
fi
|
||||
|
||||
exit $HEALTH_STATUS
|
||||
```
|
||||
|
||||
#### Alerting Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Alerting script
|
||||
|
||||
# Send alert to monitoring system
|
||||
send_alert() {
|
||||
local severity=$1
|
||||
local message=$2
|
||||
|
||||
curl -X POST "https://monitoring.example.com/alerts" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{
|
||||
\"service\": \"bootc\",
|
||||
\"severity\": \"$severity\",
|
||||
\"message\": \"$message\",
|
||||
\"timestamp\": \"$(date -Iseconds)\"
|
||||
}"
|
||||
}
|
||||
|
||||
# Check system health
|
||||
if ! /usr/local/bin/bootc-health-check.sh; then
|
||||
send_alert "critical" "Bootc system health check failed"
|
||||
fi
|
||||
|
||||
# Check storage usage
|
||||
STORAGE_USAGE=$(df /var/lib/bootc | tail -1 | awk '{print $5}' | sed 's/%//')
|
||||
if [ $STORAGE_USAGE -gt 90 ]; then
|
||||
send_alert "critical" "Storage usage is critical: ${STORAGE_USAGE}%"
|
||||
elif [ $STORAGE_USAGE -gt 80 ]; then
|
||||
send_alert "warning" "Storage usage is high: ${STORAGE_USAGE}%"
|
||||
fi
|
||||
|
||||
# Check memory usage
|
||||
MEMORY_USAGE=$(free | grep Mem | awk '{printf "%.0f", $3/$2 * 100.0}')
|
||||
if [ $MEMORY_USAGE -gt 90 ]; then
|
||||
send_alert "critical" "Memory usage is critical: ${MEMORY_USAGE}%"
|
||||
elif [ $MEMORY_USAGE -gt 80 ]; then
|
||||
send_alert "warning" "Memory usage is high: ${MEMORY_USAGE}%"
|
||||
fi
|
||||
```
|
||||
|
||||
This comprehensive examples and troubleshooting guide provides practical solutions for common issues and advanced debugging techniques for the bootc internals system.
|
||||
980
internals/bootc-internals-external-commands.md
Normal file
980
internals/bootc-internals-external-commands.md
Normal file
|
|
@ -0,0 +1,980 @@
|
|||
# bootc internals - External Commands Reference
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a comprehensive reference for all external commands used by `bootc internals` operations. These commands are essential for understanding the dependencies and integration points of the bootc internals system.
|
||||
|
||||
## Core Commands
|
||||
|
||||
### bootc
|
||||
|
||||
**Purpose**: Main bootc command for internals operations
|
||||
**Usage**: `bootc internals <subcommand> [options...]`
|
||||
**Dependencies**: None (core command)
|
||||
|
||||
#### Internals Subcommands
|
||||
- `bootc internals systemd-generator` - Generate systemd units
|
||||
- `bootc internals fixup-etc-fstab` - Fix /etc/fstab
|
||||
- `bootc internals print-json-schema` - Generate JSON schemas
|
||||
- `bootc internals fsverity` - Filesystem verity operations
|
||||
- `bootc internals fsck` - Filesystem consistency check
|
||||
- `bootc internals cleanup` - Perform cleanup operations
|
||||
- `bootc internals relabel` - SELinux relabeling
|
||||
- `bootc internals ostree-ext` - Proxy to ostree-ext CLI
|
||||
- `bootc internals cfs` - Proxy to cfsctl CLI
|
||||
- `bootc internals ostree-container` - Proxy to ostree container CLI
|
||||
- `bootc internals test-composefs` - Test composefs repository
|
||||
- `bootc internals loopback-cleanup-helper` - Loopback device cleanup
|
||||
- `bootc internals allocate-cleanup-loopback` - Test loopback allocation
|
||||
- `bootc internals bootc-install-completion` - Complete installation
|
||||
- `bootc internals reboot` - Initiate reboot
|
||||
- `bootc internals publish-rhsm-facts` - Publish RHSM facts
|
||||
- `bootc internals dump-cli-json` - Dump CLI structure as JSON
|
||||
- `bootc internals dir-diff` - Test directory diff functionality
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Generate systemd units
|
||||
bootc internals systemd-generator /run/systemd/system
|
||||
|
||||
# Fix /etc/fstab
|
||||
bootc internals fixup-etc-fstab
|
||||
|
||||
# Run filesystem check
|
||||
bootc internals fsck
|
||||
|
||||
# Clean up system
|
||||
bootc internals cleanup
|
||||
|
||||
# Test composefs
|
||||
bootc internals test-composefs
|
||||
|
||||
# Reboot system
|
||||
bootc internals reboot
|
||||
```
|
||||
|
||||
## Systemd Commands
|
||||
|
||||
### systemctl
|
||||
|
||||
**Purpose**: Systemd service management
|
||||
**Usage**: `systemctl <subcommand> [options...]`
|
||||
**Dependencies**: systemd
|
||||
|
||||
#### Service Commands
|
||||
- `systemctl status` - Show service status
|
||||
- `systemctl start` - Start service
|
||||
- `systemctl stop` - Stop service
|
||||
- `systemctl restart` - Restart service
|
||||
- `systemctl enable` - Enable service
|
||||
- `systemctl disable` - Disable service
|
||||
- `systemctl reload` - Reload service
|
||||
- `systemctl daemon-reload` - Reload systemd configuration
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Check service status
|
||||
systemctl status bootc-systemd-generator
|
||||
|
||||
# Start service
|
||||
systemctl start bootc-systemd-generator
|
||||
|
||||
# Enable service
|
||||
systemctl enable bootc-systemd-generator
|
||||
|
||||
# Reload systemd configuration
|
||||
systemctl daemon-reload
|
||||
```
|
||||
|
||||
### journalctl
|
||||
|
||||
**Purpose**: Systemd journal viewing
|
||||
**Usage**: `journalctl [options...]`
|
||||
**Dependencies**: systemd
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show all logs
|
||||
journalctl
|
||||
|
||||
# Show logs for service
|
||||
journalctl -u bootc-systemd-generator
|
||||
|
||||
# Show recent logs
|
||||
journalctl -n 100
|
||||
|
||||
# Follow logs
|
||||
journalctl -f
|
||||
|
||||
# Show logs since time
|
||||
journalctl --since "1 hour ago"
|
||||
|
||||
# Show logs with priority
|
||||
journalctl -p err
|
||||
```
|
||||
|
||||
## OSTree Commands
|
||||
|
||||
### ostree
|
||||
|
||||
**Purpose**: OSTree repository operations
|
||||
**Usage**: `ostree <subcommand> [options...]`
|
||||
**Dependencies**: ostree package
|
||||
|
||||
#### Repository Commands
|
||||
- `ostree log` - Show commit log
|
||||
- `ostree show` - Show commit details
|
||||
- `ostree refs` - List references
|
||||
- `ostree ls` - List repository contents
|
||||
- `ostree cat` - Show file contents
|
||||
- `ostree checkout` - Checkout files
|
||||
- `ostree admin status` - Show admin status
|
||||
- `ostree admin pin` - Pin deployments
|
||||
- `ostree admin unpin` - Unpin deployments
|
||||
- `ostree admin deploy` - Deploy commits
|
||||
- `ostree admin rollback` - Rollback deployments
|
||||
- `ostree admin cleanup` - Clean up deployments
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show repository status
|
||||
ostree admin status
|
||||
|
||||
# List references
|
||||
ostree refs
|
||||
|
||||
# Show commit details
|
||||
ostree show <commit-hash>
|
||||
|
||||
# List repository contents
|
||||
ostree ls <commit-hash>
|
||||
|
||||
# Show file contents
|
||||
ostree cat <commit-hash> /path/to/file
|
||||
|
||||
# Checkout files
|
||||
ostree checkout <commit-hash> /path/to/destination
|
||||
|
||||
# Deploy commit
|
||||
ostree admin deploy <commit-hash>
|
||||
|
||||
# Rollback deployment
|
||||
ostree admin rollback
|
||||
|
||||
# Clean up deployments
|
||||
ostree admin cleanup
|
||||
```
|
||||
|
||||
### ostree-ext
|
||||
|
||||
**Purpose**: Extended OSTree operations
|
||||
**Usage**: `ostree-ext <subcommand> [options...]`
|
||||
**Dependencies**: ostree-ext package
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Container operations
|
||||
ostree-ext container pull quay.io/myorg/image:latest
|
||||
|
||||
# Repository operations
|
||||
ostree-ext repo create /path/to/repo
|
||||
|
||||
# Image operations
|
||||
ostree-ext image build /path/to/image
|
||||
```
|
||||
|
||||
## Composefs Commands
|
||||
|
||||
### cfsctl
|
||||
|
||||
**Purpose**: Composefs control operations
|
||||
**Usage**: `cfsctl <subcommand> [options...]`
|
||||
**Dependencies**: composefs package
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Create repository
|
||||
cfsctl repo create /path/to/repo
|
||||
|
||||
# Import layer
|
||||
cfsctl oci import-layer <sha256> <name>
|
||||
|
||||
# List layers
|
||||
cfsctl oci ls-layer <name>
|
||||
|
||||
# Create filesystem
|
||||
cfsctl create-fs <name> <output>
|
||||
|
||||
# Write boot entries
|
||||
cfsctl write-boot <name> <output>
|
||||
```
|
||||
|
||||
## Filesystem Commands
|
||||
|
||||
### fsverity
|
||||
|
||||
**Purpose**: Filesystem verity operations
|
||||
**Usage**: `fsverity <subcommand> [options...]`
|
||||
**Dependencies**: fsverity-utils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Measure file digest
|
||||
fsverity measure /path/to/file
|
||||
|
||||
# Enable verity
|
||||
fsverity enable /path/to/file
|
||||
|
||||
# Show verity status
|
||||
fsverity status /path/to/file
|
||||
```
|
||||
|
||||
### mount
|
||||
|
||||
**Purpose**: Filesystem mounting
|
||||
**Usage**: `mount [options...] <device> <directory>`
|
||||
**Dependencies**: util-linux
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Mount filesystem
|
||||
mount /dev/sda1 /mnt
|
||||
|
||||
# Unmount filesystem
|
||||
umount /mnt
|
||||
|
||||
# Check mount points
|
||||
findmnt
|
||||
|
||||
# Mount with options
|
||||
mount -o ro,noexec /dev/sda1 /mnt
|
||||
```
|
||||
|
||||
### umount
|
||||
|
||||
**Purpose**: Unmount filesystems
|
||||
**Usage**: `umount [options...] <directory>`
|
||||
**Dependencies**: util-linux
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Unmount filesystem
|
||||
umount /mnt
|
||||
|
||||
# Force unmount
|
||||
umount -f /mnt
|
||||
|
||||
# Lazy unmount
|
||||
umount -l /mnt
|
||||
```
|
||||
|
||||
### losetup
|
||||
|
||||
**Purpose**: Loop device management
|
||||
**Usage**: `losetup [options...]`
|
||||
**Dependencies**: util-linux
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Create loop device
|
||||
losetup -f /path/to/image
|
||||
|
||||
# List loop devices
|
||||
losetup -a
|
||||
|
||||
# Detach loop device
|
||||
losetup -d /dev/loop0
|
||||
|
||||
# Show loop device info
|
||||
losetup -l
|
||||
```
|
||||
|
||||
## SELinux Commands
|
||||
|
||||
### setsebool
|
||||
|
||||
**Purpose**: Set SELinux boolean values
|
||||
**Usage**: `setsebool [options...] <boolean> <value>`
|
||||
**Dependencies**: policycoreutils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Set boolean value
|
||||
setsebool -P httpd_can_network_connect 1
|
||||
|
||||
# List boolean values
|
||||
getsebool -a
|
||||
|
||||
# Show boolean value
|
||||
getsebool httpd_can_network_connect
|
||||
```
|
||||
|
||||
### restorecon
|
||||
|
||||
**Purpose**: Restore SELinux contexts
|
||||
**Usage**: `restorecon [options...] <path>`
|
||||
**Dependencies**: policycoreutils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Restore context
|
||||
restorecon -R /path/to/directory
|
||||
|
||||
# Restore with verbose output
|
||||
restorecon -v /path/to/file
|
||||
|
||||
# Restore with force
|
||||
restorecon -F /path/to/file
|
||||
```
|
||||
|
||||
### chcon
|
||||
|
||||
**Purpose**: Change SELinux context
|
||||
**Usage**: `chcon [options...] <context> <path>`
|
||||
**Dependencies**: coreutils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Change context
|
||||
chcon -t httpd_exec_t /path/to/file
|
||||
|
||||
# Change context recursively
|
||||
chcon -R -t httpd_exec_t /path/to/directory
|
||||
|
||||
# Change context with reference
|
||||
chcon --reference /path/to/reference /path/to/target
|
||||
```
|
||||
|
||||
## Storage Commands
|
||||
|
||||
### df
|
||||
|
||||
**Purpose**: Disk space usage
|
||||
**Usage**: `df [options...] [file...]`
|
||||
**Dependencies**: coreutils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show disk usage
|
||||
df -h
|
||||
|
||||
# Show specific filesystem
|
||||
df -h /var/lib/bootc
|
||||
|
||||
# Show inode usage
|
||||
df -i
|
||||
|
||||
# Show all filesystems
|
||||
df -a
|
||||
```
|
||||
|
||||
### du
|
||||
|
||||
**Purpose**: Directory space usage
|
||||
**Usage**: `du [options...] [file...]`
|
||||
**Dependencies**: coreutils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show directory usage
|
||||
du -h /var/lib/bootc
|
||||
|
||||
# Show total usage
|
||||
du -sh /var/lib/bootc
|
||||
|
||||
# Show usage by subdirectory
|
||||
du -h --max-depth=1 /var/lib/bootc
|
||||
|
||||
# Show usage of all files
|
||||
du -ah /var/lib/bootc
|
||||
```
|
||||
|
||||
### lsblk
|
||||
|
||||
**Purpose**: List block devices
|
||||
**Usage**: `lsblk [options...]`
|
||||
**Dependencies**: util-linux
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# List block devices
|
||||
lsblk
|
||||
|
||||
# Show device tree
|
||||
lsblk -f
|
||||
|
||||
# Show device sizes
|
||||
lsblk -b
|
||||
|
||||
# Show device types
|
||||
lsblk -d
|
||||
```
|
||||
|
||||
## Network Commands
|
||||
|
||||
### curl
|
||||
|
||||
**Purpose**: HTTP client for registry operations
|
||||
**Usage**: `curl [options...] <url>`
|
||||
**Dependencies**: curl
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Download file
|
||||
curl -O https://example.com/file.tar
|
||||
|
||||
# Get HTTP headers
|
||||
curl -I https://example.com
|
||||
|
||||
# POST data
|
||||
curl -X POST -d "data" https://example.com
|
||||
|
||||
# With authentication
|
||||
curl -u username:password https://example.com
|
||||
|
||||
# With custom headers
|
||||
curl -H "Authorization: Bearer token" https://example.com
|
||||
```
|
||||
|
||||
### wget
|
||||
|
||||
**Purpose**: HTTP client for downloading files
|
||||
**Usage**: `wget [options...] <url>`
|
||||
**Dependencies**: wget
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Download file
|
||||
wget https://example.com/file.tar
|
||||
|
||||
# Download with progress
|
||||
wget --progress=bar https://example.com/file.tar
|
||||
|
||||
# Download recursively
|
||||
wget -r https://example.com/
|
||||
|
||||
# Download with authentication
|
||||
wget --user=username --password=password https://example.com
|
||||
```
|
||||
|
||||
## Process Commands
|
||||
|
||||
### ps
|
||||
|
||||
**Purpose**: Process status
|
||||
**Usage**: `ps [options...]`
|
||||
**Dependencies**: procps
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show all processes
|
||||
ps aux
|
||||
|
||||
# Show process tree
|
||||
ps -ef
|
||||
|
||||
# Show specific process
|
||||
ps -p 1234
|
||||
|
||||
# Show processes by user
|
||||
ps -u username
|
||||
```
|
||||
|
||||
### kill
|
||||
|
||||
**Purpose**: Send signals to processes
|
||||
**Usage**: `kill [options...] <pid>`
|
||||
**Dependencies**: util-linux
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Kill process
|
||||
kill 1234
|
||||
|
||||
# Force kill process
|
||||
kill -9 1234
|
||||
|
||||
# Send signal
|
||||
kill -TERM 1234
|
||||
|
||||
# Kill by name
|
||||
pkill process_name
|
||||
```
|
||||
|
||||
### pkill
|
||||
|
||||
**Purpose**: Kill processes by name
|
||||
**Usage**: `pkill [options...] <pattern>`
|
||||
**Dependencies**: procps
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Kill by name
|
||||
pkill process_name
|
||||
|
||||
# Force kill by name
|
||||
pkill -9 process_name
|
||||
|
||||
# Kill by pattern
|
||||
pkill -f "pattern"
|
||||
```
|
||||
|
||||
## File Commands
|
||||
|
||||
### ls
|
||||
|
||||
**Purpose**: List directory contents
|
||||
**Usage**: `ls [options...] [file...]`
|
||||
**Dependencies**: coreutils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# List files
|
||||
ls
|
||||
|
||||
# List with details
|
||||
ls -l
|
||||
|
||||
# List all files
|
||||
ls -a
|
||||
|
||||
# List with human readable sizes
|
||||
ls -lh
|
||||
|
||||
# List with recursive
|
||||
ls -R
|
||||
|
||||
# List with sort by time
|
||||
ls -lt
|
||||
```
|
||||
|
||||
### find
|
||||
|
||||
**Purpose**: Find files
|
||||
**Usage**: `find [path...] [expression]`
|
||||
**Dependencies**: findutils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Find files by name
|
||||
find /path -name "*.txt"
|
||||
|
||||
# Find files by type
|
||||
find /path -type f
|
||||
|
||||
# Find files by size
|
||||
find /path -size +100M
|
||||
|
||||
# Find files by modification time
|
||||
find /path -mtime -7
|
||||
|
||||
# Find files by permissions
|
||||
find /path -perm 644
|
||||
```
|
||||
|
||||
### stat
|
||||
|
||||
**Purpose**: File status
|
||||
**Usage**: `stat [options...] [file...]`
|
||||
**Dependencies**: coreutils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show file status
|
||||
stat file.txt
|
||||
|
||||
# Show in custom format
|
||||
stat -c "%n %s %Y" file.txt
|
||||
|
||||
# Show filesystem status
|
||||
stat -f /path
|
||||
|
||||
# Show with format
|
||||
stat --format="%n: %s bytes" file.txt
|
||||
```
|
||||
|
||||
## Archive Commands
|
||||
|
||||
### tar
|
||||
|
||||
**Purpose**: Archive operations
|
||||
**Usage**: `tar [options...] <archive> [file...]`
|
||||
**Dependencies**: tar
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Create archive
|
||||
tar -cf archive.tar file1 file2
|
||||
|
||||
# Extract archive
|
||||
tar -xf archive.tar
|
||||
|
||||
# List archive contents
|
||||
tar -tf archive.tar
|
||||
|
||||
# Create compressed archive
|
||||
tar -czf archive.tar.gz file1 file2
|
||||
|
||||
# Extract compressed archive
|
||||
tar -xzf archive.tar.gz
|
||||
```
|
||||
|
||||
### gzip
|
||||
|
||||
**Purpose**: Compression
|
||||
**Usage**: `gzip [options...] [file...]`
|
||||
**Dependencies**: gzip
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Compress file
|
||||
gzip file.txt
|
||||
|
||||
# Decompress file
|
||||
gzip -d file.txt.gz
|
||||
|
||||
# Compress with custom level
|
||||
gzip -9 file.txt
|
||||
|
||||
# Keep original file
|
||||
gzip -k file.txt
|
||||
```
|
||||
|
||||
## System Information Commands
|
||||
|
||||
### uname
|
||||
|
||||
**Purpose**: System information
|
||||
**Usage**: `uname [options...]`
|
||||
**Dependencies**: coreutils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show system name
|
||||
uname
|
||||
|
||||
# Show all information
|
||||
uname -a
|
||||
|
||||
# Show kernel name
|
||||
uname -s
|
||||
|
||||
# Show kernel version
|
||||
uname -r
|
||||
|
||||
# Show machine type
|
||||
uname -m
|
||||
```
|
||||
|
||||
### hostname
|
||||
|
||||
**Purpose**: Hostname operations
|
||||
**Usage**: `hostname [options...]`
|
||||
**Dependencies**: hostname
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show hostname
|
||||
hostname
|
||||
|
||||
# Show FQDN
|
||||
hostname -f
|
||||
|
||||
# Show short hostname
|
||||
hostname -s
|
||||
|
||||
# Show domain name
|
||||
hostname -d
|
||||
```
|
||||
|
||||
### lscpu
|
||||
|
||||
**Purpose**: CPU information
|
||||
**Usage**: `lscpu [options...]`
|
||||
**Dependencies**: util-linux
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show CPU information
|
||||
lscpu
|
||||
|
||||
# Show in JSON format
|
||||
lscpu -J
|
||||
|
||||
# Show in extended format
|
||||
lscpu -e
|
||||
|
||||
# Show in parseable format
|
||||
lscpu -p
|
||||
```
|
||||
|
||||
### free
|
||||
|
||||
**Purpose**: Memory information
|
||||
**Usage**: `free [options...]`
|
||||
**Dependencies**: procps
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show memory usage
|
||||
free
|
||||
|
||||
# Show in human readable format
|
||||
free -h
|
||||
|
||||
# Show in bytes
|
||||
free -b
|
||||
|
||||
# Show with total
|
||||
free -t
|
||||
|
||||
# Show with wide format
|
||||
free -w
|
||||
```
|
||||
|
||||
## Container Commands
|
||||
|
||||
### podman
|
||||
|
||||
**Purpose**: Container runtime
|
||||
**Usage**: `podman <subcommand> [options...]`
|
||||
**Dependencies**: podman
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# List containers
|
||||
podman ps
|
||||
|
||||
# List images
|
||||
podman images
|
||||
|
||||
# Pull image
|
||||
podman pull quay.io/myorg/image:latest
|
||||
|
||||
# Run container
|
||||
podman run -it image:latest
|
||||
|
||||
# Build image
|
||||
podman build -t myimage:latest .
|
||||
|
||||
# Inspect image
|
||||
podman inspect image:latest
|
||||
```
|
||||
|
||||
### docker
|
||||
|
||||
**Purpose**: Alternative container runtime
|
||||
**Usage**: `docker <subcommand> [options...]`
|
||||
**Dependencies**: docker
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# List containers
|
||||
docker ps
|
||||
|
||||
# List images
|
||||
docker images
|
||||
|
||||
# Pull image
|
||||
docker pull quay.io/myorg/image:latest
|
||||
|
||||
# Run container
|
||||
docker run -it image:latest
|
||||
|
||||
# Build image
|
||||
docker build -t myimage:latest .
|
||||
```
|
||||
|
||||
## Development Commands
|
||||
|
||||
### make
|
||||
|
||||
**Purpose**: Build automation
|
||||
**Usage**: `make [target...]`
|
||||
**Dependencies**: make
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Build project
|
||||
make
|
||||
|
||||
# Clean build
|
||||
make clean
|
||||
|
||||
# Install
|
||||
make install
|
||||
|
||||
# Run tests
|
||||
make test
|
||||
|
||||
# Update generated files
|
||||
make update-generated
|
||||
```
|
||||
|
||||
### cargo
|
||||
|
||||
**Purpose**: Rust package manager
|
||||
**Usage**: `cargo <subcommand> [options...]`
|
||||
**Dependencies**: rust
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Build project
|
||||
cargo build
|
||||
|
||||
# Run project
|
||||
cargo run
|
||||
|
||||
# Run tests
|
||||
cargo test
|
||||
|
||||
# Check code
|
||||
cargo check
|
||||
|
||||
# Update dependencies
|
||||
cargo update
|
||||
```
|
||||
|
||||
### git
|
||||
|
||||
**Purpose**: Version control
|
||||
**Usage**: `git <subcommand> [options...]`
|
||||
**Dependencies**: git
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://github.com/containers/bootc.git
|
||||
|
||||
# Check status
|
||||
git status
|
||||
|
||||
# Add files
|
||||
git add .
|
||||
|
||||
# Commit changes
|
||||
git commit -m "message"
|
||||
|
||||
# Push changes
|
||||
git push
|
||||
```
|
||||
|
||||
## Monitoring Commands
|
||||
|
||||
### top
|
||||
|
||||
**Purpose**: Process monitoring
|
||||
**Usage**: `top [options...]`
|
||||
**Dependencies**: procps
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show processes
|
||||
top
|
||||
|
||||
# Show specific user
|
||||
top -u username
|
||||
|
||||
# Show specific process
|
||||
top -p 1234
|
||||
|
||||
# Show with custom delay
|
||||
top -d 5
|
||||
|
||||
# Show with custom sort
|
||||
top -o %CPU
|
||||
```
|
||||
|
||||
### htop
|
||||
|
||||
**Purpose**: Interactive process monitoring
|
||||
**Usage**: `htop [options...]`
|
||||
**Dependencies**: htop
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show processes
|
||||
htop
|
||||
|
||||
# Show specific user
|
||||
htop -u username
|
||||
|
||||
# Show specific process
|
||||
htop -p 1234
|
||||
|
||||
# Show with custom delay
|
||||
htop -d 5
|
||||
```
|
||||
|
||||
### iotop
|
||||
|
||||
**Purpose**: I/O monitoring
|
||||
**Usage**: `iotop [options...]`
|
||||
**Dependencies**: iotop
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show I/O usage
|
||||
iotop
|
||||
|
||||
# Show only processes doing I/O
|
||||
iotop -o
|
||||
|
||||
# Show with custom delay
|
||||
iotop -d 5
|
||||
|
||||
# Show with custom refresh
|
||||
iotop -n 10
|
||||
```
|
||||
|
||||
## Security Commands
|
||||
|
||||
### openssl
|
||||
|
||||
**Purpose**: SSL/TLS operations
|
||||
**Usage**: `openssl <command> [options...]`
|
||||
**Dependencies**: openssl
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Generate private key
|
||||
openssl genrsa -out key.pem 2048
|
||||
|
||||
# Generate certificate
|
||||
openssl req -new -x509 -key key.pem -out cert.pem
|
||||
|
||||
# Verify certificate
|
||||
openssl verify cert.pem
|
||||
|
||||
# Check certificate details
|
||||
openssl x509 -in cert.pem -text -noout
|
||||
|
||||
# Generate hash
|
||||
openssl dgst -sha256 file.txt
|
||||
```
|
||||
|
||||
### gpg
|
||||
|
||||
**Purpose**: GPG operations
|
||||
**Usage**: `gpg [options...]`
|
||||
**Dependencies**: gnupg
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Generate key pair
|
||||
gpg --gen-key
|
||||
|
||||
# List keys
|
||||
gpg --list-keys
|
||||
|
||||
# Sign file
|
||||
gpg --sign file.txt
|
||||
|
||||
# Verify signature
|
||||
gpg --verify file.txt.asc
|
||||
|
||||
# Encrypt file
|
||||
gpg --encrypt file.txt
|
||||
```
|
||||
|
||||
This comprehensive reference covers all external commands used by the bootc internals system, providing examples and usage patterns for each command.
|
||||
419
internals/bootc-internals-flowchart.md
Normal file
419
internals/bootc-internals-flowchart.md
Normal file
|
|
@ -0,0 +1,419 @@
|
|||
# bootc internals - Process Flowchart
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a visual representation of the `bootc internals` process flow, showing the decision points, operations, and data structures involved in internal system operations.
|
||||
|
||||
## Main Process Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ bootc internals │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Parse Command Arguments │
|
||||
│ │
|
||||
│ • Parse internals subcommand │
|
||||
│ • Parse command-specific options │
|
||||
│ • Validate arguments │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Route to Subcommand │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Subcommand Type? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Systemd │ │ Filesystem │ │ Proxy │ │
|
||||
│ │ Generator │ │ Operations │ │ Commands │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │
|
||||
│ │ │ Generate ││ │ │ Fsck ││ │ │ OstreeExt ││ │
|
||||
│ │ │ Units ││ │ │ Cleanup ││ │ │ Cfs ││ │
|
||||
│ │ │ Fix Fstab ││ │ │ Relabel ││ │ │ OstreeCont ││ │
|
||||
│ │ └─────────────┘│ │ │ Fsverity ││ │ └─────────────┘│ │
|
||||
│ └─────────────────┘ │ └─────────────┘│ └─────────────────┘ │
|
||||
│ │ │ │
|
||||
│ ┌─────────────────┐ │ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Testing │ │ │ System │ │ Development │ │
|
||||
│ │ Commands │ │ │ Operations │ │ Tools │ │
|
||||
│ │ │ │ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ │ ┌─────────────┐│ │ ┌─────────────┐│ │
|
||||
│ │ │ TestComp ││ │ │ │ Reboot ││ │ │ PrintSchema ││ │
|
||||
│ │ │ Loopback ││ │ │ │ InstallComp ││ │ │ DumpCliJson ││ │
|
||||
│ │ │ DirDiff ││ │ │ │ RhsmFacts ││ │ │ DirDiff ││ │
|
||||
│ │ └─────────────┘│ │ │ └─────────────┘│ │ └─────────────┘│ │
|
||||
│ └─────────────────┘ │ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Internal operation completed successfully │
|
||||
│ • Results displayed or logged │
|
||||
│ • System state updated if applicable │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Systemd Generator Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Systemd Generator Process │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check System State │
|
||||
│ │
|
||||
│ • Check if system is ostree-booted │
|
||||
│ • Verify /etc/fstab exists │
|
||||
│ • Check for existing bootc stamps │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Analyze /etc/fstab │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Fstab Analysis │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ From Anaconda │ │ Not From Anaconda │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Generate ││ │ │ No Action Needed ││ │
|
||||
│ │ │ Fstab Editor││ │ │ ││ │
|
||||
│ │ │ Service ││ │ │ • Return false ││ │
|
||||
│ │ │ ││ │ │ • Exit cleanly ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Generate Systemd Unit │
|
||||
│ │
|
||||
│ • Create bootc-fstab-edit.service │
|
||||
│ • Set up service dependencies │
|
||||
│ • Configure service execution │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Systemd unit generated successfully │
|
||||
│ • Service ready for execution │
|
||||
│ • Fstab will be updated on next boot │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Filesystem Consistency Check Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Fsck Process │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Initialize Storage │
|
||||
│ │
|
||||
│ • Get storage instance │
|
||||
│ • Open OSTree repository │
|
||||
│ • Prepare output stream │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Run Consistency Checks │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Check Type? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ OSTree │ │ Composefs │ │ Deployment │ │
|
||||
│ │ Repository │ │ Repository │ State │ │
|
||||
│ │ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │
|
||||
│ │ │ Check Repo ││ │ │ Check Repo ││ │ │ Check Depl ││ │
|
||||
│ │ │ Integrity ││ │ │ Integrity ││ │ │ States ││ │
|
||||
│ │ │ Validate ││ │ │ Validate ││ │ │ Validate ││ │
|
||||
│ │ │ Objects ││ │ │ Images ││ │ │ Configs ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────┘│ │ └─────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Report Results │
|
||||
│ │
|
||||
│ • Display check results │
|
||||
│ • Report any errors found │
|
||||
│ • Provide recommendations │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • All checks completed │
|
||||
│ │ • System integrity verified │
|
||||
│ │ • Issues reported if found │
|
||||
│ │ • Recommendations provided │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Cleanup Operations Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Cleanup Process │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Initialize Storage │
|
||||
│ │
|
||||
│ • Get storage instance │
|
||||
│ • Open OSTree repository │
|
||||
│ • Prepare cleanup operations │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Identify Cleanup Targets │
|
||||
│ │
|
||||
│ • Find old deployments │
|
||||
│ • Identify unused container images │
|
||||
│ • Locate temporary files │
|
||||
│ • Check for orphaned data │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Perform Cleanup │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Cleanup Type? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Deployments │ │ Images │ │ Temporary │ │
|
||||
│ │ │ │ │ │ Files │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │
|
||||
│ │ │ Remove Old ││ │ │ Remove ││ │ │ Remove ││ │
|
||||
│ │ │ Deployments ││ │ │ Unused ││ │ │ Temp Files ││ │
|
||||
│ │ │ Clean Refs ││ │ │ Images ││ │ │ Clean Cache ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────┘│ │ └─────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Garbage Collection │
|
||||
│ │
|
||||
│ • Run OSTree garbage collection │
|
||||
│ • Clean up repository objects │
|
||||
│ • Update repository metadata │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Cleanup completed successfully │
|
||||
│ • Storage space freed │
|
||||
│ • System optimized │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Proxy Commands Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Proxy Commands Process │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Determine Proxy Type │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Proxy Type? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ OstreeExt │ │ Cfs │ │ OstreeCont │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │
|
||||
│ │ │ Parse Args ││ │ │ Parse Args ││ │ │ Parse Args ││ │
|
||||
│ │ │ Call CLI ││ │ │ Call CLI ││ │ │ Call CLI ││ │
|
||||
│ │ │ Return ││ │ │ Return ││ │ │ Return ││ │
|
||||
│ │ │ Results ││ │ │ Results ││ │ │ Results ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────┘│ │ └─────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Execute Proxy Command │
|
||||
│ │
|
||||
│ • Forward arguments to target CLI │
|
||||
│ • Execute command with proper context │
|
||||
│ • Return results to caller │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Proxy command executed successfully │
|
||||
│ • Results returned to caller │
|
||||
│ • Target CLI completed │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Testing Commands Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Testing Commands Process │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Determine Test Type │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Test Type? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ TestComp │ │ Loopback │ │ DirDiff │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │
|
||||
│ │ │ Init Repo ││ │ │ Create Dev ││ │ │ Setup Dirs ││ │
|
||||
│ │ │ Write Test ││ │ │ Test Ops ││ │ │ Run Merge ││ │
|
||||
│ │ │ Verify ││ │ │ Cleanup ││ │ │ Verify ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────┘│ │ └─────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Execute Test │
|
||||
│ │
|
||||
│ • Run test operations │
|
||||
│ • Verify expected results │
|
||||
│ • Clean up test data │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Test completed successfully │
|
||||
│ • Results verified │
|
||||
│ • System state restored │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Error Handling Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Detection │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Classification │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ System │ │ Permission │ │ Resource │ │
|
||||
│ │ Errors │ │ Errors │ │ Errors │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • Not Root │ │ • Access Denied │ │ • Out of Space │ │
|
||||
│ │ • Not Booted │ │ • Invalid Path │ │ • Memory Error │ │
|
||||
│ │ • Invalid State │ │ • File Not Found│ │ • Device Error │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Response │
|
||||
│ │
|
||||
│ • Display error message │
|
||||
│ • Provide context information │
|
||||
│ • Suggest remediation steps │
|
||||
│ • Return appropriate exit code │
|
||||
│ • Clean up any partial state │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## State Transitions
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ System States │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Initial State │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ System Ready │ │
|
||||
│ │ │ │
|
||||
│ │ • All services running │ │
|
||||
│ │ • Storage available │ │
|
||||
│ │ • Permissions correct │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Execute Command │ │
|
||||
│ │ │ │
|
||||
│ │ • Parse arguments │ │
|
||||
│ │ • Validate inputs │ │
|
||||
│ │ • Check prerequisites │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Processing State │ │
|
||||
│ │ │ │
|
||||
│ │ • Command executing │ │
|
||||
│ │ • System state changing │ │
|
||||
│ │ • Resources being used │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Final State │ │
|
||||
│ │ │ │
|
||||
│ │ • Command completed │ │
|
||||
│ │ • System state updated │ │
|
||||
│ │ • Resources cleaned up │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
This flowchart provides a comprehensive visual representation of the bootc internals process, showing all decision points, operations, and state transitions involved in internal system operations.
|
||||
313
internals/bootc-internals-quick-reference.md
Normal file
313
internals/bootc-internals-quick-reference.md
Normal file
|
|
@ -0,0 +1,313 @@
|
|||
# bootc internals - Quick Reference
|
||||
|
||||
## Command Summary
|
||||
|
||||
| Command | Purpose | Usage |
|
||||
|---------|---------|-------|
|
||||
| `systemd-generator` | Generate systemd units | `bootc internals systemd-generator <dir>` |
|
||||
| `fixup-etc-fstab` | Fix /etc/fstab | `bootc internals fixup-etc-fstab` |
|
||||
| `print-json-schema` | Generate JSON schemas | `bootc internals print-json-schema --of <type>` |
|
||||
| `fsverity` | Filesystem verity ops | `bootc internals fsverity <subcommand>` |
|
||||
| `fsck` | Filesystem consistency | `bootc internals fsck` |
|
||||
| `cleanup` | System cleanup | `bootc internals cleanup` |
|
||||
| `relabel` | SELinux relabeling | `bootc internals relabel <path>` |
|
||||
| `ostree-ext` | Proxy to ostree-ext | `bootc internals ostree-ext [args...]` |
|
||||
| `cfs` | Proxy to cfsctl | `bootc internals cfs [args...]` |
|
||||
| `ostree-container` | Proxy to ostree container | `bootc internals ostree-container [args...]` |
|
||||
| `test-composefs` | Test composefs repo | `bootc internals test-composefs` |
|
||||
| `loopback-cleanup-helper` | Loopback cleanup | `bootc internals loopback-cleanup-helper --device <dev>` |
|
||||
| `allocate-cleanup-loopback` | Test loopback | `bootc internals allocate-cleanup-loopback --file-path <path>` |
|
||||
| `bootc-install-completion` | Complete installation | `bootc internals bootc-install-completion --sysroot <path> --stateroot <name>` |
|
||||
| `reboot` | Initiate reboot | `bootc internals reboot` |
|
||||
| `publish-rhsm-facts` | Publish RHSM facts | `bootc internals publish-rhsm-facts` |
|
||||
| `dump-cli-json` | Dump CLI JSON | `bootc internals dump-cli-json` |
|
||||
| `dir-diff` | Test directory diff | `bootc internals dir-diff <pristine> <current> <new> [--perform-merge]` |
|
||||
|
||||
## Fsverity Subcommands
|
||||
|
||||
| Subcommand | Purpose | Usage |
|
||||
|------------|---------|-------|
|
||||
| `measure` | Measure file digest | `bootc internals fsverity measure --path <file>` |
|
||||
| `enable` | Enable verity | `bootc internals fsverity enable --path <file>` |
|
||||
|
||||
## Common Options
|
||||
|
||||
| Option | Purpose | Example |
|
||||
|--------|---------|---------|
|
||||
| `--help` | Show help | `bootc internals --help` |
|
||||
| `--verbose` | Verbose output | `bootc internals fsck --verbose` |
|
||||
| `--quiet` | Quiet output | `bootc internals cleanup --quiet` |
|
||||
|
||||
## Quick Commands
|
||||
|
||||
### System Maintenance
|
||||
```bash
|
||||
# Daily maintenance
|
||||
bootc internals fsck && bootc internals cleanup
|
||||
|
||||
# Check system status
|
||||
bootc status
|
||||
|
||||
# Check storage usage
|
||||
df -h /var/lib/bootc
|
||||
```
|
||||
|
||||
### Development
|
||||
```bash
|
||||
# Test composefs
|
||||
bootc internals test-composefs
|
||||
|
||||
# Test loopback device
|
||||
bootc internals allocate-cleanup-loopback --file-path /tmp/test.img
|
||||
|
||||
# Test directory diff
|
||||
bootc internals dir-diff /tmp/pristine /tmp/current /tmp/new --perform-merge
|
||||
```
|
||||
|
||||
### Debugging
|
||||
```bash
|
||||
# Enable debug logging
|
||||
RUST_LOG=debug bootc internals fsck
|
||||
|
||||
# Check systemd services
|
||||
systemctl status bootc-*
|
||||
|
||||
# Check logs
|
||||
journalctl -u bootc-* --since "1 hour ago"
|
||||
```
|
||||
|
||||
### Systemd Integration
|
||||
```bash
|
||||
# Generate units
|
||||
bootc internals systemd-generator /run/systemd/system
|
||||
|
||||
# Fix fstab
|
||||
bootc internals fixup-etc-fstab
|
||||
|
||||
# Reload systemd
|
||||
systemctl daemon-reload
|
||||
```
|
||||
|
||||
### Proxy Commands
|
||||
```bash
|
||||
# OSTree operations
|
||||
bootc internals ostree-ext container pull quay.io/myorg/image:latest
|
||||
|
||||
# Composefs operations
|
||||
bootc internals cfs create-fs myimage /tmp/output
|
||||
|
||||
# Legacy ostree container
|
||||
bootc internals ostree-container pull quay.io/myorg/image:latest
|
||||
```
|
||||
|
||||
## Error Codes
|
||||
|
||||
| Code | Meaning | Solution |
|
||||
|------|---------|----------|
|
||||
| 1 | General error | Check logs for details |
|
||||
| 2 | Permission denied | Run as root |
|
||||
| 3 | Resource error | Check storage/memory |
|
||||
| 4 | Configuration error | Check configuration files |
|
||||
| 5 | System error | Check system status |
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Permission Denied
|
||||
```bash
|
||||
# Check user
|
||||
whoami
|
||||
|
||||
# Run as root
|
||||
sudo bootc internals <command>
|
||||
```
|
||||
|
||||
### Storage Full
|
||||
```bash
|
||||
# Check usage
|
||||
df -h /var/lib/bootc
|
||||
|
||||
# Clean up
|
||||
bootc internals cleanup
|
||||
|
||||
# Remove old deployments
|
||||
ostree admin cleanup
|
||||
```
|
||||
|
||||
### Systemd Issues
|
||||
```bash
|
||||
# Check status
|
||||
systemctl status bootc-*
|
||||
|
||||
# Reload configuration
|
||||
systemctl daemon-reload
|
||||
|
||||
# Restart services
|
||||
systemctl restart bootc-*
|
||||
```
|
||||
|
||||
### Filesystem Errors
|
||||
```bash
|
||||
# Check integrity
|
||||
bootc internals fsck
|
||||
|
||||
# Repair if needed
|
||||
ostree fsck --repair
|
||||
|
||||
# Restore from backup
|
||||
ostree admin deploy --from-commit <backup>
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Purpose | Default |
|
||||
|----------|---------|---------|
|
||||
| `RUST_LOG` | Log level | `info` |
|
||||
| `BOOTC_DEBUG` | Debug mode | `false` |
|
||||
| `BOOTC_CONFIG` | Config file | `/etc/bootc/config.toml` |
|
||||
|
||||
## Configuration Files
|
||||
|
||||
| File | Purpose | Location |
|
||||
|------|---------|----------|
|
||||
| Main config | Bootc configuration | `/etc/bootc/config.toml` |
|
||||
| Systemd units | Generated units | `/run/systemd/system/` |
|
||||
| OSTree repo | Repository data | `/var/lib/bootc/ostree/` |
|
||||
| Composefs repo | Composefs data | `/var/lib/bootc/composefs/` |
|
||||
|
||||
## Log Files
|
||||
|
||||
| File | Purpose | Location |
|
||||
|------|---------|----------|
|
||||
| System logs | System messages | `/var/log/messages` |
|
||||
| Journal logs | Systemd journal | `journalctl -u bootc-*` |
|
||||
| Bootc logs | Bootc specific | `/var/log/bootc/` |
|
||||
|
||||
## Performance Tips
|
||||
|
||||
### Optimize Storage
|
||||
```bash
|
||||
# Regular cleanup
|
||||
bootc internals cleanup
|
||||
|
||||
# Compress repository
|
||||
ostree admin cleanup --compress
|
||||
|
||||
# Remove old deployments
|
||||
ostree admin cleanup --keep=3
|
||||
```
|
||||
|
||||
### Optimize Performance
|
||||
```bash
|
||||
# Check system load
|
||||
uptime
|
||||
|
||||
# Check memory usage
|
||||
free -h
|
||||
|
||||
# Check disk I/O
|
||||
iotop
|
||||
```
|
||||
|
||||
### Monitor System
|
||||
```bash
|
||||
# Check system status
|
||||
bootc status
|
||||
|
||||
# Check filesystem integrity
|
||||
bootc internals fsck
|
||||
|
||||
# Check storage usage
|
||||
df -h /var/lib/bootc
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Root Privileges
|
||||
- All internals commands require root privileges
|
||||
- Use `sudo` or switch to root user
|
||||
- Check current user with `whoami`
|
||||
|
||||
### Input Validation
|
||||
- All paths are validated for security
|
||||
- Path traversal attacks are prevented
|
||||
- Absolute paths are required
|
||||
|
||||
### Resource Limits
|
||||
- Memory usage is limited
|
||||
- CPU usage is monitored
|
||||
- Storage usage is tracked
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Regular Maintenance
|
||||
- Run `fsck` daily
|
||||
- Run `cleanup` weekly
|
||||
- Monitor storage usage
|
||||
- Check system logs
|
||||
|
||||
### Development
|
||||
- Use test environments
|
||||
- Test commands before production
|
||||
- Document custom usage
|
||||
- Monitor system health
|
||||
|
||||
### Production
|
||||
- Set up monitoring
|
||||
- Configure alerts
|
||||
- Regular backups
|
||||
- Document procedures
|
||||
|
||||
## Troubleshooting Steps
|
||||
|
||||
1. **Check system status**
|
||||
```bash
|
||||
bootc status
|
||||
systemctl status bootc-*
|
||||
```
|
||||
|
||||
2. **Check logs**
|
||||
```bash
|
||||
journalctl -u bootc-* --since "1 hour ago"
|
||||
tail -f /var/log/bootc/main.log
|
||||
```
|
||||
|
||||
3. **Check resources**
|
||||
```bash
|
||||
df -h /var/lib/bootc
|
||||
free -h
|
||||
uptime
|
||||
```
|
||||
|
||||
4. **Run diagnostics**
|
||||
```bash
|
||||
bootc internals fsck
|
||||
bootc internals cleanup
|
||||
```
|
||||
|
||||
5. **Check configuration**
|
||||
```bash
|
||||
cat /etc/bootc/config.toml
|
||||
systemctl daemon-reload
|
||||
```
|
||||
|
||||
## Quick Scripts
|
||||
|
||||
### Health Check
|
||||
```bash
|
||||
#!/bin/bash
|
||||
bootc status && bootc internals fsck && echo "System healthy"
|
||||
```
|
||||
|
||||
### Maintenance
|
||||
```bash
|
||||
#!/bin/bash
|
||||
bootc internals fsck && bootc internals cleanup && echo "Maintenance complete"
|
||||
```
|
||||
|
||||
### Monitoring
|
||||
```bash
|
||||
#!/bin/bash
|
||||
df -h /var/lib/bootc | tail -1 | awk '{print $5}' | sed 's/%//'
|
||||
```
|
||||
|
||||
This quick reference provides essential information for using the bootc internals system effectively.
|
||||
543
internals/bootc-internals-technical-guide.md
Normal file
543
internals/bootc-internals-technical-guide.md
Normal file
|
|
@ -0,0 +1,543 @@
|
|||
# bootc internals - Technical Guide
|
||||
|
||||
## Overview
|
||||
|
||||
`bootc internals` is a hidden command that provides internal-only operations for system maintenance, debugging, and integration with other tools. These commands are not intended for regular users but are essential for system administrators, developers, and automated tooling.
|
||||
|
||||
## Purpose
|
||||
|
||||
The internals commands serve several critical functions:
|
||||
|
||||
1. **System Maintenance**: Low-level system operations and cleanup
|
||||
2. **Integration**: Proxy frontends for other tools and services
|
||||
3. **Debugging**: Testing and diagnostic capabilities
|
||||
4. **Development**: Internal tooling and schema generation
|
||||
5. **Systemd Integration**: Generator and service management
|
||||
|
||||
## Command Structure
|
||||
|
||||
```rust
|
||||
pub(crate) enum InternalsOpts {
|
||||
SystemdGenerator { normal_dir, early_dir, late_dir },
|
||||
FixupEtcFstab,
|
||||
PrintJsonSchema { of: SchemaType },
|
||||
Fsverity(FsverityOpts),
|
||||
Fsck,
|
||||
Cleanup,
|
||||
Relabel { as_path, path },
|
||||
OstreeExt { args },
|
||||
Cfs { args },
|
||||
OstreeContainer { args },
|
||||
TestComposefs,
|
||||
LoopbackCleanupHelper { device },
|
||||
AllocateCleanupLoopback { file_path },
|
||||
BootcInstallCompletion { sysroot, stateroot },
|
||||
Reboot,
|
||||
PublishRhsmFacts, // Feature-gated
|
||||
DumpCliJson, // Feature-gated
|
||||
DirDiff { pristine_etc, current_etc, new_etc, perform_merge },
|
||||
}
|
||||
```
|
||||
|
||||
## Core Commands
|
||||
|
||||
### 1. Systemd Generator
|
||||
|
||||
**Purpose**: Generate systemd units for bootc integration
|
||||
**Usage**: `bootc internals systemd-generator <normal_dir> [early_dir] [late_dir]`
|
||||
|
||||
```rust
|
||||
InternalsOpts::SystemdGenerator {
|
||||
normal_dir: Utf8PathBuf,
|
||||
early_dir: Option<Utf8PathBuf>,
|
||||
late_dir: Option<Utf8PathBuf>,
|
||||
} => {
|
||||
let unit_dir = &Dir::open_ambient_dir(normal_dir, cap_std::ambient_authority())?;
|
||||
crate::generator::generator(root, unit_dir)
|
||||
}
|
||||
```
|
||||
|
||||
**Functionality**:
|
||||
- Generates systemd units for bootc services
|
||||
- Handles fstab editing for composefs systems
|
||||
- Creates bootc-fstab-edit.service when needed
|
||||
- Integrates with systemd's generator system
|
||||
|
||||
**Implementation**:
|
||||
```rust
|
||||
pub(crate) fn fstab_generator_impl(root: &Dir, unit_dir: &Dir) -> Result<bool> {
|
||||
// Check if system is ostree-booted
|
||||
if !is_ostree_booted_in(root)? {
|
||||
return Ok(false);
|
||||
}
|
||||
|
||||
// Check /etc/fstab for anaconda stamp
|
||||
if let Some(fd) = root.open_optional("etc/fstab")? {
|
||||
let mut from_anaconda = false;
|
||||
for line in fd.lines() {
|
||||
let line = line?;
|
||||
if line.contains(BOOTC_EDITED_STAMP) {
|
||||
return Ok(false); // Already processed
|
||||
}
|
||||
if line.contains(FSTAB_ANACONDA_STAMP) {
|
||||
from_anaconda = true;
|
||||
}
|
||||
}
|
||||
|
||||
if from_anaconda {
|
||||
generate_fstab_editor(unit_dir)?;
|
||||
return Ok(true);
|
||||
}
|
||||
}
|
||||
Ok(false)
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Filesystem Consistency Check (Fsck)
|
||||
|
||||
**Purpose**: Perform consistency checking on bootc systems
|
||||
**Usage**: `bootc internals fsck`
|
||||
|
||||
```rust
|
||||
InternalsOpts::Fsck => {
|
||||
let sysroot = &get_storage().await?;
|
||||
crate::fsck::fsck(&sysroot, std::io::stdout().lock()).await?;
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
**Functionality**:
|
||||
- Validates OSTree repository integrity
|
||||
- Checks composefs repository consistency
|
||||
- Verifies deployment states
|
||||
- Validates system configuration
|
||||
|
||||
**Implementation**:
|
||||
```rust
|
||||
pub async fn fsck(sysroot: &Storage, mut out: impl Write) -> Result<()> {
|
||||
let ostree = sysroot.get_ostree()?;
|
||||
let repo = ostree.repo();
|
||||
|
||||
// Run all registered fsck checks
|
||||
for check in FSCK_CHECKS {
|
||||
match check(sysroot).await {
|
||||
Ok(Ok(())) => writeln!(out, "✓ {}", check.name())?,
|
||||
Ok(Err(e)) => writeln!(out, "✗ {}: {}", check.name(), e)?,
|
||||
Err(e) => writeln!(out, "✗ {}: {}", check.name(), e)?,
|
||||
}
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Cleanup Operations
|
||||
|
||||
**Purpose**: Perform cleanup actions on bootc systems
|
||||
**Usage**: `bootc internals cleanup`
|
||||
|
||||
```rust
|
||||
InternalsOpts::Cleanup => {
|
||||
let sysroot = get_storage().await?;
|
||||
crate::deploy::cleanup(&sysroot).await
|
||||
}
|
||||
```
|
||||
|
||||
**Functionality**:
|
||||
- Remove old deployments
|
||||
- Clean up unused container images
|
||||
- Garbage collect OSTree repository
|
||||
- Remove temporary files
|
||||
|
||||
### 4. Filesystem Verity (Fsverity)
|
||||
|
||||
**Purpose**: Manage fsverity integrity verification
|
||||
**Usage**: `bootc internals fsverity <subcommand>`
|
||||
|
||||
```rust
|
||||
pub(crate) enum FsverityOpts {
|
||||
Measure { path: Utf8PathBuf },
|
||||
Enable { path: Utf8PathBuf },
|
||||
}
|
||||
|
||||
// Implementation
|
||||
InternalsOpts::Fsverity(args) => match args {
|
||||
FsverityOpts::Measure { path } => {
|
||||
let fd = std::fs::File::open(&path)?;
|
||||
let digest: fsverity::Sha256HashValue = fsverity::measure_verity(&fd)?;
|
||||
println!("{}", digest.to_hex());
|
||||
Ok(())
|
||||
}
|
||||
FsverityOpts::Enable { path } => {
|
||||
let fd = std::fs::File::open(&path)?;
|
||||
fsverity::enable_verity_raw::<fsverity::Sha256HashValue>(&fd)?;
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Subcommands**:
|
||||
- **`measure`**: Calculate fsverity digest of a file
|
||||
- **`enable`**: Enable fsverity verification on a file
|
||||
|
||||
### 5. Proxy Commands
|
||||
|
||||
#### OstreeExt Proxy
|
||||
**Purpose**: Proxy frontend for `ostree-ext` CLI
|
||||
**Usage**: `bootc internals ostree-ext [args...]`
|
||||
|
||||
```rust
|
||||
InternalsOpts::OstreeExt { args } => {
|
||||
ostree_ext::cli::run_from_iter(["ostree-ext".into()].into_iter().chain(args)).await
|
||||
}
|
||||
```
|
||||
|
||||
#### Cfs Proxy
|
||||
**Purpose**: Proxy frontend for `cfsctl` CLI
|
||||
**Usage**: `bootc internals cfs [args...]`
|
||||
|
||||
```rust
|
||||
InternalsOpts::Cfs { args } => {
|
||||
crate::cfsctl::run_from_iter(args.iter()).await
|
||||
}
|
||||
```
|
||||
|
||||
#### OstreeContainer Proxy
|
||||
**Purpose**: Proxy frontend for legacy `ostree container` CLI
|
||||
**Usage**: `bootc internals ostree-container [args...]`
|
||||
|
||||
```rust
|
||||
InternalsOpts::OstreeContainer { args } => {
|
||||
ostree_ext::cli::run_from_iter(
|
||||
["ostree-ext".into(), "container".into()]
|
||||
.into_iter()
|
||||
.chain(args),
|
||||
).await
|
||||
}
|
||||
```
|
||||
|
||||
### 6. System Maintenance
|
||||
|
||||
#### Fixup /etc/fstab
|
||||
**Purpose**: Fix /etc/fstab for composefs systems
|
||||
**Usage**: `bootc internals fixup-etc-fstab`
|
||||
|
||||
```rust
|
||||
InternalsOpts::FixupEtcFstab => {
|
||||
crate::deploy::fixup_etc_fstab(&root)
|
||||
}
|
||||
```
|
||||
|
||||
#### Relabel
|
||||
**Purpose**: SELinux relabeling
|
||||
**Usage**: `bootc internals relabel --as-path <path> <target_path>`
|
||||
|
||||
```rust
|
||||
InternalsOpts::Relabel { as_path, path } => {
|
||||
let root = &Dir::open_ambient_dir("/", cap_std::ambient_authority())?;
|
||||
let path = path.strip_prefix("/")?;
|
||||
let sepolicy = &ostree::SePolicy::new(&gio::File::for_path("/"), gio::Cancellable::NONE)?;
|
||||
crate::lsm::relabel_recurse(root, path, as_path.as_deref(), sepolicy)?;
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 7. Testing and Development
|
||||
|
||||
#### Test Composefs
|
||||
**Purpose**: Ensure composefs repository is initialized
|
||||
**Usage**: `bootc internals test-composefs`
|
||||
|
||||
```rust
|
||||
InternalsOpts::TestComposefs => {
|
||||
let storage = get_storage().await?;
|
||||
let cfs = storage.get_ensure_composefs()?;
|
||||
let testdata = b"some test data";
|
||||
let testdata_digest = openssl::sha::sha256(testdata);
|
||||
let mut w = SplitStreamWriter::new(&cfs, None, Some(testdata_digest));
|
||||
w.write_inline(testdata);
|
||||
let object = cfs.write_stream(w, Some("testobject"))?.to_hex();
|
||||
// Verify expected digest
|
||||
assert_eq!(object, "expected_digest");
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
#### Loopback Device Management
|
||||
**Purpose**: Manage loopback devices for testing
|
||||
**Usage**:
|
||||
- `bootc internals loopback-cleanup-helper --device <device>`
|
||||
- `bootc internals allocate-cleanup-loopback --file-path <path>`
|
||||
|
||||
```rust
|
||||
InternalsOpts::LoopbackCleanupHelper { device } => {
|
||||
crate::blockdev::run_loopback_cleanup_helper(&device).await
|
||||
}
|
||||
|
||||
InternalsOpts::AllocateCleanupLoopback { file_path: _ } => {
|
||||
let temp_file = tempfile::NamedTempFile::new()?;
|
||||
let temp_path = temp_file.path();
|
||||
|
||||
let loopback = crate::blockdev::LoopbackDevice::new(temp_path)?;
|
||||
println!("Created loopback device: {}", loopback.path());
|
||||
|
||||
// Cleanup
|
||||
drop(loopback);
|
||||
println!("Successfully closed loopback device");
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 8. Installation Completion
|
||||
|
||||
**Purpose**: Complete installation from ostree-ext
|
||||
**Usage**: `bootc internals bootc-install-completion --sysroot <path> --stateroot <name>`
|
||||
|
||||
```rust
|
||||
InternalsOpts::BootcInstallCompletion { sysroot, stateroot } => {
|
||||
let rootfs = &Dir::open_ambient_dir("/", cap_std::ambient_authority())?;
|
||||
crate::install::completion::run_from_ostree(rootfs, &sysroot, &stateroot).await
|
||||
}
|
||||
```
|
||||
|
||||
### 9. System Operations
|
||||
|
||||
#### Reboot
|
||||
**Purpose**: Initiate reboot (for testing)
|
||||
**Usage**: `bootc internals reboot`
|
||||
|
||||
```rust
|
||||
InternalsOpts::Reboot => {
|
||||
crate::reboot::reboot()
|
||||
}
|
||||
```
|
||||
|
||||
#### Print JSON Schema
|
||||
**Purpose**: Generate JSON schemas (for development)
|
||||
**Usage**: `bootc internals print-json-schema --of <type>`
|
||||
|
||||
```rust
|
||||
InternalsOpts::PrintJsonSchema { of } => {
|
||||
let schema = match of {
|
||||
SchemaType::Host => schema_for!(crate::spec::Host),
|
||||
SchemaType::Progress => schema_for!(crate::progress_jsonl::Event),
|
||||
};
|
||||
let mut stdout = std::io::stdout().lock();
|
||||
serde_json::to_writer_pretty(&mut stdout, &schema)?;
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 10. Feature-Gated Commands
|
||||
|
||||
#### RHSM Facts Publishing
|
||||
**Purpose**: Publish subscription-manager facts
|
||||
**Usage**: `bootc internals publish-rhsm-facts` (requires `rhsm` feature)
|
||||
|
||||
```rust
|
||||
#[cfg(feature = "rhsm")]
|
||||
InternalsOpts::PublishRhsmFacts => {
|
||||
crate::rhsm::publish_facts(&root).await
|
||||
}
|
||||
```
|
||||
|
||||
#### CLI JSON Dump
|
||||
**Purpose**: Dump CLI structure as JSON
|
||||
**Usage**: `bootc internals dump-cli-json` (requires `docgen` feature)
|
||||
|
||||
```rust
|
||||
#[cfg(feature = "docgen")]
|
||||
InternalsOpts::DumpCliJson => {
|
||||
use clap::CommandFactory;
|
||||
let cmd = Opt::command();
|
||||
let json = crate::cli_json::dump_cli_json(&cmd)?;
|
||||
println!("{}", json);
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 11. Directory Diff Testing
|
||||
|
||||
**Purpose**: Test etc-diff/etc-merge functionality
|
||||
**Usage**: `bootc internals dir-diff <pristine_etc> <current_etc> <new_etc> [--perform-merge]`
|
||||
|
||||
```rust
|
||||
InternalsOpts::DirDiff {
|
||||
pristine_etc,
|
||||
current_etc,
|
||||
new_etc,
|
||||
perform_merge,
|
||||
} => {
|
||||
// Test 3-way merge functionality
|
||||
let pristine_dir = Dir::open_ambient_dir(&pristine_etc, cap_std::ambient_authority())?;
|
||||
let current_dir = Dir::open_ambient_dir(¤t_etc, cap_std::ambient_authority())?;
|
||||
let new_dir = Dir::open_ambient_dir(&new_etc, cap_std::ambient_authority())?;
|
||||
|
||||
let (pristine_files, current_files, new_files) =
|
||||
traverse_etc(&pristine_dir, ¤t_dir, &new_dir)?;
|
||||
|
||||
if perform_merge {
|
||||
let diff = compute_diff(&pristine_files, ¤t_files)?;
|
||||
merge(¤t_dir, ¤t_files, &new_dir, &new_files, diff)?;
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
### 1. Command Routing
|
||||
|
||||
The internals commands are routed through the main CLI dispatcher:
|
||||
|
||||
```rust
|
||||
match opt {
|
||||
Opt::Internals(opts) => match opts {
|
||||
InternalsOpts::SystemdGenerator { ... } => { ... }
|
||||
InternalsOpts::Fsck => { ... }
|
||||
InternalsOpts::Cleanup => { ... }
|
||||
// ... other commands
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Error Handling
|
||||
|
||||
All internals commands use consistent error handling:
|
||||
|
||||
```rust
|
||||
#[context("Operation name")]
|
||||
pub(crate) fn operation() -> Result<()> {
|
||||
// Implementation with proper error context
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Integration Points
|
||||
|
||||
- **Systemd**: Generator integration for service management
|
||||
- **OSTree**: Direct OSTree operations and repository management
|
||||
- **Composefs**: Composefs repository operations
|
||||
- **SELinux**: Security labeling and policy enforcement
|
||||
- **Filesystem**: Low-level filesystem operations
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### 1. Privilege Requirements
|
||||
|
||||
Most internals commands require root privileges:
|
||||
|
||||
```rust
|
||||
pub(crate) fn require_root(is_container: bool) -> Result<()> {
|
||||
ensure!(
|
||||
rustix::process::getuid().is_root(),
|
||||
if is_container {
|
||||
"The user inside the container from which you are running this command must be root"
|
||||
} else {
|
||||
"This command must be executed as the root user"
|
||||
}
|
||||
);
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Hidden Commands
|
||||
|
||||
All internals commands are hidden from help output:
|
||||
|
||||
```rust
|
||||
#[clap(subcommand)]
|
||||
#[clap(hide = true)]
|
||||
Internals(InternalsOpts),
|
||||
```
|
||||
|
||||
### 3. Internal Use Only
|
||||
|
||||
Commands are marked as internal-only and not intended for regular users.
|
||||
|
||||
## Performance Characteristics
|
||||
|
||||
### 1. Systemd Generator
|
||||
|
||||
- **Fast**: Minimal overhead during boot
|
||||
- **Conditional**: Only runs when needed
|
||||
- **Efficient**: Direct filesystem operations
|
||||
|
||||
### 2. Fsck Operations
|
||||
|
||||
- **Comprehensive**: Checks all system components
|
||||
- **Parallel**: Can run multiple checks concurrently
|
||||
- **Detailed**: Provides specific error information
|
||||
|
||||
### 3. Cleanup Operations
|
||||
|
||||
- **Safe**: Only removes confirmed unused data
|
||||
- **Efficient**: Batch operations where possible
|
||||
- **Atomic**: Operations are atomic where possible
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### 1. Common Issues
|
||||
|
||||
#### Generator Not Running
|
||||
```bash
|
||||
# Check systemd generator status
|
||||
systemctl status bootc-systemd-generator
|
||||
|
||||
# Check generator logs
|
||||
journalctl -u bootc-systemd-generator
|
||||
```
|
||||
|
||||
#### Fsck Failures
|
||||
```bash
|
||||
# Run fsck manually
|
||||
bootc internals fsck
|
||||
|
||||
# Check specific components
|
||||
bootc internals fsck --component ostree
|
||||
```
|
||||
|
||||
#### Cleanup Issues
|
||||
```bash
|
||||
# Run cleanup manually
|
||||
bootc internals cleanup
|
||||
|
||||
# Check storage usage
|
||||
df -h /sysroot
|
||||
```
|
||||
|
||||
### 2. Debug Commands
|
||||
|
||||
```bash
|
||||
# Enable debug logging
|
||||
RUST_LOG=debug bootc internals <command>
|
||||
|
||||
# Check system state
|
||||
bootc status
|
||||
|
||||
# Verify system integrity
|
||||
bootc internals fsck
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Usage Guidelines
|
||||
|
||||
- **Internal Only**: Don't use in production scripts
|
||||
- **Root Required**: Always run as root
|
||||
- **Testing**: Use in test environments first
|
||||
- **Documentation**: Document any custom usage
|
||||
|
||||
### 2. Integration Patterns
|
||||
|
||||
- **Systemd**: Use generators for service integration
|
||||
- **Monitoring**: Use fsck for health checks
|
||||
- **Maintenance**: Use cleanup for storage management
|
||||
- **Development**: Use test commands for validation
|
||||
|
||||
### 3. Error Handling
|
||||
|
||||
- **Logging**: Always check logs for errors
|
||||
- **Recovery**: Have recovery procedures ready
|
||||
- **Testing**: Test commands before production use
|
||||
- **Monitoring**: Monitor system health after operations
|
||||
|
||||
This technical guide provides comprehensive understanding of the bootc internals system's architecture, implementation, and usage patterns.
|
||||
Loading…
Add table
Add a link
Reference in a new issue