Add site(8), OpenBSD installation and upgrade customization

This is practically https://www.openbsd.org/faq/faq4.html#site
"Customizing the Install Process"++ with practical examples and references
to/from relevant manuals.

Prodding/first diff from Aaron Poffenberger <akp AT hypernote DOT com>
"I didn't know about it and now I'm using it on all my systems." florian
Feedback semarie afresh1
OK afresh1

3 files changed, 103 insertions, 5 deletions

diff --git a/share/man/man8/Makefile b/share/man/man8/Makefile
index f21de024e82..1d9a6d1a625 100644
--- a/share/man/man8/Makefile
+++ b/share/man/man8/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.102 2021/05/01 16:11:10 visa Exp $
+#	$OpenBSD: Makefile,v 1.103 2021/11/06 01:24:37 kn Exp $
 #	$NetBSD: Makefile,v 1.13 1996/03/28 21:36:40 mark Exp $
 #	@(#)Makefile	8.1 (Berkeley) 6/5/93
 
@@ -6,7 +6,7 @@ MAN=	afterboot.8 autoinstall.8 boot_config.8 bulk.8 \
 	crash.8 daily.8 \
 	diskless.8 genassym.sh.8 intro.8 netstart.8 rc.8 \
 	rc.conf.8 rc.d.8 rc.shutdown.8 rc.subr.8 release.8 \
-	security.8 ssl.8 starttls.8 sticky.8 yp.8
+	security.8 site.8 ssl.8 starttls.8 sticky.8 yp.8
 
 SUBDIR=	man8.alpha man8.amd64 man8.arm64 man8.armv7 \
 	man8.hppa man8.i386 man8.landisk \
diff --git a/share/man/man8/autoinstall.8 b/share/man/man8/autoinstall.8
index f30bb61d9c1..b21a7cef532 100644
--- a/share/man/man8/autoinstall.8
+++ b/share/man/man8/autoinstall.8
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: autoinstall.8,v 1.23 2021/07/18 11:08:34 kn Exp $
+.\"     $OpenBSD: autoinstall.8,v 1.24 2021/11/06 01:24:37 kn Exp $
 .\"
 .\" Copyright (c) 2013 Robert Peichaer <rpe@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: July 18 2021 $
+.Dd $Mdocdate: November 6 2021 $
 .Dt AUTOINSTALL 8
 .Os
 .Sh NAME
@@ -32,6 +32,10 @@ file and HTTP to fetch the file.
 If that fails, the installer asks for the location which can either be
 a URL or a local path.
 .Pp
+See
+.Xr site 8
+for how to provide custom configuration.
+.Pp
 To start unattended installation or upgrade choose '(A)utoinstall' at the
 install prompt.
 If there is only one network interface, the installer fetches the response
@@ -235,7 +239,8 @@ host foo {
 .Sh SEE ALSO
 .Xr dhcp-options 5 ,
 .Xr dhcpd.conf 5 ,
-.Xr diskless 8
+.Xr diskless 8 ,
+.Xr site 8
 .Sh HISTORY
 The
 .Nm
diff --git a/share/man/man8/site.8 b/share/man/man8/site.8
new file mode 100644
index 00000000000..4ceffdf2cd6
--- /dev/null
+++ b/share/man/man8/site.8
@@ -0,0 +1,93 @@
+.\"     $OpenBSD: site.8,v 1.1 2021/11/06 01:24:37 kn Exp $
+.\"
+.\" Copyright (c) 2021 Klemens Nanni <kn@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: November 6 2021 $
+.Dt SITE 8
+.Os
+.Sh NAME
+.Nm site
+.Nd OpenBSD installation and upgrade customization
+.Sh DESCRIPTION
+The
+.Ox
+installer allows user-created sets and scripts to complement
+and modify the files from a default install prior to rebooting.
+.Pp
+Like the official file sets, generic
+.Pa site${ Ns Va VERSION Ns }.tgz
+and
+hostname-specific
+.Pa site${ Ns Va VERSION Ns }-$( Ns Ic hostname Fl s Ns ).tgz
+sets are
+.Xr gzip 1
+compressed
+.Xr tar 1
+archives rooted in
+.Pa /
+and untarred with the
+.Fl xzphf
+options.
+.Pp
+.Nm sets
+must be included in
+.Pa index.txt
+in order to be fetched via
+HTTP(S) and selectable in the installer.
+.Pp
+If they exist and are executable,
+.Pa /install.site
+and
+.Pa /upgrade.site
+are run at the end of the install and upgrade process, respectively, with
+.Xr chroot 8
+based at the system's root.
+.Sh FILES
+.Bl -tag -width "site${VERSION}-$(hostname -s).tgz" -compact
+.It Pa site${ Ns Va VERSION Ns }.tgz
+Generic set.
+.It Pa site${ Ns Va VERSION Ns }-$( Ns Ic hostname Fl s Ns ).tgz
+Host-specific set.
+.It Pa /upgrade.site
+Generic post-upgrade script.
+.It Pa /install.site
+Generic post-install script.
+.El
+.Sh EXAMPLES
+Create
+.Nm
+sets and update the index:
+.Bd -literal -offset indent
+# tar -czhf site70.tgz generic/
+# tar -czhf site70-puffy.tgz puffy/
+# ls -lT > index.txt
+.Ed
+.Pp
+Upgrade
+.Xr packages 7
+upon reboot after
+.Xr sysupgrade 8
+upgraded the system:
+.Bd -literal -offset indent
+# cat <<- EOF >> /upgrade.site
+	echo 'pkg_add -Iu' >>/etc/rc.firsttime
+EOF
+# chmod +x /upgrade.site
+# sysupgrade
+.Ed
+.Sh SEE ALSO
+.Xr autoinstall 8 ,
+.Xr rc 8 ,
+.Xr sysupgrade 8