scoutfs/utils/man/scoutfs.8

.TH scoutfs 8
.SH NAME
scoutfs \- scoutfs management utility
.SH DESCRIPTION
The
.B scoutfs
utility provides commands to create and manage a ScoutFS filesystem.
.SH COMMANDS

Note: Commands taking the
.B --path
option will, when the option is omitted, fall back to using the value of the
.I SCOUTFS_MOUNT_PATH
environment variable. If that variable is also absent the current working
directory will be used.

.TP
.BI "df [-h|--human-readable] [-p|--path PATH]"
.sp
Display available and used space on the ScoutFS data and metadata devices.
.RS 1.0i
.PD 0
.TP
.sp
.B "-h, --human-readable"
Output sizes in human-readable size units (e.g. 500G, 1.2P) rather than number
of ScoutFS allocation blocks.
.TP
.B "-p, --path PATH"
A path within a ScoutFS filesystem.
.RE
.PD

.TP
.BI "mkfs META-DEVICE DATA-DEVICE {-Q|--quorum-count} NUM [-m|--max-meta-size SIZE] [-d|--max-data-size SIZE] [-f|--force]"
.sp
Initialize a new ScoutFS filesystem on the target devices. Since ScoutFS uses
separate block devices for its metadata and data storage, two are required.
.sp
If
.B --force
option is not given, mkfs will check for existing filesystem signatures. It is
recommended to use
.B wipefs(8)
to remove non-ScoutFS filesystem signatures before proceeding, and
.B --force
to overwrite a previous ScoutFS filesystem.
.RS 1.0i
.PD 0
.TP
.sp
.B META-DEVICE
The path to the block device to be used for ScoutFS metadata.  If possible, use
a faster block device for the metadata device.
.TP
.B DATA-DEVICE
The path to the block device to be used for ScoutFS file data.  If possible, use
a larger block device for the data device.
.TP
.B "-Q, --quorum-count NUM"
The number of mounts needed to reach quorum and elect one
to be the server.  Mounts of the filesystem will hang until a quorum of
mounts are operational.
.sp
Mounts with the
.B server_addr
mount option participate in quorum.  The safest quorum number is the
smallest majority of an odd number of participating mounts.  For
example,
two out of three total mounts.  This ensures that there can only be one
set of mounts that can establish quorum.
.TP
.B "-m, --max-meta-size SIZE"
Limit the space used by ScoutFS on the metadata device to the
given size, rather than using the entire block device. Size is given as
an integer followed by a units digit: "K", "M", "G", "T", "P", to denote
kibibytes, mebibytes, etc.
.TP
.B "-d, --max-data-size SIZE"
Same as previous, but for limiting the size of the data device.
.TP
.B "-f, --force"
Ignore presence of existing data on the data and metadata devices.
.RE
.PD

.TP
.BI "stat FILE [-s|--single-field FIELD-NAME]"
.sp
Display ScoutFS-specific metadata fields for the given file.
.RS 1.0i
.PD 0
.TP
.sp
.B "FILE"
Path to the file.
.TP
.B "-s, --single-field FIELD-NAME"
Only output a single field's value instead of the default: all the stats with
one stat per line.
.sp
.TP
.RE
.PD
The fields are:
.RS 1.0i
.PD 0
.TP
.B "meta_seq"
The metadata change sequence.  This changes each time the inode's metadata
is changed.
.TP
.B "data_seq"
The data change sequence.  This changes each time the inode's data
is changed.
.TP
.B "data_version"
The data version changes every time the contents of the file changes,
or the file grows or shrinks.
.TP
.B "online_blocks"
The number of 4Kb data blocks that contain data and can be read.
.TP
.B "offline_blocks"
The number of 4Kb data blocks that are offline and would need to be
staged to be read.
.RE
.PD

.TP
.BI "statfs [-s|--single-field FIELD-NAME] [-p|--path PATH]"
.sp
Display ScoutFS-specific filesystem-wide metadata fields.
.RS 1.0i
.PD 0
.TP
.sp
.B "-s, --single-field FIELD-NAME"
Only ontput a single stat instead of all the stats with one stat per
line.  The possible stat names are those given in the output.
.TP
.B "-p, --path PATH"
A path within a ScoutFS filesystem.
.sp
.TP
.RE
.PD
The fields are:
.RS 1.0i
.PD 0
.TP
.B "fsid"
The unique 64bit filesystem identifier for this filesystem.
.TP
.B "rid"
The unique 64bit random identifier for this mount of the filesystem.
This is generated for every new mount of the file system.
.TP
.B "committed_seq"
All seqs up to and including this seq have been
committed.  Can be compared with meta_seq and data_seq from inodes in
.B stat
to discover if changes to a file have been committed to disk.
.TP
.B "total_meta_blocks"
The total number of 64K metadata blocks in the filesystem.
.TP
.B "total_data_blocks"
The total number of 4K data blocks in the filesystem.
.RE
.PD

.TP
.BI "counters [-t|--table] SYSFS-DIR"
.sp
Display the counters and their values for a mounted ScoutFS filesystem.
.RS 1.0i
.PD 0
.sp
.TP
.B SYSFS-DIR
The mount's sysfs directory in which to find the
.B counters/
directory when then contains files for each counter.
The sysfs directory is
of the form
.I /sys/fs/scoutfs/f.<fsid>.r.<rid>/
\&.
.TP
.B "-t, --table"
Format the counters into a columnar table that fills the width of the display
instead of printing one counter per line.
.RE
.PD

.TP
.BI "search-xattrs XATTR-NAME [-p|--path PATH]"
.sp
Display the inode numbers of inodes in the filesystem which may have
an extended attribute with the given name.
.sp
The results may contain false positives.  The returned inode numbers
should be checked to verify that the extended attribute is in fact
present on the inode.
.RS 1.0i
.PD 0
.TP
.sp
.B XATTR-NAME
The full name of the extended attribute to search for as
described in the
.BR xattr (7)
manual page.
.TP
.B "-p|--path PATH"
A path within a ScoutFS filesystem.
.RE
.PD

.TP
.BI "list-hidden-xattrs FILE"
.sp
Display extended attributes starting with the
.BR scoutfs.
prefix and containing the
.BR hide.
tag
which makes them invisible to
.BR listxattr (2) .
The names of each attribute are output, one per line.  Their order
is not specified.
.RS 1.0i
.PD 0
.TP
.sp
.B "FILE"
The path to a file within a ScoutFS filesystem.  File permissions must allow
reading.
.RE
.PD

.TP
.BI "walk-inodes {meta_seq|data_seq} FIRST-INODE LAST-INODE [-p|--path PATH]"
.sp
Walk an inode index in the file system and output the inode numbers
that are found between the first and last positions in the index.
.RS 1.0i
.PD 0
.sp
.TP
.BR meta_seq , data_seq
Which index to walk.
.TP
.B "FIRST-INODE"
An integer index value giving starting position of the index walk.
.I 0
is the first possible position.
.TP
.B "LAST-INODE"
An integer index value giving the last position to include in the index walk.
.I \-1
can be given to indicate the last possible position.
.TP
.B "-p|--path PATH"
A path within a ScoutFS filesystem.
.RE
.PD

.TP
.BI "ino-path INODE-NUM [-p|--path PATH]"
.sp
Display all paths that reference an inode number.
.sp
Ongoing filesystem changes, such as renaming a common parent of multiple paths,
can cause displayed paths to be inconsistent.
.RS 1.0i
.PD 0
.sp
.TP
.B "INODE-NUM"
The inode number of the target inode.
.TP
.B "-p|--path PATH"
A path within a ScoutFS filesystem.
.RE
.PD

.TP
.BI "data-waiting {-I|--inode} INODE-NUM {-B|--block} BLOCK-NUM [-p|--path PATH]"
.sp
Display all the files and blocks for which there is a task blocked waiting on
offline data.
.sp
The results are sorted by the file's inode number and the
logical block offset that is being waited on.
.sp
Each line of output describes a block in a file that has a task waiting
and is formatted as:
.I "ino <nr> iblock <nr> ops [str]"
\&. The ops string indicates blocked operations seperated by commas and can
include
.B read
for a read operation,
.B write
for a write operation, and
.B change_size
for a truncate or extending write.
.RS 1.0i
.PD 0
.sp
.TP
.B "-I, --inode INODE-NUM"
Start iterating over waiting tasks from the given inode number.
Value of 0 will show all waiting tasks.
.TP
.B "-B, --block BLOCK-NUM"
Start iterating over waiting tasks from the given logical block number
in the starting inode.  Value of 0 will show blocks in the first inode
and then continue to show all blocks with tasks waiting in all the
remaining inodes.
.TP
.B "-p, --path PATH"
A path within a ScoutFS filesystem.
.RE
.PD

.TP
.BI "data-wait-err {-I|--inode} INODE-NUM {-V|--version} VER-NUM {-F|--offset} OFF-NUM {-C|--count} COUNT {-O|--op} OP {-E|--err} ERR [-p|--path PATH]"
.sp
Return error from matching waiters.
.RS 1.0i
.PD 0
.sp
.TP
.B "-C, --count COUNT"
Count.
.TP
.B "-E, --err ERR"
Error.
.TP
.B "-F, --offset OFF-NUM"
Offset. May be expressed in bytes, or with KMGTP (Kibi, Mibi, etc.) size
suffixes.
.TP
.B "-I, --inode INODE-NUM"
Inode number.
.TP
.B "-O, --op OP"
Operation. One of: "read", "write", "change_size".
.TP
.B "-p, --path PATH"
A path within a ScoutFS filesystem.
.RE
.PD

.TP
.BI "stage ARCHIVE-FILE FILE {-V|--version} VERSION [-o, --offset OFF-NUM] [-l, --length LENGTH]"
.sp
.B Stage
(i.e. return to online) the previously-offline contents of a file by copying a
region from another file, the archive, and without updating regular inode
metadata.  Any operations that are blocked by the existence of an offline
region will proceed once the region has been staged.
.RS 1.0i
.PD 0
.TP
.sp
.B "ARCHIVE-FILE"
The source file for the file contents being staged.
.TP
.B "FILE"
The regular file whose contents will be staged.
.TP
.B "-V, --version VERSION"
The data_version of the contents to be staged.  It must match the
current data_version of the file.
.TP
.B "-o, --offset OFF-NUM"
The starting byte offset of the region to write.  May be expressed in bytes, or with
KMGTP (Kibi, Mibi, etc.) size suffixes. Default is 0.
.TP
.B "-l, --length LENGTH"
Length of range (bytes or KMGTP units) of file to stage. Default is the file's
total size.
.RE
.PD

.TP
.BI "release FILE {-V|--version} VERSION [-o, --offset OFF-NUM] [-l, --length LENGTH]"
.sp
.B Release
the given region of the file.  That is, remove the region's backing data and
leave an offline data region. Future attempts to read or write the offline
region will block until the region is restored by a
.B stage
write.  This is used by userspace archive managers to free data space in the
ScoutFS filesystem once the file data has been archived.
.sp
Note: This only works on regular files with write permission.  Releasing regions
that are already offline or sparse, including regions extending past the end of
the file, will silently succeed.
.RS 1.0i
.PD 0
.TP
.sp
.B "path"
The path to the regular file whose region will be released.
.TP
.B "-V, --version VERSION"
The data_version of the contents to be released.  It must match the current
data_version of the file. This ensures that a release operation is truncating
the same version of the data that was archived. (Use the
.BI "stat"
subcommand to obtain data version for a file.)
.TP
.B "-o, --offset OFF-NUM"
The starting byte offset of the region to write.  May be expressed in bytes, or with
KMGTP (Kibi, Mibi, etc.) size suffixes. Default is 0.
.TP
.B "-l, --length LENGTH"
Length of range (bytes or KMGTP units) of file to stage. Default is the file's
total size.
.RE
.PD

.TP
.BI "setattr FILE [-d, --data-version=VERSION [-s, --size=SIZE [-o, --offline]]] [-t, --ctime=TIMESPEC]"
.sp
Set ScoutFS-specific attributes on a newly created zero-length file.
.RS 1.0i
.PD 0
.sp
.TP
.B "-V, --data-version=VERSION"
Set data version.
.TP
.B "-o, --offline"
Set file contents as offline, not sparse. Requires
.I --size
option also be present.
.TP
.B "-s, --size=SIZE"
Set file size. May be expressed in bytes, or with
KMGTP (Kibi, Mibi, etc.) size suffixes. Requires
.I --data-version
option also be present.
.TP
.B "-t, --ctime=TIMESPEC"
Set creation time using
.I "<seconds-since-epoch>.<nanoseconds>"
format.
.RE
.PD

.TP
.BI "print META-DEVICE"
.sp
Prints out all of the metadata in the file system.  This makes no effort
to ensure that the structures are consistent as they're traversed and
can present structures that seem corrupt as they change as they're
output.
.RS 1.0i
.PD 0
.TP
.sp
.B "META-DEVICE"
The path to the metadata device for the filesystem whose metadata will be
printed.  Since this command reads via the host's buffer cache, it may not
reflect the current blocks in the filesystem possibly written to the shared
block devices from another host, unless
.B blockdev \--flushbufs
command is used first.
.RE
.PD

.SH SEE ALSO
.BR scoutfs (5),
.BR xattr (7),
.BR blockdev (8),
.BR wipefs (8)

.SH AUTHORS
Zach Brown <zab@versity.com>