pve-storage-dir.adoc

   1 [[storage_directory]]
   2 Directory Backend
   3 -----------------
   4 ifdef::wiki[]
   5 :pve-toplevel:
   6 :title: Storage: Directory
   7 endif::wiki[]
   8
   9 Storage pool type: `dir`
  10
  11 {pve} can use local directories or locally mounted shares for
  12 storage. A directory is a file level storage, so you can store any
  13 content type like virtual disk images, containers, templates, ISO images
  14 or backup files.
  15
  16 NOTE: You can mount additional storages via standard linux `/etc/fstab`,
  17 and then define a directory storage for that mount point. This way you
  18 can use any file system supported by Linux.
  19
  20 This backend assumes that the underlying directory is POSIX
  21 compatible, but nothing else. This implies that you cannot create
  22 snapshots at the storage level. But there exists a workaround for VM
  23 images using the `qcow2` file format, because that format supports
  24 snapshots internally.
  25
  26 TIP: Some storage types do not support `O_DIRECT`, so you can't use
  27 cache mode `none` with such storages. Simply use cache mode
  28 `writeback` instead.
  29
  30 We use a predefined directory layout to store different content types
  31 into different sub-directories. This layout is used by all file level
  32 storage backends.
  33
  34 .Directory layout
  35 [width="100%",cols="d,m",options="header"]
  36 |===========================================================
  37 |Content type        |Subdir
  38 |VM images           |`images/<VMID>/`
  39 |ISO images          |`template/iso/`
  40 |Container templates |`template/cache/`
  41 |Backup files        |`dump/`
  42 |Snippets            |`snippets/`
  43 |===========================================================
  44
  45
  46 Configuration
  47 ~~~~~~~~~~~~~
  48
  49 This backend supports all common storage properties, and adds two
  50 additional properties. The `path` property is used to specify the
  51 directory. This needs to be an absolute file system path.
  52
  53 The optional `content-dirs` property allows for the default layout
  54 to be changed. It consists of a comma-separated list of identifiers
  55 in the following format:
  56
  57  vtype=path
  58
  59 Where `vtype` is one of the allowed content types for the storage, and
  60 `path` is a path relative to the mountpoint of the storage, preceded
  61 with /.
  62
  63 .Configuration Example (`/etc/pve/storage.cfg`)
  64 ----
  65 dir: backup
  66         path /mnt/backup
  67         content backup
  68         prune-backups keep-last=7
  69         max-protected-backups 3
  70         content-dirs backup=/custom/backup/dir
  71 ----
  72
  73 The above configuration defines a storage pool called `backup`. That pool can be
  74 used to store up to 7 regular backups (`keep-last=7`) and 3 protected backups
  75 per VM. The real path for the backup files is `/mnt/backup/custom/backup/dir/...`.
  76
  77 File naming conventions
  78 ~~~~~~~~~~~~~~~~~~~~~~~
  79
  80 This backend uses a well defined naming scheme for VM images:
  81
  82  vm-<VMID>-<NAME>.<FORMAT>
  83
  84 `<VMID>`::
  85
  86 This specifies the owner VM.
  87
  88 `<NAME>`::
  89
  90 This can be an arbitrary name (`ascii`) without white space. The
  91 backend uses `disk-[N]` as default, where `[N]` is replaced by an
  92 integer to make the name unique.
  93
  94 `<FORMAT>`::
  95
  96 Specifies the image format (`raw|qcow2|vmdk`).
  97
  98 When you create a VM template, all VM images are renamed to indicate
  99 that they are now read-only, and can be used as a base image for clones:
 100
 101  base-<VMID>-<NAME>.<FORMAT>
 102
 103 NOTE: Such base images are used to generate cloned images. So it is
 104 important that those files are read-only, and never get modified. The
 105 backend changes the access mode to `0444`, and sets the immutable flag
 106 (`chattr +i`) if the storage supports that.
 107
 108
 109 Storage Features
 110 ~~~~~~~~~~~~~~~~
 111
 112 As mentioned above, most file systems do not support snapshots out
 113 of the box. To workaround that problem, this backend is able to use
 114 `qcow2` internal snapshot capabilities.
 115
 116 Same applies to clones. The backend uses the `qcow2` base image
 117 feature to create clones.
 118
 119 .Storage features for backend `dir`
 120 [width="100%",cols="m,m,3*d",options="header"]
 121 |==============================================================================
 122 |Content types                              |Image formats         |Shared |Snapshots |Clones
 123 |images rootdir vztmpl iso backup snippets  |raw qcow2 vmdk subvol |no     |qcow2     |qcow2
 124 |==============================================================================
 125
 126
 127 Examples
 128 ~~~~~~~~
 129
 130 Please use the following command to allocate a 4GB image on storage `local`:
 131
 132  # pvesm alloc local 100 vm-100-disk10.raw 4G
 133  Formatting '/var/lib/vz/images/100/vm-100-disk10.raw', fmt=raw size=4294967296
 134  successfully created 'local:100/vm-100-disk10.raw'
 135
 136 NOTE: The image name must conform to above naming conventions.
 137
 138 The real file system path is shown with:
 139
 140  # pvesm path local:100/vm-100-disk10.raw
 141  /var/lib/vz/images/100/vm-100-disk10.raw
 142
 143 And you can remove the image with:
 144
 145  # pvesm free local:100/vm-100-disk10.raw
 146
 147
 148 ifdef::wiki[]
 149
 150 See Also
 151 ~~~~~~~~
 152
 153 * link:/wiki/Storage[Storage]
 154
 155 endif::wiki[]
 156
 157