diff --git a/documentation/content/en/books/handbook/introduction/_index.adoc b/documentation/content/en/books/handbook/introduction/_index.adoc index 976fb7f174..77fa5f9303 100644 --- a/documentation/content/en/books/handbook/introduction/_index.adoc +++ b/documentation/content/en/books/handbook/introduction/_index.adoc @@ -1,289 +1,290 @@ --- title: Chapter 1. Introduction part: Part I. Getting Started prev: books/handbook/parti next: books/handbook/bsdinstall description: This chapter covers various aspects of the FreeBSD Project, such as its history, goals, development model, and so on tags: ["introduction", "synopsis", "about", "Who Uses FreeBSD", "goals", "history"] showBookMenu: true weight: 3 path: "/books/handbook/" --- [[introduction]] = Introduction :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 1 :partnums: :source-highlighter: rouge :experimental: :images-path: books/handbook/introduction/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] [[introduction-synopsis]] == Synopsis Thank you for your interest in FreeBSD! The following chapter covers various aspects of the FreeBSD Project, such as its history, goals, development model, and so on. After reading this chapter you will know: * How FreeBSD relates to other computer operating systems. * The history of the FreeBSD Project. * The goals of the FreeBSD Project. * The basics of the FreeBSD open-source development model. * And of course: where the name "FreeBSD" comes from. [[nutshell]] == Welcome to FreeBSD! FreeBSD is an Open Source, standards-compliant Unix-like operating system for x86 (both 32 and 64 bit), ARM(R), AArch64, RISC-V(R), MIPS(R), POWER(R), PowerPC(R), and Sun UltraSPARC(R) computers. It provides all the features that are nowadays taken for granted, such as preemptive multitasking, memory protection, virtual memory, multi-user facilities, SMP support, all the Open Source development tools for different languages and frameworks, and desktop features centered around X Window System, KDE, or GNOME. Its particular strengths are: * _Liberal Open Source license_, which grants you rights to freely modify and extend its source code and incorporate it in both Open Source projects and closed products without imposing restrictions typical to copyleft licenses, as well as avoiding potential license incompatibility problems. * _Strong TCP/IP networking_ - FreeBSD implements industry standard protocols with ever increasing performance and scalability. This makes it a good match in both server, and routing/firewalling roles - and indeed many companies and vendors use it precisely for that purpose. * _Fully integrated OpenZFS support_, including root-on-ZFS, ZFS Boot Environments, fault management, administrative delegation, support for jails, FreeBSD specific documentation, and system installer support. * _Extensive security features_, from the Mandatory Access Control framework to Capsicum capability and sandbox mechanisms. * _Over 30 thousand prebuilt packages_ for all supported architectures, and the Ports Collection which makes it easy to build your own, customized ones. * _Documentation_ - in addition to Handbook and books from different authors that cover topics ranging from system administration to kernel internals, there are also the man:man[1] pages, not only for userspace daemons, utilities, and configuration files, but also for kernel driver APIs (section 9) and individual drivers (section 4). * _Simple and consistent repository structure and build system_ - FreeBSD uses a single repository for all of its components, both kernel and userspace. This, along with an unified and easy to customize build system and a well thought out development process makes it easy to integrate FreeBSD with build infrastructure for your own product. * _Staying true to Unix philosophy_, preferring composability instead of monolithic "all in one" daemons with hardcoded behavior. * _Binary compatibility_ with Linux, which makes it possible to run many Linux binaries without the need for virtualisation. FreeBSD is based on the 4.4BSD-Lite release from Computer Systems Research Group (CSRG) at the University of California at Berkeley, and carries on the distinguished tradition of BSD systems development. In addition to the fine work provided by CSRG, the FreeBSD Project has put in many thousands of man-hours into extending the functionality and fine-tuning the system for maximum performance and reliability in real-life load situations. FreeBSD offers performance and reliability on par with other Open Source and commercial offerings, combined with cutting-edge features not available anywhere else. [[os-overview]] === What Can FreeBSD Do? The applications to which FreeBSD can be put are truly limited only by your own imagination. From software development to factory automation, inventory control to azimuth correction of remote satellite antennae; if it can be done with a commercial UNIX(R) product then it is more than likely that you can do it with FreeBSD too! FreeBSD also benefits significantly from literally thousands of high quality applications developed by research centers and universities around the world, often available at little to no cost. Because the source code for FreeBSD itself is freely available, the system can also be customized to an almost unheard of degree for special applications or projects, and in ways not generally possible with operating systems from most major commercial vendors. Here is just a sampling of some of the applications in which people are currently using FreeBSD: * _Internet Services:_ The robust TCP/IP networking built into FreeBSD makes it an ideal platform for a variety of Internet services such as: ** Web servers ** IPv4 and IPv6 routing ** Firewalls and NAT ("IP masquerading") gateways ** FTP servers ** Email servers ** And more... * _Education:_ Are you a student of computer science or a related engineering field? There is no better way of learning about operating systems, computer architecture and networking than the hands on, under the hood experience that FreeBSD can provide. A number of freely available CAD, mathematical and graphic design packages also make it highly useful to those whose primary interest in a computer is to get _other_ work done! * _Research:_ With source code for the entire system available, FreeBSD is an excellent platform for research in operating systems as well as other branches of computer science. FreeBSD's freely available nature also makes it possible for remote groups to collaborate on ideas or shared development without having to worry about special licensing agreements or limitations on what may be discussed in open forums. * _Networking:_ Need a new router? A name server (DNS)? A firewall to keep people out of your internal network? FreeBSD can easily turn that unused PC sitting in the corner into an advanced router with sophisticated packet-filtering capabilities. * _Embedded:_ FreeBSD makes an excellent platform to build embedded systems upon. With support for the ARM(R), MIPS(R) and PowerPC(R) platforms, coupled with a robust network stack, cutting edge features and the permissive extref:{faq}[BSD license, bsd-license-restrictions] FreeBSD makes an excellent foundation for building embedded routers, firewalls, and other devices. * _Desktop:_ FreeBSD makes a fine choice for an inexpensive desktop solution using the freely available X11 server. FreeBSD offers a choice from many open-source desktop environments, including the standard GNOME and KDE graphical user interfaces. FreeBSD can even boot "diskless" from a central server, making individual workstations even cheaper and easier to administer. * _Software Development:_ The basic FreeBSD system comes with a full suite of development tools including a full C/C++ compiler and debugger suite. Support for many other languages are also available through the ports and packages collection. FreeBSD is available to download free of charge, or can be obtained on either CD-ROM or DVD. Please see crossref:mirrors[mirrors, Obtaining FreeBSD] for more information about obtaining FreeBSD. [[introduction-nutshell-users]] === Who Uses FreeBSD? FreeBSD has been known for its web serving capabilities - sites that run on FreeBSD include https://news.ycombinator.com/[Hacker News], http://www.netcraft.com/[Netcraft], http://www.163.com/[NetEase], https://signup.netflix.com/openconnect[Netflix], http://www.sina.com/[Sina], http://www.sony.co.jp/[Sony Japan], http://www.rambler.ru/[Rambler], http://www.yahoo.com/[Yahoo!], and http://www.yandex.ru/[Yandex]. FreeBSD's advanced features, proven security, predictable release cycle, and permissive license have led to its use as a platform for building many commercial and open source appliances, devices, and products. Many of the world's largest IT companies use FreeBSD: * http://www.apache.org/[Apache] - The Apache Software Foundation runs most of its public facing infrastructure, including possibly one of the largest SVN repositories in the world with over 1.4 million commits, on FreeBSD. * http://www.apple.com/[Apple] - OS X borrows heavily from FreeBSD for the network stack, virtual file system, and many userland components. Apple iOS also contains elements borrowed from FreeBSD. * http://www.cisco.com/[Cisco] - IronPort network security and anti-spam appliances run a modified FreeBSD kernel. * http://www.citrix.com/[Citrix] - The NetScaler line of security appliances provide layer 4-7 load balancing, content caching, application firewall, secure VPN, and mobile cloud network access, along with the power of a FreeBSD shell. * https://www.emc.com/isilon[Dell EMC Isilon] - Isilon's enterprise storage appliances are based on FreeBSD. The extremely liberal FreeBSD license allowed Isilon to integrate their intellectual property throughout the kernel and focus on building their product instead of an operating system. * http://www.quest.com/KACE[Quest KACE] - The KACE system management appliances run FreeBSD because of its reliability, scalability, and the community that supports its continued development. * http://www.ixsystems.com/[iXsystems] - The TrueNAS line of unified storage appliances is based on FreeBSD. * http://www.juniper.net/[Juniper] - The JunOS operating system that powers all Juniper networking gear (including routers, switches, security, and networking appliances) is based on FreeBSD. Juniper is one of many vendors that showcases the symbiotic relationship between the project and vendors of commercial products. Improvements generated at Juniper are upstreamed into FreeBSD to reduce the complexity of integrating new features from FreeBSD back into JunOS in the future. * http://www.mcafee.com/[McAfee] - SecurOS, the basis of McAfee enterprise firewall products including Sidewinder is based on FreeBSD. * http://www.netapp.com/[NetApp] - The Data ONTAP GX line of storage appliances are based on FreeBSD. In addition, NetApp has contributed back many features, including the new BSD licensed hypervisor, bhyve. * http://www.netflix.com/[Netflix] - The OpenConnect appliance that Netflix uses to stream movies to its customers is based on FreeBSD. Netflix has made extensive contributions to the codebase and works to maintain a zero delta from mainline FreeBSD. Netflix OpenConnect appliances are responsible for delivering more than 32% of all Internet traffic in North America. * http://www.sandvine.com/[Sandvine] - Sandvine uses FreeBSD as the basis of their high performance real-time network processing platforms that make up their intelligent network policy control products. * http://www.sony.com/[Sony] - The PlayStation 4 gaming console runs a modified version of FreeBSD. * http://www.sophos.com/[Sophos] - The Sophos Email Appliance product is based on a hardened FreeBSD and scans inbound mail for spam and viruses, while also monitoring outbound mail for malware as well as the accidental loss of sensitive information. * http://www.spectralogic.com/[Spectra Logic] - The nTier line of archive grade storage appliances run FreeBSD and OpenZFS. * https://www.stormshield.com[Stormshield] - Stormshield Network Security appliances are based on a hardened version of FreeBSD. The BSD license allows them to integrate their own intellectual property with the system while returning a great deal of interesting development to the community. * http://www.weather.com/[The Weather Channel] - The IntelliStar appliance that is installed at each local cable provider's headend and is responsible for injecting local weather forecasts into the cable TV network's programming runs FreeBSD. * http://www.verisign.com/[Verisign] - Verisign is responsible for operating the .com and .net root domain registries as well as the accompanying DNS infrastructure. They rely on a number of different network operating systems including FreeBSD to ensure there is no common point of failure in their infrastructure. * http://www.voxer.com/[Voxer] - Voxer powers their mobile voice messaging platform with ZFS on FreeBSD. Voxer switched from a Solaris derivative to FreeBSD because of its superior documentation, larger and more active community, and more developer friendly environment. In addition to critical features like ZFS and DTrace, FreeBSD also offers TRIM support for ZFS. * https://fudosecurity.com/en/[Fudo Security] - The FUDO security appliance allows enterprises to monitor, control, record, and audit contractors and administrators who work on their systems. Based on all of the best security features of FreeBSD including ZFS, GELI, Capsicum, HAST, and auditdistd. FreeBSD has also spawned a number of related open source projects: * http://bsdrp.net/[BSD Router] - A FreeBSD based replacement for large enterprise routers designed to run on standard PC hardware. * https://www.truenas.com/[TrueNAS] is a Network Attached Storage (NAS) software that shares and protects data from modern-day threats like ransomware and malware. TrueNAS makes it easy for users and client devices to access shared data through virtually any sharing protocol. * https://ghostbsd.org/[GhostBSD] - is derived from FreeBSD, uses the GTK environment to provide a beautiful looks and comfortable experience on the modern BSD platform offering a natural and native UNIX(R) work environment. * http://mfsbsd.vx.sk/[mfsBSD] - A toolkit for building a FreeBSD system image that runs entirely from memory. * https://xigmanas.com/[XigmaNAS] - A file server distribution based on FreeBSD with a PHP powered web interface. * http://www.opnsense.org/[OPNSense] - OPNsense is an open source, easy-to-use and easy-to-build FreeBSD based firewall and routing platform. OPNsense includes most of the features available in expensive commercial firewalls, and more in many cases. It brings the rich feature set of commercial offerings with the benefits of open and verifiable sources. * https://www.midnightbsd.org[MidnightBSD] - is a FreeBSD derived operating system developed with desktop users in mind. It includes all the software you'd expect for your daily tasks: mail, web browsing, word processing, gaming, and much more. * https://www.nomadbsd.org[NomadBSD] - is a persistent live system for USB flash drives, based on FreeBSD. Together with automatic hardware detection and setup, it is configured to be used as a desktop system that works out of the box, but can also be used for data recovery, for educational purposes, or to test FreeBSD's hardware compatibility. * http://www.pfsense.org/[pfSense] - A firewall distribution based on FreeBSD with a huge array of features and extensive IPv6 support. * http://zrouter.org/[ZRouter] - An open source alternative firmware for embedded devices based on FreeBSD. Designed to replace the proprietary firmware on off-the-shelf routers. A list of https://www.freebsdfoundation.org/about/testimonials/[testimonials from companies basing their products and services on FreeBSD] can be found at the FreeBSD Foundation website. Wikipedia also maintains a https://en.wikipedia.org/wiki/List_of_products_based_on_FreeBSD[list of products based on FreeBSD]. [[history]] == About the FreeBSD Project The following section provides some background information on the project, including a brief history, project goals, and the development model of the project. [[intro-history]] === A Brief History of FreeBSD The FreeBSD Project had its genesis in the early part of 1993, partially as the brainchild of the Unofficial 386BSDPatchkit's last 3 coordinators: Nate Williams, Rod Grimes and Jordan Hubbard. The original goal was to produce an intermediate snapshot of 386BSD in order to fix a number of problems that the patchkit mechanism was just not capable of solving. The early working title for the project was 386BSD 0.5 or 386BSD Interim in reference of that fact. 386BSD was Bill Jolitz's operating system, which had been up to that point suffering rather severely from almost a year's worth of neglect. As the patchkit swelled ever more uncomfortably with each passing day, they decided to assist Bill by providing this interim "cleanup" snapshot. Those plans came to a rude halt when Bill Jolitz suddenly decided to withdraw his sanction from the project without any clear indication of what would be done instead. The trio thought that the goal remained worthwhile, even without Bill's support, and so they adopted the name "FreeBSD" coined by David Greenman. The initial objectives were set after consulting with the system's current users and, once it became clear that the project was on the road to perhaps even becoming a reality, Jordan contacted Walnut Creek CDROM with an eye toward improving FreeBSD's distribution channels for those many unfortunates without easy access to the Internet. Walnut Creek CDROM not only supported the idea of distributing FreeBSD on CD but also went so far as to provide the project with a machine to work on and a fast Internet connection. Without Walnut Creek CDROM's almost unprecedented degree of faith in what was, at the time, a completely unknown project, it is quite unlikely that FreeBSD would have gotten as far, as fast, as it has today. The first CD-ROM (and general net-wide) distribution was FreeBSD 1.0, released in December of 1993. This was based on the 4.3BSD-Lite ("Net/2") tape from U.C. Berkeley, with many components also provided by 386BSD and the Free Software Foundation. It was a fairly reasonable success for a first offering, and they followed it with the highly successful FreeBSD 1.1 release in May of 1994. Around this time, some rather unexpected storm clouds formed on the horizon as Novell and U.C. Berkeley settled their long-running lawsuit over the legal status of the Berkeley Net/2 tape. A condition of that settlement was U.C. Berkeley's concession that large parts of Net/2 were "encumbered" code and the property of Novell, who had in turn acquired it from AT&T some time previously. What Berkeley got in return was Novell's "blessing" that the 4.4BSD-Lite release, when it was finally released, would be declared unencumbered and all existing Net/2 users would be strongly encouraged to switch. This included FreeBSD, and the project was given until the end of July 1994 to stop shipping its own Net/2 based product. Under the terms of that agreement, the project was allowed one last release before the deadline, that release being FreeBSD 1.1.5.1. FreeBSD then set about the arduous task of literally re-inventing itself from a completely new and rather incomplete set of 4.4BSD-Lite bits. The "Lite" releases were light in part because Berkeley's CSRG had removed large chunks of code required for actually constructing a bootable running system (due to various legal requirements) and the fact that the Intel port of 4.4 was highly incomplete. It took the project until November of 1994 to make this transition, and in December it released FreeBSD 2.0 to the world. Despite being still more than a little rough around the edges, the release was a significant success and was followed by the more robust and easier to install FreeBSD 2.0.5 release in June of 1995. Since that time, FreeBSD has made a series of releases each time improving the stability, speed, and feature set of the previous version. For now, long-term development projects continue to take place in the 10.X-CURRENT (trunk) branch, and snapshot releases of 10.X are continually made available from link:ftp://ftp.FreeBSD.org/pub/FreeBSD/snapshots/[the snapshot server] as work progresses. [[goals]] === FreeBSD Project Goals The goals of the FreeBSD Project are to provide software that may be used for any purpose and without strings attached. Many of us have a significant investment in the code (and project) and would certainly not mind a little financial compensation now and then, but we are definitely not prepared to insist on it. We believe that our first and foremost "mission" is to provide code to any and all comers, and for whatever purpose, so that the code gets the widest possible use and provides the widest possible benefit. This is, I believe, one of the most fundamental goals of Free Software and one that we enthusiastically support. That code in our source tree which falls under the GNU General Public License (GPL) or Library General Public License (LGPL) comes with slightly more strings attached, though at least on the side of enforced access rather than the usual opposite. Due to the additional complexities that can evolve in the commercial use of GPL software we do, however, prefer software submitted under the more relaxed BSD license when it is a reasonable option to do so. [[development]] === The FreeBSD Development Model The development of FreeBSD is a very open and flexible process, being literally built from the contributions of thousands of people around the world, as can be seen from our extref:{contributors}[list of contributors]. FreeBSD's development infrastructure allow these thousands of contributors to collaborate over the Internet. We are constantly on the lookout for new developers and ideas, and those interested in becoming more closely involved with the project need simply contact us at the {freebsd-hackers}. The {freebsd-announce} is also available to those wishing to make other FreeBSD users aware of major areas of work. Useful things to know about the FreeBSD Project and its development process, whether working independently or in close cooperation: The Git repositories[[development-cvs-repository]]:: For several years, the central source tree for FreeBSD was maintained by http://www.nongnu.org/cvs/[CVS] (Concurrent Versions System), a freely available source code control tool. In June 2008, the Project switched to using https://subversion.apache.org/[SVN] (Subversion). The switch was deemed necessary, as the technical limitations imposed by CVS were becoming obvious due to the rapid expansion of the source tree and the amount of history already stored. The Documentation Project and Ports Collection repositories also moved from CVS to SVN in May 2012 and July 2012, respectively. In December 2020, the Project https://www.freebsd.org/status/report-2020-10-2020-12.html#Git-Migration-Working-Group[migrated Source and Documentation repositories] to https://git-scm.com/[Git], with https://www.freebsd.org/status/report-2021-04-2021-06/#_git_migration_working_group[Ports following suit] in April 2021. Please refer to the crossref:cutting-edge[synching, Obtaining the Source] section for more information on obtaining the FreeBSD `src/` repository and crossref:ports[ports-using, Using the Ports Collection] for details on obtaining the FreeBSD Ports Collection. The committers list[[development-committers]]:: The _committers_ are the people who have _push_ access to the Git repository, and are authorized to make modifications to the FreeBSD source (the term "committer" comes from `commit`, the source control command which is used to bring new changes into the repository). Anyone can submit a bug to the https://bugs.FreeBSD.org/submit/[Bug Database]. Before submitting a bug report, the FreeBSD mailing lists, IRC channels, or forums can be used to help verify that an issue is actually a bug. The FreeBSD core team[[development-core]]:: The _FreeBSD core team_ would be equivalent to the board of directors if the FreeBSD Project were a company. The primary task of the core team is to make sure the project, as a whole, is in good shape and is heading in the right directions. Inviting dedicated and responsible developers to join our group of committers is one of the functions of the core team, as is the recruitment of new core team members as others move on. The current core team was elected from a pool of committer candidates in June 2020. Elections are held every 2 years. + [NOTE] ==== Like most developers, most members of the core team are also volunteers when it comes to FreeBSD development and do not benefit from the project financially, so "commitment" should also not be misconstrued as meaning "guaranteed support." The "board of directors" analogy above is not very accurate, and it may be more suitable to say that these are the people who gave up their lives in favor of FreeBSD against their better judgement! ==== Outside contributors:: Last, but definitely not least, the largest group of developers are the users themselves who provide feedback and bug fixes to us on an almost constant basis. The primary way of keeping in touch with FreeBSD's more non-centralized development is to subscribe to the {freebsd-hackers} where such things are discussed. See crossref:eresources[eresources, Resources on the Internet] for more information about the various FreeBSD mailing lists. + extref:{contributors}[The FreeBSD Contributors List] is a long and growing one, so why not join it by contributing something back to FreeBSD today? + Providing code is not the only way of contributing to the project; for a more complete list of things that need doing, please refer to the link:https://www.FreeBSD.org/[FreeBSD Project web site]. In summary, our development model is organized as a loose set of concentric circles. The centralized model is designed for the convenience of the _users_ of FreeBSD, who are provided with an easy way of tracking one central code base, not to keep potential contributors out! Our desire is to present a stable operating system with a large set of coherent crossref:ports[ports,application programs] that the users can easily install and use - this model works very well in accomplishing that. All we ask of those who would join us as FreeBSD developers is some of the same dedication its current people have to its continued success! [[third-party-programs]] === Third Party Programs In addition to the base distributions, FreeBSD offers a ported software collection with thousands of commonly sought-after programs. At the time of this writing, there were over {numports} ports! The list of ports ranges from http servers, to games, languages, editors, and almost everything in between. The entire Ports Collection requires approximately {ports-size}. To compile a port, you simply change to the directory of the program you wish to install, type `make install`, and let the system do the rest. The full original distribution for each port you build is retrieved dynamically so you need only enough disk space to build the ports you want. Almost every port is also provided as a pre-compiled "package", which can be installed with a simple command (`pkg install`) by those who do not wish to compile their own ports from source. More information on packages and ports can be found in crossref:ports[ports,Installing Applications: Packages and Ports]. === Additional Documentation All supported FreeBSD versions provide an option in the installer to install additional documentation under [.filename]#/usr/local/share/doc/freebsd# during the initial system setup. -Documentation may also be installed at any later time using packages: +Documentation may also be installed later using packages: [source,shell] .... # pkg install en-freebsd-doc .... For localized versions replace the "en" with language prefix of choice. +Be aware that some of the localised versions might be out of date and might contain information that is no longer correct or relevant. You may view the locally installed manuals with a web browser using the following URLs: The FreeBSD Handbook:: [.filename]#link:file:///usr/local/share/doc/freebsd/en/books/handbook/book.html[/usr/local/share/doc/freebsd/en/books/handbook/book.html]# The FreeBSD FAQ:: [.filename]#link:file://localhost/usr/local/share/doc/freebsd/en/books/faq/book.html[/usr/local/share/doc/freebsd/en/books/faq/book.html]# You can always find the up to date copy at https://docs.FreeBSD.org/[https://docs.FreeBSD.org/]. diff --git a/documentation/content/en/books/handbook/linuxemu/_index.adoc b/documentation/content/en/books/handbook/linuxemu/_index.adoc index ff7b75b739..858a399ca3 100644 --- a/documentation/content/en/books/handbook/linuxemu/_index.adoc +++ b/documentation/content/en/books/handbook/linuxemu/_index.adoc @@ -1,341 +1,341 @@ --- title: Chapter 10. Linux Binary Compatibility part: Part II. Common Tasks prev: books/handbook/printing next: books/handbook/wine description: FreeBSD provides binary compatibility with Linux, allowing users to install and run most Linux binaries on a FreeBSD system without having to first modify the binary tags: ["linux", "linuxulator", "emulation", "binary", "compatibility"] showBookMenu: true weight: 13 path: "/books/handbook/" --- [[linuxemu]] = Linux Binary Compatibility :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 10 :partnums: :source-highlighter: rouge :experimental: :images-path: books/handbook/linuxemu/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] [[linuxemu-synopsis]] == Synopsis FreeBSD provides optional binary compatibility with Linux(R), allowing users to install and run unmodified Linux binaries. It is available for the i386, amd64, and arm64 architectures. Some Linux-specific operating system features are not yet supported; this mostly happens with functionality specific to hardware or related to system management, such as cgroups or namespaces. After reading this chapter, you will know: * How to enable Linux binary compatibility on a FreeBSD system. * How to install additional Linux shared libraries. * How to install Linux applications on a FreeBSD system. * The implementation details of Linux compatibility in FreeBSD. Before reading this chapter, you should: * Know how to install crossref:ports[ports,additional third-party software]. [[linuxemu-lbc-install]] == Configuring Linux Binary Compatibility By default, Linux binary compatibility is not enabled. To enable it at boot time, add this line to [.filename]#/etc/rc.conf#: [.programlisting] .... linux_enable="YES" .... Once enabled, it can be started without rebooting by running: [source,shell] .... # service linux start .... The [.filename]#/etc/rc.d/linux# script will load necessary kernel modules and mount filesystems expected by Linux applications under [.filename]#/compat/linux#. This is enough for statically linked Linux binaries to work. They can be started in the same way native FreeBSD binaries can; they behave almost exactly like native processes and can be traced and debugged the usual way. Linux binaries linked dynamically (which is the vast majority) also require Linux shared libraries to be installed - they can run on top of the FreeBSD kernel, but they cannot use FreeBSD libraries; this is similar to how 32-bit binaries cannot use native 64-bit libraries. There are several ways of providing those libraries: one can copy them over from an existing Linux installation using the same architecture, install them from FreeBSD packages, or install using man:deboostrap[8] (from package:sysutils/debootstrap[]), and others. [[linuxemu-packages]] == CentOS Base System from FreeBSD Packages [NOTE] ==== This method is not yet available for arm64. ==== The easiest way to install Linux libraries is to install package:emulators/linux_base-c7[] package or port, which places the CentOS 7-derived base system into [.filename]#/compat/linux#: [source,shell] .... # pkg install linux_base-c7 .... FreeBSD provides packages for some Linux binary applications. -For example, to install Sublime Text 4, along all the Linux libraries it depends on, run this command: +For example, to install Sublime Text 4, along with all the Linux libraries it depends on, run this command: [source,shell] .... # pkg install linux-sublime-text4 .... [[linuxemu-debootstrap]] == Debian / Ubuntu Base System with man:debootstrap[8] An alternative way of providing Linux shared libraries is by using package:sysutils/debootstrap[]. This has the advantage of providing a full Debian or Ubuntu distribution. To use it, follow the instructions at FreeBSD Wiki: https://wiki.freebsd.org/LinuxJails[FreeBSD Wiki - Linux Jails]. After deboostrapping, chroot(8) into the newly created directory and install software in a way typical for the Linux distribution inside, for example: [source,shell] .... # chroot /compat/ubuntu /bin/bash root@hostname:/# apt update .... It is possible to debootstrap into [.filename]#/compat/linux#, but it is discouraged to avoid collisions with files installed from FreeBSD ports and packages. Instead, derive the directory name from the distribution or version name, e.g., [.filename]#/compat/ubuntu#. If the bootstrapped instance is intended to provide Linux shared libraries without having to explicitly use chroot or jails, one can point the kernel at it by updating the `compat.linux.emul_path` sysctl and adding a line like this to [.filename]#/etc/sysctl.conf#: [.programlisting] .... compat.linux.emul_path="/compat/ubuntu" .... -This sysctl controls kernel's path translation mechanism; see the man:linux[4] man page for details. +This sysctl controls the kernel's path translation mechanism; see man:linux[4] for details. Please note that changing it might cause trouble for Linux applications installed from FreeBSD packages; one reason is that many of those applications are still 32-bit, while Ubuntu seems to be deprecating 32-bit library support. [[linuxemu-advanced]] == Advanced Topics The Linux compatibility layer is a work in progress. Consult https://wiki.freebsd.org/Linuxulator[FreeBSD Wiki - Linuxulator] for more information. A list of all Linux-related man:sysctl[8] knobs can be found in man:linux[4]. Some applications require specific filesystems to be mounted. This is normally handled by the [.filename]#/etc/rc.d/linux# script, but can be disabled by adding this line to [.filename]#/etc/rc.conf#: [.programlisting] .... linux_mounts_enable="NO" .... Filesystems mounted by the rc script will not work for Linux processes inside chroots or jails; if needed, configure them in [.filename]#/etc/fstab#: .... devfs /compat/linux/dev devfs rw,late 0 0 tmpfs /compat/linux/dev/shm tmpfs rw,late,size=1g,mode=1777 0 0 fdescfs /compat/linux/dev/fd fdescfs rw,late,linrdlnk 0 0 linprocfs /compat/linux/proc linprocfs rw,late 0 0 linsysfs /compat/linux/sys linsysfs rw,late 0 0 .... Since the Linux binary compatibility layer has gained support for running both 32- and 64-bit Linux binaries (on 64-bit x86 hosts), it is no longer possible to link the emulation functionality statically into a custom kernel. [[linuxemu-libs-manually]] === Installing Additional Libraries Manually [NOTE] ==== For base system subdirectories created with man:debootstrap[8], use the instructions above instead. ==== If a Linux application complains about missing shared libraries after configuring Linux binary compatibility, determine which shared libraries the Linux binary needs and install them manually. From a Linux system using the same CPU architecture, `ldd` can be used to determine which shared libraries the application needs. For example, to check which shared libraries `linuxdoom` needs, run this command from a Linux system that has Doom installed: [source,shell] .... % ldd linuxdoom libXt.so.3 (DLL Jump 3.1) => /usr/X11/lib/libXt.so.3.1.0 libX11.so.3 (DLL Jump 3.1) => /usr/X11/lib/libX11.so.3.1.0 libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29 .... Then, copy all the files in the last column of the output from the Linux system into [.filename]#/compat/linux# on the FreeBSD system. Once copied, create symbolic links to the names in the first column. This example will result in the following files on the FreeBSD system: [source,shell] .... /compat/linux/usr/X11/lib/libXt.so.3.1.0 /compat/linux/usr/X11/lib/libXt.so.3 -> libXt.so.3.1.0 /compat/linux/usr/X11/lib/libX11.so.3.1.0 /compat/linux/usr/X11/lib/libX11.so.3 -> libX11.so.3.1.0 /compat/linux/lib/libc.so.4.6.29 /compat/linux/lib/libc.so.4 -> libc.so.4.6.29 .... If a Linux shared library already exists with a matching major revision number to the first column of the `ldd` output, it does not need to be copied to the file named in the last column, as the existing library should work. It is advisable to copy the shared library if it is a newer version, though. The old one can be removed, as long as the symbolic link points to the new one. For example, these libraries already exist on the FreeBSD system: [source,shell] .... /compat/linux/lib/libc.so.4.6.27 /compat/linux/lib/libc.so.4 -> libc.so.4.6.27 .... and `ldd` indicates that a binary requires a later version: [source,shell] .... libc.so.4 (DLL Jump 4.5pl26) -> libc.so.4.6.29 .... Since the existing library is only one or two versions out of date in the last digit, the program should still work with the slightly older version. However, it is safe to replace the existing [.filename]#libc.so# with the newer version: [source,shell] .... /compat/linux/lib/libc.so.4.6.29 /compat/linux/lib/libc.so.4 -> libc.so.4.6.29 .... Generally, one will need to look for the shared libraries that Linux binaries depend on only the first few times that a Linux program is installed on FreeBSD. After a while, there will be a sufficient set of Linux shared libraries on the system to be able to run newly installed Linux binaries without any extra work. === Branding Linux ELF Binaries The FreeBSD kernel uses several methods to determine if the binary to be executed is a Linux one: it checks the brand in the ELF file header, looks for known ELF interpreter paths and checks ELF notes; finally, by default, unbranded ELF executables are assumed to be Linux anyway. Should all those methods fail, an attempt to execute the binary might result in error message: [source,shell] .... % ./my-linux-elf-binary ELF binary type not known Abort .... To help the FreeBSD kernel distinguish between a FreeBSD ELF binary and a Linux binary, use man:brandelf[1]: [source,shell] .... % brandelf -t Linux my-linux-elf-binary .... === Installing a Linux RPM Based Application To install a Linux RPM-based application, first install the package:archivers/rpm4[] package or port. Once installed, `root` can use this command to install a [.filename]#.rpm#: [source,shell] .... # cd /compat/linux # rpm2cpio < /path/to/linux.archive.rpm | cpio -id .... If necessary, `brandelf` the installed ELF binaries. Note that this will prevent a clean uninstall. === Configuring the Hostname Resolver If DNS does not work or this error appears: [source,shell] .... resolv+: "bind" is an invalid keyword resolv+: "hosts" is an invalid keyword .... configure [.filename]#/compat/linux/etc/host.conf# as follows: [.programlisting] .... order hosts, bind multi on .... This specifies that [.filename]#/etc/hosts# is searched first and DNS is searched second. When [.filename]#/compat/linux/etc/host.conf# does not exist, Linux applications use [.filename]#/etc/host.conf# and complain about the incompatible FreeBSD syntax. Remove `bind` if a name server is not configured using [.filename]#/etc/resolv.conf#. [[linuxemu-advanced]] === Miscellaneous This section describes how Linux binary compatibility works and is based on an email written to {freebsd-chat} by Terry Lambert mailto:tlambert@primenet.com[tlambert@primenet.com] (Message ID: `<199906020108.SAA07001@usr09.primenet.com>`). FreeBSD has an abstraction called an "execution class loader". This is a wedge into the man:execve[2] system call. Historically, the UNIX(R) loader examined the magic number (generally the first 4 or 8 bytes of the file) to see if it was a binary known to the system, and if so, invoked the binary loader. If it was not the binary type for the system, the man:execve[2] call returned a failure, and the shell attempted to start executing it as shell commands. The assumption was a default of "whatever the current shell is". Later, a hack was made for man:sh[1] to examine the first two characters, and if they were `:\n`, it invoked the man:csh[1] shell instead. FreeBSD has a list of loaders, instead of a single loader, with a fallback to the `#!` loader for running shell interpreters or shell scripts. For the Linux ABI support, FreeBSD sees the magic number as an ELF binary. The ELF loader looks for a specialized _brand_, which is a comment section in the ELF image, and which is not present on SVR4/Solaris(TM) ELF binaries. For Linux binaries to function, they must be _branded_ as type `Linux` using man:brandelf[1]: [source,shell] .... # brandelf -t Linux file .... When the ELF loader sees the `Linux` brand, the loader replaces a pointer in the `proc` structure. All system calls are indexed through this pointer. In addition, the process is flagged for special handling of the trap vector for the signal trampoline code, and several other (minor) fix-ups that are handled by the Linux kernel module. The Linux system call vector contains, among other things, a list of `sysent[]` entries whose addresses reside in the kernel module. When a system call is called by the Linux binary, the trap code dereferences the system call function pointer off the `proc` structure, and gets the Linux, not the FreeBSD, system call entry points. Linux mode dynamically _reroots_ lookups. This is, in effect, equivalent to `union` to file system mounts. First, an attempt is made to look up the file in [.filename]#/compat/linux/original-path#. If that fails, the lookup is done in [.filename]#/original-path#. This makes sure that binaries that require other binaries can run. For example, the Linux toolchain can all run under Linux ABI support. It also means that the Linux binaries can load and execute FreeBSD binaries, if there are no corresponding Linux binaries present, and that a man:uname[1] command can be placed in the [.filename]#/compat/linux# directory tree to ensure that the Linux binaries cannot tell they are not running on Linux. In effect, there is a Linux kernel in the FreeBSD kernel. The various underlying functions that implement all of the services provided by the kernel are identical to both the FreeBSD system call table entries, and the Linux system call table entries: file system operations, virtual memory operations, signal delivery, and System V IPC. The only difference is that FreeBSD binaries get the FreeBSD _glue_ functions, and Linux binaries get the Linux _glue_ functions. The FreeBSD _glue_ functions are statically linked into the kernel, and the Linux _glue_ functions can be statically linked, or they can be accessed via a kernel module. Technically, this is not really emulation, it is an ABI implementation. It is sometimes called "Linux emulation" because the implementation was done at a time when there was no other word to describe what was going on. Saying that FreeBSD ran Linux binaries was not true, since the code was not compiled in.