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 "change-format-version [-V, --format-version VERS] [-F|--offline META-DEVICE DATA-DEVICE]"
.sp
Change the format version of an existing file system.  The maxmimum
supported version is used by default.   A specific version in the range
can be specified.   The range of supported versions in shown in the
output of --help.
.RS 1.0i
.PD 0
.TP
.sp
.B "-F, --offline META-DEVICE DATA-DEVICE"
Change the format version by writing directly to the metadata and data
devices.   Like mkfs, this writes directly to the devices without
protection and must only be used on completely unmounted devices.   The
command will fail if it sees evidence of active quorum use of the device
or of previously connected clients which haven't been reclaimed.  The
only way to avoid these checks is to fully mount and cleanly unmount the
file system. 
.sp
This is not an atomic operation because it writes to blocks on two
devices.   Write failure can result in the versions becoming out of sync
which will prevent the system from mouting.  To recover the error must
be resolved so the command can be repeated and successfully write to
the super blocks on both devices.
.RE
.PD

.TP
.BI "change-quorum-config {-Q|--quorum-slot} NR,ADDR,PORT [-F|--offline META-DEVICE DATA-DEVICE]"
.sp
Change the quorum configuration for an existing file system.  The new
configuration completely replaces the old configuration.   Any slots
from the old configuration that should be retained must be described
with arguments in the new configuration.
.sp
Currently the configuration may only be changed offline.
.sp
.RS 1.0i
.PD 0
.TP
.B "-Q, --quorum-slot NR,ADDR,PORT"
The quorum configuration is built by specifying configured slots with
multiple arguments as described in the
.B mkfs
command.
.TP
.B "-F, --offline META-DEVICE"
Perform the change offline by updating the superblock in the metadata
device.   The command will read the super block and refuse to make the
change if it sees any evidence that the metadata device is currently in
use.   The file system must be successfully unmounted after possibly
recovering any previously unresolved mounts for the change to be
successful.   After the change succeeds the newly configured slots can
be used by mounts.
.sp
The offline change directly reads from and writes to the device and does
not protect against concurrent use of the device.   It must be carefully
run when the file system will not be mounted.
.RE
.PD

.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-slot} NR,ADDR,PORT [-m|--max-meta-size SIZE] [-d|--max-data-size SIZE] [-z|--data-alloc-zone-blocks BLOCKS] [-f|--force] [-A|--allow-small-size] [-V|--format-version VERS]"
.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.
The internal structures and nature of metadata and data transactions
lead to minimum viable device sizes.  
.B mkfs
will check both devices and fail with an error if either are under the
minimum size.   If
.B --allow-small-size
is given then sizes under the minimum size will be
allowed after printing an informational warning.
.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-slot NR,ADDR,PORT"
Each \-Q option configures a quorum slot.  The NR specifies the number
of the slot to configure which must be between 0 and 14.  Each slot
number must only be used once, but they can be used in any order and
they need not be consecutive.  This is to allow natural relationships
between slot numbers and nodes which may have arbitrary numbering
schemes.  ADDR and PORT are the numerical IPv4 address and port which
will be used as the UDP endpoint for leader elections and as the TCP
listening address for server connections.  The number of configured
slots determines the size of the quorum of member mounts which must be
present to start the server for the filesystem to operate.  A simple
majority is typically required, while one mount is sufficient if only
one or two slots are configured.  Until the majority quorum are present,
all mounts will hang waiting for a server to connect to.
.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 "-A, --allow-small-size"
Allows use of specified device sizes less than the minimum.  This can
result in bad behaviour and is only intended for testing.
.TP
.B "-z, --data-alloc-zone-blocks BLOCKS"
Set the data_alloc_zone_blocks volume option, as described in
.BR scoutfs (5).
.TP
.B "-f, --force"
Ignore presence of existing data on the data and metadata devices.
.TP
.B "-V, --format-verson"
Specify the format version to use in the newly created file system.
The range of supported versions is visible in the output of 
+.BR scoutfs (8)
+.I --help
.
.RE
.PD

.TP
.BI "resize-devices [-p|--path PATH] [-m|--meta-size SIZE] [-d|--data-size SIZE]"
.sp
Resize the metadata or data devices of a mounted ScoutFS filesystem.
.sp
ScoutFS metadata has free extent records and fields in the super block
that reflect the size of the devices in use.  This command sends a
request to the server to change the size of the device that can be used
by updating free extents and setting the super block fields.
.sp
The specified sizes are in bytes and are translated into block counts.
If the specified sizes are not a multiple of the metadata or data block
sizes then a message is output and the resized size is truncated down to
the next whole block.  Specifying either a size of 0 or the current
device size makes no change.    The current size of the devices can be
seen, in units of their respective block sizes, in the total_meta_blocks
and total_data_blocks fields returned by the scoutfs statfs command (via
the statfs_more ioctl).
.sp
Shrinking is not supported.  Specifying a smaller size for either device
will return an error and neither device will be resized.
.sp
Specifying a larger size will expand the initial size of the device that
will be used.  Free space records are added for the expanded region and
can be used once the resizing transaction is complete.
.sp
The resizing action is performed in a transaction on the server.  This
command will hang until a server is elected and running and can service
the reqeust.  The server serializes any concurrent requests to resize.
.sp
The new sizes must fit within the current sizes of the mounted devices.
Presumably this command is being performed as part of a larger
coordinated resize of the underlying devices.  The device must be
expanded before ScoutFS can use the larger device and ScoutFS must stop
using a region to shrink before it could be removed from the device
(which is not currently supported).
.sp
The resize will be committed by the server before the response is sent
to the client.  The system can be using the new device size before the
result is communicated through the client and this command completes.
The client could crash and the server could still have performed the
resize.
.RS 1.0i
.PD 0
.TP
.sp
.B "-p, --path PATH"
A path in the mounted ScoutFS filesystem which will have its devices
resized.
.TP
.B "-m, --meta-size SIZE"
.B "-d, --data-size SIZE"
The new size of the metadata or data device to use, in bytes.  Size is given as
an integer followed by a units digit: "K", "M", "G", "T", "P", to denote
kibibytes, mebibytes, etc.
.RE
.PD

.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

.TP
.BI "get-allocated-inos [-i|--ino INO] [-s|--single] [-p|--path PATH]"
.sp
This debugging command prints allocated inode numbers.  It only prints
inodes
found in the group that contains the starting inode.  The printed inode
numbers aren't necessarily reachable.  They could be anywhere in the
process from being unlinked to finally deleted when their items
were found.
.RS 1.0i
.PD 0
.TP
.sp
.B "-i, --ino INO"
The first 64bit inode number which could be printed.
.TP
.B "-s, --single"
Only print the single starting inode when it is allocated, all other allocated
inode numbers will be ignored.
.TP
.B "-p, --path PATH"
A path within a ScoutFS filesystem.
.RE
.PD

.TP

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

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