Command Reference

JuiceFS provides many commands to help you manage your filesystem. This page provides a detailed reference for these commands.

Overview

If you run juicefs by itself, it will print all the available subcommands. In addition, you can add -h/--help flag after each subcommand to get help information of that subcommand.

juicefs COMMAND [options]

COMMAND could be:
  auth      authorize a filesystem
  mount     mount a filesystem
  umount    umount a filesystem
  info      show information of file or directory
  lsof      list recent opened files
  import    import files from existing object storage
  rmr       remove all files/directories recursively
  snapshot  create or remove snapshots
  grep      parallelized file pattern searcher
  profile   analyze log (Experimental)
  benchmark run benchmark
  warmup    build cache for target directories/files
  version   show the version

Usage: juicefs [COMMAND] [options]

Add -h or --help after all commands, getting arguments list and help information.

Note

If juicefs is not placed in your $PATH, you should run the script with the path to the script. For example, if juicefs is placed in current directory, you should use ./juicefs. It is recommended to place juicefs in your $PATH for the convenience.

The documentation below gives you detailed information about each subcommand.

juicefs auth

Description

Set up the authentication information of your filesystem.

Synopsis

juicefs auth <name> --token=<token> [--accesskey=<access_key>] [--secretkey=<secret_key>]
               [--accesskey2=<access_key_2>] [--secretkey2=<secret_key_2>]

Options

<name>

The name of your filesystem.

--token=<token>

The JuiceFS token of your filesystem, you can find this token in the web console.

--accesskey=<access_key>

The access key of your bucket, you can read our guide on how to get access key and secret from your service provider.

--secretkey=<secret_key>

The secret key of your bucket, you can read our guide on how to get access key and secret from your service provider.

--accesskey2=<access_key_2>

The access key of your secondary bucket.

--secretkey2=<secret_key_2>

The secret key of your secondary bucket.

Notes

  1. The authentication information is stored in $HOME/.juicefs/<NAME>.conf.

  2. You will be prompted to enter the access key and secret if you didn’t provide it through the --token, --accesskey and --secretkey options.

  3. If your object storage provider allows accessing without key pairs (e.g. IAM), you can leave blank when you are asked for access and secret keys, or you can simply pass an empty string to the --accesskey and --secretkey options.

  4. Enable the JuiceFS replication in the setting panel of the Web Console, and mount with the --accesskey2 and --secretkey2 options.

juicefs mount

Description

Mount a filesystem.

Synopsis

juicefs mount <name> <mountpoint> [-f] [-b] [-v]
                [--log=<log_path>] [--http=ADDR]
                [--external | --internal] [--max-uploads=<max_uploads>]
                [--cache-dir=<cache_dir>] [--cache-size=<cache_size>]
                [--writeback] [--metacache]
                [--allow-other] [--allow-root] [--enable-xattr]
                ...

Options

<name>

The name of your filesystem.

<mountpoint>

The mountpoint of your filesystem.

-f

Run in the foreground mode.

-b

Run in the background mode.

--subdir=<subdir>

mount a sub-directory

--ioretries=<number>

(default: 30) number of retries for network failure

--http=ADDR

The bind address to serve files using HTTP, for example, localhost:8080.

--disallow-list

Disallow list a directory in WebDAV

--log=<log_path>

(default: /var/log/juicefs.log) The path of the log file.

-v

Run verbosely.

--no-update

use local config only

Object Storage Options

--external

Prefer to use the external entrypoint of the object storage service. This means the traffic of JuiceFS will go through the public network instead of the internal network.

--internal

Prefer to use the internal entrypoint of the object storage service. This means the traffic of JuiceFS will go through the internal network instead of the public network. (Applicable to some object storages that separate internal and external network domain names, e.g. Aliyun OSS, UCloud UFile, etc.)

--max-uploads=<max_uploads>

(default: 50) The maximum number of concurrent uploading connections.

--prefetch=<number>

(default: 3) number of concurrent prefetching

--upload-limit=<upload_limit>

(default: unlimited) The maximum bandwidth for upload (Mbps).

--delete-limit=<delete-limit>

(default: unlimited) The maximum invoke rate for object delete (QPS).

--get-timeout=<get_timeout>

The maximum time for getting a single object (seconds).

--put-timeout=<put_timeout>

The maximum time for upload a single object (seconds).

--gc

cleanup unused chunks after mounting immediately

--dry

do not delete chunks during GC

--flip

flip the two replicated bucket (prefer secondary bucket)

Security Options

--rsa-key=RSAKEY

Path to RSA private key (PEM). Passphrase will be asked or provided with JFS_RSA_PASSPHRASE environment variable.

Cache Options

--cache-dir=<cache_dir>
(default: /var/jfsCache or $HOME/.juicefs/cache) The path of the cache.
Separate multiple directories by :, add quotation mark if using wildcard match (*).
e.g. --cache-dir '/data*/jfsCache:/mydata*/jfsCache'
--cache-size=<cache_size>
(default: 1G) The maximum size of the cache. The default unit is MiB.
Will be evenly distributed to each directory in multiple directories mode.
--free-space-ratio=<free_space_ratio>

(default: 0.2) The minimum size of the cache directory (ratio).

--buffer-size=<buffer_size>

(default: 300) The maximum memory size of read and write data buffer (MiB).

--cache-mode=<cache_mode>

(default: 0600) Permission mode of cache files.

--cache-group=<cache_group>

(default: no sharing) the name of group to join and provide remote cache

--no-sharing

(default: false) do not share cached blocks to others

--writeback

(default: false) data will be written to local disk first, and be uploaded to object storage asynchronously in the background.

--cache-partial-only

(default: false) If only cache the blocks for small reads

--metacache

Enable metadata caching in local memory.

--metacacheto=<metacacheto>

(default: 300) Expiration of the meta cache (seconds).

--max-cached-inodes=MAXCACHEDINODES

(default: 5000000) the max number of cached inodes

--opencache

Open a file based on cached metadata.

--attrcacheto=<attrcacheto>

(default: 1) Duration for the attributes of file and directory cached in the kernel (seconds) .

--entrycacheto=<entrycacheto>

(default: 1) Duration for the file entry cached in the kernel (seconds).

--direntrycacheto=<direntrycacheto>

(default: 1) Duration for the directory entry cached in the kernel (seconds).

FUSE Options

--allow-other

Allow accesses from other users. This option is enabled by default when you are running as root user. You need to enable this feature explicitly otherwise.

--enable-xattr

Enable extended attributes (xattr) support.

--enable-acl

Enable POSIX ACL support.

--no-posix-lock

Disable POSIX lock support.

--no-bsd-lock

Disable BSD lock support.

-o FUSE_OPTS

other FUSE options

-o writeback_cache

Enable kernel writeback cache for 3.15+ Linux kernel, boost the performance dramatically for random write and small write.

See how to mount a filesystem in the document Getting Started.

Experimental Options

--min-balance-diff=MINBALANCEDIFF

When the inodes difference between the current zone and the zone with the least inodes exceeds this value, the metadata will be automatically balanced.

--min-dir-inodes=MINDIRINODES

When the number of directories in the current path exceeds this value, the metadata is automatically balanced.

--max-space=MAXSPACE

limit the total space in GiB (default: no limit)

--source-dir=SOURCEDIR

Use JuiceFS as cache for a directory

--refresh-interval=REFRESHINTERVAL

checking for update (seconds)

Deprecated Options

Warning

The following are the options that have been deprecated by JuiceFS!

--async

see --writeback

--ssl

Use HTTPS to access object store (always enabled)

--dircache

see --metacache

-d

see -v

--cacheDir=CACHEDIR

see --cache-dir

--cacheSize=CACHESIZE

see --cache-size

--allow-root

allow root to access (use --allow-other instead)

--no-sync

do not sync the replicated object store

--batch=BATCH

number of seconds to wait to combine multiple small files as single object

juicefs umount

Description

Umount a JuiceFS file system.

Synopsis

juicefs umount <mountpoint> [options]

Options

-f --force

Umount it forcibly.

juicefs info

Description

Show information about the file or directory stored in JuiceFS.

Synopsis

juicefs info <path> [-n | --plain]

Options

<path>

The path to the file you are querying.

-n --plain

Show sizes in bytes.

Examples

Show information of a directory.

# juicefs info /jfs/logs
/jfs/logs:
 inodes:              4      # inode total
  directories:        2      # directory total
  files:              2      # file total
 chunks:              44     # chunk total of all files
 length:              2.91G  # real size of all files
 size:                2.91G  # billable size, every file and directory is aligned to 4KB as minimum billable size

Show information of a file.

# juicefs info --plain /jfs/daily-log.tar
/jfs/daily-log.tar:
 inode:       2955        # inode ID of the file
 length:      3128903680  # real size of the file
 size:        3128950784    # billable size, minimum is 4KB
 chunks:      47          # chunk total and detail, maximum 64MB for each chunk
   0: 58597 67108864 0 67108864 # location in the file, chunk ID, length of chunk, real start location, length
   1: 58598 67108864 0 67108864
   ...
   45: 58661 67108864 0 67108864
   46: 58662 41895936 0 41895936

juicefs lsof

Description

List recently (within 10 minutes) opened files in JuiceFS.

Synopsis

juicefs lsof <path>

juicefs import

Description

Import files already existing in the object storage without reuploading.

Synopsis

juicefs import <uri> <dst> [-v] [--name=<name>] [--mode=<mode>]

Options

<uri>

The URI of the file you are importing. It should be in the format of <bucket_name>[.<domain>][/<prefix>].

<dst>

The destination of the imported file.

--name=<name>

The name of the filesystem. This is required in systems other than Linux.

--mode=<mode>

Mode (Unix permissions) of imported files.

-v

Run verbosely.

Notes

  1. The imported file will be read-only. However, you can still modify other attributes – e.g. filename, permissions – of the files and directories.

  2. If you delete the imported file in JuiceFS, the data stored in your object storage will NOT be deleted.

juicefs rmr

Description

Remove all the files and subdirectories, similar to rm -rf, but much faster.

It will try to remove them using current uid/gid, ignore those that can’t be removed, return the number of removed files/directories, the number of left ones. If trash is enabled, the removed files are removed into trash.

Synopsis

juicefs rmr <dir> [-h]

juicefs snapshot

Description

Manage JuiceFS snapshots. Snapshots are snapshots of your data at a certain time. It is a common technology used in data backup. JuiceFS will not create a copy of your data when you create a snapshot. It will only create a copy when there are some changes made to the original data (i.e. copy-on-write).

Synopsis

juicefs snapshot <src> <dst> [-f | --force] [-c | --copy]  # create a snapshot
juicefs snapshot -d <dst> [-f | --force]  # delete a snapshot

Options

<src>

The path to the file you are creating the snapshot from.

<dst>

The locate where you want to store your snapshot.

-d --delete

Remove the snapshot.

-f --force

Overwrite existing snapshot, or remove the snapshot arbitrarily.

-c --copy

Use current user’s uid, gid and umask to create the snapshot. Otherwise it will use permission information of the file you are creating snapshot.

juicefs grep

Description

Parallelized file pattern searcher.

Synopsis

juicefs grep [PATTERN] PATH ... [options]

Options

[PATTERN]

Support simple pattern and basic regular expression.

PATH

Search path and files.

-j JOBS --jobs=JOBS

Number of parallel jobs (default is number of CPU cores).

-e PATTERNS --regexp PATTERNS

This option is most useful when multiple -e options are used to specify multiple patterns, or when a pattern begins with a dash (-).

-E extended-regexp

Interpret pattern as an extended regular expression.

-H

Always print filename headers with output lines.

-n --line-number

Each output line is preceded by its relative line number in the file, starting at line 1.

-i --ignore-case

Perform case insensitive matching. By default, it is case sensitive.

-v --invert-match

Selected lines are those not matching any of the specified patterns.

juicefs profile

Description

Collect and analyze the file system’s oplog (operation log).

Synopsis

juicefs profile [options]

Options

-x PATH --path=PATH

The path of log, default path is /jfs.

-f FILE --file=FILE
The filename of log, default filename is .ophistory.
For the differences between log files please refer to The .oplog virtual file in the mount directory.
-g GROUP_BY --group-by=GROUP_BY

Group the output by a specific attribute (default by cmd), choose from [uid, pid, cmd].

-s SORT_BY --sort-by=SORT_BY

Sort the output by a specific column (default by total_time), choose from [group, number, avg_time, total_time].

-u FILTER_BY_UID --filter-by-uid=FILTER_BY_UID

Filter the output by one or multiple keywords on the UID column, please separate multi keywords by comma (,).

-p FILTER_BY_PID --filter-by-pid=FILTER_BY_PID

Filter the output by one or multiple keywords on the PID column, please separate multi keywords by comma (,).

-w WINDOW_SIZE --window-size=WINDOW_SIZE

The window size of collect oplog, accept float value, 60 seconds by default.

-i FLUSH_INTERVAL --flush-interval=FLUSH_INTERVAL

The interval of flush output, accept float value, 2 seconds by default.

juicefs benchmark

Description

Run benchmark, including read/write/stat big/small files.

Synopsis

juicefs benchmark [options] path-to-test

Options

--dest=DEST

(default: /jfs/benchmark) path to run benchmark

--block-size=BLOCK_SIZE

(default: 1MiB) block size in MiB

--bigfile-file-size=BIGFILE_FILE_SIZE

(default: 1024MiB) size of big file in MiB

--smallfile-file-size=SMALLFILE_FILE_SIZE

(default: 0.1MiB) size of small file in MiB

--smallfile-count=SMALLFILE_COUNT

(default: 100) number of small files

juicefs warmup

Description

Warm-up cache for the files

Synopsis

juicefs warmup [PATH] [options]

Options

-f LISTFILE, --listfile=LISTFILE

file containing a list of paths (one path per line)

-c CONCURRENT, --concurrent=CONCURRENT

(default: 50) number of concurrent workers

-b

run in background

juicefs version

Description

Show the JuiceFS version information.

Synopsis

juicefs version [options]

Options

-u --upgrade

Upgrade the JuiceFS client to latest version.