已开启
sync: sync improvements from openEuler-24.03-LTS-SP4 to master #14
sync: sync improvements from openEuler-24.03-LTS-SP4 to master #14
已开启
wuxingyi创建于 9月17日
共 9 个文件变更+1286-1
@@ -0,0 +1,251 @@
1+.\" Copyright (c) 2023-2026 ChinaUnicom / fastblock contributors
2+.\" Licensed under Mulan PSL v2.
3+.TH FASTBLOCK-CLIENT 8 "2026-07-21" "fastblock 0.1" "System Administration"
4+.SH NAME
5+fastblock-client \- administrative client for fastblock monitors
6+.SH SYNOPSIS
7+.B fastblock-client
8+.RB [ \-conf= path ]
9+.BI \-op= operation
10+.RI [ options... ]
11+.PP
12+.B fastblock-client
13+.RB [ \-conf= path ]
14+.BR \-set= noReblance | noout
15+.PP
16+.B fastblock-client
17+.RB [ \-conf= path ]
18+.BR \-unset= noReblance | noout
19+.SH DESCRIPTION
20+.B fastblock-client
21+connects to a
22+.BR fastblock-mon (8)
23+control endpoint and issues cluster management requests: pool and image
24+lifecycle, map queries, OSD in/out, cluster status, and a set of fake/test
25+helpers used in development environments.
26+.PP
27+The client loads
28+.I /etc/fastblock/fastblock.json
29+by default (or the path given by
30+.BR \-conf )
31+using the built-in client identity
32+.BR fbclient ,
33+then dials the monitor address/port from that configuration.
34+.SH OPTIONS
35+.TP
36+.BI \-conf= path
37+Path to the JSON configuration file. Default:
38+.IR /etc/fastblock/fastblock.json .
39+.TP
40+.BI \-op= operation
41+Primary operation to perform. Supported values are listed in
42+.BR OPERATIONS .
43+Exactly one of
44+.BR \-op ,
45+.BR \-set ,
46+or
47+.B \-unset
48+must select a supported action.
49+.TP
50+.BI \-set= flag
51+Set a cluster flag. Supported:
52+.BR noReblance ,
53+.BR noout .
54+.TP
55+.BI \-unset= flag
56+Clear a cluster flag. Supported:
57+.BR noReblance ,
58+.BR noout .
59+.TP
60+.BI \-poolname= name
61+Pool name (create/delete/list-related image ops).
62+.TP
63+.BI \-poolid= id
64+Pool ID (for example with
65+.BR getpgosds ).
66+.TP
67+.BI \-pgcount= N
68+Number of PGs when creating a pool.
69+.TP
70+.BI \-pgsize= N
71+Replica size of a pool. Default: 3.
72+.TP
73+.BI \-failure_domain= domain
74+Failure domain for pool creation. Default:
75+.BR osd .
76+.TP
77+.BI \-imagename= name
78+Image name for image operations.
79+.TP
80+.BI \-imagesize= bytes
81+Image size in bytes. Must be at least 4\ MiB (4194304) for create/resize.
82+.TP
83+.BI \-objectsize= bytes
84+Object size for image creation. Default: 4194304 (4\ MiB).
85+.TP
86+.BI \-osdid= id
87+OSD identifier for operations such as
88+.BR outosd ,
89+.BR inosd ,
90+.BR fakestoposd ,
91+.BR showconfig .
92+.TP
93+.BI \-uuid= uuid
94+OSD UUID (required for some fake/apply operations).
95+.TP
96+.BI \-hostname= name
97+Hostname advertised when fake-booting an OSD. Default: localhost.
98+.TP
99+.BI \-address= ip
100+Address advertised when fake-booting an OSD. Default: 127.0.0.1.
101+.TP
102+.BI \-port= port
103+Port used with fake OSD boot helpers.
104+.TP
105+.BI \-size= bytes
106+Size value used with fake OSD boot helpers.
107+.TP
108+.BI \-osdcount= N
109+Number of OSDs for
110+.BR fakestartcluster .
111+.TP
112+.BI \-hostcount= N
113+Number of hosts for
114+.BR fakestartcluster .
115+.TP
116+.BI \-version= N
117+Map version hint for incremental map fetches. Default: \-1.
118+.TP
119+.B \-detail
120+Print additional detail where supported.
121+.SH OPERATIONS
122+Values for
123+.BR \-op :
124+.TP
125+.B createpool
126+Create a pool. Requires
127+.B \-poolname
128+and
129+.BR \-pgcount .
130+Optional:
131+.BR \-pgsize ,
132+.BR \-failure_domain .
133+.TP
134+.B deletepool
135+Delete a pool. Requires
136+.BR \-poolname .
137+.TP
138+.B listpools
139+List pools.
140+.TP
141+.B createimage
142+Create an image. Requires
143+.BR \-poolname ,
144+.BR \-imagename ,
145+and
146+.B \-imagesize
147+(>= 4\ MiB). Optional:
148+.BR \-objectsize .
149+.TP
150+.B removeimage
151+Remove an image. Requires
152+.B \-poolname
153+and
154+.BR \-imagename .
155+.TP
156+.B resizeimage
157+Resize an image. Requires
158+.BR \-imagename ,
159+.BR \-imagesize ,
160+and typically
161+.BR \-poolname .
162+.TP
163+.B getimage
164+Query image information.
165+.TP
166+.B getosdmap
167+Fetch the OSD map once.
168+.TP
169+.B getpgmap
170+Fetch the PG map once.
171+.TP
172+.B getclustermap
173+Fetch combined cluster map information once.
174+.TP
175+.B watchosdmap / watchpgmap / watchclustermap
176+Watch maps and print updates continuously.
177+.TP
178+.B getpgosds
179+Show PG to OSD placement; optional
180+.BR \-poolid .
181+.TP
182+.B outosd / inosd
183+Mark an OSD out or in. Requires
184+.BR \-osdid .
185+.TP
186+.B status
187+Show cluster status.
188+.TP
189+.B showconfig
190+Show OSD-related configuration from the monitor. Uses
191+.BR \-osdid .
192+.TP
193+.B fakeapplyid / fakebootosd / fakestoposd / fakestartcluster
194+Development helpers for simulating OSD identity application, boot, stop, or
195+bulk fake cluster start. These are intended for test environments, not general
196+production administration.
197+.SH EXAMPLES
198+Create a 3-replica pool with 64 PGs:
199+.PP
200+.RS
201+.nf
202+fastblock-client \-conf=/etc/fastblock/fastblock.json \\
203+ \-op=createpool \-poolname=rbd \-pgcount=64 \-pgsize=3
204+.fi
205+.RE
206+.PP
207+Create a 10\ GiB image:
208+.PP
209+.RS
210+.nf
211+fastblock-client \-op=createimage \-poolname=rbd \\
212+ \-imagename=vol01 \-imagesize=10737418240
213+.fi
214+.RE
215+.PP
216+Show cluster status:
217+.PP
218+.RS
219+.nf
220+fastblock-client \-op=status
221+.fi
222+.RE
223+.PP
224+Mark OSD 2 out, then set noout:
225+.PP
226+.RS
227+.nf
228+fastblock-client \-op=outosd \-osdid=2
229+fastblock-client \-set=noout
230+.fi
231+.RE
232+.SH FILES
233+.TP
234+.I /etc/fastblock/fastblock.json
235+Default configuration file used to locate the monitor endpoint.
236+.TP
237+.I /usr/local/bin/fastblock-client
238+Default binary install path in the current package.
239+.SH EXIT STATUS
240+On unsupported operations or missing required arguments the client exits with
241+a fatal error. Successful one-shot operations exit after the response path
242+signals completion; watch operations run until interrupted.
243+.SH SEE ALSO
244+.BR fastblock (7),
245+.BR fastblock-mon (8),
246+.BR fastblock-osd (8)
247+.SH COPYRIGHT
248+fastblock is licensed under Mulan PSL v2.
249+See
250+.I http://license.coscl.org.cn/MulanPSL2
251+for details.
@@ -0,0 +1,245 @@
1+.\" Copyright (c) 2023-2026 ChinaUnicom / fastblock contributors
2+.\" Licensed under Mulan PSL v2.
3+.TH FASTBLOCK-CLIENT 8 "2026-07-21" "fastblock 0.1" "系统管理"
4+.SH 名称
5+fastblock-client \- fastblock monitor 管理客户端
6+.SH 大纲
7+.B fastblock-client
8+.RB [ \-conf= path ]
9+.BI \-op= operation
10+.RI [ options... ]
11+.PP
12+.B fastblock-client
13+.RB [ \-conf= path ]
14+.BR \-set= noReblance | noout
15+.PP
16+.B fastblock-client
17+.RB [ \-conf= path ]
18+.BR \-unset= noReblance | noout
19+.SH 描述
20+.B fastblock-client
21+连接到
22+.BR fastblock-mon (8)
23+控制端点并发送集群管理请求,包括 pool/image 生命周期、map 查询、OSD in/out、集群状态查询,以及开发测试用的一组 fake 辅助操作。
24+.PP
25+默认读取
26+.I /etc/fastblock/fastblock.json
27+(或
28+.B \-conf
29+指定路径),以内置身份
30+.B fbclient
31+解析配置,并连接其中的 monitor 地址与端口。
32+.SH 选项
33+.TP
34+.BI \-conf= path
35+JSON 配置文件路径。默认:
36+.IR /etc/fastblock/fastblock.json 。
37+.TP
38+.BI \-op= operation
39+要执行的主操作。支持值见
40+.BR 操作 。
41+.BR \-op 、
42+.B \-set
43+或
44+.B \-unset
45+必须能确定一个受支持的动作。
46+.TP
47+.BI \-set= flag
48+设置集群标志。支持:
49+.BR noReblance 、
50+.BR noout 。
51+.TP
52+.BI \-unset= flag
53+清除集群标志。支持:
54+.BR noReblance 、
55+.BR noout 。
56+.TP
57+.BI \-poolname= name
58+pool 名称(创建/删除及 image 相关操作)。
59+.TP
60+.BI \-poolid= id
61+pool ID(例如
62+.B getpgosds
63+)。
64+.TP
65+.BI \-pgcount= N
66+创建 pool 时的 PG 数量。
67+.TP
68+.BI \-pgsize= N
69+pool 副本数。默认:3。
70+.TP
71+.BI \-failure_domain= domain
72+创建 pool 时的故障域。默认:
73+.BR osd 。
74+.TP
75+.BI \-imagename= name
76+image 名称。
77+.TP
78+.BI \-imagesize= bytes
79+image 大小(字节)。创建/扩容时至少 4\ MiB(4194304)。
80+.TP
81+.BI \-objectsize= bytes
82+创建 image 时的 object 大小。默认:4194304(4\ MiB)。
83+.TP
84+.BI \-osdid= id
85+OSD 标识,用于
86+.BR outosd 、
87+.BR inosd 、
88+.BR fakestoposd 、
89+.B showconfig
90+等。
91+.TP
92+.BI \-uuid= uuid
93+OSD UUID(部分 fake/apply 操作需要)。
94+.TP
95+.BI \-hostname= name
96+fake boot OSD 时上报的主机名。默认:localhost。
97+.TP
98+.BI \-address= ip
99+fake boot OSD 时上报的地址。默认:127.0.0.1。
100+.TP
101+.BI \-port= port
102+与 fake OSD boot 辅助操作一起使用的端口。
103+.TP
104+.BI \-size= bytes
105+与 fake OSD boot 辅助操作一起使用的 size。
106+.TP
107+.BI \-osdcount= N
108+.B fakestartcluster
109+的 OSD 数量。
110+.TP
111+.BI \-hostcount= N
112+.B fakestartcluster
113+的主机数量。
114+.TP
115+.BI \-version= N
116+增量拉取 map 时的版本提示。默认:\-1。
117+.TP
118+.B \-detail
119+在支持的场景打印更详细信息。
120+.SH 操作
121+.B \-op
122+的取值:
123+.TP
124+.B createpool
125+创建 pool。需要
126+.B \-poolname
127+与
128+.BR \-pgcount 。
129+可选:
130+.BR \-pgsize 、
131+.BR \-failure_domain 。
132+.TP
133+.B deletepool
134+删除 pool。需要
135+.BR \-poolname 。
136+.TP
137+.B listpools
138+列出 pool。
139+.TP
140+.B createimage
141+创建 image。需要
142+.BR \-poolname 、
143+.BR \-imagename
144+以及
145+.B \-imagesize
146+(>= 4\ MiB)。可选:
147+.BR \-objectsize 。
148+.TP
149+.B removeimage
150+删除 image。需要
151+.B \-poolname
152+与
153+.BR \-imagename 。
154+.TP
155+.B resizeimage
156+调整 image 大小。需要
157+.BR \-imagename 、
158+.B \-imagesize ,
159+通常还需要
160+.BR \-poolname 。
161+.TP
162+.B getimage
163+查询 image 信息。
164+.TP
165+.B getosdmap
166+一次性获取 OSD map。
167+.TP
168+.B getpgmap
169+一次性获取 PG map。
170+.TP
171+.B getclustermap
172+一次性获取集群 map 信息。
173+.TP
174+.B watchosdmap / watchpgmap / watchclustermap
175+持续监视 map 并打印更新。
176+.TP
177+.B getpgosds
178+显示 PG 到 OSD 的分布;可选
179+.BR \-poolid 。
180+.TP
181+.B outosd / inosd
182+将 OSD 标为 out 或 in。需要
183+.BR \-osdid 。
184+.TP
185+.B status
186+显示集群状态。
187+.TP
188+.B showconfig
189+从 monitor 查看 OSD 相关配置。使用
190+.BR \-osdid 。
191+.TP
192+.B fakeapplyid / fakebootosd / fakestoposd / fakestartcluster
193+用于模拟 OSD 申请 ID、boot、stop 或批量假集群启动的开发辅助操作,面向测试环境,一般不用于生产运维。
194+.SH 示例
195+创建 3 副本、64 个 PG 的 pool:
196+.PP
197+.RS
198+.nf
199+fastblock-client \-conf=/etc/fastblock/fastblock.json \\
200+ \-op=createpool \-poolname=rbd \-pgcount=64 \-pgsize=3
201+.fi
202+.RE
203+.PP
204+创建 10\ GiB 的 image:
205+.PP
206+.RS
207+.nf
208+fastblock-client \-op=createimage \-poolname=rbd \\
209+ \-imagename=vol01 \-imagesize=10737418240
210+.fi
211+.RE
212+.PP
213+查看集群状态:
214+.PP
215+.RS
216+.nf
217+fastblock-client \-op=status
218+.fi
219+.RE
220+.PP
221+将 OSD 2 标为 out,并设置 noout:
222+.PP
223+.RS
224+.nf
225+fastblock-client \-op=outosd \-osdid=2
226+fastblock-client \-set=noout
227+.fi
228+.RE
229+.SH 文件
230+.TP
231+.I /etc/fastblock/fastblock.json
232+默认配置文件,用于定位 monitor 端点。
233+.TP
234+.I /usr/local/bin/fastblock-client
235+当前打包布局下的默认二进制路径。
236+.SH 退出状态
237+遇到不支持的操作或缺少必要参数时,客户端以致命错误退出。一次性操作在响应路径结束后退出;watch 类操作会持续运行直到被中断。
238+.SH 参见
239+.BR fastblock (7),
240+.BR fastblock-mon (8),
241+.BR fastblock-osd (8)
242+.SH 版权
243+fastblock 采用木兰宽松许可证第 2 版(Mulan PSL v2)授权。
244+详见
245+.IR http://license.coscl.org.cn/MulanPSL2 。
@@ -0,0 +1,138 @@
1+.\" Copyright (c) 2023-2026 ChinaUnicom / fastblock contributors
2+.\" Licensed under Mulan PSL v2.
3+.TH FASTBLOCK-MON 8 "2026-07-21" "fastblock 0.1" "System Administration"
4+.SH NAME
5+fastblock-mon \- fastblock cluster monitor daemon
6+.SH SYNOPSIS
7+.B fastblock-mon
8+.BI \-conf= path
9+.BI \-id= name
10+.RB [ \-max-core= N ]
11+.SH DESCRIPTION
12+.B fastblock-mon
13+is the monitor process of a
14+.BR fastblock (7)
15+cluster. It stores and distributes cluster metadata (including OSD map and PG
16+map), participates in leader election via embedded etcd, and serves control
17+RPCs used by OSDs and administrative clients.
18+.PP
19+Only the elected leader monitor runs the full control services (TCP control
20+server, PG/OSD maintenance tasks, and related exporters). Follower monitors
21+remain ready to take over if leadership changes.
22+.PP
23+Typical production use is through systemd template units:
24+.PP
25+.RS
26+.B systemctl start fastblock-mon@\fImonitor-name\fR
27+.RE
28+.PP
29+The unit invokes:
30+.PP
31+.RS
32+.B /usr/local/bin/fastblock-mon \-conf=/etc/fastblock/fastblock.json \-id=\fI%i\fR
33+.RE
34+.SH OPTIONS
35+.TP
36+.BI \-conf= path
37+Path to the JSON configuration file. Default:
38+.IR /etc/fastblock/fastblock.json .
39+.TP
40+.BI \-id= name
41+Monitor identity. This value must match one of the entries in the
42+.B monitors
43+list of the configuration file. This option is required.
44+.TP
45+.BI \-max-core= N
46+Maximum number of CPU cores the Go runtime may use
47+.RB ( GOMAXPROCS ).
48+Default: 1.
49+.SH CONFIGURATION
50+The configuration file is JSON. Important fields include:
51+.TP
52+.B monitors
53+List of monitor names in the cluster.
54+.TP
55+.B mon_host
56+Host addresses for monitors.
57+.TP
58+.B mon_rpc_address / mon_rpc_port
59+Address and port used for the monitor control RPC service
60+(defaults commonly resolve around port 3333 when unset in code defaults).
61+.TP
62+.B prometheus_port
63+HTTP port for Prometheus metrics (default commonly 3332).
64+.TP
65+.B log_path / log_level
66+Monitor log file path and level
67+.RB ( info ,
68+.BR warn ,
69+.BR error ).
70+.TP
71+.B election_master_key
72+etcd key used for leader election.
73+.TP
74+.B data_dir
75+Local data directory used by the embedded etcd member.
76+.PP
77+etcd listen/advertise URLs and related etcd settings are derived from the
78+monitor list and host configuration when the process starts with
79+.BR \-id .
80+.SH EXAMPLES
81+Start monitor instance
82+.B mon1
83+with the default config path:
84+.PP
85+.RS
86+.nf
87+fastblock-mon \-conf=/etc/fastblock/fastblock.json \-id=mon1
88+.fi
89+.RE
90+.PP
91+Allow the process to use up to 4 cores:
92+.PP
93+.RS
94+.nf
95+fastblock-mon \-conf=/etc/fastblock/fastblock.json \-id=mon1 \-max-core=4
96+.fi
97+.RE
98+.PP
99+Start via systemd (preferred on packaged systems):
100+.PP
101+.RS
102+.nf
103+systemctl enable --now fastblock-mon@mon1
104+.fi
105+.RE
106+.SH FILES
107+.TP
108+.I /etc/fastblock/fastblock.json
109+Default configuration file.
110+.TP
111+.I /usr/lib/systemd/system/fastblock-mon@.service
112+systemd template unit (path may vary by distro layout).
113+.TP
114+.I /usr/local/bin/fastblock-mon
115+Default binary install path in the current package.
116+.SH NOTES
117+.IP \(bu 3
118+If
119+.B \-id
120+is omitted, the process aborts with a missing-parameter error.
121+.IP \(bu 3
122+Ensure system clocks are reasonably synchronized across monitor hosts;
123+the systemd unit waits on
124+.BR time-sync.target .
125+.IP \(bu 3
126+Cluster administrative operations are performed with
127+.BR fastblock-client (8)
128+against a monitor endpoint defined in the same configuration file.
129+.SH SEE ALSO
130+.BR fastblock (7),
131+.BR fastblock-client (8),
132+.BR fastblock-osd (8),
133+.BR systemctl (1)
134+.SH COPYRIGHT
135+fastblock is licensed under Mulan PSL v2.
136+See
137+.I http://license.coscl.org.cn/MulanPSL2
138+for details.
@@ -0,0 +1,130 @@
1+.\" Copyright (c) 2023-2026 ChinaUnicom / fastblock contributors
2+.\" Licensed under Mulan PSL v2.
3+.TH FASTBLOCK-MON 8 "2026-07-21" "fastblock 0.1" "系统管理"
4+.SH 名称
5+fastblock-mon \- fastblock 集群 monitor 守护进程
6+.SH 大纲
7+.B fastblock-mon
8+.BI \-conf= path
9+.BI \-id= name
10+.RB [ \-max-core= N ]
11+.SH 描述
12+.B fastblock-mon
13+是
14+.BR fastblock (7)
15+集群中的 monitor 进程。它负责存储与分发集群元数据(含 OSD map、PG map),通过内嵌 etcd 参与选主,并向 OSD 与管理客户端提供控制面 RPC。
16+.PP
17+仅当选为 leader 的 monitor 会运行完整控制服务(TCP 控制服务、PG/OSD 维护任务及相关 exporter)。follower 在领导权变更时可接管。
18+.PP
19+生产环境通常通过 systemd 模板单元管理:
20+.PP
21+.RS
22+.B systemctl start fastblock-mon@\fImonitor-name\fR
23+.RE
24+.PP
25+单元实际启动命令为:
26+.PP
27+.RS
28+.B /usr/local/bin/fastblock-mon \-conf=/etc/fastblock/fastblock.json \-id=\fI%i\fR
29+.RE
30+.SH 选项
31+.TP
32+.BI \-conf= path
33+JSON 配置文件路径。默认:
34+.IR /etc/fastblock/fastblock.json 。
35+.TP
36+.BI \-id= name
37+monitor 标识。必须与配置文件中
38+.B monitors
39+列表里的某一项一致。该选项为必填。
40+.TP
41+.BI \-max-core= N
42+Go 运行时可使用的最大 CPU 核数
43+.RB ( GOMAXPROCS )。
44+默认:1。
45+.SH 配置
46+配置文件为 JSON,重要字段包括:
47+.TP
48+.B monitors
49+集群中 monitor 名称列表。
50+.TP
51+.B mon_host
52+monitor 主机地址列表。
53+.TP
54+.B mon_rpc_address / mon_rpc_port
55+monitor 控制 RPC 的地址与端口(代码默认端口常见为 3333)。
56+.TP
57+.B prometheus_port
58+Prometheus 指标 HTTP 端口(默认常见为 3332)。
59+.TP
60+.B log_path / log_level
61+日志路径与级别
62+.RB ( info 、
63+.BR warn 、
64+.BR error )。
65+.TP
66+.B election_master_key
67+用于选主的 etcd key。
68+.TP
69+.B data_dir
70+内嵌 etcd 成员使用的本地数据目录。
71+.PP
72+进程以
73+.B \-id
74+启动时,会根据 monitor 列表与主机配置推导 etcd 的 listen/advertise 等参数。
75+.SH 示例
76+使用默认配置路径启动 monitor 实例
77+.BR mon1 :
78+.PP
79+.RS
80+.nf
81+fastblock-mon \-conf=/etc/fastblock/fastblock.json \-id=mon1
82+.fi
83+.RE
84+.PP
85+最多使用 4 个 CPU 核:
86+.PP
87+.RS
88+.nf
89+fastblock-mon \-conf=/etc/fastblock/fastblock.json \-id=mon1 \-max-core=4
90+.fi
91+.RE
92+.PP
93+通过 systemd 启动(打包系统上的推荐方式):
94+.PP
95+.RS
96+.nf
97+systemctl enable --now fastblock-mon@mon1
98+.fi
99+.RE
100+.SH 文件
101+.TP
102+.I /etc/fastblock/fastblock.json
103+默认配置文件。
104+.TP
105+.I /usr/lib/systemd/system/fastblock-mon@.service
106+systemd 模板单元(具体路径随发行版布局可能不同)。
107+.TP
108+.I /usr/local/bin/fastblock-mon
109+当前打包布局下的默认二进制路径。
110+.SH 说明
111+.IP \(bu 3
112+若省略
113+.BR \-id ,
114+进程会因缺少参数而退出。
115+.IP \(bu 3
116+请尽量保证各 monitor 主机时钟同步;systemd 单元会等待
117+.BR time-sync.target 。
118+.IP \(bu 3
119+集群管理操作请使用
120+.BR fastblock-client (8) ,
121+其对端为同一配置文件中的 monitor 地址。
122+.SH 参见
123+.BR fastblock (7),
124+.BR fastblock-client (8),
125+.BR fastblock-osd (8),
126+.BR systemctl (1)
127+.SH 版权
128+fastblock 采用木兰宽松许可证第 2 版(Mulan PSL v2)授权。
129+详见
130+.IR http://license.coscl.org.cn/MulanPSL2 。
@@ -0,0 +1,152 @@
1+.\" Copyright (c) 2023-2026 ChinaUnicom / fastblock contributors
2+.\" Licensed under Mulan PSL v2.
3+.TH FASTBLOCK-OSD 8 "2026-07-21" "fastblock 0.1" "System Administration"
4+.SH NAME
5+fastblock-osd \- fastblock object storage daemon
6+.SH SYNOPSIS
7+.B fastblock-osd
8+.BI \-C \ path
9+.BI \-I \ id
10+.RB [ options ]
11+.PP
12+.B fastblock-osd
13+.BI \-\-conf= path
14+.BI \-\-id= id
15+.RB [ options ]
16+.SH DESCRIPTION
17+.B fastblock-osd
18+is the Object Storage Daemon of a
19+.BR fastblock (7)
20+cluster. Each OSD stores object data and Raft logs on local media using SPDK
21+blobstore facilities, joins multi-Raft placement groups (PGs), and serves
22+client data paths (typically over RDMA when configured).
23+.PP
24+An OSD must be given a stable numeric identifier
25+.RB ( \-I / \-\-id )
26+and a JSON configuration file
27+.RB ( \-C / \-\-conf ).
28+New disks are initialized with
29+.B \-\-mkfs
30+(optionally
31+.BR \-\-force )
32+and a UUID.
33+.PP
34+On packaged systems, OSDs are commonly managed with systemd template units:
35+.PP
36+.RS
37+.B systemctl start fastblock-osd@\fIid\fR
38+.RE
39+.PP
40+The unit runs a command equivalent to:
41+.PP
42+.RS
43+.nf
44+fastblock-osd \-C /etc/fastblock/fastblock.json \-\-id \fIid\fR \-N \fInuma\fR
45+.fi
46+.RE
47+.PP
48+where the NUMA node is derived from the instance id.
49+.SH OPTIONS
50+fastblock-osd is built on the SPDK application framework and therefore also
51+accepts standard SPDK application arguments. fastblock-specific options:
52+.TP
53+.BR \-C ", " \-\-conf " " \fIpath\fR
54+Path to the JSON configuration file (required in normal operation).
55+.TP
56+.BR \-I ", " \-\-id " " \fIid\fR
57+OSD identifier. Required.
58+.TP
59+.BR \-f ", " \-\-mkfs
60+Create/initialize a new OSD on the configured device(s).
61+.TP
62+.BR \-F ", " \-\-force
63+Force mkfs even if existing metadata is detected.
64+.TP
65+.BR \-U ", " \-\-uuid " " \fIuuid\fR
66+UUID of the OSD; used together with
67+.BR \-\-mkfs .
68+.TP
69+.BR \-S ", " \-\-core-num " " \fInum\fR
70+Number of CPU cores for the OSD reactor set.
71+Note: after a cluster is created with a given core count, later OSDs are
72+expected to use a consistent core configuration.
73+.TP
74+.BR \-N ", " \-\-numa-node " " \fIid\fR
75+Bind the OSD to the given NUMA node.
76+.SH CONFIGURATION
77+The configuration file is JSON and is shared with other fastblock components.
78+OSD-related settings typically include monitor addresses, RDMA device name,
79+Raft timing parameters, and msg/RDMA resource pool sizes. Optional keys such
80+as
81+.BR osd_data_dir ,
82+.BR osd_no_huge ,
83+and
84+.B osd_mem_size_mb
85+control local SPDK memory and data directory behavior.
86+.PP
87+Ensure the process has access to the intended NVMe/AIO devices and RDMA
88+resources described by the config and deployment method.
89+.SH EXAMPLES
90+Initialize OSD 0 on a new device layout (UUID required):
91+.PP
92+.RS
93+.nf
94+fastblock-osd \-C /etc/fastblock/fastblock.json \\
95+ \-\-id 0 \-\-mkfs \-\-uuid 123e4567\-e89b\-12d3\-a456\-426614174000
96+.fi
97+.RE
98+.PP
99+Start OSD 0 with 2 cores on NUMA node 0:
100+.PP
101+.RS
102+.nf
103+fastblock-osd \-C /etc/fastblock/fastblock.json \\
104+ \-\-id 0 \-\-core\-num 2 \-\-numa\-node 0
105+.fi
106+.RE
107+.PP
108+Start via systemd:
109+.PP
110+.RS
111+.nf
112+systemctl enable --now fastblock-osd@0
113+.fi
114+.RE
115+.SH FILES
116+.TP
117+.I /etc/fastblock/fastblock.json
118+Default configuration file path used by the packaged unit.
119+.TP
120+.I /var/log/fastblock/osd\fIN\fP.log
121+Log path used by the packaged
122+.B fastblock-osd@
123+unit for instance
124+.IR N .
125+.TP
126+.I /usr/lib/systemd/system/fastblock-osd@.service
127+systemd template unit (path may vary by distro layout).
128+.TP
129+.I /usr/local/bin/fastblock-osd
130+Default binary install path in the current package.
131+.SH NOTES
132+.IP \(bu 3
133+.B \-\-id
134+must be set; the process refuses to start without it.
135+.IP \(bu 3
136+After mkfs, the OSD registers/boots with monitors so that PG placement can
137+include it. Use
138+.BR fastblock-client (8)
139+to inspect status and maps.
140+.IP \(bu 3
141+Core count chosen at cluster creation time should be treated as part of the
142+cluster contract; changing it later may not be supported by all tooling paths.
143+.SH SEE ALSO
144+.BR fastblock (7),
145+.BR fastblock-mon (8),
146+.BR fastblock-client (8),
147+.BR systemctl (1)
148+.SH COPYRIGHT
149+fastblock is licensed under Mulan PSL v2.
150+See
151+.I http://license.coscl.org.cn/MulanPSL2
152+for details.
@@ -0,0 +1,143 @@
1+.\" Copyright (c) 2023-2026 ChinaUnicom / fastblock contributors
2+.\" Licensed under Mulan PSL v2.
3+.TH FASTBLOCK-OSD 8 "2026-07-21" "fastblock 0.1" "系统管理"
4+.SH 名称
5+fastblock-osd \- fastblock 对象存储守护进程
6+.SH 大纲
7+.B fastblock-osd
8+.BI \-C \ path
9+.BI \-I \ id
10+.RB [ options ]
11+.PP
12+.B fastblock-osd
13+.BI \-\-conf= path
14+.BI \-\-id= id
15+.RB [ options ]
16+.SH 描述
17+.B fastblock-osd
18+是
19+.BR fastblock (7)
20+集群中的 Object Storage Daemon。每个 OSD 通过 SPDK blobstore 在本地介质上保存对象数据与 Raft 日志,加入 multi-Raft 的 PG,并在配置允许时通过 RDMA 等路径服务客户端数据 IO。
21+.PP
22+启动 OSD 时必须指定稳定的数字 ID
23+.RB ( \-I / \-\-id )
24+以及 JSON 配置文件
25+.RB ( \-C / \-\-conf )。
26+新磁盘使用
27+.B \-\-mkfs
28+初始化(必要时加
29+.BR \-\-force ),
30+并提供 UUID。
31+.PP
32+打包系统上通常用 systemd 模板单元管理:
33+.PP
34+.RS
35+.B systemctl start fastblock-osd@\fIid\fR
36+.RE
37+.PP
38+单元大致等价于:
39+.PP
40+.RS
41+.nf
42+fastblock-osd \-C /etc/fastblock/fastblock.json \-\-id \fIid\fR \-N \fInuma\fR
43+.fi
44+.RE
45+.PP
46+其中 NUMA 节点由实例 ID 推导。
47+.SH 选项
48+fastblock-osd 基于 SPDK 应用框架,因此也接受 SPDK 通用参数。fastblock 相关选项:
49+.TP
50+.BR \-C ", " \-\-conf " " \fIpath\fR
51+JSON 配置文件路径(正常运行时需要)。
52+.TP
53+.BR \-I ", " \-\-id " " \fIid\fR
54+OSD 标识。该选项为必填。
55+.TP
56+.BR \-f ", " \-\-mkfs
57+在配置的设备上创建/初始化新的 OSD。
58+.TP
59+.BR \-F ", " \-\-force
60+即使检测到已有元数据也强制 mkfs。
61+.TP
62+.BR \-U ", " \-\-uuid " " \fIuuid\fR
63+OSD 的 UUID;与
64+.B \-\-mkfs
65+一起使用。
66+.TP
67+.BR \-S ", " \-\-core-num " " \fInum\fR
68+OSD reactor 使用的 CPU 核数。
69+注意:集群创建时指定的核数之后通常应保持一致。
70+.TP
71+.BR \-N ", " \-\-numa-node " " \fIid\fR
72+将 OSD 绑定到指定 NUMA 节点。
73+.SH 配置
74+配置文件为 JSON,并与其他 fastblock 组件共享。OSD 相关项通常包括 monitor 地址、RDMA 设备名、Raft 时间参数,以及 msg/RDMA 资源池大小等。可选键如
75+.BR osd_data_dir 、
76+.BR osd_no_huge 、
77+.B osd_mem_size_mb
78+用于控制本地 SPDK 内存与数据目录行为。
79+.PP
80+请确保进程能够访问配置与部署方式所描述的 NVMe/AIO 设备及 RDMA 资源。
81+.SH 示例
82+在新设备布局上初始化 OSD 0(需要 UUID):
83+.PP
84+.RS
85+.nf
86+fastblock-osd \-C /etc/fastblock/fastblock.json \\
87+ \-\-id 0 \-\-mkfs \-\-uuid 123e4567\-e89b\-12d3\-a456\-426614174000
88+.fi
89+.RE
90+.PP
91+在 NUMA 节点 0 上以 2 核启动 OSD 0:
92+.PP
93+.RS
94+.nf
95+fastblock-osd \-C /etc/fastblock/fastblock.json \\
96+ \-\-id 0 \-\-core\-num 2 \-\-numa\-node 0
97+.fi
98+.RE
99+.PP
100+通过 systemd 启动:
101+.PP
102+.RS
103+.nf
104+systemctl enable --now fastblock-osd@0
105+.fi
106+.RE
107+.SH 文件
108+.TP
109+.I /etc/fastblock/fastblock.json
110+打包单元使用的默认配置路径。
111+.TP
112+.I /var/log/fastblock/osd\fIN\fP.log
113+打包的
114+.B fastblock-osd@
115+单元为实例
116+.I N
117+使用的日志路径。
118+.TP
119+.I /usr/lib/systemd/system/fastblock-osd@.service
120+systemd 模板单元(具体路径随发行版布局可能不同)。
121+.TP
122+.I /usr/local/bin/fastblock-osd
123+当前打包布局下的默认二进制路径。
124+.SH 说明
125+.IP \(bu 3
126+必须设置
127+.BR \-\-id ,
128+否则进程拒绝启动。
129+.IP \(bu 3
130+mkfs 之后,OSD 会向 monitor 注册/boot,以便参与 PG 分布。可用
131+.BR fastblock-client (8)
132+查看状态与 map。
133+.IP \(bu 3
134+创建集群时选定的核数应视为集群约定的一部分;后续修改不一定被所有工具路径支持。
135+.SH 参见
136+.BR fastblock (7),
137+.BR fastblock-mon (8),
138+.BR fastblock-client (8),
139+.BR systemctl (1)
140+.SH 版权
141+fastblock 采用木兰宽松许可证第 2 版(Mulan PSL v2)授权。
142+详见
143+.IR http://license.coscl.org.cn/MulanPSL2 。
@@ -0,0 +1,96 @@
1+.\" Copyright (c) 2023-2026 ChinaUnicom / fastblock contributors
2+.\" Licensed under Mulan PSL v2.
3+.TH FASTBLOCK 7 "2026-07-21" "fastblock 0.1" "Miscellaneous"
4+.SH NAME
5+fastblock \- distributed block storage system for all-flash scenarios
6+.SH DESCRIPTION
7+.B fastblock
8+is a distributed block storage system designed for high performance and low
9+latency on NVMe and other all-flash media. It uses the mature Raft consensus
10+protocol (multi-Raft) for data replication and reliability.
11+.PP
12+The architecture is intentionally similar to Ceph-style designs so operators
13+can map familiar concepts:
14+.TP
15+.B Monitor
16+Maintains cluster metadata (OSD map, PG map, pool and image information),
17+handles topology, and coordinates PG placement. Implemented in Go and backed
18+by embedded etcd for multi-replica metadata.
19+.TP
20+.B OSD
21+Object Storage Daemon. Stores objects on local media via SPDK blobstore,
22+participates in multi-Raft groups, and serves client data I/O over RDMA where
23+available.
24+.TP
25+.B Client paths
26+User data is exposed through SPDK vhost (VMs), NVMe-oF target, or library
27+integrations. The
28+.BR fastblock-client (8)
29+tool talks to monitors for cluster administration (pools, images, maps).
30+.PP
31+Control-plane RPCs (metadata) typically use TCP. Data and Raft RPCs are
32+designed for RDMA to reduce latency and CPU cost on the I/O path.
33+.SH COMPONENTS
34+Installed packages commonly provide these programs:
35+.TP
36+.BR fastblock-mon (8)
37+Cluster monitor daemon.
38+.TP
39+.BR fastblock-client (8)
40+Administrative client for monitors.
41+.TP
42+.BR fastblock-osd (8)
43+Object storage daemon.
44+.TP
45+.B fastblock-vhost
46+SPDK vhost frontend for virtual machines (see package documentation).
47+.TP
48+.B fastblock-nvmf-tgt
49+NVMe-oF target frontend (see package documentation).
50+.TP
51+.B block_bench
52+Block I/O benchmark helper shipped with the OSD package.
53+.SH CONFIGURATION
54+The default cluster configuration file is:
55+.PP
56+.RS
57+.I /etc/fastblock/fastblock.json
58+.RE
59+.PP
60+Frontends may use additional files such as
61+.I /etc/fastblock/vhost.json
62+and
63+.IR /etc/fastblock/nvmf_tgt.json .
64+.PP
65+On systems packaged by openEuler, systemd units are provided, for example:
66+.PP
67+.RS
68+.BR fastblock-mon@ .service ,
69+.BR fastblock-osd@ .service ,
70+.BR fastblock-vhost .service ,
71+.BR fastblock-nvmf-tgt .service
72+.RE
73+.PP
74+and corresponding
75+.B .target
76+units under
77+.IR fastblock.target .
78+.SH FILES
79+.TP
80+.I /etc/fastblock/fastblock.json
81+Primary JSON configuration for monitors, OSDs, and clients.
82+.TP
83+.I /var/log/fastblock/
84+Default directory for component logs (paths are configurable).
85+.TP
86+.I /usr/local/bin/fastblock-*
87+Default install location of binaries in the current package layout.
88+.SH SEE ALSO
89+.BR fastblock-mon (8),
90+.BR fastblock-client (8),
91+.BR fastblock-osd (8)
92+.SH COPYRIGHT
93+fastblock is licensed under Mulan PSL v2.
94+See
95+.I http://license.coscl.org.cn/MulanPSL2
96+for details.
@@ -1,12 +1,22 @@
1%define debug_package %{nil}1%define debug_package %{nil}
2Name: fastblock2Name: fastblock
3Version: 0.13Version: 0.1
4-Release: 3%{?dist}4+Release: 6%{?dist}
5Summary: block storage system5Summary: block storage system
6Group: Application/System6Group: Application/System
7License: Mulan PSL v27License: Mulan PSL v2
8URL: None8URL: None
9Source0: %{name}-%{version}.tar.gz9Source0: %{name}-%{version}.tar.gz
10+# English man pages
11+Source1: fastblock.7
12+Source2: fastblock-mon.8
13+Source3: fastblock-client.8
14+Source4: fastblock-osd.8
15+# Chinese (zh_CN) man pages
16+Source5: fastblock.zh_CN.7
17+Source6: fastblock-mon.zh_CN.8
18+Source7: fastblock-client.zh_CN.8
19+Source8: fastblock-osd.zh_CN.8
10 20 
11Requires: fastblock-mon = %{version}-%{release}21Requires: fastblock-mon = %{version}-%{release}
12Requires: fastblock-osd = %{version}-%{release}22Requires: fastblock-osd = %{version}-%{release}
@@ -95,6 +105,18 @@ cmake . -DCMAKE_BUILD_TYPE=Release \
95 105 
96mkdir -p %{buildroot}/etc/fastblock/106mkdir -p %{buildroot}/etc/fastblock/
97 107 
108+# English man pages
109+install -D -m 644 %{SOURCE1} %{buildroot}%{_mandir}/man7/fastblock.7
110+install -D -m 644 %{SOURCE2} %{buildroot}%{_mandir}/man8/fastblock-mon.8
111+install -D -m 644 %{SOURCE3} %{buildroot}%{_mandir}/man8/fastblock-client.8
112+install -D -m 644 %{SOURCE4} %{buildroot}%{_mandir}/man8/fastblock-osd.8
113+ 
114+# Chinese (zh_CN) man pages
115+install -D -m 644 %{SOURCE5} %{buildroot}%{_mandir}/zh_CN/man7/fastblock.7
116+install -D -m 644 %{SOURCE6} %{buildroot}%{_mandir}/zh_CN/man8/fastblock-mon.8
117+install -D -m 644 %{SOURCE7} %{buildroot}%{_mandir}/zh_CN/man8/fastblock-client.8
118+install -D -m 644 %{SOURCE8} %{buildroot}%{_mandir}/zh_CN/man8/fastblock-osd.8
119+ 
98%post mon120%post mon
99/usr/bin/systemctl preset fastblock-mon@.service fastblock-mon.target >/dev/null 2>&1 ||:121/usr/bin/systemctl preset fastblock-mon@.service fastblock-mon.target >/dev/null 2>&1 ||:
100%systemd_post fastblock-mon@.service fastblock-mon.target122%systemd_post fastblock-mon@.service fastblock-mon.target
@@ -132,6 +154,8 @@ fi
132%systemd_postun fastblock-nvmf-tgt.service fastblock-nvmf-tgt.target154%systemd_postun fastblock-nvmf-tgt.service fastblock-nvmf-tgt.target
133 155 
134%files156%files
157+%{_mandir}/man7/fastblock.7*
158+%lang(zh_CN) %{_mandir}/zh_CN/man7/fastblock.7*
135 159 
136%files mon160%files mon
137%{_unitdir}/fastblock.target161%{_unitdir}/fastblock.target
@@ -139,6 +163,10 @@ fi
139%{_unitdir}/fastblock-mon@.service163%{_unitdir}/fastblock-mon@.service
140%attr(0755, root, root) /usr/local/bin/fastblock-mon164%attr(0755, root, root) /usr/local/bin/fastblock-mon
141%attr(0755, root, root) /usr/local/bin/fastblock-client165%attr(0755, root, root) /usr/local/bin/fastblock-client
166+%{_mandir}/man8/fastblock-mon.8*
167+%{_mandir}/man8/fastblock-client.8*
168+%lang(zh_CN) %{_mandir}/zh_CN/man8/fastblock-mon.8*
169+%lang(zh_CN) %{_mandir}/zh_CN/man8/fastblock-client.8*
142 170 
143%files osd171%files osd
144%{_unitdir}/fastblock-osd.target172%{_unitdir}/fastblock-osd.target
@@ -151,11 +179,25 @@ fi
151%attr(0755, root, root) /usr/local/bin/block_bench179%attr(0755, root, root) /usr/local/bin/block_bench
152%attr(0755, root, root) /usr/local/bin/fastblock-vhost180%attr(0755, root, root) /usr/local/bin/fastblock-vhost
153%attr(0755, root, root) /usr/local/bin/fastblock-nvmf-tgt181%attr(0755, root, root) /usr/local/bin/fastblock-nvmf-tgt
182+%{_mandir}/man8/fastblock-osd.8*
183+%lang(zh_CN) %{_mandir}/zh_CN/man8/fastblock-osd.8*
154 184 
155%clean185%clean
156rm -rf %{buildroot}186rm -rf %{buildroot}
157 187 
158%changelog188%changelog
189+* Fri Sep 04 2026 wuxingyi <wuxy158@chinaunicom.cn> - 0.1-6
190+- Sync code from openEuler-24.03-LTS-SP4 to openEuler-26.09-DevStation
191+ to fix package downgrade issue
192+ 
193+* Thu Jul 23 2026 wuxingyi <wuxy158@chinaunicom.cn> - 0.1-5
194+- Add Chinese (zh_CN) man pages for fastblock, fastblock-mon, fastblock-client
195+ and fastblock-osd
196+ 
197+* Tue Jul 21 2026 wuxingyi <wuxy158@chinaunicom.cn> - 0.1-4
198+- Add English man pages for fastblock, fastblock-mon, fastblock-client and
199+ fastblock-osd
200+ 
159* Mon Jun 22 2026 wuxingyi <wuxy158@chinaunicom.cn> - 0.1-3201* Mon Jun 22 2026 wuxingyi <wuxy158@chinaunicom.cn> - 0.1-3
160- Fix systemd template unit uninstallation missing instance name error202- Fix systemd template unit uninstallation missing instance name error
161 203 
@@ -0,0 +1,88 @@
1+.\" Copyright (c) 2023-2026 ChinaUnicom / fastblock contributors
2+.\" Licensed under Mulan PSL v2.
3+.TH FASTBLOCK 7 "2026-07-21" "fastblock 0.1" "杂项"
4+.SH 名称
5+fastblock \- 面向全闪场景的分布式块存储系统
6+.SH 描述
7+.B fastblock
8+是一套面向 NVMe 等全闪介质、追求高性能与低延迟的分布式块存储系统。数据复制与可靠性基于成熟的 Raft 协议(multi-Raft)实现。
9+.PP
10+整体架构有意贴近 Ceph 一类设计,便于运维人员映射已有概念:
11+.TP
12+.B Monitor(监视器)
13+维护集群元数据(OSD map、PG map、pool 与 image 信息),管理拓扑并协调 PG 分布。使用 Go 实现,并通过内嵌 etcd 做元数据多副本。
14+.TP
15+.B OSD
16+Object Storage Daemon。基于 SPDK blobstore 在本地介质上保存对象,加入 multi-Raft 的 PG,并在配置允许时通过 RDMA 提供客户端数据 IO。
17+.TP
18+.B 客户端路径
19+用户数据可通过 SPDK vhost(虚拟机)、NVMe-oF target 或库集成对外提供。管理侧使用
20+.BR fastblock-client (8)
21+与 monitor 通信,完成 pool、image、map 等集群管理操作。
22+.PP
23+控制面 RPC(元数据)通常走 TCP;数据面与 Raft RPC 面向 RDMA,以降低 IO 路径延迟与 CPU 开销。
24+.SH 组件
25+软件包通常提供以下程序:
26+.TP
27+.BR fastblock-mon (8)
28+集群 monitor 守护进程。
29+.TP
30+.BR fastblock-client (8)
31+面向 monitor 的管理客户端。
32+.TP
33+.BR fastblock-osd (8)
34+对象存储守护进程。
35+.TP
36+.B fastblock-vhost
37+面向虚拟机的 SPDK vhost 前端(详见软件包文档)。
38+.TP
39+.B fastblock-nvmf-tgt
40+NVMe-oF target 前端(详见软件包文档)。
41+.TP
42+.B block_bench
43+随 OSD 软件包提供的块 IO 压测工具。
44+.SH 配置
45+默认集群配置文件为:
46+.PP
47+.RS
48+.I /etc/fastblock/fastblock.json
49+.RE
50+.PP
51+前端还可能使用
52+.I /etc/fastblock/vhost.json
53+、
54+.I /etc/fastblock/nvmf_tgt.json
55+等文件。
56+.PP
57+在 openEuler 打包环境中通常提供 systemd 单元,例如:
58+.PP
59+.RS
60+.BR fastblock-mon@ .service 、
61+.BR fastblock-osd@ .service 、
62+.BR fastblock-vhost .service 、
63+.BR fastblock-nvmf-tgt .service
64+.RE
65+.PP
66+以及
67+.B fastblock.target
68+下的对应
69+.B .target
70+单元。
71+.SH 文件
72+.TP
73+.I /etc/fastblock/fastblock.json
74+monitor、OSD 与 client 的主 JSON 配置。
75+.TP
76+.I /var/log/fastblock/
77+组件日志默认目录(具体路径可配置)。
78+.TP
79+.I /usr/local/bin/fastblock-*
80+当前打包布局下二进制的默认安装路径。
81+.SH 参见
82+.BR fastblock-mon (8),
83+.BR fastblock-client (8),
84+.BR fastblock-osd (8)
85+.SH 版权
86+fastblock 采用木兰宽松许可证第 2 版(Mulan PSL v2)授权。
87+详见
88+.IR http://license.coscl.org.cn/MulanPSL2 。