]>
Commit | Line | Data |
---|---|---|
8119f671 | 1 | [[storage_directory]] |
aa039b0f DM |
2 | Directory Backend |
3 | ----------------- | |
5f09af76 DM |
4 | ifdef::wiki[] |
5 | :pve-toplevel: | |
cb84ed18 | 6 | :title: Storage: Directory |
5f09af76 DM |
7 | endif::wiki[] |
8 | ||
aa039b0f DM |
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 | ||
8c1189b6 | 16 | NOTE: You can mount additional storages via standard linux `/etc/fstab`, |
aa039b0f DM |
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 | |
871e1fd6 | 22 | snapshots at the storage level. But there exists a workaround for VM |
aa039b0f DM |
23 | images using the `qcow2` file format, because that format supports |
24 | snapshots internally. | |
25 | ||
871e1fd6 | 26 | TIP: Some storage types do not support `O_DIRECT`, so you can't use |
aa039b0f DM |
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 | |
871e1fd6 | 31 | into different sub-directories. This layout is used by all file level |
aa039b0f DM |
32 | storage backends. |
33 | ||
34 | .Directory layout | |
35 | [width="100%",cols="d,m",options="header"] | |
36 | |=========================================================== | |
37 | |Content type |Subdir | |
8c1189b6 FG |
38 | |VM images |`images/<VMID>/` |
39 | |ISO images |`template/iso/` | |
40 | |Container templates |`template/cache/` | |
41 | |Backup files |`dump/` | |
c2c8eb89 | 42 | |Snippets |`snippets/` |
aa039b0f DM |
43 | |=========================================================== |
44 | ||
5eba0743 | 45 | |
aa039b0f DM |
46 | Configuration |
47 | ~~~~~~~~~~~~~ | |
48 | ||
432750f7 LN |
49 | This backend supports all common storage properties, and adds two |
50 | additional properties. The `path` property is used to specify the | |
51 | directory. This needs to be an absolute file system path. | |
52 | ||
256c4c76 WB |
53 | The optional `content-dirs` property allows for the default layout |
54 | to be changed. It consists of a comma-separated list of identifiers | |
93ee25d0 | 55 | in the following format: |
432750f7 | 56 | |
93ee25d0 | 57 | vtype=path |
432750f7 LN |
58 | |
59 | Where `vtype` is one of the allowed content types for the storage, and | |
93ee25d0 LN |
60 | `path` is a path relative to the mountpoint of the storage, preceded |
61 | with /. | |
aa039b0f | 62 | |
8c1189b6 | 63 | .Configuration Example (`/etc/pve/storage.cfg`) |
aa039b0f DM |
64 | ---- |
65 | dir: backup | |
66 | path /mnt/backup | |
67 | content backup | |
5c85b0a1 | 68 | prune-backups keep-last=7 |
2db55d5d | 69 | max-protected-backups 3 |
93ee25d0 | 70 | content-dirs backup=/custom/backup/dir |
aa039b0f DM |
71 | ---- |
72 | ||
5c85b0a1 | 73 | The above configuration defines a storage pool called `backup`. That pool can be |
2db55d5d | 74 | used to store up to 7 regular backups (`keep-last=7`) and 3 protected backups |
432750f7 | 75 | per VM. The real path for the backup files is `/mnt/backup/custom/backup/dir/...`. |
aa039b0f DM |
76 | |
77 | File naming conventions | |
78 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
79 | ||
80 | This backend uses a well defined naming scheme for VM images: | |
81 | ||
82 | vm-<VMID>-<NAME>.<FORMAT> | |
83 | ||
84 | `<VMID>`:: | |
85 | ||
86 | This specifies the owner VM. | |
87 | ||
88 | `<NAME>`:: | |
89 | ||
8c1189b6 | 90 | This can be an arbitrary name (`ascii`) without white space. The |
871e1fd6 | 91 | backend uses `disk-[N]` as default, where `[N]` is replaced by an |
aa039b0f DM |
92 | integer to make the name unique. |
93 | ||
94 | `<FORMAT>`:: | |
95 | ||
8c1189b6 | 96 | Specifies the image format (`raw|qcow2|vmdk`). |
aa039b0f DM |
97 | |
98 | When you create a VM template, all VM images are renamed to indicate | |
5eba0743 | 99 | that they are now read-only, and can be used as a base image for clones: |
aa039b0f DM |
100 | |
101 | base-<VMID>-<NAME>.<FORMAT> | |
102 | ||
103 | NOTE: Such base images are used to generate cloned images. So it is | |
871e1fd6 FG |
104 | important that those files are read-only, and never get modified. The |
105 | backend changes the access mode to `0444`, and sets the immutable flag | |
aa039b0f DM |
106 | (`chattr +i`) if the storage supports that. |
107 | ||
5eba0743 | 108 | |
aa039b0f DM |
109 | Storage Features |
110 | ~~~~~~~~~~~~~~~~ | |
111 | ||
871e1fd6 | 112 | As mentioned above, most file systems do not support snapshots out |
aa039b0f DM |
113 | of the box. To workaround that problem, this backend is able to use |
114 | `qcow2` internal snapshot capabilities. | |
115 | ||
116 | Same applies to clones. The backend uses the `qcow2` base image | |
117 | feature to create clones. | |
118 | ||
119 | .Storage features for backend `dir` | |
120 | [width="100%",cols="m,m,3*d",options="header"] | |
121 | |============================================================================== | |
c2c8eb89 DC |
122 | |Content types |Image formats |Shared |Snapshots |Clones |
123 | |images rootdir vztmpl iso backup snippets |raw qcow2 vmdk subvol |no |qcow2 |qcow2 | |
aa039b0f DM |
124 | |============================================================================== |
125 | ||
126 | ||
127 | Examples | |
128 | ~~~~~~~~ | |
129 | ||
130 | Please use the following command to allocate a 4GB image on storage `local`: | |
131 | ||
132 | # pvesm alloc local 100 vm-100-disk10.raw 4G | |
133 | Formatting '/var/lib/vz/images/100/vm-100-disk10.raw', fmt=raw size=4294967296 | |
7c384c31 | 134 | successfully created 'local:100/vm-100-disk10.raw' |
aa039b0f DM |
135 | |
136 | NOTE: The image name must conform to above naming conventions. | |
137 | ||
138 | The real file system path is shown with: | |
139 | ||
140 | # pvesm path local:100/vm-100-disk10.raw | |
141 | /var/lib/vz/images/100/vm-100-disk10.raw | |
142 | ||
143 | And you can remove the image with: | |
144 | ||
145 | # pvesm free local:100/vm-100-disk10.raw | |
146 | ||
deb4673f DM |
147 | |
148 | ifdef::wiki[] | |
149 | ||
150 | See Also | |
151 | ~~~~~~~~ | |
152 | ||
f532afb7 | 153 | * link:/wiki/Storage[Storage] |
deb4673f DM |
154 | |
155 | endif::wiki[] | |
156 | ||
157 |