growlight-readline(8)

📦 version 1.2.38, in fedora 43, fedora 44

🌸 NAME 🌸

okay so growlight-readline is literally your block device and filesystem editor, bestie 💅 that's the whole vibe, no cap.

✨ SYNOPSIS ✨

growlight-readline [-h|--help] [-i|--import] [-v|--verbose]
[-V|--version] [-t path|--target=path]

💖 DESCRIPTION 💖

okay bestie, listen — growlight-readline detects and describes disk pools, block devices, partition tables, and partitions. She's not just a looker either, she does things: she can partition devices, manipulate ZFS, MD, DM, LVM and hardware RAID virtual devices, and she'll even prepare an fstab file for using the devices to boot or in a chroot. And the way that she's fully aware of variable sector sizes, GPT, and UEFI? 😭 iconic. She also facilitates use of UUID/WWN- and HBA-based identification of block devices. periodt.

This page right here describes the line-based implementation. For the fullscreen notcurses(3)-based variant, go consult growlight(8) 🦋

🎀 OPTIONS 🎀

  • -h, --help — prints a brief usage summary and dips. that's it, that's the whole thing 🌸
  • -i, --import — attempts to assemble aggregates (zpools, MD devices, etc) based on block device scans at startup. she's doing detective work fr fr 🔍
  • -v, --verbose — be more verbose. give her the mic, she has more to say 👑
  • -V, --version — prints version information and exits. quick lil flex ✨
  • --notroot — forces growlight-readline to start without necessary privileges (she will usually refuse to start). like girl... she said no the first time 🙈
  • -t path, --target=path — runs in system installation mode, using path as the temporary mountpoint for the target's root filesystem. "map" commands will populate the hierarchy rooted at this mountpoint. System installation mode can also be entered at run time with the "target" command. The "map" command will not result in active mounts unless growlight-readline is operating in system installation mode (they will merely be used to construct target fstab output). Once system installation mode is entered, growlight-readline will return 0 only as a result of a successful invocation of the "target finalize" command. path must exist at the time of its specification. 💀

🌈 USAGE 🌈

okay so here's the tea — growlight-readline implements an interactive command line driven via GNU Readline. You type commands; a newline causes input to be interpreted, and output resulting from this interpretation is displayed to you. And unlike programs such as fdisk(8) and gdisk(8), growlight-readline acts on commands immediately: it neither requires nor provides an explicit commit step (though several commands do require confirmation). she's decisive like that 💅

Now, the argument types, because you will be asked for them:

  • an argument specified as blockdev can be either a real block device, a virtual block device, or a partition 🧚
  • an argument specified as partition must be a partition within some kernel-recognized partition table
  • an argument specified as fs must be a kernel-recognizable filesystem
  • an argument specified as uuid must be 36 ASCII characters forming a valid DCE 1.1 UUID

Devices can be specified via any appropriate identifier (label, UUID, etc.). you have options, queen 👑

🦋 uefiboot 🦋

uefiboot [ -protectmbr ]

Prepare the target for UEFI-based booting. A target root filesystem map must be defined, and this filesystem must be mounted at the chroot'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. 🫶

If all these conditions are met, GRUB2 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's MBR will be overwritten with zeroes, if possible, to deter attempting to perform a BIOS/MBR boot from the device. Alternatively, the -protectmbr option will install a "protective MBR" consisting of one type 0xEE (EFI GPT) partition spanning the disk. This might be preferable if interoperating with GPT-unaware tools. 💖

🌸 biosboot 🌸

biosboot

Prepare the target for BIOS-based booting. A target root filesystem map must be defined, and this filesystem must be mounted at the chroot'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. 😌

If all these conditions are met, GRUB2 will be installed into this filesystem at /boot/grub, configured to boot a Linux kernel residing at FIXME. GRUB2's first stage will be loaded into the bootloader portion of the device's MBR. The partition containing GRUB2 will be marked as active (flag 0x80). slay 💅

🧚 adapter 🧚

adapter reset adapter
adapter rescan adapter
adapter detail adapter
adapter [ -v ]

Passed no arguments, adapter lists each HBA (Host Bus Adapter) device known to the system, including those not actively used. Passed "-v", attached devices of each HBA will also be listed. For each adapter listed, the first token is an identifier suitable for use with other adapter subcommands (it is typically the device driver's module name suffixed by a small integer, but the exact form is intentionally left implementation-defined — mystery is the moment 🔥).

  • "reset" resets the HBA, if it supports this functionality
  • "rescan" causes the kernel to scan the HBA for newly connected devices
  • both operations are performed via the Linux kernel's sysfs filesystem
  • "detail" will display detailed information about the adapter

💜 blockdev 💜

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 ]

Passed no arguments, blockdev concisely lists all block devices recognized by the system. Passed "-v", partitions and filesystems present on a given block device will also be listed. 🌈

  • "rescan" causes the kernel to reanalyze the device's geometry and partition tables. Any changes will be propagated to growlight-readline
  • "badblocks" runs a non-destructive bad block check on the device. If provided "rw", "badblocks" will perform a destructive, lengthier, more strenuous read-write check ⚠️ (yes bestie, destructive means destructive, be careful)
  • "wipebiosboot" 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
  • "ataerase" 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) ✨
  • "rmtable" will attempt to write zeros over all partition table structures such that libblkid(3) does not recognize the disk as being partitioned
  • "mktable" will create a partition table of the provided type; with no arguments, supported partition table types are listed
  • "detail" will display detailed information about the block device

🎀 partition 🎀

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 ]

Passed no arguments, partition concisely lists all detected partitions. Passed "-v", data present on a given partition will also be listed.

  • "del" attempts to convert a partition to unallocated space
  • "add" attempts to carve a partition of the specified size, type and name from the specified block device's free space
  • "size" 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 "empty space up until this sector." A range with no second number specifies "empty space following this sector." A range with two numbers indicates "the specified range", and must be wholly contained within free space. A size of 0 indicates "all space available." When a size is used instead of a sector range, the space is taken from the largest free space. 🧠
  • "setuuid" attempts to set the partition GUID (not the Type UUID) to uuid
  • "setname" attempts to set the partition label to name
  • with no arguments, "settype" lists the types supported by various partitioning schemes. Otherwise, it attempts to set the specified type on the specified partition
  • with no arguments, "setflag" lists the partition flags supported by this system. Otherwise, it attempts to set or unset the specified flag on the specified partition

🍓 fs 🍓

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

Passed no arguments, fs concisely lists all detected possible filesystems, irrespective of mount status or viability. 👀

  • the "mkfs" subcommand will create a filesystem on the specified block device of the specified type, having the specified label (possibly truncated). "mkfs" with no arguments lists supported filesystem types
  • "wipefs" will attempt to destroy the specified filesystem's superblocks, to the degree that libblkid(3) does not detect them 💀
  • "setuuid" will set the UUID of the filesystem on blockdev, assuming that filesystem supports UUIDs
  • "setlabel" will set the volume label of the filesystem on blockdev, assuming that filesystem supports volume labels
  • "mount" 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's /etc/fstab, and will thus not persist across reboots ⚠️
  • "loop" will attempt to mount the file as a mnttype-type filesystem at mountpoint using a loop device
  • "umount" will attempt to unmount the filesystem underlain by blockdev
  • "fsck" will check the filesystem for correctness. she's just checking in on you bestie 🫶

👑 swap 👑

swap on swapdev label [ uuid ]
swap off swapdev
swap

okay so, when you just run swap with no arguments, it gives you a concise list of every swap device the system knows about — even the ones that aren't actively being used. 💖 The on subcommand tries to create and use a swap device on swapdev. But bestie, this will fail if swapdev is referenced by any map, mount, md device, dm device, or zpool, if swapdev isn't writable, or if any mkswap(8) or swapon(2) error happens. 😭 The off subcommand tries to halt an active swap device — and no, it does not write to the swap device itself, so the swap device stays usable. It'll fail if the device isn't an active swap, or if any swapoff(2) failure happens. 💅

✨ mdadm arguments

mdadm [ -v ]

When you run mdadm with no arguments, it gives you a concise list of every MD (Multiple Device, aka the Linux kernel's mdraid driver) device currently available to the system. 🦋 If you pass -v, each MD device's components also get listed. Otherwise, arguments get sanitized and passed to the external mdadm(8) tool. Just a heads up: this behavior is subject to change as MD gets more fully integrated. 💅

💫 dmsetup arguments

Arguments get sanitized and passed to the external dmsetup(8) tool. Note that this behavior is subject to change as DM gets more fully integrated. 👑

🌊 zpool arguments

zpool [ -v ]

Run zpool with no arguments, and it concisely lists each zpool (ZFS storage pool) device currently available to the system. If you pass -v, each zpool's components also get listed. Otherwise, arguments get sanitized and passed to the external zpool(8) tool. Again, this behavior is subject to change as ZFS gets more fully integrated. 🌈

❄️ zfs arguments

Arguments get sanitized and passed to the external zfs(8) tool. This command is not expected to be retained once ZFS is fully integrated. 🥶

🎯 target

target set path
target unset
target finalize
target

The set subcommand sets the target (check the --target option for context). If a target has already been set, the command fails. If path doesn't exist in the current filesystem, it fails. If path exists but isn't a directory, it fails. 💀

Called with unset, it undefines the target and all mappings inside it. If there's no target defined, the command fails. Called with finalize, the target's /etc/fstab gets written out. Called with no arguments, it lists the current target (if one exists). ✨

🗺️ map

map [ mountdev mountpoint options ]
map

With no arguments, map dumps the target's /etc/fstab as it's currently envisioned. Otherwise, it attempts to mount mountdev at mountpoint (relative to the target root) as a filesystem of appropriate type, using the specified mount options (see mount(8)). If the mount succeeds, the mapping gets added to the target /etc/fstab — but note, this won't be written out until you run target finalize. 🫶

The map command is unavailable unless you're in system preparation mode (see target). 🚫

🧹 unmap mountpoint

unmap removes the target map and unmounts the associated mount. The mapping will no longer be carried into the target's /etc/fstab. The mountpoint is relative to the target root. 💅

📂 mounts

Displays all currently-mounted filesystems. Accepts no arguments. 🗂️

🥾 grubmap

Invokes grub-mkdevicemap to display GRUB2's calculated device map. This will not overwrite any existing device map — it's included merely for diagnostic purposes. Accepts no arguments. 🔍

⚡ benchmark blockdev

Run a simple, non-destructive benchmark on the block device. Currently, this is implemented via hdparm -t. 🏎️

🩺 troubleshoot

Look for problems, both physical and logical, in the storage setup. This command's behavior is not yet well-defined FIXME. 🚧

👑 version

Displays the &dhpackage; banner and version, and the version of various tools/libraries. version accepts no arguments. 💖

🧾 diags [ count ]

Dump up through count diagnostic messages from the logging ringbuffer to stdout. If you provide no parameter, all available diagnostic messages get printed. Timestamps are printed along with each message. 🕒

🆘 help

help command
help

When invoked with a command, help displays that command's synopsis. Otherwise, help lists a synopsis of each command. 📖

🚪 quit

Exits the program. See the --target command line option and the target command to understand the conditions for a successful return during installation mode. quit accepts no arguments. 👋

🐛 BUGS 🐛

Pedantic collections of ambiguous identifiers — for instance, if a label equals another device's /dev/ name — will lead to questionable results. This ought to be fixed. 💀

👀 SEE ALSO 👀

mount (2), swapoff (2), swapon (2), umount (2), libblkid (3), notcurses (3), fstab (5), proc (5), inotify (7), udev (7), blkid(8),, dmraid(8), dmsetup (8), growlight(8), grub-install (8), grub-mkdevicemap (8), hdparm (8), losetup (8), lsblk (8), mdadm (8), mkfs (8), mount (8), parted (8), sfdisk (8), umount (8), zfs (8), zpool (8)

💖 AUTHORS 💖

nick black nickblack@linux.com

and that's the tea! ☕️ this has been growlight-readline(8), version v1.2.38. stay iconic. 💅✨

📦 where this page comes from