README revision 236707
1162485Sjulian# $FreeBSD: head/tools/tools/tinybsd/README 236707 2012-06-07 09:14:28Z bz $ 2162485Sjulian 3162485Sjulian- TinyBSD 4162485Sjulian 5162485SjulianYou must read this to know how to build embedded systems with TinyBSD. 6162485Sjulian 7162485Sjulian- TinyBSD files 8162485Sjulian 9162485SjulianTinyBSD's creation conf files are available under /usr/src/tools/tools/tinybsd/conf 10162485Sjulianand the script are available under /usr/src/tools/tools/tinybsd/tinybsd. 11162485Sjulian 12162485SjulianThe system has been entirely based on the ease of image customization from 13162485SjulianPicoBSD, and the compilation script based on NanoBSD's. 14162485Sjulian 15162485Sjulian# ls /usr/src/tools/tools/tinybsd/conf 16162485Sjulianbridge/ default/ firewall/ minimal/ vpn/ wireless/ wrap/ 17162485Sjulian 18162485SjulianWe have these six pre configured images to build. On each directory we have 3 19162485Sjulianmain files in there. Let's see what each of them are: 20162485Sjulian 21162485Sjulian# ls /usr/src/tools/tools/tinybsd/conf/default 22162485SjulianTINYBSD etc/ tinybsd.basefiles 23162485Sjulian 24162485SjulianTINYBSD: Just like PicoBSD had its kernel previously compiled, we call ours 25162485SjulianTINYBSD. 26162485Sjulian 27162485Sjulian# more TINYBSD 28162485Sjulian 29162485Sjulianmachine i386 30162485Sjuliancpu I486_CPU 31162485Sjuliancpu I586_CPU 32162485Sjuliancpu I686_CPU 33162485Sjulianident TINYBSD 34162485Sjulian 35162485Sjulian#To statically compile in device wiring instead of /boot/device.hints 36162485Sjulian#hints "GENERIC.hints" #Default places to look for devices. 37162485Sjulian... 38162485Sjulian 39162485SjulianAs you can see, it's a kernel file identical to your system's, leaving only 40162485Sjulianthe task of enabling or disabling options, according to your needs. 41162485Sjulian 42162485Sjuliantinybsd.basefiles: Just like PicoBSD had its crunch.conf file to define which 43162485Sjulianfiles we'd want the new system to have, in this one we'll have all files to be 44162485Sjulianput into our embedded system, already having all available files for running 45162485Sjulianthe system well. Put in or take out the files you need according to your 46162485Sjulianneeds. Let's see it: 47162485Sjulian 48162485Sjulian# more tinybsd.basefiles 49162485Sjulian# contents of ${WORKDIR}/boot 50162485Sjulianboot/boot0 51162485Sjulianboot/boot1 52162485Sjulianboot/boot2 53162485Sjulianboot/defaults/loader.conf 54162485Sjulianboot/device.hints 55162485Sjulian... 56162485Sjulian# contents of ${WORKDIR}/bin 57162485Sjulianbin/[:bin/test 58162485Sjulianbin/cat 59162485Sjulianbin/chflags 60162485Sjulianbin/chio 61162485Sjulianbin/chmod 62162485Sjulian... 63162485Sjulian 64162485SjulianAnd so on. In case you'd want to add the binary "setkey", sitting on 65162485Sjulian/usr/sbin, you'd only need to add the following line inside the /usr/sbin part 66162485Sjulianof the file, like this: 67162485Sjulian 68162485Sjulianusr/sbin/pw 69162485Sjulianusr/sbin/pwd_mkdb 70162485Sjulianusr/sbin/setkey 71162485Sjulian 72163854Sjuliantinybsd.ports: Here you can add the applications from the FreeBSD Ports Collection 73163854Sjulianwhich you want TinyBSD ports system to install in your embedded system. You whould 74163854Sjulianlist one application per line, mentioning its category and name, like the examples: 75163854Sjulianwww/mini_httpd 76163854Sjuliannet-mgmt/rate 77163806Sjulian 78162485Sjulianetc/: This is the directory where you can put your custom /etc configuration. 79162485Sjulian 80162485Sjulian# ls /usr/src/tools/tools/tinybsd/tinybsd 81162485Sjuliantinybsd 82162485Sjulian 83162485Sjuliantinybsd: This is the script that builds the entire system. You'll hardly 84162485Sjulianneed to modify it at all. The idea is for it to create a temporary work 85162485Sjuliandirectory for it to create the entire system tree. Once done, it'll copy all 86162485Sjulianfiles listed in tinybsd.basefiles to this tree, then it'll compile a new 87162485Sjuliankernel using the definitions in the TINYBSD file, and finally copy the library 88162485Sjuliandependencies the binaries will have. We'll then populate /etc on that 89162485Sjuliantemporary tree and put in a few important default configurations inside on 90162485Sjulian/usr/src/tools/tools/tinybsd/conf/YOURCHOICE/etc/ like rc.conf, fstab and others. 91162485Sjulian 92162485SjulianFinally, we create an empty image, according to your media's specifications, 93162485Sjulianpassed on to the script on the command line, and copy the entire temporary 94162485Sjulianwork tree into the image mounted on /mnt. 95162485Sjulian 96162485Sjulian- Running TinyBSD 97162485Sjulian 98162485SjulianNow that we know how it works, it's time for us to build our own image. Let's 99162485Sjuliando that step-by-step. 100162485Sjulian 101162485Sjulian1) Choose what pre-configured image you want. 102162485Sjulian 103162485Sjulian2) Edit the TINYBSD kernel file and add/remove all options you'll need. 104162485Sjulian 105162485Sjulian3) Edit the tinybsd.basefiles file and add/remove all binaries you'll need on 106162485Sjulianyour system. 107162485Sjulian 108228975Suqs4) Copy all your /etc configuration which you want to conf/YOURIMAGE/etc/. 109162485Sjulian 110162485Sjulian5) Gather the right information on your destination media. To do that, plug in 111162485Sjulianthe device on the system and fetch the information using diskinfo(8): 112162485Sjulian 113162485Sjulian# diskinfo -v /dev/ad2 114162485Sjulianad2 115162485Sjulian 512 # sectorsize 116162485Sjulian 20060135424 # mediasize in bytes (19G) 117162485Sjulian 39179952 # mediasize in sectors 118162485Sjulian 38869 # Cylinders according to firmware. 119162485Sjulian 16 # Heads according to firmware. 120162485Sjulian 63 # Sectors according to firmware. 121162485Sjulian 122162485SjulianTo create my image, I'll need to know the media size in sectors, Heads 123162485Sjulianaccording to firmware and Sectors according to firmware. Optionally, you may 124162485Sjuliandefine the name of the generated image's file, but if you don't, it'll be 125162485Sjuliannamed tinybsd.bin. Now that we have gathered these informations through 126162485Sjuliandiskinfo, all we need to do is run tinybsd. Remember that it has 3 127162485Sjulianparameters plus 1 optional, and if you don't pass on the required ones, the 128162485Sjulianscript will warn you about it: 129162485Sjulian 130162485Sjulian# /usr/src/tools/tools/tinybsd/tinybsd 131162485SjulianWoops! 132162485Sjulian Usage: tinybsd <mediasize in sectors> <heads according to firmware> 133162485Sjulian <sectors according to firmware> <conf> [<tinybsd image name>] 134162485Sjulian 135162485Sjulian Example: tinybsd 62592 4 32 136162485Sjulian 137162485Sjulian or 138162485Sjulian 139162485Sjulian /usr/src/tools/tools/tinybsd/tinybsd 62592 4 32 wireless 140162485Sjulian 141162485Sjulian Run diskinfo(8) -v against your CF device to get correct information 142162485Sjulian about your disk. 143162485Sjulian 144162485SjulianPassing on the parameters correctly: 145162485Sjulian 146162485Sjulian# /usr/src/tools/tools/tinybsd/tinybsd 39179952 16 63 wireless 147162485SjulianCreating directory hierarchy... 148162485Sjulian./bin missing (created) 149162485Sjulian./boot missing (created) 150162485Sjulian./boot/defaults missing (created) 151162485Sjulian./boot/kernel missing (created) 152162485Sjulian./boot/modules missing (created) 153162485Sjulian./dev missing (created) 154162485Sjulian./etc missing (created) 155162485Sjulian... 156162485Sjulian 157162485SjulianIn the end, we have the generated tinybsd.bin image. Now we have to copy it to 158162485Sjulianits final destination: 159162485Sjulian 160162485Sjulian# dd if=/usr/src/tools/tools/tinybsd/tinybsd.bin of=/dev/ad2 161162485Sjulian 162162485SjulianBoot up your new embedded system and log on it. If you're ever going to modify 163162485Sjulianit, you must first remount the root slice as read-write, as it operates by 164162485Sjuliandefault on read-only mode, saving disk writes and preventing data-loss in case 165162485Sjulianof power failures. To mount it for read-write, use mount: 166162485Sjulian 167162485Sjulian# mount -u -o rw / 168162485Sjulian 169162485SjulianOnce you're done, return it to read-only mode: 170162485Sjulian 171162485Sjulian# mount -u -o ro / 172162485Sjulian 173162485SjulianThe first thing you need to do after logging for the first time, is to set a 174162485Sjulianroot password. By default, it's created with no root password. 175162485Sjulian 176162485SjulianIf you run df(1), you'll see the following partitions: 177162485Sjulian 178162485Sjulian# df 179162485SjulianFilesystem 1K-blocks Used Avail Capacity Mounted on 180162485Sjulian/dev/ad0a 29359 19446 7565 72% / 181162485Sjuliandevfs 1 1 0 100% /dev 182162485Sjulianprocfs 4 4 0 100% /proc 183162485Sjulian/dev/md0 3694 114 3286 3% /var 184162485Sjulian/dev/md1 19566 6 17996 0% /tmp 185162485Sjulian 186162485SjulianAs you can see, /var and /tmp are mounted on /dev/md0 and /dev/md1 187162485Sjulianrespectively, using memory disk devices. That's because both /var and /tmp are 188162485Sjulianwrite-intensive, and as our system works mostly on read-only mode, we'd suffer 189162485Sjulianwith writing problems there, so the memory disk approach works fine. On the 190162485Sjulianother hand, whenever you reboot the system, those directories' contents 191162485Sjulian(including logs on /var/log) will be lost. If you need to keep the contents of 192162485Sjulianthose directories, I suggest you to always upload them to another box. 193162485Sjulian 194162485SjulianThe configuration line that fires up the system script to create /var as a 195162485Sjulianmemory disk partition is "varmfs="YES"", inside 196162485Sjulian/etc/rc.conf. Besides mounting /var as a memory disk device, it also populates 197162485Sjulianits tree with the necessary subdirectories. Initially, /var is created on 198162485Sjulianmemory using only 32MB of space, and that's usually enough. Although, if you 199162485Sjulianfind it necessary to tweak that configuration, you may edit this line of 200162485Sjulian/etc/rc.conf: 201162485Sjulian 202162485Sjulianvarsize="32m" 203162485Sjulian 204162485SjulianChange 32m to whatever value you see fit (in MBytes). Take care of not using 205162485Sjulianyour entire memory for /var. 206162485Sjulian 207162485Sjulian- Ports and TinyBSD 208162485Sjulian 209162485SjulianYou can also install ports on the new system via ports. For that, you'll need 210162485Sjulianto set the PREFIX environment variable to the image's destination path. Let's 211162485Sjulianassume you want to install apache on the newly-created image. For that, I'd do 212162485Sjulianthis: 213162485Sjulian 214162485Sjulian# mdconfig -a -t vnode -f /usr/src/tools/tools/tinybsd/tinybsd.bin -u 0 215162485Sjulian 216162485SjulianThat uses mdconfig to enable the memory disk 0. 217162485Sjulian 218162485Sjulian# mount /dev/md0a /mnt 219162485Sjulian 220162485SjulianNow we've mounted the image on the temporary directory /mnt. Let's then 221162485Sjulianinstall apache via ports: 222162485Sjulian 223162485Sjulian# cd /usr/ports/www/apache13 224162485Sjulian# make install PREFIX=/mnt/usr/local 225162485Sjulian===> Vulnerability check disabled 226162485Sjulian>> apache_1.3.31.tar.gz doesn't seem to exist in /usr/ports/distfiles/. 227162485Sjulian>> Attempting to fetch from http://www.apache.org/dist/httpd/. 228162485Sjulian... 229162485Sjulian This port has installed the following startup scripts which may cause 230162485Sjulian these network services to be started at boot time. 231162485Sjulian/mnt/usr/local/etc/rc.d/apache.sh 232162485Sjulian.... 233162485Sjulian 234162485SjulianOnce the install is finished, let's verify that apache has indeed been 235162485Sjulianproperly installed under our /mnt directory: 236162485Sjulian 237162485Sjulian# cd /mnt/usr/local/sbin 238162485Sjulian# ls -lga httpd 239162485Sjulian-rwxr-xr-x 1 root wheel 252439 Jul 14 15:31 httpd 240162485Sjulian 241162485SjulianOur software has been successfully installed. You must notice that at the end 242162485Sjulianof the install, it shows the full path for the PREFIX variable we passed it. 243162485SjulianThe problem with that is that at boot-time, your system is going to look for 244162485Sjulianit under /mnt instead of /usr. So we need to edit apache's initialization 245162485Sjulianscript under /usr/local/etc/rc.d (apache.sh) and remove all instances of 246162485Sjulian"/mnt" in it. 247162485Sjulian 248162485SjulianWARNING: A very important thing to care about are dependencies. Before 249162485Sjulianinstalling anything, check to see if it has any dependencies, and that you'll 250162485Sjulianhave enough disk space on the destination system for both the application 251162485Sjulianyou're installing and its dependencies. 252162485Sjulian 253162485Sjulian- Script download 254162485Sjulian 255162485SjulianTinyBSD is still a project under heavy development, both the script itself and 256162485Sjulianits documentation. 257162485Sjulian 258162485SjulianIn case you'd like to try or use the BETA version of the script, feel free to 259236707Sbzdownload it from the project's official site at http://code.google.com/p/tinybsd/. 260