DOCSEARCHbyAlgolia
Submit Docs

FreeBSD Documentation

repository·main·Indexed 18 days ago

https://github.com/freebsd/freebsd-doc

Source files and toolchain configurations used to generate official FreeBSD manuals, books, and web documentation. Includes the committers-guide covering administrative details, OpenPGP authentication, Kerberos/LDAP password management, commit bit authority, and Git workflows for the src, doc, and ports repositories.

Tokens
139.2K
Snippets
465
Records
642
Agent score
63%

What's inside freebsd-doc

  1. Access FreeBSD Foundation resources and support

    main

    The FreeBSD Foundation is a 501(c)(3) non-profit that supports FreeBSD through software development, infrastructure, security, and legal representation. Developers and organizations can engage with the Foundation through several channels:

    • Technology Roadmap: View the long-term technical direction of the project.
    • Partnership Program: Explore the Foundation Partnership Program for organizational support.
    • Donations: Support software development and infrastructure via direct donations.
    • Events: Participate in developer summits and community events.
    • FreeBSD Journal: Access technical articles and community news.

    Contact Information: Deb Goodkin deb@FreeBSDFoundation.org

  2. Use framework-kmod for dynamic screen dimming

    main

    The framework-kmod module is designed for power efficiency in lightweight setups. It automatically dims the screen after a configurable timeout of inactivity and restores brightness immediately upon detecting user input via evdev[4].

    Requirements:

    • drm-kmod drivers must be loaded in advance.
    • Best suited for tty consoles or simple window managers (e.g., i3, dwm).

    Links:

  3. OpenStack on FreeBSD Project Overview

    main

    The OpenStack on FreeBSD project aims to port key OpenStack components to FreeBSD so that FreeBSD can function as an OpenStack host. While users can currently spawn FreeBSD instances on OpenStack cloud platforms, the OpenStack control plane cannot yet run on FreeBSD hosts. The project focuses on porting core services to enable resource orchestration, such as provisioning and managing CHERI-enabled Morello boards.

    Current Porting Status of Components:

    • Keystone (identity service)
    • Glance (image service)
    • Placement (resource tracking and inventory service)
    • Neutron (networking service)
    • Nova (compute service)

    Key Technical Challenges & Implementation Details:

    • Neutron Networking: Neutron's design traditionally relies on Linux network namespaces for DHCP servers. On FreeBSD, the project is working to adapt alternatives like vnet.
    • Privilege Separation: The oslo.privsep library is rooted in Linux capabilities. Current implementations use workarounds to bypass Linux-specific capability operations, which may result in non-standard configurations or code in the current development state.
    • Planned Lifecycle Integration: Future development focuses on completing the VM lifecycle via DHCP integration, FreeBSD bridge drivers/agents, and Bhyve + Libvirt integration.

  4. Overview of FreeBSD Jail Types

    main

    FreeBSD Jails provide operating system-level virtualization. There are several distinct types based on how they handle the base system and networking:

    • Thick Jails: A complete copy of the FreeBSD base system is replicated within the jail. They offer high isolation and independence but have higher resource overhead.
    • Thin Jails: Share the base system from a template using OpenZFS snapshots or NullFS mounts. They are resource-efficient and faster to deploy. NullFS thin jails share a live, read-only base system, meaning updates to the template affect all jails.
    • Service Jails (FreeBSD 15.0+): Share the complete filesystem tree directly with the host (path = /). They provide minimal configuration for confining daemons but offer reduced filesystem isolation.
    • VNET Jails: A type of jail (can be Thick or Thin) that provides a virtualized, isolated network stack, including its own IP addresses, routing tables, and interfaces.
    • Linux Jails: Use a compatibility layer to run Linux binaries and applications within the FreeBSD kernel.

  5. Overview of OCI Containers on FreeBSD

    main

    OCI (Open Container Initiative) containers on FreeBSD use FreeBSD jails as the underlying virtualization technology. This allows users to use industry-standard tooling like Podman, Buildah, and Skopeo to describe, distribute, and run containerized workloads.

    Key analogies for FreeBSD users:

    • Container Image: Similar to the FreeBSD base.txz tarball.
    • Containerfile: Similar to a jail.conf file.
    • Running a container: Similar to using the jail command, but via the podman suite.

  6. Introduction to USES Macros

    main

    In FreeBSD Ports, USES macros are used to declare requirements and settings for a port. They simplify the process of adding dependencies, changing build behaviors, and adding metadata by selecting preset values.

    Syntax

    • Multiple values: Separate values with spaces.
    • Arguments: Append arguments to a value using a colon (:).
    • Multiple arguments: Separate arguments with commas (,).

    Example usage patterns:

    # Multiple values
USES= bison perl

# Adding an argument
USES= tar:xz

# Adding multiple arguments
USES= drupal:7,theme

# Mixing values and arguments
USES= pgsql:9.3+ cpe python:2.7,build
    USES= pgsql:9.3+ cpe python:2.7,build

  7. How the mac_do, mdo, and setcred components work together

    main

    The project provides a mechanism for controlled process credential transitions without relying on setuid executables. It uses the Mandatory Access Control (MAC) framework to authorize credential changes based on administrator-defined rules.

    Core components:

    • mac_do(4): A kernel module that evaluates credential transition requests against configured rules and authorizes those that match.
    • mdo(1): A userland mediator program. It acts as the interface for processes that want to launch new processes with different credentials, communicating the request to mac_do(4).
    • setcred(2): A new system call that allows userland to request multiple credential changes (UID, GID, and groups) atomically. This atomicity allows mac_do(4) to validate the entire transition from the initial state to the final desired state in a single decision.

    Currently, mac_do(4) only grants transitions for processes spawned from the /usr/bin/mdo executable.

  8. Understand Mandatory Access Control (MAC) in FreeBSD

    main

    Mandatory Access Control (MAC) is a security framework in FreeBSD that allows administrators to implement pluggable security policies. Unlike Discretionary Access Control (DAC), where users control access to their own files, MAC enforcement is performed by the operating system and administrators based on predefined rules.

    Key concepts include:

    • Subject: An active entity (like a user process or thread) that causes information to flow between objects.
    • Object: A data container or system resource (like a file, directory, or device) through which information flows.
    • Label: A security attribute applied to subjects and objects that describes their security properties (e.g., integrity or secrecy).
    • Policy: A collection of rules defining how subjects and objects interact based on their labels.

    Warning: Improper MAC configuration can lead to loss of system access or inability to use Xorg. MAC augments existing security but is not a complete security solution on its own.

  9. Understand the Biba Integrity Policy

    main

    The Biba policy provides hierarchical integrity levels to prevent unauthorized modification of data. It follows the principle of no write up, no read down (the opposite of MLS).

    Core Rules:

    • Subject Write Access: A subject can write to objects on its own level or below, but not above.
    • Subject Read Access: A subject can read objects on its own level or above, but not below.

    Integrity Labels:

    • biba/low: The lowest integrity level. Setting this on objects/subjects blocks write access to biba/high objects/subjects but allows reading.
    • biba/equal: Used for objects exempt from the policy.
    • biba/high: Permits writing to objects at a lower label, but does not permit reading that object. Recommended for objects affecting system-wide integrity.

  10. Handle bundled libraries in ports

    main

    Bundling third-party libraries inside a distribution is generally discouraged due to security, bug, and licensing risks.

    Best Practices:

    1. Use the unbundled version by adding a LIB_DEPENDS entry.
    2. If bundling is strictly necessary (e.g., for emulators like Wine), add BUNDLE_LIBS=yes to the Makefile. This prevents pkg from computing provided libraries. Note: Always consult the portmgr before using this.

    Risks of bundling:

    • Security: Vulnerabilities in the upstream library may not be patched in the bundled version.
    • Bugs: Divergent code makes patching harder and duplicates effort.
    • Symbol Collision: Can cause runtime errors if a system-wide version of the same library is loaded.

  11. Understand the security and isolation model of Service Jails

    main

    Service jails provide a lightweight way to isolate rc.d services.

    Isolation Capabilities:

    • Process Visibility: Services in a jail cannot see processes outside the jail.
    • Network Access: Restricted network access by default.
    • Filesystem: Restricted mounting permissions.
    • Sysvipc: Isolated System V IPC.

    Inheritance and Extensions:

    • Filesystem: Inherits the filesystem of the parent host or jail.
    • Advanced Configuration: Through additional configuration, service jails can be set up to inherit parent IPs, sysvipc, and memory page locking, or to utilize the vmm[4] (bhyve) virtual machine monitor.

    Security Note: Service jails do not provide the same level of security as a manual jail setup that uses a separate filesystem and dedicated IP/VNET. They are intended as an easier-to-configure alternative that still provides benefits like hiding processes of the same user.

  12. FreeBSD Container Image Tagging Strategies

    main

    Choose your image tag based on whether you prioritize stability (Production) or automatic updates (CI/CD).

    Immutable Tags (Recommended for Production)

    These tags never change, ensuring reproducibility even after security patches.

    • major.minor (e.g., 14.4): Specific FreeBSD RELEASE.
    • major.minor.pX (e.g., 14.4p1): Specific patch level.
    • major.snapYYYYMMDDHHMMSS: A specific snapshot build.

    Mutable Tags (Recommended for CI/CD)

    These tags are updated to track the latest releases or snapshots.

    • major (e.g., 15): Always the latest supported RELEASE in the 15.x ABI.
    • major.snap (e.g., 15.snap): Tracks the latest developer snapshot (STABLE/CURRENT). Use with caution as it may break.