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  de‐
33       vice)  equal  to  the  page  size of the machine creating the PV (often
34       4 KiB.) The metadata area contains a 512 byte header  and  a  multi-KiB
35       circular 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  de‐
60       fault_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 overrid‐
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 be‐
72       cause  the metadata area size also determines the location of pe_start.
73       When using these two options together, pe_start is calculated as: meta‐
74       data area start (page size), plus the specified --metadatasize, rounded
75       up to the next multiple of --dataalignment.  With metadata starting  at
76       4 KiB,  --metadatasize  2048k,  and  --dataalignment  128k, pe_start is
77       2176 KiB and mda_size is 2172 KiB.  The pe_start  of  2176 KiB  is  the
78       nearest  even  multiple  of  128 KiB that provides at least 2048 KiB of
79       metadata space.  Always check the resulting alignment and metadata size
80       when using these options.
81
82       To  shift  an aligned pe_start value, use the --dataalignmentoffset op‐
83       tion.  The pe_start alignment is calculated  as  described  above,  and
84       then the value specified with --dataalignmentoffset 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|json_std ]
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           [    --devices PV ]
116           [    --devicesfile String ]
117           [    --driverloaded y|n ]
118           [    --journal String ]
119           [    --lockopt String ]
120           [    --longhelp ]
121           [    --nohints ]
122           [    --nolocking ]
123           [    --profile String ]
124           [    --version ]
125

OPTIONS

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

VARIABLES

313       PV     Physical Volume name, a device path under  /dev.   For  commands
314              managing physical extents, a PV positional arg generally accepts
315              a suffix indicating a range (or multiple ranges) of physical ex‐
316              tents  (PEs).  When  the first PE is omitted, it defaults to the
317              start of the device, and when the last PE is omitted it defaults
318              to  end.   Start and end range (inclusive): PV[:PE-PE]...  Start
319              and length range (counting from 0): PV[:PE+PE]...
320
321       String See the option description for information about the string con‐
322              tent.
323
324       Size[UNIT]
325              Size  is  an  input number that accepts an optional unit.  Input
326              units are always treated as base two values, regardless of capi‐
327              talization,  e.g.  'k'  and 'K' both refer to 1024.  The default
328              input unit is specified by letter, followed by |UNIT.  UNIT rep‐
329              resents other possible input units: b|B is bytes, s|S is sectors
330              of 512 bytes, k|K is KiB, m|M is MiB, g|G is GiB,  t|T  is  TiB,
331              p|P  is  PiB, e|E is EiB.  (This should not be confused with the
332              output control --units, where capital letters mean  multiple  of
333              1000.)
334

ENVIRONMENT VARIABLES

336       See  lvm(8)  for  information  about environment variables used by lvm.
337       For example, LVM_VG_NAME can generally be substituted for a required VG
338       parameter.
339

EXAMPLES

341       Initialize a partition and a full device.
342       pvcreate /dev/sdc4 /dev/sde
343
344       If a device is a 4 KiB sector drive that compensates for windows parti‐
345       tioning (sector 7 is the lowest aligned logical block, the  4 KiB  sec‐
346       tors  start at LBA -1, and consequently sector 63 is aligned on a 4 KiB
347       boundary) manually account for this when initializing for use by LVM.
348       pvcreate --dataalignmentoffset 7s /dev/sdb
349

SEE ALSO

351       lvm(8), lvm.conf(5), lvmconfig(8), lvmdevices(8),
352
353       pvchange(8), pvck(8), pvcreate(8), pvdisplay(8), pvmove(8),
354       pvremove(8), pvresize(8), pvs(8), pvscan(8),
355
356       vgcfgbackup(8), vgcfgrestore(8), vgchange(8), vgck(8), vgcreate(8),
357       vgconvert(8), vgdisplay(8), vgexport(8), vgextend(8), vgimport(8),
358       vgimportclone(8), vgimportdevices(8), vgmerge(8), vgmknodes(8),
359       vgreduce(8), vgremove(8), vgrename(8), vgs(8), vgscan(8), vgsplit(8),
360
361       lvcreate(8), lvchange(8), lvconvert(8), lvdisplay(8), lvextend(8),
362       lvreduce(8), lvremove(8), lvrename(8), lvresize(8), lvs(8), lvscan(8),
363
364       lvm-fullreport(8), lvm-lvpoll(8), blkdeactivate(8), lvmdump(8),
365
366       dmeventd(8), lvmpolld(8), lvmlockd(8), lvmlockctl(8), cmirrord(8),
367       lvmdbusd(8), fsadm(8),
368
369       lvmsystemid(7), lvmreport(7), lvmraid(7), lvmthin(7), lvmcache(7)
370
371
372
373Red Hat, Inc.        LVM TOOLS 2.03.18(2)-git (2022-11-10)         PVCREATE(8)
Impressum