Command Reference
JuiceFS provides many commands to help you manage your file system. 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
doctor collect diagnose information
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.
juicefs auth
Authenticate the client against JuiceFS Console, and fetch or update configuration file for the JuiceFS Volume, and stored in $HOME/.juicefs/$VOL_NAME.conf
. This command is useful when you need to deploy JuiceFS via script, or use self-hosted object storage for onpremise deployment.
Synopsis
juicefs auth NAME [options]
Options
Items | Description |
---|---|
NAME | The name of your file system. |
--token=TOKEN | The JuiceFS token of your file system, you can find this token in the web console. |
--bucket=BUCKET | name or endpoint of the bucket (optional) |
--access-key=ACCESSKEY | The access key of your bucket, you can read our guide on how to get access key and secret from your service provider. |
--secret-key=SECRETKEY | The secret key of your bucket, you can read our guide on how to get access key and secret from your service provider. |
--session-token=SESSIONTOKEN | the session token to access the bucket (optional) |
--bucket2=BUCKET2 | name or endpoint of the secondary bucket (optional) |
--access-key2=ACCESSKEY2 | When data replication is enabled, use this parameter to specify the access key for the secondary bucket. Learn more at Cross-region data replication. |
--secret-key2=SECRETKEY2 | When data replication is enabled, use this parameter to specify the secret key for the secondary bucket. Learn more at Cross-region data replication. |
--session-token2=SESSION_TOKEN2 | the session token to access the bucket (optional) |
--passphrase=PASSPHRASE | Passphrase for encrypted key, see Data Encryption for more. |
--subdir=SUBDIR | Specify a sub-directory for mount, you can also create ACL to restrict client access to specific sub-directories, learn more at Client Access Control |
--conf-dir=CONFDIR | a directory for configuration (default: /root/.juicefs ) |
--no-update | Client will by default obtain latest config from JuiceFS Web Console, set to true to disable this behavior, and then client will no longer talk to JuiceFS Console when mounting. |
Notes
- You will be prompted to enter the access key and secret if you didn't provide it through the
--token
,--accesskey
and--secretkey
options. - If your object storage provider allows accessing without key pairs (e.g. AWS 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.
juicefs mount
Mount the file system. You must provide the token of the file system (check the "File System Settings" in the website console), and the key pair to access the object storage (refer to How to Get Object Storage Access Key and Secret Key for details).
If the configuration file is not generated by the auth
subcommand before mounting the file system, the client will ask you to provide the file system token and the key pair to access the object storage API separately through command line interaction.
You can mount JuiceFS as root or normal user, but due to permission issues, cache and client log locations will be different, read option descriptions below for more.
Synopsis
juicefs mount NAME MOUNTPOINT [options]
Options
Items | Description |
---|---|
NAME | The name of your file system. |
MOUNTPOINT | The mount point for your file system. |
--update-fstab | add or update entry in /etc/fstab, when applicable, see Auto-mount on boot. |
-f , --foreground | Run in the foreground mode, client logs will print directly to console, often used in debugging. |
-b , --background | Run in the background mode, which is the default behavior. |
--subdir=SUBDIR | Specify a sub-directory for mount, you can also create ACL to restrict client access to specific sub-directories, learn more at Client Access Control |
--ioretries=IORETRIES | (default: 30) number of retries for network failure |
--http=ADDRESS | The bind address to serve files using HTTP, for example, localhost:8080 . |
--disallow-list | Disallow list a directory in WebDAV |
--log=LOGPATH | Log file location, defaults to /var/log/juicefs.log (when running as root) or ~/.juicefs/log/juicefs.log (when running as normal user). |
-v , --verbose | Print verbose log. |
--no-update | Client will by default obtain latest config from JuiceFS Web Console, set to true to disable this behavior, and then client will no longer talk to JuiceFS Console when mounting. |
Object Storage Options
Items | Description |
---|---|
--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=MAXUPLOADS | Max number of concurrent uploads (default: 20), increasing upload concurrency usually demands higher --buffer-size , learn more at Read/Write Buffer. |
--prefetch=PREFETCH | When a block is randomly read by a small offset range, the whole block is scheduled for download asynchronously, this is called prefetch in JuiceFS. This parameter controls the number of prefetch concurrency (default: 1), set to 0 to disable this behavior. In some situation, prefetch causes read amplification, see read amplification. |
--upload-limit=UPLOADLIMIT | Maximum bandwidth for upload in Mbps, default to 0 (unlimited). Apart from bandwidth control, this parameter can also be used for system load control with high throughput scenarios. |
--download-limit=DOWNLOADLIMIT | Maximum bandwidth for download in Mbps, default to 0 (unlimited). Apart from bandwidth control, this parameter can also be used for system load control with high throughput scenarios. |
--delete-limit=DELETELIMIT | Maximum QPS for deletion default to 0 (unlimited). Use this if for example, some object storage limit API calls. |
--get-timeout=GETTIMEOUT | Max number of seconds to get an object (default: 60), may need to increase this in low bandwidth conditions, see Read / Write error. |
--put-timeout=PUTTIMEOUT | Max number of seconds to upload an object (default: 60), may need to increase this in low bandwidth conditions, see Read / Write error. |
--gc | After mount, check for object storage garbage (unreferenced objects) and delete them. We do not expect JuiceFS to produce leak in object storage, but if there's relevant suspicions, run gc to check and cleanup. |
--dry | Only check for garbage in object storage when running gc, but do not delete them. |
--flip | When data replication is enabled, use secondary bucket as primary bucket. Learn more at Cross-region data replication. |
Security Options
Items | Description |
---|---|
--rsa-key=RSAKEY | Path to RSA private key (PEM). Passphrase will be asked or provided with JFS_RSA_PASSPHRASE environment variable. |
Cache Options
Read Cache to understand JuiceFS's cache design.
Items | Description |
---|---|
--cache-dir=CACHEDIR | Cache directory, defaults to /var/jfsCache (when running as root) or $HOME/.juicefs/cache (when running as normal user). Separate multiple directories by : , add quotation mark if using wildcard match (* ). e.g. --cache-dir '/data*/jfsCache:/mydata*/jfsCache' |
--cache-size=CACHESIZE | Local cache size limit in MiB, default to 102400 (100GiB). When multiple directories are used as cache directory, --cache-size limits the total size sum (split evenly). |
--free-space-ratio=FREESPACE | Minimum free space ratio on cache disk (default: 0.2), if Client write cache is enabled, this option also controls write cache size |
--buffer-size=BUFFERSIZE | the total size of memory used for read/write buffering in MiB (default: 300), learn more at Read/Write Buffer |
--cache-mode=CACHEMODE | file permission for cached blocks (default: 0600) |
--cache-group=CACHEGROUP | the name of group to join and provide remote cache (default: no sharing) |
--subgroups=SUBGROUPS | the number of sub-groups in a cache group (default: 0) |
--group-ip=GROUPIP | set IP address for cache group, usually this is only needed when you must manually specify network interface in a multi-NIC node |
--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 |
--fill-group-cache | build remote cache for new written blocks |
--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 for read using cached metadata, default to false, which means every open operation access metadata service to check for file changes. If file is frequently opened and scarcely changed, consider enabling --opencache to further improve read performance. |
--attrcacheto=ATTRCACHETO | File attribute cache timeout in seconds, default to 1. |
--entrycacheto=ENTRYCACHETO | File entry cache timeout in seconds, default to 1. |
--direntrycacheto=DIRENTRYCACHETO | Directory entry cache timeout in seconds (default: 1). |
--readdir-cache | cache readdir in kernel (require Linux kernel 4.20+) |
FUSE Options
Items | Description |
---|---|
--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, default to false, which is recommended for most scenarios because xattr comes with its own overhead. |
--enable-acl | Enable POSIX ACL support. |
--no-posix-lock | Disable POSIX lock support. |
--no-bsd-lock | Disable BSD lock support. |
--block-interrupt=BLOCKINTERRUPT | (default: 1) number of seconds to block interruption |
-o FUSE_OPTS | Other FUSE options. For example, enabling FUSE write cache through -o writeback_cache can greatly improve the performance of random writes and fragmented writes (requires Linux Kernel 3.15 and above). |
See how to mount a file system in the document Getting Started.
Experimental Options
Items | Description |
---|---|
--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=SOURCE | Use JuiceFS as cache for a directory |
--refresh-interval=REFRESHINTERVAL | checking for update (seconds) |
--update-source | propagate all changes to source |
--fsck | check consistency |
Deprecated Options
The follow options have been deprecated by JuiceFS, only reserved for reference.
Items | Description |
---|---|
--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 |
--keep-fd | keep FUSE session alive |
juicefs umount
Umount a JuiceFS file system. This command handles the platform differences, i.e. umount
in Linux and diskutil unmount
in macOS.
Synopsis
juicefs umount PATH [options]
Options
Items | Description |
---|---|
PATH | The mount point for your file system. |
-f --force | Umount it forcibly. |
juicefs info
Show information about the file or directory stored in JuiceFS.
Synopsis
juicefs info PATH [options]
Options
Items | Description |
---|---|
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
List recently (within 10 minutes) opened files in JuiceFS.
Synopsis
juicefs lsof PATH
juicefs import
juicefs import
only collects metadata of the existing files, and save to the metadata engine of the JuiceFS cloud service, this gives JuiceFS access to existing object storage files, but the file data will remain in the object storage as is. For imported files, you can change the file properties as you like, e.g. file name, permissions, etc. But these changes will not be reflected in the object storage. Similarly, deleting imported files in JuiceFS will only delete the associating metadata, not the actual files in the object storage.
Also, imported files will not be able to utilize the powerful JuiceFS cache design.
As explained above, while juicefs import
can bring basic access for existing files in object storage, it cannot provide a high-performance experience, so if this is a concern, we strongly recommend you to fully copy existing data into JuiceFS. Juicesync is the recommended tool if you need to move data in and out of JuiceFS, but thanks to POSIX compatibility of JuiceFS, you can use any other tool you like.
Synopsis
juicefs import URI DST [-v] [--name=<name>] [--mode=<mode>]
Options
Items | Description |
---|---|
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 file system. This is required in systems other than Linux. |
--mode=MODE | Mode (Unix permissions) of imported files. |
-v | Run verbosely. |
--conf-dir=CONFDIR | a directory for configuration (default: /root/.juicefs ) |
--no-update | client will by default obtain latest config from JuiceFS Web Console, set to true to disable this behavior (usually not needed) |
Notes
- The imported file will be read-only. However, you can still modify other attributes (e.g. filename, permissions) of the files and directories.
- If you delete the imported file in JuiceFS, the data stored in your object storage will NOT be deleted.
juicefs rmr
Remove all the files and subdirectories, similar to rm -rf
, except this command deals with metadata directly (bypassing POSIX API), thus is 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, deleted files are moved into trash. Files inside trash is still billable, read more at Trash.
Synopsis
juicefs rmr DIR
juicefs snapshot
Manage JuiceFS snapshots.
Taking a snapshot of your data at a certain time, and JuiceFS will create a copy of the corresponding metadata, without copying the actual file data in the object storage, so the snapshot process is much faster compared to a straightforward copy. Snapshots work in copy-on-write fashion, meaning it will only copy the original data when changes are introduced on relevant files.
Snapshotting creates a copy of relevant metadata and will result in an increase in bill, pay special attention when taking snapshots on directories with large amount of files.
Synopsis
juicefs snapshot SRC DST [-f|--force] [-c|--copy] # create a snapshot
juicefs snapshot -d DST [-f|--force] # delete a snapshot
Options
Items | Description |
---|---|
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
Parallelized file pattern searcher.
Synopsis
juicefs grep [PATTERN] PATH ... [options]
Options
Items | Description |
---|---|
[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
Performs basic profiling based on access log, and writes comprehensive statistics to command line output. Use this command to quickly identify the overall file system access pattern of your application, and assess performance.
Synopsis
juicefs profile [options]
Options
Items | Description |
---|---|
-x PATH --path=PATH | The directory path of access log, default to /jfs . |
-f FILE --file=FILE | The filename of the access log, default to .ophistory . Refer to Access Log for different types of access log. |
-g GROUP_BY --group-by=GROUP_BY | Group the output by a specific attribute, default to cmd , choose from uid , pid , cmd . |
-s SORT_BY --sort-by=SORT_BY | Sort the output by a specific column, default to 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 | Analysis time window, accept float value, default to 60 seconds. |
-i FLUSH_INTERVAL --flush-interval=FLUSH_INTERVAL | Flush output interval, accept float value, default to 2 seconds. |
juicefs benchmark
Run benchmark, including read/write/stat big/small files.
Synopsis
juicefs benchmark [options] path-to-test
Options
Items | Description |
---|---|
--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 doctor
Collect abundant debug information, including access log, client log, CPU stats, Goroutine stacktraces. When run into unexpected situations, JuiceFS team may asks you to collect information with this command, and send back the result to continue support.
We encourage you to also take a look at Troubleshooting Methods and Troubleshooting Cases, and try to solve some of the more frequently encountered problems by yourself.
Synopsis
juicefs doctor MOUNTPOINT
juicefs warmup
Download data to local cache in advance, to achieve better performance on application's first read. Executing this command in any cache group member will have the same effect.
Synopsis
juicefs warmup [PATH] [options]
Options
Items | Description |
---|---|
-f LISTFILE , --listfile=LISTFILE | file containing a list of paths (one path per line) |
-c CONCURRENT , --concurrent=CONCURRENT | Download concurrency, default to 50. If the download bandwidth of the object storage is small, you need to reduce the concurrency to make the warm-up process more stable. |
-b | run in background |
juicefs version
Show the JuiceFS version information. The update details of each version can be viewed on the "Release Notes".
Synopsis
juicefs version [options]
Options
Items | Description |
---|---|
-u --upgrade | Upgrade the JuiceFS client to latest version. |
-r --restart | Execute seamless remount, if client is upgraded. |