ceph/doc/man/8/cephfs-shell.rst

   1 :orphan:
   2
   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 ===========
  17
  18 CephFS Shell provides shell-like commands that directly interact with the
  19 Ceph File System.
  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.
  31
  32 Options
  33 =======
  34
  35 .. option:: -b, --batch FILE
  36
  37    Path to batch file.
  38
  39 .. option:: -c, --config FILE
  40
  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
  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
  59     [build]$ python3 -m venv venv && source venv/bin/activate && pip3 install cmd2
  60     [build]$ source vstart_environment.sh && source venv/bin/activate && python3 ../src/tools/cephfs/cephfs-shell
  61
  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
  83 Copy a file/directory to Ceph File System from Local File System.
  84
  85 Usage :
  86
  87         put [options] <source_path> <target_path>
  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
 103 Copy a file from Ceph File System to Local File System.
 104
 105 Usage :
 106
 107     get [options] <source_path> <target_path>
 108
 109 * source_path - remote file/directory path which is to be copied to local file system.
 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
 274 run_pyscript
 275 ------------
 276
 277 Runs a python script file inside the console
 278
 279 Usage:
 280
 281     run_pyscript <script_path> [script_arguments]
 282
 283 * Console commands can be executed inside this script with cmd ("your command")
 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.
 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
 305 Usage :
 306
 307     shortcuts
 308
 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
 351 Options :
 352   -h     show this help message and exit
 353   -a     display read-only settings as well
 354   -l     describe function of parameter
 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
 367 run_script
 368 ----------
 369
 370 Runs commands in script file that is encoded as either ASCII or UTF-8 text.
 371 Each command in the script should be separated by a newline.
 372
 373 Usage:
 374
 375     run_script <file_path>
 376
 377
 378 * file_path - a file path pointing to a script
 379
 380 .. note:: This command is available as ``load`` for cmd2 versions 0.9.13
 381    or less.
 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
 395 Find an item in File System
 396
 397 Usage:
 398
 399      locate [options] <name>
 400
 401 Options :
 402   -c       Count number of items found
 403   -i       Ignore case
 404
 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
 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
 539 Following is a sample ``cephfs-shell.conf``
 540
 541 .. code-block:: ini
 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 +-----------------------------------------------+-----------+
 611
 612 Files
 613 =====
 614
 615 ``~/.cephfs-shell.conf``