diff --git a/documentation/content/en/articles/nanobsd/_index.adoc b/documentation/content/en/articles/nanobsd/_index.adoc --- a/documentation/content/en/articles/nanobsd/_index.adoc +++ b/documentation/content/en/articles/nanobsd/_index.adoc @@ -54,7 +54,7 @@ NanoBSD is a tool developed by {phk} and now maintained by {imp}. It creates a FreeBSD 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 "computer appliances". +It can be used to build specialized install images, designed for easy installation and maintenance of systems commonly called "computer appliances". Computer appliances have their hardware and software bundled in the product, which means all applications are pre-installed. The appliance is plugged into an existing network and can begin working (almost) immediately. @@ -148,16 +148,16 @@ * `-h`: prints the help summary page. * `-q`: makes output quieter. -* `-v`: makes output more verbose +* `-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 +* `-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) +* `-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. @@ -165,7 +165,10 @@ 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. +* `-K`: do not install a kernel. A disk image without a kernel will not be able to achieve a normal boot sequence. +* `-W`: do not install world. +* `-B`: do not install either kernel and world. +* `-I`: build a disk image from an existing build or install. Do not build or install kernel, world, and the etc configuration file, just create the disk image. ==== The Complete Image Building Process @@ -173,24 +176,24 @@ 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. +. `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. +. `make_conf_build`: Assemble make.conf from 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 [.filename]#/etc# directory, based on the `make distribution` command. -. `setup_nanobsd_etc`: the first configuration specific to NanoBSD takes place at this stage. The [.filename]#/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 [.filename]#/usr/local/etc# gets moved to [.filename]#/etc/local# and a symbolic link is created back from [.filename]#/etc/local# to [.filename]#/usr/local/etc#. -. `prune_usr`: the empty directories from [.filename]#/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. +. `setup_nanobsd_etc`: The first configuration specific to NanoBSD takes place at this stage. The [.filename]#/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 [.filename]#/usr/local/etc# gets moved to [.filename]#/etc/local# and a symbolic link is created back from [.filename]#/etc/local# to [.filename]#/usr/local/etc#. +. `prune_usr`: The empty directories from [.filename]#/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. === Customizing a NanoBSD Image @@ -233,7 +236,7 @@ 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_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. @@ -276,14 +279,14 @@ 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. +There are many variables 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 `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-byte 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 [.filename]#/etc#, [.filename]#/var#, and [.filename]#/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 [.filename]#/etc#; and the `NANO_RAM_TMPVARSIZE` variable sets the size of both the [.filename]#/var# and [.filename]#/tmp# directory, as [.filename]#/tmp# is symbolically linked to [.filename]#/var/tmp#. By default, both malloc disks sizes are set at 20MB each. They can always be changed, but usually the [.filename]#/etc# does not grow too much in size, so 20MB is a good starting point, whereas the [.filename]#/var# and especially [.filename]#/tmp# can grow much larger if not careful about it. For memory constrained systems, smaller filesystem sizes may be chosen. +* The [.filename]#/etc#, [.filename]#/var#, and [.filename]#/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 [.filename]#/etc#; and the `NANO_RAM_TMPVARSIZE` variable sets the size of both the [.filename]#/var# and [.filename]#/tmp# directory, as [.filename]#/tmp# is symbolically linked to [.filename]#/var/tmp#. By default, both malloc disks sizes are set at 20MB each. They can always be changed, but usually the [.filename]#/etc# does not grow too much in size, so 20MB is a good starting point, whereas the [.filename]#/var# and especially [.filename]#/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 extref:{handbook}[FreeBSD 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. +* The different partition sizes can be set through the use of `NANO_CODESIZE`, `NANO_CONFSIZE`, and `NANO_DATASIZE` as a multiple of 512-byte 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. ==== Custom Functions @@ -416,11 +419,11 @@ To install new image onto the running NanoBSD system, it is possible to use either the [.filename]#updatep1# or [.filename]#updatep2# script located in the [.filename]#/root# directory, depending from which partition is running the current system. -According to which services are available on host serving new NanoBSD image and what type of transfer is preferred, it is possible to examine one of these three ways: +According to which services are available on the host serving the new NanoBSD image and what type of transfer is preferred, it is possible to use one of these three methods: ==== Using man:ftp[1] -If the transfer speed is in first place, use this example: +If the transfer speed is most important, use this example: [source,shell] .... @@ -439,11 +442,11 @@ ==== Using man:nc[1] -Try this example if the remote host is not running neither man:ftpd[8] or man:sshd[8] service: +Try this example if the remote host is not running the man:ftpd[8] or man:sshd[8] service: [.procedure] ==== -. At first, open a TCP listener on host serving the image and make it send the image to client: +. First, open a TCP listener on the host serving the image, and make it send the image to the client: + [source,shell] .... @@ -452,9 +455,9 @@ + [NOTE] ====== -Make sure that the used port is not blocked to receive incoming connections from NanoBSD host by firewall. +Make sure that the chosen port is not blocked by the firewall to receive incoming connections from the NanoBSD host. ====== -. Connect to the host serving new image and execute [.filename]#updatep1# script: +. Connect to the host serving the new image, and execute the [.filename]#updatep1# script: + [source,shell] ....