1# $FreeBSD$ 2 3- TinyBSD 4 5You must read this to know how to build embedded systems with TinyBSD. 6 7- TinyBSD files 8 9TinyBSD's creation conf files are available under /usr/src/tools/tools/tinybsd/conf 10and the script are available under /usr/src/tools/tools/tinybsd/tinybsd. 11 12The system has been entirely based on the ease of image customization from 13PicoBSD, and the compilation script based on NanoBSD's. 14 15# ls /usr/src/tools/tools/tinybsd/conf 16bridge/ default/ firewall/ minimal/ vpn/ wireless/ wrap/ 17 18We have these six pre configured images to build. On each directory we have 3 19main files in there. Let's see what each of them are: 20 21# ls /usr/src/tools/tools/tinybsd/conf/default 22TINYBSD etc/ tinybsd.basefiles 23 24TINYBSD: Just like PicoBSD had its kernel previously compiled, we call ours 25TINYBSD. 26 27# more TINYBSD 28 29machine i386 30cpu I486_CPU 31cpu I586_CPU 32cpu I686_CPU 33ident TINYBSD 34 35#To statically compile in device wiring instead of /boot/device.hints 36#hints "GENERIC.hints" #Default places to look for devices. 37... 38 39As you can see, it's a kernel file identical to your system's, leaving only 40the task of enabling or disabling options, according to your needs. 41 42tinybsd.basefiles: Just like PicoBSD had its crunch.conf file to define which 43files we'd want the new system to have, in this one we'll have all files to be 44put into our embedded system, already having all available files for running 45the system well. Put in or take out the files you need according to your 46needs. Let's see it: 47 48# more tinybsd.basefiles 49# contents of ${WORKDIR}/boot 50boot/boot0 51boot/boot1 52boot/boot2 53boot/defaults/loader.conf 54boot/device.hints 55... 56# contents of ${WORKDIR}/bin 57bin/[:bin/test 58bin/cat 59bin/chflags 60bin/chio 61bin/chmod 62... 63 64And so on. In case you'd want to add the binary "setkey", sitting on 65/usr/sbin, you'd only need to add the following line inside the /usr/sbin part 66of the file, like this: 67 68usr/sbin/pw 69usr/sbin/pwd_mkdb 70usr/sbin/setkey 71 72tinybsd.ports: Here you can add the applications from the FreeBSD Ports Collection 73which you want TinyBSD ports system to install in your embedded system. You whould 74list one application per line, mentioning its category and name, like the examples: 75www/mini_httpd 76net-mgmt/rate 77 78etc/: This is the directory where you can put your custom /etc configuration. 79 80# ls /usr/src/tools/tools/tinybsd/tinybsd 81tinybsd 82 83tinybsd: This is the script that builds the entire system. You'll hardly 84need to modify it at all. The idea is for it to create a temporary work 85directory for it to create the entire system tree. Once done, it'll copy all 86files listed in tinybsd.basefiles to this tree, then it'll compile a new 87kernel using the definitions in the TINYBSD file, and finally copy the library 88dependencies the binaries will have. We'll then populate /etc on that 89temporary tree and put in a few important default configurations inside on 90/usr/src/tools/tools/tinybsd/conf/YOURCHOICE/etc/ like rc.conf, fstab and others. 91 92Finally, we create an empty image, according to your media's specifications, 93passed on to the script on the command line, and copy the entire temporary 94work tree into the image mounted on /mnt. 95 96- Running TinyBSD 97 98Now that we know how it works, it's time for us to build our own image. Let's 99do that step-by-step. 100 1011) Choose what pre-configured image you want. 102 1032) Edit the TINYBSD kernel file and add/remove all options you'll need. 104 1053) Edit the tinybsd.basefiles file and add/remove all binaries you'll need on 106your system. 107 1084) Copy all your /etc configuration which you want to conf/YOURIMAGE/etc/. 109 1105) Gather the right information on your destination media. To do that, plug in 111the device on the system and fetch the information using diskinfo(8): 112 113# diskinfo -v /dev/ad2 114ad2 115 512 # sectorsize 116 20060135424 # mediasize in bytes (19G) 117 39179952 # mediasize in sectors 118 38869 # Cylinders according to firmware. 119 16 # Heads according to firmware. 120 63 # Sectors according to firmware. 121 122To create my image, I'll need to know the media size in sectors, Heads 123according to firmware and Sectors according to firmware. Optionally, you may 124define the name of the generated image's file, but if you don't, it'll be 125named tinybsd.bin. Now that we have gathered these informations through 126diskinfo, all we need to do is run tinybsd. Remember that it has 3 127parameters plus 1 optional, and if you don't pass on the required ones, the 128script will warn you about it: 129 130# /usr/src/tools/tools/tinybsd/tinybsd 131Woops! 132 Usage: tinybsd <mediasize in sectors> <heads according to firmware> 133 <sectors according to firmware> <conf> [<tinybsd image name>] 134 135 Example: tinybsd 62592 4 32 136 137 or 138 139 /usr/src/tools/tools/tinybsd/tinybsd 62592 4 32 wireless 140 141 Run diskinfo(8) -v against your CF device to get correct information 142 about your disk. 143 144Passing on the parameters correctly: 145 146# /usr/src/tools/tools/tinybsd/tinybsd 39179952 16 63 wireless 147Creating directory hierarchy... 148./bin missing (created) 149./boot missing (created) 150./boot/defaults missing (created) 151./boot/kernel missing (created) 152./boot/modules missing (created) 153./dev missing (created) 154./etc missing (created) 155... 156 157In the end, we have the generated tinybsd.bin image. Now we have to copy it to 158its final destination: 159 160# dd if=/usr/src/tools/tools/tinybsd/tinybsd.bin of=/dev/ad2 161 162Boot up your new embedded system and log on it. If you're ever going to modify 163it, you must first remount the root slice as read-write, as it operates by 164default on read-only mode, saving disk writes and preventing data-loss in case 165of power failures. To mount it for read-write, use mount: 166 167# mount -u -o rw / 168 169Once you're done, return it to read-only mode: 170 171# mount -u -o ro / 172 173The first thing you need to do after logging for the first time, is to set a 174root password. By default, it's created with no root password. 175 176If you run df(1), you'll see the following partitions: 177 178# df 179Filesystem 1K-blocks Used Avail Capacity Mounted on 180/dev/ad0a 29359 19446 7565 72% / 181devfs 1 1 0 100% /dev 182procfs 4 4 0 100% /proc 183/dev/md0 3694 114 3286 3% /var 184/dev/md1 19566 6 17996 0% /tmp 185 186As you can see, /var and /tmp are mounted on /dev/md0 and /dev/md1 187respectively, using memory disk devices. That's because both /var and /tmp are 188write-intensive, and as our system works mostly on read-only mode, we'd suffer 189with writing problems there, so the memory disk approach works fine. On the 190other hand, whenever you reboot the system, those directories' contents 191(including logs on /var/log) will be lost. If you need to keep the contents of 192those directories, I suggest you to always upload them to another box. 193 194The configuration line that fires up the system script to create /var as a 195memory disk partition is "varmfs="YES"", inside 196/etc/rc.conf. Besides mounting /var as a memory disk device, it also populates 197its tree with the necessary subdirectories. Initially, /var is created on 198memory using only 32MB of space, and that's usually enough. Although, if you 199find it necessary to tweak that configuration, you may edit this line of 200/etc/rc.conf: 201 202varsize="32m" 203 204Change 32m to whatever value you see fit (in MBytes). Take care of not using 205your entire memory for /var. 206 207- Ports and TinyBSD 208 209You can also install ports on the new system via ports. For that, you'll need 210to set the PREFIX environment variable to the image's destination path. Let's 211assume you want to install apache on the newly-created image. For that, I'd do 212this: 213 214# mdconfig -a -t vnode -f /usr/src/tools/tools/tinybsd/tinybsd.bin -u 0 215 216That uses mdconfig to enable the memory disk 0. 217 218# mount /dev/md0a /mnt 219 220Now we've mounted the image on the temporary directory /mnt. Let's then 221install apache via ports: 222 223# cd /usr/ports/www/apache13 224# make install PREFIX=/mnt/usr/local 225===> Vulnerability check disabled 226>> apache_1.3.31.tar.gz doesn't seem to exist in /usr/ports/distfiles/. 227>> Attempting to fetch from http://www.apache.org/dist/httpd/. 228... 229 This port has installed the following startup scripts which may cause 230 these network services to be started at boot time. 231/mnt/usr/local/etc/rc.d/apache.sh 232.... 233 234Once the install is finished, let's verify that apache has indeed been 235properly installed under our /mnt directory: 236 237# cd /mnt/usr/local/sbin 238# ls -lga httpd 239-rwxr-xr-x 1 root wheel 252439 Jul 14 15:31 httpd 240 241Our software has been successfully installed. You must notice that at the end 242of the install, it shows the full path for the PREFIX variable we passed it. 243The problem with that is that at boot-time, your system is going to look for 244it under /mnt instead of /usr. So we need to edit apache's initialization 245script under /usr/local/etc/rc.d (apache.sh) and remove all instances of 246"/mnt" in it. 247 248WARNING: A very important thing to care about are dependencies. Before 249installing anything, check to see if it has any dependencies, and that you'll 250have enough disk space on the destination system for both the application 251you're installing and its dependencies. 252 253- Script download 254 255TinyBSD is still a project under heavy development, both the script itself and 256its documentation. 257 258In case you'd like to try or use the BETA version of the script, feel free to 259download it from the project's official site at http://code.google.com/p/tinybsd/. 260