1growlight-readline(8) growlight-readline(8)
2
6 growlight-readline - Block device and filesystem editor
7
9 growlight-readline [-h|--help] [-i|--import] [-v|--verbose] [-V|--ver‐
10 sion] [-t path|--target=path]
11
13 growlight-readline detects and describes disk pools, block devices,
14 partition tables, and partitions. It can partition devices, manipulate
15 ZFS, MD, DM, LVM and hardware RAID virtual devices, and prepare an
16 fstab file for using the devices to boot or in a chroot, and is fully
17 aware of variable sector sizes, GPT, and UEFI. growlight-readline fa‐
18 cilitates use of UUID/WWN- and HBA-based identification of block de‐
19 vices.
20 This page describes the line-based implementation. Consult grow‐
22 light(8) for a fullscreen notcurses(3)-based variant.
23
25 -h|--help: Print a brief usage summary, and exit.
26 -i|--import: Attempt to assemble aggregates (zpools, MD devices, etc)
28 based on block device scans at startup.
29 -v|--verbose: Be more verbose.
31 -V|--version: Print version information and exit.
33 --notroot: Force growlight-readline to start without necessary privi‐
35 leges (it will usually refuse to start).
36 -t path|--target=path: Run in system installation mode, using path as
38 the temporary mountpoint for the target's root filesystem. "map" com‐
39 mands will populate the hierarchy rooted at this mountpoint. System
40 installation mode can also be entered at run time with the "target"
41 command. The "map" command will not result in active mounts unless
42 growlight-readline is operating in system installation mode (they will
43 merely be used to construct target fstab output). Once system instal‐
44 lation mode is entered, growlight-readline will return 0 only as a re‐
45 sult of a successful invocation of the "target finalize" command. path
46 must exist at the time of its specification.
47
49 growlight-readline implements an interactive command line driven via
50 GNU Readline. Commands are entered; a newline causes input to be in‐
51 terpreted, and output resulting from this interpretation is displayed
52 to the user. Unlike programs such as fdisk(8) and gdisk(8), growlight-
53 readline acts on commands immediately: it neither requires nor provides
54 an explicit commit step (though several commands do require confirma‐
55 tion).
56 An argument specified as blockdev can be either a real block device, a
58 virtual block device, or a partition. An argument specified as parti‐
59 tion must be a partition within some kernel-recognized partition table.
60 An argument specified as fs must be a kernel-recognizable filesystem.
61 An argument specified as uuid must be 36 ASCII characters forming a
62 valid DCE 1.1 UUID. Devices can be specified via any appropriate iden‐
63 tifier (label, UUID, etc.).
64 **uefiboot [ -protectmbr ]**
66 Prepare the target for UEFI-based booting. A target root filesystem
68 map must be defined, and this filesystem must be mounted at the ch‐
69 root's toplevel. The filesystem must reside within a GPT partition
70 having the EFI System Partition (ef00) TUID of
71 C12A7328-F81F-11D2-BA4B-00A0C93EC93B. This GPT table must not reside
72 on an mdadm, device-mapper, or zfs device. Preferably, no other de‐
73 vices in the system are bootable, but this is not enforced.
74 If all these conditions are met, GRUB2 will be installed into this
76 filesystem, configured to boot a Linux kernel residing at FIXME. This
77 kernel must be compiled with EFI stub loader support. The bootloader
78 portion of the device's MBR will be overwritten with zeroes, if possi‐
79 ble, to deter attempting to perform a BIOS/MBR boot from the device.
80 Alternatively, the -protectmbr option will install a "protective MBR"
81 consisting of one type 0xEE (EFI GPT) partition spanning the disk.
82 This might be preferable if interoperating with GPT-unaware tools.
83 **biosboot**
85 Prepare the target for BIOS-based booting. A target root filesystem
87 map must be defined, and this filesystem must be mounted at the ch‐
88 root's toplevel. The filesystem must reside either within a GPT parti‐
89 tion having the BIOS Boot Partition (ef02) TUID of
90 21686148-6449-6E6F-744E-656564454649, or within a MBR partition having
91 type 0x83 (Linux). The partition table must not reside on an mdadm,
92 device-mapper, or zfs device. Preferably, no other devices in the sys‐
93 tem are bootable, but this is not enforced.
94 If all these conditions are met, GRUB2 will be installed into this
96 filesystem at /boot/grub, configured to boot a Linux kernel residing at
97 FIXME. GRUB2's first stage will be loaded into the bootloader portion
98 of the device's MBR. The partition containing GRUB2 will be marked as
99 active (flag 0x80).
100 **adapter reset adapter**
102 **adapter rescan adapter**
103 **adapter detail adapter**
104 **adapter [ -v ]**
105 Passed no arguments, adapter lists each HBA (Host Bus Adapter) device
107 known to the system, including those not actively used. Passed "-v",
108 attached devices of each HBA will also be listed. For each adapter
109 listed, the first token is an identifier suitable for use with other
110 adapter subcommands (it is typically the device driver's module name
111 suffixed by a small integer, but the exact form is intentionally left
112 implementation-defined). The "reset" subcommand resets the HBA, if it
113 supports this functionality. The "rescan" subcommand causes the kernel
114 to scan the HBA for newly connected devices. Both operations are per‐
115 formed via the Linux kernel's sysfs filesystem. "detail" will display
116 detailed information about the adapter.
117 **blockdev rescan blockdev**
119 **blockdev badblocks blockdev [ rw ]**
120 **blockdev wipebiosboot blockdev**
121 **blockdev ataerase blockdev**
122 **blockdev rmtable blockdev**
123 **blockdev mktable [ blockdev tabletype ]**
124 **blockdev detail blockdev**
125 **blockdev [ -v ]**
126 Passed no arguments, blockdev concisely lists all block devices recog‐
128 nized by the system. Passed "-v", partitions and filesystems present
129 on a given block device will also be listed. The "rescan" command
130 causes the kernel to reanalyze the device's geometry and partition ta‐
131 bles. Any changes will be propagated to growlight-readline. "bad‐
132 blocks" runs a non-destructive bad block check on the device. If pro‐
133 vided "rw", "badblocks" will perform a destructive, lenghtier, more
134 strenuous read-write check. "wipebiosboot" writes zeroes to the BIOS
135 bootcode section of a disk (the first 446 bytes of the first sector),
136 hopefully ensuring that no attempt will be made to perform a BIOS-type
137 boot from the device. "ataerase" uses the ATA Secure Erase functional‐
138 ity of the disk, if supported, to restore the device to factory set‐
139 tings. This can lead to noticeably improved performance from used Sol‐
140 id State Devices (SSDs). "rmtable" will attempt to write zeros over
141 all partition table structures such that libblkid(3) does not recognize
142 the disk as being partitioned. "mktable" will create a partition table
143 of the provided type; with no arguments, supported partition table
144 types are listed. "detail" will display detailed information about the
145 block device.
146 **partition del partition**
148 **partition add blockdev size name type**
149 **partition setuuid partition uuid**
150 **partition setname partition name**
151 **partition settype [ partition type ]**
152 **partition setflag [ partition on|off flag ]**
153 **partition [ -v ]**
154 Passed no arguments, partition concisely lists all detected partitions.
156 Passed "-v", data present on a given partition will also be listed.
157 "del" attempts to convert a partition to unallocated space. "add" at‐
158 tempts to carve a partition of the specified size, type and name from
159 the specified block device's free space. "size" may be either a single
160 number, representing a size in bytes, or a range indicated by one or
161 two numbers separated by a colon. A range with no first number speci‐
162 fies "empty space up until this sector." A range with no second number
163 specifies "empty space following this sector." A range with two numbers
164 indicates "the specified range", and must be wholly contained within
165 free space. A size of 0 indicates "all space available." When a size
166 is used instead of a sector range, the space is taken from the largest
167 free space. "setuuid" attempts to set the partition GUID (not the Type
168 UUID) to uuid. "setname" attempts to set the partition label to name.
169 With no arguments, "settype" lists the types supported by various par‐
170 titioning schemes. Otherwise, it attempts to set the specified type on
171 the specified partition. With no arguments, "setflag" lists the parti‐
172 tion flags supported by this system. Otherwise, it attempts to set or
173 unset the specified flag on the specified partition.
174 **fs mkfs [ blockdev fstype label ]**
176 **fs wipefs blockdev**
177 **fs fsck blockdev**
178 **fs setuuid blockdev uuid**
179 **fs setlabel blockdev label**
180 **fs loop file mountpoint mnttype options**
181 **fs mount blockdev mountpoint mnttype options**
182 **fs umount blockdev**
183 **fs**
184 Passed no arguments, fs concisely lists all detected possible filesys‐
186 tems, irrespective of mount status or viability. The "mkfs" subcommand
187 will create a filesystem on the specified block device of the specified
188 type, having the specified label (possibly truncated). "mkfs" with no
189 arguments lists supported filesystem types. "wipefs" will attempt to
190 destroy the specified filesystem's superblocks, to the degree that lib‐
191 blkid(3) does not detect them. "setuuid" will set the UUID of the
192 filesystem on blockdev, assuming that filesystem supports UUIDs. "set‐
193 label" will set the volume label of the filesystem on blockdev, assum‐
194 ing that filesystem supports volume labels. "mount" will attempt to
195 mount the block device as a mnttype-type filesystem at mountpoint.
196 This mount will not be added to either the host or target's /etc/fstab,
197 and will thus not persist across reboots. "loop" will attempt to mount
198 the file as a mnttype-type filesystem at mountpoint using a loop de‐
199 vice. "umount" will attempt to unmount the filesystem underlain by
200 blockdev. "fsck" will check the filesystem for correctness.
201 **swap on swapdev label [ uuid ]**
203 **swap off swapdev**
204 **swap**
205 Passed no arguments, swap concisely lists each swap device known to the
207 system, including those not actively used. The "on" subcommand at‐
208 tempts to create and use a swap device on swapdev. This command will
209 fail if swapdev is referenced by any map, mount, md device, dm device,
210 or zpool, if swapdev is not writable, or on any mkswap(8) or swapon(2)
211 error. The "off" subcommand attempts to halt an active swap device (it
212 does not write to the swap device itself, and thus the swap device re‐
213 mains usable). It will fail if the device is not an active swap, or on
214 any swapoff(2) failure.
215 **mdadm arguments**
217 **mdadm [ -v ]**
218 Passed no arguments, mdadm concisely lists each MD (Multiple Device,
220 aka the Linux kernel's mdraid driver) device currently available to the
221 system. Passed "-v", each MD device's components will also be listed.
222 Otherwise, arguments will be sanitized and passed to the external
223 mdadm(8) tool. Note that this behavior is subject to change as MD is
224 more fully integrated.
225 **dmsetup arguments**
227 Arguments are sanitized and passed to the external dmsetup(8) tool.
229 Note that this behavior is subject to change as DM is more fully inte‐
230 grated.
231 **zpool arguments**
233 **zpool [ -v ]**
234 Passed no arguments, zpool concisely lists each zpool (ZFS storage
236 pool) device currently available to the system. Passed "-v", each
237 zpool's components will also be listed. Otherwise, arguments will be
238 sanitized and passed to the external zpool(8) tool. Note that this be‐
239 havior is subject to change as ZFS is more fully integrated.
240 **zfs arguments**
242 Arguments are sanitized and passed to the external zfs(8) tool. This
244 command is not expected to be retained once ZFS is fully integrated.
245 **target set path**
247 **target unset**
248 **target finalize**
249 **target**
250 The set subcommand sets the target (see the --target option). If a
252 target has already been set, the command will fail. If path does not
253 exist in the current filesystem, the command will fail. If path ex‐
254 ists, but is not a directory, the command will fail. Called with un‐
255 set, undefines the target and all mappings therein. If there is no
256 target defined, the command will fail. Called with finalize, the tar‐
257 get's /etc/fstab will be written out. Called with no arguments, lists
258 the current target (if one exists).
259 **map [ mountdev mountpoint options ]**
261 **map**
262 Provided no arguments, map dumps the target's /etc/fstab as currently
264 envisioned. Otherwise, attempt to mount mountdev at mountpoint (rela‐
265 tive to the target root) as a filesystem of appropriate type, using the
266 specified mount options (see mount(8)). If the mount is successful,
267 the mapping will be added to the target /etc/fstab (though this will
268 not be written out until target finalize is run). The map command is
269 unavailable unless in system preparation mode (see target).
270 **unmap mountpoint**
272 unmap removes the target map, and unmounts the associated mount. The
274 mapping will no longer be carried into the target's /etc/fstab. The
275 mountpoint is relative to the target root.
276 **mounts**
278 Displays all currently-mounted filesystems. Accepts no arguments.
280 **grubmap**
282 Invokes grub-mkdevicemap to display GRUB2's calculated device map.
284 This will not overwrite any existing device map, but is included merely
285 for diagnostic purposes. Accepts no arguments.
286 **benchmark blockdev**
288 Run a simple, non-destructive benchmark on the block device. Current‐
290 ly, this is implemented via hdparm -t.
291 **troubleshoot**
293 Look for problems, both physical and logical, in the storage setup.
295 This command's behavior is not yet well-defined FIXME.
296 **version**
298 Displays the &dhpackage; banner and version, and the version of various
300 tools/libraries. version accepts no arguments.
301 **diags [ count ]**
303 Dump up through count diagnostic messages from the logging ringbuffer
305 to stdout. Provided no parameter, all available diagnostic messages
306 will be printed. Timestamps are printed along with each message.
307 **help command**
309 **help**
310 Invoked upon a command, help displays that command's synopsis. Other‐
312 wise, help lists a synopsis of each command.
313 **quit**
315 Exits the program. See the --target command line option and target
317 command to understand the conditions for a successful return during in‐
318 stallation mode. quit accepts no arguments.
319
321 Pedantic collections of ambiguous identifiers (for instance, if a label
322 equals another device's /dev/ name) will lead to questionable results.
323 This ought be fixed.
324
326 mount (2), swapoff (2), swapon (2), umount (2), libblkid (3), notcurses
327 [1m(3), fstab (5), proc (5), inotify (7), udev (7), blkid(8),, dmraid(8),
328 dmsetup (8), growlight(8), grub-install (8), grub-mkdevicemap (8), hd‐
329 parm (8), losetup (8), lsblk (8), mdadm (8), mkfs (8), mount (8), part‐
330 ed (8), sfdisk (8), umount (8), zfs (8), zpool (8)
331
333 nick black <nickblack@linux.com>.
334 v1.2.32 growlight-readline(8)