Warning about new TinyBSD version
TinyBSD was totally rewritten in last version, this documentation is still in progress, if you want know what changed and how to use the new TinyBSD version, please keep reading this page.
TinyBSD Instalation
TinyBSD can be found in FreeBSD base system - /usr/src/tools/tools/tinybsd. If you downloaded the tarball you should extract it on /usr/src/tools/tools. Like the follow:
# cd /usr/src/tools/tools # tar zxfv tinybsd-CURRENT.tar.gz
TinyBSD files
TinyBSD's creation conf files are available under /usr/src/tools/tools/tinybsd and the script are available under /usr/src/tools/tools/tinybsd/tinybsd.
The system has been entirely based on the ease of image customization from PicoBSD, and the compilation script based on NanoBSD's.
# ls /usr/src/tools/tools/tinybsd/conf bridge/ default/ firewall/ minimal/ vpn/ wireless/ wrap/
We have these six pre configured images to build. On each directory we have 3 main files in there. Let's see what each of them are:
# ls /usr/src/tools/tools/tinybsd/default TINYBSD etc/ tinybsd.basefiles
We have these 3 main files in there. Let's see what each of them are:
TINYBSD: Just like PicoBSD had its kernel previously compiled, we call ours TINYBSD.
# more TINYBSD machine i386 cpu I486_CPU cpu I586_CPU cpu I686_CPU ident TINYBSD #To statically compile in device wiring instead of /boot/device.hints #hints "GENERIC.hints" #Default places to look for devices. ...
As you can see, it's a kernel file identical to your system's, leaving only the task of enabling or disabling options, according to your needs.
tinybsd.basefiles: Just like PicoBSD had its crunch.conf file to define which files we'd want the new system to have, in this one we'll have all files to be put into our embedded system, already having all available files for running the system well. Put in or take out the files you need according to your needs. Let's see it:
# more tinybsd.basefiles
# contents of ${WORKDIR}/boot
boot/boot0
boot/boot1
boot/boot2
boot/defaults/loader.conf
boot/device.hints
...
# contents of ${WORKDIR}/bin
bin/[:bin/test
bin/cat
bin/chflags
bin/chio
bin/chmod
...
And so on. In case you'd want to add the binary "setkey", sitting on
/usr/sbin, you'd only need to add the following line inside the /usr/sbin part
of the file, like this:
usr/sbin/pw
usr/sbin/pwd_mkdb
usr/sbin/setkey
etc/: This is the directory where you can put your custom /etc configuration. Note: If you need add another custom directory or files, add it on /usr/local/share/tinybsd/conf/YOUR-IMAGE/, it will be copied to your final image.
# ls /usr/src/tools/tools/tinybsd/default/etc/ fstab rc.conf
# ls /usr/src/tools/tools/tinybsd/tinybsd tinybsd
tinybsd: This is the script that builds the entire system. You'll hardly need to modify it at all. The idea is for it to create a temporary work directory for it to create the entire system tree. Once done, it'll copy all files listed in tinybsd.basefiles to this tree, then it'll compile a new kernel using the definitions in the TINYBSD file, and finally copy the library dependencies the binaries will have. We'll then populate /etc on that temporary tree and put in a few important default configurations inside on /usr/local/share/tinybsd/conf/YOURCHOICE/etc/ like rc.conf, fstab and others.
Finally, we create an empty image, according to your media's specifications, passed on to the script on the command line, and copy the entire temporary work tree into the image mounted on /mnt.
Running TinyBSD
Now that we know how it works, it's time for us to build our own image. Let's do that step-by-step.
1) Choose what pre-configured image you want.
2) Edit the TINYBSD kernel file and add/remove all options you'll need.
3) Edit the tinybsd.basefiles file and add/remove all binaries you'll need on your system.
4) Copy all your /etc configuration wich you want to conf/YOURIMAGE/etc/.
5) Gather the right information on your destination media. To do that, plug in the device on the system and fetch the information using diskinfo(8):
# diskinfo -v /dev/ad2
ad2
512 # sectorsize
20060135424 # mediasize in bytes (19G)
39179952 # mediasize in sectors
38869 # Cylinders according to firmware.
16 # Heads according to firmware.
63 # Sectors according to firmware.
To create my image, I'll need to know the media size in sectors, Heads according to firmware and Sectors according to firmware. Optionally, you may define the name of the generated image's file, but if you don't, it'll be named tinybsd.bin. Now that we have gathered these informations through diskinfo, all we need to do is run tinybsd. Remember that it has 3 parameters plus 1 optional, and if you don't pass on the required ones, the script will warn you about it:
# /usr/src/tools/tools/tinybsd/tinybsd help
Woops
Usage: tinybsd sectors=<size of media> [80000]
heads=<heads according to firmware> [4]
spt=<sectors per track according to firmware> [32]
conf=<configuration name> (see conf/name) [default]
mfsroot[=<yes|no>] [no]
image=<tinybsd image name> [tinybsd.bin]
batch[=<anything>] (do not ask interactively)
new[=<anything>] (do not read previous values)
Examples:
tinybsd sectors=65536 heads=8 spt=16 conf=wireless mfsroot=yes image=myimage.img batch
Default values are set in the program.
Environment values override defaults.
Previous values override environment values but can be disabled.
Command arguments override previous values.
Interactive values override command arguments but can be disabled.
Run diskinfo(8) -v against your CF device to get correct information
about your disk. USB keys do not need any specific geometry
Passing on the parameters correctly:
# /usr/src/tools/tools/tinybsd/tinybsd sectors=39179952 heads=16 spt=63 conf=wireless 512 byte sectors per unit? [39179952] use 'none' to clear ? Tracks per cylinder? [16] use 'none' to clear ? Sectors per track? [63] use 'none' to clear ? Configuration name? [wireless] use 'none' to clear ? Use an MFSROOT? [NO] use 'none' to clear ? Image file to generate? [tinybsd.bin] use 'none' to clear ? =====> Removing /usr/obj/tinybsdbuild =====> Removing Build Kernel Directory =====> done. =====> Alternative image name not set; defaulting to 'tinybsd.bin' =====> Creating directory hierarchy... ./bin missing (created) ./boot missing (created) ./boot/defaults missing (created) ./boot/kernel missing (created) ./boot/modules missing (created) ./dev missing (created) ./etc missing (created) ...
In the end, we have the generated tinybsd.bin image. Now we have to copy it to its final destination:
# dd if=/usr/src/tools/tools/tinybsd/tinybsd.bin of=/dev/ad2
Boot up your new embedded system and log on it. If you're ever going to modify it, you must first remount the root slice as read-write, as it operates by default on read-only mode, saving disk writes and preventing data-loss in case of power failures. To mount it for read-write, use mount:
# mount -u -o rw /
Once you're done, return it to read-only mode:
# mount -u -o ro /
The first thing you need to do after logging for the first time, is to set a root password. By default, it's created with no root password.
If you run df(1), you'll see the following partitions:
# df Filesystem 1K-blocks Used Avail Capacity Mounted on /dev/ad0a 29359 19446 7565 72% / devfs 1 1 0 100% /dev procfs 4 4 0 100% /proc /dev/md0 3694 114 3286 3% /var /dev/md1 19566 6 17996 0% /tmp
As you can see, /var and /tmp are mounted on /dev/md0 and /dev/md1 respectively, using memory disk devices. That's because both /var and /tmp are write-intensive, and as our system works mostly on read-only mode, we'd suffer with writing problems there, so the memory disk approach works fine. On the other hand, whenever you reboot the system, those directories' contents (including logs on /var/log) will be lost. If you need to keep the contents of those directories, I suggest you to always upload them to another box.
The configuration line that fires up the system script to create /var as a memory disk partition is "varmfs="YES"", inside /etc/rc.conf. Besides mounting /var as a memory disk device, it also populates its tree with the necessary subdirectories. Initially, /var is created on memory using only 32MB of space, and that's usually enough. Although, if you find it necessary to tweak that configuration, you may edit this line of /etc/rc.conf:
varsize="32m"
Change 32m to whatever value you see fit (in MBytes). Take care of not using your entire memory for /var.
- Building an image with mfsroot option:
That's a great new feature in TinyBSD-CURRENT, now you can choose this option just typing "YES" on the question prompt and the image will be build to work as MFS (Memory File System), so you can use your USB pen drive, memory stick or anything else to boot your system. When it's booted you can remove it and your system will still works, because the system was loaded on the memory. You can boot how many system you want to.
- Batch option:
If you don´t want to be asked interactively every time about your config options, just use "batch" flag in build time, like this:
tinybsd sectors=65536 heads=8 spt=16 conf=wireless batch
- Build logs:
The build logs now are written in $HOME/tinybsd.log, you can check this file to see if happened any problem or everthing works fine.
- Rewrite your config options:
All TinyBSD configurations were saved in $HOME/.tinybsd.host, to rewrite/update your config options you have to use "new" option in build flags, like the follow:
# tinybsd sectors=65536 heads=8 spt=16 conf=wireless mfsroot=yes new
Ports and TinyBSD
The TinyBSD-CURRENT was completly redone the routines for third party applications install.
The TinyBSD user have to populate the conf/<image type>/tinybsd.ports file listing the port name (in category/port) that he wants to be installed on his tinybsd system, just like:
category/application
say, for example:
www/mini_httpd
So based on this information tinybsd will have the path for the port, will cd to that directory, check for the package name with "make -V PKGNAME" and later, run pkg_info to check from its exit code wether the port is installed or not.
If not locally installed, tinybsd will "make install" this port in the local system, else (it already locally installed) tinybsd will skip to missing_dir function.
On missing_dir function it checks for all directories which are not automatically generated from BSD.local.dist, if the directory does not exist it will "mkdir -p" it under /usr/local PREFIX on TinyBSD workdir, creating on the TinyBSD image the necessary directories hierarchy.
Later it goes to copy_ports function where it checks for the applications the port installs, with pkg_info, and updates a listing excluding all things unecessary to a an embedded system, say, all data installed under www,doc,share,include,man (which just makes no sense existing on an embedded system, and would only demand useless storage space). This listing will be called /tmp/ports.files, and will contain all files that need to be added to the tinybsd system the user is building.
Later, copy_libraries function will copy all necessary libraries to the image as well, just like the main idea behind the whole TinyBSD.
Finally, deinstall_ports will deinstall the port from the local system if and only if it was not installed. It the port was already installed, obviously tinybsd won't remove it from the local system.
I believe this is the most efficient way to handle third parties applications on embedded system. At least the easiest way for the users. They can always, of course add or remove binaries or modules themselves, but now we have a subsystem on tinybsd which does the hard work. Enjoy!
Notes about the ULE scheduler
As the ULE 2.0/3.0 scheduler is included since FreeBSD 7.0, the following line may be changed in conf/$config/TINYBSD:
options SCHED_4BSD # 4BSD scheduler
to
options SCHED_ULE # ULE scheduler
Not yet tested on SMP-Machines, but the performance should be better.
Note: Some users felt that the their system was slower than usually.
Please try it yourself and paste your results below.