DOCSEARCHbyAlgolia
Submit Docs

mfsBSD Documentation

repository·master·Indexed 20 days ago

https://github.com/mmatuska/mfsbsd

A toolset for creating minimal, memory-resident FreeBSD installations. mfsBSD generates bootable images (ISO, disk images, or tarballs) that load the entire OS into RAM via the memory disk (md) subsystem. It includes mfsBSD-mini for creating small images from existing systems and supports deployment to removable media, Google Compute Engine, and remote servers. Requires FreeBSD 11 or higher and a minimum of 512MB of system RAM at runtime.

Tokens
1.7K
Snippets
7
Records
13
Agent score
69%

What's inside mfsBSD

  1. Overview of mfsBSD

    master
    mfsBSD is a set of scripts designed to generate minimal, bootable FreeBSD installations. The resulting installation is packaged into various formats (ISO, disk images, or raw archives) and is designed to be loaded entirely into system memory using the FreeBSD memory disk (md) subsystem. This makes it suitable for running from removable media like SD cards or USB keys.

  2. Generate a small bootable image with mfsBSD-mini

    master

    mfsBSD-mini is a set of scripts designed to generate a small, bootable image (ISO file or tar archive) from an existing, installed FreeBSD system. The resulting image is designed to be loaded completely into memory.

    Once generated, the image can be written directly to a bootable block device (such as a hard disk or USB stick, e.g., /dev/da0) or to a specific bootable partition (e.g., /dev/ada0p2) using the dd(1) utility.

    dd if=your_image.iso of=/dev/da0

  3. Select a FreeBSD base, world, or kernel source

    master

    mfsBSD allows you to build images from different sources:

    Using a FreeBSD Distribution

    If you have a FreeBSD distribution (e.g., from a mounted ISO), specify the path using the BASE variable: make BASE=/path/to/distribution

    Using a Custom World and Kernel

    • Existing Build: If you have already built your own world and kernel, use CUSTOM=1.
    • Automated Build: To have mfsBSD perform the make buildworld and make buildkernel steps for you, set BUILDWORLD=1 and BUILDKERNEL=1 respectively.

  4. Supported mfsBSD output file formats

    master

    mfsBSD can generate several types of bootable artifacts depending on your target deployment:

    • General purpose disk images: Ideal for SD cards, USB keys, and other removable media.
    • GCE compatible tar file artifacts: For Google Compute Engine compatibility.
    • ISO images: Standard bootable optical disc images.
    • Basic tar files: Such as .tar.gz archives.

  5. Create a minimal FreeBSD rescue CD-ROM

    master

    To create a rescue CD-ROM containing a minimal FreeBSD installation that can be ejected after booting:

    1. Modify your configuration files.
    2. Create an ISO image file (e.g., using make iso BASE=/cdrom/usr/freebsd-dist).
    3. Burn the ISO image onto a writable CD.
    4. Boot the target machine from the CD.
    make iso BASE=/cdrom/usr/freebsd-dist

  6. Install FreeBSD on a Linux server without console access

    master

    To deploy FreeBSD onto a remote Linux server where you lack physical or console access, follow these steps. Warning: Ensure your configuration files (especially network and SSH settings) are correctly modified before proceeding, otherwise you will lose remote access to the machine.

    1. Modify your configuration files to ensure SSH access is enabled and network settings are correct.
    2. Create a FreeBSD image file (e.g., using make BASE=/cdrom/usr/freebsd-dist).
    3. Write the image to the server's bootable hard drive using the dd command.
    4. Reboot the server.
    5. Access the machine via SSH.
    make BASE=/cdrom/usr/freebsd-dist

  7. Configure mfsBSD build settings

    master

    mfsBSD uses sample configuration files located in the conf/ directory. To customize your build, copy these files to new files that do not have the .sample extension and modify them as needed.

    Root Password Configuration

    By default, the root password is set to mfsroot. You can change this using the following make variables:

    • ROOTPW: Set a plain text password.
    • ROOTPW_HASH: Set a pre-hashed password.

    SSH and Remote Root Login

    You can control how root accesses the system via SSH using the PERMIT_ROOT_LOGIN variable:

    • PERMIT_ROOT_LOGIN=no: Disables remote root login.
    • PERMIT_ROOT_LOGIN=without-password: Disallows password authentication for root. If using this, you must add your SSH keys to conf/authorized_keys to maintain access.
    # Example of setting a custom root password and disabling password login
make ROOTPW=mysecretpassword PERMIT_ROOT_LOGIN=without-password

  8. Requirements for building mfsBSD

    master

    To build mfsBSD images, your build environment must meet the following criteria:

    • Operating System: FreeBSD 11 or higher (tested on i386, amd64, and arm64).
    • Distribution Files: You must provide base.txz and kernel.txz from a FreeBSD 11 or higher distribution, or use a FreeBSD 11-based (or newer) FreeBSD source tree.

  9. Create a FreeBSD rescue partition for remote re-partitioning

    master

    To set up a rescue partition on an existing FreeBSD system that allows for remote hard drive re-partitioning:

    1. Modify your configuration files.
    2. Create a .tar.gz archive (e.g., using make tar BASE=/cdrom/usr/freebsd-dist).
    3. Create a UFS partition using bsdinstall or gpart (e.g., ada0p2).
    4. Create a file system on the new partition (e.g., newfs /dev/ada0p2).
    5. Mount the partition and extract the .tar.gz file onto it.
    6. Configure a bootmanager (e.g., using gpart bootcode).
    7. Boot from the rescue system.
    make tar BASE=/cdrom/usr/freebsd-dist
newfs /dev/ada0p2
gpart bootcode -b /poot/pmbr -p /boot/gptboot -i 1 ada0

  10. Build mfsBSD-mini images

    master

    To build the mfsBSD-mini images, you must run the preparation command from the main mfsBSD directory.

    Ensure you have met the necessary build-time and runtime requirements for the main mfsBSD project before executing this command.

    make prepare-mini

  11. Include additional packages and files in the image

    master

    You can include extra software and files in your mfsBSD boot image using specific directories:

    • Packages: Copy package archives (e.g., .txz files) into the packages/ directory to have them automatically installed.
    • Custom Files: Add any files or directories to the customfiles/ directory. These will be copied recursively into the root of the boot image.

    Important: Ensure your total image size does not exceed the MFSROOT_MAXSIZE value. If your image is too large, adjust MFSROOT_MAXSIZE in your configuration.

  12. Build mfsBSD images (Examples)

    master

    Use the following command patterns to generate different types of mfsBSD outputs:

    Disk Image

    make BASE=/path/to/dist

    Bootable ISO

    make iso BASE=/path/to/dist

    Compressed Tarball

    make tar BASE=/path/to/dist

    GCE-compatible Tarball

    make gce BASE=/path/to/dist

    Specialized Editions

    • Roothack edition: make iso CUSTOM=1 BUILDWORLD=1 BUILDKERNEL=1 ROOTHACK=1
    • Custom Release (using FreeBSD Release distribution): make iso BASE=/path/to/release RELEASE=11.0-RELEASE TARGET=amd64
    # Example: Building a bootable ISO using a custom world and kernel
make iso CUSTOM=1 BUILDWORLD=1 BUILDKERNEL=1