Command Reference
Running juicefs
by itself and it will print all available commands. In addition, you can add -h/--help
flag after each command to get more information, e.g., juicefs format -h
.
NAME:
juicefs - A POSIX file system built on Redis and object storage.
USAGE:
juicefs [global options] command [command options] [arguments...]
VERSION:
1.1.0
COMMANDS:
ADMIN:
format Format a volume
config Change configuration of a volume
quota Manage directory quotas
destroy Destroy an existing volume
gc Garbage collector of objects in data storage
fsck Check consistency of a volume
restore restore files from trash
dump Dump metadata into a JSON file
load Load metadata from a previously dumped JSON file
version Show version
INSPECTOR:
status Show status of a volume
stats Show real time performance statistics of JuiceFS
profile Show profiling of operations completed in JuiceFS
info Show internal information of a path or inode
debug Collect and display system static and runtime information
summary Show tree summary of a directory
SERVICE:
mount Mount a volume
umount Unmount a volume
gateway Start an S3-compatible gateway
webdav Start a WebDAV server
TOOL:
bench Run benchmarks on a path
objbench Run benchmarks on an object storage
warmup Build cache for target directories/files
rmr Remove directories recursively
sync Sync between two storages
clone clone a file or directory without copying the underlying data
GLOBAL OPTIONS:
--verbose, --debug, -v enable debug log (default: false)
--quiet, -q show warning and errors only (default: false)
--trace enable trace log (default: false)
--log-id value append the given log id in log, use "random" to use random uuid
--no-agent disable pprof (:6060) agent (default: false)
--pyroscope value pyroscope address
--no-color disable colors (default: false)
--help, -h show help (default: false)
--version, -V print version only (default: false)
COPYRIGHT:
Apache License 2.0
Auto completion
To enable commands completion, simply source the script provided within hack/autocomplete
directory. For example:
- Bash
- Zsh
source hack/autocomplete/bash_autocomplete
source hack/autocomplete/zsh_autocomplete
Please note the auto-completion is only enabled for the current session. If you want to apply it for all new sessions, add the source
command to .bashrc
or .zshrc
:
- Bash
- Zsh
echo "source path/to/bash_autocomplete" >> ~/.bashrc
echo "source path/to/zsh_autocomplete" >> ~/.zshrc
Alternatively, if you are using bash on a Linux system, you may just copy the script to /etc/bash_completion.d
and rename it to juicefs
:
cp hack/autocomplete/bash_autocomplete /etc/bash_completion.d/juicefs
source /etc/bash_completion.d/juicefs
Admin
juicefs format
Create and format a file system, if a volume already exists with the same META-URL
, this command will skip the format step. To adjust configurations for existing volumes, use juicefs config
.
Synopsis
juicefs format [command options] META-URL NAME
# Create a simple test volume (data will be stored in a local directory)
juicefs format sqlite3://myjfs.db myjfs
# Create a volume with Redis and S3
juicefs format redis://localhost myjfs --storage=s3 --bucket=https://mybucket.s3.us-east-2.amazonaws.com
# Create a volume with password protected MySQL
juicefs format mysql://jfs:mypassword@(127.0.0.1:3306)/juicefs myjfs
# A safer alternative
META_PASSWORD=mypassword juicefs format mysql://jfs:@(127.0.0.1:3306)/juicefs myjfs
# Create a volume with quota enabled
juicefs format sqlite3://myjfs.db myjfs --inodes=1000000 --capacity=102400
# Create a volume with trash disabled
juicefs format sqlite3://myjfs.db myjfs --trash-days=0
Options
Items | Description |
---|---|
META-URL | Database URL for metadata storage, see JuiceFS supported metadata engines for details. |
NAME | Name of the file system |
--force | overwrite existing format (default: false) |
--no-update | don't update existing volume (default: false) |
Data storage options
Items | Description |
---|---|
--storage=file | Object storage type (e.g. s3 , gs , oss , cos ) (default: file , refer to documentation for all supported object storage types) |
--bucket=/var/jfs | A bucket URL to store data (default: $HOME/.juicefs/local or /var/jfs ) |
--access-key=value | Access Key for object storage (can also be set via the environment variable ACCESS_KEY ), see How to Set Up Object Storage for more. |
--secret-key value | Secret Key for object storage (can also be set via the environment variable SECRET_KEY ), see How to Set Up Object Storage for more. |
--session-token=value | session token for object storage, see How to Set Up Object Storage for more. |
--storage-class value Added in v1.1 | the default storage class |
Data format options
Items | Description |
---|---|
--block-size=4096 | size of block in KiB (default: 4096). 4M is usually a better default value because many object storage services use 4M as their internal block size, thus using the same block size in JuiceFS usually yields better performance. |
--compress=none | compression algorithm, choose from lz4 , zstd , none (default). Enabling compression will inevitably affect performance. Among the two supported algorithms, lz4 offers a better performance, while zstd comes with a higher compression ratio, Google for their detailed comparison. |
--encrypt-rsa-key=value | A path to RSA private key (PEM) |
--encrypt-algo=aes256gcm-rsa | encrypt algorithm (aes256gcm-rsa, chacha20-rsa) (default: "aes256gcm-rsa") |
--hash-prefix | For most object storages, if object storage blocks are sequentially named, they will also be closely stored in the underlying physical regions. When loaded with intensive concurrent consecutive reads, this can cause hotspots and hinder object storage performance. Enabling --hash-prefix will add a hash prefix to name of the blocks (slice ID mod 256, see internal implementation), this distributes data blocks evenly across actual object storage regions, offering more consistent performance. Obviously, this option dictates object naming pattern and should be specified when a file system is created, and cannot be changed on-the-fly.Currently, AWS S3 had already made improvements and no longer require application side optimization, but for other types of object storages, this option still recommended for large scale scenarios. |
--shards=0 | If your object storage limit speed in a bucket level (or you're using a self-hosted object storage with limited performance), you can store the blocks into N buckets by hash of key (default: 0), when N is greater than 0, bucket should to be in the form of %d , e.g. --bucket "juicefs-%d" . --shards cannot be changed afterwards and must be planned carefully ahead. |
Management options
Items | Description |
---|---|
--capacity=0 | storage space limit in GiB, default to 0 which means no limit. Capacity will include trash files, if trash is enabled. |
--inodes=0 | Limit the number of inodes, default to 0 which means no limit. |
--trash-days=1 | By default, delete files are put into trash, this option controls the number of days before trash files are expired, default to 1, set to 0 to disable trash. |
juicefs config
Change config of a volume. Note that after updating some settings, the client may not take effect immediately, and it needs to wait for a certain period of time. The specific waiting time can be controlled by the --heartbeat
option.
Synopsis
juicefs config [command options] META-URL
# Show the current configurations
juicefs config redis://localhost
# Change volume "quota"
juicefs config redis://localhost --inodes 10000000 --capacity 1048576
# Change maximum days before files in trash are deleted
juicefs config redis://localhost --trash-days 7
# Limit client version that is allowed to connect
juicefs config redis://localhost --min-client-version 1.0.0 --max-client-version 1.1.0
Options
Items | Description |
---|---|
--yes, -y | automatically answer 'yes' to all prompts and run non-interactively (default: false) |
--force | skip sanity check and force update the configurations (default: false) |
Data storage options
Items | Description |
---|---|
--storage=file Added in v1.1 | Object storage type (e.g. s3 , gs , oss , cos ) (default: "file" , refer to documentation for all supported object storage types). |
--bucket=/var/jfs | A bucket URL to store data (default: $HOME/.juicefs/local or /var/jfs ) |
--access-key=value | Access Key for object storage (can also be set via the environment variable ACCESS_KEY ), see How to Set Up Object Storage for more. |
--secret-key value | Secret Key for object storage (can also be set via the environment variable SECRET_KEY ), see How to Set Up Object Storage for more. |
--session-token=value | session token for object storage, see How to Set Up Object Storage for more. |
--storage-class value Added in v1.1 | the default storage class |
--upload-limit=0 | bandwidth limit for upload in Mbps (default: 0) |
--download-limit=0 | bandwidth limit for download in Mbps (default: 0) |
Management options
Items | Description |
---|---|
--capacity value | limit for space in GiB |
--inodes value | limit for number of inodes |
--trash-days value | number of days after which removed files will be permanently deleted |
--encrypt-secret | encrypt the secret key if it was previously stored in plain format (default: false) |
--min-client-version value Added in v1.1 | minimum client version allowed to connect |
--max-client-version value Added in v1.1 | maximum client version allowed to connect |
--dir-stats Added in v1.1 | enable dir stats, which is necessary for fast summary and dir quota (default: false) |
juicefs quota
Added in v1.1
Manage directory quotas
Synopsis
juicefs quota command [command options] META-URL
# Set quota to a directory
juicefs quota set redis://localhost --path /dir1 --capacity 1 --inodes 100
# Get quota of a directory
juicefs quota get redis://localhost --path /dir1
# List all directory quotas
juicefs quota list redis://localhost
# Delete quota of a directory
juicefs quota delete redis://localhost --path /dir1
# Check quota consistency of a directory
juicefs quota check redis://localhost
Options
Items | Description |
---|---|
META-URL | Database URL for metadata storage, see "JuiceFS supported metadata engines" for details. |
--path value | full path of the directory within the volume |
--capacity value | hard quota of the directory limiting its usage of space in GiB (default: 0) |
--inodes value | hard quota of the directory limiting its number of inodes (default: 0) |
--repair | repair inconsistent quota (default: false) |
--strict | calculate total usage of directory in strict mode (NOTE: may be slow for huge directory) (default: false) |
juicefs destroy
Destroy an existing volume, will delete relevant data in metadata engine and object storage. See How to destroy a file system.
Synopsis
juicefs destroy [command options] META-URL UUID
juicefs destroy redis://localhost e94d66a8-2339-4abd-b8d8-6812df737892
Options
Items | Description |
---|---|
--yes, -y Added in v1.1 | automatically answer 'yes' to all prompts and run non-interactively (default: false) |
--force | skip sanity check and force destroy the volume (default: false) |
juicefs gc
If for some reason, a object storage block escape JuiceFS management completely, i.e. the metadata is gone, but the block still persists in the object storage, and cannot be released, this is called an "object leak". If this happens without any special file system manipulation, it could well indicate a bug within JuiceFS, file a GitHub Issue to let us know.
Meanwhile, you can run this command to deal with leaked objects. It also deletes stale slices produced by file overwrites. See Status Check & Maintenance.
Synopsis
juicefs gc [command options] META-URL
# Check only, no writable change
juicefs gc redis://localhost
# Trigger compaction of all slices
juicefs gc redis://localhost --compact
# Delete leaked objects
juicefs gc redis://localhost --delete
Options
Items | Description |
---|---|
--delete | delete leaked objects (default: false) |
--compact | compact all chunks with more than 1 slices (default: false). |
--threads=10 | number of threads to delete leaked objects (default: 10) |
juicefs fsck
Check consistency of file system.
Synopsis
juicefs fsck [command options] META-URL
juicefs fsck redis://localhost
Options
Items | Description |
---|---|
--path value Added in v1.1 | absolute path within JuiceFS to check |
--repair Added in v1.1 | repair specified path if it's broken (default: false) |
--recursive, -r Added in v1.1 | recursively check or repair (default: false) |
--sync-dir-stat Added in v1.1 | sync stat of all directories, even if they are existed and not broken (NOTE: it may take a long time for huge trees) (default: false) |
juicefs restore
Added in v1.1
Rebuild the tree structure for trash files, and put them back to original directories.
Synopsis
juicefs restore [command options] META HOUR ...
juicefs restore redis://localhost/1 2023-05-10-01
Options
Items | Description |
---|---|
--put-back value | move the recovered files into original directory (default: false) |
--threads value | number of threads (default: 10) |
juicefs dump
Dump metadata into a JSON file. Refer to "Metadata backup" for more information.
Synopsis
juicefs dump [command options] META-URL [FILE]
# Export metadata to meta-dump.json
juicefs dump redis://localhost meta-dump.json
# Export metadata for only one subdirectory of the file system
juicefs dump redis://localhost sub-meta-dump.json --subdir /dir/in/jfs
Options
Items | Description |
---|---|
META-URL | Database URL for metadata storage, see JuiceFS supported metadata engines for details. |
FILE | Export file path, if not specified, it will be exported to standard output. If the filename ends with .gz , it will be automatically compressed. |
--subdir=path | Only export metadata for the specified subdirectory. |
--keep-secret-key Added in v1.1 | Export object storage authentication information, the default is false . Since it is exported in plain text, pay attention to data security when using it. If the export file does not contain object storage authentication information, you need to use juicefs config to reconfigure object storage authentication information after the subsequent import is completed. |
juicefs load
Load metadata from a previously dumped JSON file. Read "Metadata recovery and migration" to learn more.
Synopsis
juicefs load [command options] META-URL [FILE]
# Import the metadata backup file meta-dump.json to the database
juicefs load redis://127.0.0.1:6379/1 meta-dump.json
Options
Items | Description |
---|---|
META-URL | Database URL for metadata storage, see JuiceFS supported metadata engines for details. |
FILE | Import file path, if not specified, it will be imported from standard input. If the filename ends with .gz , it will be automatically decompressed. |
--encrypt-rsa-key=path Added in v1.0.4 | The path to the RSA private key file used for encryption. |
--encrypt-alg=aes256gcm-rsa Added in v1.0.4 | Encryption algorithm, the default is aes256gcm-rsa . |
Inspector
juicefs status
Show status of JuiceFS.
Synopsis
juicefs status [command options] META-URL
juicefs status redis://localhost
Options
Items | Description |
---|---|
--session=0, -s 0 | show detailed information (sustained inodes, locks) of the specified session (SID) (default: 0) |
--more, -m Added in v1.1 | show more statistic information, may take a long time (default: false) |
juicefs stats
Show runtime statistics, read Real-time performance monitoring for more.
Synopsis
juicefs stats [command options] MOUNTPOINT
juicefs stats /mnt/jfs
# More metrics
juicefs stats /mnt/jfs -l 1
Options
Items | Description |
---|---|
--schema=ufmco | schema string that controls the output sections (u : usage, f : FUSE, m : metadata, c : block cache, o : object storage, g : Go) (default: ufmco ) |
--interval=1 | interval in seconds between each update (default: 1) |
--verbosity=0 | verbosity level, 0 or 1 is enough for most cases (default: 0) |
juicefs profile
Show profiling of operations completed in JuiceFS, based on access log. read Real-time performance monitoring for more.
Synopsis
juicefs profile [command options] MOUNTPOINT/LOGFILE
# Monitor real time operations
juicefs profile /mnt/jfs
# Replay an access log
cat /mnt/jfs/.accesslog > /tmp/jfs.alog
# Press Ctrl-C to stop the "cat" command after some time
juicefs profile /tmp/jfs.alog
# Analyze an access log and print the total statistics immediately
juicefs profile /tmp/jfs.alog --interval 0
Options
Items | Description |
---|---|
--uid=value, -u value | only track specified UIDs (separated by comma) |
--gid=value, -g value | only track specified GIDs (separated by comma) |
--pid=value, -p value | only track specified PIDs (separated by comma) |
--interval=2 | flush interval in seconds; set it to 0 when replaying a log file to get an immediate result (default: 2) |
juicefs info
Show internal information for given paths or inodes.
Synopsis
juicefs info [command options] PATH or INODE
# Check a path
juicefs info /mnt/jfs/foo
# Check an inode
cd /mnt/jfs
juicefs info -i 100
Options
Items | Description |
---|---|
--inode, -i | use inode instead of path (current dir should be inside JuiceFS) (default: false) |
--recursive, -r | get summary of directories recursively (NOTE: it may take a long time for huge trees) (default: false) |
--strict Added in v1.1 | get accurate summary of directories (NOTE: it may take a long time for huge trees) (default: false) |
--raw | show internal raw information (default: false) |
juicefs debug
Added in v1.1
It collects and displays information from multiple dimensions such as the operating environment and system logs to help better locate errors
Synopsis
juicefs debug [command options] MOUNTPOINT
# Collect and display information about the mount point /mnt/jfs
juicefs debug /mnt/jfs
# Specify the output directory as /var/log
juicefs debug --out-dir=/var/log /mnt/jfs
# Get the last up to 1000 log entries
juicefs debug --out-dir=/var/log --limit=1000 /mnt/jfs
Options
Items | Description |
---|---|
--out-dir=./debug/ | The output directory of the results, automatically created if the directory does not exist (default: ./debug/ ) |
--stats-sec=5 | The number of seconds to sample .stats file (default: 5) |
--limit=value | The number of log entries collected, from newest to oldest, if not specified, all entries will be collected |
--trace-sec=5 | The number of seconds to sample trace metrics (default: 5) |
--profile-sec=30 | The number of seconds to sample profile metrics (default: 30) |
juicefs summary
Added in v1.1
It is used to show tree summary of target directory.
Synopsis
juicefs summary [command options] PATH
# Show with path
juicefs summary /mnt/jfs/foo
# Show max depth of 5
juicefs summary --depth 5 /mnt/jfs/foo
# Show top 20 entries
juicefs summary --entries 20 /mnt/jfs/foo
# Show accurate result
juicefs summary --strict /mnt/jfs/foo
Options
Items | Description |
---|---|
--depth value, -d value | depth of tree to show (zero means only show root) (default: 2) |
--entries value, -e value | show top N entries (sort by size) (default: 10) |
--strict | show accurate summary, including directories and files (may be slow) (default: false) |
--csv | print summary in csv format (default: false) |
Service
juicefs mount
Mount a volume. The volume must be formatted in advance.
JuiceFS can be mounted by root or normal user, but due to their privilege differences, cache directory and log path will vary, read below descriptions for more.
Synopsis
juicefs mount [command options] META-URL MOUNTPOINT
# Mount in foreground
juicefs mount redis://localhost /mnt/jfs
# Mount in background with password protected Redis
juicefs mount redis://:mypassword@localhost /mnt/jfs -d
# A safer alternative
META_PASSWORD=mypassword juicefs mount redis://localhost /mnt/jfs -d
# Mount with a sub-directory as root
juicefs mount redis://localhost /mnt/jfs --subdir /dir/in/jfs
# Enable "writeback" mode, which improves performance at the risk of losing objects
juicefs mount redis://localhost /mnt/jfs -d --writeback
# Enable "read-only" mode
juicefs mount redis://localhost /mnt/jfs -d --read-only
# Disable metadata backup
juicefs mount redis://localhost /mnt/jfs --backup-meta 0
Options
Items | Description |
---|---|
META-URL | Database URL for metadata storage, see JuiceFS supported metadata engines for details. |
MOUNTPOINT | file system mount point, e.g. /mnt/jfs , Z: . |
-d, --background | run in background (default: false) |
--no-syslog | disable syslog (default: false) |
--log=path | path of log file when running in background (default: $HOME/.juicefs/juicefs.log or /var/log/juicefs.log ) |
--update-fstab Added in v1.1 | add / update entry in /etc/fstab , will create a symlink from /sbin/mount.juicefs to JuiceFS executable if not existing (default: false) |
FUSE related options
Items | Description |
---|---|
--enable-xattr | enable extended attributes (xattr) (default: false) |
--enable-ioctl Added in v1.1 | enable ioctl (support GETFLAGS/SETFLAGS only) (default: false) |
--root-squash value Added in v1.1 | mapping local root user (UID = 0) to another one specified as UID:GID |
--prefix-internal Added in v1.1 | add '.jfs' prefix to all internal files (default: false) |
-o value | other FUSE options, see FUSE Mount Options |
Metadata related options
Items | Description |
---|---|
--subdir=value | mount a sub-directory as root (default: "") |
--backup-meta=3600 | interval (in seconds) to automatically backup metadata in the object storage (0 means disable backup) (default: "3600") |
--heartbeat=12 | interval (in seconds) to send heartbeat; it's recommended that all clients use the same heartbeat value (default: "12") |
--read-only | allow lookup/read operations only (default: false) |
--no-bgjob | Disable background jobs, default to false, which means clients by default carry out background jobs, including:
compactChunk in pkg/meta/base.go ). |
--atime-mode=noatime Added in v1.1 | Control atime (last time the file was accessed) behavior, support the following modes:
|
--skip-dir-nlink value Added in v1.1 | number of retries after which the update of directory nlink will be skipped (used for tkv only, 0 means never) (default: 20) |
Metadata cache related options
For metadata cache description and usage, refer to Kernel metadata cache and Client memory metadata cache.
Items | Description |
---|---|
--attr-cache=1 | attributes cache timeout in seconds (default: 1), read Kernel metadata cache |
--entry-cache=1 | file entry cache timeout in seconds (default: 1), read Kernel metadata cache |
--dir-entry-cache=1 | dir entry cache timeout in seconds (default: 1), read Kernel metadata cache |
--open-cache=0 | open file cache timeout in seconds (0 means disable this feature) (default: 0) |
--open-cache-limit value Added in v1.1 | max number of open files to cache (soft limit, 0 means unlimited) (default: 10000) |
Data storage related options
Items | Description |
---|---|
--storage=file | Object storage type (e.g. s3 , gs , oss , cos ) (default: "file" , refer to documentation for all supported object storage types). |
--storage-class value Added in v1.1 | the storage class for data written by current client |
--bucket=value | customized endpoint to access object storage |
--get-timeout=60 | the max number of seconds to download an object (default: 60) |
--put-timeout=60 | the max number of seconds to upload an object (default: 60) |
--io-retries=10 | number of retries after network failure (default: 10) |
--max-uploads=20 | Upload concurrency, defaults to 20. This is already a reasonably high value for 4M writes, with such write pattern, increasing upload concurrency usually demands higher --buffer-size , learn more at Read/Write Buffer. But for random writes around 100K, 20 might not be enough and can cause congestion at high load, consider using a larger upload concurrency, or try to consolidate small writes in the application end. |
--max-deletes=10 | number of threads to delete objects (default: 10) |
--upload-limit=0 | bandwidth limit for upload in Mbps (default: 0) |
--download-limit=0 | bandwidth limit for download in Mbps (default: 0) |
Data cache related options
Items | Description |
---|---|
--buffer-size=300 | total read/write buffering in MiB (default: 300), see Read/Write buffer |
--prefetch=1 | prefetch N blocks in parallel (default: 1), see Client read data cache |
--writeback | upload objects in background (default: false), see Client write data cache |
--upload-delay=0 | When --writeback is enabled, you can use this option to add a delay to object storage upload, default to 0, meaning that upload will begin immediately after write. Different units are supported, including s (second), m (minute), h (hour). If files are deleted during this delay, upload will be skipped entirely, when using JuiceFS for temporary storage, use this option to reduce resource usage. Refer to Client write data cache. |
--cache-dir=value | directory paths of local cache, use : (Linux, macOS) or ; (Windows) to separate multiple paths (default: $HOME/.juicefs/cache or /var/jfsCache ), see Client read data cache |
--cache-mode value Added in v1.1 | file permissions for cached blocks (default: "0600") |
--cache-size=102400 | size of cached object for read in MiB (default: 102400), see Client read data cache |
--free-space-ratio=0.1 | min free space ratio (default: 0.1), if Client write data cache is enabled, this option also controls write cache size, see Client read data cache |
--cache-partial-only | cache random/small read only (default: false), see Client read data cache |
--verify-cache-checksum value Added in v1.1 | Checksum level for cache data. After enabled, checksum will be calculated on divided parts of the cache blocks and stored on disks, which are used for verification during reads. The following strategies are supported:
|
--cache-eviction value Added in v1.1 | cache eviction policy (none or 2-random) (default: "2-random") |
--cache-scan-interval value Added in v1.1 | interval (in seconds) to scan cache-dir to rebuild in-memory index (default: "3600") |
Metrics related options
Items | |
---|---|
--metrics=127.0.0.1:9567 | address to export metrics (default: 127.0.0.1:9567 ) |
--consul=127.0.0.1:8500 | Consul address to register (default: 127.0.0.1:8500 ) |
--no-usage-report | do not send usage report (default: false) |
juicefs umount
Unmount a volume.
Synopsis
juicefs umount [command options] MOUNTPOINT
juicefs umount /mnt/jfs
Options
Items | Description |
---|---|
-f, --force | force unmount a busy mount point (default: false) |
--flush Added in v1.1 | wait for all staging chunks to be flushed (default: false) |
juicefs gateway
Start an S3-compatible gateway, read Deploy JuiceFS S3 Gateway for more.
Synopsis
juicefs gateway [command options] META-URL ADDRESS
export MINIO_ROOT_USER=admin
export MINIO_ROOT_PASSWORD=12345678
juicefs gateway redis://localhost localhost:9000
Options
Apart from options listed below, this command shares options with juicefs mount
, be sure to refer to mount
as well.
Items | Description |
---|---|
META-URL | Database URL for metadata storage, see JuiceFS supported metadata engines for details. |
ADDRESS | S3 gateway address and listening port, for example: localhost:9000 |
--access-log=path | path for JuiceFS access log. |
--no-banner | disable MinIO startup information (default: false) |
--multi-buckets | use top level of directories as buckets (default: false) |
--keep-etag | save the ETag for uploaded objects (default: false) |
--umask=022 | umask for new file and directory in octal (default: 022) |
juicefs webdav
Start a WebDAV server, refer to Deploy WebDAV Server for more.
Synopsis
juicefs webdav [command options] META-URL ADDRESS
juicefs webdav redis://localhost localhost:9007
Options
Apart from options listed below, this command shares options with juicefs mount
, be sure to refer to mount
as well.
Items | Description |
---|---|
META-URL | Database URL for metadata storage, see JuiceFS supported metadata engines for details. |
ADDRESS | WebDAV address and listening port, for example: localhost:9007 . |
--cert-file Added in v1.1 | certificate file for HTTPS |
--key-file Added in v1.1 | key file for HTTPS |
--gzip | compress served files via gzip (default: false) |
--disallowList | disallow list a directory (default: false) |
--access-log=path | path for JuiceFS access log. |
Tool
juicefs bench
Run benchmark, including read/write/stat for big and small files.
For a detailed introduction to the bench
subcommand, refer to the documentation.
Synopsis
juicefs bench [command options] PATH
# Run benchmarks with 4 threads
juicefs bench /mnt/jfs -p 4
# Run benchmarks of only small files
juicefs bench /mnt/jfs --big-file-size 0
Options
Items | Description |
---|---|
--block-size=1 | block size in MiB (default: 1) |
--big-file-size=1024 | size of big file in MiB (default: 1024) |
--small-file-size=0.1 | size of small file in MiB (default: 0.1) |
--small-file-count=100 | number of small files (default: 100) |
--threads=1, -p 1 | number of concurrent threads (default: 1) |
juicefs objbench
Run basic benchmarks on the target object storage to test if it works as expected. Read documentation for more.
Synopsis
juicefs objbench [command options] BUCKET
# Run benchmarks on S3
ACCESS_KEY=myAccessKey SECRET_KEY=mySecretKey juicefs objbench --storage=s3 https://mybucket.s3.us-east-2.amazonaws.com -p 6
Options
Items | Description |
---|---|
--storage=file | Object storage type (e.g. s3 , gs , oss , cos ) (default: file , refer to documentation for all supported object storage types) |
--access-key=value | Access Key for object storage (can also be set via the environment variable ACCESS_KEY ), see How to Set Up Object Storage for more. |
--secret-key value | Secret Key for object storage (can also be set via the environment variable SECRET_KEY ), see How to Set Up Object Storage for more. |
--block-size=4096 | size of each IO block in KiB (default: 4096) |
--big-object-size=1024 | size of each big object in MiB (default: 1024) |
--small-object-size=128 | size of each small object in KiB (default: 128) |
--small-objects=100 | number of small objects (default: 100) |
--skip-functional-tests | skip functional tests (default: false) |
--threads=4, -p 4 | number of concurrent threads (default: 4) |
juicefs warmup
Download data to local cache in advance, to achieve better performance on application's first read. You can specify a mount point path to recursively warm-up all files under this path. You can also specify a file through the --file
option to only warm-up the files contained in it.
If the files needing warming up resides in many different directories, you should specify their names in a text file, and pass to the warmup
command using the --file
option, allowing juicefs warmup
to download concurrently, which is significantly faster than calling juicefs warmup
multiple times, each with a single file.
Synopsis
juicefs warmup [command options] [PATH ...]
# Warm up all files in datadir
juicefs warmup /mnt/jfs/datadir
# Warm up selected files
echo '/jfs/f1
/jfs/f2
/jfs/f3' > /tmp/filelist.txt
juicefs warmup -f /tmp/filelist.txt
Options
Items | Description |
---|---|
--file=path, -f path | file containing a list of paths (each line is a file path) |
--threads=50, -p 50 | number of concurrent workers, default to 50. Reduce this number in low bandwidth environment to avoid download timeouts |
--background, -b | run in background (default: false) |
juicefs rmr
Remove all the files and subdirectories, similar to rm -rf
, except this command deals with metadata directly (bypassing kernel), thus is much faster.
If trash is enabled, deleted files are moved into trash. Read more at Trash.
Synopsis
juicefs rmr PATH ...
juicefs rmr /mnt/jfs/foo
juicefs sync
Sync between two storage, read Data migration for more.
Synopsis
juicefs sync [command options] SRC DST
# Sync object from OSS to S3
juicefs sync oss://mybucket.oss-cn-shanghai.aliyuncs.com s3://mybucket.s3.us-east-2.amazonaws.com
# Sync objects from S3 to JuiceFS
juicefs sync s3://mybucket.s3.us-east-2.amazonaws.com/ jfs://META-URL/
# SRC: a1/b1,a2/b2,aaa/b1 DST: empty sync result: aaa/b1
juicefs sync --exclude='a?/b*' s3://mybucket.s3.us-east-2.amazonaws.com/ jfs://META-URL/
# SRC: a1/b1,a2/b2,aaa/b1 DST: empty sync result: a1/b1,aaa/b1
juicefs sync --include='a1/b1' --exclude='a[1-9]/b*' s3://mybucket.s3.us-east-2.amazonaws.com/ jfs://META-URL/
# SRC: a1/b1,a2/b2,aaa/b1,b1,b2 DST: empty sync result: a1/b1,b2
juicefs sync --include='a1/b1' --exclude='a*' --include='b2' --exclude='b?' s3://mybucket.s3.us-east-2.amazonaws.com/ jfs://META-URL/
As shown in the examples, the format of both source (SRC
) and destination (DST
) paths is:
[NAME://][ACCESS_KEY:SECRET_KEY[:TOKEN]@]BUCKET[.ENDPOINT][/PREFIX]
In which:
NAME
: JuiceFS supported data storage types likes3
,oss
, refer to this document for a full list.ACCESS_KEY
andSECRET_KEY
: The credential required to access the data storage, refer to this document.TOKEN
token used to access the object storage, as some object storage supports the use of temporary token to obtain permission for a limited timeBUCKET[.ENDPOINT]
: The access address of the data storage service. The format may be different for different storage types, and refer to the document.[/PREFIX]
: Optional, a prefix for the source and destination paths that can be used to limit synchronization of data only in certain paths.
Selection related options
Items | Description |
---|---|
--start=KEY, -s KEY, --end=KEY, -e KEY | Provide object storage key range for syncing. |
--exclude=PATTERN | Exclude keys matching PATTERN. |
--include=PATTERN | Include keys matching PATTERN, need to be used with --exclude . |
--limit=-1 | Limit the number of objects that will be processed, default to -1 which means unlimited. |
--update, -u | Update existing files if the source files' mtime is newer, default to false. |
--force-update, -f | Always update existing file, default to false. |
--existing, --ignore-non-existing Added in v1.1 | Skip creating new files on destination, default to false. |
--ignore-existing Added in v1.1 | Skip updating files that already exist on destination, default to false. |
Action related options
Items | Description |
---|---|
--dirs | Sync empty directories as well. |
--perms | Preserve permissions, default to false. |
--links, -l | Copy symlinks as symlinks default to false. |
--delete-src, --deleteSrc | Delete objects that already exist in destination. Different from rsync, files won't be deleted at the first run, instead they will be deleted at the next run, after files are successfully copied to the destination. |
--delete-dst, --deleteDst | Delete extraneous objects from destination. |
--check-all | Verify the integrity of all files in source and destination, default to false. Comparison is done on byte streams, which comes at a performance cost. |
--check-new | Verify the integrity of newly copied files, default to false. Comparison is done on byte streams, which comes at a performance cost. |
--dry | Don't actually copy any file. |
Storage related options
Items | Description |
---|---|
--threads=10, -p 10 | Number of concurrent threads, default to 10. |
--list-threads=1 Added in v1.1 | Number of list threads, default to 1. Read concurrent list to learn its usage. |
--list-depth=1 Added in v1.1 | Depth of concurrent list operation, default to 1. Read concurrent list to learn its usage. |
--no-https | Do not use HTTPS, default to false. |
--storage-class value Added in v1.1 | the storage class for destination |
--bwlimit=0 | Limit bandwidth in Mbps default to 0 which means unlimited. |
Cluster related options
Items | Description |
---|---|
--manager-addr=ADDR | The listening address of the Manager node in distributed synchronization mode in the format: <IP>:[port] . If not specified, it listens on a random port. If this option is omitted, it listens on a random local IPv4 address and a random port. |
--worker=ADDR,ADDR | Worker node addresses used in distributed syncing, comma separated. |
juicefs clone
Added in v1.1
Quickly clone directories or files within a single JuiceFS mount point. The cloning process involves copying only the metadata without copying the data blocks, making it extremely fast. Read Clone Files or Directories for more.
Synopsis
juicefs clone [command options] SRC DST
# Clone a file
juicefs clone /mnt/jfs/file1 /mnt/jfs/file2
# Clone a directory
juicefs clone /mnt/jfs/dir1 /mnt/jfs/dir2
# Preserve the UID, GID, and mode of the file
juicefs clone -p /mnt/jfs/file1 /mnt/jfs/file2
Options
Items | Description |
---|---|
--preserve, -p | By default, the executor's UID and GID are used for the clone result, and the mode is recalculated based on the user's umask. Use this option to preserve the UID, GID, and mode of the file. |