Linuxulator (Linux Emulation)

Linux binary compatibility, commonly referred to as Linuxulator, is a mechanism to run unmodified Linux binaries under FreeBSD. It does not involve virtual machines or emulation; instead, it provides the binaries with kernel interfaces identical to those provided by a real Linux kernel. Technically it's similar to the way 32-bit FreeBSD binaries run on top of 64-bit FreeBSD kernel.

There are two main ways to use Linuxulator. First, documented in the FreeBSD Handbook, uses Linux applications provided as FreeBSD ports and packages, to be installed using pkg(8). Second, described at LinuxJails, provides a full Debian/Ubuntu userspace. The former is more user-friendly, but provides a limited number of available applications. The latter method is more involved, but is handy when doing development work. Both can be used at the same time.

Status

We currently claim compatibility with Linux 3.2.0 in 12-STABLE and 5.15.0 in 14-STABLE and up.

The list of currently tested applications can be found at LinuxApps. For Steam, we suggest using linux-steam-utils package. The status of tested games can be found here. Instructions on how to watch Netflix can be found in this forum post.

Development

The goal is to implement as many Linux syscalls as possible, except for ones that are obsolete or only used for management purposes.

The canonical list of unimplemented syscalls can be found at sys/compat/linux/linux_dummy.c. Those marked UNIMPLEMENTED() are not supposed to be ever supported, usually because they have been obsoleted upstream. A somewhat stale list can be found at LinuxulatorMissing.

The Linux syscalls(2) man page lists all syscalls including references to the Linux kernel version each syscall first appeared. Note that in Linux, there are differences in syscalls supported by each architecture, there's a website tracking this.

Testing

LTP

Very easy to set up:

  1. Install devel/linux-ltp port, or linux-c7-ltp package
  2. cd into /compat/linux/opt/ltp and initiate a full LTP test run with "./runltp -p -l/var/tmp/results-log -o/var/tmp/results-output -C/var/tmp/results-failed -d/tmp"

Keep an eye on /compat/linux/tmp between tests and clean it up. You should also run "ipcs" and remove some leftover (compare before and after each run).

Current LTP results can be found here. Results for some of the older releases can be found here.

Debugging

FreeBSD's truss(1) and ktrace(1) can trace Linux binaries and decode the syscall names, but they don't support decoding Linux arguments into human-readable form. Linux strace(1) does, though - it can be installed from the linux-c7-strace package, or by apt install strace in Ubuntu chroot.

Linux core dumps are supported starting with 14.0-STABLE. Use Linux gdb to open them; you might want to consult Ubuntu documentation on debug symbol packages.

Roadmap

Bugs

A note to users: Feel free to read the following list of things to fix, but do not make conclusions out of it. The linux compatibility environment runs just fine. There are some broken edge cases that don't affect daily use. The following list is only meant for developers. Just because something is marked as a bug, it doesn't mean it doesn't work. It may be the case that some obscure error condition does not return the expected error value, or that a seldomly used feature is not implemented.

There's an umbrella ticket for tracking Linuxulator-related PRs: 247219


CategoryProject

Linuxulator (last edited 2024-09-20T12:39:46+0000 by EdwardTomaszNapierala)