From 794277053f39d98f704ebe0588e6d7a1c1b1aa22 Mon Sep 17 00:00:00 2001 From: Zach Brown Date: Fri, 17 Jan 2020 15:46:33 -0800 Subject: [PATCH] scoutfs-utils: add a few more man pages Add an overview man page for scoutfs and add a manpage for the userspace utility and its commands. Signed-off-by: Zach Brown --- utils/man/scoutfs.5 | 48 ++++ utils/man/scoutfs.8 | 435 ++++++++++++++++++++++++++++++++++++ utils/scoutfs-utils.spec.in | 8 +- 3 files changed, 488 insertions(+), 3 deletions(-) create mode 100644 utils/man/scoutfs.5 create mode 100644 utils/man/scoutfs.8 diff --git a/utils/man/scoutfs.5 b/utils/man/scoutfs.5 new file mode 100644 index 00000000..9d45a3da --- /dev/null +++ b/utils/man/scoutfs.5 @@ -0,0 +1,48 @@ +.TH scoutfs 5 +.SH NAME +scoutfs \- overview and mount options for the scoutfs filesystem +.SH DESCRIPTION +A scoutfs filesystem is stored on a block device. Multiple mounts of +the filesystem are supported between hosts that share access to the +block device. A new filesystem is created with the +.B mkfs +command in the +.BR scoutfs (8) +utility. +.SH MOUNT OPTIONS +The following mount options are supported by scoutfs in addition to the +general mount options described in the +.BR mount (8) +manual page. +.TP +.B server_addr= +The server_addr option indicates that this mount will participate in +quorum election to try and run a server for all the mounts of its +filesystem. The option specifies the local TCP IPv4 address that the +mount's elected server will listen on for connections from all other +mounts of the filesystem. +.sp +The IPv4 address must be specified as a dotted quad, name resolution is +not supported. A specific port may be provided after a seperating +colon. If no port is specified then a random port will be chosen. The +address will be used for the lifetime of the mount and can not be +changed. The mount must be unmounted to specify a different address. +.sp +If server_addr is not specified then the mount will read the filesystem +until it sees the address of an elected server to connect to. +.SH FURTHER READING +A +.B scoutfs +filesystem can detect corruption at runtime. A catalog of kernel log +messages that indicate corruption can be found in +.BR scoutfs-corruption (8) +\&. + +.SH SEE ALSO +.BR scoutfs (8), +.BR scoutfs-corruption (7). + +.SH AUTHORS +Zach Brown + + diff --git a/utils/man/scoutfs.8 b/utils/man/scoutfs.8 new file mode 100644 index 00000000..4664f14a --- /dev/null +++ b/utils/man/scoutfs.8 @@ -0,0 +1,435 @@ +.TH scoutfs 8 +.SH NAME +scoutfs \- scoutfs management utility +.SH DESCRIPTION +The +.b +scoutfs +utility provides commands to manage a scoutfs filesystem. +.SH COMMANDS +.TP +.BI "counters [\-t\] " +.sp +Displays the counters and their values for a mounted scoutfs filesystem. +Each counter and its value are printed on a line to stdout with +sufficient spaces seperating the name and value to align the values +after +.RS 1.0i +.PD 0 +.TP +.sp +.B "\-t" +Format the counters into a table that fills the display instead of +printing one counter per line. The names and values are padded to +create columns that fill the current width of the terminal. +.TP +.B "sysfs topdir" +Specify the mount's sysfs directory in which to find the +.B counters/ +directory when then contains files for each counter. +The sysfs directory is typically +of the form +.I /sys/fs/scoutfs/f..r./ +\&. +.RE +.PD + +.TP +.BI "data-waiting " +.sp +Displays 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 specifies a block in a file that has a task waiting +and is formatted as: +.I "ino iblock 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 "ino" +Start iterating over waiting tasks from the given inode number. +Specifying 0 will show all waiting tasks. +.TP +.B "iblock" +Start iterating over waiting tasks from the given logical block number +in the starting inode. Specifying 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 "path" +A path to any inode in the target filesystem, typically the root +directory. +.RE +.PD + +.TP +.BI "find-xattrs <\-n\ name> <\-f path>" +.sp +Displays 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 "-n name" +Specifies the full name of the extended attribute to search for as +described in the +.BR xattr (7) +manual page. +.TP +.B "-f path" +Specifies the path to any inode in the filesystem to search. +.RE +.PD + +.TP +.BI "ino-path " +.sp +Displays all the paths to links to the given inode number. +.sp +All the relative paths from the root directory to each link of the +target inode are output, one result per line. Each output path is +guaranteed to have been a valid path to a link at some point in the +past. An individual path won't be corrupted by a rename that occurs +during the search. The set of paths can be modified while the search is +running. A rename of a parent directory of all the paths, for example, +can result in output where the parent directory name component changes +in the middle of outputting all the paths. +.RS 1.0i +.PD 0 +.sp +.TP +.B "ino" +The inode number of the target inode to resolve. +.TP +.B "path" +A path to any inode in the target filesystem, typically the root +directory. +.RE +.PD + +.TP +.BI "listxattr-hidden <\-f path>" +.sp +Displays all the extended attributes starting with the +.BR scoutfs. +prefix and which contain the +.BR hide. +tag +which makes them invisible to +.BR listxattr (2) +\&. +The names of each attribute are output, one name per line. Their order +is determined by internal indexing implementation details and should not +be relied on. +.RS 1.0i +.PD 0 +.TP +.sp +.B "-f path" +The path to the file whose extended attributes will be listed. The +user must have read permission to the inode. +.RE +.PD + +.TP +.BI "mkfs <\-Q nr> " +.sp +Initialize a new empty filesystem in the target device by writing empty +structures and a new superblock. +.sp +This +.B unconditionally destroys +the contents of the device, regardless of what it contains or who may be +using it. It simply writes new data structures into known offsets. +.B Be very careful that the device does not contain data and is not actively in use. +.RS 1.0i +.PD 0 +.TP +.sp +.B "-Q nr" +Specify the number of mounts needed to reach quorum and elect a mount +to start the server. Mounts of the device will hang until this many +mounts are operational and can elect a server amongst themselves. +.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. +.sp +Degenerate quorums are possible, for example by specifying half of an +even number of mounts or less than half of the mount count, down to even +just one mount establishing quorum. These minority quorums carry the +risk of multiple quorums being established concurrently. Each quorum's +elected servers race to fence each other and can have the unlikely +outcome of continually racing to fence each other resulting in a +persistent loss of service. +.TP +.B "path" +The path to the device whose contents will be unconditionally destroyed. +.RE +.PD + +.TP +.BI "print " +.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 "path" +The path to the device that contains the filesystem whose metadata will +be printed. The command reads from the buffer cache of the device which +may not reflect the current blocks in the filesystem that may have been +written through another host or device. The local device's cache can be +manually flused before printing, perhaps with the +.B \--flushbufs +command in the +.BR blockdev (8) +command. +.RE +.PD + +.TP +.BI "release <4KB block offset> <4KB block count>" +.sp +.B Release +the given logical block region of the file. That is, truncate away +any data blocks but leave behind offline data regions and do not change +the main inode metadata. Future attempts to read or write the block +region +will block until the region is restored by a +.B stage +write. This is used by userspace archive managers to store file data +in a remote archive tier. +.sp +This only works on regular files and with write permission. Releasing +regions that are already offline or are sparse, including past the end +of the file, silently succeed. +.RS 1.0i +.PD 0 +.TP +.sp +.B "path" +The path to the regular file whose region will be released. +.TP +.B "version" +The current data version of the contents of the file. This ensures +that a release operation is truncating the version of the data that it +expects. It can't throw away data that was newly written while it was +performing its release operation. An inode's data_version is read +by the SCOUTFS_IOC_STATFS_MORE +ioctl. +.TP +.B "4KB block offset" +The 64bit logical block offset of the start of the region in units of 4KB. +.TP +.B "4KB block count" +The 64bit length of the region to release in units of 4KB blocks. +.RE +.PD + +.TP +.BI "setattr <\-c ctime> <\-d data_version> -o <\-s i_size> <\-f path> +.sp +Set scoutfs specific metadata on a newly created inode without updating +other inode metadata. +.RS 1.0i +.PD 0 +.TP +.sp +.B "-c ctime" +Specify the inode's creation GMT timespec with 64bit seconds and 32bit +nanoseconds formatted as +.B sec.nsec +\&. +.TP +.B "-d data_version" +Specify the inode's data version. This can only be set on regular files whose +current data_version is 0. +.TP +.B "-o" +Create an offline region for all of the file's data up to the specified +file size. This can only be set on regular files whose data_version is +0 and i_size must also be specified. +.TP +.B "-s i_size" +Set the inode's i_size. This can only be set on regular files whose +data_version is 0. +.TP +.B "-f path" +The file whose metadata will be set. +.RE +.PD + +.TP +.BI "stage " +.sp +.B Stage +the contents of the file by reading a region of another archive file and writing it +into the file region without updating regular inode metadata. Any tasks +that are blocked by the offline region will proceed once it has been +staged. +.RS 1.0i +.PD 0 +.TP +.sp +.B "file" +The regular file whose contents will be staged. +.TP +.B "vers" +The data_version of the contents to be staged. It must match the +current data_version of the file. +.TP +.B "offset" +The starting byte offset of the region to write. This must be aligned +to 4KB blocks. +.TP +.B "count" +The length of the region to write in bytes. A length of 0 is a noop +and will immediately return success. The length must be a multiple +of 4KB blocks unless it is writing the final partial block in which +case it must end at i_size. +.TP +.B "archive file" +A file whose contents will be read and written as the staged region. +The start of the archive file will be used as the start of the region. +.RE +.PD + +.TP +.BI "stat [-s single] " +.sp +Display scoutfs metadata fields for the given inode. +.RS 1.0i +.PD 0 +.TP +.sp +.B "-s single" +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 "path" +The path to the file whose inode field will be output. +.sp +.TP +.RE +.PD +The fields are as follows: +.RS 1.0i +.PD 0 +.TP +.B "meta_seq" +The metadata change sequence. This changes each time the inode's metadata +is changed during a mount's transaction. +.TP +.B "data_seq" +The data change sequence. This changes each time the inode's data +is changed during a mount's transaction. +.TP +.B "data_version" +The data version changes every time any contents of the file changes, +including size changes. It can change many times during a syscall in a +transactions. +.TP +.B "online_blocks" +The number of 4Kb data blocks that contain data and can be read. +.TP +.B "online_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] " +.sp +Display scoutfs metadata fields for a scoutfs filesystem. +.RS 1.0i +.PD 0 +.TP +.sp +.B "-s single" +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 "path" +The path to any inode in the filesystem. +.sp +.TP +.RE +.PD +The fields are as follows: +.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. +.RE +.PD + +.TP +.BI "walk-inodes " +.sp +Walks an inode index in the file system and outputs the inode numbers +that are found within the first and last positions in the index. +.RS 1.0i +.PD 0 +.sp +.TP +.B "index" +Specifies the index to walk. The currently supported indices are +.B meta_seq +and +.B data_seq +\&. +.TP +.B "first" +The starting position of the index walk. +.I 0 +is the first possible position in every index. +.TP +.B "last" +The last position to include in the index walk. +.I \-1 +can be given as shorthand for the U64_MAX last possible position in +every index. +.TP +.B "path" +A path to any inode in the filesystem, typically the root directory. +.RE +.PD + +.SH SEE ALSO +.BR scoutfs (5), +.BR xattr (7). + +.SH AUTHORS +Zach Brown diff --git a/utils/scoutfs-utils.spec.in b/utils/scoutfs-utils.spec.in index 81847d9d..35219721 100644 --- a/utils/scoutfs-utils.spec.in +++ b/utils/scoutfs-utils.spec.in @@ -43,18 +43,20 @@ scoutfs - development headers %build make -gzip man/*.7 +gzip man/*.? %install -mkdir -p $RPM_BUILD_ROOT%{_mandir}/man7 +mkdir -p $RPM_BUILD_ROOT%{_mandir}/man{5,7,8} +cp man/*.5.gz $RPM_BUILD_ROOT%{_mandir}/man5/. cp man/*.7.gz $RPM_BUILD_ROOT%{_mandir}/man7/. +cp man/*.8.gz $RPM_BUILD_ROOT%{_mandir}/man8/. install -m 755 -D src/scoutfs $RPM_BUILD_ROOT%{_sbindir}/scoutfs install -m 644 -D src/ioctl.h $RPM_BUILD_ROOT%{_includedir}/scoutfs/ioctl.h install -m 644 -D src/format.h $RPM_BUILD_ROOT%{_includedir}/scoutfs/format.h %files %defattr(644,root,root,755) -%{_mandir}/man7/scoutfs-corruption.7.gz +%{_mandir}/man*/scoutfs*.gz %defattr(755,root,root,755) %{_sbindir}/scoutfs