4.7 KiB
4.7 KiB
| status | date | story |
|---|---|---|
| proposed | 2025-02-28 | Standardize filesystem hierarchy for Zebra deployments |
Standardize Filesystem Hierarchy: FHS vs. XDG
Context & Problem Statement
Zebra currently has inconsistencies in its filesystem layout, particularly regarding where configuration, data, cache files, and binaries are stored. We need a standardized approach compatible with:
- Traditional Linux systems.
- Containerized deployments (Docker).
- Cloud environments with stricter filesystem restrictions (e.g., Google's Container-Optimized OS).
We previously considered using the Filesystem Hierarchy Standard (FHS) exclusively (Issue #3432). However, recent changes introduced the XDG Base Directory Specification, which offers a user-centric approach. We need to decide whether to:
- Adhere to FHS.
- Adopt XDG Base Directory Specification.
- Use a hybrid approach, leveraging the strengths of both.
The choice impacts how we structure our Docker images, where configuration files are located, and how users interact with Zebra in different environments.
Priorities & Constraints
- Security: Minimize the risk of privilege escalation by adhering to least-privilege principles.
- Maintainability: Ensure a clear and consistent filesystem layout that is easy to understand and maintain.
- Compatibility: Work seamlessly across various Linux distributions, Docker, and cloud environments (particularly those with restricted filesystems like Google's Container-Optimized OS).
- User Experience: Provide a predictable and user-friendly experience for locating configuration and data files.
- Flexibility: Allow users to override default locations via environment variables where appropriate.
- Avoid Breaking Changes: Minimize disruption to existing users and deployments, if possible.
Considered Options
Option 1: FHS
- Configuration:
/etc/zebrad/ - Data:
/var/lib/zebrad/ - Cache:
/var/cache/zebrad/ - Logs:
/var/log/zebrad/ - Binary:
/opt/zebra/bin/zebrador/usr/local/bin/zebrad
Option 2: XDG Base Directory Specification
- Configuration:
$HOME/.config/zebrad/ - Data:
$HOME/.local/share/zebrad/ - Cache:
$HOME/.cache/zebrad/ - State:
$HOME/.local/state/zebrad/ - Binary:
$HOME/.local/bin/zebrador/usr/local/bin/zebrad
Option 3: Hybrid Approach (FHS for System-Wide, XDG for User-Specific)
- System-wide configuration:
/etc/zebrad/ - User-specific configuration:
$XDG_CONFIG_HOME/zebrad/ - System-wide data (read-only, shared):
/usr/share/zebrad/(e.g., checkpoints) - User-specific data:
$XDG_DATA_HOME/zebrad/ - Cache:
$XDG_CACHE_HOME/zebrad/ - State:
$XDG_STATE_HOME/zebrad/ - Runtime:
$XDG_RUNTIME_DIR/zebrad/ - Binary:
/opt/zebra/bin/zebrad(system-wide) or$HOME/.local/bin/zebrad(user-specific)
Pros and Cons of the Options
FHS
-
Pros:
- Traditional and well-understood by system administrators.
- Clear separation of configuration, data, cache, and binaries.
- Suitable for packaged software installations.
-
Cons:
- Less user-friendly; requires root access to modify configuration.
- Can conflict with stricter cloud environments restricting writes to
/etcand/var. - Doesn't handle multi-user scenarios as gracefully as XDG.
XDG Base Directory Specification
-
Pros:
- User-centric: configuration and data stored in user-writable locations.
- Better suited for containerized and cloud environments.
- Handles multi-user scenarios gracefully.
- Clear separation of configuration, data, cache, and state.
-
Cons:
- Less traditional; might be unfamiliar to some system administrators.
- Requires environment variables to be set correctly.
- Binary placement less standardized.
Hybrid Approach (FHS for System-Wide, XDG for User-Specific)
-
Pros:
- Combines strengths of FHS and XDG.
- Allows system-wide defaults while prioritizing user-specific configurations.
- Flexible and adaptable to different deployment scenarios.
- Clear binary placement in
/opt.
-
Cons:
- More complex than either FHS or XDG alone.
- Requires careful consideration of precedence rules.
Decision Outcome
Pending
Expected Consequences
Pending