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