CELESTEFS COMMAND LINE INTERFACE
The celestefs programme is a command line interface to the higher-level Celeste file store. This interface gives you the capabilities of creating namespaces and credentials, and manipulating Celeste data files in a hierarchical file system.
The general form of the command line invocation is:
celestefs --id name --password password [--celeste-address address:port] [--celeste-timeout seconds] operation
Unless otherwise specified, all parameters are encoded as UTF-8 strings. In cases where a null value is to be supplied, it is specified by the keyword null.
COMMAND LINE PARAMETERS
--id name Specifies the name of the credential to use for this operation (See the operation mkid).
--password passphrase Specifies the password to the credential used for this operation.
--celeste-address address:port Specifies the address and tcp-port number of the Celeste node to contact to perform the specified operation. If --celeste-address is left unspecified, the default value used for the address and port of the Celeste node is 127.0.0.1:14000 Note that any Celeste node is capable of performing the operation and you can distribute the operations among many nodes.
--celeste-timeout seconds Specifies the number of seconds to wait for each low-level Celeste operation to complete.
Attributes
Some operations allow you to specify attributes, information associated with a file that the file system implementation understands and uses to maintain the associated file. The command line representation of an attribute is --attr name=value; this syntax can be repeated to supply values for multiple attributes and follows the operation name on the command line. Attributes differ from properties (see below).
| Name | Description |
|---|---|
| Acl | The name of the access control list attribute, which dictates what permissions a given file operation requires. This attribute is settable at file creation time and is subsequently modifiable. See FileAttributes.Names.ACL_NAME |
| BlockSize | The name of the block size attribute, which determines the size of the BlockObjects used to store the file's contents in Celeste. This attribute is settable at file creation time, but is not subsequently modifiable. See FileAttributes.Names.BLOCK_SIZE_NAME |
| CacheEnabled | The name of the buffer cache enabled attribute, which determines whether or not data from a given modification to the file will be stored locally in the client-side buffer cache. This attribute is transitory, applying only to the handle used to access the file, as opposed to the file itself. It may be set at any time. Note that this attribute is designed for use in contexts where the same file access handle will be used multiple times to read or write the file; this condition does not hold for the celestefs interface and the attribute should be left with its default value when accessing a file through celestefs. See FileAttributes.Names.CACHE_ENABLED_NAME |
| ClientMetadata | The name of the client metadata attribute, which records client-supplied metadata that the file system implementation simply stores and retrieves upon request, without itself interpreting or using the metadata. This attribute is settable at file creation time and is subsequently modifiable. See FileAttributes.Names.CLIENT_METADATA_NAME |
| ContentType | The name of the content type attribute, which records the file's MIME type. This attribute is settable at file creation time, but is not subsequently modifiable. See FileAttributes.Names.CONTENT_TYPE_NAME |
| CreatedTime | The name of the file creation time attribute. This attribute is set by the file system implementation when a file is created and is not subsequently modifiable. See FileAttributes.Names.CREATED_TIME_NAME |
| DeletionTimeToLive | The name of the deletion time to live attribute, which gives the number of seconds each Celeste object used to represent a given file will remain within Celeste after that file has been deleted. This attribute is settable at file creation time and can be modified from then until the file is deleted. See FileAttributes.Names.DELETION_TIME_TO_LIVE_NAME |
| FileSerialNumber | The name of the file serial number (inode number) attribute. This attribute is set by the file system implementation when a file is created and is not subsequently modifiable. See FileAttributes.Names.FILE_SERIAL_NUMBER_NAME |
| Deleted | The name of the <q>is deleted</q> attribute. This attribute is set by the file system implementation to reflect a file's deletion status and cannot otherwise be modified. See FileAttributes.Names.IS_DELETED_NAME |
| MetadataChangedTime | The name of the metadata changed time attribute, which records when file metadata was last changed. This attribute is updated as necessary by the file system implementation and cannot otherwise be modified. See FileAttributes.Names.METADATA_CHANGED_TIME_NAME |
| ModifiedTime | The name of the file modification time attribute. This attribute is set by the file system implementation when a file is created and updated whenever that file is modified. It cannot otherwise be modified. See FileAttributes.Names.MODIFIED_TIME_NAME |
| ReplicationParameters | The name of the file replication parameters attribute, which dictates how much redundancy Celeste should maintain when storing a file. This attribute is settable at file creation time, but is not subsequently modifiable. See FileAttributes.Names.REPLICATION_PARAMETERS_NAME |
| SignModifications | The name of the <q>data must be signed</q> attribute, which dictates whether operations that modify the file must be digitally signed. This attribute is settable at file creation time, but is not subsequently modifiable. See FileAttributes.Names.SIGN_MODIFICATIONS_NAME |
| TimeToLive | The name of the time to live attribute, which gives the number of seconds each Celeste object used to represent a given file will remain within Celeste. This attribute is settable at file creation time, but is not subsequently modifiable. See FileAttributes.Names.TIME_TO_LIVE_NAME |
Properties
Some operations allow properties to be specified as well as attributes. A property is user-supplied file metadata that the file system simply records and regurgitates without itself using for its own purposes. The command line representation of a property is --prop name=value. Where allowed at all, property specifications can be intermixed with attribute specifications.
Operations
Operations consist of one of the following set of command line parameters
create Create a named file within a specified file-system.
The specified file-system and creator credential must have already been created (see the mkfs and mkid operations).
| <path-name> | The full path-name file to create. |
$ celestefs --id meMyselfAndI --password plugh create [--attr|--prop name=value]... /meMyselfAndI/fubar
getAttributes Get selected attributes for a given file.
If no -attr flags are given, reports on all attributes.
| optional: --attr name | An attribute whose value is to be reported. This option can be repeated. |
$ celestefs --id meMyselfAndI --password plugh getAttributes --attr signModifications /meMyselfAndI/fubar
getProperties Get selected properties for a given file.
If no -prop flags are given, reports on all properties.
| optional: --prop name | A property whose value is to be reported. This option can be repeated. |
$ celestefs --id meMyselfAndI --password plugh getProperties --prop myFunkyProperty --prop anotherProperty /meMyselfAndI/fubar
ls Display file metadata.
| optional: -l | Display a long form of output including content-type, size, modified-time, and file-name. |
| optional: -s | Display a short form of output including size and file-name. |
| <path-name> | The full path-name of the file. |
$ celestefs --id meMyselfAndI --password plugh ls -l /meMyselfAndI/
0:owner@:[deleteFile, inspectFile, readFile, setACL, setFileLength, setUserAndGroup, writeFile]:grant
1:group@:[readFile]:grant
X-Celeste/Directory 2 2008-08-16 01:33:57 /
mkdir Create a directory.
| <path-name> | The full path-name of the directory to create. |
$ celestefs --id meMyselfAndI --password plugh mkdir [--attr|--prop name=value]... /myMyselfAndI/foo
mkfs Create a new Celeste filesystem.
Any attributes supplied apply to the root directory of the new filesystem.
| <name> | The name of the new filesystem. |
$ celestefs --id meMyselfAndI --password plugh \
mkfs --attr 'ReplicationParameters=AObject.Replication.Store=3;VObject.Replication.Store=3;BObject.Replication.Store=3;' [--attr name=value ]... meMyselfAndI
mkid Create a new credential in the Celeste system.
The credential name and password are specified by the --id and --password command line arguments.
$ celestefs --id meMyselfAndI --password plugh mkid --attr 'ReplicationParameters=AObject.Replication.Store=3;VObject.Replication.Store=3;BObject.Replication.Store=3;'
pread Read data from a Celeste file.
| <path-name> | The full path-name of the file. (See the operation create) |
| <offset> | The decimal value of the byte offset to start reading. |
| <length> | The decimal value of the number of bytes to read. The special value -1 signifies to read until end-of-file. |
$ celestefs --id meMyselfAndI --password plugh pread /meMyselfAndI/fubar 0 -1 Hello World
pwrite Write to a Celeste file
Read data from the standard input and write it to the named Celeste file.
| --buffer-size size | An optional flag specifying the amount of data to transfer with each write |
| <path-name> | The full path-name of the file. (See the operation create) |
| <offset> | The decimal value of the byte offset to start writing. |
$ echo 'Hello World' | celestefs --id meMyselfAndI --password plugh pwrite --buffer-size 65536 /meMyselfAndI/fubar 0
rm Remove a Celeste file.
| <path-name> | The full path-name of the file. (See the operation create) |
$ echo 'Hello World' | celestefs --id meMyselfAndI --password plugh rm /meMyselfAndI/fubar
readdir Read a Celeste directory.
| <path-name> | The full path-name of the directory. (See the operation mkdir) |
$ celestefs --id meMyselfAndI --password plugh readdir /meMyselfAndI
rename Rename a Celeste file.
| <from-name> | The full path-name of the file to rename. (See the operation create) |
| <to-name> | The full path-name of the new file name. |
$ celestefs --id meMyselfAndI --password plugh rename /meMyselfAndI/fubar /meMySelfAndId/foobar
set-length Set the length of a Celeste file.
| <pathname> | The full path-name of the file. (See the operation create) |
| <length> | The new length of the file. |
$ celestefs --id meMyselfAndI --password plugh set-length /meMyselfAndI/fubar 6
test Test a file.
| -e | Success if this file exists. |
| -d | Success if this file exists and is a directory. |
| -t content-type | Success if this file exists and has the content-type type. |
| <path-name> | The full path-name of the file to test. (See the operation create) |
$ echo 'Hello World' | celestefs --id meMyselfAndI --password plugh rm /meMyselfAndI/fubar
write copy a file in chunks from the local file system to the Celeste file system.
Works by doing repeated writes of the length given by the --buffer-size flag (defaults to 256KB).
| --buffer-size size | An optional flag specifying the amount of data to transfer with each write |
| <path-name> | The full path-name of the file. (See the operation create) |
| <offset> | The decimal value of the byte offset to start writing. |
| <local-file> | The name of a file in the local file system that is to act as the source of the data to be written |
$ celestefs --id meMyselfAndI --password plugh write --buffer-size 65536 /meMyselfAndI/bigFile 0 bigFileToCopy
write-file copy a file from the local file system to the Celeste file system.
Works by doing a single write of the entire local file into Celeste (which is practical only for files small enough to fit into the heap of the JVM doing the actual copy).
| <path-name> | The full path-name of the file. (See the operation create) |
| <offset> | The decimal value of the byte offset to start writing. |
| <local-file> | The name of a file in the local file system that is to act as the source of the data to be written |
$ celestefs --id meMyselfAndI --password plugh write-file /meMyselfAndI/someFile 0 someFileToCopy
PUTTING IT ALL TOGETHER
The example below is from the shell-script languages/bash/celestefs-example in the top-level directory of the Celeste installation.
$ celestefs \--id meMyselfAndI \--password plugh mkid $ celestefs \--id meMyselfAndI \--password plugh mkfs celestefs-example fspw $ celestefs \--id meMyselfAndI \--password plugh ls \-l /celestefs-example/ X-Celeste/Directory 2 2008-08-25 16:50:53 . X-Celeste/Directory 2 2008-08-25 16:50:53 .. $ celestefs \--id meMyselfAndI \--password plugh pread /celestefs-example/ 0 \-1 X-Celeste/Directory 2 1219708253943 . X-Celeste/Directory 2 1219708253943 .. $ celestefs \--id meMyselfAndI \--password plugh create /celestefs-example/fubar $ echo 'Hello World' \| \ celestefs \--id meMyselfAndI \--password plugh pwrite /celestefs-example/fubar 0 $ celestefs \--id meMyselfAndI \--password plugh ls \-l /celestefs-example/fubar application/octet-stream 12 2008-08-25 16:51:12 /fubar $ celestefs \--id meMyselfAndI \--password plugh pread /celestefs-example/fubar 0 \-1 Hello World $ celestefs \--id meMyselfAndI \--password plugh mkdir /celestefs-example/foo $ celestefs \--id meMyselfAndI \--password plugh create /celestefs-example/foo/bar $ echo 'Hello World' \| \ celestefs \--id meMyselfAndI \--password plugh pwrite /celestefs-example/foo/bar 0 $ celestefs \--id meMyselfAndI \--password plugh pread /celestefs-example/foo/bar 0 \-1 Hello World $ celestefs \--id meMyselfAndI \--password plugh rm /celestefs-example/foo/bar $ celestefs \--id meMyselfAndI \--password plugh pread /celestefs-example/foo/bar 0 \-1 File not found
Sign up or Log in to add a comment or watch this page.