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