https://wiki.archlinux.org/api.php?action=feedcontributions&user=Fylwind&feedformat=atomArchWiki - User contributions [en]2024-03-28T11:55:40ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Haskell&diff=676018Haskell2021-06-07T01:08:10Z<p>Fylwind: /* Static global package database */ (1) Removed reference to ~/.cabal/config modification because it does not work (2) Spliced the path determination command into the examples to improve copy-pastability.</p>
<hr />
<div>[[Category:Programming languages]]<br />
[[ja:Haskell]]<br />
[[ru:Haskell]]<br />
{{Related articles start}}<br />
{{Related|Haskell package guidelines}}<br />
{{Related articles end}}<br />
<br />
From [[Wikipedia:Haskell (programming language)|Wikipedia]]:<br />
:[https://www.haskell.org Haskell] is a general-purpose, statically typed, purely functional programming language with type inference and lazy evaluation. Developed to be suitable for teaching, research and industrial application, Haskell has pioneered a number of advanced programming language features such as type classes, which enable type-safe operator overloading. Haskell's main implementation is the Glasgow Haskell Compiler (GHC). It is named after logician Haskell Curry.<br />
<br />
== Installation ==<br />
<br />
{{Note|There are several choices for Haskell installation, one is supported by Arch Linux, while others are officially supported by Haskell for any Linux distributions. This article describes Arch way of installing and using Haskell. See [[#Alternate installations]] for more information about other installation methods.}}<br />
<br />
Haskell generates machine code that can be run natively on Linux. There is nothing special required to run a binary (already compiled) software, like {{Pkg|xmonad}} or {{Pkg|pandoc}} provided in the [[official repositories]]. On the other side, building [[AUR]] packages or developing software require a compiler and build tools to be installed.<br />
<br />
To install the latest version of Haskell, [[install]] the following packages from the official repositories:<br />
* {{Pkg|ghc}} ([https://www.haskell.org/ghc GHC]) — A Haskell compiler. There are several [https://www.haskell.org/haskellwiki/Implementations implementations] available, but the one used most (which is now ''de facto'' the reference) is the GHC (Glasgow Haskell Compiler).<br />
* {{Pkg|cabal-install}} ([https://www.haskell.org/cabal Cabal]) — A build tool focused on dependency resolution and sources packages from [https://hackage.haskell.org Hackage]. Hackage is the Haskell community's central package archive of open source software.<br />
* {{Pkg|stack}} ([https://www.haskellstack.org Stack]) — A build tool focused on curated snapshots and sources packages from [https://www.stackage.org Stackage]. Stackage is a stable subset of Hackage that provides curated sets (snapshots) of packages known to work well with each other. Alternatively, Stack can be installed through {{AUR|stack-static}} package. It provides statically linked binaries, thereby avoiding dozens of {{ic|haskell-*}} dependencies.<br />
<br />
You can install and configure either Cabal or Stack or both of them. Most of the popular Haskell packages support both Cabal and Stack.<br />
<br />
== Configuration ==<br />
<br />
Since version [https://github.com/archlinux/svntogit-community/commit/7a948cdfb808afd3ce6f93047ae0dc1778e79f9f 8.0.2-1], the Arch {{Pkg|ghc}} package and all [https://archlinux.org/packages/?q=haskell haskell-*] packages in ''community'' provide only dynamically linked libraries. Therefore, to link successfully one must configure GHC, Cabal and Stack for dynamic linking, as the default is to use static linking.<br />
<br />
Using dynamic linking typically results in faster builds and smaller disk and RAM usage (by sharing pages between multiple running Haskell programs), and will free you from troubleshooting cross-GHC mixing errors. But it has its own disadvantage: '''all tools you install from source will break''' on every update of {{Pkg|ghc}}, {{Pkg|ghc-libs}} or [https://archlinux.org/packages/?q=haskell haskell-*] packages since libraries compiled with GHC do not provide a stable [[Wikipedia:Application binary interface|ABI]]. When running such broken binary, you will see the usual message {{ic|error while loading shared libraries: libHS...so: cannot open shared object file: No such file or directory}}. To fix this, just rebuild and reinstall the broken tool in order to relink it to newer libraries.<br />
<br />
On the other hand, static linking is generally easier to maintain and does not force you to rebuild all tools from source after every update of their dependencies. For these reasons, static linking is often the preferred option for local development outside of the package system. If you prefer static linking, see [[#Static linking]] or [[#Alternate installations]] for details.<br />
<br />
{{Note|For a detailed explanation of why Arch moved to dynamic linking for Haskell packages, see this [https://www.reddit.com/r/linux/comments/9emwtu/arch_linux_ama/e5qssdz maintainer's response].}}<br />
<br />
=== Invoking GHC directly ===<br />
<br />
In order to link successfully one must pass the {{ic|-dynamic}} flag to GHC. You can try it with the following file:<br />
<br />
{{hc|Main.hs|2=<br />
main = putStrLn "Hello, World"<br />
}}<br />
<br />
Compile and run it with:<br />
<br />
{{hc|<br />
$ ghc -dynamic Main.hs<br />
$ ./Main|<br />
Hello, World<br />
}}<br />
<br />
=== Configuring Cabal for dynamic linking ===<br />
<br />
First, run the following command to download the latest list of packages from Hackage and create global configuration file {{ic|~/.cabal/config}} (or the file {{ic|$CABAL_CONFIG}} points to):<br />
<br />
$ cabal update<br />
<br />
{{Tip|It is advisable to periodically run {{ic|cabal update}} to synchronize your local list of packages and dependencies with the newest version on Hackage.}}<br />
<br />
To configure Cabal for dynamic linking, uncomment and edit the following options in {{ic|~/.cabal/config}}:<br />
<br />
{{hc|~/.cabal/config|<br />
library-vanilla: False<br />
shared: True<br />
executable-dynamic: True<br />
program-default-options<br />
ghc-options: -dynamic<br />
}}<br />
<br />
* {{ic|library-vanilla: False}} suppresses the creation of static libraries (if your project contains a library).<br />
* {{ic|shared: True}} enables the creation of shared libraries (if your project contains a library).<br />
* {{ic|executable-dynamic: True}} causes dynamic linking to be used for executables (if your project contains executables).<br />
* {{ic|ghc-options: -dynamic}} adds the {{ic|-dynamic}} flag to every invocation of GHC (e.g. if a package has a non-trivial {{ic|Setup.hs}}).<br />
<br />
=== Configuring Stack for dynamic linking ===<br />
<br />
You can use {{ic|stack setup}} command to initialize Stack and create global configuration file {{ic|~/.stack/config.yaml}}. By default Stack will automatically download its own version of GHC to an isolated location upon first invocation. To force Stack to use system GHC installation instead, run {{ic|stack setup}} with {{ic|--system-ghc}} and {{ic|--resolver}} flags:<br />
<br />
$ stack setup --system-ghc --resolver ''resolver''<br />
<br />
Note that you need to specify a resolver which is compatible with your system GHC. Otherwise Stack will happily ignore {{ic|--system-ghc}} flag and download its own copy of GHC. You can determine the version of system GHC using {{ic|ghc --version}} command:<br />
<br />
{{hc|$ ghc --version|<br />
The Glorious Glasgow Haskell Compilation System, version 8.10.2<br />
}}<br />
<br />
Then visit [https://www.stackage.org Stackage] website and pick a suitable Long Term Support (LTS) or nightly snapshot matching your system GHC version. Use the selected snapshot for {{ic|--resolver}} flag on the command line, e.g. {{ic|--resolver lts-16.15}} or {{ic|--resolver nightly-2020-09-01}}.<br />
<br />
Stackage typically lags behind new GHC releases. It may happen that no Stackage snapshot for your system GHC has yet been released. In this case you might want to choose a snapshot for some earlier minor version of GHC or temporarily downgrade your Haskell installation and wait until support for newer GHC releases finally lands on Stackage.<br />
<br />
To configure Stack for dynamic linking, add the following snippet to {{ic|~/.stack/config.yaml}}:<br />
<br />
{{hc|~/.stack/config.yaml|<br />
# Stop downloading GHCs into isolated locations under ~/.stack.<br />
install-ghc: false<br />
<br />
# Allow Stack to pick the system GHC (false by default).<br />
system-ghc: true<br />
<br />
# Allow to use, say, Stackage snapshot for GHC 8.8.2 with system GHC 8.8.3.<br />
compiler-check: newer-minor<br />
<br />
# Add the -dynamic flag to every invocation of GHC.<br />
ghc-options:<br />
"$everything": -dynamic<br />
}}<br />
<br />
== Package management ==<br />
<br />
Most of Haskell libraries and executables are distributed in units of source packages available from Hackage and Stackage.<br />
<br />
As is common in other compiled languages, a number of popular Haskell packages are available from official Arch repositories in pre-built form. Some additional packages can be installed from [[AUR]].<br />
<br />
Although it is recommended to use [[pacman]] to install GHC, libraries and tools from official repositories — at some point you may want to install Haskell packages directly from Hackage/Stackage or compile your own (or somebody else's) packages from source. You will need Cabal or Stack for doing that.<br />
<br />
The following table summarizes the advantages and disadvantages of different package management styles.<br />
<br />
{| class="wikitable"<br />
! '''Method'''<br />
! '''Pros'''<br />
! '''Cons'''<br />
|-<br />
| Official repositories || Provided by Arch Linux developers, consistent versions of packages, already compiled || Not all packages available, only dynamic libraries available<br />
|-<br />
| Cabal || All packages available, root not required || Installed in home directory, failures in dependency resolution, difficult to remove specific packages<br />
|-<br />
| Stack || All packages available (favors Stackage), root not required || Installed in home directory, versions are pinned to snapshot, difficult to remove specific packages<br />
|-<br />
| AUR || Additional packages available || Risk of unmaintained or orphaned packages, incompatible versions of packages possible<br />
|-<br />
|}<br />
<br />
=== Cabal ===<br />
<br />
{{Note|In Haskell, the term ''Cabal'' can refer to either:<br />
* Cabal file format that describes Haskell packages and their dependencies;<br />
* Cabal library that works with Cabal file format;<br />
* {{ic|cabal}} command-line tool (provided by {{Pkg|cabal-install}} package) that uses Cabal library to build Haskell packages.<br />
In the context of this article, ''Cabal'' usually means {{ic|cabal}} command-line tool unless specified otherwise.}}<br />
<br />
Cabal is "the original" build system for Haskell. Most of libraries and tools you can find on Hackage can be installed via Cabal.<br />
<br />
==== Installing packages ====<br />
<br />
To run user-wide executables installed by Cabal, {{ic|~/.cabal/bin}} must be added to the {{ic|$PATH}} environment variable. This can be done by putting the following line in your shell configuration file, for instance {{ic|~/.bashrc}} for {{Pkg|bash}} or {{ic|~/.zshrc}} for {{Pkg|zsh}}:<br />
<br />
export PATH="$HOME/.cabal/bin:$PATH"<br />
<br />
Run the following command to install a Hackage package and all of its dependencies in a single step:<br />
<br />
$ cabal install --ghc-options=-dynamic ''package''<br />
<br />
{{Note|As of October 2020 Cabal [https://github.com/haskell/cabal/issues/6505 ignores] {{ic|ghc-options}} from {{ic|~/.cabal/config}} while building packages with {{ic|build-type: Custom}}. Therefore, it is necessary to specify {{ic|1=--ghc-options=-dynamic}} flag on the command line otherwise you might experience build errors in {{ic|setup.hs}} like {{ic|Could not find module ‘Prelude’ There are files missing in the ‘base-...’ package}}.}}<br />
<br />
You can also build and install a Haskell package from source. To do this, run the following command from the package directory:<br />
<br />
$ cabal install --ghc-options=-dynamic<br />
<br />
Each Cabal package should specify a list of its dependencies and their version constraints in the {{ic|.cabal}} file according to the [https://pvp.haskell.org Package Versioning Policy] (PVP). During the package installation, Cabal tries to find a set of dependencies that satisfies all the constraints. This process is called ''dependency resolution''.<br />
<br />
There are reasons why Stack exists; Cabal is known to generate a lot of friction with beginners. Most of the time dependency resolution works well but sometimes it fails. In this case you will need to figure out the cause of the problem and give Cabal some hints about how to resolve offending dependencies. For example, sometimes it is necessary to say {{ic|1=cabal install --allow-newer --ghc-options=-dynamic ''package''}} to allow Cabal to ignore package's PVP-dictated upper bounds on dependency versions, effectively installing package with newer dependencies than the package author has permitted. It gets hairier for less-well maintained packages; for another example, see [https://groups.google.com/d/msg/idris-lang/h2uWYmqHcc0/5k0jNmQ3BAAJ this thread] about installing Idris (another programming language, written in Haskell), where one had to use both {{ic|--allow-newer}} and {{ic|1=--constraint='haskeline < 0.8.0.0'}} command-line flags to get a successful compile.<br />
<br />
==== Removing packages ====<br />
<br />
There is no easy way to do it. Cabal does not have support for this functionality but there are external tools like [https://github.com/phadej/cabal-extras#cabal-store-gc cabal-store-gc].<br />
<br />
To reinstall the entire user-wide Haskell package system, remove {{ic|~/.cabal}} and {{ic|~/.ghc}} and start from scratch. This is often necessary when GHC is upgraded.<br />
<br />
For more precision, it's possible to use {{ic|ghc-pkg unregister ''package''}} or {{ic|ghc-pkg hide ''package''}}/{{ic|ghc-pkg expose ''package''}} directly on the [https://downloads.haskell.org/ghc/8.10.2/docs/html/users_guide/packages.html#package-databases|''user package database''] — this makes GHC "forget" about an installed package (or pretend it's not there). However neither of these removes any files.<br />
<br />
=== Stack ===<br />
<br />
Stack is another tool to manage Haskell packages. It has slightly different goals than Cabal, with a slightly different philosophy. It uses Cabal library under the hood and integrates with Hackage — but maintains its own repositories of packages (snapshots) on Stackage with the promise that snapshots are curated and include packages which work well together.<br />
<br />
==== Installing packages ====<br />
<br />
In its default configuration, Stack installs compiled executables to {{ic|~/.local/bin}}. Add this directory to the {{ic|$PATH}} environment variable in your shell configuration file, for instance {{ic|~/.bashrc}} for {{Pkg|bash}} or {{ic|~/.zshrc}} for {{Pkg|zsh}}:<br />
<br />
export PATH="$HOME/.local/bin:$PATH"<br />
<br />
Run the following command to download, build and install a Stackage package:<br />
<br />
stack install ''package''<br />
<br />
{{Note|As of October 2020 Stack [https://github.com/commercialhaskell/stack/issues/3409 ignores] {{ic|ghc-options}} from {{ic|~/.stack/config.yaml}} while building {{ic|Setup.hs}}. If you experience build errors in {{ic|Setup.hs}} like {{ic|Could not find module ‘Prelude’ There are files missing in the ‘base-...’ package}}, try to install {{Pkg|ghc-static}} package as a workaround.}}<br />
<br />
You can also build and install a Haskell package from source by running the following command from the package directory:<br />
<br />
stack install --resolver ''resolver''<br />
<br />
Note that you should specify the same resolver as one used for {{ic|stack setup}} command.<br />
<br />
==== Removing packages ====<br />
<br />
Stack does not support the "uninstall" operation.<br />
<br />
If you want to reinstall the entire user-wide Haskell package system, remove {{ic|~/.stack}} directory and start from scratch. This is often necessary when GHC is upgraded.<br />
<br />
== Alternate installations ==<br />
<br />
{{Note|This section describes alternative ways of installing Haskell on Arch without using packages from the official repositories. If you previously installed GHC, Cabal, Stack or any other Haskell packages, make sure to uninstall them first. Remove {{ic|~/.cabal}} and {{ic|~/.stack}} directories if they exist.}}<br />
<br />
There are two officially recommended methods of installing Haskell on any generic Linux distribution: [https://gitlab.haskell.org/haskell/ghcup-hs ghcup] and [https://www.haskellstack.org Stack]. Both methods install statically linked GHC, tools and libraries in your home directory.<br />
<br />
The advantage of using ghcup or Stack instead of Haskell packages from the official repositories is the ability to install and manage multiple versions of GHC side by side. Cabal and Stack installed this way typically work right out of the box without any additional configuration, which might be easier for beginners.<br />
<br />
A completely different way of installing Haskell is [[Nix]] package manager. Nix has a steeper learning curve but offers greater flexibility in managing both Haskell and non-Haskell packages in a reliable and reproducible fashion.<br />
<br />
=== ghcup ===<br />
<br />
ghcup is a command line tool that allows to easily install multiple versions of GHC and switch between them. It is similar in scope to [https://github.com/rust-lang/rustup rustup], [https://github.com/pyenv/pyenv pyenv] and [https://www.jenv.be jenv].<br />
<br />
Install {{AUR|ghcup-hs-bin}} package. Alternatively, you may follow official [https://www.haskell.org/ghcup installation instructions] or manually download [https://downloads.haskell.org/~ghcup ghcup binary] and place it somewhere into your {{ic|$PATH}}.<br />
<br />
By default, ghcup will install GHC executables into {{ic|~/.ghcup/bin}}. You need to add this directory to the {{ic|$PATH}} environment variable in your shell configuration file, for instance {{ic|~/.bashrc}} for {{Pkg|bash}} or {{ic|~/.zshrc}} for {{Pkg|zsh}}. If you want to run executables installed by Cabal, add {{ic|~/.cabal/bin}} to {{ic|$PATH}} as well:<br />
<br />
export PATH="$HOME/.cabal/bin:$HOME/.ghcup/bin:$PATH"<br />
<br />
{{Tip|If you want to use XDG style directories, define {{ic|GHCUP_USE_XDG_DIRS}} environment variable (https://gitlab.haskell.org/haskell/ghcup-hs/#xdg-support).}}<br />
<br />
ghcup provides a convenient TUI which supports most of its functionality:<br />
<br />
$ ghcup tui<br />
<br />
Alternatively, you can use the following CLI commands:<br />
<br />
List available versions of GHC and Cabal:<br />
<br />
$ ghcup list<br />
<br />
Install the recommended version of GHC:<br />
<br />
$ ghcup install ghc<br />
<br />
You can also install a specific version of GHC, for example:<br />
<br />
$ ghcup install ghc 8.10.2<br />
<br />
The commands above do not automatically make GHC available on the {{ic|$PATH}}. You need to select which GHC version to use by default:<br />
<br />
$ ghcup set ghc 8.10.2<br />
<br />
Install the recommended version of Cabal:<br />
<br />
$ ghcup install cabal<br />
<br />
You can now use Cabal to build and install statically linked Haskell executables without any special configuration or command line flags:<br />
<br />
{{bc|<br />
$ cabal update<br />
$ cabal install ''executable''<br />
}}<br />
<br />
To start a new Cabal project:<br />
{{hc|<br />
$ cd /path/to/my-project<br />
$ cabal init<br />
$ cabal build<br />
$ cabal run|<br />
Up to date<br />
Hello, Haskell!<br />
}}<br />
<br />
For more information, refer to official [https://gitlab.haskell.org/haskell/ghcup-hs ghcup] and [https://cabal.readthedocs.io/en/latest Cabal] documentation.<br />
<br />
=== Stack ===<br />
<br />
Install {{AUR|stack-static}} package. Alternatively, you may follow official [https://docs.haskellstack.org/en/stable/install_and_upgrade installation instructions] or manually download [https://github.com/commercialhaskell/stack/releases Stack binary] and place it somewhere into your {{ic|$PATH}}.<br />
<br />
If you want to run executables installed by Stack, add {{ic|~/.local/bin}} directory to the {{ic|$PATH}} environment variable in your shell configuration file, for instance {{ic|~/.bashrc}} for {{Pkg|bash}} or {{ic|~/.zshrc}} for {{Pkg|zsh}}:<br />
<br />
export PATH="$HOME/.local/bin:$PATH"<br />
<br />
Run {{ic|stack setup}} to automatically install GHC from the latest Stackage LTS snapshot:<br />
<br />
$ stack setup<br />
<br />
You can now use Stack to build and install statically linked Haskell packages without any special configuration or command line flags:<br />
<br />
$ stack install ''package''<br />
<br />
For more information, refer to official [https://docs.haskellstack.org/en/stable Stack documentation].<br />
<br />
=== Nix ===<br />
<br />
{{Expansion|I cannot offer a good enough overview, due to no experience with it}}<br />
<br />
== IDE support ==<br />
<br />
=== Tools ===<br />
<br />
==== ghcid ====<br />
<br />
[https://github.com/ndmitchell/ghcid ghcid] provides a simple and robust way to display compiler messages on source code change.<br />
<br />
==== Linters ====<br />
<br />
[https://github.com/ndmitchell/hlint hlint] is a linter, suggesting possible improvements to Haskell code.<br />
<br />
[https://github.com/kowainik/stan stan] is another linter, complementary to hlint. It is in its early stages as of January 2021.<br />
<br />
==== haskell-language-server ====<br />
<br />
[https://github.com/haskell/haskell-language-server haskell-language-server] is a [https://microsoft.github.io/language-server-protocol/ Language Server Protocol] (LSP) implementation for Haskell. It provides IDE-like features like type-on-hover or autocompletions for any editor integrating with the LSP.<br />
<br />
There are pre-built binaries which can be installed via {{AUR|haskell-language-server-bin}}, [[#ghcup]] or by the [https://marketplace.visualstudio.com/items?itemName=haskell.haskell Haskell extension] for [[Visual Studio Code]].<br />
<br />
==== Formatters ====<br />
<br />
{| class="wikitable"<br />
! '''Formatter'''<br />
! '''Notes'''<br />
|-<br />
| [https://github.com/lspitzner/brittany brittany] ||<br />
|-<br />
| [https://github.com/ennocramer/floskell floskell] ||<br />
|-<br />
| [https://github.com/tweag/ormolu ormolu] || not configurable by design<br />
|-<br />
| [https://github.com/parsonsmatt/fourmolu fourmolu] || fork of ormolu, adding configurability<br />
|-<br />
| [https://github.com/jaspervdj/stylish-haskell stylish-haskell]<br />
|-<br />
|}<br />
<br />
=== Editors ===<br />
<br />
{{Expansion|I do not have experience with other editors}}<br />
<br />
==== Emacs ====<br />
<br />
Basic [[Emacs]] support for Haskell is provided by the official [https://github.com/haskell/haskell-mode haskell-mode]. For more advanced features, also use [https://github.com/emacs-lsp/lsp-haskell lsp-haskell] with [[#haskell-language-server]].<br />
<br />
==== Vim ====<br />
<br />
Any [https://vimawesome.com/?q=LSP LSP client] plugin will work with [[#haskell-language-server]].<br />
<br />
==== Visual Studio Code ====<br />
<br />
[[Visual Studio Code]] support is provided by the official [https://marketplace.visualstudio.com/items?itemName=haskell.haskell Haskell plugin].<br />
<br />
== Tips and tricks ==<br />
<br />
=== Static linking ===<br />
<br />
{{Note|This section explains how to build statically linked Haskell packages on Arch, but still use GHC installed from the official repositories. Before you proceed, make sure to remove {{ic|~/.cabal}} and {{ic|~/.stack}} directories if they exist.}}<br />
<br />
{{Note|In the context of this article, static linking does not mean generating completely static ELF binaries. Only Haskell code will be linked statically into a single ELF binary, which may be dynamically linked to other system libraries such as {{Pkg|glibc}}.}}<br />
<br />
To use static linking, one must, at minimum, install the static boot libraries through the {{Pkg|ghc-static}} package. This would allow you to build projects that depend exclusively on the boot libraries as well as on any other libraries that are not installed through the {{ic|haskell-*}} packages from the official repositories.<br />
<br />
Unfortunately, if your project depends on any of dynamically linked {{ic|haskell-*}} packages that you have installed, Cabal does not take the absence of static libraries into account during dependency resolution. As a result, it will try to use the existing {{ic|haskell-*}} package and then fail with [https://bugs.archlinux.org/task/54563#comment158808 linker errors] when it discovers the static libraries are missing:<br />
<br />
Could not find module ‘''SomePackage.SomeModule''’<br />
There are files missing in the ‘''somepackage-0.1.0.0''’ package,<br />
try running 'ghc-pkg check'.<br />
Use -v (or `:set -v` in ghci) to see a list of the files searched for.<br />
<br />
Unlike {{ic|ghc-static}}, there are no “{{ic|haskell-*-static}}” packages available for linkage. There other others ways to work around this issue though, as described in each of the sections below.<br />
<br />
==== Static global package database ====<br />
<br />
A direct [https://www.reddit.com/r/linux/comments/9emwtu/arch_linux_ama/efjnyd6/ approach] is offered by the official {{Pkg|ghc-static}} package, which exposes an alternative "static" global package database at {{ic|/usr/lib/ghc-''version''/static-package.conf.d}}. The static database is limited to only the statically linkable boot packages, therefore if Cabal is reconfigured to use the static database instead of the default database, it would behave as though the dynamic-only {{ic|haskell-*}} packages don't exist.<br />
<br />
The precise path of the static database could be determined at build time using a command such as:<br />
<br />
$ ghc --print-global-package-db | sed 's/\(package\.conf\.d\)$/static-\1/'<br />
/usr/lib/ghc-''version''/static-package.conf.d<br />
<br />
Here's how to enable the static database for use:<br />
<br />
* When building packages with Cabal, one can pass the following flag to limit the selection of global packages to only the boot packages:<br />
<br />
$ cabal configure --ghc-pkg-option="--global-package-db=$(ghc --print-global-package-db | sed 's/\(package\.conf\.d\)$/static-\1/')"<br />
<br />
* When building directly using GHC rather than Cabal, one can pass the following flags to override the global package database:<br />
<br />
$ ghc -clear-package-db -package-db "$(ghc --print-global-package-db | sed 's/\(package\.conf\.d\)$/static-\1/')" -user-package-db ...<br />
<br />
==== ghc-pristine ====<br />
<br />
Install {{AUR|ghc-pristine}} package, which wraps over an existing GHC installation to create a separate GHC distribution in {{ic|/usr/share/ghc-pristine}}, with a package database that contains only boot libraries. This effectively creates a semi-isolated environment without dynamically linked {{ic|haskell-*}} packages, but still makes use of the GHC compiler from the official repositories. Then, to build software with static linking, one simply needs to invoke the wrapped compiler {{ic|/usr/share/ghc-pristine/bin/ghc}}. For Cabal, this amounts to the following configuration in {{ic|~/.cabal/config}}:<br />
<br />
{{hc|~/.cabal/config|<br />
with-compiler: /usr/share/ghc-pristine/bin/ghc<br />
}}<br />
<br />
You can also specify the path to the compiler on a per-project basis by running the following command from the project directory:<br />
<br />
$ cabal configure --with-compiler=/usr/share/ghc-pristine/bin/ghc<br />
<br />
==== cabal-static ====<br />
<br />
Another way to gain back static linking on Arch is to install {{AUR|cabal-static}} package. Unlike the official {{Pkg|cabal-install}}, this one does not pull dynamically linked {{ic|haskell-*}} dependencies from the official repositories and avoids mixing static and shared Haskell libraries installed on the same system. Then you can use Cabal as usual with the following limitation: '''you have to make sure''' that the only other Haskell packages you have installed are {{Pkg|ghc}}, {{Pkg|ghc-libs}} and {{Pkg|ghc-static}} (not {{Pkg|cabal-install}}, {{Pkg|stack}} and none of the {{ic|haskell-*}} packages available in the official repositories).<br />
<br />
==== stack-static ====<br />
<br />
Install {{AUR|stack-static}} package. Similarly to {{ic|cabal-static}} method, make sure that the only other Haskell packages you have installed from the official repositories are {{Pkg|ghc}}, {{Pkg|ghc-libs}} and {{Pkg|ghc-static}}. Then setup Stack to use system GHC as explained in [[#Configuring Stack for dynamic linking]]:<br />
<br />
$ stack setup --system-ghc --resolver ''resolver''<br />
<br />
To make these options permanent, paste the following snippet to {{ic|~/.stack/config.yaml}}:<br />
<br />
{{hc|~/.stack/config.yaml|<br />
# Stop downloading GHCs into isolated locations under ~/.stack.<br />
install-ghc: false<br />
<br />
# Allow Stack to pick the system GHC (false by default).<br />
system-ghc: true<br />
<br />
# Allow to use, say, Stackage snapshot for GHC 8.8.2 with system GHC 8.8.3.<br />
compiler-check: newer-minor<br />
}}<br />
<br />
This configuration will allow you to build statically linked packages as you would normally do, but using system GHC installation instead of GHC provided by Stack.<br />
<br />
==== hpack-static-bin ====<br />
<br />
{{AUR|hpack-static-bin}} provides a statically linked (meaning no haskell-* dependencies) alternative to {{Pkg|haskell-hpack}}. It is precompiled, so no make dependencies are needed.<br />
<br />
==== ghcup ====<br />
<br />
ghcup ([[#ghcup]]) is a tool that can install GHC locally, entirely outside the system package manager. Additionally, it supports multiple versions of GHC side by side. Using the GHC provided by this tool will completely avoid the difficulties associated with static linking since the system GHC is not used at all. It also naturally avoids breakages in locally built libraries caused by upgrades of the system GHC and its boot libraries.<br />
<br />
== See also ==<br />
<br />
*[http://learnyouahaskell.com/ Learn You a Haskell for Great Good!]<br />
*[http://book.realworldhaskell.org/ Real World Haskell]</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Haskell&diff=674846Haskell2021-06-01T01:11:54Z<p>Fylwind: /* Static linking */ Suggest ghcup as alternative</p>
<hr />
<div>[[Category:Programming languages]]<br />
[[ja:Haskell]]<br />
[[ru:Haskell]]<br />
{{Related articles start}}<br />
{{Related|Haskell package guidelines}}<br />
{{Related articles end}}<br />
<br />
From [[Wikipedia:Haskell (programming language)|Wikipedia]]:<br />
:[https://www.haskell.org Haskell] is a general-purpose, statically typed, purely functional programming language with type inference and lazy evaluation. Developed to be suitable for teaching, research and industrial application, Haskell has pioneered a number of advanced programming language features such as type classes, which enable type-safe operator overloading. Haskell's main implementation is the Glasgow Haskell Compiler (GHC). It is named after logician Haskell Curry.<br />
<br />
== Installation ==<br />
<br />
{{Note|There are several choices for Haskell installation, one is supported by Arch Linux, while others are officially supported by Haskell for any Linux distributions. This article describes Arch way of installing and using Haskell. See [[#Alternate installations]] for more information about other installation methods.}}<br />
<br />
Haskell generates machine code that can be run natively on Linux. There is nothing special required to run a binary (already compiled) software, like {{Pkg|xmonad}} or {{Pkg|pandoc}} provided in the [[official repositories]]. On the other side, building [[AUR]] packages or developing software require a compiler and build tools to be installed.<br />
<br />
To install the latest version of Haskell, [[install]] the following packages from the official repositories:<br />
* {{Pkg|ghc}} ([https://www.haskell.org/ghc GHC]) — A Haskell compiler. There are several [https://www.haskell.org/haskellwiki/Implementations implementations] available, but the one used most (which is now ''de facto'' the reference) is the GHC (Glasgow Haskell Compiler).<br />
* {{Pkg|cabal-install}} ([https://www.haskell.org/cabal Cabal]) — A build tool focused on dependency resolution and sources packages from [https://hackage.haskell.org Hackage]. Hackage is the Haskell community's central package archive of open source software.<br />
* {{Pkg|stack}} ([https://www.haskellstack.org Stack]) — A build tool focused on curated snapshots and sources packages from [https://www.stackage.org Stackage]. Stackage is a stable subset of Hackage that provides curated sets (snapshots) of packages known to work well with each other. Alternatively, Stack can be installed through {{AUR|stack-static}} package. It provides statically linked binaries, thereby avoiding dozens of {{ic|haskell-*}} dependencies.<br />
<br />
You can install and configure either Cabal or Stack or both of them. Most of the popular Haskell packages support both Cabal and Stack.<br />
<br />
== Configuration ==<br />
<br />
Since version [https://github.com/archlinux/svntogit-community/commit/7a948cdfb808afd3ce6f93047ae0dc1778e79f9f 8.0.2-1], the Arch {{Pkg|ghc}} package and all [https://archlinux.org/packages/?q=haskell haskell-*] packages in ''community'' provide only dynamically linked libraries. Therefore, to link successfully one must configure GHC, Cabal and Stack for dynamic linking, as the default is to use static linking.<br />
<br />
Using dynamic linking typically results in faster builds and smaller disk and RAM usage (by sharing pages between multiple running Haskell programs), and will free you from troubleshooting cross-GHC mixing errors. But it has its own disadvantage: '''all tools you install from source will break''' on every update of {{Pkg|ghc}}, {{Pkg|ghc-libs}} or [https://archlinux.org/packages/?q=haskell haskell-*] packages since libraries compiled with GHC do not provide a stable [[Wikipedia:Application binary interface|ABI]]. When running such broken binary, you will see the usual message {{ic|error while loading shared libraries: libHS...so: cannot open shared object file: No such file or directory}}. To fix this, just rebuild and reinstall the broken tool in order to relink it to newer libraries.<br />
<br />
On the other hand, static linking is generally easier to maintain and does not force you to rebuild all tools from source after every update of their dependencies. For these reasons, static linking is often the preferred option for local development outside of the package system. If you prefer static linking, see [[#Static linking]] or [[#Alternate installations]] for details.<br />
<br />
{{Note|For a detailed explanation of why Arch moved to dynamic linking for Haskell packages, see this [https://www.reddit.com/r/linux/comments/9emwtu/arch_linux_ama/e5qssdz maintainer's response].}}<br />
<br />
=== Invoking GHC directly ===<br />
<br />
In order to link successfully one must pass the {{ic|-dynamic}} flag to GHC. You can try it with the following file:<br />
<br />
{{hc|Main.hs|2=<br />
main = putStrLn "Hello, World"<br />
}}<br />
<br />
Compile and run it with:<br />
<br />
{{hc|<br />
$ ghc -dynamic Main.hs<br />
$ ./Main|<br />
Hello, World<br />
}}<br />
<br />
=== Configuring Cabal for dynamic linking ===<br />
<br />
First, run the following command to download the latest list of packages from Hackage and create global configuration file {{ic|~/.cabal/config}} (or the file {{ic|$CABAL_CONFIG}} points to):<br />
<br />
$ cabal update<br />
<br />
{{Tip|It is advisable to periodically run {{ic|cabal update}} to synchronize your local list of packages and dependencies with the newest version on Hackage.}}<br />
<br />
To configure Cabal for dynamic linking, uncomment and edit the following options in {{ic|~/.cabal/config}}:<br />
<br />
{{hc|~/.cabal/config|<br />
library-vanilla: False<br />
shared: True<br />
executable-dynamic: True<br />
program-default-options<br />
ghc-options: -dynamic<br />
}}<br />
<br />
* {{ic|library-vanilla: False}} suppresses the creation of static libraries (if your project contains a library).<br />
* {{ic|shared: True}} enables the creation of shared libraries (if your project contains a library).<br />
* {{ic|executable-dynamic: True}} causes dynamic linking to be used for executables (if your project contains executables).<br />
* {{ic|ghc-options: -dynamic}} adds the {{ic|-dynamic}} flag to every invocation of GHC (e.g. if a package has a non-trivial {{ic|Setup.hs}}).<br />
<br />
=== Configuring Stack for dynamic linking ===<br />
<br />
You can use {{ic|stack setup}} command to initialize Stack and create global configuration file {{ic|~/.stack/config.yaml}}. By default Stack will automatically download its own version of GHC to an isolated location upon first invocation. To force Stack to use system GHC installation instead, run {{ic|stack setup}} with {{ic|--system-ghc}} and {{ic|--resolver}} flags:<br />
<br />
$ stack setup --system-ghc --resolver ''resolver''<br />
<br />
Note that you need to specify a resolver which is compatible with your system GHC. Otherwise Stack will happily ignore {{ic|--system-ghc}} flag and download its own copy of GHC. You can determine the version of system GHC using {{ic|ghc --version}} command:<br />
<br />
{{hc|$ ghc --version|<br />
The Glorious Glasgow Haskell Compilation System, version 8.10.2<br />
}}<br />
<br />
Then visit [https://www.stackage.org Stackage] website and pick a suitable Long Term Support (LTS) or nightly snapshot matching your system GHC version. Use the selected snapshot for {{ic|--resolver}} flag on the command line, e.g. {{ic|--resolver lts-16.15}} or {{ic|--resolver nightly-2020-09-01}}.<br />
<br />
Stackage typically lags behind new GHC releases. It may happen that no Stackage snapshot for your system GHC has yet been released. In this case you might want to choose a snapshot for some earlier minor version of GHC or temporarily downgrade your Haskell installation and wait until support for newer GHC releases finally lands on Stackage.<br />
<br />
To configure Stack for dynamic linking, add the following snippet to {{ic|~/.stack/config.yaml}}:<br />
<br />
{{hc|~/.stack/config.yaml|<br />
# Stop downloading GHCs into isolated locations under ~/.stack.<br />
install-ghc: false<br />
<br />
# Allow Stack to pick the system GHC (false by default).<br />
system-ghc: true<br />
<br />
# Allow to use, say, Stackage snapshot for GHC 8.8.2 with system GHC 8.8.3.<br />
compiler-check: newer-minor<br />
<br />
# Add the -dynamic flag to every invocation of GHC.<br />
ghc-options:<br />
"$everything": -dynamic<br />
}}<br />
<br />
== Package management ==<br />
<br />
Most of Haskell libraries and executables are distributed in units of source packages available from Hackage and Stackage.<br />
<br />
As is common in other compiled languages, a number of popular Haskell packages are available from official Arch repositories in pre-built form. Some additional packages can be installed from [[AUR]].<br />
<br />
Although it is recommended to use [[pacman]] to install GHC, libraries and tools from official repositories — at some point you may want to install Haskell packages directly from Hackage/Stackage or compile your own (or somebody else's) packages from source. You will need Cabal or Stack for doing that.<br />
<br />
The following table summarizes the advantages and disadvantages of different package management styles.<br />
<br />
{| class="wikitable"<br />
! '''Method'''<br />
! '''Pros'''<br />
! '''Cons'''<br />
|-<br />
| Official repositories || Provided by Arch Linux developers, consistent versions of packages, already compiled || Not all packages available, only dynamic libraries available<br />
|-<br />
| Cabal || All packages available, root not required || Installed in home directory, failures in dependency resolution, difficult to remove specific packages<br />
|-<br />
| Stack || All packages available (favors Stackage), root not required || Installed in home directory, versions are pinned to snapshot, difficult to remove specific packages<br />
|-<br />
| AUR || Additional packages available || Risk of unmaintained or orphaned packages, incompatible versions of packages possible<br />
|-<br />
|}<br />
<br />
=== Cabal ===<br />
<br />
{{Note|In Haskell, the term ''Cabal'' can refer to either:<br />
* Cabal file format that describes Haskell packages and their dependencies;<br />
* Cabal library that works with Cabal file format;<br />
* {{ic|cabal}} command-line tool (provided by {{Pkg|cabal-install}} package) that uses Cabal library to build Haskell packages.<br />
In the context of this article, ''Cabal'' usually means {{ic|cabal}} command-line tool unless specified otherwise.}}<br />
<br />
Cabal is "the original" build system for Haskell. Most of libraries and tools you can find on Hackage can be installed via Cabal.<br />
<br />
==== Installing packages ====<br />
<br />
To run user-wide executables installed by Cabal, {{ic|~/.cabal/bin}} must be added to the {{ic|$PATH}} environment variable. This can be done by putting the following line in your shell configuration file, for instance {{ic|~/.bashrc}} for {{Pkg|bash}} or {{ic|~/.zshrc}} for {{Pkg|zsh}}:<br />
<br />
export PATH="$HOME/.cabal/bin:$PATH"<br />
<br />
Run the following command to install a Hackage package and all of its dependencies in a single step:<br />
<br />
$ cabal install --ghc-options=-dynamic ''package''<br />
<br />
{{Note|As of October 2020 Cabal [https://github.com/haskell/cabal/issues/6505 ignores] {{ic|ghc-options}} from {{ic|~/.cabal/config}} while building packages with {{ic|build-type: Custom}}. Therefore, it is necessary to specify {{ic|1=--ghc-options=-dynamic}} flag on the command line otherwise you might experience build errors in {{ic|setup.hs}} like {{ic|Could not find module ‘Prelude’ There are files missing in the ‘base-...’ package}}.}}<br />
<br />
You can also build and install a Haskell package from source. To do this, run the following command from the package directory:<br />
<br />
$ cabal install --ghc-options=-dynamic<br />
<br />
Each Cabal package should specify a list of its dependencies and their version constraints in the {{ic|.cabal}} file according to the [https://pvp.haskell.org Package Versioning Policy] (PVP). During the package installation, Cabal tries to find a set of dependencies that satisfies all the constraints. This process is called ''dependency resolution''.<br />
<br />
There are reasons why Stack exists; Cabal is known to generate a lot of friction with beginners. Most of the time dependency resolution works well but sometimes it fails. In this case you will need to figure out the cause of the problem and give Cabal some hints about how to resolve offending dependencies. For example, sometimes it is necessary to say {{ic|1=cabal install --allow-newer --ghc-options=-dynamic ''package''}} to allow Cabal to ignore package's PVP-dictated upper bounds on dependency versions, effectively installing package with newer dependencies than the package author has permitted. It gets hairier for less-well maintained packages; for another example, see [https://groups.google.com/d/msg/idris-lang/h2uWYmqHcc0/5k0jNmQ3BAAJ this thread] about installing Idris (another programming language, written in Haskell), where one had to use both {{ic|--allow-newer}} and {{ic|1=--constraint='haskeline < 0.8.0.0'}} command-line flags to get a successful compile.<br />
<br />
==== Removing packages ====<br />
<br />
There is no easy way to do it. Cabal does not have support for this functionality but there are external tools like [https://github.com/phadej/cabal-extras#cabal-store-gc cabal-store-gc].<br />
<br />
To reinstall the entire user-wide Haskell package system, remove {{ic|~/.cabal}} and {{ic|~/.ghc}} and start from scratch. This is often necessary when GHC is upgraded.<br />
<br />
For more precision, it's possible to use {{ic|ghc-pkg unregister ''package''}} or {{ic|ghc-pkg hide ''package''}}/{{ic|ghc-pkg expose ''package''}} directly on the [https://downloads.haskell.org/ghc/8.10.2/docs/html/users_guide/packages.html#package-databases|''user package database''] — this makes GHC "forget" about an installed package (or pretend it's not there). However neither of these removes any files.<br />
<br />
=== Stack ===<br />
<br />
Stack is another tool to manage Haskell packages. It has slightly different goals than Cabal, with a slightly different philosophy. It uses Cabal library under the hood and integrates with Hackage — but maintains its own repositories of packages (snapshots) on Stackage with the promise that snapshots are curated and include packages which work well together.<br />
<br />
==== Installing packages ====<br />
<br />
In its default configuration, Stack installs compiled executables to {{ic|~/.local/bin}}. Add this directory to the {{ic|$PATH}} environment variable in your shell configuration file, for instance {{ic|~/.bashrc}} for {{Pkg|bash}} or {{ic|~/.zshrc}} for {{Pkg|zsh}}:<br />
<br />
export PATH="$HOME/.local/bin:$PATH"<br />
<br />
Run the following command to download, build and install a Stackage package:<br />
<br />
stack install ''package''<br />
<br />
{{Note|As of October 2020 Stack [https://github.com/commercialhaskell/stack/issues/3409 ignores] {{ic|ghc-options}} from {{ic|~/.stack/config.yaml}} while building {{ic|Setup.hs}}. If you experience build errors in {{ic|Setup.hs}} like {{ic|Could not find module ‘Prelude’ There are files missing in the ‘base-...’ package}}, try to install {{Pkg|ghc-static}} package as a workaround.}}<br />
<br />
You can also build and install a Haskell package from source by running the following command from the package directory:<br />
<br />
stack install --resolver ''resolver''<br />
<br />
Note that you should specify the same resolver as one used for {{ic|stack setup}} command.<br />
<br />
==== Removing packages ====<br />
<br />
Stack does not support the "uninstall" operation.<br />
<br />
If you want to reinstall the entire user-wide Haskell package system, remove {{ic|~/.stack}} directory and start from scratch. This is often necessary when GHC is upgraded.<br />
<br />
== Alternate installations ==<br />
<br />
{{Note|This section describes alternative ways of installing Haskell on Arch without using packages from the official repositories. If you previously installed GHC, Cabal, Stack or any other Haskell packages, make sure to uninstall them first. Remove {{ic|~/.cabal}} and {{ic|~/.stack}} directories if they exist.}}<br />
<br />
There are two officially recommended methods of installing Haskell on any generic Linux distribution: [https://gitlab.haskell.org/haskell/ghcup-hs ghcup] and [https://www.haskellstack.org Stack]. Both methods install statically linked GHC, tools and libraries in your home directory.<br />
<br />
The advantage of using ghcup or Stack instead of Haskell packages from the official repositories is the ability to install and manage multiple versions of GHC side by side. Cabal and Stack installed this way typically work right out of the box without any additional configuration, which might be easier for beginners.<br />
<br />
A completely different way of installing Haskell is [[Nix]] package manager. Nix has a steeper learning curve but offers greater flexibility in managing both Haskell and non-Haskell packages in a reliable and reproducible fashion.<br />
<br />
=== ghcup ===<br />
<br />
ghcup is a command line tool that allows to easily install multiple versions of GHC and switch between them. It is similar in scope to [https://github.com/rust-lang/rustup rustup], [https://github.com/pyenv/pyenv pyenv] and [https://www.jenv.be jenv].<br />
<br />
Install {{AUR|ghcup-hs-bin}} package. Alternatively, you may follow official [https://www.haskell.org/ghcup installation instructions] or manually download [https://downloads.haskell.org/~ghcup ghcup binary] and place it somewhere into your {{ic|$PATH}}.<br />
<br />
By default, ghcup will install GHC executables into {{ic|~/.ghcup/bin}}. You need to add this directory to the {{ic|$PATH}} environment variable in your shell configuration file, for instance {{ic|~/.bashrc}} for {{Pkg|bash}} or {{ic|~/.zshrc}} for {{Pkg|zsh}}. If you want to run executables installed by Cabal, add {{ic|~/.cabal/bin}} to {{ic|$PATH}} as well:<br />
<br />
export PATH="$HOME/.cabal/bin:$HOME/.ghcup/bin:$PATH"<br />
<br />
{{Tip|If you want to use XDG style directories, define {{ic|GHCUP_USE_XDG_DIRS}} environment variable (https://gitlab.haskell.org/haskell/ghcup-hs/#xdg-support).}}<br />
<br />
ghcup provides a convenient TUI which supports most of its functionality:<br />
<br />
$ ghcup tui<br />
<br />
Alternatively, you can use the following CLI commands:<br />
<br />
List available versions of GHC and Cabal:<br />
<br />
$ ghcup list<br />
<br />
Install the recommended version of GHC:<br />
<br />
$ ghcup install ghc<br />
<br />
You can also install a specific version of GHC, for example:<br />
<br />
$ ghcup install ghc 8.10.2<br />
<br />
The commands above do not automatically make GHC available on the {{ic|$PATH}}. You need to select which GHC version to use by default:<br />
<br />
$ ghcup set ghc 8.10.2<br />
<br />
Install the recommended version of Cabal:<br />
<br />
$ ghcup install cabal<br />
<br />
You can now use Cabal to build and install statically linked Haskell executables without any special configuration or command line flags:<br />
<br />
{{bc|<br />
$ cabal update<br />
$ cabal install ''executable''<br />
}}<br />
<br />
To start a new Cabal project:<br />
{{hc|<br />
$ cd /path/to/my-project<br />
$ cabal init<br />
$ cabal build<br />
$ cabal run|<br />
Up to date<br />
Hello, Haskell!<br />
}}<br />
<br />
For more information, refer to official [https://gitlab.haskell.org/haskell/ghcup-hs ghcup] and [https://cabal.readthedocs.io/en/latest Cabal] documentation.<br />
<br />
=== Stack ===<br />
<br />
Install {{AUR|stack-static}} package. Alternatively, you may follow official [https://docs.haskellstack.org/en/stable/install_and_upgrade installation instructions] or manually download [https://github.com/commercialhaskell/stack/releases Stack binary] and place it somewhere into your {{ic|$PATH}}.<br />
<br />
If you want to run executables installed by Stack, add {{ic|~/.local/bin}} directory to the {{ic|$PATH}} environment variable in your shell configuration file, for instance {{ic|~/.bashrc}} for {{Pkg|bash}} or {{ic|~/.zshrc}} for {{Pkg|zsh}}:<br />
<br />
export PATH="$HOME/.local/bin:$PATH"<br />
<br />
Run {{ic|stack setup}} to automatically install GHC from the latest Stackage LTS snapshot:<br />
<br />
$ stack setup<br />
<br />
You can now use Stack to build and install statically linked Haskell packages without any special configuration or command line flags:<br />
<br />
$ stack install ''package''<br />
<br />
For more information, refer to official [https://docs.haskellstack.org/en/stable Stack documentation].<br />
<br />
=== Nix ===<br />
<br />
{{Expansion|I cannot offer a good enough overview, due to no experience with it}}<br />
<br />
== IDE support ==<br />
<br />
=== Tools ===<br />
<br />
==== ghcid ====<br />
<br />
[https://github.com/ndmitchell/ghcid ghcid] provides a simple and robust way to display compiler messages on source code change.<br />
<br />
==== Linters ====<br />
<br />
[https://github.com/ndmitchell/hlint hlint] is a linter, suggesting possible improvements to Haskell code.<br />
<br />
[https://github.com/kowainik/stan stan] is another linter, complementary to hlint. It is in its early stages as of January 2021.<br />
<br />
==== haskell-language-server ====<br />
<br />
[https://github.com/haskell/haskell-language-server haskell-language-server] is a [https://microsoft.github.io/language-server-protocol/ Language Server Protocol] (LSP) implementation for Haskell. It provides IDE-like features like type-on-hover or autocompletions for any editor integrating with the LSP.<br />
<br />
There are pre-built binaries which can be installed via {{AUR|haskell-language-server-bin}}, [[#ghcup]] or by the [https://marketplace.visualstudio.com/items?itemName=haskell.haskell Haskell extension] for [[Visual Studio Code]].<br />
<br />
==== Formatters ====<br />
<br />
{| class="wikitable"<br />
! '''Formatter'''<br />
! '''Notes'''<br />
|-<br />
| [https://github.com/lspitzner/brittany brittany] ||<br />
|-<br />
| [https://github.com/ennocramer/floskell floskell] ||<br />
|-<br />
| [https://github.com/tweag/ormolu ormolu] || not configurable by design<br />
|-<br />
| [https://github.com/parsonsmatt/fourmolu fourmolu] || fork of ormolu, adding configurability<br />
|-<br />
| [https://github.com/jaspervdj/stylish-haskell stylish-haskell]<br />
|-<br />
|}<br />
<br />
=== Editors ===<br />
<br />
{{Expansion|I do not have experience with other editors}}<br />
<br />
==== Emacs ====<br />
<br />
Basic [[Emacs]] support for Haskell is provided by the official [https://github.com/haskell/haskell-mode haskell-mode]. For more advanced features, also use [https://github.com/emacs-lsp/lsp-haskell lsp-haskell] with [[#haskell-language-server]].<br />
<br />
==== Vim ====<br />
<br />
Any [https://vimawesome.com/?q=LSP LSP client] plugin will work with [[#haskell-language-server]].<br />
<br />
==== Visual Studio Code ====<br />
<br />
[[Visual Studio Code]] support is provided by the official [https://marketplace.visualstudio.com/items?itemName=haskell.haskell Haskell plugin].<br />
<br />
== Tips and tricks ==<br />
<br />
=== Static linking ===<br />
<br />
{{Note|This section explains how to build statically linked Haskell packages on Arch, but still use GHC installed from the official repositories. Before you proceed, make sure to remove {{ic|~/.cabal}} and {{ic|~/.stack}} directories if they exist.}}<br />
<br />
{{Note|In the context of this article, static linking does not mean generating completely static ELF binaries. Only Haskell code will be linked statically into a single ELF binary, which may be dynamically linked to other system libraries such as {{Pkg|glibc}}.}}<br />
<br />
To use static linking, one must, at minimum, install the static boot libraries through the {{Pkg|ghc-static}} package. This would allow you to build projects that depend exclusively on the boot libraries as well as on any other libraries that are not installed through the {{ic|haskell-*}} packages from the official repositories.<br />
<br />
Unfortunately, if your project depends on any of dynamically linked {{ic|haskell-*}} packages that you have installed, Cabal does not take the absence of static libraries into account during dependency resolution. As a result, it will try to use the existing {{ic|haskell-*}} package and then fail with [https://bugs.archlinux.org/task/54563#comment158808 linker errors] when it discovers the static libraries are missing:<br />
<br />
Could not find module ‘''SomePackage.SomeModule''’<br />
There are files missing in the ‘''somepackage-0.1.0.0''’ package,<br />
try running 'ghc-pkg check'.<br />
Use -v (or `:set -v` in ghci) to see a list of the files searched for.<br />
<br />
Unlike {{ic|ghc-static}}, there are no “{{ic|haskell-*-static}}” packages available for linkage. There other others ways to work around this issue though, as described in each of the sections below.<br />
<br />
==== Static global package database ====<br />
<br />
A direct [https://www.reddit.com/r/linux/comments/9emwtu/arch_linux_ama/efjnyd6/ approach] is offered by the official {{Pkg|ghc-static}} package, which exposes an alternative "static" global package database at {{ic|/usr/lib/ghc-''version''/static-package.conf.d}}. The static database is limited to only the statically linkable boot packages, therefore if Cabal is reconfigured to use the static database instead of the default database, it would behave as though the dynamic-only {{ic|haskell-*}} packages don't exist.<br />
<br />
The precise path of the static database could be determined at build time using a command such as:<br />
<br />
$ ghc --print-global-package-db | sed 's/\(package\.conf\.d\)$/static-\1/'<br />
<br />
Here's how to enable the static database for use:<br />
<br />
* When building packages with Cabal, one can pass the following flag to limit the selection of global packages to only the boot packages:<br />
<br />
$ cabal configure --ghc-pkg-option=--global-package-db=/usr/lib/ghc-''version''/static-package.conf.d<br />
<br />
* This can be configured account-wide by editing {{ic|~/.cabal/config}}:<br />
<br />
{{hc|~/.cabal/config|2=<br />
program-default-options<br />
ghc-pkg-options: --global-package-db=/usr/lib/ghc-''version''/static-package.conf.d<br />
}}<br />
<br />
* When building directly using GHC rather than Cabal, one can pass the following flags to override the global package database:<br />
<br />
$ ghc -clear-package-db -package-db /usr/lib/ghc-''version''/static-package.conf.d -user-package-db ...<br />
<br />
==== ghc-pristine ====<br />
<br />
Install {{AUR|ghc-pristine}} package, which wraps over an existing GHC installation to create a separate GHC distribution in {{ic|/usr/share/ghc-pristine}}, with a package database that contains only boot libraries. This effectively creates a semi-isolated environment without dynamically linked {{ic|haskell-*}} packages, but still makes use of the GHC compiler from the official repositories. Then, to build software with static linking, one simply needs to invoke the wrapped compiler {{ic|/usr/share/ghc-pristine/bin/ghc}}. For Cabal, this amounts to the following configuration in {{ic|~/.cabal/config}}:<br />
<br />
{{hc|~/.cabal/config|<br />
with-compiler: /usr/share/ghc-pristine/bin/ghc<br />
}}<br />
<br />
You can also specify the path to the compiler on a per-project basis by running the following command from the project directory:<br />
<br />
$ cabal configure --with-compiler=/usr/share/ghc-pristine/bin/ghc<br />
<br />
==== cabal-static ====<br />
<br />
Another way to gain back static linking on Arch is to install {{AUR|cabal-static}} package. Unlike the official {{Pkg|cabal-install}}, this one does not pull dynamically linked {{ic|haskell-*}} dependencies from the official repositories and avoids mixing static and shared Haskell libraries installed on the same system. Then you can use Cabal as usual with the following limitation: '''you have to make sure''' that the only other Haskell packages you have installed are {{Pkg|ghc}}, {{Pkg|ghc-libs}} and {{Pkg|ghc-static}} (not {{Pkg|cabal-install}}, {{Pkg|stack}} and none of the {{ic|haskell-*}} packages available in the official repositories).<br />
<br />
==== stack-static ====<br />
<br />
Install {{AUR|stack-static}} package. Similarly to {{ic|cabal-static}} method, make sure that the only other Haskell packages you have installed from the official repositories are {{Pkg|ghc}}, {{Pkg|ghc-libs}} and {{Pkg|ghc-static}}. Then setup Stack to use system GHC as explained in [[#Configuring Stack for dynamic linking]]:<br />
<br />
$ stack setup --system-ghc --resolver ''resolver''<br />
<br />
To make these options permanent, paste the following snippet to {{ic|~/.stack/config.yaml}}:<br />
<br />
{{hc|~/.stack/config.yaml|<br />
# Stop downloading GHCs into isolated locations under ~/.stack.<br />
install-ghc: false<br />
<br />
# Allow Stack to pick the system GHC (false by default).<br />
system-ghc: true<br />
<br />
# Allow to use, say, Stackage snapshot for GHC 8.8.2 with system GHC 8.8.3.<br />
compiler-check: newer-minor<br />
}}<br />
<br />
This configuration will allow you to build statically linked packages as you would normally do, but using system GHC installation instead of GHC provided by Stack.<br />
<br />
==== hpack-static-bin ====<br />
<br />
{{AUR|hpack-static-bin}} provides a statically linked (meaning no haskell-* dependencies) alternative to {{Pkg|haskell-hpack}}. It is precompiled, so no make dependencies are needed.<br />
<br />
==== ghcup ====<br />
<br />
ghcup ({{AUR|ghcup-hs-bin}}) is a tool that can install GHC locally, entirely outside the system package manager. Additionally, it supports multiple versions of GHC side by side. Using the GHC provided by this tool will completely avoid the difficulties associated with static linking since the system GHC is not used at all. It also naturally avoids breakages in locally built libraries caused by upgrades of the system GHC and its boot libraries.<br />
<br />
== See also ==<br />
<br />
*[http://learnyouahaskell.com/ Learn You a Haskell for Great Good!]<br />
*[http://book.realworldhaskell.org/ Real World Haskell]</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Haskell&diff=674845Haskell2021-06-01T00:53:39Z<p>Fylwind: /* Static linking */ Describe a new, more direct approach offered by ghc-static</p>
<hr />
<div>[[Category:Programming languages]]<br />
[[ja:Haskell]]<br />
[[ru:Haskell]]<br />
{{Related articles start}}<br />
{{Related|Haskell package guidelines}}<br />
{{Related articles end}}<br />
<br />
From [[Wikipedia:Haskell (programming language)|Wikipedia]]:<br />
:[https://www.haskell.org Haskell] is a general-purpose, statically typed, purely functional programming language with type inference and lazy evaluation. Developed to be suitable for teaching, research and industrial application, Haskell has pioneered a number of advanced programming language features such as type classes, which enable type-safe operator overloading. Haskell's main implementation is the Glasgow Haskell Compiler (GHC). It is named after logician Haskell Curry.<br />
<br />
== Installation ==<br />
<br />
{{Note|There are several choices for Haskell installation, one is supported by Arch Linux, while others are officially supported by Haskell for any Linux distributions. This article describes Arch way of installing and using Haskell. See [[#Alternate installations]] for more information about other installation methods.}}<br />
<br />
Haskell generates machine code that can be run natively on Linux. There is nothing special required to run a binary (already compiled) software, like {{Pkg|xmonad}} or {{Pkg|pandoc}} provided in the [[official repositories]]. On the other side, building [[AUR]] packages or developing software require a compiler and build tools to be installed.<br />
<br />
To install the latest version of Haskell, [[install]] the following packages from the official repositories:<br />
* {{Pkg|ghc}} ([https://www.haskell.org/ghc GHC]) — A Haskell compiler. There are several [https://www.haskell.org/haskellwiki/Implementations implementations] available, but the one used most (which is now ''de facto'' the reference) is the GHC (Glasgow Haskell Compiler).<br />
* {{Pkg|cabal-install}} ([https://www.haskell.org/cabal Cabal]) — A build tool focused on dependency resolution and sources packages from [https://hackage.haskell.org Hackage]. Hackage is the Haskell community's central package archive of open source software.<br />
* {{Pkg|stack}} ([https://www.haskellstack.org Stack]) — A build tool focused on curated snapshots and sources packages from [https://www.stackage.org Stackage]. Stackage is a stable subset of Hackage that provides curated sets (snapshots) of packages known to work well with each other. Alternatively, Stack can be installed through {{AUR|stack-static}} package. It provides statically linked binaries, thereby avoiding dozens of {{ic|haskell-*}} dependencies.<br />
<br />
You can install and configure either Cabal or Stack or both of them. Most of the popular Haskell packages support both Cabal and Stack.<br />
<br />
== Configuration ==<br />
<br />
Since version [https://github.com/archlinux/svntogit-community/commit/7a948cdfb808afd3ce6f93047ae0dc1778e79f9f 8.0.2-1], the Arch {{Pkg|ghc}} package and all [https://archlinux.org/packages/?q=haskell haskell-*] packages in ''community'' provide only dynamically linked libraries. Therefore, to link successfully one must configure GHC, Cabal and Stack for dynamic linking, as the default is to use static linking.<br />
<br />
Using dynamic linking typically results in faster builds and smaller disk and RAM usage (by sharing pages between multiple running Haskell programs), and will free you from troubleshooting cross-GHC mixing errors. But it has its own disadvantage: '''all tools you install from source will break''' on every update of {{Pkg|ghc}}, {{Pkg|ghc-libs}} or [https://archlinux.org/packages/?q=haskell haskell-*] packages since libraries compiled with GHC do not provide a stable [[Wikipedia:Application binary interface|ABI]]. When running such broken binary, you will see the usual message {{ic|error while loading shared libraries: libHS...so: cannot open shared object file: No such file or directory}}. To fix this, just rebuild and reinstall the broken tool in order to relink it to newer libraries.<br />
<br />
On the other hand, static linking is generally easier to maintain and does not force you to rebuild all tools from source after every update of their dependencies. For these reasons, static linking is often the preferred option for local development outside of the package system. If you prefer static linking, see [[#Static linking]] or [[#Alternate installations]] for details.<br />
<br />
{{Note|For a detailed explanation of why Arch moved to dynamic linking for Haskell packages, see this [https://www.reddit.com/r/linux/comments/9emwtu/arch_linux_ama/e5qssdz maintainer's response].}}<br />
<br />
=== Invoking GHC directly ===<br />
<br />
In order to link successfully one must pass the {{ic|-dynamic}} flag to GHC. You can try it with the following file:<br />
<br />
{{hc|Main.hs|2=<br />
main = putStrLn "Hello, World"<br />
}}<br />
<br />
Compile and run it with:<br />
<br />
{{hc|<br />
$ ghc -dynamic Main.hs<br />
$ ./Main|<br />
Hello, World<br />
}}<br />
<br />
=== Configuring Cabal for dynamic linking ===<br />
<br />
First, run the following command to download the latest list of packages from Hackage and create global configuration file {{ic|~/.cabal/config}} (or the file {{ic|$CABAL_CONFIG}} points to):<br />
<br />
$ cabal update<br />
<br />
{{Tip|It is advisable to periodically run {{ic|cabal update}} to synchronize your local list of packages and dependencies with the newest version on Hackage.}}<br />
<br />
To configure Cabal for dynamic linking, uncomment and edit the following options in {{ic|~/.cabal/config}}:<br />
<br />
{{hc|~/.cabal/config|<br />
library-vanilla: False<br />
shared: True<br />
executable-dynamic: True<br />
program-default-options<br />
ghc-options: -dynamic<br />
}}<br />
<br />
* {{ic|library-vanilla: False}} suppresses the creation of static libraries (if your project contains a library).<br />
* {{ic|shared: True}} enables the creation of shared libraries (if your project contains a library).<br />
* {{ic|executable-dynamic: True}} causes dynamic linking to be used for executables (if your project contains executables).<br />
* {{ic|ghc-options: -dynamic}} adds the {{ic|-dynamic}} flag to every invocation of GHC (e.g. if a package has a non-trivial {{ic|Setup.hs}}).<br />
<br />
=== Configuring Stack for dynamic linking ===<br />
<br />
You can use {{ic|stack setup}} command to initialize Stack and create global configuration file {{ic|~/.stack/config.yaml}}. By default Stack will automatically download its own version of GHC to an isolated location upon first invocation. To force Stack to use system GHC installation instead, run {{ic|stack setup}} with {{ic|--system-ghc}} and {{ic|--resolver}} flags:<br />
<br />
$ stack setup --system-ghc --resolver ''resolver''<br />
<br />
Note that you need to specify a resolver which is compatible with your system GHC. Otherwise Stack will happily ignore {{ic|--system-ghc}} flag and download its own copy of GHC. You can determine the version of system GHC using {{ic|ghc --version}} command:<br />
<br />
{{hc|$ ghc --version|<br />
The Glorious Glasgow Haskell Compilation System, version 8.10.2<br />
}}<br />
<br />
Then visit [https://www.stackage.org Stackage] website and pick a suitable Long Term Support (LTS) or nightly snapshot matching your system GHC version. Use the selected snapshot for {{ic|--resolver}} flag on the command line, e.g. {{ic|--resolver lts-16.15}} or {{ic|--resolver nightly-2020-09-01}}.<br />
<br />
Stackage typically lags behind new GHC releases. It may happen that no Stackage snapshot for your system GHC has yet been released. In this case you might want to choose a snapshot for some earlier minor version of GHC or temporarily downgrade your Haskell installation and wait until support for newer GHC releases finally lands on Stackage.<br />
<br />
To configure Stack for dynamic linking, add the following snippet to {{ic|~/.stack/config.yaml}}:<br />
<br />
{{hc|~/.stack/config.yaml|<br />
# Stop downloading GHCs into isolated locations under ~/.stack.<br />
install-ghc: false<br />
<br />
# Allow Stack to pick the system GHC (false by default).<br />
system-ghc: true<br />
<br />
# Allow to use, say, Stackage snapshot for GHC 8.8.2 with system GHC 8.8.3.<br />
compiler-check: newer-minor<br />
<br />
# Add the -dynamic flag to every invocation of GHC.<br />
ghc-options:<br />
"$everything": -dynamic<br />
}}<br />
<br />
== Package management ==<br />
<br />
Most of Haskell libraries and executables are distributed in units of source packages available from Hackage and Stackage.<br />
<br />
As is common in other compiled languages, a number of popular Haskell packages are available from official Arch repositories in pre-built form. Some additional packages can be installed from [[AUR]].<br />
<br />
Although it is recommended to use [[pacman]] to install GHC, libraries and tools from official repositories — at some point you may want to install Haskell packages directly from Hackage/Stackage or compile your own (or somebody else's) packages from source. You will need Cabal or Stack for doing that.<br />
<br />
The following table summarizes the advantages and disadvantages of different package management styles.<br />
<br />
{| class="wikitable"<br />
! '''Method'''<br />
! '''Pros'''<br />
! '''Cons'''<br />
|-<br />
| Official repositories || Provided by Arch Linux developers, consistent versions of packages, already compiled || Not all packages available, only dynamic libraries available<br />
|-<br />
| Cabal || All packages available, root not required || Installed in home directory, failures in dependency resolution, difficult to remove specific packages<br />
|-<br />
| Stack || All packages available (favors Stackage), root not required || Installed in home directory, versions are pinned to snapshot, difficult to remove specific packages<br />
|-<br />
| AUR || Additional packages available || Risk of unmaintained or orphaned packages, incompatible versions of packages possible<br />
|-<br />
|}<br />
<br />
=== Cabal ===<br />
<br />
{{Note|In Haskell, the term ''Cabal'' can refer to either:<br />
* Cabal file format that describes Haskell packages and their dependencies;<br />
* Cabal library that works with Cabal file format;<br />
* {{ic|cabal}} command-line tool (provided by {{Pkg|cabal-install}} package) that uses Cabal library to build Haskell packages.<br />
In the context of this article, ''Cabal'' usually means {{ic|cabal}} command-line tool unless specified otherwise.}}<br />
<br />
Cabal is "the original" build system for Haskell. Most of libraries and tools you can find on Hackage can be installed via Cabal.<br />
<br />
==== Installing packages ====<br />
<br />
To run user-wide executables installed by Cabal, {{ic|~/.cabal/bin}} must be added to the {{ic|$PATH}} environment variable. This can be done by putting the following line in your shell configuration file, for instance {{ic|~/.bashrc}} for {{Pkg|bash}} or {{ic|~/.zshrc}} for {{Pkg|zsh}}:<br />
<br />
export PATH="$HOME/.cabal/bin:$PATH"<br />
<br />
Run the following command to install a Hackage package and all of its dependencies in a single step:<br />
<br />
$ cabal install --ghc-options=-dynamic ''package''<br />
<br />
{{Note|As of October 2020 Cabal [https://github.com/haskell/cabal/issues/6505 ignores] {{ic|ghc-options}} from {{ic|~/.cabal/config}} while building packages with {{ic|build-type: Custom}}. Therefore, it is necessary to specify {{ic|1=--ghc-options=-dynamic}} flag on the command line otherwise you might experience build errors in {{ic|setup.hs}} like {{ic|Could not find module ‘Prelude’ There are files missing in the ‘base-...’ package}}.}}<br />
<br />
You can also build and install a Haskell package from source. To do this, run the following command from the package directory:<br />
<br />
$ cabal install --ghc-options=-dynamic<br />
<br />
Each Cabal package should specify a list of its dependencies and their version constraints in the {{ic|.cabal}} file according to the [https://pvp.haskell.org Package Versioning Policy] (PVP). During the package installation, Cabal tries to find a set of dependencies that satisfies all the constraints. This process is called ''dependency resolution''.<br />
<br />
There are reasons why Stack exists; Cabal is known to generate a lot of friction with beginners. Most of the time dependency resolution works well but sometimes it fails. In this case you will need to figure out the cause of the problem and give Cabal some hints about how to resolve offending dependencies. For example, sometimes it is necessary to say {{ic|1=cabal install --allow-newer --ghc-options=-dynamic ''package''}} to allow Cabal to ignore package's PVP-dictated upper bounds on dependency versions, effectively installing package with newer dependencies than the package author has permitted. It gets hairier for less-well maintained packages; for another example, see [https://groups.google.com/d/msg/idris-lang/h2uWYmqHcc0/5k0jNmQ3BAAJ this thread] about installing Idris (another programming language, written in Haskell), where one had to use both {{ic|--allow-newer}} and {{ic|1=--constraint='haskeline < 0.8.0.0'}} command-line flags to get a successful compile.<br />
<br />
==== Removing packages ====<br />
<br />
There is no easy way to do it. Cabal does not have support for this functionality but there are external tools like [https://github.com/phadej/cabal-extras#cabal-store-gc cabal-store-gc].<br />
<br />
To reinstall the entire user-wide Haskell package system, remove {{ic|~/.cabal}} and {{ic|~/.ghc}} and start from scratch. This is often necessary when GHC is upgraded.<br />
<br />
For more precision, it's possible to use {{ic|ghc-pkg unregister ''package''}} or {{ic|ghc-pkg hide ''package''}}/{{ic|ghc-pkg expose ''package''}} directly on the [https://downloads.haskell.org/ghc/8.10.2/docs/html/users_guide/packages.html#package-databases|''user package database''] — this makes GHC "forget" about an installed package (or pretend it's not there). However neither of these removes any files.<br />
<br />
=== Stack ===<br />
<br />
Stack is another tool to manage Haskell packages. It has slightly different goals than Cabal, with a slightly different philosophy. It uses Cabal library under the hood and integrates with Hackage — but maintains its own repositories of packages (snapshots) on Stackage with the promise that snapshots are curated and include packages which work well together.<br />
<br />
==== Installing packages ====<br />
<br />
In its default configuration, Stack installs compiled executables to {{ic|~/.local/bin}}. Add this directory to the {{ic|$PATH}} environment variable in your shell configuration file, for instance {{ic|~/.bashrc}} for {{Pkg|bash}} or {{ic|~/.zshrc}} for {{Pkg|zsh}}:<br />
<br />
export PATH="$HOME/.local/bin:$PATH"<br />
<br />
Run the following command to download, build and install a Stackage package:<br />
<br />
stack install ''package''<br />
<br />
{{Note|As of October 2020 Stack [https://github.com/commercialhaskell/stack/issues/3409 ignores] {{ic|ghc-options}} from {{ic|~/.stack/config.yaml}} while building {{ic|Setup.hs}}. If you experience build errors in {{ic|Setup.hs}} like {{ic|Could not find module ‘Prelude’ There are files missing in the ‘base-...’ package}}, try to install {{Pkg|ghc-static}} package as a workaround.}}<br />
<br />
You can also build and install a Haskell package from source by running the following command from the package directory:<br />
<br />
stack install --resolver ''resolver''<br />
<br />
Note that you should specify the same resolver as one used for {{ic|stack setup}} command.<br />
<br />
==== Removing packages ====<br />
<br />
Stack does not support the "uninstall" operation.<br />
<br />
If you want to reinstall the entire user-wide Haskell package system, remove {{ic|~/.stack}} directory and start from scratch. This is often necessary when GHC is upgraded.<br />
<br />
== Alternate installations ==<br />
<br />
{{Note|This section describes alternative ways of installing Haskell on Arch without using packages from the official repositories. If you previously installed GHC, Cabal, Stack or any other Haskell packages, make sure to uninstall them first. Remove {{ic|~/.cabal}} and {{ic|~/.stack}} directories if they exist.}}<br />
<br />
There are two officially recommended methods of installing Haskell on any generic Linux distribution: [https://gitlab.haskell.org/haskell/ghcup-hs ghcup] and [https://www.haskellstack.org Stack]. Both methods install statically linked GHC, tools and libraries in your home directory.<br />
<br />
The advantage of using ghcup or Stack instead of Haskell packages from the official repositories is the ability to install and manage multiple versions of GHC side by side. Cabal and Stack installed this way typically work right out of the box without any additional configuration, which might be easier for beginners.<br />
<br />
A completely different way of installing Haskell is [[Nix]] package manager. Nix has a steeper learning curve but offers greater flexibility in managing both Haskell and non-Haskell packages in a reliable and reproducible fashion.<br />
<br />
=== ghcup ===<br />
<br />
ghcup is a command line tool that allows to easily install multiple versions of GHC and switch between them. It is similar in scope to [https://github.com/rust-lang/rustup rustup], [https://github.com/pyenv/pyenv pyenv] and [https://www.jenv.be jenv].<br />
<br />
Install {{AUR|ghcup-hs-bin}} package. Alternatively, you may follow official [https://www.haskell.org/ghcup installation instructions] or manually download [https://downloads.haskell.org/~ghcup ghcup binary] and place it somewhere into your {{ic|$PATH}}.<br />
<br />
By default, ghcup will install GHC executables into {{ic|~/.ghcup/bin}}. You need to add this directory to the {{ic|$PATH}} environment variable in your shell configuration file, for instance {{ic|~/.bashrc}} for {{Pkg|bash}} or {{ic|~/.zshrc}} for {{Pkg|zsh}}. If you want to run executables installed by Cabal, add {{ic|~/.cabal/bin}} to {{ic|$PATH}} as well:<br />
<br />
export PATH="$HOME/.cabal/bin:$HOME/.ghcup/bin:$PATH"<br />
<br />
{{Tip|If you want to use XDG style directories, define {{ic|GHCUP_USE_XDG_DIRS}} environment variable (https://gitlab.haskell.org/haskell/ghcup-hs/#xdg-support).}}<br />
<br />
ghcup provides a convenient TUI which supports most of its functionality:<br />
<br />
$ ghcup tui<br />
<br />
Alternatively, you can use the following CLI commands:<br />
<br />
List available versions of GHC and Cabal:<br />
<br />
$ ghcup list<br />
<br />
Install the recommended version of GHC:<br />
<br />
$ ghcup install ghc<br />
<br />
You can also install a specific version of GHC, for example:<br />
<br />
$ ghcup install ghc 8.10.2<br />
<br />
The commands above do not automatically make GHC available on the {{ic|$PATH}}. You need to select which GHC version to use by default:<br />
<br />
$ ghcup set ghc 8.10.2<br />
<br />
Install the recommended version of Cabal:<br />
<br />
$ ghcup install cabal<br />
<br />
You can now use Cabal to build and install statically linked Haskell executables without any special configuration or command line flags:<br />
<br />
{{bc|<br />
$ cabal update<br />
$ cabal install ''executable''<br />
}}<br />
<br />
To start a new Cabal project:<br />
{{hc|<br />
$ cd /path/to/my-project<br />
$ cabal init<br />
$ cabal build<br />
$ cabal run|<br />
Up to date<br />
Hello, Haskell!<br />
}}<br />
<br />
For more information, refer to official [https://gitlab.haskell.org/haskell/ghcup-hs ghcup] and [https://cabal.readthedocs.io/en/latest Cabal] documentation.<br />
<br />
=== Stack ===<br />
<br />
Install {{AUR|stack-static}} package. Alternatively, you may follow official [https://docs.haskellstack.org/en/stable/install_and_upgrade installation instructions] or manually download [https://github.com/commercialhaskell/stack/releases Stack binary] and place it somewhere into your {{ic|$PATH}}.<br />
<br />
If you want to run executables installed by Stack, add {{ic|~/.local/bin}} directory to the {{ic|$PATH}} environment variable in your shell configuration file, for instance {{ic|~/.bashrc}} for {{Pkg|bash}} or {{ic|~/.zshrc}} for {{Pkg|zsh}}:<br />
<br />
export PATH="$HOME/.local/bin:$PATH"<br />
<br />
Run {{ic|stack setup}} to automatically install GHC from the latest Stackage LTS snapshot:<br />
<br />
$ stack setup<br />
<br />
You can now use Stack to build and install statically linked Haskell packages without any special configuration or command line flags:<br />
<br />
$ stack install ''package''<br />
<br />
For more information, refer to official [https://docs.haskellstack.org/en/stable Stack documentation].<br />
<br />
=== Nix ===<br />
<br />
{{Expansion|I cannot offer a good enough overview, due to no experience with it}}<br />
<br />
== IDE support ==<br />
<br />
=== Tools ===<br />
<br />
==== ghcid ====<br />
<br />
[https://github.com/ndmitchell/ghcid ghcid] provides a simple and robust way to display compiler messages on source code change.<br />
<br />
==== Linters ====<br />
<br />
[https://github.com/ndmitchell/hlint hlint] is a linter, suggesting possible improvements to Haskell code.<br />
<br />
[https://github.com/kowainik/stan stan] is another linter, complementary to hlint. It is in its early stages as of January 2021.<br />
<br />
==== haskell-language-server ====<br />
<br />
[https://github.com/haskell/haskell-language-server haskell-language-server] is a [https://microsoft.github.io/language-server-protocol/ Language Server Protocol] (LSP) implementation for Haskell. It provides IDE-like features like type-on-hover or autocompletions for any editor integrating with the LSP.<br />
<br />
There are pre-built binaries which can be installed via {{AUR|haskell-language-server-bin}}, [[#ghcup]] or by the [https://marketplace.visualstudio.com/items?itemName=haskell.haskell Haskell extension] for [[Visual Studio Code]].<br />
<br />
==== Formatters ====<br />
<br />
{| class="wikitable"<br />
! '''Formatter'''<br />
! '''Notes'''<br />
|-<br />
| [https://github.com/lspitzner/brittany brittany] ||<br />
|-<br />
| [https://github.com/ennocramer/floskell floskell] ||<br />
|-<br />
| [https://github.com/tweag/ormolu ormolu] || not configurable by design<br />
|-<br />
| [https://github.com/parsonsmatt/fourmolu fourmolu] || fork of ormolu, adding configurability<br />
|-<br />
| [https://github.com/jaspervdj/stylish-haskell stylish-haskell]<br />
|-<br />
|}<br />
<br />
=== Editors ===<br />
<br />
{{Expansion|I do not have experience with other editors}}<br />
<br />
==== Emacs ====<br />
<br />
Basic [[Emacs]] support for Haskell is provided by the official [https://github.com/haskell/haskell-mode haskell-mode]. For more advanced features, also use [https://github.com/emacs-lsp/lsp-haskell lsp-haskell] with [[#haskell-language-server]].<br />
<br />
==== Vim ====<br />
<br />
Any [https://vimawesome.com/?q=LSP LSP client] plugin will work with [[#haskell-language-server]].<br />
<br />
==== Visual Studio Code ====<br />
<br />
[[Visual Studio Code]] support is provided by the official [https://marketplace.visualstudio.com/items?itemName=haskell.haskell Haskell plugin].<br />
<br />
== Tips and tricks ==<br />
<br />
=== Static linking ===<br />
<br />
{{Note|This section explains how to build statically linked Haskell packages on Arch, but still use GHC installed from the official repositories. Before you proceed, make sure to remove {{ic|~/.cabal}} and {{ic|~/.stack}} directories if they exist.}}<br />
<br />
{{Note|In the context of this article, static linking does not mean generating completely static ELF binaries. Only Haskell code will be linked statically into a single ELF binary, which may be dynamically linked to other system libraries such as {{Pkg|glibc}}.}}<br />
<br />
To use static linking, one must, at minimum, install the static boot libraries through the {{Pkg|ghc-static}} package. This would allow you to build projects that depend exclusively on the boot libraries as well as on any other libraries that are not installed through the {{ic|haskell-*}} packages from the official repositories.<br />
<br />
Unfortunately, if your project depends on any of dynamically linked {{ic|haskell-*}} packages that you have installed, Cabal does not take the absence of static libraries into account during dependency resolution. As a result, it will try to use the existing {{ic|haskell-*}} package and then fail with [https://bugs.archlinux.org/task/54563#comment158808 linker errors] when it discovers the static libraries are missing:<br />
<br />
Could not find module ‘''SomePackage.SomeModule''’<br />
There are files missing in the ‘''somepackage-0.1.0.0''’ package,<br />
try running 'ghc-pkg check'.<br />
Use -v (or `:set -v` in ghci) to see a list of the files searched for.<br />
<br />
Unlike {{ic|ghc-static}}, there are no “{{ic|haskell-*-static}}” packages available for linkage. There other others ways to work around this issue though, as described in each of the sections below.<br />
<br />
==== Static global package database ====<br />
<br />
A direct [https://www.reddit.com/r/linux/comments/9emwtu/arch_linux_ama/efjnyd6/ approach] is offered by the official {{Pkg|ghc-static}} package, which exposes an alternative "static" global package database at {{ic|/usr/lib/ghc-''version''/static-package.conf.d}}. The static database is limited to only the statically linkable boot packages, therefore if Cabal is reconfigured to use the static database instead of the default database, it would behave as though the dynamic-only {{ic|haskell-*}} packages don't exist.<br />
<br />
The precise path of the static database could be determined at build time using a command such as:<br />
<br />
$ ghc --print-global-package-db | sed 's/\(package\.conf\.d\)$/static-\1/'<br />
<br />
Here's how to enable the static database for use:<br />
<br />
* When building packages with Cabal, one can pass the following flag to limit the selection of global packages to only the boot packages:<br />
<br />
$ cabal configure --ghc-pkg-option=--global-package-db=/usr/lib/ghc-''version''/static-package.conf.d<br />
<br />
* This can be configured account-wide by editing {{ic|~/.cabal/config}}:<br />
<br />
{{hc|~/.cabal/config|2=<br />
program-default-options<br />
ghc-pkg-options: --global-package-db=/usr/lib/ghc-''version''/static-package.conf.d<br />
}}<br />
<br />
* When building directly using GHC rather than Cabal, one can pass the following flags to override the global package database:<br />
<br />
$ ghc -clear-package-db -package-db /usr/lib/ghc-''version''/static-package.conf.d -user-package-db ...<br />
<br />
==== ghc-pristine ====<br />
<br />
Install {{AUR|ghc-pristine}} package, which wraps over an existing GHC installation to create a separate GHC distribution in {{ic|/usr/share/ghc-pristine}}, with a package database that contains only boot libraries. This effectively creates a semi-isolated environment without dynamically linked {{ic|haskell-*}} packages, but still makes use of the GHC compiler from the official repositories. Then, to build software with static linking, one simply needs to invoke the wrapped compiler {{ic|/usr/share/ghc-pristine/bin/ghc}}. For Cabal, this amounts to the following configuration in {{ic|~/.cabal/config}}:<br />
<br />
{{hc|~/.cabal/config|<br />
with-compiler: /usr/share/ghc-pristine/bin/ghc<br />
}}<br />
<br />
You can also specify the path to the compiler on a per-project basis by running the following command from the project directory:<br />
<br />
$ cabal configure --with-compiler=/usr/share/ghc-pristine/bin/ghc<br />
<br />
==== cabal-static ====<br />
<br />
Another way to gain back static linking on Arch is to install {{AUR|cabal-static}} package. Unlike the official {{Pkg|cabal-install}}, this one does not pull dynamically linked {{ic|haskell-*}} dependencies from the official repositories and avoids mixing static and shared Haskell libraries installed on the same system. Then you can use Cabal as usual with the following limitation: '''you have to make sure''' that the only other Haskell packages you have installed are {{Pkg|ghc}}, {{Pkg|ghc-libs}} and {{Pkg|ghc-static}} (not {{Pkg|cabal-install}}, {{Pkg|stack}} and none of the {{ic|haskell-*}} packages available in the official repositories).<br />
<br />
==== stack-static ====<br />
<br />
Install {{AUR|stack-static}} package. Similarly to {{ic|cabal-static}} method, make sure that the only other Haskell packages you have installed from the official repositories are {{Pkg|ghc}}, {{Pkg|ghc-libs}} and {{Pkg|ghc-static}}. Then setup Stack to use system GHC as explained in [[#Configuring Stack for dynamic linking]]:<br />
<br />
$ stack setup --system-ghc --resolver ''resolver''<br />
<br />
To make these options permanent, paste the following snippet to {{ic|~/.stack/config.yaml}}:<br />
<br />
{{hc|~/.stack/config.yaml|<br />
# Stop downloading GHCs into isolated locations under ~/.stack.<br />
install-ghc: false<br />
<br />
# Allow Stack to pick the system GHC (false by default).<br />
system-ghc: true<br />
<br />
# Allow to use, say, Stackage snapshot for GHC 8.8.2 with system GHC 8.8.3.<br />
compiler-check: newer-minor<br />
}}<br />
<br />
This configuration will allow you to build statically linked packages as you would normally do, but using system GHC installation instead of GHC provided by Stack.<br />
<br />
==== hpack-static-bin ====<br />
<br />
{{AUR|hpack-static-bin}} provides a statically linked (meaning no haskell-* dependencies) alternative to {{Pkg|haskell-hpack}}. It is precompiled, so no make dependencies are needed.<br />
<br />
== See also ==<br />
<br />
*[http://learnyouahaskell.com/ Learn You a Haskell for Great Good!]<br />
*[http://book.realworldhaskell.org/ Real World Haskell]</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Talk:Dm-crypt/Encrypting_a_non-root_file_system&diff=589261Talk:Dm-crypt/Encrypting a non-root file system2019-11-18T08:24:00Z<p>Fylwind: /* Should --align-payload=1 be still used? */ new section</p>
<hr />
<div>==rm talk page link==<br />
Wouldn't the talk page link be more of a source for that sentence than the keyfile link?<br />
I suggest moving [1] up to "by doing an alternative method:" and putting the talk page link as [2] in the place of [1], if it is okay with you. - [[User:Wincraft71|Wincraft71]] ([[User talk:Wincraft71|talk]]) 07:33, 4 January 2018 (UTC)<br />
<br />
== Should --align-payload=1 be still used? ==<br />
<br />
Should {{ic|1=--align-payload=1}} be still used? The man page says:<br />
<br />
: '''WARNING''': This option is DEPRECATED and has often unexpected impact to the data offset and keyslot area size (for LUKS2) due to the complex rounding. For fixed data device offset use {{ic|1=--offset}} option instead.<br />
<br />
--[[User:Fylwind|Fylwind]] ([[User talk:Fylwind|talk]]) 08:24, 18 November 2019 (UTC)</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Dm-crypt/Encrypting_a_non-root_file_system&diff=589260Dm-crypt/Encrypting a non-root file system2019-11-18T08:19:40Z<p>Fylwind: /* Loop device */ Following up the previous edit, there's no need to talk about dd's edge case now that head is used instead.</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Disk encryption]]<br />
[[es:Dm-crypt (Español)/Encrypting a non-root file system]]<br />
[[ja:Dm-crypt/root 以外のファイルシステムの暗号化]]<br />
[[pl:Dm-crypt/Encrypting a non-root file system]]<br />
[[zh-hant:Dm-crypt/Encrypting a non-root file system]]<br />
The following are examples of encrypting a secondary, i.e. non-root, filesystem with dm-crypt. <br />
== Overview == <br />
Encrypting a secondary filesystem usually protects only sensitive data, while leaving the operating system and program files unencrypted. This is useful for encrypting an external medium, such as a USB drive, so that it can be moved to different computers securely. One might also choose to encrypt sets of data separately according to who has access to it. <br />
<br />
Because dm-crypt is a [[Disk encryption#Block_device_encryption|block-level]] encryption layer, it only encrypts full devices, [[#Partition|full partitions]] and [[#Loop_device|loop devices]]. To encrypt individual files requires a filesystem-level encryption layer, such as [[eCryptfs]] or [[EncFS]]. See [[Disk encryption]] for general information about securing private data.<br />
<br />
== Partition ==<br />
This example covers the encryption of the {{ic|/home}} partition, but it can be applied to any other comparable non-root partition containing user data.<br />
<br />
{{Tip|You can either have a single user's {{ic|/home}} directory on a partition, or create a common partition for all user's {{ic|/home}} directories.}}<br />
<br />
First make sure the partition is empty (has no file system attached to it). Delete the partition and create an empty one if it has a file system. Then prepare the partition by securely erasing it, see [[Dm-crypt/Drive preparation#Secure erasure of the hard disk drive]]. <br />
<br />
Create the partition which will contain the encrypted container. <br />
<br />
Then setup the LUKS header with:<br />
# cryptsetup ''options'' luksFormat ''device''<br />
<br />
Replace {{ic|''device''}} with the previously created partition. See [[Dm-crypt/Device encryption#Encryption options for LUKS mode]] for details like the available {{ic|''options''}}.<br />
<br />
To gain access to the encrypted partition, unlock it with the device mapper, using:<br />
# cryptsetup open ''device'' ''name''<br />
<br />
After unlocking the partition, it will be available at {{ic|/dev/mapper/''name''}}. Now create a [[file system]] of your choice with:<br />
# mkfs.''fstype'' /dev/mapper/''name''<br />
<br />
Mount the file system to {{ic|/home}}, or if it should be accessible to only one user to {{ic|/home/''username''}}, see [[#Manual mounting and unmounting]].<br />
<br />
{{Tip|Unmount and mount once to verify that the mapping is working as intended.}}<br />
<br />
=== Manual mounting and unmounting ===<br />
To mount the partition:<br />
<br />
# cryptsetup open ''device'' ''name''<br />
# mount -t ''fstype'' /dev/mapper/''name'' /mnt/home<br />
<br />
To unmount it:<br />
<br />
# umount /mnt/home<br />
# cryptsetup close ''name''<br />
<br />
{{Tip|[[GVFS]] can also mount encrypted partitions. One can use a file manager with gvfs support (e.g. [[Thunar]]) to mount the partition, and a password dialog will pop-up. For other desktops, {{Aur|zulucrypt}} also provides a GUI.}}<br />
<br />
=== Automated unlocking and mounting ===<br />
<br />
There are three different solutions for automating the process of unlocking the partition and mounting its filesystem.<br />
<br />
==== At boot time ====<br />
<br />
Using the {{ic|/etc/crypttab}} configuration file, unlocking happens at boot time by systemd's automatic parsing. This is the recommended solution if you want to use one common partition for all user's home partitions or automatically mount another encrypted block device. <br />
<br />
See [[Dm-crypt/System configuration#crypttab]] for references and [[Dm-crypt/System configuration#Mounting at boot time]] for an example set up. <br />
<br />
==== On user login ====<br />
<br />
Using ''pam_exec'' it is possible to unlock (''cryptsetup open'') the partition on user login: this is the recommended solution if you want to have a single user's home directory on a partition. See [[dm-crypt/Mounting at login]].<br />
<br />
Unlocking on user login is also possible with [[pam_mount]].<br />
<br />
== Loop device ==<br />
<br />
There are two methods for using a loop device as an encrypted container, one using {{ic|losetup}} directly and one without.<br />
<br />
=== Without losetup ===<br />
<br />
Using losetup directly can be avoided completely by doing the following [https://wiki.gentoo.org/wiki/Custom_Initramfs#Encrypted_keyfile]:<br />
<br />
# head -c 20M </dev/urandom >key.img<br />
# cryptsetup --align-payload=1 luksFormat key.img<br />
<br />
Before running {{ic|cryptsetup}}, look at the [[Dm-crypt/Device_encryption#Encryption_options_for_LUKS_mode|Encryption options for LUKS mode]] and [[Disk_encryption#Ciphers_and_modes_of_operation|Ciphers and modes of operation]] first to select your additional desired settings.<br />
<br />
The instructions for opening the device and making the [[file system]] are the same as [[#Partition]].<br />
<br />
Having too small of a file will get you a {{ic|Requested offset is beyond real size of device /dev/loop0}} error, but as a rough reference creating a 4 MiB file will encrypt it successfully. [http://archive.is/VOh2p]<br />
<br />
Manual mounting and unmounting procedure is equivalent to [[#Manual mounting and unmounting]].<br />
<br />
=== Using losetup ===<br />
<br />
A loop device enables to map a blockdevice to a file with the standard util-linux tool {{ic|losetup}}. The file can then contain a filesystem, which can be used quite like any other filesystem. A lot of users know [[TrueCrypt]] as a tool to create encrypted containers. Just about the same functionality can be achieved with a loopback filesystem encrypted with LUKS and is shown in the following example. <br />
<br />
First, start by creating an encrypted container, using an appropriate [[random number generator]]: <br />
<br />
# head -c 10M </dev/urandom >/bigsecret<br />
<br />
This will create the file {{ic|bigsecret}} with a size of 10 megabytes. <br />
<br />
{{Note|To avoid having to [[Dm-crypt/Device_encryption#Loopback filesystem|resize]] the container later on, make sure to make it larger than the total size of the files to be encrypted, in order to at least also host the associated metadata needed by the internal file system. If you are going to use LUKS mode, its metadata header requires one to two megabytes alone.}}<br />
<br />
Next create the device node {{ic|/dev/loop0}}, so that we can mount/use our container:<br />
<br />
# losetup /dev/loop0 /bigsecret<br />
<br />
{{Note|If it gives you the error {{ic|/dev/loop0: No such file or directory}}, you need to first load the kernel module with {{ic|modprobe loop}}. These days (Kernel 3.2) loop devices are created on demand. Ask for a new loop device with {{ic|# losetup -f}}.}}<br />
<br />
From now on the procedure is the same as for [[#Partition]], except for the fact that the container is already randomised and will not need another secure erasure.<br />
<br />
{{Tip|Containers with ''dm-crypt'' can be very flexible. Have a look at the features and documentation of [[Tomb]]. It provides a ''dm-crypt'' script wrapper for fast and flexible handling.}}<br />
<br />
==== Manual mounting and unmounting ====<br />
To unmount the container:<br />
<br />
# umount /mnt/secret<br />
# cryptsetup close secret<br />
# losetup -d /dev/loop0<br />
<br />
To mount the container again:<br />
<br />
# losetup /dev/loop0 /bigsecret<br />
# cryptsetup open /dev/loop0 secret<br />
# mount -t ext4 /dev/mapper/secret /mnt/secret</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Dm-crypt/Encrypting_a_non-root_file_system&diff=589259Dm-crypt/Encrypting a non-root file system2019-11-18T08:16:52Z<p>Fylwind: /* Loop device */ Switch to head because head is easier to use and dd sometimes reads partial blocks, copying the wrong number of bytes. See https://unix.stackexchange.com/a/121888</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Disk encryption]]<br />
[[es:Dm-crypt (Español)/Encrypting a non-root file system]]<br />
[[ja:Dm-crypt/root 以外のファイルシステムの暗号化]]<br />
[[pl:Dm-crypt/Encrypting a non-root file system]]<br />
[[zh-hant:Dm-crypt/Encrypting a non-root file system]]<br />
The following are examples of encrypting a secondary, i.e. non-root, filesystem with dm-crypt. <br />
== Overview == <br />
Encrypting a secondary filesystem usually protects only sensitive data, while leaving the operating system and program files unencrypted. This is useful for encrypting an external medium, such as a USB drive, so that it can be moved to different computers securely. One might also choose to encrypt sets of data separately according to who has access to it. <br />
<br />
Because dm-crypt is a [[Disk encryption#Block_device_encryption|block-level]] encryption layer, it only encrypts full devices, [[#Partition|full partitions]] and [[#Loop_device|loop devices]]. To encrypt individual files requires a filesystem-level encryption layer, such as [[eCryptfs]] or [[EncFS]]. See [[Disk encryption]] for general information about securing private data.<br />
<br />
== Partition ==<br />
This example covers the encryption of the {{ic|/home}} partition, but it can be applied to any other comparable non-root partition containing user data.<br />
<br />
{{Tip|You can either have a single user's {{ic|/home}} directory on a partition, or create a common partition for all user's {{ic|/home}} directories.}}<br />
<br />
First make sure the partition is empty (has no file system attached to it). Delete the partition and create an empty one if it has a file system. Then prepare the partition by securely erasing it, see [[Dm-crypt/Drive preparation#Secure erasure of the hard disk drive]]. <br />
<br />
Create the partition which will contain the encrypted container. <br />
<br />
Then setup the LUKS header with:<br />
# cryptsetup ''options'' luksFormat ''device''<br />
<br />
Replace {{ic|''device''}} with the previously created partition. See [[Dm-crypt/Device encryption#Encryption options for LUKS mode]] for details like the available {{ic|''options''}}.<br />
<br />
To gain access to the encrypted partition, unlock it with the device mapper, using:<br />
# cryptsetup open ''device'' ''name''<br />
<br />
After unlocking the partition, it will be available at {{ic|/dev/mapper/''name''}}. Now create a [[file system]] of your choice with:<br />
# mkfs.''fstype'' /dev/mapper/''name''<br />
<br />
Mount the file system to {{ic|/home}}, or if it should be accessible to only one user to {{ic|/home/''username''}}, see [[#Manual mounting and unmounting]].<br />
<br />
{{Tip|Unmount and mount once to verify that the mapping is working as intended.}}<br />
<br />
=== Manual mounting and unmounting ===<br />
To mount the partition:<br />
<br />
# cryptsetup open ''device'' ''name''<br />
# mount -t ''fstype'' /dev/mapper/''name'' /mnt/home<br />
<br />
To unmount it:<br />
<br />
# umount /mnt/home<br />
# cryptsetup close ''name''<br />
<br />
{{Tip|[[GVFS]] can also mount encrypted partitions. One can use a file manager with gvfs support (e.g. [[Thunar]]) to mount the partition, and a password dialog will pop-up. For other desktops, {{Aur|zulucrypt}} also provides a GUI.}}<br />
<br />
=== Automated unlocking and mounting ===<br />
<br />
There are three different solutions for automating the process of unlocking the partition and mounting its filesystem.<br />
<br />
==== At boot time ====<br />
<br />
Using the {{ic|/etc/crypttab}} configuration file, unlocking happens at boot time by systemd's automatic parsing. This is the recommended solution if you want to use one common partition for all user's home partitions or automatically mount another encrypted block device. <br />
<br />
See [[Dm-crypt/System configuration#crypttab]] for references and [[Dm-crypt/System configuration#Mounting at boot time]] for an example set up. <br />
<br />
==== On user login ====<br />
<br />
Using ''pam_exec'' it is possible to unlock (''cryptsetup open'') the partition on user login: this is the recommended solution if you want to have a single user's home directory on a partition. See [[dm-crypt/Mounting at login]].<br />
<br />
Unlocking on user login is also possible with [[pam_mount]].<br />
<br />
== Loop device ==<br />
<br />
There are two methods for using a loop device as an encrypted container, one using {{ic|losetup}} directly and one without.<br />
<br />
=== Without losetup ===<br />
<br />
Using losetup directly can be avoided completely by doing the following [https://wiki.gentoo.org/wiki/Custom_Initramfs#Encrypted_keyfile]:<br />
<br />
# head -c 20M </dev/urandom >key.img<br />
# cryptsetup --align-payload=1 luksFormat key.img<br />
<br />
Before running {{ic|cryptsetup}}, look at the [[Dm-crypt/Device_encryption#Encryption_options_for_LUKS_mode|Encryption options for LUKS mode]] and [[Disk_encryption#Ciphers_and_modes_of_operation|Ciphers and modes of operation]] first to select your additional desired settings.<br />
<br />
The instructions for opening the device and making the [[file system]] are the same as [[#Partition]].<br />
<br />
Having too small of a file will get you a {{ic|Requested offset is beyond real size of device /dev/loop0}} error, but as a rough reference creating a 4 MiB file will encrypt it successfully. [http://archive.is/VOh2p]<br />
<br />
If creating a larger file, {{ic|dd}} from {{ic|/dev/urandom}} will stop after 32 MiB, requiring the {{ic|1=iflag=fullblock}} option to complete the full write. [https://unix.stackexchange.com/questions/178949/why-does-dd-from-dev-urandom-stops-early]<br />
<br />
Manual mounting and unmounting procedure is equivalent to [[#Manual mounting and unmounting]].<br />
<br />
=== Using losetup ===<br />
<br />
A loop device enables to map a blockdevice to a file with the standard util-linux tool {{ic|losetup}}. The file can then contain a filesystem, which can be used quite like any other filesystem. A lot of users know [[TrueCrypt]] as a tool to create encrypted containers. Just about the same functionality can be achieved with a loopback filesystem encrypted with LUKS and is shown in the following example. <br />
<br />
First, start by creating an encrypted container, using an appropriate [[random number generator]]: <br />
<br />
# head -c 10M </dev/urandom >/bigsecret<br />
<br />
This will create the file {{ic|bigsecret}} with a size of 10 megabytes. <br />
<br />
{{Note|To avoid having to [[Dm-crypt/Device_encryption#Loopback filesystem|resize]] the container later on, make sure to make it larger than the total size of the files to be encrypted, in order to at least also host the associated metadata needed by the internal file system. If you are going to use LUKS mode, its metadata header requires one to two megabytes alone.}}<br />
<br />
Next create the device node {{ic|/dev/loop0}}, so that we can mount/use our container:<br />
<br />
# losetup /dev/loop0 /bigsecret<br />
<br />
{{Note|If it gives you the error {{ic|/dev/loop0: No such file or directory}}, you need to first load the kernel module with {{ic|modprobe loop}}. These days (Kernel 3.2) loop devices are created on demand. Ask for a new loop device with {{ic|# losetup -f}}.}}<br />
<br />
From now on the procedure is the same as for [[#Partition]], except for the fact that the container is already randomised and will not need another secure erasure.<br />
<br />
{{Tip|Containers with ''dm-crypt'' can be very flexible. Have a look at the features and documentation of [[Tomb]]. It provides a ''dm-crypt'' script wrapper for fast and flexible handling.}}<br />
<br />
==== Manual mounting and unmounting ====<br />
To unmount the container:<br />
<br />
# umount /mnt/secret<br />
# cryptsetup close secret<br />
# losetup -d /dev/loop0<br />
<br />
To mount the container again:<br />
<br />
# losetup /dev/loop0 /bigsecret<br />
# cryptsetup open /dev/loop0 secret<br />
# mount -t ext4 /dev/mapper/secret /mnt/secret</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Talk:Avahi&diff=510449Talk:Avahi2018-02-11T06:39:18Z<p>Fylwind: /* mdns_minimal no longer works? */ conflict with systemd-resolved</p>
<hr />
<div>== Warning about its usage? ==<br />
I strongly suggest that Avahi not be used at this time; especially with Win9X on the LAN. Avahi does nothing to help with the network connections and does not offer any services which are not available elsewhere. Worse, it is not complete, and is missing key elements.<br />
<br />
Futher, since all networking configuration is extremely difficult, it is far more advantageous to focus the user on the basics. Unless the user is of advanced understanding of Arch and the inner workings of Linux in general, the use of Avahi is only distracting from the ultimate quest; having a simple and intuitive network and file sharing setup.<br />
<br />
If any user might stumble upon this subject, it would be good to offer appropriate warnings at the begining of the article, and clearly explain the details of the tested situation offered in the article. Obviously it does not work in certain situations, as I can attest.<br />
<br />
Thanks. - [[User:KitchM|KitchM]] 20:51, 3 June 2010 (EDT)<br />
: This comment is quite long. Since Avahi upstream does see itself unstable, so maybe the warning here is not needed. At the same time, the "Not working situations" should be list clearly of cause. --[[User:Fengchao|Fengchao]] ([[User talk:Fengchao|talk]]) 05:49, 18 May 2012 (UTC)<br />
<br />
::The comment was meant to be amplified enough so all could understand all the nuances of the problem. Further, just because upstream thinks it is stable, or even useful, does not make it either. To test if the product works, anyone is free to test it. [[User:KitchM|KitchM]] ([[User talk:KitchM|talk]]) 15:10, 18 May 2012 (UTC)<br />
::: Then please add an objective summary of the current situation. And an list of "Not working situations" based on your experence will help other users as well. -- [[User:Fengchao|Fengchao]] ([[User talk:Fengchao|talk]]) 12:15, 19 May 2012 (UTC)<br />
<br />
== mdns_minimal no longer works? ==<br />
<br />
From the install notes:<br />
<br />
==> Please note that due to security reasons from version 0.9 on the <br />
minimal mDNS stack included in nss-mdns (dubbed "legacy") is no <br />
longer built - nss-mdns will not work unless Avahi is running.<br />
==> To enable IPv4 multicast DNS lookups, append 'mdns4' to the hosts line<br />
in /etc/nsswitch.conf. Use 'mdns6' for IPv6 or 'mdns' for both.<br />
<br />
[[User:Tad|Tad]] ([[User talk:Tad|talk]]) 06:40, 14 April 2016 (UTC)<br />
<br />
:I think the installation message is incorrect, because the minimal modules are included in the package. I have opened a bug report: {{bug|48935}}. -- [[User:Lonaowna|Lonaowna]] ([[User talk:Lonaowna|talk]]) 11:26, 14 April 2016 (UTC)<br />
<br />
::Ok... apparently "the minimal mDNS stack" and mdns_minimal are two different things, and the installation message is about something else than mdns_minimal. -- [[User:Lonaowna|Lonaowna]] ([[User talk:Lonaowna|talk]]) 14:59, 14 April 2016 (UTC)<br />
<br />
:::Is mDNS still necessary? It seems systemd-resolved has built-in support for it. Enabling mDNS as this article describes now causes the error message: {{ic|*** WARNING: Detected another IPv4 mDNS stack running on this host. This makes mDNS unreliable and is thus not recommended. ***}}<br />
<br />
==Don't Merge Avahi print service/CUPS with Airport/Airprint==<br />
<br />
There is no logical relationship. AirPort/AirPrint is something separate and distinct from creating an Avahi service file to make printers available to wireless clients. Avahi and its services are not in any way related. 'AirPort' is an apple product you buy, Configuring an Avahi service to make a printer available -- is something you can do with Avahi. Make sense that would stay on the Avahi page.<br />
<br />
[[User:Drankinatty|David C. Rankin, J.D.,P.E. -- Rankin Law Firm, PLLC]] ([[User talk:Drankinatty|talk]]) 06:17, 29 July 2017 (UTC)</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Talk:Haskell&diff=491271Talk:Haskell2017-09-25T08:13:29Z<p>Fylwind: /* Section: "Building statically linked packages with Cabal (without using shared libraries)" */ re</p>
<hr />
<div><br />
== Stack for package management? ==<br />
The page currently only mentions cabal-install. [http://haskellstack.org/ Stack] seems to be an easier way of setting up Haskell environments and getting dependencies (For instance: https://hackage.haskell.org/package/turtle-1.2.8/docs/Turtle-Tutorial.html) [[User:Crasm|Crasm]] ([[User talk:Crasm|talk]]) 22:21, 30 July 2016 (UTC)<br />
<br />
<br />
<br />
- I made more clear Stack is available as an alternative build too, but I tried to imply on the first sentence that you can also use Stack if you want: "You can use Stack but..." but I was focusing on explaining how to get a cabal-install that works and links statically.<br />
<br />
- About using stack from the repo (https://www.archlinux.org/packages/community/x86_64/stack/) or the upstream version manually installed, is about if having any haskell-* package installed is incompatible with this new cabal-install we are building. We'd need to check, because maybe installing stack from the repo and bringing those haskell-* packages doesn't affect the linking. Otherwise I was trying to explain how to build a cabal-install in a clean environment. [[User:Jimenezrick|Jimenezrick]] ([[User talk:Jimenezrick|talk]]) 17:59, 28 August 2017 (UTC)<br />
<br />
== Section: "Building statically linked packages with Cabal (without using shared libraries)" ==<br />
<br />
There's an easier way to install statically linked packages using Cabal, as described in the article. Therefore, I think this section is no longer necessary. --[[User:Fylwind|Fylwind]] ([[User talk:Fylwind|talk]]) 22:02, 24 September 2017 (UTC)<br />
<br />
:Regardless, please read [[ArchWiki:Contributing#Do not make complex edits at once]] and follow it in the future. The diff for your [https://wiki.archlinux.org/index.php?title=Haskell&diff=next&oldid=491214 last edit] is almost perfect anti-example for this rule. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 05:51, 25 September 2017 (UTC)<br />
<br />
::Sorry, I'll keep that in mind in the future. --[[User:Fylwind|Fylwind]] ([[User talk:Fylwind|talk]]) 08:13, 25 September 2017 (UTC)</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Talk:Haskell&diff=491224Talk:Haskell2017-09-24T22:02:41Z<p>Fylwind: /* Section: "Building statically linked packages with Cabal (without using shared libraries)" */ new section</p>
<hr />
<div><br />
== Stack for package management? ==<br />
The page currently only mentions cabal-install. [http://haskellstack.org/ Stack] seems to be an easier way of setting up Haskell environments and getting dependencies (For instance: https://hackage.haskell.org/package/turtle-1.2.8/docs/Turtle-Tutorial.html) [[User:Crasm|Crasm]] ([[User talk:Crasm|talk]]) 22:21, 30 July 2016 (UTC)<br />
<br />
<br />
<br />
- I made more clear Stack is available as an alternative build too, but I tried to imply on the first sentence that you can also use Stack if you want: "You can use Stack but..." but I was focusing on explaining how to get a cabal-install that works and links statically.<br />
<br />
- About using stack from the repo (https://www.archlinux.org/packages/community/x86_64/stack/) or the upstream version manually installed, is about if having any haskell-* package installed is incompatible with this new cabal-install we are building. We'd need to check, because maybe installing stack from the repo and bringing those haskell-* packages doesn't affect the linking. Otherwise I was trying to explain how to build a cabal-install in a clean environment. [[User:Jimenezrick|Jimenezrick]] ([[User talk:Jimenezrick|talk]]) 17:59, 28 August 2017 (UTC)<br />
<br />
== Section: "Building statically linked packages with Cabal (without using shared libraries)" ==<br />
<br />
There's an easier way to install statically linked packages using Cabal, as described in the article. Therefore, I think this section is no longer necessary. --[[User:Fylwind|Fylwind]] ([[User talk:Fylwind|talk]]) 22:02, 24 September 2017 (UTC)</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Haskell&diff=491223Haskell2017-09-24T22:00:36Z<p>Fylwind: Explain the static linkage problem better and offer simpler solution. Mention "stack". Remove outdated "cabal is not package manager" slogan. Keep package management factual and avoid recommendations.</p>
<hr />
<div>[[Category:Programming languages]]<br />
[[ja:Haskell]]<br />
[http://www.haskell.org Haskell] is a general purpose, purely functional, programming language.<br />
<br />
== Installation ==<br />
<br />
Haskell generates machine code that can be run natively on Linux. There is nothing special required to run a binary (already compiled) software, like the ones provided in the [[official repositories]] or by the [[ArchHaskell]] group. On the other side, [[AUR]] packages or source codes requires a compiler to build the software.<br />
<br />
Installing the compiler alone permits to build Haskell source code. A few additional tools are needed for development work.<br />
<br />
=== Compiler ===<br />
<br />
To build a Haskell source code into native code, a compiler must be installed. There are several [http://www.haskell.org/haskellwiki/Implementations implementations available], but the one used most (which is now ''de facto'' the reference) is the GHC (Glasgow Haskell Compiler). It is available in the official repositories as {{Pkg|ghc}}.<br />
<br />
You can try it with the following file:<br />
<br />
{{hc|Main.hs|main &#61; putStrLn "Hello, World"}}<br />
<br />
and by running:<br />
<br />
{{hc|<br />
$ ghc -dynamic Main.hs<br />
$ ./Main |<br />
Hello, World<br />
}}<br />
<br />
== Problems with linking ==<br />
<br />
Since version [https://git.archlinux.org/svntogit/community.git/commit/trunk?h=packages/ghc&id=7a948cdfb808afd3ce6f93047ae0dc1778e79f9f 8.0.2-1], the Arch {{Pkg|ghc}} package no longer installs static versions of the GHC boot libraries by default, nor do any of the [https://www.archlinux.org/packages/?q=haskell haskell-*] packages in ''community''. Therefore, to link successfully one must pass the {{ic|-dynamic}} flag to GHC, as the default is to use static linking. For Cabal, this amounts to the following configuration:<br />
<br />
{{bc|<br />
cabal configure --disable-library-vanilla --enable-shared --enable-executable-dynamic<br />
}}<br />
<br />
* {{ic|--disable-library-vanilla}} suppresses the creation of static libraries (if your project contains a library).<br />
* {{ic|--enable-shared}} enables the creation of shared libraries (if your project contains a library).<br />
* {{ic|--enable-executable-dynamic}} causes dynamic linking to be used for executables (if your project contains executables).<br />
<br />
You can also set these flags in {{ic|~/.cabal/config}} so that it applies to all projects by default:<br />
<br />
{{hc|~/.cabal/config|<br />
library-vanilla: False<br />
shared: True<br />
enable-executable-dynamic: True<br />
}}<br />
<br />
Dynamic linking is used for most Haskell modules packaged through [[pacman]] and some packages in the [[AUR]]. Since GHC provides no [[w:Application binary interface|ABI]] compatibility between compiler releases, static linking is often the preferred option for local development outside of the package system.<br />
<br />
{{Note|In the context of this article, static linking does not mean generating completely static ELF binaries. Only Haskell code will be linked statically into a single ELF binary, which may be dynamically linked to other system libraries such as ''glibc''.}}<br />
<br />
=== Static linking ===<br />
<br />
To use static linking, one must, at minimum, install the static boot libraries through the {{Pkg|ghc-static}} package. This would allow you to build projects that depend exclusively on the boot libraries as well as any library that is not installed through the {{ic|haskell-*}} packages.<br />
<br />
Unfortunately, if your project depends on any of the {{ic|haskell-*}} packages that you have installed, Cabal does not take the absence of static libraries into account during dependency resolution. As a result, it will try to use the existing {{ic|haskell-*}} package and then fail with [https://bugs.archlinux.org/task/54563#comment158808 linker errors] when it realizes the static libraries are missing. Unlike {{ic|ghc-static}}, there are no “{{ic|haskell-*-static}}” packages to fix this problem.<br />
<br />
To work around this problem, you can install {{AUR|ghc-pristine}}, which wraps over an existing GHC installation to create a separate GHC distribution in {{ic|/usr/share/ghc-pristine}}, with a package database that contains only boot libraries. Then, to build software with static linking, one simply needs to invoke the wrapped compiler {{ic|/usr/share/ghc-pristine/bin/ghc}}. For Cabal, this amounts to the following configuration:<br />
<br />
{{bc|<br />
1=cabal configure --with-compiler=/usr/share/ghc-pristine<br />
}}<br />
<br />
This can be made permanent by editing {{ic|~/.cabal/config}}. Be aware that you still need {{ic|ghc-static}}.<br />
<br />
Alternatives to {{ic|ghc-pristine}}:<br />
<br />
* One could manually run {{ic|cabal install --force-reinstalls}} to shadow the corresponding {{ic|haskell-*}} packages. This can be tedious as you must explicitly enumerate all transitive dependencies that coincide with an existing {{ic|haskell-*}} package.<br />
* Use a completely separate GHC distribution: download the official Linux binaries for [https://www.haskell.org/ghc/ GHC] and [https://www.haskell.org/cabal/download.html cabal-install] and unpack them somewhere else. This is in effect what {{ic|ghc-pristine}} does, but {{ic|ghc-pristine}} uses less disk space.<br />
<br />
=== Building statically linked packages with Cabal (without using shared libraries) ===<br />
<br />
This section explains how to install {{ic|cabal-install}} but from [https://hackage.haskell.org/package/cabal-install Hackage] instead of the official {{Pkg|cabal-install}} package from the repositories. This {{ic|cabal-install}} will build Haskell packages without using [https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/shared_libs.html shared libraries] unlike the official {{Pkg|cabal-install}} which requires you to link dynamically.<br />
<br />
In theory with any {{ic|cabal-install}} you could choose between both methods, static and dynamic, for linking your Haskell code. In practice because in Arch some basic Haskell libraries ({{ic|haskell-*}} packages) are provided as shared objects ({{ic|.so}} files) and those libraries are globally registered in Cabal, it has trouble using the same libraries for static linking. To avoid linking [https://bugs.archlinux.org/task/54563#comment158826 errors], it's also especially important to not to mix statically and dynamically Haskell packages installed on the same system, as Cabal doesn't fetch a required package once it has been globally registered (check them with the command {{ic|ghc-pkg list}}) in one of its forms and not the other (independently of the linking type of the package that it's needed).<br />
<br />
For these reasons, '''you have to make sure''' that the only two related Haskell packages you have installed are {{Pkg|ghc}}, the compiler, and {{Pkg|ghc-static}}, the boot libraries on its static form, (not {{Pkg|stack}}, {{Pkg|cabal-helper}}, {{Pkg|cabal-install}} and none of the {{ic|haskell-*}} dynamic libraries [https://www.archlinux.org/packages/?q=haskell- available] in the official repositories).<br />
<br />
You can also use [https://www.haskellstack.org/ Stack] as an alternative build tool for Haskell packages, which will link statically by default. But if you still want to use Cabal to build using static linking, follow the next steps of this section to install your own compiled {{ic|cabal-install}} from Hackage. For this purpose we are going to use the tool [https://haskellstack.org/ Stack] that will help us fetching all the dependencies required and building your own {{ic|cabal-install}}.<br />
<br />
First you have to install {{AUR|stack-static}} because you'll use it to bootstrap the compilation of your own Cabal and you don't want to pull as dependencies those packages from the official Arch repositories containing the {{ic|haskell-*}} dynamic libraries.<br />
<br />
Then prepare Stack downloading the package index. Stack will be used with the only purpose of bootstrapping the compilation of your own {{ic|cabal-install}} but using the already installed {{Pkg|ghc}} compiler:<br />
$ stack setup --system-ghc<br />
<br />
Now install your own {{ic|cabal-install}}:<br />
$ stack install --system-ghc cabal-install<br />
<br />
This newly installed {{ic|cabal-install}} has been compiled without shared libraries and won't use them when building packages by default. Also, this {{ic|cabal-install}} will use the installed {{Pkg|ghc}} compiler.<br />
<br />
=== Haskell development tools ===<br />
<br />
To start developing in Haskell easily, one option is the [http://www.haskell.org/platform/ haskell-platform] bundle which is described as:<br />
<br />
:''The easiest way to get started with programming Haskell. It comes with all you need to get up and running. Think of it as "Haskell: batteries included".''<br />
<br />
Although an [[AUR]] package exists ({{AUR|haskell-platform}}{{Broken package link|{{aur-mirror|haskell-platform}}}}), the Haskell Platform can be advantageously replaced by [[installing]] the [https://bbs.archlinux.org/viewtopic.php?pid=1151382#p1151382 following packages] from the [[official repositories]]:<br />
<br />
* ghc ({{Pkg|ghc}}) — Compiler, which only comes with dynamic [https://ghc.haskell.org/trac/ghc/wiki/Commentary/Libraries boot libraries] ({{Pkg|ghc-libs}}). Static boot libraries ({{Pkg|ghc-static}}) must be separately installed.<br />
* cabal-install ({{Pkg|cabal-install}}) — A build tool focused on dependency resolution and sources packages from Hackage<br />
* stack ({{Pkg|stack}}) — A build tool focused on curated snapshots and sources packages from Stackage<br />
* haddock ({{Pkg|haskell-haddock-api}}{{Broken package link|{{aur-mirror|haskell-haddock-api}}}} and {{Pkg|haskell-haddock-library}}) — Tools for generating documentation<br />
* alex ({{Pkg|alex}}) — Lexical analyzer generator<br />
* happy ({{Pkg|happy}}) — Parser generator<br />
<br />
Alternatively, you can use {{Pkg|stack}} to manage your Haskell environment by following the [https://docs.haskellstack.org/en/stable/install_and_upgrade/#arch-linux Arch Linux install instructions].<br />
<br />
== Managing Haskell packages ==<br />
<br />
Many Haskell libraries and executables are grouped in packages. They are all available on [http://hackage.haskell.org Hackage], and a subset of them is curated on [https://www.stackage.org Stackage]. To install and manage these packages, several methods are available:<br />
<br />
* Either (but not both):<br />
** [[Official repositories]], or<br />
** [[ArchHaskell|ArchHaskell repository]]<br />
* [[#cabal-install|cabal-install]]<br />
* [[#stack|stack]]<br />
* [[Arch User Repository]]<br />
<br />
[https://github.com/magthe/cblrepo cblrepo] is a tool used for maintaining Haskell packages for Linux distributions. A wrapper around this, {{AUR|cabal2pkgbuild-git}}{{Broken package link|{{aur-mirror|cabal2pkgbuild-git}}}}, can create PKGBUILD files from Hackage packages. See [[Haskell package guidelines]] for more information on ''creating new'' Haskell packages.<br />
<br />
=== Pros/Cons of the different methods ===<br />
<br />
The following table documents the advantages and disadvantages of different package management styles.<br />
<br />
{| class="wikitable"<br />
! '''Method'''<br />
! '''Pros'''<br />
! '''Cons'''<br />
|-<br />
| [[Official repositories]] || Provided by ArchLinux developers, consistent versions of packages, already compiled || Only a few packages available, only dynamic libraries available<br />
|-<br />
| [[#ArchHaskell repository|ArchHaskell repository]] || Provided by ArchHaskell group, consistent versions of packages, already compiled || Need manual intervention to get started with<br />
|-<br />
| [[#cabal-install|cabal-install]] || All packages available, root not required || Installed in home directory, [http://www.haskell.org/haskellwiki/Cabal/Survival#What_is_the_difficulty_caused_by_Cabal-install.3F failures in dependency resolution], difficult to remove specific packages<br />
|-<br />
| [[#stack|stack]] || All packages available (favors Stackage), root not required || Installed in home directory, versions are pinned to snapshot, difficult to remove specific packages<br />
|-<br />
| [[Arch User Repository]] || Simple to get started || Risk of unmaintained or orphaned packages, incompatible versions of packages possible<br />
|-<br />
|}<br />
<br />
=== ArchHaskell repository ===<br />
<br />
See [[ArchHaskell]] for details.<br />
<br />
=== cabal-install ===<br />
<br />
{{Pkg|cabal-install}} is available from the [[official repositories]].<br />
<br />
{{Note|{{ic|cabal-install}} is the package that contains the "cabal" command-line utility, whereas {{ic|Cabal}} is the package that provides the "Cabal" library, used by both cabal-install and stack.}}<br />
<br />
==== Preparation and $PATH ====<br />
<br />
To run user-wide executables installed by cabal-install, {{ic|~/.cabal/bin}} must be added to the {{ic|$PATH}} variable. That can be done by putting the following line in your shell configuration file, for instance {{ic|~/.bashrc}} for {{Pkg|bash}} or {{ic|~/.zshrc}} for {{Pkg|zsh}}:<br />
{{bc|PATH&#61;$PATH:~/.cabal/bin}}<br />
<br />
==== Installing packages user-wide ====<br />
<br />
{{bc|<br />
1=$ cabal update<br />
<br />
$ # Dynamic linking<br />
$ cabal install --disable-library-vanilla --enable-shared --enable-executable-dynamic ''<pkg>''<br />
<br />
$ # Static linking (requires ghc-static and ghc-pristine)<br />
$ cabal install --with-compiler=/usr/share/ghc-pristine/bin/ghc ''<pkg>''<br />
}}<br />
<br />
It is possible to install a package system-wide with the {{ic|--global}} flag, but this is '''strongly discouraged'''. With the user-wide install, all files are kept in {{ic|~/.cabal}} and libraries are registered to {{ic|~/.ghc}}, offering the possibility to do a clean-up easily by simply removing these folders. With system-wide install, the files will be dispersed in the file system and difficult to manage.<br />
<br />
==== Sandboxes ====<br />
<br />
Cabal sandboxes provide a ''consistent'' local package database and environment (similar to virtual-env in Python or rvm in Ruby). To create a sandbox in the current directory, run:<br />
<br />
{{bc|cabal sandbox init}}<br />
<br />
It can be later removed using {{bc|cabal sandbox delete}}<br />
<br />
By default, if the current directory contains a sandbox, cabal will take advantage of it for installation, so you can follow the same steps as [[#Installing packages user-wide]]. If you want to use a sandbox elsewhere, you can – while the current directory contains the sandbox – run {{ic|cabal exec "$SHELL"}} to start a sandbox-aware shell. Then you can change the directory to wherever you want, and cabal will still use the sandbox. Alternatively, you can pass the {{ic|1=--sandbox-config-file=''/somewhere''/cabal.sandbox.config}} flag to cabal.<br />
<br />
To run executables within a cabal sandbox, you must also set {{bc|PATH&#61;$PATH:$PWD/.cabal-sandbox/bin}} or start a local shell with {{ic|cabal exec "$SHELL"}}.<br />
<br />
==== Removing packages ====<br />
There is no easy way to do it. Cabal does not have removing process.<br />
<br />
Consider installing to a sandbox instead, which can be deleted without affecting other sandboxes or your user-wide installation.<br />
<br />
One thing to make your life easier is use zsh auto completion to find all the haskell packages.<br />
<br />
If you want/can fix/reinstall whole user-wide Haskell package system - remove {{ic|~/.cabal}} and {{ic|~/.ghc}} and start from scratch. This is often necessary when GHC is upgraded.<br />
<br />
=== stack ===<br />
<br />
[https://haskellstack.org Stack] is a build tool that focuses on automatically curated, consistent package sets rather than dependency resolution. This means it's easy to install a set of packages without concern of version conflicts as long as they co-exist within a given Stackage snapshot. It can be installed through either {{Pkg|stack}} or {{AUR|stack-static}}. The latter provides statically linked binaries, thereby avoiding dozens of {{ic|haskell-*}} dependencies. More information can be found at [https://docs.haskellstack.org/en/stable/install_and_upgrade/#arch-linux § Install/upgrade # Arch Linux].<br />
<br />
== See also ==<br />
<br />
*[http://learnyouahaskell.com/ Learn You a Haskell for Great Good!]<br />
*[http://book.realworldhaskell.org/ Real World Haskell]</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Template_talk:Pkg&diff=491220Template talk:Pkg2017-09-24T21:19:57Z<p>Fylwind: /* Inaccurate note */ new section</p>
<hr />
<div>== Inaccurate note ==<br />
<br />
I don't think the note is accurate (appears to have been fixed already?). --[[User:Fylwind|Fylwind]] ([[User talk:Fylwind|talk]]) 21:19, 24 September 2017 (UTC)</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Haskell&diff=491214Haskell2017-09-24T19:43:15Z<p>Fylwind: /* Haskell development tools */ Document the recent split: ghc → ghc + ghc-libs</p>
<hr />
<div>[[Category:Programming languages]]<br />
[[ja:Haskell]]<br />
[http://www.haskell.org Haskell] is a general purpose, purely functional, programming language.<br />
<br />
== Installation ==<br />
<br />
Haskell generates machine code that can be run natively on Linux. There is nothing special required to run a binary (already compiled) software, like the ones provided in the [[official repositories]] or by the [[ArchHaskell]] group. On the other side, [[AUR]] packages or source codes requires a compiler to build the software.<br />
<br />
Installing the compiler alone permits to build Haskell source code. A few additional tools are needed for development work.<br />
<br />
=== Compiler ===<br />
<br />
To build a Haskell source–code into native–code, a compiler must be installed. There are several [http://www.haskell.org/haskellwiki/Implementations implementations available], but the one used most (which is now ''de facto'' the reference) is the GHC (Glasgow Haskell Compiler). It is available in the official repositories as {{Pkg|ghc}}.<br />
<br />
You can try it with the following file:<br />
<br />
{{hc|Main.hs|main &#61; putStrLn "Hello, World"}}<br />
<br />
and by running:<br />
<br />
{{hc|<br />
$ ghc -dynamic Main.hs<br />
$ ./Main |<br />
Hello, World<br />
}}<br />
<br />
=== Problems with linking ===<br />
<br />
GHC uses static linking by default and the {{ic|-dynamic}} flag is needed to select dynamic linking. Since version [https://git.archlinux.org/svntogit/community.git/commit/trunk?h=packages/ghc&id=7a948cdfb808afd3ce6f93047ae0dc1778e79f9f 8.0.2-1], the Arch {{Pkg|ghc}} package no longer contains static versions of the GHC boot libraries by default, nor do any of the {{ic|haskell-*}} packages . Static versions of the GHC boot libraries may be installed separately through the {{Pkg|ghc-static}} package, but no such equivalent exists for the {{ic|haskell-*}} packages. Therefore, without {{ic|-dynamic}} Haskell code and packages will generally fail to link unless the program depends only on boot packages and locally installed packages and {{Pkg|ghc-static}} is installed.<br />
<br />
This also causes issues with Cabal trying to use the default static linking. To force dynamic linking in Cabal, edit {{ic|~/.cabal/config}} and add the line {{ic|executable-dynamic: True}}.<br />
<br />
Dynamic linking is used for most Haskell modules packaged through [[pacman]] and is common for packages in the [[AUR]]. Since GHC provides no [[w:Application binary interface|ABI]] compatibility between compiler releases, static linking is often the preferred option for local development outside of the package system.<br />
<br />
=== Building statically linked packages with Cabal (without using shared libraries) ===<br />
<br />
This section explains how to install {{ic|cabal-install}} but from [https://hackage.haskell.org/package/cabal-install Hackage] instead of the official {{Pkg|cabal-install}} package from the repositories. This {{ic|cabal-install}} will build Haskell packages without using [https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/shared_libs.html shared libraries] unlike the official {{Pkg|cabal-install}} which requires you to link dynamically.<br />
<br />
{{Note|In the context of this section, static linking does not mean generating completely static ELF binaries. Only Haskell code will be linked statically into a single ELF binary, which may be dynamically linked to other system libraries such as ''glibc''.}}<br />
<br />
In theory with any {{ic|cabal-install}} you could choose between both methods, static and dynamic, for linking your Haskell code. In practice because in Arch some basic Haskell libraries ({{ic|haskell-*}} packages) are provided as shared objects ({{ic|.so}} files) and those libraries are globally registered in Cabal, it has trouble using the same libraries for static linking. To avoid linking [https://bugs.archlinux.org/task/54563#comment158826 errors], it's also especially important to not to mix statically and dynamically Haskell packages installed on the same system, as Cabal doesn't fetch a required package once it has been globally registered (check them with the command {{ic|ghc-pkg list}}) in one of its forms and not the other (independently of the linking type of the package that it's needed).<br />
<br />
For these reasons, '''you have to make sure''' that the only two related Haskell packages you have installed are {{Pkg|ghc}}, the compiler, and {{Pkg|ghc-static}}, the boot libraries on its static form, (not {{Pkg|stack}}, {{Pkg|cabal-helper}}, {{Pkg|cabal-install}} and none of the {{ic|haskell-*}} dynamic libraries [https://www.archlinux.org/packages/?q=haskell- available] in the official repositories).<br />
<br />
You can also use [https://www.haskellstack.org/ Stack] as an alternative build tool for Haskell packages, which will link statically by default. But if you still want to use Cabal to build using static linking, follow the next steps of this section to install your own compiled {{ic|cabal-install}} from Hackage. For this purpose we are going to use the tool [https://haskellstack.org/ Stack] that will help us fetching all the dependencies required and building your own {{ic|cabal-install}}.<br />
<br />
First you have to install {{AUR|stack-static}} because you'll use it to bootstrap the compilation of your own Cabal and you don't want to pull as dependencies those packages from the official Arch repositories containing the {{ic|haskell-*}} dynamic libraries.<br />
<br />
Then prepare Stack downloading the package index. Stack will be used with the only purpose of bootstrapping the compilation of your own {{ic|cabal-install}} but using the already installed {{Pkg|ghc}} compiler:<br />
$ stack setup --system-ghc<br />
<br />
Now install your own {{ic|cabal-install}}:<br />
$ stack install --system-ghc cabal-install<br />
<br />
This newly installed {{ic|cabal-install}} has been compiled without shared libraries and won't use them when building packages by default. Also, this {{ic|cabal-install}} will use the installed {{Pkg|ghc}} compiler.<br />
<br />
=== Haskell development tools ===<br />
<br />
To start developing in Haskell easily, one option is the [http://www.haskell.org/platform/ haskell-platform] bundle which is described as:<br />
<br />
:''The easiest way to get started with programming Haskell. It comes with all you need to get up and running. Think of it as "Haskell: batteries included".''<br />
<br />
Although an [[AUR]] package exists ({{AUR|haskell-platform}}{{Broken package link|{{aur-mirror|haskell-platform}}}}), the Haskell Platform can be advantageously replaced by [[installing]] the [https://bbs.archlinux.org/viewtopic.php?pid=1151382#p1151382 following packages] from the [[official repositories]]:<br />
<br />
* ghc ({{Pkg|ghc}}) — Compiler, which only comes with dynamic [https://ghc.haskell.org/trac/ghc/wiki/Commentary/Libraries boot libraries] ({{Pkg|ghc-libs}}). Static boot libraries ({{Pkg|ghc-static}}) must be separately installed.<br />
* cabal-install ({{Pkg|cabal-install}}) — A command line interface for ''Cabal'' and ''Hackage''<br />
* haddock ({{Pkg|haskell-haddock-api}}{{Broken package link|{{aur-mirror|haskell-haddock-api}}}} and {{Pkg|haskell-haddock-library}}) — Tools for generating documentation<br />
* happy ({{Pkg|happy}}) — Parser generator<br />
* alex ({{Pkg|alex}}) — Lexical analyzer generator<br />
<br />
Alternatively, you can use {{Pkg|stack}} to manage your Haskell environment by following the [https://docs.haskellstack.org/en/stable/install_and_upgrade/#arch-linux Arch Linux install instructions].<br />
<br />
== Managing Haskell packages ==<br />
<br />
{{Expansion|[https://haskellstack.org/ Stack utility] and [https://www.stackage.org/ Stackage repository] already have adoption in Haskell world. If you familiar with them, please provide description.}}<br />
<br />
Many Haskell libraries and executables are grouped in packages. They are all available on [http://hackage.haskell.org Hackage]. To install and manage these packages, several methods are available and unusual ones are explained in the rest of this section.<br />
<br />
The recommended workflow is the following:<br />
* [[Official repositories]] or [[ArchHaskell|ArchHaskell repository]] as principal source of Haskell packages (the ''or'' is exclusive here)<br />
* [[#cabal-install|cabal-install]] (possibly with sandboxes) for Haskell development<br />
* [[Arch User Repository]] for packages that are not available elsewhere<br />
<br />
[https://github.com/magthe/cblrepo cblrepo] is a tool used for maintaining Haskell packages for Linux distributions. A wrapper around this, {{AUR|cabal2pkgbuild-git}}{{Broken package link|{{aur-mirror|cabal2pkgbuild-git}}}}, can create PKGBUILD files from Hackage packages. See [[Haskell package guidelines]] for more information on ''creating new'' Haskell packages.<br />
<br />
=== Pros/Cons of the different methods ===<br />
<br />
The following table documents the advantages and disadvantages of different package management styles.<br />
<br />
{| class="wikitable"<br />
! '''Method'''<br />
! '''Pros'''<br />
! '''Cons'''<br />
|-<br />
| [[Official repositories]] || Provided by ArchLinux developers, consistent versions of packages, already compiled || Only a few packages available<br />
|-<br />
| [[#ArchHaskell repository|ArchHaskell repository]] || Provided by ArchHaskell group, consistent versions of packages, already compiled || Need manual intervention to get started with<br />
|-<br />
| [[#cabal-install|cabal-install]] || All packages available || Installed in home folder, {{Pkg|cabal-install}} [https://ivanmiljenovic.wordpress.com/2010/03/15/repeat-after-me-cabal-is-not-a-package-manager is not a package manager], incompatible versions of packages possible (aka. [http://www.haskell.org/haskellwiki/Cabal/Survival#What_is_the_difficulty_caused_by_Cabal-install.3F cabal hell])<br />
|-<br />
| [[Arch User Repository]] || Simple to get started || Risk of unmaintained or orphaned packages, incompatible versions of packages possible<br />
|-<br />
|}<br />
<br />
=== ArchHaskell repository ===<br />
<br />
See [[ArchHaskell]] for details.<br />
<br />
=== cabal-install ===<br />
<br />
{{warning|Discouraged method, keep in mind that {{Pkg|cabal-install}} [https://ivanmiljenovic.wordpress.com/2010/03/15/repeat-after-me-cabal-is-not-a-package-manager is not a package manager].}}<br />
<br />
{{Note|The only exception is for Haskell development, where {{Pkg|cabal-install}} is the recommended tool. Since version 1.18, cabal provides a ''sandbox'' system that permits to isolate different versions of libraries for different projects. There is an introduction to cabal sandbox [http://coldwa.st/e/blog/2013-08-20-Cabal-sandbox.html here].}}<br />
<br />
==== Preparation and $PATH ====<br />
Install {{Pkg|cabal-install}} from the [[official repositories]].<br />
<br />
To run installed executables without specifying the path, the cabal binary folder {{ic|~/.cabal/bin}} must be added to the {{ic|$PATH}} variable. That can be done by putting the following line in your shell configuration file, for instance {{ic|~/.bashrc}} for {{Pkg|bash}} or {{ic|~/.zshrc}} for {{Pkg|zsh}}:<br />
{{bc|PATH&#61;$PATH:~/.cabal/bin}}<br />
To run executables within a cabal sandbox, you must also add {{bc|PATH&#61;$PATH:.cabal-sandbox/bin}}<br />
<br />
==== Installing packages ====<br />
{{bc|<br />
$ cabal update<br />
<br />
$ # When using ghc-static<br />
$ cabal install <pkg><br />
<br />
$ # When using ghc<br />
$ cabal install\<br />
--enable-shared<br />
--enable-executable-dynamic<br />
--ghc-options&asymp;-dynamic<br />
<pkg><br />
}}<br />
<br />
It is possible to install a package system–wide with the {{ic|--global}} flag, but this is '''strongly discouraged'''. With the user–wide install, all files are kept in {{ic|~/.cabal}} and libraries are registered to {{ic|~/.ghc}}, offering the possibility to do a clean-up easily by simply removing these folders. With system–wide install, the files will be dispersed in the file system and difficult to manage.<br />
<br />
==== Removing packages ====<br />
There is no easy way to do it. Cabal does not have removing process.<br />
<br />
One thing to make your life easier is use zsh auto completion to find all the haskell packages.<br />
<br />
If you want/can fix/reinstall whole Haskell package system - remove {{ic|~/.cabal}} and {{ic|~/.ghc}} and start from scratch.<br />
<br />
== See also ==<br />
<br />
*[http://learnyouahaskell.com/ Learn You a Haskell for Great Good!]<br />
*[http://book.realworldhaskell.org/ Real World Haskell]</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Haskell&diff=487902Haskell2017-08-28T20:34:17Z<p>Fylwind: /* Problems with linking */ Clarify that there's no static libs for the haskell-* packages</p>
<hr />
<div>[[Category:Programming languages]]<br />
[[ja:Haskell]]<br />
[http://www.haskell.org Haskell] is a general purpose, purely functional, programming language.<br />
<br />
== Installation ==<br />
<br />
Haskell generates machine code that can be run natively on Linux. There is nothing special required to run a binary (already compiled) software, like the ones provided in the [[official repositories]] or by the [[ArchHaskell]] group. On the other side, [[AUR]] packages or source codes requires a compiler to build the software.<br />
<br />
Installing the compiler alone permits to build Haskell source code. A few additional tools are needed for development work.<br />
<br />
=== Compiler ===<br />
<br />
To build a Haskell source–code into native–code, a compiler must be installed. There are several [http://www.haskell.org/haskellwiki/Implementations implementations available], but the one used most (which is now ''de facto'' the reference) is the GHC (Glasgow Haskell Compiler). It is available in the official repositories as {{Pkg|ghc}}.<br />
<br />
You can try it with the following file:<br />
<br />
{{hc|Main.hs|main &#61; putStrLn "Hello, World"}}<br />
<br />
and by running:<br />
<br />
{{hc|<br />
$ ghc -dynamic Main.hs<br />
$ ./Main |<br />
Hello, World<br />
}}<br />
<br />
=== Problems with linking ===<br />
<br />
GHC uses static linking by default and the {{ic|-dynamic}} flag is needed to select dynamic linking. Since version [https://git.archlinux.org/svntogit/community.git/commit/trunk?h=packages/ghc&id=7a948cdfb808afd3ce6f93047ae0dc1778e79f9f 8.0.2-1], the Arch {{Pkg|ghc}} package no longer contains static versions of the GHC boot libraries by default, nor do any of the {{ic|haskell-*}} packages . Static versions of the GHC boot libraries may be installed separately through the {{Pkg|ghc-static}} package, but no such equivalent exists for the {{ic|haskell-*}} packages. Therefore, without {{ic|-dynamic}} Haskell code and packages will generally fail to link unless the program depends only on boot packages and locally installed packages and {{Pkg|ghc-static}} is installed.<br />
<br />
This also causes issues with Cabal trying to use the default static linking. To force dynamic linking in Cabal, edit {{ic|~/.cabal/config}} and add the line {{ic|executable-dynamic: True}}.<br />
<br />
Dynamic linking is used for most Haskell modules packaged through [[pacman]] and is common for packages in the [[AUR]]. Since GHC provides no [[w:Application binary interface|ABI]] compatibility between compiler releases, static linking is often the preferred option for local development outside of the package system.<br />
<br />
=== Using Cabal with static linking ===<br />
<br />
{{Accuracy|There is the {{Pkg|stack}} package, linked from the next section as well as upstream documentation. It actually ''depends'' on multiple {{ic|haskell-*}} libraries.}}<br />
<br />
{{Accuracy|There is a difference between "using Cabal for static linking" and "using statically-linked Cabal". Why does this section sound like the latter is necessary for the former?}}<br />
<br />
You can use [https://www.haskellstack.org/ Stack] as an alternative build tool for Haskell packages, which will link statically by default, but if you still want to use Cabal to build using static linking follow these steps. You'll need to install your own copy of {{Pkg|cabal-install}}. '''You have to make sure''' the only two related Haskell packages you have installed are {{Pkg|ghc}} and {{Pkg|ghc-static}} (no {{Pkg|cabal-helper}}, {{Pkg|cabal-install}} and none of the {{ic|haskell-*}} dynamic libraries [https://www.archlinux.org/packages/?q=haskell- available] in the official repositories).<br />
<br />
First you have to [https://docs.haskellstack.org/en/stable/README/#how-to-install install Stack] from upstream because you'll use it to bootstrap the compilation of your own Cabal and you don't want to pull those packages from the official repositories containing the {{ic|haskell-*}} dynamic libraries.<br />
<br />
Then download a GHC compiler with Stack:<br />
$ stack setup<br />
<br />
Now install your own {{Pkg|cabal-install}}:<br />
$ stack install cabal-install<br />
<br />
As long as you use this Cabal for installing everything, it will link statically.<br />
<br />
=== Haskell development tools ===<br />
<br />
To start developing in Haskell easily, one option is the [http://www.haskell.org/platform/ haskell-platform] bundle which is described as:<br />
<br />
:''The easiest way to get started with programming Haskell. It comes with all you need to get up and running. Think of it as "Haskell: batteries included".''<br />
<br />
Although an [[AUR]] package exists ({{AUR|haskell-platform}}{{Broken package link|{{aur-mirror|haskell-platform}}}}), the Haskell Platform can be advantageously replaced by [[installing]] the [https://bbs.archlinux.org/viewtopic.php?pid=1151382#p1151382 following packages] from the [[official repositories]]:<br />
<br />
* ghc ({{Pkg|ghc}} and {{Pkg|ghc-static}}) — Compiler with dynamic [https://ghc.haskell.org/trac/ghc/wiki/Commentary/Libraries boot libraries], and supplementary static boot libraries<br />
* cabal-install ({{Pkg|cabal-install}}) — A command line interface for ''Cabal'' and ''Hackage''<br />
* haddock ({{Pkg|haskell-haddock-api}}{{Broken package link|{{aur-mirror|haskell-haddock-api}}}} and {{Pkg|haskell-haddock-library}}) — Tools for generating documentation<br />
* happy ({{Pkg|happy}}) — Parser generator<br />
* alex ({{Pkg|alex}}) — Lexical analyzer generator<br />
<br />
Alternatively, you can use {{Pkg|stack}} to manage your Haskell environment by following the [https://docs.haskellstack.org/en/stable/install_and_upgrade/#arch-linux Arch Linux install instructions].<br />
<br />
== Managing Haskell packages ==<br />
<br />
{{Expansion|[https://haskellstack.org/ Stack utility] and [https://www.stackage.org/ Stackage repository] already have adoption in Haskell world. If you familiar with them, please provide description.}}<br />
<br />
Many Haskell libraries and executables are grouped in packages. They are all available on [http://hackage.haskell.org Hackage]. To install and manage these packages, several methods are available and unusual ones are explained in the rest of this section.<br />
<br />
The recommended workflow is the following:<br />
* [[Official repositories]] or [[ArchHaskell|ArchHaskell repository]] as principal source of Haskell packages (the ''or'' is exclusive here)<br />
* [[#cabal-install|cabal-install]] (possibly with sandboxes) for Haskell development<br />
* [[Arch User Repository]] for packages that are not available elsewhere<br />
<br />
[https://github.com/magthe/cblrepo cblrepo] is a tool used for maintaining Haskell packages for Linux distributions. A wrapper around this, {{AUR|cabal2pkgbuild-git}}{{Broken package link|{{aur-mirror|cabal2pkgbuild-git}}}}, can create PKGBUILD files from Hackage packages. See [[Haskell package guidelines]] for more information on ''creating new'' Haskell packages.<br />
<br />
=== Pros/Cons of the different methods ===<br />
<br />
The following table documents the advantages and disadvantages of different package management styles.<br />
<br />
{| class="wikitable"<br />
! '''Method'''<br />
! '''Pros'''<br />
! '''Cons'''<br />
|-<br />
| [[Official repositories]] || Provided by ArchLinux developers, consistent versions of packages, already compiled || Only a few packages available<br />
|-<br />
| [[#ArchHaskell repository|ArchHaskell repository]] || Provided by ArchHaskell group, consistent versions of packages, already compiled || Need manual intervention to get started with<br />
|-<br />
| [[#cabal-install|cabal-install]] || All packages available || Installed in home folder, {{Pkg|cabal-install}} [https://ivanmiljenovic.wordpress.com/2010/03/15/repeat-after-me-cabal-is-not-a-package-manager is not a package manager], incompatible versions of packages possible (aka. [http://www.haskell.org/haskellwiki/Cabal/Survival#What_is_the_difficulty_caused_by_Cabal-install.3F cabal hell])<br />
|-<br />
| [[Arch User Repository]] || Simple to get started || Risk of unmaintained or orphaned packages, incompatible versions of packages possible<br />
|-<br />
|}<br />
<br />
=== ArchHaskell repository ===<br />
<br />
See [[ArchHaskell]] for details.<br />
<br />
=== cabal-install ===<br />
<br />
{{warning|Discouraged method, keep in mind that {{Pkg|cabal-install}} [https://ivanmiljenovic.wordpress.com/2010/03/15/repeat-after-me-cabal-is-not-a-package-manager is not a package manager].}}<br />
<br />
{{Note|The only exception is for Haskell development, where {{Pkg|cabal-install}} is the recommended tool. Since version 1.18, cabal provides a ''sandbox'' system that permits to isolate different versions of libraries for different projects. There is an introduction to cabal sandbox [http://coldwa.st/e/blog/2013-08-20-Cabal-sandbox.html here].}}<br />
<br />
==== Preparation and $PATH ====<br />
Install {{Pkg|cabal-install}} from the [[official repositories]].<br />
<br />
To run installed executables without specifying the path, the cabal binary folder {{ic|~/.cabal/bin}} must be added to the {{ic|$PATH}} variable. That can be done by putting the following line in your shell configuration file, for instance {{ic|~/.bashrc}} for {{Pkg|bash}} or {{ic|~/.zshrc}} for {{Pkg|zsh}}:<br />
{{bc|PATH&#61;$PATH:~/.cabal/bin}}<br />
To run executables within a cabal sandbox, you must also add {{bc|PATH&#61;$PATH:.cabal-sandbox/bin}}<br />
<br />
==== Installing packages ====<br />
{{bc|<br />
$ cabal update<br />
<br />
$ # When using ghc-static<br />
$ cabal install <pkg><br />
<br />
$ # When using ghc<br />
$ cabal install\<br />
--enable-shared<br />
--enable-executable-dynamic<br />
--ghc-options&asymp;-dynamic<br />
<pkg><br />
}}<br />
<br />
It is possible to install a package system–wide with the {{ic|--global}} flag, but this is '''strongly discouraged'''. With the user–wide install, all files are kept in {{ic|~/.cabal}} and libraries are registered to {{ic|~/.ghc}}, offering the possibility to do a clean-up easily by simply removing these folders. With system–wide install, the files will be dispersed in the file system and difficult to manage.<br />
<br />
==== Removing packages ====<br />
There is no easy way to do it. Cabal does not have removing process.<br />
<br />
One thing to make your life easier is use zsh auto completion to find all the haskell packages.<br />
<br />
If you want/can fix/reinstall whole Haskell package system - remove {{ic|~/.cabal}} and {{ic|~/.ghc}} and start from scratch.<br />
<br />
== See also ==<br />
<br />
*[http://learnyouahaskell.com/ Learn You a Haskell for Great Good!]<br />
*[http://book.realworldhaskell.org/ Real World Haskell]</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Talk:Installation_guide&diff=481671Talk:Installation guide2017-07-11T01:33:06Z<p>Fylwind: /* Consider linking to Install from existing Linux */ Forgot signature</p>
<hr />
<div>== Read this first before adding new suggestions ==<br />
<br />
* The point of this page is to be a ''concise'' checklist of things to be done. Detailed instructions, if they are not specific to the installation process only, belong in wiki articles or upstream documentation describing the respective topics.<br />
* Should you have more complex changes for this guide in mind, create a copy on your user page, and link it here for review; e.g. [[User:Example/Installation guide]].<br />
* systemd tools such as ''hostnamectl'', ''timedatectl'' and ''localectl'' [https://github.com/systemd/systemd/issues/798#issuecomment-126568596 do not work] in the installation chroot environment, so please do not propose to use them in the guide unless you can prove that they have been made to work also in that case. See [https://wiki.archlinux.org/index.php?title=Talk:Beginners%27_guide&oldid=388727#General_problems], [https://wiki.archlinux.org/index.php?title=Talk:Beginners%27_guide&oldid=404695#Replace_commands_with_their_systemd_equivalents], [https://wiki.archlinux.org/index.php?title=Talk:Beginners%27_guide&oldid=418662#Utilizing_systemd_tools] and [https://wiki.archlinux.org/index.php?title=Talk:Installation_guide&oldid=434985#change_configuration_system_from_old_way_to_new_way.28using_systemd_commands.29] for some past discussions about this issue.<br />
* {{ic|localectl list-keymaps}} does not work due to bug {{Bug|46725}}. For the chosen replacement command, see [https://wiki.archlinux.org/index.php?title=Talk:Beginners%27_guide&oldid=435044#localectl].<br />
<br />
-- [[ArchWiki:Administrators|The ArchWiki Administrators]] 22:17, 2 September 2016 (UTC)<br />
__TOC__<br />
<br />
== "See ''foo''" vs "See the ''foo'' article" ==<br />
<br />
:''[Moved from [[Talk:Beginners' guide]]. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 20:29, 12 July 2016 (UTC)]''<br />
<br />
This revision [https://wiki.archlinux.org/index.php?title=Beginners%27_guide&diff=400266&oldid=400243] added a new mention of "See the ''foo'' article", rather than the more common "See ''foo''". I'd argue former is the better form, and when the guide is viewed from a .txt (if the BG/IG merge completes), the longer wording makes sense as well. Are there opinions against using the longer form throughout the BG? -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 00:13, 18 September 2015 (UTC)<br />
<br />
:I'm neutral, so that doesn't count as an opinion against ^^ That said, the long form can only be used with links to entire articles, but more difficultly with links to specific sections such as "See also [[Pacman#pacman crashes the official installation media]]", since in those cases a more natural-sounding long form should be something like "See also the 'pacman crashes the official installation media' section of the [[Pacman]] article", I think, which is clearly ugly to see and use, so consistency is a bit hard to reach. — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 16:13, 18 September 2015 (UTC)<br />
<br />
::I guess the proper solution would be to incorporate links in the article text where possible. "See X" gets repetitive fast, anyway. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 14:44, 29 September 2015 (UTC)<br />
<br />
:I'm actually here because when viewing the text format I was trying to figure out what the heck packages.both was I thought it might have been a meta package or something. -- [[User:Y2kbugger|Y2kbugger]] ([[User talk:Y2kbugger|talk]]) 17:36, 30 October 2016 (UTC)<br />
<br />
::Ideally packages.both would be a file path, but I'm not sure it's present in the live environment. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 18:13, 30 October 2016 (UTC)<br />
<br />
== pacman-key --populate ==<br />
<br />
:''[Moved from [[Talk:Beginners' guide]]. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 20:38, 12 July 2016 (UTC)]''<br />
<br />
Reference: https://wiki.archlinux.org/index.php?title=Beginners%27_guide&diff=next&oldid=411670<br />
I tried to install Archlinux on my new computer and got stuck. Only using the {{ic|pacman-key --populate archlinux}} helped me. I think I am not the only one having this problem. But why did you undo it? {{Unsigned|20:38, 12 December 2015|Sandstorm}}<br />
:This command is already run for the new system (by installation of archlinux-keyring), so running it by hand shouldn't be required for most users. Of course, things can go wrong (how old was the ISO you used to install the system?), but that belongs in Troubleshooting sections of the respective articles, which are linked at the beginning of the guide. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 19:52, 12 December 2015 (UTC)<br />
::I had downloaded the ISO just yesterday, minutes before the install. Only that command installed the keys. Probably I should open a bug if you can confirm the issue?<br />
:::Did you have to run pacman-key after, or before pacstrap? And do you recall what the error messages said exactly? (See also {{Bug|31286}}) -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 20:15, 12 December 2015 (UTC)<br />
::::I had to run after pacstrap. As far as I remember, pacstrap stopped after trying to download the keys. The error message was something like shown in this forum post: https://bbs.archlinux.org/viewtopic.php?id=165367<br />
:::::Well then, as you suggested, I'd open a bug report. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 20:34, 12 December 2015 (UTC)<br />
::::::Done. Could you check if the description is good. I could not find an appropriate category, so I though Packages:Core might be the closest one. https://bugs.archlinux.org/task/47351 --[[User:Sandstorm|Sandstorm]] ([[User talk:Sandstorm|talk]]) 20:48, 12 December 2015 (UTC)<br />
:::::::Thanks, the description looks OK. If the category e.a is not right, [[Special:Contributions/Scimmia|User:Scimmia]] should fix it. :P -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 13:59, 13 December 2015 (UTC)<br />
<br />
::::::::Hmm, looks like it was closed with "Works for me" ... not very enlightening. All I can suggest is to further improve on [[Pacman/Package signing]] and related articles, and recheck if they're accessible enough from the Beginners' guide. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 21:59, 12 February 2016 (UTC)<br />
<br />
== timesyncd: add manual date ==<br />
<br />
:''[Moved from [[Talk:Beginners' guide]]. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 20:44, 12 July 2016 (UTC)]''<br />
<br />
While the right time isn't as important in the live system as in the installed one, it may still be unexpected to users [https://wiki.archlinux.org/index.php?title=Beginners%27_guide&diff=432465&oldid=431268]. We could instead instruct to specify a date explicitly to timedatectl. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 11:25, 6 July 2016 (UTC)<br />
<br />
:Is the issue setting the time manually or just setting the time zone? The change you linked to just had setting the time zone. -- [[User:Rdeckard|Rdeckard]] ([[User_talk:Rdeckard|talk]]) 01:29, 9 July 2016 (UTC)<br />
<br />
::Well, with setting it manually you'd kill two birds with one stone. The time would be what users expect, but without adding an extra step of little consequence. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 18:35, 12 July 2016 (UTC)<br />
<br />
== Switch to systemd-networkd ==<br />
<br />
Next ISOs may use systemd-networkd instead of dhcpcd, see [https://lists.archlinux.org/pipermail/arch-releng/2016-July/003739.html] -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 10:26, 19 July 2016 (UTC)<br />
<br />
== The Great Merge ==<br />
<br />
:''[Moved from [[Talk:Beginners' guide]]. — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 11:11, 24 August 2016 (UTC)]''<br />
<br />
[[#Plan]] reaches closure, and the [[Beginners' guide]] is now comparable in size to the [[Installation guide]]. "Cleanup day" [https://bbs.archlinux.org/viewtopic.php?id=214373] would be a good time to start the merge of both guides, and replace the Beginners' guide, together with translations on this domain, to redirections to the [[Installation guide]]. <br />
<br />
It would be preferable if before then, a TU or dev also brings this up on arch-dev-public for input from the developers, also regarding [[#Page protection]]. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 14:25, 5 July 2016 (UTC)<br />
<br />
:I agree with extending the redirection to the translations, with the exception of 4 which are actively maintained or have been retranslated recently, so I've flagged them to see if their maintainers want to deal with the merge on their own: [[Beginners' guide (العربية)]], [[Beginners' guide (Español)]], [[Beginners' guide (Русский)]] and [[Beginners' guide (简体中文)]]. — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 10:58, 6 July 2016 (UTC)<br />
<br />
:: I will take care of [[Beginners' guide (简体中文)]]. --[[User:Fengchao|Fengchao]] ([[User talk:Fengchao|talk]]) 06:21, 7 July 2016 (UTC)<br />
<br />
::: Note that typically content is rewritten in the [[Installation guide]], rather than taken literally from the [[Beginners' guide]] (see [[Talk:Installation_guide#BG_merge]]), so my suggestion is to focus translation efforts on the Installation guide, rather than the Beginners' guide. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 17:44, 12 July 2016 (UTC)<br />
<br />
::: I've redirected all translations apart from the above. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 18:50, 12 July 2016 (UTC)<br />
<br />
::::There are still some pages left: [https://wiki.archlinux.org/index.php?title=Special%3APrefixIndex&prefix=Beginners%27+Guide&namespace=0&hideredirects=1] -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:13, 14 July 2016 (UTC)<br />
<br />
:::::I've just handled those, but there's more to do at [https://wiki.archlinux.org/index.php?title=Special%3APrefixIndex&prefix=begin&namespace=10]. — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 10:38, 14 July 2016 (UTC)<br />
<br />
::::::What's the point of redirecting templates to regular pages? [https://wiki.archlinux.org/index.php?title=Template:Beginners%27_Guide_navigation_(Dansk)&curid=10983&diff=441462&oldid=387477] [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:59, 15 July 2016 (UTC)<br />
<br />
:::::::We were discussing that in [[ArchWiki_talk:Administrators#How_to_archive_templates]], we had a half-baked solution, maybe we should just put it to the vote. — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 14:28, 16 July 2016 (UTC)<br />
<br />
::::::::Oops, 154 days and still no reply from me, sorry about that... Thanks for your patience and strong nerves for the future, because unfortunately it's far from being the worst case of my this-year-maybe discussions :P<br />
::::::::In this case, I'd say that the templates can be simply deleted: it's fairly trivial transclusion of one &lt;div> and a couple of links, without any MediaWiki hacks, which can be recreated any time if needed. There is also pretty low probability that beginners' guides will be allowed in the near (less than 10 years) future in general, let alone split across multiple pages requiring navigational template. And if it's needed sometime in the next century, they will most likely have something better than MediaWiki's obscure template syntax.<br />
::::::::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:13, 16 July 2016 (UTC)<br />
<br />
:::::::::These redirected templates are a very marginal problem IMO, I don't mind if they stay as redirects or are deleted, but only because the fact that [[ArchWiki_talk:Administrators#How_to_archive_templates]] is still open justifies deciding case by case for the moment. Note that as redirects they don't pollute [[Special:UnusedTemplates]]. I wouldn't like to promote deletion as the official default template archiving method though, but I agree with delaying the resolution of that discussion, there are other priorities right now. — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 13:57, 18 July 2016 (UTC)<br />
<br />
::::::::::So I've taken the chance and deleted the BG navigation templates. Let's wait for [[ArchWiki_talk:Administrators#How_to_archive_templates]] with the general decision, hopefully this year... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:06, 25 July 2016 (UTC)<br />
<br />
::[[Beginners' guide (Русский)]] is now merged ^_^ -- [[User:Kycok|Kycok]] ([[User talk:Kycok|talk]]) 13:38, 10 July 2017 (UTC)<br />
<br />
=== Translations ===<br />
<br />
The translations of the [[Main page]] should be updated along with the English page. Also the [https://wiki.archlinux.org/index.php/Special:WhatLinksHere/Beginners%27_guide_(%E6%AD%A3%E9%AB%94%E4%B8%AD%E6%96%87) backlinks] of the BG translations should be cleaned as much as possible, as that might be somewhat [https://wiki.archlinux.org/index.php?title=Beginners%27_guide_(%E6%AD%A3%E9%AB%94%E4%B8%AD%E6%96%87)&diff=443707&oldid=443682 confusing] for future translators. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 11:45, 30 July 2016 (UTC)<br />
<br />
:Oh jolly... can we automate this with a bot somehow? -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 18:12, 30 July 2016 (UTC)<br />
<br />
::I haven't been doing any natural language processing yet, but if you feel like teaching my bot Chinese, please help yourself :)<br />
::Just kidding, I could probably make some semi-automatic assistant to at least quickly find and mark the links and open vimdiff for manual editing.<br />
::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:23, 30 July 2016 (UTC)<br />
<br />
:::I've fixed most of the backlinks to the english article, as well as the translated [[Main page]] articles. For the backlinks to translations I could definitely use the help of an assistant. :P -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 00:35, 27 August 2016 (UTC)<br />
<br />
== Initramfs ==<br />
<br />
=== Examples ===<br />
<br />
Initramfs, maybe add some examples like "eg encrypting/btrfs hook" so that beginners know what it is for? -- [https://www.reddit.com/r/archlinux/comments/4z7z0i/the_beginners_guide_has_been_removed_from_the_wiki/d6ui70e /u/youguess]<br />
: I'm not sure how to best word this. [[Installation_guide#Partition_the_disks]] mentions:<br />
:: If wanting to create any stacked block devices for LVM, disk encryption or RAID, do it now.<br />
: and each of those articles mention you need to edit {{ic|mkinitcpio.conf}} already. <s>"When" may be an unfortunate wording, however - since this step is indeed optional. See also [[#Initramfs]].</s> -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 18:34, 26 August 2016 (UTC)<br />
<br />
== Notes ==<br />
<br />
I've left some notes in [[User:Alad/Sandbox#Installation guide]], if anyone is interested in making suggestions. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 09:49, 22 September 2016 (UTC)<br />
<br />
edit: moved notes to here. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 12:05, 30 October 2016 (UTC)<br />
<br />
* [[Installation_guide#Pre-installation]]<br />
** No (bash) tab-completion in the chroot unless you install {{Pkg|bash-completion}}<br />
* [[Installation_guide#Connect_to_the_Internet]]<br />
** {{ic|systemctl stop dhcpcd@<TAB>}}<br />
:: Style undefined, see [[Help_talk:Reading#Mention_tab_completion.3F]]<br />
:: (The goal is to kill all running instances of ''dhcpcd'' to avoid conflicts; interface names are tangential)<br />
<br />
== systemd-firstboot for locale, timezone, and hostname? ==<br />
<br />
{{ic|systemd-firstboot}} works in a arch-chroot environment. I've tested it on a new installation. There are a couple of ways that it can be used. I think the simplest is:<br />
<br />
# systemd-firstboot --prompt<br />
<br />
There the program prompts a user to select a locale from a list of generate locales, the timezone (again from a list of available), and set the hostname. The program outputs what changes are made when performed. For example, when setting the timezone it states {{ic|/etc/localtime written}}.<br />
<br />
A section that used this method might look like this [[User:Rdeckard/Firstboot]], replacing the current locale, timezone, and hostname sections. [[User:Rdeckard|Rdeckard]] ([[User_talk:Rdeckard|talk]]) 16:16, 23 September 2016 (UTC)<br />
<br />
:I see two downsides to this:<br />
:*The steps are no longer logically separated, i.e. you set the hostname as part of systemd-firstboot and {{ic|/etc/hosts}} manually, similar for {{ic|/etc/locale.gen}}<br />
:*If systemd-firstboot breaks - which isn't unreasonable to expect, since localectl is broken since a year - we have to undo the change again.<br />
:I also had some concern about it abstracting away too much, but that should be covered by the "output changes that are made" part. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 23:20, 30 September 2016 (UTC)<br />
::Okay, those are good points. I'm in agreement it's probably best not to use systemd-firstboot in the guide for now. -- [[User:Rdeckard|Rdeckard]] ([[User_talk:Rdeckard|talk]]) 13:58, 5 October 2016 (UTC)<br />
<br />
== Wireless Configuration ==<br />
<br />
The advice for wireless network setup to refer to the wireless networking page in the Wiki could present a new user with a significant hurdle to overcome. The ARCH ISO contains wifi-menu, which should be sufficient for most purposes to establish a wireless network conneciton. I propose that informaton be added to the networking section at the start of the page stating:<br />
<br />
For wireless connections, iw(8), wpa_supplicant(8) and netctl are available. See Wireless network configuration. The ARCH ISO makes wifi-menu available. The wifi-menu programme should be sufficiently powerful for most users to establish a connection to a known WiFi network. {{Unsigned|11:49, 18 October 2016|Deggy}}<br />
<br />
:My eventual plan is to propose a man page for wifi_menu, then we can just link to that one instead of netctl. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 10:32, 18 October 2016 (UTC)<br />
<br />
::That would be great, I'd try to help; welcome to drop me a note about it. In the meantime I'd be +1 to Deggy's suggestion. Simplest way for new Archers, most of them will be used to a distro automatically enabling a network tool. Likewise, a simple sentence above it ala "see [[dhcpcd#Running]] for a quick start and [[Network configuration]] for free choice." would make it simpler for those wired users. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 10:33, 18 March 2017 (UTC)<br />
<br />
:::Thanks. Though I disagree on another link to [[dhcpcd]] in [[Installation_guide#Network_configuration]]; attentive users will have noticed that it is the method used in the installation environment, and [[Installation_guide#Configure_the_system]] specifically avoids recommending particular software choices for the new system (due to endless bickering in our user base on what's "best" or "recommended").<br />
:::Regarding wifi-menu, its usage is poorly covered even in the [[netctl]] article ([[Netctl#Wireless_.28WPA-PSK.29]] doesn't even mention how to select an interface) so that, or said man page, should be fixed first in my view. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 22:38, 18 March 2017 (UTC)<br />
<br />
::::[https://wiki.archlinux.org/index.php?title=Netctl&type=revision&diff=471232&oldid=471030] Well, in this case "The [[dhcpcd]] daemon is [https://git.archlinux.org/archiso.git/tree/configs/releng/airootfs/etc/udev/rules.d/81-dhcpcd.rules enabled] on boot for '''wired''' devices,.." should be changed to "On the installation image the [[dhcpcd]] daemon is [[enable]]d on boot for '''wired''' devices,...", because the crosslink helps a new user more than the udev rule and it currently suggests a non-existent default. Likewise, [[Installation guide#Network configuration]] should clarify it again with "The newly installed environment has no network connection activated per default. See [[Network configuration]] to configure one." --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 00:00, 19 March 2017 (UTC)<br />
<br />
:::::Sounds reasonable and would also strike off one point in [[#Notes]]. :) I think the link to the udev rule is still useful though, perhaps suitable for the ''wired'' word. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 02:13, 19 March 2017 (UTC)<br />
<br />
::::::[https://wiki.archlinux.org/index.php?title=Installation_guide&type=revision&diff=471297&oldid=469435] @Deggy: Your suggestion not fully picked up yet, but for now ''wifi-menu'' is directly mentioned behind the [[Netctl#Wireless_.28WPA-PSK.29|netctl]] link. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 18:01, 19 March 2017 (UTC)<br />
<br />
== <s>Base size</s> ==<br />
<br />
Article mentions 800mb. I completed (2017-05-07) a install (just the base install step) and got:<br />
/boot = 32Mb (32 752)<br />
/ (all but boot) = 1.1G (1 077 896)<br />
<br />
Should i update it?<br />
<br />
{{Unsigned|22:35, 7 May 2017|Gcb}}<br />
<br />
:Are you sure you've installed only those packages mentioned in this article, without optional ones and without {{Grp|base-devel}} group? -- [[User:Kycok|Kycok]] ([[User talk:Kycok|talk]]) 21:55, 7 May 2017 (UTC)<br />
<br />
::No response, closing. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 23:05, 14 June 2017 (UTC)<br />
<br />
== Restart required before `genfstab -U`? ==<br />
<br />
see https://www.reddit.com/r/archlinux/comments/6j34ra/archiso_lsblk_still_returns_old_uuid_after_mkfs/<br />
<br />
{{unsigned|00:40, 24 June 2017|Tromang}}<br />
<br />
:Looks like something you should report to {{Pkg|arch-install-scripts}}. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 16:48, 24 June 2017 (UTC)<br />
<br />
== Consider linking to [[Install from existing Linux]] ==<br />
<br />
The page [[Install from existing Linux]] is [https://wiki.archlinux.org/index.php?title=Special:WhatLinksHere/Install_from_existing_Linux&namespace=0&hideredirs=1 almost an orphan] because there are very few links going into it. I had to find it through Google. Perhaps consider linking to it from here? [[User:Fylwind|Fylwind]] ([[User talk:Fylwind|talk]]) 01:32, 11 July 2017 (UTC)</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Talk:Installation_guide&diff=481670Talk:Installation guide2017-07-11T01:32:50Z<p>Fylwind: /* Consider linking to Install from existing Linux */ new section</p>
<hr />
<div>== Read this first before adding new suggestions ==<br />
<br />
* The point of this page is to be a ''concise'' checklist of things to be done. Detailed instructions, if they are not specific to the installation process only, belong in wiki articles or upstream documentation describing the respective topics.<br />
* Should you have more complex changes for this guide in mind, create a copy on your user page, and link it here for review; e.g. [[User:Example/Installation guide]].<br />
* systemd tools such as ''hostnamectl'', ''timedatectl'' and ''localectl'' [https://github.com/systemd/systemd/issues/798#issuecomment-126568596 do not work] in the installation chroot environment, so please do not propose to use them in the guide unless you can prove that they have been made to work also in that case. See [https://wiki.archlinux.org/index.php?title=Talk:Beginners%27_guide&oldid=388727#General_problems], [https://wiki.archlinux.org/index.php?title=Talk:Beginners%27_guide&oldid=404695#Replace_commands_with_their_systemd_equivalents], [https://wiki.archlinux.org/index.php?title=Talk:Beginners%27_guide&oldid=418662#Utilizing_systemd_tools] and [https://wiki.archlinux.org/index.php?title=Talk:Installation_guide&oldid=434985#change_configuration_system_from_old_way_to_new_way.28using_systemd_commands.29] for some past discussions about this issue.<br />
* {{ic|localectl list-keymaps}} does not work due to bug {{Bug|46725}}. For the chosen replacement command, see [https://wiki.archlinux.org/index.php?title=Talk:Beginners%27_guide&oldid=435044#localectl].<br />
<br />
-- [[ArchWiki:Administrators|The ArchWiki Administrators]] 22:17, 2 September 2016 (UTC)<br />
__TOC__<br />
<br />
== "See ''foo''" vs "See the ''foo'' article" ==<br />
<br />
:''[Moved from [[Talk:Beginners' guide]]. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 20:29, 12 July 2016 (UTC)]''<br />
<br />
This revision [https://wiki.archlinux.org/index.php?title=Beginners%27_guide&diff=400266&oldid=400243] added a new mention of "See the ''foo'' article", rather than the more common "See ''foo''". I'd argue former is the better form, and when the guide is viewed from a .txt (if the BG/IG merge completes), the longer wording makes sense as well. Are there opinions against using the longer form throughout the BG? -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 00:13, 18 September 2015 (UTC)<br />
<br />
:I'm neutral, so that doesn't count as an opinion against ^^ That said, the long form can only be used with links to entire articles, but more difficultly with links to specific sections such as "See also [[Pacman#pacman crashes the official installation media]]", since in those cases a more natural-sounding long form should be something like "See also the 'pacman crashes the official installation media' section of the [[Pacman]] article", I think, which is clearly ugly to see and use, so consistency is a bit hard to reach. — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 16:13, 18 September 2015 (UTC)<br />
<br />
::I guess the proper solution would be to incorporate links in the article text where possible. "See X" gets repetitive fast, anyway. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 14:44, 29 September 2015 (UTC)<br />
<br />
:I'm actually here because when viewing the text format I was trying to figure out what the heck packages.both was I thought it might have been a meta package or something. -- [[User:Y2kbugger|Y2kbugger]] ([[User talk:Y2kbugger|talk]]) 17:36, 30 October 2016 (UTC)<br />
<br />
::Ideally packages.both would be a file path, but I'm not sure it's present in the live environment. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 18:13, 30 October 2016 (UTC)<br />
<br />
== pacman-key --populate ==<br />
<br />
:''[Moved from [[Talk:Beginners' guide]]. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 20:38, 12 July 2016 (UTC)]''<br />
<br />
Reference: https://wiki.archlinux.org/index.php?title=Beginners%27_guide&diff=next&oldid=411670<br />
I tried to install Archlinux on my new computer and got stuck. Only using the {{ic|pacman-key --populate archlinux}} helped me. I think I am not the only one having this problem. But why did you undo it? {{Unsigned|20:38, 12 December 2015|Sandstorm}}<br />
:This command is already run for the new system (by installation of archlinux-keyring), so running it by hand shouldn't be required for most users. Of course, things can go wrong (how old was the ISO you used to install the system?), but that belongs in Troubleshooting sections of the respective articles, which are linked at the beginning of the guide. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 19:52, 12 December 2015 (UTC)<br />
::I had downloaded the ISO just yesterday, minutes before the install. Only that command installed the keys. Probably I should open a bug if you can confirm the issue?<br />
:::Did you have to run pacman-key after, or before pacstrap? And do you recall what the error messages said exactly? (See also {{Bug|31286}}) -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 20:15, 12 December 2015 (UTC)<br />
::::I had to run after pacstrap. As far as I remember, pacstrap stopped after trying to download the keys. The error message was something like shown in this forum post: https://bbs.archlinux.org/viewtopic.php?id=165367<br />
:::::Well then, as you suggested, I'd open a bug report. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 20:34, 12 December 2015 (UTC)<br />
::::::Done. Could you check if the description is good. I could not find an appropriate category, so I though Packages:Core might be the closest one. https://bugs.archlinux.org/task/47351 --[[User:Sandstorm|Sandstorm]] ([[User talk:Sandstorm|talk]]) 20:48, 12 December 2015 (UTC)<br />
:::::::Thanks, the description looks OK. If the category e.a is not right, [[Special:Contributions/Scimmia|User:Scimmia]] should fix it. :P -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 13:59, 13 December 2015 (UTC)<br />
<br />
::::::::Hmm, looks like it was closed with "Works for me" ... not very enlightening. All I can suggest is to further improve on [[Pacman/Package signing]] and related articles, and recheck if they're accessible enough from the Beginners' guide. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 21:59, 12 February 2016 (UTC)<br />
<br />
== timesyncd: add manual date ==<br />
<br />
:''[Moved from [[Talk:Beginners' guide]]. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 20:44, 12 July 2016 (UTC)]''<br />
<br />
While the right time isn't as important in the live system as in the installed one, it may still be unexpected to users [https://wiki.archlinux.org/index.php?title=Beginners%27_guide&diff=432465&oldid=431268]. We could instead instruct to specify a date explicitly to timedatectl. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 11:25, 6 July 2016 (UTC)<br />
<br />
:Is the issue setting the time manually or just setting the time zone? The change you linked to just had setting the time zone. -- [[User:Rdeckard|Rdeckard]] ([[User_talk:Rdeckard|talk]]) 01:29, 9 July 2016 (UTC)<br />
<br />
::Well, with setting it manually you'd kill two birds with one stone. The time would be what users expect, but without adding an extra step of little consequence. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 18:35, 12 July 2016 (UTC)<br />
<br />
== Switch to systemd-networkd ==<br />
<br />
Next ISOs may use systemd-networkd instead of dhcpcd, see [https://lists.archlinux.org/pipermail/arch-releng/2016-July/003739.html] -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 10:26, 19 July 2016 (UTC)<br />
<br />
== The Great Merge ==<br />
<br />
:''[Moved from [[Talk:Beginners' guide]]. — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 11:11, 24 August 2016 (UTC)]''<br />
<br />
[[#Plan]] reaches closure, and the [[Beginners' guide]] is now comparable in size to the [[Installation guide]]. "Cleanup day" [https://bbs.archlinux.org/viewtopic.php?id=214373] would be a good time to start the merge of both guides, and replace the Beginners' guide, together with translations on this domain, to redirections to the [[Installation guide]]. <br />
<br />
It would be preferable if before then, a TU or dev also brings this up on arch-dev-public for input from the developers, also regarding [[#Page protection]]. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 14:25, 5 July 2016 (UTC)<br />
<br />
:I agree with extending the redirection to the translations, with the exception of 4 which are actively maintained or have been retranslated recently, so I've flagged them to see if their maintainers want to deal with the merge on their own: [[Beginners' guide (العربية)]], [[Beginners' guide (Español)]], [[Beginners' guide (Русский)]] and [[Beginners' guide (简体中文)]]. — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 10:58, 6 July 2016 (UTC)<br />
<br />
:: I will take care of [[Beginners' guide (简体中文)]]. --[[User:Fengchao|Fengchao]] ([[User talk:Fengchao|talk]]) 06:21, 7 July 2016 (UTC)<br />
<br />
::: Note that typically content is rewritten in the [[Installation guide]], rather than taken literally from the [[Beginners' guide]] (see [[Talk:Installation_guide#BG_merge]]), so my suggestion is to focus translation efforts on the Installation guide, rather than the Beginners' guide. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 17:44, 12 July 2016 (UTC)<br />
<br />
::: I've redirected all translations apart from the above. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 18:50, 12 July 2016 (UTC)<br />
<br />
::::There are still some pages left: [https://wiki.archlinux.org/index.php?title=Special%3APrefixIndex&prefix=Beginners%27+Guide&namespace=0&hideredirects=1] -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:13, 14 July 2016 (UTC)<br />
<br />
:::::I've just handled those, but there's more to do at [https://wiki.archlinux.org/index.php?title=Special%3APrefixIndex&prefix=begin&namespace=10]. — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 10:38, 14 July 2016 (UTC)<br />
<br />
::::::What's the point of redirecting templates to regular pages? [https://wiki.archlinux.org/index.php?title=Template:Beginners%27_Guide_navigation_(Dansk)&curid=10983&diff=441462&oldid=387477] [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:59, 15 July 2016 (UTC)<br />
<br />
:::::::We were discussing that in [[ArchWiki_talk:Administrators#How_to_archive_templates]], we had a half-baked solution, maybe we should just put it to the vote. — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 14:28, 16 July 2016 (UTC)<br />
<br />
::::::::Oops, 154 days and still no reply from me, sorry about that... Thanks for your patience and strong nerves for the future, because unfortunately it's far from being the worst case of my this-year-maybe discussions :P<br />
::::::::In this case, I'd say that the templates can be simply deleted: it's fairly trivial transclusion of one &lt;div> and a couple of links, without any MediaWiki hacks, which can be recreated any time if needed. There is also pretty low probability that beginners' guides will be allowed in the near (less than 10 years) future in general, let alone split across multiple pages requiring navigational template. And if it's needed sometime in the next century, they will most likely have something better than MediaWiki's obscure template syntax.<br />
::::::::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:13, 16 July 2016 (UTC)<br />
<br />
:::::::::These redirected templates are a very marginal problem IMO, I don't mind if they stay as redirects or are deleted, but only because the fact that [[ArchWiki_talk:Administrators#How_to_archive_templates]] is still open justifies deciding case by case for the moment. Note that as redirects they don't pollute [[Special:UnusedTemplates]]. I wouldn't like to promote deletion as the official default template archiving method though, but I agree with delaying the resolution of that discussion, there are other priorities right now. — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 13:57, 18 July 2016 (UTC)<br />
<br />
::::::::::So I've taken the chance and deleted the BG navigation templates. Let's wait for [[ArchWiki_talk:Administrators#How_to_archive_templates]] with the general decision, hopefully this year... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:06, 25 July 2016 (UTC)<br />
<br />
::[[Beginners' guide (Русский)]] is now merged ^_^ -- [[User:Kycok|Kycok]] ([[User talk:Kycok|talk]]) 13:38, 10 July 2017 (UTC)<br />
<br />
=== Translations ===<br />
<br />
The translations of the [[Main page]] should be updated along with the English page. Also the [https://wiki.archlinux.org/index.php/Special:WhatLinksHere/Beginners%27_guide_(%E6%AD%A3%E9%AB%94%E4%B8%AD%E6%96%87) backlinks] of the BG translations should be cleaned as much as possible, as that might be somewhat [https://wiki.archlinux.org/index.php?title=Beginners%27_guide_(%E6%AD%A3%E9%AB%94%E4%B8%AD%E6%96%87)&diff=443707&oldid=443682 confusing] for future translators. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 11:45, 30 July 2016 (UTC)<br />
<br />
:Oh jolly... can we automate this with a bot somehow? -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 18:12, 30 July 2016 (UTC)<br />
<br />
::I haven't been doing any natural language processing yet, but if you feel like teaching my bot Chinese, please help yourself :)<br />
::Just kidding, I could probably make some semi-automatic assistant to at least quickly find and mark the links and open vimdiff for manual editing.<br />
::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:23, 30 July 2016 (UTC)<br />
<br />
:::I've fixed most of the backlinks to the english article, as well as the translated [[Main page]] articles. For the backlinks to translations I could definitely use the help of an assistant. :P -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 00:35, 27 August 2016 (UTC)<br />
<br />
== Initramfs ==<br />
<br />
=== Examples ===<br />
<br />
Initramfs, maybe add some examples like "eg encrypting/btrfs hook" so that beginners know what it is for? -- [https://www.reddit.com/r/archlinux/comments/4z7z0i/the_beginners_guide_has_been_removed_from_the_wiki/d6ui70e /u/youguess]<br />
: I'm not sure how to best word this. [[Installation_guide#Partition_the_disks]] mentions:<br />
:: If wanting to create any stacked block devices for LVM, disk encryption or RAID, do it now.<br />
: and each of those articles mention you need to edit {{ic|mkinitcpio.conf}} already. <s>"When" may be an unfortunate wording, however - since this step is indeed optional. See also [[#Initramfs]].</s> -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 18:34, 26 August 2016 (UTC)<br />
<br />
== Notes ==<br />
<br />
I've left some notes in [[User:Alad/Sandbox#Installation guide]], if anyone is interested in making suggestions. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 09:49, 22 September 2016 (UTC)<br />
<br />
edit: moved notes to here. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 12:05, 30 October 2016 (UTC)<br />
<br />
* [[Installation_guide#Pre-installation]]<br />
** No (bash) tab-completion in the chroot unless you install {{Pkg|bash-completion}}<br />
* [[Installation_guide#Connect_to_the_Internet]]<br />
** {{ic|systemctl stop dhcpcd@<TAB>}}<br />
:: Style undefined, see [[Help_talk:Reading#Mention_tab_completion.3F]]<br />
:: (The goal is to kill all running instances of ''dhcpcd'' to avoid conflicts; interface names are tangential)<br />
<br />
== systemd-firstboot for locale, timezone, and hostname? ==<br />
<br />
{{ic|systemd-firstboot}} works in a arch-chroot environment. I've tested it on a new installation. There are a couple of ways that it can be used. I think the simplest is:<br />
<br />
# systemd-firstboot --prompt<br />
<br />
There the program prompts a user to select a locale from a list of generate locales, the timezone (again from a list of available), and set the hostname. The program outputs what changes are made when performed. For example, when setting the timezone it states {{ic|/etc/localtime written}}.<br />
<br />
A section that used this method might look like this [[User:Rdeckard/Firstboot]], replacing the current locale, timezone, and hostname sections. [[User:Rdeckard|Rdeckard]] ([[User_talk:Rdeckard|talk]]) 16:16, 23 September 2016 (UTC)<br />
<br />
:I see two downsides to this:<br />
:*The steps are no longer logically separated, i.e. you set the hostname as part of systemd-firstboot and {{ic|/etc/hosts}} manually, similar for {{ic|/etc/locale.gen}}<br />
:*If systemd-firstboot breaks - which isn't unreasonable to expect, since localectl is broken since a year - we have to undo the change again.<br />
:I also had some concern about it abstracting away too much, but that should be covered by the "output changes that are made" part. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 23:20, 30 September 2016 (UTC)<br />
::Okay, those are good points. I'm in agreement it's probably best not to use systemd-firstboot in the guide for now. -- [[User:Rdeckard|Rdeckard]] ([[User_talk:Rdeckard|talk]]) 13:58, 5 October 2016 (UTC)<br />
<br />
== Wireless Configuration ==<br />
<br />
The advice for wireless network setup to refer to the wireless networking page in the Wiki could present a new user with a significant hurdle to overcome. The ARCH ISO contains wifi-menu, which should be sufficient for most purposes to establish a wireless network conneciton. I propose that informaton be added to the networking section at the start of the page stating:<br />
<br />
For wireless connections, iw(8), wpa_supplicant(8) and netctl are available. See Wireless network configuration. The ARCH ISO makes wifi-menu available. The wifi-menu programme should be sufficiently powerful for most users to establish a connection to a known WiFi network. {{Unsigned|11:49, 18 October 2016|Deggy}}<br />
<br />
:My eventual plan is to propose a man page for wifi_menu, then we can just link to that one instead of netctl. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 10:32, 18 October 2016 (UTC)<br />
<br />
::That would be great, I'd try to help; welcome to drop me a note about it. In the meantime I'd be +1 to Deggy's suggestion. Simplest way for new Archers, most of them will be used to a distro automatically enabling a network tool. Likewise, a simple sentence above it ala "see [[dhcpcd#Running]] for a quick start and [[Network configuration]] for free choice." would make it simpler for those wired users. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 10:33, 18 March 2017 (UTC)<br />
<br />
:::Thanks. Though I disagree on another link to [[dhcpcd]] in [[Installation_guide#Network_configuration]]; attentive users will have noticed that it is the method used in the installation environment, and [[Installation_guide#Configure_the_system]] specifically avoids recommending particular software choices for the new system (due to endless bickering in our user base on what's "best" or "recommended").<br />
:::Regarding wifi-menu, its usage is poorly covered even in the [[netctl]] article ([[Netctl#Wireless_.28WPA-PSK.29]] doesn't even mention how to select an interface) so that, or said man page, should be fixed first in my view. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 22:38, 18 March 2017 (UTC)<br />
<br />
::::[https://wiki.archlinux.org/index.php?title=Netctl&type=revision&diff=471232&oldid=471030] Well, in this case "The [[dhcpcd]] daemon is [https://git.archlinux.org/archiso.git/tree/configs/releng/airootfs/etc/udev/rules.d/81-dhcpcd.rules enabled] on boot for '''wired''' devices,.." should be changed to "On the installation image the [[dhcpcd]] daemon is [[enable]]d on boot for '''wired''' devices,...", because the crosslink helps a new user more than the udev rule and it currently suggests a non-existent default. Likewise, [[Installation guide#Network configuration]] should clarify it again with "The newly installed environment has no network connection activated per default. See [[Network configuration]] to configure one." --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 00:00, 19 March 2017 (UTC)<br />
<br />
:::::Sounds reasonable and would also strike off one point in [[#Notes]]. :) I think the link to the udev rule is still useful though, perhaps suitable for the ''wired'' word. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 02:13, 19 March 2017 (UTC)<br />
<br />
::::::[https://wiki.archlinux.org/index.php?title=Installation_guide&type=revision&diff=471297&oldid=469435] @Deggy: Your suggestion not fully picked up yet, but for now ''wifi-menu'' is directly mentioned behind the [[Netctl#Wireless_.28WPA-PSK.29|netctl]] link. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 18:01, 19 March 2017 (UTC)<br />
<br />
== <s>Base size</s> ==<br />
<br />
Article mentions 800mb. I completed (2017-05-07) a install (just the base install step) and got:<br />
/boot = 32Mb (32 752)<br />
/ (all but boot) = 1.1G (1 077 896)<br />
<br />
Should i update it?<br />
<br />
{{Unsigned|22:35, 7 May 2017|Gcb}}<br />
<br />
:Are you sure you've installed only those packages mentioned in this article, without optional ones and without {{Grp|base-devel}} group? -- [[User:Kycok|Kycok]] ([[User talk:Kycok|talk]]) 21:55, 7 May 2017 (UTC)<br />
<br />
::No response, closing. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 23:05, 14 June 2017 (UTC)<br />
<br />
== Restart required before `genfstab -U`? ==<br />
<br />
see https://www.reddit.com/r/archlinux/comments/6j34ra/archiso_lsblk_still_returns_old_uuid_after_mkfs/<br />
<br />
{{unsigned|00:40, 24 June 2017|Tromang}}<br />
<br />
:Looks like something you should report to {{Pkg|arch-install-scripts}}. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 16:48, 24 June 2017 (UTC)<br />
<br />
== Consider linking to [[Install from existing Linux]] ==<br />
<br />
The page [[Install from existing Linux]] is [https://wiki.archlinux.org/index.php?title=Special:WhatLinksHere/Install_from_existing_Linux&namespace=0&hideredirs=1 almost an orphan] because there are very few links going into it. I had to find it through Google. Perhaps consider linking to it from here?</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Font_configuration&diff=480497Font configuration2017-06-26T07:34:56Z<p>Fylwind: /* Applications without fontconfig support */ also mention Emacs</p>
<hr />
<div>[[Category:Fonts]]<br />
[[it:Font configuration]]<br />
[[ja:フォント設定]]<br />
[[ru:Font configuration]]<br />
[[sr:Font configuration]]<br />
[[tr:Yazıtipi yapılandırması]]<br />
[[zh-hans:Font configuration]]<br />
{{Related articles start}}<br />
{{Related|Fonts}}<br />
{{Related|Font configuration/Examples}}<br />
{{Related|Java Runtime Environment Fonts}}<br />
{{Related|Metric-compatible fonts}}<br />
{{Related|MS Fonts}}<br />
{{Related|X Logical Font Description}}<br />
{{Related articles end}}<br />
<br />
[http://www.freedesktop.org/wiki/Software/fontconfig/ Fontconfig] is a library designed to provide a list of available [[fonts]] to applications, and also for configuration for how fonts get rendered: see [[Wikipedia:Fontconfig]]. The FreeType library {{Pkg|freetype2}} renders the fonts, based on this configuration.<br />
<br />
Though Fontconfig is the standard in modern Linux, some applications rely on the original method of font selection and display, the [[X Logical Font Description]].<br />
<br />
The font rendering packages on Arch Linux includes support for ''freetype2'' with the bytecode interpreter (BCI) enabled. For better font rendering, especially with an LCD monitor, see [[#Fontconfig configuration]] and [[Font configuration/Examples]].<br />
<br />
== Font paths ==<br />
<br />
For fonts to be known to applications, they must be cataloged for easy and quick access.<br />
<br />
The font paths initially known to Fontconfig are: {{ic|/usr/share/fonts/}}, {{ic|~/.local/share/fonts}} (and {{ic|~/.fonts/}}, now deprecated). Fontconfig will scan these directories recursively. For ease of organization and installation, it is recommended to use these font paths when [[adding fonts]].<br />
<br />
To see a list of known Fontconfig fonts:<br />
$ fc-list : file<br />
<br />
See {{man|1|fc-list|url=}} for more output formats.<br />
<br />
Check for Xorg's known font paths by reviewing its log:<br />
<br />
$ grep /fonts ~/.local/share/xorg/Xorg.0.log<br />
<br />
{{Tip|<br />
* You can also check the list of [[Xorg]]'s known font paths using the command {{ic|xset q}}.<br />
* Use {{ic|/var/log/Xorg.0.log}} if Xorg is run with root privileges.<br />
}}<br />
<br />
Keep in mind that Xorg does not search recursively through the {{ic|/usr/share/fonts/}} directory like Fontconfig does. To add a path, the full path must be used:<br />
Section "Files"<br />
FontPath "/usr/share/fonts/local/"<br />
EndSection<br />
<br />
If you want font paths to be set on a per-user basis, you can add and remove font paths from the default by adding the following line(s) to {{ic|~/.xinitrc}}:<br />
xset +fp /usr/share/fonts/local/ # Prepend a custom font path to Xorg's list of known font paths<br />
xset -fp /usr/share/fonts/sucky_fonts/ # Remove the specified font path from Xorg's list of known font paths<br />
<br />
To see a list of known Xorg fonts use {{ic|xlsfonts}}, from the {{Pkg|xorg-xlsfonts}} package.<br />
<br />
== Fontconfig configuration ==<br />
<br />
Fontconfig is documented in the [http://www.freedesktop.org/software/fontconfig/fontconfig-user.html fonts-conf] man page.<br />
<br />
Configuration can be done per-user through {{ic|$XDG_CONFIG_HOME/fontconfig/fonts.conf}}, and globally with {{ic|/etc/fonts/local.conf}}. The settings in the per-user configuration have precedence over the global configuration. Both these files use the same syntax.<br />
{{Note|Configuration files and directories: {{ic|~/.fonts.conf/}}, {{ic|~/.fonts.conf.d/}} and {{ic|~/.fontconfig/*.cache-*}} are deprecated since {{Pkg|fontconfig}} 2.10.1 ([http://cgit.freedesktop.org/fontconfig/commit/?id&#61;8c255fb185d5651b57380b0a9443001e8051b29d upstream commit]) and will not be read by default in the future versions of the package. New paths are {{ic|$XDG_CONFIG_HOME/fontconfig/fonts.conf}}, {{ic|$XDG_CONFIG_HOME/fontconfig/conf.d/NN-name.conf}} and {{ic|$XDG_CACHE_HOME/fontconfig/*.cache-*}} respectively. If using the second location, make sure the naming is valid (where {{ic|NN}} is a two digit number like {{ic|00}}, {{ic|10}}, or {{ic|99}}).}}<br />
<br />
Fontconfig gathers all its configurations in a central file ({{ic|/etc/fonts/fonts.conf}}). This file is replaced during fontconfig updates and should not be edited. Fontconfig-aware applications source this file to know available fonts and how they get rendered. This file is a conglomeration of rules from the global configuration ({{ic|/etc/fonts/local.conf}}), the configured presets in {{ic|/etc/fonts/conf.d/}}, and the user configuration file ({{ic|$XDG_CONFIG_HOME/fontconfig/fonts.conf}}). {{ic|fc-cache}} can be used to rebuild fontconfig's configuration, although changes will only be visible in newly launched applications.<br />
<br />
{{Note|For some desktop environments (such as [[GNOME]] and [[KDE]]) using the ''Font Control Panel'' will automatically create or overwrite the user font configuration file. For these desktop environments, it is best to match your already defined font configurations to get the expected behavior.}}<br />
<br />
Fontconfig configuration files use [[Wikipedia:XML|XML]] format and need these headers:<br />
<br />
{{bc|<nowiki><br />
<?xml version="1.0"?><br />
<!DOCTYPE fontconfig SYSTEM "fonts.dtd"><br />
<fontconfig><br />
<br />
<!-- settings go here --><br />
<br />
</fontconfig><br />
</nowiki>}}<br />
<br />
The configuration examples in this article omit these tags.<br />
<br />
=== Presets ===<br />
<br />
There are presets installed in the directory {{ic|/etc/fonts/conf.avail}}. They can be enabled by creating [[Wikipedia:Symbolic link|symbolic link]]s to them, both per-user and globally, as described in {{ic|/etc/fonts/conf.d/README}}. These presets will override matching settings in their respective configuration files.<br />
<br />
For example, to enable sub-pixel RGB rendering globally:<br />
<br />
# cd /etc/fonts/conf.d<br />
# ln -s ../conf.avail/10-sub-pixel-rgb.conf<br />
<br />
To do the same but instead for a per-user configuration:<br />
<br />
$ mkdir $XDG_CONFIG_HOME/fontconfig/conf.d<br />
$ ln -s /etc/fonts/conf.avail/10-sub-pixel-rgb.conf $XDG_CONFIG_HOME/fontconfig/conf.d<br />
<br />
=== Anti-aliasing ===<br />
<br />
[[Wikipedia:Font rasterization|Font rasterization]] converts vector font data to bitmap data so that it can be displayed. The result can appear jagged due to [[Wikipedia:Aliasing|aliasing]]. The technique known as [[Wikipedia:Anti-aliasing|anti-aliasing]] can be used to increase the apparent resolution of font edges. Anti-aliasing is '''enabled''' by default. To disable it:<br />
<br />
{{bc|<nowiki><br />
<match target="font"><br />
<edit name="antialias" mode="assign"><br />
<bool>false</bool><br />
</edit><br />
</match><br />
</nowiki>}}<br />
<br />
{{Note|Some applications, like [[GNOME]] may [[#Troubleshooting|override default anti-aliasing settings]].}}<br />
<br />
=== Hinting ===<br />
<br />
[[Wikipedia:Font hinting|Font hinting]] (also known as instructing) is the use of mathematical instructions to adjust the display of an outline font so that it lines up with a rasterized grid, (i.e. the pixel grid of the display). Its intended effect is to make fonts appear more crisp so that they are more readable. Fonts will line up correctly without hinting when displays have around 300 [[Wikipedia:Dots per inch|DPI]].<br />
<br />
==== Byte-Code Interpreter (BCI) ====<br />
<br />
Using BCI hinting, instructions in TrueType fonts are rendered according to FreeTypes's interpreter. BCI hinting works well with fonts with good hinting instructions. Hinting is '''enabled''' by default. To disable it:<br />
<br />
{{bc|<nowiki><br />
<match target="font"><br />
<edit name="hinting" mode="assign"><br />
<bool>false</bool><br />
</edit><br />
</match><br />
</nowiki>}}<br />
<br />
==== Autohinter ====<br />
<br />
The autohinter attempts to do automatic hinting and disregards any existing hinting information. Originally it was the default because TrueType2 fonts were patent-protected but now that these patents have expired there is very little reason to use it. It does work better with fonts that have broken or no hinting information but it will be strongly sub-optimal for fonts with good hinting information. Generally common fonts are of the later kind so autohinter will not be useful. Autohinter is '''disabled''' by default. To enable it:<br />
<br />
{{bc|<nowiki><br />
<match target="font"><br />
<edit name="autohint" mode="assign"><br />
<bool>true</bool><br />
</edit><br />
</match><br />
</nowiki>}}<br />
<br />
==== Hintstyle ====<br />
<br />
Hintstyle is the amount of font reshaping done to line up to the grid. Hinting values are: {{ic|hintnone}}, {{ic|hintslight}}, {{ic|hintmedium}}, and {{ic|hintfull}}. {{ic|hintslight}} will make the font more fuzzy to line up to the grid but will be better in retaining font shape, while {{ic|hintfull}} will be a crisp font that aligns well to the pixel grid but will lose a greater amount of font shape. '''{{ic|hintslight}}''' is the default setting. To change it:<br />
<br />
{{bc|<nowiki><br />
<match target="font"><br />
<edit name="hintstyle" mode="assign"><br />
<const>hintnone</const><br />
</edit><br />
</match><br />
</nowiki>}}<br />
<br />
{{Note|Some applications, like [[GNOME]] may [[#Troubleshooting|override default hinting settings.]]}}<br />
<br />
=== Subpixel rendering ===<br />
<br />
Most monitors manufactured today use the Red, Green, Blue (RGB) specification. Fontconfig will need to know your monitor type to be able to display your fonts correctly. Monitors are either: '''RGB''' (most common), '''BGR''', '''V-RGB''' (vertical), or '''V-BGR'''. A monitor test can be found [http://www.lagom.nl/lcd-test/subpixel.php here].<br />
<br />
To enable subpixel rendering:<br />
<br />
{{bc|<nowiki><br />
<match target="font"><br />
<edit name="rgba" mode="assign"><br />
<const>rgb</const><br />
</edit><br />
</match><br />
</nowiki>}}<br />
<br />
{{Note|1=Subpixel rendering effectively triples the horizontal (or vertical) resolution for fonts by making use of subpixels. The default autohinter and subpixel rendering are not designed to work together, hence you will want to enable the subpixel autohinter. Prior to {{Pkg|freetype2}} 2.7, the subpixel hinting mode was configurable with the {{ic|FT2_SUBPIXEL_HINTING}} [[environment variable]]. Possible values were {{ic|0}} (disabled), {{ic|1}} (Infinality) and {{ic|2}} (minimal). From {{Pkg|freetype2}} 2.7, subpixel hinting uses upstream's configuration method, which has a different syntax. Subpixel hinting mode configured in the file {{ic|/etc/profile.d/freetype2.sh}} which includes a brief documentation. Possible values are {{ic|1=truetype:interpreter-version=35}} (classic mode/2.6 default), {{ic|1=truetype:interpreter-version=38}} ("Infinality" mode), {{ic|1=truetype:interpreter-version=40}} (minimal mode/2.7 default).}}<br />
<br />
==== LCD filter ====<br />
<br />
When using subpixel rendering, you should enable the LCD filter, which is designed to reduce colour fringing. This is described under [http://www.freetype.org/freetype2/docs/reference/ft2-lcd_filtering.html LCD filtering] in the FreeType 2 API reference. Different options are described under [http://www.freetype.org/freetype2/docs/reference/ft2-lcd_filtering.html#FT_LcdFilter FT_LcdFilter], and are illustrated by this [http://www.spasche.net/files/lcdfiltering/ LCD filter test] page.<br />
<br />
The {{ic|lcddefault}} filter will work for most users. Other filters are available that can be used in special situations: {{ic|lcdlight}}; a lighter filter ideal for fonts that look too bold or fuzzy, {{ic|lcdlegacy}}, the original Cairo filter; and {{ic|lcdnone}} to disable it entirely.<br />
<br />
{{bc|<nowiki><br />
<match target="font"><br />
<edit name="lcdfilter" mode="assign"><br />
<const>lcddefault</const><br />
</edit><br />
</match><br />
</nowiki>}}<br />
<br />
==== Advanced LCD filter specification ====<br />
<br />
If the available built-in LCD filters are not satisfactory, it is possible to tweak the font rendering very specifically by building a custom freetype2 package and modifying the hardcoded filters. The [[Arch Build System]] can be used to build and install packages from source.<br />
<br />
First, refresh the freetype2 PKGBUILD as root:<br />
<br />
# abs extra/freetype2<br />
<br />
This example uses {{ic|/var/abs/build}} as the build directory, substitute it according to your personal ABS setup. Download and extract the freetype2 package as a regular user:<br />
<br />
$ cd /var/abs/build<br />
$ cp -r ../extra/freetype2 .<br />
$ cd freetype2<br />
$ makepkg -o<br />
<br />
Edit the file {{ic|src/freetype-VERSION/src/base/ftlcdfil.c}} and look up the definition of the constant {{ic|default_filter[5]}}:<br />
<br />
static const FT_Byte default_filter[5] =<br />
{ 0x10, 0x40, 0x70, 0x40, 0x10 };<br />
<br />
This constant defines a low-pass filter applied to the rendered glyph. Modify it as needed. (reference: [https://lists.nongnu.org/archive/html/freetype/2006-09/msg00069.html freetype list discussion]) Save the file, build and install the custom package:<br />
<br />
$ makepkg -e<br />
# pacman -Rd freetype2<br />
# pacman -U freetype2-VERSION-ARCH.pkg.tar.xz<br />
<br />
Reboot or restart X. The lcddefault filter should now render fonts differently.<br />
<br />
=== Disable auto-hinter for bold fonts ===<br />
<br />
The auto-hinter uses sophisticated methods for font rendering, but often makes bold fonts too wide. Fortunately, a solution can be turning off the autohinter for bold fonts while leaving it on for the rest:<br />
...<br />
<match target="font"><br />
<test name="weight" compare="more"><br />
<const>medium</const><br />
</test><br />
<edit name="autohint" mode="assign"><br />
<bool>false</bool><br />
</edit><br />
</match><br />
...<br />
<br />
=== Replace or set default fonts ===<br />
<br />
The most reliable way to do this is to add an XML fragment similar to the one below. ''Using the "binding" attribute will give you better results'', for example, in Firefox where you may not want to change properties of font being replaced. This will cause Ubuntu to be used in place of Georgia:<br />
<br />
{{bc|<nowiki><br />
...<br />
<match target="pattern"><br />
<test qual="any" name="family"><string>georgia</string></test><br />
<edit name="family" mode="assign" binding="same"><string>Ubuntu</string></edit><br />
</match><br />
...<br />
</nowiki>}}<br />
<br />
An alternate approach is to set the "preferred" font, but ''this only works if the original font is not on the system'', in which case the one specified will be substituted:<br />
<br />
{{bc|<nowiki><br />
...<br />
<!-- Replace Helvetica with Bitstream Vera Sans Mono --><br />
<!-- Note, an alias for Helvetica should already exist in default conf files --><br />
<alias><br />
<family>Helvetica</family><br />
<prefer><family>Bitstream Vera Sans Mono</family></prefer><br />
<default><family>fixed</family></default><br />
</alias><br />
...<br />
</nowiki>}}<br />
<br />
=== Whitelisting and blacklisting fonts ===<br />
<br />
The element {{ic|<selectfont>}} is used in conjunction with the {{ic|<acceptfont>}} and {{ic|<rejectfont>}} elements to selectively whitelist or blacklist fonts from the resolve list and match requests. The simplest and most typical use case it to reject one font that is needed to be installed, however is getting matched for a generic font query that is causing problems within application user interfaces.<br />
<br />
First obtain the Family name as listed in the font itself:<br />
<br />
{{hc|1=$ fc-scan .fonts/lklug.ttf --format='%{family}\n'|2=<br />
LKLUG<br />
}}<br />
<br />
Then use that Family name in a {{ic|<rejectfont>}} stanza:<br />
<br />
{{bc|<nowiki><br />
<selectfont><br />
<rejectfont><br />
<pattern><br />
<patelt name="family" ><br />
<string>LKLUG</string><br />
</patelt><br />
</pattern><br />
</rejectfont><br />
</selectfont><br />
</nowiki>}}<br />
<br />
Typically when both elements are combined, {{ic|<rejectfont>}} is first used on a more general matching glob to reject a large group (such as a whole directory), then {{ic|<acceptfont>}} is used after it to whitelist individual fonts out of the larger blacklisted group.<br />
<br />
{{bc|<nowiki><br />
<selectfont><br />
<rejectfont><br />
<glob>/usr/share/fonts/OTF/*</glob><br />
</rejectfont><br />
<acceptfont><br />
<pattern><br />
<patelt name="family" ><br />
<string>Monaco</string><br />
</patelt><br />
</pattern><br />
</acceptfont><br />
</selectfont><br />
</nowiki>}}<br />
<br />
=== Disable bitmap fonts ===<br />
<br />
Bitmap fonts are sometimes used as fallbacks for missing fonts, which may cause text to be rendered pixelated or too large. Use the {{ic|70-no-bitmaps.conf}} [[#Presets|preset]] to disable this behavior. <br />
<br />
<div id="EmbeddedBitmap">To disable embedded bitmap for all fonts:<div><br />
<br />
{{hc|~/.config/fontconfig/conf.d/20-no-embedded.conf|<nowiki><br />
<?xml version="1.0"?><br />
<!DOCTYPE fontconfig SYSTEM "fonts.dtd"><br />
<fontconfig><br />
<match target="font"><br />
<edit name="embeddedbitmap" mode="assign"><br />
<bool>false</bool><br />
</edit><br />
</match><br />
</fontconfig><br />
</nowiki>}}<br />
<br />
To disable embedded bitmap fonts for a specific font:<br />
<br />
<match target="font"><br />
<test qual="any" name="family"><br />
<string>Monaco</string><br />
</test><br />
<edit name="embeddedbitmap"><br />
<bool>false</bool><br />
</edit><br />
</match><br />
<br />
=== Disable scaling of bitmap fonts ===<br />
<br />
To disable scaling of bitmap fonts (which often makes them blurry), remove {{ic|/etc/fonts/conf.d/10-scale-bitmap-fonts.conf}}.<br />
<br />
=== Create bold and italic styles for incomplete fonts ===<br />
<br />
FreeType has the ability to automatically create ''italic'' and '''bold''' styles for fonts that do not have them, but only if explicitly required by the application. Given programs rarely send these requests, this section covers manually forcing generation of missing styles.<br />
<br />
Start by editing {{ic|/usr/share/fonts/fonts.cache-1}} as explained below. Store a copy of the modifications on another file, because a font update with {{ic|fc-cache}} will overwrite {{ic|/usr/share/fonts/fonts.cache-1}}.<br />
<br />
Assuming the Dupree font is installed:<br />
"dupree.ttf" 0 "Dupree:style=Regular:slant=0:weight=80:width=100:foundry=unknown:index=0:outline=True:''etc...''<br />
<br />
Duplicate the line, change {{ic|<nowiki>style=Regular</nowiki>}} to {{ic|<nowiki>style=Bold</nowiki>}} or any other style. Also change {{ic|<nowiki>slant=0</nowiki>}} to {{ic|<nowiki>slant=100</nowiki>}} for italic, {{ic|<nowiki>weight=80</nowiki>}} to {{ic|<nowiki>weight=200</nowiki>}} for bold, or combine them for '''''bold italic''''':<br />
"dupree.ttf" 0 "Dupree:style=Bold Italic:slant=100:weight=200:width=100:foundry=unknown:index=0:outline=True:''etc...''<br />
<br />
Now add necessary modifications to {{ic|$XDG_CONFIG_HOME/fontconfig/fonts.conf}}:<br />
{{bc|<nowiki><br />
...<br />
<match target="font"><br />
<test name="family" qual="any"><br />
<string>Dupree</string><br />
&lt;!-- other fonts here .... --&gt;<br />
</test><br />
<test name="weight" compare="more_eq"><int>140</int></test><br />
<edit name="embolden" mode="assign"><bool>true</bool></edit><br />
</match><br />
<br />
<match target="font"><br />
<test name="family" qual="any"><br />
<string>Dupree</string><br />
&lt;!-- other fonts here .... --&gt;<br />
</test><br />
<test name="slant" compare="more_eq"><int>80</int></test><br />
<edit name="matrix" mode="assign"><br />
<times><br />
<name>matrix</name><br />
<matrix><br />
<double>1</double><double>0.2</double><br />
<double>0</double><double>1</double><br />
</matrix><br />
</times><br />
</edit><br />
</match><br />
...<br />
</nowiki>}}<br />
{{Tip| Use the value 'embolden' for existing bold fonts in order to make them even bolder.}}<br />
<br />
=== Change rule overriding ===<br />
<br />
{{Accuracy|{{ic|/etc/fonts/conf.d/50-user.conf}} will be created again when {{Pkg|fontconfig}} is updated}}<br />
<br />
Fontconfig processes files in {{ic|/etc/fonts/conf.d}} in numerical order. This enables rules or files to override one another, but often confuses users about what file gets parsed last.<br />
<br />
To guarantee that personal settings take precedence over any other rules, change their ordering:<br />
# cd /etc/fonts/conf.d<br />
# mv 50-user.conf 99-user.conf<br />
<br />
This change seems however to be unnecessary for the most of the cases, because a user is given enough control by default to set up own font preferences, hinting and antialiasing properties, alias new fonts to generic font families, etc.<br />
<br />
=== Query the current settings ===<br />
<br />
To find out what settings are in effect, use {{ic|fc-match --verbose}}. eg.<br />
<br />
{{hc|$ fc-match --verbose Sans|<br />
family: "DejaVu Sans"(s)<br />
hintstyle: 3(i)(s)<br />
hinting: True(s)<br />
...<br />
}}<br />
<br />
Look up the meaning of the numbers at http://www.freedesktop.org/software/fontconfig/fontconfig-user.html. Eg. 'hintstyle: 3' means 'hintfull'<br />
<br />
== Applications without fontconfig support ==<br />
<br />
Some applications like [[URxvt]] and [[Emacs]] will ignore fontconfig settings. You can work around this by using {{ic|~/.Xresources}}, but it is as flexible as fontconfig. Example (see [[#Fontconfig configuration]] for explanations of the options):<br />
<br />
{{hc|~/.Xresources|<nowiki><br />
Xft.autohint: 0<br />
Xft.lcdfilter: lcddefault<br />
Xft.hintstyle: hintslight<br />
Xft.hinting: 1<br />
Xft.antialias: 1<br />
Xft.rgba: rgb<br />
</nowiki>}}<br />
<br />
Make sure the settings are loaded properly when X starts with {{ic|xrdb -q}} (see [[Xresources]] for more information).<br />
<br />
== Troubleshooting ==<br />
<br />
=== Distorted fonts ===<br />
<br />
{{Note|96 DPI is not a standard. You should use your monitor's actual DPI to get proper font rendering, especially when using subpixel rendering.}}<br />
<br />
If fonts are still unexpectedly large or small, poorly proportioned or simply rendering poorly, fontconfig may be using the incorrect DPI.<br />
<br />
Fontconfig should be able to detect DPI parameters as discovered by the Xorg server. You can check the automatically discovered DPI with {{ic|xdpyinfo}} (provided by the {{pkg|xorg-xdpyinfo}} package):<br />
<br />
{{hc|<nowiki>$ xdpyinfo | grep dots</nowiki>|<br />
resolution: 102x102 dots per inch<br />
}}<br />
<br />
If the DPI is detected incorrectly (usually due to an incorrect monitor [[Wikipedia:Extended Display Identification Data|EDID]]), you can specify it manually in the Xorg configuration, see [[Xorg#Display size and DPI]]. This is the recommended solution, but it may not work with buggy drivers.<br />
<br />
Fontconfig will default to the Xft.dpi variable if it is set. Xft.dpi is usually set by desktop environments (usually to Xorg's DPI setting) or manually in {{ic|~/.Xdefaults}} or {{ic|~/.Xresources}}. Use xrdb to query for the value:<br />
<br />
{{hc|<nowiki>$ xrdb -query | grep dpi</nowiki>|<br />
Xft.dpi: 102<br />
}}<br />
<br />
Those still having problems can fall back to manually setting the DPI used by fontconfig:<br />
<br />
...<br />
<!-- Setup for DPI=96 --><br />
<match target="pattern"><br />
<edit name="dpi" mode="assign"><double>102</double></edit><br />
</match><br />
...<br />
<br />
=== Calibri, Cambria, Monaco, etc. not rendering properly ===<br />
<br />
Some scalable fonts have embedded bitmap versions which are rendered instead, mainly at smaller sizes. Using [[Metric-compatible fonts]] as replacements can improve the rendering in these cases. <br />
<br />
You can also force using scalable fonts at all sizes by [[#Disable bitmap fonts|disabling embedded bitmap]], sacrificing some rendering quality.<br />
<br />
=== Applications overriding hinting ===<br />
<br />
Some applications or desktop environments may override default fontconfig hinting and anti-aliasing settings. This may happen with [[GNOME]] 3, for example while you are using Qt applications like {{pkg|vlc}} or {{pkg|smplayer}}. Use the specific configuration program for the application in such cases. For GNOME, try {{pkg|gnome-tweak-tool}}.<br />
<br />
=== Applications not picking up hinting from DE's settings ===<br />
<br />
For instance, under GNOME it sometimes happens that Firefox applies full hinting even when it's set to "none" in GNOME's settings, which results in sharp and widened fonts. In this case you would have to add hinting settings to your {{ic|fonts.conf}} file:<br />
<br />
<?xml version='1.0'?><br />
<!DOCTYPE fontconfig SYSTEM 'fonts.dtd'> <br />
<fontconfig><br />
<match target="font"><br />
<edit mode="assign" name="hinting"><br />
<bool>false</bool><br />
</edit><br />
</match><br />
</fontconfig><br />
<br />
In this example, hinting is set to "grayscale".<br />
<br />
=== Incorrect hinting in GTK applications on non-Gnome systems ===<br />
<br />
{{Accuracy|Mentions GTK relies on fontconfig, then claims that "some" fonts get the hinting "wrong", and ends up refering to Xft (but see e.g [http://doc.opensuse.org/documentation/html/openSUSE_113/opensuse-reference/cha.fontconfig.html#sec.fontconfig.xft]). IOW, unsupported claims and unclear relations}}<br />
<br />
[[GNOME]] uses the XSETTINGS system to configure font rendering. Outside of GNOME, GTK applications rely on fontconfig, but some fonts get the hinting wrong causing them to look too bold or too light. <br />
<br />
A simple solution is using {{AUR|xsettingsd-git}} to provide the configuration, for example:<br />
<br />
{{hc|~/.xsettingsd|<br />
Xft/Hinting 1<br />
Xft/RGBA "rgb"<br />
Xft/HintStyle "hintslight"<br />
Xft/Antialias 1<br />
}}<br />
<br />
Alternatively you could just write the font configuration as {{ic|Xft.*}} directives in {{ic|~/.Xresources}} without using a settings daemon.<br />
<br />
=== Helvetica font problem in generated PDFs ===<br />
<br />
If the following command<br />
<br />
fc-match helvetica<br />
<br />
produces<br />
<br />
helvR12-ISO8859-1.pcf.gz: "Helvetica" "Regular"<br />
<br />
then the bitmap font provided by {{Pkg|xorg-fonts-75dpi}} is likely to be embedded into PDFs generated by "Print to File" or "Export" in various applications. The bitmap font was probably installed as a consequence of installing the whole {{Grp|xorg}} group (which is usually NOT recommended). To solve the pixelized font problem, you can uninstall the package. Install {{Pkg|gsfonts}} (Type 1) or {{Pkg|tex-gyre-fonts}} (OpenType) for corresponding free subsitute of Helvetica (and other PostScript/PDF base fonts).<br />
<br />
You may also experience similar problem when you open a PDF which requires Helvetica but does not have it embedded for viewing.<br />
<br />
=== FreeType Breaking Bitmap Fonts ===<br />
<br />
Some users are reporting problems ({{Bug|52502}}) with bitmap fonts having changed names after upgrading {{Pkg|freetype2}} to version 2.7.1, creating havok in terminal emulators and several other programs such as {{Pkg|dwm}} or {{Pkg|dmenu}} by falling back to another (different) font. This was caused by the changes to the PCF font family format, which is described in their ''release notes'' [https://sourceforge.net/projects/freetype/files/freetype2/2.7.1/]. Users transitioning from the old format might want to create a ''font alias'' to remedy the problems, like the solution which is described in [https://forum.manjaro.org/t/terminus-font-name-fix-after-freetype2-update-to-2-7-1-1/15530], given here too:<br />
<br />
Assume we want to create an alias for {{Pkg|terminus-font}}, which was renamed from {{ic|Terminus}} to {{ic|xos4 Terminus}} in the previously described {{Pkg|freetype2}} update:<br />
* Create a configuration file in {{ic|/etc/fonts/conf.avail/}} for the ''font alias'':<br />
{{hc|/etc/fonts/conf.avail/33-TerminusPCFFont.conf|<?xml version<nowiki>=</nowiki>"1.0"?><br />
<!DOCTYPE fontconfig SYSTEM "fonts.dtd"><br />
<fontconfig><br />
<alias><br />
<family>Terminus</family><br />
<prefer><family>xos4 Terminus</family></prefer><br />
<default><family>fixed</family></default><br />
</alias><br />
</fontconfig><br />
}}<br />
* Create a symbolic link towards it in the {{ic|/etc/fonts/conf.d}} directory. In our example we would link as follows: {{ic|ln -s /etc/fonts/conf.avail/33-TerminusPCFFont.conf /etc/fonts/conf.d}} to make the change permanent.<br />
Everything should now work as it did before the update, the ''font alias'' should not be in effect, but make sure to either reload {{ic|.Xresources}} or restart the display server first so the affected programs can use the alias.<br />
<br />
== See also ==<br />
<br />
* [http://www.freedesktop.org/software/fontconfig/fontconfig-user.html Fontconfig Users' Guide]<br />
* [http://www.x.org/X11R6.8.2/doc/fonts.html Fonts in X11R6.8.2] - Official Xorg font information<br />
* [http://freetype.sourceforge.net/freetype2/ FreeType 2 overview]<br />
* [https://forums.gentoo.org/viewtopic-t-723341.html Gentoo font-rendering thread]<br />
* [http://www.freetype.org/freetype2/docs/text-rendering-general.html On slight hinting]</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Haskell&diff=480491Haskell2017-06-26T02:19:58Z<p>Fylwind: /* Haskell development tools */ Add ghc-static</p>
<hr />
<div>[[Category:Programming languages]]<br />
[[ja:Haskell]]<br />
[http://www.haskell.org Haskell] is a general purpose, purely functional, programming language.<br />
<br />
== Installation ==<br />
<br />
Haskell generates machine code that can be run natively on Linux. There is nothing special required to run a binary (already compiled) software, like the ones provided in the [[official repositories]] or by the [[ArchHaskell]] group. On the other side, [[AUR]] packages or source codes requires a compiler to build the software.<br />
<br />
Installing the compiler alone permits to build Haskell source code. A few additional tools are needed for development work.<br />
<br />
=== Compiler ===<br />
<br />
To build a Haskell source–code into native–code, a compiler must be installed. There are several [http://www.haskell.org/haskellwiki/Implementations implementations available], but the one used most (which is now ''de facto'' the reference) is the GHC (Glasgow Haskell Compiler). It is available in the official repositories as {{Pkg|ghc}}.<br />
<br />
You can try it with the following file:<br />
<br />
{{hc|Main.hs|main &#61; putStrLn "Hello, World"}}<br />
<br />
and by running:<br />
<br />
{{hc|<br />
$ ghc -dynamic Main.hs<br />
$ ./Main |<br />
Hello, World<br />
}}<br />
<br />
The {{ic|-dynamic}} flag is needed because the {{Pkg|ghc}} package no longer ships with static libraries, and GHC uses static linking by default. If you do need the static libraries, install {{Pkg|ghc-static}}.<br />
<br />
=== Haskell development tools ===<br />
<br />
To start developing in Haskell easily, one option is the [http://www.haskell.org/platform/ haskell-platform] bundle which is described as:<br />
<br />
:''The easiest way to get started with programming Haskell. It comes with all you need to get up and running. Think of it as "Haskell: batteries included".''<br />
<br />
Although an [[AUR]] package exists ({{AUR|haskell-platform}}{{Broken package link|{{aur-mirror|haskell-platform}}}}), the Haskell Platform can be advantageously replaced by [[installing]] the [https://bbs.archlinux.org/viewtopic.php?pid=1151382#p1151382 following packages] from the [[official repositories]]:<br />
<br />
* ghc ({{Pkg|ghc}} and {{Pkg|ghc-static}}) — Compiler with dynamic [https://ghc.haskell.org/trac/ghc/wiki/Commentary/Libraries boot libraries], and supplementary static boot libraries<br />
* cabal-install ({{Pkg|cabal-install}}) — A command line interface for ''Cabal'' and ''Hackage''<br />
* haddock ({{Pkg|haskell-haddock-api}} and {{Pkg|haskell-haddock-library}}) — Tools for generating documentation<br />
* happy ({{Pkg|happy}}) — Parser generator<br />
* alex ({{Pkg|alex}}) — Lexical analyzer generator<br />
<br />
Alternatively, you can use {{Pkg|stack}} to manage your Haskell environment by following the [https://docs.haskellstack.org/en/stable/install_and_upgrade/#arch-linux Arch Linux install instructions].<br />
<br />
== Managing Haskell packages ==<br />
<br />
{{Expansion|[https://haskellstack.org/ Stack utility] and [https://www.stackage.org/ Stackage repository] already have adoption in Haskell world. If you familiar with them, please provide description.}}<br />
<br />
Many Haskell libraries and executables are grouped in packages. They are all available on [http://hackage.haskell.org Hackage]. To install and manage these packages, several methods are available and unusual ones are explained in the rest of this section.<br />
<br />
The recommended workflow is the following:<br />
* [[Official repositories]] or [[ArchHaskell|ArchHaskell repository]] as principal source of Haskell packages (the ''or'' is exclusive here)<br />
* [[#cabal-install|cabal-install]] (possibly with sandboxes) for Haskell development<br />
* [[Arch User Repository]] for packages that are not available elsewhere<br />
<br />
[https://github.com/magthe/cblrepo cblrepo] is a tool used for maintaining Haskell packages for Linux distributions. A wrapper around this, {{AUR|cabal2pkgbuild-git}}{{Broken package link|{{aur-mirror|cabal2pkgbuild-git}}}}, can create PKGBUILD files from Hackage packages. See [[Haskell package guidelines]] for more information on ''creating new'' Haskell packages.<br />
<br />
=== Pros/Cons of the different methods ===<br />
<br />
The following table documents the advantages and disadvantages of different package management styles.<br />
<br />
{| class="wikitable"<br />
! '''Method'''<br />
! '''Pros'''<br />
! '''Cons'''<br />
|-<br />
| [[Official repositories]] || Provided by ArchLinux developers, consistent versions of packages, already compiled || Only a few packages available<br />
|-<br />
| [[#ArchHaskell repository|ArchHaskell repository]] || Provided by ArchHaskell group, consistent versions of packages, already compiled || Need manual intervention to get started with<br />
|-<br />
| [[#cabal-install|cabal-install]] || All packages available || Installed in home folder, {{Pkg|cabal-install}} [https://ivanmiljenovic.wordpress.com/2010/03/15/repeat-after-me-cabal-is-not-a-package-manager is not a package manager], incompatible versions of packages possible (aka. [http://www.haskell.org/haskellwiki/Cabal/Survival#What_is_the_difficulty_caused_by_Cabal-install.3F cabal hell])<br />
|-<br />
| [[Arch User Repository]] || Simple to get started || Risk of unmaintained or orphaned packages, incompatible versions of packages possible<br />
|-<br />
|}<br />
<br />
=== ArchHaskell repository ===<br />
<br />
See [[ArchHaskell]] for details.<br />
<br />
=== cabal-install ===<br />
<br />
{{warning|Discouraged method, keep in mind that {{Pkg|cabal-install}} [https://ivanmiljenovic.wordpress.com/2010/03/15/repeat-after-me-cabal-is-not-a-package-manager is not a package manager].}}<br />
<br />
{{Note|The only exception is for Haskell development, where {{Pkg|cabal-install}} is the recommended tool. Since version 1.18, cabal provides a ''sandbox'' system that permits to isolate different versions of libraries for different projects. There is an introduction to cabal sandbox [http://coldwa.st/e/blog/2013-08-20-Cabal-sandbox.html here].}}<br />
<br />
==== Preparation and $PATH ====<br />
Install {{Pkg|cabal-install}} from the [[official repositories]].<br />
<br />
To run installed executables without specifying the path, the cabal binary folder {{ic|~/.cabal/bin}} must be added to the {{ic|$PATH}} variable. That can be done by putting the following line in your shell configuration file, for instance {{ic|~/.bashrc}} for {{Pkg|bash}} or {{ic|~/.zshrc}} for {{Pkg|zsh}}:<br />
{{bc|PATH&#61;$PATH:~/.cabal/bin}}<br />
To run executables within a cabal sandbox, you must also add {{bc|PATH&#61;$PATH:.cabal-sandbox/bin}}<br />
<br />
==== Installing packages ====<br />
{{bc|<br />
$ cabal update<br />
$ cabal install <pkg>}}<br />
<br />
It is possible to install a package system–wide with the {{ic|--global}} flag, but this is '''strongly discouraged'''. With the user–wide install, all files are kept in {{ic|~/.cabal}} and libraries are registered to {{ic|~/.ghc}}, offering the possibility to do a clean-up easily by simply removing these folders. With system–wide install, the files will be dispersed in the file system and difficult to manage.<br />
<br />
==== Removing packages ====<br />
There is no easy way to do it. Cabal does not have removing process.<br />
<br />
One thing to make your life easier is use zsh auto completion to find all the haskell packages.<br />
<br />
If you want/can fix/reinstall whole Haskell package system - remove {{ic|~/.cabal}} and {{ic|~/.ghc}} and start from scratch.<br />
<br />
== See also ==<br />
<br />
*[http://learnyouahaskell.com/ Learn You a Haskell for Great Good!]<br />
*[http://book.realworldhaskell.org/ Real World Haskell]</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Haskell&diff=480490Haskell2017-06-26T02:16:41Z<p>Fylwind: /* Compiler */ -dynamic flag is needed because 'ghc' doesn't come with static libs anymore</p>
<hr />
<div>[[Category:Programming languages]]<br />
[[ja:Haskell]]<br />
[http://www.haskell.org Haskell] is a general purpose, purely functional, programming language.<br />
<br />
== Installation ==<br />
<br />
Haskell generates machine code that can be run natively on Linux. There is nothing special required to run a binary (already compiled) software, like the ones provided in the [[official repositories]] or by the [[ArchHaskell]] group. On the other side, [[AUR]] packages or source codes requires a compiler to build the software.<br />
<br />
Installing the compiler alone permits to build Haskell source code. A few additional tools are needed for development work.<br />
<br />
=== Compiler ===<br />
<br />
To build a Haskell source–code into native–code, a compiler must be installed. There are several [http://www.haskell.org/haskellwiki/Implementations implementations available], but the one used most (which is now ''de facto'' the reference) is the GHC (Glasgow Haskell Compiler). It is available in the official repositories as {{Pkg|ghc}}.<br />
<br />
You can try it with the following file:<br />
<br />
{{hc|Main.hs|main &#61; putStrLn "Hello, World"}}<br />
<br />
and by running:<br />
<br />
{{hc|<br />
$ ghc -dynamic Main.hs<br />
$ ./Main |<br />
Hello, World<br />
}}<br />
<br />
The {{ic|-dynamic}} flag is needed because the {{Pkg|ghc}} package no longer ships with static libraries, and GHC uses static linking by default. If you do need the static libraries, install {{Pkg|ghc-static}}.<br />
<br />
=== Haskell development tools ===<br />
<br />
To start developing in Haskell easily, one option is the [http://www.haskell.org/platform/ haskell-platform] bundle which is described as:<br />
<br />
:''The easiest way to get started with programming Haskell. It comes with all you need to get up and running. Think of it as "Haskell: batteries included".''<br />
<br />
Although an [[AUR]] package exists ({{AUR|haskell-platform}}{{Broken package link|{{aur-mirror|haskell-platform}}}}), the Haskell Platform can be advantageously replaced by [[installing]] the [https://bbs.archlinux.org/viewtopic.php?pid=1151382#p1151382 following packages] from the [[official repositories]]:<br />
<br />
* ghc ({{Pkg|ghc}}) — The compiler<br />
* cabal-install ({{Pkg|cabal-install}}) — A command line interface for ''Cabal'' and ''Hackage''<br />
* haddock ({{Pkg|haskell-haddock-api}} and {{Pkg|haskell-haddock-library}}) — Tools for generating documentation<br />
* happy ({{Pkg|happy}}) — Parser generator<br />
* alex ({{Pkg|alex}}) — Lexical analyzer generator<br />
<br />
Alternatively, you can use {{Pkg|stack}} to manage your Haskell environment by following the [https://docs.haskellstack.org/en/stable/install_and_upgrade/#arch-linux Arch Linux install instructions].<br />
<br />
== Managing Haskell packages ==<br />
<br />
{{Expansion|[https://haskellstack.org/ Stack utility] and [https://www.stackage.org/ Stackage repository] already have adoption in Haskell world. If you familiar with them, please provide description.}}<br />
<br />
Many Haskell libraries and executables are grouped in packages. They are all available on [http://hackage.haskell.org Hackage]. To install and manage these packages, several methods are available and unusual ones are explained in the rest of this section.<br />
<br />
The recommended workflow is the following:<br />
* [[Official repositories]] or [[ArchHaskell|ArchHaskell repository]] as principal source of Haskell packages (the ''or'' is exclusive here)<br />
* [[#cabal-install|cabal-install]] (possibly with sandboxes) for Haskell development<br />
* [[Arch User Repository]] for packages that are not available elsewhere<br />
<br />
[https://github.com/magthe/cblrepo cblrepo] is a tool used for maintaining Haskell packages for Linux distributions. A wrapper around this, {{AUR|cabal2pkgbuild-git}}{{Broken package link|{{aur-mirror|cabal2pkgbuild-git}}}}, can create PKGBUILD files from Hackage packages. See [[Haskell package guidelines]] for more information on ''creating new'' Haskell packages.<br />
<br />
=== Pros/Cons of the different methods ===<br />
<br />
The following table documents the advantages and disadvantages of different package management styles.<br />
<br />
{| class="wikitable"<br />
! '''Method'''<br />
! '''Pros'''<br />
! '''Cons'''<br />
|-<br />
| [[Official repositories]] || Provided by ArchLinux developers, consistent versions of packages, already compiled || Only a few packages available<br />
|-<br />
| [[#ArchHaskell repository|ArchHaskell repository]] || Provided by ArchHaskell group, consistent versions of packages, already compiled || Need manual intervention to get started with<br />
|-<br />
| [[#cabal-install|cabal-install]] || All packages available || Installed in home folder, {{Pkg|cabal-install}} [https://ivanmiljenovic.wordpress.com/2010/03/15/repeat-after-me-cabal-is-not-a-package-manager is not a package manager], incompatible versions of packages possible (aka. [http://www.haskell.org/haskellwiki/Cabal/Survival#What_is_the_difficulty_caused_by_Cabal-install.3F cabal hell])<br />
|-<br />
| [[Arch User Repository]] || Simple to get started || Risk of unmaintained or orphaned packages, incompatible versions of packages possible<br />
|-<br />
|}<br />
<br />
=== ArchHaskell repository ===<br />
<br />
See [[ArchHaskell]] for details.<br />
<br />
=== cabal-install ===<br />
<br />
{{warning|Discouraged method, keep in mind that {{Pkg|cabal-install}} [https://ivanmiljenovic.wordpress.com/2010/03/15/repeat-after-me-cabal-is-not-a-package-manager is not a package manager].}}<br />
<br />
{{Note|The only exception is for Haskell development, where {{Pkg|cabal-install}} is the recommended tool. Since version 1.18, cabal provides a ''sandbox'' system that permits to isolate different versions of libraries for different projects. There is an introduction to cabal sandbox [http://coldwa.st/e/blog/2013-08-20-Cabal-sandbox.html here].}}<br />
<br />
==== Preparation and $PATH ====<br />
Install {{Pkg|cabal-install}} from the [[official repositories]].<br />
<br />
To run installed executables without specifying the path, the cabal binary folder {{ic|~/.cabal/bin}} must be added to the {{ic|$PATH}} variable. That can be done by putting the following line in your shell configuration file, for instance {{ic|~/.bashrc}} for {{Pkg|bash}} or {{ic|~/.zshrc}} for {{Pkg|zsh}}:<br />
{{bc|PATH&#61;$PATH:~/.cabal/bin}}<br />
To run executables within a cabal sandbox, you must also add {{bc|PATH&#61;$PATH:.cabal-sandbox/bin}}<br />
<br />
==== Installing packages ====<br />
{{bc|<br />
$ cabal update<br />
$ cabal install <pkg>}}<br />
<br />
It is possible to install a package system–wide with the {{ic|--global}} flag, but this is '''strongly discouraged'''. With the user–wide install, all files are kept in {{ic|~/.cabal}} and libraries are registered to {{ic|~/.ghc}}, offering the possibility to do a clean-up easily by simply removing these folders. With system–wide install, the files will be dispersed in the file system and difficult to manage.<br />
<br />
==== Removing packages ====<br />
There is no easy way to do it. Cabal does not have removing process.<br />
<br />
One thing to make your life easier is use zsh auto completion to find all the haskell packages.<br />
<br />
If you want/can fix/reinstall whole Haskell package system - remove {{ic|~/.cabal}} and {{ic|~/.ghc}} and start from scratch.<br />
<br />
== See also ==<br />
<br />
*[http://learnyouahaskell.com/ Learn You a Haskell for Great Good!]<br />
*[http://book.realworldhaskell.org/ Real World Haskell]</div>Fylwindhttps://wiki.archlinux.org/index.php?title=PKGBUILD&diff=467381PKGBUILD2017-02-01T17:10:54Z<p>Fylwind: /* install */ mention Pacman hooks, which often deprecate .install scripts in many cases</p>
<hr />
<div>[[Category:Package development]]<br />
[[cs:PKGBUILD]]<br />
[[da:PKGBUILD]]<br />
[[el:PKGBUILD]]<br />
[[es:PKGBUILD]]<br />
[[fa:PKGBUILD]]<br />
[[fr:PKGBUILD]]<br />
[[it:PKGBUILD]]<br />
[[ja:PKGBUILD]]<br />
[[pl:PKGBUILD]]<br />
[[ru:PKGBUILD]]<br />
[[sr:PKGBUILD]]<br />
[[zh-hans:PKGBUILD]]<br />
[[zh-hant:PKGBUILD]]<br />
{{Related articles start}}<br />
{{Related|Arch packaging standards}}<br />
{{Related|Arch Build System}}<br />
{{Related|Creating packages}}<br />
{{Related|.SRCINFO}}<br />
{{Related|:Category:Package development}}<br />
{{Related|Pacman tips}}<br />
{{Related|Arch User Repository}}<br />
{{Related|makepkg}}<br />
{{Related|pacman}}<br />
{{Related articles end}}<br />
<br />
This article discusses variables definable by the maintainer in a PKGBUILD. For information on the PKGBUILD functions and creating packages in general, refer to [[Creating packages]]. Also read {{ic|man PKGBUILD}}.<br />
<br />
A PKGBUILD is a shell script containing the build information required by [[Arch Linux]] packages.<br />
<br />
Packages in Arch Linux are built using the [[makepkg]] utility. When ''makepkg'' is run, it searches for a {{ic|PKGBUILD}} file in the current directory and follows the instructions therein to either compile or otherwise acquire the files to build a package archive ({{ic|''pkgname''.pkg.tar.xz}}). The resulting package contains binary files and installation instructions, readily installable with [[pacman]].<br />
<br />
Mandatory variables are {{ic|pkgname}}, {{ic|pkgver}}, {{ic|pkgrel}}, and {{ic|arch}}. {{ic|license}} is not strictly necessary to build a package, but is recommended for any PKGBUILDs shared with others, as ''makepkg'' will produce a warning if not present.<br />
<br />
It is a common practice to define the variables in the PKGBUILD in same order as given here. However, this is not mandatory, as long as correct [[Bash]] syntax is used.<br />
<br />
== Package name ==<br />
<br />
=== pkgbase ===<br />
<br />
An optional global directive is available when building a split package. {{ic|pkgbase}} is used to refer to the group of packages in the output of ''makepkg'' and in the naming of source-only tarballs. If not specified, the first element in the {{ic|pkgname}} array is used. The variable is not allowed to begin with a hyphen. All values for split packages default to the global ones given in the PKGBUILD. Everything, except [[#makedepends]], [[#Sources]], and [[#Integrity]] variables can be overridden within each split package's {{ic|package()}} function.<br />
<br />
=== pkgname ===<br />
<br />
The name(s) of the package(s). This should consist of lowercase alphanumerics and any of the following characters: {{ic|@}}, {{ic|.}}, {{ic|_}}, {{ic|+}}, {{ic|-}} (at symbol, dot, underscore, plus, hyphen). Names are not allowed to start with hyphens. For the sake of consistency, {{ic|pkgname}} should match the name of the source tarball of the software: for instance, if the software is in {{ic|foobar-2.5.tar.gz}}, use {{ic|1=pkgname=foobar}}. The name of the directory containing the PKGBUILD should also match the {{ic|pkgname}}.<br />
<br />
Split packages should be defined as an array, e.g. {{ic|1=pkgname=('foo' 'bar')}}.<br />
<br />
== Version ==<br />
<br />
=== pkgver ===<br />
<br />
The version of the package. This should be the same as the version released by the author of the package. It can contain letters, numbers, periods and underscores, but '''not''' a hyphen ({{ic|-}}). If the author of the software uses one, replace it with an underscore ({{ic|_}}). If the {{ic|pkgver}} variable is used later in the PKGBUILD, then the underscore can easily be substituted for a hyphen, e.g. {{ic|1=source=("$pkgname-${pkgver//_/-}.tar.gz")}}.<br />
<br />
{{Note|If upstream uses a timestamp versioning such as {{ic|30102014}}, ensure to use the reversed date, i.e. {{ic|20141030}} ([[Wikipedia:ISO 8601|ISO 8601]] format). Otherwise it will not appear as a newer version.}}<br />
<br />
{{Tip|<br />
* The ordering of uncommon values can be tested with [https://www.archlinux.org/pacman/vercmp.8.html vercmp], which is provided by the [[pacman]] package.<br />
* [[makepkg]] can automatically [http://allanmcrae.com/2013/04/pacman-4-1-released/ update] this variable by defining a {{ic|pkgver()}} function in the PKGBUILD. See [[VCS package guidelines#The pkgver() function]] for details.<br />
}}<br />
<br />
=== pkgrel ===<br />
<br />
The release number. This is usually a positive integer number that allows to differentiate between consecutive builds of the same version of a package. As fixes and additional features are added to the PKGBUILD that influence the resulting package, the {{ic|pkgrel}} should be incremented by 1. When a new version of the software is released, this value must be reset to 1. In exceptional cases other formats can be found in use, such as ''major.minor''.<br />
<br />
=== epoch ===<br />
<br />
{{Warning|{{ic|epoch}} should only be used when absolutely required to do so.}}<br />
<br />
Used to force the package to be seen as newer than any previous version with a lower epoch. This value is required to be a positive integer; the default is 0. It is used when the version numbering scheme of a package changes (or is alphanumeric), breaking normal version comparison logic. For example:<br />
<br />
{{hc|1=<br />
pkgver=5.13<br />
pkgrel=2<br />
epoch=1<br />
|2=<br />
1:5.13-2<br />
}}<br />
<br />
See [https://www.archlinux.org/pacman/pacman.8.html pacman(8)] for more information on version comparisons.<br />
<br />
== Generic ==<br />
<br />
=== pkgdesc ===<br />
<br />
The description of the package. This is recommended to be 80 characters or less and should not include the package name in a self-referencing way, unless the application name differs from the package name. For example, use {{ic|1=pkgdesc="Text editor for X11"}} instead of {{ic|1=pkgdesc="Nedit is a text editor for X11"}}.<br />
<br />
Also it is important to use keywords wisely to increase the chances of appearing in relevant search queries.<br />
<br />
=== arch ===<br />
<br />
An array of architectures that the PKGBUILD is intended to build and work on. Arch officially supports only {{ic|i686}} and {{ic|x86_64}}, but projects like [http://archlinuxarm.org/ Arch Linux ARM] provide support for other architectures such as {{ic|arm}} for armv5, {{ic|armv6h}} for armv6 hardfloat, {{ic|armv7h}} for armv7 hardfloat, and {{ic|aarch64}} for armv8 64bit.<br />
<br />
If a package is architecture-independent in its compiled state (shell scripts, fonts, themes, many types of extensions, etc.) then use {{ic|1=arch=('any')}}. Please note that, as this is intended for packages that can be built once and used on any architecture, it will cause the package to be labeled {{ic|-any}} as opposed to {{ic|-i686}}, {{ic|-x86_64}}, etc.<br />
<br />
If instead a package can be compiled for any architecture, but is architecture-specific once compiled, specify all architectures officially supported by Arch, i.e. {{ic|1=arch=('i686' 'x86_64')}}.<br />
<br />
The target architecture can be accessed with the variable {{ic|$CARCH}} during a build.<br />
<br />
=== url ===<br />
The URL of the official site of the software being packaged.<br />
<br />
=== license ===<br />
The license under which the software is distributed. The {{pkg|licenses}} package contains many commonly used licenses, which are installed to {{ic|/usr/share/licenses/common}}. If a package is licensed under one of these licenses, the value should be set to the directory name, e.g. {{ic|1=license=('GPL')}}. If the appropriate license is not included, several things must be done:<br />
<br />
# Add {{ic|custom}} to the {{ic|license}} array. Optionally, you can replace {{ic|custom}} with {{ic|custom:''name of license''}}. Once a license is used in two or more packages in an official repository (including {{ic|[community]}}), it becomes a part of the {{Pkg|licenses}} package.<br />
# Install the license in: {{ic|/usr/share/licenses/''pkgname''/}}, e.g. {{ic|/usr/share/licenses/foobar/LICENSE}}.<br />
# If the license is only found in a website, then you need to separately include it in the package.<br />
<br />
* The [[Wikipedia:BSD License|BSD]], [[Wikipedia:MIT License|MIT]], [[Wikipedia:ZLIB license|zlib/png]] and [[Wikipedia:Python License|Python]] licenses are special cases and could not be included in the {{pkg|licenses}} package. For the sake of the {{ic|license}} array, it is treated as a common license ({{ic|1=license=('BSD')}}, {{ic|1=license=('MIT')}}, {{ic|1=license=('ZLIB')}} and {{ic|1=license=('Python')}}), but technically each one is a custom license, because each one has its own copyright line. Any packages licensed under these four should have its own unique license stored in {{ic|/usr/share/licenses/''pkgname''}}. Some packages may not be covered by a single license. In these cases, multiple entries may be made in the {{ic|license}} array, e.g. {{ic|1=license=('GPL' 'custom:''name of license''')}}.<br />
* (L)GPL has many versions and permutations of those versions. For (L)GPL software, the convention is:<br />
** (L)GPL — (L)GPLv2 or any later version<br />
** (L)GPL2 — (L)GPL2 only<br />
** (L)GPL3 — (L)GPL3 or any later version<br />
* If after researching the issue no license can be determined, [https://projects.archlinux.org/pacman.git/tree/proto/PKGBUILD.proto PKGBUILD.proto] suggests using {{ic|unknown}}. However, upstream should be contacted about the conditions under which the software is (and is not) available.<br />
<br />
{{Tip|Some software authors do not provide separate license file and describe distribution rules in section of common {{ic|ReadMe.txt}}. This information can be extracted to a separate file during {{ic|build()}} with something like {{ic|sed -n '/'''This software'''/,/''' thereof.'''/p' ReadMe.txt > LICENSE}}}}<br />
<br />
=== groups ===<br />
<br />
The [[Creating packages#Meta packages and groups|group]] the package belongs in. For instance, when installing the {{Grp|kdebase}} package, it installs all packages belonging in that group.<br />
<br />
== Dependencies ==<br />
<br />
{{Note|Additional architecture-specific arrays can be added by appending an underscore and the architecture name, e.g. {{ic|1=depends_i686=()}}, {{ic|1=optdepends_x86_64=()}}.<br />
}}<br />
<br />
=== depends ===<br />
An array of packages that must be installed before the software can be run. Version restrictions can be specified with comparison operators, e.g. {{ic|1=depends=('foobar>=1.8.0')}}; if multiple restrictions are needed, the dependency can be repeated for each, e.g. {{ic|1=depends=('foobar>=1.8.0' 'foobar<2.0.0')}}. <br />
<br />
Dependencies that are provided by other dependencies do not need to be listed. For instance, if a package ''foo'' depends on both ''bar'' and ''baz'', and the ''bar'' package depends in turn on ''baz'' too, ''baz'' does not need to be included in ''foo'''s {{ic|depends}} array.<br />
<br />
If the dependency name appears to be a library, e.g. {{ic|1=depends=('libfoobar.so')}}, makepkg will try to find a binary that depends on the library in the built package and append the version needed by the binary. Appending the version yourself disables automatic detection, e.g. {{ic|1=depends=('libfoobar.so=2')}}.<br />
<br />
=== optdepends ===<br />
<br />
An array of packages that are not needed for the software to function, but provide additional features. This may imply that not all executables provided by a package will function without the respective optdepends.[https://lists.archlinux.org/pipermail/arch-general/2014-December/038124.html] If the software works on multiple alternative dependencies, all of them can be listed here, instead of the {{ic|depends}} array.<br />
<br />
A short description of the extra functionality each optdepend provides should also be noted:<br />
<br />
optdepends=('cups: printing support'<br />
'sane: scanners support'<br />
'libgphoto2: digital cameras support'<br />
'alsa-lib: sound support'<br />
'giflib: GIF images support'<br />
'libjpeg: JPEG images support'<br />
'libpng: PNG images support')<br />
<br />
=== makedepends ===<br />
An array of packages that are '''only''' required to build the software. The minimum dependency version can be specified in the same format as in the {{ic|depends}} array. The packages in the {{ic|depends}} array are implicitly required to build the package, they should not be duplicated here.<br />
<br />
{{Tip|The following can be used to see if a particular package is either in the {{Grp|base-devel}} group or pulled in by a members of the group:<br />
<br />
<nowiki>$ LC_ALL=C pacman -Si $(pactree -rl ''package'') 2>/dev/null | grep -q "^Groups *:.*base-devel"</nowiki><br />
<br />
}}<br />
<br />
{{Note|The group {{Grp|base-devel}} is assumed to be already installed when building with ''makepkg''. Members of this group '''should not''' be included in {{ic|makedepends}} array.}}<br />
<br />
=== checkdepends ===<br />
An array of packages that the software depends on to run its test suite, but are not needed at runtime. Packages in this list follow the same format as {{ic|depends}}. These dependencies are only considered when the [[Creating packages#check()|check()]] function is present and is to be run by makepkg. <br />
<br />
{{Note|The group {{Grp|base-devel}} is assumed to be already installed when building with ''makepkg''. Members of this group '''should not''' be included in {{ic|checkdepends}} array.}}<br />
<br />
== Package relations ==<br />
<br />
{{Note|Additional architecture-specific arrays can be added by appending an underscore and the architecture name, e.g. {{ic|1=provides_i686=()}}, {{ic|1=conflicts_x86_64=()}}.}}<br />
<br />
=== provides ===<br />
An array of additional packages that the software provides the features of (or a virtual package such as {{Ic|cron}} or {{Ic|sh}}). Packages providing the same item can be installed side-by-side, unless at least one of them uses a {{ic|conflicts}} array.<br />
<br />
{{Warning|A version that the package provides should be mentioned ({{ic|pkgver}} and perhaps the {{ic|pkgrel}}), if packages needing the software may require one. For instance, a modified ''qt'' package version 3.3.8, named ''qt-foobar'', should use {{ic|1=provides=('qt=3.3.8')}}; using {{ic|1=provides=('qt')}} would cause the dependencies that require a specific version of ''qt'' to fail. Do not add {{ic|pkgname}} to the {{ic|provides}} array, as it is done automatically.}}<br />
<br />
=== conflicts ===<br />
<br />
An array of packages that conflict with, or cause problems with the package, if installed. All these packages and packages providing this item will need to be removed. The version properties of the conflicting packages can also be specified in the same format as the {{ic|depends}} array.<br />
<br />
This means when you write a package for which an alternate version is available (be it in the official packages or in the AUR) and your package conflicts that version, you need to put the other versions in your {{ic|conflicts}} array as well. Specifying conflict is not only for packages in the official repositories; if another AUR package conflicts with yours, you need to put that AUR package in your {{ic|conflicts}} array as well.<br />
<br />
However, there is an exception to this. If your package provides a package name and the other packages, conflicting with yours, provide the same package, you do not need to specify that conflicting package in your {{ic|conflicts}} array. Let us take a concrete example:<br />
<br />
* {{pkg|netbeans}} provides {{ic|netbeans}}<br />
* {{aur|netbeans-javase}} provides {{ic|netbeans}} and conflicts {{ic|netbeans}}<br />
* {{aur|netbeans-php}} provides {{ic|netbeans}} and conflicts {{ic|netbeans}} but does not need to conflicts {{aur|netbeans-javase}} since pacman is smart enough to figure out these packages are incompatible since they provide the same feature and are in conflict with it.<br />
The same applies in the reverse order: {{aur|netbeans-php}} does not need to conflict with {{aur|netbeans-javase}} as well, because they provide the same package.<br />
<br />
Even this is not recommended, in practise, putting the conflicting packages in all directions is not always applicable especially if all these packages are maintained by different people. This exception is useful and comes thus in handy. That way you know you do not need to contact all package maintainers for which you package is in conflict to ask them to include your package name in their {{ic|conflicts}} array.<br />
<br />
=== replaces ===<br />
An array of obsolete packages that are replaced by the package, e.g. {{pkg|wireshark-gtk}} uses {{ic|1=replaces=('wireshark')}}. When syncing, ''pacman'' will immediately replace an installed package upon encountering another package with the matching {{ic|replaces}} in the repositories. If providing an alternate version of an already existing package or uploading to the [[AUR]], use the {{ic|conflicts}} and {{ic|provides}} arrays, which are only evaluated when actually installing the conflicting package.<br />
<br />
== Others ==<br />
<br />
=== backup ===<br />
<br />
An array of files that can contain user-made changes and should be preserved during upgrade or removal of a package, primarily intended for configuration files in {{ic|/etc}}.<br />
<br />
Files in this array should use '''relative''' paths without the leading slash ({{ic|/}}) (e.g. {{ic|etc/pacman.conf}}, instead of {{ic|/etc/pacman.conf}}).<br />
<br />
When updating, new versions may be saved as {{ic|file.pacnew}} to avoid overwriting a file which already exists and was previously modified by the user. Similarly, when the package is removed, user-modified files will be preserved as {{ic|file.pacsave}} unless the package was removed with the {{ic|pacman -Rn}} command.<br />
<br />
See also [[Pacnew and Pacsave files]].<br />
<br />
=== options ===<br />
This array allows overriding some of the default behavior of ''makepkg'', defined in {{Ic|/etc/makepkg.conf}}. To set an option, include the name in the array. To reverse the default behavior, place an '''{{ic|!}}''' at the front.<br />
<br />
The full list of the available options can be found in [https://www.archlinux.org/pacman/PKGBUILD.5.html PKGBUILD(5)].<br />
<br />
=== install ===<br />
The name of the {{ic|.install}} script to be included in the package. This should be the same as {{ic|pkgname}}. ''pacman'' has the ability to store and execute a package-specific script when it installs, removes or upgrades a package. The script contains the following functions which run at different times:<br />
<br />
* {{ic|pre_install}} — The script is run right before files are extracted. One argument is passed: new package version.<br />
* {{ic|post_install}} — The script is run right after files are extracted. One argument is passed: new package version.<br />
* {{ic|pre_upgrade}} — The script is run right before files are extracted. Two arguments are passed in the following order: new package version, old package version.<br />
* {{ic|post_upgrade}} — The script is run right after files are extracted. Two arguments are passed in the following order: new package version, old package version.<br />
* {{ic|pre_remove}} — The script is run right before files are removed. One argument is passed: old package version.<br />
* {{ic|post_remove}} — The script is run right after files are removed. One argument is passed: old package version.<br />
<br />
Each function is run [[chroot]]ed inside the ''pacman'' install directory. See [https://bbs.archlinux.org/viewtopic.php?pid=913891 this thread].<br />
<br />
{{Tip|A prototype {{ic|.install}} is provided at [https://projects.archlinux.org/pacman.git/plain/proto/proto.install /usr/share/pacman/proto.install].}}<br />
<br />
{{Note|Do not end the script with {{ic|exit}}. This would prevent the contained functions from executing.}}<br />
<br />
{{Note|1=Many operations previously done using {{ic|.install}} scripts (e.g. updating the font cache) are now done automatically via Pacman hooks (e.g. {{ic|1=/usr/share/libalpm/hooks/[https://git.archlinux.org/svntogit/packages.git/tree/trunk/fontconfig.hook?h=packages/fontconfig fontconfig.hook]}}), rendering them unnecessary.}}<br />
<br />
=== changelog ===<br />
<br />
The name of the package changelog. To view changelogs for installed packages (that have this file):<br />
<br />
$ pacman -Qc ''pkgname''<br />
<br />
== Sources ==<br />
<br />
=== source ===<br />
<br />
An array of files needed to build the package. It must contain the location of the software source, which in most cases is a full HTTP or FTP URL. The previously set variables {{ic|pkgname}} and {{ic|pkgver}} can be used effectively here (e.g. {{ic|<nowiki>source=("https://example.com/$pkgname-$pkgver.tar.gz")</nowiki>}}).<br />
<br />
Files can also be supplied directly in the location of the {{ic|PKGBUILD}} and added to this array. These paths are resolved relative to the directory of the {{ic|PKGBUILD}}. Before the actual build process is started, all of the files referenced in this array will be downloaded or checked for existence, and ''makepkg'' will not proceed, if any are missing.<br />
<br />
''.install'' files are recognized automatically by ''makepkg'' and should not be included in the source array. Files in the source array with extensions ''.sig'', ''.sign'', or ''.asc'' are recognized by ''makepkg'' as PGP signatures and will be automatically used to verify the integrity of the corresponding source file.<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* Additional architecture-specific arrays can be added by appending an underscore and the architecture name, e.g. {{ic|1=source_i686=()}}. There must be a corresponding integrity array with checksums, e.g. {{ic|1=sha256sums_x86_64=()}}.<br />
* File names of downloaded sources should be globally unique, because the [[makepkg#Package_output|SRCDEST]] variable could be the same directory for all packages. This can be ensured by specifying an alternative source name with the syntax {{ic|1=source=(<nowiki>'</nowiki>''filename''::''fileuri''<nowiki>'</nowiki>)}}, where the chosen {{ic|''filename''}} should be related to the package name: {{bc|<nowiki>source=("project_name::hg+https://googlefontdirectory.googlecode.com/hg/")</nowiki>}}<br />
}}<br />
<br />
{{Tip|If some servers prevent you from downloading a file because of restricted user-agents, read [[Nonfree applications package guidelines#Custom DLAGENTS]].}}<br />
<br />
=== noextract ===<br />
<br />
An array of files listed under {{ic|source}}, which should not be extracted from their archive format by ''makepkg''. This can be used with archives that cannot be handled by {{ic|/usr/bin/bsdtar}} or those that need to be installed as-is. If an alternative unarchiving tool is used (e.g. {{Pkg|lrzip}}), it should be added in the {{ic|makedepends}} array and the first line of the [[Creating packages#prepare()|prepare()]] function should extract the source archive manually; for example:<br />
<br />
prepare() {<br />
lrzip -d ''source''.tar.lrz<br />
}<br />
<br />
Note that while the {{ic|source}} array accepts URLs, {{ic|noextract}} is '''just''' the file name portion:<br />
<br />
<nowiki>source=("http://foo.org/bar/foobar.tar.xz")</nowiki><br />
noextract=('foobar.tar.xz')<br />
<br />
To extract ''nothing'', you can do something like this:<br />
<br />
* If {{ic|source}} contains only plain URLs without custom file names, strip the source array before the last slash:<br />
: {{bc|1=noextract=("${source[@]##*/}")}}<br />
* If {{ic|source}} contains only entries with custom file names, strip the source array after the {{ic|::}} separator (taken from [https://projects.archlinux.org/svntogit/packages.git/tree/trunk/PKGBUILD?h=packages/firefox-i18n#n123 firefox-i18n's PKGBUILD]):<br />
: {{bc|1=noextract=("${source[@]%%::*}")}}<br />
<br />
=== validpgpkeys ===<br />
An array of PGP fingerprints. If used, ''makepkg'' will only accept signatures from the keys listed here and will ignore the trust values from the keyring. If the source file was signed with a subkey, ''makepkg'' will still use the primary key for comparison.<br />
<br />
Only full fingerprints are accepted. They must be uppercase and must not contain whitespace characters.<br />
<br />
{{note|You can use {{ic|gpg --list-keys --fingerprint <KEYID>}} to find out the fingerprint of the appropriate key.}}<br />
<br />
Please read [[Makepkg#Signature_checking]] for more information.<br />
<br />
== Integrity ==<br />
<br />
{{Note|Additional architecture-specific arrays can be added by appending an underscore and the architecture name, e.g. {{ic|1=md5sums_i686=()}}, {{ic|1=sha256sums_x86_64=()}}.<br />
}}<br />
<br />
These variables are arrays whose items are checksum strings that will be used to verify the integrity of the respective files in the [[#source|source]] array. You can also insert {{ic|SKIP}} for a particular file, and its checksum will not be tested.<br />
<br />
Checksums are intended to verify the ''integrity'' of the downloaded files, '''not''' their ''authenticity'': for this reason, even though the MD5 algorithm is known to have considerable [[Wikipedia:MD5#Security|vulnerabilities]] when used for other purposes, it is recommended for file integrity as a faster alternative to SHA-2 hashes, especially when large files are present in the {{ic|source}} array. If possible, however, always test the authenticity of the files by adding their signatures to the {{ic|source}} array: in this case you will also be able to safely skip their checksum verification altogether, as described above.<br />
<br />
The values for these variables can be auto-generated by [[makepkg]]'s {{ic|-g}}/{{ic|--geninteg}} option, then commonly appended with {{ic|makepkg -g >> PKGBUILD}}. The {{ic|updpkgsums}} command is able to update the variables wherever they are in the PKGBUILD. Both tools will use the variable that is already set in the PKGBUILD, or fall back to {{ic|md5sums}} if none is set.<br />
<br />
The file integrity checks to use can be set up with the {{ic|INTEGRITY_CHECK}} option in {{ic|/etc/makepkg.conf}}. See [https://www.archlinux.org/pacman/makepkg.conf.5.html makepkg.conf(5)].<br />
<br />
=== md5sums ===<br />
<br />
An array of 128-bit [[Wikipedia:MD5|MD5]] checksums of the files listed in the {{ic|source}} array.<br />
<br />
=== sha1sums ===<br />
<br />
An array of 160-bit [[Wikipedia:SHA-1|SHA-1]] checksums of the files listed in the {{ic|source}} array.<br />
<br />
=== sha256sums ===<br />
<br />
An array of [[Wikipedia:SHA-2|SHA-2]] checksums with digest size of 256 bits.<br />
<br />
=== sha224sums, sha384sums, sha512sums ===<br />
<br />
An array of SHA-2 checksums with digest sizes 224, 384, and 512 bits, respectively. These are less common alternatives to {{ic|sha256sums}}.<br />
<br />
== See also ==<br />
*[https://www.archlinux.org/pacman/PKGBUILD.5.html PKGBUILD(5) Manual Page]<br />
*[https://projects.archlinux.org/pacman.git/plain/proto/PKGBUILD.proto Example PKGBUILD file]</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Sudo&diff=461602Sudo2017-01-05T14:27:43Z<p>Fylwind: /* Configure sudo using drop-in files in /etc/sudoers.d */ editing /etc/sudoers.d files manually is just as dangerous as editing /etc/sudoers</p>
<hr />
<div>[[Category:Security]]<br />
[[fa:sudo]]<br />
[[cs:Sudo]]<br />
[[es:Sudo]]<br />
[[fr:Sudo]]<br />
[[it:Sudo]]<br />
[[ja:Sudo]]<br />
[[ru:Sudo]]<br />
[[sr:Sudo]]<br />
[[tr:Sudo]]<br />
[[uk:Sudo]]<br />
[[zh-CN:Sudo]]<br />
{{Related articles start}}<br />
{{Related|Users and groups}}<br />
{{Related|su}}<br />
{{Related articles end}}<br />
<br />
[https://www.sudo.ws/sudo/ sudo] allows a system administrator to delegate authority to give certain users—or groups of users—the ability to run commands as root or another user while providing an audit trail of the commands and their arguments.<br />
<br />
Sudo is an alternative to [[su]] for running commands as root. Unlike [[su]], which launches a root shell that allows all further commands root access, sudo instead grants temporary privilege escalation to a single command. By enabling root privileges only when needed, sudo usage reduces the likelihood that a typo or a bug in an invoked command will ruin the system.<br />
<br />
Sudo can also be used to run commands as other users; additionally, sudo logs all commands and failed access attempts for security auditing.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|sudo}} package.<br />
<br />
== Usage ==<br />
<br />
To begin using {{ic|sudo}} as a non-privileged user, it must be properly configured. See [[#Configuration]].<br />
<br />
To use ''sudo'', simply prefix a command and its arguments with {{ic|sudo}} and a space:<br />
<br />
$ sudo ''cmd''<br />
<br />
For example, to use pacman:<br />
<br />
$ sudo pacman -Syu<br />
<br />
See {{man|8|sudo|url=https://www.sudo.ws/man/sudo.man.html}} for more information.<br />
<br />
== Configuration ==<br />
<br />
{{Expansion|Move [[#Defaults skeleton]] here, and create an intro discussing {{ic|Defaults}}, perhaps with a table that lists common settings}}<br />
<br />
See {{man|5|sudoers|url=https://www.sudo.ws/man/sudoers.man.html}} for more information, such as configuring the password timeout.<br />
<br />
=== View current settings ===<br />
<br />
Run {{ic|sudo -ll}} to print out the current sudo configuration, or {{ic|sudo -lU ''user''}} for a specific user.<br />
<br />
=== Using visudo ===<br />
<br />
The configuration file for sudo is {{ic|/etc/sudoers}}. It should '''always''' be edited with the {{ic|visudo}} command. {{ic|visudo}} locks the {{ic|sudoers}} file, saves edits to a temporary file, and checks that file's grammar before copying it to {{ic|/etc/sudoers}}.<br />
<br />
{{Warning|<br />
* It is imperative that {{ic|sudoers}} be free of syntax errors! Any error makes sudo unusable. '''Always''' edit it with {{ic|visudo}} to prevent errors.<br />
* From {{man|8|visudo|url=https://www.sudo.ws/man/visudo.man.html}}: ''Note that this can be a security hole since it allows the user to execute any program they wish simply by setting VISUAL or EDITOR.''<br />
}}<br />
<br />
The default editor for visudo is {{ic|vi}}. sudo from the core repository is compiled with {{Ic|--with-env-editor}} by default and honors the use of the {{Ic|VISUAL}} and {{Ic|EDITOR}} variables. {{ic|EDITOR}} is not used when {{ic|VISUAL}} is set.<br />
<br />
To establish nano as the '''visudo''' editor for the duration of the current shell session, set and export the {{Ic|EDITOR}} variable before calling '''visudo'''.<br />
<br />
# EDITOR=nano visudo<br />
<br />
To change the editor permanently, see [[Environment variables#Per user]]. To change the editor of choice permanently system-wide only for {{ic|visudo}}, add the following to {{ic|/etc/sudoers}} (assuming {{ic|nano}} is your preferred editor):<br />
<br />
# Reset environment by default<br />
Defaults env_reset<br />
# Set default EDITOR to nano, and do not allow visudo to use EDITOR/VISUAL.<br />
Defaults editor=/usr/bin/nano, !env_editor<br />
<br />
=== Example Entries ===<br />
<br />
To allow a user to gain full root privileges when he/she precedes a command with {{ic|sudo}}, add the following line:<br />
<br />
USER_NAME ALL=(ALL) ALL<br />
<br />
To allow a user to run all commands as any user but only the machine with hostname {{ic|HOST_NAME}}:<br />
<br />
USER_NAME HOST_NAME=(ALL) ALL<br />
<br />
To allow members of group {{ic|wheel}} sudo access:<br />
<br />
%wheel ALL=(ALL) ALL<br />
<br />
To disable asking for a password for user {{ic|USER_NAME}}:<br />
<br />
Defaults:USER_NAME !authenticate<br />
<br />
Enable explicitly defined commands only for user {{ic|USER_NAME}} on host {{ic|HOST_NAME}}:<br />
<br />
USER_NAME HOST_NAME=/usr/bin/halt,/usr/bin/poweroff,/usr/bin/reboot,/usr/bin/pacman -Syu<br />
{{note| the most customized option should go at the end of the file, as the later lines overrides the previous ones. In particular such a line should be after the {{ic|%wheel}} line if your user is in this group.}}<br />
Enable explicitly defined commands only for user {{ic|USER_NAME}} on host {{ic|HOST_NAME}} without password:<br />
USER_NAME HOST_NAME= NOPASSWD: /usr/bin/halt,/usr/bin/poweroff,/usr/bin/reboot,/usr/bin/pacman -Syu<br />
<br />
A detailed {{ic|sudoers}} example is available at {{ic|/usr/share/doc/sudo/examples/sudoers}}. Otherwise, see the {{man|5|sudoers|url=https://www.sudo.ws/man/sudoers.man.html}} for detailed information.<br />
<br />
=== Sudoers default file permissions ===<br />
<br />
The owner and group for the {{ic|sudoers}} file must both be 0. The file permissions must be set to 0440. These permissions are set by default, but if you accidentally change them, they should be changed back immediately or sudo will fail.<br />
<br />
# chown -c root:root /etc/sudoers<br />
# chmod -c 0440 /etc/sudoers<br />
<br />
== Tips and tricks ==<br />
<br />
=== Disable per-terminal sudo ===<br />
<br />
{{Warning|This will let any process use your sudo session.}}<br />
<br />
If you are annoyed by sudo's defaults that require you to enter your password every time you open a new terminal, disable '''tty_tickets''':<br />
<br />
Defaults !tty_tickets<br />
<br />
=== Environment variables ===<br />
<br />
If you have a lot of environment variables, or you export your proxy settings via {{ic|1=export http_proxy="..."}}, when using sudo these variables do not get passed to the root account unless you run sudo with the {{ic|-E}} option.<br />
<br />
$ sudo -E pacman -Syu<br />
<br />
The recommended way of preserving environment variables is to append them to {{ic|env_keep}}:<br />
<br />
{{hc|/etc/sudoers|<nowiki><br />
Defaults env_keep += "ftp_proxy http_proxy https_proxy no_proxy"<br />
</nowiki>}}<br />
<br />
=== Passing aliases ===<br />
<br />
If you use a lot of aliases, you might have noticed that they do not carry over to the root account when using sudo. However, there is an easy way to make them work. Simply add the following to your {{ic|~/.bashrc}} or {{ic|/etc/bash.bashrc}}:<br />
<br />
alias sudo='sudo '<br />
<br />
=== Root password ===<br />
<br />
Users can configure sudo to ask for the root password instead of the user password by adding {{ic|targetpw}} (target user, defaults to root) or {{ic|rootpw}} to the Defaults line in {{ic|/etc/sudoers}}:<br />
Defaults targetpw<br />
<br />
To prevent exposing your root password to users, you can restrict this to a specific group:<br />
Defaults:%wheel targetpw<br />
%wheel ALL=(ALL) ALL<br />
<br />
=== Disable root login ===<br />
<br />
Users may wish to disable the root login. Without root, attackers must first guess a user name configured as a sudoer as well as the user password. See for example [[Ssh#Deny]].<br />
<br />
{{Warning|<br />
* Be careful, you may lock yourself out by disabling root login. Sudo is not automatically installed and its default configuration allows neither passwordless root access nor root access with your own password. Ensure a user is properly configured as a sudoer ''before'' disabling the root account!<br />
* If you have changed your sudoers -file to use rootpw as default, then do not disable root login with any of the following commands!<br />
* If you are already locked out, see [[Password recovery]] for help.}}<br />
<br />
The account can be locked via {{ic|passwd}}:<br />
<br />
# passwd -l root<br />
<br />
A similar command unlocks root.<br />
<br />
$ sudo passwd -u root<br />
<br />
Alternatively, edit {{ic|/etc/shadow}} and replace the root's encrypted password with "!":<br />
<br />
root:!:12345::::::<br />
<br />
To enable root login again:<br />
<br />
$ sudo passwd root<br />
<br />
==== gksu ====<br />
<br />
To set ''gksu'' to use sudo by default, run:<br />
<br />
$ gconftool-2 --set --type boolean /apps/gksu/sudo-mode true<br />
<br />
==== kdesu ====<br />
<br />
kdesu may be used under KDE to launch GUI applications with root privileges. It is possible that by default kdesu will try to use su even if the root account is disabled. Fortunately one can tell kdesu to use sudo instead of su. Create/edit the file {{ic|~/.config/kdesurc}} (or {{ic|~/.kde4/share/config/kdesurc}} for the kde4 version of kdesu):<br />
<br />
[super-user-command]<br />
super-user-command=sudo<br />
<br />
or use the following command (use ''kwriteconfig'' for the kde4 version of kdesu):<br />
<br />
$ kwriteconfig5 --file kdesurc --group super-user-command --key super-user-command sudo<br />
<br />
Alternatively, install {{AUR|kdesudo}}, which has the added advantage of tab-completion for the command following.<br />
<br />
=== Harden with Sudo Example ===<br />
<br />
Let us say you create 3 users: admin, devel, and joe. The user "admin" is used for journalctl, systemctl, mount, kill, and iptables; "devel" is used for installing packages, and editing config files; and "joe" is the user you log in with. To let "joe" reboot, shutdown, and use netctl we would do the following:<br />
<br />
Edit /etc/pam.d/su and /etc/pam.d/su-1<br />
Require user be in the wheel group, but do not put anyone in it.<br />
#%PAM-1.0<br />
auth sufficient pam_rootok.so<br />
# Uncomment the following line to implicitly trust users in the "wheel" group.<br />
#auth sufficient pam_wheel.so trust use_uid<br />
# Uncomment the following line to require a user to be in the "wheel" group.<br />
auth required pam_wheel.so use_uid<br />
auth required pam_unix.so<br />
account required pam_unix.so<br />
session required pam_unix.so<br />
<br />
Limit SSH login to the 'ssh' group. Only "joe" will be part of this group.<br />
groupadd -r ssh<br />
gpasswd -a joe ssh<br />
echo 'AllowGroups ssh' >> /etc/ssh/sshd_config<br />
<br />
[[Restart]] {{ic|sshd.service}}.<br />
<br />
Add users to other groups.<br />
for g in power network ;do ;gpasswd -a joe $g ;done<br />
for g in network power storage ;do ;gpasswd -a admin $g ;done<br />
<br />
Set permissions on configs so devel can edit them.<br />
chown -R devel:root /etc/{http,openvpn,cups,zsh,vim,screenrc}<br />
<br />
Cmnd_Alias POWER = /usr/bin/shutdown -h now, /usr/bin/halt, /usr/bin/poweroff, /usr/bin/reboot<br />
Cmnd_Alias STORAGE = /usr/bin/mount -o nosuid\,nodev\,noexec, /usr/bin/umount<br />
Cmnd_Alias SYSTEMD = /usr/bin/journalctl, /usr/bin/systemctl<br />
Cmnd_Alias KILL = /usr/bin/kill, /usr/bin/killall<br />
Cmnd_Alias PKGMAN = /usr/bin/pacman<br />
Cmnd_Alias NETWORK = /usr/bin/netctl<br />
Cmnd_Alias FIREWALL = /usr/bin/iptables, /usr/bin/ip6tables<br />
Cmnd_Alias SHELL = /usr/bin/zsh, /usr/bin/bash<br />
%power ALL = (root) NOPASSWD: POWER<br />
%network ALL = (root) NETWORK<br />
%storage ALL = (root) STORAGE<br />
root ALL = (ALL) ALL<br />
admin ALL = (root) SYSTEMD, KILL, FIREWALL<br />
devel ALL = (root) PKGMAN<br />
Joe ALL = (devel) SHELL, (admin) SHELL <br />
<br />
With this setup, you will almost never need to login as the Root user.<br />
<br />
"Joe" can connect to his home WiFi.<br />
sudo netctl start home<br />
sudo poweroff<br />
<br />
"Joe" can not use netctl as any other user.<br />
sudo -u admin -- netctl start home<br />
<br />
When "joe" needs to use journalctl or kill run away process he can switch to that user<br />
sudo -i -u devel<br />
sudo -i -u admin<br />
<br />
But "joe" cannot switch to the root user.<br />
sudo -i -u root<br />
<br />
If "joe" want to start a gnu-screen session as admin he can do it like this:<br />
sudo -i -u admin<br />
admin% chown admin:tty `echo $TTY`<br />
admin% screen<br />
<br />
=== Configure sudo using drop-in files in /etc/sudoers.d ===<br />
<br />
''sudo'' parses files contained in the directory {{ic|/etc/sudoers.d/}}. This means that instead of editing {{ic|/etc/sudoers}}, you can change settings in standalone files and drop them in that directory. This has two advantages:<br />
<br />
* There is no need to edit a {{ic|sudoers.pacnew}} file;<br />
* If there is a problem with a new entry, you can remove the offending file instead of editing {{ic|/etc/sudoers}} (but see the warning below).<br />
<br />
The format for entries in these drop-in files is the same as for {{ic|/etc/sudoers}} itself. To edit them directly, use {{ic|visudo -f /etc/sudoers.d/''somefile''}}. See the "Including other files from within sudoers" section of {{man|5|sudoers|url=https://www.sudo.ws/man/sudoers.man.html}} for details.<br />
<br />
The files in {{ic|/etc/sudoers.d/}} directory are parsed in lexicographical order, file names containing {{ic|.}} or {{ic|~}} are skipped. To avoid sorting problems, the file names should begin with two digits, e.g. {{ic|01_foo}}.<br />
<br />
{{Note|The order of entries in the drop-in files is important: make sure that the statements do not override themselves.}}<br />
<br />
{{Warning|The files in {{ic|/etc/sudoers.d/}} are just as fragile as {{ic|/etc/sudoers}} itself: any improperly formatted file will prevent {{ic|sudo}} from working. Hence, for the same reason it is strongly advised to use {{ic|visudo}}}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== SSH TTY Problems ===<br />
<br />
{{Merge|#Configuration}}<br />
<br />
SSH does not allocate a tty by default when running a remote command. Without a tty, sudo cannot disable echo when prompting for a password. You can use ssh's {{ic|-tt}} option to force it to allocate a tty (or {{ic|-t}} twice).<br />
<br />
The {{ic|Defaults}} option {{ic|requiretty}} only allows the user to run sudo if they have a tty.<br />
<br />
# Disable "ssh hostname sudo <cmd>", because it will show the password in clear text. You have to run "ssh -t hostname sudo <cmd>".<br />
#<br />
#Defaults requiretty<br />
<br />
=== Permissive umask ===<br />
<br />
{{Merge|#Configuration}}<br />
<br />
Sudo will union the user's [[umask]] value with its own umask (which defaults to 0022). This prevents sudo from creating files with more open permissions than the user's umask allows. While this is a sane default if no custom umask is in use, this can lead to situations where a utility run by sudo may create files with different permissions than if run by root directly. If errors arise from this, sudo provides a means to fix the umask, even if the desired umask is more permissive than the umask that the user has specified. Adding this (using {{ic|visudo}}) will override sudo's default behavior:<br />
<br />
Defaults umask = 0022<br />
Defaults umask_override<br />
<br />
This sets sudo's umask to root's default umask (0022) and overrides the default behavior, always using the indicated umask regardless of what umask the user as set.<br />
<br />
=== Defaults skeleton ===<br />
<br />
{{Merge|#Configuration}}<br />
<br />
The authors site has a [http://www.sudo.ws/sudo/sudoers.man.html#x5355444f455253204f5054494f4e53 list of all the options] that can be used with the {{ic|Defaults}} command in the {{ic|/etc/sudoers}} file.<br />
<br />
See [https://gist.github.com/AladW/7eca9799b9ea624eca31] for a list of options (parsed from the version 1.8.7 source code) in a format optimized for {{ic|sudoers}}.</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Systemd/User&diff=456100Systemd/User2016-11-05T20:50:27Z<p>Fylwind: /* Reading the journal */</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Daemons and system services]]<br />
[[Category:Boot process]]<br />
[[es:Systemd/User]]<br />
[[fr:Systemd/utilisateur]]<br />
[[it:Systemd/User]]<br />
[[ja:Systemd/ユーザー]]<br />
[[ru:Systemd/User]]<br />
[[zh-CN:Systemd/User]]<br />
{{Related articles start}}<br />
{{Related|systemd}}<br />
{{Related|Automatic login to virtual console}}<br />
{{Related|Start X at login}}<br />
{{Related articles end}}<br />
<br />
[[systemd]] offers users the ability to manage services under the user's control with a per-user systemd instance, enabling users to start, stop, enable, and disable their own units. This is convenient for daemons and other services that are commonly run for a single user, such as [[mpd]], or to perform automated tasks like fetching mail. With some caveats it is even possible to run xorg and the entire window manager from user services.<br />
<br />
== How it works ==<br />
<br />
As per default configuration in {{ic|/etc/pam.d/system-login}}, the {{ic|pam_systemd}} module automatically launches a {{ic|systemd --user}} instance when the user logs in for the first time. This process will survive as long as there is some session for that user, and will be killed as soon as the last session for the user is closed. When [[#Automatic start-up of systemd user instances]] is enabled, the instance is started on boot and will not be killed. The systemd user instance is responsible for managing user services, which can be used to run daemons or automated tasks, with all the benefits of systemd, such as socket activation, timers, dependency system or strict process control via cgroups.<br />
<br />
Similarly to system units, user units are located in the following directories (ordered by ascending precedence):<br />
<br />
* {{ic|/usr/lib/systemd/user/}} where units provided by installed packages belong.<br />
* {{ic|~/.local/share/systemd/user/}} where units of packages that have been installed in the home directory belong.<br />
* {{ic|/etc/systemd/user/}} where system-wide user units are placed by the system administrator.<br />
* {{ic|~/.config/systemd/user/}} where the user puts its own units.<br />
<br />
When systemd user instance starts, it brings up the target {{ic|default.target}}. Other units can be controlled manually with {{ic|systemctl --user}}.<br />
<br />
{{Note|<br />
* Be aware that the {{ic|systemd --user}} instance is a per-user process, and not per-session. The rationale is that most resources handled by user services, like sockets or state files will be per-user (live on the user's home dir) and not per session. This means that all user services run outside of a session. As a consequence, programs that need to be run inside a session will probably break in user services. The way systemd handles user sessions is pretty much in flux. See [https://mail.gnome.org/archives/desktop-devel-list/2014-January/msg00079.html] and [http://lists.freedesktop.org/archives/systemd-devel/2014-March/017552.html] for some hints on where things are going.<br />
* {{ic|systemd --user}} runs as a separate process from the {{ic|systemd --system}} process. User units can not reference or depend on system units.<br />
}}<br />
<br />
== Basic setup ==<br />
<br />
All the user services will be placed in {{ic|~/.config/systemd/user/}}. If you want to run services on first login, execute {{ic|systemctl --user enable ''service''}} for any service you want to be autostarted.<br />
<br />
=== D-Bus ===<br />
<br />
Some programs will need a [[D-Bus]] user message bus, and systemd is the manager of the user message bus.[https://www.archlinux.org/news/d-bus-now-launches-user-buses/] The ''dbus-daemon'' is started once per user for all sessions with the provided {{ic|dbus.socket}} and {{ic|dbus.service}} user units.<br />
<br />
{{Note|If you had previously created these units manually under {{ic|/etc/systemd/user/}} or {{ic|~/.config/systemd/user/}}, they can be removed.}}<br />
<br />
=== Environment variables ===<br />
<br />
The user instance of systemd does not inherit any of the [[environment variables]] set in places like {{ic|.bashrc}} etc. There are several ways to set environment variables for the systemd user instance:<br />
<br />
# For users with a {{ic|$HOME}} directory, use the {{ic|DefaultEnvironment}} option in {{ic|~/.config/systemd/user.conf}}. Affects only that user's user unit.<br />
# Use the {{ic|DefaultEnvironment}} option in {{ic|/etc/systemd/user.conf}} file. Affects all user units.<br />
# Add a drop-in config file in {{ic|/etc/systemd/system/user@.service.d/}}. Affects all user units; see [[#Service example]]<br />
# At any time, use {{ic|systemctl --user set-environment}} or {{ic|systemctl --user import-environment}}. Affects all user units started after setting the environment variables, but not the units that were already running.<br />
# Using the {{ic|dbus-update-activation-environment --systemd --all}} command provided by [[dbus]]. Has the same effect as {{ic|systemctl --user import-environment}}, but also affects the D-Bus session. You can add this to the end of your shell initialization file.<br />
<br />
One variable you may want to set is {{ic|PATH}}.<br />
<br />
==== Service example ====<br />
Create the [[Systemd#Drop-in files|drop-in]] directory {{ic|/etc/systemd/system/user@.service.d/}} and inside create a file that has the extension {{ic|.conf}} (e.g. {{ic|local.conf}}):<br />
{{hc|/etc/systemd/system/user@.service.d/local.conf|2=<br />
[Service]<br />
Environment="PATH=/usr/lib/ccache/bin/:$PATH"<br />
Environment="EDITOR=nano -c"<br />
Environment="BROWSER=firefox"<br />
Environment="NO_AT_BRIDGE=1"<br />
}}<br />
<br />
==== DISPLAY and XAUTHORITY ====<br />
<br />
{{ic|DISPLAY}} is used by any X application to know which display to use and {{ic|XAUTHORITY}} to provide a path to the user's {{ic|.Xauthority}} file and thus the cookie needed to access the X server. If you plan on launching X applications from systemd units, these variables need to be set. Systemd provides a script in {{ic|/etc/X11/xinit/xinitrc.d/50-systemd-user.sh}} to import those variables into the systemd user session on X launch. [https://github.com/systemd/systemd/blob/v219/NEWS#L194] So unless you start X in a nonstandard way, user services should be aware of the {{ic|DISPLAY}} and {{ic|XAUTHORITY}}.<br />
<br />
==== PATH ====<br />
<br />
If you customize your {{ic|PATH}} and plan on launching applications that make use of it from systemd units, you should make sure the modified {{ic|PATH}} is set on the systemd environment. Assuming you set your {{ic|PATH}} in {{ic|.bash_profile}}, the best way to make systemd aware of your modified {{ic|PATH}} is by adding the following to {{ic|.bash_profile}} after the {{ic|PATH}} variable is set:<br />
<br />
{{hc|~/.bash_profile|<nowiki><br />
systemctl --user import-environment PATH<br />
</nowiki>}}<br />
<br />
=== Automatic start-up of systemd user instances ===<br />
<br />
The systemd user instance is started after the first login of a user and killed after the last session of the user is closed. Sometimes it may be useful to start it right after boot, and keep the systemd user instance running after the last session closes, for instance to have some user process running without any open session. Lingering is used to that effect. Use the following command to enable lingering for specific user:<br />
<br />
# loginctl enable-linger ''username''<br />
<br />
{{Warning|systemd services are '''not''' sessions, they run outside of ''logind''. Do not use lingering to enable automatic login as it will [[General troubleshooting#Session permissions|break the session]].}}<br />
<br />
== Xorg and systemd ==<br />
<br />
There are several ways to run xorg within systemd units. Below there are two options, either by starting a new user session with an xorg process, or by launching xorg from a systemd user service.<br />
<br />
=== Automatic login into Xorg without display manager ===<br />
<br />
{{Accuracy|This setup ends up with two user D-Bus buses, one for the desktop, and an other for systemd. Why can't we use the systemd one alone? }}<br />
<br />
This option will launch a system unit that will start a user session with an xorg server and then run the usual {{ic|~/.xinitrc}} to launch the window manager, etc.<br />
<br />
You need to have [[#D-Bus]] correctly set up and {{AUR|xlogin-git}} installed.<br />
<br />
Set up your [[xinitrc]] from the skeleton, so that it will source the files in {{ic|/etc/X11/xinit/xinitrc.d/}}. Running your {{ic|~/.xinitrc}} should not return, so either have {{ic|wait}} as the last command, or add {{ic|exec}} to the last command that will be called and which should not return (your window manager, for instance).<br />
<br />
The session will use its own dbus daemon, but various systemd utilities will automatically connect to the {{ic|dbus.service}} instance.<br />
<br />
Finally, enable ('''as root''') the ''xlogin'' service for automatic login at boot:<br />
<br />
# systemctl enable xlogin@''username''<br />
<br />
The user session lives entirely inside a systemd scope and everything in the user session should work just fine.<br />
<br />
=== Xorg as a systemd user service ===<br />
<br />
Alternatively, [[xorg]] can be run from within a systemd user service. This is nice since other X-related units can be made to depend on xorg, etc, but on the other hand, it has some drawbacks explained below.<br />
<br />
{{Pkg|xorg-server}} provides integration with systemd in two ways:<br />
* Can be run unprivileged, delegating device management to logind (see Hans de Goede commits around [http://cgit.freedesktop.org/xorg/xserver/commit/?id=82863656ec449644cd34a86388ba40f36cea11e9 this commit]).<br />
* Can be made into a socket activated service (see [http://cgit.freedesktop.org/xorg/xserver/commit/?id=b3d3ffd19937827bcbdb833a628f9b1814a6e189 this commit]). This removes the need for {{AUR|systemd-xorg-launch-helper-git}}.<br />
<br />
Unfortunately, to be able to run xorg in unprivileged mode, it needs to run inside a session. So, right now the handicap of running xorg as user service is that it must be run with root privileges (like before 1.16), and can't take advantage of the unprivileged mode introduced in 1.16.<br />
<br />
{{Note|This is not a fundamental restriction imposed by logind, but the reason seems to be that xorg needs to know which session to take over, and right now it gets this information calling [http://www.freedesktop.org/wiki/Software/systemd/logind logind]'s {{ic|GetSessionByPID}} using its own pid as argument. See [http://lists.x.org/archives/xorg-devel/2014-February/040476.html this thread] and [http://cgit.freedesktop.org/xorg/xserver/tree/hw/xfree86/os-support/linux/systemd-logind.c xorg sources]. It seems likely that xorg could be modified to get the session from the tty it is attaching to, and then it could run unprivileged from a user service outside a session.}}<br />
<br />
{{Warning|1=On xorg 1.18 socket activation seems to be broken. The client triggering the activation deadlocks. See the upstream bug report [https://bugs.freedesktop.org/show_bug.cgi?id=93072]. As a temporary workaround you can start the xorg server without socket activation, making sure the clients connect after a delay, so the server is fully started. There seems to be no nice mechanism te get startup notification for the X server.}}<br />
<br />
This is how to launch xorg from a user service:<br />
<br />
1. Make xorg run with root privileges and for any user, by editing {{ic|/etc/X11/Xwrapper.config}} <br />
<br />
{{hc|/etc/X11/Xwrapper.config|<nowiki><br />
allowed_users=anybody<br />
needs_root_rights=yes<br />
</nowiki>}}<br />
<br />
2. Add the following units to {{ic|~/.config/systemd/user}}<br />
<br />
{{hc|~/.config/systemd/user/xorg@.socket|<nowiki><br />
[Unit]<br />
Description=Socket for xorg at display %i<br />
<br />
[Socket]<br />
ListenStream=/tmp/.X11-unix/X%i<br />
</nowiki>}}<br />
<br />
{{hc|~/.config/systemd/user/xorg@.service|<nowiki><br />
[Unit]<br />
Description=Xorg server at display %i<br />
<br />
Requires=xorg@%i.socket<br />
After=xorg@%i.socket<br />
<br />
[Service]<br />
Type=simple<br />
SuccessExitStatus=0 1<br />
<br />
ExecStart=/usr/bin/Xorg :%i -nolisten tcp -noreset -verbose 2 "vt${XDG_VTNR}"<br />
</nowiki>}}<br />
<br />
where {{ic|${XDG_VTNR} }} is the virtual terminal where xorg will be launched, either hard-coded in the service unit, or set in the systemd environment with<br />
<br />
$ systemctl --user set-environment XDG_VTNR=1<br />
<br />
{{Note|xorg should be launched at the same virtual terminal where the user logged in. Otherwise logind will consider the session inactive.}}<br />
<br />
3. Make sure to configure the {{ic|DISPLAY}} environment variable as explained [[#DISPLAY_and_XAUTHORITY|above]].<br />
<br />
4. Then, to enable socket activation for xorg on display 0 and tty 2 one would do:<br />
<br />
$ systemctl --user set-environment XDG_VTNR=2 # So that xorg@.service knows which vt use<br />
$ systemctl --user start xorg@0.socket # Start listening on the socket for display 0<br />
<br />
Now running any X application will launch xorg on virtual terminal 2 automatically.<br />
<br />
The environment variable {{ic|XDG_VTNR}} can be set in the systemd environment from {{ic|.bash_profile}}, and then one could start any X application, including a window manager, as a systemd unit that depends on {{ic|xorg@0.socket}}.<br />
<br />
{{Warning|Currently running a window manager as a user service means it runs outside of a session with the problems this may bring: [[General troubleshooting#Session permissions|break the session]]. However, it seems that systemd developers intend to make something like this possible. See [https://mail.gnome.org/archives/desktop-devel-list/2014-January/msg00079.html] and [http://lists.freedesktop.org/archives/systemd-devel/2014-March/017552.html]}}<br />
<br />
== Writing user units ==<br />
<br />
=== Example ===<br />
<br />
The following is an example of a user version of the mpd service.<br />
{{hc|~/.config/systemd/user/mpd.service|<nowiki><br />
[Unit]<br />
Description=Music Player Daemon<br />
<br />
[Service]<br />
ExecStart=/usr/bin/mpd --no-daemon<br />
<br />
[Install]<br />
WantedBy=default.target<br />
</nowiki>}}<br />
<br />
=== Example with variables ===<br />
<br />
The following is an example of a user version of {{ic|sickbeard.service}}, which takes into account variable home directories where SickBeard can find certain files:<br />
<br />
{{hc|~/.config/systemd/user/sickbeard.service|<nowiki><br />
[Unit]<br />
Description=SickBeard Daemon<br />
<br />
[Service]<br />
ExecStart=/usr/bin/env python2 /opt/sickbeard/SickBeard.py --config %h/.sickbeard/config.ini --datadir %h/.sickbeard<br />
<br />
[Install]<br />
WantedBy=default.target<br />
</nowiki>}}<br />
<br />
As detailed in {{ic|man systemd.unit}}, the {{ic|%h}} variable is replaced by the home directory of the user running the service. There are other variables that can be taken into account in the [[systemd]] manpages.<br />
<br />
=== Note about X applications ===<br />
<br />
Most X apps need a {{ic|DISPLAY}} variable to run. See [[#DISPLAY and XAUTHORITY]] for how to this variable is set for the entire systemd user instance.<br />
<br />
=== Reading the journal ===<br />
<br />
The journal for the user can be read using the analogous command:<br />
<br />
$ journalctl --user<br />
<br />
To specify a unit, one can use<br />
<br />
$ journalctl --user -u myunit.service<br />
<br />
Note that there seems to be some sort of bug that can sometimes output from user services from being properly attributed to their service unit. Therefore, filtering by the {{ic|-u}} may unwittingly exclude some of the output from the service units.<br />
<br />
== Some use cases ==<br />
<br />
=== Persistent terminal multiplexer ===<br />
<br />
{{Out of date|References {{ic|user-session@.service}} instead of {{ic|user@.service}}; the latter does not contain {{ic|1=Conflicts=getty@tty1.service}}.}}<br />
<br />
You may wish your user session to default to running a terminal multiplexer, such as [[GNU Screen]] or [[Tmux]], in the background rather than logging you into a window manager session. Separating login from X login is most likely only useful for those who boot to a TTY instead of to a display manager (in which case you can simply bundle everything you start in with myStuff.target). <br />
<br />
To create this type of user session, procede as above, but instead of creating wm.target, create multiplexer.target:<br />
<br />
{{bc|1=<br />
[Unit]<br />
Description=Terminal multiplexer<br />
Documentation=info:screen man:screen(1) man:tmux(1)<br />
After=cruft.target<br />
Wants=cruft.target<br />
<br />
[Install]<br />
Alias=default.target<br />
}}<br />
<br />
{{ic|cruft.target}}, like {{ic|mystuff.target}} above, should start anything you think should run before tmux or screen starts (or which you want started at boot regardless of timing), such as a GnuPG daemon session.<br />
<br />
You then need to create a service for your multiplexer session. Here is a sample service, using tmux as an example and sourcing a gpg-agent session which wrote its information to {{ic|/tmp/gpg-agent-info}}. This sample session, when you start X, will also be able to run X programs, since DISPLAY is set.<br />
<br />
{{bc|1=<br />
[Unit]<br />
Description=tmux: A terminal multiplixer <br />
Documentation=man:tmux(1)<br />
After=gpg-agent.service<br />
Wants=gpg-agent.service<br />
<br />
[Service]<br />
Type=forking<br />
ExecStart=/usr/bin/tmux start<br />
ExecStop=/usr/bin/tmux kill-server<br />
Environment=DISPLAY=:0<br />
EnvironmentFile=/tmp/gpg-agent-info<br />
<br />
[Install]<br />
WantedBy=multiplexer.target<br />
}}<br />
<br />
Once this is done, {{ic|systemctl --user enable}} {{ic|tmux.service}}, {{ic|multiplexer.target}} and any services you created to be run by {{ic|cruft.target}} and you should be set to go! Activated {{ic|user-session@.service}} as described above, but be sure to remove the {{ic|1=Conflicts=getty@tty1.service}} from {{ic|user-session@.service}}, since your user session will not be taking over a TTY. Congratulations! You have a running terminal multiplexer and some other useful programs ready to start at boot!<br />
<br />
=== Window manager ===<br />
<br />
To run a window manager as a systemd service, you first need to run [[#Xorg as a systemd user service]]. In the following we will use awesome as an example:<br />
<br />
{{hc|~/.config/systemd/user/awesome.service|<nowiki><br />
[Unit]<br />
Description=Awesome window manager<br />
After=xorg.target<br />
Requires=xorg.target<br />
<br />
[Service]<br />
ExecStart=/usr/bin/awesome<br />
Restart=always<br />
RestartSec=10<br />
<br />
[Install]<br />
WantedBy=wm.target<br />
</nowiki>}}<br />
<br />
{{Note|The {{ic|[Install]}} section includes a {{ic|WantedBy}} part. When using {{ic|systemctl --user enable}} it will link this as {{ic|~/.config/systemd/user/wm.target.wants/''window_manager''.service}}, allowing it to be started at login. Is recommended to enable this service, not to link it manually.}}<br />
<br />
== Kill user processes on logout ==<br />
<br />
Arch Linux builds the {{pkg|systemd}} package with {{ic|--without-kill-user-processes}}, setting {{ic|1=KillUserProcesses}} to {{ic|no}} by default. This setting causes user processes not to be killed when the user completely logs out. To change this behavior in order to have all user processes killed on the user's logout, set {{ic|1=KillUserProcesses=yes}} in {{ic|/etc/systemd/logind.conf}}. <br />
<br />
Note that changing this setting breaks terminal multiplexers such as [[tmux]] and [[screen]]. If you change this setting, you can still use a terminal multiplexer by using {{ic|systemd-run}} as follows:<br />
<br />
$ systemd-run --scope --user ''command'' ''args''<br />
<br />
For example, to run {{ic|screen}} you would do:<br />
<br />
$ systemd-run --scope --user screen -S ''foo''<br />
<br />
== See also ==<br />
* [https://bitbucket.org/KaiSforza/systemd-user-units/wiki/Home KaiSforza's Bitbucket wiki]<br />
* [https://github.com/zoqaeski/systemd-user-units Zoqaeski's units on GitHub]<br />
* [https://bbs.archlinux.org/viewtopic.php?id=167115 Arch forum thread about changes in systemd 206 user instances]</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Partitioning&diff=453219Partitioning2016-10-07T18:11:09Z<p>Fylwind: /* Partition scheme */ Rephrase it to make it more obvious what is needed for BIOS+GPT+GRUB</p>
<hr />
<div>[[Category:File systems]]<br />
[[Category:Boot process]]<br />
[[Category:System recovery]]<br />
[[ar:Partitioning]]<br />
[[es:Partitioning]]<br />
[[hu:Partitioning]]<br />
[[it:Partitioning]]<br />
[[ja:パーティショニング]]<br />
[[pl:Partitioning]]<br />
[[ru:Partitioning]]<br />
[[zh-CN:Partitioning]]<br />
{{Related articles start}}<br />
{{Related|File systems}}<br />
{{Related|fdisk}}<br />
{{Related|parted}}<br />
{{Related|fstab}}<br />
{{Related|LVM}}<br />
{{Related|Swap}}<br />
{{Related|Arch boot process}}<br />
{{Related|Unified Extensible Firmware Interface}}<br />
{{Related articles end}}<br />
[[w:Disk partitioning|Partitioning]] a hard drive divides the available space into sections that can be accessed independently. An entire drive may be allocated to a single partition, or multiple ones for cases such as dual-booting, maintaining a [[swap]] partition, or to logically separate data such as audio and video files. <br />
<br />
The required information is stored in a [[#Partition table]] scheme such as MBR or GPT.<br />
<br />
Tables are modified using a [[#Partitioning tool]] which must be compatible to the chosen scheme of partitioning table. Available tools include [[fdisk]] and [[parted]].<br />
<br />
Once created, a partition must be formatted with an appropriate [[file system]] (''swap'' excepted) before data can be written to the newly-formatted file system volume.<br />
<br />
== Partition table ==<br />
<br />
{{Note|To print/list existing tables (of a specific device), run {{ic|parted ''/dev/sda'' print}} or {{ic|fdisk -l ''/dev/sda''}}, where {{ic|''/dev/sda''}} is a device name.}}<br />
<br />
=== Choosing between GPT and MBR ===<br />
<br />
GUID Partition Table (GPT) is an alternative, contemporary, partitioning style; it is intended to replace the old Master Boot Record (MBR) system. GPT has several advantages over MBR which has quirks dating back to MS-DOS times. With the recent developments to the formatting tools ''fdisk'' (MBR) and ''gdisk'' (GPT), it is equally easy to get good dependability and performance for GPT or MBR. <br />
<br />
Some points to consider when choosing: <br />
<br />
* To dual-boot with Windows (both 32-bit and 64-bit) using Legacy BIOS, the MBR scheme is required.<br />
* To dual-boot Windows 64-bit using [[UEFI]] mode instead of BIOS, the GPT scheme is required.<br />
* If you are installing on older hardware, especially on old laptops, consider choosing MBR because its BIOS might not support GPT.<br />
* If you are partitioning a disk of 2 TiB or larger, you need to use GPT.<br />
* It is recommended to always use GPT for [[UEFI]] boot, as some UEFI implementations do not support booting to the MBR while in UEFI mode.<br />
* If none of the above apply, choose freely between GPT and MBR. Since GPT is more modern, it is recommended in this case.<br />
<br />
{{Note|For GRUB to boot from a GPT-partitioned disk on a BIOS-based system, a [[GRUB#GUID_Partition_Table_.28GPT.29_specific_instructions|BIOS boot partition]] is required. Please note that this partition is unrelated to the {{ic|/boot}} mountpoint, and will be used by GRUB directly. Do not create a filesystem on it, and do not mount it.}}<br />
<br />
=== Master Boot Record ===<br />
<br />
The [[Wikipedia:Master boot record|Master Boot Record]] (MBR) is the first 512 bytes of a storage device. It contains an operating system bootloader and the storage device's partition table. It plays an important role in the [[boot process]] under [[wikipedia:BIOS|BIOS]] systems. See [[Wikipedia:Master boot record#Disk partitioning]] for the MBR structure.<br />
<br />
{{Note|The MBR is not located in a partition; it is located at the first sector of the device (physical offset 0), preceding the first partition. (The boot sector present on a partitionless device or within an individual partition is called a [[w:Volume boot record|Volume boot record]] instead.)}}<br />
<br />
==== Master Boot Record (partition table) ====<br />
<br />
There are 3 types of partitions in the MBR scheme:<br />
<br />
* Primary<br />
* Extended<br />
** Logical<br />
<br />
'''Primary''' partitions can be bootable and are limited to four partitions per disk or RAID volume. If the MBR partition table requires more than four partitions, then one of the primary partitions needs to be replaced by an '''extended''' partition containing '''logical''' partitions within it. <br />
<br />
Extended partitions can be thought of as containers for logical partitions. A hard disk can contain no more than one extended partition. The extended partition is also counted as a primary partition so if the disk has an extended partition, only three additional primary partitions are possible (i.e. three primary partitions and one extended partition). The number of logical partitions residing in an extended partition is unlimited. A system that dual boots with Windows will require for Windows to reside in a primary partition.<br />
<br />
The customary numbering scheme is to create primary partitions ''sda1'' through ''sda3'' followed by an extended partition ''sda4''. The logical partitions on ''sda4'' are numbered ''sda5'', ''sda6'', etc.<br />
<br />
==== Master Boot Record (bootstrap code) ====<br />
<br />
The first 446 bytes of MBR are '''bootstrap code area'''. On BIOS systems it usually contains the first stage of the boot loader.<br />
<br />
=== GUID Partition Table ===<br />
<br />
[[Wikipedia:GUID Partition Table|GUID Partition Table]] (GPT) is a partitioning scheme that is part of the [[Unified Extensible Firmware Interface]] specification; it uses [[Wikipedia:Globally unique identifier|globally unique identifiers]] (GUIDs), or UUIDs in linux world, to define partitions and [[Wikipedia:GUID Partition Table#Partition type GUIDs|partition types]]. It is designed to succeed the [[#Master Boot Record]] partitioning scheme method.<br />
<br />
==== Advantages of GPT ====<br />
<br />
{{Merge|Partitioning#Choosing between GPT and MBR|Keep advantages/disadvantages in one place.}}<br />
<br />
* Provides a unique disk GUID and unique [[Persistent block device naming#by-partuuid|partition GUID]] ({{ic|PARTUUID}}) for each partition - A good filesystem-independent way of referencing partitions and disks.<br />
* Provides a filesystem-independent [[Persistent block device naming#by-partlabel|partition name]] ({{ic|PARTLABEL}}).<br />
* Arbitrary number of partitions - depends on space allocated for the partition table - No need for extended and logical partitions. By default the GPT table contains space for defining 128 partitions. However if you want to define more partitions, you can allocate more space to the partition table (currently only ''gdisk'' is known to support this feature).<br />
* Uses 64-bit LBA for storing Sector numbers - maximum addressable disk size is 2 ZiB. MBR is limited to addressing 2 TiB of space per drive.<br />
* Stores a backup header and partition table at the end of the disk that aids in [[fdisk#Recover GPT header|recovery]] in case the primary ones are damaged.<br />
* CRC32 checksums to detect errors and corruption of the header and partition table.<br />
<br />
==== Kernel Support ====<br />
<br />
The {{ic|CONFIG_EFI_PARTITION}} option in the kernel config enables GPT support in the kernel (despite the name, EFI PARTITION). This option must be built in the kernel and not compiled as a loadable module. This option is required even if GPT disks are used only for data storage and not for booting. This option is enabled by default in Arch's {{Pkg|linux}} and {{Pkg|linux-lts}} kernels in the [core] repo. In case of a custom kernel, enable this option by doing {{ic|1=CONFIG_EFI_PARTITION=y}}.<br />
<br />
=== Partitionless disk ===<br />
<br />
Partitionless disk (a.k.a. superfloppy) refers to using a storage device without using a partition table, having one file system volume occupying the whole storage device.<br />
<br />
==== Btrfs partitioning ====<br />
<br />
Btrfs can occupy an entire data storage device and replace the [[#Master Boot Record|MBR]] or [[#GUID Partition Table|GPT]] partitioning schemes. See the [[Btrfs#Partitionless Btrfs disk]] instructions for details.<br />
<br />
See also [[Wikipedia:Btrfs]].<br />
<br />
=== Backup and restoration ===<br />
<br />
See [[fdisk#Backup and restore]] and [[File recovery#Testdisk and PhotoRec]].<br />
<br />
== Partition scheme ==<br />
<br />
{{Expansion|It would be nice to have tables for each scenario|section=Example_tables}}<br />
<br />
There are no strict rules for partitioning a hard drive, although one may follow the general guidance given below. A disk partitioning scheme is determined by various issues such as desired flexibility, speed, security, as well as the limitations imposed by available disk space. It is essentially personal preference. If you would like to dual boot Arch Linux and a Windows operating system please see [[Dual boot with Windows]].<br />
<br />
{{Note|<br />
* [[UEFI]] systems require a separate [[EFI System Partition]].<br />
* BIOS systems partitioned with [[#GUID Partition Table|GPT]] requires a separate [[GRUB#GUID Partition Table (GPT) specific instructions|BIOS boot partition]] if [[GRUB]] is used as the bootloader (as is commonly the case).<br />
}}<br />
<br />
=== Single root partition ===<br />
<br />
This scheme is the simplest and should be enough for most use cases. A [[swapfile]] can be created and easily resized as needed. It usually makes sense to start by considering a single {{ic|/}} partition and then separate out others based on specific use cases like RAID, encryption, a shared media partition, etc.<br />
<br />
=== Discrete partitions ===<br />
<br />
Separating out a path as a partition allows for the choice of a different filesystem and mount options. In some cases like a media partition, they can also be shared between operating systems.<br />
<br />
=== Mount points ===<br />
<br />
The following mount points are possible choices for separate partitions, you can make your decision based on actual needs.<br />
<br />
==== Root partition ====<br />
<br />
The root directory is the top of the hierarchy, the point where the primary filesystem is mounted and from which all other filesystems stem. All files and directories appear under the root directory {{ic|/}}, even if they are stored on different physical devices. The contents of the root filesystem must be adequate to boot, restore, recover, and/or repair the system. Therefore, certain directories under {{ic|/}} are not candidates for separate partitions.<br />
<br />
The {{ic|/}} partition or root partition is necessary and it is the most important. The other partitions can be replaced by it.<br />
<br />
{{Warning|Directories essential for booting (except for {{ic|/boot}}) '''must''' be on the same partition as {{ic|/}} or mounted in early userspace by the [[initramfs]]. These essential directories are: {{ic|/etc}} and {{ic|/usr}} [http://freedesktop.org/wiki/Software/systemd/separate-usr-is-broken].}}<br />
<br />
==== /boot ====<br />
<br />
The {{ic|/boot}} directory contains the kernel and ramdisk images as well as the bootloader configuration file and bootloader stages. It also stores data that is used before the kernel begins executing user-space programs. {{ic|/boot}} is not required for normal system operation, but only during boot and kernel upgrades (when regenerating the initial ramdisk).<br />
<br />
A separate {{ic|/boot}} partition is needed if installing a software RAID0 (stripe) system.<br />
<br />
{{Note|It is recommended to mount [[ESP]] to {{ic|/boot}} if booting using UEFI boot loaders that do not contain drivers for other filesystems. Such loaders are for example [[EFISTUB]] and [[systemd-boot]].}}<br />
<br />
==== /home ====<br />
<br />
The {{ic|/home}} directory contains user-specific configuration files, caches, application data and media files.<br />
<br />
Separating out {{ic|/home}} allows {{ic|/}} to be re-partitioned separately, but note that you can still reinstall Arch with {{ic|/home}} untouched even if it is not separate - the other top-level directories just need to be removed, and then pacstrap can be run.<br />
<br />
You should not share home directories between users on different distributions, because they use incompatible software versions and patches. Instead, consider sharing a media partition or at least using different home directories on the same {{ic|/home}} partition.<br />
<br />
==== /var ====<br />
<br />
The {{ic|/var}} directory stores variable data such as spool directories and files, administrative and logging data, [[pacman]]'s cache, the [[ABS]] tree, etc. It is used, for example, for caching and logging, and hence frequently read or written. Keeping it in a separate partition avoids running out of disk space due to flunky logs, etc.<br />
<br />
It exists to make it possible to mount {{ic|/usr}} as read-only. Everything that historically went into {{ic|/usr}} that is written to during system operation (as opposed to installation and software maintenance) must reside under {{ic|/var}}.<br />
<br />
{{Note|{{ic|/var}} contains many small files. The choice of file system type should consider this fact if a separate partition is used.}}<br />
<br />
==== /tmp ====<br />
<br />
This is already a separate partition by default, by virtue of being mounted as ''tmpfs'' by systemd.<br />
<br />
==== Swap ====<br />
<br />
A [[swap]] partition provides memory that can be used as virtual RAM. A [[swap file]] should be considered too, as they don't have any performance overhead compared to a partition but are much easier to resize as needed. A swap partition can ''potentially'' be shared between operating systems, but not if hibernation is used.<br />
<br />
==== How big should my partitions be? ====<br />
<br />
{{Note|<br />
*The below are simply recommendations; there is no hard rule dictating partition size.<br />
*If available, an extra 25% of space added to each filesystem will provide a cushion for future expansion and help protect against fragmentation.}}<br />
<br />
The size of the partitions depends on personal preference, but the following information may be helpful:<br />
<br />
; /boot - 200 MB : It requires only about 100 MB, but if multiple kernels/boot images are likely to be in use, 200 or 300 MB is a better choice.<br />
; / - 15–20 GB : It traditionally contains the {{ic|/usr}} directory, which can grow significantly depending upon how much software is installed. 15–20 GB should be sufficient for most users with modern hard disks. If you plan to store a swap file here, you might need a larger partition size.<br />
; /var - 8–12 GB : It will contain, among other data, the [[ABS]] tree and the [[pacman]] cache. Retaining these packages is helpful in case a package upgrade causes instability, requiring a [[downgrade]] to an older, archived package. The pacman cache in particular will grow as the system is expanded and updated, but it can be safely cleared if space becomes an issue. 8–12 GB on a desktop system should be sufficient for {{ic|/var}}, depending on how much software will be installed.<br />
; /home - [varies] : It is typically where user data, downloads, and multimedia reside. On a desktop system, {{ic|/home}} is typically the largest filesystem on the drive by a large margin.<br />
; swap - [varies] : Historically, the general rule for swap partition size was to allocate twice the amount of physical RAM. As computers have gained ever larger memory capacities, this rule is outdated. For example, on average desktop machines with up to 512MB RAM, the 2x rule is usually adequate; if a sufficient amount of RAM (more than 1024MB) is available, it may be possible to have a smaller swap partition. See [[Suspend and hibernate]] to hibernate into a swap partition or file.<br />
; /data - [varies] : One can consider mounting a "data" partition to cover various files to be shared by all users. Using the {{ic|/home}} partition for this purpose is fine as well.<br />
<br />
== Partitioning tools ==<br />
<br />
The following programs can be used to create and/or manipulate device partition tables and partitions. See the linked articles for the exact commands to be used.<br />
<br />
{{Warning|To partition devices, use a partitioning tool compatible to the chosen type of partition table. Incompatible tools may result in the destruction of that table, along with existing partitions or data.}}<br />
<br />
*{{App|[[fdisk]]|Terminal partitioning tools included in Linux.|https://www.kernel.org/|{{Pkg|util-linux}}}}<br />
*{{App|[[cfdisk]]|Terminal partitioning tool written with ncurses libraries.|https://www.kernel.org/|{{Pkg|util-linux}}}}<br />
*{{App|[[sfdisk]]|Scriptable version of fdisk.||{{Pkg|util-linux}}}}<br />
*{{App|[[gdisk]]|[[#GUID Partition Table|GPT]] version of fdisk.|http://www.rodsbooks.com/gdisk/|{{Pkg|gptfdisk}}}}<br />
*{{App|[[cgdisk]]|GPT version of cfdisk.|http://www.rodsbooks.com/gdisk/|{{Pkg|gptfdisk}}}}<br />
*{{App|[[sgdisk]]|Scriptable version of gdisk.|http://www.rodsbooks.com/gdisk/sgdisk-walkthrough.html|{{Pkg|gptfdisk}}}}<br />
*{{App|[[GNU Parted]]|Terminal partitioning tool.|https://www.gnu.org/software/parted/parted.html|{{pkg|parted}}}}<br />
*{{App|[[GParted]]|Graphical tool written in GTK.|http://gparted.sourceforge.net/|{{Pkg|gparted}}}}<br />
*{{App|Partitionmanager|Graphical tool written in Qt.|http://sourceforge.net/projects/partitionman/|{{Pkg|partitionmanager}}}}<br />
<br />
This table will help you to choose utility for your needs:<br />
<br />
{| class="wikitable"<br />
! User interaction<br />
! MBR<br />
! GPT<br />
|-<br />
| Dialog<br />
| fdisk <br> parted<br />
| fdisk <br> gdisk <br> parted<br />
|-<br />
| Pseudo-graphics<br />
| cfdisk<br />
| cfdisk <br> cgdisk<br />
|-<br />
| Non-interactive<br />
| sfdisk <br> parted<br />
| sfdisk <br> sgdisk <br> parted<br />
|-<br />
| Graphical<br />
| GParted <br> partitionmanager<br />
| GParted <br> partitionmanager<br />
|}<br />
<br />
== Partition alignment ==<br />
<br />
Proper partition alignment is essential for optimal performance and longevity. This is due to the [[wikipedia:Block (data storage)|block]] nature of every I/O operation on the hardware level as well as file system level. The key to alignment is partitioning to (at least) the given ''block size'', which depends on the used hardware. If the partitions are not aligned to begin at multiples of the ''block size'', aligning the file system is a pointless exercise because everything is skewed by the start offset of the partition.<br />
<br />
=== Hard disk drives ===<br />
<br />
Historically, hard drives were addressed by indicating the ''cylinder'', the ''head'', and the ''sector'' at which data was to be read or written (also known as [[wikipedia:Cylinder-head-sector|CHS addressing]]). These represented the radial position (cylinder), the axial position (drive head: platter and side), and the azimuth (sector) of the data respectively. Nowadays, with [[wikipedia:Logical block addressing|logical block addressing]], the entire hard drive is addressed as one continuous stream of data and the term [[wikipedia:Disk sector|sector]] designates the smallest addressable unit.<br />
<br />
The standard ''sector size'' is 512B, but modern high-capacity hard drives use greater value, commonly 4KiB. Using values greater than 512B is referred to as the [[Advanced Format]].<br />
<br />
=== Solid state drives ===<br />
<br />
{{Expansion|The EBS should be the same as the value reported by {{ic|/sys/class/block/sd''X''/queue/discard_granularity}}.}}<br />
<br />
Solid state drives are based on [[wikipedia:Flash memory|flash memory]], and thus differ significantly from hard drives. While reading remains possible in a random access fashion, erasure (hence rewriting and random writing) is possible only by [[wikipedia:Flash_memory#Block_erasure|whole blocks]]. Additionally, the ''erase block size'' (EBS) are significantly greater than regular ''block size'', for example 128KiB vs. 4KiB, so it is necessary to align to multiples of EBS. Some [[NVMe]] drives should be aligned to 4KiB, but not all. To find the sector size of your SSD, see [[Advanced Format#How to determine if HDD employ a 4k sector]].<br />
<br />
=== Partitioning tools ===<br />
<br />
In the past, proper alignment required manual calculation and intervention when partitioning. Many of the common partition tools now handle partition alignment automatically:<br />
<br />
* ''fdisk''<br />
* ''gdisk''<br />
* ''gparted''<br />
* ''parted''<br />
<br />
On an already partitioned disk, you can use [[parted]] to verify the alignment of a partition on a device. For instance, to verify alignment of partition 1 on {{ic|/dev/sda}}:<br />
<br />
# parted /dev/sda<br />
(parted) align-check optimal 1<br />
1 aligned<br />
<br />
{{Warning|1=Using {{ic|/usr/bin/blockdev}} with option {{ic|--getalignoff}} to check if a the partition is aligned has been reported to be [https://bbs.archlinux.org/viewtopic.php?id=174141 unreliable].}}<br />
<br />
== See also ==<br />
* [[Wikipedia:Disk partitioning]]<br />
* [[Wikipedia:Binary prefix]]<br />
* [http://thestarman.pcministry.com/asm/mbr/DiskTerms.htm Understanding Disk Drive Terminology]<br />
* [http://kb.iu.edu/data/aijw.html What is a Master Boot Record (MBR)?]<br />
* Rod Smith's page on [http://www.rodsbooks.com/gdisk/whatsgpt.html What's a GPT?] and [http://rodsbooks.com/gdisk/booting.html Booting OSes from GPT]<br />
* [http://www.ibm.com/developerworks/linux/library/l-gpt/index.html?ca=dgr-lnxw07GPT-Storagedth-lx&S_TACT=105AGY83&S_CMP=grlnxw07 Make the most of large drives with GPT and Linux - IBM Developer Works]<br />
* [http://www.microsoft.com/whdc/device/storage/GPT_FAQ.mspx Microsoft's Windows and GPT FAQ]<br />
* [http://www.thomas-krenn.com/en/wiki/Partition_Alignment Partition Alignment] (with examples)</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Steam&diff=449298Steam2016-09-04T07:49:49Z<p>Fylwind: Mention the runtime issues first, which is kind of important</p>
<hr />
<div>[[Category:Gaming]]<br />
[[ja:Steam]]<br />
[[ru:Steam]]<br />
[[zh-CN:Steam]]<br />
{{Related articles start}}<br />
{{Related|Steam/Wine}}<br />
{{Related|Steam/Troubleshooting}}<br />
{{Related|Steam/Game-specific troubleshooting}}<br />
{{Related articles end}}<br />
From [[Wikipedia:Steam (software)|Wikipedia]]:<br />
:Steam is a digital distribution, digital rights management, multiplayer and communications platform developed by Valve Corporation. It is used to distribute games and related media online, from small independent developers to larger software houses.<br />
<br />
[http://store.steampowered.com/about/ Steam] is best known as the platform needed to play Source Engine games (e.g. Half-Life 2, Counter-Strike). Today it offers many games from many other developers.<br />
<br />
== Installation ==<br />
<br />
{{Note|<br />
* Arch Linux is '''not''' [https://support.steampowered.com/kb_article.php?ref&#61;1504-QHXN-8366 officially supported].<br />
* If you have a 64-bit system, enable the [[multilib]] repository.<br />
}}<br />
<br />
[[Install]] the {{Pkg|steam}} package.<br />
<br />
Steam is not supported on this distribution. As such some fixes are needed on the users part to get things functioning properly:<br />
<br />
* Steam may fail to start due to broken/missing libraries. See [[Steam/Troubleshooting#Steam runtime issues]].<br />
* Steam makes heavy usage of the Arial font. A decent Arial font to use is {{Pkg|ttf-liberation}} or [[Steam/Troubleshooting#Text is corrupt or missing|the fonts provided by Steam]]. Asian languages require {{Pkg|wqy-zenhei}} to display properly.<br />
* If you have a 64-bit system, you '''must''' install the 32-bit Multilib version of your [[Xorg#Driver installation|graphics driver]], {{pkg|lib32-alsa-plugins}} to enable sound, and {{pkg|lib32-curl}} to enable update at first run.<br />
* Several games have dependencies which may be missing from your system. If a game fails to launch (often without error messages) then make sure all of the libraries listed in [[Steam/Game-specific troubleshooting]] are installed.<br />
<br />
== Usage ==<br />
<br />
=== Big Picture Mode ===<br />
<br />
To start Steam in Big Picture Mode from a [[Display manager]], create a {{ic|/usr/share/xsessions/steam-big-picture.desktop}} file with the following contents: <br />
<br />
{{hc|/usr/share/xsessions/steam-big-picture.desktop|<nowiki><br />
[Desktop Entry]<br />
Name=Steam Big Picture Mode<br />
Comment=Start Steam in Big Picture Mode<br />
Exec=/usr/bin/steam -bigpicture<br />
TryExec=/usr/bin/steam<br />
Icon=<br />
Type=Application</nowiki>}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Launching games with custom commands ===<br />
<br />
{{Style}}<br />
<br />
Steam has fortunately added support for launching games using your own custom command. To do so, navigate to the Library page, right click on the selected game, click Properties, and Set Launch Options. Steam replaces the tag {{ic|%command%}} with the command it actually wishes to run. For example, to launch Team Fortress 2 with primusrun and at resolution 1920x1080, you would enter:<br />
<br />
primusrun %command% -w 1920 -h 1080<br />
<br />
On some systems optirun gives better performances than primusrun, however some games may crash shortly after the launch. This may be fixed preloading the correct version of libGL. Use:<br />
<br />
locate libGL<br />
<br />
to find out the available implementations. For a 64 bits game you may want to preload the nvidia 64 bits libGL, then use the launch command:<br />
<br />
LD_PRELOAD=/usr/lib/nvidia/libGL.so optirun %command%<br />
<br />
If you are running the [[Linux-ck]] kernel, you may have some success in reducing overall latencies and improving performance by launching the game in SCHED_ISO (low latency, avoid choking CPU) via {{Pkg|schedtool}}<br />
<br />
# schedtool -I -e %command% ''other arguments''<br />
<br />
Also keep in mind that Steam [http://i.imgur.com/oJcLDBi.png doesn't really care] what you want it to run. By setting {{ic|%command%}} to an environment variable, you can have Steam run whatever you would like. For example, the Launch Option used in the image above:<br />
<br />
IGNORE_ME=%command% glxgears<br />
<br />
=== Skins for Steam ===<br />
<br />
{{Note|Using skins that are not up-to-date with the version of the Steam client may cause visual errors.}}<br />
<br />
The Steam interface can be fully customized by copying its various interface files in its skins directory and modifying them.<br />
<br />
An extensive list of skins can be found on [http://forums.steampowered.com/forums/showthread.php?t=1161035 Steam's forums].<br />
<br />
=== Changing the Steam friends notification placement ===<br />
<br />
{{Style}}<br />
<br />
{{Note|A handful of games do not support this, for example this can not work with XCOM: Enemy Unknown.}}<br />
<br />
==== Use a skin ====<br />
<br />
You can create a skin that does nothing but change the notification corner. First you need to create the directories:<br />
<br />
$ mkdir -p $HOME/Top-Right/resource<br />
$ cp -R $HOME/.steam/steam/resource/styles $HOME/Top-Right/resource/<br />
$ mv $HOME/Top-Right $HOME/.local/share/Steam/skins/<br />
$ cd .local/share/Steam/skins/<br />
$ cp -R Top-Right Top-Left && cp -R Top-Right Bottom-Right<br />
<br />
Then modify the correct files. {{ic|Top-Right/resource/styles/gameoverlay.style}} will change the corner for the in-game overlay whereas {{ic|steam.style}} will change it for your desktop.<br />
<br />
Now find the entry: {{ic|Notifications.PanelPosition}} in whichever file you opened and change it to the appropriate value, for example for Top-Right:<br />
<br />
Notifications.PanelPosition "TopRight"<br />
<br />
This line will look the same in both files. Repeat the process for all the 3 variants ({{ic|Top-Right}}, {{ic|Top-Left}} and {{ic|Bottom-Left}}) and adjust the corners for the desktop and in-game overlay to your satisfaction for each skin, then save the files.<br />
<br />
To finish you will have to select the skin in Steam: ''Settings > Interface'' and ''<default skin>'' in the drop-down menu.<br />
<br />
You can use these files across distributions and even between Windows and Linux (OS X has its own entry for the desktop notification placement)<br />
<br />
==== On-the-fly patch ====<br />
<br />
This method is more compatible with future updates of Steams since the files in the skins above are updated as part of steam and as such if the original files change, the skin will not follow the graphics update to steam and will have to be re-created every time something like that happens. Doing things this way will also give you the ability to use per-game notification locations as you can run a patch changing the location of the notifications by specifying it in the launch options for games.<br />
<br />
Steam updates the files we need to edit everytime it updates (which is everytime it is launched) so the most effective way to do this is patching the file after Steam has already been launched.<br />
<br />
First you will need a patch:<br />
<br />
{{hc|$HOME/.steam/topright.patch|<nowiki><br />
--- A/steam/resource/styles/gameoverlay.styles 2013-06-14 23:49:36.000000000 +0000<br />
+++ B/steam/resource/styles/gameoverlay.styles 2014-07-08 23:13:15.255806000 +0000<br />
@@ -7,7 +7,7 @@<br />
mostly_black "0 0 0 240"<br />
semi_black "0 0 0 128"<br />
semi_gray "32 32 32 220"<br />
- Notifications.PanelPosition "BottomRight"<br />
+ Notifications.PanelPosition "TopRight"<br />
}<br />
<br />
styles<br />
<br />
</nowiki>}}<br />
<br />
{{Note|The patch file should have all above lines, including the newline at the end.}}<br />
<br />
You can edit the entry and change it between "BottomRight"(default), "TopRight" "TopLeft" and "BottomLeft": the following will assume you used "TopRight" as in the original file.<br />
<br />
Next create an alias in {{ic|$HOME/.bashrc}}:<br />
<br />
alias steam_topright='pushd $HOME/.steam/ && patch -p1 -f -r - --no-backup-if-mismatch < topright.patch && popd'<br />
<br />
Log out and back in to refresh the aliases. Launch Steam and wait for it to fully load, then run the alias <br />
<br />
$ steam_topright<br />
<br />
And most games you launch after this will have their notification in the upper right corner.<br />
<br />
You can also duplicate the patch and make more aliases for the other corners if you do not want all games to use the same corner so you can switch back.<br />
<br />
To automate the process you will need a script file as steam launch options cannot read your aliases. The location and name of the file could for example be '''$HOME/.scripts/steam_topright.sh''', and assuming that is the path you used, it needs to be executable:<br />
<br />
$ chmod +755 $HOME/.scripts/steam_topright.sh<br />
<br />
The contents of the file should be the following:<br />
<br />
#!/bin/sh<br />
pushd $HOME/.steam/ && patch -p1 -f -r - --no-backup-if-mismatch < topright.patch && popd<br />
<br />
And the launch options should be something like the following.<br />
<br />
$HOME/.scripts/steam_topright.sh && %command%<br />
<br />
There is another file in the same folder as '''gameoverlay.style''' folder called '''steam.style''' which has an entry with the exact same function as the file we patched and will change the notification corner for the desktop only (not in-game), but for editing this file to actually work it has to be set before steam is launched and the folder set to read-only so steam cannot re-write the file. Therefore the only two ways to modify that file is to make the directory read only so steam cannot change it when it is launched (can break updates) or making a skin like in method 1.<br />
<br />
=== Silent Mode ===<br />
<br />
To stop the main window from showing at startup, use the {{ic|-silent}} option:<br />
<br />
$ steam -silent<br />
<br />
{{Tip|This option can be added to a [[desktop entry]].}}<br />
<br />
=== Streaming server ===<br />
<br />
See https://steamcommunity.com/sharedfiles/filedetails/?id=680514371<br />
<br />
== Troubleshooting ==<br />
<br />
See [[Steam/Troubleshooting]].<br />
<br />
== See also ==<br />
<br />
* [https://wiki.gentoo.org/wiki/Steam Steam] at Gentoo wiki<br />
* [http://pcgamingwiki.com/wiki/The_Big_List_of_DRM-Free_Games_on_Steam The Big List of DRM-Free Games on Steam] at PCGamingWiki<br />
* [http://steam.wikia.com/wiki/List_of_DRM-free_games List of DRM-free games] at wikia</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Man_page&diff=434284Man page2016-05-08T02:48:03Z<p>Fylwind: /* Using less (Recommended) */ calling "man" inside a function named "man" leads to infinite recursion; also the "env" is totally useless here</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:System administration]]<br />
[[ar:Man page]]<br />
[[es:Man page]]<br />
[[ja:Man ページ]]<br />
[[ko:Man page]]<br />
[[ru:Man page]]<br />
[[zh-cn:Man page]]<br />
'''man pages''' (abbreviation for "manual pages") are the extensive documentation that comes preinstalled with almost all substantial UNIX-like operating systems, including Arch Linux. The command used to display them is {{Ic|man}}.<br />
<br />
In spite of their scope, man pages are designed to be self-contained documents, consequentially limiting themselves to referring to other man pages when discussing related subjects. This is in sharp contrast with the hyperlink-aware info files, GNU's attempt at replacing the traditional man page format.<br />
<br />
[[Core utilities#less|less]] is the default pager used with ''man''.<br />
<br />
== Accessing Man Pages ==<br />
To read a man page, simply enter:<br />
<br />
$ man ''page_name''<br />
<br />
Manuals are sorted into several sections:<br />
# General commands<br />
# System calls (functions provided by the kernel)<br />
# Library calls (C library functions)<br />
# Special files (usually found in /dev) and drivers<br />
# File formats and conventions<br />
# Games<br />
# Miscellaneous (including conventions)<br />
# System administration commands (usually requiring root privileges) and daemons<br />
<br />
Man pages are usually referred to by their name, followed by their section number in parentheses. Often there are multiple man pages of the same name, such as man(1) and man(7). In this case, give man the section number followed by the name of the man page, for example:<br />
<br />
$ man 5 passwd<br />
<br />
to read the man page on {{Ic|/etc/passwd}}, rather than the {{Ic|passwd}} utility.<br />
<br />
One-line descriptions of man pages can be displayed using the {{Ic|whatis}} command. For example, for a brief description of the man page sections about {{ic|ls}}, type:<br />
{{hc|$ whatis ls|ls (1p) - list directory contents<br />
ls (1) - list directory contents}}<br />
<br />
== Format ==<br />
Man pages all follow a fairly standard format, which helps in navigating them. Some sections which are often present include:<br />
* NAME - The name of the command and a one-line statement of its purpose.<br />
* SYNOPSIS - A list of the options and arguments a command takes or the parameters the function takes and its header file.<br />
* DESCRIPTION - A more in depth description of a command or function's purpose and workings.<br />
* EXAMPLES - Common examples, usually ranging from the simple to the relatively complex.<br />
* OPTIONS - Descriptions of each of the options a command takes and what they do.<br />
* EXIT STATUS - The meanings of different exit codes.<br />
* FILES - Files related to a command or function.<br />
* BUGS - Problems with the command or function that are pending repair. Also known as KNOWN BUGS.<br />
* SEE ALSO - A list of related commands or functions.<br />
* AUTHOR, HISTORY, COPYRIGHT, LICENSE, WARRANTY - Information about the program, its past, its terms of use, and its creator.<br />
<br />
== Searching manuals ==<br />
Whilst the {{Ic|man}} utility allows users to display man pages, and search their contents via ''less'', a problem arises when one knows not the exact name of the desired manual page in the first place! Fortunately, the {{Ic|-k}} or {{Ic|--apropos}} options can be used to search the manual page descriptions for instances of a given keyword.<br />
<br />
The research feature is provided by a dedicated cache. By default you may not have any cache built and all your searches will give you the ''nothing appropriate'' result. You can generate the cache or update it by running<br />
# mandb<br />
You should run it everytime a new manpage is installed.<br />
<br />
Now you can begin your search.<br />
For example, to search for man pages related to "password":<br />
<br />
$ man -k password<br />
<br />
or:<br />
<br />
$ man --apropos password<br />
<br />
This is equivalent to calling the {{Ic|apropos}} command:<br />
<br />
$ apropos password<br />
<br />
The given keyword is interpreted as a regular expression by default.<br />
<br />
If you want to do a more in-depth search by matching the keywords found in the whole articles, you can use the {{ic|-K}} option:<br />
$ man -K password<br />
<br />
== Colored man pages ==<br />
Color-enabled man pages allow for a clearer presentation and easier digestion of the content.<br />
There are two prevalent methods for achieving colored man pages: using {{Ic|less}}, or opting for {{Ic|most}}.<br />
<br />
=== Using less (Recommended) ===<br />
:<small>''Source: [http://linuxtidbits.wordpress.com/2009/03/23/less-colors-for-man-pages/ Less Colors For Man Pages | Linux Tidbits]''</small><br />
This method has the advantage that {{Ic|less}} has a bigger feature set than {{Ic|most}}, and is the default for viewing man pages.<br />
<br />
Add the following to a shell configuration file. For [[Bash]] it would be:<br />
{{hc|~/.bashrc|<br />
<nowiki>alias man="\<br />
LESS_TERMCAP_mb=$'\E[01;31m' \<br />
LESS_TERMCAP_md=$'\E[01;38;5;74m' \<br />
LESS_TERMCAP_me=$'\E[0m' \<br />
LESS_TERMCAP_se=$'\E[0m' \<br />
LESS_TERMCAP_so=$'\E[38;5;246m' \<br />
LESS_TERMCAP_ue=$'\E[0m' \<br />
LESS_TERMCAP_us=$'\E[04;38;5;146m' \<br />
man"<br />
</nowiki>}}<br />
<br />
To see the changes in your Man Pages (without restarting bash or linux), you may run:<br />
<br />
# source ~/.bashrc<br />
<br />
For [[Fish]] a basic configuration would be:<br />
{{hc|~/.config/fish/config.fish|<br />
<nowiki>set -xU LESS_TERMCAP_mb (printf "\e[01;31m") # begin blinking<br />
set -xU LESS_TERMCAP_md (printf "\e[01;31m") # begin bold<br />
set -xU LESS_TERMCAP_me (printf "\e[0m") # end mode<br />
set -xU LESS_TERMCAP_se (printf "\e[0m") # end standout-mode<br />
set -xU LESS_TERMCAP_so (printf "\e[01;44;33m") # begin standout-mode - info box<br />
set -xU LESS_TERMCAP_ue (printf "\e[0m") # end underline<br />
set -xU LESS_TERMCAP_us (printf "\e[01;32m") # begin underline<br />
</nowiki>}}<br />
<br />
To see the changes in your Man Pages (without restarting fish or linux), you may run:<br />
<br />
# source ~/.config/fish/config.fish<br />
<br />
For a detailed explanation on these variables, see [http://unix.stackexchange.com/questions/108699/documentation-on-less-termcap-variables/108840#108840 this answer]. To customize the colors, see [[Wikipedia:ANSI escape code]] for reference.<br />
<br />
==== If less doesn't display color man pages ====<br />
<br />
{{Accuracy|Which terminals on which systems don't support [[wikipedia:ANSI_escape_code#SGR|SGR escape sequences]]? Old versions of ''less'' are not supported on Arch. Anyway, this option ''disables'' colors, and everything ''might'' have been just fine until the above has been applied.}}<br />
<br />
On some systems, terminals don't understand SGR escape sequences, and older versions of {{Ic|less}} (without the -R option) don't understand SGR either. {{Ic|Groff}} offers a few solutions to fix this. The easiest one is to set and export the variable {{ic|GROFF_NO_SGR}} in your terminal environment:<br />
<br />
export GROFF_NO_SGR=1<br />
<br />
This tells {{Ic|groff}} to make adjustments when it is passed a man page for formatting.<br />
<br />
=== Using most (Not recommended) ===<br />
The basic function of 'most' is similar to {{Ic|less}} and {{Ic|more}}, but it has a smaller feature set. Configuring most to use colors is easier than using less, but additional configuration is necessary to make most behave like less.<br />
Install the {{Pkg|most}} package.<br />
<br />
Edit {{ic|/etc/man_db.conf}}, uncomment the pager definition and change it to:<br />
DEFINE pager most -s<br />
Test the new setup by typing:<br />
$ man whatever_man_page<br />
<br />
Modifying the color values requires editing {{ic|~/.mostrc}} (creating the file if it is not present) or editing {{ic|/etc/most.conf}} for system-wide changes. Example {{ic|~/.mostrc}}:<br />
% Color settings<br />
color normal lightgray black<br />
color status yellow blue<br />
color underline yellow black<br />
color overstrike brightblue black<br />
Another example showing keybindings similar to {{Ic|less}} (jump to line is set to 'J'):<br />
% less-like keybindings<br />
unsetkey "^K"<br />
unsetkey "g"<br />
unsetkey "G"<br />
unsetkey ":"<br />
<br />
setkey next_file ":n"<br />
setkey find_file ":e"<br />
setkey next_file ":p"<br />
setkey toggle_options ":o"<br />
setkey toggle_case ":c"<br />
setkey delete_file ":d"<br />
setkey exit ":q"<br />
<br />
setkey bob "g"<br />
setkey eob "G"<br />
setkey down "e"<br />
setkey down "E"<br />
setkey down "j"<br />
setkey down "^N"<br />
setkey up "y"<br />
setkey up "^Y"<br />
setkey up "k"<br />
setkey up "^P"<br />
setkey up "^K"<br />
setkey page_down "f"<br />
setkey page_down "^F"<br />
setkey page_up "b"<br />
setkey page_up "^B"<br />
setkey other_window "z"<br />
setkey other_window "w"<br />
setkey search_backward "?"<br />
setkey bob "p"<br />
setkey goto_mark "'"<br />
setkey find_file "E"<br />
setkey edit "v"<br />
<br />
=== Colored man pages on xterm or rxvt-unicode ===<br />
<br />
:<small>''Source: [http://pub.ligatura.org/fs/xfree86/xresources/xterm XFree resources file for XTerm program]''</small>{{Dead link|2013|09|10}}<br />
<br />
A quick way to add color to manual pages viewed on {{Pkg|xterm}}/{{Ic|uxterm}} or {{Pkg|rxvt-unicode}} is to modify {{ic|~/.Xresources}}.<br />
<br />
==== xterm ====<br />
*VT100.colorBDMode: true<br />
*VT100.colorBD: red<br />
*VT100.colorULMode: true<br />
*VT100.colorUL: cyan<br />
<br />
which ''replaces'' the decorations with the colors. Also add:<br />
<br />
*VT100.veryBoldColors: 6<br />
<br />
if you want colors and decorations (bold or underline) ''at the same time''. See {{ic|man xterm}} for a description of the {{ic|veryBoldColors}} resource.<br />
<br />
==== rxvt-unicode ====<br />
URxvt.colorIT: #87af5f<br />
URxvt.colorBD: #d7d7d7<br />
URxvt.colorUL: #87afd7<br />
<br />
Run:<br />
$ xrdb -load ~/.Xresources<br />
<br />
Launch a new {{Ic|xterm/uxterm}} or {{Ic|rxvt-unicode}} and you should see colorful man pages.<br />
This combination puts colors to '''bold''' and <u>underlined</u> words in {{Ic|xterm/uxterm}} or to '''bold''', <u>underlined</u>, and ''italicized'' text in {{Ic|rxvt-unicode}}. You can play with different combinations of these attributes (see the [http://pub.ligatura.org/fs/xfree86/xresources/xterm sources]{{Dead link|2013|09|10}} of this item).<br />
<br />
== Dynamic page width ==<br />
<br />
{{Accuracy|How is this dynamic? If you later resize the terminal window, the line breaks will still become wrong.}}<br />
<br />
The man page width is controlled by the {{Ic|MANWIDTH}} environment variable.<br />
<br />
If the number of columns in the terminal is too small (e.g. the window width is narrow), the line breaks will be wrong. This can be very disturbing for reading. You can fix this by setting the MANWIDTH on {{Ic|man}} invocation. With {{Ic|Bash}}, that would be:<br />
<br />
{{Hc|~/.bashrc|<br />
<nowiki>man() {<br />
local width=$(tput cols)<br />
[ $width -gt $MANWIDTH ] && width=$MANWIDTH<br />
env MANWIDTH=$width \<br />
man "$@"<br />
}<br />
</nowiki>}}<br />
<br />
Feel free to combine this function with the [[#Colored man pages|color settings]].<br />
<br />
== Reading local man pages ==<br />
Instead of the standard interface, using browsers such as {{Pkg|lynx}} and [[Firefox]] to view man pages allows users to reap info pages' main benefit: hyperlinked text.<br />
<br />
[[KDE]] users can read man pages in Konqueror using:<br />
man:<name><br />
From the [[Official repositories]] come two other possibilities:<br />
<br />
1. {{pkg|xorg-xman}} provides a categorized look at man pages in [[X]].<br />
<br />
2. The [[GNOME]] Help Browser {{pkg|yelp}} is a more neat way but has some dependencies.<br />
<br />
=== Converting to browser-readable HTML ===<br />
==== mdocml ====<br />
Install {{AUR|mdocml}} from [[AUR]]. To convert a page, for example {{ic|free(1)}}:<br />
$ gunzip -c /usr/share/man/man1/free.1.gz | mandoc -Thtml -Ostyle=style.css 1> free.html<br />
<br />
Now open the file called {{ic|free.html}} in your favourite browser.<br />
<br />
==== man2html ====<br />
First, install {{Pkg|man2html}} from the official repositories.<br />
<br />
Now, convert a man page:<br />
$ man free | man2html -compress -cgiurl man$section/$title.$section$subsection.html > ~/man/free.html<br />
<br />
Another use for {{Ic|man2html}} is exporting to raw, printer-friendly text:<br />
$ man free | man2html -bare > ~/free.txt<br />
<br />
==== man -H ====<br />
The GNU implementation of man in the Arch repositories also has the ability to do this on its own:<br />
$ man -H free<br />
<br />
This will read your {{ic|BROWSER}} [[environment variable]] to determine the browser. You can override this by passing the binary to the {{ic|-H}} option.<br />
<br />
==== roffit ====<br />
First install {{AUR|roffit}}{{Broken package link|{{aur-mirror|roffit}}}} from [[AUR]].<br />
<br />
To convert a man page:<br />
<br />
$ gunzip -c /usr/share/man/man1/free.1.gz | roffit > free.html<br />
<br />
=== Converting to PDF ===<br />
man pages have always been printable: they are written in troff, which is fundamentally a typesetting language. If you have ghostscript installed, converting a man page to PDF is actually very easy: {{ic|<nowiki>man -t <manpage> | ps2pdf - <pdf></nowiki>}}. [https://www.google.com/search?q=manpage+pdf+troff&num=100&hl=en&prmd=imvns&source=lnms&tbm=isch&sa=X&ei=5BZpUI3oH6rI2AXvx4CoAw&ved=0CAoQ_AUoAQ&biw=1321&bih=1100 This google image search] should give you an idea of what the result looks like; it may not be to everybody's liking.<br />
<br />
Caveats: Fonts are generally limited to Times at hardcoded sizes. There are no hyperlinks. Some man pages were specifically designed for terminal viewing, and won't look right in PS or PDF form.<br />
<br />
The following perl script converts man pages to PDFs, caches the PDFs in the {{ic|$HOME/.manpdf/}} directory, and calls a PDF viewer, specifically {{Pkg|mupdf}}.<br />
<br />
{{hc|Usage: manpdf [<section>] <manpage>|<nowiki><br />
#!/usr/bin/perl<br />
use File::stat;<br />
<br />
$pdfdir = $ENV{"HOME"}."/.manpdf";<br />
-d $pdfdir || mkdir $pdfdir || die "can't create $pdfdir";<br />
$manpage = $ARGV[0];<br />
chop($manpath = `man -w $manpage`);<br />
die if $?;<br />
<br />
$maninfo = stat($manpath) or die;<br />
$manpath =~ s@.*/man./(.*)(\.(gz|bz2))?$@$1@;<br />
$pdfpath = "$pdfdir/$manpath.pdf";<br />
$pdftime = 0;<br />
if (-f $pdfpath) {<br />
$pdfinfo = stat($pdfpath) or die;<br />
$pdftime = $pdfinfo->mtime;<br />
}<br />
if (!-f $pdfpath || $maninfo->mtime > $pdftime) {<br />
system "man -t $manpage | ps2pdf -dPDFSETTINGS=/screen - $pdfpath";<br />
}<br />
die if !-f $pdfpath;<br />
if (!fork) {<br />
open(STDOUT, "/dev/null");<br />
open(STDERR, "/dev/null");<br />
exec "mupdf", "-r", "96", $pdfpath;<br />
#exec "acroread", $pdfpath;<br />
}<br />
</nowiki>}}<br />
<br />
== Online Man Pages ==<br />
There are several online databases of man pages, including:<br />
*[http://man7.org/linux/man-pages/index.html Man7.org.] Upstream for Arch Linux's {{pkg|man-pages}}.<br />
*[http://manpages.debian.net/ ''Debian GNU/Linux man pages'']<br />
*[http://leaf.dragonflybsd.org/cgi/web-man ''DragonFlyBSD manual pages'']<br />
*[http://www.freebsd.org/cgi/man.cgi ''FreeBSD Hypertext Man Pages'']<br />
*[http://www.manpages.spotlynx.com/ ''Linux and Solaris 10 Man Pages'']<br />
*[http://manpagehelp.net ''Linux/FreeBSD Man Pages''] with user comments<br />
*[http://linux.die.net/man/ ''Linux man pages at die.net'']<br />
*[http://www.kernel.org/doc/man-pages/ The Linux man-pages project at kernel.org]<br />
*[http://netbsd.gw.com/cgi-bin/man-cgi ''NetBSD manual pages'']<br />
*[http://developer.apple.com/documentation/Darwin/Reference/ManPages/index.html ''Mac OS X Manual Pages'']<br />
*[http://unixhelp.ed.ac.uk/alphabetical/index.html ''On-line UNIX manual pages'']<br />
*[http://www.openbsd.org/cgi-bin/man.cgi ''OpenBSD manual pages'']<br />
*[http://man.cat-v.org/plan_9/ ''Plan 9 Manual — Volume 1'']<br />
*[http://man.cat-v.org/inferno/ ''Inferno Manual — Volume 1'']<br />
*[http://sfdoccentral.symantec.com/sf/5.0MP3/linux/manpages/index.html ''Storage Foundation Man Pages'']<br />
*[http://www.unix.com/man-page/OpenSolaris/1/man/ ''The UNIX and Linux Forums Man Page Repository'']<br />
*[http://manpages.ubuntu.com/ ''Ubuntu Manpage Repository'']<br />
<br />
{{Warning|Some distributions provide patched or outdated man pages that differ from those provided by Arch. Exercise caution when using online man pages.}}<br />
<br />
==Noteworthy manpages==<br />
<br />
Here follows a non-exhaustive list of noteworthy pages that might help you understand a lot of things more in-depth. Some of them might serve as a good reference (like the ascii table).<br />
<br />
* ascii(7)<br />
* boot(7)<br />
* charsets(7)<br />
* chmod(1)<br />
* credentials(7)<br />
* fstab(5)<br />
* hier(7)<br />
* systemd(1)<br />
* locale(1P)(5)(7)<br />
* printf(3)<br />
* proc(5)<br />
* regex(7)<br />
* signal(7)<br />
* term(5)(7)<br />
* termcap(5)<br />
* terminfo(5)<br />
* utf-8(7)<br />
More generally, have a look at category 7 pages:<br />
$ man -s 7 -k ".*" <br />
<br />
Arch Linux specific pages:<br />
* archlinux(7)<br />
* mkinitcpio(8)<br />
* pacman(8)<br />
* pacman-key(8)<br />
* pacman.conf(5)<br />
<br />
== See also ==<br />
<br />
* [http://wiki.gentoo.org/wiki/Man_page man page - Gentoo wiki article]<br />
* [http://unix.stackexchange.com/a/147 Setting colors for less] and [http://unix.stackexchange.com/a/6357 solving related problems] (threads on StackExchange)<br />
* [https://linuxtidbits.wordpress.com/2013/08/21/wtfm-write-the-fine-manual-with-pod2man-text-converter/ Write The Fine Manual with pod2man]</div>Fylwindhttps://wiki.archlinux.org/index.php?title=YubiKey&diff=414634YubiKey2016-01-07T17:41:39Z<p>Fylwind: compromission → compromise</p>
<hr />
<div>[[Category:Security]]<br />
[[ja:Yubikey]]<br />
The Yubikey is a small [http://en.wikipedia.org/wiki/Security_token USB token] that generates [http://en.wikipedia.org/wiki/One-time_password One-Time Passwords] (OTP).<br />
It is manufactured by [http://www.yubico.com/ Yubico].<br />
<br />
One of its strengths is that it emulates a USB keyboard to send the OTP as text, and thus requires only USB HID drivers found on practically all desktop computers.<br />
<br />
== Introduction ==<br />
<br />
=== How does it work ===<br />
<br />
Yubikey's authentication protocol is based on [http://en.wikipedia.org/wiki/Symmetric_cryptography symmetric cryptography].<br />
More specifically, each Yubikey contains a 128-bit [http://en.wikipedia.org/wiki/Advanced_Encryption_Standard AES] key unique to that device.<br />
It is used to encrypt a token made of different fields such as the ID of the key, a counter, a random number, etc.<br />
The OTP is made from concatenating the ID of the key with this encrypted token.<br />
<br />
This OTP is sent to the target system, to which we want to authenticate.<br />
This target system asks a validation server if the OTP is good.<br />
The validation server has a mapping of Yubikey IDs -> AES key.<br />
Using the key ID in the OTP, it can thus retrieve the AES key and decrypt the other part of the OTP.<br />
If it looks OK (plain-text ID and encrypted ID are the same, the counter is bigger than the last seen one to prevent [http://en.wikipedia.org/wiki/Replay_attack replay attacks]...), then authentication is successful.<br />
<br />
The validation server sends that authentication status back to the target system, which grants access or not based on that response.<br />
<br />
=== Security risks ===<br />
<br />
==== AES key compromise ====<br />
<br />
As you can imagine, the AES key should be kept very secret.<br />
It can not be retrieved from the Yubikey itself (or it should not, at least not with software).<br />
It is present in the validation server though, so the security of this server is very important.<br />
<br />
==== Validation requests/responses tampering ====<br />
<br />
Since the target system relies on the ruling of the validation server, a trivial attack would be to impersonate the validation server.<br />
The target system thus needs to authenticate the validation server.<br />
2 methods are available :<br />
* '''HMAC''': This is also symmetric crypto, the target server and validation server share a key that is used to sign requests and responses.<br />
* '''TLS''': Requests and responses travel via HTTP, so TLS (HTTPS) can be used to authenticate and encrypt the connection.<br />
<br />
=== YubiCloud and validation servers ===<br />
<br />
When you buy a Yubikey, it is preloaded with an AES key that is known only to Yubico.<br />
They will not even communicate it to you.<br />
Yubico provides a validation server with free unlimited access (YubiCloud).<br />
It also offers open-source implementations of the server.<br />
<br />
So you can either:<br />
* choose to use your Yubikey with its preloaded AES key and validate against Yubico's validation server ;<br />
* or load a new AES key in your Yubikey and run your own validation server.<br />
<br />
{{Note|To authenticate the Yubico validation server, you can:<br />
* '''with HMAC''': use https://upgrade.yubico.com/getapikey/ to get an HMAC key and ID<br />
* '''with HTTPS''': the validation server's certificate is signed by GoDaddy, that is cool because it is thus trusted by default in Arch installs (at least if you have package ca-certificates)}}<br />
<br />
== Two-factor authentication with SSH ==<br />
<br />
{{Note|See also: https://developers.yubico.com/yubico-pam/Yubikey_and_SSH_via_PAM.html}}<br />
<br />
This details how to use a Yubikey to have [http://en.wikipedia.org/wiki/Two-factor_authentication two-factor authentication] with SSH, that is, to use both a password and a Yubikey-generated OTP.<br />
<br />
=== Prerequisites ===<br />
<br />
Install {{Pkg|yubico-pam}}.<br />
<br />
{{Note|If you are configuring a distant server to use Yubikey, you should open at least one additional, rescue SSH session, so that you are not locked out of your server if the configuration does not work and you exit your main session inadvertently}}<br />
<br />
=== PAM configuration ===<br />
<br />
You have to edit {{ic|/etc/pam.d/sshd}}, and modify the line that reads :<br />
auth required pam_unix.so<br />
into<br />
auth required pam_unix.so use_first_pass<br />
<br />
Then do one of the following. I personally would highly recommend the HTTPS method, but the choice is yours. --[[User:Gohu|Gohu]] 17:49, 24 April 2011 (EDT)<br />
<br />
==== If using HTTPS to authenticate the validation server ====<br />
Insert the following line '''before''' the previously modified {{ic|pam_unix.so}} line.<br />
auth required pam_yubico.so id=1 url=https://api.yubico.com/wsapi/2.0/verify?id=%d&otp=%s<br />
The id=1 is of no real use but it is required.<br />
{{Note|If you run your own validation server, modify the {{ic|url}} parameter to point to your server. If you are not running your own validation server, you may omit the {{ic|url}} parameter entirely as it is the default.}}<br />
{{Note|These instructions are outdated and are unlikely to work. It may be useful to go to https://developers.yubico.com/yubico-pam/Yubikey_and_SSH_via_PAM.html for up to date instructions while someone finds the time to update the Arch Wiki.}}<br />
<br />
==== If using HMAC to authenticate the validation server ====<br />
Insert the following line '''before''' the previously modified {{ic|pam_unix.so}} line.<br />
auth required pam_yubico.so id=1234 key=YnVubmllcyBhcmUgY29vbAo=<br />
where {{ic|id}} and {{ic|key}} are your own HMAC ID and key, requested from Yubico as explained above.<br />
<br />
{{Note|HMAC credentials should be unique to a single target server. That way, if an attacker finds them, he will not be able to craft responses to authenticate to other target servers you own}}<br />
<br />
{{Note|We did not specify the {{ic|url}} parameter: it defaults to Yubico's HTTP (non-TLS) server}}<br />
<br />
You should also disallow unprivileged users to read the file to prevent them from seeing the HMAC credentials:<br />
# chmod o-r /etc/pam.d/sshd<br />
<br />
{{Note|If you run your own validation server, add the {{ic|url}} parameter to point to your server. If you are not running your own validation server, you may omit the {{ic|url}} parameter entirely as it is the default.}}<br />
<br />
=== SSHD configuration ===<br />
<br />
You should check that {{ic|/etc/ssh/sshd_config}} contains these lines and that they are not commented, but I believe this is the default.<br />
ChallengeResponseAuthentication no<br />
UsePAM yes<br />
<br />
=== That is it! ===<br />
<br />
You should not need to restart anything if you just touched the PAM config file.<br />
<br />
To log in, at the {{ic|Password:}} prompt of SSH, you have to type your password '''without pressing enter''' and touch the Yubikey's button.<br />
The Yubikey should send a return at the end of the OTP so you do not need to touch the enter key at all.<br />
<br />
{{Note|If you remove use_first_pass from the pam_unix.so line, you can just use your YubiKey first, then it will prompt for your password after the YubiKey line.}}<br />
<br />
=== Explanation ===<br />
This works because the prompt is {{ic|pam_yubico.so}}'s one, since this module is before {{ic|pam_unix.so}}, which does basic password authentication.<br />
So, you are giving a string that is the concatenation of your password and the OTP to {{ic|pam_yubico.so}}.<br />
Since the OTPs have a fixed length (let us call this size N), it just has to get the last N characters to retrieve the OTP, and it assumes that the other characters at the start are the password.<br />
It tries to validate the OTP, and in case of success, sends the password to the next PAM module, {{ic|pam_unix.so}}, which was instructed not to prompt for the password, but to receive it from the previous module, with {{ic|use_first_pass}}.<br />
<br />
== Installing the OATH Applet for a Yubikey NEO ==<br />
These steps will allow you to install the OATH applet onto your Yubikey NEO. This allows the use of Yubico Authenticator in the Google Play Store.<br />
{{Note|1=These steps are only for NEOs with a firmware version <= 3.1.2. The current generation NEOs (with U2F) come with the OpenPGP applet already installed)}}<br />
<br />
=== Configure the NEO as a CCID Device ===<br />
# Get {{AUR| yubikey-personalization-gui-git}} from the AUR.<br />
# Add the udev rules and reboot so you can manage the YubiKey without needing to be root<br />
# Run {{ic | ykpersonalize -m82}}, enter {{ic | y}}, and hit enter.<br />
<br />
=== Install the Applet ===<br />
# Install {{AUR| gpshell}}, {{AUR| gppcscconnectionplugin}}, {{AUR| globalplatform}}, and {{Pkg | pcsclite}}.<br />
# Start {{ic | pcscd}} with {{ic | sudo systemctl start pcscd}}.<br />
# Download the most recent CAP file from the [http://opensource.yubico.com/ykneo-oath/releases.html ykneo-oath] site.<br />
# Download {{ic | gpinstall.txt}} from [https://github.com/Yubico/ykneo-oath/blob/master/gpinstall.txt GitHub].<br />
# Edit the line in gpinstall.txt beginning with {{ic | install -file}} to reflect the path where the CAP file is located.<br />
# Open a terminal and run {{ic| gpshell <location of gpinstall.txt>}}<br />
# Ideally, a bunch of text will scroll by and it ends saying something like<br />
{{ bc | Command --> 80E88013D7C000C400BE00C700CA00CA00B400BE00CE00D200D500D700B000DB00C700DF00BEFFFF00BE00E400AC00AE00AE00DB00E700A<br />
A00EA00ED00ED00ED00BE00EF00F100F400F100F700FA00FF00BE00F700AA01010103010700CA00C400B400AA00F700B400AA00B600C7010C<br />
010C00AA0140012001B0056810B0013005600000056810E0011006B4B44304B44404B44106B44B4405B443400343B002410636810E06B4B44<br />
407326810B004B43103441003334002B102B404B3B403BB4003B440076820A4100221024405B4341008B44600000231066820A100<br />
Wrapped command --> 84E88013DFC000C400BE00C700CA00CA00B400BE00CE00D200D500D700B000DB00C700DF00BEFFFF00BE00E400AC00AE00AE00DB00E700A<br />
A00EA00ED00ED00ED00BE00EF00F100F400F100F700FA00FF00BE00F700AA01010103010700CA00C400B400AA00F700B400AA00B600C7010C<br />
010C00AA0140012001B0056810B0013005600000056810E0011006B4B44304B44404B44106B44B4405B443400343B002410636810E06B4B44<br />
407326810B004B43103441003334002B102B404B3B403BB4003B440076820A4100221024405B4341008B44600000231066820A15D848CB77<br />
27D0EDA00<br />
Response <-- 009000<br />
Command --> 80E60C002107A000000527210108A00000052721010108A000000527210101010003C901000000<br />
Wrapped command --> 84E60C002907A000000527210108A00000052721010108A000000527210101010003C9010000B4648127914A4C7C00<br />
Response <-- 009000<br />
card_disconnect<br />
release_context}}<br />
# Unplug the NEO and try it with the Yubico Authenticator app<br />
<br />
===(Optional) Install the Yubico Authenticator Desktop client===<br />
<br />
You can get the desktop version of the Yubico Authenticator by installing {{AUR|yubico-yubioath-desktop-git}}.<br />
<br />
== Enabling U2F in the browser ==<br />
<br />
=== Chromium/Chrome ===<br />
<br />
In order for the U2F functionality to work with Chromium you need to install the {{Pkg | libu2f-host}} library.<br />
This provides the [https://github.com/Yubico/libu2f-host/blob/master/70-u2f.rules udev rules] required to enable access to the Yubikey as a user.<br />
Yubikey is by default only accessible by root, and without these rules Chromium will give an error.<br />
<br />
=== Firefox ===<br />
<br />
To enable U2F support in Firefox, you need to install [https://github.com/prefiks/u2f4moz this addon].<br />
Native support is currently [https://bugzilla.mozilla.org/show_bug.cgi?id=1065729 work in progress].</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Android&diff=413570Android2015-12-27T09:28:01Z<p>Fylwind: /* Building Android */ alternative to installing lib32-ncurses5-compat-libs + flex error during build due to new glibc</p>
<hr />
<div>[[Category:Development]]<br />
[[Category:Mobile devices]]<br />
[[it:Android]]<br />
[[ja:Android]]<br />
[[ru:Android]]<br />
[[zh-CN:Android]]<br />
{{Related articles start}}<br />
{{Related|Android notifier}}<br />
{{Related|Android tethering}}<br />
{{Related articles end}}<br />
<br />
== Exploring Android device ==<br />
<br />
There are few methods of exploring your device:<br />
<br />
*[[MTP]] over USB for files transferring.<br />
*[[#Alternative connection methods|Alternative methods]] (such as FTP, SSH).<br />
<br />
For more advanced usage, development, flashing and restore:<br />
*[[#Android Debug Bridge (ADB)|ADB]] mostly for development purposes.<br />
*[[#Restoring Android|Restoring Android]] for flashing and restoring Android firmwares (includes fastboot).<br />
<br />
== Android development ==<br />
<br />
There are 3 steps that need to be performed before you can develop Android applications on your Arch Linux box:<br />
<br />
# Install the Android SDK core component,<br />
# Install one or several Android SDK Platform packages,<br />
# Install one of the IDEs compatible with the Android SDK.<br />
<br />
=== Android SDK core components ===<br />
<br />
{{Note|First, if you are running a 64-bit system, make sure the [[multilib]] repository is enabled in [[Pacman#Repositories|pacman.conf]]. Otherwise errors of the type: "error: target not found: lib32-zlib" will plague your installation attempt.}}<br />
<br />
Before developing Android applications, you need to install the Android SDK, which is made of 3 distinct packages, all installable from [[AUR]]:<br />
<br />
# {{AUR|android-sdk}}<br />
# {{AUR|android-sdk-platform-tools}}<br />
# {{AUR|android-sdk-build-tools}}<br />
<br />
Android-sdk will be installed on {{ic|/opt/android-sdk}}. This folder has root permissions, so keep in mind to run sdk manager as root, otherwise you will not be able to install/update/modify anything on /opt/android-sdk. However, if you intend to use it as a regular user, create an android sdk users group (or use any group name you want):<br />
# groupadd sdkusers<br />
<br />
Add your user into this group:<br />
# gpasswd -a <user> sdkusers<br />
<br />
Change folder's group.<br />
# chown -R :sdkusers /opt/android-sdk/<br />
<br />
Change permissions of the folder so the user that was just added to the group will be able to write in it:<br />
# chmod -R g+w /opt/android-sdk/<br />
<br />
Re-login or as <user> log your terminal in to the newly created group:<br />
<br />
$ newgrp sdkusers<br />
<br />
{{Note|As an alternative to a global install with the [[AUR]] packages, the SDK can be installed to a user's home directory via [https://developer.android.com/sdk/index.html the upstream instructions].}}<br />
<br />
=== Android SDK platform API ===<br />
<br />
Install the desired Android SDK Platform package from the [[AUR]]:<br />
<br />
* {{aur|android-platform}} (latest)<br />
* {{aur|android-platform-23}}<br />
* {{aur|android-platform-22}}<br />
* {{aur|android-platform-21}}<br />
* {{aur|android-platform-20}}<br />
* {{aur|android-platform-19}}{{Broken package link|{{aur-mirror|android-platform-19}}}}<br />
* {{aur|android-platform-18}}{{Broken package link|{{aur-mirror|android-platform-18}}}}<br />
* {{aur|android-platform-17}}{{Broken package link|{{aur-mirror|android-platform-17}}}}<br />
* {{aur|android-platform-16}}{{Broken package link|{{aur-mirror|android-platform-16}}}}<br />
* {{aur|android-platform-15}}{{Broken package link|{{aur-mirror|android-platform-15}}}}<br />
* {{aur|android-platform-14}}{{Broken package link|{{aur-mirror|android-platform-14}}}}<br />
* {{aur|android-platform-13}}{{Broken package link|{{aur-mirror|android-platform-13}}}}<br />
* {{aur|android-platform-12}}{{Broken package link|{{aur-mirror|android-platform-12}}}}<br />
* {{aur|android-platform-11}}{{Broken package link|{{aur-mirror|android-platform-11}}}}<br />
* {{aur|android-platform-10}}{{Broken package link|{{aur-mirror|android-platform-10}}}}<br />
* {{aur|android-platform-9}}{{Broken package link|{{aur-mirror|android-platform-9}}}}<br />
* {{aur|android-platform-8}}{{Broken package link|{{aur-mirror|android-platform-8}}}}<br />
* {{aur|android-platform-7}}{{Broken package link|{{aur-mirror|android-platform-7}}}}<br />
* {{aur|android-platform-6}}{{Broken package link|{{aur-mirror|android-platform-6}}}}<br />
* {{aur|android-platform-5}}{{Broken package link|{{aur-mirror|android-platform-5}}}}<br />
* {{aur|android-platform-4}}{{Broken package link|{{aur-mirror|android-platform-4}}}}<br />
* {{aur|android-platform-3}}{{Broken package link|{{aur-mirror|android-platform-3}}}}<br />
* {{aur|android-platform-2}}{{Broken package link|{{aur-mirror|android-platform-2}}}}<br />
<br />
=== Development environment ===<br />
<br />
Android Studio is the new official Android development environment based on IntelliJ IDEA. Alternatively, you can use [[Eclipse]] with the official but deprecated ADT plugin, or [[Netbeans]] with the NBAndroid plugin. All are described below.<br />
<br />
==== Android Studio ====<br />
<br />
[https://developer.android.com/sdk/index.html Android Studio] is the official Android development environment based on [https://www.jetbrains.com/idea/ IntelliJ Idea]. Android Studio replaces the older [https://developer.android.com/tools/help/adt.html Eclipse Android Developer Tools] and provides integrated Android developer tools for development and debugging.<br />
<br />
You can download and install it with the {{AUR|android-studio}} package from the [[AUR]]. If you get an error about a missing SDK, refer to the section Getting Android SDK platform API above.<br />
<br />
{{Note|1=If you are using a tiling window manager other than i3wm, you may need to apply one of the fixes mentioned in [https://code.google.com/p/android/issues/detail?id=57675 this] issue page.}}<br />
{{Note|1=Make sure you properly [[Java#Change_default_Java_environment|set the Java environment]] otherwise android-studio will not start.}}<br />
{{Note|1=Bad font rendering in Android Studio can be fixed by installing the [[Infinality#Installation_2|infinality-bundle]] and using infinality patched openJDK 7 ({{AUR|jdk7-openjdk-infinality}}) or openJDK 8 ({{AUR|jdk8-openjdk-infinality}}) from the AUR as mentioned in [https://youtrack.jetbrains.com/issue/IDEA-57233#comment=27-876236 this] issue page. Patched OpenJDK8 is also available from [[Unofficial user repositories#infinality-bundle|Infinality unofficial repository]]. }}<br />
<br />
Normally, apps are built through the Android Studio GUI. To build apps from the commandline (using e.g. {{ic|./gradlew assembleDebug}}), add the following to your {{ic|~/.bashrc}}:<br />
<br />
export ANDROID_HOME=/opt/android-sdk<br />
<br />
==== Eclipse ====<br />
<br />
{{Note|Since 2014-12-08, the ADT plugin is officially considered deprecated and Android Studio is now the official IDE.}}<br />
<br />
Most stuff required for Android development in Eclipse is already packaged in AUR:<br />
<br />
Official plugin by Google &ndash; [http://developer.android.com/sdk/eclipse-adt.html Eclipse ADT]:<br />
# {{AUR|eclipse-android}}<br />
<br />
Dependencies:<br />
# {{AUR|eclipse-emf}}<br />
# {{AUR|eclipse-gef}}<br />
# {{AUR|eclipse-wtp}}<br />
<br />
{{Note|<br />
* if you get a message about unresolvable dependencies, install [[Java]] manually and try again.<br />
* as an alternative, you can install the ADT via eclipse's built in "add new software" command (see instructions on ADT site).<br />
* if you are in real trouble, it is also possible to download Android SDK and use the bundled Eclipse. This usually works without problems.<br />
* if you need to install extra SDK plugins not found in the AUR, you must change the file ownership of /opt/android-sdk first. You can do this with {{ic|# chgrp -R users /opt/android-sdk ; chmod -R 0775 /opt/android-sdk}} (see [[File Permissions]] for more details).<br />
}}<br />
<br />
Enter the path to the Android SDK Location in<br />
<br />
Windows -> Preferences -> Android<br />
<br />
{{Note|<br />
If the plugins do not show up in Eclipse after the AUR package has been upgraded, then eclipse probably has out-of-date caches. Running {{ic|sudo eclipse -clean}} once should clear them. If the problem persists, uninstall eclipse and all the plugins, delete {{ic|/usr/share/eclipse}}, and reinstall everything.<br />
}}<br />
<br />
==== Netbeans ====<br />
<br />
If you prefer using [[Netbeans]] as your IDE and want to develop Android applications, download the [http://www.nbandroid.org NBAndroid] by going to:<br />
<br />
Tools -> Plugins -> Settings<br />
<br />
Add the following URL: http://nbandroid.org/release81/updates/updates.xml<br />
<br />
Then go to '''Available Plugins''' and install the '''Android''' and '''JUnit''' plugins. Once you have installed go to:<br />
<br />
Tools -> Options -> Miscellaneous -> Android<br />
<br />
and select the path where the SDK is installed (/opt/android-sdk by default). That is it, now you can create a new Android project and start developing using Netbeans.<br />
<br />
=== Android Debug Bridge (ADB) ===<br />
<br />
{{Tip|For some devices, you may have to enable MTP on the device, before ADB will work. Some other devices require enable PTP mode to work.}}<br />
==== Connect device ====<br />
To connect to a real device or phone via ADB under Arch, you must:<br />
<br />
# Install {{Pkg|android-tools}}. In addittion, you might want to install {{Pkg|android-udev}} if you wish to connect the device to the proper {{ic|/dev/}} entries.<br />
# Enable USB Debugging on your phone or device:<br />
#* Jelly Bean (4.2) and newer: Go to {{ic|Settings --> About Phone}} tap “Build Number” until you get a popup that you have become a developer (about 10 times). Then go to {{ic|Settings --> Developer --> USB debugging}} and enable it.<br />
#* Older versions: This is usually done from {{ic|Settings --> Applications --> Development --> USB debugging}}. Reboot the phone after checking this option to make sure USB debugging is enabled.<br />
# Add yourself to the ''adbusers'' group:<br />
# gpasswd -a ''username'' adbusers<br />
<br />
If [[#Does it work?|ADB recognizes your device]] (it is visible and accessible in IDE), you are done. Otherwise see instructions below.<br />
<br />
==== Figure out device IDs ====<br />
<br />
Each Android device has a USB vendor/product ID. An example for HTC Evo is:<br />
<br />
vendor id: 0bb4<br />
product id: 0c8d<br />
<br />
Plug in your device and execute:<br />
<br />
$ lsusb<br />
<br />
It should come up something like this:<br />
<br />
Bus 002 Device 006: ID 0bb4:0c8d High Tech Computer Corp.<br />
<br />
==== Adding udev Rules ====<br />
<br />
Use the rules from [http://source.android.com/source/initializing.html#configuring-usb-access Android developer] or you can use the following template for your udev rules, just replace [VENDOR ID] and [PRODUCT ID] with yours. Copy these rules into {{ic|/etc/udev/rules.d/51-android.rules}}:<br />
<br />
{{hc|/etc/udev/rules.d/51-android.rules|2=<nowiki>SUBSYSTEM=="usb", ATTR{idVendor}=="[VENDOR ID]", MODE="0666", GROUP="adbusers"<br />
SUBSYSTEM=="usb",ATTR{idVendor}=="[VENDOR ID]",ATTR{idProduct}=="[PRODUCT ID]",SYMLINK+="android_adb"<br />
SUBSYSTEM=="usb",ATTR{idVendor}=="[VENDOR ID]",ATTR{idProduct}=="[PRODUCT ID]",SYMLINK+="android_fastboot"</nowiki>}}<br />
<br />
Then, to reload your new udev rules, execute:<br />
# udevadm control --reload-rules<br />
<br />
==== Configuring adb ====<br />
<br />
Instead of using udev rules, you may create/edit {{ic|~/.android/adb_usb.ini}} which contains a list of vendor IDs.<br />
<br />
$ cat ~/.android/adb_usb.ini <br />
0x27e8<br />
<br />
==== Detect the device ====<br />
<br />
After you have setup the udev rules, unplug your device and replug it.<br />
<br />
After running:<br />
<br />
$ adb devices<br />
<br />
you should see something like:<br />
<br />
List of devices attached <br />
HT07VHL00676 device<br />
<br />
==== General usage ====<br />
<br />
You can now use adb to transfer files between the device and your computer. To transfer files to the device, use<br />
$ adb push ''<what-to-copy>'' ''<where-to-place>''<br />
<br />
To transfer files from the device, use<br />
$ adb pull ''<what-to-pull>'' ''<where-to-place>''<br />
<br />
==== Notes & Troubleshooting ====<br />
<br />
* '''ADB''' can also be installed via [[#Android SDK platform API|platform tools]](usually available in {{Ic|/opt/android-sdk/platform-tools/}}), so it might not be necesarry to install {{Pkg|android-tools}} (available in {{Ic|/usr/bin/}}).<br />
<br />
* If you are getting an empty list (your device is not there), it may be because you have not enabled USB debugging on your device. You can do that by going to Settings => Applications => Development and enabling USB debugging. On Android 4.2 (Jelly Bean) the Development menu is hidden; to enable it go to Settings => About phone and tap Build number 7 times.<br />
<br />
* If there are still problems such as ''adb'' displaying {{ic|???????? no permissions}} under devices, try restarting the adb server as root.<br />
# adb kill-server<br />
# adb start-server<br />
<br />
=== NVIDIA Tegra platform ===<br />
<br />
If you target your application at NVIDIA Tegra platform, you might also want to install tools, samples and documentation provided by NVIDIA. In [http://developer.nvidia.com/category/zone/mobile-development NVIDIA Developer Zone for Mobile] there are two tools: <br />
<br />
# The [http://developer.nvidia.com/tegra-resources Tegra Android Development Pack] provides tools (NVIDIA Debug Manager) related to [http://developer.android.com/sdk/eclipse-adt.html Eclipse ADT] and their documentation. <br />
# The [http://developer.nvidia.com/tegra-resources Tegra Toolkit] provides tools (mostly CPU and GPU optimization related), samples and documentation. <br />
<br />
Both are currently not available in the [[AUR]] anymore, because NVIDIA requires a registration/login for the download.<br />
<br />
== Building Android ==<br />
<br />
Please note that these instructions are based on the [http://source.android.com/source/building.html official AOSP build instructions]. Other Android-derived systems such as CyanogenMod will often require extra steps.<br />
<br />
=== OS bitness ===<br />
<br />
Android 2.2.x (Froyo) and below are the only versions of Android that will build on a 32-bit system. For 2.3.x (Gingerbread) and above, you will need a 64-bit installation. <br />
<br />
=== Required packages ===<br />
<br />
To build any version of Android, you need to install these packages:<br />
<br />
* 32-bit and 64-bit systems: {{Pkg|gcc}} {{Pkg|git}} {{Pkg|gnupg}} {{Pkg|flex}} {{Pkg|bison}} {{Pkg|gperf}} {{Pkg|sdl}} {{Pkg|wxgtk}} {{Pkg|squashfs-tools}} {{Pkg|curl}} {{Pkg|ncurses}} {{Pkg|zlib}} {{Pkg|schedtool}} {{Pkg|perl-switch}} {{Pkg|zip}} {{Pkg|unzip}} {{Pkg|libxslt}} {{Pkg|python2-virtualenv}} {{Pkg|bc}}<br />
<br />
* 64-bit systems only: {{Pkg|gcc-multilib}} {{Pkg|lib32-zlib}} {{Pkg|lib32-ncurses}} {{Pkg|lib32-readline}}<br />
<br />
* AUR Packages: {{Aur|libtinfo}}<br />
<br />
To build Android 6+, you need to install these additional packages:<br />
<br />
* 32-bit and 64-bit systems: {{Pkg|rsync}}<br />
<br />
{{Note|1=You must now also install {{Aur|lib32-ncurses5-compat-libs}} & {{Aur|ncurses5-compat-libs}} since ncurses was updated to ncurses6 and android's prebuilt clang still depends on ncurses5. You can check what libs are still needed:<br />
<br />
{{bc|ldd prebuilts/clang/linux-x86/host/3.6/bin/clang}}<br />
<br />
If you don't want to (or can't) replace lib32-ncurses with lib32-ncurses5-compat-libs, then you can instead just build the package with makepkg, extract the {{ic|.tar.xz}} to, say, {{ic|$HOME/lib32-ncurses5-compat-libs}}, and then export {{ic|LD_LIBRARY_PATH}}:<br />
<br />
{{bc|1=$ export LD_LIBRARY_PATH=$HOME/lib32-ncurses5-compat-libs/usr/lib32:$LD_LIBRARY_PATH}}<br />
}}<br />
<br />
=== Java Development Kit ===<br />
<br />
Android 5 (Lollipop) can be built with {{Pkg|jdk7-openjdk}}.<br />
<br />
Older versions [http://source.android.com/source/initializing.html require] a working '''Oracle JDK''' installed on your build system. It '''will not''' work with OpenJDK.<br />
*For Gingerbread through KitKat (2.3 - 4.4), Java 6 is required, which is available as {{AUR|jdk6}} from the AUR. See [[Java]] if you want to use it besides another (newer) JDK version.<br />
*For Cupcake through Froyo (1.5 - 2.2), Java 5 is required, which is no longer available for Arch Linux.<br />
<br />
=== Setting up the build environment ===<br />
<br />
Download the {{ic|repo}} utility per [https://source.android.com/source/downloading.html Android Downloading the Source guide].<br />
<br />
$ mkdir ~/bin<br />
$ export PATH=~/bin:$PATH<br />
$ curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo<br />
$ chmod a+x ~/bin/repo<br />
<br />
Create a directory to build.<br />
<br />
$ mkdir ~/android<br />
$ cd ~/android<br />
<br />
You will need to change the default Python from version 3 to version 2:<br />
<br />
$ virtualenv2 venv # Creates a directory, venv/, containing the Virtualenv<br />
<br />
{{Note|During build you may receive error pertaining to missing python modules. A quick and dirty fix is to symlink /usr/lib/python2.7/* to ~/android/venv/python2.7/ (Change ~/android to reflect your build directory if different than above).<br />
Example:<br />
$ ln -s /usr/lib/python2.7/* /Data/Android_Build/venv/lib/python2.7/<br />
}}<br />
Activate the Virtualenv, which will update $PATH to point at Python 2.<br />
<br />
{{Note|this activation is only active for the current terminal session.<br />
}}<br />
<br />
$ source venv/bin/activate<br />
<br />
=== Downloading the source code ===<br />
<br />
This will clone the repositories. You '''only''' need to do this the first time you build Android, or if you want to switch branches.<br />
<br />
* The {{ic|repo}} has a {{ic|-j}} switch that operates similarly to the one used with {{ic|make}}. Since it controls the number of simultaneous downloads, you should adjust the value depending on downstream network bandwidth.<br />
<br />
* You will need to specify a '''branch''' (release of Android) to check out with the {{ic|-b}} switch. If you leave the switch out, you will get the so-called '''master branch'''.<br />
<br />
$ repo init -u https://android.googlesource.com/platform/manifest -b master<br />
$ repo sync -j4<br />
<br />
{{Note|To further decrease sync times, you can utilize the -c switch with the repo command as such:<br />
$ repo sync -j8 -c<br />
The {{ic|-c}} switch will only sync the branch which is specified in the manifest, which in turn is determined by the branch specified with the {{ic|-b}} switch, or the default branch set by the repository maintainer.<br />
}}<br />
<br />
Wait a long time. Just the uncompiled source code, along with the {{ic|.repo}} and {{ic|.git}} directories that are used to keep track of it, are well over 10 GB.<br />
<br />
{{Note|If you want to update your local copy of the Android source, at a later time, simply enter the build directory, load the Virtualenv, and re-sync:<br />
$ repo sync<br />
}}<br />
<br />
=== Building the code ===<br />
<br />
This should do what you need for AOSP:<br />
<br />
$ source build/envsetup.sh<br />
$ lunch full-eng<br />
$ make -j4<br />
<br />
If you run '''lunch''' without arguments, it will ask what build you want to create. Use -j with a number between one and two times number of cores/threads.<br />
<br />
The build takes a very long time.<br />
<br />
{{Note|If {{ic|make}} fails with something like<br />
<br />
flex-2.5.39: loadlocale.c:131: _nl_intern_locale_data: Assertion `cnt < (sizeof (_nl_value_type_LC_COLLATE) / sizeof (_nl_value_type_LC_COLLATE[0]))' failed.<br />
<br />
try running {{ic|1=LANG=C make}} instead.<br />
<br />
}}<br />
<br />
{{Note|Make sure you have enough RAM.<br />
Android will use the /tmp directory heavily. By default the size of the partition the /tmp folder is mounted on is half the size of your RAM. If it fills up, the build will fail. 4GB of RAM or more is recommended.<br />
* Alternatively, you can get rid of the tmpfs from [[fstab]] all together. <br />
}}<br />
<br />
{{Note|From the [https://source.android.com/source/building-running.html#build-the-code Android Building and Running guide]:<br />
<br />
"GNU make can handle parallel tasks with a -jN argument, and it's common to use a number of tasks N that's between 1 and 2 times the number of hardware threads on the computer being used for the build. E.g. on a dual-E5520 machine (2 CPUs, 4 cores per CPU, 2 threads per core), the fastest builds are made with commands between make -j16 and make -j32."<br />
<br />
}}<br />
=== Testing the build ===<br />
<br />
When finished, run/test the final image(s).<br />
<br />
$ emulator<br />
<br />
=== Creating a Flashable Image ===<br />
To create an image that can be flashed it is necessary to:<br />
<br />
make -j8 updatepackage<br />
<br />
This will create a zip image under '''out/target/product/hammerhead''' (hammerhead being the device name) that can be flashed.<br />
<br />
== Restoring Android ==<br />
<br />
{{Expansion}}<br />
<br />
In some cases, you want to return to the stock Android after flashing custom ROMs to your Android mobile device. For flashing instructions of your device, please use [http://forum.xda-developers.com/ XDA forums].<br />
<br />
=== Fastboot ===<br />
<br />
Fastboot (as well as [[#Connecting_to_a_real_device_-_Android_Debug_Bridge_.28ADB.29|ADB]]) comes together with a package {{Pkg|android-tools}} from the [[official repositories]].<br />
<br />
{{Note|Restoring firmwares using {{ic|fastboot}} can be quite tricky, but you might want to browse [http://www.xda-developers.com/ XDA developers forums] for a stock firmware, which is mostly a {{ic|*.zip}} file, but inside of it, comes with the firmware files and {{ic|flash-all.sh}} script. For example, [https://developers.google.com/android/nexus/images Google Nexus] firmwares include {{ic|flash-all.sh}} script or another example could be for OnePlus One - [http://forum.xda-developers.com/oneplus-one/general/guide-return-opo-to-100-stock-t2826541 XDA thread], where you can find firmwares with included {{ic|flash-all.sh}} script.}}<br />
<br />
=== Samsung ===<br />
<br />
Samsung does not support fastboot in any way. Using Odin is safer, easier and more popular than Heimdall, but it is up to you.<br />
<br />
==== Heimdall ====<br />
<br />
[http://glassechidna.com.au/heimdall/ Heimdall] is a cross-platform open-source tool suite used to flash firmware (also known as ROMs) onto Samsung mobile devices and is also known as an alternative to [http://odindownload.com/ Odin]. It can be installed as {{Pkg|heimdall}} or {{AUR|heimdall-git}}.<br />
<br />
The flashing instructions can be found on Heimdall's [https://github.com/Benjamin-Dobell/Heimdall/tree/master/Linux GitHub page] or on [http://forum.xda-developers.com/showthread.php?t=1922461 XDA forums].<br />
<br />
==== Odin (Virtualbox) ====<br />
<br />
It is also possible to restore stock Android on the Samsung devices using [http://odindownload.com/ Odin], but inside the [[VirtualBox]]. For more information, see [http://forum.xda-developers.com/showthread.php?t=758634 XDA thread].<br />
<br />
Arch Linux related steps:<br />
# Install [[VirtualBox]] together with its [[VirtualBox#Extension_pack|extension pack]]. Optionally, install [[VirtualBox#Guest_additions_disc|guest additions]].<br />
# Install your preferred, but compatible with Odin, Windows operating system into a virtual hard drive using VirtualBox. Optionally, install guest additions to the Windows operating system.<br />
# Open VirtualBox settings of your Windows operating system, navigate to '''USB''', then tick (or make sure it is ticked) '''Enable USB 2.0 (EHCI) Controller'''.<br />
# At VirtualBox running Windows operating system, click in the menu bar '''Devices''', then '''USB Devices''', then click on your Samsung mobile device connected to your computer via USB.<br />
<br />
Windows related links:<br />
# Samsung drivers can be downloaded from [http://androidxda.com/download-samsung-usb-drivers here].<br />
# Odin can be downloaded from [https://www.androidfilehost.com/?fid=23501681358557126 here].<br />
# Samsung Android firmwares can be downloaded from [http://www.sammobile.com/firmwares/ here].<br />
<br />
If you want to make sure that everything is working and ready, connect your Samsung device turned on into a Download mode, and open Odin. The white box (a big one at the bottom-left) named '''Message''', should print a line similar to this:<br />
<ID:0/003> Added!!<br />
which means that your device is visible to Odin and is ready to be flashed.<br />
<br />
{{Note|There are no general instructions of restoring stock firmware on Samsung mobile devices. You have to use [https://www.google.com Google] and [http://www.xda-developers.com XDA developers forums] to find a flashing instructions for specific device. For example, this is how the [http://goo.gl/cZLyF8 thread] about the Samsung Galaxy S4 looks like}}<br />
<br />
== Alternative connection methods ==<br />
<br />
=== adb-sync ===<br />
<br />
[https://github.com/google/adb-sync adb-sync] (available in {{AUR|adb-sync-git}}) is a tool to synchronize files between a PC and an Android device using the ADB<br />
<br />
=== AirDroid ===<br />
<br />
[http://goo.gl/EZQ9GQ AirDroid] is an Android app to access files from your web browser.<br />
<br />
=== FTP ===<br />
<br />
You run a FTP server on Arch and connect to it from your phone, or the other way around: run a FTP server on your phone and connect to it from Arch.<br />
<br />
See [[List of applications/Internet#FTP]]. There are a lot of FTP clients/servers available for Android.<br />
<br />
=== SSH Server ===<br />
<br />
There are many SSH servers available for Android, it allows you to transfer files using {{ic|scp}} command. See also [[SSH]].<br />
<br />
=== Samba ===<br />
<br />
See [[Samba]].<br />
<br />
== Tips & Tricks ==<br />
<br />
=== During Debugging "Source not found" ===<br />
<br />
Most probably the debugger wants to step into the Java code. As the source code of Android does not come with the Android SDK, this leads to an error. The best solution is to use step filters to not jump into the Java source code. Step filters are not activated by default. To activate them: <br />
Window -> Preferences -> Java -> Debug -> Step Filtering<br />
Consider to select them all. If appropriate you can add the android.* package. See the forum post for more information: http://www.eclipsezone.com/eclipse/forums/t83338.rhtml<br />
<br />
=== Linux distribution on the sdcard ===<br />
<br />
You can install Debian like in this [http://forum.xda-developers.com/showthread.php?t=631389 thread]. Excellent guide to installing Arch in chroot (in parallel with Android) can be found on [http://archlinuxarm.org/forum/viewtopic.php?f=27&t=1361&start=40 archlinuxarm.org forum].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Android Studio: Android Virtual Devices show 'failed to load'. ===<br />
Make sure you've exported the variable {{ic|ANDROID_HOME}} as explained in [[Android Studio]].<br />
<br />
=== aapt: No such file or directory ===<br />
<br />
The build tools include 32-bit binaries. For this reason they require 32-bit libraries. If you happened to install the SDK manually, you will additionally need to install<br />
'''multilib/lib32-libstdc++5''' and '''multilib/lib32-zlib'''.<br />
<br />
=== ValueError: unsupported pickle protocol ===<br />
<br />
One fix is to issue:<br />
<br />
rm ~/.repopickle_.gitconfig<br />
<br />
If that does not work, then try this:<br />
<br />
rm `find /path/to/android-root -name .repopickle_config`</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Media_Transfer_Protocol&diff=410113Media Transfer Protocol2015-11-25T04:40:44Z<p>Fylwind: /* Input/output error upon first access */ Remounting does not seem to be necessary.</p>
<hr />
<div>[[Category:Storage]]<br />
[[Category:Mobile devices]]<br />
[[ja:MTP]]<br />
[[ru:MTP]]<br />
[[zh-CN:MTP]]<br />
{{Related articles start}}<br />
{{Related|USB storage devices}}<br />
{{Related articles end}}<br />
[[Wikipedia:Media_Transfer_Protocol|MTP]], or the ''Media Transfer Protocol'', is a USB device class which is used by many mobile phones (e.g. Samsung Galaxy S4) and media players (e.g. Creative Zen).<br />
<br />
== Installation ==<br />
<br />
=== Functionality ===<br />
<br />
Linux MTP support is provided by [[installing]] the {{Pkg|libmtp}} package. It can be installed on its own and used to access devices. However, a number of packages are available that use it as a dependency and add additional convenience (e.g. filemanager) functionalities and compatibility with particular device types - which includes improving transfer access speeds. <br />
<br />
These packages to choose from all implement a [[Wikipedia:Filesystem in Userspace]]: <br />
<br />
* {{Pkg|mtpfs}}<br />
* {{AUR|jmtpfs}} - is reported to work well for newer Android 4+ devices <br />
* {{AUR|go-mtpfs-git}} - is reported to work well for newer Android 3+ devices <br />
* {{AUR|simple-mtpfs}}<br />
* {{AUR|android-file-transfer}} - MTP client with minimalistic UI<br />
<br />
All of them aim at better functionality and performance over {{ic|libmtp}}. Since there are a lot of different USB devices, you might want to research first which one looks most suitable for yours. <br />
<br />
{{Tip|It is recommended to reboot your computer after installing MTP related packages.}}<br />
<br />
=== Integration with file managers ===<br />
<br />
To view the contents of your Android device's storage via MTP in your file manager, install the corresponding plugin:<br />
<br />
* For file managers that use [[GVFS]] (GNOME Files), install {{Pkg|gvfs-mtp}} for MTP or {{Pkg|gvfs-gphoto2}} for PTP support.<br />
* For file managers that use KIO (KDE's Dolphin), install {{Pkg|kio-mtp}}{{Broken package link|{{aur-mirror|kio-mtp}}}} (PTP support is included by default).<br />
<br />
After installing the required package, the device should show up in the file manager automatically and be accessible via an URL, for example {{ic|mtp://[usb:002,013]/}}.<br />
<br />
== Usage ==<br />
<br />
It might be required to create a mount-point directory first. The directory {{ic|~/mnt}} is used as an example below. Also do not forget to unlock your phone's screen before connecting it to the computer.<br />
<br />
=== libmtp ===<br />
<br />
Detect your device:<br />
<br />
# mtp-detect<br />
<br />
If an error is returned, see [[#libmtp 2|troubleshooting libmtp]]. <br />
<br />
{{Note|Your regular user must be in the {{ic|uucp}} group.}}<br />
<br />
Connect to your device:<br />
# mtp-connect<br />
<br />
If connection is successful, there are several switch options to use in conjunction with ''mtp-connect'' to access data on the device. You might want to use some stand alone commands:<br />
mtp-albumart mtp-emptyfolders mtp-getplaylist mtp-reset mtp-trexist<br />
mtp-albums mtp-files mtp-hotplug mtp-sendfile<br />
mtp-connect mtp-folders mtp-newfolder mtp-sendtr<br />
mtp-delfile mtp-format mtp-newplaylist mtp-thumb<br />
mtp-detect mtp-getfile mtp-playlists mtp-tracks<br />
{{Warning | Some commands may be harmful to your MTP device!}}<br />
<br />
=== mtpfs ===<br />
<br />
{{Note | The following is likely to not work and you might have to resort to [[Digital_Cameras#libgphoto2|gphoto2]] or a file manager with gvfs support like [[PCManFM]]. }}<br />
<br />
First edit your {{ic|/etc/fuse.conf}} and uncomment the following line:<br />
user_allow_other<br />
<br />
Mount your device on {{ic|~/mnt}}:<br />
$ mtpfs -o allow_other ~/mnt<br />
<br />
Unmount device mounted on {{ic|~/mnt}}:<br />
<br />
$ fusermount -u ~/mnt<br />
<br />
=== jmtpfs ===<br />
<br />
Mount device on {{ic|~/mnt}}:<br />
<br />
$ jmtpfs ~/mnt<br />
<br />
Unmount device mounted on {{ic|~/mnt}}:<br />
<br />
$ fusermount -u ~/mnt<br />
<br />
=== go-mtpfs ===<br />
<br />
{{Note|Mounting with {{ic|go-mtpfs}} might fail if an external SD Card is present. If you try to access your device while having an SD card and go-mtpfs complains, try removing the SD card and mounting again.}}<br />
<br />
Install {{Pkg|android-udev}}, which will allow you to edit {{ic|/etc/udev/rules.d/51-android.rules}} and apply to your {{ic|idVendor}} and {{ic|idProduct}}, which you can see after running ''mtp-detect''. To the end of the line, add your user {{ic|<nowiki>OWNER="<user>"</nowiki>}}. First, create the {{ic|fuse}} group if it doesn't exist:<br />
<br />
# groupadd fuse<br />
<br />
Add yourself to the {{ic|fuse}} group:<br />
<br />
# gpasswd -a <user> fuse<br />
<br />
Reboot might be required.<br />
<br />
Mount device on {{ic|~/mnt}}:<br />
<br />
$ go-mtpfs ~/mnt<br />
<br />
Unmount device mounted on {{ic|~/mnt}}:<br />
<br />
$ fusermount -u ~/mnt<br />
<br />
=== simple-mtpfs ===<br />
<br />
List MTP devices:<br />
<br />
$ simple-mtpfs --list-devices<br />
<br />
Mount your device on {{ic|~/mnt}}:<br />
<br />
$ simple-mtpfs ~/mnt<br />
<br />
Unmount device mounted on {{ic|~/mnt}}:<br />
<br />
$ fusermount -u ~/mnt<br />
<br />
=== Android File Transfer ===<br />
<br />
;FUSE interface<br />
<br />
$ mkdir ~/my-device<br />
$ ./aft-mtp-mount ~/my-device<br />
<br />
If you want album art to be displayed, it must be named {{ic|albumart.xxx}} and placed first in the destination folder. Then copy other files. Also, note that fuse could be 7-8 times slower than ui/cli file transfer.<br />
<br />
;Qt user interface<br />
<br />
Start the application, choose a destination folder and click any button on the toolbar. Available options are: ''Upload Album'', ''Upload Directory'' and ''Upload Files''. The latter two are self-explanatory. ''Upload album'' searches the source directory for album covers, and sets the best available cover.<br />
<br />
=== Media players ===<br />
<br />
You can also use your MTP device in music players such as Amarok. To achieve this, you might have to edit {{ic|/etc/udev/rules.d/51-android.rules}} (the MTP device used in the following example is a Galaxy Nexus). <br />
Run:<br />
<br />
$ lsusb<br />
<br />
Search for your device. It should be something like that:<br />
Bus 003 Device 011: ID 04e8:6860 Samsung Electronics Co., Ltd GT-I9100 Phone [Galaxy S II], GT-P7500 [Galaxy Tab 10.1]<br />
<br />
And entry to {{ic|/etc/udev/rules.d/51-android.rules}} will be this:<br />
SUBSYSTEM=="usb", ATTR{idVendor}=="04e8", ATTR{idProduct}=="6860", MODE="0666", OWNER="[username]"<br />
<br />
Also reload udev rules:<br />
# udevadm control --reload<br />
<br />
== Troubleshooting ==<br />
<br />
=== libmtp ===<br />
<br />
==== Unknown device ====<br />
<br />
If you see a message like:<br />
<br />
Device 0 (VID=XXXX and PID=XXXX) is UNKNOWN.<br />
Please report this VID/PID and the device model to the libmtp development team<br />
<br />
You should check whether your device is listed in the [http://sourceforge.net/p/libmtp/code/ci/HEAD/tree/src/music-players.h supported devices list]. If it is not, you should report it to the developers team. If it is, your {{ic|libmtp}} might be slightly outdated. To allow it to be properly used by {{ic|libmtp}}, you can add your device to:<br />
<br />
/etc/udev/rules.d/69-libmtp.rules<br />
<br />
==== Unable to enumerate USB device ====<br />
<br />
{{Merge||Unrelated to MTP, perhaps suited for [[USB storage devices]]}}<br />
<br />
If you see a message like this in system log ({{ic|journalctl}})<br />
<br />
usb usb4-port2: unable to enumerate USB device<br />
<br />
You can try following temporary [https://bbs.archlinux.org/viewtopic.php?pid=1087323#p1087323 workaround]<br />
<br />
# modprobe -vr uhci_hcd<br />
# modprobe -va ohci_hcd<br />
# modprobe -va uhci_hcd<br />
<br />
If it works you should create {{ic|/etc/modprobe.d/usb_hci_order.conf}} with following content<br />
<br />
# create a dependency on ohci for uhci, which fixes problems<br />
# with external usb devices not showing up<br />
#<br />
softdep uhci_hcd pre: ohci_hcd<br />
<br />
=== jmtpfs ===<br />
<br />
==== Input/output error upon first access ====<br />
<br />
Symptoms: jmtpfs successfully mounts, but as soon as one attempts to access files on the device (e.g. via {{ic|ls}}), an error is reported:<br />
<br />
cannot access <mount-point>: Input/output error<br />
<br />
This appears to be a security feature: MTP does not work when the phone is locked by the lockscreen. Unlock the phone and it should work again as long as the cord remains connected.<br />
<br />
=== gvfs-mtp ===<br />
<br />
{{Merge|udev}}<br />
<br />
If you have installed the {{Pkg|gvfs-mtp}} package, and your device doesn't show up in the file manager, you might need to reboot or write a udev rule in order to auto-mount the device.<br />
<br />
Plug your device and get the vendor-id and product-id,respectively:<br />
<br />
$ lsusb<br />
Bus 001 Device 007: ID 0421:0661 Nokia Mobile Phones Lumia 920<br />
(...)<br />
<br />
The two numbers after ID are ''vendorId'' : ''productID''<br />
<br />
Then make a udev rule, e.g.<br />
<br />
# nano /etc/udev/rules.d/51-android.rules<br />
<br />
and type this rule:<br />
<br />
ATTR{idVendor}=="YOUR VENDOR ID HERE", ATTR{idProduct}=="YOUR PRODUCT ID HERE", SYMLINK+="libmtp", MODE="660", ENV{ID_MTP_DEVICE}="1"<br />
<br />
Reload the udev rules.<br />
<br />
# udevadm control --reload<br />
<br />
And reboot the system. Now file managers (like Thunar) should be able to automount the MTP Device. [https://bbs.archlinux.org/viewtopic.php?id=180719]<br />
<br />
=== kio-mtp ===<br />
<br />
If you are not able to use the action "Open with File Manager", you may work around this problem by editing the file {{ic|/usr/share/apps/solid/actions/solid_mtp.desktop}}.<br />
<br />
Change the line<br />
<br />
Exec=kioclient exec mtp:udi=%i/<br />
<br />
To<br />
<br />
Exec=dolphin "mtp:/"</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Media_Transfer_Protocol&diff=410112Media Transfer Protocol2015-11-25T04:37:40Z<p>Fylwind: /* jmtpfs */ I guess this could be considered "working as intended", although the error message is kind of useless.</p>
<hr />
<div>[[Category:Storage]]<br />
[[Category:Mobile devices]]<br />
[[ja:MTP]]<br />
[[ru:MTP]]<br />
[[zh-CN:MTP]]<br />
{{Related articles start}}<br />
{{Related|USB storage devices}}<br />
{{Related articles end}}<br />
[[Wikipedia:Media_Transfer_Protocol|MTP]], or the ''Media Transfer Protocol'', is a USB device class which is used by many mobile phones (e.g. Samsung Galaxy S4) and media players (e.g. Creative Zen).<br />
<br />
== Installation ==<br />
<br />
=== Functionality ===<br />
<br />
Linux MTP support is provided by [[installing]] the {{Pkg|libmtp}} package. It can be installed on its own and used to access devices. However, a number of packages are available that use it as a dependency and add additional convenience (e.g. filemanager) functionalities and compatibility with particular device types - which includes improving transfer access speeds. <br />
<br />
These packages to choose from all implement a [[Wikipedia:Filesystem in Userspace]]: <br />
<br />
* {{Pkg|mtpfs}}<br />
* {{AUR|jmtpfs}} - is reported to work well for newer Android 4+ devices <br />
* {{AUR|go-mtpfs-git}} - is reported to work well for newer Android 3+ devices <br />
* {{AUR|simple-mtpfs}}<br />
* {{AUR|android-file-transfer}} - MTP client with minimalistic UI<br />
<br />
All of them aim at better functionality and performance over {{ic|libmtp}}. Since there are a lot of different USB devices, you might want to research first which one looks most suitable for yours. <br />
<br />
{{Tip|It is recommended to reboot your computer after installing MTP related packages.}}<br />
<br />
=== Integration with file managers ===<br />
<br />
To view the contents of your Android device's storage via MTP in your file manager, install the corresponding plugin:<br />
<br />
* For file managers that use [[GVFS]] (GNOME Files), install {{Pkg|gvfs-mtp}} for MTP or {{Pkg|gvfs-gphoto2}} for PTP support.<br />
* For file managers that use KIO (KDE's Dolphin), install {{Pkg|kio-mtp}}{{Broken package link|{{aur-mirror|kio-mtp}}}} (PTP support is included by default).<br />
<br />
After installing the required package, the device should show up in the file manager automatically and be accessible via an URL, for example {{ic|mtp://[usb:002,013]/}}.<br />
<br />
== Usage ==<br />
<br />
It might be required to create a mount-point directory first. The directory {{ic|~/mnt}} is used as an example below. Also do not forget to unlock your phone's screen before connecting it to the computer.<br />
<br />
=== libmtp ===<br />
<br />
Detect your device:<br />
<br />
# mtp-detect<br />
<br />
If an error is returned, see [[#libmtp 2|troubleshooting libmtp]]. <br />
<br />
{{Note|Your regular user must be in the {{ic|uucp}} group.}}<br />
<br />
Connect to your device:<br />
# mtp-connect<br />
<br />
If connection is successful, there are several switch options to use in conjunction with ''mtp-connect'' to access data on the device. You might want to use some stand alone commands:<br />
mtp-albumart mtp-emptyfolders mtp-getplaylist mtp-reset mtp-trexist<br />
mtp-albums mtp-files mtp-hotplug mtp-sendfile<br />
mtp-connect mtp-folders mtp-newfolder mtp-sendtr<br />
mtp-delfile mtp-format mtp-newplaylist mtp-thumb<br />
mtp-detect mtp-getfile mtp-playlists mtp-tracks<br />
{{Warning | Some commands may be harmful to your MTP device!}}<br />
<br />
=== mtpfs ===<br />
<br />
{{Note | The following is likely to not work and you might have to resort to [[Digital_Cameras#libgphoto2|gphoto2]] or a file manager with gvfs support like [[PCManFM]]. }}<br />
<br />
First edit your {{ic|/etc/fuse.conf}} and uncomment the following line:<br />
user_allow_other<br />
<br />
Mount your device on {{ic|~/mnt}}:<br />
$ mtpfs -o allow_other ~/mnt<br />
<br />
Unmount device mounted on {{ic|~/mnt}}:<br />
<br />
$ fusermount -u ~/mnt<br />
<br />
=== jmtpfs ===<br />
<br />
Mount device on {{ic|~/mnt}}:<br />
<br />
$ jmtpfs ~/mnt<br />
<br />
Unmount device mounted on {{ic|~/mnt}}:<br />
<br />
$ fusermount -u ~/mnt<br />
<br />
=== go-mtpfs ===<br />
<br />
{{Note|Mounting with {{ic|go-mtpfs}} might fail if an external SD Card is present. If you try to access your device while having an SD card and go-mtpfs complains, try removing the SD card and mounting again.}}<br />
<br />
Install {{Pkg|android-udev}}, which will allow you to edit {{ic|/etc/udev/rules.d/51-android.rules}} and apply to your {{ic|idVendor}} and {{ic|idProduct}}, which you can see after running ''mtp-detect''. To the end of the line, add your user {{ic|<nowiki>OWNER="<user>"</nowiki>}}. First, create the {{ic|fuse}} group if it doesn't exist:<br />
<br />
# groupadd fuse<br />
<br />
Add yourself to the {{ic|fuse}} group:<br />
<br />
# gpasswd -a <user> fuse<br />
<br />
Reboot might be required.<br />
<br />
Mount device on {{ic|~/mnt}}:<br />
<br />
$ go-mtpfs ~/mnt<br />
<br />
Unmount device mounted on {{ic|~/mnt}}:<br />
<br />
$ fusermount -u ~/mnt<br />
<br />
=== simple-mtpfs ===<br />
<br />
List MTP devices:<br />
<br />
$ simple-mtpfs --list-devices<br />
<br />
Mount your device on {{ic|~/mnt}}:<br />
<br />
$ simple-mtpfs ~/mnt<br />
<br />
Unmount device mounted on {{ic|~/mnt}}:<br />
<br />
$ fusermount -u ~/mnt<br />
<br />
=== Android File Transfer ===<br />
<br />
;FUSE interface<br />
<br />
$ mkdir ~/my-device<br />
$ ./aft-mtp-mount ~/my-device<br />
<br />
If you want album art to be displayed, it must be named {{ic|albumart.xxx}} and placed first in the destination folder. Then copy other files. Also, note that fuse could be 7-8 times slower than ui/cli file transfer.<br />
<br />
;Qt user interface<br />
<br />
Start the application, choose a destination folder and click any button on the toolbar. Available options are: ''Upload Album'', ''Upload Directory'' and ''Upload Files''. The latter two are self-explanatory. ''Upload album'' searches the source directory for album covers, and sets the best available cover.<br />
<br />
=== Media players ===<br />
<br />
You can also use your MTP device in music players such as Amarok. To achieve this, you might have to edit {{ic|/etc/udev/rules.d/51-android.rules}} (the MTP device used in the following example is a Galaxy Nexus). <br />
Run:<br />
<br />
$ lsusb<br />
<br />
Search for your device. It should be something like that:<br />
Bus 003 Device 011: ID 04e8:6860 Samsung Electronics Co., Ltd GT-I9100 Phone [Galaxy S II], GT-P7500 [Galaxy Tab 10.1]<br />
<br />
And entry to {{ic|/etc/udev/rules.d/51-android.rules}} will be this:<br />
SUBSYSTEM=="usb", ATTR{idVendor}=="04e8", ATTR{idProduct}=="6860", MODE="0666", OWNER="[username]"<br />
<br />
Also reload udev rules:<br />
# udevadm control --reload<br />
<br />
== Troubleshooting ==<br />
<br />
=== libmtp ===<br />
<br />
==== Unknown device ====<br />
<br />
If you see a message like:<br />
<br />
Device 0 (VID=XXXX and PID=XXXX) is UNKNOWN.<br />
Please report this VID/PID and the device model to the libmtp development team<br />
<br />
You should check whether your device is listed in the [http://sourceforge.net/p/libmtp/code/ci/HEAD/tree/src/music-players.h supported devices list]. If it is not, you should report it to the developers team. If it is, your {{ic|libmtp}} might be slightly outdated. To allow it to be properly used by {{ic|libmtp}}, you can add your device to:<br />
<br />
/etc/udev/rules.d/69-libmtp.rules<br />
<br />
==== Unable to enumerate USB device ====<br />
<br />
{{Merge||Unrelated to MTP, perhaps suited for [[USB storage devices]]}}<br />
<br />
If you see a message like this in system log ({{ic|journalctl}})<br />
<br />
usb usb4-port2: unable to enumerate USB device<br />
<br />
You can try following temporary [https://bbs.archlinux.org/viewtopic.php?pid=1087323#p1087323 workaround]<br />
<br />
# modprobe -vr uhci_hcd<br />
# modprobe -va ohci_hcd<br />
# modprobe -va uhci_hcd<br />
<br />
If it works you should create {{ic|/etc/modprobe.d/usb_hci_order.conf}} with following content<br />
<br />
# create a dependency on ohci for uhci, which fixes problems<br />
# with external usb devices not showing up<br />
#<br />
softdep uhci_hcd pre: ohci_hcd<br />
<br />
=== jmtpfs ===<br />
<br />
==== Input/output error upon first access ====<br />
<br />
Symptoms: jmtpfs successfully mounts, but as soon as one attempts to access files on the device (e.g. via {{ic|ls}}), an error is reported:<br />
<br />
cannot access <mount-point>: Input/output error<br />
<br />
This appears to be a security feature: MTP does not work when the phone is locked by the lockscreen. Unlock the phone and then remount the device.<br />
<br />
=== gvfs-mtp ===<br />
<br />
{{Merge|udev}}<br />
<br />
If you have installed the {{Pkg|gvfs-mtp}} package, and your device doesn't show up in the file manager, you might need to reboot or write a udev rule in order to auto-mount the device.<br />
<br />
Plug your device and get the vendor-id and product-id,respectively:<br />
<br />
$ lsusb<br />
Bus 001 Device 007: ID 0421:0661 Nokia Mobile Phones Lumia 920<br />
(...)<br />
<br />
The two numbers after ID are ''vendorId'' : ''productID''<br />
<br />
Then make a udev rule, e.g.<br />
<br />
# nano /etc/udev/rules.d/51-android.rules<br />
<br />
and type this rule:<br />
<br />
ATTR{idVendor}=="YOUR VENDOR ID HERE", ATTR{idProduct}=="YOUR PRODUCT ID HERE", SYMLINK+="libmtp", MODE="660", ENV{ID_MTP_DEVICE}="1"<br />
<br />
Reload the udev rules.<br />
<br />
# udevadm control --reload<br />
<br />
And reboot the system. Now file managers (like Thunar) should be able to automount the MTP Device. [https://bbs.archlinux.org/viewtopic.php?id=180719]<br />
<br />
=== kio-mtp ===<br />
<br />
If you are not able to use the action "Open with File Manager", you may work around this problem by editing the file {{ic|/usr/share/apps/solid/actions/solid_mtp.desktop}}.<br />
<br />
Change the line<br />
<br />
Exec=kioclient exec mtp:udi=%i/<br />
<br />
To<br />
<br />
Exec=dolphin "mtp:/"</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Media_Transfer_Protocol&diff=410111Media Transfer Protocol2015-11-25T04:36:03Z<p>Fylwind: /* Input/output error upon first access */ Think I found out the real reason why this happens</p>
<hr />
<div>[[Category:Storage]]<br />
[[Category:Mobile devices]]<br />
[[ja:MTP]]<br />
[[ru:MTP]]<br />
[[zh-CN:MTP]]<br />
{{Related articles start}}<br />
{{Related|USB storage devices}}<br />
{{Related articles end}}<br />
[[Wikipedia:Media_Transfer_Protocol|MTP]], or the ''Media Transfer Protocol'', is a USB device class which is used by many mobile phones (e.g. Samsung Galaxy S4) and media players (e.g. Creative Zen).<br />
<br />
== Installation ==<br />
<br />
=== Functionality ===<br />
<br />
Linux MTP support is provided by [[installing]] the {{Pkg|libmtp}} package. It can be installed on its own and used to access devices. However, a number of packages are available that use it as a dependency and add additional convenience (e.g. filemanager) functionalities and compatibility with particular device types - which includes improving transfer access speeds. <br />
<br />
These packages to choose from all implement a [[Wikipedia:Filesystem in Userspace]]: <br />
<br />
* {{Pkg|mtpfs}}<br />
* {{AUR|jmtpfs}} - is reported to work well for newer Android 4+ devices <br />
* {{AUR|go-mtpfs-git}} - is reported to work well for newer Android 3+ devices <br />
* {{AUR|simple-mtpfs}}<br />
* {{AUR|android-file-transfer}} - MTP client with minimalistic UI<br />
<br />
All of them aim at better functionality and performance over {{ic|libmtp}}. Since there are a lot of different USB devices, you might want to research first which one looks most suitable for yours. <br />
<br />
{{Tip|It is recommended to reboot your computer after installing MTP related packages.}}<br />
<br />
=== Integration with file managers ===<br />
<br />
To view the contents of your Android device's storage via MTP in your file manager, install the corresponding plugin:<br />
<br />
* For file managers that use [[GVFS]] (GNOME Files), install {{Pkg|gvfs-mtp}} for MTP or {{Pkg|gvfs-gphoto2}} for PTP support.<br />
* For file managers that use KIO (KDE's Dolphin), install {{Pkg|kio-mtp}}{{Broken package link|{{aur-mirror|kio-mtp}}}} (PTP support is included by default).<br />
<br />
After installing the required package, the device should show up in the file manager automatically and be accessible via an URL, for example {{ic|mtp://[usb:002,013]/}}.<br />
<br />
== Usage ==<br />
<br />
It might be required to create a mount-point directory first. The directory {{ic|~/mnt}} is used as an example below. Also do not forget to unlock your phone's screen before connecting it to the computer.<br />
<br />
=== libmtp ===<br />
<br />
Detect your device:<br />
<br />
# mtp-detect<br />
<br />
If an error is returned, see [[#libmtp 2|troubleshooting libmtp]]. <br />
<br />
{{Note|Your regular user must be in the {{ic|uucp}} group.}}<br />
<br />
Connect to your device:<br />
# mtp-connect<br />
<br />
If connection is successful, there are several switch options to use in conjunction with ''mtp-connect'' to access data on the device. You might want to use some stand alone commands:<br />
mtp-albumart mtp-emptyfolders mtp-getplaylist mtp-reset mtp-trexist<br />
mtp-albums mtp-files mtp-hotplug mtp-sendfile<br />
mtp-connect mtp-folders mtp-newfolder mtp-sendtr<br />
mtp-delfile mtp-format mtp-newplaylist mtp-thumb<br />
mtp-detect mtp-getfile mtp-playlists mtp-tracks<br />
{{Warning | Some commands may be harmful to your MTP device!}}<br />
<br />
=== mtpfs ===<br />
<br />
{{Note | The following is likely to not work and you might have to resort to [[Digital_Cameras#libgphoto2|gphoto2]] or a file manager with gvfs support like [[PCManFM]]. }}<br />
<br />
First edit your {{ic|/etc/fuse.conf}} and uncomment the following line:<br />
user_allow_other<br />
<br />
Mount your device on {{ic|~/mnt}}:<br />
$ mtpfs -o allow_other ~/mnt<br />
<br />
Unmount device mounted on {{ic|~/mnt}}:<br />
<br />
$ fusermount -u ~/mnt<br />
<br />
=== jmtpfs ===<br />
<br />
Mount device on {{ic|~/mnt}}:<br />
<br />
$ jmtpfs ~/mnt<br />
<br />
Unmount device mounted on {{ic|~/mnt}}:<br />
<br />
$ fusermount -u ~/mnt<br />
<br />
=== go-mtpfs ===<br />
<br />
{{Note|Mounting with {{ic|go-mtpfs}} might fail if an external SD Card is present. If you try to access your device while having an SD card and go-mtpfs complains, try removing the SD card and mounting again.}}<br />
<br />
Install {{Pkg|android-udev}}, which will allow you to edit {{ic|/etc/udev/rules.d/51-android.rules}} and apply to your {{ic|idVendor}} and {{ic|idProduct}}, which you can see after running ''mtp-detect''. To the end of the line, add your user {{ic|<nowiki>OWNER="<user>"</nowiki>}}. First, create the {{ic|fuse}} group if it doesn't exist:<br />
<br />
# groupadd fuse<br />
<br />
Add yourself to the {{ic|fuse}} group:<br />
<br />
# gpasswd -a <user> fuse<br />
<br />
Reboot might be required.<br />
<br />
Mount device on {{ic|~/mnt}}:<br />
<br />
$ go-mtpfs ~/mnt<br />
<br />
Unmount device mounted on {{ic|~/mnt}}:<br />
<br />
$ fusermount -u ~/mnt<br />
<br />
=== simple-mtpfs ===<br />
<br />
List MTP devices:<br />
<br />
$ simple-mtpfs --list-devices<br />
<br />
Mount your device on {{ic|~/mnt}}:<br />
<br />
$ simple-mtpfs ~/mnt<br />
<br />
Unmount device mounted on {{ic|~/mnt}}:<br />
<br />
$ fusermount -u ~/mnt<br />
<br />
=== Android File Transfer ===<br />
<br />
;FUSE interface<br />
<br />
$ mkdir ~/my-device<br />
$ ./aft-mtp-mount ~/my-device<br />
<br />
If you want album art to be displayed, it must be named {{ic|albumart.xxx}} and placed first in the destination folder. Then copy other files. Also, note that fuse could be 7-8 times slower than ui/cli file transfer.<br />
<br />
;Qt user interface<br />
<br />
Start the application, choose a destination folder and click any button on the toolbar. Available options are: ''Upload Album'', ''Upload Directory'' and ''Upload Files''. The latter two are self-explanatory. ''Upload album'' searches the source directory for album covers, and sets the best available cover.<br />
<br />
=== Media players ===<br />
<br />
You can also use your MTP device in music players such as Amarok. To achieve this, you might have to edit {{ic|/etc/udev/rules.d/51-android.rules}} (the MTP device used in the following example is a Galaxy Nexus). <br />
Run:<br />
<br />
$ lsusb<br />
<br />
Search for your device. It should be something like that:<br />
Bus 003 Device 011: ID 04e8:6860 Samsung Electronics Co., Ltd GT-I9100 Phone [Galaxy S II], GT-P7500 [Galaxy Tab 10.1]<br />
<br />
And entry to {{ic|/etc/udev/rules.d/51-android.rules}} will be this:<br />
SUBSYSTEM=="usb", ATTR{idVendor}=="04e8", ATTR{idProduct}=="6860", MODE="0666", OWNER="[username]"<br />
<br />
Also reload udev rules:<br />
# udevadm control --reload<br />
<br />
== Troubleshooting ==<br />
<br />
=== libmtp ===<br />
<br />
==== Unknown device ====<br />
<br />
If you see a message like:<br />
<br />
Device 0 (VID=XXXX and PID=XXXX) is UNKNOWN.<br />
Please report this VID/PID and the device model to the libmtp development team<br />
<br />
You should check whether your device is listed in the [http://sourceforge.net/p/libmtp/code/ci/HEAD/tree/src/music-players.h supported devices list]. If it is not, you should report it to the developers team. If it is, your {{ic|libmtp}} might be slightly outdated. To allow it to be properly used by {{ic|libmtp}}, you can add your device to:<br />
<br />
/etc/udev/rules.d/69-libmtp.rules<br />
<br />
==== Unable to enumerate USB device ====<br />
<br />
{{Merge||Unrelated to MTP, perhaps suited for [[USB storage devices]]}}<br />
<br />
If you see a message like this in system log ({{ic|journalctl}})<br />
<br />
usb usb4-port2: unable to enumerate USB device<br />
<br />
You can try following temporary [https://bbs.archlinux.org/viewtopic.php?pid=1087323#p1087323 workaround]<br />
<br />
# modprobe -vr uhci_hcd<br />
# modprobe -va ohci_hcd<br />
# modprobe -va uhci_hcd<br />
<br />
If it works you should create {{ic|/etc/modprobe.d/usb_hci_order.conf}} with following content<br />
<br />
# create a dependency on ohci for uhci, which fixes problems<br />
# with external usb devices not showing up<br />
#<br />
softdep uhci_hcd pre: ohci_hcd<br />
<br />
=== jmtpfs ===<br />
<br />
{{Accuracy|no bug report}}<br />
<br />
==== Input/output error upon first access ====<br />
<br />
Symptoms: jmtpfs successfully mounts, but as soon as one attempts to access files on the device (e.g. via {{ic|ls}}), an error is reported:<br />
<br />
cannot access <mount-point>: Input/output error<br />
<br />
This appears to be a security feature: MTP does not work when the phone is locked by the lockscreen. Unlock the phone and then remount the device.<br />
<br />
=== gvfs-mtp ===<br />
<br />
{{Merge|udev}}<br />
<br />
If you have installed the {{Pkg|gvfs-mtp}} package, and your device doesn't show up in the file manager, you might need to reboot or write a udev rule in order to auto-mount the device.<br />
<br />
Plug your device and get the vendor-id and product-id,respectively:<br />
<br />
$ lsusb<br />
Bus 001 Device 007: ID 0421:0661 Nokia Mobile Phones Lumia 920<br />
(...)<br />
<br />
The two numbers after ID are ''vendorId'' : ''productID''<br />
<br />
Then make a udev rule, e.g.<br />
<br />
# nano /etc/udev/rules.d/51-android.rules<br />
<br />
and type this rule:<br />
<br />
ATTR{idVendor}=="YOUR VENDOR ID HERE", ATTR{idProduct}=="YOUR PRODUCT ID HERE", SYMLINK+="libmtp", MODE="660", ENV{ID_MTP_DEVICE}="1"<br />
<br />
Reload the udev rules.<br />
<br />
# udevadm control --reload<br />
<br />
And reboot the system. Now file managers (like Thunar) should be able to automount the MTP Device. [https://bbs.archlinux.org/viewtopic.php?id=180719]<br />
<br />
=== kio-mtp ===<br />
<br />
If you are not able to use the action "Open with File Manager", you may work around this problem by editing the file {{ic|/usr/share/apps/solid/actions/solid_mtp.desktop}}.<br />
<br />
Change the line<br />
<br />
Exec=kioclient exec mtp:udi=%i/<br />
<br />
To<br />
<br />
Exec=dolphin "mtp:/"</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Software_access_point&diff=407518Software access point2015-10-30T13:48:26Z<p>Fylwind: /* Wi-Fi Link Layer */ also stop netctl-auto</p>
<hr />
<div>[[Category:Wireless networking]]<br />
[[ja:ソフトウェアアクセスポイント]]<br />
[[ru:Software access point]]<br />
[[zh-CN:Software access point]]<br />
{{Related articles start}}<br />
{{Related|Network configuration}}<br />
{{Related|Wireless network configuration}}<br />
{{Related|Ad-hoc networking}}<br />
{{Related|Internet sharing}}<br />
{{Related articles end}}<br />
A software access point is used when you want your computer to act as a Wi-Fi access point for the local network. It saves you the trouble of getting a separate wireless router.<br />
<br />
== Requirements ==<br />
<br />
=== Wi-Fi device must support AP mode ===<br />
<br />
You need a [http://wireless.kernel.org/en/developers/Documentation/nl80211 nl80211] compatible wireless device, which supports the AP [http://wireless.kernel.org/en/users/Documentation/modes operating mode]. This can be verified by running {{ic|iw list}} command, under the {{ic|Supported interface modes}} block there should be {{ic|AP}} listed:<br />
<br />
{{hc|$ iw list|<br />
Wiphy phy1<br />
...<br />
Supported interface modes:<br />
* IBSS<br />
* managed<br />
* '''AP'''<br />
* AP/VLAN<br />
* WDS<br />
* monitor<br />
* mesh point<br />
...<br />
}}<br />
<br />
=== Wireless client and software AP with a single Wi-Fi device ===<br />
<br />
Creating a software AP is independent from your own network connection (Ethernet, wireless, ...). Many wireless devices even support ''simultaneous'' operation both as AP and as wireless "client" at the same time. Using that capability you can create a software AP acting as a "wireless repeater" for an existing network, using a single wireless device. The capability is listed in the following section in the output of {{ic|iw list}}:<br />
<br />
{{hc|1=$ iw list|2=<br />
Wiphy phy1<br />
...<br />
valid interface combinations:<br />
* #{ managed } <= 2048, #{ AP, mesh point } <= 8, #{ P2P-client, P2P-GO } <= 1,<br />
total <= 2048, #channels <= 1, STA/AP BI must match<br />
...<br />
}}<br />
The constraint {{ic|1=#channels <= 1}} means that your software AP must operate on the same channel as your Wi-Fi client connection; see the {{ic|channel}} setting in {{ic|hostapd.conf}} below.<br />
<br />
If you want to use the capability/feature, perhaps because an Ethernet connection is not available, you need to create two separate ''virtual interfaces'' for using it. <br />
Virtual interfaces for a physical device {{ic|wlan0}} can be created as follows: <br />
First, the ''virtual interfaces'' are created for the network connection ({{ic|wlan0_sta}}) itself and for the software AP/hostapd "wireless repeater":<br />
<br />
# iw dev wlan0 interface add wlan0_sta type station <br />
# iw dev wlan0 interface add wlan0_ap type __ap <br />
Second, the interfaces are assigned separate MAC addresses (use custom unique addresses): <br />
# ip link set dev wlan0_sta address 12:34:56:78:ab:cd<br />
# ip link set dev wlan0_ap address 12:34:56:78:ab:ce<br />
<br />
== Overview ==<br />
<br />
Setting up an access point comprises two main parts:<br />
* Setting up the '''Wi-Fi link layer''', so that wireless clients can associate to your computer's "software access point" and send/receive IP packets from/to your computer; this is what the hostapd package will do for you.<br />
* Setting up the '''network configuration''' on you computer, so that your computer will properly relay IP packets from/to its own Internet connection from/to wireless clients.<br />
<br />
== Wi-Fi Link Layer ==<br />
<br />
The actual Wi-Fi link is established via the {{Pkg|hostapd}} package (available in the [[official repositories]]). The package has WPA2 support.<br />
<br />
Adjust the options in ''hostapd'' configuration file if necessary. Especially, change the {{ic|ssid}} and the {{ic|wpa_passphrase}}. See [http://wireless.kernel.org/en/users/Documentation/hostapd hostapd Linux documentation page] for more information.<br />
<br />
{{hc|/etc/hostapd/hostapd.conf|<nowiki><br />
ssid=YourWiFiName<br />
wpa_passphrase=Somepassphrase<br />
interface=wlan0_ap<br />
bridge=br0<br />
auth_algs=3<br />
channel=7<br />
driver=nl80211<br />
hw_mode=g<br />
logger_stdout=-1<br />
logger_stdout_level=2<br />
max_num_sta=5<br />
rsn_pairwise=CCMP<br />
wpa=2<br />
wpa_key_mgmt=WPA-PSK<br />
wpa_pairwise=TKIP CCMP<br />
</nowiki>}}<br />
<br />
Before starting hostapd, make sure netctl-auto is stopped for the wireless network interface and that the interface is brought up:<br />
<br />
# systemctl stop netctl-auto@wlan0_ap<br />
# ip link set dev wlan0_ap up<br />
<br />
Otherwise, hostapd will fail with a nondescript error: "could not configure driver mode".<br />
<br />
For automatically starting hostapd, [[Daemon|enable]] the {{ic|hostapd.service}}.<br />
{{Warning|The wireless channels allowed for access point operation differ according to geography. Depending on the wireless firmware, you may have to set the region correctly to use legal channels. '''Do not''' choose another region, as you may be illegally disturbing network traffic, affecting wireless functionality of your own device and others within its reach! To set the region see [[Wireless network configuration#Respecting the regulatory domain]].}} <br />
<br />
{{Note|If you have a card based on RTL8192CU chipset, install {{AUR|hostapd-8192cu}}{{Broken package link|{{aur-mirror|hostapd-8192cu}}}} in the [[AUR]] and replace {{ic|1=driver=nl80211}} with {{ic|1=driver=rtl871xdrv}} in the {{ic|hostapd.conf}} file.}}<br />
<br />
== Network configuration ==<br />
<br />
There are two basic ways for implementing this:<br />
# '''bridge''': create a network ''bridge'' on your computer (wireless clients will appear to access the same network interface and the same subnet that's used by your computer)<br />
# '''NAT''': with IP forwarding/masquerading and DHCP service (wireless clients will use a dedicated subnet, data from/to that subnet is NAT-ted -- similar to a normal Wi-Fi router that's connected to your DSL or cable modem)<br />
<br />
The bridge approach is simpler, but it requires that any service that's needed by your wireless clients (like, DHCP) is available on your computers external interface. That means it will not work if you have a dial-up connection (e.g., via PPPoE or a 3G modem) or if you're using a cable modem that will supply exactly one IP address to you via DHCP.<br />
<br />
The NAT approach is more versatile, as it clearly separates Wi-Fi clients from your computer and it's completely transparent to the outside world. It will work with any kind of network connection, and (if needed) you can introduce traffic policies using the usual iptables approach.<br />
<br />
Of course, it is possible to ''combine both things''. For that, studying both articles would be necessary. Example: Like having a bridge that contains both an ethernet device and the wireless device with an static ip, offering DHCP and setting NAT configured to relay the traffic to an additional network device - that can be ppp or eth.<br />
<br />
=== Bridge Setup ===<br />
<br />
You need to create a network ''bridge'' and add your network interface (e.g. {{ic|eth0}}) to it. You '''should not''' add the wireless device (e.g. {{ic|wlan0}}) to the bridge; hostapd will add it on its own.<br />
<br />
See [[Network bridge]].<br />
<br />
{{Tip|You may wish to reuse an existing bridge, if you have one (e.g. used by a virtual machine).}}<br />
<br />
=== NAT Setup ===<br />
<br />
See [[Internet sharing]] for details.<br />
<br />
On that article, the device connected to the LAN is {{ic|net0}}. That device would be in this case your wireless device (e.g. {{ic|wlan0}}).<br />
<br />
== Tools ==<br />
<br />
=== create_ap ===<br />
<br />
The [https://bbs.archlinux.org/viewtopic.php?pid=1269258 create_ap] script combines {{Pkg|hostapd}}, [[dnsmasq]] and [[iptables]] to create a Bridged/NATed Access Point (available in the [[AUR]] {{Aur|create_ap}}).<br />
<br />
=== RADIUS ===<br />
<br />
See [https://me.m01.eu/blog/2012/05/wpa-2-enterprise-from-scratch-on-a-raspberry-pi/] for instructions to run a [http://freeradius.org/ FreeRADIUS] server for [[WPA2 Enterprise]].<br />
<br />
== Troubleshooting ==<br />
<br />
===WLAN is very slow===<br />
<br />
This could be caused by low entropy. Consider installing [[haveged]].<br />
<br />
===NetworkManager is interfering===<br />
<br />
hostapd may not work, if the device is managed by NetworkManager. You can mask the device:<br />
<br />
{{hc|/etc/NetworkManager/NetworkManager.conf|<nowiki><br />
[keyfile]<br />
unmanaged-devices=mac:<hwaddr><br />
</nowiki>}}<br />
<br />
== See also ==<br />
<br />
* [[Router]]<br />
* [http://nims11.wordpress.com/2012/04/27/hostapd-the-linux-way-to-create-virtual-wifi-access-point/ Hostapd : The Linux Way to create Virtual Wi-Fi Access Point]<br />
* [http://xyne.archlinux.ca/notes/network/dhcp_with_dns.html tutorial and script for configuring a subnet with DHCP and DNS]</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Software_access_point&diff=407165Software access point2015-10-28T03:20:30Z<p>Fylwind: add error example if wlan is not brought up</p>
<hr />
<div>[[Category:Wireless networking]]<br />
[[ja:ソフトウェアアクセスポイント]]<br />
[[ru:Software access point]]<br />
[[zh-CN:Software access point]]<br />
{{Related articles start}}<br />
{{Related|Network configuration}}<br />
{{Related|Wireless network configuration}}<br />
{{Related|Ad-hoc networking}}<br />
{{Related|Internet sharing}}<br />
{{Related articles end}}<br />
A software access point is used when you want your computer to act as a Wi-Fi access point for the local network. It saves you the trouble of getting a separate wireless router.<br />
<br />
== Requirements ==<br />
<br />
=== Wi-Fi device must support AP mode ===<br />
<br />
You need a [http://wireless.kernel.org/en/developers/Documentation/nl80211 nl80211] compatible wireless device, which supports the AP [http://wireless.kernel.org/en/users/Documentation/modes operating mode]. This can be verified by running {{ic|iw list}} command, under the {{ic|Supported interface modes}} block there should be {{ic|AP}} listed:<br />
<br />
{{hc|$ iw list|<br />
Wiphy phy1<br />
...<br />
Supported interface modes:<br />
* IBSS<br />
* managed<br />
* '''AP'''<br />
* AP/VLAN<br />
* WDS<br />
* monitor<br />
* mesh point<br />
...<br />
}}<br />
<br />
=== Wireless client and software AP with a single Wi-Fi device ===<br />
<br />
Creating a software AP is independent from your own network connection (Ethernet, wireless, ...). Many wireless devices even support ''simultaneous'' operation both as AP and as wireless "client" at the same time. Using that capability you can create a software AP acting as a "wireless repeater" for an existing network, using a single wireless device. The capability is listed in the following section in the output of {{ic|iw list}}:<br />
<br />
{{hc|1=$ iw list|2=<br />
Wiphy phy1<br />
...<br />
valid interface combinations:<br />
* #{ managed } <= 2048, #{ AP, mesh point } <= 8, #{ P2P-client, P2P-GO } <= 1,<br />
total <= 2048, #channels <= 1, STA/AP BI must match<br />
...<br />
}}<br />
The constraint {{ic|1=#channels <= 1}} means that your software AP must operate on the same channel as your Wi-Fi client connection; see the {{ic|channel}} setting in {{ic|hostapd.conf}} below.<br />
<br />
If you want to use the capability/feature, perhaps because an Ethernet connection is not available, you need to create two separate ''virtual interfaces'' for using it. <br />
Virtual interfaces for a physical device {{ic|wlan0}} can be created as follows: <br />
First, the ''virtual interfaces'' are created for the network connection ({{ic|wlan0_sta}}) itself and for the software AP/hostapd "wireless repeater":<br />
<br />
# iw dev wlan0 interface add wlan0_sta type station <br />
# iw dev wlan0 interface add wlan0_ap type __ap <br />
Second, the interfaces are assigned separate MAC addresses (use custom unique addresses): <br />
# ip link set dev wlan0_sta address 12:34:56:78:ab:cd<br />
# ip link set dev wlan0_ap address 12:34:56:78:ab:ce<br />
<br />
== Overview ==<br />
<br />
Setting up an access point comprises two main parts:<br />
* Setting up the '''Wi-Fi link layer''', so that wireless clients can associate to your computer's "software access point" and send/receive IP packets from/to your computer; this is what the hostapd package will do for you.<br />
* Setting up the '''network configuration''' on you computer, so that your computer will properly relay IP packets from/to its own Internet connection from/to wireless clients.<br />
<br />
== Wi-Fi Link Layer ==<br />
<br />
The actual Wi-Fi link is established via the {{Pkg|hostapd}} package (available in the [[official repositories]]). The package has WPA2 support.<br />
<br />
Adjust the options in ''hostapd'' configuration file if necessary. Especially, change the {{ic|ssid}} and the {{ic|wpa_passphrase}}. See [http://wireless.kernel.org/en/users/Documentation/hostapd hostapd Linux documentation page] for more information.<br />
<br />
{{hc|/etc/hostapd/hostapd.conf|<nowiki><br />
ssid=YourWiFiName<br />
wpa_passphrase=Somepassphrase<br />
interface=wlan0_ap<br />
bridge=br0<br />
auth_algs=3<br />
channel=7<br />
driver=nl80211<br />
hw_mode=g<br />
logger_stdout=-1<br />
logger_stdout_level=2<br />
max_num_sta=5<br />
rsn_pairwise=CCMP<br />
wpa=2<br />
wpa_key_mgmt=WPA-PSK<br />
wpa_pairwise=TKIP CCMP<br />
</nowiki>}}<br />
<br />
When starting hostapd, make sure the wireless network interface is brought up first:<br />
<br />
# ip link set dev wlan0_ap up<br />
<br />
Otherwise, it will fail with a nondescript error: "could not configure driver mode".<br />
<br />
For automatically starting hostapd, [[Daemon|enable]] the {{ic|hostapd.service}}.<br />
{{Warning|The wireless channels allowed for access point operation differ according to geography. Depending on the wireless firmware, you may have to set the region correctly to use legal channels. '''Do not''' choose another region, as you may be illegally disturbing network traffic, affecting wireless functionality of your own device and others within its reach! To set the region see [[Wireless network configuration#Respecting the regulatory domain]].}} <br />
<br />
{{Note|If you have a card based on RTL8192CU chipset, install {{AUR|hostapd-8192cu}}{{Broken package link|{{aur-mirror|hostapd-8192cu}}}} in the [[AUR]] and replace {{ic|1=driver=nl80211}} with {{ic|1=driver=rtl871xdrv}} in the {{ic|hostapd.conf}} file.}}<br />
<br />
== Network configuration ==<br />
<br />
There are two basic ways for implementing this:<br />
# '''bridge''': create a network ''bridge'' on your computer (wireless clients will appear to access the same network interface and the same subnet that's used by your computer)<br />
# '''NAT''': with IP forwarding/masquerading and DHCP service (wireless clients will use a dedicated subnet, data from/to that subnet is NAT-ted -- similar to a normal Wi-Fi router that's connected to your DSL or cable modem)<br />
<br />
The bridge approach is simpler, but it requires that any service that's needed by your wireless clients (like, DHCP) is available on your computers external interface. That means it will not work if you have a dial-up connection (e.g., via PPPoE or a 3G modem) or if you're using a cable modem that will supply exactly one IP address to you via DHCP.<br />
<br />
The NAT approach is more versatile, as it clearly separates Wi-Fi clients from your computer and it's completely transparent to the outside world. It will work with any kind of network connection, and (if needed) you can introduce traffic policies using the usual iptables approach.<br />
<br />
Of course, it is possible to ''combine both things''. For that, studying both articles would be necessary. Example: Like having a bridge that contains both an ethernet device and the wireless device with an static ip, offering DHCP and setting NAT configured to relay the traffic to an additional network device - that can be ppp or eth.<br />
<br />
=== Bridge Setup ===<br />
<br />
You need to create a network ''bridge'' and add your network interface (e.g. {{ic|eth0}}) to it. You '''should not''' add the wireless device (e.g. {{ic|wlan0}}) to the bridge; hostapd will add it on its own.<br />
<br />
See [[Network bridge]].<br />
<br />
{{Tip|You may wish to reuse an existing bridge, if you have one (e.g. used by a virtual machine).}}<br />
<br />
=== NAT Setup ===<br />
<br />
See [[Internet sharing]] for details.<br />
<br />
On that article, the device connected to the LAN is {{ic|net0}}. That device would be in this case your wireless device (e.g. {{ic|wlan0}}).<br />
<br />
== Tools ==<br />
<br />
=== create_ap ===<br />
<br />
The [https://bbs.archlinux.org/viewtopic.php?pid=1269258 create_ap] script combines {{Pkg|hostapd}}, [[dnsmasq]] and [[iptables]] to create a Bridged/NATed Access Point (available in the [[AUR]] {{Aur|create_ap}}).<br />
<br />
=== RADIUS ===<br />
<br />
See [https://me.m01.eu/blog/2012/05/wpa-2-enterprise-from-scratch-on-a-raspberry-pi/] for instructions to run a [http://freeradius.org/ FreeRADIUS] server for [[WPA2 Enterprise]].<br />
<br />
== Troubleshooting ==<br />
<br />
===WLAN is very slow===<br />
<br />
This could be caused by low entropy. Consider installing [[haveged]].<br />
<br />
===NetworkManager is interfering===<br />
<br />
hostapd may not work, if the device is managed by NetworkManager. You can mask the device:<br />
<br />
{{hc|/etc/NetworkManager/NetworkManager.conf|<nowiki><br />
[keyfile]<br />
unmanaged-devices=mac:<hwaddr><br />
</nowiki>}}<br />
<br />
== See also ==<br />
<br />
* [[Router]]<br />
* [http://nims11.wordpress.com/2012/04/27/hostapd-the-linux-way-to-create-virtual-wifi-access-point/ Hostapd : The Linux Way to create Virtual Wi-Fi Access Point]<br />
* [http://xyne.archlinux.ca/notes/network/dhcp_with_dns.html tutorial and script for configuring a subnet with DHCP and DNS]</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Software_access_point&diff=407164Software access point2015-10-28T03:18:16Z<p>Fylwind: /* Wi-Fi Link Layer */ make sure wlan is brought up first</p>
<hr />
<div>[[Category:Wireless networking]]<br />
[[ja:ソフトウェアアクセスポイント]]<br />
[[ru:Software access point]]<br />
[[zh-CN:Software access point]]<br />
{{Related articles start}}<br />
{{Related|Network configuration}}<br />
{{Related|Wireless network configuration}}<br />
{{Related|Ad-hoc networking}}<br />
{{Related|Internet sharing}}<br />
{{Related articles end}}<br />
A software access point is used when you want your computer to act as a Wi-Fi access point for the local network. It saves you the trouble of getting a separate wireless router.<br />
<br />
== Requirements ==<br />
<br />
=== Wi-Fi device must support AP mode ===<br />
<br />
You need a [http://wireless.kernel.org/en/developers/Documentation/nl80211 nl80211] compatible wireless device, which supports the AP [http://wireless.kernel.org/en/users/Documentation/modes operating mode]. This can be verified by running {{ic|iw list}} command, under the {{ic|Supported interface modes}} block there should be {{ic|AP}} listed:<br />
<br />
{{hc|$ iw list|<br />
Wiphy phy1<br />
...<br />
Supported interface modes:<br />
* IBSS<br />
* managed<br />
* '''AP'''<br />
* AP/VLAN<br />
* WDS<br />
* monitor<br />
* mesh point<br />
...<br />
}}<br />
<br />
=== Wireless client and software AP with a single Wi-Fi device ===<br />
<br />
Creating a software AP is independent from your own network connection (Ethernet, wireless, ...). Many wireless devices even support ''simultaneous'' operation both as AP and as wireless "client" at the same time. Using that capability you can create a software AP acting as a "wireless repeater" for an existing network, using a single wireless device. The capability is listed in the following section in the output of {{ic|iw list}}:<br />
<br />
{{hc|1=$ iw list|2=<br />
Wiphy phy1<br />
...<br />
valid interface combinations:<br />
* #{ managed } <= 2048, #{ AP, mesh point } <= 8, #{ P2P-client, P2P-GO } <= 1,<br />
total <= 2048, #channels <= 1, STA/AP BI must match<br />
...<br />
}}<br />
The constraint {{ic|1=#channels <= 1}} means that your software AP must operate on the same channel as your Wi-Fi client connection; see the {{ic|channel}} setting in {{ic|hostapd.conf}} below.<br />
<br />
If you want to use the capability/feature, perhaps because an Ethernet connection is not available, you need to create two separate ''virtual interfaces'' for using it. <br />
Virtual interfaces for a physical device {{ic|wlan0}} can be created as follows: <br />
First, the ''virtual interfaces'' are created for the network connection ({{ic|wlan0_sta}}) itself and for the software AP/hostapd "wireless repeater":<br />
<br />
# iw dev wlan0 interface add wlan0_sta type station <br />
# iw dev wlan0 interface add wlan0_ap type __ap <br />
Second, the interfaces are assigned separate MAC addresses (use custom unique addresses): <br />
# ip link set dev wlan0_sta address 12:34:56:78:ab:cd<br />
# ip link set dev wlan0_ap address 12:34:56:78:ab:ce<br />
<br />
== Overview ==<br />
<br />
Setting up an access point comprises two main parts:<br />
* Setting up the '''Wi-Fi link layer''', so that wireless clients can associate to your computer's "software access point" and send/receive IP packets from/to your computer; this is what the hostapd package will do for you.<br />
* Setting up the '''network configuration''' on you computer, so that your computer will properly relay IP packets from/to its own Internet connection from/to wireless clients.<br />
<br />
== Wi-Fi Link Layer ==<br />
<br />
The actual Wi-Fi link is established via the {{Pkg|hostapd}} package (available in the [[official repositories]]). The package has WPA2 support.<br />
<br />
Adjust the options in ''hostapd'' configuration file if necessary. Especially, change the {{ic|ssid}} and the {{ic|wpa_passphrase}}. See [http://wireless.kernel.org/en/users/Documentation/hostapd hostapd Linux documentation page] for more information.<br />
<br />
{{hc|/etc/hostapd/hostapd.conf|<nowiki><br />
ssid=YourWiFiName<br />
wpa_passphrase=Somepassphrase<br />
interface=wlan0_ap<br />
bridge=br0<br />
auth_algs=3<br />
channel=7<br />
driver=nl80211<br />
hw_mode=g<br />
logger_stdout=-1<br />
logger_stdout_level=2<br />
max_num_sta=5<br />
rsn_pairwise=CCMP<br />
wpa=2<br />
wpa_key_mgmt=WPA-PSK<br />
wpa_pairwise=TKIP CCMP<br />
</nowiki>}}<br />
<br />
When starting hostapd, make sure the wireless network interface is brought up first:<br />
<br />
# ip link set dev wlan0_ap up<br />
<br />
For automatically starting hostapd, [[Daemon|enable]] the {{ic|hostapd.service}}.<br />
{{Warning|The wireless channels allowed for access point operation differ according to geography. Depending on the wireless firmware, you may have to set the region correctly to use legal channels. '''Do not''' choose another region, as you may be illegally disturbing network traffic, affecting wireless functionality of your own device and others within its reach! To set the region see [[Wireless network configuration#Respecting the regulatory domain]].}} <br />
<br />
{{Note|If you have a card based on RTL8192CU chipset, install {{AUR|hostapd-8192cu}}{{Broken package link|{{aur-mirror|hostapd-8192cu}}}} in the [[AUR]] and replace {{ic|1=driver=nl80211}} with {{ic|1=driver=rtl871xdrv}} in the {{ic|hostapd.conf}} file.}}<br />
<br />
== Network configuration ==<br />
<br />
There are two basic ways for implementing this:<br />
# '''bridge''': create a network ''bridge'' on your computer (wireless clients will appear to access the same network interface and the same subnet that's used by your computer)<br />
# '''NAT''': with IP forwarding/masquerading and DHCP service (wireless clients will use a dedicated subnet, data from/to that subnet is NAT-ted -- similar to a normal Wi-Fi router that's connected to your DSL or cable modem)<br />
<br />
The bridge approach is simpler, but it requires that any service that's needed by your wireless clients (like, DHCP) is available on your computers external interface. That means it will not work if you have a dial-up connection (e.g., via PPPoE or a 3G modem) or if you're using a cable modem that will supply exactly one IP address to you via DHCP.<br />
<br />
The NAT approach is more versatile, as it clearly separates Wi-Fi clients from your computer and it's completely transparent to the outside world. It will work with any kind of network connection, and (if needed) you can introduce traffic policies using the usual iptables approach.<br />
<br />
Of course, it is possible to ''combine both things''. For that, studying both articles would be necessary. Example: Like having a bridge that contains both an ethernet device and the wireless device with an static ip, offering DHCP and setting NAT configured to relay the traffic to an additional network device - that can be ppp or eth.<br />
<br />
=== Bridge Setup ===<br />
<br />
You need to create a network ''bridge'' and add your network interface (e.g. {{ic|eth0}}) to it. You '''should not''' add the wireless device (e.g. {{ic|wlan0}}) to the bridge; hostapd will add it on its own.<br />
<br />
See [[Network bridge]].<br />
<br />
{{Tip|You may wish to reuse an existing bridge, if you have one (e.g. used by a virtual machine).}}<br />
<br />
=== NAT Setup ===<br />
<br />
See [[Internet sharing]] for details.<br />
<br />
On that article, the device connected to the LAN is {{ic|net0}}. That device would be in this case your wireless device (e.g. {{ic|wlan0}}).<br />
<br />
== Tools ==<br />
<br />
=== create_ap ===<br />
<br />
The [https://bbs.archlinux.org/viewtopic.php?pid=1269258 create_ap] script combines {{Pkg|hostapd}}, [[dnsmasq]] and [[iptables]] to create a Bridged/NATed Access Point (available in the [[AUR]] {{Aur|create_ap}}).<br />
<br />
=== RADIUS ===<br />
<br />
See [https://me.m01.eu/blog/2012/05/wpa-2-enterprise-from-scratch-on-a-raspberry-pi/] for instructions to run a [http://freeradius.org/ FreeRADIUS] server for [[WPA2 Enterprise]].<br />
<br />
== Troubleshooting ==<br />
<br />
===WLAN is very slow===<br />
<br />
This could be caused by low entropy. Consider installing [[haveged]].<br />
<br />
===NetworkManager is interfering===<br />
<br />
hostapd may not work, if the device is managed by NetworkManager. You can mask the device:<br />
<br />
{{hc|/etc/NetworkManager/NetworkManager.conf|<nowiki><br />
[keyfile]<br />
unmanaged-devices=mac:<hwaddr><br />
</nowiki>}}<br />
<br />
== See also ==<br />
<br />
* [[Router]]<br />
* [http://nims11.wordpress.com/2012/04/27/hostapd-the-linux-way-to-create-virtual-wifi-access-point/ Hostapd : The Linux Way to create Virtual Wi-Fi Access Point]<br />
* [http://xyne.archlinux.ca/notes/network/dhcp_with_dns.html tutorial and script for configuring a subnet with DHCP and DNS]</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Media_Transfer_Protocol&diff=406973Media Transfer Protocol2015-10-26T07:30:37Z<p>Fylwind: weird problem when using jmtpfs with on certain hardware</p>
<hr />
<div>[[Category:Storage]]<br />
[[Category:Mobile devices]]<br />
[[ja:MTP]]<br />
[[ru:MTP]]<br />
[[zh-CN:MTP]]<br />
{{Related articles start}}<br />
{{Related|USB storage devices}}<br />
{{Related articles end}}<br />
[[Wikipedia:Media_Transfer_Protocol|MTP]], or the ''Media Transfer Protocol'', is a USB device class which is used by many mobile phones (e.g. Samsung Galaxy S4) and media players (e.g. Creative Zen).<br />
<br />
== Installation ==<br />
<br />
=== Functionality ===<br />
<br />
Linux MTP support is provided by [[installing]] the {{Pkg|libmtp}} package. It can be installed on its own and used to access devices. However, a number of packages are available that use it as a dependency and add additional convenience (e.g. filemanager) functionalities and compatibility with particular device types - which includes improving transfer access speeds. <br />
<br />
These packages to choose from all implement a [[Wikipedia:Filesystem in Userspace]]: <br />
<br />
* {{Pkg|mtpfs}}<br />
* {{AUR|jmtpfs}} - is reported to work well for newer Android 4+ devices <br />
* {{AUR|go-mtpfs-git}} - is reported to work well for newer Android 3+ devices <br />
* {{AUR|simple-mtpfs}}<br />
* {{AUR|android-file-transfer}} - MTP client with minimalistic UI<br />
<br />
All of them aim at better functionality and performance over {{ic|libmtp}}. Since there are a lot of different USB devices, you might want to research first which one looks most suitable for yours. <br />
<br />
{{Tip|It is recommended to reboot your computer after installing MTP related packages.}}<br />
<br />
=== Integration with file managers ===<br />
<br />
To view the contents of your Android device's storage via MTP in your file manager, install the corresponding plugin:<br />
<br />
* For file managers that use [[GVFS]] (GNOME Files), install {{Pkg|gvfs-mtp}} for MTP or {{Pkg|gvfs-gphoto2}} for PTP support.<br />
* For file managers that use KIO (KDE's Dolphin), install {{Pkg|kio-mtp}}{{Broken package link|{{aur-mirror|kio-mtp}}}} (PTP support is included by default).<br />
<br />
After installing the required package, the device should show up in the file manager automatically and be accessible via an URL, for example {{ic|mtp://[usb:002,013]/}}.<br />
<br />
== Usage ==<br />
<br />
It might be required to create a mount-point directory first. The directory {{ic|~/mnt}} is used as an example below. Also do not forget to unlock your phone's screen before connecting it to the computer.<br />
<br />
=== libmtp ===<br />
<br />
Detect your device:<br />
<br />
# mtp-detect<br />
<br />
If an error is returned, see [[#libmtp 2|troubleshooting libmtp]]. <br />
<br />
{{Note|Your regular user must be in the {{ic|uucp}} group.}}<br />
<br />
Connect to your device:<br />
# mtp-connect<br />
<br />
If connection is successful, there are several switch options to use in conjunction with ''mtp-connect'' to access data on the device. You might want to use some stand alone commands:<br />
mtp-albumart mtp-emptyfolders mtp-getplaylist mtp-reset mtp-trexist<br />
mtp-albums mtp-files mtp-hotplug mtp-sendfile<br />
mtp-connect mtp-folders mtp-newfolder mtp-sendtr<br />
mtp-delfile mtp-format mtp-newplaylist mtp-thumb<br />
mtp-detect mtp-getfile mtp-playlists mtp-tracks<br />
{{Warning | Some commands may be harmful to your MTP device!}}<br />
<br />
=== mtpfs ===<br />
<br />
{{Note | The following is likely to not work and you might have to resort to [[Digital_Cameras#libgphoto2|gphoto2]] or a file manager with gvfs support like [[PCManFM]]. }}<br />
<br />
First edit your {{ic|/etc/fuse.conf}} and uncomment the following line:<br />
user_allow_other<br />
<br />
Mount your device on {{ic|~/mnt}}:<br />
$ mtpfs -o allow_other ~/mnt<br />
<br />
Unmount device mounted on {{ic|~/mnt}}:<br />
<br />
$ fusermount -u ~/mnt<br />
<br />
=== jmtpfs ===<br />
<br />
Mount device on {{ic|~/mnt}}:<br />
<br />
$ jmtpfs ~/mnt<br />
<br />
Unmount device mounted on {{ic|~/mnt}}:<br />
<br />
$ fusermount -u ~/mnt<br />
<br />
=== go-mtpfs ===<br />
<br />
{{Note|Mounting with {{ic|go-mtpfs}} might fail if an external SD Card is present. If you try to access your device while having an SD card and go-mtpfs complains, try removing the SD card and mounting again.}}<br />
<br />
Install {{Pkg|android-udev}}, which will allow you to edit {{ic|/etc/udev/rules.d/51-android.rules}} and apply to your {{ic|idVendor}} and {{ic|idProduct}}, which you can see after running ''mtp-detect''. To the end of the line, add your user {{ic|<nowiki>OWNER="<user>"</nowiki>}}. First, create the {{ic|fuse}} group if it doesn't exist:<br />
<br />
# groupadd fuse<br />
<br />
Add yourself to the {{ic|fuse}} group:<br />
<br />
# gpasswd -a <user> fuse<br />
<br />
Reboot might be required.<br />
<br />
Mount device on {{ic|~/mnt}}:<br />
<br />
$ go-mtpfs ~/mnt<br />
<br />
Unmount device mounted on {{ic|~/mnt}}:<br />
<br />
$ fusermount -u ~/mnt<br />
<br />
=== simple-mtpfs ===<br />
<br />
List MTP devices:<br />
<br />
$ simple-mtpfs --list-devices<br />
<br />
Mount your device on {{ic|~/mnt}}:<br />
<br />
$ simple-mtpfs ~/mnt<br />
<br />
Unmount device mounted on {{ic|~/mnt}}:<br />
<br />
$ fusermount -u ~/mnt<br />
<br />
=== Android File Transfer ===<br />
<br />
;FUSE interface<br />
<br />
$ mkdir ~/my-device<br />
$ ./aft-mtp-mount ~/my-device<br />
<br />
If you want album art to be displayed, it must be named {{ic|albumart.xxx}} and placed first in the destination folder. Then copy other files. Also, note that fuse could be 7-8 times slower than ui/cli file transfer.<br />
<br />
;Qt user interface<br />
<br />
Start the application, choose a destination folder and click any button on the toolbar. Available options are: ''Upload Album'', ''Upload Directory'' and ''Upload Files''. The latter two are self-explanatory. ''Upload album'' searches the source directory for album covers, and sets the best available cover.<br />
<br />
=== Media players ===<br />
<br />
You can also use your MTP device in music players such as Amarok. To achieve this, you might have to edit {{ic|/etc/udev/rules.d/51-android.rules}} (the MTP device used in the following example is a Galaxy Nexus). <br />
Run:<br />
<br />
$ lsusb<br />
<br />
Search for your device. It should be something like that:<br />
Bus 003 Device 011: ID 04e8:6860 Samsung Electronics Co., Ltd GT-I9100 Phone [Galaxy S II], GT-P7500 [Galaxy Tab 10.1]<br />
<br />
And entry to {{ic|/etc/udev/rules.d/51-android.rules}} will be this:<br />
SUBSYSTEM=="usb", ATTR{idVendor}=="04e8", ATTR{idProduct}=="6860", MODE="0666", OWNER="[username]"<br />
<br />
Also reload udev rules:<br />
# udevadm control --reload<br />
<br />
== Troubleshooting ==<br />
<br />
=== libmtp ===<br />
<br />
==== Unknown device ====<br />
<br />
If you see a message like:<br />
<br />
Device 0 (VID=XXXX and PID=XXXX) is UNKNOWN.<br />
Please report this VID/PID and the device model to the libmtp development team<br />
<br />
You should check whether your device is listed in the [http://sourceforge.net/p/libmtp/code/ci/HEAD/tree/src/music-players.h supported devices list]. If it is not, you should report it to the developers team. If it is, your {{ic|libmtp}} might be slightly outdated. To allow it to be properly used by {{ic|libmtp}}, you can add your device to:<br />
<br />
/etc/udev/rules.d/69-libmtp.rules<br />
<br />
==== Unable to enumerate USB device ====<br />
<br />
{{Merge||Unrelated to MTP, perhaps suited for [[USB storage devices]]}}<br />
<br />
If you see a message like this in system log ({{ic|journalctl}})<br />
<br />
usb usb4-port2: unable to enumerate USB device<br />
<br />
You can try following temporary [https://bbs.archlinux.org/viewtopic.php?pid=1087323#p1087323 workaround]<br />
<br />
# modprobe -vr uhci_hcd<br />
# modprobe -va ohci_hcd<br />
# modprobe -va uhci_hcd<br />
<br />
If it works you should create {{ic|/etc/modprobe.d/usb_hci_order.conf}} with following content<br />
<br />
# create a dependency on ohci for uhci, which fixes problems<br />
# with external usb devices not showing up<br />
#<br />
softdep uhci_hcd pre: ohci_hcd<br />
<br />
<br />
=== jmtpfs ===<br />
<br />
==== Input/output error upon first access ====<br />
<br />
Symptoms: jmtpfs successfully mounts, but as soon as one attempts to access files on the device (e.g. via {{ic|ls}}), an error is reported:<br />
<br />
cannot access <mount-point>: Input/output error<br />
<br />
To work around this problem, try changing the USB connection type (in the phone's configuration interface) from MTP to PTP briefly, and then switch back to MTP. Then remount the device using jmtpfs and it should work properly this time. (The problem will reappear if the USB cord is disconnected and then reconnected.)<br />
<br />
=== gvfs-mtp ===<br />
<br />
{{Merge|udev}}<br />
<br />
If you have installed the {{Pkg|gvfs-mtp}} package, and your device doesn't show up in the file manager, you might need to reboot or write a udev rule in order to auto-mount the device.<br />
<br />
Plug your device and get the vendor-id and product-id,respectively:<br />
<br />
$ lsusb<br />
Bus 001 Device 007: ID 0421:0661 Nokia Mobile Phones Lumia 920<br />
(...)<br />
<br />
The two numbers after ID are ''vendorId'' : ''productID''<br />
<br />
Then make a udev rule, e.g.<br />
<br />
# nano /etc/udev/rules.d/51-android.rules<br />
<br />
and type this rule:<br />
<br />
ATTR{idVendor}=="YOUR VENDOR ID HERE", ATTR{idProduct}=="YOUR PRODUCT ID HERE", SYMLINK+="libmtp", MODE="660", ENV{ID_MTP_DEVICE}="1"<br />
<br />
Reload the udev rules.<br />
<br />
# udevadm control --reload<br />
<br />
And reboot the system. Now file managers (like Thunar) should be able to automount the MTP Device. [https://bbs.archlinux.org/viewtopic.php?id=180719]<br />
<br />
=== kio-mtp ===<br />
<br />
If you are not able to use the action "Open with File Manager", you may work around this problem by editing the file {{ic|/usr/share/apps/solid/actions/solid_mtp.desktop}}.<br />
<br />
Change the line<br />
<br />
Exec=kioclient exec mtp:udi=%i/<br />
<br />
To<br />
<br />
Exec=dolphin "mtp:/"</div>Fylwindhttps://wiki.archlinux.org/index.php?title=VirtualBox&diff=390221VirtualBox2015-08-06T23:01:09Z<p>Fylwind: /* Use the right front-end */ VRDP requires extension pack</p>
<hr />
<div>[[Category:Emulators]]<br />
[[Category:Hypervisors]]<br />
[[cs:VirtualBox]]<br />
[[de:VirtualBox]]<br />
[[el:VirtualBox]]<br />
[[es:VirtualBox]]<br />
[[fr:VirtualBox]]<br />
[[hu:VirtualBox]]<br />
[[it:VirtualBox]]<br />
[[ja:VirtualBox]]<br />
[[pt:VirtualBox]]<br />
[[ru:VirtualBox]]<br />
[[zh-CN:VirtualBox]]<br />
{{Related articles start}}<br />
{{Related|:Category:Hypervisors}}<br />
{{Related|PhpVirtualBox}}<br />
{{Related|Moving an existing install into (or out of) a virtual machine}}<br />
{{Related articles end}}<br />
<br />
[https://www.virtualbox.org VirtualBox] is a [[Wikipedia:Hypervisor|hypervisor]] used to run operating systems in a special environment, called a virtual machine, on top of the existing operating system. VirtualBox is in constant development and new features are implemented continuously. It comes with a [[Qt]] GUI interface, as well as headless and [[Wikipedia:Simple DirectMedia Layer|SDL]] command-line tools for managing and running virtual machines.<br />
<br />
In order to integrate functions of the host system to the guests, including shared folders and clipboard, video acceleration and a seamless window integration mode, ''guest additions'' are provided for some guest operating systems.<br />
<br />
== Installation steps for Arch Linux hosts ==<br />
<br />
In order to launch VirtualBox virtual machines on your Arch Linux box, follow these installation steps.<br />
<br />
=== Install the core packages ===<br />
<br />
First, [[install]] the {{Pkg|virtualbox}} package which contains the GPL-licensed VirtualBox suite with the SDL and headless command-line tools included. The {{Pkg|virtualbox}} package comes with {{Pkg|virtualbox-host-modules}} as a required dependency. <br />
<br />
You can install the {{Pkg|qt4}} optional dependency in order to use the graphical interface which is based on [[Qt]]. This is not required if you intend to use VirtualBox in command-line only. [[#Use the right front-end|See below to learn the differences]].<br />
<br />
=== Install the VirtualBox kernel modules ===<br />
<br />
Next, to fully virtualize your guest installation, VirtualBox provides the following [[kernel modules]]: {{ic|vboxdrv}}, {{ic|vboxnetadp}}, {{ic|vboxnetflt}}, and {{ic|vboxpci}}. These must be added to your host kernel.<br />
<br />
The binary compatibility of kernel modules depends on the API of the kernel against which they have been compiled. The problem with the Linux kernel is that these interfaces might not be the same from one kernel version to another. In order to avoid compatibility problems and subtle bugs, each time the Linux kernel is upgraded, it is advised to recompile the kernel modules against the Linux kernel version that has just been installed. This is what Arch Linux packagers actually do with the VirtualBox kernel modules packages: each time a new Arch Linux kernel is released, the Virtualbox modules are upgraded accordingly.<br />
<br />
Therefore, if you are using a kernel from the [[official repositories]] or a custom one (self-compiled or installed from the [[AUR]]), the kernel module package you will need to install will thus vary.<br />
<br />
==== Hosts running an official kernel ====<br />
<br />
* If you are using the {{Pkg|linux}} kernel, make sure the {{pkg|virtualbox-host-modules}} package is still installed. The latter has been installed when you installed the {{Pkg|virtualbox}} package.<br />
* If you are using the LTS version of the kernel ({{pkg|linux-lts}}), you need to install the {{pkg|virtualbox-host-modules-lts}} package. {{Pkg|virtualbox-host-modules}} can now be removed if you want.<br />
* If you are using the {{aur|linux-ck}} kernel, build the {{aur|virtualbox-ck-host-modules}} package.<br />
<br />
==== Hosts running a custom kernel ====<br />
<br />
{{Merge|Dynamic Kernel Module Support|The general tips on DKMS usage do not belong on this page.}}<br />
<br />
If you use or intend to use a self-compiled kernel from sources, you have to know that VirtualBox does not require any virtualization modules (e.g. virtuo, kvm,...). The VirtualBox kernel modules provide all the necessary for VirtualBox to work properly. You can thus disable in your kernel ''.config'' file these virtualization modules if you do not use other hypervisors like Xen, KVM or QEMU.<br />
<br />
The {{ic|virtualbox-host-modules}} package works fine with custom kernels of the same version of the Arch Linux stock kernel such as {{AUR|linux-ck}}. Since the {{ic|virtualbox-host-modules}} comes with the official Arch Linux kernel ({{Pkg|linux}}) as a dependency and if you do not use that kernel, install {{Pkg|virtualbox-host-dkms}} instead.<br />
<br />
If you are using a custom kernel which is not of the same version of the Arch Linux stock one, you will have to install the {{Pkg|virtualbox-host-dkms}} too. The latter comes bundled with the source of the VirtualBox kernel modules that will be compiled to generate these modules for your kernel.<br />
<br />
As the {{Pkg|virtualbox-host-dkms}} package requires compilation, make sure you have the kernel headers corresponding to your custom kernel version to prevent this error from happening {{ic|Your kernel headers for kernel ''your custom kernel version'' cannot be found at /usr/lib/modules/''your custom kernel version''/build or /usr/lib/modules/''your custom kernel version''/source}}.<br />
* If you use a self-compiled kernel and have used {{ic|make modules_install}} to install its modules, folders {{ic|/usr/lib/modules/''your custom kernel version''/build}} and {{ic|(...)/source}} will be symlinked to your kernel sources. These will act as the kernel headers you need. If you have not removed these kernel sources yet, you have nothing to do.<br />
* If you use a custom kernel from [[AUR]], make sure the package {{Pkg|linux-headers}} is installed.<br />
<br />
Once {{Pkg|virtualbox-host-dkms}} is installed, simply generate the kernel modules for your custom kernel by running the following command structure:<br />
# dkms install vboxhost/''virtualbox-host-source version'' -k ''your custom kernel version''/''your architecture''<br />
<br />
{{Tip|Use this all-in-one command instead, if you do not want to adapt the above command:<br />
{{bc|<nowiki># dkms install vboxhost/$(pacman -Q virtualbox|awk '{print $2}'|sed 's/\-.\+//') -k $(uname -rm|sed 's/\ /\//')</nowiki>}}<br />
}}<br />
<br />
To automatically recompile the VirtualBox kernel modules when their sources get upgraded (i.e. when the {{Pkg|virtualbox-host-dkms}} package gets upgraded) and avoid to type again the above {{ic|dkms install}} command manually afterwards, enable the {{ic|dkms}} service with:<br />
# systemctl enable dkms.service<br />
<br />
If this service is not enabled while the {{Pkg|virtualbox-host-dkms}} package is being updated, the VirtualBox modules will not be updated and you will have to type in manually the {{ic|dkms install}} command described above to compile the latest version of the Virtualbox kernel modules. If you do not want to type in manually this command, if the {{ic|dkms}} service is automatically loaded at startup, you just need to reboot and your VirtualBox modules will be recompiled silently.<br />
<br />
However, if you want to keep this daemon disabled, you can use an [[mkinitcpio|initramfs hook]] that will automatically trigger the {{ic|dkms install}} command described above at boot time. This will require a reboot to recompile the VirtualBox modules. To enable this hook, install the {{AUR|vboxhost-hook}} package and add {{ic|vboxhost}} to your HOOKS array in {{ic|/etc/mkinitcpio.conf}}. Again, make sure the right linux headers are available for the new kernel otherwise the compilation will fail.<br />
<br />
{{Tip|Like the {{ic|dkms}} command, the {{ic|vboxhost}} hook will tell you if anything goes wrong during the recompilation of the VirtualBox modules.}}<br />
<br />
=== Load the VirtualBox kernel modules ===<br />
<br />
Among the [[kernel modules]] VirtualBox uses, there is a mandatory module named {{ic|vboxdrv}}, which must be loaded before any virtual machines can run. It can be automatically loaded when Arch Linux starts up, or it can be loaded manually when necessary.<br />
<br />
To load the module manually:<br />
# modprobe vboxdrv<br />
<br />
To load the VirtualBox module at boot time, refer to [[Kernel modules#Automatic module handling]] and create a {{ic|*.conf}} file (e.g. {{ic|virtualbox.conf}}) in {{ic|/etc/modules-load.d/}} with the line:<br />
{{hc|/etc/modules-load.d/virtualbox.conf|<br />
vboxdrv}}<br />
<br />
The following modules are optional but are recommended if you do not want to be bothered in some advanced configurations (precised here after): {{ic|vboxnetadp}}, {{ic|vboxnetflt}} and {{ic|vboxpci}}.<br />
<br />
* {{ic|vboxnetadp}} and {{ic|vboxnetflt}} are both needed when you intend to use the [https://www.virtualbox.org/manual/ch06.html#network_bridged bridged] or [https://www.virtualbox.org/manual/ch06.html#network_hostonly host-only networking] feature. More precisely, {{ic|vboxnetadp}} is needed to create the host interface in the VirtualBox global preferences, and {{ic|vboxnetflt}} is needed to launch a virtual machine using that network interface.<br />
<br />
* {{ic|vboxpci}} is needed when your virtual machine needs to pass through a PCI device on your host.<br />
<br />
{{Note|If the VirtualBox kernel modules were loaded in the kernel while you updated the modules, you need to reload them manually to use the new updated version. To do it, run {{ic|vboxreload}} as root.}}<br />
<br />
Finally, if you use the aforementioned "Host-only" or "bridge networking" feature, make sure {{pkg|net-tools}} is installed. VirtualBox actually uses {{ic|ifconfig}} and {{ic|route}} to assign the IP and route to the host interface configured with {{ic|VBoxManage hostonlyif}} or via the GUI in ''Settings > Network > Host-only Networks > Edit host-only network (space) > Adapter''.<br />
<br />
=== Add usernames to the vboxusers group ===<br />
<br />
To use the USB ports of your host machine in your virtual machines, add to the {{ic|vboxusers}} [[group]] the usernames that will be authorized to use this feature. The new group does not automatically apply to existing sessions; the user has to log out and log in again, or start a new environment with the {{ic|newgrp}} command or with {{ic|sudo -u $USER -s}}. To add the current user to the {{ic|vboxusers}} group, type:<br />
# gpasswd -a $USER vboxusers<br />
<br />
=== Guest additions disc ===<br />
<br />
It is also recommended to install the {{Pkg|virtualbox-guest-iso}} package on the host running VirtualBox. This package will act as a disc image that can be used to install the guest additions onto guest systems other than Arch Linux. The ''.iso'' file will be located at {{ic|/usr/lib/virtualbox/additions/VBoxGuestAdditions.iso}}, and may have to be mounted manually inside the virtual machine. Once mounted, you can run the guest additions installer inside the guest.<br />
<br />
=== Extension pack ===<br />
<br />
Since VirtualBox 4.0, non-GPL components have been split from the rest of the application. Despite being released under a non-free license and '''being only available for personal use''', you might be interested in installing the Oracle Extension Pack which provides [https://www.virtualbox.org/manual/ch01.html#intro-installing additional features]. To avoid manual manipulation, the {{aur|virtualbox-ext-oracle}} package is available, and a prebuilt version can be found in the [[Unofficial user repositories#seblu|seblu]] repository.<br />
<br />
If you prefer to use the traditional and manual way: download the extension manually and install it via the GUI (''File > Preferences > Extensions'') or via {{ic|VBoxManage extpack install <.vbox-extpack>}}, make sure you have a toolkit (like [[Polkit]], gksu, etc.) to grant privileged access to VirtualBox. The installation of this extension [https://www.virtualbox.org/ticket/8473 requires root access].<br />
<br />
=== Use the right front-end ===<br />
<br />
Now, you are ready to use VirtualBox. Congratulations!<br />
<br />
Multiple front-ends are available to you of which two are available by default:<br />
* If you want to use VirtualBox in command-line only (only launch and change settings of existing virtual machines), you can use the {{ic|VBoxSDL}} command. VBoxSDL does only provide a simple window that contains only the ''pure'' virtual machine, without menus or other controls.<br />
* If you want to use VirtualBox in command-line without any GUI running (e.g. on a server) to create, launch and configure virtual machines, use the {{ic|VBoxHeadless}} which produces no visible output on the host at all, but instead only delivers VRDP data (note: VRDP is only enabled if the extension pack is installed).<br />
<br />
If you installed the {{Pkg|qt4}} optional dependency, you can run {{ic|VirtualBox}} and have a nice-looking GUI interface with menus usable via the mouse.<br />
<br />
Finally, you can use [[PhpVirtualBox]] to administrate your virtual machines via a web interface.<br />
<br />
Refer to the [https://www.virtualbox.org/manual VirtualBox manual] to learn how to create virtual machines.<br />
<br />
{{Warning|If you intend to store virtual disk images on a [[Btrfs]] file system, before creating any images, you should consider disabling [[Btrfs#Copy-On-Write_.28CoW.29|Copy-on-Write]] for the destination directory of these images.}}<br />
<br />
== Installation steps for Arch Linux guests ==<br />
<br />
=== Install Arch Linux inside the virtual machine ===<br />
<br />
{{Note| Windows 8+ or Server 2008+ hosts may have to disable Hyper-V in order to use hardware virtualization features and create 64 bit virtual machines in VirtualBox. To learn how to disable or re-enable Hyper-V [https://superuser.com/questions/684966/switch-off-hyper-v-without-disable-functionality-in-windows-8-1 see this Super User post]. }}<br />
<br />
Boot the Arch installation media through one of the virtual machine's virtual drives. Then, complete the installation of a basic Arch system as explained in the [[Beginners' guide]] or the [[Installation guide]] without installing any graphic driver: we will install one provided by VirtualBox just at the next step.<br />
<br />
==== Installation in EFI mode ====<br />
<br />
If you want to install Arch Linux in EFI mode inside VirtualBox, in the settings of the virtual machine, go in the ''Settings'' tab, and check the checkbox ''Enable EFI (special OSes only)''. After selecting the kernel from the Arch Linux installation media's menu, the media will hang for a minute or two and will continue to boot the kernel normally afterwards. Be patient.<br />
<br />
When booting in EFI mode, VirtualBox will first attempt to run {{ic|/EFI/BOOT/BOOTX64.EFI}} from the ESP. If that first option fails, VirtualBox will then try the EFI shell script {{ic|startup.nsh}} from the root of the ESP. Unless you want to manually launch your bootloader from the EFI shell every time, you will need to move your bootloader to that default path. Do not bother with the VirtualBox Boot Manager (accessible with {{ic|F2}} at boot): EFI entries added to it manually at boot or with {{Pkg|efibootmgr}} will persist after a reboot [https://www.virtualbox.org/ticket/11177 but are lost when the VM is shut down].<br />
<br />
=== Install the Guest Additions ===<br />
<br />
After completing the installation of the guest system, install the VirtualBox [https://www.virtualbox.org/manual/ch04.html Guest Additions] which include drivers and applications that optimize the guest operating system. These can be installed via {{Pkg|virtualbox-guest-utils}}, which provides {{Pkg|virtualbox-guest-modules}} as a required dependency.<br />
<br />
{{Note|The method described in the [https://www.virtualbox.org/manual/ch04.html#idp54932560 VirtualBox manual] does not work on Arch Linux guests, resulting in an {{ic|Unable to determine your Linux distribution}} repeated several times as error message. If you tried this method first and you use the right solution described above afterwards, this will fail. You will get a [[Pacman#"Failed to commit transaction (conflicting files)" error|file conflict]]: {{ic|/usr/bin/VBox*}} and {{ic|/usr/lib/VBox* exists in filesystem}}. The solution is to remove the offending files first with {{ic|rm /usr/bin/VBox* /usr/lib/VBox*}} as root. These files are actually symbolic links to the location where the additions tools were installed; by default, this is {{ic|/opt/VBoxGuestAdditions-''version number''}}. Remove these files too with {{ic|rm -r /opt/VBoxGuestAdditions-''version number''}} as they are not needed. Now you can restart the installation from the right method above.}}<br />
<br />
=== Install the VirtualBox guest kernel modules ===<br />
<br />
==== Guests running an official kernel ====<br />
<br />
* If you are using the {{Pkg|linux}} kernel, make sure the {{pkg|virtualbox-guest-modules}} package is still installed. The latter has been installed when you installed the {{Pkg|virtualbox-guest-utils}} package.<br />
* If you are using the LTS version of the kernel ({{pkg|linux-lts}}), you need to install the {{pkg|virtualbox-guest-modules-lts}} package. {{Pkg|virtualbox-guest-modules}} can now be removed if you want.<br />
* If you are using the {{aur|linux-ck}}, kernel, build the {{aur|virtualbox-ck-guest-modules}} package. {{Pkg|virtualbox-guest-modules}} can now be removed in this case too, if you want.<br />
<br />
==== Guests running a custom kernel ====<br />
<br />
As this installation step is quite similar to the Vitualbox kernel modules section for the host described above, please refer to [[#Install the VirtualBox kernel modules|that section]] for more information and replace all {{Pkg|virtualbox-host-modules}}, {{Pkg|virtualbox-host-dkms}} and {{AUR|vboxhost-hook}} statements by {{Pkg|virtualbox-guest-modules}}, {{Pkg|virtualbox-guest-dkms}} and {{AUR|vboxguest-hook}} respectively.<br />
<br />
=== Load the Virtualbox kernel modules ===<br />
<br />
To load the modules manually, type:<br />
# modprobe -a vboxguest vboxsf vboxvideo<br />
<br />
To load the VirtualBox module at boot time, refer to [[Kernel modules#Automatic module handling]] and create a {{ic|*.conf}} file (e.g. {{ic|virtualbox.conf}}) in {{ic|/etc/modules-load.d/}} with these lines:<br />
{{hc|/etc/modules-load.d/virtualbox.conf|<br />
vboxguest<br />
vboxsf<br />
vboxvideo}}<br />
<br />
Alternatively, [[enable]] the {{ic|vboxservice}} service which loads the modules and synchronizes the guest's system time with the host.<br />
<br />
=== Launch the VirtualBox guest services ===<br />
<br />
After the rather big installation step dealing with VirtualBox kernel modules, now you need to start the guest services. The guest services are actually just a binary executable called {{ic|VBoxClient}} which will interact with your X Window System. {{ic|VBoxClient}} manages the following features:<br />
* shared clipboard and drag and drop between the host and the guest;<br />
* seamless window mode;<br />
* the guest display is automatically resized according to the size of the guest window;<br />
* checking the VirtualBox host version<br />
<br />
All of these features can be enabled independently with their dedicated flags:<br />
$ VBoxClient --clipboard --draganddrop --seamless --display --checkhostversion<br />
<br />
As a shortcut, the {{ic|VBoxClient-all}} bash script enables all of these features. You should set {{ic|VBoxClient}} to be automatically loaded as your [[desktop environment]] or [[window manager]] starts. In practice,<br />
* if you are using a [[desktop environment]], you just need to check a box or add the {{ic|/usr/sbin/VBoxClient-all}} to the autostart section in your [[desktop environment]] settings (the DE will typically set a flag to a ''.desktop'' file in {{ic|~/.config/autostart}}, see [[Autostart#Desktop entries|the Autostart section]] for more details);<br />
* if you do not have any [[desktop environment]], add the following line to the top of {{ic|~/.xinitrc}} above any {{ic|exec}} options. See [[Xinitrc]] for detail.<br />
{{hc|~/.xinitrc|<br />
/usr/bin/VBoxClient-all}}<br />
<br />
VirtualBox can also synchronize the time between the host and the guest. To do this, run {{ic|VBoxService}} as root. To set this to run automatically on boot, simply [[enable]] the {{ic|vboxservice}} service.<br />
<br />
Now, you should have a working Arch Linux guest. Note that features like clipboard sharing are disabled by default in VirtualBox, and you will need to turn them on in the per-VM settings if you actually want to use them (e.g. ''Settings > General > Advanced > Shared Clipboard'').<br />
<br />
If you want to share folders between your host and your Arch Linux guest, read on.<br />
<br />
=== Enable shared folders ===<br />
<br />
Shared folders are managed on the host, in the settings of the Virtual Machine accessible via the GUI of VirtualBox, in the ''Shared Folders'' tab. There, ''Folder Path'', the name of the mount point identified by ''Folder name'', and options like ''Read-only'', ''Auto-mount'' and ''Make permanent'' can be specified. These parameters can be defined with the {{ic|VBoxManage}} command line utility. See [https://www.virtualbox.org/manual/ch04.html#sharedfolders there for more details].<br />
<br />
No matter which method you will use to mount your folder, all methods require some steps first.<br />
<br />
To avoid this issue {{ic|/sbin/mount.vboxsf: mounting failed with the error: No such device}}, make sure the {{ic|vboxsf}} kernel module is properly loaded. It should be, since we enabled all guest kernel modules previously.<br />
<br />
Two additional steps are needed in order for the mount point to be accessible from users other than root:<br />
* the {{Pkg|virtualbox-guest-utils}} package created a group {{ic|vboxsf}} (done in a previous step);<br />
* your username must be in this group, use this command {{ic|gpasswd -a $USER vboxsf}} to add your username and use {{ic|newgrp}} to apply the changes immediately;<br />
<br />
==== Manual mounting ====<br />
<br />
Use the following command to mount your folder in your Arch Linux guest:<br />
# mount -t vboxsf ''shared_folder_name'' ''mount_point_on_guest_system''<br />
<br />
The vboxsf filesystem offers other options which can be displayed with this command:<br />
# mount.vboxsf<br />
<br />
For example if the user was not in the ''vboxsf'' group, we could have used this command to give access our mountpoint to him:<br />
# mount -t vboxsf -o uid=1000,gid=1000 home /mnt/<br />
<br />
Where ''uid'' and ''gid'' are values corresponding to the users we want to give access to. These values are obtained from the {{ic|id}} command run against this user.<br />
<br />
==== Automounting ====<br />
<br />
In order for the automounting feature to work you must have checked the auto-mount checkbox in the GUI or used the optional {{ic|--automount}} argument with the command {{ic|VBoxManage sharedfolder}}.<br />
<br />
The shared folder should now appear in {{ic|/media/sf_''shared_folder_name''}}. If users in {{ic|media}} cannot access the shared folders, check that {{ic|media}} has permissions 755 or has group ownership {{ic|vboxsf}} if using permission 750. This is currently not the default if media is created by installing the {{ic|virtualbox-guest-utils}}.<br />
<br />
You can use symlinks if you want to have a more convenient access and avoid to browse in that directory, e.g.:<br />
$ ln -s /media/sf_''shared_folder_name'' ~/''my_documents''<br />
<br />
==== Mount at boot ====<br />
<br />
You can mount your directory with [[fstab]]. However, to prevent startup problems with systemd, {{ic|1=comment=systemd.automount}} should be added to {{ic|/etc/fstab}}. This way, the shared folders are mounted only when those mount points are accessed and not during startup. This can avoid some problems, especially if the guest additions are not loaded yet when systemd read fstab and mount the partitions.<br />
desktop /media/desktop vboxsf uid=user,gid=group,rw,dmode=700,fmode=600,comment=systemd.automount 0 0<br />
<br />
As of 2012-08-02, mount.vboxsf does not support the ''nofail'' option:<br />
desktop /media/desktop vboxsf uid=user,gid=group,rw,dmode=700,fmode=600,nofail 0 0<br />
<br />
== Import/export VirtualBox virtual machines from/to other hypervisors ==<br />
<br />
If you plan to use your virtual machine on another hypervisor or want to import in VirtualBox a virtual machine created with another hypervisor, you might be interested in reading the following steps.<br />
<br />
=== Remove additions ===<br />
<br />
Guest additions are available in most hypervisor solutions: VirtualBox comes with the Guest Additions, VMware with the VMware Tools, Parallels with the Parallels Tools, etc. These additional components are designed to be installed inside a virtual machine after the guest operating system has been installed. They consist of device drivers and system applications that optimize the guest operating system for better performance and usability [https://www.virtualbox.org/manual/ch04.html by providing these features].<br />
<br />
If you have installed the additions to your virtual machine, please uninstall them first. Your guest, especially if it is using an OS from the Windows family, might behave weirdly, crash or even might not boot at all if you are still using the specific drivers in another hypervisor.<br />
<br />
=== Use the right virtual disk format ===<br />
<br />
This step will depend on the ability to convert the virtual disk image directly or not.<br />
<br />
==== Automatic tools ====<br />
<br />
Some companies provide tools which offer the ability to create virtual machines from a Windows or GNU/Linux operating system located either in a virtual machine or even in a native installation. With such a product, you do not need to apply this and the following steps and can stop reading here.<br />
* ''[http://www.parallels.com/products/transporter Parallels Transporter]'' which is non free, is a product from Parallels Inc. This solution basically consists in an piece of software called ''agent'' that will be installed in the guest you want to import/convert. Then, Parallels Transporter, <u>which only works on OS X</u>, will create a virtual machine from that ''agent'' which is contacted either by USB or Ethernet network.<br />
* ''[https://www.vmware.com/products/converter/ VMware vCenter Converter]'' which is free upon registration on the VMware webiste, works nearly the same way as Parallels Transporter, but the piece of software that will gather the data to create the virtual machine only works on a Windows platform.<br />
<br />
==== Manual conversion ====<br />
<br />
First, familiarize yourself with the [[#Formats supported by VirtualBox]] and [[Wikipedia:Comparison of platform virtual machines#Image type compatibility|those supported by third-party hypervisors]].<br />
<br />
* Importing or exporting a virtual machine from/to a VMware solution is not a problem at all if you use the VMDK or OVF disk format, otherwise converting [[#VMDK to VDI and VDI to VMDK]] is possible and the aforementioned VMware vCenter Converter tool is available.<br />
<br />
* Importing or exporting from/to QEMU is not a problem neither: some QEMU formats are supported directly by VirtualBox and conversion between [[#QCOW2 to VDI and VDI to QCOW2]] is still available if needed.<br />
<br />
* Importing or exporting from/to Parallels hypervisor is the hardest way: Parallels does only support its own HDD format (even the standard and portable OVF format is not supported!).<br />
:* To export your virtual machine to Parallels, you will need to use the Parallels Transporter tool described above.<br />
:* To import your virtual machine to VirtualBox, you will need to use the VMware vCenter Converter described above to convert the VM to the VMware format first. Then, apply the solution to migrate from VMware.<br />
<br />
=== Create the VM configuration for your hypervisor ===<br />
<br />
Each hypervisor have their own virtual machine configuration file: {{ic|.vbox}} for VirtualBox, {{ic|.vmx}} for VMware, a {{ic|config.pvs}} file located in the virtual machine bundle ({{ic|.pvm}} file), etc. You will have thus to recreate a new virtual machine in your new destination hypervisor and specify its hardware configuration as close as possible as your initial virtual machine.<br />
<br />
Pay a close attention to the firmware interface (BIOS or UEFI) used to install the guest operating system. While an option is available to choose between these 2 interfaces on VirtualBox and on Parallels solutions, on VMware, you will have to add manually the following line to your ''.vmx'' file.<br />
<br />
{{hc|ArchLinux_vm.vmx|2=<br />
firmware = "efi"<br />
}}<br />
<br />
Finally, ask your hypervisor to use the existing virtual disk you have converted and launch the virtual machine.<br />
{{Tip|<br />
* On VirtualBox, if you do not want to browse the whole GUI to find the right location to add your new virtual drive device, you can [[#Replace a virtual disk manually from the .vbox file]], or use the {{ic|VBoxManage storageattach}} described in [[#Increase virtual disks]] or in the [https://www.virtualbox.org/manual/ch08.html#vboxmanage-storageattach VirtualBox manual page].<br />
* Similarly, in VMware products, you can replace the location of the current virtual disk location by adapting the ''.vmdk'' file location in your ''.vmx'' configuration file.}}<br />
<br />
== Virtual disks management ==<br />
<br />
=== Formats supported by VirtualBox ===<br />
<br />
VirtualBox supports the following virtual disk formats:<br />
<br />
* VDI: The Virtual Disk Image is the VirtualBox own open container used by default when you create a virtual machine with VirtualBox.<br />
<br />
* VMDK: The Virtual Machine Disk has been initially developed by VMware for their products. The specification was initially closed source, but it became now an open format which is fully supported by VirtualBox. This format offers the ability to be split into several 2GB files. This feature is specially useful if you want to store the virtual machine on machines which do not support very large files. Other formats, excluding the HDD format from Parallels, do not provide such an equivalent feature.<br />
<br />
* VHD: The Virtual Hard Disk is the format used by Microsoft in Windows Virtual PC and Hyper-V. If you intend to use any of these Microsoft products, you will have to choose this format.<br />
:{{Tip|Since Windows 7, this format can be mounted directly without any additional application.}} <br />
<br />
* VHDX (read only): This is the eXtended version of the Virtual Hard Disk format developed by Microsoft, which has been released on 2012-09-04 with Hyper-V 3.0 coming with Windows Server 2012. This new version of the disk format does offer enhanced performance (better block alignment), larger blocks size, and journal support which brings power failure resiliency. VirtualBox [https://www.virtualbox.org/manual/ch15.html#idp63002176 should support this format in read only].<br />
<br />
* Version 2 of the HDD: The HDD format is developed by Parallels Inc and used in their hypervisor solutions like Parallels Desktop for Mac. Newer versions of this format (i.e. 3 and 4) are not supported due to the lack of documentation for this proprietary format. {{Note|There is currently a controversy regarding the support of the version 2 of the format. While the official VirtualBox manual [https://www.virtualbox.org/manual/ch05.html#vdidetails only reports the second version of the HDD file format as supported], Wikipedia's contributors are [[Wikipedia:Comparison of platform virtual machines#Image type compatibility|reporting the first version may work too]]. Help is welcome if you can perform some tests with the first version of the HDD format.}}<br />
<br />
* QED: The QEMU Enhanced Disk format is an old file format for QEMU, another free and open source hypervisor. This format was designed from 2010 in a way to provide a superior alternative to QCOW2 and others. This format features a fully asynchronous I/O path, strong data integrity, backing files, and sparse files. QED format is supported only for compatibility with virtual machines created with old versions of QEMU.<br />
<br />
* QCOW: The QEMU Copy On Write format is the current format for QEMU. The QCOW format does support zlib-based transparent compression and encryption (the latter has flaw and is not recommended). QCOW is available in two versions: QCOW and QCOW2. The latter tends to supersede the first one. QCOW is [https://www.virtualbox.org/manual/ch15.html#idp63002176 currently fully supported by VirtualBox]. QCOW2 comes in two revisions: QCOW2 0.10 and QCOW2 1.1 (which is the default when you create a virtual disk with QEMU). VirtualBox does not support this QCOW2 format (both revisions have been tried).<br />
<br />
* OVF: The Open Virtualization Format is an open format which has been designed for interoperability and distributions of virtual machines between different hypervisors. VirtualBox supports all revisions of this format via the [https://www.virtualbox.org/manual/ch08.html#idp55423424 {{ic|VBoxManage}} import/export feature] but with [https://www.virtualbox.org/manual/ch14.html#KnownProblems known limitations].<br />
<br />
* RAW: This is the mode when the virtual disk is exposed directly to the disk without being contained in a specific file format container. VirtualBox supports this feature in several ways: converting RAW disk [https://www.virtualbox.org/manual/ch08.html#idp59139136 to a specific format], or by [https://www.virtualbox.org/manual/ch08.html#vboxmanage-clonevdi cloning a disk to RAW], or by using directly a VMDK file [https://www.virtualbox.org/manual/ch09.html#idp57804112 which points to a physical disk or a simple file].<br />
<br />
=== Disk image format conversion ===<br />
<br />
==== VMDK to VDI and VDI to VMDK ====<br />
<br />
VirtualBox can handle back and forth conversion between VDI and VMDK by itself with [https://www.virtualbox.org/manual/ch08.html#vboxmanage-clonevdi {{ic|VBoxManage clonehd}}].<br />
<br />
VMDK to VDI:<br />
<br />
$ VBoxManage clonehd ''source.vmdk'' ''destination.vdi'' --format VDI<br />
<br />
VDI to VMDK:<br />
<br />
$ VBoxManage clonehd ''source.vdi'' ''destination.vmdk'' --format VMDK<br />
<br />
==== VHD to VDI and VDI to VDH ====<br />
<br />
VirtualBox can handle conversion back and forth this format with [https://www.virtualbox.org/manual/ch08.html#vboxmanage-clonevdi {{ic|VBoxManage clonehd}}] too.<br />
<br />
VHD to VDI:<br />
<br />
$ VBoxManage clonehd ''source.vhd'' ''destination.vdi'' --format VDI<br />
<br />
VDI to VHD:<br />
<br />
$ VBoxManage clonehd ''source.vdi'' ''destination.vhd'' --format VHD<br />
<br />
==== QCOW2 to VDI and VDI to QCOW2 ====<br />
<br />
[https://www.virtualbox.org/manual/ch08.html#vboxmanage-clonevdi {{ic|VBoxManage clonehd}}] cannot handle the QEMU format conversion; we will thus rely on another tool. The {{ic|qemu-img}} command from {{Pkg|qemu}} can be used to convert images back and forth from VDI to QCOW2. {{Note|{{ic|qemu-img}} can handle a bunch of other formats too. According to the {{ic|qemu-img --help}}, here are the supported formats this tool supports: "''vvfat vpc vmdk vhdx vdi ssh sheepdog sheepdog sheepdog raw host_cdrom host_floppy host_device file qed qcow2 qcow parallels nbd nbd nbd iscsi dmg tftp ftps ftp https http cow cloop bochs blkverify blkdebug'".}}<br />
<br />
QCOW2 to VDI:<br />
<br />
$ qemu-img convert -pO vdi ''source.qcow2'' ''destination.vdi''<br />
<br />
VDI to QCOW2:<br />
<br />
$ qemu-img convert -pO qcow2 ''source.vdi'' ''destination.qcow2''<br />
<br />
As QCOW2 comes in two revisions (see [[#Formats supported by VirtualBox]], use the flag {{ic|1=-o compat=}} to specify the revision.<br />
<br />
$ qemu-img convert -pO qcow2 ''source.vdi'' ''destination.qcow2'' -o compat=0.10<br />
or<br />
$ qemu-img convert -pO qcow2 ''source.vdi'' ''destination.qcow2'' -o compat=1.1<br />
<br />
{{Tip|The {{ic|-p}} parameter is used to get the progression of the conversion task.}}<br />
<br />
=== Mount virtual disks ===<br />
<br />
==== VDI ====<br />
<br />
Mounting vdi images only works with fixed size images (a.k.a. static images); dynamic (dynamically size allocating) images are not easily mountable.<br />
<br />
The offset of the partition (within the vdi) is needed, then add the value of {{ic|offData}} to {{ic|32256}} (e.g. 69632 + 32256 = 101888):<br />
<br />
$ VBoxManage internalcommands dumphdinfo <storage.vdi> | grep "offData"<br />
<br />
The can now be mounted with:<br />
<br />
# mount -t ext4 -o rw,noatime,noexec,loop,offset=101888 <storage.vdi> /mntpoint/<br />
<br />
You can also use [https://github.com/pld-linux/VirtualBox/blob/master/mount.vdi mount.vdi] script that, which you can use as (install script itself to {{ic|/usr/bin/}}):<br />
<br />
# mount -t vdi -o fstype=ext4,rw,noatime,noexec ''vdi_file_location'' ''/mnt/''<br />
<br />
Alternately you can use {{Pkg|qemu}}'s kernel module that can do this [[http://bethesignal.org/blog/2011/01/05/how-to-mount-virtualbox-vdi-image/ attrib]]:<br />
<br />
# modprobe nbd max_part=16<br />
# qemu-nbd -c /dev/nbd0 <storage.vdi><br />
# mount /dev/nbd0p1 /mnt/dir/<br />
# # to unmount:<br />
# umount /mnt/dir/<br />
# qemu-nbd -d /dev/nbd0<br />
<br />
If the partition nodes are not propagated try using {{ic|partprobe /dev/nbd0}}; otherwise, a vdi partition can be mapped directly to a node by: {{ic|qemu-nbd -P 1 -c /dev/nbd0 <storage.vdi>}}.<br />
<br />
=== Compact virtual disks ===<br />
<br />
Compacting virtual disks only works with {{ic|.vdi}} files and basically consists in the following steps.<br />
<br />
Boot your virtual machine and remove all bloat manually or by using cleaning tools like {{Pkg|bleachbit}} which is [http://bleachbit.sourceforge.net/download/windows available for Windows systems too].<br />
<br />
Wiping free space with zeroes can be achieved with several tools:<br />
* If you were previously using Bleachbit, check the checkbox ''System > Free disk space'' in the GUI, or use {{ic|bleachbit -c system.free_disk_space}} in CLI;<br />
* On UNIX-based systems, by using {{ic|dd}} or preferably {{Pkg|dcfldd}} (see [http://superuser.com/a/355322 here] to learn the differences) :<br />
:{{bc|1=# dcfldd if=/dev/zero of=''/fillfile'' bs=4M}}<br />
:When {{ic|fillfile}} reaches the limit of the partition, you will get a message like {{ic|1280 blocks (5120Mb) written.dcfldd:: No space left on device}}. This means that all of the user-space and non-reserved blocks of the partition will be filled with zeros. Using this command as root is important to make sure all free blocks have been overwritten. Indeed, by default, when using partitions with ext filesystem, a specified percentage of filesystem blocks is reserved for the super-user (see the {{ic|-m}} argument in the {{ic|mkfs.ext4}} man pages or use {{ic|tune2fs -l}} to see how much space is reserved for root applications).<br />
:When the aforementioned process has completed, you can remove the file {{ic|''fillfile''}} you created.<br />
<br />
* On Windows, there are two tools available:<br />
:*{{ic|sdelete}} from the [http://technet.microsoft.com/en-us/sysinternals/bb842062.aspx Sysinternals Suite], type {{ic|sdelete -s -z ''c:''}}, where you need to reexecute the command for each drive you have in your virtual machine;<br />
:* or, if you love scripts, there is a [http://blog.whatsupduck.net/2012/03/powershell-alternative-to-sdelete.html PowerShell solution], but which still needs to be repeated for all drives.<br />
::{{bc|PS> ./Write-ZeroesToFreeSpace.ps1 -Root ''c:\'' -PercentFree 0}}<br />
::{{Note|This script must be run in a PowerShell environment with administrator privileges. By default, scripts cannot be run, ensure the execution policy is at least on {{ic|RemoteSigned}} and not on {{ic|Restricted}}. This can be checked with {{ic|Get-ExecutionPolicy}} and the required policy can be set with {{ic|Set-ExecutionPolicy RemoteSigned}}.}}<br />
<br />
Once the free disk space have been wiped, shut down your virtual machine.<br />
<br />
The next time you boot your virtual machine, it is recommended to do a filesystem check.<br />
* On UNIX-based systems, you can use {{ic|fsck}} manually;<br />
:* On GNU/Linux systems, and thus on Arch Linux, you can force a disk check at boot [[Fsck#Forcing the check|thanks to a kernel boot parameter]];<br />
* On Windows systems, you can use:<br />
:* either {{ic|chkdsk ''c:'' /F}} where {{ic|''c:''}} needs to be replaced by each disk you need to scan and fix errors;<br />
:* or {{ic|FsckDskAll}} [http://therightstuff.de/2009/02/14/ChkDskAll-ChkDsk-For-All-Drives.aspx from here] which is basically the same software as {{ic|chkdsk}}, but without the need to repeat the command for all drives;<br />
<br />
Now, remove the zeros from the {{ic|vdi}} file with {{ic|[https://www.virtualbox.org/manual/ch08.html#vboxmanage-modifyvdi VBoxManage modifyhd]}}:<br />
$ VBoxManage modifyhd ''your_disk.vdi'' --compact<br />
<br />
{{Note|If your virtual machine has snapshots, you need to apply the above command on each {{ic|.vdi}} files you have.}}<br />
<br />
=== Increase virtual disks ===<br />
<br />
If you are running out of space due to the small hard drive size you selected when you created your virtual machine, the solution adviced by the VirtualBox manual is to use [https://www.virtualbox.org/manual/ch08.html#vboxmanage-modifyvdi {{ic|VBoxManage modifyhd}}]. However this command only works for VDI and VHD disks and only for the dynamically allocated variants. If you want to resize a fixed size virtual disk disk too, read on this trick which works either for a Windows or UNIX-like virtual machine.<br />
<br />
First, create a new virtual disk next to the one you want to increase:<br />
$ VBoxManage createhd -filename ''new.vdi'' --size ''10000''<br />
<br />
where size is in MiB, in this example 10000MiB ~= 10GiB, and ''new.vdi'' is name of new hard drive to be created.<br />
<br />
Next, the old virtual disk needs to be cloned to the new one which this may take some time:<br />
$ VBoxManage clonehd ''old.vdi'' ''new.vdi'' --existing<br />
<br />
{{Note|By default, this command uses the ''Standard'' (corresponding to dynamic allocated) file format variant and thus will not use the same file format variant as your source virtual disk. If your ''old.vdi'' has a fixed size and you want to keep this variant, add the parameter {{ic|--variant Fixed}}.}}<br />
<br />
Detach the old hard drive and attach new one, replace all mandatory italic arguments by your own:<br />
$ VBoxManage storageattach ''VM_name'' --storagectl ''SATA'' --port ''0'' --medium none<br />
$ VBoxManage storageattach ''VM_name'' --storagectl ''SATA'' --port ''0'' --medium ''new.vdi'' --type hdd<br />
<br />
To get the storage controller name and the port number, you can use the command {{ic|VBoxManage showvminfo ''VM_name''}}. Among the output you will get such a result (what you are looking for is in italic):<br />
<br />
{{bc|<br />
[...]<br />
Storage Controller Name (0): IDE<br />
Storage Controller Type (0): PIIX4<br />
Storage Controller Instance Number (0): 0<br />
Storage Controller Max Port Count (0): 2<br />
Storage Controller Port Count (0): 2<br />
Storage Controller Bootable (0): on<br />
Storage Controller Name (1): SATA<br />
Storage Controller Type (1): IntelAhci<br />
Storage Controller Instance Number (1): 0<br />
Storage Controller Max Port Count (1): 30<br />
Storage Controller Port Count (1): 1<br />
Storage Controller Bootable (1): on<br />
IDE (1, 0): Empty<br />
''SATA'' (''0'', 0): /home/wget/IT/Virtual_machines/GNU_Linux_distributions/ArchLinux_x64_EFI/Snapshots/{6bb17af7-e8a2-4bbf-baac-fbba05ebd704}.vdi (UUID: 6bb17af7-e8a2-4bbf-baac-fbba05ebd704)<br />
[...]}}<br />
<br />
Download [http://gparted.org/download.php GParted live image] and mount it as a virtual CD/DVD disk file, boot your virtual machine, increase/move your partitions, umount GParted live and reboot.<br />
<br />
{{Note|On GPT disks, increasing the size of the disk will result in the backup GPT header not being at the end of the device. GParted will ask to fix this, click on ''Fix'' both times. On MBR disks, you do not have such a problem as this partition table as no trailer at the end of the disk.}}<br />
<br />
Finally, unregister the virtual disk from VirtualBox and remove the file:<br />
$ VBoxManage closemedium disk ''old.vdi''<br />
$ rm ''old.vdi''<br />
<br />
=== Replace a virtual disk manually from the .vbox file ===<br />
<br />
If you think that editing a simple ''XML'' file is more convenient than playing with the GUI or with {{ic|VBoxManage}} and you want to replace (or add) a virtual disk to your virtual machine, in the ''.vbox'' configuration file corresponding to your virtual machine, simply replace the GUID, the file location and the format to your needs:<br />
<br />
{{hc|ArchLinux_vm.vbox|2=<br />
<HardDisk uuid="''{670157e5-8bd4-4f7b-8b96-9ee412a712b5}''" location="''ArchLinux_vm.vdi''" format="''VDI''" type="Normal"/><br />
}}<br />
<br />
then in the {{ic|<AttachedDevice>}} sub-tag of {{ic|<StorageController>}}, replace the GUID by the new one.<br />
<br />
{{hc|ArchLinux_vm.vbox|2=<br />
<AttachedDevice type="HardDisk" port="0" device="0"><br />
<Image uuid="''{670157e5-8bd4-4f7b-8b96-9ee412a712b5}''"/><br />
</AttachedDevice><br />
}}<br />
<br />
{{Note|If you do not know the GUID of the drive you want to add, you can use the {{ic|VBoxManage showhdinfo ''file''}}. If you previously used {{ic|VBoxManage clonehd}} to copy/convert your virtual disk, this command should have outputted the GUID just after the copy/conversion completed. Using a random GUID does not work, as each [http://www.virtualbox.org/manual/ch05.html#cloningvdis UUID is stored inside each disk image].}}<br />
<br />
==== Transfer between Linux host and other OS ====<br />
<br />
The information about path to harddisks and the snapshots is stored between {{ic|<HardDisks> .... </HardDisks>}} tags in the file with the ''.vbox'' extension. You can edit them manually or use this script where you will need change only the path or use defaults, assumed that ''.vbox'' is in the same directory with a virtual harddisk and the snapshots folder. It will print out new configuration to stdout.<br />
<br />
{{bc|1=<br />
#!/bin/bash<br />
NewPath="${PWD}/"<br />
Snapshots="Snapshots/"<br />
Filename="$1"<br />
<br />
awk -v SetPath="$NewPath" -v SnapPath="$Snapshots" '{if(index($0,"<HardDisk uuid=") != 0){A=$3;split(A,B,"=");<br />
L=B[2];<br />
gsub(/\"/,"",L);<br />
sub(/^.*\//,"",L);<br />
sub(/^.*\\/,"",L);<br />
if(index($3,"{") != 0){SnapS=SnapPath}else{SnapS=""};<br />
print $1" "$2" location="\"SetPath SnapS L"\" "$4" "$5}<br />
else print $0}' "$Filename"}}<br />
<br />
{{Note|<br />
* If you will prepare virtual machine for use in Windows host then in the path name end you should use backslash \ instead of / .<br />
* The script detects snapshots by looking for {{ic|{}} in the file name.<br />
* To make it run on a new host you will need to add it first to the register by clicking on '''Machine -> Add...''' or use hotkeys Ctrl+A and then browse to ''.vbox'' file that contains configuration or use command line {{ic|VBoxManage registervm ''filename''.vbox}}}}<br />
<br />
=== Clone a virtual disk and assigning a new UUID to it ===<br />
<br />
UUIDs are widely used by VirtualBox. Each virtual machines and each virtual disk of a virtual machine must have a different UUID. When you launch a virtual machine in VirtualBox, the latter will keep track of all UUID of your virtual machine instance. See the [http://www.virtualbox.org/manual/ch08.html#vboxmanage-list {{ic|VBoxManage list}}] to list the items registered with VirtualBox.<br />
<br />
If you cloned a virtual disk manually by copying the virtual disk file, you will need to assign a new UUID to the cloned virtual drive if you want to use the disk in the same virtual machine or even in another (if that one has already been opened, and thus registered, with VirtualBox).<br />
<br />
You can use this command to assign a new UUID to your virtual disk: <br />
$ VBoxManage internalcommands sethduuid ''/path/to/disk.vdi''<br />
<br />
{{Tip|In the future, to avoid copying the virtual disk and assigning a new UUID to your file manually, use {{ic|[http://www.virtualbox.org/manual/ch08.html#vboxmanage-clonevdi VBoxManage clonehd]}} instead.}}<br />
<br />
{{Note|The commands above supports [[#Formats supported by VirtualBox|all virtual disk formats supported by VirtualBox]].}}<br />
<br />
== Advanced configuration ==<br />
<br />
=== Virtual machine launch management ===<br />
<br />
==== Starting virtual machines with a service ====<br />
<br />
Find hereafter the implementation details of a systemd service that will be used to consider a virtual machine as a service.<br />
<br />
{{hc|/etc/systemd/system/vboxvmservice@.service|2=<br />
[Unit]<br />
Description=VBox Virtual Machine %i Service<br />
Requires=systemd-modules-load.service<br />
After=systemd-modules-load.service<br />
<br />
[Service]<br />
User=''username''<br />
Group=vboxusers<br />
ExecStart=/usr/bin/VBoxHeadless -s %i<br />
ExecStop=/usr/bin/VBoxManage controlvm %i savestate<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
{{Note|Replace {{ic|''username''}} with a user that is a member of the {{ic|vboxusers}} group. Make sure the user chosen is the same user that will create/import virtual machines, otherwise the user will not see the VM appliances.}}<br />
<br />
{{Note|If you have multiple virtual machines managed by Systemd and they are not stopping properly, try to add {{ic|RemainAfterExit&#61;true}} and {{ic|KillMode&#61;none}} at the end of {{ic|[Service]}} section.}}<br />
<br />
To enable the service that will launch the virtual machine at next boot, use:<br />
# systemctl enable vboxvmservice@''your_virtual_machine_name''<br />
<br />
To start the service that will launch directly the virtual machine, use:<br />
# systemctl start vboxvmservice@''your_virtual_machine_name''<br />
<br />
VirtualBox 4.2 introduces [http://lifeofageekadmin.com/how-to-set-your-virtualbox-vm-to-automatically-startup/ a new way] for UNIX-like systems to have virtual machines started automatically, other than using a systemd service.<br />
<br />
==== Starting virtual machines with a keyboard shortcut ====<br />
<br />
It can be useful to start virtual machines directly with a keyboard shortcut instead of using the VirtualBox interface (GUI or CLI). For that, you can simply define key bindings in {{ic|.xbindkeysrc}}. Please refer to [[Xbindkeys]] for more details.<br />
<br />
Example, using the {{ic|Fn}} key of a laptop with an unused battery key ({{ic|F3}} on the computer used in this example):<br />
"VBoxManage startvm 'Windows 7'"<br />
m:0x0 + c:244<br />
XF86Battery<br />
<br />
{{Note|If you have a space in the name of your virtual machine, then enclose it with single apostrophes like made in the example just above.}}<br />
<br />
=== Use specific device in the virtual machine ===<br />
<br />
==== Using USB webcam / microphone ====<br />
<br />
{{Note|You will need to have VirtualBox extension pack installed before following the steps below. See [[#Extension pack]] for details.}}<br />
<br />
# Make sure the virtual machine is not running and your webcam / microphone is not being used.<br />
# Bring up the main VirtualBox window and go to settings for Arch machine. Go to USB section.<br />
# Make sure "Enable USB Controller" is selected. Also make sure that "Enable USB 2.0 (EHCI) Controller" is selected too.<br />
# Click the "Add filter from device" button (the cable with the '+' icon).<br />
# Select your USB webcam/microphone device from the list.<br />
# Now click OK and start your VM.<br />
<br />
==== Detecting web-cams and other USB devices ====<br />
<br />
Make sure you filter any devices that are not a keyboard or a mouse so they do not start up at boot and this insures that Windows will detect the device at start-up.<br />
<br />
=== Access a guest server ===<br />
<br />
To access [[Wikipedia:Apache_HTTP_Server|Apache server]] on a Virtual Machine from the host machine '''only''', simply execute the following lines on the host:<br />
$ VBoxManage setextradata GuestName "VBoxInternal/Devices/''pcnet''/0/LUN#0/Config/Apache/HostPort" ''8888''<br />
$ VBoxManage setextradata GuestName "VBoxInternal/Devices/''pcnet''/0/LUN#0/Config/Apache/GuestPort" ''80''<br />
$ VBoxManage setextradata GuestName "VBoxInternal/Devices/''pcnet''/0/LUN#0/Config/Apache/Protocol" TCP<br />
Where 8888 is the port the host should listen on and 80 is the port the VM will send Apache's signal on.<br />
<br />
To use a port lower than 1024 on the host machine, changes need to be made to the firewall on that host machine. This can also be set up to work with SSH or any other services by changing "Apache" to the corresponding service and ports. <br />
<br />
{{note|{{ic|pcnet}} refers to the network card of the VM. If you use an Intel card in your VM settings, change {{ic|pcnet}} to {{ic|e1000}}.}}<br />
<br />
To communicate between the VirtualBox guest and host using ssh, the server port must be forwarded under Settings > Network. When connecting from the client/host, connect to the IP address of the client/host machine, as opposed to the connection of the other machine. This is because the connection will be made over a virtual adapter.<br />
<br />
=== D3D acceleration in Windows guests ===<br />
<br />
Recent versions of Virtualbox have support for accelerating OpenGL inside guests. This can be enabled with a simple checkbox in the machine's settings, right below where video ram is set, and installing the Virtualbox guest additions. However, most Windows games use Direct3D (part of DirectX), not OpenGL, and are thus not helped by this method. However, it is possible to gain accelerated Direct3D in your Windows guests by borrowing the d3d libraries from Wine, which translate d3d calls into OpenGL, which is then accelerated. These libraries are now part of Virtualbox guest additions software. <br />
<br />
After enabling OpenGL acceleration as described above, reboot the guest into safe mode (press F8 before the Windows screen appears but after the Virtualbox screen disappears), and install Virtualbox guest additions, during install enable checkbox "Direct3D support". Reboot back to normal mode and you should have accelerated Direct3D. <br />
<br />
{{Note | This hack may or may not work for some games depending on what hardware checks they make and what parts of D3D they use.}}<br />
{{Note | This was tested on Windows XP, 7 and 8.1. If method does not work on your Windows version please add data here.}}<br />
<br />
=== VirtualBox on a USB key ===<br />
When using VirtualBox on a USB key, for example to start an installed machine with an ISO image, you will manually have to create VDMKs from the existing drives. However, once the new VMDKs are saved and you move on to another machine, you may experience problems launching an appropriate machine again. To get rid of this issue, you can use the following script to launch VirtualBox. This script will clean up and unregister old VMDK files and it will create new, proper VMDKs for you:<br />
{{bc|<nowiki><br />
#!/bin/bash<br />
<br />
# Erase old VMDK entries<br />
rm ~/.VirtualBox/*.vmdk<br />
<br />
# Clean up VBox-Registry<br />
sed -i '/sd/d' ~/.VirtualBox/VirtualBox.xml<br />
<br />
# Remove old harddisks from existing machines<br />
find ~/.VirtualBox/Machines -name \*.xml | while read file; do<br />
line=`grep -e "type\=\"HardDisk\"" -n $file | cut -d ':' -f 1`<br />
if [ -n "$line" ]; then<br />
sed -i ${line}d $file<br />
sed -i ${line}d $file<br />
sed -i ${line}d $file<br />
fi<br />
sed -i "/rg/d" $file<br />
done<br />
<br />
# Delete prev-files created by VirtualBox<br />
find ~/.VirtualBox/Machines -name \*-prev -exec rm '{}' \;<br />
<br />
# Recreate VMDKs<br />
ls -l /dev/disk/by-uuid | cut -d ' ' -f 9,11 | while read ln; do<br />
if [ -n "$ln" ]; then<br />
uuid=`echo "$ln" | cut -d ' ' -f 1`<br />
device=`echo "$ln" | cut -d ' ' -f 2 | cut -d '/' -f 3 | cut -b 1-3`<br />
<br />
# determine whether drive is mounted already<br />
checkstr1=`mount | grep $uuid`<br />
checkstr2=`mount | grep $device`<br />
checkstr3=`ls ~/.VirtualBox/*.vmdk | grep $device`<br />
if [[ -z "$checkstr1" && -z "$checkstr2" && -z "$checkstr3" ]]; then<br />
VBoxManage internalcommands createrawvmdk -filename ~/.VirtualBox/$device.vmdk -rawdisk /dev/$device -register<br />
fi<br />
fi<br />
done<br />
<br />
# Start VirtualBox<br />
VirtualBox<br />
</nowiki>}}<br />
Note that your user has to be added to the "disk" group to create VMDKs out of existing drives.<br />
<br />
=== Run a native Arch Linux installation inside VirtualBox ===<br />
<br />
If you have a dual boot system between Arch Linux and another operating system, it can become rapidly tedious to switch back and forth if you need to work in both. Also, by using virtual machines, you just have a tiny fragment of your computer power, which can cause issues when working on projects requiring performance.<br />
<br />
This guide will let you reuse, in a virtual machine, your native Arch Linux installation when you are running your second operating system. This way, you keep the ability to run each operating system natively, but have the option to run your Arch Linux installation inside a virtual machine.<br />
<br />
==== Make sure you have a persistent naming scheme ====<br />
<br />
Depending on your hard drive setup, device files representing your hard drives may appear differently when you will run your Arch Linux installation natively or in virtual machine. This problem occurs when using [[RAID#Implementation|FakeRAID]] for example. The fake RAID device will be mapped in {{ic|/dev/mapper/}} when you run your GNU/Linux distribution natively, while the devices are still accessible separately. However, in your virtual machine, it can appear without any mapping in {{ic|/dev/sdaX}} for example, because the drivers controlling the fake RAID in your host operating system (e.g. Windows) are abstracting the fake RAID device.<br />
<br />
To circumvent this problem, we will need to use an addressing scheme that is persistent to both systems. This can be achieved using [[Fstab#UUIDs|UUIDs]] in your {{ic|/etc/fstab}} file. Make sure your [[fstab]] file is using UUIDs, otherwise fix this issue. Read [[fstab]] and [[Persistent block device naming]].<br />
<br />
{{ic|/etc/fstab}} is not the only location where UUIDs are used. Bootloaders and boot managers make use of them too. Now, make sure these are really using UUIDs.<br />
<br />
; [[GRUB Legacy]]<br />
If you are still using the old [[GRUB Legacy]], maybe is it [[GRUB Legacy#Upgrading to GRUB2|time to upgrade]], since this package is now dropped from the official Arch Linux repositories. If you want to keep it, edit {{ic|/boot/grub/menu.lst}} and replace the {{ic|1=root=/dev/sdXX}} statement in your Arch Linux boot entry by the Linux UUID mapping in {{ic|/dev/disk/by-uuid/}} corresponding to your root partition.<br />
<br />
title Arch Linux<br />
root<br />
kernel /vmlinuz-linux root=''/dev/disk/by-uuid/0a3407de-014b-458b-b5c1-848e92a327a3'' ro vga=773<br />
initrd /initramfs-linux-vbox.img<br />
<br />
Repeat the process here, for the fallback entry.<br />
<br />
; [[GRUB]]<br />
If you are running the most recent version of [[GRUB]]; you have nothing to do. Yet another reason to upgrade to GRUB 2.<br />
<br />
{{Warning|<br />
* Make sure your host partition is only accessible in read only from your Arch Linux virtual machine, this will avoid risk of corruptions if you were to corrupt that host partition by writing on it due to lack of attention.<br />
* You should NEVER allow VirtualBox to boot from the entry of your second operating system, which, as a reminder, is used as the host for this virtual machine! Take thus a special care especially if your default boot loader/boot manager entry is your other operating system. Give a more important timeout or put it below in the order of preferences.}}<br />
<br />
==== Make sure your mkinitcpio image is correct ====<br />
<br />
Make sure your [[Mkinitcpio|mkinitcpio]] configuration uses the [[Mkinitcpio#HOOKS|HOOK]] {{ic|block}}:<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
[...]<br />
HOOKS="base udev autodetect modconf ''block'' filesystems keyboard fsck"<br />
[...]}}<br />
<br />
If it is not present, add it and [[Mkinitcpio#Image creation and activation|regenerate your initramfs]]:<br />
<br />
# mkinitcpio -p linux<br />
<br />
==== Create a VM configuration to boot from the physical drive ====<br />
<br />
===== Create a raw disk .vmdk image =====<br />
<br />
Now, we need to create a new virtual machine which will use a [https://www.virtualbox.org/manual/ch09.html#rawdisk RAW disk] as virtual drive, for that we will use a ~ 1Kio VMDK file which will be mapped to a physical disk. Unfortunately, VirtualBox does not have this option in the GUI, so we will have to use the console and use an internal command of {{ic|VBoxManage}}.<br />
<br />
Boot the host which will use the Arch Linux virtual machine. The command will need to be adapted according to the host you have.<br />
<br />
; On a GNU/Linux host:<br />
<br />
There is 3 ways to achieve this: login as root, changing the access right of the device with {{ic|chmod}}, adding your user to the {{ic|disk}} group. The latter way is the more elegant, let us proceed that way:<br />
<br />
# gpasswd -a ''your_user'' disk<br />
<br />
Apply the new group settings with:<br />
<br />
$ newgrp<br />
<br />
Now, you can use the command:<br />
<br />
$ VBoxManage internalcommands createrawvmdk -filename ''/path/to/file.vmdk'' -rawdisk ''/dev/sdb'' -register <br />
<br />
Adapt the above command to your need, especially the path and filename of the VMDK location and the raw disk location to map which contain your Arch Linux installation.<br />
<br />
; On a Windows host:<br />
<br />
Open a command prompt must be run as administrator. {{Tip|On Windows, open your start menu/start screen, type {{ic|cmd}}, and type {{ic|Ctrl+Shift+Enter}}, this is a shortcut to execute the selected program with admin rights.}}<br />
<br />
On Windows, as the disk filename convention is different from UNIX, use this command to determine what drives you have in your Windows system and their location:{{hc|# wmic diskdrive get name,size,model|<br />
Model Name Size<br />
WDC WD40EZRX-00SPEB0 ATA Device \\.\PHYSICALDRIVE1 4000783933440<br />
KINGSTON SVP100S296G ATA Device \\.\PHYSICALDRIVE0 96024821760<br />
Hitachi HDT721010SLA360 ATA Device \\.\PHYSICALDRIVE2 1000202273280<br />
Innostor Ext. HDD USB Device \\.\PHYSICALDRIVE3 1000202273280}}<br />
<br />
In this example, as the Windows convention is {{ic|\\.\PhysicalDriveX}} where X is a number from 0, {{ic|\\.\PHYSICALDRIVE1}} could be analogous to {{ic|/dev/sdb}} from the Linux disk terminology.<br />
<br />
To use the {{ic|VBoxManage}} command on Windows, you can either, change the current directory to your VirtualBox installation folder first with {{ic|cd C:\Program Files\Oracle\VirtualBox\}}<br />
<br />
# .\VBoxManage.exe internalcommands createrawvmdk -filename C:\file.vmdk -rawdisk \\.\PHYSICALDRIVE1<br />
<br />
or use the absolute path name: <br />
<br />
# "C:\Program Files\Oracle\VirtualBox\VBoxManage.exe" internalcommands createrawvmdk -filename C:\file.vmdk -rawdisk \\.\PHYSICALDRIVE1<br />
<br />
; On another OS host:<br />
<br />
There are other limitations regarding the aforementioned command when used in other operating systems like OS X, please thus [https://www.virtualbox.org/manual/ch09.html#rawdisk read carefully the manual page], if you are concerned.<br />
<br />
===== Create the VM configuration file =====<br />
<br />
{{Note|<br />
* To make use of the VBoxManage command on Windows, you need to change the current directory to your VirtualBox installation folder first: cd C:\Program Files\Oracle\VirtualBox\.<br />
* Windows makes use of backslashes instead of slashes, please replace all slashes / occurrences by backslashes \ in the commands that follow when you will use them.}}<br />
<br />
After, we need to create a new machine (replace the ''VM_name'' to your convenience) and register it with VirtualBox.<br />
<br />
$ VBoxManage createvm -name ''VM_name'' -register<br />
<br />
Then, the newly raw disk needs to be attached to the machine. This will depend if your computer or actually the root of your native Arch Linux installation is on an IDE or a SATA controller.<br />
<br />
If you need an IDE controller:<br />
<br />
$ VBoxManage storagectl ''VM_name'' --name "IDE Controller" --add ide<br />
$ VBoxManage storageattach ''VM_name'' --storagectl "IDE Controller" --port 0 --device 0 --type hdd --medium /path/to/file.vmdk<br />
<br />
otherwise:<br />
<br />
$ VBoxManage storagectl ''VM_name'' --name "SATA Controller" --add sata<br />
$ VBoxManage storageattach ''VM_name'' --storagectl "SATA Controller" --port 0 --device 0 --type hdd --medium /path/to/file.vmdk<br />
<br />
While you continue using the CLI, it is recommended to use the VirtualBox GUI, to personalise the virtual machine configuration. Indeed, you must specify its hardware configuration as close as possible as your native machine: turning on the 3D acceleration, increasing video memory, setting the network interface, etc.<br />
<br />
==== Install the Guest Additions ====<br />
<br />
Finally, you may want to seamlessly integrate your Arch Linux with your host operating system and allow copy pasting between both OSes. Please refer to [[#Install the Guest Additions]] for that, since this Arch Linux virtual machine is basically an Arch Linux guest.<br />
<br />
{{Warning|For [[Xorg]] to work in natively and in the virtual machine, since obviously it will be using different drivers, it is best if there is no {{ic|/etc/X11/xorg.conf}}, so Xorg will pick up everything it needs on the fly. However, if you really do need your own Xorg configuration, maybe is it worth to set your default systemd target to {{ic|multi-user.target}} with {{ic|systemctl isolate graphical.target}} as root (more details at [[Systemd#Targets table]] and [[Systemd#Change current target]]). In that way, the graphical interface is disabled (i.e. Xorg is not launched) and after you logged in, you can {{ic|startx}}} manually with a custom {{ic|xorg.conf}}.}}<br />
<br />
=== Install a native Arch Linux system from VirtualBox ===<br />
<br />
In some cases it may be useful to install a native Arch Linux system while running another operating system: one way to accomplish this is to perform the installation through VirtualBox on a [http://www.virtualbox.org/manual/ch09.html#rawdisk raw disk]. If the existing operating system is Linux based, you may want to consider following [[Install from Existing Linux]] instead.<br />
<br />
This scenario is very similar to [[#Run a native Arch Linux installation inside VirtualBox]], but will follow those steps in a different order: start by [[#Create a raw disk .vmdk image]], then [[#Create the VM configuration file]].<br />
<br />
Now, you should have a working VM configuration whose virtual VMDK disk is tied to a real disk. The installation process is exactly the same as the steps described in [[#Installation steps for Arch Linux guests]], but [[#Make sure you have a persistent naming scheme]] and [[#Make sure your mkinitcpio image is correct]].<br />
<br />
{{Warning|<br />
*For BIOS systems and MBR disks, do not install a bootloader inside your virtual machine, this will not work since the MBR is not linked to the MBR of your real machine and your virtual disk is only mapped to a real partition without the MBR.<br />
*For UEFI systems without [[Wikipedia:Compatibility Support Module#CSM|CSM]] and GPT disks, the installation will not work at all since:<br />
:*the [[Wikipedia:EFI System partition|ESP]] partition is not mapped to your virtual disk and Arch Linux requires to have the Linux kernel on it to boot as an EFI application (see [[EFISTUB]] for details);<br />
:*and the efivars, if you are installing Arch Linux using the EFI mode brought by VirtualBox, are not the one of your real system: the bootmanager entries will hence not be registered.<br />
*This is why, it is recommended to create your partitions in a native installation first, otherwize the partitions will not be taken into consideration in your MBR/GPT partition table.}}<br />
<br />
After completing the installation, boot your computer natively with an GNU/Linux installation media (whether it be Arch Linux or not), [[Beginner's Guide#Chroot and configure the base system|chroot]] into your installed Arch Linux installation and [[Beginner's Guide#Install and configure a bootloader|#Install and configure a bootloader]].<br />
<br />
=== Move a native Windows installation to a virtual machine ===<br />
<br />
If you want to migrate an existing native Windows installation to a virtual machine which will be used with VirtualBox on GNU/Linux, this use case is for you. This section only covers native Windows installation using the MSDOS/Intel partition scheme. Your Windows installation must reside on the first MBR partition for this operation to success. Operation for other partitions are available but have been untested (see [[#Known limitations]] for details).<br />
<br />
{{Warning|If you are using an OEM version of Windows, this process is unauthorized by the end user license license. Indeed, the OEM license typically states the Windows install is tied with the hardware together. Transferring a Windows install to a virtual machine removes this link. Make thus sure you have a full Windows install or a volume license model before continuing. If you have a full Windows license but the latter is not coming in volume, nor as a special license for several PCs, this means you will have to remove the native installation after the transfer operation has been achieved.}}<br />
<br />
A couple of tasks are required to be done inside your native Windows installation first, then on your GNU/Linux host.<br />
<br />
==== Tasks on Windows ====<br />
<br />
The first three following points comes from [https://www.virtualbox.org/wiki/Migrate_Windows#HAL this outdated VirtualBox wiki page], but are updated here.<br />
<br />
* Remove IDE/ATA controllers checks (Windows XP only): Windows memorize the IDE/ATA drive controllers it has been installed on and will not boot if it detects these have changed. The solution proposed by Microsoft is to reuse the same controller or use one of the same serial, which is impossible to achieve since we are using a Virtual Machine. [https://www.virtualbox.org/wiki/Migrate_Windows#HardDiskSupport MergeIDE], a German tool, developped upon another other solution proposed by Microsoft can be used. That solution basically consists in taking all IDE/ATA controller drivers supported by Windows XP from the initial driver archive (the location is hard coded, or specify it as the first argument to the {{ic|.bat}} script), installing them and registering them with the regedit database.<br />
<br />
* Use the right type of Hardware Abstraction Layer (old 32 bits Windows versions): Microsoft ships 3 default versions: {{ic|Hal.dll}} (Standard PC), {{ic|Halacpi.dll}} (ACPI HAL) and {{ic|Halaacpi.dll}} (ACPI HAL with IO APIC). Your Windows install could come installed with the first or the second version. In that way, please [https://www.virtualbox.org/manual/ch08.html#idp56927888 disable the ''Enable IO/APIC'' VirtualBox extended feature].<br />
<br />
* Disable any AGP device driver (only outdated Windows versions): If you have the files {{ic|agp440.sys}} or {{ic|intelppm.sys}} inside the {{ic|C:\Windows\SYSTEM32\drivers\}} directory, remove it. As VirtualBox uses a PCI virtual graphic card, this can cause problems when this AGP driver is used.<br />
<br />
* Create a Windows recovery disk: In the following steps, if things turn bad, you will need to repair your Windows installation. Make sure you have an install media at hand, or create one with ''Create a recovery disk'' from Vista SP1, ''Create a system repair disc'' on Windows 7 or ''Create a recovery drive'' on Windows 8.x).<br />
<br />
==== Tasks on GNU/Linux ====<br />
<br />
* Reduce the native Windows partition size to the size Windows actually needs with {{ic|ntfsresize}} available from {{Pkg|ntfs-3g}}. The size you will specify will be the same size of the VDI that will be created in the next step. If this size is too low, you may break your Windows install and the latter might not boot at all.<br />
<br />
:Use the {{ic|--no-action}} option first to run a test:<br />
:{{bc|# ntfsresize --no-action --size ''52Gi'' ''/dev/sda1''}}<br />
<br />
:If only the previous test succeeded, execute this command again, but this time without the aforementioned test flag.<br />
<br />
* Install VirtualBox on your GNU/Linux host (see [[#Installation steps for Arch Linux hosts]] if your host is Arch Linux).<br />
<br />
* Create the Windows disk image from the beginning of the drive to the end of the first partition where is located your Windows installation. Copying from the beginning of the disk is necessary because the MBR space at the beginning of the drive needs to be on the virtual drive along with the Windows partition. In this example two following partitions {{ic|sda2}} and {{ic|sda3}}will be later removed from the partition table and the MBR bootloader will be updated.<br />
<br />
:{{bc|<nowiki># sectnum=$(( $(cat /sys/block/''sda/sda1''/start) + $(cat /sys/block/''sda/sda1''/size) ))</nowiki>}}<br />
:Using {{ic|cat /sys/block/''sda/sda1''/size}} will output the number of total sectors of the first partition of the disk {{ic|sda}}. Adapt where necessary.<br />
<br />
:{{bc|<nowiki># dd if=''/dev/sda'' bs=512 count=$sectnum | VBoxManage convertfromraw stdin ''windows.vdi'' $(( $sectnum * 512 ))</nowiki>}}<br />
:We need to display the size in byte, {{ic|$(( $sectnum * 512 ))}} will convert the sector numbers to bytes.<br />
<br />
* Since you created your disk image as root, set the right ownership to the virtual disk image: {{bc|# chown ''your_user'':''your_group'' windows.vdi}}<br />
<br />
* Create your virtual machine configuration file and use the virtual disk created previously as the main virtual hard disk.<br />
<br />
* Try to boot your Windows VM, it may just work. First though remove and repair disks from the boot process as it may interfere (and likely will) booting into safe-mode.<br />
<br />
* Attempt to boot your Windows virtual machine in safe mode (press the F8 key before the Windows logo shows up)... if running into boot issues, read [[#Fix MBR and Microsoft bootloader]]. In safe-mode, drivers will be installed likely by the Windows plug-and-play detection mechanism [http://i.imgur.com/hh1RrSp.png view]. Additionally, install the VirtualBox Guest Additions via the menu ''Devices'' > ''Insert Guest Additions CD image...''. If a new disk dialog does not appear, navigate to the CD drive and start the installer manually.<br />
<br />
* You should finally have a working Windows virtual machine. Do not forget to read the [[#Known limitations]].<br />
<br />
==== Fix MBR and Microsoft bootloader ====<br />
<br />
If your Windows virtual machine refuses to boot, you may need to apply the following modifications to your virtual machine.<br />
<br />
*Boot a GNU/Live live distribution inside your virtual machine before Windows starts up.<br />
<br />
*Remove other partitions entries from the virtual disk MBR. Indeed, since we copied the MBR and only the Windows partition, the entries of the other partitions are still present in the MBR, but the partitions are not available anymore. Use {{ic|fdisk}} to achieve this for example.<br />
:{{bc|<nowiki>fdisk ''/dev/sda''<br />
Command (m for help): a<br />
Partition number (''1-3'', default ''3''): ''1''</nowiki>}}<br />
<br />
*Write the updated partition table to the disk (this will recreate the MBR) using the {{ic|m}} command inside {{ic|fdisk}}.<br />
<br />
*Use {{Pkg|testdisk}} (see [http://www.cgsecurity.org/index.html?testdisk.html here] for details) to add a generic MBR:<br />
:{{bc|# testdisk > ''Disk /dev/sda...''' > [Proceed] > [Intel] Intel/PC partition > [MBR Code] Write TestDisk MBR to first sector > Write a new copy of MBR code to first sector? (Y/n) > Y > Write a new copy of MBR code, confirm? (Y/N) > A new copy of MBR code has been written. You have to reboot for the change to take effect. > [OK]}}<br />
<br />
*With the new MBR and updated partition table, your Windows virtual machine should be able to boot. If you are still encountering issues, boot your Windows recovery disk from on of the previous step, and inside your Windows RE environment, execute the commands [http://support.microsoft.com/kb/927392 described here].<br />
<br />
==== Known limitations ====<br />
<br />
*Your virtual machine can sometimes hang and overrun your RAM, this can be caused by conflicting drivers still installed inside your Windows virtual machine. Good luck to find them!<br />
*Additional software expecting a given driver beneath may either not be disabled/uninstalled or needs to be uninstalled first as the drivers that are no longer available.<br />
*Your Windows installation must reside on the first partition for the above process to work. If this requirement is not met, the process might be achieved too, but this had not been tested. This will require either copying the MBR and editing in hexadecimal see [http://superuser.com/questions/237782/virtualbox-booting-cloned-disk/253417#253417 VirtualBox: booting cloned disk] or will require to fix the partition table [http://gparted.org/h2-fix-msdos-pt.php manually] or by repairing Windows with the recovery disk you created in a previous step. Let us consider our Windows installation on the second partition; we will copy the MBR, then the second partition where to the disk image. {{ic|VBoxManage convertfromraw}} needs the total number of bytes that will be written: calculated thanks to the size of the MBR (the start of the first partition) plus the size of the second (Windows) partition. {{ic|<nowiki>{ dd if=/dev/sda bs=512 count=$(cat /sys/block/sda/sda1/start) ; dd if=/dev/sda2 bs=512 count=$(cat /sys/block/sda/sda2/size) ; } | VBoxManage convertfromraw stdin windows.vdi $(( ($(cat /sys/block/sda/sda1/start) + $(cat /sys/block/sda/sda2/size)) * 512 ))</nowiki>}}.<br />
<br />
== Troubleshooting ==<br />
<br />
=== VERR_ACCESS_DENIED ===<br />
<br />
To access the raw vmdk image on a windows host, run the VirtualBox GUI as administrator.<br />
<br />
=== Keyboard and mouse are blocked in my virtual machine ===<br />
<br />
This means your virtual machine has captured the input of your keyboard and your mouse. Simply press the right {{ic|Ctrl}} key and your input should control your host again.<br />
<br />
To control transparently your virtual machine with your mouse going back and forth your host, without having to press any key, and thus have a seamless integration, install the guest additions inside the guest. Read from the [[#Install the Guest Additions]] step if you guest is Arch Linux, otherwise read the official VirtualBox help.<br />
<br />
=== Cannot send CTRL+ALT+Fn key to my virtual machine ===<br />
<br />
Your guest operating system is a GNU/Linux distribution and you want to open a new TTY shell by hitting {{ic|Ctrl+Alt+F2}} or exit your current X session with {{ic|Ctrl+Alt+Backspace}}. If you type these keyboard shortcuts without any adaptation, the guest will not receive any input and the host (if it is a GNU/Linux distribution too) will intercept these shortcut keys. To send {{ic|Ctrl+Alt+F2}} to the guest for example, simply hit your ''Host Key'' (usually the right {{ic|Ctrl}} key) and press {{ic|F2}} simultaneously.<br />
<br />
=== Fix ISO images problems ===<br />
<br />
While VirtualBox can mount ISO images without problem, there are some image formats which cannot reliably be converted to ISO. For instance, ccd2iso ignores .ccd and .sub files, which can give disk images with broken files. <br />
<br />
In this case, you will either have to use [[CDEmu]] for Linux inside VirtualBox or any other utility used to mount disk images.<br />
<br />
=== VirtualBox GUI does not match my GTK Theme ===<br />
<br />
See [[Uniform Look for Qt and GTK Applications]] for information about theming Qt based applications like Virtualbox.<br />
<br />
=== OpenBSD unusable when virtualisation instructions unavailable ===<br />
<br />
While OpenBSD is reported to work fine on other hypervisors without virtualisation instructions (VT-x AMD-V) enabled, an OpenBSD virtual machine running on VirtualBox without these instructions will be unusable, manifesting with a bunch of segmentation faults. Starting VirtualBox with the ''-norawr0'' argument [https://www.virtualbox.org/ticket/3947 may solve the problem]. You can do it like this:<br />
$ VBoxSDL -norawr0 -vm ''name_of_OpenBSD_VM''<br />
<br />
=== VBOX_E_INVALID_OBJECT_STATE (0x80BB0007) ===<br />
<br />
This can occur if a VM is exited ungracefully. The solution to unlock the VM is trivial:<br />
$ VBoxManage controlvm ''virtual_machine_name'' poweroff<br />
<br />
=== USB subsystem is not working on the host or guest ===<br />
<br />
Your user must be in the {{ic|vboxusers}} group, and you need to install the [[#Extension pack|extension pack]] if you want USB 2 support. Then you will be able to enable USB 2 in the VM settings and add one or several filters for the devices you want to access from the guest OS.<br />
<br />
If {{ic|VBoxManage list usbhost}} does not show any USB devices even if run as root, make sure that there is no old udev rules (from VirtualBox 4.x) in ''/etc/udev/rules.d/''. VirtualBox 5.0 installs udev rules to ''/usr/lib/udev/rules.d/''. You can use command like {{ic|pacman -Qo /usr/lib/udev/rules.d/60-vboxdrv.rules}} to determine if the udev rule file is outdated.<br />
<br />
Sometimes, on old Linux hosts, the USB subsystem is not auto-detected resulting in an error {{ic|Could not load the Host USB Proxy service: VERR_NOT_FOUND}} or in a not visible USB drive on the host, [https://bbs.archlinux.org/viewtopic.php?id=121377 even when the user is in the '''vboxusers''' group]. This problem is due to the fact that VirtualBox switched from ''usbfs'' to ''sysfs'' in version 3.0.8. If the host does not understand this change, you can revert to the old behaviour by defining the following environment variable in any file that is sourced by your shell (e.g. your {{ic|~/.bashrc}} if you are using ''bash''):<br />
<br />
{{hc|~/.bashrc|VBOX_USB<nowiki>=</nowiki>usbfs}}<br />
<br />
Then make sure, the environment has been made aware of this change (reconnect, source the file manually, launch a new shell instance or reboot).<br />
<br />
Also make sure that your user is a member of the {{ic|storage}} group.<br />
<br />
=== Failed to create the host-only network interface ===<br />
<br />
Make sure all required kernel modules are loaded. See [[#Load the VirtualBox kernel modules]].<br />
<br />
=== WinXP: Bit-depth cannot be greater than 16 ===<br />
<br />
If you are running at 16-bit color depth, then the icons may appear fuzzy/choppy. However, upon attempting to change the color depth to a higher level, the system may restrict you to a lower resolution or simply not enable you to change the depth at all. To fix this, run {{ic|regedit}} in Windows and add the following key to the Windows XP VM's registry:<br />
[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows NT\Terminal Services]<br />
"ColorDepth"=dword:00000004<br />
<br />
Then update the color depth in the "desktop properties" window. If nothing happens, force the screen to redraw through some method (i.e. {{ic|Host+f}} to redraw/enter full screen).<br />
<br />
=== Use serial port in guest OS ===<br />
<br />
Check you permission for the serial port:<br />
$ /bin/ls -l /dev/ttyS*<br />
crw-rw---- 1 root uucp 4, 64 Feb 3 09:12 /dev/ttyS0<br />
crw-rw---- 1 root uucp 4, 65 Feb 3 09:12 /dev/ttyS1<br />
crw-rw---- 1 root uucp 4, 66 Feb 3 09:12 /dev/ttyS2<br />
crw-rw---- 1 root uucp 4, 67 Feb 3 09:12 /dev/ttyS3<br />
<br />
Add your user to the {{ic|uucp}} group.<br />
# gpasswd -a $USER uucp <br />
and log out and log in again.<br />
<br />
=== Windows 8.x Error Code 0x000000C4===<br />
<br />
If you get this error code while booting, even if you choose OS Type Win 8, try to enable the {{ic|CMPXCHG16B}} CPU instruction:<br />
<br />
$ vboxmanage setextradata ''virtual_machine_name'' VBoxInternal/CPUM/CMPXCHG16B 1<br />
<br />
=== Windows 8 VM fails to boot with error "ERR_DISK_FULL" ===<br />
<br />
Situation: Your Windows 8 VM refuses to start. VirtualBox throws an error stating the virtual disk is full. However, you are certain that the disk is not full. <br />
Bring up your VM's settings at ''Settings > Storage > Controller:SATA'' and select "Use Host I/O Cache".<br />
<br />
=== Linux guests have slow/distorted audio ===<br />
<br />
The AC97 audio driver within the Linux kernel occasionally guesses the wrong clock settings when running inside Virtual Box, leading to audio that is either too slow or too fast. To fix this, create a file in {{ic|/etc/modprobe.d}} with the following line:<br />
<br />
options snd-intel8x0 ac97_clock=48000<br />
<br />
=== Guest freezes after starting Xorg ===<br />
<br />
Faulty or missing drivers may cause the guest to freeze after starting Xorg, see for example [https://bbs.archlinux.org/viewtopic.php?pid=1167838] and [https://bbs.archlinux.org/viewtopic.php?id=156079]. Try disabling 3D acceleration in ''Settings > Display'', and check if all [[Xorg]] drivers are installed.<br />
<br />
=== "NS_ERROR_FAILURE" and missing menu items ===<br />
<br />
If you encounter this message when first time starting the virtual machine:<br />
<br />
{{bc|Failed to open a session for the virtual machine debian.<br />
Could not open the medium '/home/.../VirtualBox VMs/debian/debian.qcow'.<br />
QCow: Reading the L1 table for image '/home/.../VirtualBox VMs/debian/debian.qcow' failed (VERR_EOF).<br />
VD: error VERR_EOF opening image file '/home/.../VirtualBox VMs/debian/debian.qcow' (VERR_EOF).<br />
<br />
Result Code: <br />
NS_ERROR_FAILURE (0x80004005)<br />
Component: <br />
Medium<br />
}}<br />
<br />
Exit VirtualBox, delete all files of the new machine and from virtualbox config file remove the last line in {{ic|MachineRegistry}} menu (or the offending machine you are creating):<br />
<br />
{{hc|~/.config/VirtualBox/VirtualBox.xml|2=<br />
...<br />
<MachineRegistry><br />
<MachineEntry uuid="{00000000-0000-0000-0000-000000000000}" src="/home/void/VirtualBox VMs/debian/debian.vbox"/><br />
<MachineEntry uuid="{00000000-0000-0000-0000-000000000000}" src="/home/void/VirtualBox VMs/ubuntu/ubuntu.vbox"/><br />
<strike><MachineEntry uuid="{00000000-0000-0000-0000-000000000000}" src="/home/void/VirtualBox VMs/lastvmcausingproblems/lastvmcausingproblems.qcow"/></strike><br />
</MachineRegistry><br />
...<br />
}}<br />
<br />
This happens sometimes when selecting ''QCOW''/''QCOW2''/''QED'' disk format when creating a new virutal disk.<br />
<br />
=== USB modem ===<br />
<br />
If you have a USB modem which is being used by the guest OS, killing the guest OS can cause the modem to become unusable by the host system. Killing and restarting {{ic|VBoxSVC}} should fix this problem.<br />
<br />
=== "The specified path does not exist. Check the path and then try again." error in Windows guests ===<br />
<br />
This error message often appears when running an .exe file which requires administrator priviliges from a shared folder in windows guests. See [https://www.virtualbox.org/ticket/5732 the bug report] for details.<br />
<br />
There are several workarounds:<br />
<br />
# Disable UAC from Control Panel -> Action Center -> "Change User Account Control settings" from left side pane -> set slider to "Never notify" -> OK and reboot<br />
# Copy the file from the shared folder to the guest and run from there<br />
# Control Panel -> Network and Internet -> Internet Options -> Security -> Trusted Sites -> Sites -> Add "VBOXSVR" as a website<br />
# Start -> type "gpedit.msc" and press Enter -> Computer Configuration -> Administrative Templates -> Windows Components -> Internet Explorer -> Internet Control Panel -> Security Page -> Size to Zone Assignment List -> Add "VBOXSVR" to "2" and reboot<br />
<br />
{{Accuracy|Haven't tested#3 and #4 workarounds myself. If someone can confirm that they are working as well, please delete this note/template.}}<br />
<br />
=== No 64-bit OS client options ===<br />
<br />
When launching a VM client, and no 64-bit options are available, make sure your CPU virtualization capabilities (usually named {{ic|VT-x}}) are enabled in the BIOS.<br />
<br />
=== Host OS freezes on Virtual Machine start ===<br />
<br />
{{Expansion|Needs a link to a bug report; vague expressions like "currently" and "at the moment of writing" are of no help.}}<br />
<br />
This is a known incompatiblity with SMAP enabled kernels affecting (mostly) Intel Broadwell chipsets.<br />
<br />
The matter is currently being investigated, with a wide variety of WIP vboxhost module patches out in the wild that are meant to solve the issue.<br />
<br />
At the moment of writing though, the only 100% guaranteed solution to this problem is disabling SMAP support in your kernel by appending the "nosmap" option to your kernel boot command line.<br />
<br />
== See also ==<br />
<br />
* [https://www.virtualbox.org/manual/UserManual.html VirtualBox User Manual]<br />
* [[Wikipedia:VirtualBox]]</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Arch_User_Repository&diff=377931Arch User Repository2015-06-08T22:44:09Z<p>Fylwind: /* Submitting packages to aur4.archlinux.org */ mention alternative SSH URL format for Git remotels</p>
<hr />
<div>[[Category:Arch User Repository]]<br />
[[Category:Package development]]<br />
[[Category:Package management]]<br />
[[ar:Arch User Repository]]<br />
[[cs:Arch User Repository]]<br />
[[da:Arch User Repository]]<br />
[[de:Arch User Repository]]<br />
[[el:Arch User Repository]]<br />
[[es:Arch User Repository]]<br />
[[fi:AUR]]<br />
[[fr:AUR]]<br />
[[it:Arch User Repository]]<br />
[[ja:Arch User Repository]]<br />
[[nl:Arch User Repository]]<br />
[[pl:Arch User Repository]]<br />
[[pt:Arch User Repository]]<br />
[[ro:AUR]]<br />
[[ru:Arch User Repository]]<br />
[[sr:Arch User Repository]]<br />
[[tr:Arch Kullanıcı Deposu]]<br />
[[uk:Arch User Repository]]<br />
[[zh-CN:Arch User Repository]]<br />
{{Related articles start}}<br />
{{Related|AUR helpers}}<br />
{{Related|AurJson}}<br />
{{Related|AUR Trusted User Guidelines}}<br />
{{Related|PKGBUILD}}<br />
{{Related|makepkg}}<br />
{{Related|pacman}}<br />
{{Related|Official repositories}}<br />
{{Related|Arch Build System}}<br />
{{Related|Creating packages}}<br />
{{Related articles end}}<br />
<br />
The Arch User Repository (AUR) is a community-driven repository for Arch users. It contains package descriptions ([[PKGBUILD]]s) that allow you to compile a package from source with [[makepkg]] and then install it via [[pacman#Additional commands|pacman]]. The AUR was created to organize and share new packages from the community and to help expedite popular packages' inclusion into the [[community]] repository. This document explains how users can access and utilize the AUR.<br />
<br />
A good number of new packages that enter the official repositories start in the AUR. In the AUR, users are able to contribute their own package builds (PKGBUILD and related files). The AUR community has the ability to vote for or against packages in the AUR. If a package becomes popular enough &mdash; provided it has a compatible license and good packaging technique &mdash; it may be entered into the ''community'' repository (directly accessible by [[pacman]] or [[abs]]).<br />
<br />
== Getting started ==<br />
<br />
Users can search and download PKGBUILDs from the [https://aur.archlinux.org AUR Web Interface]. These PKGBUILDs can be built into installable packages using [[makepkg]], then installed using pacman. <br />
<br />
* Ensure the {{Grp|base-devel}} package group is installed ({{ic|pacman -S --needed base-devel}}).<br />
* Read the remainder of this article for more info and a short tutorial on installing AUR packages.<br />
* Visit the [https://aur.archlinux.org AUR Web Interface] to inform yourself on updates and happenings. There you will also find statistics and an up-to-date list of newest available packages available in AUR.<br />
* Glance over the [[#FAQ]] for answers to the most common questions.<br />
* You may wish to adjust {{ic|/etc/makepkg.conf}} to better optimize for your processor prior to building packages from the AUR. A significant improvement in compile times can be realized on systems with multi-core processors by adjusting the MAKEFLAGS variable. Users can also enable hardware-specific optimizations in GCC via the CFLAGS variable. See [[makepkg]] for more information.<br />
<br />
== History ==<br />
<br />
The following items are listed for historical purposes only. They have since been superseded by the AUR and are no longer available.<br />
<br />
In the beginning, there was {{ic|<nowiki>ftp://ftp.archlinux.org/incoming</nowiki>}}, and people contributed by simply uploading the PKGBUILD, the needed supplementary files, and the built package itself to the server. The package and associated files remained there until a [[Package Maintainer]] saw the program and adopted it.<br />
<br />
Then the Trusted User Repositories were born. Certain individuals in the community were allowed to host their own repositories for anyone to use. The AUR expanded on this basis, with the aim of making it both more flexible and more usable. In fact, the AUR maintainers are still referred to as TUs (Trusted Users).<br />
<br />
== Searching ==<br />
<br />
The AUR web interface can be found at https://aur.archlinux.org/, and an interface suitable for accessing the AUR from a script can be found at https://aur.archlinux.org/rpc.php.<br />
<br />
Queries search package names and descriptions via a MySQL LIKE comparison. This allows for more flexible search criteria (e.g. try searching for {{ic|tool%like%grep}} instead of {{ic|tool like grep}}). If you need to search for a description that contains {{ic|%}}, escape it with {{ic|\%}}.<br />
<br />
== Installing packages ==<br />
<br />
Installing packages from the AUR is a relatively simple process. Essentially:<br />
<br />
# Acquire the tarball which contains the [[PKGBUILD]] and possibly other required files, like systemd-units and patches (but often not the actual code).<br />
# Extract the tarball (preferably in a folder set aside just for builds from the AUR) with {{ic|tar -xvf foo.tar.gz}}.<br />
# Run {{ic|makepkg}} in the directory where the files are saved ({{ic|makepkg -s}} will automatically resolve dependencies with pacman). This will download the code, compile it and pack it.<br />
# Look for a README file in {{ic|src/}}, as it might contain information needed later on.<br />
# Install the resulting package with [[pacman]]:<br />
<br />
: {{bc|# pacman -U /path/to/pkg.tar.xz}}<br />
<br />
[[AUR helpers]] add seamless access to the AUR. They vary in their features but can ease in searching, fetching, building, and installing from PKGBUILDs found in the AUR. All of these scripts can be found in the AUR.<br />
<br />
{{Warning|There is not and will never be an ''official'' mechanism for installing build material from the AUR. '''All AUR users should be familiar with the build process.'''}}<br />
<br />
=== Prerequisites ===<br />
<br />
First ensure that the necessary tools are installed. The package group {{grp|base-devel}} should be sufficient; it includes {{pkg|make}} and other tools needed for compiling from source.<br />
<br />
{{Warning|Packages in the AUR assume the {{grp|base-devel}} group is installed, and AUR packages will not list members of this group as dependencies even if the package cannot be built without them. Please ensure this group is installed before complaining about failed builds.}}<br />
<br />
# pacman -S --needed base-devel<br />
<br />
Next choose an appropriate build directory. A build directory is simply a directory where the package will be made or "built" and can be any directory. Examples of commonly used directories are:<br />
<br />
~/builds<br />
<br />
or if using ABS (the [[Arch Build System]]):<br />
<br />
/var/abs/local<br />
<br />
For more information on ABS read the [[Arch Build System]] article. The example will use {{ic|~/builds}} as the build directory.<br />
<br />
=== Acquire build files ===<br />
<br />
Locate the package in the AUR. This is done using the search feature (text field at the top of the [https://aur.archlinux.org/ AUR home page]). Clicking the application's name in the search list brings up an information page on the package. Read through the description to confirm that this is the desired package, note when the package was last updated, and read any comments.<br />
<br />
Download the necessary build files by clicking on the "Download tarball" link under "Package actions" on the right hand side. This file should be saved to the build directory or otherwise copied to the directory after downloading. In this example, the file is called "foo.tar.gz" (standard format is ''pkgname''.tar.gz, if it has been properly submitted).<br />
<br />
Alternatively you can download the tarball from the terminal, changing directories to the build directory first:<br />
<br />
$ cd ~/builds<br />
$ curl -L -O <nowiki>https://aur.archlinux.org/packages/fo/foo/foo.tar.gz</nowiki><br />
<br />
=== Build the package ===<br />
<br />
Change directories to the build directory if not already there, then extract the previously downloaded package:<br />
<br />
$ cd ~/builds<br />
$ tar -xvf foo.tar.gz<br />
<br />
This should create a new directory called "foo" in the build directory.<br />
<br />
{{Warning|'''Carefully check all files.''' {{ic|cd}} to the newly created directory and carefully check the {{ic|PKGBUILD}} and any {{ic|.install}} file for malicious commands. {{ic|PKGBUILD}}s are bash scripts containing functions to be executed by {{ic|makepkg}}: these functions can contain ''any'' valid commands or Bash syntax, so it is totally possible for a {{ic|PKGBUILD}} to contain dangerous commands through malice or ignorance on the part of the author. Since {{ic|makepkg}} uses fakeroot (and should never be run as root), there is some level of protection but you should never count on it. If in doubt, do not build the package and seek advice on the forums or mailing list.}}<br />
<br />
$ cd foo<br />
$ nano PKGBUILD<br />
$ nano foo.install<br />
<br />
Make the package. After manually confirming the integrity of the files, run [[makepkg]] as a normal user:<br />
<br />
$ makepkg -s<br />
<br />
The {{ic|-s}} switch will use [[sudo]] to install any needed dependencies. If the use of sudo is undesirable, manually install required dependencies beforehand and exclude the {{ic|-s}} in the above command.<br />
<br />
=== Install the package ===<br />
<br />
Install the package using pacman. A tarball should have been created named:<br />
<br />
<''application name''>-<''application version number''>-<''package revision number''>-<''architecture''>.pkg.tar.xz<br />
<br />
This package can be installed using pacman's "upgrade" command:<br />
<br />
# pacman -U foo-0.1-1-i686.pkg.tar.xz <br />
<br />
These manually installed packages are called foreign packages &mdash; packages which have not originated from any repository known to pacman. To list all foreign packages:<br />
$ pacman -Qm <br />
<br />
{{Note|The above example is only a brief summary of the package building process. A visit to the [[makepkg]] and [[ABS]] pages will provide more detail and is highly recommended, especially for first-time users.}}<br />
<br />
== Feedback ==<br />
<br />
The [https://aur.archlinux.org AUR Web Interface] has a comments facility that allows users to provide suggestions and feedback on improvements to the PKGBUILD contributor. Avoid pasting patches or PKGBUILDs into the comments section: they quickly become obsolete and just end up needlessly taking up lots of space. Instead email those files to the maintainer, or even use a [[pastebin]].<br />
<br />
One of the easiest activities for '''all''' Arch users is to browse the AUR and '''vote''' for their favourite packages using the online interface. All packages are eligible for adoption by a TU for inclusion in the [[community]] repository, and the vote count is one of the considerations in that process; it is in everyone's interest to vote!<br />
<br />
== Sharing and maintaining packages ==<br />
<br />
Users can '''share''' PKGBUILDs using the Arch User Repository. It does not contain any binary packages but allows users to upload PKGBUILDs that can be downloaded by others. These PKGBUILDs are completely unofficial and have not been thoroughly vetted, so they should be used at your own risk.<br />
<br />
=== Submitting packages ===<br />
<br />
{{Warning|Before attempting to submit a package you are expected to familiarize yourself with [[Arch packaging standards]] and all articles, mentioned at the bottom of it.}}<br />
<br />
{{Note|The following section describes how to upload packages to aurweb 3.5.1. If you are submitting a package for the first time, please consider directly uploading it to [[#AUR 4|AUR 4]] instead.}}<br />
<br />
After logging in to the AUR web interface, a user can [https://aur.archlinux.org/pkgsubmit.php submit] a gzipped tarball ({{ic|.tar.gz}}) of a directory containing build files for a package. The directory inside the tarball should contain a [[PKGBUILD]], [[#AUR metadata|.SRCINFO]], any {{ic|.install}} files, patches, etc. ('''absolutely''' no binaries). Examples of what such a directory should look like can be seen inside {{ic|/var/abs}} if the [[Arch Build System]] were installed.<br />
<br />
The tarball can be created with the following command:<br />
<br />
$ makepkg --source<br />
<br />
Note that this is a gzipped tarball; assuming you are uploading a package called ''libfoo'', when you create the file it should look similar to this:<br />
<br />
{{hc|$ tar tf libfoo-0.1-1.src.tar.gz|<br />
libfoo/<br />
libfoo/.SRCINFO<br />
libfoo/PKGBUILD<br />
libfoo/libfoo.install}}<br />
<br />
{{Note|The ".SRCINFO" file contains source package metadata, see [[#AUR metadata]] for details.}}<br />
<br />
When submitting a package, observe the following rules:<br />
<br />
* Check the [https://www.archlinux.org/packages/ official package database] for the package. If '''any version''' of it exists, '''do not''' submit the package. If the official package is out-of-date, flag it as such. If the official package is broken or is lacking a feature, then please file a [https://bugs.archlinux.org/ bug report].<br />
* Check the AUR for the package. If it is currently maintained, changes can be submitted in a comment for the maintainer's attention. If it is unmaintained, the package can be adopted and updated as required. Do not create duplicate packages.<br />
* Verify carefully that what you are uploading is correct. All contributors must read and adhere to the [[Arch packaging standards]] when writing PKGBUILDs. This is essential to the smooth running and general success of the AUR. Remember that you are not going to earn any credit or respect from your peers by wasting their time with a bad PKGBUILD.<br />
* Packages that contain binaries or that are very poorly written may be deleted without warning.<br />
* If you are unsure about the package (or the build/submission process) in any way, submit the PKGBUILD to the [https://mailman.archlinux.org/mailman/listinfo/aur-general AUR mailing list] or the [https://bbs.archlinux.org/viewforum.php?id=4 AUR forum] on the Arch forums for public review before adding it to the AUR.<br />
* Make sure the package is useful. Will anyone else want to use this package? Is it extremely specialized? If more than a few people would find this package useful, it is appropriate for submission.<br />
* The AUR and official repositories are intended for packages which install generally software and software-related content, including one or more of the following: executable(s); config file(s); online or offline documentation for specific software or the Arch Linux distribution as a whole; media intended to be used directly by software.<br />
* Gain some experience before submitting packages. Build a few packages to learn the process and then submit.<br />
* If you submit a {{ic|package.tar.gz}} with a file named {{ic|package}} in it you will get an error: "Could not change to directory {{ic|/home/aur/unsupported/package/package}}". To resolve this, rename the file named {{ic|package}} to something else; for example, {{ic|package.rc}}. When it is installed in the {{ic|pkg}} directory, you may rename it back to {{ic|package}}.<br />
<br />
=== Maintaining packages ===<br />
<br />
* If you maintain a package and want to update the PKGBUILD for your package just resubmit it.<br />
* Check for feedback and comments from other users and try to incorporate any improvements they suggest; consider it a learning process!<br />
* Please do not leave a comment containing the version number every time you update the package. This keeps the comment section usable for valuable content mentioned above. [[AUR helpers]] are suited better to check for updates.<br />
* Please do not just submit and forget about packages! It is the maintainer's job to maintain the package by checking for updates and improving the PKGBUILD.<br />
* If you do not want to continue to maintain the package for some reason, {{ic|disown}} the package using the AUR web interface and/or post a message to the AUR Mailing List.<br />
<br />
=== Other requests ===<br />
<br />
* Disownment requests and removal requests can be created by clicking on the "File Request" link under "Package actions" on the right hand side. This automatically sends a notification email to the current package maintainer and to the [https://mailman.archlinux.org/mailman/listinfo/aur-requests aur-requests mailing list] for discussion. [[Trusted Users]] will then either accept or reject the request.<br />
* Disownment requests will be granted after two weeks if the current maintainer did not react.<br />
* '''Package merging has been implemented''', users still have to resubmit a package under a new name and may request merging of the old version's comments and votes.<br />
* Removal requests require the following information:<br />
** Reason for deletion, at least a short note <br> '''Notice:''' A package's comments does not sufficiently point out the reasons why a package is up for deletion. Because as soon as a TU takes action, the only place where such information can be obtained is the aur-requests mailing list.<br />
** Supporting details, like when a package is provided by another package, if you are the maintainer yourself, it is renamed and the original owner agreed, etc.<br />
** For merge requests: Name of the package base to merge into.<br />
<br />
Removal requests can be disapproved, in which case you will likely be advised to disown the package for a future packager's reference.<br />
<br />
== Git repository ==<br />
A [[Git]] repository of the AUR is available at {{ic|<nowiki>git://pkgbuild.com/aur-mirror.git</nowiki>}}, and is generally updated at least once per day. If the repository's [http://git-scm.com/book/en/Git-Basics-Viewing-the-Commit-History commit history] is not needed, then cloning with the {{ic|1=--depth=1}} option will be much quicker:<br />
<br />
<nowiki>$ git clone --depth=1 git://pkgbuild.com/aur-mirror.git</nowiki><br />
<br />
For more information, see the following: [http://pkgbuild.com/git/aur-mirror.git/ Git Web interface], [https://bbs.archlinux.org/viewtopic.php?id=113099 forum thread].<br />
<br />
== AUR metadata ==<br />
<br />
{{Style|This section was originally in a separate page, it may need adaptations to better fit into this article.}}<br />
<br />
In order to display information in the [[AUR]] web interface, the AUR's back-end code attempts to parse [[PKGBUILD]] files and salvage package name, version, and other information from it. {{ic|PKGBUILD}}s are [[Bash]] scripts, and correctly parsing Bash scripts without executing them is a huge challenge, which is why [[makepkg]] is a Bash script itself: it includes the PKGBUILD of the package being built via the {{ic|source}} directive. AUR metadata files were created to get rid of some hacks, used by AUR package maintainers to work around incorrect parsing in the web interface. See also {{Bug|25210}}, {{Bug|15043}}, and {{Bug|16394}}.<br />
<br />
=== How it works ===<br />
By adding a metadata file called ".SRCINFO" to source tarballs to overwrite specific PKGBUILD fields. An outdated format of this file was described in the [https://mailman.archlinux.org/pipermail/aur-dev/2013-March/002428.html AUR 2.1.0 release announcement]. {{ic|.SRCINFO}} files are parsed line-by-line. The syntax for each line is {{ic|1=key[_arch] = value}}. Exactly one space must be on each side of the equals sign, even for an empty value, and do not include quotes around the values.<br />
<br />
The {{ic|key}} is a field name, based on the names of the corresponding [[PKGBUILD Variables]]. Some field names may optionally be suffixed with an architecture name. Fields are grouped into sections, each headed by one of the following two field names:<br />
<br />
* pkgbase: This is required by AUR 3, otherwise the infamous “only lowercase letters are allowed” error is reported. (Pacman uses the first ''pkgname'' if ''pkgbase'' is omitted.) Repeat pkgname if unsure. There is only one ''pkgbase'' section. The field values from this section are inherited unless overridden in the ''pkgname'' sections that follow it. An empty field value in the ''pkgname'' section cancels the inheritance.<br />
* pkgname: There may be multiple ''pkgname'' sections.<br />
<br />
The following field names are associated with a single value for the section:<br />
<br />
* epoch<br />
* pkgver: package version, may be formatted as [''epoch'':]''pkgver'' if the epoch field is not given separately<br />
* pkgrel: release number of the package specific to Arch Linux<br />
* pkgdesc<br />
* url<br />
<br />
The following field names may be repeated on multiple lines in a section to add multiple values:<br />
<br />
* license: in case of multiple licenses separate them by a space<br />
* groups<br />
<br />
The following field names may be repeated, and also may optionally have an architecture suffix, separated from the field name by an underscore:<br />
<br />
* depends: dependencies, one per line<br />
* makedepends<br />
* checkdepends<br />
* optdepends<br />
* conflicts<br />
* provides<br />
* replaces<br />
* source<br />
<br />
Fields with other names are ignored. Blank lines and comment lines beginning with a hash sign (#) are also ignored. Lines may be indented. This format closely matches the {{ic|.PKGINFO}} format that is used for binary packages in [[pacman]]/libalpm.<br />
<br />
== AUR translation ==<br />
<br />
See [https://projects.archlinux.org/aurweb.git/tree/TRANSLATING TRANSLATING] in the AUR source tree for information about creating and maintaining translation of the AUR web interface.<br />
<br />
== FAQ ==<br />
<br />
=== What is the AUR? ===<br />
<br />
The AUR (Arch User Repository) is a place where the Arch Linux community can upload [[PKGBUILD]]s of applications, libraries, etc., and share them with the entire community. Fellow users can then vote for their favorites to be moved into the [[community]] repository to be shared with Arch Linux users in binary form.<br />
<br />
=== What kind of packages are permitted on the AUR? ===<br />
<br />
The packages on the AUR are merely "build scripts", i.e. recipes to build binaries for pacman. For most cases, everything is permitted, subject to the abovementioned usefulness and scope guidelines, as long as you are in compliance with the licensing terms of the content. For other cases, where it is mentioned that "you may not link" to downloads, i.e. contents that are not redistributable, you may only use the file name itself as the source. This means and requires that users already have the restricted source in the build directory prior to building the package. When in doubt, ask.<br />
<br />
=== How can I vote for packages in AUR? ===<br />
<br />
Sign up on the [https://aur.archlinux.org/ AUR website] to get a "Vote for this package" option while browsing packages. After signing up it is also possible to vote from the commandline with {{AUR|aurvote}}.<br />
<br />
=== What is a Trusted User / TU? ===<br />
<br />
A [[AUR Trusted User Guidelines|Trusted User]], in short TU, is a person who is chosen to oversee AUR and the [[community]] repository. They are the ones who maintain popular PKGBUILDs in ''community'', and overall keep the AUR running.<br />
<br />
=== What is the difference between the Arch User Repository and the community repository? ===<br />
<br />
The Arch User Repository is where all PKGBUILDs that users submit are stored, and must be built manually with [[makepkg]]. When PKGBUILDs receive enough community interest and the support of a TU, they are moved into the [[community]] repository (maintained by the TUs), where the binary packages can be installed with [[pacman]].<br />
<br />
=== How to get a PKGBUILD into the community repository? ===<br />
<br />
Usually, at least 10 votes are required for something to move into [[community]]. However, if a TU wants to support a package, it will often be found in the repository.<br />
<br />
Reaching the required minimum of votes is not the only requirement, there has to be a TU willing to maintain the package. TUs are not required to move a package into the ''community'' repository even if it has thousands of votes.<br />
<br />
Usually when a very popular package stays in the AUR it is because:<br />
<br />
* Arch Linux already has another version of a package in the repositories<br />
* The package is AUR-centric (e.g. an [[AUR helper]])<br />
* Its license prohibits redistribution<br />
<br />
See also [[DeveloperWiki:Community repo candidates]] and [[AUR Trusted User Guidelines#Rules for Packages Entering the .5Bcommunity.5D Repo|Rules for Packages Entering the community Repo]].<br />
<br />
=== How do I make a PKGBUILD? ===<br />
<br />
The best resource is the wiki page about [[creating packages]]. Remember to look in AUR before creating the PKGBUILD as to not duplicate efforts.<br />
<br />
=== Foo in AUR is outdated; what do I do? ===<br />
<br />
For starters, you can flag packages out-of-date. If it stays out-of-date for an extended period of time, the best thing to do is email the maintainer. If there is no response from the maintainer after two weeks, you can file an orphan request. When we are talking about a package which is flagged out of date for more than 3 months and is in general not updated for a long time, please add this in your orphan request.<br />
<br />
In the meantime, you can try updating the package yourself by editing the PKGBUILD - sometimes updates do not require any changes to the build or package process, in which case simply updating the {{ic|pkgver}} or {{ic|source}} array is sufficient.<br />
<br />
=== I have a PKGBUILD I would like to submit; can someone check it to see if there are any errors? ===<br />
<br />
If you would like to have your PKGBUILD critiqued, post it on the aur-general mailing list to get feedback from the TUs and fellow AUR members. You could also get help from the [[IRC channel]], #archlinux on irc.freenode.net. You can also use [[namcap]] to check your PKGBUILD and the resulting package for errors.<br />
<br />
=== Foo in AUR does not compile when I run makepkg; what should I do? ===<br />
<br />
You are probably missing something trivial.<br />
<br />
# Run {{ic|pacman -Syyu}} before compiling anything with {{ic|makepkg}} as the problem may be that your system is not up-to-date.<br />
# Ensure you have both "base" and "base-devel" groups installed.<br />
# Try using the "{{ic|-s}}" option with {{ic|makepkg}} to check and install all the dependencies needed before starting the build process.<br />
<br />
Be sure to first read the PKGBUILD and the comments on the AUR page of the package in question.<br />
The reason might not be trivial after all. Custom CFLAGS, LDFLAGS and MAKEFLAGS can cause failures. It is also possible that the PKGBUILD is broken for everyone. If you cannot figure it out on your own, just report it to the maintainer e.g. by posting the errors you are getting in the comments on the AUR page.<br />
<br />
=== How can I speed up repeated build processes? ===<br />
<br />
If you frequently compile code that uses gcc - say, a git or SVN package - you may find [[ccache]], short for "compiler cache", useful.<br />
<br />
=== How can I upload to AUR without using the web interface? ===<br />
<br />
You can use an [[AUR helper]] like {{pkg|burp}} or {{AUR|aurup}}, both are commandline programs.<br />
<br />
=== What is the difference between foo and foo-git packages? ===<br />
<br />
Many AUR packages are presented in regular ("stable") and development versions ("unstable"). A development package usually has a suffix such as "-cvs", "-svn", "-git", "-hg", "-bzr" or "-darcs". While development packages are not intended for regular use, they may offer new features or bugfixes. Because {{ic|-git}}, {{ic|-svn}}, {{ic|-hg}} and {{ic|-bzr}} package builds download the latest available source when you execute {{ic|makepkg}}, a package version to track possible updates is not directly available for these. Likewise these package builds cannot perform an authenticity checksum for the same reason, instead it is relied on the maintainer(s) of the git repository. <br />
<br />
See also [[Enhancing Arch Linux Stability#Avoid development packages]].<br />
<br />
== AUR 4 ==<br />
<br />
Since release 4.0.0, aurweb uses Git repositories for AUR packages which means that the package submission process is a bit different. While [https://aur.archlinux.org/ aur.archlinux.org] runs aurweb 3.5.1 until August 8th 2015, there is a setup of a 4.0.0 release candidate running under [https://aur4.archlinux.org/ aur4.archlinux.org]. <br />
<br />
Current AUR maintainers are given a grace period between June 8th and July 8th to upload any package they already maintain to [https://aur4.archlinux.org/ aur4.archlinux.org]. After July 8th any package in the current AUR can be taken over by any maintainer and uploaded. On August 8th [https://aur4.archlinux.org/ aur4.archlinux.org] will become the new official AUR and will be moved to the aur subdomain.<br />
<br />
=== Before submitting packages to aur4.archlinux.org ===<br />
<br />
Before you submit a package for the first time, you need to create a new SSH key pair.<br />
It is recommended that you create a new key, rather than use an existing SSH key so that you could selectively revoke the SSH key should something happen.<br />
<br />
To create a new SSH key pair:<br />
<br />
$ ssh-keygen -f ~/.ssh/id_aur<br />
<br />
Log into the AUR web interface, go to ''My Account'' and copy the content of {{ic|~/.ssh/id_aur.pub}} (or any other key you want to use) into the ''SSH Public Key'' field. Click ''Update'' to save the key. It is recommended to add the following lines to your {{ic|~/.ssh/config}} so you do not need to specify user and key each time you connect to the AUR SSH interface:<br />
<br />
Host aur4.archlinux.org<br />
IdentityFile ~/.ssh/id_aur<br />
User aur<br />
<br />
=== Submitting packages to aur4.archlinux.org ===<br />
<br />
{{Warning|Before attempting to submit a package you are expected to familiarize yourself with [[Arch packaging standards]] and all articles, mentioned at the bottom of it.}}<br />
<br />
In order to upload a package, simply clone the Git repository with the corresponding name:<br />
<br />
$ git clone ssh://<nowiki>aur@aur4.archlinux.org/</nowiki>''foobar''.git<br />
<br />
(One can also use the alternative format {{ic|<nowiki>aur@aur4.archlinux.org</nowiki>:/''foobar''.git}}.)<br />
<br />
You can then add the source files to the local copy of the Git repository. When making changes to the repository, make sure you always include the {{ic|PKGBUILD}} and {{ic|.SRCINFO}} in the top-level directory. You can create {{ic|.SRCINFO}} files using {{ic|mksrcinfo}}, provided by {{Pkg|pkgbuild-introspection}}. <br />
<br />
In order to submit new versions of a package base to the AUR, commit the new {{ic|PKGBUILD}}, {{ic|.SRCINFO}} and possibly helper files (like install files) and run {{ic|git push}}. For example, after adding the {{ic|PKGBUILD}} to the newly created directory, you can run the following commands to create and submit the initial commit:<br />
<br />
$ mksrcinfo<br />
$ git add PKGBUILD .SRCINFO<br />
$ git commit -m 'Initial import'<br />
$ git push origin master<br />
<br />
To update a package, edit the {{ic|PKGBUILD}} and run the following commands to track the changes in the AUR Git repository:<br />
<br />
$ mksrcinfo<br />
$ git commit -am 'Update to ''1.0.0'''<br />
$ git push<br />
<br />
{{Tip|If you forget to commit the {{ic|.SRCINFO}} and add it in a later commit, the AUR will still reject your pushes because the {{ic|.SRCINFO}} must exist for ''every'' commit. To solve this problem you can fix the first commit where you forgot the {{ic|.SRCINFO}} and then rebase your branch onto that commit.}}<br />
<br />
=== Migration scripts ===<br />
<br />
Several scripts exist to ease the transition:<br />
<br />
* [https://gist.github.com/bbidulock/82ab6f5347f021136054 bbidulock's script] to migrate from a .backup directory with all packages.<br />
* [https://github.com/voidus/aur2git aur2git] - A ruby gem to download and submit your existing packages.<br />
* [https://github.com/ido/packages-archlinux/blob/master/bin/import-to-aur4.sh import-to-aur4] split an existing single git repository and retain the history (all at once)<br />
* [https://github.com/JonnyJD/PKGBUILDs/blob/master/_bin/aur4_import.sh aur4_import.sh] import a package from a repository with multiple packages (creating gitignore and .SRCINFO for every commit)<br />
* [https://gist.github.com/amiad/d9876a004c3e836a69a7 import-to-aur4.sh] - Import packages from aur3 to aur4 by packages list.<br />
<br />
Keep in mind all those scripts are unsupported and contributed by users!<br />
<br />
== See also ==<br />
* [https://aur.archlinux.org AUR Web Interface]<br />
* [https://www.archlinux.org/mailman/listinfo/aur-general AUR Mailing List]<br />
* [http://pkgbuild.com/git/aur-mirror.git/ AUR Mirror Git repository]</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Linux_Containers&diff=370394Linux Containers2015-04-21T03:32:06Z<p>Fylwind: /* Host Network Configuration */ configuration for wireless networks</p>
<hr />
<div>[[Category:Security]]<br />
[[Category:Virtualization]]<br />
[[pt:Linux Containers]]<br />
{{Related articles start}}<br />
{{Related|Cgroups}}<br />
{{Related|systemd-nspawn}}<br />
{{Related|Docker}}<br />
{{Related articles end}}<br />
<br />
<br />
'''LinuX Containers''' ('''LXC''') is an operating system-level virtualization method for running multiple isolated Linux systems (containers) on a single control host (LXC host). It does not provide a virtual machine, but rather provides a virtual environment that has its own CPU, memory, block I/O, network etc. space. This is provided by [[cgroups]] features in Linux kernel on LXC host. It is similar to a chroot, but offers much more isolation.<br />
<br />
== Setup ==<br />
=== Required software ===<br />
Install {{Pkg|lxc}} and {{Pkg|arch-install-scripts}} from the [[official repositories]].<br />
<br />
Verify that the running kernel is properly configured to run a container:<br />
$ lxc-checkconfig<br />
<br />
Due to security concerns, the default Arch kernel does NOT ship with the ability to run containers as an unprivileged users, therefore, it is normal to see a '''missing''' status for "User namespaces" when running the check. See [https://bugs.archlinux.org/task/36969 FS#36969] for this feature request.<br />
<br />
=== Host Network Configuration ===<br />
LXCs support different virtual network types. A bridge device on the host is required for most types of virtual networking. The examples of creating a bridge provided below are not meant to be limiting but illustrative. Users may use other programs to achieve the same results.<br />
<br />
{{Note|Select only '''one''' of the methods below to implement the bridge on the host!}}<br />
<br />
==== Example using only netctl ====<br />
{{Pkg|netctl}} is available from the [[official repositories]].<br />
A bridge template can be found in {{ic|/etc/netctl/examples}} which needs to be edited to match the host network hardware specs and IP ranges of the host network. Below are two example bridge configs, one using a dhcp setup and the other using a static IP setup.<br />
<br />
{{hc|1=/etc/netctl/lxcbridge|2=<br />
Description="LXC bridge"<br />
Interface=br0<br />
Connection=bridge<br />
BindsToInterfaces=('eno1')<br />
IP=dhcp<br />
SkipForwardingDelay=yes}}<br />
<br />
{{hc|1=/etc/netctl/lxcbridge|2=<br />
Description="LXC bridge"<br />
Interface=br0<br />
Connection=bridge<br />
BindsToInterfaces=('eno1')<br />
IP=static<br />
Address=192.168.0.2/24<br />
Gateway='192.168.0.1'<br />
DNS=('192.168.0.1')}}<br />
<br />
Before attempting to start the bridge, [[disable]] the running network interface on the host as the bridge will replace it; this depends on how the host network is configured, common networking examples are shown in [[Beginners%27_guide#Configure_the_network]].<br />
<br />
For users already using netctl to manage an adapter, simply switch-to it:<br />
# netctl switch-to lxcbridge<br />
# netctl enable lxcbridge<br />
<br />
Verify network connectivity on the host before continuing. This can be accomplished with a simple ping:<br />
$ ping -c 1 www.google.com<br />
<br />
==== Example using only bridge-utils ====<br />
Placeholder for someone using this setup.<br />
<br />
==== Example for a wireless network ====<br />
<br />
Wireless networks cannot be bridged directly, so a different method must be used in this case. First a bridge must be created similar to the previous examples, but we will not add any interface to it (other than the virtual interface of the container itself, which is done automatically). It should have a static IP address, say 192.168.0.2. (The gateway does not need to be specified, at least not on the host side of the bridge.)<br />
<br />
The host must be configured to perform NAT using iptables:<br />
<br />
# iptables -A POSTROUTING -o <var>wlp3s0</var> -j MASQUERADE<br />
<br />
where {{ic|<var>wlp3s0</var>}} is the name of your wireless interface. Since packet forwarding is disabled by default, this must be enabled by [[Internet_sharing#Enable_packet_forwarding|modifying a kernel parameter]]:<br />
<br />
# echo 1 > /proc/sys/net/ipv4/ip_forward<br />
<br />
This will be reset on reboot, so consider adding a conf file to {{ic|/etc/sysctl.d}} (although there may be caveats: see the warning in [[Internet_sharing#Enable_packet_forwarding]])<br />
<br />
The remaining steps are similar, except for one thing: for the container, the gateway must be configured to be the IP address of the host (in this example, it was 192.168.0.2). This is specified in {{ic|/var/lib/lxc/''container_name''/config}} (see the following sections).<br />
<br />
=== Container creation ===<br />
Select a template from {{ic|/usr/share/lxc/templates}} that matches the target distro to containerize. Users wishing to containerize non-Arch distros will need additional packages on the host depending on the target distro:<br />
* Debian-based: {{AUR|debootstrap}} package from [[AUR]].<br />
* Fedora-based: {{AUR|yum}} package from [[AUR]].<br />
<br />
Run {{ic|lxc-create}} to create the container which installs the root filesystem of the LXC to {{ic|/var/lib/lxc/CONTAINER_NAME/rootfs}} by default. Example creating an Arch Linux LXC named "playtime":<br />
# lxc-create -n playtime -t /usr/share/lxc/templates/lxc-archlinux<br />
<br />
{{Tip|Users may optionally install {{Pkg|haveged}} and [[start]] {{ic|haveged.service}} to avoid a perceived hang during the setup process while waiting for system entropy to be seeded. Without it, the generation of private/GPG keys can create a lengthy wait.}}<br />
<br />
{{Tip|Users of [[Btrfs]] can append {{ic|-B btrfs}} to create a Btrfs subvolume for storing containerized rootfs. This comes in handy if cloning containers with the help of {{ic|lxc-clone}} command.}}<br />
<br />
=== Container configuration ===<br />
==== Basic config with networking ====<br />
System resources to be virtualized / isolated when a process is using the container are defined in {{ic|/var/lib/lxc/CONTAINER_NAME/config}}. By default, the creation process will make a minimum setup without networking support. Below is an example config with networking:<br />
<br />
{{hc|/var/lib/lxc/playtime/config|<nowiki><br />
# Template used to create this container: /usr/share/lxc/templates/lxc-archlinux<br />
# Parameters passed to the template:<br />
# For additional config options, please look at lxc.container.conf(5)<br />
<br />
## default values<br />
lxc.rootfs = /var/lib/lxc/playtime/rootfs<br />
lxc.utsname = playtime<br />
lxc.arch = x86_64<br />
lxc.include = /usr/share/lxc/config/archlinux.common.conf<br />
<br />
## network<br />
lxc.network.type = veth<br />
lxc.network.link = br0<br />
lxc.network.flags = up<br />
lxc.network.ipv4 = 192.168.0.3/24<br />
lxc.network.ipv4.gateway = 192.168.0.1<br />
lxc.network.name = eth0<br />
<br />
## mounts<br />
## specify shared filesystem paths in the format below<br />
## make sure that the mount point exists on the lxc<br />
lxc.mount.entry = /mnt/data/share mnt/data none bind 0 0<br />
</nowiki>}}<br />
<br />
==== Systemd considerations (required) ====<br />
The following sections explain some quirks that should be addressed. After creating the autodev script {{ic|/var/lib/lxc/playtime/autodev}} and after reading the information in the below sections, modify {{ic|/var/lib/lxc/playtime/config}} to contain this new section:<br />
## systemd within the lxc<br />
lxc.autodev = 1<br />
lxc.pts = 1024<br />
lxc.kmsg = 0<br />
lxc.hook.autodev=/var/lib/lxc/playtime/autodev<br />
<br />
===== Systemd conflicts in the /dev tree =====<br />
To avoid conflicts of systemd and lxc in the /dev tree. It is '''highly recommended''' to enable the 'autodev' mode. This will cause LXC to create its own device tree but this also means that the traditional way of manually creating device nodes in the container rootfs /dev tree will not work because /dev is overmounted by LXC.<br />
<br />
{{Warning|Any device nodes required that are not created by LXC by default must be created by the ''autodev hook'' script!}}<br />
<br />
Create the following script:<br />
{{hc|/var/lib/lxc/playtime/autodev|<nowiki><br />
#!/bin/bash<br />
cd ${LXC_ROOTFS_MOUNT}/dev<br />
mkdir net<br />
mknod net/tun c 10 200<br />
chmod 0666 net/tun<br />
</nowiki>}}<br />
<br />
Make it executable:<br />
# chmod +x /var/lib/lxc/playtime/autodev<br />
<br />
It is also important to disable services that are not supported inside a container. Either attach to the running LXC or [[chroot]] into the container rootfs and mask those services:<br />
<br />
ln -s /dev/null /etc/systemd/system/systemd-udevd.service<br />
ln -s /dev/null /etc/systemd/system/systemd-udevd-control.socket<br />
ln -s /dev/null /etc/systemd/system/systemd-udevd-kernel.socket<br />
ln -s /dev/null /etc/systemd/system/proc-sys-fs-binfmt_misc.automount<br />
<br />
This disables udev and mounting of /proc/sys/fs/binfmt_misc.<br />
<br />
===== Maintain devpts consistency =====<br />
Additionally ensure a pty declaration in the LXC container because the presence of this causes LXC to mount devpts as a new instance. Without this the container gets the host's devpts and that is not a good thing - more strange things will happen!<br />
lxc.pts = 1024<br />
<br />
{{Note|There is no need to explicitly mount system devices (either via the container config or via its own /etc/fstab) and this should not be done because systemd (or LXC in the case of /dev...) takes care of it.}}<br />
<br />
===== Prevent excess journald activity =====<br />
<br />
By default lxc symlinks /dev/kmsg to /dev/console, this leads to journald running 100% cpu usage all the time. To prevent the symlink, use:<br />
lxc.kmsg = 0<br />
<br />
==== Xorg program considerations (optional) ====<br />
In order to run programs on the host's display, some bind mounts need to be defined so the containerized programs can access the host's resources. Add the following section to {{ic|/var/lib/lxc/playtime/config}}:<br />
## for xorg<br />
## fix overmounting see: https://github.com/lxc/lxc/issues/434<br />
lxc.mount.entry = tmpfs tmp tmpfs defaults<br />
lxc.mount.entry = /dev/dri dev/dri none bind,optional,create=dir<br />
lxc.mount.entry = /dev/snd dev/snd none bind,optional,create=dir<br />
lxc.mount.entry = /tmp/.X11-unix tmp/.X11-unix none bind,optional,create=dir<br />
lxc.mount.entry = /dev/video0 dev/video0 none bind,optional,create=file<br />
<br />
==== OpenVPN considerations (optional) ====<br />
In addition to the above, users wishing to run {{Pkg|openvpn}} inside the LXC will need to add the following section to {{ic|/var/lib/lxc/playtime/config}}:<br />
## for openvpn<br />
lxc.cgroup.devices.allow = c 10:200 rwm<br />
<br />
== Managing Containers ==<br />
<br />
To List all installed LXC containers:<br />
# lxc-ls -f<br />
<br />
Systemd can be used to [[start]] and to [[stop]] LXCs via {{ic|lxc@CONTAINER_NAME.service}}. [[Enable]] {{ic|lxc@CONTAINER_NAME.service}} to have it start when the host system boots.<br />
<br />
Users can also start/stop LXCs without systemd.<br />
Start a container:<br />
# lxc-start -n CONTAINER_NAME<br />
<br />
Stop a container:<br />
# lxc-stop -n CONTAINER_NAME<br />
<br />
To attach to a container:<br />
# lxc-attach -n CONTAINER_NAME<br />
<br />
Once attached, treat the container like any other linux system, set the root password, create users, install packages, etc.<br />
<br />
== Running Xorg programs ==<br />
Either attach to or ssh into the target container and prefix the call to the program with the DISPLAY id of the host's X session. For most simple setups, the display is always 0.0. Example running firefox from the container in the host's display:<br />
$ DISPLAY=:0.0 firefox<br />
<br />
Alternatively, to avoid directly attaching to or connecting to the container, the following can be used on the host to automate the process:<br />
# lxc-attach -n playtime --clear-env -- sudo -u YOURUSER env DISPLAY=0.0 firefox<br />
<br />
== See also ==<br />
<br />
* [https://www.stgraber.org/2013/12/20/lxc-1-0-blog-post-series/ LXC 1.0 Blog Post Series]<br />
* [http://www.ibm.com/developerworks/linux/library/l-lxc-containers/ LXC@developerWorks]<br />
* [http://docs.docker.io/en/latest/installation/archlinux/ Docker Installation on ArchLinux]</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Network_configuration/Wireless&diff=369706Network configuration/Wireless2015-04-14T22:01:05Z<p>Fylwind: /* Troubleshooting */ some tips for host resolving problems</p>
<hr />
<div>[[Category:Wireless Networking]]<br />
[[cs:Wireless Setup]]<br />
[[de:(W)LAN und Arch Linux]]<br />
[[el:Wireless Setup]]<br />
[[es:Wireless Setup]]<br />
[[fr:Wifi]]<br />
[[it:Wireless Setup]]<br />
[[ja:ワイヤレス設定]]<br />
[[nl:Wireless Setup]]<br />
[[ro:Wireless]]<br />
[[ru:Wireless network configuration]]<br />
[[th:Wireless Setup]]<br />
[[tr:Kablosuz bağlantı]]<br />
[[zh-CN:Wireless network configuration]]<br />
{{Related articles start}}<br />
{{Related|Network configuration}}<br />
{{Related|Software access point}}<br />
{{Related|Ad-hoc networking}}<br />
{{Related|Internet sharing}}<br />
{{Related articles end}}<br />
<br />
Configuring wireless is a two-part process; the first part is to identify and ensure the correct driver for your wireless device is installed (they are available on the installation media, but often have to be installed explicitly), and to configure the interface. The second is choosing a method of managing wireless connections. This article covers both parts, and provides additional links to wireless management tools.<br />
<br />
== Device driver ==<br />
<br />
The default Arch Linux kernel is ''modular'', meaning many of the drivers for machine hardware reside on the hard drive and are available as [[Kernel modules|modules]]. At boot, [[udev]] takes an inventory of your hardware and loads appropriate modules (drivers) for your corresponding hardware, which will in turn allow creation of a network ''interface''.<br />
<br />
Some wireless chipsets also require firmware, in addition to a corresponding driver. Many firmware images are provided by the {{Pkg|linux-firmware}} package which is installed by default, however, proprietary firmware images are not included and have to be installed separately. This is described in [[#Installing driver/firmware]].<br />
<br />
{{Note|Udev is not perfect. If the proper module is not loaded by udev on boot, simply [[Kernel modules#Loading|load it manually]]. Note also that udev may occasionally load more than one driver for a device, and the resulting conflict will prevent successful configuration. Make sure to [[Kernel modules#Blacklisting|blacklist]] the unwanted module.}}<br />
<br />
{{Tip|Though not strictly required, it's a good idea to first install user-space tools mentioned in [[#Manual setup]], especially when some problem should appear.}}<br />
<br />
=== Check the driver status ===<br />
<br />
To check if the driver for your card has been loaded, check the output of the {{ic|lspci -k}} or {{ic|lsusb -v}} command, depending on if the card is connected by PCI(e) or USB. You should see that some kernel driver is in use, for example:<br />
<br />
{{hc|$ lspci -k|<nowiki><br />
06:00.0 Network controller: Intel Corporation WiFi Link 5100<br />
Subsystem: Intel Corporation WiFi Link 5100 AGN<br />
Kernel driver in use: iwlwifi<br />
Kernel modules: iwlwifi<br />
</nowiki>}}<br />
<br />
{{Note|If the card is a USB device, running {{ic|<nowiki>dmesg | grep usbcore</nowiki>}} should give something like {{ic|usbcore: registered new interface driver rtl8187}} as output.}}<br />
<br />
Also check the output of {{ic|ip link}} command to see if a wireless interface ([[Network configuration#Device names|usually]] it starts with the letter "w", e.g. {{ic|wlp2s1}}) was created. Then bring the interface up with {{ic|ip link set ''interface'' up}}. For example, assuming the interface is {{ic|wlan0}}:<br />
<br />
# ip link set wlan0 up<br />
<br />
If you get this error message: {{ic|SIOCSIFFLAGS: No such file or directory}}, it most certainly means that your wireless chipset requires a firmware to function.<br />
<br />
Check kernel messages for firmware being loaded:<br />
<br />
{{hc|<nowiki>$ dmesg | grep firmware</nowiki>|<nowiki><br />
[ 7.148259] iwlwifi 0000:02:00.0: loaded firmware version 39.30.4.1 build 35138 op_mode iwldvm<br />
</nowiki>}}<br />
<br />
If there is no relevant output, check the messages for the full output for the module you identified earlier ({{ic|iwlwifi}} in this example) to identify the relevant message or further issues:<br />
<br />
{{hc|<nowiki>$ dmesg | grep iwlwifi</nowiki>|<nowiki><br />
[ 12.342694] iwlwifi 0000:02:00.0: irq 44 for MSI/MSI-X<br />
[ 12.353466] iwlwifi 0000:02:00.0: loaded firmware version 39.31.5.1 build 35138 op_mode iwldvm<br />
[ 12.430317] iwlwifi 0000:02:00.0: CONFIG_IWLWIFI_DEBUG disabled<br />
...<br />
[ 12.430341] iwlwifi 0000:02:00.0: Detected Intel(R) Corporation WiFi Link 5100 AGN, REV=0x6B<br />
</nowiki>}}<br />
<br />
If the kernel module is successfully loaded and the interface is up, you can skip the next section.<br />
<br />
=== Installing driver/firmware ===<br />
<br />
Check the following lists to discover if your card is supported:<br />
<br />
* The [https://help.ubuntu.com/community/WifiDocs/WirelessCardsSupported Ubuntu Wiki] has a good list of wireless cards and whether or not they are supported either in the Linux kernel or by a user-space driver (includes driver name).<br />
* [http://linux-wless.passys.nl/ Linux Wireless Support] and The Linux Questions' [http://www.linuxquestions.org/hcl/index.php?cat=10 Hardware Compatibility List] (HCL) also have a good database of kernel-friendly hardware.<br />
* The [http://wireless.kernel.org/en/users/Devices kernel page] additionally has a matrix of supported hardware.<br />
<br />
Note that some vendors ship products that may contain different chip sets, even if the product identifier is the same. Only the usb-id (for USB devices) or pci-id (for PCI devices) is authoritative.<br />
<br />
If your wireless card is listed above, follow the [[#Troubleshooting drivers and firmware]] subsection of this page, which contains information about installing drivers and firmware of some specific wireless cards. Then [[#Check the driver status|check the driver status]] again.<br />
<br />
If your wireless card is not listed above, it is likely supported only under Windows (some Broadcom, 3com, etc). For these, you can try to use [[#ndiswrapper]].<br />
<br />
== Wireless management ==<br />
<br />
Assuming that your drivers are installed and working properly, you will need to choose a method of managing your wireless connections. The following subsections will help you decide.<br />
<br />
Procedure and tools required will depend on several factors:<br />
* The desired nature of configuration management; from a completely manual command line procedure to an automated solution with graphical front-ends.<br />
* The encryption type (or lack thereof) which protects the wireless network.<br />
* The need for network profiles, if the computer will frequently change networks (such as a laptop).<br />
<br />
{{Tip|<br />
* Whatever is your choice, '''you should try to connect using the manual method first'''. This will help you understand the different steps that are required and troubleshoot possible problems.<br />
* If possible (e.g. if you manage your Wi-Fi access point), try connecting with no encryption, to check that everything works. Then try using encryption, either WEP (simple to configure, but crackable in a matter of seconds), WPA or WPA2.<br />
}}<br />
<br />
The following table shows the different methods that can be used to activate and manage a wireless connection, depending on the encryption and management types, and the various tools that are required. Although there may be other possibilities, these are the most frequently used:<br />
<br />
{| class="wikitable"<br />
! Management method || Interface activation || Wireless connection management <br>(/=alternatives) || Assigning IP address <br>(/=alternatives) <br />
|-<br />
| [[#Manual setup|Manually managed]], <br>with no or WEP encryption || [[Core utilities#ip|ip]] || {{Pkg|iw}} / [https://www.archlinux.org/packages/?name=wireless_tools iwconfig] || [[Core utilities#ip|ip]] / [[dhcpcd]] / {{Pkg|dhclient}}<br />
|-<br />
| [[#Manual setup|Manually managed]], <br>with WPA or WPA2 PSK encryption || [[Core utilities#ip|ip]] || {{Pkg|iw}} / [https://www.archlinux.org/packages/?name=wireless_tools iwconfig] + [[WPA supplicant|wpa_supplicant]] || [[Core utilities#ip|ip]] / [[dhcpcd]] / {{Pkg|dhclient}}<br />
|-<br />
| [[#Automatic setup|Automatically managed]], <br>with network profiles support || colspan="3" align="center" | [[netctl]], [[Wicd]], [[NetworkManager]], etc.<br><br />
These tools pull in the required dependencies from the list of packages in the manual method.<br />
|}<br />
<br />
=== Manual setup ===<br />
<br />
Just like other network interfaces, the wireless ones are controlled with ''ip'' from the {{Pkg|iproute2}} package.<br />
<br />
You will need to install a basic set of tools for managing the wireless connection. Either:<br />
:*{{Pkg|iw}} - only supports the nl80211 (netlink) standard. It does not support the older WEXT (Wireless EXTentions) standard. If ''iw'' does not see your card, this may be the reason.<br />
:or<br />
:*{{Pkg|wireless_tools}} - currently deprecated, but still widely supported. Use this for modules using the WEXT standard.<br />
<br />
For WPA/WPA2 encryption, you will also need:<br />
:*{{Pkg|wpa_supplicant}} - works with both WEXT and nl80211.<br />
<br />
The table below gives an overview of comparable commands for ''iw'' and ''wireless_tools'' (see [http://wireless.kernel.org/en/users/Documentation/iw/replace-iwconfig iw replaces iwconfig] for more examples). These user-space tools work extremely well and allow complete manual control of wireless connection.<br />
<br />
{{Note|<br />
* Examples in this section assume that your wireless device interface is {{ic|wlan0}} and that you are connecting to {{ic|''your_essid''}} wifi access point. Replace both accordingly. To find your wireless device interface, see [[#Getting_some_useful_information]].<br />
* Note that most of the commands have to be executed with [[Users and groups|root permissions]]. Executed with normal user rights, some of the commands (e.g. ''iwlist''), will exit without error but not produce the correct output either, which can be confusing.<br />
}} <br />
<br />
{| class="wikitable"<br />
! ''iw'' command<br />
! ''wireless_tools'' command<br />
! Description<br />
|-<br />
| iw dev wlan0 link<br />
| iwconfig wlan0<br />
| Getting link status.<br />
|-<br />
| iw dev wlan0 scan<br />
| iwlist wlan0 scan<br />
| Scanning for available access points.<br />
|-<br />
| iw dev wlan0 set type ibss<br />
| iwconfig wlan0 mode ad-hoc<br />
| Setting the operation mode to ''ad-hoc''.<br />
|-<br />
| iw dev wlan0 connect ''your_essid''<br />
| iwconfig wlan0 essid ''your_essid''<br />
| Connecting to open network.<br />
|-<br />
| iw dev wlan0 connect ''your_essid'' 2432<br />
| iwconfig wlan0 essid ''your_essid'' freq 2432M<br />
| Connecting to open network specifying channel.<br />
|-<br />
| iw dev wlan0 connect ''your_essid'' key 0:''your_key''<br />
| iwconfig wlan0 essid ''your_essid'' key ''your_key''<br />
| Connecting to WEP encrypted network using hexadecimal key.<br />
|-<br />
| iw dev wlan0 connect ''your_essid'' key 0:''your_key''<br />
| iwconfig wlan0 essid ''your_essid'' key s:''your_key''<br />
| Connecting to WEP encrypted network using ASCII key.<br />
|-<br />
| iw dev wlan0 set power_save on<br />
| iwconfig wlan0 power on<br />
| Enabling power save.<br />
|}<br />
<br />
{{Note|Depending on your hardware and encryption type, some of these steps may not be necessary. Some cards are known to require interface activation and/or access point scanning before being associated to an access point and being given an IP address. Some experimentation may be required. For instance, WPA/WPA2 users may try to directly activate their wireless network from step [[#Association]].}}<br />
<br />
==== Getting some useful information ====<br />
<br />
{{Tip|See [http://wireless.kernel.org/en/users/Documentation/iw official documentation] of the ''iw'' tool for more examples.}}<br />
<br />
* First you need to find the name of wireless interface. You can do it with following command:<br />
<br />
{{hc|$ iw dev|<br />
phy#0<br />
Interface '''wlan0'''<br />
ifindex 3<br />
wdev 0x1<br />
addr 12:34:56:78:9a:bc<br />
type managed<br />
channel 1 (2412 MHz), width: 40 MHz, center1: 2422 MHz<br />
}}<br />
<br />
* To check link status, use following command. Example output when not connected to an AP:<br />
<br />
{{hc|$ iw dev wlan0 link|<br />
Not connected.<br />
}}<br />
<br />
When connected to an AP, you will see something like:<br />
<br />
{{hc|$ iw dev wlan0 link|<br />
Connected to 12:34:56:78:9a:bc (on wlan0)<br />
SSID: MyESSID<br />
freq: 2412<br />
RX: 33016518 bytes (152703 packets)<br />
TX: 2024638 bytes (11477 packets)<br />
signal: -53 dBm<br />
tx bitrate: 150.0 MBit/s MCS 7 40MHz short GI<br />
<br />
bss flags: short-preamble short-slot-time<br />
dtim period: 1<br />
beacon int: 100<br />
}}<br />
<br />
* You can get statistic information, such as the amount of tx/rx bytes, signal strength etc., with following command:<br />
<br />
{{hc|$ iw dev wlan0 station dump|<br />
Station 12:34:56:78:9a:bc (on wlan0)<br />
inactive time: 1450 ms<br />
rx bytes: 24668671<br />
rx packets: 114373<br />
tx bytes: 1606991<br />
tx packets: 8557<br />
tx retries: 623<br />
tx failed: 1425<br />
signal: -52 dBm<br />
signal avg: -53 dBm<br />
tx bitrate: 150.0 MBit/s MCS 7 40MHz short GI<br />
authorized: yes<br />
authenticated: yes<br />
preamble: long<br />
WMM/WME: yes<br />
MFP: no<br />
TDLS peer: no<br />
}}<br />
<br />
==== Interface activation ====<br />
<br />
{{Tip|Usually this step is not required}}<br />
<br />
Some cards require that the kernel interface be activated before you can use ''iw'' or ''wireless_tools'':<br />
<br />
# ip link set wlan0 up<br />
<br />
{{Note|If you get errors like {{ic|RTNETLINK answers: Operation not possible due to RF-kill}}, make sure that hardware switch is ''on''. See [[#Rfkill caveat]] for details.}}<br />
<br />
To verify that the interface is up, inspect the output of the following command:<br />
<br />
{{hc|# ip link show wlan0|<br />
3: wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state DOWN mode DORMANT group default qlen 1000<br />
link/ether 12:34:56:78:9a:bc brd ff:ff:ff:ff:ff:ff<br />
}}<br />
<br />
The {{ic|UP}} in {{ic|<BROADCAST,MULTICAST,UP,LOWER_UP>}} is what indicates the interface is up, not the later {{ic|state DOWN}}.<br />
<br />
==== Access point discovery ====<br />
<br />
See what access points are available:<br />
<br />
# iw dev wlan0 scan | less<br />
<br />
{{Note|If it displays {{ic|Interface doesn't support scanning}}, then you probably forgot to install the firmware. In some cases this message is also displayed when not running ''iw'' as root.}}<br />
<br />
{{Tip|Depending on your location, you might need to set the correct [[#Respecting the regulatory domain|regulatory domain]] in order to see all available networks.}}<br />
<br />
The important points to check:<br />
* '''SSID:''' the name of the network.<br />
* '''Signal:''' is reported in a wireless power ratio in dbm (e.g. from -100 to 0). The closer the negative value gets to zero, the better the signal. Observing the reported power on a good quality link and a bad one should give an idea about the individual range. <br />
* '''Security:''' it is not reported directly, check the line starting with {{ic|capability}}. If there is {{ic|Privacy}}, for example {{ic|capability: ESS Privacy ShortSlotTime (0x0411)}}, then the network is protected somehow.<br />
** If you see an {{ic|RSN}} information block, then the network is protected by [[Wikipedia:IEEE 802.11i-2004|Robust Security Network]] protocol, also known as WPA2.<br />
** If you see an {{ic|WPA}} information block, then the network is protected by [[Wikipedia:Wi-Fi Protected Access|Wi-Fi Protected Access]] protocol.<br />
** In the {{ic|RSN}} and {{ic|WPA}} blocks you may find the following information:<br />
*** '''Group cipher:''' value in TKIP, CCMP, both, others.<br />
*** '''Pairwise ciphers:''' value in TKIP, CCMP, both, others. Not necessarily the same value than Group cipher.<br />
*** '''Authentication suites:''' value in PSK, 802.1x, others. For home router, you'll usually find PSK (''i.e.'' passphrase). In universities, you are more likely to find 802.1x suite which requires login and password. Then you will need to know which key management is in use (e.g. EAP), and what encapsulation it uses (e.g. PEAP). Find more details at [[Wikipedia:Authentication protocol]] and the sub-articles.<br />
** If you do not see neither {{ic|RSN}} nor {{ic|WPA}} blocks but there is {{ic|Privacy}}, then WEP is used.<br />
<br />
==== Operating mode ====<br />
<br />
{{Tip|This step is optional, but may be required}}<br />
<br />
At this step you might need to set the proper operating mode of the wireless card. More specifically, if you are going to connect an [[Ad-hoc networking|ad-hoc network]], you need to set the operating mode to {{ic|ibss}}:<br />
<br />
# iw dev wlan0 set type ibss<br />
<br />
{{Note|Changing the operating mode on some cards might require the wireless interface to be ''down'' ({{ic|ip link set wlan0 down}}).}}<br />
<br />
==== Association ====<br />
<br />
Depending on the encryption, you need to associate your wireless device with the access point to use and pass the encryption key:<br />
<br />
* '''No encryption''' {{bc|# iw dev wlan0 connect "''your_essid''"}}<br />
* '''WEP'''<br />
** using a hexadecimal or ASCII key (the format is distinguished automatically, because a WEP key has a fixed length): {{bc|# iw dev wlan0 connect "''your_essid''" key 0:''your_key''}}<br />
** using a hexadecimal or ASCII key, specifying the third set up key as default (keys are counted from zero, four are possible): {{bc|# iw dev wlan0 connect "''your_essid''" key d:2:''your_key''}}<br />
* '''WPA/WPA2''' According to what you got from [[#Access point discovery]], issue this command: {{bc|# wpa_supplicant -D nl80211,wext -i wlan0 -c <(wpa_passphrase "''your_SSID''" "''your_key''")}}<br />
<br />
If this does not work, you may need to adjust the options. <br />
If connected successfully, continue in a new terminal (or quit {{ic|wpa_supplicant}} with {{ic|Ctrl+c}} and add the {{ic|-B}} switch to the above command to run it in the background). [[WPA supplicant]] contains more information on options and on how to create a permanent configuration file for the wireless access point.<br />
<br />
Regardless of the method used, you can check if you have associated successfully:<br />
<br />
# iw dev wlan0 link<br />
<br />
==== Getting an IP address ====<br />
<br />
{{Note|See [[Network configuration#Configure the IP address]] for more examples. This part is identical.}}<br />
<br />
Finally, provide an IP address to the network interface. Simple examples are:<br />
<br />
# dhcpcd wlan0<br />
<br />
for DHCP, or<br />
<br />
# ip addr add 192.168.0.2/24 dev wlan0<br />
# ip route add default via 192.168.0.1<br />
<br />
for static IP addressing.<br />
<br />
{{Tip|[[dhcpcd]] contains a [[dhcpcd#10-wpa_supplicant|hook]] (enabled by default) to automatically launch [[WPA supplicant]] on wireless interfaces. In most cases, you do not need to create any [[#Manual wireless connection at boot using systemd and dhcpcd|custom service]], just enable {{ic|dhcpcd@''interface''.service}}.}}<br />
<br />
==== Custom startup scripts/services ====<br />
<br />
Although the manual configuration method will help troubleshoot wireless problems, you will have to re-type every command each time you reboot. You can also quickly write a ''systemd'' service to automate the whole process, which is still a quite convenient way of managing network connection while keeping full control over your configuration. You can find some examples in this section. If you prefer to use scripts to handle the commands, see the [[Network configuration#Persistent configuration on boot using systemd|network configuration]] article for an example how to source them.<br />
<br />
===== Manual wireless connection at boot using systemd and dhcpcd =====<br />
<br />
This example uses [[systemd]] for start up, [[WPA supplicant]] for connecting, and {{Pkg|dhcpcd}} for assigning an IP address.<br />
<br />
{{Note|Make sure that {{Pkg|wpa_supplicant}} is installed and create {{ic|/etc/wpa_supplicant/wpa_supplicant.conf}}. See [[WPA supplicant]] for details.}}<br />
<br />
Create a ''systemd'' unit, e.g {{ic|/etc/systemd/system/network-wireless@.service}}:<br />
<br />
{{hc|/etc/systemd/system/network-wireless@.service|<nowiki><br />
[Unit]<br />
Description=Wireless network connectivity (%i)<br />
Wants=network.target<br />
Before=network.target<br />
BindsTo=sys-subsystem-net-devices-%i.device<br />
After=sys-subsystem-net-devices-%i.device<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
<br />
ExecStart=/usr/bin/ip link set dev %i up<br />
ExecStart=/usr/bin/wpa_supplicant -B -i %i -c /etc/wpa_supplicant/wpa_supplicant.conf<br />
ExecStart=/usr/bin/dhcpcd %i<br />
<br />
ExecStop=/usr/bin/ip link set dev %i down<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
Start and/or enable the unit as described in [[systemd#Using units]], remember to pass the name of the interface:<br />
<br />
# systemctl enable network-wireless@wlan0.service<br />
# systemctl start network-wireless@wlan0.service<br />
<br />
===== Systemd with wpa_supplicant and static IP =====<br />
<br />
{{Note|Make sure that {{Pkg|wpa_supplicant}} is installed and create a custom {{ic|/etc/wpa_supplicant/wpa_supplicant.conf}}. See [[WPA supplicant]] for details.}}<br />
<br />
First create configuration file for the [[systemd]] service, replace {{ic|''interface''}} with the proper interface name for reference:<br />
<br />
{{hc|/etc/conf.d/network-wireless-''interface''|<nowiki><br />
address=192.168.0.10<br />
netmask=24<br />
broadcast=192.168.0.255<br />
gateway=192.168.0.1<br />
</nowiki>}}<br />
<br />
Create a ''systemd'' unit file:<br />
<br />
{{hc|/etc/systemd/system/network-wireless@.service|<nowiki><br />
[Unit]<br />
Description=Wireless network connectivity (%i)<br />
Wants=network.target<br />
Before=network.target<br />
BindsTo=sys-subsystem-net-devices-%i.device<br />
After=sys-subsystem-net-devices-%i.device<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
EnvironmentFile=/etc/conf.d/network-wireless-%i<br />
<br />
ExecStart=/usr/bin/ip link set dev %i up<br />
ExecStart=/usr/bin/wpa_supplicant -B -i %i -c /etc/wpa_supplicant/wpa_supplicant.conf<br />
ExecStart=/usr/bin/ip addr add ${address}/${netmask} broadcast ${broadcast} dev %i<br />
ExecStart=/usr/bin/ip route add default via ${gateway}<br />
<br />
ExecStop=/usr/bin/ip addr flush dev %i<br />
ExecStop=/usr/bin/ip link set dev %i down<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
[[systemd#Using units|Enable and start]] the unit {{ic|network-wireless@''interface''}}, passing your name of the interface.<br />
<br />
=== Automatic setup ===<br />
<br />
There are many solutions to choose from, but remember that all of them are mutually exclusive; you should not run two daemons simultaneously. The following table compares the different connection managers, additional notes are in subsections below.<br />
<br />
{| class="wikitable"<br />
! Connection manager || Network <br>profiles <br>support || Roaming <br>(auto connect dropped <br>or changed location) || [[Wikipedia:Point-to-Point Protocol|PPP]] support <br>(e.g. 3G modem) || Official <br>GUI || Console tools<br />
|-<br />
| [[Connman]] || Yes || Yes || Yes || No || {{ic|connmanctl}}<br />
|-<br />
| [[netctl]] || Yes || Yes || Yes || No || {{ic|netctl}},{{ic|wifi-menu}}<br />
|-<br />
| [[NetworkManager]] || Yes || Yes || Yes || Yes || {{ic|nmcli}}<br />
|-<br />
| [[Wicd]] || Yes || Yes || No || Yes || {{ic|wicd-curses}}<br />
|}<br />
<br />
==== Connman ====<br />
<br />
''ConnMan'' is an alternative to ''NetworkManager'' and ''Wicd'', designed to be light on resources making it ideal for netbooks, and other mobile devices. It is modular in design takes advandage of the dbus API and provides proper abstraction on top of ''wpa_supplicant''. <br />
<br />
See [[Connman]].<br />
<br />
==== netctl ====<br />
<br />
''netctl'' is a replacement for ''netcfg'' designed to work with ''systemd''. It uses a profile based setup and is capable of detection and connection to a wide range of network types. This is no harder than using graphical tools.<br />
<br />
See [[netctl]].<br />
<br />
==== Wicd ====<br />
<br />
''Wicd'' is a network manager that can handle both wireless and wired connections. It is written in Python and Gtk with fewer dependencies than ''NetworkManager'', making it an ideal solution for lightweight desktop users.<br />
<br />
See [[Wicd]].<br />
<br />
{{Note|[[wicd]] may cause excessive dropped connections with some drivers, while [[NetworkManager]] might work better.}}<br />
<br />
==== NetworkManager ====<br />
<br />
''NetworkManager'' is an advanced network management tool that is enabled by default in most popular GNU/Linux distributions. In addition to managing wired connections, ''NetworkManager'' provides worry-free wireless roaming with an easy-to-use GUI program for selecting your desired network.<br />
<br />
See [[NetworkManager]].<br />
<br />
{{Note|GNOME's {{Pkg|network-manager-applet}} also works under [[Xfce]] if you install {{AUR|xfce4-xfapplet-plugin}} (available in the [[Arch User Repository|AUR]]) first. Additionally, there are applets available for [[KDE]].}}<br />
<br />
==== WiFi Radar ====<br />
<br />
''WiFi Radar'' is a Python/PyGTK2 utility for managing wireless (and '''only''' wireless) profiles. It enables you to scan for available networks and create profiles for your preferred networks.<br />
<br />
See [[Wifi Radar]].<br />
<br />
== Troubleshooting ==<br />
<br />
This section contains general troubleshooting tips, not strictly related to problems with drivers or firmware. For such topics, see next section [[#Troubleshooting drivers and firmware]].<br />
<br />
=== Rfkill caveat ===<br />
<br />
Many laptops have a hardware button (or switch) to turn off wireless card, however, the card can also be blocked by kernel. This can be handled by {{Pkg|rfkill}}. Use ''rfkill'' to show the current status:<br />
<br />
{{hc|# rfkill list|<br />
0: phy0: Wireless LAN<br />
Soft blocked: yes<br />
Hard blocked: yes<br />
}}<br />
<br />
If the card is ''hard-blocked'', use the hardware button (switch) to unblock it. If the card is not ''hard-blocked'' but ''soft-blocked'', use the following command:<br />
<br />
# rfkill unblock wifi<br />
<br />
{{Note|It is possible that the card will go from ''hard-blocked'' and ''soft-unblocked'' state into ''hard-unblocked'' and ''soft-blocked'' state by pressing the hardware button (i.e. the ''soft-blocked'' bit is just switched no matter what). This can be adjusted by tuning some options of the {{ic|rfkill}} [[Kernel modules|kernel module]].}}<br />
<br />
More info: http://askubuntu.com/questions/62166/siocsifflags-operation-not-possible-due-to-rf-kill<br />
<br />
=== Respecting the regulatory domain ===<br />
<br />
The [http://en.wikipedia.org/wiki/IEEE_802.11#Regulatory_domains_and_legal_compliance regulatory domain], or "regdomain", is used to reconfigure wireless drivers to make sure that wireless hardware usage complies with local laws set by the FCC, ETSI and other organizations. Regdomains use [https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 ISO 3166-1 alpha-2 country codes]. For example, the regdomain of the United States would be "US", China would be "CN", etc.<br />
<br />
Regdomains affect the availability of wireless channels. In the 2.4GHz band, the allowed channels are 1-11 for the US, 1-14 for Japan, and 1-13 for most of the rest of the world. In the 5GHz band, the rules for allowed channels are much more complex. In either case, consult [https://en.wikipedia.org/wiki/List_of_WLAN_channels this list of WLAN channels] for more detailed information.<br />
<br />
Regdomains also affect the limit on the [https://en.wikipedia.org/wiki/Equivalent_isotropically_radiated_power effective isotropic radiated power (EIRP)] from wireless devices. This is derived from transmit power/"tx power", and is measured in [https://en.wikipedia.org/wiki/DBm dBm/mBm (1dBm=100mBm) or mW (log scale)]. In the 2.4GHz band, the maximum is 30dBm in the US and Canada, 20dBm in most of Europe, and 20dB-30dBm for the rest of the world. In the 5GHz band, maximums are usually lower. Consult the [http://git.kernel.org/cgit/linux/kernel/git/linville/wireless-regdb.git/tree/db.txt wireless-regdb] for more detailed information (EIRP dBm values are in the second set of brackets for each line).<br />
<br />
Misconfiguring the regdomain can be useful - for example, by allowing use of an unused channel when other channels are crowded, or by allowing an increase in tx power to widen transmitter range. However, '''this is not recommended''' as it could break local laws and cause interference with other radio devices.<br />
<br />
To configure the regdomain, install {{Pkg|crda}} and {{Pkg|wireless-regdb}} and reboot (to reload the {{ic|cfg80211}} module and all related drivers). Check the boot log to make sure that CRDA is being called by {{ic|cfg80211}}:<br />
<br />
$ dmesg | grep cfg80211<br />
<br />
The current regdomain can be set to the United States with:<br />
<br />
# iw reg set US<br />
<br />
And queried with:<br />
<br />
$ iw reg get<br />
<br />
{{Note|Your device may be set to country "00", which is the "world regulatory domain" and contains generic settings. If this cannot be unset, CRDA may be misconfigured.}}<br />
<br />
However, setting the regdomain may not alter your settings. Some devices have a regdomain set in firmware/EEPROM, which dictates the limits of the device, meaning that setting regdomain in software [http://wiki.openwrt.org/doc/howto/wireless.utilities#iw can only increase restrictions], not decrease them. For example, a CN device could be set in software to the US regdomain, but because CN has an EIRP maximum of 20dBm, the device will not be able to transmit at the US maximum of 30dBm.<br />
<br />
For example, to see if the regdomain is being set in firmware for an Atheros device:<br />
<br />
$ dmesg | grep ath:<br />
<br />
For other chipsets, it may help to search for "EEPROM", "regdomain", or simply the name of the device driver.<br />
<br />
To see if your regdomain change has been successful, and to query the number of available channels and their allowed transmit power:<br />
<br />
$ iw list | grep -A 15 Frequencies:<br />
<br />
A more permanent configuration of the regdomain can be achieved through editing {{ic|/etc/conf.d/wireless-regdom}} and uncommenting the appropriate domain. {{ic|wpa_supplicant}} can also use a regdomain in the {{ic|1=country=}} line of {{ic|/etc/wpa_supplicant.conf}}.<br />
<br />
It is also possible to configure the [http://wireless.kernel.org/en/developers/Documentation/cfg80211 cfg80211] kernel module to use a specific regdomain by adding, for example, {{ic|1=options cfg80211 ieee80211_regdom=EU}} to {{ic|/etc/modprobe.d/modprobe.conf}}. However, this is part of the [http://wireless.kernel.org/en/developers/Regulatory#The_ieee80211_regdom_module_parameter old regulatory implementation].<br />
<br />
For further information, read the [http://wireless.kernel.org/en/developers/Regulatory/ wireless.kernel.org regulatory documentation].<br />
<br />
=== Observing Logs === <br />
<br />
A good first measure to troubleshoot is to analyze the system's logfiles first. In order not to manually parse through them all, it can help to open a second terminal/console window and watch the kernels messages with <br />
$ dmesg -w<br />
while performing the action, e.g. the wireless association attempt. <br />
<br />
When using a tool for network management, the same can be done for systemd with <br />
# journalctl -f <br />
<br />
Frequently a wireless error is accompanied by a deauthentication with a particular reason code, for example: <br />
wlan0: deauthenticating from XX:XX:XX:XX:XX:XX by local choice (reason=3)<br />
Looking up [http://www.aboutcher.co.uk/2012/07/linux-wifi-deauthenticated-reason-codes/ the reason code] might give a first hint. <br />
<br />
The individual tools used in this article further provide options for more detailed debugging output, which can be used in a second step of the analysis, if required.<br />
<br />
=== Failure to Connect ===<br />
<br />
{{Poor writing|No structure. Check if it can be structured as another cause # in [[#Random_disconnections]], best with an explanation on why changing the router parameters may be a worthwhile try.}}<br />
<br />
First try to connect to the network with no authentication<br />
<br />
==== Other troubling-shooting in no particular order: ====<br />
<br />
Try disabling n mode within your router/Access Point settings.<br />
<br />
Change the the channel of in your Access Point<br />
<br />
Use a channel width of 20hz instead of 40hz<br />
<br />
=== Power saving ===<br />
<br />
See [[Power saving#Network interfaces]].<br />
<br />
=== Failed to get IP address ===<br />
<br />
* If getting an IP address repeatedly fails using the default {{Pkg|dhcpcd}} client, try installing and using {{Pkg|dhclient}} instead. Do not forget to select ''dhclient'' as the primary DHCP client in your [[#Automatic setup|connection manager]]!<br />
<br />
* If you can get an IP address for a wired interface and not for a wireless interface, try disabling the wireless card's power saving features:<br />
<br />
# iw dev wlan0 set power_save off<br />
<br />
* If you get a timeout error due to a ''waiting for carrier'' problem, then you might have to set the channel mode to {{ic|auto}} for the specific device:<br />
<br />
# iwconfig wlan0 channel auto<br />
<br />
Before changing the channel to auto, make sure your wireless interface is down. After it has successfully changed it, you can bring the interface up again and continue from there.<br />
<br />
=== Valid IP address but cannot resolve host ===<br />
<br />
If you are on a public wireless network that may have a [https://en.wikipedia.org/wiki/Captive_portal captive portal], be sure to remove {{ic|/etc/resolv.conf.head}} as custom DNS servers cause the captive portals to fail.<br />
<br />
=== Connection always times out ===<br />
<br />
The driver may suffer from a lot of tx excessive retries and invalid misc errors for some unknown reason, resulting in a lot of packet loss and keep disconnecting, sometimes instantly. Following tips might be helpful.<br />
<br />
==== Lowering the rate ====<br />
<br />
Try setting lower rate, for example 5.5M:<br />
<br />
# iwconfig wlan0 rate 5.5M auto<br />
<br />
Fixed option should ensure that the driver does not change the rate on its own, thus making the connection a bit more stable:<br />
<br />
# iwconfig wlan0 rate 5.5M fixed<br />
<br />
==== Lowering the txpower ====<br />
<br />
You can try lowering the transmit power as well. This may save power as well:<br />
<br />
# iwconfig wlan0 txpower 5<br />
<br />
Valid settings are from {{ic|0}} to {{ic|20}}, {{ic|auto}} and {{ic|off}}.<br />
<br />
==== Setting rts and fragmentation thresholds ====<br />
<br />
Default iwconfig options have rts and fragmentation thresholds off. These options are particularly useful when there are many adjacent APs or in a noisy environment.<br />
<br />
The minimum value for fragmentation value is 256 and maximum is 2346. In many windows drivers the maximum is the default value:<br />
<br />
# iwconfig wlan0 frag 2346<br />
<br />
For rts minimum is 0, maximum is 2347. Once again windows drivers often use maximum as the default:<br />
<br />
# iwconfig wlan0 rts 2347<br />
<br />
=== Random disconnections ===<br />
<br />
==== Cause #1 ====<br />
<br />
If dmesg says {{ic|1=wlan0: deauthenticating from MAC by local choice (reason=3)}} and you lose your Wi-Fi connection, it is likely that you have a bit too aggressive power-saving on your Wi-Fi card[http://us.generation-nt.com/answer/gentoo-user-wireless-deauthenticating-by-local-choice-help-204640041.html]. Try disabling the wireless card's power-saving features:<br />
<br />
# iwconfig wlan0 power off<br />
<br />
See [[Power saving]] for tips on how to make it permanent (just specify {{ic|off}} instead of {{ic|on}}).<br />
<br />
If your card does not support {{ic|iwconfig wlan0 power off}}, check the '''BIOS''' for power management options. Disabling PCI-Express power management in the BIOS of a Lenovo W520 resolved this issue.<br />
<br />
==== Cause #2 ====<br />
<br />
If you are experiencing frequent disconnections and dmesg shows messages such as <br />
<br />
{{ic|1=ieee80211 phy0: wlan0: No probe response from AP xx:xx:xx:xx:xx:xx after 500ms, disconnecting}}<br />
<br />
try changing the channel bandwidth to {{ic|20MHz}} through your router's settings page.<br />
<br />
==== Cause #3 ====<br />
<br />
On some laptop models with hardware rfkill switches (e.g., Thinkpad X200 series), due to wear or bad design, the switch (or its connection to the mainboard) might become loose over time resulting in seemingly random hardblocks/disconnects when you accidentally touch the switch or move the laptop.<br />
There is no software solution to this, unless your switch is electrical and the BIOS offers the option to disable the switch.<br />
If your switch is mechanical (most are), there are lots of possible solutions, most of which aim to disable the switch: Soldering the contact point on the mainboard/wifi-card, glueing or blocking the switch, using a screw nut to tighten the switch or removing it altogether.<br />
<br />
== Troubleshooting drivers and firmware ==<br />
<br />
This section covers methods and procedures for installing kernel modules and ''firmware'' for specific chipsets, that differ from generic method.<br />
<br />
See [[Kernel modules]] for general informations on operations with modules.<br />
<br />
=== Ralink ===<br />
<br />
==== rt2x00 ====<br />
<br />
Unified driver for Ralink chipsets (it replaces {{ic|rt2500}}, {{ic|rt61}}, {{ic|rt73}}, etc). This driver has been in the Linux kernel since 2.6.24, you only need to load the right module for the chip: {{ic|rt2400pci}}, {{ic|rt2500pci}}, {{ic|rt2500usb}}, {{ic|rt61pci}} or {{ic|rt73usb}} which will autoload the respective {{ic|rt2x00}} modules too.<br />
<br />
A list of devices supported by the modules is available at the project's [http://rt2x00.serialmonkey.com/wiki/index.php/Hardware homepage].<br />
<br />
; Additional notes<br />
* Since kernel 3.0, rt2x00 includes also these drivers: {{ic|rt2800pci}}, {{ic|rt2800usb}}.<br />
* Since kernel 3.0, the staging drivers {{ic|rt2860sta}} and {{ic|rt2870sta}} are replaced by the mainline drivers {{ic|rt2800pci}} and {{ic|rt2800usb}}<sup>[https://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commitdiff;h=fefecc6989b4b24276797270c0e229c07be02ad3]</sup>.<br />
* Some devices have a wide range of options that can be configured with {{ic|iwpriv}}. These are documented in the [http://web.ralinktech.com/ralink/Home/Support/Linux.html source tarballs] available from Ralink.<br />
<br />
==== rt3090 ====<br />
<br />
For devices which are using the rt3090 chipset it should be possible to use {{ic|rt2800pci}} driver, however, is not working with this chipset very well (e.g. sometimes it's not possible to use higher rate than 2Mb/s).<br />
<br />
The best way is to use the {{AUR|rt3090-dkms}} driver from [[AUR]]. Make sure to [[Kernel modules#Blacklisting|blacklist]] the {{ic|rt2800pci}} module and setup the {{ic|rt3090sta}} module to [[Kernel modules#Loading|load]] at boot.<br />
<br />
{{Note|This driver also works with rt3062 chipsets. Also the {{AUR|rt3090}} package is not supported by the latest kernel and has been orphaned {{AUR|rt3090-dkms}} should be used instead. }}<br />
<br />
==== rt3290 ====<br />
<br />
The rt3290 chipset is recognised by the kernel {{ic|rt2800pci}} module. However, some users experience problems and reverting to a patched Ralink driver seems to be beneficial in these [https://bbs.archlinux.org/viewtopic.php?id=161952 cases].<br />
<br />
==== rt3573 ====<br />
<br />
New chipset as of 2012. It may require proprietary drivers from Ralink. Different manufacturers use it, see the [https://bbs.archlinux.org/viewtopic.php?pid=1164228#p1164228 Belkin N750 DB wireless usb adapter] forums thread.<br />
<br />
==== rt5572 ====<br />
<br />
New chipset as of 2012 with support for 5 Ghz bands. It may require proprietary drivers from Ralink and some effort to compile them. At the time of writing a how-to on compilation is available for a DLINK DWA-160 rev. B2 [http://bernaerts.dyndns.org/linux/229-ubuntu-precise-dlink-dwa160-revb2 here].<br />
<br />
=== Realtek ===<br />
<br />
==== rtl8192cu ====<br />
<br />
The driver is now in the kernel, but many users have reported being unable to make a connection although scanning for networks does work.<br />
<br />
Package {{AUR|8192cu-dkms}} in the AUR includes many patches, try this if it doesn't work fine with the driver in kernel.<br />
<br />
==== rtl8192e ====<br />
<br />
The driver is part of the current kernel package. The module initialization may fail at boot giving this error message:<br />
<br />
rtl819xE:ERR in CPUcheck_firmware_ready()<br />
rtl819xE:ERR in init_firmware() step 2<br />
rtl819xE:ERR!!! _rtl8192_up(): initialization is failed!<br />
r8169 0000:03:00.0: eth0: link down<br />
<br />
A workaround is to simply unload the module:<br />
# modprobe -r r8192e_pci<br />
and reload the module (after a pause):<br />
# modprobe r8192e_pci<br />
<br />
==== rtl8188eu ====<br />
<br />
Some dongles, like the TP-Link TL-WN725N v2 (not sure, but it seems that uses the rtl8179 chipset), use chipsets compatible with this driver. In Linux 3.12 the driver [http://lwn.net/Articles/564798/ has been moved] to kernel staging source tree. For older kernels use out-of-tree driver sources built with [[dkms]] - install the {{AUR|dkms-8188eu}} package from AUR. At the times of 3.15 kernel rtl8188eu driver is buggy and has many stability issues.<br />
<br />
==== rtl8723be ====<br />
<br />
The {{ic|rtl8723be}} module is included in the mainline Linux kernel since version 3.15.<br />
<br />
Some users may encounter errors with powersave on this card. This is shown with occasional disconnects that are not recognized by high level network managers ([[netctl]], [[NetworkManager]]). This error can be confirmed by running {{ic|dmesg -w}} or {{ic|journalctl -f}} and looking for output related to powersave and the {{ic|rtl8723be}} module. If you are having this issue, use the {{ic|1=fwlps=0}} kernel option, which should prevent the WiFi card from automatically sleeping and halting connection.<br />
<br />
{{hc|/etc/modprobe.d/rtl8723be.conf|2=<br />
options rtl8723be fwlps=0<br />
}}<br />
<br />
=== Atheros ===<br />
<br />
The [http://madwifi-project.org/ MadWifi team] currently maintains three different drivers for devices with Atheros chipset:<br />
<br />
* {{ic|madwifi}} is an old, obsolete driver. Not present in Arch kernel since 2.6.39.1<sup>[https://mailman.archlinux.org/pipermail/arch-dev-public/2011-June/020669.html]</sup>.<br />
* {{ic|ath5k}} is newer driver, which replaces the {{ic|madwifi}} driver. Currently a better choice for some chipsets, but not all chipsets are supported (see below)<br />
* {{ic|ath9k}} is the newest of these three drivers, it is intended for newer Atheros chipsets. All of the chips with 802.11n capabilities are supported.<br />
<br />
There are some other drivers for some Atheros devices. See [http://wireless.kernel.org/en/users/Drivers/Atheros#PCI_.2F_PCI-E_.2F_AHB_Drivers Linux Wireless documentation] for details.<br />
<br />
==== ath5k ====<br />
<br />
External resources:<br />
* http://wireless.kernel.org/en/users/Drivers/ath5k<br />
* http://wiki.debian.org/ath5k<br />
<br />
If you find web pages randomly loading very slow, or if the device is unable to lease an IP address, try to switch from hardware to software encryption by loading the {{ic|ath5k}} module with {{ic|1=nohwcrypt=1}} option. See [[Kernel Modules#Setting module options]] for details.<br />
<br />
Some laptops may have problems with their wireless LED indicator flickering red and blue. To solve this problem, do:<br />
<br />
# echo none > /sys/class/leds/ath5k-phy0::tx/trigger<br />
# echo none > /sys/class/leds/ath5k-phy0::rx/trigger<br />
<br />
For alternatives, see [https://bugzilla.redhat.com/show_bug.cgi?id=618232 this bug report].<br />
<br />
==== ath9k ====<br />
<br />
External resources:<br />
* http://wireless.kernel.org/en/users/Drivers/ath9k<br />
* http://wiki.debian.org/ath9k<br />
<br />
As of Linux 3.15.1, some users have been experiencing a decrease in bandwidth. In some cases this can fixed by editing {{ic|/etc/modprobe.d/ath9k.conf}} and adding the line:<br />
options ath9k nohwcrypt=1<br />
<br />
{{Note|Check with the command lsmod what module(-name) is in use and change it if named otherwise (e.g. ath9k_htc).}}<br />
<br />
In the unlikely event that you have stability issues that trouble you, you could try using the {{AUR|backports-patched}} package. An [https://lists.ath9k.org/mailman/listinfo/ath9k-devel ath9k mailing list] exists for support and development related discussions.<br />
<br />
===== Power saving =====<br />
<br />
Although [http://wireless.kernel.org/en/users/Documentation/dynamic-power-save Linux Wireless] says that dynamic power saving is enabled for Atheros ath9k single-chips newer than AR9280, for some devices (e.g. AR9285) {{Pkg|powertop}} might still report that power saving is disabled. In this case enable it manually.<br />
<br />
On some devices (e.g. AR9285), enabling the power saving might result in the following error:<br />
<br />
{{hc|# iw wlan0 set power_save on|<br />
command failed: Operation not supported (-95)<br />
}}<br />
<br />
The solution is to set the {{ic|1=ps_enable=1}} option for the {{ic|ath9k}} module:<br />
<br />
{{hc|/etc/modprobe.d/ath9k.conf|2=<br />
options ath9k ps_enable=1<br />
}}<br />
<br />
===== ASUS =====<br />
<br />
{{Moveto||How is this related to {{ic|ath9k}} driver? There must be some better place for this stuff.}}<br />
<br />
With some ASUS laptops (tested with ASUS U32U series), it could help to add {{ic|1=options asus_nb_wmi wapf=1}} to {{ic|/etc/modprobe.d/asus_nb_wmi.conf}} to fix rfkill-related issues.<br />
<br />
You can also try to blacklist the module asus_nb_wmi (tested with ASUSPRO P550C):<br />
# echo "blacklist asus_nb_wmi" >> /etc/modprobe.d/blacklist.conf<br />
<br />
=== Intel ===<br />
<br />
==== ipw2100 and ipw2200 ====<br />
<br />
These modules are fully supported in the kernel, but they require additional firmware. Depending on which of the chipsets you have, [[pacman|install]] either {{Pkg|ipw2100-fw}} or {{Pkg|ipw2200-fw}}. Then [[Kernel modules#Manual module handling|reload]] the appropriate module.<br />
<br />
{{Tip|You may use the following [[Kernel modules#Setting module options|module options]]:<br />
* use the {{ic|1=rtap_iface=1}} option to enable the radiotap interface<br />
* use the {{ic|1=led=1}} option to enable a front LED indicating when the wireless is connected or not<br />
}}<br />
<br />
==== iwlegacy ====<br />
<br />
[http://wireless.kernel.org/en/users/Drivers/iwlegacy iwlegacy] is the wireless driver for Intel's 3945 and 4965 wireless chips. The firmware is included in the {{Pkg|linux-firmware}} package.<br />
<br />
[[udev]] should load the driver automatically, otherwise load {{ic|iwl3945}} or {{ic|iwl4965}} manually. See [[Kernel modules#Loading]] for details.<br />
<br />
==== iwlwifi ====<br />
<br />
[http://wireless.kernel.org/en/users/Drivers/iwlwifi iwlwifi] is the wireless driver for Intel's current wireless chips, such as 5100AGN, 5300AGN, and 5350AGN. See the [http://wireless.kernel.org/en/users/Drivers/iwlwifi#Supported_Devices full list of supported devices]. The firmware is included in the {{Pkg|linux-firmware}} package.<br />
<br />
If you have problems connecting to networks in general or your link quality is very poor, try to disable 802.11n, and perhaps also enable software encryption:<br />
<br />
{{hc|/etc/modprobe.d/iwlwifi.conf|2=<br />
options iwlwifi 11n_disable=1<br />
options iwlwifi swcrypto=1<br />
}}<br />
<br />
If you have a problem with slow uplink speed in 802.11n mode, for example 20Mbps, try to enable antenna aggregation:<br />
<br />
{{hc|/etc/modprobe.d/iwlwifi.conf|2=<br />
options iwlwifi 11n_disable=8<br />
}}<br />
<br />
Do not be confused with the option name, when the value is set to {{ic|8}} it does not disable anything but re-enables transmission antenna aggregation.[http://forums.gentoo.org/viewtopic-t-996692.html?sid=81bdfa435c089360bdfd9368fe0339a9] [https://bugzilla.kernel.org/show_bug.cgi?id=81571]<br />
<br />
In case this does not work for you, you may try disabling power saving for your wireless adapter. For a permanent solution, add a new udev rule:<br />
<br />
{{hc|/etc/udev/rules.d/80-iwlwifi.rules|2=<br />
ACTION=="add", SUBSYSTEM=="net", ATTR{address}=="''your_mac_address''", RUN+="/usr/bin/iw dev %k set power_save off"<br />
}}<br />
<br />
[http://ubuntuforums.org/showthread.php?t=2183486&p=12845473#post12845473 Some] have never gotten this to work. [http://ubuntuforums.org/showthread.php?t=2205733&p=12935783#post12935783 Others] found salvation by disabling N in their router settings after trying everything. This is known to have be the only solution on more than one occasion. The second link there mentions a 5ghz option that might be worth exploring.<br />
<br />
{{Note|1=The {{pkg|linux-lts}}-3.14 kernel may take several minutes to load the firmware and make the wireless card ready for use. The issue is reported to be fixed in {{pkg|linux}}-3.17 kernel.[https://bbs.archlinux.org/viewtopic.php?id=190757]}}<br />
<br />
==== Disabling LED blink ====<br />
<br />
{{Note|This works with the {{ic|iwlegacy}} and {{ic|iwlwifi}} drivers.}}<br />
<br />
The default settings on the module are to have the LED blink on activity. Some people find this extremely annoying. To have the LED on solid when Wi-Fi is active, you can use the [[systemd#Temporary files|systemd-tmpfiles]]:<br />
<br />
{{hc|/etc/tmpfiles.d/phy0-led.conf|<br />
w /sys/class/leds/phy0-led/trigger - - - - phy0radio<br />
}}<br />
<br />
Run {{ic|systemd-tmpfiles --create phy0-led.conf}} for the change to take effect, or reboot.<br />
<br />
To see all the possible trigger values for this LED:<br />
<br />
# cat /sys/class/leds/phy0-led/trigger<br />
<br />
{{Tip|If you do not have {{ic|/sys/class/leds/phy0-led}}, you may try to use the {{ic|1=led_mode="1"}} [[Kernel modules#Setting module options|module option]]. It should be valid for both {{ic|iwlwifi}} and {{ic|iwlegacy}} drivers.}}<br />
<br />
=== Broadcom ===<br />
<br />
See [[Broadcom wireless]].<br />
<br />
=== Other drivers/devices ===<br />
<br />
==== Tenda w322u ====<br />
<br />
Treat this Tenda card as an {{ic|rt2870sta}} device. See [[#rt2x00]].<br />
<br />
==== orinoco ====<br />
<br />
This should be a part of the kernel package and be installed already.<br />
<br />
Some Orinoco chipsets are Hermes II. You can use the {{ic|wlags49_h2_cs}} driver instead of {{ic|orinoco_cs}} and gain WPA support. To use the driver, [[Kernel modules#Blacklisting|blacklist]] {{ic|orinoco_cs}} first.<br />
<br />
==== prism54 ====<br />
<br />
The driver {{ic|p54}} is included in kernel, but you have to download the appropriate firmware for your card from [http://linuxwireless.org/en/users/Drivers/p54#firmware this site] and install it into the {{ic|/usr/lib/firmware}} directory.<br />
<br />
{{Note|There's also older, deprecated driver {{ic|prism54}}, which might conflict with the newer driver ({{ic|p54pci}} or {{ic|p54usb}}). Make sure to [[Kernel modules#Blacklisting|blacklist]] {{ic|prism54}}.}}<br />
<br />
==== ACX100/111 ====<br />
<br />
{{Warning|The drivers for these devices [https://mailman.archlinux.org/pipermail/arch-dev-public/2011-June/020669.html are broken] and do not work with newer kernel versions.}}<br />
<br />
Packages: {{ic|tiacx}} {{ic|tiacx-firmware}} (deleted from official repositories and AUR)<br />
<br />
See [http://sourceforge.net/apps/mediawiki/acx100/index.php?title=Main_Page official wiki] for details.<br />
<br />
==== zd1211rw ====<br />
<br />
[http://zd1211.wiki.sourceforge.net/ {{ic|zd1211rw}}] is a driver for the ZyDAS ZD1211 802.11b/g USB WLAN chipset, and it is included in recent versions of the Linux kernel. See [http://www.linuxwireless.org/en/users/Drivers/zd1211rw/devices] for a list of supported devices. You only need to [[pacman|install]] the firmware for the device, provided by the {{Pkg|zd1211-firmware}} package.<br />
<br />
==== hostap_cs ====<br />
<br />
[http://hostap.epitest.fi/ Host AP] is a Linux driver for wireless LAN cards based on Intersil's Prism2/2.5/3 chipset. The driver is included in Linux kernel.<br />
<br />
{{Note|Make sure to [[Kernel_modules#Blacklisting|blacklist]] the {{ic|orinico_cs}} driver, it may cause problems.}}<br />
<br />
=== ndiswrapper ===<br />
<br />
Ndiswrapper is a wrapper script that allows you to use some Windows drivers in Linux. You will need the {{ic|.inf}} and {{ic|.sys}} files from your Windows driver. <br />
{{Note|Be sure to use drivers appropriate to your architecture (x86 vs. x86_64).}}<br />
<br />
{{Tip|If you need to extract these files from an {{ic|*.exe}} file, you can use {{Pkg|cabextract}}.}}<br />
<br />
Follow these steps to configure ndiswrapper.<br />
<br />
1. Install {{AUR|ndiswrapper}} package from the [[AUR]]<br />
<br />
2. Install the driver to {{ic|/etc/ndiswrapper/*}}<br />
# ndiswrapper -i filename.inf<br />
<br />
3. List all installed drivers for ndiswrapper<br />
$ ndiswrapper -l<br />
<br />
4. Let ndiswrapper write its configuration in {{ic|/etc/modprobe.d/ndiswrapper.conf}}:<br />
# ndiswrapper -m<br />
# depmod -a<br />
<br />
Now the ndiswrapper install is almost finished; follow the instructions on [[Kernel modules#Loading]] to automatically load the module at boot.<br />
<br />
The important part is making sure that ndiswrapper exists on this line, so just add it alongside the other modules. It would be best to test that ndiswrapper will load now, so:<br />
# modprobe ndiswrapper<br />
# iwconfig<br />
<br />
and ''wlan0'' should now exist. If you have problems, some help is available at:<br />
[http://sourceforge.net/p/ndiswrapper/ndiswrapper/HowTos/ ndiswrapper howto] and [http://sourceforge.net/p/ndiswrapper/ndiswrapper/FAQ/ ndiswrapper FAQ].<br />
<br />
=== compat-drivers-patched ===<br />
<br />
{{Out of date|{{AUR|compat-drivers-patched}} has reached end-of-life, {{AUR|backports-patched}} should be used instead}}<br />
<br />
Patched compat wireless drivers correct the "fixed-channel -1" issue, whilst providing better injection. Please install the {{AUR|compat-drivers-patched}} package from the [[Arch User Repository|AUR]].<br />
<br />
{{AUR|compat-drivers-patched}} does not conflict with any other package and the modules built reside in {{ic|/usr/lib/modules/''your_kernel_version''/updates}}.<br />
<br />
These patched drivers come from the [http://wireless.kernel.org/ Linux Wireless project] and support many of the above mentioned chips such as:<br />
<br />
ath5k ath9k_htc carl9170 b43 zd1211rw rt2x00 wl1251 wl12xx ath6kl brcm80211<br />
<br />
Supported groups:<br />
<br />
atheros ath iwlagn rtl818x rtlwifi wl12xx atlxx bt<br />
<br />
It is also possible to build a specific module/driver or a group of drivers by editing the [[PKGBUILD]], particularly uncommenting the '''line #46'''. Here is an example of building the atheros group:<br />
<br />
scripts/driver-select atheros<br />
<br />
Please read the package's [[PKGBUILD]] for any other possible modifications prior to compilation and installation.<br />
<br />
== See also ==<br />
<br />
* [http://wireless.kernel.org/ The Linux Wireless project]<br />
* [http://aircrack-ng.org/doku.php?id=install_drivers Aircrack-ng guide on installing drivers]</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Xorg/Keyboard_configuration&diff=369542Xorg/Keyboard configuration2015-04-14T01:31:15Z<p>Fylwind: /* Key combinations */ remark about locale generation</p>
<hr />
<div>[[Category:Keyboards]]<br />
[[Category:X Server]]<br />
[[es:Keyboard Configuration in Xorg]]<br />
[[ja:Xorg でのキーボード設定]]<br />
{{Related articles start}}<br />
{{Related|Keyboard configuration in console}}<br />
{{Related|Extra keyboard keys}}<br />
{{Related|Xorg}}<br />
{{Related|X KeyBoard extension}}<br />
{{Related articles end}}<br />
<br />
This article's purpose is to detail basic Xorg server keyboard configuration. For advanced topics such as keyboard layout modification or additional key mappings, see [[Extra keyboard keys]].<br />
<br />
== Overview ==<br />
<br />
The Xorg server uses the [[X KeyBoard extension]] (XKB) to define keyboard layouts. Optionally, [[xmodmap]] can be used to access the internal keymap table directly, although this is not recommended for complex tasks. Also [[systemd]]'s ''localectl'' can be used to define the keyboard layout for both the Xorg server and the virtual console.<br />
<br />
{{Note|XKB options can be overridden by the tools provided by some desktop environments such as [[GNOME#XkbOptions_keyboard_options|GNOME (XkbOptions)]] and [[KDE#Set keyboard|KDE (set keyboard)]].}}<br />
<br />
== Viewing keyboard settings ==<br />
<br />
You can use the following command to see the actual XKB settings:<br />
<br />
{{hc|$ setxkbmap -print -verbose 10|<nowiki><br />
Setting verbose level to 10<br />
locale is C<br />
Applied rules from evdev:<br />
model: evdev<br />
layout: us<br />
options: terminate:ctrl_alt_bksp<br />
Trying to build keymap using the following components:<br />
keycodes: evdev+aliases(qwerty)<br />
types: complete<br />
compat: complete<br />
symbols: pc+us+inet(evdev)+terminate(ctrl_alt_bksp)<br />
geometry: pc(pc104)<br />
xkb_keymap {<br />
xkb_keycodes { include "evdev+aliases(qwerty)" };<br />
xkb_types { include "complete" };<br />
xkb_compat { include "complete" };<br />
xkb_symbols { include "pc+us+inet(evdev)+terminate(ctrl_alt_bksp)" };<br />
xkb_geometry { include "pc(pc104)" };<br />
};<br />
</nowiki>}}<br />
<br />
=== Third party utilities ===<br />
<br />
There are some "unofficial" utilities which allow to print specific information about the currently used keyboard layout.<br />
<br />
* {{AUR|xkb-switch-git}}:<br />
<br />
{{hc|$ xkb-switch|us}}<br />
<br />
* {{AUR|xkblayout-state}}:<br />
<br />
{{hc|$ xkblayout-state print "%s"|de}}<br />
<br />
== Setting keyboard layout ==<br />
<br />
Keyboard layout in Xorg can be set in multiple ways. Here is an explanation of used options:<br />
<br />
* {{ic|XkbModel}} selects the keyboard model. This has an influence only for some extra keys your keyboard might have. The safe fallback are {{ic|pc104}} or {{ic|pc105}}. But for instance laptops usually have some extra keys, and sometimes you can make them work by simply setting a proper model.<br />
* {{ic|XkbLayout}} selects the keyboard layout. Multiple layouts may be specified in a comma-separated list, e.g. if you want to quickly switch between layouts.<br />
* {{ic|XkbVariant}} selects a specific layout variant. For instance, the default {{ic|sk}} variant is {{ic|qwertz}}, but you can manually specify {{ic|qwerty}}, etc.<br />
* {{ic|XkbOptions}} contains some extra options. Used for specifying layout switching, notification LED, compose mode etc.<br />
<br />
{{Note|You must specify as many variants as the number of specified layouts. If you want the default variant, specify an empty string as the variant (the comma must stay). For example, to have the default {{ic|us}} layout as primary and the {{ic|dvorak}} variant of {{ic|us}} layout as secondary, specify {{ic|us,us}} as {{ic|XkbLayout}} and {{ic|,dvorak}} as {{ic|XkbVariant}}.}}<br />
<br />
The layout name is usually a [[Wikipedia:ISO_3166-1_alpha-2#Officially_assigned_code_elements|2-letter country code]]. To see a full list of keyboard models, layouts, variants and options, along with a short description, open {{ic|/usr/share/X11/xkb/rules/base.lst}}. Alternatively, you may use one of the following commands to see a list without a description:<br />
<br />
* {{ic|localectl list-x11-keymap-models}}<br />
* {{ic|localectl list-x11-keymap-layouts}}<br />
* {{ic|localectl list-x11-keymap-variants [''layout'']}}<br />
* {{ic|localectl list-x11-keymap-options}}<br />
<br />
Examples in the following subsections will have the same effect, they will set {{ic|pc104}} model, {{ic|cz}} as primary layout, {{ic|us}} as secondary layout, {{ic|dvorak}} variant for {{ic|us}} layout and the {{ic|Alt+Shift}} combination for switching between layouts.<br />
<br />
=== Using setxkbmap ===<br />
<br />
''setxkbmap'' sets the keyboard layout for the current X session only, but can be made persistent in [[xinitrc|~/.xinitrc]]. This overrides system-wide configuration specified by [[#Using X configuration files|X configuration files]].<br />
<br />
The usage is as follows (see {{ic|man 1 setxkbmap}}):<br />
<br />
$ setxkbmap [-model ''xkb_model''] [-layout ''xkb_layout''] [-variant ''xkb_variant''] [-option ''xkb_options'']<br />
<br />
To change just the layout ({{ic|-layout}} is the default flag):<br />
<br />
$ setxkbmap ''xkb_layout''<br />
<br />
For multiple customizations:<br />
<br />
$ setxkbmap -model pc104 -layout cz,us -variant ,dvorak -option grp:alt_shift_toggle<br />
<br />
=== Using X configuration files ===<br />
<br />
{{Note|{{ic|xorg.conf}} is parsed by the X server at start-up. To apply changes, restart X. [http://fedoraproject.org/wiki/Input_device_configuration#xorg.conf.d].}}<br />
<br />
The syntax of X configuration files is explained in [[Xorg#Configuration]]. This method creates system-wide configuration which is persistent across reboots.<br />
<br />
Here is an example:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/10-keyboard.conf|<br />
Section "InputClass"<br />
Identifier "system-keyboard"<br />
MatchIsKeyboard "on"<br />
Option "XkbLayout" "cz,us"<br />
Option "XkbModel" "pc104"<br />
Option "XkbVariant" ",dvorak"<br />
Option "XkbOptions" "grp:alt_shift_toggle"<br />
EndSection<br />
}}<br />
<br />
==== Using localectl ====<br />
<br />
For convenience, the tool ''localectl'' may be used instead of manually editing X configuration files. It will save the configuration in {{ic|/etc/X11/xorg.conf.d/00-keyboard.conf}}, this file should not be manually edited, because ''localectl'' will overwrite the changes on next start.<br />
<br />
The usage is as follows:<br />
<br />
$ localectl [--no-convert] set-x11-keymap ''layout'' [''model'' [''variant'' [''options'']]]<br />
<br />
To set a ''model'', ''variant'' or ''options'', all preceding fields need to be specified. Unless the {{ic|--no-convert}} option is passed, the specified keymap is also converted to the closest matching console keymap and applied to the [[Keyboard configuration in console|console configuration]] in {{ic|vconsole.conf}}. See {{ic|man localectl}} for more information.<br />
<br />
To create a {{ic|/etc/X11/xorg.conf.d/00-keyboard.conf}} like the above:<br />
<br />
$ localectl --no-convert set-x11-keymap cz,us pc104 ,dvorak grp:alt_shift_toggle<br />
<br />
== Frequently used XKB options ==<br />
<br />
=== Switching between keyboard layouts ===<br />
<br />
To be able to easily switch keyboard layouts, first specify multiple layouts between which you want to switch (the first one is the default). Then specify a key (or key combination), which will be used for switching. For example, to switch between a US and a Swedish layout using the {{ic|CapsLock}} key, use {{ic|us,se}} as an argument of {{ic|XkbLayout}} and {{ic|grp:caps_toggle}} as an argument of {{ic|XkbOptions}}.<br />
<br />
You can use other key combinations than {{ic|CapsLock}}, they are listed in {{ic|/usr/share/X11/xkb/rules/base.lst}}, start with {{ic|grp:}} and end with {{ic|toggle}}. To get the full list of available options, run the following command:<br />
<br />
$ grep "grp:.*toggle" /usr/share/X11/xkb/rules/base.lst<br />
<br />
=== Terminating Xorg with Ctrl+Alt+Backspace ===<br />
<br />
By default, the key combination {{ic|Ctrl+Alt+Backspace}} is disabled. You can enable it by passing {{ic|terminate:ctrl_alt_bksp}} to {{ic|XkbOptions}}.<br />
<br />
=== Swapping Caps Lock with Left Control ===<br />
<br />
To swap Caps Lock with Left Control key, add {{ic|ctrl:swapcaps}} to {{ic|XkbOptions}}. Run the following command to see similar options along with their descriptions:<br />
<br />
$ grep -E "(ctrl|caps):" /usr/share/X11/xkb/rules/base.lst<br />
<br />
=== Enabling mouse keys ===<br />
<br />
[[Wikipedia:Mouse keys|Mouse keys]] is now disabled by default and has to be manually enabled by passing {{ic|keypad:pointerkeys}} to {{ic|XkbOptions}}. This will make the {{ic|Shift+NumLock}} shortcut toggle mouse keys.<br />
<br />
=== Configuring compose key ===<br />
<br />
Though typically not on traditional keyboards, a [[Wikipedia:Compose key|Compose key]] can be configured to an existent key.<br />
<br />
The {{ic|Compose}} key begins a keypress sequence that involves (usually two) additional keypresses. Usage is typically either for entering characters in a language that the keyboard was not designed for, or for other less-used characters that are not covered with the {{ic|AltGr}} modifier. For example, pressing {{ic|Compose}} {{ic|'}} {{ic|e}} produces {{ic|é}}, or {{ic|Compose}} {{ic|-}} {{ic|-}} will produce an "em dash": {{ic|—}}.<br />
<br />
Though a few more eccentric keyboards feature a {{ic|Compose}} key, its availability is usually through substituting an already existing key to it. For example, to make the {{ic|Menu}} key a {{ic|Compose}} key use the [[Desktop environment]] configuration, or pass {{ic|compose:menu}} to {{ic|XkbOptions}} (or [[#Using setxbkmap|setxkbmap]]: {{ic|setxkbmap -option compose:menu}}). Allowed key substitutions are defined in {{ic|/usr/share/X11/xkb/rules/base.lst}}:<br />
<br />
$ grep "compose:" /usr/share/X11/xkb/rules/base.lst<br />
<br />
==== Key combinations ====<br />
<br />
The default combinations for the compose keys depend on the locale and are stored in {{ic|/usr/share/X11/locale/''used_locale''/Compose}}, where {{ic|''used_locale''}} is for example {{ic|en_US.UTF-8}}. (Hence, it is important that the [[Locale#Generating_locales|locale is configured and generated correctly]], otherwise the compose key will not work properly.)<br />
<br />
You can define your own compose key combinations by copying the default file to {{ic|~/.XCompose}} and editing it. The compose key works with any of the thousands of valid Unicode characters, including those outside the Basic Multilingual Plane.<br />
<br />
However, GTK does not use [[Wikipedia:X Input Method|XIM]] by default and therefore does not follow {{ic|~/.XCompose}} keys. This can be fixed by forcing GTK to use XIM by adding {{ic|1=export GTK_IM_MODULE=xim}} and/or {{ic|1=export XMODIFIERS="@im=none"}} to {{ic|~/.xprofile}}.<br />
<br />
{{Tip|XIM is very old, you might have better luck with other input methods: [[Wikipedia:Smart Common Input Method|SCIM]], [[Wikipedia:Uim|uim]], [[Wikipedia:Intelligent Input Bus|IBus]] etc. See [[Internationalization#Input methods in Xorg]] for details.}}<br />
<br />
=== Currency sign on other key ===<br />
<br />
Most European keyboards have a Euro sign (€) printed on on the {{ic|5}} key. For example, to access it with {{ic|Alt+5}}, use the {{ic|lv3:lalt_switch}} and {{ic|eurosign:5}} options.<br />
<br />
The Rupee sign (₹) can be used the same way with {{ic|rupeesign:4}}.<br />
<br />
=== Switching state immediately when Caps Lock is pressed ===<br />
<br />
Those who prefer typing capital letters with Caps Lock key may experience a short delay when Caps Lock state is switched, resulting in two or more capital letters (e.g. ''THe'', ''ARch LInux''). This is a known issue related to input components in Xserver, which has been reported years ago but no official fix has been released yet. For anyone who would like to follow up the issue, bug reports and latest working progress can be found at [https://bugs.freedesktop.org/show_bug.cgi?id=27903] and [https://bugs.freedesktop.org/show_bug.cgi?id=56491].<br />
<br />
==== Workaround ====<br />
<br />
First, export your keyboard configurations to a file:<br />
<br />
$ xkbcomp -xkb $DISPLAY xkbmap<br />
<br />
In the file ''xkbmap'', locate the Caps Lock section which begins with ''key <CAPS>'':<br />
<br />
key <CAPS> { [ Caps_Lock ] };<br />
<br />
and replace whole section with the following code:<br />
<br />
key <CAPS> {<br />
repeat=no,<br />
type[group1]="ALPHABETIC",<br />
symbols[group1]=[ Caps_Lock, Caps_Lock],<br />
actions[group1]=[ LockMods(modifiers=Lock), Private(type=3,data[0]=1,data[1]=3,data[2]=3)]<br />
};<br />
<br />
Save and reload keyboard configurations:<br />
<br />
$ xkbcomp -w 0 xkbmap $DISPLAY<br />
<br />
Consider making it a service launching after X starts, since reloaded configurations do not survive a system reboot.<br />
<br />
== Other settings ==<br />
<br />
=== Adjusting typematic delay and rate ===<br />
<br />
The ''typematic delay'' indicates the amount of time (typically in miliseconds) a key needs to be pressed in order for the repeating process to begin. After the repeating process has been triggered, the character will be repeated with a certain frequency (usually given in Hz) specified by the ''typematic rate''. The typematic delay in the [[Keyboard_configuration_in_console#Adjusting_typematic_delay_and_rate|virtual console]] is not affected by these settings.<br />
<br />
==== Using xset ====<br />
<br />
The tool ''xset'' can be used to set the typematic delay and rate for an active X server, certain actions during runtime tho may cause the XServer to reset these changes and revert instead to its ''seat defaults''.<br />
<br />
Usage:<br />
<br />
$ xset r rate ''delay'' [''rate'']<br />
<br />
For example to set a typematic delay to 200ms and a typematic rate to 30Hz, use the following command (use [[xinitrc]] to make it permanent):<br />
<br />
$ xset r rate 200 30<br />
<br />
Issuing the command without specifying the delay and rate will reset the typematic values to their respective defaults; a delay of 660ms and a rate of 25Hz:<br />
<br />
$ xset r rate<br />
<br />
==== Using XServer startup options ====<br />
<br />
A more resistant way to set the typematic delay and rate is to make them the ''seat defaults'' by passing the desired settings to the X server on its startup using the following options:<br />
<br />
* {{ic|-ardelay ''miliseconds''}} - sets the autorepeat delay (length of time in milliseconds that a key must be depressed before autorepeat starts).<br />
* {{ic|-arinterval ''miliseconds''}} - sets the autorepeat interval (length of time in milliseconds that should elapse between autorepeat-generated keystrokes).<br />
<br />
See {{ic|man xserver}} for a full list of X server options and refer to your [[display manager]] for information about how to pass these options.<br />
<br />
==== Using XServer options ====<br />
<br />
Add this line to {{ic|/etc/X11/xorg.conf.d/00-keyboard.conf}}:<br />
<br />
Option "AutoRepeat" "''delay'' ''rate''"</div>Fylwindhttps://wiki.archlinux.org/index.php?title=OpenSSH&diff=369262OpenSSH2015-04-11T05:04:09Z<p>Fylwind: /* Recommendations */ spelling</p>
<hr />
<div>[[Category:Secure Shell]]<br />
[[ar:Ssh]]<br />
[[de:SSH]]<br />
[[es:Secure Shell]]<br />
[[fr:ssh]]<br />
[[it:Secure Shell]]<br />
[[ja:Secure Shell]]<br />
[[ko:Secure Shell]]<br />
[[pl:Secure Shell]]<br />
[[pt:Secure Shell]]<br />
[[ru:Secure Shell]]<br />
[[sr:Secure Shell]]<br />
[[zh-CN:Secure Shell]]<br />
{{Related articles start}}<br />
{{Related|SSH keys}}<br />
{{Related|Pam abl}}<br />
{{Related|fail2ban}}<br />
{{Related|sshguard}}<br />
{{Related|Sshfs}}<br />
{{Related|Syslog-ng}}<br />
{{Related|SFTP chroot}}<br />
{{Related articles end}}<br />
<br />
Secure Shell (SSH) is a network protocol that allows data to be exchanged over a secure channel between two computers. Encryption provides confidentiality and integrity of data. SSH uses public-key cryptography to authenticate the remote computer and allow the remote computer to authenticate the user, if necessary.<br />
<br />
SSH is typically used to log into a remote machine and execute commands, but it also supports tunneling, forwarding arbitrary TCP ports and X11 connections; file transfer can be accomplished using the associated SFTP or SCP protocols.<br />
<br />
An SSH server, by default, listens on the standard TCP port 22. An SSH client program is typically used for establishing connections to an ''sshd'' daemon accepting remote connections. Both are commonly present on most modern operating systems, including Mac OS X, GNU/Linux, Solaris and OpenVMS. Proprietary, freeware and open source versions of various levels of complexity and completeness exist.<br />
<br />
(Source: [[Wikipedia:Secure Shell]])<br />
<br />
== OpenSSH ==<br />
OpenSSH (OpenBSD Secure Shell) is a set of computer programs providing encrypted communication sessions over a computer network using the ssh protocol. It was created as an open source alternative to the proprietary Secure Shell software suite offered by SSH Communications Security. OpenSSH is developed as part of the OpenBSD project, which is led by Theo de Raadt.<br />
<br />
OpenSSH is occasionally confused with the similarly-named OpenSSL; however, the projects have different purposes and are developed by different teams, the similar name is drawn only from similar goals.<br />
<br />
=== Installing OpenSSH ===<br />
[[pacman|Install]] {{Pkg|openssh}} from the [[official repositories]].<br />
<br />
=== Configuring SSHD ===<br />
<br />
The SSH daemon configuration file can be found and edited in {{ic|/etc/ssh/ssh'''d'''_config}}.<br />
<br />
To allow access only for some users add this line:<br />
AllowUsers user1 user2<br />
<br />
To allow access only for some groups:<br />
AllowGroups group1 group2<br />
<br />
To disable root login over SSH, change the PermitRootLogin line into this:<br />
PermitRootLogin no<br />
<br />
To add a nice welcome message edit the file {{ic|/etc/issue}} and change the Banner line into this:<br />
Banner /etc/issue<br />
<br />
If the server is to be exposed to the WAN, it is recommended to change the default port from 22 to a higher one like this:<br />
Port 39901<br />
<br />
For a discussion, see [[wikipedia:Security_through_obscurity|security through obscurity]]. Even though the port ssh is running on could be detected by using a port-scanner like {{Pkg|nmap}}, changing it will reduce the number of log entries caused by automated authentication attempts. To help select a port review the [[Wikipedia:List of TCP and UDP port numbers|list of TCP and UDP port numbers]]. You can also find port information locally in {{ic|/etc/services}}. Select an alternative port that is '''not''' already assigned to a common service to prevent conflicts.<br />
<br />
{{Note|OpenSSH can also listen on multiple ports simply by having multiple '''Port x''' lines in the config file.}}<br />
<br />
It is also recommended to disable password logins entirely. This will greatly increase security, see [[SSH keys#Disabling password logins]] for more information.<br />
<br />
=== Managing the sshd daemon ===<br />
The SSH daemon comes with different systemd unit files. <br />
<br />
You can start the daemon for immediate usage and/or enable it for next startup as described in [[systemd#Using units]]: <br />
# systemctl start sshd.service<br />
# systemctl enable sshd.service<br />
<br />
{{Warning|Systemd is an asynchronous starting process. If you bind the SSH daemon to a specific IP address {{ic|ListenAddress 192.168.1.100}} it may fail to load during boot since the default sshd.service unit file has no dependency on network interfaces being enabled. When binding to an IP address, you will need to add {{ic|1=After=network.target}} to a custom sshd.service unit file. See [[Systemd#Editing provided unit files]].}}<br />
<br />
Alternatively to the service used above, the SSH daemon supports socket activation. Using it implies that ''systemd'' listens on the SSH socket and will only start the daemon process for an incoming connection: <br />
# systemctl start sshd.socket<br />
# systemctl enable sshd.socket <br />
<br />
You will need to [[systemd#Editing provided unit files|edit]] the unit file if you want it to listen on a port other than the default 22:<br />
<br />
{{hc|# systemctl edit sshd.socket|<nowiki><br />
[Socket]<br />
ListenStream=<br />
ListenStream=12345<br />
</nowiki>}}<br />
<br />
{{Warning|Using {{ic|sshd.socket}} negates the {{ic|ListenAddress}} setting, so it will allow connections over any address. To achieve the effect of setting {{ic|ListenAddress}}, you must specify the port ''and'' IP for {{ic|ListenStream}} (e.g. {{ic|1=ListenStream=192.168.1.100:22}}). You must also add {{ic|1=FreeBind=true}} under {{ic|[Socket]}} or else setting the IP address will have the same drawback as setting {{ic|ListenAddress}}: the socket will fail to start if the network is not up in time.}}<br />
<br />
{{Tip|When using socket activation neither {{ic|sshd.socket}} nor the daemon's regular {{ic|sshd.service}} allow to monitor connection attempts in the log, but executing {{ic|# journalctl /usr/bin/sshd}} does.}}<br />
<br />
=== Connecting to the server ===<br />
To connect to a server, run:<br />
$ ssh -p port user@server-address<br />
<br />
=== Protecting SSH ===<br />
Allowing remote log-on through SSH is good for administrative purposes, but can pose a threat to your server's security. Often the target of brute force attacks, SSH access needs to be limited properly to prevent third parties gaining access to your server.<br />
* Use non-standard account names and passwords<br />
* Only allow incoming SSH connections from trusted locations<br />
* Use [[fail2ban]] or [[sshguard]] to monitor for brute force attacks, and ban brute forcing IPs accordingly<br />
<br />
==== Protecting against brute force attacks ====<br />
Brute forcing is a simple concept: One continuously tries to log in to a webpage or server log-in prompt like SSH with a high number of random username and password combinations. You can protect yourself from brute force attacks by using an automated script that blocks anybody trying to brute force their way in, for example [[fail2ban]] or [[sshguard]].<br />
<br />
Alternatively, brute force attacks can be made infeasible by forcing public key authentication, by adding the following setting to {{ic|sshd_config}}:<br />
<br />
PasswordAuthentication no<br />
<br />
Before effecting this setting, make sure that all accounts which require SSH access have public key authentication set up in the corresponding {{ic|authorized_keys}} files.<br />
<br />
==== Limit root login ====<br />
It is generally considered bad practice to allow the root user to log in without restraint over SSH. There are two methods by which SSH root access can be restricted for increased security.<br />
<br />
===== Deny =====<br />
<br />
Sudo selectively provides root rights for actions requiring these without requiring authenticating against the root account. This allows locking the root account against access via SSH and potentially functions as a security measure agaist brute force attacks, since now an attacker must guess the account name in additition to the password.<br />
<br />
SSH can be configured to deny remote logins with the root user by editing the "Authentication" section in {{ic|/etc/ssh/sshd_config}}. Simply change {{ic|#PermitRootLogin yes}} to {{ic|no}} and uncomment the line:<br />
<br />
{{hc|/etc/ssh/sshd_config|<br />
PermitRootLogin no<br />
...<br />
}}<br />
<br />
Next, restart the SSH daemon:<br />
# systemctl restart sshd<br />
<br />
You will now be unable to log in through SSH under root, but will still be able to log in with your normal user and use [[su]] or [[sudo]] to do system administration.<br />
<br />
===== Restrict =====<br />
<br />
Some automated tasks such as remote, full-system backup require full root access. To allow these in a secure way, instead of disabling root login via SSH, it is possible to only allow root logins for selected commands. This can be achieved by editing {{ic|~root/.ssh/authorized_keys}}, by prefixing the desired key, e.g. as follows:<br />
<br />
command="/usr/lib/rsync/rrsync -ro /" ssh-rsa …<br />
<br />
This will allow any login with this specific key only to execute the command specified between the quotes.<br />
<br />
The increased attack surface created by exposing the root user name at login can be compensated by adding the following to {{ic|sshd_config}}:<br />
<br />
PermitRootLogin forced-commands-only<br />
<br />
This setting will not only restrict the commands which root may execute via SSH, but it will also disable the use of passwords, forcing use of public key authentication for the root account.<br />
<br />
A slightly less restrictive alternative will allow any command for root, but makes brute force attacks infeasible by enforcing public key authentication. For this option, set:<br />
<br />
PermitRootLogin without-password<br />
<br />
== Other SSH clients and servers ==<br />
Apart from OpenSSH, there are many SSH [[Wikipedia:Comparison of SSH clients|clients]] and [[Wikipedia:Comparison of SSH servers|servers]] avaliable.<br />
<br />
=== Dropbear ===<br />
[[Wikipedia:Dropbear (software)|Dropbear]] is a SSH-2 client and server. {{Pkg|dropbear}} is available in the [[official repositories]].<br />
<br />
The commandline ssh client is named dbclient.<br />
<br />
=== SSH alternative: Mobile Shell - responsive, survives disconnects ===<br />
From the Mosh [http://mosh.mit.edu/ website]:<br />
<br />
Remote terminal application that allows roaming, supports intermittent connectivity, and provides intelligent local echo and line editing of user keystrokes. Mosh is a replacement for SSH. It is more robust and responsive, especially over Wi-Fi, cellular, and long-distance links.<br />
<br />
[[pacman|Install]] {{Pkg|mosh}} from the [[official repositories]] or the latest revision {{AUR|mosh-git}} in the [[AUR]].<br />
<br />
== Tips and tricks ==<br />
<br />
=== Encrypted SOCKS tunnel ===<br />
This is highly useful for laptop users connected to various unsafe wireless connections. The only thing you need is an SSH server running at a somewhat secure location, like your home or at work. It might be useful to use a dynamic DNS service like [http://www.dyndns.org/ DynDNS] so you do not have to remember your IP-address.<br />
<br />
==== Step 1: start the connection ====<br />
<br />
You only have to execute this single command to start the connection:<br />
<br />
$ ssh -TND 4711 ''user''@''host''<br />
<br />
where {{Ic|''user''}} is your username at the SSH server running at the {{Ic|''host''}}. It will ask for your password, and then you are connected! The {{Ic|N}} flag disables the interactive prompt, and the {{Ic|D}} flag specifies the local port on which to listen on (you can choose any port number if you want). The {{Ic|T}} flag disables pseudo-tty allocation.<br />
<br />
It is nice to add the verbose ({{Ic|-v}}) flag, because then you can verify that it is actually connected from that output.<br />
<br />
==== Step 2: configure your browser (or other programs) ====<br />
<br />
The above step is completely useless if you do not configure your web browser (or other programs) to use this newly created socks tunnel. Since the current version of SSH supports both SOCKS4 and SOCKS5, you can use either of them.<br />
<br />
* For Firefox: ''Edit > Preferences > Advanced > Network > Connection > Setting'': <br> Check the ''Manual proxy configuration'' radio button, and enter {{ic|localhost}} in the ''SOCKS host'' text field, and then enter your port number in the next text field ({{ic|4711}} in the example above).<br />
<br />
Firefox does not automatically make DNS requests through the socks tunnel. This potential privacy concern can be mitigated by the following steps:<br />
<br />
# Type about:config into the Firefox location bar.<br />
# Search for network.proxy.socks_remote_dns<br />
# Set the value to true.<br />
# Restart the browser.<br />
<br />
* For Chromium: You can set the SOCKS settings as environment variables or as command line options. I recommend to add one of the following functions to your {{ic|.bashrc}}:<br />
function secure_chromium {<br />
port=4711<br />
export SOCKS_SERVER=localhost:$port<br />
export SOCKS_VERSION=5<br />
chromium &<br />
exit<br />
}<br />
OR<br />
function secure_chromium {<br />
port=4711<br />
chromium --proxy-server="socks://localhost:$port" &<br />
exit<br />
}<br />
<br />
Now open a terminal and just do:<br />
$ secure_chromium<br />
<br />
Enjoy your secure tunnel!<br />
<br />
=== X11 forwarding ===<br />
X11 forwarding is a mechanism that allows graphical interfaces of X11 programs running on a remote system to be displayed on a local client machine. For X11 forwarding the remote host doesn't need to have a full X11 system installed, however it needs at least to have ''xauth'' installed. ''xauth'' is a utility that maintains {{ic|Xauthority}} configurations used by server and client for authentication of X11 session ([http://xmodulo.com/2012/11/how-to-enable-x11-forwarding-using-ssh.html source]).<br />
<br />
{{Warning|X11 forwarding has important security implications which should be at least acknowledged by reading relevant sections of {{ic|ssh}}, {{ic|sshd_config}} and {{ic|ssh_config}} manual pages. See also [https://security.stackexchange.com/questions/14815/security-concerns-with-x11-forwarding a short writeup]}}<br />
<br />
==== Setup ====<br />
<br />
On the remote system:<br />
<br />
*[[pacman#Installing specific packages|install]] {{Pkg|xorg-xauth}} and {{Pkg|xorg-xhost}} from the [[official repositories]]<br />
*in {{ic|/etc/ssh/ssh'''d'''_config}}:<br />
**verify that {{ic|AllowTcpForwarding}} and {{ic|X11UseLocalhost}} options are set to ''yes'', and that {{ic|X11DisplayOffset}} is set to ''10'' (those are the default values if nothing has been changed, see {{ic|man sshd_config}})<br />
**set {{ic|X11Forwarding}} to ''yes''<br />
* then [[Systemd#Using units|restart]] the [[#Managing the sshd daemon|''sshd'' daemon]]. <br />
* The X server must also be running on the remote system.<br />
<br />
On the client's side, enable the {{ic|ForwardX11}} option by either specifying the {{ic|-X}} switch on the command line for opportunistic connections, or by setting {{ic|ForwardX11}} to ''yes'' in [[#Client|openSSH client's configuration file]].<br />
<br />
{{Tip|You can enable the {{ic|ForwardX11Trusted}} option ({{ic|-Y}} switch on the command line) if GUI is drawing badly or you receive errors; this will prevent X11 forwardings from being subjected to the [http://www.x.org/wiki/Development/Documentation/Security/ X11 SECURITY extension] controls. Be sure you have read [[#X11 forwarding|the warning]] at the beginning of this section if you do so.}}<br />
<br />
==== Usage ====<br />
<br />
[[#Connecting to the server|Log on to the remote machine]] normally, specifying the {{ic|-X}} switch if ''ForwardX11'' wasn't enabled in the client's configuration file:<br />
$ ssh -X ''user@host''<br />
If you receive errors trying to run graphical applications, try ''ForwardX11Trusted'' instead:<br />
$ ssh -Y ''user@host''<br />
You can now start any X program on the remote server, the output will be forwarded to your local session:<br />
$ xclock<br />
<br />
If you get "Cannot open display" errors try the following command as the non root user:<br />
$ xhost +<br />
<br />
The above command will allow anybody to forward X11 applications. To restrict forwarding to a particular host type:<br />
$ xhost +hostname<br />
<br />
where hostname is the name of the particular host you want to forward to. See {{ic|man xhost}} for more details.<br />
<br />
Be careful with some applications as they check for a running instance on the local machine. [[Firefox]] is an example: either close the running Firefox instance or use the following start parameter to start a remote instance on the local machine:<br />
$ firefox -no-remote<br />
<br />
If you get "X11 forwarding request failed on channel 0" when you connect (and the server {{ic|/var/log/errors.log}} shows "Failed to allocate internet-domain X11 display socket"), make sure package {{Pkg|xorg-xauth}} is installed. If its installation is not working, try to either:<br />
<br />
* enable the {{ic|AddressFamily any}} option in {{ic|ssh'''d'''_config}} on the ''server'', or<br />
* set the {{ic|AddressFamily}} option in {{ic|ssh'''d'''_config}} on the ''server'' to inet.<br />
Setting it to inet may fix problems with Ubuntu clients on IPv4.<br />
<br />
For running X applications as other user on the SSH server you need to {{Ic|xauth add}} the authentication line taken from {{Ic|xauth list}} of the SSH logged in user.<br />
<br />
=== Forwarding other ports ===<br />
In addition to SSH's built-in support for X11, it can also be used to securely tunnel any TCP connection, by use of local forwarding or remote forwarding.<br />
<br />
Local forwarding opens a port on the local machine, connections to which will be forwarded to the remote host and from there on to a given destination. Very often, the forwarding destination will be the same as the remote host, thus providing a secure shell and, e.g. a secure VNC connection, to the same machine. Local forwarding is accomplished by means of the {{Ic|-L}} switch and it is accompanying forwarding specification in the form of {{Ic|<tunnel port>:<destination address>:<destination port>}}.<br />
<br />
Thus:<br />
<br />
$ ssh -L 1000:mail.google.com:25 192.168.0.100<br />
<br />
will use SSH to login to and open a shell on 192.168.0.100, and will also create a tunnel from the local machine's TCP port 1000 to mail.google.com on port 25. Once established, connections to localhost:1000 will connect to the Gmail SMTP port. To Google, it will appear that any such connection (though not necessarily the data conveyed over the connection) originated from 192.168.0.100, and such data will be secure as between the local machine and 192.168.0.100, but not between 192.168.0.100, unless other measures are taken.<br />
<br />
Similarly:<br />
<br />
$ ssh -L 2000:192.168.0.100:6001 192.168.0.100<br />
<br />
will allow connections to localhost:2000 which will be transparently sent to the remote host on port 6001. The preceding example is useful for VNC connections using the vncserver utility--part of the tightvnc package--which, though very useful, is explicit about its lack of security.<br />
<br />
Remote forwarding allows the remote host to connect to an arbitrary host via the SSH tunnel and the local machine, providing a functional reversal of local forwarding, and is useful for situations where, e.g., the remote host has limited connectivity due to firewalling. It is enabled with the {{Ic|-R}} switch and a forwarding specification in the form of {{Ic|<tunnel port>:<destination address>:<destination port>}}.<br />
<br />
Thus:<br />
<br />
$ ssh -R 3000:irc.freenode.net:6667 192.168.0.200<br />
<br />
will bring up a shell on 192.168.0.200, and connections from 192.168.0.200 to itself on port 3000 (remotely speaking, localhost:3000) will be sent over the tunnel to the local machine and then on to irc.freenode.net on port 6667, thus, in this example, allowing the use of IRC programs on the remote host to be used, even if port 6667 would normally be blocked to it.<br />
<br />
Both local and remote forwarding can be used to provide a secure "gateway," allowing other computers to take advantage of an SSH tunnel, without actually running SSH or the SSH daemon by providing a bind-address for the start of the tunnel as part of the forwarding specification, e.g. {{Ic|<tunnel address>:<tunnel port>:<destination address>:<destination port>}}. The {{Ic|<tunnel address>}} can be any address on the machine at the start of the tunnel, {{Ic|localhost}}, {{Ic|*}} (or blank), which, respectively, allow connections via the given address, via the loopback interface, or via any interface. By default, forwarding is limited to connections from the machine at the "beginning" of the tunnel, i.e. the {{Ic|<tunnel address>}} is set to {{Ic|localhost}}. Local forwarding requires no additional configuration, however remote forwarding is limited by the remote server's SSH daemon configuration. See the {{Ic|GatewayPorts}} option in {{Ic|sshd_config(5)}} for more information.<br />
<br />
=== Multiplexing ===<br />
<br />
The SSH daemon usually listens on port 22. However, it is common practice for many public internet hotspots to block all traffic that is not on the regular HTTP/S ports (80 and 443, respectively), thus effectively blocking SSH connections. The immediate solution for this is to have {{ic|sshd}} listen additionally on one of the whitelisted ports:<br />
<br />
{{hc|/etc/ssh/sshd_config|<br />
Port 22<br />
Port 443<br />
}}<br />
<br />
However, it is likely that port 443 is already in use by a web server serving HTTPS content, in which case it is possible to use a multiplexer, such as {{Pkg|sslh}}, which listens on the multiplexed port and can intelligently forward packets to many services.<br />
<br />
=== Speeding up SSH ===<br />
<br />
You can make all sessions to the same host use a single connection, which will greatly speed up subsequent logins, by adding these lines under the proper host in {{ic|/etc/ssh/ssh_config}}:<br />
Host examplehost.com<br />
ControlMaster auto<br />
ControlPersist yes<br />
ControlPath ~/.ssh/socket-%r@%h:%p<br />
<br />
See the {{ic|ssh_config(5)}} manual page for full description of these options.<br />
<br />
Another option to improve speed is to enable compression with the {{ic|-C}} flag. A permanent solution is to add this line under the proper host in {{ic|/etc/ssh/ssh_config}}:<br />
Compression yes<br />
{{Warning|{{ic|man ssh}} states that "''Compression is desirable on modem lines and other slow connections, but will only slow down things on fast networks''". This tip might be counterproductive depending on your network configuration.}}<br />
<br />
Login time can be shortened by using the {{ic|-4}} flag, which bypasses IPv6 lookup. This can be made permanent by adding this line under the proper host in {{ic|/etc/ssh/ssh_config}}:<br />
AddressFamily inet<br />
<br />
Changing the ciphers used by SSH to less cpu-demanding ones can improve speed. In this respect, the best choices are arcfour and blowfish-cbc.<br />
<br />
{{Warning|Please do not do this unless you know what you are doing; arcfour has a number of known weaknesses.}}<br />
<br />
To use alternative ciphers, run SSH with the {{ic|-c}} flag:<br />
$ ssh -c arcfour,blowfish-cbc user@server-address<br />
<br />
To use them permanently, add this line under the proper host in {{ic|/etc/ssh/ssh_config}}:<br />
Ciphers arcfour,blowfish-cbc<br />
<br />
=== Mounting a remote filesystem with SSHFS ===<br />
Please refer to the [[Sshfs]] article to use sshfs to mount a remote system - accessible via SSH - to a local folder, so you will be able to do any operation on the mounted files with any tool (copy, rename, edit with vim, etc.). Using sshfs instead of shfs is generally preferred as a new version of shfs has not been released since 2004.<br />
<br />
=== Keep alive ===<br />
Your ssh session will automatically log out if it is idle. To keep the connection active (alive) add this to {{ic|~/.ssh/config}} or to {{ic|/etc/ssh/ssh_config}} on the client.<br />
<br />
ServerAliveInterval 120<br />
<br />
This will send a "keep alive" signal to the server every 120 seconds.<br />
<br />
Conversely, to keep incoming connections alive, you can set<br />
<br />
ClientAliveInterval 120<br />
<br />
(or some other number greater than 0) in {{ic|/etc/ssh/sshd_config}} on the server.<br />
<br />
=== Saving connection data in ssh config ===<br />
Whenever you want to connect to a ssh server, you usually have to type at least its address and the username. To save that typing work for servers you regularly connect to, you can use the personal {{ic|~/.ssh/config}} or the global {{ic|/etc/ssh/ssh_config}} files as shown in the following example:<br />
<br />
{{hc|~/.ssh/config|<br />
Host myserver<br />
HostName 123.123.123.123<br />
Port 12345<br />
User bob<br />
Host other_server<br />
HostName test.something.org<br />
User alice<br />
CheckHostIP no<br />
Cipher blowfish<br />
}}<br />
<br />
Now you can simply connect to the server by using the name you specified:<br />
<br />
$ ssh myserver<br />
<br />
To see a complete list of the possible options, check out ssh_config's manpage on your system or the [http://www.openbsd.org/cgi-bin/man.cgi?query=ssh_config ssh_config documentation] on the official website.<br />
<br />
=== Automatically restart SSH tunnels with systemd ===<br />
<br />
[[systemd]] can automatically start SSH connections on boot/login ''and'' restart them when they fail. This makes it a useful tool for maintaining SSH tunnels.<br />
<br />
The following service can start an SSH tunnel on login using the connection settings in your [[#Saving connection data in ssh config|ssh config]]. If the connection closes for any reason, it waits 10 seconds before restarting it:<br />
<br />
{{hc|~/.config/systemd/user/tunnel.service|<nowiki><br />
[Unit]<br />
Description=SSH tunnel to myserver<br />
<br />
[Service]<br />
Type=simple<br />
Restart=always<br />
RestartSec=10<br />
ExecStart=/usr/bin/ssh -F %h/.ssh/config -N myserver<br />
</nowiki>}}<br />
<br />
Then [[enable]] and [[start]] the user service. See [[#Keep alive]] for how to prevent the tunnel from timing out. If you wish to start the tunnel on boot, you will need to rewrite the unit as a system service.<br />
<br />
=== Autossh - automatically restarts SSH sessions and tunnels ===<br />
When a session or tunnel cannot be kept alive, for example due to bad network conditions causing client disconnections, you can use [http://www.harding.motd.ca/autossh/ Autossh] to automatically restart them. Autossh can be installed from the [[official repositories]]. <br />
<br />
Usage examples:<br />
$ autossh -M 0 -o "ServerAliveInterval 45" -o "ServerAliveCountMax 2" username@example.com<br />
Combined with [[ sshfs ]]:<br />
$ sshfs -o reconnect,compression=yes,transform_symlinks,ServerAliveInterval=45,ServerAliveCountMax=2,ssh_command='autossh -M 0' username@example.com: /mnt/example <br />
Connecting through a SOCKS-proxy set by [[ Proxy_settings ]]:<br />
$ autossh -M 0 -o "ServerAliveInterval 45" -o "ServerAliveCountMax 2" -NCD 8080 username@example.com <br />
With the {{ic|-f}} option autossh can be made to run as a background process. Running it this way however means the passphrase cannot be entered interactively.<br />
<br />
The session will end once you type {{ic|exit}} in the session, or the autossh process receives a SIGTERM, SIGINT of SIGKILL signal.<br />
<br />
==== Run Autossh automatically at boot via systemd ====<br />
If you want to automatically start autossh, it is now easy to get systemd to manage this for you. For example, you could create a systemd unit file like this:<br />
<br />
[Unit]<br />
Description=AutoSSH service for port 2222<br />
After=network.target<br />
<br />
[Service]<br />
Environment="AUTOSSH_GATETIME=0"<br />
ExecStart=/usr/bin/autossh -M 0 -NL 2222:localhost:2222 -o TCPKeepAlive=yes foo@bar.com<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
<br />
Here {{ic|1=AUTOSSH_GATETIME=0}} is an environment variable specifying how long ssh must be up before autossh considers it a successful connection, setting it to 0 autossh also ignores the first run failure of ssh. This may be useful when running autossh at boot. Other environment variables are available on the manpage. Of course, you can make this unit more complex if necessary (see the systemd documentation for details), and obviously you can use your own options for autossh, but note that the {{ic|-f}} implying {{ic|1=AUTOSSH_GATETIME=0}} does not work with systemd. <br />
<br />
Then place this in, for example, /etc/systemd/system/autossh.service. Afterwards, you can then enable your autossh tunnels with, e.g.:<br />
<br />
$ systemctl start autossh<br />
(or whatever you called the service file)<br />
<br />
If this works OK for you, you can make this permanent by running<br />
<br />
$ systemctl enable autossh<br />
<br />
That way autossh will start automatically at boot.<br />
<br />
It is also easy to maintain several autossh processes, to keep several tunnels alive. Just create multiple .service files with different names.<br />
<br />
== Changing SSH port number with socket activation (sshd.socket) ==<br />
<br />
Create the file {{ic|/etc/systemd/system/sshd.socket.d/port.conf}} with:<br />
<br />
[Socket]<br />
# Disable default port<br />
ListenStream=<br />
# Set new port<br />
ListenStream=12345<br />
<br />
systemd will automatically listen on the new port after a reload:<br />
<br />
systemctl daemon-reload<br />
<br />
== Troubleshooting ==<br />
<br />
=== Checklist ===<br />
<br />
This is a first-steps troubleshooting checklist. It is recommended to check these issues before you look any further:<br />
<br />
1. The client and server {{ic|~/.ssh}} folder and its content should be accessible by its user:<br />
<br />
$ chmod 700 /home/USER/.ssh<br />
$ chmod 600 /home/USER/.ssh/*<br />
<br />
2. Check that all files within client's and server's {{ic|~/.ssh}} folder are owned by its user:<br />
<br />
$ chown -R USER: ~/.ssh<br />
<br />
3. Check that the client's public e.g. {{ic|id_rsa.pub}} key row is in the server's {{ic|authorized_keys}} file.<br />
<br />
4. Check you did not limit SSH access via {{ic|AllowUsers}} in {{ic|/etc/ssh/sshd_config}} (space separated).<br />
<br />
==== Cleanup outdated keys (optional) ====<br />
<br />
5. Delete old/invalid key rows in server's {{ic|~/.ssh/authorized_keys}} file.<br />
<br />
6. Delete old/invalid private and public keys within the clients {{ic|~/.ssh}} folder.<br />
<br />
==== Recommendations ====<br />
<br />
7. Keep as few keys as possible in user's {{ic|~/.ssh/authorized_keys}} file on the server.<br />
<br />
=== SSH connection left hanging after poweroff/reboot ===<br />
<br />
SSH connection hangs after poweroff or reboot if systemd stop network before sshd. To fix that problem, comment and change the {{ic|After}} statement:<br />
{{hc|/usr/lib/systemd/system/systemd-user-sessions.service|2=<br />
#After=remote-fs.target<br />
After=network.target}}<br />
<br />
=== Connection refused or timeout problem ===<br />
<br />
==== Is your router doing port forwarding? ====<br />
<br />
SKIP THIS STEP IF YOU ARE NOT BEHIND A NAT MODEM/ROUTER (eg, a VPS or otherwise publicly addressed host). Most home and small businesses will have a NAT modem/router.<br />
<br />
The first thing is to make sure that your router knows to forward any incoming ssh connection to your machine. Your external IP is given to you by your ISP, and it is associated with any requests coming out of your router. So your router needs to know that any incoming ssh connection to your external IP needs to be forwarded to your machine running sshd.<br />
<br />
Find your internal network address.<br />
<br />
ip a<br />
<br />
Find your interface device and look for the inet field. Then access your router's configuration web interface, using your router's IP (find this on the web). Tell your router to forward it to your inet IP. Go to [http://portforward.com/] for more instructions on how to do so for your particular router.<br />
<br />
==== Is SSH running and listening? ====<br />
$ ss -tnlp<br />
<br />
If the above command do not show SSH port is open, SSH is NOT running. Check {{ic|/var/log/messages}} for errors etc.<br />
<br />
==== Are there firewall rules blocking the connection? ====<br />
<br />
[[Iptables]] may be blocking connections on port {{ic|22}}. Check this with:<br />
{{bc|# iptables -nvL}}<br />
and look for rules that might be dropping packets on the {{ic|INPUT}} chain. Then, if necessary, unblock the port with a command like: <br />
{{bc|<br />
# iptables -I INPUT 1 -p tcp --dport 22 -j ACCEPT<br />
}}<br />
For more help configuring firewalls, see [[firewalls]].<br />
<br />
==== Is the traffic even getting to your computer? ====<br />
Start a traffic dump on the computer you are having problems with:<br />
<br />
# tcpdump -lnn -i any port ssh and tcp-syn<br />
<br />
This should show some basic information, then wait for any matching traffic to happen before displaying it. Try your connection now. If you do not see any output when you attempt to connect, then something outside of your computer is blocking the traffic (e. g., hardware firewall, NAT router etc.).<br />
<br />
==== Your ISP or a third party blocking default port? ====<br />
{{Note|Try this step if you '''know''' you are not running any firewalls and you know you have configured the router for DMZ or have forwarded the port to your computer and it still does not work. Here you will find diagnostic steps and a possible solution.}}<br />
<br />
In some cases, your ISP might block the default port (SSH port 22) so whatever you try (opening ports, hardening the stack, defending against flood attacks, et al) ends up useless. To confirm this, create a server on all interfaces (0.0.0.0) and connect remotely. <br />
<br />
If you get an error message comparable to this:<br />
ssh: connect to host www.inet.hr port 22: Connection refused<br />
<br />
That means the port is '''not''' being blocked by the ISP, but the server does not run SSH on that port (See [[wikipedia:Security_through_obscurity|security through obscurity]]).<br />
<br />
However, if you get an error message comparable to this:<br />
ssh: connect to host 111.222.333.444 port 22: Operation timed out <br />
<br />
That means that something is rejecting your TCP traffic on port 22. Basically that port is stealth, either by your firewall or 3rd party intervention (like an ISP blocking and/or rejecting incoming traffic on port 22). If you know you are not running any firewall on your computer, and you know that Gremlins are not growing in your routers and switches, then your ISP is blocking the traffic.<br />
<br />
To double check, you can run Wireshark on your server and listen to traffic on port 22. Since Wireshark is a Layer 2 Packet Sniffing utility, and TCP/UDP are Layer 3 and above (see [[wikipedia:Internet protocol suite|IP Network stack]]), if you do not receive anything while connecting remotely, a third party is most likely to be blocking the traffic on that port to your server.<br />
<br />
===== Diagnosis via Wireshark =====<br />
[[pacman|Install]] Wireshark with the {{Pkg|wireshark-cli}} package, available in the [[official repositories]].<br />
<br />
And then run it using,<br />
tshark -f "tcp port 22" -i NET_IF<br />
<br />
where NET_IF is the network interface for a WAN connection (see {{ic|ip a}} to check). If you are not receiving any packets while trying to connect remotely, you can be very sure that your ISP is blocking the incoming traffic on port 22.<br />
<br />
===== Possible solution =====<br />
The solution is just to use some other port that the ISP is not blocking. Open the {{ic|/etc/ssh/sshd_config}} and configure the file to use different ports. For example, add:<br />
<br />
Port 22<br />
Port 1234<br />
<br />
Also make sure that other "Port" configuration lines in the file are commented out. Just commenting "Port 22" and putting "Port 1234" will not solve the issue because then sshd will only listen on port 1234. Use both lines to run the SSH server on both ports. <br />
<br />
Restart the server {{ic|systemctl restart sshd.service}} and you are almost done. You still have to configure your client(s) to use the other port instead of the default port. There are numerous solutions to that problem, but let us cover two of them here.<br />
<br />
==== Read from socket failed: connection reset by peer ====<br />
Recent versions of openssh sometimes fail with the above error message, due to a bug involving elliptic curve cryptography. In that case add the following line to {{ic|~/.ssh/config}}:<br />
<br />
HostKeyAlgorithms ssh-rsa-cert-v01@openssh.com,ssh-dss-cert-v01@openssh.com,ssh-rsa-cert-v00@openssh.com,ssh-dss-cert-v00@openssh.com,ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,ssh-rsa,ssh-dss<br />
<br />
With openssh 5.9, the above fix does not work. Instead, put the following lines in {{ic|~/.ssh/config}}:<br />
<br />
Ciphers aes128-ctr,aes192-ctr,aes256-ctr,aes128-cbc,3des-cbc <br />
MACs hmac-md5,hmac-sha1,hmac-ripemd160<br />
<br />
See also the [http://www.gossamer-threads.com/lists/openssh/dev/51339 discussion] on the openssh bug forum.<br />
<br />
=== "[your shell]: No such file or directory" / ssh_exchange_identification problem ===<br />
One possible cause for this is the need of certain SSH clients to find an absolute path (one returned by {{Ic|whereis -b [your shell]}}, for instance) in {{Ic|$SHELL}}, even if the shell's binary is located in one of the {{Ic|$PATH}} entries.<br />
<br />
==="Terminal unknown" or "Error opening terminal" error message===<br />
With ssh it is possible to receive errors like "Terminal unknown" upon logging in. Starting ncurses applications like nano fails with the message "Error opening terminal". There are two methods to this problem, a quick one using the $TERM variable and a profound one using the terminfo file.<br />
<br />
====Workaround by setting the $TERM variable====<br />
After connecting to the remote server set the $TERM variable to "xterm" with the following command.<br />
<br />
{{ic|TERM&#61;xterm}}<br />
<br />
This method is a workaround and should be used on ssh servers you do seldomly connect to, because it can have unwanted side effects. Also you have to repeat the command after every connection, or alternatively set it in ~.bashrc .<br />
====Solution using terminfo file====<br />
A profound solution is transferring the terminfo file of the terminal on your client computer to the ssh server. In this example we cover how to setup the terminfo file for the "rxvt-unicode-256color" terminal.<br />
Create the directory containing the terminfo files on the ssh server, while you are logged in to the server issue this command:<br />
<br />
{{ic| mkdir -p ~/.terminfo/r/}}<br />
<br />
Now copy the terminfo file of your terminal to the new directory. Replace {{ic|rxvt-unicode-256color}} with your client's terminal in the following command and {{ic|ssh-server}} with the relevant user and server adress.<br />
<br />
{{ic|$ scp /usr/share/terminfo/r/''rxvt-unicode-256color'' ssh-server:~/.terminfo/r/}}<br />
<br />
After logging in and out from the ssh server the problem should be fixed.<br />
<br />
== See also ==<br />
<br />
* [http://www.soloport.com/iptables.html A Cure for the Common SSH Login Attack]<br />
* [http://www.la-samhna.de/library/brutessh.html Defending against brute force ssh attacks]<br />
* [http://www.ibm.com/developerworks/library/l-keyc/index.html OpenSSH key management, Part 1] and [http://www.ibm.com/developerworks/library/l-keyc2 Part 2] on IBM developerWorks<br />
* [https://stribika.github.io/2015/01/04/secure-secure-shell.html Secure Secure Shell]</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Power_management&diff=369171Power management2015-04-10T04:50:08Z<p>Fylwind: /* ACPI events */ alternative location for logind.conf; warn about restarting systemd-logind</p>
<hr />
<div>[[Category:Power management]]<br />
[[es:Power Management]]<br />
[[ja:電源管理]]<br />
[[zh-CN:Power Management]]<br />
{{Related articles start}}<br />
{{Related|Power saving}}<br />
{{Related|Display Power Management Signaling}}<br />
{{Related|Suspend and hibernate}}<br />
{{Related articles end}}<br />
<br />
The purpose of this page is to provide general overview of power management in Arch Linux. As Arch Linux uses [[systemd]] as system manager, this article focuses on it.<br />
<br />
There are multiple places where one can change power management settings:<br />
* [[Kernel parameters]]<br />
* [[Kernel modules]]<br />
* [[udev]] rules<br />
<br />
There are also many power management tools:<br />
* [[systemd]]<br />
* [[pm-utils]]<br />
* [[Laptop Mode Tools]]<br />
* [[TLP]]<br />
* [[acpid]]<br />
<br />
{{Note|Power settings you set in one place/tool could be overwritten in another place/tool.}}<br />
<br />
== Power management with systemd ==<br />
<br />
=== ACPI events ===<br />
<br />
''systemd'' handles some power-related [[Wikipedia:Advanced_Configuration_and_Power_Interface|ACPI]] events. They can be configured via the following options from {{ic|/etc/systemd/logind.conf}} (or {{ic|/etc/systemd/logind.conf.d/*.conf}}):<br />
<br />
* {{ic|HandlePowerKey}}: specifies which action is invoked when the power key is pressed.<br />
* {{ic|HandleSuspendKey}}: specifies which action is invoked when the suspend key is pressed.<br />
* {{ic|HandleHibernateKey}}: specifies which action is invoked when the hibernate key is pressed.<br />
* {{ic|HandleLidSwitch}}: specifies which action is invoked when the lid is closed.<br />
<br />
The specified action can be one of {{ic|ignore}}, {{ic|poweroff}}, {{ic|reboot}}, {{ic|halt}}, {{ic|suspend}}, {{ic|hibernate}}, {{ic|hybrid-sleep}}, {{ic|lock}} or {{ic|kexec}}.<br />
<br />
If these options are not configured, ''systemd'' will use its defaults: {{ic|1=HandlePowerKey=poweroff}}, {{ic|1=HandleSuspendKey=suspend}}, {{ic|1=HandleHibernateKey=hibernate}}, and {{ic|1=HandleLidSwitch=suspend}}.<br />
<br />
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 />
{{Note|<br />
* [[systemd#Using units|Restart]] the {{ic|systemd-logind}} daemon for your changes to take effect (be warned: this will terminate all login sessions).<br />
* ''systemd'' cannot handle AC and Battery ACPI events, so if you use [[Laptop Mode Tools]] or other similar tools [[acpid]] is still required.<br />
* If more than one display is connected, the action specified by {{ic|HandleLidSwitchDocked}} occurs.<br />
}}<br />
<br />
In the current version of ''systemd'', the {{ic|Handle*}} options will apply throughout the system unless they are "inhibited" (temporarily turned off) by a program, such as a power manager inside a desktop environment. If these inhibits are not taken, you can end up with a situation where ''systemd'' suspends your system, then when it wakes up the other power manager suspends it again.<br />
<br />
{{Warning|Currently, only the power managers of [[KDE]], [[GNOME]] and [[Xfce]] issue the necessary ''inhibited'' commands. When using [[acpid]] or others to handle ACPI events, set the {{ic|Handle}} options to {{ic|ignore}}.}}<br />
<br />
=== Suspend and hibernate ===<br />
<br />
''systemd'' provides commands for suspend to RAM, hibernate and a hybrid suspend using the kernel's native suspend/resume functionality. There are also mechanisms to add hooks to customize pre- and post-suspend actions.<br />
<br />
{{Note|''systemd'' can also use other suspend backends (such as [[Uswsusp]] or [[TuxOnIce]]), in addition to the default ''kernel'' backend, in order to put the computer to sleep or hibernate. See [[Uswsusp#With systemd]] for an example.}}<br />
<br />
{{ic|systemctl suspend}} should work out of the box, for {{ic|systemctl hibernate}} to work on your system you need to follow the instructions at [[Suspend and hibernate#Hibernation]].<br />
<br />
==== Hybrid sleep ====<br />
<br />
{{ic|systemctl hybrid-sleep}} both hibernates and suspends at the same time. This combines some of the benefits and drawbacks of suspension and hibernation. This is useful in case a computer were to suddenly lose power (AC disconnection or battery depletion) since upon powerup it will resume from hibernation. If there is no power loss, then it will resume from suspension, which is much faster than resuming from hibernation. However, since "hybrid-sleep" has to dump memory to swap in order for hibernation to work, it is slower to enter sleep than a plain {{ic|systemctl suspend}}. An alternative is a [[#Delayed_hibernation_service_file|delayed hibernation service file]].<br />
<br />
=== Sleep hooks ===<br />
<br />
''systemd'' does not use [[pm-utils]] to put the machine to sleep when using {{ic|systemctl suspend}}, {{ic|systemctl hibernate}} or {{ic|systemctl hybrid-sleep}}; ''pm-utils'' hooks, including any [[Pm-utils#Creating_your_own_hooks|custom hooks]], will not be run. However, ''systemd'' provides two similar mechanisms to run custom scripts on these events.<br />
<br />
==== Suspend/resume service files ====<br />
<br />
Service files can be hooked into ''suspend.target'', ''hibernate.target'' and ''sleep.target'' to execute actions before or after suspend/hibernate. Separate files should be created for user actions and root/system actions. [[systemd#Using units|Enable]] the {{ic|suspend@''user''}} and {{ic|resume@''user''}} services to have them started at boot. Examples:<br />
<br />
{{hc|/etc/systemd/system/suspend@.service|2=<nowiki><br />
[Unit]<br />
Description=User suspend actions<br />
Before=sleep.target<br />
<br />
[Service]<br />
User=%I<br />
Type=forking<br />
Environment=DISPLAY=:0<br />
ExecStartPre= -/usr/bin/pkill -u %u unison ; /usr/local/bin/music.sh stop ; /usr/bin/mysql -e 'slave stop'<br />
ExecStart=/usr/bin/sflock<br />
<br />
[Install]<br />
WantedBy=sleep.target</nowiki>}}<br />
<br />
{{hc|/etc/systemd/system/resume@.service|2=<nowiki><br />
[Unit]<br />
Description=User resume actions<br />
After=suspend.target<br />
<br />
[Service]<br />
User=%I<br />
Type=simple<br />
ExecStartPre=/usr/local/bin/ssh-connect.sh<br />
ExecStart=/usr/bin/mysql -e 'slave start'<br />
<br />
[Install]<br />
WantedBy=suspend.target</nowiki>}}<br />
<br />
For root/system actions ([[systemd#Using units|enable]] the {{ic|root-resume}} and {{ic|root-suspend}} services to have them started at boot):<br />
<br />
{{hc|/etc/systemd/system/root-resume.service|2=<nowiki><br />
[Unit]<br />
Description=Local system resume actions<br />
After=suspend.target<br />
<br />
[Service]<br />
Type=simple<br />
ExecStart=/usr/bin/systemctl restart mnt-media.automount<br />
<br />
[Install]<br />
WantedBy=suspend.target</nowiki>}}<br />
<br />
{{hc|/etc/systemd/system/root-suspend.service|2=<nowiki><br />
[Unit]<br />
Description=Local system suspend actions<br />
Before=sleep.target<br />
<br />
[Service]<br />
Type=simple<br />
ExecStart=-/usr/bin/pkill sshfs<br />
<br />
[Install]<br />
WantedBy=sleep.target</nowiki>}}<br />
<br />
A couple of handy hints about these service files (more in {{ic|man systemd.service}}):<br />
* If {{ic|1=<nowiki>Type=oneshot</nowiki>}} then you can use multiple {{ic|1=<nowiki>ExecStart=</nowiki>}} lines. Otherwise only one {{ic|ExecStart}} line is allowed. You can add more commands with either {{ic|ExecStartPre}} or by separating commands with a semicolon (see the first example above; note the spaces before and after the semicolon, as they are ''required'').<br />
* A command prefixed with {{ic|-}} will cause a non-zero exit status to be ignored and treated as a successful command. <br />
* The best place to find errors when troubleshooting these service files is of course with [[Systemd#Journal|journalctl]].<br />
<br />
==== Combined Suspend/resume service file ====<br />
<br />
With the combined suspend/resume service file, a single hook does all the work for different phases (sleep/resume) and for different targets (suspend/hibernate/hybrid-sleep).<br />
<br />
Example and explanation:<br />
<br />
{{hc|/etc/systemd/system/wicd-sleep.service|2=<nowiki><br />
[Unit]<br />
Description=Wicd sleep hook<br />
Before=sleep.target<br />
StopWhenUnneeded=yes<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
ExecStart=-/usr/share/wicd/daemon/suspend.py<br />
ExecStop=-/usr/share/wicd/daemon/autoconnect.py<br />
<br />
[Install]<br />
WantedBy=sleep.target</nowiki>}}<br />
<br />
* {{ic|1=<nowiki>RemainAfterExit=yes</nowiki>}}: After started, the service is considered active until it is explicitly stopped.<br />
* {{ic|1=<nowiki>StopWhenUnneeded=yes</nowiki>}}: When active, the service will be stopped if no other active service requires it. In this specific example, it will be stopped after ''sleep.target'' is stopped.<br />
* Because ''sleep.target'' is pulled in by ''suspend.target'', ''hibernate.target'' and ''hybrid-sleep.target'' and ''sleep.target'' itself is a ''StopWhenUnneeded'' service, the hook is guaranteed to start/stop properly for different tasks.<br />
<br />
==== Delayed hibernation service file ====<br />
<br />
An alternative approach is delayed hibernation. This makes use of sleep hooks to suspend as usual but sets a timer to wake up later to perform hibernation. Here, entering sleep is faster than {{ic|systemctl hybrid-sleep}} since no hibernation is performed initially. However, unlike "hybrid-sleep", at this point there is no protection against power loss via hibernation while in suspension. This caveat makes this approach more suitable for laptops than desktops. Since hibernation is delayed, the laptop battery is only used during suspension and to trigger the eventual hibernation. This uses less power over the long-term than a "hybrid-sleep" which will remain suspended until the battery is drained. Note that if your laptop has a spinning hard disk, when it wakes up from suspend in order to hibernate, you may not want to be moving or carrying the laptop for these few seconds. Delayed hibernation may be desirable both to reduce power use as well as for security reasons (e.g. when using full disk encryption). An example script is located [http://superuser.com/questions/298672/linuxhow-to-hibernate-after-a-period-of-sleep here]. See also [https://bbs.archlinux.org/viewtopic.php?pid=1420279#p1420279 this post] for an updated systemd sleep hook. <br />
<br />
A slightly updated version of the service is:<br />
{{hc|/etc/systemd/system/suspend-to-hibernate.service|<nowiki><br />
[Unit]<br />
Description=Delayed hibernation trigger<br />
Documentation=https://bbs.archlinux.org/viewtopic.php?pid=1420279#p1420279<br />
Documentation=https://wiki.archlinux.org/index.php/Power_management<br />
Before=suspend.target<br />
Conflicts=hibernate.target hybrid-suspend.target<br />
StopWhenUnneeded=true<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
Environment="WAKEALARM=/sys/class/rtc/rtc0/wakealarm"<br />
Environment="SLEEPLENGTH=+2hour"<br />
ExecStart=-/usr/bin/sh -c 'echo -n "alarm set for "; date +%%s -d$SLEEPLENGTH | tee $WAKEALARM'<br />
ExecStop=-/usr/bin/sh -c '\<br />
alarm=$(cat $WAKEALARM); \<br />
now=$(date +%%s); \<br />
if [ -z "$alarm" ] || [ "$now" -ge "$alarm" ]; then \<br />
echo "hibernate triggered"; \<br />
systemctl hibernate; \<br />
else \<br />
echo "normal wakeup"; \<br />
fi; \<br />
echo 0 > $WAKEALARM; \<br />
'<br />
<br />
[Install]<br />
WantedBy=sleep.target<br />
</nowiki><br />
}}<br />
<br />
The {{ic|Before}} and {{ic|Conflicts}} options ensure it only is run for suspension and not hibernation--otherwise the service will run twice if delayed hibernation is triggered. The {{ic|WantedBy}} and {{ic|StopWhenUnneeded}} options are so it is started before sleep and stops upon resume. (Note that the {{ic|suspend.target}} and {{ic|hibernate.target}} targets do not stop when unneeded, but {{ic|sleep.target}} does). [[systemd#Using units|Enable]] the service.<br />
<br />
==== Hooks in /usr/lib/systemd/system-sleep ====<br />
<br />
''systemd'' runs all executables in {{ic|/usr/lib/systemd/system-sleep/}}, passing 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: {{ic|suspend}}, {{ic|hibernate}} or {{ic|hybrid-sleep}}, depending on which is being invoked<br />
<br />
In contrast to [[pm-utils]], ''systemd'' will run these scripts concurrently and not one after another.<br />
<br />
The output of any custom script will be logged by ''systemd-suspend.service'', ''systemd-hibernate.service'' or ''systemd-hybrid-sleep.service''. You can see its output in ''systemd''<nowiki>'</nowiki>s [[systemd#Journal|journal]]:<br />
# journalctl -b -u systemd-suspend<br />
<br />
{{Note|You can also use ''sleep.target'', ''suspend.target'', ''hibernate.target'' or ''hybrid-sleep.target'' to hook units into the sleep state logic instead of using custom scripts.}}<br />
<br />
An example of a custom sleep script:<br />
<br />
{{hc|/usr/lib/systemd/system-sleep/example.sh|<br />
#!/bin/sh<br />
case $1/$2 in<br />
pre/*)<br />
echo "Going to $2..."<br />
;;<br />
post/*)<br />
echo "Waking up from $2..."<br />
;;<br />
esac}}<br />
<br />
Do not forget to make your script executable:<br />
# chmod a+x /usr/lib/systemd/system-sleep/example.sh<br />
<br />
See {{ic|man 7 systemd.special}} and {{ic|man 8 systemd-sleep}} for more details.<br />
<br />
==== Troubleshooting ====<br />
<br />
===== Delayed lid switch action =====<br />
<br />
When performing lid switches in short succession, ''logind'' will delay the suspend action for up to 90s to detect possible docks. [http://lists.freedesktop.org/archives/systemd-devel/2015-January/027131.html] This delay will be configurable with systemd v210. [http://cgit.freedesktop.org/systemd/systemd/commit/?id=9d10cbee89ca7f82d29b9cb27bef11e23e3803ba]<br />
<br />
== See also ==<br />
<br />
* [[Laptop#Power management]] describes power management specific for laptops - especially battery monitoring.<br />
* [[General recommendations#Power management]]</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Beginners%27_guide&diff=368559Beginners' guide2015-04-05T00:44:14Z<p>Fylwind: /* BIOS/MBR examples */ change MB and GB to MiB and GiB</p>
<hr />
<div>[[Category:Getting and installing Arch]]<br />
[[ar:Beginners' Guide]]<br />
[[bg:Beginners' Guide]]<br />
[[cs:Beginners' Guide]]<br />
[[da:Beginners' Guide]]<br />
[[de:Anleitung für Einsteiger]]<br />
[[el:Beginners' Guide]]<br />
[[es:Beginners' Guide]]<br />
[[fa:راهنمای تازهکارها]]<br />
[[fr:Installation]]<br />
[[he:Beginners' Guide]]<br />
[[hr:Beginners' Guide]]<br />
[[hu:Beginners' Guide]]<br />
[[id:Beginners' Guide]]<br />
[[it:Beginners' Guide]]<br />
[[ja:ビギナーズガイド]]<br />
[[ko:Beginners' Guide]]<br />
[[lt:Beginners' Guide]]<br />
[[nl:Beginners' Guide]]<br />
[[pl:Beginners' Guide]]<br />
[[pt:Beginners' Guide]]<br />
[[ro:Ghidul începătorilor]]<br />
[[ru:Beginners' guide]]<br />
[[sk:Beginners' Guide]]<br />
[[sr:Beginners' Guide]]<br />
[[sv:Nybörjarguiden]]<br />
[[tr:Yeni başlayanlar rehberi]]<br />
[[uk:Beginners' Guide]]<br />
[[zh-CN:Beginners' guide]]<br />
[[zh-TW:Beginners' Guide]]<br />
{{Related articles start}}<br />
{{Related|:Category:Accessibility}}<br />
{{Related|Installation guide}}<br />
{{Related|Diskless system}}<br />
{{Related|Install from SSH}}<br />
{{Related|General recommendations}}<br />
{{Related|General troubleshooting}}<br />
{{Related articles end}}<br />
This document will guide you through the process of installing [[Arch Linux]] using the [https://projects.archlinux.org/arch-install-scripts.git/ Arch Install Scripts]. Before installing, you are advised to skim over the [[FAQ]].<br />
<br />
The community-maintained [[Main page|ArchWiki]] is the primary resource that should be consulted if issues arise. The [[IRC channel]] (irc://irc.freenode.net/#archlinux) and the [https://bbs.archlinux.org/ forums] are also excellent resources if an answer cannot be found elsewhere. In accordance with [[the Arch Way]], you are encouraged to type {{ic|man ''command''}} to read the [[man page]] of any command you are unfamiliar with.<br />
<br />
== Minimum system requirements ==<br />
<br />
Arch Linux should run on any [[Wikipedia:P6 (microarchitecture)|i686]] compatible machine with a minimum of 256 MB RAM. A basic installation with all packages from the {{Grp|base}} group should take less than 800 MB of disk space. If you are working with limited space, this can be trimmed down considerably, but you will have to know what you are doing.<br />
<br />
== Prepare the latest installation medium ==<br />
<br />
{{Tip|Compared to the regular ISO images, the [https://downloads.archlinux.de/iso/archboot/latest archboot] images can take several steps explained in this guide [[Archboot#Interactive_setup_features|interactively]]. See [[Archboot]] for details.}}<br />
<br />
The installation media and their [[GnuPG]] signatures can be acquired from the [https://archlinux.org/download/ Download] page. The single ISO image supports both 32bit and 64bit systems; this guide assumes you use the latest available version.<br />
<br />
It is highly recommended to verify the image signature before use, ''especially when downloading from an HTTP mirror'', as these are run by volunteers who could theoretically serve malicious images. [http://www.cs.arizona.edu/stork/packagemanagersecurity/attacks-on-package-managers.html#explanation] On a system with GnuPG installed, do this by downloading the ''PGP signature'' (under ''Checksums'') to the ISO directory, and run:<br />
<br />
$ gpg --verify archlinux-''version''-dual.iso.sig<br />
<br />
If the public key is not found, [[GnuPG#Import key|import]] it with {{ic|gpg --recv-keys ''key-id''}}. <br />
<br />
Alternatively, run from an existing Arch Linux installation:<br />
<br />
$ pacman-key -v archlinux-''version''-dual.iso.sig<br />
<br />
Now choose one of the methods from the table below to [[#Boot the installation medium]] on the target machine(s). As the installation process retrieves packages from a remote repository, these methods require an internet connection; see [[Offline installation of packages]] when none is available.<br />
<br />
{| class="wikitable"<br />
! Method<br />
! Articles<br />
! Conditions<br />
|-<br />
| Write the image on flash media or optical disc, then boot from it.<br />
|<br />
* [[USB flash installation media]]<br />
* [[Optical disc drive#Burning]]<br />
|<br />
* Installation on one, or a few machines at most<br />
* Obtain a directly bootable system<br />
|-<br />
| Mount the image on a server machine and have clients boot it over the network.<br />
|<br />
* [[PXE]]<br />
* [[Diskless system]]<br />
|<br />
* Client-server model<br />
* Wired (1Gbit+) network connection<br />
|-<br />
| Mount the image in a running Linux system and install Arch from a chroot environment.<br />
|<br />
* [[Install from existing Linux]]<br />
* [[Install from SSH]]<br />
|<br />
* Replace an existing system with reduced downtime<br />
* Install on the local machine, or a remote one via [[VNC]] or [[SSH]]<br />
|-<br />
| Set up a virtual machine and install Arch as a guest system.<br />
|<br />
* [[:Category:Hypervisors]]<br />
* [[Moving an existing install into (or out of) a virtual machine]]<br />
|<br />
* Operating system compatible with virtualization software<br />
* Obtain an isolated system for learning, testing or debugging<br />
|}<br />
<br />
== Boot the installation medium ==<br />
<br />
Point the current boot device to the media containing the Arch installation media. This is typically achieved by pressing a key during the [[Wikipedia:Power-on self test|POST]] phase, as indicated on the splash screen. Refer to your motherboard's manual for details.<br />
<br />
When the Arch menu appears, select "Boot Arch Linux" and press {{ic|Enter}} to enter the live environment where you will perform the actual installation.<br />
<br />
You will be presented with a [[Zsh]] shell prompt, logged in as the root user. ''Zsh'' provides advanced tab completion and other features as part of the [http://grml.org/zsh/ grml config]. For editing text files, the console editor [[nano#Usage|nano]] is suggested.<br />
<br />
=== Booting into UEFI mode ===<br />
<br />
{{Warning|While the choice to install in EFI mode is forward looking, early vendor UEFI implementations carried more bugs than their BIOS counterparts. It is advised to do a search relating your particular mainboard model before proceeding.}}<br />
<br />
In case you have a [[Unified Extensible Firmware Interface|UEFI]] motherboard with UEFI mode enabled, the CD/USB will automatically launch Arch Linux via [[Gummiboot]] and present the following menu:<br />
<br />
{{bc|<br />
Arch Linux archiso x86_64 UEFI USB<br />
UEFI Shell x86_64 v1<br />
UEFI Shell x86_64 v2<br />
EFI Default Loader}}<br />
<br />
To verify you are booted in UEFI mode, run:<br />
<br />
# efivar -l<br />
<br />
Should ''efivar'' not list the UEFI variables properly, check if all [[UEFI#Requirements_for_UEFI_variable_support|requirements]] are met.<br />
<br />
=== Troubleshooting boot problems ===<br />
<br />
* If you are using an Intel video chipset and the screen goes blank during the boot process, the problem is likely an issue with [[Kernel mode setting]]. A possible workaround may be achieved by rebooting and pressing {{ic|Tab}} over the entry that you are trying to boot (i686 or x86_64). At the end of the string type {{ic|nomodeset}} and press {{ic|Enter}}. Alternatively, try {{ic|1=video=SVIDEO-1:d}} which, if it works, will not disable kernel mode setting. You can also try {{ic|1=i915.modeset=0}}. See the [[Intel]] article for more information.<br />
* If the screen does ''not'' go blank and the boot process gets stuck while trying to load the kernel, press {{ic|Tab}} while hovering over the menu entry, type {{ic|1=acpi=off}} at the end of the string and press {{ic|Enter}}.<br />
<br />
== Keyboard layout ==<br />
<br />
{{Note|Changes here ''only'' affect the installation process.}}<br />
<br />
The default keyboard layout is set to [[Wikipedia:File:KB United States-NoAltGr.svg|US]], the [[locale]] to {{ic|en_US.UTF-8}}. To change the keyboard layout, run:<br />
<br />
# loadkeys ''layout''<br />
<br />
where ''layout'' is a two-letter [[Wikipedia:ISO 3166-1 alpha-2#Officially assigned code elements|country code]]. Use {{ic|localectl list-keymaps}} to list all available keymaps.<br />
<br />
If certain special characters appear as white squares or other symboles, you may wish to change the console font. See [[Fonts#Previewing_and_testing]] for details.<br />
<br />
== Establish an internet connection ==<br />
<br />
{{Warning|As of [http://cgit.freedesktop.org/systemd/systemd/tree/NEWS?id&#61;dee4c244254bb49d1ffa8bd7171ae9cce596d2d0 v197], udev no longer assigns network interface names according to the ''wlanX'' and ''ethX'' naming scheme. If you are coming from a different distribution or are reinstalling Arch and not aware of the new interface naming style, please do not assume that your wireless interface is named ''wlan0'', or that your wired interface is named ''eth0''. You can use the command {{ic|ip link}} to discover the names of your interfaces.}}<br />
<br />
{{Tip|The ''elinks'' browser is available in the live system: it can be useful for example to authenticate in RADIUS-protected networks.}}<br />
<br />
The ''dhcpcd'' network daemon starts automatically during boot and it will attempt to start a wired connection. Try to ping a server to see if a connection was established. For example, Google's webservers:<br />
<br />
{{hc|# ping -c 3 www.google.com|2=<br />
PING www.l.google.com (74.125.132.105) 56(84) bytes of data.<br />
64 bytes from wb-in-f105.1e100.net (74.125.132.105): icmp_req=1 ttl=50 time=17.0 ms<br />
64 bytes from wb-in-f105.1e100.net (74.125.132.105): icmp_req=2 ttl=50 time=18.2 ms<br />
64 bytes from wb-in-f105.1e100.net (74.125.132.105): icmp_req=3 ttl=50 time=16.6 ms<br />
<br />
--- www.l.google.com ping statistics ---<br />
3 packets transmitted, 3 received, 0% packet loss, time 2003ms<br />
rtt min/avg/max/mdev = 16.660/17.320/18.254/0.678 ms<br />
}}<br />
<br />
If you get a {{ic|ping: unknown host}} error, first check if there is an issue with your cable or wireless signal strength. If not, you will need to set up the network manually, as explained below. Once a connection is established move on to [[#Prepare the storage devices]].<br />
<br />
=== Static IP ===<br />
<br />
Follow this procedure if you need to set up a wired connection via a static IP address.<br />
<br />
Identify the name of your ethernet interface:<br />
<br />
{{hc|# ip link|<br />
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT<br />
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00<br />
2: enp2s0f0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN mode DEFAULT qlen 1000<br />
link/ether 00:11:25:31:69:20 brd ff:ff:ff:ff:ff:ff<br />
3: wlp3s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP mode DORMANT qlen 1000<br />
link/ether 01:02:03:04:05:06 brd ff:ff:ff:ff:ff:ff<br />
}}<br />
<br />
In this example, the ethernet interface is {{ic|enp2s0f0}}. If you are unsure, your ethernet interface is likely to start with the letter "e", and unlikely to be "lo" or start with the letter "w".<br />
<br />
See [[Network_configuration#Static_IP_address]] for required settings. Configure a static profile for ''dhcpcd'' in {{ic|/etc/dhcpcd.conf}} with your settings, for example: <br />
<br />
interface enp2s0f0<br />
static ip_address=192.168.0.10/24<br />
static routers=192.168.0.1<br />
static domain_name_servers=192.168.0.1 8.8.8.8<br />
<br />
Restart {{ic|dhcpcd.service}}:<br />
<br />
# systemctl restart dhcpcd.service<br />
<br />
You should now have a working network connection. If you do not, see [[Network configuration]] page.<br />
<br />
=== Wireless ===<br />
<br />
{{Warning|Wireless chipset firmware packages (for cards which require them) are pre-installed under {{ic|/usr/lib/firmware}} in the live environment (on CD/USB stick) '''but must be explicitly installed to your actual system to provide wireless functionality after you reboot into it!''' Package installation is covered later in this guide. Ensure installation of both your wireless module and firmware before rebooting! See [[Wireless network configuration]] if you are unsure about the requirement of corresponding firmware installation for your particular chipset.}}<br />
<br />
Use [[netctl]]'s ''wifi-menu'' to connect to a wireless network:<br />
<br />
# wifi-menu<br />
<br />
This should bring you a menu of wifi networks if your computer has only one Wi-Fi device (mostly the case in laptops).<br />
<br />
If your computer has more than one Wi-Fi device, you need to choose one and pass its interface name to ''wifi-menu''. First, identify the name of the needed interface:<br />
<br />
{{hc|# iw dev|2=<br />
phy#0<br />
Interface wlp3s0<br />
ifindex 3<br />
wdev 0x1<br />
addr 00:11:22:33:44:55<br />
type managed<br />
}}<br />
<br />
This example shows {{ic|wlp3s0}} as the only available wireless interface, for simplicity. If you are unsure, wireless interfaces are likely to start with the letter "w", and unlikely to be "lo" or start with the letter "e".<br />
<br />
Now try ''wifi-menu'' again by passing it the interface name:<br />
<br />
# wifi-menu wlp3s0<br />
<br />
See the sample configuration in [[WPA2 Enterprise#netctl]] for networks that require both a username and password.<br />
<br />
You should now have a working wireless network connection. If you do not or even failed to identify the wireless interface, see [[#Without wifi-menu]] below or the detailed [[Wireless network configuration]] page.<br />
<br />
==== Without wifi-menu ====<br />
<br />
Bring the interface up with:<br />
<br />
# ip link set wlp3s0 up<br />
<br />
To verify that the interface is up, inspect the output of the following command:<br />
<br />
{{hc|# ip link show wlp3s0|<br />
3: wlp3s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state DOWN mode DORMANT group default qlen 1000<br />
link/ether 00:11:22:33:44:55 brd ff:ff:ff:ff:ff:ff<br />
}}<br />
<br />
The {{ic|UP}} in {{ic|<BROADCAST,MULTICAST,UP,LOWER_UP>}} is what indicates the interface is up, not the later {{ic|state DOWN}}.<br />
<br />
Most wireless chipsets require firmware in addition to a corresponding driver. The kernel tries to identify and load both automatically. If you get output like {{ic|SIOCSIFFLAGS: No such file or directory}}, this means you will need to manually load the firmware. If unsure, invoke ''dmesg'' to query the kernel log for a firmware request from the wireless chipset. For example, if you have an Intel chipset which requires and has requested firmware from the kernel at boot:<br />
<br />
{{hc|<nowiki># dmesg | grep firmware</nowiki>|<br />
firmware: requesting iwlwifi-5000-1.ucode<br />
}}<br />
<br />
If there is no output, it may be concluded that the system's wireless chipset does not require firmware.<br />
<br />
Next, scan for available networks using {{ic|iw dev wlp3s0 scan <nowiki>|</nowiki> grep SSID}}, then connect to a network with:<br />
<br />
# wpa_supplicant -B -i wlp3s0 -c <(wpa_passphrase "''ssid''" "''psk''")<br />
<br />
You need to replace {{ic|''ssid''}} with the name of your network and {{ic|''psk''}} with your wireless password, '''leaving the quotes around the network name and password'''.<br />
<br />
Finally, you have to give your interface an IP address. This can be set manually or using dhcp:<br />
<br />
# dhcpcd wlp3s0<br />
<br />
If that does not work, issue the following commands:<br />
<br />
# echo 'ctrl_interface=DIR=/run/wpa_supplicant' > /etc/wpa_supplicant.conf<br />
# wpa_passphrase "''ssid''" "''psk''" >> /etc/wpa_supplicant.conf<br />
# ip link set ''interface'' up<br />
# wpa_supplicant -B -D nl80211,wext -c /etc/wpa_supplicant.conf -i ''interface''<br />
# dhcpcd -A ''interface''<br />
<br />
Setting the interface up at step 3 may not be needed, but does no harm in any case.<br />
<br />
=== Analog modem, ISDN, or PPPoE DSL ===<br />
<br />
For xDSL, dial-up, and ISDN connections, see [[Direct Modem Connection]].<br />
<br />
=== Behind a proxy server ===<br />
<br />
If you are behind a proxy server, you will need to export the {{ic|http_proxy}} and {{ic|ftp_proxy}} environment variables. See [[Proxy settings]] for more information.<br />
<br />
== Prepare the storage devices ==<br />
<br />
In this step, the storage devices that will be used by the new system will be prepared. Read [[Partitioning]] for a more general overview.<br />
<br />
{{Warning|Partitioning will destroy existing data. Before proceeding, you '''must''' backup all data that needs to be preserved.}}<br />
<br />
{{Tip|<br />
* Users intending to create stacked block devices for [[LVM]], [[disk encryption]] or [[RAID]], should keep those instructions into consideration when preparing the partitions.<br />
* If intending to install to a USB flash key, see [[Installing Arch Linux on a USB key]].}}<br />
<br />
=== Identify the devices ===<br />
<br />
The first step is identify the devices where the new system will be installed. The following command will show all the available devices:<br />
<br />
# lsblk<br />
<br />
This will list all devices connected to your system along with their partition schemes, including that used to host and boot live Arch installation media (e.g. a USB drive). Not all devices listed will therefore be viable or appropriate mediums for installation. To filter out inappropriate results, the command can optionally be amended as follows:<br />
<br />
# lsblk | grep -v "rom\|loop\|airoot"<br />
<br />
Devices (e.g. hard disks) will be listed as {{ic|sd''x''}}, where {{ic|''x''}} is a lower-case letter starting from {{ic|a}} for the first device ({{ic|sda}}), {{ic|b}} for the second device ({{ic|sdb}}), and so on. Existing partitions on those devices will be listed as {{ic|sd''xY''}}, where {{ic|''Y''}} is a number starting from {{ic|1}} for the first partition, {{ic|2}} for the second, and so on. In the example below, only one device is available ({{ic|sda}}), and that device uses only one partition ({{ic|sda1}}):<br />
<br />
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT<br />
sda 8:0 0 80G 0 disk<br />
└─sda1 8:1 0 80G 0 part<br />
<br />
The {{ic|sd''xY''}} convention will be used in the examples provided below for partition tables, partitions, and file systems. As they are just examples, it is important to ensure that any necessary changes to device names, partition numbers, and/or partition sizes (etc.) are made. Do not just blindly copy and paste the commands.<br />
<br />
If the existing partition scheme needs not be changed, skip to [[#Create filesystems]], otherwise continue reading the following section.<br />
<br />
=== Partition table types ===<br />
<br />
If you are installing alongside an existing installation (i.e. dual-booting), a partition table will already be in use. If the devices are not partitioned, or the current partitions table or scheme needs to be changed, you will first have to determine the partition tables (one for each device) in use or to be used.<br />
<br />
{{Warning|If Arch and Windows are dual-booting from same device, then Arch '''must''' follow the same firmware boot mode and partitioning combination already used, or Windows will fail to boot. See [[Windows and Arch Dual Boot#Important information]] for more details.}}<br />
<br />
There are two types of partition table:<br />
<br />
* [[Master Boot Record| MBR]]: Intended for BIOS systems (also referred to as "msdos")<br />
* [[GUID Partition Table| GPT]]: Intended for UEFI systems<br />
<br />
Any existing partition table can be identified with the following command for each device:<br />
<br />
# parted /dev/sd''x'' print<br />
<br />
=== Partitioning tools ===<br />
<br />
For each device to be partitioned, a proper tool must be chosen according to the partition table to be used. Several partitioning tools are provided by the Arch installation medium, including:<br />
<br />
* [[parted]]: MBR and GPT<br />
* [[Partitioning#Fdisk usage summary|fdisk]], '''cfdisk''', '''sfdisk''': MBR and GPT<br />
* [[Partitioning#Gdisk usage summary|gdisk]], '''cgdisk''', '''sgdisk''': GPT<br />
<br />
{{Warning|Using a partitioning tool that is incompatible with your partition table type will likely result in the destruction of that table, along with any existing partitions/data.}}<br />
<br />
{{Tip|The devices may also be partitioned before booting the Arch installation media, possibly using alternative live systems with other partitioning tools. For example beginners might find it easier to use a graphical partitioning tool such as [[GParted]], which is also provided as a [http://gparted.sourceforge.net/livecd.php live CD] and works with both MBR and GPT partition tables.}}<br />
<br />
==== Using parted in interactive mode ====<br />
<br />
All the examples provided below make use of ''parted'', as it can be used for both BIOS/MBR and UEFI/GPT. It will be launched in ''interactive mode'', which simplifies the partitioning process and reduces unnecessary repetition by automatically applying all partitioning commands to the specified device.<br />
<br />
In order to start operating on a device, execute:<br />
<br />
# parted /dev/sd''x''<br />
<br />
You will notice that the command-line prompt changes from a hash ({{ic|#}}) to {{ic|(parted)}}: this also means that the new prompt is not a command to be manually entered when running the commands in the examples.<br />
<br />
To see a list of the available commands, enter:<br />
<br />
(parted) help<br />
<br />
When finished, or if wishing to implement a partition table or scheme for another device, exit from parted with:<br />
<br />
(parted) quit<br />
<br />
After exiting, the command-line prompt will change back to {{ic|#}}.<br />
<br />
=== Create new partition table ===<br />
<br />
You need to (re)create the partition table of a device when it has never been partitioned before, or when you want to change the type of its partition table. Recreating the partition table of a device is also useful when the partition scheme needs to be restructured from scratch.<br />
<br />
{{Warning|<br />
* If dual-booting with an existing installation of Windows on a UEFI/GPT system, do not erase the partition table. Doing so will destroy all existing data on the device, including the UEFI partition with the Windows ''.efi'' file required to boot it.<br />
* MBR is designed specifically for use with BIOS systems, and GPT is designed for UEFI. It is not recommended for less experienced users to break this convention as both have features and/or limitations that may be incompatible with your hardware (e.g. MBR cannot cope with devices larger than 2 TiB). [https://www.happyassassin.net/2014/01/25/uefi-boot-how-does-that-actually-work-then/] If for any reason you do not wish to follow this convention, see [http://mjg59.dreamwidth.org/8035.html] and [http://rodsbooks.com/gdisk/bios.html] for more information and possible workarounds.}}<br />
<br />
Open each device whose partition table must be (re)created with:<br />
<br />
# parted /dev/sd''x''<br />
<br />
To then create a new MBR/msdos partition table for BIOS systems, use the following command:<br />
<br />
(parted) mklabel msdos<br />
<br />
To create a new GPT partition table for UEFI systems instead, use:<br />
<br />
(parted) mklabel gpt<br />
<br />
=== Partition schemes ===<br />
<br />
You can decide the number and size of the partitions the devices should be split into, and which directories will be used to mount the partitions in the installed system (also known as ''mount points''). The mapping from partitions to directories is the [[Partitioning#Partition scheme|partition scheme]], which must comply with the following requirements:<br />
<br />
* At least a partition for the {{ic|/}} (''root'') directory '''must''' be created.<br />
* Depending on the motherboard's firmware interface, the chosen [[#Partition table types]], and in some cases also the chosen [[boot loader]], the following additional partitions '''must''' be created:<br />
** '''BIOS/MBR''': no additional partition required.<br />
** '''UEFI/GPT''': one [[Unified Extensible Firmware Interface#EFI System Partition|EFI System Partition]].<br />
<br />
In the examples below it is assumed that a new and contiguous partitioning scheme is applied to a single device. Some optional partitions will also be created for the {{ic|/boot}} and {{ic|/home}} directories: see also [[Arch filesystem hierarchy]] for an explanation of the purpose of the various directories; if separate partitions for directories like {{ic|/boot}} or {{ic|/home}} are not created, these will simply be contained in the {{ic|/}} partition. Also the creation of an optional partiton for [[swap space]] will be illustrated.<br />
<br />
If not already open in a ''parted'' interactive session, open each device to be partitioned with:<br />
<br />
# parted /dev/sd''x''<br />
<br />
The following command will be used to create partitions:<br />
<br />
(parted) mkpart ''part-type'' ''fs-type'' ''start'' ''end''<br />
<br />
* {{ic|''part-type''}} is one of {{ic|primary}}, {{ic|extended}} or {{ic|logical}}, and is meaningful only for MBR partition tables.<br />
* {{ic|''fs-type''}} is one of the supported file systems listed in the [http://www.gnu.org/software/parted/manual/parted.html#mkpart manual]. The partition will be properly formatted in [[#Create filesystems]].<br />
* {{ic|''start''}} is the beginning of the partition from the start of the device. It consists of a number followed by a [http://www.gnu.org/software/parted/manual/parted.html#unit unit], for example {{ic|1M}} means start at 1MiB.<br />
* {{ic|''end''}} is the end of the partition from the start of the device (''not'' from the {{ic|''start''}} value). It has the same syntax as {{ic|''start''}}, for example {{ic|100%}} means end at the end of the device (use all the remaining space).<br />
<br />
{{Warning|It is important that the partitions do not overlap each other: if you do not want to leave unused space in the device, make sure that each partition starts where the previous one ends.}}<br />
<br />
{{Note|''parted'' may issue a warning like:<br />
<br />
Warning: The resulting partition is not properly aligned for best performance.<br />
Ignore/Cancel?<br />
<br />
In this case, read [[Partitioning#Partition alignment]] and follow [[GNU Parted#Alignment]] to fix it.}}<br />
<br />
The following command will be used to flag the partition that contains the {{ic|/boot}} directory as bootable:<br />
<br />
(parted) set ''partition'' boot on<br />
<br />
* {{ic|''partition''}} is the number of the partition to be flagged (see the output of the {{ic|print}} command).<br />
<br />
==== UEFI/GPT examples ====<br />
<br />
In every instance, a special bootable [[Unified Extensible Firmware Interface#EFI System Partition|EFI System Partition]] is required.<br />
<br />
{{Warning|If dual-booting with an existing installation of Windows on a UEFI/GPT system, the existing UEFI partition must not be deleted. Doing so will destroy the ''.efi'' file required to boot Windows.}}<br />
<br />
If creating a new EFI System Partition, use the following commands (the recommended size is 512MiB):<br />
<br />
(parted) mkpart ESP fat32 1MiB 513MiB<br />
(parted) set 1 boot on<br />
<br />
The remaining partition scheme is entirely up to you. For one other partition using 100% of remaining space:<br />
<br />
(parted) mkpart primary ext3 513MiB 100%<br />
<br />
For separate {{ic|/}} (20GiB) and {{ic|/home}} (all remaining space) partitions:<br />
<br />
(parted) mkpart primary ext3 513MiB 20.5GiB<br />
(parted) mkpart primary ext3 20.5GiB 100%<br />
<br />
And for separate {{ic|/}} (20GiB), swap (4GiB), and {{ic|/home}} (all remaining space) partitions:<br />
<br />
(parted) mkpart primary ext3 513MiB 20.5GiB<br />
(parted) mkpart primary linux-swap 20.5GiB 24.5GiB<br />
(parted) mkpart primary ext3 24.5GiB 100%<br />
<br />
==== BIOS/MBR examples ====<br />
<br />
For a minimum single primary partition using all available disk space, the following command would be used:<br />
<br />
(parted) mkpart primary ext3 1MiB 100%<br />
(parted) set 1 boot on<br />
<br />
In the following instance, a 20GiB {{ic|/}} partition will be created, followed by a {{ic|/home}} partition using all the remaining space:<br />
<br />
(parted) mkpart primary ext3 1MiB 20GiB<br />
(parted) set 1 boot on<br />
(parted) mkpart primary ext3 20GiB 100%<br />
<br />
In the final example below, separate {{ic|/boot}} (100MiB), {{ic|/}} (20GiB), swap (4GiB), and {{ic|/home}} (all remaining space) partitions will be created:<br />
<br />
(parted) mkpart primary ext3 1MiB 100MiB<br />
(parted) set 1 boot on<br />
(parted) mkpart primary ext3 100MiB 20GiB<br />
(parted) mkpart primary linux-swap 20GiB 24GiB<br />
(parted) mkpart primary ext3 24GiB 100%<br />
<br />
=== Create filesystems ===<br />
<br />
Once the partitions have been created, each must be formatted with an appropriate [[file system]], ''except'' for swap partitions. All available partitions on the intended installation device can be listed with the following command:<br />
<br />
# lsblk /dev/sd''x''<br />
<br />
With the exceptions noted below, it is recommended to use the {{ic|ext4}} file system:<br />
<br />
# mkfs.ext4 /dev/sd''xY''<br />
<br />
{{Warning|<br />
* If dual-booting with an existing installation of Windows on a UEFI/GPT system, do not re-format the UEFI partition. Doing so will destroy all existing data on that partition, including the Windows ''.efi'' file required to boot it.<br />
* If a new UEFI system partition has been created on a UEFI/GPT system, it must be formatted with a {{ic|fat32}} or {{ic|vfat32}} file system. Failure to do so will result in an unbootable installation:<br />
:{{bc|# mkfs.vfat -F32 /dev/sd''xY''}}}}<br />
<br />
=== Activate swap ===<br />
<br />
If a swap partition has been created, it must be set up and activated with:<br />
<br />
# mkswap /dev/sd''xY''<br />
# swapon /dev/sd''xY''<br />
<br />
=== Mount the partitions ===<br />
<br />
{{Note|Swap partitions must '''not''' be mounted here.}}<br />
<br />
The {{ic|/}} (root) partition must be mounted '''first''': this is because any directories such as {{ic|/boot}} or {{ic|/home}} that have separate partitions will have to be created in the root file system. The {{ic|/mnt}} directory of the live system will be used to mount the root partition, and consequently all the other partitions will stem from there. If the root partition's name is {{ic|sd''xR''}}, do:<br />
<br />
# mount /dev/sd''xR'' /mnt<br />
<br />
Once the {{ic|/}} partition has been mounted, any remaining partitions may be mounted in any order. The general procedure is to first create the mount point, and then mount the partition to it. If using a separate {{ic|/boot}} partition:<br />
<br />
# mkdir -p /mnt/boot<br />
# mount /dev/sd''xB'' /mnt/boot<br />
<br />
{{Note|Using {{ic|/boot}} is recommended also for mounting the EFI System Partition on UEFI/GPT system. See [[EFISTUB]] and related articles for alternatives.}}<br />
<br />
If using a separate {{ic|/home}} partition:<br />
<br />
# mkdir -p /mnt/home<br />
# mount /dev/sd''xH'' /mnt/home<br />
<br />
Once all the remaining partitions, if any, have been mounted, the devices are ready to install Arch.<br />
<br />
== Select a mirror ==<br />
<br />
You may want to edit the {{ic|mirrorlist}} file and place your preferred mirror first. A copy of this file will be installed on your new system by ''pacstrap'' as well, so it is worth getting it right.<br />
<br />
{{hc|# nano /etc/pacman.d/mirrorlist|<br />
##<br />
## Arch Linux repository mirrorlist<br />
## Sorted by mirror score from mirror status page<br />
## Generated on YYYY-MM-DD<br />
##<br />
<br />
<nowiki>Server = http://mirror.example.xyz/archlinux/$repo/os/$arch</nowiki><br />
...}}<br />
<br />
If you want, you can make it the ''only'' mirror available by deleting all other lines, but it is usually a good idea to have a few more, in case the first one goes offline. Should you change your mirror list at a later stage, refresh all package lists with {{ic|pacman -Syyu}}. See [[Mirrors]] for more information.<br />
<br />
== Install the base system ==<br />
<br />
The base system is installed using the ''pacstrap'' script. The {{ic|-i}} switch can be omitted if you wish to install every package from the {{Grp|base}} group without prompting. To build packages from the [[AUR]] or with [[ABS]], you will also need the {{Grp|base-devel}} group.<br />
<br />
# pacstrap -i /mnt base base-devel<br />
<br />
Other packages can be installed later using [[pacman]].<br />
<br />
See [[Pacman#Troubleshooting]] and [[Pacman-key#Troubleshooting]] in case of errors.<br />
<br />
== Generate an fstab ==<br />
<br />
[[Wikipedia:Universally_unique_identifier|UUID]]s are used because they have certain advantages (see [[fstab#Identifying filesystems]]). If you prefer labels instead, replace the {{ic|-U}} option with {{ic|-L}}:<br />
<br />
# genfstab -U -p /mnt >> /mnt/etc/fstab<br />
# nano /mnt/etc/fstab<br />
<br />
{{Warning|The {{ic|fstab}} file should always be checked after generating it. If you encounter errors running ''genfstab'' or later in the install process, do '''not''' run ''genfstab'' again; just edit the {{ic|fstab}} file. See [[fstab#Field definitions]] for syntax information.}}<br />
<br />
== Chroot and configure the base system ==<br />
<br />
Next, [[Change root|chroot]] into your newly installed system:<br />
<br />
# arch-chroot /mnt /bin/bash<br />
<br />
At this stage of the installation, you will configure the primary configuration files of your Arch Linux base system. These can either be created if they do not exist, or edited if you wish to change the defaults.<br />
<br />
Closely following and understanding these steps is of key importance to ensure a properly configured system.<br />
<br />
{{Warning|Do not assume that the tools you used from the ISO are automatically installed. For example, if you used ''wifi-menu'' to gain network access during the installation and want to continue so after the first boot, you will have to install ''dialog'' to use it. The following section specifies such cases, do follow it closely to avoid a hiccup in your fresh install.}}<br />
<br />
=== Locale ===<br />
<br />
Locales define which language the system uses and other regional considerations, such as currency denomination, numerology and character sets. Possible values are listed in {{ic|/etc/locale.gen}}, with the active locale defined in {{ic|locale.conf}} files.<br />
<br />
All entries in {{ic|locale.gen}} are commented out (preceded by {{ic|#}}) by default. Uncomment {{ic|en_US.UTF-8 UTF-8}}, as well as other needed localisations. {{ic|UTF-8}} is highly recommended over other options.<br />
<br />
{{hc|# nano /etc/locale.gen|<br />
...<br />
#en_SG ISO-8859-1<br />
en_US.UTF-8 UTF-8<br />
#en_US ISO-8859-1<br />
...<br />
}}<br />
<br />
Before locales can be enabled, they must be ''generated'':<br />
<br />
# locale-gen<br />
<br />
Create {{ic|/etc/locale.conf}}, where {{ic|LANG}} refers to the first column of an uncommented entry in {{ic|/etc/locale.gen}}.<br />
<br />
# echo LANG=''en_US.UTF-8'' > /etc/locale.conf<br />
<br />
Export the chosen locale:<br />
<br />
# export LANG=''en_US.UTF-8''<br />
<br />
{{Note|<br />
* Choosing {{ic|en_US.UTF-8}} as the system locale allows to keep system logs in English for easier troubleshooting. Users may override this setting for their session as described in [[Locale#Setting the locale]].<br />
* {{ic|LANG}} acts as the default value for the locale-related {{ic|LC_*}} variables. To use other locales for these variables, run ''locale'' to see the available options and add them to {{ic|locale.conf}}. It is not recommended to set the {{ic|LC_ALL}} variable. See [[Locale]] for details.}}<br />
<br />
=== Console font and keymap ===<br />
<br />
If you changed the default console keymap and font in [[#Keyboard layout]], create {{ic|/etc/vconsole.conf}} to make those changes persist in the installed system. It is important {{ic|KEYMAP}} matches the value initially set with {{ic|loadkeys}}, to ensure correct entry of [[#Set the root password|the root password]] on reboot.<br />
<br />
{{hc|# nano /etc/vconsole.conf|2=<br />
KEYMAP=''de-latin1''<br />
FONT=''lat9w-16''<br />
}}<br />
<br />
These settings only apply to virtual consoles, not [[Xorg]]. See [[Fonts#Console fonts]] for more information.<br />
<br />
=== Time zone ===<br />
<br />
Available time zones and subzones can be found in the {{ic|/usr/share/zoneinfo/''Zone''/''SubZone''}} directories, and listed with the ''ls'' command. Create a symbolic link {{ic|/etc/localtime}} to your subzone file {{ic|/usr/share/zoneinfo/''Zone''/''SubZone''}}:<br />
<br />
# ln -s /usr/share/zoneinfo/''Zone''/''SubZone'' /etc/localtime<br />
<br />
You may use [http://tldp.org/LDP/abs/html/tabexpansion.html tab completion] to show available zones and subzones. Example:<br />
<br />
# ln -s /usr/share/zoneinfo/Europe/Minsk /etc/localtime<br />
<br />
If you get {{ic|ln: failed to create symbolic link '/etc/localtime': File exists}}, check the existing file with {{ic|ls -l /etc/localtime}} and add the {{ic|-f}} option to the ''ln'' command to overwrite it.<br />
<br />
=== Hardware clock ===<br />
<br />
If you have multiple operating systems installed in the same machine, they will all derive the current time from the same hardware clock, which must be set to either UTC or ''localtime''. For this reason you must make sure that all the operating systems see the hardware clock as providing time in the same chosen [[Time#Time standard|standard]], otherwise some of them will perform the time zone adjustement for the system clock, while others will not.<br />
<br />
In particular, it is strongly recommended to set the hardware clock to UTC, in order to avoid conflicts between the installed operating systems. For example, if the hardware clock was set to ''localtime'', more than one operating system may adjust it after a [[Wikipedia:Daylight_saving_time|DST]] change, thus resulting in an overcorrection; more problems may arise when travelling between different time zones and using one of the operating systems to reset the system/hardware clock.<br />
<br />
To set the hardware clock to UTC in Linux, run:<br />
<br />
# hwclock --systohc --utc<br />
<br />
The ''hwclock'' command also generates the {{ic|/etc/adjtime}} file.<br />
<br />
{{Note|Using UTC for the hardware clock does not mean that software will display time in UTC. However, the system setup/BIOS interface will instead: this should be neither surprising nor treated as a bug.}}<br />
<br />
{{Warning|Windows systems use ''localtime'' by default. Using ''localtime'' on Arch systems may lead to several known and unfixable bugs, but there are no plans to drop support for ''localtime''. It is, though, recommended to set Windows to use UTC instead, and prevent it from synchronising time. See [[Time#UTC in Windows]].}}<br />
<br />
=== Kernel modules ===<br />
<br />
Needed kernel modules are automatically loaded by [[udev]], so you will rarely need to load modules manually. See [[Kernel modules]] for details.<br />
<br />
=== Hostname ===<br />
<br />
Set the [[Network_configuration#Set_the_hostname|hostname]] to your liking:<br />
<br />
# echo ''myhostname'' > /etc/hostname<br />
<br />
Add the same hostname to {{ic|/etc/hosts}}:<br />
<br />
#<ip-address> <hostname.domain.org> <hostname><br />
127.0.0.1 localhost.localdomain localhost ''myhostname''<br />
::1 localhost.localdomain localhost ''myhostname''<br />
<br />
=== Configure the network ===<br />
<br />
You need to configure the network again, but this time for your newly installed environment. The procedure and prerequisites are similar to the one described [[#Establish an internet connection|above]], except we are going to make it persistent and automatically run at boot.<br />
<br />
As a first step, identify the network interface name you want to configure the connection for with {{ic|ip link}}.<br />
<br />
{{Note|<br />
* For more in-depth information on network configuration, visit [[Network configuration]] and [[Wireless network configuration]].<br />
* If you would like to use the old interface naming scheme (i.e. {{ic|eth''X''}} and {{ic|wlan''X''}}) you can accomplish this by creating an empty file at {{ic|/etc/udev/rules.d/80-net-setup-link.rules}} which will mask the file of the same name located under {{ic|/usr/lib/udev/rules.d}}.<br />
}}<br />
<br />
Now select a daemon to handle the configuration and operation. Several are listed below; only select '''one''' of them for the new system.<br />
<br />
==== Wired ====<br />
<br />
; Using dhcpcd<br />
A simple option for adapter configuration is to use the DHCP Client Daemon, the method used by default with the install medium. See [[Dhcpcd#Running]].<br />
<br />
Users requiring only '''single wired network connection''' can simply enable the ''dhcpcd'' service for the interface:<br />
<br />
# systemctl enable dhcpcd@''interface_name''.service<br />
<br />
If static IP settings are required, adjust the profile configuration as described in [[#Static IP]]. <br />
<br />
; Using systemd-networkd<br />
<br />
The Arch default init system, [[systemd]] includes built-in support for managing adapters using both DHCP and static IP setups. Configuration is simple. See [[Systemd-networkd#Required_services_and_setup]].<br />
<br />
; Using netctl<br />
<br />
Another option is [[netctl]] which is a CLI-based tool used to configure and manage network connections via user-created profiles. Create a profile as shown in [[netctl#Example profiles]], then enable it as described in [[netctl#Basic method]].<br />
<br />
==== Wireless ====<br />
<br />
All of the tools listed in [[#Wired]] above can activate wireless connections. For wireless, however, ''dhcpcd'' and ''systemd-networkd'' require a separate configuration of the connection in the wireless backend, [[wpa_supplicant]], first. If you anticipate to connect the machine to different wireless networks over time, a tool which provides its own connection management may be easier to handle. Aside from [[netctl]] introduced below, [[Wireless network configuration#Automatic setup]] lists other choices. <br />
<br />
{{Note|If your wireless adapter requires a firmware (as described in the above [[#Wireless|Establish an internet connection]] section and also in the article [[Wireless network configuration#Device driver]]), install the package containing your firmware. Most of the time, the {{Pkg|linux-firmware}} package will contain the needed firmware. Though for some devices, the required firmware might be in its own package. For example:<br />
{{bc|# pacman -S zd1211-firmware}}<br />
See [[Wireless network configuration#Installing driver/firmware]] for more info.}}<br />
<br />
Install {{Pkg|iw}} and {{Pkg|wpa_supplicant}} which you will need to connect to a network:<br />
<br />
# pacman -S iw wpa_supplicant<br />
<br />
===== Adding wireless networks =====<br />
<br />
; Using wifi-menu<br />
<br />
Install {{Pkg|dialog}}, which is required for ''wifi-menu'':<br />
<br />
# pacman -S dialog<br />
<br />
After finishing the rest of this installation and rebooting, you can connect to the network with {{ic|wifi-menu ''interface_name''}} (where {{ic|''interface_name''}} is the interface of your wireless chipset).<br />
<br />
# wifi-menu ''interface_name''<br />
<br />
{{Warning|Do not use ''wifi-menu'' now, instead wait until you have finished this guide and have rebooted. It will not work now because a process spawned by this command will conflict with the one you have running outside of the chroot. Alternatively, you could just configure a network profile manually using the following templates so that you do not have to worry about using ''wifi-menu'' at all.}}<br />
<br />
; Using manual netctl profiles<br />
<br />
Copy a network profile from {{ic|/etc/netctl/examples}} to {{ic|/etc/netctl}}:<br />
<br />
# cd /etc/netctl<br />
# cp examples/wireless-wpa my-network<br />
<br />
Edit the profile as needed (modify {{ic|Interface}}, {{ic|ESSID}} and {{ic|Key}}):<br />
<br />
# nano my-network<br />
<br />
Enable above created profile to start it at every boot:<br />
<br />
# netctl enable my-network<br />
<br />
===== Connect automatically to known networks =====<br />
<br />
{{Warning|This method cannot be used with explicitely enabled [[Netctl#Configuration|profiles]], i.e. through {{ic|netctl enable ''profile''}}.}}<br />
<br />
Install {{Pkg|wpa_actiond}}, which is required for {{ic|netctl-auto}}:<br />
<br />
# pacman -S wpa_actiond<br />
<br />
Enable the {{ic|netctl-auto}} service, which will connect to known networks and gracefully handle roaming and disconnects:<br />
<br />
# systemctl enable netctl-auto@''interface_name''.service<br />
<br />
{{Tip|[[netctl]] also provides {{ic|netctl-ifplugd}}, which can be used to handle wired profiles in conjunction with {{ic|netctl-auto}}.}}<br />
<br />
==== Analog modem, ISDN or PPPoE DSL ====<br />
<br />
For xDSL, dial-up and ISDN connections, see [[Direct Modem Connection]].<br />
<br />
=== Create an initial ramdisk environment ===<br />
<br />
{{Note|As [[mkinitcpio]] was run on installation of {{Pkg|linux}} with ''pacstrap'', most users can skip this step and use the defaults provided in {{ic|mkinitcpio.conf}}.}}<br />
<br />
Set the correct [[Mkinitcpio#HOOKS|hooks]] in {{ic|/etc/mkinitcpio.conf}} and re-generate the initramfs image:<br />
<br />
# mkinitcpio -p linux<br />
<br />
=== Set the root password ===<br />
<br />
Set the root password with:<br />
<br />
# passwd<br />
<br />
=== Install and configure a bootloader ===<br />
<br />
==== For BIOS motherboards ====<br />
<br />
For BIOS systems, several boot loaders are available, see [[Boot loaders]] for a complete list. Choose one as per your convenience. Possible choices include:<br />
<br />
* [[Syslinux#Installation]] is (currently) limited to loading only files from the partition where it was installed. Its configuration file is considered to be easier to understand. An example configuration can be found in [[Syslinux#Examples]].<br />
* [[GRUB]] is more feature-rich and supports more complex scenarios. Its configuration file(s) is more similar to 'sh' scripting language, which may be difficult for beginners to manually write. It is recommended that they automatically generate one.<br />
<br />
Here, installation with '''GRUB''' and '''MBR''' is demonstrated. <br />
<br />
Install the {{Pkg|grub}} package; to have GRUB search for other installed operating systems, install {{Pkg|os-prober}} in addition:<br />
<br />
# pacman -S grub os-prober<br />
<br />
Install the bootloader to the drive Arch was installed to (do '''not''' append a partition number, or {{ic|/dev/sda''X''}}):<br />
<br />
# grub-install --target=i386-pc --recheck ''/dev/sda''<br />
<br />
Automatically generate {{ic|grub.cfg}}:<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
{{Note|A sample {{ic|/boot/grub/grub.cfg}} is included with the {{Pkg|grub}} package, and subsequent {{ic|grub-*}} commands may not over-write it. Ensure your intended changes are in {{ic|grub.cfg}}, rather than in {{ic|grub.cfg.new}} or similar file.}}<br />
<br />
For more information on configuring and using GRUB, see [[GRUB]].<br />
<br />
==== For UEFI motherboards ====<br />
<br />
For UEFI systems, several boot loaders are available, see [[Boot loaders]] for a complete list. Choose one as per your convenience. Possible choices include:<br />
<br />
* [[gummiboot]] is a minimal UEFI Boot Manager which provides a menu for [[EFISTUB]] kernels and other UEFI applications. This is recommended for beginners, especially those wishing to dual-boot with other installed operating systems such as Windows 8.<br />
* [[GRUB#UEFI_systems|GRUB]] is a more complete bootloader, useful if you run into problems with Gummiboot.<br />
<br />
Here, installation with ''gummiboot'' is demonstrated. First install {{Pkg|dosfstools}} to manipulate the EFI System Partition post-installation, and {{Pkg|efibootmgr}} to create a UEFI boot entry (used by bootmanager installation scripts):<br />
<br />
# pacman -S dosfstools efibootmgr<br />
<br />
{{Note|<br />
* For UEFI boot, the drive needs to be GPT-partitioned and an [[Unified Extensible Firmware Interface#EFI System Partition|EFI System Partition]] (512 MiB or larger, gdisk type {{ic|EF00}}, formatted with FAT32) must be present. In the following examples, this partition is assumed to be mounted at {{ic|/boot}}. If you have followed this guide from the beginning, you have already done all of these.<br />
* It is strongly recommended to have the EFI System Partition mounted at {{ic|/boot}} as this is required to automatically update Gummiboot.<br />
}}<br />
<br />
Install the {{Pkg|gummiboot}} package and run the automated installation script, replacing {{ic|'''$esp'''}} with the location of your EFI System Partiton, usually {{ic|/boot}}:<br />
<br />
# pacman -S gummiboot<br />
# gummiboot --path='''$esp''' install<br />
<br />
Gummiboot will automatically be detected by firmware that requires that the bootable {{ic|bootx64.efi}} stub be placed in {{ic|'''$esp'''/EFI/boot}}, and will in turn automatically detect the presence of any other installed operating systems using ''.efi'' stubs. However, it will still be necessary to manually create a configuration file for Gummiboot.<br />
<br />
First, create {{ic|'''$esp'''/loader/entries/arch.conf}} and add the following, replacing {{ic|/dev/sdaX}} with your '''root''' partition (most likely {{ic|/dev/sda2}} if {{ic|/dev/sda1}} is the ESP):<br />
<br />
{{hc|# nano '''$esp'''/loader/entries/arch.conf|2=<br />
title Arch Linux<br />
linux /vmlinuz-linux<br />
initrd /initramfs-linux.img<br />
options root='''/dev/sdaX''' rw<br />
}}<br />
<br />
Second, create {{ic|'''$esp'''/loader/loader.conf}} and add the following, replacing the timeout value (in seconds) with your own choice:<br />
{{hc|# nano '''$esp'''/loader/loader.conf|2=<br />
default arch<br />
timeout 5<br />
}}<br />
<br />
See [[gummiboot]] for more information.<br />
<br />
== Unmount the partitions and reboot ==<br />
<br />
Exit from the chroot environment:<br />
<br />
# exit<br />
<br />
{{Note|While partitions are unmounted automatically by ''systemd'' on shutdown, you may do so manually with {{ic|umount -R /mnt}} as a safety measure. If the partition is "busy", you can find the cause with [[fuser]].}}<br />
<br />
Reboot the computer:<br />
<br />
# reboot<br />
<br />
Remove the installation media, or you may boot back into it. You can log into your new installation as ''root'', using the password you specified with ''passwd''.<br />
<br />
== Post-installation ==<br />
<br />
Your new Arch Linux base system is now a functional GNU/Linux environment ready to be built into whatever you wish or require for your purposes. You are now ''strongly'' advised to read the [[General recommendations]] article, especially the first two sections. Its other sections provide links to post-installation tutorials like setting up a graphical user interface, sound or a touchpad.<br />
<br />
For a list of applications that may be of interest, see [[List of applications]].</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Beginners%27_guide&diff=368558Beginners' guide2015-04-05T00:42:50Z<p>Fylwind: /* UEFI/GPT examples */ use MiB and GiB instead of MB and GB</p>
<hr />
<div>[[Category:Getting and installing Arch]]<br />
[[ar:Beginners' Guide]]<br />
[[bg:Beginners' Guide]]<br />
[[cs:Beginners' Guide]]<br />
[[da:Beginners' Guide]]<br />
[[de:Anleitung für Einsteiger]]<br />
[[el:Beginners' Guide]]<br />
[[es:Beginners' Guide]]<br />
[[fa:راهنمای تازهکارها]]<br />
[[fr:Installation]]<br />
[[he:Beginners' Guide]]<br />
[[hr:Beginners' Guide]]<br />
[[hu:Beginners' Guide]]<br />
[[id:Beginners' Guide]]<br />
[[it:Beginners' Guide]]<br />
[[ja:ビギナーズガイド]]<br />
[[ko:Beginners' Guide]]<br />
[[lt:Beginners' Guide]]<br />
[[nl:Beginners' Guide]]<br />
[[pl:Beginners' Guide]]<br />
[[pt:Beginners' Guide]]<br />
[[ro:Ghidul începătorilor]]<br />
[[ru:Beginners' guide]]<br />
[[sk:Beginners' Guide]]<br />
[[sr:Beginners' Guide]]<br />
[[sv:Nybörjarguiden]]<br />
[[tr:Yeni başlayanlar rehberi]]<br />
[[uk:Beginners' Guide]]<br />
[[zh-CN:Beginners' guide]]<br />
[[zh-TW:Beginners' Guide]]<br />
{{Related articles start}}<br />
{{Related|:Category:Accessibility}}<br />
{{Related|Installation guide}}<br />
{{Related|Diskless system}}<br />
{{Related|Install from SSH}}<br />
{{Related|General recommendations}}<br />
{{Related|General troubleshooting}}<br />
{{Related articles end}}<br />
This document will guide you through the process of installing [[Arch Linux]] using the [https://projects.archlinux.org/arch-install-scripts.git/ Arch Install Scripts]. Before installing, you are advised to skim over the [[FAQ]].<br />
<br />
The community-maintained [[Main page|ArchWiki]] is the primary resource that should be consulted if issues arise. The [[IRC channel]] (irc://irc.freenode.net/#archlinux) and the [https://bbs.archlinux.org/ forums] are also excellent resources if an answer cannot be found elsewhere. In accordance with [[the Arch Way]], you are encouraged to type {{ic|man ''command''}} to read the [[man page]] of any command you are unfamiliar with.<br />
<br />
== Minimum system requirements ==<br />
<br />
Arch Linux should run on any [[Wikipedia:P6 (microarchitecture)|i686]] compatible machine with a minimum of 256 MB RAM. A basic installation with all packages from the {{Grp|base}} group should take less than 800 MB of disk space. If you are working with limited space, this can be trimmed down considerably, but you will have to know what you are doing.<br />
<br />
== Prepare the latest installation medium ==<br />
<br />
{{Tip|Compared to the regular ISO images, the [https://downloads.archlinux.de/iso/archboot/latest archboot] images can take several steps explained in this guide [[Archboot#Interactive_setup_features|interactively]]. See [[Archboot]] for details.}}<br />
<br />
The installation media and their [[GnuPG]] signatures can be acquired from the [https://archlinux.org/download/ Download] page. The single ISO image supports both 32bit and 64bit systems; this guide assumes you use the latest available version.<br />
<br />
It is highly recommended to verify the image signature before use, ''especially when downloading from an HTTP mirror'', as these are run by volunteers who could theoretically serve malicious images. [http://www.cs.arizona.edu/stork/packagemanagersecurity/attacks-on-package-managers.html#explanation] On a system with GnuPG installed, do this by downloading the ''PGP signature'' (under ''Checksums'') to the ISO directory, and run:<br />
<br />
$ gpg --verify archlinux-''version''-dual.iso.sig<br />
<br />
If the public key is not found, [[GnuPG#Import key|import]] it with {{ic|gpg --recv-keys ''key-id''}}. <br />
<br />
Alternatively, run from an existing Arch Linux installation:<br />
<br />
$ pacman-key -v archlinux-''version''-dual.iso.sig<br />
<br />
Now choose one of the methods from the table below to [[#Boot the installation medium]] on the target machine(s). As the installation process retrieves packages from a remote repository, these methods require an internet connection; see [[Offline installation of packages]] when none is available.<br />
<br />
{| class="wikitable"<br />
! Method<br />
! Articles<br />
! Conditions<br />
|-<br />
| Write the image on flash media or optical disc, then boot from it.<br />
|<br />
* [[USB flash installation media]]<br />
* [[Optical disc drive#Burning]]<br />
|<br />
* Installation on one, or a few machines at most<br />
* Obtain a directly bootable system<br />
|-<br />
| Mount the image on a server machine and have clients boot it over the network.<br />
|<br />
* [[PXE]]<br />
* [[Diskless system]]<br />
|<br />
* Client-server model<br />
* Wired (1Gbit+) network connection<br />
|-<br />
| Mount the image in a running Linux system and install Arch from a chroot environment.<br />
|<br />
* [[Install from existing Linux]]<br />
* [[Install from SSH]]<br />
|<br />
* Replace an existing system with reduced downtime<br />
* Install on the local machine, or a remote one via [[VNC]] or [[SSH]]<br />
|-<br />
| Set up a virtual machine and install Arch as a guest system.<br />
|<br />
* [[:Category:Hypervisors]]<br />
* [[Moving an existing install into (or out of) a virtual machine]]<br />
|<br />
* Operating system compatible with virtualization software<br />
* Obtain an isolated system for learning, testing or debugging<br />
|}<br />
<br />
== Boot the installation medium ==<br />
<br />
Point the current boot device to the media containing the Arch installation media. This is typically achieved by pressing a key during the [[Wikipedia:Power-on self test|POST]] phase, as indicated on the splash screen. Refer to your motherboard's manual for details.<br />
<br />
When the Arch menu appears, select "Boot Arch Linux" and press {{ic|Enter}} to enter the live environment where you will perform the actual installation.<br />
<br />
You will be presented with a [[Zsh]] shell prompt, logged in as the root user. ''Zsh'' provides advanced tab completion and other features as part of the [http://grml.org/zsh/ grml config]. For editing text files, the console editor [[nano#Usage|nano]] is suggested.<br />
<br />
=== Booting into UEFI mode ===<br />
<br />
{{Warning|While the choice to install in EFI mode is forward looking, early vendor UEFI implementations carried more bugs than their BIOS counterparts. It is advised to do a search relating your particular mainboard model before proceeding.}}<br />
<br />
In case you have a [[Unified Extensible Firmware Interface|UEFI]] motherboard with UEFI mode enabled, the CD/USB will automatically launch Arch Linux via [[Gummiboot]] and present the following menu:<br />
<br />
{{bc|<br />
Arch Linux archiso x86_64 UEFI USB<br />
UEFI Shell x86_64 v1<br />
UEFI Shell x86_64 v2<br />
EFI Default Loader}}<br />
<br />
To verify you are booted in UEFI mode, run:<br />
<br />
# efivar -l<br />
<br />
Should ''efivar'' not list the UEFI variables properly, check if all [[UEFI#Requirements_for_UEFI_variable_support|requirements]] are met.<br />
<br />
=== Troubleshooting boot problems ===<br />
<br />
* If you are using an Intel video chipset and the screen goes blank during the boot process, the problem is likely an issue with [[Kernel mode setting]]. A possible workaround may be achieved by rebooting and pressing {{ic|Tab}} over the entry that you are trying to boot (i686 or x86_64). At the end of the string type {{ic|nomodeset}} and press {{ic|Enter}}. Alternatively, try {{ic|1=video=SVIDEO-1:d}} which, if it works, will not disable kernel mode setting. You can also try {{ic|1=i915.modeset=0}}. See the [[Intel]] article for more information.<br />
* If the screen does ''not'' go blank and the boot process gets stuck while trying to load the kernel, press {{ic|Tab}} while hovering over the menu entry, type {{ic|1=acpi=off}} at the end of the string and press {{ic|Enter}}.<br />
<br />
== Keyboard layout ==<br />
<br />
{{Note|Changes here ''only'' affect the installation process.}}<br />
<br />
The default keyboard layout is set to [[Wikipedia:File:KB United States-NoAltGr.svg|US]], the [[locale]] to {{ic|en_US.UTF-8}}. To change the keyboard layout, run:<br />
<br />
# loadkeys ''layout''<br />
<br />
where ''layout'' is a two-letter [[Wikipedia:ISO 3166-1 alpha-2#Officially assigned code elements|country code]]. Use {{ic|localectl list-keymaps}} to list all available keymaps.<br />
<br />
If certain special characters appear as white squares or other symboles, you may wish to change the console font. See [[Fonts#Previewing_and_testing]] for details.<br />
<br />
== Establish an internet connection ==<br />
<br />
{{Warning|As of [http://cgit.freedesktop.org/systemd/systemd/tree/NEWS?id&#61;dee4c244254bb49d1ffa8bd7171ae9cce596d2d0 v197], udev no longer assigns network interface names according to the ''wlanX'' and ''ethX'' naming scheme. If you are coming from a different distribution or are reinstalling Arch and not aware of the new interface naming style, please do not assume that your wireless interface is named ''wlan0'', or that your wired interface is named ''eth0''. You can use the command {{ic|ip link}} to discover the names of your interfaces.}}<br />
<br />
{{Tip|The ''elinks'' browser is available in the live system: it can be useful for example to authenticate in RADIUS-protected networks.}}<br />
<br />
The ''dhcpcd'' network daemon starts automatically during boot and it will attempt to start a wired connection. Try to ping a server to see if a connection was established. For example, Google's webservers:<br />
<br />
{{hc|# ping -c 3 www.google.com|2=<br />
PING www.l.google.com (74.125.132.105) 56(84) bytes of data.<br />
64 bytes from wb-in-f105.1e100.net (74.125.132.105): icmp_req=1 ttl=50 time=17.0 ms<br />
64 bytes from wb-in-f105.1e100.net (74.125.132.105): icmp_req=2 ttl=50 time=18.2 ms<br />
64 bytes from wb-in-f105.1e100.net (74.125.132.105): icmp_req=3 ttl=50 time=16.6 ms<br />
<br />
--- www.l.google.com ping statistics ---<br />
3 packets transmitted, 3 received, 0% packet loss, time 2003ms<br />
rtt min/avg/max/mdev = 16.660/17.320/18.254/0.678 ms<br />
}}<br />
<br />
If you get a {{ic|ping: unknown host}} error, first check if there is an issue with your cable or wireless signal strength. If not, you will need to set up the network manually, as explained below. Once a connection is established move on to [[#Prepare the storage devices]].<br />
<br />
=== Static IP ===<br />
<br />
Follow this procedure if you need to set up a wired connection via a static IP address.<br />
<br />
Identify the name of your ethernet interface:<br />
<br />
{{hc|# ip link|<br />
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT<br />
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00<br />
2: enp2s0f0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN mode DEFAULT qlen 1000<br />
link/ether 00:11:25:31:69:20 brd ff:ff:ff:ff:ff:ff<br />
3: wlp3s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP mode DORMANT qlen 1000<br />
link/ether 01:02:03:04:05:06 brd ff:ff:ff:ff:ff:ff<br />
}}<br />
<br />
In this example, the ethernet interface is {{ic|enp2s0f0}}. If you are unsure, your ethernet interface is likely to start with the letter "e", and unlikely to be "lo" or start with the letter "w".<br />
<br />
See [[Network_configuration#Static_IP_address]] for required settings. Configure a static profile for ''dhcpcd'' in {{ic|/etc/dhcpcd.conf}} with your settings, for example: <br />
<br />
interface enp2s0f0<br />
static ip_address=192.168.0.10/24<br />
static routers=192.168.0.1<br />
static domain_name_servers=192.168.0.1 8.8.8.8<br />
<br />
Restart {{ic|dhcpcd.service}}:<br />
<br />
# systemctl restart dhcpcd.service<br />
<br />
You should now have a working network connection. If you do not, see [[Network configuration]] page.<br />
<br />
=== Wireless ===<br />
<br />
{{Warning|Wireless chipset firmware packages (for cards which require them) are pre-installed under {{ic|/usr/lib/firmware}} in the live environment (on CD/USB stick) '''but must be explicitly installed to your actual system to provide wireless functionality after you reboot into it!''' Package installation is covered later in this guide. Ensure installation of both your wireless module and firmware before rebooting! See [[Wireless network configuration]] if you are unsure about the requirement of corresponding firmware installation for your particular chipset.}}<br />
<br />
Use [[netctl]]'s ''wifi-menu'' to connect to a wireless network:<br />
<br />
# wifi-menu<br />
<br />
This should bring you a menu of wifi networks if your computer has only one Wi-Fi device (mostly the case in laptops).<br />
<br />
If your computer has more than one Wi-Fi device, you need to choose one and pass its interface name to ''wifi-menu''. First, identify the name of the needed interface:<br />
<br />
{{hc|# iw dev|2=<br />
phy#0<br />
Interface wlp3s0<br />
ifindex 3<br />
wdev 0x1<br />
addr 00:11:22:33:44:55<br />
type managed<br />
}}<br />
<br />
This example shows {{ic|wlp3s0}} as the only available wireless interface, for simplicity. If you are unsure, wireless interfaces are likely to start with the letter "w", and unlikely to be "lo" or start with the letter "e".<br />
<br />
Now try ''wifi-menu'' again by passing it the interface name:<br />
<br />
# wifi-menu wlp3s0<br />
<br />
See the sample configuration in [[WPA2 Enterprise#netctl]] for networks that require both a username and password.<br />
<br />
You should now have a working wireless network connection. If you do not or even failed to identify the wireless interface, see [[#Without wifi-menu]] below or the detailed [[Wireless network configuration]] page.<br />
<br />
==== Without wifi-menu ====<br />
<br />
Bring the interface up with:<br />
<br />
# ip link set wlp3s0 up<br />
<br />
To verify that the interface is up, inspect the output of the following command:<br />
<br />
{{hc|# ip link show wlp3s0|<br />
3: wlp3s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state DOWN mode DORMANT group default qlen 1000<br />
link/ether 00:11:22:33:44:55 brd ff:ff:ff:ff:ff:ff<br />
}}<br />
<br />
The {{ic|UP}} in {{ic|<BROADCAST,MULTICAST,UP,LOWER_UP>}} is what indicates the interface is up, not the later {{ic|state DOWN}}.<br />
<br />
Most wireless chipsets require firmware in addition to a corresponding driver. The kernel tries to identify and load both automatically. If you get output like {{ic|SIOCSIFFLAGS: No such file or directory}}, this means you will need to manually load the firmware. If unsure, invoke ''dmesg'' to query the kernel log for a firmware request from the wireless chipset. For example, if you have an Intel chipset which requires and has requested firmware from the kernel at boot:<br />
<br />
{{hc|<nowiki># dmesg | grep firmware</nowiki>|<br />
firmware: requesting iwlwifi-5000-1.ucode<br />
}}<br />
<br />
If there is no output, it may be concluded that the system's wireless chipset does not require firmware.<br />
<br />
Next, scan for available networks using {{ic|iw dev wlp3s0 scan <nowiki>|</nowiki> grep SSID}}, then connect to a network with:<br />
<br />
# wpa_supplicant -B -i wlp3s0 -c <(wpa_passphrase "''ssid''" "''psk''")<br />
<br />
You need to replace {{ic|''ssid''}} with the name of your network and {{ic|''psk''}} with your wireless password, '''leaving the quotes around the network name and password'''.<br />
<br />
Finally, you have to give your interface an IP address. This can be set manually or using dhcp:<br />
<br />
# dhcpcd wlp3s0<br />
<br />
If that does not work, issue the following commands:<br />
<br />
# echo 'ctrl_interface=DIR=/run/wpa_supplicant' > /etc/wpa_supplicant.conf<br />
# wpa_passphrase "''ssid''" "''psk''" >> /etc/wpa_supplicant.conf<br />
# ip link set ''interface'' up<br />
# wpa_supplicant -B -D nl80211,wext -c /etc/wpa_supplicant.conf -i ''interface''<br />
# dhcpcd -A ''interface''<br />
<br />
Setting the interface up at step 3 may not be needed, but does no harm in any case.<br />
<br />
=== Analog modem, ISDN, or PPPoE DSL ===<br />
<br />
For xDSL, dial-up, and ISDN connections, see [[Direct Modem Connection]].<br />
<br />
=== Behind a proxy server ===<br />
<br />
If you are behind a proxy server, you will need to export the {{ic|http_proxy}} and {{ic|ftp_proxy}} environment variables. See [[Proxy settings]] for more information.<br />
<br />
== Prepare the storage devices ==<br />
<br />
In this step, the storage devices that will be used by the new system will be prepared. Read [[Partitioning]] for a more general overview.<br />
<br />
{{Warning|Partitioning will destroy existing data. Before proceeding, you '''must''' backup all data that needs to be preserved.}}<br />
<br />
{{Tip|<br />
* Users intending to create stacked block devices for [[LVM]], [[disk encryption]] or [[RAID]], should keep those instructions into consideration when preparing the partitions.<br />
* If intending to install to a USB flash key, see [[Installing Arch Linux on a USB key]].}}<br />
<br />
=== Identify the devices ===<br />
<br />
The first step is identify the devices where the new system will be installed. The following command will show all the available devices:<br />
<br />
# lsblk<br />
<br />
This will list all devices connected to your system along with their partition schemes, including that used to host and boot live Arch installation media (e.g. a USB drive). Not all devices listed will therefore be viable or appropriate mediums for installation. To filter out inappropriate results, the command can optionally be amended as follows:<br />
<br />
# lsblk | grep -v "rom\|loop\|airoot"<br />
<br />
Devices (e.g. hard disks) will be listed as {{ic|sd''x''}}, where {{ic|''x''}} is a lower-case letter starting from {{ic|a}} for the first device ({{ic|sda}}), {{ic|b}} for the second device ({{ic|sdb}}), and so on. Existing partitions on those devices will be listed as {{ic|sd''xY''}}, where {{ic|''Y''}} is a number starting from {{ic|1}} for the first partition, {{ic|2}} for the second, and so on. In the example below, only one device is available ({{ic|sda}}), and that device uses only one partition ({{ic|sda1}}):<br />
<br />
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT<br />
sda 8:0 0 80G 0 disk<br />
└─sda1 8:1 0 80G 0 part<br />
<br />
The {{ic|sd''xY''}} convention will be used in the examples provided below for partition tables, partitions, and file systems. As they are just examples, it is important to ensure that any necessary changes to device names, partition numbers, and/or partition sizes (etc.) are made. Do not just blindly copy and paste the commands.<br />
<br />
If the existing partition scheme needs not be changed, skip to [[#Create filesystems]], otherwise continue reading the following section.<br />
<br />
=== Partition table types ===<br />
<br />
If you are installing alongside an existing installation (i.e. dual-booting), a partition table will already be in use. If the devices are not partitioned, or the current partitions table or scheme needs to be changed, you will first have to determine the partition tables (one for each device) in use or to be used.<br />
<br />
{{Warning|If Arch and Windows are dual-booting from same device, then Arch '''must''' follow the same firmware boot mode and partitioning combination already used, or Windows will fail to boot. See [[Windows and Arch Dual Boot#Important information]] for more details.}}<br />
<br />
There are two types of partition table:<br />
<br />
* [[Master Boot Record| MBR]]: Intended for BIOS systems (also referred to as "msdos")<br />
* [[GUID Partition Table| GPT]]: Intended for UEFI systems<br />
<br />
Any existing partition table can be identified with the following command for each device:<br />
<br />
# parted /dev/sd''x'' print<br />
<br />
=== Partitioning tools ===<br />
<br />
For each device to be partitioned, a proper tool must be chosen according to the partition table to be used. Several partitioning tools are provided by the Arch installation medium, including:<br />
<br />
* [[parted]]: MBR and GPT<br />
* [[Partitioning#Fdisk usage summary|fdisk]], '''cfdisk''', '''sfdisk''': MBR and GPT<br />
* [[Partitioning#Gdisk usage summary|gdisk]], '''cgdisk''', '''sgdisk''': GPT<br />
<br />
{{Warning|Using a partitioning tool that is incompatible with your partition table type will likely result in the destruction of that table, along with any existing partitions/data.}}<br />
<br />
{{Tip|The devices may also be partitioned before booting the Arch installation media, possibly using alternative live systems with other partitioning tools. For example beginners might find it easier to use a graphical partitioning tool such as [[GParted]], which is also provided as a [http://gparted.sourceforge.net/livecd.php live CD] and works with both MBR and GPT partition tables.}}<br />
<br />
==== Using parted in interactive mode ====<br />
<br />
All the examples provided below make use of ''parted'', as it can be used for both BIOS/MBR and UEFI/GPT. It will be launched in ''interactive mode'', which simplifies the partitioning process and reduces unnecessary repetition by automatically applying all partitioning commands to the specified device.<br />
<br />
In order to start operating on a device, execute:<br />
<br />
# parted /dev/sd''x''<br />
<br />
You will notice that the command-line prompt changes from a hash ({{ic|#}}) to {{ic|(parted)}}: this also means that the new prompt is not a command to be manually entered when running the commands in the examples.<br />
<br />
To see a list of the available commands, enter:<br />
<br />
(parted) help<br />
<br />
When finished, or if wishing to implement a partition table or scheme for another device, exit from parted with:<br />
<br />
(parted) quit<br />
<br />
After exiting, the command-line prompt will change back to {{ic|#}}.<br />
<br />
=== Create new partition table ===<br />
<br />
You need to (re)create the partition table of a device when it has never been partitioned before, or when you want to change the type of its partition table. Recreating the partition table of a device is also useful when the partition scheme needs to be restructured from scratch.<br />
<br />
{{Warning|<br />
* If dual-booting with an existing installation of Windows on a UEFI/GPT system, do not erase the partition table. Doing so will destroy all existing data on the device, including the UEFI partition with the Windows ''.efi'' file required to boot it.<br />
* MBR is designed specifically for use with BIOS systems, and GPT is designed for UEFI. It is not recommended for less experienced users to break this convention as both have features and/or limitations that may be incompatible with your hardware (e.g. MBR cannot cope with devices larger than 2 TiB). [https://www.happyassassin.net/2014/01/25/uefi-boot-how-does-that-actually-work-then/] If for any reason you do not wish to follow this convention, see [http://mjg59.dreamwidth.org/8035.html] and [http://rodsbooks.com/gdisk/bios.html] for more information and possible workarounds.}}<br />
<br />
Open each device whose partition table must be (re)created with:<br />
<br />
# parted /dev/sd''x''<br />
<br />
To then create a new MBR/msdos partition table for BIOS systems, use the following command:<br />
<br />
(parted) mklabel msdos<br />
<br />
To create a new GPT partition table for UEFI systems instead, use:<br />
<br />
(parted) mklabel gpt<br />
<br />
=== Partition schemes ===<br />
<br />
You can decide the number and size of the partitions the devices should be split into, and which directories will be used to mount the partitions in the installed system (also known as ''mount points''). The mapping from partitions to directories is the [[Partitioning#Partition scheme|partition scheme]], which must comply with the following requirements:<br />
<br />
* At least a partition for the {{ic|/}} (''root'') directory '''must''' be created.<br />
* Depending on the motherboard's firmware interface, the chosen [[#Partition table types]], and in some cases also the chosen [[boot loader]], the following additional partitions '''must''' be created:<br />
** '''BIOS/MBR''': no additional partition required.<br />
** '''UEFI/GPT''': one [[Unified Extensible Firmware Interface#EFI System Partition|EFI System Partition]].<br />
<br />
In the examples below it is assumed that a new and contiguous partitioning scheme is applied to a single device. Some optional partitions will also be created for the {{ic|/boot}} and {{ic|/home}} directories: see also [[Arch filesystem hierarchy]] for an explanation of the purpose of the various directories; if separate partitions for directories like {{ic|/boot}} or {{ic|/home}} are not created, these will simply be contained in the {{ic|/}} partition. Also the creation of an optional partiton for [[swap space]] will be illustrated.<br />
<br />
If not already open in a ''parted'' interactive session, open each device to be partitioned with:<br />
<br />
# parted /dev/sd''x''<br />
<br />
The following command will be used to create partitions:<br />
<br />
(parted) mkpart ''part-type'' ''fs-type'' ''start'' ''end''<br />
<br />
* {{ic|''part-type''}} is one of {{ic|primary}}, {{ic|extended}} or {{ic|logical}}, and is meaningful only for MBR partition tables.<br />
* {{ic|''fs-type''}} is one of the supported file systems listed in the [http://www.gnu.org/software/parted/manual/parted.html#mkpart manual]. The partition will be properly formatted in [[#Create filesystems]].<br />
* {{ic|''start''}} is the beginning of the partition from the start of the device. It consists of a number followed by a [http://www.gnu.org/software/parted/manual/parted.html#unit unit], for example {{ic|1M}} means start at 1MiB.<br />
* {{ic|''end''}} is the end of the partition from the start of the device (''not'' from the {{ic|''start''}} value). It has the same syntax as {{ic|''start''}}, for example {{ic|100%}} means end at the end of the device (use all the remaining space).<br />
<br />
{{Warning|It is important that the partitions do not overlap each other: if you do not want to leave unused space in the device, make sure that each partition starts where the previous one ends.}}<br />
<br />
{{Note|''parted'' may issue a warning like:<br />
<br />
Warning: The resulting partition is not properly aligned for best performance.<br />
Ignore/Cancel?<br />
<br />
In this case, read [[Partitioning#Partition alignment]] and follow [[GNU Parted#Alignment]] to fix it.}}<br />
<br />
The following command will be used to flag the partition that contains the {{ic|/boot}} directory as bootable:<br />
<br />
(parted) set ''partition'' boot on<br />
<br />
* {{ic|''partition''}} is the number of the partition to be flagged (see the output of the {{ic|print}} command).<br />
<br />
==== UEFI/GPT examples ====<br />
<br />
In every instance, a special bootable [[Unified Extensible Firmware Interface#EFI System Partition|EFI System Partition]] is required.<br />
<br />
{{Warning|If dual-booting with an existing installation of Windows on a UEFI/GPT system, the existing UEFI partition must not be deleted. Doing so will destroy the ''.efi'' file required to boot Windows.}}<br />
<br />
If creating a new EFI System Partition, use the following commands (the recommended size is 512MiB):<br />
<br />
(parted) mkpart ESP fat32 1MiB 513MiB<br />
(parted) set 1 boot on<br />
<br />
The remaining partition scheme is entirely up to you. For one other partition using 100% of remaining space:<br />
<br />
(parted) mkpart primary ext3 513MiB 100%<br />
<br />
For separate {{ic|/}} (20GiB) and {{ic|/home}} (all remaining space) partitions:<br />
<br />
(parted) mkpart primary ext3 513MiB 20.5GiB<br />
(parted) mkpart primary ext3 20.5GiB 100%<br />
<br />
And for separate {{ic|/}} (20GiB), swap (4GiB), and {{ic|/home}} (all remaining space) partitions:<br />
<br />
(parted) mkpart primary ext3 513MiB 20.5GiB<br />
(parted) mkpart primary linux-swap 20.5GiB 24.5GiB<br />
(parted) mkpart primary ext3 24.5GiB 100%<br />
<br />
==== BIOS/MBR examples ====<br />
<br />
For a minimum single primary partition using all available disk space, the following command would be used:<br />
<br />
(parted) mkpart primary ext3 1M 100%<br />
(parted) set 1 boot on<br />
<br />
In the following instance, a 20Gib {{ic|/}} partition will be created, followed by a {{ic|/home}} partition using all the remaining space:<br />
<br />
(parted) mkpart primary ext3 1M 20G<br />
(parted) set 1 boot on<br />
(parted) mkpart primary ext3 20G 100%<br />
<br />
In the final example below, separate {{ic|/boot}} (100MiB), {{ic|/}} (20Gib), swap (4GiB), and {{ic|/home}} (all remaining space) partitions will be created:<br />
<br />
(parted) mkpart primary ext3 1M 100M<br />
(parted) set 1 boot on<br />
(parted) mkpart primary ext3 100M 20G<br />
(parted) mkpart primary linux-swap 20G 24G<br />
(parted) mkpart primary ext3 24G 100%<br />
<br />
=== Create filesystems ===<br />
<br />
Once the partitions have been created, each must be formatted with an appropriate [[file system]], ''except'' for swap partitions. All available partitions on the intended installation device can be listed with the following command:<br />
<br />
# lsblk /dev/sd''x''<br />
<br />
With the exceptions noted below, it is recommended to use the {{ic|ext4}} file system:<br />
<br />
# mkfs.ext4 /dev/sd''xY''<br />
<br />
{{Warning|<br />
* If dual-booting with an existing installation of Windows on a UEFI/GPT system, do not re-format the UEFI partition. Doing so will destroy all existing data on that partition, including the Windows ''.efi'' file required to boot it.<br />
* If a new UEFI system partition has been created on a UEFI/GPT system, it must be formatted with a {{ic|fat32}} or {{ic|vfat32}} file system. Failure to do so will result in an unbootable installation:<br />
:{{bc|# mkfs.vfat -F32 /dev/sd''xY''}}}}<br />
<br />
=== Activate swap ===<br />
<br />
If a swap partition has been created, it must be set up and activated with:<br />
<br />
# mkswap /dev/sd''xY''<br />
# swapon /dev/sd''xY''<br />
<br />
=== Mount the partitions ===<br />
<br />
{{Note|Swap partitions must '''not''' be mounted here.}}<br />
<br />
The {{ic|/}} (root) partition must be mounted '''first''': this is because any directories such as {{ic|/boot}} or {{ic|/home}} that have separate partitions will have to be created in the root file system. The {{ic|/mnt}} directory of the live system will be used to mount the root partition, and consequently all the other partitions will stem from there. If the root partition's name is {{ic|sd''xR''}}, do:<br />
<br />
# mount /dev/sd''xR'' /mnt<br />
<br />
Once the {{ic|/}} partition has been mounted, any remaining partitions may be mounted in any order. The general procedure is to first create the mount point, and then mount the partition to it. If using a separate {{ic|/boot}} partition:<br />
<br />
# mkdir -p /mnt/boot<br />
# mount /dev/sd''xB'' /mnt/boot<br />
<br />
{{Note|Using {{ic|/boot}} is recommended also for mounting the EFI System Partition on UEFI/GPT system. See [[EFISTUB]] and related articles for alternatives.}}<br />
<br />
If using a separate {{ic|/home}} partition:<br />
<br />
# mkdir -p /mnt/home<br />
# mount /dev/sd''xH'' /mnt/home<br />
<br />
Once all the remaining partitions, if any, have been mounted, the devices are ready to install Arch.<br />
<br />
== Select a mirror ==<br />
<br />
You may want to edit the {{ic|mirrorlist}} file and place your preferred mirror first. A copy of this file will be installed on your new system by ''pacstrap'' as well, so it is worth getting it right.<br />
<br />
{{hc|# nano /etc/pacman.d/mirrorlist|<br />
##<br />
## Arch Linux repository mirrorlist<br />
## Sorted by mirror score from mirror status page<br />
## Generated on YYYY-MM-DD<br />
##<br />
<br />
<nowiki>Server = http://mirror.example.xyz/archlinux/$repo/os/$arch</nowiki><br />
...}}<br />
<br />
If you want, you can make it the ''only'' mirror available by deleting all other lines, but it is usually a good idea to have a few more, in case the first one goes offline. Should you change your mirror list at a later stage, refresh all package lists with {{ic|pacman -Syyu}}. See [[Mirrors]] for more information.<br />
<br />
== Install the base system ==<br />
<br />
The base system is installed using the ''pacstrap'' script. The {{ic|-i}} switch can be omitted if you wish to install every package from the {{Grp|base}} group without prompting. To build packages from the [[AUR]] or with [[ABS]], you will also need the {{Grp|base-devel}} group.<br />
<br />
# pacstrap -i /mnt base base-devel<br />
<br />
Other packages can be installed later using [[pacman]].<br />
<br />
See [[Pacman#Troubleshooting]] and [[Pacman-key#Troubleshooting]] in case of errors.<br />
<br />
== Generate an fstab ==<br />
<br />
[[Wikipedia:Universally_unique_identifier|UUID]]s are used because they have certain advantages (see [[fstab#Identifying filesystems]]). If you prefer labels instead, replace the {{ic|-U}} option with {{ic|-L}}:<br />
<br />
# genfstab -U -p /mnt >> /mnt/etc/fstab<br />
# nano /mnt/etc/fstab<br />
<br />
{{Warning|The {{ic|fstab}} file should always be checked after generating it. If you encounter errors running ''genfstab'' or later in the install process, do '''not''' run ''genfstab'' again; just edit the {{ic|fstab}} file. See [[fstab#Field definitions]] for syntax information.}}<br />
<br />
== Chroot and configure the base system ==<br />
<br />
Next, [[Change root|chroot]] into your newly installed system:<br />
<br />
# arch-chroot /mnt /bin/bash<br />
<br />
At this stage of the installation, you will configure the primary configuration files of your Arch Linux base system. These can either be created if they do not exist, or edited if you wish to change the defaults.<br />
<br />
Closely following and understanding these steps is of key importance to ensure a properly configured system.<br />
<br />
{{Warning|Do not assume that the tools you used from the ISO are automatically installed. For example, if you used ''wifi-menu'' to gain network access during the installation and want to continue so after the first boot, you will have to install ''dialog'' to use it. The following section specifies such cases, do follow it closely to avoid a hiccup in your fresh install.}}<br />
<br />
=== Locale ===<br />
<br />
Locales define which language the system uses and other regional considerations, such as currency denomination, numerology and character sets. Possible values are listed in {{ic|/etc/locale.gen}}, with the active locale defined in {{ic|locale.conf}} files.<br />
<br />
All entries in {{ic|locale.gen}} are commented out (preceded by {{ic|#}}) by default. Uncomment {{ic|en_US.UTF-8 UTF-8}}, as well as other needed localisations. {{ic|UTF-8}} is highly recommended over other options.<br />
<br />
{{hc|# nano /etc/locale.gen|<br />
...<br />
#en_SG ISO-8859-1<br />
en_US.UTF-8 UTF-8<br />
#en_US ISO-8859-1<br />
...<br />
}}<br />
<br />
Before locales can be enabled, they must be ''generated'':<br />
<br />
# locale-gen<br />
<br />
Create {{ic|/etc/locale.conf}}, where {{ic|LANG}} refers to the first column of an uncommented entry in {{ic|/etc/locale.gen}}.<br />
<br />
# echo LANG=''en_US.UTF-8'' > /etc/locale.conf<br />
<br />
Export the chosen locale:<br />
<br />
# export LANG=''en_US.UTF-8''<br />
<br />
{{Note|<br />
* Choosing {{ic|en_US.UTF-8}} as the system locale allows to keep system logs in English for easier troubleshooting. Users may override this setting for their session as described in [[Locale#Setting the locale]].<br />
* {{ic|LANG}} acts as the default value for the locale-related {{ic|LC_*}} variables. To use other locales for these variables, run ''locale'' to see the available options and add them to {{ic|locale.conf}}. It is not recommended to set the {{ic|LC_ALL}} variable. See [[Locale]] for details.}}<br />
<br />
=== Console font and keymap ===<br />
<br />
If you changed the default console keymap and font in [[#Keyboard layout]], create {{ic|/etc/vconsole.conf}} to make those changes persist in the installed system. It is important {{ic|KEYMAP}} matches the value initially set with {{ic|loadkeys}}, to ensure correct entry of [[#Set the root password|the root password]] on reboot.<br />
<br />
{{hc|# nano /etc/vconsole.conf|2=<br />
KEYMAP=''de-latin1''<br />
FONT=''lat9w-16''<br />
}}<br />
<br />
These settings only apply to virtual consoles, not [[Xorg]]. See [[Fonts#Console fonts]] for more information.<br />
<br />
=== Time zone ===<br />
<br />
Available time zones and subzones can be found in the {{ic|/usr/share/zoneinfo/''Zone''/''SubZone''}} directories, and listed with the ''ls'' command. Create a symbolic link {{ic|/etc/localtime}} to your subzone file {{ic|/usr/share/zoneinfo/''Zone''/''SubZone''}}:<br />
<br />
# ln -s /usr/share/zoneinfo/''Zone''/''SubZone'' /etc/localtime<br />
<br />
You may use [http://tldp.org/LDP/abs/html/tabexpansion.html tab completion] to show available zones and subzones. Example:<br />
<br />
# ln -s /usr/share/zoneinfo/Europe/Minsk /etc/localtime<br />
<br />
If you get {{ic|ln: failed to create symbolic link '/etc/localtime': File exists}}, check the existing file with {{ic|ls -l /etc/localtime}} and add the {{ic|-f}} option to the ''ln'' command to overwrite it.<br />
<br />
=== Hardware clock ===<br />
<br />
If you have multiple operating systems installed in the same machine, they will all derive the current time from the same hardware clock, which must be set to either UTC or ''localtime''. For this reason you must make sure that all the operating systems see the hardware clock as providing time in the same chosen [[Time#Time standard|standard]], otherwise some of them will perform the time zone adjustement for the system clock, while others will not.<br />
<br />
In particular, it is strongly recommended to set the hardware clock to UTC, in order to avoid conflicts between the installed operating systems. For example, if the hardware clock was set to ''localtime'', more than one operating system may adjust it after a [[Wikipedia:Daylight_saving_time|DST]] change, thus resulting in an overcorrection; more problems may arise when travelling between different time zones and using one of the operating systems to reset the system/hardware clock.<br />
<br />
To set the hardware clock to UTC in Linux, run:<br />
<br />
# hwclock --systohc --utc<br />
<br />
The ''hwclock'' command also generates the {{ic|/etc/adjtime}} file.<br />
<br />
{{Note|Using UTC for the hardware clock does not mean that software will display time in UTC. However, the system setup/BIOS interface will instead: this should be neither surprising nor treated as a bug.}}<br />
<br />
{{Warning|Windows systems use ''localtime'' by default. Using ''localtime'' on Arch systems may lead to several known and unfixable bugs, but there are no plans to drop support for ''localtime''. It is, though, recommended to set Windows to use UTC instead, and prevent it from synchronising time. See [[Time#UTC in Windows]].}}<br />
<br />
=== Kernel modules ===<br />
<br />
Needed kernel modules are automatically loaded by [[udev]], so you will rarely need to load modules manually. See [[Kernel modules]] for details.<br />
<br />
=== Hostname ===<br />
<br />
Set the [[Network_configuration#Set_the_hostname|hostname]] to your liking:<br />
<br />
# echo ''myhostname'' > /etc/hostname<br />
<br />
Add the same hostname to {{ic|/etc/hosts}}:<br />
<br />
#<ip-address> <hostname.domain.org> <hostname><br />
127.0.0.1 localhost.localdomain localhost ''myhostname''<br />
::1 localhost.localdomain localhost ''myhostname''<br />
<br />
=== Configure the network ===<br />
<br />
You need to configure the network again, but this time for your newly installed environment. The procedure and prerequisites are similar to the one described [[#Establish an internet connection|above]], except we are going to make it persistent and automatically run at boot.<br />
<br />
As a first step, identify the network interface name you want to configure the connection for with {{ic|ip link}}.<br />
<br />
{{Note|<br />
* For more in-depth information on network configuration, visit [[Network configuration]] and [[Wireless network configuration]].<br />
* If you would like to use the old interface naming scheme (i.e. {{ic|eth''X''}} and {{ic|wlan''X''}}) you can accomplish this by creating an empty file at {{ic|/etc/udev/rules.d/80-net-setup-link.rules}} which will mask the file of the same name located under {{ic|/usr/lib/udev/rules.d}}.<br />
}}<br />
<br />
Now select a daemon to handle the configuration and operation. Several are listed below; only select '''one''' of them for the new system.<br />
<br />
==== Wired ====<br />
<br />
; Using dhcpcd<br />
A simple option for adapter configuration is to use the DHCP Client Daemon, the method used by default with the install medium. See [[Dhcpcd#Running]].<br />
<br />
Users requiring only '''single wired network connection''' can simply enable the ''dhcpcd'' service for the interface:<br />
<br />
# systemctl enable dhcpcd@''interface_name''.service<br />
<br />
If static IP settings are required, adjust the profile configuration as described in [[#Static IP]]. <br />
<br />
; Using systemd-networkd<br />
<br />
The Arch default init system, [[systemd]] includes built-in support for managing adapters using both DHCP and static IP setups. Configuration is simple. See [[Systemd-networkd#Required_services_and_setup]].<br />
<br />
; Using netctl<br />
<br />
Another option is [[netctl]] which is a CLI-based tool used to configure and manage network connections via user-created profiles. Create a profile as shown in [[netctl#Example profiles]], then enable it as described in [[netctl#Basic method]].<br />
<br />
==== Wireless ====<br />
<br />
All of the tools listed in [[#Wired]] above can activate wireless connections. For wireless, however, ''dhcpcd'' and ''systemd-networkd'' require a separate configuration of the connection in the wireless backend, [[wpa_supplicant]], first. If you anticipate to connect the machine to different wireless networks over time, a tool which provides its own connection management may be easier to handle. Aside from [[netctl]] introduced below, [[Wireless network configuration#Automatic setup]] lists other choices. <br />
<br />
{{Note|If your wireless adapter requires a firmware (as described in the above [[#Wireless|Establish an internet connection]] section and also in the article [[Wireless network configuration#Device driver]]), install the package containing your firmware. Most of the time, the {{Pkg|linux-firmware}} package will contain the needed firmware. Though for some devices, the required firmware might be in its own package. For example:<br />
{{bc|# pacman -S zd1211-firmware}}<br />
See [[Wireless network configuration#Installing driver/firmware]] for more info.}}<br />
<br />
Install {{Pkg|iw}} and {{Pkg|wpa_supplicant}} which you will need to connect to a network:<br />
<br />
# pacman -S iw wpa_supplicant<br />
<br />
===== Adding wireless networks =====<br />
<br />
; Using wifi-menu<br />
<br />
Install {{Pkg|dialog}}, which is required for ''wifi-menu'':<br />
<br />
# pacman -S dialog<br />
<br />
After finishing the rest of this installation and rebooting, you can connect to the network with {{ic|wifi-menu ''interface_name''}} (where {{ic|''interface_name''}} is the interface of your wireless chipset).<br />
<br />
# wifi-menu ''interface_name''<br />
<br />
{{Warning|Do not use ''wifi-menu'' now, instead wait until you have finished this guide and have rebooted. It will not work now because a process spawned by this command will conflict with the one you have running outside of the chroot. Alternatively, you could just configure a network profile manually using the following templates so that you do not have to worry about using ''wifi-menu'' at all.}}<br />
<br />
; Using manual netctl profiles<br />
<br />
Copy a network profile from {{ic|/etc/netctl/examples}} to {{ic|/etc/netctl}}:<br />
<br />
# cd /etc/netctl<br />
# cp examples/wireless-wpa my-network<br />
<br />
Edit the profile as needed (modify {{ic|Interface}}, {{ic|ESSID}} and {{ic|Key}}):<br />
<br />
# nano my-network<br />
<br />
Enable above created profile to start it at every boot:<br />
<br />
# netctl enable my-network<br />
<br />
===== Connect automatically to known networks =====<br />
<br />
{{Warning|This method cannot be used with explicitely enabled [[Netctl#Configuration|profiles]], i.e. through {{ic|netctl enable ''profile''}}.}}<br />
<br />
Install {{Pkg|wpa_actiond}}, which is required for {{ic|netctl-auto}}:<br />
<br />
# pacman -S wpa_actiond<br />
<br />
Enable the {{ic|netctl-auto}} service, which will connect to known networks and gracefully handle roaming and disconnects:<br />
<br />
# systemctl enable netctl-auto@''interface_name''.service<br />
<br />
{{Tip|[[netctl]] also provides {{ic|netctl-ifplugd}}, which can be used to handle wired profiles in conjunction with {{ic|netctl-auto}}.}}<br />
<br />
==== Analog modem, ISDN or PPPoE DSL ====<br />
<br />
For xDSL, dial-up and ISDN connections, see [[Direct Modem Connection]].<br />
<br />
=== Create an initial ramdisk environment ===<br />
<br />
{{Note|As [[mkinitcpio]] was run on installation of {{Pkg|linux}} with ''pacstrap'', most users can skip this step and use the defaults provided in {{ic|mkinitcpio.conf}}.}}<br />
<br />
Set the correct [[Mkinitcpio#HOOKS|hooks]] in {{ic|/etc/mkinitcpio.conf}} and re-generate the initramfs image:<br />
<br />
# mkinitcpio -p linux<br />
<br />
=== Set the root password ===<br />
<br />
Set the root password with:<br />
<br />
# passwd<br />
<br />
=== Install and configure a bootloader ===<br />
<br />
==== For BIOS motherboards ====<br />
<br />
For BIOS systems, several boot loaders are available, see [[Boot loaders]] for a complete list. Choose one as per your convenience. Possible choices include:<br />
<br />
* [[Syslinux#Installation]] is (currently) limited to loading only files from the partition where it was installed. Its configuration file is considered to be easier to understand. An example configuration can be found in [[Syslinux#Examples]].<br />
* [[GRUB]] is more feature-rich and supports more complex scenarios. Its configuration file(s) is more similar to 'sh' scripting language, which may be difficult for beginners to manually write. It is recommended that they automatically generate one.<br />
<br />
Here, installation with '''GRUB''' and '''MBR''' is demonstrated. <br />
<br />
Install the {{Pkg|grub}} package; to have GRUB search for other installed operating systems, install {{Pkg|os-prober}} in addition:<br />
<br />
# pacman -S grub os-prober<br />
<br />
Install the bootloader to the drive Arch was installed to (do '''not''' append a partition number, or {{ic|/dev/sda''X''}}):<br />
<br />
# grub-install --target=i386-pc --recheck ''/dev/sda''<br />
<br />
Automatically generate {{ic|grub.cfg}}:<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
{{Note|A sample {{ic|/boot/grub/grub.cfg}} is included with the {{Pkg|grub}} package, and subsequent {{ic|grub-*}} commands may not over-write it. Ensure your intended changes are in {{ic|grub.cfg}}, rather than in {{ic|grub.cfg.new}} or similar file.}}<br />
<br />
For more information on configuring and using GRUB, see [[GRUB]].<br />
<br />
==== For UEFI motherboards ====<br />
<br />
For UEFI systems, several boot loaders are available, see [[Boot loaders]] for a complete list. Choose one as per your convenience. Possible choices include:<br />
<br />
* [[gummiboot]] is a minimal UEFI Boot Manager which provides a menu for [[EFISTUB]] kernels and other UEFI applications. This is recommended for beginners, especially those wishing to dual-boot with other installed operating systems such as Windows 8.<br />
* [[GRUB#UEFI_systems|GRUB]] is a more complete bootloader, useful if you run into problems with Gummiboot.<br />
<br />
Here, installation with ''gummiboot'' is demonstrated. First install {{Pkg|dosfstools}} to manipulate the EFI System Partition post-installation, and {{Pkg|efibootmgr}} to create a UEFI boot entry (used by bootmanager installation scripts):<br />
<br />
# pacman -S dosfstools efibootmgr<br />
<br />
{{Note|<br />
* For UEFI boot, the drive needs to be GPT-partitioned and an [[Unified Extensible Firmware Interface#EFI System Partition|EFI System Partition]] (512 MiB or larger, gdisk type {{ic|EF00}}, formatted with FAT32) must be present. In the following examples, this partition is assumed to be mounted at {{ic|/boot}}. If you have followed this guide from the beginning, you have already done all of these.<br />
* It is strongly recommended to have the EFI System Partition mounted at {{ic|/boot}} as this is required to automatically update Gummiboot.<br />
}}<br />
<br />
Install the {{Pkg|gummiboot}} package and run the automated installation script, replacing {{ic|'''$esp'''}} with the location of your EFI System Partiton, usually {{ic|/boot}}:<br />
<br />
# pacman -S gummiboot<br />
# gummiboot --path='''$esp''' install<br />
<br />
Gummiboot will automatically be detected by firmware that requires that the bootable {{ic|bootx64.efi}} stub be placed in {{ic|'''$esp'''/EFI/boot}}, and will in turn automatically detect the presence of any other installed operating systems using ''.efi'' stubs. However, it will still be necessary to manually create a configuration file for Gummiboot.<br />
<br />
First, create {{ic|'''$esp'''/loader/entries/arch.conf}} and add the following, replacing {{ic|/dev/sdaX}} with your '''root''' partition (most likely {{ic|/dev/sda2}} if {{ic|/dev/sda1}} is the ESP):<br />
<br />
{{hc|# nano '''$esp'''/loader/entries/arch.conf|2=<br />
title Arch Linux<br />
linux /vmlinuz-linux<br />
initrd /initramfs-linux.img<br />
options root='''/dev/sdaX''' rw<br />
}}<br />
<br />
Second, create {{ic|'''$esp'''/loader/loader.conf}} and add the following, replacing the timeout value (in seconds) with your own choice:<br />
{{hc|# nano '''$esp'''/loader/loader.conf|2=<br />
default arch<br />
timeout 5<br />
}}<br />
<br />
See [[gummiboot]] for more information.<br />
<br />
== Unmount the partitions and reboot ==<br />
<br />
Exit from the chroot environment:<br />
<br />
# exit<br />
<br />
{{Note|While partitions are unmounted automatically by ''systemd'' on shutdown, you may do so manually with {{ic|umount -R /mnt}} as a safety measure. If the partition is "busy", you can find the cause with [[fuser]].}}<br />
<br />
Reboot the computer:<br />
<br />
# reboot<br />
<br />
Remove the installation media, or you may boot back into it. You can log into your new installation as ''root'', using the password you specified with ''passwd''.<br />
<br />
== Post-installation ==<br />
<br />
Your new Arch Linux base system is now a functional GNU/Linux environment ready to be built into whatever you wish or require for your purposes. You are now ''strongly'' advised to read the [[General recommendations]] article, especially the first two sections. Its other sections provide links to post-installation tutorials like setting up a graphical user interface, sound or a touchpad.<br />
<br />
For a list of applications that may be of interest, see [[List of applications]].</div>Fylwindhttps://wiki.archlinux.org/index.php?title=VirtualBox&diff=362628VirtualBox2015-02-25T11:04:36Z<p>Fylwind: /* Use the right front-end */ indicate command used to run the GUI</p>
<hr />
<div>[[Category:Emulators]]<br />
[[Category:Hypervisors]]<br />
[[cs:VirtualBox]]<br />
[[de:VirtualBox]]<br />
[[el:VirtualBox]]<br />
[[es:VirtualBox]]<br />
[[fr:VirtualBox]]<br />
[[hu:VirtualBox]]<br />
[[it:VirtualBox]]<br />
[[ja:VirtualBox]]<br />
[[pt:VirtualBox]]<br />
[[ru:VirtualBox]]<br />
[[zh-CN:VirtualBox]]<br />
{{Related articles start}}<br />
{{Related|:Category:Hypervisors}}<br />
{{Related|PhpVirtualBox}}<br />
{{Related|Moving an existing install into (or out of) a virtual machine}}<br />
{{Related articles end}}<br />
<br />
[https://www.virtualbox.org VirtualBox] is a [[Wikipedia:Hypervisor|hypervisor]] used to run operating systems in a special environment, called a virtual machine, on top of the existing operating system. VirtualBox is in constant development and new features are implemented continuously. It comes with a [[Qt]] GUI interface, as well as headless and [[Wikipedia:Simple DirectMedia Layer|SDL]] command-line tools for managing and running virtual machines.<br />
<br />
In order to integrate functions of the host system to the guests, including shared folders and clipboard, video acceleration and a seamless window integration mode, ''guest additions'' are provided for some guest operating systems.<br />
<br />
== Installation steps for Arch Linux hosts ==<br />
<br />
In order to launch VirtualBox virtual machines on your Arch Linux box, follow these installation steps.<br />
<br />
=== Install the core packages ===<br />
<br />
First, from the [[official repositories]], install the {{Pkg|virtualbox}} package which contains the GPL-licensed VirtualBox suite with the SDL and headless command-line tools included. The {{Pkg|virtualbox}} package comes with {{Pkg|virtualbox-host-modules}} as a required dependency. <br />
<br />
You can install the {{Pkg|qt4}} optional dependency in order to use the graphical interface which is based on [[Qt]]. This is not required if you intend to use VirtualBox in command-line only. [[#Use the right front-end|See below to learn the differences]].<br />
<br />
=== Install the VirtualBox kernel modules ===<br />
<br />
Next, to fully virtualize your guest installation, VirtualBox provides the following [[kernel modules]]: {{ic|vboxdrv}}, {{ic|vboxnetadp}}, {{ic|vboxnetflt}}, and {{ic|vboxpci}}. These must be added to your host kernel.<br />
<br />
The binary compatibility of kernel modules depends on the API of the kernel against which they have been compiled. The problem with the Linux kernel is that these interfaces might not be the same from one kernel version to another. In order to avoid compatibility problems and subtle bugs, each time the Linux kernel is upgraded, it is advised to recompile the kernel modules against the Linux kernel version that has just been installed. This is what Arch Linux packagers actually do with the VirtualBox kernel modules packages: each time a new Arch Linux kernel is released, the Virtualbox modules are upgraded accordingly.<br />
<br />
Therefore, if you are using a kernel from the [[official repositories]] or a custom one (self-compiled or installed from the [[AUR]]), the kernel module package you will need to install will thus vary.<br />
<br />
==== Hosts running an official kernel ====<br />
<br />
* If you are using the {{Pkg|linux}} kernel, make sure the {{pkg|virtualbox-host-modules}} package is still installed. The latter has been installed when you installed the {{Pkg|virtualbox}} package.<br />
* If you are using the LTS version of the kernel ({{pkg|linux-lts}}), you need to install the {{pkg|virtualbox-host-modules-lts}} package. {{Pkg|virtualbox-host-modules}} can now be removed if you want.<br />
* If you are using the {{aur|linux-ck}} kernel, build the {{aur|virtualbox-ck-host-modules}} package.<br />
<br />
==== Hosts running a custom kernel ====<br />
<br />
{{Merge|Dynamic Kernel Module Support|The general tips on DKMS usage do not belong on this page.}}<br />
<br />
If you use or intend to use a self-compiled kernel from sources, you have to know that VirtualBox does not require any virtualization modules (e.g. virtuo, kvm,...). The VirtualBox kernel modules provide all the necessary for VirtualBox to work properly. You can thus disable in your kernel ''.config'' file these virtualization modules if you do not use other hypervisors like Xen, KVM or QEMU.<br />
<br />
The {{ic|virtualbox-host-modules}} package works fine with custom kernels of the same version of the Arch Linux stock kernel such as {{AUR|linux-ck}}. Since the {{ic|virtualbox-host-modules}} comes with the official Arch Linux kernel ({{Pkg|linux}}) as a dependency and if you do not use that kernel, install {{Pkg|virtualbox-host-dkms}} instead.<br />
<br />
If you are using a custom kernel which is not of the same version of the Arch Linux stock one, you will have to install the {{Pkg|virtualbox-host-dkms}} too. The latter comes bundled with the source of the VirtualBox kernel modules that will be compiled to generate these modules for your kernel.<br />
<br />
As the {{Pkg|virtualbox-host-dkms}} package requires compilation, make sure you have the kernel headers corresponding to your custom kernel version to prevent this error from happening {{ic|Your kernel headers for kernel ''your custom kernel version'' cannot be found at /usr/lib/modules/''your custom kernel version''/build or /usr/lib/modules/''your custom kernel version''/source}}.<br />
* If you use a self-compiled kernel and have used {{ic|make modules_install}} to install its modules, folders {{ic|/usr/lib/modules/''your custom kernel version''/build}} and {{ic|(...)/source}} will be symlinked to your kernel sources. These will act as the kernel headers you need. If you have not removed these kernel sources yet, you have nothing to do.<br />
* If you use a custom kernel from [[AUR]], make sure the package {{Pkg|linux-headers}} is installed.<br />
<br />
Once {{Pkg|virtualbox-host-dkms}} is installed, simply generate the kernel modules for your custom kernel by running the following command structure:<br />
# dkms install vboxhost/''virtualbox-host-source version'' -k ''your custom kernel version''/''your architecture''<br />
<br />
{{Tip|Use this all-in-one command instead, if you do not want to adapt the above command:<br />
{{bc|<nowiki># dkms install vboxhost/$(pacman -Q virtualbox|awk '{print $2}'|sed 's/\-.\+//') -k $(uname -rm|sed 's/\ /\//')</nowiki>}}<br />
}}<br />
<br />
To automatically recompile the VirtualBox kernel modules when their sources get upgraded (i.e. when the {{Pkg|virtualbox-host-dkms}} package gets upgraded) and avoid to type again the above {{ic|dkms install}} command manually afterwards, enable the {{ic|dkms}} service with:<br />
# systemctl enable dkms.service<br />
<br />
If this service is not enabled while the {{Pkg|virtualbox-host-dkms}} package is being updated, the VirtualBox modules will not be updated and you will have to type in manually the {{ic|dkms install}} command described above to compile the latest version of the Virtualbox kernel modules. If you do not want to type in manually this command, if the {{ic|dkms}} service is automatically loaded at startup, you just need to reboot and your VirtualBox modules will be recompiled silently.<br />
<br />
However, if you want to keep this daemon disabled, you can use an [[mkinitcpio|initramfs hook]] that will automatically trigger the {{ic|dkms install}} command described above at boot time. This will require a reboot to recompile the VirtualBox modules. To enable this hook, install the {{AUR|vboxhost-hook}} package from the [[Arch User Repository|AUR]] and add {{ic|vboxhost}} to your HOOKS array in {{ic|/etc/mkinitcpio.conf}}. Again, make sure the right linux headers are available for the new kernel otherwise the compilation will fail.<br />
<br />
{{Tip|Like the {{ic|dkms}} command, the {{ic|vboxhost}} hook will tell you if anything goes wrong during the recompilation of the VirtualBox modules.}}<br />
<br />
=== Load the VirtualBox kernel modules ===<br />
<br />
Among the [[kernel modules]] VirtualBox uses, there is a mandatory module named {{ic|vboxdrv}}, which must be loaded before any virtual machines can run. It can be automatically loaded when Arch Linux starts up, or it can be loaded manually when necessary.<br />
<br />
To load the module manually:<br />
# modprobe vboxdrv<br />
<br />
To load the VirtualBox module at boot time, refer to [[Kernel_modules#Loading]] and create a {{ic|*.conf}} file (e.g. {{ic|virtualbox.conf}}) in {{ic|/etc/modules-load.d/}} with the line:<br />
{{hc|/etc/modules-load.d/virtualbox.conf|<br />
vboxdrv}}<br />
<br />
The following modules are optional but are recommended if you do not want to be bothered in some advanced configurations (precised here after): {{ic|vboxnetadp}}, {{ic|vboxnetflt}} and {{ic|vboxpci}}.<br />
<br />
* {{ic|vboxnetadp}} and {{ic|vboxnetflt}} are both needed when you intend to use the [https://www.virtualbox.org/manual/ch06.html#network_hostonly "Host-only networking"] feature. More precisely, {{ic|vboxnetadp}} is needed to create the host interface in the VirtualBox global preferences, and {{ic|vboxnetflt}} is needed to launch a virtual machine using that network interface.<br />
<br />
* {{ic|vboxpci}} is needed when your virtual machine needs to pass through a PCI device on your host.<br />
<br />
{{Note|If the VirtualBox kernel modules were loaded in the kernel while you updated the modules, you need to reload them manually to use the new updated version. To do it, run {{ic|vboxreload}} as root.}}<br />
<br />
Finally, if you use the aforementioned "Host-only networking" feature, make sure {{pkg|net-tools}} is installed. VirtualBox actually uses {{ic|ifconfig}} and {{ic|route}} to assign the IP and route to the host interface configured with {{ic|VBoxManage hostonlyif}} or via the GUI in ''Settings > Network > Host-only Networks > Edit host-only network (space) > Adapter''.<br />
<br />
=== Add usernames to the vboxusers group ===<br />
<br />
To use the USB ports of your host machine in your virtual machines, add to the {{ic|vboxusers}} [[group]] the usernames that will be authorized to use this feature. The new group does not automatically apply to existing sessions; the user has to log out and log in again, or start a new environment with the {{ic|newgrp}} command or with {{ic|sudo -u $USER -s}}. To add the current user to the {{ic|vboxusers}} group, type:<br />
# gpasswd -a $USER vboxusers<br />
<br />
=== Guest additions disc ===<br />
<br />
It is also recommended to install the {{Pkg|virtualbox-guest-iso}} package on the host running VirtualBox. This package will act as a disc image that can be used to install the guest additions onto guest systems other than Arch Linux. The ''.iso'' file will be located at {{ic|/usr/lib/virtualbox/additions/VBoxGuestAdditions.iso}}, and may have to be mounted manually inside the virtual machine. Once mounted, you can run the guest additions installer inside the guest.<br />
<br />
=== Extension pack ===<br />
<br />
Since VirtualBox 4.0, non-GPL components have been split from the rest of the application. Despite being released under a non-free license and '''being only available for personal use''', you might be interested in installing the Oracle Extension Pack which provides [https://www.virtualbox.org/manual/ch01.html#intro-installing additional features]. To avoid manual manipulation, the {{aur|virtualbox-ext-oracle}} package is available on the [[AUR]], and a prebuilt version can be found in the [[Unofficial user repositories#seblu|seblu]] repository.<br />
<br />
If you prefer to use the traditional and manual way: download the extension manually and install it via the GUI (''Settings > Extensions'') or via {{ic|VBoxManage extpack install <.vbox-extpack>}}, make sure you have a toolkit (like [[Polkit]], gksu, etc.) to grant privileged access to VirtualBox. The installation of this extension [https://www.virtualbox.org/ticket/8473 requires root access].<br />
<br />
=== Use the right front-end ===<br />
<br />
Now, you are ready to use VirtualBox. Congratulations!<br />
<br />
Multiple front-ends are available to you of which two are available by default:<br />
* If you want to use VirtualBox in command-line only (only launch and change settings of existing virtual machines), you can use the {{ic|VBoxSDL}} command. VBoxSDL does only provide a simple window that contains only the ''pure'' virtual machine, without menus or other controls.<br />
* If you want to use VirtualBox in command-line without any GUI running (e.g. on a server) to create, launch and configure virtual machines, use the {{ic|VBoxHeadless}} which produces no visible output on the host at all, but instead only delivers VRDP data.<br />
<br />
If you installed the {{Pkg|qt4}} optional dependency, you can run {{ic|VirtualBox}} and have a nice-looking GUI interface with menus usable via the mouse.<br />
<br />
Finally, you can use [[PhpVirtualBox]] to administrate your virtual machines via a web interface.<br />
<br />
Refer to the [https://www.virtualbox.org/manual VirtualBox manual] to learn how to create virtual machines.<br />
<br />
{{Warning|If you intend to store virtual disk images on a [[Btrfs]] file system, before creating any images, you should consider disabling [[Btrfs#Copy-On-Write_.28CoW.29|Copy-on-Write]] for the destination directory of these images.}}<br />
<br />
== Installation steps for Arch Linux guests ==<br />
<br />
=== Install Arch Linux inside the virtual machine ===<br />
<br />
{{Note| Windows hosts may have to disable Hyper-V in order to use hardware virtualization features and create 64 bit virtual machines in VirtualBox. To learn how to disable or re-enable Hyper-V [http://superuser.com/questions/684966/switch-off-hyper-v-without-disable-functionality-in-windows-8-1 see this stackoverflow post]. }}<br />
<br />
Boot the Arch installation media through one of the virtual machine's virtual drives. Then, complete the installation of a basic Arch system as explained in the [[Beginners' guide]] or the [[Installation guide]] without installing any graphic driver: we will install one provided by VirtualBox just at the next step.<br />
<br />
==== Installation in EFI mode ====<br />
<br />
If you want to install Arch Linux in EFI mode inside VirtualBox, in the settings of the virtual machine, go in the ''Settings'' tab, and check the checkbox ''Enable EFI (special OSes only)''. After selecting the kernel from the Arch Linux installation media's menu, the media will hang for a minute or two and will continue to boot the kernel normally afterwards. Be patient.<br />
<br />
When booting in EFI mode, VirtualBox will first attempt to run {{ic|/EFI/BOOT/BOOTX64.EFI}} from the ESP. If that first option fails, VirtualBox will then try the EFI shell script {{ic|startup.nsh}} from the root of the ESP. Unless you want to manually launch your bootloader from the EFI shell every time, you will need to move your bootloader to that default path. Do not bother with the VirtualBox Boot Manager (accessible with {{ic|F2}} at boot): EFI entries added to it manually at boot or with {{Pkg|efibootmgr}} will persist after a reboot [https://www.virtualbox.org/ticket/11177 but are lost when the VM is shut down].<br />
<br />
=== Install the Guest Additions ===<br />
<br />
After completing the installation of the guest system, install the VirtualBox [https://www.virtualbox.org/manual/ch04.html Guest Additions] which include drivers and applications that optimize the guest operating system. These can be installed via {{Pkg|virtualbox-guest-utils}}, which provides {{Pkg|virtualbox-guest-modules}} as a required dependency.<br />
<br />
{{Note|The method described in the [https://www.virtualbox.org/manual/ch04.html#idp54932560 VirtualBox manual] does not work on Arch Linux guests, resulting in an {{ic|Unable to determine your Linux distribution}} repeated several times as error message. If you tried this method first and you use the right solution described above afterwards, this will fail. You will get a [[Pacman#I get an error when updating: "file exists in filesystem"!|file conflict]]: {{ic|/usr/bin/VBox*}} and {{ic|/usr/lib/VBox* exists in filesystem}}. The solution is to remove the offending files first with {{ic|# rm /usr/bin/VBox* /usr/lib/VBox*}}. These files are actually symbolic links to the location where the additions tools were installed; by default, this is {{ic|/opt/VBoxGuestAdditions-''version number''}}. Remove these files too {{ic|# rm -r /opt/VBoxGuestAdditions-''version number''}} as they are not needed. Now you can restart the installation from the right method above.}}<br />
<br />
=== Install the VirtualBox guest kernel modules ===<br />
<br />
==== Guests running an official kernel ====<br />
<br />
* If you are using the {{Pkg|linux}} kernel, make sure the {{pkg|virtualbox-guest-modules}} package is still installed. The latter has been installed when you installed the {{Pkg|virtualbox-guest-utils}} package.<br />
* If you are using the LTS version of the kernel ({{pkg|linux-lts}}), you need to install the {{pkg|virtualbox-guest-modules-lts}} package. {{Pkg|virtualbox-guest-modules}} can now be removed if you want.<br />
* If you are using the {{aur|linux-ck}}, kernel, build the {{aur|virtualbox-ck-guest-modules}} package. {{Pkg|virtualbox-guest-modules}} can now be removed in this case too, if you want.<br />
<br />
==== Guests running a custom kernel ====<br />
<br />
As this installation step is quite similar to the Vitualbox kernel modules section for the host described above, please refer to [[#Install the VirtualBox kernel modules|that section]] for more information and replace all {{Pkg|virtualbox-host-modules}}, {{Pkg|virtualbox-host-dkms}} and {{AUR|vboxhost-hook}} statements by {{Pkg|virtualbox-guest-modules}}, {{Pkg|virtualbox-guest-dkms}} and {{AUR|vboxguest-hook}} respectively.<br />
<br />
=== Load the Virtualbox kernel modules ===<br />
<br />
To load the modules manually, type:<br />
# modprobe -a vboxguest vboxsf vboxvideo<br />
<br />
To load the VirtualBox module at boot time, refer to [[Kernel_modules#Loading]] and create a {{ic|*.conf}} file (e.g. {{ic|virtualbox.conf}}) in {{ic|/etc/modules-load.d/}} with these lines:<br />
{{hc|/etc/modules-load.d/virtualbox.conf|<br />
vboxguest<br />
vboxsf<br />
vboxvideo}}<br />
<br />
Alternatively, [[enable]] the {{ic|vboxservice}} service which loads the modules and synchronizes the guest's system time with the host.<br />
<br />
=== Launch the VirtualBox guest services ===<br />
<br />
After the rather big installation step dealing with VirtualBox kernel modules, now you need to start the guest services. The guest services are actually just a binary executable called {{ic|VBoxClient}} which will interact with your X Window System. {{ic|VBoxClient}} manages the following features:<br />
* shared clipboard and drag and drop between the host and the guest;<br />
* seamless window mode;<br />
* the guest display is automatically resized according to the size of the guest window;<br />
* checking the VirtualBox host version<br />
<br />
All of these features can be enabled independently with their dedicated flags:<br />
$ VBoxClient --clipboard --draganddrop --seamless --display --checkhostversion<br />
<br />
As a shortcut, the {{ic|VBoxClient-all}} bash script enables all of these features. You should set {{ic|VBoxClient}} to be automatically loaded as your [[desktop environment]] or [[window manager]] starts. In practice,<br />
* if you are using a [[desktop environment]], you just need to check a box or add the {{ic|/usr/sbin/VBoxClient-all}} to the autostart section in your [[desktop environment]] settings (the DE will typically set a flag to a ''.desktop'' file in {{ic|~/.config/autostart}}, see [[Autostart#Desktop entries|the Autostart section]] for more details);<br />
* if you do not have any [[desktop environment]], add the following line to the top of {{ic|~/.xinitrc}} (copy the file from {{ic|/etc/skel/.xinitrc}} if it does not exist) above any {{ic|exec}} options:<br />
{{hc|~/.xinitrc|<br />
/usr/bin/VBoxClient-all}}<br />
<br />
VirtualBox can also synchronize the time between the host and the guest. To do this, run {{ic|VBoxService}} as root. To set this to run automatically on boot, simply [[enable]] the {{ic|vboxservice}} service.<br />
<br />
Now, you should have a working Arch Linux guest. Congratulations!<br />
<br />
If you want to share folders between your host and your Arch Linux guest, read on.<br />
<br />
=== Enable shared folders ===<br />
<br />
Shared folders are managed on the host, in the settings of the Virtual Machine accessible via the GUI of VirtualBox, in the ''Shared Folders'' tab. There, ''Folder Path'', the name of the mount point identified by ''Folder name'', and options like ''Read-only'', ''Auto-mount'' and ''Make permanent'' can be specified. These parameters can be defined with the {{ic|VBoxManage}} command line utility. See [https://www.virtualbox.org/manual/ch04.html#sharedfolders there for more details].<br />
<br />
No matter which method you will use to mount your folder, all methods require some steps first.<br />
<br />
To avoid this issue {{ic|/sbin/mount.vboxsf: mounting failed with the error: No such device}}, make sure the {{ic|vboxsf}} kernel module is properly loaded. It should be, since we enabled all guest kernel modules previously.<br />
<br />
Two additional steps are needed in order for the mount point to be accessible from users other than root:<br />
* the {{Pkg|virtualbox-guest-utils}} package created a group {{ic|vboxsf}} (done in a previous step);<br />
* your username must be in this group, use this command {{ic|gpasswd -a $USER vboxsf}} to add your username and use {{ic|newgrp}} to apply the changes immediately;<br />
<br />
==== Manual mounting ====<br />
<br />
Use the following command to mount your folder in your Arch Linux guest:<br />
# mount -t vboxsf ''shared_folder_name'' ''mount_point_on_guest_system''<br />
<br />
The vboxsf filesystem offers other options which can be displayed with this command:<br />
# mount.vboxsf<br />
<br />
For example if the user was not in the ''vboxsf'' group, we could have used this command to give access our mountpoint to him:<br />
# mount -t vboxsf -o uid=1000,gid=1000 home /mnt/<br />
<br />
Where ''uid'' and ''gid'' are values corresponding to the users we want to give access to. These values are obtained from the {{ic|id}} command run against this user.<br />
<br />
==== Automounting ====<br />
<br />
In order for the automounting feature to work you must have checked the auto-mount checkbox in the GUI or used the optional {{ic|--automount}} argument with the command {{ic|VBoxManage sharedfolder}}.<br />
<br />
The shared folder should now appear in {{ic|/media/sf_''shared_folder_name''}}.<br />
<br />
You can use symlinks if you want to have a more convenient access and avoid to browse in that directory, e.g.:<br />
$ ln -s /media/sf_''shared_folder_name'' ~/''my_documents''<br />
<br />
==== Mount at boot ====<br />
<br />
You can mount your directory with [[fstab]]. However, to prevent startup problems with systemd, {{ic|1=comment=systemd.automount}} should be added to {{ic|/etc/fstab}}. This way, the shared folders are mounted only when those mount points are accessed and not during startup. This can avoid some problems, especially if the guest additions are not loaded yet when systemd read fstab and mount the partitions.<br />
desktop /media/desktop vboxsf uid=user,gid=group,rw,dmode=700,fmode=600,comment=systemd.automount 0 0<br />
<br />
As of 2012-08-02, mount.vboxsf does not support the ''nofail'' option:<br />
desktop /media/desktop vboxsf uid=user,gid=group,rw,dmode=700,fmode=600,nofail 0 0<br />
<br />
== Import/export VirtualBox virtual machines from/to other hypervisors ==<br />
<br />
If you plan to use your virtual machine on another hypervisor or want to import in VirtualBox a virtual machine created with another hypervisor, you might be interested in reading the following steps.<br />
<br />
=== Remove additions ===<br />
<br />
Guest additions are available in most hypervisor solutions: VirtualBox comes with the Guest Additions, VMware with the VMware Tools, Parallels with the Parallels Tools, etc. These additional components are designed to be installed inside a virtual machine after the guest operating system has been installed. They consist of device drivers and system applications that optimize the guest operating system for better performance and usability [https://www.virtualbox.org/manual/ch04.html by providing these features].<br />
<br />
If you have installed the additions to your virtual machine, please uninstall them first. Your guest, especially if it is using an OS from the Windows family, might behave weirdly, crash or even might not boot at all if you are still using the specific drivers in another hypervisor.<br />
<br />
=== Use the right virtual disk format ===<br />
<br />
This step will depend on the ability to convert the virtual disk image directly or not.<br />
<br />
==== Automatic tools ====<br />
<br />
Some companies provide tools which offer the ability to create virtual machines from a Windows or GNU/Linux operating system located either in a virtual machine or even in a native installation. With such a product, you do not need to apply this and the following steps and can stop reading here.<br />
* ''[http://www.parallels.com/products/transporter Parallels Transporter]'' which is non free, is a product from Parallels Inc. This solution basically consists in an piece of software called ''agent'' that will be installed in the guest you want to import/convert. Then, Parallels Transporter, <u>which only works on OS X</u>, will create a virtual machine from that ''agent'' which is contacted either by USB or Ethernet network.<br />
* ''[https://www.vmware.com/products/converter/ VMware vCenter Converter]'' which is free upon registration on the VMware webiste, works nearly the same way as Parallels Transporter, but the piece of software that will gather the data to create the virtual machine only works on a Windows platform.<br />
<br />
==== Manual conversion ====<br />
<br />
First, familiarize yourself with the [[#Formats supported by VirtualBox]] and [[Wikipedia:Comparison of platform virtual machines#Image type compatibility|those supported by third-party hypervisors]].<br />
<br />
* Importing or exporting a virtual machine from/to a VMware solution is not a problem at all if you use the VMDK or OVF disk format, otherwise converting [[#VMDK to VDI and VDI to VMDK]] is possible and the aforementioned VMware vCenter Converter tool is available.<br />
<br />
* Importing or exporting from/to QEMU is not a problem neither: some QEMU formats are supported directly by VirtualBox and conversion between [[#QCOW2 to VDI and VDI to QCOW2]] is still available if needed.<br />
<br />
* Importing or exporting from/to Parallels hypervisor is the hardest way: Parallels does only support its own HDD format (even the standard and portable OVF format is not supported!).<br />
:* To export your virtual machine to Parallels, you will need to use the Parallels Transporter tool described above.<br />
:* To import your virtual machine to VirtualBox, you will need to use the VMware vCenter Converter described above to convert the VM to the VMware format first. Then, apply the solution to migrate from VMware.<br />
<br />
=== Create the VM configuration for your hypervisor ===<br />
<br />
Each hypervisor have their own virtual machine configuration file: {{ic|.vbox}} for VirtualBox, {{ic|.vmx}} for VMware, a {{ic|config.pvs}} file located in the virtual machine bundle ({{ic|.pvm}} file), etc. You will have thus to recreate a new virtual machine in your new destination hypervisor and specify its hardware configuration as close as possible as your initial virtual machine.<br />
<br />
Pay a close attention to the firmware interface (BIOS or UEFI) used to install the guest operating system. While an option is available to choose between these 2 interfaces on VirtualBox and on Parallels solutions, on VMware, you will have to add manually the following line to your ''.vmx'' file.<br />
<br />
{{hc|ArchLinux_vm.vmx|2=<br />
firmware = "efi"<br />
}}<br />
<br />
Finally, ask your hypervisor to use the existing virtual disk you have converted and launch the virtual machine.<br />
{{Tip|<br />
* On VirtualBox, if you do not want to browse the whole GUI to find the right location to add your new virtual drive device, you can [[#Replace a virtual disk manually from the .vbox file]], or use the {{ic|VBoxManage storageattach}} described in [[#Increasing virtual disks]] or in the [https://www.virtualbox.org/manual/ch08.html#vboxmanage-storageattach VirtualBox manual page].<br />
* Similarly, in VMware products, you can replace the location of the current virtual disk location by adapting the ''.vmdk'' file location in your ''.vmx'' configuration file.}}<br />
<br />
== Virtual disks management ==<br />
<br />
=== Formats supported by VirtualBox ===<br />
<br />
VirtualBox supports the following virtual disk formats:<br />
<br />
* VDI: The Virtual Disk Image is the VirtualBox own open container used by default when you create a virtual machine with VirtualBox.<br />
<br />
* VMDK: The Virtual Machine Disk has been initially developed by VMware for their products. The specification was initially closed source, but it became now an open format which is fully supported by VirtualBox. This format offers the ability to be split into several 2GB files. This feature is specially useful if you want to store the virtual machine on machines which do not support very large files. Other formats, excluding the HDD format from Parallels, do not provide such an equivalent feature.<br />
<br />
* VHD: The Virtual Hard Disk is the format used by Microsoft in Windows Virtual PC and Hyper-V. If you intend to use any of these Microsoft products, you will have to choose this format.<br />
:{{Tip|Since Windows 7, this format can be mounted directly without any additional application.}} <br />
<br />
* VHDX (read only): This is the eXtended version of the Virtual Hard Disk format developed by Microsoft, which has been released on 2012-09-04 with Hyper-V 3.0 coming with Windows Server 2012. This new version of the disk format does offer enhanced performance (better block alignment), larger blocks size, and journal support which brings power failure resiliency. VirtualBox [https://www.virtualbox.org/manual/ch15.html#idp63002176 should support this format in read only].<br />
<br />
* Version 2 of the HDD: The HDD format is developed by Parallels Inc and used in their hypervisor solutions like Parallels Desktop for Mac. Newer versions of this format (i.e. 3 and 4) are not supported due to the lack of documentation for this proprietary format. {{Note|There is currently a controversy regarding the support of the version 2 of the format. While the official VirtualBox manual [https://www.virtualbox.org/manual/ch05.html#vdidetails only reports the second version of the HDD file format as supported], Wikipedia's contributors are [[Wikipedia:Comparison of platform virtual machines#Image type compatibility|reporting the first version may work too]]. Help is welcome if you can perform some tests with the first version of the HDD format.}}<br />
<br />
* QED: The QEMU Enhanced Disk format is an old file format for QEMU, another free and open source hypervisor. This format was designed from 2010 in a way to provide a superior alternative to QCOW2 and others. This format features a fully asynchronous I/O path, strong data integrity, backing files, and sparse files. QED format is supported only for compatibility with virtual machines created with old versions of QEMU.<br />
<br />
* QCOW: The QEMU Copy On Write format is the current format for QEMU. The QCOW format does support zlib-based transparent compression and encryption (the latter has flaw and is not recommended). QCOW is available in two versions: QCOW and QCOW2. The latter tends to supersede the first one. QCOW is [https://www.virtualbox.org/manual/ch15.html#idp63002176 currently fully supported by VirtualBox]. QCOW2 comes in two revisions: QCOW2 0.10 and QCOW2 1.1 (which is the default when you create a virtual disk with QEMU). VirtualBox does not support this QCOW2 format (both revisions have been tried).<br />
<br />
* OVF: The Open Virtualization Format is an open format which has been designed for interoperability and distributions of virtual machines between different hypervisors. VirtualBox supports all revisions of this format via the [https://www.virtualbox.org/manual/ch08.html#idp55423424 {{ic|VBoxManage}} import/export feature] but with [https://www.virtualbox.org/manual/ch14.html#KnownProblems known limitations].<br />
<br />
* RAW: This is the mode when the virtual disk is exposed directly to the disk without being contained in a specific file format container. VirtualBox supports this feature in several ways: converting RAW disk [https://www.virtualbox.org/manual/ch08.html#idp59139136 to a specific format], or by [https://www.virtualbox.org/manual/ch08.html#vboxmanage-clonevdi cloning a disk to RAW], or by using directly a VMDK file [https://www.virtualbox.org/manual/ch09.html#idp57804112 which points to a physical disk or a simple file].<br />
<br />
=== Disk image format conversion ===<br />
<br />
==== VMDK to VDI and VDI to VMDK ====<br />
<br />
VirtualBox can handle back and forth conversion between VDI and VMDK by itself with [https://www.virtualbox.org/manual/ch08.html#vboxmanage-clonevdi {{ic|VBoxManage clonehd}}].<br />
<br />
VMDK to VDI:<br />
<br />
$ VBoxManage clonehd ''source.vmdk'' ''destination.vdi'' --format VDI<br />
<br />
VDI to VMDK:<br />
<br />
$ VBoxManage clonehd ''source.vdi'' ''destination.vmdk'' --format VMDK<br />
<br />
==== VHD to VDI and VDI to VDH ====<br />
<br />
VirtualBox can handle conversion back and forth this format with [https://www.virtualbox.org/manual/ch08.html#vboxmanage-clonevdi {{ic|VBoxManage clonehd}}] too.<br />
<br />
VHD to VDI:<br />
<br />
$ VBoxManage clonehd ''source.vhd'' ''destination.vdi'' --format VDI<br />
<br />
VDI to VHD:<br />
<br />
$ VBoxManage clonehd ''source.vdi'' ''destination.vhd'' --format VHD<br />
<br />
==== QCOW2 to VDI and VDI to QCOW2 ====<br />
<br />
[https://www.virtualbox.org/manual/ch08.html#vboxmanage-clonevdi {{ic|VBoxManage clonehd}}] cannot handle the QEMU format conversion; we will thus rely on another tool. The {{ic|qemu-img}} command from {{Pkg|qemu}} can be used to convert images back and forth from VDI to QCOW2. {{Note|{{ic|qemu-img}} can handle a bunch of other formats too. According to the {{ic|qemu-img --help}}, here are the supported formats this tool supports: "''vvfat vpc vmdk vhdx vdi ssh sheepdog sheepdog sheepdog raw host_cdrom host_floppy host_device file qed qcow2 qcow parallels nbd nbd nbd iscsi dmg tftp ftps ftp https http cow cloop bochs blkverify blkdebug'".}}<br />
<br />
QCOW2 to VDI:<br />
<br />
$ qemu-img convert -pO vdi ''source.qcow2'' ''destination.vdi''<br />
<br />
VDI to QCOW2:<br />
<br />
$ qemu-img convert -pO qcow2 ''source.vdi'' ''destination.qcow2''<br />
<br />
As QCOW2 comes in two revisions (see [[#Formats supported by VirtualBox]], use the flag {{ic|1=-o compat=}} to specify the revision.<br />
<br />
$ qemu-img convert -pO qcow2 ''source.vdi'' ''destination.qcow2'' -o compat=0.10<br />
or<br />
$ qemu-img convert -pO qcow2 ''source.vdi'' ''destination.qcow2'' -o compat=1.1<br />
<br />
{{Tip|The {{ic|-p}} parameter is used to get the progression of the conversion task.}}<br />
<br />
=== Mount virtual disks ===<br />
<br />
==== VDI ====<br />
<br />
Mounting vdi images only works with fixed size images (a.k.a. static images); dynamic (dynamically size allocating) images are not easily mountable.<br />
<br />
The offset of the partition (within the vdi) is needed, then add the value of {{ic|offData}} to {{ic|32256}} (e.g. 69632 + 32256 = 101888):<br />
<br />
$ VBoxManage internalcommands dumphdinfo <storage.vdi> | grep "offData"<br />
<br />
The can now be mounted with:<br />
<br />
# mount -t ext4 -o rw,noatime,noexec,loop,offset=101888 <storage.vdi> /mntpoint/<br />
<br />
You can also use [https://github.com/pld-linux/VirtualBox/blob/master/mount.vdi mount.vdi] script that, which you can use as (install script itself to {{ic|/usr/bin/}}):<br />
<br />
# mount -t vdi -o fstype=ext4,rw,noatime,noexec ''vdi_file_location'' ''/mnt/''<br />
<br />
Alternately you can use {{Pkg|qemu}}'s kernel module that can do this [[http://bethesignal.org/blog/2011/01/05/how-to-mount-virtualbox-vdi-image/ attrib]]:<br />
<br />
# modprobe nbd max_part=16<br />
# qemu-nbd -c /dev/nbd0 <storage.vdi><br />
# mount /dev/nbd0p1 /mnt/dir/<br />
# # to unmount:<br />
# umount /mnt/dir/<br />
# qemu-nbd -d /dev/nbd0<br />
<br />
If the partition nodes are not propagated try using {{ic|partprobe /dev/nbd0}}; otherwise, a vdi partition can be mapped directly to a node by: {{ic|qemu-nbd -P 1 -c /dev/nbd0 <storage.vdi>}}.<br />
<br />
=== Compact virtual disks ===<br />
<br />
Compacting virtual disks only works with {{ic|.vdi}} files and basically consists in the following steps.<br />
<br />
Boot your virtual machine and remove all bloat manually or by using cleaning tools like {{Pkg|bleachbit}} which is [http://bleachbit.sourceforge.net/download/windows available for Windows systems too].<br />
<br />
Wiping free space with zeroes can be achieved with several tools:<br />
* If you were previously using Bleachbit, check the checkbox ''System > Free disk space'' in the GUI, or use {{ic|bleachbit -c system.free_disk_space}} in CLI;<br />
* On UNIX-based systems, by using {{ic|dd}} or preferably {{Pkg|dcfldd}} (see [http://superuser.com/a/355322 here] to learn the differences) :<br />
:{{bc|1=# dcfldd if=/dev/zero of=''/fillfile'' bs=4M}}<br />
:When {{ic|fillfile}} reaches the limit of the partition, you will get a message like {{ic|1280 blocks (5120Mb) written.dcfldd:: No space left on device}}. This means that all of the user-space and non-reserved blocks of the partition will be filled with zeros. Using this command as root is important to make sure all free blocks have been overwritten. Indeed, by default, when using partitions with ext filesystem, a specified percentage of filesystem blocks is reserved for the super-user (see the {{ic|-m}} argument in the {{ic|mkfs.ext4}} man pages or use {{ic|tune2fs -l}} to see how much space is reserved for root applications).<br />
:When the aforementioned process has completed, you can remove the file {{ic|''fillfile''}} you created.<br />
<br />
* On Windows, there are two tools available:<br />
:*{{ic|sdelete}} from the [http://technet.microsoft.com/en-us/sysinternals/bb842062.aspx Sysinternals Suite], type {{ic|sdelete -s ''c:''}}, where you need to reexecute the command for each drive you have in your virtual machine;<br />
:* or, if you love scripts, there is a [http://blog.whatsupduck.net/2012/03/powershell-alternative-to-sdelete.html PowerShell solution], but which still needs to be repeated for all drives.<br />
::{{bc|PS> ./Write-ZeroesToFreeSpace.ps1 -Root ''c:\'' -PercentFree 0}}<br />
::{{Note|This script must be run in a PowerShell environment with administrator privileges. By default, scripts cannot be run, ensure the execution policy is at least on {{ic|RemoteSigned}} and not on {{ic|Restricted}}. This can be checked with {{ic|Get-ExecutionPolicy}} and the required policy can be set with {{ic|Set-ExecutionPolicy RemoteSigned}}.}}<br />
<br />
Once the free disk space have been wiped, shut down your virtual machine.<br />
<br />
The next time you boot your virtual machine, it is recommended to do a filesystem check.<br />
* On UNIX-based systems, you can use {{ic|fsck}} manually;<br />
:* On GNU/Linux systems, and thus on Arch Linux, you can force a disk check at boot [[Fsck#Forcing the check|thanks to a kernel boot parameter]];<br />
* On Windows systems, you can use:<br />
:* either {{ic|chkdsk ''c:'' /F}} where {{ic|''c:''}} needs to be replaced by each disk you need to scan and fix errors;<br />
:* or {{ic|FsckDskAll}} [http://therightstuff.de/2009/02/14/ChkDskAll-ChkDsk-For-All-Drives.aspx from here] which is basically the same software as {{ic|chkdsk}}, but without the need to repeat the command for all drives;<br />
<br />
Now, remove the zeros from the {{ic|vdi}} file with {{ic|[https://www.virtualbox.org/manual/ch08.html#vboxmanage-modifyvdi VBoxManage modifyhd]}}:<br />
$ VBoxManage modifyhd ''your_disk.vdi'' --compact<br />
<br />
{{Note|If your virtual machine has snapshots, you need to apply the above command on each {{ic|.vdi}} files you have.}}<br />
<br />
=== Increase virtual disks ===<br />
<br />
If you are running out of space due to the small hard drive size you selected when you created your virtual machine, the solution adviced by the VirtualBox manual is to use [https://www.virtualbox.org/manual/ch08.html#vboxmanage-modifyvdi {{ic|VBoxManage modifyhd}}]. However this command only works for VDI and VHD disks and only for the dynamically allocated variants. If you want to resize a fixed size virtual disk disk too, read on this trick which works either for a Windows or UNIX-like virtual machine.<br />
<br />
First, create a new virtual disk next to the one you want to increase:<br />
$ VBoxManage createhd -filename ''new.vdi'' --size ''10000''<br />
<br />
where size is in MiB, in this example 10000MiB ~= 10GiB, and ''new.vdi'' is name of new hard drive to be created.<br />
<br />
Next, the old virtual disk needs to be cloned to the new one which this may take some time:<br />
$ VBoxManage clonehd ''old.vdi'' ''new.vdi'' --existing<br />
<br />
{{Note|By default, this command uses the ''Standard'' (corresponding to dynamic allocated) file format variant and thus will not use the same file format variant as your source virtual disk. If your ''old.vdi'' has a fixed size and you want to keep this variant, add the parameter {{ic|--variant Fixed}}.}}<br />
<br />
Detach the old hard drive and attach new one, replace all mandatory italic arguments by your own:<br />
$ VBoxManage storageattach ''VM_name'' --storagectl ''SATA'' --port ''0'' --medium none<br />
$ VBoxManage storageattach ''VM_name'' --storagectl ''SATA'' --port ''0'' --medium ''new.vdi'' --type hdd<br />
<br />
To get the storage controller name and the port number, you can use the command {{ic|VBoxManage showvminfo ''VM_name''}}. Among the output you will get such a result (what you are looking for is in italic):<br />
<br />
{{bc|<br />
[...]<br />
Storage Controller Name (0): IDE<br />
Storage Controller Type (0): PIIX4<br />
Storage Controller Instance Number (0): 0<br />
Storage Controller Max Port Count (0): 2<br />
Storage Controller Port Count (0): 2<br />
Storage Controller Bootable (0): on<br />
Storage Controller Name (1): SATA<br />
Storage Controller Type (1): IntelAhci<br />
Storage Controller Instance Number (1): 0<br />
Storage Controller Max Port Count (1): 30<br />
Storage Controller Port Count (1): 1<br />
Storage Controller Bootable (1): on<br />
IDE (1, 0): Empty<br />
''SATA'' (''0'', 0): /home/wget/IT/Virtual_machines/GNU_Linux_distributions/ArchLinux_x64_EFI/Snapshots/{6bb17af7-e8a2-4bbf-baac-fbba05ebd704}.vdi (UUID: 6bb17af7-e8a2-4bbf-baac-fbba05ebd704)<br />
[...]}}<br />
<br />
Download [http://gparted.org/download.php GParted live image] and mount it as a virtual CD/DVD disk file, boot your virtual machine, increase/move your partitions, umount GParted live and reboot.<br />
<br />
{{Note|On GPT disks, increasing the size of the disk will result in the backup GPT header not being at the end of the device. GParted will ask to fix this, click on ''Fix'' both times. On MBR disks, you do not have such a problem as this partition table as no trailer at the end of the disk.}}<br />
<br />
Finally, unregister the virtual disk from VirtualBox and remove the file:<br />
$ VBoxManage closemedium disk ''old.vdi''<br />
$ rm ''old.vdi''<br />
<br />
=== Replace a virtual disk manually from the .vbox file ===<br />
<br />
If you think that editing a simple ''XML'' file is more convenient than playing with the GUI or with {{ic|VBoxManage}} and you want to replace (or add) a virtual disk to your virtual machine, in the ''.vbox'' configuration file corresponding to your virtual machine, simply replace the GUID, the file location and the format to your needs:<br />
<br />
{{hc|ArchLinux_vm.vbox|2=<br />
<HardDisk uuid="''{670157e5-8bd4-4f7b-8b96-9ee412a712b5}''" location="''ArchLinux_vm.vdi''" format="''VDI''" type="Normal"/><br />
}}<br />
<br />
then in the {{ic|<AttachedDevice>}} sub-tag of {{ic|<StorageController>}}, replace the GUID by the new one.<br />
<br />
{{hc|ArchLinux_vm.vbox|2=<br />
<AttachedDevice type="HardDisk" port="0" device="0"><br />
<Image uuid="''{670157e5-8bd4-4f7b-8b96-9ee412a712b5}''"/><br />
</AttachedDevice><br />
}}<br />
<br />
{{Note|If you do not know the GUID of the drive you want to add, you can use the {{ic|VBoxManage showhdinfo ''file''}}. If you previously used {{ic|VBoxManage clonehd}} to copy/convert your virtual disk, this command should have outputted the GUID just after the copy/conversion completed. Using a random GUID does not work, as each [http://www.virtualbox.org/manual/ch05.html#cloningvdis UUID is stored inside each disk image].}}<br />
<br />
=== Clone a virtual disk and assigning a new UUID to it ===<br />
<br />
UUIDs are widely used by VirtualBox. Each virtual machines and each virtual disk of a virtual machine must have a different UUID. When you launch a virtual machine in VirtualBox, the latter will keep track of all UUID of your virtual machine instance. See the [http://www.virtualbox.org/manual/ch08.html#vboxmanage-list {{ic|VBoxManage list}}] to list the items registered with VirtualBox.<br />
<br />
If you cloned a virtual disk manually by copying the virtual disk file, you will need to assign a new UUID to the cloned virtual drive if you want to use the disk in the same virtual machine or even in another (if that one has already been opened, and thus registered, with VirtualBox).<br />
<br />
You can use this command to assign a new UUID to your virtual disk: <br />
$ VBoxManage internalcommands sethduuid ''/path/to/disk.vdi''<br />
<br />
{{Tip|In the future, to avoid copying the virtual disk and assigning a new UUID to your file manually, use {{ic|[http://www.virtualbox.org/manual/ch08.html#vboxmanage-clonevdi VBoxManage clonehd]}} instead.}}<br />
<br />
{{Note|The commands above supports [[#Formats supported by VirtualBox|all virtual disk formats supported by VirtualBox]].}}<br />
<br />
== Advanced configuration ==<br />
<br />
=== Virtual machine launch management ===<br />
<br />
==== Starting virtual machines with a service ====<br />
<br />
Find hereafter the implementation details of a systemd service that will be used to consider a virtual machine as a service.<br />
<br />
{{hc|/etc/systemd/system/vboxvmservice@.service|2=<br />
[Unit]<br />
Description=VBox Virtual Machine %i Service<br />
Requires=systemd-modules-load.service<br />
After=systemd-modules-load.service<br />
<br />
[Service]<br />
User=''username''<br />
Group=vboxusers<br />
ExecStart=/usr/bin/VBoxHeadless -s %i<br />
ExecStop=/usr/bin/VBoxManage controlvm %i savestate<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
{{Note|Replace {{ic|''username''}} with a user that is a member of the {{ic|vboxusers}} group. Make sure the user chosen is the same user that will create/import virtual machines, otherwise the user will not see the VM appliances.}}<br />
<br />
{{Note|If you have multiple virtual machines managed by Systemd and they are not stopping properly, try to add {{ic|RemainAfterExit&#61;true}} and {{ic|KillMode&#61;none}} at the end of {{ic|[Service]}} section.}}<br />
<br />
To enable the service that will launch the virtual machine at next boot, use:<br />
# systemctl enable vboxvmservice@''your_virtual_machine_name''<br />
<br />
To start the service that will launch directly the virtual machine, use:<br />
# systemctl start vboxvmservice@''your_virtual_machine_name''<br />
<br />
VirtualBox 4.2 introduces [http://lifeofageekadmin.com/how-to-set-your-virtualbox-vm-to-automatically-startup/ a new way] for UNIX-like systems to have virtual machines started automatically, other than using a systemd service.<br />
<br />
==== Starting virtual machines with a keyboard shortcut ====<br />
<br />
It can be useful to start virtual machines directly with a keyboard shortcut instead of using the VirtualBox interface (GUI or CLI). For that, you can simply define key bindings in {{ic|.xbindkeysrc}}. Please refer to [[Xbindkeys]] for more details.<br />
<br />
Example, using the {{ic|Fn}} key of a laptop with an unused battery key ({{ic|F3}} on the computer used in this example):<br />
"VBoxManage startvm 'Windows 7'"<br />
m:0x0 + c:244<br />
XF86Battery<br />
<br />
{{Note|If you have a space in the name of your virtual machine, then enclose it with single apostrophes like made in the example just above.}}<br />
<br />
=== Use specific device in the virtual machine ===<br />
<br />
==== Using USB webcam / microphone ====<br />
<br />
{{Note|You will need to have VirtualBox extension pack installed before following the steps below. See [[#Extension pack]] for details.}}<br />
<br />
# Make sure the virtual machine is not running and your webcam / microphone is not being used.<br />
# Bring up the main VirtualBox window and go to settings for Arch machine. Go to USB section.<br />
# Make sure "Enable USB Controller" is selected. Also make sure that "Enable USB 2.0 (EHCI) Controller" is selected too.<br />
# Click the "Add filter from device" button (the cable with the '+' icon).<br />
# Select your USB webcam/microphone device from the list.<br />
# Now click OK and start your VM.<br />
<br />
==== Detecting web-cams and other USB devices ====<br />
<br />
Make sure you filter any devices that are not a keyboard or a mouse so they do not start up at boot and this insures that Windows will detect the device at start-up.<br />
<br />
=== Access a guest server ===<br />
<br />
To access [[Wikipedia:Apache_HTTP_Server|Apache server]] on a Virtual Machine from the host machine '''only''', simply execute the following lines on the host:<br />
$ VBoxManage setextradata GuestName "VBoxInternal/Devices/''pcnet''/0/LUN#0/Config/Apache/HostPort" ''8888''<br />
$ VBoxManage setextradata GuestName "VBoxInternal/Devices/''pcnet''/0/LUN#0/Config/Apache/GuestPort" ''80''<br />
$ VBoxManage setextradata GuestName "VBoxInternal/Devices/''pcnet''/0/LUN#0/Config/Apache/Protocol" TCP<br />
Where 8888 is the port the host should listen on and 80 is the port the VM will send Apache's signal on.<br />
<br />
To use a port lower than 1024 on the host machine, changes need to be made to the firewall on that host machine. This can also be set up to work with SSH or any other services by changing "Apache" to the corresponding service and ports. <br />
<br />
{{note|{{ic|pcnet}} refers to the network card of the VM. If you use an Intel card in your VM settings, change {{ic|pcnet}} to {{ic|e1000}}.}}<br />
<br />
To communicate between the VirtualBox guest and host using ssh, the server port must be forwarded under Settings > Network. When connecting from the client/host, connect to the IP address of the client/host machine, as opposed to the connection of the other machine. This is because the connection will be made over a virtual adapter.<br />
<br />
=== D3D acceleration in Windows guests ===<br />
<br />
Recent versions of Virtualbox have support for accelerating OpenGL inside guests. This can be enabled with a simple checkbox in the machine's settings, right below where video ram is set, and installing the Virtualbox guest additions. However, most Windows games use Direct3D (part of DirectX), not OpenGL, and are thus not helped by this method. However, it is possible to gain accelerated Direct3D in your Windows guests by borrowing the d3d libraries from Wine, which translate d3d calls into OpenGL, which is then accelerated. These libraries are now part of Virtualbox guest additions software. <br />
<br />
After enabling OpenGL acceleration as described above, reboot the guest into safe mode (press F8 before the Windows screen appears but after the Virtualbox screen disappears), and install Virtualbox guest additions, during install enable checkbox "Direct3D support". Reboot back to normal mode and you should have accelerated Direct3D. <br />
<br />
{{Note | This hack may or may not work for some games depending on what hardware checks they make and what parts of D3D they use.}}<br />
{{Note | This was tested on Windows XP, 7 and 8.1. If method does not work on your Windows version please add data here.}}<br />
<br />
=== VirtualBox on a USB key ===<br />
When using VirtualBox on a USB key, for example to start an installed machine with an ISO image, you will manually have to create VDMKs from the existing drives. However, once the new VMDKs are saved and you move on to another machine, you may experience problems launching an appropriate machine again. To get rid of this issue, you can use the following script to launch VirtualBox. This script will clean up and unregister old VMDK files and it will create new, proper VMDKs for you:<br />
{{bc|<nowiki><br />
#!/bin/bash<br />
<br />
# Erase old VMDK entries<br />
rm ~/.VirtualBox/*.vmdk<br />
<br />
# Clean up VBox-Registry<br />
sed -i '/sd/d' ~/.VirtualBox/VirtualBox.xml<br />
<br />
# Remove old harddisks from existing machines<br />
find ~/.VirtualBox/Machines -name \*.xml | while read file; do<br />
line=`grep -e "type\=\"HardDisk\"" -n $file | cut -d ':' -f 1`<br />
if [ -n "$line" ]; then<br />
sed -i ${line}d $file<br />
sed -i ${line}d $file<br />
sed -i ${line}d $file<br />
fi<br />
sed -i "/rg/d" $file<br />
done<br />
<br />
# Delete prev-files created by VirtualBox<br />
find ~/.VirtualBox/Machines -name \*-prev -exec rm '{}' \;<br />
<br />
# Recreate VMDKs<br />
ls -l /dev/disk/by-uuid | cut -d ' ' -f 9,11 | while read ln; do<br />
if [ -n "$ln" ]; then<br />
uuid=`echo "$ln" | cut -d ' ' -f 1`<br />
device=`echo "$ln" | cut -d ' ' -f 2 | cut -d '/' -f 3 | cut -b 1-3`<br />
<br />
# determine whether drive is mounted already<br />
checkstr1=`mount | grep $uuid`<br />
checkstr2=`mount | grep $device`<br />
checkstr3=`ls ~/.VirtualBox/*.vmdk | grep $device`<br />
if [[ -z "$checkstr1" && -z "$checkstr2" && -z "$checkstr3" ]]; then<br />
VBoxManage internalcommands createrawvmdk -filename ~/.VirtualBox/$device.vmdk -rawdisk /dev/$device -register<br />
fi<br />
fi<br />
done<br />
<br />
# Start VirtualBox<br />
VirtualBox<br />
</nowiki>}}<br />
Note that your user has to be added to the "disk" group to create VMDKs out of existing drives.<br />
<br />
=== Run a native Arch Linux installation inside VirtualBox ===<br />
<br />
If you have a dual boot system between Arch Linux and another operating system, it can become rapidly tedious to switch back and forth if you need to work in both. Also, by using virtual machines, you just have a tiny fragment of your computer power, which can cause issues when working on projects requiring performance.<br />
<br />
This guide will let you reuse, in a virtual machine, your native Arch Linux installation when you are running your second operating system. This way, you keep the ability to run each operating system natively, but have the option to run your Arch Linux installation inside a virtual machine.<br />
<br />
==== Make sure you have a persistent naming scheme ====<br />
<br />
Depending on your hard drive setup, device files representing your hard drives may appear differently when you will run your Arch Linux installation natively or in virtual machine. This problem occurs when using [[RAID#Implementation|FakeRAID]] for example. The fake RAID device will be mapped in {{ic|/dev/mapper/}} when you run your GNU/Linux distribution natively, while the devices are still accessible separately. However, in your virtual machine, it can appear without any mapping in {{ic|/dev/sdaX}} for example, because the drivers controlling the fake RAID in your host operating system (e.g. Windows) are abstracting the fake RAID device.<br />
<br />
To circumvent this problem, we will need to use an addressing scheme that is persistent to both systems. This can be achieved using [[Fstab#UUIDs|UUIDs]] in your {{ic|/etc/fstab}} file. Make sure your [[fstab]] file is using UUIDs, otherwise fix this issue. Read [[fstab]] and [[Persistent block device naming]].<br />
<br />
{{ic|/etc/fstab}} is not the only location where UUIDs are used. Bootloaders and boot managers make use of them too. Now, make sure these are really using UUIDs.<br />
<br />
; [[GRUB Legacy]]<br />
If you are still using the old [[GRUB Legacy]], maybe is it [[GRUB Legacy#Upgrading to GRUB2|time to upgrade]], since this package is now dropped from the official Arch Linux repositories. If you want to keep it, edit {{ic|/boot/grub/menu.lst}} and replace the {{ic|1=root=/dev/sdXX}} statement in your Arch Linux boot entry by the Linux UUID mapping in {{ic|/dev/disk/by-uuid/}} corresponding to your root partition.<br />
<br />
title Arch Linux<br />
root<br />
kernel /vmlinuz-linux root=''/dev/disk/by-uuid/0a3407de-014b-458b-b5c1-848e92a327a3'' ro vga=773<br />
initrd /initramfs-linux-vbox.img<br />
<br />
Repeat the process here, for the fallback entry.<br />
<br />
; [[GRUB]]<br />
If you are running the most recent version of [[GRUB]]; you have nothing to do. Yet another reason to upgrade to GRUB 2.<br />
<br />
{{Warning|<br />
* Make sure your host partition is only accessible in read only from your Arch Linux virtual machine, this will avoid risk of corruptions if you were to corrupt that host partition by writing on it due to lack of attention.<br />
* You should NEVER allow VirtualBox to boot from the entry of your second operating system, which, as a reminder, is used as the host for this virtual machine! Take thus a special care especially if your default boot loader/boot manager entry is your other operating system. Give a more important timeout or put it below in the order of preferences.}}<br />
<br />
==== Make sure your mkinitcpio image is correct ====<br />
<br />
Make sure your [[Mkinitcpio|mkinitcpio]] configuration uses the [[Mkinitcpio#HOOKS|HOOK]] {{ic|block}}:<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
[...]<br />
HOOKS="base udev autodetect modconf ''block'' filesystems keyboard fsck"<br />
[...]}}<br />
<br />
If it is not present, add it, and regenerate your initramfs, with the command {{ic|# mkinitcpio -p linux}}, whose [[Mkinitcpio#Image creation and activation|usage is described here in detail]].<br />
<br />
==== Create a VM configuration to boot from the physical drive ====<br />
<br />
===== Create a raw disk .vmdk image =====<br />
<br />
Now, we need to create a new virtual machine which will use a [https://www.virtualbox.org/manual/ch09.html#rawdisk RAW disk] as virtual drive, for that we will use a ~ 1Kio VMDK file which will be mapped to a physical disk. Unfortunately, VirtualBox does not have this option in the GUI, so we will have to use the console and use an internal command of {{ic|VBoxManage}}.<br />
<br />
Boot the host which will use the Arch Linux virtual machine. The command will need to be adapted according to the host you have.<br />
<br />
; On a GNU/Linux host:<br />
<br />
There is 3 ways to achieve this: login as root, changing the access right of the device with {{ic|chmod}}, adding your user to the {{ic|disk}} group. The latter way is the more elegant, let us proceed that way:<br />
<br />
# gpasswd -a ''your_user'' disk<br />
<br />
Apply the new group settings with:<br />
<br />
$ newgrp<br />
<br />
Now, you can use the command:<br />
<br />
$ VBoxManage internalcommands createrawvmdk -filename ''/path/to/file.vmdk'' -rawdisk ''/dev/sdb'' -register <br />
<br />
Adapt the above command to your need, especially the path and filename of the VMDK location and the raw disk location to map which contain your Arch Linux installation.<br />
<br />
; On a Windows host:<br />
<br />
Open a command prompt must be run as administrator. {{Tip|On Windows, open your start menu/start screen, type {{ic|cmd}}, and type {{ic|Ctrl+Shift+Enter}}, this is a shortcut to execute the selected program with admin rights.}}<br />
<br />
On Windows, as the disk filename convention is different from UNIX, use this command to determine what drives you have in your Windows system and their location:{{hc|# wmic diskdrive get name,size,model|<br />
Model Name Size<br />
WDC WD40EZRX-00SPEB0 ATA Device \\.\PHYSICALDRIVE1 4000783933440<br />
KINGSTON SVP100S296G ATA Device \\.\PHYSICALDRIVE0 96024821760<br />
Hitachi HDT721010SLA360 ATA Device \\.\PHYSICALDRIVE2 1000202273280<br />
Innostor Ext. HDD USB Device \\.\PHYSICALDRIVE3 1000202273280}}<br />
<br />
In this example, as the Windows convention is {{ic|\\.\PhysicalDriveX}} where X is a number from 0, {{ic|\\.\PHYSICALDRIVE1}} could be analogous to {{ic|/dev/sdb}} from the Linux disk terminology.<br />
<br />
To use the {{ic|VBoxManage}} command on Windows, you can either, change the current directory to your VirtualBox installation folder first with {{ic|cd C:\Program Files\Oracle\VirtualBox\}}<br />
<br />
# .\VBoxManage.exe internalcommands createrawvmdk -filename C:\file.vmdk -rawdisk \\.\PHYSICALDRIVE1<br />
<br />
or use the absolute path name: <br />
<br />
# "C:\Program Files\Oracle\VirtualBox\VBoxManage.exe" internalcommands createrawvmdk -filename C:\file.vmdk -rawdisk \\.\PHYSICALDRIVE1<br />
<br />
; On another OS host:<br />
<br />
There are other limitations regarding the aforementioned command when used in other operating systems like OS X, please thus [https://www.virtualbox.org/manual/ch09.html#rawdisk read carefully the manual page], if you are concerned.<br />
<br />
===== Create the VM configuration file =====<br />
<br />
{{Note|<br />
* To make use of the VBoxManage command on Windows, you need to change the current directory to your VirtualBox installation folder first: cd C:\Program Files\Oracle\VirtualBox\.<br />
* Windows makes use of backslashes instead of slashes, please replace all slashes / occurrences by backslashes \ in the commands that follow when you will use them.}}<br />
<br />
After, we need to create a new machine (replace the ''VM_name'' to your convenience) and register it with VirtualBox.<br />
<br />
$ VBoxManage createvm -name ''VM_name'' -register<br />
<br />
Then, the newly raw disk needs to be attached to the machine. This will depend if your computer or actually the root of your native Arch Linux installation is on an IDE or a SATA controller.<br />
<br />
If you need an IDE controller:<br />
<br />
$ VBoxManage storagectl ''VM_name'' --name "IDE Controller" --add ide<br />
$ VBoxManage storageattach ''VM_name'' --storagectl "IDE Controller" --port 0 --device 0 --type hdd --medium /path/to/file.vmdk<br />
<br />
otherwise:<br />
<br />
$ VBoxManage storagectl ''VM_name'' --name "SATA Controller" --add sata<br />
$ VBoxManage storageattach ''VM_name'' --storagectl "SATA Controller" --port 0 --device 0 --type hdd --medium /path/to/file.vmdk<br />
<br />
While you continue using the CLI, it is recommended to use the VirtualBox GUI, to personalise the virtual machine configuration. Indeed, you must specify its hardware configuration as close as possible as your native machine: turning on the 3D acceleration, increasing video memory, setting the network interface, etc.<br />
<br />
==== Install the Guest Additions ====<br />
<br />
Finally, you may want to seamlessly integrate your Arch Linux with your host operating system and allow copy pasting between both OSes. Please refer to [[#Install the Guest Additions]] for that, since this Arch Linux virtual machine is basically an Arch Linux guest.<br />
<br />
{{Warning|For [[Xorg]] to work in natively and in the virtual machine, since obviously it will be using different drivers, it is best if there is no {{ic|/etc/X11/xorg.conf}}, so Xorg will pick up everything it needs on the fly. However, if you really do need your own Xorg configuration, maybe is it worth to set your default systemd target to {{ic|multi-user.target}} with {{ic|# systemctl isolate graphical.target}} (more details at [[Systemd#Targets table]] and [[Systemd#Change current target]]. In that way, the graphical interface is disabled (i.e. Xorg is not launched) and after you logged in, you can {{ic|startx}}} manually with a custom {{ic|xorg.conf}}.}}<br />
<br />
=== Install a native Arch Linux system from VirtualBox ===<br />
<br />
In some cases it may be useful to install a native Arch Linux system while running another operating system: one way to accomplish this is to perform the installation through VirtualBox on a [http://www.virtualbox.org/manual/ch09.html#rawdisk raw disk]. If the existing operating system is Linux based, you may want to consider following [[Install from Existing Linux]] instead.<br />
<br />
This scenario is very similar to [[#Run a native Arch Linux installation inside VirtualBox]], but will follow those steps in a different order: start by [[#Create a raw disk .vmdk image]], then [[#Create the VM configuration file]].<br />
<br />
Now, you should have a working VM configuration whose virtual VMDK disk is tied to a real disk. The installation process is exactly the same as the steps described in [[#Installation steps for Arch Linux guests]], but [[#Make sure you have a persistent naming scheme]] and [[#Make sure your mkinitcpio image is correct]].<br />
<br />
{{Warning|<br />
*For BIOS systems and MBR disks, do not install a bootloader inside your virtual machine, this will not work since the MBR is not linked to the MBR of your real machine and your virtual disk is only mapped to a real partition without the MBR.<br />
*For UEFI systems without [[Wikipedia:Compatibility Support Module#CSM|CSM]] and GPT disks, the installation will not work at all since:<br />
:*the [[Wikipedia:EFI System partition|ESP]] partition is not mapped to your virtual disk and Arch Linux requires to have the Linux kernel on it to boot as an EFI application (see [[EFISTUB]] for details);<br />
:*and the efivars, if you are installing Arch Linux using the EFI mode brought by VirtualBox, are not the one of your real system: the bootmanager entries will hence not be registered.<br />
*This is why, it is recommended to create your partitions in a native installation first, otherwize the partitions will not be taken into consideration in your MBR/GPT partition table.}}<br />
<br />
After completing the installation, boot your computer natively with an GNU/Linux installation media (whether it be Arch Linux or not), [[Beginner's Guide#Chroot and configure the base system|chroot]] into your installed Arch Linux installation and [[Beginner's Guide#Install and configure a bootloader|#Install and configure a bootloader]].<br />
<br />
=== Move a native Windows installation to a virtual machine ===<br />
<br />
If you want to migrate an existing native Windows installation to a virtual machine which will be used with VirtualBox on GNU/Linux, this use case is for you. This section only covers native Windows installation using the MSDOS/Intel partition scheme. Your Windows installation must reside on the first MBR partition for this operation to success. Operation for other partitions are available but have been untested (see [[#Known limitations]] for details).<br />
<br />
{{Warning|If you are using an OEM version of Windows, this process is unauthorized by the end user license license. Indeed, the OEM license typically states the Windows install is tied with the hardware together. Transferring a Windows install to a virtual machine remove this link. Make thus sure you have a full Windows install or a volume license model before continuing. If you have a full Windows license but the latter is not coming in volume, nor as a special license for several PCs, this means you will have to remove the native installation after the transfer operation has been achieved.}}<br />
<br />
A couple of tasks are required to be done inside your native Windows installation first, then on your GNU/Linux host.<br />
<br />
==== Tasks on Windows ====<br />
<br />
The first three following points comes from [https://www.virtualbox.org/wiki/Migrate_Windows#HAL this outdated VirtualBox wiki page], but are updated here.<br />
<br />
* Remove IDE/ATA controllers checks (Windows XP only): Windows memorize the IDE/ATA drive controllers it has been installed on and will not boot if it detects these have changed. The solution proposed by Microsoft is to reuse the same controller or use one of the same serial, which is impossible to achieve since we are using a Virtual Machine. [https://www.virtualbox.org/wiki/Migrate_Windows#HardDiskSupport MergeIDE], a German tool, developped upon another other solution proposed by Microsoft can be used. That solution basically consists in taking all IDE/ATA controller drivers supported by Windows XP from the initial driver archive (the location is hard coded, or specify it as the first argument to the {{ic|.bat}} script), installing them and registering them with the regedit database.<br />
<br />
* Use the right type of Hardware Abstraction Layer (old 32 bits Windows versions): Microsoft ships 3 default versions: {{ic|Hal.dll}} (Standard PC), {{ic|Halacpi.dll}} (ACPI HAL) and {{ic|Halaacpi.dll}} (ACPI HAL with IO APIC). Your Windows install could come installed with the first or the second version. In that way, please [https://www.virtualbox.org/manual/ch08.html#idp56927888 disable the ''Enable IO/APIC'' VirtualBox extended feature].<br />
<br />
* Disable any AGP device driver (only outdated Windows versions): If you have the files {{ic|agp440.sys}} or {{ic|intelppm.sys}} inside the {{ic|C:\Windows\SYSTEM32\drivers\}} directory, remove it. As VirtualBox uses a PCI virtual graphic card, this can cause problems when this AGP driver is used.<br />
<br />
* Create a Windows recovery disk: In the following steps, if things turn bad, you will need to repair your Windows installation. Make sure you have an install media at hand, or create one with ''Create a recovery disk'' from Vista SP1, ''Create a system repair disc'' on Windows 7 or ''Create a recovery drive'' on Windows 8.x).<br />
<br />
==== Tasks on GNU/Linux ====<br />
<br />
* Reduce the native Windows partition size to the size Windows actually needs with {{ic|ntfsresize}} available from {{Pkg|ntfs-3g}}. The size you will specify will be the same size of the VDI that will be created in the next step. If this size is too low, you may break your Windows install and the latter might not boot at all.<br />
<br />
:Use the {{ic|--no-action}} option first to run a test:<br />
:{{bc|# ntfsresize --no-action --size ''52Gi'' ''/dev/sda1''}}<br />
<br />
:If only the previous test succeeded, execute this command again, but this time without the aforementioned test flag.<br />
<br />
* Install VirtualBox on your GNU/Linux host (see [[#Installation steps for Arch Linux hosts]] if your host is Arch Linux).<br />
<br />
* Create the Windows disk image from the beginning of the drive to the end of the first partition where is located your Windows installation. Copying from the beginning of the disk is necessary because the MBR space at the beginning of the drive needs to be on the virtual drive along with the Windows partition. In this example two following partitions {{ic|sda2}} and {{ic|sda3}}will be later removed from the partition table and the MBR bootloader will be updated.<br />
<br />
:{{bc|<nowiki># sectnum=$(( $(cat /sys/block/''sda/sda1''/start) + $(cat /sys/block/''sda/sda1''/size) ))</nowiki>}}<br />
:Using {{ic|cat /sys/block/''sda/sda1''/size}} will output the number of total sectors of the first partition of the disk {{ic|sda}}. Adapt where necessary.<br />
<br />
:{{bc|<nowiki># dd if=''/dev/sda'' bs=512 count=$sectnum | VBoxManage convertfromraw stdin ''windows.vdi'' $(( $sectnum * 512 ))</nowiki>}}<br />
:We need to display the size in byte, {{ic|$(( $sectnum * 512 ))}} will convert the sector numbers to bytes.<br />
<br />
* Since you created your disk image as root, set the right ownership to the virtual disk image: {{ic|# chown $USER:users windows.vdi}}.<br />
<br />
* Create your virtual machine configuration file and use the virtual disk created previously as the main virtual hard disk.<br />
<br />
* Try to boot your Windows VM, it may just work. First though remove and repair disks from the boot process as it may interfere (and likely will) booting into safe-mode.<br />
<br />
* Attempt to boot your Windows virtual machine in safe mode (press the F8 key before the Windows logo shows up)... if running into boot issues, read [[#Fix MBR and Microsoft bootloader]]. In safe-mode, drivers will be installed likely by the Windows plug-and-play detection mechanism [http://i.imgur.com/hh1RrSp.png view]. Additionally, install the VirtualBox Guest Additions via the menu ''Devices'' > ''Insert Guest Additions CD image...''. If a new disk dialog does not appear, navigate to the CD drive and start the installer manually.<br />
<br />
* You should finally have a working Windows virtual machine. Do not forget to read the [[#Known limitations]].<br />
<br />
==== Fix MBR and Microsoft bootloader ====<br />
<br />
If your Windows virtual machine refuses to boot, you may need to apply the following modifications to your virtual machine.<br />
<br />
*Boot a GNU/Live live distribution inside your virtual machine before Windows starts up.<br />
<br />
*Remove other partitions entries from the virtual disk MBR. Indeed, since we copied the MBR and only the Windows partition, the entries of the other partitions are still present in the MBR, but the partitions are not available anymore. Use {{ic|fdisk}} to achieve this for example.<br />
:{{bc|<nowiki>fdisk ''/dev/sda''<br />
Command (m for help): a<br />
Partition number (''1-3'', default ''3''): ''1''</nowiki>}}<br />
<br />
*Write the updated partition table to the disk (this will recreate the MBR) using the {{ic|m}} command inside {{ic|fdisk}}.<br />
<br />
*Use {{Pkg|testdisk}} (see [http://www.cgsecurity.org/index.html?testdisk.html here] for details) to add a generic MBR:<br />
:{{bc|# testdisk > ''Disk /dev/sda...''' > [Proceed] > [Intel] Intel/PC partition > [MBR Code] Write TestDisk MBR to first sector > Write a new copy of MBR code to first sector? (Y/n) > Y > Write a new copy of MBR code, confirm? (Y/N) > A new copy of MBR code has been written. You have to reboot for the change to take effect. > [OK]}}<br />
<br />
*With the new MBR and updated partition table, your Windows virtual machine should be able to boot. If you are still encountering issues, boot your Windows recovery disk from on of the previous step, and inside your Windows RE environment, execute the commands [http://support.microsoft.com/kb/927392 described here].<br />
<br />
==== Known limitations ====<br />
<br />
*Your virtual machine can sometimes hang and overrun your RAM, this can be caused by conflicting drivers still installed inside your Windows virtual machine. Good luck to find them!<br />
*Additional software expecting a given driver beneath may either not be disabled/uninstalled or needs to be uninstalled first as the drivers that are no longer available.<br />
*Your Windows installation must reside on the first partition for the above process to work. If this requirement is not met, the process might be achieved too, but this had not been tested. This will require either copying the MBR and editing in hexadecimal see [http://superuser.com/questions/237782/virtualbox-booting-cloned-disk/253417#253417 VirtualBox: booting cloned disk] or will require to fix the partition table [http://gparted.org/h2-fix-msdos-pt.php manually] or by repairing Windows with the recovery disk you created in a previous step. Let us consider our Windows installation on the second partition; we will copy the MBR, then the second partition where to the disk image. {{ic|VBoxManage convertfromraw}} needs the total number of bytes that will be written: calculated thanks to the size of the MBR (the start of the first partition) plus the size of the second (Windows) partition. {{ic|<nowiki>{ dd if=/dev/sda bs=512 count=$(cat /sys/block/sda/sda1/start) ; dd if=/dev/sda2 bs=512 count=$(cat /sys/block/sda/sda2/size) ; } | VBoxManage convertfromraw stdin windows.vdi $(( ($(cat /sys/block/sda/sda1/start) + $(cat /sys/block/sda/sda2/size)) * 512 ))</nowiki>}}.<br />
<br />
== Troubleshooting ==<br />
<br />
=== VERR_ACCESS_DENIED ===<br />
<br />
To access the raw vmdk image on a windows host, run the VirtualBox GUI as administrator.<br />
<br />
=== Keyboard and mouse are blocked in my virtual machine ===<br />
<br />
This means your virtual machine has captured the input of your keyboard and your mouse. Simply press the right {{ic|Ctrl}} key and your input should control your host again.<br />
<br />
To control transparently your virtual machine with your mouse going back and forth your host, without having to press any key, and thus have a seamless integration, install the guest additions inside the guest. Read from the [[#Install the Guest Additions]] step if you guest is Arch Linux, otherwise read the official VirtualBox help.<br />
<br />
=== Cannot send CTRL+ALT+Fn key to my virtual machine ===<br />
<br />
Your guest operating system is a GNU/Linux distribution and you want to open a new TTY shell by hitting {{ic|Ctrl+Alt+F2}} or exit your current X session with {{ic|Ctrl+Alt+Backspace}}. If you type these keyboard shortcuts without any adaptation, the guest will not receive any input and the host (if it is a GNU/Linux distribution too) will intercept these shortcut keys. To send {{ic|Ctrl+Alt+F2}} to the guest for example, simply hit your ''Host Key'' (usually the right {{ic|Ctrl}} key) and press {{ic|F2}} simultaneously.<br />
<br />
=== Fix ISO images problems ===<br />
<br />
While VirtualBox can mount ISO images without problem, there are some image formats which cannot reliably be converted to ISO. For instance, ccd2iso ignores .ccd and .sub files, which can give disk images with broken files. <br />
<br />
In this case, you will either have to use [[CDEmu]] for Linux inside VirtualBox or any other utility used to mount disk images.<br />
<br />
=== VirtualBox GUI does not match my GTK Theme ===<br />
<br />
See [[Uniform Look for Qt and GTK Applications]] for information about theming Qt based applications like Virtualbox.<br />
<br />
=== OpenBSD unusable when virtualisation instructions unavailable ===<br />
<br />
While OpenBSD is reported to work fine on other hypervisors without virtualisation instructions (VT-x AMD-V) enabled, an OpenBSD virtual machine running on VirtualBox without these instructions will be unusable, manifesting with a bunch of segmentation faults. Starting VirtualBox with the ''-norawr0'' argument [https://www.virtualbox.org/ticket/3947 may solve the problem]. You can do it like this:<br />
$ VBoxSDL -norawr0 -vm ''name_of_OpenBSD_VM''<br />
<br />
=== VBOX_E_INVALID_OBJECT_STATE (0x80BB0007) ===<br />
<br />
This can occur if a VM is exited ungracefully. The solution to unlock the VM is trivial:<br />
$ VBoxManage controlvm ''virtual_machine_name'' poweroff<br />
<br />
=== USB subsystem is not working on the host or guest ===<br />
<br />
Your user must be in the {{ic|vboxusers}} group, and you need to install the [[#Extension pack|extension pack]] if you want USB 2 support. Then you will be able to enable USB 2 in the VM settings and add one or several filters for the devices you want to access from the guest OS.<br />
<br />
Sometimes, on old Linux hosts, the USB subsystem is not auto-detected resulting in an error {{ic|Could not load the Host USB Proxy service: VERR_NOT_FOUND}} or in a not visible USB drive on the host, [https://bbs.archlinux.org/viewtopic.php?id=121377 even when the user is in the '''vboxusers''' group]. This problem is due to the fact that VirtualBox switched from ''usbfs'' to ''sysfs'' in version 3.0.8. If the host does not understand this change, you can revert to the old behaviour by defining the following environment variable in any file that is sourced by your shell (e.g. your {{ic|~/.bashrc}} if you are using ''bash''):<br />
<br />
{{hc|~/.bashrc|VBOX_USB<nowiki>=</nowiki>usbfs}}<br />
<br />
Then make sure, the environment has been made aware of this change (reconnect, source the file manually, launch a new shell instance or reboot).<br />
<br />
Also make sure that your user is a member of the {{ic|storage}} group.<br />
<br />
=== Failed to create the host-only network interface ===<br />
<br />
Make sure all required kernel modules are loaded. See [[#Load the VirtualBox kernel modules]].<br />
<br />
=== WinXP: Bit-depth cannot be greater than 16 ===<br />
<br />
If you are running at 16-bit color depth, then the icons may appear fuzzy/choppy. However, upon attempting to change the color depth to a higher level, the system may restrict you to a lower resolution or simply not enable you to change the depth at all. To fix this, run {{ic|regedit}} in Windows and add the following key to the Windows XP VM's registry:<br />
[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows NT\Terminal Services]<br />
"ColorDepth"=dword:00000004<br />
<br />
Then update the color depth in the "desktop properties" window. If nothing happens, force the screen to redraw through some method (i.e. {{ic|Host+f}} to redraw/enter full screen).<br />
<br />
=== Use serial port in guest OS ===<br />
<br />
Check you permission for the serial port:<br />
$ /bin/ls -l /dev/ttyS*<br />
crw-rw---- 1 root uucp 4, 64 Feb 3 09:12 /dev/ttyS0<br />
crw-rw---- 1 root uucp 4, 65 Feb 3 09:12 /dev/ttyS1<br />
crw-rw---- 1 root uucp 4, 66 Feb 3 09:12 /dev/ttyS2<br />
crw-rw---- 1 root uucp 4, 67 Feb 3 09:12 /dev/ttyS3<br />
<br />
Add your user to the {{ic|uucp}} group.<br />
# gpasswd -a $USER uucp <br />
and log out and log in again.<br />
<br />
=== Windows 8.x Error Code 0x000000C4===<br />
<br />
If you get this error code while booting, even if you choose OS Type Win 8, try to enable the {{ic|CMPXCHG16B}} CPU instruction:<br />
<br />
$ vboxmanage setextradata ''virtual_machine_name'' VBoxInternal/CPUM/CMPXCHG16B 1<br />
<br />
=== Windows 8 VM fails to boot with error "ERR_DISK_FULL" ===<br />
<br />
Situation: Your Windows 8 VM refuses to start. VirtualBox throws an error stating the virtual disk is full. However, you are certain that the disk is not full. <br />
Bring up your VM's settings at ''Settings > Storage > Controller:SATA'' and select "Use Host I/O Cache".<br />
<br />
=== Linux guests have slow/distorted audio ===<br />
<br />
The AC97 audio driver within the Linux kernel occasionally guesses the wrong clock settings when running inside Virtual Box, leading to audio that is either too slow or too fast. To fix this, create a file in {{ic|/etc/modprobe.d}} with the following line:<br />
<br />
options snd-intel8x0 ac97_clock=48000<br />
<br />
=== Guest freezes after starting Xorg ===<br />
<br />
Faulty or missing drivers may cause the guest to freeze after starting Xorg, see for example [https://bbs.archlinux.org/viewtopic.php?pid=1167838] and [https://bbs.archlinux.org/viewtopic.php?id=156079]. Try disabling 3D acceleration in ''Settings > Display'', and check if all [[Xorg]] drivers are installed.<br />
<br />
=== "NS_ERROR_FAILURE" and missing menu items ===<br />
<br />
If you encounter this message when first time starting the virtual machine:<br />
<br />
{{bc|Failed to open a session for the virtual machine debian.<br />
Could not open the medium '/home/.../VirtualBox VMs/debian/debian.qcow'.<br />
QCow: Reading the L1 table for image '/home/.../VirtualBox VMs/debian/debian.qcow' failed (VERR_EOF).<br />
VD: error VERR_EOF opening image file '/home/.../VirtualBox VMs/debian/debian.qcow' (VERR_EOF).<br />
<br />
Result Code: <br />
NS_ERROR_FAILURE (0x80004005)<br />
Component: <br />
Medium<br />
}}<br />
<br />
Exit VirtualBox, delete all files of the new machine and from virtualbox config file remove the last line in {{ic|MachineRegistry}} menu (or the offending machine you are creating):<br />
<br />
{{hc|~/.config/VirtualBox/VirtualBox.xml|2=<br />
...<br />
<MachineRegistry><br />
<MachineEntry uuid="{00000000-0000-0000-0000-000000000000}" src="/home/void/VirtualBox VMs/debian/debian.vbox"/><br />
<MachineEntry uuid="{00000000-0000-0000-0000-000000000000}" src="/home/void/VirtualBox VMs/ubuntu/ubuntu.vbox"/><br />
<strike><MachineEntry uuid="{00000000-0000-0000-0000-000000000000}" src="/home/void/VirtualBox VMs/lastvmcausingproblems/lastvmcausingproblems.qcow"/></strike><br />
</MachineRegistry><br />
...<br />
}}<br />
<br />
This happens sometimes when selecting ''QCOW''/''QCOW2''/''QED'' disk format when creating a new virutal disk.<br />
<br />
=== "The specified path does not exist. Check the path and then try again." error in Windows guests ===<br />
<br />
This error message often appears when running an .exe file which requires administrator priviliges from a shared folder in windows guests. See [https://www.virtualbox.org/ticket/5732 the bug report] for details.<br />
<br />
There are several workarounds:<br />
<br />
# Disable UAC from Control Panel -> Action Center -> "Change User Account Control settings" from left side pane -> set slider to "Never notify" -> OK and reboot<br />
# Copy the file from the shared folder to the guest and run from there<br />
# Control Panel -> Network and Internet -> Internet Options -> Security -> Trusted Sites -> Sites -> Add "VBOXSVR" as a website<br />
# Start -> type "gpedit.msc" and press Enter -> Computer Configuration -> Administrative Templates -> Windows Components -> Internet Explorer -> Internet Control Panel -> Security Page -> Size to Zone Assignment List -> Add "VBOXSVR" to "2" and reboot<br />
<br />
{{Accuracy|Haven't tested#3 and #4 workarounds myself. If someone can confirm that they are working as well, please delete this note/template.}}<br />
<br />
=== No 64-bit OS client options ===<br />
<br />
When launching a VM client, and no 64-bit options are available, make sure your CPU virtualization capabilities (usually named {{ic|VT-x}}) are enabled in the BIOS.<br />
<br />
== See also ==<br />
<br />
* [https://www.virtualbox.org/manual/UserManual.html VirtualBox User Manual]<br />
* [[Wikipedia:VirtualBox]]</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Kernel_module&diff=358599Kernel module2015-01-29T01:58:42Z<p>Fylwind: /* Manual module handling */ Clarify the "Note" section a bit</p>
<hr />
<div>[[Category:Kernel]]<br />
[[Category:Hardware detection and troubleshooting]]<br />
[[Category:Boot process]]<br />
[[es:Kernel modules]]<br />
[[fr:Kernel modules]]<br />
[[it:Kernel modules]]<br />
[[ja:Kernel modules]]<br />
[[ru:Kernel modules]]<br />
[[zh-CN:Kernel modules]]<br />
{{Related articles start}}<br />
{{Related|Boot debugging}}<br />
{{Related|Kernels}}<br />
{{Related|Kernel parameters}}<br />
{{Related articles end}}<br />
<br />
[[Wikipedia:Loadable_kernel_module|Kernel modules]] are pieces of code that can be loaded and unloaded into the kernel upon demand. They extend the functionality of the kernel without the need to reboot the system. <br />
<br />
== Overview ==<br />
<br />
To create a kernel module, you can read [http://tldp.org/LDP/lkmpg/2.6/html/index.html The Linux Kernel Module Programming Guide]. A module can be configured as built-in or loadable. To dynamically load or remove a module, it has to be configured as a loadable module in the kernel configuration (the line related to the module will therefore display the letter {{ic|M}}).<br />
<br />
Modules are stored in {{ic|/usr/lib/modules/''kernel_release''}}. You can use the command {{ic|uname -r}} to get your current kernel release version.<br />
<br />
{{Note|Module names often use underscores ({{ic|_}}) or dashes ({{ic|-}}); however, those symbols are interchangeable, both when using the {{ic|modprobe}} command and in configuration files in {{ic|/etc/modprobe.d/}}.}}<br />
<br />
== Obtaining information ==<br />
<br />
To show what kernel modules are currently loaded:<br />
<br />
$ lsmod<br />
<br />
To show information about a module:<br />
<br />
$ modinfo ''module_name''<br />
<br />
To list the options that are set for a loaded module:<br />
<br />
$ systool -v -m ''module_name''<br />
<br />
To display the comprehensive configuration of all the modules:<br />
<br />
$ modprobe -c | less<br />
<br />
To display the configuration of a particular module:<br />
<br />
$ modprobe -c | grep ''module_name''<br />
<br />
List the dependencies of a module (or alias), including the module itself:<br />
<br />
$ modprobe --show-depends ''module_name''<br />
<br />
== Automatic module handling ==<br />
<br />
Today, all necessary modules loading is handled automatically by [[udev]], so if you do not need to use any out-of-tree kernel modules, there is no need to put modules that should be loaded at boot in any configuration file. However, there are cases where you might want to load an extra module during the boot process, or blacklist another one for your computer to function properly.<br />
<br />
Extra kernel modules to be loaded during boot are configured as a static list in files under {{ic|/etc/modules-load.d/}}. Each configuration file is named in the style of {{ic|/etc/modules-load.d/<program>.conf}}. Configuration files simply contain a list of kernel modules names to load, separated by newlines. Empty lines and lines whose first non-whitespace character is {{ic|#}} or {{ic|;}} are ignored.<br />
<br />
{{hc|/etc/modules-load.d/virtio-net.conf|<br />
# Load virtio-net.ko at boot<br />
virtio-net}}<br />
<br />
See {{ic|man modules-load.d}} for more details.<br />
<br />
== Manual module handling ==<br />
<br />
Kernel modules are handled by tools provided by {{Pkg|kmod}} package. You can use these tools manually.<br />
<br />
{{Note|1=If you have upgraded your [https://www.archlinux.org/packages/?name=linux kernel] but have not yet rebooted, {{ic|modprobe}} can fail with no error message and exit with code 1 as {{ic|/lib/modules/$(uname -r)/}} no longer exists. If you suspect this, be sure to manually check that the directory exists, or that exit code of the {{ic|modprobe}} command was indeed zero.}}<br />
<br />
To load a module:<br />
<br />
# modprobe ''module_name''<br />
<br />
To load a module by filename (i.e. one that is not installed in {{ic|/lib/modules/$(uname -r)/}}):<br />
<br />
# insmod filename [args]<br />
<br />
To unload a module:<br />
<br />
# modprobe -r ''module_name''<br />
<br />
Or, alternatively:<br />
<br />
# rmmod ''module_name''<br />
<br />
== Setting module options ==<br />
<br />
To pass a parameter to a kernel module, you can use a modprobe configuration file or use the kernel command line.<br />
<br />
=== Using files in /etc/modprobe.d/ ===<br />
<br />
Files in {{ic|/etc/modprobe.d/}} directory can be used to pass module settings to [[udev]], which will use {{ic|modprobe}} to manage the loading of the modules during system boot. Configuration files in this directory can have any name, given that they end with the {{ic|.conf}} extension. The syntax is:<br />
{{hc|/etc/modprobe.d/myfilename.conf|2=<br />
options modname parametername=parametervalue}}<br />
<br />
For example:<br />
<br />
{{hc|/etc/modprobe.d/thinkfan.conf|2=<br />
# On ThinkPads, this lets the 'thinkfan' daemon control fan speed<br />
options thinkpad_acpi fan_control=1}}<br />
<br />
{{Note|If any of the affected modules is loaded from the initramfs, then you will need to add the appropriate {{ic|.conf}} file to {{ic|FILES}} in {{ic|/etc/[[mkinitcpio.conf]]}} or use the {{ic|modconf}} [[Mkinitcpio.conf#HOOKS|hook]], so that it will be included in the initramfs.}}<br />
<br />
=== Using kernel command line ===<br />
<br />
If the module is built into the kernel, you can also pass options to the module using the kernel command line. For all common bootloaders, the following syntax is correct:<br />
<br />
modname.parametername=parametercontents<br />
<br />
For example:<br />
<br />
thinkpad_acpi.fan_control=1<br />
<br />
Simply add this to your bootloader's kernel-line, as described in [[Kernel parameters|Kernel Parameters]].<br />
<br />
== Aliasing ==<br />
<br />
Aliases are alternate names for a module. For example: {{ic|alias my-mod really_long_modulename}} means you can use {{ic|modprobe my-mod}} instead of {{ic|modprobe really_long_modulename}}. You can also use shell-style wildcards, so {{ic|alias my-mod* really_long_modulename}} means that {{ic|modprobe my-mod-something}} has the same effect. Create an alias:<br />
<br />
{{hc|/etc/modprobe.d/myalias.conf|<br />
alias mymod really_long_module_name}}<br />
<br />
Some modules have aliases which are used to automatically load them when they are needed by an application. Disabling these aliases can prevent automatic loading but will still allow the modules to be manually loaded.<br />
<br />
{{hc|/etc/modprobe.d/modprobe.conf|<br />
# Prevent Bluetooth autoload<br />
alias net-pf-31 off}}<br />
<br />
== Blacklisting ==<br />
<br />
Blacklisting, in the context of kernel modules, is a mechanism to prevent the kernel module from loading. This could be useful if, for example, the associated hardware is not needed, or if loading that module causes problems: for instance there may be two kernel modules that try to control the same piece of hardware, and loading them together would result in a conflict.<br />
<br />
Some modules are loaded as part of the [[initramfs]]. {{ic|mkinitcpio -M}} will print out all automatically detected modules: to prevent the initramfs from loading some of those modules, blacklist them in {{ic|/etc/modprobe.d/modprobe.conf}}. Running {{ic|mkinitcpio -v}} will list all modules pulled in by the various hooks (e.g. {{ic|filesystems}} hook, {{ic|block}} hook, etc.). Remember to add that {{ic|.conf}} file to the {{ic|FILES}} section in {{ic|/etc/mkinitcpio.conf}}, if you have not done so already, and rebuild the initramfs once you have blacklisted the modules, and reboot afterwards.<br />
<br />
=== Using files in /etc/modprobe.d/ ===<br />
<br />
Create a {{ic|.conf}} file inside {{ic|/etc/modprobe.d/}} and append a line for each module you want to blacklist, using the {{ic|blacklist}} keyword. If for example you want to prevent the {{ic|pcspkr}} module from loading:<br />
<br />
{{hc|/etc/modprobe.d/nobeep.conf|<br />
# Do not load the 'pcspkr' module on boot.<br />
blacklist pcspkr}}<br />
<br />
{{Note|The {{ic|blacklist}} command will blacklist a module so that it will not be loaded automatically, but the module may be loaded if another non-blacklisted module depends on it or if it is loaded manually.<br />
<br />
However, there is a workaround for this behaviour; the {{ic|install}} command instructs modprobe to run a custom command instead of inserting the module in the kernel as normal, so you can force the module to always fail loading with:<br />
<br />
{{hc|/etc/modprobe.d/blacklist.conf|<br />
...<br />
install ''module_name'' /bin/false<br />
...}}<br />
<br />
This will effectively blacklist that module and any other that depends on it.}}<br />
<br />
=== Using kernel command line ===<br />
<br />
{{Tip|This can be very useful if a broken module makes it impossible to boot your system.}}<br />
<br />
You can also blacklist modules from the bootloader.<br />
<br />
Simply add {{ic|1=modprobe.blacklist=modname1,modname2,modname3}} to your bootloader's kernel line, as described in [[Kernel parameters]].<br />
<br />
{{Note|When you are blacklisting more than one module, note that they are separated by commas only. Spaces or anything else might presumably break the syntax.}}<br />
<br />
== See also ==<br />
<br />
* [[Disable PC Speaker Beep]]</div>Fylwindhttps://wiki.archlinux.org/index.php?title=VCS_package_guidelines&diff=356748VCS package guidelines2015-01-16T23:39:06Z<p>Fylwind: /* Git */ there's no need for extended regex in some of these examples</p>
<hr />
<div>[[Category:Package development]]<br />
[[it:VCS PKGBUILD Guidelines]]<br />
[[ja:VCS PKGBUILD Guidelines]]<br />
[[zh-CN:VCS PKGBUILD Guidelines]]<br />
[[zh-TW:VCS PKGBUILD Guidelines]]<br />
{{Package Guidelines}}<br />
<br />
[[Wikipedia:Revision_control|Version control systems]] can be used for retrieval of source code for both usual statically versioned packages and latest (trunk) version of a development branch. This article covers both cases.<br />
<br />
== Prototypes ==<br />
{{Warning|The prototype files provided in the {{Pkg|abs}} package and in [https://projects.archlinux.org/abs.git/tree/prototypes the ABS Git repository] are ''significantly'' out-of-date. Do ''not'' consider the prototypes to be authoritative in any way. See {{Bug|34485}}.}}<br />
<br />
The {{Pkg|abs}} package for the [[Arch Build System]] provides prototypes for [[CVS]], [[SVN]], [[Git]], [[Mercurial]], and [[Wikipedia:Darcs|Darcs]] [[PKGBUILD]]s. When {{Pkg|abs}} is installed, you can find them in {{ic|/usr/share/pacman}}. Latest versions can be found in the [https://projects.archlinux.org/abs.git/tree/prototypes prototypes directory in the ABS Git repository].<br />
<br />
== Guidelines ==<br />
<br />
* Suffix {{Ic|pkgname}} with {{Ic|-cvs}}, {{Ic|-svn}}, {{Ic|-hg}}, {{Ic|-darcs}}, {{Ic|-bzr}}, {{Ic|-git}} etc. unless the package fetches a specific release.<br />
<br />
* If the resulting package is different after changing the dependencies, URL, sources, etc. increasing the {{Ic|pkgrel}} is mandatory. Touching the {{ic|pkgver}} is not.<br />
<br />
* {{Ic|--holdver}} can be used to prevent [[makepkg]] from updating the {{ic|pkgver}} (see: [https://www.archlinux.org/pacman/makepkg.8.html makepkg(8)])<br />
<br />
* Include what the package conflicts with and provides (e.g. for {{AUR|fluxbox-git}}: {{Ic|1=conflicts=('fluxbox')}} and {{Ic|1=provides=('fluxbox')}}).<br />
<br />
* {{Ic|1=replaces=()}} generally causes unnecessary problems and should be avoided.<br />
<br />
* When using the cvsroot, use {{Ic|anonymous:@}} rather than {{Ic|anonymous@}} to avoid having to enter a blank password or {{Ic|anonymous:password@}}, if one is required.<br />
<br />
* Include the appropriate VCS tool in {{Ic|1=makedepends=()}} ({{pkg|cvs}}, {{pkg|subversion}}, {{pkg|git}}, ...).<br />
<br />
* Because the sources are not static, skip the checksum in {{ic|1=md5sums=()}} by adding {{ic|'SKIP'}}.<br />
<br />
=== VCS sources ===<br />
{{Note|Pacman 4.1 supports the following VCS sources: {{ic|bzr}}, {{ic|git}}, {{ic|hg}} and {{ic|svn}}. See the {{ic|fragment}} section of {{ic|man PKGBUILD}} or [https://www.archlinux.org/pacman/PKGBUILD.5.html PKGBUILD(5)] for a list of supported VCS.}}<br />
<br />
Starting with {{Pkg|pacman}} 4.1, the VCS sources should be specified in the {{ic|1=source=()}} array and will be treated like any other source. {{ic|makepkg}} will clone/checkout/branch the repository into {{ic|$SRCDEST}} (same as {{ic|$startdir}} if not set in [https://www.archlinux.org/pacman/makepkg.conf.5.html makepkg.conf(5)]) and copy it to {{ic|$srcdir}} (in a specific way to each VCS). The local repository is left untouched, thus invalidating the need for a {{ic|-build}} directory.<br />
<br />
The general format of a VCS {{ic|1=source=()}} array is:<br />
source=('[folder::][vcs+]url[#fragment]')<br />
<br />
* {{ic|folder}} (optional) is used to change the default repository name to something more relevant (e.g. than {{ic|trunk}}) or to preserve the previous sources.<br />
* {{ic|vcs+}} is needed for URLs that do not reflect the VCS type, e.g. {{ic|<nowiki>git+http://some_repo</nowiki>}}.<br />
* {{ic|url}} is the URL to the distant or local repository.<br />
* {{ic|#fragment}} (optional) is needed to pull a specific branch or commit. See {{ic|man PKGBUILD}} for more information on the fragments available for each VCS.<br />
<br />
An example Git source array:<br />
<nowiki>source=('project_name::git+http://project_url#branch=project_branch')</nowiki><br />
<br />
=== The pkgver() function ===<br />
<br />
The {{ic|pkgver}} autobump is now achieved via a dedicated {{ic|pkgver()}} function. This allows for better control over the {{ic|pkgver}}, and maintainers should favor a {{ic|pkgver}} that makes sense.<br />
<br />
To use {{ic|pkgver()}}, you still need to declare the {{ic|pkgver}} variable with the most recent value. makepkg will invoke function {{ic|pkgver()}}, and update variable {{ic|pkgver}} accordingly.<br />
<br />
It is recommended to have following version format: ''RELEASE.rREVISION'' where ''REVISION'' is a monotonically increasing number that uniquely identifies the source tree (VCS revisions do this). If there are no public releases and no repository tags then zero could be used as a release number or you can drop ''RELEASE'' completely and use version number that looks like ''rREVISION''. If there are public releases but repo has no tags then the developer should get the release version somehow e.g. by parsing the project files.<br />
<br />
The revision number delimiter ("r" right before REVISION) is important. This delimiter allows to avoid problems in case if upstream decides to make its first release or uses versions with different number of components. E.g. if at revision "455" upstream decides to release version 0.1 then the revision delimiter preserves version monotonicity - {{ic|0.1.r456 > r454}}. Without the delimiter monotonicity fails - {{ic|0.1.456 < 454}}.<br />
<br />
Following are some examples showing the ''intended'' output:<br />
<br />
==== Git ====<br />
<br />
Using the most recent annotated tag reachable from the last commit:<br />
<br />
{{hc|<nowiki><br />
pkgver() {<br />
cd "$pkgname"<br />
git describe --long | sed 's/\([^-]*-g\)/r\1/;s/-/./g'<br />
}</nowiki>|<br />
2.0.r6.ga17a017<br />
}}<br />
<br />
Using the most recent un-annotated tag reachable from the last commit:<br />
<br />
{{hc|<nowiki><br />
pkgver() {<br />
cd "$pkgname"<br />
git describe --long --tags | sed 's/\([^-]*-g\)/r\1/;s/-/./g'<br />
}</nowiki>|<br />
0.71.r115.gd95ee07<br />
}}<br />
<br />
In case if the git tag does not contain dashes then one can use simpler sed expression {{ic|sed 's/-/.r/;s/-/./'}}.<br />
<br />
If tag contains a prefix, like {{ic|v}} or project name then it should be cut off:<br />
<br />
{{hc|<nowiki><br />
pkgver() {<br />
cd "$pkgname"<br />
# cutting off 'foo-' prefix that presents in the git tag<br />
git describe --long | sed 's/^foo-//;s/\([^-]*-g\)/r\1/;s/-/./g'<br />
}</nowiki>|<br />
6.1.r3.gd77e105<br />
}}<br />
<br />
If there are no tags then use number of revisions since beginning of the history:<br />
<br />
{{hc|<nowiki><br />
pkgver() {<br />
cd "$pkgname"<br />
printf "r%s.%s" "$(git rev-list --count HEAD)" "$(git rev-parse --short HEAD)"<br />
}</nowiki>|<br />
r1142.a17a017<br />
}}<br />
<br />
Version and only commit/revision number (SHA1 omitted; however, without a SHA1 quick referencing of an exact revision is lost if not mindful of versioning):<br />
<br />
git describe --long | sed -r 's/-([0-9,a-g,A-G]{7}.*)//' | sed 's/-/./'<br />
<br />
Both methods can also be combined, to support repositories that start without a tag but get tagged later on (uses a bashism):<br />
<br />
{{hc|<nowiki><br />
pkgver() {<br />
cd "$pkgname"<br />
( set -o pipefail<br />
git describe --long | sed 's/\([^-]*-g\)/r\1/;s/-/./g' ||<br />
printf "r%s.%s" "$(git rev-list --count HEAD)" "$(git rev-parse --short HEAD)"<br />
)<br />
}</nowiki>|<br />
r492.4c50e43<br />
}}<br />
<br />
==== Subversion ====<br />
<br />
{{hc|<nowiki><br />
pkgver() {<br />
cd "$pkgname"<br />
local ver="$(svnversion)"<br />
printf "r%s" "${ver//[[:alpha:]]}"<br />
}</nowiki>|<br />
r8546<br />
}}<br />
<br />
{{Note|If the project has releases you should use them instead of the {{ic|0.}}.}}<br />
<br />
==== Mercurial ====<br />
<br />
{{hc|<nowiki><br />
pkgver() {<br />
cd "$pkgname"<br />
printf "r%s.%s" "$(hg identify -n)" "$(hg identify -i)"<br />
}</nowiki>|<br />
r2813.75881cc5391e<br />
}}<br />
<br />
==== Bazaar ====<br />
<br />
{{hc|<nowiki><br />
pkgver() {<br />
cd "$pkgname"<br />
printf "r%s" "$(bzr revno)"<br />
}</nowiki>|<br />
r830<br />
}}<br />
<br />
==== Fallback ====<br />
<br />
In case no satisfactory {{ic|pkgver}} can be extracted from the repository, the current date can be used:<br />
<br />
{{hc|<nowiki><br />
pkgver() {<br />
date +%Y%m%d<br />
}</nowiki>|<br />
20130408<br />
}}<br />
<br />
Although it does not identify source tree state uniquely, so avoid it if possible.<br />
<br />
== Tips ==<br />
<br />
=== Git Submodules ===<br />
Git submodules are a little tricky to do. The idea is to add the URLs of the submodules themselves directly to the sources array and then reference them during prepare(). This could look like this:<br />
<br />
{{bc|<nowiki><br />
source=("git://somewhere.org/something/something.git"<br />
"git://somewhere.org/mysubmodule/mysubmodule.git")<br />
<br />
prepare() {<br />
cd something<br />
git submodule init<br />
git config submodule.mysubmodule.url $srcdir/mysubmodule<br />
git submodule update<br />
}<br />
</nowiki>}}</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Users_and_groups&diff=333137Users and groups2014-08-30T18:18:58Z<p>Fylwind: /* User management */ Use nologin instead of false to avoid conflicting with the Tip underneath</p>
<hr />
<div>[[Category:Security]]<br />
[[de:Benutzer und Gruppen]]<br />
[[es:Users and Groups]]<br />
[[fr:Utilisateurs et Groupes]]<br />
[[it:Users and Groups]]<br />
[[ja:Users and Groups]]<br />
[[ru:Users and Groups]]<br />
[[sr:Users and Groups]]<br />
[[zh-CN:Users and Groups]]<br />
[[zh-TW:Users and Groups]]<br />
{{Related articles start}}<br />
{{Related|DeveloperWiki:UID / GID Database}}<br />
{{Related|polkit}}<br />
{{Related|File permissions and attributes}}<br />
{{Related|Change username}}<br />
{{Related articles end}}<br />
<br />
Users and groups are used on GNU/Linux for [[Wikipedia:access control#Computer security|access control]] — that is, to control access to the system's files, directories, and peripherals. Linux offers relatively simple/coarse access control mechanisms by default. For more advanced options, see [[ACL]] and [[LDAP Authentication]].<br />
<br />
== Overview ==<br />
<br />
A ''user'' is anyone who uses a computer. In this case, we are describing the names which represent those users. It may be Mary or Bill, and they may use the names Dragonlady or Pirate in place of their real name. All that matters is that the computer has a name for each account it creates, and it is this name by which a person gains access to use the computer. Some system services also run using restricted or privileged user accounts.<br />
<br />
Managing users is done for the purpose of security by limiting access in certain specific ways. The superuser (root) has complete access to the operating system and its configuration; it is intended for administrative use only. Unprivileged users can use the [[su]] and [[sudo]] programs for controlled privilege escalation.<br />
<br />
Any individual may have more than one account, as long as they use a different name for each account they create. Further, there are some reserved names which may not be used such as "root".<br />
<br />
Users may be grouped together into a "group", and users may be added to an existing group to utilize the privileged access it grants.<br />
<br />
{{Note|The beginner should use these tools carefully and stay away from having anything to do with any other ''existing'' user account, other than their own.}}<br />
<br />
== Permissions and ownership ==<br />
<br />
From [http://ph7spot.com/musings/in-unix-everything-is-a-file In UNIX Everything is a File]:<br />
<br />
:''The UNIX operating system crystallizes a couple of unifying ideas and concepts that shaped its design, user interface, culture and evolution. One of the most important of these is probably the mantra: "everything is a file," widely regarded as one of the defining points of UNIX.''<br />
<br />
:''This key design principle consists of providing a unified paradigm for accessing a wide range of input/output resources: documents, directories, hard-drives, CD-ROMs, modems, keyboards, printers, monitors, terminals and even some inter-process and network communications. The trick is to provide a common abstraction for all of these resources, each of which the UNIX fathers called a "file." Since every "file" is exposed through the same API, you can use the same set of basic commands to read/write to a disk, keyboard, document or network device.''<br />
<br />
From [http://www.intel-research.net/Publications/Pittsburgh/101220041324_277.pdf Extending UNIX File Abstraction for General-Purpose Networking]:<br />
<br />
:''A fundamental and very powerful, consistent abstraction provided in UNIX and compatible operating systems is the file abstraction. Many OS services and device interfaces are implemented to provide a file or file system metaphor to applications. This enables new uses for, and greatly increases the power of, existing applications — simple tools designed with specific uses in mind can, with UNIX file abstractions, be used in novel ways. A simple tool, such as cat, designed to read one or more files and output the contents to standard output, can be used to read from I/O devices through special device files, typically found under the {{ic|/dev}} directory. On many systems, audio recording and playback can be done simply with the commands, "{{ic|cat /dev/audio > myfile}}" and "{{ic|cat myfile > /dev/audio}}," respectively.''<br />
<br />
Every file on a GNU/Linux system is owned by a user and a group. In addition, there are three types of access permissions: read, write, and execute. Different access permissions can be applied to a file's owning user, owning group, and others (those without ownership). One can determine a file's owners and permissions by viewing the long listing format of the [[Core utilities#ls|ls]] command:<br />
<br />
{{hc|$ ls -l /boot/|total 13740<br />
drwxr-xr-x 2 root root 4096 Jan 12 00:33 grub<br />
-rw-r--r-- 1 root root 8570335 Jan 12 00:33 initramfs-linux-fallback.img<br />
-rw-r--r-- 1 root root 1821573 Jan 12 00:31 initramfs-linux.img<br />
-rw-r--r-- 1 root root 1457315 Jan 8 08:19 System.map26<br />
-rw-r--r-- 1 root root 2209920 Jan 8 08:19 vmlinuz-linux}}<br />
<br />
The first column displays the file's permissions (for example, the file {{ic|initramfs-linux.img}} has permissions {{ic|-rw-r--r--}}). The third and fourth columns display the file's owning user and group, respectively. In this example, all files are owned by the ''root'' user and the ''root'' group.<br />
<br />
{{hc|$ ls -l /media/|total 16<br />
drwxrwx--- 1 root vboxsf 16384 Jan 29 11:02 sf_Shared}}<br />
<br />
In this example, the {{ic|sf_Shared}} directory is owned by the ''root'' user and the ''vboxsf'' group. It is also possible to determine a file's owners and permissions using the stat command:<br />
<br />
Owning user:<br />
<br />
{{hc|$ stat -c %U /media/sf_Shared/|root}}<br />
<br />
Owning group:<br />
<br />
{{hc|$ stat -c %G /media/sf_Shared/|vboxsf}}<br />
<br />
Access rights:<br />
<br />
{{hc|$ stat -c %A /media/sf_Shared/|drwxrwx---}}<br />
<br />
Access permissions are displayed in three groups of characters, representing the permissions of the owning user, owning group, and others, respectively. For example, the characters {{ic|-rw-r--r--}} indicate that the file's owner has read and write permission, but not execute ({{ic|rw-}}), whilst users belonging to the owning group and other users have only read permission ({{ic|r--}} and {{ic|r--}}). Meanwhile, the characters {{ic|drwxrwx---}} indicate that the file's owner and users belonging to the owning group all have read, write, and execute permissions ({{ic|rwx}} and {{ic|rwx}}), whilst other users are denied access ({{ic|---}}). The first character represents the file's type.<br />
<br />
List files owned by a user or group with the ''find'' utility:<br />
<br />
# find / -group [group]<br />
<br />
# find / -user [user]<br />
<br />
A file's owning user and group can be changed with the ''chown'' (change owner) command. A file's access permissions can be changed with the ''chmod'' (change mode) command.<br />
<br />
See [http://linux.die.net/man/1/chown man chown], [http://linux.die.net/man/1/chmod man chmod], and [http://www.linux.com/learn/tutorials/309527-understanding-linux-file-permissions Linux file permissions] for additional detail.<br />
<br />
== File list ==<br />
<br />
{{Warning|Do not edit these files by hand. There are utilities that properly handle locking and avoid invalidating the format of the database. See [[#User management]] and [[#Group management]] for an overview.}}<br />
<br />
{| class="wikitable"<br />
! File || Purpose<br />
|-<br />
| {{ic|/etc/shadow}} || Secure user account information<br />
|-<br />
| {{ic|/etc/passwd}} || User account information<br />
|-<br />
| {{ic|/etc/gshadow}} || Contains the shadowed information for group accounts<br />
|-<br />
| {{ic|/etc/group}} || Defines the groups to which users belong<br />
|-<br />
| {{ic|/etc/sudoers}} || List of who can run what by sudo<br />
|-<br />
| {{ic|/home/*}} || Home directories<br />
|}<br />
<br />
== User management ==<br />
<br />
To list users currently logged on the system, the ''who'' command can be used.<br />
<br />
To add a new user, use the ''useradd'' command:<br />
<br />
# useradd -m -g [initial_group] -G [additional_groups] -s [login_shell] [username]<br />
<br />
* {{ic|-m}} creates the user home directory as {{ic|/home/''username''}}. Within their home directory, a non-root user can write files, delete them, install programs, and so on.<br />
* {{ic|-g}} defines the group name or number of the user's initial login group. If specified, the group name must exist; if a group number is provided, it must refer to an already existing group. If not specified, the behaviour of ''useradd'' will depend on the {{ic|USERGROUPS_ENAB}} variable contained in {{ic|/etc/login.defs}}. The default behaviour ({{ic|USERGROUPS_ENAB yes}}) is to create a group with the same name as the username, with {{ic|GID}} equal to {{ic|UID}}.<br />
* {{ic|-G}} introduces a list of supplementary groups which the user is also a member of. Each group is separated from the next by a comma, with no intervening spaces. The default is for the user to belong only to the initial group.<br />
* {{ic|-s}} defines the path and file name of the user's default login shell. After the boot process is complete, the default login shell is the one specified here. Ensure the chosen shell package is installed if choosing something other than [[Bash]].<br />
<br />
{{Warning|The login shell should be one of those listed in {{ic|/etc/shells}}, unless the shell is intended to be non-functional (e.g. {{ic|/usr/bin/nologin}}). For programs that use PAM, this is checked by the {{ic|pam_shells}} module.}}<br />
<br />
{{Note|The password for the newly created user must then be defined, using ''passwd'' as explained [[#Other_examples_of_user_management|below]].}}<br />
<br />
{{Tip|In case you need to create an user for a specific service, use {{ic|/usr/bin/nologin}} as shell.}} <br />
<br />
=== Example adding a user ===<br />
<br />
On a typical desktop system, use the following command to add a new user named {{ic|archie}}, specify Bash as their login shell and add them to the {{ic|wheel}} group (see the entry in [[#User groups]] for details):<br />
<br />
# useradd -m -G wheel -s /bin/bash archie<br />
<br />
This command will also automatically create a group called {{ic|archie}} with the same GID as the UID of the user {{ic|archie}} and makes this the default group for {{ic|archie}} on login. Making each user have their own group (with group name same as user name and GID same as UID) is the preferred way to add users.<br />
<br />
You could also make the default group something else, e.g. {{ic|users}}:<br />
<br />
# useradd -m -g users -G wheel -s /bin/bash archie<br />
<br />
However, this is '''not''' recommended for multi-user systems. Typically, the method for facilitating shared write access for specific groups of users while keeping home directories private is setting user [[umask]] value to {{ic|002}}, meaning the default group ({{ic|users}} in the example above) will by default always have write access to any file you create. The user's home folder, which is owned by a group with group name same as user name, will be read-only for other system users, while shared files/folders can be made writeable by default for everyone in the operative group. The owning group can be automatically fixed to the group which owns the parent directory by setting the group sticky bit on this directory:<br />
<br />
# chmod g+s ''our_shared_directory''<br />
<br />
Otherwise the file creator's default group (usually the same as the user name) is used.<br />
<br />
=== Other examples of user management ===<br />
<br />
To add a user to other groups use:<br />
<br />
# usermod -aG ''additional_groups'' ''username''<br />
<br />
Alternatively, gpasswd may be used. Though the username can only be added (or removed) from one group at a time.<br />
<br />
# gpasswd --add ''username'' ''group''<br />
<br />
{{Warning|If the {{ic|-a}} option is omitted in the ''usermod'' command above, the user is removed from all groups not listed in {{ic|''additional_groups''}} (i.e. the user will be member only of those groups listed in {{ic|''additional_groups''}}).}}<br />
<br />
To enter user information for the ''GECOS'' field (e.g. the full user name), type:<br />
<br />
# chfn ''username''<br />
<br />
(this way ''chfn'' runs in interactive mode).<br />
<br />
To specify the user's password, type:<br />
<br />
# passwd ''username''<br />
<br />
To mark a user's password as expired, requiring them to create a new password the first time they log in, type:<br />
<br />
# chage -d 0 ''username''<br />
<br />
User accounts may be deleted with the ''userdel'' command.<br />
<br />
# userdel -r ''username''<br />
<br />
The {{ic|-r}} option specifies that the user's home directory and mail spool should also be deleted.<br />
<br />
{{Tip|The [[AUR]] packages {{AUR|adduser}}, {{AUR|adduser-defaults}} or {{AUR|adduser-deb}} provide an ''adduser'' script that allows carrying out the jobs of ''useradd'', ''chfn'' and ''passwd'' interactively. See also {{Bug|32893}}.}}<br />
<br />
== User database ==<br />
<br />
Local user information is stored in the {{ic|/etc/passwd}} file. To list all user accounts on the system:<br />
<br />
$ cat /etc/passwd<br />
<br />
There is one line per account, and each is of the format:<br />
<br />
account:password:UID:GID:GECOS:directory:shell<br />
<br />
where:<br />
<br />
* {{ic|account}} is the user name<br />
* {{ic|password}} is the user password<br />
* {{ic|UID}} is the numerical user ID<br />
* {{ic|GID}} is the numerical primary group ID for the user<br />
* {{ic|GECOS}} is an optional field used for informational purposes; usually it contains the full user name<br />
* {{ic|directory}} is the user's {{ic|$HOME}} directory<br />
* {{ic|shell}} is the user command interpreter (defaults to {{ic|/bin/sh}})<br />
<br />
{{Note|1=Arch Linux uses ''shadowed'' passwords. The {{ic|passwd}} file is world-readable, so storing passwords (hashed or otherwise) in this file would be insecure. Instead, the {{ic|password}} field will contain a placeholder character ({{ic|x}}) indicating that the hashed password is saved in the access-restricted file {{ic|/etc/shadow}}.}}<br />
<br />
== Group management ==<br />
<br />
{{ic|/etc/group}} is the file that defines the groups on the system ({{ic|man group}} for details).<br />
<br />
Display group membership with the {{ic|groups}} command:<br />
<br />
$ groups [user]<br />
<br />
If {{ic|user}} is omitted, the current user's group names are displayed.<br />
<br />
The {{ic|id}} command provides additional detail, such as the user's UID and associated GIDs:<br />
<br />
$ id [user]<br />
<br />
To list all groups on the system:<br />
<br />
$ cat /etc/group<br />
<br />
Create new groups with the {{ic|groupadd}} command:<br />
<br />
# groupadd [group]<br />
<br />
Add users to a group with the {{ic|gpasswd}} command:<br />
<br />
# gpasswd -a [user] [group]<br />
<br />
Modify an existing group with {{ic|groupmod}}; e.g. to rename {{ic|old_group}} group to {{ic|new_group}} whilst preserving gid (all files previously owned by {{ic|old_group}} will be owned by {{ic|new_group}}):<br />
<br />
# groupmod -n [old_group] [new_group]<br />
<br />
To delete existing groups:<br />
<br />
# groupdel [group]<br />
<br />
To remove users from a group:<br />
<br />
# gpasswd -d [user] [group]<br />
<br />
If the user is currently logged in, he/she must log out and in again for the change to have effect.<br />
<br />
== Group list ==<br />
<br />
=== User groups ===<br />
<br />
Workstation/desktop users often add their non-root user to some of following groups to allow access to peripherals and other hardware and facilitate system administration:<br />
<br />
{| class="wikitable"<br />
! Group || Affected files || Purpose<br />
|-<br />
| games || {{ic|/var/games}} || Access to some game software.<br />
|-<br />
| rfkill || {{ic|/dev/rfkill}} || Right to control wireless devices power state (used by {{Pkg|rfkill}}).<br />
|-<br />
| users || || Standard users group.<br />
|-<br />
| uucp || {{ic|/dev/ttyS[0-9]}}, {{ic|/dev/tts/[0-9]}} || Serial and USB devices such as modems, handhelds, RS-232/serial ports.<br />
|-<br />
| wheel || || Administration group, commonly used to give access to the [[sudo]] and [[su]] utilities (neither uses it by default, configurable in {{ic|/etc/pam.d/su}} and {{ic|/etc/pam.d/su-l}}). It can also be used to gain full read access to [[systemd#Journal|journal]] files.<br />
|}<br />
<br />
=== System groups ===<br />
<br />
The following groups are used for system purposes and are not likely to be used by novice Arch users:<br />
<br />
{| class="wikitable"<br />
! Group || Affected files || Purpose<br />
|-<br />
| bin || none || Historical<br />
|-<br />
| daemon || ||<br />
|-<br />
| dbus || || used internally by {{Pkg|dbus}}<br />
|-<br />
| ftp || {{ic|/srv/ftp}} || used by [[Wikipedia:FTP|FTP]] servers like [[Proftpd]]<br />
|-<br />
| fuse || || Used by fuse to allow user mounts.<br />
|-<br />
| http || ||<br />
|-<br />
| kmem || {{ic|/dev/port}}, {{ic|/dev/mem}}, {{ic|/dev/kmem}} ||<br />
|-<br />
| mail || {{ic|/usr/bin/mail}} ||<br />
|-<br />
| mem || ||<br />
|-<br />
| nobody || || Unprivileged group.<br />
|-<br />
| polkitd || || [[polkit]] group.<br />
|-<br />
| root || {{ic|/*}} || Complete system administration and control (root, admin).<br />
|-<br />
| smmsp || || [[Wikipedia:sendmail|sendmail]] group.<br />
|-<br />
| systemd-journal || {{ic|/var/log/journal/*}} || Provides access to the complete systemd logs. Otherwise, only user generated messages are displayed.<br />
|-<br />
| tty || {{ic|/dev/tty}}, {{ic|/dev/vcc}}, {{ic|/dev/vc}}, {{ic|/dev/ptmx}} || Eg. to acces {{ic|/dev/ACMx}}<br />
|-<br />
|}<br />
<br />
=== Software groups ===<br />
<br />
These groups are used by certain non-essential software. Sometimes they are used just internally, in these cases you should not add your user into these groups. See the main page for the software for details.<br />
<br />
{| class="wikitable"<br />
! Group || Affected files || Purpose<br />
|-<br />
| adbusers || devices nodes under {{ic|/dev/}} || Right to access [[Android]] Debugging Bridge.<br />
|-<br />
| avahi || ||<br />
|-<br />
| cdemu || {{ic|/dev/vhba_ctl}} || Right to use [[cdemu]] drive emulation.<br />
|-<br />
| clamav || {{ic|/var/lib/clamav/*}}, {{ic|/var/log/clamav/*}} || Used by [[Clam AntiVirus]].<br />
|-<br />
| gdm || X server authorization directory (ServAuthDir) || [[GDM]] group.<br />
|-<br />
| locate || {{ic|/usr/bin/locate}}, {{ic|/var/lib/locate}}, {{ic|/var/lib/mlocate}}, {{ic|/var/lib/slocate}} || Right to use [[Wikipedia:updatedb|updatedb]] command.<br />
|-<br />
| mpd || {{ic|/var/lib/mpd/*}}, {{ic|/var/log/mpd/*}}, {{ic|/var/run/mpd/*}}, optionally music directories || [[MPD]] group.<br />
|-<br />
| networkmanager || || Requirement for your user to connect wirelessly with [[NetworkManager]]. This group is not included with Arch by default so it must be added manually.<br />
|-<br />
| ntp || {{ic|/var/lib/ntp/*}} || [[NTPd]] group.<br />
|-<br />
| thinkpad || {{ic|/dev/misc/nvram}} || Used by ThinkPad users for access to tools such as [[tpb]].<br />
|-<br />
| vboxsf || virtual machines' shared folders || Used by [[VirtualBox]].<br />
|-<br />
| vboxusers || {{ic|/dev/vboxdrv}} || Right to use VirtualBox software.<br />
|-<br />
| vmware || || Right to use [[VMware]] software.<br />
|-<br />
| wireshark || || Right to capture packets with [[Wireshark]].<br />
|}<br />
<br />
=== Deprecated or unused groups ===<br />
<br />
Following groups are currently of no use for anyone:<br />
<br />
{| class="wikitable"<br />
! Group || Purpose<br />
|-<br />
| log || Access to log files in {{ic|/var/log}}.<br />
|-<br />
| ssh || <s>[[Sshd]] can be configured to only allow members of this group to login.</s> This is true for any arbitrary group; the {{ic|ssh}} group is not created by default, hence non-standard.<br />
|-<br />
| stb-admin || '''Unused!''' Right to access [http://system-tools-backends.freedesktop.org/ system-tools-backends]<br />
|-<br />
| kvm || Adding a user to the {{ic|kvm}} group used to be required to allow non-root users to access virtual machines using [[KVM]]. This has been deprecated in favor of using [[udev]] rules, and this is done automatically.<br />
|}<br />
<br />
==== Pre-systemd groups ====<br />
<br />
These groups used to be needed before arch migrated to [[systemd]]. That is no longer the case, as long as the ''logind'' session is not broken (see [[General troubleshooting#Session permissions]] to check it). The groups can even cause some functionality to break. See [[Sysvinit#Migration_to_systemd]] for details.<br />
<br />
{| class="wikitable"<br />
! Group || Affected files || Purpose<br />
|-<br />
| audio || {{ic|/dev/audio}}, {{ic|/dev/snd/*}}, {{ic|/dev/rtc0}} || Direct access to sound hardware, for all sessions (requirement is imposed by both [[ALSA]] and [[OSS]]). Local sessions already have the ability to play sound and access mixer controls.<br />
|-<br />
| camera || || Access to [[Digital Cameras]].<br />
|-<br />
| disk || {{ic|/dev/sda[1-9]}}, {{ic|/dev/sdb[1-9]}} || Access to block devices not affected by other groups such as {{ic|optical}}, {{ic|floppy}}, and {{ic|storage}}.<br />
|-<br />
| floppy || {{ic|/dev/fd[0-9]}} || Access to floppy drives.<br />
|-<br />
| lp || {{ic|/etc/cups}}, {{ic|/var/log/cups}}, {{ic|/var/cache/cups}}, {{ic|/var/spool/cups}}, {{ic|/dev/parport[0-9]}} || Access to printer hardware; enables the user to manage print jobs.<br />
|-<br />
| network || || Right to change network settings such as when using [[NetworkManager]]. <br />
|-<br />
| optical || {{ic|/dev/sr[0-9]}}, {{ic|/dev/sg[0-9]}} || Access to optical devices such as CD and DVD drives.<br />
|-<br />
| power || || Right to use [[Pm-utils]] (suspend, hibernate...) and power management controls.<br />
|-<br />
| scanner || {{ic|/var/lock/sane}} || Access to scanner hardware.<br />
|-<br />
| storage || || Access to removable drives such as USB hard drives, flash/jump drives, MP3 players; enables the user to mount storage devices.<br />
|-<br />
| sys || || Right to administer printers in [[CUPS]].<br />
|-<br />
| video || {{ic|/dev/fb/0}}, {{ic|/dev/misc/agpgart}} || Access to video capture devices, 2D/3D hardware acceleration, framebuffer ([[Xorg|X]] can be used ''without'' belonging to this group). Local sessions already have the ability to use hardware acceleration and video capture.<br />
|}</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Users_and_groups&diff=333132Users and groups2014-08-30T18:06:28Z<p>Fylwind: /* User management */</p>
<hr />
<div>[[Category:Security]]<br />
[[de:Benutzer und Gruppen]]<br />
[[es:Users and Groups]]<br />
[[fr:Utilisateurs et Groupes]]<br />
[[it:Users and Groups]]<br />
[[ja:Users and Groups]]<br />
[[ru:Users and Groups]]<br />
[[sr:Users and Groups]]<br />
[[zh-CN:Users and Groups]]<br />
[[zh-TW:Users and Groups]]<br />
{{Related articles start}}<br />
{{Related|DeveloperWiki:UID / GID Database}}<br />
{{Related|polkit}}<br />
{{Related|File permissions and attributes}}<br />
{{Related|Change username}}<br />
{{Related articles end}}<br />
<br />
Users and groups are used on GNU/Linux for [[Wikipedia:access control#Computer security|access control]] — that is, to control access to the system's files, directories, and peripherals. Linux offers relatively simple/coarse access control mechanisms by default. For more advanced options, see [[ACL]] and [[LDAP Authentication]].<br />
<br />
== Overview ==<br />
<br />
A ''user'' is anyone who uses a computer. In this case, we are describing the names which represent those users. It may be Mary or Bill, and they may use the names Dragonlady or Pirate in place of their real name. All that matters is that the computer has a name for each account it creates, and it is this name by which a person gains access to use the computer. Some system services also run using restricted or privileged user accounts.<br />
<br />
Managing users is done for the purpose of security by limiting access in certain specific ways. The superuser (root) has complete access to the operating system and its configuration; it is intended for administrative use only. Unprivileged users can use the [[su]] and [[sudo]] programs for controlled privilege escalation.<br />
<br />
Any individual may have more than one account, as long as they use a different name for each account they create. Further, there are some reserved names which may not be used such as "root".<br />
<br />
Users may be grouped together into a "group", and users may be added to an existing group to utilize the privileged access it grants.<br />
<br />
{{Note|The beginner should use these tools carefully and stay away from having anything to do with any other ''existing'' user account, other than their own.}}<br />
<br />
== Permissions and ownership ==<br />
<br />
From [http://ph7spot.com/musings/in-unix-everything-is-a-file In UNIX Everything is a File]:<br />
<br />
:''The UNIX operating system crystallizes a couple of unifying ideas and concepts that shaped its design, user interface, culture and evolution. One of the most important of these is probably the mantra: "everything is a file," widely regarded as one of the defining points of UNIX.''<br />
<br />
:''This key design principle consists of providing a unified paradigm for accessing a wide range of input/output resources: documents, directories, hard-drives, CD-ROMs, modems, keyboards, printers, monitors, terminals and even some inter-process and network communications. The trick is to provide a common abstraction for all of these resources, each of which the UNIX fathers called a "file." Since every "file" is exposed through the same API, you can use the same set of basic commands to read/write to a disk, keyboard, document or network device.''<br />
<br />
From [http://www.intel-research.net/Publications/Pittsburgh/101220041324_277.pdf Extending UNIX File Abstraction for General-Purpose Networking]:<br />
<br />
:''A fundamental and very powerful, consistent abstraction provided in UNIX and compatible operating systems is the file abstraction. Many OS services and device interfaces are implemented to provide a file or file system metaphor to applications. This enables new uses for, and greatly increases the power of, existing applications — simple tools designed with specific uses in mind can, with UNIX file abstractions, be used in novel ways. A simple tool, such as cat, designed to read one or more files and output the contents to standard output, can be used to read from I/O devices through special device files, typically found under the {{ic|/dev}} directory. On many systems, audio recording and playback can be done simply with the commands, "{{ic|cat /dev/audio > myfile}}" and "{{ic|cat myfile > /dev/audio}}," respectively.''<br />
<br />
Every file on a GNU/Linux system is owned by a user and a group. In addition, there are three types of access permissions: read, write, and execute. Different access permissions can be applied to a file's owning user, owning group, and others (those without ownership). One can determine a file's owners and permissions by viewing the long listing format of the [[Core utilities#ls|ls]] command:<br />
<br />
{{hc|$ ls -l /boot/|total 13740<br />
drwxr-xr-x 2 root root 4096 Jan 12 00:33 grub<br />
-rw-r--r-- 1 root root 8570335 Jan 12 00:33 initramfs-linux-fallback.img<br />
-rw-r--r-- 1 root root 1821573 Jan 12 00:31 initramfs-linux.img<br />
-rw-r--r-- 1 root root 1457315 Jan 8 08:19 System.map26<br />
-rw-r--r-- 1 root root 2209920 Jan 8 08:19 vmlinuz-linux}}<br />
<br />
The first column displays the file's permissions (for example, the file {{ic|initramfs-linux.img}} has permissions {{ic|-rw-r--r--}}). The third and fourth columns display the file's owning user and group, respectively. In this example, all files are owned by the ''root'' user and the ''root'' group.<br />
<br />
{{hc|$ ls -l /media/|total 16<br />
drwxrwx--- 1 root vboxsf 16384 Jan 29 11:02 sf_Shared}}<br />
<br />
In this example, the {{ic|sf_Shared}} directory is owned by the ''root'' user and the ''vboxsf'' group. It is also possible to determine a file's owners and permissions using the stat command:<br />
<br />
Owning user:<br />
<br />
{{hc|$ stat -c %U /media/sf_Shared/|root}}<br />
<br />
Owning group:<br />
<br />
{{hc|$ stat -c %G /media/sf_Shared/|vboxsf}}<br />
<br />
Access rights:<br />
<br />
{{hc|$ stat -c %A /media/sf_Shared/|drwxrwx---}}<br />
<br />
Access permissions are displayed in three groups of characters, representing the permissions of the owning user, owning group, and others, respectively. For example, the characters {{ic|-rw-r--r--}} indicate that the file's owner has read and write permission, but not execute ({{ic|rw-}}), whilst users belonging to the owning group and other users have only read permission ({{ic|r--}} and {{ic|r--}}). Meanwhile, the characters {{ic|drwxrwx---}} indicate that the file's owner and users belonging to the owning group all have read, write, and execute permissions ({{ic|rwx}} and {{ic|rwx}}), whilst other users are denied access ({{ic|---}}). The first character represents the file's type.<br />
<br />
List files owned by a user or group with the ''find'' utility:<br />
<br />
# find / -group [group]<br />
<br />
# find / -user [user]<br />
<br />
A file's owning user and group can be changed with the ''chown'' (change owner) command. A file's access permissions can be changed with the ''chmod'' (change mode) command.<br />
<br />
See [http://linux.die.net/man/1/chown man chown], [http://linux.die.net/man/1/chmod man chmod], and [http://www.linux.com/learn/tutorials/309527-understanding-linux-file-permissions Linux file permissions] for additional detail.<br />
<br />
== File list ==<br />
<br />
{{Warning|Do not edit these files by hand. There are utilities that properly handle locking and avoid invalidating the format of the database. See [[#User management]] and [[#Group management]] for an overview.}}<br />
<br />
{| class="wikitable"<br />
! File || Purpose<br />
|-<br />
| {{ic|/etc/shadow}} || Secure user account information<br />
|-<br />
| {{ic|/etc/passwd}} || User account information<br />
|-<br />
| {{ic|/etc/gshadow}} || Contains the shadowed information for group accounts<br />
|-<br />
| {{ic|/etc/group}} || Defines the groups to which users belong<br />
|-<br />
| {{ic|/etc/sudoers}} || List of who can run what by sudo<br />
|-<br />
| {{ic|/home/*}} || Home directories<br />
|}<br />
<br />
== User management ==<br />
<br />
To list users currently logged on the system, the ''who'' command can be used.<br />
<br />
To add a new user, use the ''useradd'' command:<br />
<br />
# useradd -m -g [initial_group] -G [additional_groups] -s [login_shell] [username]<br />
<br />
* {{ic|-m}} creates the user home directory as {{ic|/home/''username''}}. Within their home directory, a non-root user can write files, delete them, install programs, and so on.<br />
* {{ic|-g}} defines the group name or number of the user's initial login group. If specified, the group name must exist; if a group number is provided, it must refer to an already existing group. If not specified, the behaviour of ''useradd'' will depend on the {{ic|USERGROUPS_ENAB}} variable contained in {{ic|/etc/login.defs}}. The default behaviour ({{ic|USERGROUPS_ENAB yes}}) is to create a group with the same name as the username, with {{ic|GID}} equal to {{ic|UID}}.<br />
* {{ic|-G}} introduces a list of supplementary groups which the user is also a member of. Each group is separated from the next by a comma, with no intervening spaces. The default is for the user to belong only to the initial group.<br />
* {{ic|-s}} defines the path and file name of the user's default login shell. After the boot process is complete, the default login shell is the one specified here. Ensure the chosen shell package is installed if choosing something other than [[Bash]].<br />
<br />
{{Warning|The login shell should be one of those listed in {{ic|/etc/shells}}, unless the shell is intended to be non-functional (e.g. to prevent login). For programs that use PAM, this is checked by the {{ic|pam_shells}} module.}}<br />
<br />
{{Note|The password for the newly created user must then be defined, using ''passwd'' as explained [[#Other_examples_of_user_management|below]].}}<br />
<br />
{{Tip|In case you need to create an user for a specific service, use {{ic|/usr/bin/nologin}} as shell.}} <br />
<br />
=== Example adding a user ===<br />
<br />
On a typical desktop system, use the following command to add a new user named {{ic|archie}}, specify Bash as their login shell and add them to the {{ic|wheel}} group (see the entry in [[#User groups]] for details):<br />
<br />
# useradd -m -G wheel -s /bin/bash archie<br />
<br />
This command will also automatically create a group called {{ic|archie}} with the same GID as the UID of the user {{ic|archie}} and makes this the default group for {{ic|archie}} on login. Making each user have their own group (with group name same as user name and GID same as UID) is the preferred way to add users.<br />
<br />
You could also make the default group something else, e.g. {{ic|users}}:<br />
<br />
# useradd -m -g users -G wheel -s /bin/bash archie<br />
<br />
However, this is '''not''' recommended for multi-user systems. Typically, the method for facilitating shared write access for specific groups of users while keeping home directories private is setting user [[umask]] value to {{ic|002}}, meaning the default group ({{ic|users}} in the example above) will by default always have write access to any file you create. The user's home folder, which is owned by a group with group name same as user name, will be read-only for other system users, while shared files/folders can be made writeable by default for everyone in the operative group. The owning group can be automatically fixed to the group which owns the parent directory by setting the group sticky bit on this directory:<br />
<br />
# chmod g+s ''our_shared_directory''<br />
<br />
Otherwise the file creator's default group (usually the same as the user name) is used.<br />
<br />
=== Other examples of user management ===<br />
<br />
To add a user to other groups use:<br />
<br />
# usermod -aG ''additional_groups'' ''username''<br />
<br />
Alternatively, gpasswd may be used. Though the username can only be added (or removed) from one group at a time.<br />
<br />
# gpasswd --add ''username'' ''group''<br />
<br />
{{Warning|If the {{ic|-a}} option is omitted in the ''usermod'' command above, the user is removed from all groups not listed in {{ic|''additional_groups''}} (i.e. the user will be member only of those groups listed in {{ic|''additional_groups''}}).}}<br />
<br />
To enter user information for the ''GECOS'' field (e.g. the full user name), type:<br />
<br />
# chfn ''username''<br />
<br />
(this way ''chfn'' runs in interactive mode).<br />
<br />
To specify the user's password, type:<br />
<br />
# passwd ''username''<br />
<br />
To mark a user's password as expired, requiring them to create a new password the first time they log in, type:<br />
<br />
# chage -d 0 ''username''<br />
<br />
User accounts may be deleted with the ''userdel'' command.<br />
<br />
# userdel -r ''username''<br />
<br />
The {{ic|-r}} option specifies that the user's home directory and mail spool should also be deleted.<br />
<br />
{{Tip|The [[AUR]] packages {{AUR|adduser}}, {{AUR|adduser-defaults}} or {{AUR|adduser-deb}} provide an ''adduser'' script that allows carrying out the jobs of ''useradd'', ''chfn'' and ''passwd'' interactively. See also {{Bug|32893}}.}}<br />
<br />
== User database ==<br />
<br />
Local user information is stored in the {{ic|/etc/passwd}} file. To list all user accounts on the system:<br />
<br />
$ cat /etc/passwd<br />
<br />
There is one line per account, and each is of the format:<br />
<br />
account:password:UID:GID:GECOS:directory:shell<br />
<br />
where:<br />
<br />
* {{ic|account}} is the user name<br />
* {{ic|password}} is the user password<br />
* {{ic|UID}} is the numerical user ID<br />
* {{ic|GID}} is the numerical primary group ID for the user<br />
* {{ic|GECOS}} is an optional field used for informational purposes; usually it contains the full user name<br />
* {{ic|directory}} is the user's {{ic|$HOME}} directory<br />
* {{ic|shell}} is the user command interpreter (defaults to {{ic|/bin/sh}})<br />
<br />
{{Note|1=Arch Linux uses ''shadowed'' passwords. The {{ic|passwd}} file is world-readable, so storing passwords (hashed or otherwise) in this file would be insecure. Instead, the {{ic|password}} field will contain a placeholder character ({{ic|x}}) indicating that the hashed password is saved in the access-restricted file {{ic|/etc/shadow}}.}}<br />
<br />
== Group management ==<br />
<br />
{{ic|/etc/group}} is the file that defines the groups on the system ({{ic|man group}} for details).<br />
<br />
Display group membership with the {{ic|groups}} command:<br />
<br />
$ groups [user]<br />
<br />
If {{ic|user}} is omitted, the current user's group names are displayed.<br />
<br />
The {{ic|id}} command provides additional detail, such as the user's UID and associated GIDs:<br />
<br />
$ id [user]<br />
<br />
To list all groups on the system:<br />
<br />
$ cat /etc/group<br />
<br />
Create new groups with the {{ic|groupadd}} command:<br />
<br />
# groupadd [group]<br />
<br />
Add users to a group with the {{ic|gpasswd}} command:<br />
<br />
# gpasswd -a [user] [group]<br />
<br />
Modify an existing group with {{ic|groupmod}}; e.g. to rename {{ic|old_group}} group to {{ic|new_group}} whilst preserving gid (all files previously owned by {{ic|old_group}} will be owned by {{ic|new_group}}):<br />
<br />
# groupmod -n [old_group] [new_group]<br />
<br />
To delete existing groups:<br />
<br />
# groupdel [group]<br />
<br />
To remove users from a group:<br />
<br />
# gpasswd -d [user] [group]<br />
<br />
If the user is currently logged in, he/she must log out and in again for the change to have effect.<br />
<br />
== Group list ==<br />
<br />
=== User groups ===<br />
<br />
Workstation/desktop users often add their non-root user to some of following groups to allow access to peripherals and other hardware and facilitate system administration:<br />
<br />
{| class="wikitable"<br />
! Group || Affected files || Purpose<br />
|-<br />
| games || {{ic|/var/games}} || Access to some game software.<br />
|-<br />
| rfkill || {{ic|/dev/rfkill}} || Right to control wireless devices power state (used by {{Pkg|rfkill}}).<br />
|-<br />
| users || || Standard users group.<br />
|-<br />
| uucp || {{ic|/dev/ttyS[0-9]}}, {{ic|/dev/tts/[0-9]}} || Serial and USB devices such as modems, handhelds, RS-232/serial ports.<br />
|-<br />
| wheel || || Administration group, commonly used to give access to the [[sudo]] and [[su]] utilities (neither uses it by default, configurable in {{ic|/etc/pam.d/su}} and {{ic|/etc/pam.d/su-l}}). It can also be used to gain full read access to [[systemd#Journal|journal]] files.<br />
|}<br />
<br />
=== System groups ===<br />
<br />
The following groups are used for system purposes and are not likely to be used by novice Arch users:<br />
<br />
{| class="wikitable"<br />
! Group || Affected files || Purpose<br />
|-<br />
| bin || none || Historical<br />
|-<br />
| daemon || ||<br />
|-<br />
| dbus || || used internally by {{Pkg|dbus}}<br />
|-<br />
| ftp || {{ic|/srv/ftp}} || used by [[Wikipedia:FTP|FTP]] servers like [[Proftpd]]<br />
|-<br />
| fuse || || Used by fuse to allow user mounts.<br />
|-<br />
| http || ||<br />
|-<br />
| kmem || {{ic|/dev/port}}, {{ic|/dev/mem}}, {{ic|/dev/kmem}} ||<br />
|-<br />
| mail || {{ic|/usr/bin/mail}} ||<br />
|-<br />
| mem || ||<br />
|-<br />
| nobody || || Unprivileged group.<br />
|-<br />
| polkitd || || [[polkit]] group.<br />
|-<br />
| root || {{ic|/*}} || Complete system administration and control (root, admin).<br />
|-<br />
| smmsp || || [[Wikipedia:sendmail|sendmail]] group.<br />
|-<br />
| systemd-journal || {{ic|/var/log/journal/*}} || Provides access to the complete systemd logs. Otherwise, only user generated messages are displayed.<br />
|-<br />
| tty || {{ic|/dev/tty}}, {{ic|/dev/vcc}}, {{ic|/dev/vc}}, {{ic|/dev/ptmx}} || Eg. to acces {{ic|/dev/ACMx}}<br />
|-<br />
|}<br />
<br />
=== Software groups ===<br />
<br />
These groups are used by certain non-essential software. Sometimes they are used just internally, in these cases you should not add your user into these groups. See the main page for the software for details.<br />
<br />
{| class="wikitable"<br />
! Group || Affected files || Purpose<br />
|-<br />
| adbusers || devices nodes under {{ic|/dev/}} || Right to access [[Android]] Debugging Bridge.<br />
|-<br />
| avahi || ||<br />
|-<br />
| cdemu || {{ic|/dev/vhba_ctl}} || Right to use [[cdemu]] drive emulation.<br />
|-<br />
| clamav || {{ic|/var/lib/clamav/*}}, {{ic|/var/log/clamav/*}} || Used by [[Clam AntiVirus]].<br />
|-<br />
| gdm || X server authorization directory (ServAuthDir) || [[GDM]] group.<br />
|-<br />
| locate || {{ic|/usr/bin/locate}}, {{ic|/var/lib/locate}}, {{ic|/var/lib/mlocate}}, {{ic|/var/lib/slocate}} || Right to use [[Wikipedia:updatedb|updatedb]] command.<br />
|-<br />
| mpd || {{ic|/var/lib/mpd/*}}, {{ic|/var/log/mpd/*}}, {{ic|/var/run/mpd/*}}, optionally music directories || [[MPD]] group.<br />
|-<br />
| networkmanager || || Requirement for your user to connect wirelessly with [[NetworkManager]]. This group is not included with Arch by default so it must be added manually.<br />
|-<br />
| ntp || {{ic|/var/lib/ntp/*}} || [[NTPd]] group.<br />
|-<br />
| thinkpad || {{ic|/dev/misc/nvram}} || Used by ThinkPad users for access to tools such as [[tpb]].<br />
|-<br />
| vboxsf || virtual machines' shared folders || Used by [[VirtualBox]].<br />
|-<br />
| vboxusers || {{ic|/dev/vboxdrv}} || Right to use VirtualBox software.<br />
|-<br />
| vmware || || Right to use [[VMware]] software.<br />
|-<br />
| wireshark || || Right to capture packets with [[Wireshark]].<br />
|}<br />
<br />
=== Deprecated or unused groups ===<br />
<br />
Following groups are currently of no use for anyone:<br />
<br />
{| class="wikitable"<br />
! Group || Purpose<br />
|-<br />
| log || Access to log files in {{ic|/var/log}}.<br />
|-<br />
| ssh || <s>[[Sshd]] can be configured to only allow members of this group to login.</s> This is true for any arbitrary group; the {{ic|ssh}} group is not created by default, hence non-standard.<br />
|-<br />
| stb-admin || '''Unused!''' Right to access [http://system-tools-backends.freedesktop.org/ system-tools-backends]<br />
|-<br />
| kvm || Adding a user to the {{ic|kvm}} group used to be required to allow non-root users to access virtual machines using [[KVM]]. This has been deprecated in favor of using [[udev]] rules, and this is done automatically.<br />
|}<br />
<br />
==== Pre-systemd groups ====<br />
<br />
These groups used to be needed before arch migrated to [[systemd]]. That is no longer the case, as long as the ''logind'' session is not broken (see [[General troubleshooting#Session permissions]] to check it). The groups can even cause some functionality to break. See [[Sysvinit#Migration_to_systemd]] for details.<br />
<br />
{| class="wikitable"<br />
! Group || Affected files || Purpose<br />
|-<br />
| audio || {{ic|/dev/audio}}, {{ic|/dev/snd/*}}, {{ic|/dev/rtc0}} || Direct access to sound hardware, for all sessions (requirement is imposed by both [[ALSA]] and [[OSS]]). Local sessions already have the ability to play sound and access mixer controls.<br />
|-<br />
| camera || || Access to [[Digital Cameras]].<br />
|-<br />
| disk || {{ic|/dev/sda[1-9]}}, {{ic|/dev/sdb[1-9]}} || Access to block devices not affected by other groups such as {{ic|optical}}, {{ic|floppy}}, and {{ic|storage}}.<br />
|-<br />
| floppy || {{ic|/dev/fd[0-9]}} || Access to floppy drives.<br />
|-<br />
| lp || {{ic|/etc/cups}}, {{ic|/var/log/cups}}, {{ic|/var/cache/cups}}, {{ic|/var/spool/cups}}, {{ic|/dev/parport[0-9]}} || Access to printer hardware; enables the user to manage print jobs.<br />
|-<br />
| network || || Right to change network settings such as when using [[NetworkManager]]. <br />
|-<br />
| optical || {{ic|/dev/sr[0-9]}}, {{ic|/dev/sg[0-9]}} || Access to optical devices such as CD and DVD drives.<br />
|-<br />
| power || || Right to use [[Pm-utils]] (suspend, hibernate...) and power management controls.<br />
|-<br />
| scanner || {{ic|/var/lock/sane}} || Access to scanner hardware.<br />
|-<br />
| storage || || Access to removable drives such as USB hard drives, flash/jump drives, MP3 players; enables the user to mount storage devices.<br />
|-<br />
| sys || || Right to administer printers in [[CUPS]].<br />
|-<br />
| video || {{ic|/dev/fb/0}}, {{ic|/dev/misc/agpgart}} || Access to video capture devices, 2D/3D hardware acceleration, framebuffer ([[Xorg|X]] can be used ''without'' belonging to this group). Local sessions already have the ability to use hardware acceleration and video capture.<br />
|}</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Fonts&diff=326006Fonts2014-07-21T09:25:17Z<p>Fylwind: /* Creating a package */</p>
<hr />
<div>[[Category:Fonts]]<br />
[[Category:Graphics and desktop publishing]]<br />
[[cs:Fonts]]<br />
[[de:Schriftarten]]<br />
[[es:Fonts]]<br />
[[it:Fonts]]<br />
[[ja:Fonts]]<br />
[[ru:Fonts]]<br />
[[tr:Yazıtipleri]]<br />
[[zh-CN:Fonts]]<br />
[[zh-TW:Fonts]]<br />
{{Related articles start}}<br />
{{Related|Font configuration}}<br />
{{Related|Infinality-bundle+fonts}}<br />
{{Related|Java Runtime Environment Fonts}}<br />
{{Related|MS Fonts}}<br />
{{Related articles end}}<br />
From [[Wikipedia:Computer font|Wikipedia]]:<br />
:''A computer font (or font) is an electronic data file containing a set of glyphs, characters, or symbols such as dingbats.''<br />
<br />
Note that certain font licenses may impose some legal limitations.<br />
<br />
== Font formats ==<br />
<br />
Most computer fonts used today are in either ''bitmap'' or ''outline'' data formats. <br />
;Bitmap fonts: Consist of a matrix of dots or pixels representing the image of each glyph in each face and size.<br />
;Outline or ''vector'' fonts: Use Bézier curves, drawing instructions and mathematical formulae to describe each glyph, which make the character outlines scalable to any size.<br />
<br />
=== Common extensions ===<br />
<br />
* {{ic|bdf}} and {{ic|bdf.gz}} – bitmap fonts, ''b''itmap ''d''istribution ''f''ormat and gzip compressed {{ic|bdf}}<br />
* {{ic|pcf}} and {{ic|pcf.gz}} – bitmaps, ''p''ortable ''c''ompiled ''f''ont and gzip compressed {{ic|pcf}}<br />
* {{ic|psf}}, {{ic|psfu}}, {{ic|psf.gz}} and {{ic|psfu.gz}} – bitmaps, ''P''C ''s''creen ''f''ont, ''P''C ''s''creen ''f''ont ''U''nicode and the gzipped versions (not compatible with X.Org)<br />
* {{ic|pfa}} and {{ic|pfb}} – outline fonts, ''P''ostScript ''f''ont ''A''SCII and ''P''ostScript ''f''ont ''b''inary. PostScript fonts carry built-in printer instructions.<br />
* {{ic|ttf}} – outline, ''T''rue''T''ype ''f''ont. Originally designed as a replacement for the PostScript fonts.<br />
* {{ic|otf}} – outline, ''O''pen''T''ype ''f''ont. TrueType with PostScript typographic instructions.<br />
<br />
For most purposes, the technical differences between TrueType and OpenType can be ignored, some fonts with a {{ic|ttf}} extension are actually OpenType fonts.<br />
<br />
=== Other formats ===<br />
<br />
The typesetting application, ''TeX,'' and its companion font software, ''Metafont,'' render characters using their own methods. Some of the file extensions used for fonts by these two programs are {{ic|*pk}}, {{ic|*gf}}, {{ic|mf}} and {{ic|vf}}.<br />
<br />
''FontForge,'' a font editing application, can store fonts in its native text-based format, {{ic|sfd}}, ''s''pline ''f''ont ''d''atabase.<br />
<br />
The [http://www.w3.org/TR/SVG/fonts.html SVG] format also has its own font description method.<br />
<br />
== Installation ==<br />
<br />
There are various methods for installing fonts.<br />
<br />
=== Pacman ===<br />
<br />
Fonts and font collections in the enabled repositories can be installed using [[Pacman|pacman]]. Available fonts may be found by using:<br />
$ pacman -Ss font<br />
Or to search for {{ic|ttf}} fonts only:<br />
$ pacman -Ss ttf<br />
<br />
=== Creating a package ===<br />
<br />
You should give pacman the ability to manage your fonts, which is done by creating an Arch package. These can also be shared with the community in the [[AUR]]. Here is an example of how to create a basic package. To learn more about building packages, read [[PKGBUILD]].<br />
<br />
{{bc|<nowiki><br />
pkgname=ttf-fontname<br />
pkgver=1.0<br />
pkgrel=1<br />
pkgdesc="custom fonts"<br />
arch=(any)<br />
depends=(fontconfig xorg-font-utils)<br />
source=("http://someurl.org/$pkgname.tar.bz2")<br />
install=$pkgname.install<br />
<br />
package() {<br />
install -d "$pkgdir/usr/share/fonts/TTF"<br />
install -m644 "$srcdir/$pkgname/"*.ttf "$pkgdir/usr/share/fonts/TTF/"<br />
}<br />
</nowiki>}}<br />
<br />
This PKGBUILD assumes the fonts are TrueType. An install file ({{ic|ttf-fontname.install}}) is also needed to update the font cache:<br />
<br />
{{bc|<nowiki><br />
post_install() {<br />
echo -n "Updating font cache... "<br />
fc-cache >/dev/null -f<br />
mkfontscale /usr/share/fonts/TTF<br />
mkfontdir /usr/share/fonts/TTF<br />
echo done<br />
}<br />
<br />
post_upgrade() {<br />
post_install<br />
}<br />
<br />
post_remove() {<br />
post_install<br />
}<br />
</nowiki>}}<br />
<br />
For a more convenient package creation from TTFs you can also use {{AUR|makefontpkg}} from the [[AUR]].<br />
<br />
=== Manual installation ===<br />
<br />
The recommended way of adding fonts that are not in the repositories to your system is described in [[#Creating a package]]. This gives pacman the ability to remove or update them at a later time. Fonts can alternately be installed manually as well.<br />
<br />
To install fonts system-wide (available for all users), move the folder to the {{ic|/usr/share/fonts/}} directory. To install fonts for only a single user, use {{ic|~/.local/share/fonts}} ({{ic|~/.fonts/}} is now deprecated).<br />
<br />
For Xserver to load fonts directly (as opposed to the use of a ''font server'') the directory for your newly added font must be added with a FontPath entry. This entry is located in the ''Files'' section [[Xorg#Configuration|of your Xorg configuration file]] (e.g. {{ic|/etc/X11/xorg.conf}} or {{ic|/etc/xorg.conf}}). See [[#Older applications]] for more detail.<br />
<br />
Then update the fontconfig font cache:<br />
<br />
$ fc-cache -vf<br />
<br />
=== Manual installation: advanced method ===<br />
<br />
Manual installation and maintenance of your font resources may be especially useful if your collection is more specialized, e.g. if you use commercial fonts,<br />
if you use fonts in different formats, if you often install and remove font files, or if you just feel you need more control and better access than offered by<br />
the package manager. There are numerous benefits to such an approach:<br />
<br />
* You can avoid installation of multiple copies of the same family in different versions and formats (one of the most common reasons for rendering issues).<br />
* You can use multiple and non-standard physical sources of font files (e.g. an additional hard drive, a separate partition).<br />
* You can avoid relying on huge and cryptic local font sources which possibly contain 5 families you need and 55 you don't need (TeX Live & {{ic|09-texlive-fonts.conf}}, random font collections from the AUR, etc).<br />
* You can avoid rendering issues because your fontconfig settings were tuned to a different format but the one installed in your system.<br />
* You can quickly verify which families in which format(s) are present in the system and available for applications by visually inspecting the content of the main font directory (as a result, you don't need sophisticated and heavy-on-resources font management applications: {{Pkg|gtk2fontsel}} and basic CLI tools like {{ic|fc-query}} from {{Pkg|fontconfig}} package will do the job even better and faster).<br />
* When you install or upgrade a single font, the same version will be available for all applications, including LaTeX related software.<br />
* If necessary, you can quickly enable / disable a particular family because you know where exactly it can be found (useful for debugging).<br />
* You don't need to worry about redundant {{ic|/etc/fonts/conf.avail/nn-foo.conf}} fontconfig files, potentially conflicting with your rendering settings (especially when you are using a [[Font configuration#Patched_packages|customized font configuration and patched libraries]]).<br />
* In the long run, you save time needed to resolve issues and eliminate conflicts caused by careless use of the package manager.<br />
<br />
In practical terms, there are at least a few ways to achieve this, which, if necessary, can be adopted by any package manager. The one described below has<br />
proven to be very efficient and secure even with large font collections.<br />
<br />
* We are going to separate font source locations (e.g. {{ic|/usr/share/fonts.avail}}: this is where our fonts will be stored) from a directory containing symbolic links to the families in use ({{ic|/usr/share/fonts}}).<br />
<br />
* Each family is going to be located in a separate, clearly named subdirectory. The naming convention should be consistent and unambiguous, for instance:<br />
<br />
{{bc|<nowiki><br />
<ttf|otf|t1>-<optional_global_group_or_foundry_name>-<font_family_name><br />
</nowiki>}}<br />
<br />
This way the content of the source directory will look like this:<br />
<br />
{{bc|<nowiki><br />
$ ls /usr/share/fonts.avail<br />
<br />
/usr/share/fonts.avail/otf-heuristica<br />
/usr/share/fonts.avail/ttf-liberation<br />
/usr/share/fonts.avail/ttf-ms-arial<br />
...<br />
</nowiki>}}<br />
<br />
* We are not going to touch TeX Live font directories to avoid issues with LaTeX software. Instead, since we can use multiple locations, we will create symlinks in {{ic|/usr/share/fonts}}, giving applications access to particular families:<br />
<br />
{{bc|<nowiki><br />
# cd /usr/share/fonts<br />
# ln -s ../fonts.avail/otf-heuristica .<br />
# ln -s /opt/texlive/texmf-dist/fonts/truetype/public/opensans ttf-texlive-open.sans<br />
</nowiki>}}<br />
<br />
The result:<br />
<br />
{{bc|<nowiki><br />
$ ls /usr/share/fonts<br />
<br />
ttf-liberation -> ..fonts.avail/ttf-liberation<br />
ttf-ms-arial -> ..fonts.avail/ttf-ms-arial<br />
otf-heuristica -> ..fonts.avail/otf-heuristica<br />
otf-texlive-tex.gyre -> /opt/texlive/texmf-dist/fonts/opentype/public/tex-gyre<br />
ttf-texlive-open.sans -> /opt/texlive/texmf-dist/fonts/truetype/public/opensans<br />
...<br />
</nowiki>}}<br />
<br />
Finally, you may want to run the usual:<br />
<br />
{{bc|<nowiki><br />
# fc-cache && mkfontscale && mkfontdir<br />
</nowiki>}}<br />
<br />
A similar approach can be found in [[TeX_Live|TeX Live]] Wiki article, but it's way simpler and describes a per-user scenario rather than a global implementation.<br />
<br />
=== Older applications ===<br />
<br />
With older applications that do not support fontconfig (e.g. GTK+ 1.x applications, and {{ic|xfontsel}}) the index will need to be created in the font directory:<br />
<br />
$ mkfontscale<br />
$ mkfontdir<br />
<br />
Or to include more than one folder with one command:<br />
<br />
$ for dir in /font/dir1/ /font/dir2/; do xset +fp $dir; done && xset fp rehash<br />
<br />
Or if fonts were installed in a different sub-folders under the e.g. {{ic|/usr/share/fonts}}:<br />
<br />
$ for dir in * ; do if [ -d "$dir" ]; then cd "$dir";xset +fp "$PWD" ;mkfontscale; mkfontdir;cd .. ;fi; done && xset fp rehash<br />
<br />
At times the X server may fail to load the fonts directory and you will need to rescan all the {{ic|fonts.dir}} files:<br />
<br />
# xset +fp /usr/share/fonts/misc # Inform the X server of new directories<br />
# xset fp rehash # Forces a new rescan<br />
<br />
To check that the font(s) is included:<br />
<br />
$ xlsfonts | grep fontname<br />
<br />
{{note|Many packages will automatically configure Xorg to use the font upon installation. If that is the case with your font, this step is not necessary.}}<br />
<br />
This can also be set globally in {{ic|/etc/X11/xorg.conf}} or {{ic|/etc/X11/xorg.conf.d}}.<br />
<br />
Here is an example of the section that must be added to {{ic|/etc/X11/xorg.conf}}. Add or remove paths based on your particular font requirements.<br />
<br />
# Let X.Org know about the custom font directories<br />
Section "Files"<br />
FontPath "/usr/share/fonts/100dpi"<br />
FontPath "/usr/share/fonts/75dpi"<br />
FontPath "/usr/share/fonts/cantarell"<br />
FontPath "/usr/share/fonts/cyrillic"<br />
FontPath "/usr/share/fonts/encodings"<br />
FontPath "/usr/share/fonts/misc"<br />
FontPath "/usr/share/fonts/truetype"<br />
FontPath "/usr/share/fonts/TTF"<br />
FontPath "/usr/share/fonts/util"<br />
EndSection<br />
<br />
=== Pango Warnings ===<br />
When [http://www.pango.org/ Pango] is in use on your system it will read from [http://www.freedesktop.org/wiki/Software/fontconfig fontconfig] to sort out where to source fonts.<br />
<br />
(process:5741): Pango-WARNING **: failed to choose a font, expect ugly output. engine-type='PangoRenderFc', script='common'<br />
(process:5741): Pango-WARNING **: failed to choose a font, expect ugly output. engine-type='PangoRenderFc', script='latin'<br />
<br />
If you are seeing errors similar to this and/or seeing blocks instead of characters in your application then you need to add fonts and update the font cache. This example uses the {{Pkg|ttf-liberation}} fonts to illustrate the solution and runs as root to enable them system-wide.<br />
<br />
# pacman -S ttf-liberation<br />
-- output abbreviated, assumes installation succeeded -- <br />
<br />
# fc-cache -vfs<br />
/usr/share/fonts: caching, new cache contents: 0 fonts, 3 dirs<br />
/usr/share/fonts/TTF: caching, new cache contents: 16 fonts, 0 dirs<br />
/usr/share/fonts/encodings: caching, new cache contents: 0 fonts, 1 dirs<br />
/usr/share/fonts/encodings/large: caching, new cache contents: 0 fonts, 0 dirs<br />
/usr/share/fonts/util: caching, new cache contents: 0 fonts, 0 dirs<br />
/var/cache/fontconfig: cleaning cache directory<br />
fc-cache: succeeded<br />
<br />
You can test for a default font being set like so:<br />
<br />
# fc-match<br />
LiberationMono-Regular.ttf: "Liberation Mono" "Regular"<br />
<br />
== Console fonts ==<br />
<br />
{{Note|This section is about the [[Wikipedia:Linux console|Linux console]]. For an alternative console solutions offering more features (full Unicode fonts, modern graphics adapters etc.), see [[fbterm]], [[KMSCON]] or similar projects.}}<br />
<br />
By default, the [[Wikipedia:Virtual console|virtual console]] uses the kernel built-in font with a [[Wikipedia:CP437|CP437]] character set,<sup>[https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/drivers/tty/vt/Makefile#n4]</sup> but this can be easily changed.<br />
<br />
The [[Wikipedia:Linux console|Linux console]] uses UTF-8 encoding by default, but because the standard VGA-compatible framebuffer is used, a console font is limited to either a standard 256, or 512 glyphs. If the font has more than 256 glyphs, the number of colours is reduced from 16 to 8. In order to assign correct symbol to be displayed to the given Unicode value, a special translation map, often called ''unimap'', is needed. Nowadays most of the console fonts have the ''unimap'' built-in, historically it had to be loaded separately.<br />
<br />
The {{Pkg|kbd}} package provides tools to change virtual console font and font mapping. Available fonts are saved in the {{ic|/usr/share/kbd/consolefonts/}} directory, those ending with ''.psfu'' or ''.psfu.gz'' have a Unicode translation map built-in.<br />
<br />
Keymaps, the connection between the key pressed and the character used by the computer, are found in the subdirectories of {{ic|/usr/share/kbd/keymaps/}}, see [[Keyboard configuration in console]] for details.<br />
<br />
{{Note|Replacing the font can cause issues with programs that expect a standard VGA-style font, such as those using line drawing graphics.}}<br />
<br />
=== Previewing and testing ===<br />
<br />
{{Tip|An organized library of images for previewing is available: [http://alexandre.deverteuil.net/consolefonts/consolefonts.html Linux console fonts screenshots].}}<br />
<br />
The available glyphs or letters in the font can also be viewed as a table with using ''showconsolefont'':<br />
<br />
$ showconsolefont<br />
<br />
The ''setfont'' utility may be used to temporarily change the font, so that the user can consider its permanent use. Just pass the name of the font (they are located in {{ic|/usr/share/kbd/consolefonts/}}). For example:<br />
<br />
$ setfont lat2-16<br />
<br />
If the newly changed font is not suitable, a return to the default font with the following command (even if the console display is totally unreadable, this command will still work, just type the command "blindly"):<br />
<br />
$ setfont<br />
<br />
{{Note|''setfont'' only works on the console currently being used. Any other consoles, active or inactive, remain unaffected.}}<br />
<br />
=== Persistent configuration ===<br />
<br />
The {{ic|FONT}} variable in {{ic|/etc/vconsole.conf}} is used to set the font at boot, persistently for all consoles. See {{ic|man 5 vconsole.conf}} for details.<br />
<br />
For displaying characters such as ''Č, ž, đ, š'' or ''Ł, ę, ą, ś'' using the font {{ic|lat2-16.psfu.gz}}:<br />
<br />
{{hc|/etc/vconsole.conf|2=<br />
...<br />
FONT=lat2-16<br />
}}<br />
<br />
It means that second part of ISO/IEC 8859 characters are used with size 16. You can change font size using other values (e.g. {{ic|lat2-08}}). For the regions determined by 8859 specification, look at the [[wikipedia:ISO/IEC_8859#The_Parts_of_ISO.2FIEC_8859|Wikipedia table]].<br />
<br />
To use the specified font in early userspace, use the {{ic|consolefont}} hook in {{ic|/etc/mkinitcpio.conf}}. See [[Mkinitcpio#HOOKS]] for more information.<br />
<br />
If the fonts seems to not change on boot, or change only temporarily, it is most likely that they got reset when graphics driver was initialized and console was switched to framebuffer. To avoid this, load your graphics driver earlier. See for example [[Kernel Mode Setting#Early KMS start]], [https://bbs.archlinux.org/viewtopic.php?id=145765] or other ways to setup your framebuffer before {{ic|/etc/vconsole.conf}} is applied.<br />
<br />
== Font packages ==<br />
<br />
This is a selective list that includes many font packages from the [[AUR]] along with those in the official repositories. Fonts are tagged "Unicode" if they have wide Unicode support, see the project or Wikipedia pages for detail.<br />
<br />
Github user Ternstor has created a python script that generates HTML documents with PNG images of all the fonts in the AUR and the official repositories: [https://github.com/ternstor/distrofonts/blob/master/archfonts.py].<br />
<br />
=== Braille ===<br />
<br />
*{{Pkg|ttf-ubraille}} - Font containing Unicode symbols for ''braille''<br />
<br />
=== International users ===<br />
<br />
Applications and browsers select and display fonts depending upon fontconfig preferences and available font glyph for Unicode text. To list installed fonts for a particular language, issue a command {{ic|<nowiki>fc-list :lang="two letter language code"</nowiki>}}. For instance, to list installed Arabic fonts or fonts supporting Arabic glyph:<br />
{{hc|$ fc-list :lang&#61;ar &#124; cut -d: -f1|2=<br />
<nowiki><br />
/usr/share/fonts/TTF/FreeMono.ttf<br />
/usr/share/fonts/TTF/DejaVuSansCondensed.ttf<br />
/usr/share/fonts/truetype/custom/DroidKufi-Bold.ttf<br />
/usr/share/fonts/TTF/DejaVuSansMono.ttf<br />
/usr/share/fonts/TTF/FreeSerif.ttf<br />
</nowiki><br />
}}<br />
<br />
To properly render fonts for multilingual websites like Wikipedia or this Arch Linux wiki, install these packages: {{Pkg|ttf-freefont}}, {{Pkg|ttf-arphic-uming}}, {{Pkg|ttf-baekmuk}}<br />
<br />
==== Arabic & Urdu ====<br />
<br />
*{{AUR|ttf-qurancomplex-fonts}} - Fonts by King Fahd Glorious Quran Printing Complex in al-Madinah al-Munawwarah ''(AUR)''<br />
*{{AUR|ttf-amiri}} - A classical Arabic typeface in Naskh style poineered by Amiria Press ''(AUR)''<br />
*{{AUR|ttf-sil-lateef}} - Unicode Arabic font from SIL ''(AUR)''<br />
*{{AUR|ttf-sil-scheherazade}} - Unicode Arabic font from SIL ''(AUR)''<br />
*{{AUR|ttf-arabeyes-fonts}} - Collection of free Arabic fonts ''(AUR)''<br />
<br />
==== Persian ====<br />
<br />
*{{AUR|ttf-persian-irfonts}} - Official I.R. Iran Supreme Council of Information and Communication Technology (SCICT) standard persian fonts series ''(AUR)''<br />
*{{AUR|ttf-persian-borna}} - Borna Rayaneh Persian B font series ''(AUR)''<br />
*{{AUR|ttf-persian-x2}} - X Series 2 fonts are built on freely available fonts and extended to support Persian, Arabic, Urdu, Pashto, Dari, Uzbek, Kurdish, Uighur, old Turkish (Ottoman) and modern Turkish (Roman). ''(AUR)''<br />
<br />
==== Birman ====<br />
<br />
*{{AUR|ttf-myanmar3}} - Font for Myanmar/Burmese script ''(AUR)''<br />
<br />
==== Chinese, Japanese, Korean, Vietnamese ====<br />
<br />
===== (Mainly) Chinese =====<br />
<br />
*{{AUR|ttf-tw}} - Kai and Song traditional Chinese font from the Ministry of Education of Taiwan ''(AUR)''.<br />
*{{Pkg|wqy-microhei}} - A Sans-Serif style high quality CJKV outline font.<br />
*{{Pkg|wqy-zenhei}} - Hei Ti Style (sans-serif) Chinese Outline font embedded with bitmapped Song Ti (also supporting Japanese (partial) and Korean characters).<br />
*{{Pkg|ttf-arphic-ukai}} - ''Kaiti'' (brush stroke) Unicode font (enabling anti-aliasing is suggested)<br />
*{{Pkg|ttf-arphic-uming}} - ''Mingti'' (printed) Unicode font<br />
*{{Pkg|opendesktop-fonts}} - ''New Sung'' font, previously is ttf-fireflysung package<br />
*{{Pkg|wqy-bitmapfont}} - Bitmapped Song Ti (serif) Chinese font<br />
*{{Pkg|ttf-hannom}} - Chinese and Vietnamese TrueType font<br />
<br />
===== Japanese =====<br />
<br />
*{{Pkg|otf-ipafont}} - Formal style Japanese Gothic (sans-serif) and Mincho (serif) fonts set; one of the highest quality open source font. Default of openSUSE-ja.<br />
*{{AUR|ttf-vlgothic}} - Japanese Gothic fonts. Default of Debian/Fedora/Vine Linux ''(AUR)''<br />
*{{AUR|ttf-mplus}} - Modern Gothic style Japanese outline fonts. It includes all of Japanese Hiragana/Katakana, Basic Latin, Latin-1 Supplement, Latin Extended-A, IPA Extensions and most of Japanese Kanji, Greek, Cyrillic, Vietnamese with 7 weights (proportional) or 5 weights (monospace). ''(AUR)''<br />
*{{AUR|ttf-ipa-mona}}, {{AUR|ttf-monapo}} - Japanese fonts to show [[wikipedia:2channel_Shift_JIS_art|2channel Shift JIS art]] properly. ''(AUR)''<br />
*{{Pkg|ttf-sazanami}} - Japanese free TrueType font. This is outdated and not maintained any more, but may be defined as a fallback font on several environments.<br />
*{{Pkg|ttf-hanazono}} - A free Japanese kanji font, style Mincho (serif).<br />
<br />
===== Korean =====<br />
<br />
*{{Pkg|ttf-baekmuk}} - Collection of Korean TrueType fonts<br />
*{{AUR|ttf-alee}} - Set of free Hangul TrueType fonts (''AUR'')<br />
*{{AUR|ttf-unfonts-core}} - Un fonts (default Baekmuk fonts may be unsatisfactory) (''AUR'')<br />
*{{AUR|ttf-nanum}} - Nanum series TrueType fonts (''AUR'')<br />
*{{AUR|ttf-nanumgothic_coding}} - Nanum series fixed width TrueType fonts (''AUR'')<br />
<br />
==== Cyrillic ====<br />
<br />
''Also see [[#Monospaced]], [[#Sans-serif]] and [[#Serif]]''<br />
*{{AUR|ttf-paratype}} - Font family by ParaType: sans, serif, mono, extended cyrillic and latin, OFL license (''AUR'')<br />
*{{AUR|font-arhangai}} - Mongolian Cyrillic (''AUR'')<br />
*{{AUR|ttf-pingwi-typography}} - PingWi Typography (PWT) fonts (''AUR'')<br />
<br />
==== Greek ====<br />
<br />
Almost all Unicode fonts contain the Greek character set (polytonic included). Some additional font packages, which might not contain the complete Unicode set but utilize high quality Greek (and Latin, of course) typefaces are:<br />
*{{AUR|otf-gfs}} - Selection of OpenType fonts from the Greek Font Society ''(AUR)''<br />
*{{AUR|ttf-mgopen}} - Professional TrueType fonts from Magenta ''(AUR)''<br />
<br />
==== Hebrew ====<br />
<br />
*{{AUR|culmus}} - Nice collection of free Hebrew fonts ''(AUR)''<br />
<br />
==== Indic ====<br />
<br />
*{{Pkg|ttf-freebanglafont}} - Font for Bangla<br />
*{{Pkg|ttf-indic-otf}} - Indic OpenType Fonts collection (containing ttf-freebanglafont)<br />
:(This one contains a "look of disapproval" that might be more to your liking than the {{Pkg|bdf-unifont}} one mentioned elsewhere in this document)<br />
* {{AUR|lohit-fonts}} - Indic TrueType fonts from Fedora Project (containing Oriya Fonts and more) ''(AUR)''<br />
<br />
==== Khmer ====<br />
<br />
*{{Pkg|ttf-khmer}} - Font covering glyphs for Khmer language<br />
*[http://code.google.com/webfonts/family?family=Hanuman&subset=khmer Hanuman] ({{AUR|ttf-google-fonts-hg}} or {{AUR|ttf-google-fonts-git}})<br />
<br />
==== Sinhala ====<br />
<br />
*{{AUR|ttf-lklug}} - Sinhala Unicode font (''AUR'')<br />
<br />
==== Tamil ====<br />
<br />
*{{AUR|ttf-tamil}} - Tamil Unicode fonts (''AUR'')<br />
<br />
==== Tibetan ====<br />
<br />
*{{Pkg|ttf-tibetan-machine}} - Tibetan Machine TTFont<br />
<br />
=== Math ===<br />
<br />
*{{Pkg|font-mathematica}} - Mathematica fonts by Wolfram Research, Inc.<br />
*{{AUR|ttf-mathtype}} - MathType fonts ''(AUR)''<br />
*{{AUR|ttf-computer-modern-fonts}} - ''(AUR)''<br />
<br />
=== Microsoft fonts ===<br />
<br />
See [[MS Fonts]].<br />
<br />
=== Apple Mac OS X fonts ===<br />
<br />
* {{AUR|ttf-mac-fonts}} - Mac OS X TrueType fonts<br />
* {{AUR|ttf-mac}} - Mac OS X TrueType fonts (This package does not come with the ttf fonts (only the otf fonts), they have to be provided on their own.<br />
<br />
=== Monospaced ===<br />
<br />
Here are some suggestions. Every user has their own favorite, so experiment to find yours. <br />
If you are in a hurry, you read Dan Benjamin's blog post: [http://hivelogic.com/articles/top-10-programming-fonts ''Top 10 Programming Fonts''].<br />
<br />
Here is a long list of fonts by Trevor Lowing: http://www.lowing.org/fonts/.<br />
<br />
A comparison with images on Slant: [http://www.slant.co/topics/67/~what-are-the-best-programming-fonts What are the best programming fonts?]<br />
<br />
And a Stack Overflow question with some images: [http://stackoverflow.com/questions/4689/recommended-fonts-for-programming Recommended fonts for programming]<br />
<br />
==== TrueType ====<br />
<br />
* Agave ({{AUR|ttf-agave}})<br />
* [[Wikipedia:Andalé Mono|Andalé Mono]] ({{AUR|ttf-ms-fonts}})<br />
* Anka/Coder ({{AUR|ttf-anka-coder}})<br />
* [http://www.marksimonson.com/fonts/view/anonymous-pro Anonymous Pro] ({{AUR|ttf-anonymous-pro}}, included in {{AUR|ttf-google-fonts-hg}} and {{AUR|ttf-google-fonts-git}})<br />
* [[Wikipedia:Bitstream Vera|Bitstream Vera Mono]] ({{Pkg|ttf-bitstream-vera}})<br />
* [[Wikipedia:Consolas|Consolas]] ({{AUR|ttf-vista-fonts}}) - Windows programming font<br />
* [[Wikipedia:Courier New|Courier New]] ({{AUR|ttf-ms-fonts}})<br />
* Cousine ({{AUR|ttf-chromeos-fonts}} or {{AUR|ttf-google-fonts-hg}} or {{AUR|ttf-google-fonts-git}}) - Chrome/Chromium OS replacement for Courier New (metric-compatible)<br />
* [[Wikipedia:DejaVu fonts|DejaVu Sans Mono]] ({{Pkg|ttf-dejavu}}) - Unicode<br />
* [[Wikipedia:Droid (font)|Droid Sans Mono]] ({{Pkg|ttf-droid}}, included in {{AUR|ttf-google-fonts-hg}} and {{AUR|ttf-google-fonts-git}})<br />
* Envy Code R ({{AUR|ttf-envy-code-r}})<br />
* [[Wikipedia:GNU FreeFont|FreeMono]] ({{Pkg|ttf-freefont}}) - Unicode<br />
* [[Wikipedia:Inconsolata|Inconsolata]] ({{Pkg|ttf-inconsolata}}) - Excellent programming font<br />
* [[Wikipedia:Inconsolata|Inconsolata-g]] ({{AUR|ttf-inconsolata-g}}) - adds some programmer-friendly modifications<br />
* [[Wikipedia:Liberation fonts|Liberation Mono]] ({{Pkg|ttf-liberation}}) - Replacement for Courier New, based on Cousine (metric-compatible)<br />
* [[Wikipedia:Lucida Typewriter|Lucida Typewriter]] (included in package {{AUR|jre}})<br />
* [[Wikipedia:Monaco (typeface)|Monaco]] ({{AUR|ttf-monaco}}) - Popular programming font on OSX/Textmate<br />
* Monofur ({{AUR|ttf-monofur}})<br />
* [[Wikipedia:Source_Code_Pro|Source Code Pro]] ({{pkg|adobe-source-code-pro-fonts}})<br />
<br />
==== Bitmap ====<br />
<br />
*Default 8x16<br />
*Dina ({{Pkg|dina-font}})<br />
*[http://font.gohu.org/ Gohu] ({{AUR|gohufont}})<br />
*Lime ({{Pkg|artwiz-fonts}})<br />
*[[Wikipedia:ProFont|ProFont]] ({{Pkg|profont}})<br />
*[[Wikipedia:Proggy Programming Fonts|Proggy Programming Fonts]] ({{AUR|proggyfonts}})<br />
*Proggy opti cyrillic ({{AUR|proggyopticyr-font}})<br />
*Tamsyn ({{Pkg|tamsyn-font}})<br />
*[[Wikipedia:Terminus (typeface)|Terminus]] ({{Pkg|terminus-font}})<br />
*Unifont (glyphs like (look of disapproval)) ({{Pkg|bdf-unifont}})<br />
<br />
=== Sans-serif ===<br />
<br />
*[http://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=andika Andika] ({{AUR|ttf-andika}}, included in {{AUR|ttf-sil-fonts}})<br />
*[[Wikipedia:Arial|Arial]] ({{AUR|ttf-ms-fonts}})<br />
*[[Wikipedia:Arial Black|Arial Black]] ({{AUR|ttf-ms-fonts}})<br />
*Arimo ({{AUR|ttf-chromeos-fonts}} or {{AUR|ttf-google-fonts-hg}} or {{AUR|ttf-google-fonts-git}}) - Chrome/Chromium OS replacement for Arial (metric-compatible)<br />
*[[Wikipedia:Calibri|Calibri]] ({{AUR|ttf-vista-fonts}})<br />
*[[Wikipedia:Candara|Candara]] ({{AUR|ttf-vista-fonts}})<br />
*[[Wikipedia:Constantia (typeface)|Constantia]] ({{AUR|ttf-vista-fonts}})<br />
*[[Wikipedia:Corbel (typeface)|Corbel]] ({{AUR|ttf-vista-fonts}})<br />
*[[Wikipedia:DejaVu fonts|DejaVu Sans]] ({{Pkg|ttf-dejavu}}) - Unicode<br />
*[[Wikipedia:Droid (font)|Droid Sans]] ({{Pkg|ttf-droid}}, included in {{AUR|ttf-google-fonts-hg}} and {{AUR|ttf-google-fonts-git}})<br />
*[[Wikipedia:GNU FreeFont|FreeSans]] ({{Pkg|ttf-freefont}}) - Unicode<br />
*[[Wikipedia:Impact (typeface)|Impact]] ({{AUR|ttf-ms-fonts}})<br />
*[[Wikipedia:Liberation fonts|Liberation Sans]] ({{Pkg|ttf-liberation}}) Replacement for Arial, based on Arimo (metric-compatible)<br />
*[[Wikipedia:Linux Libertine|Linux Biolinum]] ({{Pkg|ttf-linux-libertine}})<br />
*[[Wikipedia:Lucida Sans|Lucida Sans]] ({{AUR|ttf-ms-fonts}})<br />
*[[Wikipedia:Microsoft Sans Serif|Microsoft Sans Serif]] ({{AUR|ttf-ms-fonts}})<br />
*[[Wikipedia:PT Sans|PT Sans]] ({{AUR|ttf-google-fonts-hg}} or {{AUR|ttf-google-fonts-git}}) - 3 major variations: normal, narrow, and caption - Unicode: Latin, Cyrillic<br />
*[[Wikipedia:Source Sans Pro|Source Sans Pro]] ({{pkg|adobe-source-sans-pro-fonts}})<br />
*[[Wikipedia:Tahoma (typeface)|Tahoma]] ({{AUR|ttf-tahoma}})<br />
*[[Wikipedia:Trebuchet MS|Trebuchet]] ({{AUR|ttf-ms-fonts}})<br />
*[[Wikipedia:Ubuntu-Title|Ubuntu-Title]] ({{AUR|ttf-ubuntu-title}})<br />
*[[Wikipedia:Ubuntu Font Family|Ubuntu Font Family]] ({{Pkg|ttf-ubuntu-font-family}})<br />
*[[Wikipedia:Verdana|Verdana]] ({{AUR|ttf-ms-fonts}})<br />
<br />
=== Script ===<br />
<br />
*[[Wikipedia:Comic Sans|Comic Sans]] ({{AUR|ttf-ms-fonts}})<br />
<br />
=== Serif ===<br />
<br />
*[[Wikipedia:Cambria (typeface)|Cambria]] ({{AUR|ttf-vista-fonts}})<br />
*[[Wikipedia:Charis SIL|Charis]] ({{AUR|ttf-charis}}, included in {{AUR|ttf-sil-fonts}}) - Unicode: Latin, Cyrillic<br />
*[[Wikipedia:DejaVu fonts|DejaVu Serif]] ({{Pkg|ttf-dejavu}}) - Unicode<br />
*[[Wikipedia:Doulos SIL|Doulos]] ({{AUR|doulos-sil}}, included in {{AUR|ttf-sil-fonts}}) - Unicode: Latin, Cyrillic<br />
*[[Wikipedia:Droid (font)|Droid Serif]] ({{Pkg|ttf-droid}}, included in {{AUR|ttf-google-fonts-hg}} and {{AUR|ttf-google-fonts-git}})<br />
*[[Wikipedia:GNU FreeFont|FreeSerif]] ({{Pkg|ttf-freefont}}) - Unicode<br />
*[[Wikipedia:Gentium|Gentium]] ({{Pkg|ttf-gentium}}, included in {{AUR|ttf-sil-fonts}}) - Unicode: Latin, Greek, Cyrillic, Phonetic Alphabet<br />
*[[Wikipedia:Georgia (typeface)|Georgia]] ({{AUR|ttf-ms-fonts}})<br />
*[[Wikipedia:Liberation fonts|Liberation Serif]] ({{Pkg|ttf-liberation}}) - Replacement for Times New Roman, based on Tinos (metric-compatible)<br />
*[[Wikipedia:Linux Libertine|Linux Libertine]] ({{Pkg|ttf-linux-libertine}}) - Unicode: Latin, Greek, Cyrillic, Hebrew<br />
*[[Wikipedia:Times New Roman|Times New Roman]] ({{AUR|ttf-ms-fonts}})<br />
*Tinos ({{AUR|ttf-chromeos-fonts}} or {{AUR|ttf-google-fonts-hg}} or {{AUR|ttf-google-fonts-git}}) - Chrome/Chromium OS replacement for Times New Roman (metric-compatible)<br />
<br />
=== Unsorted ===<br />
<br />
<!--This section should be absorbed into the Monospace/Serif/Sans-Serif structure--><br />
*{{AUR|ttf-google-fonts-git}} and {{AUR|ttf-google-fonts-hg}} — a huge collection of free fonts (including ubuntu, inconsolata, droid, etc.) - Note: Your font dialog might get very long as >100 fonts will be added. {{AUR|ttf-google-fonts-hg}} pulls down the entire Mercurial repository from the upstream Web Fonts project. {{AUR|ttf-google-fonts-git}} pulls from a much smaller and leaner unofficial repository hosted on GitHub. ''(AUR)''<br />
*{{Pkg|ttf-mph-2b-damase}} — Covers full plane 1 and several scripts<br />
*{{Pkg|ttf-symbola}} — Provides emoji and many many other symbols<br />
*{{AUR|ttf-sil-fonts}} — Gentium, Charis, Doulos, Andika and Abyssinica from SIL ''(AUR)''<br />
*{{Pkg|font-bh-ttf}} — X.Org Luxi fonts<br />
*{{Pkg|ttf-cheapskate}} — Font collection from ''dustismo.com''<br />
*{{AUR|ttf-isabella}} — Calligraphic font based on the ''Isabella Breviary'' of 1497<br />
*{{Pkg|ttf-junicode}} — Junius font containing almost complete medieval latin script glyphs<br />
*arkpandorafonts {{AUR|ttf-arkpandora}} — Alternative to Arial and Times New Roman fonts ''(AUR)''<br />
*{{Pkg|xorg-fonts-type1}} — IBM Courier and Adobe Utopia sets of [[Wikipedia:PostScript fonts|PostScript fonts]]<br />
<br />
== Fallback font order with X11 ==<br />
<br />
Fontconfig automatically chooses a font that matches the current requirement. That is to say, if one is looking at a window containing English and Chinese for example, it will switch to another font for the Chinese text if the default one does not support it.<br />
<br />
Fontconfig lets every user configure the order they want via {{ic|$XDG_CONFIG_HOME/fontconfig/fonts.conf}}.<br />
If you want a particular Chinese font to be selected after your favorite Serif font, your file would look like this:<br />
<?xml version="1.0"?><br />
<!DOCTYPE fontconfig SYSTEM "fonts.dtd"><br />
<fontconfig><br />
<alias><br />
<family>serif</family><br />
<prefer><br />
<family>Your favorite Latin Serif font name</family><br />
<family>Your Chinese font name</family><br />
</prefer><br />
</alias><br />
</fontconfig><br />
<br />
You can add a section for Sans-serif and monospace as well. For more informations, have a look at the fontconfig manual.<br />
<br />
== Font alias ==<br />
<br />
There are several font aliases which represent other fonts in order that applications may use similar fonts. The most common aliases are: {{ic|serif}} for a font of the serif type (e.g. DejaVu Serif); {{ic|sans-serif}} for a font of the sans-serif type (e.g. DejaVu Sans); and {{ic|monospace}} for a monospaced font (e.g. DejaVu Sans Mono). However, the fonts which these aliases represent may vary and the relationship is often not shown in font management tools, such as those found in [[KDE]] and other [[desktop environments]].<br />
<br />
To reverse an alias and find which font it is representing, run:<br />
$ fc-match monospace<br />
DejaVuSansMono.ttf: "DejaVu Sans Mono" "Book"<br />
<br />
In this case, {{ic|DejaVuSansMono.ttf}} is the font represented by the monospace alias.<br />
<br />
== Tips ==<br />
<br />
=== List all installed fonts ===<br />
<br />
You can use the following command to list all installed fonts that are available on your system. <br />
<br />
$ fc-list<br />
<br />
=== Application-specific font cache ===<br />
<br />
Matplotlib ({{pkg|python-matplotlib}} or {{pkg|python2-matplotlib}}) uses its own font cache, so after updating fonts, be sure to remove {{ic|$HOME/.matplotlib/fontList.cache}}, <br />
{{ic|$HOME/.cache/matplotlib/fontList.cache}}, {{ic|$HOME/.sage/matplotlib-1.2.1/fontList.cache}}, etc. so it will regenerate its cache and find the new fonts [http://matplotlib.1069221.n5.nabble.com/getting-matplotlib-to-recognize-a-new-font-td40500.html].<br />
<br />
== See Also ==<br />
<br />
* [[Font configuration]]<br />
* [[Infinality-bundle+fonts]]</div>Fylwindhttps://wiki.archlinux.org/index.php?title=Fonts&diff=325997Fonts2014-07-21T03:45:27Z<p>Fylwind: remove unnecessary quoting; use install instead of cp -dpr because the latter doesn't deref symlinks</p>
<hr />
<div>[[Category:Fonts]]<br />
[[Category:Graphics and desktop publishing]]<br />
[[cs:Fonts]]<br />
[[de:Schriftarten]]<br />
[[es:Fonts]]<br />
[[it:Fonts]]<br />
[[ja:Fonts]]<br />
[[ru:Fonts]]<br />
[[tr:Yazıtipleri]]<br />
[[zh-CN:Fonts]]<br />
[[zh-TW:Fonts]]<br />
{{Related articles start}}<br />
{{Related|Font configuration}}<br />
{{Related|Infinality-bundle+fonts}}<br />
{{Related|Java Runtime Environment Fonts}}<br />
{{Related|MS Fonts}}<br />
{{Related articles end}}<br />
From [[Wikipedia:Computer font|Wikipedia]]:<br />
:''A computer font (or font) is an electronic data file containing a set of glyphs, characters, or symbols such as dingbats.''<br />
<br />
Note that certain font licenses may impose some legal limitations.<br />
<br />
== Font formats ==<br />
<br />
Most computer fonts used today are in either ''bitmap'' or ''outline'' data formats. <br />
;Bitmap fonts: Consist of a matrix of dots or pixels representing the image of each glyph in each face and size.<br />
;Outline or ''vector'' fonts: Use Bézier curves, drawing instructions and mathematical formulae to describe each glyph, which make the character outlines scalable to any size.<br />
<br />
=== Common extensions ===<br />
<br />
* {{ic|bdf}} and {{ic|bdf.gz}} – bitmap fonts, ''b''itmap ''d''istribution ''f''ormat and gzip compressed {{ic|bdf}}<br />
* {{ic|pcf}} and {{ic|pcf.gz}} – bitmaps, ''p''ortable ''c''ompiled ''f''ont and gzip compressed {{ic|pcf}}<br />
* {{ic|psf}}, {{ic|psfu}}, {{ic|psf.gz}} and {{ic|psfu.gz}} – bitmaps, ''P''C ''s''creen ''f''ont, ''P''C ''s''creen ''f''ont ''U''nicode and the gzipped versions (not compatible with X.Org)<br />
* {{ic|pfa}} and {{ic|pfb}} – outline fonts, ''P''ostScript ''f''ont ''A''SCII and ''P''ostScript ''f''ont ''b''inary. PostScript fonts carry built-in printer instructions.<br />
* {{ic|ttf}} – outline, ''T''rue''T''ype ''f''ont. Originally designed as a replacement for the PostScript fonts.<br />
* {{ic|otf}} – outline, ''O''pen''T''ype ''f''ont. TrueType with PostScript typographic instructions.<br />
<br />
For most purposes, the technical differences between TrueType and OpenType can be ignored, some fonts with a {{ic|ttf}} extension are actually OpenType fonts.<br />
<br />
=== Other formats ===<br />
<br />
The typesetting application, ''TeX,'' and its companion font software, ''Metafont,'' render characters using their own methods. Some of the file extensions used for fonts by these two programs are {{ic|*pk}}, {{ic|*gf}}, {{ic|mf}} and {{ic|vf}}.<br />
<br />
''FontForge,'' a font editing application, can store fonts in its native text-based format, {{ic|sfd}}, ''s''pline ''f''ont ''d''atabase.<br />
<br />
The [http://www.w3.org/TR/SVG/fonts.html SVG] format also has its own font description method.<br />
<br />
== Installation ==<br />
<br />
There are various methods for installing fonts.<br />
<br />
=== Pacman ===<br />
<br />
Fonts and font collections in the enabled repositories can be installed using [[Pacman|pacman]]. Available fonts may be found by using:<br />
$ pacman -Ss font<br />
Or to search for {{ic|ttf}} fonts only:<br />
$ pacman -Ss ttf<br />
<br />
=== Creating a package ===<br />
<br />
You should give pacman the ability to manage your fonts, which is done by creating an Arch package. These can also be shared with the community in the [[AUR]]. Here is an example of how to create a basic package. To learn more about building packages, read [[PKGBUILD]].<br />
<br />
{{bc|<nowiki><br />
pkgname=ttf-fontname<br />
pkgver=1.0<br />
pkgrel=1<br />
pkgdesc="custom fonts"<br />
arch=(any)<br />
depends=(fontconfig xorg-font-utils)<br />
source=("http://someurl.org/$pkgname.tar.bz2")<br />
install=$pkgname.install<br />
<br />
package() {<br />
install -d "$pkgdir/usr/share/fonts/TTF"<br />
install -m644 "$srcdir/$pkgname/"*.ttf "$pkgdir/usr/share/fonts/TTF/"<br />
}<br />
</nowiki>}}<br />
<br />
This PKGBUILD assumes the fonts are TrueType. An install file ({{ic|ttf-fontname.install}}) is also needed to update the font cache:<br />
<br />
{{bc|<nowiki><br />
post_install() {<br />
echo -n "Updating font cache... "<br />
fc-cache >/dev/null -fs<br />
mkfontscale /usr/share/fonts/TTF /usr/share/fonts/Type1<br />
mkfontdir /usr/share/fonts/TTF /usr/share/fonts/Type1<br />
echo done<br />
}<br />
<br />
post_upgrade() {<br />
post_install<br />
}<br />
<br />
post_remove() {<br />
post_install<br />
}<br />
</nowiki>}}<br />
<br />
For a more convenient package creation from TTFs you can also use {{AUR|makefontpkg}} from the [[AUR]].<br />
<br />
=== Manual installation ===<br />
<br />
The recommended way of adding fonts that are not in the repositories to your system is described in [[#Creating a package]]. This gives pacman the ability to remove or update them at a later time. Fonts can alternately be installed manually as well.<br />
<br />
To install fonts system-wide (available for all users), move the folder to the {{ic|/usr/share/fonts/}} directory. To install fonts for only a single user, use {{ic|~/.local/share/fonts}} ({{ic|~/.fonts/}} is now deprecated).<br />
<br />
For Xserver to load fonts directly (as opposed to the use of a ''font server'') the directory for your newly added font must be added with a FontPath entry. This entry is located in the ''Files'' section [[Xorg#Configuration|of your Xorg configuration file]] (e.g. {{ic|/etc/X11/xorg.conf}} or {{ic|/etc/xorg.conf}}). See [[#Older applications]] for more detail.<br />
<br />
Then update the fontconfig font cache:<br />
<br />
$ fc-cache -vf<br />
<br />
=== Manual installation: advanced method ===<br />
<br />
Manual installation and maintenance of your font resources may be especially useful if your collection is more specialized, e.g. if you use commercial fonts,<br />
if you use fonts in different formats, if you often install and remove font files, or if you just feel you need more control and better access than offered by<br />
the package manager. There are numerous benefits to such an approach:<br />
<br />
* You can avoid installation of multiple copies of the same family in different versions and formats (one of the most common reasons for rendering issues).<br />
* You can use multiple and non-standard physical sources of font files (e.g. an additional hard drive, a separate partition).<br />
* You can avoid relying on huge and cryptic local font sources which possibly contain 5 families you need and 55 you don't need (TeX Live & {{ic|09-texlive-fonts.conf}}, random font collections from the AUR, etc).<br />
* You can avoid rendering issues because your fontconfig settings were tuned to a different format but the one installed in your system.<br />
* You can quickly verify which families in which format(s) are present in the system and available for applications by visually inspecting the content of the main font directory (as a result, you don't need sophisticated and heavy-on-resources font management applications: {{Pkg|gtk2fontsel}} and basic CLI tools like {{ic|fc-query}} from {{Pkg|fontconfig}} package will do the job even better and faster).<br />
* When you install or upgrade a single font, the same version will be available for all applications, including LaTeX related software.<br />
* If necessary, you can quickly enable / disable a particular family because you know where exactly it can be found (useful for debugging).<br />
* You don't need to worry about redundant {{ic|/etc/fonts/conf.avail/nn-foo.conf}} fontconfig files, potentially conflicting with your rendering settings (especially when you are using a [[Font configuration#Patched_packages|customized font configuration and patched libraries]]).<br />
* In the long run, you save time needed to resolve issues and eliminate conflicts caused by careless use of the package manager.<br />
<br />
In practical terms, there are at least a few ways to achieve this, which, if necessary, can be adopted by any package manager. The one described below has<br />
proven to be very efficient and secure even with large font collections.<br />
<br />
* We are going to separate font source locations (e.g. {{ic|/usr/share/fonts.avail}}: this is where our fonts will be stored) from a directory containing symbolic links to the families in use ({{ic|/usr/share/fonts}}).<br />
<br />
* Each family is going to be located in a separate, clearly named subdirectory. The naming convention should be consistent and unambiguous, for instance:<br />
<br />
{{bc|<nowiki><br />
<ttf|otf|t1>-<optional_global_group_or_foundry_name>-<font_family_name><br />
</nowiki>}}<br />
<br />
This way the content of the source directory will look like this:<br />
<br />
{{bc|<nowiki><br />
$ ls /usr/share/fonts.avail<br />
<br />
/usr/share/fonts.avail/otf-heuristica<br />
/usr/share/fonts.avail/ttf-liberation<br />
/usr/share/fonts.avail/ttf-ms-arial<br />
...<br />
</nowiki>}}<br />
<br />
* We are not going to touch TeX Live font directories to avoid issues with LaTeX software. Instead, since we can use multiple locations, we will create symlinks in {{ic|/usr/share/fonts}}, giving applications access to particular families:<br />
<br />
{{bc|<nowiki><br />
# cd /usr/share/fonts<br />
# ln -s ../fonts.avail/otf-heuristica .<br />
# ln -s /opt/texlive/texmf-dist/fonts/truetype/public/opensans ttf-texlive-open.sans<br />
</nowiki>}}<br />
<br />
The result:<br />
<br />
{{bc|<nowiki><br />
$ ls /usr/share/fonts<br />
<br />
ttf-liberation -> ..fonts.avail/ttf-liberation<br />
ttf-ms-arial -> ..fonts.avail/ttf-ms-arial<br />
otf-heuristica -> ..fonts.avail/otf-heuristica<br />
otf-texlive-tex.gyre -> /opt/texlive/texmf-dist/fonts/opentype/public/tex-gyre<br />
ttf-texlive-open.sans -> /opt/texlive/texmf-dist/fonts/truetype/public/opensans<br />
...<br />
</nowiki>}}<br />
<br />
Finally, you may want to run the usual:<br />
<br />
{{bc|<nowiki><br />
# fc-cache && mkfontscale && mkfontdir<br />
</nowiki>}}<br />
<br />
A similar approach can be found in [[TeX_Live|TeX Live]] Wiki article, but it's way simpler and describes a per-user scenario rather than a global implementation.<br />
<br />
=== Older applications ===<br />
<br />
With older applications that do not support fontconfig (e.g. GTK+ 1.x applications, and {{ic|xfontsel}}) the index will need to be created in the font directory:<br />
<br />
$ mkfontscale<br />
$ mkfontdir<br />
<br />
Or to include more than one folder with one command:<br />
<br />
$ for dir in /font/dir1/ /font/dir2/; do xset +fp $dir; done && xset fp rehash<br />
<br />
Or if fonts were installed in a different sub-folders under the e.g. {{ic|/usr/share/fonts}}:<br />
<br />
$ for dir in * ; do if [ -d "$dir" ]; then cd "$dir";xset +fp "$PWD" ;mkfontscale; mkfontdir;cd .. ;fi; done && xset fp rehash<br />
<br />
At times the X server may fail to load the fonts directory and you will need to rescan all the {{ic|fonts.dir}} files:<br />
<br />
# xset +fp /usr/share/fonts/misc # Inform the X server of new directories<br />
# xset fp rehash # Forces a new rescan<br />
<br />
To check that the font(s) is included:<br />
<br />
$ xlsfonts | grep fontname<br />
<br />
{{note|Many packages will automatically configure Xorg to use the font upon installation. If that is the case with your font, this step is not necessary.}}<br />
<br />
This can also be set globally in {{ic|/etc/X11/xorg.conf}} or {{ic|/etc/X11/xorg.conf.d}}.<br />
<br />
Here is an example of the section that must be added to {{ic|/etc/X11/xorg.conf}}. Add or remove paths based on your particular font requirements.<br />
<br />
# Let X.Org know about the custom font directories<br />
Section "Files"<br />
FontPath "/usr/share/fonts/100dpi"<br />
FontPath "/usr/share/fonts/75dpi"<br />
FontPath "/usr/share/fonts/cantarell"<br />
FontPath "/usr/share/fonts/cyrillic"<br />
FontPath "/usr/share/fonts/encodings"<br />
FontPath "/usr/share/fonts/misc"<br />
FontPath "/usr/share/fonts/truetype"<br />
FontPath "/usr/share/fonts/TTF"<br />
FontPath "/usr/share/fonts/util"<br />
EndSection<br />
<br />
=== Pango Warnings ===<br />
When [http://www.pango.org/ Pango] is in use on your system it will read from [http://www.freedesktop.org/wiki/Software/fontconfig fontconfig] to sort out where to source fonts.<br />
<br />
(process:5741): Pango-WARNING **: failed to choose a font, expect ugly output. engine-type='PangoRenderFc', script='common'<br />
(process:5741): Pango-WARNING **: failed to choose a font, expect ugly output. engine-type='PangoRenderFc', script='latin'<br />
<br />
If you are seeing errors similar to this and/or seeing blocks instead of characters in your application then you need to add fonts and update the font cache. This example uses the {{Pkg|ttf-liberation}} fonts to illustrate the solution and runs as root to enable them system-wide.<br />
<br />
# pacman -S ttf-liberation<br />
-- output abbreviated, assumes installation succeeded -- <br />
<br />
# fc-cache -vfs<br />
/usr/share/fonts: caching, new cache contents: 0 fonts, 3 dirs<br />
/usr/share/fonts/TTF: caching, new cache contents: 16 fonts, 0 dirs<br />
/usr/share/fonts/encodings: caching, new cache contents: 0 fonts, 1 dirs<br />
/usr/share/fonts/encodings/large: caching, new cache contents: 0 fonts, 0 dirs<br />
/usr/share/fonts/util: caching, new cache contents: 0 fonts, 0 dirs<br />
/var/cache/fontconfig: cleaning cache directory<br />
fc-cache: succeeded<br />
<br />
You can test for a default font being set like so:<br />
<br />
# fc-match<br />
LiberationMono-Regular.ttf: "Liberation Mono" "Regular"<br />
<br />
== Console fonts ==<br />
<br />
{{Note|This section is about the [[Wikipedia:Linux console|Linux console]]. For an alternative console solutions offering more features (full Unicode fonts, modern graphics adapters etc.), see [[fbterm]], [[KMSCON]] or similar projects.}}<br />
<br />
By default, the [[Wikipedia:Virtual console|virtual console]] uses the kernel built-in font with a [[Wikipedia:CP437|CP437]] character set,<sup>[https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/drivers/tty/vt/Makefile#n4]</sup> but this can be easily changed.<br />
<br />
The [[Wikipedia:Linux console|Linux console]] uses UTF-8 encoding by default, but because the standard VGA-compatible framebuffer is used, a console font is limited to either a standard 256, or 512 glyphs. If the font has more than 256 glyphs, the number of colours is reduced from 16 to 8. In order to assign correct symbol to be displayed to the given Unicode value, a special translation map, often called ''unimap'', is needed. Nowadays most of the console fonts have the ''unimap'' built-in, historically it had to be loaded separately.<br />
<br />
The {{Pkg|kbd}} package provides tools to change virtual console font and font mapping. Available fonts are saved in the {{ic|/usr/share/kbd/consolefonts/}} directory, those ending with ''.psfu'' or ''.psfu.gz'' have a Unicode translation map built-in.<br />
<br />
Keymaps, the connection between the key pressed and the character used by the computer, are found in the subdirectories of {{ic|/usr/share/kbd/keymaps/}}, see [[Keyboard configuration in console]] for details.<br />
<br />
{{Note|Replacing the font can cause issues with programs that expect a standard VGA-style font, such as those using line drawing graphics.}}<br />
<br />
=== Previewing and testing ===<br />
<br />
{{Tip|An organized library of images for previewing is available: [http://alexandre.deverteuil.net/consolefonts/consolefonts.html Linux console fonts screenshots].}}<br />
<br />
The available glyphs or letters in the font can also be viewed as a table with using ''showconsolefont'':<br />
<br />
$ showconsolefont<br />
<br />
The ''setfont'' utility may be used to temporarily change the font, so that the user can consider its permanent use. Just pass the name of the font (they are located in {{ic|/usr/share/kbd/consolefonts/}}). For example:<br />
<br />
$ setfont lat2-16<br />
<br />
If the newly changed font is not suitable, a return to the default font with the following command (even if the console display is totally unreadable, this command will still work, just type the command "blindly"):<br />
<br />
$ setfont<br />
<br />
{{Note|''setfont'' only works on the console currently being used. Any other consoles, active or inactive, remain unaffected.}}<br />
<br />
=== Persistent configuration ===<br />
<br />
The {{ic|FONT}} variable in {{ic|/etc/vconsole.conf}} is used to set the font at boot, persistently for all consoles. See {{ic|man 5 vconsole.conf}} for details.<br />
<br />
For displaying characters such as ''Č, ž, đ, š'' or ''Ł, ę, ą, ś'' using the font {{ic|lat2-16.psfu.gz}}:<br />
<br />
{{hc|/etc/vconsole.conf|2=<br />
...<br />
FONT=lat2-16<br />
}}<br />
<br />
It means that second part of ISO/IEC 8859 characters are used with size 16. You can change font size using other values (e.g. {{ic|lat2-08}}). For the regions determined by 8859 specification, look at the [[wikipedia:ISO/IEC_8859#The_Parts_of_ISO.2FIEC_8859|Wikipedia table]].<br />
<br />
To use the specified font in early userspace, use the {{ic|consolefont}} hook in {{ic|/etc/mkinitcpio.conf}}. See [[Mkinitcpio#HOOKS]] for more information.<br />
<br />
If the fonts seems to not change on boot, or change only temporarily, it is most likely that they got reset when graphics driver was initialized and console was switched to framebuffer. To avoid this, load your graphics driver earlier. See for example [[Kernel Mode Setting#Early KMS start]], [https://bbs.archlinux.org/viewtopic.php?id=145765] or other ways to setup your framebuffer before {{ic|/etc/vconsole.conf}} is applied.<br />
<br />
== Font packages ==<br />
<br />
This is a selective list that includes many font packages from the [[AUR]] along with those in the official repositories. Fonts are tagged "Unicode" if they have wide Unicode support, see the project or Wikipedia pages for detail.<br />
<br />
Github user Ternstor has created a python script that generates HTML documents with PNG images of all the fonts in the AUR and the official repositories: [https://github.com/ternstor/distrofonts/blob/master/archfonts.py].<br />
<br />
=== Braille ===<br />
<br />
*{{Pkg|ttf-ubraille}} - Font containing Unicode symbols for ''braille''<br />
<br />
=== International users ===<br />
<br />
Applications and browsers select and display fonts depending upon fontconfig preferences and available font glyph for Unicode text. To list installed fonts for a particular language, issue a command {{ic|<nowiki>fc-list :lang="two letter language code"</nowiki>}}. For instance, to list installed Arabic fonts or fonts supporting Arabic glyph:<br />
{{hc|$ fc-list :lang&#61;ar &#124; cut -d: -f1|2=<br />
<nowiki><br />
/usr/share/fonts/TTF/FreeMono.ttf<br />
/usr/share/fonts/TTF/DejaVuSansCondensed.ttf<br />
/usr/share/fonts/truetype/custom/DroidKufi-Bold.ttf<br />
/usr/share/fonts/TTF/DejaVuSansMono.ttf<br />
/usr/share/fonts/TTF/FreeSerif.ttf<br />
</nowiki><br />
}}<br />
<br />
To properly render fonts for multilingual websites like Wikipedia or this Arch Linux wiki, install these packages: {{Pkg|ttf-freefont}}, {{Pkg|ttf-arphic-uming}}, {{Pkg|ttf-baekmuk}}<br />
<br />
==== Arabic & Urdu ====<br />
<br />
*{{AUR|ttf-qurancomplex-fonts}} - Fonts by King Fahd Glorious Quran Printing Complex in al-Madinah al-Munawwarah ''(AUR)''<br />
*{{AUR|ttf-amiri}} - A classical Arabic typeface in Naskh style poineered by Amiria Press ''(AUR)''<br />
*{{AUR|ttf-sil-lateef}} - Unicode Arabic font from SIL ''(AUR)''<br />
*{{AUR|ttf-sil-scheherazade}} - Unicode Arabic font from SIL ''(AUR)''<br />
*{{AUR|ttf-arabeyes-fonts}} - Collection of free Arabic fonts ''(AUR)''<br />
<br />
==== Persian ====<br />
<br />
*{{AUR|ttf-persian-irfonts}} - Official I.R. Iran Supreme Council of Information and Communication Technology (SCICT) standard persian fonts series ''(AUR)''<br />
*{{AUR|ttf-persian-borna}} - Borna Rayaneh Persian B font series ''(AUR)''<br />
*{{AUR|ttf-persian-x2}} - X Series 2 fonts are built on freely available fonts and extended to support Persian, Arabic, Urdu, Pashto, Dari, Uzbek, Kurdish, Uighur, old Turkish (Ottoman) and modern Turkish (Roman). ''(AUR)''<br />
<br />
==== Birman ====<br />
<br />
*{{AUR|ttf-myanmar3}} - Font for Myanmar/Burmese script ''(AUR)''<br />
<br />
==== Chinese, Japanese, Korean, Vietnamese ====<br />
<br />
===== (Mainly) Chinese =====<br />
<br />
*{{AUR|ttf-tw}} - Kai and Song traditional Chinese font from the Ministry of Education of Taiwan ''(AUR)''.<br />
*{{Pkg|wqy-microhei}} - A Sans-Serif style high quality CJKV outline font.<br />
*{{Pkg|wqy-zenhei}} - Hei Ti Style (sans-serif) Chinese Outline font embedded with bitmapped Song Ti (also supporting Japanese (partial) and Korean characters).<br />
*{{Pkg|ttf-arphic-ukai}} - ''Kaiti'' (brush stroke) Unicode font (enabling anti-aliasing is suggested)<br />
*{{Pkg|ttf-arphic-uming}} - ''Mingti'' (printed) Unicode font<br />
*{{Pkg|opendesktop-fonts}} - ''New Sung'' font, previously is ttf-fireflysung package<br />
*{{Pkg|wqy-bitmapfont}} - Bitmapped Song Ti (serif) Chinese font<br />
*{{Pkg|ttf-hannom}} - Chinese and Vietnamese TrueType font<br />
<br />
===== Japanese =====<br />
<br />
*{{Pkg|otf-ipafont}} - Formal style Japanese Gothic (sans-serif) and Mincho (serif) fonts set; one of the highest quality open source font. Default of openSUSE-ja.<br />
*{{AUR|ttf-vlgothic}} - Japanese Gothic fonts. Default of Debian/Fedora/Vine Linux ''(AUR)''<br />
*{{AUR|ttf-mplus}} - Modern Gothic style Japanese outline fonts. It includes all of Japanese Hiragana/Katakana, Basic Latin, Latin-1 Supplement, Latin Extended-A, IPA Extensions and most of Japanese Kanji, Greek, Cyrillic, Vietnamese with 7 weights (proportional) or 5 weights (monospace). ''(AUR)''<br />
*{{AUR|ttf-ipa-mona}}, {{AUR|ttf-monapo}} - Japanese fonts to show [[wikipedia:2channel_Shift_JIS_art|2channel Shift JIS art]] properly. ''(AUR)''<br />
*{{Pkg|ttf-sazanami}} - Japanese free TrueType font. This is outdated and not maintained any more, but may be defined as a fallback font on several environments.<br />
*{{Pkg|ttf-hanazono}} - A free Japanese kanji font, style Mincho (serif).<br />
<br />
===== Korean =====<br />
<br />
*{{Pkg|ttf-baekmuk}} - Collection of Korean TrueType fonts<br />
*{{AUR|ttf-alee}} - Set of free Hangul TrueType fonts (''AUR'')<br />
*{{AUR|ttf-unfonts-core}} - Un fonts (default Baekmuk fonts may be unsatisfactory) (''AUR'')<br />
*{{AUR|ttf-nanum}} - Nanum series TrueType fonts (''AUR'')<br />
*{{AUR|ttf-nanumgothic_coding}} - Nanum series fixed width TrueType fonts (''AUR'')<br />
<br />
==== Cyrillic ====<br />
<br />
''Also see [[#Monospaced]], [[#Sans-serif]] and [[#Serif]]''<br />
*{{AUR|ttf-paratype}} - Font family by ParaType: sans, serif, mono, extended cyrillic and latin, OFL license (''AUR'')<br />
*{{AUR|font-arhangai}} - Mongolian Cyrillic (''AUR'')<br />
*{{AUR|ttf-pingwi-typography}} - PingWi Typography (PWT) fonts (''AUR'')<br />
<br />
==== Greek ====<br />
<br />
Almost all Unicode fonts contain the Greek character set (polytonic included). Some additional font packages, which might not contain the complete Unicode set but utilize high quality Greek (and Latin, of course) typefaces are:<br />
*{{AUR|otf-gfs}} - Selection of OpenType fonts from the Greek Font Society ''(AUR)''<br />
*{{AUR|ttf-mgopen}} - Professional TrueType fonts from Magenta ''(AUR)''<br />
<br />
==== Hebrew ====<br />
<br />
*{{AUR|culmus}} - Nice collection of free Hebrew fonts ''(AUR)''<br />
<br />
==== Indic ====<br />
<br />
*{{Pkg|ttf-freebanglafont}} - Font for Bangla<br />
*{{Pkg|ttf-indic-otf}} - Indic OpenType Fonts collection (containing ttf-freebanglafont)<br />
:(This one contains a "look of disapproval" that might be more to your liking than the {{Pkg|bdf-unifont}} one mentioned elsewhere in this document)<br />
* {{AUR|lohit-fonts}} - Indic TrueType fonts from Fedora Project (containing Oriya Fonts and more) ''(AUR)''<br />
<br />
==== Khmer ====<br />
<br />
*{{Pkg|ttf-khmer}} - Font covering glyphs for Khmer language<br />
*[http://code.google.com/webfonts/family?family=Hanuman&subset=khmer Hanuman] ({{AUR|ttf-google-fonts-hg}} or {{AUR|ttf-google-fonts-git}})<br />
<br />
==== Sinhala ====<br />
<br />
*{{AUR|ttf-lklug}} - Sinhala Unicode font (''AUR'')<br />
<br />
==== Tamil ====<br />
<br />
*{{AUR|ttf-tamil}} - Tamil Unicode fonts (''AUR'')<br />
<br />
==== Tibetan ====<br />
<br />
*{{Pkg|ttf-tibetan-machine}} - Tibetan Machine TTFont<br />
<br />
=== Math ===<br />
<br />
*{{Pkg|font-mathematica}} - Mathematica fonts by Wolfram Research, Inc.<br />
*{{AUR|ttf-mathtype}} - MathType fonts ''(AUR)''<br />
*{{AUR|ttf-computer-modern-fonts}} - ''(AUR)''<br />
<br />
=== Microsoft fonts ===<br />
<br />
See [[MS Fonts]].<br />
<br />
=== Apple Mac OS X fonts ===<br />
<br />
* {{AUR|ttf-mac-fonts}} - Mac OS X TrueType fonts<br />
* {{AUR|ttf-mac}} - Mac OS X TrueType fonts (This package does not come with the ttf fonts (only the otf fonts), they have to be provided on their own.<br />
<br />
=== Monospaced ===<br />
<br />
Here are some suggestions. Every user has their own favorite, so experiment to find yours. <br />
If you are in a hurry, you read Dan Benjamin's blog post: [http://hivelogic.com/articles/top-10-programming-fonts ''Top 10 Programming Fonts''].<br />
<br />
Here is a long list of fonts by Trevor Lowing: http://www.lowing.org/fonts/.<br />
<br />
A comparison with images on Slant: [http://www.slant.co/topics/67/~what-are-the-best-programming-fonts What are the best programming fonts?]<br />
<br />
And a Stack Overflow question with some images: [http://stackoverflow.com/questions/4689/recommended-fonts-for-programming Recommended fonts for programming]<br />
<br />
==== TrueType ====<br />
<br />
* Agave ({{AUR|ttf-agave}})<br />
* [[Wikipedia:Andalé Mono|Andalé Mono]] ({{AUR|ttf-ms-fonts}})<br />
* Anka/Coder ({{AUR|ttf-anka-coder}})<br />
* [http://www.marksimonson.com/fonts/view/anonymous-pro Anonymous Pro] ({{AUR|ttf-anonymous-pro}}, included in {{AUR|ttf-google-fonts-hg}} and {{AUR|ttf-google-fonts-git}})<br />
* [[Wikipedia:Bitstream Vera|Bitstream Vera Mono]] ({{Pkg|ttf-bitstream-vera}})<br />
* [[Wikipedia:Consolas|Consolas]] ({{AUR|ttf-vista-fonts}}) - Windows programming font<br />
* [[Wikipedia:Courier New|Courier New]] ({{AUR|ttf-ms-fonts}})<br />
* Cousine ({{AUR|ttf-chromeos-fonts}} or {{AUR|ttf-google-fonts-hg}} or {{AUR|ttf-google-fonts-git}}) - Chrome/Chromium OS replacement for Courier New (metric-compatible)<br />
* [[Wikipedia:DejaVu fonts|DejaVu Sans Mono]] ({{Pkg|ttf-dejavu}}) - Unicode<br />
* [[Wikipedia:Droid (font)|Droid Sans Mono]] ({{Pkg|ttf-droid}}, included in {{AUR|ttf-google-fonts-hg}} and {{AUR|ttf-google-fonts-git}})<br />
* Envy Code R ({{AUR|ttf-envy-code-r}})<br />
* [[Wikipedia:GNU FreeFont|FreeMono]] ({{Pkg|ttf-freefont}}) - Unicode<br />
* [[Wikipedia:Inconsolata|Inconsolata]] ({{Pkg|ttf-inconsolata}}) - Excellent programming font<br />
* [[Wikipedia:Inconsolata|Inconsolata-g]] ({{AUR|ttf-inconsolata-g}}) - adds some programmer-friendly modifications<br />
* [[Wikipedia:Liberation fonts|Liberation Mono]] ({{Pkg|ttf-liberation}}) - Replacement for Courier New, based on Cousine (metric-compatible)<br />
* [[Wikipedia:Lucida Typewriter|Lucida Typewriter]] (included in package {{AUR|jre}})<br />
* [[Wikipedia:Monaco (typeface)|Monaco]] ({{AUR|ttf-monaco}}) - Popular programming font on OSX/Textmate<br />
* Monofur ({{AUR|ttf-monofur}})<br />
* [[Wikipedia:Source_Code_Pro|Source Code Pro]] ({{pkg|adobe-source-code-pro-fonts}})<br />
<br />
==== Bitmap ====<br />
<br />
*Default 8x16<br />
*Dina ({{Pkg|dina-font}})<br />
*[http://font.gohu.org/ Gohu] ({{AUR|gohufont}})<br />
*Lime ({{Pkg|artwiz-fonts}})<br />
*[[Wikipedia:ProFont|ProFont]] ({{Pkg|profont}})<br />
*[[Wikipedia:Proggy Programming Fonts|Proggy Programming Fonts]] ({{AUR|proggyfonts}})<br />
*Proggy opti cyrillic ({{AUR|proggyopticyr-font}})<br />
*Tamsyn ({{Pkg|tamsyn-font}})<br />
*[[Wikipedia:Terminus (typeface)|Terminus]] ({{Pkg|terminus-font}})<br />
*Unifont (glyphs like (look of disapproval)) ({{Pkg|bdf-unifont}})<br />
<br />
=== Sans-serif ===<br />
<br />
*[http://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=andika Andika] ({{AUR|ttf-andika}}, included in {{AUR|ttf-sil-fonts}})<br />
*[[Wikipedia:Arial|Arial]] ({{AUR|ttf-ms-fonts}})<br />
*[[Wikipedia:Arial Black|Arial Black]] ({{AUR|ttf-ms-fonts}})<br />
*Arimo ({{AUR|ttf-chromeos-fonts}} or {{AUR|ttf-google-fonts-hg}} or {{AUR|ttf-google-fonts-git}}) - Chrome/Chromium OS replacement for Arial (metric-compatible)<br />
*[[Wikipedia:Calibri|Calibri]] ({{AUR|ttf-vista-fonts}})<br />
*[[Wikipedia:Candara|Candara]] ({{AUR|ttf-vista-fonts}})<br />
*[[Wikipedia:Constantia (typeface)|Constantia]] ({{AUR|ttf-vista-fonts}})<br />
*[[Wikipedia:Corbel (typeface)|Corbel]] ({{AUR|ttf-vista-fonts}})<br />
*[[Wikipedia:DejaVu fonts|DejaVu Sans]] ({{Pkg|ttf-dejavu}}) - Unicode<br />
*[[Wikipedia:Droid (font)|Droid Sans]] ({{Pkg|ttf-droid}}, included in {{AUR|ttf-google-fonts-hg}} and {{AUR|ttf-google-fonts-git}})<br />
*[[Wikipedia:GNU FreeFont|FreeSans]] ({{Pkg|ttf-freefont}}) - Unicode<br />
*[[Wikipedia:Impact (typeface)|Impact]] ({{AUR|ttf-ms-fonts}})<br />
*[[Wikipedia:Liberation fonts|Liberation Sans]] ({{Pkg|ttf-liberation}}) Replacement for Arial, based on Arimo (metric-compatible)<br />
*[[Wikipedia:Linux Libertine|Linux Biolinum]] ({{Pkg|ttf-linux-libertine}})<br />
*[[Wikipedia:Lucida Sans|Lucida Sans]] ({{AUR|ttf-ms-fonts}})<br />
*[[Wikipedia:Microsoft Sans Serif|Microsoft Sans Serif]] ({{AUR|ttf-ms-fonts}})<br />
*[[Wikipedia:PT Sans|PT Sans]] ({{AUR|ttf-google-fonts-hg}} or {{AUR|ttf-google-fonts-git}}) - 3 major variations: normal, narrow, and caption - Unicode: Latin, Cyrillic<br />
*[[Wikipedia:Source Sans Pro|Source Sans Pro]] ({{pkg|adobe-source-sans-pro-fonts}})<br />
*[[Wikipedia:Tahoma (typeface)|Tahoma]] ({{AUR|ttf-tahoma}})<br />
*[[Wikipedia:Trebuchet MS|Trebuchet]] ({{AUR|ttf-ms-fonts}})<br />
*[[Wikipedia:Ubuntu-Title|Ubuntu-Title]] ({{AUR|ttf-ubuntu-title}})<br />
*[[Wikipedia:Ubuntu Font Family|Ubuntu Font Family]] ({{Pkg|ttf-ubuntu-font-family}})<br />
*[[Wikipedia:Verdana|Verdana]] ({{AUR|ttf-ms-fonts}})<br />
<br />
=== Script ===<br />
<br />
*[[Wikipedia:Comic Sans|Comic Sans]] ({{AUR|ttf-ms-fonts}})<br />
<br />
=== Serif ===<br />
<br />
*[[Wikipedia:Cambria (typeface)|Cambria]] ({{AUR|ttf-vista-fonts}})<br />
*[[Wikipedia:Charis SIL|Charis]] ({{AUR|ttf-charis}}, included in {{AUR|ttf-sil-fonts}}) - Unicode: Latin, Cyrillic<br />
*[[Wikipedia:DejaVu fonts|DejaVu Serif]] ({{Pkg|ttf-dejavu}}) - Unicode<br />
*[[Wikipedia:Doulos SIL|Doulos]] ({{AUR|doulos-sil}}, included in {{AUR|ttf-sil-fonts}}) - Unicode: Latin, Cyrillic<br />
*[[Wikipedia:Droid (font)|Droid Serif]] ({{Pkg|ttf-droid}}, included in {{AUR|ttf-google-fonts-hg}} and {{AUR|ttf-google-fonts-git}})<br />
*[[Wikipedia:GNU FreeFont|FreeSerif]] ({{Pkg|ttf-freefont}}) - Unicode<br />
*[[Wikipedia:Gentium|Gentium]] ({{Pkg|ttf-gentium}}, included in {{AUR|ttf-sil-fonts}}) - Unicode: Latin, Greek, Cyrillic, Phonetic Alphabet<br />
*[[Wikipedia:Georgia (typeface)|Georgia]] ({{AUR|ttf-ms-fonts}})<br />
*[[Wikipedia:Liberation fonts|Liberation Serif]] ({{Pkg|ttf-liberation}}) - Replacement for Times New Roman, based on Tinos (metric-compatible)<br />
*[[Wikipedia:Linux Libertine|Linux Libertine]] ({{Pkg|ttf-linux-libertine}}) - Unicode: Latin, Greek, Cyrillic, Hebrew<br />
*[[Wikipedia:Times New Roman|Times New Roman]] ({{AUR|ttf-ms-fonts}})<br />
*Tinos ({{AUR|ttf-chromeos-fonts}} or {{AUR|ttf-google-fonts-hg}} or {{AUR|ttf-google-fonts-git}}) - Chrome/Chromium OS replacement for Times New Roman (metric-compatible)<br />
<br />
=== Unsorted ===<br />
<br />
<!--This section should be absorbed into the Monospace/Serif/Sans-Serif structure--><br />
*{{AUR|ttf-google-fonts-git}} and {{AUR|ttf-google-fonts-hg}} — a huge collection of free fonts (including ubuntu, inconsolata, droid, etc.) - Note: Your font dialog might get very long as >100 fonts will be added. {{AUR|ttf-google-fonts-hg}} pulls down the entire Mercurial repository from the upstream Web Fonts project. {{AUR|ttf-google-fonts-git}} pulls from a much smaller and leaner unofficial repository hosted on GitHub. ''(AUR)''<br />
*{{Pkg|ttf-mph-2b-damase}} — Covers full plane 1 and several scripts<br />
*{{Pkg|ttf-symbola}} — Provides emoji and many many other symbols<br />
*{{AUR|ttf-sil-fonts}} — Gentium, Charis, Doulos, Andika and Abyssinica from SIL ''(AUR)''<br />
*{{Pkg|font-bh-ttf}} — X.Org Luxi fonts<br />
*{{Pkg|ttf-cheapskate}} — Font collection from ''dustismo.com''<br />
*{{AUR|ttf-isabella}} — Calligraphic font based on the ''Isabella Breviary'' of 1497<br />
*{{Pkg|ttf-junicode}} — Junius font containing almost complete medieval latin script glyphs<br />
*arkpandorafonts {{AUR|ttf-arkpandora}} — Alternative to Arial and Times New Roman fonts ''(AUR)''<br />
*{{Pkg|xorg-fonts-type1}} — IBM Courier and Adobe Utopia sets of [[Wikipedia:PostScript fonts|PostScript fonts]]<br />
<br />
== Fallback font order with X11 ==<br />
<br />
Fontconfig automatically chooses a font that matches the current requirement. That is to say, if one is looking at a window containing English and Chinese for example, it will switch to another font for the Chinese text if the default one does not support it.<br />
<br />
Fontconfig lets every user configure the order they want via {{ic|$XDG_CONFIG_HOME/fontconfig/fonts.conf}}.<br />
If you want a particular Chinese font to be selected after your favorite Serif font, your file would look like this:<br />
<?xml version="1.0"?><br />
<!DOCTYPE fontconfig SYSTEM "fonts.dtd"><br />
<fontconfig><br />
<alias><br />
<family>serif</family><br />
<prefer><br />
<family>Your favorite Latin Serif font name</family><br />
<family>Your Chinese font name</family><br />
</prefer><br />
</alias><br />
</fontconfig><br />
<br />
You can add a section for Sans-serif and monospace as well. For more informations, have a look at the fontconfig manual.<br />
<br />
== Font alias ==<br />
<br />
There are several font aliases which represent other fonts in order that applications may use similar fonts. The most common aliases are: {{ic|serif}} for a font of the serif type (e.g. DejaVu Serif); {{ic|sans-serif}} for a font of the sans-serif type (e.g. DejaVu Sans); and {{ic|monospace}} for a monospaced font (e.g. DejaVu Sans Mono). However, the fonts which these aliases represent may vary and the relationship is often not shown in font management tools, such as those found in [[KDE]] and other [[desktop environments]].<br />
<br />
To reverse an alias and find which font it is representing, run:<br />
$ fc-match monospace<br />
DejaVuSansMono.ttf: "DejaVu Sans Mono" "Book"<br />
<br />
In this case, {{ic|DejaVuSansMono.ttf}} is the font represented by the monospace alias.<br />
<br />
== Tips ==<br />
<br />
=== List all installed fonts ===<br />
<br />
You can use the following command to list all installed fonts that are available on your system. <br />
<br />
$ fc-list<br />
<br />
=== Application-specific font cache ===<br />
<br />
Matplotlib ({{pkg|python-matplotlib}} or {{pkg|python2-matplotlib}}) uses its own font cache, so after updating fonts, be sure to remove {{ic|$HOME/.matplotlib/fontList.cache}}, <br />
{{ic|$HOME/.cache/matplotlib/fontList.cache}}, {{ic|$HOME/.sage/matplotlib-1.2.1/fontList.cache}}, etc. so it will regenerate its cache and find the new fonts [http://matplotlib.1069221.n5.nabble.com/getting-matplotlib-to-recognize-a-new-font-td40500.html].<br />
<br />
== See Also ==<br />
<br />
* [[Font configuration]]<br />
* [[Infinality-bundle+fonts]]</div>Fylwind