1podman-volume-create(1)     General Commands Manual    podman-volume-create(1)
2
3
4

NAME

6       podman-volume-create - Create a new volume
7
8

SYNOPSIS

10       podman volume create [options] [name]
11
12

DESCRIPTION

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
19

OPTIONS

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
25
26       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
30
31       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
35
36       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
41
42   --help
43       Print usage statement
44
45
46   --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
50
51   --label, -l=label
52       Set metadata for a volume (e.g., --label mykey=value).
53
54
55   --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
59
60       For the local driver the following options are supported: type, device,
61       o, and [no]copy.
62
63
64              • The type option sets the type of the filesystem to be mounted,
65                and is equivalent to the -t flag to mount(8).
66
67              • The device option sets the device to be mounted, and is equiv‐
68                alent to the device argument to mount(8).
69
70              • 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
74
75
76       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
80
81              • 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
85              • 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
95              • 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
99              • 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
104
105
106       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
110
111       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
115
116       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
120

EXAMPLES

122       $ podman volume create myvol
123
124       $ podman volume create
125
126       $ podman volume create --label foo=bar myvol
127
128       # podman volume create --opt device=tmpfs --opt type=tmpfs --opt o=size=2M,nodev,noexec myvol
129
130       # podman volume create --opt device=tmpfs --opt type=tmpfs --opt o=uid=1000,gid=1000 testvol
131
132       # podman volume create --driver image --opt image=fedora:latest fedoraVol
133
134
135

QUOTAS

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
142
143       Example /etc/fstab entry:
144
145       /dev/podman/podman-var /var xfs defaults,x-systemd.device-timeout=0,pquota 1 2
146
147
148
149       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
154
155       The xfs_quota tool can be used to assign a project ID  to  the  storage
156       driver directory, e.g.:
157
158       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
164
165
166       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
173

SEE ALSO

175       podman(1),     containers.conf(5),     podman-volume(1),      mount(8),
176       xfs_quota(8), xfs_quota(8), projects(5), projid(5)
177
178

HISTORY

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
185
186
187                                                       podman-volume-create(1)
Impressum