Synopsis #
FreeBSD can execute many unmodified Linux binaries through a kernel compatibility layer and a Linux userland installed under /compat/linux. This is not a virtual machine or a Linux container. Applications that require Linux namespaces, cgroups, or unsupported kernel interfaces need another approach.
The compatibility layer is available on x86 32-bit, x86 64-bit, and AArch64 systems. Confirm the application architecture and requirements before installing a userland.
Enable the compatibility service #
Enable the service at boot and start it for the current boot:
# sysrc linux_enable=YES
# service linux start
Confirm that the expected compatibility modules are loaded:
$ kldstat
The exact module list depends on the host architecture and the binary being run.
Install a Linux userland #
Install the Rocky Linux 9 base userland used by current FreeBSD documentation:
# pkg install linux_base-rl9
Files supplied by the Linux userland are installed beneath /compat/linux. Additional Linux packages may be needed for an application’s shared libraries.
Diagnose a binary that does not start #
Collect evidence before adding libraries or changing kernel settings:
$ file /path/to/program
$ ldd /path/to/program
$ sysctl compat.linux
Check the following conditions:
- The binary architecture is supported by the host.
- The Linux compatibility service is running after the current boot.
- Required shared libraries exist in the Linux userland rather than only in the FreeBSD base system.
- The application does not require Linux-only kernel facilities such as namespaces or cgroups.
ldd may fail or produce incomplete output for a binary whose interpreter or first dependency is missing. The binary’s file output and application documentation remain useful in that case.