CLI Commands

Note: Mapfs doesn't enable GUI.

mapfs provides a set of CLI commands for users to interact with the filesystem:

List all available commands

  # list all available commands
  $ mapfs

  # help message
  $ mapfs --help
  $ mapfs -h

  # version
  $ mapfs --version
  $ mapfs -v

  # help message for a specific command
  $ mapfs <command> --help
  
  # e.g. help message for "mount" command
  $ mapfs mount
  
  # e.g. help message for "umount" command
  $ mapfs umount

  # e.g. help message for "add" command
  $ mapfs add

Add/Remove one volume

Adding one volume means creating a mapping between a cloud storage and a local volume.

Removing one volume means deleting the mapping between a cloud storage and a local volume.

  # mapping AWS S3
  # mapfs add <VolumeName> aws <AccessKey> <SecretKey> <BucketName> <Region> [Options]
  # for example
  $ mapfs add s3_volume aws AKIAIOSFODNN7EXAMPLE wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY mybucket us-west-2

  # mapping Azure Blob Storage
  # mapfs add <VolumeName> azure "ConnectionString" <ContinerName> [Options]
  # for example
  $ mapfs add azure_volume azure "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net" mycontainer

  # mapping Google Cloud Storage
  # mapfs add <VolumeName> gcs <AccessKey> <SecretKey> <BucketName> <Region> [Options]
  # for example
  $ mapfs add gcs_volume gcs GOOG1E0S3CR3T4CC3SSK3Y wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY mybucket us-west1

  # mapping a Wasabi bucket
  # mapfs add <VolumeName> wasabi <AccessKey> <SecretKey> <BucketName> <Region> [Options]
  # for example
  $ mapfs add wasabi_volume wasabi AKIAIOSFODNN7EXAMPLE wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY mybucket us-west-1

  # mapping CloudFlare R2
  # mapfs add <VolumeName> cloudflare <AccessKey> <SecretKey> <BucketName> <AccountID> [Options]
  # for example
  $ mapfs add cloudflare_volume cloudflare AKIAIOSFODNN7EXAMPLE wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY mybucket 12345666633

  # mapping Aliyun OSS
  # mapfs add <VolumeName> aliyun <AccessKey> <SecretKey> <BucketName> <Region> [Options]
  # for example
  $ mapfs add aliyun_volume aliyun AKIAIOSFODNN7EXAMPLE wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY mybucket cn-hangzhou

  # mapping Oracle Cloud Storage
  # mapfs add <VolumeName> oracle <AccessKey> <SecretKey> <BucketName> <Region> <OCI-Namespace> [Options]
  # for example
  $ mapfs add oracle_volume oracle AKIAIOSFODNN7EXAMPLE wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY mybucket us-ashburn-1 mynamespace

  # list all configured volumes
  $ mapfs list

  # remove one volume
  # mapfs remove <VolumeName>
  # Note: Removing one volume will delete the mapping between the cloud storage and the local volume, and delete the local cache data of this volume, but won't delete any data in the cloud storage.
  # for example
  $ mapfs remove s3_volume

Configure Cache parameters

By default, the cache directory relies on /opt/mapfs/cache directory. And the default data cache size is 100GB.

Note:
1, Cache size is in GB.
2, Shrinking cache size is not supported.
3, Changing cache directory will delete all cached data.

User can configure the cache parameters using the following commands:

1, Configure cache directory and size during creating a volume:

  # mapfs add <VolumeName> <CloudProvider> <AccessKey> <SecretKey> <BucketName> <Region> cache-dir=<CacheDirectory> cache-size=<CacheSize>
  # for example
  $ mapfs add s3_volume aws AKIAIOSFODNN7EXAMPLE wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY mybucket us-west-2 cache-dir=/data/mapfs_cache cache-size=200

  # only change the cache size
  $ mapfs add s3_volume aws AKIAIOSFODNN7EXAMPLE wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY mybucket us-west-2 cache-size=10

2, Configure cache directory and size for an existing volume:

  # mapfs configure <VolumeName> cache-dir=<CacheDirectory> cache-size=<CacheSize>
  # for example
  $ mapfs configure s3_volume cache-dir=/data/mapfs_cache cache-size=200

  # only change the cache size
  $ mapfs configure s3_volume cache-size=10
Note:before configuring, the volume must be in the Unmount status

Mount/Unmount one volume

After mouting one configured volume, users can access the cloud storage through the local mount point.

Note:
1, "iouring" mount option is recommended for extremely high IO performance scenarios with small size read requests.
for example, when the read request size is 4KB or even smaller, users can enable "iouring" to improve IO performance.

2, "mount" and "umount" commands require root privileges.

  # mount one volume
  # mapfs mount <VolumeName> <MountPoint> [iouring]
  # for example
  $ mapfs mount s3_volume /mnt/s3_volume

  # sometimes, users may want to enable "fuse over io uring" to improve IOPS, then they can add "iouring" option when mounting the volume
  $ mapfs mount s3_volume /mnt/s3_volume iouring

  # after mouting, you can access the cloud storage through the local mount point
  $ ls /mnt/s3_volume
  $ cat /mnt/s3_volume/file.txt
  $ mkdir /mnt/s3_volume/new_folder

Unmounting one volume will disconnect the mapping between the cloud storage and the local mount point, but won't delete any data in cloud storage.


  # unmount one volume
  # sudo mapfs umount <VolumeName>, or
  # sudo umount <MountPoint> [-f]
  # for example
  $ sudo mapfs umount s3_volume
  $ sudo umount /mnt/s3_volume
  $ sudo umount /mnt/s3_volume -f

Get volume runtime status

Displays the IO Status, Cache Hit/Miss Statistics information for all the mounted volumes.


  # get runtime status for all mounted volumes
  $ mapfs status