'\" t
.\" Man page generated from reStructuredText
.\" by the Docutils 0.23 manpage writer.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "CEPHFS-SHELL" "8" "Oct 24, 2026" "dev" "Ceph"
.SH NAME
cephfs-shell \- Shell-like tool talking with CephFS
.SH SYNOPSIS
.nf
\fBcephfs\-shell\fP [options] [command]
\fBcephfs\-shell\fP [options] \-\- [command, command,...]
.fi
.sp
.SH DESCRIPTION
.sp
CephFS Shell provides shell\-like commands that directly interact with the
Ceph File System.
.sp
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\(aqs execution is complete with the command\(aqs
return value.
.sp
Behaviour of CephFS Shell can be tweaked using \fBcephfs\-shell.conf\fP\&. Refer to
CephFS Shell Configuration File for details.
.SH OPTIONS
.INDENT 0.0
.TP
.B \-b, \-\-batch FILE
Path to batch file.
.UNINDENT
.INDENT 0.0
.TP
.B \-c, \-\-config FILE
Path to cephfs\-shell.conf
.UNINDENT
.INDENT 0.0
.TP
.B \-f, \-\-fs FS
Name of filesystem to mount.
.UNINDENT
.INDENT 0.0
.TP
.B \-t, \-\-test FILE
Path to transcript(s) in FILE for testing
.UNINDENT
.sp
\fBNote:\fP
.INDENT 0.0
.INDENT 3.5
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:
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.EX
[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
.EE
.UNINDENT
.UNINDENT
.SH COMMANDS
.sp
\fBNote:\fP
.INDENT 0.0
.INDENT 3.5
Apart from Ceph File System, CephFS Shell commands can also interact
directly with the local file system. To achieve this, \fB!\fP (an
exclamation point) must precede the CephFS Shell command.
.sp
Usage :
.INDENT 0.0
.INDENT 3.5
!<cephfs_shell_command>
.UNINDENT
.UNINDENT
.sp
For example,
.INDENT 0.0
.INDENT 3.5
.sp
.EX
CephFS:~/>>> !ls # Lists the local file system directory contents.
CephFS:~/>>> ls  # Lists the Ceph File System directory contents.
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS mkdir
.sp
Create the directory(ies), if they do not already exist.
.sp
Usage :
.INDENT 0.0
.INDENT 3.5
mkdir [\-option] <directory>...
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
directory \- name of the directory to be created.
.UNINDENT
.INDENT 0.0
.TP
.B Options :
.INDENT 7.0
.TP
.BI \-m \ MODE
Sets the access mode for the new directory.
.TP
.B  \-p\fP,\fB  \-\-parent
Create parent directories as necessary. When this option is specified, no error is reported if a directory already exists.
.UNINDENT
.UNINDENT
.SS put
.sp
Copy a file/directory to Ceph File System from Local File System.
.sp
Usage :
.INDENT 0.0
.INDENT 3.5
put [options] <source_path> <target_path>
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
.INDENT 2.0
.TP
.B source_path \- local file/directory path to be copied to cephfs.
.INDENT 7.0
.IP \(bu 2
if \fI\&.\fP copies all the file/directories in the local working directory.
.IP \(bu 2
if \fI\-\fP  Reads the input from stdin.
.UNINDENT
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
.B target_path \- remote directory path where the files/directories are to be copied to.
.INDENT 7.0
.IP \(bu 2
if \fI\&.\fP files/directories are copied to the remote working directory.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Options :
.INDENT 7.0
.TP
.B  \-f\fP,\fB  \-\-force
Overwrites the destination if it already exists.
.UNINDENT
.UNINDENT
.SS get
.sp
Copy a file from Ceph File System to Local File System.
.sp
Usage :
.INDENT 0.0
.INDENT 3.5
get [options] <source_path> <target_path>
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
.INDENT 2.0
.TP
.B source_path \- remote file/directory path which is to be copied to local file system.
.INDENT 7.0
.IP \(bu 2
if \fI\&.\fP copies all the file/directories in the remote working directory.
.UNINDENT
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
.B target_path \- local directory path where the files/directories are to be copied to.
.INDENT 7.0
.IP \(bu 2
if \fI\&.\fP files/directories are copied to the local working directory.
.IP \(bu 2
if \fI\-\fP Writes output to stdout.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Options:
.INDENT 7.0
.TP
.B  \-f\fP,\fB  \-\-force
Overwrites the destination if it already exists.
.UNINDENT
.UNINDENT
.SS ls
.sp
List all the files and directories in the current working directory.
.sp
Usage :
.INDENT 0.0
.INDENT 3.5
ls [option] [directory]...
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
.INDENT 2.0
.TP
.B directory \- name of directory whose files/directories are to be listed.
.INDENT 7.0
.IP \(bu 2
By default current working directory\(aqs files/directories are listed.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Options:
.INDENT 7.0
.TP
.B  \-l\fP,\fB  \-\-long
list with long format \- show permissions
.TP
.B  \-r\fP,\fB  \-\-reverse
reverse sort
.TP
.B  \-H
human readable
.TP
.BI \-a\fP,\fB  \-a\fB ll
ignore entries starting with .
.TP
.B  \-S
Sort by file_size
.UNINDENT
.UNINDENT
.SS cat
.sp
Concatenate files and print on the standard output
.sp
Usage :
.INDENT 0.0
.INDENT 3.5
cat  <file>....
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
file \- name of the file
.UNINDENT
.SS ln
.sp
Add a hard link to an existing file or create a symbolic link to an existing
file or directory.
.sp
Usage:
.INDENT 0.0
.INDENT 3.5
ln [options] <target> [link_name]
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
target \- file/directory to which a link is to be created
.IP \(bu 2
link_name \- link to target with the name link_name
.UNINDENT
.INDENT 0.0
.TP
.B Options:
.INDENT 7.0
.TP
.B  \-s\fP,\fB  \-\-symbolic
Create symbolic link
.TP
.B  \-v\fP,\fB  \-\-verbose
Print name of each linked file
.TP
.B  \-f\fP,\fB  \-\-force
Force create link/symbolic link
.UNINDENT
.UNINDENT
.SS cd
.sp
Change current working directory.
.sp
Usage :
.INDENT 0.0
.INDENT 3.5
cd [directory]
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
.INDENT 2.0
.TP
.B directory \- path/directory name. If no directory is mentioned it is changed to the root directory.
.INDENT 7.0
.IP \(bu 2
If \(aq.\(aq moves to the parent directory of the current directory.
.UNINDENT
.UNINDENT
.UNINDENT
.SS cwd
.sp
Get current working directory.
.sp
Usage :
.INDENT 0.0
.INDENT 3.5
cwd
.UNINDENT
.UNINDENT
.SS quit/Ctrl + D
.sp
Close the shell.
.SS chmod
.sp
Change the permissions of file/directory.
.sp
Usage :
.INDENT 0.0
.INDENT 3.5
chmod <mode> <file/directory>
.UNINDENT
.UNINDENT
.SS mv
.sp
Moves files/Directory from source to destination.
.sp
Usage :
.INDENT 0.0
.INDENT 3.5
mv <source_path> <destination_path>
.UNINDENT
.UNINDENT
.SS rmdir
.sp
Delete a directory(ies).
.sp
Usage :
.INDENT 0.0
.INDENT 3.5
rmdir <directory_name>.....
.UNINDENT
.UNINDENT
.SS rm
.sp
Remove a file(es).
.sp
Usage :
.INDENT 0.0
.INDENT 3.5
rm <file_name/pattern>...
.UNINDENT
.UNINDENT
.SS write
.sp
Create and Write a file.
.sp
Usage :
.INDENT 0.0
.INDENT 3.5
write <file_name>
<Enter Data>
Ctrl+D Exit.
.UNINDENT
.UNINDENT
.SS lls
.sp
Lists all files and directories in the specified directory.Current local directory files and directories are listed if no     path is mentioned
.sp
Usage:
.INDENT 0.0
.INDENT 3.5
lls <path>.....
.UNINDENT
.UNINDENT
.SS lcd
.sp
Moves into the given local directory.
.sp
Usage :
.INDENT 0.0
.INDENT 3.5
lcd <path>
.UNINDENT
.UNINDENT
.SS lpwd
.sp
Prints the absolute path of the current local directory.
.sp
Usage :
.INDENT 0.0
.INDENT 3.5
lpwd
.UNINDENT
.UNINDENT
.SS umask
.sp
Set and get the file mode creation mask
.sp
Usage :
.INDENT 0.0
.INDENT 3.5
umask [mode]
.UNINDENT
.UNINDENT
.SS alias
.sp
Define or display aliases
.sp
Usage:
.INDENT 0.0
.INDENT 3.5
alias [name] | [<name> <value>]
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
name \- name of the alias being looked up, added, or replaced
.IP \(bu 2
value \- what the alias will be resolved to (if adding or replacing) this can contain spaces and does not need to be quoted
.UNINDENT
.SS run_pyscript
.sp
Runs a python script file inside the console
.sp
Usage:
.INDENT 0.0
.INDENT 3.5
run_pyscript <script_path> [script_arguments]
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
Console commands can be executed inside this script with cmd (\(dqyour command\(dq)
However, you cannot run nested \(dqpy\(dq or \(dqpyscript\(dq commands from within this
script. Paths or arguments that contain spaces must be enclosed in quotes
.UNINDENT
.sp
\fBNote:\fP
.INDENT 0.0
.INDENT 3.5
This command is available as \fBpyscript\fP for cmd2 versions 0.9.13
or less.
.UNINDENT
.UNINDENT
.SS py
.sp
Invoke python command, shell, or script
.sp
Usage :
.INDENT 0.0
.INDENT 3.5
py <command>: Executes a Python command.
py: Enters interactive Python mode.
.UNINDENT
.UNINDENT
.SS shortcuts
.sp
Lists shortcuts (aliases) available
.sp
Usage :
.INDENT 0.0
.INDENT 3.5
shortcuts
.UNINDENT
.UNINDENT
.SS history
.sp
View, run, edit, and save previously entered commands.
.sp
Usage :
.INDENT 0.0
.INDENT 3.5
history [\-h] [\-r | \-e | \-s | \-o FILE | \-t TRANSCRIPT] [arg]
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Options:
.INDENT 7.0
.TP
.B  \-h
show this help message and exit
.TP
.B  \-r
run selected history items
.TP
.B  \-e
edit and then run selected history items
.TP
.B  \-s
script format; no separation lines
.TP
.BI \-o \ FILE
output commands to a script file
.TP
.BI \-t \ TRANSCRIPT
output commands and results to a transcript file
.UNINDENT
.UNINDENT
.SS unalias
.sp
Unsets aliases
.sp
Usage :
.INDENT 0.0
.INDENT 3.5
unalias [\-a] name [name ...]
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
name \- name of the alias being unset
.UNINDENT
.INDENT 0.0
.TP
.B Options:
.INDENT 7.0
.TP
.B  \-a
remove all alias definitions
.UNINDENT
.UNINDENT
.SS set
.sp
Sets a settable parameter or shows current settings of parameters.
.sp
Usage :
.INDENT 0.0
.INDENT 3.5
set [\-h] [\-a] [\-l] [settable [settable ...]]
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
Call without arguments for a list of settable parameters with their values.
.UNINDENT
.INDENT 0.0
.TP
.B Options :
.INDENT 7.0
.TP
.B  \-h
show this help message and exit
.TP
.B  \-a
display read\-only settings as well
.TP
.B  \-l
describe function of parameter
.UNINDENT
.UNINDENT
.SS edit
.sp
Edit a file in a text editor.
.sp
Usage:
.INDENT 0.0
.INDENT 3.5
edit [file_path]
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
file_path \- path to a file to open in editor
.UNINDENT
.SS run_script
.sp
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.
.sp
Usage:
.INDENT 0.0
.INDENT 3.5
run_script <file_path>
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
file_path \- a file path pointing to a script
.UNINDENT
.sp
\fBNote:\fP
.INDENT 0.0
.INDENT 3.5
This command is available as \fBload\fP for cmd2 versions 0.9.13
or less.
.UNINDENT
.UNINDENT
.SS shell
.sp
Execute a command as if at the OS prompt.
.sp
Usage:
.INDENT 0.0
.INDENT 3.5
shell <command> [arguments]
.UNINDENT
.UNINDENT
.SS locate
.sp
Find an item in File System
.sp
Usage:
.INDENT 0.0
.INDENT 3.5
locate [options] <name>
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Options :
.INDENT 7.0
.TP
.B  \-c
Count number of items found
.TP
.B  \-i
Ignore case
.UNINDENT
.UNINDENT
.SS stat
.sp
Display file status.
.sp
Usage :
.INDENT 0.0
.INDENT 3.5
stat [\-h] <file_name> [file_name ...]
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Options :
.INDENT 7.0
.TP
.B  \-h
Shows the help message
.UNINDENT
.UNINDENT
.SS snap
.sp
Create or Delete Snapshot
.sp
Usage:
.INDENT 0.0
.INDENT 3.5
snap {create|delete} <snap_name> <dir_name>
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
snap_name \- Snapshot name to be created or deleted
.IP \(bu 2
dir_name \- directory under which snapshot should be created or deleted
.UNINDENT
.SS setxattr
.sp
Set extended attribute for a file
.sp
Usage :
.INDENT 0.0
.INDENT 3.5
setxattr [\-h] <path> <name> <value>
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
path \- Path to the file
.IP \(bu 2
name \- Extended attribute name to get or set
.IP \(bu 2
value \- Extended attribute value to be set
.UNINDENT
.INDENT 0.0
.TP
.B Options:
.INDENT 7.0
.TP
.B  \-h\fP,\fB  \-\-help
Shows the help message
.UNINDENT
.UNINDENT
.SS getxattr
.sp
Get extended attribute value for the name associated with the path
.sp
Usage :
.INDENT 0.0
.INDENT 3.5
getxattr [\-h] <path> <name>
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
path \- Path to the file
.IP \(bu 2
name \- Extended attribute name to get or set
.UNINDENT
.INDENT 0.0
.TP
.B Options:
.INDENT 7.0
.TP
.B  \-h\fP,\fB  \-\-help
Shows the help message
.UNINDENT
.UNINDENT
.SS listxattr
.sp
List extended attribute names associated with the path
.sp
Usage :
.INDENT 0.0
.INDENT 3.5
listxattr [\-h] <path>
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
path \- Path to the file
.UNINDENT
.INDENT 0.0
.TP
.B Options:
.INDENT 7.0
.TP
.B  \-h\fP,\fB  \-\-help
Shows the help message
.UNINDENT
.UNINDENT
.SS df
.sp
Display amount of available disk space
.sp
Usage :
.INDENT 0.0
.INDENT 3.5
df [\-h] [file [file ...]]
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
file \- name of the file
.UNINDENT
.INDENT 0.0
.TP
.B Options:
.INDENT 7.0
.TP
.B  \-h\fP,\fB  \-\-help
Shows the help message
.UNINDENT
.UNINDENT
.SS du
.sp
Show disk usage of a directory
.sp
Usage :
.INDENT 0.0
.INDENT 3.5
du [\-h] [\-r] [paths [paths ...]]
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
paths \- name of the directory
.UNINDENT
.INDENT 0.0
.TP
.B Options:
.INDENT 7.0
.TP
.B  \-h\fP,\fB  \-\-help
Shows the help message
.TP
.B  \-r
Recursive Disk usage of all directories
.UNINDENT
.UNINDENT
.SS quota
.sp
Quota management for a Directory
.sp
Usage :
.INDENT 0.0
.INDENT 3.5
quota [\-h] [\-\-max_bytes [MAX_BYTES]] [\-\-max_files [MAX_FILES]] {get,set} path
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
{get,set} \- quota operation type.
.IP \(bu 2
path \- name of the directory.
.UNINDENT
.INDENT 0.0
.TP
.B Options :
.INDENT 7.0
.TP
.B  \-h\fP,\fB  \-\-help
Shows the help message
.TP
.BI \-\-max_bytes \ MAX_BYTES
Set max cumulative size of the data under this directory
.TP
.BI \-\-max_files \ MAX_FILES
Set total number of files under this directory tree
.UNINDENT
.UNINDENT
.SH CEPHFS SHELL CONFIGURATION FILE
.sp
By default, CephFS Shell looks for \fBcephfs\-shell.conf\fP in the path provided
by the environment variable \fBCEPHFS_SHELL_CONF\fP and then in user\(aqs home
directory (\fB~/.cephfs\-shell.conf\fP).
.sp
Right now, CephFS Shell inherits all its options from its dependency \fBcmd2\fP\&.
Therefore, these options might vary with the version of \fBcmd2\fP installed on
your system. Refer to \fBcmd2\fP docs for a description of these options.
.sp
Following is a sample \fBcephfs\-shell.conf\fP
.INDENT 0.0
.INDENT 3.5
.sp
.EX
[cephfs\-shell]
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
.EE
.UNINDENT
.UNINDENT
.SH EXIT CODE
.sp
Following exit codes are returned by cephfs shell
.TS
box center;
l|l.
T{
Error Type
T}	T{
Exit Code
T}
_
T{
Miscellaneous
T}	T{
1
T}
_
T{
Keyboard Interrupt
T}	T{
2
T}
_
T{
Operation not permitted
T}	T{
3
T}
_
T{
Permission denied
T}	T{
4
T}
_
T{
No such file or directory
T}	T{
5
T}
_
T{
I/O error
T}	T{
6
T}
_
T{
No space left on device
T}	T{
7
T}
_
T{
File exists
T}	T{
8
T}
_
T{
No data available
T}	T{
9
T}
_
T{
Invalid argument
T}	T{
10
T}
_
T{
Operation not supported on transport endpoint
T}	T{
11
T}
_
T{
Range error
T}	T{
12
T}
_
T{
Operation would block
T}	T{
13
T}
_
T{
Directory not empty
T}	T{
14
T}
_
T{
Not a directory
T}	T{
15
T}
_
T{
Disk quota exceeded
T}	T{
16
T}
_
T{
Broken pipe
T}	T{
17
T}
_
T{
Cannot send after transport endpoint shutdown
T}	T{
18
T}
_
T{
Connection aborted
T}	T{
19
T}
_
T{
Connection refused
T}	T{
20
T}
_
T{
Connection reset
T}	T{
21
T}
_
T{
Interrupted function call
T}	T{
22
T}
.TE
.SH FILES
.sp
\fB~/.cephfs\-shell.conf\fP
.SH Copyright
2010-2014, Inktank Storage, Inc. and contributors. Licensed under Creative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)
.\" End of generated man page.