]>
Commit | Line | Data |
---|---|---|
b5b8bbf5 FG |
1 | :orphan: |
2 | ||
3 | ======================================== | |
4 | ceph-volume -- Ceph OSD deployment tool | |
5 | ======================================== | |
6 | ||
7 | .. program:: ceph-volume | |
8 | ||
9 | Synopsis | |
10 | ======== | |
11 | ||
12 | | **ceph-volume** [-h] [--cluster CLUSTER] [--log-level LOG_LEVEL] | |
13 | | [--log-path LOG_PATH] | |
14 | ||
b32b8144 FG |
15 | | **ceph-volume** **lvm** [ *trigger* | *create* | *activate* | *prepare* |
16 | | *zap* | *list*] | |
17 | ||
18 | | **ceph-volume** **simple** [ *trigger* | *scan* | *activate* ] | |
19 | ||
b5b8bbf5 FG |
20 | |
21 | Description | |
22 | =========== | |
23 | ||
24 | :program:`ceph-volume` is a single purpose command line tool to deploy logical | |
25 | volumes as OSDs, trying to maintain a similar API to ``ceph-disk`` when | |
26 | preparing, activating, and creating OSDs. | |
27 | ||
28 | It deviates from ``ceph-disk`` by not interacting or relying on the udev rules | |
29 | that come installed for Ceph. These rules allow automatic detection of | |
30 | previously setup devices that are in turn fed into ``ceph-disk`` to activate | |
31 | them. | |
32 | ||
33 | ||
34 | Commands | |
35 | ======== | |
36 | ||
37 | lvm | |
38 | --- | |
39 | ||
40 | By making use of LVM tags, the ``lvm`` sub-command is able to store and later | |
41 | re-discover and query devices associated with OSDs so that they can later | |
42 | activated. | |
43 | ||
44 | Subcommands: | |
45 | ||
46 | **activate** | |
47 | Enables a systemd unit that persists the OSD ID and its UUID (also called | |
48 | ``fsid`` in Ceph CLI tools), so that at boot time it can understand what OSD is | |
49 | enabled and needs to be mounted. | |
50 | ||
51 | Usage:: | |
52 | ||
94b18763 | 53 | ceph-volume lvm activate --bluestore <osd id> <osd fsid> |
b5b8bbf5 FG |
54 | |
55 | Optional Arguments: | |
56 | ||
57 | * [-h, --help] show the help message and exit | |
94b18763 FG |
58 | * [--auto-detect-objectstore] Automatically detect the objecstore by inspecting |
59 | the OSD | |
60 | * [--bluestore] bluestore objectstore (default) | |
61 | * [--filestore] filestore objectstore | |
62 | * [--all] Activate all OSDs found in the system | |
63 | * [--no-systemd] Skip creating and enabling systemd units and starting of OSD | |
64 | services | |
b5b8bbf5 | 65 | |
28e407b8 AA |
66 | Multiple OSDs can be activated at once by using the (idempotent) ``--all`` flag:: |
67 | ||
68 | ceph-volume lvm activate --all | |
69 | ||
b5b8bbf5 FG |
70 | |
71 | **prepare** | |
94b18763 FG |
72 | Prepares a logical volume to be used as an OSD and journal using a ``filestore`` |
73 | or ``bluestore`` (default) setup. It will not create or modify the logical volumes | |
b5b8bbf5 FG |
74 | except for adding extra metadata. |
75 | ||
76 | Usage:: | |
77 | ||
78 | ceph-volume lvm prepare --filestore --data <data lv> --journal <journal device> | |
79 | ||
80 | Optional arguments: | |
81 | ||
82 | * [-h, --help] show the help message and exit | |
83 | * [--journal JOURNAL] A logical group name, path to a logical volume, or path to a device | |
b32b8144 | 84 | * [--bluestore] Use the bluestore objectstore (default) |
94b18763 FG |
85 | * [--block.wal] Path to a bluestore block.wal logical volume or partition |
86 | * [--block.db] Path to a bluestore block.db logical volume or partition | |
b32b8144 FG |
87 | * [--filestore] Use the filestore objectstore |
88 | * [--dmcrypt] Enable encryption for the underlying OSD devices | |
b5b8bbf5 FG |
89 | * [--osd-id OSD_ID] Reuse an existing OSD id |
90 | * [--osd-fsid OSD_FSID] Reuse an existing OSD fsid | |
94b18763 | 91 | * [--crush-device-class] Define a CRUSH device class to assign the OSD to |
b5b8bbf5 FG |
92 | |
93 | Required arguments: | |
94 | ||
95 | * --data A logical group name or a path to a logical volume | |
96 | ||
28e407b8 AA |
97 | For encrypting an OSD, the ``--dmcrypt`` flag must be added when preparing |
98 | (also supported in the ``create`` sub-command). | |
99 | ||
100 | ||
b5b8bbf5 FG |
101 | **create** |
102 | Wraps the two-step process to provision a new osd (calling ``prepare`` first | |
103 | and then ``activate``) into a single one. The reason to prefer ``prepare`` and | |
104 | then ``activate`` is to gradually introduce new OSDs into a cluster, and | |
105 | avoiding large amounts of data being rebalanced. | |
106 | ||
107 | The single-call process unifies exactly what ``prepare`` and ``activate`` do, | |
108 | with the convenience of doing it all at once. Flags and general usage are | |
94b18763 | 109 | equivalent to those of the ``prepare`` and ``activate`` subcommand. |
b5b8bbf5 FG |
110 | |
111 | **trigger** | |
112 | This subcommand is not meant to be used directly, and it is used by systemd so | |
113 | that it proxies input to ``ceph-volume lvm activate`` by parsing the | |
114 | input from systemd, detecting the UUID and ID associated with an OSD. | |
115 | ||
116 | Usage:: | |
117 | ||
118 | ceph-volume lvm trigger <SYSTEMD-DATA> | |
119 | ||
120 | The systemd "data" is expected to be in the format of:: | |
121 | ||
122 | <OSD ID>-<OSD UUID> | |
123 | ||
124 | The lvs associated with the OSD need to have been prepared previously, | |
125 | so that all needed tags and metadata exist. | |
126 | ||
127 | Positional arguments: | |
128 | ||
129 | * <SYSTEMD_DATA> Data from a systemd unit containing ID and UUID of the OSD. | |
130 | ||
b32b8144 FG |
131 | **list** |
132 | List devices or logical volumes associated with Ceph. An association is | |
133 | determined if a device has information relating to an OSD. This is | |
134 | verified by querying LVM's metadata and correlating it with devices. | |
135 | ||
136 | The lvs associated with the OSD need to have been prepared previously by | |
137 | ceph-volume so that all needed tags and metadata exist. | |
138 | ||
139 | Usage:: | |
140 | ||
141 | ceph-volume lvm list | |
142 | ||
143 | List a particular device, reporting all metadata about it:: | |
144 | ||
145 | ceph-volume lvm list /dev/sda1 | |
146 | ||
147 | List a logical volume, along with all its metadata (vg is a volume | |
148 | group, and lv the logical volume name):: | |
149 | ||
150 | ceph-volume lvm list {vg/lv} | |
151 | ||
152 | Positional arguments: | |
153 | ||
94b18763 FG |
154 | * <DEVICE> Either in the form of ``vg/lv`` for logical volumes, |
155 | ``/path/to/sda1`` or ``/path/to/sda`` for regular devices. | |
b32b8144 FG |
156 | |
157 | ||
158 | **zap** | |
159 | Zaps the given logical volume or partition. If given a path to a logical | |
160 | volume it must be in the format of vg/lv. Any filesystems present | |
161 | on the given lv or partition will be removed and all data will be purged. | |
162 | ||
163 | However, the lv or partition will be kept intact. | |
164 | ||
165 | Usage, for logical volumes:: | |
166 | ||
167 | ceph-volume lvm zap {vg/lv} | |
168 | ||
169 | Usage, for logical partitions:: | |
170 | ||
171 | ceph-volume lvm zap /dev/sdc1 | |
172 | ||
173 | Positional arguments: | |
174 | ||
94b18763 FG |
175 | * <DEVICE> Either in the form of ``vg/lv`` for logical volumes, |
176 | ``/path/to/sda1`` or ``/path/to/sda`` for regular devices. | |
b32b8144 FG |
177 | |
178 | ||
179 | simple | |
180 | ------ | |
181 | ||
182 | Scan legacy OSD directories or data devices that may have been created by | |
183 | ceph-disk, or manually. | |
184 | ||
185 | Subcommands: | |
186 | ||
187 | **activate** | |
188 | Enables a systemd unit that persists the OSD ID and its UUID (also called | |
189 | ``fsid`` in Ceph CLI tools), so that at boot time it can understand what OSD is | |
190 | enabled and needs to be mounted, while reading information that was previously | |
191 | created and persisted at ``/etc/ceph/osd/`` in JSON format. | |
192 | ||
193 | Usage:: | |
194 | ||
195 | ceph-volume simple activate --bluestore <osd id> <osd fsid> | |
196 | ||
197 | Optional Arguments: | |
198 | ||
199 | * [-h, --help] show the help message and exit | |
200 | * [--bluestore] bluestore objectstore (default) | |
201 | * [--filestore] filestore objectstore | |
202 | ||
203 | Note: It requires a matching JSON file with the following format:: | |
204 | ||
205 | /etc/ceph/osd/<osd id>-<osd fsid>.json | |
206 | ||
207 | ||
208 | **scan** | |
209 | Scan a running OSD or data device for an OSD for metadata that can later be | |
210 | used to activate and manage the OSD with ceph-volume. The scan method will | |
211 | create a JSON file with the required information plus anything found in the OSD | |
212 | directory as well. | |
213 | ||
214 | Optionally, the JSON blob can be sent to stdout for further inspection. | |
215 | ||
216 | Usage on data devices:: | |
217 | ||
218 | ceph-volume simple scan <data device> | |
219 | ||
220 | Running OSD directories:: | |
221 | ||
222 | ceph-volume simple scan <path to osd dir> | |
223 | ||
224 | ||
225 | Optional arguments: | |
226 | ||
227 | * [-h, --help] show the help message and exit | |
228 | * [--stdout] Send the JSON blob to stdout | |
229 | * [--force] If the JSON file exists at destination, overwrite it | |
230 | ||
231 | Required Positional arguments: | |
232 | ||
233 | * <DATA DEVICE or OSD DIR> Actual data partition or a path to the running OSD | |
234 | ||
235 | **trigger** | |
236 | This subcommand is not meant to be used directly, and it is used by systemd so | |
237 | that it proxies input to ``ceph-volume simple activate`` by parsing the | |
238 | input from systemd, detecting the UUID and ID associated with an OSD. | |
239 | ||
240 | Usage:: | |
241 | ||
242 | ceph-volume simple trigger <SYSTEMD-DATA> | |
243 | ||
244 | The systemd "data" is expected to be in the format of:: | |
245 | ||
246 | <OSD ID>-<OSD UUID> | |
247 | ||
248 | The JSON file associated with the OSD need to have been persisted previously by | |
249 | a scan (or manually), so that all needed metadata can be used. | |
250 | ||
251 | Positional arguments: | |
252 | ||
253 | * <SYSTEMD_DATA> Data from a systemd unit containing ID and UUID of the OSD. | |
254 | ||
255 | ||
b5b8bbf5 FG |
256 | Availability |
257 | ============ | |
258 | ||
259 | :program:`ceph-volume` is part of Ceph, a massively scalable, open-source, distributed storage system. Please refer to | |
260 | the documentation at http://docs.ceph.com/ for more information. | |
261 | ||
262 | ||
263 | See also | |
264 | ======== | |
265 | ||
266 | :doc:`ceph-osd <ceph-osd>`\(8), | |
267 | :doc:`ceph-disk <ceph-disk>`\(8), |