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