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/cephfs-shell
49
51 mkdir
52 Create the directory(ies), if they do not already exist.
53 Usage :
55 mkdir [-option] <directory>...
56 • directory - name of the directory to be created.
58 Options :
60 -m MODE
62 Sets the access mode for the new directory.
63 -p, --parent
65 Create parent directories as necessary. When this option
66 is specified, no error is reported if a directory already
67 exists.
68 put
70 Copy a file/directory to Ceph File System from Local File System.
71 Usage :
73 put [options] <source_path> <target_path>
74 •
76 source_path - local file/directory path to be copied to cephfs.
78 • if . copies all the file/directories in the local working
80 directory.
81 • if - Reads the input from stdin.
83 •
85 target_path - remote directory path where the files/directories are
87 to be copied to.
88 • if . files/directories are copied to the remote working di‐
90 rectory.
91 Options :
93 -f, --force
95 Overwrites the destination if it already exists.
96 get
98 Copy a file from Ceph File System to Local File System.
99 Usage :
101 get [options] <source_path> <target_path>
102 •
104 source_path - remote file/directory path which is to be copied to lo‐
106 cal file system.
107 • if . copies all the file/directories in the remote working
109 directory.
110 •
112 target_path - local directory path where the files/directories are to
114 be copied to.
115 • if . files/directories are copied to the local working di‐
117 rectory.
118 • if - Writes output to stdout.
120 Options:
122 -f, --force
124 Overwrites the destination if it already exists.
125 ls
127 List all the files and directories in the current working directory.
128 Usage :
130 ls [option] [directory]...
131 •
133 directory - name of directory whose files/directories are to be
135 listed.
136 • By default current working directory's files/directories are
138 listed.
139 Options:
141 -l, --long
143 list with long format - show permissions
144 -r, --reverse
146 reverse sort
147 -H human readable
149 -a,-all
151 ignore entries starting with .
152 -S Sort by file_size
154 cat
156 Concatenate files and print on the standard output
157 Usage :
159 cat <file>....
160 • file - name of the file
162 cd
164 Change current working directory.
165 Usage :
167 cd [directory]
168 •
170 directory - path/directory name. If no directory is mentioned it is
172 changed to the root directory.
173 • If '.' moves to the parent directory of the current direc‐
175 tory.
176 cwd
178 Get current working directory.
179 Usage :
181 cwd
182 quit/Ctrl + D
184 Close the shell.
185 chmod
187 Change the permissions of file/directory.
188 Usage :
190 chmod <mode> <file/directory>
191 mv
193 Moves files/Directory from source to destination.
194 Usage :
196 mv <source_path> <destination_path>
197 rmdir
199 Delete a directory(ies).
200 Usage :
202 rmdir <directory_name>.....
203 rm
205 Remove a file(es).
206 Usage :
208 rm <file_name/pattern>...
209 write
211 Create and Write a file.
212 Usage :
214 write <file_name> <Enter Data> Ctrl+D Exit.
215 lls
217 Lists all files and directories in the specified directory.Current lo‐
218 cal directory files and directories are listed if no path is men‐
219 tioned
220 Usage:
222 lls <path>.....
223 lcd
225 Moves into the given local directory.
226 Usage :
228 lcd <path>
229 lpwd
231 Prints the absolute path of the current local directory.
232 Usage :
234 lpwd
235 umask
237 Set and get the file mode creation mask
238 Usage :
240 umask [mode]
241 alias
243 Define or display aliases
244 Usage:
246 alias [name] | [<name> <value>]
247 • name - name of the alias being looked up, added, or replaced
249 • value - what the alias will be resolved to (if adding or replacing)
251 this can contain spaces and does not need to be quoted
252 run_pyscript
254 Runs a python script file inside the console
255 Usage:
257 run_pyscript <script_path> [script_arguments]
258 • Console commands can be executed inside this script with cmd ("your
260 command") However, you cannot run nested "py" or "pyscript" commands
261 from within this script. Paths or arguments that contain spaces must
262 be enclosed in quotes
263 NOTE:
265 This command is available as pyscript for cmd2 versions 0.9.13 or
266 less.
267 py
269 Invoke python command, shell, or script
270 Usage :
272 py <command>: Executes a Python command. py: Enters interactive
273 Python mode.
274 shortcuts
276 Lists shortcuts (aliases) available
277 Usage :
279 shortcuts
280 history
282 View, run, edit, and save previously entered commands.
283 Usage :
285 history [-h] [-r | -e | -s | -o FILE | -t TRANSCRIPT] [arg]
286 Options:
288 -h show this help message and exit
290 -r run selected history items
292 -e edit and then run selected history items
294 -s script format; no separation lines
296 -o FILE
298 output commands to a script file
299 -t TRANSCRIPT
301 output commands and results to a transcript file
302 unalias
304 Unsets aliases
305 Usage :
307 unalias [-a] name [name ...]
308 • name - name of the alias being unset
310 Options:
312 -a remove all alias definitions
314 set
316 Sets a settable parameter or shows current settings of parameters.
317 Usage :
319 set [-h] [-a] [-l] [settable [settable ...]]
320 • Call without arguments for a list of settable parameters with their
322 values.
323 Options :
325 -h show this help message and exit
327 -a display read-only settings as well
329 -l describe function of parameter
331 edit
333 Edit a file in a text editor.
334 Usage:
336 edit [file_path]
337 • file_path - path to a file to open in editor
339 run_script
341 Runs commands in script file that is encoded as either ASCII or UTF-8
342 text. Each command in the script should be separated by a newline.
343 Usage:
345 run_script <file_path>
346 • file_path - a file path pointing to a script
348 NOTE:
350 This command is available as load for cmd2 versions 0.9.13 or less.
351 shell
353 Execute a command as if at the OS prompt.
354 Usage:
356 shell <command> [arguments]
357 locate
359 Find an item in File System
360 Usage:
362 locate [options] <name>
363 Options :
365 -c Count number of items found
367 -i Ignore case
369 stat
371 Display file status.
372 Usage :
374 stat [-h] <file_name> [file_name ...]
375 Options :
377 -h Shows the help message
379 snap
381 Create or Delete Snapshot
382 Usage:
384 snap {create|delete} <snap_name> <dir_name>
385 • snap_name - Snapshot name to be created or deleted
387 • dir_name - directory under which snapshot should be created or
389 deleted
390 setxattr
392 Set extended attribute for a file
393 Usage :
395 setxattr [-h] <path> <name> <value>
396 • path - Path to the file
398 • name - Extended attribute name to get or set
400 • value - Extended attribute value to be set
402 Options:
404 -h, --help
406 Shows the help message
407 getxattr
409 Get extended attribute value for the name associated with the path
410 Usage :
412 getxattr [-h] <path> <name>
413 • path - Path to the file
415 • name - Extended attribute name to get or set
417 Options:
419 -h, --help
421 Shows the help message
422 listxattr
424 List extended attribute names associated with the path
425 Usage :
427 listxattr [-h] <path>
428 • path - Path to the file
430 Options:
432 -h, --help
434 Shows the help message
435 df
437 Display amount of available disk space
438 Usage :
440 df [-h] [file [file ...]]
441 • file - name of the file
443 Options:
445 -h, --help
447 Shows the help message
448 du
450 Show disk usage of a directory
451 Usage :
453 du [-h] [-r] [paths [paths ...]]
454 • paths - name of the directory
456 Options:
458 -h, --help
460 Shows the help message
461 -r Recursive Disk usage of all directories
463 quota
465 Quota management for a Directory
466 Usage :
468 quota [-h] [--max_bytes [MAX_BYTES]] [--max_files [MAX_FILES]]
469 {get,set} path
470 • {get,set} - quota operation type.
472 • path - name of the directory.
474 Options :
476 -h, --help
478 Shows the help message
479 --max_bytes MAX_BYTES
481 Set max cumulative size of the data under this directory
482 --max_files MAX_FILES
484 Set total number of files under this directory tree
485
487 By default, CephFS Shell looks for cephfs-shell.conf in the path pro‐
488 vided by the environment variable CEPHFS_SHELL_CONF and then in user's
489 home directory (~/.cephfs-shell.conf).
490 Right now, CephFS Shell inherits all its options from its dependency
492 cmd2. Therefore, these options might vary with the version of cmd2 in‐
493 stalled on your system. Refer to cmd2 docs for a description of these
494 options.
495 Following is a sample cephfs-shell.conf
497 [cephfs-shell]
499 prompt = CephFS:~/>>>
500 continuation_prompt = >
501 quiet = False
503 timing = False
504 colors = True
505 debug = False
506 abbrev = False
508 autorun_on_edit = False
509 echo = False
510 editor = vim
511 feedback_to_output = False
512 locals_in_py = True
513
515 Following exit codes are returned by cephfs shell
516 ┌───────────────────────────┬───────────┐
518 │Error Type │ Exit Code │
519 ├───────────────────────────┼───────────┤
520 │Miscellaneous │ 1 │
521 ├───────────────────────────┼───────────┤
522 │Keyboard Interrupt │ 2 │
523 ├───────────────────────────┼───────────┤
524 │Operation not permitted │ 3 │
525 ├───────────────────────────┼───────────┤
526 │Permission denied │ 4 │
527 ├───────────────────────────┼───────────┤
528 │No such file or directory │ 5 │
529 ├───────────────────────────┼───────────┤
530 │I/O error │ 6 │
531 ├───────────────────────────┼───────────┤
532 │No space left on device │ 7 │
533 ├───────────────────────────┼───────────┤
534 │File exists │ 8 │
535 ├───────────────────────────┼───────────┤
536 │No data available │ 9 │
537 └───────────────────────────┴───────────┘
538 │Invalid argument │ 10 │
540 ├───────────────────────────┼───────────┤
541 │Operation not supported on │ 11 │
542 │transport endpoint │ │
543 ├───────────────────────────┼───────────┤
544 │Range error │ 12 │
545 ├───────────────────────────┼───────────┤
546 │Operation would block │ 13 │
547 ├───────────────────────────┼───────────┤
548 │Directory not empty │ 14 │
549 ├───────────────────────────┼───────────┤
550 │Not a directory │ 15 │
551 ├───────────────────────────┼───────────┤
552 │Disk quota exceeded │ 16 │
553 ├───────────────────────────┼───────────┤
554 │Broken pipe │ 17 │
555 ├───────────────────────────┼───────────┤
556 │Cannot send after trans‐ │ 18 │
557 │port endpoint shutdown │ │
558 ├───────────────────────────┼───────────┤
559 │Connection aborted │ 19 │
560 ├───────────────────────────┼───────────┤
561 │Connection refused │ 20 │
562 ├───────────────────────────┼───────────┤
563 │Connection reset │ 21 │
564 ├───────────────────────────┼───────────┤
565 │Interrupted function call │ 22 │
566 └───────────────────────────┴───────────┘
567
569 ~/.cephfs-shell.conf
570
572 2010-2022, Inktank Storage, Inc. and contributors. Licensed under Cre‐
573 ative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)
574dev Oct 18, 2022 CEPHFS-SHELL(8)