.\"	$NetBSD: release.7,v 1.40 2022/08/21 15:01:08 brook Exp $
.\"
.\" Copyright (c) 1997, 2000, 2005 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Charles M. Hannum and Jason R. Thorpe.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd July 13, 2020
.Dt RELEASE 7
.Os
.Sh NAME
.Nm release
.Nd layout of NetBSD releases and snapshots
.Sh DESCRIPTION
This document describes the layout of
.Nx
releases and snapshots.
This layout should be consistent between FTP servers and CD-ROMs,
except possibly the path that leads to the release hierarchy.
.Pp
In this document, the following special words have these definitions:
.Bl -tag -width "<machine_arch>"
.It Aq Em machine
The platform for which the release was built, corresponding to the
.Em hw.machine
sysctl variable, e.g.,
.Em i386
or
.Em amiga .
.It Aq Em machine_arch
The architecture for which a particular installation set was built,
corresponding to the
.Em hw.machine_arch
sysctl variable, e.g.,
.Em i386
or
.Em m68k .
.It Aq Em rel
The release version number.
.El
.Pp
All
.Sy README
files are descriptions of the various files in directories that have
.Dq non-standard
contents.
There may also be a
.Sy README
file at the top-level,
describing who built the snapshot and under what circumstances
.Po e.g., whether it's an official
.Nx
snapshot, or not
.Pc .
.Pp
All
.Sy MD5
files are MD5 digests for the various files in that directory, in the
format produced by the command:
.Sy cksum -a MD5 Aq Sy file .
.Pp
All
.Sy SHA512
files are SHA512 digests for the various files in that directory, in the
format produced by the command:
.Sy cksum -a SHA512 Aq Sy file .
.Pp
The SHA512 digest is safer, but MD5 checksums are provided so that a wider
range of operating systems can check the integrity of the release files.
.Pp
Files that end in
.Sy .tgz
are gzipped tar archives.
This is used in lieu of
.Sy .tar.gz
because the software used to download the sets may incorrectly auto-unpack
files ending in
.Sy .gz
and to accommodate systems which only support 3 character extensions
to file names.
.Pp
All tar archives are relative to the target's
.Sy /
directory, and
.Em do not
include the leading
.Dq / .
.Pp
The root of the release hierarchy may be the root directory of a
CD-ROM, but in all other cases it should be
.Sm off
.Xo
.Sy .../NetBSD-
.Aq Em rel
.Sy / .
.Xc
.Sm on
.Pp
The root of the release hierarchy should contain the following
files and subdirectories:
.Pp
.Bl -tag -width "<machine>"
.It Sy images/
Image files intended for use in installing
.Nx .
There are different types of images for different platforms, and sometimes
multiple different image types for a single platform.
.Pp
Images in this directory, unlike images in the
.Sm off
.Xo
.Sy .../NetBSD-
.Aq Em rel
.Sy /
.Aq Em machine
.Sy /installation/\\*/
.Xc
.Sm on
directories, contain file systems that
have an internal layout that corresponds to
a complete release for a given machine type.
If built with
.Dq iso-image-source ,
then it will also contain a
.Dq source
directory.
These images are usually bootable.
.Bl -tag -width "NetBSD-<rel>-<machine>.iso"
.It Sy MD5
.It Sy SHA512
.It Sy NetBSD- Ns Ao Em rel Ac Ns Sy - Ns Ao Em machine Ac Ns Sy .iso
CD-ROM images in ISO 9660 format, usually created with
.Dq ./build.sh ... iso-image ...
after a
.Dq ./build.sh -x ... release ...
in
.Pa src
or created with
.Dq ./build.sh ... iso-image-source ...
after a
.Dq ./build.sh -x ... release sourcesets ...
in
.Pa src .
.It Sy NetBSD- Ns Ao Em rel Ac Ns Sy - Ns Ao Em machine Ac Ns Sy -install.img.gz
Bootable installation images intended to be written to any drive which
appears as an
.Xr sd 4
type, such as USB flash disks.
These images are created with
.Dq ./build.sh ... install-image
in
.Pa src .
.El
.
.It Sy shared/
Files shared by two or more machine types.
.Bl -tag -width "<machine_arch>"
.It Ao Em machine_arch Ac Ns Pa /
Files which may be shared by all systems of the same
.Aq Em machine_arch
will be located in
.Sm off
.Xo
.Sy .../NetBSD-
.Aq Em rel
.Sy /shared/
.Aq Em machine_arch
.Sy /
.Xc
.Sm on
with symbolic links pointing to these files from the
.Aq Em machine
subdirectory.
.It Sy ALL/
Files which are completely machine-independent will be
located in
.Sy .../NetBSD- Ns Ao Em rel Ac Ns Sy /shared/ALL/
with symbolic links pointing to these files from the
.Aq Em machine
subdirectory.
.El
.
.It Sy source/
Source code of the operating system should be put into
.Sy .../NetBSD- Ns Ao Em rel Ac Ns Sy /source/
using the following layout:
.Pp
.Bl -tag -width "sets/"
.It Sy sets/
Sources for the various system sets.
.Bl -tag -width "sharesrc.tgz"
.It Sy MD5
.It Sy SHA512
.It Sy gnusrc.tgz
Contains sources for all GPLed and possibly other programs that
contains restrictions in their licensing that prevent others from
using these programs in closed-source environments.
.It Sy sharesrc.tgz
Contains machine-independent data files that can be shared across
architectures/systems.
.It Sy src.tgz
The operating system's userland source code, including all programs,
tools, libraries, etc.
.It Sy syssrc.tgz
Kernel sources for all architectures plus sources of the tools needed
to build kernels (like
.Xr config 1 ) .
.It Sy xsrc.tgz
Source code of the X Window System used on all
.Nx
architectures.
Includes X clients and servers.
.El
.El
.
.It Ao Em machine Ac Ns Pa /
The binary releases in
.Sm off
.Xo
.Sy .../NetBSD-
.Aq Em rel
.Sy /
.Aq Em machine
.Sy /
.Xc
.Sm on
fit the following layout:
.Bl -tag -width "installation/"
.It Sy INSTALL.txt
Installation notes, including complete descriptions of files contained
within the release hierarchy
.It Sy INSTALL.more
pretty version, suited for viewing with
.Xr more 1
.It Sy INSTALL.html
HTML version
.It Sy INSTALL.ps
PostScript version
.It Sy binary/
system binaries
.Bl -tag -width "SHA512/"
.It Sy gzimg/
compressed system images
.Bl -tag -width "xserver.tgz"
.It Ao Em machine Ac Ns Pa .tar.gz
The primary system image on those platforms that provide them.  These
images may not be bootable.
.It Ao Em machine Ac Ns Pa - Ns Ao Em board Ac Ns Pa .tar.gz
A bootable system image for a particular board, on platforms that
provide them.
.El
.It Sy sets/
installation sets
.Bl -tag -width "xserver.tgz"
.It Sy MD5
.It Sy SHA512
.It Sy base.tgz
The base binary distribution.
This set contains the base
.Nx
utilities that are necessary for the system to run and be minimally
functional.
This set excludes all things listed in the sets
described below.
.It Sy comp.tgz
The compiler tools distribution.
This set contains the C and C++
compilers, assembler, linker, other toolchain components, and their
manual pages.
It also includes the system include files
.Pq Pa /usr/include
and the static system libraries.
.It Sy etc.tgz
This set contains the system configuration files that reside in
.Pa /etc
and in several other places throughout the file system hierarchy.
.It Sy games.tgz
This set includes the games and their manual pages.
.It Sy kern-GENERIC.tgz
This set includes a kernel built from the
.Sy GENERIC
kernel configuration file.
This is meant as an example only; different
platforms may have differently named kernels.
.It Sy man.tgz
This set includes all of the manual pages for the binaries and other
software contained in the
.Sy base
set which are not included in the other sets.
.It Sy misc.tgz
This set includes miscellaneous non-essential files, including dictionaries,
the typesettable document set, and various other documentation and example
configuration files.
.It Sy modules.tgz
This set includes all the kernel modules.
.It Sy rescue.tgz
This set contains the
.Xr rescue 8
utilities.
.It Sy tests.tgz
This set includes the
.Xr tests 7
for
.Xr atf 7 ,
the automated test framework used by NetBSD.
.It Sy text.tgz
This set includes the
.Nx
text processing tools, including
.Xr groff 1 ,
all related programs, and their manual pages.
.It Sy xbase.tgz
This set includes the base X11 distribution, including manual pages
and excluding everything contained in the other X11 sets.
.It Sy xetc.tgz
This set includes X11 configuration files.
.It Sy xcomp.tgz
This set includes the X11 include files and static X11 libraries.
.It Sy xfont.tgz
This set includes the X11 fonts.
.It Sy xserver.tgz
This set includes the X servers and manual pages for
a given machine.
.Em "Note: this set may not be available on some platforms" .
.El
.It Sy kernel/
suitably named, gzipped kernels
.Bl -tag -width "netbsd-GENERIC.gz"
.It Sy MD5
.It Sy SHA512
.It Sy netbsd-GENERIC.gz
A kernel built from the
.Sy GENERIC
kernel configuration file.
This is meant as an example only; different
platforms may have differently named kernels.
.El
.El
.It Sy installation/
installation helper items
.Bl -tag -width "diskimage/"
.It Sy cdrom/
CD-ROM images in ISO 9660 format, created as part of
.Dq build.sh ... release ...
in
.Pa src .
.Pp
Images in this directory are bootable, and contain one a kernel,
installation tools, and rescue tools.
They do not contain installation sets, source sets, or
other components of a complete release.
.Pp
.Em "Note: These images are only present in the amd64 and i386 distributions."
.Bl -tag -width "boot-com.iso"
.It Sy MD5
.It Sy SHA512
.It Sy boot.iso
VGA console
.It Sy boot-com.iso
Serial console
.El
.It Sy diskimage/
disk images, on those platforms that provide them
.Bl -tag -width "diskimage.gz"
.It Sy MD5
.It Sy SHA512
.It Sy diskimage.gz
.El
.It Sy floppy/
floppy images, on those platforms that provide them
.Bl -tag -width "boot1.fs"
.It Sy MD5
.It Sy SHA512
.It Sy boot1.fs
.It Sy boot2.fs
.El
.It Sy instkernel/
installation kernels for platforms that can boot them directly
.Bl -tag -width netbsd.gz
.It Sy MD5
.It Sy SHA512
.It Sy netbsd.gz
.El
.It Sy miniroot/
miniroot images, on those platforms that provide them
.Bl -tag -width "miniroot.fs.gz"
.It Sy MD5
.It Sy SHA512
.It Sy miniroot.fs.gz
.El
.It Sy misc/
miscellaneous installation helper utilities, including boot selectors,
floppy writing software, other software that runs under foreign operating
systems, etc.
.Bl -tag -width "SHA512"
.It Sy MD5
.It Sy SHA512
.It Sy ...
.El
.It Sy netboot/
network boot programs
.Bl -tag -width "netboot.gz"
.It Sy MD5
.It Sy SHA512
.It Sy netboot.gz
.El
.It Sy tapeimage/
tape images, on those platforms that provide them
.Bl -tag -width "tapeboot"
.It Sy MD5
.It Sy SHA512
.It Sy tapeboot
.El
.El
.El
.El
.Sh SEE ALSO
.Xr cksum 1 ,
.Xr dd 1 ,
.Xr gzip 1 ,
.Xr split 1 ,
.Xr tar 1
.Sh HISTORY
The
.Nm
manual page first appeared in
.Nx 1.3 .