diff --git a/documentation/content/en/books/handbook/mail/_index.adoc b/documentation/content/en/books/handbook/mail/_index.adoc index 2ba45f2e4a..f89e990075 100644 --- a/documentation/content/en/books/handbook/mail/_index.adoc +++ b/documentation/content/en/books/handbook/mail/_index.adoc @@ -1,964 +1,964 @@ --- title: Chapter 31. Electronic Mail part: IV. Network Communication prev: books/handbook/ppp-and-slip next: books/handbook/network-servers description: This chapter provides a basic introduction to running a mail server on FreeBSD, as well as an introduction to sending and receiving email using FreeBSD tags: ["mail", "sendmail", "dma", "MTA", "SMTP", "mail user agents", "fetchmail", "procmail", "alpine", "mutt", "postfix"] showBookMenu: true weight: 36 path: "/books/handbook/" --- [[mail]] = Electronic Mail :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 31 :partnums: :source-highlighter: rouge :experimental: :images-path: books/handbook/mail/ 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::[] [[mail-synopsis]] == Synopsis "Electronic Mail", better known as email, is one of the most widely used forms of communication today. This chapter provides a basic introduction to running a mail server on FreeBSD, as well as an introduction to sending and receiving email using FreeBSD. For more complete coverage of this subject, refer to the books listed in crossref:bibliography[bibliography,Bibliography]. This chapter covers: * Which software components are involved in sending and receiving electronic mail. * How to configure DragonFly Mail Agent. * Where basic Sendmail configuration files are located in FreeBSD. * The difference between remote and local mailboxes. * How to install and configure an alternate Mail Transfer Agent, replacing DragonFly Mail Agent or Sendmail. * How to troubleshoot common mail server problems. * How to configure Sendmail to only send mail. * How to configure SMTP authentication for added security in Sendmail. * How to install and use a Mail User Agent, such as mutt, to send and receive email. * How to download mail from a remote POP or IMAP server. * How to automatically apply filters and rules to incoming email. [[mail-using]] == Mail Components There are five major parts involved in an email exchange: the Mail User Agent (MUA), the Mail Transfer Agent (MTA), a mail host, a remote or local mailbox, and DNS. This section provides an overview of these components. Mail User Agent (MUA):: The Mail User Agent (MUA) is an application which is used to compose, send, and receive emails. This application can be a command line program, such as the built-in `mail` utility or a third-party application from the Ports Collection, such as alpine, elm, or mutt. Dozens of graphical programs are also available in the Ports Collection, including Claws Mail, Evolution, and Thunderbird. Some organizations provide a web mail program which can be accessed through a web browser. More information about installing and using a MUA on FreeBSD can be found in <>. Mail Transfer Agent (MTA):: The Mail Transfer Agent (MTA) is responsible for receiving incoming mail and delivering outgoing mail. -Starting with FreeBSD version 14.0, the default MTA is DragonFly Mail Agent (man:dma[8]); in earlier versions, it is man:sedmail[8]. +Starting with FreeBSD version 14.0, the default MTA is DragonFly Mail Agent (man:dma[8]); in earlier versions, it is man:sendmail[8]. Other MTAs, including Exim, Postfix, and qmail, may be installed to replace the default MTA. Mail Host and Mailboxes:: The mail host is a server that is responsible for delivering and receiving mail for a host or a network. The mail host collects all mail sent to the domain and stores it either in the default `mbox` or the alternative Maildir format, depending on the configuration. Once mail has been stored, it may either be read locally using a MUA or remotely accessed and collected using protocols such as POP or IMAP. If mail is read locally, a POP or IMAP server does not need to be installed. Domain Name System (DNS):: The Domain Name System (DNS) and its daemon man:named[8] play a large role in the delivery of mail. In order to deliver mail from one site to another, the MTA will look up the remote site in DNS to determine which host will receive mail for the destination. This process also occurs when mail is sent from a remote host to the MTA. [[dragonFly-mail-agent]] == DragonFly Mail Agent (DMA) DragonFly Mail Agent (DMA) is the default MTA in FreeBSD starting with version 14.0. man:dma[8] is a small Mail Transport Agent (MTA), designed for home and office use. It accepts mails from locally installed Mail User Agents (MUA) and delivers the mails either locally or to a remote destination. Remote delivery includes several features like TLS/SSL support and SMTP authentication. man:dma[8] is not intended as a replacement for real, big MTAs like man:sendmail[8] or man:postfix[1]. Consequently, man:dma[8] does not listen on port 25 for incoming connections. [[configuring-dragonfly-mail-agent]] === Configuring DragonFly Mail Agent (DMA) DMA comes with a default configuration that will be suitable for many deployments. Custom settings are defined in [.filename]#/etc/dma/dma.conf#, and SMTP authentication is configured in [.filename]#/etc/dma/auth.conf#. [[configuring-gmail-dma]] ==== Using DMA to Route Outgoing Mail through Gmail (STARTTLS:SMTP example) This example [.filename]#/etc/dma/dma.conf# can be used to send mail using Google's SMTP servers. [.programlisting] .... SMARTHOST smtp.gmail.com PORT 587 AUTHPATH /etc/dma/auth.conf SECURETRANSFER STARTTLS MASQUERADE username@gmail.com .... Authentication can be set with one line in [.filename]#/etc/dma/auth.conf#: [.programlisting] .... username@gmail.com|smtp.gmail.com:password .... Execute the following command to test the configuration: [source,shell] .... % echo this is a test | mail -v -s testing-email username@gmail.com .... [[configuring-fastmail-dma]] ==== Using DMA to Route Outgoing Mail through Fastmail (SSL/TLS example) This example [.filename]#/etc/dma/dma.conf# can be used to send mail using Fastmail's SMTP servers. [.programlisting] .... SMARTHOST smtp.fastmail.com PORT 465 AUTHPATH /etc/dma/auth.conf SECURETRANSFER MAILNAME example.server.com .... Authentication can be set with one line in [.filename]#/etc/dma/auth.conf#: [.programlisting] .... username@fastmail.com|smtp.fastmail.com:password .... Execute the following command to test the configuration: [source,shell] .... % echo this is a test | mail -v -s testing-email username@fastmail.com .... [[configuring-custom-dma]] ==== Using DMA to Route Outgoing Mail through a Custom Mail Host This example [.filename]#/etc/dma/dma.conf# can be used to send mail using a custom mail host. [.programlisting] .... SMARTHOST mail.example.org PORT 587 AUTHPATH /etc/dma/auth.conf SECURETRANSFER STARTTLS .... Authentication can be set with one line in [.filename]#/etc/dma/auth.conf#: [.programlisting] .... username@example.org|mail.example.org:password .... Execute the following command to test the configuration: [source,shell] .... % echo this is a test | mail -v -s testing-email username@example.org .... [[sendmail]] == Sendmail Sendmail is a venerable and versatile Mail Transfer Agent (MTA) with a long history in UNIX(R) and UNIX-like systems. It was a part of the FreeBSD base system until FreeBSD 13, offering robust email transport capabilities, extensive customization options, and support for complex routing and filtering. [[configuring-sendmail]] === Configuration Files The configuration files for Sendmail are located in [.filename]#/etc/mail/#. [.filename]#/etc/mail/access#:: This access database file defines which hosts or IP addresses have access to the local mail server and what kind of access they have. Hosts listed as `OK`, which is the default option, are allowed to send mail to this host as long as the mail's final destination is the local machine. Hosts listed as `REJECT` are rejected for all mail connections. Hosts listed as `RELAY` are allowed to send mail for any destination using this mail server. Hosts listed as `ERROR` will have their mail returned with the specified mail error. If a host is listed as `SKIP`, Sendmail will abort the current search for this entry without accepting or rejecting the mail. Hosts listed as `QUARANTINE` will have their messages held and will receive the specified text as the reason for the hold. + Examples of using these options for both IPv4 and IPv6 addresses can be found in the FreeBSD sample configuration, [.filename]#/etc/mail/access.sample#: + To configure the access database, use the format shown in the sample to make entries in [.filename]#/etc/mail/access#, but do not put a comment symbol (`+#+`) in front of the entries. Create an entry for each host or network whose access should be configured. Mail senders that match the left side of the table are affected by the action on the right side of the table. + Whenever this file is updated, update its database and restart Sendmail: + [source,shell] .... # makemap hash /etc/mail/access < /etc/mail/access # service sendmail restart .... [.filename]#/etc/mail/aliases#:: This database file contains a list of virtual mailboxes that are expanded to users, files, programs, or other aliases. Here are a few entries to illustrate the file format: + [.programlisting] .... root: localuser ftp-bugs: joe,eric,paul bit.bucket: /dev/null procmail: "|/usr/local/bin/procmail" .... + The mailbox name on the left side of the colon is expanded to the target(s) on the right. The first entry expands the `root` mailbox to the `localuser` mailbox, which is then looked up in the [.filename]#/etc/mail/aliases# database. If no match is found, the message is delivered to `localuser`. The second entry shows a mail list. Mail to `ftp-bugs` is expanded to the three local mailboxes `joe`, `eric`, and `paul`. A remote mailbox could be specified as _user@example.com_. The third entry shows how to write mail to a file, in this case [.filename]#/dev/null#. The last entry demonstrates how to send mail to a program, [.filename]#/usr/local/bin/procmail#, through a UNIX(R) pipe. Refer to man:aliases[5] for more information about the format of this file. + Whenever this file is updated, run `newaliases` to update and initialize the aliases database. [.filename]#/etc/mail/sendmail.cf#:: This is the master configuration file for Sendmail. It controls the overall behavior of Sendmail, including everything from rewriting email addresses to printing rejection messages to remote mail servers. Accordingly, this configuration file is quite complex. Fortunately, this file rarely needs to be changed for standard mail servers. + The master Sendmail configuration file can be built from man:m4[1] macros that define the features and behavior of Sendmail. Refer to [.filename]#/usr/src/contrib/sendmail/cf/README# for some of the details. + Whenever changes to this file are made, Sendmail needs to be restarted for the changes to take effect. [.filename]#/etc/mail/virtusertable#:: This database file maps mail addresses for virtual domains and users to real mailboxes. These mailboxes can be local, remote, aliases defined in [.filename]#/etc/mail/aliases#, or files. This allows multiple virtual domains to be hosted on one machine. + FreeBSD provides a sample configuration file in [.filename]#/etc/mail/virtusertable.sample# to further demonstrate its format. The following example demonstrates how to create custom entries using that format: + [.programlisting] .... root@example.com root postmaster@example.com postmaster@noc.example.net @example.com joe .... + This file is processed in a first match order. When an email address matches the address on the left, it is mapped to the local mailbox listed on the right. The format of the first entry in this example maps a specific email address to a local mailbox, whereas the format of the second entry maps a specific email address to a remote mailbox. Finally, any email address from `example.com` which has not matched any of the previous entries will match the last mapping and be sent to the local mailbox `joe`. When creating custom entries, use this format and add them to [.filename]#/etc/mail/virtusertable#. Whenever this file is edited, update its database and restart Sendmail: + [source,shell] .... # makemap hash /etc/mail/virtusertable < /etc/mail/virtusertable # service sendmail restart .... [.filename]#/etc/mail/relay-domains#:: In a default FreeBSD installation, Sendmail is configured to only send mail from the host it is running on. For example, if a POP server is available, users will be able to check mail from remote locations but they will not be able to send outgoing emails from outside locations. Typically, a few moments after the attempt, an email will be sent from `MAILER-DAEMON` with a `5.7 Relaying Denied` message. + The most straightforward solution is to add the ISP's FQDN to [.filename]#/etc/mail/relay-domains#. If multiple addresses are needed, add them one per line: + [.programlisting] .... your.isp.example.com other.isp.example.net users-isp.example.org www.example.org .... + After creating or editing this file, restart Sendmail with `service sendmail restart`. + Now any mail sent through the system by any host in this list, provided the user has an account on the system, will succeed. This allows users to send mail from the system remotely without opening the system up to relaying SPAM from the Internet. [[mail-changingmta]] == Changing the Mail Transfer Agent Starting with FreeBSD version 14.0, man:dma[8] is the default MTA, and before 14.0, the default MTA is man:sendmail[8]. However, the system administrator can change the system's MTA. A wide choice of alternative MTAs is available from the `mail` category of the FreeBSD Ports Collection. [WARNING] ==== If the default's outgoing mail service is disabled, it is important that it is replaced with an alternative mail delivery system. Otherwise, system functions such as man:periodic[8] will be unable to deliver their results by email. Many parts of the system expect a functional MTA. If applications continue to use the default binaries to try to send email after they are disabled, mail could go into an inactive queue and never be delivered. ==== [[replace-sendmail-dma]] === Replacing Sendmail with Other MTA In order to completely disable man:sendmail[8] execute the following commands: [source,shell] .... # sysrc sendmail_enable="NO" # sysrc sendmail_submit_enable="NO" # sysrc sendmail_outbound_enable="NO" # sysrc sendmail_msp_queue_enable="NO" .... To only disable man:sendmail[8]'s incoming mail service execute the following command: [source,shell] .... # sysrc sendmail_enable="NO" .... Then stop the man:sendmail[8] service: [source,shell] .... # service sendmail onestop .... Some extra configuration is needed as man:sendmail[8] is so ubiquitous that some software assumes it is already installed and configured. Check [.filename]#/etc/periodic.conf# and make sure that these values are set to `NO`. If this file does not exist, create it with these entries: [.programlisting] .... daily_clean_hoststat_enable="NO" daily_status_mail_rejects_enable="NO" daily_status_include_submit_mailq="NO" daily_submit_queuerun="NO" .... The next step is to install another MTA, man:dma[8] will be used in this example. As pointed above, man:dma[8] is the default MTA in FreeBSD starting with version 14.0. Therefore, it is only necessary to install it from the ports if you are using a previous version. To install it execute the following command: [source,shell] .... # pkg install dma .... Perform the configuration as indicated in <>. Then change all the entries in the file [.filename]#/etc/mail/mailer.conf# to man:dma[8]: [.programlisting] .... # $FreeBSD$ # # Execute the "real" sendmail program, named /usr/libexec/sendmail/sendmail # # If dma(8) is installed, an example mailer.conf that uses dma(8) instead can # be found in /usr/share/examples/dma # sendmail /usr/local/libexec/dma mailq /usr/local/libexec/dma newaliases /usr/local/libexec/dma .... [NOTE] ==== When using the version of man:dma[8] included in the base system, the paths will change to [.filename]#/usr/libexec/dma#. ==== To ensure that anything in the queue is flushed at boot or before shutdown, execute the following command: [source,shell] .... # sysrc dma_flushq_enable="YES" .... Once everything is configured, it is recommended to reboot the system. Rebooting provides the opportunity to ensure that the system is correctly configured to start the new MTA automatically on boot. [[replace-dma]] === Replacing DragonFly Mail Agent (DMA) with Other MTA As noted above, starting with FreeBSD version 14.0, the default MTA is DMA. In this example, package:mail/postfix[] will be used as the alternative MTA. Before installing package:mail/postfix[] some extra configuration is needed. Check [.filename]#/etc/periodic.conf# and make sure that these values are set to `NO`. If this file does not exist, create it with these entries: [.programlisting] .... daily_clean_hoststat_enable="NO" daily_status_mail_rejects_enable="NO" daily_status_include_submit_mailq="NO" daily_submit_queuerun="NO" .... Then install package:mail/postfix[]: [source,shell] .... # pkg install postfix .... To start package:mail/postfix[] at system boot execute the following command: [source,shell] .... # sysrc postfix_enable="YES" .... [TIP] ==== It is good practice to read the installation message after installing an application. Provides useful information about settings, etc. ==== If postfix is *not* already activated in [.filename]#/usr/local/etc/mail/mailer.conf# execute the following commands: [source,shell] .... mv /usr/local/etc/mail/mailer.conf /usr/local/etc/mail/mailer.conf.old install -d /usr/local/etc/mail install -m 0644 /usr/local/share/postfix/mailer.conf.postfix /usr/local/etc/mail/mailer.conf .... When employing SASL, ensure that postfix has access to read the sasldb file. This is accomplished by adding postfix to group mail and making the [.filename]#/usr/local/etc/sasldb*# file(s) readable by group mail (this should be the default for new installs). Once everything is configured, it is recommended to reboot the system. Rebooting provides the opportunity to ensure that the system is correctly configured to start the new MTA automatically on boot. [[mail-agents]] == Mail User Agents A MUA is an application that is used to send and receive email. As email "evolves" and becomes more complex, MUAs are becoming increasingly powerful and provide users increased functionality and flexibility. The `mail` category of the FreeBSD Ports Collection contains numerous MUAs. These include graphical email clients such as Evolution or Balsa and console based clients such as mutt or alpine. [[mail-command]] === mail man:mail[1] is the default MUA installed with FreeBSD. It is a console based MUA that offers the basic functionality required to send and receive text-based email. It provides limited attachment support and can only access local mailboxes. Although man:mail[1] does not natively support interaction with POP or IMAP servers, these mailboxes may be downloaded to a local `mbox` using an application such as fetchmail or getmail. In order to send and receive email, run man:mail[1]: [source,shell] .... % mail .... The contents of the user's mailbox in [.filename]#/var/mail# are automatically read by man:mail[1]. Should the mailbox be empty, the utility exits with a message indicating that no mail could be found. If mail exists, the application interface starts, and a list of messages will be displayed. Messages are automatically numbered, as can be seen in the following example: [.programlisting] .... Mail version 8.1 6/6/93. Type ? for help. "/var/mail/username": 3 messages 3 new >N 1 root@localhost Mon Mar 8 14:05 14/510 "test" N 2 root@localhost Mon Mar 8 14:05 14/509 "user account" N 3 root@localhost Mon Mar 8 14:05 14/509 "sample" .... Messages can now be read by typing kbd:[t] followed by the message number. This example reads the first email: [.programlisting] .... & t 1 Message 1: From root@localhost Mon Mar 8 14:05:52 2004 X-Original-To: username@localhost Delivered-To: username@localhost To: username@localhost Subject: test Date: Mon, 8 Mar 2004 14:05:52 +0200 (SAST) From: root@localhost (Charlie Root) This is a test message, please reply if you receive it. .... As seen in this example, the message will be displayed with full headers. To display the list of messages again, press kbd:[h]. If the email requires a reply, press either kbd:[R] or kbd:[r] man:mail[1] keys. kbd:[R] instructs man:mail[1] to reply only to the sender of the email, while kbd:[r] replies to all other recipients of the message. These commands can be suffixed with the mail number of the message to reply to. After typing the response, the end of the message should be marked by a single kbd:[.] on its own line. An example can be seen below: [.programlisting] .... & R 1 To: root@localhost Subject: Re: test Thank you, I did get your email. . EOT .... In order to send a new email, press kbd:[m], followed by the recipient email address. Multiple recipients may be specified by separating each address with the kbd:[,] delimiter. The subject of the message may then be entered, followed by the message contents. The end of the message should be specified by putting a single kbd:[.] on its own line. [.programlisting] .... & mail root@localhost Subject: I mastered mail Now I can send and receive email using mail ... :) . EOT .... While using man:mail[1], press kbd:[?] to display help at any time. Refer to man:mail[1] for more help on how to use man:mail[1]. [NOTE] ==== man:mail[1] was not designed to handle attachments and thus deals with them poorly. Newer MUAs handle attachments in a more intelligent way. ==== [[mutt-command]] === Mutt Mutt is a powerful MUA, with many features, including: * The ability to thread messages. * PGP support for digital signing and encryption of email. * MIME support. * Maildir support. * Highly customizable. Refer to link:http://www.mutt.org[http://www.mutt.org] for more information on Mutt. [TIP] ==== A Mutt fork called NeoMutt is worth mentioning, which brings added features. See more on the link:https://neomutt.org/about.html[NeoMutt website]. If NeoMutt was chosen, replace the following command examples from `mutt` to `neomutt`. ==== Mutt may be installed using the package:mail/mutt[] port. After the port has been installed, Mutt can be started by issuing the following command: [source,shell] .... % mutt .... Mutt will automatically read and display the contents of the user mailbox in [.filename]#/var/mail#. If no mails are found, Mutt will wait for commands from the user. The example below shows Mutt displaying a list of messages: image::mutt1.png[Mutt email client showing a list of messages] To read an email, select it using the cursor keys and press kbd:[Enter]. An example of Mutt displaying email can be seen below: image::mutt2.png[Mutt email client displaying an email] Similar to man:mail[1], Mutt can be used to reply only to the sender of the message as well as to all recipients. To reply only to the sender of the email, press kbd:[r]. To send a group reply to the original sender as well as all the message recipients, press kbd:[g]. [NOTE] ==== By default, Mutt uses the man:vi[1] editor for creating and replying to emails. Each user can customize this by creating or editing the [.filename]#.muttrc# in their home directory and setting the `editor` variable or by setting the `EDITOR` environment variable. Refer to link:http://www.mutt.org/[http://www.mutt.org/] for more information about configuring Mutt. ==== To compose a new mail message, press kbd:[m]. After a valid subject has been given, Mutt will start man:vi[1] so the email can be written. Once the contents of the email are complete, save and quit from `vi`. Mutt will resume, displaying a summary screen of the mail that is to be delivered. In order to send the mail, press kbd:[y]. An example of the summary screen can be seen below: image::mutt3.png[Mutt email client showing the summary screen] Mutt contains extensive help which can be accessed from most of the menus by pressing kbd:[?]. The top line also displays the keyboard shortcuts where appropriate. [[alpine-command]] === alpine alpine is aimed at a beginner user, but also includes some advanced features. [WARNING] ==== alpine has had several remote vulnerabilities discovered in the past, which allowed remote attackers to execute arbitrary code as users on the local system, by the action of sending a specially-prepared email. While _known_ problems have been fixed, alpine code is written in an insecure style and the FreeBSD Security Officer believes there are likely to be other undiscovered vulnerabilities. Users install alpine at their own risk. ==== The current version of alpine may be installed using the package:mail/alpine[] port. Once the port has installed, alpine can be started by issuing the following command: [source,shell] .... % alpine .... The first time alpine runs, it displays a greeting page with a brief introduction, as well as a request from the alpine development team to send an anonymous email message allowing them to judge how many users are using their client. To send this anonymous message, press kbd:[Enter]. Alternatively, press kbd:[E] to exit the greeting without sending an anonymous message. An example of the greeting page is shown below: image::pine1.png[alpine email client showing the greeting page] The main menu is then presented, which can be navigated using the cursor keys. This main menu provides shortcuts for the composing new mails, browsing mail directories, and administering address book entries. Below the main menu, relevant keyboard shortcuts to perform functions specific to the task at hand are shown. The default directory opened by alpine is [.filename]#inbox#. To view the message index, press kbd:[I], or select the [.guimenuitem]#MESSAGE INDEX# option shown below: image::pine2.png[alpine email client showing the default directory] The message index shows messages in the current directory and can be navigated by using the cursor keys. Highlighted messages can be read by pressing kbd:[Enter]. image::pine3.png[alpine email client showing the message index] In the screenshot below, a sample message is displayed by alpine. Contextual keyboard shortcuts are displayed at the bottom of the screen. An example of one of a shortcut is kbd:[r], which tells the MUA to reply to the current message being displayed. image::pine4.png[alpine email client showing an email] Replying to an email in alpine is done using the pico editor, which is installed by default with alpine. pico makes it easy to navigate the message and is easier for novice users to use than man:vi[1] or man:mail[1]. Once the reply is complete, the message can be sent by pressing kbd:[Ctrl+X]. alpine will ask for confirmation before sending the message. image::pine5.png[alpine email client showing the message compose window] alpine can be customized using the [.guimenuitem]#SETUP# option from the main menu. [[mail-advanced]] == Advanced Topics This section covers more involved topics such as mail configuration and setting up mail for an entire domain. [[mail-config]] === Basic Configuration Out of the box, one can send email to external hosts as long as [.filename]#/etc/resolv.conf# is configured or the network has access to a configured DNS server. To have email delivered to the MTA on the FreeBSD host, do one of the following: * Run a DNS server for the domain. * Get mail delivered directly to the FQDN for the machine. In order to have mail delivered directly to a host, it must have a permanent static IP address, not a dynamic IP address. If the system is behind a firewall, it must be configured to allow SMTP traffic. To receive mail directly at a host, one of these two must be configured: * Make sure that the lowest-numbered MX record in DNS points to the host's static IP address. * Make sure there is no MX entry in the DNS for the host. Either of the above will allow mail to be received directly at the host. Try this: [source,shell] .... # hostname .... The output should be similar to the following: [.programlisting] .... example.FreeBSD.org .... [source,shell] .... # host example.FreeBSD.org .... The output should be similar to the following: [.programlisting] .... example.FreeBSD.org has address 204.216.27.XX .... In this example, mail sent directly to mailto:yourlogin@example.FreeBSD.org[yourlogin@example.FreeBSD.org] should work without problems, assuming a full-featured MTA is running correctly on `example.FreeBSD.org`. Note that man:dma[8] does not listen on port 25 for incoming connections and cannot be used in this scenario. For this example: [source,shell] .... # host example.FreeBSD.org .... The output should be similar to the following: [.programlisting] .... example.FreeBSD.org has address 204.216.27.XX example.FreeBSD.org mail is handled (pri=10) by nevdull.FreeBSD.org .... All mail sent to `example.FreeBSD.org` will be collected on `nevdull` under the same username instead of being sent directly to your host. The above information is handled by the DNS server. The DNS record that carries mail routing information is the link:https://en.wikipedia.org/wiki/MX_record[mail exchanger record (MX record)]. If no MX record exists, mail will be delivered directly to the host by way of its IP address. The MX entry for `freefall.FreeBSD.org` at one time looked like this: [.programlisting] .... freefall MX 30 mail.crl.net freefall MX 40 agora.rdrop.com freefall MX 10 freefall.FreeBSD.org freefall MX 20 who.cdrom.com .... `freefall` had many MX entries. The lowest MX number is the host that receives mail directly, if available. If it is not accessible for some reason, the next lower-numbered host will accept messages temporarily, and pass it along when a lower-numbered host becomes available. Alternate MX sites should have separate Internet connections in order to be most useful. Your ISP can provide this service. [[mail-domain]] === Mail for a Domain When configuring an MTA for a network, any mail sent to hosts in its domain should be diverted to the MTA so that users can receive their mail on the master mail server. To make life easiest, a user account with the same _username_ should exist on both the MTA and the system with the MUA. Use man:adduser[8] to create the user accounts. [TIP] ==== In addition to adding local users to the host, there are alternative methods known as virtual users. Programs like link:https://www.cyrusimap.org/[Cyrus] and link:https://www.dovecot.org/[Dovecot] can be integrated into MTAs to handle users, mail storage, and also provide access via POP3 and IMAP. ==== The MTA must be the designated mail exchanger for each workstation on the network. This is done in the DNS configuration with an MX record: [.programlisting] .... example.FreeBSD.org A 204.216.27.XX ; Workstation MX 10 nevdull.FreeBSD.org ; Mailhost .... This will redirect mail for the workstation to the MTA no matter where the A record points. The mail is sent to the MX host. This must be configured on a DNS server. If the network does not run its own DNS server, talk to the ISP or DNS provider. The following is an example of virtual email hosting. Consider a customer with the domain `customer1.org`, where all the mail for `customer1.org` should be sent to `mail.myhost.com`. The DNS entry should look like this: [.programlisting] .... customer1.org MX 10 mail.myhost.com .... An `A` record is _not_ needed for `customer1.org` in order to only handle email for that domain. However, running `ping` against `customer1.org` will not work unless an `A` record exists for it. Tell the MTA which domains and/or hostnames it should accept mail for. Either of the following will work for Sendmail: * Add the hosts to [.filename]#/etc/mail/local-host-names# when using the `FEATURE(use_cw_file)`. * Add a `Cwyour.host.com` line to [.filename]#/etc/sendmail.cf#. [[outgoing-only]] === Setting Up to Send Only There are many instances where one may only want to send mail through a relay. Some examples are: * The computer is a desktop machine that needs to use programs such as man:mail[1], using the ISP's mail relay. * The computer is a server that does not handle mail locally, but needs to pass off all mail to a relay for processing. While any MTA is capable of filling this particular niche, it can be difficult to properly configure a full-featured MTA just to handle offloading mail. Programs such as Sendmail and Postfix are overkill for this use. Additionally, a typical Internet access service agreement may forbid one from running a "mail server". The easiest way to fulfill those needs is to use the man:dma[8] MTA included in the <>. For systems up to 13.2, need be to installed from ports. In addition to man:dma[8], third-party software can be used to achieve the same, like package:mail/ssmtp[]. [source,shell] .... # cd /usr/ports/mail/ssmtp # make install replace clean .... Once installed, package:mail/ssmtp[] can be configured with [.filename]#/usr/local/etc/ssmtp/ssmtp.conf#: [.programlisting] .... root=yourrealemail@example.com mailhub=mail.example.com rewriteDomain=example.com hostname=_HOSTNAME_ .... Use the real email address for `root`. Enter the ISP's outgoing mail relay in place of `mail.example.com`. Some ISPs call this the "outgoing mail server" or "SMTP server". Make sure to disable Sendmail, including the outgoing mail service. See <> for details. package:mail/ssmtp[] has some other options available. Refer to the examples in [.filename]#/usr/local/etc/ssmtp# or the manual page of ssmtp for more information. Setting up ssmtp in this manner allows any software on the computer that needs to send mail to function properly, while not violating the ISP's usage policy or allowing the computer to be hijacked for spamming. [[SMTP-Auth]] === SMTP Authentication in Sendmail Configuring SMTP authentication on the MTA provides a number of benefits. SMTP authentication adds a layer of security to Sendmail, and provides mobile users who switch hosts the ability to use the same MTA without the need to reconfigure their mail client's settings each time. Install package:security/cyrus-sasl2[] from the Ports Collection. This port supports a number of compile-time options. For the SMTP authentication method demonstrated in this example, make sure that `LOGIN` is not disabled. After installing package:security/cyrus-sasl2[], edit [.filename]#/usr/local/lib/sasl2/Sendmail.conf#, or create it if it does not exist, and add the following line: [.programlisting] .... pwcheck_method: saslauthd .... Next, install package:security/cyrus-sasl2-saslauthd[] and add execute the following command: [source,shell] .... # sysrc saslauthd_enable="YES" .... Finally, start the saslauthd daemon: [source,shell] .... # service saslauthd start .... This daemon serves as a broker for Sendmail to authenticate against the FreeBSD man:passwd[5] database. This saves the trouble of creating a new set of usernames and passwords for each user that needs to use SMTP authentication, and keeps the login and mail password the same. Next, edit [.filename]#/etc/make.conf# and add the following lines: [.programlisting] .... SENDMAIL_CFLAGS=-I/usr/local/include/sasl -DSASL SENDMAIL_LDADD=/usr/local/lib/libsasl2.so .... These lines provide Sendmail the proper configuration options for linking to package:cyrus-sasl2[] at compile time. Make sure that package:cyrus-sasl2[] has been installed before recompiling Sendmail. Recompile Sendmail by executing the following commands: [source,shell] .... # cd /usr/src/lib/libsmutil # make cleandir && make obj && make # cd /usr/src/lib/libsm # make cleandir && make obj && make # cd /usr/src/usr.sbin/sendmail # make cleandir && make obj && make && make install .... This compile should not have any problems if [.filename]#/usr/src# has not changed extensively and the shared libraries it needs are available. After Sendmail has been compiled and reinstalled, edit [.filename]#/etc/mail/freebsd.mc# or the local [.filename]#.mc#. Many administrators choose to use the output from man:hostname[1] as the name of [.filename]#.mc# for uniqueness. Add these lines: [.programlisting] .... dnl set SASL options TRUST_AUTH_MECH(`GSSAPI DIGEST-MD5 CRAM-MD5 LOGIN')dnl define(`confAUTH_MECHANISMS', `GSSAPI DIGEST-MD5 CRAM-MD5 LOGIN')dnl .... These options configure the different methods available to Sendmail for authenticating users. To use a method other than pwcheck, refer to the Sendmail documentation. Finally, run man:make[1] while in [.filename]#/etc/mail#. That will run the new [.filename]#.mc# and create a [.filename]#.cf# named either [.filename]#freebsd.cf# or the name used for the local [.filename]#.mc#. Then, run `make install restart`, which will copy the file to [.filename]#sendmail.cf#, and properly restart Sendmail. For more information about this process, refer to [.filename]#/etc/mail/Makefile#. To test the configuration, use a MUA to send a test message. For further investigation, set the `LogLevel` of Sendmail to `13` and watch [.filename]#/var/log/maillog# for any errors. For more information, refer to http://www.sendmail.org/~ca/email/auth.html[SMTP authentication]. diff --git a/documentation/content/en/books/handbook/network/_index.adoc b/documentation/content/en/books/handbook/network/_index.adoc index f196e475d6..bb9a7ab798 100644 --- a/documentation/content/en/books/handbook/network/_index.adoc +++ b/documentation/content/en/books/handbook/network/_index.adoc @@ -1,950 +1,950 @@ --- title: Chapter 7. Network part: Part I. Getting Started prev: books/handbook/wayland next: books/handbook/partii description: This chapter delves into the topic of network configuration and performance, showcasing the robust networking capabilities of the FreeBSD operating system. tags: ["network", "ipv4", "ipv6", "wireless", "wpa_supplicant", "static ip", "dynamic ip"] showBookMenu: true weight: 9 path: "/books/handbook/" --- [[network]] = Network :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 7 :partnums: :source-highlighter: rouge :experimental: :images-path: books/handbook/network/ 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::[] [[network-synopsis]] == Synopsis This chapter delves into the topic of network configuration and performance, showcasing the robust networking capabilities of the FreeBSD operating system. Whether working with wired or wireless networks, this chapter provides a comprehensive guide to configuring and optimizing network connectivity in FreeBSD. Before diving into the details, it is beneficial for readers to have a basic understanding of networking concepts such as protocols, network interfaces, and addressing. This chapter covers: * The ability to configure wired networks in FreeBSD, including network interface setup, addressing, and customization options. * The skills to configure wireless networks in FreeBSD, encompassing wireless network interface setup, security protocols, and troubleshooting techniques. * FreeBSD's networking capabilities and its reputation for excellent network performance. * An understanding of various network services and protocols supported by FreeBSD, with configuration instructions for DNS, DHCP and more. More information about how to make advanced network configurations in crossref:advanced-networking[advanced-networking,Advanced Networking]. [[config-network-setup]] == Setting up the Network Setting up a wired or wireless connection is a common task for a FreeBSD user. This section will show how to identify the wired and wireless network adapters and how to configure them. Before starting with the configuration it is necessary to know the following network data: * If the network has DHCP * If the network does not have DHCP, the static IP to be used * The netmask * The IP address of the default gateway [TIP] ==== The network connection may have been configured at installation time by man:bsdinstall[8]. ==== [[config-identify-network-adapter]] === Identify Network Adapters FreeBSD supports a wide variety of network adapters for both wired and wireless networks. Check the Hardware Compatibility List for the used link:https://www.freebsd.org/releases/[FreeBSD release] to see if the network adapter is supported. To get the network adapters used by our system execute the following command: [source,shell] .... % pciconf -lv | grep -A1 -B3 network .... The output should be similar to the following: [.programlisting] .... em0@pci0:0:25:0: class=0x020000 rev=0x03 hdr=0x00 vendor=0x8086 device=0x10f5 subvendor=0x17aa subdevice=0x20ee vendor = 'Intel Corporation' <1> device = '82567LM Gigabit Network Connection' <2> class = network subclass = ethernet -- iwn0@pci0:3:0:0: class=0x028000 rev=0x00 hdr=0x00 vendor=0x8086 device=0x4237 subvendor=0x8086 subdevice=0x1211 vendor = 'Intel Corporation' <1> device = 'PRO/Wireless 5100 AGN [Shiloh] Network Connection' <2> class = networ .... The text before the '@' symbol is the name of the driver controlling the device. In this case these are man:em[4] and man:iwn[4]. <1> Shows the name of the vendor <2> Shows the name of the device [NOTE] ==== It is only necessary to load the network interface card module if FreeBSD has not detected it correctly. For example, to load the man:alc[4] module, execute the following command: [source,shell] .... # kldload if_alc .... Alternatively, to load the driver as a module at boot time, place the following line in [.filename]#/boot/loader.conf#: [.programlisting] .... if_alc_load="YES" .... ==== [[config-network-connection]] == Wired Networks Once the right driver is loaded the network adapter needs to be configured. FreeBSD uses the driver name followed by a unit number to name the network interface adapter. The unit number represents the order in which the adapter is detected at boot time, or is later discovered. For example, `em0` is the first network interface card (NIC) on the system using the man:em[4] driver. To display the network interface configuration, enter the following command: [source,shell] .... % ifconfig .... The output should be similar to the following: [.programlisting] .... em0: flags=8863 metric 0 mtu 1500 options=481249b ether 00:1f:16:0f:27:5a inet6 fe80::21f:16ff:fe0f:275a%em0 prefixlen 64 scopeid 0x1 inet 192.168.1.19 netmask 0xffffff00 broadcast 192.168.1.255 media: Ethernet autoselect (1000baseT ) status: active nd6 options=23 lo0: flags=8049 metric 0 mtu 16384 options=680003 inet6 ::1 prefixlen 128 inet6 fe80::1%lo0 prefixlen 64 scopeid 0x2 inet 127.0.0.1 netmask 0xff000000 groups: lo nd6 options=21 .... In this example, the following devices were displayed: * `em0`: The Ethernet interface. * `lo0`: The loop interface is a software loopback mechanism which may be used for performance analysis, software testing, and/or local communication. More information in man:lo[4]. The example shows that `em0` is up and running. The key indicators are: . `UP` means that the interface is configured and ready. . The interface has an IPv4 Internet (`inet`) address, `192.168.1.19`. . The interface has an IPv6 Internet (`inet6`) address, `fe80::21f:16ff:fe0f:275a%em0`. . It has a valid subnet mask (`netmask`), where `0xffffff00` is the same as `255.255.255.0`. . It has a valid broadcast address, `192.168.1.255`. . The MAC address of the interface (`ether`) is `00:1f:16:0f:27:5a`. . The physical media selection is on autoselection mode (`media: Ethernet autoselect (1000baseT )`). . The status of the link (`status`) is `active`, indicating that the carrier signal is detected. For `em0`, the `status: no carrier` status is normal when an Ethernet cable is not plugged into the interface. If the man:ifconfig[8] output had shown something similar to the next output it would indicate the interface has not been configured: [.programlisting] .... em0: flags=8822 metric 0 mtu 1500 options=481249b ether 00:1f:16:0f:27:5a media: Ethernet autoselect status: no carrier nd6 options=29 .... [[config-static-ip-v4]] === Configuring Static IPv4 Address This section provides a guide to configuring a static IPv4 address on a FreeBSD system. The network interface card configuration can be performed from the command line with man:ifconfig[8] but will not persist after a reboot unless the configuration is also added to [.filename]#/etc/rc.conf#. [NOTE] ==== If the network was configured during installation by man:bsdinstall[8], some entries for the network interface card (NICs) may be already present. Double check [.filename]#/etc/rc.conf# before executing man:sysrc[8]. ==== The IP address can be set executing the following command: [source,shell] .... # ifconfig em0 inet 192.168.1.150/24 .... To make the change persist across reboots execute the following command: [source,shell] .... # sysrc ifconfig_em0="inet 192.168.1.150 netmask 255.255.255.0" .... Add the default router executing the following command: [source,shell] .... # sysrc defaultrouter="192.168.1.1" .... Add the DNS records to [.filename]#/etc/resolv.conf#: [.programlisting] .... nameserver 8.8.8.8 nameserver 8.8.4.4 .... Then restart `netif` and `routing` executing the following command: [source,shell] .... # service netif restart && service routing restart .... The connection can be tested using man:ping[8]: [source,shell] .... % ping -c2 www.FreeBSD.org .... The output should be similar to the following: [.programlisting] .... PING web.geo.FreeBSD.org (147.28.184.45): 56 data bytes 64 bytes from 147.28.184.45: icmp_seq=0 ttl=51 time=55.173 ms 64 bytes from 147.28.184.45: icmp_seq=1 ttl=51 time=53.093 ms --- web.geo.FreeBSD.org ping statistics --- 2 packets transmitted, 2 packets received, 0.0% packet loss round-trip min/avg/max/stddev = 53.093/54.133/55.173/1.040 ms .... [[config-dynamic-ip-v4]] === Configuring Dynamic IPv4 Address If the network has a DHCP server, it is very easy to configure the network interface to use DHCP. FreeBSD uses man:dhclient[8] as the DHCP client. man:dhclient[8] will automatically provide the IP, the netmask and the default router. To make the interface work with DHCP execute the following command: [source,shell] .... # sysrc ifconfig_em0="DHCP" .... man:dhclient[8] can be used manually by running the following command: [source,shell] .... # dhclient em0 .... The output should be similar to the following: [.programlisting] .... DHCPREQUEST on em0 to 255.255.255.255 port 67 DHCPACK from 192.168.1.1 unknown dhcp option value 0x7d bound to 192.168.1.19 -- renewal in 43200 seconds. .... In this way it can be verified that the address assignment using DHCP works correctly. [TIP] ==== man:dhclient[8] client can be started in background. This can cause trouble with applications depending on a working network, but it will provide a faster startup in many cases. To execute man:dhclient[8] in background execute the following command: [source,shell] .... # sysrc background_dhclient="YES" .... ==== Then restart `netif` executing the following command: [source,shell] .... # service netif restart .... The connection can be tested using man:ping[8]: [source,shell] .... % ping -c2 www.FreeBSD.org .... The output should be similar to the following: [.programlisting] .... PING web.geo.FreeBSD.org (147.28.184.45): 56 data bytes 64 bytes from 147.28.184.45: icmp_seq=0 ttl=51 time=55.173 ms 64 bytes from 147.28.184.45: icmp_seq=1 ttl=51 time=53.093 ms --- web.geo.FreeBSD.org ping statistics --- 2 packets transmitted, 2 packets received, 0.0% packet loss round-trip min/avg/max/stddev = 53.093/54.133/55.173/1.040 ms .... [[network-ipv6]] === IPv6 IPv6 is the new version of the well-known IP protocol, also known as IPv4. IPv6 provides several advantages over IPv4 as well as many new features: * Its 128-bit address space allows for 340,282,366,920,938,463,463,374,607,431,768,211,456 addresses. This addresses the IPv4 address shortage and eventual IPv4 address exhaustion. * Routers only store network aggregation addresses in their routing tables, thus reducing the average space of a routing table to 8192 entries. This addresses the scalability issues associated with IPv4, which required every allocated block of IPv4 addresses to be exchanged between Internet routers, causing their routing tables to become too large to allow efficient routing. * Address autoconfiguration (http://www.ietf.org/rfc/rfc2462.txt[RFC2462]). * Mandatory multicast addresses. * Built-in IPsec (IP security). * Simplified header structure. * Support for mobile IP. * IPv6-to-IPv4 transition mechanisms. FreeBSD includes the http://www.kame.net/[KAME project] IPv6 reference implementation and comes with everything needed to use IPv6. This section focuses on getting IPv6 configured and running. There are three different types of IPv6 addresses: Unicast:: A packet sent to a unicast address arrives at the interface belonging to the address. Anycast:: These addresses are syntactically indistinguishable from unicast addresses but they address a group of interfaces. The packet destined for an anycast address will arrive at the nearest router interface. Anycast addresses are only used by routers. Multicast:: These addresses identify a group of interfaces. A packet destined for a multicast address will arrive at all interfaces belonging to the multicast group. The IPv4 broadcast address, usually `xxx.xxx.xxx.255`, is expressed by multicast addresses in IPv6. When reading an IPv6 address, the canonical form is represented as `x:x:x:x:x:x:x:x`, where each `x` represents a 16 bit hex value. An example is `FEBC:A574:382B:23C1:AA49:4592:4EFE:9982`. Often, an address will have long substrings of all zeros. A `::` (double colon) can be used to replace one substring per address. Also, up to three leading ``0``s per hex value can be omitted. For example, `fe80::1` corresponds to the canonical form `fe80:0000:0000:0000:0000:0000:0000:0001`. A third form is to write the last 32 bits using the well known IPv4 notation. For example, `2002::10.0.0.1` corresponds to the hexadecimal canonical representation `2002:0000:0000:0000:0000:0000:0a00:0001`, which in turn is equivalent to `2002::a00:1`. To view a FreeBSD system's IPv6 address execute the following command: [source,shell] .... # ifconfig .... The output should be similar to the following: [.programlisting] .... em0: flags=8863 metric 0 mtu 1500 options=481249b ether 00:1f:16:0f:27:5a inet 192.168.1.150 netmask 0xffffff00 broadcast 192.168.1.255 inet6 fe80::21f:16ff:fe0f:275a%em0 prefixlen 64 scopeid 0x1 media: Ethernet autoselect (1000baseT ) status: active nd6 options=23 .... In this example, the `em0` interface is using `fe80::21f:16ff:fe0f:275a%em0`, an auto-configured link-local address which was automatically generated from the MAC address. Some IPv6 addresses are reserved. A list of reserved addresses can be checked in the following table: [[reservedip6]] .Example IPv6 Reserved Addresses [cols="1,1,1,1", frame="none", options="header"] |=== | IPv6 address | Prefixlength (Bits) | Description | Notes |`::` |128 bits |unspecified |Equivalent to `0.0.0.0` in IPv4. |`::1` |128 bits |loopback address |Equivalent to `127.0.0.1` in IPv4. |`::00:xx:xx:xx:xx` |96 bits |embedded IPv4 |The lower 32 bits are the compatible IPv4 address. |`::ff:xx:xx:xx:xx` |96 bits |IPv4 mapped IPv6 address |The lower 32 bits are the IPv4 address for hosts which do not support IPv6. |`fe80::/10` |10 bits |link-local |Equivalent to 169.254.0.0/16 in IPv4. |`fc00::/7` |7 bits |unique-local |Unique local addresses are intended for local communication and are only routable within a set of cooperating sites. |`ff00::` |8 bits |multicast | |``2000::-3fff::`` |3 bits |global unicast |All global unicast addresses are assigned from this pool. The first 3 bits are `001`. |=== For further information on the structure of IPv6 addresses, refer to http://www.ietf.org/rfc/rfc3513.txt[RFC3513]. [[config-static-ip-v6]] === Configuring Static IPv6 Address To configure a FreeBSD system as an IPv6 client with a static IPv6 address it is necessary to set the IPv6 address. Execute the following commands to meet the requirements: [source,shell] .... # sysrc ifconfig_em0_ipv6="inet6 2001:db8:4672:6565:2026:5043:2d42:5344 prefixlen 64" .... To assign a default router, specify its address executing the following command: [source,shell] .... # sysrc ipv6_defaultrouter="2001:db8:4672:6565::1" .... [[config-dynamic-ip-v6]] === Configuring Dynamic IPv6 Address If the network has a DHCP server, it is very easy to configure the network interface to use DHCP. man:dhclient[8] will provide automatically the IP, the netmask and the default router. -To make the interface works with DHCP execute the following command: +To make the interface work with DHCP execute the following command: [source,shell] .... # sysrc ifconfig_em0_ipv6="inet6 accept_rtadv" # sysrc rtsold_enable="YES" .... === Router Advertisement and Host Auto Configuration This section demonstrates how to setup man:rtadvd[8] on an IPv6 router to advertise the IPv6 network prefix and default route. To enable man:rtadvd[8], execute the following command: [source,shell] .... # sysrc rtadvd_enable="YES" .... It is important to specify the interface on which to do IPv6 router advertisement. For example, to tell man:rtadvd[8] to use `em0`: [source,shell] .... # sysrc rtadvd_interfaces="em0" .... Next, create the configuration file, [.filename]#/etc/rtadvd.conf# as seen in this example: [.programlisting] .... em0:\ :addrs#1:addr="2001:db8:1f11:246::":prefixlen#64:tc=ether: .... Replace `em0` with the interface to be used and `2001:db8:1f11:246::` with the prefix of the allocation. For a dedicated `/64` subnet, nothing else needs to be changed. Otherwise, change the `prefixlen#` to the correct value. === IPv6 and IPv4 Address mapping When IPv6 is enabled on a server, there may be a need to enable IPv4 mapped IPv6 address communication. This compatibility option allows for IPv4 addresses to be represented as IPv6 addresses. Permitting IPv6 applications to communicate with IPv4 and vice versa may be a security issue. This option may not be required in most cases and is available only for compatibility. This option will allow IPv6-only applications to work with IPv4 in a dual stack environment. This is most useful for third party applications which may not support an IPv6-only environment. To enable this feature execute the following command: [source,shell] .... # sysrc ipv6_ipv4mapping="YES" .... [[network-wireless]] == Wireless Networks Most wireless networks are based on the link:https://en.wikipedia.org/wiki/IEEE_802.11[IEEE(R) 802.11 standards]. FreeBSD supports networks that operate using link:https://en.wikipedia.org/wiki/IEEE_802.11a-1999[802.11a], link:https://en.wikipedia.org/wiki/IEEE_802.11b-1999[802.11b], link:https://en.wikipedia.org/wiki/IEEE_802.11g-2003[802.11g] and link:https://en.wikipedia.org/wiki/IEEE_802.11n-2009[802.11n]. [NOTE] ==== link:https://en.wikipedia.org/wiki/IEEE_802.11ac-2013[802.11ac] support on FreeBSD is currently under development. ==== A basic wireless network consists of multiple stations communicating with radios that broadcast in either the 2.4GHz or 5GHz band, though this varies according to the locale and is also changing to enable communication in the 2.3GHz and 4.9GHz ranges. There are three basic steps to configure a wireless network: 1. Scan and select an access point 2. Authenticate the station 3. Configure an IP address or use DHCP. The following sections discuss each step. [[network-wireless-quick-start]] === Quick Start to Connect to a Wireless Network Connecting FreeBSD to an existing wireless network is a very common situation. This procedure shows the steps required: * The first step will be to obtain the SSID (Service Set Identifier) and PSK (Pre-Shared Key) for the wireless network from the network administrator. * The second step will be to add an entry for this network to [.filename]#/etc/wpa_supplicant.conf#. If the file does not exist, create it: [.programlisting] .... network={ ssid="myssid" <.> psk="mypsk" <.> } .... <.> Is the SSID of the wireless network. Replace it with the name of the wireless network. <.> Is the PSK of the wireless network. Replace it with the password of the wireless network. * The third step will be to add the network entry to configure the network on startup: [source,shell] .... # sysrc wlans_iwn0="wlan0" # sysrc ifconfig_wlan0="WPA DHCP" .... * And the last step will be the restart `netif` service executing the following command: [source,shell] .... # service netif restart .... [[basic-wireless-configuration]] === Basic Wireless Configuration The first step will be to configure the wireless network card to an interface. To find out what wireless network cards are in the system check the section <>. [source,shell] .... # ifconfig wlan0 create wlandevice iwm0 .... To make the change persist across reboots execute the following command: [source,shell] .... # sysrc wlans_iwn0="wlan0" .... [NOTE] ==== Since the regulatory situation is different in various parts of the world, it is necessary to correctly set the domains that apply to your location to have the correct information about what channels can be used. The available region definitions can be found in [.filename]#/etc/regdomain.xml#. To set the data at runtime, use `ifconfig`: [source,shell] .... # ifconfig wlan0 regdomain etsi2 country AT .... To persist the settings, add it to [.filename]#/etc/rc.conf#: [source,shell] .... # sysrc create_args_wlan0="country AT regdomain etsi2" .... ==== [[scan-wireless-networks]] === Scan Wireless Networks Available wireless networks can be scanned using man:ifconfig[8]. To list the wireless networks execute the following command: [source,shell] .... # ifconfig wlan0 up list scan .... The output should be similar to the following: [.programlisting] .... SSID/MESH ID BSSID CHAN RATE S:N INT CAPS FreeBSD e8:d1:1b:1b:58:ae 1 54M -47:-96 100 EP RSN BSSLOAD HTCAP WPS WME NetBSD d4:b9:2f:35:fe:08 1 54M -80:-96 100 EP RSN BSSLOAD HTCAP WPS WME OpenBSD fc:40:09:c6:31:bd 36 54M -94:-96 100 EPS VHTPWRENV APCHANREP RSN WPS BSSLOAD HTCAP VHTCAP VHTOPMODE WME GNU-Linux dc:f8:b9:a0:a8:e0 44 54M -95:-96 100 EP WPA RSN WPS HTCAP VHTCAP VHTOPMODE WME VHTPWRENV Windows 44:48:b9:b3:c3:ff 44 54M -84:-96 100 EP BSSLOAD VHTPWRENV HTCAP WME RSN VHTCAP VHTOPMODE WPS MacOS 46:48:b9:b3:c3:ff 44 54M -84:-96 100 EP BSSLOAD VHTPWRENV HTCAP WME RSN VHTCAP VHTOPMODE WPS .... . SSID/MESH ID identifies the name of the network. . BSSID identifies the MAC address of the access point. . CAPS field identifies the type of each network and the capabilities of the stations operating there (see the definition of `list scan` in man:ifconfig[8] for more details). [[wireless-authentication]] === Connection and Authentication to a Wireless Network Once a wireless network has been selected from the list of scanned networks, it is necessary to perform the connection and the authentication. In the vast majority of wireless networks, authentication is done with a password configured in the router. Other schemes require cryptographic handshakes to be completed before data traffic can flow, either using pre-shared keys or secrets, or more complex schemes that involve backend services such as RADIUS. [[authenticate-wpa2-wpa-personal]] ==== Authenticate with WPA2/WPA/Personal The authentication process in a wireless network is managed by man:wpa_supplicant[8]. The man:wpa_supplicant[8] configuration will be made in the [.filename]#/etc/wpa_supplicant.conf# file. For more information, see man:wpa_supplicant.conf[5]. Once the scanning of the wireless networks has been carried out, a network has been chosen and have the password (PSK), that information will be added to the file [.filename]#/etc/wpa_supplicant.conf# as in the following example: [.programlisting] .... network={ scan_ssid=1 <.> ssid="FreeBSD" <.> psk="12345678" <.> } .... <.> SSID scan technique. Only need to use this option if the network is hidden. <.> Network name. <.> Passwork of the wireless network. The next step will be to configure the wireless connection in the file [.filename]#/etc/rc.conf#. To use a static address it will be necessary to execute the following command: [source,shell] .... # sysrc ifconfig_wlan0="inet 192.168.1.20 netmask 255.255.255.0" .... To use a dynamic address it will be necessary to execute the following command: [source,shell] .... # ifconfig_wlan0="WPA DHCP" .... Then restart the network executing the following command: [source,shell] .... # service netif restart .... [NOTE] ==== More information on how to perform more advanced methods of authentication can be obtained at crossref:advanced-networking[network-advanced-wireless,"Wireless Advanced Authentication"]. ==== [[authenticate-open-networks]] ==== Authenticate with Open Networks [TIP] ==== It is important that the user is *very* careful when connecting to open networks without any kind of authentication. ==== Once the wireless network scan is done and the SSID of the wireless network is selected, execute the following command: [source,shell] .... # ifconfig wlan0 ssid SSID .... And then execute man:dhclient[8] to get the address configured: [source,shell] .... # dhclient wlan0 .... === Using Both Wired and Wireless Connections A wired connection provides better performance and reliability, while a wireless connection provides flexibility and mobility. Laptop users typically want to roam seamlessly between the two types of connections. On FreeBSD, it is possible to combine two or even more network interfaces together in a "failover" fashion. This type of configuration uses the most preferred and available connection from a group of network interfaces, and the operating system switches automatically when the link state changes. Link aggregation and failover is covered in crossref:advanced-networking[network-aggregation,"Link Aggregation and Failover"] and an example for using both wired and wireless connections is provided at crossref:advanced-networking[networking-lagg-wired-and-wireless,"Failover Mode Between Ethernet and Wireless Interfaces"]. [[hostname]] == Hostname The hostname represents the fully qualified domain name (FQDN) of the host on the network. [TIP] ==== If no hostname has been set for the host FreeBSD will assign the value `Amnesiac`. ==== [[get-hostname]] === Check The Current Hostname man:hostname[1] can be used to check the current hostname: [source,shell] .... $ hostname .... The output should be similar to the following: [.programlisting] .... freebsdhostname.example.com .... [[change-hostname]] === Change Hostname To change the hostname of the host and persist it across reboots execute the following command: [source,shell] .... # sysrc hostname="freebsdhostname.example.com" .... [[dns]] == DNS The DNS could be understanded as a link:https://en.wikipedia.org/wiki/Telephone_directory[telephone directory] in which an IP is identified to a hostname and vice versa. There are three files that handle how a FreeBSD system interact with the DNS. These three files are man:hosts[5], man:resolv.conf[5] and man:nsswitch.conf[5] Unless otherwise stated in the [.filename]#/etc/nsswitch.conf# file, FreeBSD will look at the addresses in the [.filename]#/etc/hosts# file and then the DNS information in the [.filename]#/etc/resolv.conf# file. [NOTE] ==== The man:nsswitch.conf[5] file specifies how the nsdispatch (name-service switch dispatcher) should operate. By default, the hosts section of the [.filename]#/etc/nsswitch.conf# file will be as follows: [.programlisting] .... hosts: files dns .... For example, in case of using the man:nscd[8] service. The order of preference could be changed by leaving the line as follows: [.programlisting] .... hosts: files cache dns .... ==== [[local-addresses]] === Local addresses The [.filename]#/etc/hosts# file is a simple text database who provide host name to IP address mappings. Entries for local computers connected via a LAN can be added to this file for simplistic naming purposes instead of setting up a DNS server. Additionally, [.filename]#/etc/hosts# can be used to provide a local record of Internet names, reducing the need to query external DNS servers for commonly accessed names. For example, in the case of having a local instance of package:www/gitlab-ce[] in a local environment, it could be added as follows to the file [.filename]#/etc/hosts#: [.programlisting] .... 192.168.1.150 git.example.com git .... [[configuring-nameserver]] === Configuring the Nameserver How a FreeBSD system accesses the Internet Domain Name System (DNS) is controlled by man:resolv.conf[5]. The most common entries to [.filename]#/etc/resolv.conf# are: [.informaltable] [cols="1,1", frame="none"] |=== |`nameserver` |The IP address of a name server the resolver should query. The servers are queried in the order listed with a maximum of three. |`search` |Search list for hostname lookup. This is normally determined by the domain of the local hostname. |`domain` |The local domain name. |=== A typical [.filename]#/etc/resolv.conf# looks like this: [.programlisting] .... search example.com nameserver 147.11.1.11 nameserver 147.11.100.30 .... [NOTE] ==== Only one of the `search` and `domain` options should be used. ==== When using DHCP, man:dhclient[8] usually rewrites [.filename]#/etc/resolv.conf# with information received from the DHCP server. [TIP] ==== If the machine in which the configuration is being made is *not* a DNS server, man:local-unbound[8] can be used to improve DNS lookup performance. To enable it at boot time execute the following command: [source,shell] .... # sysrc local_unbound_enable="YES" .... To start the man:local-unbound[8] service execute the following command: [source,shell] .... # service local_unbound start .... ==== [[troubleshooting]] == Troubleshooting When troubleshooting hardware and software configurations, check the simple things first. * Is the network cable plugged in? * Are the network services properly configured? * Is the firewall configured correctly? * Is the NIC supported by FreeBSD? * Is the router working correctly? [TIP] ==== Before sending a bug report, always check the Hardware Notes in the link:https://www.freebsd.org/releases/[FreeBSD release page], update the version of FreeBSD to the latest STABLE version, check the mailing list archives, and search the Internet. ==== [[wired-troubleshooting]] === Troubleshooting in Wired Networks If the card works, yet performance is poor, read through man:tuning[7]. Also, check the network configuration as incorrect network settings can cause slow connections. `No route to host` messages occur if the system is unable to route a packet to the destination host. This can happen if no default route is specified or if a cable is unplugged. Check the output of `netstat -rn` and make sure there is a valid route to the host. If there is not, read crossref:advanced-networking[network-routing,"Gateways and Routes"]. `ping: sendto: Permission denied` error messages are often caused by a misconfigured firewall. If a firewall is enabled on FreeBSD but no rules have been defined, the default policy is to deny all traffic, even man:ping[8]. Refer to crossref:firewalls[firewalls,Firewalls] for more information. [[wireless-troubleshooting]] === Troubleshooting in Wireless Networks This section describes a number of steps to help troubleshoot common wireless networking problems. * If the access point is not listed when scanning, check that the configuration has not limited the wireless device to a limited set of channels. * If the device cannot associate with an access point, verify that the configuration matches the settings on the access point. This includes the authentication scheme and any security protocols. Simplify the configuration as much as possible. If using a security protocol such as WPA2 or WPA, configure the access point for open authentication and no security to see if traffic will pass. * Once the system can associate with the access point, diagnose the network configuration using tools like man:ping[8]. * There are many lower-level debugging tools. Debugging messages can be enabled in the 802.11 protocol support layer using man:wlandebug[8].