1podman-volume-create(1) General Commands Manual podman-volume-create(1)
2
6 podman-volume-create - Create a new volume
7
10 podman volume create [options] [name]
11
14 Creates an empty volume and prepares it to be used by containers. The
15 volume can be created with a specific name, if a name is not given a
16 random name is generated. You can add metadata to the volume by using
17 the --label flag and driver options can be set using the --opt flag.
18
21 --driver, -d=driver
22 Specify the volume driver name (default local). There are two drivers
23 supported by Podman itself: local and image.
24 The local driver uses a directory on disk as the backend by default,
27 but can also use the mount(8) command to mount a filesystem as the vol‐
28 ume if --opt is specified.
29 The image driver uses an image as the backing store of for the volume.
32 An overlay filesystem is created, which allows changes to the volume to
33 be committed as a new layer on top of the image.
34 Using a value other than local or image, Podman attempts to create the
37 volume using a volume plugin with the given name. Such plugins must be
38 defined in the volume_plugins section of the containers.conf(5) config‐
39 uration file.
40 --help
43 Print usage statement
44 --ignore
47 Don't fail if the named volume already exists, instead just print the
48 name. Note that the new options are not applied to the existing volume.
49 --label, -l=label
52 Set metadata for a volume (e.g., --label mykey=value).
53 --opt, -o=option
56 Set driver specific options. For the default driver, local, this al‐
57 lows a volume to be configured to mount a filesystem on the host.
58 For the local driver the following options are supported: type, device,
61 o, and [no]copy.
62 • The type option sets the type of the filesystem to be mounted,
65 and is equivalent to the -t flag to mount(8).
66 • The device option sets the device to be mounted, and is equiv‐
68 alent to the device argument to mount(8).
69 • The copy option enables copying files from the container image
71 path where the mount is created to the newly created volume on
72 the first run. copy is the default.
73 The o option sets options for the mount, and is equivalent to the
77 filesystem options (also -o) passed to mount(8) with the following ex‐
78 ceptions:
79 • The o option supports uid and gid options to set the UID and
82 GID of the created volume that are not normally supported by
83 mount(8).
84 • The o option supports the size option to set the maximum size
86 of the created volume, the inodes option to set the maximum
87 number of inodes for the volume, and noquota to completely
88 disable quota support even for tracking of disk usage. The
89 size option is supported on the "tmpfs" and "xfs[note]" file
90 systems. The inodes option is supported on the "xfs[note]"
91 file systems. Note: xfs filesystems must be mounted with the
92 prjquota flag described in the xfs_quota(8) man page. Podman
93 will throw an error if they're not.
94 • The o option supports using volume options other than the
96 UID/GID options with the local driver and requires root privi‐
97 leges.
98 • The o options supports the timeout option which allows users
100 to set a driver specific timeout in seconds before volume cre‐
101 ation fails. For example, --opt=o=timeout=10 sets a driver
102 timeout of 10 seconds.
103 Note Do not confuse the --opt,-o create option with the -o mount op‐
107 tion. For example, with podman volume create, use -o=o=uid=1000 not
108 -o=uid=1000.
109 For the image driver, the only supported option is image, which speci‐
112 fies the image the volume is based on. This option is mandatory when
113 using the image driver.
114 When not using the local and image drivers, the given options are
117 passed directly to the volume plugin. In this case, supported options
118 are dictated by the plugin in question, not Podman.
119
122 $ podman volume create myvol
123 $ podman volume create
125 $ podman volume create --label foo=bar myvol
127 # podman volume create --opt device=tmpfs --opt type=tmpfs --opt o=size=2M,nodev,noexec myvol
129 # podman volume create --opt device=tmpfs --opt type=tmpfs --opt o=uid=1000,gid=1000 testvol
131 # podman volume create --driver image --opt image=fedora:latest fedoraVol
133
137 podman volume create uses XFS project quota controls for controlling
138 the size and the number of inodes of builtin volumes. The directory
139 used to store the volumes must be an XFS file system and be mounted
140 with the pquota option.
141 Example /etc/fstab entry:
144 /dev/podman/podman-var /var xfs defaults,x-systemd.device-timeout=0,pquota 1 2
146 Podman generates project IDs for each builtin volume, but these project
150 IDs need to be unique for the XFS file system. These project IDs by de‐
151 fault are generated randomly, with a potential for overlap with other
152 quotas on the same file system.
153 The xfs_quota tool can be used to assign a project ID to the storage
156 driver directory, e.g.:
157 echo 100000:/var/lib/containers/storage/overlay >> /etc/projects
159 echo 200000:/var/lib/containers/storage/volumes >> /etc/projects
160 echo storage:100000 >> /etc/projid
161 echo volumes:200000 >> /etc/projid
162 xfs_quota -x -c 'project -s storage volumes' /<xfs mount point>
163 In the example above we are configuring the overlay storage driver for
167 newly created containers as well as volumes to use project IDs with a
168 start offset. All containers are assigned larger project IDs (e.g. >=
169 100000). All volume assigned project IDs larger project IDs starting
170 with 200000. This prevents xfs_quota management conflicts with con‐
171 tainers/storage.
172
175 podman(1), containers.conf(5), podman-volume(1), mount(8),
176 xfs_quota(8), xfs_quota(8), projects(5), projid(5)
177
180 January 2020, updated with information on volume plugins by Matthew
181 Heon mheon@redhat.com ⟨mailto:mheon@redhat.com⟩ November 2018, Origi‐
182 nally compiled by Urvashi Mohnani umohnani@redhat.com
183 ⟨mailto:umohnani@redhat.com⟩
184 podman-volume-create(1)