.\" Automatically generated by Pandoc 3.1.3
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "growlight-readline" "8" "v1.2.38" "" ""
.hy
.SH NAME
.PP
growlight-readline - Block device and filesystem editor
.SH SYNOPSIS
.PP
\f[B]growlight-readline\f[R] [\f[B]-h|--help\f[R]]
[\f[B]-i|--import\f[R]] [\f[B]-v|--verbose\f[R]]
[\f[B]-V|--version\f[R]] [\f[B]-t path|--target=path\f[R]]
.SH DESCRIPTION
.PP
\f[B]growlight-readline\f[R] detects and describes disk pools, block
devices, partition tables, and partitions.
It can partition devices, manipulate ZFS, MD, DM, LVM and hardware RAID
virtual devices, and prepare an fstab file for using the devices to boot
or in a chroot, and is fully aware of variable sector sizes, GPT, and
UEFI.
\f[B]growlight-readline\f[R] facilitates use of UUID/WWN- and HBA-based
identification of block devices.
.PP
This page describes the line-based implementation.
Consult \f[B]growlight(8)\f[R] for a fullscreen
\f[B]notcurses(3)\f[R]-based variant.
.SH OPTIONS
.PP
\f[B]-h|--help\f[R]: Print a brief usage summary, and exit.
.PP
\f[B]-i|--import\f[R]: Attempt to assemble aggregates (zpools, MD
devices, etc) based on block device scans at startup.
.PP
\f[B]-v|--verbose\f[R]: Be more verbose.
.PP
\f[B]-V|--version\f[R]: Print version information and exit.
.PP
\f[B]--notroot\f[R]: Force \f[B]growlight-readline\f[R] to start without
necessary privileges (it will usually refuse to start).
.PP
\f[B]-t path|--target=path\f[R]: Run in system installation mode, using
\f[B]path\f[R] as the temporary mountpoint for the target\[aq]s root
filesystem.
\[dq]map\[dq] commands will populate the hierarchy rooted at this
mountpoint.
System installation mode can also be entered at run time with the
\[dq]target\[dq] command.
The \[dq]map\[dq] command will not result in active mounts unless
\f[B]growlight-readline\f[R] is operating in system installation mode
(they will merely be used to construct target fstab output).
Once system installation mode is entered, \f[B]growlight-readline\f[R]
will return 0 only as a result of a successful invocation of the
\[dq]target finalize\[dq] command.
\f[B]path\f[R] must exist at the time of its specification.
.SH USAGE
.PP
\f[B]growlight-readline\f[R] implements an interactive command line
driven via GNU Readline.
Commands are entered; a newline causes input to be interpreted, and
output resulting from this interpretation is displayed to the user.
Unlike programs such as \f[B]fdisk(8)\f[R] and \f[B]gdisk(8)\f[R],
\f[B]growlight-readline\f[R] acts on commands immediately: it neither
requires nor provides an explicit commit step (though several commands
do require confirmation).
.PP
An argument specified as \f[B]blockdev\f[R] can be either a real block
device, a virtual block device, or a partition.
An argument specified as \f[B]partition\f[R] must be a partition within
some kernel-recognized partition table.
An argument specified as \f[B]fs\f[R] must be a kernel-recognizable
filesystem.
An argument specified as \f[B]uuid\f[R] must be 36 ASCII characters
forming a valid DCE 1.1 UUID.
Devices can be specified via any appropriate identifier (label, UUID,
etc.).
.IP
.nf
\f[C]
**uefiboot [ -protectmbr ]**
\f[R]
.fi
.PP
Prepare the target for UEFI-based booting.
A target root filesystem map must be defined, and this filesystem must
be mounted at the chroot\[aq]s toplevel.
The filesystem must reside within a GPT partition having the EFI System
Partition (ef00) TUID of C12A7328-F81F-11D2-BA4B-00A0C93EC93B.
This GPT table must not reside on an mdadm, device-mapper, or zfs
device.
Preferably, no other devices in the system are bootable, but this is not
enforced.
.PP
If all these conditions are met, \f[B]GRUB2\f[R] will be installed into
this filesystem, configured to boot a Linux kernel residing at FIXME.
This kernel must be compiled with EFI stub loader support.
The bootloader portion of the device\[aq]s MBR will be overwritten with
zeroes, if possible, to deter attempting to perform a BIOS/MBR boot from
the device.
Alternatively, the \f[B]-protectmbr\f[R] option will install a
\[dq]protective MBR\[dq] consisting of one type 0xEE (EFI GPT) partition
spanning the disk.
This might be preferable if interoperating with GPT-unaware tools.
.IP
.nf
\f[C]
**biosboot**
\f[R]
.fi
.PP
Prepare the target for BIOS-based booting.
A target root filesystem map must be defined, and this filesystem must
be mounted at the chroot\[aq]s toplevel.
The filesystem must reside either within a GPT partition having the BIOS
Boot Partition (ef02) TUID of 21686148-6449-6E6F-744E-656564454649, or
within a MBR partition having type 0x83 (Linux).
The partition table must not reside on an mdadm, device-mapper, or zfs
device.
Preferably, no other devices in the system are bootable, but this is not
enforced.
.PP
If all these conditions are met, \f[B]GRUB2\f[R] will be installed into
this filesystem at /boot/grub, configured to boot a Linux kernel
residing at FIXME.
\f[B]GRUB2\[aq]s\f[R] first stage will be loaded into the bootloader
portion of the device\[aq]s MBR.
The partition containing \f[B]GRUB2\f[R] will be marked as
\f[B]active\f[R] (flag 0x80).
.IP
.nf
\f[C]
**adapter reset adapter**
**adapter rescan adapter**
**adapter detail adapter**
**adapter [ -v ]**
\f[R]
.fi
.PP
Passed no arguments, \f[B]adapter\f[R] lists each HBA (Host Bus Adapter)
device known to the system, including those not actively used.
Passed \[dq]-v\[dq], attached devices of each HBA will also be listed.
For each adapter listed, the first token is an identifier suitable for
use with other \f[B]adapter\f[R] subcommands (it is typically the device
driver\[aq]s module name suffixed by a small integer, but the exact form
is intentionally left implementation-defined).
The \[dq]reset\[dq] subcommand resets the HBA, if it supports this
functionality.
The \[dq]rescan\[dq] subcommand causes the kernel to scan the HBA for
newly connected devices.
Both operations are performed via the Linux kernel\[aq]s sysfs
filesystem.
\[dq]detail\[dq] will display detailed information about the adapter.
.IP
.nf
\f[C]
**blockdev rescan blockdev**
**blockdev badblocks blockdev [ rw ]**
**blockdev wipebiosboot blockdev**
**blockdev ataerase blockdev**
**blockdev rmtable blockdev**
**blockdev mktable [ blockdev tabletype ]**
**blockdev detail blockdev**
**blockdev [ -v ]**
\f[R]
.fi
.PP
Passed no arguments, \f[B]blockdev\f[R] concisely lists all block
devices recognized by the system.
Passed \[dq]-v\[dq], partitions and filesystems present on a given block
device will also be listed.
The \[dq]rescan\[dq] command causes the kernel to reanalyze the
device\[aq]s geometry and partition tables.
Any changes will be propagated to \f[B]growlight-readline\f[R].
\[dq]badblocks\[dq] runs a non-destructive bad block check on the
device.
If provided \[dq]rw\[dq], \[dq]badblocks\[dq] will perform a
destructive, lenghtier, more strenuous read-write check.
\[dq]wipebiosboot\[dq] writes zeroes to the BIOS bootcode section of a
disk (the first 446 bytes of the first sector), hopefully ensuring that
no attempt will be made to perform a BIOS-type boot from the device.
\[dq]ataerase\[dq] uses the ATA Secure Erase functionality of the disk,
if supported, to restore the device to factory settings.
This can lead to noticeably improved performance from used Solid State
Devices (SSDs).
\[dq]rmtable\[dq] will attempt to write zeros over all partition table
structures such that \f[B]libblkid(3)\f[R] does not recognize the disk
as being partitioned.
\[dq]mktable\[dq] will create a partition table of the provided type;
with no arguments, supported partition table types are listed.
\[dq]detail\[dq] will display detailed information about the block
device.
.IP
.nf
\f[C]
**partition del partition**
**partition add blockdev size name type**
**partition setuuid partition uuid**
**partition setname partition name**
**partition settype [ partition type ]**
**partition setflag [ partition on|off flag ]**
**partition [ -v ]**
\f[R]
.fi
.PP
Passed no arguments, \f[B]partition\f[R] concisely lists all detected
partitions.
Passed \[dq]-v\[dq], data present on a given partition will also be
listed.
\[dq]del\[dq] attempts to convert a partition to unallocated space.
\[dq]add\[dq] attempts to carve a partition of the specified size, type
and name from the specified block device\[aq]s free space.
\[dq]size\[dq] may be either a single number, representing a size in
bytes, or a range indicated by one or two numbers separated by a colon.
A range with no first number specifies \[dq]empty space up until this
sector.\[dq] A range with no second number specifies \[dq]empty space
following this sector.\[dq] A range with two numbers indicates \[dq]the
specified range\[dq], and must be wholly contained within free space.
A size of 0 indicates \[dq]all space available.\[dq] When a size is used
instead of a sector range, the space is taken from the largest free
space.
\[dq]setuuid\[dq] attempts to set the partition GUID (\f[B]not\f[R] the
Type UUID) to uuid.
\[dq]setname\[dq] attempts to set the partition label to name.
With no arguments, \[dq]settype\[dq] lists the types supported by
various partitioning schemes.
Otherwise, it attempts to set the specified type on the specified
partition.
With no arguments, \[dq]setflag\[dq] lists the partition flags supported
by this system.
Otherwise, it attempts to set or unset the specified flag on the
specified partition.
.IP
.nf
\f[C]
**fs mkfs [ blockdev fstype label ]**
**fs wipefs blockdev**
**fs fsck blockdev**
**fs setuuid blockdev uuid**
**fs setlabel blockdev label**
**fs loop file mountpoint mnttype options**
**fs mount blockdev mountpoint mnttype options**
**fs umount blockdev**
**fs**
\f[R]
.fi
.PP
Passed no arguments, \f[B]fs\f[R] concisely lists all detected possible
filesystems, irrespective of mount status or viability.
The \[dq]mkfs\[dq] subcommand will create a filesystem on the specified
block device of the specified type, having the specified label (possibly
truncated).
\[dq]mkfs\[dq] with no arguments lists supported filesystem types.
\[dq]wipefs\[dq] will attempt to destroy the specified filesystem\[aq]s
superblocks, to the degree that \f[B]libblkid(3)\f[R] does not detect
them.
\[dq]setuuid\[dq] will set the UUID of the filesystem on blockdev,
assuming that filesystem supports UUIDs.
\[dq]setlabel\[dq] will set the volume label of the filesystem on
blockdev, assuming that filesystem supports volume labels.
\[dq]mount\[dq] will attempt to mount the block device as a mnttype-type
filesystem at mountpoint.
This mount will not be added to either the host or target\[aq]s
/etc/fstab, and will thus not persist across reboots.
\[dq]loop\[dq] will attempt to mount the file as a mnttype-type
filesystem at mountpoint using a loop device.
\[dq]umount\[dq] will attempt to unmount the filesystem underlain by
blockdev.
\[dq]fsck\[dq] will check the filesystem for correctness.
.IP
.nf
\f[C]
**swap on swapdev label [ uuid ]**
**swap off swapdev**
**swap**
\f[R]
.fi
.PP
Passed no arguments, \f[B]swap\f[R] concisely lists each swap device
known to the system, including those not actively used.
The \[dq]on\[dq] subcommand attempts to create and use a swap device on
\f[B]swapdev\f[R].
This command will fail if \f[B]swapdev\f[R] is referenced by any map,
mount, md device, dm device, or zpool, if \f[B]swapdev\f[R] is not
writable, or on any \f[B]mkswap(8)\f[R] or \f[B]swapon(2)\f[R] error.
The \[dq]off\[dq] subcommand attempts to halt an active swap device (it
does not write to the swap device itself, and thus the swap device
remains usable).
It will fail if the device is not an active swap, or on any
\f[B]swapoff(2)\f[R] failure.
.IP
.nf
\f[C]
**mdadm arguments**
**mdadm [ -v ]**
\f[R]
.fi
.PP
Passed no arguments, \f[B]mdadm\f[R] concisely lists each MD (Multiple
Device, aka the Linux kernel\[aq]s mdraid driver) device currently
available to the system.
Passed \[dq]-v\[dq], each MD device\[aq]s components will also be
listed.
Otherwise, arguments will be sanitized and passed to the external
\f[B]mdadm(8)\f[R] tool.
Note that this behavior is subject to change as MD is more fully
integrated.
.IP
.nf
\f[C]
**dmsetup arguments**
\f[R]
.fi
.PP
Arguments are sanitized and passed to the external \f[B]dmsetup(8)\f[R]
tool.
Note that this behavior is subject to change as DM is more fully
integrated.
.IP
.nf
\f[C]
**zpool arguments**
**zpool [ -v ]**
\f[R]
.fi
.PP
Passed no arguments, \f[B]zpool\f[R] concisely lists each zpool (ZFS
storage pool) device currently available to the system.
Passed \[dq]-v\[dq], each zpool\[aq]s components will also be listed.
Otherwise, arguments will be sanitized and passed to the external
\f[B]zpool(8)\f[R] tool.
Note that this behavior is subject to change as ZFS is more fully
integrated.
.IP
.nf
\f[C]
**zfs arguments**
\f[R]
.fi
.PP
Arguments are sanitized and passed to the external \f[B]zfs(8)\f[R]
tool.
This command is not expected to be retained once ZFS is fully
integrated.
.IP
.nf
\f[C]
**target set path**
**target unset**
**target finalize**
**target**
\f[R]
.fi
.PP
The \f[B]set\f[R] subcommand sets the target (see the \f[B]--target\f[R]
option).
If a target has already been set, the command will fail.
If \f[B]path\f[R] does not exist in the current filesystem, the command
will fail.
If \f[B]path\f[R] exists, but is not a directory, the command will fail.
Called with \f[B]unset\f[R], undefines the target and all mappings
therein.
If there is no target defined, the command will fail.
Called with \f[B]finalize\f[R], the target\[aq]s /etc/fstab will be
written out.
Called with no arguments, lists the current target (if one exists).
.IP
.nf
\f[C]
**map [ mountdev mountpoint options ]**
**map**
\f[R]
.fi
.PP
Provided no arguments, \f[B]map\f[R] dumps the target\[aq]s /etc/fstab
as currently envisioned.
Otherwise, attempt to mount mountdev at mountpoint (relative to the
target root) as a filesystem of appropriate type, using the specified
mount options (see \f[B]mount(8)\f[R]).
If the mount is successful, the mapping will be added to the target
/etc/fstab (though this will not be written out until \f[B]target
finalize\f[R] is run).
The \f[B]map\f[R] command is unavailable unless in system preparation
mode (see \f[B]target\f[R]).
.IP
.nf
\f[C]
**unmap mountpoint**
\f[R]
.fi
.PP
\f[B]unmap\f[R] removes the target map, and unmounts the associated
mount.
The mapping will no longer be carried into the target\[aq]s /etc/fstab.
The mountpoint is relative to the target root.
.IP
.nf
\f[C]
**mounts**
\f[R]
.fi
.PP
Displays all currently-mounted filesystems.
Accepts no arguments.
.IP
.nf
\f[C]
**grubmap**
\f[R]
.fi
.PP
Invokes \f[B]grub-mkdevicemap\f[R] to display \f[B]GRUB2\[aq]s\f[R]
calculated device map.
This will not overwrite any existing device map, but is included merely
for diagnostic purposes.
Accepts no arguments.
.IP
.nf
\f[C]
**benchmark blockdev**
\f[R]
.fi
.PP
Run a simple, non-destructive benchmark on the block device.
Currently, this is implemented via \f[B]hdparm -t\f[R].
.IP
.nf
\f[C]
**troubleshoot**
\f[R]
.fi
.PP
Look for problems, both physical and logical, in the storage setup.
This command\[aq]s behavior is not yet well-defined FIXME.
.IP
.nf
\f[C]
**version**
\f[R]
.fi
.PP
Displays the \f[B]&dhpackage;\f[R] banner and version, and the version
of various tools/libraries.
\f[B]version\f[R] accepts no arguments.
.IP
.nf
\f[C]
**diags [ count ]**
\f[R]
.fi
.PP
Dump up through count diagnostic messages from the logging ringbuffer to
stdout.
Provided no parameter, all available diagnostic messages will be
printed.
Timestamps are printed along with each message.
.IP
.nf
\f[C]
**help command**
**help**
\f[R]
.fi
.PP
Invoked upon a \f[B]command\f[R], \f[B]help\f[R] displays that
command\[aq]s synopsis.
Otherwise, \f[B]help\f[R] lists a synopsis of each command.
.IP
.nf
\f[C]
**quit**
\f[R]
.fi
.PP
Exits the program.
See the \f[B]--target\f[R] command line option and \f[B]target\f[R]
command to understand the conditions for a successful return during
installation mode.
\f[B]quit\f[R] accepts no arguments.
.SH BUGS
.PP
Pedantic collections of ambiguous identifiers (for instance, if a label
equals another device\[aq]s /dev/ name) will lead to questionable
results.
This ought be fixed.
.SH SEE ALSO
.PP
\f[B]mount (2)\f[R], \f[B]swapoff (2)\f[R], \f[B]swapon (2)\f[R],
\f[B]umount (2)\f[R], \f[B]libblkid (3)\f[R], \f[B]notcurses (3)\f[R],
\f[B]fstab (5)\f[R], \f[B]proc (5)\f[R], \f[B]inotify (7)\f[R],
\f[B]udev (7)\f[R], \f[B]blkid(8)\f[R],, \f[B]dmraid(8)\f[R],
\f[B]dmsetup (8)\f[R], \f[B]growlight(8)\f[R], \f[B]grub-install
(8)\f[R], \f[B]grub-mkdevicemap (8)\f[R], \f[B]hdparm (8)\f[R],
\f[B]losetup (8)\f[R], \f[B]lsblk (8)\f[R], \f[B]mdadm (8)\f[R],
\f[B]mkfs (8)\f[R], \f[B]mount (8)\f[R], \f[B]parted (8)\f[R],
\f[B]sfdisk (8)\f[R], \f[B]umount (8)\f[R], \f[B]zfs (8)\f[R],
\f[B]zpool (8)\f[R]
.SH AUTHORS
nick black <nickblack@linux.com>.