1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
//! Command-line definitions for `byssusd` and `byssus`.
//!
//! Kept in the library so the binaries and the man page generator share one
//! source: the manual pages in `contrib/man/` are generated from these
//! definitions and checked against them by a unit test.
// Doc comments double as `--help` text, where Markdown backticks would show.
#![allow(clippy::doc_markdown)]
/// `byssusd`, the daemon.
pub mod byssusd {
use std::path::PathBuf;
use clap::Parser;
use crate::logging::LogLevel;
/// Byssus daemon: reconciles bind mounts from membership directories.
///
/// byssusd watches the membership directories of every configured group
/// and group set, and creates and removes bind mounts (read-only by
/// default) beneath each target root, so consumers attached to a view see
/// members appear and disappear. It keeps only CAP_SYS_ADMIN, and switches
/// to the service user (daemon.user) when started as root.
///
/// Signals: SIGHUP reloads the configuration, keeping the previous one if
/// the new configuration is invalid. SIGTERM or SIGINT stops the daemon;
/// mounts are preserved.
///
/// Files (defaults): /etc/byssus/byssus.toml and /etc/byssus/conf.d/*.toml
/// (configuration); /var/lib/byssus/state.json (state).
///
/// Exit status: 0 after a clean shutdown, 1 if startup fails.
///
/// See also byssus(8), and REFERENCE.md and OPERATIONS.md in
/// /usr/share/doc/byssus.
#[derive(Debug, Parser)]
#[command(name = "byssusd", version)]
pub struct Cli {
/// Main configuration file [default: /etc/byssus/byssus.toml].
#[arg(long, value_name = "FILE")]
pub config: Option<PathBuf>,
/// Drop-in configuration directory [default: /etc/byssus/conf.d].
#[arg(long, value_name = "DIR")]
pub config_dir: Option<PathBuf>,
/// Log level: error, warn, info, debug, trace.
#[arg(long, value_name = "LEVEL", default_value = "info")]
pub log_level: LogLevel,
/// Service user to switch to when started as root (overrides daemon.user).
#[arg(long, value_name = "USER")]
pub user: Option<String>,
/// Permit running as UID 0 without a service user (development and tests).
#[arg(long)]
pub allow_root: bool,
/// Permit target roots on slave mounts (normally a sign that the
/// daemon runs in a non-host mount namespace).
#[arg(long)]
pub allow_slave_namespace: bool,
}
}
/// `byssus`, the command-line tool.
pub mod byssus {
use std::path::PathBuf;
use clap::{Args, Parser, Subcommand, ValueEnum};
use crate::app::ConfigSource;
use crate::logging::LogLevel;
/// Byssus command-line tool: inspect, validate and reconcile mounts.
///
/// status, dry-run and check never mount anything; run as root with
/// daemon.user configured, they look as that user, as the daemon would.
/// reconcile performs one reconciliation pass and needs CAP_SYS_ADMIN.
///
/// See also byssusd(8), and REFERENCE.md and OPERATIONS.md in
/// /usr/share/doc/byssus.
#[derive(Debug, Parser)]
#[command(name = "byssus", version)]
pub struct Cli {
#[command(flatten)]
pub config: ConfigArgs,
/// Log level for diagnostics on stderr: error, warn, info, debug, trace.
#[arg(long, global = true, value_name = "LEVEL")]
pub log_level: Option<LogLevel>,
#[command(subcommand)]
pub command: Command,
}
#[derive(Debug, Args)]
pub struct ConfigArgs {
/// Main configuration file [default: /etc/byssus/byssus.toml].
#[arg(long, global = true, value_name = "FILE")]
pub config: Option<PathBuf>,
/// Drop-in configuration directory [default: /etc/byssus/conf.d].
#[arg(long, global = true, value_name = "DIR")]
pub config_dir: Option<PathBuf>,
}
impl ConfigArgs {
/// The configuration locations these arguments select.
#[must_use]
pub fn source(&self) -> ConfigSource {
ConfigSource {
file: self.config.clone(),
dir: self.config_dir.clone(),
}
}
}
#[derive(Debug, Clone, Copy, ValueEnum)]
pub enum Format {
Text,
Json,
}
#[derive(Debug, Subcommand)]
pub enum Command {
/// Show every desired or recorded member and its mount state.
///
/// Exits 1 if any member is in an error state.
Status {
/// Output format.
#[arg(long, value_enum, default_value_t = Format::Text)]
format: Format,
},
/// Validate configuration, kernel, permissions and propagation, and show
/// what a reconcile would do, without mounting anything.
///
/// When run as root with a service user configured, checks run as that
/// user. Exits 1 if any check fails.
DryRun {
/// Output format.
#[arg(long, value_enum, default_value_t = Format::Text)]
format: Format,
},
/// Perform one reconciliation pass and exit. Requires CAP_SYS_ADMIN and
/// refuses to run while byssusd holds the state lock.
Reconcile {
#[command(flatten)]
privileges: PrivilegeArgs,
},
/// Check whether the configuration would be accepted by a reload,
/// optionally with drop-in fragments added, replaced or removed, without
/// installing anything or signaling the daemon.
///
/// Runs the same validation as a SIGHUP reload: parsing, ownership and
/// modes, cross-group rules, paths, opening every root and membership
/// directory, watches and propagation. When run as root with a service
/// user configured, access is checked as that user. Exits 0 if the
/// configuration would be accepted, 1 otherwise.
Check {
/// Candidate drop-in fragment, treated as installed in the drop-in
/// directory under its file name (replacing a fragment of that name).
/// May be repeated.
#[arg(long = "add", value_name = "FILE")]
add: Vec<PathBuf>,
/// File name of an installed drop-in fragment to leave out. May be
/// repeated.
#[arg(long = "remove", value_name = "NAME")]
remove: Vec<String>,
/// Treat target roots on slave mounts as acceptable (as byssusd
/// --allow-slave-namespace would).
#[arg(long)]
allow_slave_namespace: bool,
/// Output format.
#[arg(long, value_enum, default_value_t = Format::Text)]
format: Format,
},
/// Print the version.
Version,
}
#[derive(Debug, Args)]
pub struct PrivilegeArgs {
/// Service user to switch to when started as root (overrides daemon.user).
#[arg(long, value_name = "USER")]
pub user: Option<String>,
/// Permit running as UID 0 without a service user (development and tests).
#[arg(long)]
pub allow_root: bool,
/// Permit target roots on slave mounts.
#[arg(long)]
pub allow_slave_namespace: bool,
}
}
#[cfg(test)]
mod tests {
use std::fs;
use std::path::Path;
use clap::CommandFactory as _;
const UPDATE_HINT: &str = "regenerate with: BYSSUS_UPDATE_MAN=1 cargo test --lib cli::";
/// Renders `cmd` and its visible subcommands as section 8 manual pages.
fn render(cmd: clap::Command, pages: &mut Vec<(String, Vec<u8>)>) {
for sub in cmd.get_subcommands().filter(|s| !s.is_hide_set()).cloned() {
render(sub, pages);
}
let man = clap_mangen::Man::new(cmd)
.section("8")
.source(format!("byssus {}", crate::VERSION))
.manual("Byssus Manual");
let mut page = Vec::new();
man.render(&mut page).expect("render man page");
pages.push((man.get_filename(), page));
}
fn pages() -> Vec<(String, Vec<u8>)> {
let mut pages = Vec::new();
for cmd in [
super::byssusd::Cli::command(),
super::byssus::Cli::command(),
] {
let mut cmd = cmd.disable_help_subcommand(true);
cmd.build();
render(cmd, &mut pages);
}
pages.sort();
pages
}
fn pages_on_disk(dir: &Path) -> Vec<String> {
let mut names: Vec<String> = fs::read_dir(dir)
.map(|entries| {
entries
.map(|e| e.unwrap().file_name().to_string_lossy().into_owned())
.filter(|name| name.ends_with(".8"))
.collect()
})
.unwrap_or_default();
names.sort();
names
}
#[test]
fn man_pages_match_cli_definitions() {
let dir = Path::new(env!("CARGO_MANIFEST_DIR")).join("contrib/man");
let pages = pages();
if std::env::var_os("BYSSUS_UPDATE_MAN").is_some() {
fs::create_dir_all(&dir).unwrap();
for stale in pages_on_disk(&dir) {
fs::remove_file(dir.join(stale)).unwrap();
}
for (name, page) in &pages {
fs::write(dir.join(name), page).unwrap();
}
}
let expected: Vec<String> = pages.iter().map(|(name, _)| name.clone()).collect();
assert_eq!(pages_on_disk(&dir), expected, "{UPDATE_HINT}");
for (name, page) in &pages {
assert!(
fs::read(dir.join(name)).unwrap() == *page,
"contrib/man/{name} is out of date; {UPDATE_HINT}"
);
}
}
}