From owner-dev-commits-doc-all@freebsd.org Tue Jan 19 02:17:10 2021 Return-Path: Delivered-To: dev-commits-doc-all@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id AE8EA4DD667 for ; Tue, 19 Jan 2021 02:17:10 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4DKXNQ4Zf7z3qtZ; Tue, 19 Jan 2021 02:17:10 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 8FEB11E5FF; Tue, 19 Jan 2021 02:17:10 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 10J2HAwv063521; Tue, 19 Jan 2021 02:17:10 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 10J2HAlY063520; Tue, 19 Jan 2021 02:17:10 GMT (envelope-from git) Date: Tue, 19 Jan 2021 02:17:10 GMT Message-Id: <202101190217.10J2HAlY063520@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Daniel Ebdrup Jensen Subject: git: f2a33a330d - main - articles/nanobsd: Add section on customizing NanoBSD MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: debdrup X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: f2a33a330d5ac238aa9b2f1c4fadb9f7265577d5 Auto-Submitted: auto-generated X-BeenThere: dev-commits-doc-all@freebsd.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: Commit messages for all branches of the doc repository List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 19 Jan 2021 02:17:10 -0000 The branch main has been updated by debdrup: URL: https://cgit.FreeBSD.org/doc/commit/?id=f2a33a330d5ac238aa9b2f1c4fadb9f7265577d5 commit f2a33a330d5ac238aa9b2f1c4fadb9f7265577d5 Author: Yoan Adida AuthorDate: 2021-01-17 10:55:07 +0000 Commit: Daniel Ebdrup Jensen CommitDate: 2021-01-19 02:16:17 +0000 articles/nanobsd: Add section on customizing NanoBSD nanobsd.sh can be passed several options, and having this documented is a good idea, as it even includes the ability to customize the third-party software on the NanoBSD image. While here, fix up some uses of applications tags, and some incorrect capitalization. Submitted by: Yoan Adida (previous version) Reviewed by: bcr, imp, wblock (some of an earlier version), Mina Galić , PauAmma Differential Revision: https://reviews.freebsd.org/D7406 --- en_US.ISO8859-1/articles/nanobsd/article.xml | 407 +++++++++++++++++++++++++-- 1 file changed, 387 insertions(+), 20 deletions(-) diff --git a/en_US.ISO8859-1/articles/nanobsd/article.xml b/en_US.ISO8859-1/articles/nanobsd/article.xml index 16623c3486..29293887af 100644 --- a/en_US.ISO8859-1/articles/nanobsd/article.xml +++ b/en_US.ISO8859-1/articles/nanobsd/article.xml @@ -28,8 +28,8 @@ This document provides information about the NanoBSD tools, which can be used to create &os; system images for embedded applications, suitable - for use on a Compact Flash card (or other mass storage - medium). + for use on a USB key, memory card or other mass + storage media. @@ -38,10 +38,11 @@ NanoBSD - NanoBSD is a tool currently - developed by &a.phk.email;. It creates a &os; system image for - embedded applications, suitable for use on a Compact Flash card - (or other mass storage medium). + NanoBSD is a tool developed by + &a.phk.email; and now maintained by &a.imp.email;. It + creates a &os; system image for embedded applications, + suitable for use on a USB key, memory card or other mass + storage media. It can be used to build specialized install images, designed for easy installation and maintenance of systems commonly called @@ -190,6 +191,148 @@ storage medium. + + + Options When Building a NanoBSD Image + + When building a NanoBSD + image, several build options can be passed to + nanobsd.sh on the + command line. These options can have a significant + impact on the build process. + + Some options are for verbosity purposes: + + + -h: prints the help + summary page. + + + + -q: makes output quieter. + + + + -v: makes output more + verbose + + + + Some other options can be used to restrict the + building process. Sometimes it is not necessary to + rebuild everything from sources, especially if an + image has already been built, and only little change + is made. + + + -k: do not build the + kernel + + + + -w: do not build world + + + + -b: do not build either + kernel and world + + + + -i: do not build a disk + image at all. As a file will not be created, it + will not be possible to &man.dd.1; it to a + storage media. + + + + -f: do not build a disk + image of the first partition (which is useful for + upgrade purposes) + + + + -n: add -DNO_CLEAN + to buildworld, + buildkernel. Also, + all the files that have already been built in a + previous run are kept. + + + + A configuration file can be used to tweak as + many elements as desired. Load it with + + The last options are: + + + -K: do not install a kernel. + A disk image without a kernel will not be able + to achieve a normal boot sequence. + + + + + + + The Complete Image Building Process + + The complete image building process is going through + a lot of steps. The exact steps taken will depend on the + chosen options when starting the script. Assuming the + script is run with no particular options, this is what + will happen. + + + run_early_customize: + commands that are defined in a supplied configuration + file. + clean_build: Just cleans + the build environment by deleting the previously built files. + make_conf_build: Assemble + make.conffrom the CONF_WORLD and + CONF_BUILD variables. + build_world: Build world. + build_kernel: Build the + kernel files. + clean_world: Clean the + destination directory. + make_conf_install: + Assemble make.conf from the CONF_WORLD + and CONF_INSTALL variables. + install_world: Install + all files built during buildworld. + install_etc: Install + the necessary files in the /etc + directory, based on the make distribution + command. + setup_nanobsd_etc: the + first configuration specific to NanoBSD + takes place at this stage. The /etc/diskless is + created and the root filesystem is defined as read-only. + install_kernel: the + kernel and modules files are installed. + run_customize: all + the customizing routines defined by the user will be called. + setup_nanobsd: a special + configuration directory layout is setup. The + /usr/local/etc gets moved to + /etc/local and a symbolic link is + created back from /etc/local to + /usr/local/etc. + prune_usr: the empty + directories from /usr are removed. + run_late_customize: + the very last custom scripts can be run at this point. + fixup_before_diskimage: + List all installed files in a metalog + create_diskimage: creates + the actual disk image, based on the disk geometries provides + parameters. + last_orders: does nothing + for now. + + @@ -280,6 +423,184 @@ details. + + There are many more configuration options that could + be relevant depending upon the kind of + NanoBSD that is desired. + + + General Customization + + There are three stages, by design, at which + it is possible to make changes that affect the + building process, just by setting up a variable in the + provided configuration file: + + + + run_early_customize: + before anything else happens. + + run_customize: after all + the standard files have been laid out + + run_late_customize: at + the very end of the process, just before the actual + NanoBSD image is built. + + + + To customize a NanoBSD image, at any of these steps, + it is best to add a specific value to one of the corresponding + variables. + + The NANO_EARLY_CUSTOMIZE variable is + used at the first step of the building process. At this point, + there is no example as to what can be done using that variable, + but it may change in the future. + + The NANO_CUSTOMIZE variable is used + after the kernel, world and etc configuration files have been + installed, and the etc files have been setup as to be a + NanoBSD installation. So it is the correct step in the + building process to tweak configuration options and add + packages, like in the cust_nobeastie example. + + The NANO_LATE_CUSTOMIZE variable is + used just before the disk image is created, so it is the very + last moment to change anything. Remember that the + setup_nanobsd routine already executed and + that the etc, conf + and cfgdirectories and subdirectories are + already modified, so it is not time to change them at this + point. Rather, it is possible to add or remove specific files. + + + + Booting Options + + There are also variables that can change the way the + NanoBSD image boots. Two options are passed to + &man.boot0cfg.8; to initialize the boot sector of the disk image: + + NANO_BOOT0CFG + NANO_BOOTLOADER + + + With NANO_BOOTLOADER a bootloader + file can be chosen. The most common possible options are between + boot0sio and boot0 + depending on whether the appliance has a serial port or not. It is best + to avoid supplying a different bootloader, but it is possible. + To do so, it is best to have checked the + &os; Handbook + chapter on the boot process. + + With NANO_BOOT0CFG, the booting + process can be tweaked, like selecting on which partition the + NanoBSD image will actually boot. + It is best to check the &man.boot0cfg.8; page before changing + the default value of this variable. One option that could be + interesting to change is the timeout of the booting procedure. + To do so, the NANO_BOOT0CFG variable can be + changed to "-o packet -s 1 -m 3 -t 36". + That way the booting process would start after approximately 2 + seconds; because it is rare that waiting 10 seconds before + actually booting is desired. + + Good to know: the NANO_BOOT2CFG + variable is only used in the cust_comconsole + routine that can be called at the + NANO_CUSTOMIZE step if the appliance has a + serial port and all console input and output has to take place through + it. Be sure to check the relevant parameters of the serial + port, as setting a bad parameter value can make it useless. + + + + + Disk Image Creation + In the end of the boot process is the disk image + creation. With this step, the NanoBSD + script provides a file that can simply be copied onto a disk + for the appliance, and that will make it boot and start. + + There are many variable that need to be set just right + for the script to produce a usable disk image. + + + The NANO_DRIVE variable must be set + to the drive name of the media at runtime. Usually, the + default value ada0, which represents the first + IDE/ATA/SATA + device on the appliance is expected to be the correct one, but + a different type of storage could also be used - like a USB + key, in which case, it would rather be da0. + + + The NANO_MEDIASIZE variable must be + set to the size (in 512 bytes sectors) of the storage media + that will be used. If you set it wrong, it is possible that + the NanoBSD image will not boot + at all, and a message at boot time will be warning about + incorrect disk geometry. + + + + + The /etc, /var, + and /tmp directories are allocated as + &man.md.4; (malloc) disks at boot time; so their sizes can be + tailored to suit the appliance needs. The NANO_RAM_ETCSIZE + variable sets the size of the /etc; and the + NANO_RAM_TMPVARSIZE variable sets the size of + both the /var and /tmp + directory, as /tmp is symbolically linked to + /var/tmp. By default, both malloc disks + sizes are set at 20MB each. They can always be changed, but + usually the /etc does not grow too much + in size, so 20MB is a good starting point, whereas the + /var and especially /tmp + can grow much larger if not careful about it. For + memory constrained systems, smaller filesystem sizes + may be chosen. + + + + As NanoBSD is + mainly designed to build a system image for an + appliance, it is assumed that the storage media used + will be relatively small. For that reason, + the filesystem that is laid out is configured to have + a small block size (4Kb) and a small fragment size (512b). + The configuration options of the filesystem can be + modified through the NANO_NEWFS + variable, but the syntax must respect the + &man.newfs.8; command format. Also, by default, the + filesystem has Soft Updates enabled. The + &os; Handbook + can be checked about this. + + + The different partition sizes can be set through the + use of NANO_CODESIZE, + NANO_CONFSIZE, and NANO_DATASIZE + as a multiple of 512 bytes sectors. + NANO_CODESIZE defines the size of the first + two image partitions: code#1 and + code#2. They have to be big enough to hold + all the files that will be produced as a result of the + buildworld and buildkernel + processes. NANO_CONFSIZE defines the size + of the configuration file partition, so it does not need to be + very big; but do not make it so small that it will not hold all + configuration files. Finally, NANO_DATASIZE + defines the size of an optional partition, that can be used + on the appliance. The last partition can be used, + for example, to keep files created on the fly on disk. + + + @@ -337,20 +658,43 @@ customize_cmd cust_etc_size Adding Packages - Packages can be added to a - NanoBSD image using a custom - function. The following function will install all the - packages located in - /usr/src/tools/tools/nanobsd/packages: - - install_packages () ( -mkdir -p ${NANO_WORLDDIR}/packages -cp /usr/src/tools/tools/nanobsd/packages/* ${NANO_WORLDDIR}/packages -cp $(which pkg-static) ${NANO_WORLDDIR}/ -chroot ${NANO_WORLDDIR} sh -c 'cd packages; /pkg-static add *;cd ..;' -rm -rf ${NANO_WORLDDIR}/packages ${NANO_WORLDDIR}/pkg-static -) -customize_cmd install_packages + Packages can be added to a NanoBSD + image, to provide specific functionalities on the + appliance. To do so, either: + + + Add the cust_pkgng to the + NANO_CUSTOMIZE variable, or + + + + Add a 'customize_cmd cust_pkgng' + command in a customized configuration file. + + + + Both methods achieve the same result: launching + the cust_pkgng routine. This routine + will go through NANO_PACKAGE_DIR + directory to find either all packages or just the list of + packages in the NANO_PACKAGE_LIST variable. + It is common, when installing applications through + pkg on a standard &os; environment, that the install + process puts configuration files, in the + usr/local/etc directory, and + startup scripts in the /usr/local/etc/rc.d + directory. So, after the required packages have been + installed, they need to be configured in order + for them to start right out of the box. To do so, + the necessary configuration files have to be installed in the + correct directories. This can be achieved by writing + dedicated routines or the generic cust_install_files + routine can be used to lay out files properly from the + /usr/src/tools/tools/nanobsd/Files directory. + Usually a statement, sometimes multiple statements, + in the /etc/rc.conf also needs to be + added for each package. + @@ -409,6 +753,29 @@ customize_cmd cust_comconsole customize_cmd cust_install_files customize_cmd cust_allow_ssh_root customize_cmd cust_nobeastie + + All the build and install compilation options can be found in + the &man.src.conf.5; man page, but not all options can or should be + used when building a NanoBSD image. + The build and install options should be defined according to the + needs of the image being built. + + For example, the ftp client and server might not be needed. + Adding WITHOUT_FTP=TRUE to a configuration file + in the CONF_BUILD section will avoid having + them built. Also, if the NanoBSD + appliance will not be used to build programs then it is possible + to add the WITHOUT_BINUTILS=TRUE in the + CONF_INSTALL section; but not + in the CONF_BUILD section as they will be + used to build the NanoBSD image. + + Not building a particular set of programs — + through a compilation option — shortens the overall building + time and lowers the required size for the disk image, + whereas not installing the same specific set of programs + does not lower the overall building time. +