diff --git a/documentation/content/en/books/developers-handbook/secure/_index.adoc b/documentation/content/en/books/developers-handbook/secure/_index.adoc index 738a18988c..a871193a5b 100644 --- a/documentation/content/en/books/developers-handbook/secure/_index.adoc +++ b/documentation/content/en/books/developers-handbook/secure/_index.adoc @@ -1,290 +1,290 @@ --- title: Chapter 3. Secure Programming authors: - author: Murray Stokely prev: books/developers-handbook/tools next: books/developers-handbook/l10n description: Secure Programming in FreeBSD tags: ["secure programming", "Buffer Overflows", "SetUID issues"] showBookMenu: true weight: 4 params: path: "/books/developers-handbook/secure/" --- [[secure]] = Secure Programming :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 3 :partnums: :source-highlighter: rouge :experimental: :images-path: books/developers-handbook/ 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::[] [[secure-synopsis]] == Synopsis This chapter describes some of the security issues that have plagued UNIX(R) programmers for decades and some of the new tools available to help programmers avoid writing exploitable code. [[secure-philosophy]] == Secure Design Methodology Writing secure applications takes a very scrutinous and pessimistic outlook on life. Applications should be run with the principle of "least privilege" so that no process is ever running with more than the bare minimum access that it needs to accomplish its function. Previously tested code should be reused whenever possible to avoid common mistakes that others may have already fixed. One of the pitfalls of the UNIX(R) environment is how easy it is to make assumptions about the sanity of the environment. Applications should never trust user input (in all its forms), system resources, inter-process communication, or the timing of events. UNIX(R) processes do not execute synchronously so logical operations are rarely atomic. [[secure-bufferov]] == Buffer Overflows -Buffer Overflows have been around since the very beginnings of the von Neumann crossref:bibliography[cod,1] architecture. +Buffer Overflows have been around since the very beginnings of the von Neumann crossref:bibliography[COD,1] architecture. They first gained widespread notoriety in 1988 with the Morris Internet worm. Unfortunately, the same basic attack remains effective today. By far the most common type of buffer overflow attack is based on corrupting the stack. Most modern computer systems use a stack to pass arguments to procedures and to store local variables. A stack is a last in first out (LIFO) buffer in the high memory area of a process image. When a program invokes a function a new "stack frame" is created. This stack frame consists of the arguments passed to the function as well as a dynamic amount of local variable space. The "stack pointer" is a register that holds the current location of the top of the stack. Since this value is constantly changing as new values are pushed onto the top of the stack, many implementations also provide a "frame pointer" that is located near the beginning of a stack frame so that local variables can more easily be addressed relative to this value. -crossref:bibliography[cod,1] The return address for function calls is also stored on the stack, and this is the cause of stack-overflow exploits since overflowing a local variable in a function can overwrite the return address of that function, potentially allowing a malicious user to execute any code he or she wants. +crossref:bibliography[COD,1] The return address for function calls is also stored on the stack, and this is the cause of stack-overflow exploits since overflowing a local variable in a function can overwrite the return address of that function, potentially allowing a malicious user to execute any code he or she wants. Although stack-based attacks are by far the most common, it would also be possible to overrun the stack with a heap-based (malloc/free) attack. The C programming language does not perform automatic bounds checking on arrays or pointers as many other languages do. In addition, the standard C library is filled with a handful of very dangerous functions. [.informaltable] [cols="1,1", frame="none"] |=== |`strcpy`(char *dest, const char *src) | May overflow the dest buffer |`strcat`(char *dest, const char *src) | May overflow the dest buffer |`getwd`(char *buf) | May overflow the buf buffer |`gets`(char *s) | May overflow the s buffer |`[vf]scanf`(const char *format, ...) | May overflow its arguments. |`realpath`(char *path, char resolved_path[]) | May overflow the path buffer |`[v]sprintf`(char *str, const char *format, ...) | May overflow the str buffer. |=== === Example Buffer Overflow The following example code contains a buffer overflow designed to overwrite the return address and skip the instruction immediately following the function call. (Inspired by crossref:bibliography[Phrack,4]) [.programlisting] .... #include void manipulate(char *buffer) { char newbuffer[80]; strcpy(newbuffer,buffer); } int main() { char ch,buffer[4096]; int i=0; while ((buffer[i++] = getchar()) != '\n') {}; i=1; manipulate(buffer); i=2; printf("The value of i is : %d\n",i); return 0; } .... Let us examine what the memory image of this process would look like if we were to input 160 spaces into our little program before hitting return. [XXX figure here!] Obviously more malicious input can be devised to execute actual compiled instructions (such as exec(/bin/sh)). === Avoiding Buffer Overflows The most straightforward solution to the problem of stack-overflows is to always use length restricted memory and string copy functions. `strncpy` and `strncat` are part of the standard C library. These functions accept a length value as a parameter which should be no larger than the size of the destination buffer. These functions will then copy up to 'length' bytes from the source to the destination. However there are a number of problems with these functions. Neither function guarantees NUL termination if the size of the input buffer is as large as the destination. The length parameter is also used inconsistently between strncpy and strncat so it is easy for programmers to get confused as to their proper usage. There is also a significant performance loss compared to `strcpy` when copying a short string into a large buffer since `strncpy` NUL fills up the size specified. Another memory copy implementation exists to get around these problems. The `strlcpy` and `strlcat` functions guarantee that they will always null terminate the destination string when given a non-zero length argument. ==== Compiler based run-time bounds checking Unfortunately there is still a very large assortment of code in public use which blindly copies memory around without using any of the bounded copy routines we just discussed. Fortunately, there is a way to help prevent such attacks - run-time bounds checking, which is implemented by several C/C++ compilers. ProPolice is one such compiler feature, and is integrated into man:gcc[1] versions 4.1 and later. It replaces and extends the earlier StackGuard man:gcc[1] extension. ProPolice helps to protect against stack-based buffer overflows and other attacks by laying pseudo-random numbers in key areas of the stack before calling any function. When a function returns, these "canaries" are checked and if they are found to have been changed the executable is immediately aborted. Thus any attempt to modify the return address or other variable stored on the stack in an attempt to get malicious code to run is unlikely to succeed, as the attacker would have to also manage to leave the pseudo-random canaries untouched. Recompiling your application with ProPolice is an effective means of stopping most buffer-overflow attacks, but it can still be compromised. ==== Library based run-time bounds checking Compiler-based mechanisms are completely useless for binary-only software for which you cannot recompile. For these situations there are a number of libraries which re-implement the unsafe functions of the C-library (`strcpy`, `fscanf`, `getwd`, etc..) and ensure that these functions can never write past the stack pointer. * libsafe * libverify * libparanoia Unfortunately these library-based defenses have a number of shortcomings. These libraries only protect against a very small set of security related issues and they neglect to fix the actual problem. These defenses may fail if the application was compiled with -fomit-frame-pointer. Also, the LD_PRELOAD and LD_LIBRARY_PATH environment variables can be overwritten/unset by the user. [[secure-setuid]] == SetUID issues There are at least 6 different IDs associated with any given process, and you must therefore be very careful with the access that your process has at any given time. In particular, all seteuid applications should give up their privileges as soon as it is no longer required. The real user ID can only be changed by a superuser process. The login program sets this when a user initially logs in and it is seldom changed. The effective user ID is set by the `exec()` functions if a program has its seteuid bit set. An application can call `seteuid()` at any time to set the effective user ID to either the real user ID or the saved set-user-ID. When the effective user ID is set by `exec()` functions, the previous value is saved in the saved set-user-ID. [[secure-chroot]] == Limiting your program's environment The traditional method of restricting a process is with the `chroot()` system call. This system call changes the root directory from which all other paths are referenced for a process and any child processes. For this call to succeed the process must have execute (search) permission on the directory being referenced. The new environment does not actually take effect until you `chdir()` into your new environment. It should also be noted that a process can easily break out of a chroot environment if it has root privilege. This could be accomplished by creating device nodes to read kernel memory, attaching a debugger to a process outside of the man:chroot[8] environment, or in many other creative ways. The behavior of the `chroot()` system call can be controlled somewhat with the kern.chroot_allow_open_directories `sysctl` variable. When this value is set to 0, `chroot()` will fail with EPERM if there are any directories open. If set to the default value of 1, then `chroot()` will fail with EPERM if there are any directories open and the process is already subject to a `chroot()` call. For any other value, the check for open directories will be bypassed completely. === FreeBSD's jail functionality The concept of a Jail extends upon the `chroot()` by limiting the powers of the superuser to create a true `virtual server'. Once a prison is set up all network communication must take place through the specified IP address, and the power of "root privilege" in this jail is severely constrained. While in a prison, any tests of superuser power within the kernel using the `suser()` call will fail. However, some calls to `suser()` have been changed to a new interface `suser_xxx()`. This function is responsible for recognizing or denying access to superuser power for imprisoned processes. A superuser process within a jailed environment has the power to: * Manipulate credential with `setuid`, `seteuid`, `setgid`, `setegid`, `setgroups`, `setreuid`, `setregid`, `setlogin` * Set resource limits with `setrlimit` * Modify some sysctl nodes (kern.hostname) * `chroot()` * Set flags on a vnode: `chflags`, `fchflags` * Set attributes of a vnode such as file permission, owner, group, size, access time, and modification time. * Bind to privileged ports in the Internet domain (ports < 1024) `Jail` is a very useful tool for running applications in a secure environment but it does have some shortcomings. Currently, the IPC mechanisms have not been converted to the `suser_xxx` so applications such as MySQL cannot be run within a jail. Superuser access may have a very limited meaning within a jail, but there is no way to specify exactly what "very limited" means. === POSIX(R).1e Process Capabilities POSIX(R) has released a working draft that adds event auditing, access control lists, fine grained privileges, information labeling, and mandatory access control. This is a work in progress and is the focus of the http://www.trustedbsd.org/[TrustedBSD] project. Some of the initial work has been committed to FreeBSD-CURRENT (cap_set_proc(3)). [[secure-trust]] == Trust An application should never assume that anything about the users environment is sane. This includes (but is certainly not limited to): user input, signals, environment variables, resources, IPC, mmaps, the filesystem working directory, file descriptors, the # of open files, etc. You should never assume that you can catch all forms of invalid input that a user might supply. Instead, your application should use positive filtering to only allow a specific subset of inputs that you deem safe. Improper data validation has been the cause of many exploits, especially with CGI scripts on the world wide web. For filenames you need to be extra careful about paths ("../", "/"), symbolic links, and shell escape characters. Perl has a really cool feature called "Taint" mode which can be used to prevent scripts from using data derived outside the program in an unsafe way. This mode will check command line arguments, environment variables, locale information, the results of certain syscalls (`readdir()`, `readlink()`, `getpwxxx()`), and all file input. [[secure-race-conditions]] == Race Conditions A race condition is anomalous behavior caused by the unexpected dependence on the relative timing of events. In other words, a programmer incorrectly assumed that a particular event would always happen before another. Some of the common causes of race conditions are signals, access checks, and file opens. Signals are asynchronous events by nature so special care must be taken in dealing with them. Checking access with `access(2)` then `open(2)` is clearly non-atomic. Users can move files in between the two calls. Instead, privileged applications should `seteuid()` and then call `open()` directly. Along the same lines, an application should always set a proper umask before `open()` to obviate the need for spurious `chmod()` calls. diff --git a/documentation/content/en/books/handbook/advanced-networking/_index.adoc b/documentation/content/en/books/handbook/advanced-networking/_index.adoc index 42125e86d7..7090c1cd39 100644 --- a/documentation/content/en/books/handbook/advanced-networking/_index.adoc +++ b/documentation/content/en/books/handbook/advanced-networking/_index.adoc @@ -1,2387 +1,2387 @@ --- title: Chapter 34. Advanced Networking part: IV. Network Communication prev: books/handbook/firewalls next: books/handbook/partv description: "Advanced networking in FreeBSD: basics of gateways and routes, CARP, how to configure multiple VLANs on FreeBSD, etc" tags: ["Advanced Networking", "Handbook", "gateway", "routes", "wireless", "tethering", "bluetooth", "bridging", "CARP", "VLAN", "WiFi"] showBookMenu: true weight: 39 params: path: "/books/handbook/advanced-networking/" --- [[advanced-networking]] = Advanced Networking :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 34 :partnums: :source-highlighter: rouge :experimental: :images-path: books/handbook/advanced-networking/ 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::[] [[advanced-networking-synopsis]] == Synopsis This chapter covers a number of advanced networking topics. Read this chapter to learn: * The basics of gateways and routes. * How to set up USB tethering. * How to set up IEEE(R) 802.11 and Bluetooth(R) devices. * How to make FreeBSD act as a bridge. * How to set up network PXE booting. * How to enable and utilize the features of the Common Address Redundancy Protocol (CARP) in FreeBSD. * How to configure multiple VLANs on FreeBSD. * How to configure a bluetooth headset. Before reading this chapter: * Understand the basics of the [.filename]#/etc/rc# scripts. * Be familiar with basic network terminology. * Understand basic network configuration on FreeBSD (crossref:network[network,FreeBSD network]). * Know how to configure and install a new FreeBSD kernel (crossref:kernelconfig[kernelconfig,Configuring the FreeBSD Kernel]). * Know how to install additional third-party software (crossref:ports[ports,Installing Applications: Packages and Ports]). [[network-routing]] == Gateways and Routes _Routing_ is the mechanism that allows a system to find the network path to another system. A _route_ is a defined pair of addresses which represent the "destination" and a "gateway". The route indicates that when trying to get to the specified destination, send the packets through the specified gateway. There are three types of destinations: individual hosts, subnets, and "default". The "default route" is used if no other routes apply. There are also three types of gateways: individual hosts, interfaces, also called links, and Ethernet hardware (MAC) addresses. Known routes are stored in a routing table. This section provides an overview of routing basics. It then demonstrates how to configure a FreeBSD system as a router and offers some troubleshooting tips. [[network-routing-default]] === Routing Basics To view the routing table of a FreeBSD system, use man:netstat[1]: [source,shell] .... % netstat -r Routing tables Internet: Destination Gateway Flags Refs Use Netif Expire default outside-gw UGS 37 418 em0 localhost localhost UH 0 181 lo0 test0 0:e0:b5:36:cf:4f UHLW 5 63288 re0 77 10.20.30.255 link#1 UHLW 1 2421 example.com link#1 UC 0 0 host1 0:e0:a8:37:8:1e UHLW 3 4601 lo0 host2 0:e0:a8:37:8:1e UHLW 0 5 lo0 => host2.example.com link#1 UC 0 0 224 link#1 UC 0 0 .... The entries in this example are as follows: default:: The first route in this table specifies the `default` route. When the local system needs to make a connection to a remote host, it checks the routing table to determine if a known path exists. If the remote host matches an entry in the table, the system checks to see if it can connect using the interface specified in that entry. + If the destination does not match an entry, or if all known paths fail, the system uses the entry for the default route. For hosts on a local area network, the `Gateway` field in the default route is set to the system which has a direct connection to the Internet. When reading this entry, verify that the `Flags` column indicates that the gateway is usable (`UG`). + The default route for a machine which itself is functioning as the gateway to the outside world will be the gateway machine at the Internet Service Provider (ISP). localhost:: The second route is the `localhost` route. The interface specified in the `Netif` column for `localhost` is [.filename]#lo0#, also known as the loopback device. This indicates that all traffic for this destination should be internal, rather than sending it out over the network. MAC address:: The addresses beginning with `0:e0:` are MAC addresses. FreeBSD will automatically identify any hosts, `test0` in the example, on the local Ethernet and add a route for that host over the Ethernet interface, [.filename]#re0#. This type of route has a timeout, seen in the `Expire` column, which is used if the host does not respond in a specific amount of time. When this happens, the route to this host will be automatically deleted. These hosts are identified using the Routing Information Protocol (RIP), which calculates routes to local hosts based upon a shortest path determination. subnet:: FreeBSD will automatically add subnet routes for the local subnet. In this example, `10.20.30.255` is the broadcast address for the subnet `10.20.30` and `example.com` is the domain name associated with that subnet. The designation `link#1` refers to the first Ethernet card in the machine. + Local network hosts and local subnets have their routes automatically configured by a daemon called man:routed[8]. If it is not running, only routes which are statically defined by the administrator will exist. host:: The `host1` line refers to the host by its Ethernet address. Since it is the sending host, FreeBSD knows to use the loopback interface ([.filename]#lo0#) rather than the Ethernet interface. + The two `host2` lines represent aliases which were created using man:ifconfig[8]. The `=>` symbol after the [.filename]#lo0# interface says that an alias has been set in addition to the loopback address. Such routes only show up on the host that supports the alias and all other hosts on the local network will have a `link#1` line for such routes. 224:: The final line (destination subnet `224`) deals with multicasting. Various attributes of each route can be seen in the `Flags` column. crossref:advanced-networking[routeflags,Commonly Seen Routing Table Flags] summarizes some of these flags and their meanings: [[routeflags]] .Commonly Seen Routing Table Flags [cols="1,1", frame="none", options="header"] |=== | Flag | Purpose |U |The route is active (up). |H |The route destination is a single host. |G |Send anything for this destination on to this gateway, which will figure out from there where to send it. |S |This route was statically configured. |C |Clones a new route based upon this route for machines to connect to. This type of route is normally used for local networks. |W |The route was auto-configured based upon a local area network (clone) route. |L |Route involves references to Ethernet (link) hardware. |=== On a FreeBSD system, the default route can defined in [.filename]#/etc/rc.conf# by specifying the IP address of the default gateway: [.programlisting] .... defaultrouter="10.20.30.1" .... It is also possible to manually add the route using `route`: [source,shell] .... # route add default 10.20.30.1 .... Note that manually added routes will not survive a reboot. For more information on manual manipulation of network routing tables, refer to man:route[8]. [[network-static-routes]] === Configuring a Router with Static Routes A FreeBSD system can be configured as the default gateway, or router, for a network if it is a dual-homed system. A dual-homed system is a host which resides on at least two different networks. Typically, each network is connected to a separate network interface, though IP aliasing can be used to bind multiple addresses, each on a different subnet, to one physical interface. In order for the system to forward packets between interfaces, FreeBSD must be configured as a router. Internet standards and good engineering practice prevent the FreeBSD Project from enabling this feature by default, but it can be configured to start at boot by adding this line to [.filename]#/etc/rc.conf#: [.programlisting] .... gateway_enable="YES" # Set to YES if this host will be a gateway .... To enable routing now, set the man:sysctl[8] variable `net.inet.ip.forwarding` to `1`. To stop routing, reset this variable to `0`. The routing table of a router needs additional routes so it knows how to reach other networks. Routes can be either added manually using static routes or routes can be automatically learned using a routing protocol. Static routes are appropriate for small networks and this section describes how to add a static routing entry for a small network. [NOTE] ==== For large networks, static routes quickly become unscalable. FreeBSD comes with the standard BSD routing daemon man:routed[8], which provides the routing protocols RIP, versions 1 and 2, and IRDP. Support for the BGP and OSPF routing protocols can be installed using the package:net/quagga[] package or port. ==== Consider the following network: image::static-routes.png[] In this scenario, `RouterA` is a FreeBSD machine that is acting as a router to the rest of the Internet. It has a default route set to `10.0.0.1` which allows it to connect with the outside world. `RouterB` is already configured to use `192.168.1.1` as its default gateway. Before adding any static routes, the routing table on `RouterA` looks like this: [source,shell] .... % netstat -nr Routing tables Internet: Destination Gateway Flags Refs Use Netif Expire default 10.0.0.1 UGS 0 49378 xl0 127.0.0.1 127.0.0.1 UH 0 6 lo0 10.0.0.0/24 link#1 UC 0 0 xl0 192.168.1.0/24 link#2 UC 0 0 xl1 .... With the current routing table, `RouterA` does not have a route to the `192.168.2.0/24` network. The following command adds the `Internal Net 2` network to ``RouterA``'s routing table using `192.168.1.2` as the next hop: [source,shell] .... # route add -net 192.168.2.0/24 192.168.1.2 .... Now, `RouterA` can reach any host on the `192.168.2.0/24` network. However, the routing information will not persist if the FreeBSD system reboots. If a static route needs to be persistent, add it to [.filename]#/etc/rc.conf#: [.programlisting] .... # Add Internal Net 2 as a persistent static route static_routes="internalnet2" route_internalnet2="-net 192.168.2.0/24 192.168.1.2" .... The `static_routes` configuration variable is a list of strings separated by a space, where each string references a route name. The variable `route_internalnet2` contains the static route for that route name. Using more than one string in `static_routes` creates multiple static routes. The following shows an example of adding static routes for the `192.168.0.0/24` and `192.168.1.0/24` networks: [.programlisting] .... static_routes="net1 net2" route_net1="-net 192.168.0.0/24 192.168.0.1" route_net2="-net 192.168.1.0/24 192.168.1.1" .... [[network-routing-troubleshooting]] === Troubleshooting When an address space is assigned to a network, the service provider configures their routing tables so that all traffic for the network will be sent to the link for the site. But how do external sites know to send their packets to the network's ISP? There is a system that keeps track of all assigned address spaces and defines their point of connection to the Internet backbone, or the main trunk lines that carry Internet traffic across the country and around the world. Each backbone machine has a copy of a master set of tables, which direct traffic for a particular network to a specific backbone carrier, and from there down the chain of service providers until it reaches a particular network. It is the task of the service provider to advertise to the backbone sites that they are the point of connection, and thus the path inward, for a site. This is known as route propagation. Sometimes, there is a problem with route propagation and some sites are unable to connect. Perhaps the most useful command for trying to figure out where routing is breaking down is `traceroute`. It is useful when `ping` fails. When using `traceroute`, include the address of the remote host to connect to. The output will show the gateway hosts along the path of the attempt, eventually either reaching the target host, or terminating because of a lack of connection. For more information, refer to man:traceroute[8]. [[network-routing-multicast]] === Multicast Considerations FreeBSD natively supports both multicast applications and multicast routing. Multicast applications do not require any special configuration in order to run on FreeBSD. Support for multicast routing requires that the following option be compiled into a custom kernel: [.programlisting] .... options MROUTING .... The multicast routing daemon, mrouted can be installed using the package:net/mrouted[] package or port. This daemon implements the DVMRP multicast routing protocol and is configured by editing [.filename]#/usr/local/etc/mrouted.conf# in order to set up the tunnels and DVMRP. The installation of mrouted also installs map-mbone and mrinfo, as well as their associated man pages. Refer to these for configuration examples. [NOTE] ==== DVMRP has largely been replaced by the PIM protocol in many multicast installations. Refer to man:pim[4] for more information. ==== [[configtuning-virtual-hosts]] == Virtual Hosts A common use of FreeBSD is virtual site hosting, where one server appears to the network as many servers. This is achieved by assigning multiple network addresses to a single interface. A given network interface has one "real" address, and may have any number of "alias" addresses. These aliases are normally added by placing alias entries in [.filename]#/etc/rc.conf#, as seen in this example: [source,shell] .... # sysrc ifconfig_fxp0_alias0="inet xxx.xxx.xxx.xxx netmask xxx.xxx.xxx.xxx" .... Alias entries must start with `alias__0__` using a sequential number such as `alias0`, `alias1`, and so on. The configuration process will stop at the first missing number. The calculation of alias netmasks is important. For a given interface, there must be one address which correctly represents the network's netmask. Any other addresses which fall within this network must have a netmask of all ``1``s, expressed as either `255.255.255.255` or `0xffffffff`. For example, consider the case where the `fxp0` interface is connected to two networks: `10.1.1.0` with a netmask of `255.255.255.0` and `202.0.75.16` with a netmask of `255.255.255.240`. The system is to be configured to appear in the ranges `10.1.1.1` through `10.1.1.5` and `202.0.75.17` through `202.0.75.20`. Only the first address in a given network range should have a real netmask. All the rest (`10.1.1.2` through `10.1.1.5` and `202.0.75.18` through `202.0.75.20`) must be configured with a netmask of `255.255.255.255`. The following [.filename]#/etc/rc.conf# entries configure the adapter correctly for this scenario: [source,shell] .... # sysrc ifconfig_fxp0="inet 10.1.1.1 netmask 255.255.255.0" # sysrc ifconfig_fxp0_alias0="inet 10.1.1.2 netmask 255.255.255.255" # sysrc ifconfig_fxp0_alias1="inet 10.1.1.3 netmask 255.255.255.255" # sysrc ifconfig_fxp0_alias2="inet 10.1.1.4 netmask 255.255.255.255" # sysrc ifconfig_fxp0_alias3="inet 10.1.1.5 netmask 255.255.255.255" # sysrc ifconfig_fxp0_alias4="inet 202.0.75.17 netmask 255.255.255.240" # sysrc ifconfig_fxp0_alias5="inet 202.0.75.18 netmask 255.255.255.255" # sysrc ifconfig_fxp0_alias6="inet 202.0.75.19 netmask 255.255.255.255" # sysrc ifconfig_fxp0_alias7="inet 202.0.75.20 netmask 255.255.255.255" .... A simpler way to express this is with a space-separated list of IP address ranges. The first address will be given the indicated subnet mask and the additional addresses will have a subnet mask of `255.255.255.255`. [source,shell] .... # sysrc ifconfig_fxp0_aliases="inet 10.1.1.1-5/24 inet 202.0.75.17-20/28" .... [[network-advanced-wireless]] == Wireless Advanced Authentication FreeBSD supports different ways of connecting to a wireless network. This section describes how to perform advanced authentication to a Wireless Network. To make a connection and basic authentication to a wireless network the section crossref:network[wireless-authentication,Connection and Authentication to a Wireless Network] in the Network Chapter describes how to do it. [[network-wireless-wpa-eap-tls]] === WPA with EAP-TLS The second way to use WPA is with an 802.1X backend authentication server. In this case, WPA is called WPA Enterprise to differentiate it from the less secure WPA Personal. Authentication in WPA Enterprise is based on the Extensible Authentication Protocol (EAP). EAP does not come with an encryption method. Instead, EAP is embedded inside an encrypted tunnel. There are many EAP authentication methods, but EAP-TLS, EAP-TTLS, and EAP-PEAP are the most common. EAP with Transport Layer Security (EAP-TLS) is a well-supported wireless authentication protocol since it was the first EAP method to be certified by the http://www.wi-fi.org/[Wi-Fi Alliance]. EAP-TLS requires three certificates to run: the certificate of the Certificate Authority (CA) installed on all machines, the server certificate for the authentication server, and one client certificate for each wireless client. In this EAP method, both the authentication server and wireless client authenticate each other by presenting their respective certificates, and then verify that these certificates were signed by the organization's CA. As previously, the configuration is done via [.filename]#/etc/wpa_supplicant.conf#: [.programlisting] .... network={ ssid="freebsdap" <.> proto=RSN <.> key_mgmt=WPA-EAP <.> eap=TLS <.> identity="loader" <.> ca_cert="/etc/certs/cacert.pem" <.> client_cert="/etc/certs/clientcert.pem" <.> private_key="/etc/certs/clientkey.pem" <.> private_key_passwd="freebsdmallclient" <.> } .... <.> This field indicates the network name (SSID). <.> This example uses the RSN IEEE(R) 802.11i protocol, also known as WPA2. <.> The `key_mgmt` line refers to the key management protocol to use. In this example, it is WPA using EAP authentication. <.> This field indicates the EAP method for the connection. <.> The `identity` field contains the identity string for EAP. <.> The `ca_cert` field indicates the pathname of the CA certificate file. This file is needed to verify the server certificate. <.> The `client_cert` line gives the pathname to the client certificate file. This certificate is unique to each wireless client of the network. <.> The `private_key` field is the pathname to the client certificate private key file. <.> The `private_key_passwd` field contains the passphrase for the private key. Then, add the following lines to [.filename]#/etc/rc.conf#: [.programlisting] .... wlans_ath0="wlan0" ifconfig_wlan0="WPA DHCP" .... The next step is to bring up the interface: [source,shell] .... # service netif start Starting wpa_supplicant. DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 7 DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 15 DHCPACK from 192.168.0.20 bound to 192.168.0.254 -- renewal in 300 seconds. wlan0: flags=8843 mtu 1500 ether 00:11:95:d5:43:62 inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 media: IEEE 802.11 Wireless Ethernet DS/11Mbps mode 11g status: associated ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS wme burst roaming MANUAL .... It is also possible to bring up the interface manually using man:wpa_supplicant[8] and man:ifconfig[8]. [[network-wireless-wpa-eap-ttls]] === WPA with EAP-TTLS With EAP-TLS, both the authentication server and the client need a certificate. With EAP-TTLS, a client certificate is optional. This method is similar to a web server which creates a secure SSL tunnel even if visitors do not have client-side certificates. EAP-TTLS uses an encrypted TLS tunnel for safe transport of the authentication data. The required configuration can be added to [.filename]#/etc/wpa_supplicant.conf#: [.programlisting] .... network={ ssid="freebsdap" proto=RSN key_mgmt=WPA-EAP eap=TTLS <.> identity="test" <.> password="test" <.> ca_cert="/etc/certs/cacert.pem" <.> phase2="auth=MD5" <.> } .... <.> This field specifies the EAP method for the connection. <.> The `identity` field contains the identity string for EAP authentication inside the encrypted TLS tunnel. <.> The `password` field contains the passphrase for the EAP authentication. <.> The `ca_cert` field indicates the pathname of the CA certificate file. This file is needed to verify the server certificate. <.> This field specifies the authentication method used in the encrypted TLS tunnel. In this example, EAP with MD5-Challenge is used. The "inner authentication" phase is often called "phase2". Next, add the following lines to [.filename]#/etc/rc.conf#: [.programlisting] .... wlans_ath0="wlan0" ifconfig_wlan0="WPA DHCP" .... The next step is to bring up the interface: [source,shell] .... # service netif start Starting wpa_supplicant. DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 7 DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 15 DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 21 DHCPACK from 192.168.0.20 bound to 192.168.0.254 -- renewal in 300 seconds. wlan0: flags=8843 mtu 1500 ether 00:11:95:d5:43:62 inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 media: IEEE 802.11 Wireless Ethernet DS/11Mbps mode 11g status: associated ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS wme burst roaming MANUAL .... [[network-wireless-wpa-eap-peap]] === WPA with EAP-PEAP [NOTE] ==== PEAPv0/EAP-MSCHAPv2 is the most common PEAP method. In this chapter, the term PEAP is used to refer to that method. ==== Protected EAP (PEAP) is designed as an alternative to EAP-TTLS and is the most used EAP standard after EAP-TLS. In a network with mixed operating systems, PEAP should be the most supported standard after EAP-TLS. PEAP is similar to EAP-TTLS as it uses a server-side certificate to authenticate clients by creating an encrypted TLS tunnel between the client and the authentication server, which protects the ensuing exchange of authentication information. PEAP authentication differs from EAP-TTLS as it broadcasts the username in the clear and only the password is sent in the encrypted TLS tunnel. EAP-TTLS will use the TLS tunnel for both the username and password. Add the following lines to [.filename]#/etc/wpa_supplicant.conf# to configure the EAP-PEAP related settings: [.programlisting] .... network={ ssid="freebsdap" proto=RSN key_mgmt=WPA-EAP eap=PEAP <.> identity="test" <.> password="test" <.> ca_cert="/etc/certs/cacert.pem" <.> phase1="peaplabel=0" <.> phase2="auth=MSCHAPV2" <.> } .... <.> This field specifies the EAP method for the connection. <.> The `identity` field contains the identity string for EAP authentication inside the encrypted TLS tunnel. <.> The `password` field contains the passphrase for the EAP authentication. <.> The `ca_cert` field indicates the pathname of the CA certificate file. This file is needed to verify the server certificate. <.> This field contains the parameters for the first phase of authentication, the TLS tunnel. According to the authentication server used, specify a specific label for authentication. Most of the time, the label will be "client EAP encryption" which is set by using `peaplabel=0`. More information can be found in man:wpa_supplicant.conf[5]. <.> This field specifies the authentication protocol used in the encrypted TLS tunnel. In the case of PEAP, it is `auth=MSCHAPV2`. Add the following to [.filename]#/etc/rc.conf#: [.programlisting] .... wlans_ath0="wlan0" ifconfig_wlan0="WPA DHCP" .... Then, bring up the interface: [source,shell] .... # service netif start Starting wpa_supplicant. DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 7 DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 15 DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 21 DHCPACK from 192.168.0.20 bound to 192.168.0.254 -- renewal in 300 seconds. wlan0: flags=8843 mtu 1500 ether 00:11:95:d5:43:62 inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 media: IEEE 802.11 Wireless Ethernet DS/11Mbps mode 11g status: associated ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS wme burst roaming MANUAL .... [[wireless-ad-hoc-mode]] == Wireless Ad-hoc Mode IBSS mode, also called ad-hoc mode, is designed for point to point connections. For example, to establish an ad-hoc network between the machines `A` and `B`, choose two IP addresses and a SSID. On `A`: [source,shell] .... # ifconfig wlan0 create wlandev ath0 wlanmode adhoc # ifconfig wlan0 inet 192.168.0.1 netmask 255.255.255.0 ssid freebsdap # ifconfig wlan0 wlan0: flags=8843 metric 0 mtu 1500 ether 00:11:95:c3:0d:ac inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255 media: IEEE 802.11 Wireless Ethernet autoselect mode 11g status: running ssid freebsdap channel 2 (2417 Mhz 11g) bssid 02:11:95:c3:0d:ac country US ecm authmode OPEN privacy OFF txpower 21.5 scanvalid 60 protmode CTS wme burst .... The `adhoc` parameter indicates that the interface is running in IBSS mode. `B` should now be able to detect `A`: [source,shell] .... # ifconfig wlan0 create wlandev ath0 wlanmode adhoc # ifconfig wlan0 up scan SSID/MESH ID BSSID CHAN RATE S:N INT CAPS freebsdap 02:11:95:c3:0d:ac 2 54M -64:-96 100 IS WME .... The `I` in the output confirms that `A` is in ad-hoc mode. Now, configure `B` with a different IP address: [source,shell] .... # ifconfig wlan0 inet 192.168.0.2 netmask 255.255.255.0 ssid freebsdap # ifconfig wlan0 wlan0: flags=8843 metric 0 mtu 1500 ether 00:11:95:d5:43:62 inet 192.168.0.2 netmask 0xffffff00 broadcast 192.168.0.255 media: IEEE 802.11 Wireless Ethernet autoselect mode 11g status: running ssid freebsdap channel 2 (2417 Mhz 11g) bssid 02:11:95:c3:0d:ac country US ecm authmode OPEN privacy OFF txpower 21.5 scanvalid 60 protmode CTS wme burst .... Both `A` and `B` are now ready to exchange information. [[network-wireless-ap]] === FreeBSD Host Access Points FreeBSD can act as an Access Point (AP) which eliminates the need to buy a hardware AP or run an ad-hoc network. This can be particularly useful when a FreeBSD machine is acting as a gateway to another network such as the Internet. [[network-wireless-ap-basic]] ==== Basic Settings Before configuring a FreeBSD machine as an AP, the kernel must be configured with the appropriate networking support for the wireless card as well as the security protocols being used. For more details, see crossref:advanced-networking[network-wireless-ap-basic, Basic Settings]. [NOTE] ==== The NDIS driver wrapper for Windows(R) drivers does not currently support AP operation. Only native FreeBSD wireless drivers support AP mode. ==== Once wireless networking support is loaded, check if the wireless device supports the host-based access point mode, also known as hostap mode: [source,shell] .... # ifconfig wlan0 create wlandev ath0 # ifconfig wlan0 list caps drivercaps=6f85edc1 cryptocaps=1f .... This output displays the card's capabilities. The `HOSTAP` word confirms that this wireless card can act as an AP. Various supported ciphers are also listed: WEP, TKIP, and AES. This information indicates which security protocols can be used on the AP. The wireless device can only be put into hostap mode during the creation of the network pseudo-device, so a previously created device must be destroyed first: [source,shell] .... # ifconfig wlan0 destroy .... then regenerated with the correct option before setting the other parameters: [source,shell] .... # ifconfig wlan0 create wlandev ath0 wlanmode hostap # ifconfig wlan0 inet 192.168.0.1 netmask 255.255.255.0 ssid freebsdap mode 11g channel 1 .... Use man:ifconfig[8] again to see the status of the [.filename]#wlan0# interface: [source,shell] .... # ifconfig wlan0 wlan0: flags=8843 metric 0 mtu 1500 ether 00:11:95:c3:0d:ac inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255 media: IEEE 802.11 Wireless Ethernet autoselect mode 11g status: running ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac country US ecm authmode OPEN privacy OFF txpower 21.5 scanvalid 60 protmode CTS wme burst dtimperiod 1 -dfs .... The `hostap` parameter indicates the interface is running in the host-based access point mode. The interface configuration can be done automatically at boot time by adding the following lines to [.filename]#/etc/rc.conf#: [.programlisting] .... wlans_ath0="wlan0" create_args_wlan0="wlanmode hostap" ifconfig_wlan0="inet 192.168.0.1 netmask 255.255.255.0 ssid freebsdap mode 11g channel 1" .... ==== Host-based Access Point Without Authentication or Encryption Although it is not recommended to run an AP without any authentication or encryption, this is a simple way to check if the AP is working. This configuration is also important for debugging client issues. Once the AP is configured, initiate a scan from another wireless machine to find the AP: [source,shell] .... # ifconfig wlan0 create wlandev ath0 # ifconfig wlan0 up scan SSID/MESH ID BSSID CHAN RATE S:N INT CAPS freebsdap 00:11:95:c3:0d:ac 1 54M -66:-96 100 ES WME .... The client machine found the AP and can be associated with it: [source,shell] .... # ifconfig wlan0 inet 192.168.0.2 netmask 255.255.255.0 ssid freebsdap # ifconfig wlan0 wlan0: flags=8843 metric 0 mtu 1500 ether 00:11:95:d5:43:62 inet 192.168.0.2 netmask 0xffffff00 broadcast 192.168.0.255 media: IEEE 802.11 Wireless Ethernet OFDM/54Mbps mode 11g status: associated ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac country US ecm authmode OPEN privacy OFF txpower 21.5 bmiss 7 scanvalid 60 bgscan bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS wme burst .... [[network-wireless-ap-wpa]] ==== WPA2 Host-based Access Point This section focuses on setting up a FreeBSD access point using the WPA2 security protocol. More details regarding WPA and the configuration of WPA-based wireless clients -can be found in crossref:advanced-networking[network-wireless-wpa, WPA with EAP-TLS]. +can be found in crossref:advanced-networking[network-wireless-wpa-eap-tls, WPA with EAP-TLS]. The man:hostapd[8] daemon is used to deal with client authentication and key management on the WPA2-enabled AP. The following configuration operations are performed on the FreeBSD machine acting as the AP. Once the AP is correctly working, man:hostapd[8] can be automatically started at boot with this line in [.filename]#/etc/rc.conf#: [.programlisting] .... hostapd_enable="YES" .... Before trying to configure man:hostapd[8], first configure the basic settings introduced in crossref:advanced-networking[network-wireless-ap-basic, Basic Settings]. ===== WPA2-PSK WPA2-PSK is intended for small networks where the use of a backend authentication server is not possible or desired. The configuration is done in [.filename]#/etc/hostapd.conf#: [.programlisting] .... interface=wlan0 <.> debug=1 <.> ctrl_interface=/var/run/hostapd <.> ctrl_interface_group=wheel <.> ssid=freebsdap <.> wpa=2 <.> wpa_passphrase=freebsdmall <.> wpa_key_mgmt=WPA-PSK <.> wpa_pairwise=CCMP <.> .... <.> Wireless interface used for the access point. <.> Level of verbosity used during the execution of man:hostapd[8]. A value of `1` represents the minimal level. <.> Pathname of the directory used by man:hostapd[8] to store domain socket files for communication with external programs such as man:hostapd_cli[8]. The default value is used in this example. <.> The group allowed to access the control interface files. <.> The wireless network name, or SSID, that will appear in wireless scans. <.> Enable WPA and specify which WPA authentication protocol will be required. A value of `2` configures the AP for WPA2 and is recommended. Set to `1` only if the obsolete WPA is required. <.> ASCII passphrase for WPA authentication. <.> The key management protocol to use. This example sets WPA-PSK. <.> Encryption algorithms accepted by the access point. In this example, only the CCMP (AES) cipher is accepted. CCMP is an alternative to TKIP and is strongly preferred when possible. TKIP should be allowed only when there are stations incapable of using CCMP. The next step is to start man:hostapd[8]: [source,shell] .... # service hostapd forcestart .... [source,shell] .... # ifconfig wlan0 wlan0: flags=8943 metric 0 mtu 1500 ether 04:f0:21:16:8e:10 inet6 fe80::6f0:21ff:fe16:8e10%wlan0 prefixlen 64 scopeid 0x9 nd6 options=21 media: IEEE 802.11 Wireless Ethernet autoselect mode 11na status: running ssid No5ignal channel 36 (5180 MHz 11a ht/40+) bssid 04:f0:21:16:8e:10 country US ecm authmode WPA2/802.11i privacy MIXED deftxkey 2 AES-CCM 2:128-bit AES-CCM 3:128-bit txpower 17 mcastrate 6 mgmtrate 6 scanvalid 60 ampdulimit 64k ampdudensity 8 shortgi wme burst dtimperiod 1 -dfs groups: wlan .... Once the AP is running, the clients can associate with it. See crossref:advanced-networking[network-wireless-ap-basic, Basic Settings] for more details. It is possible to see the stations associated with the AP using `ifconfig _wlan0_ list sta`. [[network-usb-tethering]] == USB Tethering Many cellphones provide the option to share their data connection over USB (often called "tethering"). This feature uses one of RNDIS, CDC, or a custom Apple(R) iPhone(R)/iPad(R) protocol. * Android(TM) devices generally use the man:urndis[4] driver. * Apple(R) devices use the man:ipheth[4] driver. * Older devices will often use the man:cdce[4] driver. Before attaching a device, load the appropriate driver into the kernel: [source,shell] .... # kldload if_urndis # kldload if_cdce # kldload if_ipheth .... Once the device is attached ``ue``_0_ will be available for use like a normal network device. Be sure that the "USB tethering" option is enabled on the device. To make this change permanent and load the driver as a module at boot time, place the appropriate line of the following in [.filename]#/boot/loader.conf#: [source,shell] .... if_urndis_load="YES" if_cdce_load="YES" if_ipheth_load="YES" .... [[network-bluetooth]] == Bluetooth Bluetooth is a wireless technology for creating personal networks operating in the 2.4 GHz unlicensed band, with a range of 10 meters. Networks are usually formed ad-hoc from portable devices such as cellular phones, handhelds, and laptops. Unlike Wi-Fi wireless technology, Bluetooth offers higher level service profiles, such as FTP-like file servers, file pushing, voice transport, serial line emulation, and more. This section describes the use of a USB Bluetooth dongle on a FreeBSD system. It then describes the various Bluetooth protocols and utilities. === Loading Bluetooth Support The Bluetooth stack in FreeBSD is implemented using the man:netgraph[4] framework. A broad variety of Bluetooth USB dongles is supported by man:ng_ubt[4]. Broadcom BCM2033 based Bluetooth devices are supported by the man:ubtbcmfw[4] and man:ng_ubt[4] drivers. The 3Com Bluetooth PC Card 3CRWB60-A is supported by the man:ng_bt3c[4] driver. Serial and UART based Bluetooth devices are supported by man:ng_h4[4] and man:hcseriald[8]. Before attaching a device, determine which of the above drivers it uses, then load the driver. For example, if the device uses the man:ng_ubt[4] driver: [source,shell] .... # kldload ng_ubt .... If the Bluetooth device will be attached to the system during system startup, the system can be configured to load the module at boot time by adding the driver to [.filename]#/boot/loader.conf#: [.programlisting] .... ng_ubt_load="YES" .... Once the driver is loaded, plug in the USB dongle. If the driver load was successful, output similar to the following should appear on the console and in [.filename]#/var/log/messages#: [source,shell] .... ubt0: vendor 0x0a12 product 0x0001, rev 1.10/5.25, addr 2 ubt0: Interface 0 endpoints: interrupt=0x81, bulk-in=0x82, bulk-out=0x2 ubt0: Interface 1 (alt.config 5) endpoints: isoc-in=0x83, isoc-out=0x3, wMaxPacketSize=49, nframes=6, buffer size=294 .... To start and stop the Bluetooth stack, use its startup script. It is a good idea to stop the stack before unplugging the device. Starting the bluetooth stack might require man:hcsecd[8] to be started. When starting the stack, the output should be similar to the following: [source,shell] .... # service bluetooth start ubt0 BD_ADDR: 00:02:72:00:d4:1a Features: 0xff 0xff 0xf 00 00 00 00 00 <3-Slot> <5-Slot> Max. ACL packet size: 192 bytes Number of ACL packets: 8 Max. SCO packet size: 64 bytes Number of SCO packets: 8 .... === Finding Other Bluetooth Devices The Host Controller Interface (HCI) provides a uniform method for accessing Bluetooth baseband capabilities. In FreeBSD, a netgraph HCI node is created for each Bluetooth device. For more details, refer to man:ng_hci[4]. One of the most common tasks is discovery of Bluetooth devices within RF proximity. This operation is called _inquiry_. Inquiry and other HCI related operations are done using man:hccontrol[8]. The example below shows how to find out which Bluetooth devices are in range. The list of devices should be displayed in a few seconds. Note that a remote device will only answer the inquiry if it is set to _discoverable_ mode. [source,shell] .... % hccontrol -n ubt0hci inquiry Inquiry result, num_responses=1 Inquiry result #0 BD_ADDR: 00:80:37:29:19:a4 Page Scan Rep. Mode: 0x1 Page Scan Period Mode: 00 Page Scan Mode: 00 Class: 52:02:04 Clock offset: 0x78ef Inquiry complete. Status: No error [00] .... The `BD_ADDR` is the unique address of a Bluetooth device, similar to the MAC address of a network card. This address is needed for further communication with a device and it is possible to assign a human readable name to a `BD_ADDR`. Information regarding the known Bluetooth hosts is contained in [.filename]#/etc/bluetooth/hosts#. The following example shows how to obtain the human readable name that was assigned to the remote device: [source,shell] .... % hccontrol -n ubt0hci remote_name_request 00:80:37:29:19:a4 BD_ADDR: 00:80:37:29:19:a4 Name: Pav's T39 .... If an inquiry is performed on a remote Bluetooth device, it will find the computer as "your.host.name (ubt0)". The name assigned to the local device can be changed at any time. Remote devices can be assigned aliases in [.filename]#/etc/bluetooth/hosts#. More information about [.filename]#/etc/bluetooth/hosts# file might be found in man:bluetooth.hosts[5]. The Bluetooth system provides a point-to-point connection between two Bluetooth units, or a point-to-multipoint connection which is shared among several Bluetooth devices. The following example shows how to create a connection to a remote device: [source,shell] .... % hccontrol -n ubt0hci create_connection BT_ADDR .... `create_connection` accepts `BT_ADDR` as well as host aliases in [.filename]#/etc/bluetooth/hosts#. The following example shows how to obtain the list of active baseband connections for the local device: [source,shell] .... % hccontrol -n ubt0hci read_connection_list Remote BD_ADDR Handle Type Mode Role Encrypt Pending Queue State 00:80:37:29:19:a4 41 ACL 0 MAST NONE 0 0 OPEN .... A _connection handle_ is useful when termination of the baseband connection is required, though it is normally not required to do this by hand. The stack will automatically terminate inactive baseband connections. [source,shell] .... # hccontrol -n ubt0hci disconnect 41 Connection handle: 41 Reason: Connection terminated by local host [0x16] .... Type `hccontrol help` for a complete listing of available HCI commands. Most of the HCI commands do not require superuser privileges. === Device Pairing By default, Bluetooth communication is not authenticated, and any device can talk to any other device. A Bluetooth device, such as a cellular phone, may choose to require authentication to provide a particular service. Bluetooth authentication is normally done with a _PIN code_, an ASCII string up to 16 characters in length. The user is required to enter the same PIN code on both devices. Once the user has entered the PIN code, both devices will generate a _link key_. After that, the link key can be stored either in the devices or in a persistent storage. Next time, both devices will use the previously generated link key. This procedure is called _pairing_. Note that if the link key is lost by either device, the pairing must be repeated. The man:hcsecd[8] daemon is responsible for handling Bluetooth authentication requests. The default configuration file is [.filename]#/etc/bluetooth/hcsecd.conf#. An example section for a cellular phone with the PIN code set to `1234` is shown below: [.programlisting] .... device { bdaddr 00:80:37:29:19:a4; name "Pav's T39"; key nokey; pin "1234"; } .... The only limitation on PIN codes is length. Some devices, such as Bluetooth headsets, may have a fixed PIN code built in. The `-d` switch forces man:hcsecd[8] to stay in the foreground, so it is easy to see what is happening. Set the remote device to receive pairing and initiate the Bluetooth connection to the remote device. The remote device should indicate that pairing was accepted and request the PIN code. Enter the same PIN code listed in [.filename]#hcsecd.conf#. Now the computer and the remote device are paired. Alternatively, pairing can be initiated on the remote device. The following line can be added to [.filename]#/etc/rc.conf# to configure man:hcsecd[8] to start automatically on system start: [.programlisting] .... hcsecd_enable="YES" .... The following is a sample of the man:hcsecd[8] daemon output: [.programlisting] .... hcsecd[16484]: Got Link_Key_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4 hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', link key doesn't exist hcsecd[16484]: Sending Link_Key_Negative_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:19:a4 hcsecd[16484]: Got PIN_Code_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4 hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', PIN code exists hcsecd[16484]: Sending PIN_Code_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:19:a4 .... === Network Access with PPP Profiles A Dial-Up Networking (DUN) profile can be used to configure a cellular phone as a wireless modem for connecting to a dial-up Internet access server. It can also be used to configure a computer to receive data calls from a cellular phone. Network access with a PPP profile can be used to provide LAN access for a single Bluetooth device or multiple Bluetooth devices. It can also provide PC to PC connection using PPP networking over serial cable emulation. In FreeBSD, these profiles are implemented with man:ppp[8] and the man:rfcomm_pppd[8] wrapper which converts a Bluetooth connection into something PPP can use. Before a profile can be used, a new PPP label must be created in [.filename]#/etc/ppp/ppp.conf#. Consult man:rfcomm_pppd[8] for examples. In this example, man:rfcomm_pppd[8] is used to open a connection to a remote device with a `BD_ADDR` of `00:80:37:29:19:a4` on a DUNRFCOMM channel: [source,shell] .... # rfcomm_pppd -a 00:80:37:29:19:a4 -c -C dun -l rfcomm-dialup .... The actual channel number will be obtained from the remote device using the SDP protocol. It is possible to specify the RFCOMM channel by hand, and in this case man:rfcomm_pppd[8] will not perform the SDP query. Use man:sdpcontrol[8] to find out the RFCOMM channel on the remote device. In order to provide network access with the PPPLAN service, man:sdpd[8] must be running and a new entry for LAN clients must be created in [.filename]#/etc/ppp/ppp.conf#. Consult man:rfcomm_pppd[8] for examples. Finally, start the RFCOMMPPP server on a valid RFCOMM channel number. The RFCOMMPPP server will automatically register the Bluetooth LAN service with the local SDP daemon. The example below shows how to start the RFCOMMPPP server. [source,shell] .... # rfcomm_pppd -s -C 7 -l rfcomm-server .... === Bluetooth Protocols This section provides an overview of the various Bluetooth protocols, their function, and associated utilities. ==== Logical Link Control and Adaptation Protocol (L2CAP) The Logical Link Control and Adaptation Protocol (L2CAP) provides connection-oriented and connectionless data services to upper layer protocols. L2CAP permits higher level protocols and applications to transmit and receive L2CAP data packets up to 64 kilobytes in length. L2CAP is based around the concept of _channels_. A channel is a logical connection on top of a baseband connection, where each channel is bound to a single protocol in a many-to-one fashion. Multiple channels can be bound to the same protocol, but a channel cannot be bound to multiple protocols. Each L2CAP packet received on a channel is directed to the appropriate higher level protocol. Multiple channels can share the same baseband connection. In FreeBSD, a netgraph L2CAP node is created for each Bluetooth device. This node is normally connected to the downstream Bluetooth HCI node and upstream Bluetooth socket nodes. The default name for the L2CAP node is "devicel2cap". For more details refer to man:ng_l2cap[4]. A useful command is man:l2ping[8], which can be used to ping other devices. Some Bluetooth implementations might not return all of the data sent to them, so `0 bytes` in the following example is normal. [source,shell] .... # l2ping -a 00:80:37:29:19:a4 0 bytes from 0:80:37:29:19:a4 seq_no=0 time=48.633 ms result=0 0 bytes from 0:80:37:29:19:a4 seq_no=1 time=37.551 ms result=0 0 bytes from 0:80:37:29:19:a4 seq_no=2 time=28.324 ms result=0 0 bytes from 0:80:37:29:19:a4 seq_no=3 time=46.150 ms result=0 .... The man:l2control[8] utility is used to perform various operations on L2CAP nodes. This example shows how to obtain the list of logical connections (channels) and the list of baseband connections for the local device: [source,shell] .... % l2control -a 00:02:72:00:d4:1a read_channel_list L2CAP channels: Remote BD_ADDR SCID/ DCID PSM IMTU/ OMTU State 00:07:e0:00:0b:ca 66/ 64 3 132/ 672 OPEN % l2control -a 00:02:72:00:d4:1a read_connection_list L2CAP connections: Remote BD_ADDR Handle Flags Pending State 00:07:e0:00:0b:ca 41 O 0 OPEN .... Another diagnostic tool is man:btsockstat[1]. It is similar to man:netstat[1], but for Bluetooth network-related data structures. The example below shows the same logical connection as man:l2control[8] above. [source,shell] .... % btsockstat Active L2CAP sockets PCB Recv-Q Send-Q Local address/PSM Foreign address CID State c2afe900 0 0 00:02:72:00:d4:1a/3 00:07:e0:00:0b:ca 66 OPEN Active RFCOMM sessions L2PCB PCB Flag MTU Out-Q DLCs State c2afe900 c2b53380 1 127 0 Yes OPEN Active RFCOMM sockets PCB Recv-Q Send-Q Local address Foreign address Chan DLCI State c2e8bc80 0 250 00:02:72:00:d4:1a 00:07:e0:00:0b:ca 3 6 OPEN .... ==== Radio Frequency Communication (RFCOMM) The RFCOMM protocol provides emulation of serial ports over the L2CAP protocol. RFCOMM is a simple transport protocol, with additional provisions for emulating the 9 circuits of RS-232 (EIATIA-232-E) serial ports. It supports up to 60 simultaneous connections (RFCOMM channels) between two Bluetooth devices. For the purposes of RFCOMM, a complete communication path involves two applications running on the communication endpoints with a communication segment between them. RFCOMM is intended to cover applications that make use of the serial ports of the devices in which they reside. The communication segment is a direct connect Bluetooth link from one device to another. RFCOMM is only concerned with the connection between the devices in the direct connect case, or between the device and a modem in the network case. RFCOMM can support other configurations, such as modules that communicate via Bluetooth wireless technology on one side and provide a wired interface on the other side. In FreeBSD, RFCOMM is implemented at the Bluetooth sockets layer. ==== Service Discovery Protocol (SDP) The Service Discovery Protocol (SDP) provides the means for client applications to discover the existence of services provided by server applications as well as the attributes of those services. The attributes of a service include the type or class of service offered and the mechanism or protocol information needed to utilize the service. SDP involves communication between a SDP server and a SDP client. The server maintains a list of service records that describe the characteristics of services associated with the server. Each service record contains information about a single service. A client may retrieve information from a service record maintained by the SDP server by issuing a SDP request. If the client, or an application associated with the client, decides to use a service, it must open a separate connection to the service provider in order to utilize the service. SDP provides a mechanism for discovering services and their attributes, but it does not provide a mechanism for utilizing those services. Normally, a SDP client searches for services based on some desired characteristics of the services. However, there are times when it is desirable to discover which types of services are described by an SDP server's service records without any prior information about the services. This process of looking for any offered services is called _browsing_. The Bluetooth SDP server, man:sdpd[8], and command line client, man:sdpcontrol[8], are included in the standard FreeBSD installation. The following example shows how to perform a SDP browse query. [source,shell] .... % sdpcontrol -a 00:01:03:fc:6e:ec browse Record Handle: 00000000 Service Class ID List: Service Discovery Server (0x1000) Protocol Descriptor List: L2CAP (0x0100) Protocol specific parameter #1: u/int/uuid16 1 Protocol specific parameter #2: u/int/uuid16 1 Record Handle: 0x00000001 Service Class ID List: Browse Group Descriptor (0x1001) Record Handle: 0x00000002 Service Class ID List: LAN Access Using PPP (0x1102) Protocol Descriptor List: L2CAP (0x0100) RFCOMM (0x0003) Protocol specific parameter #1: u/int8/bool 1 Bluetooth Profile Descriptor List: LAN Access Using PPP (0x1102) ver. 1.0 .... Note that each service has a list of attributes, such as the RFCOMM channel. Depending on the service, the user might need to make note of some of the attributes. Some Bluetooth implementations do not support service browsing and may return an empty list. In this case, it is possible to search for the specific service. The example below shows how to search for the OBEX Object Push (OPUSH) service: [source,shell] .... % sdpcontrol -a 00:01:03:fc:6e:ec search OPUSH .... Offering services on FreeBSD to Bluetooth clients is done with the man:sdpd[8] server. The following line can be added to [.filename]#/etc/rc.conf#: [.programlisting] .... sdpd_enable="YES" .... Then the man:sdpd[8] daemon can be started with: [source,shell] .... # service sdpd start .... The local server application that wants to provide a Bluetooth service to remote clients will register the service with the local SDP daemon. An example of such an application is man:rfcomm_pppd[8]. Once started, it will register the Bluetooth LAN service with the local SDP daemon. The list of services registered with the local SDP server can be obtained by issuing a SDP browse query via the local control channel: [source,shell] .... # sdpcontrol -l browse .... ==== OBEX Object Push (OPUSH) Object Exchange (OBEX) is a widely used protocol for simple file transfers between mobile devices. Its main use is in infrared communication, where it is used for generic file transfers between notebooks or PDAs, and for sending business cards or calendar entries between cellular phones and other devices with Personal Information Manager (PIM) applications. The OBEX server and client are implemented by obexapp, which can be installed using the package:comms/obexapp[] package or port. The OBEX client is used to push and/or pull objects from the OBEX server. An example object is a business card or an appointment. The OBEX client can obtain the RFCOMM channel number from the remote device via SDP. This can be done by specifying the service name instead of the RFCOMM channel number. Supported service names are: `IrMC`, `FTRN`, and `OPUSH`. It is also possible to specify the RFCOMM channel as a number. Below is an example of an OBEX session where the device information object is pulled from the cellular phone, and a new object, the business card, is pushed into the phone's directory. [source,shell] .... % obexapp -a 00:80:37:29:19:a4 -C IrMC obex> get telecom/devinfo.txt devinfo-t39.txt Success, response: OK, Success (0x20) obex> put new.vcf Success, response: OK, Success (0x20) obex> di Success, response: OK, Success (0x20) .... In order to provide the OPUSH service, man:sdpd[8] must be running and a root folder, where all incoming objects will be stored, must be created. The default path to the root folder is [.filename]#/var/spool/obex#. Finally, start the OBEX server on a valid RFCOMM channel number. The OBEX server will automatically register the OPUSH service with the local SDP daemon. The example below shows how to start the OBEX server. [source,shell] .... # obexapp -s -C 10 .... ==== Serial Port Profile (SPP) The Serial Port Profile (SPP) allows Bluetooth devices to perform serial cable emulation. This profile allows legacy applications to use Bluetooth as a cable replacement, through a virtual serial port abstraction. In FreeBSD, man:rfcomm_sppd[1] implements SPP and a pseudo tty is used as a virtual serial port abstraction. The example below shows how to connect to a remote device's serial port service. A RFCOMM channel does not have to be specified as man:rfcomm_sppd[1] can obtain it from the remote device via SDP. To override this, specify a RFCOMM channel on the command line. [source,shell] .... # rfcomm_sppd -a 00:07:E0:00:0B:CA -t rfcomm_sppd[94692]: Starting on /dev/pts/6... /dev/pts/6 .... Once connected, the pseudo tty can be used as serial port: [source,shell] .... # cu -l /dev/pts/6 .... The pseudo tty is printed on stdout and can be read by wrapper scripts: [.programlisting] .... PTS=`rfcomm_sppd -a 00:07:E0:00:0B:CA -t` cu -l $PTS .... === Troubleshooting By default, when FreeBSD is accepting a new connection, it tries to perform a role switch and become master. Some older Bluetooth devices which do not support role switching will not be able to connect. Since role switching is performed when a new connection is being established, it is not possible to ask the remote device if it supports role switching. However, there is a HCI option to disable role switching on the local side: [source,shell] .... # hccontrol -n ubt0hci write_node_role_switch 0 .... To display Bluetooth packets, use the third-party package hcidump, which can be installed using the package:comms/hcidump[] package or port. This utility is similar to man:tcpdump[1] and can be used to display the contents of Bluetooth packets on the terminal and to dump the Bluetooth packets to a file. [[network-bridging]] == Bridging It is sometimes useful to divide a network, such as an Ethernet segment, into network segments without having to create IP subnets and use a router to connect the segments together. A device that connects two networks together in this fashion is called a "bridge". A bridge works by learning the MAC addresses of the devices on each of its network interfaces. It forwards traffic between networks only when the source and destination MAC addresses are on different networks. In many respects, a bridge is like an Ethernet switch with very few ports. A FreeBSD system with multiple network interfaces can be configured to act as a bridge. Bridging can be useful in the following situations: Connecting Networks:: The basic operation of a bridge is to join two or more network segments. There are many reasons to use a host-based bridge instead of networking equipment, such as cabling constraints or firewalling. A bridge can also connect a wireless interface running in hostap mode to a wired network and act as an access point. Filtering/Traffic Shaping Firewall:: A bridge can be used when firewall functionality is needed without routing or Network Address Translation (NAT). + An example is a small company that is connected via DSL or ISDN to an ISP. There are thirteen public IP addresses from the ISP and ten computers on the network. In this situation, using a router-based firewall is difficult because of subnetting issues. A bridge-based firewall can be configured without any IP addressing issues. Network Tap:: A bridge can join two network segments in order to inspect all Ethernet frames that pass between them using man:bpf[4] and man:tcpdump[1] on the bridge interface, or by sending a copy of all frames out on an additional interface known as a span port. Layer 2 VPN:: Two Ethernet networks can be joined across an IP link by bridging the networks to an EtherIP tunnel or a man:tap[4] based solution such as OpenVPN. Layer 2 Redundancy:: A network can be connected together with multiple links and use the Spanning Tree Protocol (STP) to block redundant paths. This section describes how to configure a FreeBSD system as a bridge using man:if_bridge[4]. A netgraph bridging driver is also available, and is described in man:ng_bridge[4]. [NOTE] ==== Packet filtering can be used with any firewall package that hooks into the man:pfil[9] framework. The bridge can be used as a traffic shaper with man:altq[4] or man:dummynet[4]. ==== === Enabling the Bridge In FreeBSD, man:if_bridge[4] is a kernel module which is automatically loaded by man:ifconfig[8] when creating a bridge interface. It is also possible to compile bridge support into a custom kernel by adding `device if_bridge` to the custom kernel configuration file. The bridge is created using interface cloning. To create the bridge interface: [source,shell] .... # ifconfig bridge create bridge0 # ifconfig bridge0 bridge0: flags=8802 metric 0 mtu 1500 ether 96:3d:4b:f1:79:7a id 00:00:00:00:00:00 priority 32768 hellotime 2 fwddelay 15 maxage 20 holdcnt 6 proto rstp maxaddr 100 timeout 1200 root id 00:00:00:00:00:00 priority 0 ifcost 0 port 0 .... When a bridge interface is created, it is automatically assigned a randomly generated Ethernet address. The `maxaddr` and `timeout` parameters control how many MAC addresses the bridge will keep in its forwarding table and how many seconds before each entry is removed after it is last seen. The other parameters control how STP operates. Next, specify which network interfaces to add as members of the bridge. For the bridge to forward packets, all member interfaces and the bridge need to be up: [source,shell] .... # ifconfig bridge0 addm fxp0 addm fxp1 up # ifconfig fxp0 up # ifconfig fxp1 up .... The bridge can now forward Ethernet frames between [.filename]#fxp0# and [.filename]#fxp1#. Add the following lines to [.filename]#/etc/rc.conf# so the bridge is created at startup: [.programlisting] .... cloned_interfaces="bridge0" ifconfig_bridge0="addm fxp0 addm fxp1 up" ifconfig_fxp0="up" ifconfig_fxp1="up" .... If the bridge host needs an IP address, set it on the bridge interface, not on the member interfaces. The address can be set statically or via DHCP. This example sets a static IP address: [source,shell] .... # ifconfig bridge0 inet 192.168.0.1/24 .... It is also possible to assign an IPv6 address to a bridge interface. To make the changes permanent, add the addressing information to [.filename]#/etc/rc.conf#. [NOTE] ==== When packet filtering is enabled, bridged packets will pass through the filter inbound on the originating interface on the bridge interface, and outbound on the appropriate interfaces. Either stage can be disabled. When direction of the packet flow is important, it is best to firewall on the member interfaces rather than the bridge itself. The bridge has several configurable settings for passing non-IP and IP packets, and layer2 firewalling with man:ipfw[8]. See man:if_bridge[4] for more information. ==== === Enabling Spanning Tree For an Ethernet network to function properly, only one active path can exist between two devices. The STP protocol detects loops and puts redundant links into a blocked state. Should one of the active links fail, STP calculates a different tree and enables one of the blocked paths to restore connectivity to all points in the network. The Rapid Spanning Tree Protocol (RSTP or 802.1w) provides backwards compatibility with legacy STP. RSTP provides faster convergence and exchanges information with neighboring switches to quickly transition to forwarding mode without creating loops. FreeBSD supports RSTP and STP as operating modes, with RSTP being the default mode. STP can be enabled on member interfaces using man:ifconfig[8]. For a bridge with [.filename]#fxp0# and [.filename]#fxp1# as the current interfaces, enable STP with: [source,shell] .... # ifconfig bridge0 stp fxp0 stp fxp1 bridge0: flags=8843 metric 0 mtu 1500 ether d6:cf:d5:a0:94:6d id 00:01:02:4b:d4:50 priority 32768 hellotime 2 fwddelay 15 maxage 20 holdcnt 6 proto rstp maxaddr 100 timeout 1200 root id 00:01:02:4b:d4:50 priority 32768 ifcost 0 port 0 member: fxp0 flags=1c7 port 3 priority 128 path cost 200000 proto rstp role designated state forwarding member: fxp1 flags=1c7 port 4 priority 128 path cost 200000 proto rstp role designated state forwarding .... This bridge has a spanning tree ID of `00:01:02:4b:d4:50` and a priority of `32768`. As the `root id` is the same, it indicates that this is the root bridge for the tree. Another bridge on the network also has STP enabled: [source,shell] .... bridge0: flags=8843 metric 0 mtu 1500 ether 96:3d:4b:f1:79:7a id 00:13:d4:9a:06:7a priority 32768 hellotime 2 fwddelay 15 maxage 20 holdcnt 6 proto rstp maxaddr 100 timeout 1200 root id 00:01:02:4b:d4:50 priority 32768 ifcost 400000 port 4 member: fxp0 flags=1c7 port 4 priority 128 path cost 200000 proto rstp role root state forwarding member: fxp1 flags=1c7 port 5 priority 128 path cost 200000 proto rstp role designated state forwarding .... The line `root id 00:01:02:4b:d4:50 priority 32768 ifcost 400000 port 4` shows that the root bridge is `00:01:02:4b:d4:50` and has a path cost of `400000` from this bridge. The path to the root bridge is via `port 4` which is [.filename]#fxp0#. === Bridge Interface Parameters Several `ifconfig` parameters are unique to bridge interfaces. This section summarizes some common uses for these parameters. The complete list of available parameters is described in man:ifconfig[8]. private:: A private interface does not forward any traffic to any other port that is also designated as a private interface. The traffic is blocked unconditionally so no Ethernet frames will be forwarded, including ARP packets. If traffic needs to be selectively blocked, a firewall should be used instead. span:: A span port transmits a copy of every Ethernet frame received by the bridge. The number of span ports configured on a bridge is unlimited, but if an interface is designated as a span port, it cannot also be used as a regular bridge port. This is most useful for snooping a bridged network passively on another host connected to one of the span ports of the bridge. For example, to send a copy of all frames out the interface named [.filename]#fxp4#: + [source,shell] .... # ifconfig bridge0 span fxp4 .... sticky:: If a bridge member interface is marked as sticky, dynamically learned address entries are treated as static entries in the forwarding cache. Sticky entries are never aged out of the cache or replaced, even if the address is seen on a different interface. This gives the benefit of static address entries without the need to pre-populate the forwarding table. Clients learned on a particular segment of the bridge cannot roam to another segment. + An example of using sticky addresses is to combine the bridge with VLANs in order to isolate customer networks without wasting IP address space. Consider that `CustomerA` is on `vlan100`, `CustomerB` is on `vlan101`, and the bridge has the address `192.168.0.1`: + [source,shell] .... # ifconfig bridge0 addm vlan100 sticky vlan100 addm vlan101 sticky vlan101 # ifconfig bridge0 inet 192.168.0.1/24 .... + In this example, both clients see `192.168.0.1` as their default gateway. Since the bridge cache is sticky, one host cannot spoof the MAC address of the other customer in order to intercept their traffic. + Any communication between the VLANs can be blocked using a firewall or, as seen in this example, private interfaces: + [source,shell] .... # ifconfig bridge0 private vlan100 private vlan101 .... + The customers are completely isolated from each other and the full `/24` address range can be allocated without subnetting. + The number of unique source MAC addresses behind an interface can be limited. Once the limit is reached, packets with unknown source addresses are dropped until an existing host cache entry expires or is removed. + The following example sets the maximum number of Ethernet devices for `CustomerA` on `vlan100` to 10: + [source,shell] .... # ifconfig bridge0 ifmaxaddr vlan100 10 .... Bridge interfaces also support monitor mode, where the packets are discarded after man:bpf[4] processing and are not processed or forwarded further. This can be used to multiplex the input of two or more interfaces into a single man:bpf[4] stream. This is useful for reconstructing the traffic for network taps that transmit the RX/TX signals out through two separate interfaces. For example, to read the input from four network interfaces as one stream: [source,shell] .... # ifconfig bridge0 addm fxp0 addm fxp1 addm fxp2 addm fxp3 monitor up # tcpdump -i bridge0 .... === SNMP Monitoring The bridge interface and STP parameters can be monitored via man:bsnmpd[1] which is included in the FreeBSD base system. The exported bridge MIBs conform to IETF standards so any SNMP client or monitoring package can be used to retrieve the data. To enable monitoring on the bridge, uncomment this line in [.filename]#/etc/snmpd.config# by removing the beginning `+#+` symbol: [.programlisting] .... begemotSnmpdModulePath."bridge" = "/usr/lib/snmp_bridge.so" .... Other configuration settings, such as community names and access lists, may need to be modified in this file. See man:bsnmpd[1] and man:snmp_bridge[3] for more information. Once these edits are saved, add this line to [.filename]#/etc/rc.conf#: [.programlisting] .... bsnmpd_enable="YES" .... Then, start man:bsnmpd[1]: [source,shell] .... # service bsnmpd start .... The following examples use the Net-SNMP software (package:net-mgmt/net-snmp[]) to query a bridge from a client system. The package:net-mgmt/bsnmptools[] port can also be used. From the SNMP client which is running Net-SNMP, add the following lines to [.filename]#$HOME/.snmp/snmp.conf# in order to import the bridge MIB definitions: [.programlisting] .... mibdirs +/usr/share/snmp/mibs mibs +BRIDGE-MIB:RSTP-MIB:BEGEMOT-MIB:BEGEMOT-BRIDGE-MIB .... To monitor a single bridge using the IETF BRIDGE-MIB (RFC4188): [source,shell] .... % snmpwalk -v 2c -c public bridge1.example.com mib-2.dot1dBridge BRIDGE-MIB::dot1dBaseBridgeAddress.0 = STRING: 66:fb:9b:6e:5c:44 BRIDGE-MIB::dot1dBaseNumPorts.0 = INTEGER: 1 ports BRIDGE-MIB::dot1dStpTimeSinceTopologyChange.0 = Timeticks: (189959) 0:31:39.59 centi-seconds BRIDGE-MIB::dot1dStpTopChanges.0 = Counter32: 2 BRIDGE-MIB::dot1dStpDesignatedRoot.0 = Hex-STRING: 80 00 00 01 02 4B D4 50 ... BRIDGE-MIB::dot1dStpPortState.3 = INTEGER: forwarding(5) BRIDGE-MIB::dot1dStpPortEnable.3 = INTEGER: enabled(1) BRIDGE-MIB::dot1dStpPortPathCost.3 = INTEGER: 200000 BRIDGE-MIB::dot1dStpPortDesignatedRoot.3 = Hex-STRING: 80 00 00 01 02 4B D4 50 BRIDGE-MIB::dot1dStpPortDesignatedCost.3 = INTEGER: 0 BRIDGE-MIB::dot1dStpPortDesignatedBridge.3 = Hex-STRING: 80 00 00 01 02 4B D4 50 BRIDGE-MIB::dot1dStpPortDesignatedPort.3 = Hex-STRING: 03 80 BRIDGE-MIB::dot1dStpPortForwardTransitions.3 = Counter32: 1 RSTP-MIB::dot1dStpVersion.0 = INTEGER: rstp(2) .... The `dot1dStpTopChanges.0` value is two, indicating that the STP bridge topology has changed twice. A topology change means that one or more links in the network have changed or failed and a new tree has been calculated. The `dot1dStpTimeSinceTopologyChange.0` value will show when this happened. To monitor multiple bridge interfaces, the private BEGEMOT-BRIDGE-MIB can be used: [source,shell] .... % snmpwalk -v 2c -c public bridge1.example.com enterprises.fokus.begemot.begemotBridge BEGEMOT-BRIDGE-MIB::begemotBridgeBaseName."bridge0" = STRING: bridge0 BEGEMOT-BRIDGE-MIB::begemotBridgeBaseName."bridge2" = STRING: bridge2 BEGEMOT-BRIDGE-MIB::begemotBridgeBaseAddress."bridge0" = STRING: e:ce:3b:5a:9e:13 BEGEMOT-BRIDGE-MIB::begemotBridgeBaseAddress."bridge2" = STRING: 12:5e:4d:74:d:fc BEGEMOT-BRIDGE-MIB::begemotBridgeBaseNumPorts."bridge0" = INTEGER: 1 BEGEMOT-BRIDGE-MIB::begemotBridgeBaseNumPorts."bridge2" = INTEGER: 1 ... BEGEMOT-BRIDGE-MIB::begemotBridgeStpTimeSinceTopologyChange."bridge0" = Timeticks: (116927) 0:19:29.27 centi-seconds BEGEMOT-BRIDGE-MIB::begemotBridgeStpTimeSinceTopologyChange."bridge2" = Timeticks: (82773) 0:13:47.73 centi-seconds BEGEMOT-BRIDGE-MIB::begemotBridgeStpTopChanges."bridge0" = Counter32: 1 BEGEMOT-BRIDGE-MIB::begemotBridgeStpTopChanges."bridge2" = Counter32: 1 BEGEMOT-BRIDGE-MIB::begemotBridgeStpDesignatedRoot."bridge0" = Hex-STRING: 80 00 00 40 95 30 5E 31 BEGEMOT-BRIDGE-MIB::begemotBridgeStpDesignatedRoot."bridge2" = Hex-STRING: 80 00 00 50 8B B8 C6 A9 .... To change the bridge interface being monitored via the `mib-2.dot1dBridge` subtree: [source,shell] .... % snmpset -v 2c -c private bridge1.example.com BEGEMOT-BRIDGE-MIB::begemotBridgeDefaultBridgeIf.0 s bridge2 .... [[network-aggregation]] == Link Aggregation and Failover FreeBSD provides the man:lagg[4] interface which can be used to aggregate multiple network interfaces into one virtual interface in order to provide failover and link aggregation. Failover allows traffic to continue to flow as long as at least one aggregated network interface has an established link. Link aggregation works best on switches which support LACP, as this protocol distributes traffic bi-directionally while responding to the failure of individual links. The aggregation protocols supported by the lagg interface determine which ports are used for outgoing traffic and whether or not a specific port accepts incoming traffic. The following protocols are supported by man:lagg[4]: failover:: This mode sends and receives traffic only through the master port. If the master port becomes unavailable, the next active port is used. The first interface added to the virtual interface is the master port and all subsequently added interfaces are used as failover devices. If failover to a non-master port occurs, the original port becomes master once it becomes available again. loadbalance:: This provides a static setup and does not negotiate aggregation with the peer or exchange frames to monitor the link. If the switch supports LACP, that should be used instead. lacp:: The IEEE(R) 802.3ad Link Aggregation Control Protocol (LACP) negotiates a set of aggregable links with the peer into one or more Link Aggregated Groups (LAGs). Each LAG is composed of ports of the same speed, set to full-duplex operation, and traffic is balanced across the ports in the LAG with the greatest total speed. Typically, there is only one LAG which contains all the ports. In the event of changes in physical connectivity, LACP will quickly converge to a new configuration. + LACP balances outgoing traffic across the active ports based on hashed protocol header information and accepts incoming traffic from any active port. The hash includes the Ethernet source and destination address and, if available, the VLAN tag, and the IPv4 or IPv6 source and destination address. roundrobin:: This mode distributes outgoing traffic using a round-robin scheduler through all active ports and accepts incoming traffic from any active port. Since this mode violates Ethernet frame ordering, it should be used with caution. broadcast:: This mode sends outgoing traffic to all ports configured on the lagg interface, and receives frames on any port. === Configuration Examples This section demonstrates how to configure a Cisco(R) switch and a FreeBSD system for LACP load balancing. It then shows how to configure two Ethernet interfaces in failover mode as well as how to configure failover mode between an Ethernet and a wireless interface. [[networking-lacp-aggregation-cisco]] .LACP Aggregation with a Cisco(R) Switch [example] ==== This example connects two man:fxp[4] Ethernet interfaces on a FreeBSD machine to the first two Ethernet ports on a Cisco(R) switch as a single load balanced and fault tolerant link. More interfaces can be added to increase throughput and fault tolerance. Replace the names of the Cisco(R) ports, Ethernet devices, channel group number, and IP address shown in the example to match the local configuration. Frame ordering is mandatory on Ethernet links and any traffic between two stations always flows over the same physical link, limiting the maximum speed to that of one interface. The transmit algorithm attempts to use as much information as it can to distinguish different traffic flows and balance the flows across the available interfaces. On the Cisco(R) switch, add the _FastEthernet0/1_ and _FastEthernet0/2_ interfaces to channel group _1_: [source,shell] .... interface FastEthernet0/1 channel-group 1 mode active channel-protocol lacp ! interface FastEthernet0/2 channel-group 1 mode active channel-protocol lacp .... On the FreeBSD system, create the man:lagg[4] interface using the physical interfaces _fxp0_ and _fxp1_ and bring the interfaces up with an IP address of _10.0.0.3/24_: [source,shell] .... # ifconfig fxp0 up # ifconfig fxp1 up # ifconfig lagg0 create # ifconfig lagg0 up laggproto lacp laggport fxp0 laggport fxp1 10.0.0.3/24 .... Next, verify the status of the virtual interface: [source,shell] .... # ifconfig lagg0 lagg0: flags=8843 metric 0 mtu 1500 options=8 ether 00:05:5d:71:8d:b8 inet 10.0.0.3 netmask 0xffffff00 broadcast 10.0.0.255 media: Ethernet autoselect status: active laggproto lacp laggport: fxp1 flags=1c laggport: fxp0 flags=1c .... Ports marked as `ACTIVE` are part of the LAG that has been negotiated with the remote switch. Traffic will be transmitted and received through these active ports. Add `-v` to the above command to view the LAG identifiers. To see the port status on the Cisco(R) switch: [source,shell] .... switch# show lacp neighbor Flags: S - Device is requesting Slow LACPDUs F - Device is requesting Fast LACPDUs A - Device is in Active mode P - Device is in Passive mode Channel group 1 neighbors Partner's information: LACP port Oper Port Port Port Flags Priority Dev ID Age Key Number State Fa0/1 SA 32768 0005.5d71.8db8 29s 0x146 0x3 0x3D Fa0/2 SA 32768 0005.5d71.8db8 29s 0x146 0x4 0x3D .... For more detail, type `show lacp neighbor detail`. To retain this configuration across reboots, add the following entries to [.filename]#/etc/rc.conf# on the FreeBSD system: [.programlisting] .... ifconfig_fxp0="up" ifconfig_fxp1="up" cloned_interfaces="lagg0" ifconfig_lagg0="laggproto lacp laggport fxp0 laggport fxp1 10.0.0.3/24" .... ==== [[networking-lagg-failover]] .Failover Mode [example] ==== Failover mode can be used to switch over to a secondary interface if the link is lost on the master interface. To configure failover, make sure that the underlying physical interfaces are up, then create the man:lagg[4] interface. In this example, _fxp0_ is the master interface, _fxp1_ is the secondary interface, and the virtual interface is assigned an IP address of _10.0.0.15/24_: [source,shell] .... # ifconfig fxp0 up # ifconfig fxp1 up # ifconfig lagg0 create # ifconfig lagg0 up laggproto failover laggport fxp0 laggport fxp1 10.0.0.15/24 .... The virtual interface should look something like this: [source,shell] .... # ifconfig lagg0 lagg0: flags=8843 metric 0 mtu 1500 options=8 ether 00:05:5d:71:8d:b8 inet 10.0.0.15 netmask 0xffffff00 broadcast 10.0.0.255 media: Ethernet autoselect status: active laggproto failover laggport: fxp1 flags=0<> laggport: fxp0 flags=5 .... Traffic will be transmitted and received on _fxp0_. If the link is lost on _fxp0_, _fxp1_ will become the active link. If the link is restored on the master interface, it will once again become the active link. To retain this configuration across reboots, add the following entries to [.filename]#/etc/rc.conf#: [.programlisting] .... ifconfig_fxp0="up" ifconfig_fxp1="up" cloned_interfaces="lagg0" ifconfig_lagg0="laggproto failover laggport fxp0 laggport fxp1 10.0.0.15/24" .... ==== [[networking-lagg-wired-and-wireless]] .Failover Mode Between Ethernet and Wireless Interfaces [example] ==== For laptop users, it is usually desirable to configure the wireless device as a secondary which is only used when the Ethernet connection is not available. With man:lagg[4], it is possible to configure a failover which prefers the Ethernet connection for both performance and security reasons, while maintaining the ability to transfer data over the wireless connection. This is achieved by overriding the Ethernet interface's MAC address with that of the wireless interface. [NOTE] **** In theory, either the Ethernet or wireless MAC address can be changed to match the other. However, some popular wireless interfaces lack support for overriding the MAC address. We therefore recommend overriding the Ethernet MAC address for this purpose. **** [NOTE] **** If the driver for the wireless interface is not loaded in the `GENERIC` or custom kernel, and the computer is running FreeBSD {rel121-current}, load the corresponding [.filename]#.ko# in [.filename]#/boot/loader.conf# by adding `*driver_load="YES"*` to that file and rebooting. Another, better way is to load the driver in [.filename]#/etc/rc.conf# by adding it to `kld_list` (see man:rc.conf[5] for details) in that file and rebooting. This is needed because otherwise the driver is not loaded yet at the time the man:lagg[4] interface is set up. **** In this example, the Ethernet interface, _re0_, is the master and the wireless interface, _wlan0_, is the failover. The _wlan0_ interface was created from the _ath0_ physical wireless interface, and the Ethernet interface will be configured with the MAC address of the wireless interface. First, bring the wireless interface up (replacing _FR_ with the local 2-letter country code), but do not set an IP address. Replace _wlan0_ to match the system's wireless interface name: [source,shell] .... # ifconfig wlan0 create wlandev ath0 country FR ssid my_router up .... Determine the MAC address of the wireless interface like this: [source,shell] .... # ifconfig wlan0 wlan0: flags=8843 metric 0 mtu 1500 ether b8:ee:65:5b:32:59 groups: wlan ssid Bbox-A3BD2403 channel 6 (2437 MHz 11g ht/20) bssid 00:37:b7:56:4b:60 regdomain ETSI country FR indoor ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF AES-CCM 2:128-bit txpower 30 bmiss 7 scanvalid 60 protmode CTS ampdulimit 64k ampdudensity 8 shortgi -stbctx stbcrx -ldpc wme burst roaming MANUAL media: IEEE 802.11 Wireless Ethernet MCS mode 11ng status: associated nd6 options=29 .... The `ether` line will contain the MAC address of the specified interface. Now, change the MAC address of the Ethernet interface to match: [source,shell] .... # ifconfig re0 ether b8:ee:65:5b:32:59 .... Make sure the _re0_ interface is up, then create the man:lagg[4] interface with _re0_ as master with failover to _wlan0_: [source,shell] .... # ifconfig re0 up # ifconfig lagg0 create # ifconfig lagg0 up laggproto failover laggport re0 laggport wlan0 .... The virtual interface should look something like this: [source,shell] .... # ifconfig lagg0 lagg0: flags=8843 metric 0 mtu 1500 options=8 ether b8:ee:65:5b:32:59 laggproto failover lagghash l2,l3,l4 laggport: re0 flags=5 laggport: wlan0 flags=0<> groups: lagg media: Ethernet autoselect status: active .... Then, start the DHCP client to obtain an IP address: [source,shell] .... # dhclient lagg0 .... To retain this configuration across reboots, add the following entries to [.filename]#/etc/rc.conf#: [.programlisting] .... ifconfig_re0="ether b8:ee:65:5b:32:59" wlans_ath0="wlan0" ifconfig_wlan0="WPA" create_args_wlan0="country FR" cloned_interfaces="lagg0" ifconfig_lagg0="up laggproto failover laggport re0 laggport wlan0 DHCP" .... ==== [[network-diskless]] == Diskless Operation with PXE The Intel(R) Preboot eXecution Environment (PXE) allows an operating system to boot over the network. For example, a FreeBSD system can boot over the network and operate without a local disk, using file systems mounted from an NFS server. PXE support is usually available in the BIOS. To use PXE when the machine starts, select the `Boot from network` option in the BIOS setup or type a function key during system initialization. In order to provide the files needed for an operating system to boot over the network, a PXE setup also requires properly configured DHCP, TFTP, and NFS servers, where: * Initial parameters, such as an IP address, executable boot filename and location, server name, and root path are obtained from the DHCP server. * The operating system loader file is booted using TFTP. * The file systems are loaded using NFS. When a computer PXE boots, it receives information over DHCP about where to obtain the initial boot loader file. After the host computer receives this information, it downloads the boot loader via TFTP and then executes the boot loader. In FreeBSD, the boot loader file is [.filename]#/boot/pxeboot#. After [.filename]#/boot/pxeboot# executes, the FreeBSD kernel is loaded and the rest of the FreeBSD bootup sequence proceeds, as described in crossref:boot[boot,The FreeBSD Booting Process]. [NOTE] ==== For UEFI PXE based boot, the actual boot loader file to use is [.filename]#/boot/loader.efi#. See the below section crossref:advanced-networking[_debugging_pxe_problems,Debugging PXE Problems] on how to use [.filename]#/boot/loader.efi#. ==== This section describes how to configure these services on a FreeBSD system so that other systems can PXE boot into FreeBSD. Refer to man:diskless[8] for more information. [CAUTION] ==== As described, the system providing these services is insecure. It should live in a protected area of a network and be untrusted by other hosts. ==== [[network-pxe-nfs]] === Setting Up the PXE Environment The steps shown in this section configure the built-in NFS and TFTP servers. The next section demonstrates how to install and configure the DHCP server. In this example, the directory which will contain the files used by PXE users is [.filename]#/b/tftpboot/FreeBSD/install#. It is important that this directory exists and that the same directory name is set in both [.filename]#/etc/inetd.conf# and [.filename]#/usr/local/etc/dhcpd.conf#. [NOTE] ==== The command examples below assume use of the man:sh[1] shell. man:csh[1] and man:tcsh[1] users will need to start a man:sh[1] shell or adapt the commands to man:csh[1] syntax. ==== [.procedure] . Create the root directory which will contain a FreeBSD installation to be NFS mounted: + [source,shell] .... # export NFSROOTDIR=/b/tftpboot/FreeBSD/install # mkdir -p ${NFSROOTDIR} .... . Enable the NFS server by adding this line to [.filename]#/etc/rc.conf#: + [.programlisting] .... nfs_server_enable="YES" .... . Export the diskless root directory via NFS by adding the following to [.filename]#/etc/exports#: + [.programlisting] .... /b -ro -alldirs -maproot=root .... . Start the NFS server: + [source,shell] .... # service nfsd start .... . Enable man:inetd[8] by adding the following line to [.filename]#/etc/rc.conf#: + [.programlisting] .... inetd_enable="YES" .... . Uncomment the following line in [.filename]#/etc/inetd.conf# by making sure it does not start with a `+#+` symbol: + [.programlisting] .... tftp dgram udp wait root /usr/libexec/tftpd tftpd blocksize 1468 -l -s /b/tftpboot .... + [NOTE] ==== The specified tftp blocksize, e.g. 1468 bytes, replaces the default size 512 bytes. Some PXE versions require the TCP version of TFTP. In this case, uncomment the second `tftp` line which contains `stream tcp`. ==== . Start man:inetd[8]: + [source,shell] .... # service inetd start .... . Install the base system into [.filename]#${NFSROOTDIR}#, either by decompressing the official archives or by rebuilding the FreeBSD kernel and userland (refer to crossref:cutting-edge[makeworld,“Updating FreeBSD from Source”] for more detailed instructions, but do not forget to add `DESTDIR=_${NFSROOTDIR}_` when running the `make installkernel` and `make installworld` commands. . Test that the TFTP server works and can download the boot loader which will be obtained via PXE: + [source,shell] .... # tftp localhost tftp> get FreeBSD/install/boot/pxeboot Received 264951 bytes in 0.1 seconds .... . Edit [.filename]#${NFSROOTDIR}/etc/fstab# and create an entry to mount the root file system over NFS: + [.programlisting] .... # Device Mountpoint FSType Options Dump Pass myhost.example.com:/b/tftpboot/FreeBSD/install / nfs ro 0 0 .... + Replace _myhost.example.com_ with the hostname or IP address of the NFS server. In this example, the root file system is mounted read-only in order to prevent NFS clients from potentially deleting the contents of the root file system. . Set the root password in the PXE environment for client machines which are PXE booting : + [source,shell] .... # chroot ${NFSROOTDIR} # passwd .... . If needed, enable man:ssh[1] root logins for client machines which are PXE booting by editing [.filename]#${NFSROOTDIR}/etc/ssh/sshd_config# and enabling `PermitRootLogin`. This option is documented in man:sshd_config[5]. . Perform any other needed customizations of the PXE environment in [.filename]#${NFSROOTDIR}#. These customizations could include things like installing packages or editing the password file with man:vipw[8]. When booting from an NFS root volume, [.filename]#/etc/rc# detects the NFS boot and runs [.filename]#/etc/rc.initdiskless#. In this case, [.filename]#/etc# and [.filename]#/var# need to be memory backed file systems so that these directories are writable but the NFS root directory is read-only: [source,shell] .... # chroot ${NFSROOTDIR} # mkdir -p conf/base # tar -c -v -f conf/base/etc.cpio.gz --format cpio --gzip etc # tar -c -v -f conf/base/var.cpio.gz --format cpio --gzip var .... When the system boots, memory file systems for [.filename]#/etc# and [.filename]#/var# will be created and mounted and the contents of the [.filename]#cpio.gz# files will be copied into them. By default, these file systems have a maximum capacity of 5 megabytes. If the archives do not fit, which is usually the case for [.filename]#/var# when binary packages have been installed, request a larger size by putting the number of 512 byte sectors needed (e.g., 5 megabytes is 10240 sectors) in [.filename]#${NFSROOTDIR}/conf/base/etc/md_size# and [.filename]#${NFSROOTDIR}/conf/base/var/md_size# files for [.filename]#/etc# and [.filename]#/var# file systems respectively. [[network-pxe-setting-up-dhcp]] === Configuring the DHCP Server The DHCP server does not need to be the same machine as the TFTP and NFS server, but it needs to be accessible in the network. DHCP is not part of the FreeBSD base system but can be installed using the package:net/isc-dhcp44-server[] port or package. Once installed, edit the configuration file, [.filename]#/usr/local/etc/dhcpd.conf#. Configure the `next-server`, `filename`, and `root-path` settings as seen in this example: [.programlisting] .... subnet 192.168.0.0 netmask 255.255.255.0 { range 192.168.0.2 192.168.0.3 ; option subnet-mask 255.255.255.0 ; option routers 192.168.0.1 ; option broadcast-address 192.168.0.255 ; option domain-name-servers 192.168.35.35, 192.168.35.36 ; option domain-name "example.com"; # IP address of TFTP server next-server 192.168.0.1 ; # path of boot loader obtained via tftp filename "FreeBSD/install/boot/pxeboot" ; # pxeboot boot loader will try to NFS mount this directory for root FS option root-path "192.168.0.1:/b/tftpboot/FreeBSD/install/" ; } .... The `next-server` directive is used to specify the IP address of the TFTP server. The `filename` directive defines the path to [.filename]#/boot/pxeboot#. A relative filename is used, meaning that [.filename]#/b/tftpboot# is not included in the path. The `root-path` option defines the path to the NFS root file system. Once the edits are saved, enable DHCP at boot time by adding the following line to [.filename]#/etc/rc.conf#: [.programlisting] .... dhcpd_enable="YES" .... Then start the DHCP service: [source,shell] .... # service isc-dhcpd start .... === Debugging PXE Problems Once all of the services are configured and started, PXE clients should be able to automatically load FreeBSD over the network. If a particular client is unable to connect, when that client machine boots up, enter the BIOS configuration menu and confirm that it is set to boot from the network. This section describes some troubleshooting tips for isolating the source of the configuration problem should no clients be able to PXE boot. [.procedure] **** . Use the package:net/wireshark[] package or port to debug the network traffic involved during the PXE booting process, which is illustrated in the diagram below. + .PXE Booting Process with NFS Root Mount image::pxe-nfs.png[] + 1. Client broadcasts a DHCPDISCOVER message. + 2. The DHCP server responds with the IP address, next-server, filename, and root-path values. + 3. The client sends a TFTP request to next-server, asking to retrieve filename. + 4. The TFTP server responds and sends filename to client. + 5. The client executes filename, which is pxeboot(8), which then loads the kernel. When the kernel executes, the root file system specified by root-path is mounted over NFS. + . On the TFTP server, read [.filename]#/var/log/xferlog# to ensure that [.filename]#pxeboot# is being retrieved from the correct location. To test this example configuration: + [source,shell] .... # tftp 192.168.0.1 tftp> get FreeBSD/install/boot/pxeboot Received 264951 bytes in 0.1 seconds .... + The `BUGS` sections in man:tftpd[8] and man:tftp[1] document some limitations with TFTP. . Make sure that the root file system can be mounted via NFS. To test this example configuration: + [source,shell] .... # mount -t nfs 192.168.0.1:/b/tftpboot/FreeBSD/install /mnt .... + . For UEFI PXE based booting, replace the [.filename]#boot/pxeboot# file with the [.filename]#boot/loader.efi# file: [source,shell] .... # chroot ${NFSROOTDIR} # mv boot/pxeboot boot/pxeboot.original # cp boot/loader.efi boot/pxeboot .... **** [[carp]] == Common Address Redundancy Protocol (CARP) The Common Address Redundancy Protocol (CARP) allows multiple hosts to share the same IP address and Virtual Host ID (VHID) in order to provide _high availability_ for one or more services. This means that one or more hosts can fail, and the other hosts will transparently take over so that users do not see a service failure. In addition to the shared IP address, each host has its own IP address for management and configuration. All of the machines that share an IP address have the same VHID. The VHID for each virtual IP address must be unique across the broadcast domain of the network interface. High availability using CARP is built into FreeBSD, though the steps to configure it vary slightly depending upon the FreeBSD version. This section provides the same example configuration for versions before and equal to or after FreeBSD 10. This example configures failover support with three hosts, all with unique IP addresses, but providing the same web content. It has two different masters named `hosta.example.org` and `hostb.example.org`, with a shared backup named `hostc.example.org`. These machines are load balanced with a Round Robin DNS configuration. The master and backup machines are configured identically except for their hostnames and management IP addresses. These servers must have the same configuration and run the same services. When the failover occurs, requests to the service on the shared IP address can only be answered correctly if the backup server has access to the same content. The backup machine has two additional CARP interfaces, one for each of the master content server's IP addresses. When a failure occurs, the backup server will pick up the failed master machine's IP address. [[carp-10x]] === Using CARP Enable boot-time support for CARP by adding an entry for the [.filename]#carp.ko# kernel module in [.filename]#/boot/loader.conf#: [.programlisting] .... carp_load="YES" .... To load the module now without rebooting: [source,shell] .... # kldload carp .... For users who prefer to use a custom kernel, include the following line in the custom kernel configuration file and compile the kernel as described in crossref:kernelconfig[kernelconfig,Configuring the FreeBSD Kernel]: [.programlisting] .... device carp .... The hostname, management IP address and subnet mask, shared IP address, and VHID are all set by adding entries to [.filename]#/etc/rc.conf#. This example is for `hosta.example.org`: [.programlisting] .... hostname="hosta.example.org" ifconfig_em0="inet 192.168.1.3 netmask 255.255.255.0" ifconfig_em0_alias0="inet vhid 1 pass testpass alias 192.168.1.50/32" .... The next set of entries are for `hostb.example.org`. Since it represents a second master, it uses a different shared IP address and VHID. However, the passwords specified with `pass` must be identical as CARP will only listen to and accept advertisements from machines with the correct password. [.programlisting] .... hostname="hostb.example.org" ifconfig_em0="inet 192.168.1.4 netmask 255.255.255.0" ifconfig_em0_alias0="inet vhid 2 pass testpass alias 192.168.1.51/32" .... The third machine, `hostc.example.org`, is configured to handle failover from either master. This machine is configured with two CARPVHIDs, one to handle the virtual IP address for each of the master hosts. The CARP advertising skew, `advskew`, is set to ensure that the backup host advertises later than the master, since `advskew` controls the order of precedence when there are multiple backup servers. [.programlisting] .... hostname="hostc.example.org" ifconfig_em0="inet 192.168.1.5 netmask 255.255.255.0" ifconfig_em0_alias0="inet vhid 1 advskew 100 pass testpass alias 192.168.1.50/32" ifconfig_em0_alias1="inet vhid 2 advskew 100 pass testpass alias 192.168.1.51/32" .... Having two CARPVHIDs configured means that `hostc.example.org` will notice if either of the master servers becomes unavailable. If a master fails to advertise before the backup server, the backup server will pick up the shared IP address until the master becomes available again. [NOTE] ==== If the original master server becomes available again, `hostc.example.org` will not release the virtual IP address back to it automatically. For this to happen, preemption has to be enabled. The feature is disabled by default, it is controlled via the man:sysctl[8] variable `net.inet.carp.preempt`. The administrator can force the backup server to return the IP address to the master: [source,shell] .... # ifconfig em0 vhid 1 state backup .... ==== Once the configuration is complete, either restart networking or reboot each system. High availability is now enabled. CARP functionality can be controlled via several man:sysctl[8] variables documented in the man:carp[4] manual pages. Other actions can be triggered from CARP events by using man:devd[8]. [[network-vlan]] == VLANs VLANs are a way of virtually dividing up a network into many different subnetworks, also referred to as segmenting. Each segment will have its own broadcast domain and be isolated from other VLANs. On FreeBSD, VLANs must be supported by the network card driver. To see which drivers support vlans, refer to the man:vlan[4] manual page. When configuring a VLAN, a couple pieces of information must be known. First, which network interface? Second, what is the VLAN tag? To configure VLANs at run time, with a NIC of `em0` and a VLAN tag of `5` the command would look like this: [source,shell] .... # ifconfig em0.5 create vlan 5 vlandev em0 inet 192.168.20.20/24 .... [NOTE] ==== See how the interface name includes the NIC driver name and the VLAN tag, separated by a period? This is a best practice to make maintaining the VLAN configuration easy when many VLANs are present on a machine. ==== [NOTE] ==== When defining VLANs, ensure that the parent network interface is also configured and enabled. The minimum configuration for the above example would be: [source,shell] .... # ifconfig em0 up .... ==== To configure VLANs at boot time, [.filename]#/etc/rc.conf# must be updated. To duplicate the configuration above, the following will need to be added: [.programlisting] .... vlans_em0="5" ifconfig_em0_5="inet 192.168.20.20/24" .... Additional VLANs may be added, by simply adding the tag to the `vlans_em0` field and adding an additional line configuring the network on that VLAN tag's interface. [NOTE] ==== When defining VLANs in [.filename]#/etc/rc.conf#, make sure that the parent network interface is configured and enabled as well. The minimum configuration for the above example would be: [.programlisting] .... ifconfig_em0="up" .... ==== It is useful to assign a symbolic name to an interface so that when the associated hardware is changed, only a few configuration variables need to be updated. For example, security cameras need to be run over VLAN 1 on `em0`. Later, if the `em0` card is replaced with a card that uses the man:ixgb[4] driver, all references to `em0.1` will not have to change to `ixgb0.1`. To configure VLAN `5`, on the NIC `em0`, assign the interface name `cameras`, and assign the interface an IP address of `_192.168.20.20_` with a `24`-bit prefix, use this command: [source,shell] .... # ifconfig em0.5 create vlan 5 vlandev em0 name cameras inet 192.168.20.20/24 .... For an interface named `video`, use the following: [source,shell] .... # ifconfig video.5 create vlan 5 vlandev video name cameras inet 192.168.20.20/24 .... To apply the changes at boot time, add the following lines to [.filename]#/etc/rc.conf#: [.programlisting] .... vlans_video="cameras" create_args_cameras="vlan 5" ifconfig_cameras="inet 192.168.20.20/24" .... diff --git a/documentation/content/en/books/handbook/glossary.adoc b/documentation/content/en/books/handbook/glossary.adoc index 005a10e66f..28439170fa 100644 --- a/documentation/content/en/books/handbook/glossary.adoc +++ b/documentation/content/en/books/handbook/glossary.adoc @@ -1,1096 +1,1097 @@ --- title: FreeBSD Glossary prev: books/handbook/pgpkeys next: books/handbook/colophon description: FreeBSD Handbook Glossary showBookMenu: true weight: 45 params: path: "/books/handbook/glossary/" --- [glossary] [[freebsd-glossary]] = FreeBSD Glossary :doctype: book :toc: macro :toclevels: 1 :icons: font :!sectnums: :partnums: :source-highlighter: rouge :experimental: :images-path: books/handbook/glossary/ 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::[] This glossary contains terms and acronyms used within the FreeBSD community and documentation. [discrete] == A ACL:: See crossref:glossary[acl-glossary,Access Control List]. ACPI:: See crossref:glossary[acpi-glossary,Advanced Configuration and Power Interface]. AMD:: See crossref:glossary[amd-glossary,Automatic Mount Daemon]. AML:: See crossref:glossary[aml-glossary,ACPI Machine Language]. API:: See crossref:glossary[api-glossary,Application Programming Interface]. APIC:: See crossref:glossary[apic-glossary,Advanced Programmable Interrupt Controller]. APM:: See crossref:glossary[apm-glossary,Advanced Power Management]. APOP:: See crossref:glossary[apop-glossary,Authenticated Post Office Protocol]. ASL:: See crossref:glossary[asl-glossary,ACPI Source Language]. ATA:: See crossref:glossary[ata-glossary,Advanced Technology Attachment]. ATM:: See crossref:glossary[atm-glossary,Asynchronous Transfer Mode]. [[aml-glossary]] ACPI Machine Language:: Pseudocode, interpreted by a virtual machine within an ACPI-compliant operating system, providing a layer between the underlying hardware and the documented interface presented to the OS. [[asl-glossary]] ACPI Source Language:: The programming language AML is written in. [[acl-glossary]] Access Control List:: A list of permissions attached to an object, usually either a file or a network device. [[acpi-glossary]] Advanced Configuration and Power Interface:: A specification which provides an abstraction of the interface the hardware presents to the operating system, so that the operating system should need to know nothing about the underlying hardware to make the most of it. ACPI evolves and supersedes the functionality provided previously by APM, PNPBIOS and other technologies, and provides facilities for controlling power consumption, machine suspension, device enabling and disabling, etc. [[api-glossary]] Application Programming Interface:: A set of procedures, protocols and tools that specify the canonical interaction of one or more program parts; how, when and why they do work together, and what data they share or operate on. [[apm-glossary]] Advanced Power Management:: An API enabling the operating system to work in conjunction with the BIOS in order to achieve power management. APM has been superseded by the much more generic and powerful ACPI specification for most applications. [[apic-glossary]] Advanced Programmable Interrupt Controller:: {empty} [[ata-glossary]] Advanced Technology Attachment:: {empty} [[atm-glossary]] Asynchronous Transfer Mode:: {empty} [[apop-glossary]] Authenticated Post Office Protocol:: {empty} [[amd-glossary]] Automatic Mount Daemon:: A daemon that automatically mounts a filesystem when a file or directory within that filesystem is accessed. [discrete] == B BAR:: See crossref:glossary[bar-glossary,Base Address Register]. BIND:: See crossref:glossary[bind-glossary,Berkeley Internet Name Domain]. BIOS:: See crossref:glossary[bios-glossary,Basic Input/Output System]. BSD:: See crossref:glossary[bsd-glossary,Berkeley Software Distribution]. [[bar-glossary]] Base Address Register:: The registers that determine which address range a PCI device will respond to. [[bios-glossary]] Basic Input/Output System:: The definition of BIOS depends a bit on the context. Some people refer to it as the ROM chip with a basic set of routines to provide an interface between software and hardware. Others refer to it as the set of routines contained in the chip that help in bootstrapping the system. Some might also refer to it as the screen used to configure the bootstrapping process. The BIOS is PC-specific but other systems have something similar. [[bind-glossary]] Berkeley Internet Name Domain:: An implementation of the DNS protocols. [[bsd-glossary]] Berkeley Software Distribution:: This is the name that the Computer Systems Research Group (CSRG) at link:http://www.berkeley.edu[The University of California at Berkeley] gave to their improvements and modifications to AT&T's 32V UNIX(R). FreeBSD is a descendant of the CSRG work. [[bikeshed-glossary]] Bikeshed Building:: A phenomenon whereby many people will give an opinion on an uncomplicated topic, whilst a complex topic receives little or no discussion. See the extref:{faq}[FAQ, bikeshed-painting] for the origin of the term. [discrete] == C CD:: See crossref:glossary[cd-glossary,Carrier Detect]. CHAP:: See crossref:glossary[chap-glossary,Challenge Handshake Authentication Protocol]. CLIP:: See crossref:glossary[clip-glossary,Classical IP over ATM]. COFF:: See crossref:glossary[coff-glossary,Common Object File Format]. CPU:: See crossref:glossary[cpu-glossary,Central Processing Unit]. CTS:: See crossref:glossary[cts-glossary,Clear To Send]. [[cd-glossary]] Carrier Detect:: An RS232C signal indicating that a carrier has been detected. [[cpu-glossary]] Central Processing Unit:: Also known as the processor. This is the brain of the computer where all calculations take place. There are a number of different architectures with different instruction sets. Among the more well-known are the Intel-x86 and derivatives, Arm, and PowerPC. [[chap-glossary]] Challenge Handshake Authentication Protocol:: A method of authenticating a user, based on a secret shared between client and server. [[clip-glossary]] Classical IP over ATM:: {empty} [[cts-glossary]] Clear To Send:: An RS232C signal giving the remote system permission to send data. + See crossref:glossary[rts-glossary,Also Request To Send]. [[coff-glossary]] Common Object File Format:: {empty} [discrete] == D DAC:: See crossref:glossary[dac-glossary,Discretionary Access Control]. DDB:: See crossref:glossary[ddb-glossary,Debugger]. DES:: See crossref:glossary[des-glossary,Data Encryption Standard]. DHCP:: See crossref:glossary[dhcp-glossary,Dynamic Host Configuration Protocol]. DNS:: See crossref:glossary[dns-glossary,Domain Name System]. DRM:: See crossref:glossary[drm-glossary,Direct Rendering Manager]. DSDT:: See crossref:glossary[dsdt-glossary,Differentiated System Description Table]. DSR:: See crossref:glossary[dsr-glossary,Data Set Ready]. DTR:: See crossref:glossary[dtr-glossary,Data Terminal Ready]. DVMRP:: See crossref:glossary[dvmrp-glossary,Distance-Vector Multicast Routing Protocol]. [[dac-glossary]] Discretionary Access Control:: {empty} [[des-glossary]] Data Encryption Standard:: A method of encrypting information, traditionally used as the method of encryption for UNIX(R) passwords and the man:crypt[3] function. [[dsr-glossary]] Data Set Ready:: An RS232C signal sent from the modem to the computer or terminal indicating a readiness to send and receive data. + See crossref:glossary[dtr-glossary,Also Data Terminal Ready]. [[dtr-glossary]] Data Terminal Ready:: An RS232C signal sent from the computer or terminal to the modem indicating a readiness to send and receive data. [[ddb-glossary]] Debugger:: An interactive in-kernel facility for examining the status of a system, often used after a system has crashed to establish the events surrounding the failure. [[dsdt-glossary]] Differentiated System Description Table:: An ACPI table, supplying basic configuration information about the base system. [[dvmrp-glossary]] Distance-Vector Multicast Routing Protocol:: {empty} [[dns-glossary]] Domain Name System:: The system that converts humanly readable hostnames (i.e., mail.example.net) to Internet addresses and vice versa. [[drm-glossary]] Direct Rendering Manager:: The man:drm[7] kernel module allows client applications direct access to the graphical hardware via the Direct Rendering Infrastructure. [[dhcp-glossary]] Dynamic Host Configuration Protocol:: A protocol that dynamically assigns IP addresses to a computer (host) when it requests one from the server. The address assignment is called a “lease”. [discrete] == E ECOFF:: See crossref:glossary[ecoff-glossary,Extended COFF]. ELF:: See crossref:glossary[elf-glossary,Executable and Linking Format]. ESP:: See crossref:glossary[esp-glossary,Encapsulated Security Payload]. +[[esp-glossary]] Encapsulated Security Payload:: {empty} [[elf-glossary]] Executable and Linking Format:: {empty} [[ecoff-glossary]] Extended COFF:: {empty} [discrete] == F FADT:: See crossref:glossary[fadt-glossary,Fixed ACPI Description Table]. FAT:: See crossref:glossary[fat-glossary,File Allocation Table]. FAT16:: See crossref:glossary[fat16-glossary,File Allocation Table (16-bit)]. FTP:: See crossref:glossary[ftp-glossary,File Transfer Protocol]. [[fat-glossary]] File Allocation Table:: {empty} [[fat16-glossary]] File Allocation Table (16-bit):: {empty} [[ftp-glossary]] File Transfer Protocol:: A member of the family of high-level protocols implemented on top of TCP which can be used to transfer files over a TCP/IP network. [[fadt-glossary]] Fixed ACPI Description Table:: {empty} [discrete] == G GUI:: See crossref:glossary[gui-glossary,Graphical User Interface]. [[giant-glossary]] Giant:: The name of a mutual exclusion mechanism (a sleep `mutex`) that protects a large set of kernel resources. Although a simple locking mechanism was adequate in the days where a machine might have only a few dozen processes, one networking card, and certainly only one processor, in current times it is an unacceptable performance bottleneck. FreeBSD developers are actively working to replace it with locks that protect individual resources, which will allow a much greater degree of parallelism for both single-processor and multi-processor machines. [[gui-glossary]] Graphical User Interface:: A system where the user and computer interact with graphics. [discrete] == H HTML:: See crossref:glossary[html-glossary,HyperText Markup Language]. HUP:: See crossref:glossary[hup-glossary,HangUp]. [[hup-glossary]] HangUp:: {empty} [[html-glossary]] HyperText Markup Language:: The markup language used to create web pages. [discrete] == I I/O:: See crossref:glossary[io-glossary,Input/Output]. IASL:: See crossref:glossary[iasl-glossary,Intel’s ASL compiler]. IMAP:: See crossref:glossary[imap-glossary,Internet Message Access Protocol]. IP:: See crossref:glossary[ip-glossary,Internet Protocol]. IPFW:: See crossref:glossary[ipfw-glossary,IP Firewall]. IPP:: See crossref:glossary[ipp-glossary,Internet Printing Protocol]. IPv4:: See crossref:glossary[ipv4-glossary,IP Version 4]. IPv6:: See crossref:glossary[ipv6-glossary,IP Version 6]. ISP:: See crossref:glossary[isp-glossary,Internet Service Provider]. [[ipfw-glossary]] IP Firewall:: {empty} [[ipv4-glossary]] IP Version 4:: The IP protocol version 4, which uses 32 bits for addressing. This version is still the most widely used, but it is slowly being replaced with IPv6. + See crossref:glossary[ipv6-glossary,Also IP Version 6]. [[ipv6-glossary]] IP Version 6:: The new IP protocol. Invented because the address space in IPv4 is running out. Uses 128 bits for addressing. [[io-glossary]] Input/Output:: {empty} [[iasl-glossary]] Intel’s ASL compiler:: Intel’s compiler for converting ASL into AML. [[imap-glossary]] Internet Message Access Protocol:: A protocol for accessing email messages on a mail server, characterised by the messages usually being kept on the server as opposed to being downloaded to the mail reader client. + See Also Post Office Protocol Version 3. [[ipp-glossary]] Internet Printing Protocol:: {empty} [[ip-glossary]] Internet Protocol:: The packet transmitting protocol that is the basic protocol on the Internet. Originally developed at the U.S. Department of Defense and an extremely important part of the TCP/IP stack. Without the Internet Protocol, the Internet would not have become what it is today. For more information, see link:ftp://ftp.rfc-editor.org/in-notes/rfc791.txt[RFC 791]. [[isp-glossary]] Internet Service Provider:: A company that provides access to the Internet. [discrete] == K [[kame-glossary]] KAME:: Japanese for “turtle”, the term KAME is used in computing circles to refer to the link:http://www.kame.net/[KAME Project], who work on an implementation of IPv6. KDC:: See crossref:glossary[kdc-glossary,Key Distribution Center]. KLD:: See crossref:glossary[kld-glossary,Kernel ld(1)]. KMS:: See crossref:glossary[kms-glossary,Kernel Mode Setting]. KSE:: See crossref:glossary[kse-glossary,Kernel Scheduler Entities]. KVA:: See crossref:glossary[kva-glossary,Kernel Virtual Address]. Kbps:: See crossref:glossary[kbps-glossary,Kilo Bits Per Second]. [[kms-glossary]] Setting the display mode in kernel space. [[kld-glossary]] Kernel man:ld[1]:: A method of dynamically loading functionality into a FreeBSD kernel without rebooting the system. [[kse-glossary]] Kernel Scheduler Entities:: A kernel-supported threading system. See the link:http://www.freebsd.org/kse[project home page] for further details. [[kva-glossary]] Kernel Virtual Address:: {empty} [[kdc-glossary]] Key Distribution Center:: {empty} [[kbps-glossary]] Kilo Bits Per Second:: Used to measure bandwidth (how much data can pass a given point at a specified amount of time). Alternates to the Kilo prefix include Mega, Giga, Tera, and so forth. [discrete] == L LAN:: See crossref:glossary[lan-glossary,Local Area Network]. LOR:: See crossref:glossary[lor-glossary,Lock Order Reversal]. LPD:: See crossref:glossary[lpd-glossary,Line Printer Daemon]. [[lpd-glossary]] Line Printer Daemon:: {empty} [[lan-glossary]] Local Area Network:: A network used on a local area, e.g. office, home, or so forth. [[lor-glossary]] Lock Order Reversal:: The FreeBSD kernel uses a number of resource locks to arbitrate contention for those resources. A run-time lock diagnostic system found in FreeBSD-CURRENT kernels (but removed for releases), called man:witness[4], detects the potential for deadlocks due to locking errors. (man:witness[4] is actually slightly conservative, so it is possible to get false positives.) A true positive report indicates that “if you were unlucky, a deadlock would have happened here”. + True positive LORs tend to get fixed quickly, so check https://lists.FreeBSD.org/subscription/freebsd-current and the link:http://sources.zabbadoz.net/freebsd/lor.html[LORs Seen] page before posting to the mailing lists. [discrete] == M MAC:: See crossref:glossary[mac-glossary,Mandatory Access Control]. MADT:: See crossref:glossary[madt-glossary,Multiple APIC Description Table]. MFC:: See crossref:glossary[mfc-glossary,Merge From Current]. MFH:: See crossref:glossary[mfh-glossary,Merge From Head]. MFS:: See crossref:glossary[mfs-glossary,Merge From Stable]. MFV:: See crossref:glossary[mfv-glossary,Merge From Vendor]. MIT:: See crossref:glossary[mit-glossary,Massachusetts Institute of Technology]. MLS:: See crossref:glossary[mls-glossary,Multi-Level Security]. MOTD:: See crossref:glossary[motd-glossary,Message Of The Day]. MTA:: See crossref:glossary[mta-glossary,Mail Transfer Agent]. MUA:: See crossref:glossary[mua-glossary,Mail User Agent]. [[mta-glossary]] Mail Transfer Agent:: An application used to transfer email. An MTA has traditionally been part of the BSD base system. Today Sendmail is included in the base system, but there are many other MTAs, such as postfix, qmail and Exim. [[mua-glossary]] Mail User Agent:: An application used by users to display and write email. [[mac-glossary]] Mandatory Access Control:: {empty} [[mit-glossary]] Massachusetts Institute of Technology:: {empty} [[mfc-glossary]] Merge From Current:: To merge functionality or a patch from the -CURRENT branch to another, most often -STABLE. [[mfh-glossary]] Merge From Head:: To merge functionality or a patch from a repository HEAD to an earlier branch. [[mfs-glossary]] Merge From Stable:: In the normal course of FreeBSD development, a change will be committed to the -CURRENT branch for testing before being merged to -STABLE. On rare occasions, a change will go into -STABLE first and then be merged to -CURRENT. + This term is also used when a patch is merged from -STABLE to a security branch. + See crossref:glossary[mfc-glossary,Also Merge From Current]. [[mfv-glossary]] Merge From Vendor:: {empty} [[motd-glossary]] Message Of The Day:: A message, usually shown on login, often used to distribute information to users of the system. [[mls-glossary]] Multi-Level Security:: {empty} [[madt-glossary]] Multiple APIC Description Table:: {empty} [discrete] == N NAT:: See crossref:glossary[nat-glossary,Network Address Translation]. NDISulator:: See crossref:glossary[projectevil-glossary,Project Evil]. NFS:: See crossref:glossary[nfs-glossary,Network File System]. NTFS:: See crossref:glossary[ntfs-glossary,New Technology File System]. NTP:: See crossref:glossary[ntp-glossary,Network Time Protocol]. [[nat-glossary]] Network Address Translation:: A technique where IP packets are rewritten on the way through a gateway, enabling many machines behind the gateway to effectively share a single IP address. [[nfs-glossary]] Network File System:: {empty} [[ntfs-glossary]] New Technology File System:: A filesystem developed by Microsoft and available in its “New Technology” operating systems, such as Windows(R) 2000, Windows NT(R) and Windows(R) XP. [[ntp-glossary]] Network Time Protocol:: A means of synchronizing clocks over a network. [discrete] == O OBE:: See crossref:glossary[obe-glossary,Overtaken By Events]. ODMR:: See crossref:glossary[odmr-glossary,On-Demand Mail Relay]. OS:: See crossref:glossary[os-glossary,Operating System]. [[odmr-glossary]] On-Demand Mail Relay:: {empty} [[os-glossary]] Operating System:: A set of programs, libraries and tools that provide access to the hardware resources of a computer. Operating systems range today from simplistic designs that support only one program running at a time, accessing only one device to fully multi-user, multi-tasking and multi-process systems that can serve thousands of users simultaneously, each of them running dozens of different applications. [[obe-glossary]] Overtaken By Events:: Indicates a suggested change (such as a Problem Report or a feature request) which is no longer relevant or applicable due to such things as later changes to FreeBSD, changes in networking standards, the affected hardware having since become obsolete, and so forth. [discrete] == P PAE:: See crossref:glossary[pae-glossary,Physical Address Extensions]. PAM:: See crossref:glossary[pam-glossary,Pluggable Authentication Modules]. PAP:: See crossref:glossary[pap-glossary,Password Authentication Protocol]. PC:: See crossref:glossary[pc-glossary,Personal Computer]. PCNSFD:: See crossref:glossary[pcnfsd-glossary,Personal Computer Network File System Daemon]. PDF:: See crossref:glossary[pdf-glossary,Portable Document Format]. PID:: See crossref:glossary[pid-glossary,Process ID]. POLA:: See crossref:glossary[pola-glossary,Principle Of Least Astonishment]. POP:: See crossref:glossary[pop-glossary,Post Office Protocol]. POP3:: See crossref:glossary[pop3-glossary,Post Office Protocol Version 3]. PPD:: See crossref:glossary[ppd-glossary,PostScript Printer Description]. PPP:: See crossref:glossary[ppp-glossary,Point-to-Point Protocol]. PPPoA:: See crossref:glossary[pppoa-glossary,PPP over ATM]. PPPoE:: See crossref:glossary[pppoe-glossary,PPP over Ethernet]. [[pppoa-glossary]] PPP over ATM:: {empty} [[pppoe-glossary]] PPP over Ethernet:: {empty} PR:: See crossref:glossary[pr-glossary,Problem Report]. PXE:: See crossref:glossary[pxe-glossary,Preboot eXecution Environment]. [[pap-glossary]] Password Authentication Protocol:: {empty} [[pc-glossary]] Personal Computer:: {empty} [[pcnfsd-glossary]] Personal Computer Network File System Daemon:: {empty} [[pae-glossary]] Physical Address Extensions:: A method of enabling access to up to 64 GB of RAM on systems which only physically have a 32-bit wide address space (and would therefore be limited to 4 GB without PAE). [[pam-glossary]] Pluggable Authentication Modules:: {empty} [[ppp-glossary]] Point-to-Point Protocol:: {empty} [[pointyhat]] Pointy Hat:: A mythical piece of headgear, much like a dunce cap, awarded to any FreeBSD committer who breaks the build, makes revision numbers go backwards, or creates any other kind of havoc in the source base. Any committer worth his or her salt will soon accumulate a large collection. The usage is (almost always?) humorous. [[pdf-glossary]] Portable Document Format:: {empty} [[pop-glossary]] Post Office Protocol:: See Also Post Office Protocol Version 3. [[pop3-glossary]] Post Office Protocol Version 3:: A protocol for accessing email messages on a mail server, characterised by the messages usually being downloaded from the server to the client, as opposed to remaining on the server. + See crossref:glossary[imap-glossary,Also Internet Message Access Protocol]. [[ppd-glossary]] PostScript Printer Description:: {empty} [[pxe-glossary]] Preboot eXecution Environment:: {empty} [[pola-glossary]] Principle Of Least Astonishment:: As FreeBSD evolves, changes visible to the user should be kept as unsurprising as possible. For example, arbitrarily rearranging system startup variables in [.filename]#/etc/defaults/rc.conf# violates POLA. Developers consider POLA when contemplating user-visible system changes. [[prime-glossary]] PRIME:: A method of multiple physical graphics coprocessors coexisting by sharing their direct memory access buffers. [[pr-glossary]] Problem Report:: A description of some kind of problem that has been found in either the FreeBSD source or documentation. See extref:{problem-reports}[Writing FreeBSD Problem Reports]. [[pid-glossary]] Process ID:: A number, unique to a particular process on a system, which identifies it and allows actions to be taken against it. [[projectevil-glossary]] Project Evil:: The working title for the NDISulator, written by Bill Paul, who named it referring to how awful it is (from a philosophical standpoint) to need to have something like this in the first place. The NDISulator is a special compatibility module to allow Microsoft Windows(TM) NDIS miniport network drivers to be used with FreeBSD/i386. This is usually the only way to use cards where the driver is closed-source. See [.filename]#src/sys/compat/ndis/subr_ndis.c#. [discrete] == R RA:: See crossref:glossary[ra-glossary,Router Advertisement]. RAID:: See crossref:glossary[raid-glossary,Redundant Array of Inexpensive Disks]. RAM:: See crossref:glossary[ram-glossary,Random Access Memory]. RD:: See crossref:glossary[rd-glossary,Received Data]. RFC:: See crossref:glossary[rfc-glossary,Request For Comments]. RISC:: See crossref:glossary[risc-glossary,Reduced Instruction Set Computer]. RPC:: See crossref:glossary[rpc-glossary,Remote Procedure Call]. RS232C:: See crossref:glossary[rs232c-glossary,Recommended Standard 232C]. RTS:: See crossref:glossary[rts-glossary,Request To Send]. [[ram-glossary]] Random Access Memory:: {empty} [[rcs-glossary]] Revision Control System:: The _Revision Control System (RCS)_ is one of the oldest software suites that implement “revision control” for plain files. It allows the storage, retrieval, archival, logging, identification and merging of multiple revisions for each file. RCS consists of many small tools that work together. It lacks some of the features found in more modern revision control systems, like Git, but it is very simple to install, configure, and start using for a small set of files. + See crossref:glossary[svn-glossary,Also Subversion]. [[rd-glossary]] Received Data:: An RS232C pin or wire that data is received on. + See crossref:glossary[td-glossary,Also Transmitted Data]. [[rs232c-glossary]] Recommended Standard 232C:: A standard for communications between serial devices. [[risc-glossary]] Reduced Instruction Set Computer:: An approach to processor design where the operations the hardware can perform are simplified but made as general purpose as possible. This can lead to lower power consumption, fewer transistors and in some cases, better performance and increased code density. Examples of RISC processors include the Alpha, SPARC(R), ARM(R) and PowerPC(R). [[raid-glossary]] Redundant Array of Inexpensive Disks:: {empty} [[rpc-glossary]] Remote Procedure Call:: {empty} [[rfc-glossary]] Request For Comments:: A set of documents defining Internet standards, protocols, and so forth. See www.rfc-editor.org. + Also used as a general term when someone has a suggested change and wants feedback. [[rts-glossary]] Request To Send:: An RS232C signal requesting that the remote system commences transmission of data. + See crossref:glossary[cts-glossary,Also Clear To Send]. [[ra-glossary]] Router Advertisement:: {empty} [discrete] == S SCI:: See crossref:glossary[sci-glossary,System Control Interrupt]. SCSI:: See crossref:glossary[scsi-glossary,Small Computer System Interface]. SG:: See crossref:glossary[sg-glossary,Signal Ground]. SLAAC:: See crossref:glossary[slaac-glossary,StateLess Address AutoConfiguration]. SMB:: See crossref:glossary[smb-glossary,Server Message Block]. SMP:: See crossref:glossary[smp-glossary,Symmetric MultiProcessor]. SMTP:: See crossref:glossary[smtp-glossary,Simple Mail Transfer Protocol]. SMTP AUTH:: See crossref:glossary[smtpauth-glossary,SMTP Authentication]. SSH:: See crossref:glossary[ssh-glossary,Secure Shell]. STR:: See crossref:glossary[str-glossary,Suspend To RAM]. SVN:: See crossref:glossary[svn-glossary,Subversion]. [[slaac-glossary]] StateLess Address AutoConfiguration:: {empty} [[smtpauth-glossary]] SMTP Authentication:: {empty} [[smb-glossary]] Server Message Block:: {empty} [[sg-glossary]] Signal Ground:: An RS232 pin or wire that is the ground reference for the signal. [[smtp-glossary]] Simple Mail Transfer Protocol:: {empty} [[ssh-glossary]] Secure Shell:: {empty} [[scsi-glossary]] Small Computer System Interface:: {empty} [[svn-glossary]] Subversion:: Subversion is a version control system currently used by the FreeBSD project. [[str-glossary]] Suspend To RAM:: {empty} [[smp-glossary]] Symmetric MultiProcessor:: {empty} [[sci-glossary]] System Control Interrupt:: {empty} [discrete] == T TCP:: See crossref:glossary[tcp-glossary,Transmission Control Protocol]. TCP/IP:: See crossref:glossary[tcpip-glossary,Transmission Control Protocol/Internet Protocol]. TD:: See crossref:glossary[td-glossary,Transmitted Data]. TFTP:: See crossref:glossary[tftp-glossary,Trivial FTP]. TGT:: See crossref:glossary[tgt-glossary,Ticket-Granting Ticket]. TSC:: See crossref:glossary[tsc-glossary,Time Stamp Counter]. [[tgt-glossary]] Ticket-Granting Ticket:: {empty} [[tsc-glossary]] Time Stamp Counter:: A profiling counter internal to modern Pentium(R) processors that counts core frequency clock ticks. [[tcp-glossary]] Transmission Control Protocol:: A protocol that sits on top of (e.g.) the IP protocol and guarantees that packets are delivered in a reliable, ordered, fashion. [[tcpip-glossary]] Transmission Control Protocol/Internet Protocol:: The term for the combination of the TCP protocol running over the IP protocol. Much of the Internet runs over TCP/IP. [[td-glossary]] Transmitted Data:: An RS232C pin or wire that data is transmitted on. + See crossref:glossary[rd-glossary,Also Received Data]. [[tftp-glossary]] Trivial FTP:: {empty} [discrete] == U UDP:: See crossref:glossary[udp-glossary,User Datagram Protocol]. UFS1:: See crossref:glossary[ufs1-glossary,Unix File System Version 1]. UFS2:: See crossref:glossary[ufs2-glossary,Unix File System Version 2]. UID:: See crossref:glossary[uid-glossary,User ID]. URL:: See crossref:glossary[url-glossary,Uniform Resource Locator]. USB:: See crossref:glossary[usb-glossary,Universal Serial Bus]. [[url-glossary]] Uniform Resource Locator:: A method of locating a resource, such as a document on the Internet and a means to identify that resource. [[ufs1-glossary]] Unix File System Version 1:: The original UNIX(R) file system, sometimes called the Berkeley Fast File System. [[ufs2-glossary]] Unix File System Version 2:: An extension to UFS1, introduced in FreeBSD 5-CURRENT. UFS2 adds 64 bit block pointers (breaking the 1T barrier), support for extended file storage and other features. [[usb-glossary]] Universal Serial Bus:: A hardware standard used to connect a wide variety of computer peripherals to a universal interface. [[uid-glossary]] User ID:: A unique number assigned to each user of a computer, by which the resources and permissions assigned to that user can be identified. [[udp-glossary]] User Datagram Protocol:: A simple, unreliable datagram protocol which is used for exchanging data on a TCP/IP network. UDP does not provide error checking and correction like TCP. [discrete] == V VPN:: See crossref:glossary[vpn-glossary,Virtual Private Network]. [[vpn-glossary]] Virtual Private Network:: A method of using a public telecommunication such as the Internet, to provide remote access to a localized network, such as a corporate LAN. diff --git a/documentation/content/en/books/handbook/preface/_index.adoc b/documentation/content/en/books/handbook/preface/_index.adoc index dfed27ebd1..0c9fcd9dfb 100644 --- a/documentation/content/en/books/handbook/preface/_index.adoc +++ b/documentation/content/en/books/handbook/preface/_index.adoc @@ -1,333 +1,333 @@ --- title: Preface prev: books/handbook next: books/handbook/parti description: The FreeBSD newcomer will find that the first section of this book guides the user through the FreeBSD installation process and gently introduces the concepts and conventions that underpin UNIX tags: ["preface", "audience", "organization", "conventions", "acknowledgments"] showBookMenu: true weight: 1 params: path: "/books/handbook/preface/" --- [preface] [[book-preface]] = Preface :doctype: book :toc: macro :toclevels: 1 :icons: font :source-highlighter: rouge :experimental: :images-path: books/handbook/preface/ 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::[] [[preface-audience]] == Intended Audience The FreeBSD newcomer will find that the first section of this book guides the user through the FreeBSD installation process and gently introduces the concepts and conventions that underpin UNIX(R). Working through this section requires little more than the desire to explore, and the ability to take on board new concepts as they are introduced. Once reaching this far, the second, far larger, section of the Handbook is a comprehensive reference to all manner of topics of interest to FreeBSD system administrators. Some of these chapters may recommend to do some prior reading, and this is noted in the synopsis at the beginning of each chapter. For a list of additional sources of information, please see crossref:bibliography[bibliography,Bibliography]. [[preface-changes-from4]] == Fourth Edition The current version of the Handbook represents the cumulative effort of a working group that has been reviewing and updating all Handbook content. These are the major updates since the fourth edition of the Handbook. * The Handbook has been converted from link:https://docbook.org/[Docbook] to link:https://gohugo.io/[Hugo] and link:https://asciidoctor.org/[AsciiDoctor] * The link:https://docs.FreeBSD.org[FreeBSD Documentation Portal] has been created. * The crossref:introduction[introduction, Introduction] chapter has been updated to improve the FreeBSD history and fix minor typos. * The crossref:bsdinstall[bsdinstall, Install] chapter has been updated with an upgraded synopsis, the latest changes to the installer, refreshed images, added alt text to images, and the removal of references to specific versions. * The crossref:basics[basics, Basics] chapter has updated tables, command outputs, and directory structure per man:hier. * The crossref:ports[ports, Ports] chapter has been updated and now simplifies package searches, updates software examples (Nginx replaces Apache), improves the man:pkg[8] bootstrap process, and adds new instructions for configuring and managing packages, including blocking and unblocking. * The crossref:x11[x11, X11] chapter has been updated to reflect the current state of graphics in FreeBSD, remove outdated references to old Intel drivers, configurations, and compiz, and relocate desktop environment instructions (such as KDE Plasma and GNOME) to the Desktop Environments chapter, as these environments now also support Wayland in addition to X11. * The crossref:wayland[wayland,Wayland] chapter has been added with information about installing and configuring Wayland under FreeBSD. * The crossref:network[network, Network] chapter has been created to cover basic wired and wireless network configuration, including hostname, DNS, and troubleshooting. Sections on wired networks, wireless, and IPv6 have been moved and updated with improved command outputs, use of sysrc, and better AsciiDoc syntax. * The crossref:desktop[desktop, Desktop] chapter has been updated with upgraded installation instructions for KDE Plasma, GNOME, XFCE, MATE, Cinnamon, and LXQT, expanded browser options, a new development tools section, and updates to office productivity, document viewers, and finance sections. * The crossref:multimedia[multimedia, Multimedia] chapter has been reworked with updates to the sound section, new tables for sound mixers, audio players, and video players, guidance on automatic headphone switching, a new conferencing and meetings section, and a revised image scanners section. * The crossref:linuxemu[linuxemu, Linuxemu] chapter has been improved with updated instructions for setting up a Debian/Ubuntu base system using debootstrap. -* The crossref:config[config, Config] chapter has been renamed for accuracy, with updates to service management, cron and periodic, syslog, power management, and swap sections. A new entry on config files was added, and the outdated tuning section was removed. +* The crossref:config[config-tuning, Config] chapter has been renamed for accuracy, with updates to service management, cron and periodic, syslog, power management, and swap sections. A new entry on config files was added, and the outdated tuning section was removed. * The crossref:security[security, Security] chapter has been updated with enhancements to VPN over IPSec, securing accounts, password hashes, sudo/doas, and OpenSSH/OpenSSL. New sections have been added covering IDS, secure levels, file flags, Capsicum, NFSv4 ACLs, and resource limits. * The crossref:jails[jails, Jails] chapter has been updated to include details on jail types (Thick, Thin, VNET, and Linux Jails), host system configuration, networking options, the jail configuration file, setup procedures, upgrade methods, resource limits, and different jail managers and container solutions. * The crossref:mail[mail, Mail] chapter has been updated to include information on DMA, upgrades to Sendmail, instructions for changing DMA and Sendmail to use different MTAs, and the removal of Dialup and Fetchmail sections, along with a reorganization of the chapter. * The crossref:bibliography[bibliography,Bibliography] has been extensively updated. [[preface-changes-from3]] == Third Edition The current online version of the Handbook represents the cumulative effort of many hundreds of contributors over the past 10 years. The following are some of the significant changes since the two volume third edition was published in 2004: * crossref:wine[wine,WINE] has been added with information about how to run Windows(R) applications on FreeBSD. * crossref:dtrace[dtrace,DTrace] has been added with information about the powerful DTrace performance analysis tool. * crossref:filesystems[filesystems,Other File Systems] have been added with information about non-native file systems in FreeBSD, such as ZFS from Sun(TM). * crossref:audit[audit,Security Event Auditing] has been added to cover the new auditing capabilities in FreeBSD and explain its use. * crossref:virtualization[virtualization,Virtualization] has been added with information about installing FreeBSD on virtualization software. * crossref:bsdinstall[bsdinstall,Installing FreeBSD] has been added to cover installation of FreeBSD using the new installation utility, bsdinstall. [[preface-changes-from2]] == Second Edition (2004) The third edition was the culmination of over two years of work by the dedicated members of the FreeBSD Documentation Project. The printed edition grew to such a size that it was necessary to publish as two separate volumes. The following are the major changes in this new edition: * crossref:config[config-tuning,Configuration and Tuning] has been expanded with new information about the ACPI power and resource management, the `cron` system utility, and more kernel tuning options. * crossref:security[security,Security] has been expanded with new information about virtual private networks (VPNs), file system access control lists (ACLs), and security advisories. * crossref:mac[mac,Mandatory Access Control] is a new chapter with this edition. It explains what MAC is and how this mechanism can be used to secure a FreeBSD system. * crossref:disks[disks,Storage] has been expanded with new information about USB storage devices, file system snapshots, file system quotas, file and network backed filesystems, and encrypted disk partitions. * A troubleshooting section has been added to crossref:ppp-and-slip[ppp-and-slip,PPP]. * crossref:mail[mail,Electronic Mail] has been expanded with new information about using alternative transport agents, SMTP authentication, UUCP, fetchmail, procmail, and other advanced topics. * crossref:network-servers[network-servers,Network Servers] is all new with this edition. This chapter includes information about setting up the Apache HTTP Server, ftpd, and setting up a server for Microsoft(R) Windows(R) clients with Samba. Some sections from crossref:advanced-networking[advanced-networking,Advanced Networking] were moved here to improve the presentation. * crossref:advanced-networking[advanced-networking,Advanced Networking] has been expanded with new information about using Bluetooth(R) devices with FreeBSD, setting up wireless networks, and Asynchronous Transfer Mode (ATM) networking. * A glossary has been added to provide a central location for the definitions of technical terms used throughout the book. * A number of aesthetic improvements have been made to the tables and figures throughout the book. [[preface-changes]] == First Edition (2001) The second edition was the culmination of over two years of work by the dedicated members of the FreeBSD Documentation Project. The following were the major changes in this edition: * A complete Index has been added. * All ASCII figures have been replaced by graphical diagrams. * A standard synopsis has been added to each chapter to give a quick summary of what information the chapter contains, and what the reader is expected to know. * The content has been logically reorganized into three parts: "Getting Started", "System Administration", and "Appendices". * crossref:basics[basics,FreeBSD Basics] has been expanded to contain additional information about processes, daemons, and signals. * crossref:ports[ports,Installing Applications: Packages and Ports] has been expanded to contain additional information about binary package management. * crossref:x11[x11,The X Window System] has been completely rewritten with an emphasis on using modern desktop technologies such as KDE and GNOME on XFree86(TM) 4.X. * crossref:boot[boot,The FreeBSD Booting Process] has been expanded. * crossref:disks[disks,Storage] has been written from what used to be two separate chapters on "Disks" and "Backups". We feel that the topics are easier to comprehend when presented as a single chapter. A section on RAID (both hardware and software) has also been added. * crossref:serialcomms[serialcomms,Serial Communications] has been completely reorganized and updated for FreeBSD 4.X/5.X. * crossref:ppp-and-slip[ppp-and-slip,PPP] has been substantially updated. * Many new sections have been added to crossref:advanced-networking[advanced-networking,Advanced Networking]. * crossref:mail[mail,Electronic Mail] has been expanded to include more information about configuring sendmail. * crossref:linuxemu[linuxemu,Linux® Binary Compatibility] has been expanded to include information about installing Oracle(R) and SAP(R) R/3(R). * The following new topics are covered in this second edition: ** crossref:config[config-tuning,Configuration and Tuning]. ** crossref:multimedia[multimedia,Multimedia]. [[preface-overview]] == Organization of This Book This book is split into five logically distinct sections. The first section, _Getting Started_, covers the installation and basic usage of FreeBSD. It is expected that the reader will follow these chapters in sequence, possibly skipping chapters covering familiar topics. The second section, _Common Tasks_, covers some frequently used features of FreeBSD. This section, and all subsequent sections, can be read out of order. Each chapter begins with a succinct synopsis that describes what the chapter covers and what the reader is expected to already know. This is meant to allow the casual reader to skip around to find chapters of interest. The third section, _System Administration_, covers administration topics. The fourth section, _Network Communication_, covers networking and server topics. The fifth section contains appendices of reference information. _crossref:introduction[introduction,Introduction]_:: Introduces FreeBSD to a new user. It describes the history of the FreeBSD Project, its goals and development model. _crossref:bsdinstall[bsdinstall,Installing FreeBSD]_:: Walks a user through the entire installation process of FreeBSD 9._x_ and later using bsdinstall. _crossref:basics[basics,FreeBSD Basics]_:: Covers the basic commands and functionality of the FreeBSD operating system. When familiar with Linux(R) or another flavor of UNIX(R) then this chapter can probably be skipped. _crossref:ports[ports,Installing Applications: Packages and Ports]_:: Covers the installation of third-party software with both FreeBSD's innovative "Ports Collection" and standard binary packages. _crossref:x11[x11,The X Window System]_:: Describes the X Window System in general and using X11 on FreeBSD in particular. Also describes common desktop environments such as KDE and GNOME. _crossref:wayland[wayland,Wayland]_:: Describes the Wayland display server in general and using Wayland on FreeBSD in particular. Also describes common compositors such as Wayfire, Hikari and Sway. _crossref:desktop[desktop,Desktop Applications]_:: Lists some common desktop applications, such as web browsers and productivity suites, and describes how to install them on FreeBSD. _crossref:multimedia[multimedia,Multimedia]_:: Shows how to set up sound and video playback support for the system. Also describes some sample audio and video applications. _crossref:kernelconfig[kernelconfig,Configuring the FreeBSD Kernel]_:: Explains the need to configure a new kernel and provides detailed instructions for configuring, building, and installing a custom kernel. _crossref:printing[printing,Printing]_:: Describes managing printers on FreeBSD, including information about banner pages, printer accounting, and initial setup. _crossref:linuxemu[linuxemu,Linux® Binary Compatibility]_:: Describes the Linux(R) compatibility features of FreeBSD. Also provides detailed installation instructions for many popular Linux(R) applications such as Oracle(R) and Mathematica(R). _crossref:wine[wine,WINE]_:: Describes WINE and provides detailed installation instructions. Also describes how WINE operates, how to install a GUI helper, how to run Windows(R) applications on FreeBSD, and offers other tips and solutions. _crossref:config[config-tuning,Configuration and Tuning]_:: Describes the parameters available for system administrators to tune a FreeBSD system for optimum performance. Also describes the various configuration files used in FreeBSD and where to find them. _crossref:boot[boot,The FreeBSD Booting Process]_:: Describes the FreeBSD boot process and explains how to control this process with configuration options. _crossref:security[security,Security]_:: Describes many different tools available to help keep the FreeBSD system secure, including Kerberos, IPsec and OpenSSH. _crossref:jails[jails,Jails]_:: Describes the jails framework, and the improvements of jails over the traditional chroot support of FreeBSD. _crossref:mac[mac,Mandatory Access Control]_:: Explains what Mandatory Access Control (MAC) is and how this mechanism can be used to secure a FreeBSD system. _crossref:audit[audit,Security Event Auditing]_:: Describes what FreeBSD Event Auditing is, how it can be installed, configured, and how audit trails can be inspected or monitored. _crossref:disks[disks,Storage]_:: Describes how to manage storage media and filesystems with FreeBSD. This includes physical disks, RAID arrays, optical and tape media, memory-backed disks, and network filesystems. _crossref:geom[geom,GEOM: Modular Disk Transformation Framework]_:: Describes what the GEOM framework in FreeBSD is and how to configure various supported RAID levels. _crossref:zfs[zfs,The OpenZFS storage platform]_:: Describes the OpenZFS storage platform and provides a quick-start guide and information about advanced topics running OpenZFS under FreeBSD. _crossref:filesystems[filesystems,Other File Systems]_:: Examines support for non-native file systems under FreeBSD like ext2, ext3 and ext4. _crossref:virtualization[virtualization,Virtualization]_:: Describes what virtualization systems offer, and how they can be used with FreeBSD. _crossref:l10n[l10n,Localization - i18n/L10n Usage and Setup]_:: Describes how to use FreeBSD in languages other than English. Covers both system and application level localization. _crossref:cutting-edge[updating-upgrading,Updating and Upgrading FreeBSD]_:: Explains the differences between FreeBSD-STABLE, FreeBSD-CURRENT, and FreeBSD releases. Describes which users would benefit from tracking a development system and outlines that process. Covers the methods users may take to update their system to the latest security release. _crossref:dtrace[dtrace,DTrace]_:: Describes how to configure and use the DTrace tool from Sun(TM) on FreeBSD. Dynamic tracing can help locate performance issues, by performing real time system analysis. _crossref:usb-device-mode[usb-device-mode,USB Device Mode / USB OTG]_:: Explains the use of USB Device Mode and USB On The Go (USB OTG) on FreeBSD. _crossref:ppp-and-slip[ppp-and-slip,PPP]_:: Describes how to use PPP to connect to remote systems in FreeBSD. _crossref:mail[mail,Electronic Mail]_:: Explains the different components of an email server and dives into simple configuration topics for the most popular mail server software: sendmail. _crossref:network-servers[network-servers,Network Servers]_:: Provides detailed instructions and example configuration files to set up the FreeBSD machine as a network filesystem server, domain name server, network information system server, or time synchronization server. _crossref:firewalls[firewalls,Firewalls]_:: Explains the philosophy behind software-based firewalls and provides detailed information about the configuration of the different firewalls available for FreeBSD. _crossref:advanced-networking[advanced-networking,Advanced Networking]_:: Describes many networking topics, including sharing an Internet connection with other computers on the LAN, advanced routing topics, wireless networking, Bluetooth(R), ATM, IPv6, and much more. _crossref:mirrors[mirrors,Obtaining FreeBSD]_:: Lists different sources for obtaining FreeBSD media on CDROM or DVD as well as different sites on the Internet that allows to download and install FreeBSD. _crossref:bibliography[bibliography,Bibliography]_:: This book touches on many different subjects that may leave readers hungry for a more detailed explanation. The bibliography lists many excellent books that are referenced in the text. _crossref:eresources[eresources,Resources on the Internet]_:: Describes the many forums available for FreeBSD users to post questions and engage in technical conversations about FreeBSD. _crossref:pgpkeys[pgpkeys,OpenPGP Keys]_:: Lists the PGP fingerprints of several FreeBSD Developers. [[preface-conv]] == Conventions used in this book To provide a consistent and easy to read text, several conventions are followed throughout the book. [[preface-conv-typographic]] === Typographic Conventions _Italic_:: An _italic_ font is used for filenames, URLs, emphasized text, and the first usage of technical terms. `Monospace`:: A `monospaced` font is used for error messages, commands, environment variables, names of ports, hostnames, user names, group names, device names, variables, and code fragments. *Bold*:: A *bold* font is used for applications, commands, and keys. [[preface-conv-commands]] === User Input Keys are shown in *bold* to stand out from other text. Key combinations that are meant to be typed simultaneously are shown with `+` between the keys, such as: kbd:[Ctrl+Alt+Del] Meaning the user should type the kbd:[Ctrl], kbd:[Alt], and kbd:[Del] keys at the same time. Keys that are meant to be typed in sequence will be separated with commas, for example: kbd:[Ctrl+X], kbd:[Ctrl+S] Would mean that the user is expected to type the kbd:[Ctrl] and kbd:[X] keys simultaneously and then to type the kbd:[Ctrl] and kbd:[S] keys simultaneously. [[preface-conv-examples]] === Examples Examples starting with [.filename]#C:\># indicate a MS-DOS(R) command. Unless otherwise noted, these commands may be executed from a "Command Prompt" window in a modern Microsoft(R) Windows(R) environment. [source,shell] .... C:\> tools\fdimage floppies\kern.flp A: .... Examples starting with # indicate a command that must be invoked as the superuser in FreeBSD. Login as `root` to type the command, or login as the normal account and use man:su[1] to gain superuser privileges. [source,shell] .... # dd if=kern.flp of=/dev/fd0 .... Examples starting with % indicate a command that should be invoked from a normal user account. Unless otherwise noted, C-shell syntax is used for setting environment variables and other shell commands. [source,shell] .... % top .... [[preface-acknowledgements]] == Acknowledgments This book represents the efforts of many hundreds of people around the world. Whether they sent in fixes for typos, or submitted complete chapters, all the contributions have been useful. Several companies have supported the development of this document by paying authors to work on it full-time, paying for publication, etc. In particular, BSDi (subsequently acquired by http://www.windriver.com[Wind River Systems]) paid members of the FreeBSD Documentation Project to work on improving this book full time leading up to the publication of the first printed edition in March 2000 (ISBN 1-57176-241-8). Wind River Systems then paid several additional authors to make a number of improvements to the print-output infrastructure and to add additional chapters to the text. This work culminated in the publication of the second printed edition in November 2001 (ISBN 1-57176-303-1). In 2003-2004, http://www.freebsdmall.com[FreeBSD Mall, Inc], paid several contributors to improve the Handbook in preparation for the third printed edition. The third printed edition has been split into two volumes. Both volumes have been published as The FreeBSD Handbook 3rd Edition Volume 1: User Guide (ISBN 1-57176-327-9) and The FreeBSD Handbook 3rd Edition Volume 2: Administrators Guide (ISBN 1-57176-328-7). diff --git a/documentation/content/en/books/handbook/x11/_index.adoc b/documentation/content/en/books/handbook/x11/_index.adoc index 46d9c3caad..f549ceffec 100644 --- a/documentation/content/en/books/handbook/x11/_index.adoc +++ b/documentation/content/en/books/handbook/x11/_index.adoc @@ -1,1055 +1,1055 @@ --- title: Chapter 5. The X Window System part: Part I. Getting Started prev: books/handbook/ports next: books/handbook/wayland description: This chapter describes how to install and configure the X Window System providing a graphical environment tags: ["AMD", "DRM", "Fonts", "Graphics", "Input", "Intel", "Monitor", "NVIDIA", "PRIME", "SCFB", "TrueType", "VESA", "Video", "X11", "Xf86", "Xorg"] showBookMenu: true weight: 7 params: path: "/books/handbook/x11/" --- [[x11]] = The X Window System :doctype: book :toc: macro :toclevels: 2 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 5 :partnums: :source-highlighter: rouge :experimental: :images-path: books/handbook/x11/ 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::[] [[x11-synopsis]] == Synopsis An crossref:bsdinstall[bsdinstall-synopsis,installation] of FreeBSD using man:bsdinstall[8] does not automatically install a graphical user interface. This chapter describes how to install and configure the man:Xorg[1] server, which provides the open source X Window System (colloquially X11) used to provide a graphical environment. Before reading this chapter: * Know how to install additional third-party software as described in crossref:ports[ports,Installing Applications: Packages and Ports]. Read this chapter to learn: * How to select and install drivers for the graphics processor (GPU). * The various components of the X Window System, and how they interoperate. * How to install and configure the X.org server. * How to install fonts for the X Window System. [[x-graphic-card-drivers]] == Graphics Drivers _**abstract**: Identify the GPU, the port providing a driver for it, install it, then enable it to run at subsequent boot with man:sysrc[8]._ Before FreeBSD can render a graphical environment, it needs a kernel module to drive the graphics processor. Graphics drivers are a fast-moving, cross-platform target, which is why this is developed and distributed separately from the FreeBSD base system. The following table shows the different graphics processors supported by FreeBSD, their corresponding module, and which port provides it: .Supported Graphics Devices [options="header", cols="1,1,1,1"] |=== | Type | License | Module | Port | Intel(R) | Open Source | `i915kms` | package:graphics/drm-kmod[] | AMD(R) | Open Source | `amdgpu` or `radeonkms` | package:graphics/drm-kmod[] | NVIDIA(R) | Proprietary | `nvidia-drm`, `nvidia-modeset`, or `nvidia` | package:graphics/nvidia-drm-kmod[] or + package:x11/nvidia-driver[] | System Console Framebuffer | Open Source | `scfb` | package:x11-drivers/xf86-video-scfb[] | VESA BIOS Extension | Open Source | `vesa` | package:x11-drivers/xf86-video-vesa[] | VirtualBox(R) | Open Source | `vboxvideo` | package:emulators/virtualbox-ose-additions[] | VMware(R) | Open Source | `vmwgfx` | package:x11-drivers/xf86-video-vmware[] |=== There are several generations of driver technologies supported. * Direct Rendering drivers allowing PRIME offloading. PRIME allows for multiple providers of graphics processing to coexist. PRIME is described further in <>. * Kernel Modesetting (crossref:glossary[kms-glossary,KMS]) This allows the driver to directly specify the display mode. This is required to support suspend and resume when using the man:vt[4] console driver. * User Modesetting The oldest class of drivers is still supported, however they may only be used with man:sc[4] console and older versions of the man:Xorg[1] graphical environment. The following command can be used to identify which graphics processor is installed in the system: [source,shell] .... % pciconf -lv | grep -B3 display .... The output should be similar to the following: [.programlisting] .... vgapci1@pci0:0:2:0: class=0x030000 rev=0x0c hdr=0x00 vendor=0x8086 device=0x46a6 subvendor=0x1028 subdevice=0x0b29 vendor = 'Intel Corporation' device = 'Alder Lake-P GT2 [Iris Xe Graphics]' class = display .... Detailed instructions on installing and enabling these drivers are in the subsequent subsections. [WARNING] ==== If the graphics processor is not supported by Intel(R), AMD(R), or NVIDIA(R) drivers, then SCFB or VESA modules should be used. SCFB module must be used when booting in UEFI mode. VESA module must be used when booting in BIOS mode. This command can be used to check the booting mode: [source,shell] .... % sysctl machdep.bootmethod .... The output should be similar to the following: [.programlisting] .... machdep.bootmethod: UEFI .... ==== [[x-configuration-intel]] === Intel(R) Graphics The package:graphics/drm-kmod[] package indirectly provides a range of kernel modules for use with Intel(R) Graphics. Recent versions of these modules can be used in conjunction with other graphics processors in PRIME with no special configuration. The Intel(R) Graphics driver can be installed by executing the following command: [source,shell] .... # pkg install drm-kmod .... Then add the module to [.filename]#/etc/rc.conf# file, by executing the following command: [source,shell] .... # sysrc kld_list+=i915kms .... [[x-configuration-amd]] === AMD(R) Graphics The package:graphics/drm-kmod[] package indirectly provides kernel modules for a range of AMD(R) Graphics processors. The modules `amdgpu` or `radeonkms` can be used depending the generation of the hardware. The FreeBSD project maintains a link:https://wiki.freebsd.org/Graphics/AMD-GPU-Matrix[AMD graphics support matrix] showing support levels and to determine which driver must be used. The AMD(R) Graphics drivers can be installed by executing the following command: [source,shell] .... # pkg install drm-kmod .... Enable the current module by adding it to the [.filename]#/etc/rc.conf# file, executing the following command: [source,shell] .... # sysrc kld_list+=amdgpu .... For older graphics (pre-HD7000/Tahiti), instead enable the legacy module by adding it to the [.filename]#/etc/rc.conf# file, executing the following command: [source,shell] .... # sysrc kld_list+=radeonkms .... [[x-configuration-nvidia]] === NVIDIA(R) Graphics NVIDIA(R) produces standalone or discrete graphics processors, and provides a proprietary driver for FreeBSD. The FreeBSD Ports Collection provides over a decade of drivers for supporting generations of NVIDIA graphics. Administrators should install the latest driver supported by their hardware. The following table shows the port containing the driver, the kernel module recommended for loading, and a link to the list of hardware supported by that driver: .Supported versions of NVIDIA(R) Graphics drivers [options="header", cols="1,1,1"] |=== | Port | Module | Supported hardware | package:graphics/nvidia-drm-kmod[] | `nvidia-drm` or + `nvidia-modeset` | link:https://www.nvidia.com/Download/driverResults.aspx/210651/en-us/[supported hardware] | package:x11/nvidia-driver-470[] | `nvidia-modeset` | link:https://www.nvidia.com/Download/driverResults.aspx/194639/en-us/[supported hardware] | package:x11/nvidia-driver-390[] or + package:x11/nvidia-secondary-driver-390[] | `nvidia-modeset` | link:https://www.nvidia.com/Download/driverResults.aspx/191122/en-us/[supported hardware] | package:x11/nvidia-driver-340[] | `nvidia` | link:https://www.nvidia.com/Download/driverResults.aspx/156167/en-us/[supported hardware] | package:x11/nvidia-driver-304[] | `nvidia` | link:https://www.nvidia.com/Download/driverResults.aspx/123712/en-us/[supported hardware] |=== The latest NVIDIA(R) Graphics driver can be installed by running the following command: [source,shell] .... # pkg install nvidia-drm-kmod .... To enable the driver, add the module to [.filename]#/etc/rc.conf# file, by executing the following command: [source,shell] .... # sysrc kld_list+=nvidia-drm .... -This is the direct rendering crossref:glossary[glossary-kms,KMS] driver. +This is the direct rendering crossref:glossary[kms-glossary,KMS] driver. Kernel modesetting is the option to set the graphics mode in the kernel. Enable it for subsequent boots with the following man:loader.conf[5] tunable: [source,shell] .... hw.nvidiadrm.modeset="1" .... Both PRIME and crossref:wayland[wayland-synopsis,Wayland] require kernel modesetting. Prior versions of the driver do not support Direct Rendering. Instead use the modesetting module, by executing the following command: [source,shell] .... # sysrc kld_list+=nvidia-modeset .... If requiring Nvidia drivers prior to 390, note that they do not support kernel modesetting, and thus they must be used with the legacy man:sc[4] console driver, and a package:x11/xorg-server[] version prior to 1.20. Enable them in [.filename]#/etc/rc.conf# with the following command: [source,shell] .... # sysrc kld_list+=nvidia .... [[x-overview]] == X Window System Overview The X Window System is the heritage graphical stack for UNIX(R) platforms, supporting the latest technologies while maintaining support for generations of applications. Applications, including the components of the desktop, are hosted by the man:Xorg[1] server. This system is network aware and its various components can interoperate across networks. [[x-install]] == Installing The X.org Server _**abstract**: The package:x11/xorg[X.org] server must be installed to host the crossref:desktop[desktop-synopsis,desktop]. Users must be added to the `video` group to use it._ Once a graphics driver is installed and enabled, the X.org server can be installed as a meta-package, or compiled locally with the ports tree. The full meta-package can be installed quickly but with fewer options for customization: [source,shell] .... # pkg install xorg .... This installation results in the complete X Window System being installed, including a traditional window manager, man:twm[1], and surrounding traditional desktop suite. Most users will want to install and configure a contemporary crossref:desktop[desktop-synopsis,desktop] of their choice. The current user must be a member of the `video` group to run a graphical environment. To add a user to the `video` group, execute the following command: [source,shell] .... # pw groupmod video -m username .... To run the X Window System, use man:startx[1] from package:x11/xinit[], or install and configure a display manager to start a graphical login on boot. [TIP] ==== A smaller version of the X Window System suitable for experienced users is available in package:x11/xorg-minimal[]. Most of the documents, libraries, and applications will not be installed. Some applications require these additional components to function. ==== [[x-config]] == X.org Configuration _**abstract**: If the defaults for the monitor or input devices, are not satisfactory, crossref:desktop[desktop-synopsis,desktops] include GUIs for configuring them, or they can be configured manually._ The X.org server supports most common graphics processors, monitors, and input devices. First, try the defaults. This subsection provides an overview of their configuration. [[x-config-files]] === X.org Configuration Files Historically, the X.org server was configured with files in [.filename]#/usr/local/etc/X11/#. This is still supported for edge cases, but conflicts with dynamic autoconfiguration. Do not create configuration for the X.org server in [.filename]#xorg.conf# or run `Xorg -configure` unless automatic configuration fails. X.org server looks in several directories for configuration files. [.filename]#/usr/local/etc/X11/# is the *recommended* directory for these files on FreeBSD. Using this directory helps keep application files separate from operating system files. It is easier to use multiple files that each configure a specific setting than the traditional single [.filename]#xorg.conf#. These files are stored in the [.filename]#/usr/local/etc/X11/xorg.conf.d/# subdirectory. [[x-config-gpu]] === Graphics Configuration Direct rendering provides the ability to seamlessly use a discrete graphics processor (dGPU) alongside an integrated graphics processor (iGPU), called PRIME. The drivers will automatically offload intensive tasks to the dGPU when required, and power it down when able. To launch applications on the more powerful GPU in PRIME, use the `DRI_PRIME=1` enviroment variable. If multiple graphics drivers are conflicting, the driver for the graphics processor can be specified in the [.filename]#/usr/local/etc/X11/xorg.conf.d/# directory. To configure the Intel(R) driver in a configuration file: [[x-config-video-cards-file-intel]] .Select Intel(R) Graphics Driver in a File [example] ==== [.filename]#/usr/local/etc/X11/xorg.conf.d/20-intel.conf# [.programlisting] .... Section "Device" Identifier "Card0" Driver "intel" EndSection .... ==== To configure the AMD(R) driver in a configuration file: [[x-config-video-cards-file-amd]] .Select AMD(R) Graphics Driver in a File [example] ==== [.filename]#/usr/local/etc/X11/xorg.conf.d/20-radeon.conf# [.programlisting] .... Section "Device" Identifier "Card0" Driver "radeon" EndSection .... ==== To configure the NVIDIA(R) driver in a configuration file: [[x-config-video-cards-file-nvidia]] .Select NVIDIA(R) Graphics Driver in a File [example] ==== [.filename]#/usr/local/etc/X11/xorg.conf.d/20-nvidia.conf# [.programlisting] .... Section "Device" Identifier "Card0" Driver "nvidia-modeset" EndSection .... ==== [TIP] ==== package:x11/nvidia-xconfig[] can also be used to perform basic control over configuration options available in the NVIDIA driver. ==== To configure the SCFB driver in a configuration file: [[x-config-video-cards-file-sfcb]] .Select SCFB Graphics Driver in a File [example] ==== [.filename]#/usr/local/etc/X11/xorg.conf.d/20-scfb.conf# [.programlisting] .... Section "Device" Identifier "Card0" Driver "scfb" EndSection .... ==== To configure the VESA driver in a configuration file: [[x-config-video-cards-file-vesa]] .Select VESA Graphics Driver in a File [example] ==== [.filename]#/usr/local/etc/X11/xorg.conf.d/20-vesa.conf# [.programlisting] .... Section "Device" Identifier "Card0" Driver "vesa" EndSection .... ==== To configure multiple graphics processors, the `BusID` can be added. A list of graphics processor bus ``ID``s can be displayed by executing: [source,shell] .... % pciconf -lv | grep -B3 display .... The output should be similar to the following: [.programlisting] .... vgapci0@pci0:0:2:0: class=0x030000 rev=0x0c hdr=0x00 vendor=0x8086 device=0x46a6 subvendor=0x1028 subdevice=0x0b29 vendor = 'Intel Corporation' device = 'Alder Lake-P GT2 [Iris Xe Graphics]' class = display -- vgapci0@pci0:1:0:0: class=0x030200 rev=0xa1 hdr=0x00 vendor=0x10de device=0x25b9 subvendor=0x1028 subdevice=0x0b29 vendor = 'NVIDIA Corporation' device = 'GA107GLM [RTX A1000 Laptop GPU]' class = display .... [[x-config-video-cards-file-multiple]] .Select Intel(R) Graphics Driver and NVIDIA(R) Graphics Driver in a File [example] ==== [.filename]#/usr/local/etc/X11/xorg.conf.d/20-drivers.conf# [.programlisting] .... Section "Device" Identifier "Card0" Driver "intel" BusID "pci0:0:2:0" EndSection Section "Device" Identifier "Card1" Driver "nvidia-modeset" BusID "pci0:0:2:1" EndSection .... ==== [[x-config-monitors]] === Monitor Configuration Almost all monitors support the Extended Display Identification Data standard (`EDID`). X.org uses `EDID` to communicate with the monitor and detect the supported resolutions and refresh rates. Then it selects the most appropriate combination of settings to use with that monitor. Other resolutions supported by the monitor can be selected atomically after the X server has been started with man:xrandr[1], or in the X.org server configuration files. [[x-config-monitors-xrandr]] ==== Using RandR (Resize and Rotate) Run man:xrandr[1] in an X session without any parameters to see a list of video outputs and detected monitor modes: [source,shell] .... % xrandr .... The output should be similar to the following: [.programlisting] .... Screen 0: minimum 320 x 200, current 2560 x 960, maximum 8192 x 8192 LVDS-1 connected 1280x800+0+0 (normal left inverted right x axis y axis) 261mm x 163mm 1280x800 59.99*+ 59.81 59.91 50.00 1280x720 59.86 59.74 1024x768 60.00 1024x576 59.90 59.82 960x540 59.63 59.82 800x600 60.32 56.25 864x486 59.92 59.57 640x480 59.94 720x405 59.51 58.99 640x360 59.84 59.32 VGA-1 connected primary 1280x960+1280+0 (normal left inverted right x axis y axis) 410mm x 257mm 1280x1024 75.02 60.02 1440x900 74.98 60.07 1280x960 60.00* 1280x800 74.93 59.81 1152x864 75.00 1024x768 75.03 70.07 60.00 832x624 74.55 800x600 72.19 75.00 60.32 56.25 640x480 75.00 72.81 66.67 59.94 720x400 70.08 HDMI-1 disconnected (normal left inverted right x axis y axis) DP-1 disconnected (normal left inverted right x axis y axis) HDMI-2 disconnected (normal left inverted right x axis y axis) DP-2 disconnected (normal left inverted right x axis y axis) DP-3 disconnected (normal left inverted right x axis y axis) .... This shows that the `VGA-1` output is being used to display a screen resolution of 1280x960 pixels at a refresh rate of about 60 Hz. The `LVDS-1` is being used as a secondary monitor to display a screen resolution of 1280x800 pixels at a refresh rate of about 60 Hz. Monitors are not attached to the `HDMI-1`, `HDMI-2`, `DP-1`, `DP-2`, and `DP-3` connectors. Any of the other display modes can be selected with man:xrandr[1]. For example, to switch to 1280x1024 at 60 Hz: [source,shell] .... % xrandr --output LVDS-1 --mode 1280x720 --rate 60 .... [TIP] ==== Oftentimes, a black screen upon starting X can be fixed by adding an `xrandr --auto` step to the initialization process. ==== [[x-config-monitors-file]] ==== Using the X.org Configuration Files The monitor configuration can also be set in a configuration file. To set a screen resolution of 1024x768 in a configuration file: .Set Screen Resolution in a File [example] ==== [.filename]#/usr/local/etc/X11/xorg.conf.d/10-monitor.conf# [.programlisting] .... Section "Screen" Identifier "Screen0" Device "Card0" SubSection "Display" Modes "1024x768" EndSubSection EndSection .... ==== [[x-config-input]] === Input Configuration The package:Xorg[X.org] server provides the package:x11/libinput[] library, a cross-platform effort to support all touch, pointing, and keyboard devices under a unified library. Unless specified otherwise, this is loaded automatically. Individual device settings for man:libinput[4] can be tuned in the crossref:desktop[desktop-synopsis,desktop's] GUI, or manually with package:x11/xinput[xinput] and package:x11/setxkbmap[setxkbmap]. Alternatively, there are older, lightweight, individual drivers for specific input devices available in the package:x11-drivers[] catagory named x11/xf86-input-[foo]. This approach requires manual configuration of the X.org server. Both are described in this subsection. [[x-config-input-atmoic]] ==== Using Atomic Input Configuration Devices supported by man:libinput[4] can be configured with graphical utilities included with the crossref:desktop[desktop-synopsis,desktop] of choice, or manually and atomically at runtime with package:x11/xinput[] and package:x11/setxkbmap[]. To ask man:libinput[4] what devices it's currently attached to, run man:xinput[1] with no arguments: [source,shell] .... $ xinput .... Its output should be similar to the following: [example] .... ⎡ Virtual core pointer id=2 [master pointer (3)] ⎜ ↳ Virtual core XTEST pointer id=4 [slave pointer (2)] ⎜ ↳ System mouse id=7 [slave pointer (2)] ⎜ ↳ VEN_0488:00 0488:1031 Mouse id=11 [slave pointer (2)] ⎜ ↳ VEN_0488:00 0488:1031 TouchPad id=12 [slave pointer (2)] ⎣ Virtual core keyboard id=3 [master keyboard (2)] ↳ Virtual core XTEST keyboard id=5 [slave keyboard (3)] ↳ System keyboard multiplexer id=6 [slave keyboard (3)] ↳ Power Button id=8 [slave keyboard (3)] ↳ Sleep Button id=9 [slave keyboard (3)] ↳ AT keyboard id=10 [slave keyboard (3)] .... All settings supported by these devices are provided as properties, which can be listed and set atomically. Pointing devices have many configurable properties, keyboards usually need none. To customize the keyboard, take a look at man:setxkbmap[1]. Once satisfied with the configuration, simply add the lines to the X initialization script such as [.filename]#~/.Xsession# or [.filename]#~/.xinitrc#. [[x-config-input-file]] ==== Using X.org Configuration Files [TIP] ==== Some desktop environments (such as crossref:desktop[kde-environment,KDE Plasma]) provide a graphical UI for setting these parameters. Check if this is the case before resorting to manual configuration editing. ==== [[x-config-input-keyboard-layout]] For example, to manually configure the X.org server for the keyboard layout: .Setting a Keyboard Layout [example] ==== [.filename]#/usr/local/etc/X11/xorg.conf.d/00-keyboard.conf# [.programlisting] .... Section "InputClass" Identifier "Keyboard1" MatchIsKeyboard "on" Option "XkbLayout" "es, fr" Option "XkbModel" "pc104" Option "XkbVariant" ",qwerty" Option "XkbOptions" "grp:win_space_toggle" EndSection .... ==== [[x-fonts]] == Using Fonts in the X Window System _**abstract**: Additional fonts can be installed from the package:x11-fonts[] category or placed in [.filename]#~/.fonts#. They are available immediately to modern applications. Configuration for older applications is available and described as well._ The X Window System provides the X FreeType interface library (man:Xft[3]) to render vector or outline fonts, as well as the traditional X Logical Font Description system maintaining compatibility with generations of applications and fonts. There are primarily two types of fonts users will be interested in: * OpenType fonts or TrueType(R) fonts are for displaying on a screen. * Adobe(R) PostScript(R) Type 1 fonts are for printing to paper. These are both vector or outline fonts, there are also bitmap fonts. The FreeBSD Ports Collection includes a wide and growing catalog of free, high quality fonts available for installation in the package:x11-fonts[] catagory. System-wide font packages installed from the ports collection live in `[.filename]#/usr/local/share/fonts/#`. Fonts for a single user can be placed in `[.filename]#~/.fonts/#`, or `[.filename]#~/.local/share/fonts/#`. Fonts in either directory or subdirectories will be available for immediate use when the font information cache is rebuilt. To trigger this manually, issue: [source,shell] .... % fc-cache .... Plenty of free, high quality fonts of both types are available in the ports tree which can be readily used with X Window System. This chapter provides a brief overview of both, as well as configuring the X FreeType interface. For more information about how to install and configure fonts on FreeBSD, please read the article link:{fonts}[Fonts and FreeBSD]. [[truetype]] === TrueType(R) Fonts X.org has built in support for rendering TrueType(R) fonts. There are two different modules that can enable this functionality. The freetype module is used in this example because it is more consistent with the other font rendering back-ends. To enable the freetype module just add the following line to the `"Module"` section of [.filename]#/usr/local/etc/X11/xorg.conf.d/90-fonts.conf#. [.programlisting] .... Load "freetype" .... Now make a directory for the TrueType(R) fonts (for example, [.filename]#/usr/local/share/fonts/TrueType#) and copy all of the TrueType(R) fonts into this directory. Keep in mind that TrueType(R) fonts cannot be directly taken from an Apple(R) Mac(R); they must be in UNIX(R)/MS-DOS(R)/Windows(R) format for use by X.org. Once the files have been copied into this directory, use mkfontscale to create a [.filename]#fonts.dir#, so that the X font renderer knows that these new files have been installed. `mkfontscale` can be installed as a package: [source,shell] .... # pkg install mkfontscale .... Then create an index of X font files in a directory: [source,shell] .... # cd /usr/local/share/fonts/TrueType # mkfontscale .... Now add the TrueType(R) directory to the font path. This is just the same as described in <>: [source,shell] .... % xset fp+ /usr/local/share/fonts/TrueType % xset fp rehash .... or add a `FontPath` line to [.filename]#xorg.conf#. Now Gimp, LibreOffice, and all of the other X applications should now recognize the installed TrueType(R) fonts. Extremely small fonts (as with text in a high resolution display on a web page) and extremely large fonts (within LibreOffice) will look much better now. [[type1]] === Type1 Fonts The URW font collection (package:x11-fonts/urwfonts[]) includes high quality versions of standard type1 fonts (Times Roman(TM), Helvetica(TM), Palatino(TM) and others). The Freefonts collection (package:x11-fonts/freefonts[]) includes many more fonts, but most of them are intended for use in graphics software such as the Gimp, and are not complete enough to serve as screen fonts. To install the above Type1 font collections from binary packages, run the following commands: [source,shell] .... # pkg install urwfonts .... And likewise with the freefont or other collections. To have a manually configured X server detect these fonts, add an appropriate line to the X server configuration file ([.filename]#/usr/local/etc/X11/xorg.conf.d/90-fonts.conf#), which reads: [.programlisting] .... Section "Files" FontPath "/usr/local/share/fonts/urwfonts/" EndSection .... Alternatively, at the command line in the X session run: [source,shell] .... % xset fp+ /usr/local/share/fonts/urwfonts % xset fp rehash .... This will work but will be lost when the X session is closed, unless it is added to the startup file ([.filename]#~/.xinitrc# for a normal `startx` session, or [.filename]#~/.xsession# when logging in through a graphical login manager like XDM). A third way is to use the new [.filename]#/usr/local/etc/fonts/local.conf# as demonstrated in <>. [[antialias]] === Anti-Aliased Fonts All fonts in X.org that are found in [.filename]#/usr/local/share/fonts/# and [.filename]#~/.fonts/# are automatically made available for anti-aliasing to Xft-aware applications. Most recent applications are Xft-aware, including KDE, GNOME, and Firefox. To control which fonts are anti-aliased, or to configure anti-aliasing properties, create (or edit, if it already exists) the file [.filename]#/usr/local/etc/fonts/local.conf#. Several advanced features of the Xft font system can be tuned using this file; this section describes only some simple possibilities. For more details, please see man:fonts-conf[5]. This file must be in XML format. Pay careful attention to case, and make sure all tags are properly closed. The file begins with the usual XML header followed by a DOCTYPE definition, and then the `` tag: [.programlisting] .... .... As previously stated, all fonts in [.filename]#/usr/local/share/fonts/# as well as [.filename]#~/.fonts/# are already made available to Xft-aware applications. To add another directory outside of these two directory trees, add a line like this to [.filename]#/usr/local/etc/fonts/local.conf#: [.programlisting] .... /path/to/my/fonts .... After adding new fonts, and especially new font directories, rebuild the font caches: [source,shell] .... # fc-cache -f .... Anti-aliasing makes borders slightly fuzzy, which makes very small text more readable and removes "staircases" from large text, but can cause eyestrain if applied to normal text. To exclude font sizes smaller than 14 point from anti-aliasing, include these lines: [.programlisting] .... 14 false 14 false .... Spacing for some monospaced fonts might also be inappropriate with anti-aliasing. This seems to be an issue with KDE, in particular. One possible fix is to force the spacing for such fonts to be 100. Add these lines: [.programlisting] .... fixed mono console mono .... (this aliases the other common names for fixed fonts as `"mono"`), and then add: [.programlisting] .... mono 100 .... Certain fonts, such as Helvetica, may have a problem when anti-aliased. Usually this manifests itself as a font that seems cut in half vertically. At worst, it may cause applications to crash. To avoid this, consider adding the following to [.filename]#local.conf#: [.programlisting] .... Helvetica sans-serif .... After editing [.filename]#local.conf#, make certain to end the file with the `` tag. Not doing this will cause changes to be ignored. Users can add personalized settings by creating their own [.filename]#~/.config/fontconfig/fonts.conf#. This file uses the same `XML` format described above. One last point: with an LCD screen, sub-pixel sampling may be desired. This basically treats the (horizontally separated) red, green and blue components separately to improve the horizontal resolution; the results can be dramatic. To enable this, add the line somewhere in [.filename]#local.conf#: [.programlisting] .... unknown rgb .... [NOTE] ==== Depending on the sort of display, `rgb` may need to be changed to `bgr`, `vrgb` or `vbgr`: experiment and see which works best. ==== diff --git a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc index bf37987160..e6842bec60 100644 --- a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc +++ b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc @@ -1,5452 +1,5447 @@ --- title: Chapter 5. Configuring the Makefile prev: books/porters-handbook/slow-porting next: books/porters-handbook/special description: Configuring the Makefile for FreeBSD Ports tags: ["makefiles", "configuring", "naming", "versions"] showBookMenu: true weight: 5 params: path: "/books/porters-handbook/makefiles/" --- [[makefiles]] = Configuring the Makefile :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 5 :partnums: :source-highlighter: rouge :experimental: :g-plus-plus: g++ :images-path: books/porters-handbook/ 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::[] Configuring the [.filename]#Makefile# is pretty simple, and again we suggest looking at existing examples before starting. Also, there is a crossref:porting-samplem[porting-samplem,sample Makefile] in this handbook, so take a look and please follow the ordering of variables and sections in that template to make the port easier for others to read. Consider these problems in sequence during the design of the new [.filename]#Makefile#: [[makefile-source]] == The Original Source Does it live in `DISTDIR` as a standard ``gzip``ped tarball named something like [.filename]#foozolix-1.2.tar.gz#? If so, go on to the next step. If not, the distribution file format might require overriding one or more of `DISTVERSION`, `DISTNAME`, `EXTRACT_CMD`, `EXTRACT_BEFORE_ARGS`, `EXTRACT_AFTER_ARGS`, `EXTRACT_SUFX`, or `DISTFILES`. In the worst case, create a custom `do-extract` target to override the default. This is rarely, if ever, necessary. [[makefile-naming]] == Naming The first part of the port's [.filename]#Makefile# names the port, describes its version number, and lists it in the correct category. [[makefile-portname]] === `PORTNAME` Set `PORTNAME` to the base name of the software. It is used as the base for the FreeBSD package, and for crossref:makefiles[makefile-distname,`DISTNAME`]. [IMPORTANT] ==== The package name must be unique across the entire ports tree. Make sure that the `PORTNAME` is not already in use by an existing port, and that no other port already has the same `PKGBASE`. If the name has already been used, add either crossref:makefiles[porting-pkgnameprefix-suffix,`PKGNAMEPREFIX` or `PKGNAMESUFFIX`]. ==== [[makefile-versions]] === Versions, `DISTVERSION` _or_ `PORTVERSION` Set `DISTVERSION` to the version number of the software. `PORTVERSION` is the version used for the FreeBSD package. It will be automatically derived from `DISTVERSION` to be compatible with FreeBSD's package versioning scheme. If the version contains _letters_, it might be needed to set `PORTVERSION` and not `DISTVERSION`. [IMPORTANT] ==== Only one of `PORTVERSION` and `DISTVERSION` can be set at a time. ==== From time to time, some software will use a version scheme that is not compatible with how `DISTVERSION` translates in `PORTVERSION`. [TIP] ==== When updating a port, it is possible to use the `-t` argument of man:pkg-version[8] to check if the new version is greater or lesser than before. See below on how to use man:pkg-version[8] to compare versions. ==== [[makefile-versions-ex-pkg-version]] .Using man:pkg-version[8] to Compare Versions [example] ==== `pkg version -t` takes two versions as arguments, it will respond with `<`, `=` or `>` if the first version is less, equal, or more than the second version, respectively. [source,shell] .... % pkg version -t 1.2 1.3 < <.> % pkg version -t 1.2 1.2 = <.> % pkg version -t 1.2 1.2.0 = <.> % pkg version -t 1.2 1.2.p1 > <.> % pkg version -t 1.2.a1 1.2.b1 < <.> % pkg version -t 1.2 1.2p1 < <.> .... <.> `1.2` is before `1.3`. <.> `1.2` and `1.2` are equal as they have the same version. <.> `1.2` and `1.2.0` are equal as nothing equals zero. <.> `1.2` is after `1.2.p1` as `.p1`, think "pre-release 1". <.> `1.2.a1` is before `1.2.b1`, think "alpha" and "beta", and `a` is before `b`. <.> `1.2` is before `1.2p1` as `2p1`, think "2, patch level 1" which is a version after any `2.X` but before `3`. [NOTE] **** In here, the `a`, `b`, and `p` are used as if meaning "alpha", "beta" or "pre-release" and "patch level", but they are only letters and are sorted alphabetically, so any letter can be used, and they will be sorted appropriately. **** ==== .Examples of `DISTVERSION` and the Derived `PORTVERSION` [cols="10%,90%", frame="none", options="header"] |=== | DISTVERSION | PORTVERSION |0.7.1d |0.7.1.d |10Alpha3 |10.a3 |3Beta7-pre2 |3.b7.p2 |8:f_17 |8f.17 |=== [[makefile-versions-ex1]] .Using `DISTVERSION` [example] ==== When the version only contains numbers separated by dots, dashes or underscores, use `DISTVERSION`. [.programlisting] .... PORTNAME= nekoto DISTVERSION= 1.2-4 .... It will generate a `PORTVERSION` of `1.2.4`. ==== [[makefile-versions-ex2]] .Using `DISTVERSION` When the Version Starts with a Letter or a Prefix [example] ==== When the version starts or ends with a letter, or a prefix or a suffix that is not part of the version, use `DISTVERSIONPREFIX`, `DISTVERSION`, and `DISTVERSIONSUFFIX`. If the version is `v1.2-4`: [.programlisting] .... PORTNAME= nekoto DISTVERSIONPREFIX= v DISTVERSION= 1_2_4 .... Some of the time, projects using GitHub will use their name in their versions. For example, the version could be `nekoto-1.2-4`: [.programlisting] .... PORTNAME= nekoto DISTVERSIONPREFIX= nekoto- DISTVERSION= 1.2_4 .... Those projects also sometimes use some string at the end of the version, for example, `1.2-4_RELEASE`: [.programlisting] .... PORTNAME= nekoto DISTVERSION= 1.2-4 DISTVERSIONSUFFIX= _RELEASE .... Or they do both, for example, `nekoto-1.2-4_RELEASE`: [.programlisting] .... PORTNAME= nekoto DISTVERSIONPREFIX= nekoto- DISTVERSION= 1.2-4 DISTVERSIONSUFFIX= _RELEASE .... `DISTVERSIONPREFIX` and `DISTVERSIONSUFFIX` will not be used while constructing `PORTVERSION`, but only used in `DISTNAME`. All will generate a `PORTVERSION` of `1.2.4`. ==== [[makefile-versions-ex3]] .Using `DISTVERSION` When the Version Contains Letters Meaning "alpha", "beta", or "pre-release" [example] ==== When the version contains numbers separated by dots, dashes or underscores, and letters are used to mean "alpha", "beta" or "pre-release", which is, before the version without the letters, use `DISTVERSION`. [.programlisting] .... PORTNAME= nekoto DISTVERSION= 1.2-pre4 .... [.programlisting] .... PORTNAME= nekoto DISTVERSION= 1.2p4 .... Both will generate a `PORTVERSION` of `1.2.p4` which is before than 1.2. man:pkg-version[8] can be used to check that fact: [source,shell] .... % pkg version -t 1.2.p4 1.2 < .... ==== [[makefile-versions-ex4]] .Not Using `DISTVERSION` When the Version Contains Letters Meaning "Patch Level" [example] ==== When the version contains letters that are not meant as "alpha", "beta", or "pre", but more in a "patch level", and meaning after the version without the letters, use `PORTVERSION`. [.programlisting] .... PORTNAME= nekoto PORTVERSION= 1.2p4 .... In this case, using `DISTVERSION` is not possible because it would generate a version of `1.2.p4` which would be before `1.2` and not after. man:pkg-version[8] will verify this: [source,shell] .... % pkg version -t 1.2 1.2.p4 > <.> % pkg version -t 1.2 1.2p4 < <.> .... <.> `1.2` is after `1.2.p4`, which is _wrong_ in this case. <.> `1.2` is before `1.2p4`, which is what was needed. ==== For some more advanced examples of setting `PORTVERSION`, when the software's versioning is really not compatible with FreeBSD's, or `DISTNAME` when the distribution file does not contain the version itself, see crossref:makefiles[makefile-distname, `DISTNAME`]. [[makefile-naming-revepoch]] === `PORTREVISION` and `PORTEPOCH` [[makefile-portrevision]] ==== `PORTREVISION` `PORTREVISION` is a monotonically increasing value which is reset to 0 with every increase of `DISTVERSION`, typically every time there is a new official vendor release. If `PORTREVISION` is non-zero, the value is appended to the package name. Changes to `PORTREVISION` are used by automated tools like man:pkg-version[8] to determine that a new package is available. `PORTREVISION` must be increased each time a change is made to the port that changes the generated package in any way. That includes changes that only affect a package built with non-default crossref:makefiles[makefile-options,options]. Examples of when `PORTREVISION` must be bumped: * Addition of patches to correct security vulnerabilities, bugs, or to add new functionality to the port. * Changes to the port [.filename]#Makefile# to enable or disable compile-time options in the package. * Changes in the packing list or the install-time behavior of the package. For example, a change to a script which generates initial data for the package, like man:ssh[1] host keys. * Version bump of a port's shared library dependency (in this case, someone trying to install the old package after installing a newer version of the dependency will fail since it will look for the old libfoo.x instead of libfoo.(x+1)). * Silent changes to the port distfile which have significant functional differences. For example, changes to the distfile requiring a correction to [.filename]#distinfo# with no corresponding change to `DISTVERSION`, where a `diff -ru` of the old and new versions shows non-trivial changes to the code. * Changes to `MAINTAINER`. Examples of changes which do not require a `PORTREVISION` bump: * Style changes to the port skeleton with no functional change to what appears in the resulting package. * Changes to `MASTER_SITES` or other functional changes to the port which do not affect the resulting package. * Trivial patches to the distfile such as correction of typos, which are not important enough that users of the package have to go to the trouble of upgrading. * Build fixes which cause a package to become compilable where it was previously failing. As long as the changes do not introduce any functional change on any other platforms on which the port did previously build. Since `PORTREVISION` reflects the content of the package, if the package was not previously buildable then there is no need to increase `PORTREVISION` to mark a change. A rule of thumb is to decide whether a change committed to a port is something which _some_ people would benefit from having. Either because of an enhancement, fix, or by virtue that the new package will actually work at all. Then weigh that against that fact that it will cause everyone who regularly updates their ports tree to be compelled to update. If yes, `PORTREVISION` must be bumped. [NOTE] ==== People using binary packages will _never_ see the update if `PORTREVISION` is not bumped. Without increasing `PORTREVISION`, the package builders have no way to detect the change and thus, will not rebuild the package. ==== [[makefile-portepoch]] ==== `PORTEPOCH` From time to time a software vendor or FreeBSD porter will do something silly and release a version of their software which is actually numerically less than the previous version. An example of this is a port which goes from foo-20000801 to foo-1.0 (the former will be incorrectly treated as a newer version since 20000801 is a numerically greater value than 1). [TIP] ==== The results of version number comparisons are not always obvious. `pkg version` (see man:pkg-version[8]) can be used to test the comparison of two version number strings. For example: [source,shell] .... % pkg version -t 0.031 0.29 > .... The `>` output indicates that version 0.031 is considered greater than version 0.29, which may not have been obvious to the porter. ==== In situations such as this, `PORTEPOCH` must be increased. If `PORTEPOCH` is nonzero it is appended to the package name as described in section 0 above. `PORTEPOCH` must never be decreased or reset to zero, because that would cause comparison to a package from an earlier epoch to fail. For example, the package would not be detected as out of date. The new version number, `1.0,1` in the above example, is still numerically less than the previous version, 20000801, but the `,1` suffix is treated specially by automated tools and found to be greater than the implied suffix `,0` on the earlier package. Dropping or resetting `PORTEPOCH` incorrectly leads to no end of grief. If the discussion above was not clear enough, please consult the {freebsd-ports}. It is expected that `PORTEPOCH` will not be used for the majority of ports, and that sensible use of `DISTVERSION`, or that use `PORTVERSION` carefully, can often preempt it becoming necessary if a future release of the software changes the version structure. However, care is needed by FreeBSD porters when a vendor release is made without an official version number - such as a code "snapshot" release. The temptation is to label the release with the release date, which will cause problems as in the example above when a new "official" release is made. For example, if a snapshot release is made on the date `20000917`, and the previous version of the software was version `1.2`, do not use `20000917` for `DISTVERSION`. The correct way is a `DISTVERSION` of `1.2.20000917`, or similar, so that the succeeding release, say `1.3`, is still a numerically greater value. [[makefile-portrevision-example]] ==== Example of `PORTREVISION` and `PORTEPOCH` Usage The `gtkmumble` port, version `0.10`, is committed to the ports collection: [.programlisting] .... PORTNAME= gtkmumble DISTVERSION= 0.10 .... `PKGNAME` becomes `gtkmumble-0.10`. A security hole is discovered which requires a local FreeBSD patch. `PORTREVISION` is bumped accordingly. [.programlisting] .... PORTNAME= gtkmumble DISTVERSION= 0.10 PORTREVISION= 1 .... `PKGNAME` becomes `gtkmumble-0.10_1` A new version is released by the vendor, numbered `0.2` (it turns out the author actually intended `0.10` to actually mean `0.1.0`, not "what comes after 0.9" - oops, too late now). Since the new minor version `2` is numerically less than the previous version `10`, `PORTEPOCH` must be bumped to manually force the new package to be detected as "newer". Since it is a new vendor release of the code, `PORTREVISION` is reset to 0 (or removed from the [.filename]#Makefile#). [.programlisting] .... PORTNAME= gtkmumble DISTVERSION= 0.2 PORTEPOCH= 1 .... `PKGNAME` becomes `gtkmumble-0.2,1` The next release is 0.3. Since `PORTEPOCH` never decreases, the version variables are now: [.programlisting] .... PORTNAME= gtkmumble DISTVERSION= 0.3 PORTEPOCH= 1 .... `PKGNAME` becomes `gtkmumble-0.3,1` [NOTE] ==== If `PORTEPOCH` were reset to `0` with this upgrade, someone who had installed the `gtkmumble-0.10_1` package would not detect the `gtkmumble-0.3` package as newer, since `3` is still numerically less than `10`. Remember, this is the whole point of `PORTEPOCH` in the first place. ==== [[porting-pkgnameprefix-suffix]] === `PKGNAMEPREFIX` and `PKGNAMESUFFIX` Two optional variables, `PKGNAMEPREFIX` and `PKGNAMESUFFIX`, are combined with `PORTNAME` and `PORTVERSION` to form `PKGNAME` as `${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}`. Make sure this conforms to our crossref:makefiles[porting-pkgname,guidelines for a good package name]. In particular, the use of a hyphen (`-`) in `PORTVERSION` is _not_ allowed. Also, if the package name has the _language-_ or the _-compiled.specifics_ part (see below), use `PKGNAMEPREFIX` and `PKGNAMESUFFIX`, respectively. Do not make them part of `PORTNAME`. [[porting-pkgname]] === Package Naming Conventions These are the conventions to follow when naming packages. This is to make the package directory easy to scan, as there are already thousands of packages and users are going to turn away if they hurt their eyes! Package names take the form of [.filename]#language_region-name-compiled.specifics-version.numbers#. The package name is defined as `${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}`. Make sure to set the variables to conform to that format. [[porting-pkgname-language]] [.filename]#language_region-#:: FreeBSD strives to support the native language of its users. The _language-_ part is a two letter abbreviation of the natural language defined by ISO-639 when the port is specific to a certain language. Examples are `ja` for Japanese, `ru` for Russian, `vi` for Vietnamese, `zh` for Chinese, `ko` for Korean and `de` for German. + If the port is specific to a certain region within the language area, add the two letter country code as well. Examples are `en_US` for US English and `fr_CH` for Swiss French. + The _language-_ part is set in `PKGNAMEPREFIX`. [[porting-pkgname-name]] [.filename]#name#:: Make sure that the port's name and version are clearly separated and placed into `PORTNAME` and `DISTVERSION`. The only reason for `PORTNAME` to contain a version part is if the upstream distribution is really named that way, as in the package:textproc/libxml2[] or package:japanese/kinput2-freewnn[] ports. Otherwise, `PORTNAME` cannot contain any version-specific information. It is quite normal for several ports to have the same `PORTNAME`, as the package:www/apache*[] ports do; in that case, different versions (and different index entries) are distinguished by `PKGNAMEPREFIX` and `PKGNAMESUFFIX` values. + There is a tradition of naming `Perl 5` modules by prepending `p5-` and converting the double-colon separator to a hyphen. For example, the `Data::Dumper` module becomes `p5-Data-Dumper`. [[porting-pkgname-compiled-specifics]] [.filename]#-compiled.specifics#:: If the port can be built with different crossref:makefiles[makefile-masterdir,hardcoded defaults] (usually part of the directory name in a family of ports), the _-compiled.specifics_ part states the compiled-in defaults. The hyphen is optional. Examples are paper size and font units. + The _-compiled.specifics_ part is set in `PKGNAMESUFFIX`. [[porting-pkgname-version-numbers]] [.filename]#-version.numbers#:: The version string follows a dash (`-`) and is a period-separated list of integers and single lowercase alphabetics. In particular, it is not permissible to have another dash inside the version string. The only exception is the string `pl` (meaning "patchlevel"), which can be used _only_ when there are no major and minor version numbers in the software. If the software version has strings like "alpha", "beta", "rc", or "pre", take the first letter and put it immediately after a period. If the version string continues after those names, the numbers follow the single alphabet without an extra period between them (for example, `1.0b2`). + The idea is to make it easier to sort ports by looking at the version string. In particular, make sure version number components are always delimited by a period, and if the date is part of the string, use the `d__yyyy.mm.dd__` format, not `_dd.mm.yyyy_` or the non-Y2K compliant `_yy.mm.dd_` format. It is important to prefix the version with a letter, here `d` (for date), in case a release with an actual version number is made, which would be numerically less than `_yyyy_`. [IMPORTANT] ==== Package name must be unique among all of the ports tree, check that there is not already a port with the same `PORTNAME` and if there is add one of crossref:makefiles[porting-pkgnameprefix-suffix,`PKGNAMEPREFIX` or `PKGNAMESUFFIX`]. ==== Here are some (real) examples on how to convert the name as called by the software authors to a suitable package name, for each line, only one of `DISTVERSION` or `PORTVERSION` is set in, depending on which would be used in the port's [.filename]#Makefile#: .Package Naming Examples [cols="1,1,1,1,1,1,1", frame="none", options="header"] |=== | Distribution Name | PKGNAMEPREFIX | PORTNAME | PKGNAMESUFFIX | DISTVERSION | PORTVERSION | Reason or comment |mule-2.2.2 |(empty) |mule |(empty) |2.2.2 | |No changes required |mule-1.0.1 |(empty) |mule |1 |1.0.1 | |This is version 1 of mule, and version 2 already exists |EmiClock-1.0.2 |(empty) |emiclock |(empty) |1.0.2 | |No uppercase names for single programs |rdist-1.3alpha |(empty) |rdist |(empty) |1.3alpha | |Version will be `1.3.a` |es-0.9-beta1 |(empty) |es |(empty) |0.9-beta1 | |Version will be `0.9.b1` |mailman-2.0rc3 |(empty) |mailman |(empty) |2.0rc3 | |Version will be `2.0.r3` |v3.3beta021.src |(empty) |tiff |(empty) | |3.3 |What the heck was that anyway? |tvtwm |(empty) |tvtwm |(empty) | |p11 |No version in the filename, use what upstream says it is |piewm |(empty) |piewm |(empty) |1.0 | |No version in the filename, use what upstream says it is |xvgr-2.10pl1 |(empty) |xvgr |(empty) | |2.10.pl1 |In that case, `pl1` means patch level, so using DISTVERSION is not possible. |gawk-2.15.6 |ja- |gawk |(empty) |2.15.6 | |Japanese language version |psutils-1.13 |(empty) |psutils |-letter |1.13 | |Paper size hardcoded at package build time |pkfonts |(empty) |pkfonts |300 |1.0 | |Package for 300dpi fonts |=== If there is absolutely no trace of version information in the original source and it is unlikely that the original author will ever release another version, just set the version string to `1.0` (like the `piewm` example above). Otherwise, ask the original author or use the date string the source file was released on (`d__yyyy.mm.dd__`, or `d__yyyymmdd__`) as the version. [TIP] ==== Use any letter. Here, `d` here stands for date, if the source is a Git repository, `g` followed by the commit date is commonly used, using `s` for snapshot is also common. ==== [[makefile-categories]] == Categorization [[makefile-categories-definition]] === `CATEGORIES` When a package is created, it is put under [.filename]#/usr/ports/packages/All# and links are made from one or more subdirectories of [.filename]#/usr/ports/packages#. The names of these subdirectories are specified by the variable `CATEGORIES`. It is intended to make life easier for the user when he is wading through the pile of packages on the FTP site or the CDROM. Please take a look at the crossref:makefiles[porting-categories,current list of categories] and pick the ones that are suitable for the port. This list also determines where in the ports tree the port is imported. If there is more than one category here, the port files must be put in the subdirectory with the name of the first category. See crossref:makefiles[choosing-categories,below] for more discussion about how to pick the right categories. [[porting-categories]] === Current List of Categories Here is the current list of port categories. Those marked with an asterisk (`*`) are _virtual_ categories-those that do not have a corresponding subdirectory in the ports tree. They are only used as secondary categories, and only for search purposes. [NOTE] ==== For non-virtual categories, there is a one-line description in `COMMENT` in that subdirectory's [.filename]#Makefile#. ==== [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Category | Description | Notes |[.filename]#accessibility# |Ports to help disabled users. | |[.filename]#afterstep#`*` |Ports to support the http://www.afterstep.org/[AfterStep] window manager. | |[.filename]#arabic# |Arabic language support. | |[.filename]#archivers# |Archiving tools. | |[.filename]#astro# |Astronomical ports. | |[.filename]#audio# |Sound support. | |[.filename]#benchmarks# |Benchmarking utilities. | |[.filename]#biology# |Biology-related software. | |[.filename]#cad# |Computer aided design tools. | |[.filename]#chinese# |Chinese language support. | |[.filename]#comms# |Communication software. |Mostly software to talk to the serial port. |[.filename]#converters# |Character code converters. | |[.filename]#databases# |Databases. | |[.filename]#deskutils# |Things that used to be on the desktop before computers were invented. | |[.filename]#devel# |Development utilities. |Do not put libraries here just because they are libraries. They should _not_ be in this category unless they truly do not belong anywhere else. |[.filename]#dns# |DNS-related software. | |[.filename]#docs#`*` |Meta-ports for FreeBSD documentation. | |[.filename]#editors# |General editors. |Specialized editors go in the section for those tools. For example, a mathematical-formula editor will go in [.filename]#math#, and have [.filename]#editors# as a second category. |[.filename]#education#`*` |Education-related software. |This includes applications, utilities, or games primarily or substantially designed to help the user learn a specific topic or study in general. It also includes course-writing applications, course-delivery applications, and classroom or school management applications |[.filename]#elisp#`*` |Emacs-lisp ports. | |[.filename]#emulators# |Emulators for other operating systems. |Terminal emulators do _not_ belong here. X-based ones go to [.filename]#x11# and text-based ones to either [.filename]#comms# or [.filename]#misc#, depending on the exact functionality. |[.filename]#enlightenment#`*` |Ports related to the Enlightenment window manager. | |[.filename]#filesystems# |File systems and related utilities. | |[.filename]#finance# |Monetary, financial and related applications. | |[.filename]#french# |French language support. | |[.filename]#ftp# |FTP client and server utilities. |If the port speaks both FTP and HTTP, put it in [.filename]#ftp# with a secondary category of [.filename]#www#. |[.filename]#games# |Games. | |[.filename]#geography#`*` |Geography-related software. | |[.filename]#german# |German language support. | |[.filename]#gnome#`*` |Ports from the https://www.gnome.org/[GNOME] Project. | |[.filename]#gnustep#`*` |Software related to the GNUstep desktop environment. | |[.filename]#graphics# |Graphics utilities. | |[.filename]#hamradio#`*` |Software for amateur radio. | |[.filename]#haskell#`*` |Software related to the Haskell language. | |[.filename]#hebrew# |Hebrew language support. | |[.filename]#hungarian# |Hungarian language support. | |[.filename]#irc# |Internet Relay Chat utilities. | |[.filename]#japanese# |Japanese language support. | |[.filename]#java# |Software related to the Java(TM) language. |The [.filename]#java# category must not be the only one for a port. Save for ports directly related to the Java language, porters are also encouraged not to use [.filename]#java# as the main category of a port. |[.filename]#kde#`*` |Ports from the https://www.kde.org/[KDE] Project (generic). | |[.filename]#kde-applications#`*` |Applications from the https://www.kde.org/[KDE] Project. | |[.filename]#kde-frameworks#`*` |Add-on libraries from the https://www.kde.org/[KDE] Project for programming with Qt. | |[.filename]#kde-plasma#`*` |Desktop from the https://www.kde.org/[KDE] Project. | |[.filename]#kld#`*` |Kernel loadable modules. | |[.filename]#korean# |Korean language support. | |[.filename]#lang# |Programming languages. | |[.filename]#linux#`*` |Linux applications and support utilities. | |[.filename]#lisp#`*` |Software related to the Lisp language. | |[.filename]#mail# |Mail software. | |[.filename]#mate#`*` |Ports related to the MATE desktop environment, a fork of GNOME 2. | |[.filename]#math# |Numerical computation software and other utilities for mathematics. | |[.filename]#mbone#`*` |MBone applications. | |[.filename]#misc# |Miscellaneous utilities |Things that do not belong anywhere else. If at all possible, try to find a better category for the port than `misc`, as ports tend to be overlooked in here. |[.filename]#multimedia# |Multimedia software. | |[.filename]#net# |Miscellaneous networking software. | |[.filename]#net-im# |Instant messaging software. | |[.filename]#net-mgmt# |Networking management software. | |[.filename]#net-p2p# |Peer to peer network applications. | |[.filename]#net-vpn#`*` |Virtual Private Network applications. | |[.filename]#news# |USENET news software. | |[.filename]#parallel#`*` |Applications dealing with parallelism in computing. | |[.filename]#pear#`*` |Ports related to the Pear PHP framework. | |[.filename]#perl5#`*` |Ports that require Perl version 5 to run. | |[.filename]#plan9#`*` |Various programs from https://9p.io/wiki/plan9/Download/index.html[Plan9]. | |[.filename]#polish# |Polish language support. | |[.filename]#ports-mgmt# |Ports for managing, installing and developing FreeBSD ports and packages. | |[.filename]#portuguese# |Portuguese language support. | |[.filename]#print# |Printing software. |Desktop publishing tools (previewers, etc.) belong here too. |[.filename]#python#`*` |Software related to the https://www.python.org/[Python] language. | |[.filename]#ruby#`*` |Software related to the https://www.ruby-lang.org/[Ruby] language. | |[.filename]#rubygems#`*` |Ports of https://www.rubygems.org/[RubyGems] packages. | |[.filename]#russian# |Russian language support. | |[.filename]#scheme#`*` |Software related to the Scheme language. | |[.filename]#science# |Scientific ports that do not fit into other categories such as [.filename]#astro#, [.filename]#biology# and [.filename]#math#. | |[.filename]#security# |Security utilities. | |[.filename]#shells# |Command line shells. | |[.filename]#spanish#`*` |Spanish language support. | |[.filename]#sysutils# |System utilities. | |[.filename]#tcl#`*` |Ports that use Tcl to run. | |[.filename]#textproc# |Text processing utilities. |It does not include desktop publishing tools, which go to [.filename]#print#. |[.filename]#tk#`*` |Ports that use Tk to run. | |[.filename]#ukrainian# |Ukrainian language support. | |[.filename]#vietnamese# |Vietnamese language support. | |[.filename]#wayland#`*` |Ports to support the Wayland display server. | |[.filename]#windowmaker#`*` |Ports to support the Window Maker window manager. | |[.filename]#www# |Software related to the World Wide Web. |HTML language support belongs here too. |[.filename]#x11# |The X Window System and friends. |This category is only for software that directly supports the window system. Do not put regular X applications here. Most of them go into other [.filename]#x11-*# categories (see below). |[.filename]#x11-clocks# |X11 clocks. | |[.filename]#x11-drivers# |X11 drivers. | |[.filename]#x11-fm# |X11 file managers. | |[.filename]#x11-fonts# |X11 fonts and font utilities. | |[.filename]#x11-servers# |X11 servers. | |[.filename]#x11-themes# |X11 themes. | |[.filename]#x11-toolkits# |X11 toolkits. | |[.filename]#x11-wm# |X11 window managers. | |[.filename]#xfce#`*` |Ports related to the https://www.xfce.org/[Xfce] desktop environment. | |[.filename]#zope#`*` |https://www.zope.org/[Zope] support. | |=== [[choosing-categories]] === Choosing the Right Category As many of the categories overlap, choosing which of the categories will be the primary category of the port can be tedious. There are several rules that govern this issue. Here is the list of priorities, in decreasing order of precedence: * The first category must be a physical category (see crossref:makefiles[porting-categories,above]). This is necessary to make the packaging work. Virtual categories and physical categories may be intermixed after that. * Language specific categories always come first. For example, if the port installs Japanese X11 fonts, then the `CATEGORIES` line would read [.filename]#japanese x11-fonts#. * Specific categories are listed before less-specific ones. For instance, an HTML editor is listed as [.filename]#www editors#, not the other way around. Also, do not list [.filename]#net# when the port belongs to any of [.filename]#irc#, [.filename]#mail#, [.filename]#news#, [.filename]#security#, or [.filename]#www#, as [.filename]#net# is included implicitly. * [.filename]#x11# is used as a secondary category only when the primary category is a natural language. In particular, do not put [.filename]#x11# in the category line for X applications. * Emacs modes are placed in the same ports category as the application supported by the mode, not in [.filename]#editors#. For example, an Emacs mode to edit source files of some programming language goes into [.filename]#lang#. * Ports installing loadable kernel modules also have the virtual category [.filename]#kld# in their `CATEGORIES` line. This is one of the things handled automatically by adding `USES=kmod`. * [.filename]#misc# does not appear with any other non-virtual category. If there is `misc` with something else in `CATEGORIES`, that means `misc` can safely be deleted and the port placed only in the other subdirectory. * If the port truly does not belong anywhere else, put it in [.filename]#misc#. If the category is not clearly defined, please put a comment to that effect in the https://bugs.freebsd.org/submit/[port submission] in the bug database so we can discuss it before we import it. As a committer, send a note to the {freebsd-ports} so we can discuss it first. Too often, new ports are imported to the wrong category only to be moved right away. [[proposing-categories]] === Proposing a New Category As the Ports Collection has grown over time, various new categories have been introduced. New categories can either be _virtual_ categories-those that do not have a corresponding subdirectory in the ports tree- or _physical_ categories-those that do. This section discusses the issues involved in creating a new physical category. Read it thoroughly before proposing a new one. Our existing practice has been to avoid creating a new physical category unless either a large number of ports would logically belong to it, or the ports that would belong to it are a logically distinct group that is of limited general interest (for instance, categories related to spoken human languages), or preferably both. The rationale for this is that such a change creates a extref:{committers-guide}[fair amount of work, ports] for both the committers and also for all users who track changes to the Ports Collection. In addition, proposed category changes just naturally seem to attract controversy. (Perhaps this is because there is no clear consensus on when a category is "too big", nor whether categories should lend themselves to browsing (and thus what number of categories would be an ideal number), and so forth.) Here is the procedure: [.procedure] . Propose the new category on {freebsd-ports}. Include a detailed rationale for the new category, including why the existing categories are not sufficient, and the list of existing ports proposed to move. (If there are new ports pending in Bugzilla that would fit this category, list them too.) Indicating that the updater is also the maintainer or submitter may be helpful to the case. . Participate in the discussion. . If it seems that there is support for the idea, file a PR which includes both the rationale and the list of existing ports that need to be moved. Ideally, this PR would also include these patches: ** [.filename]##Makefile##s for the new ports once they are repocopied ** [.filename]#Makefile# for the new category ** [.filename]#Makefile# for the old ports' categories ** [.filename]##Makefile##s for ports that depend on the old ports ** (for extra credit, include the other files that have to change, as per the procedure in the Committer's Guide.) . Since it affects the ports infrastructure and involves moving and patching many ports but also possibly running regression tests on the build cluster, assign the PR to the {portmgr}. . If that PR is approved, a committer will need to follow the rest of the procedure that is extref:{committers-guide}[outlined in the Committer's Guide, ports]. Proposing a new virtual category is similar to the above but much less involved, since no ports will actually have to move. In this case, the only patches to include in the PR would be those to add the new category to `CATEGORIES` of the affected ports. [[proposing-reorg]] === Proposing Reorganizing All the Categories Occasionally someone proposes reorganizing the categories with either a 2-level structure, or some other kind of keyword structure. To date, nothing has come of any of these proposals because, while they are very easy to make, the effort involved to retrofit the entire existing ports collection with any kind of reorganization is daunting to say the very least. Please read the history of these proposals in the mailing list archives before posting this idea. Furthermore, be prepared to be challenged to offer a working prototype. [[makefile-distfiles]] == The Distribution Files The second part of the [.filename]#Makefile# describes the files that must be downloaded to build the port, and where they can be downloaded. [[makefile-distname]] === `DISTNAME` `DISTNAME` is the name of the port as called by the authors of the software. `DISTNAME` defaults to `${PORTNAME}-${DISTVERSIONPREFIX}${DISTVERSION}${DISTVERSIONSUFFIX}`, and if not set, `DISTVERSION` defaults to `${PORTVERSION}` so override `DISTNAME` only if necessary. `DISTNAME` is only used in two places. First, the distribution file list (`DISTFILES`) defaults to `${DISTNAME}${EXTRACT_SUFX}`. Second, the distribution file is expected to extract into a subdirectory named `WRKSRC`, which defaults to [.filename]#work/${DISTNAME}#. Some vendor's distribution names which do not fit into the `${PORTNAME}-${PORTVERSION}`-scheme can be handled automatically by setting `DISTVERSIONPREFIX`, `DISTVERSION`, and `DISTVERSIONSUFFIX`. `PORTVERSION` will be derived from `DISTVERSION` automatically. [IMPORTANT] ==== Only one of `PORTVERSION` and `DISTVERSION` can be set at a time. If `DISTVERSION` does not derive a correct `PORTVERSION`, do not use `DISTVERSION`. ==== If the upstream version scheme can be derived into a ports-compatible version scheme, set some variable to the upstream version, _do not_ use `DISTVERSION` as the variable name. Set `PORTVERSION` to the computed version based on the created variable and set `DISTNAME` accordingly. If the upstream version scheme cannot easily be coerced into a ports-compatible value, set `PORTVERSION` to a sensible value, and set `DISTNAME` with `PORTNAME` with the verbatim upstream version. [[makefile-distname-ex1]] .Deriving `PORTVERSION` Manually [example] ==== BIND9 uses a version scheme that is not compatible with the ports versions (it has `-` in its versions) and cannot be derived using `DISTVERSION` because after the 9.9.9 release, it will release a "patchlevels" in the form of `9.9.9-P1`. DISTVERSION would translate that into `9.9.9.p1`, which, in the ports versioning scheme means 9.9.9 pre-release 1, which is before 9.9.9 and not after. So `PORTVERSION` is manually derived from an `ISCVERSION` variable to output `9.9.9p1`. The order into which the ports framework, and pkg, will sort versions is checked using the `-t` argument of man:pkg-version[8]: [source,shell] .... % pkg version -t 9.9.9 9.9.9.p1 > <.> % pkg version -t 9.9.9 9.9.9p1 < <.> .... <.> The `>` sign means that the first argument passed to `-t` is greater than the second argument. `9.9.9` is after `9.9.9.p1`. <.> The `<` sign means that the first argument passed to `-t` is less than the second argument. `9.9.9` is before `9.9.9p1`. In the port [.filename]#Makefile#, for example package:dns/bind99[], it is achieved by: [.programlisting] .... PORTNAME= bind PORTVERSION= ${ISCVERSION:S/-P/P/:S/b/.b/:S/a/.a/:S/rc/.rc/} CATEGORIES= dns net MASTER_SITES= ISC/bind9/${ISCVERSION} PKGNAMESUFFIX= 99 DISTNAME= ${PORTNAME}-${ISCVERSION} MAINTAINER= mat@FreeBSD.org COMMENT= BIND DNS suite with updated DNSSEC and DNS64 WWW= https://www.isc.org/bind/ LICENSE= ISCL # ISC releases things like 9.8.0-P1 or 9.8.1rc1, which our versioning does not like ISCVERSION= 9.9.9-P6 .... Define upstream version in `ISCVERSION`, with a comment saying _why_ it is needed. Use `ISCVERSION` to get a ports-compatible `PORTVERSION`. Use `ISCVERSION` directly to get the correct URL for fetching the distribution file. Use `ISCVERSION` directly to name the distribution file. ==== [[makefile-distname-ex2]] .Derive `DISTNAME` from `PORTVERSION` [example] ==== From time to time, the distribution file name has little or no relation to the version of the software. In package:comms/kermit[], only the last element of the version is present in the distribution file: [.programlisting] .... PORTNAME= kermit PORTVERSION= 9.0.304 CATEGORIES= comms ftp net MASTER_SITES= ftp://ftp.kermitproject.org/kermit/test/tar/ DISTNAME= cku${PORTVERSION:E}-dev20 .... The `:E` man:make[1] modifier returns the suffix of the variable, in this case, `304`. The distribution file is correctly generated as `cku304-dev20.tar.gz`. ==== [[makefile-distname-ex3]] .Exotic Case 1 [example] ==== Sometimes, there is no relation between the software name, its version, and the distribution file it is distributed in. From package:audio/libworkman[]: [.programlisting] .... PORTNAME= libworkman PORTVERSION= 1.4 CATEGORIES= audio MASTER_SITES= LOCAL/jim DISTNAME= ${PORTNAME}-1999-06-20 .... ==== [[makefile-distname-ex4]] .Exotic Case 2 [example] ==== In package:comms/librs232[], the distribution file is not versioned, so using crossref:makefiles[makefile-dist_subdir,`DIST_SUBDIR`] is needed: [.programlisting] .... PORTNAME= librs232 PORTVERSION= 20160710 CATEGORIES= comms MASTER_SITES= http://www.teuniz.net/RS-232/ DISTNAME= RS-232 DIST_SUBDIR= ${PORTNAME}-${PORTVERSION} .... ==== [NOTE] ==== `PKGNAMEPREFIX` and `PKGNAMESUFFIX` do not affect `DISTNAME`. Also note that if `WRKSRC` is equal to [.filename]#${WRKDIR}/${DISTNAME}# while the original source archive is named something other than `${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}`, leave `DISTNAME` alone- defining only `DISTFILES` is easier than both `DISTNAME` and `WRKSRC` (and possibly `EXTRACT_SUFX`). ==== [[makefile-master_sites]] === `MASTER_SITES` Record the directory part of the FTP/HTTP-URL pointing at the original tarball in `MASTER_SITES`. Do not forget the trailing slash ([.filename]#/#)! The `make` macros will try to use this specification for grabbing the distribution file with `FETCH` if they cannot find it already on the system. It is recommended that multiple sites are included on this list, preferably from different continents. This will safeguard against wide-area network problems. [IMPORTANT] ==== `MASTER_SITES` must not be blank. It must point to the actual site hosting the distribution files. It cannot point to web archives, or the FreeBSD distribution files cache sites. The only exception to this rule is ports that do not have any distribution files. For example, meta-ports do not have any distribution files, so `MASTER_SITES` does not need to be set. ==== [[makefile-master_sites-shorthand]] ==== Using `MASTER_SITE_*` Variables Shortcut abbreviations are available for popular archives like SourceForge (`SOURCEFORGE`), GNU (`GNU`), or Perl CPAN (`PERL_CPAN`). `MASTER_SITES` can use them directly: [.programlisting] .... MASTER_SITES= GNU/make .... The older expanded format still works, but all ports have been converted to the compact format. The expanded format looks like this: [.programlisting] .... MASTER_SITES= ${MASTER_SITE_GNU} MASTER_SITE_SUBDIR= make .... These values and variables are defined in https://cgit.freebsd.org/ports/tree/Mk/bsd.sites.mk[Mk/bsd.sites.mk]. New entries are added often, so make sure to check the latest version of this file before submitting a port. [TIP] ==== For any `MASTER_SITE_FOO` variable, the shorthand `_FOO_` can be used. For example, use: [.programlisting] .... MASTER_SITES= FOO .... If `MASTER_SITE_SUBDIR` is needed, use this: [.programlisting] .... MASTER_SITES= FOO/bar .... ==== [NOTE] ==== Some `MASTER_SITE_*` names are quite long, and for ease of use, shortcuts have been defined: [[makefile-master_sites-shortcut]] .Shortcuts for `MASTER_SITE_*` Macros [cols="1,1", frame="none", options="header"] |=== | Macro | Shortcut |`PERL_CPAN` |`CPAN` |`GITHUB` |`GH` |`GITHUB_CLOUD` |`GHC` |`LIBREOFFICE_DEV` |`LODEV` |`NETLIB` |`NL` |`RUBYGEMS` |`RG` |`SOURCEFORGE` |`SF` |=== ==== [[makefile-master_sites-magic]] ==== Magic MASTER_SITES Macros Several "magic" macros exist for popular sites with a predictable directory structure. For these, just use the abbreviation and the system will choose a subdirectory automatically. For a port named `Stardict`, of version `1.2.3`, and hosted on SourceForge, adding this line: [.programlisting] .... MASTER_SITES= SF .... infers a subdirectory named `/project/stardict/stardict/1.2.3`. If the inferred directory is incorrect, it can be overridden: [.programlisting] .... MASTER_SITES= SF/stardict/WyabdcRealPeopleTTS/${PORTVERSION} .... This can also be written as [.programlisting] .... MASTER_SITES= SF MASTER_SITE_SUBDIR= stardict/WyabdcRealPeopleTTS/${PORTVERSION} .... [[makefile-master_sites-popular]] .Magic `MASTER_SITES` Macros [cols="1,1", frame="none", options="header"] |=== | Macro | Assumed subdirectory |`APACHE_COMMONS_BINARIES` |`${PORTNAME:S,commons-,,}` |`APACHE_COMMONS_SOURCE` |`${PORTNAME:S,commons-,,}` |`APACHE_JAKARTA` |`${PORTNAME:S,-,/,}/source` |`BERLIOS` |`${PORTNAME:tl}.berlios` |`CHEESESHOP` |`source/${DISTNAME:C/(.).\*/\1/}/${DISTNAME:C/(.*)-[0-9].*/\1/}` |`CPAN` |`${PORTNAME:C/-.*//}` |`DEBIAN` |`pool/main/${PORTNAME:C/^((lib)?.).*$/\1/}/${PORTNAME}` |`FARSIGHT` |`${PORTNAME}` |`FESTIVAL` |`${PORTREVISION}` |`GCC` |`releases/${DISTNAME}` |`GENTOO` |`distfiles` |`GIMP` |`${PORTNAME}/${PORTVERSION:R}/` |`GH` |`${GH_ACCOUNT}/${GH_PROJECT}/tar.gz/${GH_TAGNAME}?dummy=/` |`GHC` |`${GH_ACCOUNT}/${GH_PROJECT}/` |`GNOME` |`sources/${PORTNAME}/${PORTVERSION:C/^([0-9]+\.[0-9]+).*/\1/}` |`GNU` |`${PORTNAME}` |`GNUPG` |`${PORTNAME}` |`GNU_ALPHA` |`${PORTNAME}` |`HORDE` |`${PORTNAME}` |`LODEV` |`${PORTNAME}` |`MATE` |`${PORTVERSION:C/^([0-9]+\.[0-9]+).*/\1/}` |`MOZDEV` |`${PORTNAME:tl}` |`NL` |`${PORTNAME}` |`QT` |`archive/qt/${PORTVERSION:R}` |`SAMBA` |`${PORTNAME}` |`SAVANNAH` |`${PORTNAME:tl}` |`SF` |`${PORTNAME:tl}/${PORTNAME:tl}/${PORTVERSION}` |=== [[makefile-master_sites-github]] === `USE_GITHUB` If the distribution file comes from a specific commit or tag on https://github.com/[GitHub] for which there is no officially released file, there is an easy way to set the right `DISTNAME` and `MASTER_SITES` automatically. [WARNING] ==== As of 2023-02-21 link:https://github.blog/2023-02-21-update-on-the-future-stability-of-source-code-archives-and-hashes/[GitHub] have announced that source downloads will be stable for a year. Please switch to release assets and if not available ask upstream to generate ones. ==== These variables are available: [[makefile-master_sites-github-description]] .`USE_GITHUB` Description [cols="1,1,1", options="header"] |=== | Variable | Description | Default |`GH_ACCOUNT` |Account name of the GitHub user hosting the project |`${PORTNAME}` |`GH_PROJECT` |Name of the project on GitHub |`${PORTNAME}` |`GH_TAGNAME` |Name of the tag to download (2.0.1, hash, ...) Using the name of a branch here is incorrect. It is also possible to use the hash of a commit id to do a snapshot. |`${DISTVERSIONPREFIX}${DISTVERSION}${DISTVERSIONSUFFIX}` |`GH_SUBDIR` |When the software needs an additional distribution file to be extracted within `${WRKSRC}`, this variable can be used. See the examples in crossref:makefiles[makefile-master_sites-github-multiple, Fetching Multiple Files from GitHub] for more information. |(none) |`GH_TUPLE` |`GH_TUPLE` allows putting `GH_ACCOUNT`, `GH_PROJECT`, `GH_TAGNAME`, and `GH_SUBDIR` into a single variable. The format is _account_`:`_project_`:`_tagname_`:`_group_`/`_subdir_. The `/`_subdir_ part is optional. It is helpful when there is more than one GitHub project from which to fetch. | |=== [IMPORTANT] ==== Do not use `GH_TUPLE` for the default distribution file, as it has no default. ==== [[makefile-master_sites-github-ex1]] .Simple Use of `USE_GITHUB` [example] ==== While trying to make a port for version `1.2.7` of pkg from the FreeBSD user on github, at https://github.com/freebsd/pkg/[], The [.filename]#Makefile# would end up looking like this (slightly stripped for the example): [.programlisting] .... PORTNAME= pkg DISTVERSION= 1.2.7 USE_GITHUB= yes GH_ACCOUNT= freebsd .... It will automatically have `MASTER_SITES` set to `GH` and `WRKSRC` to `${WRKDIR}/pkg-1.2.7`. ==== [[makefile-master_sites-github-ex2]] .More Complete Use of `USE_GITHUB` [example] ==== While trying to make a port for the bleeding edge version of pkg from the FreeBSD user on github, at https://github.com/freebsd/pkg/[], the [.filename]#Makefile# ends up looking like this (slightly stripped for the example): [.programlisting] .... PORTNAME= pkg-devel DISTVERSION= 1.3.0.a.20140411 USE_GITHUB= yes GH_ACCOUNT= freebsd GH_PROJECT= pkg GH_TAGNAME= 6dbb17b .... It will automatically have `MASTER_SITES` set to `GH` and `WRKSRC` to `${WRKDIR}/pkg-6dbb17b`. [TIP] **** `20140411` is the date of the commit referenced in `GH_TAGNAME`, not the date the [.filename]#Makefile# is edited, or the date the commit is made. **** ==== [[makefile-master_sites-github-ex3]] .Use of `USE_GITHUB` with `DISTVERSIONPREFIX` [example] ==== From time to time, `GH_TAGNAME` is a slight variation from `DISTVERSION`. For example, if the version is `1.0.2`, the tag is `v1.0.2`. In those cases, it is possible to use `DISTVERSIONPREFIX` or `DISTVERSIONSUFFIX`: [.programlisting] .... PORTNAME= foo DISTVERSIONPREFIX= v DISTVERSION= 1.0.2 USE_GITHUB= yes .... It will automatically set `GH_TAGNAME` to `v1.0.2`, while `WRKSRC` will be kept to `${WRKDIR}/foo-1.0.2`. ==== [[makefile-master_sites-github-ex4]] .Using `USE_GITHUB` When Upstream Does Not Use Versions [example] ==== If there never was a version upstream, do not invent one like `0.1` or `1.0`. Create the port with a `DISTVERSION` of `g__YYYYMMDD__`, where `g` is for Git, and `_YYYYMMDD_` represents the date the commit referenced in `GH_TAGNAME`. [.programlisting] .... PORTNAME= bar DISTVERSION= g20140411 USE_GITHUB= yes GH_TAGNAME= c472d66b .... This creates a versioning scheme that increases over time, and that is still before version `0`. See crossref:makefiles[makefile-versions-ex-pkg-version, this secion on how to compare versions] using man:pkg-version[8]): [source,shell] .... % pkg version -t g20140411 0 < .... Which means using `PORTEPOCH` will not be needed in case upstream decides to cut versions in the future. ==== [[makefile-master_sites-github-ex5]] .Using `USE_GITHUB` to Access a Commit Between Two Versions [example] ==== If the current version of the software uses a Git tag, and the port needs to be updated to a newer, intermediate version, without a tag, use man:git-describe[1] to find out the version to use: [source,shell] .... % git describe --tags f0038b1 v0.7.3-14-gf0038b1 .... `v0.7.3-14-gf0038b1` can be split into three parts: `v0.7.3`:: This is the last Git tag that appears in the commit history before the requested commit. `-14`:: This means that the requested commit, `f0038b1`, is the 14th commit after the `v0.7.3` tag. `-gf0038b1`:: The `-g` means "Git", and the `f0038b1` is the commit hash that this reference points to. [.programlisting] .... PORTNAME= bar DISTVERSIONPREFIX= v DISTVERSION= 0.7.3-14 DISTVERSIONSUFFIX= -gf0038b1 USE_GITHUB= yes .... This creates a versioning scheme that increases over time (well, over commits), and does not conflict with the creation of a `0.7.4` version. See crossref:makefiles[makefile-versions-ex-pkg-version, this section for how to compare versions] using man:pkg-version[8]): [source,shell] .... % pkg version -t 0.7.3 0.7.3.14 < % pkg version -t 0.7.3.14 0.7.4 < .... [NOTE] **** If the requested commit is the same as a tag, a shorter description is shown by default. The longer version is equivalent: [source,shell] .... % git describe --tags c66c71d v0.7.3 % git describe --tags --long c66c71d v0.7.3-0-gc66c71d .... **** ==== [[makefile-master_sites-github-multiple]] ==== Fetching Multiple Files from GitHub The `USE_GITHUB` framework also supports fetching multiple distribution files from different places in GitHub. It works in a way very similar to crossref:makefiles[porting-master-sites-n, Multiple Distribution or Patches Files from Multiple Locations]. Multiple values are added to `GH_ACCOUNT`, `GH_PROJECT`, and `GH_TAGNAME`. Each different value is assigned a group. The main value can either have no group, or the `:DEFAULT` group. A value can be omitted if it is the same as the default as listed in crossref:makefiles[makefile-master_sites-github-description,`USE_GITHUB` Description]. `GH_TUPLE` can also be used when there are a lot of distribution files. It helps keep the account, project, tagname, and group information at the same place. For each group, a `${WRKSRC_group}` helper variable is created, containing the directory into which the file has been extracted. The `${WRKSRC_group}` variables can be used to move directories around during `post-extract`, or add to `CONFIGURE_ARGS`, or whatever is needed so that the software builds correctly. [CAUTION] ==== The `:__group__` part _must_ be used for _only one_ distribution file. It is used as a unique key and using it more than once will overwrite the previous values. ==== [NOTE] ==== As this is only syntactic sugar above `DISTFILES` and `MASTER_SITES`, the group names must adhere to the restrictions on group names outlined in crossref:makefiles[porting-master-sites-n, Multiple Distribution or Patches Files from Multiple Locations] ==== When fetching multiple files from GitHub, sometimes the default distribution file is not fetched from GitHub. To disable fetching the default distribution, set: [.programlisting] .... USE_GITHUB= nodefault .... [IMPORTANT] ==== When using `USE_GITHUB=nodefault`, the [.filename]#Makefile# must set `DISTFILES` in its crossref:porting-order[porting-order-portname,top block]. The definition should be: [.programlisting] .... DISTFILES= ${DISTNAME}${EXTRACT_SUFX} .... ==== [[makefile-master_sites-github-multi]] .Use of `USE_GITHUB` with Multiple Distribution Files [example] ==== From time to time, there is a need to fetch more than one distribution file. For example, when the upstream git repository uses submodules. This can be done easily using groups in the `GH_*` variables: [.programlisting] .... PORTNAME= foo DISTVERSION= 1.0.2 USE_GITHUB= yes GH_ACCOUNT= bar:icons,contrib GH_PROJECT= foo-icons:icons foo-contrib:contrib GH_TAGNAME= 1.0:icons fa579bc:contrib GH_SUBDIR= ext/icons:icons CONFIGURE_ARGS= --with-contrib=${WRKSRC_contrib} .... This will fetch three distribution files from github. The default one comes from [.filename]#foo/foo# and is version `1.0.2`. The second one, with the `icons` group, comes from [.filename]#bar/foo-icons# and is in version `1.0`. The third one comes from [.filename]#bar/foo-contrib# and uses the Git commit `fa579bc`. The distribution files are named [.filename]#foo-foo-1.0.2_GH0.tar.gz#, [.filename]#bar-foo-icons-1.0_GH0.tar.gz#, and [.filename]#bar-foo-contrib-fa579bc_GH0.tar.gz#. All the distribution files are extracted in `${WRKDIR}` in their respective subdirectories. The default file is still extracted in `${WRKSRC}`, in this case, [.filename]#${WRKDIR}/foo-1.0.2#. Each additional distribution file is extracted in `${WRKSRC_group}`. Here, for the `icons` group, it is called `${WRKSRC_icons}` and it contains [.filename]#${WRKDIR}/foo-icons-1.0#. The file with the `contrib` group is called `${WRKSRC_contrib}` and contains `${WRKDIR}/foo-contrib-fa579bc`. The software's build system expects to find the icons in a [.filename]#ext/icons# subdirectory in its sources, so `GH_SUBDIR` is used. `GH_SUBDIR` makes sure that [.filename]#ext# exists, but that [.filename]#ext/icons# does not already exist. Then it does this: [.programlisting] .... post-extract: @${MV} ${WRKSRC_icons} ${WRKSRC}/ext/icons .... ==== [[makefile-master_sites-github-multi2]] .Use of `USE_GITHUB` with Multiple Distribution Files Using `GH_TUPLE` [example] ==== This is functionally equivalent to crossref:makefiles[makefile-master_sites-github-multi,Use of `USE_GITHUB` with Multiple Distribution Files], but using `GH_TUPLE`: [.programlisting] .... PORTNAME= foo DISTVERSION= 1.0.2 USE_GITHUB= yes GH_TUPLE= bar:foo-icons:1.0:icons/ext/icons \ bar:foo-contrib:fa579bc:contrib CONFIGURE_ARGS= --with-contrib=${WRKSRC_contrib} .... Grouping was used in the previous example with `bar:icons,contrib`. Some redundant information is present with `GH_TUPLE` because grouping is not possible. ==== [[makefile-master_sites-github-submodules]] .How to Use `USE_GITHUB` with Git Submodules? [example] ==== Ports with GitHub as an upstream repository sometimes use submodules. See man:git-submodule[1] for more information. The problem with submodules is that each is a separate repository. As such, they each must be fetched separately. Using package:finance/moneymanagerex[] as an example, its GitHub repository is https://github.com/moneymanagerex/moneymanagerex/[]. It has a https://github.com/moneymanagerex/moneymanagerex/blob/master/.gitmodules[.gitmodules] file at the root. This file describes all the submodules used in this repository, and lists additional repositories needed. This file will tell what additional repositories are needed: [.programlisting] .... [submodule "lib/wxsqlite3"] path = lib/wxsqlite3 url = https://github.com/utelle/wxsqlite3.git [submodule "3rd/mongoose"] path = 3rd/mongoose url = https://github.com/cesanta/mongoose.git [submodule "3rd/LuaGlue"] path = 3rd/LuaGlue url = https://github.com/moneymanagerex/LuaGlue.git [submodule "3rd/cgitemplate"] path = 3rd/cgitemplate url = https://github.com/moneymanagerex/html-template.git [...] .... The only information missing from that file is the commit hash or tag to use as a version. This information is found after cloning the repository: [source,shell] .... % git clone --recurse-submodules https://github.com/moneymanagerex/moneymanagerex.git Cloning into 'moneymanagerex'... remote: Counting objects: 32387, done. [...] Submodule '3rd/LuaGlue' (https://github.com/moneymanagerex/LuaGlue.git) registered for path '3rd/LuaGlue' Submodule '3rd/cgitemplate' (https://github.com/moneymanagerex/html-template.git) registered for path '3rd/cgitemplate' Submodule '3rd/mongoose' (https://github.com/cesanta/mongoose.git) registered for path '3rd/mongoose' Submodule 'lib/wxsqlite3' (https://github.com/utelle/wxsqlite3.git) registered for path 'lib/wxsqlite3' [...] Cloning into '/home/mat/work/freebsd/ports/finance/moneymanagerex/moneymanagerex/3rd/LuaGlue'... Cloning into '/home/mat/work/freebsd/ports/finance/moneymanagerex/moneymanagerex/3rd/cgitemplate'... Cloning into '/home/mat/work/freebsd/ports/finance/moneymanagerex/moneymanagerex/3rd/mongoose'... Cloning into '/home/mat/work/freebsd/ports/finance/moneymanagerex/moneymanagerex/lib/wxsqlite3'... [...] Submodule path '3rd/LuaGlue': checked out 'c51d11a247ee4d1e9817dfa2a8da8d9e2f97ae3b' Submodule path '3rd/cgitemplate': checked out 'cd434eeeb35904ebcd3d718ba29c281a649b192c' Submodule path '3rd/mongoose': checked out '2140e5992ab9a3a9a34ce9a281abf57f00f95cda' Submodule path 'lib/wxsqlite3': checked out 'fb66eb230d8aed21dec273b38c7c054dcb7d6b51' [...] % cd moneymanagerex % git submodule status c51d11a247ee4d1e9817dfa2a8da8d9e2f97ae3b 3rd/LuaGlue (heads/master) cd434eeeb35904ebcd3d718ba29c281a649b192c 3rd/cgitemplate (cd434ee) 2140e5992ab9a3a9a34ce9a281abf57f00f95cda 3rd/mongoose (6.2-138-g2140e59) fb66eb230d8aed21dec273b38c7c054dcb7d6b51 lib/wxsqlite3 (v3.4.0) [...] .... It can also be found on GitHub. Each subdirectory that is a submodule is shown as `_directory @ hash_`, for example, `mongoose @ 2140e59`. [NOTE] **** While getting the information from GitHub seems more straightforward, the information found using `git submodule status` will provide more meaningful information. For example, here, ``lib/wxsqlite3``'s commit hash `fb66eb2` correspond to `v3.4.0`. Both can be used interchangeably, but when a tag is available, use it. **** Now that all the required information has been gathered, the [.filename]#Makefile# can be written (only GitHub-related lines are shown): [.programlisting] .... PORTNAME= moneymanagerex DISTVERSIONPREFIX= v DISTVERSION= 1.3.0 USE_GITHUB= yes GH_TUPLE= utelle:wxsqlite3:v3.4.0:wxsqlite3/lib/wxsqlite3 \ moneymanagerex:LuaGlue:c51d11a:lua_glue/3rd/LuaGlue \ moneymanagerex:html-template:cd434ee:html_template/3rd/cgitemplate \ cesanta:mongoose:2140e59:mongoose/3rd/mongoose \ [...] .... ==== [[makefile-master_sites-gitlab]] === `USE_GITLAB` Similar to GitHub, if the distribution file comes from https://gitlab.com/[gitlab.com] or is hosting the GitLab software, these variables are available for use and might need to be set. [[makefile-master_sites-gitlab-description]] .`USE_GITLAB` Description [cols="1,1,1", options="header"] |=== | Variable | Description | Default |`GL_SITE` |Site name hosting the GitLab project |https://gitlab.com/ |`GL_ACCOUNT` |Account name of the GitLab user hosting the project |`${PORTNAME}` |`GL_PROJECT` |Name of the project on GitLab |`${PORTNAME}` |`GL_COMMIT` |The commit hash to download. Must be the full 160 bit, 40 character hex sha1 hash. This is a required variable for GitLab. |`(none)` |`GL_SUBDIR` |When the software needs an additional distribution file to be extracted within `${WRKSRC}`, this variable can be used. See the examples in crossref:makefiles[makefile-master_sites-gitlab-multiple, Fetching Multiple Files from GitLab] for more information. |(none) |`GL_TUPLE` |`GL_TUPLE` allows putting `GL_SITE`, `GL_ACCOUNT`, `GL_PROJECT`, `GL_COMMIT`, and `GL_SUBDIR` into a single variable. The format is _site_`:`_account_`:`_project_`:`_commit_`:`_group_`/`_subdir_. The _site_`:` and `/`_subdir_ part is optional. It is helpful when there are more than one GitLab project from which to fetch. | |=== [[makefile-master_sites-gitlab-ex1]] .Simple Use of `USE_GITLAB` [example] ==== While trying to make a port for version `1.14` of libsignon-glib from the accounts-sso user on gitlab.com, at https://gitlab.com/accounts-sso/libsignon-glib/[], The [.filename]#Makefile# would end up looking like this for fetching the distribution files: [.programlisting] .... PORTNAME= libsignon-glib DISTVERSION= 1.14 USE_GITLAB= yes GL_ACCOUNT= accounts-sso GL_COMMIT= e90302e342bfd27bc8c9132ab9d0ea3d8723fd03 .... It will automatically have `MASTER_SITES` set to https://gitlab.com/[gitlab.com] and `WRKSRC` to `${WRKDIR}/libsignon-glib-e90302e342bfd27bc8c9132ab9d0ea3d8723fd03-e90302e342bfd27bc8c9132ab9d0ea3d8723fd03`. ==== [[makefile-master_sites-gitlab-ex2]] .More Complete Use of `USE_GITLAB` [example] ==== A more complete use of the above if port had no versioning and foobar from the foo user on project bar on a self hosted GitLab site `https://gitlab.example.com/`, the [.filename]#Makefile# ends up looking like this for fetching distribution files: [.programlisting] .... PORTNAME= foobar DISTVERSION= g20170906 USE_GITLAB= yes GL_SITE= https://gitlab.example.com GL_ACCOUNT= foo GL_PROJECT= bar GL_COMMIT= 9c1669ce60c3f4f5eb43df874d7314483fb3f8a6 .... It will have `MASTER_SITES` set to `"https://gitlab.example.com"` and `WRKSRC` to `${WRKDIR}/bar-9c1669ce60c3f4f5eb43df874d7314483fb3f8a6-9c1669ce60c3f4f5eb43df874d7314483fb3f8a6`. [TIP] ====== `20170906` is the date of the commit referenced in `GL_COMMIT`, not the date the [.filename]#Makefile# is edited, or the date the commit to the FreeBSD ports tree is made. ====== [NOTE] ====== ``GL_SITE``'s protocol, port and webroot can all be modified in the same variable. ====== ==== [[makefile-master_sites-gitlab-multiple]] ==== Fetching Multiple Files from GitLab The `USE_GITLAB` framework also supports fetching multiple distribution files from different places from GitLab and GitLab hosted sites. It works in a way very similar to crossref:makefiles[porting-master-sites-n, Multiple Distribution or Patches Files from Multiple Locations] and crossref:makefiles[makefile-master_sites-gitlab-multiple, Fetching Multiple Files from GitLab]. Multiple values are added to `GL_SITE`, `GL_ACCOUNT`, `GL_PROJECT` and `GL_COMMIT`. Each different value is assigned a group. crossref:makefiles[makefile-master_sites-gitlab-description,`USE_GITLAB` Description]. `GL_TUPLE` can also be used when there are a lot of distribution files. It helps keep the site, account, project, commit, and group information at the same place. For each group, a `${WRKSRC_group}` helper variable is created, containing the directory into which the file has been extracted. The `${WRKSRC_group}` variables can be used to move directories around during `post-extract`, or add to `CONFIGURE_ARGS`, or whatever is needed so that the software builds correctly. [CAUTION] ==== The `:__group__` part _must_ be used for _only one_ distribution file. It is used as a unique key and using it more than once will overwrite the previous values. ==== [NOTE] ==== As this is only syntactic sugar above `DISTFILES` and `MASTER_SITES`, the group names must adhere to the restrictions on group names outlined in crossref:makefiles[porting-master-sites-n, Multiple Distribution or Patches Files from Multiple Locations] ==== When fetching multiple files using GitLab, sometimes the default distribution file is not fetched from a GitLab site. To disable fetching the default distribution, set: [.programlisting] .... USE_GITLAB= nodefault .... [IMPORTANT] ==== When using `USE_GITLAB=nodefault`, the [.filename]#Makefile# must set `DISTFILES` in its crossref:makefiles[porting-order-portname,top block]. The definition should be: [.programlisting] .... DISTFILES= ${DISTNAME}${EXTRACT_SUFX} .... ==== [[makefile-master_sites-gitlab-multi]] .Use of `USE_GITLAB` with Multiple Distribution Files [example] ==== From time to time, there is a need to fetch more than one distribution file. For example, when the upstream git repository uses submodules. This can be done easily using groups in the `GL_*` variables: [.programlisting] .... PORTNAME= foo DISTVERSION= 1.0.2 USE_GITLAB= yes GL_SITE= https://gitlab.example.com:9434/gitlab:icons GL_ACCOUNT= bar:icons,contrib GL_PROJECT= foo-icons:icons foo-contrib:contrib GL_COMMIT= c189207a55da45305c884fe2b50e086fcad4724b ae7368cab1ca7ca754b38d49da064df87968ffe4:icons 9e4dd76ad9b38f33fdb417a4c01935958d5acd2a:contrib GL_SUBDIR= ext/icons:icons CONFIGURE_ARGS= --with-contrib=${WRKSRC_contrib} .... This will fetch two distribution files from gitlab.com and one from `gitlab.example.com` hosting GitLab. The default one comes from [.filename]#https://gitlab.com/foo/foo# and commit is `c189207a55da45305c884fe2b50e086fcad4724b`. The second one, with the `icons` group, comes from [.filename]#https://gitlab.example.com:9434/gitlab/bar/foo-icons# and commit is `ae7368cab1ca7ca754b38d49da064df87968ffe4`. The third one comes from [.filename]#https://gitlab.com/bar/foo-contrib# and is commit `9e4dd76ad9b38f33fdb417a4c01935958d5acd2a`. The distribution files are named [.filename]#foo-foo-c189207a55da45305c884fe2b50e086fcad4724b_GL0.tar.gz#, [.filename]#bar-foo-icons-ae7368cab1ca7ca754b38d49da064df87968ffe4_GL0.tar.gz#, and [.filename]#bar-foo-contrib-9e4dd76ad9b38f33fdb417a4c01935958d5acd2a_GL0.tar.gz#. All the distribution files are extracted in `${WRKDIR}` in their respective subdirectories. The default file is still extracted in `${WRKSRC}`, in this case, [.filename]#${WRKDIR}/foo-c189207a55da45305c884fe2b50e086fcad4724b-c189207a55da45305c884fe2b50e086fcad4724b#. Each additional distribution file is extracted in `${WRKSRC_group}`. Here, for the `icons` group, it is called `${WRKSRC_icons}` and it contains [.filename]#${WRKDIR}/foo-icons-ae7368cab1ca7ca754b38d49da064df87968ffe4-ae7368cab1ca7ca754b38d49da064df87968ffe4#. The file with the `contrib` group is called `${WRKSRC_contrib}` and contains `${WRKDIR}/foo-contrib-9e4dd76ad9b38f33fdb417a4c01935958d5acd2a-9e4dd76ad9b38f33fdb417a4c01935958d5acd2a`. The software's build system expects to find the icons in a [.filename]#ext/icons# subdirectory in its sources, so `GL_SUBDIR` is used. `GL_SUBDIR` makes sure that [.filename]#ext# exists, but that [.filename]#ext/icons# does not already exist. Then it does this: [.programlisting] .... post-extract: @${MV} ${WRKSRC_icons} ${WRKSRC}/ext/icons .... ==== [[makefile-master_sites-gitlab-multi2]] .Use of `USE_GITLAB` with Multiple Distribution Files Using `GL_TUPLE` [example] ==== This is functionally equivalent to crossref:makefiles[makefile-master_sites-gitlab-multi,Use of `USE_GITLAB` with Multiple Distribution Files], but using `GL_TUPLE`: [.programlisting] .... PORTNAME= foo DISTVERSION= 1.0.2 USE_GITLAB= yes GL_COMMIT= c189207a55da45305c884fe2b50e086fcad4724b GL_TUPLE= https://gitlab.example.com:9434/gitlab:bar:foo-icons:ae7368cab1ca7ca754b38d49da064df87968ffe4:icons/ext/icons \ bar:foo-contrib:9e4dd76ad9b38f33fdb417a4c01935958d5acd2a:contrib CONFIGURE_ARGS= --with-contrib=${WRKSRC_contrib} .... Grouping was used in the previous example with `bar:icons,contrib`. Some redundant information is present with `GL_TUPLE` because grouping is not possible. ==== [[makefile-extract_sufx]] === `EXTRACT_SUFX` If there is one distribution file, and it uses an odd suffix to indicate the compression mechanism, set `EXTRACT_SUFX`. For example, if the distribution file was named [.filename]#foo.tar.gzip# instead of the more normal [.filename]#foo.tar.gz#, write: [.programlisting] .... DISTNAME= foo EXTRACT_SUFX= .tar.gzip .... The `USES=tar[:__xxx__]`, `USES=lha` or `USES=zip` automatically set `EXTRACT_SUFX` to the most common archives extensions as necessary, see crossref:uses[uses,Using `USES` Macros] for more details. If neither of these are set then `EXTRACT_SUFX` defaults to `.tar.gz`. [NOTE] ==== As `EXTRACT_SUFX` is only used in `DISTFILES`, only set one of them.. ==== [[makefile-distfiles-definition]] === `DISTFILES` Sometimes the names of the files to be downloaded have no resemblance to the name of the port. For example, it might be called [.filename]#source.tar.gz# or similar. In other cases the application's source code might be in several different archives, all of which must be downloaded. If this is the case, set `DISTFILES` to be a space separated list of all the files that must be downloaded. [.programlisting] .... DISTFILES= source1.tar.gz source2.tar.gz .... If not explicitly set, `DISTFILES` defaults to `${DISTNAME}${EXTRACT_SUFX}`. [[makefile-extract_only]] === `EXTRACT_ONLY` If only some of the `DISTFILES` must be extracted-for example, one of them is the source code, while another is an uncompressed document-list the filenames that must be extracted in `EXTRACT_ONLY`. [.programlisting] .... DISTFILES= source.tar.gz manual.html EXTRACT_ONLY= source.tar.gz .... When none of the `DISTFILES` need to be uncompressed, set `EXTRACT_ONLY` to the empty string. [.programlisting] .... EXTRACT_ONLY= .... [[porting-patchfiles]] === `PATCHFILES` If the port requires some additional patches that are available by FTP or HTTP, set `PATCHFILES` to the names of the files and `PATCH_SITES` to the URL of the directory that contains them (the format is the same as `MASTER_SITES`). If the patch is not relative to the top of the source tree (that is, `WRKSRC`) because it contains some extra pathnames, set `PATCH_DIST_STRIP` accordingly. For instance, if all the pathnames in the patch have an extra `foozolix-1.0/` in front of the filenames, then set `PATCH_DIST_STRIP=-p1`. Do not worry if the patches are compressed; they will be decompressed automatically if the filenames end with [.filename]#.Z#, [.filename]#.gz#, [.filename]#.bz2# or [.filename]#.xz#. If the patch is distributed with some other files, such as documentation, in a compressed tarball, using `PATCHFILES` is not possible. If that is the case, add the name and the location of the patch tarball to `DISTFILES` and `MASTER_SITES`. Then, use `EXTRA_PATCHES` to point to those files and [.filename]#bsd.port.mk# will automatically apply them. In particular, do _not_ copy patch files into [.filename]#${PATCHDIR}#. That directory may not be writable. [TIP] ==== If there are multiple patches and they need mixed values for the strip parameter, it can be added alongside the patch name in `PATCHFILES`, e.g: [.programlisting] .... PATCHFILES= patch1 patch2:-p1 .... This does not conflict with crossref:makefiles[porting-master-sites-n,the master site grouping feature], adding a group also works: [.programlisting] .... PATCHFILES= patch2:-p1:source2 .... ==== [NOTE] ==== The tarball will have been extracted alongside the regular source by then, so there is no need to explicitly extract it if it is a regular compressed tarball. Take extra care not to overwrite something that already exists in that directory if extracting it manually. Also, do not forget to add a command to remove the copied patch in the `pre-clean` target. ==== [[porting-master-sites-n]] === Multiple Distribution or Patches Files from Multiple Locations (Consider this to be a somewhat "advanced topic"; those new to this document may wish to skip this section at first). This section has information on the fetching mechanism known as both `MASTER_SITES:n` and `MASTER_SITES_NN`. We will refer to this mechanism as `MASTER_SITES:n`. A little background first. OpenBSD has a neat feature inside `DISTFILES` and `PATCHFILES` which allows files and patches to be postfixed with `:n` identifiers. Here, `n` can be any word containing `[0-9a-zA-Z_]` and denote a group designation. For example: [.programlisting] .... DISTFILES= alpha:0 beta:1 .... In OpenBSD, distribution file [.filename]#alpha# will be associated with variable `MASTER_SITES0` instead of our common `MASTER_SITES` and [.filename]#beta# with `MASTER_SITES1`. This is a very interesting feature which can decrease that endless search for the correct download site. Just picture 2 files in `DISTFILES` and 20 sites in `MASTER_SITES`, the sites slow as hell where [.filename]#beta# is carried by all sites in `MASTER_SITES`, and [.filename]#alpha# can only be found in the 20th site. It would be such a waste to check all of them if the maintainer knew this beforehand, would it not? Not a good start for that lovely weekend! Once the concept is clear, just imagine more `DISTFILES` and more `MASTER_SITES`. Surely our "distfiles survey meister" would appreciate the relief to network strain that this would bring. In the next sections, information will follow on the FreeBSD implementation of this idea. We improved a bit on OpenBSD's concept. [IMPORTANT] ==== The group names cannot have dashes in them (`-`), in fact, they cannot have any characters out of the `[a-zA-Z0-9_]` range. This is because, while man:make[1] is ok with variable names containing dashes, man:sh[1] is not. ==== [[porting-master-sites-n-simplified]] ==== Simplified Information This section explains how to quickly prepare fine grained fetching of multiple distribution files and patches from different sites and subdirectories. We describe here a case of simplified `MASTER_SITES:n` usage. This will be sufficient for most scenarios. More detailed information are available in crossref:makefiles[ports-master-sites-n-detailed, Detailed Information]. Some applications consist of multiple distribution files that must be downloaded from a number of different sites. For example, Ghostscript consists of the core of the program, and then a large number of driver files that are used depending on the user's printer. Some of these driver files are supplied with the core, but many others must be downloaded from a variety of different sites. To support this, each entry in `DISTFILES` may be followed by a colon and a "group name". Each site listed in `MASTER_SITES` is then followed by a colon, and the group that indicates which distribution files are downloaded from this site. For example, consider an application with the source split in two parts, [.filename]#source1.tar.gz# and [.filename]#source2.tar.gz#, which must be downloaded from two different sites. The port's [.filename]#Makefile# would include lines like crossref:makefiles[ports-master-sites-n-example-simple-use-one-file-per-site,Simplified Use of `MASTER_SITES:n` with One File Per Site]. [[ports-master-sites-n-example-simple-use-one-file-per-site]] .Simplified Use of `MASTER_SITES:n` with One File Per Site [example] ==== [.programlisting] .... MASTER_SITES= ftp://ftp1.example.com/:source1 \ http://www.example.com/:source2 DISTFILES= source1.tar.gz:source1 \ source2.tar.gz:source2 .... ==== Multiple distribution files can have the same group. Continuing the previous example, suppose that there was a third distfile, [.filename]#source3.tar.gz#, that is downloaded from `ftp.example2.com`. The [.filename]#Makefile# would then be written like crossref:makefiles[ports-master-sites-n-example-simple-use-more-than-one-file-per-site,Simplified Use of `MASTER_SITES:n` with More Than One File Per Site]. [[ports-master-sites-n-example-simple-use-more-than-one-file-per-site]] .Simplified Use of `MASTER_SITES:n` with More Than One File Per Site [example] ==== [.programlisting] .... MASTER_SITES= ftp://ftp.example.com/:source1 \ http://www.example.com/:source2 DISTFILES= source1.tar.gz:source1 \ source2.tar.gz:source2 \ source3.tar.gz:source2 .... ==== [[ports-master-sites-n-detailed]] ==== Detailed Information Okay, so the previous example did not reflect the new port's needs? In this section we will explain in detail how the fine grained fetching mechanism `MASTER_SITES:n` works and how it can be used. . Elements can be postfixed with `:__n__` where _n_ is `[^:,]\+`, that is, _n_ could conceptually be any alphanumeric string but we will limit it to `[a-zA-Z_][0-9a-zA-Z_]+` for now. + Moreover, string matching is case sensitive; that is, `n` is different from `N`. + However, these words cannot be used for postfixing purposes since they yield special meaning: `default`, `all` and `ALL` (they are used internally in item crossref:makefiles[porting-master-sites-n-what-changes-in-port-targets, ii]). Furthermore, `DEFAULT` is a special purpose word (check item crossref:makefiles[porting-master-sites-n-DEFAULT-group,3]). . Elements postfixed with `:n` belong to the group `n`, `:m` belong to group `m` and so forth. + -[[porting-master-sites-n-DEFAULT-group]] -. Elements without a postfix are groupless, they all belong to the special group +. [[porting-master-sites-n-DEFAULT-group]] Elements without a postfix are groupless, they all belong to the special group `DEFAULT`. Any elements postfixed with `DEFAULT`, is just being redundant unless an element belongs to both `DEFAULT` and other groups at the same time (check item crossref:makefiles[porting-master-sites-n-comma-operator,5]). + These examples are equivalent but the first one is preferred: + [.programlisting] .... MASTER_SITES= alpha .... + [.programlisting] .... MASTER_SITES= alpha:DEFAULT .... . Groups are not exclusive, an element may belong to several different groups at the same time and a group can either have either several different elements or none at all. + -[[porting-master-sites-n-comma-operator]] -. When an element belongs to several groups at the same time, use the comma operator (`,`). +. [[porting-master-sites-n-comma-operator]] When an element belongs to several groups at the same time, use the comma operator (`,`). + Instead of repeating it several times, each time with a different postfix, we can list several groups at once in a single postfix. For instance, `:m,n,o` marks an element that belongs to group `m`, `n` and `o`. + All these examples are equivalent but the last one is preferred: + [.programlisting] .... MASTER_SITES= alpha alpha:SOME_SITE .... + [.programlisting] .... MASTER_SITES= alpha:DEFAULT alpha:SOME_SITE .... + [.programlisting] .... MASTER_SITES= alpha:SOME_SITE,DEFAULT .... + [.programlisting] .... MASTER_SITES= alpha:DEFAULT,SOME_SITE .... . All sites within a given group are sorted according to `MASTER_SORT_AWK`. All groups within `MASTER_SITES` and `PATCH_SITES` are sorted as well. + -[[porting-master-sites-n-group-semantics]] -. Group semantics can be used in any of the variables `MASTER_SITES`, `PATCH_SITES`, `MASTER_SITE_SUBDIR`, `PATCH_SITE_SUBDIR`, `DISTFILES`, and `PATCHFILES` according to this syntax: +. [[porting-master-sites-n-group-semantics]] Group semantics can be used in any of the variables `MASTER_SITES`, `PATCH_SITES`, `MASTER_SITE_SUBDIR`, `PATCH_SITE_SUBDIR`, `DISTFILES`, and `PATCHFILES` according to this syntax: .. All `MASTER_SITES`, `PATCH_SITES`, `MASTER_SITE_SUBDIR` and `PATCH_SITE_SUBDIR` elements must be terminated with the forward slash `/` character. If any elements belong to any groups, the group postfix `:__n__` must come right after the terminator `/`. The `MASTER_SITES:n` mechanism relies on the existence of the terminator `/` to avoid confusing elements where a `:n` is a valid part of the element with occurrences where `:n` denotes group `n`. For compatibility purposes, since the `/` terminator was not required before in both `MASTER_SITE_SUBDIR` and `PATCH_SITE_SUBDIR` elements, if the postfix immediate preceding character is not a `/` then `:n` will be considered a valid part of the element instead of a group postfix even if an element is postfixed with `:n`. See both crossref:makefiles[ports-master-sites-n-example-detailed-use-master-site-subdir,Detailed Use of `MASTER_SITES:n` in `MASTER_SITE_SUBDIR`] and crossref:makefiles[ports-master-sites-n-example-detailed-use-complete-example-master-sites,Detailed Use of `MASTER_SITES:n` with Comma Operator, Multiple Files, Multiple Sites and Multiple Subdirectories]. + [[ports-master-sites-n-example-detailed-use-master-site-subdir]] .Detailed Use of `MASTER_SITES:n` in `MASTER_SITE_SUBDIR` [example] ==== [.programlisting] .... MASTER_SITE_SUBDIR= old:n new/:NEW .... *** Directories within group `DEFAULT` -> old:n *** Directories within group `NEW` -> new ==== + [[ports-master-sites-n-example-detailed-use-complete-example-master-sites]] .Detailed Use of `MASTER_SITES:n` with Comma Operator, Multiple Files, Multiple Sites and Multiple Subdirectories [example] ==== [.programlisting] .... MASTER_SITES= http://site1/%SUBDIR%/ http://site2/:DEFAULT \ http://site3/:group3 http://site4/:group4 \ http://site5/:group5 http://site6/:group6 \ http://site7/:DEFAULT,group6 \ http://site8/%SUBDIR%/:group6,group7 \ http://site9/:group8 DISTFILES= file1 file2:DEFAULT file3:group3 \ file4:group4,group5,group6 file5:grouping \ file6:group7 MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ directory-one/:group6,DEFAULT \ directory .... The previous example results in this fine grained fetching. Sites are listed in the exact order they will be used. *** [.filename]#file1# will be fetched from **** `MASTER_SITE_OVERRIDE` **** http://site1/directory-trial:1/ **** http://site1/directory-one/ **** http://site1/directory/ **** http://site2/ **** http://site7/ **** `MASTER_SITE_BACKUP` *** [.filename]#file2# will be fetched exactly as [.filename]#file1# since they both belong to the same group **** `MASTER_SITE_OVERRIDE` **** http://site1/directory-trial:1/ **** http://site1/directory-one/ **** http://site1/directory/ **** http://site2/ **** http://site7/ **** `MASTER_SITE_BACKUP` *** [.filename]#file3# will be fetched from **** `MASTER_SITE_OVERRIDE` **** http://site3/ **** `MASTER_SITE_BACKUP` *** [.filename]#file4# will be fetched from **** `MASTER_SITE_OVERRIDE` **** http://site4/ **** http://site5/ **** http://site6/ **** http://site7/ **** http://site8/directory-one/ **** `MASTER_SITE_BACKUP` *** [.filename]#file5# will be fetched from **** `MASTER_SITE_OVERRIDE` **** `MASTER_SITE_BACKUP` *** [.filename]#file6# will be fetched from **** `MASTER_SITE_OVERRIDE` **** http://site8/ **** `MASTER_SITE_BACKUP` ==== . How do I group one of the special macros from [.filename]#bsd.sites.mk#, for example, SourceForge (`SF`)? + This has been simplified as much as possible. See crossref:makefiles[ports-master-sites-n-example-detailed-use-master-site-sourceforge,Detailed Use of `MASTER_SITES:n` with SourceForge (`SF`)]. + [[ports-master-sites-n-example-detailed-use-master-site-sourceforge]] .Detailed Use of `MASTER_SITES:n` with SourceForge (`SF`) [example] ==== [.programlisting] .... MASTER_SITES= http://site1/ SF/something/1.0:sourceforge,TEST DISTFILES= something.tar.gz:sourceforge .... [.filename]#something.tar.gz# will be fetched from all sites within SourceForge. ==== . How do I use this with `PATCH*`? + All examples were done with `MASTER*` but they work exactly the same for `PATCH*` ones as can be seen in crossref:makefiles[ports-master-sites-n-example-detailed-use-patch-sites,Simplified Use of `MASTER_SITES:n` with `PATCH_SITES`]. + [[ports-master-sites-n-example-detailed-use-patch-sites]] .Simplified Use of `MASTER_SITES:n` with `PATCH_SITES` [example] ==== [.programlisting] .... PATCH_SITES= http://site1/ http://site2/:test PATCHFILES= patch1:test .... ==== [[port-master-sites-n-what-changed]] ==== What Does Change for Ports? What Does Not? [lowerroman] . All current ports remain the same. The `MASTER_SITES:n` feature code is only activated if there are elements postfixed with `:__n__` like elements according to the aforementioned syntax rules, especially as shown in item crossref:makefiles[porting-master-sites-n-group-semantics, 7]. + -[[porting-master-sites-n-what-changes-in-port-targets]] -. The port targets remain the same: `checksum`, `makesum`, `patch`, `configure`, `build`, etc. With the obvious exceptions of `do-fetch`, `fetch-list`, `master-sites` and `patch-sites`. +. [[porting-master-sites-n-what-changes-in-port-targets]] The port targets remain the same: `checksum`, `makesum`, `patch`, `configure`, `build`, etc. With the obvious exceptions of `do-fetch`, `fetch-list`, `master-sites` and `patch-sites`. ** `do-fetch`: deploys the new grouping postfixed `DISTFILES` and `PATCHFILES` with their matching group elements within both `MASTER_SITES` and `PATCH_SITES` which use matching group elements within both `MASTER_SITE_SUBDIR` and `PATCH_SITE_SUBDIR`. Check crossref:makefiles[ports-master-sites-n-example-detailed-use-complete-example-master-sites,Detailed Use of `MASTER_SITES:n` with Comma Operator, Multiple Files, Multiple Sites and Multiple Subdirectories]. ** `fetch-list`: works like old `fetch-list` with the exception that it groups just like `do-fetch`. ** `master-sites` and `patch-sites`: (incompatible with older versions) only return the elements of group `DEFAULT`; in fact, they execute targets `master-sites-default` and `patch-sites-default` respectively. + Furthermore, using target either `master-sites-all` or `patch-sites-all` is preferred to directly checking either `MASTER_SITES` or `PATCH_SITES`. Also, directly checking is not guaranteed to work in any future versions. Check item crossref:makefiles[porting-master-sites-n-new-port-targets-master-sites-all, B] for more information on these new port targets. . New port targets .. There are `master-sites-_n_` and `patch-sites-_n_` targets which will list the elements of the respective group _n_ within `MASTER_SITES` and `PATCH_SITES` respectively. For instance, both `master-sites-DEFAULT` and `patch-sites-DEFAULT` will return the elements of group `DEFAULT`, `master-sites-test` and `patch-sites-test` of group `test`, and thereon. + -[[porting-master-sites-n-new-port-targets-master-sites-all]] -.. There are new targets `master-sites-all` and `patch-sites-all` which do the work of the old `master-sites` and `patch-sites` ones. They return the elements of all groups as if they all belonged to the same group with the caveat that it lists as many `MASTER_SITE_BACKUP` and `MASTER_SITE_OVERRIDE` as there are groups defined within either `DISTFILES` or `PATCHFILES`; respectively for `master-sites-all` and `patch-sites-all`. +.. [[porting-master-sites-n-new-port-targets-master-sites-all]] There are new targets `master-sites-all` and `patch-sites-all` which do the work of the old `master-sites` and `patch-sites` ones. They return the elements of all groups as if they all belonged to the same group with the caveat that it lists as many `MASTER_SITE_BACKUP` and `MASTER_SITE_OVERRIDE` as there are groups defined within either `DISTFILES` or `PATCHFILES`; respectively for `master-sites-all` and `patch-sites-all`. [[makefile-dist_subdir]] === `DIST_SUBDIR` Do not let the port clutter [.filename]#/usr/ports/distfiles#. If the port requires a lot of files to be fetched, or contains a file that has a name that might conflict with other ports (for example, [.filename]#Makefile#), set `DIST_SUBDIR` to the name of the port (`${PORTNAME}` or `${PKGNAMEPREFIX}${PORTNAME}` are fine). This will change `DISTDIR` from the default [.filename]#/usr/ports/distfiles# to [.filename]#/usr/ports/distfiles/${DIST_SUBDIR}#, and in effect puts everything that is required for the port into that subdirectory. It will also look at the subdirectory with the same name on the backup master site at http://distcache.FreeBSD.org[http://distcache.FreeBSD.org] (Setting `DISTDIR` explicitly in [.filename]#Makefile# will not accomplish this, so please use `DIST_SUBDIR`.) [NOTE] ==== This does not affect `MASTER_SITES` defined in the [.filename]#Makefile#. ==== [[makefile-maintainer]] == `MAINTAINER` Set the mail-address here. Please. _:-)_ Only a single address without the comment part is allowed as a `MAINTAINER` value. The format used is `user@hostname.domain`. Please do not include any descriptive text such as a real name in this entry. That merely confuses the Ports infrastructure and most tools using it. The maintainer is responsible for keeping the port up to date and making sure that it works correctly. For a detailed description of the responsibilities of a port maintainer, refer to extref:{contributing}[The challenge for port maintainers, maintain-port]. [NOTE] ==== A maintainer volunteers to keep a port in good working order. Maintainers have the primary responsibility for their ports, but not exclusive ownership. Ports exist for the benefit of the community and, in reality, belong to the community. What this means is that people other than the maintainer can make changes to a port. Large changes to the Ports Collection might require changes to many ports. The FreeBSD Ports Management Team or members of other teams might modify ports to fix dependency issues or other problems, like a version bump for a shared library update. Some types of fixes have "blanket approval" from the {portmgr}, allowing any committer to fix those categories of problems on any port. These fixes do not need approval from the maintainer. Blanket approval for most ports applies to fixes like infrastructure changes, or trivial and _tested_ build and runtime fixes. The current list is available in extref:{committers-guide}[Ports section of the Committer's Guide, ports-qa-misc-blanket-approval]. ==== Other changes to the port will be sent to the maintainer for review and approval before being committed. If the maintainer does not respond to an update request after two weeks (excluding major public holidays), then that is considered a maintainer timeout, and the update can be made without explicit maintainer approval. If the maintainer does not respond within three months, or if there have been three consecutive timeouts, then that maintainer is considered absent without leave, and all of their ports can be assigned back to the pool. Exceptions to this are anything maintained by the {portmgr}, or the {security-officer}. No unauthorized commits may ever be made to ports maintained by those groups. We reserve the right to modify the maintainer's submission to better match existing policies and style of the Ports Collection without explicit blessing from the submitter or the maintainer. Also, large infrastructural changes can result in a port being modified without the maintainer's consent. These kinds of changes will never affect the port's functionality. The {portmgr} reserves the right to revoke or override anyone's maintainership for any reason, and the {security-officer} reserves the right to revoke or override maintainership for security reasons. [[makefile-comment]] == `COMMENT` The comment is a one-line description of a port shown by `pkg info`. Please follow these rules when composing it: . The COMMENT string should be 70 characters or less. . Do _not_ include the package name or version number of software. . The comment must begin with a capital and end without a period. . Do not start with an indefinite article (that is, A or An). . Capitalize names such as Apache, JavaScript, or Perl. . Use a serial comma for lists of words: "green, red, and blue." . Check for spelling errors. Here is an example: [.programlisting] .... COMMENT= Cat chasing a mouse all over the screen .... The COMMENT variable immediately follows the MAINTAINER variable in the [.filename]#Makefile#. [[makefile-www]] == Project website Each port should point to a website that provides more information about the software. Whenever possible, this should be the official project website maintained by the developers of the software. [.programlisting] .... WWW= https://ffmpeg.org/ .... But it can also be a directory or resource in the source code repository: [.programlisting] .... WWW= https://sourceforge.net/projects/mpd/ .... The WWW variable immediately follows the COMMENT variable in the [.filename]#Makefile#. If the same content can be accessed via HTTP and HTTPS, the URL starting with `https://` shall be used. If the URI is the root of the website or directory, it must be terminated with a slash. This information used to be placed into the last line of the [.filename]#pkg-descr# file. It has been moved into the Makefile for easier maintenance and processing. Having a `WWW:` line at the end of the [.filename]#pkg-descr# file is deprecated. [[licenses]] == Licenses Each port must document the license under which it is available. If it is not an OSI approved license it must also document any restrictions on redistribution. [[licenses-license]] === `LICENSE` A short name for the license or licenses if more than one license apply. If it is one of the licenses listed in crossref:makefiles[licenses-license-list,Predefined License List], only `LICENSE_FILE` and `LICENSE_DISTFILES` variables can be set. If this is a license that has not been defined in the ports framework (see crossref:makefiles[licenses-license-list,Predefined License List]), the `LICENSE_PERMS` and `LICENSE_NAME` must be set, along with either `LICENSE_FILE` or `LICENSE_TEXT`. `LICENSE_DISTFILES` and `LICENSE_GROUPS` can also be set, but are not required. The predefined licenses are shown in crossref:makefiles[licenses-license-list,Predefined License List]. The current list is always available in [.filename]#Mk/bsd.licenses.db.mk#. [[licenses-license-ex1]] .Simplest Usage, Predefined Licenses [example] ==== When the [.filename]#README# of some software says "This software is under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version." but does not provide the license file, use this: [.programlisting] .... LICENSE= LGPL21+ .... When the software provides the license file, use this: [.programlisting] .... LICENSE= LGPL21+ LICENSE_FILE= ${WRKSRC}/COPYING .... ==== For the predefined licenses, the default permissions are `dist-mirror dist-sell pkg-mirror pkg-sell auto-accept`. [[licenses-license-list]] .Predefined License List [cols="1,1,1,1", frame="none", options="header"] |=== | Short Name | Name | Group | Permissions |`AGPLv3` |GNU Affero General Public License version 3 |`FSF GPL OSI` |(default) |`AGPLv3+` |GNU Affero General Public License version 3 (or later) |`FSF GPL OSI` |(default) |`APACHE10` |Apache License 1.0 |`FSF` |(default) |`APACHE11` |Apache License 1.1 |`FSF OSI` |(default) |`APACHE20` |Apache License 2.0 |`FSF OSI` |(default) |`ART10` |Artistic License version 1.0 |`OSI` |(default) |`ART20` |Artistic License version 2.0 |`FSF GPL OSI` |(default) |`ARTPERL10` |Artistic License (perl) version 1.0 |`OSI` |(default) |`BSD` |BSD license Generic Version (deprecated) |`FSF OSI COPYFREE` |(default) |`BSD2CLAUSE` |BSD 2-clause "Simplified" License |`FSF OSI COPYFREE` |(default) |`BSD3CLAUSE` |BSD 3-clause "New" or "Revised" License |`FSF OSI COPYFREE` |(default) |`BSD4CLAUSE` |BSD 4-clause "Original" or "Old" License |`FSF` |(default) |`BSL` |Boost Software License |`FSF OSI COPYFREE` |(default) |`CC-BY-1.0` |Creative Commons Attribution 1.0 | |(default) |`CC-BY-2.0` |Creative Commons Attribution 2.0 | |(default) |`CC-BY-2.5` |Creative Commons Attribution 2.5 | |(default) |`CC-BY-3.0` |Creative Commons Attribution 3.0 | |(default) |`CC-BY-4.0` |Creative Commons Attribution 4.0 | |(default) |`CC-BY-NC-1.0` |Creative Commons Attribution Non Commercial 1.0 | |`dist-mirror``pkg-mirror``auto-accept` |`CC-BY-NC-2.0` |Creative Commons Attribution Non Commercial 2.0 | |`dist-mirror``pkg-mirror``auto-accept` |`CC-BY-NC-2.5` |Creative Commons Attribution Non Commercial 2.5 | |`dist-mirror``pkg-mirror``auto-accept` |`CC-BY-NC-3.0` |Creative Commons Attribution Non Commercial 3.0 | |`dist-mirror``pkg-mirror``auto-accept` |`CC-BY-NC-4.0` |Creative Commons Attribution Non Commercial 4.0 | |`dist-mirror``pkg-mirror``auto-accept` |`CC-BY-NC-ND-1.0` |Creative Commons Attribution Non Commercial No Derivatives 1.0 | |`dist-mirror``pkg-mirror``auto-accept` |`CC-BY-NC-ND-2.0` |Creative Commons Attribution Non Commercial No Derivatives 2.0 | |`dist-mirror``pkg-mirror``auto-accept` |`CC-BY-NC-ND-2.5` |Creative Commons Attribution Non Commercial No Derivatives 2.5 | |`dist-mirror``pkg-mirror``auto-accept` |`CC-BY-NC-ND-3.0` |Creative Commons Attribution Non Commercial No Derivatives 3.0 | |`dist-mirror``pkg-mirror``auto-accept` |`CC-BY-NC-ND-4.0` |Creative Commons Attribution Non Commercial No Derivatives 4.0 | |`dist-mirror``pkg-mirror``auto-accept` |`CC-BY-NC-SA-1.0` |Creative Commons Attribution Non Commercial Share Alike 1.0 | |`dist-mirror``pkg-mirror``auto-accept` |`CC-BY-NC-SA-2.0` |Creative Commons Attribution Non Commercial Share Alike 2.0 | |`dist-mirror``pkg-mirror``auto-accept` |`CC-BY-NC-SA-2.5` |Creative Commons Attribution Non Commercial Share Alike 2.5 | |`dist-mirror``pkg-mirror``auto-accept` |`CC-BY-NC-SA-3.0` |Creative Commons Attribution Non Commercial Share Alike 3.0 | |`dist-mirror``pkg-mirror``auto-accept` |`CC-BY-NC-SA-4.0` |Creative Commons Attribution Non Commercial Share Alike 4.0 | |`dist-mirror``pkg-mirror``auto-accept` |`CC-BY-ND-1.0` |Creative Commons Attribution No Derivatives 1.0 | |(default) |`CC-BY-ND-2.0` |Creative Commons Attribution No Derivatives 2.0 | |(default) |`CC-BY-ND-2.5` |Creative Commons Attribution No Derivatives 2.5 | |(default) |`CC-BY-ND-3.0` |Creative Commons Attribution No Derivatives 3.0 | |(default) |`CC-BY-ND-4.0` |Creative Commons Attribution No Derivatives 4.0 | |(default) |`CC-BY-SA-1.0` |Creative Commons Attribution Share Alike 1.0 | |(default) |`CC-BY-SA-2.0` |Creative Commons Attribution Share Alike 2.0 | |(default) |`CC-BY-SA-2.5` |Creative Commons Attribution Share Alike 2.5 | |(default) |`CC-BY-SA-3.0` |Creative Commons Attribution Share Alike 3.0 | |(default) |`CC-BY-SA-4.0` |Creative Commons Attribution Share Alike 4.0 | |(default) |`CC0-1.0` |Creative Commons Zero v1.0 Universal |`FSF GPL COPYFREE` |(default) |`CDDL` |Common Development and Distribution License |`FSF OSI` |(default) |`CPAL-1.0` |Common Public Attribution License |`FSF OSI` |(default) |`ClArtistic` |Clarified Artistic License |`FSF GPL OSI` |(default) |`EPL` |Eclipse Public License |`FSF OSI` |(default) |`GFDL` |GNU Free Documentation License |`FSF` |(default) |`GMGPL` |GNAT Modified General Public License |`FSF GPL OSI` |(default) |`GPLv1` |GNU General Public License version 1 |`FSF GPL OSI` |(default) |`GPLv1+` |GNU General Public License version 1 (or later) |`FSF GPL OSI` |(default) |`GPLv2` |GNU General Public License version 2 |`FSF GPL OSI` |(default) |`GPLv2+` |GNU General Public License version 2 (or later) |`FSF GPL OSI` |(default) |`GPLv3` |GNU General Public License version 3 |`FSF GPL OSI` |(default) |`GPLv3+` |GNU General Public License version 3 (or later) |`FSF GPL OSI` |(default) |`GPLv3RLE` |GNU GPL version 3 Runtime Library Exception |`FSF GPL OSI` |(default) |`GPLv3RLE+` |GNU GPL version 3 Runtime Library Exception (or later) |`FSF GPL OSI` |(default) |`ISCL` |Internet Systems Consortium License |`FSF GPL OSI COPYFREE` |(default) |`LGPL20` |GNU Library General Public License version 2.0 |`FSF GPL OSI` |(default) |`LGPL20+` |GNU Library General Public License version 2.0 (or later) |`FSF GPL OSI` |(default) |`LGPL21` |GNU Lesser General Public License version 2.1 |`FSF GPL OSI` |(default) |`LGPL21+` |GNU Lesser General Public License version 2.1 (or later) |`FSF GPL OSI` |(default) |`LGPL3` |GNU Lesser General Public License version 3 |`FSF GPL OSI` |(default) |`LGPL3+` |GNU Lesser General Public License version 3 (or later) |`FSF GPL OSI` |(default) |`LPPL10` |LaTeX Project Public License version 1.0 |`FSF OSI` |`dist-mirror dist-sell` |`LPPL11` |LaTeX Project Public License version 1.1 |`FSF OSI` |`dist-mirror dist-sell` |`LPPL12` |LaTeX Project Public License version 1.2 |`FSF OSI` |`dist-mirror dist-sell` |`LPPL13` |LaTeX Project Public License version 1.3 |`FSF OSI` |`dist-mirror dist-sell` |`LPPL13a` |LaTeX Project Public License version 1.3a |`FSF OSI` |`dist-mirror dist-sell` |`LPPL13b` |LaTeX Project Public License version 1.3b |`FSF OSI` |`dist-mirror dist-sell` |`LPPL13c` |LaTeX Project Public License version 1.3c |`FSF OSI` |`dist-mirror dist-sell` |`MIT` |MIT license / X11 license |`COPYFREE FSF GPL OSI` |(default) |`MPL10` |Mozilla Public License version 1.0 |`FSF OSI` |(default) |`MPL11` |Mozilla Public License version 1.1 |`FSF OSI` |(default) |`MPL20` |Mozilla Public License version 2.0 |`FSF OSI` |(default) |`NCSA` |University of Illinois/NCSA Open Source License |`COPYFREE FSF GPL OSI` |(default) |`NONE` |No license specified | |`none` |`OFL10` |SIL Open Font License version 1.0 (https://scripts.sil.org/OFL/) |`FONTS` |(default) |`OFL11` |SIL Open Font License version 1.1 (https://scripts.sil.org/OFL/) |`FONTS` |(default) |`OWL` |Open Works License (owl.apotheon.org) |`COPYFREE` |(default) |`OpenSSL` |OpenSSL License |`FSF` |(default) |`PD` |Public Domain |`GPL COPYFREE` |(default) |`PHP202` |PHP License version 2.02 |`FSF OSI` |(default) |`PHP30` |PHP License version 3.0 |`FSF OSI` |(default) |`PHP301` |PHP License version 3.01 |`FSF OSI` |(default) |`PSFL` |Python Software Foundation License |`FSF GPL OSI` |(default) |`PostgreSQL` |PostgreSQL License |`FSF GPL OSI COPYFREE` |(default) |`RUBY` |Ruby License |`FSF` |(default) |`UNLICENSE` |The Unlicense |`COPYFREE FSF GPL` |(default) |`WTFPL` |Do What the Fuck You Want To Public License version 2 |`GPL FSF COPYFREE` |(default) |`WTFPL1` |Do What the Fuck You Want To Public License version 1 |`GPL FSF COPYFREE` |(default) |`ZLIB` |zlib License |`GPL FSF OSI` |(default) |`ZPL21` |Zope Public License version 2.1 |`GPL OSI` |(default) |=== [[licenses-license_perms]] === `LICENSE_PERMS` and `LICENSE_PERMS_NAME_` Permissions. use `none` if empty. .License Permissions List [[licenses-license_perms-dist-mirror]] `dist-mirror`:: Redistribution of the distribution files is permitted. The distribution files will be added to the FreeBSD `MASTER_SITE_BACKUP` CDN. [[licenses-license_perms-no-dist-mirror]] `no-dist-mirror`:: Redistribution of the distribution files is prohibited. This is equivalent to setting crossref:special[porting-restrictions-restricted,`RESTRICTED`]. The distribution files will _not_ be added to the FreeBSD `MASTER_SITE_BACKUP` CDN. [[licenses-license_perms-dist-sell]] `dist-sell`:: Selling of distribution files is permitted. The distribution files will be present on the installer images. [[licenses-license_perms-no-dist-sell]] `no-dist-sell`:: Selling of distribution files is prohibited. This is equivalent to setting crossref:special[porting-restrictions-no_cdrom,`NO_CDROM`]. [[licenses-license_perms-pkg-mirror]] `pkg-mirror`:: Free redistribution of package is permitted. The package will be distributed on the FreeBSD package CDN https://pkg.freebsd.org/[https://pkg.freebsd.org/]. [[licenses-license_perms-no-pkg-mirror]] `no-pkg-mirror`:: Free redistribution of package is prohibited. Equivalent to setting crossref:special[porting-restrictions-no_package,`NO_PACKAGE`]. The package will _not_ be distributed from the FreeBSD package CDN https://pkg.freebsd.org/[https://pkg.freebsd.org/]. [[licenses-license_perms-pkg-sell]] `pkg-sell`:: Selling of package is permitted. The package will be present on the installer images. [[licenses-license_perms-no-pkg-sell]] `no-pkg-sell`:: Selling of package is prohibited. This is equivalent to setting crossref:special[porting-restrictions-no_cdrom,`NO_CDROM`]. The package will _not_ be present on the installer images. [[licenses-license_perms-auto-accept]] `auto-accept`:: License is accepted by default. Prompts to accept a license are not displayed unless the user has defined `LICENSES_ASK`. Use this unless the license states the user must accept the terms of the license. [[licenses-license_perms-no-auto-accept]] `no-auto-accept`:: License is not accepted by default. The user will always be asked to confirm the acceptance of this license. This must be used if the license states that the user must accept its terms. When both `_permission_` and `no-_permission_` is present the `no-_permission_` will cancel `_permission_`. When `_permission_` is not present, it is considered to be a `no-_permission_`. [WARNING] ==== Some missing permissions will prevent a port (and all ports depending on it) from being usable by package users: A port without the `auto-accept` permission will never be be built and all the ports depending on it will be ignored. A port without the `pkg-mirror` permission, and any ports that depend on it, will be removed after the build, thus ensuring they are not distributed. ==== [[licenses-license_perms-ex1]] .Nonstandard License [example] ==== Read the terms of the license and translate those using the available permissions. [.programlisting] .... LICENSE= UNKNOWN LICENSE_NAME= unknown LICENSE_TEXT= This program is NOT in public domain.\ It can be freely distributed for non-commercial purposes only. LICENSE_PERMS= dist-mirror no-dist-sell pkg-mirror no-pkg-sell auto-accept .... ==== [[licenses-license_perms-ex2]] .Standard and Nonstandard Licenses [example] ==== Read the terms of the license and express those using the available permissions. In case of doubt, please ask for guidance on the {freebsd-ports}. [.programlisting] .... LICENSE= WARSOW GPLv2 LICENSE_COMB= multi LICENSE_NAME_WARSOW= Warsow Content License LICENSE_FILE_WARSOW= ${WRKSRC}/docs/license.txt LICENSE_PERMS_WARSOW= dist-mirror pkg-mirror auto-accept .... When the permissions of the GPLv2 and the UNKNOWN licenses are mixed, the port ends up with `dist-mirror dist-sell pkg-mirror pkg-sell auto-accept dist-mirror no-dist-sell pkg-mirror no-pkg-sell auto-accept`. The `no-_permissions_` cancel the _permissions_. The resulting list of permissions are _dist-mirror pkg-mirror auto-accept_. The distribution files and the packages will not be available on the installer images. ==== [[licenses-license_groups]] === `LICENSE_GROUPS` and `LICENSE_GROUPS_NAME` Groups the license belongs. .Predefined License Groups List [[licenses-license_groups-FSF]] `FSF`:: Free Software Foundation Approved, see the https://www.fsf.org/licensing/[FSF Licensing & Compliance Team]. [[licenses-license_groups-GPL]] `GPL`:: GPL Compatible [[licenses-license_groups-OSI]] `OSI`:: OSI Approved, see the Open Source Initiative https://opensource.org/licenses/[Open Source Licenses] page. [[licenses-license_groups-COPYFREE]] `COPYFREE`:: Comply with Copyfree Standard Definition, see the https://copyfree.org/standard/licenses/[Copyfree Licenses] page. [[licenses-license_groups-FONTS]] `FONTS`:: Font licenses [[licenses-license_name]] === `LICENSE_NAME` and `LICENSE_NAME_NAME` Full name of the license. [[licenses-license_name-ex1]] .`LICENSE_NAME` [example] ==== [.programlisting] .... LICENSE= UNRAR LICENSE_NAME= UnRAR License LICENSE_FILE= ${WRKSRC}/license.txt LICENSE_PERMS= dist-mirror dist-sell pkg-mirror pkg-sell auto-accept .... ==== [[licenses-license_file]] === `LICENSE_FILE` and `LICENSE_FILE_NAME` Full path to the file containing the license text, usually [.filename]#${WRKSRC}/some/file#. If the file is not in the distfile, and its content is too long to be put in crossref:makefiles[licenses-license_text,`LICENSE_TEXT`], put it in a new file in [.filename]#${FILESDIR}#. [[licenses-license_file-ex1]] .`LICENSE_FILE` [example] ==== [.programlisting] .... LICENSE= GPLv3+ LICENSE_FILE= ${WRKSRC}/COPYING .... ==== [[licenses-license_text]] === `LICENSE_TEXT` and `LICENSE_TEXT_NAME` Text to use as a license. Useful when the license is not in the distribution files and its text is short. [[licenses-license_text-ex1]] .`LICENSE_TEXT` [example] ==== [.programlisting] .... LICENSE= UNKNOWN LICENSE_NAME= unknown LICENSE_TEXT= This program is NOT in public domain.\ It can be freely distributed for non-commercial purposes only,\ and THERE IS NO WARRANTY FOR THIS PROGRAM. LICENSE_PERMS= dist-mirror no-dist-sell pkg-mirror no-pkg-sell auto-accept .... ==== [[licenses-license_distfiles]] === `LICENSE_DISTFILES` and `LICENSE_DISTFILES_NAME` The distribution files to which the licenses apply. Defaults to all the distribution files. [[licenses-license_distfiles-ex1]] .`LICENSE_DISTFILES` [example] ==== Used when the distribution files do not all have the same license. For example, one has a code license, and another has some artwork that cannot be redistributed: [.programlisting] .... MASTER_SITES= SF/some-game DISTFILES= ${DISTNAME}${EXTRACT_SUFX} artwork.zip LICENSE= BSD3CLAUSE ARTWORK LICENSE_COMB= dual LICENSE_NAME_ARTWORK= The game artwork license LICENSE_TEXT_ARTWORK= The README says that the files cannot be redistributed LICENSE_PERMS_ARTWORK= pkg-mirror pkg-sell auto-accept LICENSE_DISTFILES_BSD3CLAUSE= ${DISTNAME}${EXTRACT_SUFX} LICENSE_DISTFILES_ARTWORK= artwork.zip .... ==== [[licenses-license_comb]] === `LICENSE_COMB` Set to `multi` if all licenses apply. Set to `dual` if any license applies. Defaults to `single`. [[licenses-license_comb-ex1]] .Dual Licenses [example] ==== When a port says "This software may be distributed under the GNU General Public License or the Artistic License", it means that either license can be used. Use this: [.programlisting] .... LICENSE= ART10 GPLv1 LICENSE_COMB= dual .... If license files are provided, use this: [.programlisting] .... LICENSE= ART10 GPLv1 LICENSE_COMB= dual LICENSE_FILE_ART10= ${WRKSRC}/Artistic LICENSE_FILE_GPLv1= ${WRKSRC}/Copying .... ==== [[licenses-license_comb-ex2]] .Multiple Licenses [example] ==== When part of a port has one license, and another part has a different license, use `multi`: [.programlisting] .... LICENSE= GPLv2 LGPL21+ LICENSE_COMB= multi .... ==== [[makefile-portscout]] == `PORTSCOUT` Portscout is an automated distfile check utility for the FreeBSD Ports Collection, described in detail in crossref:keeping-up[distfile-survey,Portscout: the FreeBSD Ports Distfile Scanner]. `PORTSCOUT` defines special conditions within which the Portscout distfile scanner is restricted. Situations where `PORTSCOUT` is set include: * When distfiles have to be ignored for specific versions. For example, to exclude version _8.2_ and version _8.3_ from distfile version checks because they are known to be broken, add: + [.programlisting] .... PORTSCOUT= skipv:8.2,8.3 .... * When distfile version checks have to be disabled completely. For example, if a port is not going to be updated ever again, add: + [.programlisting] .... PORTSCOUT= ignore:1 .... * When specific versions or specific major and minor revisions of a distfile must be checked. For example, if only version _0.6.4_ must be monitored because newer versions have compatibility issues with FreeBSD, add: + [.programlisting] .... PORTSCOUT= limit:^0\.6\.4 .... * When URLs listing the available versions differ from the download URLs. For example, to limit distfile version checks to the download page for the package:databases/pgtune[] port, add: + [.programlisting] .... PORTSCOUT= site:http://www.renpy.org/dl/release/ .... [[makefile-depend]] == Dependencies Many ports depend on other ports. This is a very convenient feature of most Unix-like operating systems, including FreeBSD. Multiple ports can share a common dependency, rather than bundling that dependency with every port or package that needs it. There are seven variables that can be used to ensure that all the required bits will be on the user's machine. There are also some pre-supported dependency variables for common cases, plus a few more to control the behavior of dependencies. [IMPORTANT] ==== When software has extra dependencies that provide extra features, the base dependencies listed in `*_DEPENDS` should include the extra dependencies that would benefit most users. The base dependencies should never be a "minimal" dependency set. The goal is not to include every dependency possible. Only include those that will benefit most people. ==== [[makefile-lib_depends]] === `LIB_DEPENDS` This variable specifies the shared libraries this port depends on. It is a list of `_lib:dir_` tuples where `_lib_` is the name of the shared library, `_dir_` is the directory in which to find it in case it is not available. For example, [.programlisting] .... LIB_DEPENDS= libjpeg.so:graphics/jpeg .... will check for a shared jpeg library with any version, and descend into the [.filename]#graphics/jpeg# subdirectory of the ports tree to build and install it if it is not found. The dependency is checked twice, once from within the `build` target and then from within the `install` target. Also, the name of the dependency is put into the package so that `pkg install` (see man:pkg-install[8]) will automatically install it if it is not on the user's system. [[makefile-run_depends]] === `RUN_DEPENDS` This variable specifies executables or files this port depends on during run-time. It is a list of ``_path:dir_``[:``_target_``] tuples where `_path_` is the name of the executable or file, _dir_ is the directory in which to find it in case it is not available, and _target_ is the target to call in that directory. If _path_ starts with a slash (`/`), it is treated as a file and its existence is tested with `test -e`; otherwise, it is assumed to be an executable, and `which -s` is used to determine if the program exists in the search path. For example, [.programlisting] .... RUN_DEPENDS= ${LOCALBASE}/news/bin/innd:news/inn \ xmlcatmgr:textproc/xmlcatmgr .... will check if the file or directory [.filename]#/usr/local/news/bin/innd# exists, and build and install it from the [.filename]#news/inn# subdirectory of the ports tree if it is not found. It will also see if an executable called `xmlcatmgr` is in the search path, and descend into [.filename]#textproc/xmlcatmgr# to build and install it if it is not found. [NOTE] ==== In this case, `innd` is actually an executable; if an executable is in a place that is not expected to be in the search path, use the full pathname. ==== [NOTE] ==== The official search `PATH` used on the ports build cluster is [.programlisting] .... /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin .... ==== The dependency is checked from within the `install` target. Also, the name of the dependency is put into the package so that `pkg install` (see man:pkg-install[8]) will automatically install it if it is not on the user's system. The _target_ part can be omitted if it is the same as `DEPENDS_TARGET`. A quite common situation is when `RUN_DEPENDS` is literally the same as `BUILD_DEPENDS`, especially if ported software is written in a scripted language or if it requires the same build and run-time environment. In this case, it is both tempting and intuitive to directly assign one to the other: [.programlisting] .... RUN_DEPENDS= ${BUILD_DEPENDS} .... However, such assignment can pollute run-time dependencies with entries not defined in the port's original `BUILD_DEPENDS`. This happens because of man:make[1]'s lazy evaluation of variable assignment. Consider a [.filename]#Makefile# with `USE_*`, which are processed by [.filename]#ports/Mk/bsd.*.mk# to augment initial build dependencies. For example, `USES= gmake` adds package:devel/gmake[] to `BUILD_DEPENDS`. To prevent such additional dependencies from polluting `RUN_DEPENDS`, create another variable with the current content of `BUILD_DEPENDS` and assign it to both `BUILD_DEPENDS` and `RUN_DEPENDS`: [.programlisting] .... MY_DEPENDS= some:devel/some \ other:lang/other BUILD_DEPENDS= ${MY_DEPENDS} RUN_DEPENDS= ${MY_DEPENDS} .... [IMPORTANT] ==== _Do not_ use `:=` to assign `BUILD_DEPENDS` to `RUN_DEPENDS` or vice-versa. All variables are expanded immediately, which is exactly the wrong thing to do and almost always a failure. ==== [[makefile-build_depends]] === `BUILD_DEPENDS` This variable specifies executables or files this port requires to build. Like `RUN_DEPENDS`, it is a list of ``_path:dir_``[:``_target_``] tuples. For example, [.programlisting] .... BUILD_DEPENDS= unzip:archivers/unzip .... will check for an executable called `unzip`, and descend into the [.filename]#archivers/unzip# subdirectory of the ports tree to build and install it if it is not found. [NOTE] ==== "build" here means everything from extraction to compilation. The dependency is checked from within the `extract` target. The _target_ part can be omitted if it is the same as `DEPENDS_TARGET` ==== [[makefile-fetch_depends]] === `FETCH_DEPENDS` This variable specifies executables or files this port requires to fetch. Like the previous two, it is a list of ``_path:dir_``[:``_target_``] tuples. For example, [.programlisting] .... FETCH_DEPENDS= ncftp2:net/ncftp2 .... will check for an executable called `ncftp2`, and descend into the [.filename]#net/ncftp2# subdirectory of the ports tree to build and install it if it is not found. The dependency is checked from within the `fetch` target. The _target_ part can be omitted if it is the same as `DEPENDS_TARGET`. [[makefile-extract_depends]] === `EXTRACT_DEPENDS` This variable specifies executables or files this port requires for extraction. Like the previous, it is a list of ``_path:dir_``[:``_target_``] tuples. For example, [.programlisting] .... EXTRACT_DEPENDS= unzip:archivers/unzip .... will check for an executable called `unzip`, and descend into the [.filename]#archivers/unzip# subdirectory of the ports tree to build and install it if it is not found. The dependency is checked from within the `extract` target. The _target_ part can be omitted if it is the same as `DEPENDS_TARGET`. [NOTE] ==== Use this variable only if the extraction does not already work (the default assumes `tar`) and cannot be made to work using `USES=tar`, `USES=lha` or `USES=zip` described in crossref:uses[uses,Using `USES` Macros]. ==== [[makefile-patch_depends]] === `PATCH_DEPENDS` This variable specifies executables or files this port requires to patch. Like the previous, it is a list of ``_path:dir_``[:``_target_``] tuples. For example, [.programlisting] .... PATCH_DEPENDS= ${NONEXISTENT}:java/jfc:extract .... will descend into the [.filename]#java/jfc# subdirectory of the ports tree to extract it. The dependency is checked from within the `patch` target. The _target_ part can be omitted if it is the same as `DEPENDS_TARGET`. [[makefile-uses]] === `USES` Parameters can be added to define different features and dependencies used by the port. They are specified by adding this line to the [.filename]#Makefile#: [.programlisting] .... USES= feature[:arguments] .... For the complete list of values, please see crossref:uses[uses,Using `USES` Macros]. [WARNING] ==== `USES` cannot be assigned after inclusion of [.filename]#bsd.port.pre.mk#. ==== [[makefile-use-vars]] === `USE_*` Several variables exist to define common dependencies shared by many ports. Their use is optional, but helps to reduce the verbosity of the port [.filename]##Makefile##s. Each of them is styled as `USE_*`. These variables may be used only in the port [.filename]##Makefile##s and [.filename]#ports/Mk/bsd.*.mk#. They are not meant for user-settable options - use `PORT_OPTIONS` for that purpose. [NOTE] ==== It is _always_ incorrect to set any `USE_*` in [.filename]#/etc/make.conf#. For instance, setting [.programlisting] .... USE_GCC=X.Y .... (where X.Y is version number) would add a dependency on gccXY for every port, including `lang/gccXY` itself! ==== [[makefile-use-vars-table]] .`USE_*` [cols="1,1", frame="none", options="header"] |=== | Variable | Means |`USE_GCC` a| The port requires GCC (`gcc` or `{g-plus-plus}`) to build. Some ports need a specific, old GCC version, some require modern, recent versions. It is typically set to `yes` (means always use stable, modern GCC from ports per `GCC_DEFAULT` in [.filename]#Mk/bsd.default-versions.mk#). This is also the default value. The exact version can also be specified, with a value such as `10`. GCC from the base system is used when it satisfies the requested version, otherwise an appropriate compiler is built from ports, and `CC` and `CXX` are adjusted accordingly. The `:build` argument following the version specifier adds only a build time dependency to the port. For example: [example] ==== [.programlisting] .... USE_GCC=yes # port requires a current version of GCC USE_GCC=11:build # port requires GCC 11 at build time only .... ==== [NOTE] ==== `USE_GCC=any` is deprecated and should not be used in new ports ==== |=== Variables related to gmake and [.filename]#configure# are described in crossref:special[building,Building Mechanisms], while autoconf, automake and libtool are described in crossref:special[using-autotools,Using GNU Autotools]. Perl related variables are described in crossref:special[using-perl,Using Perl]. X11 variables are listed in crossref:special[using-x11,Using X11]. crossref:special[using-gnome,Using Gnome] deals with GNOME and crossref:special[using-kde,Using KDE] with KDE related variables. crossref:special[using-java,Using Java] documents Java variables, while crossref:special[using-php,Web Applications, Apache and PHP] contains information on Apache, PHP and PEAR modules. -Python is discussed in crossref:special[using-python,Using Python], while Ruby in crossref:special[using-ruby,Using Ruby]. +Python is discussed in crossref:special[using-python,Using Python], while Ruby in crossref:uses[uses-ruby,Ruby]. crossref:special[using-sdl,Using SDL] provides variables used for SDL applications and finally, crossref:special[using-xfce,Using Xfce] contains information on Xfce. [[makefile-version-dependency]] === Minimal Version of a Dependency A minimal version of a dependency can be specified in any `*_DEPENDS` except `LIB_DEPENDS` using this syntax: [.programlisting] .... p5-Spiffy>=0.26:devel/p5-Spiffy .... The first field contains a dependent package name, which must match the entry in the package database, a comparison sign, and a package version. The dependency is satisfied if p5-Spiffy-0.26 or newer is installed on the machine. [[makefile-note-on-dependencies]] === Notes on Dependencies As mentioned above, the default target to call when a dependency is required is `DEPENDS_TARGET`. It defaults to `install`. This is a user variable; it is never defined in a port's [.filename]#Makefile#. If the port needs a special way to handle a dependency, use the `:target` part of `*_DEPENDS` instead of redefining `DEPENDS_TARGET`. When running `make clean`, the port dependencies are automatically cleaned too. If this is not desirable, define `NOCLEANDEPENDS` in the environment. This may be particularly desirable if the port has something that takes a long time to rebuild in its dependency list, such as KDE, GNOME or Mozilla. To depend on another port unconditionally, use the variable `${NONEXISTENT}` as the first field of `BUILD_DEPENDS` or `RUN_DEPENDS`. Use this only when the source of the other port is needed. Compilation time can be saved by specifying the target too. For instance [.programlisting] .... BUILD_DEPENDS= ${NONEXISTENT}:graphics/jpeg:extract .... will always descend to the `jpeg` port and extract it. [[makefile-circular-dependencies]] === Circular Dependencies Are Fatal [IMPORTANT] ==== Do not introduce any circular dependencies into the ports tree! ==== The ports building technology does not tolerate circular dependencies. If one is introduced, someone, somewhere in the world, will have their FreeBSD installation broken almost immediately, with many others quickly to follow. These can really be hard to detect. If in doubt, before making that change, make sure to run: `cd /usr/ports; make index`. That process can be quite slow on older machines, but it may be able to save a large number of people, including yourself, a lot of grief in the process. [[makefile-automatic-dependencies]] === Problems Caused by Automatic Dependencies Dependencies must be declared either explicitly or by using the crossref:makefiles[makefile-options,OPTIONS framework]. Using other methods like automatic detection complicates indexing, which causes problems for port and package management. [[makefile-automatic-dependencies-bad]] .Wrong Declaration of an Optional Dependency [example] ==== [.programlisting] .... .include .if exists(${LOCALBASE}/bin/foo) LIB_DEPENDS= libbar.so:foo/bar .endif .... ==== The problem with trying to automatically add dependencies is that files and settings outside an individual port can change at any time. For example: an index is built, then a batch of ports are installed. But one of the ports installs the tested file. The index is now incorrect, because an installed port unexpectedly has a new dependency. The index may still be wrong even after rebuilding if other ports also determine their need for dependencies based on the existence of other files. [[makefile-automatic-dependencies-good]] .Correct Declaration of an Optional Dependency [example] ==== [.programlisting] .... OPTIONS_DEFINE= BAR BAR_DESC= Calling cellphones via bar BAR_LIB_DEPENDS= libbar.so:foo/bar .... ==== Testing option variables is the correct method. It will not cause inconsistencies in the index of a batch of ports, provided the options were defined prior to the index build. Simple scripts can then be used to automate the building, installation, and updating of these ports and their packages. [[makefile-masterdir]] == Slave Ports and `MASTERDIR` If the port needs to build slightly different versions of packages by having a variable (for instance, resolution, or paper size) take different values, create one subdirectory per package to make it easier for users to see what to do, but try to share as many files as possible between ports. Typically, by using variables cleverly, only a very short [.filename]#Makefile# is needed in all but one of the directories. In the sole [.filename]#Makefile#, use `MASTERDIR` to specify the directory where the rest of the files are. Also, use a variable as part of crossref:makefiles[porting-pkgname,`PKGNAMESUFFIX`] so the packages will have different names. This will be best demonstrated by an example. This is part of [.filename]#print/pkfonts300/Makefile#; [.programlisting] .... PORTNAME= pkfonts${RESOLUTION} PORTVERSION= 1.0 DISTFILES= pk${RESOLUTION}.tar.gz PLIST= ${PKGDIR}/pkg-plist.${RESOLUTION} .if !defined(RESOLUTION) RESOLUTION= 300 .else .if ${RESOLUTION} != 118 && ${RESOLUTION} != 240 && \ ${RESOLUTION} != 300 && ${RESOLUTION} != 360 && \ ${RESOLUTION} != 400 && ${RESOLUTION} != 600 .BEGIN: @${ECHO_MSG} "Error: invalid value for RESOLUTION: \"${RESOLUTION}\"" @${ECHO_MSG} "Possible values are: 118, 240, 300, 360, 400 and 600." @${FALSE} .endif .endif .... package:print/pkfonts300[] also has all the regular patches, package files, etc. Running `make` there, it will take the default value for the resolution (300) and build the port normally. As for other resolutions, this is the _entire_ [.filename]#print/pkfonts360/Makefile#: [.programlisting] .... RESOLUTION= 360 MASTERDIR= ${.CURDIR}/../pkfonts300 .include "${MASTERDIR}/Makefile" .... ([.filename]#print/pkfonts118/Makefile#, [.filename]#print/pkfonts600/Makefile#, and all the other are similar). `MASTERDIR` definition tells [.filename]#bsd.port.mk# that the regular set of subdirectories like `FILESDIR` and `SCRIPTDIR` are to be found under [.filename]#pkfonts300#. The `RESOLUTION=360` line will override the `RESOLUTION=300` line in [.filename]#pkfonts300/Makefile# and the port will be built with resolution set to 360. [[makefile-manpages]] == Man Pages If the port anchors its man tree somewhere other than `PREFIX`, use `MANDIRS` to specify those directories. Note that the files corresponding to manual pages must be placed in [.filename]#pkg-plist# along with the rest of the files. The purpose of `MANDIRS` is to enable automatic compression of manual pages, therefore the file names are suffixed with [.filename]#.gz#. [[makefile-info]] == Info Files If the package needs to install GNU info files, list them in `INFO` (without the trailing `.info`), one entry per document. These files are assumed to be installed to [.filename]#PREFIX/INFO_PATH#. Change `INFO_PATH` if the package uses a different location. However, this is not recommended. These entries contain just the path relative to [.filename]#PREFIX/INFO_PATH#. For example, package:lang/gcc34[] installs info files to [.filename]#PREFIX/INFO_PATH/gcc34#, and `INFO` will be something like this: [.programlisting] .... INFO= gcc34/cpp gcc34/cppinternals gcc34/g77 ... .... Appropriate installation/de-installation code will be automatically added to the temporary [.filename]#pkg-plist# before package registration. [[makefile-options]] == Makefile Options Many applications can be built with optional or differing configurations. Examples include choice of natural (human) language, GUI versus command-line, or type of database to support. Users may need a different configuration than the default, so the ports system provides hooks the port author can use to control which variant will be built. Supporting these options properly will make users happy, and effectively provide two or more ports for the price of one. [[makefile-options-options]] === `OPTIONS` [[makefile-options-background]] ==== Background `OPTIONS_*` give the user installing the port a dialog showing the available options, and then saves those options to [.filename]#${PORT_DBDIR}/${OPTIONS_NAME}/options#. The next time the port is built, the options are reused. `PORT_DBDIR` defaults to [.filename]#/var/db/ports#. `OPTIONS_NAME` is to the port origin with an underscore as the space separator, for example, for package:dns/bind99[] it will be `dns_bind99`. When the user runs `make config` (or runs `make build` for the first time), the framework checks for [.filename]#${PORT_DBDIR}/${OPTIONS_NAME}/options#. If that file does not exist, the values of `OPTIONS_*` are used, and a dialog box is displayed where the options can be enabled or disabled. Then [.filename]#options# is saved and the configured variables are used when building the port. If a new version of the port adds new `OPTIONS`, the dialog will be presented to the user with the saved values of old `OPTIONS` prefilled. `make showconfig` shows the saved configuration. Use `make rmconfig` to remove the saved configuration. [[makefile-options-syntax]] ==== Syntax `OPTIONS_DEFINE` contains a list of `OPTIONS` to be used. These are independent of each other and are not grouped: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT2 .... Once defined, `OPTIONS` are described (optional, but strongly recommended): [.programlisting] .... OPT1_DESC= Describe OPT1 OPT2_DESC= Describe OPT2 OPT3_DESC= Describe OPT3 OPT4_DESC= Describe OPT4 OPT5_DESC= Describe OPT5 OPT6_DESC= Describe OPT6 .... [.filename]#ports/Mk/bsd.options.desc.mk# has descriptions for many common `OPTIONS`. While often useful, override them if the description is insufficient for the port. [TIP] ==== When describing options, view it from the perspective of the user: "What functionality does it change?" and "Why would I want to enable this?" Do not just repeat the name. For example, describing the `NLS` option as "include NLS support" does not help the user, who can already see the option name but may not know what it means. Describing it as "Native Language Support via gettext utilities" is much more helpful. ==== [IMPORTANT] ==== Option names are always in all uppercase. They cannot use mixed case or lowercase. ==== `OPTIONS` can be grouped as radio choices, where only one choice from each group is allowed: [.programlisting] .... OPTIONS_SINGLE= SG1 OPTIONS_SINGLE_SG1= OPT3 OPT4 .... [WARNING] ==== There _must_ be one of each `OPTIONS_SINGLE` group selected at all times for the options to be valid. One option of each group _must_ be added to `OPTIONS_DEFAULT`. ==== `OPTIONS` can be grouped as radio choices, where none or only one choice from each group is allowed: [.programlisting] .... OPTIONS_RADIO= RG1 OPTIONS_RADIO_RG1= OPT7 OPT8 .... `OPTIONS` can also be grouped as "multiple-choice" lists, where _at least one_ option must be enabled: [.programlisting] .... OPTIONS_MULTI= MG1 OPTIONS_MULTI_MG1= OPT5 OPT6 .... `OPTIONS` can also be grouped as "multiple-choice" lists, where none or any option can be enabled: [.programlisting] .... OPTIONS_GROUP= GG1 OPTIONS_GROUP_GG1= OPT9 OPT10 .... `OPTIONS` are unset by default, unless they are listed in `OPTIONS_DEFAULT`: [.programlisting] .... OPTIONS_DEFAULT= OPT1 OPT3 OPT6 .... `OPTIONS` definitions must appear before the inclusion of [.filename]#bsd.port.options.mk#. `PORT_OPTIONS` values can only be tested after the inclusion of [.filename]#bsd.port.options.mk#. Inclusion of [.filename]#bsd.port.pre.mk# can be used instead, too, and is still widely used in ports written before the introduction of [.filename]#bsd.port.options.mk#. But be aware that some variables will not work as expected after the inclusion of [.filename]#bsd.port.pre.mk#, typically some `USE_*` flags. [[ports-options-simple-use]] .Simple Use of `OPTIONS` [example] ==== [.programlisting] .... OPTIONS_DEFINE= FOO BAR OPTIONS_DEFAULT=FOO FOO_DESC= Option foo support BAR_DESC= Feature bar support # Will add --with-foo / --without-foo FOO_CONFIGURE_WITH= foo BAR_RUN_DEPENDS= bar:bar/bar .include .... ==== [[ports-options-check-unset]] .Check for Unset Port `OPTIONS` [example] ==== [.programlisting] .... .if ! ${PORT_OPTIONS:MEXAMPLES} CONFIGURE_ARGS+=--without-examples .endif .... The form shown above is discouraged. The preferred method is using a configure knob to really enable and disable the feature to match the option: [.programlisting] .... # Will add --with-examples / --without-examples EXAMPLES_CONFIGURE_WITH= examples .... ==== [[ports-options-practical-use]] .Practical Use of `OPTIONS` [example] ==== [.programlisting] .... OPTIONS_DEFINE= EXAMPLES OPTIONS_DEFAULT= PGSQL LDAP SSL OPTIONS_SINGLE= BACKEND OPTIONS_SINGLE_BACKEND= MYSQL PGSQL BDB OPTIONS_MULTI= AUTH OPTIONS_MULTI_AUTH= LDAP PAM SSL EXAMPLES_DESC= Install extra examples MYSQL_DESC= Use MySQL as backend PGSQL_DESC= Use PostgreSQL as backend BDB_DESC= Use Berkeley DB as backend LDAP_DESC= Build with LDAP authentication support PAM_DESC= Build with PAM support SSL_DESC= Build with OpenSSL support # Will add USE_PGSQL=yes PGSQL_USE= pgsql=yes # Will add --enable-postgres / --disable-postgres PGSQL_CONFIGURE_ENABLE= postgres ICU_LIB_DEPENDS= libicuuc.so:devel/icu # Will add --with-examples / --without-examples EXAMPLES_CONFIGURE_WITH= examples # Check other OPTIONS .include .... ==== [[makefile-options-default]] ==== Default Options These options are always on by default. * `DOCS` - build and install documentation. * `NLS` - Native Language Support. * `EXAMPLES` - build and install examples. * `IPV6` - IPv6 protocol support. [NOTE] ==== There is no need to add these to `OPTIONS_DEFAULT`. To have them active, and show up in the options selection dialog, however, they must be added to `OPTIONS_DEFINE`. ==== [[makefile-options-auto-activation]] === Feature Auto-Activation When using a GNU configure script, keep an eye on which optional features are activated by auto-detection. Explicitly disable optional features that are not needed by adding `--without-xxx` or `--disable-xxx` in `CONFIGURE_ARGS`. [[makefile-options-auto-activation-bad]] .Wrong Handling of an Option [example] ==== [.programlisting] .... .if ${PORT_OPTIONS:MFOO} LIB_DEPENDS+= libfoo.so:devel/foo CONFIGURE_ARGS+= --enable-foo .endif .... ==== In the example above, imagine a library libfoo is installed on the system. The user does not want this application to use libfoo, so he toggled the option off in the `make config` dialog. But the application's configure script detects the library present in the system and includes its support in the resulting executable. Now when the user decides to remove libfoo from the system, the ports system does not protest (no dependency on libfoo was recorded) but the application breaks. [[makefile-options-auto-activation-good]] .Correct Handling of an Option [example] ==== [.programlisting] .... FOO_LIB_DEPENDS= libfoo.so:devel/foo # Will add --enable-foo / --disable-foo FOO_CONFIGURE_ENABLE= foo .... ==== [NOTE] ==== Under some circumstances, the shorthand conditional syntax can cause problems with complex constructs. The errors are usually `Malformed conditional`, an alternative syntax can be used. [.programlisting] .... .if !empty(VARIABLE:MVALUE) .... as an alternative to [.programlisting] .... .if ${VARIABLE:MVALUE} .... ==== [[options-helpers]] === Options Helpers There are some macros to help simplify conditional values which differ based on the options set. For easier access, a comprehensive list is provided: `PLIST_SUB`, `SUB_LIST`:: For automatic `%%_OPT_%%` and `%%NO__OPT__%%` generation, see crossref:makefiles[options_sub, `OPTIONS_SUB`]. + For more complex usage, see crossref:makefiles[options-variables, Generic Variables Replacement, `OPT_VARIABLE` and `OPT_VARIABLE_OFF`]. `CONFIGURE_ARGS`:: For `--enable-_x_` and `--disable-_x_`, see crossref:makefiles[options-configure_enable, `OPT_CONFIGURE_ENABLE`]. + For `--with-_x_` and `--without-_x_`, see crossref:makefiles[options-configure_with, `OPT_CONFIGURE_WITH`]. + For all other cases, see crossref:makefiles[options-configure_on, `OPT_CONFIGURE_ON` and `OPT_CONFIGURE_OFF`]. `CMAKE_ARGS`:: For arguments that are booleans (`on`, `off`, `true`, `false`, `0`, `1`) see crossref:makefiles[options-cmake_bool, `OPT_CMAKE_BOOL` and `OPT_CMAKE_BOOL_OFF`]. + For all other cases, see crossref:makefiles[options-cmake_on, `OPT_CMAKE_ON` and `OPT_CMAKE_OFF`]. `MESON_ARGS`:: For arguments that take `true` or `false`, see crossref:makefiles[options-meson_true, `OPT_MESON_TRUE` and `OPT_MESON_FALSE`]. + For arguments that take `yes` or `no`, use crossref:makefiles[options-meson_yes, `OPT_MESON_YES` and `OPT_MESON_NO`]. + For arguments that take `enabled` or `disabled`, see crossref:makefiles[options-meson_enabled, `OPT_MESON_ENABLED` and `OPT_MESON_DISABLED`]. + For all other cases, use crossref:makefiles[options-meson_on, `OPT_MESON_ON` and `OPT_MESON_OFF`]. `QMAKE_ARGS`:: See crossref:makefiles[options-qmake_on, `OPT_QMAKE_ON` and `OPT_QMAKE_OFF`]. `USE_*`:: See crossref:makefiles[options-use, `OPT_USE` and `OPT_USE_OFF`]. `*_DEPENDS`:: See crossref:makefiles[options-dependencies, Dependencies, `OPT_DEPTYPE` and `OPT_DEPTYPE_OFF`]. `*` (Any variable):: The most used variables have direct helpers, see crossref:makefiles[options-variables, Generic Variables Replacement, `OPT_VARIABLE` and `OPT_VARIABLE_OFF`]. + For any variable without a specific helper, see crossref:makefiles[options-vars, `OPT_VARS` and `OPT_VARS_OFF`]. Options dependencies:: When an option need another option to work, see crossref:makefiles[options-implies, `OPT_IMPLIES`]. Options conflicts:: When an option cannot work if another is also enabled, see crossref:makefiles[options-prevents, `OPT_PREVENTS` and `OPT_PREVENTS_MSG`]. Build targets:: When an option need some extra processing, see crossref:makefiles[options-targets, Additional Build Targets, `_target_-_OPT_-on` and `_target_-_OPT_-off`]. [[options_sub]] ==== `OPTIONS_SUB` If `OPTIONS_SUB` is set to `yes` then each of the options added to `OPTIONS_DEFINE` will be added to `PLIST_SUB` and `SUB_LIST`, for example: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPTIONS_SUB= yes .... is equivalent to: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} PLIST_SUB+= OPT1="" NO_OPT1="@comment " SUB_LIST+= OPT1="" NO_OPT1="@comment " .else PLIST_SUB+= OPT1="@comment " NO_OPT1="" SUB_LIST+= OPT1="@comment " NO_OPT1="" .endif .... [NOTE] ==== The value of `OPTIONS_SUB` is ignored. Setting it to any value will add `PLIST_SUB` and `SUB_LIST` entries for _all_ options. ==== [[options-use]] ==== `OPT_USE` and `OPT_USE_OFF` When option _OPT_ is selected, for each `_key=value_` pair in ``OPT_USE``, _value_ is appended to the corresponding `USE_KEY`. If _value_ has spaces in it, replace them with commas and they will be changed back to spaces during processing. `OPT_USE_OFF` works the same way, but when `OPT` is _not_ selected. For example: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_USES= xorg OPT1_USE= mysql=yes xorg=x11,xextproto,xext,xrandr OPT1_USE_OFF= openssl=yes .... is equivalent to: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} USE_MYSQL= yes USES+= xorg USE_XORG= x11 xextproto xext xrandr .else USE_OPENSSL= yes .endif .... [[options-configure-helpers]] ==== `CONFIGURE_ARGS` Helpers [[options-configure_enable]] ===== `OPT_CONFIGURE_ENABLE` When option _OPT_ is selected, for each _entry_ in `OPT_CONFIGURE_ENABLE` then `--enable-_entry_` is appended to `CONFIGURE_ARGS`. When option _OPT_ is _not_ selected, `--disable-_entry_` is appended to `CONFIGURE_ARGS`. An optional argument can be specified with an `=` symbol. This argument is only appended to the `--enable-_entry_` configure option. For example: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT2 OPT1_CONFIGURE_ENABLE= test1 test2 OPT2_CONFIGURE_ENABLE= test2=exhaustive .... is equivalent to: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} CONFIGURE_ARGS+= --enable-test1 --enable-test2 .else CONFIGURE_ARGS+= --disable-test1 --disable-test2 .endif .if ${PORT_OPTIONS:MOPT2} CONFIGURE_ARGS+= --enable-test2=exhaustive .else CONFIGURE_ARGS+= --disable-test2 .endif .... [[options-configure_with]] ===== `OPT_CONFIGURE_WITH` When option _OPT_ is selected, for each _entry_ in `_OPT_CONFIGURE_WITH` then `--with-_entry_` is appended to `CONFIGURE_ARGS`. When option _OPT_ is _not_ selected, `--without-_entry_` is appended to `CONFIGURE_ARGS`. An optional argument can be specified with an `=` symbol. This argument is only appended to the `--with-_entry_` configure option. For example: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT2 OPT1_CONFIGURE_WITH= test1 OPT2_CONFIGURE_WITH= test2=exhaustive .... is equivalent to: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT2 .include .if ${PORT_OPTIONS:MOPT1} CONFIGURE_ARGS+= --with-test1 .else CONFIGURE_ARGS+= --without-test1 .endif .if ${PORT_OPTIONS:MOPT2} CONFIGURE_ARGS+= --with-test2=exhaustive .else CONFIGURE_ARGS+= --without-test2 .endif .... [[options-configure_on]] ===== `OPT_CONFIGURE_ON` and `OPT_CONFIGURE_OFF` When option _OPT_ is selected, the value of `OPT_CONFIGURE_ON`, if defined, is appended to `CONFIGURE_ARGS`. `OPT_CONFIGURE_OFF` works the same way, but when `OPT` is _not_ selected. For example: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_CONFIGURE_ON= --add-test OPT1_CONFIGURE_OFF= --no-test .... is equivalent to: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} CONFIGURE_ARGS+= --add-test .else CONFIGURE_ARGS+= --no-test .endif .... [TIP] ==== Most of the time, the helpers in crossref:makefiles[options-configure_enable, `OPT_CONFIGURE_ENABLE`] and crossref:makefiles[options-configure_with, `OPT_CONFIGURE_WITH`] provide a shorter and more comprehensive functionality. ==== [[options-cmake-helpers]] ==== `CMAKE_ARGS` Helpers [[options-cmake_on]] ===== `OPT_CMAKE_ON` and `OPT_CMAKE_OFF` When option _OPT_ is selected, the value of `OPT_CMAKE_ON`, if defined, is appended to `CMAKE_ARGS`. `OPT_CMAKE_OFF` works the same way, but when `OPT` is _not_ selected. For example: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_CMAKE_ON= -DTEST:BOOL=true -DDEBUG:BOOL=true OPT1_CMAKE_OFF= -DOPTIMIZE:BOOL=true .... is equivalent to: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} CMAKE_ARGS+= -DTEST:BOOL=true -DDEBUG:BOOL=true .else CMAKE_ARGS+= -DOPTIMIZE:BOOL=true .endif .... [TIP] ==== See crossref:makefiles[options-cmake_bool, `OPT_CMAKE_BOOL` and `OPT_CMAKE_BOOL_OFF`] for a shorter helper when the value is boolean. ==== [[options-cmake_bool]] ===== `OPT_CMAKE_BOOL` and `OPT_CMAKE_BOOL_OFF` When option _OPT_ is selected, for each _entry_ in `OPT_CMAKE_BOOL` then `-D_entry_:BOOL=true` is appended to `CMAKE_ARGS`. When option _OPT_ is _not_ selected, `-D_entry_:BOOL=false` is appended to `CONFIGURE_ARGS`. `OPT_CMAKE_BOOL_OFF` is the opposite, `-D_entry_:BOOL=false` is appended to `CMAKE_ARGS` when the option is selected, and `-D_entry_:BOOL=true` when the option is _not_ selected. For example: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_CMAKE_BOOL= TEST DEBUG OPT1_CMAKE_BOOL_OFF= OPTIMIZE .... is equivalent to: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} CMAKE_ARGS+= -DTEST:BOOL=true -DDEBUG:BOOL=true \ -DOPTIMIZE:BOOL=false .else CMAKE_ARGS+= -DTEST:BOOL=false -DDEBUG:BOOL=false \ -DOPTIMIZE:BOOL=true .endif .... [[options-meson-helpers]] ==== `MESON_ARGS` Helpers [[options-meson_on]] ===== `OPT_MESON_ON` and `OPT_MESON_OFF` When option _OPT_ is selected, the value of `OPT_MESON_ON`, if defined, is appended to `MESON_ARGS`. `OPT_MESON_OFF` works the same way, but when `OPT` is _not_ selected. For example: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_MESON_ON= -Dopt=1 OPT1_MESON_OFF= -Dopt=2 .... is equivalent to: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} MESON_ARGS+= -Dopt=1 .else MESON_ARGS+= -Dopt=2 .endif .... [[options-meson_true]] ===== `OPT_MESON_TRUE` and `OPT_MESON_FALSE` When option _OPT_ is selected, for each _entry_ in `OPT_MESON_TRUE` then `-D_entry_=true` is appended to `MESON_ARGS`. When option _OPT_ is _not_ selected, `-D_entry_=false` is appended to `MESON_ARGS`. `OPT_MESON_FALSE` is the opposite, `-D_entry_=false` is appended to `MESON_ARGS` when the option is selected, and `-D_entry_=true` when the option is _not_ selected. For example: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_MESON_TRUE= test debug OPT1_MESON_FALSE= optimize .... is equivalent to: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} MESON_ARGS+= -Dtest=true -Ddebug=true \ -Doptimize=false .else MESON_ARGS+= -Dtest=false -Ddebug=false \ -Doptimize=true .endif .... [[options-meson_yes]] ===== `OPT_MESON_YES` and `OPT_MESON_NO` When option _OPT_ is selected, for each _entry_ in `OPT_MESON_YES` then `-D_entry_=yes` is appended to `MESON_ARGS`. When option _OPT_ is _not_ selected, `-D_entry_=no` is appended to `MESON_ARGS`. `OPT_MESON_NO` is the opposite, `-D_entry_=no` is appended to `MESON_ARGS` when the option is selected, and `-D_entry_=yes` when the option is _not_ selected. For example: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_MESON_YES= test debug OPT1_MESON_NO= optimize .... is equivalent to: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} MESON_ARGS+= -Dtest=yes -Ddebug=yes \ -Doptimize=no .else MESON_ARGS+= -Dtest=no -Ddebug=no \ -Doptimize=yes .endif .... [[options-meson_enabled]] ===== `OPT_MESON_ENABLED` and `OPT_MESON_DISABLED` When option _OPT_ is selected, for each _entry_ in `OPT_MESON_ENABLED` then `-D_entry_=enabled` is appended to `MESON_ARGS`. When option _OPT_ is _not_ selected, `-D_entry_=disabled` is appended to `MESON_ARGS`. `OPT_MESON_DISABLED` is the opposite, `-D_entry_=disabled` is appended to `MESON_ARGS` when the option is selected, and `-D_entry_=enabled` when the option is _not_ selected. For example: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_MESON_ENABLED= test OPT1_MESON_DISABLED= debug .... is equivalent to: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} MESON_ARGS+= -Dtest=enabled -Ddebug=disabled .else MESON_ARGS+= -Dtest=disabled -Ddebug=enabled .endif .... [[options-qmake_on]] ==== `OPT_QMAKE_ON` and `OPT_QMAKE_OFF` When option _OPT_ is selected, the value of `OPT_QMAKE_ON`, if defined, is appended to `QMAKE_ARGS`. `OPT_QMAKE_OFF` works the same way, but when `OPT` is _not_ selected. For example: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_QMAKE_ON= -DTEST:BOOL=true OPT1_QMAKE_OFF= -DPRODUCTION:BOOL=true .... is equivalent to: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} QMAKE_ARGS+= -DTEST:BOOL=true .else QMAKE_ARGS+= -DPRODUCTION:BOOL=true .endif .... [[options-implies]] ==== `OPT_IMPLIES` Provides a way to add dependencies between options. When _OPT_ is selected, all the options listed in this variable will be selected too. Using the crossref:makefiles[options-configure_enable,`OPT_CONFIGURE_ENABLE`] described earlier to illustrate: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT2 OPT1_IMPLIES= OPT2 OPT1_CONFIGURE_ENABLE= opt1 OPT2_CONFIGURE_ENABLE= opt2 .... Is equivalent to: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT2 .include .if ${PORT_OPTIONS:MOPT1} CONFIGURE_ARGS+= --enable-opt1 .else CONFIGURE_ARGS+= --disable-opt1 .endif .if ${PORT_OPTIONS:MOPT2} || ${PORT_OPTIONS:MOPT1} CONFIGURE_ARGS+= --enable-opt2 .else CONFIGURE_ARGS+= --disable-opt2 .endif .... [[options-implies-ex1]] .Simple Use of `OPT_IMPLIES` [example] ==== This port has a `X11` option, and a `GNOME` option that needs the `X11` option to be selected to build. [.programlisting] .... OPTIONS_DEFINE= X11 GNOME OPTIONS_DEFAULT= X11 X11_USES= xorg X11_USE= xorg=xi,xextproto GNOME_USE= gnome=gtk30 GNOME_IMPLIES= X11 .... ==== [[options-prevents]] ==== `OPT_PREVENTS` and `OPT_PREVENTS_MSG` Provides a way to add conflicts between options. When _OPT_ is selected, all the options listed in `OPT_PREVENTS` must be un-selected. If `OPT_PREVENTS_MSG` is set and a conflict is triggered, its content will be shown explaining why they conflict. For example: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT2 OPT1_PREVENTS= OPT2 OPT1_PREVENTS_MSG= OPT1 and OPT2 enable conflicting options .... Is roughly equivalent to: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT2 .include .if ${PORT_OPTIONS:MOPT2} && ${PORT_OPTIONS:MOPT1} BROKEN= Option OPT1 conflicts with OPT2 (select only one) .endif .... The only difference is that the first one will write an error after running `make config`, suggesting changing the selected options. [[options-prevents-ex1]] .Simple Use of `OPT_PREVENTS` [example] ==== This port has `X509` and `SCTP` options. Both options add patches, but the patches conflict with each other, so they cannot be selected at the same time. [.programlisting] .... OPTIONS_DEFINE= X509 SCTP SCTP_PATCHFILES= ${PORTNAME}-6.8p1-sctp-2573.patch.gz:-p1 SCTP_CONFIGURE_WITH= sctp X509_PATCH_SITES= http://www.roumenpetrov.info/openssh/x509/:x509 X509_PATCHFILES= ${PORTNAME}-7.0p1+x509-8.5.diff.gz:-p1:x509 X509_PREVENTS= SCTP X509_PREVENTS_MSG= X509 and SCTP patches conflict .... ==== [[options-vars]] ==== `OPT_VARS` and `OPT_VARS_OFF` Provides a generic way to set and append to variables. [WARNING] ==== Before using `OPT_VARS` and `OPT_VARS_OFF`, see if there is already a more specific helper available in crossref:makefiles[options-variables, Generic Variables Replacement, `OPT_VARIABLE` and `OPT_VARIABLE_OFF`]. ==== When option _OPT_ is selected, and `OPT_VARS` defined, `_key_=_value_` and `_key_+=_value_` pairs are evaluated from `OPT_VARS`. An `=` cause the existing value of `KEY` to be overwritten, an `+=` appends to the value. `OPT_VARS_OFF` works the same way, but when `OPT` is _not_ selected. [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT2 OPT3 OPT1_VARS= also_build+=bin1 OPT2_VARS= also_build+=bin2 OPT3_VARS= bin3_build=yes OPT3_VARS_OFF= bin3_build=no MAKE_ARGS= ALSO_BUILD="${ALSO_BUILD}" BIN3_BUILD="${BIN3_BUILD}" .... is equivalent to: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT2 MAKE_ARGS= ALSO_BUILD="${ALSO_BUILD}" BIN3_BUILD="${BIN3_BUILD}" .include .if ${PORT_OPTIONS:MOPT1} ALSO_BUILD+= bin1 .endif .if ${PORT_OPTIONS:MOPT2} ALSO_BUILD+= bin2 .endif .if ${PORT_OPTIONS:MOPT2} BIN3_BUILD= yes .else BIN3_BUILD= no .endif .... [IMPORTANT] ==== Values containing whitespace must be enclosed in quotes: [.programlisting] .... OPT_VARS= foo="bar baz" .... This is due to the way man:make[1] variable expansion deals with whitespace. When `OPT_VARS= foo=bar baz` is expanded, the variable ends up containing two strings, `foo=bar` and `baz`. But the submitter probably intended there to be only one string, `foo=bar baz`. Quoting the value prevents whitespace from being used as a delimiter. Also, _do not_ add extra spaces after the `_var_=` sign and before the value, it would also be split into two strings. _This will not work_: [.programlisting] .... OPT_VARS= foo= bar .... ==== [[options-dependencies]] ==== Dependencies, `OPT_DEPTYPE` and `OPT_DEPTYPE_OFF` For any of these dependency types: * `PKG_DEPENDS` * `EXTRACT_DEPENDS` * `PATCH_DEPENDS` * `FETCH_DEPENDS` * `BUILD_DEPENDS` * `LIB_DEPENDS` * `RUN_DEPENDS` When option _OPT_ is selected, the value of `OPT_DEPTYPE`, if defined, is appended to `DEPTYPE`. `OPT_DEPTYPE_OFF` works the same, but when `OPT` is _not_ selected. For example: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_LIB_DEPENDS= liba.so:devel/a OPT1_LIB_DEPENDS_OFF= libb.so:devel/b .... is equivalent to: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} LIB_DEPENDS+= liba.so:devel/a .else LIB_DEPENDS+= libb.so:devel/b .endif .... [[options-variables]] ==== Generic Variables Replacement, `OPT_VARIABLE` and `OPT_VARIABLE_OFF` For any of these variables: * `ALL_TARGET` * `BINARY_ALIAS` * `BROKEN` * `CATEGORIES` * `CFLAGS` * `CONFIGURE_ENV` * `CONFLICTS` * `CONFLICTS_BUILD` * `CONFLICTS_INSTALL` * `CPPFLAGS` * `CXXFLAGS` * `DESKTOP_ENTRIES` * `DISTFILES` * `EXTRACT_ONLY` * `EXTRA_PATCHES` * `GH_ACCOUNT` * `GH_PROJECT` * `GH_SUBDIR` * `GH_TAGNAME` * `GH_TUPLE` * `GL_ACCOUNT` * `GL_COMMIT` * `GL_PROJECT` * `GL_SITE` * `GL_SUBDIR` * `GL_TUPLE` * `IGNORE` * `INFO` * `INSTALL_TARGET` * `LDFLAGS` * `LIBS` * `MAKE_ARGS` * `MAKE_ENV` * `MASTER_SITES` * `PATCHFILES` * `PATCH_SITES` * `PLIST_DIRS` * `PLIST_FILES` * `PLIST_SUB` * `PORTDOCS` * `PORTEXAMPLES` * `SUB_FILES` * `SUB_LIST` * `TEST_TARGET` * `USES` When option _OPT_ is selected, the value of `OPT_ABOVEVARIABLE`, if defined, is appended to `_ABOVEVARIABLE_`. `OPT_ABOVEVARIABLE_OFF` works the same way, but when `OPT` is _not_ selected. For example: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_USES= gmake OPT1_CFLAGS_OFF= -DTEST .... is equivalent to: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} USES+= gmake .else CFLAGS+= -DTEST .endif .... [NOTE] ==== Some variables are not in this list, in particular `PKGNAMEPREFIX` and `PKGNAMESUFFIX`. This is intentional. A port _must not_ change its name when its option set changes. ==== [WARNING] ==== Some of these variables, at least `ALL_TARGET`, `DISTFILES` and `INSTALL_TARGET`, have their default values set _after_ the options are processed. With these lines in the [.filename]#Makefile#: [.programlisting] .... ALL_TARGET= all DOCS_ALL_TARGET= doc .... If the `DOCS` option is enabled, `ALL_TARGET` will have a final value of `all doc`; if the option is disabled, it would have a value of `all`. With only the options helper line in the [.filename]#Makefile#: [.programlisting] .... DOCS_ALL_TARGET= doc .... If the `DOCS` option is enabled, `ALL_TARGET` will have a final value of `doc`; if the option is disabled, it would have a value of `all`. ==== [[options-targets]] ==== Additional Build Targets, `_target_-_OPT_-on` and `_target_-_OPT_-off` These [.filename]#Makefile# targets can accept optional extra build targets: * `pre-fetch` * `do-fetch` * `post-fetch` * `pre-extract` * `do-extract` * `post-extract` * `pre-patch` * `do-patch` * `post-patch` * `pre-configure` * `do-configure` * `post-configure` * `pre-build` * `do-build` * `post-build` * `pre-install` * `do-install` * `post-install` * `post-stage` * `pre-package` * `do-package` * `post-package` When option _OPT_ is selected, the target `_TARGET_-_OPT_-on`, if defined, is executed after `_TARGET_`. `_TARGET_-_OPT_-off` works the same way, but when `OPT` is _not_ selected. For example: [.programlisting] .... OPTIONS_DEFINE= OPT1 post-patch-OPT1-on: @${REINPLACE_CMD} -e '/opt1/s|/usr/bin/|${EXAMPLESDIR}/|' ${WRKSRC}/Makefile post-patch-OPT1-off: @${REINPLACE_CMD} -e '/opt1/s|/usr/bin/|${PREFIX}/bin/|' ${WRKSRC}/Makefile .... is equivalent to: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include post-patch: .if ${PORT_OPTIONS:MOPT1} @${REINPLACE_CMD} -e '/opt1/s|/usr/bin/|${EXAMPLESDIR}/|' ${WRKSRC}/Makefile .else @${REINPLACE_CMD} -e '/opt1/s|/usr/bin/|${PREFIX}/bin/|' ${WRKSRC}/Makefile .endif .... [[makefile-wrkdir]] == Specifying the Working Directory Each port is extracted into a working directory, which must be writable. The ports system defaults to having `DISTFILES` unpack in to a directory called `${DISTNAME}`. In other words, if the [.filename]#Makefile# has: [.programlisting] .... PORTNAME= foo DISTVERSION= 1.0 .... then the port's distribution files contain a top-level directory, [.filename]#foo-1.0#, and the rest of the files are located under that directory. A number of variables can be overridden if that is not the case. [[makefile-wrksrc]] === `WRKSRC` The variable lists the name of the directory that is created when the application's distfiles are extracted. If our previous example extracted into a directory called [.filename]#foo# (and not [.filename]#foo-1.0#) write: [.programlisting] .... WRKSRC= ${WRKDIR}/foo .... or possibly [.programlisting] .... WRKSRC= ${WRKDIR}/${PORTNAME} .... [[makefile-wrksrc_subdir]] === `WRKSRC_SUBDIR` If the source files needed for the port are in a subdirectory of the extracted distribution file, set `WRKSRC_SUBDIR` to that directory. [.programlisting] .... WRKSRC_SUBDIR= src .... [[makefile-no_wrksubdir]] === `NO_WRKSUBDIR` If the port does not extract in to a subdirectory at all, then set `NO_WRKSUBDIR` to indicate that. [.programlisting] .... NO_WRKSUBDIR= yes .... [NOTE] ==== Because `WRKDIR` is the only directory that is supposed to be writable during the build, and is used to store many files recording the status of the build, the port's extraction will be forced into a subdirectory. ==== [[conflicts]] == Conflict Handling There are three different variables to register a conflict between packages and ports: `CONFLICTS`, `CONFLICTS_INSTALL` and `CONFLICTS_BUILD`. [NOTE] ==== The conflict variables automatically set the variable `IGNORE`, which is more fully documented in crossref:porting-dads[dads-noinstall,Marking a Port Not Installable with `BROKEN`, `FORBIDDEN`, or `IGNORE`]. ==== When removing one of several conflicting ports, it is advisable to retain `CONFLICTS` in those other ports for a few months to cater for users who only update once in a while. [[conclicts-conflicts_install]] `CONFLICTS_INSTALL`:: If the package cannot coexist with other packages (because of file conflicts, runtime incompatibilities, etc.). `CONFLICTS_INSTALL` check is done after the build stage and prior to the install stage. [[conclicts-conflicts_build]] `CONFLICTS_BUILD`:: If the port cannot be built when other specific ports are already installed. Build conflicts are not recorded in the resulting package. [[conclicts-conflicts]] `CONFLICTS`:: If the port cannot be built if a certain port is already installed and the resulting package cannot coexist with the other package. `CONFLICTS` check is done prior to the build stage and prior to the install stage. Each space-separated item in the `CONFLICTS*` variable values is matched against packages except the one being built, using shell globbing rules. This allows listing all flavors of a port in a conflict list instead of having to take pains to exclude the flavor being built from that list. For example, if git-lite is installed, `CONFLICTS_INSTALL=git git-lite` would allow to perform: [source,shell] .... % make -C devel/git FLAVOR=lite all deinstall install .... But the following command would report a conflict, since the package base name installed is `git-lite`, while `git` would be built, but cannot be installed in addition to `git-lite`: [source,shell] .... % make -C devel/git FLAVOR=default all deinstall install .... Without that feature, the Makefile would need one `_flavor__CONFLICTS_INSTALL` for each flavor, listing every other flavor. The most common content of one of these variable is the package base of another port. The package base is the package name without the appended version, it can be obtained by running `make -V PKGBASE`. [[conflicts-ex1]] .Basic usage of `CONFLICTS*` [example] ==== package:dns/bind99[] cannot be installed if package:dns/bind910[] is present because they install same files. First gather the package base to use: [source,shell] .... % make -C dns/bind99 -V PKGBASE bind99 % make -C dns/bind910 -V PKGBASE bind910 .... Then add to the [.filename]#Makefile# of package:dns/bind99[]: [.programlisting] .... CONFLICTS_INSTALL= bind910 .... And add to the [.filename]#Makefile# of package:dns/bind910[]: [.programlisting] .... CONFLICTS_INSTALL= bind99 .... ==== Sometimes, only certain versions of another port are incompatible. When this is the case, use the full package name including the version. If necessary, use shell globs like `*` and `?` so that all necessary versions are matched. [[conflicts-ex2]] .Using `CONFLICTS*` With Globs. [example] ==== From versions from 2.0 and up-to 2.4.1_2, package:deskutils/gnotime[] used to install a bundled version of package:databases/qof[]. To reflect this past, the [.filename]#Makefile# of package:databases/qof[] contains: [.programlisting] .... CONFLICTS_INSTALL= gnotime-2.[0-3]* \ gnotime-2.4.0* gnotime-2.4.1 \ gnotime-2.4.1_[12] .... The first entry match versions `2.0` through `2.3`, the second all the revisions of `2.4.0`, the third the exact `2.4.1` version, and the last the first and second revisions of the `2.4.1` version. package:deskutils/gnotime[] does not have any conflicts line because its current version does not conflict with anything else. ==== The variable `DISABLE_CONFLICTS` may be temporarily set when making targets that are not affected by conflicts. The variable is not to be set in port Makefiles. [source,shell] .... % make -DDISABLE_CONFLICTS patch .... [[install]] == Installing Files [IMPORTANT] ==== The `install` phase is very important to the end user because it adds files to their system. All the additional commands run in the port [.filename]#Makefile#'s `*-install` targets should be echoed to the screen. _Do not_ silence these commands with `@` or `.SILENT`. ==== [[install-macros]] === `INSTALL_*` Macros Use the macros provided in [.filename]#bsd.port.mk# to ensure correct modes of files in the port's `*-install` targets. Set ownership directly in [.filename]#pkg-plist# with the corresponding entries, such as `@(_owner_,_group_,)`, `@owner _owner_`, and `@group _group_`. These operators work until overridden, or until the end of [.filename]#pkg-plist#, so remember to reset them after they are no longer needed. The default ownership is `root:wheel`. See crossref:plist[plist-keywords-base,Base Keywords] for more information. * `INSTALL_PROGRAM` is a command to install binary executables. * `INSTALL_SCRIPT` is a command to install executable scripts. * `INSTALL_LIB` is a command to install shared libraries (but not static libraries). * `INSTALL_KLD` is a command to install kernel loadable modules. Some architectures do not like having the modules stripped, so use this command instead of `INSTALL_PROGRAM`. * `INSTALL_DATA` is a command to install sharable data, including static libraries. * `INSTALL_MAN` is a command to install manpages and other documentation (it does not compress anything). These variables are set to the man:install[1] command with the appropriate flags for each situation. [IMPORTANT] ==== Do not use `INSTALL_LIB` to install static libraries, because stripping them renders them useless. Use `INSTALL_DATA` instead. ==== [[install-strip]] === Stripping Binaries and Shared Libraries Installed binaries should be stripped. Do not strip binaries manually unless absolutely required. The `INSTALL_PROGRAM` macro installs and strips a binary at the same time. The `INSTALL_LIB` macro does the same thing to shared libraries. When a file must be stripped, but neither `INSTALL_PROGRAM` nor `INSTALL_LIB` macros are desirable, `${STRIP_CMD}` strips the program or shared library. This is typically done within the `post-install` target. For example: [.programlisting] .... post-install: ${STRIP_CMD} ${STAGEDIR}${PREFIX}/bin/xdl .... When multiple files need to be stripped: [.programlisting] .... post-install: .for l in geometry media body track world ${STRIP_CMD} ${STAGEDIR}${PREFIX}/lib/lib${PORTNAME}-${l}.so.0 .endfor .... Use man:file[1] on a file to determine if it has been stripped. Binaries are reported by man:file[1] as `stripped`, or `not stripped`. Additionally, man:strip[1] will detect programs that have already been stripped and exit cleanly. [IMPORTANT] ==== When `WITH_DEBUG` is defined, elf files _must not_ be stripped. The variables (`STRIP_CMD`, `INSTALL_PROGRAM`, `INSTALL_LIB`, ...) and crossref:uses[uses,`USES`] provided by the framework handle this automatically. Some software, add `-s` to their `LDFLAGS`, in this case, either remove `-s` if `WITH_DEBUG` is set, or remove it unconditionally and use `STRIP_CMD` in `post-install`. ==== [[install-copytree]] === Installing a Whole Tree of Files Sometimes, a large number of files must be installed while preserving their hierarchical organization. For example, copying over a whole directory tree from `WRKSRC` to a target directory under `PREFIX`. Note that `PREFIX`, `EXAMPLESDIR`, `DATADIR`, and other path variables must always be prepended with `STAGEDIR` to respect staging (see crossref:special[staging,Staging]). Two macros exist for this situation. The advantage of using these macros instead of `cp` is that they guarantee proper file ownership and permissions on target files. The first macro, `COPYTREE_BIN`, will set all the installed files to be executable, thus being suitable for installing into [.filename]#PREFIX/bin#. The second macro, `COPYTREE_SHARE`, does not set executable permissions on files, and is therefore suitable for installing files under [.filename]#PREFIX/share# target. [.programlisting] .... post-install: ${MKDIR} ${STAGEDIR}${EXAMPLESDIR} (cd ${WRKSRC}/examples && ${COPYTREE_SHARE} . ${STAGEDIR}${EXAMPLESDIR}) .... This example will install the contents of the [.filename]#examples# directory in the vendor distfile to the proper examples location of the port. [.programlisting] .... post-install: ${MKDIR} ${STAGEDIR}${DATADIR}/summer (cd ${WRKSRC}/temperatures && ${COPYTREE_SHARE} "June July August" ${STAGEDIR}${DATADIR}/summer) .... And this example will install the data of summer months to the [.filename]#summer# subdirectory of a [.filename]#DATADIR#. Additional `find` arguments can be passed via the third argument to `COPYTREE_*` macros. For example, to install all files from the first example except Makefiles, one can use these commands. [.programlisting] .... post-install: ${MKDIR} ${STAGEDIR}${EXAMPLESDIR} (cd ${WRKSRC}/examples && \ ${COPYTREE_SHARE} . ${STAGEDIR}${EXAMPLESDIR} "! -name Makefile") .... These macros do not add the installed files to [.filename]#pkg-plist#. They must be added manually. For optional documentation (`PORTDOCS`, see crossref:makefiles[install-documentation, Install Additional Documentation]) and examples (`PORTEXAMPLES`), the `%%PORTDOCS%%` or `%%PORTEXAMPLES%%` prefixes must be prepended in [.filename]#pkg-plist#. [[install-documentation]] === Install Additional Documentation If the software has some documentation other than the standard man and info pages that is useful for the user, install it under `DOCSDIR`. This can be done, like the previous item, in the `post-install` target. Create a new directory for the port. The directory name is `DOCSDIR`. This usually equals `PORTNAME`. However, if the user might want different versions of the port to be installed at the same time, the whole `PKGNAME` can be used. Since only the files listed in [.filename]#pkg-plist# are installed, it is safe to always install documentation to `STAGEDIR` (see crossref:special[staging,Staging]). Hence `.if` blocks are only needed when the installed files are large enough to cause significant I/O overhead. [.programlisting] .... post-install: ${MKDIR} ${STAGEDIR}${DOCSDIR} ${INSTALL_DATA} ${WRKSRC}/docs/xvdocs.ps ${STAGEDIR}${DOCSDIR} .... On the other hand, if there is a DOCS option in the port, install the documentation in a `post-install-DOCS-on` target. These targets are described in crossref:makefiles[options-targets, Additional Build Targets, `_target_-_OPT_-on` and `_target_-_OPT_-off`]. Here are some handy variables and how they are expanded by default when used in the [.filename]#Makefile#: * `DATADIR` gets expanded to [.filename]#PREFIX/share/PORTNAME#. * `DATADIR_REL` gets expanded to [.filename]#share/PORTNAME#. * `DOCSDIR` gets expanded to [.filename]#PREFIX/share/doc/PORTNAME#. * `DOCSDIR_REL` gets expanded to [.filename]#share/doc/PORTNAME#. * `EXAMPLESDIR` gets expanded to [.filename]#PREFIX/share/examples/PORTNAME#. * `EXAMPLESDIR_REL` gets expanded to [.filename]#share/examples/PORTNAME#. [NOTE] ==== The `DOCS` option only controls additional documentation installed in `DOCSDIR`. It does not apply to standard man pages and info pages. Things installed in `EXAMPLESDIR` are controlled by the `EXAMPLES` option. ==== These variables are exported to `PLIST_SUB`. Their values will appear there as pathnames relative to [.filename]#PREFIX# if possible. That is, [.filename]#share/doc/PORTNAME# will be substituted for `%%DOCSDIR%%` in the packing list by default, and so on. (See more on [.filename]#pkg-plist# substitution crossref:plist[plist-sub,here].) All conditionally installed documentation files and directories are included in [.filename]#pkg-plist# with the `%%PORTDOCS%%` prefix, for example: [.programlisting] .... %%PORTDOCS%%%%DOCSDIR%%/AUTHORS %%PORTDOCS%%%%DOCSDIR%%/CONTACT .... As an alternative to enumerating the documentation files in [.filename]#pkg-plist#, a port can set the variable `PORTDOCS` to a list of file names and shell glob patterns to add to the final packing list. The names will be relative to `DOCSDIR`. Therefore, a port that utilizes `PORTDOCS`, and uses a non-default location for its documentation, must set `DOCSDIR` accordingly. If a directory is listed in `PORTDOCS` or matched by a glob pattern from this variable, the entire subtree of contained files and directories will be registered in the final packing list. If the `DOCS` option has been unset then files and directories listed in `PORTDOCS` would not be installed or added to port packing list. Installing the documentation at `PORTDOCS` as shown above remains up to the port itself. A typical example of utilizing `PORTDOCS`: [.programlisting] .... PORTDOCS= README.* ChangeLog docs/* .... [NOTE] ==== The equivalents of `PORTDOCS` for files installed under `DATADIR` and `EXAMPLESDIR` are `PORTDATA` and `PORTEXAMPLES`, respectively. The contents of [.filename]#pkg-message# are displayed upon installation. See crossref:pkg-files[porting-message,the section on using [.filename]#pkg-message#] for details. [.filename]#pkg-message# does not need to be added to [.filename]#pkg-plist#. ==== [[install-subdirs]] === Subdirectories Under `PREFIX` Try to let the port put things in the right subdirectories of `PREFIX`. Some ports lump everything and put it in the subdirectory with the port's name, which is incorrect. Also, many ports put everything except binaries, header files and manual pages in a subdirectory of [.filename]#lib#, which does not work well with the BSD paradigm. Many of the files must be moved to one of these directories: [.filename]#etc# (setup/configuration files), [.filename]#libexec# (executables started internally), [.filename]#sbin# (executables for superusers/managers), [.filename]#info# (documentation for info browser) or [.filename]#share# (architecture independent files). See man:hier[7] for details; the rules governing [.filename]#/usr# pretty much apply to [.filename]#/usr/local# too. The exception are ports dealing with USENET "news". They may use [.filename]#PREFIX/news# as a destination for their files. [[binary-alias]] == Use `BINARY_ALIAS` to Rename Commands Instead of Patching the Build When `BINARY_ALIAS` is defined it will create symlinks of the given commands in a directory which will be prepended to `PATH`. Use it to substitute hardcoded commands the build phase relies on without having to patch any build files. [[binary-alias-ex1]] .Using `BINARY_ALIAS` to Make `gsed` Available as `sed` [example] ==== Some ports expect `sed` to behave like GNU sed and use features that man:sed[1] does not provide. GNU sed is available from package:textproc/gsed[] on FreeBSD. Use `BINARY_ALIAS` to substitute `sed` with `gsed` for the duration of the build: [.programlisting] .... BUILD_DEPENDS= gsed:textproc/gsed ... BINARY_ALIAS= sed=gsed .... ==== [[binary-alias-ex2]] .Using `BINARY_ALIAS` to Provide Aliases for Hardcoded `python3` Commands [example] ==== A port that has a hardcoded reference to `python3` in its build scripts will need to have it available in `PATH` at build time. Use `BINARY_ALIAS` to create an alias that points to the right Python 3 binary: [.programlisting] .... USES= python:3.4+,build ... BINARY_ALIAS= python3=${PYTHON_CMD} .... See crossref:special[using-python,Using Python] for more information about `USES=python`. ==== [NOTE] ==== Binary aliases are created after the dependencies provided via `BUILD_DEPENDS` and `LIB_DEPENDS` are processed and before the `configure` target. This leads to various limitations. For example, programs installed via `TEST_DEPENDS` cannot be used to create a binary alias as test dependencies specified this way are processed after binary aliases are created. ====