share/man/man7/growfs.7

   1 .\" Copyright 2014 John-Mark Gurney
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd November 22, 2022
  28 .Dt GROWFS 7
  29 .Os
  30 .Sh NAME
  31 .Nm growfs ,
  32 .Nm growfs_fstab
  33 .Nd start up scripts to grow the root file system and add swap
  34 .Sh DESCRIPTION
  35 The
  36 .Nm
  37 script normally runs at the first boot after system installation.
  38 If the boot disk is larger than the root file system and boot partitions,
  39 and the root file system is in the last partition,
  40 .Nm
  41 can expand the root file system.
  42 It can also add a swap partition, with a default size of 10% of the boot disk.
  43 Swap is limited to twice the memory size up to 4 GB,
  44 8 GB up to 8 GB of memory, and memory size over 8 GB.
  45 It is also limited to the
  46 .Xr sysctl 8
  47 value of
  48 .Li vm.swap_maxpages
  49 divided by 2.
  50 By default, no swap partition is created if an existing swap partition is found
  51 or is listed in
  52 .Pa /etc/fstab ,
  53 or the disk is under 15 GB.
  54 The
  55 .Nm growfs_fstab
  56 script adds any new swap partition to
  57 .Pa /etc/fstab
  58 after the root file system is made writable,
  59 and enables its use as a dump partition if the
  60 .Va dumpdev
  61 variable from
  62 .Xr rc.conf 5
  63 is set to
  64 .Li AUTO .
  65 .Pp
  66 The following options in
  67 .Pa /etc/rc.conf
  68 control the behavior of
  69 .Nm :
  70 .Bl -tag -width ".Va growfs_swap_size" -offset indent
  71 .It Va growfs_enable
  72 .Pq Dq Li NO
  73 If set to
  74 .Dq Li YES ,
  75 the first time the machine boots, the root file system will be automatically
  76 expanded, if possible, to fill up all available space after it,
  77 after optionally adding a swap device at the end.
  78 .It Va growfs_swap_size
  79 .Pq Dq Li \&
  80 If set to
  81 .Dq Li 0 ,
  82 the addition of a swap partition is disabled.
  83 An empty value
  84 .Pq Dq Li \&
  85 allows the creation of a swap partition with the default size.
  86 If set to another value,
  87 the swap partition will be created with the specified size in bytes,
  88 even if another swap partition is detected.
  89 .El
  90 .Pp
  91 A setting for
  92 .Va growfs_swap_size
  93 can be set in the kernel environment, in which case it overrides
  94 the value from
  95 .Pa /etc/rc.conf .
  96 .Pp
  97 To expand the root file system without rebooting, run the following command:
  98 .Dl % /etc/rc.d/growfs onestart
  99 In addition, if a swap partition is added, run the command:
 100 .Dl % /etc/rc.d/growfs_fstab onestart
 101 Note that if a disk is expanded again,
 102 and if the root file system had previously been expanded
 103 and a swap partition added, it is necessary to delete the swap
 104 partition before this procedure
 105 in order to expand the root file system to the new size.
 106 A new swap partition can be created during the expansion.
 107 .Sh IMPLEMENTATION NOTES
 108 The
 109 .Nm
 110 script only attempts to expand the root file system,
 111 and free space must be available immediately after the root partition.
 112 It is normally used on images that have a single file system.
 113 The script requires that
 114 .Xr awk 1
 115 be present and in the path.
 116 This usually means that
 117 .Pa /usr
 118 must be available prior to running the script.
 119 .Sh FILES
 120 .Bl -tag -compact -width Pa
 121 .It Pa /etc/fstab
 122 .It Pa /etc/rc.conf
 123 .El
 124 .Sh EXIT STATUS
 125 .Ex -std
 126 .Sh SEE ALSO
 127 .Xr fstab 5 ,
 128 .Xr rc.conf 5 ,
 129 .Xr growfs 8 ,
 130 .Xr zpool 8
 131 .Sh HISTORY
 132 The
 133 .Nm
 134 manual page first appeared in
 135 .Fx 10.1 .
 136 The ability to add a swap partition was added in
 137 .Fx 14.0 .
 138 .Sh AUTHORS
 139 The man page and script were written by
 140 .An John-Mark Gurney Aq Mt jmg@FreeBSD.org .
 141 The ability to create a swap partition was added by
 142 .An Michael Karels Aq Mt karels@FreeBSD.org .