1PVCREATE(8)                 System Manager's Manual                PVCREATE(8)
2
3
4

NAME

6       pvcreate - Initialize physical volume(s) for use by LVM
7

SYNOPSIS

9       pvcreate position_args
10           [ option_args ]
11

DESCRIPTION

13       pvcreate  initializes  a Physical Volume (PV) on a device so the device
14       is recognized as belonging to LVM.  This allows the PV to be used in  a
15       Volume Group (VG).  An LVM disk label is written to the device, and LVM
16       metadata areas are initialized.  A PV can be placed on a  whole  device
17       or partition.
18
19       Use vgcreate(8) to create a new VG on the PV, or vgextend(8) to add the
20       PV to an existing VG.  Use pvremove(8) to remove  the  LVM  disk  label
21       from the device.
22
23       The  force option will create a PV without confirmation.  Repeating the
24       force option (-ff) will forcibly create a PV,  overriding  checks  that
25       normally prevent it, e.g. if the PV is already in a VG.
26
27       Metadata location, size, and alignment
28
29       The  LVM  disk label begins 512 bytes from the start of the device, and
30       is 512 bytes in size.
31
32       The LVM metadata area begins at  an  offset  (from  the  start  of  the
33       device)  equal to the page size of the machine creating the PV (often 4
34       KiB.) The metadata area contains a 512 byte header and a multi-KiB cir‐
35       cular buffer that holds text copies of the VG metadata.
36
37       With  default  settings, the first physical extent (PE), which contains
38       LV data, is 1 MiB from the start of the device.  This location is  con‐
39       trolled  by default_data_alignment in lvm.conf, which is set to 1 (MiB)
40       by default.  The pe_start will be a multiple of this  many  MiB.   This
41       location can be checked with:
42       pvs -o pe_start PV
43
44       The size of the LVM metadata area is the space between the the start of
45       the metadata area and the first PE.  When metadata begins at 4 KiB  and
46       the  first PE is at 1024 KiB, the metadata area size is 1020 KiB.  This
47       can be checked with:
48       pvs -o mda_size PV
49
50       The mda_size cannot be increased after pvcreate, so if larger  metadata
51       is  needed, it must be set during pvcreate.  Two copies of the VG meta‐
52       data must always fit within the metadata area, so the maximum VG  meta‐
53       data size is around half the mda_size.  This can be checked with:
54       vgs -o mda_free VG
55
56       A  larger  metadata area can be set with --metadatasize.  The resulting
57       mda_size may be larger than  specified  due  to  default_data_alignment
58       placing pe_start on a MiB boundary, and the fact that the metadata area
59       extends to  the  first  PE.   With  metadata  starting  at  4  KiB  and
60       default_data_alignment 1 (MiB), setting --metadatasize 2048k results in
61       pe_start of 3 MiB and mda_size of 3068 KiB.  Alternatively, --metadata‐
62       size 2044k results in pe_start at 2 MiB and mda_size of 2044 KiB.
63
64       The  alignment of pe_start described above may be automatically overri‐
65       den based on md device properties or device i/o properties reported  in
66       sysfs.   These  automatic  adjustments  can  be  enabled/disabled using
67       lvm.conf settings md_chunk_alignment  and  data_alignment_offset_detec‐
68       tion.
69
70       To  use a different pe_start alignment, use the --dataalignment option.
71       The --metadatasize option would also typically be  used  in  this  case
72       because  the  metadata  area  size  also  determines  the  location  of
73       pe_start.  When using these two options together,  pe_start  is  calcu‐
74       lated  as:  metadata area start (page size), plus the specified --meta‐
75       datasize, rounded up to the next  multiple  of  --dataalignment.   With
76       metadata  starting  at 4 KiB, --metadatasize 2048k, and --dataalignment
77       128k, pe_start is 2176 KiB and mda_size is 2172 KiB.  The  pe_start  of
78       2176 KiB is the nearest even multiple of 128 KiB that provides at least
79       2048 KiB of metadata space.  Always check the resulting  alignment  and
80       metadata size when using these options.
81
82       To  shift  an  aligned  pe_start  value,  use  the --dataaligmentoffset
83       option.  The pe_start alignment is calculated as described  above,  and
84       then  the value specified with --dataaligmentoffset is added to produce
85       the final pe_start value.
86

USAGE

88       pvcreate PV ...
89           [ -f|--force ]
90           [ -M|--metadatatype lvm2 ]
91           [ -u|--uuid String ]
92           [ -Z|--zero y|n ]
93           [    --dataalignment Size[k|UNIT] ]
94           [    --dataalignmentoffset Size[k|UNIT] ]
95           [    --bootloaderareasize Size[m|UNIT] ]
96           [    --labelsector Number ]
97           [    --[pv]metadatacopies 0|1|2 ]
98           [    --metadatasize Size[m|UNIT] ]
99           [    --metadataignore y|n ]
100           [    --norestorefile ]
101           [    --setphysicalvolumesize Size[m|UNIT] ]
102           [    --reportformat basic|json ]
103           [    --restorefile String ]
104           [ COMMON_OPTIONS ]
105
106       Common options for lvm:
107           [ -d|--debug ]
108           [ -h|--help ]
109           [ -q|--quiet ]
110           [ -t|--test ]
111           [ -v|--verbose ]
112           [ -y|--yes ]
113           [    --commandprofile String ]
114           [    --config String ]
115           [    --driverloaded y|n ]
116           [    --lockopt String ]
117           [    --longhelp ]
118           [    --nolocking ]
119           [    --profile String ]
120           [    --version ]
121

OPTIONS

123       --bootloaderareasize Size[m|UNIT]
124              Reserve space for the bootloader between the LVM metadata area
125              and the first PE.  The bootloader area is reserved for bootload‐
126              ers to embed their own data or metadata; LVM will not use it.
127              The bootloader area begins where the first PE would otherwise be
128              located.  The first PE is moved out by the size of the boot‐
129              loader area, and then moved out further if necessary to match
130              the data alignment.  The start of the bootloader area is always
131              aligned, see also --dataalignment and --dataalignmentoffset. The
132              bootloader area may be larger than requested due to the align‐
133              ment, but it's never less than the requested size.  To see the
134              bootloader area start and size of an existing PV use pvs -o
135              +pv_ba_start,pv_ba_size.
136
137       --commandprofile String
138              The command profile to use for command configuration.  See
139              lvm.conf(5) for more information about profiles.
140
141       --config String
142              Config settings for the command. These override lvm.conf set‐
143              tings.  The String arg uses the same format as lvm.conf, or may
144              use section/field syntax.  See lvm.conf(5) for more information
145              about config.
146
147       --dataalignment Size[k|UNIT]
148              Align the start of a PV data area with a multiple of this num‐
149              ber.  To see the location of the first Physical Extent (PE) of
150              an existing PV, use pvs -o +pe_start. In addition, it may be
151              shifted by an alignment offset, see --dataalignmentoffset.  Also
152              specify an appropriate PE size when creating a VG.
153
154       --dataalignmentoffset Size[k|UNIT]
155              Shift the start of the PV data area by this additional offset.
156
157       -d|--debug ...
158              Set debug level. Repeat from 1 to 6 times to increase the detail
159              of messages sent to the log file and/or syslog (if configured).
160
161       --driverloaded y|n
162              If set to no, the command will not attempt to use device-mapper.
163              For testing and debugging.
164
165       -f|--force ...
166              Override various checks, confirmations and protections.  Use
167              with extreme caution.
168
169       -h|--help
170              Display help text.
171
172       --labelsector Number
173              By default the PV is labelled with an LVM2 identifier in its
174              second sector (sector 1). This lets you use a different sector
175              near the start of the disk (between 0 and 3 inclusive - see
176              LABEL_SCAN_SECTORS in the source). Use with care.
177
178       --lockopt String
179              Used to pass options for special cases to lvmlockd.  See lvm‐
180              lockd(8) for more information.
181
182       --longhelp
183              Display long help text.
184
185       --metadataignore y|n
186              Specifies the metadataignore property of a PV.  If yes, metadata
187              areas on the PV are ignored, and lvm will not store metadata in
188              the metadata areas of the PV.  If no, lvm will store metadata on
189              the PV.
190
191       --metadatasize Size[m|UNIT]
192              The approximate amount of space used for each VG metadata area.
193              The size may be rounded.
194
195       -M|--metadatatype lvm2
196              Specifies the type of on-disk metadata to use.  lvm2 (or just 2)
197              is the current, standard format.  lvm1 (or just 1) is no longer
198              used.
199
200       --nolocking
201              Disable locking.
202
203       --norestorefile
204              In conjunction with --uuid, this allows a uuid to be specified
205              without also requiring that a backup of the metadata be pro‐
206              vided.
207
208       --profile String
209              An alias for --commandprofile or --metadataprofile, depending on
210              the command.
211
212       --[pv]metadatacopies 0|1|2
213              The number of metadata areas to set aside on a PV for storing VG
214              metadata.  When 2, one copy of the VG metadata is stored at the
215              front of the PV and a second copy is stored at the end.  When 1,
216              one copy of the VG metadata is stored at the front of the PV.
217              When 0, no copies of the VG metadata are stored on the given PV.
218              This may be useful in VGs containing many PVs (this places limi‐
219              tations on the ability to use vgsplit later.)
220
221       -q|--quiet ...
222              Suppress output and log messages. Overrides --debug and --ver‐
223              bose.  Repeat once to also suppress any prompts with answer
224              'no'.
225
226       --reportformat basic|json
227              Overrides current output format for reports which is defined
228              globally by the report/output_format setting in lvm.conf.  basic
229              is the original format with columns and rows.  If there is more
230              than one report per command, each report is prefixed with the
231              report name for identification. json produces report output in
232              JSON format. See lvmreport(7) for more information.
233
234       --restorefile String
235              In conjunction with --uuid, this reads the file (produced by
236              vgcfgbackup), extracts the location and size of the data on the
237              PV, and ensures that the metadata produced by the program is
238              consistent with the contents of the file, i.e. the physical
239              extents will be in the same place and not be overwritten by new
240              metadata. This provides a mechanism to upgrade the metadata for‐
241              mat or to add/remove metadata areas. Use with care.
242
243       --setphysicalvolumesize Size[m|UNIT]
244              Overrides the automatically detected size of the PV.  Use with
245              care, or prior to reducing the physical size of the device.
246
247       -t|--test
248              Run in test mode. Commands will not update metadata.  This is
249              implemented by disabling all metadata writing but nevertheless
250              returning success to the calling function. This may lead to
251              unusual error messages in multi-stage operations if a tool
252              relies on reading back metadata it believes has changed but
253              hasn't.
254
255       -u|--uuid String
256              Specify a UUID for the device.  Without this option, a random
257              UUID is generated.  This option is needed before restoring a
258              backup of LVM metadata onto a replacement device; see vgcfgre‐
259              store(8). As such, use of --restorefile is compulsory unless the
260              --norestorefile is used.  All PVs must have unique UUIDs, and
261              LVM will prevent certain operations if multiple devices are seen
262              with the same UUID.  See vgimportclone(8) for more information.
263
264       -v|--verbose ...
265              Set verbose level. Repeat from 1 to 4 times to increase the
266              detail of messages sent to stdout and stderr.
267
268       --version
269              Display version information.
270
271       -y|--yes
272              Do not prompt for confirmation interactively but always assume
273              the answer yes. Use with extreme caution.  (For automatic no,
274              see -qq.)
275
276       -Z|--zero y|n
277              Controls if the first 4 sectors (2048 bytes) of the device are
278              wiped.  The default is to wipe these sectors unless either or
279              both of --restorefile or --uuid are specified.
280

VARIABLES

282       PV
283              Physical  Volume  name,  a device path under /dev.  For commands
284              managing physical extents, a PV positional arg generally accepts
285              a  suffix  indicating  a  range (or multiple ranges) of physical
286              extents (PEs). When the first PE is omitted, it defaults to  the
287              start of the device, and when the last PE is omitted it defaults
288              to end.  Start and end range (inclusive):  PV[:PE-PE]...   Start
289              and length range (counting from 0): PV[:PE+PE]...
290
291       String
292              See the option description for information about the string con‐
293              tent.
294
295       Size[UNIT]
296              Size is an input number that accepts an  optional  unit.   Input
297              units are always treated as base two values, regardless of capi‐
298              talization, e.g. 'k' and 'K' both refer to  1024.   The  default
299              input unit is specified by letter, followed by |UNIT.  UNIT rep‐
300              resents other possible input units:  bBsSkKmMgGtTpPeE.   b|B  is
301              bytes,  s|S  is  sectors  of 512 bytes, k|K is kilobytes, m|M is
302              megabytes, g|G is gigabytes, t|T is terabytes, p|P is petabytes,
303              e|E  is  exabytes.  (This should not be confused with the output
304              control --units, where capital letters mean multiple of 1000.)
305

ENVIRONMENT VARIABLES

307       See lvm(8) for information about environment  variables  used  by  lvm.
308       For example, LVM_VG_NAME can generally be substituted for a required VG
309       parameter.
310

EXAMPLES

312       Initialize a partition and a full device.
313       pvcreate /dev/sdc4 /dev/sde
314
315       If a device is a 4KiB sector drive that compensates for windows  parti‐
316       tioning (sector 7 is the lowest aligned logical block, the 4KiB sectors
317       start at LBA -1, and consequently sector 63 is aligned on a 4KiB bound‐
318       ary) manually account for this when initializing for use by LVM.
319       pvcreate --dataalignmentoffset 7s /dev/sdb
320

SEE ALSO

322       lvm(8) lvm.conf(5) lvmconfig(8)
323
324       pvchange(8)  pvck(8)  pvcreate(8)  pvdisplay(8)  pvmove(8)  pvremove(8)
325       pvresize(8) pvs(8) pvscan(8)
326
327       vgcfgbackup(8) vgcfgrestore(8) vgchange(8) vgck(8)  vgcreate(8)  vgcon‐
328       vert(8)  vgdisplay(8)  vgexport(8)  vgextend(8)  vgimport(8)  vgimport‐
329       clone(8) vgmerge(8) vgmknodes(8)  vgreduce(8)  vgremove(8)  vgrename(8)
330       vgs(8) vgscan(8) vgsplit(8)
331
332       lvcreate(8)  lvchange(8)  lvconvert(8)  lvdisplay(8)  lvextend(8) lvre‐
333       duce(8) lvremove(8) lvrename(8) lvresize(8) lvs(8) lvscan(8)
334
335       lvm-fullreport(8) lvm-lvpoll(8) lvm2-activation-generator(8) blkdeacti‐
336       vate(8) lvmdump(8)
337
338       dmeventd(8)  lvmpolld(8)  lvmlockd(8)  lvmlockctl(8)  cmirrord(8) lvmd‐
339       busd(8)
340
341       lvmsystemid(7) lvmreport(7) lvmraid(7) lvmthin(7) lvmcache(7)
342
343
344
345Red Hat, Inc.          LVM TOOLS 2.03.09(2) (2020-03-26)           PVCREATE(8)
Impressum