CEPHFS-SHELL(8)

✨ NAME ✨

cephfs-shell — it's a CephFS (Ceph) thing, a shell-ish tool that literally talks to CephFS 💬💖

---

🌸 SYNOPSIS 🌸

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

---

🫶 DESCRIPTION 🫶

okay so bestie, CephFS Shell hands you shell-like commands that go straight-up talk to the Ceph File System. no middleman, no cap 🦋

You can run this icon in interactive mode or non-interactive mode, and both are giving main character energy:

• Interactive mode — cephfs-shell opens a shell session, and once your command is done it prints the prompt string and then just… waits. Indefinitely. Forever. Patiently. 💅 When the shell session finally wraps up, cephfs-shell quits with the return value of the last executed command — so whatever you did last is the vibe it leaves with.
• Non-interactive mode — cephfs-shell runs a command and dips right after it finishes, exiting with that command's return value. quick, efficient, in-and-out, we love to see it ⭐

And the behaviour of CephFS Shell? Totally tweakable, bestie — via cephfs-shell.conf. Go read CephFS Shell Configuration File for the tea ☕

---

💅 OPTIONS 💅

• -b, --batch FILE — path to the batch file 📄
• -c, --config FILE — path to cephfs-shell.conf 🎀
• -f, --fs FS — the name of the filesystem to mount 🗂️
• -t, --test FILE — path to transcript(s) in <italic>FILE</italic> for testing 🧪

Note: heads up! the latest version of the cmd2 module is required for running cephfs-shell 🔥 If CephFS was installed through source, you gotta execute cephfs-shell in the build directory. It can also be executed like this 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

no skipping that pip3 install cmd2 colorama, it's mandatory fr fr 🙈✨

---

🎀 COMMANDS 🎀

okay so real talk bestie: CephFS Shell is not just for the Ceph File System. It can also go poke at your local file system directly, and the way you unlock that is by putting a ! (an exclamation point, yes, literally) in front of the command.

Usage:

!<cephfs_shell_command>

Like for example:

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

Same command, two entirely different universes. The ! is the plot twist. 🦋

---

mkdir

Creates the directory(ies), but only if they don't already exist. No double-dipping.

Usage:

mkdir [-option] <directory>...

• directory — name of the directory to be created.

Options:

• -m MODE — sets the access mode for the new directory.
• -p, --parent — creates parent directories as necessary. And when you use this one, no error is reported if a directory already exists. So chill, it just vibes.

put

Copies a file/directory to the Ceph File System from your Local File System. Glow-up energy ✨

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.

get

Copies a file from the Ceph File System back down to your Local File System. Bringing the content home 🫶

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.

Options:

• -f, --force — overwrites the destination if it already exists.

ls

Lists all the files and directories in the current working directory. The classic. The moment. 💅

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.

Options:

• -l, --long — list with long format — show permissions
• -r, --reverse — reverse sort
• -H — human readable
• -a,-all — ignore entries starting with .
• -S — Sort by file_size

cat

Concatenate files and print on the standard output. Just dumping the whole thing straight to your eyeballs 😭

Usage:

cat  <file>....

• file — name of the file

ln

Add a hard link to an existing file, or create a symbolic link to an existing file or directory. Two flavours, pick your fighter.

Usage:

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

Options:

• -s, --symbolic — Create symbolic link
• -v, --verbose — Print name of each linked file
• -f, --force — Force create link/symbolic link

cd

Change current working directory. Teleporting, basically 🧚

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.

cwd

Get current working directory. Where are you, bestie?

Usage:

cwd

quit/Ctrl + D

Close the shell. The goodbye 😭 press Ctrl+D and you're out.

---

chmod

Change the permissions of file/directory. Gatekeeping who gets in 🔥

Usage:

chmod <mode> <file/directory>

mv

Moves files/Directory from source to destination.

Usage:

mv <source_path> <destination_path>

rmdir

Delete a directory(ies).

Usage:

rmdir <directory_name>.....

rm

Remove a file(es).

Usage:

rm <file_name/pattern>...

write

Create and Write a file.

Usage:

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

lls

Lists all files and directories in the specified directory. Current local directory files and directories are listed if no path is mentioned. (Note the double-l — this one is looking at your local side 👀)

Usage:

lls <path>.....

lcd

Moves into the given local directory.

Usage:

lcd <path>

lpwd

Prints the absolute path of the current local directory.

Usage:

lpwd

umask

Set and get the file mode creation mask.

Usage:

umask [mode]

alias

Define or display aliases. Nicknames for your faves 💖

Usage:

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

run_pyscript

Runs a python script file inside the console. Python girlies rise 🌈

Usage:

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

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

py

Invoke python command, shell, or script.

Usage:

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

shortcuts

Lists shortcuts (aliases) available.

Usage:

shortcuts

history

View, run, edit, and save previously entered commands. Your entire past, archived 💀

Usage:

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

Options:

• -h — show this help message and exit
• -r — run selected history items
• -e — edit and then run selected history items
• -s — script format; no separation lines
• -o FILE — output commands to a script file
• -t TRANSCRIPT — output commands and results to a transcript file

unalias

Unsets aliases. Breaking up with your nicknames, respectfully.

Usage:

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

• name — name of the alias being unset

Options:

• -a — remove all alias definitions

set

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:

• -h — show this help message and exit
• -a — display read-only settings as well
• -l — describe function of parameter

edit

Edit a file in a text editor.

Usage:

edit [file_path]

• file_path — path to a file to open in editor

run_script

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.

Usage:

run_script <file_path>

• file_path — a file path pointing to a script

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

shell

Execute a command as if at the OS prompt.

Usage:

shell <command> [arguments]

locate

Find an item in File System. Where is it, where is it 🙈

Usage:

locate [options] <name>

Options:

• -c — Count number of items found
• -i — Ignore case

stat

Display file status.

Usage:

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

Options:

• -h — Shows the help message

snap

Create or Delete Snapshot.

Usage:

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

setxattr

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

Options:

• -h, --help — Shows the help message

getxattr

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

Options:

• -h, --help — Shows the help message

listxattr

List extended attribute names associated with the path.

Usage:

listxattr [-h] <path>

• path — Path to the file

Options:

• -h, --help — Shows the help message

df

Display amount of available disk space.

Usage:

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

• file — name of the file

Options:

• -h, --help — Shows the help message

du

Show disk usage of a directory.

Usage:

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

• paths — name of the directory

Options:

• -h, --help — Shows the help message
• -r — Recursive Disk usage of all directories

quota

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. So these options might vary with the version of cmd2 installed on your system. Refer to cmd2 docs for a description of these options. iykyk 👑

Following is a sample cephfs-shell.conf:

[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

💥 EXIT CODE 💥

bestie when the cephfs shell bails on you, it doesn't just ghost — it leaves a number behind so you know exactly what went down. every code has a whole personality, so here's the full roster, no skips, no cap:

• Miscellaneous — 1
• Keyboard Interrupt — 2
• Operation not permitted — 3
• Permission denied — 4
• No such file or directory — 5
• I/O error — 6
• No space left on device — 7
• File exists — 8
• No data available — 9
• Invalid argument — 10
• Operation not supported on transport endpoint — 11
• Range error — 12
• Operation would block — 13
• Directory not empty — 14
• Not a directory — 15
• Disk quota exceeded — 16
• Broken pipe — 17
• Cannot send after transport endpoint shutdown — 18
• Connection aborted — 19
• Connection refused — 20
• Connection reset — 21
• Interrupted function call — 22

so like — exit 1 is the "idk what happened but it happened" of the group chat, exit 2 means you personally hit Ctrl+C and said enough, and 3–22 are the shell being extremely specific about the drama. check your exit code before you spiral, bestie, it's literally telling you the tea. 🫖✨

---

📁 FILES 📁

• ~/.cephfs-shell.conf

that's the one, the config bestie, your shell's lil home base. 🏠💖

---

📜 Copyright 📜

2010-2014, Inktank Storage, Inc. and contributors. Licensed under Creative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)

---

and that's the whole page, bestie!! 🎀 you read all three parts, you're genuinely so iconic for that. this one's from CEPHFS-SHELL(8), source/version <rainbow>dev</rainbow>, dated Oct 06, 2026 — go forth and cephfs-shell responsibly, ily, periodt 💅✨