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 |===========================================================
  43
  44
  45 Configuration
  46 ~~~~~~~~~~~~~
  47
  48 This backend supports all common storage properties, and adds an
  49 additional property called `path` to specify the directory. This
  50 needs to be an absolute file system path.
  51
  52 .Configuration Example (`/etc/pve/storage.cfg`)
  53 ----
  54 dir: backup
  55         path /mnt/backup
  56         content backup
  57         maxfiles 7
  58 ----
  59
  60 Above configuration defines a storage pool called `backup`. That pool
  61 can be used to store up to 7 backups (`maxfiles 7`) per VM. The real
  62 path for the backup files is `/mnt/backup/dump/...`.
  63
  64
  65 File naming conventions
  66 ~~~~~~~~~~~~~~~~~~~~~~~
  67
  68 This backend uses a well defined naming scheme for VM images:
  69
  70  vm-<VMID>-<NAME>.<FORMAT>
  71
  72 `<VMID>`::
  73
  74 This specifies the owner VM.
  75
  76 `<NAME>`::
  77
  78 This can be an arbitrary name (`ascii`) without white space. The
  79 backend uses `disk-[N]` as default, where `[N]` is replaced by an
  80 integer to make the name unique.
  81
  82 `<FORMAT>`::
  83
  84 Specifies the image format (`raw|qcow2|vmdk`).
  85
  86 When you create a VM template, all VM images are renamed to indicate
  87 that they are now read-only, and can be used as a base image for clones:
  88
  89  base-<VMID>-<NAME>.<FORMAT>
  90
  91 NOTE: Such base images are used to generate cloned images. So it is
  92 important that those files are read-only, and never get modified. The
  93 backend changes the access mode to `0444`, and sets the immutable flag
  94 (`chattr +i`) if the storage supports that.
  95
  96
  97 Storage Features
  98 ~~~~~~~~~~~~~~~~
  99
 100 As mentioned above, most file systems do not support snapshots out
 101 of the box. To workaround that problem, this backend is able to use
 102 `qcow2` internal snapshot capabilities.
 103
 104 Same applies to clones. The backend uses the `qcow2` base image
 105 feature to create clones.
 106
 107 .Storage features for backend `dir`
 108 [width="100%",cols="m,m,3*d",options="header"]
 109 |==============================================================================
 110 |Content types                     |Image formats         |Shared |Snapshots |Clones
 111 |images rootdir vztmpl iso backup  |raw qcow2 vmdk subvol |no     |qcow2     |qcow2
 112 |==============================================================================
 113
 114
 115 Examples
 116 ~~~~~~~~
 117
 118 Please use the following command to allocate a 4GB image on storage `local`:
 119
 120  # pvesm alloc local 100 vm-100-disk10.raw 4G
 121  Formatting '/var/lib/vz/images/100/vm-100-disk10.raw', fmt=raw size=4294967296
 122  successfully created 'local:100/vm-100-disk10.raw'
 123
 124 NOTE: The image name must conform to above naming conventions.
 125
 126 The real file system path is shown with:
 127
 128  # pvesm path local:100/vm-100-disk10.raw
 129  /var/lib/vz/images/100/vm-100-disk10.raw
 130
 131 And you can remove the image with:
 132
 133  # pvesm free local:100/vm-100-disk10.raw
 134
 135
 136 ifdef::wiki[]
 137
 138 See Also
 139 ~~~~~~~~
 140
 141 * link:/wiki/Storage[Storage]
 142
 143 endif::wiki[]
 144
 145