Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
podman-volume-create(1)	    General Commands Manual    podman-volume-create(1)

NAME
       podman-volume-create - Create a new volume

SYNOPSIS
       podman volume create [options] [name]

DESCRIPTION
       Creates	an  empty volume and prepares it to be used by containers. The
       volume can be created with a specific name, if a	name is	 not  given  a
       random  name  is	generated. You can add metadata	to the volume by using
       the --label flag	and driver options can be set using the	--opt flag.

OPTIONS
   --driver, -d=driver
       Specify the volume driver name (default local).	There are two  drivers
       supported by Podman itself: local and image.

       The  local  driver  uses	a directory on disk as the backend by default,
       but can also use	the mount(8) command to	mount a	filesystem as the vol-
       ume if --opt is specified.

       The image driver	uses an	image as the backing store of for the  volume.
       An overlay filesystem is	created, which allows changes to the volume to
       be committed as a new layer on top of the image.

       Using  a	value other than local or image, Podman	attempts to create the
       volume using a volume plugin with the given name.  Such plugins must be
       defined in the volume_plugins section of	the containers.conf(5) config-
       uration file.

   --gid=gid
       Set the GID that	the volume will	be created as. Differently than	 --opt
       o=gid=*gid*,  the specified value is not	passed to the mount operation.
       The specified GID will own the volume's mount point directory  and  af-
       fects the volume	chown operation.

   --help
       Print usage statement

   --ignore
       Don't  fail  if the named volume	already	exists,	instead	just print the
       name. Note that the new options are not applied to the existing volume.

   --label, -l=label
       Set metadata for	a volume (e.g.,	--label	mykey=value).

   --opt, -o=option
       Set driver specific options.  For the default driver, local,  this  al-
       lows a volume to	be configured to mount a filesystem on the host.

       For the local driver the	following options are supported: type, device,
       o, and [no]copy.

       • The type option sets the type of the filesystem to be mounted,	and is
	 equivalent to the -t flag to mount(8).

       • The device option sets	the device to be mounted, and is equivalent to
	 the device argument to	mount(8).

       • The  copy  option enables copying files from the container image path
	 where the mount is created to the newly created volume	on  the	 first
	 run.  copy is the default.

       The  o  option  sets  options  for  the mount, and is equivalent	to the
       filesystem options (also	-o) passed to mount(8) with the	following  ex-
       ceptions:

       • The  o	 option	supports uid and gid options to	set the	UID and	GID of
	 the created volume that are not normally supported by mount(8).

       • The o option supports the size	option to set the maximum size of  the
	 created volume, the inodes option to set the maximum number of	inodes
	 for  the volume, and noquota to completely disable quota support even
	 for tracking of disk usage.  The size	option	is  supported  on  the
	 "tmpfs" and "xfs[note]" file systems.	The inodes option is supported
	 on  the  "xfs[note]"  file  systems.	Note:  xfs filesystems must be
	 mounted with the prjquota flag	 described  in	the  xfs_quota(8)  man
	 page. Podman will throw an error if they're not.

       • The o option supports using volume options other than the UID/GID op-
	 tions with the	local driver and requires root privileges.

       • The o options supports	the timeout option which allows	users to set a
	 driver	 specific timeout in seconds before volume creation fails. For
	 example, --opt=o=timeout=10 sets a driver timeout of 10 seconds.

       Note Do not confuse the --opt,-o	create option with the	-o  mount  op-
       tion.   For  example,  with podman volume create, use -o=o=uid=1000 not
       -o=uid=1000.

       For the image driver, the only supported	option is image, which	speci-
       fies  the  image	the volume is based on.	 This option is	mandatory when
       using the image driver.

       When not	using the local	and  image  drivers,  the  given  options  are
       passed  directly	 to the	volume plugin. In this case, supported options
       are dictated by the plugin in question, not Podman.

   --uid=uid
       Set the UID that	the volume will	be created as. Differently than	 --opt
       o=uid=*uid*,  the specified value is not	passed to the mount operation.
       The specified UID will own the volume's mount point directory  and  af-
       fects the volume	chown operation.

QUOTAS
       podman  volume  create  uses XFS	project	quota controls for controlling
       the size	and the	number of inodes of  builtin  volumes.	The  directory
       used  to	 store	the  volumes must be an	XFS file system	and be mounted
       with the	pquota option.

       Example /etc/fstab entry:

       /dev/podman/podman-var /var xfs defaults,x-systemd.device-timeout=0,pquota 1 2

       Podman generates	project	IDs for	each builtin volume, but these project
       IDs need	to be unique for the XFS file system. These project IDs	by de-
       fault are generated randomly, with a potential for overlap  with	 other
       quotas on the same file system.

       The  xfs_quota  tool  can be used to assign a project ID	to the storage
       driver directory, e.g.:

       echo 100000:/var/lib/containers/storage/overlay >> /etc/projects
       echo 200000:/var/lib/containers/storage/volumes >> /etc/projects
       echo storage:100000 >> /etc/projid
       echo volumes:200000 >> /etc/projid
       xfs_quota -x -c 'project	-s storage volumes' /<xfs mount	point>

       In the example above we are configuring the overlay storage driver  for
       newly  created  containers as well as volumes to	use project IDs	with a
       start offset.  All containers are assigned larger project IDs (e.g.  >=
       100000).	  All  volume assigned project IDs larger project IDs starting
       with 200000.  This prevents xfs_quota management	 conflicts  with  con-
       tainers/storage.

EXAMPLES
       Create empty volume.

       $ podman	volume create

       Create empty named volume.

       $ podman	volume create myvol

       Create empty named volume with specified	label.

       $ podman	volume create --label foo=bar myvol

       Create tmpfs named volume with specified	size and mount options.

       # podman	volume create --opt device=tmpfs --opt type=tmpfs --opt	o=size=2M,nodev,noexec myvol

       Create tmpfs named volume testvol with specified	options.

       # podman	volume create --opt device=tmpfs --opt type=tmpfs --opt	o=uid=1000,gid=1000 testvol

       Create volume overriding	the owner UID and GID.

       # podman	volume create --uid 1000 --gid 1000 myvol

       Create  image  named volume using the specified local image in contain-
       ers/storage.

       # podman	volume create --driver image --opt image=fedora:latest fedoraVol

MOUNT EXAMPLES
       podman volume create allows the type,  device,  and  o  options	to  be
       passed to mount(8) when using the local driver.

s3fs-fuse
       s3fs-fuse or just s3fs, is a fuse filesystem that allows	s3 prefixes to
       be mounted as filesystem	mounts.

       Installing:

       $ doas dnf install s3fs-fuse

       Simple usage:

       $ s3fs --help
       $ s3fs -o use_xattr,endpoint=aq-central-1 bucket:/prefix	/mnt

       Equivalent through mount(8)

       $ mount -t fuse.s3fs -o use_xattr,endpoint=aq-central-1 bucket:/prefix /mnt

       Equivalent through podman volume	create

       $ podman	volume create s3fs-fuse-volume -o type=fuse.s3fs -o device=bucket:/prefix -o o=use_xattr,endpoint=aq-central-1

       The volume can then be mounted in a container with

       $ podman	run -v s3fs-fuse-volume:/s3:z --rm -it fedora:latest

       Please see the available	options	on their wiki.

   Using with other container users
       The  above example works	because	the volume is mounted as the host user
       and inside the container	root is	mapped to the user in the host.

       If the mount is accessed	by a different user inside  the	 container,  a
       "Permission denied" error will be raised.

       $ podman	run --user bin:bin -v s3fs-fuse-volume:/s3:z,U --rm -it	fedora:latest
       $ ls /s3
       # ls: /s3: Permission denied

       In FUSE-land, mounts are	protected for the user who mounted them; spec-
       ify  the	 allow_other mount option if other users need access.  > Note:
       This will remove	the normal fuse	security measures on the mount	point,
       after which, the	normal filesystem permissions will have	to protect it

       $ podman	volume create s3fs-fuse-other-volume -o	type=fuse.s3fs -o device=bucket:/prefix	-o o=allow_other,use_xattr,endpoint=aq-central-1
       $ podman	run --user bin:bin -v s3fs-fuse-volume:/s3:z,U --rm -it	fedora:latest
       $ ls /s3

   The Prefix must exist
       s3fs will fail to mount if the prefix does not exist in the bucket.

       Create a	s3-directory by	putting	an empty object	at the desired prefix/
       key

       $ aws s3api put-object --bucket bucket --key prefix/

       If  performance	is  the	priority, please check out the more performant
       goofys.

	      FUSE filesystems exist for Google	Cloud Storage and  Azure  Blob
	      Storage

SEE ALSO
       podman(1),      containers.conf(5),     podman-volume(1),     mount(8),
       xfs_quota(8), xfs_quota(8), projects(5),	projid(5)

HISTORY
       January 2020, updated with information on  volume  plugins  by  Matthew
       Heon  mheon@redhat.com  <mailto:mheon@redhat.com> November 2018,	Origi-
       nally	compiled    by	   Urvashi     Mohnani	   umohnani@redhat.com
       <mailto:umohnani@redhat.com>

						       podman-volume-create(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=podman-volume-create&sektion=1&manpath=FreeBSD+Ports+15.0>

home | help