116 lines
4.7 KiB
Markdown
116 lines
4.7 KiB
Markdown
---
|
|
status: proposed
|
|
date: 2025-02-28
|
|
story: 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:
|
|
|
|
1. Traditional Linux systems.
|
|
2. Containerized deployments (Docker).
|
|
3. 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](https://github.com/ZcashFoundation/zebra/issues/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/zebrad` or `/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/zebrad` or `/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 `/etc` and `/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
|
|
|
|
## More Information
|
|
|
|
* [Filesystem Hierarchy Standard (FHS) v3.0](https://refspecs.linuxfoundation.org/FHS_3.0/fhs-3.0.html)
|
|
* [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/latest/)
|
|
* [Zebra Issue #3432: Use the Filesystem Hierarchy Standard (FHS) for deployments and artifacts](https://github.com/ZcashFoundation/zebra/issues/3432)
|
|
* [Google Container-Optimized OS: Working with the File System](https://cloud.google.com/container-optimized-os/docs/concepts/disks-and-filesystem#working_with_the_file_system)
|