]>
Commit | Line | Data |
---|---|---|
20effc67 | 1 | :orphan: |
11fdf7f2 | 2 | |
20effc67 TL |
3 | =================================================== |
4 | cephfs-shell -- Shell-like tool talking with CephFS | |
5 | =================================================== | |
6 | ||
7 | .. program:: cephfs-shell | |
8 | ||
9 | Synopsis | |
10 | ======== | |
11 | ||
12 | | **cephfs-shell** [options] [command] | |
13 | | **cephfs-shell** [options] -- [command, command,...] | |
14 | ||
15 | Description | |
16 | =========== | |
11fdf7f2 | 17 | |
f67539c2 | 18 | CephFS Shell provides shell-like commands that directly interact with the |
20effc67 | 19 | Ceph File System. |
f67539c2 TL |
20 | |
21 | This tool can be used in interactive mode as well as in non-interactive mode. | |
22 | In former mode, cephfs-shell opens a shell session and after the given command | |
23 | is finished, it prints the prompt string and waits indefinitely. When the | |
24 | shell session is finished, cephfs-shell quits with the return value of last | |
25 | executed command. In non-interactive mode, cephfs-shell issues a command and | |
26 | exits right after the command's execution is complete with the command's | |
27 | return value. | |
28 | ||
29 | Behaviour of CephFS Shell can be tweaked using ``cephfs-shell.conf``. Refer to | |
30 | `CephFS Shell Configuration File`_ for details. | |
11fdf7f2 | 31 | |
20effc67 TL |
32 | Options |
33 | ======= | |
11fdf7f2 | 34 | |
20effc67 | 35 | .. option:: -b, --batch FILE |
11fdf7f2 | 36 | |
20effc67 TL |
37 | Path to batch file. |
38 | ||
39 | .. option:: -c, --config FILE | |
11fdf7f2 | 40 | |
20effc67 TL |
41 | Path to cephfs-shell.conf |
42 | ||
43 | .. option:: -f, --fs FS | |
44 | ||
45 | Name of filesystem to mount. | |
46 | ||
47 | .. option:: -t, --test FILE | |
48 | ||
49 | Path to transcript(s) in FILE for testing | |
9f95a23c TL |
50 | |
51 | .. note:: | |
52 | ||
53 | Latest version of the cmd2 module is required for running cephfs-shell. | |
54 | If CephFS is installed through source, execute cephfs-shell in the build | |
55 | directory. It can also be executed as following using virtualenv: | |
56 | ||
57 | .. code:: bash | |
58 | ||
a4b75251 | 59 | [build]$ python3 -m venv venv && source venv/bin/activate && pip3 install cmd2 |
9f95a23c TL |
60 | [build]$ source vstart_environment.sh && source venv/bin/activate && python3 ../src/tools/cephfs/cephfs-shell |
61 | ||
11fdf7f2 TL |
62 | Commands |
63 | ======== | |
64 | ||
65 | mkdir | |
66 | ----- | |
67 | ||
68 | Create the directory(ies), if they do not already exist. | |
69 | ||
70 | Usage : | |
71 | ||
72 | mkdir [-option] <directory>... | |
73 | ||
74 | * directory - name of the directory to be created. | |
75 | ||
76 | Options : | |
77 | -m MODE Sets the access mode for the new directory. | |
78 | -p, --parent Create parent directories as necessary. When this option is specified, no error is reported if a directory already exists. | |
79 | ||
80 | put | |
81 | --- | |
82 | ||
9f95a23c | 83 | Copy a file/directory to Ceph File System from Local File System. |
11fdf7f2 TL |
84 | |
85 | Usage : | |
86 | ||
33c7a0ef | 87 | put [options] <source_path> <target_path> |
11fdf7f2 TL |
88 | |
89 | * source_path - local file/directory path to be copied to cephfs. | |
90 | * if `.` copies all the file/directories in the local working directory. | |
91 | * if `-` Reads the input from stdin. | |
92 | ||
93 | * target_path - remote directory path where the files/directories are to be copied to. | |
94 | * if `.` files/directories are copied to the remote working directory. | |
95 | ||
96 | Options : | |
97 | -f, --force Overwrites the destination if it already exists. | |
98 | ||
99 | ||
100 | get | |
101 | --- | |
102 | ||
9f95a23c | 103 | Copy a file from Ceph File System to Local File System. |
11fdf7f2 TL |
104 | |
105 | Usage : | |
106 | ||
33c7a0ef | 107 | get [options] <source_path> <target_path> |
11fdf7f2 | 108 | |
9f95a23c | 109 | * source_path - remote file/directory path which is to be copied to local file system. |
11fdf7f2 TL |
110 | * if `.` copies all the file/directories in the remote working directory. |
111 | ||
112 | * target_path - local directory path where the files/directories are to be copied to. | |
113 | * if `.` files/directories are copied to the local working directory. | |
114 | * if `-` Writes output to stdout. | |
115 | ||
116 | Options: | |
117 | -f, --force Overwrites the destination if it already exists. | |
118 | ||
119 | ls | |
120 | -- | |
121 | ||
122 | List all the files and directories in the current working directory. | |
123 | ||
124 | Usage : | |
125 | ||
126 | ls [option] [directory]... | |
127 | ||
128 | * directory - name of directory whose files/directories are to be listed. | |
129 | * By default current working directory's files/directories are listed. | |
130 | ||
131 | Options: | |
132 | -l, --long list with long format - show permissions | |
133 | -r, --reverse reverse sort | |
134 | -H human readable | |
135 | -a, -all ignore entries starting with . | |
136 | -S Sort by file_size | |
137 | ||
138 | ||
139 | cat | |
140 | --- | |
141 | ||
142 | Concatenate files and print on the standard output | |
143 | ||
144 | Usage : | |
145 | ||
146 | cat <file>.... | |
147 | ||
148 | * file - name of the file | |
149 | ||
150 | cd | |
151 | -- | |
152 | ||
153 | Change current working directory. | |
154 | ||
155 | Usage : | |
156 | ||
157 | cd [directory] | |
158 | ||
159 | * directory - path/directory name. If no directory is mentioned it is changed to the root directory. | |
160 | * If '.' moves to the parent directory of the current directory. | |
161 | ||
162 | cwd | |
163 | --- | |
164 | ||
165 | Get current working directory. | |
166 | ||
167 | Usage : | |
168 | ||
169 | cwd | |
170 | ||
171 | ||
172 | quit/Ctrl + D | |
173 | ------------- | |
174 | ||
175 | Close the shell. | |
176 | ||
177 | chmod | |
178 | ----- | |
179 | ||
180 | Change the permissions of file/directory. | |
181 | ||
182 | Usage : | |
183 | ||
184 | chmod <mode> <file/directory> | |
185 | ||
186 | mv | |
187 | -- | |
188 | ||
189 | Moves files/Directory from source to destination. | |
190 | ||
191 | Usage : | |
192 | ||
193 | mv <source_path> <destination_path> | |
194 | ||
195 | rmdir | |
196 | ----- | |
197 | ||
198 | Delete a directory(ies). | |
199 | ||
200 | Usage : | |
201 | ||
202 | rmdir <directory_name>..... | |
203 | ||
204 | rm | |
205 | -- | |
206 | ||
207 | Remove a file(es). | |
208 | ||
209 | Usage : | |
210 | ||
211 | rm <file_name/pattern>... | |
212 | ||
213 | ||
214 | write | |
215 | ----- | |
216 | ||
217 | Create and Write a file. | |
218 | ||
219 | Usage : | |
220 | ||
221 | write <file_name> | |
222 | <Enter Data> | |
223 | Ctrl+D Exit. | |
224 | ||
225 | lls | |
226 | --- | |
227 | ||
228 | Lists all files and directories in the specified directory.Current local directory files and directories are listed if no path is mentioned | |
229 | ||
230 | Usage: | |
231 | ||
232 | lls <path>..... | |
233 | ||
234 | lcd | |
235 | --- | |
236 | ||
237 | Moves into the given local directory. | |
238 | ||
239 | Usage : | |
240 | ||
241 | lcd <path> | |
242 | ||
243 | lpwd | |
244 | ---- | |
245 | ||
246 | Prints the absolute path of the current local directory. | |
247 | ||
248 | Usage : | |
249 | ||
250 | lpwd | |
251 | ||
252 | ||
253 | umask | |
254 | ----- | |
255 | ||
256 | Set and get the file mode creation mask | |
257 | ||
258 | Usage : | |
259 | ||
260 | umask [mode] | |
261 | ||
262 | alias | |
263 | ----- | |
264 | ||
265 | Define or display aliases | |
266 | ||
267 | Usage: | |
268 | ||
269 | alias [name] | [<name> <value>] | |
270 | ||
271 | * name - name of the alias being looked up, added, or replaced | |
272 | * value - what the alias will be resolved to (if adding or replacing) this can contain spaces and does not need to be quoted | |
273 | ||
9f95a23c TL |
274 | run_pyscript |
275 | ------------ | |
11fdf7f2 TL |
276 | |
277 | Runs a python script file inside the console | |
278 | ||
279 | Usage: | |
280 | ||
9f95a23c | 281 | run_pyscript <script_path> [script_arguments] |
11fdf7f2 TL |
282 | |
283 | * Console commands can be executed inside this script with cmd ("your command") | |
9f95a23c TL |
284 | However, you cannot run nested "py" or "pyscript" commands from within this |
285 | script. Paths or arguments that contain spaces must be enclosed in quotes | |
286 | ||
287 | .. note:: This command is available as ``pyscript`` for cmd2 versions 0.9.13 | |
288 | or less. | |
11fdf7f2 TL |
289 | |
290 | py | |
291 | -- | |
292 | ||
293 | Invoke python command, shell, or script | |
294 | ||
295 | Usage : | |
296 | ||
297 | py <command>: Executes a Python command. | |
298 | py: Enters interactive Python mode. | |
299 | ||
300 | shortcuts | |
301 | --------- | |
302 | ||
303 | Lists shortcuts (aliases) available | |
304 | ||
9f95a23c TL |
305 | Usage : |
306 | ||
307 | shortcuts | |
308 | ||
11fdf7f2 TL |
309 | history |
310 | ------- | |
311 | ||
312 | View, run, edit, and save previously entered commands. | |
313 | ||
314 | Usage : | |
315 | ||
316 | history [-h] [-r | -e | -s | -o FILE | -t TRANSCRIPT] [arg] | |
317 | ||
318 | Options: | |
319 | -h show this help message and exit | |
320 | -r run selected history items | |
321 | -e edit and then run selected history items | |
322 | -s script format; no separation lines | |
323 | -o FILE output commands to a script file | |
324 | -t TRANSCRIPT output commands and results to a transcript file | |
325 | ||
326 | unalias | |
327 | ------- | |
328 | ||
329 | Unsets aliases | |
330 | ||
331 | Usage : | |
332 | ||
333 | unalias [-a] name [name ...] | |
334 | ||
335 | * name - name of the alias being unset | |
336 | ||
337 | Options: | |
338 | -a remove all alias definitions | |
339 | ||
340 | set | |
341 | --- | |
342 | ||
343 | Sets a settable parameter or shows current settings of parameters. | |
344 | ||
345 | Usage : | |
346 | ||
347 | set [-h] [-a] [-l] [settable [settable ...]] | |
348 | ||
349 | * Call without arguments for a list of settable parameters with their values. | |
350 | ||
9f95a23c TL |
351 | Options : |
352 | -h show this help message and exit | |
353 | -a display read-only settings as well | |
354 | -l describe function of parameter | |
11fdf7f2 TL |
355 | |
356 | edit | |
357 | ---- | |
358 | ||
359 | Edit a file in a text editor. | |
360 | ||
361 | Usage: | |
362 | ||
363 | edit [file_path] | |
364 | ||
365 | * file_path - path to a file to open in editor | |
366 | ||
9f95a23c TL |
367 | run_script |
368 | ---------- | |
11fdf7f2 TL |
369 | |
370 | Runs commands in script file that is encoded as either ASCII or UTF-8 text. | |
9f95a23c | 371 | Each command in the script should be separated by a newline. |
11fdf7f2 TL |
372 | |
373 | Usage: | |
374 | ||
9f95a23c TL |
375 | run_script <file_path> |
376 | ||
11fdf7f2 TL |
377 | |
378 | * file_path - a file path pointing to a script | |
379 | ||
9f95a23c TL |
380 | .. note:: This command is available as ``load`` for cmd2 versions 0.9.13 |
381 | or less. | |
11fdf7f2 TL |
382 | |
383 | shell | |
384 | ----- | |
385 | ||
386 | Execute a command as if at the OS prompt. | |
387 | ||
388 | Usage: | |
389 | ||
390 | shell <command> [arguments] | |
391 | ||
392 | locate | |
393 | ------ | |
394 | ||
9f95a23c | 395 | Find an item in File System |
11fdf7f2 TL |
396 | |
397 | Usage: | |
9f95a23c | 398 | |
11fdf7f2 TL |
399 | locate [options] <name> |
400 | ||
401 | Options : | |
402 | -c Count number of items found | |
403 | -i Ignore case | |
404 | ||
9f95a23c TL |
405 | stat |
406 | ------ | |
407 | ||
408 | Display file status. | |
409 | ||
410 | Usage : | |
411 | ||
412 | stat [-h] <file_name> [file_name ...] | |
413 | ||
414 | Options : | |
415 | -h Shows the help message | |
416 | ||
417 | snap | |
418 | ---- | |
419 | ||
420 | Create or Delete Snapshot | |
421 | ||
422 | Usage: | |
423 | ||
424 | snap {create|delete} <snap_name> <dir_name> | |
425 | ||
426 | * snap_name - Snapshot name to be created or deleted | |
427 | ||
428 | * dir_name - directory under which snapshot should be created or deleted | |
429 | ||
430 | setxattr | |
431 | -------- | |
432 | ||
433 | Set extended attribute for a file | |
434 | ||
435 | Usage : | |
436 | ||
437 | setxattr [-h] <path> <name> <value> | |
438 | ||
439 | * path - Path to the file | |
440 | ||
441 | * name - Extended attribute name to get or set | |
442 | ||
443 | * value - Extended attribute value to be set | |
444 | ||
445 | Options: | |
446 | -h, --help Shows the help message | |
447 | ||
448 | getxattr | |
449 | -------- | |
450 | ||
451 | Get extended attribute value for the name associated with the path | |
452 | ||
453 | Usage : | |
454 | ||
455 | getxattr [-h] <path> <name> | |
456 | ||
457 | * path - Path to the file | |
458 | ||
459 | * name - Extended attribute name to get or set | |
460 | ||
461 | Options: | |
462 | -h, --help Shows the help message | |
463 | ||
464 | listxattr | |
465 | --------- | |
466 | ||
467 | List extended attribute names associated with the path | |
468 | ||
469 | Usage : | |
470 | ||
471 | listxattr [-h] <path> | |
472 | ||
473 | * path - Path to the file | |
474 | ||
475 | Options: | |
476 | -h, --help Shows the help message | |
f67539c2 TL |
477 | |
478 | df | |
479 | -- | |
480 | ||
481 | Display amount of available disk space | |
482 | ||
483 | Usage : | |
484 | ||
485 | df [-h] [file [file ...]] | |
486 | ||
487 | * file - name of the file | |
488 | ||
489 | Options: | |
490 | -h, --help Shows the help message | |
491 | ||
492 | du | |
493 | -- | |
494 | ||
495 | Show disk usage of a directory | |
496 | ||
497 | Usage : | |
498 | ||
499 | du [-h] [-r] [paths [paths ...]] | |
500 | ||
501 | * paths - name of the directory | |
502 | ||
503 | Options: | |
504 | -h, --help Shows the help message | |
505 | ||
506 | -r Recursive Disk usage of all directories | |
507 | ||
508 | ||
509 | quota | |
510 | ----- | |
511 | ||
512 | Quota management for a Directory | |
513 | ||
514 | Usage : | |
515 | ||
516 | quota [-h] [--max_bytes [MAX_BYTES]] [--max_files [MAX_FILES]] {get,set} path | |
517 | ||
518 | * {get,set} - quota operation type. | |
519 | ||
520 | * path - name of the directory. | |
521 | ||
522 | Options : | |
523 | -h, --help Shows the help message | |
524 | ||
525 | --max_bytes MAX_BYTES Set max cumulative size of the data under this directory | |
526 | ||
527 | --max_files MAX_FILES Set total number of files under this directory tree | |
528 | ||
529 | CephFS Shell Configuration File | |
530 | =============================== | |
531 | By default, CephFS Shell looks for ``cephfs-shell.conf`` in the path provided | |
532 | by the environment variable ``CEPHFS_SHELL_CONF`` and then in user's home | |
533 | directory (``~/.cephfs-shell.conf``). | |
534 | ||
535 | Right now, CephFS Shell inherits all its options from its dependency ``cmd2``. | |
536 | Therefore, these options might vary with the version of ``cmd2`` installed on | |
537 | your system. Refer to ``cmd2`` docs for a description of these options. | |
538 | ||
20effc67 TL |
539 | Following is a sample ``cephfs-shell.conf`` |
540 | ||
541 | .. code-block:: ini | |
f67539c2 TL |
542 | |
543 | [cephfs-shell] | |
544 | prompt = CephFS:~/>>> | |
545 | continuation_prompt = > | |
546 | ||
547 | quiet = False | |
548 | timing = False | |
549 | colors = True | |
550 | debug = False | |
551 | ||
552 | abbrev = False | |
553 | autorun_on_edit = False | |
554 | echo = False | |
555 | editor = vim | |
556 | feedback_to_output = False | |
557 | locals_in_py = True | |
558 | ||
559 | Exit Code | |
560 | ========= | |
561 | ||
562 | Following exit codes are returned by cephfs shell | |
563 | ||
564 | +-----------------------------------------------+-----------+ | |
565 | | Error Type | Exit Code | | |
566 | +===============================================+===========+ | |
567 | | Miscellaneous | 1 | | |
568 | +-----------------------------------------------+-----------+ | |
569 | | Keyboard Interrupt | 2 | | |
570 | +-----------------------------------------------+-----------+ | |
571 | | Operation not permitted | 3 | | |
572 | +-----------------------------------------------+-----------+ | |
573 | | Permission denied | 4 | | |
574 | +-----------------------------------------------+-----------+ | |
575 | | No such file or directory | 5 | | |
576 | +-----------------------------------------------+-----------+ | |
577 | | I/O error | 6 | | |
578 | +-----------------------------------------------+-----------+ | |
579 | | No space left on device | 7 | | |
580 | +-----------------------------------------------+-----------+ | |
581 | | File exists | 8 | | |
582 | +-----------------------------------------------+-----------+ | |
583 | | No data available | 9 | | |
584 | +-----------------------------------------------+-----------+ | |
585 | | Invalid argument | 10 | | |
586 | +-----------------------------------------------+-----------+ | |
587 | | Operation not supported on transport endpoint | 11 | | |
588 | +-----------------------------------------------+-----------+ | |
589 | | Range error | 12 | | |
590 | +-----------------------------------------------+-----------+ | |
591 | | Operation would block | 13 | | |
592 | +-----------------------------------------------+-----------+ | |
593 | | Directory not empty | 14 | | |
594 | +-----------------------------------------------+-----------+ | |
595 | | Not a directory | 15 | | |
596 | +-----------------------------------------------+-----------+ | |
597 | | Disk quota exceeded | 16 | | |
598 | +-----------------------------------------------+-----------+ | |
599 | | Broken pipe | 17 | | |
600 | +-----------------------------------------------+-----------+ | |
601 | | Cannot send after transport endpoint shutdown | 18 | | |
602 | +-----------------------------------------------+-----------+ | |
603 | | Connection aborted | 19 | | |
604 | +-----------------------------------------------+-----------+ | |
605 | | Connection refused | 20 | | |
606 | +-----------------------------------------------+-----------+ | |
607 | | Connection reset | 21 | | |
608 | +-----------------------------------------------+-----------+ | |
609 | | Interrupted function call | 22 | | |
610 | +-----------------------------------------------+-----------+ | |
20effc67 TL |
611 | |
612 | Files | |
613 | ===== | |
614 | ||
615 | ``~/.cephfs-shell.conf`` |