diff --git a/en/projects/nanobsd/Makefile b/en/projects/nanobsd/Makefile new file mode 100644 index 0000000000..78a6e42d79 --- /dev/null +++ b/en/projects/nanobsd/Makefile @@ -0,0 +1,17 @@ +# NanoBSD: packing up FreeBSD for appliances. +# +# $FreeBSD$ + +MAINTAINER= phk + +.if exists(../Makefile.conf) +.include "../Makefile.conf" +.endif +.if exists(../Makefile.inc) +.include "../Makefile.inc" +.endif + +DOCS= index.sgml +DATA= style.css + +.include "${WEB_PREFIX}/share/mk/web.site.mk" diff --git a/en/projects/nanobsd/index.sgml b/en/projects/nanobsd/index.sgml new file mode 100644 index 0000000000..082366e2b5 --- /dev/null +++ b/en/projects/nanobsd/index.sgml @@ -0,0 +1,191 @@ + + + + %includes; + + + + + + %developers; + +]> + + + &header; + +
+ NanoBSD is designed to put a possibly reduced FreeBSD system + on a Compact Flash card (or other mass storage of your choice) + in a way which is suitable for use in appliance like applications. +
+ The mass storage is divided into three parts, two image partitions + and a configuration file partition, which normally are mounted + only read-only. This means that it is safe to pull the power + plug on a NanoBSD machine and that Flash based storage is not worn + out with filesystem metadata writes. +
+ Having two image partitions means that it is possible to download + a new image while the system is running, reboot to run that new + image and if that fails somehow, it is still possible to switch + back to the old image partition. + +
+ The Nanobsd build system lives in src/tools/tools/nanobsd + and consists of makefiles and shell scripts which drives use of + the Makefiles in the FreeBSD source tree to create a NanoBSD image. +
+ The necessary commands to build a NanoBSD image are: +
+ Depending on your machine, this will take from half an hour + to some hours. The process is split into a sequence of + steps, and if errors happen underway it is generally, but + not always possible to rectify the error and type make + again to complete the missing steps. +
+ If you want to start from scratch you have to delete all files + and directories in the NanoBSD directory which start with an + underscore: rm -rf _.* +
+ Here is a breakdown of the files and directories which NanoBSD + builds, in the order they are built: +
The output from running make buildworld in the + source tree. +
If this step fails, the output is instead left + in the file _.bw.tmp +
The output from running make installworld DESTDIR=_.w + in the source tree. +
If this step fails, the output is instead left + in the file _.iw.tmp +
This is the directory tree into which installworld installs. +
The output from running make distribute DESTDIR=_.w + in the source trees etc subdirectory. +
If this step fails, the output is instead left + in the file _.di.tmp +
The output from running make buildkernel + in the source tree. +
If this step fails, the output is instead left + in the file _.bk.tmp +
The output from running make installkernel DESTDIR=_.w + in the source tree. +
If this step fails, the output is instead left + in the file _.ik.tmp +
The output from running the customization scripts in the + Customize subdirectory. +
If this step fails, the output is instead left + in the file _.cs.tmp +
The output from building the image file containing the filesystem + images of the finished NanoBSD. +
If this step fails, the output is instead left + in the file _.md.tmp +
Mtree(8) output from the files installed into the code patitions + in the NanoBSD image. +
Image file containing the full disk image. This is the image + file you will put on the Compact Flash or other mass storage from + which your target platform boots. +
Image file containing just the code partition image. This is + image you will download to update a running system. +
+ This is where things get interesting, and where you will be spending + your time when developing with NanoBSD. +
+ The first thing you need to configure is how much storage + you have on your mass storage media. NanoBSD can work out + of the box with as little as 64MB, and if you spend time on + it, you can cut it down even further until you end up with + an installed system with just the kernel and two or three + files in userland. +
+ You can determine the size of the storage media with the + diskinfo(8) command or by examining dmesg(8) or console + output during boot. +
+ Once you know the number of sectors on the entire media + insert this in the Makefile in the definitions of + SECTS or pass it as a command line option to make(1) when + you build NanoBSD: MAKE SECTS=100000. +
+ Some platforms need to use CHS addressing in the bootblocks + in which case you need to set the HD and SC + values in the Makefile as well. These can also be found from + diskinfo(8), dmesg(8) or console output. Even if your current + platform does not need these to be set, it is always a good idea + to do it anyway. +
+ Please be aware that you have to get the values used on the + target platform. Putting a CF card in a USB-CF adapter will + not result in the correct values for the geometry. +
+ The DATASIZEparameter controls how many sectors are + used for the configuration partition. Typically you will need + very little, but depending on your application and how you + organize things, you may want to set this higher or lower. + Obviously, the space you use for the configuration partition + is not available for the image partitions. +
+ You can run scripts which will customize the NanoBSD image + by listing them in the CUSTOMIZE variable in the + Makefile. The scripts will be given arguments to show them + where everything is and they can do pretty much anything + they want to do to the directory tree. +
+ The make.conf file overrides the usual /etc/make.conf + and by default disables a lot of FreeBSD from the build in order to + make it fit on 64MB devices. Go through the list and decide if there + are anything you want or do not want in your NanoBSD image. +
+ You may also want to use a kernel other than GENERIC. + Put the config file in ../../../sys/i386/conf and + set the name in KERNCONF in make.conf. +
+ You can save a couple of megabytes of space in your image by + removing all the bits you will not need. (How many appliances + need support for nine different RAID controllers ?) +
+ By default the follwing customize scripts are provided (but not + called unless you list them in CUSTOMIZE. +
+ Disables getty(8) on the VGA devices and enables console in the + COM1 serial port. +
+ Disables the "beastie-menu" in the bootloader. +
+ Disables ata-dma for the Soekris NET4801 because early hardware + versions do not support DMA on the CF socket. + + + &footer; + +