https://wiki.archlinux.org/api.php?action=feedcontributions&user=Visit&feedformat=atomArchWiki - User contributions [en]2024-03-29T02:36:30ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Arch_User_Repository&diff=377873Arch User Repository2015-06-08T09:19:34Z<p>Visit: </p>
<hr />
<div>[[Category:Arch User Repository]]<br />
[[Category:Package development]]<br />
[[Category:Package management]]<br />
[[ar:Arch User Repository]]<br />
[[cs:Arch User Repository]]<br />
[[da:Arch User Repository]]<br />
[[de:Arch User Repository]]<br />
[[el:Arch User Repository]]<br />
[[es:Arch User Repository]]<br />
[[fi:AUR]]<br />
[[fr:AUR]]<br />
[[it:Arch User Repository]]<br />
[[ja:Arch User Repository]]<br />
[[nl:Arch User Repository]]<br />
[[pl:Arch User Repository]]<br />
[[pt:Arch User Repository]]<br />
[[ro:AUR]]<br />
[[ru:Arch User Repository]]<br />
[[sr:Arch User Repository]]<br />
[[tr:Arch Kullanıcı Deposu]]<br />
[[uk:Arch User Repository]]<br />
[[zh-CN:Arch User Repository]]<br />
{{Related articles start}}<br />
{{Related|AUR helpers}}<br />
{{Related|AurJson}}<br />
{{Related|AUR Trusted User Guidelines}}<br />
{{Related|PKGBUILD}}<br />
{{Related|makepkg}}<br />
{{Related|pacman}}<br />
{{Related|Official repositories}}<br />
{{Related|Arch Build System}}<br />
{{Related|Creating packages}}<br />
{{Related articles end}}<br />
<br />
The Arch User Repository (AUR) is a community-driven repository for Arch users. It contains package descriptions ([[PKGBUILD]]s) that allow you to compile a package from source with [[makepkg]] and then install it via [[pacman#Additional commands|pacman]]. The AUR was created to organize and share new packages from the community and to help expedite popular packages' inclusion into the [[community]] repository. This document explains how users can access and utilize the AUR.<br />
<br />
A good number of new packages that enter the official repositories start in the AUR. In the AUR, users are able to contribute their own package builds (PKGBUILD and related files). The AUR community has the ability to vote for or against packages in the AUR. If a package becomes popular enough &mdash; provided it has a compatible license and good packaging technique &mdash; it may be entered into the ''community'' repository (directly accessible by [[pacman]] or [[abs]]).<br />
<br />
== Getting started ==<br />
<br />
Users can search and download PKGBUILDs from the [https://aur.archlinux.org AUR Web Interface]. These PKGBUILDs can be built into installable packages using [[makepkg]], then installed using pacman. <br />
<br />
* Ensure the {{Grp|base-devel}} package group is installed ({{ic|pacman -S --needed base-devel}}).<br />
* Read the remainder of this article for more info and a short tutorial on installing AUR packages.<br />
* Visit the [https://aur.archlinux.org AUR Web Interface] to inform yourself on updates and happenings. There you will also find statistics and an up-to-date list of newest available packages available in AUR.<br />
* Glance over the [[#FAQ]] for answers to the most common questions.<br />
* You may wish to adjust {{ic|/etc/makepkg.conf}} to better optimize for your processor prior to building packages from the AUR. A significant improvement in compile times can be realized on systems with multi-core processors by adjusting the MAKEFLAGS variable. Users can also enable hardware-specific optimizations in GCC via the CFLAGS variable. See [[makepkg]] for more information.<br />
<br />
== History ==<br />
<br />
The following items are listed for historical purposes only. They have since been superseded by the AUR and are no longer available.<br />
<br />
In the beginning, there was {{ic|<nowiki>ftp://ftp.archlinux.org/incoming</nowiki>}}, and people contributed by simply uploading the PKGBUILD, the needed supplementary files, and the built package itself to the server. The package and associated files remained there until a [[Package Maintainer]] saw the program and adopted it.<br />
<br />
Then the Trusted User Repositories were born. Certain individuals in the community were allowed to host their own repositories for anyone to use. The AUR expanded on this basis, with the aim of making it both more flexible and more usable. In fact, the AUR maintainers are still referred to as TUs (Trusted Users).<br />
<br />
== Searching ==<br />
<br />
The AUR web interface can be found at https://aur.archlinux.org/, and an interface suitable for accessing the AUR from a script can be found at https://aur.archlinux.org/rpc.php.<br />
<br />
Queries search package names and descriptions via a MySQL LIKE comparison. This allows for more flexible search criteria (e.g. try searching for {{ic|tool%like%grep}} instead of {{ic|tool like grep}}). If you need to search for a description that contains {{ic|%}}, escape it with {{ic|\%}}.<br />
<br />
== Installing packages ==<br />
<br />
Installing packages from the AUR is a relatively simple process. Essentially:<br />
<br />
# Acquire the tarball which contains the [[PKGBUILD]] and possibly other required files, like systemd-units and patches (but often not the actual code).<br />
# Extract the tarball (preferably in a folder set aside just for builds from the AUR) with {{ic|tar -xvf foo.tar.gz}}.<br />
# Run {{ic|makepkg}} in the directory where the files are saved ({{ic|makepkg -s}} will automatically resolve dependencies with pacman). This will download the code, compile it and pack it.<br />
# Look for a README file in {{ic|src/}}, as it might contain information needed later on.<br />
# Install the resulting package with [[pacman]]:<br />
<br />
: {{bc|# pacman -U /path/to/pkg.tar.xz}}<br />
<br />
[[AUR helpers]] add seamless access to the AUR. They vary in their features but can ease in searching, fetching, building, and installing from PKGBUILDs found in the AUR. All of these scripts can be found in the AUR.<br />
<br />
{{Warning|There is not and will never be an ''official'' mechanism for installing build material from the AUR. '''All AUR users should be familiar with the build process.'''}}<br />
<br />
=== Prerequisites ===<br />
<br />
First ensure that the necessary tools are installed. The package group {{grp|base-devel}} should be sufficient; it includes {{pkg|make}} and other tools needed for compiling from source.<br />
<br />
{{Warning|Packages in the AUR assume the {{grp|base-devel}} group is installed, and AUR packages will not list members of this group as dependencies even if the package cannot be built without them. Please ensure this group is installed before complaining about failed builds.}}<br />
<br />
# pacman -S --needed base-devel<br />
<br />
Next choose an appropriate build directory. A build directory is simply a directory where the package will be made or "built" and can be any directory. Examples of commonly used directories are:<br />
<br />
~/builds<br />
<br />
or if using ABS (the [[Arch Build System]]):<br />
<br />
/var/abs/local<br />
<br />
For more information on ABS read the [[Arch Build System]] article. The example will use {{ic|~/builds}} as the build directory.<br />
<br />
=== Acquire build files ===<br />
<br />
Locate the package in the AUR. This is done using the search feature (text field at the top of the [https://aur.archlinux.org/ AUR home page]). Clicking the application's name in the search list brings up an information page on the package. Read through the description to confirm that this is the desired package, note when the package was last updated, and read any comments.<br />
<br />
Download the necessary build files by clicking on the "Download tarball" link under "Package actions" on the right hand side. This file should be saved to the build directory or otherwise copied to the directory after downloading. In this example, the file is called "foo.tar.gz" (standard format is ''pkgname''.tar.gz, if it has been properly submitted).<br />
<br />
Alternatively you can download the tarball from the terminal, changing directories to the build directory first:<br />
<br />
$ cd ~/builds<br />
$ curl -L -O <nowiki>https://aur.archlinux.org/packages/fo/foo/foo.tar.gz</nowiki><br />
<br />
=== Build the package ===<br />
<br />
Change directories to the build directory if not already there, then extract the previously downloaded package:<br />
<br />
$ cd ~/builds<br />
$ tar -xvf foo.tar.gz<br />
<br />
This should create a new directory called "foo" in the build directory.<br />
<br />
{{Warning|'''Carefully check all files.''' {{ic|cd}} to the newly created directory and carefully check the {{ic|PKGBUILD}} and any {{ic|.install}} file for malicious commands. {{ic|PKGBUILD}}s are bash scripts containing functions to be executed by {{ic|makepkg}}: these functions can contain ''any'' valid commands or Bash syntax, so it is totally possible for a {{ic|PKGBUILD}} to contain dangerous commands through malice or ignorance on the part of the author. Since {{ic|makepkg}} uses fakeroot (and should never be run as root), there is some level of protection but you should never count on it. If in doubt, do not build the package and seek advice on the forums or mailing list.}}<br />
<br />
$ cd foo<br />
$ nano PKGBUILD<br />
$ nano foo.install<br />
<br />
Make the package. After manually confirming the integrity of the files, run [[makepkg]] as a normal user:<br />
<br />
$ makepkg -s<br />
<br />
The {{ic|-s}} switch will use [[sudo]] to install any needed dependencies. If the use of sudo is undesirable, manually install required dependencies beforehand and exclude the {{ic|-s}} in the above command.<br />
<br />
=== Install the package ===<br />
<br />
Install the package using pacman. A tarball should have been created named:<br />
<br />
<''application name''>-<''application version number''>-<''package revision number''>-<''architecture''>.pkg.tar.xz<br />
<br />
This package can be installed using pacman's "upgrade" command:<br />
<br />
# pacman -U foo-0.1-1-i686.pkg.tar.xz <br />
<br />
These manually installed packages are called foreign packages &mdash; packages which have not originated from any repository known to pacman. To list all foreign packages:<br />
$ pacman -Qm <br />
<br />
{{Note|The above example is only a brief summary of the package building process. A visit to the [[makepkg]] and [[ABS]] pages will provide more detail and is highly recommended, especially for first-time users.}}<br />
<br />
== Feedback ==<br />
<br />
The [https://aur.archlinux.org AUR Web Interface] has a comments facility that allows users to provide suggestions and feedback on improvements to the PKGBUILD contributor. Avoid pasting patches or PKGBUILDs into the comments section: they quickly become obsolete and just end up needlessly taking up lots of space. Instead email those files to the maintainer, or even use a [[pastebin]].<br />
<br />
One of the easiest activities for '''all''' Arch users is to browse the AUR and '''vote''' for their favourite packages using the online interface. All packages are eligible for adoption by a TU for inclusion in the [[community]] repository, and the vote count is one of the considerations in that process; it is in everyone's interest to vote!<br />
<br />
== Sharing and maintaining packages ==<br />
<br />
Users can '''share''' PKGBUILDs using the Arch User Repository. It does not contain any binary packages but allows users to upload PKGBUILDs that can be downloaded by others. These PKGBUILDs are completely unofficial and have not been thoroughly vetted, so they should be used at your own risk.<br />
<br />
=== Submitting packages ===<br />
<br />
{{Warning|Before attempting to submit a package you are expected to familiarize yourself with [[Arch packaging standards]] and all articles, mentioned at the bottom of it.}}<br />
<br />
{{Note|The following section describes how to upload packages to aurweb 3.5.1. If you are submitting a package for the first time, please consider directly uploading it to [[#AUR 4|AUR 4]] instead.}}<br />
<br />
After logging in to the AUR web interface, a user can [https://aur.archlinux.org/pkgsubmit.php submit] a gzipped tarball ({{ic|.tar.gz}}) of a directory containing build files for a package. The directory inside the tarball should contain a [[PKGBUILD]], [[#AUR metadata|.SRCINFO]], any {{ic|.install}} files, patches, etc. ('''absolutely''' no binaries). Examples of what such a directory should look like can be seen inside {{ic|/var/abs}} if the [[Arch Build System]] were installed.<br />
<br />
The tarball can be created with the following command:<br />
<br />
$ makepkg --source<br />
<br />
Note that this is a gzipped tarball; assuming you are uploading a package called ''libfoo'', when you create the file it should look similar to this:<br />
<br />
{{hc|$ tar tf libfoo-0.1-1.src.tar.gz|<br />
libfoo/<br />
libfoo/.SRCINFO<br />
libfoo/PKGBUILD<br />
libfoo/libfoo.install}}<br />
<br />
{{Note|The ".SRCINFO" file contains source package metadata, see [[#AUR metadata]] for details.}}<br />
<br />
When submitting a package, observe the following rules:<br />
<br />
* Check the [https://www.archlinux.org/packages/ official package database] for the package. If '''any version''' of it exists, '''do not''' submit the package. If the official package is out-of-date, flag it as such. If the official package is broken or is lacking a feature, then please file a [https://bugs.archlinux.org/ bug report].<br />
* Check the AUR for the package. If it is currently maintained, changes can be submitted in a comment for the maintainer's attention. If it is unmaintained, the package can be adopted and updated as required. Do not create duplicate packages.<br />
* Verify carefully that what you are uploading is correct. All contributors must read and adhere to the [[Arch packaging standards]] when writing PKGBUILDs. This is essential to the smooth running and general success of the AUR. Remember that you are not going to earn any credit or respect from your peers by wasting their time with a bad PKGBUILD.<br />
* Packages that contain binaries or that are very poorly written may be deleted without warning.<br />
* If you are unsure about the package (or the build/submission process) in any way, submit the PKGBUILD to the [https://mailman.archlinux.org/mailman/listinfo/aur-general AUR mailing list] or the [https://bbs.archlinux.org/viewforum.php?id=4 AUR forum] on the Arch forums for public review before adding it to the AUR.<br />
* Make sure the package is useful. Will anyone else want to use this package? Is it extremely specialized? If more than a few people would find this package useful, it is appropriate for submission.<br />
* The AUR and official repositories are intended for packages which install generally software and software-related content, including one or more of the following: executable(s); config file(s); online or offline documentation for specific software or the Arch Linux distribution as a whole; media intended to be used directly by software.<br />
* Gain some experience before submitting packages. Build a few packages to learn the process and then submit.<br />
* If you submit a {{ic|package.tar.gz}} with a file named {{ic|package}} in it you will get an error: "Could not change to directory {{ic|/home/aur/unsupported/package/package}}". To resolve this, rename the file named {{ic|package}} to something else; for example, {{ic|package.rc}}. When it is installed in the {{ic|pkg}} directory, you may rename it back to {{ic|package}}.<br />
<br />
=== Maintaining packages ===<br />
<br />
* If you maintain a package and want to update the PKGBUILD for your package just resubmit it.<br />
* Check for feedback and comments from other users and try to incorporate any improvements they suggest; consider it a learning process!<br />
* Please do not leave a comment containing the version number every time you update the package. This keeps the comment section usable for valuable content mentioned above. [[AUR helpers]] are suited better to check for updates.<br />
* Please do not just submit and forget about packages! It is the maintainer's job to maintain the package by checking for updates and improving the PKGBUILD.<br />
* If you do not want to continue to maintain the package for some reason, {{ic|disown}} the package using the AUR web interface and/or post a message to the AUR Mailing List.<br />
<br />
=== Other requests ===<br />
<br />
* Disownment requests and removal requests can be created by clicking on the "File Request" link under "Package actions" on the right hand side. This automatically sends a notification email to the current package maintainer and to the [https://mailman.archlinux.org/mailman/listinfo/aur-requests aur-requests mailing list] for discussion. [[Trusted Users]] will then either accept or reject the request.<br />
* Disownment requests will be granted after two weeks if the current maintainer did not react.<br />
* '''Package merging has been implemented''', users still have to resubmit a package under a new name and may request merging of the old version's comments and votes.<br />
* Removal requests require the following information:<br />
** Reason for deletion, at least a short note <br> '''Notice:''' A package's comments does not sufficiently point out the reasons why a package is up for deletion. Because as soon as a TU takes action, the only place where such information can be obtained is the aur-requests mailing list.<br />
** Supporting details, like when a package is provided by another package, if you are the maintainer yourself, it is renamed and the original owner agreed, etc.<br />
** For merge requests: Name of the package base to merge into.<br />
<br />
Removal requests can be disapproved, in which case you will likely be advised to disown the package for a future packager's reference.<br />
<br />
== Git repository ==<br />
A [[Git]] repository of the AUR is available at {{ic|<nowiki>git://pkgbuild.com/aur-mirror.git</nowiki>}}, and is generally updated at least once per day. If the repository's [http://git-scm.com/book/en/Git-Basics-Viewing-the-Commit-History commit history] is not needed, then cloning with the {{ic|1=--depth=1}} option will be much quicker:<br />
<br />
<nowiki>$ git clone --depth=1 git://pkgbuild.com/aur-mirror.git</nowiki><br />
<br />
For more information, see the following: [http://pkgbuild.com/git/aur-mirror.git/ Git Web interface], [https://bbs.archlinux.org/viewtopic.php?id=113099 forum thread].<br />
<br />
== AUR metadata ==<br />
<br />
{{Style|This section was originally in a separate page, it may need adaptations to better fit into this article.}}<br />
<br />
In order to display information in the [[AUR]] web interface, the AUR's back-end code attempts to parse [[PKGBUILD]] files and salvage package name, version, and other information from it. {{ic|PKGBUILD}}s are [[Bash]] scripts, and correctly parsing Bash scripts without executing them is a huge challenge, which is why [[makepkg]] is a Bash script itself: it includes the PKGBUILD of the package being built via the {{ic|source}} directive. AUR metadata files were created to get rid of some hacks, used by AUR package maintainers to work around incorrect parsing in the web interface. See also {{Bug|25210}}, {{Bug|15043}}, and {{Bug|16394}}.<br />
<br />
=== How it works ===<br />
By adding a metadata file called ".SRCINFO" to source tarballs to overwrite specific PKGBUILD fields. An outdated format of this file was described in the [https://mailman.archlinux.org/pipermail/aur-dev/2013-March/002428.html AUR 2.1.0 release announcement]. {{ic|.SRCINFO}} files are parsed line-by-line. The syntax for each line is {{ic|1=key[_arch] = value}}. Exactly one space must be on each side of the equals sign, even for an empty value, and do not include quotes around the values.<br />
<br />
The {{ic|key}} is a field name, based on the names of the corresponding [[PKGBUILD Variables]]. Some field names may optionally be suffixed with an architecture name. Fields are grouped into sections, each headed by one of the following two field names:<br />
<br />
* pkgbase: This is required by AUR 3, otherwise the infamous “only lowercase letters are allowed” error is reported. (Pacman uses the first ''pkgname'' if ''pkgbase'' is omitted.) Repeat pkgname if unsure. There is only one ''pkgbase'' section. The field values from this section are inherited unless overridden in the ''pkgname'' sections that follow it. An empty field value in the ''pkgname'' section cancels the inheritance.<br />
* pkgname: There may be multiple ''pkgname'' sections.<br />
<br />
The following field names are associated with a single value for the section:<br />
<br />
* epoch<br />
* pkgver: package version, may be formatted as [''epoch'':]''pkgver'' if the epoch field is not given separately<br />
* pkgrel: release number of the package specific to Arch Linux<br />
* pkgdesc<br />
* url<br />
<br />
The following field names may be repeated on multiple lines in a section to add multiple values:<br />
<br />
* license: in case of multiple licenses separate them by a space<br />
* groups<br />
<br />
The following field names may be repeated, and also may optionally have an architecture suffix, separated from the field name by an underscore:<br />
<br />
* depends: dependencies, one per line<br />
* makedepends<br />
* checkdepends<br />
* optdepends<br />
* conflicts<br />
* provides<br />
* replaces<br />
* source<br />
<br />
Fields with other names are ignored. Blank lines and comment lines beginning with a hash sign (#) are also ignored. Lines may be indented. This format closely matches the {{ic|.PKGINFO}} format that is used for binary packages in [[pacman]]/libalpm.<br />
<br />
== AUR translation ==<br />
<br />
See [https://projects.archlinux.org/aurweb.git/tree/TRANSLATING TRANSLATING] in the AUR source tree for information about creating and maintaining translation of the AUR web interface.<br />
<br />
== FAQ ==<br />
<br />
=== What is the AUR? ===<br />
<br />
The AUR (Arch User Repository) is a place where the Arch Linux community can upload [[PKGBUILD]]s of applications, libraries, etc., and share them with the entire community. Fellow users can then vote for their favorites to be moved into the [[community]] repository to be shared with Arch Linux users in binary form.<br />
<br />
=== What kind of packages are permitted on the AUR? ===<br />
<br />
The packages on the AUR are merely "build scripts", i.e. recipes to build binaries for pacman. For most cases, everything is permitted, subject to the abovementioned usefulness and scope guidelines, as long as you are in compliance with the licensing terms of the content. For other cases, where it is mentioned that "you may not link" to downloads, i.e. contents that are not redistributable, you may only use the file name itself as the source. This means and requires that users already have the restricted source in the build directory prior to building the package. When in doubt, ask.<br />
<br />
=== How can I vote for packages in AUR? ===<br />
<br />
Sign up on the [https://aur.archlinux.org/ AUR website] to get a "Vote for this package" option while browsing packages. After signing up it is also possible to vote from the commandline with {{AUR|aurvote}}.<br />
<br />
=== What is a Trusted User / TU? ===<br />
<br />
A [[AUR Trusted User Guidelines|Trusted User]], in short TU, is a person who is chosen to oversee AUR and the [[community]] repository. They are the ones who maintain popular PKGBUILDs in ''community'', and overall keep the AUR running.<br />
<br />
=== What is the difference between the Arch User Repository and the community repository? ===<br />
<br />
The Arch User Repository is where all PKGBUILDs that users submit are stored, and must be built manually with [[makepkg]]. When PKGBUILDs receive enough community interest and the support of a TU, they are moved into the [[community]] repository (maintained by the TUs), where the binary packages can be installed with [[pacman]].<br />
<br />
=== How to get a PKGBUILD into the community repository? ===<br />
<br />
Usually, at least 10 votes are required for something to move into [[community]]. However, if a TU wants to support a package, it will often be found in the repository.<br />
<br />
Reaching the required minimum of votes is not the only requirement, there has to be a TU willing to maintain the package. TUs are not required to move a package into the ''community'' repository even if it has thousands of votes.<br />
<br />
Usually when a very popular package stays in the AUR it is because:<br />
<br />
* Arch Linux already has another version of a package in the repositories<br />
* The package is AUR-centric (e.g. an [[AUR helper]])<br />
* Its license prohibits redistribution<br />
<br />
See also [[DeveloperWiki:Community repo candidates]] and [[AUR Trusted User Guidelines#Rules for Packages Entering the .5Bcommunity.5D Repo|Rules for Packages Entering the community Repo]].<br />
<br />
=== How do I make a PKGBUILD? ===<br />
<br />
The best resource is the wiki page about [[creating packages]]. Remember to look in AUR before creating the PKGBUILD as to not duplicate efforts.<br />
<br />
=== Foo in AUR is outdated; what do I do? ===<br />
<br />
For starters, you can flag packages out-of-date. If it stays out-of-date for an extended period of time, the best thing to do is email the maintainer. If there is no response from the maintainer after two weeks, you can file an orphan request. When we are talking about a package which is flagged out of date for more than 3 months and is in general not updated for a long time, please add this in your orphan request.<br />
<br />
In the meantime, you can try updating the package yourself by editing the PKGBUILD - sometimes updates do not require any changes to the build or package process, in which case simply updating the {{ic|pkgver}} or {{ic|source}} array is sufficient.<br />
<br />
=== I have a PKGBUILD I would like to submit; can someone check it to see if there are any errors? ===<br />
<br />
If you would like to have your PKGBUILD critiqued, post it on the aur-general mailing list to get feedback from the TUs and fellow AUR members. You could also get help from the [[IRC channel]], #archlinux on irc.freenode.net. You can also use [[namcap]] to check your PKGBUILD and the resulting package for errors.<br />
<br />
=== Foo in AUR does not compile when I run makepkg; what should I do? ===<br />
<br />
You are probably missing something trivial.<br />
<br />
# Run {{ic|pacman -Syyu}} before compiling anything with {{ic|makepkg}} as the problem may be that your system is not up-to-date.<br />
# Ensure you have both "base" and "base-devel" groups installed.<br />
# Try using the "{{ic|-s}}" option with {{ic|makepkg}} to check and install all the dependencies needed before starting the build process.<br />
<br />
Be sure to first read the PKGBUILD and the comments on the AUR page of the package in question.<br />
The reason might not be trivial after all. Custom CFLAGS, LDFLAGS and MAKEFLAGS can cause failures. It is also possible that the PKGBUILD is broken for everyone. If you cannot figure it out on your own, just report it to the maintainer e.g. by posting the errors you are getting in the comments on the AUR page.<br />
<br />
=== How can I speed up repeated build processes? ===<br />
<br />
If you frequently compile code that uses gcc - say, a git or SVN package - you may find [[ccache]], short for "compiler cache", useful.<br />
<br />
=== How can I upload to AUR without using the web interface? ===<br />
<br />
You can use an [[AUR helper]] like {{pkg|burp}} or {{AUR|aurup}}, both are commandline programs.<br />
<br />
=== What is the difference between foo and foo-git packages? ===<br />
<br />
Many AUR packages are presented in regular ("stable") and development versions ("unstable"). A development package usually has a suffix such as "-cvs", "-svn", "-git", "-hg", "-bzr" or "-darcs". While development packages are not intended for regular use, they may offer new features or bugfixes. Because {{ic|-git}}, {{ic|-svn}}, {{ic|-hg}} and {{ic|-bzr}} package builds download the latest available source when you execute {{ic|makepkg}}, a package version to track possible updates is not directly available for these. Likewise these package builds cannot perform an authenticity checksum for the same reason, instead it is relied on the maintainer(s) of the git repository. <br />
<br />
See also [[Enhancing Arch Linux Stability#Avoid development packages]].<br />
<br />
== AUR 4 ==<br />
<br />
Since release 4.0.0, aurweb uses Git repositories for AUR packages which means that the package submission process is a bit different. While [https://aur.archlinux.org/ aur.archlinux.org] is currently still running aurweb 3.5.1, there is a setup of a 4.0.0 release candidate running under [https://aur4.archlinux.org/ aur4.archlinux.org]. AUR package maintainers are supposed to move their packages from [https://aur.archlinux.org/ aur.archlinux.org] to [https://aur4.archlinux.org/ aur4.archlinux.org] between June 8th and July 8th. On August 8th, [https://aur4.archlinux.org/ aur4.archlinux.org] will become the new official AUR (and will be moved to the ''aur'' subdomain).<br />
<br />
=== Before submitting packages to aur4.archlinux.org ===<br />
<br />
Before you submit a package for the first time, you need to create a new SSH key pair.<br />
It is recommended that you create a new key, rather than use an existing SSH key so that you could selectively revoke the SSH key should something happen.<br />
<br />
To create a new SSH key pair:<br />
<br />
$ ssh-keygen -f ~/.ssh/id_rsa-aur<br />
<br />
Log into the AUR web interface, go to ''My Account'' and copy the content of {{ic|~/.ssh/id_rsa-aur.pub}} (or any other key you want to use) into the ''SSH Public Key'' field. Click ''Update'' to save the key. It is recommended to add the following lines to your {{ic|~/.ssh/config}} so you do not need to specify user and key each time you connect to the AUR SSH interface:<br />
<br />
Host aur4.archlinux.org<br />
IdentityFile ~/.ssh/id_rsa-aur<br />
User aur<br />
<br />
=== Submitting packages to aur4.archlinux.org ===<br />
<br />
{{Warning|Before attempting to submit a package you are expected to familiarize yourself with [[Arch packaging standards]] and all articles, mentioned at the bottom of it.}}<br />
<br />
In order to upload a package, simply clone the Git repository with the corresponding name:<br />
<br />
$ git clone <nowiki>aur@aur4.archlinux.org:/</nowiki>''foobar''.git<br />
$ git clone <nowiki>ssh://aur@aur4.archlinux.org/</nowiki>''foobar''.git<br />
<br />
You can then add the source files to the local copy of the Git repository. When making changes to the repository, make sure you always include the {{ic|PKGBUILD}} and {{ic|.SRCINFO}} in the top-level directory. You can create {{ic|.SRCINFO}} files using {{ic|mksrcinfo}}, provided by {{AUR|pkgbuild-introspection-git}}. In order to submit new versions of a package base to the AUR, commit the new {{ic|PKGBUILD}}, {{ic|.SRCINFO}} and possibly helper files (like install files) and run {{ic|git push}}. For example, after adding the {{ic|PKGBUILD}} to the newly created directory, you can run the following commands to create and submit the initial commit:<br />
<br />
$ mksrcinfo<br />
$ git add PKGBUILD .SRCINFO<br />
$ git commit -m 'Initial import'<br />
$ git push origin master<br />
<br />
To update a package, edit the {{ic|PKGBUILD}} and run the following commands to track the changes in the AUR Git repository:<br />
<br />
$ mksrcinfo<br />
$ git commit -am 'Update to ''1.0.0'''<br />
$ git push<br />
<br />
=== Migration scripts ===<br />
<br />
Several scripts exist to ease the transition:<br />
<br />
* [https://gist.github.com/bbidulock/82ab6f5347f021136054 bbidulock's script] to migrate from a .backup directory with all packages.<br />
* [https://github.com/voidus/aur2git aur2git] - A ruby gem to download and submit your existing packages.<br />
* [https://github.com/ido/packages-archlinux/blob/master/bin/import-to-aur4.sh import-to-aur4] to split an existing single git repository and retain the history.<br />
<br />
Keep in mind all those scripts are unsupported and contributed by users!<br />
<br />
== See also ==<br />
* [https://aur.archlinux.org AUR Web Interface]<br />
* [https://www.archlinux.org/mailman/listinfo/aur-general AUR Mailing List]<br />
* [http://pkgbuild.com/git/aur-mirror.git/ AUR Mirror Git repository]</div>Visithttps://wiki.archlinux.org/index.php?title=Bluetooth_headset&diff=374029Bluetooth headset2015-05-17T23:21:06Z<p>Visit: </p>
<hr />
<div>[[Category:Sound]]<br />
[[Category:Bluetooth]]<br />
[[ja:Bluetooth ヘッドセット]]<br />
[[ru:Bluetooth headset]]<br />
{{Related articles start}}<br />
{{Related|Bluetooth}}<br />
{{Related|Bluez4}}<br />
{{Related articles end}}<br />
<br />
Currently, Arch Linux supports the A2DP profile (Audio Sink) for remote audio playback with the default installation. <br />
<br />
{{Tip|<br />
* The most recent version of [[Bluez]] does not support the Headset/Handsfree profiles. This means that microphone input will not work, and also no sound output on headsets that do not support the A2DP profile. For using a headset with the Headset/Handsfree profiles, you will need to jump down to the legacy methods which require using [[AUR]] to fetch alternative packages.<br />
* Bluez5 is only supported by [[PulseAudio]] and not by [[ALSA]]. If you do not want to use PulseAudio, you need to install an older Bluez version from the AUR.}}<br />
<br />
== Headset via Bluez5/PulseAudio ==<br />
<br />
PulseAudio 5.x supports A2DP per default.<br />
Make sure the following packages are [[install]]ed: {{Pkg|pulseaudio-alsa}}, {{Pkg|pulseaudio-bluetooth}}, {{Pkg|bluez}}, {{Pkg|bluez-libs}}, {{Pkg|bluez-utils}}, {{Pkg|bluez-firmware}}.<br />
<br />
Start the Bluetooth system:<br />
<br />
# systemctl start bluetooth<br />
<br />
Now we can use the ''bluetoothctl'' command line utility to pair and connect. For troubleshooting and more detailed explanations of ''bluetoothctl'' see the [[Bluetooth]] article. Run<br />
<br />
# bluetoothctl<br />
<br />
to be greeted by its internal command prompt. Then enter:<br />
<br />
# power on<br />
# agent on<br />
# default-agent<br />
# scan on<br />
<br />
Now make sure that your headset is in pairing mode. It should be discovered shortly. For example,<br />
[NEW] Device 00:1D:43:6D:03:26 Lasmex LBT10<br />
shows a device that calls itself "Lasmex LBT10" and has MAC address ''00:1D:43:6D:03:26''. We will now use that MAC address to initiate the pairing:<br />
<br />
# pair 00:1D:43:6D:03:26<br />
<br />
After pairing, you also need to explicitly connect the device (every time?):<br />
<br />
# connect 00:1D:43:6D:03:26<br />
<br />
If everything works correctly, you now have a separate output device in [[PulseAudio]].<br />
{{Note|The device may be off by default. Select it's audio profile (''OFF'', A2DP, HFP) in the "Configuration" tab of {{Pkg|pavucontrol}}.}}<br />
You can now redirect any audio through that device using the "Playback" and "Recording" tabs of {{Pkg|pavucontrol}}.<br />
<br />
You can now disable scanning again and exit the program:<br />
# scan off<br />
# exit<br />
<br />
=== Troubleshooting ===<br />
<br />
Many users report frustration with getting A2DP/Bluetooth Headsets to work. <br />
<br />
==== Selected audio profile, but headset inactive and audio cannot be redirected ====<br />
<br />
Deceptively, this menu is available before the device has been connected; annoyingly it will have no effect. The menu seems to be created as soon as the receiver recognizes the device.<br />
<br />
Make sure to run bluetoothctl (with sudo/as root) and connect the device manually. There may be configuration options to remove the need to do this each time, but neither pairing nor trusting induce automatic connecting for me.<br />
<br />
==== Pairing fails with AuthenticationFailed ====<br />
<br />
If pairing fails, you can try [https://stackoverflow.com/questions/12888589/linux-command-line-howto-accept-pairing-for-bluetooth-device-without-pin disabling SSPMode] with:<br />
# hciconfig hci0 sspmode 0<br />
<br />
==== Pairing works, but connecting does not ====<br />
<br />
You might see the following error in ''bluetoothctl'':<br />
<br />
[bluetooth]# connect 00:1D:43:6D:03:26<br />
Attempting to connect to 00:1D:43:6D:03:26<br />
Failed to connect: org.bluez.Error.Failed<br />
<br />
To further investigate, have a look at the log via one of the following commands:<br />
<br />
# systemctl status bluetooth<br />
# journalctl -n 20<br />
<br />
You might see a message like this:<br />
<br />
bluetoothd[5556]: a2dp-sink profile connect failed for 00:1D:43:6D:03:26: Protocol not available<br />
<br />
The problem in this case is that PulseAudio is not catching up. A common solution to this problem is to restart PulseAudio. Note that it is perfectly fine to run ''bluetoothctl'' as root while PulseAudio runs as user. After restarting PulseAudio, retry to connect. It is not necessary to repeat the pairing.<br />
<br />
If restarting PulseAudio does not work, you need to load module-bluetooth-discover.<br />
<br />
# pactl load-module module-bluetooth-discover<br />
<br />
The same load-module command can be added to {{ic|/etc/pulse/default.pa}}.<br />
<br />
If that still does not work, or you are using PulseAudio's system-wide mode, also load the following PulseAudio modules (again these can be loaded via your default.pa or system.pa):<br />
<br />
module-bluetooth-policy<br />
module-bluez5-device<br />
module-bluez5-discover<br />
<br />
To have your headset auto connect you need to enable PulseAudio's switch-on-connect module. Add the following:<br />
{{hc|/etc/pulse/default.pa|<br />
# automatically switch to newly-connected devices<br />
load-module module-switch-on-connect<br />
}}<br />
<br />
You then need to tell ''bluetoothctl'' to trust your Bluetooth headset, or you will see errors like this:<br />
bluetoothd[487]: Authentication attempt without agent<br />
bluetoothd[487]: Access denied: org.bluez.Error.Rejected<br />
<br />
[bluetooth]# trust 00:1D:43:6D:03:26<br />
<br />
After a reboot, your Bluetooth adapter will not power on by default. You need to add a udev rule to power it on:<br />
{{hc|/etc/udev/rules.d/10-local.rules|2=<br />
# Set bluetooth power up<br />
ACTION=="add", SUBSYSTEM=="bluetooth", KERNEL=="hci[0-9]*", RUN+="/usr/bin/hciconfig %k up"<br />
}}<br />
<br />
==== Connecting works, but I cannot play sound ====<br />
<br />
Make sure that you see the following messages in your system log:<br />
<br />
bluetoothd[5556]: Endpoint registered: sender=:1.83 path=/MediaEndpoint/A2DPSource<br />
bluetoothd[5556]: Endpoint registered: sender=:1.83 path=/MediaEndpoint/A2DPSink<br />
<br />
If you see a message similar to this, you can go on and investigate your PulseAudio configuration. Otherwise, go back and ensure the connection is successful.<br />
<br />
==== UUIDs has unsupported type ====<br />
<br />
During pairing you might see this output in ''bluetoothctl'':<br />
<br />
[CHG] Device 00:1D:43:6D:03:26 UUIDs has unsupported type<br />
<br />
This message is a very common one and can be ignored.<br />
<br />
== Legacy method: ALSA-BTSCO ==<br />
<br />
{{Out of date|Instructions rely on [[bluez4]].}}<br />
<br />
It is much easier to set up your bluetooth headset today, with bluez >= 3.16. You may want to try the out-of-box python script in [http://fosswire.com/2008/01/11/a2dp-stereo-linux/ this blog] (you need edit the script to work with gconftool-2). There is also a piece of equivalent bash script [http://lymanrb.blogspot.com/2008/05/linux.html here].<br />
<br />
You need your headset's bdaddr. It is of the form ''12:34:56:78:9A:BC''. Either find it in the documentation of your headset, on the headset itself or with the '''hcitool scan''' command.<br />
<br />
Install {{AUR|btsco}}.<br />
<br />
To load the kernel module, type:<br />
# modprobe snd-bt-sco<br />
There will now be an extra audio device. Use {{ic|alsamixer -cN}} (where N is most likely 1) to set the volume. You can access the device with any alsa-capable application by choosing the device ''BT headset'', or with any OSS application by using {{ic|/dev/dspN}} as the audio device.<br />
<br />
But to actually get any sound, you have to connect your headset to the computer first.<br />
<br />
=== Connecting the headset ===<br />
<br />
If you connect your headset for the first time, read the section about pairing first. To connect to your headset to the computer, use the command<br />
$ btsco -f <bdaddr><br />
for example<br />
$ btsco -f 12:34:56:78:9A:BC<br />
<br />
==== Pairing the headset with your computer ====<br />
<br />
The first time you connect the headset, you have to pair it with the computer. To do this, you need your headset's PIN. Depending on your headset you may have to reset the headset and repeat the pairing everytime you used the headset with another bluetooth device.<br />
<br />
There are two ways to pair your headset with the computer:<br />
<br />
===== Using ''bluez-gnome'' =====<br />
<br />
{{Out of date|Package does no longer exist in the repositories.}}<br />
<br />
Install the ''bluez-gnome'' package from the community repository. Then start the '''bt-applet''' program. Once you try to connect to the headset, a window will open and ask for the PIN.<br />
<br />
===== Using ''passkey-agent'' =====<br />
<br />
Before connecting to the headset, enter the command<br />
$ passkey-agent --default <pin><br />
where ''<pin>'' is your headset's PIN. Then try to connect to the headset.<br />
<br />
=== Headset and ALSA Devices ===<br />
<br />
1. First if you have not already, [[pacman|install]] {{Pkg|bluez}} from the [[official repositories]].<br />
<br />
2. Scan for your device<br />
$ hcitool (-i <optional hci#>***) scan<br />
<br />
3. Pair your headset with your device:<br />
$ bluez-simple-agent (optional hci# ***) XX:XX:XX:XX:XX:XX<br />
and put in your pin (0000 or 1234, etc)<br />
<br />
4. Make sure your {{ic|/etc/bluetooth/audio.conf}} allows A2DP Audio Sinks. Place this line just bellow the [General] heading:<br />
Enable=Source,Sink,Media,Socket<br />
<br />
5. Add this to your {{ic|/etc/asound.conf}} file:<br />
#/etc/asound.conf<br />
<br />
pcm.btheadset {<br />
type plug<br />
slave {<br />
pcm {<br />
type bluetooth<br />
device XX:XX:XX:XX:XX:XX <br />
profile "auto"<br />
} <br />
} <br />
hint {<br />
show on<br />
description "BT Headset"<br />
} <br />
}<br />
ctl.btheadset {<br />
type bluetooth<br />
} <br />
<br />
6. Check to see if it has been added to alsa devices<br />
$ aplay -L<br />
<br />
7. Now play with aplay:<br />
$ aplay -D btheadset /path/to/audio/file<br />
<br />
or Mplayer:<br />
$ mplayer -ao alsa:device=btheadset /path/to/audio/or/video/file<br />
<br />
{{Tip|To find hci# for a usb dongle, type in <br />
$ hcitool dev<br />
}}<br />
<br />
=== Headset's multimedia buttons ===<br />
<br />
In order to get your bluetooth headset's multimedia buttons (play, pause, next, previous) working you need to create {{ic|/etc/modules-load.d/uinput.conf}} containing {{ic|uinput}}.<br />
<br />
== Legacy method: PulseAudio ==<br />
<br />
{{Out of date|Instructions rely on [[bluez4]] (references to {{ic|/etc/bluetooth/audio.conf}} and ''bluez-simple-agent'').}}<br />
<br />
This one is much easier and more elegant. PulseAudio will seamlessly switch between output devices when the headset is turned on. If you have ALSA as the sound server, you need the following packages installed:<br />
{{Pkg|pulseaudio}} and {{Pkg|pulseaudio-alsa}}.<br />
<br />
Now, to configure the audio output to use bluetooth, just install {{Pkg|pavucontrol}} and run it to configure the audio output:<br />
$ pavucontrol<br />
Make sure to take a look at the [[PulseAudio]] wiki entry for setting up PulseAudio, especially if you are running KDE.<br />
<br />
=== Troubleshooting ===<br />
<br />
==== Audio sink fails ====<br />
<br />
Bluetooth headset is connected, but ALSA/PulseAudio fails to pick up the connected device. You will get "Audio sink fails".<br />
According to [http://wiki.gentoo.org/wiki/Bluetooth_Headset gentoo wiki], you have to verify than in {{ic|/etc/bluetooth/audio.conf}} there is {{ic|<nowiki>Enable=Socket</nowiki>}} under the {{ic|[General]}} section heading.<br />
<br />
Just do a {{ic|# systemctl restart bluetooth}} to apply it.<br />
<br />
==== Page timeout issue ====<br />
<br />
If you receive this error whilst trying to pair your headset with your system using bluez-simple-agent, then you can try to restart your system and use the graphical bluez applet of your desktop environment.<br />
<br />
== Legacy documentation: ALSA, bluez5 and PulseAudio method ==<br />
<br />
{{Accuracy|Describes two different methods, see the [[Talk:Bluetooth_Headset#bluez5_method:_overcomplicated_instructions|talk page]] for details.|Talk:Bluetooth_Headset#bluez5_method:_overcomplicated_instructions}}<br />
<br />
[[ALSA]], [[bluez|bluez5]], and [[PulseAudio]] work together to allow a wireless [[Bluetooth]] headset to play audio. The following method works with a Lenovo T61p laptop and SoundBot SB220 wireless bluetooth headset. The required software stack is extensive and failure to include all components can produce errors which are difficult to understand. The following list of software packages might not be the minimum required set and needs to be examined more closely.<br />
<br />
Bluez5 has a regression causing HSP/HFP Telephone profile to not be available. This regression is documented in the [http://www.freedesktop.org/wiki/Software/PulseAudio/Notes/5.0/ draft release notes for Pulseaudio 5.0] which say (in "Notes for packagers"): "PulseAudio now supports BlueZ 5, but only the A2DP profile. BlueZ 4 is still the only way to make HSP/HFP work." ([https://fedoraproject.org/wiki/Common_F20_bugs#bluez5-profile from here])<br />
<br />
=== Install Software Packages ===<br />
<br />
The core software components are [[ALSA]], Bluez5, [[PulseAudio]]. However there are additional libraries which are required. As well as a player which can play audio files. The following section lists the software packages installed in order to connect the headset and play audio over the headset.<br />
<br />
==== Install ALSA and associated libraries ====<br />
<br />
[[ALSA]] works with the linux kernel to provide audio services to user mode software. The following packages are used with the [[Bluetooth]] headset: {{Pkg|alsa-utils}}, {{Pkg|alsa-plugins}}, {{Pkg|alsa-tools}}.<br />
<br />
==== Install Bluez5 ====<br />
<br />
Bluez5 is the latest [[Bluetooth]] stack. It is required for [[PulseAudio]] to interface with wireless headsets. Required packages: {{Pkg|bluez}}, {{Pkg|bluez-utils}}, {{Pkg|bluez-libs}}.<br />
<br />
==== Install Audacious ====<br />
<br />
[[Audacious]] is a program which plays audio files. It can work directly with [[ALSA]] or with [[PulseAudio]]. Required packages: {{Pkg|audacious}}, {{Pkg|audacious-plugins}}.<br />
<br />
=== Procedure ===<br />
<br />
Once the required packages are installed, use this procedure to play audio with a bluetooth headset. The high level overview of the procedure is to pair the headset, connect the headset, configure the player and pulse audio controller and then play audio.<br />
<br />
Start the bluetooth service as root:<br />
# systemctl start bluetooth<br />
<br />
Verify Bluetooth is started<br />
# systemctl status bluetooth<br />
bluetooth.service - Bluetooth service<br />
Loaded: loaded (/usr/lib/systemd/system/bluetooth.service; disabled)<br />
Active: active (running) since Sat 2013-12-07 12:31:14 PST; 12s ago<br />
Docs: man:bluetoothd(8)<br />
Main PID: 3136 (bluetoothd)<br />
Status: "Running"<br />
CGroup: /system.slice/bluetooth.service<br />
└─3136 /usr/lib/bluetooth/bluetoothd<br />
<br />
Dec 07 12:31:14 t61p systemd[1]: Starting Bluetooth service...<br />
Dec 07 12:31:14 t61p bluetoothd[3136]: Bluetooth daemon 5.11<br />
Dec 07 12:31:14 t61p systemd[1]: Started Bluetooth service.<br />
Dec 07 12:31:14 t61p bluetoothd[3136]: Starting SDP server<br />
Dec 07 12:31:14 t61p bluetoothd[3136]: Bluetooth management interface 1.3 i...ed<br />
Hint: Some lines were ellipsized, use -l to show in full.<br />
<br />
Start the PulseAudio daemon. This must be done after X windows is started and as a normal user.<br />
$ pulseaudio -D<br />
<br />
Verify the PulseAudio daemon is running.<br />
$ pulseaudio --check -v<br />
I: [pulseaudio] main.c: Daemon running as PID 3186<br />
<br />
Start up bluetoothctl as root and pair and connect your headset. As a regular user, bluetoothctl will pair but not connect. Perhaps this is related to the config file (shown below) which is setup for what appears to be the root user.<br />
Note: the procedure shown below is for an initial pair and connect of the headphone. If the headset is already paired, then the procedure below can be shortened to: power on, agent on, default-agent, connect <mac address>. The mac address can be seen from the devices command output.<br />
<br />
$ bluetoothctl <br />
[NEW] Controller 00:1E:4C:F4:98:5B t61p-0 [default]<br />
[NEW] Device 00:1A:7D:12:36:B9 SoundBot SB220<br />
[bluetooth]# show<br />
Controller 00:1E:4C:F4:98:5B<br />
Name: t61p<br />
Alias: t61p-0<br />
Class: 0x000000<br />
Powered: no<br />
Discoverable: no<br />
Pairable: yes<br />
UUID: PnP Information (00001200-0000-1000-8000-00805f9b34fb)<br />
UUID: Generic Access Profile (00001800-0000-1000-8000-00805f9b34fb)<br />
UUID: Generic Attribute Profile (00001801-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control (0000110e-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control Target (0000110c-0000-1000-8000-00805f9b34fb)<br />
UUID: Audio Source (0000110a-0000-1000-8000-00805f9b34fb)<br />
UUID: Audio Sink (0000110b-0000-1000-8000-00805f9b34fb)<br />
Modalias: usb:v1D6Bp0246d050B<br />
Discovering: no<br />
[bluetooth]# power on<br />
[CHG] Controller 00:1E:4C:F4:98:5B Class: 0x0c010c<br />
Changing power on succeeded<br />
[CHG] Controller 00:1E:4C:F4:98:5B Powered: yes<br />
[bluetooth]# agent on<br />
Agent registered<br />
[bluetooth]# default-agent<br />
Default agent request successful<br />
<br />
<power on your headset in pairing mode. Eventually you will see what appears to be a mac address.><br />
[bluetooth]# scan on<br />
Discovery started<br />
[CHG] Controller 00:1E:4C:F4:98:5B Discovering: yes<br />
[CHG] Device 00:1A:7D:12:36:B9 RSSI: -61<br />
[bluetooth]# pair 00:1A:7D:12:36:B9<br />
Attempting to pair with 00:1A:7D:12:36:B9<br />
[CHG] Device 00:1A:7D:12:36:B9 Connected: yes<br />
[CHG] Device 00:1A:7D:12:36:B9 UUIDs has unsupported type<br />
[CHG] Device 00:1A:7D:12:36:B9 Paired: yes<br />
Pairing successful<br />
[bluetooth]# connect 00:1A:7D:12:36:B9<br />
[CHG] Device 00:1A:7D:12:36:B9 Connected: yes<br />
Connection successful<br />
[bluetooth]# info 00:1A:7D:12:36:B9<br />
Device 00:1A:7D:12:36:B9<br />
Name: SoundBot SB220<br />
Alias: SoundBot SB220<br />
Class: 0x240404<br />
Icon: audio-card<br />
Paired: yes<br />
Trusted: no<br />
Blocked: no<br />
Connected: yes<br />
LegacyPairing: yes<br />
UUID: Headset (00001108-0000-1000-8000-00805f9b34fb)<br />
UUID: Audio Sink (0000110b-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control Target (0000110c-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control (0000110e-0000-1000-8000-00805f9b34fb)<br />
UUID: Handsfree (0000111e-0000-1000-8000-00805f9b34fb)<br />
<br />
Start up alsamixer, for simplicity un-mute all your outputs. Oddly enough some can be muted though. The ones I had muted during playback were:<br />
* Headphones<br />
* SPIDF<br />
<br />
Start up audacious. Use the menu to select PulseAudio as your output. Somewhere I read that bluez5 requires pulseaudio-git and this jives with my experience.<br />
<br />
Start up pavucontrol in a terminal. In the Outputs tab select the bluetooth headset.<br />
<br />
[http://netskink.blogspot.com/2013/12/pulseaudio-pavucontrol-and-audacious.html screenshot of application settings]<br />
<br />
==== Miscellaneous configuration files ====<br />
<br />
For reference, these settings were also done.<br />
<br />
===== ALSA /etc/asound.conf =====<br />
<br />
The settings shown at the top of this page was used, but the additional modification for Intel laptop sound cards.<br />
<br />
{{bc|<nowiki><br />
pcm.btheadset {<br />
type plug<br />
slave {<br />
pcm {<br />
type bluetooth<br />
device 00:1A:7D:12:36:B9<br />
profile "auto"<br />
}<br />
}<br />
hint {<br />
show on<br />
description "BT Headset"<br />
}<br />
}<br />
ctl.btheadset {<br />
type bluetooth<br />
}<br />
options snd-hda-intel model=laptop<br />
</nowiki>}}<br />
<br />
===== /etc/dbus-1/system.d/bluetooth.conf =====<br />
<br />
The settings here seem to be enabled for root only. See the policy user="root" section. However, if a regular user is specified here, the system fails to start. Someone with more knowledge could explain why.<br />
<br />
{{hc|/etc/dbus-1/system.d/bluetooth.conf|<nowiki><br />
<!-- This configuration file specifies the required security policies for Bluetooth core daemon to work. --><br />
<br />
<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"<br />
"http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"><br />
<busconfig><br />
<br />
<!-- ../system.conf have denied everything, so we just punch some holes --><br />
<br />
<policy user="root"><br />
<allow own="org.bluez"/><br />
<allow send_destination="org.bluez"/><br />
<allow send_interface="org.bluez.Agent1"/><br />
<allow send_interface="org.bluez.MediaEndpoint1"/><br />
<allow send_interface="org.bluez.MediaPlayer1"/><br />
<allow send_interface="org.bluez.ThermometerWatcher1"/><br />
<allow send_interface="org.bluez.AlertAgent1"/><br />
<allow send_interface="org.bluez.Profile1"/><br />
<allow send_interface="org.bluez.HeartRateWatcher1"/><br />
<allow send_interface="org.bluez.CyclingSpeedWatcher1"/><br />
</policy><br />
<br />
<policy at_console="true"><br />
<allow send_destination="org.bluez"/><br />
</policy><br />
<br />
<!-- allow users of lp group (printing subsystem) to communicate with bluetoothd --><br />
<policy group="lp"><br />
<allow send_destination="org.bluez"/><br />
</policy><br />
<br />
<policy context="default"><br />
<deny send_destination="org.bluez"/><br />
</policy><br />
<br />
</busconfig><br />
</nowiki>}}<br />
<br />
===== Tested applications =====<br />
<br />
As noted above this will work easily with audacious. YouTube videos with Chromium and Flash Player will work on some videos. If the video has ads it will not work, but if the video does not have ads it will work. Just make sure that after audacious is working with Bluetooth headset, start Chromium, and navigate to YouTube. Find a video without leading ads, and it should play the audio. If the settings icon has the a menu with two drop-down combo boxes for Speed and Quality it will play.<br />
<br />
== Switch between HSV and A2DP setting ==<br />
<br />
This can easily be achieved by the following command where 2 needs to be changed with the correct device number.<br />
<br />
pacmd set-card-profile 2 a2dp_sink<br />
<br />
=== A2DP not working with PulseAudio ===<br />
<br />
If PulseAudio fails when changing the profile to A2DP with bluez 4.1+ and PulseAudio 3.0+, you can try disabling the Socket interface from {{ic|/etc/bluetooth/audio.conf}} by removing the line {{ic|1=Enable=Socket}} and adding line {{ic|1=Disable=Socket}}.<br />
<br />
== Tested headsets ==<br />
<br />
{| class="wikitable"<br />
! Model<br />
! Version<br />
! Comments<br />
! Compatible<br />
|-<br />
| '''Philips SHB9150'''<br />
| bluez5, pulseaudio 5<br />
| Pause and resume does not work. With at least mpv and Banshee hitting the pause button stops audio output but does not pause the player.<br />
| {{R|Limited}}<br />
|-<br />
| '''Philips SHB9100'''<br />
| <br />
| Pause and resume is flaky. See [https://bbs.archlinux.org/viewtopic.php?pid=1315428#p1315428] for the underlying issue and a temporary solution to improve audio quality.<br />
| {{R|Limited}}<br />
|-<br />
| '''Philips SHB7000'''<br />
| <br />
| Pause and resume is flaky.<br />
| {{R|Limited}}<br />
|-<br />
| '''Philips SHB5500BK/00'''<br />
| bluez 5.28, PulseAudio 6.0<br />
| Pause and resume is not working.<br />
| {{R|Limited}}<br />
|-<br />
| '''Parrot Zik'''<br />
| <br />
| Firmware 1.04. The microphone is detected, but does not work. Sometimes it lags (but does not stutter); usually this is not noticeable unless playing games, in which case you may switch to a wired connection.<br />
| {{R|Limited}}<br />
|-<br />
| '''Sony DR-BT50'''<br />
| bluez{4,5}<br />
| Works for a2dp, see [http://vlsd.blogspot.com/2013/11/bluetooth-headphones-and-arch-linux.html]). Adapter: D-Link DBT-120 USB dongle.<br />
| {{Yes}}<br />
|-<br />
| '''Sony SBH50'''<br />
| bluez5<br />
| Works for a2dp, Adapter: Broadcom Bluetooth 2.1 Device (Vendor=0a5c ProdID=219b Rev=03.43). Requires the {{ic|btusb}} [[modprobe|module]].<br />
| {{Yes}}<br />
|-<br />
| '''Sony MDR-XB950BT'''<br />
| pulseaudio<br />
| Tested a2dp. Adapter: Grand-X BT40G. Doesn't auto-connect, need to connect manually. Other functionality works fine.<br />
| {{R|Limited}}<br />
|-<br />
| '''Sony MUC-M1BT1'''<br />
| bluez5, {{AUR|pulseaudio-git}}<br />
| Both A2DP & HSP/HFP work fine.<br />
| {{Yes}}<br />
|-<br />
| '''SoundBot SB220'''<br />
| bluez5, {{AUR|pulseaudio-git}}<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Auna Air 300'''<br />
| bluez5, pulseaudio-git<br />
| For some reason, a few restarts were required, and eventually it just started working.<br />
| {{R|Limited}}<br />
|-<br />
| '''Sennheiser MM 400-X'''<br />
| bluez5, pulseaudio 4.0-6<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Sennheiser MM 550-X Travel'''<br />
| bluez 5.27-1, pulseaudio 5.0-1<br />
| Next/Previous buttons work out-of-the-box, Play/Pause does not<br />
| {{Yes}}<br />
|-<br />
| '''Audionic BlueBeats (B-777)'''<br />
| bluez5, pulseaudio 4.0-6<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Logitech Wireless Headset'''<br />
| bluez 5.14, pulseaudio-git<br />
| part number PN 981-000381, advertised for use with iPad<br />
| {{Yes}}<br />
|-<br />
| '''HMDX Jam Classic Bluetooth'''<br />
| bluez, pulseaudio-git<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''PT-810'''<br />
| bluez 5.14, pulseaudio-git<br />
| Generic USB-Powered Bluetooth Audio Receiver with 3.5mm headset jack and a2dp profile. Widely available as "USB Bluetooth Receiver." IDs as PT-810.<br />
| {{Yes}}<br />
|-<br />
| '''Philips SHB4000WT'''<br />
| bluez5<br />
| A2DP works, HDP distorted.<br />
| {{Yes}}<br />
|-<br />
| '''Philips AEA2000/12'''<br />
| bluez5<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Nokia BH-104'''<br />
| bluez4<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Creative AirwaveHD'''<br />
| bluez 5.23<br />
| Bluetooth adapter Atheros Communications usb: 0cf3:0036<br />
| {{Yes}}<br />
|-<br />
| '''Creative HITZ WP380'''<br />
| bluez 5.27, pulseaudio 5.0-1<br />
| A2DP Profile only. Buttons work (Play, Pause, Prev, Next). Volume buttons are hardware-only. Auto-connect works but you should include the bluetooth module in "pulseaudio" to switch to it automatically. Clear HD Music Audio (This device support APTx codec but it isn't supported in linux yet). You may have some latency problems which needs pulseaudio restart.<br />
| {{Yes}}<br />
|-<br />
| '''deleyCON Bluetooth Headset'''<br />
| bluez 5.23<br />
| Adapter: CSL - USB nano Bluetooth-Adapter V4.0. Tested a2dp profile. Untested microphone. Does not auto-connect (even when paired and trusted), must connect manually. Play/pause button mutes/unmutes the headphones, not the playback. Playback fwd/bwd buttons do not work (nothing visible with ''xev'').<br />
| {{R|Limited}}<br />
|-<br />
| '''UE BOOM'''<br />
| bluez 5.27, pulseaudio-git 5.99<br />
| Update to latest UE BOOM fw 1.3.58. Sound latency in video solved by configuring pavucontrol. Works with UE BOOM x2.<br />
| {{Yes}}<br />
|-<br />
| '''LG HBS-730'''<br />
| bluez 5.27, pulseaudio 5.0<br />
| Works out of box.<br />
| {{Yes}}<br />
|-<br />
| '''Beats Studio Wireless'''<br />
| bluez 5.28, pulseaudio 6.0<br />
| Works out of box. Not tested multimedia buttons.<br />
| {{Yes}}<br />
|-<br />
| '''AKG Y45BT'''<br />
| bluez 5.30, pulseaudio 6.0<br />
| Pause and resume does not work. Needs {{ic|1=Enable=Socket}} in {{ic|/etc/bluetooth/audio.conf}} and {{ic|load-module module-bluetooth-discover}} in {{ic|/etc/pulse/default.pa}}.<br />
| {{Yes}}<br />
|}<br />
<br />
== See also ==<br />
<br />
<br />
Using the same device on Windows and Linux without pairing the device over and over again<br />
<br />
* [http://ubuntuforums.org/showthread.php?p=9363229#post9363229 Dual booting with a Bluetooth keyboard]</div>Visithttps://wiki.archlinux.org/index.php?title=Bluetooth_headset&diff=363945Bluetooth headset2015-03-04T22:03:59Z<p>Visit: added headset AKG Y45BT</p>
<hr />
<div>[[Category:Sound]]<br />
[[Category:Bluetooth]]<br />
[[ja:Bluetooth ヘッドセット]]<br />
[[ru:Bluetooth headset]]<br />
{{Related articles start}}<br />
{{Related|Bluetooth}}<br />
{{Related|Bluez4}}<br />
{{Related articles end}}<br />
<br />
Currently, Arch Linux supports the A2DP profile (Audio Sink) for remote audio playback with the default installation. <br />
<br />
{{Tip|The most recent version of [[Bluez]] does not support the Headset/Handsfree profiles. This means that microphone input will not work, and also no sound output on headsets that do not support the A2DP profile. For using a headset with the Headset/Handsfree profiles, you will need to jump down to the legacy methods which require using [[AUR]] to fetch alternative packages.<br />
}}<br />
<br />
{{Tip| {{AUR|pulseaudio-git}} has added native support for the Headset/Handsfree profiles and Bluez5.}}<br />
<br />
{{Tip|Bluez5 is only supported by [[PulseAudio]] and not by [[ALSA]]. If you do not want to use PulseAudio, you need to install an older Bluez version from the AUR.}}<br />
<br />
== Headset via Bluez5/PulseAudio (git) ==<br />
<br />
PulseAudio 5.x supports A2DP per default.<br />
The current git also supports HFP.<br />
Make sure the following packages are installed:<br />
<br />
# pacman -S pulseaudio-alsa bluez bluez-libs bluez-utils bluez-firmware<br />
<br />
Start the Bluetooth system:<br />
<br />
# systemctl start bluetooth<br />
<br />
Now we can use the ''bluetoothctl'' command line utility to pair and connect. For troubleshooting and more detailed explanations of ''bluetoothctl'' see the [[Bluetooth]] article. Run<br />
<br />
# bluetoothctl<br />
<br />
to be greeted by its internal command prompt. Then enter:<br />
<br />
# power on<br />
# agent on<br />
# default-agent<br />
# scan on<br />
<br />
Now make sure that your headset is in pairing mode. It should be discovered shortly. For example,<br />
[NEW] Device 00:1D:43:6D:03:26 Lasmex LBT10<br />
shows a device that calls itself "Lasmex LBT10" and has MAC address ''00:1D:43:6D:03:26''. We will now use that MAC address to initiate the pairing:<br />
<br />
# pair 00:1D:43:6D:03:26<br />
<br />
After pairing, you also need to explicitly connect the device (every time?):<br />
<br />
# connect 00:1D:43:6D:03:26<br />
<br />
If everything works correctly, you now have a separate output device in [[PulseAudio]].<br />
{{Note|The device may be off by default. Select it's audio profile (''OFF'', A2DP, HFP) in the "Configuration" tab of {{Pkg|pavucontrol}}.}}<br />
You can now redirect any audio through that device using the "Playback" and "Recording" tabs of {{Pkg|pavucontrol}}.<br />
<br />
You can now disable scanning again and exit the program:<br />
# scan off<br />
# exit<br />
<br />
<br />
=== Troubleshooting ===<br />
<br />
<br />
Many users report frustration with getting A2DP/Bluetooth Headsets to work. <br />
<br />
==== Selected audio profile, but headset inactive and audio cannot be redirected ====<br />
<br />
Deceptively, this menu is available before the device has been connected; annoyingly it will have no effect. The menu seems to be created as soon as the receiver recognizes the device.<br />
<br />
Make sure to run bluetoothctl (with sudo/as root) and connect the device manually. There may be configuration options to remove the need to do this each time, but neither pairing nor trusting induce automatic connecting for me.<br />
<br />
==== Pairing fails with AuthenticationFailed ====<br />
<br />
If pairing fails, you can try [https://stackoverflow.com/questions/12888589/linux-command-line-howto-accept-pairing-for-bluetooth-device-without-pin disabling SSPMode] with:<br />
# hciconfig hci0 sspmode 0<br />
<br />
==== Pairing works, but connecting does not ====<br />
<br />
You might see the following error in ''bluetoothctl'':<br />
<br />
[bluetooth]# connect 00:1D:43:6D:03:26<br />
Attempting to connect to 00:1D:43:6D:03:26<br />
Failed to connect: org.bluez.Error.Failed<br />
<br />
To further investigate, have a look at the log via one of the following commands:<br />
<br />
# systemctl status bluetooth<br />
# journalctl -n 20<br />
<br />
You might see a message like this:<br />
<br />
bluetoothd[5556]: a2dp-sink profile connect failed for 00:1D:43:6D:03:26: Protocol not available<br />
<br />
The problem in this case is that PulseAudio is not catching up. A common solution to this problem is to restart PulseAudio. Note that it is perfectly fine to run ''bluetoothctl'' as root while PulseAudio runs as user. After restarting PulseAudio, retry to connect. It is not necessary to repeat the pairing.<br />
<br />
If restarting PulseAudio does not work, you need to load module-bluetooth-discover.<br />
<br />
# pactl load-module module-bluetooth-discover<br />
<br />
The same load-module command can be added to {{ic|/etc/pulse/default.pa}}.<br />
<br />
If that still does not work, or you are using PulseAudio's system-wide mode, also load the following PulseAudio modules (again these can be loaded via your default.pa or system.pa):<br />
<br />
module-bluetooth-policy<br />
module-bluez5-device<br />
module-bluez5-discover<br />
<br />
To have your headset auto connect you need to enable PulseAudio's switch-on-connect module. Add the following:<br />
{{hc|/etc/pulse/default.pa|<br />
# automatically switch to newly-connected devices<br />
load-module module-switch-on-connect<br />
}}<br />
<br />
You then need to tell ''bluetoothctl'' to trust your Bluetooth headset, or you will see errors like this:<br />
bluetoothd[487]: Authentication attempt without agent<br />
bluetoothd[487]: Access denied: org.bluez.Error.Rejected<br />
<br />
[bluetooth]# trust 00:1D:43:6D:03:26<br />
<br />
After a reboot, your Bluetooth adapter will not power on by default. You need to add a udev rule to power it on:<br />
{{hc|/etc/udev/rules.d/10-local.rules|2=<br />
# Set bluetooth power up<br />
ACTION=="add", SUBSYSTEM=="bluetooth", KERNEL=="hci[0-9]*", RUN+="/usr/bin/hciconfig %k up"<br />
}}<br />
<br />
==== Connecting works, but I cannot play sound ====<br />
<br />
Make sure that you see the following messages in your system log:<br />
<br />
bluetoothd[5556]: Endpoint registered: sender=:1.83 path=/MediaEndpoint/A2DPSource<br />
bluetoothd[5556]: Endpoint registered: sender=:1.83 path=/MediaEndpoint/A2DPSink<br />
<br />
If you see a message similar to this, you can go on and investigate your PulseAudio configuration. Otherwise, go back and ensure the connection is successful.<br />
<br />
==== UUIDs has unsupported type ====<br />
<br />
During pairing you might see this output in ''bluetoothctl'':<br />
<br />
[CHG] Device 00:1D:43:6D:03:26 UUIDs has unsupported type<br />
<br />
This message is a very common one and can be ignored.<br />
<br />
== Legacy method: ALSA-BTSCO ==<br />
<br />
{{Out of date|Instructions rely on [[bluez4]].}}<br />
<br />
It is much easier to set up your bluetooth headset today, with bluez >= 3.16. You may want to try the out-of-box python script in [http://fosswire.com/2008/01/11/a2dp-stereo-linux/ this blog] (you need edit the script to work with gconftool-2). There is also a piece of equivalent bash script [http://lymanrb.blogspot.com/2008/05/linux.html here].<br />
<br />
You need your headset's bdaddr. It is of the form ''12:34:56:78:9A:BC''. Either find it in the documentation of your headset, on the headset itself or with the '''hcitool scan''' command.<br />
<br />
Install {{AUR|btsco}}.<br />
<br />
To load the kernel module, type:<br />
# modprobe snd-bt-sco<br />
There will now be an extra audio device. Use {{ic|alsamixer -cN}} (where N is most likely 1) to set the volume. You can access the device with any alsa-capable application by choosing the device ''BT headset'', or with any OSS application by using {{ic|/dev/dspN}} as the audio device.<br />
<br />
But to actually get any sound, you have to connect your headset to the computer first.<br />
<br />
=== Connecting the headset ===<br />
<br />
If you connect your headset for the first time, read the section about pairing first. To connect to your headset to the computer, use the command<br />
$ btsco -f <bdaddr><br />
for example<br />
$ btsco -f 12:34:56:78:9A:BC<br />
<br />
==== Pairing the headset with your computer ====<br />
<br />
The first time you connect the headset, you have to pair it with the computer. To do this, you need your headset's PIN. Depending on your headset you may have to reset the headset and repeat the pairing everytime you used the headset with another bluetooth device.<br />
<br />
There are two ways to pair your headset with the computer:<br />
<br />
===== Using ''bluez-gnome'' =====<br />
<br />
{{Out of date|Package does no longer exist in the repositories.}}<br />
<br />
Install the ''bluez-gnome'' package from the community repository. Then start the '''bt-applet''' program. Once you try to connect to the headset, a window will open and ask for the PIN.<br />
<br />
===== Using ''passkey-agent'' =====<br />
<br />
Before connecting to the headset, enter the command<br />
$ passkey-agent --default <pin><br />
where ''<pin>'' is your headset's PIN. Then try to connect to the headset.<br />
<br />
=== Headset and ALSA Devices ===<br />
<br />
1. First if you have not already, [[pacman|install]] {{Pkg|bluez}} from the [[official repositories]].<br />
<br />
2. Scan for your device<br />
$ hcitool (-i <optional hci#>***) scan<br />
<br />
3. Pair your headset with your device:<br />
$ bluez-simple-agent (optional hci# ***) XX:XX:XX:XX:XX:XX<br />
and put in your pin (0000 or 1234, etc)<br />
<br />
4. Make sure your {{ic|/etc/bluetooth/audio.conf}} allows A2DP Audio Sinks. Place this line just bellow the [General] heading:<br />
Enable=Source,Sink,Media,Socket<br />
<br />
5. Add this to your {{ic|/etc/asound.conf}} file:<br />
#/etc/asound.conf<br />
<br />
pcm.btheadset {<br />
type plug<br />
slave {<br />
pcm {<br />
type bluetooth<br />
device XX:XX:XX:XX:XX:XX <br />
profile "auto"<br />
} <br />
} <br />
hint {<br />
show on<br />
description "BT Headset"<br />
} <br />
}<br />
ctl.btheadset {<br />
type bluetooth<br />
} <br />
<br />
6. Check to see if it has been added to alsa devices<br />
$ aplay -L<br />
<br />
7. Now play with aplay:<br />
$ aplay -D btheadset /path/to/audio/file<br />
<br />
or Mplayer:<br />
$ mplayer -ao alsa:device=btheadset /path/to/audio/or/video/file<br />
<br />
{{Tip|To find hci# for a usb dongle, type in <br />
$ hcitool dev<br />
}}<br />
<br />
=== Headset's multimedia buttons ===<br />
<br />
In order to get your bluetooth headset's multimedia buttons (play, pause, next, previous) working you need to create {{ic|/etc/modules-load.d/uinput.conf}} containing {{ic|uinput}}.<br />
<br />
== Legacy method: PulseAudio ==<br />
<br />
{{Out of date|Instructions rely on [[bluez4]] (references to {{ic|/etc/bluetooth/audio.conf}} and ''bluez-simple-agent'').}}<br />
<br />
This one is much easier and more elegant. PulseAudio will seamlessly switch between output devices when the headset is turned on. If you have ALSA as the sound server, you need the following packages installed:<br />
{{Pkg|pulseaudio}} and {{Pkg|pulseaudio-alsa}}.<br />
<br />
Now, to configure the audio output to use bluetooth, just install {{Pkg|pavucontrol}} and run it to configure the audio output:<br />
$ pavucontrol<br />
Make sure to take a look at the [[PulseAudio]] wiki entry for setting up PulseAudio, especially if you are running KDE.<br />
<br />
=== Troubleshooting ===<br />
<br />
==== Audio sink fails ====<br />
<br />
Bluetooth headset is connected, but ALSA/PulseAudio fails to pick up the connected device. You will get "Audio sink fails".<br />
According to [http://wiki.gentoo.org/wiki/Bluetooth_Headset gentoo wiki], you have to verify than in {{ic|/etc/bluetooth/audio.conf}} there is {{ic|<nowiki>Enable=Socket</nowiki>}} under the {{ic|[General]}} section heading.<br />
<br />
Just do a {{ic|# systemctl restart bluetooth}} to apply it.<br />
<br />
==== Page timeout issue ====<br />
<br />
If you receive this error whilst trying to pair your headset with your system using bluez-simple-agent, then you can try to restart your system and use the graphical bluez applet of your desktop environment.<br />
<br />
== Legacy documentation: ALSA, bluez5 and PulseAudio method ==<br />
<br />
{{Accuracy|Describes two different methods, see the [[Talk:Bluetooth_Headset#bluez5_method:_overcomplicated_instructions|talk page]] for details.|Talk:Bluetooth_Headset#bluez5_method:_overcomplicated_instructions}}<br />
<br />
[[ALSA]], [[bluez|bluez5]], and [[PulseAudio]] work together to allow a wireless [[Bluetooth]] headset to play audio. The following method works with a Lenovo T61p laptop and SoundBot SB220 wireless bluetooth headset. The required software stack is extensive and failure to include all components can produce errors which are difficult to understand. The following list of software packages might not be the minimum required set and needs to be examined more closely.<br />
<br />
Bluez5 has a regression causing HSP/HFP Telephone profile to not be available. This regression is documented in the [http://www.freedesktop.org/wiki/Software/PulseAudio/Notes/5.0/ draft release notes for Pulseaudio 5.0] which say (in "Notes for packagers"): "PulseAudio now supports BlueZ 5, but only the A2DP profile. BlueZ 4 is still the only way to make HSP/HFP work." ([https://fedoraproject.org/wiki/Common_F20_bugs#bluez5-profile from here])<br />
<br />
=== Install Software Packages ===<br />
<br />
The core software components are [[ALSA]], Bluez5, [[PulseAudio]]. However there are additional libraries which are required. As well as a player which can play audio files. The following section lists the software packages installed in order to connect the headset and play audio over the headset.<br />
<br />
==== Install ALSA and associated libraries ====<br />
<br />
[[ALSA]] works with the linux kernel to provide audio services to user mode software. The following packages are used with the [[Bluetooth]] headset: {{Pkg|alsa-utils}}, {{Pkg|alsa-plugins}}, {{Pkg|alsa-tools}}.<br />
<br />
==== Install Bluez5 ====<br />
<br />
Bluez5 is the latest [[Bluetooth]] stack. It is required for [[PulseAudio]] to interface with wireless headsets. Required packages: {{Pkg|bluez}}, {{Pkg|bluez-utils}}, {{Pkg|bluez-libs}}.<br />
<br />
==== Install PulseAudio ====<br />
<br />
[[PulseAudio]] interfaces with [[ALSA]], Bluez and other user mode programs. The {{AUR|pulseaudio-git}} package from [[AUR]] has capabilities not provided by the stock {{Pkg|pulseaudio}} package. The additional capabilities are required by Bluez5. More info regarding the differences between Bluez5 and PulseAudio are [https://bbs.archlinux.org/viewtopic.php?pid=1302270#p1302270 here.]<br />
<br />
Required packages: {{AUR|pulseaudio-git}}, {{Pkg|pavucontrol}}.<br />
<br />
==== Install Audacious ====<br />
<br />
[[Audacious]] is a program which plays audio files. It can work directly with [[ALSA]] or with [[PulseAudio]]. Required packages: {{Pkg|audacious}}, {{Pkg|audacious-plugins}}.<br />
<br />
=== Procedure ===<br />
<br />
Once the required packages are installed, use this procedure to play audio with a bluetooth headset. The high level overview of the procedure is to pair the headset, connect the headset, configure the player and pulse audio controller and then play audio.<br />
<br />
Start the bluetooth service as root:<br />
# systemctl start bluetooth<br />
<br />
Verify Bluetooth is started<br />
# systemctl status bluetooth<br />
bluetooth.service - Bluetooth service<br />
Loaded: loaded (/usr/lib/systemd/system/bluetooth.service; disabled)<br />
Active: active (running) since Sat 2013-12-07 12:31:14 PST; 12s ago<br />
Docs: man:bluetoothd(8)<br />
Main PID: 3136 (bluetoothd)<br />
Status: "Running"<br />
CGroup: /system.slice/bluetooth.service<br />
└─3136 /usr/lib/bluetooth/bluetoothd<br />
<br />
Dec 07 12:31:14 t61p systemd[1]: Starting Bluetooth service...<br />
Dec 07 12:31:14 t61p bluetoothd[3136]: Bluetooth daemon 5.11<br />
Dec 07 12:31:14 t61p systemd[1]: Started Bluetooth service.<br />
Dec 07 12:31:14 t61p bluetoothd[3136]: Starting SDP server<br />
Dec 07 12:31:14 t61p bluetoothd[3136]: Bluetooth management interface 1.3 i...ed<br />
Hint: Some lines were ellipsized, use -l to show in full.<br />
<br />
Start the PulseAudio daemon. This must be done after X windows is started and as a normal user.<br />
$ pulseaudio -D<br />
<br />
Verify the PulseAudio daemon is running.<br />
$ pulseaudio --check -v<br />
I: [pulseaudio] main.c: Daemon running as PID 3186<br />
<br />
Start up bluetoothctl as root and pair and connect your headset. As a regular user, bluetoothctl will pair but not connect. Perhaps this is related to the config file (shown below) which is setup for what appears to be the root user.<br />
Note: the procedure shown below is for an initial pair and connect of the headphone. If the headset is already paired, then the procedure below can be shortened to: power on, agent on, default-agent, connect <mac address>. The mac address can be seen from the devices command output.<br />
<br />
$ bluetoothctl <br />
[NEW] Controller 00:1E:4C:F4:98:5B t61p-0 [default]<br />
[NEW] Device 00:1A:7D:12:36:B9 SoundBot SB220<br />
[bluetooth]# show<br />
Controller 00:1E:4C:F4:98:5B<br />
Name: t61p<br />
Alias: t61p-0<br />
Class: 0x000000<br />
Powered: no<br />
Discoverable: no<br />
Pairable: yes<br />
UUID: PnP Information (00001200-0000-1000-8000-00805f9b34fb)<br />
UUID: Generic Access Profile (00001800-0000-1000-8000-00805f9b34fb)<br />
UUID: Generic Attribute Profile (00001801-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control (0000110e-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control Target (0000110c-0000-1000-8000-00805f9b34fb)<br />
UUID: Audio Source (0000110a-0000-1000-8000-00805f9b34fb)<br />
UUID: Audio Sink (0000110b-0000-1000-8000-00805f9b34fb)<br />
Modalias: usb:v1D6Bp0246d050B<br />
Discovering: no<br />
[bluetooth]# power on<br />
[CHG] Controller 00:1E:4C:F4:98:5B Class: 0x0c010c<br />
Changing power on succeeded<br />
[CHG] Controller 00:1E:4C:F4:98:5B Powered: yes<br />
[bluetooth]# agent on<br />
Agent registered<br />
[bluetooth]# default-agent<br />
Default agent request successful<br />
<br />
<power on your headset in pairing mode. Eventually you will see what appears to be a mac address.><br />
[bluetooth]# scan on<br />
Discovery started<br />
[CHG] Controller 00:1E:4C:F4:98:5B Discovering: yes<br />
[CHG] Device 00:1A:7D:12:36:B9 RSSI: -61<br />
[bluetooth]# pair 00:1A:7D:12:36:B9<br />
Attempting to pair with 00:1A:7D:12:36:B9<br />
[CHG] Device 00:1A:7D:12:36:B9 Connected: yes<br />
[CHG] Device 00:1A:7D:12:36:B9 UUIDs has unsupported type<br />
[CHG] Device 00:1A:7D:12:36:B9 Paired: yes<br />
Pairing successful<br />
[bluetooth]# connect 00:1A:7D:12:36:B9<br />
[CHG] Device 00:1A:7D:12:36:B9 Connected: yes<br />
Connection successful<br />
[bluetooth]# info 00:1A:7D:12:36:B9<br />
Device 00:1A:7D:12:36:B9<br />
Name: SoundBot SB220<br />
Alias: SoundBot SB220<br />
Class: 0x240404<br />
Icon: audio-card<br />
Paired: yes<br />
Trusted: no<br />
Blocked: no<br />
Connected: yes<br />
LegacyPairing: yes<br />
UUID: Headset (00001108-0000-1000-8000-00805f9b34fb)<br />
UUID: Audio Sink (0000110b-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control Target (0000110c-0000-1000-8000-00805f9b34fb)<br />
UUID: A/V Remote Control (0000110e-0000-1000-8000-00805f9b34fb)<br />
UUID: Handsfree (0000111e-0000-1000-8000-00805f9b34fb)<br />
<br />
Start up alsamixer, for simplicity un-mute all your outputs. Oddly enough some can be muted though. The ones I had muted during playback were:<br />
* Headphones<br />
* SPIDF<br />
<br />
Start up audacious. Use the menu to select PulseAudio as your output. Somewhere I read that bluez5 requires pulseaudio-git and this jives with my experience.<br />
<br />
Start up pavucontrol in a terminal. In the Outputs tab select the bluetooth headset.<br />
<br />
[http://netskink.blogspot.com/2013/12/pulseaudio-pavucontrol-and-audacious.html screenshot of application settings]<br />
<br />
==== Miscellaneous configuration files ====<br />
<br />
For reference, these settings were also done.<br />
<br />
===== ALSA /etc/asound.conf =====<br />
<br />
The settings shown at the top of this page was used, but the additional modification for Intel laptop sound cards.<br />
<br />
{{bc|<nowiki><br />
pcm.btheadset {<br />
type plug<br />
slave {<br />
pcm {<br />
type bluetooth<br />
device 00:1A:7D:12:36:B9<br />
profile "auto"<br />
}<br />
}<br />
hint {<br />
show on<br />
description "BT Headset"<br />
}<br />
}<br />
ctl.btheadset {<br />
type bluetooth<br />
}<br />
options snd-hda-intel model=laptop<br />
</nowiki>}}<br />
<br />
===== /etc/dbus-1/system.d/bluetooth.conf =====<br />
<br />
The settings here seem to be enabled for root only. See the policy user="root" section. However, if a regular user is specified here, the system fails to start. Someone with more knowledge could explain why.<br />
<br />
{{hc|/etc/dbus-1/system.d/bluetooth.conf|<nowiki><br />
<!-- This configuration file specifies the required security policies for Bluetooth core daemon to work. --><br />
<br />
<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"<br />
"http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"><br />
<busconfig><br />
<br />
<!-- ../system.conf have denied everything, so we just punch some holes --><br />
<br />
<policy user="root"><br />
<allow own="org.bluez"/><br />
<allow send_destination="org.bluez"/><br />
<allow send_interface="org.bluez.Agent1"/><br />
<allow send_interface="org.bluez.MediaEndpoint1"/><br />
<allow send_interface="org.bluez.MediaPlayer1"/><br />
<allow send_interface="org.bluez.ThermometerWatcher1"/><br />
<allow send_interface="org.bluez.AlertAgent1"/><br />
<allow send_interface="org.bluez.Profile1"/><br />
<allow send_interface="org.bluez.HeartRateWatcher1"/><br />
<allow send_interface="org.bluez.CyclingSpeedWatcher1"/><br />
</policy><br />
<br />
<policy at_console="true"><br />
<allow send_destination="org.bluez"/><br />
</policy><br />
<br />
<!-- allow users of lp group (printing subsystem) to communicate with bluetoothd --><br />
<policy group="lp"><br />
<allow send_destination="org.bluez"/><br />
</policy><br />
<br />
<policy context="default"><br />
<deny send_destination="org.bluez"/><br />
</policy><br />
<br />
</busconfig><br />
</nowiki>}}<br />
<br />
===== Tested applications =====<br />
<br />
As noted above this will work easily with audacious. YouTube videos with Chromium and Flash Player will work on some videos. If the video has ads it will not work, but if the video does not have ads it will work. Just make sure that after audacious is working with Bluetooth headset, start Chromium, and navigate to YouTube. Find a video without leading ads, and it should play the audio. If the settings icon has the a menu with two drop-down combo boxes for Speed and Quality it will play.<br />
<br />
== Switch between HSV and A2DP setting ==<br />
<br />
This can easily be achieved by the following command where 2 needs to be changed with the correct device number.<br />
<br />
pacmd set-card-profile 2 a2dp<br />
<br />
=== A2DP not working with PulseAudio ===<br />
<br />
If PulseAudio fails when changing the profile to A2DP with bluez 4.1+ and PulseAudio 3.0+, you can try disabling the Socket interface from {{ic|/etc/bluetooth/audio.conf}} by removing the line {{ic|1=Enable=Socket}} and adding line {{ic|1=Disable=Socket}}.<br />
<br />
== Tested headsets ==<br />
<br />
{| class="wikitable"<br />
! Model<br />
! Version<br />
! Comments<br />
! Compatible<br />
|-<br />
| '''Philips SHB9150'''<br />
| bluez5, pulseaudio 5<br />
| Pause and resume does not work. With at least mpv and Banshee hitting the pause button stops audio output but does not pause the player.<br />
| {{R|Limited}}<br />
|-<br />
| '''Philips SHB9100'''<br />
| <br />
| Pause and resume is flaky. See [https://bbs.archlinux.org/viewtopic.php?pid=1315428#p1315428] for the underlying issue and a temporary solution to improve audio quality.<br />
| {{R|Limited}}<br />
|-<br />
| '''Philips SHB7000'''<br />
| <br />
| Pause and resume is flaky.<br />
| {{R|Limited}}<br />
|-<br />
| '''Philips SHB5500BK/00'''<br />
| bluez 5.28, PulseAudio 6.0<br />
| Pause and resume is not working.<br />
| {{R|Limited}}<br />
|-<br />
| '''Parrot Zik'''<br />
| <br />
| Firmware 1.04. The microphone is detected, but does not work. Sometimes it lags (but does not stutter); usually this is not noticeable unless playing games, in which case you may switch to a wired connection.<br />
| {{R|Limited}}<br />
|-<br />
| '''Sony DR-BT50'''<br />
| bluez{4,5}<br />
| Works for a2dp, see [http://vlsd.blogspot.com/2013/11/bluetooth-headphones-and-arch-linux.html]). Adapter: D-Link DBT-120 USB dongle.<br />
| {{Yes}}<br />
|-<br />
| '''Sony SBH50'''<br />
| bluez5<br />
| Works for a2dp, Adapter: Broadcom Bluetooth 2.1 Device (Vendor=0a5c ProdID=219b Rev=03.43). Requires the {{ic|btusb}} [[modprobe|module]].<br />
| {{Yes}}<br />
|-<br />
| '''Sony MDR-XB950BT'''<br />
| pulseaudio<br />
| Tested a2dp. Adapter: Grand-X BT40G. Doesn't auto-connect, need to connect manually. Other functionality works fine.<br />
| {{R|Limited}}<br />
|-<br />
| '''SoundBot SB220'''<br />
| bluez5, {{AUR|pulseaudio-git}}<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Auna Air 300'''<br />
| bluez5, pulseaudio-git<br />
| For some reason, a few restarts were required, and eventually it just started working.<br />
| {{R|Limited}}<br />
|-<br />
| '''Sennheiser MM 400-X'''<br />
| bluez5, pulseaudio 4.0-6<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Sennheiser MM 550-X Travel'''<br />
| bluez 5.27-1, pulseaudio 5.0-1<br />
| Next/Previous buttons work out-of-the-box, Play/Pause does not<br />
| {{Yes}}<br />
|-<br />
| '''Audionic BlueBeats (B-777)'''<br />
| bluez5, pulseaudio 4.0-6<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Logitech Wireless Headset'''<br />
| bluez 5.14, pulseaudio-git<br />
| part number PN 981-000381, advertised for use with iPad<br />
| {{Yes}}<br />
|-<br />
| '''HMDX Jam Classic Bluetooth'''<br />
| bluez, pulseaudio-git<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''PT-810'''<br />
| bluez 5.14, pulseaudio-git<br />
| Generic USB-Powered Bluetooth Audio Receiver with 3.5mm headset jack and a2dp profile. Widely available as "USB Bluetooth Receiver." IDs as PT-810.<br />
| {{Yes}}<br />
|-<br />
| '''Philips SHB4000WT'''<br />
| bluez5<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Philips AEA2000/12'''<br />
| bluez5<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Nokia BH-104'''<br />
| bluez4<br />
| <br />
| {{Yes}}<br />
|-<br />
| '''Creative AirwaveHD'''<br />
| bluez 5.23<br />
| Bluetooth adapter Atheros Communications usb: 0cf3:0036<br />
| {{Yes}}<br />
|-<br />
| '''Creative HITZ WP380'''<br />
| bluez 5.27, pulseaudio 5.0-1<br />
| A2DP Profile only. Buttons work (Play, Pause, Prev, Next). Volume buttons are hardware-only. Auto-connect works but you should include the bluetooth module in "pulseaudio" to switch to it automatically. Clear HD Music Audio (This device support APTx codec but it isn't supported in linux yet). You may have some latency problems which needs pulseaudio restart.<br />
| {{Yes}}<br />
|-<br />
| '''deleyCON Bluetooth Headset'''<br />
| bluez 5.23<br />
| Adapter: CSL - USB nano Bluetooth-Adapter V4.0. Tested a2dp profile. Untested microphone. Does not auto-connect (even when paired and trusted), must connect manually. Play/pause button mutes/unmutes the headphones, not the playback. Playback fwd/bwd buttons do not work (nothing visible with ''xev'').<br />
| {{R|Limited}}<br />
|-<br />
| '''UE BOOM'''<br />
| bluez 5.27, pulseaudio-git 5.99<br />
| Update to latest UE BOOM fw 1.3.58. Sound latency in video solved by configuring pavucontrol. Works with UE BOOM x2.<br />
| {{Yes}}<br />
|-<br />
| '''LG HBS-730'''<br />
| bluez 5.27, pulseaudio 5.0<br />
| Works out of box.<br />
| {{Yes}}<br />
|-<br />
| '''Beats Studio Wireless'''<br />
| bluez 5.28, pulseaudio 6.0<br />
| Works out of box. Not tested multimedia buttons.<br />
| {{Yes}}<br />
|-<br />
| '''AKG Y45BT'''<br />
| bluez 5.28, pulseaudio 6.0<br />
| Pause and resume does not work. Needs {{ic|1=Enable=Socket}} in {{ic|/etc/bluetooth/audio.conf}}.<br />
| {{Yes}}<br />
|}<br />
<br />
== See also ==<br />
<br />
<br />
Using the same device on Windows and Linux without pairing the device over and over again<br />
<br />
* [http://ubuntuforums.org/showthread.php?p=9363229#post9363229 Dual booting with a Bluetooth keyboard]</div>Visithttps://wiki.archlinux.org/index.php?title=Systemd/FAQ&diff=334739Systemd/FAQ2014-09-11T06:23:43Z<p>Visit: Better way of overriding options in default unit files.</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Daemons and system services]]<br />
[[Category:Boot process]]<br />
[[es:Systemd FAQ]]<br />
[[it:Systemd FAQ]]<br />
[[ja:Systemd FAQ]]<br />
[[zh-CN:Systemd FAQ]]<br />
== FAQ ==<br />
<br />
For an up-to-date list of known issues, look at the upstream [http://cgit.freedesktop.org/systemd/systemd/tree/TODO TODO].<br />
<br />
=== Why do I get log messages on my console? ===<br />
<br />
You must set the kernel loglevel yourself. Historically, {{ic|/etc/rc.sysinit}} did this for us and set dmesg loglevel to {{ic|3}}, which was a reasonably quiet loglevel. Either add {{ic|1=loglevel=3}} or {{ic|quiet}} to your [[kernel parameters]].<br />
<br />
=== How do I change the default number of gettys? ===<br />
<br />
Currently, only one getty is launched by default. If you switch to another tty, a getty will be launched there (socket-activation style). In other words, [Ctl] [Alt] [F2] will launch a new getty on tty2.<br />
<br />
By default, the number of auto-activated gettys is capped at six. Thus [F7] through [F12] won't launch a getty.<br />
<br />
If you want to change this behavior, then edit {{ic|/etc/systemd/logind.conf}} and change the value of {{ic|NAutoVTs}}. If you want all [F''x''] keys to start a getty, increase the value of NAutoVTs to 12. If you are [[Systemd#Forward_journald_to_.2Fdev.2Ftty12|forwarding journald to tty12]], increase the value of NAutoVTs to 11 (thus leaving tty12 free).<br />
<br />
You can also pre-activate gettys which will be running from boot.<br />
<br />
To add another pre-activated getty, simply place another symlink for instantiating another getty in the {{ic|/etc/systemd/system/getty.target.wants/}} directory:<br />
<br />
# ln -sf /usr/lib/systemd/system/getty@.service /etc/systemd/system/getty.target.wants/getty@tty9.service<br />
# systemctl start getty@tty9.service<br />
<br />
To remove a getty, simply remove the getty symlinks you want to get rid of in the {{ic|/etc/systemd/system/getty.target.wants/}} directory:<br />
<br />
# rm /etc/systemd/system/getty.target.wants/getty@{tty5,tty6}.service<br />
# systemctl stop getty@tty5.service getty@tty6.service<br />
<br />
systemd does not use the {{ic|/etc/inittab}} file.<br />
<br />
=== How do I get more verbose output during boot? ===<br />
<br />
If you see no output at all in console after the initram message, this means you have the {{ic|quiet}} parameter in your kernel line. It's best to remove it, at least the first time you boot with systemd, to see if everything is ok. Then, you will see a list {{ic|[ OK ]}} in green or {{ic|[ FAILED ]}} in red.<br />
<br />
Any messages are logged to the system log and if you want to find out about the status of your system run {{ic|systemctl}} (no root privileges required) or look at the boot/system log with {{ic|journalctl}}.<br />
<br />
=== How do I avoid clearing the console after boot? ===<br />
<br />
Create a directory called {{ic|/etc/systemd/system/getty@.service.d}} and place {{ic|nodisallocate.conf}} in there to [[Systemd#Editing_provided_unit_files|override]] the {{ic|TTYVTDisallocate}} option to {{ic|no}}.<br />
<br />
{{hc|/etc/systemd/system/getty@.service.d/nodisallocate.conf|2=<br />
[Service]<br />
TTYVTDisallocate=no<br />
}}<br />
<br />
=== What kernel options are required for systemd? ===<br />
<br />
Kernels prior to 3.0 are unsupported. <br />
<br />
If you use a custom kernel, you will need to make sure that systemd's options are selected.<br />
<br />
If you are compiling a new kernel for use with an installed version of systemd, the required and recommended options are listed in the systemd README file {{ic|/usr/share/doc/systemd/README}}.v<br />
<br />
If you are preparing to install a new version of systemd and are running a custom kernel, the most recent version of the file can be found in the [http://cgit.freedesktop.org/systemd/systemd/tree/README the systemd git].<br />
<br />
=== What other units does a unit depend on? ===<br />
<br />
For example, if you want to figure out which services a target like {{ic|multi-user.target}} pulls in, use something like this: <br />
<br />
{{hc|$ systemctl show -p "Wants" multi-user.target|2=<br />
Wants=rc-local.service avahi-daemon.service rpcbind.service NetworkManager.service acpid.service dbus.service atd.service crond.service auditd.service ntpd.service udisks.service bluetooth.service cups.service wpa_supplicant.service getty.target modem-manager.service portreserve.service abrtd.service yum-updatesd.service upowerd.service test-first.service pcscd.service rsyslog.service haldaemon.service remote-fs.target plymouth-quit.service systemd-update-utmp-runlevel.service sendmail.service lvm2-monitor.service cpuspeed.service udev-post.service mdmonitor.service iscsid.service livesys.service livesys-late.service irqbalance.service iscsi.service<br />
}}<br />
<br />
Instead of {{ic|Wants}} you might also try {{ic|WantedBy}}, {{ic|Requires}}, {{ic|RequiredBy}}, {{ic|Conflicts}}, {{ic|ConflictedBy}}, {{ic|Before}}, {{ic|After}} for the respective types of dependencies and their inverse.<br />
<br />
=== My computer shuts down, but the power stays on ===<br />
<br />
Use {{ic|systemctl poweroff}} instead of {{ic|systemctl halt}}.<br />
<br />
=== After migrating to systemd, why won't my fakeRAID mount? ===<br />
<br />
Be sure you use:<br />
<br />
# systemctl enable dmraid.service<br />
<br />
=== How can I make a script start during the boot process? ===<br />
<br />
Create a new file in {{ic|/etc/systemd/system}} (e.g. ''myscript''.service) and add the following contents:<br />
<br />
[Unit]<br />
Description=My script<br />
<br />
[Service]<br />
ExecStart=/usr/bin/my-script<br />
<br />
[Install]<br />
WantedBy=multi-user.target <br />
<br />
Then:<br />
<br />
# systemctl enable ''myscript''.service<br />
<br />
This example assumes you want your script to start up when the target multi-user is launched. Also do {{ic|chmod 755}} to your script to enable execute permissions if you haven't done so already.<br />
<br />
{{Note|In case you want to start a shell script, make sure you have {{ic|#!/bin/sh}} in the first line of the script. Do '''not''' write something like {{ic|<nowiki>ExecStart=/bin/sh /path/to/script.sh</nowiki>}} because that will not work.}}<br />
<br />
=== Status of .service says "active (exited)" in green. (e.g. iptables) ===<br />
<br />
This is perfectly normal. In the case with iptables it is because there is no daemon to run, it is controlled in the kernel. Therefore, it exits after the rules have been loaded.<br />
<br />
To check if your iptables rules have been loaded properly:<br />
<br />
# iptables --list<br />
<br />
=== "Failed to issue method call: File exists" error ===<br />
<br />
This happens when using {{ic|systemctl enable}} and the symlink it tries to create in {{ic|/etc/systemd/system/}} already exists. Typically this happens when switching from one display manager to another one (for instance GDM to KDM, which can be enabled with {{ic|gdm.service}} and {{ic|kdm.service}}, respectively) and the corresponding symlink {{ic|/etc/systemd/system/display-manager.service}} already exists.<br />
<br />
To solve this problem, either first disable the relevant display manager before enabling the new one, or use {{ic|systemctl -f enable}} to overwrite an existing symlink.</div>Visithttps://wiki.archlinux.org/index.php?title=Btrfs&diff=329381Btrfs2014-08-08T22:39:38Z<p>Visit: </p>
<hr />
<div>[[Category:File systems]]<br />
[[ja:Btrfs]]<br />
[[zh-CN:Btrfs]]<br />
{{Related articles start}}<br />
{{Related|File systems}}<br />
{{Related|Btrfs - Tips and tricks}}<br />
{{Related|Mkinitcpio-btrfs}}<br />
{{Related articles end}}<br />
<br />
From [[Wikipedia:Btrfs]]<br />
<br />
:''Btrfs (B-tree file system, variously pronounced: "Butter F S", "Better F S", "B-tree F S", or simply "Bee Tee Arr Eff Ess") is a GPL-licensed experimental copy-on-write file system for Linux. Development began at Oracle Corporation in 2007.''<br />
<br />
From [https://btrfs.wiki.kernel.org/index.php/Main_Page Btrfs Wiki]<br />
<br />
:''Btrfs is a new copy on write (CoW) filesystem for Linux aimed at implementing advanced features while focusing on fault tolerance, repair and easy administration. Jointly developed at Oracle, Red Hat, Fujitsu, Intel, SUSE, STRATO and many others, Btrfs is licensed under the GPL and open for contribution from anyone.''<br />
<br />
{{Warning|<br />
* Btrfs has some features that are considered experimental. See the Btrfs Wiki's [https://btrfs.wiki.kernel.org/index.php/Main_Page#Stability_status Stability status,] [https://btrfs.wiki.kernel.org/index.php/FAQ#Is_btrfs_stable.3F Is Btrfs stable,] and [https://btrfs.wiki.kernel.org/index.php/Getting_started Getting started] for more detailed information.<br />
* Beware of the [[#Limitations|limitations]].<br />
}}<br />
<br />
== Installation ==<br />
<br />
Btrfs is included in the default kernel and its tools ({{Pkg|btrfs-progs}}) are available in the official repositories. [[GRUB]], [[mkinitcpio]], and [[Syslinux]] have support for Btrfs and require no additional configuration.<br />
<br />
=== Additional packages ===<br />
<br />
* {{Pkg|btrfs-progs}} includes ''btrfsck'', a tool that can fix errors on Btrfs filesystems.<br />
* {{AUR|mkinitcpio-btrfs}} enables roll-back abilities.<br />
* {{AUR|btrfs-progs-git}} for nightly<br />
<br />
{{Tip|See [https://btrfs.wiki.kernel.org/index.php/Getting_started Btrfs Wiki Getting Started] for suggestions regarding running Btrfs effectively.}}<br />
<br />
== General administration of Btrfs ==<br />
<br />
=== Creating a new file system ===<br />
<br />
A Btrfs file system can either be newly created or have one converted.<br />
<br />
To format a partition do:<br />
<br />
# mkfs.btrfs -L ''mylabel'' /dev/''partition''<br />
<br />
{{Note|1=As of [https://git.kernel.org/cgit/linux/kernel/git/mason/btrfs-progs.git/commit/?id=c652e4efb8e2dd76ef1627d8cd649c6af5905902 this] commit (November 2013), Btrfs default blocksize is 16KB.}}<br />
<br />
To use a larger blocksize for data/meta data, specify a value for the leafsize via the {{ic|-l}} switch as shown in this example using 16KB blocks:<br />
<br />
# mkfs.btrfs -L ''mylabel'' -l 16k /dev/''partition''<br />
<br />
Multiple devices can be entered to create a RAID. Supported RAID levels include RAID 0, RAID 1, RAID 10, RAID 5 and RAID 6. By default the metadata is mirrored and data is striped. See [https://btrfs.wiki.kernel.org/index.php/Using_Btrfs_with_Multiple_Devices Using Btrfs with Multiple Devices] for more information about how to create a Btrfs RAID volume.<br />
<br />
# mkfs.btrfs [''options''] /dev/''part1'' /dev/''part2''<br />
<br />
=== Convert from Ext3/4 ===<br />
<br />
Boot from an install CD, then convert by doing:<br />
<br />
# btrfs-convert /dev/''partition''<br />
<br />
Mount the partion and test the conversion by checking the files. Be sure to change the {{ic|/etc/fstab}} to reflect the change ('''type''' to {{ic|btrfs}} and '''fs_passno''' [the last field] to {{ic|0}} as Btrfs does not do a file system check on boot). Also note that the UUID of the partition will have changed, so update fstab accordingly when using UUIDs. {{ic|chroot}} into the system and rebuild the GRUB menu list (see [[Install from Existing Linux]] and [[GRUB]] articles). If converting a root filesystem, while still chrooted run {{ic|mkinitcpio -p linux}} to regenerate the initramfs or the system will not successfully boot.<br />
<br />
To complete, delete the saved image, delete the sub-volume that image is on, and finally [[#Balance|balance]] the file system to reclaim the space.<br />
<br />
# rm /ext2_saved/*<br />
# btrfs subvolume delete /ext2_saved<br />
<br />
=== Mount options ===<br />
<br />
See [https://btrfs.wiki.kernel.org/index.php/Mount_options Btrfs Wiki Mount options] and [https://btrfs.wiki.kernel.org/index.php/Gotchas Btrfs Wiki Gotchas] for more information.<br />
<br />
In addition to configurations that can be made during or after file system creation, the various mount options for Btrfs can drastically change its performance characteristics.<br />
<br />
{{Warning|Specific mount options can disable safety features and increase the risk of complete file system corruption. For details, see link above.}}<br />
<br />
As this is a file system that is still in active development. Changes and regressions should be expected. See links in the [[#See also]] section for some benchmarks.<br />
<br />
It is necessary to add the {{ic|btrfs}} hook to initcpio if adding multi-device Btrfs volumes to {{ic|/etc/fstab}} without {{ic|udev}} hook in initcpio.<br />
<br />
==== Examples ====<br />
<br />
{{Note|1=The following examples can decrease performance on less capable hardware. Performance may increase by removing the {{ic|nospace_cache}} option and using {{ic|lzo}} as compression.}}<br />
<br />
* '''Linux 3.14'''<br />
** Btrfs on a SSD for system installation and an emphasis on maximizing performance.<br />
*:{{bc|1=noatime,compress=lzo,ssd,discard,autodefrag}}<br />
** Btrfs on a HDD for archival purposes with an emphasis on maximizing space.<br />
*: {{bc|1=noatime,compress-force=zlib,autodefrag,nospace_cache}}<br />
<br />
Note that since kernel 2.6.31, the {{ic|ssd}} option is automatically set when mounting an SSD drive so is not usually needed.<br />
<br />
=== Displaying used/free space ===<br />
<br />
General linux userspace tools such as {{ic|/usr/bin/df}} will inaccurately report free space on a Btrfs partition since it does not take into account space allocated for and used by the metadata. It is recommended to use {{ic|/usr/bin/btrfs}} to query a btrfs partition. Below is an illustration of this effect, first querying using {{ic|df -h}}, and then using {{ic|btrfs filesystem df}}:<br />
<br />
{{hc|$ df -h /|<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/sda3 119G 3.0G 116G 3% /<br />
}}<br />
<br />
{{hc|$ btrfs filesystem df /|2=<br />
Data: total=3.01GB, used=2.73GB<br />
System: total=4.00MB, used=16.00KB<br />
Metadata: total=1.01GB, used=181.83MB<br />
}}<br />
<br />
Notice that {{ic|df -h}} reports 3.0GB used but {{ic|btrfs filesystem df}} reports 2.73GB for the data. This is due to the way BTRFS allocates space into the pool. The true disk usage is the sum of all three 'used' values which is inferior to 3.0GB as reported by {{ic|df -h}}.<br />
<br />
{{Note|1=If you see an entry of type {{ic|unknown}} in btrfs fi df's output at kernel >= 3.15 this is a display bug. As of [http://thread.gmane.org/gmane.comp.file-systems.btrfs/34419 this patch], the entry means GlobalReserve, which is kind of a buffer for changes not jet flushed. This entry is displayed as {{ic|unknown, single}} in RAID setups and not possible to re-balance.}}<br />
<br />
Another useful command to show a less verbose readout of used space is {{ic|btrfs filesystem show}}:<br />
<br />
{{hc|# btrfs filesystem show /dev/sda3|<br />
failed to open /dev/sr0: No medium found<br />
Label: 'arch64' uuid: 02ad2ea2-be12-2233-8765-9e0a48e9303a<br />
Total devices 1 FS bytes used 2.91GB<br />
devid 1 size 118.95GB used 4.02GB path /dev/sda2<br />
<br />
Btrfs v0.20-rc1-358-g194aa4a-dirty<br />
}}<br />
<br />
== Limitations ==<br />
<br />
A few limitations should be known before trying.<br />
<br />
=== Encryption ===<br />
<br />
Btrfs has no built-in encryption support (this may come in future); users can encrypt the partition before running {{ic|mkfs.btrfs}}. See [[dm-crypt]]. <br />
<br />
Existing Btrfs file system, can use something like [[EncFS]] or [[TrueCrypt]], though perhaps without some of Btrfs' features.<br />
<br />
=== Swap file ===<br />
<br />
Btrfs does not support swap files. This is due to swap files requiring a function that Btrfs doesn't have for possibility of file system corruption [https://btrfs.wiki.kernel.org/index.php/FAQ#Does_btrfs_support_swap_files.3F]. A swap file can be mounted on a loop device with poorer performance but will not be able to hibernate. Install the package {{Pkg|systemd-swap}} from the [[official repositories]] to automate this.<br />
<br />
=== GRUB ===<br />
<br />
==== Partition offset ====<br />
<br />
{{Note|1=The offset problem may happen when you try to embed {{ic|core.img}} into a partitioned disk. It means that [https://wiki.archlinux.org/index.php?title=Talk:Btrfs&diff=319474&oldid=292530 it is OK] to embed grub's {{ic|corg.img}} into a Btrfs pool on a partitionless disk (e.g. {{ic|/dev/sd''X''}}) directly.}}<br />
<br />
[[GRUB]] can boot Btrfs partitions however the module may be larger than other [[file systems]]. And the {{ic|core.img}} file made by {{ic|grub-install}} may not fit in the first 63 sectors (31.5KiB) of the drive between the MBR and the first partition. Up-to-date partitioning tools such as {{ic|fdisk}} and {{ic|gdisk}} avoid this issue by offsetting the first partition by roughly 1MiB or 2MiB.<br />
<br />
==== Missing root ====<br />
<br />
Users experiencing the following: {{ic|1=error no such device: root}} when booting from a RAID style setup then edit /usr/share/grub/grub-mkconfig_lib and remove both quotes from the line {{ic|1=echo " search --no-floppy --fs-uuid --set=root ${hints} ${fs_uuid}"}}. Regenerate the config for grub and the system should boot without an error.<br />
<br />
== Features ==<br />
<br />
Various features are available and can be adjusted.<br />
<br />
=== Copy-On-Write (CoW) ===<br />
<br />
The resolution at which data are written to the filesystem is dictated by Btrfs itself and by system-wide settings. Btrfs defaults to a 30 seconds checkpoint interval in which new data are committed to the filesystem. This is tuneable using mount options (see below)<br />
<br />
System-wide settings also affect commit intervals. They include the files under {{ic|/proc/sys/vm/*}} and are out-of-scope of this wiki article. The kernel documentation for them resides in {{ic|Documentation/sysctl/vm.txt}}.<br />
<br />
CoW comes with some advantages, but can negatively affect performance with large files that have small random writes. It is recommended to disable CoW for database files and virtual machine images. <br />
<br />
One can disable CoW for the entire block device by mounting it with {{ic|nodatacow}} option. However, this will disable CoW for the entire file system.<br />
<br />
{{Note|{{ic|nodatacow}} will only affect newly created file. CoW may still happen for existing file.}}<br />
<br />
To disable CoW for single files/directories do:<br />
<br />
$ chattr +C ''/dir/file''<br />
<br />
{{Note|From chattr man page: For btrfs, the 'C' flag should be set on new or empty files. If it is set on a file which already has data blocks, it is undefined when the blocks assigned to the file will be fully stable. If the 'C' flag is set on a directory, it will have no effect on the directory, but new files created in that directory will have the No_COW attribute.}}<br />
<br />
{{Tip|In accordance with the note above, you can use the following trick to disable CoW on existing files in a directory:<br />
$ mv ''/path/to/dir'' ''/path/to/dir''_old<br />
$ mkdir ''/path/to/dir''<br />
$ chattr +C ''/path/to/dir''<br />
$ cp -a ''/path/to/dir''_old/* ''/path/to/dir''<br />
$ rm -rf ''/path/to/dir''_old<br />
Make sure that the data are not used during this process. Also note that {{ic|mv}} or {{ic|cp --reflink}} as described below will not work.<br />
}}<br />
<br />
Likewise, to save space by forcing CoW when copying files use:<br />
<br />
$ cp --reflink ''source'' ''dest'' <br />
<br />
As {{ic|''dest''}} file is changed, only those blocks that are changed from source will be written to the disk. One might consider aliasing aliasing ''cp'' to {{ic|1=cp --reflink=auto}}.<br />
<br />
=== Multi-device filesystem and RAID feature ===<br />
<br />
==== Multi-device filesystem ====<br />
<br />
When creating a ''btrfs'' filesystem, one can pass many partitions or disk devices to ''mkfs.btrfs''. The filesystem will be created across these devices. One can '''"'''pool'''"''' this way, multiple partitions or devices to get a big ''btrfs'' filesystem.<br />
<br />
One can also add or remove device from an existing btrfs filesystem (caution is mandatory).<br />
<br />
A multi-device ''btrfs'' filesystem (also called a btrfs volume) is not recognized until {{ic|btrfs device scan}} has been run. This is the purpose of the ''btrfs'' mkinitcpio hook.<br />
<br />
==== RAID features ====<br />
<br />
When creating multi-device filesystem, one can also specify to use RAID0, RAID1, RAID10, RAID5 or RAID6 across the devices comprising the filesystem. RAID levels can be applied independently to data and meta data. By default, meta data is duplicated on single volumes or RAID1 on multi-disk sets.<br />
<br />
btrfs works in block-pairs for raid0, raid1, and raid10. This means:<br />
<br />
raid0 - block-pair striped across 2 devices<br />
<br />
raid1 - block-pair written to 2 devices<br />
<br />
For 2 disk sets, this matches raid levels as defined in md-raid (mdadm). For 3+ disk-sets, the result is entirely different than md-raid. <br />
<br />
For example:<br />
* Three 1TB disks in an md based raid1 yields a {{ic|/dev/md0}} with 1TB free space and the ability to safely lose 2 disks without losing data.<br />
* Three 1TB disks in a Btrfs volume with data=raid1 will allow the storage of approximately 1.5TB of data before reporting full. Only 1 disk can safely be lost without losing data.<br />
<br />
Btrfs uses a round-robin scheme to decide how block-pairs are spread among disks. As of Linux 3.0, a quasi-round-robin scheme is used which prefers larger disks when distributing block pairs. This allows raid0 and raid1 to take advantage of most (and sometimes all) space in a disk set made of multiple disks. For example, a set consisting of a 1TB disk and 2 500GB disks with data=raid1 will place a copy of every block on the 1TB disk and alternate (round-robin) placing blocks on each of the 500GB disks. Full space utilization will be made. A set made from a 1TB disk, a 750GB disk, and a 500GB disk will work the same, but the filesystem will report full with 250GB unusable on the 750GB disk. To always take advantage of the full space (even in the last example), use data=single. (data=single is akin to JBOD defined by some raid controllers) See [https://btrfs.wiki.kernel.org/index.php/FAQ#How_much_space_do_I_get_with_unequal_devices_in_RAID-1_mode.3F the BTRFS FAQ] for more info.<br />
<br />
=== Sub-volumes ===<br />
<br />
See the following links for more details:<br />
* [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Subvolumes Btrfs Wiki SysadminGuide#Subvolumes]<br />
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Basic_Filesystem_Commands Btrfs Wiki Getting started#Basic Filessystem Commands]<br />
* [https://btrfs.wiki.kernel.org/index.php/Trees Btrfs Wiki Trees] <br />
<br />
==== Creating sub-volumes ====<br />
<br />
To create a sub-volume:<br />
<br />
# btrfs subvolume create ''subvolume-name''<br />
<br />
==== Listing sub-volumes ====<br />
<br />
To see a list of current sub-volumes:<br />
<br />
# btrfs subvolume list -p .<br />
<br />
==== Setting a default sub-volume ====<br />
<br />
{{Warning|Changing the default subvolume with btrfs subvolume default will make the top level of the filesystem inaccessible, except by use of the {{ic|1=subvolid=0}} mount option. Reference: [https://btrfs.wiki.kernel.org/index.php/SysadminGuide Btrfs Wiki Sysadmin Guide].}}<br />
<br />
The default sub-volume is mounted if no {{ic|1=subvol=}} mount option is provided.<br />
<br />
# btrfs subvolume set-default ''subvolume-id'' /.<br />
<br />
'''Example:'''<br />
<br />
{{hc|# btrfs subvolume list .|<br />
ID 258 gen 9512 top level 5 path root_subvolume<br />
ID 259 gen 9512 top level 258 path home<br />
ID 260 gen 9512 top level 258 path var<br />
ID 261 gen 9512 top level 258 path usr<br />
}}<br />
<br />
# btrfs subvolume set-default 258 .<br />
<br />
'''Reset:'''<br />
<br />
# btrfs subvolume set-default 0 .<br />
<br />
==== Snapshots ====<br />
<br />
See [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Snapshots Btrfs Wiki SysadminGuide#Snapshots] for details.<br />
<br />
To create a snapshot:<br />
<br />
# btrfs subvolume snapshot ''source'' [''dest''/]''name''<br />
<br />
Snapshots are not recursive. Every sub-volume inside sub-volume will be an empty directory inside the snapshot.<br />
<br />
==== Installing with root on btrfs subvolume ====<br />
<br />
{{Moveto||Does not fit into [[#Features]] section, maybe we should start new one...}}<br />
<br />
{{Accuracy|Setting {{ic|rootvol}} as the default subvolume (see [[#Setting a default sub-volume]]) would be much simpler, for both installation and booting.}}<br />
<br />
{{Warning|When using legacy BIOS booting, syslinux is not capable of booting from a btrfs subvolume with the following setup, one must always use GRUB. (It is possible with a different, more complicated btrfs subvolume setup, that is out of the scope of this section.)}}<br />
<br />
For increased flexibility, install the system into a dedicated sub-volume.<br />
Set up a btrfs filesystem as to your liking and mount it to /mnt. The following mkfs command is given as an example.<br />
<br />
# mkfs.btrfs /dev/sda1 <br />
# mount /dev/sda1 /mnt<br />
<br />
Create a subvolume for root, where rootvol is an arbitrary name. If you wish, create additional subvolumes at this step, for example to accommodate /home.<br />
<br />
# cd /mnt<br />
# btrfs subvolume create rootvol<br />
# cd /<br />
# umount /mnt<br />
<br />
Mount the subvolume.<br />
<br />
# mount -o subvol=rootvol /dev/sda1 /mnt<br />
<br />
From here continue the installation process from the pacstrap step, as per the [[Installation guide]] or [[Beginners' guide]].<br />
<br />
Additional considerations:<br />
* In /etc/fstab, the mount option subvol="subvolume-name" has to be specified, and the fsck setting in the last field has to be 0.<br />
* In the kernel boot parameters, use: {{ic|1=rootflags=subvol=''subvolume-name''}}. It is still necessary to add the standard root parameter with {{ic| 1=root=/dev/sda1}}.<br />
* It is advisable to add '''crc32c''' (or '''crc32c-intel''' for Intel machines) to the modules array in {{ic|/etc/mkinitcpio.conf}}<br />
<br />
{{Note|Child sub-volumes are automatically mounted by Btrfs when the parent sub-volume is mounted.}}<br />
<br />
=== Defragmentation ===<br />
<br />
Btrfs supports online defragmentation. To defragment the metadata of the root folder do:<br />
<br />
# btrfs filesystem defragment /<br />
<br />
This ''will not'' defragment the entire file system. For more information read [https://btrfs.wiki.kernel.org/index.php/Problem_FAQ#Defragmenting_a_directory_doesn.27t_work this page] on the btrfs wiki.<br />
<br />
To defragment the entire file system verbosely:<br />
<br />
# btrfs filesystem defragment -r -v /<br />
<br />
{{Note|The command above will defragment only file data. To defragment directory metadata for every directory in the file system, run this command: {{bc|# find / -xdev -type d -print -exec btrfs filesystem defragment '{}' \;}}}}<br />
<br />
=== Compression ===<br />
<br />
Btrfs supports transparent compression, which means every file on the partition is automatically compressed. This does not only reduce the size of those files, but also [http://www.phoronix.com/scan.php?page=article&item=btrfs_compress_2635&num=1 improves performance], in particular if using the [http://www.phoronix.com/scan.php?page=article&item=btrfs_lzo_2638&num=1 lzo algorithm], in some specific use cases (e.g. single tread with heavy file IO), while obviously harming performance on other cases (e.g. multithreaded and/or cpu intensive tasks with large file IO).<br />
<br />
Compression is enabled using the {{ic|1=compress=zlib}} or {{ic|1=compress=lzo}} mount options. Only files created or modified after the mount option is added will be compressed. However, it can be applied quite easily to existing files (e.g. after a conversion from ext3/4) using the {{ic|btrfs filesystem defragment -c''alg''}} command, where {{ic|''alg''}} is either {{ic|zlib}} or {{ic|lzo}}. In order to re-compress the whole file system with {{ic|lzo}}, run the following command:<br />
<br />
# btrfs filesystem defragment -r -v -clzo /<br />
<br />
{{Tip|Compression can also be enabled per-file without using the {{ic|compress}} mount option; simply apply {{ic|chattr +c}} to the file. When applied to directories, it will cause new files to be automatically compressed as they come.}}<br />
<br />
When installing Arch to an empty Btrfs partition, set the {{ic|compress}} option after [[Beginners' guide#Prepare_the_storage_drive|preparing the storage drive]]. Simply switch to another terminal ({{ic|Ctrl+Alt+''number''}}), and run the following command:<br />
<br />
# mount -o remount,compress=lzo /dev/sd''XY'' /mnt/target<br />
<br />
After the installation is finished, add {{ic|1=compress=lzo}} to the mount options of the root file system in [[fstab]].<br />
<br />
=== Checkpoint interval ===<br />
<br />
Starting with Linux 3.12, users are able to change the checkpoint interval from the default 30 s to any value by appending the {{ic|commit}} mount option in {{ic|/etc/fstab}} for the btrfs partition.<br />
<br />
LABEL=arch64 / btrfs defaults,noatime,ssd,compress=lzo,commit=120 0 0<br />
<br />
=== Partitioning ===<br />
<br />
Btrfs can occupy an entire data storage device and replace the [[MBR]] or [[GPT]] partitioning schemes. One can use [[Btrfs#Sub-volumes|subvolumes]] to simulate partitions. There are some limitations to this approach in single disk setups:<br />
<br />
* Cannot use different [[File systems|file systems]] for different [[fstab|mount points]].<br />
* Cannot use [[Swap|swap area]] as Btrfs does not support [[Swap#Swap_file|swap files]] and there is no place to create [[Swap#Swap_partition|swap partition]].<br />
* Cannot use [[UEFI]] to boot.<br />
<br />
To overwrite the existing partition table with Btrfs, run the following command:<br />
<br />
# mkfs.btrfs /dev/sd''X''<br />
<br />
Do not specify {{ic|/dev/sda''X''}} or it will format an existing partition instead of replacing the entire partitioning scheme.<br />
<br />
Install the [[Bootloaders|boot loader]] in a like fashion to installing it for a data storage device with a [[MBR|Master Boot Record]]. For example:<br />
<br />
# grub-install --recheck /dev/sd''X''<br />
<br />
for [[Grub#Install_to_440-byte_MBR_boot_code_region|GRUB]].<br />
<br />
{{Warning|Using the {{ic|btrfs filesystem set-default}} command to change the default sub-volume from anything other than the top level (ID 0) may break Grub. See [[Btrfs#Setting a default sub-volume]] to reset.}}<br />
<br />
=== Scrub ===<br />
<br />
See [https://btrfs.wiki.kernel.org/index.php/Glossary Btrfs Wiki Glossary].<br />
<br />
# btrfs scrub start /<br />
# btrfs scrub status /<br />
<br />
{{Warning|The running scrub process will prevent the system from suspending, see [http://comments.gmane.org/gmane.comp.file-systems.btrfs/33106 this thread] for details.}}<br />
<br />
If running the scrub as a systemd service, use {{ic|1=Type=forking}}. Alternatively, you can pass the "-B" flag to btrfs scrub start to run it in the foreground and use the default Type value.<br />
<br />
=== Balance ===<br />
<br />
See [https://btrfs.wiki.kernel.org/index.php/Glossary Btrfs Wiki Glossary].<br />
<br />
Since {{Pkg|btrfs-progs}}-3.12 ''balancing'' is a background process - see {{ic|man 8 btrfs}} for full description.<br />
<br />
# btrfs balance start /<br />
# btrfs balance status /<br />
<br />
== See also ==<br />
<br />
* '''Official site'''<br />
** [https://btrfs.wiki.kernel.org/ Btrfs Wiki]<br />
** [https://btrfs.wiki.kernel.org/index.php/Glossary Btrfs Wiki Glossary]<br />
* '''Official FAQs'''<br />
** [https://btrfs.wiki.kernel.org/index.php/FAQ Btrfs Wiki FAQ]<br />
** [https://btrfs.wiki.kernel.org/index.php/Problem_FAQ Btrfs Wiki Problem FAQ]<br />
* '''Btrfs pull requests'''<br />
** [http://lkml.indiana.edu/hypermail/linux/kernel/1401.3/03045.html 3.14]<br />
** [http://lkml.indiana.edu/hypermail/linux/kernel/1311.1/03526.html 3.13]<br />
** [http://lkml.indiana.edu/hypermail/linux/kernel/1309.1/02981.html 3.12]<br />
** [http://lkml.indiana.edu/hypermail/linux/kernel/1305.1/01064.html 3.11]<br />
* '''Performance related'''<br />
** [http://superuser.com/questions/432188/should-i-put-my-multi-device-btrfs-filesystem-on-disk-partitions-or-raw-devices Btrfs on raw disks?]<br />
** [http://comments.gmane.org/gmane.comp.file-systems.btrfs/19440 Varying leafsize and nodesize in Btrfs]<br />
** [http://comments.gmane.org/gmane.comp.file-systems.btrfs/15646 Btrfs support for efficient SSD operation (data blocks alignment)]<br />
** [https://btrfs.wiki.kernel.org/index.php/FAQ#Is_Btrfs_optimized_for_SSD.3F Is Btrfs optimized for SSDs?]<br />
** '''Phoronix mount option benchmarking'''<br />
*** [http://www.phoronix.com/scan.php?page=article&item=linux_314_btrfs Linux 3.14]<br />
*** [http://www.phoronix.com/scan.php?page=article&item=linux_btrfs_311&num=1 Linux 3.11]<br />
*** [http://www.phoronix.com/scan.php?page=news_item&px=MTM0OTU Linux 3.9]<br />
*** [http://www.phoronix.com/scan.php?page=article&item=btrfs_linux37_mounts&num=1 Linux 3.7]<br />
*** [http://www.phoronix.com/scan.php?page=article&item=linux_btrfs_options&num=1 Linux 3.2]<br />
** [http://blog.erdemagaoglu.com/post/4605524309/lzo-vs-snappy-vs-lzf-vs-zlib-a-comparison-of Lzo vs. zLib]<br />
* '''Miscellaneous'''<br />
** [http://www.funtoo.org/wiki/BTRFS_Fun Funtoo Wiki Btrfs Fun]<br />
** [http://www.phoronix.com/scan.php?page=news_item&px=MTA0ODU Avi Miller presenting Btrfs] at SCALE 10x, January 2012.<br />
** [http://www.phoronix.com/scan.php?page=news_item&px=MTA4Mzc Summary of Chris Mason's talk] from LFCS 2012<br />
** [http://git.kernel.org/?p&#61;linux/kernel/git/torvalds/linux-2.6.git;a&#61;commit;h&#61;35054394c4b3cecd52577c2662c84da1f3e73525 Btrfs: stop providing a bmap operation to avoid swapfile corruptions] 2009-01-21<br />
** [http://marc.merlins.org/perso/btrfs/post_2014-03-22_Btrfs-Tips_-Doing-Fast-Incremental-Backups-With-Btrfs-Send-and-Receive.html Doing Fast Incremental Backups With Btrfs Send and Receive]</div>Visithttps://wiki.archlinux.org/index.php?title=Btrfs&diff=329380Btrfs2014-08-08T22:36:01Z<p>Visit: Short info about df output type: unknown</p>
<hr />
<div>[[Category:File systems]]<br />
[[ja:Btrfs]]<br />
[[zh-CN:Btrfs]]<br />
{{Related articles start}}<br />
{{Related|File systems}}<br />
{{Related|Btrfs - Tips and tricks}}<br />
{{Related|Mkinitcpio-btrfs}}<br />
{{Related articles end}}<br />
<br />
From [[Wikipedia:Btrfs]]<br />
<br />
:''Btrfs (B-tree file system, variously pronounced: "Butter F S", "Better F S", "B-tree F S", or simply "Bee Tee Arr Eff Ess") is a GPL-licensed experimental copy-on-write file system for Linux. Development began at Oracle Corporation in 2007.''<br />
<br />
From [https://btrfs.wiki.kernel.org/index.php/Main_Page Btrfs Wiki]<br />
<br />
:''Btrfs is a new copy on write (CoW) filesystem for Linux aimed at implementing advanced features while focusing on fault tolerance, repair and easy administration. Jointly developed at Oracle, Red Hat, Fujitsu, Intel, SUSE, STRATO and many others, Btrfs is licensed under the GPL and open for contribution from anyone.''<br />
<br />
{{Warning|<br />
* Btrfs has some features that are considered experimental. See the Btrfs Wiki's [https://btrfs.wiki.kernel.org/index.php/Main_Page#Stability_status Stability status,] [https://btrfs.wiki.kernel.org/index.php/FAQ#Is_btrfs_stable.3F Is Btrfs stable,] and [https://btrfs.wiki.kernel.org/index.php/Getting_started Getting started] for more detailed information.<br />
* Beware of the [[#Limitations|limitations]].<br />
}}<br />
<br />
== Installation ==<br />
<br />
Btrfs is included in the default kernel and its tools ({{Pkg|btrfs-progs}}) are available in the official repositories. [[GRUB]], [[mkinitcpio]], and [[Syslinux]] have support for Btrfs and require no additional configuration.<br />
<br />
=== Additional packages ===<br />
<br />
* {{Pkg|btrfs-progs}} includes ''btrfsck'', a tool that can fix errors on Btrfs filesystems.<br />
* {{AUR|mkinitcpio-btrfs}} enables roll-back abilities.<br />
* {{AUR|btrfs-progs-git}} for nightly<br />
<br />
{{Tip|See [https://btrfs.wiki.kernel.org/index.php/Getting_started Btrfs Wiki Getting Started] for suggestions regarding running Btrfs effectively.}}<br />
<br />
== General administration of Btrfs ==<br />
<br />
=== Creating a new file system ===<br />
<br />
A Btrfs file system can either be newly created or have one converted.<br />
<br />
To format a partition do:<br />
<br />
# mkfs.btrfs -L ''mylabel'' /dev/''partition''<br />
<br />
{{Note|1=As of [https://git.kernel.org/cgit/linux/kernel/git/mason/btrfs-progs.git/commit/?id=c652e4efb8e2dd76ef1627d8cd649c6af5905902 this] commit (November 2013), Btrfs default blocksize is 16KB.}}<br />
<br />
To use a larger blocksize for data/meta data, specify a value for the leafsize via the {{ic|-l}} switch as shown in this example using 16KB blocks:<br />
<br />
# mkfs.btrfs -L ''mylabel'' -l 16k /dev/''partition''<br />
<br />
Multiple devices can be entered to create a RAID. Supported RAID levels include RAID 0, RAID 1, RAID 10, RAID 5 and RAID 6. By default the metadata is mirrored and data is striped. See [https://btrfs.wiki.kernel.org/index.php/Using_Btrfs_with_Multiple_Devices Using Btrfs with Multiple Devices] for more information about how to create a Btrfs RAID volume.<br />
<br />
# mkfs.btrfs [''options''] /dev/''part1'' /dev/''part2''<br />
<br />
=== Convert from Ext3/4 ===<br />
<br />
Boot from an install CD, then convert by doing:<br />
<br />
# btrfs-convert /dev/''partition''<br />
<br />
Mount the partion and test the conversion by checking the files. Be sure to change the {{ic|/etc/fstab}} to reflect the change ('''type''' to {{ic|btrfs}} and '''fs_passno''' [the last field] to {{ic|0}} as Btrfs does not do a file system check on boot). Also note that the UUID of the partition will have changed, so update fstab accordingly when using UUIDs. {{ic|chroot}} into the system and rebuild the GRUB menu list (see [[Install from Existing Linux]] and [[GRUB]] articles). If converting a root filesystem, while still chrooted run {{ic|mkinitcpio -p linux}} to regenerate the initramfs or the system will not successfully boot.<br />
<br />
To complete, delete the saved image, delete the sub-volume that image is on, and finally [[#Balance|balance]] the file system to reclaim the space.<br />
<br />
# rm /ext2_saved/*<br />
# btrfs subvolume delete /ext2_saved<br />
<br />
=== Mount options ===<br />
<br />
See [https://btrfs.wiki.kernel.org/index.php/Mount_options Btrfs Wiki Mount options] and [https://btrfs.wiki.kernel.org/index.php/Gotchas Btrfs Wiki Gotchas] for more information.<br />
<br />
In addition to configurations that can be made during or after file system creation, the various mount options for Btrfs can drastically change its performance characteristics.<br />
<br />
{{Warning|Specific mount options can disable safety features and increase the risk of complete file system corruption. For details, see link above.}}<br />
<br />
As this is a file system that is still in active development. Changes and regressions should be expected. See links in the [[#See also]] section for some benchmarks.<br />
<br />
It is necessary to add the {{ic|btrfs}} hook to initcpio if adding multi-device Btrfs volumes to {{ic|/etc/fstab}} without {{ic|udev}} hook in initcpio.<br />
<br />
==== Examples ====<br />
<br />
{{Note|1=The following examples can decrease performance on less capable hardware. Performance may increase by removing the {{ic|nospace_cache}} option and using {{ic|lzo}} as compression.}}<br />
<br />
* '''Linux 3.14'''<br />
** Btrfs on a SSD for system installation and an emphasis on maximizing performance.<br />
*:{{bc|1=noatime,compress=lzo,ssd,discard,autodefrag}}<br />
** Btrfs on a HDD for archival purposes with an emphasis on maximizing space.<br />
*: {{bc|1=noatime,compress-force=zlib,autodefrag,nospace_cache}}<br />
<br />
Note that since kernel 2.6.31, the {{ic|ssd}} option is automatically set when mounting an SSD drive so is not usually needed.<br />
<br />
=== Displaying used/free space ===<br />
<br />
General linux userspace tools such as {{ic|/usr/bin/df}} will inaccurately report free space on a Btrfs partition since it does not take into account space allocated for and used by the metadata. It is recommended to use {{ic|/usr/bin/btrfs}} to query a btrfs partition. Below is an illustration of this effect, first querying using {{ic|df -h}}, and then using {{ic|btrfs filesystem df}}:<br />
<br />
{{hc|$ df -h /|<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/sda3 119G 3.0G 116G 3% /<br />
}}<br />
<br />
{{hc|$ btrfs filesystem df /|2=<br />
Data: total=3.01GB, used=2.73GB<br />
System: total=4.00MB, used=16.00KB<br />
Metadata: total=1.01GB, used=181.83MB<br />
}}<br />
<br />
Notice that {{ic|df -h}} reports 3.0GB used but {{ic|btrfs filesystem df}} reports 2.73GB for the data. This is due to the way BTRFS allocates space into the pool. The true disk usage is the sum of all three 'used' values which is inferior to 3.0GB as reported by {{ic|df -h}}.<br />
<br />
{{Note|1=If you see an entry of type {{ic|unknown}} in btrfs fi df's output at kernel >= 3.15 this is a display bug. As of [http://thread.gmane.org/gmane.comp.file-systems.btrfs/34419 this patch], the entry means GlobalReserve, which is kind of a buffer for changes not jet flushed.}}<br />
<br />
Another useful command to show a less verbose readout of used space is {{ic|btrfs filesystem show}}:<br />
<br />
{{hc|# btrfs filesystem show /dev/sda3|<br />
failed to open /dev/sr0: No medium found<br />
Label: 'arch64' uuid: 02ad2ea2-be12-2233-8765-9e0a48e9303a<br />
Total devices 1 FS bytes used 2.91GB<br />
devid 1 size 118.95GB used 4.02GB path /dev/sda2<br />
<br />
Btrfs v0.20-rc1-358-g194aa4a-dirty<br />
}}<br />
<br />
== Limitations ==<br />
<br />
A few limitations should be known before trying.<br />
<br />
=== Encryption ===<br />
<br />
Btrfs has no built-in encryption support (this may come in future); users can encrypt the partition before running {{ic|mkfs.btrfs}}. See [[dm-crypt]]. <br />
<br />
Existing Btrfs file system, can use something like [[EncFS]] or [[TrueCrypt]], though perhaps without some of Btrfs' features.<br />
<br />
=== Swap file ===<br />
<br />
Btrfs does not support swap files. This is due to swap files requiring a function that Btrfs doesn't have for possibility of file system corruption [https://btrfs.wiki.kernel.org/index.php/FAQ#Does_btrfs_support_swap_files.3F]. A swap file can be mounted on a loop device with poorer performance but will not be able to hibernate. Install the package {{Pkg|systemd-swap}} from the [[official repositories]] to automate this.<br />
<br />
=== GRUB ===<br />
<br />
==== Partition offset ====<br />
<br />
{{Note|1=The offset problem may happen when you try to embed {{ic|core.img}} into a partitioned disk. It means that [https://wiki.archlinux.org/index.php?title=Talk:Btrfs&diff=319474&oldid=292530 it is OK] to embed grub's {{ic|corg.img}} into a Btrfs pool on a partitionless disk (e.g. {{ic|/dev/sd''X''}}) directly.}}<br />
<br />
[[GRUB]] can boot Btrfs partitions however the module may be larger than other [[file systems]]. And the {{ic|core.img}} file made by {{ic|grub-install}} may not fit in the first 63 sectors (31.5KiB) of the drive between the MBR and the first partition. Up-to-date partitioning tools such as {{ic|fdisk}} and {{ic|gdisk}} avoid this issue by offsetting the first partition by roughly 1MiB or 2MiB.<br />
<br />
==== Missing root ====<br />
<br />
Users experiencing the following: {{ic|1=error no such device: root}} when booting from a RAID style setup then edit /usr/share/grub/grub-mkconfig_lib and remove both quotes from the line {{ic|1=echo " search --no-floppy --fs-uuid --set=root ${hints} ${fs_uuid}"}}. Regenerate the config for grub and the system should boot without an error.<br />
<br />
== Features ==<br />
<br />
Various features are available and can be adjusted.<br />
<br />
=== Copy-On-Write (CoW) ===<br />
<br />
The resolution at which data are written to the filesystem is dictated by Btrfs itself and by system-wide settings. Btrfs defaults to a 30 seconds checkpoint interval in which new data are committed to the filesystem. This is tuneable using mount options (see below)<br />
<br />
System-wide settings also affect commit intervals. They include the files under {{ic|/proc/sys/vm/*}} and are out-of-scope of this wiki article. The kernel documentation for them resides in {{ic|Documentation/sysctl/vm.txt}}.<br />
<br />
CoW comes with some advantages, but can negatively affect performance with large files that have small random writes. It is recommended to disable CoW for database files and virtual machine images. <br />
<br />
One can disable CoW for the entire block device by mounting it with {{ic|nodatacow}} option. However, this will disable CoW for the entire file system.<br />
<br />
{{Note|{{ic|nodatacow}} will only affect newly created file. CoW may still happen for existing file.}}<br />
<br />
To disable CoW for single files/directories do:<br />
<br />
$ chattr +C ''/dir/file''<br />
<br />
{{Note|From chattr man page: For btrfs, the 'C' flag should be set on new or empty files. If it is set on a file which already has data blocks, it is undefined when the blocks assigned to the file will be fully stable. If the 'C' flag is set on a directory, it will have no effect on the directory, but new files created in that directory will have the No_COW attribute.}}<br />
<br />
{{Tip|In accordance with the note above, you can use the following trick to disable CoW on existing files in a directory:<br />
$ mv ''/path/to/dir'' ''/path/to/dir''_old<br />
$ mkdir ''/path/to/dir''<br />
$ chattr +C ''/path/to/dir''<br />
$ cp -a ''/path/to/dir''_old/* ''/path/to/dir''<br />
$ rm -rf ''/path/to/dir''_old<br />
Make sure that the data are not used during this process. Also note that {{ic|mv}} or {{ic|cp --reflink}} as described below will not work.<br />
}}<br />
<br />
Likewise, to save space by forcing CoW when copying files use:<br />
<br />
$ cp --reflink ''source'' ''dest'' <br />
<br />
As {{ic|''dest''}} file is changed, only those blocks that are changed from source will be written to the disk. One might consider aliasing aliasing ''cp'' to {{ic|1=cp --reflink=auto}}.<br />
<br />
=== Multi-device filesystem and RAID feature ===<br />
<br />
==== Multi-device filesystem ====<br />
<br />
When creating a ''btrfs'' filesystem, one can pass many partitions or disk devices to ''mkfs.btrfs''. The filesystem will be created across these devices. One can '''"'''pool'''"''' this way, multiple partitions or devices to get a big ''btrfs'' filesystem.<br />
<br />
One can also add or remove device from an existing btrfs filesystem (caution is mandatory).<br />
<br />
A multi-device ''btrfs'' filesystem (also called a btrfs volume) is not recognized until {{ic|btrfs device scan}} has been run. This is the purpose of the ''btrfs'' mkinitcpio hook.<br />
<br />
==== RAID features ====<br />
<br />
When creating multi-device filesystem, one can also specify to use RAID0, RAID1, RAID10, RAID5 or RAID6 across the devices comprising the filesystem. RAID levels can be applied independently to data and meta data. By default, meta data is duplicated on single volumes or RAID1 on multi-disk sets.<br />
<br />
btrfs works in block-pairs for raid0, raid1, and raid10. This means:<br />
<br />
raid0 - block-pair striped across 2 devices<br />
<br />
raid1 - block-pair written to 2 devices<br />
<br />
For 2 disk sets, this matches raid levels as defined in md-raid (mdadm). For 3+ disk-sets, the result is entirely different than md-raid. <br />
<br />
For example:<br />
* Three 1TB disks in an md based raid1 yields a {{ic|/dev/md0}} with 1TB free space and the ability to safely lose 2 disks without losing data.<br />
* Three 1TB disks in a Btrfs volume with data=raid1 will allow the storage of approximately 1.5TB of data before reporting full. Only 1 disk can safely be lost without losing data.<br />
<br />
Btrfs uses a round-robin scheme to decide how block-pairs are spread among disks. As of Linux 3.0, a quasi-round-robin scheme is used which prefers larger disks when distributing block pairs. This allows raid0 and raid1 to take advantage of most (and sometimes all) space in a disk set made of multiple disks. For example, a set consisting of a 1TB disk and 2 500GB disks with data=raid1 will place a copy of every block on the 1TB disk and alternate (round-robin) placing blocks on each of the 500GB disks. Full space utilization will be made. A set made from a 1TB disk, a 750GB disk, and a 500GB disk will work the same, but the filesystem will report full with 250GB unusable on the 750GB disk. To always take advantage of the full space (even in the last example), use data=single. (data=single is akin to JBOD defined by some raid controllers) See [https://btrfs.wiki.kernel.org/index.php/FAQ#How_much_space_do_I_get_with_unequal_devices_in_RAID-1_mode.3F the BTRFS FAQ] for more info.<br />
<br />
=== Sub-volumes ===<br />
<br />
See the following links for more details:<br />
* [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Subvolumes Btrfs Wiki SysadminGuide#Subvolumes]<br />
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Basic_Filesystem_Commands Btrfs Wiki Getting started#Basic Filessystem Commands]<br />
* [https://btrfs.wiki.kernel.org/index.php/Trees Btrfs Wiki Trees] <br />
<br />
==== Creating sub-volumes ====<br />
<br />
To create a sub-volume:<br />
<br />
# btrfs subvolume create ''subvolume-name''<br />
<br />
==== Listing sub-volumes ====<br />
<br />
To see a list of current sub-volumes:<br />
<br />
# btrfs subvolume list -p .<br />
<br />
==== Setting a default sub-volume ====<br />
<br />
{{Warning|Changing the default subvolume with btrfs subvolume default will make the top level of the filesystem inaccessible, except by use of the {{ic|1=subvolid=0}} mount option. Reference: [https://btrfs.wiki.kernel.org/index.php/SysadminGuide Btrfs Wiki Sysadmin Guide].}}<br />
<br />
The default sub-volume is mounted if no {{ic|1=subvol=}} mount option is provided.<br />
<br />
# btrfs subvolume set-default ''subvolume-id'' /.<br />
<br />
'''Example:'''<br />
<br />
{{hc|# btrfs subvolume list .|<br />
ID 258 gen 9512 top level 5 path root_subvolume<br />
ID 259 gen 9512 top level 258 path home<br />
ID 260 gen 9512 top level 258 path var<br />
ID 261 gen 9512 top level 258 path usr<br />
}}<br />
<br />
# btrfs subvolume set-default 258 .<br />
<br />
'''Reset:'''<br />
<br />
# btrfs subvolume set-default 0 .<br />
<br />
==== Snapshots ====<br />
<br />
See [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Snapshots Btrfs Wiki SysadminGuide#Snapshots] for details.<br />
<br />
To create a snapshot:<br />
<br />
# btrfs subvolume snapshot ''source'' [''dest''/]''name''<br />
<br />
Snapshots are not recursive. Every sub-volume inside sub-volume will be an empty directory inside the snapshot.<br />
<br />
==== Installing with root on btrfs subvolume ====<br />
<br />
{{Moveto||Does not fit into [[#Features]] section, maybe we should start new one...}}<br />
<br />
{{Accuracy|Setting {{ic|rootvol}} as the default subvolume (see [[#Setting a default sub-volume]]) would be much simpler, for both installation and booting.}}<br />
<br />
{{Warning|When using legacy BIOS booting, syslinux is not capable of booting from a btrfs subvolume with the following setup, one must always use GRUB. (It is possible with a different, more complicated btrfs subvolume setup, that is out of the scope of this section.)}}<br />
<br />
For increased flexibility, install the system into a dedicated sub-volume.<br />
Set up a btrfs filesystem as to your liking and mount it to /mnt. The following mkfs command is given as an example.<br />
<br />
# mkfs.btrfs /dev/sda1 <br />
# mount /dev/sda1 /mnt<br />
<br />
Create a subvolume for root, where rootvol is an arbitrary name. If you wish, create additional subvolumes at this step, for example to accommodate /home.<br />
<br />
# cd /mnt<br />
# btrfs subvolume create rootvol<br />
# cd /<br />
# umount /mnt<br />
<br />
Mount the subvolume.<br />
<br />
# mount -o subvol=rootvol /dev/sda1 /mnt<br />
<br />
From here continue the installation process from the pacstrap step, as per the [[Installation guide]] or [[Beginners' guide]].<br />
<br />
Additional considerations:<br />
* In /etc/fstab, the mount option subvol="subvolume-name" has to be specified, and the fsck setting in the last field has to be 0.<br />
* In the kernel boot parameters, use: {{ic|1=rootflags=subvol=''subvolume-name''}}. It is still necessary to add the standard root parameter with {{ic| 1=root=/dev/sda1}}.<br />
* It is advisable to add '''crc32c''' (or '''crc32c-intel''' for Intel machines) to the modules array in {{ic|/etc/mkinitcpio.conf}}<br />
<br />
{{Note|Child sub-volumes are automatically mounted by Btrfs when the parent sub-volume is mounted.}}<br />
<br />
=== Defragmentation ===<br />
<br />
Btrfs supports online defragmentation. To defragment the metadata of the root folder do:<br />
<br />
# btrfs filesystem defragment /<br />
<br />
This ''will not'' defragment the entire file system. For more information read [https://btrfs.wiki.kernel.org/index.php/Problem_FAQ#Defragmenting_a_directory_doesn.27t_work this page] on the btrfs wiki.<br />
<br />
To defragment the entire file system verbosely:<br />
<br />
# btrfs filesystem defragment -r -v /<br />
<br />
{{Note|The command above will defragment only file data. To defragment directory metadata for every directory in the file system, run this command: {{bc|# find / -xdev -type d -print -exec btrfs filesystem defragment '{}' \;}}}}<br />
<br />
=== Compression ===<br />
<br />
Btrfs supports transparent compression, which means every file on the partition is automatically compressed. This does not only reduce the size of those files, but also [http://www.phoronix.com/scan.php?page=article&item=btrfs_compress_2635&num=1 improves performance], in particular if using the [http://www.phoronix.com/scan.php?page=article&item=btrfs_lzo_2638&num=1 lzo algorithm], in some specific use cases (e.g. single tread with heavy file IO), while obviously harming performance on other cases (e.g. multithreaded and/or cpu intensive tasks with large file IO).<br />
<br />
Compression is enabled using the {{ic|1=compress=zlib}} or {{ic|1=compress=lzo}} mount options. Only files created or modified after the mount option is added will be compressed. However, it can be applied quite easily to existing files (e.g. after a conversion from ext3/4) using the {{ic|btrfs filesystem defragment -c''alg''}} command, where {{ic|''alg''}} is either {{ic|zlib}} or {{ic|lzo}}. In order to re-compress the whole file system with {{ic|lzo}}, run the following command:<br />
<br />
# btrfs filesystem defragment -r -v -clzo /<br />
<br />
{{Tip|Compression can also be enabled per-file without using the {{ic|compress}} mount option; simply apply {{ic|chattr +c}} to the file. When applied to directories, it will cause new files to be automatically compressed as they come.}}<br />
<br />
When installing Arch to an empty Btrfs partition, set the {{ic|compress}} option after [[Beginners' guide#Prepare_the_storage_drive|preparing the storage drive]]. Simply switch to another terminal ({{ic|Ctrl+Alt+''number''}}), and run the following command:<br />
<br />
# mount -o remount,compress=lzo /dev/sd''XY'' /mnt/target<br />
<br />
After the installation is finished, add {{ic|1=compress=lzo}} to the mount options of the root file system in [[fstab]].<br />
<br />
=== Checkpoint interval ===<br />
<br />
Starting with Linux 3.12, users are able to change the checkpoint interval from the default 30 s to any value by appending the {{ic|commit}} mount option in {{ic|/etc/fstab}} for the btrfs partition.<br />
<br />
LABEL=arch64 / btrfs defaults,noatime,ssd,compress=lzo,commit=120 0 0<br />
<br />
=== Partitioning ===<br />
<br />
Btrfs can occupy an entire data storage device and replace the [[MBR]] or [[GPT]] partitioning schemes. One can use [[Btrfs#Sub-volumes|subvolumes]] to simulate partitions. There are some limitations to this approach in single disk setups:<br />
<br />
* Cannot use different [[File systems|file systems]] for different [[fstab|mount points]].<br />
* Cannot use [[Swap|swap area]] as Btrfs does not support [[Swap#Swap_file|swap files]] and there is no place to create [[Swap#Swap_partition|swap partition]].<br />
* Cannot use [[UEFI]] to boot.<br />
<br />
To overwrite the existing partition table with Btrfs, run the following command:<br />
<br />
# mkfs.btrfs /dev/sd''X''<br />
<br />
Do not specify {{ic|/dev/sda''X''}} or it will format an existing partition instead of replacing the entire partitioning scheme.<br />
<br />
Install the [[Bootloaders|boot loader]] in a like fashion to installing it for a data storage device with a [[MBR|Master Boot Record]]. For example:<br />
<br />
# grub-install --recheck /dev/sd''X''<br />
<br />
for [[Grub#Install_to_440-byte_MBR_boot_code_region|GRUB]].<br />
<br />
{{Warning|Using the {{ic|btrfs filesystem set-default}} command to change the default sub-volume from anything other than the top level (ID 0) may break Grub. See [[Btrfs#Setting a default sub-volume]] to reset.}}<br />
<br />
=== Scrub ===<br />
<br />
See [https://btrfs.wiki.kernel.org/index.php/Glossary Btrfs Wiki Glossary].<br />
<br />
# btrfs scrub start /<br />
# btrfs scrub status /<br />
<br />
{{Warning|The running scrub process will prevent the system from suspending, see [http://comments.gmane.org/gmane.comp.file-systems.btrfs/33106 this thread] for details.}}<br />
<br />
If running the scrub as a systemd service, use {{ic|1=Type=forking}}. Alternatively, you can pass the "-B" flag to btrfs scrub start to run it in the foreground and use the default Type value.<br />
<br />
=== Balance ===<br />
<br />
See [https://btrfs.wiki.kernel.org/index.php/Glossary Btrfs Wiki Glossary].<br />
<br />
Since {{Pkg|btrfs-progs}}-3.12 ''balancing'' is a background process - see {{ic|man 8 btrfs}} for full description.<br />
<br />
# btrfs balance start /<br />
# btrfs balance status /<br />
<br />
== See also ==<br />
<br />
* '''Official site'''<br />
** [https://btrfs.wiki.kernel.org/ Btrfs Wiki]<br />
** [https://btrfs.wiki.kernel.org/index.php/Glossary Btrfs Wiki Glossary]<br />
* '''Official FAQs'''<br />
** [https://btrfs.wiki.kernel.org/index.php/FAQ Btrfs Wiki FAQ]<br />
** [https://btrfs.wiki.kernel.org/index.php/Problem_FAQ Btrfs Wiki Problem FAQ]<br />
* '''Btrfs pull requests'''<br />
** [http://lkml.indiana.edu/hypermail/linux/kernel/1401.3/03045.html 3.14]<br />
** [http://lkml.indiana.edu/hypermail/linux/kernel/1311.1/03526.html 3.13]<br />
** [http://lkml.indiana.edu/hypermail/linux/kernel/1309.1/02981.html 3.12]<br />
** [http://lkml.indiana.edu/hypermail/linux/kernel/1305.1/01064.html 3.11]<br />
* '''Performance related'''<br />
** [http://superuser.com/questions/432188/should-i-put-my-multi-device-btrfs-filesystem-on-disk-partitions-or-raw-devices Btrfs on raw disks?]<br />
** [http://comments.gmane.org/gmane.comp.file-systems.btrfs/19440 Varying leafsize and nodesize in Btrfs]<br />
** [http://comments.gmane.org/gmane.comp.file-systems.btrfs/15646 Btrfs support for efficient SSD operation (data blocks alignment)]<br />
** [https://btrfs.wiki.kernel.org/index.php/FAQ#Is_Btrfs_optimized_for_SSD.3F Is Btrfs optimized for SSDs?]<br />
** '''Phoronix mount option benchmarking'''<br />
*** [http://www.phoronix.com/scan.php?page=article&item=linux_314_btrfs Linux 3.14]<br />
*** [http://www.phoronix.com/scan.php?page=article&item=linux_btrfs_311&num=1 Linux 3.11]<br />
*** [http://www.phoronix.com/scan.php?page=news_item&px=MTM0OTU Linux 3.9]<br />
*** [http://www.phoronix.com/scan.php?page=article&item=btrfs_linux37_mounts&num=1 Linux 3.7]<br />
*** [http://www.phoronix.com/scan.php?page=article&item=linux_btrfs_options&num=1 Linux 3.2]<br />
** [http://blog.erdemagaoglu.com/post/4605524309/lzo-vs-snappy-vs-lzf-vs-zlib-a-comparison-of Lzo vs. zLib]<br />
* '''Miscellaneous'''<br />
** [http://www.funtoo.org/wiki/BTRFS_Fun Funtoo Wiki Btrfs Fun]<br />
** [http://www.phoronix.com/scan.php?page=news_item&px=MTA0ODU Avi Miller presenting Btrfs] at SCALE 10x, January 2012.<br />
** [http://www.phoronix.com/scan.php?page=news_item&px=MTA4Mzc Summary of Chris Mason's talk] from LFCS 2012<br />
** [http://git.kernel.org/?p&#61;linux/kernel/git/torvalds/linux-2.6.git;a&#61;commit;h&#61;35054394c4b3cecd52577c2662c84da1f3e73525 Btrfs: stop providing a bmap operation to avoid swapfile corruptions] 2009-01-21<br />
** [http://marc.merlins.org/perso/btrfs/post_2014-03-22_Btrfs-Tips_-Doing-Fast-Incremental-Backups-With-Btrfs-Send-and-Receive.html Doing Fast Incremental Backups With Btrfs Send and Receive]</div>Visithttps://wiki.archlinux.org/index.php?title=Gitweb&diff=304613Gitweb2014-03-15T15:06:22Z<p>Visit: </p>
<hr />
<div>[[Category:Version Control System]]<br />
Gitweb is the default web interface provided with [[git]] itself and is the basis for other git scripts like [[cgit]], [[gitosis]] and others.<br />
<br />
gitweb actually supports fcgi natively, so you don't need to wrap it as a cgi script http://repo.or.cz/w/alt-git.git?a=blob_plain;f=gitweb/INSTALL https://sixohthree.com/1402/running-gitweb-in-fastcgi-mode<br />
<br />
== Installation ==<br />
<br />
To install gitweb you first have to install {{Pkg|git}} and a webserver. For this example we use {{Pkg|apache}} but you can also use {{Pkg|nginx}}, {{Pkg|lighttpd}} or others.<br />
<br />
Next you need to link the current gitweb default to your webserver location. In this example I use the default folder locations:<br />
# ln -s /usr/share/gitweb /srv/http/gitweb<br />
<br />
{{Note|1=You may want to double check the server directory to make sure the symbolic links were made.}}<br />
<br />
== Configuration ==<br />
<br />
=== Apache ===<br />
<br />
Add the following to the end of your {{ic|/etc/httpd/conf/httpd.conf}}<br />
<Directory "/srv/http/gitweb"><br />
DirectoryIndex gitweb.cgi<br />
Allow from all<br />
AllowOverride all<br />
Order allow,deny<br />
Options ExecCGI<br />
<Files gitweb.cgi><br />
SetHandler cgi-script<br />
</Files><br />
SetEnv GITWEB_CONFIG /etc/conf.d/gitweb.conf<br />
</Directory><br />
<br />
If using a virtualhosts configuration, add this to {{ic|/etc/httpd/conf/extra/httpd-vhosts.conf}}<br />
<VirtualHost *:80><br />
ServerName gitserver<br />
DocumentRoot /var/www/gitweb<br />
<Directory /var/www/gitweb><br />
Options ExecCGI +FollowSymLinks +SymLinksIfOwnerMatch<br />
AllowOverride All<br />
order allow,deny<br />
Allow from all<br />
AddHandler cgi-script cgi<br />
DirectoryIndex gitweb.cgi<br />
</Directory><br />
</VirtualHost><br />
<br />
You could also put the configuration in it's own config file in {{ic|/etc/httpd/conf/extra/}} but that's up to you to decide.<br />
<br />
==== Apache 2.4 ====<br />
<br />
For Apache 2.4 you need to install {{Pkg|mod_perl}} along with {{Pkg|git}} and {{Pkg|apache}}.<br />
<br />
Create {{ic|/etc/httpd/conf/extra/httpd-gitweb.conf}}<br />
<IfModule mod_perl.c><br />
Alias /gitweb "/usr/share/gitweb"<br />
<Directory "/usr/share/gitweb"><br />
DirectoryIndex gitweb.cgi<br />
Require all granted<br />
Options ExecCGI<br />
AddHandler perl-script .cgi<br />
PerlResponseHandler ModPerl::Registry<br />
PerlOptions +ParseHeaders<br />
SetEnv GITWEB_CONFIG /etc/conf.d/gitweb<br />
</Directory><br />
</IfModule><br />
<br />
Add the following line to the modules section of {{ic|/etc/httpd/conf/httpd.conf}}<br />
LoadModule perl_module modules/mod_perl.so<br />
<br />
Add the following line to the end of {{ic|/etc/httpd/conf/httpd.conf}}<br />
# gitweb configuration<br />
Include conf/extra/httpd-gitweb.conf<br />
<br />
=== Lighttpd ===<br />
<br />
Add the following to {{ic|/etc/lighttpd/lighttpd.conf}}:<br />
server.modules += ( "mod_alias", "mod_cgi", "mod_redirect", "mod_setenv" )<br />
setenv.add-environment = ( "GITWEB_CONFIG" => "/etc/conf.d/gitweb.conf" )<br />
url.redirect += ( "^/gitweb$" => "/gitweb/" )<br />
alias.url += ( "/gitweb/" => "/usr/share/gitweb/" )<br />
$HTTP["url"] =~ "^/gitweb/" {<br />
cgi.assign = ( ".cgi" => "" )<br />
server.indexfiles = ( "gitweb.cgi" )<br />
}<br />
<br />
You may also need to add {{ic|".css" &#61;> "text/css"}} to the {{ic|mimetype.assign}} line for GitWeb to display properly.<br />
<br />
=== Nginx ===<br />
<br />
Consider you've symlinked {{ic|ln -s /usr/share/gitweb /var/www}}, append this location to your nginx configuration:<br />
{{hc|/etc/nginx/nginx.conf|<br />
<nowiki>location /gitweb/ {<br />
index gitweb.cgi;<br />
include fastcgi_params;<br />
gzip off;<br />
fastcgi_param GITWEB_CONFIG /etc/conf.d/gitweb.conf;<br />
if ($uri ~ "/gitweb/gitweb.cgi") {<br />
fastcgi_pass unix:/var/run/fcgiwrap.sock;<br />
}<br />
}</nowiki><br />
}}<br />
Additionally, we have to install {{Pkg|fcgiwrap}} and {{Pkg|spawn-fcgi}} and modify the fcgiwrap service file:<br />
{{hc|/usr/lib/systemd/system/fcgiwrap.service|<br />
<nowiki>[Unit]<br />
Description=Simple server for running CGI applications over FastCGI<br />
After=syslog.target network.target<br />
<br />
[Service]<br />
Type=forking<br />
Restart=on-abort<br />
PIDFile=/var/run/fcgiwrap.pid<br />
ExecStart=/usr/bin/spawn-fcgi -s /var/run/fcgiwrap.sock -P /var/run/fcgiwrap.pid -u http -g http -- /usr/sbin/fcgiwrap<br />
ExecStop=/usr/bin/kill -15 $MAINPID<br />
<br />
[Install]<br />
WantedBy=multi-user.target</nowiki><br />
}}<br />
In the end, enable and restart the services:<br />
{{bc|systemctl enable nginx fcgiwrap<br />
systemctl start nginx fcgiwrap}}<br />
<br />
=== Gitweb config ===<br />
<br />
Next we need to make a gitweb config file. Open (or create if it does not exist) the file {{ic|/etc/conf.d/gitweb.conf}} and place this in it:<br />
{{hc|/etc/conf.d/gitweb.conf|<nowiki><br />
$git_temp = "/tmp";<br />
<br />
# The directories where your projects are. Must not end with a slash.<br />
$projectroot = "/path/to/your/repositories"; <br />
<br />
# Base URLs for links displayed in the web interface.<br />
our @git_base_url_list = qw(git://<your_server> http://git@<your_server>); <br />
</nowiki>}}<br />
<br />
To enable "blame" view (showing the author of each line in a source file), add the following line:<br />
$feature{'blame'}{'default'} = [1];<br />
<br />
Now the the configuration is done, please restart your webserver.<br />
For apache:<br />
systemctl restart httpd <br />
<br />
Or for lighttpd:<br />
systemctl restart lighttpd<br />
<br />
=== Syntax highlighting ===<br />
<br />
To enable syntax highlighting with Gitweb, you have to first install the {{Pkg|highlight}} package:<br />
<br />
When highlight has been installed, simply add this line to your {{ic|gitweb.conf}}:<br />
{{bc|<nowiki>$feature{'highlight'}{'default'} = [1];</nowiki>}}<br />
<br />
Save the file and highlighting should now be enabled.<br />
<br />
== Adding repositories ==<br />
<br />
To add a repository go to your repository folder, make your repository like so:<br />
mkdir my_repository.git<br />
git init --bare my_repository.git/<br />
cd my_repository.git/<br />
touch git-daemon-export-ok<br />
echo "Short project's description" > .git/description<br />
<br />
Next open the {{ic|.git/config}} file and add this:<br />
[gitweb]<br />
owner = Your Name<br />
<br />
This will fill in the "Owner" field in gitweb. It's not required.<br />
<br />
I assumed that you want to have this repository as "central" repository storage where you push your commits to so the git-daemon-export-ok and --bare are here to have minimal overhead and to allow the git daemon to be used on it.<br />
<br />
That is all for making a repository. You can now see it on your http://localhost/gitweb (assuming everything went fine). You do not need to restart apache for new repositories since the gitweb cgi script simply reads your repository folder.<br />
<br />
== See also ==<br />
<br />
This howto was mainly based on the awesome howto from howtoforge: http://www.howtoforge.com/how-to-install-a-public-git-repository-on-a-debian-server. I only picked the parts that are needed to get it working and left the additional things out.</div>Visithttps://wiki.archlinux.org/index.php?title=Gitweb&diff=304612Gitweb2014-03-15T15:05:56Z<p>Visit: </p>
<hr />
<div>[[Category:Version Control System]]<br />
Gitweb is the default web interface provided with [[git]] itself and is the basis for other git scripts like [[cgit]], [[gitosis]] and others.<br />
<br />
gitweb actually supports fcgi natively, so you don't need to wrap it as a cgi script http://repo.or.cz/w/alt-git.git?a=blob_plain;f=gitweb/INSTALL https://sixohthree.com/1402/running-gitweb-in-fastcgi-mode<br />
<br />
== Installation ==<br />
<br />
To install gitweb you first have to install {{Pkg|git}} and a webserver. For this example we use {{Pkg|apache}} but you can also use {{Pkg|nginx}}, {{Pkg|lighttpd}} or others.<br />
<br />
Next you need to link the current gitweb default to your webserver location. In this example I use the default folder locations:<br />
# ln -s /usr/share/gitweb /srv/http/gitweb<br />
<br />
{{Note|1=You may want to double check the server directory to make sure the symbolic links were made.}}<br />
<br />
== Configuration ==<br />
<br />
=== Apache ===<br />
<br />
Add the following to the end of your {{ic|/etc/httpd/conf/httpd.conf}}<br />
<Directory "/srv/http/gitweb"><br />
DirectoryIndex gitweb.cgi<br />
Allow from all<br />
AllowOverride all<br />
Order allow,deny<br />
Options ExecCGI<br />
<Files gitweb.cgi><br />
SetHandler cgi-script<br />
</Files><br />
SetEnv GITWEB_CONFIG /etc/conf.d/gitweb.conf<br />
</Directory><br />
<br />
If using a virtualhosts configuration, add this to {{ic|/etc/httpd/conf/extra/httpd-vhosts.conf}}<br />
<VirtualHost *:80><br />
ServerName gitserver<br />
DocumentRoot /var/www/gitweb<br />
<Directory /var/www/gitweb><br />
Options ExecCGI +FollowSymLinks +SymLinksIfOwnerMatch<br />
AllowOverride All<br />
order allow,deny<br />
Allow from all<br />
AddHandler cgi-script cgi<br />
DirectoryIndex gitweb.cgi<br />
</Directory><br />
</VirtualHost><br />
<br />
You could also put the configuration in it's own config file in {{ic|/etc/httpd/conf/extra/}} but that's up to you to decide.<br />
<br />
==== Apache 2.4 ====<br />
<br />
For Apache 2.4 you need to install {{Pkg|mod_perl}} along with {{Pkg|git}} and {{Pkg|apache}}.<br />
<br />
Create {{ic|/etc/httpd/conf/extra/httpd-gitweb.conf}}<br />
<IfModule mod_perl.c><br />
Alias /gitweb "/usr/share/gitweb"<br />
<Directory "/usr/share/gitweb"><br />
DirectoryIndex gitweb.cgi<br />
Require all granted<br />
Options ExecCGI<br />
AddHandler perl-script .cgi<br />
PerlResponseHandler ModPerl::Registry<br />
PerlOptions +ParseHeaders<br />
SetEnv GITWEB_CONFIG /etc/conf.d/gitweb<br />
</Directory><br />
</IfModule><br />
<br />
Add the following line to the modules section of {{ic|/etc/httpd/conf/httpd.conf}}<br />
LoadModule perl_module modules/mod_perl.so<br />
<br />
Add the following line to the end of {{ic|/etc/httpd/conf/httpd.conf}}<br />
# gitweb configuration<br />
Include conf/extra/httpd-gitweb.conf<br />
<br />
<br />
=== Lighttpd ===<br />
<br />
Add the following to {{ic|/etc/lighttpd/lighttpd.conf}}:<br />
server.modules += ( "mod_alias", "mod_cgi", "mod_redirect", "mod_setenv" )<br />
setenv.add-environment = ( "GITWEB_CONFIG" => "/etc/conf.d/gitweb.conf" )<br />
url.redirect += ( "^/gitweb$" => "/gitweb/" )<br />
alias.url += ( "/gitweb/" => "/usr/share/gitweb/" )<br />
$HTTP["url"] =~ "^/gitweb/" {<br />
cgi.assign = ( ".cgi" => "" )<br />
server.indexfiles = ( "gitweb.cgi" )<br />
}<br />
<br />
You may also need to add {{ic|".css" &#61;> "text/css"}} to the {{ic|mimetype.assign}} line for GitWeb to display properly.<br />
<br />
=== Nginx ===<br />
<br />
Consider you've symlinked {{ic|ln -s /usr/share/gitweb /var/www}}, append this location to your nginx configuration:<br />
{{hc|/etc/nginx/nginx.conf|<br />
<nowiki>location /gitweb/ {<br />
index gitweb.cgi;<br />
include fastcgi_params;<br />
gzip off;<br />
fastcgi_param GITWEB_CONFIG /etc/conf.d/gitweb.conf;<br />
if ($uri ~ "/gitweb/gitweb.cgi") {<br />
fastcgi_pass unix:/var/run/fcgiwrap.sock;<br />
}<br />
}</nowiki><br />
}}<br />
Additionally, we have to install {{Pkg|fcgiwrap}} and {{Pkg|spawn-fcgi}} and modify the fcgiwrap service file:<br />
{{hc|/usr/lib/systemd/system/fcgiwrap.service|<br />
<nowiki>[Unit]<br />
Description=Simple server for running CGI applications over FastCGI<br />
After=syslog.target network.target<br />
<br />
[Service]<br />
Type=forking<br />
Restart=on-abort<br />
PIDFile=/var/run/fcgiwrap.pid<br />
ExecStart=/usr/bin/spawn-fcgi -s /var/run/fcgiwrap.sock -P /var/run/fcgiwrap.pid -u http -g http -- /usr/sbin/fcgiwrap<br />
ExecStop=/usr/bin/kill -15 $MAINPID<br />
<br />
[Install]<br />
WantedBy=multi-user.target</nowiki><br />
}}<br />
In the end, enable and restart the services:<br />
{{bc|systemctl enable nginx fcgiwrap<br />
systemctl start nginx fcgiwrap}}<br />
<br />
=== Gitweb config ===<br />
<br />
Next we need to make a gitweb config file. Open (or create if it does not exist) the file {{ic|/etc/conf.d/gitweb.conf}} and place this in it:<br />
{{hc|/etc/conf.d/gitweb.conf|<nowiki><br />
$git_temp = "/tmp";<br />
<br />
# The directories where your projects are. Must not end with a slash.<br />
$projectroot = "/path/to/your/repositories"; <br />
<br />
# Base URLs for links displayed in the web interface.<br />
our @git_base_url_list = qw(git://<your_server> http://git@<your_server>); <br />
</nowiki>}}<br />
<br />
To enable "blame" view (showing the author of each line in a source file), add the following line:<br />
$feature{'blame'}{'default'} = [1];<br />
<br />
Now the the configuration is done, please restart your webserver.<br />
For apache:<br />
systemctl restart httpd <br />
<br />
Or for lighttpd:<br />
systemctl restart lighttpd<br />
<br />
=== Syntax highlighting ===<br />
<br />
To enable syntax highlighting with Gitweb, you have to first install the {{Pkg|highlight}} package:<br />
<br />
When highlight has been installed, simply add this line to your {{ic|gitweb.conf}}:<br />
{{bc|<nowiki>$feature{'highlight'}{'default'} = [1];</nowiki>}}<br />
<br />
Save the file and highlighting should now be enabled.<br />
<br />
== Adding repositories ==<br />
<br />
To add a repository go to your repository folder, make your repository like so:<br />
mkdir my_repository.git<br />
git init --bare my_repository.git/<br />
cd my_repository.git/<br />
touch git-daemon-export-ok<br />
echo "Short project's description" > .git/description<br />
<br />
Next open the {{ic|.git/config}} file and add this:<br />
[gitweb]<br />
owner = Your Name<br />
<br />
This will fill in the "Owner" field in gitweb. It's not required.<br />
<br />
I assumed that you want to have this repository as "central" repository storage where you push your commits to so the git-daemon-export-ok and --bare are here to have minimal overhead and to allow the git daemon to be used on it.<br />
<br />
That is all for making a repository. You can now see it on your http://localhost/gitweb (assuming everything went fine). You do not need to restart apache for new repositories since the gitweb cgi script simply reads your repository folder.<br />
<br />
== See also ==<br />
<br />
This howto was mainly based on the awesome howto from howtoforge: http://www.howtoforge.com/how-to-install-a-public-git-repository-on-a-debian-server. I only picked the parts that are needed to get it working and left the additional things out.</div>Visithttps://wiki.archlinux.org/index.php?title=Gitweb&diff=304611Gitweb2014-03-15T15:04:22Z<p>Visit: </p>
<hr />
<div>[[Category:Version Control System]]<br />
Gitweb is the default web interface provided with [[git]] itself and is the basis for other git scripts like [[cgit]], [[gitosis]] and others.<br />
<br />
gitweb actually supports fcgi natively, so you don't need to wrap it as a cgi script http://repo.or.cz/w/alt-git.git?a=blob_plain;f=gitweb/INSTALL https://sixohthree.com/1402/running-gitweb-in-fastcgi-mode<br />
<br />
== Installation ==<br />
<br />
To install gitweb you first have to install {{Pkg|git}} and a webserver. For this example we use {{Pkg|apache}} but you can also use {{Pkg|nginx}}, {{Pkg|lighttpd}} or others.<br />
<br />
Next you need to link the current gitweb default to your webserver location. In this example I use the default folder locations:<br />
# ln -s /usr/share/gitweb /srv/http/gitweb<br />
<br />
{{Note|1=You may want to double check the server directory to make sure the symbolic links were made.}}<br />
<br />
== Configuration ==<br />
<br />
=== Apache ===<br />
<br />
Add the following to the end of your {{ic|/etc/httpd/conf/httpd.conf}}<br />
<Directory "/srv/http/gitweb"><br />
DirectoryIndex gitweb.cgi<br />
Allow from all<br />
AllowOverride all<br />
Order allow,deny<br />
Options ExecCGI<br />
<Files gitweb.cgi><br />
SetHandler cgi-script<br />
</Files><br />
SetEnv GITWEB_CONFIG /etc/conf.d/gitweb.conf<br />
</Directory><br />
<br />
If using a virtualhosts configuration, add this to {{ic|/etc/httpd/conf/extra/httpd-vhosts.conf}}<br />
<VirtualHost *:80><br />
ServerName gitserver<br />
DocumentRoot /var/www/gitweb<br />
<Directory /var/www/gitweb><br />
Options ExecCGI +FollowSymLinks +SymLinksIfOwnerMatch<br />
AllowOverride All<br />
order allow,deny<br />
Allow from all<br />
AddHandler cgi-script cgi<br />
DirectoryIndex gitweb.cgi<br />
</Directory><br />
</VirtualHost><br />
<br />
You could also put the configuration in it's own config file in {{ic|/etc/httpd/conf/extra/}} but that's up to you to decide.<br />
<br />
==== Apache 2.4 ====<br />
<br />
For Apache 2.4 you need to install {{Pkg|mod_perl}}.<br />
<br />
Create {{ic|/etc/httpd/conf/extra/httpd-gitweb.conf}}<br />
<IfModule mod_perl.c><br />
Alias /gitweb "/usr/share/gitweb"<br />
<Directory "/usr/share/gitweb"><br />
DirectoryIndex gitweb.cgi<br />
Require all granted<br />
Options ExecCGI<br />
AddHandler perl-script .cgi<br />
PerlResponseHandler ModPerl::Registry<br />
PerlOptions +ParseHeaders<br />
SetEnv GITWEB_CONFIG /etc/conf.d/gitweb<br />
</Directory><br />
</IfModule><br />
<br />
Add the following line to the modules section of {{ic|/etc/httpd/conf/httpd.conf}}<br />
LoadModule perl_module modules/mod_perl.so<br />
<br />
Add the following line to the end of {{ic|/etc/httpd/conf/httpd.conf}}<br />
# gitweb configuration<br />
Include conf/extra/httpd-gitweb.conf<br />
<br />
<br />
=== Lighttpd ===<br />
<br />
Add the following to {{ic|/etc/lighttpd/lighttpd.conf}}:<br />
server.modules += ( "mod_alias", "mod_cgi", "mod_redirect", "mod_setenv" )<br />
setenv.add-environment = ( "GITWEB_CONFIG" => "/etc/conf.d/gitweb.conf" )<br />
url.redirect += ( "^/gitweb$" => "/gitweb/" )<br />
alias.url += ( "/gitweb/" => "/usr/share/gitweb/" )<br />
$HTTP["url"] =~ "^/gitweb/" {<br />
cgi.assign = ( ".cgi" => "" )<br />
server.indexfiles = ( "gitweb.cgi" )<br />
}<br />
<br />
You may also need to add {{ic|".css" &#61;> "text/css"}} to the {{ic|mimetype.assign}} line for GitWeb to display properly.<br />
<br />
=== Nginx ===<br />
<br />
Consider you've symlinked {{ic|ln -s /usr/share/gitweb /var/www}}, append this location to your nginx configuration:<br />
{{hc|/etc/nginx/nginx.conf|<br />
<nowiki>location /gitweb/ {<br />
index gitweb.cgi;<br />
include fastcgi_params;<br />
gzip off;<br />
fastcgi_param GITWEB_CONFIG /etc/conf.d/gitweb.conf;<br />
if ($uri ~ "/gitweb/gitweb.cgi") {<br />
fastcgi_pass unix:/var/run/fcgiwrap.sock;<br />
}<br />
}</nowiki><br />
}}<br />
Additionally, we have to install {{Pkg|fcgiwrap}} and {{Pkg|spawn-fcgi}} and modify the fcgiwrap service file:<br />
{{hc|/usr/lib/systemd/system/fcgiwrap.service|<br />
<nowiki>[Unit]<br />
Description=Simple server for running CGI applications over FastCGI<br />
After=syslog.target network.target<br />
<br />
[Service]<br />
Type=forking<br />
Restart=on-abort<br />
PIDFile=/var/run/fcgiwrap.pid<br />
ExecStart=/usr/bin/spawn-fcgi -s /var/run/fcgiwrap.sock -P /var/run/fcgiwrap.pid -u http -g http -- /usr/sbin/fcgiwrap<br />
ExecStop=/usr/bin/kill -15 $MAINPID<br />
<br />
[Install]<br />
WantedBy=multi-user.target</nowiki><br />
}}<br />
In the end, enable and restart the services:<br />
{{bc|systemctl enable nginx fcgiwrap<br />
systemctl start nginx fcgiwrap}}<br />
<br />
=== Gitweb config ===<br />
<br />
Next we need to make a gitweb config file. Open (or create if it does not exist) the file {{ic|/etc/conf.d/gitweb.conf}} and place this in it:<br />
{{hc|/etc/conf.d/gitweb.conf|<nowiki><br />
$git_temp = "/tmp";<br />
<br />
# The directories where your projects are. Must not end with a slash.<br />
$projectroot = "/path/to/your/repositories"; <br />
<br />
# Base URLs for links displayed in the web interface.<br />
our @git_base_url_list = qw(git://<your_server> http://git@<your_server>); <br />
</nowiki>}}<br />
<br />
To enable "blame" view (showing the author of each line in a source file), add the following line:<br />
$feature{'blame'}{'default'} = [1];<br />
<br />
Now the the configuration is done, please restart your webserver.<br />
For apache:<br />
systemctl restart httpd <br />
<br />
Or for lighttpd:<br />
systemctl restart lighttpd<br />
<br />
=== Syntax highlighting ===<br />
<br />
To enable syntax highlighting with Gitweb, you have to first install the {{Pkg|highlight}} package:<br />
<br />
When highlight has been installed, simply add this line to your {{ic|gitweb.conf}}:<br />
{{bc|<nowiki>$feature{'highlight'}{'default'} = [1];</nowiki>}}<br />
<br />
Save the file and highlighting should now be enabled.<br />
<br />
== Adding repositories ==<br />
<br />
To add a repository go to your repository folder, make your repository like so:<br />
mkdir my_repository.git<br />
git init --bare my_repository.git/<br />
cd my_repository.git/<br />
touch git-daemon-export-ok<br />
echo "Short project's description" > .git/description<br />
<br />
Next open the {{ic|.git/config}} file and add this:<br />
[gitweb]<br />
owner = Your Name<br />
<br />
This will fill in the "Owner" field in gitweb. It's not required.<br />
<br />
I assumed that you want to have this repository as "central" repository storage where you push your commits to so the git-daemon-export-ok and --bare are here to have minimal overhead and to allow the git daemon to be used on it.<br />
<br />
That is all for making a repository. You can now see it on your http://localhost/gitweb (assuming everything went fine). You do not need to restart apache for new repositories since the gitweb cgi script simply reads your repository folder.<br />
<br />
== See also ==<br />
<br />
This howto was mainly based on the awesome howto from howtoforge: http://www.howtoforge.com/how-to-install-a-public-git-repository-on-a-debian-server. I only picked the parts that are needed to get it working and left the additional things out.</div>Visithttps://wiki.archlinux.org/index.php?title=Lenovo_ThinkPad_S440&diff=290824Lenovo ThinkPad S4402013-12-29T22:59:25Z<p>Visit: </p>
<hr />
<div>[[Category:Lenovo]]<br />
<br />
This article was written to assist you with getting archlinux run on the Lenovo ThinkPad S440. It is meant to be help you with some tricky points aside to the [[Beginners' Guide]]: A guide through the whole process of installing and configuring Arch Linux; written for new or inexperienced users.<br />
<br />
== Prerequisites ==<br />
<br />
=== Creating an installation medium ===<br />
<br />
To create a bootable USB-Stick with the archlinux*.iso you downloaded, simply:<br />
<br />
dd bs=4M if=archlinux*.iso of=/dev/sdX && sync<br />
<br />
which will/should behave like a regular bootable CD-Rom in addition to a capable BIOS and the <u>correct bootsequence</u>! In doubt or in case of problems see [[Install_from_a_USB_flash_drive|Install from a USB flash drive]] for more detailed instructions.<br />
<br />
=== Enable Legacy Boot ===<br />
<br />
On boot press F12 to enter the BIOS menu and choose your USB-Stick to boot from. If you like, you can disable UEFI boot completely in the BIOS settings too.<br />
<br />
== Installation ==<br />
<br />
After that it is recommended to follow the usual installation procedure described in the [[Beginners' Guide]].<br />
<br />
=== LAN ===<br />
<br />
Works out of the box with module {{ic|r8169}}.<br />
<br />
If you use Lenovo's [[Thinkpad OneLink Dock]] you need {{AUR|asix-ax88179-dkms}} for it's ThinkPad OneLink GigaLAN adapter. The module {{ic|ax88179_178a}} delivered with the stock kernel doesn't work.<br />
<br />
=== WLAN ===<br />
<br />
Works out of the box with module {{ic|iwlwifi}}.<br />
<br />
=== Audio ===<br />
<br />
Works out of the box with module {{ic|snd-hda-intel}}.<br />
<br />
=== Video ===<br />
<br />
The S440 comes with ati intel hybrid graphics.<br />
Currently the best implementation for {{ic|i915}}/ {{ic|fglrx}} hybrids is found in the [[AMD_Catalyst#Installing_from_the_unofficial_repository|unofficial catalyst repository]].<br />
<br />
pacman -S catalyst-hook catalyst-utils-pxp xf86-video-intel intel-dri<br />
<br />
You can switch between the two drivers with on of the following commands:<br />
<br />
# intel<br />
aticonfig --px-igpu<br />
<br />
# ati<br />
aticonfig --px-dgpu<br />
<br />
If you encounter tearing in video playback when using Intel graphics (some S440 variants come without dedicated ATI chip), [[Intel Graphics#Tear-free video|try enabling the Intel drivers' "TearFree" option]].<br />
<br />
=== Touchpad ===<br />
<br />
A synaptics touchpad with two-finger scrolling. Install {{Pkg|xf86-input-synaptics}} to get it running with multi-touch gestures.<br />
<br />
=== Frequency scaling ===<br />
<br />
Work well with {{Pkg|cpupower}} as described in [[CPU_Frequency_Scaling#cpupower|CPU Frequency Scaling]]. Be aware, that the {{ic|ondemand}} governer doesn't work with i7 4500M atm. I choose {{ic|powersave}} as default.<br />
<br />
=== Webcam ===<br />
<br />
Works out of the box with {{ic|uvcvideo}}.<br />
<br />
=== Keyboard backlight ===<br />
<br />
Currently the {{ic|thinkpad_acpi}} module does not support to turn the keyboard backlight on. But you can turn it off with:<br />
<br />
echo 0 > /sys/devices/platform/thinkpad_acpi/leds/tpacpi::thinklight/brightness<br />
<br />
=== Fingerprint scanner ===<br />
<br />
To get that working you need {{Pkg|fprintd}} and {{AUR|libfprint-vfs5011-git}}. Follow the [[Fprint]] guide for the rest.<br />
<br />
=== Suspend ===<br />
<br />
Works flawlessly with with {{Pkg|pm-utils}} or any DE integration.<br />
<br />
=== Power consumption ===<br />
<br />
With {{Pkg|cpupower}}, {{Pkg|laptop-mode-utils}} and {{Pkg|acpid}} installed and graphics switched to intel gpu, I get over 9 hours battery life.<br />
<br />
==== Automatic brightness control ====<br />
<br />
If you want to change the brightness on ac-adaper plug-on/off, add the following in /etc/acpi/handler.sh:<br />
<br />
ac_adapter)<br />
case "$2" in<br />
AC|ACAD|ADP0|ACPI0003:00)<br />
case "$4" in<br />
00000000)<br />
logger 'AC unpluged'<br />
echo "20" > /sys/class/backlight/acpi_video0/brightness<br />
;;<br />
00000001)<br />
logger 'AC pluged'<br />
echo "50" > /sys/class/backlight/acpi_video0/brightness<br />
;;<br />
esac<br />
;;</div>Visithttps://wiki.archlinux.org/index.php?title=Lenovo_ThinkPad_S440&diff=290823Lenovo ThinkPad S4402013-12-29T22:53:13Z<p>Visit: Ethernet stuff</p>
<hr />
<div>[[Category:Lenovo]]<br />
<br />
This article was written to assist you with getting archlinux run on the Lenovo ThinkPad S440. It is meant to be help you with some tricky points aside to the [[Beginners' Guide]]: A guide through the whole process of installing and configuring Arch Linux; written for new or inexperienced users.<br />
<br />
== Prerequisites ==<br />
<br />
=== Creating an installation medium ===<br />
<br />
To create a bootable USB-Stick with the archlinux*.iso you downloaded, simply:<br />
<br />
dd bs=4M if=archlinux*.iso of=/dev/sdX && sync<br />
<br />
which will/should behave like a regular bootable CD-Rom in addition to a capable BIOS and the <u>correct bootsequence</u>! In doubt or in case of problems see [[Install_from_a_USB_flash_drive|Install from a USB flash drive]] for more detailed instructions.<br />
<br />
=== Enable Legacy Boot ===<br />
<br />
On boot press F12 to enter the BIOS menu and choose your USB-Stick to boot from. If you like, you can disable UEFI boot completely in the BIOS settings too.<br />
<br />
== Installation ==<br />
<br />
After that it is recommended to follow the usual installation procedure described in the [[Beginners' Guide]].<br />
<br />
=== LAN ===<br />
<br />
Works out of the box with module {{ic|r8169}}.<br />
<br />
If you use Lenovo's [[Thinkpad OneLink Dock]] you need {{AUR|asix-ax88179-dkms}}. The module {{ic|ax88179_178a}} delivered with the stock kernel doesn't work.<br />
<br />
=== WLAN ===<br />
<br />
Works out of the box with module {{ic|iwlwifi}}.<br />
<br />
=== Audio ===<br />
<br />
Works out of the box with module {{ic|snd-hda-intel}}.<br />
<br />
=== Video ===<br />
<br />
The S440 comes with ati intel hybrid graphics.<br />
Currently the best implementation for {{ic|i915}}/ {{ic|fglrx}} hybrids is found in the [[AMD_Catalyst#Installing_from_the_unofficial_repository|unofficial catalyst repository]].<br />
<br />
pacman -S catalyst-hook catalyst-utils-pxp xf86-video-intel intel-dri<br />
<br />
You can switch between the two drivers with on of the following commands:<br />
<br />
# intel<br />
aticonfig --px-igpu<br />
<br />
# ati<br />
aticonfig --px-dgpu<br />
<br />
If you encounter tearing in video playback when using Intel graphics (some S440 variants come without dedicated ATI chip), [[Intel Graphics#Tear-free video|try enabling the Intel drivers' "TearFree" option]].<br />
<br />
=== Touchpad ===<br />
<br />
A synaptics touchpad with two-finger scrolling. Install {{Pkg|xf86-input-synaptics}} to get it running with multi-touch gestures.<br />
<br />
=== Frequency scaling ===<br />
<br />
Work well with {{Pkg|cpupower}} as described in [[CPU_Frequency_Scaling#cpupower|CPU Frequency Scaling]]. Be aware, that the {{ic|ondemand}} governer doesn't work with i7 4500M atm. I choose {{ic|powersave}} as default.<br />
<br />
=== Webcam ===<br />
<br />
Works out of the box with {{ic|uvcvideo}}.<br />
<br />
=== Keyboard backlight ===<br />
<br />
Currently the {{ic|thinkpad_acpi}} module does not support to turn the keyboard backlight on. But you can turn it off with:<br />
<br />
echo 0 > /sys/devices/platform/thinkpad_acpi/leds/tpacpi::thinklight/brightness<br />
<br />
=== Fingerprint scanner ===<br />
<br />
To get that working you need {{Pkg|fprintd}} and {{AUR|libfprint-vfs5011-git}}. Follow the [[Fprint]] guide for the rest.<br />
<br />
=== Suspend ===<br />
<br />
Works flawlessly with with {{Pkg|pm-utils}} or any DE integration.<br />
<br />
=== Power consumption ===<br />
<br />
With {{Pkg|cpupower}}, {{Pkg|laptop-mode-utils}} and {{Pkg|acpid}} installed and graphics switched to intel gpu, I get over 9 hours battery life.<br />
<br />
==== Automatic brightness control ====<br />
<br />
If you want to change the brightness on ac-adaper plug-on/off, add the following in /etc/acpi/handler.sh:<br />
<br />
ac_adapter)<br />
case "$2" in<br />
AC|ACAD|ADP0|ACPI0003:00)<br />
case "$4" in<br />
00000000)<br />
logger 'AC unpluged'<br />
echo "20" > /sys/class/backlight/acpi_video0/brightness<br />
;;<br />
00000001)<br />
logger 'AC pluged'<br />
echo "50" > /sys/class/backlight/acpi_video0/brightness<br />
;;<br />
esac<br />
;;</div>Visithttps://wiki.archlinux.org/index.php?title=Lenovo_ThinkPad_S440&diff=284474Lenovo ThinkPad S4402013-11-24T20:54:33Z<p>Visit: </p>
<hr />
<div>[[Category:Lenovo]]<br />
<br />
This article was written to assist you with getting archlinux run on the Lenovo ThinkPad S440. It is meant to be help you with some tricky points aside to the [[Beginners' Guide]]: A guide through the whole process of installing and configuring Arch Linux; written for new or inexperienced users.<br />
<br />
== Prerequisites ==<br />
<br />
=== Creating an installation medium ===<br />
<br />
To create a bootable USB-Stick with the archlinux*.iso you downloaded, simply:<br />
<br />
dd bs=4M if=archlinux*.iso of=/dev/sdX && sync<br />
<br />
which will/should behave like a regular bootable CD-Rom in addition to a capable BIOS and the <u>correct bootsequence</u>! In doubt or in case of problems see [[Install_from_a_USB_flash_drive|Install from a USB flash drive]] for more detailed instructions.<br />
<br />
=== Enable Legacy Boot ===<br />
<br />
On boot press F12 to enter the BIOS menu and choose your USB-Stick to boot from. If you like, you can disable UEFI boot completely in the BIOS settings too.<br />
<br />
== Installation ==<br />
<br />
After that it is recommended to follow the usual installation procedure described in the [[Beginners' Guide]].<br />
<br />
=== WLAN ===<br />
<br />
Works out of the box with module {{ic|iwlwifi}}.<br />
<br />
=== Audio ===<br />
<br />
Works out of the box with module {{ic|snd-hda-intel}}.<br />
<br />
=== Video ===<br />
<br />
The S440 comes with ati intel hybrid graphics.<br />
Currently the best implementation for {{ic|i915}}/ {{ic|fglrx}} hybrids is found in the [[AMD_Catalyst#Installing_from_the_unofficial_repository|unofficial catalyst repository]].<br />
<br />
pacman -S catalyst-hook catalyst-utils-pxp xf86-video-intel intel-dri<br />
<br />
You can switch between the two drivers with on of the following commands:<br />
<br />
# intel<br />
aticonfig --px-igpu<br />
<br />
# ati<br />
aticonfig --px-dgpu<br />
<br />
=== Touchpad ===<br />
<br />
A synaptics touchpad with two-finger scrolling. Install {{Pkg|xf86-input-synaptics}} to get it running with multi-touch gestures.<br />
<br />
=== Frequency scaling ===<br />
<br />
Work well with {{Pkg|cpupower}} as described in [[CPU_Frequency_Scaling#cpupower|CPU Frequency Scaling]]. Be aware, that the {{ic|ondemand}} governer doesn't work with i7 4500M atm. I choose {{ic|powersave}} as default.<br />
<br />
=== Webcam ===<br />
<br />
Works out of the box with {{ic|uvcvideo}}.<br />
<br />
=== Keyboard backlight ===<br />
<br />
Currently the {{ic|thinkpad_acpi}} module does not support to turn the keyboard backlight on. But you can turn it off with:<br />
<br />
echo 0 > /sys/devices/platform/thinkpad_acpi/leds/tpacpi::thinklight/brightness<br />
<br />
=== Fingerprint scanner ===<br />
<br />
To get that working you need {{Pkg|fprintd}} and {{AUR|libfprint-vfs5011-git}}. Follow the [[Fprint]] guide for the rest.<br />
<br />
=== Suspend ===<br />
<br />
Works flawlessly with with {{Pkg|pm-utils}} or any DE integration.<br />
<br />
=== Power consumption ===<br />
<br />
With {{Pkg|cpupower}}, {{Pkg|laptop-mode-utils}} and {{Pkg|acpid}} installed and graphics switched to intel gpu, I get over 9 hours battery life.<br />
<br />
==== Automatic brightness control ====<br />
<br />
If you want to change the brightness on ac-adaper plug-on/off, add the following in /etc/acpi/handler.sh:<br />
<br />
ac_adapter)<br />
case "$2" in<br />
AC|ACAD|ADP0|ACPI0003:00)<br />
case "$4" in<br />
00000000)<br />
logger 'AC unpluged'<br />
echo "20" > /sys/class/backlight/acpi_video0/brightness<br />
;;<br />
00000001)<br />
logger 'AC pluged'<br />
echo "50" > /sys/class/backlight/acpi_video0/brightness<br />
;;<br />
esac<br />
;;</div>Visithttps://wiki.archlinux.org/index.php?title=Lenovo_ThinkPad_S440&diff=284467Lenovo ThinkPad S4402013-11-24T20:43:18Z<p>Visit: Created page with "Category:Lenovo This article was written to assist you with getting archlinux run on the Lenovo ThinkPad S440. It is meant to be help you with some tricky points aside to..."</p>
<hr />
<div>[[Category:Lenovo]]<br />
<br />
This article was written to assist you with getting archlinux run on the Lenovo ThinkPad S440. It is meant to be help you with some tricky points aside to the [[Beginners' Guide]]: A guide through the whole process of installing and configuring Arch Linux; written for new or inexperienced users.<br />
<br />
== Prerequisites ==<br />
<br />
=== Creating an installation medium ===<br />
<br />
To create a bootable USB-Stick with the archlinux*.iso you downloaded, simply:<br />
<br />
dd bs=4M if=archlinux*.iso of=/dev/sdX && sync<br />
<br />
which will/should behave like a regular bootable CD-Rom in addition to a capable BIOS and the <u>correct bootsequence</u>! In doubt or in case of problems see [[Install_from_a_USB_flash_drive|Install from a USB flash drive]] for more detailed instructions.<br />
<br />
=== Enable Legacy Boot ===<br />
<br />
On boot press F12 to enter the BIOS menu and choose your USB-Stick to boot from. If you like, you can disable UEFI boot completely in the BIOS settings too.<br />
<br />
== Installation ==<br />
<br />
After that it is recommended to follow the usual installation procedure described in the [[Beginners' Guide]].<br />
<br />
=== WLAN ===<br />
<br />
Works out of the box with module {{ic|iwlwifi}}.<br />
<br />
=== Audio ===<br />
<br />
Works out of the box with module {{ic|snd-hda-intel}}.<br />
<br />
=== Video ===<br />
<br />
The S440 comes with ati intel hybrid graphics.<br />
Currently the best implementation for {{ic|i915}}/ {{ic|fglrx}} hybrids is found in the [[AMD_Catalyst#Installing_from_the_unofficial_repository|unofficial catalyst repository]].<br />
<br />
pacman -S catalyst-hook catalyst-utils-pxp xf86-video-intel intel-dri<br />
<br />
You can switch between the two drivers with on of the following commands:<br />
<br />
# intel<br />
aticonfig --px-igpu<br />
<br />
# ati<br />
aticonfig --px-dgpu<br />
<br />
=== Touchpad ===<br />
<br />
A synaptics touchpad with two-finger scrolling. Install {{Pkg|xf86-input-synaptics}} to get it running with multi-touch gestures.<br />
<br />
=== Frequency scaling ===<br />
<br />
Work well with {{Pkg|cpupower}} as described in [[CPU_Frequency_Scaling#cpupower|CPU Frequency Scaling]]. Be aware, that the {{ic|ondemand}} governer dosn't work with i7 4500M atm. I choose {{ic|powersave}} as default.<br />
<br />
=== Webcam ===<br />
<br />
Works out of the box with {{ic|uvcvideo}}.<br />
<br />
=== Keyboard backlight ===<br />
<br />
Currently the {{ic|thinkpad_acpi}} module does not support to turn the keyboard backlight on. But you can turn it off with:<br />
<br />
echo 0 > /sys/devices/platform/thinkpad_acpi/leds/tpacpi::thinklight/brightness<br />
<br />
=== Fingerprint scanner ===<br />
<br />
To get that working you need {{Pkg|fprintd}} and {{AUR|libfprint-vfs5011-git}}. Follow the [[Fprint]] guide for the rest.<br />
<br />
=== Suspend ===<br />
<br />
Works flawlessly with with {{Pkg|pm-utils}} or any DE integration.<br />
<br />
=== Power consumption ===<br />
<br />
With {{Pkg|cpupower}}, {{Pkg|laptop-mode-utils}} and {{Pkg|acpid}} installed and graphics switched to intel gpu, I get over 9 hours battery life.<br />
<br />
==== Automatic brightness control ====<br />
<br />
If you want to change the brightness on ac-adaper plug-on/off, add the following in /etc/acpi/handler.sh:<br />
<br />
ac_adapter)<br />
case "$2" in<br />
AC|ACAD|ADP0|ACPI0003:00)<br />
case "$4" in<br />
00000000)<br />
logger 'AC unpluged'<br />
echo "20" > /sys/class/backlight/acpi_video0/brightness<br />
;;<br />
00000001)<br />
logger 'AC pluged'<br />
echo "50" > /sys/class/backlight/acpi_video0/brightness<br />
;;<br />
esac<br />
;;</div>Visithttps://wiki.archlinux.org/index.php?title=Lenovo/IBM_Notebooks&diff=284464Lenovo/IBM Notebooks2013-11-24T19:35:42Z<p>Visit: added S440</p>
<hr />
<div>[[Category:IBM]]<br />
[[Category:Lenovo]]<br />
<br />
Lenovo and previously IBM are producing wonderful machines which are known to support Linux very well. There are wiki pages with hints and guides for many models in the Arch wiki. The following table tries to give an overview.<br />
<br />
Indented list entries are duplicates.<br />
<br />
==Models==<br />
<br />
Taken from [http://www.thinkwiki.org/wiki/ThinkPad_History] and [http://www.thinkwiki.org/wiki/Category:Models].<br />
<br />
===Withdrawn Series===<br />
<br />
*[[IBM ThinkPad 600E]] (1998)<br />
<br />
===ThinkPad R===<br />
<br />
*[[IBM ThinkPad R40]] (2003)<br />
*[[IBM ThinkPad R60E]] (2006)<br />
*[[Lenovo ThinkPad R500]] (2008)<br />
<br />
===ThinkPad S===<br />
<br />
*[[Lenovo ThinkPad S440]] (2013)<br />
<br />
===ThinkPad T===<br />
<br />
*[[IBM ThinkPad T21]] (2000)<br />
*[[IBM ThinkPad T23]] (2001)<br />
*[[IBM ThinkPad T30]] (2002)<br />
*[[IBM ThinkPad T41]] (2003)<br />
*[[IBM ThinkPad T42]] (2004)<br />
*[[IBM ThinkPad T43p]] (2005)<br />
*[[Lenovo Thinkpad T61]] (2007)<br />
**[[IBM ThinkPad T61]] (2007)<br />
*[[Lenovo ThinkPad T400]] (2008)<br />
*[[Lenovo ThinkPad T400s]] (2009)<br />
*[[Lenovo ThinkPad T420]] (2011)<br />
*[[Lenovo ThinkPad T420s]] (2011)<br />
<br />
===ThinkPad W===<br />
<br />
===ThinkPad X===<br />
<br />
*[[IBM ThinkPad X31]] (2003)<br />
*[[IBM ThinkPad X41]] (2005)<br />
*[[IBM ThinkPad X60]] (2006)<br />
*[[IBM ThinkPad X60s]] (2006)<br />
*[[Lenovo Thinkpad X60 Tablet]] (2006)<br />
*[[Lenovo ThinkPad X61T]] (2007)<br />
*[[Lenovo Thinkpad X300]] (2008)<br />
*[[Lenovo ThinkPad X200]] (2008)<br />
*[[Lenovo ThinkPad X201]] (2010)<br />
*[[Lenovo ThinkPad X1]] (2011)<br />
*[[Lenovo ThinkPad X100e]] (2010)<br />
*[[Lenovo ThinkPad X120e]] (2011)<br />
*[[Lenovo ThinkPad X220]] (2011)<br />
*[[Lenovo ThinkPad X230]] (2012)<br />
<br />
===ThinkPad SL===<br />
<br />
*[[Lenovo Thinkpad SL500]] (2008)<br />
*[[Lenovo ThinkPad SL510]]<br />
<br />
===Ideapad===<br />
<br />
*[[Lenovo Ideapad S10]]<br />
*[[Lenovo Ideapad y530]]<br />
*[[Lenovo Ideapad G580]]<br />
*[[Lenovo IdeaPad Y580]]<br />
*[[Lenovo Ideapad S10-3]]<br />
*[[Lenovo Ideapad s10-3t]]<br />
<br />
===Edge===<br />
<br />
*[[ThinkPad Edge]]<br />
<br />
==See also==<br />
<br />
* [[HCL/Laptops/IBM]]<br />
* [[Thinkpad Fan Control]]<br />
* [[Thinkpad Multimedia Buttons]]<br />
* [http://www.thinkwiki.org Thinkwiki]</div>Visithttps://wiki.archlinux.org/index.php?title=Systemd&diff=283158Systemd2013-11-16T11:35:57Z<p>Visit: </p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Daemons and system services]]<br />
[[Category:Boot process]]<br />
[[ar:Systemd]]<br />
[[es:Systemd]]<br />
[[fr:Systemd]]<br />
[[it:Systemd]]<br />
[[ja:Systemd]]<br />
[[pt:Systemd]]<br />
[[ru:Systemd]]<br />
[[zh-CN:Systemd]]<br />
[[zh-TW:Systemd]]<br />
{{Article summary start}}<br />
{{Article summary text|Covers how to install and configure systemd.}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|systemd/User}}<br />
{{Article summary wiki|systemd/Services}}<br />
{{Article summary wiki|systemd/cron functionality}}<br />
{{Article summary wiki|systemd FAQ}}<br />
{{Article summary wiki|init Rosetta}}<br />
{{Article summary wiki|Daemons List}}<br />
{{Article summary wiki|udev}}<br />
{{Article summary wiki|Improve Boot Performance}}<br />
{{Article summary end}}<br />
From the [http://freedesktop.org/wiki/Software/systemd project web page]:<br />
<br />
:'''''systemd''' is a system and service manager for Linux, compatible with SysV and LSB init scripts. systemd provides aggressive parallelization capabilities, uses socket and [[D-Bus]] activation for starting services, offers on-demand starting of daemons, keeps track of processes using Linux [[cgroups|control groups]], supports snapshotting and restoring of the system state, maintains mount and automount points and implements an elaborate transactional dependency-based service control logic.''<br />
<br />
{{Note|1=For a detailed explanation as to why Arch has moved to ''systemd'', see [https://bbs.archlinux.org/viewtopic.php?pid=1149530#p1149530 this forum post].}}<br />
<br />
== Migration from SysVinit/initscripts ==<br />
<br />
{{Note|<br />
* {{Pkg|systemd}} and {{Pkg|systemd-sysvcompat}} are both installed by default on installation media newer than [https://www.archlinux.org/news/systemd-is-now-the-default-on-new-installations/ 2012-10-13]. This section is aimed at Arch Linux installations that still rely on ''sysvinit'' and ''initscripts''.<br />
* If you are running Arch Linux inside a VPS, please see [[Virtual Private Server#Moving your VPS from initscripts to systemd]].<br />
}}<br />
<br />
=== Considerations before switching ===<br />
<br />
* Do [http://freedesktop.org/wiki/Software/systemd/ some reading] about ''systemd''.<br />
* Note the fact that systemd has a ''journal'' system that replaces ''syslog'', although the two can co-exist. See [[#Journal]].<br />
* While ''systemd'' can replace some of the functionality of ''cron'', ''acpid'', or ''xinetd'', there is no need to switch away from using the traditional daemons unless you want to.<br />
* Interactive ''initscripts'' are not working with ''systemd''. In particular, ''netcfg-menu'' cannot be used at system start-up ({{Bug|31377}}).<br />
<br />
=== Installation procedure ===<br />
<br />
# [[pacman|Install]] {{Pkg|systemd}} from the [[official repositories]].<br />
# Append the following to your [[kernel parameters]]: {{ic|1=init=/usr/lib/systemd/systemd}}.<br />
# Once completed you may enable any desired services via the use of {{ic|systemctl enable ''service_name''}} (this roughly equates to what you included in the {{ic|DAEMONS}} array. New names can be found in [[Daemons List]]).<br />
# Reboot your system and verify that ''systemd'' is currently active by issuing the following command: {{ic|cat /proc/1/comm}}. This should return the string {{ic|systemd}}.<br />
# Make sure your hostname is set correctly under ''systemd'': {{ic|hostnamectl set-hostname ''myhostname''}} or {{ic|/etc/hostname}}.<br />
# Proceed to remove ''initscripts'' and ''sysvinit'' from your system and install {{Pkg|systemd-sysvcompat}}.<br />
# Optionally, remove the {{ic|1=init=/usr/lib/systemd/systemd}} parameter. It is no longer needed since {{Pkg|systemd-sysvcompat}} provides a symlink to ''systemd'''s init where ''sysvinit'' used to be.<br />
<br />
=== Supplementary information ===<br />
<br />
* If you have {{ic|quiet}} in your kernel parameters, you might want to remove it for your first couple of systemd boots, to assist with identifying any issues during boot.<br />
<br />
* It is not necessary to add your user to [[Users and Groups|groups]] ({{ic|sys}}, {{ic|disk}}, {{ic|lp}}, {{ic|network}}, {{ic|video}}, {{ic|audio}}, {{ic|optical}}, {{ic|storage}}, {{ic|scanner}}, {{ic|power}}, etc.) for most use cases with systemd. The groups can even cause some functionality to break. For example, the {{ic|audio}} group will break fast user switching and allows applications to block software mixing. Every PAM login provides a logind session, which for a local session will give you permissions via [[Wikipedia:Access control list|POSIX ACLs]] on audio/video devices, and allow certain operations like mounting removable storage via [[udisks]].<br />
<br />
* See the [[Network Configuration]] article for how to set up networking targets.<br />
<br />
== Basic systemctl usage ==<br />
<br />
The main command used to introspect and control ''systemd'' is '''systemctl'''. Some of its uses are examining the system state and managing the system and services. See {{ic|man 1 systemctl}} for more details.<br />
<br />
{{Tip|You can use all of the following ''systemctl'' commands with the {{ic|-H ''user''@''host''}} switch to control a ''systemd'' instance on a remote machine. This will use [[SSH]] to connect to the remote ''systemd'' instance.}}<br />
<br />
{{Note|''systemadm'' is the official graphical frontend for ''systemctl''. It is provided by the {{AUR|systemd-ui-git}} package from the [[AUR]].}}<br />
<br />
=== Analyzing the system state ===<br />
<br />
List running units:<br />
<br />
$ systemctl<br />
<br />
or:<br />
<br />
$ systemctl list-units<br />
<br />
List failed units:<br />
<br />
$ systemctl --failed<br />
<br />
The available unit files can be seen in {{ic|/usr/lib/systemd/system/}} and {{ic|/etc/systemd/system/}} (the latter takes precedence). You can see a list of the installed unit files with:<br />
<br />
$ systemctl list-unit-files<br />
<br />
=== Using units ===<br />
<br />
Units can be, for example, services (''.service''), mount points (''.mount''), devices (''.device'') or sockets (''.socket'').<br />
<br />
When using ''systemctl'', you generally have to specify the complete name of the unit file, including its suffix, for example ''sshd.socket''. There are however a few short forms when specifying the unit in the following ''systemctl'' commands:<br />
<br />
* If you do not specify the suffix, systemctl will assume ''.service''. For example, {{ic|netcfg}} and {{ic|netcfg.service}} are equivalent.<br />
* Mount points will automatically be translated into the appropriate ''.mount'' unit. For example, specifying {{ic|/home}} is equivalent to {{ic|home.mount}}.<br />
* Similar to mount points, devices are automatically translated into the appropriate ''.device'' unit, therefore specifying {{ic|/dev/sda2}} is equivalent to {{ic|dev-sda2.device}}.<br />
<br />
See {{ic|man systemd.unit}} for details.<br />
<br />
Activate a unit immediately:<br />
<br />
# systemctl start ''unit''<br />
<br />
Deactivate a unit immediately:<br />
<br />
# systemctl stop ''unit''<br />
<br />
Restart a unit:<br />
<br />
# systemctl restart ''unit''<br />
<br />
Ask a unit to reload its configuration:<br />
<br />
# systemctl reload ''unit''<br />
<br />
Show the status of a unit, including whether it is running or not:<br />
<br />
$ systemctl status ''unit''<br />
<br />
Check whether a unit is already enabled or not:<br />
<br />
$ systemctl is-enabled ''unit''<br />
<br />
Enable a unit to be started on bootup:<br />
<br />
# systemctl enable ''unit''<br />
<br />
{{Note|Services without an {{ic|[Install]}} section are usually called automatically by other services. If you need to install them manually, use the following command, replacing ''foo'' with the name of the service.<br />
# ln -s /usr/lib/systemd/system/''foo''.service /etc/systemd/system/graphical.target.wants/<br />
}}<br />
<br />
Disable a unit to not start during bootup:<br />
<br />
# systemctl disable ''unit''<br />
<br />
Show the manual page associated with a unit (this has to be supported by the unit file):<br />
<br />
$ systemctl help ''unit''<br />
<br />
Reload ''systemd'', scanning for new or changed units:<br />
<br />
# systemctl daemon-reload<br />
<br />
=== Power management ===<br />
<br />
[[polkit]] is necessary for power management. If you are in a local ''systemd-logind'' user session and no other session is active, the following commands will work without root privileges. If not (for example, because another user is logged into a tty), ''systemd'' will automatically ask you for the root password.<br />
<br />
Shut down and reboot the system:<br />
<br />
$ systemctl reboot<br />
<br />
Shut down and power-off the system:<br />
<br />
$ systemctl poweroff<br />
<br />
Suspend the system:<br />
<br />
$ systemctl suspend<br />
<br />
Put the system into hibernation:<br />
<br />
$ systemctl hibernate<br />
<br />
Put the system into hybrid-sleep state (or suspend-to-both):<br />
<br />
$ systemctl hybrid-sleep<br />
<br />
== Native configuration ==<br />
<br />
{{Note|You may need to create these files. All files should have {{ic|644}} permissions and {{ic|root:root}} ownership.}}<br />
<br />
=== Virtual console ===<br />
{{Deletion|Not strictly related, trying to remove the [[#Native configuration]] section entirely.|section=Duplication of content in Native configuration section}}<br />
<br />
The virtual console (keyboard mapping, console font and console map) is configured in {{ic|/etc/vconsole.conf}} or by using the ''localectl'' tool.<br />
<br />
For more information, see [[Fonts#Console fonts|console fonts]] and [[KEYMAP|keymaps]].<br />
<br />
=== Kernel modules ===<br />
{{Deletion|Not strictly related, trying to remove the [[#Native configuration]] section entirely.|section=Duplication of content in Native configuration section}}<br />
<br />
See [[Kernel modules#Configuration]].<br />
<br />
=== Filesystem mounts ===<br />
{{Merge|File Systems|This section was added here before systemd became the default init system. Delete it after merging.|section=Duplication of content in Native configuration section}}<br />
<br />
The default setup will automatically fsck and mount filesystems before starting services that need them to be mounted. For example, systemd automatically makes sure that remote filesystem mounts like [[NFS]] or [[Samba]] are only started after the network has been set up. Therefore, local and remote filesystem mounts specified in {{ic|/etc/fstab}} should work out of the box.<br />
<br />
See {{ic|man 5 systemd.mount}} for details.<br />
<br />
==== Automount ====<br />
{{Merge|fstab|This section was added here before systemd became the default init system. Delete it after merging.|section=Duplication of content in Native configuration section}}<br />
<br />
If you have a large {{ic|/home}} partition, it might be better to allow services that do not depend on {{ic|/home}} to start while {{ic|/home}} is checked by ''fsck''. This can be achieved by adding the following options to the {{ic|/etc/fstab}} entry of your {{ic|/home}} partition:<br />
<br />
noauto,x-systemd.automount<br />
<br />
This will fsck and mount {{ic|/home}} when it is first accessed, and the kernel will buffer all file access to {{ic|/home}} until it is ready.<br />
<br />
{{Note|This will make your {{ic|/home}} filesystem type {{ic|autofs}}, which is ignored by [[mlocate]] by default. The speedup of automounting {{ic|/home}} may not be more than a second or two, depending on your system, so this trick may not be worth it.}}<br />
<br />
The same applies to remote filesystem mounts. If you want them to be mounted only upon access, you will need to use the {{ic|noauto,x-systemd.automount}} parameters. In addition, you can use the {{ic|1=x-systemd.device-timeout=#}} option to specify a timeout in case the network resource is not available.<br />
<br />
If you have encrypted filesystems with keyfiles, you can also add the {{ic|noauto}} parameter to the corresponding entries in {{ic|/etc/crypttab}}. ''systemd'' will then not open the encrypted device on boot, but instead wait until it is actually accessed and then automatically open it with the specified keyfile before mounting it. This might save a few seconds on boot if you are using an encrypted RAID device for example, because systemd does not have to wait for the device to become available. For example:<br />
<br />
{{hc|/etc/crypttab|<br />
data /dev/md0 /root/key noauto}}<br />
<br />
==== LVM ====<br />
{{Merge|LVM|This section was added here before systemd became the default init system. Delete it after merging.|section=Duplication of content in Native configuration section}}<br />
<br />
If you have [[LVM]] volumes not activated via the [[Mkinitcpio|initramfs]], [[#Using units|enable]] the '''lvm-monitoring''' service, which is provided by the {{pkg|lvm2}} package.<br />
<br />
=== ACPI power management ===<br />
{{Deletion|Not strictly related, trying to remove the [[#Native configuration]] section entirely.|section=Duplication of content in Native configuration section}}<br />
<br />
See [[Power Management]].<br />
<br />
=== Temporary files ===<br />
{{Moveto|Systemd#|Trying to remove the [[#Native configuration]] section entirely, this section can easily become a top-level one like [[#Journal]].|section=Duplication of content in Native configuration section}}<br />
<br />
"'''systemd-tmpfiles''' creates, deletes and cleans up volatile and temporary files and directories." It reads configuration files in {{ic|/etc/tmpfiles.d/}} and {{ic|/usr/lib/tmpfiles.d/}} to discover which actions to perform. Configuration files in the former directory take precedence over those in the latter directory.<br />
<br />
Configuration files are usually provided together with service files, and they are named in the style of {{ic|/usr/lib/tmpfiles.d/''program''.conf}}. For example, the [[Samba]] daemon expects the directory {{ic|/run/samba}} to exist and to have the correct permissions. Therefore, the {{Pkg|samba}} package ships with this configuration:<br />
<br />
{{hc|/usr/lib/tmpfiles.d/samba.conf|<br />
D /run/samba 0755 root root}}<br />
<br />
Configuration files may also be used to write values into certain files on boot. For example, if you used {{ic|/etc/rc.local}} to disable wakeup from USB devices with {{ic|echo USBE > /proc/acpi/wakeup}}, you may use the following tmpfile instead:<br />
<br />
{{hc|/etc/tmpfiles.d/disable-usb-wake.conf|<br />
w /proc/acpi/wakeup - - - - USBE}}<br />
<br />
See the {{ic|systemd-tmpfiles}} and {{ic|tmpfiles.d(5)}} man pages for details.<br />
<br />
{{Note|This method may not work to set options in {{ic|/sys}} since the ''systemd-tmpfiles-setup'' service may run before the appropriate device modules is loaded. In this case you could check whether the module has a parameter for the option you want to set with {{ic|modinfo ''module''}} and set this option with a [[Modprobe.d#Configuration|config file in /etc/modprobe.d]]. Otherwise you will have to write a [[Udev#About_udev_rules|udev rule]] to set the appropriate attribute as soon as the device appears.}}<br />
<br />
== Writing custom .service files ==<br />
<br />
The syntax of systemd's [[#Using units|unit files]] is inspired by XDG Desktop Entry Specification ''.desktop'' files, which are in turn inspired by Microsoft Windows ''.ini'' files.<br />
<br />
See [[systemd/Services]] for more examples.<br />
<br />
=== Handling dependencies ===<br />
<br />
With ''systemd'', dependencies can be resolved by designing the unit files correctly. The most typical case is that the unit ''A'' requires the unit ''B'' to be running before ''A'' is started. In that case add {{ic|1=Requires=''B''}} and {{ic|1=After=''B''}} to the {{ic|[Unit]}} section of ''A''. If the dependency is optional, add {{ic|1=Wants=''B''}} and {{ic|1=After=''B''}} instead. Note that {{ic|1=Wants=}} and {{ic|1=Requires=}} do not imply {{ic|1=After=}}, meaning that if {{ic|1=After=}} is not specified, the two units will be started in parallel.<br />
<br />
Dependencies are typically placed on services and not on targets. For example, ''network.target'' is pulled in by whatever service configures your network interfaces, therefore ordering your custom unit after it is sufficient since ''network.target'' is started anyway.<br />
<br />
=== Type ===<br />
<br />
There are several different start-up types to consider when writing a custom service file. This is set with the {{ic|1=Type=}} parameter in the {{ic|[Service]}} section. See {{ic|man systemd.service}} for a more detailed explanation.<br />
<br />
* {{ic|1=Type=simple}} (default): ''systemd'' considers the service to be started up immediately. The process must not fork. Do not use this type if other services need to be ordered on this service, unless it is socket activated.<br />
* {{ic|1=Type=forking}}: ''systemd'' considers the service started up once the process forks and the parent has exited. For classic daemons use this type unless you know that it is not necessary. You should specify {{ic|1=PIDFile=}} as well so ''systemd'' can keep track of the main process.<br />
* {{ic|1=Type=oneshot}}: this is useful for scripts that do a single job and then exit. You may want to set {{ic|1=RemainAfterExit=yes}} as well so that ''systemd'' still considers the service as active after the process has exited.<br />
* {{ic|1=Type=notify}}: identical to {{ic|1=Type=simple}}, but with the stipulation that the daemon will send a signal to ''systemd'' when it is ready. The reference implementation for this notification is provided by ''libsystemd-daemon.so''.<br />
* {{ic|1=Type=dbus}}: the service is considered ready when the specified {{ic|BusName}} appears on DBus's system bus.<br />
<br />
=== Editing provided unit files ===<br />
<br />
To edit a unit file provided by a package, you can create a directory called {{ic|/etc/systemd/system/''unit''.d/}} for example {{ic|/etc/systemd/system/httpd.service.d/}} and place ''*.conf'' files in there to override or add new options. ''systemd'' will parse these ''*.conf'' files and apply them on top of the original unit. For example, if you simply want to add an additional dependency to a unit, you may create the following file:<br />
<br />
{{hc|/etc/systemd/system/''unit''.d/customdependency.conf|2=<br />
[Unit]<br />
Requires=''new dependency''<br />
After=''new dependency''<br />
}}<br />
<br />
As another example, in order to replace the {{ic|ExecStart}} directive for a unit that is not of type {{ic|oneshot}}, create the following file:<br />
<br />
{{hc|/etc/systemd/system/''unit''.d/customexec.conf|2=<br />
[Service]<br />
ExecStart=<br />
ExecStart=''new command''<br />
}}<br />
<br />
One more example to automatically restart a service:<br />
<br />
{{hc|/etc/systemd/system/''unit''.d/restart.conf|2=<br />
[Service]<br />
Restart=always<br />
RestartSec=30<br />
}}<br />
<br />
Then run the following for your changes to take effect:<br />
<br />
# systemctl daemon-reload<br />
# systemctl restart ''unit''<br />
<br />
Alternatively you can copy the old unit file from {{ic|/usr/lib/systemd/system/}} to {{ic|/etc/systemd/system/}} and make your changes there. A unit file in {{ic|/etc/systemd/system/}} always overrides the same unit in {{ic|/usr/lib/systemd/system/}}. Note that when the original unit in {{ic|/usr/lib/}} is changed due to a package upgrade, these changes will not automatically apply to your custom unit file in {{ic|/etc/}}. Additionally you will have to manually reenable the unit with {{ic|systemctl reenable ''unit''}}. It is therefore recommended to use the ''*.conf'' method described before instead.<br />
<br />
{{Tip|You can use '''systemd-delta''' to see which unit files have been overridden and what exactly has been changed.}}<br />
<br />
As the provided unit files will be updated from time to time, use ''systemd-delta'' for system maintenance.<br />
<br />
=== Syntax highlighting for units within Vim ===<br />
<br />
Syntax highlighting for ''systemd'' unit files within [[Vim]] can be enabled by installing {{Pkg|vim-systemd}} from the [[official repositories]].<br />
<br />
== Targets ==<br />
<br />
''systemd'' uses ''targets'' which serve a similar purpose as runlevels but act a little different. Each ''target'' is named instead of numbered and is intended to serve a specific purpose with the possibility of having multiple ones active at the same time. Some ''target''s are implemented by inheriting all of the services of another ''target'' and adding additional services to it. There are ''systemd'' ''target''s that mimic the common SystemVinit runlevels so you can still switch ''target''s using the familiar {{ic|telinit RUNLEVEL}} command.<br />
<br />
=== Get current targets ===<br />
<br />
The following should be used under ''systemd'' instead of running {{ic|runlevel}}:<br />
<br />
$ systemctl list-units --type=target<br />
<br />
=== Create custom target ===<br />
<br />
The runlevels that are assigned a specific purpose on vanilla Fedora installs; 0, 1, 3, 5, and 6; have a 1:1 mapping with a specific ''systemd'' ''target''. Unfortunately, there is no good way to do the same for the user-defined runlevels like 2 and 4. If you make use of those it is suggested that you make a new named ''systemd'' ''target'' as {{ic|/etc/systemd/system/''your target''}} that takes one of the existing runlevels as a base (you can look at {{ic|/usr/lib/systemd/system/graphical.target}} as an example), make a directory {{ic|/etc/systemd/system/''your target''.wants}}, and then symlink the additional services from {{ic|/usr/lib/systemd/system/}} that you wish to enable.<br />
<br />
=== Targets table ===<br />
<br />
{| border="1"<br />
! SysV Runlevel !! systemd Target !! Notes<br />
|-<br />
| 0 || runlevel0.target, poweroff.target || Halt the system.<br />
|-<br />
| 1, s, single || runlevel1.target, rescue.target || Single user mode.<br />
|-<br />
| 2, 4 || runlevel2.target, runlevel4.target, multi-user.target || User-defined/Site-specific runlevels. By default, identical to 3.<br />
|-<br />
| 3 || runlevel3.target, multi-user.target || Multi-user, non-graphical. Users can usually login via multiple consoles or via the network.<br />
|-<br />
| 5 || runlevel5.target, graphical.target || Multi-user, graphical. Usually has all the services of runlevel 3 plus a graphical login.<br />
|-<br />
| 6 || runlevel6.target, reboot.target || Reboot<br />
|-<br />
| emergency || emergency.target || Emergency shell<br />
|-<br />
|}<br />
<br />
=== Change current target ===<br />
<br />
In ''systemd'' targets are exposed via ''target units''. You can change them like this:<br />
<br />
# systemctl isolate graphical.target<br />
<br />
This will only change the current target, and has no effect on the next boot. This is equivalent to commands such as {{ic|telinit 3}} or {{ic|telinit 5}} in Sysvinit.<br />
<br />
=== Change default target to boot into ===<br />
<br />
The standard target is ''default.target'', which is aliased by default to ''graphical.target'' (which roughly corresponds to the old runlevel 5). To change the default target at boot-time, append one of the following [[kernel parameters]] to your bootloader:<br />
<br />
{{Tip|The ''.target'' extension can be left out.}}<br />
<br />
* {{ic|1=systemd.unit=multi-user.target}} (which roughly corresponds to the old runlevel 3),<br />
* {{ic|1=systemd.unit=rescue.target}} (which roughly corresponds to the old runlevel 1).<br />
<br />
Alternatively, you may leave the bootloader alone and change ''default.target''. This can be done using ''systemctl'':<br />
<br />
# systemctl enable multi-user.target<br />
<br />
The effect of this command is output by ''systemctl''; a symlink to the new default target is made at {{ic|/etc/systemd/system/default.target}}. This works if, and only if:<br />
<br />
[Install]<br />
Alias=default.target<br />
<br />
is in the target's configuration file. Currently, ''multi-user.target'' and ''graphical.target'' both have it.<br />
<br />
== Timers ==<br />
<br />
Systemd can replace cron functionality to a great extent. For further information, please refer to [[systemd/cron functionality]].<br />
<br />
== Journal ==<br />
<br />
''systemd'' has its own logging system called the journal; therefore, running a syslog daemon is no longer required. To read the log, use:<br />
<br />
# journalctl<br />
<br />
As in Arch Linux the directory {{ic|/var/log/journal/}} is part of the ''systemd'' package, the journal (when {{ic|1=Storage=}} is set to {{ic|auto}} in {{ic|/etc/systemd/journald.conf}}) will write to {{ic|/var/log/journal/}}. If you or some program delete that directory, systemd will '''not''' recreate it automatically; however, it will be recreated during the next update of the systemd package. Until then, logs will be written to {{ic|/run/systemd/journal}}, and logs will be lost on reboot.<br />
<br />
{{Tip|If {{ic|/var/log/journal/}} resides in a [[btrfs]] filesystem you should consider disabling [[Btrfs#Copy-On-Write_.28CoW.29|Copy-on-Write]] for the directory:<br />
# chattr +C /var/log/journal<br />
}}<br />
<br />
=== Filtering output ===<br />
<br />
''journalctl'' allows you to filter the output by specific fields.<br />
<br />
Examples:<br />
<br />
Show all messages from this boot:<br />
<br />
# journalctl -b<br />
<br />
{{note|{{ic|journalctl -b}} takes arguments such as {{ic|-0}} for the last boot or a boot id. E.g. {{ic|journalctl -b -3}} will show all messages from the fourth to last boot.}}<br />
<br />
Follow new messages:<br />
<br />
# journalctl -f<br />
<br />
Show all messages by a specific executable:<br />
<br />
# journalctl /usr/lib/systemd/systemd<br />
<br />
Show all messages by a specific process:<br />
<br />
# journalctl _PID=1<br />
<br />
Show all messages by a specific unit:<br />
<br />
# journalctl -u netcfg<br />
<br />
Show kernel ring buffer:<br />
<br />
# journalctl _TRANSPORT=kernel<br />
<br />
See {{ic|man 1 journalctl}}, {{ic|man 7 systemd.journal-fields}}, or Lennert's [http://0pointer.de/blog/projects/journalctl.html blog post] for details.<br />
<br />
=== Journal size limit ===<br />
<br />
If the journal is persistent (non-volatile), its size limit is set to a default value of 10% of the size of the respective file system. For example, with {{ic|/var/log/journal}} located on a 50 GiB root partition this would lead to 5 GiB of journal data. The maximum size of the persistent journal can be controlled by {{ic|SystemMaxUse}} in {{ic|/etc/systemd/journald.conf}}, so to limit it for example to 50 MiB uncomment and edit the corresponding line to:<br />
<br />
SystemMaxUse=50M<br />
<br />
Refer to {{ic|man journald.conf}} for more info.<br />
<br />
=== Journald in conjunction with syslog ===<br />
<br />
Compatibility with classic syslog implementations is provided via a socket {{ic|/run/systemd/journal/syslog}}, to which all messages are forwarded. To make the syslog daemon work with the journal, it has to bind to this socket instead of {{ic|/dev/log}} ([http://lwn.net/Articles/474968/ official announcement]). The {{Pkg|syslog-ng}} package in the repositories automatically provides the necessary configuration.<br />
<br />
# systemctl enable syslog-ng<br />
<br />
A good ''journalctl'' tutorial is [http://0pointer.de/blog/projects/journalctl.html here].<br />
<br />
=== Forward journald to /dev/tty12 ===<br />
<br />
In {{ic|/etc/systemd/journald.conf}} enable the following:<br />
<br />
ForwardToConsole=yes<br />
TTYPath=/dev/tty12<br />
MaxLevelConsole=info<br />
<br />
Restart journald with {{ic|sudo systemctl restart systemd-journald}}.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Investigating systemd errors ===<br />
<br />
As an example, we will investigate an error with {{ic|systemd-modules-load}} service:<br />
<br />
'''1.''' Lets find the systemd services which fail to start:<br />
{{hc|1=$ systemctl --state=failed|2=<br />
systemd-modules-load.service loaded '''failed failed''' Load Kernel Modules<br />
}}<br />
<br />
'''2.''' Ok, we found a problem with {{ic|systemd-modules-load}} service. We want to know more:<br />
{{hc|$ systemctl status systemd-modules-load|2=<br />
systemd-modules-load.service - Load Kernel Modules<br />
Loaded: loaded (/usr/lib/systemd/system/systemd-modules-load.service; static)<br />
Active: '''failed''' (Result: exit-code) since So 2013-08-25 11:48:13 CEST; 32s ago<br />
Docs: man:systemd-modules-load.service(8).<br />
man:modules-load.d(5)<br />
Process: '''15630''' ExecStart=/usr/lib/systemd/systemd-modules-load ('''code=exited, status=1/FAILURE''')<br />
}}<br />
<br />
'''3.''' Now we have the process id (PID) to investigate this error in depth. Enter the following command with the current {{ic|Process ID}} (here: 15630):<br />
{{hc|1=$ journalctl -b _PID=15630|2=<br />
-- Logs begin at Sa 2013-05-25 10:31:12 CEST, end at So 2013-08-25 11:51:17 CEST. --<br />
Aug 25 11:48:13 mypc systemd-modules-load[15630]: '''Failed to find module 'blacklist usblp''''<br />
Aug 25 11:48:13 mypc systemd-modules-load[15630]: '''Failed to find module 'install usblp /bin/false'''' <br />
}}<br />
<br />
'''4.''' We see that some of the kernel module configs have wrong settings. Therefore we have a look at these settings in {{ic|/etc/modules-load.d/}}:<br />
{{hc|$ ls -Al /etc/modules-load.d/|<br />
...<br />
-rw-r--r-- 1 root root 79 1. Dez 2012 blacklist.conf<br />
-rw-r--r-- 1 root root 1 2. Mär 14:30 encrypt.conf<br />
-rw-r--r-- 1 root root 3 5. Dez 2012 printing.conf<br />
-rw-r--r-- 1 root root 6 14. Jul 11:01 realtek.conf<br />
-rw-r--r-- 1 root root 65 2. Jun 23:01 virtualbox.conf<br />
...<br />
}}<br />
<br />
'''5.''' The {{ic|Failed to find module 'blacklist usblp'}} error message might be related to a wrong setting inside of {{ic|blacklist.conf}}. Lets deactivate it with inserting a trailing '''#''' before each option we found via step 3:<br />
{{hc|/etc/modules-load.d/blacklist.conf|<br />
'''#''' blacklist usblp<br />
'''#''' install usblp /bin/false<br />
}}<br />
<br />
'''6.''' Now, try to start {{ic|systemd-modules-load}}:<br />
$ systemctl start systemd-modules-load.service<br />
If it was successful, this shouldn't prompt anything. If you see any error, go back to step 3. and use the new PID for solving the errors left.<br />
<br />
If everything is ok, you can verify that the service was started successfully with:<br />
{{hc|$ systemctl status systemd-modules-load|2=<br />
systemd-modules-load.service - Load Kernel Modules<br />
Loaded: '''loaded''' (/usr/lib/systemd/system/systemd-modules-load.service; static)<br />
Active: '''active (exited)''' since So 2013-08-25 12:22:31 CEST; 34s ago<br />
Docs: man:systemd-modules-load.service(8)<br />
man:modules-load.d(5)<br />
Process: 19005 ExecStart=/usr/lib/systemd/systemd-modules-load (code=exited, status=0/SUCCESS)<br />
Aug 25 12:22:31 mypc systemd[1]: '''Started Load Kernel Modules'''.<br />
}}<br />
<br />
Often you can solve these kind of problems like shown above. For further investigation look at [[#Diagnosing boot problems|Diagnosing boot problems]].<br />
<br />
=== Diagnosing boot problems ===<br />
<br />
Boot with these parameters on the kernel command line:<br />
{{ic|<nowiki>systemd.log_level=debug systemd.log_target=kmsg log_buf_len=1M</nowiki>}}<br />
<br />
[http://freedesktop.org/wiki/Software/systemd/Debugging More Debugging Information]<br />
<br />
=== Shutdown/reboot takes terribly long ===<br />
<br />
If the shutdown process takes a very long time (or seems to freeze) most likely a service not exiting is to blame. ''systemd'' waits some time for each service to exit before trying to kill it. To find out if you are affected, see [http://freedesktop.org/wiki/Software/systemd/Debugging/#shutdowncompleteseventually this article].<br />
<br />
=== Short lived processes do not seem to log any output ===<br />
<br />
If {{ic|journalctl -u foounit}} does not show any output for a short lived service, look at the PID instead. For example, if {{ic|systemd-modules-load.service}} fails, and {{ic|systemctl status systemd-modules-load}} shows that it ran as PID 123, then you might be able to see output in the journal for that PID, i.e. {{ic|journalctl -b _PID&#61;123}}. Metadata fields for the journal such as _SYSTEMD_UNIT and _COMM are collected asynchronously and rely on the {{ic|/proc}} directory for the process existing. Fixing this requires fixing the kernel to provide this data via a socket connection, similar to SCM_CREDENTIALS.<br />
<br />
=== Disabling application crash dumps journaling ===<br />
<br />
Run the following in order to overwrite the settings from {{ic|/lib/sysctl.d/}}:<br />
# ln -s /dev/null /etc/sysctl.d/50-coredump.conf<br />
# sysctl kernel.core_pattern=core<br />
<br />
This will disable logging of coredumps to the journal.<br />
<br />
Note that the default RLIMIT_CORE of 0 means that no core files are written, either.<br />
If you want them, you also need to "unlimit" the core file size in the shell:<br />
$ ulimit -c unlimited<br />
<br />
See [http://www.freedesktop.org/software/systemd/man/sysctl.d.html sysctl.d] and [https://www.kernel.org/doc/Documentation/sysctl/kernel.txt the documentation for /proc/sys/kernel] for more information.<br />
<br />
== See also ==<br />
<br />
*[http://www.freedesktop.org/wiki/Software/systemd Official web site]<br />
*[[Wikipedia:systemd|Wikipedia article]]<br />
*[http://0pointer.de/public/systemd-man/ Manual pages]<br />
*[http://freedesktop.org/wiki/Software/systemd/Optimizations systemd optimizations]<br />
*[http://www.freedesktop.org/wiki/Software/systemd/FrequentlyAskedQuestions FAQ]<br />
*[http://www.freedesktop.org/wiki/Software/systemd/TipsAndTricks Tips and tricks]<br />
*[http://0pointer.de/public/systemd-ebook-psankar.pdf systemd for Administrators (PDF)]<br />
*[http://fedoraproject.org/wiki/Systemd About systemd on Fedora Project]<br />
*[http://fedoraproject.org/wiki/How_to_debug_Systemd_problems How to debug systemd problems]<br />
*[http://www.h-online.com/open/features/Control-Centre-The-systemd-Linux-init-system-1565543.html Two] [http://www.h-online.com/open/features/Booting-up-Tools-and-tips-for-systemd-1570630.html part] introductory article in ''The H Open'' magazine.<br />
*[http://0pointer.de/blog/projects/systemd.html Lennart's blog story]<br />
*[http://0pointer.de/blog/projects/systemd-update.html Status update]<br />
*[http://0pointer.de/blog/projects/systemd-update-2.html Status update2]<br />
*[http://0pointer.de/blog/projects/systemd-update-3.html Status update3]<br />
*[http://0pointer.de/blog/projects/why.html Most recent summary]<br />
*[http://fedoraproject.org/wiki/SysVinit_to_Systemd_Cheatsheet Fedora's SysVinit to systemd cheatsheet]<br />
*[[Allow Users to Shutdown|Configuring systemd to allow normal users to shutdown]]</div>Visithttps://wiki.archlinux.org/index.php?title=Mkinitcpio-btrfs&diff=281459Mkinitcpio-btrfs2013-11-04T22:43:36Z<p>Visit: Added a warning for a current design bug.</p>
<hr />
<div>{{Warning|This article is completely redesigned as of today (October 25th 2013). I've stipped all (in my opinion) unnecessary or outdated information. In case there is something missing, you can find it in the history.}}<br />
<br />
[[Category:Getting and installing Arch]]<br />
{{Article summary start}}<br />
{{Article summary text|Installing on btrfs root Outlines a process for installing (or converting) Arch Linux to a btrfs root drive with syslinux or GRUB2.}}<br />
{{Article summary heading|Overview}}<br />
{{Article summary text|{{Boot process overview}}}}<br />
{{Article summary heading|Resources}}<br />
{{Article summary text|[[Wikipedia:Btrfs|Btrfs &mdash; Wikipedia]]}}<br />
{{Article summary link|FAQ &mdash; Btrfs Wiki|https://btrfs.wiki.kernel.org/articles/f/a/q/FAQ_1fe9.html#Is_btrfs_stable.3F}}<br />
{{Article summary link|GNU GRUB &mdash; GNU Project|https://gnu.org/s/grub/}}<br />
{{Article summary link|Syslinux Website|http://www.syslinux.org/wiki/index.php/The_Syslinux_Project}}<br />
{{Article summary text|[[Wikipedia:GUID Partition Table|GUID Partition Table &mdash; Wikipedia]]}}<br />
{{Article summary end}}<br />
<br />
[[Btrfs]] provides a number of features that make it an excellent candidate for using it as the root partition in an Arch Linux installation:<br />
* ''instant'' snapshots<br />
* non-volatile rollback support<br />
* integrated multi-device support [[RAID]]<br />
* online resize, add/remove devices, defragmentation<br />
* online fsck, checksumming and auto-correction<br />
<br />
For a tour of btrfs features see [http://www.youtube.com/watch?v=hxWuaozpe2I A tour of btrfs]. As is common with FLOSS, there are a number of ways to configure btrfs as the root filesystem.<br />
<br />
This article assumes your are doing a fresh install from the [https://www.archlinux.org/download/ Arch Linux installation media].<br />
<br />
{{Note|This article is an extension of the [[Official Arch Linux Install Guide]]. It asumes you have gained an overview on the general process of installing Arch Linux and will not provide back references to this guide.}}<br />
<br />
{{Note|Arch's default mkinitcpio package contains a standard ''btrfs'' hook, which is enough to get multi-device ([[RAID]]) support. Beside that, the kernel is capable of booting a single-device btrfs root without any hook.}}<br />
<br />
== mkinitcpio-btrfs ==<br />
<br />
First of all you need to decide, if you want to use some of Btrfs's neat features like non-volatile rollback or automatic mounting of degraded Btrfs multi-device ([[RAID]]) volumes. To enable this features you need a special package from the [[Arch User Repository]] called {{AUR|mkinitcpio-btrfs}}. The package integrates some helpers in your boot process, to handle these features correctly.<br />
<br />
This guide can also be followed without this package, through I generally recommend it. The relevant sections contain notes for both types of setup.<br />
<br />
== Prerequisites ==<br />
<br />
Boot up your [https://www.archlinux.org/download/ Arch Linux installation media] and configure your network connection if not done automatically.<br />
<br />
== btrfs-progs ==<br />
<br />
To create a btrfs filesystem you will need to [[pacman|install]] the {{Pkg|btrfs-progs}} from [[Official Repositories]]. This package is normally present on your installation media. It is still a good idea to perform an update, to make sure you have the latest version of it.<br />
<br />
== Partition disks ==<br />
<br />
Partition your drive as you prefer. Both ([[GUID Partition Table|GPT]] and [[Master Boot Record|MBR]]) partition tables are supported. If you want do encrypt your Btrfs, use [[dm-crypt with LUKS|dm-crypt]].<br />
<br />
Btrfs has [https://btrfs.wiki.kernel.org/index.php/UseCases#RAID build-in RAID support]. Setting up at least RAID1 '''is recommended for enabling its internal selfhealing features'''. If you don't have two drives, setup two partitions of the same size on one drive.<br />
<br />
{{Warning|If you want true non-volatile rollback support you '''MUST NOT''' create a separate {{ic|/boot}} partition, as this will prevent rollback of your kernel.}}<br />
<br />
{{Note|Having boot on a different partition in not supported with {{AUR|mkinitcpio-btrfs}} >&#61; 0.4. This is because, kexec is used to reload the kernel from your root partition to make sure it is rolled back too. If you want, you can put it on a subvolume within your {{ic|__active}} subvolume. Btrfs will automatically mount subvolume included in the currently mounted one.}}<br />
<br />
{{Warning|If you need '''Swap''' support create a separate partition for it. '''DO NOT''' simply use a swap file! [http://git.kernel.org/?p&#61;linux/kernel/git/torvalds/linux-2.6.git;a&#61;commit;h&#61;35054394c4b3cecd52577c2662c84da1f3e73525 Doing so will slow down your btrfs filesystem].}}<br />
<br />
== Format the partitions ==<br />
<br />
Use {{ic|mkfs.btrfs}} to create your root partition.<br />
<br />
# mkfs.btrfs -L root -m raid1 -d raid1 /dev/sda1 /dev/sdb1<br />
<br />
== Mount the partitions ==<br />
<br />
Now it is time to mount the new filesystem. First create the mount directory:<br />
<br />
# mount -o defaults,relatime,compress=lzo,ssd,discard /dev/sda1 /mnt<br />
<br />
{{Note|If you are not using an '''SSD drive''', remove {{ic|ssd,discard}} from the mount options.}}<br />
<br />
{{Note|'''Compression''' [http://www.phoronix.com/scan.php?page&#61;article&item&#61;btrfs_compress_2635&num&#61;1 improves performance], since btrfs frequently writes its trees to the disk. The CPU usage needed for that is not worth mentioning. Allowed compression methods are [http://www.phoronix.com/scan.php?page&#61;article&item&#61;btrfs_lzo_2638&num&#61;1 lzo] and gzip.}}<br />
<br />
=== Configure the btrfs filesystem ===<br />
<br />
Clone the btrfs root to an {{ic|__active}} subvolume for your future system root directory {{ic|/}}. This will enable you to take snapshots in a directory outside of your system root and helps keeping a clean filesystem structure.<br />
<br />
# cd /mnt<br />
# btrfs subvolume snapshot . __active<br />
<br />
If you plan on using the rollback features of btrfs, create a {{ic|__snapshot}} directory for containing snapshots.<br />
<br />
# cd /mnt<br />
# mkdir __snapshot<br />
<br />
{{Note|The subvolume and folder names are chosen for integration with current {{AUR|mkinitcpio-btrfs}}. You can also use different subvolume and folder names and specify them in {{ic|/etc/default/btrfs_advanced}} later.}}<br />
<br />
You can create separate subvolumes for important [http://www.pathname.com/fhs/ FHS] directories. This would allow you to monitor and adjust the size allocations for each subvolume using {{ic|btrfs quota}}:<br />
<br />
{{Warning|{{AUR|mkinitcpio-btrfs}} doesn't handle these subvolumes correctly atm. You will not be able to use it's rollback support. Follow the [https://github.com/xtfxme/mkinitcpio-btrfs/issues/6 discussion].}}<br />
<br />
# cd /mnt/__active<br />
# btrfs subvolume create home<br />
# btrfs subvolume create var<br />
# btrfs subvolume create usr<br />
<br />
To see your handy work:<br />
<br />
{{hc|# btrfs subvolume list -p .|<br />
ID 256 parent 5 top level 5 path __active<br />
ID 258 parent 256 top level 5 path __active/home<br />
ID 259 parent 256 top level 5 path __active/usr<br />
ID 260 parent 256 top level 5 path __active/var<br />
}}<br />
<br />
{{Note|Child subvolumes are automatically mounted by Btrfs when the parent subvolume is mounted. This makes mounting extremely easy at boot time.}}<br />
<br />
Btrfs supports to set a default subvolume, which is mounted if no {{ic|subvol&#61;}} option is provided at mount time. If you plan to use {{AUR|mkinitcpio-btrfs}} later on, you '''MUST''' set this default subvolume to your {{ic|__active}} subvolume.<br />
<br />
{{hc|# btrfs subvolume list .|<br />
ID 256 gen 98 top level 5 path __active}}<br />
<br />
# btrfs subvolume set-default 256 .<br />
<br />
<br />
Now that the subvolumes are created and we have a layout, lets mount the root subvolume directly:<br />
<br />
# cd<br />
# umount /mnt<br />
# mount -o defaults,relatime,compress=lzo,ssd,discard /dev/sda1 /mnt<br />
<br />
{{Note|If you did not set the default subvolume you need to add an additional {{ic|subvol&#61;__active}} mount option.}}<br />
<br />
{{Note|If you are not using an '''SSD drive''', remove {{ic|ssd,discard}} from the mount options.}}<br />
<br />
{{Note|'''Compression''' [http://www.phoronix.com/scan.php?page&#61;article&item&#61;btrfs_compress_2635&num&#61;1 improves performance], since btrfs frequently writes its trees to the disk. The CPU usage needed for that is not worth mentioning. Allowed compression methods are [http://www.phoronix.com/scan.php?page&#61;article&item&#61;btrfs_lzo_2638&num&#61;1 lzo] and gzip.}}<br />
<br />
== Install the base system ==<br />
<br />
Proceed with bootstrap. If you plan to use {{AUR|mkinitcpio-btrfs}}, add its dependencys {{Pkg|btrfs-progs}} and {{Pkg|kexec-tools}}. You'll also need {{Pkg|base-devel}} to build the package from AUR. And add your favorite boot loader to the {{ic|pacstrap}} command too.<br />
<br />
# pacstrap /mnt base base-devel btrfs-progs kexec-tools grub<br />
<br />
If you plan to use {{AUR|mkinitcpio-btrfs}} download its tarball to your chroot environment.<br />
<br />
# wget -O /mnt/root/mkinitcpio-btrfs.tar.gz https://aur.archlinux.org/packages/mk/mkinitcpio-btrfs/mkinitcpio-btrfs.tar.gz<br />
<br />
== Configure the system ==<br />
<br />
Once the you have successfully configured your Arch Linux, it is important that we tweak some settings to get everything working together so when you reboot everything will work correctly.<br />
<br />
Create a place where you mount the Btrfs root subvolume to create snapshots later.<br />
<br />
# mkdir /var/lib/btrfs<br />
<br />
=== /etc/fstab ===<br />
<br />
# nano /mnt/etc/fstab<br />
<br />
Add the following line, supplement {{ic|<uuid>}} for the UUID of the btrfs root partition:<br />
<br />
UUID=<uuid> / btrfs defaults,relatime,compress=lzo,ssd,discard 0 0<br />
UUID=<uuid> /var/lib/btrfs btrfs defaults,relatime,compress=lzo,ssd,discard,subvolid=0 0 0<br />
<br />
{{Note|If you did not set the default subvolume you need to add an additional {{ic|subvol&#61;__active}} mount option.}}<br />
<br />
{{Note|If you are not using an '''SSD drive''', remove {{ic|ssd,discard}} from the mount options.}}<br />
<br />
{{Note|'''Compression''' [http://www.phoronix.com/scan.php?page&#61;article&item&#61;btrfs_compress_2635&num&#61;1 improves performance], since btrfs frequently writes its trees to the disk. The CPU usage needed for that is not worth mentioning. Allowed compression methods are [http://www.phoronix.com/scan.php?page&#61;article&item&#61;btrfs_lzo_2638&num&#61;1 lzo] and gzip.}}<br />
<br />
{{Note|Optional bind an empty folder over the {{ic|/var/lib/btrfs/__active}} folder to prevent apps such as 'find' from complaining of any loops.}}<br />
<br />
/var/lib/btrfs/empty /var/lib/btrfs/__active none bind 0 0<br />
<br />
=== mkinitcpio-btrfs ===<br />
<br />
To install {{AUR|mkinitcpio-btrfs}} you need to extract the AUR package and build it.<br />
<br />
# cd /root<br />
# tar -zxvf mkinitcpio-btrfs.tar.gz<br />
# cd mkinitcpio-btrfs<br />
# makepkg -i --asroot<br />
<br />
After installation, modify {{ic|/etc/default/btrfs_advanced}} to your needs. And don't forget to add {{ic|btrfs-advanced}} to your {{ic|HOOKS}} variable in {{ic|/etc/mkinitcpio.conf}}.<br />
<br />
{{Note|You can savely remove {{ic|fsck}} from your {{ic|HOOKS}} variable, because Btrfs has a online fsck feature, and therefore doesn't provide an fsck module.}}<br />
<br />
Now regenerate your initial RAM-disk.<br />
<br />
# mkinitcpio -p linux<br />
<br />
== Install and configure a bootloader ==<br />
<br />
Now proceed with installing your bootloader.<br />
<br />
=== GRUB ===<br />
<br />
{{Note|To see all your boot messages I recommend to remove the {{ic|silent}} option from {{ic|GRUB_CMDLINE_LINUX_DEFAULT}} in {{ic|/etc/default/grub}}. To prevent tty1 to flush all boot messages before printing the login prompt, edit {{ic|/etc/systemd/system/getty.target.wants/getty@tty1.service}} and change {{ic|TTYVTDisallocate}} to {{ic|no}}.}}<br />
<br />
Grub is able to boot directly from Btrfs root. So just do the usual installation steps.<br />
<br />
{{Note|To have your multi-device Btrfs boot if your first device has failed, add the bootloader to the second device too.}}<br />
<br />
# grub-install --target=i386-pc --recheck /dev/sda<br />
# grub-install --target=i386-pc --recheck /dev/sdb<br />
# cp /usr/share/locale/en\@quot/LC_MESSAGES/grub.mo /boot/grub/locale/en.mo<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
Make sure that your Btrfs root is correctly added to the kernel commandline in {{ic|/boot/grub/grub.cfg}}. Using UUIDs for device identification is especially useful for multi-device ([[RAID]]) setups, because all Btrfs devices own the same UUID.<br />
<br />
root=UUID=fd88d586-bb4c-4fc7-81a6-f675e2829581<br />
<br />
{{Warning|If you've set the default subvolume you '''MUST NOT''' add {{ic|subvol&#61;__active}} to your {{ic|rootflags}}.}}<br />
<br />
{{Note|Having boot on a different partition in not supported with {{AUR|mkinitcpio-btrfs}} >&#61; 0.4. This is because, kexec is used to reload the kernel from your root partition to make sure it is rolled back too. If you want, you can put it on a subvolume within your {{ic|__active}} subvolume. Btrfs will automatically mount subvolume included in the currently mounted one.}}<br />
<br />
=== Syslinux EFI ===<br />
<br />
To boot from Btrfs using syslinux EFI, you need to setup up a dedicated EFI partition in {{ic|/boot/efi}}. This partition needs to be formated as FAT32 (or HPFS on MacBooks). You need to set up your Syslinux directories on that special partition as described in [[Syslinux]].<br />
<br />
{{Warning|The downside of this setup is, that you need to store a working kernel image and its initrd on the EFI partition, because Syslinux can not access Btrfs filesystems directly. {{AUR|mkinitcpio-btrfs}} will then mount your Btrfs root and reload the kernel from your Btrfs {{ic|/boot}} directory.}}<br />
<br />
In {{ic|/boot/efi/EFI/syslinux/syslinux.cfg}} make sure your Btrfs root is correctly added to the {{ic|APPEND}} line.<br />
<br />
APPEND root=UUID=978e3e81-8048-4ae1-8a06-aa727458e8ff rw<br />
<br />
{{Warning|If you've set the default subvolume you '''MUST NOT''' add {{ic|subvol&#61;__active}} to your {{ic|APPEND}} line.}}<br />
<br />
== Usage Hints ==<br />
<br />
To create a snapshot of your root filesystem execute:<br />
<br />
# cd /var/lib/btrfs<br />
# sudo btrfs subvolume snapshot __active __snapshot/[snapshot name]<br />
<br />
Use {{ic|btrfs scrub}} for periodic online filesystem checks:<br />
<br />
# sudo btrfs scrub start /<br />
# sudo btrfs scrub status /<br />
<br />
== Known issues ==<br />
<br />
If you use a multi device ([[RAID]]) setup, make sure you rebalance after system upgrades, to prevent kernel panic on device failure:<br />
<br />
# sudo btrfs balance /</div>Visithttps://wiki.archlinux.org/index.php?title=Mkinitcpio-btrfs&diff=279654Mkinitcpio-btrfs2013-10-24T23:58:24Z<p>Visit: Redesigned the page to match current state of Btrfs and make it compatible to the AUR package mkinitcpio-btrfs again.</p>
<hr />
<div>{{Warning|This article is completely redesigned as of today (October 25th 2013). I've stipped all (in my opinion) unnecessary or outdated information. In case there is something missing, you can find it in the history.}}<br />
<br />
[[Category:Getting and installing Arch]]<br />
{{Article summary start}}<br />
{{Article summary text|Installing on btrfs root Outlines a process for installing (or converting) Arch Linux to a btrfs root drive with syslinux or GRUB2.}}<br />
{{Article summary heading|Overview}}<br />
{{Article summary text|{{Boot process overview}}}}<br />
{{Article summary heading|Resources}}<br />
{{Article summary text|[[Wikipedia:Btrfs|Btrfs &mdash; Wikipedia]]}}<br />
{{Article summary link|FAQ &mdash; Btrfs Wiki|https://btrfs.wiki.kernel.org/articles/f/a/q/FAQ_1fe9.html#Is_btrfs_stable.3F}}<br />
{{Article summary link|GNU GRUB &mdash; GNU Project|https://gnu.org/s/grub/}}<br />
{{Article summary link|Syslinux Website|http://www.syslinux.org/wiki/index.php/The_Syslinux_Project}}<br />
{{Article summary text|[[Wikipedia:GUID Partition Table|GUID Partition Table &mdash; Wikipedia]]}}<br />
{{Article summary end}}<br />
<br />
[[Btrfs]] provides a number of features that make it an excellent candidate for using it as the root partition in an Arch Linux installation:<br />
* ''instant'' snapshots<br />
* non-volatile rollback support<br />
* integrated multi-device support [[RAID]]<br />
* online resize, add/remove devices, defragmentation<br />
* online fsck, checksumming and auto-correction<br />
<br />
For a tour of btrfs features see [http://www.youtube.com/watch?v=hxWuaozpe2I A tour of btrfs]. As is common with FLOSS, there are a number of ways to configure btrfs as the root filesystem.<br />
<br />
This article assumes your are doing a fresh install from the [https://www.archlinux.org/download/ Arch Linux installation media].<br />
<br />
{{Note|This article is an extension of the [[Official Arch Linux Install Guide]]. It asumes you have gained an overview on the general process of installing Arch Linux and will not provide back references to this guide.}}<br />
<br />
{{Note|Arch's default mkinitcpio package contains a standard ''btrfs'' hook, which is enough to get multi-device ([[RAID]]) support. Beside that, the kernel is capable of booting a single-device btrfs root without any hook.}}<br />
<br />
== mkinitcpio-btrfs ==<br />
<br />
First of all you need to decide, if you want to use some of Btrfs's neat features like non-volatile rollback or automatic mounting of degraded Btrfs multi-device ([[RAID]]) volumes. To enable this features you need a special package from the [[Arch User Repository]] called {{AUR|mkinitcpio-btrfs}}. The package integrates some helpers in your boot process, to handle these features correctly.<br />
<br />
This guide can also be followed without this package, through I generally recommend it. The relevant sections contain notes for both types of setup.<br />
<br />
== Prerequisites ==<br />
<br />
Boot up your [https://www.archlinux.org/download/ Arch Linux installation media] and configure your network connection if not done automatically.<br />
<br />
== btrfs-progs ==<br />
<br />
To create a btrfs filesystem you will need to [[pacman|install]] the {{Pkg|btrfs-progs}} from [[Official Repositories]]. This package is normally present on your installation media. It is still a good idea to perform an update, to make sure you have the latest version of it.<br />
<br />
== Partition disks ==<br />
<br />
Partition your drive as you prefer. Both ([[GUID Partition Table|GPT]] and [[Master Boot Record|MBR]]) partition tables are supported. If you want do encrypt your Btrfs, use [[dm-crypt with LUKS|dm-crypt]].<br />
<br />
Btrfs has [https://btrfs.wiki.kernel.org/index.php/UseCases#RAID build-in RAID support]. Setting up at least RAID1 '''is recommended for enabling its internal selfhealing features'''. If you don't have two drives, setup two partitions of the same size on one drive.<br />
<br />
{{Warning|If you want true non-volatile rollback support you '''MUST NOT''' create a separate {{ic|/boot}} partition, as this will prevent rollback of your kernel.}}<br />
<br />
{{Note|Having boot on a different partition in not supported with {{AUR|mkinitcpio-btrfs}} >&#61; 0.4. This is because, kexec is used to reload the kernel from your root partition to make sure it is rolled back too. If you want, you can put it on a subvolume within your {{ic|__active}} subvolume. Btrfs will automatically mount subvolume included in the currently mounted one.}}<br />
<br />
{{Warning|If you need '''Swap''' support create a separate partition for it. '''DO NOT''' simply use a swap file! [http://git.kernel.org/?p&#61;linux/kernel/git/torvalds/linux-2.6.git;a&#61;commit;h&#61;35054394c4b3cecd52577c2662c84da1f3e73525 Doing so will slow down your btrfs filesystem].}}<br />
<br />
== Format the partitions ==<br />
<br />
Use {{ic|mkfs.btrfs}} to create your root partition.<br />
<br />
# mkfs.btrfs -L root -m raid1 -d raid1 /dev/sda1 /dev/sdb1<br />
<br />
== Mount the partitions ==<br />
<br />
Now it is time to mount the new filesystem. First create the mount directory:<br />
<br />
# mount -o defaults,relatime,compress=lzo,ssd,discard /dev/sda1 /mnt<br />
<br />
{{Note|If you are not using an '''SSD drive''', remove {{ic|ssd,discard}} from the mount options.}}<br />
<br />
{{Note|'''Compression''' [http://www.phoronix.com/scan.php?page&#61;article&item&#61;btrfs_compress_2635&num&#61;1 improves performance], since btrfs frequently writes its trees to the disk. The CPU usage needed for that is not worth mentioning. Allowed compression methods are [http://www.phoronix.com/scan.php?page&#61;article&item&#61;btrfs_lzo_2638&num&#61;1 lzo] and gzip.}}<br />
<br />
=== Configure the btrfs filesystem ===<br />
<br />
Clone the btrfs root to an {{ic|__active}} subvolume for your future system root directory {{ic|/}}. This will enable you to take snapshots in a directory outside of your system root and helps keeping a clean filesystem structure.<br />
<br />
# cd /mnt<br />
# btrfs subvolume snapshot . __active<br />
<br />
If you plan on using the rollback features of btrfs, create a {{ic|__snapshot}} directory for containing snapshots.<br />
<br />
# cd /mnt<br />
# mkdir __snapshot<br />
<br />
{{Note|The subvolume and folder names are chosen for integration with current {{AUR|mkinitcpio-btrfs}}. You can also use different subvolume and folder names and specify them in {{ic|/etc/default/btrfs_advanced}} later.}}<br />
<br />
You can create separate subvolumes for important [http://www.pathname.com/fhs/ FHS] directories. This would allow you to monitor and adjust the size allocations for each subvolume using {{ic|btrfs quota}}:<br />
<br />
# cd /mnt/__active<br />
# btrfs subvolume create home<br />
# btrfs subvolume create var<br />
# btrfs subvolume create usr<br />
<br />
To see your handy work:<br />
<br />
{{hc|# btrfs subvolume list -p .|<br />
ID 256 parent 5 top level 5 path __active<br />
ID 258 parent 256 top level 5 path __active/home<br />
ID 259 parent 256 top level 5 path __active/usr<br />
ID 260 parent 256 top level 5 path __active/var<br />
}}<br />
<br />
{{Note|Child subvolumes are automatically mounted by Btrfs when the parent subvolume is mounted. This makes mounting extremely easy at boot time.}}<br />
<br />
Btrfs supports to set a default subvolume, which is mounted if no {{ic|subvol&#61;}} option is provided at mount time. If you plan to use {{AUR|mkinitcpio-btrfs}} later on, you '''MUST''' set this default subvolume to your {{ic|__active}} subvolume.<br />
<br />
{{hc|# btrfs subvolume list .|<br />
ID 256 gen 98 top level 5 path __active}}<br />
<br />
# btrfs subvolume set-default 256 .<br />
<br />
<br />
Now that the subvolumes are created and we have a layout, lets mount the root subvolume directly:<br />
<br />
# cd<br />
# umount /mnt<br />
# mount -o defaults,relatime,compress=lzo,ssd,discard /dev/sda1 /mnt<br />
<br />
{{Note|If you did not set the default subvolume you need to add an additional {{ic|subvol&#61;__active}} mount option.}}<br />
<br />
{{Note|If you are not using an '''SSD drive''', remove {{ic|ssd,discard}} from the mount options.}}<br />
<br />
{{Note|'''Compression''' [http://www.phoronix.com/scan.php?page&#61;article&item&#61;btrfs_compress_2635&num&#61;1 improves performance], since btrfs frequently writes its trees to the disk. The CPU usage needed for that is not worth mentioning. Allowed compression methods are [http://www.phoronix.com/scan.php?page&#61;article&item&#61;btrfs_lzo_2638&num&#61;1 lzo] and gzip.}}<br />
<br />
== Install the base system ==<br />
<br />
Proceed with bootstrap. If you plan to use {{AUR|mkinitcpio-btrfs}}, add its dependencys {{Pkg|btrfs-progs}} and {{Pkg|kexec-tools}}. You'll also need {{Pkg|base-devel}} to build the package from AUR. And add your favorite boot loader to the {{ic|pacstrap}} command too.<br />
<br />
# pacstrap /mnt base base-devel btrfs-progs kexec-tools grub<br />
<br />
If you plan to use {{AUR|mkinitcpio-btrfs}} download its tarball to your chroot environment.<br />
<br />
# wget -O /mnt/root/mkinitcpio-btrfs.tar.gz https://aur.archlinux.org/packages/mk/mkinitcpio-btrfs/mkinitcpio-btrfs.tar.gz<br />
<br />
== Configure the system ==<br />
<br />
Once the you have successfully configured your Arch Linux, it is important that we tweak some settings to get everything working together so when you reboot everything will work correctly.<br />
<br />
Create a place where you mount the Btrfs root subvolume to create snapshots later.<br />
<br />
# mkdir /var/lib/btrfs<br />
<br />
=== /etc/fstab ===<br />
<br />
# nano /mnt/etc/fstab<br />
<br />
Add the following line, supplement {{ic|<uuid>}} for the UUID of the btrfs root partition:<br />
<br />
UUID=<uuid> / btrfs defaults,relatime,compress=lzo,ssd,discard 0 0<br />
UUID=<uuid> /var/lib/btrfs btrfs defaults,relatime,compress=lzo,ssd,discard,subvolid=0 0 0<br />
<br />
{{Note|If you did not set the default subvolume you need to add an additional {{ic|subvol&#61;__active}} mount option.}}<br />
<br />
{{Note|If you are not using an '''SSD drive''', remove {{ic|ssd,discard}} from the mount options.}}<br />
<br />
{{Note|'''Compression''' [http://www.phoronix.com/scan.php?page&#61;article&item&#61;btrfs_compress_2635&num&#61;1 improves performance], since btrfs frequently writes its trees to the disk. The CPU usage needed for that is not worth mentioning. Allowed compression methods are [http://www.phoronix.com/scan.php?page&#61;article&item&#61;btrfs_lzo_2638&num&#61;1 lzo] and gzip.}}<br />
<br />
{{Note|Optional bind an empty folder over the {{ic|/var/lib/btrfs/__active}} folder to prevent apps such as 'find' from complaining of any loops.}}<br />
<br />
/var/lib/btrfs/empty /var/lib/btrfs/__active none bind 0 0<br />
<br />
=== mkinitcpio-btrfs ===<br />
<br />
To install {{AUR|mkinitcpio-btrfs}} you need to extract the AUR package and build it.<br />
<br />
# cd /root<br />
# tar -zxvf mkinitcpio-btrfs.tar.gz<br />
# cd mkinitcpio-btrfs<br />
# makepkg -i --asroot<br />
<br />
After installation, modify {{ic|/etc/default/btrfs_advanced}} to your needs. And don't forget to add {{ic|btrfs-advanced}} to your {{ic|HOOKS}} variable in {{ic|/etc/mkinitcpio.conf}}.<br />
<br />
{{Note|You can savely remove {{ic|fsck}} from your {{ic|HOOKS}} variable, because Btrfs has a online fsck feature, and therefore doesn't provide an fsck module.}}<br />
<br />
Now regenerate your initial RAM-disk.<br />
<br />
# mkinitcpio -p linux<br />
<br />
== Install and configure a bootloader ==<br />
<br />
Now proceed with installing your bootloader.<br />
<br />
=== GRUB ===<br />
<br />
{{Note|To see all your boot messages I recommend to remove the {{ic|silent}} option from {{ic|GRUB_CMDLINE_LINUX_DEFAULT}} in {{ic|/etc/default/grub}}. To prevent tty1 to flush all boot messages before printing the login prompt, edit {{ic|/etc/systemd/system/getty.target.wants/getty@tty1.service}} and change {{ic|TTYVTDisallocate}} to {{ic|no}}.}}<br />
<br />
Grub is able to boot directly from Btrfs root. So just do the usual installation steps.<br />
<br />
{{Note|To have your multi-device Btrfs boot if your first device has failed, add the bootloader to the second device too.}}<br />
<br />
# grub-install --target=i386-pc --recheck /dev/sda<br />
# grub-install --target=i386-pc --recheck /dev/sdb<br />
# cp /usr/share/locale/en\@quot/LC_MESSAGES/grub.mo /boot/grub/locale/en.mo<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
Make sure that your Btrfs root is correctly added to the kernel commandline in {{ic|/boot/grub/grub.cfg}}. Using UUIDs for device identification is especially useful for multi-device ([[RAID]]) setups, because all Btrfs devices own the same UUID.<br />
<br />
root=UUID=fd88d586-bb4c-4fc7-81a6-f675e2829581<br />
<br />
{{Warning|If you've set the default subvolume you '''MUST NOT''' add {{ic|subvol&#61;__active}} to your {{ic|rootflags}}.}}<br />
<br />
{{Note|Having boot on a different partition in not supported with {{AUR|mkinitcpio-btrfs}} >&#61; 0.4. This is because, kexec is used to reload the kernel from your root partition to make sure it is rolled back too. If you want, you can put it on a subvolume within your {{ic|__active}} subvolume. Btrfs will automatically mount subvolume included in the currently mounted one.}}<br />
<br />
=== Syslinux EFI ===<br />
<br />
To boot from Btrfs using syslinux EFI, you need to setup up a dedicated EFI partition in {{ic|/boot/efi}}. This partition needs to be formated as FAT32 (or HPFS on MacBooks). You need to set up your Syslinux directories on that special partition as described in [[Syslinux]].<br />
<br />
{{Warning|The downside of this setup is, that you need to store a working kernel image and its initrd on the EFI partition, because Syslinux can not access Btrfs filesystems directly. {{AUR|mkinitcpio-btrfs}} will then mount your Btrfs root and reload the kernel from your Btrfs {{ic|/boot}} directory.}}<br />
<br />
In {{ic|/boot/efi/EFI/syslinux/syslinux.cfg}} make sure your Btrfs root is correctly added to the {{ic|APPEND}} line.<br />
<br />
APPEND root=UUID=978e3e81-8048-4ae1-8a06-aa727458e8ff rw<br />
<br />
{{Warning|If you've set the default subvolume you '''MUST NOT''' add {{ic|subvol&#61;__active}} to your {{ic|APPEND}} line.}}<br />
<br />
== Usage Hints ==<br />
<br />
To create a snapshot of your root filesystem execute:<br />
<br />
# cd /var/lib/btrfs<br />
# sudo btrfs subvolume snapshot __active __snapshot/[snapshot name]<br />
<br />
Use {{ic|btrfs scrub}} for periodic online filesystem checks:<br />
<br />
# sudo btrfs scrub start /<br />
# sudo btrfs scrub status /<br />
<br />
== Known issues ==<br />
<br />
If you use a multi device ([[RAID]]) setup, make sure you rebalance after system upgrades, to prevent kernel panic on device failure:<br />
<br />
# sudo btrfs balance /</div>Visithttps://wiki.archlinux.org/index.php?title=Talk:Installing_on_Btrfs_root&diff=279653Talk:Installing on Btrfs root2013-10-24T23:56:18Z<p>Visit: Visit moved page Talk:Installing on Btrfs root to Talk:Mkinitcpio-btrfs: As mentioned in discussion page. Updated content will follow.</p>
<hr />
<div>#REDIRECT [[Talk:Mkinitcpio-btrfs]]</div>Visithttps://wiki.archlinux.org/index.php?title=Talk:Mkinitcpio-btrfs&diff=279652Talk:Mkinitcpio-btrfs2013-10-24T23:56:18Z<p>Visit: Visit moved page Talk:Installing on Btrfs root to Talk:Mkinitcpio-btrfs: As mentioned in discussion page. Updated content will follow.</p>
<hr />
<div>== GPT-centric ==<br />
<br />
Why does this article make it seem as if GPT disks are the only option? btrfs is fine on MBR disks. In fact the entire section on GPT partitioning is generic and entirely irrelevant to using btrfs for root. The section should merely point to gpt or mbr partitioning pages.<br />
: Yes, the partition part should be merged out. -- [[User:Fengchao|Fengchao]] ([[User talk:Fengchao|talk]]) 00:44, 11 May 2013 (UTC)<br />
<br />
== Loop method not explained. ==<br />
<br />
The page says...<br />
<br />
"Warning: If you need swap support, either make a partition, or use the loop method detailed below. DO NOT simply use a swap file! Doing so will corrupt your btrfs filesystem."<br />
<br />
However the loop method is not detailed below.<br />
<br />
--[[User:Mex|Mex]] ([[User talk:Mex|talk]]) 15:19, 9 February 2013 (UTC)<br />
<br />
THEN WHY NOT DETAIL IT? [[User:Raininja|Raininja]] ([[User talk:Raininja|talk]]) 14:51, 11 June 2013 (UTC)<br />
<br />
== Deletion ==<br />
<br />
This page needs to be deleted. As of today (April 2013) no additional steps beyond those outlined in [[Installation_Guide|Installation Guide]] are required to install Archlinux on Btrfs (except filesystem creation, ''mkfs.btrfs''). First, all entries regarding bootloader and partitioning are not specific to the Btrfs filesystem and shouldn't be here. Instead, future users should be redirected to their dedicated pages. Second, [[mkinitcpio-btrfs]] should have its own wiki page because it is not in the official repositories and it is not required to be part of the installation process.<br />
[[User:Cngn|Cngn]] ([[User talk:Cngn|talk]]) 11:25, 10 April 2013 (UTC)<br />
<br />
:This topic should be split into different steps:<br />
:#Remove duplication with [[Installation_Guide|Installation Guide]]<br />
:#Merge btrfs partition part into [[Btrfs]]<br />
:#Add links in [[Beginner's Guide]] and [[Btrfs]] to this page.<br />
:#The info left should fit well as name [[mkinitcpio-btrfs]] so we can rename this page to new name. Or maybe [[Btrfs snapshots]] is a better name.<br />
:-- [[User:Fengchao|Fengchao]] ([[User talk:Fengchao|talk]]) 00:40, 11 May 2013 (UTC)<br />
<br />
::I think this page is very useful and there is no reason to delete it. without this page you have to scramble around trying to figure out the correct method. The reasons for including partitioning methods are for clarity, and what is the issue with having clear documentation? [[User:Raininja|Raininja]] ([[User talk:Raininja|talk]]) 14:57, 11 June 2013 (UTC)<br />
<br />
:::Fengchao's plan seems the most reasonable way to save the good content and remove what's duplicated from other articles. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 07:40, 12 June 2013 (UTC)<br />
<br />
== btrfs snapshots ==<br />
As a new archlinux user, 'don't do this' is unhelpful without an alternative set of steps that is suggested instead.<br />
What steps need to occur in order to setup btrfs in the right form for snapshots etc? [[User:Joshka|Joshka]] ([[User talk:Joshka|talk]]) 09:02, 5 May 2013 (UTC)</div>Visithttps://wiki.archlinux.org/index.php?title=Installing_on_Btrfs_root&diff=279651Installing on Btrfs root2013-10-24T23:56:17Z<p>Visit: Visit moved page Installing on Btrfs root to Mkinitcpio-btrfs: As mentioned in discussion page. Updated content will follow.</p>
<hr />
<div>#REDIRECT [[Mkinitcpio-btrfs]]</div>Visithttps://wiki.archlinux.org/index.php?title=Mkinitcpio-btrfs&diff=279650Mkinitcpio-btrfs2013-10-24T23:56:16Z<p>Visit: Visit moved page Installing on Btrfs root to Mkinitcpio-btrfs: As mentioned in discussion page. Updated content will follow.</p>
<hr />
<div>{{deletion|reason=This page needs to be deleted. As of today (April 2013) no additional steps beyond those outlined in [[Installation_Guide]] are required to install Archlinux on Btrfs (except filesystem creation, ''mkfs.btrfs''). First, all entries regarding bootloader and partitioning are not specific to the Btrfs filesystem and shouldn't be here. Instead, future users should be redirected to their dedicated pages. Second, mkinitcpio-btrfs should have its own wiki page because it is not in the official repositories and it is not required to be part of the installation process.}}<br />
[[Category:Getting and installing Arch]]<br />
{{Article summary start}}<br />
{{Article summary text|Installing on btrfs root Outlines a process for installing (or converting) Arch Linux to a btrfs root drive with syslinux or GRUB2.}}<br />
{{Article summary heading|Overview}}<br />
{{Article summary text|{{Boot process overview}}}}<br />
{{Article summary heading|Resources}}<br />
{{Article summary text|[[Wikipedia:Btrfs|Btrfs &mdash; Wikipedia]]}}<br />
{{Article summary link|FAQ &mdash; Btrfs Wiki|https://btrfs.wiki.kernel.org/articles/f/a/q/FAQ_1fe9.html#Is_btrfs_stable.3F}}<br />
{{Article summary link|GNU GRUB &mdash; GNU Project|https://gnu.org/s/grub/}}<br />
{{Article summary link|Syslinux Website|http://www.syslinux.org/wiki/index.php/The_Syslinux_Project}}<br />
{{Article summary text|[[Wikipedia:GUID Partition Table|GUID Partition Table &mdash; Wikipedia]]}}<br />
{{Article summary end}}<br />
<br />
[[btrfs]] provides a number of features (such as checksumming, snapshots, and subvolumes) that make it an excellent candidate for using it as the root partition in an Arch Linux installation. For a tour of btrfs features see [http://www.youtube.com/watch?v=hxWuaozpe2I A tour of btrfs]. As is common with FLOSS, there are a number of ways to configure btrfs as the root filesystem.<br />
<br />
This article assumes your are doing a fresh install from the [https://www.archlinux.org/download/ Arch Linux installation media]. It is also possible to create a backup of an existing Arch Linux installation and restore it to a fresh btrfs configuration. This technique is also shown in this article.<br />
<br />
{{Note|This article is for more advanced Arch Linux users, but if you are a newbie and are one with the command line, you shouldn't have any trouble as long as you are determined.}}<br />
<br />
== btrfs-progs ==<br />
<br />
To create a btrfs filesystem you will need to [[pacman|install]] the {{Pkg|btrfs-progs}} from [[Official Repositories]]. If using [[Archboot]], it's already available.<br />
<br />
== mkinitcpio-btrfs ==<br />
<br />
To get rollback features on your btrfs root device, you will need to install the {{AUR|mkinitcpio-btrfs}} package from the [[Arch User Repository]].<br />
<br />
For reference, here are the internal variables used by {{AUR|mkinitcpio-btrfs}}:<br />
<br />
${BTRFS_HAS_ROLLBACK:=true}<br />
${BTRFS_BOOT_SUBVOL:="__active"}<br />
${BTRFS_DIR_WORK:="/new_root"}<br />
${BTRFS_DIR_SNAP:="/__snapshot"}<br />
${BTRFS_DIR_ACTIVE:="/__active"}<br />
${BTRFS_DIR_ROLLBACK:="/__rollback"}<br />
${BTRFS_ROLLBACK_CHOICE:="default"}<br />
${BTRFS_ROLLBACK_LIST:="default"}<br />
${BTRFS_ROLLBACK_LIST_COUNT:=0}<br />
<br />
{{Note|The ''btrfs_advanced'' mkinitcpio hook (provided by ''mkinitcpio-btrfs'' package) is needed specifically for rollback and possibly other advanced features. The standard ''btrfs'' hook is enough to get multi-device (RAID) support. The kernel is capable of booting a single-device btrfs root on its own.}}<br />
<br />
== Boot into a live image ==<br />
<br />
It is recommended that you boot and install from the latest [https://www.archlinux.org/download/ Archlinux Netinstall Image], or an up-to-date Archlinux installation, or [[Archboot]]. The latter is capable of installing to a btrfs partition natively but does not support the unified setup detailed here; it is however a good option for this procedure because it includes recent builds of all the necessary packages.<br />
<br />
== Preparing the root drive ==<br />
<br />
Now it is time to actually install the btrfs filesystem. Please make sure that {{Pkg|btrfs-progs}} is installed and functioning correctly:<br />
<br />
# btrfs --help<br />
<br />
{{Warning|1=If you need swap support, either make a partition, or use the loop method detailed below. '''DO NOT''' simply use a swap file! [http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=35054394c4b3cecd52577c2662c84da1f3e73525 Doing so will corrupt your btrfs filesystem].}}<br />
<br />
{{Note|It is possible to allow btrfs to use the entire hard drive without using a partitioning scheme, but that is not recommended. [[GRUB2#Install_to_partition_or_partitionless_disk]]. The method used for the syslinux directions in this article does not use a partitioning system. This portion of the article will be updated in the future, but until then you can study the [[GUID Partition Table]] + [[syslinux]] installation method [http://tincman.wordpress.com/2011/01/20/installing-arch-linux-onto-a-gpt-partitioned-btrfs-root-ssd-on-a-legacy-bios-system/ here].}}<br />
<br />
{{Warning| As of January 7,2012, Syslinux does not support multidevice btrfs root!!}}<br />
<br />
{{Note|[[syslinux]] and [[GRUB2]] allow booting from a drive without a separate boot partition. Both syslinux and GRUB2 allow the use of modern GPT partitioning.}}<br />
<br />
=== GPT partitioning for GRUB2 ===<br />
<br />
To get started partitioning, we must [[pacman|install]] the {{Pkg|gptfdisk}} package from the [[Official Repositories]]:<br />
<br />
# pacman -S gptfdisk<br />
<br />
[[GRUB2]] requires a +2M boot partition at the front of the drive [[GRUB2#GPT_specific_instructions]]. You can create that with gdisk:<br />
<br />
# gdisk /dev/sda<br />
<br />
Once gdisk has loaded, you can begin entering commands into the command prompt. Type {{ic|?}} to see the available commands. Press {{ic|o}} to create a new partition table. Just use the help command and create two partitions and<br />
then use {{ic|p}} to verify the output:<br />
<br />
{{bc|<br />
GPT fdisk (gdisk) version 0.8.2<br />
<br />
Partition table scan:<br />
MBR: protective<br />
BSD: not present<br />
APM: not present<br />
GPT: present<br />
<br />
Found valid GPT with protective MBR; using GPT.<br />
<br />
Command (? for help): p<br />
Disk /dev/sda: 234441648 sectors, 111.8 GiB<br />
Logical sector size: 512 bytes<br />
Disk identifier (GUID): C75A01F9-D34E-4895-9AAB-2C8118118211<br />
Partition table holds up to 128 entries<br />
First usable sector is 34, last usable sector is 234441614<br />
Partitions will be aligned on 2048-sector boundaries<br />
Total free space is 2014 sectors (1007.0 KiB)<br />
<br />
Number Start (sector) End (sector) Size Code Name<br />
1 2048 6143 2.0 MiB EF02 BIOS boot partition<br />
2 6144 234441614 111.8 GiB 8300 Linux filesystem<br />
<br />
Command (? for help):<br />
}}<br />
<br />
{{Note|Notice the {{ic|EF02}} hex code for the partition type for the 2Mb GRUB2 boot partition. This is needed to allow GRUB2 to install the {{ic|core.img}} file into that partition for booting}}<br />
<br />
Once you have created the partitions, we will need to set the boot flag on the btrfs partition. Press {{ic|x}} for advanced options and then press {{ic|a}} to set attributes. Press the number for the partition you want to alter, in this<br />
example it is {{ic|2}}. Now press {{ic|2}} to set the legacy boot flag:<br />
<br />
{{bc|<br />
Command (? for help): x<br />
<br />
Expert command (? for help): a<br />
Partition number (1-2): 2<br />
Known attributes are:<br />
0: system partition<br />
1: hide from EFI<br />
2: legacy BIOS bootable<br />
60: read-only<br />
62: hidden<br />
63: do not automount<br />
<br />
Attribute value is 0000000000000000. Set fields are:<br />
No fields set<br />
<br />
Toggle which attribute field (0-63, 64 or <Enter> to exit): 2<br />
Have enabled the 'legacy BIOS bootable' attribute.<br />
Attribute value is 0000000000000004. Set fields are:<br />
2 (legacy BIOS bootable)<br />
<br />
Toggle which attribute field (0-63, 64 or <Enter> to exit):<br />
}}<br />
<br />
Finally, press {{ic|w}} to write the data to the disk.<br />
<br />
=== GPT partitioning for Syslinux ===<br />
<br />
This section hasn't been written yet. For a quick tutorial go [http://tincman.wordpress.com/2011/01/20/installing-arch-linux-onto-a-gpt-partitioned-btrfs-root-ssd-on-a-legacy-bios-system/ here];<br />
<br />
=== Configure the btrfs filesystem ===<br />
<br />
With the drive partitioned and ready for a filesystem, make sure {{Pkg|btrfs-progs}} is installed and create the filesystem on the root partition:<br />
<br />
# mkfs.btrfs -L btrfs-root /dev/sda2<br />
<br />
Now it is time to mount the new filesystem. First create the mount directory:<br />
<br />
# mkdir /mnt/btrfs-root<br />
<br />
and mount the partition:<br />
<br />
# mount -o defaults,noatime,discard,ssd /dev/sda2 /mnt/btrfs-root && cd /mnt/btrfs-root<br />
<br />
{{Note|If you are not using an SSD drive, remove {{ic|discard,ssd}} from the mount options.}}<br />
{{Note|I had performance problems (especially when suspending and halting) on my notebook with SSD. '''Disabling''' the '''discard''' option resolved the problem. [http://wiki.ubuntuusers.de/Btrfs-Mountoptionen#Verbotene-Mountoptionen]}}<br />
<br />
Now you should be in the newly mounted btrfs filesystem! If you plan on using the rollback features of btrfs, create a {{ic|__snapshot}} directory for containing snapshots:<br />
<br />
# mkdir __snapshot<br />
<br />
{{Note|{{ic|__snapshot}} is chosen for integration with current {{AUR|mkinitcpio-btrfs}}. See the variable reference above, or the source mkinitcpio-btrfs package.}}<br />
<br />
If you plan on using [[Syslinux]] as your boot loader, you will need to create a boot directory:<br />
<br />
# mkdir boot<br />
<br />
{{Note|Syslinux currently does not support boot directories within btrfs subvolumes. For this reason a boot directory must be created in the root directory of the btrfs filesystem and bound to a boot directory within the subvolume.}}<br />
<br />
Next we will create the subvolumes. To see all the commands available to manage subvolumes with btrfs:<br />
<br />
# btrfs subvolume --help<br />
<br />
To allow us to easily snapshot the root of our Arch Linux installation, it is recommended it be contained in a subvolume named {{ic|__active}}:<br />
<br />
{{Note|{{ic|__active}} is chosen for integration with current {{AUR|mkinitcpio-btrfs}}. See the variable reference above, or the source mkinitcpio-btrfs package.}}<br />
<br />
# btrfs subvolume create __active && cd __active<br />
<br />
Now we will create separate subvolumes for important [http://www.pathname.com/fhs/ FHS] directories. This would allow us to monitor and adjust the size allocations for each subvolume:<br />
<br />
# btrfs subvolume create home<br />
# btrfs subvolume create var<br />
# btrfs subvolume create usr<br />
<br />
To see your handy work:<br />
<br />
{{hc|# btrfs subvolume list -p .|<br />
ID 256 parent 5 top level 5 path __active<br />
ID 258 parent 256 top level 5 path __active/home<br />
ID 259 parent 256 top level 5 path __active/usr<br />
ID 260 parent 256 top level 5 path __active/var<br />
}}<br />
<br />
Fix the permissions:<br />
<br />
chmod 755 ../\__active var usr home<br />
<br />
Now that the subvolumes are created and we have a layout, lets mount the root subvolume directly:<br />
<br />
# mkdir /mnt/btrfs-active<br />
# mount -o defaults,discard,noatime,ssd,subvol=__active /dev/sda2 /mnt/btrfs-active && cd /mnt/btrfs-active<br />
<br />
{{Note|If you are not using an SSD drive, remove {{ic|discard,ssd}} from the mount options.}}<br />
{{Note|I had performance problems (especially when suspending and halting) on my notebook with SSD. '''Disabling''' the '''discard''' option resolved the problem. [http://wiki.ubuntuusers.de/Btrfs-Mountoptionen#Verbotene-Mountoptionen]}}<br />
<br />
And that's it! You should be ready to install a fresh copy of Arch Linux or restore from a backup. For example, if you made a tar backup with the techniques described above, simply:<br />
<br />
# tar -xvpJf <backup_file> -C .<br />
<br />
or if using rsync:<br />
<br />
# rsync -avhHPS --exclude={dev,sys,proc,mnt,tmp,media} <backup_dir> .<br />
<br />
=== btrfs and syslinux ===<br />
<br />
In order to continue the installation (or restoration), boot in the root of the btrfs filesystem must be bound to the boot directory contained in the {{ic|__active}} subvolume. First we should create a boot directory within the subvolume:<br />
<br />
# mkdir /mnt/btrfs-active/boot<br />
<br />
and then bind the two directories using mount:<br />
<br />
# mount --bind /mnt/btrfs-root/boot /mnt/btrfs-active/boot<br />
<br />
== Installing the base system ==<br />
<br />
{{Accuracy}}<br />
<br />
We will not be relying on AIF to do the install automatically and instead perform it manually.<br />
<br />
{{Note|The AIF is no longer supported. Installing manually is now the official way. See the [[Installation Guide]] for more info}}<br />
<br />
{{Note|You may need to uncomment a mirror from {{ic|/mnt/btrfs-active/etc/pacman.d/mirrorlist}}, and/or make other adjustments to {{ic|/mnt/btrfs-active/etc/pacman.conf}}.}}<br />
<br />
Lets begin by creating the necessary directories:<br />
<br />
# mkdir -p dev proc sys var/lib/pacman<br />
<br />
Now we bind the system directories to our installation directory:<br />
<br />
# mount -o bind /dev dev/<br />
# mount -t proc /proc proc/<br />
# mount -t sysfs /sys sys/<br />
<br />
Install base, btrfs-progs, and a bootloader (grub-bios, grub-efi, syslinux, etc). Switch {{ic|<boot_loader>}} to your preferred boot loader.<br />
<br />
Also install base-devel to build mkinitcpio-btrfs from the AUR.<br />
<br />
# pacman -r . -Sy base btrfs-progs mkinitcpio-btrfs <boot_loader> --ignore grub<br />
<br />
=== Configuration ===<br />
<br />
Once the you have successfully configured btrfs and installed (or recovered) your Arch Linux, it is important that we tweak some settings to get everything working together so when you reboot everything will work correctly.<br />
<br />
=== /etc/fstab ===<br />
<br />
This section has two different configurations depending on the bootloader you selected. We can begin by editing {{ic|/mnt/btrfs-active/etc/fstab}}:<br />
<br />
# nano /mnt/btrfs-active/etc/fstab<br />
<br />
==== GRUB2 ====<br />
<br />
Add the following line, supplement {{ic|<uuid>}} for the UUID of the btrfs root partition:<br />
<br />
UUID=<uuid> / btrfs defaults,noatime,discard,ssd,subvol=__active 0 0<br />
<br />
{{Note|If you are not using an SSD drive, remove {{ic|discard,ssd}} from the mount options.}}<br />
{{Note|I had performance problems (especially when suspending and halting) on my notebook with SSD. '''Disabling''' the '''discard''' option resolved the problem. [http://wiki.ubuntuusers.de/Btrfs-Mountoptionen#Verbotene-Mountoptionen]}}<br />
<br />
==== Syslinux ====<br />
<br />
{{Tip|Locations chosen for integration with upcoming release of mkinitcpio-btrfs}}<br />
<br />
Add everything to {{ic|/mnt/btrfs-active/etc/fstab}} ... {{ic|(btrfs-root)/boot}} will be --bind mounted so kernel upgrades work:<br />
<br />
{{hc|/etc/fstab|2=<br />
/dev/disk/by-label/btrfs-root / btrfs defaults,noatime,subvolid=0 0 0<br />
/dev/disk/by-label/btrfs-root /var/lib/btrfs-root btrfs defaults,noatime 0 0<br />
/var/lib/btrfs-root/boot /boot none bind 0 0<br />
/var/lib/btrfs-root/empty/ /var/lib/btrfs-root/__active none bind 0 0}}<br />
<br />
It is not necessary to add a {{ic|1=subvol=XX}} option for /, as it '''must''' be handled by either the initramfs ''[btrfs_advanced]'' or via the kernel boot line ''[extlinux]'', and it may not be accurate anyways (e.g. rollback mode). {{ic|1=subvolid=0}} corresponds to the btrfs root, and guarantees it will always be mounted correctly, even if the default is changed.<br />
<br />
Optional bind an empty folder over the {{ic|/var/lib/btrfs-root/__active}} folder to prevent apps such as 'find' from complaining of any loops.<br />
<br />
==== mkinitcpio-btrfs ====<br />
<br />
Download the mkinitcpio-btrfs tarball:<br />
<br />
# wget -O /mnt/btrfs-active/root/mkinitcpio-btrfs.tar.gz https://aur.archlinux.org/packages/mk/mkinitcpio-btrfs/mkinitcpio-btrfs.tar.gz<br />
<br />
Add {{ic|btrfs_advanced}} to the {{ic|HOOKS}} section of {{ic|/mnt/btrfs-active/etc/mkinitcpio.conf}}:<br />
<br />
{{hc|# nano /mnt/btrfs-active/etc/mkinitcpio.conf|2=<br />
...<br />
HOOKS="[...] btrfs_advanced"<br />
...}}<br />
<br />
Once you've chroot'ed into the btrfs installation, first install mkinitcpio-btrfs:<br />
<br />
# cd /root<br />
# tar -xvzf mkinitcpio-btrfs.tar.gz<br />
# cd mkinitcpio-btrfs<br />
# makepkg<br />
# pacman -U mkinitcpio-btrfs-${version}.pkg.tar.xz<br />
<br />
Then rebuild the initramfs:<br />
<br />
# mkinitcpio -p linux<br />
<br />
== Installing the bootloader ==<br />
<br />
If everything went smoothly (when does it ever?), you should have the great pleasure of installing your bootloader into the mbr of your root drive.<br />
<br />
=== GRUB ===<br />
<br />
See [[GRUB]] for advanced instructions. Once you have GRUB configured, and you chrooted into your install directory, install the boot loader.<br />
<br />
Chroot:<br />
<br />
If you decided that you liked your current Arch Linux and are restoring from a backup, you will need to chroot into your installation after doing all the necessary steps:<br />
<br />
# cp /etc/resolv.conf etc/<br />
# mount -o bind /dev dev/<br />
# mount -o bind /dev/pts dev/pts<br />
# mount -t proc /proc proc/<br />
# mount -t sysfs /sys sys/<br />
# chroot . /bin/bash<br />
<br />
And now:<br />
<br />
# grub-install --directory=/usr/lib/grub/i386-pc --target=i386-pc --boot-directory=/boot --recheck /dev/sda<br />
<br />
Don't forget to update {{ic|/boot/grub/grub.cfg}}:<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
You should now be able to reboot into GRUB, provided there were no problems encountered doing the steps above.<br />
<br />
=== Syslinux ===<br />
<br />
Syslinux now has an automatic installer that creates the necessary folders, sets bootflags, installs MBR etc. See [[Syslinux#Automatic_Install]] for more info. Make sure you have /mnt bind mounted then run:<br />
<br />
# syslinux-install_update -iam<br />
<br />
Then edit the {{ic|syslinux.cfg}}:<br />
<br />
Sample config:<br />
<br />
{{hc|/boot/syslinux/syslinux.cfg|2=<br />
PROMPT 0<br />
TIMEOUT 0<br />
DEFAULT arch<br />
<br />
LABEL arch<br />
LINUX ../vmlinuz-linux<br />
APPEND root=/dev/disk/by-label/btrfs-root rootflags=subvol=__active ro<br />
INITRD ../initramfs-linux.img}}<br />
<br />
If you '''ARE''' using the mkinitcpio hook, remove {{ic|1=rootflags=subvol=__active}} from the APPEND line.<br />
<br />
== Final configuration ==<br />
<br />
Almost done... be sure to edit {{ic|/mnt/etc/rc.conf}}, set the root password, and similar. Good luck on reboot!<br />
<br />
# reboot<br />
<br />
== Known issues ==<br />
<br />
=== Rollback support ===<br />
<br />
Rollback support, while fully functional, currently has one important caveat... it '''cannot''' handle kernel rollbacks because the kernel is not a part of the snapshot. This is due to the limitations of the bootloader described above. Until bootloaders support subvolumes, you '''must''' remember to manually back up your kernel + initramfs before a snapshot. Upcoming releases of {{AUR|mkinitcpio-btrfs}} will attempt to address this shortcoming.<br />
<br />
=== Syslinux ===<br />
<br />
* Syslinux operates successfully through times, but sometimes fails.<br />
<br />
* Installing syslinux with compression enabled, or editing the configuration file after enabling compression, causes boot to fail because syslinux cannot read compressed files. This probably also affects installing a new kernel with btrfs enabled but I haven't tested this.<br />
<br />
=== Slow meta-data after installation ===<br />
<br />
Do a defragmentation of / after the installation is done to fix the slow metadata issue. (a simple {{ic|ls}} may take seconds)<br />
<br />
# btrfs filesystem defrag /</div>Visit