Skip to content

Latest commit

 

History

History
146 lines (117 loc) · 5.78 KB

flux-kvs.adoc

File metadata and controls

146 lines (117 loc) · 5.78 KB
Raw

FLUX-KVS(1) Manual Page

NAME

flux-kvs - Flux key-value store utility

SYNOPSIS

flux kvs COMMAND [OPTIONS]

DESCRIPTION

The Flux key-value store (KVS) is a simple, distributed data storage service used a building block by other Flux components. flux-kvs(1) is a command line utility that operates on the KVS. It is a very thin layer on top of a C API.

The Flux KVS stores JSON values under string keys. The keys are hierarchical, using "." as a path separator, analogous to "/" separated UNIX file paths. A single "." represents the root directory of the KVS.

The KVS is distributed among the ranks of a comms session. Rank 0 is the master, and other ranks are caching slaves. All writes are flushed to the master during a commit operation. Data is stored in a hash tree such that every commit results in a new root hash. Each new root hash is multicast across the session. When slaves update their root hash, they atomically update their view to match the master. There may be a delay after a commit while old data is served on a slave that has not yet updated its root hash, thus the Flux KVS consistency model is "eventually consistent". Slaves cache data temporally and fault in new data through their parent in the overlay network.

flux-kvs(1) runs a KVS COMMAND. The possible commands and their arguments are described below.

COMMANDS

get [-j|-r|-t] [-a treeobj] key [key…​]

Retrieve the value stored under key. If nothing has been stored under key, display an error message. If no options, value is interpreted as a NULL-terminated string. If -j, it is interpreted as encoded JSON. If -r, it is interpreted as raw data and is output without formatting. If -t, the RFC 11 object is displayed. -a treeobj causes the lookup to be relative to an RFC 11 snapshot reference.

put [-j|-r|-t] [-n] key=value [key=value…​]

Store value under key and commit it. If it already has a value, overwrite it. If no options, value is stored as a NULL-terminated string. If -j, it is first encoded as JSON, then stored as a NULL-terminated string. If -r, it is stored as raw data with no termination. For raw mode only, a value of "-" indicates that the value should be read from standard input. If -t, value is stored as a RFC 11 object. -n prevents the commit from being merged with with other contemporaneous commits.

ls [-R] [-d] [-F] [-w COLS] [-1] [key …​]

Display directory referred to by key, or "." (root) if unspecified. Options are roughly equivalent to a subset of ls(1) options. -R lists directory recursively. -d displays directory not its contents. -F classifies files with one character suffix (. is directory, @ is symlink). -w COLS sets the terminal width in characters. -1 causes output to be displayed in one column.

dir [-R] [-d] [-w COLS] [-a treeobj] [key]

Display all keys and their values under the directory key. If key does not exist or is not a directory, display an error message. If key is not provided, "." (root of the namespace) is assumed. If -R is specified, recursively display keys under subdirectories. If -d is specified, do not output key values. Output is truncated to fit the terminal width. -w COLS sets the terminal width (0=unlimited). -a treeobj causes the lookup to be relative to an RFC 11 snapshot reference.

unlink [-R] [-f] key [key…​]

Remove key from the KVS and commit the change. If key represents a directory, specify -R to remove all keys underneath it. If -f is specified, ignore nonexistent files.

link target linkname

Create a new name for target, similar to a symbolic link, and commit the change. target does not have to exist. If linkname exists, it is overwritten.

readlink [-a treeobj] key [key…​]

Retrieve the key a link refers to rather than its value, as would be returned by get. -a treeobj causes the lookup to be relative to an RFC 11 snapshot reference.

mkdir key [key…​]

Create an empty directory and commit the change. If key exists, it is overwritten.

copy source destination

Copy source key to destination key. If a directory is copied, a new reference is created; it is unnecessary for copy to recurse into source.

move source destination

Like copy, but source is unlinked after the copy.

dropcache [--all]

Tell the local KVS to drop any cache it is holding. If --all is specified, send an event across the comms session instructing all KVS instances to drop their caches.

watch [-R] [-d] [-o] [-c count] key

Watch key and output changes. If key is a single value, each change will be displayed on a line of output. If key is a directory, changes within the directory and changes within it will be displayed. If -R is specified, recursively display keys under subdirectories. If -d is specified, do not output key values. If count is specified, display at most count changes. Otherwise, this command runs forever. If -o is specified, output the current value before outputting changes.

version

Display the current KVS version, an integer value. The version starts at zero and is incremented on each KVS commit. Note that some commits may be aggregated for performance and the version will be incremented once for the aggregation, so it cannot be used as a direct count of commit requests.

wait version

Block until the KVS version reaches version or greater. A simple form of synchronization between peers is: node A puts a value, commits it, reads version, sends version to node B. Node B waits for version, gets value.

AUTHOR

This page is maintained by the Flux community.

COPYRIGHT