Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
PICOBSD(8)		FreeBSD	System Manager's Manual		    PICOBSD(8)

     picobsd --	building small FreeBSD disk images


     The picobsd utility is a script which produces a minimal implementation

     The picobsd utility was originally	created	to build simple	standalone
     server, it	can be extremely useful	to developers to test their code with-
     out having	to reinstall the system.

     memory file system.  Depending on the media, it might also	contain	a num-
     ber of additional files, which can	be updated at run time,	and are	used
     to	override/update	those in the memory file system.

     file system and mounts it as root.	 It then updates the memory file sys-
     tem with files from the boot media	(if present), and executes a special-
     system runs entirely from RAM.

     The following options are available (but also check the picobsd script
     for more details).	 The most important options for	common operations are
     -src, -init, -n -and -v.

	     Put the entire contents of	the file system	in the memory file
	     system image which	is contained in	the kernel.  This is the
	     default behaviour,	and is extremely useful	as the kernel itself
	     can be loaded, using etherboot or pxeboot(8),

     -c, -clean
	     Clean the product of previous builds.

     --cfg file
	     Specify a file that contains additional config commands.

     --floppy_size size
	     (flash memories, CDROM, network booted kernels).  Note that this
	     option is overridden by the content of the	config files (config
	     in	the image tree,	or the one specified with --cfg)

	     picobsd images.

     --iso   Generate an ISO image, picobsd.iso, in addition to	the disk image

	     Also build	kernel modules.	 These are not stored on the picobsd
	     image but are left	available in the build directory.

     -n	     Make the script non-interactive, skipping the initial menu	and
	     proceeding	with the build process without requiring user input.

	     Leaves files contained in the floppy.tree on the picobsd image,
	     so	they can be loaded separately from the kernel (and updated
	     individually to customize the image).

	     Omit /boot/loader,	just rely on boot2 to load the kernel.	This
	     saves some	space but may have problems with kernels > 4MB.

     --objdir directory
	     Specify a directory with the result of a previous buildworld.
	     This saves	the need for an	--init call before creating an image.

     --src SRC_PATH
	     this option, you must also	create and initialize the subtree at
	     cross-build (see the --init option).  The source files are	unmod-
	     ified by the picobsd script.  However the source tree is not com-
	     pletely read-only,	because	config(8) expects the kernel configu-
	     ration file to be in one of its subdirectories, and also the
	     process of	initializing the usr subtree touches some parts	of the
	     might go away with	time).

	     waiting for user input before executing each of them.  Useful for
	     debugging.	 as a fully functional system.

     As	a result of extreme size limitations, the picobsd environment differs
     from the normal FreeBSD in	a number of ways:

	 As a result, only static executables may be executed.

	 specific floppy are joined together as	a single executable built with


     the following discussion, all relative path names are relative to this

     build a filesystem	without	requiring mdconfig or root privileges to mount
     a filesystem.  When run in	interactive mode (the default without the -n
     directories described below.  The base system contains a template,	called
     various kinds of network appliances.

     You can define your own PicoBSD configuration, by creating	a directory
     with a name of your choice	(e.g. FOO) which contains some of the follow-
     ing files and directories.	 For more information on how to	construct
     these files, look at one of the standard picobsd configurations as	a ref-

	     The kernel	configuration file (required).	This is	a mostly stan-
	     dard kernel configuration file, possibly stripped down by remov-
	     ing unnecessary drivers and options to reduce the kernel's	size.

	     matching MD_ROOT_SIZE option:

		   #marker    def_sz  init   MFS_inodes	   floppy_inodes
		   #PicoBSD   4200    init   8192	   32768
		   options MD_ROOT_SIZE=4200	  # same as def_sz

	     provides a	few other details on how to build the image.

	     directories containing program sources, the list of binaries to
	     this file.

	     The following issues are particularly important when dealing with
	     picobsd configurations:

	     +o	 We can	pass build options to those makefiles which understand
		 achieved with a line of the form

		       buildopts -DNO_PAM -DRELEASE_CRUNCH ...

	     +o	 When providing	the list of directories	where source files
		 are, it is convenient to list the following entry first:

		       srcdirs /usr/src/release/picobsd/tinyware

		 so that picobsd-specific versions of the programs will	be
		 found there.

		 of the	directory where	the picobsd configuration resides
		 within	a configuration, e.g.

		       srcdirs @__CWD__@/src

	     most important variables here are:

		      Should be	set to the list	of devices to be created in
		      the /dev directory of the	image (it is really the	argu-
		      ment passed to MAKEDEV(8), so refer to that manpage for
		      the names).

		      fd_size is set to	1440 which produces an image suitable
		      for a standard floppy.

		      equal to 2880.  If you are planning to dump the image
		      disk), you are not restricted to one of the standard
		      floppy sizes.  Using a large image size per se does not
		      waste RAM	at runtime, because only the files that	are
		      actually loaded from the image contribute	to the memory

		      Contains a list of files to be imported in the floppy
		      tree.  Absolute names refer to the standard file system,
		      relative names refer to the root of the source tree
		      this option if you want to import	files such as shared
		      libraries, or databases, without having to replicate
		      them first in your configuration under the floppy.tree/

	     to	be copied (optional).

	     Local additions to	the standard floppy tree (optional).  The con-
	     tent of this subtree will be copied as-is into the	floppy image.

	     Same as above, but	site-specific (optional).

     picobsd script.

     RELENG_4 sources, you can do the following:

	   cd <some_empty_directory>
	   mkdir FOO
	   picobsd --src FOO/src -n -v bridge

     picobsd.bin, plus the products of the compilation in other	directories.
     If	you want to modify the source tree in FOO/src, a new image can be pro-
     duced by simply running

	   picobsd --src FOO/src -n -v bridge

     whereas if	the change affects include files or libraries you first	need
     to	update them, e.g. by re-running


     as	you would normally do for any change of	this kind.

   Floppy Install
     installed with a simple

	   dd if=picobsd.bin of=/dev/rfd0

     and the floppy is ready to	boot.

   Hard	Disk Install
     volume or one of the slices):

	   dd if=picobsd.bin of=/dev/ada2
	   dd if=picobsd.bin of=/dev/ada2s3
	   dd if=picobsd.bin of=/dev/ada2 oseek=NN

     work in the same way as for a floppy.

     will only have success if the partition does not contain a	valid diskla-
     bel, otherwise the	kernel will likely prevent overwriting the label.  In
     of	the partition (which you can determine using gpart(8)).	 Note that
     not ask why!).  One way to	do this	is

	   disklabel -w	ada0s2 auto
	   disklabel -e	ada0s2

     e.g. if the image has 2.88MB (5760	sectors) you need to enter the follow-
     ing line for the partition:

	   a: 5760   0	  4.2BSD   512	 4096


   CDROM Install
     picobsd can produce an ISO	image named picobsd.iso, which does not	use
     ``El Torito'' emulation, so it has	no size	restrictions.  Installing
     means just	burning	a media	with the file.

   Booting From	The Network
     this purpose you should use the uncompressed kernel which is available as
     a byproduct of the	compilation.  Refer to the documentation for network
     FreeBSD kernel.

     To	boot picobsd, insert the floppy	and reset the machine.	The boot pro-
     cedure is similar to the standard FreeBSD boot.  Booting from a floppy is

     You can also use etherboot	to load	the preloaded, uncompressed kernel

     partition)	and possibly override the contents of the root file system
     longer used, unless the user specifically does it.

     passed to the main	user configuration script, /etc/rc.conf, which is sup-
     posed to override the value of a number of	configuration variables	which
     variable to create	different configurations from the same file.  After
     of	this it	configures network interfaces and optionally calls the fire-
     wall configuration	script,	/etc/rc.firewall, where	the user can store his
     own firewall configuration.

     not used anymore after /etc/rc1 takes control, again, unless you explic-
     itly request it.

     to	store and/or customize,	thus saving space.  Among the files to config-
     ure we have the following:

	     In	addition to this, the picobsd version of this file also	con-
	     tains a mapping between Ethernet (MAC) addresses and hostnames,
	     as	follows:

		   #ethertable	   start of the	ethernet->hostname mapping
		   # mac_address	   hostname
		   # 12:34:56:*		   pallino
		   # *			   this-matches-all


	     enter a hostname and IP address for the system, and this informa-
	     simply store them on disk later.

	     avoid the request.

	     This file contains	a number of variables which control the	opera-
	     tion of the system, such as interface configuration, router set-
	     up, network service startup, etc.	For the	exact list and meaning
	     of	these variables	see /etc/rc.conf.defaults.

	     It	is worth mentioning that some of the variables let you over-
	     write the contents	of some	files in /etc.	This option is avail-
	     able at the moment	for /etc/host.conf and /etc/resolv.conf, whose
	     contents are generally very short and suitable for	this type of
	     updating.	In case	you use	these variables, remember to use new-
	     lines as appropriate, e.g.

		   host_conf="#	this goes into /etc/host.conf

	     Although not mandatory, in	this file you should only set the
	     variables indicated in /etc/rc.conf.defaults, and avoid starting
	     services which depend on having the network running.  This	can be
	     /etc/rc.firewall script will be run after configuring the network
	     interfaces, so you	can set	up your	firewall and safely start net-
	     work services or enable things such as routing and	bridging.

	     and hostname contains the name assigned to	the host.

     disk (mounting and	unmounting the latter around the operation).

     If	invoked	without	arguments, update edits	and saves rc.conf,
     rc.firewall, and master.passwd.

     If	one of the arguments is	/etc (the directory name alone), then the com-
     mand saves	to disk	(without editing) all the files	in the directory for

     crunchgen(1), mdconfig(8),	nanobsd(8), swapon(8)

     Andrzej Bialecki <>, with	subsequent work	on the scripts
     by	Luigi Rizzo <> and others.  Man page and Makefiles
     created by	Greg Lehey <>.

     Documentation is still incomplete.

FreeBSD	Ports 11.2		October	1, 2013		    FreeBSD Ports 11.2


Want to link to this manual page? Use this URL:

home | help