pve-storage-dir.adoc

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