1growlight-readline(8)                                    growlight-readline(8)
2
3
4

NAME

6       growlight-readline - Block device and filesystem editor
7

SYNOPSIS

9       growlight-readline  [-h|--help] [-i|--import] [-v|--verbose] [-V|--ver‐
10       sion] [-t path|--target=path]
11

DESCRIPTION

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
21       This page  describes  the  line-based  implementation.   Consult  grow‐
22       light(8) for a fullscreen notcurses(3)-based variant.
23

OPTIONS

25       -h|--help: Print a brief usage summary, and exit.
26
27       -i|--import:  Attempt  to assemble aggregates (zpools, MD devices, etc)
28       based on block device scans at startup.
29
30       -v|--verbose: Be more verbose.
31
32       -V|--version: Print version information and exit.
33
34       --notroot: Force growlight-readline to start without  necessary  privi‐
35       leges (it will usually refuse to start).
36
37       -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

USAGE

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
57       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
65              **uefiboot [ -protectmbr ]**
66
67       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
75       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
84              **biosboot**
85
86       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
95       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
101              **adapter reset adapter**
102              **adapter rescan adapter**
103              **adapter detail adapter**
104              **adapter [ -v ]**
105
106       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
118              **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
127       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
147              **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
155       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
175              **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
185       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
202              **swap on swapdev label [ uuid ]**
203              **swap off swapdev**
204              **swap**
205
206       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
216              **mdadm arguments**
217              **mdadm [ -v ]**
218
219       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
226              **dmsetup arguments**
227
228       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
232              **zpool arguments**
233              **zpool [ -v ]**
234
235       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
241              **zfs arguments**
242
243       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
246              **target set path**
247              **target unset**
248              **target finalize**
249              **target**
250
251       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
260              **map [ mountdev mountpoint options ]**
261              **map**
262
263       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
271              **unmap mountpoint**
272
273       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
277              **mounts**
278
279       Displays all currently-mounted filesystems.  Accepts no arguments.
280
281              **grubmap**
282
283       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
287              **benchmark blockdev**
288
289       Run a simple, non-destructive benchmark on the block device.   Current‐
290       ly, this is implemented via hdparm -t.
291
292              **troubleshoot**
293
294       Look  for  problems,  both  physical and logical, in the storage setup.
295       This command's behavior is not yet well-defined FIXME.
296
297              **version**
298
299       Displays the &dhpackage; banner and version, and the version of various
300       tools/libraries.  version accepts no arguments.
301
302              **diags [ count ]**
303
304       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
308              **help command**
309              **help**
310
311       Invoked  upon a command, help displays that command's synopsis.  Other‐
312       wise, help lists a synopsis of each command.
313
314              **quit**
315
316       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

BUGS

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

SEE ALSO

326       mount (2), swapoff (2), swapon (2), umount (2), libblkid (3), notcurses
327       (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

AUTHORS

333       nick black <nickblack@linux.com>.
334
335
336
337                                    v1.2.31              growlight-readline(8)
Impressum