diff --git a/documentation/content/de/books/handbook/bsdinstall/_index.adoc b/documentation/content/de/books/handbook/bsdinstall/_index.adoc index bd17d48aed..3dd51912c0 100644 --- a/documentation/content/de/books/handbook/bsdinstall/_index.adoc +++ b/documentation/content/de/books/handbook/bsdinstall/_index.adoc @@ -1,1064 +1,1067 @@ --- title: Kapitel 2. FreeBSD installieren part: Teil I. Erste Schritte prev: books/handbook/introduction next: books/handbook/basics showBookMenu: true weight: 4 path: "/books/handbook/bsdinstall/" --- [[bsdinstall]] = FreeBSD installieren :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 2 :partnums: :source-highlighter: rouge :experimental: :images-path: books/handbook/bsdinstall/ 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::[] [[bsdinstall-synopsis]] == Übersicht Es gibt verschiedene Möglichkeiten, FreeBSD zu installieren, abhängig von der Einsatzumgebung. Dazu gehören: * Abbilder von virtuellen Maschinen, die Sie herunterladen und in einer virtuellen Umgebung einsetzen können. Diese Abbilder können von der https://www.freebsd.org/where/[FreeBSD Downloadseite] heruntergeladen werden. Es gibt Abbilder für KVM ("qcow2"), VMWare ("vmdk"), Hyper-V ("vhd"), sowie Raw-Device Abbilder, die durchgängig unterstützt werden. Dies sind keine Installationsabbilder, sondern vorkonfigurierte ("bereits installierte") Instanzen, die sofort gestartet und konfiguriert werden können. * Abbilder von virtuellen Maschinen, die auf Amazon's https://aws.amazon.com/marketplace/pp/B07L6QV354[AWS Marketplace], https://azuremarketplace.microsoft.com/en-us/marketplace/apps?search=freebsd&page=1[Microsoft Azure Marketplace] und https://console.cloud.google.com/launcher/details/freebsd-cloud/freebsd-12[Google Cloud Platform] verfügbar sind, um auf den jeweiligen Hosting-Diensten ausgeführt zu werden. Weitere Informationen zur Bereitstellung von FreeBSD auf Azure finden Sie im entsprechenden Kapitel der https://docs.microsoft.com/en-us/azure/virtual-machines/linux/freebsd-intro-on-azure[ Azure Dokumentation]. * SD-Karten Abbilder für eingebettete Systeme wie den Raspberry Pi oder BeagleBone Black. Diese Abbilder können von der https://www.freebsd.org/where/[ FreeBSD Downloadseite] heruntergeladen werden. Die Dateien müssen unkomprimiert und als Raw-Image auf eine SD-Karte geschrieben werden, von der das System dann booten wird. * Installationsabbilder, um FreeBSD auf einer Festplatte für die üblichen Desktop-, Laptop- oder Serversysteme zu installieren. Der Rest dieses Kapitels beschreibt den vierten Fall und erklärt, wie man FreeBSD mit dem textbasierten Installationsprogramm bsdinstall installiert. Die Installationsanweisungen in diesem Kapitel gelten für die i386(TM)- und AMD64-Architekturen. Gegebenenfalls werden spezifische Anweisungen für andere Plattformen erwähnt. Möglicherweise gibt es auch geringfügige Unterschiede zwischen dem Installationsprogramm und dem, was hier gezeigt wird. Sie sollten dieses Kapitel daher als eine Art Wegweiser und nicht als exakte Anleitung betrachten. [NOTE] ==== Benutzer, die es vorziehen, FreeBSD mit einem graphischen Installationsprogramm zu installieren, sind vielleicht an https://www.furybsd.org[FuryBSD], https://ghostbsd.org[GhostBSD] oder https://www.midnightbsd.org[MidnightBSD] interessiert. ==== Nachdem Sie dieses Kapitel gelesen haben, werden Sie wissen: * welche Mindestanforderungen an die Hardware gestellt werden und welche Architekturen FreeBSD unterstützt. * wie man FreeBSD Installationsmedien erstellt. * wie man bsdinstall startet. * welche Fragen bsdinstall stellt, was sie bedeuten und wie man diese beantwortet. * wie Sie Fehler bei der Installation beheben. * wie Sie eine Live-Version von FreeBSD ausprobieren können, bevor Sie die Installation starten. Bevor Sie dieses Kapitel lesen, sollten Sie: * Die Liste von unterstützter Hardware lesen, die mit der zu installierenden Version von FreeBSD ausgeliefert wird, um sicherzustellen, dass die Hardware auch unterstützt wird. [[bsdinstall-hardware]] == Minimale Hardwareanforderungen Die Hardwareanforderungen zur Installation von FreeBSD variieren mit der Architektur. Hardwarearchitekturen und von FreeBSD unterstützte Geräte sind auf der Seite link:https://www.FreeBSD.org/releases/[FreeBSD Release Informationen] aufgelistet. Die link:https://www.FreeBSD.org/where/[FreeBSD Download Seite] enthält Informationen zur Auswahl des richtigen Abbilds für verschiedene Architekturen. Für die Installation von FreeBSD sind mindestens 96 MB RAM und 1.5 GB freier Festplattenspeicher erforderlich. Allerdings ist eine solch geringe Menge an Arbeitsspeicher und Speicherplatz nur für spezifische Anwendungen ausreichend, beispielsweise für Embedded-Geräte. Desktop-Systeme benötigen weitaus mehr Ressourcen. 2-4 GB RAM und mindestens 8 GB Speicherplatz sind ein guter Anfang. Dies sind die Anforderungen an den Prozessor für jede Architektur: amd64:: Dies ist die gängigste Art von Prozessor für Desktop- und Laptop-Systeme. Andere Anbieter nennen diese Architektur auch x86-64. + Beispiele für amd64-kompatible Prozessoren umfassen: AMD Athlon(TM)64, AMD Opteron(TM), multi-core Intel(R) Xeon(TM) und Intel(R) Core(TM) 2 sowie neuere Prozessoren. i386:: Ältere Desktop- und Laptop-Systeme verwenden oft die 32-Bit x86-Architektur. + Fast alle i386-kompatiblen Prozessoren mit einer Floating-Point-Einheit werden unterstützt. Alle Intel(R)-Prozessoren 486 oder neuer werden unterstützt. + FreeBSD nutzt die Physical Adress Extensions (PAE), falls die CPU diese Funktion unterstützt. Wenn PAE im Kernel aktiviert ist, wird Speicher über 4 GB vom Kernel erkannt und kann von System verwendet werden. PAE schränkt allerdings auch die Gerätetreiber und anderen Komponenten von FreeBSD ein. powerpc:: Alle New Word ROM Apple(R) Mac(R)-Systeme mit integriertem USB werden unterstützt. SMP wird auf Maschinen mit mehreren CPUs unterstützt. + Ein 32-Bit Kernel kann jedoch nur die ersten 2 GB RAM verwenden. sparc64:: Systeme, die von FreeBSD/sparc64 unterstützt werden, sind auf der link:https://www.FreeBSD.org/platforms/sparc/[FreeBSD/sparc64-Projektseite] aufgelistet. + SMP wird auf allen Systemen mit mehr als einem Prozessor unterstützt. Eine dedizierte Platte wird benötigt, da es nicht möglich ist, eine Platte mit einem anderen Betriebssystem zur gleichen Zeit zu teilen. [[bsdinstall-pre]] == Vor der Installation Wenn das System die Mindestanforderungen für die Installation von FreeBSD erfüllt, sollte die Installationsdatei heruntergeladen und die Installationsmedien vorbereitet werden. Bevor Sie dies tun, prüfen Sie mit Hilfe dieser Checkliste, ob das System für die Installation bereit ist: [.procedure] . *Sichern Sie wichtige Daten* + Erstellen Sie _immer_ eine Sicherung aller wichtigen Daten, _bevor_ Sie ein Betriebssystem installieren. Speichern Sie die Daten jedoch nicht auf dem System, auf dem das Betriebssystem installiert wird, sondern nutzen Sie einen Wechseldatenträger, wie beispielsweise ein USB-Laufwerk, oder sichern Sie auf einem anderen System im Netzwerk, oder nutzen einen Online-Backup-Dienst. Überprüfen Sie die Sicherungen, bevor Sie mit der Installation beginnen. Sobald das Installationsprogramm die Festplatte des Systems formatiert, gehen alle gespeicherten Daten unwiderruflich verloren. . *Den Installationsort von FreeBSD festlegen* + Falls FreeBSD das einzige installierte Betriebssystem sein wird, kann dieser Schritt übersprungen werden. Sollte FreeBSD allerdings die Platte mit anderen Betriebssystemen teilen, müssen Sie entscheiden, welche Platte oder Partition für FreeBSD verwendet werden soll. + Für die Architekturen i386 und amd64 können die Platten in mehrere Partitionen aufgeteilt werden. Dazu stehen Ihnen zwei Partitionsschemas zur Verfügung. Traditionell enthält ein _Master Boot Record_ (MBR) eine Partitionstabelle, welche bis zu vier _primäre Partitionen_ aufnehmen kann. Aus historischen Gründen werden diese primären Partitionen in FreeBSD _slices_ genannt. Eine Begrenzung von nur vier Partitionen ist für große Platten sehr beschränkt, so dass eine dieser primären Partitionen als _erweiterte Partition_ eingesetzt wird. Mehrere _logische Partitionen_ können dann innerhalb der erweiterten Partition angelegt werden. Die _GUID-Partitionstabelle_ (GPT) ist eine neuere und einfachere Methode zur Partition einer Festplatte. Geläufige GPT-Implementierungen erlauben bis zu 128 Partitionen pro Platte, was die Notwendigkeit von logischen Partitionen eliminiert. + FreeBSDs Standard-Bootloader benötigt entweder eine primäre oder eine GPT-Partition. Wenn alle primären oder GPT-Partitionen bereits in Verwendung sind, muss eine davon für FreeBSD zur Verfügung gestellt werden. Benutzen Sie ein Werkzeug zur Veränderung der Partitionsgrößen, wenn Sie eine Partition erstellen möchten, ohne dabei vorhandene Daten zu löschen. Den freigegebenen Platz können Sie dann für die Installation verwenden. + Eine Vielzahl freier und kommerzieller Werkzeuge zur Veränderung der Partitionsgrößen finden Sie unter http://en.wikipedia.org/wiki/List_of_disk_partitioning_software[ http://en.wikipedia.org/wiki/List_of_disk_partitioning_software]. GParted Live (http://gparted.sourceforge.net/livecd.php[http://gparted.sourceforge.net/livecd.php]) ist eine freie Live-CD, die den GParted-Partitionseditor enthält. GParted ist auch in einer Vielzahl von anderen Linux Live-CD Distributionen enthalten. + [WARNING] ==== Bei richtiger Anwendung können Werkzeuge zur Veränderung von Partitionsgrößen auf sichere Art und Weise Platz für eine neue Partition schaffen. Erstellen Sie trotzdem eine Vollsicherung und überprüfen Sie deren Integrität bevor Sie die Partitionen auf der Platte verändern. ==== + Festplattenpartitionen, die unterschiedliche Betriebssysteme enthalten, ermöglichen es, jeweils eines dieser Systeme zu verwenden. Eine alternative Möglichkeit, mehrere Betriebssysteme gleichzeitig einzusetzen, ohne dabei Partitionen ändern zu müssen, wird im crossref:virtualization[virtualization,Virtualisierung] behandelt. . *Netzwerkparameter ermitteln* + Manche FreeBSD Installationsarten benötigen eine Netzwerkverbindung, um Installationsdateien herunter zu laden. Nach jeder Installation bietet das Installationsprogramm die Möglichkeit, die Netzwerkschnittstellen des Systems zu konfigurieren. + Steht im Netzwerk ein DHCP-Server zur Verfügung, wird dieser im Allgemeinen verwendet, um automatisch Netzwerkeinstellungen vorzunehmen. Falls DHCP nicht verfügbar ist, müssen die folgenden Netzwerkeinstellungen beim lokalen Netzwerkadministrator oder Provider erfragt werden: [[bsdinstall-collect-network-information]] .. IP-Adresse .. Subnetz-Maske .. IP-Adresse des Default-Gateway .. Domänenname des Netzwerks .. IP-Adressen der DNS-Server im Netzwerk . *Lesen Sie die FreeBSD-Errata* + Obwohl das FreeBSD Projekt sich bemüht, jede veröffentlichte Version von FreeBSD so stabil wie möglich zu machen, können sich doch gelegentlich Fehler in den Veröffentlichungsprozess einschleichen. In sehr seltenen Fällen betreffen diese Fehler den Installationsvorgang. Wenn diese Probleme entdeckt und behoben sind, werden dazu Hinweise in der FreeBSD Errata (link:https://www.FreeBSD.org/releases/{rel121-current}r/errata/[https://www.freebsd.org/releases/{rel121-current}r/errata/]) auf der FreeBSD Webseite veröffentlicht. Prüfen Sie die Errata vor der Installation, um sicherzustellen, dass es keine Probleme gibt, welche die Installation betreffen. + Informationen und Errata für all diese Veröffentlichungen finden Sie unter den Release Informationen auf der FreeBSD Webseite (link:https://www.FreeBSD.org/releases/[https://www.freebsd.org/releases/]). [[bsdinstall-installation-media]] === Die Installationsmedien vorbereiten Das FreeBSD-Installationsprogramm ist keine Anwendung, das aus einem anderen Betriebssystem heraus gestartet werden kann. Laden Sie stattdessen eine Installationsdatei für FreeBSD herunter und brennen Sie den Dateityp auf einen entsprechenden Datenträger (CD, DVD, oder USB). Starten Sie dann das System mit diesem Datenträger. Die FreeBSD-Installationsmedien sind unter link:https://www.FreeBSD.org/where/[www.freebsd.org/where/] verfügbar. Der Name der Installationsdatei enthält die Version von FreeBSD, die Architektur sowie den Dateityp. Wenn Sie beispielsweise FreeBSD 12.1 auf einem amd64-System von DVD installieren wollen, laden Sie [.filename]#FreeBSD-12.1-RELEASE-amd64-dvd1.iso# und brennen Sie die Datei auf eine DVD. Starten Sie dann das System mit dieser DVD. Die Installationsdateien stehen in verschiedenen Formaten zur Verfügung und variieren je nach Rechnerarchitektur und Medientyp. [[bsdinstall-installation-media-uefi]] Für Rechner, die mit UEFI (Unified Extensible Firmware Interface) booten, stehen zusätzliche Installationsdateien zur Verfügung. Die Namen dieser Dateien enthalten die Zeichenkette [.filename]#uefi#. Dateitypen: * `-bootonly.iso`: Dies ist die kleinste Installation, die lediglich das Installationsprogramm enthält. Hierzu ist während der Installation eine funktionierende Internetverbindung erforderlich, da das Installationsprogramm die benötigen Dateien für die FreeBSD-Installation herunter laden muss. Diese Datei sollte mit einem CD-Brennprogramm auf CD gebrannt werden. * `-disc1.iso`: Diese Datei enthält alle benötigten Dateien für eine FreeBSD-Installation, den Quellcode und die Ports-Sammlung. Die Datei sollte mit einem CD-Brennprogramm auf CD gebrannt werden. * `-dvd1.iso`: Diese Datei enthält alle benötigen Dateien für eine FreeBSD-Installation, den Quellcode und die Ports-Sammlung. Darüber hinaus enthält sie eine Reihe von beliebten Binärpaketen zur Installation eines Window-Managers, sodass Sie ein komplettes System installieren können, ohne dass Sie eine Verbindung zum Internet benötigen. Die Datei sollte mit einem DVD-Brennprogramm auf eine DVD gebrannt werden. * `-memstick.img`: Diese Datei enthält alle benötigten Dateien für eine FreeBSD-Installation, den Quellcode und die Ports-Sammlung. Die Datei sollte mit den nachstehenden Anweisungen auf einen USB-Stick geschrieben werden. * `-mini-memstick.img`: Diese Datei enthält, wie `-bootonly.iso`, keine Installationsdateien, sondern lädt diese bei Bedarf nach. Während der Installation wird eine funktionierende Internetverbindung benötigt. Schreiben Sie die Datei, wie in <> beschrieben, auf einen USB-Stick. Nachdem Sie die Datei heruntergeladen haben, laden Sie [.filename]#CHECKSUM.SHA256# aus dem gleichen Verzeichnis herunter. Berechnen Sie dann die _Prüfsumme_ für die Datei. FreeBSD bietet hierfür man:sha256[1], das Sie als `sha256 _Dateiname_` aufrufen können. Andere Betriebssysteme haben ähnliche Programme. Vergleichen Sie die berechnete Prüfsumme mit der in [.filename]#CHECKSUM.SHA256#. Die beiden Prüfsummen müssen übereinstimmen, ansonsten ist die Datei beschädigt und muss erneut heruntergeladen werden. [[bsdinstall-usb]] ==== Eine Installationsdatei auf einen USB-Stick schreiben Die [.filename]#\*.img#-Datei ist ein komplettes _Abbild_ (engl. Image) des späteren USB-Sticks. Die Datei kann _nicht_ auf das Zielgerät kopiert werden. Es existieren jedoch mehrere Programme, mit denen die [.filename]#*.img#-Datei auf einen USB-Stick geschrieben werden kann. In diesem Abschnitt werden zwei dieser Programme vorgestellt. [IMPORTANT] ==== Bevor Sie fortfahren, machen Sie Sicherungskopien der Daten auf dem USB-Stick. Diese Prozedur wird alle Daten auf dem Stick löschen. ==== [[bsdinstall-usb-dd]] [.procedure] **** *Procedure: Das Image mit `dd` auf einen USB-Stick schreiben* [WARNING] ==== Dieses Beispiel verwendet [.filename]#/dev/da0# als das Zielgerät, auf welches das Image geschrieben werden soll. Seien Sie _sehr vorsichtig_, dass das richtige Gerät benutzt wird, da das Kommando alle vorhandenen Daten auf dem Zielgerät zerstört. ==== . Das Werkzeug man:dd[1] steht unter BSD, Linux(R) und Mac OS(R)-Systemen zur Verfügung. Um das Image zu brennen, verbinden Sie den USB-Stick mit dem System und bestimmen Sie dessen Gerätenamen. Geben Sie dann den Namen der Installationsdatei und den Gerätenamen des USB-Sticks an. Dieses Beispiel schreibt die Installation für amd64 auf das erste USB-Gerät im FreeBSD-System. + [source,shell] .... # dd if=FreeBSD-12.1-RELEASE-amd64-memstick.img of=/dev/da0 bs=1M conv=sync .... + Wenn dieser Befehl fehlschlägt, stellen Sie sicher, dass der USB-Stick nicht eingehangen ist und prüfen Sie den Gerätenamen. Auf einigen Systemen muss der Befehl vielleicht mit Hilfe von man:sudo[8] ausgeführt werden. Die Syntax von man:dd[1] variiert leicht zwischen verschiedenen Plattformen. Zum Beispiel erfordert Mac OS(R) ein kleingeschriebenes `bs=1m`. Einige Systeme wie Linux(R) verwenden vielleicht einen Puffer. Verwenden Sie dann man:sync[8], um die Daten zu schreiben. **** [.procedure] **** *Procedure: Das Image unter Windows(R) schreiben* [WARNING] ==== Versichern Sie sich, dass Sie den korrekten Laufwerksbuchstaben angeben, da die bestehenden Daten des Laufwerks überschrieben und zerstört werden. ==== . Image Writer für Windows(R) herunterladen + Image Writer für Windows(R) ist eine frei verfügbare Anwendung, welche eine Imagedatei korrekt auf einen USB-Stick schreiben kann. Laden Sie diese von https://sourceforge.net/projects/win32diskimager/[ https://sourceforge.net/projects/win32diskimager/] herunter und entpacken Sie sie in ein Verzeichnis. . Das Image mit Image Writer auf den USB-Stick schreiben + Klicken Sie doppelt auf das Win32DiskImager-Icon, um das Programm zu starten. Prüfen Sie dabei, dass der Laufwerksbuchstabe unter `Device` dem Gerät entspricht, in dem sich der USB-Stick befindet. Klicken Sie auf das Ordnersymbol und wählen Sie das Image aus, welches auf den USB-Stick geschrieben werden soll. Um den Image-Dateinamen zu akzeptieren, klicken Sie auf btn:[Save]. Überprüfen Sie erneut, ob alles stimmt und dass keine Ordner auf dem USB-Stick in anderen Fenstern geöffnet sind. Sobald alles bereit ist, klicken Sie auf btn:[Write], um die Imagedatei auf den USB-Stick zu schreiben. **** Sie sind jetzt dazu bereit, mit der Installation von FreeBSD zu beginnen. [[bsdinstall-start]] == Die Installation starten [IMPORTANT] ==== Es werden bei Installation so lange keine Änderungen an den Festplatten durchgeführt, bis die folgende Meldung erscheint: [.programlisting] .... Your changes will now be written to disk. If you have chosen to overwrite existing data, it will be PERMANENTLY ERASED. Are you sure you want to commit your changes? .... Die Installation kann vor dieser Warnung zu jeder Zeit abgebrochen werden. Falls Zweifel bestehen, dass etwas falsch konfiguriert wurde, schalten Sie einfach den Computer vor diesem Punkt aus und es werden keine Änderungen an der Festplatte vorgenommen. ==== Dieser Abschnitt beschreibt, wie das System vom Installationsmedium, das nach den Anweisungen in <> erstellt wurde, gebootet wird. Wenn Sie einen bootfähigen USB-Stick einsetzen, verbinden Sie diesen mit dem System, bevor Sie den Computer einschalten. Falls die Installation von einer CD startet, müssen Sie den Computer einschalten und die CD so bald wie möglich einlegen. Wie das System konfiguriert werden muss, um von dem verwendeten Installationsmedium zu booten, hängt von der Architektur ab. [[bsdinstall-starting-i386]] === Systemstart von i386(TM) und amd64 Diese Architekturen beinhalten ein BIOS-Menü zur Auswahl des Boot-Gerätes. Abhängig von dem verwendeten Installationsmedium können Sie CD/DVD oder USB als erstes Boot-Gerät auswählen. Die meisten Systeme erlauben es auch, das Boot-Gerät während des Startvorgangs zu wählen, typischerweise durch drücken von kbd:[F10], kbd:[F11], kbd:[F12] oder kbd:[Esc]. Falls der Computer wie normal startet und das bestehende Betriebssystem lädt, befolgen Sie einen der hier aufgeführten Schritte: . Das Installationsmedium wurde während des Startvorgangs nicht früh genug eingelegt. Lassen Sie das Medium eingelegt und versuchen Sie, den Rechner neu zu starten. . Die Änderungen am BIOS waren nicht richtig oder wurden nicht gespeichert. Überprüfen Sie, dass das richtige Boot-Gerät als erstes Boot-Gerät ausgewählt ist. . Das verwendete System ist zu alt und unterstützt das starten vom gewählten Medium nicht. In diesem Fall kann der Plop Boot Manager (http://www.plop.at/de/bootmanagers.html[]) verwendet werden, um ältere Computer von CD oder USB-Medien zu starten. === Systemstart beim PowerPC(R) Auf den meisten Maschinen können Sie kbd:[C] auf der Tastatur gedrückt halten, um von der CD zu starten. Andernfalls, halten Sie kbd:[Command+Option+O+F], oder kbd:[Windows+Alt+O+F] auf nicht-Apple(R) Tastaturen gedrückt. Geben Sie an der `0 >`-Eingabeaufforderung folgendes ein: [source,shell] .... boot cd:,\ppc\loader cd:0 .... [[bsdinstall-view-probe]] === FreeBSD Bootmenü Wenn das System vom Installationsmedium gestartet wird, erscheint folgendes Menü auf dem Bildschirm: [[bsdinstall-newboot-loader-menu]] .FreeBSD Boot Loader Menü image::bsdinstall-newboot-loader-menu.png[] In der Voreinstellung wird das Menü zehn Sekunden auf Benutzereingaben warten, bevor das Installationsprogramm gestartet wird. Drücken Sie die Leertaste, um den Timer anzuhalten. Um eine Option auszuwählen, drücken Sie die entsprechende Nummer bzw. Buchstaben. Die folgenden Optionen stehen zur Verfügung. * `Boot Multi User`: Dies wird den Boot-Prozess von FreeBSD fortsetzen. Wenn der Timer angehalten wurde, drücken Sie entweder die kbd:[1], kbd:[B], oder kbd:[Enter]. * `Boot Single User`: Dieser Modus kann verwendet werden, um eine bestehende FreeBSD-Installation zu reparieren. Dies wird in crossref:boot[boot-singleuser,“Der Single-User Modus”] beschrieben. Drücken Sie die kbd:[2] oder kbd:[S] um in diesen Modus zu gelangen. * `Escape to loader prompt`: Dieser Modus startet einen Prompt, welcher nur eine begrenzte Anzahl an Low-Level-Befehlen enthält. Dies wird in crossref:boot[boot-loader,“Phase Drei”] beschrieben. Drücken Sie die kbd:[3] oder kbd:[Esc] um in diesen Modus zu gelangen. * `Reboot`: Startet das System neu. * `Kernel`: Lädt einen anderen Kernel. * `Configure Boot Options`: Öffnet das Menü, welches in <> beschrieben ist. [[bsdinstall-boot-options-menu]] .FreeBSD Boot-Optionen Menü image::bsdinstall-boot-options-menu.png[] Das Boot-Optionen Menü ist in zwei Abschnitte unterteilt. Der erste Abschnitt wird verwendet, um zurück zum Hauptmenü zu gelangen, oder um Optionen zurück auf die Standardwerte zu setzen. Im zweiten Abschnitt können verschiedene Optionen auf `On` oder `Off` gesetzt werden. Das System wird bei einem Neustart immer mit den Einstellungen für diese Optionen booten: * `ACPI Support`: Wenn das System während des Bootens hängt, setzen Sie diese Option auf `Off`. * `Safe Mode`: Wenn das System trotz deaktiviertem `ACPI Support` immer noch hängt, setzen Sie diese Option auf `On`. * `Single User`: Setzen Sie die Option auf `On`, um eine bestehende FreeBSD-Installation zu reparieren. Dieser Prozess wird in crossref:boot[boot-singleuser,“Der Single-User Modus”] beschrieben. Sobald das Problem behoben ist, setzen Sie die Option wieder auf `Off`. * `Verbose`: Wenn Sie während des Bootens ausführliche Meldungen sehen möchten, zum Beispiel für die Fehlersuche bei Hardwareproblemen, setzen Sie diese Option auf `On`. Nachdem Sie die benötigten Auswahlen getroffen haben, drücken Sie die kbd:[1] oder die Rücktaste, um zum Hauptmenü zurückzukehren. Drücken Sie dann kbd:[Enter] um den FreeBSD Bootprozess fortzusetzen. Eine Reihe von Boot-Meldungen werden nun im Rahmen der Geräteerkennung von FreeBSD angezeigt. Sobald dieser Prozess abgeschlossen ist, erscheint das Menü aus <>. [[bsdinstall-choose-mode]] .Willkommen-Menü image::bsdinstall-choose-mode.png[] Wählen Sie hier btn:[Install] und drücken Sie kbd:[Enter], um in das Installationsprogramm zu gelangen. Der Rest dieses Kapitels beschreibt das Installationsprogramm. Andernfalls verwenden Sie die Pfeiltasten um einen anderen Menüpunkt auszuwählen. btn:[Shell] kann verwendet werden, um eine Shell zu starten und Zugriff auf die Kommandozeilenprogramme zu erhalten, damit beispielsweise die Platten vor der Installation vorbereitet werden können. btn:[Live CD] kann verwendet werden um FreeBSD vor der Installation auszuprobieren. Die Live-Version wird in <> beschrieben. [TIP] ==== Um sich die Boot-Meldungen und die Ergebnisse der Geräteerkennung erneut anzeigen zu lassen, drücken Sie kbd:[S] gefolgt von kbd:[Enter]. Dadurch wird eine Shell gestartet, in der Sie die Ereignisse seitenweise mit `more /var/run/dmesg.boot` lesen können. Geben Sie `exit` ein, um zum Willkommen-Menü zurückzukehren. ==== [[using-bsdinstall]] == Verwendung von bsdinstall Dieser Abschnitt zeigt die Reihenfolge der Menüs von bsdinstall sowie die Informationen, die während der Installation abgefragt werden. Benutzen Sie die Pfeiltasten zur Navigation und die Leertaste, um einen Menüpunkt zu aktivieren oder zu deaktivieren. Wenn Sie fertig sind, drücken Sie kbd:[Enter], um die Auswahl zu speichern und zum nächsten Bildschirm zu gelangen. [[bsdinstall-keymap]] === Die Tastaturbelegung auswählen Bevor die Installation gestartet wird, lädt bsdinstall die Tastaturbelegung, wie in <> gezeigt. [[bsdinstall-keymap-loading]] .Laden der Tastaturbelegung image::bsdinstall-keymap-loading.png[] Nachdem die Tastaturbelegung geladen wurde, zeigt bsdinstall das Menü aus <> an. Wählen Sie die Tastenbelegung, die der am System angeschlossenen Tastatur am nächsten kommt, indem Sie die Pfeiltasten Hoch/Runter verwenden und anschließend kbd:[Enter] drücken. [[bsdinstall-keymap-10]] .Bildschirm zur Auswahl der Tastaturbelegung image::bsdinstall-keymap-10.png[] [NOTE] ==== Durch drücken von kbd:[Esc] wird das Menü verlassen und die Standardbelegung eingestellt. [.guimenuitem]#United States of America ISO-8859-1# ist eine sichere Option, falls Sie sich unsicher sind, welche Auswahl Sie treffen sollen. ==== [[bsdinstall-keymap-testing]] .Bildschirm zum Testen der Tastaturbelegung image::bsdinstall-keymap-testing.png[] [[bsdinstall-hostname]] === Den Rechnernamen festlegen Das nächste bsdinstall-Menü konfiguriert den Rechnernamen, der für das neu zu installierende System verwendet werden soll. [[bsdinstall-config-hostname]] .Festlegen des Rechnernamens image::bsdinstall-config-hostname.png[] Geben Sie einen für das Netzwerk eindeutigen Rechnernamen an. Der eingegebene Rechnername sollte ein voll-qualifizierter Rechnername sein, so wie z.B. `machine3.example.com`. [[bsdinstall-components]] === Auswahl der zu installierenden Komponenten Im nächsten Schritt fragt Sie bsdinstall, die optionalen Komponenten für die Installation auszuwählen. [[bsdinstall-config-components]] .Komponenten für die Installation auswählen image::bsdinstall-config-components.png[] Die Entscheidung, welche Komponenten auszuwählen sind, hängt größtenteils davon ab, für was das System künftig eingesetzt werden soll und der zur Verfügung stehende Plattenplatz. Der FreeBSD-Kernel und die Systemprogramme (zusammengenommen auch als _Basissystem_ bezeichnet) werden immer installiert. Abhängig vom Typ der Installation, werden manche dieser Komponenten nicht erscheinen. * `base-dbg` - Basiswerkzeuge wie cat, ls und vielte weitere mit aktiviertem Debugging. * `kernel-dbg` - Kernel und Module mit aktiviertem Debugging. * `lib32-dbg` - Kompatibilitäts-Bibliotheken mit aktiviertem Debugging, für die Ausführung von 32-bit-Anwendungen auf einer 64-bit-Version von FreeBSD. * `lib32` - Kompatibilitäts-Bibliotheken, um 32-bit-Anwendungen auf der 64-bit Version von FreeBSD laufen zu lassen. * `ports` - Die FreeBSD Ports-Sammlung ist eine Sammlung von Dateien, die das herunterladen, erstellen und installieren von Drittanbietersoftware automatisiert. crossref:ports[ports,Installieren von Anwendungen: Pakete und Ports] behandelt die Verwendung der Ports-Sammlung. + [WARNING] ==== Das Installationsprogramm prüft nicht, ob genügend Plattenplatz zur Verfügung steht. Wählen Sie diese Option nur, wenn die Festplatte über ausreichend Speicher verfügt. Die Ports-Sammlung nimmt etwa {ports-size} Plattenplatz ein. ==== * `src` - Der vollständige FreeBSD Quellcode für den Kernel und die Systemprogramme. Obwohl dies für die meisten Anwendungen nicht benötigt wird, kann es doch für manche Gerätetreiber, Kernelmodule und einigen Anwendungen aus der Ports-Sammlung erforderlich sein. Der Quellcode wird auch benötigt um an FreeBSD selbst mitzuentwickeln. Der komplette Quellcodebaum benötigt 1 GB Plattenplatz und um das gesamte Betriebssystem neu zu erstellen, werden zusätzliche 5 GB Platz benötigt. * `tests` - FreeBSD Test-Suite. [[bsdinstall-netinstall]] === Installation aus dem Netzwerk Das Menü in <> erscheint nur bei der Installation von einer [.filename]#-bootonly.iso#-CD, da dieses Installationsmedium keine Kopien der Installationsdateien enthält. Da die Installationsdateien über eine Netzwerkverbindung abgerufen werden müssen, weist dieses Menü darauf hin, dass zunächst die Netzwerkschnittstelle konfiguriert werden muss. Falls dieses Menü während der Installation angezeigt wird, befolgen Sie die Anweisungen in <>. [[bsdinstall-netinstall-notify]] .Installation über das Netzwerk image::bsdinstall-netinstall-files.png[] [[bsdinstall-partitioning]] == Plattenplatz bereitstellen Im nächsten Menü wird die Methode bestimmt, um den Plattenplatz zuzuweisen. [[bsdinstall-zfs-partmenu]] .Partitionierung unter FreeBSD image::bsdinstall-zfs-partmenu.png[] bsdinstall bietet dem Benutzer vier Methoden zur Zuweisung von Plattenplatz: * `Auto (UFS)` richtet die Partitionen automatisch mit dem `UFS`-Dateisystems ein. * `Manual` ermöglicht es fortgeschrittenen Benutzern, angepasste Partitionen über Menüoptionen zu erstellen. * `Shell` öffnet eine Eingabeaufforderung, in der fortgeschrittene Benutzer angepasste Partitionen mit Werkzeugen wie man:gpart[8], man:fdisk[8] und man:bsdlabel[8] erstellen können. * `Auto (ZFS)` erzeugt ein root-on-ZFS-System mit optionaler GELI-Verschlüsselung für Boot Environments. Dieser Abschnitt beschreibt, was bei der Partitionierung der Platten zu beachten ist und wie die einzelnen Methoden zur Partitionierung angewendet werden. [[configtuning-initial]] === Ein Partitionslayout entwerfen Wenn Sie Dateisysteme anlegen, sollten Sie beachten, dass Festplatten auf Daten in den äußeren Spuren schneller zugreifen können als auf Daten in den inneren Spuren. Daher sollten die kleineren und oft benutzten Dateisysteme an den äußeren Rand der Platte gelegt werden. Die größeren Partitionen wie [.filename]#/usr# sollten in die inneren Bereiche gelegt werden. Es empfiehlt sich, die Partitionen in folgender Reihenfolge anzulegen: [.filename]#/#, swap, [.filename]#/var# und [.filename]#/usr#. Die Größe der [.filename]#/var#-Partition ist abhängig vom Zweck der Maschine. Diese Partition enthält hauptsächlich Postfächer, Logdateien und Druckwarteschlangen. Abhängig von der Anzahl an Systembenutzern und der Aufbewahrungszeit für Logdateien, können Postfächer und Logdateien unerwartete Größen annehmen. Die meisten Benutzer benötigen nur selten mehr als ein Gigabyte für [.filename]#/var#. [NOTE] ==== Ein paar Mal wird es vorkommen, dass viel Festplattenspeicher in [.filename]#/var/tmp# benötigt wird. Wenn neue Software mit man:pkg_add[1] installiert wird, extrahieren die Paketwerkzeuge eine vorübergehende Kopie der Pakete unter [.filename]#/var/tmp#. Die Installation großer Softwarepakete wie Firefox oder LibreOffice kann sich wegen zu wenig Speicherplatz in [.filename]#/var/tmp# als trickreich herausstellen. ==== Die [.filename]#/usr# Partition enthält viele der Hauptbestandteile des Systems, einschließlich der FreeBSD Ports-Sammlung und den Quellcode des Systems. Für diese Partition werden mindestens zwei Gigabyte empfohlen. Behalten Sie bei der Auswahl der Partitionsgrößen den Platzbedarf im Auge. Wenn Sie den Platz auf einer Partition vollständig aufgebraucht haben, eine andere Partition aber kaum benutzen, kann die Handhabung des Systems schwierig werden. Als Daumenregel sollten Sie doppelt soviel Speicher für die Swap-Partition vorsehen, als Sie Hauptspeicher haben, da die VM-Paging-Algorithmen im Kernel so eingestellt sind, dass sie am besten laufen, wenn die Swap-Partition mindestens doppelt so groß wie der Hauptspeicher ist. Zu wenig Swap kann zu einer Leistungsverminderung im VM page scanning Code führen, sowie Probleme verursachen, wenn später mehr Speicher in die Maschine eingebaut wird. Auf größeren Systemen mit mehreren SCSI-, oder IDE-Laufwerken an unterschiedlichen Controllern, wird empfohlen, Swap-Bereiche auf bis zu vier Laufwerken einzurichten. Diese Swap-Partitionen sollten ungefähr dieselbe Größe haben. Der Kernel kann zwar mit beliebigen Größen umgehen, aber die internen Datenstrukturen skalieren bis zur vierfachen Größe der größten Partition. Ungefähr gleich große Swap-Partitionen erlauben es dem Kernel, den Swap-Bereich optimal über die Laufwerke zu verteilen. Große Swap-Bereiche, auch wenn sie nicht oft gebraucht werden, sind nützlich, da sich ein speicherfressendes Programm unter Umständen auch ohne einen Neustart des Systems beenden lässt. Indem Sie ein System richtig partitionieren, verhindern Sie, dass eine Fragmentierung in den häufig beschriebenen Partitionen auf die meist nur gelesenen Partitionen übergreift. Wenn Sie die häufig beschriebenen Partitionen an den Rand der Platte legen, dann wird die I/O-Leistung dieser Partitionen steigen. Die I/O-Leistung ist natürlich auch für große Partitionen wichtig, doch erzielen Sie eine größere Leistungssteigerung, wenn Sie [.filename]#/var# an den Rand der Platte legen. [[bsdinstall-part-guided]] === Geführte Partitionierung für UFS Bei dieser Methode wird ein Menü die verfügbaren Platten anzeigen. Sollten mehrere Platten angeschlossen sein, wählen Sie diejenige aus, auf der FreeBSD installiert werden soll. [[bsdinstall-part-guided-disk]] .Aus mehreren Platten eine auswählen image::bsdinstall-part-guided-disk.png[] Nachdem Sie die Platte ausgewählt haben, fordert das nächste Menü dazu auf, entweder die gesamte Festplatte für die Installation zu nutzen oder eine Partition aus unbenutzten Speicherplatz zu erstellen. Ein allgemeines Partitionslayout, das die gesamte Platte einnimmt wird erstellt, wenn btn:[Entire Disk] ausgewählt wird. Durch die Wahl von btn:[Partition] wird ein Partitionslayout aus dem unbenutzten Speicherplatz der Platte erstellt. [[bsdinstall-part-entire-part]] .Auswahl der gesamten Platte oder einer Partition image::bsdinstall-part-entire-part.png[] Wenn btn:[Entire Disk] gewählt wurde, weist bsdinstall darauf hin, dass die Festplatte gelöscht wird. [[bsdinstall-ufs-warning]] .Bestätigung image::bsdinstall-ufs-warning.png[] Das nächste Menü zeigt eine Liste der verfügbaren Partitionsschemas. GPT ist ist normalerweise die geeignetste Wahl für amd64-Rechner. Ältere Rechner, die nicht mit GPT kompatibel sind, sollten MBR benutzen. Die anderen Partitionsschemas werden im Allgemeinen für ungewöhnliche oder ältere Rechner benutzt. Weitere Informationen finden Sie in <>. [[bsdinstall-ufs-scheme]] image::bsdinstall-part-manual-partscheme.png[] Nachdem das Partitionslayout nun erstellt wurde, sollten Sie es überprüfen, um sicherzustellen, dass es die Bedürfnisse der Installation erfüllt. Durch die Auswahl von btn:[Revert] können die Partitionen wieder auf den ursprünglichen Wert zurückgesetzt werden und durch btn:[Auto] werden die automatischen FreeBSD Partitionen wiederhergestellt. Partitionen können auch manuell erstellt, geändert oder gelöscht werden. Sollte die Partitionierung richtig sein, wählen Sie btn:[Finish] aus, um mit der Installation fortzufahren. [[bsdinstall-part-review]] .Überprüfen der erstellten Partitionen image::bsdinstall-part-review.png[] Sobald die Festplatten konfiguriert sind, bietet das nächste Menü die letzte Möglichkeit, Änderungen vorzunehmen, bevor die ausgewählten Laufwerke formatiert werden. Wenn Änderungen vorgenommen werden müssen, wählen Sie btn:[Back], um zum Hauptmenü zurückzukehren. Mit btn:[Revert & Exit] wird das Installationsprogramm beendet, ohne Änderungen am Laufwerk vorzunehmen. Wählen Sie btn:[Commit], um die Installation zu starten. [[bsdinstall-ufs-final-confirmation]] .Abschließende Konfiguration image::bsdinstall-final-confirmation.png[] Um mit der Installation fortzufahren, gehen Sie zu <>. [[bsdinstall-part-manual]] === Manuelle Partitionierung Diese Methode öffnet den Partitionseditor: [[bsdinstall-part-manual-create]] .Partitionen manuell erstellen image::bsdinstall-part-manual-create.png[] Durch hervorheben einer Platte (in diesem Fall [.filename]#ada0#) und die Auswahl von btn:[Create], wird ein Menü mit den verfügbaren Partitionierungsschemas angezeigt. [[bsdinstall-part-manual-partscheme]] .Partitionen manuell anlegen image::bsdinstall-part-manual-partscheme.png[] GPT ist normalerweise die beste Wahl für amd64-Computer. Ältere Computer, die nicht mit GPT kompatibel sind, sollten MBR verwenden. Die anderen Partitionsschemas werden für gewöhnlich für ältere Computersysteme benutzt. [[partition-schemes]] .Partitionierungsschemas [cols="1,1", frame="none", options="header"] |=== <| Abkürzung <| Beschreibung |APM |Apple Partition Map, verwendet von PowerPC(R). |BSD |BSD-Labels ohne einen MBR, manchmal auch "dangerously dedicated mode" genannt, da nicht-BSD Festplatten-Werkzeuge dies vielleicht nicht erkennen können. |GPT |GUID Partition Table (http://de.wikipedia.org/wiki/GUID_Partition_Table[http://en.wikipedia.org/wiki/GUID_Partition_Table]). |MBR |Master Boot Record (http://de.wikipedia.org/wiki/Master_Boot_Record[http://en.wikipedia.org/wiki/Master_boot_record]). |VTOC8 |Volume Table Of Contents, von Sun SPARC64 und UltraSPARC Computern verwendet. |=== Nachdem das Partitionierungsschema ausgewählt und erstellt wurde, werden durch erneute Auswahl von btn:[Create] die Partitionen erzeugt. Mit der kbd:[Tab]-Taste können Sie den Cursor zwischen den Feldern bewegen. [[bsdinstall-part-manual-addpart]] .Partitionen manuell erzeugen image::bsdinstall-part-manual-addpart.png[] Eine FreeBSD-Standardinstallation mit GPT legt mindestens die folgenden drei Partitionen an: * `freebsd-boot` - Enthält den FreeBSD-Bootcode. * `freebsd-ufs` - Ein FreeBSD UFS-Dateisystem. * `freebsd-zfs` - Ein FreeBSD ZFS-Dateisystem. Weitere Informationen finden Sie in crossref:zfs[zfs,Das Z-Dateisystem (ZFS)]. * `freebsd-swap` - FreeBSD Auslagerungsbereich (swap space). Die einzelnen GPT-Partitionstypen sind in man:gpart[8] dokumentiert. Es können mehrere Dateisystempartitionen erzeugt werden und manche Leute ziehen es vor, ein traditionelles Layout mit getrennten Partitionen für die Dateisysteme [.filename]#/#, [.filename]#/var#, [.filename]#/tmp# und [.filename]#/usr# zu erstellen. Lesen Sie dazu <>, um ein Beispiel zu erhalten. Größenangaben (`Size`) können mit gängigen Abkürzungen eingegeben werden: _K_ für Kilobytes, _M_ für Megabytes oder _G_ für Gigabytes. [TIP] ==== Korrekte Sektorausrichtung ermöglicht größtmögliche Geschwindigkeit und das Anlegen von Partitionsgrößen als vielfaches von 4K-Bytes hilft, die passende Ausrichtung auf Platten mit entweder 512-Bytes oder 4K-Bytes Sektorgrößen, festzulegen. Generell sollte die Verwendung von Partitionsgrößen, die sogar vielfache von 1M oder 1G sind, den einfachsten Weg darstellen, um sicher zu stellen, dass jede Partition an einem vielfachen von 4K beginnt. Eine Ausnahme gibt es: momentan sollte die _freebsd-boot_-Partition aufgrund von Beschränkungen im Bootcode nicht größer sein als 512K. ==== Ein Einhägepunkt (`Mountpoint`) wird benötigt, falls diese Partition ein Dateisystem enthält. Falls nur eine einzelne UFS-Partition erstellt wird, sollte der Einhängepunkt [.filename]#/# lauten. Ein `label` ist ein Name, durch den diese Partition angesprochen wird. Festplattennamen oder -nummern können sich ändern, falls die Platte einmal an einem anderen Controller oder Port angeschlossen sein sollte, doch das Partitionslabel ändert sich dadurch nicht. Anstatt auf Plattennamen und Partitionsnummern in Dateien wie [.filename]#/etc/fstab# zu verweisen, sorgen Labels dafür, dass das System Hardwareänderungen eher toleriert. GPT-Labels erscheinen in [.filename]#/dev/gpt/#, wenn eine Platte angeschlossen wird. Andere Partitionierungsschemas besitzen unterschiedliche Fähigkeiten, Labels zu verwenden und diese erscheinen in anderen [.filename]#/dev/#-Verzeichnissen. [TIP] ==== Vergeben Sie ein einzigartiges Label für jede Partition, um Konflikte mit identischen Labels zu verhindern. Ein paar Buchstaben des Computernamens, dessen Verwendungszweck oder Ortes kann dem Label hinzugefügt werden. Beispielsweise `labroot` oder `rootfslab` für die UFS Root-Partition auf einem Laborrechner namens `lab`. ==== [[bsdinstall-part-manual-splitfs]] .Ein traditionelles, partitioniertes Dateisystem erstellen [example] ==== Für ein traditionelles Partitionslayout, in dem sich [.filename]#/#, [.filename]#/var#, [.filename]#/tmp# und [.filename]#/usr# in getrennten Partitionen befinden sollen, erstellen Sie ein GPT-Partitionsschema und anschließend die Partitionen selbst. Die gezeigten Partitionsgrößen sind typisch für eine Festplatte von 20 G. Falls mehr Platz verfügbar ist, sind größere Swap oder [.filename]#/var#-Partitionen nützlich. Den hier gezeigten Beschreibungen sind `bsp` für "Beispiel" vorangestellt, jedoch sollten Sie andere, einzigartige Beschreibungen verwenden, wie oben beschrieben. Standardmäßig erwartet FreeBSDs [.filename]#gptboot#, dass die erste UFS-Partition die [.filename]#/#-Partition ist. [.informaltable] [cols="1,1,1,1", frame="none", options="header"] |=== | Partitionstyp | Grösse | Eingehängt als | Beschreibung |`freebsd-boot` |`512K` +| +| |`freebsd-ufs` |`2G` |[.filename]#/# |`bsprootfs` |`freebsd-swap` |`4G` |`bspswap` +| |`freebsd-ufs` |`2G` |[.filename]#/var# |`bspvarfs` |`freebsd-ufs` |`1G` |[.filename]#/tmp# |`bsptmpfs` |`freebsd-ufs` |Akzeptieren Sie die Standardeinstellungen (Rest der Platte) |[.filename]#/usr# |`bspusrfs` |=== ==== Nachdem die Partitionen erzeugt wurden, wählen Sie btn:[Finish], um die Installation mit <> fortzusetzen. [[bsdinstall-part-zfs]] === Geführte Partitionierung mit Root-on-ZFS Dieser Modus funktioniert nur mit ganzen Laufwerken und wird alle vorhandenen Daten auf der Platte löschen. Das Konfigurationsmenü für ZFS bietet einige Optionen, um die Erstellung des Pools zu beeinflussen. [[bsdinstall-zfs-menu]] .ZFS Konfigurationsmenü image::bsdinstall-zfs-menu.png[] Hier eine Zusammenfassung der Optionen, die in diesem Menü benutzt werden können: * `Install` - Setzt die Installation mit den ausgewählten Optionen fort. * `Pool Type/Disks` - Erlaubt die Konfiguration des `Pool Type` und der Festplatte(n), die den Pool bilden werden. Das ZFS-Installationsprogramm unterstützt derzeit nur die Erstellung eines einzelnen Top-Level-Vdev, außer im Stripe-Modus. Um komplexere Pools zu erstellen, folgen Sie den Anweisungen in <>, um den Pool zu erstellen. * `Rescan Devices` - Aktualisiert die Liste der verfügbaren Festplatten. * `Disk Info` - Dieses Menü wird verwendet, um Datenträger zu inspizieren, einschließlich ihrer Partitionstabelle und weitere Informationen wie die Modell- und Seriennummer des Geräts. * `Pool Name` - Legt den Namen des Pools fest. Der Standard ist _zroot_. * `Force 4K Sectors?` - Erzwingt die Verwendung von 4K-Sektoren. Im Standard erstellt die Installation automatisch Partitionen, die an 4K-Grenzen ausgerichtet sind. Bei ZFS wird die Verwendung von 4K-Sektoren erzwungen. Dies ist selbst bei Festplatten mit 512-Byte-Sektoren sicher und hat den zusätzlichen Vorteil, dass Pools, die auf solchen Festplatten mit erstellt werden, auch in Zukunft 4K-Sektoren haben können, entweder als zusätzlicher Speicherplatz oder als Ersatz für ausgefallene Platten. Drücken Sie kbd:[Enter], um die Verwendung von 4K-Sektoren zu konfigurieren. * `Encrypt Disks?` - Das Verschlüsseln der Datenträger mit GELI. Weitere Informationen zur Datenträgerverschlüsselung finden Sie in crossref:disks[disks-encrypting-geli,“Plattenverschlüsselung mit geli”]. Drücken Sie kbd:[Enter] um eine Auswahl zu treffen. * `Partition Scheme` - Erlaubt die Auswahl des Partitionsschemas. GPT ist die empfohlene Option. Drücken Sie kbd:[Enter], um zwischen den verschiedenen Optionen zu wählen. * `Swap Size` - Legt die Größe des Swap-Speichers fest. * `Mirror Swap?` - Erlaubt es, den Swap-Speicher zwischen den Platten zu spiegeln. Beachten Sie jedoch, dass die Aktivierung dazu führt, dass Crash Dumps nicht mehr funktionieren. Drücken Sie kbd:[Enter], um diese Option zu aktivieren/deaktivieren. * `Encrypt Swap?` - Erlaubt es, den Swap-Speicher zu verschlüsseln. Der Swap-Speicher wird bei jedem Systemstart mit einem temporären Schlüssel verschlüsselt, der bei einem Neustart des Systems verworfen wird. Drücken Sie kbd:[Enter], diese Option zu aktivieren/deaktivieren. Weitere Informationen zur Verschlüsselung des Swap-Speichers finden Sie in crossref:disks[swap-encrypting,“Den Auslagerungsspeicher verschlüsseln”]. Wählen Sie kbd:[T] um den Pool Typ und die Festplatte(n) zu konfigurieren, die den Pool bilden werden. [[bsdinstall-zfs-vdev_type]] .ZFS Pool Typen image::bsdinstall-zfs-vdev_type.png[] Hier eine Zusammenfassung der Pool-Typen, die in diesem Menü ausgewählt werden können: * `stripe` - Striping bietet maximalen Speicherplatz für alle angeschlossenen Geräte, aber keine Redundanz. Fällt eine Platte aus, sind die Daten im Pool unwiderruflich verloren. * `mirror` - Bei der Spiegelung wird eine vollständige Kopie aller Daten auf jeder Platte gespeichert. Die Spiegelung bietet eine gute Leistung beim Lesen, da die Daten von allen Platten parallel gelesen werden. Die Leistung beim Schreiben ist langsamer, da die Daten auf alle Platten im Pool geschrieben werden müssen. Hiermit können alle Platten bis auf eine ausfallen. Diese Option erfordert mindestens zwei Platten. * `raid10` - Striped Mirrors. Bieten die beste Leistung, aber den geringsten Speicherplatz. Diese Option erfordert mindestens eine gerade Anzahl von Platten und mindestens vier Platten. * `raidz1` - Einzelnes redundantes RAID. Ermöglicht den Ausfall einer Platte. Für diese Option sind mindestens drei Festplatten erforderlich. * `raidz2` - Doppeltes redundantes RAID. Ermöglicht den Ausfall von zwei Platten. Für diese Option sind mindestens vier Festplatten erforderlich. * `raidz3` - Dreifaches redundantes RAID. Ermöglicht den Ausfall von drei Platten. Für diese Option sind mindestens fünf Festplatten erforderlich. Sobald ein Pool-Typ (`Pool Type`) ausgewählt wurde, wird eine Liste der verfügbaren Laufwerke angezeigt und der Benutzer wird aufgefordert, eine oder mehrere Laufwerke für die Erstellung des Pools auszuwählen. Anschließend wie die Konfiguration geprüft um zu gewährleisten, dass genug Laufwerke ausgewählt wurden. Wählen Sie btn:[] um zur Auswahl der Laufwerke zurückzukehren, oder btn:[] um den `Pool Type` zu ändern. [[bsdinstall-zfs-disk_select]] .Auswahl der Laufwerke image::bsdinstall-zfs-disk_select.png[] [[bsdinstall-zfs-vdev_invalid]] .Ungültige Auswahl image::bsdinstall-zfs-vdev_invalid.png[] Wenn eine oder mehrere Platten in der Liste fehlen, oder wenn Festplatten angebunden wurden, nachdem das Installationsprogramm gestartet wurde, wählen Sie btn:[- Rescan Devices] um die Laufwerke nochmals zu suchen und anzuzeigen. [[bsdinstall-zfs-rescan-devices]] .Rescan Devices image::bsdinstall-zfs-rescan-devices.png[] Um zu vermeiden, dass versehentlich die falsche Platte gelöscht wird, können Sie das btn:[- Disk-Info]-Menü verwenden. Dieses Menü zeigt verschiedene Informationen, einschließlich der Partitionstabelle, der Modellnummer und der Seriennummer, falls verfügbar. [[bsdinstall-zfs-disk_info]] .Informationen zum Laufwerk image::bsdinstall-zfs-disk_info.png[] Wählen Sie kbd:[N], um den Pool-Namen zu konfigurieren. Geben Sie den gewünschten Namen ein und wählen Sie dann btn:[OK], um den Namen zu speichern, oder btn:[], um zum Hauptmenü zurückzukehren und den Standard zu belassen. [[bsdinstall-zfs-pool-name]] .Pool-Name image::bsdinstall-zfs-pool-name.png[] Wählen Sie kbd:[S], um die Größe des Swap-Speichers festzulegen. Geben Sie die gewünschte Größe ein und wählen Sie dann btn:[OK], um die Einstellung zu speichern, oder btn:[], um zum Hauptmenü zurückzukehren und den Standard zu belassen. [[bsdinstall-zfs-swap-amount]] .Größe des Swap-Speichers image::bsdinstall-zfs-swap-amount.png[] Wenn alle Optionen wie gewünscht konfiguriert sind, wählen Sie oben im Menü die Option btn:[>>> Install]. Das Installationsprogramm bietet dann eine letzte Chance zum Abbrechen, bevor der Inhalt der ausgewählten Laufwerke zerstört wird, um den ZFS-Pool zu erstellen. [[bsdinstall-zfs-warning]] .Letzte Chance! image::bsdinstall-zfs-warning.png[] Wenn die GELI Plattenverschlüsselung aktiviert wurde, fordert das Installationsprogramm zweimal zur Eingabe der Passphrase auf. Anschließend beginnt die Initialisierung der Verschlüsselung. [[bsdinstall-zfs-geli_password]] .Passwort für die Verschlüsselung der Platte image::bsdinstall-zfs-geli_password.png[] [[bsdinstall-zfs-init-encryption]] .Initialisierung der Verschlüsselung image::bsdinstall-zfs-init-encription.png[] Danach wird die Installation normal weitergeführt. Um mit der Installation fortzufahren, lesen Sie <>. [[bsdinstall-part-shell]] === Shell Partitionierung bsdinstall bietet bei fortgeschrittenen Installationen womöglich nicht die benötigte Flexibilität. Erfahrene Benutzer können die Option btn:[Shell] im Menü auswählen, um die Laufwerke manuell zu partitionieren, Dateisysteme zu erstellen, [.filename]#/tmp/bsdinstall_etc/fstab# zu befüllen und Dateisysteme unter [.filename]#/mnt# einzuhängen. Geben Sie anschließend `exit` ein, um zu bsdinstall zurückzukehren und die Installation fortzusetzen. [[bsdinstall-fetching-distribution]] == Abrufen der Distributionen Die Installationsdauer hängt von den gewählten Distributionen, dem Installationsmedium und der Geschwindigkeit des Computers ab. Eine Reihe von Nachrichten werden angezeigt, um den Fortschritt darzustellen. Zunächst formatiert das Installationsprogramm die ausgewählten Platten und initialisiert die Partitionen. Bei `bootonly media` oder `mini memstick` werden als nächstes die benötigten Komponenten heruntergeladen: [[bsdinstall-distfile-fetching]] .Herunterladen der Distributionsdateien image::bsdinstall-distfile-fetching.png[] Als nächstes wird die Integrität der Distributionsdateien überprüft, um sicherzustellen, dass diese während des Ladevorgangs nicht beschädigt oder unsauber vom Installationsmedium gelesen wurden: [[bsdinstall-distfile-verify]] .Überprüfen der Distributionsdateien image::bsdinstall-distfile-verifying.png[] Zum Schluss werden die überprüften Distributionsdateien auf die Festplatte entpackt: [[bsdinstall-distfile-extract]] .Entpacken der Distributionsdateien image::bsdinstall-distfile-extracting.png[] Sobald alle benötigten Distributionsdateien entpackt wurden, wird bsdinstall das erste Menü für die Arbeiten nach der Installation anzeigen. Die zur Verfügung stehenden Konfigurationsoptionen werden im nächsten Abschnitt beschrieben. [[bsdinstall-post]] == Benutzerkonten, Zeitzone, Dienste und Sicherheitsoptionen [[bsdinstall-post-root]] === Setzen des `root`-Passworts Zuerst muss das `root`-Passwort gesetzt werden. Die eingegebenen Zeichen werden dabei nicht auf dem Bildschirm angezeigt. Nachdem das Passwort eingegeben wurde, muss es zur Bestätigung erneut eingetippt werden. Damit werden auch Tippfehler verhindert. [[bsdinstall-post-set-root-passwd]] .Das `root`-Passwort setzen image::bsdinstall-post-root-passwd.png[] [[bsdinstall-timezone]] === Setzen der Zeitzone Die nächsten Menüs werden verwendet, um die korrekte Ortszeit zu ermitteln. Dazu muss die gewünschte geographische Region, das Land und die Zeitzone ausgewählt werden. Das Setzen der Zeitzone erlaubt es dem System automatische Korrekturen vorzunehmen, beispielsweise beim Wechsel von Sommer- auf Winterzeit. Das hier gezeigte Beispiel bezieht sich auf einen Rechner in der Zeitzone des spanischen Festlands. Die Auswahl ist je nach geographischer Lage unterschiedlich. [[bsdinstall-timezone-region]] .Auswahl der geographischen Region image::bsdinstall-timezone-region.png[] [[bsdinstall-timezone-country]] .Das Land auswählen image::bsdinstall-timezone-country.png[] Wählen Sie das zutreffende Land mit den Pfeiltasten und durch anschließendes drücken von kbd:[Enter] aus. [[bsdinstall-timezone-zone]] .Wählen einer Zeitzone image::bsdinstall-timezone-zone.png[] Die passende Zeitzone wird durch die Pfeiltasten und anschließendes drücken von kbd:[Enter] ausgewählt. [[bsdinstall-timezone-confirmation]] .Bestätigen der Zeitzone image::bsdinstall-timezone-confirm.png[] Bestätigen Sie, dass die Abkürzung für die Zeitzone korrekt ist. [[bsdinstall-timezone-date]] .Datum auswählen image::bsdinstall-timezone-date.png[] Das entsprechende Datum wird mit den Pfeiltasten und das anschließende Drücken von btn:[Set Date] gewählt. Andernfalls kann die Auswahl durch Drücken von btn:[Skip] übersprungen werden. [[bsdinstall-timezone-time]] .Uhrzeit auswählen image::bsdinstall-timezone-time.png[] Die entsprechende Uhrzeit wird mit den Pfeiltasten und das anschließende Drücken von btn:[Set Time] gewählt. Andernfalls kann die Auswahl durch Drücken von btn:[Skip] übersprungen werden. [[bsdinstall-sysconf]] === Dienste aktivieren Zusätzliche Systemdienste, die zur Startzeit aktiviert werden sollen, können im folgenden Menü eingeschaltet werden. All diese Dienste sind optional. Starten Sie nur die Dienste, die zur korrekten Funktion des Systems benötigt werden. [[bsdinstall-config-serv]] .Auswahl zusätzlicher Dienste image::bsdinstall-config-services.png[] Die folgenden Dienste können über dieses Menü aktiviert werden: * `local_unbound` - Aktiviert den lokalen unbound DNS-Cache. Bedenken Sie, dass dies der Unbound des Basissystems ist und nur als lokaler Cache-Forwarding-Resolver gedacht ist. Möchten Sie einen DNS-Server für das gesamte Netzwerk einrichten, installieren Sie bitte package:dns/unbound[]. * `sshd` - Der Secure Shell (SSH)-Daemon für Fernzugriff über eine verschlüsselte Verbindung. Aktivieren Sie diesen Dienst nur dann, wenn das System für Fernzugriff zur Verfügung stehen soll. * `moused` - Aktivieren Sie diesen Dienst, wenn Sie Mausunterstützung auf der Systemkonsole benötigen. * `ntpdate` - Aktiviert die automatische Synchronisation der Uhrzeit beim booten. Diese Funktionalität ist ebenfalls im man:ntpd[8]-Daemon verfügbar. In naher Zukunft soll das Programm man:ntpdate[8] entfernt werden. * `ntpd` - Der Network Time Protocol (NTP)-Daemon zur automatischen Uhrzeitsynchronisation. Aktivieren Sie diesen Dienst, wenn es im Netzwerk einen Windows(R)-, Kerberos- oder LDAP-Server gibt. * `powerd` - Systemwerkzeug zur Leistungsregelung und für Stromsparfunktionen. * `dumpdev` - Aktiviert die Absturzaufzeichnung, welche sehr nützlich sein kann, um Systemfehler aufzuspüren. Daher wird Anwendern empfohlen, diese Option zu aktivieren. [[bsdinstall-hardening]] === Aktivieren von Sicherheitsoptionen Im nächsten Menü können Sicherheitsoptionen aktiviert werden. Alle diese Optionen sind optional. Es wird jedoch empfohlen, sie zu aktivieren. [[bsdinstall-hardening-options]] .Auswahl der Sicherheitsoptionen image::bsdinstall-hardening.png[] Folgende Optionen können in diesem Menü aktiviert werden: * `hide_uids` - Versteckt die Prozesse von anderen Benutzern, um zu verhindern, dass unprivilegierte Benutzer laufende Prozesse von anderen Benutzern (UID) sehen können. * `hide_gids` - Versteckt die Prozesse anderer Gruppen, um zu verhindern, dass unprivilegierte Benutzer laufende Prozesse von anderen Gruppen (GID) sehen können. * `hide_jails` - Versteckt Jail-Prozesse, um zu verhindern, dass unprivilegierte Benutzer die in den Jails laufenden Prozesse sehen können. * `read_msgbuf` - Deaktiviert den Lesezugriff auf den Nachrichtenpuffer des Kernels für nicht privilegierte Benutzer. Dadurch wird verhindert, dass man:dmesg[8] zum Anzeigen von Nachrichten aus dem Nachrichtenpuffer des Kernels verwendet wird. * `proc_debug` - Die Deaktivierung von Prozess-Debugging-Funktionen für unprivilegierte Benutzer deaktiviert einige IPC-Dienste und procfs-Funktionen, ptrace() und ktrace(). Beachten Sie, dass dadurch auch die Nutzung von Werkzeugen wie man:lldb[1], man:truss[1], man:procstat[1] und einige Debugging-Funktionen von Skriptsprachen wie PHP, für unprivilegierte Benutzer unterbunden wird. * `random_pid` - Zufällig generierte PID für neu erstellte Prozesse. * `clear_tmp` - Bereinigt das Verzeichnis [.filename]#/tmp# beim Systemstart. * `disable_syslogd` - Diese Option verhindert, dass syslogd einen Netzwerk-Socket öffnet. In der Voreinstellung startet FreeBSD syslogd auf sichere Weise mit `-s`. Das verhindert, dass der Daemon auf Port 514 auf UDP-Anfragen lauscht. Wenn diese Option aktiviert ist, läuft syslogd mit dem Schalter `-ss`, dass syslogd daran hindert, einen Port zu öffnen. Weitere Informationen finden Sie in man:syslogd[8]. * `disable_sendmail` - Deaktiviert den sendmail MTA. * `secure_console` - Wenn diese Option aktiviert ist, fragt das System im Single-User-Modus nach dem `root"`-Passwort. * `disable_ddtrace` - DTrace kann in einem Modus laufen, der sich tatsächlich auf den laufenden Kernel auswirkt. Destruktive Aktionen dürfen nicht benutzt werden, es sei denn, sie wurden explizit aktiviert. Um diese Option bei der Verwendung von DTrace zu aktivieren, benutzen Sie `-w`. Weitere Informationen finden Sie in man:dtrace[1]. [[bsdinstall-addusers]] === Benutzer hinzufügen Das nächste Menü fordert Sie dazu auf, mindestens ein Benutzerkonto zu erstellen. Es wird empfohlen, sich als normaler Benutzer am System anzumelden und nicht als `root`-Benutzer. Wenn man als `root` angemeldet ist, gibt es so gut wie keine Beschränkungen oder Schutz vor dem, was man tun kann. Die Anmeldung als normaler Benutzer ist daher sicherer und bietet mehr Schutz. Wählen Sie btn:[Yes], um neue Benutzer hinzuzufügen. [[bsdinstall-add-user1]] .Benutzerkonten hinzufügen image::bsdinstall-adduser1.png[] Folgen Sie den Anweisungen und geben Sie die angeforderten Informationen für das Benutzerkonto ein. Das Beispiel in <> erstellt ein Konto für den Benutzer `asample`. [[bsdinstall-add-user2]] .Benutzerinformationen eingeben image::bsdinstall-adduser2.png[] Die folgenden Informationen müssen eingegeben werden: * `Username` - Der Name des Benutzers, den man zur Anmeldung eingeben muss. Es ist üblich, den ersten Buchstaben des Vornamens zusammen mit dem Nachnamen zu kombinieren. Jeder Benutzername ist möglich, solange er für das System einzigartig ist. Es wird zwischen Groß- und Kleinschreibung unterschieden und der Benutzername sollte keine Leerzeichen enthalten. * `Full name` - Der volle Name des Benutzers. Dieser darf auch Leerzeichen enthalten und dient als Beschreibung für das Benutzerkonto. * `Uid` - User ID. Normalerweise wird dieses Feld leer gelassen, so dass das System einen Wert vergibt. * `Login group` - Die Benutzergruppe. Normalerweise bleibt dieses Feld leer, um die Standardgruppe zu akzeptieren. * `Invite _user_ into other groups?` - Zusätzliche Gruppen zu denen der Benutzer als Mitglied hinzugefügt werden soll. Falls der Benutzer administrativen Zugriff benötigt, tragen Sie hier `wheel` ein. * `Login class` - In der Regel bleibt dieses Feld leer. * `Shell` - Die interaktive Shell für diesen Benutzer. Tragen Sie hier eine der aufgeführten Shells ein. Weitere Informationen über Shells finden Sie im crossref:basics[shells,“Shells”]. * `Home directory` - Das Heimatverzeichnis des Benutzers. Die Vorgabe ist für gewöhnlich richtig. * `Home directory permissions` - Zugriffsrechte auf das Heimatverzeichnis des Benutzers. Die Vorgabe ist normalerweise die passende. * `Use password-based authentication?` - Normalerweise `yes`, damit der Benutzer bei der Anmeldung sein Passwort eingeben muss. * `Use an empty password?` - Normalerweise `no`, da ein leeres Passwort unsicher ist. * `Use a random password?` - Normalerweise `no`, damit der Benutzer sein Passwort am nächsten Prompt selber vergeben kann. * `Enter password` - Das Passwort für diesen Benutzer. Eingegebene Zeichen werden nicht am Bildschirm angezeigt. * `Enter password again` - Das Passwort muss zur Überprüfung erneut eingegeben werden. * `Lock out the account after creation?` - Normalerweise `no`, damit sich der Benutzer anmelden kann. Nachdem alles eingegeben wurde, wird eine Zusammenfassung angezeigt und das System fragt Sie, dies so korrekt ist. Falls ein Eingabefehler gemacht wurde, geben Sie `no` ein und versuchen es erneut. Falls alles in Ordnung ist, geben Sie `yes` ein, um den neuen Benutzer anzulegen. [[bsdinstall-add-user3]] .Verlassen der Benutzer- und Gruppenverwaltung image::bsdinstall-adduser3.png[] Falls es mehr Benutzer hinzuzufügen gibt, beantworten Sie die Frage `Add another user?` mit `yes`. Geben Sie `no` ein, wird das hinzufügen von Benutzern beendet und die Installation fortgesetzt. Für weitere Informationen zum hinzufügen von Benutzern und deren Verwaltung, lesen Sie crossref:basics[users-synopsis,“Benutzer und grundlegende Account-Verwaltung”]. [[bsdinstall-final-conf]] === Letzte Konfigurationsschritte Nachdem alles installiert und konfiguriert wurde, bekommen Sie noch eine letzte Chance, um Einstellungen zu verändern. [[bsdinstall-final-config]] .Letzte Schritte der Konfiguration image::bsdinstall-finalconfiguration.png[] Verwenden Sie dieses Menü, um noch letzte Änderungen oder zusätzliche Konfigurationen vor dem Abschließen der Installation zu tätigen. * `Add User` - Beschrieben in <>. * `Root Password` - Beschrieben in <>. * `Hostname` - Beschrieben in <>. * `Network` - Beschrieben in <>. * `Services` - Beschrieben in <>. * `Time Zone` - Beschrieben in <>. * `Handbook` - Herunterladen und installieren des FreeBSD Handbuchs. Nachdem die letzten Konfigurationsschritte beendet sind, wählen Sie btn:[Exit]. [[bsdinstall-final-modification-shell]] .Manuelle Konfiguration image::bsdinstall-final-modification-shell.png[] bsdinstall wird nach zusätzlichen Konfigurationen, die noch zu tätigen sind, fragen, bevor in das neue System gebootet wird. Wählen Sie btn:[Yes], um in eine Shell innerhalb des neuen Systems zu wechseln oder btn:[No], um mit dem letzten Schritt der Installation zu beginnen. [[bsdinstall-final-main]] .Die Installation vervollständigen image::bsdinstall-mainexit.png[] Wenn weitere Konfigurationen oder besondere Einstellungen benötigt werden, wählen Sie btn:[Live CD], um das Installationsmedium im Live-CD Modus zu starten. Wenn die Installation vollständig ist, wählen Sie btn:[Reboot], um den Computer neu zu starten und das neu installierte FreeBSD-System zu booten. Vergessen Sie nicht, das FreeBSD Installationsmedium zu entfernen, oder der Computer wird erneut davon starten. Wenn FreeBSD startet, werden viele Informationsmeldungen ausgegeben. Nachdem das System den Startvorgang abgeschlossen hat, wird eine Anmeldeaufforderung angezeigt. Geben Sie am `login:` den Benutzernamen ein, den Sie während der Installation hinzugefügt haben. Vermeiden Sie es, sich als `root` anzumelden. Lesen Sie crossref:basics[users-superuser,“Der Superuser-Account”], wenn Sie administrativen Zugriff benötigen. Um Nachrichten, die während des Bootens angezeigt wurden, zu sehen, aktivieren Sie durch drücken von kbd:[Scroll-Lock] den _scroll-back buffer_. Die Tasten kbd:[PgUp], kbd:[PgDn] und die Pfeiltasten dienen zur Navigation durch die Nachrichten. Durch erneutes drücken von kbd:[Scroll-Lock] wird der Bildschirm wieder entsperrt und kehrt zur normalen Anzeige zurück. Mit `less /var/run/dmesg.boot` können Sie sich diese Nachrichten im laufenden Betrieb ansehen. Durch drücken von kbd:[q] kehren Sie wieder zur Kommandozeile zurück. Wenn sshd in <> aktiviert wurde, ist der erste Start ein bisschen langsamer, weil das System die RSA- und DSA-Schlüssel erzeugen muss. Die nachfolgenden Startvorgänge werden dann wieder schneller sein. Wie in diesem Beispiel zu sehen ist, werden die Fingerabdrücke der Schlüssel am Bildschirm ausgegeben: [source,shell] .... Generating public/private rsa1 key pair. Your identification has been saved in /etc/ssh/ssh_host_key. Your public key has been saved in /etc/ssh/ssh_host_key.pub. The key fingerprint is: 10:a0:f5:af:93:ae:a3:1a:b2:bb:3c:35:d9:5a:b3:f3 root@machine3.example.com The key's randomart image is: +--[RSA1 1024]----+ | o.. | | o . . | | . o | | o | | o S | | + + o | |o . + * | |o+ ..+ . | |==o..o+E | +-----------------+ Generating public/private dsa key pair. Your identification has been saved in /etc/ssh/ssh_host_dsa_key. Your public key has been saved in /etc/ssh/ssh_host_dsa_key.pub. The key fingerprint is: 7e:1c:ce:dc:8a:3a:18:13:5b:34:b5:cf:d9:d1:47:b2 root@machine3.example.com The key's randomart image is: +--[ DSA 1024]----+ | .. . .| | o . . + | | . .. . E .| | . . o o . . | | + S = . | | + . = o | | + . * . | | . . o . | | .o. . | +-----------------+ Starting sshd. .... Lesen Sie crossref:security[openssh,"OpenSSH"] für weitere Informationen zu Fingerabdrücken und SSH. FreeBSD installiert standardmäßig keine graphische Umgebung. crossref:x11[x11,Das X-Window-System] enthält Informationen zur Installation und Konfiguration eines graphischen Window Managers. Das korrekte herunterfahren eines FreeBSD-Computers hilft, beugt dem Datenverlust vor und schützt sogar die Hardware vor Schäden. _Schalten Sie nicht den Strom ab, bevor das System ordnungsgemäß heruntergefahren wurde!_ Wenn der Benutzer ein Mitglied der `wheel`-Gruppe ist, können Sie zum Superuser durch die Eingabe von `su` und der anschließenden Eingabe des Passworts von `root` werden. Geben Sie dann `shutdown -p now` ein. Das System wird jetzt sauber heruntergefahren und, falls die Hardware es unterstützt, den Rechner ausschalten. [[bsdinstall-network]] == Netzwerkschnittstellen [[bsdinstall-config-network-dev]] === Die Netzwerkschnittstelle konfigurieren Als nächstes wird eine Liste der gefundenen Netzwerkschnittstellen gezeigt. Wählen Sie die Schnittstelle aus, die Sie konfigurieren möchten. [[bsdinstall-configure-net-interface]] .Eine zu konfigurierende Netzwerkschnittstelle auswählen image::bsdinstall-configure-network-interface.png[] Wenn Sie eine Ethernet-Schnittstelle ausgewählt haben, fährt das Installationsprogramm mit dem Menü aus <> fort. Wenn Sie eine drahtlose Netzwerkschnittstelle ausgewählt haben, wird das System nach drahtlosen Zugriffspunkten (Access Points) suchen: [[bsdinstall-wireless-scan]] .Nach drahtlosen Access Points scannen image::bsdinstall-configure-wireless-scan.png[] Drahtlose Netzwerke werden durch einen Service Set Identifier (SSID) identifiziert. Der SSID ist ein kurzer, eindeutiger Name, der für jedes Netzwerk vergeben wird. SSIDs, die während des Scans gefunden wurden, werden aufgelistet, gefolgt von einer Beschreibung der Verschlüsselungsarten, die für dieses Netzwerk verfügbar sind. Falls die gewünschte SSID nicht in der Liste auftaucht, wählen Sie btn:[Rescan], um erneut einen Scanvorgang durchzuführen. Falls dann das gewünschte Netzwerk immer noch nicht erscheint, überprüfen Sie die Antenne auf Verbindungsprobleme oder versuchen Sie, näher an den Access point zu gelangen. Scannen Sie erneut nach jeder vorgenommenen Änderung. [[bsdinstall-wireless-accesspoints]] .Ein drahtloses Netzwerk auswählen image::bsdinstall-configure-wireless-accesspoints.png[] Geben Sie nun die Verschlüsselungsinformationen ein, um sich mit dem drahtlosen Netzwerk zu verbinden. WPA2 wird als Verschlüsselung dringend empfohlen, da ältere Verschlüsselungsmethoden, wie WEP, nur wenig Sicherheit bieten. Wenn das Netzwerk WPA2 verwendet, geben Sie das Passwort (auch bekannt als Pre-Shared Key PSK) ein. Aus Sicherheitsgründen werden die in das Eingabefeld eingegeben Zeichen nur als Sternchen angezeigt. [[bsdinstall-wireless-wpa2]] .Verbindungsaufbau mit WPA2 image::bsdinstall-configure-wireless-wpa2setup.png[] Wählen Sie, ob eine IPv4-Adresse auf der Ethernet-Schnittstelle oder der drahtlosen Schnittstelle konfiguriert werden soll. [[bsdinstall-configure-net-ipv4]] .Auswahl von IPv4 image::bsdinstall-configure-network-interface-ipv4.png[] Es gibt zwei Arten, ein IPv4-Netzwerk zu konfigurieren. DHCP wird automatisch die Netzwerkschnittstelle richtig konfigurieren und sollte verwendet werden, wenn das Netzwerk über einen DHCP-Server verfügt. Eine _statische_ IP-Konfiguration erfordert die manuelle Eingabe von Netzwerkinformationen. [NOTE] ==== Geben Sie keine zufällig gewählten Netzwerkinformationen ein, da dies nicht funktionieren wird. Holen Sie sich die in <> gezeigten Informationen vom Netzwerkadministrator oder Serviceprovider, falls kein DHCP-Server verfügbar ist. ==== Falls ein DHCP-Server zur Verfügung steht, wählen Sie im nächsten Menü btn:[Yes], um die Netzwerkschnittstelle automatisch einrichten zu lassen. Dieser Vorgang kann einige Sekunden dauern. [[bsdinstall-net-ipv4-dhcp]] .Auswählen der IPv4-Konfiguration über DHCP image::bsdinstall-configure-network-interface-ipv4-dhcp.png[] Wenn kein DHCP-Server zur Verfügung steht, wählen Sie btn:[No] und tragen Sie die folgenden Informationen in das Menü ein: [[bsdinstall-net-ipv4-static]] .Statische IPv4-Konfiguration image::bsdinstall-configure-network-interface-ipv4-static.png[] * `IP Address` - Die IPv4-Adresse, welche diesem Computer zugewiesen werden soll. Diese Adresse muss eindeutig sein und darf nicht bereits von einem anderen Gerät im lokalen Netzwerk verwendet werden. * `Subnet Mask` - Die Subnetzmaske des Netzwerks. * `Default Router` - Die IP-Adresse des Defaultrouters im Netzwerk. Das nächste Menü fragt, ob die Schnittstelle für IPv6 konfiguriert werden soll. Falls IPv6 verfügbar ist und verwendet werden soll, wählen Sie btn:[Yes] aus. [[bsdinstall-net-ipv6]] .Auswahl von IPv6 image::bsdinstall-configure-network-interface-ipv6.png[] IPv6 besitzt ebenfalls zwei Arten der Konfiguration. _StateLess Address AutoConfiguration_, (SLAAC) wird automatisch die richtigen Informationen von einem lokalen Router abfragen. Lesen Sie http://tools.ietf.org/html/rfc4862[http://tools.ietf.org/html/rfc4862] für weitere Informationen. Eine _statische_ Konfiguration verlangt die manuelle Eingabe von Netzwerkinformationen. Wenn ein IPv6-Router verfügbar ist, wählen Sie im nächsten Menü btn:[Yes], um die Netzwerkschnittstelle automatisch konfigurieren zu lassen. [[bsdinstall-net-ipv6-slaac]] .Auswahl der IPv6SLAAC-Konfiguration image::bsdinstall-configure-network-interface-slaac.png[] Wenn kein IPv6-Router zur Verfügung steht, wählen Sie btn:[No] und tragen Sie die folgenden Adressinformationen in dieses Menü ein: [[bsdinstall-net-ipv6-static]] .Statische IPv6-Konfiguration image::bsdinstall-configure-network-interface-ipv6-static.png[] * `IPv6 Address` - Die zugewiesene IPv6-Adresse, welche dem Computer zugeteilt werden soll. Diese Adresse muss eindeutig sein und nicht bereits von einer anderen Netzwerkkomponente im lokalen Netzwerk verwendet werden. * `Default Router` - Die IPv6-Adresse des Defaultrouters im Netzwerk. Das letzte Menü der Netzwerkkonfiguration konfiguriert den _Domain Name System_ (DNS) Resolver, welcher Hostnamen von und zu Netzwerkadressen umwandelt. Falls DHCP oder SLAAC verwendet wurde, um die Netzwerkschnittstelle zu konfigurieren, ist die Konfiguration für den Resolver möglicherweise bereits eingetragen. Andernfalls geben Sie den lokalen Netzwerkdomänennamen in das Feld `Search` ein. `DNS #1` und `DNS #2` sind die IPv4- und/oder IPv6-Adressen der lokalen DNS-Server. Zumindest ein DNS-Server wird benötigt. [[bsdinstall-net-dns-config]] .DNS-Konfiguration image::bsdinstall-configure-network-ipv4-dns.png[] Sobald die Schnittstelle konfiguriert ist, bestimmen Sie einen Spiegelserver, welcher in der gleichen Region auf der Welt beheimatet ist, wie der Computer, auf dem FreeBSD installiert wird. Dateien können so viel schneller übertragen werden, wenn der Spiegelserver sich näher am Zielcomputer befindet und die Installationszeit wird somit reduziert. [[bsdinstall-netinstall-mirror]] .Einen Spiegelserver wählen image::bsdinstall-netinstall-mirrorselect.png[] [[bsdinstall-install-trouble]] == Fehlerbehebung Dieser Abschnitt behandelt einfache Fehlerbehebungen für die Installation, wie beispielsweise häufig auftretende Fehler, die von Anwendern berichtet wurden. Überprüfen Sie die Hardware Notes (link:https://www.FreeBSD.org/releases/[https://www.freebsd.org/releases/]) nach der Version von FreeBSD, um sicher zu stellen, dass die Hardware auch unterstützt wird. Wenn die Hardware unterstützt wird und Sie immer noch Abstürze oder andere Probleme erleben, müssen Sie einen eigenen Kernel bauen. Diese Prozedur wird in crossref:kernelconfig[kernelconfig,Konfiguration des FreeBSD-Kernels ] beschrieben. Das erlaubt es, Unterstützung für Geräte, die im [.filename]#GENERIC#-Kernel nicht vorhanden sind, hinzuzufügen. Der Kernel ist mit der Annahme konfiguriert, dass die Hardwaregeräte sich in ihren Fabrikeinstellungen in Bezug auf IRQs, I/O-Adressen und DMA-Kanälen befinden. Wenn die Hardware neu konfiguriert wurde, werden Sie möglicherweise die Konfiguration des Kernels bearbeiten und diesen neu erstellen müssen, um FreeBSD mitzuteilen, wo es gewisse Dinge finden kann. [NOTE] ==== Manche Installationsprobleme können Aktualisierung der Firmware auf verschiedenen Hardwarekomponenten verhindert oder verringert werden, meistens am Mainboard. Mit Mainboard-Firmware ist für gewöhnlich das BIOS gemeint. Die meisten Mainboard- und Computerhersteller haben eine Webseite mit Aktualisierungen und Informationen zur Durchführung. Hersteller raten meist von einer Aktualisierung des Mainboard-BIOS ab, außer es gibt einen guten Grund dafür, wie beispielsweise eine kritische Aktualisierung. Der Aktualisierungsvorgang _kann_ schiefgehen, was das BIOS unvollständig macht und den Computer nicht mehr starten lässt. ==== Wenn das System während der Geräteerkennung beim Starten hängt oder sich während der Installation merkwürdig verhält, ist ACPI vielleicht der Übeltäter. FreeBSD macht auf i386- und amd64-Plattformen starken Gebrauch vom ACPI-Dienst, um dem System bei der Konfiguration während des Startvorgangs zu helfen. Leider existieren immer noch Fehler im ACPI-Treiber, in den Mainboards und der BIOS-Firmware. ACPI kann durch setzen der Einstellung `hint.acpi.0.disabled` im dritten Teil des Bootloaders deaktiviert werden: [source,shell] .... set hint.acpi.0.disabled="1" .... Dies wird nach jedem Neustart des Systems wieder zurückgesetzt, also ist es notwendig, die Zeile `hint.acpi.0.disabled="1"` zu der Datei [.filename]#/boot/loader.conf# hinzuzufügen. Weitere Informationen über den Bootloader lassen sich in crossref:boot[boot-synopsis,“Übersicht”] nachlesen. [[using-live-cd]] == Verwendung der Live-CD Das Willkommensmenü von bsdinstall, welches in <> gezeigt wird, enthält eine btn:[Live CD] Option. Die Live-CD ist für Benutzer, die sich fragen, ob FreeBSD das richtige Betriebssystem für sie ist und die vor der Installation noch einige Merkmale und Eigenschaften testen wollen. Die folgenden Punkte sollten beachtet werden, bevor die btn:[Live CD] benutzt wird: * Um Zugriff auf das System zu bekommen, wird eine Authentifizierung benötigt. Der Benutzername ist `root` und das Kennwort bleibt leer. * Da das System direkt von dem Installationsmedium ausgeführt wird, ist die Geschwindigkeit deutlich langsamer als bei einem System, das auf einer Festplatte installiert ist. * Diese Option enthält nur eine Eingabeaufforderung und keine graphische Oberfläche. diff --git a/documentation/content/de/books/handbook/multimedia/_index.adoc b/documentation/content/de/books/handbook/multimedia/_index.adoc index b8a98c665c..e81456b3cf 100644 --- a/documentation/content/de/books/handbook/multimedia/_index.adoc +++ b/documentation/content/de/books/handbook/multimedia/_index.adoc @@ -1,1074 +1,1074 @@ --- title: Kapitel 7. Multimedia part: Teil II. Oft benutzte Funktionen prev: books/handbook/desktop next: books/handbook/kernelconfig showBookMenu: true weight: 10 path: "/books/handbook/multimedia/" --- [[multimedia]] = Multimedia :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 7 :partnums: :source-highlighter: rouge :experimental: :images-path: books/handbook/multimedia/ 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::[] [[multimedia-synopsis]] == Übersicht FreeBSD unterstützt viele unterschiedliche Soundkarten, die Benutzern den Genuss von Highfidelity-Klängen auf dem Computer ermöglichen. Dazu gehört unter anderem die Möglichkeit, Tonquellen in den Formaten MPEG Audio Layer 3 (MP3), Waveform Audio File (WAV), Ogg Vorbis und vielen weiteren Formaten aufzunehmen und wiederzugeben. Darüber hinaus enthält die FreeBSD Ports-Sammlung Anwendungen, die das Bearbeiten von aufgenommenen Tonspuren, das Hinzufügen von Klangeffekten und die Kontrolle der angeschlossenen MIDI-Geräte erlauben. FreeBSD unterstützt auch die Wiedergabe von Videos und DVDs. Die FreeBSD Ports-Sammlung enthält Anwendungen, um verschiedene Video-Medien wiederzugeben, zu kodieren und zu konvertieren. Dieses Kapitel beschreibt die Einrichtung von Soundkarten, Video-Wiedergabe, TV-Tuner Karten und Scannern unter FreeBSD. Es werden auch einige Anwendungen beschrieben, die für die Verwendung dieser Geräte zur Verfügung stehen. Dieses Kapitel behandelt die folgenden Punkte: * Konfiguration einer Soundkarte in FreeBSD. * Fehlersuche bei Sound Einstellungen. * Wiedergabe und Kodierung von MP3s und anderen Audio-Formaten. * Vorbereitung des Systems für die Wiedergabe von Videos. * Wiedergabe von DVDs, [.filename]#.mpg#- und [.filename]#.avi#-Dateien. * Rippen von CDs und DVDs. * Konfiguration von TV-Karten. * Installation und Konfiguration von MythTV. * Konfiguration von Scannern * Konfiguration von Bluetooth-Kopfhörern Bevor Sie dieses Kapitel lesen, sollten Sie: * Wissen, wie Sie Anwendungen installieren (crossref:ports[ports,Installieren von Anwendungen: Pakete und Ports]). [[sound-setup]] == Soundkarten einrichten Bevor Sie die Konfiguration beginnen, sollten Sie in Erfahrung bringen welches Soundkartenmodell und welcher Chip benutzt wird. FreeBSD unterstützt eine Reihe Soundkarten. Die link:{u-rel120-hardware}[Hardware-Notes] zählen alle unterstützten Karten und deren Treiber für FreeBSD auf. Um die Soundkarte benutzen zu können, muss der richtige Gerätetreiber geladen werden. Am einfachsten ist es, das Kernelmodul für die Soundkarte mit man:kldload[8] zu laden. Dieses Beispiel lädt den Treiber für einen integrierten Chipsatz, basierend auf der Intel Spezifikation: [source,shell] .... # kldload snd_hda .... Um den Treiber automatisch beim Systemstart zu laden, fügen Sie folgende Zeile in [.filename]#/boot/loader.conf# ein: [.programlisting] .... snd_hda_load="YES" .... Weitere ladbare Soundmodule sind in [.filename]#/boot/defaults/loader.conf# aufgeführt. Wenn Sie nicht sicher sind, welchen Gerätetreiber Sie laden müssen, laden Sie das Modul [.filename]#snd_driver#: [source,shell] .... # kldload snd_driver .... Der Treiber [.filename]#snd_driver# ist ein Meta-Treiber, der alle gebräuchlichen Treiber lädt und die Suche nach dem richtigen Treiber vereinfacht. Durch Hinzufügen des Meta-Treibers in [.filename]#/boot/loader.conf# können alternativ alle Audio-Treiber geladen werden. Um zu ermitteln, welcher Treiber für die Soundkarte vom Meta-Treiber [.filename]#snd_driver# geladen wurde, geben Sie `cat /dev/sndstat` ein. === Soundkarten in der Kernelkonfiguration einrichten Die Unterstützung für die Soundkarte kann auch direkt in den Kernel kompiliert werden. Weitere Informationen über den Bau eines Kernels finden Sie im crossref:kernelconfig[kernelconfig,Konfiguration des FreeBSD-Kernels]. Bei der Verwendung eines eigenen Kernels müssen Sie sicherstellen, dass der Treiber für das Audio-Framework in der Kernelkonfigurationsdatei vorhanden ist: [.programlisting] .... device sound .... Als Nächstes muss die Unterstützung für die Soundkarte hinzugefügt werden. Um das Beispiel mit dem integrierten Intel Audio-Chipsatz aus dem vorherigen Abschnitt fortzusetzen, verwenden Sie die folgende Zeile in der Kernelkonfigurationsdatei: [.programlisting] .... device snd_hda .... Lesen Sie die Manualpage des Treibers, um den entsprechenden Gerätenamen herauszufinden. Nicht PnP-fähige ISA-Soundkarten benötigen eventuell Einstellungen, wie IRQ und I/O-Port in [.filename]#/boot/device.hints#. Während des Systemstarts liest der man:loader[8] diese Datei und reicht die Einstellungen an den Kernel weiter. Für eine alte Creative SoundBlaster(R) 16 ISA-Karte, die sowohl den man:snd_sbc[4]- als auch den `snd_sb16`-Treiber benötigt, müssen die folgenden Zeilen in die Kernelkonfigurationsdatei eingetragen werden: [.programlisting] .... device snd_sbc device snd_sb16 .... Wenn die Karte den I/O-Port `0x220` und IRQ `5` benutzt, müssen folgende Zeilen zusätzlich in [.filename]#/boot/device.hints# hinzugefügt werden: [.programlisting] .... hint.sbc.0.at="isa" hint.sbc.0.port="0x220" hint.sbc.0.irq="5" hint.sbc.0.drq="1" hint.sbc.0.flags="0x15" .... Die Syntax für [.filename]#/boot/device.hints# wird in man:sound[4], sowie in der Manualpage des jeweiligen Treibers beschrieben. Das Beispiel verwendet die vorgegebenen Werte. Falls die Karteneinstellungen andere Werte vorgeben, müssen die Werte in der Kernelkonfiguration angepasst werden. Weitere Informationen zu dieser Soundkarte finden Sie in man:snd_sbc[4]. [[sound-testing]] === Die Soundkarte testen Nachdem Sie den neuen Kernel gestartet oder das erforderliche Modul geladen haben, sollte die Soundkarte erkannt werden. Führen Sie `dmesg | grep pcm` aus, um dies zu überprüfen. Diese Ausgabe stammt von einem System mit einem integrierten Conexant CX20590 Chipsatz: [source,shell] .... pcm0: at nid 5 on hdaa0 pcm1: at nid 6 on hdaa0 pcm2: at nid 31,25 and 35,27 on hdaa1 .... Der Status der Karte kann auch mit diesem Kommando geprüft werden: [source,shell] .... # cat /dev/sndstat FreeBSD Audio Driver (newpcm: 64bit 2009061500/amd64) Installed devices: pcm0: (play) pcm1: (play) pcm2: (play/rec) default .... Die Ausgabe kann für jede Soundkarte anders aussehen. Wenn das Gerät [.filename]#pcm# nicht erscheint, prüfen Sie die Kernelkonfigurationsdatei und stellen Sie sicher, dass der richtige Treiber geladen oder in den Kernel kompiliert wurde. Im nächsten Abschnitt werden häufig auftretende Probleme sowie deren Lösungen besprochen. Jetzt sollte die Soundkarte unter FreeBSD funktionieren. Wenn ein CD- oder DVD-Laufwerk an die Soundkarte angeschlossen ist, können Sie jetzt mit man:cdcontrol[1] eine CD abspielen: [source,shell] .... % cdcontrol -f /dev/acd0 play 1 .... [WARNING] ==== Audio CDs besitzen eine spezielle Kodierung. Daher sollten sie nicht mit man:mount[8] in das Dateisystem eingehangen werden. ==== Es gibt viele Anwendungen, wie package:audio/workman[], die eine bessere Benutzerschnittstelle besitzen. Zur Wiedergabe von MP3-Audiodateien kann package:audio/mpg123[] installiert werden. Eine weitere schnelle Möglichkeit die Karte zu prüfen, ist es, Daten an das Gerät [.filename]#/dev/dsp# zu senden: [source,shell] .... % cat Datei > /dev/dsp .... Für [.filename]#Datei# kann eine beliebige Datei verwendet werden. Wenn Sie einige Geräusche hören, funktioniert die Soundkarte. [NOTE] ==== Die Gerätedateien [.filename]#/dev/dsp*# werden automatisch erzeugt, wenn sie das erste Mal benötigt werden. Werden sie nicht verwendet, sind sie hingegen nicht vorhanden und tauchen daher auch nicht in der Ausgabe von man:ls[1] auf. ==== [[bluetooth-headset]] === Konfiguration von Bluetooth-Soundgeräten Die Verbindung zu einem Bluetooth-Gerät wird in diesem Abschnitt nicht erläutert. Dazu finden Sie weitere Informationen in crossref:advanced-networking[network-bluetooth,“Bluetooth”]. Damit Bluetooth zusammen mit dem Soundsystem von FreeBSD funktioniert, müssen Benutzer zuerst package:audio/virtual_oss[] installieren: [source,shell] .... # pkg install virtual_oss .... package:audio/virtual_oss[] setzt voraus, dass `cuse` in den Kernel geladen wird: [source,shell] .... # kldload cuse .... Führen Sie folgenden Befehl aus, damit `cuse` beim Systemstart automatisch geladen wird: [source,shell] .... # sysrc -f /boot/loader.conf cuse_load=yes .... Um Kopfhörer mit package:audio/virtual_oss[] zu benutzten, muss nach der Verbindung mit einem Bluetooth-Audiogerät ein virtuelles Gerät erstellt werden: [source,shell] .... # virtual_oss -C 2 -c 2 -r 48000 -b 16 -s 768 -R /dev/null -P /dev/bluetooth/headphones -d dsp .... [NOTE] ==== `_headphones_` ist in diesem Beispiel ein Hostname aus [.filename]#/etc/bluetooth/hosts#. Stattdessen kann auch `BT_ADDR` verwendet werden. ==== Weitere Informationen finden Sie in man:virtual_oss[8]. [[troubleshooting]] === Fehlerbehebung <> zeigt typische Fehlermeldungen sowie deren Lösungen: [[multimedia-sound-common-error-messages]] .Typische Fehlermeldungen [cols="30%,70%", frame="none", options="header"] |=== | Fehler | Lösung |`sb_dspwr(XX) timed out` | Der I/O-Port ist nicht korrekt angegeben. |`bad irq XX` | Der IRQ ist falsch angegeben. Stellen Sie sicher, dass der angegebene IRQ mit dem Sound IRQ übereinstimmt. |`xxx: gus pcm not attached, out of memory` | Es ist nicht genug Speicher verfügbar, um das Gerät zu betreiben. |`xxx: can't open /dev/dsp!` | -Überprüfen Sie mit `fstat | grep dsp` ob eine andere Anwendung das Gerät geöffnet hat. Häufige Störenfriede sind esound oder die Sound-Unterstützung von KDE. +Überprüfen Sie mit `fstat \| grep dsp` ob eine andere Anwendung das Gerät geöffnet hat. Häufige Störenfriede sind esound oder die Sound-Unterstützung von KDE. |=== Moderne Grafikkarten beinhalten oft auch ihre eigenen Soundtreiber, um HDMI zu verwenden. Diese Audiogeräte werden manchmal vor der eigentlichen, separaten Soundkarte aufgeführt und dadurch nicht als das Standardgerät zum Abspielen von Tönen benutzt. Um zu prüfen, ob das der Fall ist, führen Sie dmesg aus und suchen Sie nach der Zeichenfolge `pcm`. Die Ausgabe sieht in etwa so aus: [.programlisting] .... ... hdac0: HDA Driver Revision: 20100226_0142 hdac1: HDA Driver Revision: 20100226_0142 hdac0: HDA Codec #0: NVidia (Unknown) hdac0: HDA Codec #1: NVidia (Unknown) hdac0: HDA Codec #2: NVidia (Unknown) hdac0: HDA Codec #3: NVidia (Unknown) pcm0: at cad 0 nid 1 on hdac0 pcm1: at cad 1 nid 1 on hdac0 pcm2: at cad 2 nid 1 on hdac0 pcm3: at cad 3 nid 1 on hdac0 hdac1: HDA Codec #2: Realtek ALC889 pcm4: at cad 2 nid 1 on hdac1 pcm5: at cad 2 nid 1 on hdac1 pcm6: at cad 2 nid 1 on hdac1 pcm7: at cad 2 nid 1 on hdac1 ... .... In diesem Beispiel wurde die Grafikkarte (`NVidia`) vor der Soundkarte (`Realtek ALC889`) aufgeführt. Um die Soundkarte als Standardabspielgerät einzusetzen, ändern Sie `hw.snd.default_unit` auf die Einheit, welche für das Abspielen benutzt werden soll: [source,shell] .... # sysctl hw.snd.default_unit=n .... Hier repräsentiert `n` die Nummer der Soundkarte, die verwendet werden soll, in diesem Beispiel also `4`. Sie können diese Änderung dauerhaft machen, indem Sie die folgende Zeile in [.filename]#/etc/sysctl.conf# hinzufügen: [.programlisting] .... hw.snd.default_unit=4 .... [[sound-multiple-sources]] === Mehrere Tonquellen abspielen Oft sollen mehrere Tonquellen gleichzeitig abgespielt werden. FreeBSD verwendet dazu _virtuelle Tonkanäle_. Virtuelle Kanäle mischen die Tonquellen im Kernel, sodass mehrere Kanäle benutzt werden können, als von der Hardware unterstützt werden. Drei man:sysctl[8] Optionen stehen zur Konfiguration der virtuellen Kanäle zur Verfügung: [source,shell] .... # sysctl dev.pcm.0.play.vchans=4 # sysctl dev.pcm.0.rec.vchans=4 # sysctl hw.snd.maxautovchans=4 .... Im Beispiel werden vier virtuelle Kanäle eingerichtet, eine im Normalfall ausreichende Anzahl. Sowohl `dev.pcm.0.play.vchans=4` und `dev.pcm.0.rec.vchans=4` sind die Anzahl der virtuellen Kanäle des Geräts [.filename]#pcm0#, die fürs Abspielen und Aufnehmen verwendet werden und sie können konfiguriert werden, sobald das Gerät existiert. Da das Modul [.filename]#pcm# unabhängig von den Hardware-Treibern geladen werden kann, gibt `hw.snd.maxautovchans` die Anzahl der virtuellen Kanäle an, die später eingerichtete Audiogeräte erhalten. Lesen Sie man:pcm[4] für weitere Informationen. [NOTE] ==== Die Anzahl der virtuellen Kanäle kann nicht geändert werden, solange das Gerät genutzt wird. Schließen Sie daher zuerst alle Programme wie Musikabspielprogramme oder Sound-Daemonen, die auf dieses Gerät zugreifen. ==== Die korrekte [.filename]#pcm#-Gerätedatei wird automatisch zugeteilt, wenn ein Programm das Gerät [.filename]#/dev/dsp0# anfordert. === Den Mixer einstellen Die Voreinstellungen des Mixers sind im Treiber man:pcm[4] fest kodiert. Es gibt zwar viele Anwendungen und Dienste, die den Mixer einstellen können und die eingestellten Werte bei jedem Start wieder setzen, am einfachsten ist es allerdings, die Standardwerte für den Mixer direkt im Treiber einzustellen. Der Mixer kann mit den entsprechenden Werten in [.filename]#/boot/device.hints# eingestellt werden: [.programlisting] .... hint.pcm.0.vol="50" .... Die Zeile setzt die Lautstärke des Mixers beim Laden des Moduls man:pcm[4] auf den Wert `50`. [[sound-mp3]] == MP3-Audio Dieser Abschnitt beschreibt einige unter FreeBSD verfügbare MP3-Player. Zudem wird beschrieben, wie Audio-CDs gerippt und MP3s kodiert und dekodiert werden. [[mp3-players]] === MP3-Player Ein beliebter graphischer MP3-Player ist Audacious, welcher WinAmp-Skins und zusätzliche Plugins unterstützt. Die Benutzerschnittstelle ist leicht zu erlernen und enthält eine Playlist, einen graphischen Equalizer und vieles mehr. Diejenigen, die bereits mit WinAmp vertraut sind, werden Audacious sehr leicht zu benutzen finden. Unter FreeBSD kann Audacious als Port oder Paket package:multimedia/audacious[] installiert werden. Audacious ist ein Ableger von XMMS. Das Paket package:audio/mpg123[] ist ein alternativer, kommandozeilenorientierter MP3-Player. Nach der Installation kann die abzuspielende MP3-Datei auf der Kommandozeile angegeben werden. Geben Sie auch das entsprechende Soundkarte an, falls das System über mehrere Audiogeräte verfügt: [source,shell] .... # mpg123 -a /dev/dsp1.0 Foobar-GreatestHits.mp3 High Performance MPEG 1.0/2.0/2.5 Audio Player for Layer 1, 2 and 3 version 1.18.1; written and copyright by Michael Hipp and others free software (LGPL) without any warranty but with best wishes Playing MPEG stream from Foobar-GreatestHits.mp3 ... MPEG 1.0 layer III, 128 kbit/s, 44100 Hz joint-stereo .... Weitere MP3-Player stehen in der FreeBSD Ports-Sammlung zur Verfügung. [[rip-cd]] === CD-Audio Tracks rippen Bevor eine ganze CD oder einen CD-Track in das MP3-Format umgewandelt werden kann, müssen die Audiodaten von der CD auf die Festplatte gerippt werden. Dabei werden die CDDA (CD Digital Audio) Rohdaten in WAV-Dateien kopiert. Die Anwendung `cdda2wav`, die im package:sysutils/cdrtools[] Paket enthalten ist, kann zum Rippen der Audiodaten von CDs genutzt werden. Wenn die Audio CD in dem Laufwerk liegt, kann der folgende Befehl als `root` ausgeführt werden, um eine ganze CD in einzelne WAV-Dateien zu rippen: [source,shell] .... # cdda2wav -D 0,1,0 -B .... In diesem Beispiel bezieht sich der Schalter `-D _0,1,0_` auf das SCSI-Gerät [.filename]#0,1,0#, das die zu rippende CD enthält. Benutzen Sie `cdrecord -scanbus` um die richtigen Geräteparameter für das System zu bestimmen. Um einzelne Tracks zu rippen, benutzen Sie `-t` wie folgt: [source,shell] .... # cdda2wav -D 0,1,0 -t 7 .... Um mehrere Tracks zu rippen, zum Beispiel die Tracks eins bis sieben, können Sie wie folgt einen Bereich angeben: [source,shell] .... # cdda2wav -D 0,1,0 -t 1+7 .... Wenn Sie von einem ATAPI (IDE) CD-ROM-Laufwerk rippen, geben Sie den Gerätenamen anstelle der SCSI-Gerätenummer an. Dieses Beispiel rippt Track 7 von einem IDE-Laufwerk: [source,shell] .... # cdda2wav -D /dev/acd0 -t 7 .... Alternativ können mit `dd` ebenfalls Audio-Stücke von ATAPI-Laufwerken kopiert werden. Dies wird in crossref:disks[duplicating-audiocds,“Kopieren von Audio-CDs”] erläutert. [[mp3-encoding]] === MP3-Dateien kodieren und dekodieren Lame ist ein weitverbreiteter MP3-Encoder, der als Port package:audio/lame[] installiert werden kann. Wegen Patentproblemen ist kein Paket verfügbar. Der folgende Befehl konvertiert die gerippte WAV-Datei [.filename]#audio01.wav# in [.filename]#audio01.mp3# um: [source,shell] .... # lame -h -b 128 --tt "Foo Liedtietel" --ta "FooBar Künstler" --tl "FooBar Album" \ --ty "2014" --tc "Gerippt und kodiert von Foo" --tg "Musikrichtung" audio01.wav audio01.mp3 .... 128 kbits ist die gewöhnliche MP3-Bitrate, wohingegen die Bitraten 160 und 192 kbits eine höhere Qualität bieten. Je höher die Bitrate ist, desto mehr Speicherplatz benötigt die resultierende MP3-Datei. Die Option `-h` verwendet den "higher quality but a little slower" (höhere Qualität, aber etwas langsamer) Modus. Die Schalter, die mit `--t` beginnen, sind ID3-Tags, die in der Regel Informationen über das Lied enthalten und in die MP3-Datei eingebettet sind. Weitere Optionen können in der Manualpage von lame nachgelesen werden. Um aus MP3-Dateien eine Audio CD zu erstellen, müssen diese zuerst in ein nicht komprimiertes Format umgewandelt werden. Verwenden Sie XMMS um die Datei im WAV-Format zu schreiben und mpg123, um die MP3-Datei in rohe PCM-Audiodaten umzuwandeln. Um [.filename]#audio01.mp3# mit mpg123 umzuwandeln, geben Sie den Namen der PCM-Datei an: [source,shell] .... # mpg123 -s audio01.mp3 > audio01.pcm .... So verwenden Sie XMMS um eine MP3-Datei in das WAV-Format zu konvertieren: [.procedure] *Procedure: Mit XMMS in das WAV-Format konvertieren* . Starten Sie XMMS. . Klicken Sie mit der rechten Maustaste, um das XMMS-Menu zu öffnen. . Wählen Sie `Preferences` im Untermenü `Options`. . Ändern Sie das Output-Plugin in "Disk Writer Plugin". . Drücken Sie `Configure`. . Geben Sie ein Verzeichnis ein, in das Sie die unkomprimierte Datei schreiben wollen. . Laden Sie die MP3-Datei wie gewohnt in XMMS mit einer Lautstärke von 100% und einem abgeschalteten EQ. . Drücken Sie `Play` und es wird so aussehen, als spiele XMMS die MP3-Datei ab, aber keine Musik ist zu hören. Der Player überspielt die MP3-Datei in eine Datei. . Vergessen Sie nicht, das Output-Plugin wieder in den Ausgangszustand zurückzusetzen um wieder MP3-Dateien anhören zu können. cdrecord kann mit beiden Formaten Audio-CDs erstellen. Der Dateikopf von WAV-Dateien erzeugt am Anfang des Stücks ein Knacken. Der Dateikopf mit dem Port oder Paket package:audio/sox[] entfernt werden: [source,shell] .... % sox -t wav -r 44100 -s -w -c 2 track.wav track.raw .... Lesen Sie crossref:disks[creating-cds,“Erstellen und Verwenden von CDs”], um mehr Informationen zur Benutzung von CD-Brennern mit FreeBSD zu erhalten. [[video-playback]] == Videos wiedergeben Bevor Sie beginnen, sollten Sie das Modell und den benutzten Chip der Videokarte kennen. Obwohl Xorg viele Videokarten unterstützt, können nicht alle Karten Videos schnell genug wiedergeben. Eine Liste der Erweiterungen, die der Xorg-Server für eine Videokarte unterstützt, erhalten Sie unter laufendem Xorg mit `xdpyinfo`. Halten Sie eine kurze MPEG-Datei bereit, mit der Sie Wiedergabeprogramme und deren Optionen testen können. Da einige DVD-Spieler in der Voreinstellung das DVD-Gerät mit [.filename]#/dev/dvd# ansprechen oder diesen Namen fest einkodiert haben, ist es vielleicht hilfreich symbolische Links auf die richtigen Geräte anzulegen: [source,shell] .... # ln -sf /dev/acd0 /dev/dvd .... Aufgrund der Beschaffenheit man:devfs[5] gehen gesondert angelegte Links wie diese bei einem Neustart des Systems verloren. Damit die symbolischen Links automatisch beim Neustart des Systems angelegt werden, fügen Sie die folgende Zeile in [.filename]#/etc/devfs.conf# ein: [.programlisting] .... link acd0 dvd .... Das Entschlüsseln von DVDs erfordert den Aufruf bestimmter Funktionen, sowie Schreibzugriff auf das DVD-Gerät. Xorg benutzt Shared-Memory und es wird empfohlen, die nachstehenden man:sysctl[8]-Variablen auf die gezeigten Werte zu erhöhen: [.programlisting] .... kern.ipc.shmmax=67108864 kern.ipc.shmall=32768 .... [[video-interface]] === Video-Schnittstellen Es gibt einige Möglichkeiten, Videos unter Xorg abzuspielen. Welche Möglichkeit funktioniert, hängt stark von der verwendeten Hardware ab. Gebräuchliche Video-Schnittstellen sind: . Xorg: normale Ausgabe über Shared-Memory. . XVideo: Eine Erweiterung der Xorg-Schnittstelle, die Videos in jedem X11-Drawable anzeigen kann. Diese Erweiterung bietet auch auf leistungsschwachen Maschinen eine gute Qualität der Wiedergabe. Der nächste Abschnitt beschreibt, wie Sie feststellen, ob diese Erweiterung ausgeführt wird. . SDL: Simple DirectMedia Layer ist eine portable Schnittstelle für verschiedene Betriebssysteme, mit denen Anwendungen plattformunabhängig und effizient Ton und Grafik benutzen können. SDL bietet eine hardwarenahe Schnittstelle, die manchmal schneller ist als die Xorg-Schnittstelle. Unter FreeBSD kann SDL über das Paket oder den Port package:devel/sdl20[] installiert werden. . DGA: Direct Graphics Access ist eine Xorg-Erweiterung die es Anwendungen erlaubt, am Xorg-Server vorbei direkt in den Framebuffer zu schreiben. Da die Anwendung und der Xorg-Server auf gemeinsame Speicherbereiche zugreifen, müssen die Anwendungen unter dem Benutzer `root` laufen. Die DGA-Erweiterung kann mit man:dga[1] getestet werden. Wenn DGA ausgeführt wird, ändert sich die Farbe des Bildschrims, wenn eine Taste gedrückt wird. Drücken Sie zum Beenden kbd:[q]. . SVGAlib: Eine Schnittstelle zur Grafikausgabe auf der Konsole. [[video-interface-xvideo]] ==== XVideo Ob die Erweiterung läuft, entnehmen Sie der Ausgabe von `xvinfo`: [source,shell] .... % xvinfo .... XVideo wird untertsützt, wenn die Ausgabe in etwa wie folgt aussieht: [source,shell] .... X-Video Extension version 2.2 screen #0 Adaptor #0: "Savage Streams Engine" number of ports: 1 port base: 43 operations supported: PutImage supported visuals: depth 16, visualID 0x22 depth 16, visualID 0x23 number of attributes: 5 "XV_COLORKEY" (range 0 to 16777215) client settable attribute client gettable attribute (current value is 2110) "XV_BRIGHTNESS" (range -128 to 127) client settable attribute client gettable attribute (current value is 0) "XV_CONTRAST" (range 0 to 255) client settable attribute client gettable attribute (current value is 128) "XV_SATURATION" (range 0 to 255) client settable attribute client gettable attribute (current value is 128) "XV_HUE" (range -180 to 180) client settable attribute client gettable attribute (current value is 0) maximum XvImage size: 1024 x 1024 Number of image formats: 7 id: 0x32595559 (YUY2) guid: 59555932-0000-0010-8000-00aa00389b71 bits per pixel: 16 number of planes: 1 type: YUV (packed) id: 0x32315659 (YV12) guid: 59563132-0000-0010-8000-00aa00389b71 bits per pixel: 12 number of planes: 3 type: YUV (planar) id: 0x30323449 (I420) guid: 49343230-0000-0010-8000-00aa00389b71 bits per pixel: 12 number of planes: 3 type: YUV (planar) id: 0x36315652 (RV16) guid: 52563135-0000-0000-0000-000000000000 bits per pixel: 16 number of planes: 1 type: RGB (packed) depth: 0 red, green, blue masks: 0x1f, 0x3e0, 0x7c00 id: 0x35315652 (RV15) guid: 52563136-0000-0000-0000-000000000000 bits per pixel: 16 number of planes: 1 type: RGB (packed) depth: 0 red, green, blue masks: 0x1f, 0x7e0, 0xf800 id: 0x31313259 (Y211) guid: 59323131-0000-0010-8000-00aa00389b71 bits per pixel: 6 number of planes: 3 type: YUV (packed) id: 0x0 guid: 00000000-0000-0000-0000-000000000000 bits per pixel: 0 number of planes: 0 type: RGB (packed) depth: 1 red, green, blue masks: 0x0, 0x0, 0x0 .... Einige der aufgeführten Formate, wie YUV2 oder YUV12 existieren in machen XVideo-Implementierungen nicht. Dies kann zu Problemen mit einigen Spielern führen. XVideo wird wahrscheinlich von der Karte nicht unterstützt, wenn die Ausgabe wie folgt aussieht: [source,shell] .... X-Video Extension version 2.2 screen #0 no adaptors present .... Wenn die XVideo-Erweiterung auf der Karte nicht läuft, wird es nur etwas schwieriger, die Anforderungen für die Wiedergabe von Videos zu erfüllen. [[video-ports]] === Video-Anwendungen Dieser Abschnitt behandelt Anwendungen aus der FreeBSD-Ports-Sammlung, die für die Wiedergabe von Videos genutzt werden können. [[video-mplayer]] ==== MPlayer und MEncoder MPlayer ist ein auf Geschwindigkeit und Flexibilität ausgelegter Video-Spieler für die Kommandozeile mit optionaler graphischer Oberfläche. Weitere graphische Oberflächen für MPlayer stehen in der FreeBSD Ports-Sammlung zur Verfügung. MPlayer kann als Paket oder Port package:multimedia/mplayer[] installiert werden. Der Bau von MPlayer berücksichtigt die vorhandene Hardware und es können zahlreiche Optionen ausgewählt werden. Aus diesen Gründen ziehen es manche Benutzer vor, den Port zu übersetzen, anstatt das Paket zu installieren. Die Optionen sollten beim Bau des Ports überprüft werden, um dem Umfang der Unterstützung, mit dem der Port gebaut wird, zu bestimmen. Wenn eine Option nicht ausgewählt wird, ist MPlayer nicht in der Lage, diese Art von Video-Format wiederzugeben. Mit den Pfeiltasten und der Leertaste können die erforderlichen Formate ausgewählt werden. Wenn Sie fertig sind, drücken Sie kbd:[Enter], um den Bau und die Installation fortzusetzen. In der Voreinstellung wird das Paket oder der Port das `mplayer`-Kommandozeilenprogramm und das graphische Programm `gmplayer` bauen. Um Videos zu dekodieren, installieren Sie den Port package:multimedia/mencoder[]. Aus lizenzrechtlichen Gründen steht ein Paket von MEncoder nicht zur Verfügung. MPlayer erstellt beim ersten Start [.filename]#~/.mplayer# im Heimatverzeichnis des Benutzers. Dieses Verzeichnis enthält die voreingestellten Konfigurationseinstellungen für den Benutzer. Dieser Abschnitt beschreibt nur ein paar wenige Anwendungsmöglichkeiten. Eine vollständige Beschreibung der zahlreichen Möglichkeiten finden Sie in der Manualpage von mplayer(1). Um die Datei [.filename]#testfile.avi# abzuspielen, geben Sie die Video-Schnittstelle mit `-vo` an: [source,shell] .... % mplayer -vo xv testfile.avi .... [source,shell] .... % mplayer -vo sdl testfile.avi .... [source,shell] .... % mplayer -vo x11 testfile.avi .... [source,shell] .... # mplayer -vo dga testfile.avi .... [source,shell] .... # mplayer -vo 'sdl:dga' testfile.avi .... Es lohnt sich, alle Option zu testen. Die erzielte Geschwindigkeit hängt von vielen Faktoren ab und variiert beträchtlich je nach eingesetzter Hardware. Wenn Sie eine DVD abspielen wollen, ersetzen Sie [.filename]#testfile.avi# durch `-dvd://__N Gerät__`. `_N_` ist die Nummer des Stücks, das Sie abspielen wollen und [.filename]#Gerät# gibt den Gerätenamen der DVD an. Das nachstehende Kommando spielt das dritte Stück von [.filename]#/dev/dvd#: [source,shell] .... # mplayer -vo dga -dvd://3 /dev/dvd .... [NOTE] ==== Das standardmäßig verwendete DVD-Laufwerk kann beim Bau des MPlayer-Ports mit der Option `WITH_DVD_DEVICE=/pfad/zum/gerät` festgelegt werden. Die Voreinstellung verwendet das Gerät [.filename]#/dev/cd0#. Weitere Details finden Sie in [.filename]#Makefile.options# des Ports. ==== Die Tastenkombinationen zum Abbrechen, Anhalten und Weiterführen der Wiedergabe entnehmen Sie der Ausgabe von `mplayer -h` oder der mplayer(1) Manualpage. Weitere nützliche Optionen für die Wiedergabe sind `-fs -zoom` zur Wiedergabe im Vollbild-Modus und `-framedrop` zur Steigerung der Geschwindigkeit. Jeder Benutzer kann häufig verwendete Optionen in seine [.filename]#~/.mplayer/config# eintragen: [.programlisting] .... vo=xv fs=yes zoom=yes .... `mplayer` kann verwendet werden, um DVD-Stücke in [.filename]#.vob#-Dateien zu rippen. Das zweite Stück einer DVD wandeln Sie wie folgt in eine Datei um: [source,shell] .... # mplayer -dumpstream -dumpfile out.vob -dvd://2 /dev/dvd .... Die Ausgabedatei [.filename]#out.vob# wird im MPEG-Format abgespeichert. Jeder Benutzer, der mehr Informationen über Video unter UNIX(R) sammeln möchte, sollte http://www.mplayerhq.hu/DOCS/[ mplayerhq.hu/DOCS] konsultieren, da es technisch sehr informativ ist. Diese Dokumentation sollte ebenfalls studiert werden, bevor Fehlerberichte eingereicht werden. Vor der Verwendung von `mencoder` ist es hilfreich, sich mit den auf http://www.mplayerhq.hu/DOCS/HTML/en/mencoder.html[mplayerhq.hu/DOCS/HTML/en/mencoder.html] beschriebenen Optionen vertraut zu machen. Es gibt unzählige Möglichkeiten die Qualität zu verbessern, die Bitrate zu verringern und Formate zu konvertieren. Einige davon haben erhebliche Auswirkungen auf die Geschwindigkeit. Falsche Kombinationen von Kommandozeilenparametern ergeben eventuell Dateien, die selbst `mplayer` nicht mehr wiedergeben kann. Hier ist ein Beispiel für eine einfache Kopie: [source,shell] .... % mencoder input.avi -oac copy -ovc copy -o output.avi .... Wenn Sie in eine Datei rippen, benutzen Sie die Option `-dumpfile` von `mplayer`. Um [.filename]#input.avi# nach MPEG4 mit MPEG3 für den Ton zu konvertieren, muss zunächst der Port package:audio/lame[] installiert werden. Aus lizenzrechtlichen Gründen ist ein Paket nicht verfügbar. Wenn der Port installiert ist, geben Sie ein: [source,shell] .... % mencoder input.avi -oac mp3lame -lameopts br=192 \ -ovc lavc -lavcopts vcodec=mpeg4:vhq -o output.avi .... Die Ausgabedatei lässt sich mit Anwendungen wie `mplayer` oder `xine` abspielen. [.filename]#input.avi# kann durch `-dvd://1 /dev/dvd` ersetzt und das Kommando als `root` ausgeführt werden, um ein DVD-Stück direkt zu konvertieren. Da vielleicht ein paar Versuche nötig sind, um das gewünschte Ergebnis zu erhalten, empfiehlt es sich das Stück zuerst in eine Datei zu schreiben und anschließend die Datei weiter zu bearbeiten. [[video-xine]] ==== Der Video-Spieler xine xine ist ein Video-Spieler mit einer wiederverwendbaren Bibliothek und ein Programm, das durch Plugins erweitert werden kann. Es kann als Paket oder Port package:multimedia/xine[] installiert werden. Für einen reibungslosen Betrieb benötigt xine entweder eine schnelle CPU mit einer schnellen Grafikkarte, oder die XVideo-Erweiterung. Am schnellsten läuft xine mit der XVideo-Erweiterung. In der Voreinstellung startet xine eine grafische Benutzeroberfläche. Über die Menüs können dann bestimmte Dateien geöffnet werden. Alternativ kann xine auch über die Kommandozeile aufgerufen werden, um Dateien direkt wiederzugeben: [source,shell] .... % xine -g -p mymovie.avi .... Weitere Informationen und Tipps zur Fehlerbehebung finden Sie unter http://www.xine-project.org/faq[xine-project.org/faq]. [[video-ports-transcode]] ==== Die Transcode-Werkzeuge Transcode ist eine Sammlung von Werkzeugen zur Umwandlung von Video- und Audio-Dateien. Transcode mischt Video-Dateien und kann kaputte Video-Dateien reparieren. Die Werkzeuge werden als Filter verwendet, das heißt die Ein- und Ausgaben verwenden stdin/stdout. Unter FreeBSD kann Transcode als Paket oder Port package:multimedia/transcode[] installiert werden. Viele Benutzer bevorzugen es den Port zu bauen, da er ein Menü bereitstellt, wo die entsprechenden Formate für den Bau ausgewählt werden können. Mit den Pfeiltasten und der Leertaste können die erforderlichen Formate ausgewählt werden. Wenn Sie fertig sind, drücken Sie kbd:[Enter], um den Bau und die Installation fortzusetzen. Dieses Beispiel zeigt, wie eine DivX-Datei in eine PAL MPEG-1-Datei konvertiert wird: [source,shell] .... % transcode -i input.avi -V --export_prof vcd-pal -o output_vcd % mplex -f 1 -o output_vcd.mpg output_vcd.m1v output_vcd.mpa .... Die daraus resultierende MPEG-Datei, [.filename]#output_vcd.mpg#, kann beispielsweise mit MPlayer abgespielt werden. Die Datei kann auch mit einem Programm wie package:multimedia/vcdimager[] oder package:sysutils/cdrdao[] als Video-CD auf eine CD-R gebrannt werden. Zusätzlich zu der Manualpage von `transcode`, sollten Sie auch die Informationen und Beispiele im http://www.transcoding.org/cgi-bin/transcode[ transcoding.org/cgi-bin/transcode] lesen. [[tvcard]] == TV-Karten Mit TV-Karten können Sie mit dem Rechner über Kabel oder Antenne fernsehen. Die meisten Karten besitzen einen RCA- oder S-Video-Eingang. Einige Karten haben auch einen FM-Radio-Empfänger. Der man:bktr[4]-Treiber von FreeBSD unterstützt PCI-TV-Karten mit einem Brooktree Bt848/849/878/879 Chip. Dieser Teiber unterstützt die meisten Pinnacle PCTV Karten. Die Karte sollte einen der unterstützten Empfänger besitzen, die in man:bktr[4] aufgeführt sind. === Den Treiber laden Um die Karte benutzen zu können, muss der man:bktr[4]-Treiber geladen werden. Damit dies beim Systemstart automatisch erfolgt, muss die folgende Zeile in [.filename]#/boot/loader.conf# hinzugefügt werden: [.programlisting] .... bktr_load="YES" .... Alternativ kann der Treiber für die TV-Karte auch fest in den Kernel kompiliert werden. In diesem Fall müssen folgende Zeilen in die Kernelkonfigurationsdatei aufgenommen werden: [.programlisting] .... device bktr device iicbus device iicbb device smbus .... Die zusätzlichen Treiber werden benötigt, da die Komponenten der Karte über einen I2C-Bus verbunden sind. Bauen und installieren Sie dann den neuen Kernel. Um den Treiber zu testen, muss das System neu gestartet werden. Während des Neustarts sollte die TV-Karte erkannt werden: [.programlisting] .... bktr0: mem 0xd7000000-0xd7000fff irq 10 at device 10.0 on pci0 iicbb0: on bti2c0 iicbus0: on iicbb0 master-only iicbus1: on iicbb0 master-only smbus0: on bti2c0 bktr0: Pinnacle/Miro TV, Philips SECAM tuner. .... Abhängig von der verwendeten Hardware können die Meldungen natürlich anders aussehen. Die entdeckten Geräte lassen sich mit man:sysctl[8] oder in der Kernelkonfigurationsdatei überschreiben. Wenn Sie beispielsweise einen Philips-SECAM-Empfänger erzwingen wollen, fügen Sie die folgende Zeile zur Kernelkonfigurationsdatei hinzu: [.programlisting] .... options OVERRIDE_TUNER=6 .... Alternativ können Sie man:sysctl[8] benutzen: [source,shell] .... # sysctl hw.bt848.tuner=6 .... Weitere Informationen zu den verschiedenen Kerneloptionen und man:sysctl[8]-Parametern finden Sie in man:bktr[4]. === Nützliche Anwendungen Um die TV-Karte zu benutzen, installieren Sie eine der nachstehenden Anwendungen: * package:multimedia/fxtv[] lässt das Fernsehprogramm in einem Fenster laufen und kann Bilder, Audio und Video aufzeichnen. * package:multimedia/xawtv[] eine weitere TV-Anwendung mit vergleichbaren Funktionen. * Mit package:audio/xmradio[] lässt sich der FM-Radio-Empfänger, der sich auf TV-Karten befindet, benutzen. Weitere Anwendungen finden Sie in der FreeBSD Ports-Sammlung. === Fehlersuche Wenn Sie Probleme mit der TV-Karte haben, prüfen Sie zuerst, ob der Video-Capture-Chip und der Empfänger vom man:bktr[4]-Treiber unterstützt werden und ob Sie die richtigen Optionen verwenden. Weitere Hilfe zu unterstützten TV-Karten finden Sie auf der Mailingliste {freebsd-multimedia}. [[mythtv]] == MythTV MythTV ist eine beliebte Open Source PVR-Anwendung. Dieser Abschnitt beschreibt die Installation und Konfiguration von MythTV unter FreeBSD. Weitere Informationen zur Benutzung von MythTV finden Sie unter http://www.mythtv.org/wiki/[mythtv.org/wiki]. MythTV benötigt ein Frontend und ein Backend. Diese Komponenten können entweder auf dem gleichen System, oder auf unterschiedlichen Maschinen installiert werden. Das Frontend kann unter FreeBSD über den Port oder das Paket package:multimedia/mythtv-frontend[] installiert werden. Zudem muss Xorg, wie in crossref:x11[x11,Das X-Window-System] beschrieben, installiert und konfiguriert sein. Idealerweise besitzt das System auch eine Videokarte, die X-Video Motion Compensation (XvMC) unterstützt, sowie optional eine LIRC-kompatible Fernbedienung. Benutzen Sie package:multimedia/mythtv[], um sowohl das Frontend als auch das Backend zu installieren. Ein MySQL(TM) Datenbank-Server ist ebenfalls erforderlich und sollte automatisch als Abhängigkeit installiert werden. Optional sollte das System einen Empfänger und ausreichend Speicherplatz haben, um die aufgezeichneten Daten speichern zu können. === Hardware MythTV verwendet V4L um auf Videoeingabegeräte, wie Kodierer und Empfänger zuzugreifen. Unter FreeBSD funktioniert MythTV am besten mit USB DVB-S/C/T Karten, die von package:multimedia/webcamd[] unterstützt werden, da dies eine V4L-Anwendung zur Verfügung stellt, die als Benutzerprogramm läuft. Jede DVB-Karte, die von webcamd unterstützt wird, sollte mit MythTV funktionieren, jedoch gibt es eine Liste von Karten, die unter https://wiki.freebsd.org/WebcamCompat[ wiki.freebsd.org/WebcamCompat] abgerufen werden kann. Es existieren auch Treiber für Hauppauge-Karten in den folgenden Paketen: package:multimedia/pvr250[] und package:multimedia/pvrxxx[], allerdings liefern diese nur eine Treiberschnittstelle, die nicht dem Standard entspricht und die nicht mit MythTV-Versionen grösser als 0.23 funktionieren. Aus lizenzrechtlichen Gründen ist ein Paket nicht verfügbar, sodass die beiden Ports übersetzt werden müssen. Die https://wiki.freebsd.org/HTPC[ wiki.freebsd.org/HTPC] enthält eine Liste von allen verfügbaren DVB-Treibern. === MythTV Backend einrichten Geben Sie folgendes ein, um MythTV als Binärpaket zu installieren: [source,shell] .... # pkg install mythtv .... Alternativ können Sie den Port installieren: [source,shell] .... # cd /usr/ports/multimedia/mythtv # make install .... Richten Sie anschließend die MythTV-Datenbank ein: [source,shell] .... # mysql -uroot -p < /usr/local/shared/mythtv/database/mc.sql .... Konfigurieren Sie dann das Backend: [source,shell] .... # mythtv-setup .... Zum Schluss starten Sie das Backend: [source,shell] .... # sysrc mythbackend_enable=yes # service mythbackend start .... [[scanners]] == Scanner Unter FreeBSD stellt SANE (Scanner Access Now Easy) aus der Ports-Sammlung eine einheitliche Schnittstelle (API) für den Zugriff auf Scanner bereit. SANE wiederum greift auf Scanner mithilfe einiger FreeBSD-Treiber zu. FreeBSD unterstützt sowohl SCSI- als auch USB-Scanner. Abhängig von der Schnittstelle des Scanners, werden unterschiedliche Treiber benötigt. Prüfen Sie vor der Konfiguration mithilfe der http://www.sane-project.org/sane-supported-devices.html[Liste der unterstützten Geräte] ob der Scanner von SANE unterstützt wird. Dieses Kapitel beschreibt, wie Sie feststellen können, ob der Scanner von FreeBSD erkannt wurde. Zudem enthält es einen Überblick über die Konfiguration und Verwendung von SANE unter FreeBSD. [[scanners-kernel-usb]] === Den Scanner überprüfen Im [.filename]#GENERIC#-Kernel sind schon alle, für einen USB-Scanner notwendigen Treiber enthalten. Benutzer mit einem angepassten Kernel sollten sicherstellen, dass die Kernelkonfiguration die nachstehenden Zeilen enthält: [.programlisting] .... device usb device uhci device ohci device ehci device xhci .... Um zu überprüfen ob der Scanner erkannt wird, schließen Sie den USB-Scanner an. Prüfen Sie dann mit man:dmesg[8], ob der Scanner in den Systemmeldungen erscheint: [source,shell] .... ugen0.2: at usbus0 .... In diesem Beispiel wurde ein EPSON Perfection(R) 1650 USB-Scanner an [.filename]#/dev/ugen0.2# erkannt. Wenn der Scanner eine SCSI-Schnittstelle besitzt, ist die Kernelkonfiguration abhängig vom verwendeten SCSI-Controller. Der [.filename]#GENERIC#-Kernel unterstützt die gebräuchlichen SCSI-Controller. Den richtigen Treiber finden Sie in [.filename]#/usr/src/sys/conf/NOTES#. Neben dem SCSI-Treiber muss die Kernelkonfiguration noch die nachstehenden Zeilen enthalten: [.programlisting] .... device scbus device pass .... Nachdem Sie einen Kernel gebaut und installiert haben, sollte der Scanner beim Neustart in den Systemmeldungen erscheinen: [source,shell] .... pass2 at aic0 bus 0 target 2 lun 0 pass2: Fixed Scanner SCSI-2 device pass2: 3.300MB/s transfers .... Wenn der Scanner während des Systemstarts ausgeschaltet war, können Sie die Geräteerkennung erzwingen, indem Sie den SCSI-Bus erneut absuchen. Verwenden Sie dazu `camcontrol`: [source,shell] .... # camcontrol rescan all Re-scan of bus 0 was successful Re-scan of bus 1 was successful Re-scan of bus 2 was successful Re-scan of bus 3 was successful .... Der Scanner sollte jetzt in der SCSI-Geräteliste erscheinen: [source,shell] .... # camcontrol devlist at scbus0 target 5 lun 0 (pass0,da0) at scbus0 target 6 lun 0 (pass1,da1) at scbus1 target 2 lun 0 (pass3) at scbus2 target 0 lun 0 (pass2,cd0) .... Weitere Informationen über SCSI-Geräte unter FreeBSD finden Sie in man:scsi[4] und man:camcontrol[8]. === SANE konfigurieren Das SANE-System ermöglicht den Zugriff auf den Scanner über Backends (package:graphics/sane-backends[]). Lesen Sie http://www.sane-project.org/sane-supported-devices.html[http://www.sane-project.org/sane-supported-devices.html] um herauszufinden, welches Backend welchen Scanner unterstützt. Eine graphische Oberfläche wird über Anwendungen von Drittanbietern wie Kooka (package:graphics/kooka[]) oder XSane (package:graphics/xsane[]) bereitgestellt. Die Backends von SANE reichen aus, um den Scanner zu testen. Installieren Sie die Backends als Paket: [source,shell] .... # pkg install sane-backends .... Alternativ können Sie die Backends aus der Ports-Sammlung installieren: [source,shell] .... # cd /usr/ports/graphics/sane-backends # make install clean .... Nachdem Sie den Port oder das Paket package:graphics/sane-backends[] installiert haben, können Sie mit dem Befehl `sane-find-scanner` prüfen, ob SANE den Scanner erkennt: [source,shell] .... # sane-find-scanner -q found SCSI scanner "AGFA SNAPSCAN 600 1.10" at /dev/pass3 .... Die Ausgabe zeigt die Schnittstelle und die verwendete Gerätedatei des Scanners. Der Hersteller und das Modell können in der Ausgabe fehlen. [NOTE] ==== Bei einigen USB-Scannern muss die Firmware geladen werden. Lesen Sie sane-find-scanner(1) und sane(7) für weitere Details. ==== Als nächstes müssen Sie prüfen, ob der Scanner vom Frontend erkannt wird. Die SANE-Backends werden mit dem Kommandozeilenwerkzeug `scanimage` geliefert. Mit diesem Werkzeug können Sie sich Scanner anzeigen lassen und den Scan-Prozess von der Kommandozeile starten. Die Option `-L` zeigt die Scanner an. Das erste Beispiel ist für einen SCSI-Scanner, das zweite ist für einen USB-Scanner: [source,shell] .... # scanimage -L device `snapscan:/dev/pass3' is a AGFA SNAPSCAN 600 flatbed scanner # scanimage -L device 'epson2:libusb:000:002' is a Epson GT-8200 flatbed scanner .... Im zweiten Beispiel ist `epson2` der Backend-Name. `libusb:000:002` bedeutet, dass [.filename]#/dev/ugen0.2# die vom Scanner verwendete Gerätedatei ist. Wenn `scanimage` den Scanner nicht erkennen kann, erscheint folgende Meldung: [source,shell] .... # scanimage -L No scanners were identified. If you were expecting something different, check that the scanner is plugged in, turned on and detected by the sane-find-scanner tool (if appropriate). Please read the documentation which came with this software (README, FAQ, manpages). .... Wenn das passiert, müssen Sie in der Konfigurationsdatei des Backends unterhalb von [.filename]#/usr/local/etc/sane.d/# den verwendeten Scanner eintragen. Wenn der Scanner EPSON Perfection(R) 1650, der das Backend `epson2` benutzt, nicht erkannt wurde, muss [.filename]#/usr/local/etc/sane.d/epson2.conf# angepasst werden. Fügen Sie eine Zeile mit der Schnittstelle und dem Gerätenamen in die Datei ein. In diesem Beispiel wurde die nachstehende Zeile eingefügt: [.programlisting] .... usb /dev/ugen0.2 .... Speichern Sie die Änderungen und prüfen Sie, ob der Scanner mit dem richtigen Backend und Gerätenamen erkannt wird: [source,shell] .... # scanimage -L device 'epson2:libusb:000:002' is a Epson GT-8200 flatbed scanner .... Wenn `scanimage -L` den Scanner erkannt hat, ist der Scanner eingerichtet und bereit, zu scannen. Obwohl `scanimage` von der Kommandozeile scannen kann, ist eine graphische Anwendung zum Scannen besser geeignet. Bekannte Programme sind Koka oder XSane. Diese Frontends besitzten erweiterte Funktionen wie den Scan-Modus, Farbkorrektur und Batch-Scans. XSane lässt sich auch als GIMP-Plugin verwenden. === Berechtigungen für den Scanner Wenn andere Benutzer den Scanner benutzen sollen, müssen sie Lese- und Schreibrechte auf die Gerätedatei des Scanners besitzen. Im vorherigen Beispiel wird die Datei [.filename]#/dev/ugen0.2# verwendet, die faktisch nur ein Symlink auf die echte Gerätedatei, [.filename]#/dev/usb/0.2.0# genannt, darstellt. Sowohl der Symlink als auch die Gerätedatei sind jeweils im Besitz der Gruppen `wheel` und `operator`. Damit ein Benutzer den Scanner benutzen kann, muss er Mitglied in einer der beiden Gruppen sein. Allerdings sollte aus Sicherheitsgründen genau überlegt werden, welche Benutzer zu welcher Gruppe hinzugefügt werden, besonders bei der Gruppe `wheel`. Eine bessere Lösung ist es, eine spezielle Gruppe für den Zugriff anzulegen und den Scanner für Mitglieder dieser Gruppe zugänglich zu machen. Dieses Beispiel erstellt eine Gruppe namens `_usb_`: [source,shell] .... # pw groupadd usb .... Anschließend muss der [.filename]#/dev/ugen0.2#-Symlink und der Gerätename [.filename]#/dev/usb/0.2.0# für die Gruppe `usb` mit den Schreibrechten `0660` oder `0664` ausgestattet werden. All dies kann durch das Hinzufügen der folgenden Zeilen in [.filename]#/etc/devfs.rules# erreicht werden: [.programlisting] .... [system=5] add path ugen0.2 mode 0660 group usb add path usb/0.2.0 mode 0666 group usb .... [NOTE] ==== Es kommt vor, dass sich der Gerätename mit dem Hinzufügen oder Entfernen von Geräten ändert, so dass man stattdessen vielleicht allen USB-Geräten mit diesem Regelsatz Zugriff gewähren möchte: [.programlisting] .... [system=5] add path 'ugen*' mode 0660 group usb add path 'usb/*' mode 0666 group usb .... ==== Weitere Informationen zu dieser Datei finden Sie in man:devfs.rules[5]. Als nächstes aktivieren Sie den Regelsatz in [.filename]#/etc/rc.conf#: [.programlisting] .... devfs_system_ruleset="system" .... Starten Sie anschließend das man:devfs[8]-System neu: [source,shell] .... # service devfs restart .... Jetzt müssen nur noch Benutzer zur Gruppe `_usb_` hinzugefügt werden, um ihnen den Zugriff auf den Scanner zu erlauben: [source,shell] .... # pw groupmod usb -m joe .... Weitere Details finden Sie in man:pw[8]. diff --git a/documentation/content/el/books/handbook/bsdinstall/_index.adoc b/documentation/content/el/books/handbook/bsdinstall/_index.adoc index 1944c06bf1..4bb9966b97 100644 --- a/documentation/content/el/books/handbook/bsdinstall/_index.adoc +++ b/documentation/content/el/books/handbook/bsdinstall/_index.adoc @@ -1,1210 +1,1212 @@ --- title: Κεφάλαιο 2. Εγκατάσταση του FreeBSD 9.x και Μεταγενέστερων Εκδόσεων part: Μέρος I. Ξεκινώντας με το FreeBSD prev: books/handbook/introduction next: books/handbook/install showBookMenu: true weight: 4 path: "/books/handbook/bsdinstall/" --- [[bsdinstall]] = Εγκατάσταση του FreeBSD 9.x και Μεταγενέστερων Εκδόσεων :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 2 :partnums: :source-highlighter: rouge :experimental: :images-path: books/handbook/bsdinstall/ 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::[] [[bsdinstall-synopsis]] == Σύνοψη Το FreeBSD έρχεται με ένα μη-γραφικό αλλά εύκολο στη χρήση πρόγραμμα εγκατάστασης. Από το FreeBSD 9.0-RELEASE και μετά, χρησιμοποιείται το πρόγραμμα bsdinstall ενώ οι προηγούμενες εκδόσεις χρησιμοποιούν το sysinstall. Το κεφάλαιο αυτό περιγράφει τη χρήση του bsdinstall. Η χρήση του sysinstall περιγράφεται στο crossref:install[install,“Εγκατάσταση του FreeBSD 8.x και Προγενέστερων Εκδόσεων”]. Αφού διαβάσετε αυτό το κεφάλαιο, θα γνωρίζετε: * Πως να δημιουργήσετε μέσα εγκατάστασης για το FreeBSD. * Πως το FreeBSD υποδιαιρεί τους σκληρούς δίσκους και πως αναφέρεται σε αυτούς. * Πως να εκκινήσετε το bsdinstall. * Τις ερωτήσεις που θα σας κάνει το bsdinstall, τι σημαίνουν και πως να τις απαντήσετε. Πριν διαβάσετε αυτό το κεφάλαιο θα πρέπει: * Να διαβάσετε τη λίστα του υλικού που υποστηρίζεται από την έκδοση του FreeBSD που εγκαθιστάτε και να επαληθεύσετε ότι το υλικό του υπολογιστή σας υποστηρίζεται. [NOTE] ==== Σε γενικές γραμμές, αυτές οι οδηγίες εγκατάστασης αναφέρονται στην αρχιτεκτονική i386(TM) ("PC συμβατή"). Όπου χρειάζεται, γίνεται αναφορά και σε άλλες αρχιτεκτονικές. Πιθανόν να υπάρχουν μικρές διαφορές στο πρόγραμμα εγκατάστασης σε σχέση με το παρόν κείμενο και για το λόγο αυτό σας συνιστούμε να το χρησιμοποιήσετε ως γενικό οδηγό παρά σαν κυριολεκτικά ακριβείς οδηγίες. ==== [[bsdinstall-hardware]] == Απαιτήσεις Υλικού [[bsdinstall-hardware-minimal]] === Ελάχιστες Απαιτήσεις Εγκατάστασης Οι ελάχιστες απαιτήσεις για την εγκατάσταση του FreeBSD ποικίλουν ανάλογα με την έκδοση του λειτουργικού και την αρχιτεκτονική του υλικού που χρησιμοποιείται. Στις επόμενες ενότητες θα σας παρουσιάσουμε μια σύνοψη αυτών των πληροφοριών. Ανάλογα με τη μέθοδο που θα χρησιμοποιήσετε για να εγκαταστήσετε το FreeBSD, μπορεί να χρειαστείτε ένα υποστηριζόμενο οδηγό CDROM και - σε κάποιες περιπτώσεις - μια κάρτα δικτύου. Τα θέματα αυτά καλύπτονται στο <>. ==== FreeBSD/i386 Το FreeBSD/i386 απαιτεί 486 ή καλύτερο επεξεργαστή και τουλάχιστον 64 MB RAM. Για την ελάχιστη δυνατή εγκατάσταση απαιτείται 1.1 GB ελεύθερου χώρου στο σκληρό δίσκο. [NOTE] ==== Σε περιπτώσεις παλιών μηχανημάτων, τις περισσότερες φορές, η απόδοση του συστήματος βελτιώνεται περισσότερο με αύξηση της μνήμης RAM και του ελεύθερου χώρου στο δίσκο, παρά με ένα ταχύτερο επεξεργαστή. ==== ==== FreeBSD/amd64 Υπάρχουν δύο κλάσεις επεξεργαστών ικανές να εκτελέσουν το FreeBSD/amd64. Η πρώτη είναι οι επεξεργαστές AMD64 που περιλαμβάνουν τους AMD Athlon(TM)64, AMD Athlon(TM)64-FX, AMD Opteron(TM) ή καλύτερους. Η δεύτερη κλάση επεξεργαστών που μπορούν να εκτελέσουν το FreeBSD/amd64 περιλαμβάνει όσους χρησιμοποιούν την αρχιτεκτονική Intel(R) EM64T. Παραδείγματα των επεξεργαστών αυτών περιλαμβάνουν τις οικογένειες Intel(R) Core(TM) 2 Duo, Quad, Extreme processor, τη σειρά επεξεργαστών Intel(R) Xeon(TM) 3000, 5000 και 7000 καθώς και τους επεξεργαστές Intel(R) Core(TM) i3, i5 και i7. Αν το μηχάνημα σας είναι βασισμένο σε nVidia nForce3 Pro-150, θα _πρέπει_ να χρησιμοποιήσετε την κατάλληλη επιλογή στο BIOS για να απενεργοποιήσετε το IO APIC. Αν η επιλογή αυτή δεν υπάρχει, θα πρέπει να απενεργοποιήσετε αντί αυτού το ACPI. Υπάρχουν προβλήματα στο Pro-150 για τα οποία μέχρι στιγμής δεν έχει βρεθεί λύση που να τα παρακάμπτει. ==== FreeBSD/powerpc Apple(R) Macintosh(R) Υποστηρίζονται όλοι οι νέοι υπολογιστές Apple(R) Macintosh(R) που διαθέτουν ενσωματωμένες USB. Υποστηρίζεται επίσης η λειτουργία SMP σε μηχανήματα με πολλαπλούς επεξεργαστές. Ένας 32-bit πυρήνας μπορεί να χρησιμοποιήσει μόνο τα πρώτα 2 GB RAM. Το FireWire(R) δεν υποστηρίζεται στα Μπλε και Λευκά PowerMac G3. ==== FreeBSD/sparc64 Μπορείτε να δείτε τα συστήματα που υποστηρίζονται από το FreeBSD/sparc64 στο http://www.freebsd.org/platforms/sparc/[FreeBSD/sparc64] Project. Θα χρειαστείτε ένα δίσκο για αποκλειστική χρήση από το FreeBSD/sparc64. Τη δεδομένη στιγμή, δεν είναι δυνατόν το FreeBSD/sparc64 να μοιράζεται τον ίδιο δίσκο με ένα άλλο λειτουργικό σύστημα. [[bsdinstall-hardware-supported]] === Υποστηριζόμενο Υλικό Στις Σημειώσεις Υλικού (Hardware Notes) μπορείτε να βρείτε πληροφορίες για τις αρχιτεκτονικές και τις συσκευές που υποστηρίζονται από μια επίσημη έκδοση του FreeBSD. Το αρχείο αυτό ονομάζεται συνήθως [.filename]#HARDWARE.TXT#, και βρίσκεται στον κεντρικό κατάλογο του μέσου εγκατάστασης. Μπορείτε επίσης να βρείτε αντίγραφα αυτού του καταλόγου στη σελίδα http://www.FreeBSD.org/releases/[Πληροφοριών Έκδοσης] στο δικτυακό τόπο του FreeBSD. [[bsdinstall-pre]] == Εργασίες πριν την Εγκατάσταση === Κρατήστε Αντίγραφα Ασφαλείας των Δεδομένων σας Κρατήστε αντίγραφα ασφαλείας όλων των σημαντικών δεδομένων του υπολογιστή στον οποίο θα κάνετε εγκατάσταση του FreeBSD. Ελέγξτε τη σωστή λειτουργία των αντιγράφων ασφαλείας πριν συνεχίσετε. Το πρόγραμμα εγκατάστασης του FreeBSD θα ζητήσει επιβεβαίωση πριν κάνει οποιαδήποτε αλλαγή στο δίσκο σας, αλλά από τη στιγμή που αυτή η διαδικασία ξεκινήσει, δεν υπάρχει δυνατότητα επιστροφής. [[bsdinstall-where]] === Αποφασίστε που θα Εγκαταστήσετε το FreeBSD Αν το FreeBSD πρόκειται να είναι το μοναδικό λειτουργικό σύστημα του υπολογιστή και σκοπεύετε να διαθέσετε σε αυτό ολόκληρο το χώρο του σκληρού σας δίσκου, μπορείτε να παραλείψετε το υπόλοιπο αυτής της ενότητας. Αν ωστόσο θέλετε να συνυπάρχει το FreeBSD με άλλα λειτουργικά συστήματα, είναι χρήσιμο να κατανοείτε γενικά τον τρόπο διάταξης των δεδομένων στο δίσκο. [[bsdinstall-where-i386]] ==== Κατατμήσεις Δίσκων για τις Αρχιτεκτονικές FreeBSD/i386 και FreeBSD/amd64 Οι σκληροί δίσκοι μπορούν να χωριστούν σε διακριτά τμήματα. Τα τμήματα αυτά ονομάζονται _κατατμήσεις (partitions)_. Υπάρχουν δύο τρόποι για να χωριστεί ένας δίσκος σε κατατμήσεις. Ο παραδοσιακός τρόπος χρησιμοποιεί το _Master Boot Record (Βασική Εγγραφή Εκκίνησης)_ ή MBR, ένα πίνακα κατατμήσεων ικανό να αποθηκεύσει ως τέσσερις _πρωτεύουσες κατατμήσεις (primary partitions)_. (Για ιστορικούς λόγους, το FreeBSD ονομάζει τις πρωτεύουσες κατατμήσεις _slices ή φέτες_.) Το όριο των τεσσάρων κατατμήσεων είναι πολύ περιοριστικό για μεγάλους δίσκους, έτσι μια από αυτές τις κατατμήσεις μπορεί να μετατραπεί σε _εκτεταμένη κατάτμηση (extended partition)_. Μέσα στην εκτεταμένη κατάτμηση μπορούν να δημιουργηθούν πολλαπλές _λογικές κατατμήσεις (logical partitions)_. Αυτό ακούγεται κάπως παράξενο, και μάλλον είναι. Ο _Πίνακας Κατατμήσεων GUID (GUID Partition Table)_ ή GPT, αποτελεί μια νέα και απλούστερη μέθοδος κατάτμησης ενός δίσκου. Το GPT είναι πολύ πιο βολικό από τον παραδοσιακό πίνακα κατατμήσεων MBR. Οι συνήθεις υλοποιήσεις του GPT επιτρέπουν ως και 128 κατατμήσεις ανά δίσκο, εξαλείφοντας έτσι την ανάγκη για άβολες λύσεις όπως οι λογικές κατατμήσεις. [WARNING] ==== Κάποια παλιότερα λειτουργικά συστήματα όπως τα Windows(R) XP δεν είναι συμβατά με το σύστημα κατατμήσεων GPT. Αν το FreeBSD πρόκειται να εγκατασταθεί σε ένα δίσκο από κοινού με ένα τέτοιο λειτουργικό, θα πρέπει να χρησιμοποιήσετε το σύστημα MBR. ==== Ο τυπικός φορτωτής εκκίνησης (boot loader) του FreeBSD χρειάζεται είτε μια πρωτεύουσα είτε μια GPT κατάτμηση. (Δείτε το crossref:boot[boot,Η Διαδικασία Εκκίνησης του FreeBSD] για περισσότερες πληροφορίες σχετικά με τη διαδικασία εκκίνησης του FreeBSD.) Αν όλες οι πρωτεύουσες ή GPT κατατμήσεις είναι ήδη σε χρήση, θα πρέπει να ελευθερώσετε μία για χρήση με το FreeBSD. Η ελάχιστη εγκατάσταση του FreeBSD καταλαμβάνει μόνο περίπου 1 GB χώρο στο δίσκο. Πρόκειται όμως για την _απόλυτα_ ελάχιστη εγκατάσταση η οποία δεν αφήνει σχεδόν καθόλου ελεύθερο χώρο. Μια πιο ρεαλιστική ελάχιστη εγκατάσταση καταλαμβάνει περίπου 3 GB χωρίς γραφικό περιβάλλον και περίπου 5 GB με χρήση κάποιου γραφικού περιβάλλοντος. Η εγκατάσταση λογισμικού τρίτων κατασκευαστών απαιτεί ακόμα περισσότερο χώρο στο δίσκο. Υπάρχει πληθώρα http://en.wikipedia.org/wiki/List_of_disk_partitioning_software[ελεύθερων και εμπορικών εργαλείων αναδιανομής χώρου κατατμήσεων]. Το http://gparted.sourceforge.net/livecd.php[GParted Live] είναι ένα δωρεάν Live CD το οποίο περιλαμβάνει τον επεξεργαστή κατατμήσεων GParted. Το GParted περιλαμβάνεται επίσης σε πολλές άλλες Live διανομές Linux. [WARNING] ==== Οι εφαρμογές που διαχειρίζονται κατατμήσεις σκληρών δίσκων μπορούν να καταστρέψουν τα δεδομένα σας. Πάρτε πλήρη αντίγραφα ασφαλείας και επιβεβαιώστε την ορθή λειτουργία τους πριν ξεκινήσετε την τροποποίηση των κατατμήσεων του δίσκου σας. ==== Η αλλαγή μεγέθους κατατμήσεων των Microsoft(R) Vista ενδέχεται να είναι δύσκολη. Είναι χρήσιμο να έχετε διαθέσιμο ένα DVD εγκατάστασης των Vista πριν ξεκινήσετε μια τέτοια διαδικασία. .Χρησιμοποιώντας μια Υπάρχουσα Κατάτμηση [example] ==== Ένας υπολογιστής Windows(R) διαθέτει ένα μοναδικό δίσκο 40 GB ο οποίος έχει χωριστεί σε δύο κατατμήσεις των 20 GB. Στα Windows(R) ονομάζονται [.filename]#C:# και [.filename]#D:#. Η κατάτμηση [.filename]#C:# περιέχει 10 GB δεδομένων, ενώ η κατάτμηση [.filename]#D:# 5 GB. Η μετακίνηση των δεδομένων από τον [.filename]#D:# στο [.filename]#C:# ελευθερώνει τη δεύτερη κατάτμηση ώστε να μπορεί να χρησιμοποιηθεί από το FreeBSD. ==== .Συρρικνώνοντας μια Υπάρχουσα Κατάτμηση [example] ==== Ένας υπολογιστής Windows(R) έχει ένα μοναδικό σκληρό δίσκο 40 GB και μια μεγάλη κατάτμηση που τον καταλαμβάνει εξ' ολοκλήρου. Τα Windows(R) δείχνουν αυτή την κατάτμηση των 40 GB ως ένα μοναδικό οδηγό [.filename]#C:#. Τη δεδομένη στιγμή χρησιμοποιούνται 15 GB χώρου. Σκοπός είναι να καταλήξουμε με μια κατάτμηση των 20 GB για τα Windows(R) και άλλα 20 GB για το FreeBSD. Υπάρχουν δύο τρόποι για να γίνει αυτό: . Κρατήστε αντίγραφο των δεδομένων που έχετε δημιουργήσει στα Windows(R). Έπειτα επανεγκαταστήστε τα Windows(R) δημιουργώντας μια κατάτμηση μεγέθους 20 GB κατά την διαδικασία εγκατάστασης. . Χρησιμοποιήστε κάποιο εργαλείο αλλαγής μεγέθους κατατμήσεων όπως το GParted για να συρρικνώσετε την κατάτμηση των Windows(R) και να δημιουργήσετε μια νέα κατάτμηση για το FreeBSD στον ελεύθερο χώρο. ==== Η εγκατάσταση διαφορετικών λειτουργικών συστημάτων σε άλλες κατατμήσεις, επιτρέπει την εκτέλεση ενός από αυτά σε μια δεδομένη χρονική στιγμή. Μια εναλλακτική μέθοδος που επιτρέπει την ταυτόχρονη εκτέλεση πολλών λειτουργικών περιγράφεται στο crossref:virtualization[virtualization,Εικονικοποίηση]. [[bsdinstall-collect-network-information]] === Συλλέξτε Πληροφορίες για το Δίκτυο Κάποιες μέθοδοι εγκατάστασης του FreeBSD χρειάζονται μια σύνδεση δικτύου για να κατεβάσουν αρχεία. Για να συνδεθείτε με ένα δίκτυο Ethernet (ή μέσω καλωδιακού ή DSL modem με διεπαφή Ethernet), το πρόγραμμα εγκατάστασης θα σας ζητήσει πληροφορίες σχετικά με το δίκτυο σας. Συχνά, γίνεται χρήση του _DHCP_ ώστε οι ρυθμίσεις του δικτύου να γίνονται αυτόματα. Αν δεν διαθέτετε DHCP, θα πρέπει να βρείτε τις παρακάτω πληροφορίες από τον τοπικό σας διαχειριστή δικτύου ή τον παροχέα των υπηρεσιών σας: . Διεύθυνση IP . Μάσκα Υποδικτύου . Διεύθυνση IP προεπιλεγμένου δρομολογητή . Όνομα Τομέα για το τοπικό δίκτυο . Διευθύνσεις IP των διακομιστών DNS === Ελέγξτε για Παροράματα (Errata) στο FreeBSD Αν και το FreeBSD Project πασχίζει για να εξασφαλίσει ότι κάθε νέα έκδοση του FreeBSD θα είναι όσο πιο σταθερή γίνεται, ορισμένες φορές στη διαδικασία αυτή εισέρχονται λάθη. Σε πολύ σπάνιες περιπτώσεις, τα λάθη αυτά επηρεάζουν τη διαδικασία εγκατάστασης. Καθώς τα προβλήματα αυτά γίνονται αντιληπτά και επιδιορθώνονται, σημειώνονται στα link:https://www.FreeBSD.org/releases/9.0r/errata/[Παροράματα του FreeBSD] στη δικτυακή τοποθεσία του FreeBSD. Ελέγξτε τα παροράματα πριν ξεκινήσετε την εγκατάσταση, για να βεβαιωθείτε ότι δεν υπάρχουν προβλήματα που μπορούν να επηρεάσουν τη διαδικασία. Μπορείτε να βρείτε πληροφορίες και παροράματα για όλες τις εκδόσεις στη σελίδα link:https://www.FreeBSD.org/releases/[πληροφοριών έκδοσης] στην link:https://www.FreeBSD.org/[δικτυακή τοποθεσία του FreeBSD]. [[bsdinstall-installation-media]] === Προετοιμάστε τα Μέσα Εγκατάστασης Η εγκατάσταση του FreeBSD ξεκινάει με την εκκίνηση του υπολογιστή με τη χρήση ενός FreeBSD CD, DVD ή μνήμης USB. Το πρόγραμμα εγκατάστασης δεν μπορεί να εκτελεστεί μέσα από κάποιο άλλο λειτουργικό σύστημα. Εκτός από τα τυποποιημένα μέσα εγκατάστασης που περιέχουν όλα τα απαραίτητα αρχεία εγκατάστασης του FreeBSD, διατίθεται επίσης και η εκδοχή _bootonly_. Αυτό το μέσο εγκατάστασης δεν περιέχει τα απαραίτητα αρχεία, αλλά τα κατεβάζει από το δίκτυο κατά τη διάρκεια της εγκατάστασης. Κατά συνέπεια, το συγκεκριμένο CD είναι αρκετά μικρότερο σε μέγεθος ενώ και το απαιτούμενο εύρος ζώνης του δικτύου περιορίζεται καθώς κατεβαίνουν μόνο τα αρχεία που απαιτούνται. Μπορείτε να βρείτε έτοιμα μέσα εγκατάστασης για το FreeBSD στην link:https://www.FreeBSD.org/where/[δικτυακή τοποθεσία του FreeBSD.]. Κατεβάστε επίσης το αρχείο [.filename]#CHECKSUM.SHA256# από τον ίδιο κατάλογο που περιέχει και το αρχείο εγκατάστασης και χρησιμοποιήστε το για να ελέγξετε την ακεραιότητα του αρχείου εγκατάστασης υπολογίζοντας το _Άθροισμα Ελέγχου (checksum)_. Το FreeBSD διαθέτει το man:sha256[1] για αυτό το σκοπό και θα βρείτε αντίστοιχα προγράμματα και σε άλλα λειτουργικά συστήματα. Επαληθεύστε το άθροισμα ελέγχου σύμφωνα με αυτό που αναγράφεται στο αρχείο [.filename]#CHECKSUM.SHA256#. Τα αθροίσματα πρέπει να είναι ίδια. Αν δεν είναι, το αρχείο εγκατάστασης αλλοιώθηκε κατά το κατέβασμα και είναι άχρηστο. [TIP] ==== Αν διαθέτετε ήδη ένα CDROM, DVD ή USB οδηγό εγκατάστασης FreeBSD, μπορείτε να παραλείψετε αυτή την ενότητα. ==== Τα CD και DVD αρχεία ISO του FreeBSD είναι εκκινήσιμα. Χρειάζεστε μόνο ένα από αυτά για την εγκατάσταση. Γράψτε το αρχείο ISO σε ένα CD ή DVD χρησιμοποιώντας τα αντίστοιχα προγράμματα εγγραφής που διαθέτει το τρέχον λειτουργικό σας σύστημα. Στο FreeBSD, η εγγραφή μπορείτε να γίνει με το πρόγραμμα man:cdrecord[1] από το port [.filename]#sysutils/cdrtools# που μπορείτε να εγκαταστήσετε από τη Συλλογή των Ports. Για να δημιουργήσετε μια εκκινήσιμη μνήμη Flash (USB), ακολουθήστε τα παρακάτω βήματα: [[bsdinstall-installation-media-memory-stick]] [.procedure] ==== . Ανακτήστε το Αρχείο ISO για τη Μνήμη Flash + Για το FreeBSD 9.0-RELEASE και μεταγενέστερες εκδόσεις, μπορείτε να κατεβάσετε το αντίστοιχο αρχείο από τον κατάλογο [.filename]#ISO-IMAGES/# στην τοποθεσία `ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/arch/arch/ISO-IMAGES/version/FreeBSD-version-RELEASE-arch-memstick.img`. Αντικαταστήστε το _arch_ και το _version_ με την αρχιτεκτονική και την έκδοση που θέλετε να εγκαταστήσετε. Για παράδειγμα, το αρχείο για το FreeBSD/i386 9.0-RELEASE βρίσκεται στη θέση link:ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/i386/ISO-IMAGES/9.0/FreeBSD-9.0-RELEASE-i386-memstick.img[ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/i386/ISO-IMAGES/9.0/FreeBSD-9.0-RELEASE-i386-memstick.img]. + [TIP] **** Ο κατάλογος είναι διαφορετικός για το FreeBSD 8._X_ και προηγούμενες εκδόσεις. Για περισσότερες πληροφορίες σχετικά με το κατέβασμα και την εγκατάσταση του FreeBSD 8._X_ και προηγούμενων εκδόσεων, δείτε το crossref:install[install,Εγκατάσταση του FreeBSD 8.x και Προγενέστερων Εκδόσεων]. **** + Το αρχείο για τη μνήμη Flash έχει επέκταση [.filename]#.img#. Ο κατάλογος [.filename]#ISO-IMAGES/# περιέχει πλήθος από διαφορετικά αρχεία. Θα πρέπει να κατεβάσετε το κατάλληλο ανάλογα με την έκδοση του FreeBSD και το υλικό του υπολογιστή που πρόκειται να χρησιμοποιηθεί. + [IMPORTANT] **** Πριν προχωρήσετε, _αντιγράψτε_ τυχόν δεδομένα που έχετε ήδη στη μνήμη USB, καθώς η παρακάτω διαδικασία θα τα _διαγράψει_. **** . Γράψτε το Αρχείο στη Μνήμη USB [.procedure] ====== *Procedure: Εγγραφή του Αρχείου με Χρήση του FreeBSD* [WARNING] **** Το παρακάτω παράδειγμα δείχνει τη συσκευή [.filename]#/dev/da0# ως τον προορισμό εγγραφής του αρχείου. Θα πρέπει να είστε πολύ προσεκτικοί και να βεβαιωθείτε για το όνομα της συσκευής που χρησιμοποιείτε, διαφορετικά ενδέχεται να διαγράψετε δεδομένα που χρειάζεστε. **** . Εγγραφή του Αρχείου με την man:dd[1] + Το αρχείο [.filename]#.img#_δεν_ είναι ένα συνηθισμένο αρχείο. Είναι ένα αρχείο _εικόνας (image)_ με όλο το περιεχόμενο που χρειάζεται η μνήμη USB. _Δεν μπορείτε_ να το αντιγράψετε ως ένα κανονικό αρχείο, θα χρειαστεί να το γράψετε απευθείας στη συσκευή προορισμού χρησιμοποιώντας την εντολή man:dd[1]: + [source,shell] .... # dd if=FreeBSD-9.0-RELEASE-i386-memstick.img of=/dev/da0 bs=64k .... ====== [.procedure] ====== *Procedure: Εγγραφή του Αρχείου Μέσω Windows(R)* [WARNING] **** Βεβαιωθείτε ότι χρησιμοποιείτε το σωστό όνομα οδηγού για την μνήμη USB, διαφορετικά μπορεί να προκληθεί απώλεια δεδομένων. **** . Ανάκτηση του Προγράμματος Image Writer για Windows(R) + Το Image Writer για Windows(R) είναι μια δωρεάν εφαρμογή που μπορεί να γράψει σωστά ένα αρχείο image σε μια μνήμη USB. Μπορείτε να το κατεβάσετε από την τοποθεσία https://launchpad.net/win32-image-writer/[https://launchpad.net/win32-image-writer/] και να το αποσυμπιέσετε σε ένα φάκελο. . Εγγραφή του Αρχείου με το Image Writer + Κάντε διπλό κλικ στο εικονίδιο Win32DiskImager για να ξεκινήσετε το πρόγραμμα. Βεβαιωθείτε ότι το γράμμα του οδηγού που φαίνεται στην επιλογή `Device` αντιστοιχεί στη μνήμη USB. Κάντε κλικ στο εικονίδιο με το φάκελο και επιλέξτε το αρχείο εικόνας που θα γραφεί στη μνήμη USB. Κάντε κλικ στο btn:[Save] για να αποδεχθείτε το όνομα του αρχείου εικόνας. Βεβαιωθείτε ότι οι παραπάνω ενέργειες είναι σωστές και ότι δεν υπάρχουν ανοικτά παράθυρα στο σύστημα σας που να απεικονίζουν φακέλους της μνήμης USB. Τέλος, κάντε κλικ στο btn:[Write] για να γράψετε το αρχείο εικόνας στη μνήμη USB. ====== ==== [NOTE] ==== Δεν υποστηρίζεται πλέον η εγκατάσταση από δισκέτες ==== Είστε πλέον έτοιμοι να ξεκινήσετε την εγκατάσταση του FreeBSD. [[bsdinstall-start]] == Ξεκινώντας την Εγκατάσταση [IMPORTANT] ==== Από προεπιλογή, η εγκατάσταση δεν θα κάνει αλλαγές στους δίσκους σας μέχρι να δείτε το παρακάτω μήνυμα: [.programlisting] .... Your changes will now be written to disk. If you have chosen to overwrite existing data, it will be PERMANENTLY ERASED. Are you sure you want to commit your changes? .... Μπορείτε να εγκαταλείψετε την εγκατάσταση οποιαδήποτε στιγμή πριν από την παραπάνω προειδοποίηση, χωρίς να έχουν γίνει αλλαγές στα περιεχόμενα του δίσκου σας. Αν ανησυχείτε ότι ενδεχομένως έχετε κάνει κάτι λάθος, μπορείτε απλά να σβήσετε τον υπολογιστή σας πριν από αυτό το σημείο και δεν θα γίνει καμιά ζημιά. ==== [[bsdinstall-starting]] === Εκκίνηση [[bsdinstall-starting-i386]] ==== Εκκίνηση στις Αρχιτεκτονικές i386(TM) και amd64 [.procedure] . Αν προετοιμάσατε μια "εκκινήσιμη" μνήμη USB όπως περιγράφεται στο <>, τοποθετήστε τη μνήμη στην υποδοχή του υπολογιστή σας πριν τον ενεργοποιήσετε. + Αν πρόκειται να εκκινήσετε από το CDROM, θα χρειαστεί να ενεργοποιήσετε τον υπολογιστή σας και να εισάγετε το CDROM όσο πιο γρήγορα γίνεται. . Ρυθμίστε το μηχάνημα σας να ξεκινάει είτε από το CDROM είτε από την USB, ανάλογα με το μέσο εγκατάστασης που πρόκειται να χρησιμοποιήσετε. Γενικά, αυτό επιτυγχάνεται αλλάζοντας τη σχετική ρύθμιση στο BIOS. Τα περισσότερα συστήματα επιτρέπουν επίσης την επιλογή μιας συσκευής εκκίνησης καθώς ξεκινούν, τυπικά με τα πλήκτρα kbd:[F10], kbd:[F11], kbd:[F12], ή kbd:[Escape]. . Αν ο υπολογιστής σας ξεκινήσει όπως συνήθως και φορτώσει το ήδη υπάρχον λειτουργικό σύστημα, μπορεί να συμβαίνει κάτι από τα παρακάτω: .. Δεν τοποθετήσατε το CD ή DVD αρκετά νωρίς κατά την εκκίνηση. Αφήστε το μέσο στον οδηγό και δοκιμάστε να επανεκκινήσετε τον υπολογιστή σας. .. Οι αλλαγές ρυθμίσεων που κάνατε στο BIOS δεν λειτούργησαν σωστά. Θα πρέπει να ξαναδοκιμάσετε μέχρι να πετύχετε τις σωστές ρυθμίσεις. .. Το BIOS της μητρικής σας δεν υποστηρίζει εκκίνηση από το μέσο που έχετε επιλέξει. Μπορείτε να χρησιμοποιήσετε τον http://www.plop.at/en/bootmanager.html[Plop Boot Manager] για να εκκινήσετε παλιά μηχανήματα από CD ή USB. . Θα αρχίσει η εκκίνηση του FreeBSD. Αν ξεκινάτε από CDROM, θα δείτε μια οθόνη σαν την παρακάτω (έχουμε παραλείψει τις πληροφορίες έκδοσης): + [source,shell] .... Booting from CD-ROM... 645MB medium detected CD Loader 1.2 Building the boot loader arguments Looking up /BOOT/LOADER... Found Relocating the loader and the BTX Starting the BTX loader BTX loader 1.00 BTX version is 1.02 Consoles: internal video/keyboard BIOS CD is cd0 BIOS drive C: is disk0 BIOS drive D: is disk1 BIOS 636kB/261056kB available memory FreeBSD/i386 bootstrap loader, Revision 1.1 Loading /boot/defaults/loader.conf /boot/kernel/kernel text=0x64daa0 data=0xa4e80+0xa9e40 syms=[0x4+0x6cac0+0x4+0x88e9d] \ .... . Εμφανίζεται η οθόνη του φορτωτή εκκίνησης του FreeBSD: + [[bsdinstall-boot-loader-menu]] .Μενού Φορτωτή Εκκίνησης του FreeBSD image::bsdinstall-boot-loader-menu.png[] + Περιμένετε δέκα δευτερόλεπτα, ή πιέστε kbd:[Enter]. ==== Εκκίνηση στον Macintosh(R) PowerPC(R) Στα περισσότερα μηχανήματα, μπορείτε να κρατήσετε πιεσμένο το πλήκτρο kbd:[C] κατά την εκκίνηση και θα ξεκινήσετε από το CD. Σε διαφορετική περίπτωση, κρατήστε πιεσμένα τα πλήκτρα kbd:[Command+Option+O+F], ή kbd:[Windows+Alt+O+F] αν χρησιμοποιείτε πληκτρολόγιο που δεν είναι Apple(R). Στην προτροπή `0 >` γράψτε: [source,shell] .... boot cd:,\ppc\loader cd:0 .... Σε μηχανήματα Xserve χωρίς πληκτρολόγιο, δείτε την http://support.apple.com/kb/TA26930[σελίδα τεχνικής υποστήριξης της Apple(R)] για πληροφορίες εκκίνησης στο Open Firmware. ==== Εκκίνηση στον sparc64 Τα περισσότερα συστήματα sparc64 είναι ρυθμισμένα να εκκινούν αυτόματα από το σκληρό δίσκο. Για να εγκαταστήσετε το FreeBSD, θα πρέπει να εκκινήσετε από το δίκτυο ή από ένα CDROM. Θα χρειαστεί να εισέλθετε στις ρυθμίσεις της PROM (OpenFirmware). Για να γίνει αυτό, επανεκκινήστε το σύστημα και περιμένετε μέχρι να εμφανιστεί το μήνυμα εκκίνησης. Το ακριβές μήνυμα εξαρτάται από το μοντέλο, αλλά γενικά θα δείχνει όπως το παρακάτω: [source,shell] .... Sun Blade 100 (UltraSPARC-IIe), Keyboard Present Copyright 1998-2001 Sun Microsystems, Inc. All rights reserved. OpenBoot 4.2, 128 MB memory installed, Serial #51090132. Ethernet address 0:3:ba:b:92:d4, Host ID: 830b92d4. .... Αν μετά από αυτό το σημείο το σύστημα σας συνεχίζει με εκκίνηση από το σκληρό δίσκο, θα πρέπει να πιέσετε kbd:[L1+A] ή kbd:[Stop+A] στο πληκτρολόγιο, ή να στείλετε σήμα `BREAK` μέσω της σειριακής κονσόλας (χρησιμοποιώντας π.χ. το `~#` στο man:tip[1] ή man:cu[1]) για να βγείτε στην προτροπή της PROM η οποία μοιάζει με την παρακάτω: [source,shell] .... ok <.> ok {0} <.> .... <.> Αυτή η προτροπή φαίνεται σε συστήματα με μόνο μία CPU. <.> Αυτή η προτροπή φαίνεται σε συστήματα SMP. Το ψηφίο δείχνει τον αριθμό της ενεργής CPU. Στο σημείο αυτό, τοποθετήστε το CDROM στον οδηγό και στην προτροπή της PROM γράψτε `boot cdrom`. [[bsdinstall-view-probe]] === Επισκόπηση των Αποτελεσμάτων Ανίχνευσης Συσκευών Οι τελευταίες εκατοντάδες γραμμές που πέρασαν από την οθόνη σας αποθηκεύονται και μπορείτε να τις ξαναδείτε. Για να δείτε τα περιεχόμενα της προσωρινής μνήμης (buffer) πιέστε kbd:[Scroll Lock]. Με τον τρόπο αυτό ενεργοποιείται η κύλιση της οθόνης. Μπορείτε έπειτα να χρησιμοποιήσετε τα πλήκτρα με τα βελάκια ή τα kbd:[PageUp] και kbd:[PageDown] για να δείτε τα αποτελέσματα. Πιέστε ξανά το kbd:[Scroll Lock] για να σταματήσετε την κύλιση. Κάντε το αυτό τώρα, για να ξαναδείτε το κείμενο που κύλησε εκτός οθόνης καθώς ο πυρήνας εκτελούσε την ανίχνευση συσκευών. Θα δείτε κείμενο αντίστοιχο με το <>, αν και θα υπάρχουν διαφορές ανάλογα με τις συσκευές που διαθέτει ο υπολογιστής σας. [[bsdinstall-dev-probe]] .Τυπικά Αποτελέσματα Ανίχνευσης Συσκευών Ελέγξτε προσεκτικά τα αποτελέσματα της ανίχνευσης συσκευών για να βεβαιωθείτε ότι το FreeBSD βρήκε όλες τις συσκευές που αναμένατε. Αν κάποια συσκευή δεν βρέθηκε, δεν θα φαίνεται στην παραπάνω λίστα. Τα crossref:kernelconfig[kernelconfig-modules,Αρθρώματα Πυρήνα] σας επιτρέπουν να προσθέσετε υποστήριξη για συσκευές που δεν υπάρχουν στον πυρήνα [.filename]#GENERIC#. Μετά τη διαδικασία ανίχνευσης συσκευών θα δείτε το <>. Το μέσο εγκατάστασης μπορεί να χρησιμοποιηθεί με τρεις τρόπους: για να εγκαταστήσετε το FreeBSD, ως "live CD" ή απλά για να αποκτήσετε πρόσβαση σε ένα κέλυφος του FreeBSD. Χρησιμοποιήστε τα βελάκια για να κάνετε μια επιλογή και το kbd:[Enter] για να την επιβεβαιώσετε. [[bsdinstall-choose-mode]] .Επιλογή Τρόπου Λειτουργίας Μέσου Εγκατάστασης image::bsdinstall-choose-mode.png[] Επιλέξτε btn:[Install] για να ξεκινήσετε το πρόγραμμα εγκατάστασης. [[using-bsdinstall]] == Εισαγωγή στο bsdinstall Το bsdinstall είναι μια εφαρμογή εγκατάστασης για το FreeBSD που βασίζεται σε περιβάλλον κειμένου. Γράφτηκε από τον {nwhitehorn} και χρησιμοποιήθηκε πρώτη φορά το 2011 στο FreeBSD 9.0. [NOTE] ==== Η εφαρμογή pc-sysinstall του {kmoore} συμπεριλαμβάνεται με το http://pcbsd.org[PC-BSD] και μπορεί επίσης να χρησιμοποιηθεί για την http://wiki.pcbsd.org/index.php/Use_PC-BSD_Installer_to_Install_FreeBSD[εγκατάσταση του FreeBSD]. Αν και μερικές φορές συγχέεται με το bsdinstall οι δύο αυτές εφαρμογές δεν σχετίζονται. ==== Το σύστημα μενού του bsdinstall ελέγχεται μέσω των πλήκτρων με τα βελάκια και τα πλήκτρα kbd:[Enter], kbd:[Tab], kbd:[Space] και μερικά ακόμα. [[bsdinstall-keymap]] === Επιλογές στο Μενού Keymap Ανάλογα με το είδος της κονσόλας που χρησιμοποιείτε, το bsdinstall ίσως σας ρωτήσει αν επιθυμείτε να επιλέξετε μια διάταξη πληκτρολογίου διαφορετική από την προεπιλεγμένη. [[bsdinstall-keymap-select-default]] .Επιλογή Διάταξης Πληκτρολογίου image::bsdinstall-keymap-select-default.png[] Αν επιλέξετε btn:[YES] θα εμφανιστεί η οθόνη επιλογής που φαίνεται παρακάτω. Σε διαφορετική περίπτωση, η οθόνη αυτή δεν θα εμφανιστεί και θα χρησιμοποιηθεί η προεπιλεγμένη διάταξη πληκτρολογίου. [[bsdinstall-config-keymap]] .Μενού Επιλογής Διάταξης Πληκτρολογίου image::bsdinstall-config-keymap.png[] Επιλέξτε την διάταξη πληκτρολογίου που είναι πιο κοντά στο πληκτρολόγιο που διαθέτετε, χρησιμοποιώντας τα πάνω και κάτω βελάκια και επιβεβαιώνοντας με το kbd:[Enter]. [NOTE] ==== Αν πιέσετε kbd:[Esc] θα χρησιμοποιηθεί η προεπιλεγμένη διάταξη. Αν η διάταξη του τρέχοντος πληκτρολογίου δεν είναι προφανής, μια ασφαλής επιλογή είναι το [.guimenuitem]#United States of America ISO-8859-1#. ==== [[bsdinstall-hostname]] === Καθορισμός Ονόματος Υπολογιστή (hostname) Στο επόμενο βήμα, το bsdinstall θα σας ρωτήσει για το όνομα υπολογιστή (hostname) το οποίο θα δοθεί στο νέο σύστημα. [[bsdinstall-config-hostname]] .Καθορισμός Ονόματος Υπολογιστή image::bsdinstall-config-hostname.png[] Το όνομα που θα δώσετε πρέπει να περιλαμβάνει και τον τομέα (fully-qualified) όπως για παράδειγμα `machine3.example.com` [[bsdinstall-components]] === Επιλογή Στοιχείων Εγκατάστασης Στο επόμενο βήμα, το bsdinstall θα σας καλέσει να επιλέξετε ποια προαιρετικά στοιχεία του λειτουργικού επιθυμείτε να εγκαταστήσετε. [[bsdinstall-config-components]] .Επιλογή Στοιχείων Εγκατάστασης image::bsdinstall-config-components.png[] Η επιλογή των στοιχείων εγκατάστασης εξαρτάται κυρίως από την χρήση που θα έχει το σύστημα και το διαθέσιμο ελεύθερο χώρο στο δίσκο. Ο πυρήνας και τα βασικά προγράμματα του FreeBSD (γνωστά και ως "base system" ή βασικό σύστημα) εγκαθίστανται υποχρεωτικά. Ανάλογα με το είδος της εγκατάστασης, κάποια από τα παρακάτω στοιχεία μπορεί να μην εμφανιστούν. .Προαιρετικά Στοιχεία * `doc` - Επιπρόσθετη τεκμηρίωση, κυρίως ιστορικής σημασίας. Η τεκμηρίωση που παρέχεται από την Ομάδα Τεκμηρίωσης του FreeBSD εγκαθίσταται χωριστά σε επόμενο στάδιο. * `games` - Κάποια παραδοσιακά BSD παιχνίδια που περιλαμβάνουν τα fortune, rot13 και άλλα. * `lib32` - Βιβλιοθήκες συμβατότητας για εκτέλεση εφαρμογών 32-bit σε 64-bit εκδόσεις του FreeBSD. * `ports` - Η Συλλογή των Ports του FreeBSD. + Η Συλλογή των Ports αποτελεί ένα εύκολο και βολικό τρόπο εγκατάστασης λογισμικού. Η Συλλογή των Ports δεν περιέχει τον πηγαίο κώδικα που απαιτείται για τη μεταγλώττιση του λογισμικού. Πρόκειται στην πραγματικότητα για μια συλλογή αρχείων που αυτοματοποιεί τη μεταφόρτωση, μεταγλώττιση και εγκατάσταση λογισμικού τρίτων κατασκευαστών. Το crossref:ports[ports,Εγκατάσταση Εφαρμογών: Πακέτα και Ports] αναλύει τον τρόπο χρήσης της Συλλογής των Ports. + [WARNING] ==== Το πρόγραμμα εγκατάστασης δεν ελέγχει για να δει αν διαθέτετε αρκετό ελεύθερο χώρο στο δίσκο. Επιλέξτε αυτό το στοιχείο μόνο αν έχετε αρκετό χώρο. Από το FreeBSD 9.0 και μετά, η Συλλογή των Ports καταλαμβάνει περίπου {ports-size} χώρο στο δίσκο. Μπορείτε με βεβαιότητα να θεωρήσετε ότι ο χώρος αυτός θα είναι ακόμα μεγαλύτερος στις νεώτερες εκδόσεις του FreeBSD. ==== * `src` - Ο Πηγαίος Κώδικας του Συστήματος. + Το FreeBSD έρχεται με πλήρη πηγαίο κώδικα, τόσο για τον πυρήνα όσο και για τα βασικά προγράμματα. Αν και ο πηγαίος κώδικας δεν απαιτείται για την πλειονότητα των εφαρμογών, ίσως να τον χρειαστείτε για τη μεταγλώττιση συγκεκριμένων προγραμμάτων που παρέχονται ως πηγαίος κώδικας (π.χ. οδηγούς συσκευών ή αρθρώματα πυρήνα), ή για εργασίες ανάπτυξης του ίδιου του FreeBSD. + Το πλήρες δέντρο του πηγαίου κώδικα καταλαμβάνει 1 GB χώρου στο δίσκο, ενώ μια πλήρης μεταγλώττιση όλου του FreeBSD απαιτεί επιπλέον 5 GB χώρου. [[bsdinstall-netinstall]] == Εγκατάσταση από το Δίκτυο Το μέσο εγκατάστασης _bootonly_ δεν διαθέτει αντίγραφα των αρχείων εγκατάστασης. Όταν χρησιμοποιείτε την μέθοδο _bootonly_, τα αρχεία μεταφορτώνονται από το δίκτυο κατά απαίτηση. [[bsdinstall-netinstall-notify]] .Εγκατάσταση από το Δίκτυο image::bsdinstall-netinstall-files.png[] Μετά την ρύθμιση των παραμέτρων δικτύου όπως φαίνεται στο <>, γίνεται η επιλογή ενός mirror site. Τα mirror sites διαθέτουν αντίγραφα των αρχείων του FreeBSD. Επιλέξτε ένα mirror site το οποίο βρίσκεται όσο το δυνατόν πιο κοντά στην περιοχή σας. Με τον τρόπο αυτό, η μεταφόρτωση των αρχείων θα είναι ταχύτερη και θα μειωθεί ο χρόνος εγκατάστασης. [[bsdinstall-netinstall-mirror]] .Επιλογή Mirror image::bsdinstall-netinstall-mirrorselect.png[] Η εγκατάσταση θα συνεχιστεί με τον ίδιο τρόπο όπως και αν τα αρχεία ήταν διαθέσιμα τοπικά. [[bsdinstall-partitioning]] == Εκχώρηση Χώρου στο Δίσκο Υπάρχουν τρεις τρόποι να εκχωρήσετε χώρο για το FreeBSD. Με τη μέθοδο _Guided (καθοδηγούμενη)_, οι κατατμήσεις δημιουργούνται αυτόματα, ενώ με τη μέθοδο _Manual (χειροκίνητη)_ οι προχωρημένοι χρήστες μπορούν να δημιουργήσουν προσαρμοσμένες κατατμήσεις. Τέλος, υπάρχει η επιλογή να εκκινήσετε ένα κέλυφος και να δημιουργήσετε τις κατατμήσεις με απευθείας χρήση προγραμμάτων της γραμμής εντολών όπως man:gpart[8], man:fdisk[8], και man:bsdlabel[8]. [[bsdinstall-part-guided-manual]] .Επιλογή Guided ή Manual Partitioning image::bsdinstall-part-guided-manual.png[] [[bsdinstall-part-guided]] === Καθοδηγούμενη (Guided) Κατάτμηση Αν έχετε συνδέσει πολλαπλούς δίσκους, επιλέξτε αυτόν στον οποίο θα εγκαταστήσετε το FreeBSD. [[bsdinstall-part-guided-disk]] .Επιλογή από Πολλαπλούς Δίσκους image::bsdinstall-part-guided-disk.png[] Μπορείτε να εκχωρήσετε είτε ολόκληρο το δίσκο, είτε ένα μέρος του στο FreeBSD. Αν επιλέξετε btn:[Entire Disk], θα δημιουργηθούν μια κατάλληλη διάταξη κατατμήσεων ώστε να χρησιμοποιηθεί ολόκληρος ο δίσκος. Αν επιλέξετε btn:[Partition], θα δημιουργηθεί μια διάταξη που θα καταλαμβάνει τον ελεύθερο χώρο του δίσκου. [[bsdinstall-part-entire-part]] .Επιλογή Ολόκληρου Δίσκου ή Κατάτμησης image::bsdinstall-part-entire-part.png[] Ελέγξτε προσεκτικά τη διάταξη των κατατμήσεων που δημιουργήθηκε. Αν βρείτε κάποιο λάθος, επιλέξτε btn:[Revert] για να επαναφέρετε τις προηγούμενες κατατμήσεις ή btn:[Auto] για να δημιουργήσετε τις κατατμήσεις που προτείνονται αυτόματα από το FreeBSD. Μπορείτε να δημιουργήσετε, να τροποποιήσετε και να διαγράψετε κατατμήσεις χειροκίνητα. Όταν οι κατατμήσεις είναι οι σωστές, επιλέξτε btn:[Finish] για να συνεχίσετε με την εγκατάσταση. [[bsdinstall-part-review]] .Επισκόπηση Κατατμήσεων image::bsdinstall-part-review.png[] [[bsdinstall-part-manual]] === Χειροκίνητη Δημιουργία Κατατμήσεων Επιλέγοντας χειροκίνητη δημιουργία κατατμήσεων, θα μεταφερθείτε απευθείας στον επεξεργαστή κατατμήσεων. [[bsdinstall-part-manual-create]] .Χειροκίνητη Δημιουργία Κατατμήσεων image::bsdinstall-part-manual-create.png[] Επιλέγοντας ένα οδηγό ([.filename]#ada0# στο παράδειγμα μας) και το πλήκτρο btn:[Create] θα δείτε ένα μενού για την επιλογή του σχήματος κατατμήσεων (_partitioning scheme_). [[bsdinstall-part-manual-partscheme]] .Χειροκίνητη Δημιουργία Κατατμήσεων image::bsdinstall-part-manual-partscheme.png[] Το σύστημα κατατμήσεων GPT είναι συνήθως το καταλληλότερο για τα περισσότερους PC-συμβατούς υπολογιστές. Παλαιότερα λειτουργικά συστήματα δεν είναι συμβατά με τη μέθοδο GPT και χρειάζονται κατατμήσεις τύπου MBR. Τα υπόλοιπα είδη κατατμήσεων χρησιμοποιούνται σε παλιά ή μη-συνηθισμένα συστήματα υπολογιστών. .Κατηγορίες Κατατμήσεων [cols="1,1", frame="all", options="header"] |=== <| Συντομογραφία <| Περιγραφή |APM |http://support.apple.com/kb/TA21692[Apple Partition Map, χρησιμοποιείται στο PowerPC(R) Macintosh(R).] |BSD |Κατατμήσεις BSD χωρίς MBR, ορισμένες φορές καλούνται και "επικίνδυνα αφοσιωμένη κατάσταση". Δείτε το man:bsdlabel[8]. |GPT |http://en.wikipedia.org/wiki/GUID_Partition_Table[Πίνακας Κατατμήσεων GUID.] |MBR |http://en.wikipedia.org/wiki/Master_boot_record[Master Boot Record.] |PC98 |http://en.wikipedia.org/wiki/Pc9801[Παραλλαγή του MBR που χρησιμοποιείται σε υπολογιστές NEC PC-98.] |VTOC8 |Volume Table Of Contents, χρησιμοποιείται στα Sun SPARC64 και UltraSPARC. |=== Μετά τη δημιουργία του σχήματος κατατμήσεων, αν επιλέξετε ξανά btn:[Create] θα δημιουργήσετε νέες κατατμήσεις. [[bsdinstall-part-manual-addpart]] .Χειροκίνητη Δημιουργία Κατατμήσεων image::bsdinstall-part-manual-addpart.png[] Η τυποποιημένη εγκατάσταση FreeBSD με χρήση GPT δημιουργεί τουλάχιστον τρεις κατατμήσεις: .Τυποποιημένες FreeBSD GPT Κατατμήσεις * `freebsd-boot` - Ο κώδικας εκκίνησης του FreeBSD. Η κατάτμηση αυτή πρέπει να είναι η πρώτη στο δίσκο. * `freebsd-ufs` - Σύστημα αρχείων FreeBSD UFS. * `freebsd-swap` - Χώρος swap FreeBSD. Ένα άλλο αξιοσημείωτο είδος κατάτμησης, είναι το `freebsd-zfs`. Δείτε το crossref:filesystems[filesystems-zfs,Το Σύστημα Αρχείων Z (ZFS)]. Μπορείτε να δείτε τα υπόλοιπα διαθέσιμα είδη κατατμήσεων GPT στο man:gpart[8]. Μπορείτε να δημιουργήσετε πολλαπλά συστήματα αρχείων. Κάποιοι χρήστες προτιμούν τη δημιουργία των παραδοσιακών κατατμήσεων με χωριστά συστήματα αρχείων για τα [.filename]#/#, [.filename]#/var#, και [.filename]#/usr#. Δείτε το <> για ένα παράδειγμα. Μπορείτε να εισάγετε το μέγεθος με τη βοήθεια κοινών συντομεύσεων: _K_ για kilobytes, _M_ για megabytes, ή _G_ για gigabytes. [TIP] ==== Η καλύτερη απόδοση επιτυγχάνεται με ευθυγράμμιση των τομέων του δίσκου (sector alignment). Η σωστή ευθυγράμμιση επιτυγχάνεται με τη δημιουργία κατατμήσεων με μεγέθη πολλαπλάσια των 4K bytes σε οδηγούς που χρησιμοποιούν τομείς των 512 bytes ή 4K-byte. Σε γενικές γραμμές, η χρήση κατατμήσεων με μεγέθη που είναι άρτια πολλαπλάσια του 1Μ ή 1G είναι ο ευκολότερος τρόπος να επιβεβαιώσουμε ότι κάθε κατάτμηση ξεκινά σε ζυγό πολλαπλάσιο των 4Κ. Μια εξαίρεση: την παρούσα στιγμή η κατάτμηση _freebsd-boot_ δεν μπορεί να είναι μεγαλύτερη των 512Κ λόγων περιορισμών του κώδικα εκκίνησης. ==== Σε κάθε κατάτμηση που περιέχει σύστημα αρχείων, χρειάζεται ένα σημείο προσάρτησης. Αν χρησιμοποιηθεί μόνο μια κατάτμηση UFS, το σημείο προσάρτησης θα είναι η [.filename]#/#. θα σας ζητηθεί επίσης μια ετικέτα (_label_). Η ετικέτα είναι ένα όνομα το οποίο δίνεται σε μια κατάτμηση. Το όνομα ενός δίσκου ή οι αριθμοί που περιγράφουν τις κατατμήσεις μπορεί να αλλάξουν αν ο δίσκος συνδεθεί σε άλλη θύρα ή ελεγκτή, αλλά η ετικέτα του παραμένει σταθερή. Με χρήση της ετικέτας σε αρχεία όπως το [.filename]#/etc/fstab# το σύστημα γίνεται πιο ανεκτικό σε αλλαγές του υλικού. Οι ετικέτες GPT εμφανίζονται στον κατάλογο [.filename]#/dev/gpt/# όταν γίνεται η προσάρτηση της συσκευής. Σε άλλα είδη κατατμήσεων υπάρχουν διαφορετικές δυνατότητες όσο αφορά τις ετικέτες, οι οποίες εμφανίζονται σε διαφορετικούς υποκαταλόγους στο [.filename]#/dev/#. [TIP] ==== Χρησιμοποιήστε μοναδικές ετικέτες σε κάθε σύστημα αρχείων για να αποφύγετε συγκρούσεις που μπορεί να προκληθούν από όμοια ονόματα. Σε κάθε ετικέτα μπορείτε να συμπεριλάβετε μερικά γράμματα από το όνομα του υπολογιστή ή τη θέση του, ή ακόμα και τη χρήση του. Θα μπορούσατε για παράδειγμα να ονομάσετε τον κεντρικό κατάλογο `labroot` ή `rootfs-lab` σε ένα υπολογιστή που ανήκει σε ένα εργαστήριο. ==== [[bsdinstall-part-manual-splitfs]] .Δημιουργία Παραδοσιακών Κατατμήσεων στο Σύστημα Αρχείων [example] ==== Αν επιθυμείτε να χρησιμοποιήσετε το παραδοσιακό σύστημα κατατμήσεων του FreeBSD όπου τα συστήματα αρχείων [.filename]#/#, [.filename]#/var#, [.filename]#/tmp# και [.filename]#/usr# βρίσκονται σε χωριστές κατατμήσεις, δημιουργήστε ένα πίνακα κατατμήσεων GPT και ορίστε τις κατατμήσεις με τον τρόπο που φαίνεται παρακάτω. Τα μεγέθη που φαίνονται είναι τυπικά για ένα σκληρό δίσκο χωρητικότητας 20G. Αν διαθέτετε περισσότερο χώρο, ίσως είναι χρήσιμο να μεγαλώσετε την κατάτμηση swap ή [.filename]#/var#. Στο παράδειγμα μας, οι ετικέτες που χρησιμοποιούνται ξεκινούν με `ex` (από τη λέξη "example") αλλά καλό θα είναι να χρησιμοποιήσετε δικές σας μονάδικες ετικέτες όπως αναφέραμε παραπάνω. Από προεπιλογή, το [.filename]#gptboot# του FreeBSD αναμένει την πρώτη UFS κατάτμηση ως [.filename]#/#. [.informaltable] [cols="1,1,1,1", frame="none", options="header"] |=== | Τύπος Κατάτμησης | Μέγεθος | Σημείο Προσάρτησης | Ετικέτα |`freebsd-boot` |`512K` +| +| |`freebsd-ufs` |`2G` |[.filename]#/# |`exrootfs` |`freebsd-swap` |`4G` | |`exswap` |`freebsd-ufs` |`2G` |[.filename]#/var# |`exvarfs` |`freebsd-ufs` |`1G` |[.filename]#/tmp# |[.filename]#extmpfs# |`freebsd-ufs` |αποδεχθείτε την προεπιλογή (υπόλοιπος χώρος του δίσκου) |[.filename]#/usr# |`exusrfs` |=== ==== Μετά τη δημιουργία των προσαρμοσμένων κατατμήσεων, επιλέξτε btn:[Finish] για να συνεχίσετε με την εγκατάσταση. [[bsdinstall-final-warning]] == Επιβεβαίωση της Εγκατάστασης Σε αυτό το σημείο έχετε την τελευταία ευκαιρία να εγκαταλείψετε την εγκατάσταση χωρίς να γίνουν αλλαγές στο σκληρό δίσκο σας. [[bsdinstall-final-confirmation]] .Τελική Επιβεβαίωση image::bsdinstall-final-confirmation.png[] Επιλέξτε btn:[Commit] και πιέστε kbd:[Enter] για να συνεχίσετε. Αν χρειάζεται να κάνετε αλλαγές, επιλέξτε btn:[Back] για να επιστρέψετε στον επεξεργαστή κατατμήσεων. Με το πλήκτρο btn:[Revert & Exit] μπορείτε να εγκαταλείψετε το πρόγραμμα εγκατάστασης χωρίς να γίνουν αλλαγές στο σκληρό σας δίσκο. Ο χρόνος εγκατάστασης ποικίλει ανάλογα με τις διανομές και τα στοιχεία εγκατάστασης που έχετε επιλέξει, το μέσο εγκατάστασης και την ταχύτητα του υπολογιστή. Θα δείτε μια σειρά από μηνύματα σχετικά με την πρόοδο της διαδικασίας. Αρχικά, το πρόγραμμα εγκατάστασης θα γράψει τις κατατμήσεις στο δίσκο και θα εκτελέσει κατάλληλες εντολές `newfs` για να δημιουργήσει τα ανάλογα συστήματα αρχείων. Αν κάνετε εγκατάσταση μέσω δικτύου, το bsdinstall θα προχωρήσει μεταφορτώνοντας τα απαραίτητα αρχεία. [[bsdinstall-distfile-fetching]] .Μεταφόρτωση Αρχείων Εγκατάστασης image::bsdinstall-distfile-fetching.png[] Στη συνέχεια, θα γίνει έλεγχος ακεραιότητας των αρχείων εγκατάστασης για να επιβεβαιωθεί ότι δεν έχουν αλλοιωθεί κατά τη μεταφόρτωση ή κατά την ανάγνωση από το μέσο εγκατάστασης. [[bsdinstall-distfile-verify]] .Επαλήθευση Αρχείων Εγκατάστασης image::bsdinstall-distfile-verifying.png[] Στο τελευταίο βήμα, τα επιβεβαιωμένα αρχεία εγκατάστασης θα εξαχθούν και θα γραφούν στο σκληρό δίσκο. [[bsdinstall-distfile-extract]] .Εξαγωγή Αρχείων Εγκατάστασης image::bsdinstall-distfile-extracting.png[] Με το τέλος της εξαγωγής όλων των αρχείων εγκατάστασης, το bsdinstall θα εισέλθει στη διαδικασία ρυθμίσεων μετά την εγκατάσταση (δείτε <>). [[bsdinstall-post]] == Μετά την Εγκατάσταση Μετά από μια επιτυχημένη εγκατάσταση του FreeBSD, ακολουθεί μια σειρά ρυθμίσεων. Μπορείτε να επαναλάβετε οποιαδήποτε ρύθμιση αν εισέλθετε στην αντίστοιχη επιλογή στο τελικό μενού πριν επανεκκινήσετε στο νέο-εγκατεστημένο σας FreeBSD σύστημα. [[bsdinstall-post-root]] === Ρύθμιση του Κωδικού του `root` Θα πρέπει να ορίσετε ένα κωδικό πρόσβασης για το χρήστη `root`. Παρατηρήστε ότι δεν φαίνονται τα γράμματα που πληκτρολογείτε καθώς εισάγετε τον κωδικό. Μετά την εισαγωγή του κωδικού, θα πρέπει να τον εισάγετε ακόμα μια φορά. Με τον τρόπο αυτό εξασφαλίζεται ότι δεν έχει γίνει κάποιο λάθος κατά την πληκτρολόγηση. [[bsdinstall-post-set-root-passwd]] .Ρύθμιση του Κωδικού του `root` image::bsdinstall-post-root-passwd.png[] Η εγκατάσταση συνεχίζεται μετά την επιτυχή εισαγωγή του κωδικού. [[bsdinstall-config-network-dev]] === Ρύθμιση Καρτών Δικτύου [NOTE] ==== Η ρύθμιση του δικτύου παραλείπεται αν έχει ήδη πραγματοποιηθεί στα πλαίσια μιας εγκατάστασης _bootonly_. ==== Θα δείτε μια λίστα με όλες τις διεπαφές δικτύου που ανιχνεύθηκαν στον υπολογιστή σας. Επιλέξτε αυτή που επιθυμείτε να ρυθμίσετε. [[bsdinstall-configure-net-interface]] .Επιλογή μιας Διεπαφής Δικτύου image::bsdinstall-configure-network-interface.png[] [[bsdinstall-configure-net-wireless]] ==== Ρύθμιση Ασύρματης Κάρτας Δικτύου Αν επιλέξετε να ρυθμίσετε μια ασύρματη διεπαφή δικτύου, θα πρέπει να ρυθμίσετε τις παραμέτρους αναγνώρισης και ασφάλειας για να συνδεθείτε στο δίκτυο. Τα ασύρματα δίκτυα αναγνωρίζονται από το Αναγνωριστικό Υπηρεσίας ή Service Set Identifier (SSID). Το SSID είναι ένα σύντομο μοναδικό όνομα που αποδίδεται σε κάθε ασύρματο δίκτυο. Τα περισσότερα ασύρματα δίκτυα κρυπτογραφούν τα δεδομένα που μεταδίδονται για να προστατεύσουν τις πληροφορίες από μη εξουσιοδοτημένη χρήση. Συνίσταται να χρησιμοποιήσετε κρυπτογράφηση WPA2. Παλαιότερες μέθοδοι κρυπτογράφησης όπως το WEP προσφέρουν ελάχιστη ασφάλεια. Το πρώτο βήμα για να συνδεθείτε σε ένα ασύρματο δίκτυο είναι να σαρώσετε για Σημεία Ασύρματης Πρόσβασης (Access Points). [[bsdinstall-wireless-scan]] .Σάρωση για Access Points image::bsdinstall-configure-wireless-scan.png[] Τα SSIDs που θα βρείτε κατά τη διάρκεια της σάρωσης συνοδεύονται από τα είδη κρυπτογράφησης που διατίθενται για κάθε δίκτυο. Αν δεν βλέπετε το SSID που επιθυμείτε στη λίστα, επιλέξτε btn:[Rescan] για να εκτελέσετε τη σάρωση ξανά. Αν εξακολουθείτε να μη βλέπετε το επιθυμητό δίκτυο, ελέγξτε την κεραία για τυχόν προβλήματα ή μετακινήστε τον υπολογιστή πιο κοντά στο σημείο πρόσβασης. Να εκτελείτε νέα σάρωση μετά από κάθε αλλαγή. [[bsdinstall-wireless-accesspoints]] .Επιλογή Ασύρματου Δικτύου image::bsdinstall-configure-wireless-accesspoints.png[] Μετά την επιλογή του ασύρματου δικτύου, θα πρέπει να εισάγετε τις πληροφορίες που σχετίζονται με την κρυπτογράφηση. Σε δίκτυα WPA2 χρειάζεται να δώσετε μόνο ένα κωδικό πρόσβασης (γνωστό ως Pre-Shared Key ή PSK). Για λόγους ασφαλείας, οι χαρακτήρες που πληκτρολογείτε στο πεδίο εμφανίζονται ως αστερίσκοι. [[bsdinstall-wireless-wpa2]] .Ρύθμιση WPA2 image::bsdinstall-configure-wireless-wpa2setup.png[] Μετά την επιλογή του ασύρματου δικτύου και την εισαγωγή των πληροφοριών σύνδεσης, η εγκατάσταση συνεχίζεται με τη ρύθμιση των υπόλοιπων παραμέτρων του δικτύου. [[bsdinstall-ipv4]] ==== Ρύθμιση Δικτύου IPv4 Επιλέξτε αν θα χρησιμοποιηθεί δικτύωση IPv4. Πρόκειται για το πιο συνηθισμένο είδος σύνδεσης. [[bsdinstall-configure-net-ipv4]] .Επιλογή Δικτύωσης IPv4 image::bsdinstall-configure-network-interface-ipv4.png[] Υπάρχουν δύο μέθοδοι ρύθμισης του IPv4. Μέσω του _DHCP_ η ρύθμιση της διεπαφής γίνεται αυτόματα. Αυτή είναι και η συνιστώμενη μέθοδος. Η ρύθμιση _Static_ απαιτεί χειροκίνητη εισαγωγή πληροφοριών δικτύου. [NOTE] ==== Μη βάλετε τυχαίες ρυθμίσεις δικτύου, καθώς δεν θα λειτουργήσουν. Θα πρέπει να λάβετε τις πληροφορίες που αναφέρονται στο <> από τον διαχειριστή ή τον παροχέα του δικτύου σας. ==== [[bsdinstall-net-ipv4-dhcp-config]] ===== Ρύθμιση Δικτύου IPv4 μέσω DHCP Αν διαθέτετε εξυπηρετητή DHCP, επιλέξτε btn:[Yes] για να ρυθμίσετε αυτόματα την διεπαφή δικτύου. [[bsdinstall-net-ipv4-dhcp]] .Επιλέξτε Ρύθμιση IPv4 μέσω DHCP image::bsdinstall-configure-network-interface-ipv4-dhcp.png[] [[bsdinstall-net-ipv4-static-config]] ===== Στατική Ρύθμιση Δικτύου IPv4 Η στατική ρύθμιση της διεπαφής δικτύου, απαιτεί να εισάγετε κάποιες πληροφορίες σχετικά με το IPv4. [[bsdinstall-net-ipv4-static]] .Στατική Ρύθμιση IPv4 image::bsdinstall-configure-network-interface-ipv4-static.png[] * `IP Address` - Η διεύθυνση IP που θα εισάγετε χειροκίνητα σε αυτό τον υπολογιστή. Η διεύθυνση αυτή πρέπει να είναι μοναδική και να μην χρησιμοποιείται από οποιοδήποτε άλλο μηχάνημα στο τοπικό σας δίκτυο. * `Subnet Mask` - Η μάσκα υποδικτύου που χρησιμοποιεί το τοπικό σας δίκτυο. Τυπικά αυτή είναι `255.255.255.0`. * `Default Router` - Η διεύθυνση IP του προεπιλεγμένου δρομολογητή του δικτύου σας. Συνήθως είναι η διεύθυνση του δρομολογητή ή άλλου δικτυακού εξοπλισμού που συνδέει το τοπικό σας δίκτυο με το Internet. Θα τη δείτε επίσης να αναφέρετε ως _default gateway (προεπιλεγμένη πύλη)_. [[bsdinstall-ipv6]] ==== Ρύθμιση Δικτύου IPv6 Το IPv6 είναι μια νέα μέθοδος ρύθμισης δικτύου. Αν το δίκτυο σας διαθέτει IPv6 και επιθυμείτε να το ρυθμίσετε, πιέστε btn:[Yes] για να το επιλέξετε. [[bsdinstall-net-ipv6]] .Επιλογή Δικτύωσης IPv6 image::bsdinstall-configure-network-interface-ipv6.png[] Το IPv6 διαθέτει επίσης δύο μεθόδους ρύθμισης. Το _SLAAC_, ή _StateLess Address AutoConfiguration_, ρυθμίζει αυτόματα τις παραμέτρους του δικτύου σας. Η ρύθμιση _Static_ απαιτεί να κάνετε τις αντίστοιχες ρυθμίσεις χειροκίνητα. [[bsdinstall-net-ipv6-slaac-config]] ===== IPv6 Stateless Address Autoconfiguration Το SLAAC επιτρέπει σε μια συσκευή ενός δικτύου IPv6 να ζητήσει πληροφορίες αυτόματης ρύθμισης από ένα τοπικό δρομολογητή. Δείτε το http://tools.ietf.org/html/rfc4862[RFC4862] για περισσότερες πληροφορίες. [[bsdinstall-net-ipv6-slaac]] .Επιλέξτε Ρύθμιση IPv6 SLAAC image::bsdinstall-configure-network-interface-slaac.png[] [[bsdinstall-net-ipv6-static-config]] ===== Στατική Ρύθμιση Δικτύου IPv6 Η στατική ρύθμιση της διεπαφής δικτύου στο IPv6, απαιτεί την χειροκίνητη εισαγωγή κάποιων ρυθμίσεων. [[bsdinstall-net-ipv6-static]] .Στατική Ρύθμιση IPv6 image::bsdinstall-configure-network-interface-ipv6-static.png[] * `IPv6 Address` - Η διεύθυνση IP που θα εισάγετε χειροκίνητα σε αυτό τον υπολογιστή. Η διεύθυνση αυτή πρέπει να είναι μοναδική και να μην χρησιμοποιείται από κανένα άλλο μηχάνημα στο τοπικό σας δίκτυο. * `Default Router` - Η IPv6 διεύθυνση του προεπιλεγμένου δρομολογητή για το δίκτυο σας. Συνήθως είναι η διεύθυνση του δρομολογητή ή άλλου δικτυακού εξοπλισμού που συνδέει το τοπικό σας δίκτυο με το Internet. Θα τη δείτε επίσης να αναφέρεται ως _default gateway (προεπιλεγμένη πύλη)_. [[bsdinstall-net-dns]] ==== Ρύθμιση του DNS Το _Domain Name System (Σύστημα Ονομάτων Τομέα)_ ή _DNS_ μετατρέπει ονόματα υπολογιστών σε διευθύνσεις δικτύου και το αντίθετο. Αν χρησιμοποιήσατε DHCP ή SLAAC για να ρυθμίσετε αυτόματα τη διεπαφή δικτύου, οι αντίστοιχες ρυθμίσεις πιθανόν να έχουν γίνει ήδη. Στην αντίθετη περίπτωση, βάλτε το όνομα τομέα του τοπικού δικτύου στο πεδίο Search. Τα πεδία DNS #1 και DNS #2 είναι οι διευθύνσεις IP των τοπικών εξυπηρετητών DNS. Χρειάζεται να εισάγετε τουλάχιστον ένα εξυπηρετητή DNS. [[bsdinstall-net-dns-config]] .Ρύθμιση DNS image::bsdinstall-configure-network-ipv4-dns.png[] [[bsdinstall-timezone]] === Ρύθμιση της Ζώνης Ώρας Η ρύθμιση της σωστής ζώνης ώρας στο μηχάνημα σας, εξασφαλίζει την αυτόματη αλλαγή της από χειμερινή σε εαρινή και το αντίστροφο. Επιτρέπει επίσης τη σωστή λειτουργία όλων των υπηρεσιών που σχετίζονται με την τήρηση χρόνου. Το παράδειγμα μας αναφέρεται σε ένα μηχάνημα που βρίσκεται στην Ανατολική ζώνη ώρας των Ηνωμένων Πολιτειών. Η δική σας επιλογή θα είναι διαφορετική ανάλογα με τη γεωγραφική σας περιοχή. [[bsdinstall-local-utc]] .Επιλογή Τοπικού ή UTC Ρολογιού image::bsdinstall-set-clock-local-utc.png[] Επιλέξτε btn:[Yes] ή btn:[No] ανάλογα με το πως είναι ρυθμισμένο το ρολόι του μηχανήματος και πιέστε kbd:[Enter]. Αν δεν γνωρίζετε αν το σύστημα σας χρησιμοποιεί ώρα UTC ή τοπική, επιλέξτε btn:[No] για να επιλέξετε την τοπική ώρα που είναι και η πιο συνηθισμένη. [[bsdinstall-timezone-region]] .Επιλέξτε μια Περιοχή image::bsdinstall-timezone-region.png[] Επιλέξτε την σωστή περιοχή χρησιμοποιώντας τα βελάκια και πιέστε kbd:[Enter]. [[bsdinstall-timezone-country]] .Επιλογή Χώρας image::bsdinstall-timezone-country.png[] Επιλέξτε τη σωστή χώρα χρησιμοποιώντας τα βελάκια και πιέστε kbd:[Enter]. [[bsdinstall-timezone-zone]] .Επιλογή Ζώνης Ώρας image::bsdinstall-timezone-zone.png[] Επιλέξτε τη σωστή ζώνη ώρας χρησιμοποιώντας τα βελάκια και πιέστε kbd:[Enter]. [[bsdinstall-timezone-confirmation]] .Επιβεβαίωση Ζώνης Ώρας image::bsdinstall-timezone-confirm.png[] Επιβεβαιώστε ότι η συντομογραφία για την επιλεγμένη ζώνη ώρας είναι η σωστή. Έπειτα πιέστε kbd:[Enter] για να συνεχίσετε με τις υπόλοιπες ρυθμίσεις. [[bsdinstall-sysconf]] === Επιλογή Υπηρεσιών που θα Ενεργοποιηθούν Μπορείτε να επιλέξετε ποιες από τις πρόσθετες υπηρεσίες θα ενεργοποιηθούν στην εκκίνηση. Όλες οι παρακάτω υπηρεσίες είναι προαιρετικές. [[bsdinstall-config-serv]] .Επιλογή Πρόσθετων Υπηρεσιών προς Ενεργοποίηση image::bsdinstall-config-services.png[] .Πρόσθετες Υπηρεσίες * `sshd` - Secure Shell (Ασφαλές Κέλυφος) (SSH) Ο δαίμονας για ασφαλή απομακρυσμένη πρόσβαση. * `moused` - Παρέχει δυνατότητα χρήσης του ποντικιού από την κονσόλα του συστήματος. * `ntpd` - Network Time Protocol, πρωτόκολλο για ρύθμιση της ώρας μέσω δικτύου (NTP). Ο δαίμονας χρησιμοποιείται για την αυτόματη ρύθμιση του ρολογιού. * `powerd` - Βοηθητικό πρόγραμμα για έλεγχο ισχύος και διαχείριση ενέργειας. [[bsdinstall-crashdump]] === Ενεργοποίηση Crash Dumps Το bsdinstall θα σας ρωτήσει αν θέλετε να ενεργοποιήσετε τα crash dumps στο σύστημα σας. Η ενεργοποίηση των crash dumps μπορεί να είναι πολύ χρήσιμη στον εντοπισμό προβλημάτων του συστήματος και για το λόγο αυτό συνιστούμε να τα ενεργοποιείτε όταν είναι δυνατόν. Επιλέξτε btn:[Yes] για να τα ενεργοποιήσετε, ή btn:[No] για να συνεχίσετε χωρίς crash dumps. [[bsdinstall-config-crashdump]] .Ενεργοποίηση Crash Dumps image::bsdinstall-config-crashdump.png[] [[bsdinstall-addusers]] === Προσθήκη Χρηστών Η προσθήκη τουλάχιστον ενός χρήστη κατά την εγκατάσταση, σας επιτρέπει να χρησιμοποιήσετε το σύστημα χωρίς να εισέλθετε ως `root`. Όταν εισέρχεστε ως `root`, δεν υπάρχουν πρακτικά όρια ή κάποιο είδος προστασίας σχετικά με το τι μπορείτε να κάνετε. Όταν εισέρχεστε ως κανονικός χρήστης, μπορείτε να χειριστείτε το σύστημα σας με περισσότερη ασφάλεια. Επιλέξτε btn:[Yes] για να προσθέσετε νέους χρήστες. [[bsdinstall-add-user1]] .Προσθήκη Λογαριασμών Χρηστών image::bsdinstall-adduser1.png[] Εισάγετε τις πληροφορίες για το χρήστη που θα προστεθεί. [[bsdinstall-add-user2]] .Εισαγωγή Πληροφοριών Χρήστη image::bsdinstall-adduser2.png[] .Πληροφορίες Χρήστη * `Username` - Το όνομα που θα χρησιμοποιεί ο χρήστης για να εισέλθει στο σύστημα. Τυπικά το πρώτο γράμμα του μικρού ονόματος σε συνδυασμό με το επίθετο. * `Full name` - Το πλήρες όνομα του χρήστη. * `Uid` - User ID. Ο αναγνωριστικός αριθμός χρήστη. Συνήθως δεν συμπληρώνουμε αυτό το πεδίο, ώστε να επιλεγεί αυτόματα ένας αριθμός από το σύστημα. * `Login group` - Η ομάδα στην οποία ανήκει ο χρήστης. Συνήθως το αφήνουμε κενό ώστε να γίνει αποδεκτή η προεπιλεγμένη τιμή. * `Invite user into other groups?` - Επιπρόσθετες ομάδες χρηστών στις οποίες θέλουμε να ανήκει ο χρήστης. * `Login class` - Συνήθως δεν συμπληρώνουμε αυτό το πεδίο, ώστε να γίνει αποδεκτή η προεπιλεγμένη τιμή. * `Shell` - Το κέλυφος που θα χρησιμοποιεί ο συγκεκριμένος χρήστης. Στο παράδειγμα μας επιλέξαμε το man:csh[1]. * `Home directory` - Ο προσωπικός κατάλογος του χρήστη. Η προεπιλεγμένη τιμή είναι συνήθως η σωστή. * `Home directory permissions` - Τα δικαιώματα στον κατάλογο του χρήστη. Τα προεπιλεγμένα είναι συνήθως σωστά. * `Use password-based authentication?` - H τυπική απάντηση είναι "yes". * `Use an empty password?` - Η τυπική απάντηση είναι "no". * `Use a random password?` - Η τυπική απάντηση είναι "no". * `Enter password` - Ο κωδικός πρόσβασης για το συγκεκριμένο χρήστη. Δεν φαίνεται στην οθόνη καθώς τον πληκτρολογούμε. * `Enter password again` - Ο κωδικός πρέπει να εισαχθεί άλλη μια φορά για επιβεβαίωση. * `Lock out the account after creation?` - Η τυπική απάντηση είναι "no". Αφού εισάγετε όλες τις πληροφορίες, θα δείτε μια περίληψη τους και το σύστημα θα σας ρωτήσει για την ορθότητα τους. Αν κάνατε κάποιο λάθος κατά τη διάρκεια της εισαγωγής, γράψτε `no` και ξαναπροσπαθήστε. Αν όλα είναι σωστά, γράψτε `yes` για να δημιουργήσετε το νέο χρήστη. [[bsdinstall-add-user3]] .Έξοδος από τη Διαχείριση Χρηστών και Ομάδων image::bsdinstall-adduser3.png[] Αν θέλετε να προσθέσετε περισσότερους χρήστες, απαντήστε στην ερώτηση "Add another user?" με `yes`. Απαντήστε `no` για να τελειώσετε με την προσθήκη χρηστών και να συνεχίσετε την εγκατάσταση. Για περισσότερες πληροφορίες σχετικά με την προσθήκη και διαχείριση χρηστών, δείτε το crossref:users[users,Χρήστες και Βασική Διαχείριση Λογαριασμών]. [[bsdinstall-final-conf]] === Τελικές Ρυθμίσεις Μετά το τέλος της εγκατάστασης και των αρχικών ρυθμίσεων, έχετε μια τελευταία ευκαιρία να αλλάξετε τις ρυθμίσεις πριν την έξοδο από το πρόγραμμα εγκατάστασης. [[bsdinstall-final-config]] .Τελικές Ρυθμίσεις image::bsdinstall-finalconfiguration.png[] Χρησιμοποιήστε αυτό το μενού για να κάνετε οποιεσδήποτε αλλαγές ή πρόσθετες ρυθμίσεις θέλετε πριν την ολοκλήρωση της εγκατάστασης. .Επιλογές Τελικών Ρυθμίσεων * `Add User` - Περιγράφεται στο <>. * `Root Password` - Περιγράφεται στο <>. * `Hostname` - Περιγράφεται στο <>. * `Network` - Περιγράφεται στο <>. * `Services` - Περιγράφεται στο <>. * `Time Zone` - Περιγράφεται στο <>. * `Handbook` - Μεταφόρτωση και εγκατάσταση του Εγχειριδίου του FreeBSD (το οποίο διαβάζετε αυτή τη στιγμή). Με την ολοκλήρωση των τελικών ρυθμίσεων, επιλέξτε btn:[Exit] για να κλείσετε την εγκατάσταση. [[bsdinstall-final-modification-shell]] .Χειροκίνητη Ρύθμιση image::bsdinstall-final-modification-shell.png[] Το bsdinstall θα σας ρωτήσει για τυχόν επιπλέον ρυθμίσεις που πρέπει να γίνουν πριν επανεκκινήσετε στο νέο σύστημα. Επιλέξτε btn:[Yes] για να εκκινήσετε ένα κέλυφος στο νέο σύστημα ή btn:[No] για να προχωρήσετε στο τελευταίο βήμα της εγκατάστασης. [[bsdinstall-final-main]] .Ολοκλήρωση της Εγκατάστασης image::bsdinstall-mainexit.png[] Αν χρειάζεται να κάνετε περισσότερες ή ειδικές ρυθμίσεις, μπορείτε να επιλέξετε btn:[Live CD]. Με την επιλογή αυτή, Θα ξεκινήσετε το μέσο εγκατάστασης σε κατάσταση Live CD. Με την ολοκλήρωση της εγκατάστασης, επιλέξτε btn:[Reboot] για να επανεκκινήσετε τον υπολογιστή σας και να ξεκινήσετε το νέο FreeBSD σύστημά σας. Μη ξεχάσετε να αφαιρέσετε το μέσο εγκατάστασης από τον οδηγό CD (ή την USB υποδοχή), διαφορετικά το σύστημα σας ίσως ξεκινήσει ξανά από αυτό. [[bsdinstall-freebsdboot]] === Εκκίνηση και Τερματισμός του FreeBSD [[bsdinstall-freebsdboot-i386]] ==== Εκκίνηση στο FreeBSD/i386 Κατά την εκκίνηση του FreeBSD εμφανίζονται πολλά πληροφοριακά μηνύματα. Φυσιολογικά, τα περισσότερα κυλούν εκτός της οθόνης. Μετά το τέλος της εκκίνησης εμφανίζεται η προτροπή εισόδου στο σύστημα (login). Μπορείτε να δείτε τα μηνύματα που κύλησαν εκτός οθόνης πιέζοντας το πλήκτρο kbd:[Scroll-Lock] για να να ενεργοποιήσετε την _προσωρινή μνήμη κύλισης_. Χρησιμοποιήστε έπειτα τα πλήκτρα kbd:[PgUp], kbd:[PgDn] και τα βελάκια για να δείτε τα παλιά μηνύματα. Πιέζοντας το kbd:[Scroll-Lock] ξανά, θα επιστρέψετε στην κανονική απεικόνιση. Στην προτροπή `login:` γράψτε το όνομα που δημιουργήσατε κατά την εγκατάσταση, στο παράδειγμα μας `asample`. Να αποφεύγετε να εισέρχεστε ως `root` όταν δεν είναι απαραίτητο. Η δυνατότητα προς τα πίσω κύλισης των μηνυμάτων που περιγράψαμε προηγουμένως είναι περιορισμένη, επομένως δεν θα μπορέσετε με αυτό τον τρόπο να τα δείτε όλα. Μετά την είσοδο σας στο σύστημα, μπορείτε να δείτε τα μηνύματα από τη γραμμή εντολών γράφοντας `dmesg | less` στην προτροπή. Πιέστε kbd:[q] για να επιστρέψετε στη γραμμή εντολών όταν τελειώσετε. Τυπικά μηνύματα εκκίνησης (έχουν παραλειφθεί οι πληροφορίες έκδοσης): [source,shell] .... Copyright (c) 1992-2011 The FreeBSD Project. Copyright (c) 1979, 1980, 1983, 1986, 1988, 1989, 1991, 1992, 1993, 1994 The Regents of the University of California. All rights reserved. FreeBSD is a registered trademark of The FreeBSD Foundation. root@farrell.cse.buffalo.edu:/usr/obj/usr/src/sys/GENERIC amd64 CPU: Intel(R) Core(TM)2 Duo CPU E8400 @ 3.00GHz (3007.77-MHz K8-class CPU) Origin = "GenuineIntel" Id = 0x10676 Family = 6 Model = 17 Stepping = 6 Features=0x783fbff Features2=0x209 AMD Features=0x20100800 AMD Features2=0x1 real memory = 536805376 (511 MB) avail memory = 491819008 (469 MB) Event timer "LAPIC" quality 400 ACPI APIC Table: ioapic0: Changing APIC ID to 1 ioapic0 irqs 0-23 on motherboard kbd1 at kbdmux0 acpi0: on motherboard acpi0: Power Button (fixed) acpi0: Sleep Button (fixed) Timecounter "ACPI-fast" frequency 3579545 Hz quality 900 acpi_timer0: <32-bit timer at 3.579545MHz> port 0x4008-0x400b on acpi0 cpu0: on acpi0 pcib0: port 0xcf8-0xcff on acpi0 pci0: on pcib0 isab0: at device 1.0 on pci0 isa0: on isab0 atapci0: port 0x1f0-0x1f7,0x3f6,0x170-0x177,0x376,0xd000-0xd00f at device 1.1 on pci0 ata0: on atapci0 ata1: on atapci0 vgapci0: mem 0xe0000000-0xe0ffffff irq 18 at device 2.0 on pci0 em0: port 0xd010-0xd017 mem 0xf0000000-0xf001ffff irq 19 at device 3.0 on pci0 em0: Ethernet address: 08:00:27:9f:e0:92 pci0: at device 4.0 (no driver attached) pcm0: port 0xd100-0xd1ff,0xd200-0xd23f irq 21 at device 5.0 on pci0 pcm0: ohci0: mem 0xf0804000-0xf0804fff irq 22 at device 6.0 on pci0 usbus0: on ohci0 pci0: at device 7.0 (no driver attached) acpi_acad0: on acpi0 atkbdc0: port 0x60,0x64 irq 1 on acpi0 atkbd0: irq 1 on atkbdc0 kbd0 at atkbd0 atkbd0: [GIANT-LOCKED] psm0: irq 12 on atkbdc0 psm0: [GIANT-LOCKED] psm0: model IntelliMouse Explorer, device ID 4 attimer0: port 0x40-0x43,0x50-0x53 on acpi0 Timecounter "i8254" frequency 1193182 Hz quality 0 Event timer "i8254" frequency 1193182 Hz quality 100 sc0: at flags 0x100 on isa0 sc0: VGA <16 virtual consoles, flags=0x300> vga0: at port 0x3c0-0x3df iomem 0xa0000-0xbffff on isa0 atrtc0: at port 0x70 irq 8 on isa0 Event timer "RTC" frequency 32768 Hz quality 0 ppc0: cannot reserve I/O port range Timecounters tick every 10.000 msec pcm0: measured ac97 link rate at 485193 Hz em0: link state changed to UP usbus0: 12Mbps Full Speed USB v1.0 ugen0.1: at usbus0 uhub0: on usbus0 cd0 at ata1 bus 0 scbus1 target 0 lun 0 cd0: Removable CD-ROM SCSI-0 device cd0: 33.300MB/s transfers (UDMA2, ATAPI 12bytes, PIO 65534bytes) cd0: Attempt to query device size failed: NOT READY, Medium not present ada0 at ata0 bus 0 scbus0 target 0 lun 0 ada0: ATA-6 device ada0: 33.300MB/s transfers (UDMA2, PIO 65536bytes) ada0: 12546MB (25694208 512 byte sectors: 16H 63S/T 16383C) ada0: Previously was known as ad0 Timecounter "TSC" frequency 3007772192 Hz quality 800 Root mount waiting for: usbus0 uhub0: 8 ports with 8 removable, self powered Trying to mount root from ufs:/dev/ada0p2 [rw]... Setting hostuuid: 1848d7bf-e6a4-4ed4-b782-bd3f1685d551. Setting hostid: 0xa03479b2. Entropy harvesting: interrupts ethernet point_to_point kickstart. Starting file system checks: /dev/ada0p2: FILE SYSTEM CLEAN; SKIPPING CHECKS /dev/ada0p2: clean, 2620402 free (714 frags, 327461 blocks, 0.0% fragmentation) Mounting local file systems:. vboxguest0 port 0xd020-0xd03f mem 0xf0400000-0xf07fffff,0xf0800000-0xf0803fff irq 20 at device 4.0 on pci0 vboxguest: loaded successfully Setting hostname: machine3.example.com. Starting Network: lo0 em0. lo0: flags=8049 metric 0 mtu 16384 options=3 inet6 ::1 prefixlen 128 inet6 fe80::1%lo0 prefixlen 64 scopeid 0x3 inet 127.0.0.1 netmask 0xff000000 nd6 options=21 em0: flags=8843 metric 0 mtu 1500 options=9b ether 08:00:27:9f:e0:92 nd6 options=29 media: Ethernet autoselect (1000baseT ) status: active Starting devd. Starting Network: usbus0. DHCPREQUEST on em0 to 255.255.255.255 port 67 DHCPACK from 10.0.2.2 bound to 192.168.1.142 -- renewal in 43200 seconds. add net ::ffff:0.0.0.0: gateway ::1 add net ::0.0.0.0: gateway ::1 add net fe80::: gateway ::1 add net ff02::: gateway ::1 ELF ldconfig path: /lib /usr/lib /usr/lib/compat /usr/local/lib 32-bit compatibility ldconfig path: /usr/lib32 Creating and/or trimming log files. Starting syslogd. No core dumps found. Clearing /tmp (X related). Updating motd:. Configuring syscons: blanktime. Generating public/private rsa1 key pair. Your identification has been saved in /etc/ssh/ssh_host_key. Your public key has been saved in /etc/ssh/ssh_host_key.pub. The key fingerprint is: 10:a0:f5:af:93:ae:a3:1a:b2:bb:3c:35:d9:5a:b3:f3 root@machine3.example.com The key's randomart image is: +--[RSA1 1024]----+ | o.. | | o . . | | . o | | o | | o S | | + + o | |o . + * | |o+ ..+ . | |==o..o+E | +-----------------+ Generating public/private dsa key pair. Your identification has been saved in /etc/ssh/ssh_host_dsa_key. Your public key has been saved in /etc/ssh/ssh_host_dsa_key.pub. The key fingerprint is: 7e:1c:ce:dc:8a:3a:18:13:5b:34:b5:cf:d9:d1:47:b2 root@machine3.example.com The key's randomart image is: +--[ DSA 1024]----+ | .. . .| | o . . + | | . .. . E .| | . . o o . . | | + S = . | | + . = o | | + . * . | | . . o . | | .o. . | +-----------------+ Starting sshd. Starting cron. Starting background file system checks in 60 seconds. Thu Oct 6 19:15:31 MDT 2011 FreeBSD/amd64 (machine3.example.com) (ttyv0) login: .... Η δημιουργία των κλειδιών RSA και DSA μπορεί να πάρει κάποιο χρόνο σε αργά μηχανήματα. Γίνεται όμως μόνο στην πρώτη εκκίνηση και μόνο αν έχει ρυθμιστεί το sshd για αυτόματη εκκίνηση. Οι επόμενες εκκινήσεις θα είναι ταχύτερες. Το FreeBSD δεν εγκαθιστά κάποιο γραφικό περιβάλλον από προεπιλογή, αλλά υπάρχουν αρκετά διαθέσιμα προς εγκατάσταση. Δείτε το crossref:x11[x11,Το Σύστημα X Window] για περισσότερες πληροφορίες. [[bsdinstall-shutdown]] === Τερματισμός του FreeBSD Ο σωστός τερματισμός του FreeBSD εξασφαλίζει τα δεδομένα και το υλικό του υπολογιστή σας από ζημιά. Δεν πρέπει απλώς να διακόψετε την τροφοδοσία. Αν ο χρήστης σας είναι μέλος της ομάδας `wheel`, μπορείτε να γίνετε υπερχρήστης με την εντολή `su` και την εισαγωγή του κωδικού του `root`. Διαφορετικά, συνδεθείτε ως `root` και χρησιμοποιήστε την εντολή `shutdown -p now`. Το σύστημα θα τερματίσει με το σωστό τρόπο και θα διακοπεί και η παροχή ρεύματος. Μπορείτε να χρησιμοποιήσετε το συνδυασμό πλήκτρων kbd:[Ctrl+Alt+Del] για να επανεκκινήσετε το σύστημα, αλλά αυτό δεν συνίσταται κατά τη διάρκεια της κανονικής λειτουργίας. [[bsdinstall-install-trouble]] == Αντιμετώπιση Προβλημάτων Η ενότητα που ακολουθεί καλύπτει την αντιμετώπιση βασικών προβλημάτων εγκατάστασης - για παράδειγμα κοινά προβλήματα που έχουν αναφερθεί από πολλούς χρήστες. Υπάρχουν επίσης κάποιες ερωτήσεις και απαντήσεις για όσους επιθυμούν να έχουν το FreeBSD ως dual boot με MS-DOS(R) ή Windows(R). === Τι να Κάνετε αν Κάτι Πάει Στραβά Λόγω των διάφορων περιορισμών στην αρχιτεκτονική του PC, δεν είναι δυνατόν η ανίχνευση συσκευών να είναι 100% αξιόπιστη. Υπάρχουν όμως κάποια πράγματα που μπορείτε να κάνετε αν η ανίχνευση δεν είναι επιτυχής. Ελέγξτε τις http://www.FreeBSD.org/releases/[Σημειώσεις Υλικού] για την έκδοση του FreeBSD που χρησιμοποιείτε, για να βεβαιωθείτε ότι το υλικό σας υποστηρίζεται. Αν το υλικό σας υποστηρίζεται και εξακολουθείτε να έχετε κολλήματα ή άλλα προβλήματα, θα πρέπει να δημιουργήσετε ένα crossref:kernelconfig[kernelconfig,προσαρμοσμένο πυρήνα]. Αυτό θα σας επιτρέψει να προσθέσετε υποστήριξη για συσκευές οι οποίες δεν υπάρχουν στον πυρήνα [.filename]#GENERIC#. Ο πυρήνας στο μέσο εγκατάστασης έχει δημιουργηθεί με την υπόθεση ότι οι περισσότερες συσκευές βρίσκονται στις προεπιλεγμένες ρυθμίσεις τους όσο αφορά τα IRQs, τις διευθύνσεις IO και τα κανάλια DMA. Αν έχετε αλλάξει αυτές τις ρυθμίσεις ίσως χρειαστεί να αλλάξετε τις ρυθμίσεις του πυρήνα και να τον επαναμεταγλωττίσετε για να μπορέσει το FreeBSD να εντοπίσει τις συσκευές σας. Είναι επίσης πιθανό η διαδικασία ανίχνευσης για μια συσκευή που δεν είναι εγκατεστημένη να προκαλέσει πρόβλημα στην ανίχνευση μιας άλλης υπαρκτής συσκευής. Στην περίπτωση αυτή, θα πρέπει να αφαιρέσετε την ανίχνευση για τη συσκευή που δημιουργεί το πρόβλημα. [NOTE] ==== Κάποια προβλήματα εγκατάστασης μπορούν να αποφευχθούν ή να μειωθούν με την αναβάθμιση firmware διάφορων συσκευών υλικού και ειδικότερα της μητρικής. Το firmware της μητρικής είναι συχνά γνωστό με τον όρο BIOS. Οι περισσότεροι κατασκευαστές μητρικών διαθέτουν μια δικτυακή τοποθεσία από όπου μπορείτε να κατεβάσετε αναβαθμισμένες εκδόσεις και ανάλογες πληροφορίες. Οι κατασκευαστές συνήθως συνιστούν να μην αναβαθμίζετε το BIOS της μητρικής αν δεν υπάρχει καλός λόγος, όπως για παράδειγμα μια κρίσιμη ενημέρωση. Η ενημέρωση _ενδέχεται να αποτύχει_ αφήνοντας το BIOS σε μια ενδιάμεση κατάσταση και τον υπολογιστή εκτός λειτουργίας. ==== === Ερωτήσεις και Απαντήσεις στην Αντιμετώπιση Προβλημάτων === Το σύστημα μου σταματά να ανταποκρίνεται κατά την ανίχνευση συσκευών στην εκκίνηση ή συμπεριφέρεται περίεργα κατά την εγκατάσταση. Το FreeBSD κάνει εκτεταμένη χρήση των υπηρεσιών ACPI (εφόσον υπάρχει) στις αρχιτεκτονικές i386, amd64 και ia64 ώστε να ρυθμίσει σωστά τις συσκευές κατά την εκκίνηση. Δυστυχώς υπάρχουν ακόμα κάποια προβλήματα τόσο στο ACPI όσο και στο BIOS firmware αρκετών μητρικών. Μπορείτε να απενεργοποιήσετε το ACPI θέτοντας `hint.acpi.0.disabled` στο τρίτο στάδιο του φορτωτή εκκίνησης: [source,shell] .... set hint.acpi.0.disabled="1" .... Καθώς η ρύθμιση αυτή χάνεται σε κάθε εκκίνηση, είναι απαραίτητο να προσθέσετε την οδηγία `hint.acpi.0.disabled="1"` στο αρχείο [.filename]#/boot/loader.conf#. Μπορείτε να βρείτε περισσότερες πληροφορίες για το φορτωτή εκκίνησης στο crossref:boot[boot-synopsis,Σύνοψη]. [[using-live-cd]] == Χρησιμοποιώντας τη Λειτουργία Live CD Η λειτουργία live CD του FreeBSD διατίθεται στο ίδιο CD με το βασικό πρόγραμμα εγκατάστασης. Είναι χρήσιμη για όσους ακόμα αναρρωτιούνται αν το FreeBSD είναι το κατάλληλο λειτουργικό για αυτούς και θέλουν να δοκιμάσουν κάποια από τα χαρακτηριστικά του πριν το εγκαταστήσουν. [NOTE] ==== Κατά τη χρήση του live CD να έχετε υπόψη σας τα παρακάτω: * Για να αποκτήσετε πρόσβαση στο σύστημα θα πρέπει να περάσετε από διαδικασία εισόδου. Το όνομα χρήστη είναι `root` και ο κωδικός είναι κενός. * Καθώς το σύστημα εκτελείται απευθείας από το CD, η απόδοση του θα είναι σημαντικά χαμηλότερη σε σχέση με ένα σύστημα εγκατεστημένο σε σκληρό δίσκο. * Το live CD παρέχει μόνο γραμμή εντολών και όχι γραφικό περιβάλλον. ==== diff --git a/documentation/content/en/books/arch-handbook/mac/_index.adoc b/documentation/content/en/books/arch-handbook/mac/_index.adoc index 1724ba0553..24885e2cf7 100644 --- a/documentation/content/en/books/arch-handbook/mac/_index.adoc +++ b/documentation/content/en/books/arch-handbook/mac/_index.adoc @@ -1,5398 +1,5397 @@ --- title: Chapter 6. The TrustedBSD MAC Framework authors: - author: Chris Costello email: chris@FreeBSD.org - author: Robert Watson email: rwatson@FreeBSD.org prev: books/arch-handbook/sysinit next: books/arch-handbook/vm description: The TrustedBSD MAC Framework tags: ["TrustedBSD", "MAC"] showBookMenu: true weight: 7 path: "/books/arch-handbook/mac/" --- [[mac]] = The TrustedBSD MAC Framework :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 6 :partnums: :source-highlighter: rouge :experimental: :images-path: books/arch-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::[] [[mac-copyright]] == MAC Documentation Copyright This documentation was developed for the FreeBSD Project by Chris Costello at Safeport Network Services and Network Associates Laboratories, the Security Research Division of Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the DARPA CHATS research program. Redistribution and use in source (SGML DocBook) and 'compiled' forms (SGML, HTML, PDF, PostScript, RTF and so forth) with or without modification, are permitted provided that the following conditions are met: . Redistributions of source code (SGML DocBook) must retain the above copyright notice, this list of conditions and the following disclaimer as the first lines of this file unmodified. . Redistributions in compiled form (transformed to other DTDs, converted to PDF, PostScript, RTF and other formats) must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. [IMPORTANT] ==== THIS DOCUMENTATION IS PROVIDED BY THE NETWORKS ASSOCIATES TECHNOLOGY, INC "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL NETWORKS ASSOCIATES TECHNOLOGY, INC BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ==== [[mac-synopsis]] == Synopsis FreeBSD includes experimental support for several mandatory access control policies, as well as a framework for kernel security extensibility, the TrustedBSD MAC Framework. The MAC Framework is a pluggable access control framework, permitting new security policies to be easily linked into the kernel, loaded at boot, or loaded dynamically at run-time. The framework provides a variety of features to make it easier to implement new security policies, including the ability to easily tag security labels (such as confidentiality information) onto system objects. This chapter introduces the MAC policy framework and provides documentation for a sample MAC policy module. [[mac-introduction]] == Introduction The TrustedBSD MAC framework provides a mechanism to allow the compile-time or run-time extension of the kernel access control model. New system policies may be implemented as kernel modules and linked to the kernel; if multiple policy modules are present, their results will be composed. The MAC Framework provides a variety of access control infrastructure services to assist policy writers, including support for transient and persistent policy-agnostic object security labels. This support is currently considered experimental. This chapter provides information appropriate for developers of policy modules, as well as potential consumers of MAC-enabled environments, to learn about how the MAC Framework supports access control extension of the kernel. [[mac-background]] == Policy Background Mandatory Access Control (MAC), refers to a set of access control policies that are mandatorily enforced on users by the operating system. MAC policies may be contrasted with Discretionary Access Control (DAC) protections, by which non-administrative users may (at their discretion) protect objects. In traditional UNIX systems, DAC protections include file permissions and access control lists; MAC protections include process controls preventing inter-user debugging and firewalls. A variety of MAC policies have been formulated by operating system designers and security researches, including the Multi-Level Security (MLS) confidentiality policy, the Biba integrity policy, Role-Based Access Control (RBAC), Domain and Type Enforcement (DTE), and Type Enforcement (TE). Each model bases decisions on a variety of factors, including user identity, role, and security clearance, as well as security labels on objects representing concepts such as data sensitivity and integrity. The TrustedBSD MAC Framework is capable of supporting policy modules that implement all of these policies, as well as a broad class of system hardening policies, which may use existing security attributes, such as user and group IDs, as well as extended attributes on files, and other system properties. In addition, despite the name, the MAC Framework can also be used to implement purely discretionary policies, as policy modules are given substantial flexibility in how they authorize protections. [[mac-framework-kernel-arch]] == MAC Framework Kernel Architecture The TrustedBSD MAC Framework permits kernel modules to extend the operating system security policy, as well as providing infrastructure functionality required by many access control modules. If multiple policies are simultaneously loaded, the MAC Framework will usefully (for some definition of useful) compose the results of the policies. [[mac-framework-kernel-arch-elements]] === Kernel Elements The MAC Framework contains a number of kernel elements: * Framework management interfaces * Concurrency and synchronization primitives. * Policy registration * Extensible security label for kernel objects * Policy entry point composition operators * Label management primitives * Entry point API invoked by kernel services * Entry point API to policy modules * Entry points implementations (policy life cycle, object life cycle/label management, access control checks). * Policy-agnostic label-management system calls * `mac_syscall()` multiplex system call * Various security policies implemented as MAC policy modules [[mac-framework-kernel-arch-management]] === Framework Management Interfaces The TrustedBSD MAC Framework may be directly managed using sysctl's, loader tunables, and system calls. In most cases, sysctl's and loader tunables of the same name modify the same parameters, and control behavior such as enforcement of protections relating to various kernel subsystems. In addition, if MAC debugging support is compiled into the kernel, several counters will be maintained tracking label allocation. It is generally advisable that per-subsystem enforcement controls not be used to control policy behavior in production environments, as they broadly impact the operation of all active policies. Instead, per-policy controls should be preferred, as they provide greater granularity and greater operational consistency for policy modules. Loading and unloading of policy modules is performed using the system module management system calls and other system interfaces, including boot loader variables; policy modules will have the opportunity to influence load and unload events, including preventing undesired unloading of the policy. [[mac-framework-kernel-arch-synchronization]] === Policy List Concurrency and Synchronization As the set of active policies may change at run-time, and the invocation of entry points is non-atomic, synchronization is required to prevent loading or unloading of policies while an entry point invocation is in progress, freezing the set of active policies for the duration. This is accomplished by means of a framework busy count: whenever an entry point is entered, the busy count is incremented; whenever it is exited, the busy count is decremented. While the busy count is elevated, policy list changes are not permitted, and threads attempting to modify the policy list will sleep until the list is not busy. The busy count is protected by a mutex, and a condition variable is used to wake up sleepers waiting on policy list modifications. One side effect of this synchronization model is that recursion into the MAC Framework from within a policy module is permitted, although not generally used. Various optimizations are used to reduce the overhead of the busy count, including avoiding the full cost of incrementing and decrementing if the list is empty or contains only static entries (policies that are loaded before the system starts, and cannot be unloaded). A compile-time option is also provided which prevents any change in the set of loaded policies at run-time, which eliminates the mutex locking costs associated with supporting dynamically loaded and unloaded policies as synchronization is no longer required. As the MAC Framework is not permitted to block in some entry points, a normal sleep lock cannot be used; as a result, it is possible for the load or unload attempt to block for a substantial period of time waiting for the framework to become idle. [[mac-framework-kernel-arch-label-synchronization]] === Label Synchronization As kernel objects of interest may generally be accessed from more than one thread at a time, and simultaneous entry of more than one thread into the MAC Framework is permitted, security attribute storage maintained by the MAC Framework is carefully synchronized. In general, existing kernel synchronization on kernel object data is used to protect MAC Framework security labels on the object: for example, MAC labels on sockets are protected using the existing socket mutex. Likewise, semantics for concurrent access are generally identical to those of the container objects: for credentials, copy-on-write semantics are maintained for label contents as with the remainder of the credential structure. The MAC Framework asserts necessary locks on objects when invoked with an object reference. Policy authors must be aware of these synchronization semantics, as they will sometimes limit the types of accesses permitted on labels: for example, when a read-only reference to a credential is passed to a policy via an entry point, only read operations are permitted on the label state attached to the credential. [[mac-framework-kernel-arch-policy-synchronization]] === Policy Synchronization and Concurrency Policy modules must be written to assume that many kernel threads may simultaneously enter one more policy entry points due to the parallel and preemptive nature of the FreeBSD kernel. If the policy module makes use of mutable state, this may require the use of synchronization primitives within the policy to prevent inconsistent views on that state resulting in incorrect operation of the policy. Policies will generally be able to make use of existing FreeBSD synchronization primitives for this purpose, including mutexes, sleep locks, condition variables, and counting semaphores. However, policies should be written to employ these primitives carefully, respecting existing kernel lock orders, and recognizing that some entry points are not permitted to sleep, limiting the use of primitives in those entry points to mutexes and wakeup operations. When policy modules call out to other kernel subsystems, they will generally need to release any in-policy locks in order to avoid violating the kernel lock order or risking lock recursion. This will maintain policy locks as leaf locks in the global lock order, helping to avoid deadlock. [[mac-framework-kernel-arch-registration]] === Policy Registration The MAC Framework maintains two lists of active policies: a static list, and a dynamic list. The lists differ only with regards to their locking semantics: an elevated reference count is not required to make use of the static list. When kernel modules containing MAC Framework policies are loaded, the policy module will use `SYSINIT` to invoke a registration function; when a policy module is unloaded, `SYSINIT` will likewise invoke a de-registration function. Registration may fail if a policy module is loaded more than once, if insufficient resources are available for the registration (for example, the policy might require labeling and insufficient labeling state might be available), or other policy prerequisites might not be met (some policies may only be loaded prior to boot). Likewise, de-registration may fail if a policy is flagged as not unloadable. [[mac-framework-kernel-arch-entrypoints]] === Entry Points Kernel services interact with the MAC Framework in two ways: they invoke a series of APIs to notify the framework of relevant events, and they provide a policy-agnostic label structure pointer in security-relevant objects. The label pointer is maintained by the MAC Framework via label management entry points, and permits the Framework to offer a labeling service to policy modules through relatively non-invasive changes to the kernel subsystem maintaining the object. For example, label pointers have been added to processes, process credentials, sockets, pipes, vnodes, Mbufs, network interfaces, IP reassembly queues, and a variety of other security-relevant structures. Kernel services also invoke the MAC Framework when they perform important security decisions, permitting policy modules to augment those decisions based on their own criteria (possibly including data stored in security labels). Most of these security critical decisions will be explicit access control checks; however, some affect more general decision functions such as packet matching for sockets and label transition at program execution. [[mac-framework-kernel-arch-composition]] === Policy Composition When more than one policy module is loaded into the kernel at a time, the results of the policy modules will be composed by the framework using a composition operator. This operator is currently hard-coded, and requires that all active policies must approve a request for it to return success. As policies may return a variety of error conditions (success, access denied, object does not exist, ...), a precedence operator selects the resulting error from the set of errors returned by policies. In general, errors indicating that an object does not exist will be preferred to errors indicating that access to an object is denied. While it is not guaranteed that the resulting composition will be useful or secure, we have found that it is for many useful selections of policies. For example, traditional trusted systems often ship with two or more policies using a similar composition. [[mac-framework-kernel-arch-labels]] === Labeling Support As many interesting access control extensions rely on security labels on objects, the MAC Framework provides a set of policy-agnostic label management system calls covering a variety of user-exposed objects. Common label types include partition identifiers, sensitivity labels, integrity labels, compartments, domains, roles, and types. By policy agnostic, we mean that policy modules are able to completely define the semantics of meta-data associated with an object. Policy modules participate in the internalization and externalization of string-based labels provides by user applications, and can expose multiple label elements to applications if desired. In-memory labels are stored in slab-allocated `struct label`, which consists of a fixed-length array of unions, each holding a `void *` pointer and a `long`. Policies registering for label storage will be assigned a "slot" identifier, which may be used to dereference the label storage. The semantics of the storage are left entirely up to the policy module: modules are provided with a variety of entry points associated with the kernel object life cycle, including initialization, association/creation, and destruction. Using these interfaces, it is possible to implement reference counting and other storage models. Direct access to the object structure is generally not required by policy modules to retrieve a label, as the MAC Framework generally passes both a pointer to the object and a direct pointer to the object's label into entry points. The primary exception to this rule is the process credential, which must be manually dereferenced to access the credential label. This may change in future revisions of the MAC Framework. Initialization entry points frequently include a sleeping disposition flag indicating whether or not an initialization is permitted to sleep; if sleeping is not permitted, a failure may be returned to cancel allocation of the label (and hence object). This may occur, for example, in the network stack during interrupt handling, where sleeping is not permitted, or while the caller holds a mutex. Due to the performance cost of maintaining labels on in-flight network packets (Mbufs), policies must specifically declare a requirement that Mbuf labels be allocated. Dynamically loaded policies making use of labels must be able to handle the case where their init function has not been called on an object, as objects may already exist when the policy is loaded. The MAC Framework guarantees that uninitialized label slots will hold a 0 or NULL value, which policies may use to detect uninitialized values. However, as allocation of Mbuf labels is conditional, policies must also be able to handle a NULL label pointer for Mbufs if they have been loaded dynamically. In the case of file system labels, special support is provided for the persistent storage of security labels in extended attributes. Where available, extended attribute transactions are used to permit consistent compound updates of security labels on vnodes--currently this support is present only in the UFS2 file system. Policy authors may choose to implement multilabel file system object labels using one (or more) extended attributes. For efficiency reasons, the vnode label (`v_label`) is a cache of any on-disk label; policies are able to load values into the cache when the vnode is instantiated, and update the cache as needed. As a result, the extended attribute need not be directly accessed with every access control check. [NOTE] ==== Currently, if a labeled policy permits dynamic unloading, its state slot cannot be reclaimed, which places a strict (and relatively low) bound on the number of unload-reload operations for labeled policies. ==== [[mac-framework-kernel-arch-syscalls]] === System Calls The MAC Framework implements a number of system calls: most of these calls support the policy-agnostic label retrieval and manipulation APIs exposed to user applications. The label management calls accept a label description structure, `struct mac`, which contains a series of MAC label elements. Each element contains a character string name, and character string value. Each policy will be given the chance to claim a particular element name, permitting policies to expose multiple independent elements if desired. Policy modules perform the internalization and externalization between kernel labels and user-provided labels via entry points, permitting a variety of semantics. Label management system calls are generally wrapped by user library functions to perform memory allocation and error handling, simplifying user applications that must manage labels. The following MAC-related system calls are present in the FreeBSD kernel: * `mac_get_proc()` may be used to retrieve the label of the current process. * `mac_set_proc()` may be used to request a change in the label of the current process. * `mac_get_fd()` may be used to retrieve the label of an object (file, socket, pipe, ...) referenced by a file descriptor. * `mac_get_file()` may be used to retrieve the label of an object referenced by a file system path. * `mac_set_fd()` may be used to request a change in the label of an object (file, socket, pipe, ...) referenced by a file descriptor. * `mac_set_file()` may be used to request a change in the label of an object referenced by a file system path. * `mac_syscall()` permits policy modules to create new system calls without modifying the system call table; it accepts a target policy name, operation number, and opaque argument for use by the policy. * `mac_get_pid()` may be used to request the label of another process by process id. * `mac_get_link()` is identical to `mac_get_file()`, only it will not follow a symbolic link if it is the final entry in the path, so may be used to retrieve the label on a symlink. * `mac_set_link()` is identical to `mac_set_file()`, only it will not follow a symbolic link if it is the final entry in a path, so may be used to manipulate the label on a symlink. * `mac_execve()` is identical to the `execve()` system call, only it also accepts a requested label to set the process label to when beginning execution of a new program. This change in label on execution is referred to as a "transition". * `mac_get_peer()`, actually implemented via a socket option, retrieves the label of a remote peer on a socket, if available. In addition to these system calls, the `SIOCSIGMAC` and `SIOCSIFMAC` network interface ioctls permit the labels on network interfaces to be retrieved and set. [[mac-policy-architecture]] == MAC Policy Architecture Security policies are either linked directly into the kernel, or compiled into loadable kernel modules that may be loaded at boot, or dynamically using the module loading system calls at runtime. Policy modules interact with the system through a set of declared entry points, providing access to a stream of system events and permitting the policy to influence access control decisions. Each policy contains a number of elements: * Optional configuration parameters for policy. * Centralized implementation of the policy logic and parameters. * Optional implementation of policy life cycle events, such as initialization and destruction. * Optional support for initializing, maintaining, and destroying labels on selected kernel objects. * Optional support for user process inspection and modification of labels on selected objects. * Implementation of selected access control entry points that are of interest to the policy. * Declaration of policy identity, module entry points, and policy properties. [[mac-policy-declaration]] === Policy Declaration Modules may be declared using the `MAC_POLICY_SET()` macro, which names the policy, provides a reference to the MAC entry point vector, provides load-time flags determining how the policy framework should handle the policy, and optionally requests the allocation of label state by the framework. [.programlisting] .... static struct mac_policy_ops mac_policy_ops = { .mpo_destroy = mac_policy_destroy, .mpo_init = mac_policy_init, .mpo_init_bpfdesc_label = mac_policy_init_bpfdesc_label, .mpo_init_cred_label = mac_policy_init_label, /* ... */ .mpo_check_vnode_setutimes = mac_policy_check_vnode_setutimes, .mpo_check_vnode_stat = mac_policy_check_vnode_stat, .mpo_check_vnode_write = mac_policy_check_vnode_write, }; .... The MAC policy entry point vector, `mac__policy__ops` in this example, associates functions defined in the module with specific entry points. A complete listing of available entry points and their prototypes may be found in the MAC entry point reference section. Of specific interest during module registration are the .mpo_destroy and .mpo_init entry points. .mpo_init will be invoked once a policy is successfully registered with the module framework but prior to any other entry points becoming active. This permits the policy to perform any policy-specific allocation and initialization, such as initialization of any data or locks. .mpo_destroy will be invoked when a policy module is unloaded to permit releasing of any allocated memory and destruction of locks. Currently, these two entry points are invoked with the MAC policy list mutex held to prevent any other entry points from being invoked: this will be changed, but in the mean time, policies should be careful about what kernel primitives they invoke so as to avoid lock ordering or sleeping problems. The policy declaration's module name field exists so that the module may be uniquely identified for the purposes of module dependencies. An appropriate string should be selected. The full string name of the policy is displayed to the user via the kernel log during load and unload events, and also exported when providing status information to userland processes. [[mac-policy-flags]] === Policy Flags The policy declaration flags field permits the module to provide the framework with information about its capabilities at the time the module is loaded. Currently, three flags are defined: MPC_LOADTIME_FLAG_UNLOADOK:: This flag indicates that the policy module may be unloaded. If this flag is not provided, then the policy framework will reject requests to unload the module. This flag might be used by modules that allocate label state and are unable to free that state at runtime. MPC_LOADTIME_FLAG_NOTLATE:: This flag indicates that the policy module must be loaded and initialized early in the boot process. If the flag is specified, attempts to register the module following boot will be rejected. The flag may be used by policies that require pervasive labeling of all system objects, and cannot handle objects that have not been properly initialized by the policy. MPC_LOADTIME_FLAG_LABELMBUFS:: This flag indicates that the policy module requires labeling of Mbufs, and that memory should always be allocated for the storage of Mbuf labels. By default, the MAC Framework will not allocate label storage for Mbufs unless at least one loaded policy has this flag set. This measurably improves network performance when policies do not require Mbuf labeling. A kernel option, `MAC_ALWAYS_LABEL_MBUF`, exists to force the MAC Framework to allocate Mbuf label storage regardless of the setting of this flag, and may be useful in some environments. [NOTE] ==== Policies using the `MPC_LOADTIME_FLAG_LABELMBUFS` without the `MPC_LOADTIME_FLAG_NOTLATE` flag set must be able to correctly handle `NULL` Mbuf label pointers passed into entry points. This is necessary as in-flight Mbufs without label storage may persist after a policy enabling Mbuf labeling has been loaded. If a policy is loaded before the network subsystem is active (i.e., the policy is not being loaded late), then all Mbufs are guaranteed to have label storage. ==== [[mac-policy-entry-points]] === Policy Entry Points Four classes of entry points are offered to policies registered with the framework: entry points associated with the registration and management of policies, entry points denoting initialization, creation, destruction, and other life cycle events for kernel objects, events associated with access control decisions that the policy module may influence, and calls associated with the management of labels on objects. In addition, a `mac_syscall()` entry point is provided so that policies may extend the kernel interface without registering new system calls. Policy module writers should be aware of the kernel locking strategy, as well as what object locks are available during which entry points. Writers should attempt to avoid deadlock scenarios by avoiding grabbing non-leaf locks inside of entry points, and also follow the locking protocol for object access and modification. In particular, writers should be aware that while necessary locks to access objects and their labels are generally held, sufficient locks to modify an object or its label may not be present for all entry points. Locking information for arguments is documented in the MAC framework entry point document. Policy entry points will pass a reference to the object label along with the object itself. This permits labeled policies to be unaware of the internals of the object yet still make decisions based on the label. The exception to this is the process credential, which is assumed to be understood by policies as a first class security object in the kernel. [[mac-entry-point-reference]] == MAC Policy Entry Point Reference [[mac-mpo-general]] === General-Purpose Module Entry Points [[mac-mpo-init]] ==== `mpo_init` [source,c] ---- void mpo_init(struct mac_policy_conf *conf); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`conf` |MAC policy definition | |=== Policy load event. The policy list mutex is held, so sleep operations cannot be performed, and calls out to other kernel subsystems must be made with caution. If potentially sleeping memory allocations are required during policy initialization, they should be made using a separate module SYSINIT(). [[mpo-destroy]] ==== `mpo_destroy` [source,c] ---- void mpo_destroy(struct mac_policy_conf *conf); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`conf` |MAC policy definition | |=== Policy load event. The policy list mutex is held, so caution should be applied. [[mac-mpo-syscall]] ==== `mpo_syscall` [source,c] ---- int mpo_syscall(struct thread *td, int call, void *arg); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`td` |Calling thread | |`call` |Policy-specific syscall number | |`arg` |Pointer to syscall arguments | |=== This entry point provides a policy-multiplexed system call so that policies may provide additional services to user processes without registering specific system calls. The policy name provided during registration is used to demultiplexer calls from userland, and the arguments will be forwarded to this entry point. When implementing new services, security modules should be sure to invoke appropriate access control checks from the MAC framework as needed. For example, if a policy implements an augmented signal functionality, it should call the necessary signal access control checks to invoke the MAC framework and other registered policies. [NOTE] ==== Modules must currently perform the `copyin()` of the syscall data on their own. ==== [[mac-mpo-thread-userret]] ==== `mpo_thread_userret` [source,c] ---- void mpo_thread_userret(struct thread *td); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`td` |Returning thread | |=== This entry point permits policy modules to perform MAC-related events when a thread returns to user space, via a system call return, trap return, or otherwise. This is required for policies that have floating process labels, as it is not always possible to acquire the process lock at arbitrary points in the stack during system call processing; process labels might represent traditional authentication data, process history information, or other data. To employ this mechanism, intended changes to the process credential label may be stored in the `p_label` protected by a per-policy spin lock, and then set the per-thread `TDF_ASTPENDING` flag and per-process `PS_MACPENDM` flag to schedule a call to the `userret` entry point. From this entry point, the policy may create a replacement credential with less concern about the locking context. Policy writers are cautioned that event ordering relating to scheduling an AST and the AST being performed may be complex and interlaced in multithreaded applications. [[mac-label-ops]] === Label Operations [[mac-mpo-init-bpfdesc]] ==== `mpo_init_bpfdesc_label` [source,c] ---- void mpo_init_bpfdesc_label(struct label *label); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |New label to apply | |=== Initialize the label on a newly instantiated bpfdesc (BPF descriptor). Sleeping is permitted. [[mac-mpo-init-cred-label]] ==== `mpo_init_cred_label` [source,c] ---- void mpo_init_cred_label(struct label *label); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |New label to initialize | |=== Initialize the label for a newly instantiated user credential. Sleeping is permitted. [[mac-mpo-init-devfsdirent]] ==== `mpo_init_devfsdirent_label` [source,c] ---- void mpo_init_devfsdirent_label(struct label *label); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |New label to apply | |=== Initialize the label on a newly instantiated devfs entry. Sleeping is permitted. [[mac-mpo-init-ifnet]] ==== `mpo_init_ifnet_label` [source,c] ---- void mpo_init_ifnet_label(struct label *label); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |New label to apply | |=== Initialize the label on a newly instantiated network interface. Sleeping is permitted. [[mac-mpo-init-ipq]] ==== `mpo_init_ipq_label` [source,c] ---- void mpo_init_ipq_label(struct label *label, int flag); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |New label to apply | |`flag` |Sleeping/non-sleeping man:malloc[9]; see below | |=== Initialize the label on a newly instantiated IP fragment reassembly queue. The `flag` field may be one of M_WAITOK and M_NOWAIT, and should be employed to avoid performing a sleeping man:malloc[9] during this initialization call. IP fragment reassembly queue allocation frequently occurs in performance sensitive environments, and the implementation should be careful to avoid sleeping or long-lived operations. This entry point is permitted to fail resulting in the failure to allocate the IP fragment reassembly queue. [[mac-mpo-init-mbuf]] ==== `mpo_init_mbuf_label` [source,c] ---- void mpo_init_mbuf_label(int flag, struct label *label); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`flag` |Sleeping/non-sleeping man:malloc[9]; see below | |`label` |Policy label to initialize | |=== Initialize the label on a newly instantiated mbuf packet header (`mbuf`). The `flag` field may be one of M_WAITOK and M_NOWAIT, and should be employed to avoid performing a sleeping man:malloc[9] during this initialization call. Mbuf allocation frequently occurs in performance sensitive environments, and the implementation should be careful to avoid sleeping or long-lived operations. This entry point is permitted to fail resulting in the failure to allocate the mbuf header. [[mac-mpo-init-mount]] ==== `mpo_init_mount_label` [source,c] ---- void mpo_init_mount_label(struct label *mntlabel, struct label *fslabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`mntlabel` |Policy label to be initialized for the mount itself | |`fslabel` |Policy label to be initialized for the file system | |=== Initialize the labels on a newly instantiated mount point. Sleeping is permitted. [[mac-mpo-init-mount-fs-label]] ==== `mpo_init_mount_fs_label` [source,c] ---- void mpo_init_mount_fs_label(struct label *label); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |Label to be initialized | |=== Initialize the label on a newly mounted file system. Sleeping is permitted [[mac-mpo-init-pipe-label]] ==== `mpo_init_pipe_label` [source,c] ---- void mpo_init_pipe_label(struct label *label); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |Label to be filled in | |=== Initialize a label for a newly instantiated pipe. Sleeping is permitted. [[mac-mpo-init-socket]] ==== `mpo_init_socket_label` [source,c] ---- void mpo_init_socket_label(struct label *label, int flag); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |New label to initialize | |`flag` |man:malloc[9] flags | |=== Initialize a label for a newly instantiated socket. The `flag` field may be one of M_WAITOK and M_NOWAIT, and should be employed to avoid performing a sleeping man:malloc[9] during this initialization call. [[mac-mpo-init-socket-peer-label]] ==== `mpo_init_socket_peer_label` [source,c] ---- void mpo_init_socket_peer_label(struct label *label, int flag); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |New label to initialize | |`flag` |man:malloc[9] flags | |=== Initialize the peer label for a newly instantiated socket. The `flag` field may be one of M_WAITOK and M_NOWAIT, and should be employed to avoid performing a sleeping man:malloc[9] during this initialization call. [[mac-mpo-init-proc-label]] ==== `mpo_init_proc_label` [source,c] ---- void mpo_init_proc_label(struct label *label); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |New label to initialize | |=== Initialize the label for a newly instantiated process. Sleeping is permitted. [[mac-mpo-init-vnode]] ==== `mpo_init_vnode_label` [source,c] ---- void mpo_init_vnode_label(struct label *label); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |New label to initialize | |=== Initialize the label on a newly instantiated vnode. Sleeping is permitted. [[mac-mpo-destroy-bpfdesc]] ==== `mpo_destroy_bpfdesc_label` [source,c] ---- void mpo_destroy_bpfdesc_label(struct label *label); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |bpfdesc label | |=== Destroy the label on a BPF descriptor. In this entry point a policy should free any internal storage associated with `label` so that it may be destroyed. [[mac-mpo-destroy-cred]] ==== `mpo_destroy_cred_label` [source,c] ---- void mpo_destroy_cred_label(struct label *label); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |Label being destroyed | |=== Destroy the label on a credential. In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. [[mac-mpo-destroy-devfsdirent]] ==== `mpo_destroy_devfsdirent_label` [source,c] ---- void mpo_destroy_devfsdirent_label(struct label *label); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |Label being destroyed | |=== Destroy the label on a devfs entry. In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. [[mac-mpo-destroy-ifnet-label]] ==== `mpo_destroy_ifnet_label` [source,c] ---- void mpo_destroy_ifnet_label(struct label *label); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |Label being destroyed | |=== Destroy the label on a removed interface. In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. [[mac-mpo-destroy-ipq-label]] ==== `mpo_destroy_ipq_label` [source,c] ---- void mpo_destroy_ipq_label(struct label *label); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |Label being destroyed | |=== Destroy the label on an IP fragment queue. In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. [[mac-mpo-destroy-mbuf-label]] ==== `mpo_destroy_mbuf_label` [source,c] ---- void mpo_destroy_mbuf_label(struct label *label); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |Label being destroyed | |=== Destroy the label on an mbuf header. In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. [[mac-mpo-destroy-mount-label]] ==== `mpo_destroy_mount_label` [source,c] ---- void mpo_destroy_mount_label(struct label *label); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |Mount point label being destroyed | |=== Destroy the labels on a mount point. In this entry point, a policy module should free the internal storage associated with `mntlabel` so that they may be destroyed. [[mac-mpo-destroy-mount]] ==== `mpo_destroy_mount_label` [source,c] ---- void mpo_destroy_mount_label(struct label *mntlabel, struct label *fslabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`mntlabel` |Mount point label being destroyed | |`fslabel` |File system label being destroyed> | |=== Destroy the labels on a mount point. In this entry point, a policy module should free the internal storage associated with `mntlabel` and `fslabel` so that they may be destroyed. [[mac-mpo-destroy-socket]] ==== `mpo_destroy_socket_label` [source,c] ---- void mpo_destroy_socket_label(struct label *label); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |Socket label being destroyed | |=== Destroy the label on a socket. In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. [[mac-mpo-destroy-socket-peer-label]] ==== `mpo_destroy_socket_peer_label` [source,c] ---- void mpo_destroy_socket_peer_label(struct label *peerlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`peerlabel` |Socket peer label being destroyed | |=== Destroy the peer label on a socket. In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. [[mac-mpo-destroy-pipe-label]] ==== `mpo_destroy_pipe_label` [source,c] ---- void mpo_destroy_pipe_label(struct label *label); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |Pipe label | |=== Destroy the label on a pipe. In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. [[mac-mpo-destroy-proc-label]] ==== `mpo_destroy_proc_label` [source,c] ---- void mpo_destroy_proc_label(struct label *label); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |Process label | |=== Destroy the label on a process. In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. [[mac-mpo-destroy-vnode-label]] ==== `mpo_destroy_vnode_label` [source,c] ---- void mpo_destroy_vnode_label(struct label *label); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |Process label | |=== Destroy the label on a vnode. In this entry point, a policy module should free any internal storage associated with `label` so that it may be destroyed. [[mac-mpo-copy-mbuf-label]] ==== `mpo_copy_mbuf_label` [source,c] ---- void mpo_copy_mbuf_label(struct label *src, struct label *dest); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`src` |Source label | |`dest` |Destination label | |=== Copy the label information in `src` into `dest`. [[mac-mpo-copy-pipe-label]] ==== `mpo_copy_pipe_label` [source,c] ---- void mpo_copy_pipe_label(struct label *src, struct label *dest); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`src` |Source label | |`dest` |Destination label | |=== Copy the label information in `src` into `dest`. [[mac-mpo-copy-vnode-label]] ==== `mpo_copy_vnode_label` [source,c] ---- void mpo_copy_vnode_label(struct label *src, struct label *dest); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`src` |Source label | |`dest` |Destination label | |=== Copy the label information in `src` into `dest`. [[mac-mpo-externalize-cred-label]] ==== `mpo_externalize_cred_label` [source,c] ---- int mpo_externalize_cred_label(struct label *label, char *element_name, struct sbuf *sb, int *claimed); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |Label to be externalized | |`element_name` |Name of the policy whose label should be externalized | |`sb` |String buffer to be filled with a text representation of label | |`claimed` |Should be incremented when `element_data` can be filled in. | |=== Produce an externalized label based on the label structure passed. An externalized label consists of a text representation of the label contents that can be used with userland applications and read by the user. Currently, all policies' `externalize` entry points will be called, so the implementation should check the contents of `element_name` before attempting to fill in `sb`. If `element_name` does not match the name of your policy, simply return 0. Only return nonzero if an error occurs while externalizing the label data. Once the policy fills in `element_data`, `*claimed` should be incremented. [[mac-mpo-externalize-ifnet-label]] ==== `mpo_externalize_ifnet_label` [source,c] ---- int mpo_externalize_ifnet_label(struct label *label, char *element_name, struct sbuf *sb, int *claimed); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |Label to be externalized | |`element_name` |Name of the policy whose label should be externalized | |`sb` |String buffer to be filled with a text representation of label | |`claimed` |Should be incremented when `element_data` can be filled in. | |=== Produce an externalized label based on the label structure passed. An externalized label consists of a text representation of the label contents that can be used with userland applications and read by the user. Currently, all policies' `externalize` entry points will be called, so the implementation should check the contents of `element_name` before attempting to fill in `sb`. If `element_name` does not match the name of your policy, simply return 0. Only return nonzero if an error occurs while externalizing the label data. Once the policy fills in `element_data`, `*claimed` should be incremented. [[mac-mpo-externalize-pipe-label]] ==== `mpo_externalize_pipe_label` [source,c] ---- int mpo_externalize_pipe_label(struct label *label, char *element_name, struct sbuf *sb, int *claimed); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |Label to be externalized | |`element_name` |Name of the policy whose label should be externalized | |`sb` |String buffer to be filled with a text representation of label | |`claimed` |Should be incremented when `element_data` can be filled in. | |=== Produce an externalized label based on the label structure passed. An externalized label consists of a text representation of the label contents that can be used with userland applications and read by the user. Currently, all policies' `externalize` entry points will be called, so the implementation should check the contents of `element_name` before attempting to fill in `sb`. If `element_name` does not match the name of your policy, simply return 0. Only return nonzero if an error occurs while externalizing the label data. Once the policy fills in `element_data`, `*claimed` should be incremented. [[mac-mpo-externalize-socket-label]] ==== `mpo_externalize_socket_label` [source,c] ---- int mpo_externalize_socket_label(struct label *label, char *element_name, struct sbuf *sb, int *claimed); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |Label to be externalized | |`element_name` |Name of the policy whose label should be externalized | |`sb` |String buffer to be filled with a text representation of label | |`claimed` |Should be incremented when `element_data` can be filled in. | |=== Produce an externalized label based on the label structure passed. An externalized label consists of a text representation of the label contents that can be used with userland applications and read by the user. Currently, all policies' `externalize` entry points will be called, so the implementation should check the contents of `element_name` before attempting to fill in `sb`. If `element_name` does not match the name of your policy, simply return 0. Only return nonzero if an error occurs while externalizing the label data. Once the policy fills in `element_data`, `*claimed` should be incremented. [[mac-mpo-externalize-socket-peer-label]] ==== `mpo_externalize_socket_peer_label` [source,c] ---- int mpo_externalize_socket_peer_label(struct label *label, char *element_name, struct sbuf *sb, int *claimed); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |Label to be externalized | |`element_name` |Name of the policy whose label should be externalized | |`sb` |String buffer to be filled with a text representation of label | |`claimed` |Should be incremented when `element_data` can be filled in. | |=== Produce an externalized label based on the label structure passed. An externalized label consists of a text representation of the label contents that can be used with userland applications and read by the user. Currently, all policies' `externalize` entry points will be called, so the implementation should check the contents of `element_name` before attempting to fill in `sb`. If `element_name` does not match the name of your policy, simply return 0. Only return nonzero if an error occurs while externalizing the label data. Once the policy fills in `element_data`, `*claimed` should be incremented. [[mac-mpo-externalize-vnode-label]] ==== `mpo_externalize_vnode_label` [source,c] ---- int mpo_externalize_vnode_label(struct label *label, char *element_name, struct sbuf *sb, int *claimed); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |Label to be externalized | |`element_name` |Name of the policy whose label should be externalized | |`sb` |String buffer to be filled with a text representation of label | |`claimed` |Should be incremented when `element_data` can be filled in. | |=== Produce an externalized label based on the label structure passed. An externalized label consists of a text representation of the label contents that can be used with userland applications and read by the user. Currently, all policies' `externalize` entry points will be called, so the implementation should check the contents of `element_name` before attempting to fill in `sb`. If `element_name` does not match the name of your policy, simply return 0. Only return nonzero if an error occurs while externalizing the label data. Once the policy fills in `element_data`, `*claimed` should be incremented. [[mac-mpo-internalize-cred-label]] ==== `mpo_internalize_cred_label` [source,c] ---- int mpo_internalize_cred_label(struct label *label, char *element_name, char *element_data, int *claimed); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |Label to be filled in | |`element_name` |Name of the policy whose label should be internalized | |`element_data` |Text data to be internalized | |`claimed` |Should be incremented when data can be successfully internalized. | |=== Produce an internal label structure based on externalized label data in text format. Currently, all policies' `internalize` entry points are called when internalization is requested, so the implementation should compare the contents of `element_name` to its own name in order to be sure it should be internalizing the data in `element_data`. Just as in the `externalize` entry points, the entry point should return 0 if `element_name` does not match its own name, or when data can successfully be internalized, in which case `*claimed` should be incremented. [[mac-mpo-internalize-ifnet-label]] ==== `mpo_internalize_ifnet_label` [source,c] ---- int mpo_internalize_ifnet_label(struct label *label, char *element_name, char *element_data, int *claimed); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |Label to be filled in | |`element_name` |Name of the policy whose label should be internalized | |`element_data` |Text data to be internalized | |`claimed` |Should be incremented when data can be successfully internalized. | |=== Produce an internal label structure based on externalized label data in text format. Currently, all policies' `internalize` entry points are called when internalization is requested, so the implementation should compare the contents of `element_name` to its own name in order to be sure it should be internalizing the data in `element_data`. Just as in the `externalize` entry points, the entry point should return 0 if `element_name` does not match its own name, or when data can successfully be internalized, in which case `*claimed` should be incremented. [[mac-mpo-internalize-pipe-label]] ==== `mpo_internalize_pipe_label` [source,c] ---- int mpo_internalize_pipe_label(struct label *label, char *element_name, char *element_data, int *claimed); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |Label to be filled in | |`element_name` |Name of the policy whose label should be internalized | |`element_data` |Text data to be internalized | |`claimed` |Should be incremented when data can be successfully internalized. | |=== Produce an internal label structure based on externalized label data in text format. Currently, all policies' `internalize` entry points are called when internalization is requested, so the implementation should compare the contents of `element_name` to its own name in order to be sure it should be internalizing the data in `element_data`. Just as in the `externalize` entry points, the entry point should return 0 if `element_name` does not match its own name, or when data can successfully be internalized, in which case `*claimed` should be incremented. [[mac-mpo-internalize-socket-label]] ==== `mpo_internalize_socket_label` [source,c] ---- int mpo_internalize_socket_label(struct label *label, char *element_name, char *element_data, int *claimed); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |Label to be filled in | |`element_name` |Name of the policy whose label should be internalized | |`element_data` |Text data to be internalized | |`claimed` |Should be incremented when data can be successfully internalized. | |=== Produce an internal label structure based on externalized label data in text format. Currently, all policies' `internalize` entry points are called when internalization is requested, so the implementation should compare the contents of `element_name` to its own name in order to be sure it should be internalizing the data in `element_data`. Just as in the `externalize` entry points, the entry point should return 0 if `element_name` does not match its own name, or when data can successfully be internalized, in which case `*claimed` should be incremented. [[mac-mpo-internalize-vnode-label]] ==== `mpo_internalize_vnode_label` [source,c] ---- int mpo_internalize_vnode_label(struct label *label, char *element_name, char *element_data, int *claimed); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`label` |Label to be filled in | |`element_name` |Name of the policy whose label should be internalized | |`element_data` |Text data to be internalized | |`claimed` |Should be incremented when data can be successfully internalized. | |=== Produce an internal label structure based on externalized label data in text format. Currently, all policies' `internalize` entry points are called when internalization is requested, so the implementation should compare the contents of `element_name` to its own name in order to be sure it should be internalizing the data in `element_data`. Just as in the `externalize` entry points, the entry point should return 0 if `element_name` does not match its own name, or when data can successfully be internalized, in which case `*claimed` should be incremented. [[mac-label-events]] === Label Events This class of entry points is used by the MAC framework to permit policies to maintain label information on kernel objects. For each labeled kernel object of interest to a MAC policy, entry points may be registered for relevant life cycle events. All objects implement initialization, creation, and destruction hooks. Some objects will also implement relabeling, allowing user processes to change the labels on objects. Some objects will also implement object-specific events, such as label events associated with IP reassembly. A typical labeled object will have the following life cycle of entry points: [.programlisting] .... Label initialization o (object-specific wait) \ Label creation o \ Relabel events, o--<--. Various object-specific, | | Access control events ~-->--o \ Label destruction o .... Label initialization permits policies to allocate memory and set initial values for labels without context for the use of the object. The label slot allocated to a policy will be zeroed by default, so some policies may not need to perform initialization. Label creation occurs when the kernel structure is associated with an actual kernel object. For example, Mbufs may be allocated and remain unused in a pool until they are required. mbuf allocation causes label initialization on the mbuf to take place, but mbuf creation occurs when the mbuf is associated with a datagram. Typically, context will be provided for a creation event, including the circumstances of the creation, and labels of other relevant objects in the creation process. For example, when an mbuf is created from a socket, the socket and its label will be presented to registered policies in addition to the new mbuf and its label. Memory allocation in creation events is discouraged, as it may occur in performance sensitive ports of the kernel; in addition, creation calls are not permitted to fail so a failure to allocate memory cannot be reported. Object specific events do not generally fall into the other broad classes of label events, but will generally provide an opportunity to modify or update the label on an object based on additional context. For example, the label on an IP fragment reassembly queue may be updated during the MAC_UPDATE_IPQ entry point as a result of the acceptance of an additional mbuf to that queue. Access control events are discussed in detail in the following section. Label destruction permits policies to release storage or state associated with a label during its association with an object so that the kernel data structures supporting the object may be reused or released. In addition to labels associated with specific kernel objects, an additional class of labels exists: temporary labels. These labels are used to store update information submitted by user processes. These labels are initialized and destroyed as with other label types, but the creation event is MAC_INTERNALIZE, which accepts a user label to be converted to an in-kernel representation. [[mac-fs-label-event-ops]] ==== File System Object Labeling Event Operations [[mac-mpo-associate-vnode-devfs]] ===== `mpo_associate_vnode_devfs` [source,c] ---- void mpo_associate_vnode_devfs(struct mount *mp, struct label *fslabel, struct devfs_dirent *de, struct label *delabel, struct vnode *vp, struct label *vlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`mp` |Devfs mount point | |`fslabel` |Devfs file system label (`mp->mnt_fslabel`) | |`de` |Devfs directory entry | |`delabel` |Policy label associated with `de` | |`vp` |vnode associated with `de` | |`vlabel` |Policy label associated with `vp` | |=== Fill in the label (`vlabel`) for a newly created devfs vnode based on the devfs directory entry passed in `de` and its label. [[mac-mpo-associate-vnode-extattr]] ===== `mpo_associate_vnode_extattr` [source,c] ---- int mpo_associate_vnode_extattr(struct mount *mp, struct label *fslabel, struct vnode *vp, struct label *vlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`mp` |File system mount point | |`fslabel` |File system label | |`vp` |Vnode to label | |`vlabel` |Policy label associated with `vp` | |=== Attempt to retrieve the label for `vp` from the file system extended attributes. Upon success, the value `0` is returned. Should extended attribute retrieval not be supported, an accepted fallback is to copy `fslabel` into `vlabel`. In the event of an error, an appropriate value for `errno` should be returned. [[mac-mpo-associate-vnode-singlelabel]] ===== `mpo_associate_vnode_singlelabel` [source,c] ---- void mpo_associate_vnode_singlelabel(struct mount *mp, struct label *fslabel, struct vnode *vp, struct label *vlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`mp` |File system mount point | |`fslabel` |File system label | |`vp` |Vnode to label | |`vlabel` |Policy label associated with `vp` | |=== On non-multilabel file systems, this entry point is called to set the policy label for `vp` based on the file system label, `fslabel`. [[mac-mpo-create-devfs-device]] ===== `mpo_create_devfs_device` [source,c] ---- void mpo_create_devfs_device(dev_t dev, struct devfs_dirent *devfs_dirent, struct label *label); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`dev` |Device corresponding with `devfs_dirent` | |`devfs_dirent` |Devfs directory entry to be labeled. | |`label` |Label for `devfs_dirent` to be filled in. | |=== Fill out the label on a devfs_dirent being created for the passed device. This call will be made when the device file system is mounted, regenerated, or a new device is made available. [[mac-mpo-create-devfs-directory]] ===== `mpo_create_devfs_directory` [source,c] ---- void mpo_create_devfs_directory(char *dirname, int dirnamelen, struct devfs_dirent *devfs_dirent, struct label *label); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`dirname` |Name of directory being created | |`namelen` |Length of string `dirname` | |`devfs_dirent` |Devfs directory entry for directory being created. | |=== Fill out the label on a devfs_dirent being created for the passed directory. This call will be made when the device file system is mounted, regenerated, or a new device requiring a specific directory hierarchy is made available. [[mac-mpo-create-devfs-symlink]] ===== `mpo_create_devfs_symlink` [source,c] ---- void mpo_create_devfs_symlink(struct ucred *cred, struct mount *mp, struct devfs_dirent *dd, struct label *ddlabel, struct devfs_dirent *de, struct label *delabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`mp` |Devfs mount point | |`dd` |Link destination | |`ddlabel` |Label associated with `dd` | |`de` |Symlink entry | |`delabel` |Label associated with `de` | |=== Fill in the label (`delabel`) for a newly created man:devfs[5] symbolic link entry. [[mac-mpo-create-vnode-extattr]] ===== `mpo_create_vnode_extattr` [source,c] ---- int mpo_create_vnode_extattr(struct ucred *cred, struct mount *mp, struct label *fslabel, struct vnode *dvp, struct label *dlabel, struct vnode *vp, struct label *vlabel, struct componentname *cnp); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`mount` |File system mount point | |`label` |File system label | |`dvp` |Parent directory vnode | |`dlabel` |Label associated with `dvp` | |`vp` |Newly created vnode | |`vlabel` |Policy label associated with `vp` | |`cnp` |Component name for `vp` | |=== Write out the label for `vp` to the appropriate extended attribute. If the write succeeds, fill in `vlabel` with the label, and return 0. Otherwise, return an appropriate error. [[mac-mpo-create-mount]] ===== `mpo_create_mount` [source,c] ---- void mpo_create_mount(struct ucred *cred, struct mount *mp, struct label *mnt, struct label *fslabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`mp` |Object; file system being mounted | |`mntlabel` |Policy label to be filled in for `mp` | |`fslabel` |Policy label for the file system `mp` mounts. | |=== Fill out the labels on the mount point being created by the passed subject credential. This call will be made when a new file system is mounted. [[mac-mpo-create-root-mount]] ===== `mpo_create_root_mount` [source,c] ---- void mpo_create_root_mount(struct ucred *cred, struct mount *mp, struct label *mntlabel, struct label *fslabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking 3+|See <>. |=== Fill out the labels on the mount point being created by the passed subject credential. This call will be made when the root file system is mounted, after `mpo_create_mount;`. [[mac-mpo-relabel-vnode]] ===== `mpo_relabel_vnode` [source,c] ---- void mpo_relabel_vnode(struct ucred *cred, struct vnode *vp, struct label *vnodelabel, struct label *newlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`vp` |vnode to relabel | |`vnodelabel` |Existing policy label for `vp` | |`newlabel` |New, possibly partial label to replace `vnodelabel` | |=== Update the label on the passed vnode given the passed update vnode label and the passed subject credential. [[mac-mpo-setlabel-vnode-extattr]] ===== `mpo_setlabel_vnode_extattr` [source,c] ---- int mpo_setlabel_vnode_extattr(struct ucred *cred, struct vnode *vp, struct label *vlabel, struct label *intlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`vp` |Vnode for which the label is being written | |`vlabel` |Policy label associated with `vp` | |`intlabel` |Label to write out | |=== Write out the policy from `intlabel` to an extended attribute. This is called from `vop_stdcreatevnode_ea`. [[mac-mpo-update-devfsdirent]] ===== `mpo_update_devfsdirent` [source,c] ---- void mpo_update_devfsdirent(struct devfs_dirent *devfs_dirent, struct label *direntlabel, struct vnode *vp, struct label *vnodelabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`devfs_dirent` |Object; devfs directory entry | |`direntlabel` |Policy label for `devfs_dirent` to be updated. | |`vp` |Parent vnode |Locked -| |`vnodelabel` |Policy label for `vp` | |=== Update the `devfs_dirent` label from the passed devfs vnode label. This call will be made when a devfs vnode has been successfully relabeled to commit the label change such that it lasts even if the vnode is recycled. It will also be made when a symlink is created in devfs, following a call to `mac_vnode_create_from_vnode` to initialize the vnode label. [[mac-ipc-label-ops]] ==== IPC Object Labeling Event Operations [[mac-mpo-create-mbuf-from-socket]] ===== `mpo_create_mbuf_from_socket` [source,c] ---- void mpo_create_mbuf_from_socket(struct socket *so, struct label *socketlabel, struct mbuf *m, struct label *mbuflabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`socket` |Socket |Socket locking WIP |`socketlabel` |Policy label for `socket` | |`m` |Object; mbuf | |`mbuflabel` |Policy label to fill in for `m` | |=== Set the label on a newly created mbuf header from the passed socket label. This call is made when a new datagram or message is generated by the socket and stored in the passed mbuf. [[mac-mpo-create-pipe]] ===== `mpo_create_pipe` [source,c] ---- void mpo_create_pipe(struct ucred *cred, struct pipe *pipe, struct label *pipelabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`pipe` |Pipe | |`pipelabel` |Policy label associated with `pipe` | |=== Set the label on a newly created pipe from the passed subject credential. This call is made when a new pipe is created. [[mac-mpo-create-socket]] ===== `mpo_create_socket` [source,c] ---- void mpo_create_socket(struct ucred *cred, struct socket *so, struct label *socketlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential |Immutable |`so` |Object; socket to label | |`socketlabel` |Label to fill in for `so` | |=== Set the label on a newly created socket from the passed subject credential. This call is made when a socket is created. [[mac-mpo-create-socket-from-socket]] ===== `mpo_create_socket_from_socket` [source,c] ---- void mpo_create_socket_from_socket(struct socket *oldsocket, struct label *oldsocketlabel, struct socket *newsocket, struct label *newsocketlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`oldsocket` |Listening socket | |`oldsocketlabel` |Policy label associated with `oldsocket` | |`newsocket` |New socket | |`newsocketlabel` |Policy label associated with `newsocketlabel` | |=== Label a socket, `newsocket`, newly man:accept[2]ed, based on the man:listen[2] socket, `oldsocket`. [[mac-mpo-relabel-pipe]] ===== `mpo_relabel_pipe` [source,c] ---- void mpo_relabel_pipe(struct ucred *cred, struct pipe *pipe, struct label *oldlabel, struct label *newlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`pipe` |Pipe | |`oldlabel` |Current policy label associated with `pipe` | |`newlabel` |Policy label update to apply to `pipe` | |=== Apply a new label, `newlabel`, to `pipe`. [[mac-mpo-relabel-socket]] ===== `mpo_relabel_socket` [source,c] ---- void mpo_relabel_socket(struct ucred *cred, struct socket *so, struct label *oldlabel, struct label *newlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential |Immutable |`so` |Object; socket | |`oldlabel` |Current label for `so` | |`newlabel` |Label update for `so` | |=== Update the label on a socket from the passed socket label update. [[mpo-set-socket-peer-from-mbuf]] ===== `mpo_set_socket_peer_from_mbuf` [source,c] ---- void mpo_set_socket_peer_from_mbuf(struct mbuf *mbuf, struct label *mbuflabel, struct label *oldlabel, struct label *newlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`mbuf` |First datagram received over socket | |`mbuflabel` |Label for `mbuf` | |`oldlabel` |Current label for the socket | |`newlabel` |Policy label to be filled out for the socket | |=== Set the peer label on a stream socket from the passed mbuf label. This call will be made when the first datagram is received by the stream socket, with the exception of Unix domain sockets. [[mac-mpo-set-socket-peer-from-socket]] ===== `mpo_set_socket_peer_from_socket` [source,c] ---- void mpo_set_socket_peer_from_socket(struct socket *oldsocket, struct label *oldsocketlabel, struct socket *newsocket, struct label *newsocketpeerlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`oldsocket` |Local socket | |`oldsocketlabel` |Policy label for `oldsocket` | |`newsocket` |Peer socket | |`newsocketpeerlabel` |Policy label to fill in for `newsocket` | |=== Set the peer label on a stream UNIX domain socket from the passed remote socket endpoint. This call will be made when the socket pair is connected, and will be made for both endpoints. [[mac-net-labeling-event-ops]] ==== Network Object Labeling Event Operations [[mac-mpo-create-bpfdesc]] ===== `mpo_create_bpfdesc` [source,c] ---- void mpo_create_bpfdesc(struct ucred *cred, struct bpf_d *bpf_d, struct label *bpflabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential |Immutable |`bpf_d` |Object; bpf descriptor | |`bpf` |Policy label to be filled in for `bpf_d` | |=== Set the label on a newly created BPF descriptor from the passed subject credential. This call will be made when a BPF device node is opened by a process with the passed subject credential. [[mac-mpo-create-ifnet]] ===== `mpo_create_ifnet` [source,c] ---- void mpo_create_ifnet(struct ifnet *ifnet, struct label *ifnetlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`ifnet` |Network interface | |`ifnetlabel` |Policy label to fill in for `ifnet` | |=== Set the label on a newly created interface. This call may be made when a new physical interface becomes available to the system, or when a pseudo-interface is instantiated during the boot or as a result of a user action. [[mac-mpo-create-ipq]] ===== `mpo_create_ipq` [source,c] ---- void mpo_create_ipq(struct mbuf *fragment, struct label *fragmentlabel, struct ipq *ipq, struct label *ipqlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`fragment` |First received IP fragment | |`fragmentlabel` |Policy label for `fragment` | |`ipq` |IP reassembly queue to be labeled | |`ipqlabel` |Policy label to be filled in for `ipq` | |=== Set the label on a newly created IP fragment reassembly queue from the mbuf header of the first received fragment. [[mac-mpo-create-datagram-from-ipq]] ===== `mpo_create_datagram_from_ipq` [source,c] ---- void mpo_create_create_datagram_from_ipq(struct ipq *ipq, struct label *ipqlabel, struct mbuf *datagram, struct label *datagramlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`ipq` |IP reassembly queue | |`ipqlabel` |Policy label for `ipq` | |`datagram` |Datagram to be labeled | |`datagramlabel` |Policy label to be filled in for `datagramlabel` | |=== Set the label on a newly reassembled IP datagram from the IP fragment reassembly queue from which it was generated. [[mac-mpo-create-fragment]] ===== `mpo_create_fragment` [source,c] ---- void mpo_create_fragment(struct mbuf *datagram, struct label *datagramlabel, struct mbuf *fragment, struct label *fragmentlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`datagram` |Datagram | |`datagramlabel` |Policy label for `datagram` | |`fragment` |Fragment to be labeled | |`fragmentlabel` |Policy label to be filled in for `datagram` | |=== Set the label on the mbuf header of a newly created IP fragment from the label on the mbuf header of the datagram it was generate from. [[mac-mpo-create-mbuf-from-mbuf]] ===== `mpo_create_mbuf_from_mbuf` [source,c] ---- void mpo_create_mbuf_from_mbuf(struct mbuf *oldmbuf, struct label *oldmbuflabel, struct mbuf *newmbuf, struct label *newmbuflabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`oldmbuf` |Existing (source) mbuf | |`oldmbuflabel` |Policy label for `oldmbuf` | |`newmbuf` |New mbuf to be labeled | |`newmbuflabel` |Policy label to be filled in for `newmbuf` | |=== Set the label on the mbuf header of a newly created datagram from the mbuf header of an existing datagram. This call may be made in a number of situations, including when an mbuf is re-allocated for alignment purposes. [[mac-mpo-create-mbuf-linklayer]] ===== `mpo_create_mbuf_linklayer` [source,c] ---- void mpo_create_mbuf_linklayer(struct ifnet *ifnet, struct label *ifnetlabel, struct mbuf *mbuf, struct label *mbuflabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`ifnet` |Network interface | |`ifnetlabel` |Policy label for `ifnet` | |`mbuf` |mbuf header for new datagram | |`mbuflabel` |Policy label to be filled in for `mbuf` | |=== Set the label on the mbuf header of a newly created datagram generated for the purposes of a link layer response for the passed interface. This call may be made in a number of situations, including for ARP or ND6 responses in the IPv4 and IPv6 stacks. [[mac-mpo-create-mbuf-from-bpfdesc]] ===== `mpo_create_mbuf_from_bpfdesc` [source,c] ---- void mpo_create_mbuf_from_bpfdesc(struct bpf_d *bpf_d, struct label *bpflabel, struct mbuf *mbuf, struct label *mbuflabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`bpf_d` |BPF descriptor | |`bpflabel` |Policy label for `bpflabel` | |`mbuf` |New mbuf to be labeled | |`mbuflabel` |Policy label to fill in for `mbuf` | |=== Set the label on the mbuf header of a newly created datagram generated using the passed BPF descriptor. This call is made when a write is performed to the BPF device associated with the passed BPF descriptor. [[mac-mpo-create-mbuf-from-ifnet]] ===== `mpo_create_mbuf_from_ifnet` [source,c] ---- void mpo_create_mbuf_from_ifnet(struct ifnet *ifnet, struct label *ifnetlabel, struct mbuf *mbuf, struct label *mbuflabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`ifnet` |Network interface | |`ifnetlabel` |Policy label for `ifnetlabel` | |`mbuf` |mbuf header for new datagram | |`mbuflabel` |Policy label to be filled in for `mbuf` | |=== Set the label on the mbuf header of a newly created datagram generated from the passed network interface. [[mac-mpo-create-mbuf-multicast-encap]] ===== `mpo_create_mbuf_multicast_encap` [source,c] ---- void mpo_create_mbuf_multicast_encap(struct mbuf *oldmbuf, struct label *oldmbuflabel, struct ifnet *ifnet, struct label *ifnetlabel, struct mbuf *newmbuf, struct label *newmbuflabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`oldmbuf` |mbuf header for existing datagram | |`oldmbuflabel` |Policy label for `oldmbuf` | |`ifnet` |Network interface | |`ifnetlabel` |Policy label for `ifnet` | |`newmbuf` |mbuf header to be labeled for new datagram | |`newmbuflabel` |Policy label to be filled in for `newmbuf` | |=== Set the label on the mbuf header of a newly created datagram generated from the existing passed datagram when it is processed by the passed multicast encapsulation interface. This call is made when an mbuf is to be delivered using the virtual interface. [[mac-mpo-create-mbuf-netlayer]] ===== `mpo_create_mbuf_netlayer` [source,c] ---- void mpo_create_mbuf_netlayer(struct mbuf *oldmbuf, struct label *oldmbuflabel, struct mbuf *newmbuf, struct label *newmbuflabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`oldmbuf` |Received datagram | |`oldmbuflabel` |Policy label for `oldmbuf` | |`newmbuf` |Newly created datagram | |`newmbuflabel` |Policy label for `newmbuf` | |=== Set the label on the mbuf header of a newly created datagram generated by the IP stack in response to an existing received datagram (`oldmbuf`). This call may be made in a number of situations, including when responding to ICMP request datagrams. [[mac-mpo-fragment-match]] ===== `mpo_fragment_match` [source,c] ---- int mpo_fragment_match(struct mbuf *fragment, struct label *fragmentlabel, struct ipq *ipq, struct label *ipqlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`fragment` |IP datagram fragment | |`fragmentlabel` |Policy label for `fragment` | |`ipq` |IP fragment reassembly queue | |`ipqlabel` |Policy label for `ipq` | |=== Determine whether an mbuf header containing an IP datagram (`fragment`) fragment matches the label of the passed IP fragment reassembly queue (`ipq`). Return (1) for a successful match, or (0) for no match. This call is made when the IP stack attempts to find an existing fragment reassembly queue for a newly received fragment; if this fails, a new fragment reassembly queue may be instantiated for the fragment. Policies may use this entry point to prevent the reassembly of otherwise matching IP fragments if policy does not permit them to be reassembled based on the label or other information. [[mac-mpo-ifnet-relabel]] ===== `mpo_relabel_ifnet` [source,c] ---- void mpo_relabel_ifnet(struct ucred *cred, struct ifnet *ifnet, struct label *ifnetlabel, struct label *newlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`ifnet` |Object; Network interface | |`ifnetlabel` |Policy label for `ifnet` | |`newlabel` |Label update to apply to `ifnet` | |=== Update the label of network interface, `ifnet`, based on the passed update label, `newlabel`, and the passed subject credential, `cred`. [[mac-mpo-update-ipq]] ===== `mpo_update_ipq` [source,c] ---- void mpo_update_ipq(struct mbuf *fragment, struct label *fragmentlabel, struct ipq *ipq, struct label *ipqlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`mbuf` |IP fragment | |`mbuflabel` |Policy label for `mbuf` | |`ipq` |IP fragment reassembly queue | |`ipqlabel` |Policy label to be updated for `ipq` | |=== Update the label on an IP fragment reassembly queue (`ipq`) based on the acceptance of the passed IP fragment mbuf header (`mbuf`). [[mac-proc-labeling-event-ops]] ==== Process Labeling Event Operations [[mac-mpo-create-cred]] ===== `mpo_create_cred` [source,c] ---- void mpo_create_cred(struct ucred *parent_cred, struct ucred *child_cred); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`parent_cred` |Parent subject credential | |`child_cred` |Child subject credential | |=== Set the label of a newly created subject credential from the passed subject credential. This call will be made when man:crcopy[9] is invoked on a newly created `struct ucred`. This call should not be confused with a process forking or creation event. [[mac-mpo-execve-transition]] ===== `mpo_execve_transition` [source,c] ---- void mpo_execve_transition(struct ucred *old, struct ucred *new, struct vnode *vp, struct label *vnodelabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`old` |Existing subject credential |Immutable |`new` |New subject credential to be labeled | |`vp` |File to execute |Locked |`vnodelabel` |Policy label for `vp` | |=== Update the label of a newly created subject credential (`new`) from the passed existing subject credential (`old`) based on a label transition caused by executing the passed vnode (`vp`). This call occurs when a process executes the passed vnode and one of the policies returns a success from the `mpo_execve_will_transition` entry point. Policies may choose to implement this call simply by invoking `mpo_create_cred` and passing the two subject credentials so as not to implement a transitioning event. Policies should not leave this entry point unimplemented if they implement `mpo_create_cred`, even if they do not implement `mpo_execve_will_transition`. [[mac-mpo-execve-will-transition]] ===== `mpo_execve_will_transition` [source,c] ---- int mpo_execve_will_transition(struct ucred *old, struct vnode *vp, struct label *vnodelabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`old` |Subject credential prior to man:execve[2] |Immutable |`vp` |File to execute | |`vnodelabel` |Policy label for `vp` | |=== Determine whether the policy will want to perform a transition event as a result of the execution of the passed vnode by the passed subject credential. Return 1 if a transition is required, 0 if not. Even if a policy returns 0, it should behave correctly in the presence of an unexpected invocation of `mpo_execve_transition`, as that call may happen as a result of another policy requesting a transition. [[mac-mpo-create-proc0]] ===== `mpo_create_proc0` [source,c] ---- void mpo_create_proc0(struct ucred *cred); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential to be filled in | |=== Create the subject credential of process 0, the parent of all kernel processes. [[mac-mpo-create-proc1]] ===== `mpo_create_proc1` [source,c] ---- void mpo_create_proc1(struct ucred *cred); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential to be filled in | |=== Create the subject credential of process 1, the parent of all user processes. [[mac-mpo-relabel-cred]] ===== `mpo_relabel_cred` [source,c] ---- void mpo_relabel_cred(struct ucred *cred, struct label *newlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`newlabel` |Label update to apply to `cred` | |=== Update the label on a subject credential from the passed update label. [[mac-access-control-checks]] === Access Control Checks Access control entry points permit policy modules to influence access control decisions made by the kernel. Generally, although not always, arguments to an access control entry point will include one or more authorizing credentials, information (possibly including a label) for any other objects involved in the operation. An access control entry point may return 0 to permit the operation, or an man:errno[2] error value. The results of invoking the entry point across various registered policy modules will be composed as follows: if all modules permit the operation to succeed, success will be returned. If one or modules returns a failure, a failure will be returned. If more than one module returns a failure, the errno value to return to the user will be selected using the following precedence, implemented by the `error_select()` function in [.filename]#kern_mac.c#: [.informaltable] [cols="1,1", frame="none"] |=== |Most precedence |EDEADLK | |EINVAL | |ESRCH | |EACCES |Least precedence |EPERM |=== If none of the error values returned by all modules are listed in the precedence chart then an arbitrarily selected value from the set will be returned. In general, the rules provide precedence to errors in the following order: kernel failures, invalid arguments, object not present, access not permitted, other. [[mac-mpo-bpfdesc-check-receive-from-ifnet]] ==== `mpo_check_bpfdesc_receive` [source,c] ---- int mpo_check_bpfdesc_receive(struct bpf_d *bpf_d, struct label *bpflabel, struct ifnet *ifnet, struct label *ifnetlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`bpf_d` |Subject; BPF descriptor | |`bpflabel` |Policy label for `bpf_d` | |`ifnet` |Object; network interface | |`ifnetlabel` |Policy label for `ifnet` | |=== Determine whether the MAC framework should permit datagrams from the passed interface to be delivered to the buffers of the passed BPF descriptor. Return (0) for success, or an `errno` value for failure Suggested failure: EACCES for label mismatches, EPERM for lack of privilege. [[mac-mpo-check-kenv-dump]] ==== `mpo_check_kenv_dump` [source,c] ---- int mpo_check_kenv_dump(struct ucred *cred); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |=== Determine whether the subject should be allowed to retrieve the kernel environment (see man:kenv[2]). [[mac-mpo-check-kenv-get]] ==== `mpo_check_kenv_get` [source,c] ---- int mpo_check_kenv_get(struct ucred *cred, char *name); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`name` |Kernel environment variable name | |=== Determine whether the subject should be allowed to retrieve the value of the specified kernel environment variable. [[mac-mpo-check-kenv-set]] ==== `mpo_check_kenv_set` [source,c] ---- int mpo_check_kenv_set(struct ucred *cred, char *name); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`name` |Kernel environment variable name | |=== Determine whether the subject should be allowed to set the specified kernel environment variable. [[mac-mpo-check-kenv-unset]] ==== `mpo_check_kenv_unset` [source,c] ---- int mpo_check_kenv_unset(struct ucred *cred, char *name); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`name` |Kernel environment variable name | |=== Determine whether the subject should be allowed to unset the specified kernel environment variable. [[mac-mpo-check-kld-load]] ==== `mpo_check_kld_load` [source,c] ---- int mpo_check_kld_load(struct ucred *cred, struct vnode *vp, struct label *vlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`vp` |Kernel module vnode | |`vlabel` |Label associated with `vp` | |=== Determine whether the subject should be allowed to load the specified module file. [[mac-mpo-check-kld-stat]] ==== `mpo_check_kld_stat` [source,c] ---- int mpo_check_kld_stat(struct ucred *cred); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |=== Determine whether the subject should be allowed to retrieve a list of loaded kernel module files and associated statistics. [[mac-mpo-check-kld-unload]] ==== `mpo_check_kld_unload` [source,c] ---- int mpo_check_kld_unload(struct ucred *cred); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |=== Determine whether the subject should be allowed to unload a kernel module. [[mac-mpo-check-pipe-ioctl]] ==== `mpo_check_pipe_ioctl` [source,c] ---- int mpo_check_pipe_ioctl(struct ucred *cred, struct pipe *pipe, struct label *pipelabel, unsigned long cmd, void *data); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`pipe` |Pipe | |`pipelabel` |Policy label associated with `pipe` | |`cmd` |man:ioctl[2] command | |`data` |man:ioctl[2] data | |=== Determine whether the subject should be allowed to make the specified man:ioctl[2] call. [[mac-mpo-check-pipe-poll]] ==== `mpo_check_pipe_poll` [source,c] ---- int mpo_check_pipe_poll(struct ucred *cred, struct pipe *pipe, struct label *pipelabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`pipe` |Pipe | |`pipelabel` |Policy label associated with `pipe` | |=== Determine whether the subject should be allowed to poll `pipe`. [[mac-mpo-check-pipe-read]] ==== `mpo_check_pipe_read` [source,c] ---- int mpo_check_pipe_read(struct ucred *cred, struct pipe *pipe, struct label *pipelabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`pipe` |Pipe | |`pipelabel` |Policy label associated with `pipe` | |=== Determine whether the subject should be allowed read access to `pipe`. [[mac-mpo-check-pipe-relabel]] ==== `mpo_check_pipe_relabel` [source,c] ---- int mpo_check_pipe_relabel(struct ucred *cred, struct pipe *pipe, struct label *pipelabel, struct label *newlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`pipe` |Pipe | |`pipelabel` |Current policy label associated with `pipe` | |`newlabel` |Label update to `pipelabel` | |=== Determine whether the subject should be allowed to relabel `pipe`. [[mac-mpo-check-pipe-stat]] ==== `mpo_check_pipe_stat` [source,c] ---- int mpo_check_pipe_stat(struct ucred *cred, struct pipe *pipe, struct label *pipelabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`pipe` |Pipe | |`pipelabel` |Policy label associated with `pipe` | |=== Determine whether the subject should be allowed to retrieve statistics related to `pipe`. [[mac-mpo-check-pipe-write]] ==== `mpo_check_pipe_write` [source,c] ---- int mpo_check_pipe_write(struct ucred *cred, struct pipe *pipe, struct label *pipelabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`pipe` |Pipe | |`pipelabel` |Policy label associated with `pipe` | |=== Determine whether the subject should be allowed to write to `pipe`. [[mac-mpo-cred-check-socket-bind]] ==== `mpo_check_socket_bind` [source,c] ---- int mpo_check_socket_bind(struct ucred *cred, struct socket *socket, struct label *socketlabel, struct sockaddr *sockaddr); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`socket` |Socket to be bound | |`socketlabel` |Policy label for `socket` | |`sockaddr` |Address of `socket` | |=== [[mac-mpo-cred-check-socket-connect]] ==== `mpo_check_socket_connect` [source,c] ---- int mpo_check_socket_connect(struct ucred *cred, struct socket *socket, struct label *socketlabel, struct sockaddr *sockaddr); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`socket` |Socket to be connected | |`socketlabel` |Policy label for `socket` | |`sockaddr` |Address of `socket` | |=== Determine whether the subject credential (`cred`) can connect the passed socket (`socket`) to the passed socket address (`sockaddr`). Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatches, EPERM for lack of privilege. [[mac-mpo-check-socket-receive]] ==== `mpo_check_socket_receive` [source,c] ---- int mpo_check_socket_receive(struct ucred *cred, struct socket *so, struct label *socketlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`so` |Socket | |`socketlabel` |Policy label associated with `so` | |=== Determine whether the subject should be allowed to receive information from the socket `so`. [[mac-mpo-check-socket-send]] ==== `mpo_check_socket_send` [source,c] ---- int mpo_check_socket_send(struct ucred *cred, struct socket *so, struct label *socketlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`so` |Socket | |`socketlabel` |Policy label associated with `so` | |=== Determine whether the subject should be allowed to send information across the socket `so`. [[mac-mpo-check-cred-visible]] ==== `mpo_check_cred_visible` [source,c] ---- int mpo_check_cred_visible(struct ucred *u1, struct ucred *u2); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`u1` |Subject credential | |`u2` |Object credential | |=== Determine whether the subject credential `u1` can "see" other subjects with the passed subject credential `u2`. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatches, EPERM for lack of privilege, or ESRCH to hide visibility. This call may be made in a number of situations, including inter-process status sysctl's used by `ps`, and in procfs lookups. [[mac-mpo-cred-check-socket-visible]] ==== `mpo_check_socket_visible` [source,c] ---- int mpo_check_socket_visible(struct ucred *cred, struct socket *socket, struct label *socketlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`socket` |Object; socket | |`socketlabel` |Policy label for `socket` | |=== [[mac-mpo-cred-check-ifnet-relabel]] ==== `mpo_check_ifnet_relabel` [source,c] ---- int mpo_check_ifnet_relabel(struct ucred *cred, struct ifnet *ifnet, struct label *ifnetlabel, struct label *newlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`ifnet` |Object; network interface | |`ifnetlabel` |Existing policy label for `ifnet` | |`newlabel` |Policy label update to later be applied to `ifnet` | |=== Determine whether the subject credential can relabel the passed network interface to the passed label update. [[mac-mpo-cred-check-socket-relabel]] ==== `mpo_check_socket_relabel` [source,c] ---- int mpo_check_socket_relabel(struct ucred *cred, struct socket *socket, struct label *socketlabel, struct label *newlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`socket` |Object; socket | |`socketlabel` |Existing policy label for `socket` | |`newlabel` |Label update to later be applied to `socketlabel` | |=== Determine whether the subject credential can relabel the passed socket to the passed label update. [[mac-mpo-cred-check-cred-relabel]] ==== `mpo_check_cred_relabel` [source,c] ---- int mpo_check_cred_relabel(struct ucred *cred, struct label *newlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`newlabel` |Label update to later be applied to `cred` | |=== Determine whether the subject credential can relabel itself to the passed label update. [[mac-mpo-cred-check-vnode-relabel]] ==== `mpo_check_vnode_relabel` [source,c] ---- int mpo_check_vnode_relabel(struct ucred *cred, struct vnode *vp, struct label *vnodelabel, struct label *newlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential |Immutable |`vp` |Object; vnode |Locked |`vnodelabel` |Existing policy label for `vp` | |`newlabel` |Policy label update to later be applied to `vp` | |=== Determine whether the subject credential can relabel the passed vnode to the passed label update. [[mpo-cred-check-mount-stat]] ==== `mpo_check_mount_stat` [source,c] ---- int mpo_check_mount_stat(struct ucred *cred, struct mount *mp, struct label *mountlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`mp` |Object; file system mount | |`mountlabel` |Policy label for `mp` | |=== Determine whether the subject credential can see the results of a statfs performed on the file system. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatches or EPERM for lack of privilege. This call may be made in a number of situations, including during invocations of man:statfs[2] and related calls, as well as to determine what file systems to exclude from listings of file systems, such as when man:getfsstat[2] is invoked. [[mac-mpo-cred-check-proc-debug]] ==== `mpo_check_proc_debug` [source,c] ---- int mpo_check_proc_debug(struct ucred *cred, struct proc *proc); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential |Immutable |`proc` |Object; process | |=== Determine whether the subject credential can debug the passed process. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, EPERM for lack of privilege, or ESRCH to hide visibility of the target. This call may be made in a number of situations, including use of the man:ptrace[2] and man:ktrace[2] APIs, as well as for some types of procfs operations. [[mac-mpo-cred-check-vnode-access]] ==== `mpo_check_vnode_access` [source,c] ---- int mpo_check_vnode_access(struct ucred *cred, struct vnode *vp, struct label *label, int flags); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`vp` |Object; vnode | |`label` |Policy label for `vp` | |`flags` |man:access[2] flags | |=== Determine how invocations of man:access[2] and related calls by the subject credential should return when performed on the passed vnode using the passed access flags. This should generally be implemented using the same semantics used in `mpo_check_vnode_open`. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatches or EPERM for lack of privilege. [[mac-mpo-cred-check-vnode-chdir]] ==== `mpo_check_vnode_chdir` [source,c] ---- int mpo_check_vnode_chdir(struct ucred *cred, struct vnode *dvp, struct label *dlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`dvp` |Object; vnode to man:chdir[2] into | |`dlabel` |Policy label for `dvp` | |=== Determine whether the subject credential can change the process working directory to the passed vnode. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-check-vnode-chroot]] ==== `mpo_check_vnode_chroot` [source,c] ---- int mpo_check_vnode_chroot(struct ucred *cred, struct vnode *dvp, struct label *dlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`dvp` |Directory vnode | |`dlabel` |Policy label associated with `dvp` | |=== Determine whether the subject should be allowed to man:chroot[2] into the specified directory (`dvp`). [[mac-mpo-cred-check-vnode-create]] ==== `mpo_check_vnode_create` [source,c] ---- int mpo_check_vnode_create(struct ucred *cred, struct vnode *dvp, struct label *dlabel, struct componentname *cnp, struct vattr *vap); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`dvp` |Object; vnode | |`dlabel` |Policy label for `dvp` | |`cnp` |Component name for `dvp` | |`vap` |vnode attributes for `vap` | |=== Determine whether the subject credential can create a vnode with the passed parent directory, passed name information, and passed attribute information. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. This call may be made in a number of situations, including as a result of calls to man:open[2] with O_CREAT, man:mkfifo[2], and others. [[mac-mpo-cred-check-vnode-delete]] ==== `mpo_check_vnode_delete` [source,c] ---- int mpo_check_vnode_delete(struct ucred *cred, struct vnode *dvp, struct label *dlabel, struct vnode *vp, void *label, struct componentname *cnp); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`dvp` |Parent directory vnode | |`dlabel` |Policy label for `dvp` | |`vp` |Object; vnode to delete | |`label` |Policy label for `vp` | |`cnp` |Component name for `vp` | |=== Determine whether the subject credential can delete a vnode from the passed parent directory and passed name information. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. This call may be made in a number of situations, including as a result of calls to man:unlink[2] and man:rmdir[2]. Policies implementing this entry point should also implement `mpo_check_rename_to` to authorize deletion of objects as a result of being the target of a rename. [[mac-mpo-cred-check-vnode-deleteacl]] ==== `mpo_check_vnode_deleteacl` [source,c] ---- int mpo_check_vnode_deleteacl(struct ucred *cred, struct vnode *vp, struct label *label, acl_type_t type); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential |Immutable |`vp` |Object; vnode |Locked |`label` |Policy label for `vp` | |`type` |ACL type | |=== Determine whether the subject credential can delete the ACL of passed type from the passed vnode. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-cred-check-vnode-exec]] ==== `mpo_check_vnode_exec` [source,c] ---- int mpo_check_vnode_exec(struct ucred *cred, struct vnode *vp, struct label *label); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`vp` |Object; vnode to execute | |`label` |Policy label for `vp` | |=== Determine whether the subject credential can execute the passed vnode. Determination of execute privilege is made separately from decisions about any transitioning event. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mpo-cred-check-vnode-getacl]] ==== `mpo_check_vnode_getacl` [source,c] ---- int mpo_check_vnode_getacl(struct ucred *cred, struct vnode *vp, struct label *label, acl_type_t type); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`vp` |Object; vnode | |`label` |Policy label for `vp` | |`type` |ACL type | |=== Determine whether the subject credential can retrieve the ACL of passed type from the passed vnode. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-cred-check-vnode-getextattr]] ==== `mpo_check_vnode_getextattr` [source,c] ---- int mpo_check_vnode_getextattr(struct ucred *cred, struct vnode *vp, struct label *label, int attrnamespace, const char *name, struct uio *uio); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`vp` |Object; vnode | |`label` |Policy label for `vp` | |`attrnamespace` |Extended attribute namespace | |`name` |Extended attribute name | |`uio` |I/O structure pointer; see man:uio[9] | |=== Determine whether the subject credential can retrieve the extended attribute with the passed namespace and name from the passed vnode. Policies implementing labeling using extended attributes may be interested in special handling of operations on those extended attributes. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-check-vnode-link]] ==== `mpo_check_vnode_link` [source,c] ---- int mpo_check_vnode_link(struct ucred *cred, struct vnode *dvp, struct label *dlabel, struct vnode *vp, struct label *label, struct componentname *cnp); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`dvp` |Directory vnode | |`dlabel` |Policy label associated with `dvp` | |`vp` |Link destination vnode | |`label` |Policy label associated with `vp` | |`cnp` |Component name for the link being created | |=== Determine whether the subject should be allowed to create a link to the vnode `vp` with the name specified by `cnp`. [[mac-mpo-check-vnode-mmap]] ==== `mpo_check_vnode_mmap` [source,c] ---- int mpo_check_vnode_mmap(struct ucred *cred, struct vnode *vp, struct label *label, int prot); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`vp` |Vnode to map | |`label` |Policy label associated with `vp` | |`prot` |Mmap protections (see man:mmap[2]) | |=== Determine whether the subject should be allowed to map the vnode `vp` with the protections specified in `prot`. [[mac-mpo-check-vnode-mmap-downgrade]] ==== `mpo_check_vnode_mmap_downgrade` [source,c] ---- void mpo_check_vnode_mmap_downgrade(struct ucred *cred, struct vnode *vp, struct label *label, int *prot); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |See <>. | |`vp` | | |`label` | | |`prot` |Mmap protections to be downgraded | |=== Downgrade the mmap protections based on the subject and object labels. [[mac-mpo-check-vnode-mprotect]] ==== `mpo_check_vnode_mprotect` [source,c] ---- int mpo_check_vnode_mprotect(struct ucred *cred, struct vnode *vp, struct label *label, int prot); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`vp` |Mapped vnode | |`prot` |Memory protections | |=== Determine whether the subject should be allowed to set the specified memory protections on memory mapped from the vnode `vp`. [[mac-mpo-check-vnode-poll]] ==== `mpo_check_vnode_poll` [source,c] ---- int mpo_check_vnode_poll(struct ucred *active_cred, struct ucred *file_cred, struct vnode *vp, struct label *label); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`active_cred` |Subject credential | |`file_cred` |Credential associated with the struct file | |`vp` |Polled vnode | |`label` |Policy label associated with `vp` | |=== Determine whether the subject should be allowed to poll the vnode `vp`. [[mac-mpo-check-vnode-rename-from]] ==== `mpo_check_vnode_rename_from` [source,c] ---- int mpo_vnode_rename_from(struct ucred *cred, struct vnode *dvp, struct label *dlabel, struct vnode *vp, struct label *label, struct componentname *cnp); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`dvp` |Directory vnode | |`dlabel` |Policy label associated with `dvp` | |`vp` |Vnode to be renamed | |`label` |Policy label associated with `vp` | |`cnp` |Component name for `vp` | |=== Determine whether the subject should be allowed to rename the vnode `vp` to something else. [[mac-mpo-check-vnode-rename-to]] ==== `mpo_check_vnode_rename_to` [source,c] ---- int mpo_check_vnode_rename_to(struct ucred *cred, struct vnode *dvp, struct label *dlabel, struct vnode *vp, struct label *label, int samedir, struct componentname *cnp); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`dvp` |Directory vnode | |`dlabel` |Policy label associated with `dvp` | |`vp` |Overwritten vnode | |`label` |Policy label associated with `vp` | |`samedir` |Boolean; `1` if the source and destination directories are the same | |`cnp` |Destination component name | |=== Determine whether the subject should be allowed to rename to the vnode `vp`, into the directory `dvp`, or to the name represented by `cnp`. If there is no existing file to overwrite, `vp` and `label` will be NULL. [[mac-mpo-cred-check-socket-listen]] ==== `mpo_check_socket_listen` [source,c] ---- int mpo_check_socket_listen(struct ucred *cred, struct socket *socket, struct label *socketlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`socket` |Object; socket | |`socketlabel` |Policy label for `socket` | |=== Determine whether the subject credential can listen on the passed socket. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-cred-check-vnode-lookup]] ==== `mpo_check_vnode_lookup` [source,c] ---- int mpo_check_vnode_lookup(struct ucred *cred, struct vnode *dvp, struct label *dlabel, struct componentname *cnp); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`dvp` |Object; vnode | |`dlabel` |Policy label for `dvp` | |`cnp` |Component name being looked up | |=== Determine whether the subject credential can perform a lookup in the passed directory vnode for the passed name. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-cred-check-vnode-open]] ==== `mpo_check_vnode_open` [source,c] ---- int mpo_check_vnode_open(struct ucred *cred, struct vnode *vp, struct label *label, int acc_mode); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`vp` |Object; vnode | |`label` |Policy label for `vp` | |`acc_mode` |man:open[2] access mode | |=== Determine whether the subject credential can perform an open operation on the passed vnode with the passed access mode. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-cred-check-vnode-readdir]] ==== `mpo_check_vnode_readdir` [source,c] ---- int mpo_check_vnode_readdir(struct ucred *cred, struct vnode *dvp, struct label *dlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`dvp` |Object; directory vnode | |`dlabel` |Policy label for `dvp` | |=== Determine whether the subject credential can perform a `readdir` operation on the passed directory vnode. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-cred-check-vnode-readlink]] ==== `mpo_check_vnode_readlink` [source,c] ---- int mpo_check_vnode_readlink(struct ucred *cred, struct vnode *vp, struct label *label); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`vp` |Object; vnode | |`label` |Policy label for `vp` | |=== Determine whether the subject credential can perform a `readlink` operation on the passed symlink vnode. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. This call may be made in a number of situations, including an explicit `readlink` call by the user process, or as a result of an implicit `readlink` during a name lookup by the process. [[mac-mpo-cred-check-vnode-revoke]] ==== `mpo_check_vnode_revoke` [source,c] ---- int mpo_check_vnode_revoke(struct ucred *cred, struct vnode *vp, struct label *label); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`vp` |Object; vnode | |`label` |Policy label for `vp` | |=== Determine whether the subject credential can revoke access to the passed vnode. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-cred-check-vnode-setacl]] ==== `mpo_check_vnode_setacl` [source,c] ---- int mpo_check_vnode_setacl(struct ucred *cred, struct vnode *vp, struct label *label, acl_type_t type, struct acl *acl); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`vp` |Object; vnode | |`label` |Policy label for `vp` | |`type` |ACL type | |`acl` |ACL | |=== Determine whether the subject credential can set the passed ACL of passed type on the passed vnode. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-cred-check-vnode-setextattr]] ==== `mpo_check_vnode_setextattr` [source,c] ---- int mpo_check_vnode_setextattr(struct ucred *cred, struct vnode *vp, struct label *label, int attrnamespace, const char *name, struct uio *uio); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`vp` |Object; vnode | |`label` |Policy label for `vp` | |`attrnamespace` |Extended attribute namespace | |`name` |Extended attribute name | |`uio` |I/O structure pointer; see man:uio[9] | |=== Determine whether the subject credential can set the extended attribute of passed name and passed namespace on the passed vnode. Policies implementing security labels backed into extended attributes may want to provide additional protections for those attributes. Additionally, policies should avoid making decisions based on the data referenced from `uio`, as there is a potential race condition between this check and the actual operation. The `uio` may also be `NULL` if a delete operation is being performed. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-cred-check-vnode-setflags]] ==== `mpo_check_vnode_setflags` [source,c] ---- int mpo_check_vnode_setflags(struct ucred *cred, struct vnode *vp, struct label *label, u_long flags); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`vp` |Object; vnode | |`label` |Policy label for `vp` | |`flags` |File flags; see man:chflags[2] | |=== Determine whether the subject credential can set the passed flags on the passed vnode. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-cred-check-vnode-setmode]] ==== `mpo_check_vnode_setmode` [source,c] ---- int mpo_check_vnode_setmode(struct ucred *cred, struct vnode *vp, struct label *label, mode_t mode); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`vp` |Object; vnode | |`label` |Policy label for `vp` | |`mode` |File mode; see man:chmod[2] | |=== Determine whether the subject credential can set the passed mode on the passed vnode. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-cred-check-vnode-setowner]] ==== `mpo_check_vnode_setowner` [source,c] ---- int mpo_check_vnode_setowner(struct ucred *cred, struct vnode *vp, struct label *label, uid_t uid, gid_t gid); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`vp` |Object; vnode | |`label` |Policy label for `vp` | |`uid` |User ID | |`gid` |Group ID | |=== Determine whether the subject credential can set the passed uid and passed gid as file uid and file gid on the passed vnode. The IDs may be set to (`-1`) to request no update. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-cred-check-vnode-setutimes]] ==== `mpo_check_vnode_setutimes` [source,c] ---- int mpo_check_vnode_setutimes(struct ucred *cred, struct vnode *vp, struct label *label, struct timespec atime, struct timespec mtime); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`vp` |Object; vp | |`label` |Policy label for `vp` | |`atime` |Access time; see man:utimes[2] | |`mtime` |Modification time; see man:utimes[2] | |=== Determine whether the subject credential can set the passed access timestamps on the passed vnode. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-cred-check-proc-sched]] ==== `mpo_check_proc_sched` [source,c] ---- int mpo_check_proc_sched(struct ucred *ucred, struct proc *proc); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`proc` |Object; process | |=== Determine whether the subject credential can change the scheduling parameters of the passed process. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, EPERM for lack of privilege, or ESRCH to limit visibility. See man:setpriority[2] for more information. [[mac-mpo-cred-check-proc-signal]] ==== `mpo_check_proc_signal` [source,c] ---- int mpo_check_proc_signal(struct ucred *cred, struct proc *proc, int signal); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`proc` |Object; process | |`signal` |Signal; see man:kill[2] | |=== Determine whether the subject credential can deliver the passed signal to the passed process. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, EPERM for lack of privilege, or ESRCH to limit visibility. [[mac-mpo-cred-check-vnode-stat]] ==== `mpo_check_vnode_stat` [source,c] ---- int mpo_check_vnode_stat(struct ucred *cred, struct vnode *vp, struct label *label); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`vp` |Object; vnode | |`label` |Policy label for `vp` | |=== Determine whether the subject credential can `stat` the passed vnode. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. See man:stat[2] for more information. [[mac-mpo-cred-check-ifnet-transmit]] ==== `mpo_check_ifnet_transmit` [source,c] ---- int mpo_check_ifnet_transmit(struct ucred *cred, struct ifnet *ifnet, struct label *ifnetlabel, struct mbuf *mbuf, struct label *mbuflabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`ifnet` |Network interface | |`ifnetlabel` |Policy label for `ifnet` | |`mbuf` |Object; mbuf to be sent | |`mbuflabel` |Policy label for `mbuf` | |=== Determine whether the network interface can transmit the passed mbuf. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-cred-check-socket-deliver]] ==== `mpo_check_socket_deliver` [source,c] ---- int mpo_check_socket_deliver(struct ucred *cred, struct ifnet *ifnet, struct label *ifnetlabel, struct mbuf *mbuf, struct label *mbuflabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`ifnet` |Network interface | |`ifnetlabel` |Policy label for `ifnet` | |`mbuf` |Object; mbuf to be delivered | |`mbuflabel` |Policy label for `mbuf` | |=== Determine whether the socket may receive the datagram stored in the passed mbuf header. Return 0 for success, or an `errno` value for failure. Suggested failures: EACCES for label mismatch, or EPERM for lack of privilege. [[mac-mpo-check-socket-visible]] ==== `mpo_check_socket_visible` [source,c] ---- int mpo_check_socket_visible(struct ucred *cred, struct socket *so, struct label *socketlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential |Immutable |`so` |Object; socket | |`socketlabel` |Policy label for `so` | |=== Determine whether the subject credential cred can "see" the passed socket (`socket`) using system monitoring functions, such as those employed by man:netstat[8] and man:sockstat[1]. Return 0 for success, or an `errno` value for failure. Suggested failure: EACCES for label mismatches, EPERM for lack of privilege, or ESRCH to hide visibility. [[mac-mpo-check-system-acct]] ==== `mpo_check_system_acct` [source,c] ---- int mpo_check_system_acct(struct ucred *ucred, struct vnode *vp, struct label *vlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`ucred` |Subject credential | |`vp` |Accounting file; man:acct[5] | |`vlabel` |Label associated with `vp` | |=== Determine whether the subject should be allowed to enable accounting, based on its label and the label of the accounting log file. [[mac-mpo-check-system-nfsd]] ==== `mpo_check_system_nfsd` [source,c] ---- int mpo_check_system_nfsd(struct ucred *cred); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |=== Determine whether the subject should be allowed to call man:nfssvc[2]. [[mac-mpo-check-system-reboot]] ==== `mpo_check_system_reboot` [source,c] ---- int mpo_check_system_reboot(struct ucred *cred, int howto); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`howto` |`howto` parameter from man:reboot[2] | |=== Determine whether the subject should be allowed to reboot the system in the specified manner. [[mac-mpo-check-system-settime]] ==== `mpo_check_system_settime` [source,c] ---- int mpo_check_system_settime(struct ucred *cred); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |=== Determine whether the user should be allowed to set the system clock. [[mac-mpo-check-system-swapon]] ==== `mpo_check_system_swapon` [source,c] ---- int mpo_check_system_swapon(struct ucred *cred, struct vnode *vp, struct label *vlabel); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`vp` |Swap device | |`vlabel` |Label associated with `vp` | |=== Determine whether the subject should be allowed to add `vp` as a swap device. [[mac-mpo-check-system-sysctl]] ==== `mpo_check_system_sysctl` [source,c] ---- int mpo_check_system_sysctl(struct ucred *cred, int *name, u_int *namelen, void *old, size_t *oldlenp, int inkernel, void *new, size_t newlen); ---- [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Parameter | Description | Locking |`cred` |Subject credential | |`name` |See man:sysctl[3] | |`namelen` | | |`old` | | |`oldlenp` | | |`inkernel` |Boolean; `1` if called from kernel | |`new` |See man:sysctl[3] | |`newlen` | | |=== Determine whether the subject should be allowed to make the specified man:sysctl[3] transaction. [[mac-label-management]] === Label Management Calls Relabel events occur when a user process has requested that the label on an object be modified. A two-phase update occurs: first, an access control check will be performed to determine if the update is both valid and permitted, and then the update itself is performed via a separate entry point. Relabel entry points typically accept the object, object label reference, and an update label submitted by the process. Memory allocation during relabel is discouraged, as relabel calls are not permitted to fail (failure should be reported earlier in the relabel check). [[mac-userland-arch]] == Userland Architecture The TrustedBSD MAC Framework includes a number of policy-agnostic elements, including MAC library interfaces for abstractly managing labels, modifications to the system credential management and login libraries to support the assignment of MAC labels to users, and a set of tools to monitor and modify labels on processes, files, and network interfaces. More details on the user architecture will be added to this section in the near future. [[mac-userland-labels]] === APIs for Policy-Agnostic Label Management The TrustedBSD MAC Framework provides a number of library and system calls permitting applications to manage MAC labels on objects using a policy-agnostic interface. This permits applications to manipulate labels for a variety of policies without being written to support specific policies. These interfaces are used by general-purpose tools such as man:ifconfig[8], man:ls[1] and man:ps[1] to view labels on network interfaces, files, and processes. The APIs also support MAC management tools including man:getfmac[8], man:getpmac[8], man:setfmac[8], man:setfsmac[8], and man:setpmac[8]. The MAC APIs are documented in man:mac[3]. Applications handle MAC labels in two forms: an internalized form used to return and set labels on processes and objects (`mac_t`), and externalized form based on C strings appropriate for storage in configuration files, display to the user, or input from the user. Each MAC label contains a number of elements, each consisting of a name and value pair. Policy modules in the kernel bind to specific names and interpret the values in policy-specific ways. In the externalized string form, labels are represented by a comma-delimited list of name and value pairs separated by the `/` character. Labels may be directly converted to and from text using provided APIs; when retrieving labels from the kernel, internalized label storage must first be prepared for the desired label element set. Typically, this is done in one of two ways: using man:mac_prepare[3] and an arbitrary list of desired label elements, or one of the variants of the call that loads a default element set from the man:mac.conf[5] configuration file. Per-object defaults permit application writers to usefully display labels associated with objects without being aware of the policies present in the system. [NOTE] ==== Currently, direct manipulation of label elements other than by conversion to a text string, string editing, and conversion back to an internalized label is not supported by the MAC library. Such interfaces may be added in the future if they prove necessary for application writers. ==== [[mac-userland-credentials]] === Binding of Labels to Users The standard user context management interface, man:setusercontext[3], has been modified to retrieve MAC labels associated with a user's class from man:login.conf[5]. These labels are then set along with other user context when either `LOGIN_SETALL` is specified, or when `LOGIN_SETMAC` is explicitly specified. [NOTE] ==== It is expected that, in a future version of FreeBSD, the MAC label database will be separated from the [.filename]#login.conf# user class abstraction, and be maintained in a separate database. However, the man:setusercontext[3] API should remain the same following such a change. ==== [[mac-conclusion]] == Conclusion The TrustedBSD MAC framework permits kernel modules to augment the system security policy in a highly integrated manner. They may do this based on existing object properties, or based on label data that is maintained with the assistance of the MAC framework. The framework is sufficiently flexible to implement a variety of policy types, including information flow security policies such as MLS and Biba, as well as policies based on existing BSD credentials or file protections. Policy authors may wish to consult this documentation as well as existing security modules when implementing a new security service. diff --git a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc index 742bfca9ec..aea9559762 100644 --- a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc +++ b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc @@ -1,5371 +1,5373 @@ --- 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 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 <>. [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 <>. ==== [[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 man:pkg-version[8]'s `-t` argument to check if the new version is greater or lesser than before. See <>. ==== [[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 <>. [[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 <>. 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 <>. 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 <> (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 <>. ==== 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 <> 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 <> 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]#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 <>). 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.) If you are the maintainer and/or submitter, respectively, mention that as it may help 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 variable you created, 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 <> 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 <> 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 <> for details on 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 <> for details on 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 <>. 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 <>. `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 <> ==== 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 <>, 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 <> 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 <> and <>. Multiple values are added to `GL_SITE`, `GL_ACCOUNT`, `GL_PROJECT` and `GL_COMMIT`. Each different value is assigned a group. <>. `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 <> ==== 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 <>. 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 <>, 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 <>, 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! Now that you have the idea, 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 <>. 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 <>. [[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 <>. [[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 <>). Furthermore, `DEFAULT` is a special purpose word (check item <>). . 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 `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 <>). + 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 (`,`). + 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: .. 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 <> and <>. + [[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 <>. + [[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 <>. + [[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 <>. + [[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 <>. ** `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 <> 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`. [[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 your 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 <>, 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 <>), 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 <>. 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 will be removed, as well as all the ports depending on it, after the build and they will ever end up being 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 <>, 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]. 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 <>. 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 <> 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 <>. + For more complex usage, see <>. `CONFIGURE_ARGS`:: For `--enable-_x_` and `--disable-_x_`, see <>. + For `--with-_x_` and `--without-_x_`, see <>. + For all other cases, see <>. `CMAKE_ARGS`:: For arguments that are booleans (`on`, `off`, `true`, `false`, `0`, `1`) see <>. + For all other cases, see <>. `MESON_ARGS`:: For arguments that take `true` or `false`, see <>. + For arguments that take `yes` or `no`, use <>. + For arguments that take `enabled` or `disabled`, see <>. + For all other cases, use <>. `QMAKE_ARGS`:: See <>. `USE_*`:: See <>. `*_DEPENDS`:: See <>. `*` (Any variable):: The most used variables have direct helpers, see <>. + For any variable without a specific helper, see <>. Options dependencies:: When an option need another option to work, see <>. Options conflicts:: When an option cannot work if another is also enabled, see <>. Build targets:: When an option need some extra processing, see <>. [[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 <> and <> 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 <> 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 <> 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 <>. ==== 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 <>) 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 <>. 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. ==== diff --git a/documentation/content/es/books/handbook/install/_index.adoc b/documentation/content/es/books/handbook/install/_index.adoc index 5ae2ab0732..9709108b79 100644 --- a/documentation/content/es/books/handbook/install/_index.adoc +++ b/documentation/content/es/books/handbook/install/_index.adoc @@ -1,2648 +1,2651 @@ --- title: Capítulo 2. Instalación de FreeBSD part: Parte I. Primeros pasos prev: books/handbook/introduction next: books/handbook/basics showBookMenu: true weight: 4 path: "/books/handbook/install/" --- [[bsdinstall]] = Instalación de FreeBSD :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 2 :partnums: :source-highlighter: rouge :experimental: :images-path: books/handbook/install/ 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::[] [[install-synopsis]] == Sinopsis FreeBSD dispone de un programa en modo texto muy fácil de usar llamado sysinstall. Es el programa de instalación por omisión en FreeBSD, pero quien decida distribuir FreeBSD tiene todo el derecho de facilitar un sistema de instalación propio si así lo desea. Este capítulo trata sobre cómo usar sysinstall para instalar FreeBSD Tras leer este capítulo sabrá usted: * Cómo crear los discos de instalación de FreeBSD * Cómo interpreta (y subdivide) FreeBSD sus discos duros. * Cómo arrancar sysinstall. * Qué preguntas le hará sysinstall, qué significan y cómo responderlas. Antes de leer este capítulo debería usted: * Leer la lista de hardware soportado que se suministra con la con la versión de FreeBSD que va a instalar y verificar que su hardware está en dicha lista. [NOTE] ==== En general éstas instrucciones de instalación han sido escritas para computadoras de arquitectura i386(TM) («PC compatible»). En algunos puntos concretos se darán instrucciones específicas para otras plataformas (por ejemplo Alpha). A pesar de que esta guía se intenta mantener todo lo al día que es posible puede que se encuentre con pequeñas diferencias entre el programa de instalación y lo que aquí se le muestra. Le sugerimos que use este capítulo como una guía general más que como un manual literal de instalación. ==== [[install-hardware]] == Requisitos de hardware [[install-hardware-minimal]] === Configuración mínima La configuración mínima para instalar FreeBSD varía según la versión de FreeBSD y la arquitectura de hardware. Tiene información sobre la confuración mínima en las Notas de Instalación que encontrará en la sección de http://www.FreeBSD.org/releases/index.html[Información de Releases] del sitio web de FreeBSD. En la siguiente sección se facilita un resumen de dicha información. Dependiendo de cuál sea el método de instalación que elija para instalar FreeBSD necesitará un floppy, un lector de CDROM que pueda utilizar con FreeBSD o quizás un adaptador de red. Todo esto se explica en la <>. ==== FreeBSD/i386 y FreeBSD/pc98 Tanto FreeBSD/i386 como FreeBSD/pc98 necesitan un procesador 486 o superior y un mínimo de 24 MB de RAM. Necesitará también al menos 150 MB de espacio libre en disco, que es lo que necesita la instalación mínima. [NOTE] ==== En sistemas muy antiguos la mayoría de las veces será de mucha más ayuda conseguir más RAM y espacio de disco que un procesador más rápido. ==== ==== FreeBSD/alpha Para instalar FreeBSD/alpha necesitará una plataforma que esté soportada (consulte <>) y un disco duro dedicado a FreeBSD. En este momento no es posible compartir un disco con otro sistema operativo. Este disco debe estar necesariamente conectado a una controladora SCSI que esté soportada por el firmware SRM, o si se trata de un disco IDE el SRM de su máquina debe permitir el arranque desde discos IDE. Necesitará el firmware de la consola SRM de su plataforma. En ciertos casos es posible pasar del firmware AlphaBIOS (o ARC) al SRM. En otros casos no habrá más remedio que descargar un nuevo firmware desde el sito web del fabricante. [NOTE] ==== A partir de FreeBSD 7.0 no hay soporte para Alpha. La serie FreeBSD 6._X_ es la última que ofrece soporte para esta arquitectura. ==== ==== FreeBSD/amd64 Hay dos tipos de procesadores capaces de ejecutar FreeBSD/amd64. La primera son los procesadores AMD64, entre los que están los AMD Athlon(TM)64, AMD Athlon(TM)64-FX, AMD Opteron(TM) y los modelos superiores. La segunda categoría de procesadores que pueden usar FreeBSD/amd64 es la de los procesadores de arquitectura EM64T de Intel(R), por ejemplo las familias de procesadores Intel(R) Core(TM) 2 Duo, Quad, y Extreme, y la secuencia de procesadores Intel(R) Xeon(TM) 3000, 5000 y 7000. Si tiene una máquina basada en una nVidia nForce3 Pro-150 _tendrá que usar la configuración de la BIOS_ para deshabilitar IO ACPI. Si no tiene la opción de hacerlo tendrá que deshabilitar ACPI. Hay errores en el chipset Pro-150 para los que no hemos encontrado aún una solución. ==== FreeBSD/sparc64 Para instalar FreeBSD/sparc64 necesita una plataforma que esté soportada (consulte la <>). Necesitará un disco dedicado a FreeBSD/sparc64. De momento es imposible compartir un disco duro con otro sistema operativo. [[install-hardware-supported]] === Hardware soportado Cada versión de FreeBSD incluye una lista de hardware soportado en las «FreeBSD Hardware Notes». Este documento suele estar en un fichero llamado [.filename]#HARDWARE.TXT#, que está en el directorio raiz del CDROM o distribución FTP, o en el menú de documentación de sysinstall. En este documento se listan los dispositivos de hardware que se sabe que funcionan con cada versión de FreeBSD y para qué arquitectura. En la página de http://www.FreeBSD.org/releases/[Información de Releases] del sitio web de FreeBSD encontrará copias de esta lista para diversas releases y arquitecturas. [[install-pre]] == Tareas anteriores a la instalación [[install-inventory]] === Inventario de su sistema Antes de instalar FreeBSD en su sistema debería hacer un inventario de los componentes de su computadora. El sistema de instalación de FreeBSD le mostrará los componentes (discos duros, tarjetas de red, unidades de CDROM, etc.) con sus datos de modelo y fabricante. FreeBSD tratará también de determinar la configuración correcta para dichos dispositivos, lo que incluye información sobre las IRQ y el uso de puertos IO. A causa de la ingente variedad de hardware para PC este proceso no siempre se puede culminar con éxito y es posible que deba corregir las decisiones de FreeBSD retocando la configuración. Si ya dispone de otro sistema operativo instalado (como Windows(R) o Linux) puede usar los recursos que dicho o dichos sistemas operativos le faciliten para determinar exactamente qué hardware tiene y cómo está configurado. Si tiene del todo claro qué configuración está usando una tarjeta de expasión concreta es posible que pueda encontrar esos datos impresos en la propia tarjeta. Es muy habitual el uso de las IRQ 3, 5 y 7 y las direcciones de los puertos IO suelen representarse con números hexadecimales, como 0x330. Le recomendamos imprimir o tomar nota de todos esos datos antes de instalar FreeBSD. Una tabla como esta puede serle de mucha ayuda: .Ejemplo de inventario de dispositivos [cols="1,1,1,1", frame="none", options="header"] |=== | Nombre de dispositivo | IRQ | Puerto(s) IO | Notas |Primer disco duro |N/A |N/A |40 GB, fabricado por Seagate, primer maestro IDE |CDROM |N/A |N/A |Primer esclavo IDE |Segundo disco duro |N/A |N/A |20 GB, fabricado por IBM, segundo maestro IDE |Primera controladora IDE |14 |0x1f0 | |Tarjeta de red |N/A |N/A |Intel(R) 10/100 |Módem |N/A |N/A |3Com(R) 56K faxmodem, en COM1 +|... +|... +|... |... |=== Una vez termine el inventorio de componentes de su sistema debe comprobar si aparecen en la lista de hardware soportado de la versión de FreeBSD que vaya a instalar. === Haga una copia de seguridad de sus datos Si la máquina en la que va a instalar FreeBSD contiene datos que desea conservar por algún motivo asegúrese de haber hecho una copia de seguridad de los mismos y de que esa copia es de fiar antes de instalar FreeBSD. El sistema de instalación de FreeBSD le mostrará una advertencia antes de modificar datos en su disco pero una vez que el proceso ha comenzado no hay manera de dar marcha atrás. [[install-where]] === Decida dónde instalar FreeBSD Si quiere que FreeBSD use todo su disco duro puede saltar tranquilamente a la siguiente sección. Si por el contrario necesita que FreeBSD coexista con otros sistemas operativos tendrá que comprender cómo se almacenan los datos en el disco duro y cómo le afecta esto. [[install-where-i386]] ==== Esquemas de disco en FreeBSD/i386(TM) Un disco de PC puede dividirse en varias partes. Estas partes reciben el nombre de _partitions_. Dado que FreeBSD internamente también tiene particiones la nomenclatura puede ser confusa muy rápidamente, así que estas partes del disco reciben el nombre de «disk slices» o sencillamente «slices» («rebanadas de disco»y «rebanadas» respectivamente). Por ejemplo, la versión de `fdisk` que usará FreeBSD con las particiones de disco de PC usa la palabra «slices» en lugar de «partitions». Debido a limitaciones de diseño la plataforma PC sólo admite cuatro particiones por disco. Dichas particiones reciben el nombre de _particiones primarias_. Esta limitación puede sortearse (y de ese modo disponer de más de cuatro particiones) gracias a que se creó un nuevo tipo de partición, las _particiones extendidas_. Un disco puede contener una única partición extendida. Dentro de ella pueden crearse particiones especiales, que reciben el nombre de _particiones lógicas_. Cada partición tiene un _identificador de partición_ (o _partition ID_), que es un número que se usa para identificar el tipo de datos que alberga la partición. Las particiones FreeBSD tienen como identificador de partición `165`. Normalmente cada sistema operativo que vaya a utilizar identificará las particiones de un modo propio. Por ejemplo DOS (y sus descendientes, como Windows(R)) asignan a cada partición primaria y lógica una _letra de unidad_ a partir de [.filename]#C:#. FreeBSD debe instalarse en una partición primaria. FreeBSD puede albergar todos los datos que necesita, incluyendo cualquier fichero que pueda usted crear, en esta partición. Si tiene usted varios discos duros puede crear particiones para que FreeBSD las use en todos ellos o en algunos nada más. Al instalar FreeBSD debe usar al menos una partición. Puede usar una partición vacía que haya preparado o puede usar también una partición que contenga datos que no desea conservar. Si está usando todas las particiones de todos sus discos tendrá que dejar libre una de ellas para FreeBSD usando las herramientas del otro sistema operativo que esté usando (por ejemplo `fdisk` en DOS o en Windows(R)). Si tiene una partición sobrante puede usarla, pero puede verse en la necesidad de reducir una o más de las particiones que está usando. Una instalación mínima de FreeBSD cabrí en sólo 100 MB de disco pero tenga en cuenta que apenas quedaría espacio para los ficheros que quiera crear. Un mínimo más realista sería de 250 MB si no pretende usar entorno gráfico y 350 MB o más si quiere usar un interfaz gráfico de usuario. Si quiere instalar gran cantidad de software para usarlo en FreeBSD sin duda necesitará más espacio. Para ello puede usar herramientas comerciales como PartitionMagic(R) o libres como GParted para redimensionar sus particiones y hacer sitio para FreeBSD. El directorio [.filename]#tools# directory del CDROM de instalación contiene dos herramientas libres con las que puede hacer hacer esta redimensión: FIPS y PResizer. En el mismo directorio encontrará documentación de ambas. FIPS, PResizer y PartitionMagic(R) pueden redimensionar particiones FAT16 y FAT32, que pueden encontrarse desde MS-DOS(R) hasta Windows(R) ME. Tanto PartitionMagic(R) como GParted funcionan también en particiones NTFS. GParted forma parte de diversas distribuciones de «Live CD» de Linux, como http://www.sysresccd.org/[SystemRescueCD]. Hay informes de problemas redimensionando particiones de Microsoft(R) Vista. Le recomendamos tener a mano un disco de instalación de Vista cuando intente hacer esto. Lo dicho para cualquier otra tarea de mantenimiento de discos es válido aquí: tenga una copia de seguridad _fiable_ y reciente a mano. [WARNING] ==== El uso incorrecto de estas herramientas puede borrar datos de su disco duro. Recuerde, asegúrese de disponer de copias de seguridad recientes y utilizables antes de usarlas. ==== .Uso de una partición sin cambiar nada [example] ==== Supongamos que tiene una máquina con un sólo disco de 4 GB que ya tiene una versión de Windows(R) instalada y que ese disco está dividido en dos unidades, [.filename]#C:# y [.filename]#D:#, cada una de las cuales tiene un tamaño de 2 GB. Tiene 1 GB de datos en [.filename]#C:# y 0.5 GB de datos en [.filename]#D:#. Esto significa que su disco duro tiene dos particiones, una por cada letra de unidad. Copie todos sus datos de [.filename]#D:# en [.filename]#C:#; de este modo vaciará la segunda partició y podrá usarla con FreeBSD. ==== .Reducir una partición existente [example] ==== Suponga que tiene una máquina con un sólo disco de 4 GB que contiene una versión de Windows(R) instalada. Cuando instaló Windows(R) creó una gran partición, lo que le dió como resultado una unidad [.filename]#C:# de 4 GB. Está usando 1.5 GB de espacio y quiere que FreeBSD tenga 2 GB de espacio. Para poder instalar FreeBSD tendrá que realizar una de las siguientes tareas: . Haga una copia de sus datos de Windows(R) y después reinstale Windows(R), eligiendo una partición de 2 GB en el momento de la instalación. . Utilice alguna herramienta del estilo de PartitionMagic(R) que se han descrito antes para reducir el tamaño de su partición de Windows(R). ==== ==== Estructura de discos en Alpha Tendrá que dedicar un disco de su sistema para usar FreeBSD puesto que de momento es imposible compartir un disco con otro sistema operativo. Dependiendo de la la máquina Alpha que tenga el disco podrá ser SCSI o IDE en la medida en que sea posible arrancar desde tales discos. Siguiendo las normas de los manuales de Digital / Compaq todos los datos suministrados a SRM se muestran en mayúsculas. SRM no distingue entre mayúsculas y minúsculas. Use `SHOW DEVICE` en la consola de SRM para saber qué tipo de discos hay en su sistema: [source,shell] .... >>>SHOW DEVICE dka0.0.0.4.0 DKA0 TOSHIBA CD-ROM XM-57 3476 dkc0.0.0.1009.0 DKC0 RZ1BB-BS 0658 dkc100.1.0.1009.0 DKC100 SEAGATE ST34501W 0015 dva0.0.0.0.1 DVA0 ewa0.0.0.3.0 EWA0 00-00-F8-75-6D-01 pkc0.7.0.1009.0 PKC0 SCSI Bus ID 7 5.27 pqa0.0.0.4.0 PQA0 PCI EIDE pqb0.0.1.4.0 PQB0 PCI EIDE .... Este ejemplo es de una Digital Personal Workstation 433au y muestra tres discos instalados en el sistema. El primer disco es una unidad CDROM llamada [.filename]#DKA0# y los otros dos reciben los nombres de [.filename]#DKC0# y [.filename]#DKC100# respectivamente. Los discos con nombres tipo [.filename]#DKx# son discos SCSI. Por ejemplo [.filename]#DKA100# se refiere a un disco SCSI con el «target ID 1» en el primer bus SCSI (A), mientras que [.filename]#DKC300# es un disco SCSI con un ID 3 en el tercer bus SCSI (C). Los nombres de dispositivo [.filename]#PKx# son para adaptadores de bus SCSI. Como hemos visto en la salida de `SHOW DEVICE` las unidades CDROM SCSI son consideradas iguales a otros discos duros SCSI. Los discos IDE tienen nombres similares a [.filename]#DQx#, mientras que [.filename]#PQx# es la controladora IDE asociada. === Recopile los datos de la configuración de la red Si pretende conectarse a alguna red durante la instalación de FreeBSD (por ejemplo si pretende hacerlo desde un sitio FTP o mediante un servidor NFS) tendrá que conocer la configuración de su red. Durante la instalación se le pedirán esos datos para que FreeBSD pueda conectarse a la red y realizar la instalación. ==== Conexión a una red Ethernet o a un módem Cable/DSL Necesitará la siguiente información si va a conectarse a una red Ethernet o si tiene una conexión a Internet a través de una adaptador Ethernet via cable o DSL: . Dirección IP . Dirección IP de la pasarela («gateway», «puerta de enlace») . Nombre del sistema («hostname») . Dirección IP del servidor DNS . Máscara de subred Si no conoce estos datos póngase en contacto con su administrador de sistemas o con su proveedor de servicios. Es que le digan que tal información se asigna automáticamente mediante _DHCP_. Si es así, anótelo. ==== Conexión mediante módem Si usted se conecta con su ISP mediante un módem tradicional sigue pudiendo instalar FreeBSD a través de Internet; el problema es que tardará mucho más que por otros medios. Necesitará saber: . El número de teléfono de su ISP a través del que accederá a Internet . El COM: el puerto al que está conectado su módem . Su nombre de usuario y su contraseña de acceso a Internet === Consulte «FreeBSD Errata» A pesar de que el proyecto FreeBSD hace todo lo humanamente posible para asegurarse de que cada «release» de FreeBSD es todo lo estable posible a veces algún error logra entrar en escena. En contadísimas ocasiones esos errores llegan a afectar al proceso de instalación. Cuando esos errores son ubicados y corregidos aparecen en lo que llamamos la http://www.FreeBSD.org/releases/{rel120-current}r/errata/[FreeBSD Errata], que encontrará en el sitio web de FreeBSD. Debería consultar este texto antes de la instalación para asegurarse de que no hay problemas de última hora de los que deba preocuparse. Tiene información sobre las «releases», incluyendo la «errata» de cada una de ellas, en la http://www.FreeBSD.org/releases/[sección de información de «releases» ] del http://www.FreeBSD.org/[sitio web de FreeBSD]. === Obtención de los ficheros de instalación de FreeBSD El proceso de instalación de FreeBSD permite instalar FreeBSD desde ficheros ubicados en cualquiera de los siguientes sitios: .Medios locales * Un CDROM o DVD * Una partición DOS en la propia computadora * Una cinta SCSI o QIC * Discos floppy .Red * Un sitio FTP, saliendo a través de un cortafuegos o usando un proxy HTTP si fuera necesario * Un servidor NFS * Una conexión serie o a través de una cable paralelo Si ha adquirido FreeBSD en CD o DVD ya tiene todo lo que necesitará, puede pasar a la siguiente sección: (<>). Si no dispone de los ficheros de instalación de FreeBSD debería consultar la <>, donde se explica cómo preparar la instalación de FreeBSD desde cualquiera de los medios listados anteriormente. Tras leer esa sección puede volver aquí y leer la <>. [[install-floppies]] === Preparación del medio de arranque El proceso de instalación de FreeBSD comienza por arrancar su sistema mediante el instalador de FreeBSD: no es un programa que pueda ejecutar desde otro sistema operativo. Su sistema suele arrancar usando el sistema operativo que está instalado en su disco duro pero puede también ser configurado para que lo haga desde un floppy «arrancable». Las computadoras más modernas pueden también arrancar desde un CDROM introducido en la unidad CDROM. [TIP] ==== Si tiene FreeBSD en CDROM o DVD (por haberlo comprado o haberlo preparado por usted) y su sistema puede arracar desde CDROM o DVD (suele ser una opción de BIOS llamada «Boot Order» o algo similar) puede saltarse esta sección. Las imágenes de CDROM o DVD de FreeBSD permiten arrancar desde ellas y pueden emplearse para instalar FreeBSD sin ninguna preparación especial. ==== Siga estos pasos para crear las imágenes que le permitirán arrancar desde floppy: [.procedure] ===== . Consiga las imágenes de arranque desde floppy + Los discos de arranque se encuentran en el directorio [.filename]#floppies/# del medio de instalación o pueden descargarse desde el directorio correspondiente de `ftp://ftp.FreeBSD.org/pub/FreeBSD/releases//-RELEASE/floppies/`. Reemplace __ y __ con la arquitectura y la versión de FreeBSD que quiera instalar. Por ejemplo, las imágenes de arranque desde floppy para FreeBSD {rel120-current}-RELEASE para i386(TM) están en from link:ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/{rel120-current}-RELEASE/floppies/[ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/{rel120-current}-RELEASE/floppies/]. + Las imágenes de floppy tienen la extensión [.filename]#.flp#. El directorio [.filename]#floppies/# contiene diferentes imágenes y las que usted necesitará dependerán de la versión de FreeBSD que vaya a instalar y, en algunos casos, del hardware en el que lo va a instalar. En la mayoría de de los casos solamente usará dos ficheros: [.filename]#kern.flp# y [.filename]#mfsroot.flp#. La instalación en algunos sistemas concretos requerirá controladores de dispositivo adicionales, que se encuentran en la imagen [.filename]#drivers.flp#. Consulte [.filename]#README.TXT# en el propio directorio, ahí encontrará la información más reciente sobre las imágenes. + [IMPORTANT] ====== Su programa de FTP debe usar _modo binario_ para descargar las imágenes. Algunos navegadores web suelen usar el modo _texto_ ( o _ASCII_). He aquí lo primero a comprobar si no puede arrancar desde los disquetes que ha creado. ====== . Preparación de los discos floppy + Tendrá que preperar un disquete por cada imagen que descargue. Es imprescindible que esos discos carezcan de errores. La forma más sencilla de asegurarlo es formatearlos usted. No confíe en disquetes preformateados. La herramienta de formateo de Windows(R) no le advertirá del hallazgo de bloques defectuosos, si encuentra alguno sencillamente lo marcará como «defectuoso» y lo ignorará. Le recomendamos que use disquetes nuevos si decide usar este procedimiento de instalación. + [IMPORTANT] ====== Si instenta instalar FreeBSD y el programa de instalación falla, se queda congelado o sucede alguna otra catástrofe uno de las primeras cosas de las que sospechar son los disquetes. Vuelque los ficheros de imagen en discos nuevos e inténtelo de nuevo. ====== . Escriba los ficheros de imagen en discos floppy («disquetes») + Los ficheros [.filename]#.flp# _no_ son ficheros normales que puedan copiarse a disco. Son imágenes del contenido completo de los discos. Esto significa que _no puede_ simplemente copiar esos ficheros de un disco a otro. Debe usar herramientas especializadas para escribir esas imágenes directamente al disco correspondiente. + Si va a crear los disquetes de arranque en un sistema en el que se está ejecutando MS-DOS(R)/Windows(R) utilice la herramienta `fdimage`. + Si las imágenes están en el CDROM y su CDROM es la unidad [.filename]#E:# ejecute lo siguiente: + [source,shell] .... E:\> tools\fdimage floppies\kern.flp A: .... + Repita el proceso con cada fichero [.filename]#.flp# reemplazando cada vez el disco y recuerde etiquetarlos con el nombre del fichero que ha copiado en cada uno. Modifique la línea del comando donde sea necesario, adaptándola al lugar donde tenga usted los ficheros [.filename]#.flp#. Puede descargar `fdimage` desde el directorio link:ftp://ftp.FreeBSD.org/pub/FreeBSD/tools/[tools ] del sitio FTP de FreeBSD. + Si va a crear los disquetes en un sistema UNIX(R) (por ejemplo otro sistema FreeBSD) puede utilizar man:dd[1] para volcar las imágenes a los discos. En FreeBSD puede ejecutar algo como: + [source,shell] .... # dd if=kern.flp of=/dev/fd0 .... + En FreeBSD [.filename]#/dev/fd0# es la primera unidad de disquetes (la unidad [.filename]#A:#). [.filename]#/dev/fd1# sería la unidad [.filename]#B:# y así sucesivamente. Otras versiones de UNIX(R) pueden asignar nombres diferentes a las unidades de disquetes; consulte la documentación de su sistema. ===== Ya podemos instalar instalar FreeBSD. [[install-start]] == Inicio de la instalación [IMPORTANT] ==== La instalación no efectúa ningún cambio en su disco o discos duros hasta la aparición del siguiente mensaje: ---- Last Chance: Are you SURE you want continue the installation? If you're running this on a disk with data you wish to save then WE STRONGLY ENCOURAGE YOU TO MAKE PROPER BACKUPS before proceeding! We can take no responsibility for lost disk contents! ---- Es decir: ---- Última oportunidad: ?Seguro que quiere seguir adelante con la instalación? ¡Si está ejecutando este programa en un disco que contenga datos que quiera conservar LE RECOMENDAMOS ENCARECIDAMENTE QUE HAGA COPIAS DE SEGURIDAD FIABLES antes de proseguir! ¡No podemos responsabilizarnos de datos perdidos! ---- El proceso de instalación puede abandonarse en cualquier momento antes de la advertencia final sin efectuar cambios en el contenido del disco duro. Si advierte que ha configurado algo de forma incorrecta basta con que apague su sistema y no estropeará nada. ==== [[install-starting]] === El arranque [[install-starting-i386]] ==== El arranque en i386(TM) [.procedure] ==== . Comience con su sistema apagado. . Arranque el sistema. Durante el arranque deberí mostrarse la opción para entrar en la BIOS, normalmente mediante las teclas kbd:[F2], kbd:[F10], kbd:[Del], o kbd:[Alt+S]. Utilice la tecla o combinación de las mismas que se le indique en pantalla. En algunos casos el sistema puede mostrar un gráfico durante el arranque. Pulsar kbd:[Esc] suele disminuir en esos casos el tamaño del gráfico y le permitirá ver los mensajes del arranque. . Encuentre el parámetro que controla desde qué dispositivos arranca el sistema. Normalmente se llama «Boot Order» y suele presentarse como una lista de dispositivos, como `Floppy`, `CDROM`, `First Hard Disk`, etc. + Si necesita disquetes de arranque asegúrese de que selecciona la unidad correspondiente. Si va a arrancar desde CDROM, seleccione la unidad CDROM. En caso de duda consulte el manual que venía con su computadora y/o el de su placa base. + Haga los cambios necesarios, guarde los cambios y salga. El sistema debería reiniciarse. . Si ha elegido arrancar desde disquete, tal y como se describe en <>, uno de ellos será el primer disco de arranque, probablemente el que contiene [.filename]#kern.flp#. Introduzca ese disco en su unidad de disquetes. + Si va a arrancar desde CDROM tendrá que arrancar el sistema e introducir el CDROM en cuanto tenga ocasión. + Si su sistema arranca normalmente y carga el sistema operativo que ya está instalado puede ocurrir alguna de estas cosas: .. Los discos no se introdujeron lo suficientemente pronto en el proceso de arranque. Déjelos insertados y reinicie su sistema. .. Los cambios que hizo en la BIOS no han funcionado. Debería repetir los pasos previos hasta que dé con la opción correcta. .. Su BIOS en concreto no admite el arranque el arranque desde el medio que ha elegido. . FreeBSD comenzará a arrancar. Si está arrancando desde CDROM debería ver algo parecido a esto (se ha omitido la información de número de versión): + [source,shell] .... Verifying DMI Pool Data ........ Boot from ATAPI CD-ROM : 1. FD 2.88MB System Type-(00) Uncompressing ... done BTX loader 1.00 BTX version is 1.01 Console: internal video/keyboard BIOS drive A: is disk0 BIOS drive B: is disk1 BIOS drive C: is disk2 BIOS drive D: is disk3 BIOS 639kB/261120kB available memory FreeBSD/i386 bootstrap loader, Revision 0.8 /kernel text=0x277391 data=0x3268c+0x332a8 | | Hit [Enter] to boot immediately, or any other key for command prompt. Booting [kernel] in 9 seconds... _ .... + Si arranca desde floppy verá algo parecido a esto (se ha omitido la información de número de versión): + [source,shell] .... Verifying DMI Pool Data ........ BTX loader 1.00 BTX version is 1.01 Console: internal video/keyboard BIOS drive A: is disk0 BIOS drive C: is disk1 BIOS 639kB/261120kB available memory FreeBSD/i386 bootstrap loader, Revision 0.8 /kernel text=0x277391 data=0x3268c+0x332a8 | Please insert MFS root floppy and press enter: .... + Siga las instrucciones y extraiga el disco [.filename]#kern.flp# disc, inserte el disco [.filename]#mfsroot.flp# y pulse kbd:[Intro]. . Tanto si arranca desde disquete como CDROM el proceso de arranque llegará a este punto: + [source,shell] .... Hit [Enter] to boot immediately, or any other key for command prompt. Booting [kernel] in 9 seconds... _ .... + Dicho y hecho: espere diez segundos o pulse kbd:[Enter]. Esto lanzará el menú de configuración del kernel. ==== ==== Arranque en Alpha [.procedure] ==== . Comience con su sistema apagado. . Encienda su computadora y espera un mensaje de arranque en el monitor. . Si va a arrancar desde disquetes, tal y como se describe en la <>, uno de ellos será el primer disco de arranque, probablemente el que contiene [.filename]#kern.flp#. Ponga este disco en la unidad de disquetes y escriba el siguiente comando para lanzar el arranque desde el disco (corrija el nombre de su unidad de disquetes si fuera necesario): + [source,shell] .... >>>BOOT DVA0 -FLAGS '' -FILE '' .... + Si va a arrancar desde CDROM introduzca el CDROM en la unidad y escriba el siguiente comando para iniciar la instalación (corrija el nombre de la unidad correcta de CDROM si fuera necesario): + [source,shell] .... >>>BOOT DKA0 -FLAGS '' -FILE '' .... . FreeBSD comenzará a arrancar. Si está arrancando desde disquete llegado un cierto punto verá usted este mensaje: + [source,shell] .... Please insert MFS root floppy and press enter: .... + Siga las instrucciones del programa de instalación y retire el disco [.filename]#kern.flp#, inserte el disco [.filename]#mfsroot.flp# y pulse kbd:[Intro]. . Tanto si arrancó desde disquete como desde CDROM el proceso de arranque llegará a este punto: + [source,shell] .... Hit [Enter] to boot immediately, or any other key for command prompt. Booting [kernel] in 9 seconds... _ .... + Dicho y hecho: Espere diez segundos o pulse kbd:[Enter]. Esto iniciará el menú de configuración del kernel. ==== ==== Arranque en sparc64 La mayoría de sistemas sparc64 están configurados para arrancar automáticamente desde disco. Si quiere instalar FreeBSD tendrá que arrancar por red o desde un CDROM, lo que requiere que acceda a la PROM (OpenFirmware). Reinicie el sistema y espere hasta que aparezca el mensaje de arranque. Depende del modelo, pero debería parecerse a este: [source,shell] .... Sun Blade 100 (UltraSPARC-IIe), Keyboard Present Copyright 1998-2001 Sun Microsystems, Inc. All rights reserved. OpenBoot 4.2, 128 MB memory installed, Serial #51090132. Ethernet address 0:3:ba:b:92:d4, Host ID: 830b92d4. .... Si en este punto su sistema arranca desde el disco pulse kbd:[L1+A] o kbd:[Stop+A], o envíe un `BREAK` desde la consola serie serial console (usando, por ejemplo, `~#` en man:tip[1] o man:cu[1]) para así recuperar el prompt de PROM. Tiene este aspecto: [source,shell] .... ok <.> ok {0} <.> .... <.> Este es el prompt que verá en sistemas con una sola CPU. <.> Este prompt se usa en sistemas SMP; el dígito indica el número de la CPU activa. Ponga el CDROM dentro de la unidad y teclée `boot cdrom` en el prompt de la PROM. [[view-probe]] === Revisión de los resultados de la prueba de dispositivos Es posible revisar los últimos cientos de líneas que se han mostrado en pantalla, pues se almacenan en un búfer con ese propósito. Pulse kbd:[Bloq Despl] (kbd:[Scroll Lock]) y ya puede revisar el búfer. Para moverse use las flechas o kbd:[RePág] y kbd:[AvPág] (kbd:[PageUp] y kbd:[PageDown] respectivamente). Pulse de nuevo kbd:[Bloq Despl] (kbd:[Scroll Lock]) cuando quiera salir del búfer. Pruébelo, revise el texto que ha generado el kernel al probar los dispositivos del sistema. Verá un texto muy similar al de la <>, aunque en su caso concreto se mostrarán los dispositivos que tenga su sistema. [[install-dev-probe]] .Ejemplo de resultado de prueba de dispositivos [example] ==== [source,shell] .... avail memory = 253050880 (247120K bytes) Preloaded elf kernel "kernel" at 0xc0817000. Preloaded mfs_root "/mfsroot" at 0xc0817084. md0: Preloaded image 4423680 bytes at 0xc03ddcd4 md1: Malloc disk Using $PIR table, 4 entries at 0xc00fde60 npx0: on motherboard npx0: INT 16 interface pcib0: on motherboard pci0: on pcib0 pcib1: at device 1.0 on pci0 pci1: on pcib1 pci1: at 0.0 irq 11 isab0: at device 7.0 on pci0 isa0: on isab0 atapci0: port 0xe000-0xe00f at device 7.1 on pci0 ata0: at 0x1f0 irq 14 on atapci0 ata1: at 0x170 irq 15 on atapci0 uhci0 port 0xe400-0xe41f irq 10 at device 7.2 on pci 0 usb0: on uhci0 usb0: USB revision 1.0 uhub0: VIA UHCI root hub, class 9/0, rev 1.00/1.00, addr1 uhub0: 2 ports with 2 removable, self powered pci0: (vendor=0x1106, dev=0x3040) at 7.3 dc0: port 0xe800-0xe8ff mem 0xdb000000-0xeb0003ff ir q 11 at device 8.0 on pci0 dc0: Ethernet address: 00:04:5a:74:6b:b5 miibus0: on dc0 ukphy0: on miibus0 ukphy0: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto ed0: port 0xec00-0xec1f irq 9 at device 10. 0 on pci0 ed0 address 52:54:05:de:73:1b, type NE2000 (16 bit) isa0: too many dependant configs (8) isa0: unexpected small tag 14 orm0: