https://wiki.archlinux.org/api.php?action=feedcontributions&user=Gilmoreja&feedformat=atomArchWiki - User contributions [en]2024-03-29T07:53:47ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Makepkg&diff=358329Makepkg2015-01-27T15:28:25Z<p>Gilmoreja: /* Starting at boot */ -- clarity/context for sake of ToC</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package development]]<br />
[[Category:About Arch]]<br />
[[ar:Makepkg]]<br />
[[el:Makepkg]]<br />
[[es:Makepkg]]<br />
[[fr:makepkg]]<br />
[[it:Makepkg]]<br />
[[ja:Makepkg]]<br />
[[nl:Makepkg]]<br />
[[pt:Makepkg]]<br />
[[ru:makepkg]]<br />
[[sr:Makepkg]]<br />
[[tr:Makepkg]]<br />
[[zh-CN:Makepkg]]<br />
{{Related articles start}}<br />
{{Related|Creating packages}}<br />
{{Related|PKGBUILD}}<br />
{{Related|Arch User Repository}}<br />
{{Related|pacman}}<br />
{{Related|Official repositories}}<br />
{{Related|Arch Build System}}<br />
{{Related articles end}}<br />
<br />
''makepkg'' is used for compiling and building packages suitable for installation with [[pacman]], Arch Linux's package manager. ''makepkg'' is a script that automates the building of packages; it can download and validate source files, check dependencies, configure build-time settings, compile the sources, install into a temporary root, make customizations, generate meta-info, and package everything together.<br />
<br />
''makepkg'' is provided by the {{Pkg|pacman}} package.<br />
<br />
== Configuration ==<br />
{{ic|/etc/makepkg.conf}} is the main configuration file for ''makepkg''. Most users will wish to fine-tune ''makepkg'' configuration options prior to building any packages. You also might create a {{ic|~/.makepkg.conf}} file.<br />
<br />
=== Architecture, compile flags ===<br />
The {{ic|MAKEFLAGS}}, {{ic|CFLAGS}},{{ic|CXXFLAGS}} and {{ic|CPPFLAGS}} options are used by {{Pkg|make}}, {{Pkg|gcc}}, and ''g++'' whilst compiling software with ''makepkg''. By default, these options generate generic packages that can be installed on a wide range of machines. A performance improvement can be achieved by tuning compilation for the host machine. The downside is that packages compiled specifically for the compiling host's processor may not run on other machines.<br />
<br />
{{Note|Do keep in mind that not all package build systems will use your exported variables. Some override them in the original Makefiles or the [[PKGBUILD]]. For example, cmake disregards the preprocessor options environment variable, {{ic|CPPFLAGS}}.}}<br />
<br />
{{hc|/etc/makepkg.conf|<nowiki><br />
[...]<br />
<br />
#########################################################################<br />
# ARCHITECTURE, COMPILE FLAGS<br />
#########################################################################<br />
#<br />
CARCH="x86_64"<br />
CHOST="x86_64-unknown-linux-gnu"<br />
<br />
#-- Exclusive: will only run on x86_64<br />
# -march (or -mcpu) builds exclusively for an architecture<br />
# -mtune optimizes for an architecture, but builds for whole processor family<br />
CPPFLAGS="-D_FORTIFY_SOURCE=2"<br />
CFLAGS="-march=x86-64 -mtune=generic -O2 -pipe -fstack-protector --param=ssp-buffer-size=4"<br />
CXXFLAGS="-march=x86-64 -mtune=generic -O2 -pipe -fstack-protector --param=ssp-buffer-size=4"<br />
LDFLAGS="-Wl,-O1,--sort-common,--as-needed,-z,relro"<br />
#-- Make Flags: change this for DistCC/SMP systems<br />
#MAKEFLAGS="-j2"<br />
<br />
[...]<br />
</nowiki>}}<br />
<br />
The default {{ic|makepkg.conf}} {{ic|CFLAGS}} and {{ic|CXXFLAGS}} are compatible with all machines within their respective architectures. <br />
<br />
On x86_64 machines, there are rarely significant enough real world performance gains that would warrant investing the time to rebuild official packages.<br />
<br />
As of version 4.3.0, GCC offers the {{ic|1=-march=native}} switch that enables CPU auto-detection and automatically selects optimizations supported by the local machine at GCC runtime. To use it, just modify the default settings by changing the {{ic|CFLAGS}} and {{ic|CXXFLAGS}} lines as follows:<br />
<br />
# -march=native also sets the correct -mtune=<br />
CFLAGS="-march=native -O2 -pipe -fstack-protector --param=ssp-buffer-size=4 -D_FORTIFY_SOURCE=2"<br />
CXXFLAGS="${CFLAGS}"<br />
<br />
{{Tip|To see what {{ic|1=march=native}} flags are, run:<br />
<nowiki>$ gcc -march=native -E -v - </dev/null 2>&1 | sed -n 's/.* -v - //p'</nowiki><br />
}}<br />
<br />
Further optimizing for CPU type can theoretically enhance performance because {{ic|1=-march=native}} enables all available instruction sets and improves scheduling for a particular CPU. This is especially noticeable when rebuilding applications (for example: audio/video encoding tools, scientific applications, math-heavy programs, etc.) that can take heavy advantage of newer instructions sets not enabled when using the default options (or packages) provided by Arch Linux. <br />
<br />
It is very easy to reduce performance by using "non-standard" CFLAGS because compilers tend to heavily blow up the code size with loop unrolling, bad vectorization, crazy inlining, etc. depending on compiler switches. Unless you can verify/benchmark that something is faster, there is a very good chance it is not! <br />
<br />
See the GCC man page for a complete list of available options. The Gentoo [http://www.gentoo.org/doc/en/gcc-optimization.xml Compilation Optimization Guide] and [http://wiki.gentoo.org/wiki/Safe_CFLAGS Safe CFLAGS] wiki article provide more in-depth information.<br />
<br />
====MAKEFLAGS====<br />
The {{ic|MAKEFLAGS}} option can be used to specify additional options for make. Users with multi-core/multi-processor systems can specify the number of jobs to run simultaneously. This can be accomplished with the use of ''nproc'' to determine the number of available processors, e.g. {{ic|-j4}} (where "4" is the output of ''nproc''). Some [[PKGBUILD]]'s specifically override this with {{ic|-j1}}, because of race conditions in certain versions or simply because it is not supported in the first place. Packages that fail to build because of this should be [[Reporting Bug Guidelines|reported]] on the bug tracker (or in the case of [[AUR]] packages, to the package maintainer) after making sure that the error is indeed being caused by your {{ic|MAKEFLAGS}}.<br />
<br />
See {{ic|man make}} for a complete list of available options.<br />
<br />
=== Package output ===<br />
Next, one can configure where source files and packages should be placed and identify themselves as the packager. This step is optional; packages will be created in the working directory where ''makepkg'' is run by default.<br />
<br />
{{hc|/etc/makepkg.conf|<nowiki><br />
[...]<br />
<br />
#########################################################################<br />
# PACKAGE OUTPUT<br />
#########################################################################<br />
#<br />
# Default: put built package and cached source in build directory<br />
#<br />
#-- Destination: specify a fixed directory where all packages will be placed<br />
#PKGDEST=/home/packages<br />
#-- Source cache: specify a fixed directory where source files will be cached<br />
#SRCDEST=/home/sources<br />
#-- Source packages: specify a fixed directory where all src packages will be placed<br />
#SRCPKGDEST=/home/srcpackages<br />
#-- Packager: name/email of the person or organization building packages<br />
#PACKAGER="John Doe <john@doe.com>"<br />
<br />
[...]<br />
</nowiki>}}<br />
<br />
For example, create the directory:<br />
<br />
$ mkdir /home/$USER/packages<br />
<br />
Then modify the {{ic|PKGDEST}} variable in {{ic|/etc/makepkg.conf}} accordingly.<br />
<br />
The {{ic|PACKAGER}} variable will set the {{ic|packager}} value within compiled packages' {{ic|.PKGINFO}} metadata file. By default, user-compiled packages will display:<br />
<br />
{{hc|$ pacman -Qi ''package''|<nowiki><br />
[...]<br />
Packager : Unknown Packager<br />
[...]<br />
</nowiki>}}<br />
<br />
Afterwards:<br />
<br />
{{hc|$ pacman -Qi ''package''|<nowiki><br />
[...]<br />
Packager : John Doe <john@doe.com><br />
[...]<br />
</nowiki>}}<br />
<br />
This is useful if multiple users will be compiling packages on a system, or you are otherwise distributing your packages to other users.<br />
<br />
=== Signature checking ===<br />
<br />
{{Expansion|Expand a bit on {{ic|validpgpkeys()}}, e.g: "''I then check the person who signed is expected from the software mailing list, check if they sign emails, look if the PGP fingerprint is published on their homepage, … That verifies the signature enough to add the validpgpkeys array for me.''"}}<br />
<br />
If a signature file in the form of {{ic|.sig}} is part of the [[PKGBUILD]] source array, ''makepkg'' validates the authenticity of source files. For example, the signature {{ic|''pkgname''-''pkgver''.tar.gz.sig}} is used to check the integrity of the file {{ic|''pkgname''-''pkgver''.tar.gz}} with the ''gpg'' program.<br />
<br />
If desired, signatures by other developers can be manually added to the GPG keyring. See [[GnuPG]] article for details. To temporarily disable signature checking, call the ''makepkg'' command with the {{ic|--skippgpcheck}} option.<br />
<br />
{{Note|The signature checking implemented in ''makepkg'' does not use pacman's keyring, relying on the user's keyring and the {{ic|validpgpkeys()}} array instead. [http://allanmcrae.com/2015/01/two-pgp-keyrings-for-package-management-in-arch-linux/]}}<br />
<br />
To show the current list of GPG keys, use the ''gpg'' command:<br />
<br />
$ gpg --list-keys<br />
<br />
If the {{ic|pubring.gpg}} file does not exist, it will be created for you immediately.<br />
<br />
The GPG keys are expected to be stored in the user's {{ic|~/.gnupg/pubring.gpg}} file. In case it does not contain the given signature, ''makepkg'' will abort the installation:<br />
<br />
{{hc|$ makepkg|2=<br />
[...]<br />
==> Verifying source file signatures with gpg...<br />
pkgname-pkgver.tar.gz ... FAILED (unknown public key ''1234567890'')<br />
==> ERROR: One or more PGP signatures could not be verified!<br />
}}<br />
<br />
To import the key, use:<br />
<br />
$ gpg --recv-keys ''1234567890''<br />
<br />
Or to automate:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
keyserver-options auto-key-retrieve<br />
}}<br />
<br />
== Usage ==<br />
<br />
Before continuing, ensure the {{Grp|base-devel}} group is installed. Packages belonging to this group are not required to be listed as build-time (make) dependencies in [[PKGBUILD]] files. Install the {{ic|base-devel}} group by issuing (as root):<br />
<br />
# pacman -S base-devel<br />
<br />
{{Note|Before complaining about missing (make) dependencies, remember that the {{Grp|base}} group is assumed to be installed on all Arch Linux systems. The group "base-devel" is assumed to be installed when building with ''makepkg'' or when using [[AUR helpers]].}}<br />
<br />
To build a package, one must first create a [[PKGBUILD]], or build script, as described in [[Creating packages]], or obtain one from the [[Arch Build System|ABS tree]], [[Arch User Repository]], or some other source. <br />
<br />
{{Warning|Only build and/or install packages from trusted sources.}}<br />
<br />
Once in possession of a {{ic|PKGBUILD}}, change to the directory where it is saved and issue the following command to build the package described by said {{ic|PKGBUILD}}:<br />
<br />
$ makepkg<br />
<br />
''makepkg'' does not support building as root as of v4.2. Besides how a {{ic|PKGBUILD}} may contain arbitrary commands, building as root is generally considered unsafe (see for example [https://bbs.archlinux.org/viewtopic.php?id=67561]).<br />
<br />
To have ''makepkg'' clean out leftover files and folders, such as files extracted to the $srcdir, add the following option. This is useful for multiple builds of the same package or updating the package version, while using the same build folder. It prevents obsolete and remnant files from carrying over to the new builds.<br />
<br />
$ makepkg -c<br />
<br />
If required dependencies are missing, ''makepkg'' will issue a warning before failing. To build the package and install needed dependencies automatically, simply use the command:<br />
<br />
$ makepkg -s<br />
<br />
Note that these dependencies must be available in the configured repositories; see [[pacman#Repositories]] for details. Alternatively, one can manually install dependencies prior to building ({{ic|pacman -S --asdeps dep1 dep2}}).<br />
<br />
Once all dependencies are satisfied and the package builds successfully, a package file ({{ic|''pkgname''-''pkgver''.pkg.tar.xz}}) will be created in the working directory. To install, run (as root):<br />
<br />
# pacman -U ''pkgname''-''pkgver''.pkg.tar.xz<br />
<br />
Alternatively, to install, using the {{ic|-i}} flag is an easier way of running {{ic|pacman -U ''pkgname''-''pkgver''.pkg.tar.xz}}, as in:<br />
<br />
$ makepkg -i<br />
<br />
== Tips and Tricks ==<br />
=== Improving compile times ===<br />
<br />
==== tmpfs ====<br />
<br />
Compiling requires handling of many small files and involves many I/O operations; therefore moving its working directory to a [[tmpfs]] may bring significant improvements in build times. <br />
<br />
The {{ic|BUILDDIR}} value may be exported within a shell to temporarily set ''makepkg'' build directory to an existing tmpfs:<br />
$ BUILDDIR=/tmp/makepkg makepkg<br />
<br />
Relevant option in {{ic|/etc/makepkg.conf}} is to be found at the end of the {{ic|BUILD ENVIRONMENT}} section:<br />
{{hc|/etc/makepkg.conf|<nowiki><br />
[...]<br />
<br />
#########################################################################<br />
# BUILD ENVIRONMENT<br />
#########################################################################<br />
#<br />
# Defaults: BUILDENV=(!distcc color !ccache check !sign)<br />
# A negated environment option will do the opposite of the comments below.<br />
#<br />
#-- distcc: Use the Distributed C/C++/ObjC compiler<br />
#-- color: Colorize output messages<br />
#-- ccache: Use ccache to cache compilation<br />
#-- check: Run the check() function if present in the PKGBUILD<br />
#-- sign: Generate PGP signature file<br />
#<br />
BUILDENV=(!distcc color !ccache check !sign)<br />
#<br />
#-- If using DistCC, your MAKEFLAGS will also need modification. In addition,<br />
#-- specify a space-delimited list of hosts running in the DistCC cluster.<br />
#DISTCC_HOSTS=""<br />
#<br />
#-- Specify a directory for package building.<br />
#BUILDDIR=/tmp/makepkg<br />
<br />
[...]<br />
</nowiki>}}<br />
<br />
Uncommenting the {{ic|1=BUILDDIR=/tmp/makepkg}} line and setting it to e.g. {{ic|1=BUILDDIR=/tmp/builds}} (or leaving it to its default value) will make use of Arch default {{ic|/tmp}} [[tmpfs]].<br />
{{Note|The [[tmpfs]] folder needs to be mounted without the {{ic|noexec}} option, else it will prevent build scripts or utilities from being executed. Also, as stated in [[fstab#tmpfs]], its default size is half of the available RAM so you may run out of space.}}<br />
Please be reminded that any package compiled in [[tmpfs]] will not persist across reboot. Therefore, such packages should be installed consecutively to building or be moved to another (persistent) directory.<br />
<br />
==== ccache ====<br />
<br />
The use of [[ccache]] can improve build times by caching the results of compilations.<br />
<br />
=== Generate new checksums ===<br />
Since [http://allanmcrae.com/2013/04/pacman-4-1-released/ pacman 4.1], {{ic|makepkg -g >> PKGBUILD}} is no longer required because pacman-contrib was [https://projects.archlinux.org/pacman.git/tree/NEWS merged into upstream pacman], including the {{ic|updpkgsums}} script that will generate new checksums and/or replace them in the PKGBUILD. In the same directory as the PKGBUILD file, run the following command:<br />
$ updpkgsums<br />
<br />
=== Makepkg source PKGBUILD twice ===<br />
Makepkg sources the PKGBUILD twice (once when initially run, and the second time under ''fakeroot''). Any non-standard functions placed in the PKGBUILD will be run twice as well.<br />
<br />
=== WARNING: Package contains reference to $srcdir ===<br />
Somehow, the literal strings {{ic|$srcdir}} or {{ic|$pkgdir}} ended up in one of the installed files in your package.<br />
<br />
To identify which files, run the following from the ''makepkg'' build directory:<br />
$ grep -R "$(pwd)/src" pkg/<br />
<br />
[http://www.mail-archive.com/arch-general@archlinux.org/msg15561.html Link] to discussion thread.<br />
<br />
=== Create uncompressed packages ===<br />
If you only want to install packages locally, you can speed up the process by avoiding the [[Wikipedia:xz|LZMA2]] compression and subsequent decompression:<br />
<br />
{{hc|/etc/makepkg.conf|2=<br />
[...]<br />
#PKGEXT='.pkg.tar.xz'<br />
PKGEXT='.pkg.tar'<br />
[...]<br />
}}<br />
<br />
=== Utilizing multiple cores on compression ===<br />
{{pkg|xz}} does support [[Wikipedia:Symmetric multiprocessing|symmetric multiprocessing (SMP)]] on compression. This can be done by adding following changes:<br />
<br />
{{hc|/etc/makepkg.conf|2=<br />
[...]<br />
COMPRESSXZ=(xz -T0 -c -z -)<br />
[...]<br />
}}<br />
<br />
<br />
<br />
=== Using Aria2 to download sources ===<br />
<br />
{{Style|{{ic|DLAGENTS}} is generic, section should not prefer one specific downloader}}<br />
<br />
You can use [[Aria2]] instead of curl to download source files, just change the {{ic|DLAGENTS}} variable as follows:<br />
<br />
{{hc|/etc/makepkg.conf|2=<br />
[...]<br />
DLAGENTS=('ftp::/usr/bin/aria2c -UWget -s4 %u -o %o'<br />
'http::/usr/bin/aria2c -UWget -s4 %u -o %o'<br />
'https::/usr/bin/aria2c -UWget -s4 %u -o %o'<br />
'rsync::/usr/bin/rsync -z %u %o'<br />
'scp::/usr/bin/scp -C %u %o')<br />
[...]<br />
}}<br />
<br />
{{Note|Use the {{ic|-UWget}} option to change the user agent to Wget. It may prevent problems when downloading from sites that filters the requests based on the user agent to provide different responses on what the users uses to access the URL. Since Aria2 is a least known downloader it may be recognized by the site as a browser instead of a downloader, so changing the user agent to Wget may fix it in most cases}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Makepkg sometimes fails to sign a package without asking for signature passphrase ===<br />
This is caused by gpg-agent being invoked inside the fakeroot environment. A way to remedy this is to make sure that gpg-agent is loaded before you run ''makepkg''. You can do this manually, or by starting gpg-agent at boot.<br />
<br />
==== Starting gpg-agent at boot ====<br />
One way of starting gpg-agent at boot is to start it with a systemd user service.<br />
<br />
Create {{ic|~/.config/systemd/user/gpg-agent.service}}:<br />
<br />
[Unit]<br />
Description=GnuPG private key agent<br />
IgnoreOnIsolate=true<br />
<br />
[Service]<br />
Type=forking<br />
ExecStart=/usr/bin/gpg-agent --daemon<br />
ExecStop=/usr/bin/pkill gpg-agent<br />
Restart=on-abort<br />
<br />
[Install]<br />
WantedBy=default.target<br />
<br />
Once you've done that, make sure you enable the service:<br />
<br />
$ systemctl --user enable gpg-agent<br />
<br />
Then reboot your system or start the service manually the first time:<br />
<br />
$ systemctl --user start gpg-agent<br />
<br />
== See also ==<br />
* [https://www.archlinux.org/pacman/makepkg.8.html makepkg(8) Manual Page]<br />
* [https://www.archlinux.org/pacman/makepkg.conf.5.html makepkg.conf(5) Manual Page]<br />
* [https://github.com/pixelb/scripts/blob/master/scripts/gcccpuopt gcccpuopt]: A script to print the GCC CPU-specific options tailored for the current CPU</div>Gilmorejahttps://wiki.archlinux.org/index.php?title=Makepkg&diff=358326Makepkg2015-01-27T15:26:33Z<p>Gilmoreja: Added troubleshooting section, talk about why makepkg can fail to sign a package without even asking password</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package development]]<br />
[[Category:About Arch]]<br />
[[ar:Makepkg]]<br />
[[el:Makepkg]]<br />
[[es:Makepkg]]<br />
[[fr:makepkg]]<br />
[[it:Makepkg]]<br />
[[ja:Makepkg]]<br />
[[nl:Makepkg]]<br />
[[pt:Makepkg]]<br />
[[ru:makepkg]]<br />
[[sr:Makepkg]]<br />
[[tr:Makepkg]]<br />
[[zh-CN:Makepkg]]<br />
{{Related articles start}}<br />
{{Related|Creating packages}}<br />
{{Related|PKGBUILD}}<br />
{{Related|Arch User Repository}}<br />
{{Related|pacman}}<br />
{{Related|Official repositories}}<br />
{{Related|Arch Build System}}<br />
{{Related articles end}}<br />
<br />
''makepkg'' is used for compiling and building packages suitable for installation with [[pacman]], Arch Linux's package manager. ''makepkg'' is a script that automates the building of packages; it can download and validate source files, check dependencies, configure build-time settings, compile the sources, install into a temporary root, make customizations, generate meta-info, and package everything together.<br />
<br />
''makepkg'' is provided by the {{Pkg|pacman}} package.<br />
<br />
== Configuration ==<br />
{{ic|/etc/makepkg.conf}} is the main configuration file for ''makepkg''. Most users will wish to fine-tune ''makepkg'' configuration options prior to building any packages. You also might create a {{ic|~/.makepkg.conf}} file.<br />
<br />
=== Architecture, compile flags ===<br />
The {{ic|MAKEFLAGS}}, {{ic|CFLAGS}},{{ic|CXXFLAGS}} and {{ic|CPPFLAGS}} options are used by {{Pkg|make}}, {{Pkg|gcc}}, and ''g++'' whilst compiling software with ''makepkg''. By default, these options generate generic packages that can be installed on a wide range of machines. A performance improvement can be achieved by tuning compilation for the host machine. The downside is that packages compiled specifically for the compiling host's processor may not run on other machines.<br />
<br />
{{Note|Do keep in mind that not all package build systems will use your exported variables. Some override them in the original Makefiles or the [[PKGBUILD]]. For example, cmake disregards the preprocessor options environment variable, {{ic|CPPFLAGS}}.}}<br />
<br />
{{hc|/etc/makepkg.conf|<nowiki><br />
[...]<br />
<br />
#########################################################################<br />
# ARCHITECTURE, COMPILE FLAGS<br />
#########################################################################<br />
#<br />
CARCH="x86_64"<br />
CHOST="x86_64-unknown-linux-gnu"<br />
<br />
#-- Exclusive: will only run on x86_64<br />
# -march (or -mcpu) builds exclusively for an architecture<br />
# -mtune optimizes for an architecture, but builds for whole processor family<br />
CPPFLAGS="-D_FORTIFY_SOURCE=2"<br />
CFLAGS="-march=x86-64 -mtune=generic -O2 -pipe -fstack-protector --param=ssp-buffer-size=4"<br />
CXXFLAGS="-march=x86-64 -mtune=generic -O2 -pipe -fstack-protector --param=ssp-buffer-size=4"<br />
LDFLAGS="-Wl,-O1,--sort-common,--as-needed,-z,relro"<br />
#-- Make Flags: change this for DistCC/SMP systems<br />
#MAKEFLAGS="-j2"<br />
<br />
[...]<br />
</nowiki>}}<br />
<br />
The default {{ic|makepkg.conf}} {{ic|CFLAGS}} and {{ic|CXXFLAGS}} are compatible with all machines within their respective architectures. <br />
<br />
On x86_64 machines, there are rarely significant enough real world performance gains that would warrant investing the time to rebuild official packages.<br />
<br />
As of version 4.3.0, GCC offers the {{ic|1=-march=native}} switch that enables CPU auto-detection and automatically selects optimizations supported by the local machine at GCC runtime. To use it, just modify the default settings by changing the {{ic|CFLAGS}} and {{ic|CXXFLAGS}} lines as follows:<br />
<br />
# -march=native also sets the correct -mtune=<br />
CFLAGS="-march=native -O2 -pipe -fstack-protector --param=ssp-buffer-size=4 -D_FORTIFY_SOURCE=2"<br />
CXXFLAGS="${CFLAGS}"<br />
<br />
{{Tip|To see what {{ic|1=march=native}} flags are, run:<br />
<nowiki>$ gcc -march=native -E -v - </dev/null 2>&1 | sed -n 's/.* -v - //p'</nowiki><br />
}}<br />
<br />
Further optimizing for CPU type can theoretically enhance performance because {{ic|1=-march=native}} enables all available instruction sets and improves scheduling for a particular CPU. This is especially noticeable when rebuilding applications (for example: audio/video encoding tools, scientific applications, math-heavy programs, etc.) that can take heavy advantage of newer instructions sets not enabled when using the default options (or packages) provided by Arch Linux. <br />
<br />
It is very easy to reduce performance by using "non-standard" CFLAGS because compilers tend to heavily blow up the code size with loop unrolling, bad vectorization, crazy inlining, etc. depending on compiler switches. Unless you can verify/benchmark that something is faster, there is a very good chance it is not! <br />
<br />
See the GCC man page for a complete list of available options. The Gentoo [http://www.gentoo.org/doc/en/gcc-optimization.xml Compilation Optimization Guide] and [http://wiki.gentoo.org/wiki/Safe_CFLAGS Safe CFLAGS] wiki article provide more in-depth information.<br />
<br />
====MAKEFLAGS====<br />
The {{ic|MAKEFLAGS}} option can be used to specify additional options for make. Users with multi-core/multi-processor systems can specify the number of jobs to run simultaneously. This can be accomplished with the use of ''nproc'' to determine the number of available processors, e.g. {{ic|-j4}} (where "4" is the output of ''nproc''). Some [[PKGBUILD]]'s specifically override this with {{ic|-j1}}, because of race conditions in certain versions or simply because it is not supported in the first place. Packages that fail to build because of this should be [[Reporting Bug Guidelines|reported]] on the bug tracker (or in the case of [[AUR]] packages, to the package maintainer) after making sure that the error is indeed being caused by your {{ic|MAKEFLAGS}}.<br />
<br />
See {{ic|man make}} for a complete list of available options.<br />
<br />
=== Package output ===<br />
Next, one can configure where source files and packages should be placed and identify themselves as the packager. This step is optional; packages will be created in the working directory where ''makepkg'' is run by default.<br />
<br />
{{hc|/etc/makepkg.conf|<nowiki><br />
[...]<br />
<br />
#########################################################################<br />
# PACKAGE OUTPUT<br />
#########################################################################<br />
#<br />
# Default: put built package and cached source in build directory<br />
#<br />
#-- Destination: specify a fixed directory where all packages will be placed<br />
#PKGDEST=/home/packages<br />
#-- Source cache: specify a fixed directory where source files will be cached<br />
#SRCDEST=/home/sources<br />
#-- Source packages: specify a fixed directory where all src packages will be placed<br />
#SRCPKGDEST=/home/srcpackages<br />
#-- Packager: name/email of the person or organization building packages<br />
#PACKAGER="John Doe <john@doe.com>"<br />
<br />
[...]<br />
</nowiki>}}<br />
<br />
For example, create the directory:<br />
<br />
$ mkdir /home/$USER/packages<br />
<br />
Then modify the {{ic|PKGDEST}} variable in {{ic|/etc/makepkg.conf}} accordingly.<br />
<br />
The {{ic|PACKAGER}} variable will set the {{ic|packager}} value within compiled packages' {{ic|.PKGINFO}} metadata file. By default, user-compiled packages will display:<br />
<br />
{{hc|$ pacman -Qi ''package''|<nowiki><br />
[...]<br />
Packager : Unknown Packager<br />
[...]<br />
</nowiki>}}<br />
<br />
Afterwards:<br />
<br />
{{hc|$ pacman -Qi ''package''|<nowiki><br />
[...]<br />
Packager : John Doe <john@doe.com><br />
[...]<br />
</nowiki>}}<br />
<br />
This is useful if multiple users will be compiling packages on a system, or you are otherwise distributing your packages to other users.<br />
<br />
=== Signature checking ===<br />
<br />
{{Expansion|Expand a bit on {{ic|validpgpkeys()}}, e.g: "''I then check the person who signed is expected from the software mailing list, check if they sign emails, look if the PGP fingerprint is published on their homepage, … That verifies the signature enough to add the validpgpkeys array for me.''"}}<br />
<br />
If a signature file in the form of {{ic|.sig}} is part of the [[PKGBUILD]] source array, ''makepkg'' validates the authenticity of source files. For example, the signature {{ic|''pkgname''-''pkgver''.tar.gz.sig}} is used to check the integrity of the file {{ic|''pkgname''-''pkgver''.tar.gz}} with the ''gpg'' program.<br />
<br />
If desired, signatures by other developers can be manually added to the GPG keyring. See [[GnuPG]] article for details. To temporarily disable signature checking, call the ''makepkg'' command with the {{ic|--skippgpcheck}} option.<br />
<br />
{{Note|The signature checking implemented in ''makepkg'' does not use pacman's keyring, relying on the user's keyring and the {{ic|validpgpkeys()}} array instead. [http://allanmcrae.com/2015/01/two-pgp-keyrings-for-package-management-in-arch-linux/]}}<br />
<br />
To show the current list of GPG keys, use the ''gpg'' command:<br />
<br />
$ gpg --list-keys<br />
<br />
If the {{ic|pubring.gpg}} file does not exist, it will be created for you immediately.<br />
<br />
The GPG keys are expected to be stored in the user's {{ic|~/.gnupg/pubring.gpg}} file. In case it does not contain the given signature, ''makepkg'' will abort the installation:<br />
<br />
{{hc|$ makepkg|2=<br />
[...]<br />
==> Verifying source file signatures with gpg...<br />
pkgname-pkgver.tar.gz ... FAILED (unknown public key ''1234567890'')<br />
==> ERROR: One or more PGP signatures could not be verified!<br />
}}<br />
<br />
To import the key, use:<br />
<br />
$ gpg --recv-keys ''1234567890''<br />
<br />
Or to automate:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
keyserver-options auto-key-retrieve<br />
}}<br />
<br />
== Usage ==<br />
<br />
Before continuing, ensure the {{Grp|base-devel}} group is installed. Packages belonging to this group are not required to be listed as build-time (make) dependencies in [[PKGBUILD]] files. Install the {{ic|base-devel}} group by issuing (as root):<br />
<br />
# pacman -S base-devel<br />
<br />
{{Note|Before complaining about missing (make) dependencies, remember that the {{Grp|base}} group is assumed to be installed on all Arch Linux systems. The group "base-devel" is assumed to be installed when building with ''makepkg'' or when using [[AUR helpers]].}}<br />
<br />
To build a package, one must first create a [[PKGBUILD]], or build script, as described in [[Creating packages]], or obtain one from the [[Arch Build System|ABS tree]], [[Arch User Repository]], or some other source. <br />
<br />
{{Warning|Only build and/or install packages from trusted sources.}}<br />
<br />
Once in possession of a {{ic|PKGBUILD}}, change to the directory where it is saved and issue the following command to build the package described by said {{ic|PKGBUILD}}:<br />
<br />
$ makepkg<br />
<br />
''makepkg'' does not support building as root as of v4.2. Besides how a {{ic|PKGBUILD}} may contain arbitrary commands, building as root is generally considered unsafe (see for example [https://bbs.archlinux.org/viewtopic.php?id=67561]).<br />
<br />
To have ''makepkg'' clean out leftover files and folders, such as files extracted to the $srcdir, add the following option. This is useful for multiple builds of the same package or updating the package version, while using the same build folder. It prevents obsolete and remnant files from carrying over to the new builds.<br />
<br />
$ makepkg -c<br />
<br />
If required dependencies are missing, ''makepkg'' will issue a warning before failing. To build the package and install needed dependencies automatically, simply use the command:<br />
<br />
$ makepkg -s<br />
<br />
Note that these dependencies must be available in the configured repositories; see [[pacman#Repositories]] for details. Alternatively, one can manually install dependencies prior to building ({{ic|pacman -S --asdeps dep1 dep2}}).<br />
<br />
Once all dependencies are satisfied and the package builds successfully, a package file ({{ic|''pkgname''-''pkgver''.pkg.tar.xz}}) will be created in the working directory. To install, run (as root):<br />
<br />
# pacman -U ''pkgname''-''pkgver''.pkg.tar.xz<br />
<br />
Alternatively, to install, using the {{ic|-i}} flag is an easier way of running {{ic|pacman -U ''pkgname''-''pkgver''.pkg.tar.xz}}, as in:<br />
<br />
$ makepkg -i<br />
<br />
== Tips and Tricks ==<br />
=== Improving compile times ===<br />
<br />
==== tmpfs ====<br />
<br />
Compiling requires handling of many small files and involves many I/O operations; therefore moving its working directory to a [[tmpfs]] may bring significant improvements in build times. <br />
<br />
The {{ic|BUILDDIR}} value may be exported within a shell to temporarily set ''makepkg'' build directory to an existing tmpfs:<br />
$ BUILDDIR=/tmp/makepkg makepkg<br />
<br />
Relevant option in {{ic|/etc/makepkg.conf}} is to be found at the end of the {{ic|BUILD ENVIRONMENT}} section:<br />
{{hc|/etc/makepkg.conf|<nowiki><br />
[...]<br />
<br />
#########################################################################<br />
# BUILD ENVIRONMENT<br />
#########################################################################<br />
#<br />
# Defaults: BUILDENV=(!distcc color !ccache check !sign)<br />
# A negated environment option will do the opposite of the comments below.<br />
#<br />
#-- distcc: Use the Distributed C/C++/ObjC compiler<br />
#-- color: Colorize output messages<br />
#-- ccache: Use ccache to cache compilation<br />
#-- check: Run the check() function if present in the PKGBUILD<br />
#-- sign: Generate PGP signature file<br />
#<br />
BUILDENV=(!distcc color !ccache check !sign)<br />
#<br />
#-- If using DistCC, your MAKEFLAGS will also need modification. In addition,<br />
#-- specify a space-delimited list of hosts running in the DistCC cluster.<br />
#DISTCC_HOSTS=""<br />
#<br />
#-- Specify a directory for package building.<br />
#BUILDDIR=/tmp/makepkg<br />
<br />
[...]<br />
</nowiki>}}<br />
<br />
Uncommenting the {{ic|1=BUILDDIR=/tmp/makepkg}} line and setting it to e.g. {{ic|1=BUILDDIR=/tmp/builds}} (or leaving it to its default value) will make use of Arch default {{ic|/tmp}} [[tmpfs]].<br />
{{Note|The [[tmpfs]] folder needs to be mounted without the {{ic|noexec}} option, else it will prevent build scripts or utilities from being executed. Also, as stated in [[fstab#tmpfs]], its default size is half of the available RAM so you may run out of space.}}<br />
Please be reminded that any package compiled in [[tmpfs]] will not persist across reboot. Therefore, such packages should be installed consecutively to building or be moved to another (persistent) directory.<br />
<br />
==== ccache ====<br />
<br />
The use of [[ccache]] can improve build times by caching the results of compilations.<br />
<br />
=== Generate new checksums ===<br />
Since [http://allanmcrae.com/2013/04/pacman-4-1-released/ pacman 4.1], {{ic|makepkg -g >> PKGBUILD}} is no longer required because pacman-contrib was [https://projects.archlinux.org/pacman.git/tree/NEWS merged into upstream pacman], including the {{ic|updpkgsums}} script that will generate new checksums and/or replace them in the PKGBUILD. In the same directory as the PKGBUILD file, run the following command:<br />
$ updpkgsums<br />
<br />
=== Makepkg source PKGBUILD twice ===<br />
Makepkg sources the PKGBUILD twice (once when initially run, and the second time under ''fakeroot''). Any non-standard functions placed in the PKGBUILD will be run twice as well.<br />
<br />
=== WARNING: Package contains reference to $srcdir ===<br />
Somehow, the literal strings {{ic|$srcdir}} or {{ic|$pkgdir}} ended up in one of the installed files in your package.<br />
<br />
To identify which files, run the following from the ''makepkg'' build directory:<br />
$ grep -R "$(pwd)/src" pkg/<br />
<br />
[http://www.mail-archive.com/arch-general@archlinux.org/msg15561.html Link] to discussion thread.<br />
<br />
=== Create uncompressed packages ===<br />
If you only want to install packages locally, you can speed up the process by avoiding the [[Wikipedia:xz|LZMA2]] compression and subsequent decompression:<br />
<br />
{{hc|/etc/makepkg.conf|2=<br />
[...]<br />
#PKGEXT='.pkg.tar.xz'<br />
PKGEXT='.pkg.tar'<br />
[...]<br />
}}<br />
<br />
=== Utilizing multiple cores on compression ===<br />
{{pkg|xz}} does support [[Wikipedia:Symmetric multiprocessing|symmetric multiprocessing (SMP)]] on compression. This can be done by adding following changes:<br />
<br />
{{hc|/etc/makepkg.conf|2=<br />
[...]<br />
COMPRESSXZ=(xz -T0 -c -z -)<br />
[...]<br />
}}<br />
<br />
<br />
<br />
=== Using Aria2 to download sources ===<br />
<br />
{{Style|{{ic|DLAGENTS}} is generic, section should not prefer one specific downloader}}<br />
<br />
You can use [[Aria2]] instead of curl to download source files, just change the {{ic|DLAGENTS}} variable as follows:<br />
<br />
{{hc|/etc/makepkg.conf|2=<br />
[...]<br />
DLAGENTS=('ftp::/usr/bin/aria2c -UWget -s4 %u -o %o'<br />
'http::/usr/bin/aria2c -UWget -s4 %u -o %o'<br />
'https::/usr/bin/aria2c -UWget -s4 %u -o %o'<br />
'rsync::/usr/bin/rsync -z %u %o'<br />
'scp::/usr/bin/scp -C %u %o')<br />
[...]<br />
}}<br />
<br />
{{Note|Use the {{ic|-UWget}} option to change the user agent to Wget. It may prevent problems when downloading from sites that filters the requests based on the user agent to provide different responses on what the users uses to access the URL. Since Aria2 is a least known downloader it may be recognized by the site as a browser instead of a downloader, so changing the user agent to Wget may fix it in most cases}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Makepkg sometimes fails to sign a package without asking for signature passphrase ===<br />
This is caused by gpg-agent being invoked inside the fakeroot environment. A way to remedy this is to make sure that gpg-agent is loaded before you run ''makepkg''. You can do this manually, or by starting gpg-agent at boot.<br />
<br />
==== Starting at boot ====<br />
One way of starting gpg-agent at boot is to start it with a systemd user service.<br />
<br />
Create {{ic|~/.config/systemd/user/gpg-agent.service}}:<br />
<br />
[Unit]<br />
Description=GnuPG private key agent<br />
IgnoreOnIsolate=true<br />
<br />
[Service]<br />
Type=forking<br />
ExecStart=/usr/bin/gpg-agent --daemon<br />
ExecStop=/usr/bin/pkill gpg-agent<br />
Restart=on-abort<br />
<br />
[Install]<br />
WantedBy=default.target<br />
<br />
Once you've done that, make sure you enable the service:<br />
<br />
$ systemctl --user enable gpg-agent<br />
<br />
Then reboot your system or start the service manually the first time:<br />
<br />
$ systemctl --user start gpg-agent<br />
<br />
<br />
== See also ==<br />
* [https://www.archlinux.org/pacman/makepkg.8.html makepkg(8) Manual Page]<br />
* [https://www.archlinux.org/pacman/makepkg.conf.5.html makepkg.conf(5) Manual Page]<br />
* [https://github.com/pixelb/scripts/blob/master/scripts/gcccpuopt gcccpuopt]: A script to print the GCC CPU-specific options tailored for the current CPU</div>Gilmorejahttps://wiki.archlinux.org/index.php?title=User:Gilmoreja&diff=354949User:Gilmoreja2015-01-02T14:29:41Z<p>Gilmoreja: short bio</p>
<hr />
<div>I have been an Arch Linux user since 2010.<br />
<br />
I love the Linux environment because of the complete control and customization you have over all aspects of your system. I love Arch Linux because it allows the user to take that level of customization to the next level right from installation.</div>Gilmorejahttps://wiki.archlinux.org/index.php?title=User:Gilmoreja/Sig0&diff=354944User:Gilmoreja/Sig02015-01-02T14:14:39Z<p>Gilmoreja: creating a signature</p>
<hr />
<div><span style="line-height: 100%; font-size:small;"><span style="color: #888888">'''—'''</span>&nbsp;'''[[User:Gilmoreja|<span title="—You've got to start what you finish—"><span style="color: #66CC99">g</span><span style="color:#6699FF">ilmore</span><span style="color: #66CC99">ja</span></span>]]'''<span style="position:relative; bottom: +2px;">[[User:Gilmoreja|<span title="—You've got to start what you finish—" style="color: #888888"> ★ </span>]]</span><span style="border-top: 1px solid #888888; border-bottom: 1px solid #888888">[[User talk:Gilmoreja|<span title="Drop me a line!"><sup><span style="color: #66CC99">T</span><span style="color: #6699FF">alk!</span></sup></span>]]<span style="color: #888888">≒</span>[[Special:Contributions/Gilmoreja|<span title="My edits"><sub><span style="color: #66CC99">∁</span><span style="color:#6699FF">on!</span></sub></span>]]</span></div>Gilmorejahttps://wiki.archlinux.org/index.php?title=User:Gilmoreja/Signed&diff=354941User:Gilmoreja/Signed2015-01-02T13:28:12Z<p>Gilmoreja: creating a signature</p>
<hr />
<div>{{User:Gilmoreja/Sig0}}</div>Gilmorejahttps://wiki.archlinux.org/index.php?title=Systemd&diff=220792Systemd2012-08-31T18:10:47Z<p>Gilmoreja: /* FAQ */ added QA about dmraid.service</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Daemons and system services]]<br />
[[Category:Boot process]]<br />
[[es:Systemd]]<br />
[[fr:Systemd]]<br />
[[it:Systemd]]<br />
[[ru:Systemd]]<br />
[[zh-CN: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/Services}}<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]], supports snapshotting and restoring of the system state, maintains mount and automount points and implements an elaborate transactional dependency-based service control logic. It can work as a drop-in replacement for sysvinit."''<br />
<br />
{{Note|For a detailed explanation as to why Arch is switching to systemd, see: [https://bbs.archlinux.org/viewtopic.php?pid&#61;1149530#p1149530 this forum post].}}<br />
<br />
See also the [http://en.wikipedia.org/wiki/Systemd Wikipedia article].<br />
<br />
== Things to consider before you switch ==<br />
<br />
* It is highly recommended to switch to the new '''initscripts''' configuration system described in the [[rc.conf|rc.conf article]]. Once you have this configuration established, you will have done most of the work needed to make the switch to systemd.<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 the [[#Journald_in_conjunction_with_a_classic_syslog_daemon|section on the journal]] below.<br />
* Do not worry about systemd's plans to replace the functionality of '''cron''', '''acpid''', or '''xinetd'''. These are not things you need to worry about just yet. For now, you can continue to use your traditional daemons for these tasks.<br />
<br />
== Installation ==<br />
Systemd can be installed side-by-side with the regular Arch Linux initscripts, and they can be toggled by adding/removing the {{Ic|1=init=/bin/systemd}} [[kernel parameters]].<br />
<br />
=== A pure systemd installation ===<br />
<br />
# Install {{Pkg|systemd}} from [core].<br />
# The {{Pkg|systemd-arch-units}} package has some extra systemd unit files (services) which you may find useful.<br />
# Add {{ic|1=init=/bin/systemd}} to the [[Kernel parameters|kernel parameters]] in your bootloader.<br />
# Create [[#Native systemd configuration files|systemd configuration files]].<br />
# Reboot and install {{Pkg|systemd-sysvcompat}}. Now you can remove the kernel parameters from step 3 if you like.<br />
# [[#Using_Units|Enable services]] with {{ic|systemctl enable ...}}. Services replace the daemons from rc.conf.<br />
# If you miss {{ic|pidof}} or {{ic|sulogin}}, install [https://aur.archlinux.org/packages.php?ID=60061 systemd-sysvinit] from AUR.<br />
<br />
=== A mixed systemd installation ===<br />
<br />
# Install {{Pkg|systemd}} from [core]<br />
# Add {{ic|1=init=/bin/systemd}} to the [[Kernel parameters|kernel parameters]] in your bootloader.<br />
# We recommend that you use [[#Native systemd configuration files|native systemd configuration files]] instead of Arch's classic configuration files. You can still use {{ic|/etc/rc.conf}} to configure a few variables if the native configuration files do not exist, but support will be dropped in the future.<br />
# The {{Pkg|systemd-arch-units}} package has some extra systemd unit files (services) which you may find useful, notably for network configuration.<br />
# If you want to keep using syslog log files alongside the systemd journal, follow the instructions described in the [[#Journald_in_conjunction_with_a_classic_syslog_daemon|section on the journal]], below.<br />
<br />
=== Supplementary information ===<br />
{{Note|1=In a pure systemd installation, installing {{pkg|systemd-sysvcompat}} removes {{pkg|initscripts}} and {{pkg|sysvinit}}, permits the export of LANG in /etc/locale.conf, and creates symlinks to halt, reboot, etc. But you can manually remove {{pkg|initscripts}} and {{pkg|sysvinit}} as [https://bbs.archlinux.org/viewtopic.php?id=148042 here] appoints}}<br />
{{Tip|Purely filesystem-based commands (like {{ic|list-unit-files}}, {{ic|enable}}, {{ic|mask}}, etc) should work immediately after installation. However, multiple people have reported needing to reboot with systemd before even these commands begin working.}}<br />
{{Tip|If you have {{ic|quiet}} in your kernel parameters, you should remove it for your first couple of systemd boots, to assist with identifying any issues during boot.}}<br />
{{Warning|{{ic|/usr}} must be mounted and available at bootup (this is not particular to systemd). If your {{ic|/usr}} is on a separate partition, you will need to make accommodations to mount it from the initramfs and unmount it from a pivoted root on shutdown. See [[Mkinitcpio#/usr_as_a_separate_partition|the mkinitcpio wiki page]] and [http://www.freedesktop.org/wiki/Software/systemd/separate-usr-is-broken freedesktop.org#separate-usr-is-broken]}}<br />
<br />
== Native systemd configuration files ==<br />
{{Pkg|systemd}} will use {{ic|/etc/rc.conf}} if these files are absent (Note this is temporary and not a long-term solution. It is strongly advised to use the systemd configuration files on any system, since initscripts can use them).<br />
{{Note|You may need to create these files.}}<br />
=== Hostname ===<br />
{{hc|/etc/hostname|myhostname}}<br />
<br />
=== Console and keymap ===<br />
The {{ic|/etc/vconsole.conf}} file configures the virtual console, i.e. keyboard mapping and console font.<br />
{{hc|/etc/vconsole.conf|<nowiki><br />
KEYMAP=us<br />
FONT=lat9w-16<br />
FONT_MAP=8859-1_to_uni</nowiki>}}<br />
<br />
For more info see: [[Fonts#Console_fonts|Console fonts]]<br />
<br />
=== Locale ===<br />
Read {{ic|man locale.conf}} for more options <br />
{{hc|/etc/locale.conf|<nowiki><br />
LANG=en_US.UTF-8<br />
LC_COLLATE=C</nowiki>}}<br />
{{Note| {{Ic|1=/etc/profile.d/locale.sh}} from {{Pkg|systemd-sysvcompat}} or {{Pkg|initscripts}} is necessary to be able to set users' locale correctly}}<br />
<br />
=== Timezone ===<br />
Read {{ic|man 5 timezone}} for more options <br />
{{hc|/etc/timezone|Europe/Minsk}}<br />
{{Note|This file does not obviate the need for {{ic|/etc/localtime}}.}}<br />
<br />
=== Hardware clock time ===<br />
Systemd will use UTC for the hardware clock by default and this is recommended. Dealing with daylight saving time is messy. If the DST changes when your computer is off, your clock will be wrong on next boot ([http://www.cl.cam.ac.uk/~mgk25/mswish/ut-rtc.html there is a lot more to it]). Recent kernels set the system time from the RTC directly on boot without using {{ic|hwclock}}, the kernel will always assume that the RTC is in UTC. This means that if the RTC is in local time, the the system time will first be set up wrongly and then corrected shortly afterwards on every boot. This is possibly the reason for certain weird bugs (time going backwards is rarely a good thing).<br />
<br />
The reason for allowing the RTC to be in local time is to allow dual boot with Windows ([http://blogs.msdn.com/b/oldnewthing/archive/2004/09/02/224672.aspx who uses localtime]). Windows is able to deal with the RTC being in UTC by setting the following DWORD registry key to {{ic|1}}:<br />
{{bc|HKLM\SYSTEM\CurrentControlSet\Control\TimeZoneInformation\RealTimeIsUniversal}}<br />
<br />
{{Warning|On recent systems (Windows 7, Vista SP2) this setting prevents Windows from being able to update the system clock at all, and earlier versions do not work correctly when [http://social.msdn.microsoft.com/forums/en-US/tabletandtouch/thread/0b872d8a-69e9-40a6-a71f-45de90c6e243/ resuming from suspend or hibernate]. In addition, recent systems [http://support.microsoft.com/kb/2687252 may become unresponsive during Daylight Saving Time (DST) changeover] if RealTimeIsUniversal is set.}}<br />
<br />
If you run into issues on dual boot with Windows, you can set the hardware clock to local time. Contrary to popular belief, systemd supports this:<br />
{{hc|/etc/adjtime|<nowiki> <br />
0.0 0.0 0.0<br />
0<br />
LOCAL</nowiki>}}<br />
{{Note|The other parameters are still needed but are ignored by systemd.}}<br />
{{Note|It is generally advised to have a [[NTP|Network Time Protocol daemon]] running to keep the hardware clock synchronized with the system time.}}<br />
<br />
=== Kernel modules loaded during boot ===<br />
systemd uses {{ic|/etc/modules-load.d/}} to configure kernel modules to load during boot in a static list. Each configuration file is named in the style of {{ic|/etc/modules-load.d/<program>.conf}}. The configuration files should simply contain a list of kernel module names to load, separated by newlines. Empty lines and lines whose first non-whitespace character is {{ic|#}} or {{ic|;}} are ignored. Example:<br />
{{hc|/etc/modules-load.d/virtio-net.conf|<nowiki><br />
# Load virtio-net.ko at boot<br />
virtio-net</nowiki>}}<br />
See also [[Modprobe#Options]]<br />
<br />
=== Kernel modules blacklist ===<br />
Module blacklisting works the same way as with {{Pkg|initscripts}} since it is actually handled by {{Pkg|kmod}}, see [[Kernel_modules#Blacklisting|Module Blacklisting]] for details.<br />
<br />
=== Temporary files ===<br />
Systemd-tmpfiles uses the configuration files in {{ic|/usr/lib/tmpfiles.d/}} and {{ic|/etc/tmpfiles.d/}} to describe the creation, cleaning and removal of volatile and temporary files and directories which usually reside in directories such as {{ic|/run}} or {{ic|/tmp}}. Each configuration file is named in the style of {{ic|/etc/tmpfiles.d/<program>.conf}}. This will also override any files in {{ic|/usr/lib/tmpfiles.d/}} with the same name.<br />
<br />
tmpfiles are usually provided together with service files to create directories which are expected to exist by certain daemons. For example the [[Samba]] daemon expects the directory {{ic|/var/run/samba}} to exist and to have the correct permissions. The corresponding tmpfile looks like this:<br />
{{hc|/usr/lib/tmpfiles.d/samba.conf|<br />
D /var/run/samba 0755 root root<br />
}}<br />
<br />
However, tmpfiles may also be used to write values into certain files on boot. For example, if you use {{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 />
{{hc|/etc/tmpfiles.d/disable-usb-wake.conf|<br />
w /proc/acpi/wakeup - - - - USBE<br />
}}<br />
The tmpfiles method is recommended in this case since systemd doesn't actually support {{ic|/etc/rc.local}}.<br />
<br />
See {{ic|man tmpfiles.d}} for details.<br />
<br />
=== Remote filesystem mounts ===<br />
systemd automatically makes sure that remote filesystem mounts like [[NFS]] or [[Samba]] are only started after the network has been set up. Therefore remote filesystem mounts specified in {{ic|/etc/fstab}} should work out of the box.<br />
<br />
You may however want to use [[#Automount|Automount]] for remote filesystem mounts to mount them only upon access. Furthermore you can use the {{ic|1=x-systemd.device-timeout=#}} option in {{ic|/etc/fstab}} to specify a timeout in case the network resource is not available.<br />
<br />
See {{ic|man systemd.mount}} for details.<br />
<br />
=== Replacing acpid with systemd ===<br />
Systemd can handle some power-related ACPI events. This is configured via the following options in {{ic|/etc/systemd/logind.conf}}:<br />
* {{ic|HandlePowerKey}} : Power off the system when the power button is pressed<br />
* {{ic|HandleSleepKey}} : Suspend the system when the sleep key is pressed<br />
* {{ic|HandleLidSwitch}} : Suspend the system when the laptop lid is closed<br />
Depending on the value of these options, these events may for example only be triggered when no user is logged in ({{ic|no-session}}) or when only a single user session is active ({{ic|any-session}}). See {{ic|man logind.conf}} for details.<br />
<br />
These options should not be used on desktop environments like [[Gnome]] and [[XFCE]] since these handle ACPI events by themselves. However, on systems which run no graphical setup or only a simple window manager like [[i3]] or [[awesome]], this may replace the [[acpid]] daemon which is usually used to react to these ACPI events.<br />
<br />
=== Sleep hooks ===<br />
<br />
Systemd does not use [[pm-utils]] to put the machine to sleep when using {{ic|systemctl suspend}} or {{ic|systemctl hibernate}}, therefore [[pm-utils]] hooks including any [[Pm-utils#Creating_your_own_hooks|custom hooks]] created will not be run. However, systemd provides a similar mechanism to run custom scripts on these events. Systemd runs all executables in {{ic|/usr/lib/systemd/system-sleep/}} and passes two arguments to each of them:<br />
<br />
* Argument 1: either {{ic|pre}} or {{ic|post}}, depending on whether the machine is going to sleep or waking up<br />
* Argument 2: either {{ic|suspend}} or {{ic|hibernate}}, depending on what has been invoked<br />
<br />
In contrast to [[pm-utils]], systemd will run these scripts in parallel and not one after another.<br />
<br />
The output of your script will be logged by {{ic|systemd-suspend.service}} or {{ic|systemd-hibernate.service}} so you can see its output in the [[Systemd#Systemd Journal|journal]].<br />
<br />
Note that you can also use {{ic|sleep.target}}, {{ic|suspend.target}} or {{ic|hibernate.target}} to hook units into the sleep state logic instead of using scripts.<br />
<br />
See {{ic|man systemd.special}} and {{ic|man systemd-sleep}} for more information.<br />
<br />
==== Example ====<br />
{{hc|/usr/lib/systemd/system-sleep/example.sh|<nowiki><br />
case "$1" in<br />
pre )<br />
echo going to $2 ...<br />
;;<br />
post )<br />
echo waking up from $2 ...<br />
;;<br />
esac</nowiki>}}<br />
<br />
=== Unit ===<br />
A unit configuration file encodes information about a service, a socket, a device, a mount point, an automount point, a swap file or partition, a start-up target, a file system path or a timer controlled and supervised by systemd. The syntax is inspired by XDG Desktop Entry Specification .desktop files, which are in turn inspired by Microsoft Windows .ini files. See {{ic|man systemd.unit}} for more info.<br />
<br />
== Systemd commands ==<br />
<br />
*{{ic|systemctl}}: used to introspect and control the state of the systemd system and service manager.<br />
*{{ic|systemd-cgls}}: recursively shows the contents of the selected Linux control group hierarchy in a tree<br />
*{{ic|systemadm}}: a graphical frontend for the systemd system and service manager that allows introspection and control of systemd (avaiable via the {{AUR|systemd-ui-git}} package from the [[AUR]]).<br />
<br />
View the man pages for more details. <br />
<br />
{{Tip|You can use all of the following {{ic|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 />
=== Analyzing the system state ===<br />
<br />
List running units:<br />
<br />
{{bc|$ systemctl}}<br />
<br />
or:<br />
<br />
{{bc|$ systemctl list-units}}<br />
<br />
List failed units:<br />
<br />
{{bc|$ 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 list installed unit files by:<br />
{{bc|$ systemctl list-unit-files}}<br />
<br />
=== Using Units ===<br />
<br />
Units can be, for example, services ({{ic|.service}}), mount points ({{ic|.mount}}), devices ({{ic|.device}}) or sockets ({{ic|.socket}}).<br />
When using {{ic|systemctl}}, you generally have to specify the complete name of the unit file, including its suffix, for example {{ic|sshd.socket}}. There are however a few shortforms when specifying the unit in the following {{ic|systemctl}} commands:<br />
* If you don't specify the suffix, systemctl will assume {{ic|.service}}. For example, {{ic|netcfg}} and {{ic|netcfg.service}} are treated equivalent. {{Note|This currently does not work with the commands {{ic|enable}} and {{ic|disable}}.}}<br />
* Mount points will automatically be translated into the appropriate {{ic|.mount}} unit. For example, specifying {{ic|/home}} is equivalent to {{ic|home.mount}}.<br />
* Similiar to mount points, devices are automatically translated into the appropriate {{ic|.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 />
{{bc|# systemctl start <unit>}}<br />
<br />
Deactivate a unit immediately:<br />
<br />
{{bc|# systemctl stop <unit>}}<br />
<br />
Restart a unit:<br />
<br />
{{bc|# systemctl restart <unit>}}<br />
<br />
Ask a unit to reload its configuration:<br />
<br />
{{bc|# systemctl reload <unit>}}<br />
<br />
Show the status of a unit, including whether it is running or not:<br />
<br />
{{bc|$ systemctl status <unit>}}<br />
<br />
Check whether a unit is already enabled or not:<br />
<br />
{{bc|$ systemctl is-enabled <unit>}}<br />
<br />
Enable a unit to be started on bootup:<br />
<br />
{{bc|# systemctl enable <unit>}}<br />
<br />
{{Note| If services do not have an Install section, it usually means they are called automatically by other services. But if you need to install them manually, use the following command, replacing "foo" with the name of the service.<br />
<br />
{{bc|# ln -s /usr/lib/systemd/system/foo.service /etc/systemd/system/graphical.target.wants/}}<br />
<br />
}}<br />
<br />
Disable a unit to not start during bootup:<br />
<br />
{{bc|# systemctl disable <unit>}}<br />
<br />
Show the manual page associated with a unit (this has to be supported by the unit file):<br />
<br />
{{bc|$ systemctl help <unit>}}<br />
<br />
=== Power Management ===<br />
<br />
If you are in a local ConsoleKit 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 />
{{bc|$ systemctl reboot}}<br />
<br />
Shut down and power-off the system:<br />
<br />
{{bc|$ systemctl poweroff}}<br />
<br />
Shut down and halt the system:<br />
<br />
{{bc|$ systemctl halt}}<br />
<br />
Suspend the system:<br />
<br />
{{bc|$ systemctl suspend}}<br />
<br />
Hibernate the system:<br />
<br />
{{bc|$ systemctl hibernate}}<br />
<br />
== Runlevels/targets ==<br />
Runlevels is a legacy concept in systemd. 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 ''targets'' 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 runlevel/targets ===<br />
The following should be used under systemd instead of {{ic|runlevel}}:<br />
{{bc|1=# systemctl list-units --type=target}}<br />
<br />
=== Create custom target ===<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 />
{| 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 runlevels ===<br />
In systemd runlevels are exposed via "target units". You can change them like this:<br />
{{bc|# systemctl isolate graphical.target}}<br />
This will only change the current runlevel, 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 runlevel/target to boot into ===<br />
The standard target is {{ic|default.target}}, which is aliased by default to {{ic|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 />
* {{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 {{ic|default.target}}. This can be done using {{ic|systemctl}}:<br />
{{bc|# systemctl enable multi-user.target}}<br />
<br />
The effect of this command is outputted by {{ic|systemctl}}; a symlink to the new default target is made at {{ic|/etc/systemd/system/default.target}}. This works if, and only if:<br />
[Install]<br />
Alias=default.target<br />
is in the target's configuration file. Currently, {{ic|multi-user.target}} and {{ic|graphical.target}} both have it.<br />
<br />
== Running DEs under systemd ==<br />
<br />
=== Using display manager ===<br />
To enable graphical login, run your preferred [[Display Manager]] daemon (e.g. [[KDM]]). At the moment, service files exist for [[GDM]], [[KDM]], [[SLiM]], [[XDM]] and [[LXDM]].<br />
<br />
{{bc|# systemctl enable kdm.service}}<br />
<br />
This should work out of the box. If not, you might have a {{ic|default.target}} set manually or from a older install:<br />
<br />
{{hc|# ls -l /etc/systemd/system/default.target|/etc/systemd/system/default.target -> /usr/lib/systemd/system/graphical.target}}<br />
<br />
Simply delete the symlink and systemd will use its stock {{ic|default.target}} (i.e. {{ic|graphical.target}}).<br />
<br />
{{bc|# rm /etc/systemd/system/default.target}}<br />
<br />
If {{ic|/etc/locale.conf}} is used for setting the locale, add an entry to {{ic|/etc/environment}}:<br />
{{hc|/etc/environment|<nowiki><br />
LANG=en_US.utf8</nowiki>}}<br />
<br />
=== Using service file ===<br />
{{Note|Using this method there will be no PAM session created for your user. Therefore ConsoleKit (which gives you access to shutdown/reboot, audio devices etc.) will not work properly. For the recommended way, see: [[Automatic_login_to_virtual_console#With_systemd]].}}<br />
If you are only looking for a simple way to start X directly without a display manager, you can create a service file similar to this:<br />
<br />
{{hc|/etc/systemd/system/graphical.target.wants/xinit.service|<nowiki><br />
[Unit]<br />
Description=Direct login to X<br />
After=systemd-user-sessions.service<br />
<br />
[Service]<br />
ExecStart=/bin/su <username> -l -c "/bin/bash --login -c xinit"<br />
<br />
[Install]<br />
WantedBy=graphical.target<br />
</nowiki>}}<br />
<br />
== Systemd Journal ==<br />
Since version 38 systemd has an own logging system, the journal.<br />
<br />
By default, running a syslog daemon is no longer required. To read the log, use:<br />
{{bc|# journalctl}}<br />
The journal writes to {{ic|/run/systemd/journal}}, meaning logs will be lost on reboot. For non-volatile logs, create {{ic|/var/log/journal/}}:<br />
{{bc|# mkdir /var/log/journal/}}<br />
<br />
=== Filtering output ===<br />
<br />
{{ic|journalctl}} allows you to filter the output by specific fields.<br />
<br />
Examples:<br />
<br />
Show all messages by a specific executable:<br />
{{bc|# journalctl /usr/lib/systemd/systemd}}<br />
<br />
Show all messages by a specific process:<br />
{{bc|1=# journalctl _PID=1}}<br />
<br />
Show all messages by a specific unit:<br />
{{bc|1=# journalctl _SYSTEMD_UNIT=netcfg.service}}<br />
<br />
See {{ic|man journalctl}} and {{ic|systemd.journal-fields}} for details.<br />
<br />
=== journal size limit ===<br />
<br />
If the journal is made non-volatile, its size limit is set to a default value of 10% of the size of the respective file system. E.g. with {{ic|/var/log/journal}} located on a 50GiB root partition this would lead to 5GiB 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 50MiB uncomment and edit the corresponding line to:<br />
{{bc|1=SystemMaxUse=50M}}<br />
Look at {{ic|man journald.conf}} for more info.<br />
<br />
===Journald in conjunction with a classic syslog daemon===<br />
Compatibility with classic syslog implementations is provided via a<br />
socket {{ic|/run/systemd/journal/syslog}}, to which all messages are forwarded.<br />
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]). For syslog-ng, change the {{ic|source src}} section in {{ic|/etc/syslog-ng/syslog-ng.conf}} to:<br />
{{bc|<nowiki><br />
source src {<br />
unix-dgram("/run/systemd/journal/syslog");<br />
internal();<br />
file("/proc/kmsg");<br />
};</nowiki>}}<br />
<br />
and enable syslog-ng:<br />
{{bc|# systemctl enable syslog-ng.service}}<br />
<br />
== Network ==<br />
=== Dynamic (DHCP) with dhcpcd ===<br />
If you simply want to use DHCP for your ethernet connection, you can use {{ic|dhcpcd@.service}} (provided by the {{Pkg|dhcpcd}} package).<br />
To enable DHCP for {{ic|eth0}}, simply use:<br />
# systemctl start dhcpcd@eth0.service<br />
<br />
You can enable the service to automatically start at boot with:<br />
# systemctl enable dhcpcd@eth0.service<br />
<br />
=== Other configurations ===<br />
For static, wireless or advanced network configuration like bridging you can use [[Netcfg#systemd_support|netcfg]] or [[NetworkManager#Enable_NetworkManager_under_Native_systemd_system|NetworkManager]] which both provide systemd service files.<br />
{{Note|If you want to use netcfg, networkmanager or another software for managing the network you don't need to start/enable dhcpcd as seen on the previous paragraph.}}<br />
<br />
If you need a static ethernet configuration, but don't want to use [[netcfg]], there is a custom service file available on the [[Systemd/Services#Network|Systemd/Services page]].<br />
<br />
== Arch integration ==<br />
=== Initscripts emulation ===<br />
Integration with Arch's classic configuration is provided by the {{Pkg|initscripts}} package. This is simply meant as a transitional measure to ease users' move to systemd.<br />
<br />
{{Note|{{ic|/etc/inittab}} is not used at all.}}<br />
<br />
If you disabeled STGR-ALT-DEL to reboot in /etc/inittab, you will have to reconfigure this setting for systemd by doing {{ic|systemctl mask ctrl-alt-del.target}} as root.<br />
<br />
==== rc.conf ====<br />
Some variables in {{ic|/etc/rc.conf}} are respected by this glue work. For a pure systemd setup it is recommended to use the [[Systemd#Native_systemd_configuration_files|native systemd configuration files]] which will take precedence over {{ic|/etc/rc.conf}}.<br />
<br />
Supported variables:<br />
* LOCALE<br />
* KEYMAP<br />
* CONSOLEFONT<br />
* CONSOLEMAP<br />
* HOSTNAME<br />
* DAEMONS<br />
<br />
Not supported variables and systemd configuration:<br />
* TIMEZONE: Please symlink {{Ic|/etc/localtime}} to your zoneinfo file manually.<br />
* HARDWARECLOCK: See [[Systemd#Hardware clock time|Hardware clock time]].<br />
* USELVM: use {{ic|lvm.service}} provided by {{Pkg|lvm2}} instead.<br />
* USECOLOR<br />
* MODULES<br />
<br />
=== Total conversion to native systemd ===<br />
{{Note|This is the preferred method, where the system does not rely on {{ic|rc.conf}} centralised configuration anymore, but uses native systemd configuration files.}}<br />
<br />
Follow system configuration as explained in [[#Native_systemd_configuration_files]]. Each file replaces one section of {{ic|/etc/rc.conf}} as shown in that table:<br />
{| class="wikitable"<br />
|-<br />
! scope="col"| Configuration<br />
! scope="col"| Configuration file(s)<br />
! scope="col"| Legacy {{ic|/etc/rc.conf}} section<br />
|-<br />
| align="center"|Hostname<br />
| align="left"|{{ic|/etc/hostname}}<br />
{{ic|/etc/hosts}}<br />
| align="center"|{{ic|NETWORKING}}<br />
|-<br />
| align="center"|Console fonts and Keymap<br />
| align="left"|{{ic|/etc/vconsole.conf}}<br />
| align="center"|{{ic|LOCALIZATION}}<br />
|-<br />
| align="center"|Locale<br />
| align="left"|{{ic|/etc/locale.conf}}<br />
{{ic|/etc/locale.gen}}<br />
| align="center"|{{ic|LOCALIZATION}}<br />
|-<br />
| align="center"|Timezone<br />
| align="left"|{{ic|/etc/timezone}}<br />
{{ic|/etc/localtime}}<br />
| align="center"|{{ic|LOCALIZATION}}<br />
|-<br />
| align="center"|Hardware clock<br />
| align="left"|{{ic|/etc/adjtime}}<br />
| align="center"|{{ic|LOCALIZATION}}<br />
|-<br />
| align="center"|Kernel modules<br />
| align="left"|{{ic|/etc/modules-load.d/}}<br />
| align="center"|{{ic|HARDWARE}}<br />
|}<br />
<br />
For legacy purposes, the '''DAEMONS''' section in {{ic|/etc/rc.conf}} is still compatible with systemd and can be used to start services at boot, even with a "pure" systemd service management. Alternatively, you may remove the {{ic|/etc/rc.conf}} file entirely and enable services in systemd. For each {{ic|<service_name>}} in the '''DAEMONS''' array in {{ic|/etc/rc.conf}}, type:<br />
# systemctl enable <service_name>.service<br />
{{Tip|For a list of commonly used daemons with their initscripts and systemd equivalents, see [[Daemon#List_of_Daemons|this table]].}}<br />
<br />
If {{ic|<service_name>.service}} does not exist:<br />
* the service file may not be available for systemd. In that case, you'll need to keep {{ic|rc.conf}} to start the service during boot up.<br />
* systemd may name services differently, e.g. {{ic|cronie.service}} replaces {{ic|crond}} init daemon; {{ic|alsa-store.service}} and {{ic|alsa-restore.service}} replace the {{ic|alsa}} init daemon. Another important instance is the {{ic|network}} daemon, which is replaced with another set of service files (see [[#Network]] for more details.)<br />
{{Tip|you may look inside a package that contains daemon start scripts for service names. For instance:<br />
$ pacman -Ql cronie<br />
[...]<br />
cronie /etc/rc.d/crond #<-- daemon initscript listed in the DAEMONS array (unused in a "pure" systemd configuration)<br />
[...]<br />
cronie /usr/lib/systemd/system/cronie.service #<-- corresponding systemd daemon service<br />
[...]<br />
}}<br />
* systemd will automatically handle the start order of these daemons.<br />
* some services do not need to be explicitely enabled by the user. For instance, {{ic|dbus.service}} will automatically be enabled when {{ic|dbus-core}} is installed. Check the list of available services and their state using the {{ic|systemctl}} command.<br />
<br />
== FAQ ==<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 />
{{FAQ<br />
|question=Why are my console fonts ugly?<br />
|answer=If no font is set in {{ic|/etc/vconsole.conf}} (or alternatively {{ic|/etc/rc.conf}}), then a standard font will be used. The standard font is chosen due to it supporting a wide range of character sets. Set your preferred font to fix the issue.}}<br />
<br />
{{FAQ<br />
|question=Why do I get log messages on my console?<br />
|answer=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 />
{{FAQ<br />
|question=How do I make a custom unit file?<br />
|answer=The unit files in {{ic|/etc/systemd/system/}} take precedence over the ones in {{ic|/usr/lib/systemd/system/}}. To make your own version of a unit (which will not be destroyed by an upgrade), copy the old unit file from {{ic|/usr/lib/}} to {{ic|/etc/}} and make your changes there. Alternatively you can use {{ic|.include}} to parse an existing service file and then override or add new options. For example, if you simply want to add an additional dependency to a service file, you may use:<br />
{{hc|/etc/systemd/system/<service-name>.service|<br />
<nowiki><br />
.include /usr/lib/systemd/system/<service-name>.service<br />
<br />
[Unit]<br />
Requires=<new dependency><br />
After=<new dependency><br />
</nowiki>}}<br />
Then run the following for your changes to take effect:<br />
# systemctl reenable <unit><br />
# systemctl restart <unit><br />
{{Tip|You can use {{ic|systemd-delta}} to see which unit files have been overriden and what exactly has been changed.}}<br />
}}<br />
{{FAQ<br />
|question=How do I change the number of gettys running by default?<br />
|answer=To add another getty:<br />
<br />
Simply place another symlink for instantiating another getty in the {{ic|/etc/systemd/system/getty.target.wants/}} directory:<br />
<br />
{{bc|<nowiki># ln -sf /usr/lib/systemd/system/getty@.service /etc/systemd/system/getty.target.wants/getty@tty9.service<br />
# systemctl daemon-reload<br />
# systemctl start getty@tty9.service</nowiki>}}<br />
<br />
To remove a getty:<br />
<br />
Simply remove the getty symlinks you want to get rid of in the {{ic|/etc/systemd/system/getty.target.wants/}} directory:<br />
<br />
{{bc|<nowiki># rm /etc/systemd/system/getty.target.wants/getty@tty5.service /etc/systemd/system/getty.target.wants/getty@tty6.service<br />
# systemctl daemon-reload<br />
# systemctl stop getty@tty5.service getty@tty6.service</nowiki>}}<br />
<br />
systemd does not use the {{ic|/etc/inittab}} file.<br />
<br />
{{Note|As of systemd 30, only 1 getty will be launched by default. If you switch to another tty, a getty will be launched there (socket-activation style). You can still force additional agetty processes to start using the above methods.}}}}<br />
<br />
{{FAQ<br />
|question=How do I get more verbose output during boot?<br />
|answer=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}} or look at the boot/system log with {{ic|journalctl}}.<br />
}}<br />
<br />
{{FAQ<br />
|question=How do I avoid clearing the console after boot?<br />
|answer=Create a custom {{ic|getty@tty1.service}} file by copying {{ic|/usr/lib/systemd/system/getty@.service}} to {{ic|/etc/systemd/system/getty.target.wants/getty@tty1.service}} and change {{ic|TTYVTDisallocate}} to {{ic|no}}.<br />
}}<br />
<br />
{{FAQ<br />
|question=What kernel options do I need to enable in my kernel in case I do not use the official Arch kernel?<br />
|answer=Kernels prior to 2.6.39 are unsupported.<br />
<br />
This is a partial list of required/recommended options, there might be more:<br />
<br />
{{bc|<nowiki><br />
CONFIG_AUDIT=y (recommended)<br />
CONFIG_AUDIT_LOGINUID_IMMUTABLE=y (not required, may break sysvinit compat)<br />
CONFIG_CGROUPS=y<br />
CONFIG_IPV6=[y|m] (highly recommended)<br />
CONFIG_UEVENT_HELPER_PATH="" (if you don't use an initramfs)<br />
CONFIG_DEVTMPFS=y<br />
CONFIG_DEVTMPFS_MOUNT=y (recommended, if you don't use an initramfs)<br />
CONFIG_RTC_DRV_CMOS=y (highly recommended)<br />
CONFIG_FANOTIFY=y (required for readahead)<br />
CONFIG_AUTOFS4_FS=[y|m]<br />
CONFIG_TMPFS_POSIX_ACL=y (recommended, if you want to use pam_systemd.so)<br />
</nowiki>}}}}<br />
<br />
{{FAQ<br />
|question=What other units does a unit depend on?<br />
|answer=For example, if you want to figure out which services a target like {{ic|multi-user.target}} pulls in, use something like this: <br />
{{hc|$ systemctl show -p "Wants" multi-user.target|2=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 />
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 />
{{FAQ<br />
|question=My computer shuts down, but the power stays on.<br />
|answer=Use:<br />
$ systemctl poweroff<br />
Instead of {{ic|systemctl halt}}.}}<br />
<br />
{{FAQ<br />
|question=After migrating to systemd, why won't my fakeRAID mount?<br />
|answer=Be sure you use {{bc|# systemctl enable dmraid.service}}<br />
}}<br />
<br />
== Optimization ==<br />
=== systemd-analyze ===<br />
Systemd provides a tool called {{ic|systemd-analyze}} that allows you to analyze your boot process so you can see which unit files are causing your boot process to slow down. You can then optimize your system accordingly. You have to install {{Pkg|python2-dbus}} and {{Pkg|python2-cairo}} to use it.<br />
<br />
To see how much time was spent in kernel-/userspace on boot, simply use:<br />
{{bc|$ systemd-analyze}}<br />
{{Tip|If you add the {{ic|timestamp}} hook to your {{ic|HOOKS}} array in {{ic|/etc/mkinitcpio.conf}} and rebuild your initramfs, {{ic|systemd-analyze}} will also be able to show you how much time was spent in the initramfs.}}<br />
<br />
To list the started unit files, sorted by the time each of them took to start up:<br />
{{bc|$ systemd-analyze blame}}<br />
<br />
You can also create a SVG file which describes your boot process grapically, similiar to [[Bootchart]]:<br />
{{bc|$ systemd-analyze plot > plot.svg}}<br />
<br />
====Enabling bootchart in conjunction with systemd====<br />
You can use a version of bootchart to visualize the boot sequence.<br />
Since you are not able to put a second init into the kernel cmdline you won't be able to use any of the standard bootchart setups. However the {{AUR|bootchart2}} package from [[AUR]] comes with an undocumented systemd service. After you've installed bootchart2 do:<br />
{{bc|# systemctl enable bootchart.service}}<br />
Read the [https://github.com/mmeeks/bootchart bootchart documentation] for further details on using this version of bootchart.<br />
<br />
=== Shell Shortcuts ===<br />
Systemd daemon management requires a bit more text entry to accomplish tasks such as start, stopped, enabling, checking status, etc. The following functions can be added one's {{ic|~/.bashrc}} to help streamline interactions with systemd and to improve the overall experience.<br />
<br />
<pre>if ! systemd-notify --booted; then # not using systemd<br />
start() {<br />
sudo rc.d start $1<br />
}<br />
<br />
restart() {<br />
sudo rc.d restart $1<br />
}<br />
<br />
stop() {<br />
sudo rc.d stop $1<br />
}<br />
else<br />
start() {<br />
sudo systemctl start $1<br />
}<br />
<br />
restart() {<br />
sudo systemctl restart $1<br />
}<br />
<br />
stop() {<br />
sudo systemctl stop $1<br />
}<br />
<br />
enable() {<br />
sudo systemctl enable $1<br />
}<br />
<br />
status() {<br />
sudo systemctl status $1<br />
}<br />
<br />
disable() {<br />
sudo systemctl disable $1<br />
}<br />
fi<br />
</pre><br />
<br />
=== Less output ===<br />
Change {{ic|verbose}} to {{ic|quiet}} on the kernel line in GRUB. For some systems, particularly those with an SSD, the slow performance of the TTY is actually a bottleneck, and so less output means faster booting.<br />
<br />
=== Early start ===<br />
One central feature of systemd is dbus and socket activation, this causes services to be started when they are first accessed, and is generally a good thing. However, if you know that a service (like console-kit) will always be started during boot, then the overall boot time might be reduced by starting it as early as possible. This can be achieved (if the service file is set up for it, which in most cases it is) by issuing:<br />
<br />
{{bc|# systemctl enable console-kit-daemon.service}}<br />
<br />
This will cause systemd to start console-kit as soon as possible, without causing races with the socket or dbus activation.<br />
<br />
=== Automount ===<br />
The default setup will fsck and mount all filesystems before starting most daemons and services. 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 being fsck'ed. This can be achieved by adding the following options to the 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 />
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 doesn't have to wait for the device to become available. For example:<br />
{{hc|/etc/crypttab|data /dev/md0 /root/key noauto}}<br />
<br />
=== Readahead ===<br />
systemd comes with its own readahead implementation, this should in principle improve boot time. However, depending on your kernel version and the type of your hard drive, your mileage may vary (i.e. it might be slower). To enable, do:<br />
<br />
{{bc|<nowiki># systemctl enable systemd-readahead-collect.service systemd-readahead-replay.service</nowiki>}}<br />
<br />
Remember that in order for the readahead to work its magic, you should reboot a couple of times.<br />
<br />
=== User sessions ===<br />
systemd can divide user sessions into cgroups. Add {{ic|session optional pam_systemd.so}} to your relevant {{ic|/etc/pam.d/}} files (e.g., {{ic|login}} for tty logins, {{ic|sshd}} for remote access, {{ic|kde}} for password kdm logins, {{ic|kde-np}} for automatic kdm logins).<br />
<br />
Before:<br />
{{hc|$ systemd-cgls systemd:/system/getty@.service|<br />
systemd:/system/getty@.service:<br />
├ tty5<br />
│ └ 904 /sbin/agetty tty5 38400<br />
├ tty2<br />
│ ├ 13312 /bin/login --<br />
│ └ 15765 -zsh<br />
[…]}}<br />
After:<br />
{{hc|$ systemd-cgls systemd:/user/example/|<br />
systemd:/user/example/:<br />
├ 4<br />
│ ├ 902 /bin/login --<br />
│ └ 16016 -zsh<br />
[…]}}<br />
<br />
Further, you can replace [[ConsoleKit]]'s functionality with systemd. To do this, {{Pkg|polkit}} needs to be rebuilt from [[ABS]] with systemd enabled ({{ic|--enable-systemd}}), and stuff like USB automounting will work without consolekit. DBus supports systemd since version 1.6.0, so there's no longer need to build it from Git.<br />
<br />
== Troubleshooting ==<br />
=== Shutdown/Reboot takes terribly long ===<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.<br />
To find out if you are affected see [http://freedesktop.org/wiki/Software/systemd/Debugging#Shutdown_Completes_Eventually this article].<br />
==== SLiM and xfce-session ====<br />
One setup that can produce a shutdown freeze is Xfce in conjunction with SLiM: Shutting down/rebooting using xfce-session will cause slim.service to hang for half a minute until systemd kills it the hard way.<br />
One workaround is to create a modified slim.service:<br />
{{hc|/etc/systemd/system/slim.service|<nowiki><br />
[Unit]<br />
Description=SLiM Simple Login Manager<br />
After=systemd-user-sessions.service<br />
<br />
[Service]<br />
Type=forking<br />
PIDFile=/var/lock/slim.lock<br />
ExecStart=/usr/bin/slim -d<br />
ExecStop=/bin/kill -9 $MAINPID<br />
ExecStopPost=/bin/rm /var/lock/slim.lock<br />
<br />
[Install]<br />
WantedBy=graphical.target</nowiki>}}<br />
This causes SLiM to be terminated using SIGKILL. Since the lock file is also removed this does not cause a problem.<br />
<br />
=== If the CUPS service isn't starting on demand ===<br />
I found on my machine, even after running "systemctl enable cups.service", cups would never work until I manually issued "systemctl start cups.service". To remedy this you can manually symlink the cups service so its automatically started at boot: {{bc|<nowiki># sudo ln -s '/usr/lib/systemd/system/cups.service' '/etc/systemd/system/multi-user.target.wants/cups.service'</nowiki>}}<br />
I found that "systemctl enable cupsd.service" fails with a complaint about not finding the file. I'm guessing this is because it is a symlink to cups.service. Apparently systemctl doesn't like symlinks. I'm not sure if this is user error (I wasn't meant to use the symlink for this purpose) or a bug but either way, specifying cups.service seemed to work although I haven't tested it yet.<br />
<br />
=== Disable warning bell ===<br />
Add command xset -b to .xinitrc file.<br />
Discussion on [https://bbs.archlinux.org/viewtopic.php?pid=1148781 forum]<br />
<br />
=== rc.conf daemons ===<br />
Some {{ic|/etc/rc.conf}} daemons do not work well with systemd, such as '''timidity++''' and '''syslog-ng'''. For the case of timidity++, it will look for timidity++.service which is not available. Therefore, timidity++ can only be enabled with systemctl. On the other hand, syslog-ng in the rc.conf daemons will cause problem for syslog.socket. Thus, syslog-ng needs to be removed in rc.conf.<br />
<br />
== See also==<br />
*[http://www.freedesktop.org/wiki/Software/systemd Official Web Site]<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/Booting-up-Tools-and-tips-for-systemd-1570630.html Booting up: Tools and tips for systemd, a Linux init tool. In The H]<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]</div>Gilmorejahttps://wiki.archlinux.org/index.php?title=GRUB&diff=213792GRUB2012-07-20T19:28:23Z<p>Gilmoreja: /* Install to UEFI SYSTEM PARTITION */ -- Corrected syntax error</p>
<hr />
<div>[[Category:Boot loaders]]<br />
[[cs:GRUB2]]<br />
[[es:GRUB2]]<br />
[[fr:GRUB2]]<br />
[[id:GRUB2]]<br />
[[it:GRUB2]]<br />
[[ru:GRUB2]]<br />
[[tr:GRUB2]]<br />
[[zh-CN:GRUB2]]<br />
[[zh-TW:GRUB2]]<br />
{{Article summary start}}<br />
{{Article summary text|Covers various aspects of the next generation of the GRand Unified Bootloader (GRUB2).}}<br />
{{Article summary heading|Overview}}<br />
{{Article summary text|{{Boot process overview}}}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Burg}} - Burg is a brand-new boot loader based on GRUB2. It uses a new object format which allows it to be built in a wider range of OS, including Linux, Windows, OS X, Solaris, FreeBSD, etc. It also has a highly configurable menu system which works in both text and graphic mode. <br />
{{Article summary heading|Resources}}<br />
{{Article summary link|GNU GRUB -- GNU Project|https://www.gnu.org/software/grub/}}<br />
{{Article summary end}}<br />
<br />
[https://www.gnu.org/software/grub/ GRUB2] is the next generation of the GRand Unified Bootloader (GRUB). GRUB2 is derived from [http://www.nongnu.org/pupa/ PUPA] which was a research project to investigate the next generation of GRUB. GRUB2 has been rewritten from scratch to clean up everything and provide modularity and portability [https://www.gnu.org/software/grub/grub-faq.en.html#q1].<br />
<br />
In brief, the ''bootloader'' is the first software program that runs when a computer starts. It is responsible for loading and transferring control to the Linux kernel. The kernel, in turn, initializes the rest of the operating system.<br />
<br />
{{Note|The name ''GRUB'' officially refers to version ''2'' of the software, see [https://www.gnu.org/software/grub/]. If you are looking for the article on the legacy version, see [[GRUB Legacy]].}}<br />
<br />
{{Note|From 1.99-6 onwards, GRUB2 supports [[Btrfs]] as root (without a separate {{ic|/boot}} filesystem) compressed with either zlib or LZO.}}<br />
<br />
{{Note|The [[Archboot]] ISO's installer script supports {{Pkg|grub-bios}} and {{Pkg|grub-efi-x86_64}} installation. The official installer script AIF (Arch Installation Framework) does not support GRUB(2) yet.}}<br />
<br />
{{Note|For GRUB2 UEFI info, it is recommended to read the [[UEFI]], [[GPT]] and [[UEFI_Bootloaders]] pages before reading this page.}}<br />
<br />
== Preface ==<br />
<br />
[[GRUB Legacy]] (i.e. version 0.9x) is considered legacy by upstream and is being replaced by GRUB2 and [[Syslinux]] in many distributions. Upstream recommends GRUB2 >=1.99 over GRUB Legacy, even for current GRUB Legacy users.<br />
<br />
=== Notes for current GRUB Legacy users ===<br />
<br />
* There are differences in the commands of GRUB and GRUB2. Familiarize yourself with [https://www.gnu.org/software/grub/manual/grub.html#Commands GRUB2 commands] before proceeding (e.g. "find" has been replaced with "search").<br />
<br />
* GRUB2 is now ''modular'' and no longer requires "stage 1.5". As a result, the bootloader itself is limited -- modules are loaded from the hard drive as needed to expand functionality (e.g. for [[LVM]] or RAID support).<br />
<br />
* Device naming has changed between GRUB and GRUB2. Partitions are numbered from 1 instead of 0 while drives are still numbered from 0, and prefixed with partition-table type. For example, {{ic|/dev/sda1}} would be referred to as {{ic|(hd0,msdos1)}} (for MBR) or {{ic|(hd0,gpt1)}} (for GPT) using GRUB2.<br />
<br />
=== Preliminary Requirements for GRUB2 ===<br />
<br />
==== BIOS systems ====<br />
<br />
===== [[GPT]] specific instructions =====<br />
<br />
GRUB2 in BIOS-GPT configuration requires a BIOS Boot Partition to embed its {{ic|core.img}} in the absence of post-MBR gap in GPT partitioned systems (which is taken over by the GPT Primary Header and Primary Partition table). This partition is used by GRUB2 only in BIOS-GPT setups. No such partition type exists in case of MBR partitioning (at least not for GRUB2). This partition is also not required if the system is UEFI based, as no embedding of bootsectors takes place in that case. Syslinux does not require this partition.<br />
<br />
For a BIOS-GPT configuration, create a 2 MiB partition using cgdisk or GNU Parted with no filesystem. The location of the partition in the partition table does not matter but it should be within the first 2 TiB region of the disk. It is advisable to put it somewhere in the beginning of the disk before the {{ic|/boot}} partition. Set the partition type to "EF02" in cgdisk or {{ic|set <BOOT_PART_NUM> bios_grub on}} in GNU Parted.<br />
<br />
{{Note|This partition should be created before {{ic|grub-install}} or {{ic|grub-setup}} is run or before the '''Install Bootloader''' step of the Archlinux installer (if GRUB2 BIOS is selected as bootloader).}}<br />
<br />
===== [[MBR]] aka msdos partitioning specific instructions =====<br />
<br />
Usually the post-MBR gap (after the 512 byte MBR region and before the start of the 1st partition) in many MBR (or msdos disklabel) partitioned systems is 32 KiB when DOS compatibility cylinder alignment issues are satisfied in the partition table. However a post-MBR gap of about 1 to 2 MiB is recommended to provide sufficient room for embedding GRUB2's {{ic|core.img}} ({{bug|24103}}). It is advisable to use a partitioner which supports 1 MiB partition alignment to obtain this space as well as satisfy other non-512 byte sector issues (which are unrelated to embedding of {{ic|core.img}}).<br />
<br />
If you do not dual-boot with MS Windows (any version) in BIOS systems, it is advisable to switch to GPT partitioning - [[GUID_Partition_Table#Convert_from_MBR_to_GPT]]<br />
<br />
{{Note|Create the 2MiB partition mentioned above BEFORE you convert to GPT. If you do not, gparted will not resize your boot partition to allow its creation, and when you reboot GRUB2 will not know where to look.}}<br />
<br />
==== UEFI systems ====<br />
<br />
===== Create and Mount the UEFI SYSTEM PARTITION =====<br />
<br />
{{Note|It is recommended to read the [[UEFI]], [[GPT]] and [[UEFI_Bootloaders]] pages before reading this part.}}<br />
<br />
Follow [[Unified_Extensible_Firmware_Interface#Create_an_UEFI_System_Partition_in_Linux]] for instructions on creating a UEFI SYSTEM PARTITION. Then mount the UEFI SYSTEM PARTITION at {{ic|/boot/efi}}. If you have mounted the UEFISYS partition in some other mountpoint, replace {{ic|/boot/efi}} in the below instructions with that mountpoint:<br />
<br />
# mkdir -p /boot/efi<br />
# mount -t vfat <UEFISYS_PART_DEVICE> /boot/efi<br />
<br />
Create a <UEFI_SYSTEM_PARTITION>{{ic|/EFI}} directory, if it does not exist:<br />
<br />
# mkdir -p /boot/efi/EFI<br />
<br />
== Installation ==<br />
<br />
=== During Arch Linux installation ===<br />
<br />
* Skip the '''Install Bootloader''' step and exit the installer.<br />
* Configure the network:<br />
# aif -p partial-configure-network<br />
This will bring up a prompt; put in the network interface to use, (e.g., {{ic|eth0}}) and use DHCP for easy configuration.<br />
* If you did not configure the installed system's {{ic|/etc/resolv.conf}} file during installation (for instance, if you plan to let DHCP generate it later), you will need to copy the one generated by AIF when it configured the network:<br />
# cp /etc/resolv.conf /mnt/etc/resolv.conf<br />
* If you run into network issues in the pacman update step below, you may have needed to install the {{Pkg|net-tools}} package.<br />
* Check and see if the {{ic|dm_mod}} module is loaded. If it is not, load it manually:<br />
# lsmod | grep dm_mod<br />
# modprobe dm-mod<br />
{{Note|This is necessary at this point, and cannot be postponed after the chroot. If you try to use modprobe in a chroot environment that has a later kernel version from that of the installing device (at the time of writing, 2.6.33), modprobe will fail. This happens routinely using the Arch "net" installations.}}<br />
* From the installer's live shell, chroot to the installed system:<br />
# mount -o bind /dev /mnt/dev<br />
# mount -t proc /proc /mnt/proc/<br />
# mount -t sysfs /sys /mnt/sys/<br />
# chroot /mnt bash<br />
* Update pacman's database:<br />
# pacman-db-upgrade<br />
* Refresh the package list (with an extra {{ic|-y}} flag to force a refresh of all package lists even if they appear to be up to date):<br />
# pacman -Syy<br />
* Install the GRUB2 package as mentioned in the section [[#From a running Arch Linux]] (Note that the {{ic|dm-mod}} module has already been loaded, no need to do that again).<br />
<br />
=== From a running Arch Linux ===<br />
<br />
==== BIOS systems ====<br />
<br />
===== Backup Important Data =====<br />
<br />
Although a GRUB(2) installation should run smoothly, it is strongly recommended to keep the GRUB Legacy files before installing {{Pkg|grub-bios}}.<br />
<br />
# mv /boot/grub /boot/grub-legacy<br />
<br />
Backup the MBR which contains the boot code and partition table (Replace {{ic|/dev/sd'''X'''}} with your actual disk path)<br />
<br />
# dd if=/dev/sdX of=/path/to/backup/mbr_backup bs=512 count=1<br />
<br />
Only 446 bytes of the MBR contain boot code, the next 64 contain the partition table. If you do not want to overwrite your partition table when restoring, it is strongly advised to backup only the MBR boot code:<br />
<br />
# dd if=/dev/sdX of=/path/to/backup/bootcode_backup bs=446 count=1<br />
<br />
If unable to install GRUB2 correctly, see [[GRUB2#Restore_GRUB_Legacy]].<br />
<br />
===== Install grub-bios package =====<br />
<br />
The GRUB(2) packages can be installed with pacman (and will replace {{Pkg|grub-legacy}} or {{Pkg|grub}}, if it is installed):<br />
<br />
# pacman -S grub-bios<br />
<br />
{{Note|Simply installing the package won't update the {{ic|/boot/grub/i386-pc/core.img}} file and the GRUB(2) modules in {{ic|/boot/grub/i386-pc}}. You need to update them manually using {{ic|grub-install}} as explained below.}}<br />
<br />
Also load the device-mapper kernel module without which {{ic|grub-probe}} does not reliably detect disks and partitions:<br />
<br />
# modprobe dm_mod<br />
<br />
===== Install grub-bios boot files =====<br />
<br />
There are 3 ways to install GRUB(2) boot files in BIOS booting:<br />
*[[#Install_to_440-byte_MBR_boot_code_region]] (recommended) , <br />
*[[#Install_to_Partition_or_Partitionless_Disk]] (not recommended),<br />
*[[#Generate_core.img_alone]] (safest method, but requires another BIOS bootloader like [[grub-legacy]] or [[syslinux]] to be installed to chainload {{ic|/boot/grub/i386-pc/core.img}}). <br />
<br />
====== Install to 440-byte MBR boot code region ======<br />
<br />
To setup {{ic|grub-bios}} in the 440-byte Master Boot Record boot code region, populate the {{ic|/boot/grub}} directory, generate the {{ic|/boot/grub/i386-pc/core.img}} file, and embed it in the 32 KiB (minimum size - varies depending on partition alignment) post-MBR gap (MBR disks) or in BIOS Boot Partition (GPT disks), run:<br />
<br />
# grub-install --directory=/usr/lib/grub/i386-pc --target=i386-pc --boot-directory=/boot --recheck --debug /dev/sda<br />
# mkdir -p /boot/grub/locale<br />
# cp /usr/share/locale/en\@quot/LC_MESSAGES/grub.mo /boot/grub/locale/en.mo<br />
<br />
where {{ic|/dev/sda}} is the destination of the installation (in this case the MBR of the first SATA disk). If you use [[LVM]] for your {{ic|/boot}}, you can install GRUB2 on multiple physical disks. <br />
<br />
The {{ic|--no-floppy}} tells {{ic|grub-bios}} utilities not to search for any floppy devices which reduces the overall execution time of {{ic|grub-install}} on many systems (it will also prevent the issue below from occurring). Otherwise you get an error that looks like this:<br />
<br />
grub-probe: error: Cannot get the real path of '/dev/fd0'<br />
Auto-detection of a filesystem module failed.<br />
Please specify the module with the option '--modules' explicitly.<br />
<br />
{{Note|{{ic|--no-floppy}} has been removed from {{ic|grub-install}} in 2.00~beta2 upstream release, and replaced with {{ic|--allow-floppy}}.}}<br />
<br />
{{Warning|Make sure to check the {{ic|/boot}} directory if you use the latter. Sometimes the {{ic| boot-directory}} parameter creates another {{ic|/boot}} folder inside of {{ic|/boot}}. A wrong install would look like: {{ic|/boot/boot/grub/}}.}}<br />
<br />
====== Install to Partition or Partitionless Disk ======<br />
<br />
{{Note|{{ic|grub-bios}} (any version - including upstream Bazaar repo) does not encourage installation to a partition boot sector or a partitionless disk like GRUB Legacy or syslinux does. This kind of setup is prone to breakage, especially during updates, and is not supported by Arch devs.}}<br />
<br />
To set up {{ic|grub-bios}} to a partition boot sector, to a partitionless disk (also called superfloppy) or to a floppy disk, run (using for example {{ic|/dev/sdaX}} as the {{ic|/boot}} partition):<br />
<br />
# chattr -i /boot/grub/i386-pc/core.img<br />
# grub-install --directory=/usr/lib/grub/i386-pc --target=i386-pc --boot-directory=/boot --recheck --force --debug /dev/sdaX<br />
# mkdir -p /boot/grub/locale<br />
# cp /usr/share/locale/en@quot/LC_MESSAGES/grub.mo /boot/grub/locale/en.mo<br />
# chattr +i /boot/grub/i386-pc/core.img<br />
<br />
You need to use the {{ic|--force}} option to allow usage of blocklists and should not use {{ic|1=--grub-setup=/bin/true}} (which is similar to simply generating {{ic|core.img}}).<br />
<br />
{{ic|grub-install}} will give out warnings like which should give you the idea of what might go wrong with this approach:<br />
<br />
/sbin/grub-setup: warn: Attempting to install GRUB to a partitionless disk or to a partition. This is a BAD idea.<br />
/sbin/grub-setup: warn: Embedding is not possible. GRUB can only be installed in this setup by using blocklists. <br />
However, blocklists are UNRELIABLE and their use is discouraged.<br />
<br />
Without {{ic|--force}} you may get the below error and {{ic|grub-setup}} will not setup its boot code in the partition boot sector:<br />
<br />
/sbin/grub-setup: error: will not proceed with blocklists<br />
<br />
With {{ic|--force}} you should get:<br />
<br />
Installation finished. No error reported.<br />
<br />
The reason why {{ic|grub-setup}} does not by default allow this is because in case of partition or a partitionless disk is that {{ic|grub-bios}} relies on embedded blocklists in the partition bootsector to locate the {{ic|/boot/grub/i386-pc/core.img}} file and the prefix dir {{ic|/boot/grub}}. The sector locations of {{ic|core.img}} may change whenever the filesystem in the partition is being altered (files copied, deleted etc.). For more info see https://bugzilla.redhat.com/show_bug.cgi?id=728742 and https://bugzilla.redhat.com/show_bug.cgi?id=730915.<br />
<br />
The workaround for this is to set the immutable flag on {{ic|/boot/grub/i386-pc/core.img}} (using chattr command as mentioned above) so that the sector locations of the {{ic|core.img}} file in the disk is not altered. The immutable flag on {{ic|/boot/grub/i386-pc/core.img}} needs to be set only if {{ic|grub-bios}} is installed to a partition boot sector or a partitionless disk, not in case of installtion to MBR or simple generation of {{ic|core.img}} without embedding any bootsector (mentioned above).<br />
<br />
====== Generate core.img alone ======<br />
<br />
To populate the {{ic|/boot/grub}} directory and generate a {{ic|/boot/grub/i386-pc/core.img}} file '''without''' embedding any {{ic|grub-bios}} bootsector code in the MBR, post-MBR region, or the partition bootsector, add {{ic|1=--grub-setup=/bin/true}} to {{ic|grub-install}}:<br />
<br />
# grub-install --directory=/usr/lib/grub/i386-pc --target=i386-pc --grub-setup=/bin/true --boot-directory=/boot --recheck --debug /dev/sda<br />
# mkdir -p /boot/grub/locale<br />
# cp /usr/share/locale/en@quot/LC_MESSAGES/grub.mo /boot/grub/locale/en.mo<br />
<br />
You can then chainload GRUB2's {{ic|core.img}} from GRUB Legacy or syslinux as a Linux kernel or a multiboot kernel.<br />
<br />
===== Generate GRUB2 BIOS Config file =====<br />
<br />
Finally, generate a configuration for GRUB2 (this is explained in greater detail in the Configuration section):<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
{{Note|The file path is {{ic|/boot/grub/grub.cfg}}, NOT {{ic|/boot/grub/i386-pc/grub.cfg}}.}}<br />
<br />
If grub2 complains about "no suitable mode found" while booting, go to [[#Correct_GRUB2_No_Suitable_Mode_Found_Error]].<br />
<br />
If {{ic|grub-mkconfig}} fails, convert your {{ic|/boot/grub/menu.lst}} file to {{ic|/boot/grub/grub.cfg}} using:<br />
<br />
# grub-menulst2cfg /boot/grub/menu.lst /boot/grub/grub.cfg<br />
<br />
For example:<br />
<br />
{{hc|/boot/grub/menu.lst|<nowiki><br />
default=0<br />
timeout=5<br />
<br />
title Arch Linux Stock Kernel<br />
root (hd0,0)<br />
kernel /vmlinuz-linux root=/dev/sda2 ro<br />
initrd /initramfs-linux.img<br />
<br />
title Arch Linux Stock Kernel Fallback<br />
root (hd0,0)<br />
kernel /vmlinuz-linux root=/dev/sda2 ro<br />
initrd /initramfs-linux-fallback.img<br />
</nowiki>}}<br />
<br />
{{hc|/boot/grub/grub.cfg|<nowiki><br />
set default='0'; if [ x"$default" = xsaved ]; then load_env; set default="$saved_entry"; fi<br />
set timeout=5<br />
<br />
menuentry 'Arch Linux Stock Kernel' {<br />
set root='(hd0,1)'; set legacy_hdbias='0'<br />
legacy_kernel '/vmlinuz-linux' '/vmlinuz-linux' 'root=/dev/sda2' 'ro'<br />
legacy_initrd '/initramfs-linux.img' '/initramfs-linux.img'<br />
<br />
}<br />
<br />
menuentry 'Arch Linux Stock Kernel Fallback' {<br />
set root='(hd0,1)'; set legacy_hdbias='0'<br />
legacy_kernel '/vmlinuz-linux' '/vmlinuz-linux' 'root=/dev/sda2' 'ro'<br />
legacy_initrd '/initramfs-linux-fallback.img' '/initramfs-linux-fallback.img'<br />
}<br />
</nowiki>}}<br />
<br />
If you forgot to create a GRUB2 {{ic|/boot/grub/grub.cfg}} config file and simply rebooted into GRUB2 Command Shell, type:<br />
<br />
sh:grub> insmod legacycfg<br />
sh:grub> legacy_configfile ${prefix}/menu.lst<br />
<br />
Boot into Arch and re-create the proper GRUB2 {{ic|/boot/grub/grub.cfg}} config file.<br />
<br />
{{Note|This option works only in BIOS systems, not in UEFI systems.}}<br />
<br />
===== Multiboot in BIOS =====<br />
<br />
====== Boot Microsoft Windows installed in BIOS-MBR mode ======<br />
<br />
{{Note|GRUB2 supports booting {{ic|bootmgr}} directly and chainload of partition boot sector is no longer required to boot Windows in a BIOS-MBR setup.}}<br />
<br />
Find the UUID of the NTFS filesystem of the Windows's SYSTEM PARTITION where the {{ic|bootmgr}} and its files reside. For example, if Windows {{ic|bootmgr}} exists at {{ic|/media/Windows/bootmgr}}:<br />
<br />
# grub-probe --target=fs_uuid /media/Windows/bootmgr<br />
69B235F6749E84CE<br />
<br />
Then, add the below code to {{ic|/etc/grub.d/40_custom}} and regenerate {{ic|grub.cfg}} with {{ic|grub-mkconfig}} as explained above to boot Windows (Vista, 7 or 8) installed in BIOS-MBR mode:<br />
<br />
<pre><br />
#!/bin/sh<br />
menuentry "Microsoft Windows 7 BIOS-MBR" {<br />
insmod part_msdos<br />
insmod ntfs<br />
insmod search_fs_uuid<br />
insmod ntldr <br />
search --fs-uuid --no-floppy --set=root 69B235F6749E84CE<br />
ntldr /bootmgr<br />
}</pre><br />
<br />
For Windows XP:<br />
<br />
menuentry "Microsoft Windows XP" {<br />
insmod part_msdos<br />
insmod ntfs<br />
insmod search_fs_uuid<br />
insmod ntldr <br />
search --fs-uuid --no-floppy --set=root 69B235F6749E84CE<br />
ntldr /ntldr<br />
}<br />
<br />
==== UEFI systems ====<br />
<br />
{{Note|It is recommended to read the [[UEFI]], [[GPT]] and [[UEFI_Bootloaders]] pages before reading this part.}}<br />
<br />
===== Install grub-uefi package =====<br />
<br />
{{Note|Unless specified as EFI 1.x , EFI and UEFI terms are used interchangeably to denote UEFI 2.x firmware. Also unless stated explicitely, the instructions are general and not Mac specific. Some of them may not work or may be different in Macs. Apple's EFI implementation is neither a EFI 1.x version nor UEFI 2.x version but mixes up both. This kind of firmware does not fall under any one UEFI Specification version and is therefore not a standard UEFI firmware.}}<br />
<br />
GRUB2 UEFI bootloader is available in Arch Linux only from version 1.99~rc1. To install, first [[Unified_Extensible_Firmware_Interface#Detecting_UEFI_Firmware_Arch|detect which UEFI firmware arch]] you have (either x86_64 or i386).<br />
<br />
Depending on that, install the appropriate package<br />
<br />
For 64-bit aka x86_64 UEFI firmware:<br />
# pacman -S grub-efi-x86_64<br />
<br />
For 32-bit aka i386 UEFI firmware:<br />
# pacman -S grub-efi-i386<br />
<br />
{{Note|Simply installing the package will not update the {{ic|grub.efi}} file and the GRUB(2) modules in the UEFI System Partition. You need to do this manually using {{ic|grub-install}} as explained below.}}<br />
<br />
Also load the device-mapper kernel module without which {{ic|grub-probe}} does not reliably detect disks and partitions:<br />
<br />
# modprobe dm-mod<br />
<br />
===== Install grub-uefi boot files =====<br />
<br />
====== Install to UEFI SYSTEM PARTITION ======<br />
<br />
{{Note|The below commands assume you are using {{ic|grub-efi-x86_64}} (for {{ic|grub-efi-i386}} replace {{ic|x86_64}} with {{ic|i386}} in the below commands).}}<br />
<br />
The UEFI system partition will need to be mounted at {{ic|/boot/efi/}} for the GRUB2 install script to detect it:<br />
<br />
# mkdir -p /boot/efi<br />
# mount -t vfat /dev/sdXY /boot/efi<br />
<br />
Install GRUB UEFI application to {{ic|/boot/efi/EFI/arch_grub}} and its modules to {{ic|/boot/grub/x86_64-efi}} (recommended) using:<br />
<br />
# grub-install --directory=/usr/lib/grub/x86_64-efi --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=arch_grub --boot-directory=/boot --recheck --debug<br />
# mkdir -p /boot/grub/locale<br />
# cp /usr/share/locale/en\@quot/LC_MESSAGES/grub.mo /boot/grub/locale/en.mo<br />
<br />
If you want to install grub2 modules and {{ic|grub.cfg}} at the directory {{ic|/boot/efi/EFI/grub}} and the {{ic|grubx64.efi}} application at {{ic|/boot/efi/EFI/arch_grub}} use:<br />
<br />
# grub-install --directory=/usr/lib/grub/x86_64-efi --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=arch_grub --boot-directory=/boot/efi/EFI --recheck --debug<br />
# mkdir -p /boot/efi/EFI/grub/locale<br />
# cp /usr/share/locale/en\@quot/LC_MESSAGES/grub.mo /boot/efi/EFI/grub/locale/en.mo<br />
<br />
In this case {{ic|grub-efi-x86_64}} will be installed into {{ic|/boot/grub}}, making the behavior consistent with the BIOS verion of GRUB2, but this is not recommended if you use both {{ic|grub-bios}} and {{ic|grub-efi-x86_64}} in your system, as this will overwrite {{ic|grub-bios }}modules in {{ic|/boot/grub}}.<br />
<br />
The {{ic|--efi-directory}} option mentions the mountpoint of UEFI SYSTEM PARTITION , {{ic|--bootloader-id}} mentions the name of the directory used to store the {{ic|grubx64.efi}} file and {{ic|--boot-directory}} mentions the directory wherein the actual modules will be installed (and into which {{ic|grub.cfg}} should be created).<br />
<br />
The actual paths are:<br />
<br />
<efi-directory>/<EFI or efi>/<bootloader-id>/grubx64.efi<br />
<br />
<boot-directory>/grub/x86_64-efi/<all modules, grub.efi, core.efi, grub.cfg><br />
<br />
{{Note|the {{ic|--bootloader-id}} option does not change {{ic|<boot-directory>/grub}}, i.e. you cannot install the modules to {{ic|<boot-directory>/<bootloader-id>}}, the path is hard-coded to be {{ic|<boot-directory>/grub}}.}}<br />
<br />
In {{ic|<nowiki>--efi-directory=/boot/efi --boot-directory=/boot/efi/EFI --bootloader-id=grub</nowiki>}}:<br />
<br />
<efi-directory>/<EFI or efi>/<bootloader-id> == <boot-directory>/grub == /boot/efi/EFI/grub<br />
<br />
In {{ic|<nowiki>--efi-directory=/boot/efi --boot-directory=/boot/efi/EFI --bootloader-id=arch_grub</nowiki>}}:<br />
<br />
<efi-directory>/<EFI or efi>/<bootloader-id> == /boot/efi/EFI/arch_grub<br />
<boot-directory>/grub == /boot/efi/EFI/grub<br />
<br />
In {{ic|<nowiki>--efi-directory=/boot/efi --boot-directory=/boot --bootloader-id=arch_grub</nowiki>}}:<br />
<br />
<efi-directory>/<EFI or efi>/<bootloader-id> == /boot/efi/EFI/arch_grub<br />
<boot-directory>/grub == /boot/grub<br />
<br />
In {{ic|<nowiki>--efi-directory=/boot/efi --boot-directory=/boot --bootloader-id=grub</nowiki>}}:<br />
<br />
<efi-directory>/<EFI or efi>/<bootloader-id> == /boot/efi/EFI/grub<br />
<boot-directory>/grub == /boot/grub<br />
<br />
The {{ic|<nowiki><efi-directory>/<EFI or efi>/<bootloader-id>/grubx64.efi</nowiki>}} is an exact copy of {{ic|<nowiki><boot-directory>/grub/x86_64-efi/core.efi</nowiki>}}.<br />
<br />
{{Note|In GRUB2 2.00~beta4, the {{ic|grub-install}} option {{ic|--efi-directory}} replaces {{ic|--root-directory}} and the latter is deprecated.}}<br />
{{Note|The options {{ic|--efi-directory}} and {{ic|--bootloader-id}} are specific to GRUB2 UEFI.}}<br />
<br />
In all the cases the UEFI SYSTEM PARTITION should be mounted for {{ic|grub-install}} to install {{ic|grubx64.efi}} in it, which will be launched by the firmware (using the {{ic|efibootmgr}} created boot entry in non-Mac systems).<br />
<br />
If you notice carefully, there is no <device_path> option (Eg: {{ic|/dev/sda}}) at the end of the {{ic|grub-install}} command unlike the case of setting up GRUB2 for BIOS systems. Any <device_path> provided will be ignored by the install script as UEFI bootloaders do not use MBR or Partition boot sectors at all.<br />
<br />
You may now be able to UEFI boot your system by creating a {{ic|grub.cfg}} file by following [[#Generate_GRUB2_UEFI_Config_file]] and [[#Create_GRUB2_entry_in_the_Firmware_Boot_Manager]].<br />
<br />
===== Create GRUB2 entry in the Firmware Boot Manager =====<br />
<br />
====== Non-Mac UEFI systems ======<br />
<br />
{{ic|grub-install}} will ensure that {{ic|/boot/efi/EFI/arch_grub/grubx64.efi}} is launched by default if it detects {{ic|efibootmgr}} and if it is able to access UEFI Runtime Services. Follow [[Unified_Extensible_Firmware_Interface#efibootmgr]] for more info.<br />
<br />
If you have problems running GRUB2 in UEFI mode you can try the following (worked on an ASUS Z68 mainboard):<br />
<br />
# cp /boot/efi/EFI/arch_grub/grubx64.efi /boot/efi/shellx64.efi<br />
<br />
or<br />
<br />
# cp /boot/efi/EFI/arch_grub/grubx64.efi /boot/efi/EFI/shellx64.efi<br />
<br />
or<br />
<br />
# cp /boot/efi/EFI/arch_grub/grubx64.efi /boot/efi/EFI/tools/shellx64.efi<br />
<br />
After this launch the UEFI Shell from the UEFI setup/menu (in ASUS UEFI BIOS, switch to advanced mode, press Exit in the top right corner and choose "Launch EFI shell from filesystem device"). The GRUB2 menu will show up and you can boot into your system. Afterwards you can use efibootmgr to setup a menu entry (see above).<br />
<br />
====== Apple Mac EFI systems ======<br />
<br />
{{Note|TODO: GRUB upstream Bazaar mactel branch http://bzr.savannah.gnu.org/lh/grub/branches/mactel/changes. No further update from grub developers.}}<br />
{{Note|TODO: Experimental "bless" utility for Linux by Fedora developers - {{AUR|mactel-boot}}. Requires more testing.}}<br />
<br />
Use bless command from within Mac OS X to set {{ic|grubx64.efi}} as the default boot option. You can also boot from the Mac OS X install disc and launch a Terminal there if you only have Linux installed. In the Terminal, create a directory and mount the EFI System Partition:<br />
<br />
# cd /Volumes<br />
# mkdir efi<br />
# mount -t msdos /dev/disk0s1 /Volumes/efi<br />
<br />
Then run bless on {{ic|grub.efi}} and on the EFI partition to set them as the default boot options.<br />
<br />
# bless --folder=/Volumes/efi --file=/Volumes/efi/efi/arch_grub/grubx64.efi --setBoot<br />
# bless --mount=/Volumes/efi --file=/Volumes/efi/efi/arch_grub/grubx64.efi --setBoot<br />
<br />
More info at https://help.ubuntu.com/community/UEFIBooting#Apple_Mac_EFI_systems_.28both_EFI_architecture.29.<br />
<br />
===== Generate GRUB2 UEFI Config file =====<br />
<br />
Finally, generate a configuration for GRUB2 (this is explained in greater detail in the Configuration section):<br />
<br />
# grub-mkconfig -o <boot-directory>/grub/grub.cfg<br />
<br />
{{Note|The file path is {{ic|<boot-directory>/grub/grub.cfg}}, NOT {{ic|<boot-directory>/grub/x86_64-efi/grub.cfg}}.}}<br />
<br />
If you used {{ic|<nowiki>--boot-directory=/boot</nowiki>}}:<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
If you used {{ic|<nowiki>--boot-directory=/boot/efi/EFI</nowiki>}}:<br />
<br />
# grub-mkconfig -o /boot/efi/EFI/grub/grub.cfg<br />
<br />
This is independent of the value of {{ic|--bootloader-id}} option.<br />
<br />
If GRUB2 complains about "no suitable mode found" while booting, try [[#Correct_GRUB2_No_Suitable_Mode_Found_Error]].<br />
<br />
===== Create GRUB2 Standalone UEFI Application =====<br />
<br />
It is possible to create a {{ic|grubx64_standalone.efi}} application which has all the modules embeddded in a memdisk within the uefi application, thus removing the need for having a separate directory populated with all the GRUB2 uefi modules and other related files. This is done using the {{ic|grub-mkstandalone}} command which is included in {{Pkg|grub-common}} >= 1:1.99-6 package.<br />
<br />
The easiest way to do this would be with the install command already mentioned before, but specifying the modules to include. For example:<br />
<br />
# grub-mkstandalone --directory="/usr/lib/grub/x86_64-efi/" --format="x86_64-efi" --compression="xz" \<br />
--output="/boot/efi/EFI/arch_grub/grubx64_standalone.efi" <any extra files you want to include><br />
<br />
The {{ic|grubx64_standalone.efi}} file expects {{ic|grub.cfg}} to be within its $prefix which is {{ic|(memdisk)/boot/grub}}. The memdisk is embedded within the efi app. The {{ic|grub-mkstandlone}} script allow passing files to be included in the memdisk image to be as the arguments to the script (in <any extra files you want to include>).<br />
<br />
If you have the {{ic|grub.cfg}} at {{ic|/home/user/Desktop/grub.cfg}}, then create a temporary {{ic|/home/user/Desktop/boot/grub/}} directory, copy the {{ic|/home/user/Desktop/grub.cfg}} to {{ic|/home/user/Desktop/boot/grub/grub.cfg}}, cd into {{ic|/home/user/Desktop/boot/grub/}} and run:<br />
<br />
# grub-mkstandalone --directory="/usr/lib/grub/x86_64-efi/" --format="x86_64-efi" --compression="xz" \<br />
--output="/boot/efi/EFI/arch_grub/grubx64_standalone.efi" "boot/grub/grub.cfg"<br />
<br />
The reason to cd into {{ic|/home/user/Desktop/boot/grub/}} and to pass the file path as {{ic|boot/grub/grub.cfg}} (notice the lack of a leading slash - boot/ vs /boot/ ) is because {{ic|dir1/dir2/file}} is included as {{ic|(memdisk)/dir1/dir2/file}} by the {{ic|grub-mkstandalone}} script. <br />
<br />
If you pass {{ic|/home/user/Desktop/grub.cfg}} the file will be included as {{ic|(memdisk)/home/user/Desktop/grub.cfg}}. If you pass {{ic|/home/user/Desktop/boot/grub/grub.cfg}} the file will be included as {{ic|(memdisk)/home/user/Desktop/boot/grub/grub.cfg}}. That is the reason for cd'ing into {{ic|/home/user/Desktop/boot/grub/}} and passing {{ic|boot/grub/grub.cfg}}, to include the file as {{ic|(memdisk)/boot/grub/grub.cfg}}, which is what {{ic|grub.efi}} expects the file to be.<br />
<br />
You need to create an UEFI Boot Manager entry for {{ic|/boot/efi/EFI/arch_grub/grubx64_standalone.efi}} using {{ic|efibootmgr}}. Follow [[#Create GRUB2 entry in the Firmware Boot Manager]].<br />
<br />
===== Multiboot in UEFI =====<br />
<br />
====== Chainload Microsoft Windows x86_64 UEFI-GPT ======<br />
<br />
Find the UUID of the FAT32 filesystem in the UEFI SYSTEM PARTITION where the Windows UEFI Bootloader files reside. For example, if Windows {{ic|bootmgfw.efi}} exists at {{ic|/boot/efi/EFI/Microsoft/Boot/bootmgfw.efi}} (ignore the upper-lower case differences since that is immaterial in FAT filesystem):<br />
<br />
# grub-probe --target=fs_uuid /boot/efi/EFI/Microsoft/Boot/bootmgfw.efi<br />
1ce5-7f28<br />
<br />
# grub-probe --target=hints_string /boot/efi/EFI/Microsoft/Boot/bootmgfw.efi<br />
--hint-bios=hd0,gpt1 --hint-efi=hd0,gpt1 --hint-baremetal=ahci0,gpt1<br />
<br />
Then, add this code to {{ic|/boot/grub/grub.cfg}} OR {{ic|/boot/efi/EFI/grub/grub.cfg}} to chainload Windows x86_64 (Vista SP1+, 7 or 8) installed in UEFI-GPT mode:<br />
<br />
menuentry "Microsoft Windows x86_64 UEFI-GPT" {<br />
insmod part_gpt<br />
insmod fat<br />
insmod search_fs_uuid<br />
insmod chain<br />
search --fs-uuid --no-floppy --set=root --hint-bios=hd0,gpt1 --hint-efi=hd0,gpt1 --hint-baremetal=ahci0,gpt1 1ce5-7f28<br />
chainloader /efi/Microsoft/Boot/bootmgfw.efi<br />
}<br />
<br />
== Configuration ==<br />
<br />
You can also choose to automatically generate or manually edit {{ic|grub.cfg}}.<br />
<br />
{{Note|For EFI systems, if GRUB2 was installed with the {{ic|--boot-directory}} option set, the {{ic|grub.cfg}} file must be placed in the same directory as {{ic|grubx64.efi}}. Otherwise, the {{ic|grub.cfg}} file goes in {{ic|/boot/grub/}}, just like in the BIOS version of GRUB2.}}<br />
<br />
{{Note|Here is a quite complete description of how to configure GRUB2: http://members.iinet.net/~herman546/p20/GRUB2%20Configuration%20File%20Commands.html }}<br />
<br />
=== Automatically generating using grub-mkconfig (Recommended) ===<br />
<br />
The GRUB2 {{ic|menu.lst}} equivalent configuration files are {{ic|/etc/default/grub}} and {{ic|/etc/grub.d/*}}. {{ic|grub-mkconfig}} uses these files to generate {{ic|grub.cfg}}. By default the script outputs to stdout. To generate a {{ic|grub.cfg}} file run the command:<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
{{ic|/etc/grub.d/10_linux}} is set to automatically add menu items for Arch linux that work out of the box, to any generated configuration. Other operating systems may need to be added manually by editing {{ic|/etc/grub.d/40_custom}}<br />
<br />
==== Additional arguments ====<br />
<br />
To pass custom additional arguments to the Linux image, you can set the {{ic|GRUB_CMDLINE_LINUX}} variable in {{ic|/etc/default/grub}}. This is analogous to adding commands to the kernel line in GRUB Legacy.<br />
<br />
For example, use {{ic|<nowiki>GRUB_CMDLINE_LINUX="resume=/dev/sdaX"</nowiki>}} where {{ic|sda'''X'''}} is your swap partition to enable resume after hibernation.<br />
<br />
You can also use {{ic|<nowiki>GRUB_CMDLINE_LINUX="resume=/dev/disk/by-uuid/${swap_uuid}"</nowiki>}}, where {{ic|${swap_uuid} }} is the [[Persistent_block_device_naming|UUID]] of your swap partition.<br />
<br />
=== Manually creating grub.cfg ===<br />
<br />
{{Warning|Editing this file is strongly ''not'' recommended. The file is generated by the {{ic|grub-mkconfig}} command, and it is best to edit your {{ic|/etc/default/grub}} or one of the scripts in the {{ic|/etc/grub.d}} folder.}}<br />
<br />
A basic GRUB config file uses the following options<br />
* {{ic|(hdX,Y)}} is the partition {{ic|Y}} on disk {{ic|X}}, partition numbers starting at 1, disk numbers starting at 0<br />
* {{ic|1=set default=N}} is the default boot entry that is chosen after timeout for user action<br />
* {{ic|1=set timeout=M}} is the time {{ic|M}} to wait in seconds for a user selection before default is booted<br />
* {{ic|<nowiki>menuentry "title" {entry options}</nowiki>}} is a boot entry titled {{ic|title}}<br />
* {{ic|1=set root=(hdX,Y)}} sets the boot partition, where the kernel and GRUB modules are stored (boot need not be a separate partition, and may simply be a directory under the "root" partition ({{ic|/}})<br />
<br />
An example configuration:<br />
<br />
{{hc<br />
|/boot/grub/grub.cfg<br />
|<nowiki><br />
# Config file for GRUB2 - The GNU GRand Unified Bootloader<br />
# /boot/grub/grub.cfg<br />
<br />
# DEVICE NAME CONVERSIONS<br />
#<br />
# Linux Grub<br />
# -------------------------<br />
# /dev/fd0 (fd0)<br />
# /dev/sda (hd0)<br />
# /dev/sdb2 (hd1,2)<br />
# /dev/sda3 (hd0,3)<br />
#<br />
<br />
# Timeout for menu<br />
set timeout=5<br />
<br />
# Set default boot entry as Entry 0<br />
set default=0<br />
<br />
# (0) Arch Linux<br />
menuentry "Arch Linux" {<br />
set root=(hd0,1)<br />
linux /vmlinuz-linux root=/dev/sda3 ro<br />
initrd /initramfs-linux.img<br />
}<br />
<br />
## (1) Windows<br />
#menuentry "Windows" {<br />
#set root=(hd0,3)<br />
#chainloader +1<br />
#}<br />
</nowiki>}}<br />
<br />
=== Dual-booting ===<br />
<br />
{{Note|If you want GRUB2 to automatically search for other systems, you may wish to install {{Pkg|os-prober}}.}}<br />
<br />
==== Using grub-mkconfig ====<br />
The best way to add other entries is editing the {{ic|/etc/grub.d/40_custom}}. The entries in this file will be automatically added when running {{ic|grub-mkconfig}}.<br />
After adding the new lines, run:<br />
# grub-mkconfig -o /boot/grub/grub.cfg <br />
to generate an updated {{ic|grub.cfg}}.<br />
<br />
===== With GNU/Linux =====<br />
<br />
Assuming that the other distro is on partition {{ic|sda2}}:<br />
<br />
menuentry "Other Linux" {<br />
set root=(hd0,2)<br />
linux /boot/vmlinuz (add other options here as required)<br />
initrd /boot/initrd.img (if the other kernel uses/needs one)<br />
}<br />
<br />
===== With FreeBSD =====<br />
<br />
Requires that FreeBSD is installed on a single partition with UFS. Assuming it is installed on {{ic|sda4}}:<br />
<br />
menuentry "FreeBSD" {<br />
set root=(hd0,4)<br />
chainloader +1<br />
}<br />
<br />
===== With Windows =====<br />
<br />
This assumes that your Windows partition is {{ic|sda3}}.<br />
<br />
# (2) Windows XP<br />
menuentry "Windows XP" {<br />
set root=(hd0,3)<br />
chainloader (hd0,3)+1<br />
}<br />
<br />
If the Windows bootloader is on an entirely different hard drive than GRUB, it may be necessary to trick Windows into believing that it is the first hard drive. This was possible in GRUB Legacy with {{ic|map}} and is now done with {{ic|drivemap}}. Assuming GRUB is on {{ic|hd0}} and Windows is on {{ic|hd2}}, you need to add the following after {{ic|set root}}:<br />
<br />
drivemap -s hd0 hd2<br />
<br />
==== With Windows via EasyBCD and NeoGRUB ====<br />
<br />
Since EasyBCD's NeoGRUB currently does not understand the GRUB2 menu format, chainload to it by replacing the contents of your {{ic|C:\NST\menu.lst}} file with lines similar to the following:<br />
<br />
default 0<br />
timeout 1<br />
<br />
title Chainload into GRUB v2<br />
root (hd0,7)<br />
kernel /boot/grub/i386-pc/core.img<br />
<br />
===Visual Configuration===<br />
<br />
In GRUB2 it is possible, by default, to change the look of the menu. Make sure to initialize, if not done already, GRUB2 graphical terminal, gfxterm, with proper video mode, gfxmode, in GRUB2. This can be seen in the section [[#Correct_GRUB2_No_Suitable_Mode_Found_Error]]. This video mode is passed by GRUB2 to the linux kernel via 'gfxpayload' so any visual configurations need this mode in order to be in effect.<br />
<br />
====Setting the framebuffer resolution ====<br />
<br />
GRUB2 can set the framebuffer for both GRUB2 itself and the kernel. The old {{ic|1=vga=}} way is deprecated. The preferred method is editing {{ic|/etc/default/grub}} as the following sample:<br />
<br />
GRUB_GFXMODE=1024x768x32<br />
GRUB_GFXPAYLOAD_LINUX=keep<br />
<br />
To generate the changes, run: <br />
grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
The {{ic|gfxpayload}} property will make sure the kernel keeps the resolution.<br />
<br />
{{Note|If this example does not work for you try to replace {{ic|1=gfxmode="1024x768x32"}} by {{ic|1=vbemode="0x105"}}. Remember to replace the specified resolution with one suitable for your screen.}}<br />
{{Note|To show all the modes you can use {{ic|1=# hwinfo --framebuffer}} (hwinfo is available in [community]), while at GRUB2 prompt you can use the {{ic|1=vbeinfo}} command.}}<br />
<br />
If this method does not work for you, the deprecated {{ic|1=vga=}} method will still work. Just<br />
add it next to the {{ic|1="GRUB_CMDLINE_LINUX_DEFAULT="}} line in {{ic|/etc/default/grub}}<br />
for eg: {{ic|1="GRUB_CMDLINE_LINUX_DEFAULT="quiet splash vga=792"}} will give you a {{ic|1024x768}} resolution.<br />
<br />
You can choose one of these resolutions: {{ic|640×480}}, {{ic|800×600}}, {{ic|1024×768}}, {{ic|1280×1024}}, {{ic|1600×1200}}<br />
<br />
====915resolution hack ====<br />
<br />
Some times for Intel graphic adapters neither {{ic|1=# hwinfo --framebuffer}} nor {{ic|1=vbeinfo}} will show you the desired resolution. In this case you can use {{ic|915resolution}} hack. This hack will temporarily modify video BIOS and add needed resolution. See [http://915resolution.mango-lang.org/ 915resolution's home page]<br />
<br />
In the following I will proceed with the example for my system. Please adjust the recipe for your needs. First you need to find a video mode which will be modified later. For that, run {{ic|915resolution}} in GRUB2 command shell:<br />
915resolution -l<br />
The output will be something like:<br />
Intel 800/900 Series VBIOS Hack : version 0.5.3<br />
...<br />
Mode 30 : 640x480, 8 bits/pixel<br />
...<br />
Next, our purpose is to overwrite mode 30. (You can choose what ever mode you want.) In the file {{ic|/etc/grub.d/00_header}} just before the {{ic|set gfxmode&#61;${GRUB_GFXMODE}}} line insert:<br />
915resolution 30 1440 900<br />
Here we are overwriting the mode {{ic|30}} with {{ic|1440x900}} resolution. Lastly we need to set {{ic|GRUB_GFXMODE}} as described earlier, regenerate GRUB2 configuration file and reboot to test changes:<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
# reboot<br />
<br />
====Background image and bitmap fonts====<br />
<br />
GRUB2 comes with support for background images and bitmap fonts in {{ic|pf2}} format. The unifont font is included in the {{Pkg|grub-common}} package under the filename {{ic|unicode.pf2}}, or, as only ASCII characters under the name {{ic|ascii.pf2}}. <br />
<br />
Image formats supported include tga, png and jpeg, providing the correct modules are loaded. The maximum supported resolution depends on your hardware.<br />
<br />
Make sure you have set up the proper [https://wiki.archlinux.org/index.php/GRUB2#Setting_the_framebuffer_resolution framebuffer resolution].<br />
<br />
Edit {{ic|/etc/default/grub}} like this:<br />
GRUB_BACKGROUND="/boot/grub/myimage"<br />
#GRUB_THEME="/path/to/gfxtheme"<br />
<br />
{{Note|If you have installed GRUB on a separate partition, {{ic|/boot/grub/myimage}} becomes {{ic|/grub/myimage}}.}}<br />
<br />
To generate the changes and add the information into {{ic|grub.cfg}}, run: <br />
grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
If adding the splash image was successful, the user will see {{ic|"Found background image..."}} in the terminal as the command is executed. <br />
If this phrase is not seen, the image information was probably not incorporated into the {{ic|grub.cfg}} file.<br />
<br />
If the image is not displayed, check:<br />
* The path and the filename in {{ic|/etc/default/grub}} are correct.<br />
* The image is of the proper size and format (tga, png, 8-bit jpg).<br />
* The image was saved in the RGB mode, and is not indexed.<br />
* The console mode is not enabled in {{ic|/etc/default/grub}}.<br />
* The command {{ic|grub-mkconfig}} must be executed to place the background image information into the {{ic|/boot/grub/grub.cfg}} file.<br />
<br />
====Theme====<br />
<br />
Here is an example for configuring Starfield theme which was included in GRUB2 package.<br />
<br />
Edit {{ic|/etc/default/grub}}<br />
GRUB_THEME="/boot/grub/themes/starfield/theme.txt"<br />
<br />
Generate the changes:<br />
grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
If configuring the theme was successful, you'll see {{ic|Found theme: /boot/grub/themes/starfield/theme.txt}} in the terminal.<br />
Your splash image will usually not displayed when using a theme.<br />
<br />
====Menu colors====<br />
<br />
As in GRUB Legacy (0.9x), you can change the menu colors in GRUB2. The available colors for GRUB2 are at https://www.gnu.org/software/grub/manual/html_node/Theme-file-format.html#Theme-file-format.<br />
Here is an example:<br />
<br />
Edit {{ic|/etc/default/grub}}:<br />
GRUB_COLOR_NORMAL="light-blue/black"<br />
GRUB_COLOR_HIGHLIGHT="light-cyan/blue"<br />
<br />
Generate the changes:<br />
grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
====Hidden menu====<br />
<br />
One of the unique features of GRUB2 is hiding/skipping the menu and showing it by holding {{keypress|Shift}} when needed. You can also adjust whether you want to see the timeout counter.<br />
<br />
Edit {{ic|/etc/default/grub}} as you wish. Here is an example where the comments from the beginning of the two lines have been removed to enable the feature, the timeout has been set to five seconds and to be shown to the user:<br />
GRUB_HIDDEN_TIMEOUT=5<br />
GRUB_HIDDEN_TIMEOUT_QUIET=false<br />
<br />
and run:<br />
grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
=== Other Options ===<br />
<br />
==== LVM ====<br />
<br />
If you use [[LVM]] for your {{ic|/boot}}, add the following before menuentry lines:<br />
<br />
insmod lvm<br />
<br />
and specify your root in the menuentry as:<br />
<br />
set root=(''lvm_group_name''-''lvm_logical_boot_partition_name'')<br />
<br />
Example:<br />
<br />
# (0) Arch Linux<br />
menuentry "Arch Linux" {<br />
insmod lvm<br />
set root=(VolumeGroup-lv_boot)<br />
# you can only set following two lines<br />
linux /vmlinuz-linux root=/dev/mapper/VolumeGroup-root ro<br />
initrd /initramfs-linux.img<br />
}<br />
<br />
==== RAID ====<br />
<br />
GRUB2 provides convenient handling of RAID volumes. You need to add {{ic|insmod raid}} which allows you to address the volume natively. For example, {{ic|/dev/md0}} becomes:<br />
set root=(md0)<br />
<br />
whereas a partitioned RAID volume (e.g. {{ic|/dev/md0p1}}) becomes:<br />
set root=(md0,1)<br />
<br />
==== Persistent block device naming ====<br />
You can use UUIDs to detect partitions instead of the "old" {{ic|/dev/sd*}} and {{ic|/dev/hd*}} scheming. It has the advantage of detecting partitions by their unique UUIDs, which is needed by some people booting with complicated partition setups.<br />
<br />
UUIDs are used by default in the recent versions of GRUB2 - there is no downside in it anyway except that you need to re-generate the {{ic|grub.cfg}} file every time you resize or reformat your partitions. Remember this when modifying partitions with Live-CD.<br />
<br />
The recent versions of GRUB2 use UUIDs by default. You can re-enable the use of UUIDS by simply commenting the UUID line (this is also what it looks like by default):<br />
#GRUB_DISABLE_LINUX_UUID=true<br />
you can also just set the value as {{ic|false}} as shown here:<br />
GRUB_DISABLE_LINUX_UUID=false<br />
<br />
Either way, do not forget to generate the changes:<br />
grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
==== Using Labels ====<br />
<br />
It is possible to use labels, human-readable strings attached to filesystems, by using the {{ic|--label}} option to {{ic|search}}. First of all, label your existing partition:<br />
# tune2fs -L a <LABEL> <PARTITION><br />
<br />
Then, add an entry using labels. An example of this:<br />
<br />
menuentry "Arch Linux, session texte" {<br />
search --label --no-floppy --set=root archroot<br />
linux /boot/vmlinuz-linux root=/dev/disk/by-label/archroot ro<br />
initrd /boot/initramfs-linux.img<br />
}<br />
<br />
==== Recall previous entry ====<br />
<br />
GRUB2 can remember the last entry you booted from and use this as the default entry to boot from next time. This is useful if you have multiple kernels (i.e., the current Arch one and the LTS kernel as a fallback option) or operating systems. To do this, edit {{ic|/etc/default/grub}} and change the setting of {{ic|GRUB_DEFAULT}}:<br />
<br />
GRUB_DEFAULT=saved<br />
<br />
This ensures that GRUB will default to the saved entry. To enable saving the selected entry, add the following line to {{ic|/etc/default/grub}}:<br />
<br />
GRUB_SAVEDEFAULT=true<br />
<br />
{{Note|Manually added menu items, eg Windows in {{ic|/etc/grub.d/40_custom}}, will need {{ic|savedefault}} added. Remember to regenerate your configuration file.}}<br />
<br />
==== Security ====<br />
<br />
If you want to secure GRUB2 so it is not possible for anyone to change boot parameters or use the command line, you can add a user/password combination to GRUB2's configuration files. To do this, run the command {{ic|grub-mkpasswd_pbkdf2}}. Enter a password and confirm it. The output will look like this:<br />
<br />
{{bc|<nowiki><br />
Your PBKDF2 is grub.pbkdf2.sha512.10000.C8ABD3E93C4DFC83138B0C7A3D719BC650E6234310DA069E6FDB0DD4156313DA3D0D9BFFC2846C21D5A2DDA515114CF6378F8A064C94198D0618E70D23717E82.509BFA8A4217EAD0B33C87432524C0B6B64B34FBAD22D3E6E6874D9B101996C5F98AB1746FE7C7199147ECF4ABD8661C222EEEDB7D14A843261FFF2C07B1269A</nowiki>}}Then, add the following to {{ic|/etc/grub.d/00_header}}:<br />
{{bc|<nowiki>cat << EOF<br />
<br />
set superusers="username"<br />
password_pbkdf2 username <password><br />
<br />
EOF</nowiki>}}<br />
where {{ic|<password>}} is the string generated by {{ic|grub-mkpasswd_pbkdf2}}.<br />
<br />
Regenerate your configuration file. Your GRUB2 command line, boot parameters and all boot entries are now protected.<br />
<br />
This can be relaxed and further customized with more users as described in the "Security" part of [https://www.gnu.org/software/grub/manual/grub.html#Security the GRUB manual].<br />
<br />
==== Root Encryption ====<br />
<br />
To let GRUB2 automatically add the kernel parameters for root encryption,<br />
add {{ic|1=cryptdevice=/dev/yourdevice:label}} to {{ic|GRUB_CMDLINE_LINUX}} in {{ic|/etc/defaults/grub}}.<br />
<br />
Example with root mapped to {{ic|/dev/mapper/root}}:<br />
<br />
GRUB_CMDLINE_LINUX="cryptdevice=/dev/sda2:root"<br />
<br />
Also, disable the usage of UUIDs for the rootfs:<br />
<br />
GRUB_DISABLE_LINUX_UUID=true<br />
<br />
Regenerate the configuration.<br />
<br />
=== Booting an ISO Directly From GRUB2 ===<br />
Edit {{ic|/etc/grub.d/40_custom}} to add an entry for the target ISO. When finished, update the GRUB menu as with the usual {{ic|grub-mkconfig -o /boot/grub/grub.cfg}} (as root).<br />
<br />
==== Arch ISO ====<br />
{{Note|Be sure to adjust the {{ic|hdX,Y}} in the third line to point to the correct disk/partition number of the isofile. Also adjust the {{ic|img_dev}} line to match this same location.}}<br />
<br />
menuentry "Archlinux-2011.08.19-netinstall-x86_64.iso" {<br />
set isofile="/archives/archlinux-2011.08.19-netinstall-x86_64.iso"<br />
loopback loop (hd0,7)$isofile<br />
linux (loop)/arch/boot/x86_64/vmlinuz archisolabel=ARCH_201108 img_dev=/dev/sda7 img_loop=$isofile earlymodules=loop<br />
initrd (loop)/arch/boot/x86_64/archiso.img<br />
}<br />
<br />
==== Ubuntu ISO ====<br />
{{Note|Be sure to adjust the {{ic|hdX,Y}} in the third line to point to the correct disk or partition number of the ISO file.}}<br />
<br />
menuentry "ubuntu-12.04-desktop-amd64.iso" {<br />
set isofile="/path/to/ubuntu-12.04-desktop-amd64.iso"<br />
loopback loop (hdX,Y)$isofile<br />
linux (loop)/casper/vmlinuz boot=casper iso-scan/filename=$isofile quiet noeject noprompt splash --<br />
initrd (loop)/casper/initrd.lz<br />
}<br />
<br />
== Using the command shell ==<br />
<br />
Since the MBR is too small to store all GRUB2 modules, only the menu and a few basic commands reside there. The majority of GRUB2 functionality remains in modules in {{ic|/boot/grub}}, which are inserted as needed. In error conditions (e.g. if the partition layout changes) GRUB2 may fail to boot. When this happens, a command shell may appear.<br />
<br />
GRUB2 offers multiple shells/prompts. If there is a problem reading the menu but the bootloader is able to find the disk, you will likely be dropped to the "normal" shell:<br />
sh:grub><br />
<br />
If there is a more serious problem (e.g. GRUB cannot find required files), you may instead be dropped to the "rescue" shell:<br />
grub rescue><br />
<br />
The rescue shell is a restricted subset of the normal shell, offering much less functionality. If dumped to the rescue shell, first try inserting the "normal" module, then starting the "normal" shell:<br />
grub rescue> set prefix=(hdX,Y)/boot/grub<br />
grub rescue> insmod (hdX,Y)/boot/grub/i386-pc/normal.mod<br />
rescue:grub> normal<br />
<br />
=== Pager support ===<br />
<br />
GRUB2 supports pager for reading commands that provide long output (like the help command). This works only in normal shell mode and not in rescue mode. To enable pager, in GRUB2 command shell type:<br />
sh:grub> set pager=1<br />
<br />
== GUI configuration tools ==<br />
<br />
Following package may be installed from [[AUR]]<br />
* [https://aur.archlinux.org/packages.php?ID=44020 grub-customizer] (requires gettext gksu gtkmm hicolor-icon-theme openssl)<br />
*:Customize the bootloader (GRUB2 or BURG)<br />
* [http://kde-apps.org/content/show.php?content=139643 grub2-editor] (requires kdelibs)<br />
*:A KDE4 control module for configuring the GRUB2 bootloader<br />
* [http://kde-apps.org/content/show.php?content=137886 kcm-grub2] (requires kdelibs python2-qt kdebindings-python)<br />
*:This Kcm module manages the most common settings of Grub2.<br />
* [http://sourceforge.net/projects/startup-manager/ startupmanager] (requires gnome-python imagemagick yelp python2 xorg-xrandr)<br />
*:GUI app for changing the settings of GRUB, GRUB2, Usplash and Splashy<br />
<br />
== parttool or legacy hide/unhide ==<br />
<br />
If you have a Windows 9x paradigm with hidden C:\ disks GRUB Legacy had the hide/unhide feature. In GRUB2 this has been replaced by {{ic|parttool}}. For example, to boot the third C:\ disk of three Windows 9x installations on the CLI enter the CLI and:<br />
parttool hd0,1 hidden+ boot-<br />
parttool hd0,2 hidden+ boot-<br />
parttool hd0,3 hidden- boot+<br />
set root=hd0,3<br />
chainloader +1<br />
boot<br />
<br />
== Using the rescue console ==<br />
<br />
See [[#Using the command shell]] first. If unable to activate the standard shell, one possible solution is to boot using a live CD or some other rescue disk to correct configuration errors and reinstall GRUB. However, such a boot disk is not always available (nor necessary); the rescue console is surprisingly robust.<br />
<br />
The available commands in GRUB rescue include {{ic|insmod}}, {{ic|ls}}, {{ic|set}}, and {{ic|unset}}. This example uses {{ic|set}} and {{ic|insmod}}. {{ic|set}} modifies variables and {{ic|insmod}} inserts new modules to add functionality.<br />
<br />
Before starting, the user must know the location of their {{ic|/boot}} partition (be it a separate partition, or a subdirectory under their root):<br />
grub rescue> set prefix=(hdX,Y)/boot/grub<br />
<br />
where X is the physical drive number and Y is the partition number.<br />
<br />
To expand console capabilities, insert the {{ic|linux}} module:<br />
grub rescue> insmod (hdX,Y)/boot/grub/linux.mod<br />
<br />
{{Note|With a separate boot partition, omit {{ic|/boot}} from the path, (i.e. type {{ic|1=set prefix=(hdX,Y)/grub}} and {{ic|insmod (hdX,Y)/grub/linux.mod}}).}}<br />
<br />
This introduces the {{ic|linux}} and {{ic|initrd}} commands, which should be familiar (see [[#Configuration]]).<br />
<br />
An example, booting Arch Linux:<br />
set root=(hd0,5)<br />
linux /boot/vmlinuz-linux root=/dev/sda5<br />
initrd /boot/initramfs-linux.img<br />
boot<br />
<br />
With a separate boot partition, again change the lines accordingly:<br />
set root=(hd0,5)<br />
linux /vmlinuz-linux root=/dev/sda6<br />
initrd /initramfs-linux.img<br />
boot<br />
<br />
After successfully booting the Arch Linux installation, users can correct {{ic|grub.cfg}} as needed and then reinstall GRUB2.<br />
<br />
to reinstall GRUB2 and fix the problem completely, changing {{ic|/dev/sda}} if needed. See [[#Bootloader installation]] for details.<br />
<br />
== Combining the use of UUIDs and basic scripting ==<br />
<br />
If you like the idea of using UUIDs to avoid unreliable BIOS mappings or are struggling with GRUB's syntax, here is an example boot menu item that uses UUIDs and a small script to direct GRUB to the proper disk partitions for your system. All you need to do is replace the UUIDs in the sample with the correct UUIDs for your system. The example applies to a system with a boot and root partition. You will obviously need to modify the GRUB configuration if you have additional partitions:<br />
<br />
menuentry "Arch Linux 64" {<br />
# Set the UUIDs for your boot and root partition respectively<br />
set the_boot_uuid=ece0448f-bb08-486d-9864-ac3271bd8d07<br />
set the_root_uuid=c55da16f-e2af-4603-9e0b-03f5f565ec4a<br />
<br />
# (Note: This may be the same as your boot partition)<br />
<br />
# Get the boot/root devices and set them in the root and grub_boot variables<br />
search --fs-uuid --no-floppy --set=root $the_root_uuid<br />
search --fs-uuid --no-floppy --set=grub_boot $the_boot_uuid<br />
<br />
# Check to see if boot and root are equal.<br />
# If they are, then append /boot to $grub_boot (Since $grub_boot is actually the root partition)<br />
if [ $the_boot_uuid == $the_root_uuid] ; then<br />
set grub_boot=$grub_boot/boot<br />
fi<br />
<br />
# $grub_boot now points to the correct location, so the following will properly find the kernel and initrd<br />
linux ($grub_boot)/vmlinuz-linux root=/dev/disk/by-uuid/$uuid_os_root ro<br />
initrd ($grub_boot)/initramfs-linux.img<br />
}<br />
<br />
== Troubleshooting ==<br />
<br />
Any troubleshooting should be added here.<br />
<br />
=== Enable GRUB2 debug messages ===<br />
<br />
Add:<br />
<br />
set pager=1<br />
set debug=all<br />
<br />
to {{ic|grub.cfg}}.<br />
<br />
=== Correct GRUB2 No Suitable Mode Found Error ===<br />
<br />
If you get this error when booting any menuentry:<br />
<br />
error: no suitable mode found<br />
Booting however<br />
<br />
Then you need to initialize GRUB2 graphical terminal ({{ic|gfxterm}}) with proper video mode ({{ic|gfxmode}}) in GRUB2. This video mode is passed by GRUB2 to the linux kernel via 'gfxpayload'. In case of UEFI systems, if the GRUB2 video mode is not initialized, no kernel boot messages will be shown in the terminal (atleast until KMS kicks in).<br />
<br />
Copy {{ic|/usr/share/grub/unicode.pf2}} to ${GRUB2_PREFIX_DIR} ({{ic|/boot/grub/}} in case of BIOS and UEFI systems). If GRUB2 UEFI was installed with {{ic|1=--boot-directory=/boot/efi/EFI}} set, then the directory is {{ic|/boot/efi/EFI/grub/}}:<br />
<br />
# cp /usr/share/grub/unicode.pf2 ${GRUB2_PREFIX_DIR}<br />
<br />
If {{ic|/usr/share/grub/unicode.pf2}} does not exist, install {{Pkg|bdf-unifont}}, create the {{ic|unifont.pf2}} file and then copy it to {{ic|${GRUB2_PREFIX_DIR<nowiki>}</nowiki>}}:<br />
<br />
# grub-mkfont -o unicode.pf2 /usr/share/fonts/misc/unifont.bdf<br />
<br />
Then, in the {{ic|grub.cfg}} file, add the following lines to enable GRUB2 to pass the video mode correctly to the kernel, without of which you will only get a black screen (no output) but booting (actually) proceeds successfully without any system hang.<br />
<br />
BIOS systems:<br />
<br />
insmod vbe<br />
<br />
UEFI systems:<br />
<br />
insmod efi_gop<br />
insmod efi_uga<br />
<br />
After that add the following code (common to both BIOS and UEFI):<br />
<br />
insmod font<br />
<br />
if loadfont ${prefix}/fonts/unicode.pf2<br />
then<br />
insmod gfxterm<br />
set gfxmode=auto<br />
set gfxpayload=keep<br />
terminal_output gfxterm<br />
fi<br />
<br />
As you can see for gfxterm (graphical terminal) to function properly, {{ic|unicode.pf2}} font file should exist in {{ic|${GRUB2_PREFIX_DIR<nowiki>}</nowiki>}}.<br />
<br />
=== msdos-style error message ===<br />
<br />
grub-setup: warn: This msdos-style partition label has no post-MBR gap; embedding won't be possible!<br />
grub-setup: warn: Embedding is not possible. GRUB can only be installed in this setup by using blocklists.<br />
However, blocklists are UNRELIABLE and its use is discouraged.<br />
grub-setup: error: If you really want blocklists, use --force.<br />
<br />
This error may occur when you try installing GRUB2 in a VMware container. Read more about it [https://bbs.archlinux.org/viewtopic.php?pid=581760#p581760 here]. It happens when the first partition starts just after the MBR (block 63), without the usual space of 1 MiB (2048 blocks) before the first partition. Read [[#MBR_aka_msdos_partitioning_specific_instructions]]<br />
<br />
=== UEFI GRUB2 drops to shell ===<br />
<br />
If GRUB loads but drops you into the rescue shell with no errors, it may be because of a missing or misplaced {{ic|grub.cfg}}. This will happen if GRUB2 UEFI was installed with {{ic|--boot-directory}} and {{ic|grub.cfg}} is missing OR if the partition number of the boot partition changed (which is hard-coded into the {{ic|grubx64.efi}} file).<br />
<br />
=== UEFI GRUB2 not loaded ===<br />
In some cases the EFI may fail to load GRUB correctly. Provided everything is set up correctly, the output of:<br />
efibootmgr -v<br />
might look something like this:<br />
BootCurrent: 0000<br />
Timeout: 3 seconds<br />
BootOrder: 0000,0001,0002<br />
Boot0000* Grub HD(1,800,32000,23532fbb-1bfa-4e46-851a-b494bfe9478c)File(\efi\grub\grub.efi)<br />
Boot0001* Shell HD(1,800,32000,23532fbb-1bfa-4e46-851a-b494bfe9478c)File(\EfiShell.efi)<br />
Boot0002* Festplatte BIOS(2,0,00)P0: SAMSUNG HD204UI<br />
If everything works correctly, the EFI would now automatically load GRUB.<br />
<br />
If the screen only goes black for a second and the next boot option is tried afterwards, according to [https://bbs.archlinux.org/viewtopic.php?pid=981560#p981560 this post], moving GRUB to the partition root can help. The boot option has to be deleted and recreated afterwards. The entry for GRUB should look like this then:<br />
Boot0000* Grub HD(1,800,32000,23532fbb-1bfa-4e46-851a-b494bfe9478c)File(\grub.efi)<br />
<br />
=== Invalid signature ===<br />
If trying to boot Windows results in an "invalid signature" error, e.g. after reconfiguring partitions or adding additional hard drives, (re)move GRUB's device configuration and let it reconfigure:<br />
# mv /boot/grub/device.map /boot/grub/device.map-old<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
{{ic|grub-mkconfig}} should now mention all found boot options, including Windows. If it works, remove {{ic|/boot/grub/device.map-old}}.<br />
<br />
=== Restore GRUB Legacy ===<br />
<br />
* Move GRUB2 files out of the way:<br />
<br />
# mv /boot/grub /boot/grub.nonfunctional<br />
<br />
* Copy GRUB Legacy back to {{ic|/boot}}:<br />
<br />
# cp -af /boot/grub-legacy /boot/grub<br />
<br />
* Replace MBR and next 62 sectors of sda with backed up copy<br />
<br />
{{Warning|This command also restores the partition table, so be careful of overwriting a modified partition table with the old one. It '''will''' mess your system.}}<br />
<br />
# dd if=/path/to/backup/first-sectors of=/dev/sdX bs=512 count=1<br />
<br />
A safer way is to restore only the MBR boot code use:<br />
<br />
# dd if=/path/to/backup/mbr-boot-code of=/dev/sdX bs=446 count=1<br />
<br />
== References ==<br />
<br />
# Official GRUB2 Manual - https://www.gnu.org/software/grub/manual/grub.html<br />
# Ubuntu wiki page for GRUB2 - https://help.ubuntu.com/community/Grub2<br />
# GRUB2 wiki page describing steps to compile for UEFI systems - https://help.ubuntu.com/community/UEFIBooting<br />
# Wikipedia's page on [[Wikipedia:BIOS Boot partition|BIOS Boot partition]]<br />
<br />
== External Links ==<br />
<br />
# [https://github.com/the-ridikulus-rat/My_Shell_Scripts/blob/master/grub/grub_bios.sh A Linux Bash Shell script to compile and install GRUB(2) for BIOS from BZR Source]<br />
# [https://github.com/the-ridikulus-rat/My_Shell_Scripts/blob/master/grub/grub_uefi.sh A Linux Bash Shell script to compile and install GRUB(2) for UEFI from BZR Source]</div>Gilmoreja