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