1CEPHFS-SHELL(8) Ceph CEPHFS-SHELL(8)
2
6 cephfs-shell - Shell-like tool talking with CephFS
7
9 cephfs-shell [options] [command]
10 cephfs-shell [options] -- [command, command,...]
11
14 CephFS Shell provides shell-like commands that directly interact with
15 the Ceph File System.
16 This tool can be used in interactive mode as well as in non-interactive
18 mode. In former mode, cephfs-shell opens a shell session and after the
19 given command is finished, it prints the prompt string and waits indef‐
20 initely. When the shell session is finished, cephfs-shell quits with
21 the return value of last executed command. In non-interactive mode,
22 cephfs-shell issues a command and exits right after the command's exe‐
23 cution is complete with the command's return value.
24 Behaviour of CephFS Shell can be tweaked using cephfs-shell.conf. Refer
26 to CephFS Shell Configuration File for details.
27
29 -b, --batch FILE
30 Path to batch file.
31 -c, --config FILE
33 Path to cephfs-shell.conf
34 -f, --fs FS
36 Name of filesystem to mount.
37 -t, --test FILE
39 Path to transcript(s) in FILE for testing
40 NOTE:
42 Latest version of the cmd2 module is required for running
43 cephfs-shell. If CephFS is installed through source, execute
44 cephfs-shell in the build directory. It can also be executed as fol‐
45 lowing using virtualenv:
46 [build]$ python3 -m venv venv && source venv/bin/activate && pip3 install cmd2
48 [build]$ source vstart_environment.sh && source venv/bin/activate && python3 ../src/tools/cephfs/shell/cephfs-shell
49
51 NOTE:
52 Apart from Ceph File System, CephFS Shell commands can also interact
53 directly with the local file system. To achieve this, ! (an exclama‐
54 tion point) must precede the CephFS Shell command.
55 Usage :
57 !<cephfs_shell_command>
58 For example,
60 CephFS:~/>>> !ls # Lists the local file system directory contents.
62 CephFS:~/>>> ls # Lists the Ceph File System directory contents.
63 mkdir
65 Create the directory(ies), if they do not already exist.
66 Usage :
68 mkdir [-option] <directory>...
69 • directory - name of the directory to be created.
71 Options :
73 -m MODE
75 Sets the access mode for the new directory.
76 -p, --parent
78 Create parent directories as necessary. When this option
79 is specified, no error is reported if a directory already
80 exists.
81 put
83 Copy a file/directory to Ceph File System from Local File System.
84 Usage :
86 put [options] <source_path> <target_path>
87 •
89 source_path - local file/directory path to be copied to cephfs.
91 • if . copies all the file/directories in the local working
93 directory.
94 • if - Reads the input from stdin.
96 •
98 target_path - remote directory path where the files/directories are
100 to be copied to.
101 • if . files/directories are copied to the remote working di‐
103 rectory.
104 Options :
106 -f, --force
108 Overwrites the destination if it already exists.
109 get
111 Copy a file from Ceph File System to Local File System.
112 Usage :
114 get [options] <source_path> <target_path>
115 •
117 source_path - remote file/directory path which is to be copied to lo‐
119 cal file system.
120 • if . copies all the file/directories in the remote working
122 directory.
123 •
125 target_path - local directory path where the files/directories are to
127 be copied to.
128 • if . files/directories are copied to the local working di‐
130 rectory.
131 • if - Writes output to stdout.
133 Options:
135 -f, --force
137 Overwrites the destination if it already exists.
138 ls
140 List all the files and directories in the current working directory.
141 Usage :
143 ls [option] [directory]...
144 •
146 directory - name of directory whose files/directories are to be
148 listed.
149 • By default current working directory's files/directories are
151 listed.
152 Options:
154 -l, --long
156 list with long format - show permissions
157 -r, --reverse
159 reverse sort
160 -H human readable
162 -a,-all
164 ignore entries starting with .
165 -S Sort by file_size
167 cat
169 Concatenate files and print on the standard output
170 Usage :
172 cat <file>....
173 • file - name of the file
175 ln
177 Add a hard link to an existing file or create a symbolic link to an ex‐
178 isting file or directory.
179 Usage:
181 ln [options] <target> [link_name]
182 • target - file/directory to which a link is to be created
184 • link_name - link to target with the name link_name
186 Options:
188 -s, --symbolic
190 Create symbolic link
191 -v, --verbose
193 Print name of each linked file
194 -f, --force
196 Force create link/symbolic link
197 cd
199 Change current working directory.
200 Usage :
202 cd [directory]
203 •
205 directory - path/directory name. If no directory is mentioned it is
207 changed to the root directory.
208 • If '.' moves to the parent directory of the current direc‐
210 tory.
211 cwd
213 Get current working directory.
214 Usage :
216 cwd
217 quit/Ctrl + D
219 Close the shell.
220 chmod
222 Change the permissions of file/directory.
223 Usage :
225 chmod <mode> <file/directory>
226 mv
228 Moves files/Directory from source to destination.
229 Usage :
231 mv <source_path> <destination_path>
232 rmdir
234 Delete a directory(ies).
235 Usage :
237 rmdir <directory_name>.....
238 rm
240 Remove a file(es).
241 Usage :
243 rm <file_name/pattern>...
244 write
246 Create and Write a file.
247 Usage :
249 write <file_name> <Enter Data> Ctrl+D Exit.
250 lls
252 Lists all files and directories in the specified directory.Current lo‐
253 cal directory files and directories are listed if no path is men‐
254 tioned
255 Usage:
257 lls <path>.....
258 lcd
260 Moves into the given local directory.
261 Usage :
263 lcd <path>
264 lpwd
266 Prints the absolute path of the current local directory.
267 Usage :
269 lpwd
270 umask
272 Set and get the file mode creation mask
273 Usage :
275 umask [mode]
276 alias
278 Define or display aliases
279 Usage:
281 alias [name] | [<name> <value>]
282 • name - name of the alias being looked up, added, or replaced
284 • value - what the alias will be resolved to (if adding or replacing)
286 this can contain spaces and does not need to be quoted
287 run_pyscript
289 Runs a python script file inside the console
290 Usage:
292 run_pyscript <script_path> [script_arguments]
293 • Console commands can be executed inside this script with cmd ("your
295 command") However, you cannot run nested "py" or "pyscript" commands
296 from within this script. Paths or arguments that contain spaces must
297 be enclosed in quotes
298 NOTE:
300 This command is available as pyscript for cmd2 versions 0.9.13 or
301 less.
302 py
304 Invoke python command, shell, or script
305 Usage :
307 py <command>: Executes a Python command. py: Enters interactive
308 Python mode.
309 shortcuts
311 Lists shortcuts (aliases) available
312 Usage :
314 shortcuts
315 history
317 View, run, edit, and save previously entered commands.
318 Usage :
320 history [-h] [-r | -e | -s | -o FILE | -t TRANSCRIPT] [arg]
321 Options:
323 -h show this help message and exit
325 -r run selected history items
327 -e edit and then run selected history items
329 -s script format; no separation lines
331 -o FILE
333 output commands to a script file
334 -t TRANSCRIPT
336 output commands and results to a transcript file
337 unalias
339 Unsets aliases
340 Usage :
342 unalias [-a] name [name ...]
343 • name - name of the alias being unset
345 Options:
347 -a remove all alias definitions
349 set
351 Sets a settable parameter or shows current settings of parameters.
352 Usage :
354 set [-h] [-a] [-l] [settable [settable ...]]
355 • Call without arguments for a list of settable parameters with their
357 values.
358 Options :
360 -h show this help message and exit
362 -a display read-only settings as well
364 -l describe function of parameter
366 edit
368 Edit a file in a text editor.
369 Usage:
371 edit [file_path]
372 • file_path - path to a file to open in editor
374 run_script
376 Runs commands in script file that is encoded as either ASCII or UTF-8
377 text. Each command in the script should be separated by a newline.
378 Usage:
380 run_script <file_path>
381 • file_path - a file path pointing to a script
383 NOTE:
385 This command is available as load for cmd2 versions 0.9.13 or less.
386 shell
388 Execute a command as if at the OS prompt.
389 Usage:
391 shell <command> [arguments]
392 locate
394 Find an item in File System
395 Usage:
397 locate [options] <name>
398 Options :
400 -c Count number of items found
402 -i Ignore case
404 stat
406 Display file status.
407 Usage :
409 stat [-h] <file_name> [file_name ...]
410 Options :
412 -h Shows the help message
414 snap
416 Create or Delete Snapshot
417 Usage:
419 snap {create|delete} <snap_name> <dir_name>
420 • snap_name - Snapshot name to be created or deleted
422 • dir_name - directory under which snapshot should be created or
424 deleted
425 setxattr
427 Set extended attribute for a file
428 Usage :
430 setxattr [-h] <path> <name> <value>
431 • path - Path to the file
433 • name - Extended attribute name to get or set
435 • value - Extended attribute value to be set
437 Options:
439 -h, --help
441 Shows the help message
442 getxattr
444 Get extended attribute value for the name associated with the path
445 Usage :
447 getxattr [-h] <path> <name>
448 • path - Path to the file
450 • name - Extended attribute name to get or set
452 Options:
454 -h, --help
456 Shows the help message
457 listxattr
459 List extended attribute names associated with the path
460 Usage :
462 listxattr [-h] <path>
463 • path - Path to the file
465 Options:
467 -h, --help
469 Shows the help message
470 df
472 Display amount of available disk space
473 Usage :
475 df [-h] [file [file ...]]
476 • file - name of the file
478 Options:
480 -h, --help
482 Shows the help message
483 du
485 Show disk usage of a directory
486 Usage :
488 du [-h] [-r] [paths [paths ...]]
489 • paths - name of the directory
491 Options:
493 -h, --help
495 Shows the help message
496 -r Recursive Disk usage of all directories
498 quota
500 Quota management for a Directory
501 Usage :
503 quota [-h] [--max_bytes [MAX_BYTES]] [--max_files [MAX_FILES]]
504 {get,set} path
505 • {get,set} - quota operation type.
507 • path - name of the directory.
509 Options :
511 -h, --help
513 Shows the help message
514 --max_bytes MAX_BYTES
516 Set max cumulative size of the data under this directory
517 --max_files MAX_FILES
519 Set total number of files under this directory tree
520
522 By default, CephFS Shell looks for cephfs-shell.conf in the path pro‐
523 vided by the environment variable CEPHFS_SHELL_CONF and then in user's
524 home directory (~/.cephfs-shell.conf).
525 Right now, CephFS Shell inherits all its options from its dependency
527 cmd2. Therefore, these options might vary with the version of cmd2 in‐
528 stalled on your system. Refer to cmd2 docs for a description of these
529 options.
530 Following is a sample cephfs-shell.conf
532 [cephfs-shell]
534 prompt = CephFS:~/>>>
535 continuation_prompt = >
536 quiet = False
538 timing = False
539 colors = True
540 debug = False
541 abbrev = False
543 autorun_on_edit = False
544 echo = False
545 editor = vim
546 feedback_to_output = False
547 locals_in_py = True
548
550 Following exit codes are returned by cephfs shell
551 ┌───────────────────────────┬───────────┐
553 │Error Type │ Exit Code │
554 ├───────────────────────────┼───────────┤
555 │Miscellaneous │ 1 │
556 ├───────────────────────────┼───────────┤
557 │Keyboard Interrupt │ 2 │
558 ├───────────────────────────┼───────────┤
559 │Operation not permitted │ 3 │
560 ├───────────────────────────┼───────────┤
561 │Permission denied │ 4 │
562 ├───────────────────────────┼───────────┤
563 │No such file or directory │ 5 │
564 ├───────────────────────────┼───────────┤
565 │I/O error │ 6 │
566 ├───────────────────────────┼───────────┤
567 │No space left on device │ 7 │
568 ├───────────────────────────┼───────────┤
569 │File exists │ 8 │
570 ├───────────────────────────┼───────────┤
571 │No data available │ 9 │
572 ├───────────────────────────┼───────────┤
573 │Invalid argument │ 10 │
574 ├───────────────────────────┼───────────┤
575 │Operation not supported on │ 11 │
576 │transport endpoint │ │
577 ├───────────────────────────┼───────────┤
578 │Range error │ 12 │
579 ├───────────────────────────┼───────────┤
580 │Operation would block │ 13 │
581 ├───────────────────────────┼───────────┤
582 │Directory not empty │ 14 │
583 ├───────────────────────────┼───────────┤
584 │Not a directory │ 15 │
585 ├───────────────────────────┼───────────┤
586 │Disk quota exceeded │ 16 │
587 ├───────────────────────────┼───────────┤
588 │Broken pipe │ 17 │
589 ├───────────────────────────┼───────────┤
590 │Cannot send after trans‐ │ 18 │
591 │port endpoint shutdown │ │
592 ├───────────────────────────┼───────────┤
593 │Connection aborted │ 19 │
594 ├───────────────────────────┼───────────┤
595 │Connection refused │ 20 │
596 ├───────────────────────────┼───────────┤
597 │Connection reset │ 21 │
598 ├───────────────────────────┼───────────┤
599 │Interrupted function call │ 22 │
600 └───────────────────────────┴───────────┘
601
603 ~/.cephfs-shell.conf
604
606 2010-2023, Inktank Storage, Inc. and contributors. Licensed under Cre‐
607 ative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)
608dev Nov 15, 2023 CEPHFS-SHELL(8)