Your company here — click to reach over 10,000 unique daily visitors

cephfs-shell - Man Page

Shell-like tool talking with CephFS


cephfs-shell [options] [command]
cephfs-shell [options] -- [command, command,...]


CephFS Shell provides shell-like commands that directly interact with the Ceph File System.

This tool can be used in interactive mode as well as in non-interactive mode. In former mode, cephfs-shell opens a shell session and after the given command is finished, it prints the prompt string and waits indefinitely. When the shell session is finished, cephfs-shell quits with the return value of last executed command. In non-interactive mode, cephfs-shell issues a command and exits right after the command's execution is complete with the command's return value.

Behaviour of CephFS Shell can be tweaked using cephfs-shell.conf. Refer to CephFS Shell Configuration File for details.


-b, --batch FILE

Path to batch file.

-c, --config FILE

Path to cephfs-shell.conf

-f, --fs FS

Name of filesystem to mount.

-t, --test FILE

Path to transcript(s) in FILE for testing


Latest version of the cmd2 module is required for running cephfs-shell. If CephFS is installed through source, execute cephfs-shell in the build directory. It can also be executed as following using virtualenv:

[build]$ python3 -m venv venv && source venv/bin/activate && pip3 install cmd2 colorama
[build]$ source vstart_environment.sh && source venv/bin/activate && python3 ../src/tools/cephfs/shell/cephfs-shell



Apart from Ceph File System, CephFS Shell commands can also interact directly with the local file system. To achieve this, ! (an exclamation point) must precede the CephFS Shell command.

Usage :


For example,

CephFS:~/>>> !ls # Lists the local file system directory contents.
CephFS:~/>>> ls  # Lists the Ceph File System directory contents.


Create the directory(ies), if they do not already exist.

Usage :

mkdir [-option] <directory>...

  • directory - name of the directory to be created.
Options :

Sets the access mode for the new directory.

-p, --parent

Create parent directories as necessary. When this option is specified, no error is reported if a directory already exists.


Copy a file/directory to Ceph File System from Local File System.

Usage :

put [options] <source_path> <target_path>

  • source_path - local file/directory path to be copied to cephfs.
    • if . copies all the file/directories in the local working directory.
    • if -  Reads the input from stdin.
  • target_path - remote directory path where the files/directories are to be copied to.
    • if . files/directories are copied to the remote working directory.
Options :
-f, --force

Overwrites the destination if it already exists.


Copy a file from Ceph File System to Local File System.

Usage :

get [options] <source_path> <target_path>

  • source_path - remote file/directory path which is to be copied to local file system.
    • if . copies all the file/directories in the remote working directory.
  • target_path - local directory path where the files/directories are to be copied to.
    • if . files/directories are copied to the local working directory.
    • if - Writes output to stdout.
-f, --force

Overwrites the destination if it already exists.


List all the files and directories in the current working directory.

Usage :

ls [option] [directory]...

  • directory - name of directory whose files/directories are to be listed.
    • By default current working directory's files/directories are listed.
-l, --long

list with long format - show permissions

-r, --reverse

reverse sort


human readable


ignore entries starting with .


Sort by file_size


Concatenate files and print on the standard output

Usage :

cat  <file>....

  • file - name of the file


Add a hard link to an existing file or create a symbolic link to an existing file or directory.


ln [options] <target> [link_name]

  • target - file/directory to which a link is to be created
  • link_name - link to target with the name link_name
-s, --symbolic

Create symbolic link

-v, --verbose

Print name of each linked file

-f, --force

Force create link/symbolic link


Change current working directory.

Usage :

cd [directory]

  • directory - path/directory name. If no directory is mentioned it is changed to the root directory.
    • If '.' moves to the parent directory of the current directory.


Get current working directory.

Usage :


quit/Ctrl + D

Close the shell.


Change the permissions of file/directory.

Usage :

chmod <mode> <file/directory>


Moves files/Directory from source to destination.

Usage :

mv <source_path> <destination_path>


Delete a directory(ies).

Usage :

rmdir <directory_name>.....


Remove a file(es).

Usage :

rm <file_name/pattern>...


Create and Write a file.

Usage :

write <file_name> <Enter Data> Ctrl+D Exit.


Lists all files and directories in the specified directory.Current local directory files and directories are listed if no     path is mentioned


lls <path>.....


Moves into the given local directory.

Usage :

lcd <path>


Prints the absolute path of the current local directory.

Usage :



Set and get the file mode creation mask

Usage :

umask [mode]


Define or display aliases


alias [name] | [<name> <value>]

  • name - name of the alias being looked up, added, or replaced
  • value - what the alias will be resolved to (if adding or replacing) this can contain spaces and does not need to be quoted


Runs a python script file inside the console


run_pyscript <script_path> [script_arguments]

  • Console commands can be executed inside this script with cmd ("your command") However, you cannot run nested "py" or "pyscript" commands from within this script. Paths or arguments that contain spaces must be enclosed in quotes

This command is available as pyscript for cmd2 versions 0.9.13 or less.


Invoke python command, shell, or script

Usage :

py <command>: Executes a Python command. py: Enters interactive Python mode.


Lists shortcuts (aliases) available

Usage :



View, run, edit, and save previously entered commands.

Usage :

history [-h] [-r | -e | -s | -o FILE | -t TRANSCRIPT] [arg]


show this help message and exit


run selected history items


edit and then run selected history items


script format; no separation lines


output commands to a script file


output commands and results to a transcript file


Unsets aliases

Usage :

unalias [-a] name [name ...]

  • name - name of the alias being unset

remove all alias definitions


Sets a settable parameter or shows current settings of parameters.

Usage :

set [-h] [-a] [-l] [settable [settable ...]]

  • Call without arguments for a list of settable parameters with their values.
Options :

show this help message and exit


display read-only settings as well


describe function of parameter


Edit a file in a text editor.


edit [file_path]

  • file_path - path to a file to open in editor


Runs commands in script file that is encoded as either ASCII or UTF-8 text. Each command in the script should be separated by a newline.


run_script <file_path>

  • file_path - a file path pointing to a script

This command is available as load for cmd2 versions 0.9.13 or less.


Execute a command as if at the OS prompt.


shell <command> [arguments]


Find an item in File System


locate [options] <name>

Options :

Count number of items found


Ignore case


Display file status.

Usage :

stat [-h] <file_name> [file_name ...]

Options :

Shows the help message


Create or Delete Snapshot


snap {create|delete} <snap_name> <dir_name>

  • snap_name - Snapshot name to be created or deleted
  • dir_name - directory under which snapshot should be created or deleted


Set extended attribute for a file

Usage :

setxattr [-h] <path> <name> <value>

  • path - Path to the file
  • name - Extended attribute name to get or set
  • value - Extended attribute value to be set
-h, --help

Shows the help message


Get extended attribute value for the name associated with the path

Usage :

getxattr [-h] <path> <name>

  • path - Path to the file
  • name - Extended attribute name to get or set
-h, --help

Shows the help message


List extended attribute names associated with the path

Usage :

listxattr [-h] <path>

  • path - Path to the file
-h, --help

Shows the help message


Display amount of available disk space

Usage :

df [-h] [file [file ...]]

  • file - name of the file
-h, --help

Shows the help message


Show disk usage of a directory

Usage :

du [-h] [-r] [paths [paths ...]]

  • paths - name of the directory
-h, --help

Shows the help message


Recursive Disk usage of all directories


Quota management for a Directory

Usage :

quota [-h] [--max_bytes [MAX_BYTES]] [--max_files [MAX_FILES]] {get,set} path

  • {get,set} - quota operation type.
  • path - name of the directory.
Options :
-h, --help

Shows the help message

--max_bytes MAX_BYTES

Set max cumulative size of the data under this directory

--max_files MAX_FILES

Set total number of files under this directory tree

Cephfs Shell Configuration File

By default, CephFS Shell looks for cephfs-shell.conf in the path provided by the environment variable CEPHFS_SHELL_CONF and then in user's home directory (~/.cephfs-shell.conf).

Right now, CephFS Shell inherits all its options from its dependency cmd2. Therefore, these options might vary with the version of cmd2 installed on your system. Refer to cmd2 docs for a description of these options.

Following is a sample cephfs-shell.conf

prompt = CephFS:~/>>>
continuation_prompt = >

quiet = False
timing = False
colors = True
debug = False

abbrev = False
autorun_on_edit = False
echo = False
editor = vim
feedback_to_output = False
locals_in_py = True

Exit Code

Following exit codes are returned by cephfs shell

Error TypeExit Code
Keyboard Interrupt2
Operation not permitted3
Permission denied4
No such file or directory5
I/O error6
No space left on device7
File exists8
No data available9
Invalid argument10
Operation not supported on transport endpoint11
Range error12
Operation would block13
Directory not empty14
Not a directory15
Disk quota exceeded16
Broken pipe17
Cannot send after transport endpoint shutdown18
Connection aborted19
Connection refused20
Connection reset21
Interrupted function call22




Jul 09, 2024 dev Ceph