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