https://wiki.archlinux.org/api.php?action=feedcontributions&user=Alive4ever&feedformat=atomArchWiki - User contributions [en]2024-03-29T05:31:53ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Aria2&diff=565121Aria22019-01-29T00:48:15Z<p>Alive4ever: /* Web UIs */ Add a note that ruby-xmlrpc is needed for aria2rpc to run</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Download utilities]]<br />
[[Category:BitTorrent]]<br />
[[fa:Aria2]]<br />
[[it:Aria2]]<br />
[[ja:Aria2]]<br />
[[ru:Aria2]]<br />
From the project [https://aria2.github.io/ home page]:<br />
:aria2 is a lightweight multi-protocol & multi-source command-line download utility. It supports [[HTTP]]/[[HTTPS]], [[FTP]], [[BitTorrent]] and [[Wikipedia:Metalink|Metalink]]. aria2 can be manipulated via built-in [[Wikipedia:JSON-RPC|JSON-RPC]] and [[Wikipedia:XML-RPC|XML-RPC]] interfaces.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|aria2}} package.<br />
<br />
You may also want to install [https://github.com/GutenYe/systemd-units/tree/master/aria2 aria2-systemd] to use aria2 as a [[daemon]].<br />
<br />
{{Note|The executable is called {{ic|aria2c}}.}}<br />
<br />
== Configuration ==<br />
<br />
=== aria2.conf ===<br />
<br />
aria2 looks to {{ic|$XDG_CONFIG_HOME/aria2/aria2.conf}} for a set of global configuration options by default. This behavior can be modified with the {{ic|--conf-path}} switch:<br />
* Download {{ic|aria2.example.rar}} using the options specified in the configuration file {{ic|/file/aria2.rapidshare}}<br />
<nowiki>$ aria2c --conf-path=/file/aria2.rapidshare http://rapidshare.com/files/12345678/aria2.example.rar</nowiki><br />
<br />
If {{ic|$XDG_CONFIG_HOME/aria2/aria2.conf}} exists and the options specified in {{ic|/file/aria2.rapidshare}} are desired, the {{ic|--no-conf}} switch must be appended to the command:<br />
* Do not use the default configuration file and download {{ic|aria2.example.rar}} using the options specified in the configuration file {{ic|/file/aria2.rapidshare}}<br />
<nowiki>$ aria2c --no-conf --conf-path=/file/aria2.rapidshare http://rapidshare.com/files/12345678/aria2.example.rar</nowiki><br />
<br />
If {{ic|$XDG_CONFIG_HOME/aria2/aria2.conf}} does not yet exist and you wish to simplify the management of configuration options:<br />
$ touch $XDG_CONFIG_HOME/aria2/aria2.conf<br />
<br />
=== Example aria2.conf ===<br />
<br />
{{bc|<nowiki><br />
continue<br />
dir=${HOME}/Desktop<br />
file-allocation=none<br />
input-file=${HOME}/.aria2/input.conf<br />
log-level=warn<br />
max-connection-per-server=4<br />
min-split-size=5M<br />
on-download-complete=exit<br />
</nowiki>}}<br />
<br />
This is essentially the same as if running the following:<br />
<br />
$ aria2c dir=${HOME}/Desktop file-allocation=none input-file=${HOME}/.aria2/input.conf on-download-complete=exit log-level=warn FILE<br />
<br />
{{Note|The example aria2.conf above may incorrectly use the $HOME variable. Some users have reported the curly brace syntax to explicitly create a separate ${HOME} subdirectory in the aria2 working directory. Such a directory may be difficult to traverse as bash will consider it to be the $HOME environment variable. For now, it is recommended to use absolute path names in aria2.conf.}}<br />
<br />
==== Option details ====<br />
<br />
; {{ic|continue}}: Continue downloading a partially downloaded file if a corresponding control file exists.<br />
; {{ic|<nowiki>dir=${HOME}/Desktop</nowiki>}}: Store the downloaded file(s) in {{ic|~/Desktop}}.<br />
; {{ic|<nowiki>file-allocation=none</nowiki>}}: Do not pre-allocate disk space before downloading begins. (Default: prealloc) '''<sup>1</sup>'''<br />
; {{ic|<nowiki>input-file=${HOME}/.aria2/input.conf</nowiki>}}: Download a list of line, or TAB separated URIs found in {{ic|~/.aria2/input.conf}} <br />
; {{ic|<nowiki>log-level=warn</nowiki>}}: Set log level to output warnings and errors only. (Default: debug)<br />
; {{ic|<nowiki>max-connection-per-server=4</nowiki>}}: Set a maximum of four (4) connections to each server per file. (Default: 1)<br />
; {{ic|<nowiki>min-split-size=5M</nowiki>}}: Only split the file if the size is larger than 2*5MB = 10MB. (Default: 20M)<br />
; {{ic|<nowiki>on-download-complete=exit</nowiki>}}: Run the {{ic|exit}} command and exit the shell once the download session is complete.<br />
<br />
===== Example input file #1 =====<br />
<br />
* Download {{ic|aria2-1.10.0.tar.bz2}} from two separate sources to {{ic|~/Desktop}} before merging as {{ic|aria2-1.10.0.tar.bz2}}<br />
<nowiki>http://aria2.net/files/stable/aria2-1.10.0/aria2-1.10.0.tar.bz2 http://sourceforge.net/projects/aria2/files/stable/aria2-1.10.0/aria2-1.10.0.tar.bz2</nowiki><br />
<br />
===== Example input file #2 =====<br />
<br />
* Download {{ic|aria2-1.9.5.tar.bz2}} and save to {{ic|/file/old}} as {{ic|aria2.old.tar.bz2 }} &<br />
* Download {{ic|aria2-1.10.0.tar.bz2}} and save to {{ic|~/Desktop}} as {{ic|aria2.new.tar.bz2}}<br />
<br />
<nowiki>http://aria2.net/files/stable/aria2-1.9.5/aria2-1.9.5.tar.bz2</nowiki><br />
dir=/file/old<br />
out=aria2.old.tar.bz2<br />
<nowiki>http://aria2.net/files/stable/aria2-1.10.0/aria2-1.10.0.tar.bz2</nowiki><br />
out=aria2.new.tar.bz2<br />
<br />
==== Additional notes ====<br />
<br />
; <sup>1</sup> {{ic|<nowiki>--file-allocation=falloc</nowiki>}}: Recommended for newer file systems such as ext4 (with extents support), btrfs or xfs as it allocates large files (GB) almost instantly. Do not use falloc with legacy file systems such as ext3 as prealloc consumes approximately the same amount of time as standard allocation would while locking the aria2 process from proceeding to download.<br />
<br />
{{Tip|See {{ic|<nowiki>aria2c --help=#all</nowiki>}} and the aria2 man page for a complete list of configuration options.}}<br />
<br />
=== Example aria2.rapidshare ===<br />
<br />
{{bc|<nowiki><br />
http-user=USER_NAME<br />
http-passwd=PASSWORD<br />
allow-overwrite=true<br />
dir=/file/Downloads<br />
file-allocation=falloc<br />
enable-http-pipelining=true<br />
input-file=/file/input.rapidshare<br />
log-level=error<br />
max-connection-per-server=2<br />
summary-interval=120<br />
</nowiki>}}<br />
<br />
==== Option details ====<br />
<br />
; {{ic|<nowiki>http-user=USER_NAME</nowiki>}}: Set HTTP [[Wikipedia:User_(computing)|username]] as USER_NAME for password-protected logins. This affects all [[Wikipedia:Uniform_Resource_Identifier|URIs]].<br />
; {{ic|<nowiki>http-passwd=PASSWORD</nowiki>}}: Set HTTP [[Wikipedia:Password|password]] as PASSWORD for password-protected logins. This affects all URIs.<br />
; {{ic|<nowiki>allow-overwrite=true</nowiki>}}: Restart download if a corresponding control file does not exist. (Default: false)<br />
; {{ic|<nowiki>dir=/file/Downloads</nowiki>}}: Store the downloaded file(s) in {{ic|/file/Downloads}}.<br />
; {{ic|<nowiki>file-allocation=falloc</nowiki>}}: Call [http://www.kernel.org/doc/man-pages/online/pages/man2/fallocate.2.html posix_fallocate()] to allocate disk space before downloading begins. (Default: prealloc) <br />
; {{ic|<nowiki>enable-http-pipelining=true</nowiki>}}: Enable [[Wikipedia:HTTP_Pipelining|HTTP/1.1 pipelining]] to overcome network latency and to reduce network load. (Default: false)<br />
; {{ic|<nowiki>input-file=/file/input.rapidshare</nowiki>}}: Download a list of single line of TAB separated URIs found in {{ic|/file/input.rapidshare}}<br />
; {{ic|<nowiki>log-level=error</nowiki>}}: Set log level to output errors only. (Default: debug)<br />
; {{ic|<nowiki>max-connection-per-server=2</nowiki>}}: Set a maximum of two (2) connections to each server per file. (Default: 1)<br />
; {{ic|<nowiki>summary-interval=120</nowiki>}}: Output download progress summary every 120 seconds. (Default: 60) '''<sup>3</sup>'''<br />
<br />
==== Additional notes ====<br />
<br />
* Because {{ic|aria2.rapidshare}} the contains a username and password, it is advisable to set permissions on the file to 600, or similar.<br />
<br />
$ cd /file<br />
$ chmod 600 /file/aria2.rapidshare<br />
$ ls -l<br />
total 128M<br />
-rw------- 1 arch users 167 Aug 20 00:00 aria2.rapidshare<br />
<br />
; '''<sup>3</sup>''' {{ic|<nowiki>summary-interval=0</nowiki>}}: Supresses download progress summary output and may improve overall performance. Logs will continue to be output according to the value specified in the {{ic|log-level}} option. <br />
<br />
{{Tip|The example configuration file can also be applied to [http://www.hotfile.com/ Hotfile], [http://depositfiles.com/ DepositFiles], et.al.}}<br />
{{Note|Command-line options always take precedence over options listed in a configuration file.}}<br />
<br />
=== Example aria2.bittorrent ===<br />
<br />
{{bc|<nowiki><br />
bt-seed-unverified<br />
max-overall-upload-limit=1M<br />
max-upload-limit=128K<br />
seed-ratio=5.0<br />
seed-time=240<br />
</nowiki>}}<br />
<br />
==== Option details ====<br />
<br />
; {{ic|<nowiki>bt-seed-unverified=false</nowiki>}}: Do not check the hash of the file(s) before seeding. (Default: true)<br />
; {{ic|<nowiki>max-overall-upload-limit=1M</nowiki>}}: Set maximum overall upload speed to 1MB/sec. (Default: 0)<br />
; {{ic|<nowiki>max-upload-limit=128K</nowiki>}}: Set maximum upload speed per torrent to 128K/sec. (Default: 0)<br />
; {{ic|<nowiki>seed-ratio=5.0</nowiki>}}: Seed completed torrents until share ratio reaches 5.0. (Default: 1.0)<br />
; {{ic|<nowiki>seed-time=240</nowiki>}}: Seed completed torrents for 240 minutes.<br />
<br />
{{Note|If both {{ic|seed-ratio}} and {{ic|seed-time}} are specified, seeding ends when at least one of the conditions is satisfied.}}<br />
<br />
=== Example aria2.daemon ===<br />
<br />
This configuration can be used to start Aria2 as a service. It can be used in conjunction with several of the frontends listed below. Note that rpc-user and rpc-pass are deprecated, but most frontends have not been ported to the new authentication yet. Do not forget to change user, password and Download directory.<br />
<br />
{{bc|<nowiki><br />
continue<br />
daemon=true<br />
dir=/home/aria2/Downloads<br />
file-allocation=falloc<br />
log-level=warn<br />
max-connection-per-server=4<br />
max-concurrent-downloads=3<br />
max-overall-download-limit=0<br />
min-split-size=5M<br />
enable-http-pipelining=true<br />
<br />
enable-rpc=true<br />
rpc-listen-all=true<br />
rpc-user=rpcuser<br />
rpc-passwd=rpcpass<br />
</nowiki>}}<br />
<br />
== Frontends ==<br />
<br />
{{note|Settings implemented in frontends do not affect {{ic|aria2}}'s own configuration, and it is uncertain whether the different UIs reuse {{ic|aria2}} configuration if a custom one has been made. Users should ensure their desired parameters are effectively implemented within selected tools and that they are stored persistently (uGet for example has its own {{ic|aria2}}'s command line which sticks across reboots).}}<br />
<br />
=== Web UIs ===<br />
<br />
{{Note|These frontends need {{ic|aria2c}} to be started with {{ic|--enable-rpc}} in order to work. They are meant to run on your local computer, not on a remote server that downloads using aria}}<br />
<br />
* {{App|YaaW|Yet Another Aria2 Web Frontend in pure HTML/CSS/Javascirpt.|https://github.com/binux/yaaw|{{AUR|yaaw-git}}}}<br />
* {{App|Webui|Html frontend for aria2.|https://github.com/ziahamza/webui-aria2|{{AUR|webui-aria2}}}}<br />
* {{App|aria2rpc|Command line tool for connecting to a remote instance of {{ic|aria2c}}. If {{ic|aria2c}} is installed it can be found under {{ic|/usr/share/doc/aria2/xmlrpc/aria2rpc}}.|https://github.com/tatsuhiro-t/aria2/blob/master/doc/xmlrpc/aria2rpc|{{Pkg|aria2}}}}.<br />
{{Note|{{AUR|ruby-xmlrpc}} is needed to run aria2rpc}}<br />
<br />
=== Other UIs ===<br />
{{note|These frontends '''do not need''' {{ic|aria2c}} to be started with {{ic|--enable-rpc}} to function.}}<br />
<br />
* {{App|aria2fe|A GUI for the CLI-based aria2 download utility.|http://sourceforge.net/projects/aria2fe/|{{AUR|aria2fe}}}}<br />
* {{App|karia2|QT4 interface for aria2 download mananger.|http://sourceforge.net/projects/karia2/|{{AUR|karia2-svn}}}}<br />
* {{App|uGet|Feature-rich GTK+/CLI download manager which can use aria2 as a back-end by enabling a built-in plugin.|http://ugetdm.com|{{Pkg|uget}}}}<br />
* {{App|Persepolis DM| Graphical front-end for aria2 download manager with lots of features. Supports HTTP and FTP.|https://github.com/persepolisdm/|{{AUR|persepolis}},{{AUR|persepolis-git}}}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Download the packages without installing them ===<br />
<br />
Just use the command below:<br />
<br />
# pacman -Sp packages | aria2c -i -<br />
<br />
{{Ic|pacman -Sp}} lists the urls of the packages on stdout, instead of downloading them, then {{Ic|<nowiki>|</nowiki>}} pipes it to the next command. Finally, The {{Ic|-i}} in {{Ic|aria2c -i -}} switch to aria2c means that the urls for files to be downloaded should be read from the file specified, but if {{Ic|-}} is passed, then read the urls from stdin.<br />
<br />
=== pacman XferCommand ===<br />
<br />
See [[pacman/Tips and tricks#aria2]].<br />
<br />
=== Changing the User Agent ===<br />
<br />
Some sites may filter the requests based on your User Agent, since Aria2 is not a well known downloader, it may be good to use a most known downloader or browser as the Aria's User Agent. Just use the -U option like this:<br />
<br />
$ aria2c -UWget <nowiki>http://some-url-to-download/file.xyz</nowiki><br />
<br />
You can use whatever you want, like '''-UMozilla/5.0''' and so on.<br />
<br />
=== Using Aria2 with makepkg ===<br />
<br />
You can use Aria2 instead of {{Pkg|curl}} to download source files, just change the {{ic|DLAGENTS}} variable as follows:<br />
<br />
{{hc|/etc/makepkg.conf|2=<br />
[...]<br />
DLAGENTS=('ftp::/usr/bin/aria2c -UWget -s4 %u -o %o'<br />
'http::/usr/bin/aria2c -UWget -s4 %u -o %o'<br />
'https::/usr/bin/aria2c -UWget -s4 %u -o %o'<br />
'rsync::/usr/bin/rsync --no-motd -z %u %o'<br />
'scp::/usr/bin/scp -C %u %o')<br />
[...]<br />
}}<br />
<br />
{{Note|Use the {{ic|-UWget}} option to change the user agent to Wget. It may prevent problems when downloading from sites that filters the requests based on the user agent to provide different responses on what the users uses to access the URL. Since Aria2 is a lesser known downloader it may be recognized by the site as a browser instead of a downloader, so changing the user agent to Wget may fix it in most cases}}<br />
<br />
== See also ==<br />
<br />
* [https://aria2.github.io/manual/en/html/index.html aria2 manual] - Official site<br />
* [https://aria2.github.io/manual/en/html/aria2c.html#example aria2 usage examples] - Official site</div>Alive4everhttps://wiki.archlinux.org/index.php?title=Network_tools&diff=558923Network tools2018-12-12T02:47:09Z<p>Alive4ever: /* Netcat */ Add libressl-netcat as one of netcat tools.</p>
<hr />
<div>[[Category:Networking]]<br />
[[Category:Lists of software]]<br />
[[es:Network tools]]<br />
[[pt:Network tools]]<br />
{{Related articles start}}<br />
{{Related|Telnet}}<br />
{{Related|Nmap}}<br />
{{Related|Wireshark}}<br />
{{Related articles end}}<br />
This page lists various network tools. ''ping'' and ''ip'' are covered by [[Network configuration]].<br />
<br />
== Traceroute ==<br />
<br />
[[Wikipedia:Traceroute|Traceroute]] is a tool to display the path of packets across an IP network.<br />
<br />
There are several implementations available:<br />
<br />
* {{man|8|tracepath}} from {{Pkg|iputils}} (part of {{Grp|base}})<br />
* {{man|8|traceroute}} from {{Pkg|traceroute}}<br />
* {{App|MTR|Combines the functionality of traceroute and ping into one tool.|http://www.bitwizard.nl/mtr/|{{Pkg|mtr}}, {{Pkg|mtr-gtk}}}}<br />
<br />
== Netcat ==<br />
<br />
See also [[Wikipedia:Netcat]].<br />
<br />
* {{App|GNU Netcat|GNU rewrite of netcat, the network piping application.|http://netcat.sourceforge.net/|{{Pkg|gnu-netcat}}}}<br />
* {{App|openbsd-netcat|TCP/IP swiss army knife. OpenBSD variant.|https://packages.debian.org/sid/netcat-openbsd|{{Pkg|openbsd-netcat}}}}<br />
* {{App|libressl-netcat|Low level UDP/TCP connection tool with support for TLS protocol|https://www.libressl.org|{{Aur|libressl-netcat}}}}<br />
<br />
A more complex alternative is {{Pkg|socat}}.<br />
<br />
== Whois ==<br />
<br />
See also [[Wikipedia:WHOIS]].<br />
<br />
* {{App|whois|Intelligent WHOIS client.|https://github.com/rfc1036/whois|{{Pkg|whois}}}}<br />
* {{App|jwhois|An Internet Whois client|https://www.gnu.org/software/jwhois/|{{AUR|jwhois}}}}<br />
<br />
== inetd ==<br />
<br />
Arch Linux does not have [[Wikipedia:inetd|inetd]] but you can instead use [http://0pointer.de/blog/projects/inetd.html systemd] or [[Wikipedia:xinetd|xinetd]] ({{Pkg|xinetd}}).<br />
<br />
== See also ==<br />
<br />
* [[List of applications/Security#Network security]]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=Bash&diff=482477Bash2017-07-21T09:36:19Z<p>Alive4ever: /* Command line */ Add keybindings for variable and wildcard expansion</p>
<hr />
<div>[[Category:Command shells]]<br />
[[de:Bash]]<br />
[[es:Bash]]<br />
[[it:Bash]]<br />
[[ja:Bash]]<br />
[[ru:Bash]]<br />
[[zh-hans:Bash]]<br />
{{Related articles start}}<br />
{{Related|Bash/Functions}}<br />
{{Related|Bash/Prompt customization}}<br />
{{Related|Environment variables}}<br />
{{Related|Readline}}<br />
{{Related|Fortune}}<br />
{{Related|Pkgfile}}<br />
{{Related articles end}}<br />
'''Bash''' (Bourne-again Shell) is a [[command-line shell]]/programming language by the [[GNU Project]]. Its name is a homaging reference to its predecessor: the long-deprecated Bourne shell. Bash can be run on most UNIX-like operating systems, including GNU/Linux.<br />
<br />
== Invocation ==<br />
<br />
Bash behaviour can be altered depending on how it is invoked. Some descriptions of different modes follow.<br />
<br />
If Bash is spawned by {{ic|login}} in a TTY, by an [[SSH]] daemon, or similar means, it is considered a '''login shell'''. This mode can also be engaged using the {{ic|-l}}/{{ic|--login}} command line option.<br />
<br />
Bash is considered an '''interactive shell''' when its standard input and error are connected to a terminal (for example, when run in a terminal emulator), and it is not started with the {{ic|-c}} option or [http://unix.stackexchange.com/a/96805 non-option] arguments (for example, {{ic|bash '''script'''}}). All interactive shells source {{ic|/etc/bash.bashrc}} and {{ic|~/.bashrc}}, while interactive ''login'' shells also source {{ic|/etc/profile}} and {{ic|~/.bash_profile}}.<br />
<br />
{{Note|In Arch {{ic|/bin/sh}} (which used to be the Bourne shell executable) is symlinked to {{ic|/bin/bash}}. If Bash is invoked with the name {{ic|sh}}, it tries to mimic the startup behavior of historical versions of {{ic|sh}}, including POSIX compability.}}<br />
<br />
=== Configuration files ===<br />
<br />
See [http://www.gnu.org/software/bash/manual/bash.html#Bash-Startup-Files 6.2 Bash Startup Files] and [http://mywiki.wooledge.org/DotFiles DotFiles] for a complete description.<br />
<br />
{| class="wikitable"<br />
! File<br />
! Description<br />
! Login shells <sup>(see note)</sup><br />
! Interactive, ''non-login'' shells<br />
|-<br />
| {{ic|/etc/profile}}<br />
| [[Source]]s application settings in {{ic|/etc/profile.d/*.sh}} and {{ic|/etc/bash.bashrc}}.<br />
| {{Yes}}<br />
| {{No}}<br />
|-<br />
| {{ic|~/.bash_profile}}<br />
| Per-user, after {{ic|/etc/profile}}. If this file does not exist, {{ic|~/.bash_login}} and {{ic|~/.profile}} are checked in that order. The skeleton file {{ic|/etc/skel/.bash_profile}} also sources {{ic|~/.bashrc}}.<br />
| {{Yes}}<br />
| {{No}}<br />
|-<br />
| {{ic|~/.bash_logout}}<br />
| After exit of a login shell.<br />
| {{Yes}}<br />
| {{No}}<br />
|-<br />
| {{ic|/etc/bash.bashrc}}<br />
| Depends on the {{ic|1=-DSYS_BASHRC="/etc/bash.bashrc"}} compilation flag. Sources {{ic|/usr/share/bash-completion/bash_completion}}.<br />
| {{No}}<br />
| {{Yes}}<br />
|-<br />
| {{ic|~/.bashrc}}<br />
| Per-user, after {{ic|/etc/bash.bashrc}}.<br />
| {{No}}<br />
| {{Yes}}<br />
|}<br />
<br />
{{Note|<br />
* Login shells can be non-interactive when called with the {{ic|--login}} argument.<br />
* While interactive, ''non-login'' shells do '''not''' source {{ic|~/.bash_profile}}, they still inherit the environment from their parent process (which may be a login shell). See [http://mywiki.wooledge.org/ProcessManagement#On_processes.2C_environments_and_inheritance On processes, environments and inheritance] for details.<br />
}}<br />
<br />
=== Shell and environment variables ===<br />
<br />
The behavior of Bash and programs run by it can be influenced by a number of environment variables. [[Environment variables]] are used to store useful values such as command search directories, or which browser to use. When a new shell or script is launched it inherits its parent's variables, thus starting with an internal set of shell variables[http://www.kingcomputerservices.com/unix_101/understanding_unix_shells_and_environment_variables.htm ].<br />
<br />
These shell variables in Bash can be exported in order to become environment variables:<br />
<br />
VARIABLE=content<br />
export VARIABLE<br />
<br />
or with a shortcut<br />
<br />
export VARIABLE=content<br />
<br />
Environment variables are conventionally placed in {{ic|~/.profile}} or {{ic|/etc/profile}} so that all bourne-compatible shells can use them.<br />
<br />
See [[Environment variables]] for more general information.<br />
<br />
== Command line ==<br />
<br />
Bash command line is managed by the separate library called [[Readline]]. Readline provides [[emacs]] and [[vi]] styles of shortcuts for interacting with the command line, i.e. moving back and forth on the word basis, deleting words etc. It is also Readline's responsibility to manage [[Readline#History|history]] of input commands. Last, but not least, it allows you to create [[Readline#Macros|macros]].<br />
<br />
=== Tab completion ===<br />
<br />
[[Wikipedia:Command-line_completion|Tab completion]] is the option to auto-complete typed commands by pressing {{ic|Tab}} (enabled by default).<br />
<br />
==== Single-tab ====<br />
<br />
It may require up to three tab-presses to show all possible completions for a command. To reduce the needed number of tab-presses, see [[Readline#Faster completion]].<br />
<br />
==== Common programs and options ====<br />
<br />
By default, Bash only tab-completes commands, filenames, and variables. The package {{Pkg|bash-completion}} extends this by adding more specialized tab completions for common commands and their options, which can be enabled by sourcing {{ic|/usr/share/bash-completion/bash_completion}}. With {{Pkg|bash-completion}}, normal completions (such as {{ic|$ ls file.*<tab><tab>}}) will behave differently; however, they can be re-enabled with {{ic|$ compopt -o bashdefault ''program''}} (see [https://bbs.archlinux.org/viewtopic.php?id=128471] and [https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion-Builtins.html] for more detail).<br />
<br />
==== Customize per-command ====<br />
<br />
{{Note|Using the {{ic|complete}} builtin may cause conflicts with {{Pkg|bash-completion}}.}}<br />
<br />
By default Bash only tab-completes file names following a command. You can change it to complete command names using {{ic|complete -c}}:<br />
{{hc|~/.bashrc|<br />
complete -c man which<br />
}}<br />
or complete command names and file names with {{ic|-cf}}:<br />
{{bc|complete -cf sudo}}<br />
See the Bash man page for more completion options.<br />
<br />
=== History ===<br />
<br />
==== History completion ====<br />
<br />
You can bind the up and down arrow keys to search through Bash's history (see: [[Readline#History]] and [https://www.gnu.org/software/bash/manual/html_node/Readline-Init-File-Syntax.html Readline Init File Syntax]):<br />
<br />
{{hc|~/.bashrc|<br />
bind '"\e[A": history-search-backward'<br />
bind '"\e[B": history-search-forward'<br />
}}<br />
<br />
or to affect all readline programs:<br />
<br />
{{hc|~/.inputrc|<br />
"\e[A": history-search-backward<br />
"\e[B": history-search-forward<br />
}}<br />
<br />
==== Shorter history ====<br />
<br />
The {{ic|HISTCONTROL}} variable can prevent certain commands from being logged to the history. For example, to stop logging of repeated identical commands<br />
{{hc|~/.bashrc|2=export HISTCONTROL=ignoredups}}<br />
or set it to {{ic|erasedups}} to ensure that Bash's history will only contain one copy of each command (regardless of order). See the Bash man page for more options.<br />
<br />
=== Mimic Zsh run-help ability ===<br />
<br />
Zsh can invoke the manual for the command preceding the cursor by pressing {{ic|Alt+h}}.<br />
A similar behaviour is obtained in Bash using this [[Readline]] bind:<br />
{{hc|~/.bashrc|<br />
bind '"\eh": "\C-a\eb\ed\C-y\e#man \C-y\C-m\C-p\C-p\C-a\C-d\C-e"'<br />
}}<br />
This assumes are you using the (default) Emacs [[Readline#Editing mode|editing mode]].<br />
<br />
=== Additional completion keybindings ===<br />
<br />
==== Variable expansion ====<br />
Variable name can be completed with {{Ic|tab}} key. However, expanding variable to its value is done with {{Ic|C-M-e}} key combination.<br />
<br />
==== Wildcard expansion ====<br />
Wildcard {{Ic|*}} can be expanded using {{Ic|C-x *}}, i.e. pressing {{Ic|Control+x}} then pressing {{Ic|*}}.<br />
<br />
== Aliases ==<br />
<br />
[[Wikipedia:Alias_(command)|alias]] is a command, which enables a replacement of a word with another string. It is often used for abbreviating a system command, or for adding default arguments to a regularly used command. <br />
<br />
Personal aliases are preferably stored in {{ic|~/.bashrc}}, and system-wide aliases (which affect all users) belong in {{ic|/etc/bash.bashrc}}. See [https://gist.github.com/anonymous/a9055e30f97bd19645c2] for example aliases.<br />
<br />
For functions, see [[Bash/Functions]].<br />
<br />
== Tips and tricks ==<br />
<br />
=== Prompt customization ===<br />
<br />
See [[Bash/Prompt customization]].<br />
<br />
=== Command not found ===<br />
<br />
[[pkgfile]] includes a "command not found" hook that will automatically search the official repositories, when entering an unrecognized command.<br />
<br />
You need to [[source]] the hook to enable it, for example:<br />
<br />
{{hc|~/.bashrc|<br />
source /usr/share/doc/pkgfile/command-not-found.bash}}<br />
<br />
Then attempting to run an unavailable command will show the following info:<br />
<br />
{{hc|$ abiword|<br />
abiword may be found in the following packages:<br />
extra/abiword 3.0.1-2 /usr/bin/abiword<br />
}}<br />
<br />
An alternative "command not found" hook is provided by {{AUR|command-not-found}}, which looks like this:<br />
<br />
{{hc|$ abiword|<br />
The command 'abiword' is provided by the following packages:<br />
'''abiword''' (2.8.6-7) from extra<br />
[ abiword ]<br />
'''abiword''' (2.8.6-7) from staging<br />
[ abiword ]<br />
'''abiword''' (2.8.6-7) from testing<br />
[ abiword ]<br />
}}<br />
<br />
=== Disable Ctrl+z in terminal ===<br />
<br />
You can disable the {{ic|Ctrl+z}} feature (pauses/closes your application) by wrapping your command like this:<br />
<br />
#!/bin/bash<br />
trap "" 20<br />
''adom''<br />
<br />
Now when you accidentally press {{ic|Ctrl+z}} in {{AUR|adom}} instead of {{ic|Shift+z}} nothing will happen because {{ic|Ctrl+z}} will be ignored.<br />
<br />
=== Clear the screen after logging out ===<br />
<br />
To clear the screen after logging out on a virtual terminal:<br />
{{hc|~/.bash_logout|<br />
clear<br />
reset<br />
}}<br />
<br />
=== Auto "cd" when entering just a path ===<br />
<br />
Bash can automatically prepend {{ic|cd }} when entering just a path in the shell. For example:<br />
{{hc|$ /etc|<br />
bash: /etc: Is a directory<br />
}}<br />
<br />
But after adding one line into {{ic|.bashrc}} file:<br />
{{hc|~/.bashrc|<br />
...<br />
shopt -s autocd<br />
...<br />
}}<br />
<br />
You get:<br />
[user@host ~]$ /etc<br />
cd /etc<br />
[user@host etc]$<br />
<br />
=== Autojump ===<br />
<br />
{{Pkg|autojump}} allows navigating the file system by searching for strings in a database with the user's most-visited paths.<br />
<br />
After installation, {{ic|/etc/profile.d/autojump.bash}} must be [[source]]d in order to start using the application.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Line wrap on window resize ===<br />
<br />
When resizing a [[terminal emulator]], Bash may not receive the resize signal. This will cause typed text to not wrap correctly and overlap the prompt. The {{ic|checkwinsize}} shell option checks the window size after each command and, if necessary, updates the values of {{ic|LINES}} and {{ic|COLUMNS}}.<br />
<br />
{{hc|~/.bashrc|<br />
shopt -s checkwinsize<br />
}}<br />
<br />
=== Shell exits even if ignoreeof set ===<br />
<br />
If you have set the {{ic|ignoreeof}} option and you find that repeatedly hitting {{ic|ctrl-d}} causes the shell to exit, it is because this option only allows 10 consecutive invocations of this keybinding (or 10 consecutive EOF characters, to be precise), before exiting the shell.<br />
<br />
To allow higher values, you have to use the IGNOREEOF variable.<br />
<br />
For example:<br />
export IGNOREEOF=100<br />
<br />
== See also ==<br />
<br />
* [https://www.gnu.org/software/bash/manual/bashref.html Bash Reference Manual], or {{ic|/usr/share/doc/bash/bashref.html}}<br />
* [https://www.gnu.org/software/bash/manual/html_node/Readline-Init-File-Syntax.html Readline Init File Syntax]<br />
* [http://www.aosabook.org/en/bash.html The Bourne-Again Shell] - The third chapter of ''The Architecture of Open Source Applications''<br />
* [http://shellcheck.net Shellcheck] - Check bash scripts for common errors<br />
<br />
=== Tutorials ===<br />
<br />
* [http://mywiki.wooledge.org/BashGuide BashGuide on Greg's Wiki]<br />
* [http://mywiki.wooledge.org/BashFAQ BashFAQ on Greg's Wiki]<br />
* [http://wiki.bash-hackers.org/doku.php Bash Hackers Wiki]<br />
* [http://wiki.bash-hackers.org/scripting/tutoriallist Bash Hackers: List of Bash online-tutorials]<br />
* [http://www.grymoire.com/Unix/Quote.html Quote Tutorial]<br />
<br />
=== Community ===<br />
<br />
* [irc://irc.freenode.net#bash An active and friendly IRC channel for Bash]<br />
* [http://bashscripts.org Bashscripts.org]<br />
<br />
=== Examples ===<br />
<br />
* [http://tldp.org/HOWTO/Xterm-Title-4.html How to change the title of an xterm]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=WeeChat&diff=482475WeeChat2017-07-21T09:26:04Z<p>Alive4ever: /* Desktop notifications */ Add trigger.trigger.beep.command as a way to trigger desktop notification</p>
<hr />
<div>[[Category:Internet Relay Chat]]<br />
[[ja:WeeChat]]<br />
{{Style|See [[Help:Style]] and related.}}<br />
<br />
{{Related articles start}}<br />
{{Related|IRC channels}}<br />
{{Related|IRC}}<br />
{{Related|irssi}}<br />
{{Related|HexChat}}<br />
{{Related articles end}}<br />
'''WeeChat''' is a highly extendable and feature rich [[wikipedia:Internet Relay Chat|IRC]] Client currently under heavy development.<br />
<br />
== Installing ==<br />
<br />
[[Install]] the {{Pkg|weechat}} package, or {{AUR|weechat-git}} for the development version.<br />
<br />
== Running WeeChat==<br />
<br />
WeeChat is going to have multiple interfaces at some point, run '''weechat-[interface]''' to start WeeChat. <br />
<br />
As WeeChat currently only has an Ncurses interface. The command to start WeeChat is:<br />
<br />
$ weechat<br />
<br />
== Configuration ==<br />
<br />
You can configure WeeChat in 3 ways: using WeeChat's internal commands; using '''iset'''; or by editing the .conf files directly. WeeChat will automatically save settings on exit or when you run {{ic|/save}}, so if you are editing a .conf file in an editor, be sure to run {{ic|/reload}} from the console before exiting, otherwise your changes will be lost.<br />
<br />
=== Internal commands ===<br />
<br />
The {{ic|/set}} command follows this structure:<br />
{{ic|/set [file.name].[section].[directive]}}<br />
<br />
You can get a list of all configurable options by typing {{ic|/set}} in the '''weechat''' buffer window. Since there are nearly 600 default configurable options, you can search through them with a wildcard syntax: {{ic|/set irc.server.*}} or {{ic|/set *server*}} as an example. You can get help on each option with the {{ic|/help}} command: <br />
<br />
/help irc.server.freenode.autoconnect<br />
<br />
=== Internal menu-based ===<br />
<br />
For a more convenient method, install the '''iset''' script. If you have weechat 0.3.9 or newer, run:<br />
<br />
/script install iset.pl<br />
<br />
In older versions, use {{ic|/weeget install iset}}, or download [https://www.weechat.org/scripts/source/stable/iset.pl.html/ iset.pl] into your {{ic|~/.weechat/perl/autoload}} directory manually.<br />
<br />
Afterwards, run<br />
<br />
/iset<br />
<br />
to get a buffer with all configuration options.<br />
<br />
=== Configuration Files ===<br />
<br />
The .conf files for WeeChat are saved to {{ic|~/.weechat}}. These files are not commented. Detailed information can be found within the program itself (see '''Internally''' above), or WeeChat's [https://www.weechat.org/files/doc/stable/weechat_user.en.html user guide].<br />
<br />
{{Tip|in case you want to move {{ic|.weechat}} directory somewhere else (like in your '''$XDG_CONFIG_HOME'''), use this option: {{ic|$weechat -d $XDG_CONFIG_HOME/weechat}} or set the environment variable {{ic|WEECHAT_HOME}}.}}<br />
<br />
== Connecting to a server ==<br />
<br />
{{Note| Using '''/connect''' to connect to a temporary server is disabled by default if you're using 1.1+ [https://weechat.org/files/releasenotes/ReleaseNotes-devel.html#_temporary_servers_disabled_by_default_with_connect Release Note]<br />
<br />
Enable by '''/set irc.look.temporary_servers on'''<br />
<br />
}}<br />
<br />
You can connect to a IRC server by using '''/connect'''.<br />
<br />
/connect chat.freenode.net<br />
<br />
Or if there is already a '''Server''' setup you can use:<br />
<br />
/connect freenode<br />
<br />
== Creating a Server profile ==<br />
<br />
If you plan on connecting to a server more than once it may be beneficial to create a '''Server'''.<br />
<br />
/server add example irc.example.net/6667<br />
<br />
Would create the server '''example''' which would connect to '''irc.example.net''' on port '''6667'''<br />
<br />
See the WeeChat documentation and '''/help server''' for more information.<br />
<br />
== Configuring SSL ==<br />
<br />
Many IRC servers, including [https://freenode.net/ freenode] where [[IRC channel|#archlinux]] is, support SSL.<br />
<br />
If you're making a server with '''/server''', add the SSL port (usually 6697) and '''-ssl''' to the end of the line. For example:<br />
<br />
/server add freenode chat.freenode.net/6697 -ssl<br />
<br />
You can do the same thing if using '''/connect'''.<br />
<br />
/connect chat.freenode.net/6697 -ssl<br />
<br />
{{Warning|Some servers need the '''ssl_dhkey_size''' value changed to something lower. For example, if you're using freenode you'll need to set '''/set irc.server.freenode.ssl_dhkey_size 1024''' or '''/set irc.server.chat.freenode.net.ssl_dhkey_size 1024''' (see the server log)}}<br />
<br />
{{Note|Different servers may have a different port than 6697 - this is server specific.}}<br />
<br />
You may also want to change the location where WeeChat looks for trusted authorities (the default value is {{ic|%h/ssl/CAs.pem}} which translates to {{ic|~/.weechat/ssl/CAs.pem)}}:<br />
<br />
/set weechat.network.gnutls_ca_file "/etc/ssl/certs/ca-certificates.crt"<br />
<br />
== Tips and Tricks ==<br />
<br />
=== Upgrading ===<br />
<br />
WeeChat can be upgraded without disconnecting from the IRC servers (non-SSL connections only):<br />
<br />
/upgrade<br />
<br />
This will load the new WeeChat binary and reload the current configuration.<br />
<br />
=== Aliases ===<br />
<br />
Aliases can be created to simplify commonly executed commands. A nice example is Wraithan's '''smart filter''' alias:<br />
<br />
'''Smart Filter'''<br />
<br />
First, we need to enable smart filters:<br />
<br />
/set irc.look.smart_filter "on"<br />
<br />
Next, we will create the '''sfilter''' alias:<br />
<br />
/alias add sfilter filter add irc_smart_$server_$channel irc.$server.$channel irc_smart_filter *<br />
<br />
We can now type<br />
<br />
/sfilter<br />
<br />
in any buffer, and the smart filter will only be enabled for that buffer.<br />
<br />
The following alias will remove a previously enabled smart filter in the current buffer. Add the alias:<br />
<br />
/alias add rmsfilter filter del irc_smart_$server_$channel<br />
<br />
and execute it by<br />
<br />
/rmsfilter<br />
<br />
=== Exec command ===<br />
A new plugin called "exec" has been added, with command {{ic|/exec}}. It will execute external command and can display output to the current buffer with the '''-o''' option or locally (default).<br />
<br />
=== Key Bindings ===<br />
<br />
Some helpful bindings:<br />
<br />
To use ctrl-left/right arrow keys to jump to next/previous words on the input line:<br />
<br />
/key bind meta2-1;5D /input move_previous_word<br />
/key bind meta2-1;5C /input move_next_word<br />
<br />
=== SSH connection lost when idle ===<br />
<br />
If you're connecting to your WeeChat through a remote shell using SSH, for example running it in [[screen]] or [[tmux]] you might experience getting disconnected after a while when idle. There are multiple factors in play why this might happen, but the easiest way to change this is to force the connection to be kept alive by appending this to your SSH-configuration on the remote shell.<br />
<br />
This has nothing to do with WeeChat itself, but losing connection when idle won't happen with it's alternative [[irssi]] by default, and thus is a common situation for those converting to WeeChat. <br />
<br />
{{hc|# /etc/ssh/sshd_config|2=<br />
ClientAliveInterval 300}}<br />
<br />
Or have a look at [https://mosh.org Mosh].<br />
<br />
=== OTR ===<br />
<br />
Install {{AUR|python2-potr}} and enable the script '''otr.py'''. Then:<br />
<br />
/query <nick><br />
/otr start<br />
<br />
Get help on the plugin with:<br />
<br />
/help otr<br />
<br />
=== Slack ===<br />
<br />
[https://slack.com/ Slack] is a platform for team communication; an IRC on steroids. Thanks to its open API, it is possible to connect to your slack team using weechat.<br />
<br />
==== IRC gateway ====<br />
<br />
Once weechat is running, all you have to is add a new server this way:<br />
<br />
{{ic|<nowiki>/server add NAME HOST/6667 -autoconnect -ssl -ssl_dhkey_size=512 -password=PASSWORD -username=USERNAME -nicks=NICK</nowiki>}}<br />
<br />
where:<br />
<br />
* '''NAME''' is the name you want to give to the server<br />
* '''HOST''' is the the Host as provided on the Gateways page of your slack team<br />
* '''PASSWORD''' is the Pass as provided on the Gateways page of your slack team<br />
* '''USERNAME''' is the User as provided on the Gateways page of your slack team<br />
* '''NICK''' is your Slack username.<br />
<br />
===== Upload file =====<br />
<br />
To upload a file, run this following command from your shell :<br />
<br />
{{ic|<nowiki>curl -F file=@/path/to/file -F channels=CHAN -F token=XXX https://slack.com/api/files.upload</nowiki>}}<br />
<br />
where:<br />
<br />
* '''CHAN''' is the channel ID as provided on the Gateways page of your slack team<br />
* '''XXX''' is the team token as provided on the Gateways page of your slack team<br />
<br />
==== Native client ====<br />
<br />
There is a native client for slack: [https://github.com/rawdigits/wee-slack wee-slack]<br />
<br />
You need to install the python2 librairy websocket-client:<br />
<br />
{{ic|<nowiki>pacman -S python2-websocket-client</nowiki>}}<br />
<br />
Then install the wee-chat plugin into the weechat configuration folder<br />
<br />
{{ic|<nowiki>curl -o ~/.weechat/python/autoload/wee_slack.py https://raw.githubusercontent.com/rawdigits/wee-slack/master/wee_slack.py</nowiki>}}<br />
<br />
Run {{ic|<nowiki>/python reload</nowiki>}} to load the new plugin<br />
<br />
You will need an access token. You can grab one at [https://api.slack.com/docs/oauth-test-tokens here]<br />
<br />
Once weechat is running, register your token into weechat:<br />
<br />
{{ic|<nowiki>/set plugins.var.python.slack_extension.slack_api_token [YOUR_SLACK_TOKEN]</nowiki>}}<br />
<br />
And finally:<br />
<br />
{{ic|<nowiki>/save</nowiki>}}<br />
<br />
{{ic|<nowiki>/python reload</nowiki>}}<br />
<br />
===== Upload file =====<br />
<br />
To upload a file enter the following command into weechat:<br />
<br />
{{ic|<nowiki>/slack upload [file_path]</nowiki>}}<br />
<br />
=== Desktop notifications ===<br />
<br />
To receive desktop notifications for mentions or private messages, the [https://github.com/s3rvac/weechat-notify-send weechat-notify-send] script by Petr Zemek can be used.<br />
<br />
To install, use:<br />
<br />
cd ~/.weechat/python<br />
curl -O <nowiki>https://raw.githubusercontent.com/s3rvac/weechat-notify-send/master/notify_send.py</nowiki><br />
ln -s ../notify_send.py autoload/<br />
<br />
The script uses {{Pkg|libnotify}} and is known to work with both KDE and Gnome.<br />
<br />
Another alternative with the built-in {{Ic|trigger}} plugin is to set a value for {{Ic|trigger.trigger.beep.command}}.<br />
<br />
/set trigger.trigger.beep.command "/print -beep;/exec -bg notify-send -i '/usr/share/icons/hicolor/32x32/apps/weechat.png' 'IRC Notification' "${tg_tag_nick}: ${tg_message_nocolor}""<br />
<br />
=== Mobile device notifications ===<br />
<br />
To receive notifications for mentions or private messages to an Android mobile device, you can use the [https://irssinotifier.appspot.com/ IrssiNotifier] port to WeeChat from [https://www.weechat.org/files/scripts/irssinotifier.py here]. This script requires a Google Account, and a registration step with the service provider to obtain an API key. Then, install the plugin<br />
<br />
cd ~/.weechat/python<br />
curl -O <nowiki>https://www.weechat.org/files/scripts/irssinotifier.py</nowiki><br />
ln -s ../irssinotifier.py autoload/<br />
<br />
and intialize the API token and end-to-end encryption password in WeeChat<br />
<br />
/set plugins.var.python.irssinotifier.api_token your-api-token-from-website<br />
/set plugins.var.python.irssinotifier.encryption_password your-password-same-as-in-andoid-app<br />
/save<br />
<br />
An alternative that does not require a Google Account is a Ruby script for [https://www.notifymyandroid.com NotifyMyAndroid.com] from [https://github.com/jamtur01/nma-weechat here], with a similar installation procedure to the above, but into {{ic|~/.weechat/ruby}}.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Errors loading plugins ===<br />
<br />
You may see output like the following in the main window after starting '''weechat''':<br />
<br />
{{bc|<nowiki>13:26:10 =!= | Error: unable to load plugin "/usr/lib/weechat/plugins/ruby.so": libruby.so.2.4: cannot open shared object file: No such file or directory<br />
13:26:10 =!= | If you're trying to load a script and not a C plugin, try command to load scripts (/perl, /python, ...)<br />
13:26:10 =!= | Error: unable to load plugin "/usr/lib/weechat/plugins/lua.so": liblua.so.5.3: cannot open shared object file: No such file or directory<br />
13:26:10 =!= | If you're trying to load a script and not a C plugin, try command to load scripts (/perl, /python, ...)<br />
13:26:10 =!= | Error: unable to load plugin "/usr/lib/weechat/plugins/aspell.so": libaspell.so.15: cannot open shared object file: No such file or directory<br />
13:26:10 =!= | If you're trying to load a script and not a C plugin, try command to load scripts (/perl, /python, ...)<br />
13:26:10 =!= | Error: unable to load plugin "/usr/lib/weechat/plugins/tcl.so": libtcl8.6.so: cannot open shared object file: No such file or directory<br />
13:26:10 =!= | If you're trying to load a script and not a C plugin, try command to load scripts (/perl, /python, ...)</nowiki>|bc}}<br />
<br />
The default configuration for weechat attempts to load all plugins found in /usr/lib/weechat/plugins which in this case includes ruby, lua, aspell and tcl. These packages are not required by the weechat package and may not be installed on your machine. There are two options if these errors bother you:<br />
<br />
# [[Packages|Install]] [https://www.archlinux.org/packages/?name=ruby ruby], [https://www.archlinux.org/packages/?name=lua lua], [https://www.archlinux.org/packages/?name=aspell aspell] and/or [https://www.archlinux.org/packages/?name=tcl tcl] from the [[official repositories]].<br />
# Or, run {{ic|/set weechat.plugin.autoload "*,!ruby,!lua,!aspell,!tcl"}} which will prevent loading those plugins with a bang (!) prefix.<br />
<br />
== Getting Help ==<br />
<br />
To access WeeChat's built-in help, simply type<br />
<br />
/help<br />
<br />
and the help will be displayed in the main buffer (usually buffer 1).<br />
<br />
== See also ==<br />
<br />
* [https://www.weechat.org Home Page]<br />
* [https://www.weechat.org/doc/ WeeChat Documentation]<br />
* [https://www.weechat.org/scripts/ WeeChat Scripts]<br />
* [https://weechat.org/blog/ WeeChat Development Blog]<br />
<br />
=== Guides ===<br />
* [https://weechat.org/files/doc/stable/weechat_quickstart.en.html Official WeeChat quick start guide] - a good place to start<br />
* [https://guides.fixato.org/weechat FiXato's guide to WeeChat] - A Weechat Contributers Guide<br />
* [https://gist.github.com/pascalpoitras/8406501 My always up-to-date WeeChat configuration] - r3m (weechat-dev) <br />
* [https://robots.thoughtbot.com/weechat-for-slacks-irc-gateway Thoughtbot article on weechat and slack]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=GnuPG&diff=479705GnuPG2017-06-12T18:22:09Z<p>Alive4ever: /* SSH agent */ Add note to about gpg-agent-ssh.socket systemd user unit</p>
<hr />
<div>[[Category:Encryption]]<br />
[[es:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[zh-hans:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Disk encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related articles end}}<br />
<br />
According to the [http://www.gnupg.org official website]:<br />
<br />
:GnuPG is a complete and free implementation of the [http://openpgp.org/about/ OpenPGP] standard as defined by [https://tools.ietf.org/html/rfc4880 RFC4880] (also known as PGP). GnuPG allows you to encrypt and sign your data and communication. It features a versatile key management system as well as access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. Version 2 of GnuPG also provides support for S/MIME and Secure Shell (ssh).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|gnupg}} package.<br />
<br />
This will also install {{Pkg|pinentry}}, a collection of simple PIN or passphrase entry dialogs which GnuPG uses for passphrase entry. Which ''pinentry'' dialog is used is determined by the symbolic link {{ic|/usr/bin/pinentry}}, which by default points to {{ic|/usr/bin/pinentry-gtk-2}}.<br />
<br />
If you want to use a graphical frontend or program that integrates with GnuPG, see [[List of applications/Security#Encryption, signing, steganography]].<br />
<br />
== Configuration ==<br />
<br />
=== Directory location ===<br />
{{ic|$GNUPGHOME}} is used by GnuPG to point to the directory where its configuration files are stored. By default {{ic|$GNUPGHOME}} is not set and your {{ic|$HOME}} is used instead; thus, you will find a {{ic|~/.gnupg}} directory right after installation. <br />
<br />
To change the default location, either run gpg this way {{ic|$ gpg --homedir ''path/to/file''}} or set {{ic|GNUPGHOME}} in one of your regular [[startup files]].<br />
<br />
=== Configuration files ===<br />
<br />
The default configuration files are {{ic|~/.gnupg/gpg.conf}} and {{ic|~/.gnupg/dirmngr.conf}}. <br />
<br />
By default, the gnupg directory has its [[permissions]] set to {{ic|700}} and the files it contains have their permissions set to {{ic|600}}. Only the owner of the directory has permission to read, write, and access the files. This is for security purposes and should not be changed. In case this directory or any file inside it does not follow this security measure, you will get warnings about unsafe file and home directory permissions.<br />
<br />
Append to these files any long options you want. Do not write the two dashes, but simply the name of the option and required arguments. You will find skeleton files in {{ic|/usr/share/gnupg}}. These files are copied to {{ic|~/.gnupg}} the first time gpg is run if they do not exist there. Other examples are found in [[#See also]].<br />
<br />
Additionally, [[pacman]] uses a different set of configuration files for package signature verification. See [[Pacman/Package signing]] for details.<br />
<br />
=== Default options for new users ===<br />
<br />
If you want to setup some default options for new users, put configuration files in {{ic|/etc/skel/.gnupg/}}. When the new user is added in system, files from here will be copied to its GnuPG home directory. There is also a simple script called ''addgnupghome'' which you can use to create new GnuPG home directories for existing users:<br />
<br />
# addgnupghome user1 user2<br />
<br />
This will add the respective {{ic|/home/user1/.gnupg}} and {{ic|/home/user2/.gnupg}} and copy the files from the skeleton directory to it. Users with existing GnuPG home directory are simply skipped.<br />
<br />
== Usage ==<br />
<br />
{{Note|Whenever a ''{{ic|user-id}}'' is required in a command, it can be specified with your key ID, fingerprint, a part of your name or email address, etc. GnuPG is flexible on this.<br />
}}<br />
<br />
=== Create key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
{{Tip|Use the {{ic|--expert}} option for getting alternative ciphers like [[wikipedia:Elliptic_curve_cryptography|ECC]].}}<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* the RSA (sign only) and a RSA (encrypt only) key.<br />
* a keysize of the default value (2048). A larger keysize of 4096 "gives us almost nothing, while costing us quite a lot"[https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096].<br />
* an expiration date. A period of a year is good enough for the average user. This way even if access is lost to the keyring, it will allow others to know that it is no longer valid. Later, if necessary, the expiration date can be extended without having to re-issue a new key.<br />
* your name and email address. You can add multiple identities to the same key later (''e.g.'', if you have multiple email addresses you want to associate with this key).<br />
* ''no'' optional comment. Since the semantics of the comment field are [https://lists.gnupg.org/pipermail/gnupg-devel/2015-July/030150.html not well-defined], it has limited value for identification.<br />
* [[Security#Choosing_secure_passwords|a secure passphrase]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
gpg's main usage is to ensure confidentiality of exchanged messages via public-key cryptography. With it each user distributes the public key of their keyring, which can be be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[w:Public-key cryptography]] for examples about the message exchange. <br />
<br />
So, in order for others to send encrypted messages to you, they need your public key. <br />
<br />
To generate an ASCII version of your public key (''e.g.'' to distribute it by e-mail):<br />
<br />
$ gpg --output ''public.key'' --armor --export ''user-id'' <br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public.key''}} to your public key ring:<br />
<br />
$ gpg --import ''public.key''<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
=== Use a keyserver ===<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve your key without having to contact you directly:<br />
<br />
$ gpg --send-keys ''user-id''<br />
<br />
To find out details of a key on the keyserver, without importing it, do:<br />
<br />
$ gpg --search-keys ''user-id''<br />
<br />
To import a key from a key server:<br />
<br />
$ gpg --recv-keys ''key-id''<br />
<br />
{{Warning|<br />
* You should verify the authenticity of the retrieved public key by comparing its fingerprint with one that the owner published on an independent source(s) (i.e., contacting the person directly). See [[Wikipedia:Public key fingerprint]] for more information.<br />
* Using a short ID may encounter collisions. All keys will be imported that have the short ID. To avoid this, use the full fingerprint or long key ID when receiving a key.[https://lkml.org/lkml/2016/8/15/445]}}<br />
<br />
{{Tip|<br />
* Adding {{ic|keyserver-options auto-key-retrieve}} to {{ic|gpg.conf}} will automatically fetch keys from the key server as needed. <br />
* An alternative key server is {{ic|pool.sks-keyservers.net}} and can be specified with {{ic|keyserver}} in {{ic|dirmngr.conf}}; see also [[wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
* If your network blocks ports used for hkp/hkps, you may need to specify port 80, i.e. {{ic|pool.sks-keyservers.net:80}}<br />
* You can connect to the keyserver over [[Tor]] using {{ic|--use-tor}}. See this [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html GnuPG blog post] for more information.<br />
* You can connect to a keyserver using a proxy by setting the {{ic|http_proxy}} environment variable and setting {{ic|honor-http-proxy}} in {{ic|dirmngr.conf}}. Alternatively, set {{ic|http-proxy ''host[:port]''}} in {{ic|dirmngr.conf}}, overriding the {{ic|http_proxy}} environment variable.<br />
* If you wish to import a key ID to install a specific Arch Linux package, see [[pacman/Package signing#Managing the keyring]] and [[Makepkg#Signature checking]].}}<br />
<br />
=== Encrypt and decrypt ===<br />
<br />
==== Asymmetric ====<br />
You need to [[#Import a public key]] of a user before encrypting (options {{ic|--encrypt}} or {{ic|-e}}) a file or message to that recipient (options {{ic|--recipient}} or {{ic|-r}}). Additionally you need to [[#Create key pair]] if you have not already done so.<br />
<br />
To encrypt a file with the name ''doc'', use:<br />
<br />
$ gpg --recipient ''user-id'' --encrypt ''doc''<br />
<br />
To decrypt (option {{ic|--decrypt}} or {{ic|-d}}) a file with the name ''doc''.gpg encrypted with your public key, use:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
''gpg'' will prompt you for your passphrase and then decrypt and write the data from ''doc''.gpg to ''doc''. If you omit the {{ic|-o}} ({{ic|--output}}) option, ''gpg'' will write the decrypted data to stdout.<br />
<br />
{{Tip|<br />
* Add {{ic|--armor}} to encrypt a file using ASCII armor (suitable for copying and pasting a message in text format)<br />
* Use {{ic|-R ''user-id''}} or {{ic|--hidden-recipient ''user-id''}} instead of {{ic|-r}} to not put the recipient key IDs in the encrypted message. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis.<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can use gnupg to encrypt your sensitive documents by using your own user-id as recipient or by using the {{ic|--default-recipient-self}} flag instead; however, you can only do this one file at a time, although you can always tarball various files and then encrypt the tarball. See also [[Disk encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
==== Symmetric ====<br />
Symmetric encryption does not require the generation of a key pair and can be used to simply encrypt data with a passphrase. Simply use {{ic|--symmetric}} or {{ic|-c}} to perform symmetic encryption:<br />
<br />
$ gpg -c ''doc''<br />
<br />
The following example:<br />
<br />
* Encrypts {{ic|''doc''}} with a symmetric cipher using a passphrase<br />
* Uses the AES-256 cipher algorithm to encrypt the passphrase<br />
* Uses the SHA-512 digest algorithm to mangle the passphrase<br />
* Mangles the passphrase for 65536 iterations<br />
<br />
$ gpg -c --s2k-cipher-algo AES256 --s2k-digest-algo SHA512 --s2k-count 65536 ''doc''<br />
<br />
To decrypt a symmetrically encrypted {{ic|''doc''.gpg}} using a passphrase and output decrypted contents into the same directory as {{ic|''doc''}} do:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor ''<user-id>'' > ''privkey.asc''<br />
<br />
Note that ''gpg'' release 2.1 changed default behaviour so that the above command enforces a passphrase protection, even if you deliberately chose not to use one on key creation. This is because otherwise anyone who gains access to the above exported file would be able to encrypt and sign documents as if they were you ''without'' needing to know your passphrase. <br />
<br />
{{Warning|The passphrase is usually the weakest link in protecting your secret key. Place the private key in a safe place on a different system/device, such as a locked container or encrypted drive. It is the only safety you have to regain control to your keyring in case of, for example, a drive failure, theft or worse.}}<br />
<br />
To import the backup of your private key:<br />
$ gpg --import ''privkey.asc''<br />
<br />
=== Edit your key ===<br />
<br />
Running the {{ic|gpg --edit-key ''<user-id>''}} command will present a menu which enables you to do most of your key management related tasks.<br />
<br />
Some useful commands in the edit key sub menu:<br />
> passwd # change the passphrase<br />
> clean # compact any user ID that is no longer usable (e.g revoked or expired)<br />
> revkey # revoke a key<br />
> addkey # add a subkey to this key<br />
> expire # change the key expiration time<br />
<br />
Type {{ic|help}} in the edit key sub menu for more commands.<br />
<br />
{{Tip|If you have multiple email accounts you can add each one of them as an identity, using {{ic|adduid}} command. You can then set your favourite one as {{ic|primary}}.}}<br />
<br />
=== Exporting subkey ===<br />
<br />
If you plan to use the same key across multiple devices, you may want to strip out your master key and only keep the bare minimum encryption subkey on less secure systems.<br />
<br />
First, find out which subkey you want to export.<br />
<br />
$ gpg -K<br />
<br />
Select only that subkey to export.<br />
<br />
$ gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.gpg<br />
<br />
{{Warning|If you forget to add the !, all of your subkeys will be exported.}}<br />
<br />
At this point you could stop, but it is most likely a good idea to change the passphrase as well. Import the key into a temporary folder. <br />
<br />
$ gpg --homedir /tmp/gpg --import /tmp/subkey.gpg<br />
$ gpg --homedir /tmp/gpg --edit-key ''<user-id>''<br />
> passwd<br />
> save<br />
$ gpg --homedir /tmp/gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.altpass.gpg<br />
<br />
{{Note|You will get a warning that the master key was not available and the password was not changed, but that can safely be ignored as the subkey password was.}}<br />
<br />
At this point, you can now use {{ic|/tmp/subkey.altpass.gpg}} on your other devices.<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
If you have set your subkeys to expire after a set time, you can create new ones. Do this a few weeks in advance to allow others to update their keyring.<br />
<br />
{{Note|You do not need to create a new key simply because it is expired. You can extend the expiration date.}}<br />
<br />
Create new subkey (repeat for both signing and encrypting key)<br />
<br />
$ gpg --edit-key ''<user-id>''<br />
> addkey<br />
<br />
And answer the following questions it asks (see [[#Create key pair]] for suggested settings).<br />
<br />
Save changes<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver pgp.mit.edu --send-keys ''<user-id>''<br />
<br />
{{Note|Revoking expired subkeys is unnecessary and arguably bad form. If you are constantly revoking keys, it may cause others to lack confidence in you.}}<br />
<br />
== Signatures ==<br />
<br />
Signatures certify and timestamp documents. If the document is modified, verification of the signature will fail. Unlike encryption which uses public keys to encrypt a document, signatures are created with the user's private key. The recipient of a signed document then verifies the signature using the sender's public key.<br />
<br />
=== Create a signature ===<br />
<br />
==== Sign a file ====<br />
<br />
To sign a file use the {{ic|--sign}} or {{ic|-s}} flag:<br />
<br />
$ gpg --output ''doc''.sig --sign ''doc''<br />
<br />
{{ic|''doc''.sig}} contains both the compressed content of the original file {{ic|''doc''}} and the signature in a binary format, but the file is not encrypted. However, you can combine signing with [[#Encrypt and decrypt|encrypting]].<br />
<br />
==== Clearsign a file or message ====<br />
<br />
To sign a file without compressing it into binary format use:<br />
<br />
$ gpg --output ''doc''.sig --clearsign ''doc''<br />
<br />
Here both the content of the original file {{ic|''doc''}} and the signature are stored in human-readable form in {{ic|''doc''.sig}}.<br />
<br />
==== Make a detached signature ====<br />
<br />
To create a separate signature file to be distributed separately from the document or file itself, use the {{ic|--detach-sig}} flag:<br />
<br />
$ gpg --output ''doc''.sig --detach-sig ''doc''<br />
<br />
Here the signature is stored in {{ic|''doc''.sig}}, but the contents of {{ic|''doc''}} are not stored in it. This method is often used in distributing software projects to allow users to verify that the program has not been modified by a third party.<br />
<br />
=== Verify a signature ===<br />
<br />
To verify a signature use the {{ic|--verify}} flag:<br />
<br />
$ gpg --verify ''doc''.sig<br />
<br />
where {{ic|''doc''.sig}} is the signed file containing the signature you wish to verify.<br />
<br />
If you are verifying a detached signature, both the signed data file and the signature file must be present when verifying. For example, to verify Arch Linux's latest iso you would do:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig<br />
<br />
where {{ic|archlinux-''version''.iso}} must be located in the same directory.<br />
<br />
You can also specify the signed data file with a second argument:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig ''/path/to/''archlinux-''version''.iso<br />
<br />
If a file as been encrypted in addition to being signed, simply [[#Encrypt and decrypt|decrypt]] the file and its signature will also be verified.<br />
<br />
== gpg-agent ==<br />
<br />
''gpg-agent'' is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client.<br />
<br />
Starting with GnuPG 2.1.0 the use of ''gpg-agent'' is required. ''gpg-agent'' is started on-demand by the GnuPG tools, so there is usually no reason to start it manually.<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{ic|man gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|To cache your passphrase for the whole session, please run the following command:<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXXX<br />
<br />
where XXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. Passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
}}<br />
<br />
=== Reload the agent ===<br />
<br />
After changing the configuration, reload the agent using ''gpg-connect-agent'':<br />
<br />
$ gpg-connect-agent reloadagent /bye<br />
<br />
The command should print {{ic|OK}}.<br />
<br />
=== pinentry ===<br />
<br />
Finally, the agent needs to know how to ask the user for the password. This can be set in the gpg-agent configuration file.<br />
<br />
The default uses a gtk dialog. There are other options - see {{ic|info pinentry}}. To change the dialog implementation set {{ic|pinentry-program}} configuration option:<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
<br />
# PIN entry program<br />
# pinentry-program /usr/bin/pinentry-curses<br />
# pinentry-program /usr/bin/pinentry-qt<br />
# pinentry-program /usr/bin/pinentry-kwallet<br />
<br />
pinentry-program /usr/bin/pinentry-gtk-2<br />
}}<br />
<br />
{{Tip|For using {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{AUR|kwalletcli}} package.}}<br />
<br />
After making this change, reload the gpg-agent.<br />
<br />
=== Start gpg-agent with systemd user ===<br />
<br />
{{Expansion|Add {{ic|gpg-agent-extra.socket}} and {{ic|gpg-agent-browser.socket}}.}}<br />
<br />
{{Pkg|gnupg}} comes with systemd user sockets which are enabled by default. These sockets are {{ic|gpg-agent.socket}}, {{ic|gpg-agent-extra.socket}}, {{ic|gpg-agent-browser.socket}}, {{ic|gpg-agent-ssh.socket}}, and {{ic|dirmngr.socket}}.<br />
<br />
The {{ic|gpg-agent.socket}} unit will start the service on-demand and manage the lifetime. The {{ic|dirmngr.socket}} should usually be enabled too, which is a daemon spawned to handle keyserver requests.<br />
<br />
The {{ic|gpg-agent-ssh.socket}} can be used to cache ssh keys. To use {{ic|gpg-agent-ssh.socket}}, {{ic|SSH_AUTH_SOCK}} environment variable needs to be [[#SSH agent|configured]] to point at {{ic|${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh}}. When {{ic|ssh-add}} is used, {{ic|gpg-agent}} will cache the ssh keys.<br />
<br />
=== Unattended passphrase ===<br />
<br />
Starting with GnuPG 2.1.0 the use of gpg-agent and pinentry is required, which may break backwards compatibility for passphrases piped in from STDIN using the {{ic|--passphrase-fd 0}} commandline option. In order to have the same type of functionality as the older releases two things must be done:<br />
<br />
First, edit the gpg-agent configuration to allow ''loopback'' pinentry mode:<br />
<br />
{{hc|1=~/.gnupg/gpg-agent.conf|2=<br />
allow-loopback-pinentry<br />
}}<br />
<br />
Restart the gpg-agent process if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|1=~/.gnupg/gpg.conf|2=<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://bugs.g10code.com/gnupg/issue1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your [[SSH keys]]. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
To start using GnuPG agent for your SSH keys, enable SSH support in the {{ic|~/.gnupg/gpg-agent.conf}} file:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
enable-ssh-support<br />
}}<br />
<br />
{{note|This workaround is no longer needed since systemd user unit {{ic|gpg-agent-ssh.socket}} is enabled by default and will launch {{ic|gpg-agent.service}} as necessary.}}<br />
<br />
Next, make sure that ''gpg-agent'' is always started. Either follow [[#Start gpg-agent with systemd user]], or add the following to your {{ic|.bashrc}} file:<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Start the gpg-agent if not already running<br />
if ! pgrep -x -u "${USER}" gpg-agent >/dev/null 2>&1; then<br />
gpg-connect-agent /bye >/dev/null 2>&1<br />
fi<br />
</nowiki>}}<br />
<br />
Then set {{ic|SSH_AUTH_SOCK}} so that SSH will use ''gpg-agent'' instead of ''ssh-agent''. To make sure each process can find your ''gpg-agent'' instance regardless of e.g. the type of shell it is child of use [[Environment_variables#Using_pam_env|pam_env]].<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
Alternatively, depend on Bash:<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Set SSH to use gpg-agent<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="/run/user/$UID/gnupg/S.gpg-agent.ssh"<br />
fi<br />
</nowiki>}}<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* If you use non-default GnuPG [[#Directory location]], run {{ic|gpgconf --create-socketdir}} to create a socket directory under {{ic|/run/user/$UID/gnupg/}}. Otherwise the socket will be placed in the GnuPG home directory.<br />
* The test involving the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable is for the case where the agent is started as {{ic|gpg-agent --daemon /bin/sh}}, in which case the shell inherits the {{ic|SSH_AUTH_SOCK}} variable from the parent, ''gpg-agent'' [http://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307].<br />
}}<br />
<br />
Also set the GPG_TTY and refresh the TTY in case user has switched into an X session as stated in {{ic|man gpg-agent}}. For example:<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Set GPG TTY<br />
export GPG_TTY=$(tty)<br />
<br />
# Refresh gpg-agent tty in case user switches into an X session<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
</nowiki>}}<br />
<br />
Once ''gpg-agent'' is running you can use ''ssh-add'' to approve keys, following the same steps as for [[SSH keys#ssh-agent|ssh-agent]]. The list of approved keys is stored in the {{ic|~/.gnupg/sshcontrol}} file. Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. You can control passphrase caching in the {{ic|~/.gnupg/gpg-agent.conf}} file. The following example would have ''gpg-agent'' cache your keys for 3 hours:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl-ssh 10800<br />
max-cache-ttl-ssh 10800<br />
}}<br />
<br />
== Smartcards ==<br />
<br />
GnuPG uses ''scdaemon'' as an interface to your smartcard reader, please refer to the [[man page]] for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smarcard readers the optional dependency {{Pkg|libusb-compat}} have to be installed}}<br />
<br />
If you do not plan to use other cards but those based on GnuPG, you should check the {{Ic|reader-port}} parameter in {{ic|~/.gnupg/scdaemon.conf}}. The value '0' refers to the first available serial port reader and a value of '32768' (default) refers to the first USB reader.<br />
<br />
=== GnuPG with pcscd (PCSC Lite) ===<br />
<br />
{{Note|{{Pkg|pcsclite}} and {{Pkg|ccid}} have to be installed, and the contained [[systemd#Using units|systemd]] service {{ic|pcscd.service}} has to be running, or the socket {{ic|pcscd.socket}} has to be listening.}}<br />
<br />
pcscd is a daemon which handles access to smartcard (SCard API). If GnuPG's scdaemon fails to connect the smartcard directly (e.g. by using its integrated CCID support), it will fallback and try to find a smartcard using the PCSC Lite driver.<br />
<br />
==== Always use pcscd ====<br />
<br />
If you are using any smartcard with an opensc driver (e.g.: ID cards from some countries) you should pay some attention to GnuPG configuration. Out of the box you might receive a message like this when using {{Ic|gpg --card-status}}<br />
<br />
gpg: selecting openpgp failed: ec=6.108<br />
<br />
By default, scdaemon will try to connect directly to the device. This connection will fail if the reader is being used by another process. For example: the pcscd daemon used by OpenSC. To cope with this situation we should use the same underlying driver as opensc so they can work well together. In order to point scdaemon to use pcscd you should remove {{Ic|reader-port}} from {{ic|~/.gnupg/scdaemon.conf}}, specify the location to {{ic|libpcsclite.so}} library and disable ccid so we make sure that we use pcscd:<br />
<br />
{{hc|~/.gnupg/scdaemon.conf|<nowiki><br />
pcsc-driver /usr/lib/libpcsclite.so<br />
card-timeout 5<br />
disable-ccid<br />
</nowiki>}}<br />
<br />
Please check {{Ic|man scdaemon}} if you do not use OpenSC.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Different algorithm ===<br />
<br />
You may want to use stronger algorithms:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
...<br />
<br />
personal-digest-preferences SHA512<br />
cert-digest-algo SHA512<br />
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed<br />
personal-cipher-preferences TWOFISH CAMELLIA256 AES 3DES<br />
}}<br />
<br />
In the latest version of GnuPG, the default algorithms used are SHA256 and AES, both of which are secure enough for most people. However, if you are using a version of GnuPG older than 2.1, or if you want an even higher level of security, then you should follow the above step.<br />
<br />
=== Encrypt a password ===<br />
{{Tip|[[pass]] automates this process.}}<br />
<br />
It can be useful to encrypt some password, so it will not be written in clear on a configuration file. A good example is your email password.<br />
<br />
First create a file with your password. You '''need''' to leave '''one''' empty line after the password, otherwise gpg will return an error message when evaluating the file.<br />
<br />
Then run:<br />
<br />
$ gpg -e -a -r ''<user-id>'' ''your_password_file''<br />
<br />
{{ic|-e}} is for encrypt, {{ic|-a}} for armor (ASCII output), {{ic|-r}} for recipient user ID.<br />
<br />
You will be left with a new {{ic|''your_password_file''.asc}} file.<br />
<br />
=== Revoking a key ===<br />
<br />
{{Warning|<br />
*Anybody having access to your revocation certificate can revoke your key, rendering it useless.<br />
*Key revocation should only be performed if your key is compromised or lost, or you forget your passphrase.}}<br />
<br />
Revocation certificates are automatically generated for newly generated keys, although one can be generated manually by the user later. These are located at {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
<br />
To revoke your key, simply import the revocation certificate:<br />
<br />
$ gpg --import ''<fingerprint>''.rev<br />
<br />
Now update the keyserver:<br />
<br />
$ gpg --keyserver subkeys.pgp.net --send-keys ''<userid>''<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on first use|Trust on first use]] by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''<user-id>''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''<user-id>''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses the [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together at a physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-svn}}.<br />
<br />
To send the signatures to their owners you need a working [[Wikipedia:Message transfer agent|MTA]]. If you do not have already one, install [[msmtp]].<br />
<br />
=== Always show long ID's and fingerprints ===<br />
<br />
To always show long key ID's add {{ic|keyid-format 0xlong}} to your configuration file. To always show full fingerprints of keys, add {{ic|with-fingerprint}} to your configuration file.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Not enough random bytes available ===<br />
When generating a key, gpg can run into this error:<br />
Not enough random bytes available. Please do some other work to give the OS a chance to collect more entropy!<br />
To check the available entropy, check the kernel parameters:<br />
cat /proc/sys/kernel/random/entropy_avail<br />
A healthy Linux system with a lot of entropy available will have return close to the full 4,096 bits of entropy. If the value returned is less than 200, the system is running low on entropy. <br />
<br />
To solve it, remember you do not often need to create keys and best just do what the message suggests (e.g. create disk activity, move the mouse, edit the wiki - all will create entropy). If that does not help, check which service is using up the entropy and consider stopping it for the time. If that is no alternative, see [[Random number generation#Alternatives]].<br />
<br />
=== su ===<br />
<br />
When using {{Ic|pinentry}}, you must have the proper permissions of the terminal device (e.g. {{Ic|/dev/tty1}}) in use. However, with ''su'' (or ''sudo''), the ownership stays with the original user, not the new one. This means that pinentry will fail, even as root. The fix is to change the permissions of the device at some point before the use of pinentry (i.e. using gpg with an agent). If doing gpg as root, simply change the ownership to root right before using gpg:<br />
<br />
# chown root /dev/ttyN # where N is the current tty<br />
<br />
and then change it back after using gpg the first time. The equivalent is likely to be true with {{Ic|/dev/pts/}}.<br />
<br />
{{Note|The owner of tty ''must'' match with the user for which pinentry is running. Being part of the group {{Ic|tty}} '''is not''' enough.}}<br />
<br />
{{Tip|If you run gpg with {{ic|script}} it will use a new tty with the correct ownership:<br />
<br />
# script -q -c "gpg --gen-key" /dev/null<br />
}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
The default pinentry program is pinentry-gtk-2, which needs a DBus session bus to run properly. See [[General troubleshooting#Session permissions]] for details.<br />
<br />
Alternatively, you can use {{ic|pinentry-qt}}. See [[#pinentry]].<br />
<br />
=== KGpg configuration permissions ===<br />
<br />
There have been issues with {{Pkg|kdeutils-kgpg}}{{Broken package link|replaced by {{Pkg|kgpg}}}} being able to access the {{ic|~/.gnupg/}} options. One issue might be a result of a deprecated ''options'' file, see the [https://bugs.kde.org/show_bug.cgi?id=290221 bug] report.<br />
<br />
Another user reported that ''KGpg'' failed to start until the {{ic|~/.gnupg}} folder is set to {{ic|drwxr-xr-x}} permissions. If you require this work-around, ensure that the directory contents retain {{ic|-rw-------}} permissions! Further, report it as a bug to the [https://bugs.kde.org/buglist.cgi?quicksearch=kgpg developers].<br />
<br />
=== Conflicts between gnome-keyring and gpg-agent ===<br />
<br />
{{Remove|1=Useless statement for an [https://wiki.archlinux.org/index.php?title=GnuPG&diff=399866&oldid=399865 old version] of GnuPG.}}<br />
<br />
Although the Gnome keyring implements a GPG agent component, GnuPG ignores the {{ic|GPG_AGENT_INFO}} environment variable, so that Gnome keyring can no longer be used as a GPG agent.<br />
<br />
{{Move|#pinentry|Configuration does not belong under troubleshooting.}}<br />
<br />
However, the package {{Pkg|pinentry}} provides the {{Ic|pinentry-gnome3}} program. You may set the following option in your {{Ic|gpg-agent.conf}} file<br />
pinentry-program /usr/bin/pinentry-gnome3<br />
in order to make use of that pinentry program.<br />
<br />
All pinentry programs can be configured to optionally save a passphrase with libsecret. For example, when the user is asked for a passphrase via {{Ic|pinentry-gnome3}}, a checkbox is shown whether to save the passphrase using a password manager.<br />
<br />
=== GNOME on Wayland overrides SSH agent socket ===<br />
<br />
For Wayland sessions, {{Ic|gnome-session}} sets {{Ic|SSH_AUTH_SOCK}} to the standard gnome-keyring socket, {{Ic|$XDG_RUNTIME_DIR/keyring/ssh}}. This overrides any value set in {{Ic|~/.pam_environmment}} or systemd unit files.<br />
<br />
To disable this behavior, set the {{Ic|GSM_SKIP_AGENT_WORKAROUND}} variable:<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
GSM_SKIP_SSH_AGENT_WORKAROUND DEFAULT="true"<br />
}}<br />
<br />
=== mutt and gpg ===<br />
<br />
To be asked for your GnuPG password only once per session, see [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread].<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. Basically, it says that there is a bug with keys in the old {{ic|pubring.gpg}} and {{ic|secring.gpg}} files, which have now been superseded by the new {{ic|pubring.kbx}} file and the {{ic|private-keys-v1.d/}} subdirectory and files. Your missing keys can be recovered with the following commnads:<br />
<br />
$ cd<br />
$ cp -r .gnupg gnupgOLD<br />
$ gpg --export-ownertrust > otrust.txt<br />
$ gpg --import .gnupg/pubring.gpg<br />
$ gpg --import-ownertrust otrust.txt<br />
$ gpg --list-keys<br />
<br />
=== gpg hanged for all keyservers (when trying to receive keys) ===<br />
<br />
If gpg hanged with a certain keyserver when trying to receive keys, you might need to kill dirmngr in order to get access to other keyservers which are actually working, otherwise it might keeping hanging for all of them.<br />
<br />
=== Smartcard not detected ===<br />
<br />
Your user might not have the permission to access the smartcard which results in a {{ic|card error}} to be thrown, even though the card is correctly set up and inserted.<br />
<br />
One possible solution is to add a new group {{ic|scard}} including the users who need access to the smartcard.<br />
<br />
Then use an [[Udev#Writing_udev_rules|udev]] rule, similar to the following:<br />
{{hc|/etc/udev/rules.d/71-gnupg-ccid.rules|<nowiki><br />
ACTION=="add", SUBSYSTEM=="usb", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0116|0111", MODE="660", GROUP="scard"<br />
</nowiki>}}<br />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<br />
* [https://tools.ietf.org/html/rfc4880 RFC4880 "OpenPGP Message Format"]<br />
* [https://fedoraproject.org/wiki/Creating_GPG_Keys Creating GPG Keys (Fedora)]<br />
* [https://wiki.debian.org/Subkeys OpenPGP subkeys in Debian]<br />
* [https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/ A more comprehensive gpg Tutorial]<br />
* [https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]<br />
* [https://github.com/ioerror/torbirdy/blob/master/gpg.conf Torbirdy gpg.conf]<br />
* [https://www.reddit.com/r/GPGpractice/ /r/GPGpractice - a subreddit to practice using GnuPG.]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=GnuPG&diff=479703GnuPG2017-06-12T18:12:33Z<p>Alive4ever: /* Start gpg-agent with systemd user */ use xdg runtime dir instead of /run/user/{UID}</p>
<hr />
<div>[[Category:Encryption]]<br />
[[es:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[zh-hans:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Disk encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related articles end}}<br />
<br />
According to the [http://www.gnupg.org official website]:<br />
<br />
:GnuPG is a complete and free implementation of the [http://openpgp.org/about/ OpenPGP] standard as defined by [https://tools.ietf.org/html/rfc4880 RFC4880] (also known as PGP). GnuPG allows you to encrypt and sign your data and communication. It features a versatile key management system as well as access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. Version 2 of GnuPG also provides support for S/MIME and Secure Shell (ssh).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|gnupg}} package.<br />
<br />
This will also install {{Pkg|pinentry}}, a collection of simple PIN or passphrase entry dialogs which GnuPG uses for passphrase entry. Which ''pinentry'' dialog is used is determined by the symbolic link {{ic|/usr/bin/pinentry}}, which by default points to {{ic|/usr/bin/pinentry-gtk-2}}.<br />
<br />
If you want to use a graphical frontend or program that integrates with GnuPG, see [[List of applications/Security#Encryption, signing, steganography]].<br />
<br />
== Configuration ==<br />
<br />
=== Directory location ===<br />
{{ic|$GNUPGHOME}} is used by GnuPG to point to the directory where its configuration files are stored. By default {{ic|$GNUPGHOME}} is not set and your {{ic|$HOME}} is used instead; thus, you will find a {{ic|~/.gnupg}} directory right after installation. <br />
<br />
To change the default location, either run gpg this way {{ic|$ gpg --homedir ''path/to/file''}} or set {{ic|GNUPGHOME}} in one of your regular [[startup files]].<br />
<br />
=== Configuration files ===<br />
<br />
The default configuration files are {{ic|~/.gnupg/gpg.conf}} and {{ic|~/.gnupg/dirmngr.conf}}. <br />
<br />
By default, the gnupg directory has its [[permissions]] set to {{ic|700}} and the files it contains have their permissions set to {{ic|600}}. Only the owner of the directory has permission to read, write, and access the files. This is for security purposes and should not be changed. In case this directory or any file inside it does not follow this security measure, you will get warnings about unsafe file and home directory permissions.<br />
<br />
Append to these files any long options you want. Do not write the two dashes, but simply the name of the option and required arguments. You will find skeleton files in {{ic|/usr/share/gnupg}}. These files are copied to {{ic|~/.gnupg}} the first time gpg is run if they do not exist there. Other examples are found in [[#See also]].<br />
<br />
Additionally, [[pacman]] uses a different set of configuration files for package signature verification. See [[Pacman/Package signing]] for details.<br />
<br />
=== Default options for new users ===<br />
<br />
If you want to setup some default options for new users, put configuration files in {{ic|/etc/skel/.gnupg/}}. When the new user is added in system, files from here will be copied to its GnuPG home directory. There is also a simple script called ''addgnupghome'' which you can use to create new GnuPG home directories for existing users:<br />
<br />
# addgnupghome user1 user2<br />
<br />
This will add the respective {{ic|/home/user1/.gnupg}} and {{ic|/home/user2/.gnupg}} and copy the files from the skeleton directory to it. Users with existing GnuPG home directory are simply skipped.<br />
<br />
== Usage ==<br />
<br />
{{Note|Whenever a ''{{ic|user-id}}'' is required in a command, it can be specified with your key ID, fingerprint, a part of your name or email address, etc. GnuPG is flexible on this.<br />
}}<br />
<br />
=== Create key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
{{Tip|Use the {{ic|--expert}} option for getting alternative ciphers like [[wikipedia:Elliptic_curve_cryptography|ECC]].}}<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* the RSA (sign only) and a RSA (encrypt only) key.<br />
* a keysize of the default value (2048). A larger keysize of 4096 "gives us almost nothing, while costing us quite a lot"[https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096].<br />
* an expiration date. A period of a year is good enough for the average user. This way even if access is lost to the keyring, it will allow others to know that it is no longer valid. Later, if necessary, the expiration date can be extended without having to re-issue a new key.<br />
* your name and email address. You can add multiple identities to the same key later (''e.g.'', if you have multiple email addresses you want to associate with this key).<br />
* ''no'' optional comment. Since the semantics of the comment field are [https://lists.gnupg.org/pipermail/gnupg-devel/2015-July/030150.html not well-defined], it has limited value for identification.<br />
* [[Security#Choosing_secure_passwords|a secure passphrase]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
gpg's main usage is to ensure confidentiality of exchanged messages via public-key cryptography. With it each user distributes the public key of their keyring, which can be be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[w:Public-key cryptography]] for examples about the message exchange. <br />
<br />
So, in order for others to send encrypted messages to you, they need your public key. <br />
<br />
To generate an ASCII version of your public key (''e.g.'' to distribute it by e-mail):<br />
<br />
$ gpg --output ''public.key'' --armor --export ''user-id'' <br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public.key''}} to your public key ring:<br />
<br />
$ gpg --import ''public.key''<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
=== Use a keyserver ===<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve your key without having to contact you directly:<br />
<br />
$ gpg --send-keys ''user-id''<br />
<br />
To find out details of a key on the keyserver, without importing it, do:<br />
<br />
$ gpg --search-keys ''user-id''<br />
<br />
To import a key from a key server:<br />
<br />
$ gpg --recv-keys ''key-id''<br />
<br />
{{Warning|<br />
* You should verify the authenticity of the retrieved public key by comparing its fingerprint with one that the owner published on an independent source(s) (i.e., contacting the person directly). See [[Wikipedia:Public key fingerprint]] for more information.<br />
* Using a short ID may encounter collisions. All keys will be imported that have the short ID. To avoid this, use the full fingerprint or long key ID when receiving a key.[https://lkml.org/lkml/2016/8/15/445]}}<br />
<br />
{{Tip|<br />
* Adding {{ic|keyserver-options auto-key-retrieve}} to {{ic|gpg.conf}} will automatically fetch keys from the key server as needed. <br />
* An alternative key server is {{ic|pool.sks-keyservers.net}} and can be specified with {{ic|keyserver}} in {{ic|dirmngr.conf}}; see also [[wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
* If your network blocks ports used for hkp/hkps, you may need to specify port 80, i.e. {{ic|pool.sks-keyservers.net:80}}<br />
* You can connect to the keyserver over [[Tor]] using {{ic|--use-tor}}. See this [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html GnuPG blog post] for more information.<br />
* You can connect to a keyserver using a proxy by setting the {{ic|http_proxy}} environment variable and setting {{ic|honor-http-proxy}} in {{ic|dirmngr.conf}}. Alternatively, set {{ic|http-proxy ''host[:port]''}} in {{ic|dirmngr.conf}}, overriding the {{ic|http_proxy}} environment variable.<br />
* If you wish to import a key ID to install a specific Arch Linux package, see [[pacman/Package signing#Managing the keyring]] and [[Makepkg#Signature checking]].}}<br />
<br />
=== Encrypt and decrypt ===<br />
<br />
==== Asymmetric ====<br />
You need to [[#Import a public key]] of a user before encrypting (options {{ic|--encrypt}} or {{ic|-e}}) a file or message to that recipient (options {{ic|--recipient}} or {{ic|-r}}). Additionally you need to [[#Create key pair]] if you have not already done so.<br />
<br />
To encrypt a file with the name ''doc'', use:<br />
<br />
$ gpg --recipient ''user-id'' --encrypt ''doc''<br />
<br />
To decrypt (option {{ic|--decrypt}} or {{ic|-d}}) a file with the name ''doc''.gpg encrypted with your public key, use:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
''gpg'' will prompt you for your passphrase and then decrypt and write the data from ''doc''.gpg to ''doc''. If you omit the {{ic|-o}} ({{ic|--output}}) option, ''gpg'' will write the decrypted data to stdout.<br />
<br />
{{Tip|<br />
* Add {{ic|--armor}} to encrypt a file using ASCII armor (suitable for copying and pasting a message in text format)<br />
* Use {{ic|-R ''user-id''}} or {{ic|--hidden-recipient ''user-id''}} instead of {{ic|-r}} to not put the recipient key IDs in the encrypted message. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis.<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can use gnupg to encrypt your sensitive documents by using your own user-id as recipient or by using the {{ic|--default-recipient-self}} flag instead; however, you can only do this one file at a time, although you can always tarball various files and then encrypt the tarball. See also [[Disk encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
==== Symmetric ====<br />
Symmetric encryption does not require the generation of a key pair and can be used to simply encrypt data with a passphrase. Simply use {{ic|--symmetric}} or {{ic|-c}} to perform symmetic encryption:<br />
<br />
$ gpg -c ''doc''<br />
<br />
The following example:<br />
<br />
* Encrypts {{ic|''doc''}} with a symmetric cipher using a passphrase<br />
* Uses the AES-256 cipher algorithm to encrypt the passphrase<br />
* Uses the SHA-512 digest algorithm to mangle the passphrase<br />
* Mangles the passphrase for 65536 iterations<br />
<br />
$ gpg -c --s2k-cipher-algo AES256 --s2k-digest-algo SHA512 --s2k-count 65536 ''doc''<br />
<br />
To decrypt a symmetrically encrypted {{ic|''doc''.gpg}} using a passphrase and output decrypted contents into the same directory as {{ic|''doc''}} do:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor ''<user-id>'' > ''privkey.asc''<br />
<br />
Note that ''gpg'' release 2.1 changed default behaviour so that the above command enforces a passphrase protection, even if you deliberately chose not to use one on key creation. This is because otherwise anyone who gains access to the above exported file would be able to encrypt and sign documents as if they were you ''without'' needing to know your passphrase. <br />
<br />
{{Warning|The passphrase is usually the weakest link in protecting your secret key. Place the private key in a safe place on a different system/device, such as a locked container or encrypted drive. It is the only safety you have to regain control to your keyring in case of, for example, a drive failure, theft or worse.}}<br />
<br />
To import the backup of your private key:<br />
$ gpg --import ''privkey.asc''<br />
<br />
=== Edit your key ===<br />
<br />
Running the {{ic|gpg --edit-key ''<user-id>''}} command will present a menu which enables you to do most of your key management related tasks.<br />
<br />
Some useful commands in the edit key sub menu:<br />
> passwd # change the passphrase<br />
> clean # compact any user ID that is no longer usable (e.g revoked or expired)<br />
> revkey # revoke a key<br />
> addkey # add a subkey to this key<br />
> expire # change the key expiration time<br />
<br />
Type {{ic|help}} in the edit key sub menu for more commands.<br />
<br />
{{Tip|If you have multiple email accounts you can add each one of them as an identity, using {{ic|adduid}} command. You can then set your favourite one as {{ic|primary}}.}}<br />
<br />
=== Exporting subkey ===<br />
<br />
If you plan to use the same key across multiple devices, you may want to strip out your master key and only keep the bare minimum encryption subkey on less secure systems.<br />
<br />
First, find out which subkey you want to export.<br />
<br />
$ gpg -K<br />
<br />
Select only that subkey to export.<br />
<br />
$ gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.gpg<br />
<br />
{{Warning|If you forget to add the !, all of your subkeys will be exported.}}<br />
<br />
At this point you could stop, but it is most likely a good idea to change the passphrase as well. Import the key into a temporary folder. <br />
<br />
$ gpg --homedir /tmp/gpg --import /tmp/subkey.gpg<br />
$ gpg --homedir /tmp/gpg --edit-key ''<user-id>''<br />
> passwd<br />
> save<br />
$ gpg --homedir /tmp/gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.altpass.gpg<br />
<br />
{{Note|You will get a warning that the master key was not available and the password was not changed, but that can safely be ignored as the subkey password was.}}<br />
<br />
At this point, you can now use {{ic|/tmp/subkey.altpass.gpg}} on your other devices.<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
If you have set your subkeys to expire after a set time, you can create new ones. Do this a few weeks in advance to allow others to update their keyring.<br />
<br />
{{Note|You do not need to create a new key simply because it is expired. You can extend the expiration date.}}<br />
<br />
Create new subkey (repeat for both signing and encrypting key)<br />
<br />
$ gpg --edit-key ''<user-id>''<br />
> addkey<br />
<br />
And answer the following questions it asks (see [[#Create key pair]] for suggested settings).<br />
<br />
Save changes<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver pgp.mit.edu --send-keys ''<user-id>''<br />
<br />
{{Note|Revoking expired subkeys is unnecessary and arguably bad form. If you are constantly revoking keys, it may cause others to lack confidence in you.}}<br />
<br />
== Signatures ==<br />
<br />
Signatures certify and timestamp documents. If the document is modified, verification of the signature will fail. Unlike encryption which uses public keys to encrypt a document, signatures are created with the user's private key. The recipient of a signed document then verifies the signature using the sender's public key.<br />
<br />
=== Create a signature ===<br />
<br />
==== Sign a file ====<br />
<br />
To sign a file use the {{ic|--sign}} or {{ic|-s}} flag:<br />
<br />
$ gpg --output ''doc''.sig --sign ''doc''<br />
<br />
{{ic|''doc''.sig}} contains both the compressed content of the original file {{ic|''doc''}} and the signature in a binary format, but the file is not encrypted. However, you can combine signing with [[#Encrypt and decrypt|encrypting]].<br />
<br />
==== Clearsign a file or message ====<br />
<br />
To sign a file without compressing it into binary format use:<br />
<br />
$ gpg --output ''doc''.sig --clearsign ''doc''<br />
<br />
Here both the content of the original file {{ic|''doc''}} and the signature are stored in human-readable form in {{ic|''doc''.sig}}.<br />
<br />
==== Make a detached signature ====<br />
<br />
To create a separate signature file to be distributed separately from the document or file itself, use the {{ic|--detach-sig}} flag:<br />
<br />
$ gpg --output ''doc''.sig --detach-sig ''doc''<br />
<br />
Here the signature is stored in {{ic|''doc''.sig}}, but the contents of {{ic|''doc''}} are not stored in it. This method is often used in distributing software projects to allow users to verify that the program has not been modified by a third party.<br />
<br />
=== Verify a signature ===<br />
<br />
To verify a signature use the {{ic|--verify}} flag:<br />
<br />
$ gpg --verify ''doc''.sig<br />
<br />
where {{ic|''doc''.sig}} is the signed file containing the signature you wish to verify.<br />
<br />
If you are verifying a detached signature, both the signed data file and the signature file must be present when verifying. For example, to verify Arch Linux's latest iso you would do:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig<br />
<br />
where {{ic|archlinux-''version''.iso}} must be located in the same directory.<br />
<br />
You can also specify the signed data file with a second argument:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig ''/path/to/''archlinux-''version''.iso<br />
<br />
If a file as been encrypted in addition to being signed, simply [[#Encrypt and decrypt|decrypt]] the file and its signature will also be verified.<br />
<br />
== gpg-agent ==<br />
<br />
''gpg-agent'' is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client.<br />
<br />
Starting with GnuPG 2.1.0 the use of ''gpg-agent'' is required. ''gpg-agent'' is started on-demand by the GnuPG tools, so there is usually no reason to start it manually.<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{ic|man gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|To cache your passphrase for the whole session, please run the following command:<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXXX<br />
<br />
where XXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. Passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
}}<br />
<br />
=== Reload the agent ===<br />
<br />
After changing the configuration, reload the agent using ''gpg-connect-agent'':<br />
<br />
$ gpg-connect-agent reloadagent /bye<br />
<br />
The command should print {{ic|OK}}.<br />
<br />
=== pinentry ===<br />
<br />
Finally, the agent needs to know how to ask the user for the password. This can be set in the gpg-agent configuration file.<br />
<br />
The default uses a gtk dialog. There are other options - see {{ic|info pinentry}}. To change the dialog implementation set {{ic|pinentry-program}} configuration option:<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
<br />
# PIN entry program<br />
# pinentry-program /usr/bin/pinentry-curses<br />
# pinentry-program /usr/bin/pinentry-qt<br />
# pinentry-program /usr/bin/pinentry-kwallet<br />
<br />
pinentry-program /usr/bin/pinentry-gtk-2<br />
}}<br />
<br />
{{Tip|For using {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{AUR|kwalletcli}} package.}}<br />
<br />
After making this change, reload the gpg-agent.<br />
<br />
=== Start gpg-agent with systemd user ===<br />
<br />
{{Expansion|Add {{ic|gpg-agent-extra.socket}} and {{ic|gpg-agent-browser.socket}}.}}<br />
<br />
{{Pkg|gnupg}} comes with systemd user sockets which are enabled by default. These sockets are {{ic|gpg-agent.socket}}, {{ic|gpg-agent-extra.socket}}, {{ic|gpg-agent-browser.socket}}, {{ic|gpg-agent-ssh.socket}}, and {{ic|dirmngr.socket}}.<br />
<br />
The {{ic|gpg-agent.socket}} unit will start the service on-demand and manage the lifetime. The {{ic|dirmngr.socket}} should usually be enabled too, which is a daemon spawned to handle keyserver requests.<br />
<br />
The {{ic|gpg-agent-ssh.socket}} can be used to cache ssh keys. To use {{ic|gpg-agent-ssh.socket}}, {{ic|SSH_AUTH_SOCK}} environment variable needs to be [[#SSH agent|configured]] to point at {{ic|${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh}}. When {{ic|ssh-add}} is used, {{ic|gpg-agent}} will cache the ssh keys.<br />
<br />
=== Unattended passphrase ===<br />
<br />
Starting with GnuPG 2.1.0 the use of gpg-agent and pinentry is required, which may break backwards compatibility for passphrases piped in from STDIN using the {{ic|--passphrase-fd 0}} commandline option. In order to have the same type of functionality as the older releases two things must be done:<br />
<br />
First, edit the gpg-agent configuration to allow ''loopback'' pinentry mode:<br />
<br />
{{hc|1=~/.gnupg/gpg-agent.conf|2=<br />
allow-loopback-pinentry<br />
}}<br />
<br />
Restart the gpg-agent process if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|1=~/.gnupg/gpg.conf|2=<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://bugs.g10code.com/gnupg/issue1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your [[SSH keys]]. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
To start using GnuPG agent for your SSH keys, enable SSH support in the {{ic|~/.gnupg/gpg-agent.conf}} file:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
enable-ssh-support<br />
}}<br />
<br />
Next, make sure that ''gpg-agent'' is always started. Either follow [[#Start gpg-agent with systemd user]], or add the following to your {{ic|.bashrc}} file:<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Start the gpg-agent if not already running<br />
if ! pgrep -x -u "${USER}" gpg-agent >/dev/null 2>&1; then<br />
gpg-connect-agent /bye >/dev/null 2>&1<br />
fi<br />
</nowiki>}}<br />
<br />
Then set {{ic|SSH_AUTH_SOCK}} so that SSH will use ''gpg-agent'' instead of ''ssh-agent''. To make sure each process can find your ''gpg-agent'' instance regardless of e.g. the type of shell it is child of use [[Environment_variables#Using_pam_env|pam_env]].<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
Alternatively, depend on Bash:<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Set SSH to use gpg-agent<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="/run/user/$UID/gnupg/S.gpg-agent.ssh"<br />
fi<br />
</nowiki>}}<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* If you use non-default GnuPG [[#Directory location]], run {{ic|gpgconf --create-socketdir}} to create a socket directory under {{ic|/run/user/$UID/gnupg/}}. Otherwise the socket will be placed in the GnuPG home directory.<br />
* The test involving the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable is for the case where the agent is started as {{ic|gpg-agent --daemon /bin/sh}}, in which case the shell inherits the {{ic|SSH_AUTH_SOCK}} variable from the parent, ''gpg-agent'' [http://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307].<br />
}}<br />
<br />
Also set the GPG_TTY and refresh the TTY in case user has switched into an X session as stated in {{ic|man gpg-agent}}. For example:<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Set GPG TTY<br />
export GPG_TTY=$(tty)<br />
<br />
# Refresh gpg-agent tty in case user switches into an X session<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
</nowiki>}}<br />
<br />
Once ''gpg-agent'' is running you can use ''ssh-add'' to approve keys, following the same steps as for [[SSH keys#ssh-agent|ssh-agent]]. The list of approved keys is stored in the {{ic|~/.gnupg/sshcontrol}} file. Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. You can control passphrase caching in the {{ic|~/.gnupg/gpg-agent.conf}} file. The following example would have ''gpg-agent'' cache your keys for 3 hours:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl-ssh 10800<br />
max-cache-ttl-ssh 10800<br />
}}<br />
<br />
== Smartcards ==<br />
<br />
GnuPG uses ''scdaemon'' as an interface to your smartcard reader, please refer to the [[man page]] for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smarcard readers the optional dependency {{Pkg|libusb-compat}} have to be installed}}<br />
<br />
If you do not plan to use other cards but those based on GnuPG, you should check the {{Ic|reader-port}} parameter in {{ic|~/.gnupg/scdaemon.conf}}. The value '0' refers to the first available serial port reader and a value of '32768' (default) refers to the first USB reader.<br />
<br />
=== GnuPG with pcscd (PCSC Lite) ===<br />
<br />
{{Note|{{Pkg|pcsclite}} and {{Pkg|ccid}} have to be installed, and the contained [[systemd#Using units|systemd]] service {{ic|pcscd.service}} has to be running, or the socket {{ic|pcscd.socket}} has to be listening.}}<br />
<br />
pcscd is a daemon which handles access to smartcard (SCard API). If GnuPG's scdaemon fails to connect the smartcard directly (e.g. by using its integrated CCID support), it will fallback and try to find a smartcard using the PCSC Lite driver.<br />
<br />
==== Always use pcscd ====<br />
<br />
If you are using any smartcard with an opensc driver (e.g.: ID cards from some countries) you should pay some attention to GnuPG configuration. Out of the box you might receive a message like this when using {{Ic|gpg --card-status}}<br />
<br />
gpg: selecting openpgp failed: ec=6.108<br />
<br />
By default, scdaemon will try to connect directly to the device. This connection will fail if the reader is being used by another process. For example: the pcscd daemon used by OpenSC. To cope with this situation we should use the same underlying driver as opensc so they can work well together. In order to point scdaemon to use pcscd you should remove {{Ic|reader-port}} from {{ic|~/.gnupg/scdaemon.conf}}, specify the location to {{ic|libpcsclite.so}} library and disable ccid so we make sure that we use pcscd:<br />
<br />
{{hc|~/.gnupg/scdaemon.conf|<nowiki><br />
pcsc-driver /usr/lib/libpcsclite.so<br />
card-timeout 5<br />
disable-ccid<br />
</nowiki>}}<br />
<br />
Please check {{Ic|man scdaemon}} if you do not use OpenSC.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Different algorithm ===<br />
<br />
You may want to use stronger algorithms:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
...<br />
<br />
personal-digest-preferences SHA512<br />
cert-digest-algo SHA512<br />
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed<br />
personal-cipher-preferences TWOFISH CAMELLIA256 AES 3DES<br />
}}<br />
<br />
In the latest version of GnuPG, the default algorithms used are SHA256 and AES, both of which are secure enough for most people. However, if you are using a version of GnuPG older than 2.1, or if you want an even higher level of security, then you should follow the above step.<br />
<br />
=== Encrypt a password ===<br />
{{Tip|[[pass]] automates this process.}}<br />
<br />
It can be useful to encrypt some password, so it will not be written in clear on a configuration file. A good example is your email password.<br />
<br />
First create a file with your password. You '''need''' to leave '''one''' empty line after the password, otherwise gpg will return an error message when evaluating the file.<br />
<br />
Then run:<br />
<br />
$ gpg -e -a -r ''<user-id>'' ''your_password_file''<br />
<br />
{{ic|-e}} is for encrypt, {{ic|-a}} for armor (ASCII output), {{ic|-r}} for recipient user ID.<br />
<br />
You will be left with a new {{ic|''your_password_file''.asc}} file.<br />
<br />
=== Revoking a key ===<br />
<br />
{{Warning|<br />
*Anybody having access to your revocation certificate can revoke your key, rendering it useless.<br />
*Key revocation should only be performed if your key is compromised or lost, or you forget your passphrase.}}<br />
<br />
Revocation certificates are automatically generated for newly generated keys, although one can be generated manually by the user later. These are located at {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
<br />
To revoke your key, simply import the revocation certificate:<br />
<br />
$ gpg --import ''<fingerprint>''.rev<br />
<br />
Now update the keyserver:<br />
<br />
$ gpg --keyserver subkeys.pgp.net --send-keys ''<userid>''<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on first use|Trust on first use]] by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''<user-id>''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''<user-id>''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses the [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together at a physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-svn}}.<br />
<br />
To send the signatures to their owners you need a working [[Wikipedia:Message transfer agent|MTA]]. If you do not have already one, install [[msmtp]].<br />
<br />
=== Always show long ID's and fingerprints ===<br />
<br />
To always show long key ID's add {{ic|keyid-format 0xlong}} to your configuration file. To always show full fingerprints of keys, add {{ic|with-fingerprint}} to your configuration file.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Not enough random bytes available ===<br />
When generating a key, gpg can run into this error:<br />
Not enough random bytes available. Please do some other work to give the OS a chance to collect more entropy!<br />
To check the available entropy, check the kernel parameters:<br />
cat /proc/sys/kernel/random/entropy_avail<br />
A healthy Linux system with a lot of entropy available will have return close to the full 4,096 bits of entropy. If the value returned is less than 200, the system is running low on entropy. <br />
<br />
To solve it, remember you do not often need to create keys and best just do what the message suggests (e.g. create disk activity, move the mouse, edit the wiki - all will create entropy). If that does not help, check which service is using up the entropy and consider stopping it for the time. If that is no alternative, see [[Random number generation#Alternatives]].<br />
<br />
=== su ===<br />
<br />
When using {{Ic|pinentry}}, you must have the proper permissions of the terminal device (e.g. {{Ic|/dev/tty1}}) in use. However, with ''su'' (or ''sudo''), the ownership stays with the original user, not the new one. This means that pinentry will fail, even as root. The fix is to change the permissions of the device at some point before the use of pinentry (i.e. using gpg with an agent). If doing gpg as root, simply change the ownership to root right before using gpg:<br />
<br />
# chown root /dev/ttyN # where N is the current tty<br />
<br />
and then change it back after using gpg the first time. The equivalent is likely to be true with {{Ic|/dev/pts/}}.<br />
<br />
{{Note|The owner of tty ''must'' match with the user for which pinentry is running. Being part of the group {{Ic|tty}} '''is not''' enough.}}<br />
<br />
{{Tip|If you run gpg with {{ic|script}} it will use a new tty with the correct ownership:<br />
<br />
# script -q -c "gpg --gen-key" /dev/null<br />
}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
The default pinentry program is pinentry-gtk-2, which needs a DBus session bus to run properly. See [[General troubleshooting#Session permissions]] for details.<br />
<br />
Alternatively, you can use {{ic|pinentry-qt}}. See [[#pinentry]].<br />
<br />
=== KGpg configuration permissions ===<br />
<br />
There have been issues with {{Pkg|kdeutils-kgpg}}{{Broken package link|replaced by {{Pkg|kgpg}}}} being able to access the {{ic|~/.gnupg/}} options. One issue might be a result of a deprecated ''options'' file, see the [https://bugs.kde.org/show_bug.cgi?id=290221 bug] report.<br />
<br />
Another user reported that ''KGpg'' failed to start until the {{ic|~/.gnupg}} folder is set to {{ic|drwxr-xr-x}} permissions. If you require this work-around, ensure that the directory contents retain {{ic|-rw-------}} permissions! Further, report it as a bug to the [https://bugs.kde.org/buglist.cgi?quicksearch=kgpg developers].<br />
<br />
=== Conflicts between gnome-keyring and gpg-agent ===<br />
<br />
{{Remove|1=Useless statement for an [https://wiki.archlinux.org/index.php?title=GnuPG&diff=399866&oldid=399865 old version] of GnuPG.}}<br />
<br />
Although the Gnome keyring implements a GPG agent component, GnuPG ignores the {{ic|GPG_AGENT_INFO}} environment variable, so that Gnome keyring can no longer be used as a GPG agent.<br />
<br />
{{Move|#pinentry|Configuration does not belong under troubleshooting.}}<br />
<br />
However, the package {{Pkg|pinentry}} provides the {{Ic|pinentry-gnome3}} program. You may set the following option in your {{Ic|gpg-agent.conf}} file<br />
pinentry-program /usr/bin/pinentry-gnome3<br />
in order to make use of that pinentry program.<br />
<br />
All pinentry programs can be configured to optionally save a passphrase with libsecret. For example, when the user is asked for a passphrase via {{Ic|pinentry-gnome3}}, a checkbox is shown whether to save the passphrase using a password manager.<br />
<br />
=== GNOME on Wayland overrides SSH agent socket ===<br />
<br />
For Wayland sessions, {{Ic|gnome-session}} sets {{Ic|SSH_AUTH_SOCK}} to the standard gnome-keyring socket, {{Ic|$XDG_RUNTIME_DIR/keyring/ssh}}. This overrides any value set in {{Ic|~/.pam_environmment}} or systemd unit files.<br />
<br />
To disable this behavior, set the {{Ic|GSM_SKIP_AGENT_WORKAROUND}} variable:<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
GSM_SKIP_SSH_AGENT_WORKAROUND DEFAULT="true"<br />
}}<br />
<br />
=== mutt and gpg ===<br />
<br />
To be asked for your GnuPG password only once per session, see [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread].<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. Basically, it says that there is a bug with keys in the old {{ic|pubring.gpg}} and {{ic|secring.gpg}} files, which have now been superseded by the new {{ic|pubring.kbx}} file and the {{ic|private-keys-v1.d/}} subdirectory and files. Your missing keys can be recovered with the following commnads:<br />
<br />
$ cd<br />
$ cp -r .gnupg gnupgOLD<br />
$ gpg --export-ownertrust > otrust.txt<br />
$ gpg --import .gnupg/pubring.gpg<br />
$ gpg --import-ownertrust otrust.txt<br />
$ gpg --list-keys<br />
<br />
=== gpg hanged for all keyservers (when trying to receive keys) ===<br />
<br />
If gpg hanged with a certain keyserver when trying to receive keys, you might need to kill dirmngr in order to get access to other keyservers which are actually working, otherwise it might keeping hanging for all of them.<br />
<br />
=== Smartcard not detected ===<br />
<br />
Your user might not have the permission to access the smartcard which results in a {{ic|card error}} to be thrown, even though the card is correctly set up and inserted.<br />
<br />
One possible solution is to add a new group {{ic|scard}} including the users who need access to the smartcard.<br />
<br />
Then use an [[Udev#Writing_udev_rules|udev]] rule, similar to the following:<br />
{{hc|/etc/udev/rules.d/71-gnupg-ccid.rules|<nowiki><br />
ACTION=="add", SUBSYSTEM=="usb", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0116|0111", MODE="660", GROUP="scard"<br />
</nowiki>}}<br />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<br />
* [https://tools.ietf.org/html/rfc4880 RFC4880 "OpenPGP Message Format"]<br />
* [https://fedoraproject.org/wiki/Creating_GPG_Keys Creating GPG Keys (Fedora)]<br />
* [https://wiki.debian.org/Subkeys OpenPGP subkeys in Debian]<br />
* [https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/ A more comprehensive gpg Tutorial]<br />
* [https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]<br />
* [https://github.com/ioerror/torbirdy/blob/master/gpg.conf Torbirdy gpg.conf]<br />
* [https://www.reddit.com/r/GPGpractice/ /r/GPGpractice - a subreddit to practice using GnuPG.]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=GnuPG&diff=479701GnuPG2017-06-12T18:10:10Z<p>Alive4ever: /* Start gpg-agent with systemd user */ fix linking to ssh agent subsection</p>
<hr />
<div>[[Category:Encryption]]<br />
[[es:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[zh-hans:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Disk encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related articles end}}<br />
<br />
According to the [http://www.gnupg.org official website]:<br />
<br />
:GnuPG is a complete and free implementation of the [http://openpgp.org/about/ OpenPGP] standard as defined by [https://tools.ietf.org/html/rfc4880 RFC4880] (also known as PGP). GnuPG allows you to encrypt and sign your data and communication. It features a versatile key management system as well as access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. Version 2 of GnuPG also provides support for S/MIME and Secure Shell (ssh).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|gnupg}} package.<br />
<br />
This will also install {{Pkg|pinentry}}, a collection of simple PIN or passphrase entry dialogs which GnuPG uses for passphrase entry. Which ''pinentry'' dialog is used is determined by the symbolic link {{ic|/usr/bin/pinentry}}, which by default points to {{ic|/usr/bin/pinentry-gtk-2}}.<br />
<br />
If you want to use a graphical frontend or program that integrates with GnuPG, see [[List of applications/Security#Encryption, signing, steganography]].<br />
<br />
== Configuration ==<br />
<br />
=== Directory location ===<br />
{{ic|$GNUPGHOME}} is used by GnuPG to point to the directory where its configuration files are stored. By default {{ic|$GNUPGHOME}} is not set and your {{ic|$HOME}} is used instead; thus, you will find a {{ic|~/.gnupg}} directory right after installation. <br />
<br />
To change the default location, either run gpg this way {{ic|$ gpg --homedir ''path/to/file''}} or set {{ic|GNUPGHOME}} in one of your regular [[startup files]].<br />
<br />
=== Configuration files ===<br />
<br />
The default configuration files are {{ic|~/.gnupg/gpg.conf}} and {{ic|~/.gnupg/dirmngr.conf}}. <br />
<br />
By default, the gnupg directory has its [[permissions]] set to {{ic|700}} and the files it contains have their permissions set to {{ic|600}}. Only the owner of the directory has permission to read, write, and access the files. This is for security purposes and should not be changed. In case this directory or any file inside it does not follow this security measure, you will get warnings about unsafe file and home directory permissions.<br />
<br />
Append to these files any long options you want. Do not write the two dashes, but simply the name of the option and required arguments. You will find skeleton files in {{ic|/usr/share/gnupg}}. These files are copied to {{ic|~/.gnupg}} the first time gpg is run if they do not exist there. Other examples are found in [[#See also]].<br />
<br />
Additionally, [[pacman]] uses a different set of configuration files for package signature verification. See [[Pacman/Package signing]] for details.<br />
<br />
=== Default options for new users ===<br />
<br />
If you want to setup some default options for new users, put configuration files in {{ic|/etc/skel/.gnupg/}}. When the new user is added in system, files from here will be copied to its GnuPG home directory. There is also a simple script called ''addgnupghome'' which you can use to create new GnuPG home directories for existing users:<br />
<br />
# addgnupghome user1 user2<br />
<br />
This will add the respective {{ic|/home/user1/.gnupg}} and {{ic|/home/user2/.gnupg}} and copy the files from the skeleton directory to it. Users with existing GnuPG home directory are simply skipped.<br />
<br />
== Usage ==<br />
<br />
{{Note|Whenever a ''{{ic|user-id}}'' is required in a command, it can be specified with your key ID, fingerprint, a part of your name or email address, etc. GnuPG is flexible on this.<br />
}}<br />
<br />
=== Create key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
{{Tip|Use the {{ic|--expert}} option for getting alternative ciphers like [[wikipedia:Elliptic_curve_cryptography|ECC]].}}<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* the RSA (sign only) and a RSA (encrypt only) key.<br />
* a keysize of the default value (2048). A larger keysize of 4096 "gives us almost nothing, while costing us quite a lot"[https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096].<br />
* an expiration date. A period of a year is good enough for the average user. This way even if access is lost to the keyring, it will allow others to know that it is no longer valid. Later, if necessary, the expiration date can be extended without having to re-issue a new key.<br />
* your name and email address. You can add multiple identities to the same key later (''e.g.'', if you have multiple email addresses you want to associate with this key).<br />
* ''no'' optional comment. Since the semantics of the comment field are [https://lists.gnupg.org/pipermail/gnupg-devel/2015-July/030150.html not well-defined], it has limited value for identification.<br />
* [[Security#Choosing_secure_passwords|a secure passphrase]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
gpg's main usage is to ensure confidentiality of exchanged messages via public-key cryptography. With it each user distributes the public key of their keyring, which can be be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[w:Public-key cryptography]] for examples about the message exchange. <br />
<br />
So, in order for others to send encrypted messages to you, they need your public key. <br />
<br />
To generate an ASCII version of your public key (''e.g.'' to distribute it by e-mail):<br />
<br />
$ gpg --output ''public.key'' --armor --export ''user-id'' <br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public.key''}} to your public key ring:<br />
<br />
$ gpg --import ''public.key''<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
=== Use a keyserver ===<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve your key without having to contact you directly:<br />
<br />
$ gpg --send-keys ''user-id''<br />
<br />
To find out details of a key on the keyserver, without importing it, do:<br />
<br />
$ gpg --search-keys ''user-id''<br />
<br />
To import a key from a key server:<br />
<br />
$ gpg --recv-keys ''key-id''<br />
<br />
{{Warning|<br />
* You should verify the authenticity of the retrieved public key by comparing its fingerprint with one that the owner published on an independent source(s) (i.e., contacting the person directly). See [[Wikipedia:Public key fingerprint]] for more information.<br />
* Using a short ID may encounter collisions. All keys will be imported that have the short ID. To avoid this, use the full fingerprint or long key ID when receiving a key.[https://lkml.org/lkml/2016/8/15/445]}}<br />
<br />
{{Tip|<br />
* Adding {{ic|keyserver-options auto-key-retrieve}} to {{ic|gpg.conf}} will automatically fetch keys from the key server as needed. <br />
* An alternative key server is {{ic|pool.sks-keyservers.net}} and can be specified with {{ic|keyserver}} in {{ic|dirmngr.conf}}; see also [[wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
* If your network blocks ports used for hkp/hkps, you may need to specify port 80, i.e. {{ic|pool.sks-keyservers.net:80}}<br />
* You can connect to the keyserver over [[Tor]] using {{ic|--use-tor}}. See this [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html GnuPG blog post] for more information.<br />
* You can connect to a keyserver using a proxy by setting the {{ic|http_proxy}} environment variable and setting {{ic|honor-http-proxy}} in {{ic|dirmngr.conf}}. Alternatively, set {{ic|http-proxy ''host[:port]''}} in {{ic|dirmngr.conf}}, overriding the {{ic|http_proxy}} environment variable.<br />
* If you wish to import a key ID to install a specific Arch Linux package, see [[pacman/Package signing#Managing the keyring]] and [[Makepkg#Signature checking]].}}<br />
<br />
=== Encrypt and decrypt ===<br />
<br />
==== Asymmetric ====<br />
You need to [[#Import a public key]] of a user before encrypting (options {{ic|--encrypt}} or {{ic|-e}}) a file or message to that recipient (options {{ic|--recipient}} or {{ic|-r}}). Additionally you need to [[#Create key pair]] if you have not already done so.<br />
<br />
To encrypt a file with the name ''doc'', use:<br />
<br />
$ gpg --recipient ''user-id'' --encrypt ''doc''<br />
<br />
To decrypt (option {{ic|--decrypt}} or {{ic|-d}}) a file with the name ''doc''.gpg encrypted with your public key, use:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
''gpg'' will prompt you for your passphrase and then decrypt and write the data from ''doc''.gpg to ''doc''. If you omit the {{ic|-o}} ({{ic|--output}}) option, ''gpg'' will write the decrypted data to stdout.<br />
<br />
{{Tip|<br />
* Add {{ic|--armor}} to encrypt a file using ASCII armor (suitable for copying and pasting a message in text format)<br />
* Use {{ic|-R ''user-id''}} or {{ic|--hidden-recipient ''user-id''}} instead of {{ic|-r}} to not put the recipient key IDs in the encrypted message. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis.<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can use gnupg to encrypt your sensitive documents by using your own user-id as recipient or by using the {{ic|--default-recipient-self}} flag instead; however, you can only do this one file at a time, although you can always tarball various files and then encrypt the tarball. See also [[Disk encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
==== Symmetric ====<br />
Symmetric encryption does not require the generation of a key pair and can be used to simply encrypt data with a passphrase. Simply use {{ic|--symmetric}} or {{ic|-c}} to perform symmetic encryption:<br />
<br />
$ gpg -c ''doc''<br />
<br />
The following example:<br />
<br />
* Encrypts {{ic|''doc''}} with a symmetric cipher using a passphrase<br />
* Uses the AES-256 cipher algorithm to encrypt the passphrase<br />
* Uses the SHA-512 digest algorithm to mangle the passphrase<br />
* Mangles the passphrase for 65536 iterations<br />
<br />
$ gpg -c --s2k-cipher-algo AES256 --s2k-digest-algo SHA512 --s2k-count 65536 ''doc''<br />
<br />
To decrypt a symmetrically encrypted {{ic|''doc''.gpg}} using a passphrase and output decrypted contents into the same directory as {{ic|''doc''}} do:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor ''<user-id>'' > ''privkey.asc''<br />
<br />
Note that ''gpg'' release 2.1 changed default behaviour so that the above command enforces a passphrase protection, even if you deliberately chose not to use one on key creation. This is because otherwise anyone who gains access to the above exported file would be able to encrypt and sign documents as if they were you ''without'' needing to know your passphrase. <br />
<br />
{{Warning|The passphrase is usually the weakest link in protecting your secret key. Place the private key in a safe place on a different system/device, such as a locked container or encrypted drive. It is the only safety you have to regain control to your keyring in case of, for example, a drive failure, theft or worse.}}<br />
<br />
To import the backup of your private key:<br />
$ gpg --import ''privkey.asc''<br />
<br />
=== Edit your key ===<br />
<br />
Running the {{ic|gpg --edit-key ''<user-id>''}} command will present a menu which enables you to do most of your key management related tasks.<br />
<br />
Some useful commands in the edit key sub menu:<br />
> passwd # change the passphrase<br />
> clean # compact any user ID that is no longer usable (e.g revoked or expired)<br />
> revkey # revoke a key<br />
> addkey # add a subkey to this key<br />
> expire # change the key expiration time<br />
<br />
Type {{ic|help}} in the edit key sub menu for more commands.<br />
<br />
{{Tip|If you have multiple email accounts you can add each one of them as an identity, using {{ic|adduid}} command. You can then set your favourite one as {{ic|primary}}.}}<br />
<br />
=== Exporting subkey ===<br />
<br />
If you plan to use the same key across multiple devices, you may want to strip out your master key and only keep the bare minimum encryption subkey on less secure systems.<br />
<br />
First, find out which subkey you want to export.<br />
<br />
$ gpg -K<br />
<br />
Select only that subkey to export.<br />
<br />
$ gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.gpg<br />
<br />
{{Warning|If you forget to add the !, all of your subkeys will be exported.}}<br />
<br />
At this point you could stop, but it is most likely a good idea to change the passphrase as well. Import the key into a temporary folder. <br />
<br />
$ gpg --homedir /tmp/gpg --import /tmp/subkey.gpg<br />
$ gpg --homedir /tmp/gpg --edit-key ''<user-id>''<br />
> passwd<br />
> save<br />
$ gpg --homedir /tmp/gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.altpass.gpg<br />
<br />
{{Note|You will get a warning that the master key was not available and the password was not changed, but that can safely be ignored as the subkey password was.}}<br />
<br />
At this point, you can now use {{ic|/tmp/subkey.altpass.gpg}} on your other devices.<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
If you have set your subkeys to expire after a set time, you can create new ones. Do this a few weeks in advance to allow others to update their keyring.<br />
<br />
{{Note|You do not need to create a new key simply because it is expired. You can extend the expiration date.}}<br />
<br />
Create new subkey (repeat for both signing and encrypting key)<br />
<br />
$ gpg --edit-key ''<user-id>''<br />
> addkey<br />
<br />
And answer the following questions it asks (see [[#Create key pair]] for suggested settings).<br />
<br />
Save changes<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver pgp.mit.edu --send-keys ''<user-id>''<br />
<br />
{{Note|Revoking expired subkeys is unnecessary and arguably bad form. If you are constantly revoking keys, it may cause others to lack confidence in you.}}<br />
<br />
== Signatures ==<br />
<br />
Signatures certify and timestamp documents. If the document is modified, verification of the signature will fail. Unlike encryption which uses public keys to encrypt a document, signatures are created with the user's private key. The recipient of a signed document then verifies the signature using the sender's public key.<br />
<br />
=== Create a signature ===<br />
<br />
==== Sign a file ====<br />
<br />
To sign a file use the {{ic|--sign}} or {{ic|-s}} flag:<br />
<br />
$ gpg --output ''doc''.sig --sign ''doc''<br />
<br />
{{ic|''doc''.sig}} contains both the compressed content of the original file {{ic|''doc''}} and the signature in a binary format, but the file is not encrypted. However, you can combine signing with [[#Encrypt and decrypt|encrypting]].<br />
<br />
==== Clearsign a file or message ====<br />
<br />
To sign a file without compressing it into binary format use:<br />
<br />
$ gpg --output ''doc''.sig --clearsign ''doc''<br />
<br />
Here both the content of the original file {{ic|''doc''}} and the signature are stored in human-readable form in {{ic|''doc''.sig}}.<br />
<br />
==== Make a detached signature ====<br />
<br />
To create a separate signature file to be distributed separately from the document or file itself, use the {{ic|--detach-sig}} flag:<br />
<br />
$ gpg --output ''doc''.sig --detach-sig ''doc''<br />
<br />
Here the signature is stored in {{ic|''doc''.sig}}, but the contents of {{ic|''doc''}} are not stored in it. This method is often used in distributing software projects to allow users to verify that the program has not been modified by a third party.<br />
<br />
=== Verify a signature ===<br />
<br />
To verify a signature use the {{ic|--verify}} flag:<br />
<br />
$ gpg --verify ''doc''.sig<br />
<br />
where {{ic|''doc''.sig}} is the signed file containing the signature you wish to verify.<br />
<br />
If you are verifying a detached signature, both the signed data file and the signature file must be present when verifying. For example, to verify Arch Linux's latest iso you would do:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig<br />
<br />
where {{ic|archlinux-''version''.iso}} must be located in the same directory.<br />
<br />
You can also specify the signed data file with a second argument:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig ''/path/to/''archlinux-''version''.iso<br />
<br />
If a file as been encrypted in addition to being signed, simply [[#Encrypt and decrypt|decrypt]] the file and its signature will also be verified.<br />
<br />
== gpg-agent ==<br />
<br />
''gpg-agent'' is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client.<br />
<br />
Starting with GnuPG 2.1.0 the use of ''gpg-agent'' is required. ''gpg-agent'' is started on-demand by the GnuPG tools, so there is usually no reason to start it manually.<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{ic|man gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|To cache your passphrase for the whole session, please run the following command:<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXXX<br />
<br />
where XXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. Passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
}}<br />
<br />
=== Reload the agent ===<br />
<br />
After changing the configuration, reload the agent using ''gpg-connect-agent'':<br />
<br />
$ gpg-connect-agent reloadagent /bye<br />
<br />
The command should print {{ic|OK}}.<br />
<br />
=== pinentry ===<br />
<br />
Finally, the agent needs to know how to ask the user for the password. This can be set in the gpg-agent configuration file.<br />
<br />
The default uses a gtk dialog. There are other options - see {{ic|info pinentry}}. To change the dialog implementation set {{ic|pinentry-program}} configuration option:<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
<br />
# PIN entry program<br />
# pinentry-program /usr/bin/pinentry-curses<br />
# pinentry-program /usr/bin/pinentry-qt<br />
# pinentry-program /usr/bin/pinentry-kwallet<br />
<br />
pinentry-program /usr/bin/pinentry-gtk-2<br />
}}<br />
<br />
{{Tip|For using {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{AUR|kwalletcli}} package.}}<br />
<br />
After making this change, reload the gpg-agent.<br />
<br />
=== Start gpg-agent with systemd user ===<br />
<br />
{{Expansion|Add {{ic|gpg-agent-extra.socket}} and {{ic|gpg-agent-browser.socket}}.}}<br />
<br />
{{Pkg|gnupg}} comes with systemd user sockets which are enabled by default. These sockets are {{ic|gpg-agent.socket}}, {{ic|gpg-agent-extra.socket}}, {{ic|gpg-agent-browser.socket}}, {{ic|gpg-agent-ssh.socket}}, and {{ic|dirmngr.socket}}.<br />
<br />
The {{ic|gpg-agent.socket}} unit will start the service on-demand and manage the lifetime. The {{ic|dirmngr.socket}} should usually be enabled too, which is a daemon spawned to handle keyserver requests.<br />
<br />
The {{ic|gpg-agent-ssh.socket}} can be used to cache ssh keys. To use {{ic|gpg-agent-ssh.socket}}, {{ic|SSH_AUTH_SOCK}} environment variable needs to be [[#SSH agent|configured]] to point at {{ic|/run/user/${UID}/gnupg/S.gpg-agent.ssh}}. When {{ic|ssh-add}} is used, {{ic|gpg-agent}} will cache the ssh keys.<br />
<br />
=== Unattended passphrase ===<br />
<br />
Starting with GnuPG 2.1.0 the use of gpg-agent and pinentry is required, which may break backwards compatibility for passphrases piped in from STDIN using the {{ic|--passphrase-fd 0}} commandline option. In order to have the same type of functionality as the older releases two things must be done:<br />
<br />
First, edit the gpg-agent configuration to allow ''loopback'' pinentry mode:<br />
<br />
{{hc|1=~/.gnupg/gpg-agent.conf|2=<br />
allow-loopback-pinentry<br />
}}<br />
<br />
Restart the gpg-agent process if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|1=~/.gnupg/gpg.conf|2=<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://bugs.g10code.com/gnupg/issue1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your [[SSH keys]]. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
To start using GnuPG agent for your SSH keys, enable SSH support in the {{ic|~/.gnupg/gpg-agent.conf}} file:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
enable-ssh-support<br />
}}<br />
<br />
Next, make sure that ''gpg-agent'' is always started. Either follow [[#Start gpg-agent with systemd user]], or add the following to your {{ic|.bashrc}} file:<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Start the gpg-agent if not already running<br />
if ! pgrep -x -u "${USER}" gpg-agent >/dev/null 2>&1; then<br />
gpg-connect-agent /bye >/dev/null 2>&1<br />
fi<br />
</nowiki>}}<br />
<br />
Then set {{ic|SSH_AUTH_SOCK}} so that SSH will use ''gpg-agent'' instead of ''ssh-agent''. To make sure each process can find your ''gpg-agent'' instance regardless of e.g. the type of shell it is child of use [[Environment_variables#Using_pam_env|pam_env]].<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
Alternatively, depend on Bash:<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Set SSH to use gpg-agent<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="/run/user/$UID/gnupg/S.gpg-agent.ssh"<br />
fi<br />
</nowiki>}}<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* If you use non-default GnuPG [[#Directory location]], run {{ic|gpgconf --create-socketdir}} to create a socket directory under {{ic|/run/user/$UID/gnupg/}}. Otherwise the socket will be placed in the GnuPG home directory.<br />
* The test involving the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable is for the case where the agent is started as {{ic|gpg-agent --daemon /bin/sh}}, in which case the shell inherits the {{ic|SSH_AUTH_SOCK}} variable from the parent, ''gpg-agent'' [http://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307].<br />
}}<br />
<br />
Also set the GPG_TTY and refresh the TTY in case user has switched into an X session as stated in {{ic|man gpg-agent}}. For example:<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Set GPG TTY<br />
export GPG_TTY=$(tty)<br />
<br />
# Refresh gpg-agent tty in case user switches into an X session<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
</nowiki>}}<br />
<br />
Once ''gpg-agent'' is running you can use ''ssh-add'' to approve keys, following the same steps as for [[SSH keys#ssh-agent|ssh-agent]]. The list of approved keys is stored in the {{ic|~/.gnupg/sshcontrol}} file. Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. You can control passphrase caching in the {{ic|~/.gnupg/gpg-agent.conf}} file. The following example would have ''gpg-agent'' cache your keys for 3 hours:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl-ssh 10800<br />
max-cache-ttl-ssh 10800<br />
}}<br />
<br />
== Smartcards ==<br />
<br />
GnuPG uses ''scdaemon'' as an interface to your smartcard reader, please refer to the [[man page]] for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smarcard readers the optional dependency {{Pkg|libusb-compat}} have to be installed}}<br />
<br />
If you do not plan to use other cards but those based on GnuPG, you should check the {{Ic|reader-port}} parameter in {{ic|~/.gnupg/scdaemon.conf}}. The value '0' refers to the first available serial port reader and a value of '32768' (default) refers to the first USB reader.<br />
<br />
=== GnuPG with pcscd (PCSC Lite) ===<br />
<br />
{{Note|{{Pkg|pcsclite}} and {{Pkg|ccid}} have to be installed, and the contained [[systemd#Using units|systemd]] service {{ic|pcscd.service}} has to be running, or the socket {{ic|pcscd.socket}} has to be listening.}}<br />
<br />
pcscd is a daemon which handles access to smartcard (SCard API). If GnuPG's scdaemon fails to connect the smartcard directly (e.g. by using its integrated CCID support), it will fallback and try to find a smartcard using the PCSC Lite driver.<br />
<br />
==== Always use pcscd ====<br />
<br />
If you are using any smartcard with an opensc driver (e.g.: ID cards from some countries) you should pay some attention to GnuPG configuration. Out of the box you might receive a message like this when using {{Ic|gpg --card-status}}<br />
<br />
gpg: selecting openpgp failed: ec=6.108<br />
<br />
By default, scdaemon will try to connect directly to the device. This connection will fail if the reader is being used by another process. For example: the pcscd daemon used by OpenSC. To cope with this situation we should use the same underlying driver as opensc so they can work well together. In order to point scdaemon to use pcscd you should remove {{Ic|reader-port}} from {{ic|~/.gnupg/scdaemon.conf}}, specify the location to {{ic|libpcsclite.so}} library and disable ccid so we make sure that we use pcscd:<br />
<br />
{{hc|~/.gnupg/scdaemon.conf|<nowiki><br />
pcsc-driver /usr/lib/libpcsclite.so<br />
card-timeout 5<br />
disable-ccid<br />
</nowiki>}}<br />
<br />
Please check {{Ic|man scdaemon}} if you do not use OpenSC.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Different algorithm ===<br />
<br />
You may want to use stronger algorithms:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
...<br />
<br />
personal-digest-preferences SHA512<br />
cert-digest-algo SHA512<br />
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed<br />
personal-cipher-preferences TWOFISH CAMELLIA256 AES 3DES<br />
}}<br />
<br />
In the latest version of GnuPG, the default algorithms used are SHA256 and AES, both of which are secure enough for most people. However, if you are using a version of GnuPG older than 2.1, or if you want an even higher level of security, then you should follow the above step.<br />
<br />
=== Encrypt a password ===<br />
{{Tip|[[pass]] automates this process.}}<br />
<br />
It can be useful to encrypt some password, so it will not be written in clear on a configuration file. A good example is your email password.<br />
<br />
First create a file with your password. You '''need''' to leave '''one''' empty line after the password, otherwise gpg will return an error message when evaluating the file.<br />
<br />
Then run:<br />
<br />
$ gpg -e -a -r ''<user-id>'' ''your_password_file''<br />
<br />
{{ic|-e}} is for encrypt, {{ic|-a}} for armor (ASCII output), {{ic|-r}} for recipient user ID.<br />
<br />
You will be left with a new {{ic|''your_password_file''.asc}} file.<br />
<br />
=== Revoking a key ===<br />
<br />
{{Warning|<br />
*Anybody having access to your revocation certificate can revoke your key, rendering it useless.<br />
*Key revocation should only be performed if your key is compromised or lost, or you forget your passphrase.}}<br />
<br />
Revocation certificates are automatically generated for newly generated keys, although one can be generated manually by the user later. These are located at {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
<br />
To revoke your key, simply import the revocation certificate:<br />
<br />
$ gpg --import ''<fingerprint>''.rev<br />
<br />
Now update the keyserver:<br />
<br />
$ gpg --keyserver subkeys.pgp.net --send-keys ''<userid>''<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on first use|Trust on first use]] by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''<user-id>''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''<user-id>''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses the [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together at a physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-svn}}.<br />
<br />
To send the signatures to their owners you need a working [[Wikipedia:Message transfer agent|MTA]]. If you do not have already one, install [[msmtp]].<br />
<br />
=== Always show long ID's and fingerprints ===<br />
<br />
To always show long key ID's add {{ic|keyid-format 0xlong}} to your configuration file. To always show full fingerprints of keys, add {{ic|with-fingerprint}} to your configuration file.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Not enough random bytes available ===<br />
When generating a key, gpg can run into this error:<br />
Not enough random bytes available. Please do some other work to give the OS a chance to collect more entropy!<br />
To check the available entropy, check the kernel parameters:<br />
cat /proc/sys/kernel/random/entropy_avail<br />
A healthy Linux system with a lot of entropy available will have return close to the full 4,096 bits of entropy. If the value returned is less than 200, the system is running low on entropy. <br />
<br />
To solve it, remember you do not often need to create keys and best just do what the message suggests (e.g. create disk activity, move the mouse, edit the wiki - all will create entropy). If that does not help, check which service is using up the entropy and consider stopping it for the time. If that is no alternative, see [[Random number generation#Alternatives]].<br />
<br />
=== su ===<br />
<br />
When using {{Ic|pinentry}}, you must have the proper permissions of the terminal device (e.g. {{Ic|/dev/tty1}}) in use. However, with ''su'' (or ''sudo''), the ownership stays with the original user, not the new one. This means that pinentry will fail, even as root. The fix is to change the permissions of the device at some point before the use of pinentry (i.e. using gpg with an agent). If doing gpg as root, simply change the ownership to root right before using gpg:<br />
<br />
# chown root /dev/ttyN # where N is the current tty<br />
<br />
and then change it back after using gpg the first time. The equivalent is likely to be true with {{Ic|/dev/pts/}}.<br />
<br />
{{Note|The owner of tty ''must'' match with the user for which pinentry is running. Being part of the group {{Ic|tty}} '''is not''' enough.}}<br />
<br />
{{Tip|If you run gpg with {{ic|script}} it will use a new tty with the correct ownership:<br />
<br />
# script -q -c "gpg --gen-key" /dev/null<br />
}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
The default pinentry program is pinentry-gtk-2, which needs a DBus session bus to run properly. See [[General troubleshooting#Session permissions]] for details.<br />
<br />
Alternatively, you can use {{ic|pinentry-qt}}. See [[#pinentry]].<br />
<br />
=== KGpg configuration permissions ===<br />
<br />
There have been issues with {{Pkg|kdeutils-kgpg}}{{Broken package link|replaced by {{Pkg|kgpg}}}} being able to access the {{ic|~/.gnupg/}} options. One issue might be a result of a deprecated ''options'' file, see the [https://bugs.kde.org/show_bug.cgi?id=290221 bug] report.<br />
<br />
Another user reported that ''KGpg'' failed to start until the {{ic|~/.gnupg}} folder is set to {{ic|drwxr-xr-x}} permissions. If you require this work-around, ensure that the directory contents retain {{ic|-rw-------}} permissions! Further, report it as a bug to the [https://bugs.kde.org/buglist.cgi?quicksearch=kgpg developers].<br />
<br />
=== Conflicts between gnome-keyring and gpg-agent ===<br />
<br />
{{Remove|1=Useless statement for an [https://wiki.archlinux.org/index.php?title=GnuPG&diff=399866&oldid=399865 old version] of GnuPG.}}<br />
<br />
Although the Gnome keyring implements a GPG agent component, GnuPG ignores the {{ic|GPG_AGENT_INFO}} environment variable, so that Gnome keyring can no longer be used as a GPG agent.<br />
<br />
{{Move|#pinentry|Configuration does not belong under troubleshooting.}}<br />
<br />
However, the package {{Pkg|pinentry}} provides the {{Ic|pinentry-gnome3}} program. You may set the following option in your {{Ic|gpg-agent.conf}} file<br />
pinentry-program /usr/bin/pinentry-gnome3<br />
in order to make use of that pinentry program.<br />
<br />
All pinentry programs can be configured to optionally save a passphrase with libsecret. For example, when the user is asked for a passphrase via {{Ic|pinentry-gnome3}}, a checkbox is shown whether to save the passphrase using a password manager.<br />
<br />
=== GNOME on Wayland overrides SSH agent socket ===<br />
<br />
For Wayland sessions, {{Ic|gnome-session}} sets {{Ic|SSH_AUTH_SOCK}} to the standard gnome-keyring socket, {{Ic|$XDG_RUNTIME_DIR/keyring/ssh}}. This overrides any value set in {{Ic|~/.pam_environmment}} or systemd unit files.<br />
<br />
To disable this behavior, set the {{Ic|GSM_SKIP_AGENT_WORKAROUND}} variable:<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
GSM_SKIP_SSH_AGENT_WORKAROUND DEFAULT="true"<br />
}}<br />
<br />
=== mutt and gpg ===<br />
<br />
To be asked for your GnuPG password only once per session, see [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread].<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. Basically, it says that there is a bug with keys in the old {{ic|pubring.gpg}} and {{ic|secring.gpg}} files, which have now been superseded by the new {{ic|pubring.kbx}} file and the {{ic|private-keys-v1.d/}} subdirectory and files. Your missing keys can be recovered with the following commnads:<br />
<br />
$ cd<br />
$ cp -r .gnupg gnupgOLD<br />
$ gpg --export-ownertrust > otrust.txt<br />
$ gpg --import .gnupg/pubring.gpg<br />
$ gpg --import-ownertrust otrust.txt<br />
$ gpg --list-keys<br />
<br />
=== gpg hanged for all keyservers (when trying to receive keys) ===<br />
<br />
If gpg hanged with a certain keyserver when trying to receive keys, you might need to kill dirmngr in order to get access to other keyservers which are actually working, otherwise it might keeping hanging for all of them.<br />
<br />
=== Smartcard not detected ===<br />
<br />
Your user might not have the permission to access the smartcard which results in a {{ic|card error}} to be thrown, even though the card is correctly set up and inserted.<br />
<br />
One possible solution is to add a new group {{ic|scard}} including the users who need access to the smartcard.<br />
<br />
Then use an [[Udev#Writing_udev_rules|udev]] rule, similar to the following:<br />
{{hc|/etc/udev/rules.d/71-gnupg-ccid.rules|<nowiki><br />
ACTION=="add", SUBSYSTEM=="usb", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0116|0111", MODE="660", GROUP="scard"<br />
</nowiki>}}<br />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<br />
* [https://tools.ietf.org/html/rfc4880 RFC4880 "OpenPGP Message Format"]<br />
* [https://fedoraproject.org/wiki/Creating_GPG_Keys Creating GPG Keys (Fedora)]<br />
* [https://wiki.debian.org/Subkeys OpenPGP subkeys in Debian]<br />
* [https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/ A more comprehensive gpg Tutorial]<br />
* [https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]<br />
* [https://github.com/ioerror/torbirdy/blob/master/gpg.conf Torbirdy gpg.conf]<br />
* [https://www.reddit.com/r/GPGpractice/ /r/GPGpractice - a subreddit to practice using GnuPG.]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=GnuPG&diff=479698GnuPG2017-06-12T18:00:43Z<p>Alive4ever: /* Start gpg-agent with systemd user */ Explaining recent gnupg change and gpg-agent-ssh.socket usage</p>
<hr />
<div>[[Category:Encryption]]<br />
[[es:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[zh-hans:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Disk encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related articles end}}<br />
<br />
According to the [http://www.gnupg.org official website]:<br />
<br />
:GnuPG is a complete and free implementation of the [http://openpgp.org/about/ OpenPGP] standard as defined by [https://tools.ietf.org/html/rfc4880 RFC4880] (also known as PGP). GnuPG allows you to encrypt and sign your data and communication. It features a versatile key management system as well as access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. Version 2 of GnuPG also provides support for S/MIME and Secure Shell (ssh).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|gnupg}} package.<br />
<br />
This will also install {{Pkg|pinentry}}, a collection of simple PIN or passphrase entry dialogs which GnuPG uses for passphrase entry. Which ''pinentry'' dialog is used is determined by the symbolic link {{ic|/usr/bin/pinentry}}, which by default points to {{ic|/usr/bin/pinentry-gtk-2}}.<br />
<br />
If you want to use a graphical frontend or program that integrates with GnuPG, see [[List of applications/Security#Encryption, signing, steganography]].<br />
<br />
== Configuration ==<br />
<br />
=== Directory location ===<br />
{{ic|$GNUPGHOME}} is used by GnuPG to point to the directory where its configuration files are stored. By default {{ic|$GNUPGHOME}} is not set and your {{ic|$HOME}} is used instead; thus, you will find a {{ic|~/.gnupg}} directory right after installation. <br />
<br />
To change the default location, either run gpg this way {{ic|$ gpg --homedir ''path/to/file''}} or set {{ic|GNUPGHOME}} in one of your regular [[startup files]].<br />
<br />
=== Configuration files ===<br />
<br />
The default configuration files are {{ic|~/.gnupg/gpg.conf}} and {{ic|~/.gnupg/dirmngr.conf}}. <br />
<br />
By default, the gnupg directory has its [[permissions]] set to {{ic|700}} and the files it contains have their permissions set to {{ic|600}}. Only the owner of the directory has permission to read, write, and access the files. This is for security purposes and should not be changed. In case this directory or any file inside it does not follow this security measure, you will get warnings about unsafe file and home directory permissions.<br />
<br />
Append to these files any long options you want. Do not write the two dashes, but simply the name of the option and required arguments. You will find skeleton files in {{ic|/usr/share/gnupg}}. These files are copied to {{ic|~/.gnupg}} the first time gpg is run if they do not exist there. Other examples are found in [[#See also]].<br />
<br />
Additionally, [[pacman]] uses a different set of configuration files for package signature verification. See [[Pacman/Package signing]] for details.<br />
<br />
=== Default options for new users ===<br />
<br />
If you want to setup some default options for new users, put configuration files in {{ic|/etc/skel/.gnupg/}}. When the new user is added in system, files from here will be copied to its GnuPG home directory. There is also a simple script called ''addgnupghome'' which you can use to create new GnuPG home directories for existing users:<br />
<br />
# addgnupghome user1 user2<br />
<br />
This will add the respective {{ic|/home/user1/.gnupg}} and {{ic|/home/user2/.gnupg}} and copy the files from the skeleton directory to it. Users with existing GnuPG home directory are simply skipped.<br />
<br />
== Usage ==<br />
<br />
{{Note|Whenever a ''{{ic|user-id}}'' is required in a command, it can be specified with your key ID, fingerprint, a part of your name or email address, etc. GnuPG is flexible on this.<br />
}}<br />
<br />
=== Create key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
{{Tip|Use the {{ic|--expert}} option for getting alternative ciphers like [[wikipedia:Elliptic_curve_cryptography|ECC]].}}<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* the RSA (sign only) and a RSA (encrypt only) key.<br />
* a keysize of the default value (2048). A larger keysize of 4096 "gives us almost nothing, while costing us quite a lot"[https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096].<br />
* an expiration date. A period of a year is good enough for the average user. This way even if access is lost to the keyring, it will allow others to know that it is no longer valid. Later, if necessary, the expiration date can be extended without having to re-issue a new key.<br />
* your name and email address. You can add multiple identities to the same key later (''e.g.'', if you have multiple email addresses you want to associate with this key).<br />
* ''no'' optional comment. Since the semantics of the comment field are [https://lists.gnupg.org/pipermail/gnupg-devel/2015-July/030150.html not well-defined], it has limited value for identification.<br />
* [[Security#Choosing_secure_passwords|a secure passphrase]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
gpg's main usage is to ensure confidentiality of exchanged messages via public-key cryptography. With it each user distributes the public key of their keyring, which can be be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[w:Public-key cryptography]] for examples about the message exchange. <br />
<br />
So, in order for others to send encrypted messages to you, they need your public key. <br />
<br />
To generate an ASCII version of your public key (''e.g.'' to distribute it by e-mail):<br />
<br />
$ gpg --output ''public.key'' --armor --export ''user-id'' <br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public.key''}} to your public key ring:<br />
<br />
$ gpg --import ''public.key''<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
=== Use a keyserver ===<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve your key without having to contact you directly:<br />
<br />
$ gpg --send-keys ''user-id''<br />
<br />
To find out details of a key on the keyserver, without importing it, do:<br />
<br />
$ gpg --search-keys ''user-id''<br />
<br />
To import a key from a key server:<br />
<br />
$ gpg --recv-keys ''key-id''<br />
<br />
{{Warning|<br />
* You should verify the authenticity of the retrieved public key by comparing its fingerprint with one that the owner published on an independent source(s) (i.e., contacting the person directly). See [[Wikipedia:Public key fingerprint]] for more information.<br />
* Using a short ID may encounter collisions. All keys will be imported that have the short ID. To avoid this, use the full fingerprint or long key ID when receiving a key.[https://lkml.org/lkml/2016/8/15/445]}}<br />
<br />
{{Tip|<br />
* Adding {{ic|keyserver-options auto-key-retrieve}} to {{ic|gpg.conf}} will automatically fetch keys from the key server as needed. <br />
* An alternative key server is {{ic|pool.sks-keyservers.net}} and can be specified with {{ic|keyserver}} in {{ic|dirmngr.conf}}; see also [[wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
* If your network blocks ports used for hkp/hkps, you may need to specify port 80, i.e. {{ic|pool.sks-keyservers.net:80}}<br />
* You can connect to the keyserver over [[Tor]] using {{ic|--use-tor}}. See this [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html GnuPG blog post] for more information.<br />
* You can connect to a keyserver using a proxy by setting the {{ic|http_proxy}} environment variable and setting {{ic|honor-http-proxy}} in {{ic|dirmngr.conf}}. Alternatively, set {{ic|http-proxy ''host[:port]''}} in {{ic|dirmngr.conf}}, overriding the {{ic|http_proxy}} environment variable.<br />
* If you wish to import a key ID to install a specific Arch Linux package, see [[pacman/Package signing#Managing the keyring]] and [[Makepkg#Signature checking]].}}<br />
<br />
=== Encrypt and decrypt ===<br />
<br />
==== Asymmetric ====<br />
You need to [[#Import a public key]] of a user before encrypting (options {{ic|--encrypt}} or {{ic|-e}}) a file or message to that recipient (options {{ic|--recipient}} or {{ic|-r}}). Additionally you need to [[#Create key pair]] if you have not already done so.<br />
<br />
To encrypt a file with the name ''doc'', use:<br />
<br />
$ gpg --recipient ''user-id'' --encrypt ''doc''<br />
<br />
To decrypt (option {{ic|--decrypt}} or {{ic|-d}}) a file with the name ''doc''.gpg encrypted with your public key, use:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
''gpg'' will prompt you for your passphrase and then decrypt and write the data from ''doc''.gpg to ''doc''. If you omit the {{ic|-o}} ({{ic|--output}}) option, ''gpg'' will write the decrypted data to stdout.<br />
<br />
{{Tip|<br />
* Add {{ic|--armor}} to encrypt a file using ASCII armor (suitable for copying and pasting a message in text format)<br />
* Use {{ic|-R ''user-id''}} or {{ic|--hidden-recipient ''user-id''}} instead of {{ic|-r}} to not put the recipient key IDs in the encrypted message. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis.<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can use gnupg to encrypt your sensitive documents by using your own user-id as recipient or by using the {{ic|--default-recipient-self}} flag instead; however, you can only do this one file at a time, although you can always tarball various files and then encrypt the tarball. See also [[Disk encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
==== Symmetric ====<br />
Symmetric encryption does not require the generation of a key pair and can be used to simply encrypt data with a passphrase. Simply use {{ic|--symmetric}} or {{ic|-c}} to perform symmetic encryption:<br />
<br />
$ gpg -c ''doc''<br />
<br />
The following example:<br />
<br />
* Encrypts {{ic|''doc''}} with a symmetric cipher using a passphrase<br />
* Uses the AES-256 cipher algorithm to encrypt the passphrase<br />
* Uses the SHA-512 digest algorithm to mangle the passphrase<br />
* Mangles the passphrase for 65536 iterations<br />
<br />
$ gpg -c --s2k-cipher-algo AES256 --s2k-digest-algo SHA512 --s2k-count 65536 ''doc''<br />
<br />
To decrypt a symmetrically encrypted {{ic|''doc''.gpg}} using a passphrase and output decrypted contents into the same directory as {{ic|''doc''}} do:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor ''<user-id>'' > ''privkey.asc''<br />
<br />
Note that ''gpg'' release 2.1 changed default behaviour so that the above command enforces a passphrase protection, even if you deliberately chose not to use one on key creation. This is because otherwise anyone who gains access to the above exported file would be able to encrypt and sign documents as if they were you ''without'' needing to know your passphrase. <br />
<br />
{{Warning|The passphrase is usually the weakest link in protecting your secret key. Place the private key in a safe place on a different system/device, such as a locked container or encrypted drive. It is the only safety you have to regain control to your keyring in case of, for example, a drive failure, theft or worse.}}<br />
<br />
To import the backup of your private key:<br />
$ gpg --import ''privkey.asc''<br />
<br />
=== Edit your key ===<br />
<br />
Running the {{ic|gpg --edit-key ''<user-id>''}} command will present a menu which enables you to do most of your key management related tasks.<br />
<br />
Some useful commands in the edit key sub menu:<br />
> passwd # change the passphrase<br />
> clean # compact any user ID that is no longer usable (e.g revoked or expired)<br />
> revkey # revoke a key<br />
> addkey # add a subkey to this key<br />
> expire # change the key expiration time<br />
<br />
Type {{ic|help}} in the edit key sub menu for more commands.<br />
<br />
{{Tip|If you have multiple email accounts you can add each one of them as an identity, using {{ic|adduid}} command. You can then set your favourite one as {{ic|primary}}.}}<br />
<br />
=== Exporting subkey ===<br />
<br />
If you plan to use the same key across multiple devices, you may want to strip out your master key and only keep the bare minimum encryption subkey on less secure systems.<br />
<br />
First, find out which subkey you want to export.<br />
<br />
$ gpg -K<br />
<br />
Select only that subkey to export.<br />
<br />
$ gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.gpg<br />
<br />
{{Warning|If you forget to add the !, all of your subkeys will be exported.}}<br />
<br />
At this point you could stop, but it is most likely a good idea to change the passphrase as well. Import the key into a temporary folder. <br />
<br />
$ gpg --homedir /tmp/gpg --import /tmp/subkey.gpg<br />
$ gpg --homedir /tmp/gpg --edit-key ''<user-id>''<br />
> passwd<br />
> save<br />
$ gpg --homedir /tmp/gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.altpass.gpg<br />
<br />
{{Note|You will get a warning that the master key was not available and the password was not changed, but that can safely be ignored as the subkey password was.}}<br />
<br />
At this point, you can now use {{ic|/tmp/subkey.altpass.gpg}} on your other devices.<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
If you have set your subkeys to expire after a set time, you can create new ones. Do this a few weeks in advance to allow others to update their keyring.<br />
<br />
{{Note|You do not need to create a new key simply because it is expired. You can extend the expiration date.}}<br />
<br />
Create new subkey (repeat for both signing and encrypting key)<br />
<br />
$ gpg --edit-key ''<user-id>''<br />
> addkey<br />
<br />
And answer the following questions it asks (see [[#Create key pair]] for suggested settings).<br />
<br />
Save changes<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver pgp.mit.edu --send-keys ''<user-id>''<br />
<br />
{{Note|Revoking expired subkeys is unnecessary and arguably bad form. If you are constantly revoking keys, it may cause others to lack confidence in you.}}<br />
<br />
== Signatures ==<br />
<br />
Signatures certify and timestamp documents. If the document is modified, verification of the signature will fail. Unlike encryption which uses public keys to encrypt a document, signatures are created with the user's private key. The recipient of a signed document then verifies the signature using the sender's public key.<br />
<br />
=== Create a signature ===<br />
<br />
==== Sign a file ====<br />
<br />
To sign a file use the {{ic|--sign}} or {{ic|-s}} flag:<br />
<br />
$ gpg --output ''doc''.sig --sign ''doc''<br />
<br />
{{ic|''doc''.sig}} contains both the compressed content of the original file {{ic|''doc''}} and the signature in a binary format, but the file is not encrypted. However, you can combine signing with [[#Encrypt and decrypt|encrypting]].<br />
<br />
==== Clearsign a file or message ====<br />
<br />
To sign a file without compressing it into binary format use:<br />
<br />
$ gpg --output ''doc''.sig --clearsign ''doc''<br />
<br />
Here both the content of the original file {{ic|''doc''}} and the signature are stored in human-readable form in {{ic|''doc''.sig}}.<br />
<br />
==== Make a detached signature ====<br />
<br />
To create a separate signature file to be distributed separately from the document or file itself, use the {{ic|--detach-sig}} flag:<br />
<br />
$ gpg --output ''doc''.sig --detach-sig ''doc''<br />
<br />
Here the signature is stored in {{ic|''doc''.sig}}, but the contents of {{ic|''doc''}} are not stored in it. This method is often used in distributing software projects to allow users to verify that the program has not been modified by a third party.<br />
<br />
=== Verify a signature ===<br />
<br />
To verify a signature use the {{ic|--verify}} flag:<br />
<br />
$ gpg --verify ''doc''.sig<br />
<br />
where {{ic|''doc''.sig}} is the signed file containing the signature you wish to verify.<br />
<br />
If you are verifying a detached signature, both the signed data file and the signature file must be present when verifying. For example, to verify Arch Linux's latest iso you would do:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig<br />
<br />
where {{ic|archlinux-''version''.iso}} must be located in the same directory.<br />
<br />
You can also specify the signed data file with a second argument:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig ''/path/to/''archlinux-''version''.iso<br />
<br />
If a file as been encrypted in addition to being signed, simply [[#Encrypt and decrypt|decrypt]] the file and its signature will also be verified.<br />
<br />
== gpg-agent ==<br />
<br />
''gpg-agent'' is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client.<br />
<br />
Starting with GnuPG 2.1.0 the use of ''gpg-agent'' is required. ''gpg-agent'' is started on-demand by the GnuPG tools, so there is usually no reason to start it manually.<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{ic|man gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|To cache your passphrase for the whole session, please run the following command:<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXXX<br />
<br />
where XXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. Passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
}}<br />
<br />
=== Reload the agent ===<br />
<br />
After changing the configuration, reload the agent using ''gpg-connect-agent'':<br />
<br />
$ gpg-connect-agent reloadagent /bye<br />
<br />
The command should print {{ic|OK}}.<br />
<br />
=== pinentry ===<br />
<br />
Finally, the agent needs to know how to ask the user for the password. This can be set in the gpg-agent configuration file.<br />
<br />
The default uses a gtk dialog. There are other options - see {{ic|info pinentry}}. To change the dialog implementation set {{ic|pinentry-program}} configuration option:<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
<br />
# PIN entry program<br />
# pinentry-program /usr/bin/pinentry-curses<br />
# pinentry-program /usr/bin/pinentry-qt<br />
# pinentry-program /usr/bin/pinentry-kwallet<br />
<br />
pinentry-program /usr/bin/pinentry-gtk-2<br />
}}<br />
<br />
{{Tip|For using {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{AUR|kwalletcli}} package.}}<br />
<br />
After making this change, reload the gpg-agent.<br />
<br />
=== Start gpg-agent with systemd user ===<br />
<br />
{{Expansion|Add {{ic|gpg-agent-extra.socket}} and {{ic|gpg-agent-browser.socket}}.}}<br />
<br />
{{Pkg|gnupg}} comes with systemd user sockets which are enabled by default. These sockets are {{ic|gpg-agent.socket}}, {{ic|gpg-agent-extra.socket}}, {{ic|gpg-agent-browser.socket}}, {{ic|gpg-agent-ssh.socket}}, and {{ic|dirmngr.socket}}.<br />
<br />
The {{ic|gpg-agent.socket}} unit will start the service on-demand and manage the lifetime. The {{ic|dirmngr.socket}} should usually be enabled too, which is a daemon spawned to handle keyserver requests.<br />
<br />
The {{ic|gpg-agent-ssh.socket}} can be used to cache ssh keys. To use {{ic|gpg-agent-ssh.socket}}, {{ic|SSH_AUTH_SOCK}} environment variable needs to be [[#SSH Agent|configured]] to point at {{ic|/run/user/${UID}/gnupg/S.gpg-agent.ssh}}. When {{ic|ssh-add}} is used, {{ic|gpg-agent}} will cache the ssh keys.<br />
<br />
=== Unattended passphrase ===<br />
<br />
Starting with GnuPG 2.1.0 the use of gpg-agent and pinentry is required, which may break backwards compatibility for passphrases piped in from STDIN using the {{ic|--passphrase-fd 0}} commandline option. In order to have the same type of functionality as the older releases two things must be done:<br />
<br />
First, edit the gpg-agent configuration to allow ''loopback'' pinentry mode:<br />
<br />
{{hc|1=~/.gnupg/gpg-agent.conf|2=<br />
allow-loopback-pinentry<br />
}}<br />
<br />
Restart the gpg-agent process if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|1=~/.gnupg/gpg.conf|2=<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://bugs.g10code.com/gnupg/issue1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your [[SSH keys]]. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
To start using GnuPG agent for your SSH keys, enable SSH support in the {{ic|~/.gnupg/gpg-agent.conf}} file:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
enable-ssh-support<br />
}}<br />
<br />
Next, make sure that ''gpg-agent'' is always started. Either follow [[#Start gpg-agent with systemd user]], or add the following to your {{ic|.bashrc}} file:<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Start the gpg-agent if not already running<br />
if ! pgrep -x -u "${USER}" gpg-agent >/dev/null 2>&1; then<br />
gpg-connect-agent /bye >/dev/null 2>&1<br />
fi<br />
</nowiki>}}<br />
<br />
Then set {{ic|SSH_AUTH_SOCK}} so that SSH will use ''gpg-agent'' instead of ''ssh-agent''. To make sure each process can find your ''gpg-agent'' instance regardless of e.g. the type of shell it is child of use [[Environment_variables#Using_pam_env|pam_env]].<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
Alternatively, depend on Bash:<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Set SSH to use gpg-agent<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="/run/user/$UID/gnupg/S.gpg-agent.ssh"<br />
fi<br />
</nowiki>}}<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* If you use non-default GnuPG [[#Directory location]], run {{ic|gpgconf --create-socketdir}} to create a socket directory under {{ic|/run/user/$UID/gnupg/}}. Otherwise the socket will be placed in the GnuPG home directory.<br />
* The test involving the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable is for the case where the agent is started as {{ic|gpg-agent --daemon /bin/sh}}, in which case the shell inherits the {{ic|SSH_AUTH_SOCK}} variable from the parent, ''gpg-agent'' [http://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307].<br />
}}<br />
<br />
Also set the GPG_TTY and refresh the TTY in case user has switched into an X session as stated in {{ic|man gpg-agent}}. For example:<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Set GPG TTY<br />
export GPG_TTY=$(tty)<br />
<br />
# Refresh gpg-agent tty in case user switches into an X session<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
</nowiki>}}<br />
<br />
Once ''gpg-agent'' is running you can use ''ssh-add'' to approve keys, following the same steps as for [[SSH keys#ssh-agent|ssh-agent]]. The list of approved keys is stored in the {{ic|~/.gnupg/sshcontrol}} file. Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. You can control passphrase caching in the {{ic|~/.gnupg/gpg-agent.conf}} file. The following example would have ''gpg-agent'' cache your keys for 3 hours:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl-ssh 10800<br />
max-cache-ttl-ssh 10800<br />
}}<br />
<br />
== Smartcards ==<br />
<br />
GnuPG uses ''scdaemon'' as an interface to your smartcard reader, please refer to the [[man page]] for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smarcard readers the optional dependency {{Pkg|libusb-compat}} have to be installed}}<br />
<br />
If you do not plan to use other cards but those based on GnuPG, you should check the {{Ic|reader-port}} parameter in {{ic|~/.gnupg/scdaemon.conf}}. The value '0' refers to the first available serial port reader and a value of '32768' (default) refers to the first USB reader.<br />
<br />
=== GnuPG with pcscd (PCSC Lite) ===<br />
<br />
{{Note|{{Pkg|pcsclite}} and {{Pkg|ccid}} have to be installed, and the contained [[systemd#Using units|systemd]] service {{ic|pcscd.service}} has to be running, or the socket {{ic|pcscd.socket}} has to be listening.}}<br />
<br />
pcscd is a daemon which handles access to smartcard (SCard API). If GnuPG's scdaemon fails to connect the smartcard directly (e.g. by using its integrated CCID support), it will fallback and try to find a smartcard using the PCSC Lite driver.<br />
<br />
==== Always use pcscd ====<br />
<br />
If you are using any smartcard with an opensc driver (e.g.: ID cards from some countries) you should pay some attention to GnuPG configuration. Out of the box you might receive a message like this when using {{Ic|gpg --card-status}}<br />
<br />
gpg: selecting openpgp failed: ec=6.108<br />
<br />
By default, scdaemon will try to connect directly to the device. This connection will fail if the reader is being used by another process. For example: the pcscd daemon used by OpenSC. To cope with this situation we should use the same underlying driver as opensc so they can work well together. In order to point scdaemon to use pcscd you should remove {{Ic|reader-port}} from {{ic|~/.gnupg/scdaemon.conf}}, specify the location to {{ic|libpcsclite.so}} library and disable ccid so we make sure that we use pcscd:<br />
<br />
{{hc|~/.gnupg/scdaemon.conf|<nowiki><br />
pcsc-driver /usr/lib/libpcsclite.so<br />
card-timeout 5<br />
disable-ccid<br />
</nowiki>}}<br />
<br />
Please check {{Ic|man scdaemon}} if you do not use OpenSC.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Different algorithm ===<br />
<br />
You may want to use stronger algorithms:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
...<br />
<br />
personal-digest-preferences SHA512<br />
cert-digest-algo SHA512<br />
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed<br />
personal-cipher-preferences TWOFISH CAMELLIA256 AES 3DES<br />
}}<br />
<br />
In the latest version of GnuPG, the default algorithms used are SHA256 and AES, both of which are secure enough for most people. However, if you are using a version of GnuPG older than 2.1, or if you want an even higher level of security, then you should follow the above step.<br />
<br />
=== Encrypt a password ===<br />
{{Tip|[[pass]] automates this process.}}<br />
<br />
It can be useful to encrypt some password, so it will not be written in clear on a configuration file. A good example is your email password.<br />
<br />
First create a file with your password. You '''need''' to leave '''one''' empty line after the password, otherwise gpg will return an error message when evaluating the file.<br />
<br />
Then run:<br />
<br />
$ gpg -e -a -r ''<user-id>'' ''your_password_file''<br />
<br />
{{ic|-e}} is for encrypt, {{ic|-a}} for armor (ASCII output), {{ic|-r}} for recipient user ID.<br />
<br />
You will be left with a new {{ic|''your_password_file''.asc}} file.<br />
<br />
=== Revoking a key ===<br />
<br />
{{Warning|<br />
*Anybody having access to your revocation certificate can revoke your key, rendering it useless.<br />
*Key revocation should only be performed if your key is compromised or lost, or you forget your passphrase.}}<br />
<br />
Revocation certificates are automatically generated for newly generated keys, although one can be generated manually by the user later. These are located at {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
<br />
To revoke your key, simply import the revocation certificate:<br />
<br />
$ gpg --import ''<fingerprint>''.rev<br />
<br />
Now update the keyserver:<br />
<br />
$ gpg --keyserver subkeys.pgp.net --send-keys ''<userid>''<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on first use|Trust on first use]] by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''<user-id>''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''<user-id>''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses the [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together at a physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-svn}}.<br />
<br />
To send the signatures to their owners you need a working [[Wikipedia:Message transfer agent|MTA]]. If you do not have already one, install [[msmtp]].<br />
<br />
=== Always show long ID's and fingerprints ===<br />
<br />
To always show long key ID's add {{ic|keyid-format 0xlong}} to your configuration file. To always show full fingerprints of keys, add {{ic|with-fingerprint}} to your configuration file.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Not enough random bytes available ===<br />
When generating a key, gpg can run into this error:<br />
Not enough random bytes available. Please do some other work to give the OS a chance to collect more entropy!<br />
To check the available entropy, check the kernel parameters:<br />
cat /proc/sys/kernel/random/entropy_avail<br />
A healthy Linux system with a lot of entropy available will have return close to the full 4,096 bits of entropy. If the value returned is less than 200, the system is running low on entropy. <br />
<br />
To solve it, remember you do not often need to create keys and best just do what the message suggests (e.g. create disk activity, move the mouse, edit the wiki - all will create entropy). If that does not help, check which service is using up the entropy and consider stopping it for the time. If that is no alternative, see [[Random number generation#Alternatives]].<br />
<br />
=== su ===<br />
<br />
When using {{Ic|pinentry}}, you must have the proper permissions of the terminal device (e.g. {{Ic|/dev/tty1}}) in use. However, with ''su'' (or ''sudo''), the ownership stays with the original user, not the new one. This means that pinentry will fail, even as root. The fix is to change the permissions of the device at some point before the use of pinentry (i.e. using gpg with an agent). If doing gpg as root, simply change the ownership to root right before using gpg:<br />
<br />
# chown root /dev/ttyN # where N is the current tty<br />
<br />
and then change it back after using gpg the first time. The equivalent is likely to be true with {{Ic|/dev/pts/}}.<br />
<br />
{{Note|The owner of tty ''must'' match with the user for which pinentry is running. Being part of the group {{Ic|tty}} '''is not''' enough.}}<br />
<br />
{{Tip|If you run gpg with {{ic|script}} it will use a new tty with the correct ownership:<br />
<br />
# script -q -c "gpg --gen-key" /dev/null<br />
}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
The default pinentry program is pinentry-gtk-2, which needs a DBus session bus to run properly. See [[General troubleshooting#Session permissions]] for details.<br />
<br />
Alternatively, you can use {{ic|pinentry-qt}}. See [[#pinentry]].<br />
<br />
=== KGpg configuration permissions ===<br />
<br />
There have been issues with {{Pkg|kdeutils-kgpg}}{{Broken package link|replaced by {{Pkg|kgpg}}}} being able to access the {{ic|~/.gnupg/}} options. One issue might be a result of a deprecated ''options'' file, see the [https://bugs.kde.org/show_bug.cgi?id=290221 bug] report.<br />
<br />
Another user reported that ''KGpg'' failed to start until the {{ic|~/.gnupg}} folder is set to {{ic|drwxr-xr-x}} permissions. If you require this work-around, ensure that the directory contents retain {{ic|-rw-------}} permissions! Further, report it as a bug to the [https://bugs.kde.org/buglist.cgi?quicksearch=kgpg developers].<br />
<br />
=== Conflicts between gnome-keyring and gpg-agent ===<br />
<br />
{{Remove|1=Useless statement for an [https://wiki.archlinux.org/index.php?title=GnuPG&diff=399866&oldid=399865 old version] of GnuPG.}}<br />
<br />
Although the Gnome keyring implements a GPG agent component, GnuPG ignores the {{ic|GPG_AGENT_INFO}} environment variable, so that Gnome keyring can no longer be used as a GPG agent.<br />
<br />
{{Move|#pinentry|Configuration does not belong under troubleshooting.}}<br />
<br />
However, the package {{Pkg|pinentry}} provides the {{Ic|pinentry-gnome3}} program. You may set the following option in your {{Ic|gpg-agent.conf}} file<br />
pinentry-program /usr/bin/pinentry-gnome3<br />
in order to make use of that pinentry program.<br />
<br />
All pinentry programs can be configured to optionally save a passphrase with libsecret. For example, when the user is asked for a passphrase via {{Ic|pinentry-gnome3}}, a checkbox is shown whether to save the passphrase using a password manager.<br />
<br />
=== GNOME on Wayland overrides SSH agent socket ===<br />
<br />
For Wayland sessions, {{Ic|gnome-session}} sets {{Ic|SSH_AUTH_SOCK}} to the standard gnome-keyring socket, {{Ic|$XDG_RUNTIME_DIR/keyring/ssh}}. This overrides any value set in {{Ic|~/.pam_environmment}} or systemd unit files.<br />
<br />
To disable this behavior, set the {{Ic|GSM_SKIP_AGENT_WORKAROUND}} variable:<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
GSM_SKIP_SSH_AGENT_WORKAROUND DEFAULT="true"<br />
}}<br />
<br />
=== mutt and gpg ===<br />
<br />
To be asked for your GnuPG password only once per session, see [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread].<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. Basically, it says that there is a bug with keys in the old {{ic|pubring.gpg}} and {{ic|secring.gpg}} files, which have now been superseded by the new {{ic|pubring.kbx}} file and the {{ic|private-keys-v1.d/}} subdirectory and files. Your missing keys can be recovered with the following commnads:<br />
<br />
$ cd<br />
$ cp -r .gnupg gnupgOLD<br />
$ gpg --export-ownertrust > otrust.txt<br />
$ gpg --import .gnupg/pubring.gpg<br />
$ gpg --import-ownertrust otrust.txt<br />
$ gpg --list-keys<br />
<br />
=== gpg hanged for all keyservers (when trying to receive keys) ===<br />
<br />
If gpg hanged with a certain keyserver when trying to receive keys, you might need to kill dirmngr in order to get access to other keyservers which are actually working, otherwise it might keeping hanging for all of them.<br />
<br />
=== Smartcard not detected ===<br />
<br />
Your user might not have the permission to access the smartcard which results in a {{ic|card error}} to be thrown, even though the card is correctly set up and inserted.<br />
<br />
One possible solution is to add a new group {{ic|scard}} including the users who need access to the smartcard.<br />
<br />
Then use an [[Udev#Writing_udev_rules|udev]] rule, similar to the following:<br />
{{hc|/etc/udev/rules.d/71-gnupg-ccid.rules|<nowiki><br />
ACTION=="add", SUBSYSTEM=="usb", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0116|0111", MODE="660", GROUP="scard"<br />
</nowiki>}}<br />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<br />
* [https://tools.ietf.org/html/rfc4880 RFC4880 "OpenPGP Message Format"]<br />
* [https://fedoraproject.org/wiki/Creating_GPG_Keys Creating GPG Keys (Fedora)]<br />
* [https://wiki.debian.org/Subkeys OpenPGP subkeys in Debian]<br />
* [https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/ A more comprehensive gpg Tutorial]<br />
* [https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]<br />
* [https://github.com/ioerror/torbirdy/blob/master/gpg.conf Torbirdy gpg.conf]<br />
* [https://www.reddit.com/r/GPGpractice/ /r/GPGpractice - a subreddit to practice using GnuPG.]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=Talk:Systemd/User&diff=473852Talk:Systemd/User2017-04-13T13:14:56Z<p>Alive4ever: /* Setting up DISPLAY variable for systemd-user unit under Wayland session */ Real use case when DISPLAY is needed</p>
<hr />
<div>== Setting Environment variables without autologin/user-session@.service ==<br />
<br />
If you're not using auto-login, specifically the user-session@service, the environment variable DBUS_SESSION_BUS_ADDRESS needs to exported to something like {{ic|export DBUS_SESSION_BUS_ADDRESS&#61;/run/user/$(id -u)/dbus/user_bus_socket}} before {{ic|systemd --user}}. Otherwise, an error shows up in journalctl : "systemd[3975]: Failed to open private bus connection: Unable to autolaunch a dbus-daemon without a $DISPLAY for X11." Are there any other environment variables that need to be added to that section?<br />
[[User:Feynman|Feynman]] ([[User talk:Feynman|talk]]) 23:57, 5 February 2013 (UTC)<br />
<br />
::Not really. I'm not using auto-login and I'm not using any DE or login manager. It was a bug I ''believe'' on older versions on systemd. Since 198 it's not longer necessary. I still get that error on the start but it actually works without hassle. --[[User:Pabloxcl|Pabloxcl]] ([[User talk:Pabloxcl|talk]]) 16:21, 7 April 2013 (UTC)<br />
<br />
== Increasing priority of user services ==<br />
<br />
How can I increase priority for user services? When I try to use {{ic|1=CPUShares=2048}}, I get {{ic|Failed to create cgroup cpu:/user/1000.user/2.session/systemd-536/xorg.service: Permission denied}}, when I try to use {{ic|1=Nice=-15}}, I get {{ic|Failed at step NICE spawning /usr/bin/xorg-launch-helper: Permission denied}}.<br />
<br />
== Starting services using a display manager ==<br />
<br />
I had a hard time trying to use {{ic|systemd --user}} with a display manager. I use Slim, so I just put {{ic|systemd --user &}} in my {{ic|~/.xinitrc}} just before starting my WM (Awesome). Systemd started but nothing else happened. In fact I had to create a {{ic|default.target}} file in {{ic|~/.config/systemd/user/}} containing only<br />
[Unit]<br />
AllowIsolate=yes<br />
and then enable services provided that each file contains<br />
[Install]<br />
WantedBy=default.target<br />
Then all went well, {{ic|systemd --user}} launch a dbus user session and all enabled service.<br />
<br />
I think the important part is the {{ic|default.target}} file, which is documented in [[Systemd/User#Using /usr/lib/systemd/systemd --user To Manage Your Session]] but not at all talked about in the previous sections. I'm not sure how to add this to the wiki, or even if my method is the right way to do it using a DM, So I prefer discuss this on this page. [[User:Ianux|Ianux]] ([[User talk:Ianux|talk]]) 17:57, 14 September 2013 (UTC)<br />
<br />
== Passing DBUS_SESSION_BUS_ADDRESS to session ==<br />
<br />
After setting variable in <tt>/etc/systemd/system/user@.service.d/dbus.conf</tt> it is present in systemd --user (and its services) environment, as can be verified by <tt>systemctl --user show-environment</tt>, but how is it exactly passed to session processes? [[User:Pmartycz|Pmartycz]] ([[User talk:Pmartycz|talk]]) 14:20, 4 July 2015 (UTC)<br />
<br />
:It isn't, because {{ic|systemd --user}} runs outside the user session. The default {{ic|/etc/X11/xinit/xinitrc.d/30-dbus.sh}} starts another bus exclusively for the X session. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:43, 4 July 2015 (UTC)<br />
<br />
::I thought the intent of this guide was to setup a single "user" bus shared by all user sessions (X, text, remote SSH logins) and by {{ic|systemd --user}}, wasn't it? [[User:Pmartycz|Pmartycz]] ([[User talk:Pmartycz|talk]]) 18:16, 4 July 2015 (UTC)<br />
<br />
:::The first paragraph of [[Systemd/User#D-Bus]] explains the purpose. There are multiple different ways which will all "work" in certain cases. The current recommended way seems to be having multiple user buses, but in the future, as grawity indicated below, there will be only a single bus. If you want to see if the single bus aproach works for you, just {{ic|1=export DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/$UID/bus}} from your shell startup file and make sure that {{ic|/etc/X11/xinit/xinitrc.d/30-dbus.sh}} is not run. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:48, 4 July 2015 (UTC)<br />
<br />
::::Somehow it wasn't clear to me. Anyway, I think the best place for setting this variable would be somewhere in PAM. [[User:Pmartycz|Pmartycz]] ([[User talk:Pmartycz|talk]]) 21:02, 4 July 2015 (UTC)<br />
<br />
:On a kdbus system, {{ic|pam_systemd}} would set it for you. --[[User:Grawity|grawity]] ([[User talk:Grawity|talk]]) 16:06, 4 July 2015 (UTC)<br />
<br />
== Simplifying the Xorg and Systemd section ==<br />
<br />
Why doesn't the [[Systemd/User#Xorg_and_systemd]] just use the startx wrapper program? I set up a service file like this and it seems to work just fine:<br />
<br />
{{hc|~/.config/systemd/user/xorg.service|<nowiki><br />
[Unit]<br />
Description=Xorg server<br />
<br />
[Service]<br />
Type=simple<br />
SuccessExitStatus=0 1<br />
<br />
ExecStart=/usr/bin/startx<br />
</nowiki>}}<br />
<br />
This seems a lot simpler than the configuration described. Sorry if this is a dumb question! <br />
[[User:Siddharthist|Siddharthist]] ([[User talk:Siddharthist|talk]]) 02:49, 9 May 2016 (UTC)<br />
<br />
== Variable expansion implied by Service example ==<br />
<br />
The example under the [[Systemd/User#Service example|Service example]] section implies that variable expansion will work in a systemd unit, however, from my understanding and experience this is not the case and so the {{ic|PATH}} variable would not be extended as it might seem. [[User:Flungo|Flungo]] ([[User talk:Flungo|talk]]) 19:49, 28 August 2016 (UTC)<br />
<br />
:Expansion of variables works in systemd units, see {{man|5|systemd.service|COMMAND_LINES}}. It's just that {{ic|$PATH}} in the systemd unit is not the same as {{ic|$PATH}} in the shell, most notably the value does not propagate automatically from the shell into systemd. This is what [[Systemd/User#Environment_variables]] is all about. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:49, 12 September 2016 (UTC)<br />
<br />
::The referenced example implied that variable expansion worked within Environment lines. It only works within Command lines, per the linked manpage. And even then it only works as a bare word, like {{ic|/bin/true $FOO bar}}. To use within a word it must be wrapped in curlies, like {{ic|1=PATH=${FOO}:/bin}}. I updated the example to remove the variable reference. [[User:Sj26|Sj26]] ([[User talk:Sj26|talk]]) 15:51, 11 March 2017 (UTC)<br />
<br />
== user@userid.service.d drop-ins ==<br />
<br />
Since I'm researching ways to pass environment variables to {{ic|systemd --user}} I found out you can actually create a drop-in directory for a specific userid (eg {{ic|/etc/systemd/system/user@1000.service.d/}}. I thought about mentioning it in the page, but I am not sure it is good practice. What do you think? [[User:Farsil|Farsil]] ([[User talk:Farsil|talk]]) 22:15, 6 December 2016 (UTC)<br />
<br />
== Setting up DISPLAY variable for systemd-user unit under Wayland session ==<br />
<br />
On Wayland session (notably Weston), the {{Ic|/etc/X11/xinit/xinitrc.d/50-systemd-user.sh}} is not parsed, so that systemd-user units don't aware of the {{Ic|DISPLAY}} environment variable.<br />
<br />
User need to run {{Ic|systemctl --user import-environment DISPLAY WAYLAND_DISPLAY}} so that systemd user service can make use of the variable.<br />
<br />
[[User:Alive4ever|Alive4ever]] ([[User talk:Alive4ever|talk]]) 13:14, 13 April 2017 (UTC)<br />
<br />
:Why do you need {{ic|DISPLAY}} in Wayland? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:00, 13 April 2017 (UTC)<br />
<br />
::Because most GUI applications, such as web browsers, don't have complete Wayland support and therefore needs {{Ic|DISPLAY}} environment variable to run under Xwayland.<br />
::Real use case is {{Ic|gpg-agent}} systemd user service need to know {{Ic|DISPLAY}} to invoke proper {{Ic|pinentry}} gui to ask for passphrase.<br />
::{{Ic|ssh-agent}} is also another case, where it needs to know {{Ic|DISPLAY}} to invoke {{Ic|ssh-askpass}}.<br />
<br />
[[User:Alive4ever|Alive4ever]] ([[User talk:Alive4ever|talk]]) 13:14, 13 April 2017 (UTC)</div>Alive4everhttps://wiki.archlinux.org/index.php?title=Talk:Systemd/User&diff=473795Talk:Systemd/User2017-04-12T16:30:37Z<p>Alive4ever: /* Setting up DISPLAY variable for systemd-user unit under Wayland session */ new section</p>
<hr />
<div>== Setting Environment variables without autologin/user-session@.service ==<br />
<br />
If you're not using auto-login, specifically the user-session@service, the environment variable DBUS_SESSION_BUS_ADDRESS needs to exported to something like {{ic|export DBUS_SESSION_BUS_ADDRESS&#61;/run/user/$(id -u)/dbus/user_bus_socket}} before {{ic|systemd --user}}. Otherwise, an error shows up in journalctl : "systemd[3975]: Failed to open private bus connection: Unable to autolaunch a dbus-daemon without a $DISPLAY for X11." Are there any other environment variables that need to be added to that section?<br />
[[User:Feynman|Feynman]] ([[User talk:Feynman|talk]]) 23:57, 5 February 2013 (UTC)<br />
<br />
::Not really. I'm not using auto-login and I'm not using any DE or login manager. It was a bug I ''believe'' on older versions on systemd. Since 198 it's not longer necessary. I still get that error on the start but it actually works without hassle. --[[User:Pabloxcl|Pabloxcl]] ([[User talk:Pabloxcl|talk]]) 16:21, 7 April 2013 (UTC)<br />
<br />
== Increasing priority of user services ==<br />
<br />
How can I increase priority for user services? When I try to use {{ic|1=CPUShares=2048}}, I get {{ic|Failed to create cgroup cpu:/user/1000.user/2.session/systemd-536/xorg.service: Permission denied}}, when I try to use {{ic|1=Nice=-15}}, I get {{ic|Failed at step NICE spawning /usr/bin/xorg-launch-helper: Permission denied}}.<br />
<br />
== Starting services using a display manager ==<br />
<br />
I had a hard time trying to use {{ic|systemd --user}} with a display manager. I use Slim, so I just put {{ic|systemd --user &}} in my {{ic|~/.xinitrc}} just before starting my WM (Awesome). Systemd started but nothing else happened. In fact I had to create a {{ic|default.target}} file in {{ic|~/.config/systemd/user/}} containing only<br />
[Unit]<br />
AllowIsolate=yes<br />
and then enable services provided that each file contains<br />
[Install]<br />
WantedBy=default.target<br />
Then all went well, {{ic|systemd --user}} launch a dbus user session and all enabled service.<br />
<br />
I think the important part is the {{ic|default.target}} file, which is documented in [[Systemd/User#Using /usr/lib/systemd/systemd --user To Manage Your Session]] but not at all talked about in the previous sections. I'm not sure how to add this to the wiki, or even if my method is the right way to do it using a DM, So I prefer discuss this on this page. [[User:Ianux|Ianux]] ([[User talk:Ianux|talk]]) 17:57, 14 September 2013 (UTC)<br />
<br />
== Passing DBUS_SESSION_BUS_ADDRESS to session ==<br />
<br />
After setting variable in <tt>/etc/systemd/system/user@.service.d/dbus.conf</tt> it is present in systemd --user (and its services) environment, as can be verified by <tt>systemctl --user show-environment</tt>, but how is it exactly passed to session processes? [[User:Pmartycz|Pmartycz]] ([[User talk:Pmartycz|talk]]) 14:20, 4 July 2015 (UTC)<br />
<br />
:It isn't, because {{ic|systemd --user}} runs outside the user session. The default {{ic|/etc/X11/xinit/xinitrc.d/30-dbus.sh}} starts another bus exclusively for the X session. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:43, 4 July 2015 (UTC)<br />
<br />
::I thought the intent of this guide was to setup a single "user" bus shared by all user sessions (X, text, remote SSH logins) and by {{ic|systemd --user}}, wasn't it? [[User:Pmartycz|Pmartycz]] ([[User talk:Pmartycz|talk]]) 18:16, 4 July 2015 (UTC)<br />
<br />
:::The first paragraph of [[Systemd/User#D-Bus]] explains the purpose. There are multiple different ways which will all "work" in certain cases. The current recommended way seems to be having multiple user buses, but in the future, as grawity indicated below, there will be only a single bus. If you want to see if the single bus aproach works for you, just {{ic|1=export DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/$UID/bus}} from your shell startup file and make sure that {{ic|/etc/X11/xinit/xinitrc.d/30-dbus.sh}} is not run. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:48, 4 July 2015 (UTC)<br />
<br />
::::Somehow it wasn't clear to me. Anyway, I think the best place for setting this variable would be somewhere in PAM. [[User:Pmartycz|Pmartycz]] ([[User talk:Pmartycz|talk]]) 21:02, 4 July 2015 (UTC)<br />
<br />
:On a kdbus system, {{ic|pam_systemd}} would set it for you. --[[User:Grawity|grawity]] ([[User talk:Grawity|talk]]) 16:06, 4 July 2015 (UTC)<br />
<br />
== Simplifying the Xorg and Systemd section ==<br />
<br />
Why doesn't the [[Systemd/User#Xorg_and_systemd]] just use the startx wrapper program? I set up a service file like this and it seems to work just fine:<br />
<br />
{{hc|~/.config/systemd/user/xorg.service|<nowiki><br />
[Unit]<br />
Description=Xorg server<br />
<br />
[Service]<br />
Type=simple<br />
SuccessExitStatus=0 1<br />
<br />
ExecStart=/usr/bin/startx<br />
</nowiki>}}<br />
<br />
This seems a lot simpler than the configuration described. Sorry if this is a dumb question! <br />
[[User:Siddharthist|Siddharthist]] ([[User talk:Siddharthist|talk]]) 02:49, 9 May 2016 (UTC)<br />
<br />
== Variable expansion implied by Service example ==<br />
<br />
The example under the [[Systemd/User#Service example|Service example]] section implies that variable expansion will work in a systemd unit, however, from my understanding and experience this is not the case and so the {{ic|PATH}} variable would not be extended as it might seem. [[User:Flungo|Flungo]] ([[User talk:Flungo|talk]]) 19:49, 28 August 2016 (UTC)<br />
<br />
:Expansion of variables works in systemd units, see {{man|5|systemd.service|COMMAND_LINES}}. It's just that {{ic|$PATH}} in the systemd unit is not the same as {{ic|$PATH}} in the shell, most notably the value does not propagate automatically from the shell into systemd. This is what [[Systemd/User#Environment_variables]] is all about. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:49, 12 September 2016 (UTC)<br />
<br />
::The referenced example implied that variable expansion worked within Environment lines. It only works within Command lines, per the linked manpage. And even then it only works as a bare word, like {{ic|/bin/true $FOO bar}}. To use within a word it must be wrapped in curlies, like {{ic|1=PATH=${FOO}:/bin}}. I updated the example to remove the variable reference. [[User:Sj26|Sj26]] ([[User talk:Sj26|talk]]) 15:51, 11 March 2017 (UTC)<br />
<br />
== user@userid.service.d drop-ins ==<br />
<br />
Since I'm researching ways to pass environment variables to {{ic|systemd --user}} I found out you can actually create a drop-in directory for a specific userid (eg {{ic|/etc/systemd/system/user@1000.service.d/}}. I thought about mentioning it in the page, but I am not sure it is good practice. What do you think? [[User:Farsil|Farsil]] ([[User talk:Farsil|talk]]) 22:15, 6 December 2016 (UTC)<br />
<br />
== Setting up DISPLAY variable for systemd-user unit under Wayland session ==<br />
<br />
On Wayland session (notably Weston), the {{Ic|/etc/X11/xinit/xinitrc.d/50-systemd-user.sh}} is not parsed, so that systemd-user units don't aware of the {{Ic|DISPLAY}} environment variable.<br />
<br />
User need to run {{Ic|systemctl --user import-environment DISPLAY WAYLAND_DISPLAY}} so that systemd user service can make use of the variable.</div>Alive4everhttps://wiki.archlinux.org/index.php?title=Redshift&diff=472750Redshift2017-04-01T17:09:15Z<p>Alive4ever: /* Autostart */ Add autostart using .desktop file inside ~/.config/autostart/</p>
<hr />
<div>[[Category:X server]]<br />
[[Category:Graphics]]<br />
[[Category:Eye candy]]<br />
[[ja:Redshift]]<br />
[[ru:Redshift]]<br />
From the [http://jonls.dk/redshift/ Redshift project web page]:<br />
<br />
:Redshift adjusts the color temperature of your screen according to your surroundings. This may help your eyes hurt less if you are working in front of the screen at night. This program is inspired by [http://justgetflux.com f.lux].<br />
<br />
{{Note|<br />
* Redshift only works with [[Xorg]] [https://github.com/jonls/redshift/issues/55] – [[Wayland]] is not supported yet.<br />
* A native [[GNOME]] [https://github.com/benzea/gnome-shell-extension-redshift extension] has been made available and supports [[Wayland]], however it requires a patched {{pkg|gnome-settings-daemon}}. See [[#GNOME Shell Extension]].<br />
}}<br />
<br />
== Installation ==<br />
<br />
=== Redshift ===<br />
<br />
[[Install]] the {{Pkg|redshift}} package. Alternatively, install the {{AUR|redshift-minimal}} package, for a version with minimal dependencies.<br />
<br />
==== Redshift-GTK ====<br />
<br />
The {{ic|redshift-gtk}} command is provided by the {{Pkg|redshift}} package. Redshift-GTK provides a system tray icon for controlling Redshift and requires the following packages to be installed: {{Pkg|python-gobject}}, {{Pkg|python-xdg}}, and {{Pkg|librsvg}}. An alternative (non-GTK solution) for [[KDE]] is available as {{AUR|plasma5-applets-redshift-control-git}}.<br />
<br />
=== GNOME Shell Extension ===<br />
{{Note|<br />
*[[Disable]]/stop any running Redshift instance, because it is not compatible with this GNOME Extension.<br />
*You may want to [[uninstall]] {{pkg|redshift}} since it is not used by {{AUR|gnome-shell-extension-redshift-native-git}}.<br />
}}<br />
<br />
Install {{AUR|gnome-shell-extension-redshift-native-git}}, restart/re-login and enable/configure the extension with {{Pkg|gnome-tweak-tool}}.<br />
<br />
== Configuration ==<br />
<br />
Redshift will at least need your location to start, meaning the latitude and longitude of your location. Redshift employs several routines for obtaining your location. If none of them works (e.g. none of the used helper programs is installed), you need to enter your location manually: For most places/cities an easy way is to look up the wikipedia page of that place and get the location from there (search the page for "coordinates").<br />
<br />
=== Autostart ===<br />
<br />
There are several options to have redshift automatically started:<br />
<br />
* By launching redshift with a script under {{ic|/etc/X11/xinit/xinitrc.d/}}.<br />
* By adding {{ic|pgrep redshift &> /dev/null <nowiki>||</nowiki> redshift &> /dev/null &}} to {{ic|~/.xinitrc}} if you are using {{ic|startx}}<br />
* By using the provided [[Systemd#Using units|systemd service unit files]]. Be careful: the service can only be started in user mode, see [[systemd/User#Basic setup]]. Two service files are provided: {{ic|/usr/lib/systemd/user/redshift.service}} and {{ic|/usr/lib/systemd/user/redshift-gtk.service}}. Activate only one of them depending on whether or not you want the system tray icon. The {{ic|DISPLAY}} environment variable needs to be configured. See [[systemd/User#DISPLAY and XAUTHORITY]].<br />
* By right-clicking the system tray icon when redshift-gtk or plasma5-applets-redshift-control is already launched and selecting 'Autostart'.<br />
{{note|The redshift services files contains {{ic|Restart<nowiki>=</nowiki>always}} so the service will restart infinitely (see {{ic|man systemd.service}}) }}<br />
* By using your preferred window manager or desktop environment's autostart methods. For example in i3, the following line could be added to the config file: {{ic|exec --no-startup-id redshift-gtk}}. On other desktop environments, [[Desktop entries]] inside {{Ic|~/.config/autostart}} can be used.<br />
<br />
=== Quick start ===<br />
{{Tip|You can get the coordinates of a place with [http://www.geonames.org/ GeoNames.org].}}<br />
<br />
To just get it up and running with a basic setup, issue:<br />
<br />
$ redshift -l LAT:LON<br />
<br />
where LAT is the latitude and LON is the longitude of your location.<br />
<br />
=== Automatic location based on GPS ===<br />
<br />
You can also use {{Pkg|gpsd}} to automatically determine your GPS location and use it as an input for Redshift. Create the following script and pass {{ic|$lat}} and {{ic|$lon}} to {{ic|redshift -l $lat;$lon}}:<br />
<br />
#!/bin/bash<br />
date<br />
#gpsdata=$( gpspipe -w -n 10 | grep -m 1 lon )<br />
gpsdata=$( gpspipe -w | grep -m 1 TPV )<br />
lat=$( echo "$gpsdata" | jsawk 'return this.lat' )<br />
lon=$( echo "$gpsdata" | jsawk 'return this.lon' )<br />
alt=$( echo "$gpsdata" | jsawk 'return this.alt' )<br />
dt=$( echo "$gpsdata" | jsawk 'return this.time' )<br />
echo "$dt"<br />
echo "You are here: $lat, $lon at $alt"<br />
<br />
For more information, see [https://bbs.archlinux.org/viewtopic.php?pid=1389735#p1389735 this] forums thread.<br />
<br />
=== Manual setup ===<br />
<br />
Redshift reads the configuration file {{ic|~/.config/redshift.conf}}, if it exists. However, Redshift does not create that configuration file, so you have to create it manually.<br />
Below is an example (copied from the [http://jonls.dk/redshift/ Redshift website]).<br />
<br />
{{note|There seems to be a bug in Redshift that causes the transition option in the configuration file to not work as described: Instead of handling the transition between day and night it '''only''' changes the transition between application start-up and shutdown (and delay the latter as a consequence). See the [[talk:redshift#Day and night transition|talk page]] and the [https://github.com/jonls/redshift/issues/270 issue on the Redshift project page] for more information.}}<br />
<br />
{{hc|~/.config/redshift.conf|2=<br />
; Global settings for redshift<br />
[redshift]<br />
; Set the day and night screen temperatures (Neutral is 6500K)<br />
temp-day=5700<br />
temp-night=3500<br />
<br />
; Enable/Disable a smooth transition between day and night<br />
; 0 will cause a direct change from day to night screen temperature.<br />
; 1 will gradually increase or decrease the screen temperature.<br />
transition=1<br />
<br />
; Set the screen brightness. Default is 1.0.<br />
;brightness=0.9<br />
; It is also possible to use different settings for day and night<br />
; since version 1.8.<br />
;brightness-day=0.7<br />
;brightness-night=0.4<br />
; Set the screen gamma (for all colors, or each color channel<br />
; individually)<br />
gamma=0.8<br />
;gamma=0.8:0.7:0.8<br />
; This can also be set individually for day and night since<br />
; version 1.10.<br />
;gamma-day=0.8:0.7:0.8<br />
;gamma-night=0.6<br />
<br />
; Set the location-provider: 'geoclue2' or 'manual'<br />
; type 'redshift -l list' to see possible values.<br />
; The location provider settings are in a different section.<br />
location-provider=manual<br />
<br />
; Set the adjustment-method: 'randr', 'vidmode'<br />
; type 'redshift -m list' to see all possible values.<br />
; 'randr' is the preferred method, 'vidmode' is an older API.<br />
; but works in some cases when 'randr' does not.<br />
; The adjustment method settings are in a different section.<br />
adjustment-method=randr<br />
<br />
; Configuration of the location-provider:<br />
; type 'redshift -l PROVIDER:help' to see the settings.<br />
; ex: 'redshift -l manual:help'<br />
; Keep in mind that longitudes west of Greenwich (e.g. the Americas)<br />
; are negative numbers.<br />
[manual]<br />
lat=48.1<br />
lon=11.6<br />
<br />
; Configuration of the adjustment-method<br />
; type 'redshift -m METHOD:help' to see the settings.<br />
; ex: 'redshift -m randr:help'<br />
; In this example, randr is configured to adjust screen 1.<br />
; Note that the numbering starts from 0, so this is actually the<br />
; second screen. If this option is not specified, Redshift will try<br />
; to adjust _all_ screens.<br />
[randr]<br />
screen=1<br />
}}<br />
<br />
=== Use real screen brightness ===<br />
<br />
Redshift has a brightness adjustment setting, but it does not work the way most people might expect. In fact it is a fake brightness adjustment obtained by manipulating the gamma ramps, which means that it does not reduce the backlight of the screen. [http://jonls.dk/redshift/#known-bugs-and-limitations]<br />
<br />
Changing screen backlight is possible with redshift hooks and {{pkg|xorg-xrandr}} and {{pkg|xorg-xbacklight}} but, please see [[Backlight#xbacklight]] as there are some limitations and you may have to find another method of controlling the backlight depending on your hardware.<br />
<br />
You need to create a file in {{ic|~/.config/redshift/hooks}} and make it executable. You can use and edit this example. <br />
<br />
{{hc|<br />
~/.config/redshift/hooks/brightness.sh|output=#!/bin/sh<br />
<br />
# Set brightness via xbrightness when redshift status changes<br />
<br />
# Set brightness values for each status.<br />
# Range from 1 to 100 is valid<br />
brightness_day="100"<br />
brightness_transition="50"<br />
brightness_night="10"<br />
# Set fade time for changes to one minute<br />
fade_time=60000<br />
<br />
case $1 in<br />
period-changed)<br />
case $3 in<br />
night)<br />
xbacklight -set $brightness_night -time $fade_time<br />
;;<br />
transition)<br />
xbacklight -set $brightness_transition -time $fade_time<br />
;;<br />
daytime)<br />
xbacklight -set $brightness_day -time $fade_time<br />
;;<br />
esac<br />
;;<br />
esac<br />
}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Screen 1 could not be found ===<br />
<br />
Locate configuration-file "redshift.conf" in your distribution and change "screen 1" to "screen 0"<br />
<br />
=== Left/right clicking the tray icon doesn't work ===<br />
Install {{Pkg|libappindicator-gtk3}}. See [https://github.com/jonls/redshift/issues/363] and [https://bugs.archlinux.org/task/49971]<br />
<br />
=== Failed to run Redshift due to geoclue2 ===<br />
{{note|Prior to apply the method below, close redshift-gtk and restart the geoclue service. Sometimes the location service fails due to e.g. connection established after the location service.}}<br />
<br />
If using [[GNOME]], you can also toggle Location Services to "On" in "Settings -> Privacy"<br />
<br />
By default, the geoclue2 configuration files does not allow Redshift access.<br />
In order to allow access, add the following lines to {{ic|/etc/geoclue/geoclue.conf}}<br />
{{hc|/etc/geoclue/geoclue.conf|2=<br />
[redshift]<br />
allowed=true<br />
system=false<br />
users=<br />
}}<br />
<br />
== See also ==<br />
* [http://jonls.dk/redshift Redshift website]<br />
* [http://github.com/jonls/redshift Redshift on github]<br />
* {{App|sct|set color temperature|{{AUR|sct}}|{{AUR|sct}}}}</div>Alive4everhttps://wiki.archlinux.org/index.php?title=Xterm&diff=454821Xterm2016-10-23T10:05:11Z<p>Alive4ever: /* Making xterm's 'Alt' key behaves as on other terminal emulators */ small typo</p>
<hr />
<div>[[Category:Terminal emulators]]<br />
[[de:Xterm]]<br />
[[fr:Xterm]]<br />
[[ja:Xterm]]<br />
[[ru:Xterm]]<br />
'''xterm''' is the standard [[Wikipedia:Terminal emulator|terminal emulator]] for the [[X Window System]]. It is highly configurable and has many useful and some unusual features.<br />
<br />
==Configuration==<br />
=== Resource file settings ===<br />
<br />
There are several options you can set in your [[X resources]] files that may make this terminal emulator much easier to use. See {{ic|man xterm}} for a complete list.<br />
<br />
==== TERM Environmental Variable ====<br />
<br />
Allow xterm to report the '''TERM '''variable correctly. '''Do not '''set the TERM variable from your ''~/.bashrc'' or ''~/.bash_profile'' or similar file. The terminal itself should report the correct TERM to the system so that the proper ''terminfo'' file will be used. Two usable terminfo files are ''xterm, ''and ''xterm-256color.''<br />
<br />
Without setting TERM explicitly, xterm should report {{ic|$TERM}} as {{ic|xterm}}. You can check this from within xterm using either of these commands:<br />
<br />
$ echo $TERM<br />
$ tset -q<br />
<br />
When TERM is not set explicitly, color schemes for some programs, such as ''vim, ''may not appear until a key is pressed or some other input occurs. This can be remedied with this resource setting:<br />
<br />
xterm*termName: xterm-256color<br />
<br />
==== UTF-8 ====<br />
<br />
Make certain your [[locale#Setting_the_locale|locale settings]] are correct for UTF-8. Adding the following line to your resource file will then make xterm interpret all incoming data as UTF-8 encoded:<br />
<br />
XTerm*locale: true<br />
<br />
==== Making xterm's 'Alt' key behaves as on other terminal emulators ====<br />
<br />
The default {{Ic|Alt}} key behavior on {{Ic|xterm}} is a modifier to send eight bit input characters so that user can insert {{Ic|æ}} by pressing {{Ic|Alt+f}} inside {{Ic|xterm}}.<br />
<br />
This behavior is different from terminal emulators such as {{Ic|gnome-terminal}} and {{Ic|konsole}}, which uses {{Ic|Alt}} as modifier to sends {{Ic|^[}} (escape} character.<br />
<br />
If you want {{ic|Alt}} key on {{Ic|xterm}} to behave as on other terminal emulators, i.e. sends {{Ic|^[}} instead of acts as eight bit modifier, you will need to put one of the following line in your resource file.<br />
<br />
XTerm*metaSendsEscape: true<br />
XTerm*eightBitInput: false<br />
<br />
==== Fix the backspace key ====<br />
<br />
On Archlinux, {{ic|xterm}} sends {{ic|^H}} key when backspace is pressed. This breaks {{ic|Ctrl+H}} key combination on [[Emacs]].<br />
The workaround is making {{ic|xterm}} sends {{ic|^?}} when backspace is pressed, by adding the following lines to X resource file.<br />
<br />
XTerm*backarrowKey: false<br />
XTerm*ttyModes: erase ^?<br />
<br />
=== Scrolling ===<br />
As new lines are written to the bottom of the xterm window, older lines disappear from the top. To scroll up and down through the off-screen lines one can use the mouse wheel, the key combinations {{ic|Shift+PageUp}} and {{ic|Shift+PageDown}}, or the scrollbar.<br />
<br />
By default, 1024 lines are saved. You can change the number of saved lines with the {{ic|saveLines}} resource,<br />
Xterm*saveLines: 4096<br />
<br />
Other X resources that affect scrolling are {{ic|jumpScroll}}, set to {{ic|true}} by default, and {{ic|multiScroll}} and {{ic|fastScroll}}, both of which default to {{ic|false}}. To scroll inside an [[#VT_Options_menu|alternate screen]], set {{ic|alternateScroll}} to {{ic|true}}.<br />
<br />
==== The Scrollbar ====<br />
The scrollbar is not shown by default. It can be made visible by a menu selection, by command line options, or by setting resource values. It can be made to appear to the left or right of the window and its visual appearance can be modified through resource settings.<br />
<br />
The scrollbar operates differently from what you may be accustomed to using.<br />
*To scroll down:<br />
:– Click on the scrollbar with the left mouse button.<br />
:– Click on the scrollbar below the ''thumb'' with the middle mouse button.<br />
*To scroll up:<br />
:– Click on the scrollbar with the right mouse button.<br />
:– Click on the scrollbar above the ''thumb'' with the middle mouse button.<br />
*To position text, moving in either direction:<br />
:– Grab the ''thumb'' and use "click-and-drag" with the middle mouse button.<br />
<br />
===Menus===<br />
The Archlinux version of xterm is compiled with the ''toolbar, ''or ''menubar, ''disabled. The menus are still available as ''popups ''when you press {{ic|Ctrl+MouseButton}} within the xterm window. The actions invoked by the menu items can often be accomplished using command line options or by setting resource values.<br />
<br />
{{Tip|If the popup menu windows show only as small boxes, it is probably because you have a line similar to this, {{ic|xterm*geometry: 80x32}}, in your resources file. This ''does ''start xterm in an 80 column by 32 row main window, but it also forces the menu windows to be 80 pixels by 32 pixels! Replace the incorrect line with this:<br />
{{bc|xterm*VT100.geometry: 80x32}}}}<br />
<br />
Some of the menu options are discussed below.<br />
<br />
====Main Options menu====<br />
'''''Ctrl + LeftMouse'''''<br />
<br />
*{{ic|Secure Keyboard}} attempts to ensure only the xterm window, and no other application, receives your keystrokes. The display changes to reverse video when it is invoked. If the display is not in reverse video, the ''Secure Keyboard ''mode is not in effect. Please read the "SECURITY" section of the xterm man page for this option's limitations.<br />
<br />
*{{ic|Allow SendEvents}} allows other processes to send keypress and mouse events to the xterm window. Because of the security risk, do not enable this unless you are very sure you know what you are doing.<br />
<br />
*{{ic|Log to File}} – The log file will be named {{ic|Xterm.log.hostname.yyyy.mm.dd.hh.mm.ss.XXXXXX}}. This file will contain all the printed output ''and all cursor movements. ''Logging may be a security risk.<br />
<br />
*The six {{ic|Send *** Signal}} menu items are not often useful, except when your keyboard fails. {{ic|HUP}}, {{ic|TERM}} and {{ic|KILL}} will close the xterm window. {{ic|KILL}} should be avoided, as it does not allow any cleanup code to run.<br />
<br />
*The {{ic|Quit}} menu item will also close the xterm window – it is the same as sending a {{ic|HUP}} signal. Most users will use the keyboard combination {{ic|Ctrl+d}} or will type {{ic|exit}} to close an xterm instance.<br />
====VT Options menu====<br />
'''''Ctrl + MiddleMouse'''''<br />
*{{ic|Select to Clipboard}} – Normally, selected text is stored in PRIMARY, to be pasted with {{ic|Shift+Insert}} or by using the middle mouse button. By toggling this option to ''on, ''selected text will use CLIPBOARD, allowing you to paste the text selected in an xterm window into a GUI application using {{ic|Ctrl+v}}. The corresponding XTerm resource is {{ic|selectToClipboard}}.<br />
<br />
*{{ic|Show Alternate Screen}} – When you use an a terminal application such as ''vim, ''or ''less, ''the alternate screen is opened. The main VT window, now hidden, remains in memory. You can view this main window, but not issue any commands in it, by toggling this menu option. You are able to select and copy text from this main window.<br />
<br />
{{Tip|Suspending the process running in the Alternate Screen and then resuming it provides more functionality than using {{ic|Show Alternate Screen}}. With a ''bash'' shell, pressing {{ic|Ctrl+z}} suspends the process; issuing the command {{ic|fg}} then resumes it.}}<br />
<br />
*{{ic|Show Tek Window}} and {{ic|Switch to Tek Mode}} – The [[Wikipedia:Tektronix 4010|Tektronix 4014]] was a graphics terminal from the 1970s used for CAD and plotting applications. The command line program {{ic|graph}}, from {{Pkg|plotutils}}, and the application {{Pkg|gnuplot}} can be made to use xterm's Tek emulation; most people will prefer more modern display options for charting data. See the [[#Tek 4014 demonstration]], below.<br />
<br />
====VT Fonts menu====<br />
'''''Ctrl + RightMouse'''''<br />
<br />
*When using XLFD fonts, the first seven menu items will change the font face and the font size used in the current xterm window. If you are using an Xft font, only the font size will change, the font face will not change with the different selections, .<br />
<br />
{{Tip|{{ic|Unreadable}} and {{ic|Tiny}} are useful if you wish to keep an eye on a process but do not want to devote a large amount of screen space to the terminal window. An example use might be a lengthy compilation process when you only want to see that the operation completes.}}<br />
<br />
*{{ic|Selection}}, when using XLFD font names, allows you to switch to the font name stored in the PRIMARY selection (or CLIPBOARD).<br />
<br />
====Tek Options menu==== <br />
From the '''Tek Window,''' '''''Ctrl + MiddleMouse'''''<br />
<br />
The first section's options allow you to change the Tek window font size. The second set of options are used to move the focus between the Tek emulation window and the main, or ''VT, ''window and to close or hide the Tek window.<br />
<br />
===Copy and paste===<br />
First, highlighting text using the mouse in an xterm (or alternatively another application) will select the text to copy, then clicking the mouse middle-button will paste that highlighted text. Also the key combination {{ic|Shift+Insert}} will paste highlighted text, but only within an xterm.<br />
<br />
====PRIMARY or CLIPBOARD====<br />
<br />
{{Expansion|Separate shortcuts for CLIPBOARD can be defined instead of using ''Select to clipboard'', similar to VTE-like terminals. See e.g [https://github.com/AladW/arch-i3/blob/master/.Xresources#L17]}}<br />
<br />
By default, xterm, and many other applications running under X, copy highlighted text into a buffer called the PRIMARY selection. The PRIMARY selection is short-lived; the text is immediately replaced by a new PRIMARY selection as soon as another piece of text is highlighted. Some applications will allow you to paste PRIMARY selections by using the middle-mouse, but not {{ic|Shift+Insert}}, and some other applications may not allow pasting from PRIMARY entirely.<br />
<br />
There is another buffer used for copied text called the CLIPBOARD selection. The text in the CLIPBOARD is long-lived, remaining available until a user actively overwrites it. Applications that use {{ic|Ctrl+c}} and {{ic|Ctrl+x}} for text copying and cutting operations, and {{ic|Ctrl+v}} for pasting, are using the CLIPBOARD.<br />
<br />
The fleeting nature of the PRIMARY selection, where copied text is lost as soon as another selection is highlighted, annoys some users. Xterm allows the user to switch between the use of PRIMARY and CLIPBOARD using {{ic|Select to Clipboard}} on the [[#VT Options menu]] or with the {{ic|selectToClipboard}} resource.<br />
<br />
====PRIMARY and CLIPBOARD====<br />
<br />
With the above setting you can select if you want to use PRIMARY or CLIPBOARD, but to use both you need a 'hack'. For example, put this in your .Xresources:<br />
<br />
XTerm*VT100.translations: #override <Btn1Up>: select-end(PRIMARY, CLIPBOARD, CUT_BUFFER0)<br />
<br />
====Selecting text====<br />
The new user usually discovers that text may be selected using a "click-and-drag" with the left mouse button. Double-clicking will select a word, where a word is defined as consecutive alphabetic characters plus the underscore, or the Basic Regular Expression (BRE) {{ic|[A-Za-z_]}}. Triple-clicking selects a line, with a "tab" character usually copied as multiple "space" characters.<br />
<br />
Another way of selecting text, especially useful when copying more than one full screen, is:<br />
#Left-click at the start of the intended selection.<br />
#Scroll to where the end of the selection is visible.<br />
#Right-click at the end of the selection.<br />
You do not have to be precise immediately with the right-click – any highlighted selection may be extended or shortened by using a right-click.<br />
<br />
You can clear any selected text by left-clicking once, anywhere within the xterm window.<br />
<br />
==Colors==<br />
Xterm defaults to black text, the ''foreground'' color, on a white ''background.'' The foreground and background colors can be reversed using the [[#VT Options menu|VT Options menu]] or with the {{ic|-rv}} command line option.<br />
$ xterm -rv<br />
<br />
Alternatively, the same thing can be accomplished with the following [[X_resources|X resources parameter]] (do not forget to [[X_resources#Parsing_.Xresources|reread the new resource afterwards]]{{Broken section link}}!):<br />
XTerm*reverseVideo: on<br />
<br />
Xterm's foreground color (the text color) and the background color may be set from the command line, using the options {{ic|-fg}} and {{ic|-bg}} respectively.<br />
xterm -fg PapayaWhip -bg "rgb:00/00/80"<br />
<br />
The first sixteen terminal colors, as well as the foreground and background colors, may be set from an [[X resources]] file:<br />
{{bc|XTerm*foreground: rgb:b2/b2/b2<br />
XTerm*background: rgb:08/08/08<br />
XTerm*color0: rgb:28/28/28<br />
<br />
! ...Lines omitted...<br />
<br />
XTerm*color15: rgb:e4/e4/e4}}<br />
{{Note|Colors for applications that use the X libraries may be specified in many different ways.<br />
<br />
Some colors can be specified by assigned names. If {{Pkg|emacs}} or {{Pkg|vim}} has been installed, you can examine {{ic|/usr/share/emacs/*/etc/rgb.txt}} or {{ic|/usr/share/vim/*/rgb.txt}} to view the list of color names with their decimal RGB values. Colors may also be specified using hexadecimal RGB values with the format {{ic|rgb:RR/GG/BB}}, or the older and not encouraged syntax {{ic|#RRGGBB}}.<br />
<br />
The color {{ic|PapayaWhip}} is the same as {{ic|rgb:ff/ef/d5}}, which is the same as {{ic|#ffefd5}}.<br />
<br />
See '''man(7) X, '''from {{Pkg|xorg-docs}}, for a more complete description of color syntax.}}<br />
Many suggestions for color schemes can be viewed in the forum thread, [https://bbs.archlinux.org/viewtopic.php?id=51818&p=1 Terminal Colour Scheme Screenshots].<br />
{{Tip|Many people specify colors in their X resources files without specifying an application class or application instance:<br />
{{bc|*foreground: rgb:b2/b2/b2<br />
*background: rgb:08/08/08}}<br />
The above example sets the foreground and background color values for all ''Xlib'' applications (xclock, xfontsel, and others) that use these resources. This is a nice, easy way to achieve a unified color scheme.}}<br />
<br />
==Fonts==<br />
===Default fonts===<br />
Xterm's default font is the bitmap font named by the [[X Logical Font Description]] alias {{ic|fixed}}, often resolving to<br />
-misc-fixed-medium-r-semicondensed--13-120-75-75-c-60-iso8859-?<br />
This font, also aliased to the name {{ic|6x13}}, has remakably wide coverage for unicode glyphs. The default "TrueType" font is the 14‑point font matched by the name {{ic|mono}}. The ''FreeType ''font that will be used can be found with this command:<br />
$ fc-match mono<br />
<br />
Fonts can be specified from the command line, with the options {{ic|-fn}} for bitmap font names and {{ic|-fa}} for Xft names. The example below allows you to alternate between the two fonts by toggling {{ic|TrueType Fonts}} from the [[#VT Fonts menu]].<br />
{{bc|<nowiki>$ xterm -fn 7x13 -fa "Liberation Mono:size=10:antialias=false"</nowiki>}}<br />
For a more permanent change, the default fonts may be set in an [[X resources]] file:<br />
{{bc|<nowiki>xterm*faceName: Liberation Mono:size=10:antialias=false</nowiki><br />
xterm*font: 7x13}}<br />
<br />
{{Note|There is a long-standing bug in xterm that prevents the command line option {{ic|-fn}} working correctly when {{ic|faceName}} has been set in a resource file. One solution is to set the resource {{ic|renderFont}} to {{ic|false}} on the command line.<br />
{{bc|$ xterm -fn 8x13 # If this command does not set the font,<br />
$ xterm -fn 8x13 -xrm "*renderFont:false" # set the 'renderFont' resource to 'false'.}}<br />
Perhaps easier, you can just toggle {{ic|TrueType Fonts}} from the [[#VT Fonts menu]] in the terminal window.}}<br />
<br />
===Bold and underlined fonts===<br />
Italic fonts are shown as underlined characters when using XLFD names in xterm. TrueType fonts should use an oblique typeface.<br />
<br />
If you do not specify a bold font at the command line, {{ic|-fb}}, or through the {{ic|boldFont}} resource, xterm will attempt to find a bold font matching the normal font. If a matching font is not found, the bold font will be created by "overstriking" the normal font.<br />
<br />
===CJK Fonts===<br />
Many fonts do not contain glyphs for the double width Chinese, Japanese and Korean languages. Other terminal emulators such as [[urxvt]] may be better suited if you frequently work with these languages.<br />
<br />
Using bitmapped XLFD fonts with CJK has many pitfalls in xterm. It is much easier to use TrueType fonts for CJK display, using the {{ic|faceNameDoublesize}} resource. This example uses ''DejaVu Sans Mono'' as the normal font and ''WenQuanYi Bitmap Song'' as the double width font:<br />
{{bc|<nowiki>xterm*faceName: DejaVu Sans Mono:style=Book:antialias=false</nowiki><br />
xterm*faceNameDoublesize: WenQuanYi Bitmap Song<br />
xterm*faceSize: 8}}<br />
<br />
==Tips and tricks==<br />
===Automatic transparency===<br />
Install the package {{pkg|transset-df}} and a [[Wikipedia:Compositing window manager|composite manager]] such as [[Xcompmgr]]. Then add the following line to your {{ic|~/.bashrc}}:<br />
[ -n "$XTERM_VERSION" ] && transset-df --id "$WINDOWID" >/dev/null<br />
<br />
Now, each time you launch a shell in an xterm and a composite manager is running, the xterm window will be transparent.<br />
The test in front of {{ic|transset-df}} keeps transet from executing if {{ic|XTERM_VERSION}} is not defined. Note that your terminal will not be transparent if you launch a program other than a shell this way. It is probably possible to work around this if you want the functionality.<br />
<br />
Also see [[Per-application transparency]].<br />
<br />
===Enable bell urgency===<br />
Add the following line to your {{ic|~/.Xresources}} file:<br />
<br />
xterm*bellIsUrgent: true<br />
<br />
===Font tips===<br />
<br />
====Use color in place of bold and italics====<br />
When using small font sizes, bold or italic characters may be difficult to read. One solution is to turn off bolding and underlining or italics and use color instead. This example does just that:<br />
{{bc|! Forbid bold font faces; bold type is light blue.<br />
XTerm*colorBDMode: true<br />
XTerm*colorBD: rgb:82/a4/d3<br />
! Do not underscore text, underlined text is white.<br />
XTerm*colorULMode: true<br />
XTerm*colorUL: rgb:e4/e4/e4}}<br />
<br />
====Adjust line spacing====<br />
Lines of text can sometimes be too close together, or they may appear to be too widely spaced. For one example, using ''DejaVu Sans Mono, ''the low underscore glyph may butt against CJK glyphs or the cursor block in the line below. Line spacing, called ''leading ''by typographers, can be adjusted using the {{ic|scaleHeight}} resource. Here, the line spacing is widened:<br />
XTerm*scaleHeight: 1.01<br />
Valid values for {{ic|scaleHeight}} range from {{ic|0.9}} to {{ic|1.5}}, with {{ic|1.0}} being the default.<br />
===Remove black border===<br />
Xterm has a black border in some cases, you can disable this by adding the following line to your {{ic|~/.Xresources}} file.<br />
<br />
xterm*borderWidth: 0<br />
<br />
===Tek 4014 demonstration===<br />
If you have {{Pkg|plotutils}} installed, you can use xterm's Tektronix 4014 emulation to view some of the plotutils package's test files. Open the Tek window from the [[#VT Options menu]] menu item {{ic|Switch to Tek Mode}} or start a new xterm instance using this command:<br />
$ xterm -t -tn tek4014<br />
Your PS1 prompt will not render correctly, if it appears at all. In the new window, enter the command,<br />
cat /usr/share/tek2plot/dmerc.tek<br />
A world map will appear in the Tek window. You can also view other {{ic|*.tek}} files from that same directory. To close the Tek window, one can use the xterm menus.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Flickering on scroll ===<br />
<br />
{{Warning|Double buffering may cause non-bitmap fonts to render incorrectly.}}<br />
<br />
Rebuild xterm using [[ABS]] and include the {{ic|--enable-double-buffer}} flag:<br />
<br />
./configure --prefix=/usr \<br />
...<br />
--with-utempter \<br />
--enable-double-buffer<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?id=146023 Xterm modifications] for details.<br />
<br />
== See also ==<br />
<br />
* [http://lukas.zapletalovi.com/2013/07/hidden-gems-of-xterm.html Hidden gems of Xterm]<br />
* [http://www.in-ulm.de/~mascheck/X11/XTerm Commented XTerm resources]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=Xterm&diff=454820Xterm2016-10-23T10:02:41Z<p>Alive4ever: /* Fix the 'Alt' key */ Added explanation on alt key behavior</p>
<hr />
<div>[[Category:Terminal emulators]]<br />
[[de:Xterm]]<br />
[[fr:Xterm]]<br />
[[ja:Xterm]]<br />
[[ru:Xterm]]<br />
'''xterm''' is the standard [[Wikipedia:Terminal emulator|terminal emulator]] for the [[X Window System]]. It is highly configurable and has many useful and some unusual features.<br />
<br />
==Configuration==<br />
=== Resource file settings ===<br />
<br />
There are several options you can set in your [[X resources]] files that may make this terminal emulator much easier to use. See {{ic|man xterm}} for a complete list.<br />
<br />
==== TERM Environmental Variable ====<br />
<br />
Allow xterm to report the '''TERM '''variable correctly. '''Do not '''set the TERM variable from your ''~/.bashrc'' or ''~/.bash_profile'' or similar file. The terminal itself should report the correct TERM to the system so that the proper ''terminfo'' file will be used. Two usable terminfo files are ''xterm, ''and ''xterm-256color.''<br />
<br />
Without setting TERM explicitly, xterm should report {{ic|$TERM}} as {{ic|xterm}}. You can check this from within xterm using either of these commands:<br />
<br />
$ echo $TERM<br />
$ tset -q<br />
<br />
When TERM is not set explicitly, color schemes for some programs, such as ''vim, ''may not appear until a key is pressed or some other input occurs. This can be remedied with this resource setting:<br />
<br />
xterm*termName: xterm-256color<br />
<br />
==== UTF-8 ====<br />
<br />
Make certain your [[locale#Setting_the_locale|locale settings]] are correct for UTF-8. Adding the following line to your resource file will then make xterm interpret all incoming data as UTF-8 encoded:<br />
<br />
XTerm*locale: true<br />
<br />
==== Making xterm's 'Alt' key behaves as on other terminal emulators ====<br />
<br />
The default {{Ic|Alt}} key behavior on {{Ic|xterm}} is a modifier to send eight bit input characters so that user can insert {{Ic|æ}} by pressing {{Ic|Alt+f}} inside {{Ic|xterm}}.<br />
<br />
This behavior is different from terminal emulators such as {{Ic|gnome-terminal}} and {{Ic|konsole}}, which uses {{Ic|Alt}} as modifier to sends {{Ic|^[}} (escape} character.<br />
<br />
If you want {{ic|Alt}} key on {{Ic|xterm}} to behave as on other terminal emulators, i.e. sends {{Ic|^[}} instead of acts as eight bit modifier, you will need to put on of the following line in your resource file.<br />
<br />
XTerm*metaSendsEscape: true<br />
XTerm*eightBitInput: false<br />
<br />
==== Fix the backspace key ====<br />
<br />
On Archlinux, {{ic|xterm}} sends {{ic|^H}} key when backspace is pressed. This breaks {{ic|Ctrl+H}} key combination on [[Emacs]].<br />
The workaround is making {{ic|xterm}} sends {{ic|^?}} when backspace is pressed, by adding the following lines to X resource file.<br />
<br />
XTerm*backarrowKey: false<br />
XTerm*ttyModes: erase ^?<br />
<br />
=== Scrolling ===<br />
As new lines are written to the bottom of the xterm window, older lines disappear from the top. To scroll up and down through the off-screen lines one can use the mouse wheel, the key combinations {{ic|Shift+PageUp}} and {{ic|Shift+PageDown}}, or the scrollbar.<br />
<br />
By default, 1024 lines are saved. You can change the number of saved lines with the {{ic|saveLines}} resource,<br />
Xterm*saveLines: 4096<br />
<br />
Other X resources that affect scrolling are {{ic|jumpScroll}}, set to {{ic|true}} by default, and {{ic|multiScroll}} and {{ic|fastScroll}}, both of which default to {{ic|false}}. To scroll inside an [[#VT_Options_menu|alternate screen]], set {{ic|alternateScroll}} to {{ic|true}}.<br />
<br />
==== The Scrollbar ====<br />
The scrollbar is not shown by default. It can be made visible by a menu selection, by command line options, or by setting resource values. It can be made to appear to the left or right of the window and its visual appearance can be modified through resource settings.<br />
<br />
The scrollbar operates differently from what you may be accustomed to using.<br />
*To scroll down:<br />
:– Click on the scrollbar with the left mouse button.<br />
:– Click on the scrollbar below the ''thumb'' with the middle mouse button.<br />
*To scroll up:<br />
:– Click on the scrollbar with the right mouse button.<br />
:– Click on the scrollbar above the ''thumb'' with the middle mouse button.<br />
*To position text, moving in either direction:<br />
:– Grab the ''thumb'' and use "click-and-drag" with the middle mouse button.<br />
<br />
===Menus===<br />
The Archlinux version of xterm is compiled with the ''toolbar, ''or ''menubar, ''disabled. The menus are still available as ''popups ''when you press {{ic|Ctrl+MouseButton}} within the xterm window. The actions invoked by the menu items can often be accomplished using command line options or by setting resource values.<br />
<br />
{{Tip|If the popup menu windows show only as small boxes, it is probably because you have a line similar to this, {{ic|xterm*geometry: 80x32}}, in your resources file. This ''does ''start xterm in an 80 column by 32 row main window, but it also forces the menu windows to be 80 pixels by 32 pixels! Replace the incorrect line with this:<br />
{{bc|xterm*VT100.geometry: 80x32}}}}<br />
<br />
Some of the menu options are discussed below.<br />
<br />
====Main Options menu====<br />
'''''Ctrl + LeftMouse'''''<br />
<br />
*{{ic|Secure Keyboard}} attempts to ensure only the xterm window, and no other application, receives your keystrokes. The display changes to reverse video when it is invoked. If the display is not in reverse video, the ''Secure Keyboard ''mode is not in effect. Please read the "SECURITY" section of the xterm man page for this option's limitations.<br />
<br />
*{{ic|Allow SendEvents}} allows other processes to send keypress and mouse events to the xterm window. Because of the security risk, do not enable this unless you are very sure you know what you are doing.<br />
<br />
*{{ic|Log to File}} – The log file will be named {{ic|Xterm.log.hostname.yyyy.mm.dd.hh.mm.ss.XXXXXX}}. This file will contain all the printed output ''and all cursor movements. ''Logging may be a security risk.<br />
<br />
*The six {{ic|Send *** Signal}} menu items are not often useful, except when your keyboard fails. {{ic|HUP}}, {{ic|TERM}} and {{ic|KILL}} will close the xterm window. {{ic|KILL}} should be avoided, as it does not allow any cleanup code to run.<br />
<br />
*The {{ic|Quit}} menu item will also close the xterm window – it is the same as sending a {{ic|HUP}} signal. Most users will use the keyboard combination {{ic|Ctrl+d}} or will type {{ic|exit}} to close an xterm instance.<br />
====VT Options menu====<br />
'''''Ctrl + MiddleMouse'''''<br />
*{{ic|Select to Clipboard}} – Normally, selected text is stored in PRIMARY, to be pasted with {{ic|Shift+Insert}} or by using the middle mouse button. By toggling this option to ''on, ''selected text will use CLIPBOARD, allowing you to paste the text selected in an xterm window into a GUI application using {{ic|Ctrl+v}}. The corresponding XTerm resource is {{ic|selectToClipboard}}.<br />
<br />
*{{ic|Show Alternate Screen}} – When you use an a terminal application such as ''vim, ''or ''less, ''the alternate screen is opened. The main VT window, now hidden, remains in memory. You can view this main window, but not issue any commands in it, by toggling this menu option. You are able to select and copy text from this main window.<br />
<br />
{{Tip|Suspending the process running in the Alternate Screen and then resuming it provides more functionality than using {{ic|Show Alternate Screen}}. With a ''bash'' shell, pressing {{ic|Ctrl+z}} suspends the process; issuing the command {{ic|fg}} then resumes it.}}<br />
<br />
*{{ic|Show Tek Window}} and {{ic|Switch to Tek Mode}} – The [[Wikipedia:Tektronix 4010|Tektronix 4014]] was a graphics terminal from the 1970s used for CAD and plotting applications. The command line program {{ic|graph}}, from {{Pkg|plotutils}}, and the application {{Pkg|gnuplot}} can be made to use xterm's Tek emulation; most people will prefer more modern display options for charting data. See the [[#Tek 4014 demonstration]], below.<br />
<br />
====VT Fonts menu====<br />
'''''Ctrl + RightMouse'''''<br />
<br />
*When using XLFD fonts, the first seven menu items will change the font face and the font size used in the current xterm window. If you are using an Xft font, only the font size will change, the font face will not change with the different selections, .<br />
<br />
{{Tip|{{ic|Unreadable}} and {{ic|Tiny}} are useful if you wish to keep an eye on a process but do not want to devote a large amount of screen space to the terminal window. An example use might be a lengthy compilation process when you only want to see that the operation completes.}}<br />
<br />
*{{ic|Selection}}, when using XLFD font names, allows you to switch to the font name stored in the PRIMARY selection (or CLIPBOARD).<br />
<br />
====Tek Options menu==== <br />
From the '''Tek Window,''' '''''Ctrl + MiddleMouse'''''<br />
<br />
The first section's options allow you to change the Tek window font size. The second set of options are used to move the focus between the Tek emulation window and the main, or ''VT, ''window and to close or hide the Tek window.<br />
<br />
===Copy and paste===<br />
First, highlighting text using the mouse in an xterm (or alternatively another application) will select the text to copy, then clicking the mouse middle-button will paste that highlighted text. Also the key combination {{ic|Shift+Insert}} will paste highlighted text, but only within an xterm.<br />
<br />
====PRIMARY or CLIPBOARD====<br />
<br />
{{Expansion|Separate shortcuts for CLIPBOARD can be defined instead of using ''Select to clipboard'', similar to VTE-like terminals. See e.g [https://github.com/AladW/arch-i3/blob/master/.Xresources#L17]}}<br />
<br />
By default, xterm, and many other applications running under X, copy highlighted text into a buffer called the PRIMARY selection. The PRIMARY selection is short-lived; the text is immediately replaced by a new PRIMARY selection as soon as another piece of text is highlighted. Some applications will allow you to paste PRIMARY selections by using the middle-mouse, but not {{ic|Shift+Insert}}, and some other applications may not allow pasting from PRIMARY entirely.<br />
<br />
There is another buffer used for copied text called the CLIPBOARD selection. The text in the CLIPBOARD is long-lived, remaining available until a user actively overwrites it. Applications that use {{ic|Ctrl+c}} and {{ic|Ctrl+x}} for text copying and cutting operations, and {{ic|Ctrl+v}} for pasting, are using the CLIPBOARD.<br />
<br />
The fleeting nature of the PRIMARY selection, where copied text is lost as soon as another selection is highlighted, annoys some users. Xterm allows the user to switch between the use of PRIMARY and CLIPBOARD using {{ic|Select to Clipboard}} on the [[#VT Options menu]] or with the {{ic|selectToClipboard}} resource.<br />
<br />
====PRIMARY and CLIPBOARD====<br />
<br />
With the above setting you can select if you want to use PRIMARY or CLIPBOARD, but to use both you need a 'hack'. For example, put this in your .Xresources:<br />
<br />
XTerm*VT100.translations: #override <Btn1Up>: select-end(PRIMARY, CLIPBOARD, CUT_BUFFER0)<br />
<br />
====Selecting text====<br />
The new user usually discovers that text may be selected using a "click-and-drag" with the left mouse button. Double-clicking will select a word, where a word is defined as consecutive alphabetic characters plus the underscore, or the Basic Regular Expression (BRE) {{ic|[A-Za-z_]}}. Triple-clicking selects a line, with a "tab" character usually copied as multiple "space" characters.<br />
<br />
Another way of selecting text, especially useful when copying more than one full screen, is:<br />
#Left-click at the start of the intended selection.<br />
#Scroll to where the end of the selection is visible.<br />
#Right-click at the end of the selection.<br />
You do not have to be precise immediately with the right-click – any highlighted selection may be extended or shortened by using a right-click.<br />
<br />
You can clear any selected text by left-clicking once, anywhere within the xterm window.<br />
<br />
==Colors==<br />
Xterm defaults to black text, the ''foreground'' color, on a white ''background.'' The foreground and background colors can be reversed using the [[#VT Options menu|VT Options menu]] or with the {{ic|-rv}} command line option.<br />
$ xterm -rv<br />
<br />
Alternatively, the same thing can be accomplished with the following [[X_resources|X resources parameter]] (do not forget to [[X_resources#Parsing_.Xresources|reread the new resource afterwards]]{{Broken section link}}!):<br />
XTerm*reverseVideo: on<br />
<br />
Xterm's foreground color (the text color) and the background color may be set from the command line, using the options {{ic|-fg}} and {{ic|-bg}} respectively.<br />
xterm -fg PapayaWhip -bg "rgb:00/00/80"<br />
<br />
The first sixteen terminal colors, as well as the foreground and background colors, may be set from an [[X resources]] file:<br />
{{bc|XTerm*foreground: rgb:b2/b2/b2<br />
XTerm*background: rgb:08/08/08<br />
XTerm*color0: rgb:28/28/28<br />
<br />
! ...Lines omitted...<br />
<br />
XTerm*color15: rgb:e4/e4/e4}}<br />
{{Note|Colors for applications that use the X libraries may be specified in many different ways.<br />
<br />
Some colors can be specified by assigned names. If {{Pkg|emacs}} or {{Pkg|vim}} has been installed, you can examine {{ic|/usr/share/emacs/*/etc/rgb.txt}} or {{ic|/usr/share/vim/*/rgb.txt}} to view the list of color names with their decimal RGB values. Colors may also be specified using hexadecimal RGB values with the format {{ic|rgb:RR/GG/BB}}, or the older and not encouraged syntax {{ic|#RRGGBB}}.<br />
<br />
The color {{ic|PapayaWhip}} is the same as {{ic|rgb:ff/ef/d5}}, which is the same as {{ic|#ffefd5}}.<br />
<br />
See '''man(7) X, '''from {{Pkg|xorg-docs}}, for a more complete description of color syntax.}}<br />
Many suggestions for color schemes can be viewed in the forum thread, [https://bbs.archlinux.org/viewtopic.php?id=51818&p=1 Terminal Colour Scheme Screenshots].<br />
{{Tip|Many people specify colors in their X resources files without specifying an application class or application instance:<br />
{{bc|*foreground: rgb:b2/b2/b2<br />
*background: rgb:08/08/08}}<br />
The above example sets the foreground and background color values for all ''Xlib'' applications (xclock, xfontsel, and others) that use these resources. This is a nice, easy way to achieve a unified color scheme.}}<br />
<br />
==Fonts==<br />
===Default fonts===<br />
Xterm's default font is the bitmap font named by the [[X Logical Font Description]] alias {{ic|fixed}}, often resolving to<br />
-misc-fixed-medium-r-semicondensed--13-120-75-75-c-60-iso8859-?<br />
This font, also aliased to the name {{ic|6x13}}, has remakably wide coverage for unicode glyphs. The default "TrueType" font is the 14‑point font matched by the name {{ic|mono}}. The ''FreeType ''font that will be used can be found with this command:<br />
$ fc-match mono<br />
<br />
Fonts can be specified from the command line, with the options {{ic|-fn}} for bitmap font names and {{ic|-fa}} for Xft names. The example below allows you to alternate between the two fonts by toggling {{ic|TrueType Fonts}} from the [[#VT Fonts menu]].<br />
{{bc|<nowiki>$ xterm -fn 7x13 -fa "Liberation Mono:size=10:antialias=false"</nowiki>}}<br />
For a more permanent change, the default fonts may be set in an [[X resources]] file:<br />
{{bc|<nowiki>xterm*faceName: Liberation Mono:size=10:antialias=false</nowiki><br />
xterm*font: 7x13}}<br />
<br />
{{Note|There is a long-standing bug in xterm that prevents the command line option {{ic|-fn}} working correctly when {{ic|faceName}} has been set in a resource file. One solution is to set the resource {{ic|renderFont}} to {{ic|false}} on the command line.<br />
{{bc|$ xterm -fn 8x13 # If this command does not set the font,<br />
$ xterm -fn 8x13 -xrm "*renderFont:false" # set the 'renderFont' resource to 'false'.}}<br />
Perhaps easier, you can just toggle {{ic|TrueType Fonts}} from the [[#VT Fonts menu]] in the terminal window.}}<br />
<br />
===Bold and underlined fonts===<br />
Italic fonts are shown as underlined characters when using XLFD names in xterm. TrueType fonts should use an oblique typeface.<br />
<br />
If you do not specify a bold font at the command line, {{ic|-fb}}, or through the {{ic|boldFont}} resource, xterm will attempt to find a bold font matching the normal font. If a matching font is not found, the bold font will be created by "overstriking" the normal font.<br />
<br />
===CJK Fonts===<br />
Many fonts do not contain glyphs for the double width Chinese, Japanese and Korean languages. Other terminal emulators such as [[urxvt]] may be better suited if you frequently work with these languages.<br />
<br />
Using bitmapped XLFD fonts with CJK has many pitfalls in xterm. It is much easier to use TrueType fonts for CJK display, using the {{ic|faceNameDoublesize}} resource. This example uses ''DejaVu Sans Mono'' as the normal font and ''WenQuanYi Bitmap Song'' as the double width font:<br />
{{bc|<nowiki>xterm*faceName: DejaVu Sans Mono:style=Book:antialias=false</nowiki><br />
xterm*faceNameDoublesize: WenQuanYi Bitmap Song<br />
xterm*faceSize: 8}}<br />
<br />
==Tips and tricks==<br />
===Automatic transparency===<br />
Install the package {{pkg|transset-df}} and a [[Wikipedia:Compositing window manager|composite manager]] such as [[Xcompmgr]]. Then add the following line to your {{ic|~/.bashrc}}:<br />
[ -n "$XTERM_VERSION" ] && transset-df --id "$WINDOWID" >/dev/null<br />
<br />
Now, each time you launch a shell in an xterm and a composite manager is running, the xterm window will be transparent.<br />
The test in front of {{ic|transset-df}} keeps transet from executing if {{ic|XTERM_VERSION}} is not defined. Note that your terminal will not be transparent if you launch a program other than a shell this way. It is probably possible to work around this if you want the functionality.<br />
<br />
Also see [[Per-application transparency]].<br />
<br />
===Enable bell urgency===<br />
Add the following line to your {{ic|~/.Xresources}} file:<br />
<br />
xterm*bellIsUrgent: true<br />
<br />
===Font tips===<br />
<br />
====Use color in place of bold and italics====<br />
When using small font sizes, bold or italic characters may be difficult to read. One solution is to turn off bolding and underlining or italics and use color instead. This example does just that:<br />
{{bc|! Forbid bold font faces; bold type is light blue.<br />
XTerm*colorBDMode: true<br />
XTerm*colorBD: rgb:82/a4/d3<br />
! Do not underscore text, underlined text is white.<br />
XTerm*colorULMode: true<br />
XTerm*colorUL: rgb:e4/e4/e4}}<br />
<br />
====Adjust line spacing====<br />
Lines of text can sometimes be too close together, or they may appear to be too widely spaced. For one example, using ''DejaVu Sans Mono, ''the low underscore glyph may butt against CJK glyphs or the cursor block in the line below. Line spacing, called ''leading ''by typographers, can be adjusted using the {{ic|scaleHeight}} resource. Here, the line spacing is widened:<br />
XTerm*scaleHeight: 1.01<br />
Valid values for {{ic|scaleHeight}} range from {{ic|0.9}} to {{ic|1.5}}, with {{ic|1.0}} being the default.<br />
===Remove black border===<br />
Xterm has a black border in some cases, you can disable this by adding the following line to your {{ic|~/.Xresources}} file.<br />
<br />
xterm*borderWidth: 0<br />
<br />
===Tek 4014 demonstration===<br />
If you have {{Pkg|plotutils}} installed, you can use xterm's Tektronix 4014 emulation to view some of the plotutils package's test files. Open the Tek window from the [[#VT Options menu]] menu item {{ic|Switch to Tek Mode}} or start a new xterm instance using this command:<br />
$ xterm -t -tn tek4014<br />
Your PS1 prompt will not render correctly, if it appears at all. In the new window, enter the command,<br />
cat /usr/share/tek2plot/dmerc.tek<br />
A world map will appear in the Tek window. You can also view other {{ic|*.tek}} files from that same directory. To close the Tek window, one can use the xterm menus.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Flickering on scroll ===<br />
<br />
{{Warning|Double buffering may cause non-bitmap fonts to render incorrectly.}}<br />
<br />
Rebuild xterm using [[ABS]] and include the {{ic|--enable-double-buffer}} flag:<br />
<br />
./configure --prefix=/usr \<br />
...<br />
--with-utempter \<br />
--enable-double-buffer<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?id=146023 Xterm modifications] for details.<br />
<br />
== See also ==<br />
<br />
* [http://lukas.zapletalovi.com/2013/07/hidden-gems-of-xterm.html Hidden gems of Xterm]<br />
* [http://www.in-ulm.de/~mascheck/X11/XTerm Commented XTerm resources]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=Talk:Xterm&diff=454816Talk:Xterm2016-10-23T09:50:41Z<p>Alive4ever: /* Fix the alt key section */ typo fix</p>
<hr />
<div>="some unusual features"=<br />
What is this referring to? I'm curious to know. [[User:Brianbaligad|Brianbaligad]] ([[User talk:Brianbaligad|talk]]) 06:07, 20 October 2013 (UTC)<br />
:The Tek terminal emulation, changing from Xlfd to xft type faces by a menu selection, and the Ctrl-Mouseclick pop-up menus, all seem unusual to me. Being able to customize the mouse-click text selections using regular expressions is a newer feature of xterm that might be considered unusual. Too bad the wiki article doesn't cover that how-to.<br />
:[[User:Thisoldman|Thisoldman]] ([[User talk:Thisoldman|talk]]) 14:06, 20 October 2013 (UTC)<br />
<br />
=trannset-df with xterm emulators=<br />
I use xfce-terminal. I think it emulates xterm when compatibility is needed, is it the same as being defined? 'Cause I'm getting errors. [[User:Lelele|Lelele]] ([[User talk:Lelele|talk]])<br />
:Xfce-terminal does not set or use the $TERM variable in the same way as xterm. Xfce-terminal man pages refer to termcap and Archlinux uses terminfo. See this [https://bbs.archlinux.org/viewtopic.php?id=175581 forum thread]. <br />
:--[[User:Thisoldman|Thisoldman]] ([[User talk:Thisoldman|talk]]) 14:51, 25 January 2014 (UTC)<br />
<br />
=Fix the alt key section=<br />
For a user which is customized to emacs keybinding, such as {{ic|alt+f}} and {{ic|alt+b}} to move a word forward and backward, {{ic|alt+d}} and {{ic|alt+backspace}} to delete a word forward and backward, one may want xterm to behave as such. For this type of user, {{ic|XTerm*eightBitInput: false}} or {{ic|XTerm*metaSendsEscape: true}} is needed so that {{ic|xterm}} behaves as expected.<br />
<br />
For a user which is customized to default xterm settings, such as {{ic|alt+d}} to type {{ic|ä}} and {{ic|alt+f}} to type {{ic|æ}}, the default {{ic|xterm}} behavior, i.e. {{Ic|XTerm*eightBitInput: true}} and {{Ic|XTerm*metaSendsEscape: false}}, is more suitable.<br />
[[User:Alive4ever|Alive4ever]] ([[User talk:Alive4ever|talk]])</div>Alive4everhttps://wiki.archlinux.org/index.php?title=Talk:Xterm&diff=454815Talk:Xterm2016-10-23T09:49:38Z<p>Alive4ever: /* Fix the alt key section */ more missing {{ic|}} fix</p>
<hr />
<div>="some unusual features"=<br />
What is this referring to? I'm curious to know. [[User:Brianbaligad|Brianbaligad]] ([[User talk:Brianbaligad|talk]]) 06:07, 20 October 2013 (UTC)<br />
:The Tek terminal emulation, changing from Xlfd to xft type faces by a menu selection, and the Ctrl-Mouseclick pop-up menus, all seem unusual to me. Being able to customize the mouse-click text selections using regular expressions is a newer feature of xterm that might be considered unusual. Too bad the wiki article doesn't cover that how-to.<br />
:[[User:Thisoldman|Thisoldman]] ([[User talk:Thisoldman|talk]]) 14:06, 20 October 2013 (UTC)<br />
<br />
=trannset-df with xterm emulators=<br />
I use xfce-terminal. I think it emulates xterm when compatibility is needed, is it the same as being defined? 'Cause I'm getting errors. [[User:Lelele|Lelele]] ([[User talk:Lelele|talk]])<br />
:Xfce-terminal does not set or use the $TERM variable in the same way as xterm. Xfce-terminal man pages refer to termcap and Archlinux uses terminfo. See this [https://bbs.archlinux.org/viewtopic.php?id=175581 forum thread]. <br />
:--[[User:Thisoldman|Thisoldman]] ([[User talk:Thisoldman|talk]]) 14:51, 25 January 2014 (UTC)<br />
<br />
=Fix the alt key section=<br />
For a user which is customized to emacs keybinding, such as {{ic|alt+f}} and {{ic|alt+b}} to move a word forward and backward, {{ic|alt+d}} and {{ic|alt+backspace}} to delete a word forward and backward, one may want xterm to behave as such. For this type of user, {{ic|XTerm*eightBitInput: false}} or {{ic|XTerm*metaSensEscape: true}} is needed so that {{ic|xterm}} behaves as expected.<br />
<br />
For a user which is customized to default xterm settings, such as {{ic|alt+d}} to type {{ic|ä}} and {{ic|alt+f}} to type {{ic|æ}}, the default {{ic|xterm}} behavior, i.e. {{Ic|XTerm*eightBitInput: true}} and {{Ic|XTerm*metaSendsEscape: false}}, is more suitable.<br />
[[User:Alive4ever|Alive4ever]] ([[User talk:Alive4ever|talk]])</div>Alive4everhttps://wiki.archlinux.org/index.php?title=Talk:Xterm&diff=454814Talk:Xterm2016-10-23T09:48:42Z<p>Alive4ever: /* Fix the alt key section */ fix missing {{ic|}} tags</p>
<hr />
<div>="some unusual features"=<br />
What is this referring to? I'm curious to know. [[User:Brianbaligad|Brianbaligad]] ([[User talk:Brianbaligad|talk]]) 06:07, 20 October 2013 (UTC)<br />
:The Tek terminal emulation, changing from Xlfd to xft type faces by a menu selection, and the Ctrl-Mouseclick pop-up menus, all seem unusual to me. Being able to customize the mouse-click text selections using regular expressions is a newer feature of xterm that might be considered unusual. Too bad the wiki article doesn't cover that how-to.<br />
:[[User:Thisoldman|Thisoldman]] ([[User talk:Thisoldman|talk]]) 14:06, 20 October 2013 (UTC)<br />
<br />
=trannset-df with xterm emulators=<br />
I use xfce-terminal. I think it emulates xterm when compatibility is needed, is it the same as being defined? 'Cause I'm getting errors. [[User:Lelele|Lelele]] ([[User talk:Lelele|talk]])<br />
:Xfce-terminal does not set or use the $TERM variable in the same way as xterm. Xfce-terminal man pages refer to termcap and Archlinux uses terminfo. See this [https://bbs.archlinux.org/viewtopic.php?id=175581 forum thread]. <br />
:--[[User:Thisoldman|Thisoldman]] ([[User talk:Thisoldman|talk]]) 14:51, 25 January 2014 (UTC)<br />
<br />
=Fix the alt key section=<br />
For a user which is customized to emacs keybinding, such as {{ic|alt+f}} and {{ic|alt+b}} to move a word forward and backward, {{ic|alt+d}} and {{ic|alt+backspace}} to delete a word forward and backward, one may want xterm to behave as such. For this type of user, {{ic|XTerm*eightBitInput: false}} or {{XTerm*metaSensEscape: true}} is needed so that {{ic|xterm}} behaves as expected.<br />
<br />
For a user which is customized to default xterm settings, such as {{alt+d}} to type {{ic|ä}} and {{alt+f}} to type {{ic|æ}}, the default {{ic|xterm}} behavior, i.e. {{Ic|XTerm*eightBitInput: true}} and {{Ic|XTerm*metaSendsEscape: false}}, is more suitable.<br />
[[User:Alive4ever|Alive4ever]] ([[User talk:Alive4ever|talk]])</div>Alive4everhttps://wiki.archlinux.org/index.php?title=Talk:Xterm&diff=454813Talk:Xterm2016-10-23T09:47:39Z<p>Alive4ever: Talk: Fixing alt behavior</p>
<hr />
<div>="some unusual features"=<br />
What is this referring to? I'm curious to know. [[User:Brianbaligad|Brianbaligad]] ([[User talk:Brianbaligad|talk]]) 06:07, 20 October 2013 (UTC)<br />
:The Tek terminal emulation, changing from Xlfd to xft type faces by a menu selection, and the Ctrl-Mouseclick pop-up menus, all seem unusual to me. Being able to customize the mouse-click text selections using regular expressions is a newer feature of xterm that might be considered unusual. Too bad the wiki article doesn't cover that how-to.<br />
:[[User:Thisoldman|Thisoldman]] ([[User talk:Thisoldman|talk]]) 14:06, 20 October 2013 (UTC)<br />
<br />
=trannset-df with xterm emulators=<br />
I use xfce-terminal. I think it emulates xterm when compatibility is needed, is it the same as being defined? 'Cause I'm getting errors. [[User:Lelele|Lelele]] ([[User talk:Lelele|talk]])<br />
:Xfce-terminal does not set or use the $TERM variable in the same way as xterm. Xfce-terminal man pages refer to termcap and Archlinux uses terminfo. See this [https://bbs.archlinux.org/viewtopic.php?id=175581 forum thread]. <br />
:--[[User:Thisoldman|Thisoldman]] ([[User talk:Thisoldman|talk]]) 14:51, 25 January 2014 (UTC)<br />
<br />
=Fix the alt key section=<br />
For a user which is customized to emacs keybinding, such as {{alt+f}} and {{alt+b}} to move a word forward and backward, {{alt+d}} and {{alt+backspace}} to delete a word forward and backward, one may want xterm to behave as such. For this type of user, {{XTerm*eightBitInput: false}} or {{XTerm*metaSensEscape: true}} is needed so that {{ic|xterm}} behaves as expected.<br />
<br />
For a user which is customized to default xterm settings, such as {{alt+d}} to type {{ic|ä}} and {{alt+f}} to type {{ic|æ}}, the default {{ic|xterm}} behavior, i.e. {{Ic|XTerm*eightBitInput: true}} and {{Ic|XTerm*metaSendsEscape: false}}, is more suitable.<br />
[[User:Alive4ever|Alive4ever]] ([[User talk:Alive4ever|talk]])</div>Alive4everhttps://wiki.archlinux.org/index.php?title=Xterm&diff=454811Xterm2016-10-23T09:18:39Z<p>Alive4ever: /* Resource file settings */ Added backspace key configuration so that xterm sends ^? instead off ^H for backspace as on other terminal emulators</p>
<hr />
<div>[[Category:Terminal emulators]]<br />
[[de:Xterm]]<br />
[[fr:Xterm]]<br />
[[ja:Xterm]]<br />
[[ru:Xterm]]<br />
'''xterm''' is the standard [[Wikipedia:Terminal emulator|terminal emulator]] for the [[X Window System]]. It is highly configurable and has many useful and some unusual features.<br />
<br />
==Configuration==<br />
=== Resource file settings ===<br />
<br />
There are several options you can set in your [[X resources]] files that may make this terminal emulator much easier to use. See {{ic|man xterm}} for a complete list.<br />
<br />
==== TERM Environmental Variable ====<br />
<br />
Allow xterm to report the '''TERM '''variable correctly. '''Do not '''set the TERM variable from your ''~/.bashrc'' or ''~/.bash_profile'' or similar file. The terminal itself should report the correct TERM to the system so that the proper ''terminfo'' file will be used. Two usable terminfo files are ''xterm, ''and ''xterm-256color.''<br />
<br />
Without setting TERM explicitly, xterm should report {{ic|$TERM}} as {{ic|xterm}}. You can check this from within xterm using either of these commands:<br />
<br />
$ echo $TERM<br />
$ tset -q<br />
<br />
When TERM is not set explicitly, color schemes for some programs, such as ''vim, ''may not appear until a key is pressed or some other input occurs. This can be remedied with this resource setting:<br />
<br />
xterm*termName: xterm-256color<br />
<br />
==== UTF-8 ====<br />
<br />
Make certain your [[locale#Setting_the_locale|locale settings]] are correct for UTF-8. Adding the following line to your resource file will then make xterm interpret all incoming data as UTF-8 encoded:<br />
<br />
XTerm*locale: true<br />
<br />
==== Fix the 'Alt' key ====<br />
<br />
If you use the {{ic|Alt}} key for keyboard shortcuts, you will need this in your resource file:<br />
<br />
XTerm*metaSendsEscape: true<br />
<br />
==== Fix the backspace key ====<br />
<br />
On Archlinux, {{ic|xterm}} sends {{ic|^H}} key when backspace is pressed. This breaks {{ic|Ctrl+H}} key combination on [[Emacs]].<br />
The workaround is making {{ic|xterm}} sends {{ic|^?}} when backspace is pressed, by adding the following lines to X resource file.<br />
<br />
XTerm*backarrowKey: false<br />
XTerm*ttyModes: erase ^?<br />
<br />
=== Scrolling ===<br />
As new lines are written to the bottom of the xterm window, older lines disappear from the top. To scroll up and down through the off-screen lines one can use the mouse wheel, the key combinations {{ic|Shift+PageUp}} and {{ic|Shift+PageDown}}, or the scrollbar.<br />
<br />
By default, 1024 lines are saved. You can change the number of saved lines with the {{ic|saveLines}} resource,<br />
Xterm*saveLines: 4096<br />
<br />
Other X resources that affect scrolling are {{ic|jumpScroll}}, set to {{ic|true}} by default, and {{ic|multiScroll}} and {{ic|fastScroll}}, both of which default to {{ic|false}}. To scroll inside an [[#VT_Options_menu|alternate screen]], set {{ic|alternateScroll}} to {{ic|true}}.<br />
<br />
==== The Scrollbar ====<br />
The scrollbar is not shown by default. It can be made visible by a menu selection, by command line options, or by setting resource values. It can be made to appear to the left or right of the window and its visual appearance can be modified through resource settings.<br />
<br />
The scrollbar operates differently from what you may be accustomed to using.<br />
*To scroll down:<br />
:– Click on the scrollbar with the left mouse button.<br />
:– Click on the scrollbar below the ''thumb'' with the middle mouse button.<br />
*To scroll up:<br />
:– Click on the scrollbar with the right mouse button.<br />
:– Click on the scrollbar above the ''thumb'' with the middle mouse button.<br />
*To position text, moving in either direction:<br />
:– Grab the ''thumb'' and use "click-and-drag" with the middle mouse button.<br />
<br />
===Menus===<br />
The Archlinux version of xterm is compiled with the ''toolbar, ''or ''menubar, ''disabled. The menus are still available as ''popups ''when you press {{ic|Ctrl+MouseButton}} within the xterm window. The actions invoked by the menu items can often be accomplished using command line options or by setting resource values.<br />
<br />
{{Tip|If the popup menu windows show only as small boxes, it is probably because you have a line similar to this, {{ic|xterm*geometry: 80x32}}, in your resources file. This ''does ''start xterm in an 80 column by 32 row main window, but it also forces the menu windows to be 80 pixels by 32 pixels! Replace the incorrect line with this:<br />
{{bc|xterm*VT100.geometry: 80x32}}}}<br />
<br />
Some of the menu options are discussed below.<br />
<br />
====Main Options menu====<br />
'''''Ctrl + LeftMouse'''''<br />
<br />
*{{ic|Secure Keyboard}} attempts to ensure only the xterm window, and no other application, receives your keystrokes. The display changes to reverse video when it is invoked. If the display is not in reverse video, the ''Secure Keyboard ''mode is not in effect. Please read the "SECURITY" section of the xterm man page for this option's limitations.<br />
<br />
*{{ic|Allow SendEvents}} allows other processes to send keypress and mouse events to the xterm window. Because of the security risk, do not enable this unless you are very sure you know what you are doing.<br />
<br />
*{{ic|Log to File}} – The log file will be named {{ic|Xterm.log.hostname.yyyy.mm.dd.hh.mm.ss.XXXXXX}}. This file will contain all the printed output ''and all cursor movements. ''Logging may be a security risk.<br />
<br />
*The six {{ic|Send *** Signal}} menu items are not often useful, except when your keyboard fails. {{ic|HUP}}, {{ic|TERM}} and {{ic|KILL}} will close the xterm window. {{ic|KILL}} should be avoided, as it does not allow any cleanup code to run.<br />
<br />
*The {{ic|Quit}} menu item will also close the xterm window – it is the same as sending a {{ic|HUP}} signal. Most users will use the keyboard combination {{ic|Ctrl+d}} or will type {{ic|exit}} to close an xterm instance.<br />
====VT Options menu====<br />
'''''Ctrl + MiddleMouse'''''<br />
*{{ic|Select to Clipboard}} – Normally, selected text is stored in PRIMARY, to be pasted with {{ic|Shift+Insert}} or by using the middle mouse button. By toggling this option to ''on, ''selected text will use CLIPBOARD, allowing you to paste the text selected in an xterm window into a GUI application using {{ic|Ctrl+v}}. The corresponding XTerm resource is {{ic|selectToClipboard}}.<br />
<br />
*{{ic|Show Alternate Screen}} – When you use an a terminal application such as ''vim, ''or ''less, ''the alternate screen is opened. The main VT window, now hidden, remains in memory. You can view this main window, but not issue any commands in it, by toggling this menu option. You are able to select and copy text from this main window.<br />
<br />
{{Tip|Suspending the process running in the Alternate Screen and then resuming it provides more functionality than using {{ic|Show Alternate Screen}}. With a ''bash'' shell, pressing {{ic|Ctrl+z}} suspends the process; issuing the command {{ic|fg}} then resumes it.}}<br />
<br />
*{{ic|Show Tek Window}} and {{ic|Switch to Tek Mode}} – The [[Wikipedia:Tektronix 4010|Tektronix 4014]] was a graphics terminal from the 1970s used for CAD and plotting applications. The command line program {{ic|graph}}, from {{Pkg|plotutils}}, and the application {{Pkg|gnuplot}} can be made to use xterm's Tek emulation; most people will prefer more modern display options for charting data. See the [[#Tek 4014 demonstration]], below.<br />
<br />
====VT Fonts menu====<br />
'''''Ctrl + RightMouse'''''<br />
<br />
*When using XLFD fonts, the first seven menu items will change the font face and the font size used in the current xterm window. If you are using an Xft font, only the font size will change, the font face will not change with the different selections, .<br />
<br />
{{Tip|{{ic|Unreadable}} and {{ic|Tiny}} are useful if you wish to keep an eye on a process but do not want to devote a large amount of screen space to the terminal window. An example use might be a lengthy compilation process when you only want to see that the operation completes.}}<br />
<br />
*{{ic|Selection}}, when using XLFD font names, allows you to switch to the font name stored in the PRIMARY selection (or CLIPBOARD).<br />
<br />
====Tek Options menu==== <br />
From the '''Tek Window,''' '''''Ctrl + MiddleMouse'''''<br />
<br />
The first section's options allow you to change the Tek window font size. The second set of options are used to move the focus between the Tek emulation window and the main, or ''VT, ''window and to close or hide the Tek window.<br />
<br />
===Copy and paste===<br />
First, highlighting text using the mouse in an xterm (or alternatively another application) will select the text to copy, then clicking the mouse middle-button will paste that highlighted text. Also the key combination {{ic|Shift+Insert}} will paste highlighted text, but only within an xterm.<br />
<br />
====PRIMARY or CLIPBOARD====<br />
<br />
{{Expansion|Separate shortcuts for CLIPBOARD can be defined instead of using ''Select to clipboard'', similar to VTE-like terminals. See e.g [https://github.com/AladW/arch-i3/blob/master/.Xresources#L17]}}<br />
<br />
By default, xterm, and many other applications running under X, copy highlighted text into a buffer called the PRIMARY selection. The PRIMARY selection is short-lived; the text is immediately replaced by a new PRIMARY selection as soon as another piece of text is highlighted. Some applications will allow you to paste PRIMARY selections by using the middle-mouse, but not {{ic|Shift+Insert}}, and some other applications may not allow pasting from PRIMARY entirely.<br />
<br />
There is another buffer used for copied text called the CLIPBOARD selection. The text in the CLIPBOARD is long-lived, remaining available until a user actively overwrites it. Applications that use {{ic|Ctrl+c}} and {{ic|Ctrl+x}} for text copying and cutting operations, and {{ic|Ctrl+v}} for pasting, are using the CLIPBOARD.<br />
<br />
The fleeting nature of the PRIMARY selection, where copied text is lost as soon as another selection is highlighted, annoys some users. Xterm allows the user to switch between the use of PRIMARY and CLIPBOARD using {{ic|Select to Clipboard}} on the [[#VT Options menu]] or with the {{ic|selectToClipboard}} resource.<br />
<br />
====PRIMARY and CLIPBOARD====<br />
<br />
With the above setting you can select if you want to use PRIMARY or CLIPBOARD, but to use both you need a 'hack'. For example, put this in your .Xresources:<br />
<br />
XTerm*VT100.translations: #override <Btn1Up>: select-end(PRIMARY, CLIPBOARD, CUT_BUFFER0)<br />
<br />
====Selecting text====<br />
The new user usually discovers that text may be selected using a "click-and-drag" with the left mouse button. Double-clicking will select a word, where a word is defined as consecutive alphabetic characters plus the underscore, or the Basic Regular Expression (BRE) {{ic|[A-Za-z_]}}. Triple-clicking selects a line, with a "tab" character usually copied as multiple "space" characters.<br />
<br />
Another way of selecting text, especially useful when copying more than one full screen, is:<br />
#Left-click at the start of the intended selection.<br />
#Scroll to where the end of the selection is visible.<br />
#Right-click at the end of the selection.<br />
You do not have to be precise immediately with the right-click – any highlighted selection may be extended or shortened by using a right-click.<br />
<br />
You can clear any selected text by left-clicking once, anywhere within the xterm window.<br />
<br />
==Colors==<br />
Xterm defaults to black text, the ''foreground'' color, on a white ''background.'' The foreground and background colors can be reversed using the [[#VT Options menu|VT Options menu]] or with the {{ic|-rv}} command line option.<br />
$ xterm -rv<br />
<br />
Alternatively, the same thing can be accomplished with the following [[X_resources|X resources parameter]] (do not forget to [[X_resources#Parsing_.Xresources|reread the new resource afterwards]]{{Broken section link}}!):<br />
XTerm*reverseVideo: on<br />
<br />
Xterm's foreground color (the text color) and the background color may be set from the command line, using the options {{ic|-fg}} and {{ic|-bg}} respectively.<br />
xterm -fg PapayaWhip -bg "rgb:00/00/80"<br />
<br />
The first sixteen terminal colors, as well as the foreground and background colors, may be set from an [[X resources]] file:<br />
{{bc|XTerm*foreground: rgb:b2/b2/b2<br />
XTerm*background: rgb:08/08/08<br />
XTerm*color0: rgb:28/28/28<br />
<br />
! ...Lines omitted...<br />
<br />
XTerm*color15: rgb:e4/e4/e4}}<br />
{{Note|Colors for applications that use the X libraries may be specified in many different ways.<br />
<br />
Some colors can be specified by assigned names. If {{Pkg|emacs}} or {{Pkg|vim}} has been installed, you can examine {{ic|/usr/share/emacs/*/etc/rgb.txt}} or {{ic|/usr/share/vim/*/rgb.txt}} to view the list of color names with their decimal RGB values. Colors may also be specified using hexadecimal RGB values with the format {{ic|rgb:RR/GG/BB}}, or the older and not encouraged syntax {{ic|#RRGGBB}}.<br />
<br />
The color {{ic|PapayaWhip}} is the same as {{ic|rgb:ff/ef/d5}}, which is the same as {{ic|#ffefd5}}.<br />
<br />
See '''man(7) X, '''from {{Pkg|xorg-docs}}, for a more complete description of color syntax.}}<br />
Many suggestions for color schemes can be viewed in the forum thread, [https://bbs.archlinux.org/viewtopic.php?id=51818&p=1 Terminal Colour Scheme Screenshots].<br />
{{Tip|Many people specify colors in their X resources files without specifying an application class or application instance:<br />
{{bc|*foreground: rgb:b2/b2/b2<br />
*background: rgb:08/08/08}}<br />
The above example sets the foreground and background color values for all ''Xlib'' applications (xclock, xfontsel, and others) that use these resources. This is a nice, easy way to achieve a unified color scheme.}}<br />
<br />
==Fonts==<br />
===Default fonts===<br />
Xterm's default font is the bitmap font named by the [[X Logical Font Description]] alias {{ic|fixed}}, often resolving to<br />
-misc-fixed-medium-r-semicondensed--13-120-75-75-c-60-iso8859-?<br />
This font, also aliased to the name {{ic|6x13}}, has remakably wide coverage for unicode glyphs. The default "TrueType" font is the 14‑point font matched by the name {{ic|mono}}. The ''FreeType ''font that will be used can be found with this command:<br />
$ fc-match mono<br />
<br />
Fonts can be specified from the command line, with the options {{ic|-fn}} for bitmap font names and {{ic|-fa}} for Xft names. The example below allows you to alternate between the two fonts by toggling {{ic|TrueType Fonts}} from the [[#VT Fonts menu]].<br />
{{bc|<nowiki>$ xterm -fn 7x13 -fa "Liberation Mono:size=10:antialias=false"</nowiki>}}<br />
For a more permanent change, the default fonts may be set in an [[X resources]] file:<br />
{{bc|<nowiki>xterm*faceName: Liberation Mono:size=10:antialias=false</nowiki><br />
xterm*font: 7x13}}<br />
<br />
{{Note|There is a long-standing bug in xterm that prevents the command line option {{ic|-fn}} working correctly when {{ic|faceName}} has been set in a resource file. One solution is to set the resource {{ic|renderFont}} to {{ic|false}} on the command line.<br />
{{bc|$ xterm -fn 8x13 # If this command does not set the font,<br />
$ xterm -fn 8x13 -xrm "*renderFont:false" # set the 'renderFont' resource to 'false'.}}<br />
Perhaps easier, you can just toggle {{ic|TrueType Fonts}} from the [[#VT Fonts menu]] in the terminal window.}}<br />
<br />
===Bold and underlined fonts===<br />
Italic fonts are shown as underlined characters when using XLFD names in xterm. TrueType fonts should use an oblique typeface.<br />
<br />
If you do not specify a bold font at the command line, {{ic|-fb}}, or through the {{ic|boldFont}} resource, xterm will attempt to find a bold font matching the normal font. If a matching font is not found, the bold font will be created by "overstriking" the normal font.<br />
<br />
===CJK Fonts===<br />
Many fonts do not contain glyphs for the double width Chinese, Japanese and Korean languages. Other terminal emulators such as [[urxvt]] may be better suited if you frequently work with these languages.<br />
<br />
Using bitmapped XLFD fonts with CJK has many pitfalls in xterm. It is much easier to use TrueType fonts for CJK display, using the {{ic|faceNameDoublesize}} resource. This example uses ''DejaVu Sans Mono'' as the normal font and ''WenQuanYi Bitmap Song'' as the double width font:<br />
{{bc|<nowiki>xterm*faceName: DejaVu Sans Mono:style=Book:antialias=false</nowiki><br />
xterm*faceNameDoublesize: WenQuanYi Bitmap Song<br />
xterm*faceSize: 8}}<br />
<br />
==Tips and tricks==<br />
===Automatic transparency===<br />
Install the package {{pkg|transset-df}} and a [[Wikipedia:Compositing window manager|composite manager]] such as [[Xcompmgr]]. Then add the following line to your {{ic|~/.bashrc}}:<br />
[ -n "$XTERM_VERSION" ] && transset-df --id "$WINDOWID" >/dev/null<br />
<br />
Now, each time you launch a shell in an xterm and a composite manager is running, the xterm window will be transparent.<br />
The test in front of {{ic|transset-df}} keeps transet from executing if {{ic|XTERM_VERSION}} is not defined. Note that your terminal will not be transparent if you launch a program other than a shell this way. It is probably possible to work around this if you want the functionality.<br />
<br />
Also see [[Per-application transparency]].<br />
<br />
===Enable bell urgency===<br />
Add the following line to your {{ic|~/.Xresources}} file:<br />
<br />
xterm*bellIsUrgent: true<br />
<br />
===Font tips===<br />
<br />
====Use color in place of bold and italics====<br />
When using small font sizes, bold or italic characters may be difficult to read. One solution is to turn off bolding and underlining or italics and use color instead. This example does just that:<br />
{{bc|! Forbid bold font faces; bold type is light blue.<br />
XTerm*colorBDMode: true<br />
XTerm*colorBD: rgb:82/a4/d3<br />
! Do not underscore text, underlined text is white.<br />
XTerm*colorULMode: true<br />
XTerm*colorUL: rgb:e4/e4/e4}}<br />
<br />
====Adjust line spacing====<br />
Lines of text can sometimes be too close together, or they may appear to be too widely spaced. For one example, using ''DejaVu Sans Mono, ''the low underscore glyph may butt against CJK glyphs or the cursor block in the line below. Line spacing, called ''leading ''by typographers, can be adjusted using the {{ic|scaleHeight}} resource. Here, the line spacing is widened:<br />
XTerm*scaleHeight: 1.01<br />
Valid values for {{ic|scaleHeight}} range from {{ic|0.9}} to {{ic|1.5}}, with {{ic|1.0}} being the default.<br />
===Remove black border===<br />
Xterm has a black border in some cases, you can disable this by adding the following line to your {{ic|~/.Xresources}} file.<br />
<br />
xterm*borderWidth: 0<br />
<br />
===Tek 4014 demonstration===<br />
If you have {{Pkg|plotutils}} installed, you can use xterm's Tektronix 4014 emulation to view some of the plotutils package's test files. Open the Tek window from the [[#VT Options menu]] menu item {{ic|Switch to Tek Mode}} or start a new xterm instance using this command:<br />
$ xterm -t -tn tek4014<br />
Your PS1 prompt will not render correctly, if it appears at all. In the new window, enter the command,<br />
cat /usr/share/tek2plot/dmerc.tek<br />
A world map will appear in the Tek window. You can also view other {{ic|*.tek}} files from that same directory. To close the Tek window, one can use the xterm menus.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Flickering on scroll ===<br />
<br />
{{Warning|Double buffering may cause non-bitmap fonts to render incorrectly.}}<br />
<br />
Rebuild xterm using [[ABS]] and include the {{ic|--enable-double-buffer}} flag:<br />
<br />
./configure --prefix=/usr \<br />
...<br />
--with-utempter \<br />
--enable-double-buffer<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?id=146023 Xterm modifications] for details.<br />
<br />
== See also ==<br />
<br />
* [http://lukas.zapletalovi.com/2013/07/hidden-gems-of-xterm.html Hidden gems of Xterm]<br />
* [http://www.in-ulm.de/~mascheck/X11/XTerm Commented XTerm resources]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=Xterm&diff=454809Xterm2016-10-23T09:08:24Z<p>Alive4ever: /* Fix the 'Alt' key */ disabling eightBitInput instead off enabling metaSendsEscape</p>
<hr />
<div>[[Category:Terminal emulators]]<br />
[[de:Xterm]]<br />
[[fr:Xterm]]<br />
[[ja:Xterm]]<br />
[[ru:Xterm]]<br />
'''xterm''' is the standard [[Wikipedia:Terminal emulator|terminal emulator]] for the [[X Window System]]. It is highly configurable and has many useful and some unusual features.<br />
<br />
==Configuration==<br />
=== Resource file settings ===<br />
<br />
There are several options you can set in your [[X resources]] files that may make this terminal emulator much easier to use. See {{ic|man xterm}} for a complete list.<br />
<br />
==== TERM Environmental Variable ====<br />
<br />
Allow xterm to report the '''TERM '''variable correctly. '''Do not '''set the TERM variable from your ''~/.bashrc'' or ''~/.bash_profile'' or similar file. The terminal itself should report the correct TERM to the system so that the proper ''terminfo'' file will be used. Two usable terminfo files are ''xterm, ''and ''xterm-256color.''<br />
<br />
Without setting TERM explicitly, xterm should report {{ic|$TERM}} as {{ic|xterm}}. You can check this from within xterm using either of these commands:<br />
<br />
$ echo $TERM<br />
$ tset -q<br />
<br />
When TERM is not set explicitly, color schemes for some programs, such as ''vim, ''may not appear until a key is pressed or some other input occurs. This can be remedied with this resource setting:<br />
<br />
xterm*termName: xterm-256color<br />
<br />
==== UTF-8 ====<br />
<br />
Make certain your [[locale#Setting_the_locale|locale settings]] are correct for UTF-8. Adding the following line to your resource file will then make xterm interpret all incoming data as UTF-8 encoded:<br />
<br />
XTerm*locale: true<br />
<br />
==== Fix the 'Alt' key ====<br />
<br />
If you use the {{ic|Alt}} key for keyboard shortcuts, you will need this in your resource file:<br />
<br />
XTerm*eightBitInput: false<br />
<br />
=== Scrolling ===<br />
As new lines are written to the bottom of the xterm window, older lines disappear from the top. To scroll up and down through the off-screen lines one can use the mouse wheel, the key combinations {{ic|Shift+PageUp}} and {{ic|Shift+PageDown}}, or the scrollbar.<br />
<br />
By default, 1024 lines are saved. You can change the number of saved lines with the {{ic|saveLines}} resource,<br />
Xterm*saveLines: 4096<br />
<br />
Other X resources that affect scrolling are {{ic|jumpScroll}}, set to {{ic|true}} by default, and {{ic|multiScroll}} and {{ic|fastScroll}}, both of which default to {{ic|false}}. To scroll inside an [[#VT_Options_menu|alternate screen]], set {{ic|alternateScroll}} to {{ic|true}}.<br />
<br />
==== The Scrollbar ====<br />
The scrollbar is not shown by default. It can be made visible by a menu selection, by command line options, or by setting resource values. It can be made to appear to the left or right of the window and its visual appearance can be modified through resource settings.<br />
<br />
The scrollbar operates differently from what you may be accustomed to using.<br />
*To scroll down:<br />
:– Click on the scrollbar with the left mouse button.<br />
:– Click on the scrollbar below the ''thumb'' with the middle mouse button.<br />
*To scroll up:<br />
:– Click on the scrollbar with the right mouse button.<br />
:– Click on the scrollbar above the ''thumb'' with the middle mouse button.<br />
*To position text, moving in either direction:<br />
:– Grab the ''thumb'' and use "click-and-drag" with the middle mouse button.<br />
<br />
===Menus===<br />
The Archlinux version of xterm is compiled with the ''toolbar, ''or ''menubar, ''disabled. The menus are still available as ''popups ''when you press {{ic|Ctrl+MouseButton}} within the xterm window. The actions invoked by the menu items can often be accomplished using command line options or by setting resource values.<br />
<br />
{{Tip|If the popup menu windows show only as small boxes, it is probably because you have a line similar to this, {{ic|xterm*geometry: 80x32}}, in your resources file. This ''does ''start xterm in an 80 column by 32 row main window, but it also forces the menu windows to be 80 pixels by 32 pixels! Replace the incorrect line with this:<br />
{{bc|xterm*VT100.geometry: 80x32}}}}<br />
<br />
Some of the menu options are discussed below.<br />
<br />
====Main Options menu====<br />
'''''Ctrl + LeftMouse'''''<br />
<br />
*{{ic|Secure Keyboard}} attempts to ensure only the xterm window, and no other application, receives your keystrokes. The display changes to reverse video when it is invoked. If the display is not in reverse video, the ''Secure Keyboard ''mode is not in effect. Please read the "SECURITY" section of the xterm man page for this option's limitations.<br />
<br />
*{{ic|Allow SendEvents}} allows other processes to send keypress and mouse events to the xterm window. Because of the security risk, do not enable this unless you are very sure you know what you are doing.<br />
<br />
*{{ic|Log to File}} – The log file will be named {{ic|Xterm.log.hostname.yyyy.mm.dd.hh.mm.ss.XXXXXX}}. This file will contain all the printed output ''and all cursor movements. ''Logging may be a security risk.<br />
<br />
*The six {{ic|Send *** Signal}} menu items are not often useful, except when your keyboard fails. {{ic|HUP}}, {{ic|TERM}} and {{ic|KILL}} will close the xterm window. {{ic|KILL}} should be avoided, as it does not allow any cleanup code to run.<br />
<br />
*The {{ic|Quit}} menu item will also close the xterm window – it is the same as sending a {{ic|HUP}} signal. Most users will use the keyboard combination {{ic|Ctrl+d}} or will type {{ic|exit}} to close an xterm instance.<br />
====VT Options menu====<br />
'''''Ctrl + MiddleMouse'''''<br />
*{{ic|Select to Clipboard}} – Normally, selected text is stored in PRIMARY, to be pasted with {{ic|Shift+Insert}} or by using the middle mouse button. By toggling this option to ''on, ''selected text will use CLIPBOARD, allowing you to paste the text selected in an xterm window into a GUI application using {{ic|Ctrl+v}}. The corresponding XTerm resource is {{ic|selectToClipboard}}.<br />
<br />
*{{ic|Show Alternate Screen}} – When you use an a terminal application such as ''vim, ''or ''less, ''the alternate screen is opened. The main VT window, now hidden, remains in memory. You can view this main window, but not issue any commands in it, by toggling this menu option. You are able to select and copy text from this main window.<br />
<br />
{{Tip|Suspending the process running in the Alternate Screen and then resuming it provides more functionality than using {{ic|Show Alternate Screen}}. With a ''bash'' shell, pressing {{ic|Ctrl+z}} suspends the process; issuing the command {{ic|fg}} then resumes it.}}<br />
<br />
*{{ic|Show Tek Window}} and {{ic|Switch to Tek Mode}} – The [[Wikipedia:Tektronix 4010|Tektronix 4014]] was a graphics terminal from the 1970s used for CAD and plotting applications. The command line program {{ic|graph}}, from {{Pkg|plotutils}}, and the application {{Pkg|gnuplot}} can be made to use xterm's Tek emulation; most people will prefer more modern display options for charting data. See the [[#Tek 4014 demonstration]], below.<br />
<br />
====VT Fonts menu====<br />
'''''Ctrl + RightMouse'''''<br />
<br />
*When using XLFD fonts, the first seven menu items will change the font face and the font size used in the current xterm window. If you are using an Xft font, only the font size will change, the font face will not change with the different selections, .<br />
<br />
{{Tip|{{ic|Unreadable}} and {{ic|Tiny}} are useful if you wish to keep an eye on a process but do not want to devote a large amount of screen space to the terminal window. An example use might be a lengthy compilation process when you only want to see that the operation completes.}}<br />
<br />
*{{ic|Selection}}, when using XLFD font names, allows you to switch to the font name stored in the PRIMARY selection (or CLIPBOARD).<br />
<br />
====Tek Options menu==== <br />
From the '''Tek Window,''' '''''Ctrl + MiddleMouse'''''<br />
<br />
The first section's options allow you to change the Tek window font size. The second set of options are used to move the focus between the Tek emulation window and the main, or ''VT, ''window and to close or hide the Tek window.<br />
<br />
===Copy and paste===<br />
First, highlighting text using the mouse in an xterm (or alternatively another application) will select the text to copy, then clicking the mouse middle-button will paste that highlighted text. Also the key combination {{ic|Shift+Insert}} will paste highlighted text, but only within an xterm.<br />
<br />
====PRIMARY or CLIPBOARD====<br />
<br />
{{Expansion|Separate shortcuts for CLIPBOARD can be defined instead of using ''Select to clipboard'', similar to VTE-like terminals. See e.g [https://github.com/AladW/arch-i3/blob/master/.Xresources#L17]}}<br />
<br />
By default, xterm, and many other applications running under X, copy highlighted text into a buffer called the PRIMARY selection. The PRIMARY selection is short-lived; the text is immediately replaced by a new PRIMARY selection as soon as another piece of text is highlighted. Some applications will allow you to paste PRIMARY selections by using the middle-mouse, but not {{ic|Shift+Insert}}, and some other applications may not allow pasting from PRIMARY entirely.<br />
<br />
There is another buffer used for copied text called the CLIPBOARD selection. The text in the CLIPBOARD is long-lived, remaining available until a user actively overwrites it. Applications that use {{ic|Ctrl+c}} and {{ic|Ctrl+x}} for text copying and cutting operations, and {{ic|Ctrl+v}} for pasting, are using the CLIPBOARD.<br />
<br />
The fleeting nature of the PRIMARY selection, where copied text is lost as soon as another selection is highlighted, annoys some users. Xterm allows the user to switch between the use of PRIMARY and CLIPBOARD using {{ic|Select to Clipboard}} on the [[#VT Options menu]] or with the {{ic|selectToClipboard}} resource.<br />
<br />
====PRIMARY and CLIPBOARD====<br />
<br />
With the above setting you can select if you want to use PRIMARY or CLIPBOARD, but to use both you need a 'hack'. For example, put this in your .Xresources:<br />
<br />
XTerm*VT100.translations: #override <Btn1Up>: select-end(PRIMARY, CLIPBOARD, CUT_BUFFER0)<br />
<br />
====Selecting text====<br />
The new user usually discovers that text may be selected using a "click-and-drag" with the left mouse button. Double-clicking will select a word, where a word is defined as consecutive alphabetic characters plus the underscore, or the Basic Regular Expression (BRE) {{ic|[A-Za-z_]}}. Triple-clicking selects a line, with a "tab" character usually copied as multiple "space" characters.<br />
<br />
Another way of selecting text, especially useful when copying more than one full screen, is:<br />
#Left-click at the start of the intended selection.<br />
#Scroll to where the end of the selection is visible.<br />
#Right-click at the end of the selection.<br />
You do not have to be precise immediately with the right-click – any highlighted selection may be extended or shortened by using a right-click.<br />
<br />
You can clear any selected text by left-clicking once, anywhere within the xterm window.<br />
<br />
==Colors==<br />
Xterm defaults to black text, the ''foreground'' color, on a white ''background.'' The foreground and background colors can be reversed using the [[#VT Options menu|VT Options menu]] or with the {{ic|-rv}} command line option.<br />
$ xterm -rv<br />
<br />
Alternatively, the same thing can be accomplished with the following [[X_resources|X resources parameter]] (do not forget to [[X_resources#Parsing_.Xresources|reread the new resource afterwards]]{{Broken section link}}!):<br />
XTerm*reverseVideo: on<br />
<br />
Xterm's foreground color (the text color) and the background color may be set from the command line, using the options {{ic|-fg}} and {{ic|-bg}} respectively.<br />
xterm -fg PapayaWhip -bg "rgb:00/00/80"<br />
<br />
The first sixteen terminal colors, as well as the foreground and background colors, may be set from an [[X resources]] file:<br />
{{bc|XTerm*foreground: rgb:b2/b2/b2<br />
XTerm*background: rgb:08/08/08<br />
XTerm*color0: rgb:28/28/28<br />
<br />
! ...Lines omitted...<br />
<br />
XTerm*color15: rgb:e4/e4/e4}}<br />
{{Note|Colors for applications that use the X libraries may be specified in many different ways.<br />
<br />
Some colors can be specified by assigned names. If {{Pkg|emacs}} or {{Pkg|vim}} has been installed, you can examine {{ic|/usr/share/emacs/*/etc/rgb.txt}} or {{ic|/usr/share/vim/*/rgb.txt}} to view the list of color names with their decimal RGB values. Colors may also be specified using hexadecimal RGB values with the format {{ic|rgb:RR/GG/BB}}, or the older and not encouraged syntax {{ic|#RRGGBB}}.<br />
<br />
The color {{ic|PapayaWhip}} is the same as {{ic|rgb:ff/ef/d5}}, which is the same as {{ic|#ffefd5}}.<br />
<br />
See '''man(7) X, '''from {{Pkg|xorg-docs}}, for a more complete description of color syntax.}}<br />
Many suggestions for color schemes can be viewed in the forum thread, [https://bbs.archlinux.org/viewtopic.php?id=51818&p=1 Terminal Colour Scheme Screenshots].<br />
{{Tip|Many people specify colors in their X resources files without specifying an application class or application instance:<br />
{{bc|*foreground: rgb:b2/b2/b2<br />
*background: rgb:08/08/08}}<br />
The above example sets the foreground and background color values for all ''Xlib'' applications (xclock, xfontsel, and others) that use these resources. This is a nice, easy way to achieve a unified color scheme.}}<br />
<br />
==Fonts==<br />
===Default fonts===<br />
Xterm's default font is the bitmap font named by the [[X Logical Font Description]] alias {{ic|fixed}}, often resolving to<br />
-misc-fixed-medium-r-semicondensed--13-120-75-75-c-60-iso8859-?<br />
This font, also aliased to the name {{ic|6x13}}, has remakably wide coverage for unicode glyphs. The default "TrueType" font is the 14‑point font matched by the name {{ic|mono}}. The ''FreeType ''font that will be used can be found with this command:<br />
$ fc-match mono<br />
<br />
Fonts can be specified from the command line, with the options {{ic|-fn}} for bitmap font names and {{ic|-fa}} for Xft names. The example below allows you to alternate between the two fonts by toggling {{ic|TrueType Fonts}} from the [[#VT Fonts menu]].<br />
{{bc|<nowiki>$ xterm -fn 7x13 -fa "Liberation Mono:size=10:antialias=false"</nowiki>}}<br />
For a more permanent change, the default fonts may be set in an [[X resources]] file:<br />
{{bc|<nowiki>xterm*faceName: Liberation Mono:size=10:antialias=false</nowiki><br />
xterm*font: 7x13}}<br />
<br />
{{Note|There is a long-standing bug in xterm that prevents the command line option {{ic|-fn}} working correctly when {{ic|faceName}} has been set in a resource file. One solution is to set the resource {{ic|renderFont}} to {{ic|false}} on the command line.<br />
{{bc|$ xterm -fn 8x13 # If this command does not set the font,<br />
$ xterm -fn 8x13 -xrm "*renderFont:false" # set the 'renderFont' resource to 'false'.}}<br />
Perhaps easier, you can just toggle {{ic|TrueType Fonts}} from the [[#VT Fonts menu]] in the terminal window.}}<br />
<br />
===Bold and underlined fonts===<br />
Italic fonts are shown as underlined characters when using XLFD names in xterm. TrueType fonts should use an oblique typeface.<br />
<br />
If you do not specify a bold font at the command line, {{ic|-fb}}, or through the {{ic|boldFont}} resource, xterm will attempt to find a bold font matching the normal font. If a matching font is not found, the bold font will be created by "overstriking" the normal font.<br />
<br />
===CJK Fonts===<br />
Many fonts do not contain glyphs for the double width Chinese, Japanese and Korean languages. Other terminal emulators such as [[urxvt]] may be better suited if you frequently work with these languages.<br />
<br />
Using bitmapped XLFD fonts with CJK has many pitfalls in xterm. It is much easier to use TrueType fonts for CJK display, using the {{ic|faceNameDoublesize}} resource. This example uses ''DejaVu Sans Mono'' as the normal font and ''WenQuanYi Bitmap Song'' as the double width font:<br />
{{bc|<nowiki>xterm*faceName: DejaVu Sans Mono:style=Book:antialias=false</nowiki><br />
xterm*faceNameDoublesize: WenQuanYi Bitmap Song<br />
xterm*faceSize: 8}}<br />
<br />
==Tips and tricks==<br />
===Automatic transparency===<br />
Install the package {{pkg|transset-df}} and a [[Wikipedia:Compositing window manager|composite manager]] such as [[Xcompmgr]]. Then add the following line to your {{ic|~/.bashrc}}:<br />
[ -n "$XTERM_VERSION" ] && transset-df --id "$WINDOWID" >/dev/null<br />
<br />
Now, each time you launch a shell in an xterm and a composite manager is running, the xterm window will be transparent.<br />
The test in front of {{ic|transset-df}} keeps transet from executing if {{ic|XTERM_VERSION}} is not defined. Note that your terminal will not be transparent if you launch a program other than a shell this way. It is probably possible to work around this if you want the functionality.<br />
<br />
Also see [[Per-application transparency]].<br />
<br />
===Enable bell urgency===<br />
Add the following line to your {{ic|~/.Xresources}} file:<br />
<br />
xterm*bellIsUrgent: true<br />
<br />
===Font tips===<br />
<br />
====Use color in place of bold and italics====<br />
When using small font sizes, bold or italic characters may be difficult to read. One solution is to turn off bolding and underlining or italics and use color instead. This example does just that:<br />
{{bc|! Forbid bold font faces; bold type is light blue.<br />
XTerm*colorBDMode: true<br />
XTerm*colorBD: rgb:82/a4/d3<br />
! Do not underscore text, underlined text is white.<br />
XTerm*colorULMode: true<br />
XTerm*colorUL: rgb:e4/e4/e4}}<br />
<br />
====Adjust line spacing====<br />
Lines of text can sometimes be too close together, or they may appear to be too widely spaced. For one example, using ''DejaVu Sans Mono, ''the low underscore glyph may butt against CJK glyphs or the cursor block in the line below. Line spacing, called ''leading ''by typographers, can be adjusted using the {{ic|scaleHeight}} resource. Here, the line spacing is widened:<br />
XTerm*scaleHeight: 1.01<br />
Valid values for {{ic|scaleHeight}} range from {{ic|0.9}} to {{ic|1.5}}, with {{ic|1.0}} being the default.<br />
===Remove black border===<br />
Xterm has a black border in some cases, you can disable this by adding the following line to your {{ic|~/.Xresources}} file.<br />
<br />
xterm*borderWidth: 0<br />
<br />
===Tek 4014 demonstration===<br />
If you have {{Pkg|plotutils}} installed, you can use xterm's Tektronix 4014 emulation to view some of the plotutils package's test files. Open the Tek window from the [[#VT Options menu]] menu item {{ic|Switch to Tek Mode}} or start a new xterm instance using this command:<br />
$ xterm -t -tn tek4014<br />
Your PS1 prompt will not render correctly, if it appears at all. In the new window, enter the command,<br />
cat /usr/share/tek2plot/dmerc.tek<br />
A world map will appear in the Tek window. You can also view other {{ic|*.tek}} files from that same directory. To close the Tek window, one can use the xterm menus.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Flickering on scroll ===<br />
<br />
{{Warning|Double buffering may cause non-bitmap fonts to render incorrectly.}}<br />
<br />
Rebuild xterm using [[ABS]] and include the {{ic|--enable-double-buffer}} flag:<br />
<br />
./configure --prefix=/usr \<br />
...<br />
--with-utempter \<br />
--enable-double-buffer<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?id=146023 Xterm modifications] for details.<br />
<br />
== See also ==<br />
<br />
* [http://lukas.zapletalovi.com/2013/07/hidden-gems-of-xterm.html Hidden gems of Xterm]<br />
* [http://www.in-ulm.de/~mascheck/X11/XTerm Commented XTerm resources]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=St&diff=454637St2016-10-21T01:55:55Z<p>Alive4ever: /* Desktop entry */ change example font size to 12 because st uses different font scaling since version 0.7</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Terminal emulators]]<br />
[[ja:St]]<br />
[http://st.suckless.org/ st] is a simple terminal implementation for [[X]] by [http://suckless.org suckless]. It is intended to serve as a lightweight replacement for [[xterm]] or [[urxvt]]. It currently supports 256 colors, true colors, most VT10X escape sequences, UTF-8, X11 copy/paste, anti-aliased fonts (using fontconfig), fallback fonts, resizing, shortcuts via config.h, and line drawing.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|st}} or {{AUR|st-git}} package.<br />
<br />
== Configuration ==<br />
''st'' is configured through its {{ic|config.h}} file, which is copied over from {{ic|config.h}} at compile time. A default {{ic|config.def.h}} is included with the source. <br />
<br />
Consider maintaining your own [[PKGBUILD]] with your {{ic|config.h}}.<br />
<br />
=== Shell ===<br />
<br />
To change the default shell for ''st'', edit this line:<br />
<br />
static char shell[] = "/bin/sh";<br />
<br />
=== Term ===<br />
<br />
To change the terminal type, edit this line:<br />
<br />
static char termname[] = "st-256color";<br />
<br />
''st'' will set the {{ic|TERM}} variable with the value of {{ic|termname}}.<br />
<br />
{{note|If you experience trouble with ''st'', you can try to set {{ic|termname}} to {{ic|xterm}} or {{ic|xterm-256color}} }}<br />
<br />
=== Font ===<br />
<br />
Edit the following line as you prefer:<br />
<br />
static char font[] = "Liberation Mono:pixelsize=12:antialias=false:autohint=false";<br />
<br />
You can also pass the value of the font in the command line:<br />
<br />
$ st -f "Liberation Mono:size=12"<br />
<br />
=== Colors ===<br />
<br />
Edit the following line to set ''foreground'', ''background'' and ''cursor'' colors:<br />
<br />
static unsigned int defaultfg = 7;<br />
static unsigned int defaultbg = 0;<br />
static unsigned int defaultcs = 256;<br />
<br />
The values refer to the {{ic|*colorname[]}} array in the same file, you can use default color or add yours in {{ic|#rrggbb}}, for example:<br />
<br />
static const char *colorname[] = {<br />
/* 8 normal colors */<br />
"black",<br />
"red3",<br />
"green3",<br />
"yellow3",<br />
"blue2",<br />
"magenta3",<br />
"cyan3",<br />
"gray90",<br />
<br />
/* 8 bright colors */<br />
"gray50",<br />
"red",<br />
"green",<br />
"yellow",<br />
"#5c5cff",<br />
"magenta",<br />
"cyan",<br />
"white",<br />
<br />
[255] = 0,<br />
<br />
/* more colors can be added after 255 to use with DefaultXX */<br />
"#cccccc",<br />
"#eeeeee",<br />
"#111111",<br />
};<br />
<br />
/*<br />
* Default colors (colorname index)<br />
* foreground, background, cursor<br />
*/<br />
static unsigned int defaultfg = 257;<br />
static unsigned int defaultbg = 258;<br />
static unsigned int defaultcs = 256;<br />
<br />
=== Desktop entry ===<br />
To simplify launching ''st'' with a decent font e.g. {{Pkg|adobe-source-code-pro-fonts}}, you can also create a [[desktop entry]]:<br />
<br />
{{hc|~/.local/share/applications/simple-terminal.desktop|2=<br />
[Desktop Entry]<br />
Name=Simple Terminal<br />
GenericName=Terminal<br />
Comment=standard terminal emulator for the X window system<br />
Exec=st -t "Suckless Terminal" -f "Source Code Pro:style=Semibold:size=12" -g "80x24"<br />
Terminal=false<br />
Type=Application<br />
Encoding=UTF-8<br />
Icon=terminal<br />
Categories=System;TerminalEmulator;<br />
Keywords=shell;prompt;command;commandline;cmd;<br />
}}<br />
<br />
The menu entry will appear as '''Simple Terminal''' in the ''System Tools'' application list.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Keyboard ===<br />
==== DEL-Key not working properly in some Application ====<br />
add following to ''~/.inputrc'' or ''/etc/inputrc'':<br />
set enable-keypad on<br />
<br />
==== Backspace not working properly ====<br />
<br />
{{Note | According to the [http://git.suckless.org/st/tree/FAQ FAQ], this behavior has been changed in the upstream, and the issue can be fixed upgrading to the latest version. }}<br />
<br />
While virtual terminal and most popular terminal emulator for X bind {{ic|backscape}} key to {{ic|^?}} escape sequence, older version of {{ic|st}} bind it to {{ic|^H}}, as explained in older version of the FAQ.<br />
<br />
If hitting the {{ic|backspace}} key while typing on standard input of some programs (like {{ic|read}}) prints {{ic|^H}} instead of erasing, you can fix that with:<br />
<br />
stty erase '^H'<br />
<br />
This will make the terminal interprets {{ic|^H}} as an erase command. <br />
<br />
If you want to put the above command in a shell profile, you should consider checking the {{ic|$TERM}} before launch it.<br />
<br />
{{Note| Since version 0.7, {{Ic|backspace}} key behavior has been consistent. {{Ic|Backspace}} now sends {{Ic|^?}} even with {{Ic|Alt}} pressed, so that the workaround below is no longer needed.}}<br />
<br />
As of version {{ic|0-6}}, {{ic|st}} interpret backspace as {{ic|^?}} by default. An exception is when {{ic|Alt+BackSpace}} pressed, {{ic|st}} sends {{ic|^[^H}} instead of {{ic|^[^?}} ({{Bug|50000}}). This inconsistent behavior leads to bad experience, especially on Emacs when pressing {{ic|Alt+BackSpace}} no longer delete a word backwards. To fix this, adding a line on {{ic|config.h}} is needed.<br />
<pre><nowiki><br />
{ XK_BackSpace, Mod1Mask, "\033\177", 0, 0, 0},<br />
</nowiki></pre><br />
Rebuild the package to apply the change.<br />
<br />
=== Vim ===<br />
==== The background colour of text in ''vim'' will not fill in anything that is not a character ====<br />
Try setting the value of {{ic|termname}} in your {{ic|config.h}} to {{ic|st-256color}} and recompiling. And do not set the {{ic|TERM}} var in your shell, at least not to {{ic|st-256color}} as this seems to cause the issue.<br />
<br />
Another solution, perhaps a better one, is to have the following lines in your {{ic|.vimrc}} file:<br />
<br />
if &term =~ '256color'<br />
" disable Background Color Erase (BCE) so that color schemes<br />
" render properly when inside 256-color tmux and GNU screen.<br />
" see also http://sunaku.github.io/vim-256color-bce.html<br />
set t_ut=<br />
endif<br />
<br />
== See also ==<br />
*[http://st.suckless.org/ Homepage]<br />
*[http://git.suckless.org/st/plain/FAQ Frequently asked questions]<br />
*[http://git.suckless.org/st/ Official git repository]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=St&diff=454635St2016-10-21T01:52:49Z<p>Alive4ever: /* Backspace not working properly */ Add a note that backspace behavior is consistent as of st 0.7</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Terminal emulators]]<br />
[[ja:St]]<br />
[http://st.suckless.org/ st] is a simple terminal implementation for [[X]] by [http://suckless.org suckless]. It is intended to serve as a lightweight replacement for [[xterm]] or [[urxvt]]. It currently supports 256 colors, true colors, most VT10X escape sequences, UTF-8, X11 copy/paste, anti-aliased fonts (using fontconfig), fallback fonts, resizing, shortcuts via config.h, and line drawing.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|st}} or {{AUR|st-git}} package.<br />
<br />
== Configuration ==<br />
''st'' is configured through its {{ic|config.h}} file, which is copied over from {{ic|config.h}} at compile time. A default {{ic|config.def.h}} is included with the source. <br />
<br />
Consider maintaining your own [[PKGBUILD]] with your {{ic|config.h}}.<br />
<br />
=== Shell ===<br />
<br />
To change the default shell for ''st'', edit this line:<br />
<br />
static char shell[] = "/bin/sh";<br />
<br />
=== Term ===<br />
<br />
To change the terminal type, edit this line:<br />
<br />
static char termname[] = "st-256color";<br />
<br />
''st'' will set the {{ic|TERM}} variable with the value of {{ic|termname}}.<br />
<br />
{{note|If you experience trouble with ''st'', you can try to set {{ic|termname}} to {{ic|xterm}} or {{ic|xterm-256color}} }}<br />
<br />
=== Font ===<br />
<br />
Edit the following line as you prefer:<br />
<br />
static char font[] = "Liberation Mono:pixelsize=12:antialias=false:autohint=false";<br />
<br />
You can also pass the value of the font in the command line:<br />
<br />
$ st -f "Liberation Mono:size=12"<br />
<br />
=== Colors ===<br />
<br />
Edit the following line to set ''foreground'', ''background'' and ''cursor'' colors:<br />
<br />
static unsigned int defaultfg = 7;<br />
static unsigned int defaultbg = 0;<br />
static unsigned int defaultcs = 256;<br />
<br />
The values refer to the {{ic|*colorname[]}} array in the same file, you can use default color or add yours in {{ic|#rrggbb}}, for example:<br />
<br />
static const char *colorname[] = {<br />
/* 8 normal colors */<br />
"black",<br />
"red3",<br />
"green3",<br />
"yellow3",<br />
"blue2",<br />
"magenta3",<br />
"cyan3",<br />
"gray90",<br />
<br />
/* 8 bright colors */<br />
"gray50",<br />
"red",<br />
"green",<br />
"yellow",<br />
"#5c5cff",<br />
"magenta",<br />
"cyan",<br />
"white",<br />
<br />
[255] = 0,<br />
<br />
/* more colors can be added after 255 to use with DefaultXX */<br />
"#cccccc",<br />
"#eeeeee",<br />
"#111111",<br />
};<br />
<br />
/*<br />
* Default colors (colorname index)<br />
* foreground, background, cursor<br />
*/<br />
static unsigned int defaultfg = 257;<br />
static unsigned int defaultbg = 258;<br />
static unsigned int defaultcs = 256;<br />
<br />
=== Desktop entry ===<br />
To simplify launching ''st'' with a decent font e.g. {{Pkg|adobe-source-code-pro-fonts}}, you can also create a [[desktop entry]]:<br />
<br />
{{hc|~/.local/share/applications/simple-terminal.desktop|2=<br />
[Desktop Entry]<br />
Name=Simple Terminal<br />
GenericName=Terminal<br />
Comment=standard terminal emulator for the X window system<br />
Exec=st -t "Suckless Terminal" -f "Source Code Pro:style=Semibold:size=16" -g "80x24"<br />
Terminal=false<br />
Type=Application<br />
Encoding=UTF-8<br />
Icon=terminal<br />
Categories=System;TerminalEmulator;<br />
Keywords=shell;prompt;command;commandline;cmd;<br />
}}<br />
<br />
The menu entry will appear as '''Simple Terminal''' in the ''System Tools'' application list.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Keyboard ===<br />
==== DEL-Key not working properly in some Application ====<br />
add following to ''~/.inputrc'' or ''/etc/inputrc'':<br />
set enable-keypad on<br />
<br />
==== Backspace not working properly ====<br />
<br />
{{Note | According to the [http://git.suckless.org/st/tree/FAQ FAQ], this behavior has been changed in the upstream, and the issue can be fixed upgrading to the latest version. }}<br />
<br />
While virtual terminal and most popular terminal emulator for X bind {{ic|backscape}} key to {{ic|^?}} escape sequence, older version of {{ic|st}} bind it to {{ic|^H}}, as explained in older version of the FAQ.<br />
<br />
If hitting the {{ic|backspace}} key while typing on standard input of some programs (like {{ic|read}}) prints {{ic|^H}} instead of erasing, you can fix that with:<br />
<br />
stty erase '^H'<br />
<br />
This will make the terminal interprets {{ic|^H}} as an erase command. <br />
<br />
If you want to put the above command in a shell profile, you should consider checking the {{ic|$TERM}} before launch it.<br />
<br />
{{Note| Since version 0.7, {{Ic|backspace}} key behavior has been consistent. {{Ic|Backspace}} now sends {{Ic|^?}} even with {{Ic|Alt}} pressed, so that the workaround below is no longer needed.}}<br />
<br />
As of version {{ic|0-6}}, {{ic|st}} interpret backspace as {{ic|^?}} by default. An exception is when {{ic|Alt+BackSpace}} pressed, {{ic|st}} sends {{ic|^[^H}} instead of {{ic|^[^?}} ({{Bug|50000}}). This inconsistent behavior leads to bad experience, especially on Emacs when pressing {{ic|Alt+BackSpace}} no longer delete a word backwards. To fix this, adding a line on {{ic|config.h}} is needed.<br />
<pre><nowiki><br />
{ XK_BackSpace, Mod1Mask, "\033\177", 0, 0, 0},<br />
</nowiki></pre><br />
Rebuild the package to apply the change.<br />
<br />
=== Vim ===<br />
==== The background colour of text in ''vim'' will not fill in anything that is not a character ====<br />
Try setting the value of {{ic|termname}} in your {{ic|config.h}} to {{ic|st-256color}} and recompiling. And do not set the {{ic|TERM}} var in your shell, at least not to {{ic|st-256color}} as this seems to cause the issue.<br />
<br />
Another solution, perhaps a better one, is to have the following lines in your {{ic|.vimrc}} file:<br />
<br />
if &term =~ '256color'<br />
" disable Background Color Erase (BCE) so that color schemes<br />
" render properly when inside 256-color tmux and GNU screen.<br />
" see also http://sunaku.github.io/vim-256color-bce.html<br />
set t_ut=<br />
endif<br />
<br />
== See also ==<br />
*[http://st.suckless.org/ Homepage]<br />
*[http://git.suckless.org/st/plain/FAQ Frequently asked questions]<br />
*[http://git.suckless.org/st/ Official git repository]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=KDE&diff=454593KDE2016-10-20T12:57:10Z<p>Alive4ever: /* Enabling touchpad tap to click on plasma wayland session */ Minor command typo</p>
<hr />
<div>[[Category:KDE]]<br />
[[ar:KDE]]<br />
[[cs:KDE]]<br />
[[de:KDE]]<br />
[[es:KDE]]<br />
[[fr:KDE]]<br />
[[it:KDE]]<br />
[[ja:KDE]]<br />
[[pl:KDE]]<br />
[[ru:KDE]]<br />
[[tr:KDE Masaüstü Ortamı]]<br />
[[zh-CN:KDE]]<br />
[[zh-TW:KDE]]<br />
{{Related articles start}}<br />
{{Related|Desktop environment}}<br />
{{Related|Display manager}}<br />
{{Related|Dolphin}}<br />
{{Related|Window manager}}<br />
{{Related|Qt}}<br />
{{Related|KDM}}<br />
{{Related|KDevelop}}<br />
{{Related|Trinity}}<br />
{{Related|Uniform Look for Qt and GTK Applications}}<br />
{{Related articles end}}<br />
<br />
KDE is a software project currently comprising of a [[desktop environment]] known as Plasma (or Plasma Workspaces), a collection of libraries and frameworks (KDE Frameworks) and several applications (KDE Applications) as well. KDE upstream has a well maintained [http://userbase.kde.org/ UserBase wiki]. Detailed information about most KDE applications can be found there.<br />
<br />
== Installation ==<br />
<br />
=== Plasma Desktop ===<br />
<br />
{{Note|<br />
*Plasma 5 is not co-installable with Plasma 4.<br />
*The Plasma 4 desktop is unmaintained since August 2015.[https://www.kde.org/announcements/announce-applications-15.08.0.php] It is no longer in the official repositories since December 2015.[https://www.archlinux.org/news/dropping-plasma-4/]<br />
* [[KDM]] is no longer available for Plasma 5. KDE upstream [http://blog.davidedmundson.co.uk/blog/display_managers_finale recommends] using the [[SDDM]] display manager as it provides integration with the Plasma 5 theme.}}<br />
<br />
Before installing Plasma, make sure you have a working [[Xorg]] installation on your system.<br />
<br />
Install the {{Pkg|plasma-meta}} meta-package or the {{Grp|plasma}} group. For differences between {{Pkg|plasma-meta}} and {{Grp|plasma}} reference [[Creating packages#Meta packages and groups]]. Alternatively, for a more minimal Plasma installation, install the {{Pkg|plasma-desktop}} package.<br />
<br />
=== Upgrading from Plasma 4 to 5 ===<br />
<br />
# Isolate {{ic|multi-user.target}}:{{bc|# systemctl isolate multi-user.target}}<br />
# If you use KDM as display manager, [[disable]] the {{ic|kdm.service}} systemd unit. <br />
# [[Install|Uninstall]] the {{AUR|kdebase-workspace}} package.<br />
# [[Install]] the {{pkg|plasma-meta}} package or the {{grp|plasma}} group.<br />
# [[Enable]] the {{ic|sddm.service}} systemd unit, or install and enable any other [[display manager]].<br />
# Reboot or simply [[start]] the systemd {{ic|sddm.service}} unit.<br />
<br />
{{Note|The Plasma 4 configuration is not automatically migrated to Plasma 5, so you will have to configure your desktop from scratch.}}<br />
<br />
=== KDE applications and language packs ===<br />
<br />
To install the full set of KDE Applications, install the {{Grp|kde-applications}} group or the {{Pkg|kde-applications-meta}} meta-package. Note that this will only install applications, it will not install any version of the Plasma Desktop.<br />
<br />
If you need language files, install {{ic|kde-l10n-'''yourlanguagehere'''}} (e.g. {{Pkg|kde-l10n-de}} for the German language). For a full list of available languages see [https://www.archlinux.org/packages/extra/any/kde-l10n/ this link].<br />
<br />
== Starting Plasma ==<br />
<br />
{{Tip|To better integrate SDDM with Plasma, it is recommended to edit {{ic|/etc/sddm.conf}} to use the breeze theme. Refer to [[SDDM#Theme settings]] for instructions.}}<br />
<br />
To launch a Plasma 5 session, choose ''Plasma'' in your [[display manager]] menu.<br />
<br />
Alternatively, to start Plasma with ''startx'', append {{ic|exec startkde}} to your {{ic|.xinitrc}} file. If you want to start Xorg at login, please see [[Start X at login]].<br />
<br />
=== Wayland ===<br />
<br />
As of Plasma 5.8, Plasma on [[Wayland]] should be usable, although there are a [https://community.kde.org/Plasma/5.8_Errata#Wayland few known problems].<br />
<br />
* To start a Plasma on Wayland session from a display manager, install the {{Pkg|plasma-wayland-session}} package and ''Plasma'' should show up in the display manager.<br />
* To start a Plasma on Wayland session from a console, run {{ic|startplasmacompositor}}.<br />
<br />
== Configuration ==<br />
<br />
Most settings for KDE applications are stored in {{ic|~/.config}}, but some older applications may use {{ic|~/.kde4}}. However, configuring KDE is primarily done through the '''System Settings''' application. It can be started from a terminal by executing ''systemsettings5''.<br />
<br />
Frameworks 5 applications can use KDE 4 configuration however they expect the configuration files to be located in different places. To allow Frameworks 5 applications running in KDE 4 to share the same configurations they may be moved to the new locations and symlinked back to the old. Examples are:<br />
*Konsole profiles from {{ic|~/.kde4/share/apps/konsole}} to {{ic|~/.local/share/konsole/}}<br />
*Application appearance from {{ic|~/.kde4/share/config/kdeglobals}} to {{ic|~/.config/kdeglobals}} <br />
<br />
=== Personalization ===<br />
<br />
==== Plasma desktop ====<br />
<br />
===== Themes =====<br />
<br />
{{Note|1=If the Plasma cursor theme is incorrect in some instances, see the following [https://bbs.archlinux.org/viewtopic.php?pid=1533071#p1533071 forum post] for a workaround.}}<br />
[http://kde-look.org/index.php?xcontentmode=76 Plasma themes] define the look of panels and plasmoids. For easy system-wide installation, some such themes are available in both the official repositories and the [https://aur.archlinux.org/packages.php?O=0&K=plasmatheme&do_Search=Go AUR].<br />
<br />
The easiest way to install themes is by going through the Desktop Settings control panel:<br />
<br />
Workspace Theme > Desktop Theme > Get new Themes<br />
<br />
This will present a nice frontend for [http://www.kde-look.org/ kde-look.org] that allows you to install, uninstall, or update third-party plasmoid scripts with literally just one click.<br />
<br />
Splash and Lock screens are currently unavailable so to customize these screens you have to modify the original theme found in {{ic|/usr/share/plasma/look-and-feel/}}.<br />
See [https://www.kubuntuforums.net/showthread.php?67599-Plasma-5-background-images&s=59832dc20e5bfc2948dbb591d8453f61 this thread] on the Kubuntu forums.<br />
<br />
Note that the [[SDDM]] login screen is not part of this theme.<br />
<br />
====== Qt and GTK+ Applications Appearance ======<br />
<br />
{{Tip|For Qt and GTK theme consistency, see [[Uniform look for Qt and GTK applications]].}}<br />
<br />
;Qt4<br />
For Qt4 applications to have a consistent appearance, there are two options: <br />
Install {{Pkg|breeze-kde4}} and then pick Breeze as GUI Style in {{ic|qtconfig-qt4}}; or install {{Pkg|breeze-gtk}} and pick GTK+ as GUI Style.<br />
<br />
;GTK+<br />
The recommended theme for a pleasant appearance in GTK+ applications is {{Pkg|breeze-gtk}} or {{AUR|gnome-breeze-git}}, a GTK+ theme designed to mimic the appearance of Plasma 5 Breeze.<br />
Install {{Pkg|kde-gtk-config}} and select the installed GTK-theme for GTK2/GTK3-Theme in ''System Settings > Application Style > GNOME Application Style''.<br />
<br />
In some themes, tooltips in GTK+ applications have white text on white backgrounds making it difficult to read. To change the colors in GTK2 applications, find the section for tooltips in the gtkrc file and change it. For GTK3 application two files need to be changed, gtk.css and settings.ini.<br />
<br />
===== Widgets =====<br />
<br />
Plasmoids are little scripted (plasmoid scripts) or coded (plasmoid binaries) KDE applications designed to enhance the functionality of your desktop.<br />
<br />
The easiest way to install plasmoid scripts is by right-clicking onto a panel or the desktop and choosing ''Add Widgets > Get new Widgets > Download Widgets''.<br />
This will present a nice frontend for [http://www.kde-look.org/ kde-look.org] that allows you to install, uninstall, or update third-party plasmoid scripts with literally just one click.<br />
<br />
Many Plasmoid binaries are [https://aur.archlinux.org/packages.php?O=0&K=plasmoid&do_Search=Go&PP=25&SO=d&SB=v available from the AUR].<br />
<br />
===== Sound applet in the system tray =====<br />
<br />
[[Install]] {{Pkg|plasma-pa}} or {{Pkg|kmix}} (start Kmix from the Application Launcher).<br />
<br />
{{Note|1=To adjust the [https://bugs.kde.org/show_bug.cgi?id=313579#c28 step size of volume increments/decrements], add e.g. {{ic|1=VolumePercentageStep=1}} in the {{ic|[Global]}} section of {{ic|~/.kde4/share/config/kmixrc}}}}<br />
<br />
===== Disable panel shadow =====<br />
<br />
As the plasma panel is on top of other windows, its shadow is drawn over them. [https://bbs.archlinux.org/viewtopic.php?pid=1228394#p1228394] To disable this behaviour without impacting other shadows, [[install]] {{Pkg|xorg-xprop}} and run:<br />
<br />
$ xprop -remove _KDE_NET_WM_SHADOW<br />
<br />
then select the panel with the plus-sized cursor. [https://forum.kde.org/viewtopic.php?f=285&t=121592] For automation, install {{Pkg|xorg-xwininfo}} and create the following script:<br />
<br />
{{hc|/usr/local/bin/kde-no-shadow|<nowiki><br />
#!/bin/bash<br />
for WID in $(xwininfo -root -tree | sed '/"Plasma": ("plasmashell" "plasmashell")/!d; s/^ *\([^ ]*\) .*/\1/g'); do<br />
xprop -id $WID -remove _KDE_NET_WM_SHADOW<br />
done<br />
</nowiki>}}<br />
<br />
The script can be run on login with ''Add Script'' in ''Autostart'':<br />
<br />
$ kcmshell5 autostart<br />
<br />
==== Window decorations ====<br />
<br />
[http://kde-look.org/index.php?xcontentmode=75 Window decorations] can be changed in ''System Settings > Workspace Appearance > Window Decorations''.<br />
<br />
There you can also directly download and install more themes with one click, and some are available in the [https://aur.archlinux.org/packages.php?O=0&K=kdestyle&do_Search=Go&PP=25&SO=d&SB=v AUR].<br />
<br />
==== Icon themes ====<br />
<br />
Icon themes can be installed and changed on ''System Settings > Icons''.<br />
{{note|Although all modern Linux desktops share the same icon theme format, desktops like [[GNOME]] use fewer icons (esp. in menus and toolbars). Themes developed for such desktops usually lack icons required by Plasma 5 and KDE apps.<br/><br />
It is recommended to install Plasma compatible icon themes instead.}}<br />
<br />
==== Fonts ====<br />
<br />
===== Fonts in a Plasma session look poor =====<br />
<br />
Try installing the {{Pkg|ttf-dejavu}} and {{Pkg|ttf-liberation}} packages.<br />
<br />
After the installation, be sure to log out and back in. You should not have to modify anything in ''System Settings > Fonts''.<br />
<br />
If you have personally set up how your [[Fonts]] render, be aware that System Settings may alter their appearance. When you go ''System Settings > Appearance > Fonts'' System Settings will likely alter your font configuration file ({{ic|fonts.conf}}).<br />
<br />
There is no way to prevent this, but, if you set the values to match your {{ic|fonts.conf}} file, the expected font rendering will return (it will require you to restart your application or in a few cases restart your desktop). Note that Gnome's Font Preferences also does this.<br />
<br />
===== Fonts are huge or seem disproportional =====<br />
<br />
Try to force font DPI to '''96''' in ''System Settings > Application Appearance > Fonts''.<br />
<br />
If that does not work, try setting the DPI directly in your Xorg configuration as documented [[Xorg#Setting_DPI_manually|here]].<br />
<br />
==== Space efficiency ====<br />
<br />
The Plasma Netbook shell has been dropped from Plasma 5, see the following [https://forum.kde.org/viewtopic.php?f=289&t=126631&p=335947&hilit=plasma+netbook#p335899 KDE forum post]<br />
However, you can achieve something similar by editing the file {{ic|~/.config/kwinrc}} adding <br />
{{ic|1=BorderlessMaximizedWindows=true}} in the {{ic|[Windows]}} section.<br />
<br />
=== Printing ===<br />
<br />
{{Tip|Use the [[CUPS]] web interface for faster configuration. Printers configured in this way can be used in KDE applications. }}<br />
<br />
You can also configure printers in ''System Settings > Printer Configuration''. To use this method, you must first install {{Pkg|print-manager}} and {{Pkg|cups}}.<br />
<br />
The {{ic|avahi-daemon.service}} and {{ic|org.cups.cupsd.service}} daemons must be started first; otherwise, you will get the following error:<br />
The service 'Printer Configuration' does not provide an interface 'KCModule'<br />
with keyword 'system-config- printer-kde/system-config-printer-kde.py'<br />
The factory does not support creating components of the specified type.<br />
<br />
If you are getting the following error, you need to give your user the right to manage printers.<br />
There was an error during CUPS operation: 'cups-authorization-canceled'<br />
<br />
For CUPS, this is set in {{ic|/etc/cups/cups-files.conf}}.<br />
<br />
Adding {{ic|lpadmin}} to {{ic|/etc/group}} and then to the {{ic|SystemGroup}} directive in {{ic|/etc/cups/cups-files.conf}} allows anyone in the {{ic|lpadmin}} group to configure printers. Do ''not'' add the {{ic|lp}} group to the {{ic|SystemGroup}} directive, or printing will fail.<br />
<br />
# groupadd -g107 lpadmin<br />
<br />
{{hc|/etc/cups/cups-files.conf|# Administrator user group...<br />
SystemGroup sys root lpadmin}}<br />
<br />
{{Tip|Read [[CUPS#Configuration]] to get more details on how to configure CUPS.}}<br />
<br />
=== Samba/Windows support ===<br />
<br />
If you want to have access to Windows services, install [[Samba]] (package {{Pkg|samba}}).<br />
<br />
The Dolphin share functionality requires the package {{Pkg|kdenetwork-filesharing}} and usershares, which the stock smb.conf does not have enabled. Instructions to add them are in [[Samba#Creating usershare path]], after which sharing in Dolphin should work out of the box after restarting Samba.<br />
<br />
=== KDE Desktop activities ===<br />
<br />
KDE Desktop Activities are Plasma-based virtual-desktop-like sets of Plasma Widgets where you can independently configure widgets as if you have more than one screen or desktop.<br />
<br />
On your desktop, click the Cashew Plasmoid and, on the pop-up window, press "Activities".<br />
<br />
A plasma bar presenting you the current existing Plasma Desktop Activities will appear at the bottom of the screen. You can navigate between them by pressing the correspondent icons.<br />
<br />
=== Power saving ===<br />
<br />
Plasma has an integrated power saving service called "'''Powerdevil Power Management'''" that may adjust the power saving profile of the system and/or the brightness of the screen (if supported).<br />
<br />
{{Accuracy|Regarding the note below, it might be that the problem is the logind setting ''LidSwitchIgnoreInhibited'' which defaults to ''yes''. [https://bbs.archlinux.org/viewtopic.php?pid&#61;1649022#p1649022]}}<br />
<br />
{{Note|Powerdevil may not [[Power management#Power managers|inhibit]] all logind settings (such as the lid close action for laptops). In these cases, the logind setting itself will need to be changed - see [[Power management#Power management with systemd]].}}<br />
<br />
=== Monitoring changes on local files and directories ===<br />
<br />
KDE now uses '''inotify''' directly from the kernel with '''kdirwatch''' (included in kdelibs), so Gamin or FAM are no longer needed. You may want to install this {{AUR|kdirwatch}}{{Broken package link|{{aur-mirror|kdirwatch}}}} from AUR which is a GUI frontend for kdirwatch.<br />
<br />
=== Autostarting applications ===<br />
<br />
Plasma can autostart applications and run scripts on startup and shutdown. To autostart an application, start {{ic|systemsettings}} and navigate to ''Startup and Shutdown'' -> ''Autostart'' and add the program or shell script of your choice. For applications, a {{ic|.desktop}} file will be created, for shell scripts, a symlink will be created.<br />
{{Note|<br />
* Programs can be autostarted on login only, whilst shell scripts can also be run on shutdown or even before Plasma itself starts.<br />
* Shell scripts will only be run if they are marked executable.<br />
}}<br />
<br />
Place [[Desktop entries]] (i.e. {{ic|.desktop}} files) here:<br />
;{{ic|~/.config/autostart}}:for starting applications at login.<br />
<br />
Place or symlink shell scripts in one of the following directories:<br />
;{{ic|~/.config/plasma-workspace/env}}:for executing scripts at login before launching Plasma.<br />
;{{ic|~/.config/autostart-scripts}}:for executing scripts at login.<br />
;{{ic|~/.config/plasma-workspace/shutdown}}:for executing scripts on shutdown.<br />
<br />
== System administration ==<br />
<br />
=== Terminate Xorg server through KDE System Settings ===<br />
<br />
Navigate to the submenu ''System Settings > Input Devices > Keyboard > Advanced (tab) > "Key Sequence to kill the X server"'' and ensure that the checkbox is ticked.<br />
<br />
=== KCM ===<br />
<br />
KCM stands for '''KC'''onfig '''M'''odule. KCMs can help you configure your system by providing interfaces in System Settings, or through the command line with ''kcmshell5''.<br />
<br />
'''Configuration for look and feel of GTK applications.'''<br />
* {{Pkg|kde-gtk-config}}<br />
* {{AUR|kcm-gtk}}{{Broken package link|{{aur-mirror|kcm-gtk}}}}<br />
* {{AUR|kcm-qt-graphicssystem}}<br />
<br />
'''Configuration for the GRUB bootloader.'''<br />
* {{AUR|grub2-editor}}{{Broken package link|{{aur-mirror|grub2-editor}}}}<br />
<br />
'''Configuration for the [[Uncomplicated Firewall]] (UFW)'''<br />
* {{AUR|kcm-ufw}}<br />
<br />
'''Configuration for [[PolicyKit]]'''<br />
* {{AUR|kcm-polkit-kde-git}}<br />
<br />
'''Configuration for Wacom tablets'''<br />
* {{AUR|kcm-wacomtablet}}<br />
<br />
'''Configuration for systemd'''<br />
* {{Pkg|systemd-kcm}}<br />
<br />
More KCMs can be found at [http://kde-apps.org/index.php?xcontentmode=273 kde-apps.org].<br />
<br />
== Desktop search ==<br />
<br />
KDE implements desktop search with a software called Baloo, a file indexing and searching solution.<br />
<br />
=== Baloo ===<br />
<br />
==== Using and configuring Baloo ====<br />
<br />
In order to search using Baloo on the KDE Plasma Desktop, press {{ic|ALT+F2}} and type in your query. Within Dolphin press {{ic|CTRL+F}}.<br />
<br />
By default the Desktop Search KCM exposes only two options: A panel to blacklist folders and a way to disable it with one click.<br />
<br />
Alternatively you can edit your {{ic|~/.config/baloofilerc}} file ([https://community.kde.org/Baloo/Configuration info]). Additionally the {{ic|balooctl}} process can also be used. In order to disable Baloo run {{ic|balooctl disable}}.<br />
<br />
Once you added additional folders to the blacklist or disabled Baloo entirely, a process named {{ic|baloo_file_cleaner}} removes all unneeded index files automatically. They are stored under {{ic|~/.local/share/baloo/}}.<br />
<br />
More advanced configuration options are available through {{AUR|kcm_baloo_advanced}}{{Broken package link|{{aur-mirror|kcm_baloo_advanced}}}}.<br />
<br />
==== How do I index a removable device? ====<br />
<br />
By default every removable device is blacklisted. You just have to remove your device from the blacklist in the KCM panel.<br />
<br />
=== Web browsers ===<br />
==== Konqueror and Rekonq ====<br />
Konqueror supports two rendering engines – KHTML and QtWebKit (via the {{Pkg|kwebkitpart}} package) – Rekonq supports only QtWebKit. KHTML development was halted after Qt shipped WebKit but was kept for compatibility reasons. QtWebKit, in turn, has since been [https://www.mail-archive.com/development@qt-project.org/msg18866.html deprecated] by the Qt Project and replaced by [[Chromium]]-based Qt WebEngine which is currently not supported by either Konqueror or Rekonq. There is a [http://qtwebkit.blogspot.com/2016/08/qtwebkit-im-back.html community continuation] of QtWebKit.<br />
<br />
A successor named Fiber is currently in development, which will use Chromium's engine.<br />
<br />
==== Chromium and Chrome ====<br />
[[Chromium]] and its proprietary variant Google Chrome have limited Plasma integration. [[KDE_Wallet#KDE_Wallet_for_Chrome_and_Chromium|They can use KWallet]] and KDE Open/Save windows.<br />
<br />
==== Firefox ====<br />
Firefox can be configured to better integrate with Plasma. See [[Firefox#KDE_integration|Firefox KDE integration]] for details.<br />
<br />
==== Qupzilla ====<br />
Qupzilla ({{Pkg|qupzilla}}) is a Qt web browser with Plasma integration features. Qupzilla 2.0 uses Qt WebEngine intead of WebKit. The WebKit variant is also available as {{aur|qupzilla-qtwebkit-git}}.<br />
<br />
== PIM ==<br />
<br />
KDE offers its own stack for personal information management. This includes emails, contacts, calendar, etc.<br />
<br />
=== Akonadi ===<br />
<br />
Akonadi is a system meant to act as a local cache for PIM data, regardless of its origin, which can be then used by other applications. This includes the user's emails, contacts, calendars, events, journals, alarms, notes, and so on.<br />
<br />
Akonadi does not store any data by itself: the storage format depends on the nature of the data (for example, contacts may be stored in vCard format).<br />
<br />
==== Installation ====<br />
<br />
Install {{Pkg|akonadi}}. For additional addons, install {{Pkg|kdepim-addons}}. For EWS support, install {{AUR|akonadi-ews-git}}.<br />
<br />
{{Note|If you wish to use a database engine other than MariaDB/MySQL, then when installing the {{Pkg|akonadi}} package, use the following command to skip installing the {{Pkg|mariadb}} dependencies:<br />
<pre><br />
pacman -S akonadi --assume-installed mariadb<br />
</pre>}}<br />
<br />
==== Disabling Akonadi ====<br />
<br />
See this [http://userbase.kde.org/Akonadi#Disabling_the_Akonadi_subsystem section in the KDE userbase].<br />
<br />
==== Database configuration ====<br />
<br />
===== MariaDB/MySQL =====<br />
<br />
====== Using ZFS ======<br />
<br />
If your home directory is on a ZFS pool, you will need to create {{ic|~/.config/akonadi/mysql-local.conf}} with the following contents:<br />
<br />
[mysqld]<br />
innodb_use_native_aio = 0<br />
<br />
Otherwise you will get the [[MySQL#OS error 22 when running on ZFS|OS error 22]]<br />
<br />
===== PostgreSQL =====<br />
<br />
<ol><br />
<li> Install and setup PostgreSQL (see [[PostgreSQL]])<br />
<ul><li> Enable the {{ic|postgresql}} [[systemd]] service: {{ic|systemctl enable postgresql.service}}.</li></ul></li><br />
<li>Create the {{ic|~/.config/akonadi/akonadiserverrc}} file if it does not exist.</li><br />
<li>Edit {{ic|~/.config/akonadi/akonadiserverrc}} file so that it has the following contents:<br />
<pre><br />
[General]<br />
Driver=QPSQL<br />
<br />
[QPSQL]<br />
Host=/run/postgresql/<br />
InitDbPath=/usr/bin/initdb<br />
Name=akonadi<br />
Options=<br />
Password=<br />
Port=5432<br />
ServerPath=/usr/bin/pg_ctl<br />
StartServer=true<br />
User=postgres<br />
</pre><br />
{{Note|If your PostgreSQL database username, password, and port differ from {{ic|postgres}}, {{ic|}} (nothing), and {{ic|5432}}, then make sure you respectively change the configuration options, {{ic|1=User=}}, {{ic|1=Password=}}, and {{ic|1=Port=}}.}}</li><br />
<li>Start Akonadi: {{ic|akonadictl start}}, and check its status: {{ic|akonadictl status}}.</li><br />
</ol><br />
<br />
===== SQLite =====<br />
Edit {{ic|~/.config/akonadi/akonadiserverrc}} to match the configuration below:<br />
<br />
[General]<br />
Driver=QSQLITE3<br />
<br />
[QSQLITE3]<br />
Name=/home/username/.local/akonadi/akonadi.db<br />
<br />
== Phonon ==<br />
<br />
From [[Wikipedia:Phonon (software)|Wikipedia]]:<br />
<br />
:''“Phonon is the multimedia API provided by KDE and is the standard abstraction for handling multimedia streams within KDE software and also used by several Qt applications.<br />
<br />
Phonon was originally created to allow KDE and Qt software to be independent of any single multimedia framework such as GStreamer or xine and to provide a stable API for a major version's lifetime.”''<br />
<br />
'''Phonon''' is being widely used within KDE, for both audio (e.g., the System notifications or KDE audio apps) and video (e.g., the Dolphin video thumbnails).<br />
<br />
=== Which backend should I choose? ===<br />
You can choose between backends based on [[GStreamer]] and [[VLC]] – each available in versions for Qt4 applications and Qt5 applications ({{Pkg|phonon-qt4-gstreamer}}, {{Pkg|phonon-qt5-gstreamer}} – {{Pkg|phonon-qt4-vlc}}, {{Pkg|phonon-qt5-vlc}}).<br />
<br />
[https://www.phoronix.com/scan.php?page=news_item&px=MTUwNDM Upstream prefers VLC] but prominent Linux distributions (Kubuntu and Fedora-KDE for example) prefer GStreamer because that allows them to easily leave out patented MPEG codecs from the default installation. Both backends have a slightly different [http://community.kde.org/Phonon/FeatureMatrix features set].<br />
<br />
In the past other backends were developed as well but are no longer maintained and their AUR packages have been deleted.<br />
<br />
{{Note|1=<br><br />
* Multiple backends can be installed at once and prioritized at ''System Settings > Multimedia > Phonon > Backend''. For Plasma 5 this would be ''System Settings > Multimedia > Backend''.<br />
* According to the [https://forum.kde.org/viewtopic.php?f=250&t=126476&p=335080 KDE forums], the VLC backend lacks support for [[wikipedia:ReplayGain|ReplayGain]].}}<br />
{{Note|1=<br><br />
* If you choose the vlc backend, you may experience crashes every time kde wants to send you a audible warning (and in quite a number of other cases as well, see [https://forum.kde.org/viewtopic.php?f=289&t=135956])<br />
* A possible fix is to run<br />
{{bc|# /usr/lib/vlc/vlc-cache-gen -f /usr/lib/vlc/plugins}}<br />
}}<br />
<br />
== Useful applications ==<br />
<br />
The official set of KDE applications may be found [http://www.kde.org/applications/ here].<br />
<br />
=== Yakuake ===<br />
<br />
[[Yakuake]] provides a Quake-like terminal emulator whose visibility is toggled by the F12 key. It also has support for multiple tabs. Yakuake is available in the package {{Pkg|yakuake}}.<br />
<br />
=== KDE Telepathy ===<br />
<br />
[http://community.kde.org/KTp KDE Telepathy] is a project with the goal to closely integrate Instant Messaging with the KDE desktop. It utilizes the Telepathy framework as a backend and is intended to replace Kopete.<br />
<br />
To install all Telepathy protocols, install the {{Grp|telepathy}} group.<br />
To use the KDE Telepathy client, install the {{Pkg|telepathy-kde-meta}} package that includes all the packages contained in the {{Grp|telepathy-kde}} group.<br />
<br />
==== Use Telegram with KDE Telepathy ====<br />
<br />
Telegram protocol is available using {{pkg|telepathy-haze}}, installing {{aur|telegram-purple}} or {{aur|telegram-purple-git}} and {{aur|telepathy-morse-git}}. The username is the Telegram account telephone number (complete with the national prefix '+xx', e.g. '+49' for Germany). The configuration through the GUI may be tricky: if the phone number is not accepted when configuring a new account in the KDE Telepathy client (with an error message complaining about an invalid parameter which prevents the account creation), insert it between single quotes and then remove the quotes manually from the configuration file ({{ic|~/.local/share/telepathy/mission-control/accounts.cfg}}) after the account creation (if the quotes are not removed after, an authentication error should rise). Note that the configuration file should be edited manually when KDE Telepathy is not running, e.g. when there is no KDE desktop session active, otherwise manual changes may be overwritten by the software.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Using an alternative window manager ===<br />
There may be reasons you want to use another window manager than KWin, for example to work around the DRI bug that causes [[PRIME#Black_screen_with_GL-based_compositors|black screen with PRIME]].<br />
<br />
To use an alternative [[window manager]] with Plasma open the ''System Settings'' panel, navigate to ''(Default) Applications > Window Manager > Use a different window manager'' and select the window manager you wish to use from the list.<br />
<br />
==== KDE/Openbox session ====<br />
<br />
The {{Pkg|openbox}} package provides a session for using KDE with [[Openbox]]. To make use of this session, select ''KDE/Openbox'' from the [[display manager]] menu.<br />
<br />
For those starting the session manually, add the following line to your {{ic|.xinitrc}} file:<br />
exec openbox-kde-session<br />
<br />
==== Compiz custom ====<br />
<br />
If you need to run Compiz with custom options and switches select ''Compiz custom'' and then create a script called {{ic|compiz-kde-launcher}} and add to it the commands you wish to use to start Compiz. See the example below:<br />
<br />
{{hc|/usr/local/bin/compiz-kde-launcher|<nowiki><br />
#!/bin/bash<br />
LIBGL_ALWAYS_INDIRECT=1<br />
compiz --replace &<br />
wait<br />
</nowiki>}}<br />
<br />
Then make it executable:<br />
$ chmod +x /usr/local/bin/compiz-kde-launcher<br />
<br />
==== Re-enabling compositing effects ====<br />
<br />
When replacing Kwin with a window manager which does not provide a Compositor (such as Openbox), any desktop compositing effects e.g. transparency will be lost. In this case, install and run a separate Composite manager to provide the effects such as [[Xcompmgr]] or [[Compton]].<br />
<br />
=== Integrate Android ===<br />
<br />
KDE Connect provides several features for you:<br />
* Share files and URLs to/from KDE from/to any app, without wires.<br />
* Touchpad emulation: Use your phone screen as your computer's touchpad.<br />
* Notifications sync (4.3+): Read your Android notifications from the desktop.<br />
* Shared clipboard: copy and paste between your phone and your computer.<br />
* Multimedia remote control: Use your phone as a remote for Linux media players.<br />
* WiFi connection: no usb wire or bluetooth needed.<br />
* RSA Encryption: your information is safe.<br />
<br />
You will need to install KDE Connect both on your computer and on your Android. For PC side, install {{Pkg|kdeconnect}} package. For Android side, install {{ic|KDE Connect}} from [https://play.google.com/store/apps/details?id=org.kde.kdeconnect_tp Google Play] or from [https://f-droid.org/repository/browse/?fdid=org.kde.kdeconnect_tp F-Droid].<br />
<br />
=== Configure KWin to use OpenGL ES ===<br />
Set environment variable {{ic|KWIN_COMPOSE}} to 'O2ES' to force the OpenGL ES backend. Please note that OpenGL ES is not supported by all drivers.<br />
<br />
=== Speed up application startup ===<br />
<br />
User Rob described a "[http://kdemonkey.blogspot.nl/2008/04/magic-trick.html magic trick]" on his blog to improve application start-up time by 50-150ms.<br />
To enable it, create this folder in your home:<br />
$ mkdir ~/.compose-cache/<br />
It can produce freezes under heavy io. To avoid this, also do:<br />
$ ln -sfv /run/user/$UID/ /home/$USER/.compose-cache<br />
<br />
{{Note|For those curious about what is going on here, this enables an optimization which Lubos (of general KDE speediness fame) came up with some time ago and was then rewritten and integrated into libx11. Ordinarily, on startup, applications read input method information from {{ic|/usr/share/X11/locale/''your locale''/Compose}}. This file is quite long (>5000 lines for the en_US.UTF-8 one) and takes some time to process. libX11 can create a cache of the parsed information which is much quicker to read subsequently, but it will only re-use an existing cache or create a new one in {{ic|~/.compose-cache}} if the directory already exists.}}<br />
<br />
=== Configuring monitor resolution / multiple monitors ===<br />
<br />
To enable display resolution management and multiple monitors in Plasma 5, install {{Pkg|kscreen}}. This adds the additional options to System Settings/Display and Monitor.<br />
<br />
=== Open application launcher with Super key (Windows key) ===<br />
<br />
{{Note|Since plasma 5.8 release, this workaround is no longer needed. Pressing {{Ic|super}} key launches kickstart application launcher as if {{Ic|alt+F1}} keys are pressed.}}<br />
<br />
Install and start {{Pkg|ksuperkey}}. Now assign Alt + F1 as hot key. The Super Key will now open the application launcher. You can add ksuperkey to the autostart if you don't want to start it manually.<br />
<br />
=== Enabling touchpad tap to click on plasma wayland session ===<br />
<br />
Currently, it's not possible to [https://bugs.kde.org/show_bug.cgi?id=363109 configure tap to click via systemsettings] on plasma wayland session. [https://bugs.kde.org/show_bug.cgi?id=366605#c4 A workaround] is provided to configure tap to click on plasma wayland session via dbus.<br />
<br />
Here are simplified steps to get touchpad tap to click enabled on plasma wayland session.<br />
<br />
1. Identify on which libinput recognizes the touchpad device.<br />
{{Hc|# libinput-list-devices|<br />
Device: ETPS/2 Elantech Touchpad<br />
Kernel: /dev/input/event14<br />
Group: 7<br />
Seat: seat0, default<br />
Size: 78.28x38.78mm<br />
Capabilities: pointer<br />
Tap-to-click: disabled<br />
Tap-and-drag: enabled<br />
Tap drag lock: disabled<br />
Left-handed: disabled<br />
Nat.scrolling: disabled<br />
Middle emulation: n/a<br />
Calibration: n/a<br />
Scroll methods: *two-finger edge<br />
Click methods: none<br />
Disable-w-typing: enabled<br />
Accel profiles: none<br />
Rotation: n/a<br />
}}<br />
In this case, the touchpad is identified as {{Ic|event14}}<br />
<br />
2. Check whether KDE Dbus recognizes the touchpad. Replace {{Ic|event14}} with the touchpad identifier found from {{Ic|libinput-list-devices}}.<br />
{{Hc|$ qdbus org.kde.KWin.InputDevice /org/kde/KWin/InputDevice/event14 org.freedesktop.DBus.Properties.Get org.kde.KWin.InputDevice name|<br />
ETPS/2 Elantech Touchpad<br />
}}<br />
<br />
3. Check the current value of {{Ic|tapToClick}}.<br />
{{Hc|$ qdbus org.kde.KWin.InputDevice /org/kde/KWin/InputDevice/event14 org.freedesktop.DBus.Properties.Get org.kde.KWin.InputDevice tapToClick|<br />
false<br />
}}<br />
<br />
4. Now set the {{Ic|tapToClick}} value to {{Ic|true}}.<br />
{{Hc|$ qdbus org.kde.KWin.InputDevice /org/kde/KWin/InputDevice/event14 org.freedesktop.DBus.Properties.Set org.kde.KWin.InputDevice tapToClick true<br />
|<br />
}}<br />
<br />
5. Confirm that {{Ic|tapToClick}} value is {{Ic|true}}.<br />
{{Hc|$ qdbus org.kde.KWin.InputDevice /org/kde/KWin/InputDevice/event14 org.freedesktop.DBus.Properties.Get org.kde.KWin.InputDevice tapToClick|<br />
true<br />
}}<br />
<br />
After these steps performed, tap to click should work as expected.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Configuration related ===<br />
<br />
Many problems in KDE are related to configuration.<br />
<br />
==== Plasma desktop behaves strangely ====<br />
<br />
Plasma problems are usually caused by unstable '''Plasma widgets''' (colloquially called ''plasmoids'') or '''Plasma themes'''. First, find which was the last widget or theme you had installed and disable it or uninstall it.<br />
<br />
So, if your desktop suddenly exhibits "locking up", this is likely caused by a faulty installed widget. If you cannot remember which widget you installed before the problem began (sometimes it can be an irregular problem), try to track it down by removing each widget until the problem ceases. Then you can uninstall the widget, and file a bug report (bugs.kde.org) '''only if it is an official widget'''. If it is not, it is recommended you find the entry on kde-look.org and inform the developer of that widget about the problem (detailing steps to reproduce, etc).<br />
<br />
If you cannot find the problem, but you do not want ''all'' the settings to be lost, navigate to {{ic|~/.config}}:<br />
<br />
$ for j in plasma*; do mv -- "$j" "${j%}.bak"; done<br />
<br />
This command will '''rename all Plasma related configs''' to *.bak (e.g. {{ic|plasmarc.bak}}) of your user and when you will relogin into Plasma, you will have the '''default''' settings back. To undo that action, remove the .bak file extension. If you already have *.bak files, rename, move, or delete them first. It is highly recommended that you create regular backups anyway. See [[Synchronization and backup programs]] for a list of possible solutions.<br />
<br />
==== Clean cache to resolve upgrade problems ====<br />
<br />
The [https://bbs.archlinux.org/viewtopic.php?id=135301 problem] may be caused by old cache. Sometimes after an upgrade, the old cache might introduce strange, hard to debug behaviour such as unkillable shells, hangs when changing various settings and several other problems such as ark being unable to unrar or unzip or amarok not recognizing any of your music. This solution can also resolve problems with KDE and Qt programmes looking bad following upgrade.<br />
<br />
Rebuild your cache with the following commands:<br />
<br />
$ rm ~/.config/Trolltech.conf<br />
$ kbuildsycoca4 --noincremental<br />
<br />
Hopefully, your problems are now fixed.<br />
<br />
=== Clean akonadi configuration to fix KMail ===<br />
<br />
First, make sure that KMail is not running. Then backup configuration:<br />
$ mv ~/.local/share/akonadi ~/.local/share/akonadi-old<br />
$ mv ~/.config/akonadi ~/.config/akonadi-old<br />
<br />
Start ''SystemSettings > Personal'' and remove all the resources. Go back to Dolphin and remove the original {{ic|~/.local/share/akonadi}} and<br />
{{ic|~/.config/akonadi}} - the copies you made ensure that you can back-track if necessary.<br />
<br />
Now go back to the System Settings page and carefully add the necessary resources. You should see the resource reading in your mail folders. Then start Kontact/KMail to see if it work properly.<br />
<br />
=== Fix empty IMAP inbox ===<br />
<br />
For some IMAP accounts, kmail will show the inbox as a container with all other folders of this account inside. Kmail does not show messages in the inbox container but in all other subfolders [https://bugs.kde.org/show_bug.cgi?id=284172]. To solve this problem simply disable the server side subscribition in the kmail account settings.<br />
<br />
=== Getting current state of KWin for support and debug purposes ===<br />
<br />
This command prints out a wonderful summary of the current state of KWin including used options, used compositing backend and relevant OpenGL driver capabilities. See more on [http://blog.martin-graesslin.com/blog/2012/03/on-getting-help-for-kwin-and-helping-kwin/ Martin's blog].<br />
<br />
$ qdbus org.kde.KWin /KWin supportInformation<br />
<br />
=== KDE and Qt programs look bad when in a different window manager ===<br />
<br />
If you are using KDE or Qt programs but not in a full Plasma session (specifically, you did not run {{ic|startkde}}), then as of Plasma 4.6.1 you will need to tell Qt how to find KDE's styles (Oxygen, QtCurve etc.)<br />
<br />
You just need to set the environment variable {{ic|QT_PLUGIN_PATH}}. E.g. put:<br />
<br />
export QT_PLUGIN_PATH=$HOME/.kde4/lib/kde4/plugins/:/usr/lib/kde4/plugins/<br />
<br />
into your {{ic|/etc/profile}} (or {{ic|~/.profile}} if you do not have root access). {{ic|qtconfig-qt4}} should then be able to find your KDE styles and everything should look nice again!<br />
<br />
Alternatively, you can symlink the Qt styles directory to the KDE styles one:<br />
# ln -s /usr/lib/kde4/plugins/styles/ /usr/lib/qt4/pluginlib32-libdbusmenu-glibs/styles<br />
<br />
Under Gnome you can try to install the package libgnomeui.<br />
<br />
=== KF5/Qt5 applications don't display icons in i3/fvwm/awesome ===<br />
<br />
See [[Qt#Configuration of Qt5 apps under environments other than KDE]].<br />
<br />
=== Graphical related problems ===<br />
<br />
==== Plasma keeps crashing with legacy Nvidia ====<br />
<br />
This is caused by a [https://bugs.kde.org/show_bug.cgi?id=348753 bug in Plasma] when using the Nvidia-304xx driver. Rather than disabling compositing, create a file {{ic|kwin.sh}} in {{ic|~/.config/plasma-workspace/env/}} with the following contents:<br />
<br />
#!/bin/sh<br />
export KWIN_EXPLICIT_SYNC=0<br />
<br />
Then go to ''system-settings > Startup and Shutdown > Autostart'' and ''Check/Add'' the script as a pre-KDE startup file.<br />
<br />
==== Applications don't refresh properly ====<br />
<br />
If you use 3D-accelerated composition with [[Intel]], you might find that the Plasma panel and other applications don't refresh properly (stay frozen). Some Intel drivers have [https://bugzilla.redhat.com/show_bug.cgi?id=1259475 problems with EGL]. Go to System Settings under ''Display and Monitor'' -> ''Compositor''. Set ''OpenGL interface'' to OpenGL 3.1. If that does not work, see [[Intel graphics#SNA issues]] for alternative solutions.<br />
<br />
==== Low 2D desktop performance (or) artifacts appear when on 2D ====<br />
<br />
===== GPU driver problem =====<br />
<br />
Make sure you have the proper driver for your card installed, so that your desktop is at least 2D accelerated. Follow these articles for more information: [[ATI]], [[NVIDIA]], [[Intel]] for more information, in order to make sure that everything is all right.<br />
The open-source ATI and Intel drivers and the proprietary (binary) Nvidia driver should theoretically provide the best 2D and 3D acceleration.<br />
<br />
===== The Raster engine workaround =====<br />
{{Accuracy|xrender is not default in plasma 5. XRender should not be recommended anymore.}}<br />
If this does not solve your problems, your driver may not provide a good '''XRender''' acceleration which the current Qt painter engine relies on by default.<br />
<br />
You can change the painter engine to software based only by invoking the application with the {{ic|-graphicssystem raster}} command line. This rendering engine can be set as the default one by recompiling Qt with the same as configure option, {{ic|-graphicssystem raster}}.<br />
<br />
The raster paint engine enables the CPU to do the majority of the painting, as opposed to the GPU. You may get better performance, depending on your system. This is basically a work-around for the terrible Linux driver stack, since the CPU should obviously not be doing graphical computations since it is designed for fewer threads of greater complexity, as opposed to the GPU which is many threads but lesser computational strength. So, only use Raster engine if you are having problems or your GPU is much slower than you CPU, otherwise is better to use XRender.<br />
<br />
Since Qt 4.7+, recompiling Qt is not needed. Simply export {{ic|1=QT_GRAPHICSSYSTEM=raster}}, or {{ic|opengl}}, or {{ic|native}} (for the default). Raster depends on the CPU, OpenGL depends on the GPU and high driver support, and Native is just using the X11 rendering (mixture, usually).<br />
<br />
'''The best and automatic way to do that''' is to install {{AUR|kcm-qt-graphicssystem}} from AUR and configure this particular Qt setting through ''System Settings > Qt Graphics System''.<br />
<br />
For more information, consult this [http://apachelog.wordpress.com/2010/09/05/qt-graphics-system-kcm/ KDE Developer blog entry] and/or this [https://web.archive.org/web/20100430183745/http://labs.trolltech.com/blogs/2009/12/18/qt-graphics-and-performance-the-raster-engine Qt Developer blog entry].<br />
<br />
==== Low 3D desktop performance====<br />
<br />
KDE begins with desktop effects enabled. Older cards may be insufficient for 3D desktop acceleration. You can disable desktop effects in ''System Settings > Desktop Effects'' and you can toggle desktop effects with {{ic|Alt+Shift+F12}}.<br />
<br />
{{Note| You may encounter such problems with 3D desktop performance even when using a more powerful graphics card. Make sure the GPU driver and it's components has been successfully installed.}}<br />
<br />
==== Desktop compositing is disabled on my system with a modern Nvidia GPU ====<br />
<br />
Sometimes, KWin may have settings in its configuration file ({{ic|kwinrc}}) that ''may'' cause a problem on re-activating the 3D desktop {{ic|OpenGL}} compositing. That could be caused randomly (for example, due to a sudden Xorg crash or restart, and it gets corrupted), so, in case that happens, delete your {{ic|~/.kde4/share/config/kwinrc}} file and relogin. The KWin settings will turn to the KDE default ones and the problem should be probably gone.<br />
<br />
==== Flickering in fullscreen when compositing is enabled ====<br />
<br />
As of KDE SC 4.6.0, there is an option in ''Sytem Settings > Desktop Effect > Advanced > Suspend desktop effects for fullscreen windows''. Uncheck it would tell kwin to disable unredirect fullscren.<br />
<br />
==== Display settings lost on reboot (multiple monitors) ====<br />
There is a [https://bugs.kde.org/show_bug.cgi?id=346961 bug] in kscreen that makes it forget dual screen settings after reboot with certain displays.<br />
A possible workaround is to uninstall {{Pkg|kscreen}} and specify your screen setup in a xorg.conf file instead:<br />
* See [[Multihead#RandR]] for using the [[Wikipedia:RandR|RandR]] [[Wikipedia:X Window System|X Window System]] extension.<br />
* For Nouveau you can use the template at [[Nouveau#Dual Head]], just edit it to suit your setup.<br />
* For the proprietary nvidia driver you can use the [[NVIDIA#Using_NVIDIA_Settings|nvidia-settings]] utility as root to write the config file.<br />
<br />
=== Sound problems under KDE ===<br />
<br />
==== ALSA related problems ====<br />
<br />
{{Note|First make sure you have {{Pkg|alsa-lib}} and {{Pkg|alsa-utils}} installed.}}<br />
<br />
===== "Falling back to default" messages when trying to listen to any sound in KDE =====<br />
<br />
When you encounter such messages:<br />
The audio playback device ''name_of_the_sound_device'' does not work.<br />
Falling back to default<br />
Go to ''System Settings > Multimedia > Phonon'' and set the device named {{ic|default}} above all the other devices in each box you see.<br />
<br />
===== MP3 files cannot be played when using the GStreamer Phonon backend =====<br />
<br />
This can be solved by installing the GStreamer libav plugin (package {{Pkg|gst-libav}}). If you still encounter problems, you can try changing the Phonon backend used by installing another such as {{Pkg|phonon-qt4-vlc}} or {{Pkg|phonon-qt5-vlc}}.<br />
Then, make sure the backend is preferred via ''System Settings > Multimedia > Phonon > Backend (tab)''.<br />
<br />
=== Konsole does not save commands' history ===<br />
<br />
By default console command history is saved only when you type 'exit' in console. When you close Konsole with 'x' in the corner it does not happen.<br />
To enable autosaving after every command execution:<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
shopt -s histappend<br />
[[ "${PROMPT_COMMAND}" ]] && PROMPT_COMMAND="$PROMPT_COMMAND;history -a" || PROMPT_COMMAND="history -a"<br />
</nowiki>}}<br />
<br />
=== Inotify folder watch limit ===<br />
<br />
If you get the following error:<br />
<br />
KDE Baloo Filewatch service reached the inotify folder watch limit. File changes may be ignored.<br />
<br />
Then you will need to increase the inotify folder watch limit:<br />
<br />
# echo 10000 > /proc/sys/fs/inotify/max_user_watches<br />
<br />
To make changes permanent, create {{ic|/etc/sysctl.d/90-inotify.conf}} with<br />
<br />
#increase inotify watch limit<br />
fs.inotify.max_user_watches = 10000<br />
<br />
=== Freezes when using Automount on a NFS volume ===<br />
<br />
Using [[Fstab#Automount with systemd]] on a [[NFS]] volume may cause freezes, see [https://bugs.kde.org/show_bug.cgi?id=354137 bug report upstream].<br />
<br />
=== Locale warning when installing packages in Konsole ===<br />
<br />
mandb: can't set the locale; make sure $lc_* and $lang are correct<br />
<br />
By default, Konsole sets $LANG to en_US.US-ASCII. If you haven't generated that locale, then mandb can't use it. In your Konsole profile settings, click "Environment" and then add a line for LANG=en_US.UTF-8 or whatever your locale should be.<br />
<br />
=== Multi-monitor issues ===<br />
<br />
The current release of KDE Plasma has several issues with multi-monitor setups, which can make Plasma unusable. See [https://bugs.kde.org/show_bug.cgi?id=356225 KDE Bug 356225].<br />
<br />
These bugs have been resolved in the upstream/git KDE Plasma builds, which can be installed from {{AUR|plasma-desktop-git}} or {{AUR|plasma-git-meta}} - bear in mind that all packages will conflict with current versions - it is recommended to [[remove]] them first.<br />
<br />
== Unstable releases ==<br />
<br />
See [[Official repositories#kde-unstable]]<br />
<br />
== Bugs ==<br />
<br />
It is preferable that if you find a minor or serious bug, you should visit [https://bugs.archlinux.org the Arch Bug Tracker] or/and [http://bugs.kde.org KDE Bug Tracker] in order to report that. Make sure that you are clear about what you want to report.<br />
<br />
If you have any problem and you write about in on the Arch forums, first make sure that you have '''fully''' updated your system using a good sync mirror (check [https://www.archlinux.de/?page=MirrorStatus here]) or try [[Reflector]].<br />
<br />
== See also ==<br />
<br />
* [http://www.kde.org KDE homepage]<br />
* [https://bugs.kde.org KDE bug tracker]<br />
* [https://projects.kde.org KDE Projects]<br />
* [http://blog.martin-graesslin.com/blog/kategorien/kde/ Martin Graesslin's blog]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=KDE&diff=454585KDE2016-10-20T12:03:30Z<p>Alive4ever: /* Tips and tricks */ Enabling tap to click on plasma wayland session</p>
<hr />
<div>[[Category:KDE]]<br />
[[ar:KDE]]<br />
[[cs:KDE]]<br />
[[de:KDE]]<br />
[[es:KDE]]<br />
[[fr:KDE]]<br />
[[it:KDE]]<br />
[[ja:KDE]]<br />
[[pl:KDE]]<br />
[[ru:KDE]]<br />
[[tr:KDE Masaüstü Ortamı]]<br />
[[zh-CN:KDE]]<br />
[[zh-TW:KDE]]<br />
{{Related articles start}}<br />
{{Related|Desktop environment}}<br />
{{Related|Display manager}}<br />
{{Related|Dolphin}}<br />
{{Related|Window manager}}<br />
{{Related|Qt}}<br />
{{Related|KDM}}<br />
{{Related|KDevelop}}<br />
{{Related|Trinity}}<br />
{{Related|Uniform Look for Qt and GTK Applications}}<br />
{{Related articles end}}<br />
<br />
KDE is a software project currently comprising of a [[desktop environment]] known as Plasma (or Plasma Workspaces), a collection of libraries and frameworks (KDE Frameworks) and several applications (KDE Applications) as well. KDE upstream has a well maintained [http://userbase.kde.org/ UserBase wiki]. Detailed information about most KDE applications can be found there.<br />
<br />
== Installation ==<br />
<br />
=== Plasma Desktop ===<br />
<br />
{{Note|<br />
*Plasma 5 is not co-installable with Plasma 4.<br />
*The Plasma 4 desktop is unmaintained since August 2015.[https://www.kde.org/announcements/announce-applications-15.08.0.php] It is no longer in the official repositories since December 2015.[https://www.archlinux.org/news/dropping-plasma-4/]<br />
* [[KDM]] is no longer available for Plasma 5. KDE upstream [http://blog.davidedmundson.co.uk/blog/display_managers_finale recommends] using the [[SDDM]] display manager as it provides integration with the Plasma 5 theme.}}<br />
<br />
Before installing Plasma, make sure you have a working [[Xorg]] installation on your system.<br />
<br />
Install the {{Pkg|plasma-meta}} meta-package or the {{Grp|plasma}} group. For differences between {{Pkg|plasma-meta}} and {{Grp|plasma}} reference [[Creating packages#Meta packages and groups]]. Alternatively, for a more minimal Plasma installation, install the {{Pkg|plasma-desktop}} package.<br />
<br />
=== Upgrading from Plasma 4 to 5 ===<br />
<br />
# Isolate {{ic|multi-user.target}}:{{bc|# systemctl isolate multi-user.target}}<br />
# If you use KDM as display manager, [[disable]] the {{ic|kdm.service}} systemd unit. <br />
# [[Install|Uninstall]] the {{AUR|kdebase-workspace}} package.<br />
# [[Install]] the {{pkg|plasma-meta}} package or the {{grp|plasma}} group.<br />
# [[Enable]] the {{ic|sddm.service}} systemd unit, or install and enable any other [[display manager]].<br />
# Reboot or simply [[start]] the systemd {{ic|sddm.service}} unit.<br />
<br />
{{Note|The Plasma 4 configuration is not automatically migrated to Plasma 5, so you will have to configure your desktop from scratch.}}<br />
<br />
=== KDE applications and language packs ===<br />
<br />
To install the full set of KDE Applications, install the {{Grp|kde-applications}} group or the {{Pkg|kde-applications-meta}} meta-package. Note that this will only install applications, it will not install any version of the Plasma Desktop.<br />
<br />
If you need language files, install {{ic|kde-l10n-'''yourlanguagehere'''}} (e.g. {{Pkg|kde-l10n-de}} for the German language). For a full list of available languages see [https://www.archlinux.org/packages/extra/any/kde-l10n/ this link].<br />
<br />
== Starting Plasma ==<br />
<br />
{{Tip|To better integrate SDDM with Plasma, it is recommended to edit {{ic|/etc/sddm.conf}} to use the breeze theme. Refer to [[SDDM#Theme settings]] for instructions.}}<br />
<br />
To launch a Plasma 5 session, choose ''Plasma'' in your [[display manager]] menu.<br />
<br />
Alternatively, to start Plasma with ''startx'', append {{ic|exec startkde}} to your {{ic|.xinitrc}} file. If you want to start Xorg at login, please see [[Start X at login]].<br />
<br />
=== Wayland ===<br />
<br />
As of Plasma 5.8, Plasma on [[Wayland]] should be usable, although there are a [https://community.kde.org/Plasma/5.8_Errata#Wayland few known problems].<br />
<br />
* To start a Plasma on Wayland session from a display manager, install the {{Pkg|plasma-wayland-session}} package and ''Plasma'' should show up in the display manager.<br />
* To start a Plasma on Wayland session from a console, run {{ic|startplasmacompositor}}.<br />
<br />
== Configuration ==<br />
<br />
Most settings for KDE applications are stored in {{ic|~/.config}}, but some older applications may use {{ic|~/.kde4}}. However, configuring KDE is primarily done through the '''System Settings''' application. It can be started from a terminal by executing ''systemsettings5''.<br />
<br />
Frameworks 5 applications can use KDE 4 configuration however they expect the configuration files to be located in different places. To allow Frameworks 5 applications running in KDE 4 to share the same configurations they may be moved to the new locations and symlinked back to the old. Examples are:<br />
*Konsole profiles from {{ic|~/.kde4/share/apps/konsole}} to {{ic|~/.local/share/konsole/}}<br />
*Application appearance from {{ic|~/.kde4/share/config/kdeglobals}} to {{ic|~/.config/kdeglobals}} <br />
<br />
=== Personalization ===<br />
<br />
==== Plasma desktop ====<br />
<br />
===== Themes =====<br />
<br />
{{Note|1=If the Plasma cursor theme is incorrect in some instances, see the following [https://bbs.archlinux.org/viewtopic.php?pid=1533071#p1533071 forum post] for a workaround.}}<br />
[http://kde-look.org/index.php?xcontentmode=76 Plasma themes] define the look of panels and plasmoids. For easy system-wide installation, some such themes are available in both the official repositories and the [https://aur.archlinux.org/packages.php?O=0&K=plasmatheme&do_Search=Go AUR].<br />
<br />
The easiest way to install themes is by going through the Desktop Settings control panel:<br />
<br />
Workspace Theme > Desktop Theme > Get new Themes<br />
<br />
This will present a nice frontend for [http://www.kde-look.org/ kde-look.org] that allows you to install, uninstall, or update third-party plasmoid scripts with literally just one click.<br />
<br />
Splash and Lock screens are currently unavailable so to customize these screens you have to modify the original theme found in {{ic|/usr/share/plasma/look-and-feel/}}.<br />
See [https://www.kubuntuforums.net/showthread.php?67599-Plasma-5-background-images&s=59832dc20e5bfc2948dbb591d8453f61 this thread] on the Kubuntu forums.<br />
<br />
Note that the [[SDDM]] login screen is not part of this theme.<br />
<br />
====== Qt and GTK+ Applications Appearance ======<br />
<br />
{{Tip|For Qt and GTK theme consistency, see [[Uniform look for Qt and GTK applications]].}}<br />
<br />
;Qt4<br />
For Qt4 applications to have a consistent appearance, there are two options: <br />
Install {{Pkg|breeze-kde4}} and then pick Breeze as GUI Style in {{ic|qtconfig-qt4}}; or install {{Pkg|breeze-gtk}} and pick GTK+ as GUI Style.<br />
<br />
;GTK+<br />
The recommended theme for a pleasant appearance in GTK+ applications is {{Pkg|breeze-gtk}} or {{AUR|gnome-breeze-git}}, a GTK+ theme designed to mimic the appearance of Plasma 5 Breeze.<br />
Install {{Pkg|kde-gtk-config}} and select the installed GTK-theme for GTK2/GTK3-Theme in ''System Settings > Application Style > GNOME Application Style''.<br />
<br />
In some themes, tooltips in GTK+ applications have white text on white backgrounds making it difficult to read. To change the colors in GTK2 applications, find the section for tooltips in the gtkrc file and change it. For GTK3 application two files need to be changed, gtk.css and settings.ini.<br />
<br />
===== Widgets =====<br />
<br />
Plasmoids are little scripted (plasmoid scripts) or coded (plasmoid binaries) KDE applications designed to enhance the functionality of your desktop.<br />
<br />
The easiest way to install plasmoid scripts is by right-clicking onto a panel or the desktop and choosing ''Add Widgets > Get new Widgets > Download Widgets''.<br />
This will present a nice frontend for [http://www.kde-look.org/ kde-look.org] that allows you to install, uninstall, or update third-party plasmoid scripts with literally just one click.<br />
<br />
Many Plasmoid binaries are [https://aur.archlinux.org/packages.php?O=0&K=plasmoid&do_Search=Go&PP=25&SO=d&SB=v available from the AUR].<br />
<br />
===== Sound applet in the system tray =====<br />
<br />
[[Install]] {{Pkg|plasma-pa}} or {{Pkg|kmix}} (start Kmix from the Application Launcher).<br />
<br />
{{Note|1=To adjust the [https://bugs.kde.org/show_bug.cgi?id=313579#c28 step size of volume increments/decrements], add e.g. {{ic|1=VolumePercentageStep=1}} in the {{ic|[Global]}} section of {{ic|~/.kde4/share/config/kmixrc}}}}<br />
<br />
===== Disable panel shadow =====<br />
<br />
As the plasma panel is on top of other windows, its shadow is drawn over them. [https://bbs.archlinux.org/viewtopic.php?pid=1228394#p1228394] To disable this behaviour without impacting other shadows, [[install]] {{Pkg|xorg-xprop}} and run:<br />
<br />
$ xprop -remove _KDE_NET_WM_SHADOW<br />
<br />
then select the panel with the plus-sized cursor. [https://forum.kde.org/viewtopic.php?f=285&t=121592] For automation, install {{Pkg|xorg-xwininfo}} and create the following script:<br />
<br />
{{hc|/usr/local/bin/kde-no-shadow|<nowiki><br />
#!/bin/bash<br />
for WID in $(xwininfo -root -tree | sed '/"Plasma": ("plasmashell" "plasmashell")/!d; s/^ *\([^ ]*\) .*/\1/g'); do<br />
xprop -id $WID -remove _KDE_NET_WM_SHADOW<br />
done<br />
</nowiki>}}<br />
<br />
The script can be run on login with ''Add Script'' in ''Autostart'':<br />
<br />
$ kcmshell5 autostart<br />
<br />
==== Window decorations ====<br />
<br />
[http://kde-look.org/index.php?xcontentmode=75 Window decorations] can be changed in ''System Settings > Workspace Appearance > Window Decorations''.<br />
<br />
There you can also directly download and install more themes with one click, and some are available in the [https://aur.archlinux.org/packages.php?O=0&K=kdestyle&do_Search=Go&PP=25&SO=d&SB=v AUR].<br />
<br />
==== Icon themes ====<br />
<br />
Icon themes can be installed and changed on ''System Settings > Icons''.<br />
{{note|Although all modern Linux desktops share the same icon theme format, desktops like [[GNOME]] use fewer icons (esp. in menus and toolbars). Themes developed for such desktops usually lack icons required by Plasma 5 and KDE apps.<br/><br />
It is recommended to install Plasma compatible icon themes instead.}}<br />
<br />
==== Fonts ====<br />
<br />
===== Fonts in a Plasma session look poor =====<br />
<br />
Try installing the {{Pkg|ttf-dejavu}} and {{Pkg|ttf-liberation}} packages.<br />
<br />
After the installation, be sure to log out and back in. You should not have to modify anything in ''System Settings > Fonts''.<br />
<br />
If you have personally set up how your [[Fonts]] render, be aware that System Settings may alter their appearance. When you go ''System Settings > Appearance > Fonts'' System Settings will likely alter your font configuration file ({{ic|fonts.conf}}).<br />
<br />
There is no way to prevent this, but, if you set the values to match your {{ic|fonts.conf}} file, the expected font rendering will return (it will require you to restart your application or in a few cases restart your desktop). Note that Gnome's Font Preferences also does this.<br />
<br />
===== Fonts are huge or seem disproportional =====<br />
<br />
Try to force font DPI to '''96''' in ''System Settings > Application Appearance > Fonts''.<br />
<br />
If that does not work, try setting the DPI directly in your Xorg configuration as documented [[Xorg#Setting_DPI_manually|here]].<br />
<br />
==== Space efficiency ====<br />
<br />
The Plasma Netbook shell has been dropped from Plasma 5, see the following [https://forum.kde.org/viewtopic.php?f=289&t=126631&p=335947&hilit=plasma+netbook#p335899 KDE forum post]<br />
However, you can achieve something similar by editing the file {{ic|~/.config/kwinrc}} adding <br />
{{ic|1=BorderlessMaximizedWindows=true}} in the {{ic|[Windows]}} section.<br />
<br />
=== Printing ===<br />
<br />
{{Tip|Use the [[CUPS]] web interface for faster configuration. Printers configured in this way can be used in KDE applications. }}<br />
<br />
You can also configure printers in ''System Settings > Printer Configuration''. To use this method, you must first install {{Pkg|print-manager}} and {{Pkg|cups}}.<br />
<br />
The {{ic|avahi-daemon.service}} and {{ic|org.cups.cupsd.service}} daemons must be started first; otherwise, you will get the following error:<br />
The service 'Printer Configuration' does not provide an interface 'KCModule'<br />
with keyword 'system-config- printer-kde/system-config-printer-kde.py'<br />
The factory does not support creating components of the specified type.<br />
<br />
If you are getting the following error, you need to give your user the right to manage printers.<br />
There was an error during CUPS operation: 'cups-authorization-canceled'<br />
<br />
For CUPS, this is set in {{ic|/etc/cups/cups-files.conf}}.<br />
<br />
Adding {{ic|lpadmin}} to {{ic|/etc/group}} and then to the {{ic|SystemGroup}} directive in {{ic|/etc/cups/cups-files.conf}} allows anyone in the {{ic|lpadmin}} group to configure printers. Do ''not'' add the {{ic|lp}} group to the {{ic|SystemGroup}} directive, or printing will fail.<br />
<br />
# groupadd -g107 lpadmin<br />
<br />
{{hc|/etc/cups/cups-files.conf|# Administrator user group...<br />
SystemGroup sys root lpadmin}}<br />
<br />
{{Tip|Read [[CUPS#Configuration]] to get more details on how to configure CUPS.}}<br />
<br />
=== Samba/Windows support ===<br />
<br />
If you want to have access to Windows services, install [[Samba]] (package {{Pkg|samba}}).<br />
<br />
The Dolphin share functionality requires the package {{Pkg|kdenetwork-filesharing}} and usershares, which the stock smb.conf does not have enabled. Instructions to add them are in [[Samba#Creating usershare path]], after which sharing in Dolphin should work out of the box after restarting Samba.<br />
<br />
=== KDE Desktop activities ===<br />
<br />
KDE Desktop Activities are Plasma-based virtual-desktop-like sets of Plasma Widgets where you can independently configure widgets as if you have more than one screen or desktop.<br />
<br />
On your desktop, click the Cashew Plasmoid and, on the pop-up window, press "Activities".<br />
<br />
A plasma bar presenting you the current existing Plasma Desktop Activities will appear at the bottom of the screen. You can navigate between them by pressing the correspondent icons.<br />
<br />
=== Power saving ===<br />
<br />
Plasma has an integrated power saving service called "'''Powerdevil Power Management'''" that may adjust the power saving profile of the system and/or the brightness of the screen (if supported).<br />
<br />
{{Accuracy|Regarding the note below, it might be that the problem is the logind setting ''LidSwitchIgnoreInhibited'' which defaults to ''yes''. [https://bbs.archlinux.org/viewtopic.php?pid&#61;1649022#p1649022]}}<br />
<br />
{{Note|Powerdevil may not [[Power management#Power managers|inhibit]] all logind settings (such as the lid close action for laptops). In these cases, the logind setting itself will need to be changed - see [[Power management#Power management with systemd]].}}<br />
<br />
=== Monitoring changes on local files and directories ===<br />
<br />
KDE now uses '''inotify''' directly from the kernel with '''kdirwatch''' (included in kdelibs), so Gamin or FAM are no longer needed. You may want to install this {{AUR|kdirwatch}}{{Broken package link|{{aur-mirror|kdirwatch}}}} from AUR which is a GUI frontend for kdirwatch.<br />
<br />
=== Autostarting applications ===<br />
<br />
Plasma can autostart applications and run scripts on startup and shutdown. To autostart an application, start {{ic|systemsettings}} and navigate to ''Startup and Shutdown'' -> ''Autostart'' and add the program or shell script of your choice. For applications, a {{ic|.desktop}} file will be created, for shell scripts, a symlink will be created.<br />
{{Note|<br />
* Programs can be autostarted on login only, whilst shell scripts can also be run on shutdown or even before Plasma itself starts.<br />
* Shell scripts will only be run if they are marked executable.<br />
}}<br />
<br />
Place [[Desktop entries]] (i.e. {{ic|.desktop}} files) here:<br />
;{{ic|~/.config/autostart}}:for starting applications at login.<br />
<br />
Place or symlink shell scripts in one of the following directories:<br />
;{{ic|~/.config/plasma-workspace/env}}:for executing scripts at login before launching Plasma.<br />
;{{ic|~/.config/autostart-scripts}}:for executing scripts at login.<br />
;{{ic|~/.config/plasma-workspace/shutdown}}:for executing scripts on shutdown.<br />
<br />
== System administration ==<br />
<br />
=== Terminate Xorg server through KDE System Settings ===<br />
<br />
Navigate to the submenu ''System Settings > Input Devices > Keyboard > Advanced (tab) > "Key Sequence to kill the X server"'' and ensure that the checkbox is ticked.<br />
<br />
=== KCM ===<br />
<br />
KCM stands for '''KC'''onfig '''M'''odule. KCMs can help you configure your system by providing interfaces in System Settings, or through the command line with ''kcmshell5''.<br />
<br />
'''Configuration for look and feel of GTK applications.'''<br />
* {{Pkg|kde-gtk-config}}<br />
* {{AUR|kcm-gtk}}{{Broken package link|{{aur-mirror|kcm-gtk}}}}<br />
* {{AUR|kcm-qt-graphicssystem}}<br />
<br />
'''Configuration for the GRUB bootloader.'''<br />
* {{AUR|grub2-editor}}{{Broken package link|{{aur-mirror|grub2-editor}}}}<br />
<br />
'''Configuration for the [[Uncomplicated Firewall]] (UFW)'''<br />
* {{AUR|kcm-ufw}}<br />
<br />
'''Configuration for [[PolicyKit]]'''<br />
* {{AUR|kcm-polkit-kde-git}}<br />
<br />
'''Configuration for Wacom tablets'''<br />
* {{AUR|kcm-wacomtablet}}<br />
<br />
'''Configuration for systemd'''<br />
* {{Pkg|systemd-kcm}}<br />
<br />
More KCMs can be found at [http://kde-apps.org/index.php?xcontentmode=273 kde-apps.org].<br />
<br />
== Desktop search ==<br />
<br />
KDE implements desktop search with a software called Baloo, a file indexing and searching solution.<br />
<br />
=== Baloo ===<br />
<br />
==== Using and configuring Baloo ====<br />
<br />
In order to search using Baloo on the KDE Plasma Desktop, press {{ic|ALT+F2}} and type in your query. Within Dolphin press {{ic|CTRL+F}}.<br />
<br />
By default the Desktop Search KCM exposes only two options: A panel to blacklist folders and a way to disable it with one click.<br />
<br />
Alternatively you can edit your {{ic|~/.config/baloofilerc}} file ([https://community.kde.org/Baloo/Configuration info]). Additionally the {{ic|balooctl}} process can also be used. In order to disable Baloo run {{ic|balooctl disable}}.<br />
<br />
Once you added additional folders to the blacklist or disabled Baloo entirely, a process named {{ic|baloo_file_cleaner}} removes all unneeded index files automatically. They are stored under {{ic|~/.local/share/baloo/}}.<br />
<br />
More advanced configuration options are available through {{AUR|kcm_baloo_advanced}}{{Broken package link|{{aur-mirror|kcm_baloo_advanced}}}}.<br />
<br />
==== How do I index a removable device? ====<br />
<br />
By default every removable device is blacklisted. You just have to remove your device from the blacklist in the KCM panel.<br />
<br />
=== Web browsers ===<br />
==== Konqueror and Rekonq ====<br />
Konqueror supports two rendering engines – KHTML and QtWebKit (via the {{Pkg|kwebkitpart}} package) – Rekonq supports only QtWebKit. KHTML development was halted after Qt shipped WebKit but was kept for compatibility reasons. QtWebKit, in turn, has since been [https://www.mail-archive.com/development@qt-project.org/msg18866.html deprecated] by the Qt Project and replaced by [[Chromium]]-based Qt WebEngine which is currently not supported by either Konqueror or Rekonq. There is a [http://qtwebkit.blogspot.com/2016/08/qtwebkit-im-back.html community continuation] of QtWebKit.<br />
<br />
A successor named Fiber is currently in development, which will use Chromium's engine.<br />
<br />
==== Chromium and Chrome ====<br />
[[Chromium]] and its proprietary variant Google Chrome have limited Plasma integration. [[KDE_Wallet#KDE_Wallet_for_Chrome_and_Chromium|They can use KWallet]] and KDE Open/Save windows.<br />
<br />
==== Firefox ====<br />
Firefox can be configured to better integrate with Plasma. See [[Firefox#KDE_integration|Firefox KDE integration]] for details.<br />
<br />
==== Qupzilla ====<br />
Qupzilla ({{Pkg|qupzilla}}) is a Qt web browser with Plasma integration features. Qupzilla 2.0 uses Qt WebEngine intead of WebKit. The WebKit variant is also available as {{aur|qupzilla-qtwebkit-git}}.<br />
<br />
== PIM ==<br />
<br />
KDE offers its own stack for personal information management. This includes emails, contacts, calendar, etc.<br />
<br />
=== Akonadi ===<br />
<br />
Akonadi is a system meant to act as a local cache for PIM data, regardless of its origin, which can be then used by other applications. This includes the user's emails, contacts, calendars, events, journals, alarms, notes, and so on.<br />
<br />
Akonadi does not store any data by itself: the storage format depends on the nature of the data (for example, contacts may be stored in vCard format).<br />
<br />
==== Installation ====<br />
<br />
Install {{Pkg|akonadi}}. For additional addons, install {{Pkg|kdepim-addons}}. For EWS support, install {{AUR|akonadi-ews-git}}.<br />
<br />
{{Note|If you wish to use a database engine other than MariaDB/MySQL, then when installing the {{Pkg|akonadi}} package, use the following command to skip installing the {{Pkg|mariadb}} dependencies:<br />
<pre><br />
pacman -S akonadi --assume-installed mariadb<br />
</pre>}}<br />
<br />
==== Disabling Akonadi ====<br />
<br />
See this [http://userbase.kde.org/Akonadi#Disabling_the_Akonadi_subsystem section in the KDE userbase].<br />
<br />
==== Database configuration ====<br />
<br />
===== MariaDB/MySQL =====<br />
<br />
====== Using ZFS ======<br />
<br />
If your home directory is on a ZFS pool, you will need to create {{ic|~/.config/akonadi/mysql-local.conf}} with the following contents:<br />
<br />
[mysqld]<br />
innodb_use_native_aio = 0<br />
<br />
Otherwise you will get the [[MySQL#OS error 22 when running on ZFS|OS error 22]]<br />
<br />
===== PostgreSQL =====<br />
<br />
<ol><br />
<li> Install and setup PostgreSQL (see [[PostgreSQL]])<br />
<ul><li> Enable the {{ic|postgresql}} [[systemd]] service: {{ic|systemctl enable postgresql.service}}.</li></ul></li><br />
<li>Create the {{ic|~/.config/akonadi/akonadiserverrc}} file if it does not exist.</li><br />
<li>Edit {{ic|~/.config/akonadi/akonadiserverrc}} file so that it has the following contents:<br />
<pre><br />
[General]<br />
Driver=QPSQL<br />
<br />
[QPSQL]<br />
Host=/run/postgresql/<br />
InitDbPath=/usr/bin/initdb<br />
Name=akonadi<br />
Options=<br />
Password=<br />
Port=5432<br />
ServerPath=/usr/bin/pg_ctl<br />
StartServer=true<br />
User=postgres<br />
</pre><br />
{{Note|If your PostgreSQL database username, password, and port differ from {{ic|postgres}}, {{ic|}} (nothing), and {{ic|5432}}, then make sure you respectively change the configuration options, {{ic|1=User=}}, {{ic|1=Password=}}, and {{ic|1=Port=}}.}}</li><br />
<li>Start Akonadi: {{ic|akonadictl start}}, and check its status: {{ic|akonadictl status}}.</li><br />
</ol><br />
<br />
===== SQLite =====<br />
Edit {{ic|~/.config/akonadi/akonadiserverrc}} to match the configuration below:<br />
<br />
[General]<br />
Driver=QSQLITE3<br />
<br />
[QSQLITE3]<br />
Name=/home/username/.local/akonadi/akonadi.db<br />
<br />
== Phonon ==<br />
<br />
From [[Wikipedia:Phonon (software)|Wikipedia]]:<br />
<br />
:''“Phonon is the multimedia API provided by KDE and is the standard abstraction for handling multimedia streams within KDE software and also used by several Qt applications.<br />
<br />
Phonon was originally created to allow KDE and Qt software to be independent of any single multimedia framework such as GStreamer or xine and to provide a stable API for a major version's lifetime.”''<br />
<br />
'''Phonon''' is being widely used within KDE, for both audio (e.g., the System notifications or KDE audio apps) and video (e.g., the Dolphin video thumbnails).<br />
<br />
=== Which backend should I choose? ===<br />
You can choose between backends based on [[GStreamer]] and [[VLC]] – each available in versions for Qt4 applications and Qt5 applications ({{Pkg|phonon-qt4-gstreamer}}, {{Pkg|phonon-qt5-gstreamer}} – {{Pkg|phonon-qt4-vlc}}, {{Pkg|phonon-qt5-vlc}}).<br />
<br />
[https://www.phoronix.com/scan.php?page=news_item&px=MTUwNDM Upstream prefers VLC] but prominent Linux distributions (Kubuntu and Fedora-KDE for example) prefer GStreamer because that allows them to easily leave out patented MPEG codecs from the default installation. Both backends have a slightly different [http://community.kde.org/Phonon/FeatureMatrix features set].<br />
<br />
In the past other backends were developed as well but are no longer maintained and their AUR packages have been deleted.<br />
<br />
{{Note|1=<br><br />
* Multiple backends can be installed at once and prioritized at ''System Settings > Multimedia > Phonon > Backend''. For Plasma 5 this would be ''System Settings > Multimedia > Backend''.<br />
* According to the [https://forum.kde.org/viewtopic.php?f=250&t=126476&p=335080 KDE forums], the VLC backend lacks support for [[wikipedia:ReplayGain|ReplayGain]].}}<br />
{{Note|1=<br><br />
* If you choose the vlc backend, you may experience crashes every time kde wants to send you a audible warning (and in quite a number of other cases as well, see [https://forum.kde.org/viewtopic.php?f=289&t=135956])<br />
* A possible fix is to run<br />
{{bc|# /usr/lib/vlc/vlc-cache-gen -f /usr/lib/vlc/plugins}}<br />
}}<br />
<br />
== Useful applications ==<br />
<br />
The official set of KDE applications may be found [http://www.kde.org/applications/ here].<br />
<br />
=== Yakuake ===<br />
<br />
[[Yakuake]] provides a Quake-like terminal emulator whose visibility is toggled by the F12 key. It also has support for multiple tabs. Yakuake is available in the package {{Pkg|yakuake}}.<br />
<br />
=== KDE Telepathy ===<br />
<br />
[http://community.kde.org/KTp KDE Telepathy] is a project with the goal to closely integrate Instant Messaging with the KDE desktop. It utilizes the Telepathy framework as a backend and is intended to replace Kopete.<br />
<br />
To install all Telepathy protocols, install the {{Grp|telepathy}} group.<br />
To use the KDE Telepathy client, install the {{Pkg|telepathy-kde-meta}} package that includes all the packages contained in the {{Grp|telepathy-kde}} group.<br />
<br />
==== Use Telegram with KDE Telepathy ====<br />
<br />
Telegram protocol is available using {{pkg|telepathy-haze}}, installing {{aur|telegram-purple}} or {{aur|telegram-purple-git}} and {{aur|telepathy-morse-git}}. The username is the Telegram account telephone number (complete with the national prefix '+xx', e.g. '+49' for Germany). The configuration through the GUI may be tricky: if the phone number is not accepted when configuring a new account in the KDE Telepathy client (with an error message complaining about an invalid parameter which prevents the account creation), insert it between single quotes and then remove the quotes manually from the configuration file ({{ic|~/.local/share/telepathy/mission-control/accounts.cfg}}) after the account creation (if the quotes are not removed after, an authentication error should rise). Note that the configuration file should be edited manually when KDE Telepathy is not running, e.g. when there is no KDE desktop session active, otherwise manual changes may be overwritten by the software.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Using an alternative window manager ===<br />
There may be reasons you want to use another window manager than KWin, for example to work around the DRI bug that causes [[PRIME#Black_screen_with_GL-based_compositors|black screen with PRIME]].<br />
<br />
To use an alternative [[window manager]] with Plasma open the ''System Settings'' panel, navigate to ''(Default) Applications > Window Manager > Use a different window manager'' and select the window manager you wish to use from the list.<br />
<br />
==== KDE/Openbox session ====<br />
<br />
The {{Pkg|openbox}} package provides a session for using KDE with [[Openbox]]. To make use of this session, select ''KDE/Openbox'' from the [[display manager]] menu.<br />
<br />
For those starting the session manually, add the following line to your {{ic|.xinitrc}} file:<br />
exec openbox-kde-session<br />
<br />
==== Compiz custom ====<br />
<br />
If you need to run Compiz with custom options and switches select ''Compiz custom'' and then create a script called {{ic|compiz-kde-launcher}} and add to it the commands you wish to use to start Compiz. See the example below:<br />
<br />
{{hc|/usr/local/bin/compiz-kde-launcher|<nowiki><br />
#!/bin/bash<br />
LIBGL_ALWAYS_INDIRECT=1<br />
compiz --replace &<br />
wait<br />
</nowiki>}}<br />
<br />
Then make it executable:<br />
$ chmod +x /usr/local/bin/compiz-kde-launcher<br />
<br />
==== Re-enabling compositing effects ====<br />
<br />
When replacing Kwin with a window manager which does not provide a Compositor (such as Openbox), any desktop compositing effects e.g. transparency will be lost. In this case, install and run a separate Composite manager to provide the effects such as [[Xcompmgr]] or [[Compton]].<br />
<br />
=== Integrate Android ===<br />
<br />
KDE Connect provides several features for you:<br />
* Share files and URLs to/from KDE from/to any app, without wires.<br />
* Touchpad emulation: Use your phone screen as your computer's touchpad.<br />
* Notifications sync (4.3+): Read your Android notifications from the desktop.<br />
* Shared clipboard: copy and paste between your phone and your computer.<br />
* Multimedia remote control: Use your phone as a remote for Linux media players.<br />
* WiFi connection: no usb wire or bluetooth needed.<br />
* RSA Encryption: your information is safe.<br />
<br />
You will need to install KDE Connect both on your computer and on your Android. For PC side, install {{Pkg|kdeconnect}} package. For Android side, install {{ic|KDE Connect}} from [https://play.google.com/store/apps/details?id=org.kde.kdeconnect_tp Google Play] or from [https://f-droid.org/repository/browse/?fdid=org.kde.kdeconnect_tp F-Droid].<br />
<br />
=== Configure KWin to use OpenGL ES ===<br />
Set environment variable {{ic|KWIN_COMPOSE}} to 'O2ES' to force the OpenGL ES backend. Please note that OpenGL ES is not supported by all drivers.<br />
<br />
=== Speed up application startup ===<br />
<br />
User Rob described a "[http://kdemonkey.blogspot.nl/2008/04/magic-trick.html magic trick]" on his blog to improve application start-up time by 50-150ms.<br />
To enable it, create this folder in your home:<br />
$ mkdir ~/.compose-cache/<br />
It can produce freezes under heavy io. To avoid this, also do:<br />
$ ln -sfv /run/user/$UID/ /home/$USER/.compose-cache<br />
<br />
{{Note|For those curious about what is going on here, this enables an optimization which Lubos (of general KDE speediness fame) came up with some time ago and was then rewritten and integrated into libx11. Ordinarily, on startup, applications read input method information from {{ic|/usr/share/X11/locale/''your locale''/Compose}}. This file is quite long (>5000 lines for the en_US.UTF-8 one) and takes some time to process. libX11 can create a cache of the parsed information which is much quicker to read subsequently, but it will only re-use an existing cache or create a new one in {{ic|~/.compose-cache}} if the directory already exists.}}<br />
<br />
=== Configuring monitor resolution / multiple monitors ===<br />
<br />
To enable display resolution management and multiple monitors in Plasma 5, install {{Pkg|kscreen}}. This adds the additional options to System Settings/Display and Monitor.<br />
<br />
=== Open application launcher with Super key (Windows key) ===<br />
<br />
{{Note|Since plasma 5.8 release, this workaround is no longer needed. Pressing {{Ic|super}} key launches kickstart application launcher as if {{Ic|alt+F1}} keys are pressed.}}<br />
<br />
Install and start {{Pkg|ksuperkey}}. Now assign Alt + F1 as hot key. The Super Key will now open the application launcher. You can add ksuperkey to the autostart if you don't want to start it manually.<br />
<br />
=== Enabling touchpad tap to click on plasma wayland session ===<br />
<br />
Currently, it's not possible to [https://bugs.kde.org/show_bug.cgi?id=363109 configure tap to click via systemsettings] on plasma wayland session. [https://bugs.kde.org/show_bug.cgi?id=366605#c4 A workaround] is provided to configure tap to click on plasma wayland session via dbus.<br />
<br />
Here are simplified steps to get touchpad tap to click enabled on plasma wayland session.<br />
<br />
1. Identify on which libinput recognizes the touchpad device.<br />
{{Hc|# libinput-list-devices|<br />
Device: ETPS/2 Elantech Touchpad<br />
Kernel: /dev/input/event14<br />
Group: 7<br />
Seat: seat0, default<br />
Size: 78.28x38.78mm<br />
Capabilities: pointer<br />
Tap-to-click: disabled<br />
Tap-and-drag: enabled<br />
Tap drag lock: disabled<br />
Left-handed: disabled<br />
Nat.scrolling: disabled<br />
Middle emulation: n/a<br />
Calibration: n/a<br />
Scroll methods: *two-finger edge<br />
Click methods: none<br />
Disable-w-typing: enabled<br />
Accel profiles: none<br />
Rotation: n/a<br />
}}<br />
In this case, the touchpad is identified as {{Ic|event14}}<br />
<br />
2. Check whether KDE Dbus recognizes the touchpad. Replace {{Ic|event14}} with the touchpad identifier found from {{Ic|libinput-list-devices}}.<br />
{{Hc|$ qdbus org.kde.KWin.InputDevice /org/kde/KWin/InputDevice/eventX org.freedesktop.DBus.Properties.Get org.kde.KWin.InputDevice name|<br />
ETPS/2 Elantech Touchpad<br />
}}<br />
<br />
3. Check the current value of {{Ic|tapToClick}}.<br />
{{Hc|$ qdbus org.kde.KWin.InputDevice /org/kde/KWin/InputDevice/event14 org.freedesktop.DBus.Properties.Get org.kde.KWin.InputDevice tapToClick|<br />
false<br />
}}<br />
<br />
4. Now set the {{Ic|tapToClick}} value to {{Ic|true}}.<br />
{{Hc|$ qdbus org.kde.KWin.InputDevice /org/kde/KWin/InputDevice/event14 org.freedesktop.DBus.Properties.Set org.kde.KWin.InputDevice tapToClick true<br />
|<br />
}}<br />
<br />
5. Confirm that {{Ic|tapToClick}} value is {{Ic|true}}.<br />
{{Hc|$ qdbus org.kde.KWin.InputDevice /org/kde/KWin/InputDevice/event14 org.freedesktop.DBus.Properties.Get org.kde.KWin.InputDevice tapToClick|<br />
true<br />
}}<br />
<br />
After these steps performed, tap to click should work as expected.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Configuration related ===<br />
<br />
Many problems in KDE are related to configuration.<br />
<br />
==== Plasma desktop behaves strangely ====<br />
<br />
Plasma problems are usually caused by unstable '''Plasma widgets''' (colloquially called ''plasmoids'') or '''Plasma themes'''. First, find which was the last widget or theme you had installed and disable it or uninstall it.<br />
<br />
So, if your desktop suddenly exhibits "locking up", this is likely caused by a faulty installed widget. If you cannot remember which widget you installed before the problem began (sometimes it can be an irregular problem), try to track it down by removing each widget until the problem ceases. Then you can uninstall the widget, and file a bug report (bugs.kde.org) '''only if it is an official widget'''. If it is not, it is recommended you find the entry on kde-look.org and inform the developer of that widget about the problem (detailing steps to reproduce, etc).<br />
<br />
If you cannot find the problem, but you do not want ''all'' the settings to be lost, navigate to {{ic|~/.config}}:<br />
<br />
$ for j in plasma*; do mv -- "$j" "${j%}.bak"; done<br />
<br />
This command will '''rename all Plasma related configs''' to *.bak (e.g. {{ic|plasmarc.bak}}) of your user and when you will relogin into Plasma, you will have the '''default''' settings back. To undo that action, remove the .bak file extension. If you already have *.bak files, rename, move, or delete them first. It is highly recommended that you create regular backups anyway. See [[Synchronization and backup programs]] for a list of possible solutions.<br />
<br />
==== Clean cache to resolve upgrade problems ====<br />
<br />
The [https://bbs.archlinux.org/viewtopic.php?id=135301 problem] may be caused by old cache. Sometimes after an upgrade, the old cache might introduce strange, hard to debug behaviour such as unkillable shells, hangs when changing various settings and several other problems such as ark being unable to unrar or unzip or amarok not recognizing any of your music. This solution can also resolve problems with KDE and Qt programmes looking bad following upgrade.<br />
<br />
Rebuild your cache with the following commands:<br />
<br />
$ rm ~/.config/Trolltech.conf<br />
$ kbuildsycoca4 --noincremental<br />
<br />
Hopefully, your problems are now fixed.<br />
<br />
=== Clean akonadi configuration to fix KMail ===<br />
<br />
First, make sure that KMail is not running. Then backup configuration:<br />
$ mv ~/.local/share/akonadi ~/.local/share/akonadi-old<br />
$ mv ~/.config/akonadi ~/.config/akonadi-old<br />
<br />
Start ''SystemSettings > Personal'' and remove all the resources. Go back to Dolphin and remove the original {{ic|~/.local/share/akonadi}} and<br />
{{ic|~/.config/akonadi}} - the copies you made ensure that you can back-track if necessary.<br />
<br />
Now go back to the System Settings page and carefully add the necessary resources. You should see the resource reading in your mail folders. Then start Kontact/KMail to see if it work properly.<br />
<br />
=== Fix empty IMAP inbox ===<br />
<br />
For some IMAP accounts, kmail will show the inbox as a container with all other folders of this account inside. Kmail does not show messages in the inbox container but in all other subfolders [https://bugs.kde.org/show_bug.cgi?id=284172]. To solve this problem simply disable the server side subscribition in the kmail account settings.<br />
<br />
=== Getting current state of KWin for support and debug purposes ===<br />
<br />
This command prints out a wonderful summary of the current state of KWin including used options, used compositing backend and relevant OpenGL driver capabilities. See more on [http://blog.martin-graesslin.com/blog/2012/03/on-getting-help-for-kwin-and-helping-kwin/ Martin's blog].<br />
<br />
$ qdbus org.kde.KWin /KWin supportInformation<br />
<br />
=== KDE and Qt programs look bad when in a different window manager ===<br />
<br />
If you are using KDE or Qt programs but not in a full Plasma session (specifically, you did not run {{ic|startkde}}), then as of Plasma 4.6.1 you will need to tell Qt how to find KDE's styles (Oxygen, QtCurve etc.)<br />
<br />
You just need to set the environment variable {{ic|QT_PLUGIN_PATH}}. E.g. put:<br />
<br />
export QT_PLUGIN_PATH=$HOME/.kde4/lib/kde4/plugins/:/usr/lib/kde4/plugins/<br />
<br />
into your {{ic|/etc/profile}} (or {{ic|~/.profile}} if you do not have root access). {{ic|qtconfig-qt4}} should then be able to find your KDE styles and everything should look nice again!<br />
<br />
Alternatively, you can symlink the Qt styles directory to the KDE styles one:<br />
# ln -s /usr/lib/kde4/plugins/styles/ /usr/lib/qt4/pluginlib32-libdbusmenu-glibs/styles<br />
<br />
Under Gnome you can try to install the package libgnomeui.<br />
<br />
=== KF5/Qt5 applications don't display icons in i3/fvwm/awesome ===<br />
<br />
See [[Qt#Configuration of Qt5 apps under environments other than KDE]].<br />
<br />
=== Graphical related problems ===<br />
<br />
==== Plasma keeps crashing with legacy Nvidia ====<br />
<br />
This is caused by a [https://bugs.kde.org/show_bug.cgi?id=348753 bug in Plasma] when using the Nvidia-304xx driver. Rather than disabling compositing, create a file {{ic|kwin.sh}} in {{ic|~/.config/plasma-workspace/env/}} with the following contents:<br />
<br />
#!/bin/sh<br />
export KWIN_EXPLICIT_SYNC=0<br />
<br />
Then go to ''system-settings > Startup and Shutdown > Autostart'' and ''Check/Add'' the script as a pre-KDE startup file.<br />
<br />
==== Applications don't refresh properly ====<br />
<br />
If you use 3D-accelerated composition with [[Intel]], you might find that the Plasma panel and other applications don't refresh properly (stay frozen). Some Intel drivers have [https://bugzilla.redhat.com/show_bug.cgi?id=1259475 problems with EGL]. Go to System Settings under ''Display and Monitor'' -> ''Compositor''. Set ''OpenGL interface'' to OpenGL 3.1. If that does not work, see [[Intel graphics#SNA issues]] for alternative solutions.<br />
<br />
==== Low 2D desktop performance (or) artifacts appear when on 2D ====<br />
<br />
===== GPU driver problem =====<br />
<br />
Make sure you have the proper driver for your card installed, so that your desktop is at least 2D accelerated. Follow these articles for more information: [[ATI]], [[NVIDIA]], [[Intel]] for more information, in order to make sure that everything is all right.<br />
The open-source ATI and Intel drivers and the proprietary (binary) Nvidia driver should theoretically provide the best 2D and 3D acceleration.<br />
<br />
===== The Raster engine workaround =====<br />
{{Accuracy|xrender is not default in plasma 5. XRender should not be recommended anymore.}}<br />
If this does not solve your problems, your driver may not provide a good '''XRender''' acceleration which the current Qt painter engine relies on by default.<br />
<br />
You can change the painter engine to software based only by invoking the application with the {{ic|-graphicssystem raster}} command line. This rendering engine can be set as the default one by recompiling Qt with the same as configure option, {{ic|-graphicssystem raster}}.<br />
<br />
The raster paint engine enables the CPU to do the majority of the painting, as opposed to the GPU. You may get better performance, depending on your system. This is basically a work-around for the terrible Linux driver stack, since the CPU should obviously not be doing graphical computations since it is designed for fewer threads of greater complexity, as opposed to the GPU which is many threads but lesser computational strength. So, only use Raster engine if you are having problems or your GPU is much slower than you CPU, otherwise is better to use XRender.<br />
<br />
Since Qt 4.7+, recompiling Qt is not needed. Simply export {{ic|1=QT_GRAPHICSSYSTEM=raster}}, or {{ic|opengl}}, or {{ic|native}} (for the default). Raster depends on the CPU, OpenGL depends on the GPU and high driver support, and Native is just using the X11 rendering (mixture, usually).<br />
<br />
'''The best and automatic way to do that''' is to install {{AUR|kcm-qt-graphicssystem}} from AUR and configure this particular Qt setting through ''System Settings > Qt Graphics System''.<br />
<br />
For more information, consult this [http://apachelog.wordpress.com/2010/09/05/qt-graphics-system-kcm/ KDE Developer blog entry] and/or this [https://web.archive.org/web/20100430183745/http://labs.trolltech.com/blogs/2009/12/18/qt-graphics-and-performance-the-raster-engine Qt Developer blog entry].<br />
<br />
==== Low 3D desktop performance====<br />
<br />
KDE begins with desktop effects enabled. Older cards may be insufficient for 3D desktop acceleration. You can disable desktop effects in ''System Settings > Desktop Effects'' and you can toggle desktop effects with {{ic|Alt+Shift+F12}}.<br />
<br />
{{Note| You may encounter such problems with 3D desktop performance even when using a more powerful graphics card. Make sure the GPU driver and it's components has been successfully installed.}}<br />
<br />
==== Desktop compositing is disabled on my system with a modern Nvidia GPU ====<br />
<br />
Sometimes, KWin may have settings in its configuration file ({{ic|kwinrc}}) that ''may'' cause a problem on re-activating the 3D desktop {{ic|OpenGL}} compositing. That could be caused randomly (for example, due to a sudden Xorg crash or restart, and it gets corrupted), so, in case that happens, delete your {{ic|~/.kde4/share/config/kwinrc}} file and relogin. The KWin settings will turn to the KDE default ones and the problem should be probably gone.<br />
<br />
==== Flickering in fullscreen when compositing is enabled ====<br />
<br />
As of KDE SC 4.6.0, there is an option in ''Sytem Settings > Desktop Effect > Advanced > Suspend desktop effects for fullscreen windows''. Uncheck it would tell kwin to disable unredirect fullscren.<br />
<br />
==== Display settings lost on reboot (multiple monitors) ====<br />
There is a [https://bugs.kde.org/show_bug.cgi?id=346961 bug] in kscreen that makes it forget dual screen settings after reboot with certain displays.<br />
A possible workaround is to uninstall {{Pkg|kscreen}} and specify your screen setup in a xorg.conf file instead:<br />
* See [[Multihead#RandR]] for using the [[Wikipedia:RandR|RandR]] [[Wikipedia:X Window System|X Window System]] extension.<br />
* For Nouveau you can use the template at [[Nouveau#Dual Head]], just edit it to suit your setup.<br />
* For the proprietary nvidia driver you can use the [[NVIDIA#Using_NVIDIA_Settings|nvidia-settings]] utility as root to write the config file.<br />
<br />
=== Sound problems under KDE ===<br />
<br />
==== ALSA related problems ====<br />
<br />
{{Note|First make sure you have {{Pkg|alsa-lib}} and {{Pkg|alsa-utils}} installed.}}<br />
<br />
===== "Falling back to default" messages when trying to listen to any sound in KDE =====<br />
<br />
When you encounter such messages:<br />
The audio playback device ''name_of_the_sound_device'' does not work.<br />
Falling back to default<br />
Go to ''System Settings > Multimedia > Phonon'' and set the device named {{ic|default}} above all the other devices in each box you see.<br />
<br />
===== MP3 files cannot be played when using the GStreamer Phonon backend =====<br />
<br />
This can be solved by installing the GStreamer libav plugin (package {{Pkg|gst-libav}}). If you still encounter problems, you can try changing the Phonon backend used by installing another such as {{Pkg|phonon-qt4-vlc}} or {{Pkg|phonon-qt5-vlc}}.<br />
Then, make sure the backend is preferred via ''System Settings > Multimedia > Phonon > Backend (tab)''.<br />
<br />
=== Konsole does not save commands' history ===<br />
<br />
By default console command history is saved only when you type 'exit' in console. When you close Konsole with 'x' in the corner it does not happen.<br />
To enable autosaving after every command execution:<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
shopt -s histappend<br />
[[ "${PROMPT_COMMAND}" ]] && PROMPT_COMMAND="$PROMPT_COMMAND;history -a" || PROMPT_COMMAND="history -a"<br />
</nowiki>}}<br />
<br />
=== Inotify folder watch limit ===<br />
<br />
If you get the following error:<br />
<br />
KDE Baloo Filewatch service reached the inotify folder watch limit. File changes may be ignored.<br />
<br />
Then you will need to increase the inotify folder watch limit:<br />
<br />
# echo 10000 > /proc/sys/fs/inotify/max_user_watches<br />
<br />
To make changes permanent, create {{ic|/etc/sysctl.d/90-inotify.conf}} with<br />
<br />
#increase inotify watch limit<br />
fs.inotify.max_user_watches = 10000<br />
<br />
=== Freezes when using Automount on a NFS volume ===<br />
<br />
Using [[Fstab#Automount with systemd]] on a [[NFS]] volume may cause freezes, see [https://bugs.kde.org/show_bug.cgi?id=354137 bug report upstream].<br />
<br />
=== Locale warning when installing packages in Konsole ===<br />
<br />
mandb: can't set the locale; make sure $lc_* and $lang are correct<br />
<br />
By default, Konsole sets $LANG to en_US.US-ASCII. If you haven't generated that locale, then mandb can't use it. In your Konsole profile settings, click "Environment" and then add a line for LANG=en_US.UTF-8 or whatever your locale should be.<br />
<br />
=== Multi-monitor issues ===<br />
<br />
The current release of KDE Plasma has several issues with multi-monitor setups, which can make Plasma unusable. See [https://bugs.kde.org/show_bug.cgi?id=356225 KDE Bug 356225].<br />
<br />
These bugs have been resolved in the upstream/git KDE Plasma builds, which can be installed from {{AUR|plasma-desktop-git}} or {{AUR|plasma-git-meta}} - bear in mind that all packages will conflict with current versions - it is recommended to [[remove]] them first.<br />
<br />
== Unstable releases ==<br />
<br />
See [[Official repositories#kde-unstable]]<br />
<br />
== Bugs ==<br />
<br />
It is preferable that if you find a minor or serious bug, you should visit [https://bugs.archlinux.org the Arch Bug Tracker] or/and [http://bugs.kde.org KDE Bug Tracker] in order to report that. Make sure that you are clear about what you want to report.<br />
<br />
If you have any problem and you write about in on the Arch forums, first make sure that you have '''fully''' updated your system using a good sync mirror (check [https://www.archlinux.de/?page=MirrorStatus here]) or try [[Reflector]].<br />
<br />
== See also ==<br />
<br />
* [http://www.kde.org KDE homepage]<br />
* [https://bugs.kde.org KDE bug tracker]<br />
* [https://projects.kde.org KDE Projects]<br />
* [http://blog.martin-graesslin.com/blog/kategorien/kde/ Martin Graesslin's blog]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=KDE&diff=454579KDE2016-10-20T11:44:56Z<p>Alive4ever: /* Open application launcher with Super key (Windows key) */ Adding note that ksuperkey is no longer needed as of plasma 5.8</p>
<hr />
<div>[[Category:KDE]]<br />
[[ar:KDE]]<br />
[[cs:KDE]]<br />
[[de:KDE]]<br />
[[es:KDE]]<br />
[[fr:KDE]]<br />
[[it:KDE]]<br />
[[ja:KDE]]<br />
[[pl:KDE]]<br />
[[ru:KDE]]<br />
[[tr:KDE Masaüstü Ortamı]]<br />
[[zh-CN:KDE]]<br />
[[zh-TW:KDE]]<br />
{{Related articles start}}<br />
{{Related|Desktop environment}}<br />
{{Related|Display manager}}<br />
{{Related|Dolphin}}<br />
{{Related|Window manager}}<br />
{{Related|Qt}}<br />
{{Related|KDM}}<br />
{{Related|KDevelop}}<br />
{{Related|Trinity}}<br />
{{Related|Uniform Look for Qt and GTK Applications}}<br />
{{Related articles end}}<br />
<br />
KDE is a software project currently comprising of a [[desktop environment]] known as Plasma (or Plasma Workspaces), a collection of libraries and frameworks (KDE Frameworks) and several applications (KDE Applications) as well. KDE upstream has a well maintained [http://userbase.kde.org/ UserBase wiki]. Detailed information about most KDE applications can be found there.<br />
<br />
== Installation ==<br />
<br />
=== Plasma Desktop ===<br />
<br />
{{Note|<br />
*Plasma 5 is not co-installable with Plasma 4.<br />
*The Plasma 4 desktop is unmaintained since August 2015.[https://www.kde.org/announcements/announce-applications-15.08.0.php] It is no longer in the official repositories since December 2015.[https://www.archlinux.org/news/dropping-plasma-4/]<br />
* [[KDM]] is no longer available for Plasma 5. KDE upstream [http://blog.davidedmundson.co.uk/blog/display_managers_finale recommends] using the [[SDDM]] display manager as it provides integration with the Plasma 5 theme.}}<br />
<br />
Before installing Plasma, make sure you have a working [[Xorg]] installation on your system.<br />
<br />
Install the {{Pkg|plasma-meta}} meta-package or the {{Grp|plasma}} group. For differences between {{Pkg|plasma-meta}} and {{Grp|plasma}} reference [[Creating packages#Meta packages and groups]]. Alternatively, for a more minimal Plasma installation, install the {{Pkg|plasma-desktop}} package.<br />
<br />
=== Upgrading from Plasma 4 to 5 ===<br />
<br />
# Isolate {{ic|multi-user.target}}:{{bc|# systemctl isolate multi-user.target}}<br />
# If you use KDM as display manager, [[disable]] the {{ic|kdm.service}} systemd unit. <br />
# [[Install|Uninstall]] the {{AUR|kdebase-workspace}} package.<br />
# [[Install]] the {{pkg|plasma-meta}} package or the {{grp|plasma}} group.<br />
# [[Enable]] the {{ic|sddm.service}} systemd unit, or install and enable any other [[display manager]].<br />
# Reboot or simply [[start]] the systemd {{ic|sddm.service}} unit.<br />
<br />
{{Note|The Plasma 4 configuration is not automatically migrated to Plasma 5, so you will have to configure your desktop from scratch.}}<br />
<br />
=== KDE applications and language packs ===<br />
<br />
To install the full set of KDE Applications, install the {{Grp|kde-applications}} group or the {{Pkg|kde-applications-meta}} meta-package. Note that this will only install applications, it will not install any version of the Plasma Desktop.<br />
<br />
If you need language files, install {{ic|kde-l10n-'''yourlanguagehere'''}} (e.g. {{Pkg|kde-l10n-de}} for the German language). For a full list of available languages see [https://www.archlinux.org/packages/extra/any/kde-l10n/ this link].<br />
<br />
== Starting Plasma ==<br />
<br />
{{Tip|To better integrate SDDM with Plasma, it is recommended to edit {{ic|/etc/sddm.conf}} to use the breeze theme. Refer to [[SDDM#Theme settings]] for instructions.}}<br />
<br />
To launch a Plasma 5 session, choose ''Plasma'' in your [[display manager]] menu.<br />
<br />
Alternatively, to start Plasma with ''startx'', append {{ic|exec startkde}} to your {{ic|.xinitrc}} file. If you want to start Xorg at login, please see [[Start X at login]].<br />
<br />
=== Wayland ===<br />
<br />
As of Plasma 5.8, Plasma on [[Wayland]] should be usable, although there are a [https://community.kde.org/Plasma/5.8_Errata#Wayland few known problems].<br />
<br />
* To start a Plasma on Wayland session from a display manager, install the {{Pkg|plasma-wayland-session}} package and ''Plasma'' should show up in the display manager.<br />
* To start a Plasma on Wayland session from a console, run {{ic|startplasmacompositor}}.<br />
<br />
== Configuration ==<br />
<br />
Most settings for KDE applications are stored in {{ic|~/.config}}, but some older applications may use {{ic|~/.kde4}}. However, configuring KDE is primarily done through the '''System Settings''' application. It can be started from a terminal by executing ''systemsettings5''.<br />
<br />
Frameworks 5 applications can use KDE 4 configuration however they expect the configuration files to be located in different places. To allow Frameworks 5 applications running in KDE 4 to share the same configurations they may be moved to the new locations and symlinked back to the old. Examples are:<br />
*Konsole profiles from {{ic|~/.kde4/share/apps/konsole}} to {{ic|~/.local/share/konsole/}}<br />
*Application appearance from {{ic|~/.kde4/share/config/kdeglobals}} to {{ic|~/.config/kdeglobals}} <br />
<br />
=== Personalization ===<br />
<br />
==== Plasma desktop ====<br />
<br />
===== Themes =====<br />
<br />
{{Note|1=If the Plasma cursor theme is incorrect in some instances, see the following [https://bbs.archlinux.org/viewtopic.php?pid=1533071#p1533071 forum post] for a workaround.}}<br />
[http://kde-look.org/index.php?xcontentmode=76 Plasma themes] define the look of panels and plasmoids. For easy system-wide installation, some such themes are available in both the official repositories and the [https://aur.archlinux.org/packages.php?O=0&K=plasmatheme&do_Search=Go AUR].<br />
<br />
The easiest way to install themes is by going through the Desktop Settings control panel:<br />
<br />
Workspace Theme > Desktop Theme > Get new Themes<br />
<br />
This will present a nice frontend for [http://www.kde-look.org/ kde-look.org] that allows you to install, uninstall, or update third-party plasmoid scripts with literally just one click.<br />
<br />
Splash and Lock screens are currently unavailable so to customize these screens you have to modify the original theme found in {{ic|/usr/share/plasma/look-and-feel/}}.<br />
See [https://www.kubuntuforums.net/showthread.php?67599-Plasma-5-background-images&s=59832dc20e5bfc2948dbb591d8453f61 this thread] on the Kubuntu forums.<br />
<br />
Note that the [[SDDM]] login screen is not part of this theme.<br />
<br />
====== Qt and GTK+ Applications Appearance ======<br />
<br />
{{Tip|For Qt and GTK theme consistency, see [[Uniform look for Qt and GTK applications]].}}<br />
<br />
;Qt4<br />
For Qt4 applications to have a consistent appearance, there are two options: <br />
Install {{Pkg|breeze-kde4}} and then pick Breeze as GUI Style in {{ic|qtconfig-qt4}}; or install {{Pkg|breeze-gtk}} and pick GTK+ as GUI Style.<br />
<br />
;GTK+<br />
The recommended theme for a pleasant appearance in GTK+ applications is {{Pkg|breeze-gtk}} or {{AUR|gnome-breeze-git}}, a GTK+ theme designed to mimic the appearance of Plasma 5 Breeze.<br />
Install {{Pkg|kde-gtk-config}} and select the installed GTK-theme for GTK2/GTK3-Theme in ''System Settings > Application Style > GNOME Application Style''.<br />
<br />
In some themes, tooltips in GTK+ applications have white text on white backgrounds making it difficult to read. To change the colors in GTK2 applications, find the section for tooltips in the gtkrc file and change it. For GTK3 application two files need to be changed, gtk.css and settings.ini.<br />
<br />
===== Widgets =====<br />
<br />
Plasmoids are little scripted (plasmoid scripts) or coded (plasmoid binaries) KDE applications designed to enhance the functionality of your desktop.<br />
<br />
The easiest way to install plasmoid scripts is by right-clicking onto a panel or the desktop and choosing ''Add Widgets > Get new Widgets > Download Widgets''.<br />
This will present a nice frontend for [http://www.kde-look.org/ kde-look.org] that allows you to install, uninstall, or update third-party plasmoid scripts with literally just one click.<br />
<br />
Many Plasmoid binaries are [https://aur.archlinux.org/packages.php?O=0&K=plasmoid&do_Search=Go&PP=25&SO=d&SB=v available from the AUR].<br />
<br />
===== Sound applet in the system tray =====<br />
<br />
[[Install]] {{Pkg|plasma-pa}} or {{Pkg|kmix}} (start Kmix from the Application Launcher).<br />
<br />
{{Note|1=To adjust the [https://bugs.kde.org/show_bug.cgi?id=313579#c28 step size of volume increments/decrements], add e.g. {{ic|1=VolumePercentageStep=1}} in the {{ic|[Global]}} section of {{ic|~/.kde4/share/config/kmixrc}}}}<br />
<br />
===== Disable panel shadow =====<br />
<br />
As the plasma panel is on top of other windows, its shadow is drawn over them. [https://bbs.archlinux.org/viewtopic.php?pid=1228394#p1228394] To disable this behaviour without impacting other shadows, [[install]] {{Pkg|xorg-xprop}} and run:<br />
<br />
$ xprop -remove _KDE_NET_WM_SHADOW<br />
<br />
then select the panel with the plus-sized cursor. [https://forum.kde.org/viewtopic.php?f=285&t=121592] For automation, install {{Pkg|xorg-xwininfo}} and create the following script:<br />
<br />
{{hc|/usr/local/bin/kde-no-shadow|<nowiki><br />
#!/bin/bash<br />
for WID in $(xwininfo -root -tree | sed '/"Plasma": ("plasmashell" "plasmashell")/!d; s/^ *\([^ ]*\) .*/\1/g'); do<br />
xprop -id $WID -remove _KDE_NET_WM_SHADOW<br />
done<br />
</nowiki>}}<br />
<br />
The script can be run on login with ''Add Script'' in ''Autostart'':<br />
<br />
$ kcmshell5 autostart<br />
<br />
==== Window decorations ====<br />
<br />
[http://kde-look.org/index.php?xcontentmode=75 Window decorations] can be changed in ''System Settings > Workspace Appearance > Window Decorations''.<br />
<br />
There you can also directly download and install more themes with one click, and some are available in the [https://aur.archlinux.org/packages.php?O=0&K=kdestyle&do_Search=Go&PP=25&SO=d&SB=v AUR].<br />
<br />
==== Icon themes ====<br />
<br />
Icon themes can be installed and changed on ''System Settings > Icons''.<br />
{{note|Although all modern Linux desktops share the same icon theme format, desktops like [[GNOME]] use fewer icons (esp. in menus and toolbars). Themes developed for such desktops usually lack icons required by Plasma 5 and KDE apps.<br/><br />
It is recommended to install Plasma compatible icon themes instead.}}<br />
<br />
==== Fonts ====<br />
<br />
===== Fonts in a Plasma session look poor =====<br />
<br />
Try installing the {{Pkg|ttf-dejavu}} and {{Pkg|ttf-liberation}} packages.<br />
<br />
After the installation, be sure to log out and back in. You should not have to modify anything in ''System Settings > Fonts''.<br />
<br />
If you have personally set up how your [[Fonts]] render, be aware that System Settings may alter their appearance. When you go ''System Settings > Appearance > Fonts'' System Settings will likely alter your font configuration file ({{ic|fonts.conf}}).<br />
<br />
There is no way to prevent this, but, if you set the values to match your {{ic|fonts.conf}} file, the expected font rendering will return (it will require you to restart your application or in a few cases restart your desktop). Note that Gnome's Font Preferences also does this.<br />
<br />
===== Fonts are huge or seem disproportional =====<br />
<br />
Try to force font DPI to '''96''' in ''System Settings > Application Appearance > Fonts''.<br />
<br />
If that does not work, try setting the DPI directly in your Xorg configuration as documented [[Xorg#Setting_DPI_manually|here]].<br />
<br />
==== Space efficiency ====<br />
<br />
The Plasma Netbook shell has been dropped from Plasma 5, see the following [https://forum.kde.org/viewtopic.php?f=289&t=126631&p=335947&hilit=plasma+netbook#p335899 KDE forum post]<br />
However, you can achieve something similar by editing the file {{ic|~/.config/kwinrc}} adding <br />
{{ic|1=BorderlessMaximizedWindows=true}} in the {{ic|[Windows]}} section.<br />
<br />
=== Printing ===<br />
<br />
{{Tip|Use the [[CUPS]] web interface for faster configuration. Printers configured in this way can be used in KDE applications. }}<br />
<br />
You can also configure printers in ''System Settings > Printer Configuration''. To use this method, you must first install {{Pkg|print-manager}} and {{Pkg|cups}}.<br />
<br />
The {{ic|avahi-daemon.service}} and {{ic|org.cups.cupsd.service}} daemons must be started first; otherwise, you will get the following error:<br />
The service 'Printer Configuration' does not provide an interface 'KCModule'<br />
with keyword 'system-config- printer-kde/system-config-printer-kde.py'<br />
The factory does not support creating components of the specified type.<br />
<br />
If you are getting the following error, you need to give your user the right to manage printers.<br />
There was an error during CUPS operation: 'cups-authorization-canceled'<br />
<br />
For CUPS, this is set in {{ic|/etc/cups/cups-files.conf}}.<br />
<br />
Adding {{ic|lpadmin}} to {{ic|/etc/group}} and then to the {{ic|SystemGroup}} directive in {{ic|/etc/cups/cups-files.conf}} allows anyone in the {{ic|lpadmin}} group to configure printers. Do ''not'' add the {{ic|lp}} group to the {{ic|SystemGroup}} directive, or printing will fail.<br />
<br />
# groupadd -g107 lpadmin<br />
<br />
{{hc|/etc/cups/cups-files.conf|# Administrator user group...<br />
SystemGroup sys root lpadmin}}<br />
<br />
{{Tip|Read [[CUPS#Configuration]] to get more details on how to configure CUPS.}}<br />
<br />
=== Samba/Windows support ===<br />
<br />
If you want to have access to Windows services, install [[Samba]] (package {{Pkg|samba}}).<br />
<br />
The Dolphin share functionality requires the package {{Pkg|kdenetwork-filesharing}} and usershares, which the stock smb.conf does not have enabled. Instructions to add them are in [[Samba#Creating usershare path]], after which sharing in Dolphin should work out of the box after restarting Samba.<br />
<br />
=== KDE Desktop activities ===<br />
<br />
KDE Desktop Activities are Plasma-based virtual-desktop-like sets of Plasma Widgets where you can independently configure widgets as if you have more than one screen or desktop.<br />
<br />
On your desktop, click the Cashew Plasmoid and, on the pop-up window, press "Activities".<br />
<br />
A plasma bar presenting you the current existing Plasma Desktop Activities will appear at the bottom of the screen. You can navigate between them by pressing the correspondent icons.<br />
<br />
=== Power saving ===<br />
<br />
Plasma has an integrated power saving service called "'''Powerdevil Power Management'''" that may adjust the power saving profile of the system and/or the brightness of the screen (if supported).<br />
<br />
{{Accuracy|Regarding the note below, it might be that the problem is the logind setting ''LidSwitchIgnoreInhibited'' which defaults to ''yes''. [https://bbs.archlinux.org/viewtopic.php?pid&#61;1649022#p1649022]}}<br />
<br />
{{Note|Powerdevil may not [[Power management#Power managers|inhibit]] all logind settings (such as the lid close action for laptops). In these cases, the logind setting itself will need to be changed - see [[Power management#Power management with systemd]].}}<br />
<br />
=== Monitoring changes on local files and directories ===<br />
<br />
KDE now uses '''inotify''' directly from the kernel with '''kdirwatch''' (included in kdelibs), so Gamin or FAM are no longer needed. You may want to install this {{AUR|kdirwatch}}{{Broken package link|{{aur-mirror|kdirwatch}}}} from AUR which is a GUI frontend for kdirwatch.<br />
<br />
=== Autostarting applications ===<br />
<br />
Plasma can autostart applications and run scripts on startup and shutdown. To autostart an application, start {{ic|systemsettings}} and navigate to ''Startup and Shutdown'' -> ''Autostart'' and add the program or shell script of your choice. For applications, a {{ic|.desktop}} file will be created, for shell scripts, a symlink will be created.<br />
{{Note|<br />
* Programs can be autostarted on login only, whilst shell scripts can also be run on shutdown or even before Plasma itself starts.<br />
* Shell scripts will only be run if they are marked executable.<br />
}}<br />
<br />
Place [[Desktop entries]] (i.e. {{ic|.desktop}} files) here:<br />
;{{ic|~/.config/autostart}}:for starting applications at login.<br />
<br />
Place or symlink shell scripts in one of the following directories:<br />
;{{ic|~/.config/plasma-workspace/env}}:for executing scripts at login before launching Plasma.<br />
;{{ic|~/.config/autostart-scripts}}:for executing scripts at login.<br />
;{{ic|~/.config/plasma-workspace/shutdown}}:for executing scripts on shutdown.<br />
<br />
== System administration ==<br />
<br />
=== Terminate Xorg server through KDE System Settings ===<br />
<br />
Navigate to the submenu ''System Settings > Input Devices > Keyboard > Advanced (tab) > "Key Sequence to kill the X server"'' and ensure that the checkbox is ticked.<br />
<br />
=== KCM ===<br />
<br />
KCM stands for '''KC'''onfig '''M'''odule. KCMs can help you configure your system by providing interfaces in System Settings, or through the command line with ''kcmshell5''.<br />
<br />
'''Configuration for look and feel of GTK applications.'''<br />
* {{Pkg|kde-gtk-config}}<br />
* {{AUR|kcm-gtk}}{{Broken package link|{{aur-mirror|kcm-gtk}}}}<br />
* {{AUR|kcm-qt-graphicssystem}}<br />
<br />
'''Configuration for the GRUB bootloader.'''<br />
* {{AUR|grub2-editor}}{{Broken package link|{{aur-mirror|grub2-editor}}}}<br />
<br />
'''Configuration for the [[Uncomplicated Firewall]] (UFW)'''<br />
* {{AUR|kcm-ufw}}<br />
<br />
'''Configuration for [[PolicyKit]]'''<br />
* {{AUR|kcm-polkit-kde-git}}<br />
<br />
'''Configuration for Wacom tablets'''<br />
* {{AUR|kcm-wacomtablet}}<br />
<br />
'''Configuration for systemd'''<br />
* {{Pkg|systemd-kcm}}<br />
<br />
More KCMs can be found at [http://kde-apps.org/index.php?xcontentmode=273 kde-apps.org].<br />
<br />
== Desktop search ==<br />
<br />
KDE implements desktop search with a software called Baloo, a file indexing and searching solution.<br />
<br />
=== Baloo ===<br />
<br />
==== Using and configuring Baloo ====<br />
<br />
In order to search using Baloo on the KDE Plasma Desktop, press {{ic|ALT+F2}} and type in your query. Within Dolphin press {{ic|CTRL+F}}.<br />
<br />
By default the Desktop Search KCM exposes only two options: A panel to blacklist folders and a way to disable it with one click.<br />
<br />
Alternatively you can edit your {{ic|~/.config/baloofilerc}} file ([https://community.kde.org/Baloo/Configuration info]). Additionally the {{ic|balooctl}} process can also be used. In order to disable Baloo run {{ic|balooctl disable}}.<br />
<br />
Once you added additional folders to the blacklist or disabled Baloo entirely, a process named {{ic|baloo_file_cleaner}} removes all unneeded index files automatically. They are stored under {{ic|~/.local/share/baloo/}}.<br />
<br />
More advanced configuration options are available through {{AUR|kcm_baloo_advanced}}{{Broken package link|{{aur-mirror|kcm_baloo_advanced}}}}.<br />
<br />
==== How do I index a removable device? ====<br />
<br />
By default every removable device is blacklisted. You just have to remove your device from the blacklist in the KCM panel.<br />
<br />
=== Web browsers ===<br />
==== Konqueror and Rekonq ====<br />
Konqueror supports two rendering engines – KHTML and QtWebKit (via the {{Pkg|kwebkitpart}} package) – Rekonq supports only QtWebKit. KHTML development was halted after Qt shipped WebKit but was kept for compatibility reasons. QtWebKit, in turn, has since been [https://www.mail-archive.com/development@qt-project.org/msg18866.html deprecated] by the Qt Project and replaced by [[Chromium]]-based Qt WebEngine which is currently not supported by either Konqueror or Rekonq. There is a [http://qtwebkit.blogspot.com/2016/08/qtwebkit-im-back.html community continuation] of QtWebKit.<br />
<br />
A successor named Fiber is currently in development, which will use Chromium's engine.<br />
<br />
==== Chromium and Chrome ====<br />
[[Chromium]] and its proprietary variant Google Chrome have limited Plasma integration. [[KDE_Wallet#KDE_Wallet_for_Chrome_and_Chromium|They can use KWallet]] and KDE Open/Save windows.<br />
<br />
==== Firefox ====<br />
Firefox can be configured to better integrate with Plasma. See [[Firefox#KDE_integration|Firefox KDE integration]] for details.<br />
<br />
==== Qupzilla ====<br />
Qupzilla ({{Pkg|qupzilla}}) is a Qt web browser with Plasma integration features. Qupzilla 2.0 uses Qt WebEngine intead of WebKit. The WebKit variant is also available as {{aur|qupzilla-qtwebkit-git}}.<br />
<br />
== PIM ==<br />
<br />
KDE offers its own stack for personal information management. This includes emails, contacts, calendar, etc.<br />
<br />
=== Akonadi ===<br />
<br />
Akonadi is a system meant to act as a local cache for PIM data, regardless of its origin, which can be then used by other applications. This includes the user's emails, contacts, calendars, events, journals, alarms, notes, and so on.<br />
<br />
Akonadi does not store any data by itself: the storage format depends on the nature of the data (for example, contacts may be stored in vCard format).<br />
<br />
==== Installation ====<br />
<br />
Install {{Pkg|akonadi}}. For additional addons, install {{Pkg|kdepim-addons}}. For EWS support, install {{AUR|akonadi-ews-git}}.<br />
<br />
{{Note|If you wish to use a database engine other than MariaDB/MySQL, then when installing the {{Pkg|akonadi}} package, use the following command to skip installing the {{Pkg|mariadb}} dependencies:<br />
<pre><br />
pacman -S akonadi --assume-installed mariadb<br />
</pre>}}<br />
<br />
==== Disabling Akonadi ====<br />
<br />
See this [http://userbase.kde.org/Akonadi#Disabling_the_Akonadi_subsystem section in the KDE userbase].<br />
<br />
==== Database configuration ====<br />
<br />
===== MariaDB/MySQL =====<br />
<br />
====== Using ZFS ======<br />
<br />
If your home directory is on a ZFS pool, you will need to create {{ic|~/.config/akonadi/mysql-local.conf}} with the following contents:<br />
<br />
[mysqld]<br />
innodb_use_native_aio = 0<br />
<br />
Otherwise you will get the [[MySQL#OS error 22 when running on ZFS|OS error 22]]<br />
<br />
===== PostgreSQL =====<br />
<br />
<ol><br />
<li> Install and setup PostgreSQL (see [[PostgreSQL]])<br />
<ul><li> Enable the {{ic|postgresql}} [[systemd]] service: {{ic|systemctl enable postgresql.service}}.</li></ul></li><br />
<li>Create the {{ic|~/.config/akonadi/akonadiserverrc}} file if it does not exist.</li><br />
<li>Edit {{ic|~/.config/akonadi/akonadiserverrc}} file so that it has the following contents:<br />
<pre><br />
[General]<br />
Driver=QPSQL<br />
<br />
[QPSQL]<br />
Host=/run/postgresql/<br />
InitDbPath=/usr/bin/initdb<br />
Name=akonadi<br />
Options=<br />
Password=<br />
Port=5432<br />
ServerPath=/usr/bin/pg_ctl<br />
StartServer=true<br />
User=postgres<br />
</pre><br />
{{Note|If your PostgreSQL database username, password, and port differ from {{ic|postgres}}, {{ic|}} (nothing), and {{ic|5432}}, then make sure you respectively change the configuration options, {{ic|1=User=}}, {{ic|1=Password=}}, and {{ic|1=Port=}}.}}</li><br />
<li>Start Akonadi: {{ic|akonadictl start}}, and check its status: {{ic|akonadictl status}}.</li><br />
</ol><br />
<br />
===== SQLite =====<br />
Edit {{ic|~/.config/akonadi/akonadiserverrc}} to match the configuration below:<br />
<br />
[General]<br />
Driver=QSQLITE3<br />
<br />
[QSQLITE3]<br />
Name=/home/username/.local/akonadi/akonadi.db<br />
<br />
== Phonon ==<br />
<br />
From [[Wikipedia:Phonon (software)|Wikipedia]]:<br />
<br />
:''“Phonon is the multimedia API provided by KDE and is the standard abstraction for handling multimedia streams within KDE software and also used by several Qt applications.<br />
<br />
Phonon was originally created to allow KDE and Qt software to be independent of any single multimedia framework such as GStreamer or xine and to provide a stable API for a major version's lifetime.”''<br />
<br />
'''Phonon''' is being widely used within KDE, for both audio (e.g., the System notifications or KDE audio apps) and video (e.g., the Dolphin video thumbnails).<br />
<br />
=== Which backend should I choose? ===<br />
You can choose between backends based on [[GStreamer]] and [[VLC]] – each available in versions for Qt4 applications and Qt5 applications ({{Pkg|phonon-qt4-gstreamer}}, {{Pkg|phonon-qt5-gstreamer}} – {{Pkg|phonon-qt4-vlc}}, {{Pkg|phonon-qt5-vlc}}).<br />
<br />
[https://www.phoronix.com/scan.php?page=news_item&px=MTUwNDM Upstream prefers VLC] but prominent Linux distributions (Kubuntu and Fedora-KDE for example) prefer GStreamer because that allows them to easily leave out patented MPEG codecs from the default installation. Both backends have a slightly different [http://community.kde.org/Phonon/FeatureMatrix features set].<br />
<br />
In the past other backends were developed as well but are no longer maintained and their AUR packages have been deleted.<br />
<br />
{{Note|1=<br><br />
* Multiple backends can be installed at once and prioritized at ''System Settings > Multimedia > Phonon > Backend''. For Plasma 5 this would be ''System Settings > Multimedia > Backend''.<br />
* According to the [https://forum.kde.org/viewtopic.php?f=250&t=126476&p=335080 KDE forums], the VLC backend lacks support for [[wikipedia:ReplayGain|ReplayGain]].}}<br />
{{Note|1=<br><br />
* If you choose the vlc backend, you may experience crashes every time kde wants to send you a audible warning (and in quite a number of other cases as well, see [https://forum.kde.org/viewtopic.php?f=289&t=135956])<br />
* A possible fix is to run<br />
{{bc|# /usr/lib/vlc/vlc-cache-gen -f /usr/lib/vlc/plugins}}<br />
}}<br />
<br />
== Useful applications ==<br />
<br />
The official set of KDE applications may be found [http://www.kde.org/applications/ here].<br />
<br />
=== Yakuake ===<br />
<br />
[[Yakuake]] provides a Quake-like terminal emulator whose visibility is toggled by the F12 key. It also has support for multiple tabs. Yakuake is available in the package {{Pkg|yakuake}}.<br />
<br />
=== KDE Telepathy ===<br />
<br />
[http://community.kde.org/KTp KDE Telepathy] is a project with the goal to closely integrate Instant Messaging with the KDE desktop. It utilizes the Telepathy framework as a backend and is intended to replace Kopete.<br />
<br />
To install all Telepathy protocols, install the {{Grp|telepathy}} group.<br />
To use the KDE Telepathy client, install the {{Pkg|telepathy-kde-meta}} package that includes all the packages contained in the {{Grp|telepathy-kde}} group.<br />
<br />
==== Use Telegram with KDE Telepathy ====<br />
<br />
Telegram protocol is available using {{pkg|telepathy-haze}}, installing {{aur|telegram-purple}} or {{aur|telegram-purple-git}} and {{aur|telepathy-morse-git}}. The username is the Telegram account telephone number (complete with the national prefix '+xx', e.g. '+49' for Germany). The configuration through the GUI may be tricky: if the phone number is not accepted when configuring a new account in the KDE Telepathy client (with an error message complaining about an invalid parameter which prevents the account creation), insert it between single quotes and then remove the quotes manually from the configuration file ({{ic|~/.local/share/telepathy/mission-control/accounts.cfg}}) after the account creation (if the quotes are not removed after, an authentication error should rise). Note that the configuration file should be edited manually when KDE Telepathy is not running, e.g. when there is no KDE desktop session active, otherwise manual changes may be overwritten by the software.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Using an alternative window manager ===<br />
There may be reasons you want to use another window manager than KWin, for example to work around the DRI bug that causes [[PRIME#Black_screen_with_GL-based_compositors|black screen with PRIME]].<br />
<br />
To use an alternative [[window manager]] with Plasma open the ''System Settings'' panel, navigate to ''(Default) Applications > Window Manager > Use a different window manager'' and select the window manager you wish to use from the list.<br />
<br />
==== KDE/Openbox session ====<br />
<br />
The {{Pkg|openbox}} package provides a session for using KDE with [[Openbox]]. To make use of this session, select ''KDE/Openbox'' from the [[display manager]] menu.<br />
<br />
For those starting the session manually, add the following line to your {{ic|.xinitrc}} file:<br />
exec openbox-kde-session<br />
<br />
==== Compiz custom ====<br />
<br />
If you need to run Compiz with custom options and switches select ''Compiz custom'' and then create a script called {{ic|compiz-kde-launcher}} and add to it the commands you wish to use to start Compiz. See the example below:<br />
<br />
{{hc|/usr/local/bin/compiz-kde-launcher|<nowiki><br />
#!/bin/bash<br />
LIBGL_ALWAYS_INDIRECT=1<br />
compiz --replace &<br />
wait<br />
</nowiki>}}<br />
<br />
Then make it executable:<br />
$ chmod +x /usr/local/bin/compiz-kde-launcher<br />
<br />
==== Re-enabling compositing effects ====<br />
<br />
When replacing Kwin with a window manager which does not provide a Compositor (such as Openbox), any desktop compositing effects e.g. transparency will be lost. In this case, install and run a separate Composite manager to provide the effects such as [[Xcompmgr]] or [[Compton]].<br />
<br />
=== Integrate Android ===<br />
<br />
KDE Connect provides several features for you:<br />
* Share files and URLs to/from KDE from/to any app, without wires.<br />
* Touchpad emulation: Use your phone screen as your computer's touchpad.<br />
* Notifications sync (4.3+): Read your Android notifications from the desktop.<br />
* Shared clipboard: copy and paste between your phone and your computer.<br />
* Multimedia remote control: Use your phone as a remote for Linux media players.<br />
* WiFi connection: no usb wire or bluetooth needed.<br />
* RSA Encryption: your information is safe.<br />
<br />
You will need to install KDE Connect both on your computer and on your Android. For PC side, install {{Pkg|kdeconnect}} package. For Android side, install {{ic|KDE Connect}} from [https://play.google.com/store/apps/details?id=org.kde.kdeconnect_tp Google Play] or from [https://f-droid.org/repository/browse/?fdid=org.kde.kdeconnect_tp F-Droid].<br />
<br />
=== Configure KWin to use OpenGL ES ===<br />
Set environment variable {{ic|KWIN_COMPOSE}} to 'O2ES' to force the OpenGL ES backend. Please note that OpenGL ES is not supported by all drivers.<br />
<br />
=== Speed up application startup ===<br />
<br />
User Rob described a "[http://kdemonkey.blogspot.nl/2008/04/magic-trick.html magic trick]" on his blog to improve application start-up time by 50-150ms.<br />
To enable it, create this folder in your home:<br />
$ mkdir ~/.compose-cache/<br />
It can produce freezes under heavy io. To avoid this, also do:<br />
$ ln -sfv /run/user/$UID/ /home/$USER/.compose-cache<br />
<br />
{{Note|For those curious about what is going on here, this enables an optimization which Lubos (of general KDE speediness fame) came up with some time ago and was then rewritten and integrated into libx11. Ordinarily, on startup, applications read input method information from {{ic|/usr/share/X11/locale/''your locale''/Compose}}. This file is quite long (>5000 lines for the en_US.UTF-8 one) and takes some time to process. libX11 can create a cache of the parsed information which is much quicker to read subsequently, but it will only re-use an existing cache or create a new one in {{ic|~/.compose-cache}} if the directory already exists.}}<br />
<br />
=== Configuring monitor resolution / multiple monitors ===<br />
<br />
To enable display resolution management and multiple monitors in Plasma 5, install {{Pkg|kscreen}}. This adds the additional options to System Settings/Display and Monitor.<br />
<br />
=== Open application launcher with Super key (Windows key) ===<br />
<br />
{{Note|Since plasma 5.8 release, this workaround is no longer needed. Pressing {{Ic|super}} key launches kickstart application launcher as if {{Ic|alt+F1}} keys are pressed.}}<br />
<br />
Install and start {{Pkg|ksuperkey}}. Now assign Alt + F1 as hot key. The Super Key will now open the application launcher. You can add ksuperkey to the autostart if you don't want to start it manually.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Configuration related ===<br />
<br />
Many problems in KDE are related to configuration.<br />
<br />
==== Plasma desktop behaves strangely ====<br />
<br />
Plasma problems are usually caused by unstable '''Plasma widgets''' (colloquially called ''plasmoids'') or '''Plasma themes'''. First, find which was the last widget or theme you had installed and disable it or uninstall it.<br />
<br />
So, if your desktop suddenly exhibits "locking up", this is likely caused by a faulty installed widget. If you cannot remember which widget you installed before the problem began (sometimes it can be an irregular problem), try to track it down by removing each widget until the problem ceases. Then you can uninstall the widget, and file a bug report (bugs.kde.org) '''only if it is an official widget'''. If it is not, it is recommended you find the entry on kde-look.org and inform the developer of that widget about the problem (detailing steps to reproduce, etc).<br />
<br />
If you cannot find the problem, but you do not want ''all'' the settings to be lost, navigate to {{ic|~/.config}}:<br />
<br />
$ for j in plasma*; do mv -- "$j" "${j%}.bak"; done<br />
<br />
This command will '''rename all Plasma related configs''' to *.bak (e.g. {{ic|plasmarc.bak}}) of your user and when you will relogin into Plasma, you will have the '''default''' settings back. To undo that action, remove the .bak file extension. If you already have *.bak files, rename, move, or delete them first. It is highly recommended that you create regular backups anyway. See [[Synchronization and backup programs]] for a list of possible solutions.<br />
<br />
==== Clean cache to resolve upgrade problems ====<br />
<br />
The [https://bbs.archlinux.org/viewtopic.php?id=135301 problem] may be caused by old cache. Sometimes after an upgrade, the old cache might introduce strange, hard to debug behaviour such as unkillable shells, hangs when changing various settings and several other problems such as ark being unable to unrar or unzip or amarok not recognizing any of your music. This solution can also resolve problems with KDE and Qt programmes looking bad following upgrade.<br />
<br />
Rebuild your cache with the following commands:<br />
<br />
$ rm ~/.config/Trolltech.conf<br />
$ kbuildsycoca4 --noincremental<br />
<br />
Hopefully, your problems are now fixed.<br />
<br />
=== Clean akonadi configuration to fix KMail ===<br />
<br />
First, make sure that KMail is not running. Then backup configuration:<br />
$ mv ~/.local/share/akonadi ~/.local/share/akonadi-old<br />
$ mv ~/.config/akonadi ~/.config/akonadi-old<br />
<br />
Start ''SystemSettings > Personal'' and remove all the resources. Go back to Dolphin and remove the original {{ic|~/.local/share/akonadi}} and<br />
{{ic|~/.config/akonadi}} - the copies you made ensure that you can back-track if necessary.<br />
<br />
Now go back to the System Settings page and carefully add the necessary resources. You should see the resource reading in your mail folders. Then start Kontact/KMail to see if it work properly.<br />
<br />
=== Fix empty IMAP inbox ===<br />
<br />
For some IMAP accounts, kmail will show the inbox as a container with all other folders of this account inside. Kmail does not show messages in the inbox container but in all other subfolders [https://bugs.kde.org/show_bug.cgi?id=284172]. To solve this problem simply disable the server side subscribition in the kmail account settings.<br />
<br />
=== Getting current state of KWin for support and debug purposes ===<br />
<br />
This command prints out a wonderful summary of the current state of KWin including used options, used compositing backend and relevant OpenGL driver capabilities. See more on [http://blog.martin-graesslin.com/blog/2012/03/on-getting-help-for-kwin-and-helping-kwin/ Martin's blog].<br />
<br />
$ qdbus org.kde.KWin /KWin supportInformation<br />
<br />
=== KDE and Qt programs look bad when in a different window manager ===<br />
<br />
If you are using KDE or Qt programs but not in a full Plasma session (specifically, you did not run {{ic|startkde}}), then as of Plasma 4.6.1 you will need to tell Qt how to find KDE's styles (Oxygen, QtCurve etc.)<br />
<br />
You just need to set the environment variable {{ic|QT_PLUGIN_PATH}}. E.g. put:<br />
<br />
export QT_PLUGIN_PATH=$HOME/.kde4/lib/kde4/plugins/:/usr/lib/kde4/plugins/<br />
<br />
into your {{ic|/etc/profile}} (or {{ic|~/.profile}} if you do not have root access). {{ic|qtconfig-qt4}} should then be able to find your KDE styles and everything should look nice again!<br />
<br />
Alternatively, you can symlink the Qt styles directory to the KDE styles one:<br />
# ln -s /usr/lib/kde4/plugins/styles/ /usr/lib/qt4/pluginlib32-libdbusmenu-glibs/styles<br />
<br />
Under Gnome you can try to install the package libgnomeui.<br />
<br />
=== KF5/Qt5 applications don't display icons in i3/fvwm/awesome ===<br />
<br />
See [[Qt#Configuration of Qt5 apps under environments other than KDE]].<br />
<br />
=== Graphical related problems ===<br />
<br />
==== Plasma keeps crashing with legacy Nvidia ====<br />
<br />
This is caused by a [https://bugs.kde.org/show_bug.cgi?id=348753 bug in Plasma] when using the Nvidia-304xx driver. Rather than disabling compositing, create a file {{ic|kwin.sh}} in {{ic|~/.config/plasma-workspace/env/}} with the following contents:<br />
<br />
#!/bin/sh<br />
export KWIN_EXPLICIT_SYNC=0<br />
<br />
Then go to ''system-settings > Startup and Shutdown > Autostart'' and ''Check/Add'' the script as a pre-KDE startup file.<br />
<br />
==== Applications don't refresh properly ====<br />
<br />
If you use 3D-accelerated composition with [[Intel]], you might find that the Plasma panel and other applications don't refresh properly (stay frozen). Some Intel drivers have [https://bugzilla.redhat.com/show_bug.cgi?id=1259475 problems with EGL]. Go to System Settings under ''Display and Monitor'' -> ''Compositor''. Set ''OpenGL interface'' to OpenGL 3.1. If that does not work, see [[Intel graphics#SNA issues]] for alternative solutions.<br />
<br />
==== Low 2D desktop performance (or) artifacts appear when on 2D ====<br />
<br />
===== GPU driver problem =====<br />
<br />
Make sure you have the proper driver for your card installed, so that your desktop is at least 2D accelerated. Follow these articles for more information: [[ATI]], [[NVIDIA]], [[Intel]] for more information, in order to make sure that everything is all right.<br />
The open-source ATI and Intel drivers and the proprietary (binary) Nvidia driver should theoretically provide the best 2D and 3D acceleration.<br />
<br />
===== The Raster engine workaround =====<br />
{{Accuracy|xrender is not default in plasma 5. XRender should not be recommended anymore.}}<br />
If this does not solve your problems, your driver may not provide a good '''XRender''' acceleration which the current Qt painter engine relies on by default.<br />
<br />
You can change the painter engine to software based only by invoking the application with the {{ic|-graphicssystem raster}} command line. This rendering engine can be set as the default one by recompiling Qt with the same as configure option, {{ic|-graphicssystem raster}}.<br />
<br />
The raster paint engine enables the CPU to do the majority of the painting, as opposed to the GPU. You may get better performance, depending on your system. This is basically a work-around for the terrible Linux driver stack, since the CPU should obviously not be doing graphical computations since it is designed for fewer threads of greater complexity, as opposed to the GPU which is many threads but lesser computational strength. So, only use Raster engine if you are having problems or your GPU is much slower than you CPU, otherwise is better to use XRender.<br />
<br />
Since Qt 4.7+, recompiling Qt is not needed. Simply export {{ic|1=QT_GRAPHICSSYSTEM=raster}}, or {{ic|opengl}}, or {{ic|native}} (for the default). Raster depends on the CPU, OpenGL depends on the GPU and high driver support, and Native is just using the X11 rendering (mixture, usually).<br />
<br />
'''The best and automatic way to do that''' is to install {{AUR|kcm-qt-graphicssystem}} from AUR and configure this particular Qt setting through ''System Settings > Qt Graphics System''.<br />
<br />
For more information, consult this [http://apachelog.wordpress.com/2010/09/05/qt-graphics-system-kcm/ KDE Developer blog entry] and/or this [https://web.archive.org/web/20100430183745/http://labs.trolltech.com/blogs/2009/12/18/qt-graphics-and-performance-the-raster-engine Qt Developer blog entry].<br />
<br />
==== Low 3D desktop performance====<br />
<br />
KDE begins with desktop effects enabled. Older cards may be insufficient for 3D desktop acceleration. You can disable desktop effects in ''System Settings > Desktop Effects'' and you can toggle desktop effects with {{ic|Alt+Shift+F12}}.<br />
<br />
{{Note| You may encounter such problems with 3D desktop performance even when using a more powerful graphics card. Make sure the GPU driver and it's components has been successfully installed.}}<br />
<br />
==== Desktop compositing is disabled on my system with a modern Nvidia GPU ====<br />
<br />
Sometimes, KWin may have settings in its configuration file ({{ic|kwinrc}}) that ''may'' cause a problem on re-activating the 3D desktop {{ic|OpenGL}} compositing. That could be caused randomly (for example, due to a sudden Xorg crash or restart, and it gets corrupted), so, in case that happens, delete your {{ic|~/.kde4/share/config/kwinrc}} file and relogin. The KWin settings will turn to the KDE default ones and the problem should be probably gone.<br />
<br />
==== Flickering in fullscreen when compositing is enabled ====<br />
<br />
As of KDE SC 4.6.0, there is an option in ''Sytem Settings > Desktop Effect > Advanced > Suspend desktop effects for fullscreen windows''. Uncheck it would tell kwin to disable unredirect fullscren.<br />
<br />
==== Display settings lost on reboot (multiple monitors) ====<br />
There is a [https://bugs.kde.org/show_bug.cgi?id=346961 bug] in kscreen that makes it forget dual screen settings after reboot with certain displays.<br />
A possible workaround is to uninstall {{Pkg|kscreen}} and specify your screen setup in a xorg.conf file instead:<br />
* See [[Multihead#RandR]] for using the [[Wikipedia:RandR|RandR]] [[Wikipedia:X Window System|X Window System]] extension.<br />
* For Nouveau you can use the template at [[Nouveau#Dual Head]], just edit it to suit your setup.<br />
* For the proprietary nvidia driver you can use the [[NVIDIA#Using_NVIDIA_Settings|nvidia-settings]] utility as root to write the config file.<br />
<br />
=== Sound problems under KDE ===<br />
<br />
==== ALSA related problems ====<br />
<br />
{{Note|First make sure you have {{Pkg|alsa-lib}} and {{Pkg|alsa-utils}} installed.}}<br />
<br />
===== "Falling back to default" messages when trying to listen to any sound in KDE =====<br />
<br />
When you encounter such messages:<br />
The audio playback device ''name_of_the_sound_device'' does not work.<br />
Falling back to default<br />
Go to ''System Settings > Multimedia > Phonon'' and set the device named {{ic|default}} above all the other devices in each box you see.<br />
<br />
===== MP3 files cannot be played when using the GStreamer Phonon backend =====<br />
<br />
This can be solved by installing the GStreamer libav plugin (package {{Pkg|gst-libav}}). If you still encounter problems, you can try changing the Phonon backend used by installing another such as {{Pkg|phonon-qt4-vlc}} or {{Pkg|phonon-qt5-vlc}}.<br />
Then, make sure the backend is preferred via ''System Settings > Multimedia > Phonon > Backend (tab)''.<br />
<br />
=== Konsole does not save commands' history ===<br />
<br />
By default console command history is saved only when you type 'exit' in console. When you close Konsole with 'x' in the corner it does not happen.<br />
To enable autosaving after every command execution:<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
shopt -s histappend<br />
[[ "${PROMPT_COMMAND}" ]] && PROMPT_COMMAND="$PROMPT_COMMAND;history -a" || PROMPT_COMMAND="history -a"<br />
</nowiki>}}<br />
<br />
=== Inotify folder watch limit ===<br />
<br />
If you get the following error:<br />
<br />
KDE Baloo Filewatch service reached the inotify folder watch limit. File changes may be ignored.<br />
<br />
Then you will need to increase the inotify folder watch limit:<br />
<br />
# echo 10000 > /proc/sys/fs/inotify/max_user_watches<br />
<br />
To make changes permanent, create {{ic|/etc/sysctl.d/90-inotify.conf}} with<br />
<br />
#increase inotify watch limit<br />
fs.inotify.max_user_watches = 10000<br />
<br />
=== Freezes when using Automount on a NFS volume ===<br />
<br />
Using [[Fstab#Automount with systemd]] on a [[NFS]] volume may cause freezes, see [https://bugs.kde.org/show_bug.cgi?id=354137 bug report upstream].<br />
<br />
=== Locale warning when installing packages in Konsole ===<br />
<br />
mandb: can't set the locale; make sure $lc_* and $lang are correct<br />
<br />
By default, Konsole sets $LANG to en_US.US-ASCII. If you haven't generated that locale, then mandb can't use it. In your Konsole profile settings, click "Environment" and then add a line for LANG=en_US.UTF-8 or whatever your locale should be.<br />
<br />
=== Multi-monitor issues ===<br />
<br />
The current release of KDE Plasma has several issues with multi-monitor setups, which can make Plasma unusable. See [https://bugs.kde.org/show_bug.cgi?id=356225 KDE Bug 356225].<br />
<br />
These bugs have been resolved in the upstream/git KDE Plasma builds, which can be installed from {{AUR|plasma-desktop-git}} or {{AUR|plasma-git-meta}} - bear in mind that all packages will conflict with current versions - it is recommended to [[remove]] them first.<br />
<br />
== Unstable releases ==<br />
<br />
See [[Official repositories#kde-unstable]]<br />
<br />
== Bugs ==<br />
<br />
It is preferable that if you find a minor or serious bug, you should visit [https://bugs.archlinux.org the Arch Bug Tracker] or/and [http://bugs.kde.org KDE Bug Tracker] in order to report that. Make sure that you are clear about what you want to report.<br />
<br />
If you have any problem and you write about in on the Arch forums, first make sure that you have '''fully''' updated your system using a good sync mirror (check [https://www.archlinux.de/?page=MirrorStatus here]) or try [[Reflector]].<br />
<br />
== See also ==<br />
<br />
* [http://www.kde.org KDE homepage]<br />
* [https://bugs.kde.org KDE bug tracker]<br />
* [https://projects.kde.org KDE Projects]<br />
* [http://blog.martin-graesslin.com/blog/kategorien/kde/ Martin Graesslin's blog]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=Wayland&diff=452156Wayland2016-09-27T02:53:43Z<p>Alive4ever: /* Window managers and desktop shells */ added maze compositor and grefsen</p>
<hr />
<div>[[Category:X server]]<br />
[[es:Wayland]]<br />
[[fr:Wayland]]<br />
[[ja:Wayland]]<br />
[[ru:Wayland]]<br />
[[zh-CN:Wayland]]<br />
{{Related articles start}}<br />
{{Related|KMS}}<br />
{{Related|Xorg}}<br />
{{Related|Mir}}<br />
{{Related articles end}}<br />
'''Wayland''' is a new windowing protocol for Linux. Utilization of Wayland requires changes to and re-installation of parts of your system's software. For more information on Wayland see its [http://wayland.freedesktop.org/ homepage].<br />
<br />
== Requirements ==<br />
<br />
Currently Wayland will only work on systems utilizing [[KMS]].<br />
<br />
== Installation ==<br />
{{Note|Wayland is most likely installed on your system already, since it is an indirect dependency of {{Pkg|gtk2}} and {{Pkg|gtk3}}.}}<br />
<br />
[[Install]] the {{Pkg|wayland}} package.<br />
<br />
== Usage ==<br />
<br />
As Wayland is only a library, it is useless on its own. To replace X Server, you need a compositor (like [[#Weston]]).<br />
<br />
== Weston ==<br />
<br />
=== Installation ===<br />
<br />
[[Install]] the {{Pkg|weston}} package.<br />
<br />
=== Usage ===<br />
<br />
{| class="wikitable" style="float: right; width: 200px;"<br />
|+ '''''Keyboard Shortcuts''' (super = windows key - can be changed, see weston.ini)'' {{Ic|Ctrl-b}}<br />
!Cmd<br />
!Action<br />
|-<br />
|Ctrl + Alt + Backspace<br />
|Quit Weston<br />
|-<br />
|Super + Scroll (or PageUp/PageDown)<br />
|Zoom in/out of desktop<br />
|-<br />
|Super + Tab<br />
|Switch windows<br />
|-<br />
|Super + LMB<br />
|Move Window<br />
|-<br />
|Super + MMB<br />
|Rotate Window !<br />
|-<br />
|Super + RMB<br />
|Resize Window <br />
|-<br />
|Super + Alt + Scroll<br />
|Change window opacity<br />
|-<br />
|Super + K<br />
|Force Kill Active Window<br />
|-<br />
|Super + KeyUp/KeyDown<br />
|Switch Prev/Next Workspace<br />
|-<br />
|Super + Shift + KeyUp/KeyDown<br />
|Grab Current Window and Switch Workspace<br />
|-<br />
|Super + F'''''n'''''<br />
|Switch to Workspace '''''n'''''<br />
|-<br />
|Super + S<br />
|Take a screenshot<br />
|-<br />
|Super + R<br />
|Record a screencast.<br />
|}<br />
<br />
Now that Wayland and its requirements are installed you should be ready to test it out. <br />
<br />
It is possible to run Weston inside a running X session:<br />
$ weston<br />
<br />
Alternatively, to try to launch Weston natively, switch to a terminal and run:<br />
$ weston-launch<br />
<br />
Then at a TTY within Weston, you can run the demos. To launch a terminal emulator:<br />
$ weston-terminal<br />
<br />
To move flowers around the screen:<br />
$ weston-flower <br />
<br />
To test the frame protocol (runs {{ic|glxgears}}):<br />
$ weston-gears<br />
<br />
To display images:<br />
$ weston-image image1.jpg image2.jpg...<br />
<br />
=== Configuration ===<br />
Example configuration file for keyboard layout, module selection and UI modifications. See {{ic|man weston.ini}} for full details:<br />
<br />
{{hc|~/.config/weston.ini|<nowiki><br />
[core]<br />
# xwayland support<br />
modules=xwayland.so<br />
<br />
<br />
[libinput]<br />
enable_tap=true<br />
<br />
<br />
[shell]<br />
background-image=/usr/share/backgrounds/gnome/Aqua.jpg<br />
background-color=0xff002244<br />
panel-color=0x90ff0000<br />
locking=true<br />
animation=zoom<br />
close-animation=fade<br />
focus-animation=dim-layer<br />
#binding-modifier=ctrl<br />
#num-workspaces=6<br />
### for cursor themes install xcursor-themes pkg from Extra. ###<br />
#cursor-theme=whiteglass<br />
#cursor-size=24<br />
<br />
### tablet options ###<br />
#lockscreen-icon=/usr/share/icons/gnome/256x256/actions/lock.png<br />
#lockscreen=/usr/share/backgrounds/gnome/Garden.jpg<br />
#homescreen=/usr/share/backgrounds/gnome/Blinds.jpg<br />
#animation=fade<br />
<br />
<br />
### for Laptop displays ###<br />
#[output]<br />
#name=LVDS1<br />
#mode=1680x1050<br />
#transform=90<br />
<br />
#[output]<br />
#name=VGA1<br />
# The following sets the mode with a modeline, you can get modelines for your preffered resolutions using the cvt utility<br />
#mode=173.00 1920 2048 2248 2576 1080 1083 1088 1120 -hsync +vsync<br />
#transform=flipped<br />
<br />
#[output]<br />
#name=X1<br />
#mode=1024x768<br />
#transform=flipped-270<br />
<br />
<br />
[input-method]<br />
#path=/usr/lib/weston/weston-keyboard<br />
<br />
<br />
[keyboard]<br />
keymap_rules=evdev<br />
#keymap_layout=gb,de<br />
#keymap_options=caps:ctrl_modifier,shift:both_capslock_cancel<br />
### keymap_options from /usr/share/X11/xkb/rules/base.lst ###<br />
numlock-on=true<br />
<br />
[terminal]<br />
#font=DroidSansMono<br />
#font-size=14<br />
<br />
<br />
[launcher]<br />
icon=/usr/share/icons/gnome/24x24/apps/utilities-terminal.png<br />
path=/usr/bin/weston-terminal<br />
<br />
[launcher]<br />
icon=/usr/share/icons/gnome/24x24/apps/utilities-terminal.png<br />
path=/usr/bin/gnome-terminal<br />
<br />
[launcher]<br />
icon=/usr/share/icons/hicolor/24x24/apps/firefox.png<br />
path=/usr/bin/firefox<br />
<br />
[launcher]<br />
icon=/usr/share/weston/icon_flower.png<br />
path=/usr/bin/weston-flower<br />
<br />
[screensaver]<br />
# Uncomment path to disable screensaver<br />
path=/usr/libexec/weston-screensaver<br />
duration=600<br />
</nowiki><br />
}}<br />
<br />
<br />
Minimal {{ic|weston.ini}} :<br />
{{hc|~/.config/weston.ini|<nowiki><br />
[core]<br />
modules=xwayland.so<br />
<br />
[keyboard]<br />
keymap_layout=gb<br />
<br />
[output]<br />
name=LVDS1<br />
mode=1680x1050<br />
transform=90<br />
<br />
<br />
[launcher]<br />
icon=/usr/share/icons/gnome/24x24/apps/utilities-terminal.png<br />
path=/usr/bin/weston-terminal<br />
<br />
[launcher]<br />
icon=/usr/share/icons/hicolor/24x24/apps/firefox.png<br />
path=/usr/bin/firefox<br />
<br />
</nowiki><br />
}}<br />
<br />
==== XWayland ====<br />
[[Install]] the {{Pkg|xorg-server-xwayland}} package.<br />
<br />
When you want to run an X application from within Weston, it spins up Xwayland to service the request. The following configuration is shown above:<br />
<br />
{{hc|~/.config/weston.ini|<br />
<nowiki>[core]<br />
modules=xwayland.so</nowiki><br />
}}<br />
<br />
==== Screencast recording ====<br />
Weston has build-in screencast recording which can be started and stopped by pressing the {{ic|Super+r}} key combination. Screencasts are saved to the file {{ic|capture.wcap}} in the current working directory of Weston. <br />
<br />
The WCAP format is a lossless video format specific to Weston, which only records the difference in frames. To be able to play the recorded screencast, the WCAP file will need to be converted to a format which a media player can understand. First, convert the capture to the YUV pixel format:<br />
<br />
$ wcap-decode capture.wcap --yuv4mpeg2 > capture.y4m<br />
<br />
The YUV file can then be transcoded to other formats using [[FFmpeg]].<br />
<br />
==== High DPI displays ====<br />
<br />
For [[wikipedia:Retina_Display|Retina]] or [[HiDPI]] displays, use:<br />
<br />
{{hc|~/.config/weston.ini|<br />
<nowiki>[output]<br />
name=...<br />
scale=2</nowiki><br />
}}<br />
<br />
==== Shell font ====<br />
<br />
Weston uses the default sans-serif font for window title bars, clocks, etc. See [[Font configuration#Replace or set default fonts]] for instructions on how to change this font.<br />
<br />
== GUI libraries ==<br />
<br />
See details on the [http://wayland.freedesktop.org/toolkits.html official website].<br />
<br />
=== GTK+ 3 ===<br />
<br />
The {{Pkg|gtk3}} package from the official repositories now has the Wayland backend enabled.<br />
<br />
GTK+ 3 gained support for multiple backends at runtime and can switch between backends in the same way Qt can with lighthouse.<br />
<br />
When both Wayland and X backends are enabled, GTK+ will default to the X11 backend, but this can be overridden by modifying an environment variable: {{ic|GDK_BACKEND&#61;wayland}}.<br />
<br />
=== Qt 5 ===<br />
The {{Grp|qt5}} package from the repositories has the Wayland support if {{Pkg|qt5-wayland}} is installed. <br />
To run a Qt 5 app with the Wayland plugin, set the {{ic|1=QT_QPA_PLATFORM=wayland-egl}} [[environment variable]].<br />
<br />
=== Clutter ===<br />
<br />
The Clutter toolkit has a Wayland backend that allows it to run as a Wayland client. The backend is enabled in the official package in extra.<br />
<br />
To run a Clutter app on Wayland, set {{ic|CLUTTER_BACKEND&#61;wayland}}.<br />
<br />
=== SDL ===<br />
<br />
Experimental wayland support is now in SDL 2.0.2 and enabled by default on Arch Linux.<br />
<br />
To run a SDL application on Wayland, set {{ic|SDL_VIDEODRIVER&#61;wayland}}.<br />
<br />
=== GLFW ===<br />
<br />
Experimental wayland support is now in GLFW 3.1 and can be enabled with the {{ic|-DGLFW_USE_WAYLAND&#61;ON}} CMake option at compile time. You can also install the package {{AUR|glfw-wayland-git}} from the AUR.<br />
<br />
=== EFL ===<br />
<br />
EFL has complete Wayland support. <br />
To run a EFL application on Wayland, see Wayland [http://wayland.freedesktop.org/efl.html project page].<br />
<br />
== Window managers and desktop shells ==<br />
<br />
{| class="wikitable sortable"<br />
! Name<br />
! Type<br />
! Description<br />
|-<br />
| GNOME<br />
| Compositing<br />
| See [[GNOME#Starting GNOME]].<br />
|-<br />
| Hawaii<br />
| ''(Unclear)''<br />
| See [[Hawaii]].<br />
|-<br />
| sway<br />
| Tiling<br />
| [[Sway]] is an i3-compatible window manager for Wayland. [https://github.com/SirCmpwn/sway Github]<br />
|-<br />
| Enlightenment<br />
| ''(Unclear)''<br />
| Long running minimal Window Manager-turned Wayland compositor. E19 originally had Wayland support but this was removed and now only E20+ Wayland is considered stable enough for regular use. [https://www.enlightenment.org/about-wayland More Info]<br />
|-<br />
| KDE Plasma<br />
| Compositing<br />
| See [[KDE#Starting Plasma]]<br />
|-<br />
| Orbment<br />
| Tiling<br />
| [https://github.com/Cloudef/orbment orbment] (previously loliwm) is a tiling WM for Wayland.<br />
|-<br />
| Velox<br />
| Tiling<br />
| [[Velox]] is a simple window manager based on swc. It is inspired by [[dwm]] and [[xmonad]].<br />
|-<br />
| Orbital<br />
| Compositing<br />
| [https://github.com/giucam/orbital Orbital] is a Wayland compositor and shell, using Qt5 and Weston. The goal of the project is to build a simple yet flexible and good looking Wayland desktop. It is not a full fledged DE but rather the analogue of a WM in the X11 world, such as [[Awesome]] or [[Fluxbox]].<br />
|-<br />
| Papyros Shell<br />
| ''(Unclear)''<br />
| [https://github.com/papyros/papyros-shell Papyros Shell] is the desktop shell for [[Papyros]], built using QtQuick and QtCompositor as a compositor for Wayland.<br />
|-<br />
| Maynard<br />
| ''(Unclear)''<br />
| [https://github.com/raspberrypi/maynard Maynard] is a desktop shell client for Weston based on GTK. It was based on weston-gtk-shell, a project by Tiago Vignatti.<br />
|-<br />
| Motorcar<br />
| ''(Unclear)''<br />
| [https://github.com/evil0sheep/motorcar Motorcar] is a wayland compositor to explore 3D windowing.<br />
|-<br />
| Way Cooler<br />
| Tiling<br />
| {{AUR|way-cooler}} is a customizeable (lua config files) Wayland compositor written in Rust. Inspired by i3 and awesome.<br />
|-<br />
| Maze Compositor<br />
| Floating 3D<br />
| [https://github.com/capisce/mazecompositor Maze Compositor] is a 3D QT based wayland compositor<br />
|-<br />
| Grefsen<br />
| Floating<br />
| [https://github.com/ec1oud/grefsen Grefsen] is a Qt/Wayland compositor providing a minimal desktop environment.<br />
|}<br />
<br />
Some of installed wayland desktop clients might store information in {{ic|/usr/share/wayland-sessions/*.desktop}} files about how to start them in wayland.<br />
<br />
==Troubleshooting==<br />
<br />
=== LLVM assertion failure ===<br />
If you get an LLVM assertion failure, you need to rebuild {{Pkg|mesa}} without Gallium LLVM until this problem is fixed. <br />
<br />
This may imply disabling some drivers which require LLVM.<br />
You may also try exporting the following, if having problems with hardware drivers: <br />
<br />
$ export EGL_DRIVER=/usr/lib/egl/egl_gallium.so<br />
<br />
=== Weston fails to launch after update to 1.7 ===<br />
This is possibly caused by the {{ic|desktop-shell.so}} module being loaded by your {{ic|weston.ini}}. This used to be required, but is not anymore.<br />
<br />
Remove it from the {{ic|[core]}} section:<br />
<br />
{{hc|~/.config/weston.ini|<br />
<nowiki>[core]<br />
modules=xwayland.so,desktop-shell.so</nowiki><br />
}}<br />
<br />
So that you end up with:<br />
<br />
{{hc|~/.config/weston.ini|<br />
<nowiki>[core]<br />
modules=xwayland.so</nowiki><br />
}}<br />
<br />
=== Applications using dbus crashes on startup ===<br />
For a temporary solution, use {{ic|dbus-launch}} to run the application. For example, to launch {{Pkg|gnome-terminal}} inside a weston session, this command is sufficient.<br />
<br />
dbus-launch gnome-terminal<br />
<br />
== See also ==<br />
* [[Cursor themes]]<br />
* [https://bbs.archlinux.org/viewtopic.php?id=107499 Arch Linux forum discussion]<br />
* [http://wayland.freedesktop.org/docs/html/ Wayland documentation online]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=Talk:Wayland&diff=451789Talk:Wayland2016-09-24T07:08:55Z<p>Alive4ever: dbus workaround</p>
<hr />
<div>== Window managers and desktop shells ==<br />
<br />
=== Enlightenment? ===<br />
I read [https://phab.enlightenment.org/w/wayland/ here] that they already had good support for Wayland two years ago. Doesn't that make it an important addition to this list?<br />
[[User:Johnchfr|Johnchfr]] ([[User talk:Johnchfr|talk]]) 17:49, 11 October 2014 (UTC)<br />
<br />
:Yes, you are free to add it. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 04:06, 13 October 2014 (UTC)<br />
<br />
::But, I tried it out (pkg from aur) and it seems very rough. The desktop comes up but when I try launching an app, displays an error dialog and when I close the dialog, it froze my system (I could not even switch ttys)! I didn't do much testing through different compile-options, though. -- [[User:Johnchfr|Johnchfr]] ([[User talk:Johnchfr|talk]]) 11:17, 14 October 2014 (UTC)<br />
<br />
:::It seems they're working on it, so it's worth being documented here, together with any relevant note about the state of the implementation. We don't decide what's good and what's bad for users here, we just give objective information to let the users make their own decisions. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 00:02, 15 October 2014 (UTC)<br />
<br />
==Weston - Keyboard Shortcuts ==<br />
Why set {{Ic|Ctrl-b}} in the article section ? [[User:Masterslave|vinegret]] ([[User talk:Masterslave|talk]]) 07:22, 29 January 2015 (UTC)<br />
<br />
== Replacing i3way with sway ==<br />
<br />
Hi there. I've gone ahead and replaced the i3way table row with a row about [https://github.com/SirCmpwn/sway sway] instead. i3way is vaporware with 2 years of radio silence, and sway is actually usable today. [[User:SirCmpwn|SirCmpwn]] ([[User talk:SirCmpwn|talk]]) 13:29, 16 August 2015 (UTC)<br />
<br />
== dbus ==<br />
<br />
On weston 1.12, application using dbus cannot be launched normally. I've added a workaround to launch on the troubleshooting section.<br />
<br />
[[User:Alive4ever|Alive4ever]] ([[User talk:Alive4ever|talk]])</div>Alive4everhttps://wiki.archlinux.org/index.php?title=Wayland&diff=451787Wayland2016-09-24T07:00:49Z<p>Alive4ever: /* Troubleshooting */ Application using dbus crashes on weston 1.12</p>
<hr />
<div>[[Category:X server]]<br />
[[es:Wayland]]<br />
[[fr:Wayland]]<br />
[[ja:Wayland]]<br />
[[ru:Wayland]]<br />
[[zh-CN:Wayland]]<br />
{{Related articles start}}<br />
{{Related|KMS}}<br />
{{Related|Xorg}}<br />
{{Related|Mir}}<br />
{{Related articles end}}<br />
'''Wayland''' is a new windowing protocol for Linux. Utilization of Wayland requires changes to and re-installation of parts of your system's software. For more information on Wayland see its [http://wayland.freedesktop.org/ homepage].<br />
<br />
== Requirements ==<br />
<br />
Currently Wayland will only work on systems utilizing [[KMS]].<br />
<br />
== Installation ==<br />
{{Note|Wayland is most likely installed on your system already, since it is an indirect dependency of {{Pkg|gtk2}} and {{Pkg|gtk3}}.}}<br />
<br />
[[Install]] the {{Pkg|wayland}} package.<br />
<br />
== Usage ==<br />
<br />
As Wayland is only a library, it is useless on its own. To replace X Server, you need a compositor (like [[#Weston]]).<br />
<br />
== Weston ==<br />
<br />
=== Installation ===<br />
<br />
[[Install]] the {{Pkg|weston}} package.<br />
<br />
=== Usage ===<br />
<br />
{| class="wikitable" style="float: right; width: 200px;"<br />
|+ '''''Keyboard Shortcuts''' (super = windows key - can be changed, see weston.ini)'' {{Ic|Ctrl-b}}<br />
!Cmd<br />
!Action<br />
|-<br />
|Ctrl + Alt + Backspace<br />
|Quit Weston<br />
|-<br />
|Super + Scroll (or PageUp/PageDown)<br />
|Zoom in/out of desktop<br />
|-<br />
|Super + Tab<br />
|Switch windows<br />
|-<br />
|Super + LMB<br />
|Move Window<br />
|-<br />
|Super + MMB<br />
|Rotate Window !<br />
|-<br />
|Super + RMB<br />
|Resize Window <br />
|-<br />
|Super + Alt + Scroll<br />
|Change window opacity<br />
|-<br />
|Super + K<br />
|Force Kill Active Window<br />
|-<br />
|Super + KeyUp/KeyDown<br />
|Switch Prev/Next Workspace<br />
|-<br />
|Super + Shift + KeyUp/KeyDown<br />
|Grab Current Window and Switch Workspace<br />
|-<br />
|Super + F'''''n'''''<br />
|Switch to Workspace '''''n'''''<br />
|-<br />
|Super + S<br />
|Take a screenshot<br />
|-<br />
|Super + R<br />
|Record a screencast.<br />
|}<br />
<br />
Now that Wayland and its requirements are installed you should be ready to test it out. <br />
<br />
It is possible to run Weston inside a running X session:<br />
$ weston<br />
<br />
Alternatively, to try to launch Weston natively, switch to a terminal and run:<br />
$ weston-launch<br />
<br />
Then at a TTY within Weston, you can run the demos. To launch a terminal emulator:<br />
$ weston-terminal<br />
<br />
To move flowers around the screen:<br />
$ weston-flower <br />
<br />
To test the frame protocol (runs {{ic|glxgears}}):<br />
$ weston-gears<br />
<br />
To display images:<br />
$ weston-image image1.jpg image2.jpg...<br />
<br />
=== Configuration ===<br />
Example configuration file for keyboard layout, module selection and UI modifications. See {{ic|man weston.ini}} for full details:<br />
<br />
{{hc|~/.config/weston.ini|<nowiki><br />
[core]<br />
# xwayland support<br />
modules=xwayland.so<br />
<br />
<br />
[libinput]<br />
enable_tap=true<br />
<br />
<br />
[shell]<br />
background-image=/usr/share/backgrounds/gnome/Aqua.jpg<br />
background-color=0xff002244<br />
panel-color=0x90ff0000<br />
locking=true<br />
animation=zoom<br />
close-animation=fade<br />
focus-animation=dim-layer<br />
#binding-modifier=ctrl<br />
#num-workspaces=6<br />
### for cursor themes install xcursor-themes pkg from Extra. ###<br />
#cursor-theme=whiteglass<br />
#cursor-size=24<br />
<br />
### tablet options ###<br />
#lockscreen-icon=/usr/share/icons/gnome/256x256/actions/lock.png<br />
#lockscreen=/usr/share/backgrounds/gnome/Garden.jpg<br />
#homescreen=/usr/share/backgrounds/gnome/Blinds.jpg<br />
#animation=fade<br />
<br />
<br />
### for Laptop displays ###<br />
#[output]<br />
#name=LVDS1<br />
#mode=1680x1050<br />
#transform=90<br />
<br />
#[output]<br />
#name=VGA1<br />
# The following sets the mode with a modeline, you can get modelines for your preffered resolutions using the cvt utility<br />
#mode=173.00 1920 2048 2248 2576 1080 1083 1088 1120 -hsync +vsync<br />
#transform=flipped<br />
<br />
#[output]<br />
#name=X1<br />
#mode=1024x768<br />
#transform=flipped-270<br />
<br />
<br />
[input-method]<br />
#path=/usr/lib/weston/weston-keyboard<br />
<br />
<br />
[keyboard]<br />
keymap_rules=evdev<br />
#keymap_layout=gb,de<br />
#keymap_options=caps:ctrl_modifier,shift:both_capslock_cancel<br />
### keymap_options from /usr/share/X11/xkb/rules/base.lst ###<br />
numlock-on=true<br />
<br />
[terminal]<br />
#font=DroidSansMono<br />
#font-size=14<br />
<br />
<br />
[launcher]<br />
icon=/usr/share/icons/gnome/24x24/apps/utilities-terminal.png<br />
path=/usr/bin/weston-terminal<br />
<br />
[launcher]<br />
icon=/usr/share/icons/gnome/24x24/apps/utilities-terminal.png<br />
path=/usr/bin/gnome-terminal<br />
<br />
[launcher]<br />
icon=/usr/share/icons/hicolor/24x24/apps/firefox.png<br />
path=/usr/bin/firefox<br />
<br />
[launcher]<br />
icon=/usr/share/weston/icon_flower.png<br />
path=/usr/bin/weston-flower<br />
<br />
[screensaver]<br />
# Uncomment path to disable screensaver<br />
path=/usr/libexec/weston-screensaver<br />
duration=600<br />
</nowiki><br />
}}<br />
<br />
<br />
Minimal {{ic|weston.ini}} :<br />
{{hc|~/.config/weston.ini|<nowiki><br />
[core]<br />
modules=xwayland.so<br />
<br />
[keyboard]<br />
keymap_layout=gb<br />
<br />
[output]<br />
name=LVDS1<br />
mode=1680x1050<br />
transform=90<br />
<br />
<br />
[launcher]<br />
icon=/usr/share/icons/gnome/24x24/apps/utilities-terminal.png<br />
path=/usr/bin/weston-terminal<br />
<br />
[launcher]<br />
icon=/usr/share/icons/hicolor/24x24/apps/firefox.png<br />
path=/usr/bin/firefox<br />
<br />
</nowiki><br />
}}<br />
<br />
==== XWayland ====<br />
[[Install]] the {{Pkg|xorg-server-xwayland}} package.<br />
<br />
When you want to run an X application from within Weston, it spins up Xwayland to service the request. The following configuration is shown above:<br />
<br />
{{hc|~/.config/weston.ini|<br />
<nowiki>[core]<br />
modules=xwayland.so</nowiki><br />
}}<br />
<br />
==== Screencast recording ====<br />
Weston has build-in screencast recording which can be started and stopped by pressing the {{ic|Super+r}} key combination. Screencasts are saved to the file {{ic|capture.wcap}} in the current working directory of Weston. <br />
<br />
The WCAP format is a lossless video format specific to Weston, which only records the difference in frames. To be able to play the recorded screencast, the WCAP file will need to be converted to a format which a media player can understand. First, convert the capture to the YUV pixel format:<br />
<br />
$ wcap-decode capture.wcap --yuv4mpeg2 > capture.y4m<br />
<br />
The YUV file can then be transcoded to other formats using [[FFmpeg]].<br />
<br />
==== High DPI displays ====<br />
<br />
For [[wikipedia:Retina_Display|Retina]] or [[HiDPI]] displays, use:<br />
<br />
{{hc|~/.config/weston.ini|<br />
<nowiki>[output]<br />
name=...<br />
scale=2</nowiki><br />
}}<br />
<br />
==== Shell font ====<br />
<br />
Weston uses the default sans-serif font for window title bars, clocks, etc. See [[Font configuration#Replace or set default fonts]] for instructions on how to change this font.<br />
<br />
== GUI libraries ==<br />
<br />
See details on the [http://wayland.freedesktop.org/toolkits.html official website].<br />
<br />
=== GTK+ 3 ===<br />
<br />
The {{Pkg|gtk3}} package from the official repositories now has the Wayland backend enabled.<br />
<br />
GTK+ 3 gained support for multiple backends at runtime and can switch between backends in the same way Qt can with lighthouse.<br />
<br />
When both Wayland and X backends are enabled, GTK+ will default to the X11 backend, but this can be overridden by modifying an environment variable: {{ic|GDK_BACKEND&#61;wayland}}.<br />
<br />
=== Qt 5 ===<br />
The {{Grp|qt5}} package from the repositories has the Wayland support if {{Pkg|qt5-wayland}} is installed. <br />
To run a Qt 5 app with the Wayland plugin, set the {{ic|1=QT_QPA_PLATFORM=wayland-egl}} [[environment variable]].<br />
<br />
=== Clutter ===<br />
<br />
The Clutter toolkit has a Wayland backend that allows it to run as a Wayland client. The backend is enabled in the official package in extra.<br />
<br />
To run a Clutter app on Wayland, set {{ic|CLUTTER_BACKEND&#61;wayland}}.<br />
<br />
=== SDL ===<br />
<br />
Experimental wayland support is now in SDL 2.0.2 and enabled by default on Arch Linux.<br />
<br />
To run a SDL application on Wayland, set {{ic|SDL_VIDEODRIVER&#61;wayland}}.<br />
<br />
=== GLFW ===<br />
<br />
Experimental wayland support is now in GLFW 3.1 and can be enabled with the {{ic|-DGLFW_USE_WAYLAND&#61;ON}} CMake option at compile time. You can also install the package {{AUR|glfw-wayland-git}} from the AUR.<br />
<br />
=== EFL ===<br />
<br />
EFL has complete Wayland support. <br />
To run a EFL application on Wayland, see Wayland [http://wayland.freedesktop.org/efl.html project page].<br />
<br />
== Window managers and desktop shells ==<br />
<br />
{| class="wikitable sortable"<br />
! Name<br />
! Type<br />
! Description<br />
|-<br />
| GNOME<br />
| Compositing<br />
| See [[GNOME#Starting GNOME]].<br />
|-<br />
| Hawaii<br />
| ''(Unclear)''<br />
| See [[Hawaii]].<br />
|-<br />
| sway<br />
| Tiling<br />
| [[Sway]] is an i3-compatible window manager for Wayland. [https://github.com/SirCmpwn/sway Github]<br />
|-<br />
| Enlightenment<br />
| ''(Unclear)''<br />
| Long running minimal Window Manager-turned Wayland compositor. E19 originally had Wayland support but this was removed and now only E20+ Wayland is considered stable enough for regular use. [https://www.enlightenment.org/about-wayland More Info]<br />
|-<br />
| KDE Plasma<br />
| Compositing<br />
| See [[KDE#Starting Plasma]]<br />
|-<br />
| Orbment<br />
| Tiling<br />
| [https://github.com/Cloudef/orbment orbment] (previously loliwm) is a tiling WM for Wayland.<br />
|-<br />
| Velox<br />
| Tiling<br />
| [[Velox]] is a simple window manager based on swc. It is inspired by [[dwm]] and [[xmonad]].<br />
|-<br />
| Orbital<br />
| Compositing<br />
| [https://github.com/giucam/orbital Orbital] is a Wayland compositor and shell, using Qt5 and Weston. The goal of the project is to build a simple yet flexible and good looking Wayland desktop. It is not a full fledged DE but rather the analogue of a WM in the X11 world, such as [[Awesome]] or [[Fluxbox]].<br />
|-<br />
| Papyros Shell<br />
| ''(Unclear)''<br />
| [https://github.com/papyros/papyros-shell Papyros Shell] is the desktop shell for [[Papyros]], built using QtQuick and QtCompositor as a compositor for Wayland.<br />
|-<br />
| Maynard<br />
| ''(Unclear)''<br />
| [https://github.com/raspberrypi/maynard Maynard] is a desktop shell client for Weston based on GTK. It was based on weston-gtk-shell, a project by Tiago Vignatti.<br />
|-<br />
| Motorcar<br />
| ''(Unclear)''<br />
| [https://github.com/evil0sheep/motorcar Motorcar] is a wayland compositor to explore 3D windowing.<br />
|-<br />
| Way Cooler<br />
| Tiling<br />
| {{AUR|way-cooler}} is a customizeable (lua config files) Wayland compositor written in Rust. Inspired by i3 and awesome.<br />
|}<br />
<br />
Some of installed wayland desktop clients might store information in {{ic|/usr/share/wayland-sessions/*.desktop}} files about how to start them in wayland.<br />
<br />
==Troubleshooting==<br />
<br />
=== LLVM assertion failure ===<br />
If you get an LLVM assertion failure, you need to rebuild {{Pkg|mesa}} without Gallium LLVM until this problem is fixed. <br />
<br />
This may imply disabling some drivers which require LLVM.<br />
You may also try exporting the following, if having problems with hardware drivers: <br />
<br />
$ export EGL_DRIVER=/usr/lib/egl/egl_gallium.so<br />
<br />
=== Weston fails to launch after update to 1.7 ===<br />
This is possibly caused by the {{ic|desktop-shell.so}} module being loaded by your {{ic|weston.ini}}. This used to be required, but is not anymore.<br />
<br />
Remove it from the {{ic|[core]}} section:<br />
<br />
{{hc|~/.config/weston.ini|<br />
<nowiki>[core]<br />
modules=xwayland.so,desktop-shell.so</nowiki><br />
}}<br />
<br />
So that you end up with:<br />
<br />
{{hc|~/.config/weston.ini|<br />
<nowiki>[core]<br />
modules=xwayland.so</nowiki><br />
}}<br />
<br />
=== Applications using dbus crashes on startup ===<br />
For a temporary solution, use {{ic|dbus-launch}} to run the application. For example, to launch {{Pkg|gnome-terminal}} inside a weston session, this command is sufficient.<br />
<br />
dbus-launch gnome-terminal<br />
<br />
== See also ==<br />
* [[Cursor themes]]<br />
* [https://bbs.archlinux.org/viewtopic.php?id=107499 Arch Linux forum discussion]<br />
* [http://wayland.freedesktop.org/docs/html/ Wayland documentation online]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=GNOME&diff=449939GNOME2016-09-08T14:35:37Z<p>Alive4ever: /* Appearance */ Icons on menu configuration</p>
<hr />
<div>[[Category:GNOME]]<br />
[[cs:GNOME]]<br />
[[de:GNOME]]<br />
[[es:GNOME]]<br />
[[fr:GNOME]]<br />
[[it:GNOME]]<br />
[[ja:GNOME]]<br />
[[nl:GNOME]]<br />
[[pl:GNOME]]<br />
[[pt:GNOME]]<br />
[[ru:GNOME]]<br />
[[sr:GNOME]]<br />
[[th:GNOME]]<br />
[[tr:Gnome Masaüstü Ortamı]]<br />
[[uk:GNOME]]<br />
[[zh-CN:GNOME]]<br />
[[zh-TW:GNOME]]<br />
{{Related articles start}}<br />
{{Related|Desktop environment}}<br />
{{Related|Display manager}}<br />
{{Related|Window manager}}<br />
{{Related|GTK+}}<br />
{{Related|GDM}}<br />
{{Related|GNOME/Tips and tricks}}<br />
{{Related|GNOME/Troubleshooting}}<br />
{{Related|GNOME/Files}}<br />
{{Related|GNOME/Gedit}}<br />
{{Related|GNOME/Web}}<br />
{{Related|GNOME/Evolution}}<br />
{{Related|GNOME/Flashback}}<br />
{{Related|GNOME/Keyring}}<br />
{{Related|Cinnamon}}<br />
{{Related|MATE}}<br />
{{Related|Official repositories#gnome-unstable}}<br />
{{Related articles end}}<br />
<br />
GNOME (pronounced ''gah-nohm'' or ''nohm'') is a [[desktop environment]] that aims to be simple and easy to use. It is designed by [[Wikipedia:The GNOME Project|The GNOME Project]] and is composed entirely of free and open-source software. GNOME is a part of the [[Wikipedia:GNU Project|GNU Project]].<br />
<br />
== Installation ==<br />
<br />
Two groups are available:<br />
<br />
* {{Grp|gnome}} contains the base GNOME desktop and a subset of well-integrated [https://wiki.gnome.org/Apps applications];<br />
* {{Grp|gnome-extra}} contains further GNOME applications, including an archive manager, disk manager, [[Gedit|text editor]], and a set of games. Note that this group builds on the {{Grp|gnome}} group.<br />
<br />
The base desktop consists of [[Wikipedia:GNOME_Shell|GNOME Shell]], a plugin for the [[Wikipedia:Mutter_(software)|Mutter]] window manager. It can be installed separately with {{Pkg|gnome-shell}}.<br />
<br />
{{Note|''mutter'' acts as a composite manager for the desktop, employing hardware graphics acceleration to provide effects aimed at reducing screen clutter. The GNOME session manager automatically detects if your video driver is capable of running GNOME Shell and if not, falls back to software rendering using ''llvmpipe''.}} <br />
<br />
=== Additional packages ===<br />
<br />
These packages are not in the above mentioned groups:<br />
<br />
* {{App|[[Wikipedia:GNOME Boxes|Boxes]]|A simple user interface to access [[libvirt]] virtual machines.|https://wiki.gnome.org/Apps/Boxes|{{Pkg|gnome-boxes}}}}<br />
* {{App|GNOME Initial Setup|A simple, easy, and safe way to prepare a new system.|https://github.com/GNOME/gnome-initial-setup|{{Pkg|gnome-initial-setup}}}}<br />
* {{App|GNOME PackageKit|Collection of graphical tools for PackageKit to be used in the GNOME desktop.|https://github.com/GNOME/gnome-packagekit|{{Pkg|gnome-packagekit}}}}<br />
* {{App|[[Wikipedia:Nemiver|Nemiver]]|A C/C++ debugger.|https://wiki.gnome.org/Apps/Nemiver|{{Pkg|nemiver}}}}<br />
* {{App|[[Wikipedia:GNOME Software|Software]]|Lets you install and update applications and system extensions.|https://wiki.gnome.org/Apps/Software/|{{Pkg|gnome-software}}}}<br />
<br />
== GNOME Sessions ==<br />
<br />
GNOME has three available sessions, all using GNOME Shell.<br />
<br />
*'''GNOME''' is the default, innovative layout.<br />
*'''GNOME Classic''' is a traditional desktop layout with a similar interface to GNOME 2, using pre-activated extensions and parameters. [http://worldofgnome.org/welcome-to-gnome-3-8-flintstones-mode/] Hence it is more a customized GNOME Shell than a truly distinct mode.<br />
*'''GNOME on Wayland''' runs GNOME Shell using the new Wayland protocol. Traditional X applications are run through Xwayland.<br />
<br />
== Starting GNOME ==<br />
<br />
GNOME can be started either graphically, using a [[display manager]], or manually from the console. For optimal desktop integration, using [[GDM]] (the GNOME Display manager) is recommended. Note that [[enabling]] a display manager (such as GDM) means that Xorg will run with root rights. <br />
<br />
{{Note|Support for screen locking in GNOME is provided by GDM. If GNOME is not started using GDM, you will have to use another screen locker to provide this functionality - see [[List of applications/Security#Screen lockers]].}}<br />
<br />
=== Graphically ===<br />
<br />
Select the session: ''GNOME'', ''GNOME Classic'' or ''GNOME on Wayland'' from the display manager's session menu.<br />
<br />
=== Manually ===<br />
<br />
* For the standard GNOME session, add to the {{ic|~/.xinitrc}} file: {{ic|exec gnome-session}}.<br />
* For the GNOME Classic session, add to the {{ic|~/.xinitrc}} file: {{bc|<nowiki>export XDG_CURRENT_DESKTOP=GNOME-Classic:GNOME<br />
export GNOME_SHELL_SESSION_MODE=classic<br />
exec gnome-session --session=gnome-classic</nowiki>}}<br />
<br />
After editing the {{ic|~/.xinitrc}} file, GNOME can be launched with the {{ic|startx}} command (see [[xinitrc]] for additional details, such as preserving the logind session). After setting up the {{ic|~/.xinitrc}} file it can also be arranged to [[Start X at login]].<br />
<br />
{{Note|GNOME on Wayland requires the {{Pkg|xorg-server-xwayland}} package, and '''cannot''' be started using ''startx'' and {{ic|~/.xinitrc}}. Instead, run {{ic|gnome-session --session&#61;gnome-wayland}}. For more information, see [[Wayland]].}}<br />
<br />
=== GNOME applications in Wayland ===<br />
<br />
Currently, by default, GNOME applications will be run as traditional X applications through Xwayland. To test GNOME applications with Wayland, use the command line to run the application and prefix the command with {{ic|env GDK_BACKEND&#61;'wayland,x11' <command>}}.<br />
<br />
{{Note|Setting a global Wayland environment, by running {{ic|env GDK_BACKEND&#61;wayland gnome-session --session&#61;gnome-wayland}}, currently does not work. For workarounds, see [[GNOME/Troubleshooting#Setting global Wayland environment with an environment variable]].}}<br />
<br />
See the current status of Wayland on GNOME at [https://wiki.gnome.org/Initiatives/Wayland/Applications/ GNOME Applications under Wayland].<br />
<br />
== Navigation ==<br />
<br />
To learn how to use the GNOME shell effectively read the [https://wiki.gnome.org/Projects/GnomeShell/CheatSheet GNOME Shell Cheat Sheet]; it highlights GNOME shell features and keyboard shortcuts. Features include task switching, keyboard use, window control, the panel, overview mode, and more. A few of the shortcuts are:<br />
<br />
* {{ic|Super}} + {{ic|m}}: show message tray<br />
* {{ic|Super}} + {{ic|a}}: show applications menu<br />
* {{ic|Alt-}} + {{ic|Tab}}: cycle active applications <br />
* {{ic|Alt-}} + {{ic|`}} (the key above {{ic|Tab}} on US keyboard layouts): cycle windows of the application in the foreground <br />
* {{ic|Alt}} + {{ic|F2}}, then enter {{ic|r}} or {{ic|restart}}: restart the shell in case of graphical shell problems. <br />
<br />
=== Legacy names ===<br />
<br />
{{Note|<br />
Some GNOME programs have undergone name changes where the application's name in documentation and about dialogs has been changed but the executable name has not. A few such applications are listed in the table below.}}<br />
<br />
{{Tip|Searching for the legacy name of an application in the Shell search bar will successfully return the application in question. For instance, searching for ''nautilus'' will return ''Files''.}}<br />
<br />
{| class="wikitable"<br />
! Current<br />
! Legacy<br />
|-<br />
| [[Files]]<br />
| Nautilus<br />
|-<br />
| [[GNOME Web|Web]]<br />
| Epiphany<br />
|-<br />
| Videos<br />
| Totem<br />
|-<br />
| Main Menu<br />
| Alacarte<br />
|-<br />
| Document Viewer<br />
| Evince<br />
|-<br />
| Disk Usage Analyser<br />
| Baobab<br />
|-<br />
| Image Viewer<br />
| EoG (Eye of GNOME)<br />
|-<br />
| [[GNOME Keyring|Passwords and Keys]]<br />
| Seahorse<br />
|}<br />
<br />
== Configuration ==<br />
<br />
The GNOME desktop relies on a configuration database backend (DConf) to store system and application settings. The desktop comes with default configuration settings, installed applications add their own to the database. The basic configuration is done either via the GNOME System Settings panel (''gnome-control-center'') or the preferences of the individual applications. A direct configuration of the DConf database is always possible as well and performed with the ''gsettings'' command line tool. In particular it can be used to configure settings which are not exposed via the user interface.<br />
<br />
GNOME settings are then applied by the GNOME Settings Daemon. Note that the daemon can be run outside of a GNOME session in order to apply GNOME configuration in a non-GNOME environment. Execute {{ic|nohup /usr/lib/gnome-settings-daemon/gnome-settings-daemon > /dev/null &}} to do so.<br />
<br />
The configuration is usually performed per user and the rest of this section does not cover how to create configuration templates for a multi-user-system. <br />
<br />
=== System settings ===<br />
<br />
Control panel settings of note.<br />
<br />
==== Color ====<br />
<br />
The daemon {{ic|colord}} reads the display's EDID and extracts the appropriate color profile. Most color profiles are accurate and no setup is required; however for those that are not accurate, or for older displays, color profiles can be put in {{ic|~/.local/share/icc/}} and directed to.<br />
<br />
==== Date & time ====<br />
<br />
If the system has a configured [[Network Time Protocol daemon]], it will be effective for GNOME as well. The synchronization can be set to manual control from the menu, if required. <br />
<br />
To show the date in the top bar, execute:<br />
<br />
$ gsettings set org.gnome.desktop.interface clock-show-date true<br />
<br />
Additionally, to show week numbers in the Shell calendar, execute:<br />
$ gsettings set org.gnome.shell.calendar show-weekdate true<br />
<br />
==== Default applications ====<br />
<br />
Upon installing GNOME for the first time, you may find that the wrong applications are handling certain protocols. For example, ''totem'' opens videos instead of a previously used [[VLC]]. Some of the associations can be set from system settings via: ''System'' > ''Details'' > ''Default applications''. <br />
<br />
For other protocols and methods see [[Default applications]] for configuration. <br />
<br />
==== Mouse and touchpad ====<br />
<br />
To help reduce touchpad interference you may wish to implement the settings below:<br />
<br />
* Disable touchpad while typing<br />
* Disable scrolling<br />
* Disable tap-to-click<br />
<br />
{{Note|1=The [[synaptics]] driver is not supported by GNOME. Instead, you should use [[libinput]]. See [https://bugzilla.gnome.org/show_bug.cgi?id=764257#c12 this bug report].}}<br />
<br />
==== Network ====<br />
<br />
[[NetworkManager]] is the native tool of the GNOME project to control network settings from the shell. It is installed by default as a dependency for {{Pkg|tracker}} package, which is a part of {{Grp|gnome}} group, and just needs to be [[NetworkManager#Enable NetworkManager|enabled]].<br />
<br />
While any other [[List_of_applications/Internet#Network_managers|network manager]] can be used as well, NetworkManager provides the full integration via the shell network settings and a status indicator applet {{Pkg|network-manager-applet}} (not required for GNOME).<br />
<br />
==== Online accounts ====<br />
<br />
Backends for the GNOME messaging application {{Pkg|empathy}} as well as the GNOME Online Accounts section of the System Settings panel are provided in a separate group: {{Grp|telepathy}}. See [[#Unable to add accounts in Empathy and GNOME Online Accounts]]{{Broken section link}}. Some online accounts, such as [[ownCloud]], require {{Pkg|gvfs-goa}} to be installed for full functionality in GNOME applications such as [[GNOME Files]] and GNOME Documents [https://wiki.gnome.org/ThreePointSeven/Features/Owncloud].<br />
<br />
==== Search ====<br />
<br />
The GNOME shell has a search that can be quickly accessed by pressing the {{ic|Super}} key and starting to type. The {{Pkg|tracker}} package is installed by default as a part of {{Grp|gnome}} group and provides an indexing application and metadata database. It can be configured with the ''Search and Indexing'' menu item; monitor status with ''tracker-control''. It is started automatically by ''gnome-session'' when the user logs in. Indexing can be started manually with {{ic|tracker-control -s}}. Search settings can also be configured in the ''System Settings'' panel.<br />
<br />
The Tracker database can be queried using the ''tracker-sparql'' command. View its manual page {{ic|man tracker-sparql}} for more information.<br />
<br />
=== Advanced settings ===<br />
<br />
As noted above, many configuration options such as changing the [[GTK+]] theme or the [[window manager]] theme are not exposed in the GNOME System Settings panel (''gnome-control-center''). Those users that want to configure these settings may wish to use the GNOME Tweak Tool ({{Pkg|gnome-tweak-tool}}), a convenient graphical tool which exposes many of these settings. <br />
<br />
GNOME settings (which are stored in the DConf database) can also be configured using the [https://developer.gnome.org/dconf/unstable/dconf-editor.html ''dconf-editor''] (a graphical DConf configuration tool) or the [https://developer.gnome.org/gio/stable/GSettings.html ''gsettings''] command line tool. The GNOME Tweak Tool does not do anything else in the background of the GUI; note though that you will not find all settings described in the following sections in it. <br />
<br />
==== Appearance ====<br />
<br />
===== GTK+ themes and icon themes =====<br />
<br />
To install a new theme or icon set, add the relevant {{ic|~/.local/share/themes}} or {{ic|~/.local/share/icons}} respectively (add to {{ic|/usr/share/}} instead of {{ic|~/.local/share/}} for the themes to be available systemwide.) They and other GUI settings can also be defined in {{ic|~/.config/gtk-3.0/settings.ini}}:<br />
<br />
{{hc|~/.config/gtk-3.0/settings.ini|<nowiki><br />
[Settings]<br />
gtk-theme-name = Adwaita<br />
# next option is applicable only if selected theme supports it<br />
gtk-application-prefer-dark-theme = true<br />
# set font name and dimension<br />
gtk-font-name = Sans 10<br />
</nowiki>}}<br />
<br />
Additional theme locations:<br />
* [http://www.deviantart.com/browse/all/customization/skins/linuxutil/desktopenv/gnome/gtk3/ DeviantArt].<br />
* [http://gnome-look.org/index.php?xcontentmode=167 gnome-look.org].<br />
* [https://aur.archlinux.org/packages.php?O=0&K=gtk3&do_Search=Go GTK3 themes in the AUR].<br />
* [https://aur.archlinux.org/packages.php?O=0&K=xcursor&do_Search=Go&PP=50&SB=v&SO=d Cursor themes in the AUR].<br />
* [https://aur.archlinux.org/packages.php?O=0&K=icon-theme&do_Search=Go&PP=50&SB=v&SO=d Icon themes in the AUR].<br />
<br />
Once installed, they can be selected using the GNOME Tweak Tool or GSettings - see below for GSettings commands:<br />
<br />
For the GTK+ theme:<br />
$ gsettings set org.gnome.desktop.interface gtk-theme ''theme-name''<br />
<br />
For the icon theme<br />
$ gsettings set org.gnome.desktop.interface icon-theme ''theme-name''<br />
<br />
====== Global dark theme ======<br />
<br />
GNOME will use the Adwaita light theme by default however a dark variant of this theme (called the Global Dark Theme) also exists and can be selected using the Tweak Tool or by editing the GTK+ 3 settings file - see [[GTK+#Dark theme variant]]. Some applications such as Image Viewer (''eog'') use the dark theme by default. It should be noted that the Global Dark Theme only works with GTK+ 3 applications; some GTK+ 3 applications may only have partial support for the Global Dark theme. Qt and GTK+ 2 support for the Global Dark Theme may be added in the future.<br />
<br />
===== Window manager themes =====<br />
<br />
The window manager theme (the style of the window titlebars) can be set using the GNOME Tweak Tool or the following GSettings command:<br />
$ gsettings set org.gnome.desktop.wm.preferences theme ''theme-name''<br />
<br />
====== Titlebar height ======<br />
<br />
{{Note|Applying this configuration shrinks the titlebar of the GNOME-terminal and Chromium, but does not appear to affect the Nautilus titlebar height.}}<br />
<br />
{{hc|~/.config/gtk-3.0/gtk.css|<br />
headerbar.default-decoration {<br />
padding-top: 0px;<br />
padding-bottom: 0px;<br />
min-height: 0px;<br />
font-size: 0.6em;<br />
}<br />
<br />
headerbar.default-decoration button.titlebutton {<br />
padding: 0px;<br />
min-height: 0px;<br />
}<br />
}}<br />
See [https://ask.fedoraproject.org/en/question/10035/shrink-title-bar/?answer=86149#post-id-86149] for more information.<br />
<br />
====== Titlebar button order ======<br />
<br />
To set the order for the GNOME window manager (Mutter, Metacity): <br />
$ gsettings set org.gnome.desktop.wm.preferences button-layout ':minimize,maximize,close'<br />
<br />
{{Tip|The colon indicates which side of the titlebar the window buttons will appear.}}<br />
<br />
====== Hide titlebar when maximized ======<br />
<br />
*[[Install]] {{AUR|gnome-shell-extension-pixel-saver-git}} or {{AUR|gnome-shell-extension-pixel-saver}}. Maximized windows get the title bar merged into the activity bar, saving precious pixels.<br />
<br />
*[[Install]] {{AUR|mutter-hide-legacy-decorations}}. It changes a default setting in the window manager, so as to automatically hide the titlebar on legacy (non-headerbar) apps when they are maximized or tiled to the side.<br />
<br />
*[[Install]] {{AUR|maximus}}. To start the application, execute ''maximus'' from a terminal. When running, the daemon will automatically maximize windows. It will undecorate maximized windows and redecorate them when they are unmaximized. If you do not want all windows to start maximized, run {{ic|maximus -m}} instead. Note that this will only work with windows decorated by the window manager; applications that use client-side decoration such as [[GNOME Files]] will not be undecorated when maximized.<br />
<br />
===== GNOME Shell themes =====<br />
<br />
The theme of GNOME Shell itself is configurable. To use a Shell theme, firstly ensure that you have the {{Pkg|gnome-shell-extensions}} package installed. Then enable the ''User Themes'' extension, either through GNOME Tweak Tool or through the [https://extensions.gnome.org GNOME Shell Extensions] webpage. Shell themes can then be loaded and selected using the GNOME Tweak Tool.<br />
<br />
There are a number of GNOME Shell themes available [https://aur.archlinux.org/packages.php?O=0&K=gnome-shell-theme&do_Search=Go&PP=50&SB=v&SO=d in the AUR].<br />
<br />
Shell themes can also be downloaded from [http://gnome-look.org/index.php?xcontentmode=191 gnome-look.org].<br />
<br />
===== Icons on menu =====<br />
<br />
The default GNOME schema doesn't display any icon on menus. To display icons on menus, issue the following command.<br />
<br />
$ gsettings set org.gnome.settings-daemon.plugins.xsettings overrides "{'Gtk/ButtonImages': <1>, 'Gtk/MenuImages': <1>}"<br />
<br />
==== Desktop ====<br />
<br />
Various Desktop settings can be applied.<br />
<br />
===== Icons on the Desktop =====<br />
<br />
See [[GNOME/Files#Desktop Icons]].<br />
<br />
===== Lock screen and background =====<br />
<br />
When setting the Desktop or Lock screen background, it is important to note that the Pictures tab will only display pictures located in {{ic|/home/''username''/Pictures}} folder. If you wish to use a picture not located in this folder, use the commands indicated below.<br />
<br />
For the desktop background:<br />
$ gsettings set org.gnome.desktop.background picture-uri 'file:///path/to/my/picture.jpg'<br />
<br />
For the lock screen background<br />
$ gsettings set org.gnome.desktop.screensaver picture-uri 'file:///path/to/my/picture.jpg'<br />
<br />
==== Extensions ====<br />
<br />
{{Note|The GNOME Shell browser plugin which allows users to install extensions from [https://extensions.gnome.org extensions.gnome.org] is not compatible with Chrome/Chromium. Users wishing to install extensions from the webpage will have to use a compatible browser such as [[Firefox]] or [[GNOME/Web]].}}<br />
<br />
GNOME Shell can be customized with extensions per user or system-wide. <br />
<br />
The catalogue of extensions is available at [https://extensions.gnome.org extensions.gnome.org]. By a user they can be installed and activated in the browser by setting the switch in the top left of the screen to '''ON''' and clicking '''Install''' on the resulting dialog (if the extension in question is not installed). After installation it is shown in the [https://extensions.gnome.org/local/ extensions.gnome.org/local/] tab, which has to be visited as well to check for available updates. Installed extensions can also be enabled or disabled using {{Pkg|gnome-tweak-tool}}. <br />
<br />
More information about GNOME shell extensions is available on the [https://extensions.gnome.org/about/ GNOME Shell Extensions about page].<br />
<br />
[[Installing]] extensions via a package makes them available for all users of the system and automates the update process. <br />
<br />
The {{Pkg|gnome-shell-extensions}} package provides a set of extensions maintained as part of the GNOME project (many of the included extensions are used by the GNOME Classic session). <br />
<br />
Users who want a taskbar but do not wish to use the GNOME Classic session may want to enable the ''Window list'' extension (provided by the {{Pkg|gnome-shell-extensions}} package).<br />
<br />
==== Input methods ====<br />
<br />
GNOME has integrated support for input methods through [[IBus]], only {{Pkg|ibus}} and the wanted input method engine (e.g. {{Pkg|ibus-libpinyin}} for Intelligent Pinyin) needed to be installed, after installation the input method engine can be added as a keyboard layout in GNOME's Regional & Language Settings.<br />
<br />
==== Fonts ====<br />
<br />
{{Tip|If you set the ''Scaling factor'' to a value above 1.00, the Accessibility menu will be automatically enabled.}}<br />
<br />
Fonts can be set for Window titles, Interface (applications), Documents and Monospace. See the Fonts tab in the Tweak Tool for the relevant options.<br />
<br />
For hinting, RGBA will likely be desired as this fits most monitors types, and if fonts appear too blocked reduce hinting to ''Slight'' or ''None''.<br />
<br />
==== Startup applications ====<br />
<br />
To start certain applications on login, copy the relevant {{ic|.desktop}} file from {{ic|/usr/share/applications/}} to {{ic|~/.config/autostart/}}.<br />
<br />
The {{Pkg|gnome-tweak-tool}} allows managing autostart-entries.<br />
<br />
{{Tip|If the plus sign button in the Tweak Tool's Startup Applications section is unresponsive, try start the Tweak Tool from the terminal using the following command: {{ic|gnome-tweak-tool}}. See the following [https://bbs.archlinux.org/viewtopic.php?pid&#61;1413631#p1413631 forum thread].}}<br />
<br />
{{Note|The deprecated ''gnome-session-properties'' dialog can be added by [[install]]ing the {{AUR|gnome-session-properties}} package.}}<br />
<br />
==== Power ====<br />
<br />
The basic power settings that may want to be altered (these example settings assume the user is using a laptop - change them as desired):<br />
<br />
$ gsettings set org.gnome.settings-daemon.plugins.power button-power ''hibernate''<br />
$ gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-ac-timeout ''3600''<br />
$ gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-ac-type ''hibernate''<br />
$ gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-battery-timeout ''1800''<br />
$ gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-battery-type ''hibernate''<br />
$ gsettings set org.gnome.desktop.lockdown disable-lock-screen ''true''<br />
<br />
To keep a monitor active on lid close: <br />
<br />
$ gsettings set org.gnome.settings-daemon.plugins.xrandr default-monitors-setup do-nothing<br />
<br />
===== Configure behaviour on lid switch close =====<br />
<br />
The GNOME Tweak Tool can optionally ''inhibit'' the ''systemd'' setting for the lid close ACPI event.[http://ftp.gnome.org/pub/GNOME/sources/gnome-tweak-tool/3.17/gnome-tweak-tool-3.17.1.news] To ''inhibit'' the setting, start the Tweak Tool and, under the power tab, check the ''Don't suspend on lid close'' option. This means that the system will do nothing on lid close instead of suspending - the default behaviour. Checking the setting creates {{ic|~/.config/autostart/ignore-lid-switch-tweak.desktop}} which will autostart the Tweak Tool's inhibitor.<br />
<br />
If you do not want the system to suspend or do nothing on lid close, you will need to ensure that the setting described above is '''not''' checked and then configure ''systemd'' with {{ic|1=HandleLidSwitch=''preferred_behaviour''}} as described in [[Power management#ACPI events]].<br />
<br />
===== Change critical battery level action =====<br />
<br />
The settings panel does not provide an option for changing the critical battery level action. These settings have been removed from dconf as well. They are now managed by upower. Edit the upower settings in {{ic|/etc/UPower/UPower.conf}}. Find these settings and adjust to your needs.<br />
<br />
{{hc|head=/etc/UPower/UPower.conf|output=<br />
PercentageLow=10<br />
PercentageCritical=3<br />
PercentageAction=2<br />
CriticalPowerAction=HybridSleep<br />
}}<br />
<br />
==== Sort applications into application (app) folders ====<br />
<br />
{{Tip|The [https://github.com/prurigro/gnome-catgen gnome-catgen] ({{AUR|gnome-catgen-git}}) script allows you to manage folders through the creation of files in {{ic|~/.local/share/applications-categories}} named after each category and containing a list of the desktop files belonging to apps you would like to have inside. Optionally, you can have it cycle through each app without a folder and input the desired category until you ctrl-c or run out of apps.}}<br />
<br />
In the '''dconf-editor''' navigate to {{ic|org.gnome.desktop.app-folders}} and set the value of {{ic|folder-children}} to an array of comma separated folder names:<br />
<br />
['Utilities', 'Sundry']<br />
<br />
Add applications using {{ic|gsettings}}:<br />
<br />
$ gsettings set org.gnome.desktop.app-folders.folder:/org/gnome/desktop/app-folders/folders/Sundry/ apps "['alacarte.desktop', 'dconf-editor.desktop']"<br />
<br />
This adds the applications {{ic|alacarte.desktop}} and {{ic|dconf-editor.desktop}} to the Sundry folder. This will also create the folder {{ic|org.gnome.desktop.app-folders.folders.Sundry}}.<br />
<br />
To name the folder (if it has no name that appears at the top of the applications):<br />
<br />
$ gsettings set org.gnome.desktop.app-folders.folder:/org/gnome/desktop/app-folders/folders/Sundry/ name "Sundry"<br />
<br />
Applications can also be sorted by their category (specified in their ''.desktop'' file):<br />
<br />
$ gsettings set org.gnome.desktop.app-folders.folder:/org/gnome/desktop/app-folders/folders/Sundry/ categories "['Office']"<br />
<br />
If certain applications matching a category are not wanted in a certain folder, exclusions can be set:<br />
<br />
$ gsettings set org.gnome.desktop.app-folders.folder:/org/gnome/desktop/app-folders/folders/Sundry/ excluded-apps "['libreoffice-draw.desktop']"<br />
<br />
For further information, refer to the [https://git.gnome.org/browse/gsettings-desktop-schemas/tree/schemas/org.gnome.desktop.app-folders.gschema.xml.in app-folders schema].<br />
<br />
== See also ==<br />
<br />
* [http://www.gnome.org/ The Official Website of GNOME]<br />
* [https://extensions.gnome.org/ Extensions for GNOME-shell]<br />
* [https://wiki.gnome.org/Projects/GnomeShell/CheatSheet GNOME Shell Cheat Sheet], commands, keyboard shortcuts and other tips for using GNOME Shell.<br />
* Themes, icons, and backgrounds:<br />
** [http://art.gnome.org/ GNOME Art]<br />
** [http://www.gnome-look.org/ GNOME Look]<br />
* GTK/GNOME programs:<br />
** [http://www.gnomefiles.org/ GNOME Files]<br />
** [http://www.gnome.org/projects/ GNOME Project Listing]<br />
* [http://blog.fpmurphy.com/2011/03/customizing-the-gnome-3-shell.html Customizing the GNOME Shell]<br />
* GNOME Source/Mirrors:<br />
** [https://git.gnome.org/browse/ GNOME Git Repository]<br />
** [https://github.com/GNOME GNOME Github Mirror]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=Talk:QEMU&diff=446847Talk:QEMU2016-08-17T07:13:32Z<p>Alive4ever: udisksctl for loop device manipulation</p>
<hr />
<div>== Linear RAID ==<br />
<br />
When I was updating the article yesterday, I had tried to fit the section about linear raid (boot a VM from a partition by prepending a MBR to it) into the article better. But I'm not sure the technique described is the right one at all. It looks like it works, but wouldn't it be easier to install a bootloader directly to the partition (e.g. syslinux)? Then the VM could be booted directly from the partition simply by using it as its virtual disk.<br />
--[[User:Synchronicity|Synchronicity]] ([[User talk:Synchronicity|talk]]) 19:23, 9 May 2012 (UTC)<br />
<br />
== Creating bridge manually ==<br />
<br />
I really don't know what to do with this section. I'd say it has been superseded by [[QEMU#Creating bridge using qemu-bridge-helper]] (available since qemu-1.1, we now have qemu-1.5) - or is someone still using this method? Perhaps link to https://en.wikibooks.org/wiki/QEMU/Networking#TAP_interfaces or http://wiki.qemu.org/Documentation/Networking/NAT is sufficient. What do you think? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:42, 22 July 2013 (UTC)<br />
<br />
:Actually, I've become a happy user of this method. I've written some scripts to easily create bridge interface, TAP interface, and combined with Xyne's [http://xyne.archlinux.ca/notes/network/dhcp_with_dns.html excellent scripts] to set up NAT and launch DHCP server, I have complete solution to easily manage multiple VMs on one (or even more) bridge.<br />
:My scripts are available on github: [https://github.com/lahwaacz/archlinux-dotfiles/blob/master/Scripts/qemu-launcher.sh], [https://github.com/lahwaacz/archlinux-dotfiles/blob/master/Scripts/qemu-tap-helper.sh], [https://github.com/lahwaacz/archlinux-dotfiles/blob/master/Scripts/qemu-mac-hasher.py] but I won't probably integrate them into the wiki, I'l just leave a note when I do some more testing.<br />
:The thing is, what to do with the current content? Personally I think that links to [https://en.wikibooks.org/wiki/QEMU/Networking#TAP_interfaces], [http://wiki.qemu.org/Documentation/Networking/NAT] and my scripts are sufficient (of course others are welcome). I'd also leave the note at the end to ''disable the firewall on the bridge'', I find it extremely useful.<br />
:-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:24, 5 September 2013 (UTC)<br />
<br />
:I would not remove something that works still heh.--[[User:Webdawg|Webdawg]] ([[User talk:Webdawg|talk]]) 07:31, 17 July 2016 (UTC)<br />
<br />
== Starting QEMU virtual machines with systemd ==<br />
The custom systemd service script does not work. It always fails with {{ic|Failed at step EXEC spawning /usr/bin/qemu-{type}: No such file or directory}}. To Fix this modify the ExecStart command {{bc|1=ExecStart=/usr/bin/sh -c "/usr/bin/qemu-${type} -name %i -nographic ${args}"}}<br />
Also {{ic|echo 'system_powerdown' &#124; nc localhost 7101}} kills the VM immediatly. To fix this change the stop script. It simply checks each second if the main process is still running. {{bc|1=ExecStop=/usr/bin/sh -c "${haltcmd} && while [[ $(pidof qemu-${type} | grep $MAINPID) ]]; do sleep 1; done"}}<br />
{{ic|gnu-netcat}} does not work to connect to the monitor. You need to use {{ic|openbsd-netcat}}. -- [[User:Ant32|Ant32]] ([[User talk:Ant32|talk]]) 17:48, 5 September 2013 (UTC)<br />
<br />
:The first problem related to starting the service seems rather strange - didn't you have typo error in your local {{ic|qemu@.service}} file (missing the dollar sign {{ic|$}} in {{ic|${type} }})?<br />
:The second problem is valid, systemd kills the main process when the ExecStop command exits (see {{ic|systemd.service(5)}}). If your workaround really works, it could be added to the wiki with a proper description.<br />
:-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:17, 7 September 2013 (UTC)<br />
<br />
::Relevant thread on systemd-devel mailing list: [http://lists.freedesktop.org/archives/systemd-devel/2013-September/012982.html] -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 00:00, 15 September 2013 (UTC)<br />
<br />
== Kexec Hackery When Using a Real Partition ==<br />
<br />
After banging my head against a wall long enough and figuring out what {{ic|-kernel}} and {{ic|-initrd}} were really calling, I put a note above the appropriate section and mentioned two ways to use the guest's images. (Otherwise, you'll have to worry if the host and guest images match.) The first -- mount the partition(s) -- is more appropriate for "low-volume-handling" of VMs. The second -- using kexec -- becomes more useful when you're juggling more than a few VMs.<br />
<br />
I'm only mentioning this hack because (as of now) [[Kexec]] only mentions use for rebooting into another kernel, not switching out the kernel before the system is even up. This hack comes from from https://digitalocean.uservoice.com/forums/136585-digitalocean/suggestions/2814988-give-option-to-use-the-droplet-s-own-bootloader- which has two suggestions. The most recent, using systemd units by jkuan, doesn't work because jkuan tried to copy a {{ic|.target}} file into a {{ic|.service}} file and systemd wants {{ic|ExecStart}} in a {{ic|.service}} file. The second one, replacing {{ic|/usr/bin/init}} by andrew_sparks, works for me on my Arch instance at DigitalOcean.<br />
<br />
Adaptation from said post:<br />
<br />
# pacman -S kexec-tools<br />
# pacman -R systemd-sysvcompat<br />
<br />
{{hc|1=/tmp/init|2=<br />
#!/bin/sh<br />
<br />
kexec --load /boot/vmlinuz-linux --initrd=/boot/initramfs-linux.img --append="root=/dev/sda init=/usr/lib/systemd/systemd" &&<br />
mount -o ro,remount / && kexec -e<br />
exec /usr/lib/systemd/systemd<br />
}}<br />
<br />
# cd [/path/to/vm]/usr/bin<br />
# mv init init.dist<br />
# cp /tmp/init ./<br />
# chmod 755 init<br />
<br />
I'm leaving this on the Talk page as I haven't even tried it out in QEMU myself. Also, my eyes are about ready to pop out of my head, so I'm barring myself from figuring out the appropriate way to edit this in for the time being. [[User:BrainwreckedTech|BrainwreckedTech]] ([[User talk:BrainwreckedTech|talk]]) 21:23, 14 January 2014 (UTC)<br />
<br />
== Replace -net with -netdev ==<br />
<br />
The {{ic|-net}} option is deprecated and replaced by {{ic|-netdev}}. I think this article should be modified to reflect that.<br />
http://en.wikibooks.org/wiki/QEMU/Networking#cite_ref-1<br />
[[User:Axper|axper]] ([[User talk:Axper|talk]]) 18:12, 1 July 2014 (UTC)<br />
<br />
== I'm rewriting the network section ==<br />
<br />
https://wiki.archlinux.org/index.php/User:Axper/sandbox/qemu_network<br />
[[User:Axper|axper]] ([[User talk:Axper|talk]]) 20:07, 2 July 2014 (UTC)<br />
<br />
::I think a lot of networking topics could be moved outside of the QEMU page. Many virtualization applications share the same basic principles with regards to networking, such as tun/tap creating, bridges, VDE, etc. There are a few networking schemes that are QEMU-specific, for example multicast sockets and {{ic|-net socket,...}}, and these could be mentioned on the QEMU page, although these are less reliable and rarely used in comparison to tap devices. We should also of course note the QEMU-specific command line options in the QEMU page, but for general concepts and commands independent of the virtualization applications, they could go on pages dedicated to the task. The best example is VDE, which is in no way limited to QEMU, yet it still doesn't have its own page on the Arch wiki.<br />
<br />
::Incidentally, I'm planning on rewriting [[User Mode Linux]] (yes, I promise I will get around to it), which happens to share the "tap with bridge" and VDE concepts with QEMU. It would be nice if I could link to pages dedicated to those topics and only write UML-specific commands in the page, instead of duplicating a bunch of general information. I'm not familiar very familiar with Xen or LXC or Docker or the like, but I would suspect that they also share some networking infrastructure. We could possibly even create a category just for these types of pages, for example "Virtual Networking" or "Advanced Networking". [[User:EscapedNull|EscapedNull]] ([[User talk:EscapedNull|talk]]) 13:32, 19 February 2015 (UTC)<br />
<br />
== -enable-kvm vs -machine type=pc,accel=kvm ==<br />
<br />
The section [[QEMU#Enabling_KVM]] recommends {{ic|-enable-kvm}}, while [[QEMU#Virtual_machine_runs_too_slowly]] recommends {{ic|1=-machine type=pc,accel=kvm}}. Is there any difference between the two? Is one preferred over the other? Should we just link to the former section from the latter (and possibly move both command line switches to the same section)? [[User:EscapedNull|EscapedNull]] ([[User talk:EscapedNull|talk]]) 17:23, 18 January 2015 (UTC)<br />
<br />
== virtio-gpu ==<br />
<br />
Any tutorial on using the new virtio-gpu which is introduced in qemu-2.4 and kernel 4.2? [[User:Adam900710|Adam900710]] ([[User talk:Adam900710|talk]]) 02:44, 19 August 2015 (UTC)<br />
<br />
== host only networking ==<br />
<br />
I added a quick and easy method but it was deleted. I found errors in what is here. Is it worth my time to correct them or will they be deleted? {{unsigned|16:39, 4 January 2016|Netskink}}<br />
<br />
:You are welcome to make any corrections. Nobody can tell you if they will be kept or reverted beforehand, but if you're afraid to waste your time feel free to just point them out using an [[Help:Template|Article status templates|article status template]] (should be less time consuming). -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 22:28, 21 February 2016 (UTC)<br />
<br />
== <s>Qemu-bridge-helper broken QENU 2.5.0-1</s> ==<br />
<br />
/etc/qemu/bridge.conf.sample does not exist, therefore the wiki entry is impossible to follow.<br />
<br />
I have tried to find this file on the internet with no sucess.<br />
<br />
--[[User:DontPanic|DontPanic]] ([[User talk:DontPanic|talk]]) 18:34, 5 April 2016 (UTC)<br />
<br />
:This appears to be {{Bug|46791}}. – [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 00:58, 7 April 2016 (UTC)<br />
<br />
::The sample file was removed deliberately from the package in [https://git.archlinux.org/svntogit/packages.git/commit/trunk?h=packages/qemu&id=c5ecbacc08a113fbdc54a0e25babb391f36cd6db] and the wiki has been updated, closing. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:35, 4 June 2016 (UTC)<br />
<br />
== Windows 7 specific issues ==<br />
<br />
I have noticed that for me, any attempts at installing Windows 7 using qemu with virt-manager as a frontend stalls on "Starting Windows." This is immediately after booting the computer for the first time. In Virt-manager, I am able to change the Display from QXL to Cirrus to fix the issue. I'm not sure if this applies to this page in particular, but if so, might be worth adding to the "Troubleshooting" section -- [[User:Ephreal|Ephreal]] ([[User talk:Ephreal|talk]]) 14:25, 10 August 2016 (UTC)<br />
<br />
== Loop setup using udisksctl ==<br />
<br />
Udisksctl is a handy tool to setup loop device. I put an additional section on mounting raw disk image using udisksctl. I know there is a link pointing to setting up udisks for loopback iso, but it's aimed at unpartitioned read only loop device, which doesn't need to be released. In contrast to iso device, raw disk image is writable. I've added udisksctl command to release the loop device to prevent disk image corruption. -- <br />
[[User:Alive4ever|Alive4ever]] ([[User talk:Alive4ever|talk]]) 07:13, 17 August 2016 (UTC)</div>Alive4everhttps://wiki.archlinux.org/index.php?title=QEMU&diff=446846QEMU2016-08-17T07:03:13Z<p>Alive4ever: /* Mounting a partition inside a raw disk image */ using udisks2 to simplify loop device setup.</p>
<hr />
<div>[[Category:Emulators]]<br />
[[Category:Hypervisors]]<br />
[[de:Qemu]]<br />
[[es:QEMU]]<br />
[[fr:Qemu]]<br />
[[ja:QEMU]]<br />
[[zh-CN:QEMU]]<br />
[[zh-TW:QEMU]]<br />
{{Related articles start}}<br />
{{Related|:Category:Hypervisors}}<br />
{{Related|Libvirt}}<br />
{{Related articles end}}<br />
<br />
According to the [http://wiki.qemu.org/Main_Page QEMU about page], "QEMU is a generic and open source machine emulator and virtualizer."<br />
<br />
When used as a machine emulator, QEMU can run OSes and programs made for one machine (e.g. an ARM board) on a different machine (e.g. your x86 PC). By using dynamic translation, it achieves very good performance.<br />
<br />
QEMU can use other hypervisors like [[Xen]] or [[KVM]] to use CPU extensions ([[Wikipedia:Hardware-assisted virtualization|HVM]]) for virtualization. When used as a virtualizer, QEMU achieves near native performances by executing the guest code directly on the host CPU.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|qemu}} package and below optional packages for your needs:<br />
<br />
* {{Pkg|qemu-arch-extra}} - extra architectures support<br />
* {{Pkg|qemu-block-gluster}} - glusterfs block support<br />
* {{Pkg|qemu-block-iscsi}} - iSCSI block support<br />
* {{Pkg|qemu-block-rbd}} - RBD block support <br />
* {{Pkg|samba}} - SMB/CIFS server support <br />
<br />
== Graphical front-ends for QEMU ==<br />
<br />
Unlike other virtualization programs such as [[VirtualBox]] and [[VMware]], QEMU does not provide a GUI to manage virtual machines (other than the window that appears when running a virtual machine), nor does it provide a way to create persistent virtual machines with saved settings. All parameters to run a virtual machine must be specified on the command line at every launch, unless you have created a custom script to start your virtual machine(s). However, there are several GUI front-ends for QEMU:<br />
<br />
* {{Pkg|qemu-launcher}}<br />
* {{Pkg|qtemu}}<br />
* {{AUR|aqemu}}<br />
<br />
Additional front-ends with QEMU support are available for [[libvirt]].<br />
<br />
== Creating new virtualized system ==<br />
<br />
=== Creating a hard disk image ===<br />
<br />
{{Tip|See the [https://en.wikibooks.org/wiki/QEMU/Images QEMU Wikibook] for more information on QEMU images.}}<br />
<br />
To run QEMU you will need a hard disk image, unless you are booting a live system from CD-ROM or the network (and not doing so to install an operating system to a hard disk image). A hard disk image is a file which stores the contents of the emulated hard disk.<br />
<br />
A hard disk image can be ''raw'', so that it is literally byte-by-byte the same as what the guest sees, and will always use the full capacity of the guest hard drive on the host. This method provides the least I/O overhead, but can waste a lot of space, as not-used space on the guest cannot be used on the host.<br />
<br />
Alternatively, the hard disk image can be in a format such as ''qcow2'' which only allocates space to the image file when the guest operating system actually writes to those sectors on its virtual hard disk. The image appears as the full size to the guest operating system, even though it may take up only a very small amount of space on the host system. Using this format instead of ''raw'' will likely affect performance.<br />
<br />
QEMU provides the {{ic|qemu-img}} command to create hard disk images. For example to create a 4 GB image in the ''raw'' format:<br />
<br />
$ qemu-img create -f raw ''image_file'' 4G<br />
<br />
You may use {{ic|-f qcow2}} to create a ''qcow2'' disk instead.<br />
<br />
{{Note|You can also simply create a ''raw'' image by creating a file of the needed size using {{ic|dd}} or {{ic|fallocate}}.}}<br />
<br />
{{Warning|If you store the hard disk images on a [[Btrfs]] file system, you should consider disabling [[Btrfs#Copy-On-Write_.28CoW.29|Copy-on-Write]] for the directory before creating any images.}}<br />
<br />
==== Overlay storage images ====<br />
<br />
You can create a storage image once (the 'backing' image) and have QEMU keep mutations to this image in an overlay image. This allows you to revert to a previous state of this storage image. You could revert by creating a new overlay image at the time you wish to revert, based on the original backing image.<br />
<br />
To create an overlay image, issue a command like:<br />
<br />
$ qemu-img create -o backing_file=''img1.raw'',backing_fmt=''raw'' -f ''qcow2'' ''img1.cow''<br />
<br />
After that you can run your QEMU VM as usual (see [[#Running virtualized system]]):<br />
<br />
$ qemu-system-i386 ''img1.cow''<br />
<br />
The backing image will then be left intact and mutations to this storage will be recorded in the overlay image file.<br />
<br />
When the path to the backing image changes, repair is required.<br />
<br />
{{Warning|The backing image's absolute filesystem path is stored in the (binary) overlay image file. Changing the backing image's path requires some effort.}}<br />
<br />
Make sure that the original backing image's path still leads to this image. If necessary, make a symbolic link at the original path to the new path. Then issue a command like:<br />
<br />
$ qemu-img rebase -b ''/new/img1.raw'' ''/new/img1.cow''<br />
<br />
At your discretion, you may alternatively perform an 'unsafe' rebase where the old path to the backing image is not checked:<br />
<br />
$ qemu-img rebase -u -b ''/new/img1.raw'' ''/new/img1.cow''<br />
<br />
==== Resizing an image ====<br />
<br />
{{Warning|Resizing an image containing an NTFS boot file system could make the operating system installed on it unbootable. For full explanation and workaround see [http://tjworld.net/wiki/Howto/ResizeQemuDiskImages].}}<br />
<br />
The {{ic|qemu-img}} executable has the {{ic|resize}} option, which enables easy resizing of a hard drive image. It works for both ''raw'' and ''qcow2''. For example, to increase image space by 10 GB, run:<br />
<br />
$ qemu-img resize ''disk_image'' +10G<br />
<br />
After enlarging the disk image, you must use file system and partitioning tools inside the virtual machine to actually begin using the new space. When shrinking a disk image, you must '''first reduce the allocated file systems and partition sizes''' using the file system and partitioning tools inside the virtual machine and then shrink the disk image accordingly, otherwise shrinking the disk image will result in data loss!<br />
<br />
=== Preparing the installation media ===<br />
<br />
To install an operating system into your disk image, you need the installation medium (e.g. optical disk, USB-drive, or ISO image) for the operating system. The installation medium should not be mounted because QEMU accesses the media directly.<br />
<br />
{{Tip|If using an optical disk, it is a good idea to first dump the media to a file because this both improves performance and does not require you to have direct access to the devices (that is, you can run QEMU as a regular user without having to change access permissions on the media's device file). For example, if the CD-ROM device node is named {{ic|/dev/cdrom}}, you can dump it to a file with the command: {{bc|1=$ dd if=/dev/cdrom of=''cd_image.iso''}}}}<br />
<br />
=== Installing the operating system===<br />
<br />
This is the first time you will need to start the emulator. To install the operating system on the disk image, you must attach both the disk image and the installation media to the virtual machine, and have it boot from the installation media.<br />
<br />
For example on i386 guests, to install from a bootable ISO file as CD-ROM and a raw disk image:<br />
<br />
$ qemu-system-i386 -cdrom ''iso_image'' -boot order=d -drive file=''disk_image'',format=raw<br />
<br />
See {{ic|qemu(1)}} for more information about loading other media types (such as floppy, disk images or physical drives) and [[#Running virtualized system]] for other useful options.<br />
<br />
After the operating system has finished installing, the QEMU image can be booted directly (see [[#Running virtualized system]]).<br />
<br />
{{Warning|By default only 128 MB of memory is assigned to the machine. The amount of memory can be adjusted with the {{ic|-m}} switch, for example {{ic|-m 512M}} or {{ic|-m 2G}}.}}<br />
<br />
{{Tip|<br />
* Instead of specifying {{ic|1=-boot order=x}}, some users may feel more comfortable using a boot menu: {{ic|1=-boot menu=on}}, at least during configuration and experimentation.<br />
* If you need to replace floppies or CDs as part of the installation process, you can use the QEMU machine monitor (press {{ic|Ctrl+Alt+2}} in the virtual machine's window) to remove and attach storage devices to a virtual machine. Type {{ic|info block}} to see the block devices, and use the {{ic|change}} command to swap out a device. Press {{ic|Ctrl+Alt+1}} to go back to the virtual machine.}}<br />
<br />
== Running virtualized system ==<br />
<br />
{{ic|qemu-system-*}} binaries (for example {{ic|qemu-system-i386}} or {{ic|qemu-system-x86_64}}, depending on guest's architecture) are used to run the virtualized guest. The usage is:<br />
<br />
$ qemu-system-i386 ''options'' ''disk_image''<br />
<br />
Options are the same for all {{ic|qemu-system-*}} binaries, see {{ic|qemu(1)}} for documentation of all options.<br />
<br />
By default, QEMU will show the virtual machine's video output in a window. One thing to keep in mind: when you click inside the QEMU window, the mouse pointer is grabbed. To release it, press {{ic|Ctrl+Alt+g}}.<br />
<br />
{{Warning|QEMU should never be run as root. If you must launch it in a script as root, you should use the {{ic|-runas}} option to make QEMU drop root privileges.}}<br />
<br />
=== Enabling KVM ===<br />
<br />
KVM must be supported by your processor and kernel, and necessary [[kernel modules]] must be loaded. See [[KVM]] for more information.<br />
<br />
To start QEMU in KVM mode, append {{ic|-enable-kvm}} to the additional start options. To check if KVM is enabled for a running VM, enter the QEMU [https://en.wikibooks.org/wiki/QEMU/Monitor Monitor] using {{ic|Ctrl+Alt+Shift+2}}, and type {{ic|info kvm}}.<br />
<br />
{{Note|<br />
* If you start your VM with a GUI tool and experience very bad performance, you should check for proper KVM support, as QEMU may be falling back to software emulation.<br />
* KVM needs to be enabled in order to start Windows 7 and Windows 8 properly without a ''blue screen''.<br />
}}<br />
<br />
=== Enabling IOMMU (Intel VT-d/AMD-Vi) support ===<br />
Using IOMMU opens to features like PCI passthrough and memory protection from faulty or malicious devices, see [[wikipedia:Input-output memory management unit#Advantages]] and [https://www.quora.com/Memory-Management-computer-programming/Could-you-explain-IOMMU-in-plain-English Memory Management (computer programming): Could you explain IOMMU in plain English?].<br />
<br />
To enable IOMMU:<br />
#Ensure that AMD-Vi/Intel VT-d is supported by the CPU and is enabled in the BIOS settings.<br />
#Add {{ic|1=intel_iommu=on}} if you have an Intel CPU or {{ic|1=amd_iommu=on}} if you have an AMD CPU, to the [[kernel parameters]].<br />
#Reboot and ensure IOMMU is enabled by checking {{ic|dmesg}} for {{ic|DMAR}}: {{ic|[0.000000] DMAR: IOMMU enabled}}<br />
#Add {{ic|1=iommu=on}} or {{ic|1=q35,iommu=on}} depending on the {{ic|-machine}}, as ''option''.<br />
<br />
== Moving data between host and guest OS ==<br />
<br />
=== Network ===<br />
<br />
Data can be shared between the host and guest OS using any network protocol that can transfer files, such as [[NFS]], [[SMB]], [[Wikipedia:Network Block Device|NBD]], HTTP, [[Very Secure FTP Daemon|FTP]], or [[SSH]], provided that you have set up the network appropriately and enabled the appropriate services.<br />
<br />
The default user-mode networking allows the guest to access the host OS at the IP address 10.0.2.2. Any servers that you are running on your host OS, such as a SSH server or SMB server, will be accessible at this IP address. So on the guests, you can mount directories exported on the host via [[SMB]] or [[NFS]], or you can access the host's HTTP server, etc.<br />
It will not be possible for the host OS to access servers running on the guest OS, but this can be done with other network configurations (see [[#Tap networking with QEMU]]).<br />
<br />
=== QEMU's built-in SMB server ===<br />
<br />
QEMU's documentation says it has a "built-in" SMB server, but actually it just starts up [[Samba]] with an automatically generated {{ic|smb.conf}} file located at {{ic|/tmp/qemu-smb.''pid''-0/smb.conf}} and makes it accessible to the guest at a different IP address (10.0.2.4 by default). This only works for user networking, and this is not necessarily very useful since the guest can also access the normal [[Samba]] service on the host if you have set up shares on it.<br />
<br />
To enable this feature, start QEMU with a command like:<br />
<br />
$ qemu-system-i386 ''disk_image'' -net nic -net user,smb=''shared_dir_path''<br />
<br />
where {{ic|''shared_dir_path''}} is a directory that you want to share between the guest and host.<br />
<br />
Then, in the guest, you will be able to access the shared directory on the host 10.0.2.4 with the share name "qemu". For example, in Windows Explorer you would go to {{ic|\\10.0.2.4\qemu}}.<br />
<br />
{{Note|<br />
* If you are using sharing options multiple times like {{ic|1=-net user,smb=''shared_dir_path1'' -net user,smb=''shared_dir_path2''}} or {{ic|1=-net user,smb=''shared_dir_path1'',smb=''shared_dir_path2''}} then it will share only the last defined one.<br />
* If you cannot access the shared folder and the guest system is Windows, check that the [http://ecross.mvps.org/howto/enable-netbios-over-tcp-ip-with-windows.htm NetBIOS protocol is enabled] and that a firewall does not block [http://technet.microsoft.com/en-us/library/cc940063.aspx ports] used by the NetBIOS protocol.<br />
}}<br />
<br />
=== Mounting a partition inside a raw disk image ===<br />
<br />
When the virtual machine is not running, it is possible to mount partitions that are inside a raw disk image file by setting them up as loopback devices. This does not work with disk images in special formats, such as qcow2, although those can be mounted using {{ic|qemu-nbd}}.<br />
<br />
{{Warning|You must make sure to unmount the partitions before running the virtual machine again. Otherwise, data corruption is very likely to occur.}}<br />
<br />
==== With manually specifying byte offset ====<br />
<br />
One way to mount a disk image partition is to mount the disk image at a certain offset using a command like the following:<br />
<br />
# mount -o loop,offset=32256 ''disk_image'' ''mountpoint''<br />
<br />
The {{ic|1=offset=32256}} option is actually passed to the {{ic|losetup}} program to set up a loopback device that starts at byte offset 32256 of the file and continues to the end. This loopback device is then mounted. You may also use the {{ic|sizelimit}} option to specify the exact size of the partition, but this is usually unnecessary.<br />
<br />
Depending on your disk image, the needed partition may not start at offset 32256. Run {{ic|fdisk -l ''disk_image''}} to see the partitions in the image. fdisk gives the start and end offsets in 512-byte sectors, so multiply by 512 to get the correct offset to pass to {{ic|mount}}.<br />
<br />
==== With loop module autodetecting partitions ====<br />
<br />
The Linux loop driver actually supports partitions in loopback devices, but it is disabled by default. To enable it, do the following:<br />
<br />
* Get rid of all your loopback devices (unmount all mounted images, etc.).<br />
* [[Kernel_modules#Manual_module_handling|Unload]] the {{ic|loop}} kernel module, and load it with the {{ic|1=max_part=15}} parameter set. Additionally, the maximum number of loop devices can be controlled with the {{ic|max_loop}} parameter.<br />
<br />
{{Tip|You can put an entry in {{ic|/etc/modprobe.d}} to load the loop module with {{ic|1=max_part=15}} every time, or you can put {{ic|1=loop.max_part=15}} on the kernel command-line, depending on whether you have the {{ic|loop.ko}} module built into your kernel or not.}}<br />
<br />
Set up your image as a loopback device:<br />
<br />
# losetup -f -P ''disk_image''<br />
<br />
Then, if the device created was {{ic|/dev/loop0}}, additional devices {{ic|/dev/loop0pX}} will have been automatically created, where X is the number of the partition. These partition loopback devices can be mounted directly. For example:<br />
<br />
# mount /dev/loop0p1 ''mountpoint''<br />
<br />
See also [[Udisks#Mount_an_ISO_image]].<br />
<br />
==== With kpartx ====<br />
<br />
'''kpartx''' from the {{AUR|multipath-tools}} package can read a partition table on a device and create a new device for each partition. For example:<br />
# kpartx -a ''disk_image''<br />
<br />
This will setup the loopback device and create the necessary partition(s) device(s) in {{ic|/dev/mapper/}}.<br />
<br />
==== With udisksctl ====<br />
<br />
{{ic|udisksctl}} from {{Pkg|udisks2}} can be used to setup loop device. It will detect available partitions automatically. To setup loop device, issue this command.<br />
<br />
$ udisksctl loop-setup -f ''disk_image''<br />
<br />
To release the loop device, issue this command. Make sure to substitute {{ic|/dev/loop0}} with correct loop device.<br />
<br />
$ udisksctl loop-delete -b ''/dev/loop0''<br />
<br />
=== Mounting a partition inside a qcow2 image ===<br />
<br />
You may mount a partition inside a qcow2 image using {{ic|qemu-nbd}}. See [http://en.wikibooks.org/wiki/QEMU/Images#Mounting_an_image_on_the_host Wikibooks].<br />
<br />
=== Using any real partition as the single primary partition of a hard disk image ===<br />
<br />
Sometimes, you may wish to use one of your system partitions from within QEMU. Using a raw partition for a virtual machine will improve performance, as the read and write operations do not go through the file system layer on the physical host. Such a partition also provides a way to share data between the host and guest.<br />
<br />
In Arch Linux, device files for raw partitions are, by default, owned by ''root'' and the ''disk'' group. If you would like to have a non-root user be able to read and write to a raw partition, you need to change the owner of the partition's device file to that user.<br />
<br />
{{Warning|<br />
* Although it is possible, it is not recommended to allow virtual machines to alter critical data on the host system, such as the root partition.<br />
* You must not mount a file system on a partition read-write on both the host and the guest at the same time. Otherwise, data corruption will result.<br />
}}<br />
<br />
After doing so, you can attach the partition to a QEMU virtual machine as a virtual disk.<br />
<br />
However, things are a little more complicated if you want to have the ''entire'' virtual machine contained in a partition. In that case, there would be no disk image file to actually boot the virtual machine since you cannot install a bootloader to a partition that is itself formatted as a file system and not as a partitioned device with a MBR. Such a virtual machine can be booted either by specifying the [[kernel]] and [[initramfs|initrd]] manually, or by simulating a disk with a MBR by using linear [[RAID]].<br />
<br />
==== By specifying kernel and initrd manually ====<br />
<br />
QEMU supports loading [[Kernels|Linux kernels]] and [[initramfs|init ramdisks]] directly, thereby circumventing bootloaders such as [[GRUB]]. It then can be launched with the physical partition containing the root file system as the virtual disk, which will not appear to be partitioned. This is done by issuing a command similar to the following:<br />
<br />
{{Note|In this example, it is the '''host's''' images that are being used, not the guest's. If you wish to use the guest's images, either mount {{ic|/dev/sda3}} read-only (to protect the file system from the host) and specify the {{ic|/full/path/to/images}} or use some kexec hackery in the guest to reload the guest's kernel (extends boot time). }}<br />
<br />
$ qemu-system-i386 -kernel /boot/vmlinuz-linux -initrd /boot/initramfs-linux.img -append root=/dev/sda /dev/sda3<br />
<br />
In the above example, the physical partition being used for the guest's root file system is {{ic|/dev/sda3}} on the host, but it shows up as {{ic|/dev/sda}} on the guest.<br />
<br />
You may, of course, specify any kernel and initrd that you want, and not just the ones that come with Arch Linux.<br />
<br />
When there are multiple [[kernel parameters]] to be passed to the {{ic|-append}} option, they need to be quoted using single or double quotes. For example:<br />
<br />
... -append 'root=/dev/sda1 console=ttyS0'<br />
<br />
==== Simulate virtual disk with MBR using linear RAID ====<br />
<br />
A more complicated way to have a virtual machine use a physical partition, while keeping that partition formatted as a file system and not just having the guest partition the partition as if it were a disk, is to simulate a MBR for it so that it can boot using a bootloader such as GRUB.<br />
<br />
You can do this using software [[RAID]] in linear mode (you need the {{ic|linear.ko}} kernel driver) and a loopback device: the trick is to dynamically prepend a master boot record (MBR) to the real partition you wish to embed in a QEMU raw disk image.<br />
<br />
Suppose you have a plain, unmounted {{ic|/dev/hdaN}} partition with some file system on it you wish to make part of a QEMU disk image. First, you create some small file to hold the MBR:<br />
<br />
$ dd if=/dev/zero of=''/path/to/mbr'' count=32<br />
<br />
Here, a 16 KB (32 * 512 bytes) file is created. It is important not to make it too small (even if the MBR only needs a single 512 bytes block), since the smaller it will be, the smaller the chunk size of the software RAID device will have to be, which could have an impact on performance. Then, you setup a loopback device to the MBR file:<br />
<br />
# losetup -f ''/path/to/mbr''<br />
<br />
Let us assume the resulting device is {{ic|/dev/loop0}}, because we would not already have been using other loopbacks. Next step is to create the "merged" MBR + {{ic|/dev/hdaN}} disk image using software RAID:<br />
<br />
# modprobe linear<br />
# mdadm --build --verbose /dev/md0 --chunk=16 --level=linear --raid-devices=2 /dev/loop0 /dev/hda''N''<br />
<br />
The resulting {{ic|/dev/md0}} is what you will use as a QEMU raw disk image (do not forget to set the permissions so that the emulator can access it). The last (and somewhat tricky) step is to set the disk configuration (disk geometry and partitions table) so that the primary partition start point in the MBR matches the one of {{ic|/dev/hda''N''}} inside {{ic|/dev/md0}} (an offset of exactly 16 * 512 = 16384 bytes in this example). Do this using {{ic|fdisk}} on the host machine, not in the emulator: the default raw disc detection routine from QEMU often results in non-kilobyte-roundable offsets (such as 31.5 KB, as in the previous section) that cannot be managed by the software RAID code. Hence, from the the host:<br />
<br />
# fdisk /dev/md0<br />
<br />
Press {{ic|X}} to enter the expert menu. Set number of 's'ectors per track so that the size of one cylinder matches the size of your MBR file. For two heads and a sector size of 512, the number of sectors per track should be 16, so we get cylinders of size 2x16x512=16k.<br />
<br />
Now, press {{ic|R}} to return to the main menu.<br />
<br />
Press {{ic|P}} and check that the cylinder size is now 16k.<br />
<br />
Now, create a single primary partition corresponding to {{ic|/dev/hda''N''}}. It should start at cylinder 2 and end at the end of the disk (note that the number of cylinders now differs from what it was when you entered fdisk.<br />
<br />
Finally, 'w'rite the result to the file: you are done. You now have a partition you can mount directly from your host, as well as part of a QEMU disk image:<br />
<br />
$ qemu-system-i386 -hdc /dev/md0 ''[...]''<br />
<br />
You can, of course, safely set any bootloader on this disk image using QEMU, provided the original {{ic|/dev/hda''N''}} partition contains the necessary tools.<br />
<br />
== Networking ==<br />
<br />
{{Poor writing|Network topologies (sections [[#Host-only networking]], [[#Internal networking]] and info spread out across other sections) should not be described alongside the various virtual interfaces implementations, such as [[#User-mode networking]], [[#Tap networking with QEMU]], [[#Networking with VDE2]].}}<br />
<br />
The performance of virtual networking should be better with tap devices and bridges than with user-mode networking or vde because tap devices and bridges are implemented in-kernel.<br />
<br />
In addition, networking performance can be improved by assigning virtual machines a [http://wiki.libvirt.org/page/Virtio virtio] network device rather than the default emulation of an e1000 NIC. See [[#Installing virtio drivers]] for more information.<br />
<br />
=== Link-level address caveat ===<br />
<br />
By giving the {{ic|-net nic}} argument to QEMU, it will, by default, assign a virtual machine a network interface with the link-level address {{ic|52:54:00:12:34:56}}. However, when using bridged networking with multiple virtual machines, it is essential that each virtual machine has a unique link-level (MAC) address on the virtual machine side of the tap device. Otherwise, the bridge will not work correctly, because it will receive packets from multiple sources that have the same link-level address. This problem occurs even if the tap devices themselves have unique link-level addresses because the source link-level address is not rewritten as packets pass through the tap device.<br />
<br />
Make sure that each virtual machine has a unique link-level address, but it should always start with {{ic|52:54:}}. Use the following option, replace ''X'' with arbitrary hexadecimal digit:<br />
<br />
$ qemu-system-i386 -net nic,macaddr=52:54:''XX:XX:XX:XX'' -net vde ''disk_image''<br />
<br />
Generating unique link-level addresses can be done in several ways:<br />
<br />
<ol><br />
<li>Manually specify unique link-level address for each NIC. The benefit is that the DHCP server will assign the same IP address each time the virtual machine is run, but it is unusable for large number of virtual machines.<br />
</li><br />
<li>Generate random link-level address each time the virtual machine is run. Practically zero probability of collisions, but the downside is that the DHCP server will assign a different IP address each time. You can use the following command in a script to generate random link-level address in a {{ic|macaddr}} variable:<br />
<br />
{{bc|1=<br />
printf -v macaddr "52:54:%02x:%02x:%02x:%02x" $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff )) $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff ))<br />
qemu-system-i386 -net nic,macaddr="$macaddr" -net vde ''disk_image''<br />
}}<br />
<br />
</li><br />
<li>Use the following script {{ic|qemu-mac-hasher.py}} to generate the link-level address from the virtual machine name using a hashing function. Given that the names of virtual machines are unique, this method combines the benefits of the aforementioned methods: it generates the same link-level address each time the script is run, yet it preserves the practically zero probability of collisions.<br />
<br />
{{hc|qemu-mac-hasher.py|<nowiki><br />
#!/usr/bin/env python<br />
<br />
import sys<br />
import zlib<br />
<br />
if len(sys.argv) != 2:<br />
print("usage: %s <VM Name>" % sys.argv[0])<br />
sys.exit(1)<br />
<br />
crc = zlib.crc32(sys.argv[1].encode("utf-8")) & 0xffffffff<br />
crc = str(hex(crc))[2:]<br />
print("52:54:%s%s:%s%s:%s%s:%s%s" % tuple(crc))<br />
</nowiki>}}<br />
<br />
In a script, you can use for example:<br />
<br />
vm_name="''VM Name''"<br />
qemu-system-i386 -name "$vm_name" -net nic,macaddr=$(qemu-mac-hasher.py "$vm_name") -net vde ''disk_image''<br />
</li><br />
</ol><br />
<br />
=== User-mode networking ===<br />
<br />
By default, without any {{ic|-netdev}} arguments, QEMU will use user-mode networking with a built-in DHCP server. Your virtual machines will be assigned an IP address when they run their DHCP client, and they will be able to access the physical host's network through IP masquerading done by QEMU.<br />
<br />
{{warning|This only works with the TCP and UDP protocols, so ICMP, including {{ic|ping}}, will not work. Do not use {{ic|ping}} to test network connectivity.}}<br />
<br />
This default configuration allows your virtual machines to easily access the Internet, provided that the host is connected to it, but the virtual machines will not be directly visible on the external network, nor will virtual machines be able to talk to each other if you start up more than one concurrently.<br />
<br />
QEMU's user-mode networking can offer more capabilities such as built-in TFTP or SMB servers, redirecting host ports to the guest (for example to allow SSH connections to the guest) or attaching guests to VLANs so that they can talk to each other. See the QEMU documentation on the {{ic|-net user}} flag for more details.<br />
<br />
However, user-mode networking has limitations in both utility and performance. More advanced network configurations require the use of tap devices or other methods.<br />
<br />
=== Tap networking with QEMU ===<br />
<br />
[[wikipedia:TUN/TAP|Tap devices]] are a Linux kernel feature that allows you to create virtual network interfaces that appear as real network interfaces. Packets sent to a tap interface are delivered to a userspace program, such as QEMU, that has bound itself to the interface.<br />
<br />
QEMU can use tap networking for a virtual machine so that packets sent to the tap interface will be sent to the virtual machine and appear as coming from a network interface (usually an Ethernet interface) in the virtual machine. Conversely, everything that the virtual machine sends through its network interface will appear on the tap interface.<br />
<br />
Tap devices are supported by the Linux bridge drivers, so it is possible to bridge together tap devices with each other and possibly with other host interfaces such as {{ic|eth0}}. This is desirable if you want your virtual machines to be able to talk to each other, or if you want other machines on your LAN to be able to talk to the virtual machines.<br />
<br />
{{Warning|If you bridge together tap device and some host interface, such as {{ic|eth0}}, your virtual machines will appear directly on the external network, which will expose them to possible attack. Depending on what resources your virtual machines have access to, you may need to take all the [[Firewalls|precautions]] you normally would take in securing a computer to secure your virtual machines. If the risk is too great, virtual machines have little resources or you set up multiple virtual machines, a better solution might be to use [[#Host-only networking|host-only networking]] and set up NAT. In this case you only need one firewall on the host instead of multiple firewalls for each guest.}}<br />
<br />
As indicated in the user-mode networking section, tap devices offer higher networking performance than user-mode. If the guest OS supports virtio network driver, then the networking performance will be increased considerably as well. Supposing the use of the tap0 device, that the virtio driver is used on the guest, and that no scripts are used to help start/stop networking, next is part of the qemu command one should see:<br />
<br />
-net nic,model=virtio -net tap,ifname=tap0,script=no,downscript=no<br />
<br />
But if already using a tap device with virtio networking driver, one can even boost the networking performance by enabling vhost, like:<br />
<br />
-net nic,model=virtio -net tap,ifname=tap0,script=no,downscript=no,vhost=on<br />
<br />
See http://www.linux-kvm.com/content/how-maximize-virtio-net-performance-vhost-net for more information.<br />
<br />
==== Host-only networking ====<br />
<br />
If the bridge is given an IP address and traffic destined for it is allowed, but no real interface (e.g. {{ic|eth0}}) is connected to the bridge, then the virtual machines will be able to talk to each other and the host system. However, they will not be able to talk to anything on the external network, provided that you do not set up IP masquerading on the physical host. This configuration is called ''host-only networking'' by other virtualization software such as [[VirtualBox]].<br />
<br />
{{Tip|<br />
* If you want to set up IP masquerading, e.g. NAT for virtual machines, see the [[Internet sharing#Enable NAT]] page.<br />
* You may want to have a DHCP server running on the bridge interface to service the virtual network. For example, to use the {{ic|172.20.0.1/16}} subnet with [[dnsmasq]] as the DHCP server:<br />
# ip addr add 172.20.0.1/16 dev br0<br />
# ip link set br0 up<br />
# dnsmasq --interface&#61;br0 --bind-interfaces --dhcp-range&#61;172.20.0.2,172.20.255.254<br />
}}<br />
<br />
==== Internal networking ====<br />
<br />
If you do not give the bridge an IP address and add an [[iptables]] rule to drop all traffic to the bridge in the INPUT chain, then the virtual machines will be able to talk to each other, but not to the physical host or to the outside network. This configuration is called ''internal networking'' by other virtualization software such as [[VirtualBox]]. You will need to either assign static IP addresses to the virtual machines or run a DHCP server on one of them.<br />
<br />
By default iptables would drop packets in the bridge network. You may need to use such iptables rule to allow packets in a bridged network:<br />
<br />
# iptables -I FORWARD -m physdev --physdev-is-bridged -j ACCEPT<br />
<br />
==== Bridged networking using qemu-bridge-helper ====<br />
<br />
{{Note|This method is available since QEMU 1.1, see http://wiki.qemu.org/Features/HelperNetworking.}}<br />
<br />
This method does not require a start-up script and readily accommodates multiple taps and multiple bridges. It uses {{ic|/usr/lib/qemu/qemu-bridge-helper}} binary, which allows creating tap devices on an existing bridge.<br />
<br />
{{Tip|See [[Network bridge]] for information on creating bridge.}}<br />
<br />
First, create a configuration file containing the names of all bridges to be used by QEMU:<br />
<br />
{{hc|/etc/qemu/bridge.conf|<br />
allow ''bridge0''<br />
allow ''bridge1''<br />
...}}<br />
<br />
Now start the VM. The most basic usage would be:<br />
<br />
$ qemu-system-i386 -net nic -net bridge,br=''bridge0'' ''[...]''<br />
<br />
With multiple taps, the most basic usage requires specifying the VLAN for all additional NICs:<br />
<br />
$ qemu-system-i386 -net nic -net bridge,br=''bridge0'' -net nic,vlan=1 -net bridge,vlan=1,br=''bridge1'' ''[...]''<br />
<br />
==== Creating bridge manually ====<br />
<br />
{{Poor writing|This section needs serious cleanup and may contain out-of-date information.}}<br />
<br />
{{Tip|Since QEMU 1.1, the [http://wiki.qemu.org/Features/HelperNetworking network bridge helper] can set tun/tap up for you without the need for additional scripting. See [[#Bridged networking using qemu-bridge-helper]].}}<br />
<br />
The following describes how to bridge a virtual machine to a host interface such as {{ic|eth0}}, which is probably the most common configuration. This configuration makes it appear that the virtual machine is located directly on the external network, on the same Ethernet segment as the physical host machine.<br />
<br />
We will replace the normal Ethernet adapter with a bridge adapter and bind the normal Ethernet adapter to it.<br />
<br />
* Install {{Pkg|bridge-utils}}, which provides {{ic|brctl}} to manipulate bridges.<br />
<br />
* Enable IPv4 forwarding:<br />
# sysctl net.ipv4.ip_forward=1<br />
<br />
To make the change permanent, change {{ic|1=net.ipv4.ip_forward = 0}} to {{ic|1=net.ipv4.ip_forward = 1}} in {{ic|/etc/sysctl.d/99-sysctl.conf}}.<br />
<br />
* Load the {{ic|tun}} module and configure it to be loaded on boot. See [[Kernel modules]] for details.<br />
<br />
* Now create the bridge. See [[Bridge with netctl]] for details. Remember to name your bridge as {{ic|br0}}, or change the scripts below to your bridge's name.<br />
<br />
* Create the script that QEMU uses to bring up the tap adapter with {{ic|root:kvm}} 750 permissions:<br />
{{hc|/etc/qemu-ifup|<nowiki><br />
#!/bin/sh<br />
<br />
echo "Executing /etc/qemu-ifup"<br />
echo "Bringing up $1 for bridged mode..."<br />
sudo /usr/bin/ip link set $1 up promisc on<br />
echo "Adding $1 to br0..."<br />
sudo /usr/bin/brctl addif br0 $1<br />
sleep 2<br />
</nowiki>}}<br />
<br />
* Create the script that QEMU uses to bring down the tap adapter in {{ic|/etc/qemu-ifdown}} with {{ic|root:kvm}} 750 permissions:<br />
{{hc|/etc/qemu-ifdown|<nowiki><br />
#!/bin/sh<br />
<br />
echo "Executing /etc/qemu-ifdown"<br />
sudo /usr/bin/ip link set $1 down<br />
sudo /usr/bin/brctl delif br0 $1<br />
sudo /usr/bin/ip link delete dev $1<br />
</nowiki>}}<br />
<br />
* Use {{ic|visudo}} to add the following to your {{ic|sudoers}} file:<br />
{{bc|<nowiki><br />
Cmnd_Alias QEMU=/usr/bin/ip,/usr/bin/modprobe,/usr/bin/brctl<br />
%kvm ALL=NOPASSWD: QEMU<br />
</nowiki>}}<br />
<br />
* You launch QEMU using the following {{ic|run-qemu}} script:<br />
{{hc|run-qemu|<nowiki><br />
#!/bin/bash<br />
USERID=$(whoami)<br />
<br />
# Get name of newly created TAP device; see https://bbs.archlinux.org/viewtopic.php?pid=1285079#p1285079<br />
precreationg=$(/usr/bin/ip tuntap list | /usr/bin/cut -d: -f1 | /usr/bin/sort)<br />
sudo /usr/bin/ip tuntap add user $USERID mode tap<br />
postcreation=$(/usr/bin/ip tuntap list | /usr/bin/cut -d: -f1 | /usr/bin/sort)<br />
IFACE=$(comm -13 <(echo "$precreationg") <(echo "$postcreation"))<br />
<br />
# This line creates a random MAC address. The downside is the DHCP server will assign a different IP address each time<br />
printf -v macaddr "52:54:%02x:%02x:%02x:%02x" $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff )) $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff ))<br />
# Instead, uncomment and edit this line to set a static MAC address. The benefit is that the DHCP server will assign the same IP address.<br />
# macaddr='52:54:be:36:42:a9'<br />
<br />
qemu-system-i386 -net nic,macaddr=$macaddr -net tap,ifname="$IFACE" $*<br />
<br />
sudo ip link set dev $IFACE down &> /dev/null<br />
sudo ip tuntap del $IFACE mode tap &> /dev/null<br />
</nowiki>}}<br />
<br />
Then to launch a VM, do something like this<br />
$ run-qemu -hda ''myvm.img'' -m 512 -vga std<br />
<br />
* It is recommended for performance and security reasons to disable the [http://ebtables.netfilter.org/documentation/bridge-nf.html firewall on the bridge]:<br />
{{hc|/etc/sysctl.d/10-disable-firewall-on-bridge.conf|<nowiki><br />
net.bridge.bridge-nf-call-ip6tables = 0<br />
net.bridge.bridge-nf-call-iptables = 0<br />
net.bridge.bridge-nf-call-arptables = 0<br />
</nowiki>}}<br />
Run {{ic|sysctl -p /etc/sysctl.d/10-disable-firewall-on-bridge.conf}} to apply the changes immediately.<br />
<br />
See the [http://wiki.libvirt.org/page/Networking#Creating_network_initscripts libvirt wiki] and [https://bugzilla.redhat.com/show_bug.cgi?id=512206 Fedora bug 512206]. If you get errors by sysctl during boot about non-existing files, make the {{ic|bridge}} module load at boot. See [[Kernel modules#Automatic module handling]].<br />
<br />
Alternatively, you can configure [[iptables]] to allow all traffic to be forwarded across the bridge by adding a rule like this:<br />
-I FORWARD -m physdev --physdev-is-bridged -j ACCEPT<br />
<br />
==== Network sharing between physical device and a Tap device through iptables ====<br />
<br />
{{Merge|Internet_sharing|Duplication, not specific to QEMU.}}<br />
<br />
Bridged networking works fine between a wired interface (Eg. eth0), and it is easy to setup. However if the host gets connected to the network through a wireless device, then bridging is not possible.<br />
<br />
See [[Network bridge#Wireless interface on a bridge]] as a reference.<br />
<br />
One way to overcome that is to setup a tap device with a static IP, making linux automatically handle the routing for it, and then forward traffic between the tap interface and the device connected to the network through iptables rules.<br />
<br />
See [[Internet sharing]] as a reference.<br />
<br />
There you can find what is needed to share the network between devices, included tap and tun ones. The following just hints further on some of the host configurations required. As indicated in the reference above, the client needs to be configured for a static IP, using the IP assigned to the tap interface as the gateway. The caveat is that the DNS servers on the client might need to be manually edited if they change when changing from one host device connected to the network to another.<br />
<br />
To allow IP forwarding on every boot, one need to add the following lines to sysctl configuration file inside /etc/sysctl.d:<br />
<br />
net.ipv4.ip_forward = 1<br />
net.ipv6.conf.default.forwarding = 1<br />
net.ipv6.conf.all.forwarding = 1<br />
<br />
The iptables rules can look like:<br />
<br />
# Forwarding from/to outside<br />
iptables -A FORWARD -i ${INT} -o ${EXT_0} -j ACCEPT<br />
iptables -A FORWARD -i ${INT} -o ${EXT_1} -j ACCEPT<br />
iptables -A FORWARD -i ${INT} -o ${EXT_2} -j ACCEPT<br />
iptables -A FORWARD -i ${EXT_0} -o ${INT} -j ACCEPT<br />
iptables -A FORWARD -i ${EXT_1} -o ${INT} -j ACCEPT<br />
iptables -A FORWARD -i ${EXT_2} -o ${INT} -j ACCEPT<br />
# NAT/Masquerade (network address translation)<br />
iptables -t nat -A POSTROUTING -o ${EXT_0} -j MASQUERADE<br />
iptables -t nat -A POSTROUTING -o ${EXT_1} -j MASQUERADE<br />
iptables -t nat -A POSTROUTING -o ${EXT_2} -j MASQUERADE<br />
<br />
The prior supposes there are 3 devices connected to the network sharing traffic with one internal device, where for example:<br />
<br />
INT=tap0<br />
EXT_0=eth0<br />
EXT_1=wlan0<br />
EXT_2=tun0<br />
<br />
The prior shows a forwarding that would allow sharing wired and wireless connections with the tap device.<br />
<br />
The forwarding rules shown are stateless, and for pure forwarding. One could think of restricting specific traffic, putting a firewall in place to protect the guest and others. However those would decrease the networking performance, while a simple bridge does not include any of that.<br />
<br />
Bonus: Whether the connection is wired or wireless, if one gets connected through VPN to a remote site with a tun device, supposing the tun device opened for that connection is tun0, and the prior iptables rules are applied, then the remote connection gets also shared with the guest. This avoids the need for the guest to also open a VPN connection. Again, as the guest networking needs to be static, then if connecting the host remotely this way, one most probably will need to edit the DNS servers on the guest.<br />
<br />
=== Networking with VDE2 ===<br />
<br />
{{Poor writing|This section needs serious cleanup and may contain out-of-date information.}}<br />
<br />
==== What is VDE? ====<br />
<br />
VDE stands for Virtual Distributed Ethernet. It started as an enhancement of [[User-mode Linux|uml]]_switch. It is a toolbox to manage virtual networks.<br />
<br />
The idea is to create virtual switches, which are basically sockets, and to "plug" both physical and virtual machines in them. The configuration we show here is quite simple; However, VDE is much more powerful than this, it can plug virtual switches together, run them on different hosts and monitor the traffic in the switches. You are invited to read [http://wiki.virtualsquare.org/wiki/index.php/Main_Page the documentation of the project].<br />
<br />
The advantage of this method is you do not have to add sudo privileges to your users. Regular users should not be allowed to run modprobe.<br />
<br />
==== Basics ====<br />
<br />
VDE support can be [[pacman|installed]] via the {{Pkg|vde2}} package in the [[official repositories]].<br />
<br />
In our config, we use tun/tap to create a virtual interface on my host. Load the {{ic|tun}} module (see [[Kernel modules]] for details):<br />
<br />
# modprobe tun<br />
<br />
Now create the virtual switch:<br />
<br />
# vde_switch -tap tap0 -daemon -mod 660 -group users<br />
<br />
This line creates the switch, creates {{ic|tap0}}, "plugs" it, and allows the users of the group {{ic|users}} to use it.<br />
<br />
The interface is plugged in but not configured yet. To configure it, run this command:<br />
<br />
# ip addr add 192.168.100.254/24 dev tap0<br />
<br />
Now, you just have to run KVM with these {{ic|-net}} options as a normal user:<br />
<br />
$ qemu-system-i386 -net nic -net vde -hda ''[...]''<br />
<br />
Configure networking for your guest as you would do in a physical network.<br />
<br />
{{Tip|You might want to set up NAT on tap device to access the internet from the virtual machine. See [[Internet sharing#Enable NAT]] for more information.}}<br />
<br />
==== Startup scripts ====<br />
<br />
Example of main script starting VDE:<br />
<br />
{{hc|/etc/systemd/scripts/qemu-network-env|<nowiki><br />
#!/bin/sh<br />
# QEMU/VDE network environment preparation script<br />
<br />
# The IP configuration for the tap device that will be used for<br />
# the virtual machine network:<br />
<br />
TAP_DEV=tap0<br />
TAP_IP=192.168.100.254<br />
TAP_MASK=24<br />
TAP_NETWORK=192.168.100.0<br />
<br />
# Host interface<br />
NIC=eth0<br />
<br />
case "$1" in<br />
start)<br />
echo -n "Starting VDE network for QEMU: "<br />
<br />
# If you want tun kernel module to be loaded by script uncomment here<br />
#modprobe tun 2>/dev/null<br />
## Wait for the module to be loaded<br />
#while ! lsmod | grep -q "^tun"; do echo "Waiting for tun device"; sleep 1; done<br />
<br />
# Start tap switch<br />
vde_switch -tap "$TAP_DEV" -daemon -mod 660 -group users<br />
<br />
# Bring tap interface up<br />
ip address add "$TAP_IP"/"$TAP_MASK" dev "$TAP_DEV"<br />
ip link set "$TAP_DEV" up<br />
<br />
# Start IP Forwarding<br />
echo "1" > /proc/sys/net/ipv4/ip_forward<br />
iptables -t nat -A POSTROUTING -s "$TAP_NETWORK"/"$TAP_MASK" -o "$NIC" -j MASQUERADE<br />
;;<br />
stop)<br />
echo -n "Stopping VDE network for QEMU: "<br />
# Delete the NAT rules<br />
iptables -t nat -D POSTROUTING "$TAP_NETWORK"/"$TAP_MASK" -o "$NIC" -j MASQUERADE<br />
<br />
# Bring tap interface down<br />
ip link set "$TAP_DEV" down<br />
<br />
# Kill VDE switch<br />
pgrep -f vde_switch | xargs kill -TERM<br />
;;<br />
restart|reload)<br />
$0 stop<br />
sleep 1<br />
$0 start<br />
;;<br />
*)<br />
echo "Usage: $0 {start|stop|restart|reload}"<br />
exit 1<br />
esac<br />
exit 0<br />
</nowiki>}}<br />
<br />
Example of systemd service using the above script:<br />
<br />
{{hc|/etc/systemd/system/qemu-network-env.service|<nowiki><br />
[Unit]<br />
Description=Manage VDE Switch<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/etc/systemd/scripts/qemu-network-env start<br />
ExecStop=/etc/systemd/scripts/qemu-network-env stop<br />
RemainAfterExit=yes<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
Change permissions for {{ic|qemu-network-env}} to be executable<br />
<br />
# chmod u+x /etc/systemd/scripts/qemu-network-env<br />
<br />
You can [[start]] {{ic|qemu-network-env.service}} as usual.<br />
<br />
====Alternative method====<br />
<br />
If the above method does not work or you do not want to mess with kernel configs, TUN, dnsmasq, and iptables you can do the following for the same result.<br />
<br />
# vde_switch -daemon -mod 660 -group users<br />
# slirpvde --dhcp --daemon<br />
<br />
Then, to start the VM with a connection to the network of the host:<br />
<br />
$ qemu-system-i386 -net nic,macaddr=52:54:00:00:EE:03 -net vde ''disk_image''<br />
<br />
=== VDE2 Bridge ===<br />
<br />
Based on [http://selamatpagicikgu.wordpress.com/2011/06/08/quickhowto-qemu-networking-using-vde-tuntap-and-bridge/ quickhowto: qemu networking using vde, tun/tap, and bridge] graphic. Any virtual machine connected to vde is externally exposed. For example, each virtual machine can receive DHCP configuration directly from your ADSL router.<br />
<br />
==== Basics ====<br />
<br />
Remember that you need {{ic|tun}} module and {{Pkg|bridge-utils}} package.<br />
<br />
Create the vde2/tap device:<br />
<br />
# vde_switch -tap tap0 -daemon -mod 660 -group users<br />
# ip link set tap0 up<br />
<br />
Create bridge:<br />
<br />
# brctl addbr br0<br />
<br />
Add devices:<br />
<br />
# brctl addif br0 eth0<br />
# brctl addif br0 tap0<br />
<br />
And configure bridge interface:<br />
<br />
# dhcpcd br0<br />
<br />
==== Startup scripts ====<br />
<br />
All devices must be set up. And only the bridge needs an IP address. For physical devices on the bridge (e.g. {{ic|eth0}}), this can be done with [[netctl]] using a custom Ethernet profile with:<br />
<br />
{{hc|/etc/netctl/ethernet-noip|<nowiki><br />
Description='A more versatile static Ethernet connection'<br />
Interface=eth0<br />
Connection=ethernet<br />
IP=no<br />
</nowiki>}}<br />
<br />
The following custom systemd service can be used to create and activate a VDE2 tap interface for use in the {{ic|users}} user group.<br />
<br />
{{hc|/etc/systemd/system/vde2@.service|<nowiki><br />
[Unit]<br />
Description=Network Connectivity for %i<br />
Wants=network.target<br />
Before=network.target<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
ExecStart=/usr/bin/vde_switch -tap %i -daemon -mod 660 -group users<br />
ExecStart=/usr/bin/ip link set dev %i up<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 />
And finally, you can create the [[Bridge with netctl|bridge interface with netctl]].<br />
<br />
== Graphics ==<br />
<br />
QEMU can use the following different graphic outputs: {{ic|std}}, {{ic|qxl}}, {{ic|vmware}}, {{ic|virtio}}, {{ic|cirrus}} and {{ic|none}}.<br />
<br />
=== std ===<br />
<br />
With {{ic|-vga std}} you can get a resolution of up to 2560 x 1600 pixels without requiring guest drivers. This is the default since QEMU 2.2.<br />
<br />
=== qxl ===<br />
<br />
QXL is a paravirtual graphics driver with 2D support. To use it, pass the {{ic|-vga qxl}} option and install drivers in the guest. You may want to use SPICE for improved graphical performance when using QXL.<br />
<br />
On Linux guests, the {{ic|qxl}} and {{ic|bochs_drm}} kernel modules must be loaded in order to gain a decent performance.<br />
<br />
==== SPICE ====<br />
The [http://spice-space.org/ SPICE project] aims to provide a complete open source solution for remote access to virtual machines in a seamless way.<br />
<br />
SPICE can only be used when using QXL as the graphical output.<br />
<br />
The following is example of booting with SPICE as the remote desktop protocol:<br />
<br />
$ qemu-system-i386 -vga qxl -spice port=5930,disable-ticketing -chardev spicevm <br />
<br />
Connect to the guest by using a SPICE client. At the moment {{Pkg|spice-gtk3}} is recommended, however other [http://www.spice-space.org/download.html clients], including other platforms, are available:<br />
<br />
$ spicy -h 127.0.0.1 -p 5930<br />
<br />
Using [[wikipedia:Unix_socket|Unix sockets]] instead of TCP ports does not involve using network stack on the host system, so it is [https://unix.stackexchange.com/questions/91774/performance-of-unix-sockets-vs-tcp-ports reportedly] better for performance. Example:<br />
$ qemu-system-x86_64 -vga qxl -device virtio-serial-pci -device virtserialport,chardev=spicechannel0,name=com.redhat.spice.0 -chardev spicevmc,id=spicechannel0,name=vdagent -spice unix,addr=/tmp/vm_spice.socket,disable-ticketing,playback-compression=off<br />
$ spicy --uri="spice+unix:///tmp/vm_spice.socket"<br />
<br />
For improved support for multiple monitors, clipboard sharing, etc. the following packages should be installed on the guest:<br />
* {{AUR|spice-vdagent}}: Spice agent xorg client that enables copy and paste between client and X-session and more<br />
* {{AUR|xf86-video-qxl}} {{AUR|xf86-video-qxl-git}}: Xorg X11 qxl video driver<br />
* For other operating systems, see the Guest section on [http://www.spice-space.org/download.html SPICE-Space download] page.<br />
<br />
=== vmware ===<br />
<br />
Although it is a bit buggy, it performs better than std and cirrus. Install the VMware drivers ({{Pkg|xf86-video-vmware}} and {{Pkg|xf86-input-vmmouse}} for Arch Linux guests.<br />
<br />
=== virtio ===<br />
<br />
{{ic|virtio-vga}} / {{ic|virtio-gpu}} is a paravirtual 3D graphics driver based on [https://virgil3d.github.io/ virgl]. Currently a work in progress, supporting only very recent (>= 4.4) Linux guests.<br />
<br />
=== cirrus ===<br />
<br />
The cirrus graphical adapter was the default [http://wiki.qemu.org/ChangeLog/2.2#VGA before 2.2]. It [https://www.kraxel.org/blog/2014/10/qemu-using-cirrus-considered-harmful/ should not] be used on modern systems.<br />
<br />
=== none ===<br />
<br />
This is like a PC that has no VGA card at all. You would not even be able to access it with the {{ic|-vnc}} option. Also, this is different from the {{ic|-nographic}} option which lets QEMU emulate a VGA card, but disables the SDL display.<br />
<br />
=== vnc ===<br />
<br />
Given that you used the {{ic|-nographic}} option, you can add the {{ic|-vnc display}} option to have QEMU listen on {{ic|display}} and redirect the VGA display to the VNC session. There is an example of this in the [[#Starting QEMU virtual machines on boot]] section's example configs.<br />
<br />
$ qemu-system-i386 -vga std -nographic -vnc :0<br />
$ gvncviewer :0<br />
<br />
When using VNC, you might experience keyboard problems described (in gory details) [https://www.berrange.com/posts/2010/07/04/more-than-you-or-i-ever-wanted-to-know-about-virtual-keyboard-handling/ here]. The solution is ''not'' to use the {{ic|-k}} option on QEMU, and to use {{ic|gvncviewer}} from {{Pkg|gtk-vnc}}. See also [http://www.mail-archive.com/libvir-list@redhat.com/msg13340.html this] message posted on libvirt's mailing list.<br />
<br />
== Installing virtio drivers ==<br />
<br />
QEMU offers guests the ability to use paravirtualized block and network devices using the [http://wiki.libvirt.org/page/Virtio virtio] drivers, which provide better performance and lower overhead.<br />
<br />
* A virtio block device requires the option {{Ic|-drive}} instead of the simple {{Ic|-hd*}} plus {{Ic|1=if=virtio}}:<br />
$ qemu-system-i386 -boot order=c -drive file=''disk_image'',if=virtio<br />
<br />
{{Note|{{Ic|1=-boot order=c}} is absolutely necessary when you want to boot from it. There is no auto-detection as with {{Ic|-hd*}}.}}<br />
<br />
* Almost the same goes for the network:<br />
$ qemu-system-i386 -net nic,model=virtio<br />
<br />
{{Note|This will only work if the guest machine has drivers for virtio devices. Linux does, and the required drivers are included in Arch Linux, but there is no guarantee that virtio devices will work with other operating systems.}}<br />
<br />
=== Preparing an (Arch) Linux guest ===<br />
<br />
To use virtio devices after an Arch Linux guest has been installed, the following modules must be loaded in the guest: {{Ic|virtio}}, {{Ic|virtio_pci}}, {{Ic|virtio_blk}}, {{Ic|virtio_net}}, and {{Ic|virtio_ring}}. For 32-bit guests, the specific "virtio" module is not necessary.<br />
<br />
If you want to boot from a virtio disk, the initial ramdisk must contain the necessary modules. By default, this is handled by [[mkinitcpio]]'s {{ic|autodetect}} hook. Otherwise use the {{ic|MODULES}} array in {{ic|/etc/mkinitcpio.conf}} to include the necessary modules and rebuild the initial ramdisk.<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
MODULES="virtio virtio_blk virtio_pci virtio_net"}}<br />
<br />
Virtio disks are recognized with the prefix {{ic|'''v'''}} (e.g. {{ic|'''v'''da}}, {{ic|'''v'''db}}, etc.); therefore, changes must be made in at least {{ic|/etc/fstab}} and {{ic|/boot/grub/grub.cfg}} when booting from a virtio disk.<br />
<br />
{{Tip|When referencing disks by [[UUID]] in both {{ic|/etc/fstab}} and bootloader, nothing has to be done.}}<br />
<br />
Further information on paravirtualization with KVM can be found [http://www.linux-kvm.org/page/Boot_from_virtio_block_device here].<br />
<br />
You might also want to install {{Pkg|qemu-guest-agent}} to implement support for QMP commands that will enhance the hypervisor management capabilities. After installing the package you can enable and start the {{ic|qemu-ga.service}}.<br />
<br />
=== Preparing a Windows guest ===<br />
<br />
{{Note|1=The only (reliable) way to upgrade a Windows 8.1 guest to Windows 10 seems to be to temporarily choose cpu core2duo,nx for the install [http://ubuntuforums.org/showthread.php?t=2289210]. After the install, you may revert to other cpu settings (8/8/2015).}}<br />
<br />
==== Block device drivers ====<br />
<br />
===== New Install of Windows =====<br />
<br />
Windows does not come with the virtio drivers. Therefore, you will need to load them during installation. There are basically two ways to do this: via Floppy Disk or via ISO files. Both images can be downloaded from the [https://fedoraproject.org/wiki/Windows_Virtio_Drivers Fedora repository].<br />
<br />
The floppy disk option is difficult because you will need to press F6 (Shift-F6 on newer Windows) at the very beginning of powering on the QEMU. This is difficult since you need time to connect your VNC console window. You can attempt to add a delay to the boot sequence. See {{ic|man qemu-system}} for more details about applying a delay at boot.<br />
<br />
The ISO option to load drivers is the preferred way, but it is available only on Windows Vista and Windows Server 2008 and later. The procedure is to load the image with virtio drivers in an additional cdrom device along with the primary disk device and Windows installer:<br />
<br />
$ qemu-system-i386 ... \<br />
-drive file=''/path/to/primary/disk.img'',index=0,media=disk,if=virtio \<br />
-drive file=''/path/to/installer.iso'',index=2,media=cdrom \<br />
-drive file=''/path/to/virtio.iso'',index=3,media=cdrom \<br />
...<br />
<br />
During the installation, the Windows installer will ask you for your Product key and perform some additional checks. When it gets to the "Where do you want to install Windows?" screen, it will give a warning that no disks are found. Follow the example instructions below (based on Windows Server 2012 R2 with Update).<br />
<br />
* Select the option {{ic|Load Drivers}}.<br />
* Uncheck the box for "Hide drivers that aren't compatible with this computer's hardware".<br />
* Click the Browse button and open the CDROM for the virtio iso, usually named "virtio-win-XX".<br />
* Now browse to {{ic|E:\viostor\[your-os]\amd64}}, select it, and press OK.<br />
* Click Next<br />
<br />
You should now see your virtio disk(s) listed here, ready to be selected, formatted and installed to.<br />
<br />
===== Change Existing Windows VM to use virtio =====<br />
Modifying an existing Windows guest for booting from virtio disk is a bit tricky.<br />
<br />
You can download the virtio disk driver from the [https://fedoraproject.org/wiki/Windows_Virtio_Drivers Fedora repository].<br />
<br />
Now you need to create a new disk image, which fill force Windows to search for the driver. For example:<br />
<br />
$ qemu-img create -f qcow2 ''fake.qcow2'' 1G<br />
<br />
Run the original Windows guest (with the boot disk still in IDE mode) with the fake disk (in virtio mode) and a CD-ROM with the driver.<br />
<br />
$ qemu-system-i386 -m 512 -vga std -drive file=''windows_disk_image'',if=ide -drive file=''fake.qcow2'',if=virtio -cdrom virtio-win-0.1-81.iso<br />
<br />
Windows will detect the fake disk and try to find a driver for it. If it fails, go to the ''Device Manager'', locate the SCSI drive with an exclamation mark icon (should be open), click ''Update driver'' and select the virtual CD-ROM. Do not forget to select the checkbox which says to search for directories recursively.<br />
<br />
When the installation is successful, you can turn off the virtual machine and launch it again, now with the boot disk attached in virtio mode:<br />
<br />
$ qemu-system-i386 -m 512 -vga std -drive file=''windows_disk_image'',if=virtio<br />
<br />
{{Note|If you encounter the Blue Screen of Death, make sure you did not forget the {{ic|-m}} parameter, and that you do not boot with virtio instead of ide for the system drive before drivers are installed.}}<br />
<br />
==== Network drivers ====<br />
<br />
Installing virtio network drivers is a bit easier, simply add the {{ic|-net}} argument as explained above.<br />
<br />
$ qemu-system-i386 -m 512 -vga std -drive file=''windows_disk_image'',if=virtio -net nic,model=virtio -cdrom virtio-win-0.1-74.iso<br />
<br />
Windows will detect the network adapter and try to find a driver for it. If it fails, go to the ''Device Manager'', locate the network adapter with an exclamation mark icon (should be open), click ''Update driver'' and select the virtual CD-ROM. Do not forget to select the checkbox which says to search for directories recursively.<br />
<br />
=== Preparing a FreeBSD guest ===<br />
<br />
Install the {{ic|emulators/virtio-kmod}} port if you are using FreeBSD 8.3 or later up until 10.0-CURRENT where they are included into the kernel. After installation, add the following to your {{ic|/boot/loader.conf}} file:<br />
<br />
{{bc|<nowiki><br />
virtio_loader="YES"<br />
virtio_pci_load="YES"<br />
virtio_blk_load="YES"<br />
if_vtnet_load="YES"<br />
virtio_balloon_load="YES"<br />
</nowiki>}}<br />
<br />
Then modify your {{ic|/etc/fstab}} by doing the following:<br />
<br />
{{bc|<nowiki><br />
sed -i bak "s/ada/vtbd/g" /etc/fstab<br />
</nowiki>}}<br />
<br />
And verify that {{ic|/etc/fstab}} is consistent. If anything goes wrong, just boot into a rescue CD and copy {{ic|/etc/fstab.bak}} back to {{ic|/etc/fstab}}.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Starting QEMU virtual machines on boot ===<br />
<br />
==== With libvirt ====<br />
<br />
If a virtual machine is set up with [[libvirt]], it can be configured through the virt-manager GUI to start at host boot by going to the Boot Options for the virtual machine and selecting "Start virtual machine on host boot up".<br />
<br />
==== Custom script ====<br />
<br />
To run QEMU VMs on boot, you can use following systemd unit and config.<br />
<br />
{{hc|/etc/systemd/system/qemu@.service|<nowiki><br />
[Unit]<br />
Description=QEMU virtual machine<br />
<br />
[Service]<br />
Environment="type=system-x86_64" "haltcmd=kill -INT $MAINPID"<br />
EnvironmentFile=/etc/conf.d/qemu.d/%i<br />
ExecStart=/usr/bin/env qemu-${type} -name %i -nographic $args<br />
ExecStop=/bin/sh -c ${haltcmd}<br />
TimeoutStopSec=30<br />
KillMode=none<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
{{Note|According to {{ic|systemd.service(5)}} and {{ic|systemd.kill(5)}} man pages it is necessary to use the {{ic|1=KillMode=none}} option. Otherwise the main qemu process will be killed immediately after the {{ic|ExecStop}} command quits (it simply echoes one string) and your quest system will not be able to shutdown correctly.}}<br />
<br />
Then create per-VM configuration files, named {{ic|/etc/conf.d/qemu.d/''vm_name''}}, with the following variables set:<br />
<br />
; type<br />
: QEMU binary to call. If specified, will be prepended with {{ic|/usr/bin/qemu-}} and that binary will be used to start the VM. I.e. you can boot e.g. {{ic|qemu-system-arm}} images with {{ic|1=type="system-arm"}}.<br />
; args<br />
: QEMU command line to start with. Will always be prepended with {{ic|-name ${vm} -nographic}}.<br />
; haltcmd<br />
: Command to shut down a VM safely. I am using {{ic|-monitor telnet:..}} and power off my VMs via ACPI by sending {{ic|system_powerdown}} to monitor. You can use SSH or some other ways.<br />
<br />
Example configs:<br />
<br />
{{hc|/etc/conf.d/qemu.d/one|<nowiki><br />
type="system-x86_64"<br />
<br />
args="-enable-kvm -m 512 -hda /dev/mapper/vg0-vm1 -net nic,macaddr=DE:AD:BE:EF:E0:00 \<br />
-net tap,ifname=tap0 -serial telnet:localhost:7000,server,nowait,nodelay \<br />
-monitor telnet:localhost:7100,server,nowait,nodelay -vnc :0"<br />
<br />
haltcmd="echo 'system_powerdown' | nc localhost 7100" # or netcat/ncat<br />
<br />
# You can use other ways to shut down your VM correctly<br />
#haltcmd="ssh powermanager@vm1 sudo poweroff"<br />
</nowiki>}}<br />
<br />
{{hc|/etc/conf.d/qemu.d/two|<nowiki><br />
args="-enable-kvm -m 512 -hda /srv/kvm/vm2.img -net nic,macaddr=DE:AD:BE:EF:E0:01 \<br />
-net tap,ifname=tap1 -serial telnet:localhost:7001,server,nowait,nodelay \<br />
-monitor telnet:localhost:7101,server,nowait,nodelay -vnc :1"<br />
<br />
haltcmd="echo 'system_powerdown' | nc localhost 7101"<br />
</nowiki>}}<br />
<br />
To set which virtual machines will start on boot-up, [[enable]] the {{ic|qemu@''vm_name''.service}} systemd unit.<br />
<br />
=== Mouse integration ===<br />
<br />
To prevent the mouse from being grabbed when clicking on the guest operating system's window, add the option {{ic|-usbdevice tablet}}. This means QEMU is able to report the mouse position without having to grab the mouse. This also overrides PS/2 mouse emulation when activated. For example:<br />
<br />
$ qemu-system-i386 -hda ''disk_image'' -m 512 -vga std -usbdevice tablet<br />
<br />
If that does not work, try the tip at [[#Mouse cursor is jittery or erratic]].<br />
<br />
=== Pass-through host USB device ===<br />
<br />
To access physical USB device connected to host from VM, you can start QEMU with following option:<br />
<br />
$ qemu-system-i386 -usbdevice host:''vendor_id'':''product_id'' ''disk_image''<br />
<br />
You can find {{ic|vendor_id}} and {{ic|product_id}} of your device with {{ic|lsusb}} command.<br />
<br />
{{Note|If you encounter permission errors when running QEMU, see [[Udev#Writing udev rules]] for information on how to set permissions of the device.}}<br />
<br />
=== Enabling KSM ===<br />
<br />
Kernel Samepage Merging (KSM) is a feature of the Linux kernel that allows for an application to register with the kernel to have its pages merged with other processes that also register to have their pages merged. The KSM mechanism allows for guest virtual machines to share pages with each other. In an environment where many of the guest operating systems are similar, this can result in significant memory savings.<br />
<br />
To enable KSM, simply run<br />
<br />
# echo 1 > /sys/kernel/mm/ksm/run<br />
<br />
To make it permanent, you can use [[systemd#Temporary files|systemd's temporary files]]:<br />
<br />
{{hc|/etc/tmpfiles.d/ksm.conf|<br />
w /sys/kernel/mm/ksm/run - - - - 1<br />
}}<br />
<br />
If KSM is running, and there are pages to be merged (i.e. at least two similar VMs are running), then {{ic|/sys/kernel/mm/ksm/pages_shared}} should be non-zero. See https://www.kernel.org/doc/Documentation/vm/ksm.txt for more information.<br />
<br />
{{Tip|An easy way to see how well KSM is performing is to simply print the contents of all the files in that directory: {{bc|$ grep . /sys/kernel/mm/ksm/*}}}}<br />
<br />
=== Multi-monitor support ===<br />
The Linux QXL driver supports four heads (virtual screens) by default. This can be changed via the {{ic|1=qxl.heads=N}} kernel parameter.<br />
<br />
The default VGA memory size for QXL devices is 16M (VRAM size is 64M). This is not sufficient if you would like to enable two 1920x1200 monitors since that requires 2 × 1920 × 4 (color depth) × 1200 = 17.6 MiB VGA memory. This can be changed by replacing {{ic|-vga qxl}} by {{ic|<nowiki>-vga none -device qxl-vga,vgamem_mb=32</nowiki>}}. If you ever increase vgamem_mb beyond 64M, then you also have to increase the {{ic|vram_size_mb}} option.<br />
<br />
=== Copy and paste ===<br />
<br />
To have copy and paste between the host and the guest you need to enable the spice agent communication channel. It requires to add a virtio-serial device to the guest, and open a port for the spice vdagent. It is also required to install the spice vdagent in guest ({{AUR|spice-vdagent}} for Arch guests, [http://www.spice-space.org/download.html Windows guest tools] for Windows guests). Make sure the agent is running (and for future, started automatically).<br />
<br />
Start QEMU with the following options:<br />
<br />
$ qemu-system-i386 -vga qxl -spice port=5930,disable-ticketing -device virtio-serial-pci -device virtserialport,chardev=spicechannel0,name=com.redhat.spice.0 -chardev spicevmc,id=spicechannel0,name=vdagent<br />
<br />
The {{ic|-device virtio-serial-pci}} option adds the virtio-serial device, {{ic|1=-device virtserialport,chardev=spicechannel0,name=com.redhat.spice.0}} opens a port for spice vdagent in that device and {{ic|1=-chardev spicevmc,id=spicechannel0,name=vdagent}} adds a spicevmc chardev for that port.<br />
<br />
It is important that the {{ic|1=chardev=}} option of the {{ic|virtserialport}} device matches the {{ic|1=id=}} option given to the {{ic|chardev}} option ({{ic|spicechannel0}} in this example). It is also important that the port name is {{ic|com.redhat.spice.0}}, because that is the namespace where vdagent is looking for in the guest. And finally, specify {{ic|1=name=vdagent}} so that spice knows what this channel is for.<br />
<br />
=== Windows-specific notes ===<br />
<br />
QEMU can run any version of Windows from Windows 95 through Windows 10.<br />
<br />
It is possible to run [[Windows PE]] in QEMU.<br />
<br />
==== Fast startup ====<br />
<br />
For Windows 8 (or later) guests it is better to disable "Fast Startup" from the Power Options of the Control Panel, as it causes the guest to hang during every other boot.<br />
<br />
Fast Startup may also need to be disabled for changes to the {{ic|-smp}} option to be properly applied.<br />
<br />
==== Remote Desktop Protocol ====<br />
<br />
If you use a MS Windows guest, you might want to use RDP to connect to your guest VM. If you are using a VLAN or are not in the same network as the guest, use:<br />
<br />
$ qemu-system-i386 -nographic -net user,hostfwd=tcp::5555-:3389<br />
<br />
Then connect with either {{Pkg|rdesktop}} or {{Pkg|freerdp}} to the guest. For example:<br />
<br />
$ xfreerdp -g 2048x1152 localhost:5555 -z -x lan<br />
<br />
== Troubleshooting ==<br />
<br />
=== Mouse cursor is jittery or erratic ===<br />
<br />
If the cursor jumps around the screen uncontrollably, entering this on the terminal before starting QEMU might help:<br />
<br />
$ export SDL_VIDEO_X11_DGAMOUSE=0<br />
<br />
If this helps, you can add this to your {{ic|~/.bashrc}} file.<br />
<br />
=== No visible Cursor ===<br />
<br />
Add {{ic|-show-cursor}} to QEMU's options to see a mouse cursor.<br />
<br />
=== Keyboard seems broken or the arrow keys do not work ===<br />
<br />
Should you find that some of your keys do not work or "press" the wrong key (in particular, the arrow keys), you likely need to specify your keyboard layout as an option. The keyboard layouts can be found in {{ic|/usr/share/qemu/keymaps}}.<br />
<br />
$ qemu-system-i386 -k ''keymap'' ''disk_image''<br />
<br />
=== Virtual machine runs too slowly ===<br />
<br />
There are a number of techniques that you can use to improve the performance if your virtual machine. For example:<br />
<br />
* Use the {{ic|-cpu host}} option to make QEMU emulate the host's exact CPU. If you do not do this, it may be trying to emulate a more generic CPU.<br />
* If the host machine has multiple CPUs, assign the guest more CPUs using the {{ic|-smp}} option.<br />
* Make sure you have assigned the virtual machine enough memory. By default, QEMU only assigns 128 MiB of memory to each virtual machine. Use the {{ic|-m}} option to assign more memory. For example, {{ic|-m 1024}} runs a virtual machine with 1024 MiB of memory.<br />
* Use KVM if possible: add {{ic|1=-machine type=pc,accel=kvm}} to the QEMU start command you use.<br />
* If supported by drivers in the guest operating system, use [http://wiki.libvirt.org/page/Virtio virtio] for network and/or block devices. For example:<br />
$ qemu-system-i386 -net nic,model=virtio -net tap,if=tap0,script=no -drive file=''disk_image'',media=disk,if=virtio<br />
* Use TAP devices instead of user-mode networking. See [[#Tap networking with QEMU]].<br />
* If the guest OS is doing heavy writing to its disk, you may benefit from certain mount options on the host's file system. For example, you can mount an [[Ext4|ext4 file system]] with the option {{ic|1=barrier=0}}. You should read the documentation for any options that you change because sometimes performance-enhancing options for file systems come at the cost of data integrity.<br />
* If you have a raw disk image, you may want to disable the cache:<br />
$ qemu-system-i386 -drive file=''disk_image'',if=virtio,cache=none<br />
* Use the native Linux AIO:<br />
$ qemu-system-i386 -drive file=''disk_image'',if=virtio,aio=native<br />
* If you are running multiple virtual machines concurrently that all have the same operating system installed, you can save memory by enabling [[wikipedia:Kernel_SamePage_Merging_(KSM)|kernel same-page merging]]:<br />
# echo 1 > /sys/kernel/mm/ksm/run<br />
* In some cases, memory can be reclaimed from running virtual machines by running a memory ballooning driver in the guest operating system and launching QEMU with the {{ic|-balloon virtio}} option.<br />
<br />
See http://www.linux-kvm.org/page/Tuning_KVM for more information.<br />
<br />
=== Guest display stretches on window resize ===<br />
<br />
To restore default window size, press {{ic|Ctrl+Alt+u}}.<br />
<br />
=== ioctl(KVM_CREATE_VM) failed: 16 Device or resource busy ===<br />
<br />
If an error message like this is printed when starting QEMU with {{ic|-enable-kvm}} option:<br />
<br />
ioctl(KVM_CREATE_VM) failed: 16 Device or resource busy<br />
failed to initialize KVM: Device or resource busy<br />
<br />
that means another [[hypervisor]] is currently running. It is not recommended or possible to run several hypervisors in parallel.<br />
<br />
=== libgfapi error message ===<br />
<br />
The error message displayed at startup:<br />
<br />
Failed to open module: libgfapi.so.0: cannot open shared object file: No such file or directory<br />
<br />
is not a problem, it just means that you are lacking the optional GlusterFS dependency.<br />
<br />
=== Kernel panic on LIVE-environments===<br />
<br />
If you start a live-environment (or better: booting a system) you may encounter this:<br />
<br />
[ end Kernel panic - not syncing: VFS: Unable to mount root fs on unknown block(0,0)<br />
<br />
or some other boot hindering process (e.g. cannot unpack initramfs, cant start service foo).<br />
Try starting the VM with the {{ic|-m VALUE}} switch and an appropriate amount of RAM, if the ram is to low you will probably encounter similar issues as above/without the memory-switch.<br />
<br />
== See also ==<br />
<br />
* [http://qemu.org Official QEMU website]<br />
* [http://www.linux-kvm.org Official KVM website]<br />
* [http://qemu.weilnetz.de/qemu-doc.html QEMU Emulator User Documentation]<br />
* [https://en.wikibooks.org/wiki/QEMU QEMU Wikibook]<br />
* [http://alien.slackbook.org/dokuwiki/doku.php?id=slackware:qemu Hardware virtualization with QEMU] by AlienBOB (last updated in 2008)<br />
* [http://blog.falconindy.com/articles/build-a-virtual-army.html Building a Virtual Army] by Falconindy<br />
* [http://git.qemu.org/?p=qemu.git;a=tree;f=docs Lastest docs]<br />
* [http://qemu.weilnetz.de/ QEMU on Windows]<br />
* [[wikipedia:Qemu|Wikipedia]]<br />
* [https://wiki.debian.org/QEMU QEMU - Debian Wiki]<br />
* [https://people.gnome.org/~markmc/qemu-networking.html QEMU Networking on gnome.org]<br />
* [http://bsdwiki.reedmedia.net/wiki/networking_qemu_virtual_bsd_systems.html Networking QEMU Virtual BSD Systems]<br />
* [https://www.gnu.org/software/hurd/hurd/running/qemu.html QEMU on gnu.org]<br />
* [https://wiki.freebsd.org/qemu QEMU on FreeBSD as host]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=QEMU&diff=446792QEMU2016-08-16T16:38:47Z<p>Alive4ever: /* Mounting a partition inside a raw disk image */ udisksctl can also be used to setup loop device</p>
<hr />
<div>[[Category:Emulators]]<br />
[[Category:Hypervisors]]<br />
[[de:Qemu]]<br />
[[es:QEMU]]<br />
[[fr:Qemu]]<br />
[[ja:QEMU]]<br />
[[zh-CN:QEMU]]<br />
[[zh-TW:QEMU]]<br />
{{Related articles start}}<br />
{{Related|:Category:Hypervisors}}<br />
{{Related|Libvirt}}<br />
{{Related articles end}}<br />
<br />
According to the [http://wiki.qemu.org/Main_Page QEMU about page], "QEMU is a generic and open source machine emulator and virtualizer."<br />
<br />
When used as a machine emulator, QEMU can run OSes and programs made for one machine (e.g. an ARM board) on a different machine (e.g. your x86 PC). By using dynamic translation, it achieves very good performance.<br />
<br />
QEMU can use other hypervisors like [[Xen]] or [[KVM]] to use CPU extensions ([[Wikipedia:Hardware-assisted virtualization|HVM]]) for virtualization. When used as a virtualizer, QEMU achieves near native performances by executing the guest code directly on the host CPU.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|qemu}} package and below optional packages for your needs:<br />
<br />
* {{Pkg|qemu-arch-extra}} - extra architectures support<br />
* {{Pkg|qemu-block-gluster}} - glusterfs block support<br />
* {{Pkg|qemu-block-iscsi}} - iSCSI block support<br />
* {{Pkg|qemu-block-rbd}} - RBD block support <br />
* {{Pkg|samba}} - SMB/CIFS server support <br />
<br />
== Graphical front-ends for QEMU ==<br />
<br />
Unlike other virtualization programs such as [[VirtualBox]] and [[VMware]], QEMU does not provide a GUI to manage virtual machines (other than the window that appears when running a virtual machine), nor does it provide a way to create persistent virtual machines with saved settings. All parameters to run a virtual machine must be specified on the command line at every launch, unless you have created a custom script to start your virtual machine(s). However, there are several GUI front-ends for QEMU:<br />
<br />
* {{Pkg|qemu-launcher}}<br />
* {{Pkg|qtemu}}<br />
* {{AUR|aqemu}}<br />
<br />
Additional front-ends with QEMU support are available for [[libvirt]].<br />
<br />
== Creating new virtualized system ==<br />
<br />
=== Creating a hard disk image ===<br />
<br />
{{Tip|See the [https://en.wikibooks.org/wiki/QEMU/Images QEMU Wikibook] for more information on QEMU images.}}<br />
<br />
To run QEMU you will need a hard disk image, unless you are booting a live system from CD-ROM or the network (and not doing so to install an operating system to a hard disk image). A hard disk image is a file which stores the contents of the emulated hard disk.<br />
<br />
A hard disk image can be ''raw'', so that it is literally byte-by-byte the same as what the guest sees, and will always use the full capacity of the guest hard drive on the host. This method provides the least I/O overhead, but can waste a lot of space, as not-used space on the guest cannot be used on the host.<br />
<br />
Alternatively, the hard disk image can be in a format such as ''qcow2'' which only allocates space to the image file when the guest operating system actually writes to those sectors on its virtual hard disk. The image appears as the full size to the guest operating system, even though it may take up only a very small amount of space on the host system. Using this format instead of ''raw'' will likely affect performance.<br />
<br />
QEMU provides the {{ic|qemu-img}} command to create hard disk images. For example to create a 4 GB image in the ''raw'' format:<br />
<br />
$ qemu-img create -f raw ''image_file'' 4G<br />
<br />
You may use {{ic|-f qcow2}} to create a ''qcow2'' disk instead.<br />
<br />
{{Note|You can also simply create a ''raw'' image by creating a file of the needed size using {{ic|dd}} or {{ic|fallocate}}.}}<br />
<br />
{{Warning|If you store the hard disk images on a [[Btrfs]] file system, you should consider disabling [[Btrfs#Copy-On-Write_.28CoW.29|Copy-on-Write]] for the directory before creating any images.}}<br />
<br />
==== Overlay storage images ====<br />
<br />
You can create a storage image once (the 'backing' image) and have QEMU keep mutations to this image in an overlay image. This allows you to revert to a previous state of this storage image. You could revert by creating a new overlay image at the time you wish to revert, based on the original backing image.<br />
<br />
To create an overlay image, issue a command like:<br />
<br />
$ qemu-img create -o backing_file=''img1.raw'',backing_fmt=''raw'' -f ''qcow2'' ''img1.cow''<br />
<br />
After that you can run your QEMU VM as usual (see [[#Running virtualized system]]):<br />
<br />
$ qemu-system-i386 ''img1.cow''<br />
<br />
The backing image will then be left intact and mutations to this storage will be recorded in the overlay image file.<br />
<br />
When the path to the backing image changes, repair is required.<br />
<br />
{{Warning|The backing image's absolute filesystem path is stored in the (binary) overlay image file. Changing the backing image's path requires some effort.}}<br />
<br />
Make sure that the original backing image's path still leads to this image. If necessary, make a symbolic link at the original path to the new path. Then issue a command like:<br />
<br />
$ qemu-img rebase -b ''/new/img1.raw'' ''/new/img1.cow''<br />
<br />
At your discretion, you may alternatively perform an 'unsafe' rebase where the old path to the backing image is not checked:<br />
<br />
$ qemu-img rebase -u -b ''/new/img1.raw'' ''/new/img1.cow''<br />
<br />
==== Resizing an image ====<br />
<br />
{{Warning|Resizing an image containing an NTFS boot file system could make the operating system installed on it unbootable. For full explanation and workaround see [http://tjworld.net/wiki/Howto/ResizeQemuDiskImages].}}<br />
<br />
The {{ic|qemu-img}} executable has the {{ic|resize}} option, which enables easy resizing of a hard drive image. It works for both ''raw'' and ''qcow2''. For example, to increase image space by 10 GB, run:<br />
<br />
$ qemu-img resize ''disk_image'' +10G<br />
<br />
After enlarging the disk image, you must use file system and partitioning tools inside the virtual machine to actually begin using the new space. When shrinking a disk image, you must '''first reduce the allocated file systems and partition sizes''' using the file system and partitioning tools inside the virtual machine and then shrink the disk image accordingly, otherwise shrinking the disk image will result in data loss!<br />
<br />
=== Preparing the installation media ===<br />
<br />
To install an operating system into your disk image, you need the installation medium (e.g. optical disk, USB-drive, or ISO image) for the operating system. The installation medium should not be mounted because QEMU accesses the media directly.<br />
<br />
{{Tip|If using an optical disk, it is a good idea to first dump the media to a file because this both improves performance and does not require you to have direct access to the devices (that is, you can run QEMU as a regular user without having to change access permissions on the media's device file). For example, if the CD-ROM device node is named {{ic|/dev/cdrom}}, you can dump it to a file with the command: {{bc|1=$ dd if=/dev/cdrom of=''cd_image.iso''}}}}<br />
<br />
=== Installing the operating system===<br />
<br />
This is the first time you will need to start the emulator. To install the operating system on the disk image, you must attach both the disk image and the installation media to the virtual machine, and have it boot from the installation media.<br />
<br />
For example on i386 guests, to install from a bootable ISO file as CD-ROM and a raw disk image:<br />
<br />
$ qemu-system-i386 -cdrom ''iso_image'' -boot order=d -drive file=''disk_image'',format=raw<br />
<br />
See {{ic|qemu(1)}} for more information about loading other media types (such as floppy, disk images or physical drives) and [[#Running virtualized system]] for other useful options.<br />
<br />
After the operating system has finished installing, the QEMU image can be booted directly (see [[#Running virtualized system]]).<br />
<br />
{{Warning|By default only 128 MB of memory is assigned to the machine. The amount of memory can be adjusted with the {{ic|-m}} switch, for example {{ic|-m 512M}} or {{ic|-m 2G}}.}}<br />
<br />
{{Tip|<br />
* Instead of specifying {{ic|1=-boot order=x}}, some users may feel more comfortable using a boot menu: {{ic|1=-boot menu=on}}, at least during configuration and experimentation.<br />
* If you need to replace floppies or CDs as part of the installation process, you can use the QEMU machine monitor (press {{ic|Ctrl+Alt+2}} in the virtual machine's window) to remove and attach storage devices to a virtual machine. Type {{ic|info block}} to see the block devices, and use the {{ic|change}} command to swap out a device. Press {{ic|Ctrl+Alt+1}} to go back to the virtual machine.}}<br />
<br />
== Running virtualized system ==<br />
<br />
{{ic|qemu-system-*}} binaries (for example {{ic|qemu-system-i386}} or {{ic|qemu-system-x86_64}}, depending on guest's architecture) are used to run the virtualized guest. The usage is:<br />
<br />
$ qemu-system-i386 ''options'' ''disk_image''<br />
<br />
Options are the same for all {{ic|qemu-system-*}} binaries, see {{ic|qemu(1)}} for documentation of all options.<br />
<br />
By default, QEMU will show the virtual machine's video output in a window. One thing to keep in mind: when you click inside the QEMU window, the mouse pointer is grabbed. To release it, press {{ic|Ctrl+Alt+g}}.<br />
<br />
{{Warning|QEMU should never be run as root. If you must launch it in a script as root, you should use the {{ic|-runas}} option to make QEMU drop root privileges.}}<br />
<br />
=== Enabling KVM ===<br />
<br />
KVM must be supported by your processor and kernel, and necessary [[kernel modules]] must be loaded. See [[KVM]] for more information.<br />
<br />
To start QEMU in KVM mode, append {{ic|-enable-kvm}} to the additional start options. To check if KVM is enabled for a running VM, enter the QEMU [https://en.wikibooks.org/wiki/QEMU/Monitor Monitor] using {{ic|Ctrl+Alt+Shift+2}}, and type {{ic|info kvm}}.<br />
<br />
{{Note|<br />
* If you start your VM with a GUI tool and experience very bad performance, you should check for proper KVM support, as QEMU may be falling back to software emulation.<br />
* KVM needs to be enabled in order to start Windows 7 and Windows 8 properly without a ''blue screen''.<br />
}}<br />
<br />
=== Enabling IOMMU (Intel VT-d/AMD-Vi) support ===<br />
Using IOMMU opens to features like PCI passthrough and memory protection from faulty or malicious devices, see [[wikipedia:Input-output memory management unit#Advantages]] and [https://www.quora.com/Memory-Management-computer-programming/Could-you-explain-IOMMU-in-plain-English Memory Management (computer programming): Could you explain IOMMU in plain English?].<br />
<br />
To enable IOMMU:<br />
#Ensure that AMD-Vi/Intel VT-d is supported by the CPU and is enabled in the BIOS settings.<br />
#Add {{ic|1=intel_iommu=on}} if you have an Intel CPU or {{ic|1=amd_iommu=on}} if you have an AMD CPU, to the [[kernel parameters]].<br />
#Reboot and ensure IOMMU is enabled by checking {{ic|dmesg}} for {{ic|DMAR}}: {{ic|[0.000000] DMAR: IOMMU enabled}}<br />
#Add {{ic|1=iommu=on}} or {{ic|1=q35,iommu=on}} depending on the {{ic|-machine}}, as ''option''.<br />
<br />
== Moving data between host and guest OS ==<br />
<br />
=== Network ===<br />
<br />
Data can be shared between the host and guest OS using any network protocol that can transfer files, such as [[NFS]], [[SMB]], [[Wikipedia:Network Block Device|NBD]], HTTP, [[Very Secure FTP Daemon|FTP]], or [[SSH]], provided that you have set up the network appropriately and enabled the appropriate services.<br />
<br />
The default user-mode networking allows the guest to access the host OS at the IP address 10.0.2.2. Any servers that you are running on your host OS, such as a SSH server or SMB server, will be accessible at this IP address. So on the guests, you can mount directories exported on the host via [[SMB]] or [[NFS]], or you can access the host's HTTP server, etc.<br />
It will not be possible for the host OS to access servers running on the guest OS, but this can be done with other network configurations (see [[#Tap networking with QEMU]]).<br />
<br />
=== QEMU's built-in SMB server ===<br />
<br />
QEMU's documentation says it has a "built-in" SMB server, but actually it just starts up [[Samba]] with an automatically generated {{ic|smb.conf}} file located at {{ic|/tmp/qemu-smb.''pid''-0/smb.conf}} and makes it accessible to the guest at a different IP address (10.0.2.4 by default). This only works for user networking, and this is not necessarily very useful since the guest can also access the normal [[Samba]] service on the host if you have set up shares on it.<br />
<br />
To enable this feature, start QEMU with a command like:<br />
<br />
$ qemu-system-i386 ''disk_image'' -net nic -net user,smb=''shared_dir_path''<br />
<br />
where {{ic|''shared_dir_path''}} is a directory that you want to share between the guest and host.<br />
<br />
Then, in the guest, you will be able to access the shared directory on the host 10.0.2.4 with the share name "qemu". For example, in Windows Explorer you would go to {{ic|\\10.0.2.4\qemu}}.<br />
<br />
{{Note|<br />
* If you are using sharing options multiple times like {{ic|1=-net user,smb=''shared_dir_path1'' -net user,smb=''shared_dir_path2''}} or {{ic|1=-net user,smb=''shared_dir_path1'',smb=''shared_dir_path2''}} then it will share only the last defined one.<br />
* If you cannot access the shared folder and the guest system is Windows, check that the [http://ecross.mvps.org/howto/enable-netbios-over-tcp-ip-with-windows.htm NetBIOS protocol is enabled] and that a firewall does not block [http://technet.microsoft.com/en-us/library/cc940063.aspx ports] used by the NetBIOS protocol.<br />
}}<br />
<br />
=== Mounting a partition inside a raw disk image ===<br />
<br />
When the virtual machine is not running, it is possible to mount partitions that are inside a raw disk image file by setting them up as loopback devices. This does not work with disk images in special formats, such as qcow2, although those can be mounted using {{ic|qemu-nbd}}.<br />
<br />
{{Warning|You must make sure to unmount the partitions before running the virtual machine again. Otherwise, data corruption is very likely to occur.}}<br />
<br />
==== With manually specifying byte offset ====<br />
<br />
One way to mount a disk image partition is to mount the disk image at a certain offset using a command like the following:<br />
<br />
# mount -o loop,offset=32256 ''disk_image'' ''mountpoint''<br />
<br />
The {{ic|1=offset=32256}} option is actually passed to the {{ic|losetup}} program to set up a loopback device that starts at byte offset 32256 of the file and continues to the end. This loopback device is then mounted. You may also use the {{ic|sizelimit}} option to specify the exact size of the partition, but this is usually unnecessary.<br />
<br />
Depending on your disk image, the needed partition may not start at offset 32256. Run {{ic|fdisk -l ''disk_image''}} to see the partitions in the image. fdisk gives the start and end offsets in 512-byte sectors, so multiply by 512 to get the correct offset to pass to {{ic|mount}}.<br />
<br />
==== With loop module autodetecting partitions ====<br />
<br />
The Linux loop driver actually supports partitions in loopback devices, but it is disabled by default. To enable it, do the following:<br />
<br />
* Get rid of all your loopback devices (unmount all mounted images, etc.).<br />
* [[Kernel_modules#Manual_module_handling|Unload]] the {{ic|loop}} kernel module, and load it with the {{ic|1=max_part=15}} parameter set. Additionally, the maximum number of loop devices can be controlled with the {{ic|max_loop}} parameter.<br />
<br />
{{Tip|You can put an entry in {{ic|/etc/modprobe.d}} to load the loop module with {{ic|1=max_part=15}} every time, or you can put {{ic|1=loop.max_part=15}} on the kernel command-line, depending on whether you have the {{ic|loop.ko}} module built into your kernel or not.}}<br />
<br />
Set up your image as a loopback device:<br />
<br />
# losetup -f -P ''disk_image''<br />
<br />
Then, if the device created was {{ic|/dev/loop0}}, additional devices {{ic|/dev/loop0pX}} will have been automatically created, where X is the number of the partition. These partition loopback devices can be mounted directly. For example:<br />
<br />
# mount /dev/loop0p1 ''mountpoint''<br />
<br />
==== With kpartx ====<br />
<br />
'''kpartx''' from the {{AUR|multipath-tools}} package can read a partition table on a device and create a new device for each partition. For example:<br />
# kpartx -a ''disk_image''<br />
<br />
This will setup the loopback device and create the necessary partition(s) device(s) in {{ic|/dev/mapper/}}.<br />
<br />
==== With udisks2 ====<br />
{{Pkg|udisks2}} has {{ic|udisksctl}} command line utility which allows standard user to mount partitions, setup loop devices, and powering off harddisks. To setup a loop device on raw disk image, this command is sufficient.<br />
<br />
$ udisksctl loop-setup -f ''disk_image''<br />
<br />
The available partitions will be automatically detected. To release the loop device<br />
<br />
$ udisksctl loop-delete -b /dev/''loopX''<br />
<br />
{{ic|/dev/loopX}} is the loop device which created via previous command. The first loop device usually created on {{ic|loop0}}.<br />
<br />
=== Mounting a partition inside a qcow2 image ===<br />
<br />
You may mount a partition inside a qcow2 image using {{ic|qemu-nbd}}. See [http://en.wikibooks.org/wiki/QEMU/Images#Mounting_an_image_on_the_host Wikibooks].<br />
<br />
=== Using any real partition as the single primary partition of a hard disk image ===<br />
<br />
Sometimes, you may wish to use one of your system partitions from within QEMU. Using a raw partition for a virtual machine will improve performance, as the read and write operations do not go through the file system layer on the physical host. Such a partition also provides a way to share data between the host and guest.<br />
<br />
In Arch Linux, device files for raw partitions are, by default, owned by ''root'' and the ''disk'' group. If you would like to have a non-root user be able to read and write to a raw partition, you need to change the owner of the partition's device file to that user.<br />
<br />
{{Warning|<br />
* Although it is possible, it is not recommended to allow virtual machines to alter critical data on the host system, such as the root partition.<br />
* You must not mount a file system on a partition read-write on both the host and the guest at the same time. Otherwise, data corruption will result.<br />
}}<br />
<br />
After doing so, you can attach the partition to a QEMU virtual machine as a virtual disk.<br />
<br />
However, things are a little more complicated if you want to have the ''entire'' virtual machine contained in a partition. In that case, there would be no disk image file to actually boot the virtual machine since you cannot install a bootloader to a partition that is itself formatted as a file system and not as a partitioned device with a MBR. Such a virtual machine can be booted either by specifying the [[kernel]] and [[initramfs|initrd]] manually, or by simulating a disk with a MBR by using linear [[RAID]].<br />
<br />
==== By specifying kernel and initrd manually ====<br />
<br />
QEMU supports loading [[Kernels|Linux kernels]] and [[initramfs|init ramdisks]] directly, thereby circumventing bootloaders such as [[GRUB]]. It then can be launched with the physical partition containing the root file system as the virtual disk, which will not appear to be partitioned. This is done by issuing a command similar to the following:<br />
<br />
{{Note|In this example, it is the '''host's''' images that are being used, not the guest's. If you wish to use the guest's images, either mount {{ic|/dev/sda3}} read-only (to protect the file system from the host) and specify the {{ic|/full/path/to/images}} or use some kexec hackery in the guest to reload the guest's kernel (extends boot time). }}<br />
<br />
$ qemu-system-i386 -kernel /boot/vmlinuz-linux -initrd /boot/initramfs-linux.img -append root=/dev/sda /dev/sda3<br />
<br />
In the above example, the physical partition being used for the guest's root file system is {{ic|/dev/sda3}} on the host, but it shows up as {{ic|/dev/sda}} on the guest.<br />
<br />
You may, of course, specify any kernel and initrd that you want, and not just the ones that come with Arch Linux.<br />
<br />
When there are multiple [[kernel parameters]] to be passed to the {{ic|-append}} option, they need to be quoted using single or double quotes. For example:<br />
<br />
... -append 'root=/dev/sda1 console=ttyS0'<br />
<br />
==== Simulate virtual disk with MBR using linear RAID ====<br />
<br />
A more complicated way to have a virtual machine use a physical partition, while keeping that partition formatted as a file system and not just having the guest partition the partition as if it were a disk, is to simulate a MBR for it so that it can boot using a bootloader such as GRUB.<br />
<br />
You can do this using software [[RAID]] in linear mode (you need the {{ic|linear.ko}} kernel driver) and a loopback device: the trick is to dynamically prepend a master boot record (MBR) to the real partition you wish to embed in a QEMU raw disk image.<br />
<br />
Suppose you have a plain, unmounted {{ic|/dev/hdaN}} partition with some file system on it you wish to make part of a QEMU disk image. First, you create some small file to hold the MBR:<br />
<br />
$ dd if=/dev/zero of=''/path/to/mbr'' count=32<br />
<br />
Here, a 16 KB (32 * 512 bytes) file is created. It is important not to make it too small (even if the MBR only needs a single 512 bytes block), since the smaller it will be, the smaller the chunk size of the software RAID device will have to be, which could have an impact on performance. Then, you setup a loopback device to the MBR file:<br />
<br />
# losetup -f ''/path/to/mbr''<br />
<br />
Let us assume the resulting device is {{ic|/dev/loop0}}, because we would not already have been using other loopbacks. Next step is to create the "merged" MBR + {{ic|/dev/hdaN}} disk image using software RAID:<br />
<br />
# modprobe linear<br />
# mdadm --build --verbose /dev/md0 --chunk=16 --level=linear --raid-devices=2 /dev/loop0 /dev/hda''N''<br />
<br />
The resulting {{ic|/dev/md0}} is what you will use as a QEMU raw disk image (do not forget to set the permissions so that the emulator can access it). The last (and somewhat tricky) step is to set the disk configuration (disk geometry and partitions table) so that the primary partition start point in the MBR matches the one of {{ic|/dev/hda''N''}} inside {{ic|/dev/md0}} (an offset of exactly 16 * 512 = 16384 bytes in this example). Do this using {{ic|fdisk}} on the host machine, not in the emulator: the default raw disc detection routine from QEMU often results in non-kilobyte-roundable offsets (such as 31.5 KB, as in the previous section) that cannot be managed by the software RAID code. Hence, from the the host:<br />
<br />
# fdisk /dev/md0<br />
<br />
Press {{ic|X}} to enter the expert menu. Set number of 's'ectors per track so that the size of one cylinder matches the size of your MBR file. For two heads and a sector size of 512, the number of sectors per track should be 16, so we get cylinders of size 2x16x512=16k.<br />
<br />
Now, press {{ic|R}} to return to the main menu.<br />
<br />
Press {{ic|P}} and check that the cylinder size is now 16k.<br />
<br />
Now, create a single primary partition corresponding to {{ic|/dev/hda''N''}}. It should start at cylinder 2 and end at the end of the disk (note that the number of cylinders now differs from what it was when you entered fdisk.<br />
<br />
Finally, 'w'rite the result to the file: you are done. You now have a partition you can mount directly from your host, as well as part of a QEMU disk image:<br />
<br />
$ qemu-system-i386 -hdc /dev/md0 ''[...]''<br />
<br />
You can, of course, safely set any bootloader on this disk image using QEMU, provided the original {{ic|/dev/hda''N''}} partition contains the necessary tools.<br />
<br />
== Networking ==<br />
<br />
{{Poor writing|Network topologies (sections [[#Host-only networking]], [[#Internal networking]] and info spread out across other sections) should not be described alongside the various virtual interfaces implementations, such as [[#User-mode networking]], [[#Tap networking with QEMU]], [[#Networking with VDE2]].}}<br />
<br />
The performance of virtual networking should be better with tap devices and bridges than with user-mode networking or vde because tap devices and bridges are implemented in-kernel.<br />
<br />
In addition, networking performance can be improved by assigning virtual machines a [http://wiki.libvirt.org/page/Virtio virtio] network device rather than the default emulation of an e1000 NIC. See [[#Installing virtio drivers]] for more information.<br />
<br />
=== Link-level address caveat ===<br />
<br />
By giving the {{ic|-net nic}} argument to QEMU, it will, by default, assign a virtual machine a network interface with the link-level address {{ic|52:54:00:12:34:56}}. However, when using bridged networking with multiple virtual machines, it is essential that each virtual machine has a unique link-level (MAC) address on the virtual machine side of the tap device. Otherwise, the bridge will not work correctly, because it will receive packets from multiple sources that have the same link-level address. This problem occurs even if the tap devices themselves have unique link-level addresses because the source link-level address is not rewritten as packets pass through the tap device.<br />
<br />
Make sure that each virtual machine has a unique link-level address, but it should always start with {{ic|52:54:}}. Use the following option, replace ''X'' with arbitrary hexadecimal digit:<br />
<br />
$ qemu-system-i386 -net nic,macaddr=52:54:''XX:XX:XX:XX'' -net vde ''disk_image''<br />
<br />
Generating unique link-level addresses can be done in several ways:<br />
<br />
<ol><br />
<li>Manually specify unique link-level address for each NIC. The benefit is that the DHCP server will assign the same IP address each time the virtual machine is run, but it is unusable for large number of virtual machines.<br />
</li><br />
<li>Generate random link-level address each time the virtual machine is run. Practically zero probability of collisions, but the downside is that the DHCP server will assign a different IP address each time. You can use the following command in a script to generate random link-level address in a {{ic|macaddr}} variable:<br />
<br />
{{bc|1=<br />
printf -v macaddr "52:54:%02x:%02x:%02x:%02x" $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff )) $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff ))<br />
qemu-system-i386 -net nic,macaddr="$macaddr" -net vde ''disk_image''<br />
}}<br />
<br />
</li><br />
<li>Use the following script {{ic|qemu-mac-hasher.py}} to generate the link-level address from the virtual machine name using a hashing function. Given that the names of virtual machines are unique, this method combines the benefits of the aforementioned methods: it generates the same link-level address each time the script is run, yet it preserves the practically zero probability of collisions.<br />
<br />
{{hc|qemu-mac-hasher.py|<nowiki><br />
#!/usr/bin/env python<br />
<br />
import sys<br />
import zlib<br />
<br />
if len(sys.argv) != 2:<br />
print("usage: %s <VM Name>" % sys.argv[0])<br />
sys.exit(1)<br />
<br />
crc = zlib.crc32(sys.argv[1].encode("utf-8")) & 0xffffffff<br />
crc = str(hex(crc))[2:]<br />
print("52:54:%s%s:%s%s:%s%s:%s%s" % tuple(crc))<br />
</nowiki>}}<br />
<br />
In a script, you can use for example:<br />
<br />
vm_name="''VM Name''"<br />
qemu-system-i386 -name "$vm_name" -net nic,macaddr=$(qemu-mac-hasher.py "$vm_name") -net vde ''disk_image''<br />
</li><br />
</ol><br />
<br />
=== User-mode networking ===<br />
<br />
By default, without any {{ic|-netdev}} arguments, QEMU will use user-mode networking with a built-in DHCP server. Your virtual machines will be assigned an IP address when they run their DHCP client, and they will be able to access the physical host's network through IP masquerading done by QEMU.<br />
<br />
{{warning|This only works with the TCP and UDP protocols, so ICMP, including {{ic|ping}}, will not work. Do not use {{ic|ping}} to test network connectivity.}}<br />
<br />
This default configuration allows your virtual machines to easily access the Internet, provided that the host is connected to it, but the virtual machines will not be directly visible on the external network, nor will virtual machines be able to talk to each other if you start up more than one concurrently.<br />
<br />
QEMU's user-mode networking can offer more capabilities such as built-in TFTP or SMB servers, redirecting host ports to the guest (for example to allow SSH connections to the guest) or attaching guests to VLANs so that they can talk to each other. See the QEMU documentation on the {{ic|-net user}} flag for more details.<br />
<br />
However, user-mode networking has limitations in both utility and performance. More advanced network configurations require the use of tap devices or other methods.<br />
<br />
=== Tap networking with QEMU ===<br />
<br />
[[wikipedia:TUN/TAP|Tap devices]] are a Linux kernel feature that allows you to create virtual network interfaces that appear as real network interfaces. Packets sent to a tap interface are delivered to a userspace program, such as QEMU, that has bound itself to the interface.<br />
<br />
QEMU can use tap networking for a virtual machine so that packets sent to the tap interface will be sent to the virtual machine and appear as coming from a network interface (usually an Ethernet interface) in the virtual machine. Conversely, everything that the virtual machine sends through its network interface will appear on the tap interface.<br />
<br />
Tap devices are supported by the Linux bridge drivers, so it is possible to bridge together tap devices with each other and possibly with other host interfaces such as {{ic|eth0}}. This is desirable if you want your virtual machines to be able to talk to each other, or if you want other machines on your LAN to be able to talk to the virtual machines.<br />
<br />
{{Warning|If you bridge together tap device and some host interface, such as {{ic|eth0}}, your virtual machines will appear directly on the external network, which will expose them to possible attack. Depending on what resources your virtual machines have access to, you may need to take all the [[Firewalls|precautions]] you normally would take in securing a computer to secure your virtual machines. If the risk is too great, virtual machines have little resources or you set up multiple virtual machines, a better solution might be to use [[#Host-only networking|host-only networking]] and set up NAT. In this case you only need one firewall on the host instead of multiple firewalls for each guest.}}<br />
<br />
As indicated in the user-mode networking section, tap devices offer higher networking performance than user-mode. If the guest OS supports virtio network driver, then the networking performance will be increased considerably as well. Supposing the use of the tap0 device, that the virtio driver is used on the guest, and that no scripts are used to help start/stop networking, next is part of the qemu command one should see:<br />
<br />
-net nic,model=virtio -net tap,ifname=tap0,script=no,downscript=no<br />
<br />
But if already using a tap device with virtio networking driver, one can even boost the networking performance by enabling vhost, like:<br />
<br />
-net nic,model=virtio -net tap,ifname=tap0,script=no,downscript=no,vhost=on<br />
<br />
See http://www.linux-kvm.com/content/how-maximize-virtio-net-performance-vhost-net for more information.<br />
<br />
==== Host-only networking ====<br />
<br />
If the bridge is given an IP address and traffic destined for it is allowed, but no real interface (e.g. {{ic|eth0}}) is connected to the bridge, then the virtual machines will be able to talk to each other and the host system. However, they will not be able to talk to anything on the external network, provided that you do not set up IP masquerading on the physical host. This configuration is called ''host-only networking'' by other virtualization software such as [[VirtualBox]].<br />
<br />
{{Tip|<br />
* If you want to set up IP masquerading, e.g. NAT for virtual machines, see the [[Internet sharing#Enable NAT]] page.<br />
* You may want to have a DHCP server running on the bridge interface to service the virtual network. For example, to use the {{ic|172.20.0.1/16}} subnet with [[dnsmasq]] as the DHCP server:<br />
# ip addr add 172.20.0.1/16 dev br0<br />
# ip link set br0 up<br />
# dnsmasq --interface&#61;br0 --bind-interfaces --dhcp-range&#61;172.20.0.2,172.20.255.254<br />
}}<br />
<br />
==== Internal networking ====<br />
<br />
If you do not give the bridge an IP address and add an [[iptables]] rule to drop all traffic to the bridge in the INPUT chain, then the virtual machines will be able to talk to each other, but not to the physical host or to the outside network. This configuration is called ''internal networking'' by other virtualization software such as [[VirtualBox]]. You will need to either assign static IP addresses to the virtual machines or run a DHCP server on one of them.<br />
<br />
By default iptables would drop packets in the bridge network. You may need to use such iptables rule to allow packets in a bridged network:<br />
<br />
# iptables -I FORWARD -m physdev --physdev-is-bridged -j ACCEPT<br />
<br />
==== Bridged networking using qemu-bridge-helper ====<br />
<br />
{{Note|This method is available since QEMU 1.1, see http://wiki.qemu.org/Features/HelperNetworking.}}<br />
<br />
This method does not require a start-up script and readily accommodates multiple taps and multiple bridges. It uses {{ic|/usr/lib/qemu/qemu-bridge-helper}} binary, which allows creating tap devices on an existing bridge.<br />
<br />
{{Tip|See [[Network bridge]] for information on creating bridge.}}<br />
<br />
First, create a configuration file containing the names of all bridges to be used by QEMU:<br />
<br />
{{hc|/etc/qemu/bridge.conf|<br />
allow ''bridge0''<br />
allow ''bridge1''<br />
...}}<br />
<br />
Now start the VM. The most basic usage would be:<br />
<br />
$ qemu-system-i386 -net nic -net bridge,br=''bridge0'' ''[...]''<br />
<br />
With multiple taps, the most basic usage requires specifying the VLAN for all additional NICs:<br />
<br />
$ qemu-system-i386 -net nic -net bridge,br=''bridge0'' -net nic,vlan=1 -net bridge,vlan=1,br=''bridge1'' ''[...]''<br />
<br />
==== Creating bridge manually ====<br />
<br />
{{Poor writing|This section needs serious cleanup and may contain out-of-date information.}}<br />
<br />
{{Tip|Since QEMU 1.1, the [http://wiki.qemu.org/Features/HelperNetworking network bridge helper] can set tun/tap up for you without the need for additional scripting. See [[#Bridged networking using qemu-bridge-helper]].}}<br />
<br />
The following describes how to bridge a virtual machine to a host interface such as {{ic|eth0}}, which is probably the most common configuration. This configuration makes it appear that the virtual machine is located directly on the external network, on the same Ethernet segment as the physical host machine.<br />
<br />
We will replace the normal Ethernet adapter with a bridge adapter and bind the normal Ethernet adapter to it.<br />
<br />
* Install {{Pkg|bridge-utils}}, which provides {{ic|brctl}} to manipulate bridges.<br />
<br />
* Enable IPv4 forwarding:<br />
# sysctl net.ipv4.ip_forward=1<br />
<br />
To make the change permanent, change {{ic|1=net.ipv4.ip_forward = 0}} to {{ic|1=net.ipv4.ip_forward = 1}} in {{ic|/etc/sysctl.d/99-sysctl.conf}}.<br />
<br />
* Load the {{ic|tun}} module and configure it to be loaded on boot. See [[Kernel modules]] for details.<br />
<br />
* Now create the bridge. See [[Bridge with netctl]] for details. Remember to name your bridge as {{ic|br0}}, or change the scripts below to your bridge's name.<br />
<br />
* Create the script that QEMU uses to bring up the tap adapter with {{ic|root:kvm}} 750 permissions:<br />
{{hc|/etc/qemu-ifup|<nowiki><br />
#!/bin/sh<br />
<br />
echo "Executing /etc/qemu-ifup"<br />
echo "Bringing up $1 for bridged mode..."<br />
sudo /usr/bin/ip link set $1 up promisc on<br />
echo "Adding $1 to br0..."<br />
sudo /usr/bin/brctl addif br0 $1<br />
sleep 2<br />
</nowiki>}}<br />
<br />
* Create the script that QEMU uses to bring down the tap adapter in {{ic|/etc/qemu-ifdown}} with {{ic|root:kvm}} 750 permissions:<br />
{{hc|/etc/qemu-ifdown|<nowiki><br />
#!/bin/sh<br />
<br />
echo "Executing /etc/qemu-ifdown"<br />
sudo /usr/bin/ip link set $1 down<br />
sudo /usr/bin/brctl delif br0 $1<br />
sudo /usr/bin/ip link delete dev $1<br />
</nowiki>}}<br />
<br />
* Use {{ic|visudo}} to add the following to your {{ic|sudoers}} file:<br />
{{bc|<nowiki><br />
Cmnd_Alias QEMU=/usr/bin/ip,/usr/bin/modprobe,/usr/bin/brctl<br />
%kvm ALL=NOPASSWD: QEMU<br />
</nowiki>}}<br />
<br />
* You launch QEMU using the following {{ic|run-qemu}} script:<br />
{{hc|run-qemu|<nowiki><br />
#!/bin/bash<br />
USERID=$(whoami)<br />
<br />
# Get name of newly created TAP device; see https://bbs.archlinux.org/viewtopic.php?pid=1285079#p1285079<br />
precreationg=$(/usr/bin/ip tuntap list | /usr/bin/cut -d: -f1 | /usr/bin/sort)<br />
sudo /usr/bin/ip tuntap add user $USERID mode tap<br />
postcreation=$(/usr/bin/ip tuntap list | /usr/bin/cut -d: -f1 | /usr/bin/sort)<br />
IFACE=$(comm -13 <(echo "$precreationg") <(echo "$postcreation"))<br />
<br />
# This line creates a random MAC address. The downside is the DHCP server will assign a different IP address each time<br />
printf -v macaddr "52:54:%02x:%02x:%02x:%02x" $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff )) $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff ))<br />
# Instead, uncomment and edit this line to set a static MAC address. The benefit is that the DHCP server will assign the same IP address.<br />
# macaddr='52:54:be:36:42:a9'<br />
<br />
qemu-system-i386 -net nic,macaddr=$macaddr -net tap,ifname="$IFACE" $*<br />
<br />
sudo ip link set dev $IFACE down &> /dev/null<br />
sudo ip tuntap del $IFACE mode tap &> /dev/null<br />
</nowiki>}}<br />
<br />
Then to launch a VM, do something like this<br />
$ run-qemu -hda ''myvm.img'' -m 512 -vga std<br />
<br />
* It is recommended for performance and security reasons to disable the [http://ebtables.netfilter.org/documentation/bridge-nf.html firewall on the bridge]:<br />
{{hc|/etc/sysctl.d/10-disable-firewall-on-bridge.conf|<nowiki><br />
net.bridge.bridge-nf-call-ip6tables = 0<br />
net.bridge.bridge-nf-call-iptables = 0<br />
net.bridge.bridge-nf-call-arptables = 0<br />
</nowiki>}}<br />
Run {{ic|sysctl -p /etc/sysctl.d/10-disable-firewall-on-bridge.conf}} to apply the changes immediately.<br />
<br />
See the [http://wiki.libvirt.org/page/Networking#Creating_network_initscripts libvirt wiki] and [https://bugzilla.redhat.com/show_bug.cgi?id=512206 Fedora bug 512206]. If you get errors by sysctl during boot about non-existing files, make the {{ic|bridge}} module load at boot. See [[Kernel modules#Automatic module handling]].<br />
<br />
Alternatively, you can configure [[iptables]] to allow all traffic to be forwarded across the bridge by adding a rule like this:<br />
-I FORWARD -m physdev --physdev-is-bridged -j ACCEPT<br />
<br />
==== Network sharing between physical device and a Tap device through iptables ====<br />
<br />
{{Merge|Internet_sharing|Duplication, not specific to QEMU.}}<br />
<br />
Bridged networking works fine between a wired interface (Eg. eth0), and it is easy to setup. However if the host gets connected to the network through a wireless device, then bridging is not possible.<br />
<br />
See [[Network bridge#Wireless interface on a bridge]] as a reference.<br />
<br />
One way to overcome that is to setup a tap device with a static IP, making linux automatically handle the routing for it, and then forward traffic between the tap interface and the device connected to the network through iptables rules.<br />
<br />
See [[Internet sharing]] as a reference.<br />
<br />
There you can find what is needed to share the network between devices, included tap and tun ones. The following just hints further on some of the host configurations required. As indicated in the reference above, the client needs to be configured for a static IP, using the IP assigned to the tap interface as the gateway. The caveat is that the DNS servers on the client might need to be manually edited if they change when changing from one host device connected to the network to another.<br />
<br />
To allow IP forwarding on every boot, one need to add the following lines to sysctl configuration file inside /etc/sysctl.d:<br />
<br />
net.ipv4.ip_forward = 1<br />
net.ipv6.conf.default.forwarding = 1<br />
net.ipv6.conf.all.forwarding = 1<br />
<br />
The iptables rules can look like:<br />
<br />
# Forwarding from/to outside<br />
iptables -A FORWARD -i ${INT} -o ${EXT_0} -j ACCEPT<br />
iptables -A FORWARD -i ${INT} -o ${EXT_1} -j ACCEPT<br />
iptables -A FORWARD -i ${INT} -o ${EXT_2} -j ACCEPT<br />
iptables -A FORWARD -i ${EXT_0} -o ${INT} -j ACCEPT<br />
iptables -A FORWARD -i ${EXT_1} -o ${INT} -j ACCEPT<br />
iptables -A FORWARD -i ${EXT_2} -o ${INT} -j ACCEPT<br />
# NAT/Masquerade (network address translation)<br />
iptables -t nat -A POSTROUTING -o ${EXT_0} -j MASQUERADE<br />
iptables -t nat -A POSTROUTING -o ${EXT_1} -j MASQUERADE<br />
iptables -t nat -A POSTROUTING -o ${EXT_2} -j MASQUERADE<br />
<br />
The prior supposes there are 3 devices connected to the network sharing traffic with one internal device, where for example:<br />
<br />
INT=tap0<br />
EXT_0=eth0<br />
EXT_1=wlan0<br />
EXT_2=tun0<br />
<br />
The prior shows a forwarding that would allow sharing wired and wireless connections with the tap device.<br />
<br />
The forwarding rules shown are stateless, and for pure forwarding. One could think of restricting specific traffic, putting a firewall in place to protect the guest and others. However those would decrease the networking performance, while a simple bridge does not include any of that.<br />
<br />
Bonus: Whether the connection is wired or wireless, if one gets connected through VPN to a remote site with a tun device, supposing the tun device opened for that connection is tun0, and the prior iptables rules are applied, then the remote connection gets also shared with the guest. This avoids the need for the guest to also open a VPN connection. Again, as the guest networking needs to be static, then if connecting the host remotely this way, one most probably will need to edit the DNS servers on the guest.<br />
<br />
=== Networking with VDE2 ===<br />
<br />
{{Poor writing|This section needs serious cleanup and may contain out-of-date information.}}<br />
<br />
==== What is VDE? ====<br />
<br />
VDE stands for Virtual Distributed Ethernet. It started as an enhancement of [[User-mode Linux|uml]]_switch. It is a toolbox to manage virtual networks.<br />
<br />
The idea is to create virtual switches, which are basically sockets, and to "plug" both physical and virtual machines in them. The configuration we show here is quite simple; However, VDE is much more powerful than this, it can plug virtual switches together, run them on different hosts and monitor the traffic in the switches. You are invited to read [http://wiki.virtualsquare.org/wiki/index.php/Main_Page the documentation of the project].<br />
<br />
The advantage of this method is you do not have to add sudo privileges to your users. Regular users should not be allowed to run modprobe.<br />
<br />
==== Basics ====<br />
<br />
VDE support can be [[pacman|installed]] via the {{Pkg|vde2}} package in the [[official repositories]].<br />
<br />
In our config, we use tun/tap to create a virtual interface on my host. Load the {{ic|tun}} module (see [[Kernel modules]] for details):<br />
<br />
# modprobe tun<br />
<br />
Now create the virtual switch:<br />
<br />
# vde_switch -tap tap0 -daemon -mod 660 -group users<br />
<br />
This line creates the switch, creates {{ic|tap0}}, "plugs" it, and allows the users of the group {{ic|users}} to use it.<br />
<br />
The interface is plugged in but not configured yet. To configure it, run this command:<br />
<br />
# ip addr add 192.168.100.254/24 dev tap0<br />
<br />
Now, you just have to run KVM with these {{ic|-net}} options as a normal user:<br />
<br />
$ qemu-system-i386 -net nic -net vde -hda ''[...]''<br />
<br />
Configure networking for your guest as you would do in a physical network.<br />
<br />
{{Tip|You might want to set up NAT on tap device to access the internet from the virtual machine. See [[Internet sharing#Enable NAT]] for more information.}}<br />
<br />
==== Startup scripts ====<br />
<br />
Example of main script starting VDE:<br />
<br />
{{hc|/etc/systemd/scripts/qemu-network-env|<nowiki><br />
#!/bin/sh<br />
# QEMU/VDE network environment preparation script<br />
<br />
# The IP configuration for the tap device that will be used for<br />
# the virtual machine network:<br />
<br />
TAP_DEV=tap0<br />
TAP_IP=192.168.100.254<br />
TAP_MASK=24<br />
TAP_NETWORK=192.168.100.0<br />
<br />
# Host interface<br />
NIC=eth0<br />
<br />
case "$1" in<br />
start)<br />
echo -n "Starting VDE network for QEMU: "<br />
<br />
# If you want tun kernel module to be loaded by script uncomment here<br />
#modprobe tun 2>/dev/null<br />
## Wait for the module to be loaded<br />
#while ! lsmod | grep -q "^tun"; do echo "Waiting for tun device"; sleep 1; done<br />
<br />
# Start tap switch<br />
vde_switch -tap "$TAP_DEV" -daemon -mod 660 -group users<br />
<br />
# Bring tap interface up<br />
ip address add "$TAP_IP"/"$TAP_MASK" dev "$TAP_DEV"<br />
ip link set "$TAP_DEV" up<br />
<br />
# Start IP Forwarding<br />
echo "1" > /proc/sys/net/ipv4/ip_forward<br />
iptables -t nat -A POSTROUTING -s "$TAP_NETWORK"/"$TAP_MASK" -o "$NIC" -j MASQUERADE<br />
;;<br />
stop)<br />
echo -n "Stopping VDE network for QEMU: "<br />
# Delete the NAT rules<br />
iptables -t nat -D POSTROUTING "$TAP_NETWORK"/"$TAP_MASK" -o "$NIC" -j MASQUERADE<br />
<br />
# Bring tap interface down<br />
ip link set "$TAP_DEV" down<br />
<br />
# Kill VDE switch<br />
pgrep -f vde_switch | xargs kill -TERM<br />
;;<br />
restart|reload)<br />
$0 stop<br />
sleep 1<br />
$0 start<br />
;;<br />
*)<br />
echo "Usage: $0 {start|stop|restart|reload}"<br />
exit 1<br />
esac<br />
exit 0<br />
</nowiki>}}<br />
<br />
Example of systemd service using the above script:<br />
<br />
{{hc|/etc/systemd/system/qemu-network-env.service|<nowiki><br />
[Unit]<br />
Description=Manage VDE Switch<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/etc/systemd/scripts/qemu-network-env start<br />
ExecStop=/etc/systemd/scripts/qemu-network-env stop<br />
RemainAfterExit=yes<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
Change permissions for {{ic|qemu-network-env}} to be executable<br />
<br />
# chmod u+x /etc/systemd/scripts/qemu-network-env<br />
<br />
You can [[start]] {{ic|qemu-network-env.service}} as usual.<br />
<br />
====Alternative method====<br />
<br />
If the above method does not work or you do not want to mess with kernel configs, TUN, dnsmasq, and iptables you can do the following for the same result.<br />
<br />
# vde_switch -daemon -mod 660 -group users<br />
# slirpvde --dhcp --daemon<br />
<br />
Then, to start the VM with a connection to the network of the host:<br />
<br />
$ qemu-system-i386 -net nic,macaddr=52:54:00:00:EE:03 -net vde ''disk_image''<br />
<br />
=== VDE2 Bridge ===<br />
<br />
Based on [http://selamatpagicikgu.wordpress.com/2011/06/08/quickhowto-qemu-networking-using-vde-tuntap-and-bridge/ quickhowto: qemu networking using vde, tun/tap, and bridge] graphic. Any virtual machine connected to vde is externally exposed. For example, each virtual machine can receive DHCP configuration directly from your ADSL router.<br />
<br />
==== Basics ====<br />
<br />
Remember that you need {{ic|tun}} module and {{Pkg|bridge-utils}} package.<br />
<br />
Create the vde2/tap device:<br />
<br />
# vde_switch -tap tap0 -daemon -mod 660 -group users<br />
# ip link set tap0 up<br />
<br />
Create bridge:<br />
<br />
# brctl addbr br0<br />
<br />
Add devices:<br />
<br />
# brctl addif br0 eth0<br />
# brctl addif br0 tap0<br />
<br />
And configure bridge interface:<br />
<br />
# dhcpcd br0<br />
<br />
==== Startup scripts ====<br />
<br />
All devices must be set up. And only the bridge needs an IP address. For physical devices on the bridge (e.g. {{ic|eth0}}), this can be done with [[netctl]] using a custom Ethernet profile with:<br />
<br />
{{hc|/etc/netctl/ethernet-noip|<nowiki><br />
Description='A more versatile static Ethernet connection'<br />
Interface=eth0<br />
Connection=ethernet<br />
IP=no<br />
</nowiki>}}<br />
<br />
The following custom systemd service can be used to create and activate a VDE2 tap interface for use in the {{ic|users}} user group.<br />
<br />
{{hc|/etc/systemd/system/vde2@.service|<nowiki><br />
[Unit]<br />
Description=Network Connectivity for %i<br />
Wants=network.target<br />
Before=network.target<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
ExecStart=/usr/bin/vde_switch -tap %i -daemon -mod 660 -group users<br />
ExecStart=/usr/bin/ip link set dev %i up<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 />
And finally, you can create the [[Bridge with netctl|bridge interface with netctl]].<br />
<br />
== Graphics ==<br />
<br />
QEMU can use the following different graphic outputs: {{ic|std}}, {{ic|qxl}}, {{ic|vmware}}, {{ic|virtio}}, {{ic|cirrus}} and {{ic|none}}.<br />
<br />
=== std ===<br />
<br />
With {{ic|-vga std}} you can get a resolution of up to 2560 x 1600 pixels without requiring guest drivers. This is the default since QEMU 2.2.<br />
<br />
=== qxl ===<br />
<br />
QXL is a paravirtual graphics driver with 2D support. To use it, pass the {{ic|-vga qxl}} option and install drivers in the guest. You may want to use SPICE for improved graphical performance when using QXL.<br />
<br />
On Linux guests, the {{ic|qxl}} and {{ic|bochs_drm}} kernel modules must be loaded in order to gain a decent performance.<br />
<br />
==== SPICE ====<br />
The [http://spice-space.org/ SPICE project] aims to provide a complete open source solution for remote access to virtual machines in a seamless way.<br />
<br />
SPICE can only be used when using QXL as the graphical output.<br />
<br />
The following is example of booting with SPICE as the remote desktop protocol:<br />
<br />
$ qemu-system-i386 -vga qxl -spice port=5930,disable-ticketing -chardev spicevm <br />
<br />
Connect to the guest by using a SPICE client. At the moment {{Pkg|spice-gtk3}} is recommended, however other [http://www.spice-space.org/download.html clients], including other platforms, are available:<br />
<br />
$ spicy -h 127.0.0.1 -p 5930<br />
<br />
Using [[wikipedia:Unix_socket|Unix sockets]] instead of TCP ports does not involve using network stack on the host system, so it is [https://unix.stackexchange.com/questions/91774/performance-of-unix-sockets-vs-tcp-ports reportedly] better for performance. Example:<br />
$ qemu-system-x86_64 -vga qxl -device virtio-serial-pci -device virtserialport,chardev=spicechannel0,name=com.redhat.spice.0 -chardev spicevmc,id=spicechannel0,name=vdagent -spice unix,addr=/tmp/vm_spice.socket,disable-ticketing,playback-compression=off<br />
$ spicy --uri="spice+unix:///tmp/vm_spice.socket"<br />
<br />
For improved support for multiple monitors, clipboard sharing, etc. the following packages should be installed on the guest:<br />
* {{AUR|spice-vdagent}}: Spice agent xorg client that enables copy and paste between client and X-session and more<br />
* {{AUR|xf86-video-qxl}} {{AUR|xf86-video-qxl-git}}: Xorg X11 qxl video driver<br />
* For other operating systems, see the Guest section on [http://www.spice-space.org/download.html SPICE-Space download] page.<br />
<br />
=== vmware ===<br />
<br />
Although it is a bit buggy, it performs better than std and cirrus. Install the VMware drivers ({{Pkg|xf86-video-vmware}} and {{Pkg|xf86-input-vmmouse}} for Arch Linux guests.<br />
<br />
=== virtio ===<br />
<br />
{{ic|virtio-vga}} / {{ic|virtio-gpu}} is a paravirtual 3D graphics driver based on [https://virgil3d.github.io/ virgl]. Currently a work in progress, supporting only very recent (>= 4.4) Linux guests.<br />
<br />
=== cirrus ===<br />
<br />
The cirrus graphical adapter was the default [http://wiki.qemu.org/ChangeLog/2.2#VGA before 2.2]. It [https://www.kraxel.org/blog/2014/10/qemu-using-cirrus-considered-harmful/ should not] be used on modern systems.<br />
<br />
=== none ===<br />
<br />
This is like a PC that has no VGA card at all. You would not even be able to access it with the {{ic|-vnc}} option. Also, this is different from the {{ic|-nographic}} option which lets QEMU emulate a VGA card, but disables the SDL display.<br />
<br />
=== vnc ===<br />
<br />
Given that you used the {{ic|-nographic}} option, you can add the {{ic|-vnc display}} option to have QEMU listen on {{ic|display}} and redirect the VGA display to the VNC session. There is an example of this in the [[#Starting QEMU virtual machines on boot]] section's example configs.<br />
<br />
$ qemu-system-i386 -vga std -nographic -vnc :0<br />
$ gvncviewer :0<br />
<br />
When using VNC, you might experience keyboard problems described (in gory details) [https://www.berrange.com/posts/2010/07/04/more-than-you-or-i-ever-wanted-to-know-about-virtual-keyboard-handling/ here]. The solution is ''not'' to use the {{ic|-k}} option on QEMU, and to use {{ic|gvncviewer}} from {{Pkg|gtk-vnc}}. See also [http://www.mail-archive.com/libvir-list@redhat.com/msg13340.html this] message posted on libvirt's mailing list.<br />
<br />
== Installing virtio drivers ==<br />
<br />
QEMU offers guests the ability to use paravirtualized block and network devices using the [http://wiki.libvirt.org/page/Virtio virtio] drivers, which provide better performance and lower overhead.<br />
<br />
* A virtio block device requires the option {{Ic|-drive}} instead of the simple {{Ic|-hd*}} plus {{Ic|1=if=virtio}}:<br />
$ qemu-system-i386 -boot order=c -drive file=''disk_image'',if=virtio<br />
<br />
{{Note|{{Ic|1=-boot order=c}} is absolutely necessary when you want to boot from it. There is no auto-detection as with {{Ic|-hd*}}.}}<br />
<br />
* Almost the same goes for the network:<br />
$ qemu-system-i386 -net nic,model=virtio<br />
<br />
{{Note|This will only work if the guest machine has drivers for virtio devices. Linux does, and the required drivers are included in Arch Linux, but there is no guarantee that virtio devices will work with other operating systems.}}<br />
<br />
=== Preparing an (Arch) Linux guest ===<br />
<br />
To use virtio devices after an Arch Linux guest has been installed, the following modules must be loaded in the guest: {{Ic|virtio}}, {{Ic|virtio_pci}}, {{Ic|virtio_blk}}, {{Ic|virtio_net}}, and {{Ic|virtio_ring}}. For 32-bit guests, the specific "virtio" module is not necessary.<br />
<br />
If you want to boot from a virtio disk, the initial ramdisk must contain the necessary modules. By default, this is handled by [[mkinitcpio]]'s {{ic|autodetect}} hook. Otherwise use the {{ic|MODULES}} array in {{ic|/etc/mkinitcpio.conf}} to include the necessary modules and rebuild the initial ramdisk.<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
MODULES="virtio virtio_blk virtio_pci virtio_net"}}<br />
<br />
Virtio disks are recognized with the prefix {{ic|'''v'''}} (e.g. {{ic|'''v'''da}}, {{ic|'''v'''db}}, etc.); therefore, changes must be made in at least {{ic|/etc/fstab}} and {{ic|/boot/grub/grub.cfg}} when booting from a virtio disk.<br />
<br />
{{Tip|When referencing disks by [[UUID]] in both {{ic|/etc/fstab}} and bootloader, nothing has to be done.}}<br />
<br />
Further information on paravirtualization with KVM can be found [http://www.linux-kvm.org/page/Boot_from_virtio_block_device here].<br />
<br />
You might also want to install {{Pkg|qemu-guest-agent}} to implement support for QMP commands that will enhance the hypervisor management capabilities. After installing the package you can enable and start the {{ic|qemu-ga.service}}.<br />
<br />
=== Preparing a Windows guest ===<br />
<br />
{{Note|1=The only (reliable) way to upgrade a Windows 8.1 guest to Windows 10 seems to be to temporarily choose cpu core2duo,nx for the install [http://ubuntuforums.org/showthread.php?t=2289210]. After the install, you may revert to other cpu settings (8/8/2015).}}<br />
<br />
==== Block device drivers ====<br />
<br />
===== New Install of Windows =====<br />
<br />
Windows does not come with the virtio drivers. Therefore, you will need to load them during installation. There are basically two ways to do this: via Floppy Disk or via ISO files. Both images can be downloaded from the [https://fedoraproject.org/wiki/Windows_Virtio_Drivers Fedora repository].<br />
<br />
The floppy disk option is difficult because you will need to press F6 (Shift-F6 on newer Windows) at the very beginning of powering on the QEMU. This is difficult since you need time to connect your VNC console window. You can attempt to add a delay to the boot sequence. See {{ic|man qemu-system}} for more details about applying a delay at boot.<br />
<br />
The ISO option to load drivers is the preferred way, but it is available only on Windows Vista and Windows Server 2008 and later. The procedure is to load the image with virtio drivers in an additional cdrom device along with the primary disk device and Windows installer:<br />
<br />
$ qemu-system-i386 ... \<br />
-drive file=''/path/to/primary/disk.img'',index=0,media=disk,if=virtio \<br />
-drive file=''/path/to/installer.iso'',index=2,media=cdrom \<br />
-drive file=''/path/to/virtio.iso'',index=3,media=cdrom \<br />
...<br />
<br />
During the installation, the Windows installer will ask you for your Product key and perform some additional checks. When it gets to the "Where do you want to install Windows?" screen, it will give a warning that no disks are found. Follow the example instructions below (based on Windows Server 2012 R2 with Update).<br />
<br />
* Select the option {{ic|Load Drivers}}.<br />
* Uncheck the box for "Hide drivers that aren't compatible with this computer's hardware".<br />
* Click the Browse button and open the CDROM for the virtio iso, usually named "virtio-win-XX".<br />
* Now browse to {{ic|E:\viostor\[your-os]\amd64}}, select it, and press OK.<br />
* Click Next<br />
<br />
You should now see your virtio disk(s) listed here, ready to be selected, formatted and installed to.<br />
<br />
===== Change Existing Windows VM to use virtio =====<br />
Modifying an existing Windows guest for booting from virtio disk is a bit tricky.<br />
<br />
You can download the virtio disk driver from the [https://fedoraproject.org/wiki/Windows_Virtio_Drivers Fedora repository].<br />
<br />
Now you need to create a new disk image, which fill force Windows to search for the driver. For example:<br />
<br />
$ qemu-img create -f qcow2 ''fake.qcow2'' 1G<br />
<br />
Run the original Windows guest (with the boot disk still in IDE mode) with the fake disk (in virtio mode) and a CD-ROM with the driver.<br />
<br />
$ qemu-system-i386 -m 512 -vga std -drive file=''windows_disk_image'',if=ide -drive file=''fake.qcow2'',if=virtio -cdrom virtio-win-0.1-81.iso<br />
<br />
Windows will detect the fake disk and try to find a driver for it. If it fails, go to the ''Device Manager'', locate the SCSI drive with an exclamation mark icon (should be open), click ''Update driver'' and select the virtual CD-ROM. Do not forget to select the checkbox which says to search for directories recursively.<br />
<br />
When the installation is successful, you can turn off the virtual machine and launch it again, now with the boot disk attached in virtio mode:<br />
<br />
$ qemu-system-i386 -m 512 -vga std -drive file=''windows_disk_image'',if=virtio<br />
<br />
{{Note|If you encounter the Blue Screen of Death, make sure you did not forget the {{ic|-m}} parameter, and that you do not boot with virtio instead of ide for the system drive before drivers are installed.}}<br />
<br />
==== Network drivers ====<br />
<br />
Installing virtio network drivers is a bit easier, simply add the {{ic|-net}} argument as explained above.<br />
<br />
$ qemu-system-i386 -m 512 -vga std -drive file=''windows_disk_image'',if=virtio -net nic,model=virtio -cdrom virtio-win-0.1-74.iso<br />
<br />
Windows will detect the network adapter and try to find a driver for it. If it fails, go to the ''Device Manager'', locate the network adapter with an exclamation mark icon (should be open), click ''Update driver'' and select the virtual CD-ROM. Do not forget to select the checkbox which says to search for directories recursively.<br />
<br />
=== Preparing a FreeBSD guest ===<br />
<br />
Install the {{ic|emulators/virtio-kmod}} port if you are using FreeBSD 8.3 or later up until 10.0-CURRENT where they are included into the kernel. After installation, add the following to your {{ic|/boot/loader.conf}} file:<br />
<br />
{{bc|<nowiki><br />
virtio_loader="YES"<br />
virtio_pci_load="YES"<br />
virtio_blk_load="YES"<br />
if_vtnet_load="YES"<br />
virtio_balloon_load="YES"<br />
</nowiki>}}<br />
<br />
Then modify your {{ic|/etc/fstab}} by doing the following:<br />
<br />
{{bc|<nowiki><br />
sed -i bak "s/ada/vtbd/g" /etc/fstab<br />
</nowiki>}}<br />
<br />
And verify that {{ic|/etc/fstab}} is consistent. If anything goes wrong, just boot into a rescue CD and copy {{ic|/etc/fstab.bak}} back to {{ic|/etc/fstab}}.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Starting QEMU virtual machines on boot ===<br />
<br />
==== With libvirt ====<br />
<br />
If a virtual machine is set up with [[libvirt]], it can be configured through the virt-manager GUI to start at host boot by going to the Boot Options for the virtual machine and selecting "Start virtual machine on host boot up".<br />
<br />
==== Custom script ====<br />
<br />
To run QEMU VMs on boot, you can use following systemd unit and config.<br />
<br />
{{hc|/etc/systemd/system/qemu@.service|<nowiki><br />
[Unit]<br />
Description=QEMU virtual machine<br />
<br />
[Service]<br />
Environment="type=system-x86_64" "haltcmd=kill -INT $MAINPID"<br />
EnvironmentFile=/etc/conf.d/qemu.d/%i<br />
ExecStart=/usr/bin/env qemu-${type} -name %i -nographic $args<br />
ExecStop=/bin/sh -c ${haltcmd}<br />
TimeoutStopSec=30<br />
KillMode=none<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
{{Note|According to {{ic|systemd.service(5)}} and {{ic|systemd.kill(5)}} man pages it is necessary to use the {{ic|1=KillMode=none}} option. Otherwise the main qemu process will be killed immediately after the {{ic|ExecStop}} command quits (it simply echoes one string) and your quest system will not be able to shutdown correctly.}}<br />
<br />
Then create per-VM configuration files, named {{ic|/etc/conf.d/qemu.d/''vm_name''}}, with the following variables set:<br />
<br />
; type<br />
: QEMU binary to call. If specified, will be prepended with {{ic|/usr/bin/qemu-}} and that binary will be used to start the VM. I.e. you can boot e.g. {{ic|qemu-system-arm}} images with {{ic|1=type="system-arm"}}.<br />
; args<br />
: QEMU command line to start with. Will always be prepended with {{ic|-name ${vm} -nographic}}.<br />
; haltcmd<br />
: Command to shut down a VM safely. I am using {{ic|-monitor telnet:..}} and power off my VMs via ACPI by sending {{ic|system_powerdown}} to monitor. You can use SSH or some other ways.<br />
<br />
Example configs:<br />
<br />
{{hc|/etc/conf.d/qemu.d/one|<nowiki><br />
type="system-x86_64"<br />
<br />
args="-enable-kvm -m 512 -hda /dev/mapper/vg0-vm1 -net nic,macaddr=DE:AD:BE:EF:E0:00 \<br />
-net tap,ifname=tap0 -serial telnet:localhost:7000,server,nowait,nodelay \<br />
-monitor telnet:localhost:7100,server,nowait,nodelay -vnc :0"<br />
<br />
haltcmd="echo 'system_powerdown' | nc localhost 7100" # or netcat/ncat<br />
<br />
# You can use other ways to shut down your VM correctly<br />
#haltcmd="ssh powermanager@vm1 sudo poweroff"<br />
</nowiki>}}<br />
<br />
{{hc|/etc/conf.d/qemu.d/two|<nowiki><br />
args="-enable-kvm -m 512 -hda /srv/kvm/vm2.img -net nic,macaddr=DE:AD:BE:EF:E0:01 \<br />
-net tap,ifname=tap1 -serial telnet:localhost:7001,server,nowait,nodelay \<br />
-monitor telnet:localhost:7101,server,nowait,nodelay -vnc :1"<br />
<br />
haltcmd="echo 'system_powerdown' | nc localhost 7101"<br />
</nowiki>}}<br />
<br />
To set which virtual machines will start on boot-up, [[enable]] the {{ic|qemu@''vm_name''.service}} systemd unit.<br />
<br />
=== Mouse integration ===<br />
<br />
To prevent the mouse from being grabbed when clicking on the guest operating system's window, add the option {{ic|-usbdevice tablet}}. This means QEMU is able to report the mouse position without having to grab the mouse. This also overrides PS/2 mouse emulation when activated. For example:<br />
<br />
$ qemu-system-i386 -hda ''disk_image'' -m 512 -vga std -usbdevice tablet<br />
<br />
If that does not work, try the tip at [[#Mouse cursor is jittery or erratic]].<br />
<br />
=== Pass-through host USB device ===<br />
<br />
To access physical USB device connected to host from VM, you can start QEMU with following option:<br />
<br />
$ qemu-system-i386 -usbdevice host:''vendor_id'':''product_id'' ''disk_image''<br />
<br />
You can find {{ic|vendor_id}} and {{ic|product_id}} of your device with {{ic|lsusb}} command.<br />
<br />
{{Note|If you encounter permission errors when running QEMU, see [[Udev#Writing udev rules]] for information on how to set permissions of the device.}}<br />
<br />
=== Enabling KSM ===<br />
<br />
Kernel Samepage Merging (KSM) is a feature of the Linux kernel that allows for an application to register with the kernel to have its pages merged with other processes that also register to have their pages merged. The KSM mechanism allows for guest virtual machines to share pages with each other. In an environment where many of the guest operating systems are similar, this can result in significant memory savings.<br />
<br />
To enable KSM, simply run<br />
<br />
# echo 1 > /sys/kernel/mm/ksm/run<br />
<br />
To make it permanent, you can use [[systemd#Temporary files|systemd's temporary files]]:<br />
<br />
{{hc|/etc/tmpfiles.d/ksm.conf|<br />
w /sys/kernel/mm/ksm/run - - - - 1<br />
}}<br />
<br />
If KSM is running, and there are pages to be merged (i.e. at least two similar VMs are running), then {{ic|/sys/kernel/mm/ksm/pages_shared}} should be non-zero. See https://www.kernel.org/doc/Documentation/vm/ksm.txt for more information.<br />
<br />
{{Tip|An easy way to see how well KSM is performing is to simply print the contents of all the files in that directory: {{bc|$ grep . /sys/kernel/mm/ksm/*}}}}<br />
<br />
=== Multi-monitor support ===<br />
The Linux QXL driver supports four heads (virtual screens) by default. This can be changed via the {{ic|1=qxl.heads=N}} kernel parameter.<br />
<br />
The default VGA memory size for QXL devices is 16M (VRAM size is 64M). This is not sufficient if you would like to enable two 1920x1200 monitors since that requires 2 × 1920 × 4 (color depth) × 1200 = 17.6 MiB VGA memory. This can be changed by replacing {{ic|-vga qxl}} by {{ic|<nowiki>-vga none -device qxl-vga,vgamem_mb=32</nowiki>}}. If you ever increase vgamem_mb beyond 64M, then you also have to increase the {{ic|vram_size_mb}} option.<br />
<br />
=== Copy and paste ===<br />
<br />
To have copy and paste between the host and the guest you need to enable the spice agent communication channel. It requires to add a virtio-serial device to the guest, and open a port for the spice vdagent. It is also required to install the spice vdagent in guest ({{AUR|spice-vdagent}} for Arch guests, [http://www.spice-space.org/download.html Windows guest tools] for Windows guests). Make sure the agent is running (and for future, started automatically).<br />
<br />
Start QEMU with the following options:<br />
<br />
$ qemu-system-i386 -vga qxl -spice port=5930,disable-ticketing -device virtio-serial-pci -device virtserialport,chardev=spicechannel0,name=com.redhat.spice.0 -chardev spicevmc,id=spicechannel0,name=vdagent<br />
<br />
The {{ic|-device virtio-serial-pci}} option adds the virtio-serial device, {{ic|1=-device virtserialport,chardev=spicechannel0,name=com.redhat.spice.0}} opens a port for spice vdagent in that device and {{ic|1=-chardev spicevmc,id=spicechannel0,name=vdagent}} adds a spicevmc chardev for that port.<br />
<br />
It is important that the {{ic|1=chardev=}} option of the {{ic|virtserialport}} device matches the {{ic|1=id=}} option given to the {{ic|chardev}} option ({{ic|spicechannel0}} in this example). It is also important that the port name is {{ic|com.redhat.spice.0}}, because that is the namespace where vdagent is looking for in the guest. And finally, specify {{ic|1=name=vdagent}} so that spice knows what this channel is for.<br />
<br />
=== Windows-specific notes ===<br />
<br />
QEMU can run any version of Windows from Windows 95 through Windows 10.<br />
<br />
It is possible to run [[Windows PE]] in QEMU.<br />
<br />
==== Fast startup ====<br />
<br />
For Windows 8 (or later) guests it is better to disable "Fast Startup" from the Power Options of the Control Panel, as it causes the guest to hang during every other boot.<br />
<br />
Fast Startup may also need to be disabled for changes to the {{ic|-smp}} option to be properly applied.<br />
<br />
==== Remote Desktop Protocol ====<br />
<br />
If you use a MS Windows guest, you might want to use RDP to connect to your guest VM. If you are using a VLAN or are not in the same network as the guest, use:<br />
<br />
$ qemu-system-i386 -nographic -net user,hostfwd=tcp::5555-:3389<br />
<br />
Then connect with either {{Pkg|rdesktop}} or {{Pkg|freerdp}} to the guest. For example:<br />
<br />
$ xfreerdp -g 2048x1152 localhost:5555 -z -x lan<br />
<br />
== Troubleshooting ==<br />
<br />
=== Mouse cursor is jittery or erratic ===<br />
<br />
If the cursor jumps around the screen uncontrollably, entering this on the terminal before starting QEMU might help:<br />
<br />
$ export SDL_VIDEO_X11_DGAMOUSE=0<br />
<br />
If this helps, you can add this to your {{ic|~/.bashrc}} file.<br />
<br />
=== No visible Cursor ===<br />
<br />
Add {{ic|-show-cursor}} to QEMU's options to see a mouse cursor.<br />
<br />
=== Keyboard seems broken or the arrow keys do not work ===<br />
<br />
Should you find that some of your keys do not work or "press" the wrong key (in particular, the arrow keys), you likely need to specify your keyboard layout as an option. The keyboard layouts can be found in {{ic|/usr/share/qemu/keymaps}}.<br />
<br />
$ qemu-system-i386 -k ''keymap'' ''disk_image''<br />
<br />
=== Virtual machine runs too slowly ===<br />
<br />
There are a number of techniques that you can use to improve the performance if your virtual machine. For example:<br />
<br />
* Use the {{ic|-cpu host}} option to make QEMU emulate the host's exact CPU. If you do not do this, it may be trying to emulate a more generic CPU.<br />
* If the host machine has multiple CPUs, assign the guest more CPUs using the {{ic|-smp}} option.<br />
* Make sure you have assigned the virtual machine enough memory. By default, QEMU only assigns 128 MiB of memory to each virtual machine. Use the {{ic|-m}} option to assign more memory. For example, {{ic|-m 1024}} runs a virtual machine with 1024 MiB of memory.<br />
* Use KVM if possible: add {{ic|1=-machine type=pc,accel=kvm}} to the QEMU start command you use.<br />
* If supported by drivers in the guest operating system, use [http://wiki.libvirt.org/page/Virtio virtio] for network and/or block devices. For example:<br />
$ qemu-system-i386 -net nic,model=virtio -net tap,if=tap0,script=no -drive file=''disk_image'',media=disk,if=virtio<br />
* Use TAP devices instead of user-mode networking. See [[#Tap networking with QEMU]].<br />
* If the guest OS is doing heavy writing to its disk, you may benefit from certain mount options on the host's file system. For example, you can mount an [[Ext4|ext4 file system]] with the option {{ic|1=barrier=0}}. You should read the documentation for any options that you change because sometimes performance-enhancing options for file systems come at the cost of data integrity.<br />
* If you have a raw disk image, you may want to disable the cache:<br />
$ qemu-system-i386 -drive file=''disk_image'',if=virtio,cache=none<br />
* Use the native Linux AIO:<br />
$ qemu-system-i386 -drive file=''disk_image'',if=virtio,aio=native<br />
* If you are running multiple virtual machines concurrently that all have the same operating system installed, you can save memory by enabling [[wikipedia:Kernel_SamePage_Merging_(KSM)|kernel same-page merging]]:<br />
# echo 1 > /sys/kernel/mm/ksm/run<br />
* In some cases, memory can be reclaimed from running virtual machines by running a memory ballooning driver in the guest operating system and launching QEMU with the {{ic|-balloon virtio}} option.<br />
<br />
See http://www.linux-kvm.org/page/Tuning_KVM for more information.<br />
<br />
=== Guest display stretches on window resize ===<br />
<br />
To restore default window size, press {{ic|Ctrl+Alt+u}}.<br />
<br />
=== ioctl(KVM_CREATE_VM) failed: 16 Device or resource busy ===<br />
<br />
If an error message like this is printed when starting QEMU with {{ic|-enable-kvm}} option:<br />
<br />
ioctl(KVM_CREATE_VM) failed: 16 Device or resource busy<br />
failed to initialize KVM: Device or resource busy<br />
<br />
that means another [[hypervisor]] is currently running. It is not recommended or possible to run several hypervisors in parallel.<br />
<br />
=== libgfapi error message ===<br />
<br />
The error message displayed at startup:<br />
<br />
Failed to open module: libgfapi.so.0: cannot open shared object file: No such file or directory<br />
<br />
is not a problem, it just means that you are lacking the optional GlusterFS dependency.<br />
<br />
=== Kernel panic on LIVE-environments===<br />
<br />
If you start a live-environment (or better: booting a system) you may encounter this:<br />
<br />
[ end Kernel panic - not syncing: VFS: Unable to mount root fs on unknown block(0,0)<br />
<br />
or some other boot hindering process (e.g. cannot unpack initramfs, cant start service foo).<br />
Try starting the VM with the {{ic|-m VALUE}} switch and an appropriate amount of RAM, if the ram is to low you will probably encounter similar issues as above/without the memory-switch.<br />
<br />
== See also ==<br />
<br />
* [http://qemu.org Official QEMU website]<br />
* [http://www.linux-kvm.org Official KVM website]<br />
* [http://qemu.weilnetz.de/qemu-doc.html QEMU Emulator User Documentation]<br />
* [https://en.wikibooks.org/wiki/QEMU QEMU Wikibook]<br />
* [http://alien.slackbook.org/dokuwiki/doku.php?id=slackware:qemu Hardware virtualization with QEMU] by AlienBOB (last updated in 2008)<br />
* [http://blog.falconindy.com/articles/build-a-virtual-army.html Building a Virtual Army] by Falconindy<br />
* [http://git.qemu.org/?p=qemu.git;a=tree;f=docs Lastest docs]<br />
* [http://qemu.weilnetz.de/ QEMU on Windows]<br />
* [[wikipedia:Qemu|Wikipedia]]<br />
* [https://wiki.debian.org/QEMU QEMU - Debian Wiki]<br />
* [https://people.gnome.org/~markmc/qemu-networking.html QEMU Networking on gnome.org]<br />
* [http://bsdwiki.reedmedia.net/wiki/networking_qemu_virtual_bsd_systems.html Networking QEMU Virtual BSD Systems]<br />
* [https://www.gnu.org/software/hurd/hurd/running/qemu.html QEMU on gnu.org]<br />
* [https://wiki.freebsd.org/qemu QEMU on FreeBSD as host]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=PRIME&diff=446255PRIME2016-08-11T09:57:14Z<p>Alive4ever: /* PRIME GPU offloading */ simpler provider selection via provider index number instead of provider name</p>
<hr />
<div>[[Category:Graphics]]<br />
[[ja:PRIME]]<br />
[[zh-CN:PRIME]]<br />
PRIME is a technology used to manage hybrid graphics found on recent laptops ([[NVIDIA Optimus|Optimus for NVIDIA]], AMD Dynamic Switchable Graphics for Radeon).<br />
'''PRIME GPU offloading''' and '''Reverse PRIME''' is an attempt to support muxless hybrid graphics in the Linux kernel.<br />
<br />
== Installation ==<br />
<br />
=== Open Source Drivers ===<br />
<br />
Remove any closed-source graphic drivers and replace them with the open source equivalent:<br />
<br />
* {{Pkg|xf86-video-nouveau}}<br />
* {{Pkg|xf86-video-ati}}<br />
* {{Pkg|xf86-video-amdgpu}}<br />
* {{Pkg|xf86-video-intel}}<br />
<br />
Reboot and check the list of attached graphic drivers:<br />
<br />
{{hc|$ xrandr --listproviders|<br />
Providers: number : 2<br />
Provider 0: id: 0x7d cap: 0xb, Source Output, Sink Output, Sink Offload crtcs: 3 outputs: 4 associated providers: 1 name:Intel<br />
Provider 1: id: 0x56 cap: 0xf, Source Output, Sink Output, Source Offload, Sink Offload crtcs: 6 outputs: 1 associated providers: 1 name:radeon<br />
}}<br />
<br />
We can see that there are two graphic cards: Intel, the integrated card (id 0x7d), and Radeon, the discrete card (id 0x56), which should be used for GPU-intensive applications. <br />
<br />
By default the Intel card is always used:<br />
<br />
{{hc|<nowiki>$ glxinfo | grep "OpenGL renderer"</nowiki>|<br />
OpenGL renderer string: Mesa DRI Intel(R) Ivybridge Mobile<br />
}}<br />
<br />
{{Note|Sometimes, the displayed provider is {{ic|"HAINAN @ pci:0000:03:00.0"}}, not {{ic|radeon}}. In this case you should use {{ic|"HAINAN @ pci:0000:03:00.0"}} as the provider in the next command.}}<br />
<br />
=== Closed Source Drivers ===<br />
<br />
[http://us.download.nvidia.com/XFree86/Linux-x86/364.15/README/randr14.html Nvidia's documentation for their 364.15 Linux driver] gives similar information to the [[#Discrete Card as Primary GPU]] section of this article.<br />
<br />
{{Expansion|Add article about support and setup of non-Nvidia closed-source graphic drivers for PRIME}}<br />
<br />
== PRIME GPU offloading ==<br />
<br />
GPU-intensive applications should be rendered on the more powerful discrete card. The command {{ic|xrandr --setprovideroffloadsink provider sink}} can be used to make a render offload provider send its output to the sink provider (the provider which has a display connected). The provider and sink identifiers can be numeric (0x7d, 0x56) or a case-sensitive name (Intel, radeon).<br />
<br />
Example:<br />
<br />
$ xrandr --setprovideroffloadsink radeon Intel<br />
<br />
You may also use provider index instead of provider name which is simpler and easier to type, e.g. :<br />
<br />
$ xrandr --setprovideroffloadsink 1 0<br />
<br />
Now, you can use your discrete card for the applications who need it the most (for example games, 3D modellers...) by prepending the {{ic|DRI_PRIME&#61;1}} environment variable:<br />
<br />
{{hc|<nowiki>$ DRI_PRIME=1 glxinfo | grep "OpenGL renderer"</nowiki>|<br />
OpenGL renderer string: Gallium 0.4 on AMD TURKS<br />
}}<br />
<br />
Other applications will still use the less power-hungry integrated card. These settings are lost once the X server restarts, you may want to make a script and auto-run it at the startup of your desktop environment (alternatively, put it in {{ic|/etc/X11/xinit/xinitrc.d/}}). This may reduce your battery life and increase heat though.<br />
<br />
== Reverse PRIME ==<br />
<br />
If the second GPU has outputs that are not accessible by the primary GPU, you can use '''Reverse PRIME''' to make use of them. This will involve using the primary GPU to render the images, and then pass them off to the secondary GPU.<br />
<br />
In the scenario above, you would do<br />
<br />
$ xrandr --setprovideroutputsource radeon Intel<br />
<br />
When this is done, the discrete card's outputs should be available in xrandr, and you could do something like:<br />
<br />
$ xrandr --output HDMI-1 --auto --above LVDS1<br />
<br />
=== Discrete Card as Primary GPU ===<br />
<br />
Imagine following scenario: The LVDS1 (internal laptop screen) and VGA outputs are both only accessible through the integrated Intel GPU. The HDMI and Display Port outputs are attached to the discrete NVIDIA card. It is possible to use all four outputs by making use of the '''Reverse PRIME''' technology as described above. However the performance might be slow, because all the rendering for all outputs is done by the integrated Intel card. To improve this situation it is possible to do the rendering by the discrete NVIDIA card, which then copies the framebuffers for the LVDS1 and VGA outputs to the Intel card.<br />
<br />
Create the following Xorg configuration:<br />
<br />
{{hc|<nowiki>/etc/X11/xorg.conf.d/10-gpu.conf</nowiki>|<br />
# Discrete Card as Primary GPU<br />
<br />
Section "ServerLayout"<br />
Identifier "layout"<br />
Screen 0 "nouveau"<br />
Inactive "intel"<br />
EndSection<br />
<br />
Section "Device"<br />
Identifier "nouveau"<br />
Driver "nouveau"<br />
BusID "PCI:x:x:x" # Sample: "PCI:1:0:0"<br />
EndSection<br />
<br />
Section "Screen"<br />
Identifier "nouveau"<br />
Device "nouveau"<br />
EndSection<br />
<br />
Section "Device"<br />
Identifier "intel"<br />
Driver "intel"<br />
BusID "PCI:x:x:x" # Sample: "PCI:0:2:0"<br />
EndSection<br />
<br />
Section "Screen"<br />
Identifier "intel"<br />
Device "intel"<br />
EndSection<br />
}}<br />
<br />
Restart Xorg. The discrete NVIDIA card should be used now. The HDMI and Display Port outputs are the main outputs. The LVDS1 and VGA outputs are off. To enable them run:<br />
<br />
$ xrandr --setprovideroutputsource Intel nouveau<br />
<br />
The discrete card's outputs should be available now in xrandr.<br />
<br />
== Troubleshooting ==<br />
<br />
{{Accuracy|No sources to motivate the workarounds in this section}}<br />
<br />
=== XRandR specifies only 1 output provider ===<br />
<br />
Delete/move /etc/X11/xorg.conf file and any other files relating to GPUs in /etc/X11/xorg.conf.d/. Restart the X server after this change.<br />
<br />
If the video driver is blacklisted in {{ic|/etc/modprobe.d/}}, load the module and restart X. This may be the case if you use the bbswitch module for Nvidia GPUs.<br />
<br />
Since kernel version 3.19.0 the nouveau kernel module cannot be loaded under certain circumstances. Dmesg will throw an error with {{ic|invalid rom content}}. The bug as has been patched, but hasnt yet reached mainline. [https://bugs.freedesktop.org/show_bug.cgi?id=89047 Freedesktop Bug Thread] In the meantime, applying the patches to a custom kernel before compiling seems to be the only fix.<br />
<br />
=== When an application is rendered with the discrete card, it only renders a black screen ===<br />
<br />
In some cases PRIME needs a composition manager to properly work. If your window manager doesn’t do compositing, you can use [[xcompmgr]] on top of it.<br />
<br />
If you use Xfce, you can go to Menu->Settings->Window Manager Tweaks->Compositor and enable compositing, then try again your application. <br />
<br />
==== Black screen with GL-based compositors ====<br />
Currently there are issues with GL-based compositors and PRIME offloading. While Xrender-based compositors (xcompmgr, xfwm, compton's default backend, cairo-compmgr, and a few others) will work without issue, GL-based compositors (Mutter/muffin, Compiz, compton with GLX backend, Kwin's OpenGL backend, etc) will initially show a black screen, as if there was no compositor running. While you can force an image to appear by resizing the offloaded window, this is not a practical solution as it will not work for things such as full screen Wine applications. This means that desktop environments such as GNOME3 and Cinnamon have issues with using PRIME offloading.<br />
<br />
Additionally if you are using an Intel IGP you might be able to fix the GL Compositing issue by running the IGP as UXA instead of SNA, however this may cause issues with the offloading process (ie, xrandr --listproviders may not list the discrete GPU).<br />
<br />
For details see [https://bugs.freedesktop.org/show_bug.cgi?id=69101 FDO Bug #69101.]<br />
<br />
One other way to approach this issue is by enabling DRI3 in the Intel driver. See the below issue for a sample config.<br />
<br />
=== Kernel crash/oops when using PRIME and switching windows/workspaces ===<br />
Note: this has been tested on a system with Intel+AMD<br />
<br />
Using DRI3 WITH a config file for the integrated card seems to fix this issue. <br />
<br />
To enable DRI3, you need to create a config for the integrated card adding the DRI3 option:<br />
<br />
Section "Device"<br />
Identifier "Intel Graphics"<br />
Driver "intel"<br />
Option "DRI" "3"<br />
EndSection<br />
<br />
After this you can use DRI_PRIME=1 WITHOUT having to run {{ic|xrandr --setprovideroffloadsink radeon Intel}} as DRI3 will take care of the offloading.<br />
<br />
=== Glitches/Ghosting synchronization problem on second monitor when using reverse PRIME ===<br />
<br />
This problem can affect users when not using a [[composite manager]], such as with [[i3]]. [https://bugs.freedesktop.org/show_bug.cgi?id=75579]<br />
<br />
If you experience this problem under Gnome, then a possible fix is to set some environment variables in {{ic|/etc/environment}} [https://bbs.archlinux.org/viewtopic.php?id=177925]<br />
<br />
CLUTTER_PAINT=disable-clipped-redraws:disable-culling<br />
CLUTTER_VBLANK=True<br />
<br />
== See also ==<br />
<br />
* [https://wiki.freedesktop.org/nouveau/Optimus/ Nouveau Optimus]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=Qt&diff=446165Qt2016-08-10T10:30:28Z<p>Alive4ever: /* Configuration of Qt5 apps under environments other than KDE */ Avoid using -o in shell script as it is not "well defined" github.com/koalaman/shellcheck/wiki/SC2166</p>
<hr />
<div>[[Category:Widget toolkits]]<br />
[[ja:Qt]]<br />
[[ru:Qt]]<br />
[[zh-CN:Qt]]<br />
{{Related articles start}}<br />
{{Related|KDE}}<br />
{{Related|Uniform Look for Qt and GTK Applications}}<br />
{{Related|GTK+}}<br />
{{Related articles end}}<br />
[http://qt-project.org/ Qt] is a cross-platform application and widget toolkit that uses standard C++ but makes extensive use of a special code generator (called the [http://qt-project.org/doc/qt-4.8/moc.html Meta Object Compiler], or ''moc'') together with several macros to enrich the language. Some of its more important features include:<br />
* Running on the major desktop platforms and some of the mobile platforms.<br />
* Extensive internationalization support.<br />
* A complete library that provides SQL database access, XML parsing, thread management, network support, and a unified cross-platform application programming interface (API) for file handling.<br />
<br />
The Qt framework is emerging as a major development platform and is the basis of the [[KDE]] software community, among other important open source and proprietary applications such as [[VLC]], [[VirtualBox]], [[Mathematica]], [[Skype]] and many others.<br />
<br />
== Installation ==<br />
Two versions of Qt are currently available in the [[official repositories]]. They can be [[Pacman|installed]] with the following packages:<br />
* '''Qt 5.x''' is available in the {{Pkg|qt5-base}} package, with documentation in the {{Pkg|qt5-doc}} package.<br />
* '''Qt 4.x''' is available in the {{Pkg|qt4}} package, with documentation on AUR in the {{AUR|qt4-doc}} package.<br />
* '''Qt 3.x''' is available from the AUR in the {{AUR|qt3}} package, with documentation on AUR in the {{AUR|qt3-doc}} package.<br />
<br />
{{ Warning|Qt packages do not provide the usual bins (e.g. ''qmake'') in {{ic|/usr/bin}} anymore. Instead {{ic|-qt5}}, {{ic|-qt4}} and {{ic|-qt3}} symlinks are provided (e.g. {{ic|qmake-qt5}}, {{ic|qmake-qt4}}, {{ic|qmake-qt3}}). This may cause compilation failures in Qt3/4 applications.<br />
To install usual bins, see [[#Default Qt toolkit]] section. }}<br />
<br />
== Default Qt toolkit ==<br />
By installing {{Pkg|qtchooser}} you can restore the usual bins (e.g. ''qmake'') in {{ic|/usr/bin}} and setup the Qt toolkit to use. By default Qt5 is used.<br />
<br />
=== Using environment variables ===<br />
To define default Qt toolkit, you can create {{ic|QT_SELECT}} [[environment variable]]. For example, to set Qt4, do {{ic|1=export QT_SELECT=4}} in your shell's init file (e.g. {{ic|~/.bash_profile.}} or {{ic|~/.zsh_profile.}}).<br />
<br />
=== Using configuration files ===<br />
You can set default Qt toolkit by creating a symlink {{ic|~/.config/qtchooser/default.conf}} to one of ''.conf'' files in {{ic|/etc/xdg/qtchooser/}} directory. For example, to set Qt4 symlink {{ic|/etc/xdg/qtchooser/4.conf}} to {{ic|~/.config/qtchooser/default.conf}}:<br />
<br />
$ ln -s {{ic|/etc/xdg/qtchooser/4.conf}} {{ic|~/.config/qtchooser/default.conf}}<br />
<br />
== Appearance ==<br />
=== Qt4 ===<br />
Qt4 application will try to mimic the behavior of the desktop environment they are running on, unless they run into some problems or hard-coded settings.<br />
* In KDE Plasma, it uses the actually selected Qt style. It can be configured using ''KDE System Settings'' (''systemsettings5''), the settings can be found in ''Appearance > Application Style > Widget Style''.<br />
* In Cinnamon, GNOME, Xfce, it uses GTK+ ([[Uniform look for Qt and GTK applications#QGtkStyle|QGtkStyle]]).<br />
* In other desktop environments, it uses Windows.<br />
<br />
For those who want to change the look and feel of Qt4 applications, the ''Qt Configuration'' (''qtconfig-qt4'') GUI tool is provided by the {{Pkg|qt4}} package. It offers a simple interface to configure the appearance of Qt4 applications including style, colors, fonts and some further options.<br />
<br />
{{Note|If you use ''GTK+'' style, then color and font settings will be ignored, and inherited from GTK+ 2.}}<br />
<br />
Qt keeps all its configuration information in {{ic|/etc/xdg/Trolltech.conf}} (system-wide) or {{ic|~/.config/Trolltech.conf}} (user-specific). The file is rather difficult to navigate because it contains a lot of information not related to appearance, but for any changes you can just add to the end of the file and overwrite any previous values (make sure to add your modification under the [Qt] header).<br />
<br />
For example, to change the theme to QtCurve, add:<br />
{{hc|~/.config/Trolltech.conf|<nowiki><br />
...<br />
[Qt]<br />
style=QtCurve<br />
</nowiki>}}<br />
<br />
The following styles are included in Qt4: ''CDE'', ''Cleanlooks'', ''GTK+'', ''Motif'', ''Plastique'', ''Windows''. Others can be installed from the official repositories or the [[AUR]] (most are written for KDE Plasma Desktop):<br />
* {{App|Breeze|Artwork, styles and assets for the Breeze visual style for the Plasma Desktop.|https://projects.kde.org/projects/kde/workspace/breeze|{{Pkg|breeze-kde4}}}}<br />
* {{App|[[Wikipedia:Oxygen Project|Oxygen]]|KDE Oxygen style.|https://projects.kde.org/projects/kde/workspace/oxygen|{{Pkg|oxygen-kde4}}}}<br />
* {{App|QtCurve|A configurable set of widget styles for KDE and Gtk.|https://projects.kde.org/projects/playground/base/qtcurve|{{Pkg|qtcurve-qt4}}}}<br />
* {{App|Adwaita-Qt| A style to bend Qt applications to look like they belong into GNOME Shell.|https://github.com/MartinBriza/adwaita-qt|{{AUR|adwaita-qt4}}}}<br />
<br />
=== Qt5 ===<br />
Qt5 decides the style to use based on what desktop environment is used:<br />
* In KDE Plasma, it uses the actually selected Qt style. It can be configured using ''KDE System Settings'' (''systemsettings5''), the settings can be found in ''Appearance > Application Style > Widget Style''.<br />
* In Cinnamon, GNOME, MATE, LXDE, Xfce, it uses GTK+ ([[Uniform look for Qt and GTK applications#QGtkStyle|QGtkStyle]]).<br />
* In other desktop environments, it uses Fusion.<br />
<br />
To force a specific style, you can set the {{ic|1=QT_STYLE_OVERRIDE}} [[environment variable]]. Specifically, set it to {{ic|gtk2}} if you want to use the [[GTK+]] theme (Note: you will need to install the Qt style plugins mention below to get the GTK+ style). Qt5 applications also support the {{ic|-style}} flag, which you can use to launch a Qt5 application with a specific style.<br />
<br />
The following styles are included in Qt5: ''Fusion'', ''Windows''. Others can be installed from the official repositories:<br />
* {{App|Breeze|Artwork, styles and assets for the Breeze visual style for the Plasma Desktop.|https://projects.kde.org/projects/kde/workspace/breeze|{{Pkg|breeze}}}}<br />
* {{App|Oxygen|KDE Oxygen style.|https://projects.kde.org/projects/kde/workspace/oxygen|{{Pkg|oxygen}}}}<br />
* {{App|QtCurve|A configurable set of widget styles for KDE and Gtk.|https://projects.kde.org/projects/playground/base/qtcurve|{{Pkg|qtcurve-qt5}}}}<br />
* {{App|Adwaita-Qt|A style to bend Qt applications to look like they belong into GNOME Shell.|https://github.com/MartinBriza/adwaita-qt|{{AUR|adwaita-qt5}}}}<br />
* {{App|Qt style plugins|Additional style plugins for Qt5, including ''GTK+'', ''Cleanlooks'', ''Motif'', ''Plastique''.|http://code.qt.io/cgit/qt/qtstyleplugins.git|{{AUR|qt5-styleplugins}}}}<br />
<br />
=== Qt Style Sheets ===<br />
An interesting way of customizing the look and feel of a Qt application is using Style Sheets, which are just simple CSS files. Using Style Sheets, one can modify the appearance of every widget in the application.<br />
<br />
To run an application with a different style just execute:<br />
$ qt_application -stylesheet ''style.qss''<br />
<br />
For more information on Qt Style Sheets see the [http://doc.qt.io/qt-5/stylesheet-reference.html official documentation] or other [http://thesmithfam.org/blog/2009/09/10/qt-stylesheets-tutorial/ tutorials]. As an example Style Sheet see this [http://kde-apps.org/content/show.php/roxydoxy?content&#61;125979 Dolphin modification].<br />
<br />
=== GTK+ and Qt ===<br />
If you have GTK+ and Qt applications, their looks might not exactly blend in very well. If you wish to make your GTK+ styles match your Qt styles please read [[Uniform look for Qt and GTK applications]].<br />
<br />
=== Configuration of Qt5 apps under environments other than KDE ===<br />
<br />
Unlike Qt4, Qt5 doesn't ship a qtconfig utility to configure fonts, icons or styles. Instead, it will try to use the settings from the running DE. In KDE or GNOME this works well, but in other less popular DEs or WM it can lead to missing icons in Qt5 applications. One way to solve this is to fake the running desktop environment by setting <br />
{{ic|1=XDG_CURRENT_DESKTOP=KDE}} or {{ic|GNOME}}, and then using the corresponding configuration application to set the desired icon set.<br />
<br />
Another solution is provided by the {{pkg|qt5ct}} package, which provides a DE independent Qt5 QPA and a configuration utility. After installing the package, run {{ic|qt5ct}} to set an icon theme, and set the environment variable {{ic|1=QT_QPA_PLATFORMTHEME="qt5ct"}} so that the settings are picked up by Qt applications. Alternatively, use {{ic|--platformtheme qt5ct}} as argument to the Qt5 application.<br />
<br />
To automatically set {{ic|QT_QPA_PLATFORMTHEME}} for user session, add the following line to {{ic|~/.profile}}.<br />
<br />
[ "$XDG_CURRENT_DESKTOP" = "KDE" ] || [ "$XDG_CURRENT_DESKTOP" = "GNOME" ] || export QT_QPA_PLATFORMTHEME="qt5ct"<br />
<br />
This will export {{ic|QT_QPA_PLATFORMTHEME}} environment variable for the whole user session. Note that this doesn't work on [[enlightenment]] because it has its own custom environment variable setting instead of getting it from {{ic|~/.profile}} file.<br />
<br />
If the below errors are received, and some icons still do not appear in some of the apps, install {{pkg|oxygen}} and {{pkg|oxygen-icons}}:<br />
<br />
Icon theme "oxygen" not found.<br />
Icon theme "oxygen" not found.<br />
Error: standard icon theme "oxygen" not found!<br />
<br />
== Development ==<br />
<br />
=== Supported platforms ===<br />
<br />
Qt supports most platforms that are available today, even some of the more obscure ones, with more ports appearing every once in a while. For a more complete list see the [[Wikipedia:Qt_(framework)#Platforms|Qt Wikipedia article]].<br />
<br />
==== Android ====<br />
<br />
{{Expansion|Create a PKGBUILD and submit to the AUR as e.g. ''qt-android''.}}<br />
<br />
Use the [http://download.qt.io/official_releases/qt/5.5/5.5.1/qt-opensource-linux-x64-android-5.5.1.run Qt for Android installer].<br />
<br />
=== Tools ===<br />
<br />
The following are official Qt tools:<br />
<br />
* {{App|[[Wikipedia:Qt Creator|Qt Creator]]|A cross-platform IDE tailored for Qt that supports all of its features.|http://doc.qt.io/qtcreator/|{{Pkg|qtcreator}}}}<br />
* {{App|Qt Linguist|A set of tools that speed the translation and internationalization of Qt applications.|http://doc.qt.io/qt-5/qtlinguist-index.html|Qt 5: {{Pkg|qt5-tools}}, Qt 4: {{Pkg|qt4}}}}<br />
* {{App|Qt Assistant|A configurable and redistributable documentation reader for Qt ''qch'' files.|http://doc.qt.io/qt-5/qtassistant-index.html|Qt 5: {{Pkg|qt5-tools}}, Qt 4: {{Pkg|qt4}}}}<br />
* {{App|Qt Designer|A powerful cross-platform GUI layout and forms builder for Qt widgets.|http://doc.qt.io/qt-5/qtdesigner-manual.html|Qt 5: {{Pkg|qt5-tools}}, Qt 4: {{Pkg|qt4}}}}<br />
* {{App|Qt Quick Designer|A visual editor for QML files which supports WYSIWYG. It allows you to rapidly design and build Qt Quick applications and components from scratch.|http://doc.qt.io/qtcreator/creator-using-qt-quick-designer.html|{{Pkg|qtcreator}}}}<br />
* {{App|qmlscene|A tool for loading QML documents that makes it easy to quickly develop and debug QML applications.|http://doc.qt.io/qt-5/qtquick-qmlscene.html|Qt 5: {{Pkg|qt5-declarative}}, Qt 4 QML Viewer: {{Pkg|qt4}}}}<br />
* {{App|[[Wikipedia:Qmake|qmake]]|A tool that helps simplify the build process for development project across different platforms, similar to [[Wikipedia:CMake|cmake]], but with fewer options and tailored for Qt applications.|http://doc.qt.io/qt-5/qmake-manual.html|Qt 5: {{Pkg|qt5-base}}, Qt 4: {{Pkg|qt4}}}}<br />
* {{App|uic|A tool that reads ''*.ui'' XML files and generates the corresponding C++ files.|http://doc.qt.io/qt-5/uic.html|Qt 5: {{Pkg|qt5-base}}, Qt 4: {{Pkg|qt4}}}}<br />
* {{App|rcc|A tool that is used to embed resources (such as pictures) into a Qt application during the build process. It works by generating a C++ source file containing data specified in a Qt resource (.qrc) file.|http://doc.qt.io/qt-5/rcc.html|Qt 5: {{Pkg|qt5-base}}, Qt 4: {{Pkg|qt4}}}}<br />
* {{App|moc|A tool that handles Qt's C++ extensions (the signals and slots mechanism, the run-time type information, and the dynamic property system, etc.).|http://doc.qt.io/qt-5/moc.html|Qt 5: {{Pkg|qt5-base}}, Qt 4: {{Pkg|qt4}}}}<br />
<br />
=== Bindings ===<br />
Qt has bindings for all of the more popular languages, for a full list see [[Wikipedia:Qt (framework)#Programming language bindings|this list]].<br />
<br />
The following examples display a small 'Hello world!' message in a window.<br />
<br />
==== C++ ====<br />
* Package: <br />
** {{Pkg|qt4}} - Version 4.x of the Qt toolkit.<br />
** {{Pkg|qt5-base}} - Version 5.x of the Qt toolkit.<br />
* Website: http://qt-project.org/<br />
* Build: <br />
** The Qt4 version: {{ic|g++ $(pkg-config --cflags --libs QtGui) -o hello hello.cpp}}<br />
** The Qt5 version: {{ic|g++ $(pkg-config --cflags --libs Qt5Widgets) -fPIC -o hello hello.cpp}}<br />
* Run with: {{ic|./hello}}<br />
{{hc|hello.cpp|<br />
#include <QApplication><br />
#include <QLabel><br />
<br />
int main(int argc, char **argv)<br />
{<br />
QApplication app(argc, argv);<br />
QLabel hello("Hello world!");<br />
<br />
hello.show();<br />
return app.exec();<br />
}<br />
}}<br />
<br />
==== QML ====<br />
* Package: {{Pkg|qt4}} or {{Pkg|qt5-declarative}}.<br />
* Website: http://qt-project.org/<br />
* Run with: {{ic|qmlviewer-qt4 hello.qml}} or {{ic|qmlscene-qt5 hello.qml}}<br />
{{hc|hello.qml|<br />
import QtQuick 1.0<br />
<br />
Rectangle {<br />
id: page<br />
width: 400; height: 100<br />
color: "lightgray"<br />
<br />
Text {<br />
id: helloText<br />
text: "Hello world!"<br />
anchors.horizontalCenter: page.horizontalCenter<br />
anchors.verticalCenter: page.verticalCenter<br />
font.pointSize: 24; font.bold: true<br />
}<br />
}<br />
}}<br />
{{Note|For version 5.x of the Qt toolkit, we need to import QtQuick 2.y.}}<br />
<br />
==== Python (PyQt) ====<br />
* Package:<br />
** {{Pkg|python-pyqt4}} - Python 3.x bindings for Qt 4<br />
** {{Pkg|python2-pyqt4}} - Python 2.x bindings for Qt 4<br />
** {{Pkg|python-pyqt5}} - Python 3.x bindings for Qt 5<br />
** {{Pkg|python2-pyqt5}} - Python 2.x bindings for Qt 5<br />
<br />
* Website: http://www.riverbankcomputing.co.uk/software/pyqt/intro<br />
* Run with: {{ic|python hello-pyqt.py}} or {{ic|python2 hello-pyqt.py}}.<br />
{{hc|hello-pyqt.py|<nowiki><br />
import sys<br />
from PyQt4 import QtGui<br />
<br />
app = QtGui.QApplication(sys.argv)<br />
label = QtGui.QLabel("Hello world!")<br />
<br />
label.show()<br />
sys.exit(app.exec_())</nowiki><br />
}}<br />
<br />
The Qt 5.x version is slighly different:<br />
{{hc|hello-pyqt.py|<nowiki><br />
import sys<br />
from PyQt5 import QtWidgets<br />
<br />
app = QtWidgets.QApplication(sys.argv)<br />
label = QtWidgets.QLabel("Hello world!")<br />
<br />
label.show()<br />
sys.exit(app.exec_())</nowiki><br />
}}<br />
<br />
==== Python (PySide) ====<br />
* Package:<br />
** {{Pkg|python-pyside}} - Python 3.x bindings<br />
** {{Pkg|python2-pyside}} - Python 2.x bindings<br />
* Website: http://www.pyside.org/<br />
* Run with: {{ic|python hello-pyside.py}} or {{ic|python2 hello-pyside.py}}<br />
{{hc|hello-pyside.py|<nowiki><br />
import sys<br />
from PySide.QtCore import *<br />
from PySide.QtGui import *<br />
<br />
app = QApplication(sys.argv)<br />
label = QLabel("Hello world!")<br />
<br />
label.show()<br />
sys.exit(app.exec_())</nowiki><br />
}}<br />
<br />
==== C# ====<br />
* Package: {{AUR|kdebindings-qyoto}}{{Broken package link|{{aur-mirror|kdebindings-qyoto}}}}<br />
* Website: http://techbase.kde.org/Development/Languages/Qyoto<br />
* Build with: {{ic|mcs -pkg:qyoto hello.cs}}<br />
* Run with: {{ic|mono hello.exe}}<br />
{{hc|hello.cs|<br />
using System;<br />
using Qyoto;<br />
<br />
public class Hello {<br />
public static int Main(String[] args) {<br />
new QApplication(args);<br />
new QLabel("Hello world!").Show();<br />
<br />
return QApplication.Exec();<br />
}<br />
}<br />
}}<br />
<br />
==== Ruby ====<br />
* Package: {{AUR|kdebindings-qtruby}}{{Broken package link|{{aur-mirror|kdebindings-qtruby}}}}<br />
* Website: http://rubyforge.org/projects/korundum/<br />
* Run with: {{ic|ruby hello.rb}}<br />
{{hc|hello.rb|<nowiki><br />
require 'Qt4'<br />
<br />
app = Qt::Application.new(ARGV)<br />
hello = Qt::Label.new('Hello World!')<br />
<br />
hello.show<br />
app.exec</nowiki><br />
}}<br />
==== Java ====<br />
* Package: {{AUR|qtjambi}}{{Broken package link|{{aur-mirror|qtjambi}}}} or {{AUR|qtjambi-beta}}{{Broken package link|{{aur-mirror|qtjambi-beta}}}}.<br />
* Website: http://qt-jambi.org/<br />
* Build with: {{ic|javac Hello.java -cp /opt/qtjambi-beta/qtjambi-linux64-community-4.7.0/qtjambi-4.7.0.jar}}.<br />
* Run with: {{ic|java -cp /opt/qtjambi-beta/qtjambi-linux64-community-4.7.0/qtjambi-4.7.0.jar:. Hello}}.<br />
{{hc|Hello.java|<nowiki><br />
import com.trolltech.qt.gui.*;<br />
<br />
public class Hello<br />
{<br />
public static void main(String args[])<br />
{<br />
QApplication.initialize(args);<br />
QLabel hello = new QLabel("Hello World!");<br />
<br />
hello.show();<br />
QApplication.exec();<br />
}<br />
}</nowiki><br />
}}<br />
{{Note|The build instructions and example have been tested on the beta version of Qt Jambi 4.7.0.}}<br />
<br />
==== Perl ====<br />
* Package: {{AUR|kdebindings-perlqt}}{{Broken package link|{{aur-mirror|kdebindings-perlqt}}}}<br />
* Website: http://code.google.com/p/perlqt4/<br />
* Run with: {{ic|perl hello.pl}}<br />
{{hc|hello.pl|<nowiki><br />
use QtGui4;<br />
<br />
my $a = Qt::Application(\@ARGV);<br />
my $hello = Qt::Label("Hello World!", undef);<br />
<br />
$hello->show;<br />
exit $a->exec;<br />
</nowiki><br />
}}<br />
==== Lua ====<br />
* Package: {{AUR|libqtlua}}{{Broken package link|{{aur-mirror|libqtlua}}}}<br />
* Website: http://www.nongnu.org/libqtlua/<br />
* Run with: {{ic|qtlua hello.lua}}<br />
{{hc|hello.lua|<nowiki><br />
label = qt.new_widget("QLabel")<br />
<br />
label:setText("Hello World!")<br />
label:show()</nowiki><br />
}}<br />
<br />
{{Note|QtLua is not designed to develop an application in pure Lua but rather to extend a Qt C++ application using Lua as scripting language.}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Icon theme is not applied ===<br />
<br />
Since Qt 5.1 SVG support has moved into a module. Since {{Pkg|qt5-base}} does not depend on {{Pkg|qt5-svg}} it may happen that the {{Pkg|qt5-base}} is installed but not {{Pkg|qt5-svg}}. This results in deceptive icon theme behaviour. Since SVG is not supported the icons are silently skipped and the icon theme may seem to be unused. Installing {{Pkg|qt5-svg}} explicitly solves the problem.<br />
<br />
=== Theme not applied to root applications ===<br />
<br />
As the user theme file ({{ic|$XDG_CONFIG_HOME/Trolltech.conf}}), are not read by other accounts, the selected theme will not apply to [[Running_X_apps_as_root|X applications run as root]]. Possible solutions include:<br />
<br />
* Create symlinks, e.g<br />
# ln -s /home/[username]/.config/Trolltech.conf /etc/xdg/Trolltech.conf<br />
* Configure system-wide theme file: {{ic|/etc/xdg/Trolltech.conf}}<br />
* Adjust the theme as root<br />
<br />
=== Qt4 style not respected ===<br />
<br />
If pure Qt4 (non-KDE) applications do not stick with your selected Qt4 style, then you'll probably need to tell Qt4 how to find KDE's styles (Oxygen, Phase etc.). You just need to set the environment variable QT_PLUGIN_PATH. E.g. put<br />
<br />
export QT_PLUGIN_PATH=$HOME/.kde4/lib/kde4/plugins/:/usr/lib/kde4/plugins/<br />
<br />
into your {{ic|/etc/profile}} (or {{ic|~/.profile}} if you do not have root access). {{ic|qtconfig-qt4}} should then be able to find your kde styles and everything should look nice again!<br />
<br />
Alternatively, you can symlink the Qt4 styles directory to the KDE4 styles one:<br />
# ln -s /usr/lib/{kde,qt}4/plugins/styles/[theme name]<br />
<br />
=== Qt5 platform plugins and missing dependencies ===<br />
<br />
{{Accuracy|1=Is this issue still valid? (e.g. see {{Bug|40468}}) {{Pkg|qt5-base}} depends on {{Pkg|libxkbcommon-x11}} since [https://git.archlinux.org/svntogit/packages.git/commit/trunk?h=packages/qt5-base&id=d76d85392dfa67ba22c2c00d7c08ca4c2b923dd2]. Also, rather than packaging bug, it may also indicate upstream bug ({{Bug|45612}}).}}<br />
<br />
Using {{Pkg|qt5-base}} will install Qt5, which makes use of [http://doc.qt.io/qt-5/qpa.html platform abstractions], but some platform abstraction plugin dependencies may be missing. Qt may tell you that the plugin is unavailable, rather than resolve the chain of missing dependencies for other packages.<br />
<br />
For instance, if your application relies on [http://xcb.freedesktop.org xcb], and dependencies of the xcb library are missing, Qt will report:<br />
<br />
This application failed to start because it could not find or load the Qt platform plugin "xcb". Available plugins are: xcb.<br />
<br />
Reinstalling the application may fix this problem.<br />
<br />
This implies the application package misses some of its required dependencies not provided by {{Pkg|qt5-base}}. You can use ''ldd'' to identify which are missing (e.g. {{ic|ldd /usr/bin/''application'' &#124;grep -e xcb}}) and file a bug against the application package. The Qt5 page proposes a [http://doc.qt.io/qt-5/linux-requirements.html list of packages] that are recommended for installation; it can help to identify the one missing.<br />
<br />
== See also ==<br />
* [http://qt.io/ Official Website]<br />
* [http://doc.qt.io/ Qt Documentation]<br />
* [http://planet.qt.io/ Planet Qt]<br />
* [http://qt-apps.org/ Qt Applications]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=Qt&diff=445697Qt2016-08-07T14:05:00Z<p>Alive4ever: /* Configuration of Qt5 apps under environments other than KDE */ missing brackets</p>
<hr />
<div>[[Category:Widget toolkits]]<br />
[[ja:Qt]]<br />
[[ru:Qt]]<br />
[[zh-CN:Qt]]<br />
{{Related articles start}}<br />
{{Related|KDE}}<br />
{{Related|Uniform Look for Qt and GTK Applications}}<br />
{{Related|GTK+}}<br />
{{Related articles end}}<br />
[http://qt-project.org/ Qt] is a cross-platform application and widget toolkit that uses standard C++ but makes extensive use of a special code generator (called the [http://qt-project.org/doc/qt-4.8/moc.html Meta Object Compiler], or ''moc'') together with several macros to enrich the language. Some of its more important features include:<br />
* Running on the major desktop platforms and some of the mobile platforms.<br />
* Extensive internationalization support.<br />
* A complete library that provides SQL database access, XML parsing, thread management, network support, and a unified cross-platform application programming interface (API) for file handling.<br />
<br />
The Qt framework is emerging as a major development platform and is the basis of the [[KDE]] software community, among other important open source and proprietary applications such as [[VLC]], [[VirtualBox]], [[Mathematica]], [[Skype]] and many others.<br />
<br />
== Installation ==<br />
Two versions of Qt are currently available in the [[official repositories]]. They can be [[Pacman|installed]] with the following packages:<br />
* '''Qt 5.x''' is available in the {{Pkg|qt5-base}} package, with documentation in the {{Pkg|qt5-doc}} package.<br />
* '''Qt 4.x''' is available in the {{Pkg|qt4}} package, with documentation on AUR in the {{AUR|qt4-doc}} package.<br />
* '''Qt 3.x''' is available from the AUR in the {{AUR|qt3}} package, with documentation on AUR in the {{AUR|qt3-doc}} package.<br />
<br />
{{ Warning|Qt packages do not provide the usual bins (e.g. ''qmake'') in {{ic|/usr/bin}} anymore. Instead {{ic|-qt5}}, {{ic|-qt4}} and {{ic|-qt3}} symlinks are provided (e.g. {{ic|qmake-qt5}}, {{ic|qmake-qt4}}, {{ic|qmake-qt3}}). This may cause compilation failures in Qt3/4 applications.<br />
To install usual bins, see [[#Default Qt toolkit]] section. }}<br />
<br />
== Default Qt toolkit ==<br />
By installing {{Pkg|qtchooser}} you can restore the usual bins (e.g. ''qmake'') in {{ic|/usr/bin}} and setup the Qt toolkit to use. By default Qt5 is used.<br />
<br />
=== Using environment variables ===<br />
To define default Qt toolkit, you can create {{ic|QT_SELECT}} [[environment variable]]. For example, to set Qt4, do {{ic|1=export QT_SELECT=4}} in your shell's init file (e.g. {{ic|~/.bash_profile.}} or {{ic|~/.zsh_profile.}}).<br />
<br />
=== Using configuration files ===<br />
You can set default Qt toolkit by creating a symlink {{ic|~/.config/qtchooser/default.conf}} to one of ''.conf'' files in {{ic|/etc/xdg/qtchooser/}} directory. For example, to set Qt4 symlink {{ic|/etc/xdg/qtchooser/4.conf}} to {{ic|~/.config/qtchooser/default.conf}}:<br />
<br />
$ ln -s {{ic|/etc/xdg/qtchooser/4.conf}} {{ic|~/.config/qtchooser/default.conf}}<br />
<br />
== Appearance ==<br />
=== Qt4 ===<br />
Qt4 application will try to mimic the behavior of the desktop environment they are running on, unless they run into some problems or hard-coded settings.<br />
* In KDE Plasma, it uses the actually selected Qt style. It can be configured using ''KDE System Settings'' (''systemsettings5''), the settings can be found in ''Appearance > Application Style > Widget Style''.<br />
* In Cinnamon, GNOME, Xfce, it uses GTK+ ([[Uniform look for Qt and GTK applications#QGtkStyle|QGtkStyle]]).<br />
* In other desktop environments, it uses Windows.<br />
<br />
For those who want to change the look and feel of Qt4 applications, the ''Qt Configuration'' (''qtconfig-qt4'') GUI tool is provided by the {{Pkg|qt4}} package. It offers a simple interface to configure the appearance of Qt4 applications including style, colors, fonts and some further options.<br />
<br />
{{Note|If you use ''GTK+'' style, then color and font settings will be ignored, and inherited from GTK+ 2.}}<br />
<br />
Qt keeps all its configuration information in {{ic|/etc/xdg/Trolltech.conf}} (system-wide) or {{ic|~/.config/Trolltech.conf}} (user-specific). The file is rather difficult to navigate because it contains a lot of information not related to appearance, but for any changes you can just add to the end of the file and overwrite any previous values (make sure to add your modification under the [Qt] header).<br />
<br />
For example, to change the theme to QtCurve, add:<br />
{{hc|~/.config/Trolltech.conf|<nowiki><br />
...<br />
[Qt]<br />
style=QtCurve<br />
</nowiki>}}<br />
<br />
The following styles are included in Qt4: ''CDE'', ''Cleanlooks'', ''GTK+'', ''Motif'', ''Plastique'', ''Windows''. Others can be installed from the official repositories or the [[AUR]] (most are written for KDE Plasma Desktop):<br />
* {{App|Breeze|Artwork, styles and assets for the Breeze visual style for the Plasma Desktop.|https://projects.kde.org/projects/kde/workspace/breeze|{{Pkg|breeze-kde4}}}}<br />
* {{App|[[Wikipedia:Oxygen Project|Oxygen]]|KDE Oxygen style.|https://projects.kde.org/projects/kde/workspace/oxygen|{{Pkg|oxygen-kde4}}}}<br />
* {{App|QtCurve|A configurable set of widget styles for KDE and Gtk.|https://projects.kde.org/projects/playground/base/qtcurve|{{Pkg|qtcurve-qt4}}}}<br />
* {{App|Adwaita-Qt| A style to bend Qt applications to look like they belong into GNOME Shell.|https://github.com/MartinBriza/adwaita-qt|{{AUR|adwaita-qt4}}}}<br />
<br />
=== Qt5 ===<br />
Qt5 decides the style to use based on what desktop environment is used:<br />
* In KDE Plasma, it uses the actually selected Qt style. It can be configured using ''KDE System Settings'' (''systemsettings5''), the settings can be found in ''Appearance > Application Style > Widget Style''.<br />
* In Cinnamon, GNOME, MATE, LXDE, Xfce, it uses GTK+ ([[Uniform look for Qt and GTK applications#QGtkStyle|QGtkStyle]]).<br />
* In other desktop environments, it uses Fusion.<br />
<br />
To force a specific style, you can set the {{ic|1=QT_STYLE_OVERRIDE}} [[environment variable]]. Specifically, set it to {{ic|gtk2}} if you want to use the [[GTK+]] theme (Note: you will need to install the Qt style plugins mention below to get the GTK+ style). Qt5 applications also support the {{ic|-style}} flag, which you can use to launch a Qt5 application with a specific style.<br />
<br />
The following styles are included in Qt5: ''Fusion'', ''Windows''. Others can be installed from the official repositories:<br />
* {{App|Breeze|Artwork, styles and assets for the Breeze visual style for the Plasma Desktop.|https://projects.kde.org/projects/kde/workspace/breeze|{{Pkg|breeze}}}}<br />
* {{App|Oxygen|KDE Oxygen style.|https://projects.kde.org/projects/kde/workspace/oxygen|{{Pkg|oxygen}}}}<br />
* {{App|QtCurve|A configurable set of widget styles for KDE and Gtk.|https://projects.kde.org/projects/playground/base/qtcurve|{{Pkg|qtcurve-qt5}}}}<br />
* {{App|Adwaita-Qt|A style to bend Qt applications to look like they belong into GNOME Shell.|https://github.com/MartinBriza/adwaita-qt|{{AUR|adwaita-qt5}}}}<br />
* {{App|Qt style plugins|Additional style plugins for Qt5, including ''GTK+'', ''Cleanlooks'', ''Motif'', ''Plastique''.|http://code.qt.io/cgit/qt/qtstyleplugins.git|{{AUR|qt5-styleplugins}}}}<br />
<br />
=== Qt Style Sheets ===<br />
An interesting way of customizing the look and feel of a Qt application is using Style Sheets, which are just simple CSS files. Using Style Sheets, one can modify the appearance of every widget in the application.<br />
<br />
To run an application with a different style just execute:<br />
$ qt_application -stylesheet ''style.qss''<br />
<br />
For more information on Qt Style Sheets see the [http://doc.qt.io/qt-5/stylesheet-reference.html official documentation] or other [http://thesmithfam.org/blog/2009/09/10/qt-stylesheets-tutorial/ tutorials]. As an example Style Sheet see this [http://kde-apps.org/content/show.php/roxydoxy?content&#61;125979 Dolphin modification].<br />
<br />
=== GTK+ and Qt ===<br />
If you have GTK+ and Qt applications, their looks might not exactly blend in very well. If you wish to make your GTK+ styles match your Qt styles please read [[Uniform look for Qt and GTK applications]].<br />
<br />
=== Configuration of Qt5 apps under environments other than KDE ===<br />
<br />
Unlike Qt4, Qt5 doesn't ship a qtconfig utility to configure fonts, icons or styles. Instead, it will try to use the settings from the running DE. In KDE or GNOME this works well, but in other less popular DEs or WM it can lead to missing icons in Qt5 applications. One way to solve this is to fake the running desktop environment by setting <br />
{{ic|1=XDG_CURRENT_DESKTOP=KDE}} or {{ic|GNOME}}, and then using the corresponding configuration application to set the desired icon set.<br />
<br />
Another solution is provided by the {{pkg|qt5ct}} package, which provides a DE independent Qt5 QPA and a configuration utility. After installing the package, run {{ic|qt5ct}} to set an icon theme, and set the environment variable {{ic|1=QT_QPA_PLATFORMTHEME="qt5ct"}} so that the settings are picked up by Qt applications. Alternatively, use {{ic|--platformtheme qt5ct}} as argument to the Qt5 application.<br />
<br />
To automatically set {{ic|QT_QPA_PLATFORMTHEME}} for user session, add the following line to {{ic|~/.profile}}.<br />
<br />
[ "$XDG_CURRENT_DESKTOP" = "KDE" -o "$XDG_CURRENT_DESKTOP" = "GNOME" ] || export QT_QPA_PLATFORMTHEME="qt5ct"<br />
<br />
This will export {{ic|QT_QPA_PLATFORMTHEME}} environment variable for the whole user session. Note that this doesn't work on [[enlightenment]] because it has its own custom environment variable setting instead of getting it from {{ic|~/.profile}} file.<br />
<br />
If the below errors are received, and some icons still do not appear in some of the apps, install {{pkg|oxygen}} and {{pkg|oxygen-icons}}:<br />
<br />
Icon theme "oxygen" not found.<br />
Icon theme "oxygen" not found.<br />
Error: standard icon theme "oxygen" not found!<br />
<br />
== Development ==<br />
<br />
=== Supported platforms ===<br />
<br />
Qt supports most platforms that are available today, even some of the more obscure ones, with more ports appearing every once in a while. For a more complete list see the [[Wikipedia:Qt_(framework)#Platforms|Qt Wikipedia article]].<br />
<br />
==== Android ====<br />
<br />
{{Expansion|Create a PKGBUILD and submit to the AUR as e.g. ''qt-android''.}}<br />
<br />
Use the [http://download.qt.io/official_releases/qt/5.5/5.5.1/qt-opensource-linux-x64-android-5.5.1.run Qt for Android installer].<br />
<br />
=== Tools ===<br />
<br />
The following are official Qt tools:<br />
<br />
* {{App|[[Wikipedia:Qt Creator|Qt Creator]]|A cross-platform IDE tailored for Qt that supports all of its features.|http://doc.qt.io/qtcreator/|{{Pkg|qtcreator}}}}<br />
* {{App|Qt Linguist|A set of tools that speed the translation and internationalization of Qt applications.|http://doc.qt.io/qt-5/qtlinguist-index.html|Qt 5: {{Pkg|qt5-tools}}, Qt 4: {{Pkg|qt4}}}}<br />
* {{App|Qt Assistant|A configurable and redistributable documentation reader for Qt ''qch'' files.|http://doc.qt.io/qt-5/qtassistant-index.html|Qt 5: {{Pkg|qt5-tools}}, Qt 4: {{Pkg|qt4}}}}<br />
* {{App|Qt Designer|A powerful cross-platform GUI layout and forms builder for Qt widgets.|http://doc.qt.io/qt-5/qtdesigner-manual.html|Qt 5: {{Pkg|qt5-tools}}, Qt 4: {{Pkg|qt4}}}}<br />
* {{App|Qt Quick Designer|A visual editor for QML files which supports WYSIWYG. It allows you to rapidly design and build Qt Quick applications and components from scratch.|http://doc.qt.io/qtcreator/creator-using-qt-quick-designer.html|{{Pkg|qtcreator}}}}<br />
* {{App|qmlscene|A tool for loading QML documents that makes it easy to quickly develop and debug QML applications.|http://doc.qt.io/qt-5/qtquick-qmlscene.html|Qt 5: {{Pkg|qt5-declarative}}, Qt 4 QML Viewer: {{Pkg|qt4}}}}<br />
* {{App|[[Wikipedia:Qmake|qmake]]|A tool that helps simplify the build process for development project across different platforms, similar to [[Wikipedia:CMake|cmake]], but with fewer options and tailored for Qt applications.|http://doc.qt.io/qt-5/qmake-manual.html|Qt 5: {{Pkg|qt5-base}}, Qt 4: {{Pkg|qt4}}}}<br />
* {{App|uic|A tool that reads ''*.ui'' XML files and generates the corresponding C++ files.|http://doc.qt.io/qt-5/uic.html|Qt 5: {{Pkg|qt5-base}}, Qt 4: {{Pkg|qt4}}}}<br />
* {{App|rcc|A tool that is used to embed resources (such as pictures) into a Qt application during the build process. It works by generating a C++ source file containing data specified in a Qt resource (.qrc) file.|http://doc.qt.io/qt-5/rcc.html|Qt 5: {{Pkg|qt5-base}}, Qt 4: {{Pkg|qt4}}}}<br />
* {{App|moc|A tool that handles Qt's C++ extensions (the signals and slots mechanism, the run-time type information, and the dynamic property system, etc.).|http://doc.qt.io/qt-5/moc.html|Qt 5: {{Pkg|qt5-base}}, Qt 4: {{Pkg|qt4}}}}<br />
<br />
=== Bindings ===<br />
Qt has bindings for all of the more popular languages, for a full list see [[Wikipedia:Qt (framework)#Programming language bindings|this list]].<br />
<br />
The following examples display a small 'Hello world!' message in a window.<br />
<br />
==== C++ ====<br />
* Package: <br />
** {{Pkg|qt4}} - Version 4.x of the Qt toolkit.<br />
** {{Pkg|qt5-base}} - Version 5.x of the Qt toolkit.<br />
* Website: http://qt-project.org/<br />
* Build: <br />
** The Qt4 version: {{ic|g++ $(pkg-config --cflags --libs QtGui) -o hello hello.cpp}}<br />
** The Qt5 version: {{ic|g++ $(pkg-config --cflags --libs Qt5Widgets) -fPIC -o hello hello.cpp}}<br />
* Run with: {{ic|./hello}}<br />
{{hc|hello.cpp|<br />
#include <QApplication><br />
#include <QLabel><br />
<br />
int main(int argc, char **argv)<br />
{<br />
QApplication app(argc, argv);<br />
QLabel hello("Hello world!");<br />
<br />
hello.show();<br />
return app.exec();<br />
}<br />
}}<br />
<br />
==== QML ====<br />
* Package: {{Pkg|qt4}} or {{Pkg|qt5-declarative}}.<br />
* Website: http://qt-project.org/<br />
* Run with: {{ic|qmlviewer-qt4 hello.qml}} or {{ic|qmlscene-qt5 hello.qml}}<br />
{{hc|hello.qml|<br />
import QtQuick 1.0<br />
<br />
Rectangle {<br />
id: page<br />
width: 400; height: 100<br />
color: "lightgray"<br />
<br />
Text {<br />
id: helloText<br />
text: "Hello world!"<br />
anchors.horizontalCenter: page.horizontalCenter<br />
anchors.verticalCenter: page.verticalCenter<br />
font.pointSize: 24; font.bold: true<br />
}<br />
}<br />
}}<br />
{{Note|For version 5.x of the Qt toolkit, we need to import QtQuick 2.y.}}<br />
<br />
==== Python (PyQt) ====<br />
* Package:<br />
** {{Pkg|python-pyqt4}} - Python 3.x bindings for Qt 4<br />
** {{Pkg|python2-pyqt4}} - Python 2.x bindings for Qt 4<br />
** {{Pkg|python-pyqt5}} - Python 3.x bindings for Qt 5<br />
** {{Pkg|python2-pyqt5}} - Python 2.x bindings for Qt 5<br />
<br />
* Website: http://www.riverbankcomputing.co.uk/software/pyqt/intro<br />
* Run with: {{ic|python hello-pyqt.py}} or {{ic|python2 hello-pyqt.py}}.<br />
{{hc|hello-pyqt.py|<nowiki><br />
import sys<br />
from PyQt4 import QtGui<br />
<br />
app = QtGui.QApplication(sys.argv)<br />
label = QtGui.QLabel("Hello world!")<br />
<br />
label.show()<br />
sys.exit(app.exec_())</nowiki><br />
}}<br />
<br />
The Qt 5.x version is slighly different:<br />
{{hc|hello-pyqt.py|<nowiki><br />
import sys<br />
from PyQt5 import QtWidgets<br />
<br />
app = QtWidgets.QApplication(sys.argv)<br />
label = QtWidgets.QLabel("Hello world!")<br />
<br />
label.show()<br />
sys.exit(app.exec_())</nowiki><br />
}}<br />
<br />
==== Python (PySide) ====<br />
* Package:<br />
** {{Pkg|python-pyside}} - Python 3.x bindings<br />
** {{Pkg|python2-pyside}} - Python 2.x bindings<br />
* Website: http://www.pyside.org/<br />
* Run with: {{ic|python hello-pyside.py}} or {{ic|python2 hello-pyside.py}}<br />
{{hc|hello-pyside.py|<nowiki><br />
import sys<br />
from PySide.QtCore import *<br />
from PySide.QtGui import *<br />
<br />
app = QApplication(sys.argv)<br />
label = QLabel("Hello world!")<br />
<br />
label.show()<br />
sys.exit(app.exec_())</nowiki><br />
}}<br />
<br />
==== C# ====<br />
* Package: {{AUR|kdebindings-qyoto}}{{Broken package link|{{aur-mirror|kdebindings-qyoto}}}}<br />
* Website: http://techbase.kde.org/Development/Languages/Qyoto<br />
* Build with: {{ic|mcs -pkg:qyoto hello.cs}}<br />
* Run with: {{ic|mono hello.exe}}<br />
{{hc|hello.cs|<br />
using System;<br />
using Qyoto;<br />
<br />
public class Hello {<br />
public static int Main(String[] args) {<br />
new QApplication(args);<br />
new QLabel("Hello world!").Show();<br />
<br />
return QApplication.Exec();<br />
}<br />
}<br />
}}<br />
<br />
==== Ruby ====<br />
* Package: {{AUR|kdebindings-qtruby}}{{Broken package link|{{aur-mirror|kdebindings-qtruby}}}}<br />
* Website: http://rubyforge.org/projects/korundum/<br />
* Run with: {{ic|ruby hello.rb}}<br />
{{hc|hello.rb|<nowiki><br />
require 'Qt4'<br />
<br />
app = Qt::Application.new(ARGV)<br />
hello = Qt::Label.new('Hello World!')<br />
<br />
hello.show<br />
app.exec</nowiki><br />
}}<br />
==== Java ====<br />
* Package: {{AUR|qtjambi}}{{Broken package link|{{aur-mirror|qtjambi}}}} or {{AUR|qtjambi-beta}}{{Broken package link|{{aur-mirror|qtjambi-beta}}}}.<br />
* Website: http://qt-jambi.org/<br />
* Build with: {{ic|javac Hello.java -cp /opt/qtjambi-beta/qtjambi-linux64-community-4.7.0/qtjambi-4.7.0.jar}}.<br />
* Run with: {{ic|java -cp /opt/qtjambi-beta/qtjambi-linux64-community-4.7.0/qtjambi-4.7.0.jar:. Hello}}.<br />
{{hc|Hello.java|<nowiki><br />
import com.trolltech.qt.gui.*;<br />
<br />
public class Hello<br />
{<br />
public static void main(String args[])<br />
{<br />
QApplication.initialize(args);<br />
QLabel hello = new QLabel("Hello World!");<br />
<br />
hello.show();<br />
QApplication.exec();<br />
}<br />
}</nowiki><br />
}}<br />
{{Note|The build instructions and example have been tested on the beta version of Qt Jambi 4.7.0.}}<br />
<br />
==== Perl ====<br />
* Package: {{AUR|kdebindings-perlqt}}{{Broken package link|{{aur-mirror|kdebindings-perlqt}}}}<br />
* Website: http://code.google.com/p/perlqt4/<br />
* Run with: {{ic|perl hello.pl}}<br />
{{hc|hello.pl|<nowiki><br />
use QtGui4;<br />
<br />
my $a = Qt::Application(\@ARGV);<br />
my $hello = Qt::Label("Hello World!", undef);<br />
<br />
$hello->show;<br />
exit $a->exec;<br />
</nowiki><br />
}}<br />
==== Lua ====<br />
* Package: {{AUR|libqtlua}}{{Broken package link|{{aur-mirror|libqtlua}}}}<br />
* Website: http://www.nongnu.org/libqtlua/<br />
* Run with: {{ic|qtlua hello.lua}}<br />
{{hc|hello.lua|<nowiki><br />
label = qt.new_widget("QLabel")<br />
<br />
label:setText("Hello World!")<br />
label:show()</nowiki><br />
}}<br />
<br />
{{Note|QtLua is not designed to develop an application in pure Lua but rather to extend a Qt C++ application using Lua as scripting language.}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Icon theme is not applied ===<br />
<br />
Since Qt 5.1 SVG support has moved into a module. Since {{Pkg|qt5-base}} does not depend on {{Pkg|qt5-svg}} it may happen that the {{Pkg|qt5-base}} is installed but not {{Pkg|qt5-svg}}. This results in deceptive icon theme behaviour. Since SVG is not supported the icons are silently skipped and the icon theme may seem to be unused. Installing {{Pkg|qt5-svg}} explicitly solves the problem.<br />
<br />
=== Theme not applied to root applications ===<br />
<br />
As the user theme file ({{ic|$XDG_CONFIG_HOME/Trolltech.conf}}), are not read by other accounts, the selected theme will not apply to [[Running_X_apps_as_root|X applications run as root]]. Possible solutions include:<br />
<br />
* Create symlinks, e.g<br />
# ln -s /home/[username]/.config/Trolltech.conf /etc/xdg/Trolltech.conf<br />
* Configure system-wide theme file: {{ic|/etc/xdg/Trolltech.conf}}<br />
* Adjust the theme as root<br />
<br />
=== Qt4 style not respected ===<br />
<br />
If pure Qt4 (non-KDE) applications do not stick with your selected Qt4 style, then you'll probably need to tell Qt4 how to find KDE's styles (Oxygen, Phase etc.). You just need to set the environment variable QT_PLUGIN_PATH. E.g. put<br />
<br />
export QT_PLUGIN_PATH=$HOME/.kde4/lib/kde4/plugins/:/usr/lib/kde4/plugins/<br />
<br />
into your {{ic|/etc/profile}} (or {{ic|~/.profile}} if you do not have root access). {{ic|qtconfig-qt4}} should then be able to find your kde styles and everything should look nice again!<br />
<br />
Alternatively, you can symlink the Qt4 styles directory to the KDE4 styles one:<br />
# ln -s /usr/lib/{kde,qt}4/plugins/styles/[theme name]<br />
<br />
=== Qt5 platform plugins and missing dependencies ===<br />
<br />
{{Accuracy|1=Is this issue still valid? (e.g. see {{Bug|40468}}) {{Pkg|qt5-base}} depends on {{Pkg|libxkbcommon-x11}} since [https://git.archlinux.org/svntogit/packages.git/commit/trunk?h=packages/qt5-base&id=d76d85392dfa67ba22c2c00d7c08ca4c2b923dd2]. Also, rather than packaging bug, it may also indicate upstream bug ({{Bug|45612}}).}}<br />
<br />
Using {{Pkg|qt5-base}} will install Qt5, which makes use of [http://doc.qt.io/qt-5/qpa.html platform abstractions], but some platform abstraction plugin dependencies may be missing. Qt may tell you that the plugin is unavailable, rather than resolve the chain of missing dependencies for other packages.<br />
<br />
For instance, if your application relies on [http://xcb.freedesktop.org xcb], and dependencies of the xcb library are missing, Qt will report:<br />
<br />
This application failed to start because it could not find or load the Qt platform plugin "xcb". Available plugins are: xcb.<br />
<br />
Reinstalling the application may fix this problem.<br />
<br />
This implies the application package misses some of its required dependencies not provided by {{Pkg|qt5-base}}. You can use ''ldd'' to identify which are missing (e.g. {{ic|ldd /usr/bin/''application'' &#124;grep -e xcb}}) and file a bug against the application package. The Qt5 page proposes a [http://doc.qt.io/qt-5/linux-requirements.html list of packages] that are recommended for installation; it can help to identify the one missing.<br />
<br />
== See also ==<br />
* [http://qt.io/ Official Website]<br />
* [http://doc.qt.io/ Qt Documentation]<br />
* [http://planet.qt.io/ Planet Qt]<br />
* [http://qt-apps.org/ Qt Applications]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=Qt&diff=445696Qt2016-08-07T14:03:52Z<p>Alive4ever: /* Configuration of Qt5 apps under environments other than KDE */ Add workaround to beautify qt applications via ~/.profile</p>
<hr />
<div>[[Category:Widget toolkits]]<br />
[[ja:Qt]]<br />
[[ru:Qt]]<br />
[[zh-CN:Qt]]<br />
{{Related articles start}}<br />
{{Related|KDE}}<br />
{{Related|Uniform Look for Qt and GTK Applications}}<br />
{{Related|GTK+}}<br />
{{Related articles end}}<br />
[http://qt-project.org/ Qt] is a cross-platform application and widget toolkit that uses standard C++ but makes extensive use of a special code generator (called the [http://qt-project.org/doc/qt-4.8/moc.html Meta Object Compiler], or ''moc'') together with several macros to enrich the language. Some of its more important features include:<br />
* Running on the major desktop platforms and some of the mobile platforms.<br />
* Extensive internationalization support.<br />
* A complete library that provides SQL database access, XML parsing, thread management, network support, and a unified cross-platform application programming interface (API) for file handling.<br />
<br />
The Qt framework is emerging as a major development platform and is the basis of the [[KDE]] software community, among other important open source and proprietary applications such as [[VLC]], [[VirtualBox]], [[Mathematica]], [[Skype]] and many others.<br />
<br />
== Installation ==<br />
Two versions of Qt are currently available in the [[official repositories]]. They can be [[Pacman|installed]] with the following packages:<br />
* '''Qt 5.x''' is available in the {{Pkg|qt5-base}} package, with documentation in the {{Pkg|qt5-doc}} package.<br />
* '''Qt 4.x''' is available in the {{Pkg|qt4}} package, with documentation on AUR in the {{AUR|qt4-doc}} package.<br />
* '''Qt 3.x''' is available from the AUR in the {{AUR|qt3}} package, with documentation on AUR in the {{AUR|qt3-doc}} package.<br />
<br />
{{ Warning|Qt packages do not provide the usual bins (e.g. ''qmake'') in {{ic|/usr/bin}} anymore. Instead {{ic|-qt5}}, {{ic|-qt4}} and {{ic|-qt3}} symlinks are provided (e.g. {{ic|qmake-qt5}}, {{ic|qmake-qt4}}, {{ic|qmake-qt3}}). This may cause compilation failures in Qt3/4 applications.<br />
To install usual bins, see [[#Default Qt toolkit]] section. }}<br />
<br />
== Default Qt toolkit ==<br />
By installing {{Pkg|qtchooser}} you can restore the usual bins (e.g. ''qmake'') in {{ic|/usr/bin}} and setup the Qt toolkit to use. By default Qt5 is used.<br />
<br />
=== Using environment variables ===<br />
To define default Qt toolkit, you can create {{ic|QT_SELECT}} [[environment variable]]. For example, to set Qt4, do {{ic|1=export QT_SELECT=4}} in your shell's init file (e.g. {{ic|~/.bash_profile.}} or {{ic|~/.zsh_profile.}}).<br />
<br />
=== Using configuration files ===<br />
You can set default Qt toolkit by creating a symlink {{ic|~/.config/qtchooser/default.conf}} to one of ''.conf'' files in {{ic|/etc/xdg/qtchooser/}} directory. For example, to set Qt4 symlink {{ic|/etc/xdg/qtchooser/4.conf}} to {{ic|~/.config/qtchooser/default.conf}}:<br />
<br />
$ ln -s {{ic|/etc/xdg/qtchooser/4.conf}} {{ic|~/.config/qtchooser/default.conf}}<br />
<br />
== Appearance ==<br />
=== Qt4 ===<br />
Qt4 application will try to mimic the behavior of the desktop environment they are running on, unless they run into some problems or hard-coded settings.<br />
* In KDE Plasma, it uses the actually selected Qt style. It can be configured using ''KDE System Settings'' (''systemsettings5''), the settings can be found in ''Appearance > Application Style > Widget Style''.<br />
* In Cinnamon, GNOME, Xfce, it uses GTK+ ([[Uniform look for Qt and GTK applications#QGtkStyle|QGtkStyle]]).<br />
* In other desktop environments, it uses Windows.<br />
<br />
For those who want to change the look and feel of Qt4 applications, the ''Qt Configuration'' (''qtconfig-qt4'') GUI tool is provided by the {{Pkg|qt4}} package. It offers a simple interface to configure the appearance of Qt4 applications including style, colors, fonts and some further options.<br />
<br />
{{Note|If you use ''GTK+'' style, then color and font settings will be ignored, and inherited from GTK+ 2.}}<br />
<br />
Qt keeps all its configuration information in {{ic|/etc/xdg/Trolltech.conf}} (system-wide) or {{ic|~/.config/Trolltech.conf}} (user-specific). The file is rather difficult to navigate because it contains a lot of information not related to appearance, but for any changes you can just add to the end of the file and overwrite any previous values (make sure to add your modification under the [Qt] header).<br />
<br />
For example, to change the theme to QtCurve, add:<br />
{{hc|~/.config/Trolltech.conf|<nowiki><br />
...<br />
[Qt]<br />
style=QtCurve<br />
</nowiki>}}<br />
<br />
The following styles are included in Qt4: ''CDE'', ''Cleanlooks'', ''GTK+'', ''Motif'', ''Plastique'', ''Windows''. Others can be installed from the official repositories or the [[AUR]] (most are written for KDE Plasma Desktop):<br />
* {{App|Breeze|Artwork, styles and assets for the Breeze visual style for the Plasma Desktop.|https://projects.kde.org/projects/kde/workspace/breeze|{{Pkg|breeze-kde4}}}}<br />
* {{App|[[Wikipedia:Oxygen Project|Oxygen]]|KDE Oxygen style.|https://projects.kde.org/projects/kde/workspace/oxygen|{{Pkg|oxygen-kde4}}}}<br />
* {{App|QtCurve|A configurable set of widget styles for KDE and Gtk.|https://projects.kde.org/projects/playground/base/qtcurve|{{Pkg|qtcurve-qt4}}}}<br />
* {{App|Adwaita-Qt| A style to bend Qt applications to look like they belong into GNOME Shell.|https://github.com/MartinBriza/adwaita-qt|{{AUR|adwaita-qt4}}}}<br />
<br />
=== Qt5 ===<br />
Qt5 decides the style to use based on what desktop environment is used:<br />
* In KDE Plasma, it uses the actually selected Qt style. It can be configured using ''KDE System Settings'' (''systemsettings5''), the settings can be found in ''Appearance > Application Style > Widget Style''.<br />
* In Cinnamon, GNOME, MATE, LXDE, Xfce, it uses GTK+ ([[Uniform look for Qt and GTK applications#QGtkStyle|QGtkStyle]]).<br />
* In other desktop environments, it uses Fusion.<br />
<br />
To force a specific style, you can set the {{ic|1=QT_STYLE_OVERRIDE}} [[environment variable]]. Specifically, set it to {{ic|gtk2}} if you want to use the [[GTK+]] theme (Note: you will need to install the Qt style plugins mention below to get the GTK+ style). Qt5 applications also support the {{ic|-style}} flag, which you can use to launch a Qt5 application with a specific style.<br />
<br />
The following styles are included in Qt5: ''Fusion'', ''Windows''. Others can be installed from the official repositories:<br />
* {{App|Breeze|Artwork, styles and assets for the Breeze visual style for the Plasma Desktop.|https://projects.kde.org/projects/kde/workspace/breeze|{{Pkg|breeze}}}}<br />
* {{App|Oxygen|KDE Oxygen style.|https://projects.kde.org/projects/kde/workspace/oxygen|{{Pkg|oxygen}}}}<br />
* {{App|QtCurve|A configurable set of widget styles for KDE and Gtk.|https://projects.kde.org/projects/playground/base/qtcurve|{{Pkg|qtcurve-qt5}}}}<br />
* {{App|Adwaita-Qt|A style to bend Qt applications to look like they belong into GNOME Shell.|https://github.com/MartinBriza/adwaita-qt|{{AUR|adwaita-qt5}}}}<br />
* {{App|Qt style plugins|Additional style plugins for Qt5, including ''GTK+'', ''Cleanlooks'', ''Motif'', ''Plastique''.|http://code.qt.io/cgit/qt/qtstyleplugins.git|{{AUR|qt5-styleplugins}}}}<br />
<br />
=== Qt Style Sheets ===<br />
An interesting way of customizing the look and feel of a Qt application is using Style Sheets, which are just simple CSS files. Using Style Sheets, one can modify the appearance of every widget in the application.<br />
<br />
To run an application with a different style just execute:<br />
$ qt_application -stylesheet ''style.qss''<br />
<br />
For more information on Qt Style Sheets see the [http://doc.qt.io/qt-5/stylesheet-reference.html official documentation] or other [http://thesmithfam.org/blog/2009/09/10/qt-stylesheets-tutorial/ tutorials]. As an example Style Sheet see this [http://kde-apps.org/content/show.php/roxydoxy?content&#61;125979 Dolphin modification].<br />
<br />
=== GTK+ and Qt ===<br />
If you have GTK+ and Qt applications, their looks might not exactly blend in very well. If you wish to make your GTK+ styles match your Qt styles please read [[Uniform look for Qt and GTK applications]].<br />
<br />
=== Configuration of Qt5 apps under environments other than KDE ===<br />
<br />
Unlike Qt4, Qt5 doesn't ship a qtconfig utility to configure fonts, icons or styles. Instead, it will try to use the settings from the running DE. In KDE or GNOME this works well, but in other less popular DEs or WM it can lead to missing icons in Qt5 applications. One way to solve this is to fake the running desktop environment by setting <br />
{{ic|1=XDG_CURRENT_DESKTOP=KDE}} or {{ic|GNOME}}, and then using the corresponding configuration application to set the desired icon set.<br />
<br />
Another solution is provided by the {{pkg|qt5ct}} package, which provides a DE independent Qt5 QPA and a configuration utility. After installing the package, run {{ic|qt5ct}} to set an icon theme, and set the environment variable {{ic|1=QT_QPA_PLATFORMTHEME="qt5ct"}} so that the settings are picked up by Qt applications. Alternatively, use {{ic|--platformtheme qt5ct}} as argument to the Qt5 application.<br />
<br />
To automatically set {{ic|QT_QPA_PLATFORMTHEME}} for user session, add the following line to {ic|~/.profile}.<br />
<br />
[ "$XDG_CURRENT_DESKTOP" = "KDE" -o "$XDG_CURRENT_DESKTOP" = "GNOME" ] || export QT_QPA_PLATFORMTHEME="qt5ct"<br />
<br />
This will export {{ic|QT_QPA_PLATFORMTHEME}} environment variable for the whole user session. Note that this doesn't work on [[enlightenment]] because it has its own custom environment variable setting instead of getting it from {{ic|~/.profile}} file.<br />
<br />
If the below errors are received, and some icons still do not appear in some of the apps, install {{pkg|oxygen}} and {{pkg|oxygen-icons}}:<br />
<br />
Icon theme "oxygen" not found.<br />
Icon theme "oxygen" not found.<br />
Error: standard icon theme "oxygen" not found!<br />
<br />
== Development ==<br />
<br />
=== Supported platforms ===<br />
<br />
Qt supports most platforms that are available today, even some of the more obscure ones, with more ports appearing every once in a while. For a more complete list see the [[Wikipedia:Qt_(framework)#Platforms|Qt Wikipedia article]].<br />
<br />
==== Android ====<br />
<br />
{{Expansion|Create a PKGBUILD and submit to the AUR as e.g. ''qt-android''.}}<br />
<br />
Use the [http://download.qt.io/official_releases/qt/5.5/5.5.1/qt-opensource-linux-x64-android-5.5.1.run Qt for Android installer].<br />
<br />
=== Tools ===<br />
<br />
The following are official Qt tools:<br />
<br />
* {{App|[[Wikipedia:Qt Creator|Qt Creator]]|A cross-platform IDE tailored for Qt that supports all of its features.|http://doc.qt.io/qtcreator/|{{Pkg|qtcreator}}}}<br />
* {{App|Qt Linguist|A set of tools that speed the translation and internationalization of Qt applications.|http://doc.qt.io/qt-5/qtlinguist-index.html|Qt 5: {{Pkg|qt5-tools}}, Qt 4: {{Pkg|qt4}}}}<br />
* {{App|Qt Assistant|A configurable and redistributable documentation reader for Qt ''qch'' files.|http://doc.qt.io/qt-5/qtassistant-index.html|Qt 5: {{Pkg|qt5-tools}}, Qt 4: {{Pkg|qt4}}}}<br />
* {{App|Qt Designer|A powerful cross-platform GUI layout and forms builder for Qt widgets.|http://doc.qt.io/qt-5/qtdesigner-manual.html|Qt 5: {{Pkg|qt5-tools}}, Qt 4: {{Pkg|qt4}}}}<br />
* {{App|Qt Quick Designer|A visual editor for QML files which supports WYSIWYG. It allows you to rapidly design and build Qt Quick applications and components from scratch.|http://doc.qt.io/qtcreator/creator-using-qt-quick-designer.html|{{Pkg|qtcreator}}}}<br />
* {{App|qmlscene|A tool for loading QML documents that makes it easy to quickly develop and debug QML applications.|http://doc.qt.io/qt-5/qtquick-qmlscene.html|Qt 5: {{Pkg|qt5-declarative}}, Qt 4 QML Viewer: {{Pkg|qt4}}}}<br />
* {{App|[[Wikipedia:Qmake|qmake]]|A tool that helps simplify the build process for development project across different platforms, similar to [[Wikipedia:CMake|cmake]], but with fewer options and tailored for Qt applications.|http://doc.qt.io/qt-5/qmake-manual.html|Qt 5: {{Pkg|qt5-base}}, Qt 4: {{Pkg|qt4}}}}<br />
* {{App|uic|A tool that reads ''*.ui'' XML files and generates the corresponding C++ files.|http://doc.qt.io/qt-5/uic.html|Qt 5: {{Pkg|qt5-base}}, Qt 4: {{Pkg|qt4}}}}<br />
* {{App|rcc|A tool that is used to embed resources (such as pictures) into a Qt application during the build process. It works by generating a C++ source file containing data specified in a Qt resource (.qrc) file.|http://doc.qt.io/qt-5/rcc.html|Qt 5: {{Pkg|qt5-base}}, Qt 4: {{Pkg|qt4}}}}<br />
* {{App|moc|A tool that handles Qt's C++ extensions (the signals and slots mechanism, the run-time type information, and the dynamic property system, etc.).|http://doc.qt.io/qt-5/moc.html|Qt 5: {{Pkg|qt5-base}}, Qt 4: {{Pkg|qt4}}}}<br />
<br />
=== Bindings ===<br />
Qt has bindings for all of the more popular languages, for a full list see [[Wikipedia:Qt (framework)#Programming language bindings|this list]].<br />
<br />
The following examples display a small 'Hello world!' message in a window.<br />
<br />
==== C++ ====<br />
* Package: <br />
** {{Pkg|qt4}} - Version 4.x of the Qt toolkit.<br />
** {{Pkg|qt5-base}} - Version 5.x of the Qt toolkit.<br />
* Website: http://qt-project.org/<br />
* Build: <br />
** The Qt4 version: {{ic|g++ $(pkg-config --cflags --libs QtGui) -o hello hello.cpp}}<br />
** The Qt5 version: {{ic|g++ $(pkg-config --cflags --libs Qt5Widgets) -fPIC -o hello hello.cpp}}<br />
* Run with: {{ic|./hello}}<br />
{{hc|hello.cpp|<br />
#include <QApplication><br />
#include <QLabel><br />
<br />
int main(int argc, char **argv)<br />
{<br />
QApplication app(argc, argv);<br />
QLabel hello("Hello world!");<br />
<br />
hello.show();<br />
return app.exec();<br />
}<br />
}}<br />
<br />
==== QML ====<br />
* Package: {{Pkg|qt4}} or {{Pkg|qt5-declarative}}.<br />
* Website: http://qt-project.org/<br />
* Run with: {{ic|qmlviewer-qt4 hello.qml}} or {{ic|qmlscene-qt5 hello.qml}}<br />
{{hc|hello.qml|<br />
import QtQuick 1.0<br />
<br />
Rectangle {<br />
id: page<br />
width: 400; height: 100<br />
color: "lightgray"<br />
<br />
Text {<br />
id: helloText<br />
text: "Hello world!"<br />
anchors.horizontalCenter: page.horizontalCenter<br />
anchors.verticalCenter: page.verticalCenter<br />
font.pointSize: 24; font.bold: true<br />
}<br />
}<br />
}}<br />
{{Note|For version 5.x of the Qt toolkit, we need to import QtQuick 2.y.}}<br />
<br />
==== Python (PyQt) ====<br />
* Package:<br />
** {{Pkg|python-pyqt4}} - Python 3.x bindings for Qt 4<br />
** {{Pkg|python2-pyqt4}} - Python 2.x bindings for Qt 4<br />
** {{Pkg|python-pyqt5}} - Python 3.x bindings for Qt 5<br />
** {{Pkg|python2-pyqt5}} - Python 2.x bindings for Qt 5<br />
<br />
* Website: http://www.riverbankcomputing.co.uk/software/pyqt/intro<br />
* Run with: {{ic|python hello-pyqt.py}} or {{ic|python2 hello-pyqt.py}}.<br />
{{hc|hello-pyqt.py|<nowiki><br />
import sys<br />
from PyQt4 import QtGui<br />
<br />
app = QtGui.QApplication(sys.argv)<br />
label = QtGui.QLabel("Hello world!")<br />
<br />
label.show()<br />
sys.exit(app.exec_())</nowiki><br />
}}<br />
<br />
The Qt 5.x version is slighly different:<br />
{{hc|hello-pyqt.py|<nowiki><br />
import sys<br />
from PyQt5 import QtWidgets<br />
<br />
app = QtWidgets.QApplication(sys.argv)<br />
label = QtWidgets.QLabel("Hello world!")<br />
<br />
label.show()<br />
sys.exit(app.exec_())</nowiki><br />
}}<br />
<br />
==== Python (PySide) ====<br />
* Package:<br />
** {{Pkg|python-pyside}} - Python 3.x bindings<br />
** {{Pkg|python2-pyside}} - Python 2.x bindings<br />
* Website: http://www.pyside.org/<br />
* Run with: {{ic|python hello-pyside.py}} or {{ic|python2 hello-pyside.py}}<br />
{{hc|hello-pyside.py|<nowiki><br />
import sys<br />
from PySide.QtCore import *<br />
from PySide.QtGui import *<br />
<br />
app = QApplication(sys.argv)<br />
label = QLabel("Hello world!")<br />
<br />
label.show()<br />
sys.exit(app.exec_())</nowiki><br />
}}<br />
<br />
==== C# ====<br />
* Package: {{AUR|kdebindings-qyoto}}{{Broken package link|{{aur-mirror|kdebindings-qyoto}}}}<br />
* Website: http://techbase.kde.org/Development/Languages/Qyoto<br />
* Build with: {{ic|mcs -pkg:qyoto hello.cs}}<br />
* Run with: {{ic|mono hello.exe}}<br />
{{hc|hello.cs|<br />
using System;<br />
using Qyoto;<br />
<br />
public class Hello {<br />
public static int Main(String[] args) {<br />
new QApplication(args);<br />
new QLabel("Hello world!").Show();<br />
<br />
return QApplication.Exec();<br />
}<br />
}<br />
}}<br />
<br />
==== Ruby ====<br />
* Package: {{AUR|kdebindings-qtruby}}{{Broken package link|{{aur-mirror|kdebindings-qtruby}}}}<br />
* Website: http://rubyforge.org/projects/korundum/<br />
* Run with: {{ic|ruby hello.rb}}<br />
{{hc|hello.rb|<nowiki><br />
require 'Qt4'<br />
<br />
app = Qt::Application.new(ARGV)<br />
hello = Qt::Label.new('Hello World!')<br />
<br />
hello.show<br />
app.exec</nowiki><br />
}}<br />
==== Java ====<br />
* Package: {{AUR|qtjambi}}{{Broken package link|{{aur-mirror|qtjambi}}}} or {{AUR|qtjambi-beta}}{{Broken package link|{{aur-mirror|qtjambi-beta}}}}.<br />
* Website: http://qt-jambi.org/<br />
* Build with: {{ic|javac Hello.java -cp /opt/qtjambi-beta/qtjambi-linux64-community-4.7.0/qtjambi-4.7.0.jar}}.<br />
* Run with: {{ic|java -cp /opt/qtjambi-beta/qtjambi-linux64-community-4.7.0/qtjambi-4.7.0.jar:. Hello}}.<br />
{{hc|Hello.java|<nowiki><br />
import com.trolltech.qt.gui.*;<br />
<br />
public class Hello<br />
{<br />
public static void main(String args[])<br />
{<br />
QApplication.initialize(args);<br />
QLabel hello = new QLabel("Hello World!");<br />
<br />
hello.show();<br />
QApplication.exec();<br />
}<br />
}</nowiki><br />
}}<br />
{{Note|The build instructions and example have been tested on the beta version of Qt Jambi 4.7.0.}}<br />
<br />
==== Perl ====<br />
* Package: {{AUR|kdebindings-perlqt}}{{Broken package link|{{aur-mirror|kdebindings-perlqt}}}}<br />
* Website: http://code.google.com/p/perlqt4/<br />
* Run with: {{ic|perl hello.pl}}<br />
{{hc|hello.pl|<nowiki><br />
use QtGui4;<br />
<br />
my $a = Qt::Application(\@ARGV);<br />
my $hello = Qt::Label("Hello World!", undef);<br />
<br />
$hello->show;<br />
exit $a->exec;<br />
</nowiki><br />
}}<br />
==== Lua ====<br />
* Package: {{AUR|libqtlua}}{{Broken package link|{{aur-mirror|libqtlua}}}}<br />
* Website: http://www.nongnu.org/libqtlua/<br />
* Run with: {{ic|qtlua hello.lua}}<br />
{{hc|hello.lua|<nowiki><br />
label = qt.new_widget("QLabel")<br />
<br />
label:setText("Hello World!")<br />
label:show()</nowiki><br />
}}<br />
<br />
{{Note|QtLua is not designed to develop an application in pure Lua but rather to extend a Qt C++ application using Lua as scripting language.}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Icon theme is not applied ===<br />
<br />
Since Qt 5.1 SVG support has moved into a module. Since {{Pkg|qt5-base}} does not depend on {{Pkg|qt5-svg}} it may happen that the {{Pkg|qt5-base}} is installed but not {{Pkg|qt5-svg}}. This results in deceptive icon theme behaviour. Since SVG is not supported the icons are silently skipped and the icon theme may seem to be unused. Installing {{Pkg|qt5-svg}} explicitly solves the problem.<br />
<br />
=== Theme not applied to root applications ===<br />
<br />
As the user theme file ({{ic|$XDG_CONFIG_HOME/Trolltech.conf}}), are not read by other accounts, the selected theme will not apply to [[Running_X_apps_as_root|X applications run as root]]. Possible solutions include:<br />
<br />
* Create symlinks, e.g<br />
# ln -s /home/[username]/.config/Trolltech.conf /etc/xdg/Trolltech.conf<br />
* Configure system-wide theme file: {{ic|/etc/xdg/Trolltech.conf}}<br />
* Adjust the theme as root<br />
<br />
=== Qt4 style not respected ===<br />
<br />
If pure Qt4 (non-KDE) applications do not stick with your selected Qt4 style, then you'll probably need to tell Qt4 how to find KDE's styles (Oxygen, Phase etc.). You just need to set the environment variable QT_PLUGIN_PATH. E.g. put<br />
<br />
export QT_PLUGIN_PATH=$HOME/.kde4/lib/kde4/plugins/:/usr/lib/kde4/plugins/<br />
<br />
into your {{ic|/etc/profile}} (or {{ic|~/.profile}} if you do not have root access). {{ic|qtconfig-qt4}} should then be able to find your kde styles and everything should look nice again!<br />
<br />
Alternatively, you can symlink the Qt4 styles directory to the KDE4 styles one:<br />
# ln -s /usr/lib/{kde,qt}4/plugins/styles/[theme name]<br />
<br />
=== Qt5 platform plugins and missing dependencies ===<br />
<br />
{{Accuracy|1=Is this issue still valid? (e.g. see {{Bug|40468}}) {{Pkg|qt5-base}} depends on {{Pkg|libxkbcommon-x11}} since [https://git.archlinux.org/svntogit/packages.git/commit/trunk?h=packages/qt5-base&id=d76d85392dfa67ba22c2c00d7c08ca4c2b923dd2]. Also, rather than packaging bug, it may also indicate upstream bug ({{Bug|45612}}).}}<br />
<br />
Using {{Pkg|qt5-base}} will install Qt5, which makes use of [http://doc.qt.io/qt-5/qpa.html platform abstractions], but some platform abstraction plugin dependencies may be missing. Qt may tell you that the plugin is unavailable, rather than resolve the chain of missing dependencies for other packages.<br />
<br />
For instance, if your application relies on [http://xcb.freedesktop.org xcb], and dependencies of the xcb library are missing, Qt will report:<br />
<br />
This application failed to start because it could not find or load the Qt platform plugin "xcb". Available plugins are: xcb.<br />
<br />
Reinstalling the application may fix this problem.<br />
<br />
This implies the application package misses some of its required dependencies not provided by {{Pkg|qt5-base}}. You can use ''ldd'' to identify which are missing (e.g. {{ic|ldd /usr/bin/''application'' &#124;grep -e xcb}}) and file a bug against the application package. The Qt5 page proposes a [http://doc.qt.io/qt-5/linux-requirements.html list of packages] that are recommended for installation; it can help to identify the one missing.<br />
<br />
== See also ==<br />
* [http://qt.io/ Official Website]<br />
* [http://doc.qt.io/ Qt Documentation]<br />
* [http://planet.qt.io/ Planet Qt]<br />
* [http://qt-apps.org/ Qt Applications]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=Talk:GnuPG&diff=444501Talk:GnuPG2016-08-04T02:27:43Z<p>Alive4ever: /* System login with gnupg smartcard (yubikey, p-card, rsa token, etc) */ missing url label</p>
<hr />
<div>== <s>gpg-agent socket path</s> ==<br />
<br />
Under the SSH agent section, no matter if I set GNUPGHOME to ~/.gnupg or not, my gpg-agent does not work for SSH because the S.gpg-agent.ssh is not create in my ~/.gnupg directory. The S.gpg-agent.ssh file is created at /run/user/$UID/gnupg. If GNUPGHOME needs to be a specific directory such as /run/user/$UID/gnupg or a symlink needs to exist in the ~/.gnupg directory then that should be explained in the wiki article.<br />
<br />
{{unsigned|14:43, 23 June 2016|Dmp1ce}}<br />
<br />
:I can't find any reference of gpg using /run/user/$UID/gnupg by default. How do you start gpg-agent and what is in your gpg-agent.conf? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:47, 23 June 2016 (UTC)<br />
::http://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=commit;h=aab8a0b05292b0d06e3001a0b289224cb7156dbd<br />
::https://lists.gnupg.org/pipermail/gnupg-announce/2016q2/000390.html<br />
::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 14:49, 23 June 2016 (UTC)<br />
:: I start with gpg-connect-agent /bye >/dev/null 2>&1 [[User:Dmp1ce|Dmp1ce]] ([[User talk:Dmp1ce|talk]])<br />
:: My gpg-agent.conf<br />
::{{bc|<nowiki><br />
# Cache settings<br />
default-cache-ttl 10800<br />
default-cache-ttl-ssh 10800<br />
<br />
# Enable SSH support<br />
enable-ssh-support<br />
<br />
# Keyboard control<br />
#no-grab<br />
<br />
# PIN entry program<br />
#pinentry-program /usr/bin/pinentry-curses<br />
#pinentry-program /usr/bin/pinentry-qt4<br />
#pinentry-program /usr/bin/pinentry-kwallet<br />
#pinentry-program /usr/bin/pinentry-gtk-2<br />
<br />
# For duply<br />
allow-loopback-pinentry<br />
</nowiki>}}<br />
::--[[User:Dmp1ce|Dmp1ce]] ([[User talk:Dmp1ce|talk]]) 15:02, 23 June 2016 (UTC)<br />
<br />
:::OK, thank you for correcting me. I've added the [https://wiki.archlinux.org/index.php?title=GnuPG&diff=438807&oldid=438806 rest of the story], closing. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:27, 23 June 2016 (UTC)<br />
::::Pretty sure this isn't correct. Everything says it will use /run/usr/$UID/ if it exists, and systemd uses it, so it exists on every (supported) Arch system.<br />
::::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 15:34, 23 June 2016 (UTC)<br />
<br />
:::::The commit message says: {{bc|<nowiki><br />
To cope with non standard homedirs (via GNUPGHOME or --homedir) the<br />
SHA-1 hash of the homedir is computed, left truncated to 120 bits,<br />
zBase-32 encoded, prefixed with "d.", and appended to<br />
"[/var]/run/user/$(id -u)/gnupg/". If that directory exists and has<br />
proper permissions it is returned as socket dir - if not the homedir<br />
is used. Due to cleanup issues, this directory will not be<br />
auto-created but needs to be created by the user in advance.<br />
</nowiki>}}<br />
:::::That's also the reason why the {{ic|--create-socketdir}} and {{ic|--remove-socketdir}} commands were added to ''gpgconf'', as mentioned in the changelog.<br />
:::::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:41, 23 June 2016 (UTC)<br />
::::::Ah, to run multiple agents. Got it, thanks. [[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 15:50, 23 June 2016 (UTC)<br />
<br />
== <s>gnupg_SSH_AUTH_SOCK_by</s> ==<br />
<br />
In [[GnuPG#SSH_agent]], the test {{ic|if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then}} has been taken from the {{ic|gpg-agent(1)}} man page, but it's not clear what's the purpose of the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable. In [http://www.gossamer-threads.com/lists/gnupg/users/67797#67797] it says that it's "often used for testing", but I don't quite get it. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:15, 24 June 2016 (UTC)<br />
:{{ic|gnupg_SSH_AUTH_SOCK_by}} is used by gpg-agent but I'm not sure the reason behind it. Here is the code in gpg-agent that used that environment variable. http://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307 --[[User:Dmp1ce|Dmp1ce]] ([[User talk:Dmp1ce|talk]]) 18:44, 24 June 2016 (UTC)<br />
<br />
::Thanks, I think that I got it now: [https://wiki.archlinux.org/index.php?title=GnuPG&diff=441681&oldid=441641]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:04, 16 July 2016 (UTC)<br />
<br />
== System login with gnupg smartcard (yubikey, p-card, rsa token, etc) ==<br />
gnupg with [https://git.gnupg.org/cgi-bin/gitweb.cgi?p=poldi.git poldi] can be used for system login. There is a [https://bbs.archlinux.org/viewtopic.php?id=215554 thread] asking whether it is possible to use gpg for system login.<br />
A new tip section explaining gnupg smartcard for logging into Arch Linux system is a nice addition here.<br />
<br />
[[User:Alive4ever|Alive4ever]] ([[User talk:Alive4ever|talk]]) 02:27, 4 August 2016 (UTC)</div>Alive4everhttps://wiki.archlinux.org/index.php?title=Talk:GnuPG&diff=444500Talk:GnuPG2016-08-04T02:27:02Z<p>Alive4ever: /* System login with gnupg smartcard (yubikey, p-card, rsa token, etc) */ fix missing link</p>
<hr />
<div>== <s>gpg-agent socket path</s> ==<br />
<br />
Under the SSH agent section, no matter if I set GNUPGHOME to ~/.gnupg or not, my gpg-agent does not work for SSH because the S.gpg-agent.ssh is not create in my ~/.gnupg directory. The S.gpg-agent.ssh file is created at /run/user/$UID/gnupg. If GNUPGHOME needs to be a specific directory such as /run/user/$UID/gnupg or a symlink needs to exist in the ~/.gnupg directory then that should be explained in the wiki article.<br />
<br />
{{unsigned|14:43, 23 June 2016|Dmp1ce}}<br />
<br />
:I can't find any reference of gpg using /run/user/$UID/gnupg by default. How do you start gpg-agent and what is in your gpg-agent.conf? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:47, 23 June 2016 (UTC)<br />
::http://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=commit;h=aab8a0b05292b0d06e3001a0b289224cb7156dbd<br />
::https://lists.gnupg.org/pipermail/gnupg-announce/2016q2/000390.html<br />
::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 14:49, 23 June 2016 (UTC)<br />
:: I start with gpg-connect-agent /bye >/dev/null 2>&1 [[User:Dmp1ce|Dmp1ce]] ([[User talk:Dmp1ce|talk]])<br />
:: My gpg-agent.conf<br />
::{{bc|<nowiki><br />
# Cache settings<br />
default-cache-ttl 10800<br />
default-cache-ttl-ssh 10800<br />
<br />
# Enable SSH support<br />
enable-ssh-support<br />
<br />
# Keyboard control<br />
#no-grab<br />
<br />
# PIN entry program<br />
#pinentry-program /usr/bin/pinentry-curses<br />
#pinentry-program /usr/bin/pinentry-qt4<br />
#pinentry-program /usr/bin/pinentry-kwallet<br />
#pinentry-program /usr/bin/pinentry-gtk-2<br />
<br />
# For duply<br />
allow-loopback-pinentry<br />
</nowiki>}}<br />
::--[[User:Dmp1ce|Dmp1ce]] ([[User talk:Dmp1ce|talk]]) 15:02, 23 June 2016 (UTC)<br />
<br />
:::OK, thank you for correcting me. I've added the [https://wiki.archlinux.org/index.php?title=GnuPG&diff=438807&oldid=438806 rest of the story], closing. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:27, 23 June 2016 (UTC)<br />
::::Pretty sure this isn't correct. Everything says it will use /run/usr/$UID/ if it exists, and systemd uses it, so it exists on every (supported) Arch system.<br />
::::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 15:34, 23 June 2016 (UTC)<br />
<br />
:::::The commit message says: {{bc|<nowiki><br />
To cope with non standard homedirs (via GNUPGHOME or --homedir) the<br />
SHA-1 hash of the homedir is computed, left truncated to 120 bits,<br />
zBase-32 encoded, prefixed with "d.", and appended to<br />
"[/var]/run/user/$(id -u)/gnupg/". If that directory exists and has<br />
proper permissions it is returned as socket dir - if not the homedir<br />
is used. Due to cleanup issues, this directory will not be<br />
auto-created but needs to be created by the user in advance.<br />
</nowiki>}}<br />
:::::That's also the reason why the {{ic|--create-socketdir}} and {{ic|--remove-socketdir}} commands were added to ''gpgconf'', as mentioned in the changelog.<br />
:::::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:41, 23 June 2016 (UTC)<br />
::::::Ah, to run multiple agents. Got it, thanks. [[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 15:50, 23 June 2016 (UTC)<br />
<br />
== <s>gnupg_SSH_AUTH_SOCK_by</s> ==<br />
<br />
In [[GnuPG#SSH_agent]], the test {{ic|if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then}} has been taken from the {{ic|gpg-agent(1)}} man page, but it's not clear what's the purpose of the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable. In [http://www.gossamer-threads.com/lists/gnupg/users/67797#67797] it says that it's "often used for testing", but I don't quite get it. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:15, 24 June 2016 (UTC)<br />
:{{ic|gnupg_SSH_AUTH_SOCK_by}} is used by gpg-agent but I'm not sure the reason behind it. Here is the code in gpg-agent that used that environment variable. http://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307 --[[User:Dmp1ce|Dmp1ce]] ([[User talk:Dmp1ce|talk]]) 18:44, 24 June 2016 (UTC)<br />
<br />
::Thanks, I think that I got it now: [https://wiki.archlinux.org/index.php?title=GnuPG&diff=441681&oldid=441641]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:04, 16 July 2016 (UTC)<br />
<br />
== System login with gnupg smartcard (yubikey, p-card, rsa token, etc) ==<br />
gnupg with [https://git.gnupg.org/cgi-bin/gitweb.cgi?p=poldi.git] can be used for system login. There is a [https://bbs.archlinux.org/viewtopic.php?id=215554 thread] asking whether it is possible to use gpg for system login.<br />
A new tip section explaining gnupg smartcard for logging into Arch Linux system is a nice addition here.<br />
[[User:Alive4ever|Alive4ever]] ([[User talk:Alive4ever|talk]]) 02:26, 4 August 2016 (UTC)</div>Alive4everhttps://wiki.archlinux.org/index.php?title=Talk:GnuPG&diff=444499Talk:GnuPG2016-08-04T02:23:57Z<p>Alive4ever: gnupg smartcard login</p>
<hr />
<div>== <s>gpg-agent socket path</s> ==<br />
<br />
Under the SSH agent section, no matter if I set GNUPGHOME to ~/.gnupg or not, my gpg-agent does not work for SSH because the S.gpg-agent.ssh is not create in my ~/.gnupg directory. The S.gpg-agent.ssh file is created at /run/user/$UID/gnupg. If GNUPGHOME needs to be a specific directory such as /run/user/$UID/gnupg or a symlink needs to exist in the ~/.gnupg directory then that should be explained in the wiki article.<br />
<br />
{{unsigned|14:43, 23 June 2016|Dmp1ce}}<br />
<br />
:I can't find any reference of gpg using /run/user/$UID/gnupg by default. How do you start gpg-agent and what is in your gpg-agent.conf? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:47, 23 June 2016 (UTC)<br />
::http://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=commit;h=aab8a0b05292b0d06e3001a0b289224cb7156dbd<br />
::https://lists.gnupg.org/pipermail/gnupg-announce/2016q2/000390.html<br />
::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 14:49, 23 June 2016 (UTC)<br />
:: I start with gpg-connect-agent /bye >/dev/null 2>&1 [[User:Dmp1ce|Dmp1ce]] ([[User talk:Dmp1ce|talk]])<br />
:: My gpg-agent.conf<br />
::{{bc|<nowiki><br />
# Cache settings<br />
default-cache-ttl 10800<br />
default-cache-ttl-ssh 10800<br />
<br />
# Enable SSH support<br />
enable-ssh-support<br />
<br />
# Keyboard control<br />
#no-grab<br />
<br />
# PIN entry program<br />
#pinentry-program /usr/bin/pinentry-curses<br />
#pinentry-program /usr/bin/pinentry-qt4<br />
#pinentry-program /usr/bin/pinentry-kwallet<br />
#pinentry-program /usr/bin/pinentry-gtk-2<br />
<br />
# For duply<br />
allow-loopback-pinentry<br />
</nowiki>}}<br />
::--[[User:Dmp1ce|Dmp1ce]] ([[User talk:Dmp1ce|talk]]) 15:02, 23 June 2016 (UTC)<br />
<br />
:::OK, thank you for correcting me. I've added the [https://wiki.archlinux.org/index.php?title=GnuPG&diff=438807&oldid=438806 rest of the story], closing. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:27, 23 June 2016 (UTC)<br />
::::Pretty sure this isn't correct. Everything says it will use /run/usr/$UID/ if it exists, and systemd uses it, so it exists on every (supported) Arch system.<br />
::::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 15:34, 23 June 2016 (UTC)<br />
<br />
:::::The commit message says: {{bc|<nowiki><br />
To cope with non standard homedirs (via GNUPGHOME or --homedir) the<br />
SHA-1 hash of the homedir is computed, left truncated to 120 bits,<br />
zBase-32 encoded, prefixed with "d.", and appended to<br />
"[/var]/run/user/$(id -u)/gnupg/". If that directory exists and has<br />
proper permissions it is returned as socket dir - if not the homedir<br />
is used. Due to cleanup issues, this directory will not be<br />
auto-created but needs to be created by the user in advance.<br />
</nowiki>}}<br />
:::::That's also the reason why the {{ic|--create-socketdir}} and {{ic|--remove-socketdir}} commands were added to ''gpgconf'', as mentioned in the changelog.<br />
:::::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:41, 23 June 2016 (UTC)<br />
::::::Ah, to run multiple agents. Got it, thanks. [[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 15:50, 23 June 2016 (UTC)<br />
<br />
== <s>gnupg_SSH_AUTH_SOCK_by</s> ==<br />
<br />
In [[GnuPG#SSH_agent]], the test {{ic|if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then}} has been taken from the {{ic|gpg-agent(1)}} man page, but it's not clear what's the purpose of the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable. In [http://www.gossamer-threads.com/lists/gnupg/users/67797#67797] it says that it's "often used for testing", but I don't quite get it. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:15, 24 June 2016 (UTC)<br />
:{{ic|gnupg_SSH_AUTH_SOCK_by}} is used by gpg-agent but I'm not sure the reason behind it. Here is the code in gpg-agent that used that environment variable. http://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307 --[[User:Dmp1ce|Dmp1ce]] ([[User talk:Dmp1ce|talk]]) 18:44, 24 June 2016 (UTC)<br />
<br />
::Thanks, I think that I got it now: [https://wiki.archlinux.org/index.php?title=GnuPG&diff=441681&oldid=441641]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:04, 16 July 2016 (UTC)<br />
<br />
== System login with gnupg smartcard (yubikey, p-card, rsa token, etc) ==<br />
gnupg with [https://git.gnupg.org/poldi.git poldi] can be used for system login. There is a [https://bbs.archlinux.org/viewtopic.php?id=215554 thread] asking whether it is possible to use gpg for system login.<br />
A new tip section explaining gnupg smartcard for logging into Arch Linux system is a nice addition here.<br />
[[User:Alive4ever|Alive4ever]] ([[User talk:Alive4ever|talk]]) 02:23, 4 August 2016 (UTC)</div>Alive4everhttps://wiki.archlinux.org/index.php?title=XDM&diff=442759XDM2016-07-24T12:57:34Z<p>Alive4ever: /* Defining the session */ 744 permission is unsafe, better use 700 since xdm can live with 700</p>
<hr />
<div>[[Category:Display managers]]<br />
[[cs:XDM]]<br />
[[ja:XDM]]<br />
[[pt:XDM]]<br />
[[ru:XDM]]<br />
[[zh-CN:XDM]]<br />
{{Related articles start}}<br />
{{Related|Display manager}}<br />
{{Related articles end}}<br />
From [http://www.xfree86.org/current/xdm.1.html XDM manual page]:<br />
<br />
:''Xdm manages a collection of X displays, which may be on the local host or remote servers. The design of xdm was guided by the needs of X terminals as well as The Open Group standard XDMCP, the X Display Manager Control Protocol. Xdm provides services similar to those provided by init, getty and login on character terminals: prompting for login name and password, authenticating the user, and running a "session."''<br />
<br />
XDM provides a simple and straightforward graphical login prompt.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|xorg-xdm}} package. Then [[enable]] {{ic|xdm.service}}.<br />
<br />
If you would like to use an Arch Linux theme for XDM, you can optionally install the {{Pkg|xdm-archlinux}} package. If installing the latter package, then do '''not''' enable {{ic|xdm.service}}, but instead enable {{ic|xdm-archlinux.service}}.<br />
<br />
== Configuration ==<br />
<br />
=== Defining the session ===<br />
<br />
Unlike many more modern [[display manager]]s such as [[GDM]] or [[LightDM]], XDM does not source available sessions from .desktop files located in the {{ic|/usr/share/xsessions}} directory. As such, XDM does not have a 'session menu.' Instead, XDM will execute the {{ic|.xinitrc}} file in the home directory. See [[Xinitrc#Configuration]] for details.<br />
<br />
Ensure that the {{ic|.xinitrc}} file in your home directory is executable. To do this use the following command:<br />
<br />
$ chmod 700 ~/.xinitrc<br />
<br />
=== Theming ===<br />
<br />
For the exact meanings of the options discussed below, see the manual page of xdm. The configuration file is located in {{ic|/etc/X11/xdm/Xresources}}, notice that if you installed {{Pkg|xdm-archlinux}} the configuration file will instead be located in {{ic|/etc/X11/archlinux/xdm/Xresources}}.<br />
<br />
==== Background wallpaper ====<br />
<br />
You can use a program such as {{Pkg|qiv}} to set the background in XDM:<br />
<br />
* Install {{Pkg|qiv}}<br />
<br />
* Make a directory to store background images, e.g. {{ic|/root/backgrounds}} or {{ic|/usr/local/share/backgrounds}}<br />
<br />
* Place your images in the directory. <br />
<br />
* Edit {{ic|/etc/X11/xdm/Xsetup_0}}. Change the {{ic|xconsole}} command to:<br />
/usr/bin/qiv -zr /root/backgrounds/*<br />
<br />
==== Font ====<br />
<br />
* Edit {{ic|/etc/X11/xdm/Xresources}}. Add/replace the following defines:<br />
xlogin'''greetFont: -adobe-helvetica-bold-o-normal--20-'''-'''-'''-'''-'''-iso8859-1<br />
xlogin'''font: -adobe-helvetica-medium-r-normal--14-'''-'''-'''-'''-'''-iso8859-1<br />
xlogin'''promptFont: -adobe-helvetica-bold-r-normal--14-'''-'''-'''-'''-'''-iso8859-1<br />
xlogin'''failFont: -adobe-helvetica-bold-r-normal--14-'''-'''-'''-'''-'''-iso8859-1<br />
<br />
==== Login dialog positioning ====<br />
<br />
This configuration will move the login dialog to the bottom right of the screen.<br />
<br />
xlogin*frameWidth: 1<br />
xlogin*innerFramesWidth: 1<br />
xlogin*logoPadding: 0<br />
xlogin*geometry: 300x175-0-0<br />
<br />
==== Removing the logo ====<br />
Comment out the logo defines:<br />
#xlogin*logoFileName: /usr/X11R6/lib/X11/xdm/pixmaps/xorg.xpm<br />
#xlogin*logoFileName: /usr/X11R6/lib/X11/xdm/pixmaps/xorg-bw.xpm<br />
<br />
=== Multiple X sessions & Login in the window ===<br />
<br />
With the [[Xdmcp]] enable, you can easily run multiple X sessions simultaneously on the same machine.<br />
# X -query ip_xdmcp_server :2<br />
<br />
This will launch the second session, in window you need {{Pkg|xorg-server-xephyr}}<br />
# Xephyr -query this_machine_ip :2<br />
<br />
=== Passwordless login ===<br />
<br />
In order to enable passwordless login for XDM, add the line below to {{ic|/etc/X11/xdm/Xresources}}:<br />
xlogin*allowNullPasswd: true</div>Alive4everhttps://wiki.archlinux.org/index.php?title=X_resources&diff=442570X resources2016-07-23T17:02:33Z<p>Alive4ever: /* Parsing .Xresources */ Non compliant lightdm behavior, which loads ~/.Xdefaults instead of ~/.Xresources</p>
<hr />
<div>[[Category:Dotfiles]]<br />
[[Category:X server]]<br />
[[de:Xdefaults]]<br />
[[ja:X resources]]<br />
[[ru:X resources]]<br />
'''Xresources''' is a user-level configuration ''dotfile'', typically located at {{ic|~/.Xresources}}. It can be used to set [[Wikipedia:X resources|X resources]], which are configuration parameters for X client applications.<br />
<br />
They can do many operations, including:<br />
<br />
* defining terminal colours<br />
* configuring terminal preferences<br />
* setting DPI, antialiasing, hinting and other X font settings<br />
* changing the Xcursor theme<br />
* theming xscreensaver<br />
* altering preferences on low-level X applications (xclock ({{Pkg|xorg-xclock}}), {{Pkg|xpdf}}, {{Pkg|rxvt-unicode}}, etc.)<br />
<br />
{{Note|Using {{ic|~/.Xdefaults}} is deprecated, so this article will only refer to resources loaded with xrdb}}<br />
<br />
== Usage ==<br />
Make sure that {{pkg|xorg-xrdb}} is installed in your system.<br />
<br />
===Parsing .Xresources===<br />
The file {{ic|~/.Xresources}} does not exist by default. It is a plain-text file, so you can create it with any text editor. Once present it will be parsed automatically, by one of:<br />
* Most [[Display manager]]s will load the {{ic|~/.Xresources}} file on login. Some exception is [[lightdm]], which loads {{ic|~/.Xdefaults}} instead of {{ic|~/.Xresources}}.<br />
* If using {{ic|startx}} you may need to edit {{ic|.xinitrc}}, see below for details. <br />
The resources will be stored in the X server, so the file does not need to be read every time an app is started. The file can be reread to make any changes take effect.<br />
<br />
To reread the {{ic|.Xresources}} file and throw away the old resources:<br />
<br />
xrdb ~/.Xresources<br />
<br />
To reread the {{ic|.Xresources}} file and keep the old resources:<br />
<br />
xrdb -merge ~/.Xresources<br />
<br />
{{Tip|{{ic|~/.Xresources}} is just a naming convention; {{ic|xrdb}} can load any file. If you use {{ic|xrdb}} manually, you can put such a file anywhere you want (for example, {{ic|~/.config/Xresources}}).}}<br />
{{Note|Resources loaded with {{ic|xrdb}} are also accessible to ''remote'' X11 clients (such as those forwarded over SSH).}}<br />
{{Warning|The older and deprecated {{ic|~/.Xdefaults}} file is read every time you start an X11 program such as {{ic|xterm}}, but '''only''' if {{ic|xrdb}} has not '''ever''' been used in the current X session. [https://groups.google.com/forum/#!msg/comp.windows.x/hQBEdql8l-Q/hF3DETcIHGwJ]<br />
}}<br />
<br />
===Adding to xinitrc===<br />
If you are using a copy of the default [[xinitrc]] as your {{ic|.xinitrc}} it already merges {{ic|~/.Xresources}}.<br />
<br />
If you are using a custom {{ic|.xinitrc}} add the following line:<br />
<nowiki>[[ -f ~/.Xresources ]] && xrdb -merge -I$HOME ~/.Xresources</nowiki><br />
<br />
{{Warning|Never background the xrdb command within {{ic|~/.xinitrc}}. Otherwise, programs launched after xrdb may look for resources before it has finished loading them.}}<br />
<br />
===Default settings===<br />
To see the default settings for your installed X11 apps, look in {{ic|/usr/share/X11/app-defaults/}}.<br />
<br />
Detailed information on program-specific resources is usually provided in the man page for the program. xterm's man page is a good example, as it contains a list of X resources and their default values.<br />
<br />
To see the current loaded resources:<br />
xrdb -query -all<br />
<br />
===Xresources syntax===<br />
====Basic syntax====<br />
The syntax of an Xresources file is as follows:<br />
'''name.Class.resource: value'''<br />
and here is a real world example:<br />
xscreensaver.Dialog.headingFont: -*-fixed-bold-r-*-*-*-100-*-*-*-*-iso8859-1<br />
<br />
;name<br />
:The name of the application, such as xterm, xpdf, etc<br />
<br />
;class<br />
:The classification used to group resources together. Class names are typically uppercase.<br />
<br />
;resource<br />
:The name of the resource whose value is to be changed. Resources are typically lowercase with uppercase concatenation.<br />
<br />
;value<br />
:The actual value of the resource. This can be 1 of 3 types:<br />
:* Integer (whole numbers)<br />
:* Boolean (true/false, yes/no, on/off)<br />
:* String (a string of characters) (for example a word ({{ic|white}}), a color ({{ic|#ffffff}}), or a path ({{ic|/usr/bin/firefox}}))<br />
<br />
;delimiters<br />
:A dot ({{ic|'''.'''}}) is used to signify each step down into the hierarchy — in the above example we start at name, then descend into Class, and finally into the resource itself. A colon ({{ic|''':'''}}) is used to separate the resource declaration from the actual value.<br />
<br />
====Wildcard matching====<br />
<br />
The asterisk can be used as a wildcard, making it easy to write a single rule that can be applied to many different applications or elements. <br />
<br />
Using the previous example, if you want to apply the same font to all programs (not just XScreenSaver) that contain the class name {{ic|Dialog}} which contains the resource name {{ic|headingFont}}, you would write:<br />
<br />
'''*'''Dialog.headingFont: -*-fixed-bold-r-*-*-*-100-*-*-*-*-iso8859-1<br />
<br />
If you want to apply this same rule to all programs that contain the resource {{ic|headingFont}}, regardless of its class, you would write:<br />
<br />
'''*'''headingFont: -*-fixed-bold-r-*-*-*-100-*-*-*-*-iso8859-1<br />
<br />
==== Commenting ====<br />
To add a comment to your Xresources file, simply prefix it with an exclamation mark ({{ic|!}}), for example:<br />
<br />
! The following rule will be ignored because it has been commented out<br />
!Xft.antialias: true<br />
<br />
==== Include files ====<br />
<br />
To use different files for each application, use {{ic|#include}} in the main file. For example:<br />
<br />
{{hc|~/.Xresources|<br />
#include ".Xresources.d/xterm"<br />
#include ".Xresources.d/rxvt-unicode"<br />
#include ".Xresources.d/fonts"<br />
#include ".Xresources.d/xscreensaver"<br />
}}<br />
<br />
If files fail to load, specify the directory to ''xrdb'' with the {{ic|-I}} parameter. For example:<br />
<br />
{{hc|~/.xinitrc|<br />
xrdb -I''$HOME'' ~/.Xresources<br />
}}<br />
<br />
==Sample usage==<br />
The following samples should provide a good understanding of how application settings can be modified using an Xresources file. See [https://gist.github.com/anonymous/fa98de9fd70b51611303] for more examples. Refer to the man page of the application in question otherwise.<br />
<br />
===Terminal colors===<br />
Most terminals, including [[xterm]] and [[urxvt]], support at least 16 basic colors. The colors 0-7 are the 'normal' colors. Colors 8-15 are their 'bright' counterparts, used for highlighting. <br />
<br />
{{bc|<br />
! Black + DarkGrey<br />
*color0: #000000<br />
*color8: #555753<br />
! DarkRed + Red<br />
*color1: #ff6565<br />
*color9: #ff8d8d<br />
! DarkGreen + Green<br />
*color2: #93d44f<br />
*color10: #c8e7a8<br />
! DarkYellow + Yellow<br />
*color3: #eab93d<br />
*color11: #ffc123<br />
! DarkBlue + Blue<br />
*color4: #204a87<br />
*color12: #3465a4<br />
! DarkMagenta + Magenta<br />
*color5: #ce5c00<br />
*color13: #f57900<br />
!DarkCyan + Cyan (both not tango)<br />
*color6: #89b6e2<br />
*color14: #46a4ff<br />
! LightGrey + White<br />
*color7: #cccccc<br />
*color15: #ffffff<br />
}}<br />
<br />
See [[man page#Colored man pages on xterm or rxvt-unicode]] for how to color bold and underlined text automatically xterm and rxvt.<br />
<br />
{{Warning|Color resources such as {{ic|foreground}} and {{ic|background}} can be read by other applications (such as [https://www.gnu.org/software/emacs/manual/html_node/emacs/Table-of-Resources.html emacs]). This can be avoided by specifiying the class name, for example {{ic|XTerm.foreground}}.}}<br />
<br />
=== Xcursor ===<br />
<br />
See [[Cursor themes#X resources]].<br />
<br />
=== Xft ===<br />
<br />
See [[Font configuration#Applications without fontconfig support]].<br />
<br />
=== Xterm ===<br />
<br />
See [[Xterm#Configuration]].<br />
<br />
=== rxvt-unicode ===<br />
<br />
See [[Rxvt-unicode#Configuration]].<br />
<br />
=== Xpdf ===<br />
<br />
See {{ic|'''Options'''}} in [http://linux.die.net/man/1/xpdf man xpdf].<br />
<br />
==Color scheme commands==<br />
Here are some fast bash commands you can run right in your shell.<br />
<br />
===Display all 256 colors===<br />
Prints all 256 colors across the screen, very quick.<br />
<nowiki>(x=`tput op` y=`printf %76s`;for i in {0..256};do o=00$i;echo -e ${o:${#o}-3:3} `tput setaf $i;tput setab $i`${y// /=}$x;done)</nowiki><br />
<br />
===Display tput escape codes===<br />
Replace {{ic|tput op}} with whatever tput you want to trace. {{ic|op}} is the default foreground and background color.<br />
{{hc<br />
|<nowiki>$ ( strace -s5000 -e write tput op 2>&2 2>&1 ) | tee -a /dev/stderr | grep -o '"[^"]*"'</nowiki><br />
|033[\033[1;34m"\33[39;49m"\033[00m<br />
}}<br />
<br />
===Enumerating colors supported by terminals===<br />
The following command will let you discover all the terminals you have terminfo support for, and the number of colors each terminal supports. The possible values are: 8, 15, 16, 52, 64, 88 and 256.<br />
{{hc<br />
|<nowiki>$ for T in `find /usr/share/terminfo -type f -printf '%f '`;do echo "$T `tput -T $T colors`";done|sort -nk2</nowiki><br />
|Eterm-88color 88<br />
rxvt-88color 88<br />
xterm+88color 88<br />
xterm-88color 88<br />
Eterm-256color 256<br />
gnome-256color 256<br />
konsole-256color 256<br />
putty-256color 256<br />
rxvt-256color 256<br />
screen-256color 256<br />
screen-256color-bce 256<br />
screen-256color-bce-s 256<br />
screen-256color-s 256<br />
xterm+256color 256<br />
xterm-256color 256<br />
}}<br />
<br />
===Enumerating terminal capabilities===<br />
This command is useful to see what features that are supported by your terminal.<br />
{{hc<br />
|<nowiki>$ infocmp -1 | sed -nu 's/^[ \000\t]*//;s/[ \000\t]*$//;/[^ \t\000]\{1,\}/!d;/acsc/d;s/=.*,//p'|column -c80</nowiki><br />
|bel cuu ich kb2 kf15 kf3 kf44 kf59 mc0 rmso smul<br />
blink cuu1 il kbs kf16 kf30 kf45 kf6 mc4 rmul tbc<br />
bold cvvis il1 kcbt kf17 kf31 kf46 kf60 mc5 rs1 u6<br />
cbt dch ind kcub1 kf18 kf32 kf47 kf61 meml rs2 u7<br />
civis dch1 indn kcud1 kf19 kf33 kf48 kf62 memu sc u8<br />
clear dl initc kcuf1 kf2 kf34 kf49 kf63 op setab u9<br />
cnorm dl1 invis kcuu1 kf20 kf35 kf5 kf7 rc setaf vpa<br />
}}<br />
<br />
==Color scheme scripts==<br />
Any of the following scripts will display a chart of your current terminal color scheme. Handy for testing and whatnot.<br />
<br />
=== LUA ===<br />
<br />
{{bc|1=<br />
#!/usr/bin/env lua<br />
<br />
function cl(e)<br />
return string.format('\27[%sm', e)<br />
end<br />
<br />
function print_fg(bg, pre)<br />
for fg = 30,37 do<br />
fg = pre..fg<br />
io.write(cl(bg), cl(fg), string.format(' %6s ', fg), cl(0))<br />
end<br />
end<br />
<br />
for bg = 40,47 do<br />
io.write(cl(0), ' ', bg, ' ')<br />
print_fg(bg, ' ')<br />
io.write('\n ')<br />
print_fg(bg, '1;')<br />
io.write('\n\n')<br />
end<br />
<br />
-- Andres P<br />
}}<br />
<br />
=== Bash ===<br />
<br />
{{bc|1=<br />
#!/usr/bin/bash<br />
#<br />
# ANSI color scheme script featuring Space Invaders<br />
#<br />
# Original: http://crunchbang.org/forums/viewtopic.php?pid=126921%23p126921#p126921<br />
# Modified by lolilolicon<br />
#<br />
<br />
f=3 b=4<br />
for j in f b; do<br />
for i in {0..7}; do<br />
printf -v $j$i %b "\e[${!j}${i}m"<br />
done<br />
done<br />
bld=$'\e[1m'<br />
rst=$'\e[0m'<br />
<br />
cat << EOF<br />
<br />
$f1 ▀▄ ▄▀ $f2 ▄▄▄████▄▄▄ $f3 ▄██▄ $f4 ▀▄ ▄▀ $f5 ▄▄▄████▄▄▄ $f6 ▄██▄ $rst<br />
$f1 ▄█▀███▀█▄ $f2███▀▀██▀▀███ $f3▄█▀██▀█▄ $f4 ▄█▀███▀█▄ $f5███▀▀██▀▀███ $f6▄█▀██▀█▄$rst<br />
$f1█▀███████▀█ $f2▀▀███▀▀███▀▀ $f3▀█▀██▀█▀ $f4█▀███████▀█ $f5▀▀███▀▀███▀▀ $f6▀█▀██▀█▀$rst<br />
$f1▀ ▀▄▄ ▄▄▀ ▀ $f2 ▀█▄ ▀▀ ▄█▀ $f3▀▄ ▄▀ $f4▀ ▀▄▄ ▄▄▀ ▀ $f5 ▀█▄ ▀▀ ▄█▀ $f6▀▄ ▄▀$rst<br />
<br />
$bld$f1▄ ▀▄ ▄▀ ▄ $f2 ▄▄▄████▄▄▄ $f3 ▄██▄ $f4▄ ▀▄ ▄▀ ▄ $f5 ▄▄▄████▄▄▄ $f6 ▄██▄ $rst<br />
$bld$f1█▄█▀███▀█▄█ $f2███▀▀██▀▀███ $f3▄█▀██▀█▄ $f4█▄█▀███▀█▄█ $f5███▀▀██▀▀███ $f6▄█▀██▀█▄$rst<br />
$bld$f1▀█████████▀ $f2▀▀▀██▀▀██▀▀▀ $f3▀▀█▀▀█▀▀ $f4▀█████████▀ $f5▀▀▀██▀▀██▀▀▀ $f6▀▀█▀▀█▀▀$rst<br />
$bld$f1 ▄▀ ▀▄ $f2▄▄▀▀ ▀▀ ▀▀▄▄ $f3▄▀▄▀▀▄▀▄ $f4 ▄▀ ▀▄ $f5▄▄▀▀ ▀▀ ▀▀▄▄ $f6▄▀▄▀▀▄▀▄$rst<br />
<br />
<br />
$f7▌$rst<br />
<br />
$f7▌$rst<br />
<br />
$f7 ▄█▄ $rst<br />
$f7▄█████████▄$rst<br />
$f7▀▀▀▀▀▀▀▀▀▀▀$rst<br />
<br />
EOF<br />
}}<br />
<br />
=== Ruby ===<br />
<br />
{{bc|1= <br />
#!/usr/bin/env ruby<br />
# coding: utf-8<br />
<br />
# ANSI color scheme script <br />
# Author: Ivaylo Kuzev < Ivo ><br />
# Original: http://crunchbang.org/forums/viewtopic.php?pid=134749%23p134749#p134749<br />
# Modified using Ruby.<br />
<br />
CL = "\e[0m"<br />
BO = "\e[1m"<br />
<br />
R = "\e[31m" <br />
G = "\e[32m"<br />
Y = "\e[33m"<br />
B = "\e[34m"<br />
P = "\e[35m"<br />
C = "\e[36m"<br />
<br />
print <<EOF <br />
<br />
#{BO}#{R} ██████ #{CL} #{BO}#{G}██████ #{CL}#{BO}#{Y} ██████#{CL} #{BO}#{B}██████ #{CL} #{BO}#{P} ██████#{CL} #{BO}#{C} ███████#{CL}<br />
#{BO}#{R} ████████#{CL} #{BO}#{G}██ ██ #{CL}#{BO}#{Y}██ #{CL} #{BO}#{B}██ ██#{CL} #{BO}#{P}██████ #{CL} #{BO}#{C} █████████#{CL}<br />
#{R} ██ ████#{CL} #{G}██ ████#{CL}#{Y} ████ #{CL} #{B}████ ██#{CL} #{P}████ #{CL} #{C}█████ #{CL}<br />
#{R} ██ ██#{CL} #{G}██████ #{CL}#{Y} ████████#{CL} #{B}██████ #{CL} #{P}████████#{CL} #{C}██ #{CL}<br />
<br />
EOF<br />
}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Parsing errors ===<br />
<br />
[[Display manager]]s such as [[GDM]] and [[LightDM]] may use the {{ic|--nocpp}} argument for ''xrdb''. See [[LightDM#Xresources not being parsed correctly]].<br />
<br />
==See also==<br />
<br />
* [https://engineering.purdue.edu/ECN/Support/KB/Docs/UsingTheXdefaultsFil Using the Xdefaults File] - An in-depth article on how X interprets the Xdefaults file<br />
* [http://wiki.afterstep.org/index.php?title=Rxvt-Unicode_Configuration_Tutorial Rxvt-unicode Configuration Tutorial] - lots of information for urxvt users<br />
* [http://mkaz.com/solog/system/xterm-colors.html Example Colors and their names] - listing of example colors and their color names for xterm and other X-applications.<br />
* [https://web.archive.org/web/20090130061234/http://phraktured.net/terminal-colors/ Color Themes] - Extensive list of terminal color themes by Phraktured.<br />
* [http://xcolors.net/ Xcolors.net] List of user-contributed terminal color themes.<br />
* [http://beta.andrewrcraig.us/index.php?page=xcolors Xcolors by dkeg]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=LightDM&diff=442568LightDM2016-07-23T16:59:36Z<p>Alive4ever: /* Xresources not being parsed correctly */ lightdm parses ~/.Xdefaults instead of ~/.Xresources</p>
<hr />
<div>[[Category:Display managers]]<br />
[[es:LightDM]]<br />
[[fr:LightDM]]<br />
[[ja:LightDM]]<br />
[[ru:LightDM]]<br />
[[zh-CN:LightDM]]<br />
{{Related articles start}}<br />
{{Related|Display manager}}<br />
{{Related|GDM}}<br />
{{Related|KDM}}<br />
{{Related|LXDM}}<br />
{{Related articles end}}<br />
<br />
[http://www.freedesktop.org/wiki/Software/LightDM LightDM] is a cross-desktop [[display manager]]. Its key features are:<br />
* Cross-desktop - supports different desktop technologies.<br />
* Supports different display technologies (X, Wayland, Mir, ...).<br />
* Lightweight - low memory usage and high performance.<br />
* Supports guest sessions.<br />
* Supports remote login (incoming - XDMCP, VNC, outgoing - XDMCP, pluggable).<br />
* Comprehensive test suite.<br />
* Low code complexity.<br />
<br />
More details about LightDM's design can be found [http://www.freedesktop.org/wiki/Software/LightDM/Design here].<br />
<br />
== Installation ==<br />
<br />
[[Install]] {{Pkg|lightdm}}. Note that stable releases are even-numbered (1.8, 1.10) while development releases are odd-numbered (1.9, 1.11). These development releases are available with {{AUR|lightdm-devel}}. Also available is {{AUR|lightdm-bzr}}.<br />
<br />
=== Greeter===<br />
<br />
You will probably want to install a greeter. A greeter is a GUI that prompts the user for credentials, lets the user select a session, and so on. It's possible to use LightDM without a greeter, but only if an automatic login is configured. The reference greeter is {{Pkg|lightdm-gtk-greeter}}. LightDM attempts to use this greeter when started unless configured to do otherwise.<br />
<br />
The official repositories contain the following alternative greeters.<br />
* {{Pkg|lightdm-kde-greeter}}: A greeter used with KDE4.<br />
* lightdm-deepin-greeter ({{Pkg|deepin-session-ui}}): A greeter from the [[Deepin Desktop Environment|Deepin]] project.<br />
<br />
Other alternative greeters are available in the [[AUR]].<br />
* {{AUR|lightdm-webkit2-greeter}}: A greeter that uses Webkit2 for theming. It supersedes {{AUR|lightdm-webkit-greeter}}.<br />
* {{AUR|lightdm-unity-greeter}}: The greeter used by Ubuntu's [[Unity]].<br />
* {{AUR|lightdm-pantheon-greeter}}: A greeter from the elementary OS project.<br />
<br />
You can set the default greeter by changing the {{ic|[Seat:*]}} section of the LightDM configuration file, like so:<br />
<br />
{{hc|/etc/lightdm/lightdm.conf|2=<br />
[Seat:*]<br />
...<br />
greeter-session=lightdm-yourgreeter-greeter<br />
}}<br />
<br />
Which greeters are available? What values may be assigned to the {{ic|greeter-session}} option? Each {{ic|.desktop}} file in the {{ic|/usr/share/xgreeters}} directory denotes an available greeter. In this example, the {{ic|lightdm-gtk-greeter}} and {{ic|lightdm-kde-greeter}} greeters are available:<br />
$ ls -1 /usr/share/xgreeters/<br />
lightdm-gtk-greeter.desktop<br />
lightdm-kde-greeter.desktop<br />
<br />
== Enabling LightDM ==<br />
<br />
Make sure to [[enable]] {{ic|lightdm.service}} so LightDM will be started at boot, see also [[Display manager#Loading the display manager]].<br />
<br />
== Command line tool ==<br />
<br />
LightDM offers a command line tool, {{ic|dm-tool}}, which can be used to lock the current seat, switch sessions, etc, which is useful with 'minimalist' window managers and for testing. To see a list of available commands, execute:<br />
$ dm-tool --help<br />
<br />
== Testing ==<br />
<br />
First, [[install]] {{Pkg|xorg-server-xephyr}} from the [[official repositories]].<br />
<br />
Then, run LightDM as an X application:<br />
$ lightdm --test-mode --debug<br />
<br />
== Optional configuration and tweaks ==<br />
<br />
LightDM can be configured by modifying its config file, {{ic|/etc/lightdm/lightdm.conf}}.<br />
<br />
Some greeters have their own configuration files. For example:<br />
<br />
{{Pkg|lightdm-gtk-greeter}}: {{ic|/etc/lightdm/lightdm-gtk-greeter.conf}}<br />
<br />
{{AUR|lightdm-webkit2-greeter}}: {{ic|/etc/lightdm/lightdm-webkit2-greeter.conf}}<br />
<br />
{{Pkg|lightdm-kde-greeter}}: {{ic|/etc/lightdm/lightdm-kde-greeter.conf}}<br />
<br />
=== Changing background images/colors ===<br />
<br />
You can set the background to a hex color or an image. Some greeters offer more robust background options like background selection from the login screen, random backgrounds, etc.<br />
<br />
==== GTK+ greeter ====<br />
<br />
You can use the {{Pkg|lightdm-gtk-greeter-settings}} gui.<br />
<br />
Users wishing to customize the wallpaper on the greeter screen need to edit {{ic|/etc/lightdm/lightdm-gtk-greeter.conf}} and define the {{ic|background}} variable under the {{ic|[greeter]}} section. For example:<br />
{{hc|/etc/lightdm/lightdm-gtk-greeter.conf|2=<br />
[greeter]<br />
background=/usr/share/pixmaps/black_and_white_photography-wallpaper-1920x1080.jpg<br />
}}<br />
<br />
{{Note|It is recommended to place the PNG or JPG file in {{ic|/usr/share/pixmaps}} since the LightDM user needs read access to the wallpaper file.}}<br />
<br />
==== Webkit2 greeter ====<br />
<br />
The {{AUR|lightdm-webkit2-greeter}} allows you to choose a background image directly on the login screen. It also offers an option to display a random image each time it starts. By default, images are sourced from {{ic|/usr/share/backgrounds}}. You can change the background images directory by editing {{ic|lightdm-webkit2-greeter.conf}}. For example:<br />
{{hc|/etc/lightdm/lightdm-webkit2-greeter.conf|2=<br />
[branding]<br />
background_images = /usr/share/backgrounds<br />
}}<br />
<br />
{{Note|The background images directory must be accessible to the LightDM user so it should not be located anywhere under {{ic|/home}}. }}<br />
<br />
==== Unity greeter ====<br />
<br />
Users using the {{AUR|lightdm-unity-greeter}} must edit the {{ic|/usr/share/glib-2.0/schemas/com.canonical.unity-greeter.gschema.xml}} file and then execute:<br />
# glib-compile-schemas /usr/share/glib-2.0/schemas/<br />
<br />
According to [https://bbs.archlinux.org/viewtopic.php?id=149945 this] page.<br />
<br />
==== KDE greeter ====<br />
<br />
Go to ''System Settings > Login Screen (LightDM)'' and change the background image for your theme.<br />
<br />
Alternatively, you can edit the {{ic|Background}} variable in {{ic|lightdm-kde-greeter.conf}} :<br />
<br />
{{hc|/etc/lightdm/lightdm-kde-greeter.conf|2=<br />
[greeter]<br />
theme-name=classic<br />
<br />
[greeter-settings]<br />
Background=/usr/share/archlinux/wallpaper/archlinux-underground.jpg<br />
BackgroundKeepAspectRatio=true<br />
GreetMessage=Welcome to %hostname%<br />
}}<br />
<br />
=== Changing your avatar ===<br />
<br />
{{Tip|If you are using KDE, you can change your avatar in KDE System Settings.}}<br />
<br />
First, make sure the {{pkg|accountsservice}} package from the [[official repositories]] is installed, then set it up as follows, replacing {{ic|''username''}} with the desired user's login name. The ''.png'' file extension should not be included in the filename.<br />
<br />
* Edit or create the file {{ic|/var/lib/AccountsService/users/''username''}}, and add the lines<br />
<br />
[User]<br />
Icon=/var/lib/AccountsService/icons/''username''<br />
<br />
* Create the file {{ic|/var/lib/AccountsService/icons/''username''}} using a 96x96 PNG image file.<br />
<br />
{{Note|Make sure that both created files have 644 permissions, use [[chmod]] to correct them.}}<br />
<br />
=== Sources of Arch-centric 64x64 icons ===<br />
<br />
The {{AUR|archlinux-artwork}} package from the [[AUR]] contains some nice examples that install to {{ic|/usr/share/archlinux/icons}} and that can be copied to {{ic|/usr/share/icons/hicolor/64x64/devices}} as follows:<br />
<br />
# find /usr/share/archlinux/icons -name "*64*" -exec cp {} /usr/share/icons/hicolor/64x64/devices \;<br />
<br />
After copying, the {{AUR|archlinux-artwork}} package can be removed.<br />
<br />
=== Enabling autologin ===<br />
<br />
Edit the LightDM configuration file and ensure these lines are uncommented and correctly configured:<br />
<br />
{{hc|/etc/lightdm/lightdm.conf|2=<br />
[Seat:*]<br />
pam-service=lightdm<br />
pam-autologin-service=lightdm-autologin<br />
autologin-user=''username''<br />
autologin-user-timeout=0<br />
session-wrapper=/etc/lightdm/Xsession<br />
}}<br />
<br />
LightDM goes through [[PAM]] even when {{ic|autologin}} is enabled. You must be part of the {{ic|autologin}} group to be able to login automatically without entering your password:<br />
<br />
# groupadd -r autologin<br />
# gpasswd -a ''username'' autologin<br />
<br />
{{Note|GNOME users, and by extension any gnome-keyring user will have to set up a blank password to their keyring for it to be unlocked automatically.}}<br />
<br />
=== Enabling interactive passwordless login ===<br />
<br />
LightDM goes through PAM so you must configure the lightdm configuration of PAM:<br />
<br />
{{hc|/etc/pam.d/lightdm|2=<br />
#%PAM-1.0<br />
'''auth sufficient pam_succeed_if.so user ingroup nopasswdlogin'''<br />
auth include system-login<br />
...<br />
}}<br />
<br />
You must then also be part of the {{ic|nopasswdlogin}} group to be able to login interactively without entering your password:<br />
<br />
# groupadd -r nopasswdlogin<br />
# gpasswd -a ''username'' nopasswdlogin<br />
<br />
{{Note|GNOME users, and by extension any gnome-keyring user may have to follow the instructions at the end of the previous section on enabling autologin.}}<br />
<br />
To create a new user account that logs in automatically and additionally able to login again without a password the user can be created with supplementary membership of both groups, e.g.:<br />
<br />
# useradd -mG autologin,nopasswdlogin -s /bin/bash ''username''<br />
<br />
=== Hiding system and services users ===<br />
To prevent system users from showing-up in the login, install the optional dependency {{Pkg|accountsservice}}, or add the user names to {{ic|/etc/lightdm/users.conf}} under {{ic|hidden-users}}. The first option has the advantage of not needing to update the list when more users are added or removed.<br />
<br />
=== Migrating from SLiM ===<br />
<br />
Move the contents of [[xinitrc]] to [[xprofile]], removing the call to start the [[window manager]] or [[desktop environment]].<br />
<br />
=== NumLock on by default ===<br />
<br />
Install the {{Pkg|numlockx}} package and then edit {{ic|/etc/lightdm/lightdm.conf}}:<br />
{{hc|/etc/lightdm/lightdm.conf|2=<br />
[Seat:*]<br />
greeter-setup-script=/usr/bin/numlockx on<br />
}}<br />
<br />
=== User switching under Xfce4 ===<br />
<br />
If you use the [[Xfce]] desktop, the Switch User functionality of the Action Button found in your Application Launcher specifically looks for the ''gdmflexiserver'' executable in order to enable itself. If you provide it with an executable shell script {{ic|/usr/bin/gdmflexiserver}} consisting of<br />
<br />
#!/bin/sh<br />
/usr/bin/dm-tool switch-to-greeter<br />
<br />
then user switching in Xfce should work with Lightdm.<br />
<br />
Alternatively, if you use the Whisker Menu, you can go to Properties -> Commands and change the "Switch Users" command directly to:<br />
<br />
dm-tool switch-to-greeter<br />
<br />
You can also switch users from the [[XScreenSaver]] lock screen - see [[XScreenSaver#LightDM]].<br />
<br />
=== Default session === <br />
<br />
Lightdm, like other DMs, stores the last-selected xsession in {{ic|~/.dmrc}}. See [[Display manager#Session list]] for more info.<br />
<br />
=== Adjusting the login window's position ===<br />
<br />
==== GTK+ greeter ====<br />
<br />
Users need to edit {{ic|/etc/lightdm/lightdm-gtk-greeter.conf}} and enter a value for the {{ic|position}} variable. It accepts {{ic|x}} and {{ic|y}} values, either absolute (in pixels) or relative (in percent). Each value can also have an additional anchor location for the window, {{ic|start}}, {{ic|center}} and {{ic|end}} separated from the value by a comma.<br />
<br />
Example:<br />
<br />
position=200,start 50%,center<br />
<br />
== Troubleshooting ==<br />
If you encounter consistent screen flashing and ultimately no LightDM on boot, ensure that you have defined the greeter correctly in LightDM's config file. And if you have correctly defined the GTK greeter, make sure the {{ic|xsessions-directory}} (default: {{ic|/usr/share/xsessions}}) exists and contains at least one .desktop file.<br />
<br />
The same error can happen on lightdm startup if the last used session is not available anymore (eg. you last used gnome and then removed the gnome-session package): the easiest workaround is to temporarily restore the removed package. Another solution might be:<br />
<br />
# dbus-send --system --type=method_call --print-reply --dest=org.freedesktop.Accounts /org/freedesktop/Accounts/User1000 org.freedesktop.Accounts.User.SetXSession string:xfce<br />
<br />
This example sets the session "xfce" as default for the user 1000.<br />
<br />
=== Wrong locale displayed ===<br />
<br />
In case of your locale not being displayed correctly in Lightdm add your locale to {{ic|/etc/environment}}<br />
LANG=pt_PT.utf8<br />
<br />
=== Xresources not being parsed correctly ===<br />
<br />
LightDM has an [https://bugs.launchpad.net/lightdm/+bug/1084885 upstream bug] where your [[Xresources]] file will not be loaded with a pre-processor. In practical terms, this means that variables set with {{ic|#define}} are not expanded when called later. You may see this reflected as an all-pink screen if using a custom color set with urxvt. To fix it, edit {{ic|/etc/lightdm/Xsession}} and search for the line:<br />
xrdb -nocpp -merge "$file"<br />
Change it to read:<br />
xrdb -merge "$file"<br />
Your Xresources will now be pre-processed so that variables are correctly expanded.<br />
<br />
{{Note| {{ic|lightdm}} parses {{ic|~/.Xdefaults}} file instead of {{ic|~/.Xresources}}. Linking {{ic|~/.Xdefaults}} to {{ic|~/.Xresources}} is a workaround to make {{ic|lightdm}} loads the resource file properly. }}<br />
<br />
=== Missing icons with GTK greeter ===<br />
<br />
If you're using {{Pkg|lightdm-gtk-greeter}} as a greeter and it shows placeholder images as icons, make sure valid icon themes and themes are installed and configured. Check the following file:<br />
<br />
{{hc|/etc/lightdm/lightdm-gtk-greeter.conf|2=<br />
[greeter]<br />
theme-name=mate # this should be the name of a directory under /usr/share/themes/<br />
icon-theme-name=mate # this should be the name of a fully featured icons set directory under /usr/share/icons/<br />
}}<br />
<br />
=== LightDM freezes on login attempt ===<br />
<br />
You may find that after entering the correct username and password and attempting to log in, LightDM freezes and you are unable to continue to the desktop. To fix the issue, reinstall the {{Pkg|gdk-pixbuf2}} package. See [https://bbs.archlinux.org/viewtopic.php?id=179031 this forum thread].<br />
<br />
=== LightDM displaying in wrong monitor ===<br />
<br />
If you are using multiple monitors, LightDM may display in the wrong one (e.g. if your primary monitor is on the right). To force the LightDM login screen to display on a specific monitor, edit {{ic|/etc/lightdm/lightdm.conf}} and change the ''display-setup-script'' parameter like this:<br />
{{hc|/etc/lightdm/lightdm.conf|2=<br />
display-setup-script=xrandr --output ''HDMI1'' --primary<br />
}}<br />
<br />
Replace ''HDMI1'' with your real monitor ID, which you can find from '''xrandr''' command output.<br />
<br />
=== LightDM doesn't appear ===<br />
<br />
It may happen that your system boots so fast that LightDM service is started before your graphics drivers are properly loaded. If this is your case, you'll want to add the following config to your lightdm.conf file:<br />
<br />
[LightDM]<br />
logind-check-graphical=true<br />
<br />
This setting will tell LightDM to wait until graphics devices are ready before spawning greeters/autostarting sessions on them.<br />
<br />
=== Pulseaudio not starting automatically ===<br />
<br />
See [[PulseAudio#Running]].<br />
<br />
== See also ==<br />
<br />
* {{Pkg|light-locker}}, a screen locker using LightDM.<br />
* [https://wiki.ubuntu.com/LightDM Ubuntu Wiki article]<br />
* [http://wiki.gentoo.org/wiki/LightDM Gentoo Wiki article]<br />
* [https://launchpad.net/lightdm Launchpad Page]<br />
* [http://www.mattfischer.com/blog/?tag=lightdm LightDM blog]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=Unified_Extensible_Firmware_Interface&diff=442528Unified Extensible Firmware Interface2016-07-23T13:37:57Z<p>Alive4ever: /* OVMF for Virtual Machines */ qemu has -bios parameter to load custom bios, such as TianoCore's OVMF</p>
<hr />
<div>[[Category:Boot process]]<br />
[[es:Unified Extensible Firmware Interface]]<br />
[[it:Unified Extensible Firmware Interface]]<br />
[[ja:Unified Extensible Firmware Interface]]<br />
[[ru:Unified Extensible Firmware Interface]]<br />
[[zh-CN:Unified Extensible Firmware Interface]]<br />
{{Related articles start}}<br />
{{Related|Arch boot process}}<br />
{{Related|Master Boot Record}}<br />
{{Related|EFI System Partition}}<br />
{{Related|GUID Partition Table}}<br />
{{Related|Secure Boot}}<br />
{{Related|UEFI/Hardware}}<br />
{{Related articles end}}<br />
{{Warning|While the choice to install in UEFI mode is forward looking, early vendor UEFI implementations may carry more bugs than their BIOS counterparts. It is advised to do a search relating to your particular mainboard model before proceeding.}}<br />
<br />
The [http://www.uefi.org/ Unified Extensible Firmware Interface] (EFI or UEFI for short) is a new model for the interface between operating systems and firmware. It provides a standard environment for booting an operating system and running pre-boot applications. <br />
<br />
It is distinct from the commonly used "[[MBR]] boot code" method followed for [[Wikipedia:BIOS|BIOS]] systems. See [[Arch boot process]] for their differences and the boot process using UEFI. To set up UEFI Boot Loaders, see [[Boot loaders]].<br />
<br />
== UEFI versions ==<br />
* UEFI started as Intel's EFI in versions 1.x. <br />
* Later, a group of companies called the UEFI Forum took over its development, which renamed it as Unified EFI starting with version 2.0. <br />
* Unless specified as EFI 1.x, EFI and UEFI terms are used interchangeably to denote UEFI 2.x firmware. <br />
* As of 15 April 2015, UEFI Specification 2.5 is the most recent version. <br />
* Apple's EFI implementation is neither a EFI 1.x version nor UEFI 2.x version but mixes up both. This kind of firmware does not fall under any one (U)EFI specification and therefore is not a standard UEFI firmware. Unless stated explicitly, these instructions are general and some of them may not work or may be different in [[MacBook|Apple Macs]].<br />
<br />
== UEFI Firmware bitness ==<br />
<br />
Under UEFI, every program whether it is an OS loader or a utility (e.g. a memory testing app or recovery tool), should be a UEFI Application corresponding to the EFI firmware bitness/architecture. <br />
<br />
The vast majority of UEFI firmwares, including recent Apple Macs, use x86_64 EFI firmware. The only known devices that use IA32 (32-bit) EFI are older (pre 2008) Apple Macs, some Intel Cloverfield ultrabooks and some older Intel Server boards that are known to operate on Intel EFI 1.10 firmware.<br />
<br />
An x86_64 EFI firmware does not include support for launching 32-bit EFI apps (unlike x86_64 Linux and Windows versions which include such support). Therefore the UEFI application must be compiled for that specific firmware processor bitness/architecture.<br />
<br />
=== Non Macs ===<br />
<br />
Check whether the dir {{ic|/sys/firmware/efi}} exists, if it exists it means the kernel has booted in EFI mode. In that case the UEFI bitness is same as kernel bitness. (ie. i686 or x86_64)<br />
<br />
{{Note|Intel Atom System-on-Chip systems ship with 32-bit UEFI (as on 2 November 2013). See [[#Using GRUB]] for more info.}}<br />
<br />
=== Apple Macs ===<br />
<br />
Pre-2008 Macs mostly have i386-efi firmware while >=2008 Macs have mostly x86_64-efi. All Macs capable of running Mac OS X Snow Leopard 64-bit Kernel have x86_64 EFI 1.x firmware. <br />
<br />
To find out the arch of the efi firmware in a Mac, type the following into the Mac OS X terminal:<br />
<br />
$ ioreg -l -p IODeviceTree | grep firmware-abi<br />
<br />
If the command returns EFI32 then it is IA32 (32-bit) EFI firmware. If it returns EFI64 then it is x86_64 EFI firmware. Most of the Macs do not have UEFI 2.x firmware as Apple's EFI implementation is not fully compliant with UEFI 2.x Specification.<br />
<br />
== Linux Kernel Config options for UEFI ==<br />
<br />
The required Linux Kernel configuration options for UEFI systems are :<br />
<br />
CONFIG_RELOCATABLE=y<br />
CONFIG_EFI=y<br />
CONFIG_EFI_STUB=y<br />
CONFIG_FB_EFI=y<br />
CONFIG_FRAMEBUFFER_CONSOLE=y<br />
<br />
UEFI Runtime Variables Support ('''efivarfs''' filesystem - {{ic|/sys/firmware/efi/efivars}}). This option is important as this is required to manipulate UEFI Runtime Variables using tools like {{ic|/usr/bin/efibootmgr}}. The below config option has been added in kernel 3.10 and above.<br />
<br />
CONFIG_EFIVAR_FS=y<br />
<br />
UEFI Runtime Variables Support (old '''efivars sysfs''' interface - {{ic|/sys/firmware/efi/vars}}). This option should be disabled to prevent any potential issues with both efivarfs and sysfs-efivars enabled.<br />
<br />
CONFIG_EFI_VARS=n<br />
<br />
GUID Partition Table [[GPT]] config option - mandatory for UEFI support<br />
<br />
CONFIG_EFI_PARTITION=y<br />
<br />
{{Note|All of the above options are required to boot Linux via UEFI, and are enabled in Archlinux kernels in official repos.}}<br />
<br />
Retrieved from https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/x86/x86_64/uefi.txt .<br />
<br />
== UEFI Variables ==<br />
<br />
UEFI defines variables through which an operating system can interact with the firmware. UEFI Boot Variables are used by the boot-loader and used by the OS only for early system start-up. UEFI Runtime Variables allow an OS to manage certain settings of the firmware like the UEFI Boot Manager or managing the keys for UEFI Secure Boot Protocol etc. You can get the list using <br />
$ efivar -l<br />
<br />
=== UEFI Variables Support in Linux Kernel ===<br />
<br />
Linux kernel exposes EFI variables data to userspace via '''efivarfs''' ('''EFI''' '''VAR'''iable '''F'''ile'''S'''ystem) interface ({{ic|CONFIG_EFIVAR_FS}}) - mounted using {{ic|efivarfs}} kernel module at {{ic|/sys/firmware/efi/efivars}} - it has no maximum per-variable size limitation and supports UEFI Secure Boot variables. Introduced in kernel 3.8.<br />
<br />
=== Requirements for UEFI variable support ===<br />
<br />
# EFI Runtime Services support should be present in the kernel ({{ic|1=CONFIG_EFI=y}}, check if present with {{ic|zgrep CONFIG_EFI /proc/config.gz}}).<br />
# Kernel processor [[#UEFI Firmware bitness|bitness]] and EFI processor bitness should match.<br />
# Kernel should be booted in EFI mode (via [[EFISTUB]] or any [[Boot loaders|EFI boot loader]], not via BIOS/CSM or Apple's "bootcamp" which is also BIOS/CSM).<br />
# EFI Runtime Services in the kernel SHOULD NOT be disabled via kernel cmdline, i.e. {{ic|noefi}} kernel parameter SHOULD NOT be used.<br />
# {{ic|efivarfs}} filesystem should be mounted at {{ic|/sys/firmware/efi/efivars}}, otherwise follow [[#Mount efivarfs]] section below.<br />
# {{ic|efivar}} should list (option {{ic|-l}}) the EFI Variables without any error.<br />
<br />
If EFI Variables support does not work even after the above conditions are satisfied, try the below workarounds:<br />
<br />
# If any userspace tool is unable to modify efi variables data, check for existence of {{ic|/sys/firmware/efi/efivars/dump-*}} files. If they exist, delete them, reboot and retry again.<br />
# If the above step does not fix the issue, try booting with {{ic|efi_no_storage_paranoia}} kernel parameter to disable kernel efi variable storage space check that may prevent writing/modification of efi variables.<br />
<br />
{{Note|{{ic|efi_no_storage_paranoia}} should only be used when needed and should not be left as a normal boot option. The effect of this kernel command line parameter turns off a safeguard that was put in place to help avoid the bricking of machines when the NVRAM gets too full.}}<br />
<br />
==== Mount efivarfs ====<br />
<br />
{{Warning|1=''efivars'' is mounted writeable by default [https://github.com/systemd/systemd/issues/2402], which may cause permanent damage to the system. [https://bbs.archlinux.org/viewtopic.php?id=207549] As such, consider mounting ''efivars'' read-only ({{ic|-o ro}}) as described below. Note that when it is mounted read-only, tools such as ''efibootmgr'' and bootloaders will not be able to change boot settings, nor will commands like {{ic|systemctl reboot --firmware-setup}} work.}}<br />
<br />
If {{ic|efivarfs}} is not automatically mounted at {{ic|/sys/firmware/efi/efivars}} by [[systemd]] during boot, then you need to manually mount it to expose UEFI variables to [[#Userspace tools]] like {{ic|efibootmgr}}:<br />
<br />
# mount -t efivarfs efivarfs /sys/firmware/efi/efivars<br />
<br />
{{Note|The above command should be run both '''outside''' ('''before''') and '''inside''' the [[chroot]], if any.}}<br />
<br />
To mount {{ic|efivarfs}} read-only during boot, add to {{ic|/etc/fstab}}:<br />
<br />
{{hc|/etc/fstab|2=<br />
efivarfs /sys/firmware/efi/efivars efivarfs '''ro''',nosuid,nodev,noexec,noatime 0 0<br />
}}<br />
<br />
To remount with write support, run:<br />
<br />
# mount -o remount /sys/firmware/efi/efivars -o '''rw''',nosuid,nodev,noexec,noatime<br />
<br />
=== Userspace tools ===<br />
<br />
There are few tools that can access/modify the UEFI variables, namely<br />
<br />
# '''efivar''' - Library and Tool to manipulate UEFI Variables (used by efibootmgr) - https://github.com/vathpela/efivar - {{Pkg|efivar}} or {{AUR|efivar-git}}<br />
# '''efibootmgr''' - Tool to manipulate UEFI Firmware Boot Manager Settings - https://github.com/vathpela/efibootmgr - {{Pkg|efibootmgr}} or {{AUR|efibootmgr-git}}<br />
# '''uefivars''' - Dumps list of EFI variables with some additional PCI related info (uses efibootmgr code internally) - https://github.com/fpmurphy/Various/tree/master/uefivars-2.0 supports only efivarfs and https://github.com/fpmurphy/Various/tree/master/uefivars-1.0 supports only sysfs-efivars . AUR package {{AUR|uefivars-git}} <br />
# '''efitools''' - Tools for manipulating UEFI secure boot platforms - {{Pkg|efitools}} or {{AUR|efitools-git}}<br />
# '''Ubuntu's Firmware Test Suite''' - https://wiki.ubuntu.com/FirmwareTestSuite/ - {{AUR|fwts}}{{Broken package link|{{aur-mirror|fwts}}}} (along with {{AUR|fwts-efi-runtime-dkms}}{{Broken package link|{{aur-mirror|fwts-efi-runtime-dkms}}}}) or {{AUR|fwts-git}}<br />
<br />
==== efibootmgr ====<br />
<br />
{{Note|<br />
* If {{ic|efibootmgr}} completely fails to work in your system, you can reboot into UEFI Shell v2 and use {{ic|bcfg}} command to create a boot entry for the bootloader.<br />
* If you are unable to use {{ic|efibootmgr}}, some UEFI firmwares allow users to directly manage uefi boot entries from within its boot-time interface. For example, some ASUS firmwares have an "Add New Boot Option" choice which enables you to select a local EFI System Partition and manually enter the EFI stub location. (for example {{ic|\EFI\refind\refind_x64.efi}}).<br />
* The below commands use {{Pkg|refind-efi}} boot-loader as example.<br />
}}<br />
<br />
Assuming the boot-loader file to be launched is {{ic|/boot/efi/EFI/refind/refind_x64.efi}}, {{ic|/boot/efi/EFI/refind/refind_x64.efi}} can be split up as {{ic|/boot/efi}} and {{ic|/EFI/refind/refind_x64.efi}}, wherein {{ic|/boot/efi}} is the mountpoint of the EFI System Partition, which is assumed to be {{ic|/dev/sdXY}} (here {{ic|X}} and {{ic|Y}} are just placeholders for the actual values - eg:- in {{ic|/dev/sda1}} , {{ic|1=X==a}} {{ic|1=Y==1}}).<br />
<br />
To determine the actual device path for the EFI System Partition (assuming mountpoint {{ic|/boot/efi}} for example) (should be in the form {{ic|/dev/sdXY}}), try :<br />
<br />
# findmnt /boot/efi<br />
TARGET SOURCE FSTYPE OPTIONS<br />
/boot/efi /dev/sdXY vfat rw,flush,tz=UTC<br />
<br />
Verify that uefi variables support in kernel is working properly by running:<br />
<br />
# efivar -l<br />
<br />
If efivar lists the uefi variables without any error, then you can proceed. If not, check whether all the conditions in [[#Requirements for UEFI variable support]] are met.<br />
<br />
Then create the boot entry using efibootmgr as follows:<br />
<br />
# efibootmgr -c -d /dev/sdX -p Y -l /EFI/refind/refind_x64.efi -L "rEFInd"<br />
<br />
{{Note|1=UEFI uses backward slash {{ic|\}} as path separator (similar to Windows paths), but the official {{Pkg|efibootmgr}} pkg support passing unix-style paths with forward-slash {{ic|/}} as path-separator for the {{ic|-l}} option. Efibootmgr internally converts {{ic|/}} to {{ic|\}} before encoding the loader path. The relevant git commit that incorporated this feature in efibootmgr is http://linux.dell.com/cgi-bin/cgit.cgi/efibootmgr.git/commit/?id=f38f4aaad1dfa677918e417c9faa6e3286411378 .}}<br />
<br />
In the above command {{ic|/boot/efi/EFI/refind/refind_x64.efi}} translates to {{ic|/boot/efi}} and {{ic|/EFI/refind/refind_x64.efi}} which in turn translate to drive {{ic|/dev/sdX}} -> partition {{ic|Y}} -> file {{ic|/EFI/refind/refind_x64.efi}}.<br />
<br />
The 'label' is the name of the menu entry shown in the UEFI boot menu. This name is user's choice and does not affect the booting of the system. More info can be obtained from [http://linux.dell.com/cgi-bin/cgit.cgi/efibootmgr.git/plain/README efibootmgr GIT README] .<br />
<br />
FAT32 filesystem is case-insensitive since it does not use UTF-8 encoding by default. In that case the firmware uses capital 'EFI' instead of small 'efi', therefore using {{ic|\EFI\refind\refindx64.efi}} or {{ic|\efi\refind\refind_x64.efi}} does not matter (this will change if the filesystem encoding is UTF-8).<br />
<br />
== UEFI Shell ==<br />
<br />
The UEFI Shell is a shell/terminal for the firmware which allows launching uefi applications which include uefi bootloaders. Apart from that, the shell can also be used to obtain various other information about the system or the firmware like memory map (memmap), modifying boot manager variables (bcfg), running partitioning programs (diskpart), loading uefi drivers, editing text files (edit), hexedit etc. <br />
<br />
=== Obtaining UEFI Shell ===<br />
<br />
You can download a BSD licensed UEFI Shell from Intel's Tianocore UDK/EDK2 Sourceforge.net project:<br />
* [[AUR]] package {{AUR|uefi-shell-git}} (recommended) - provides x86_64 Shell in x86_64 system and IA32 Shell in i686 system - compiled directly from latest Tianocore EDK2 SVN source<br />
* There are copies of Shell v1 and Shell v2 in the EFI directory on the Arch install media image.<br />
* [https://github.com/tianocore/edk2/tree/master/ShellBinPkg Precompiled UEFI Shell v2 binaries] (may not be up-to-date)<br />
* [https://github.com/tianocore/edk2/tree/master/EdkShellBinPkg Precompiled UEFI Shell v1 binaries] (not updated anymore upstream)<br />
<br />
Shell v2 works best in UEFI 2.3+ systems and is recommended over Shell v1 in those systems. Shell v1 should work in all UEFI systems irrespective of the spec. version the firmware follows. More info at [http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=ShellPkg ShellPkg] and [http://sourceforge.net/mailarchive/message.php?msg_id=28690732 this mail]<br />
<br />
=== Launching UEFI Shell ===<br />
<br />
Few Asus and other AMI Aptio x86_64 UEFI firmware based motherboards (from Sandy Bridge onwards) provide an option called {{ic|"Launch EFI Shell from filesystem device"}} . For those motherboards, download the x86_64 UEFI Shell and copy it to your EFI System Partition as {{ic|<EFI_SYSTEM_PARTITION>/shellx64.efi}} (mostly {{ic|/boot/efi/shellx64.efi}}) .<br />
<br />
Systems with Phoenix SecureCore Tiano UEFI firmware are known to have embedded UEFI Shell which can be launched using either {{ic|F6}}, {{ic|F11}} or {{ic|F12}} key.<br />
<br />
{{Note|If you are unable to launch UEFI Shell from the firmware directly using any of the above mentioned methods, create a FAT32 USB pen drive with {{ic|Shell.efi}} copied as {{ic|(USB)/efi/boot/bootx64.efi}}. This USB should come up in the firmware boot menu. Launching this option will launch the UEFI Shell for you.}}<br />
<br />
=== Important UEFI Shell Commands ===<br />
<br />
UEFI Shell commands usually support {{ic|-b}} option which makes output pause after each page. Run {{ic|help -b}} to list available commands.<br />
<br />
More info at http://software.intel.com/en-us/articles/efi-shells-and-scripting/<br />
<br />
==== bcfg ====<br />
<br />
{{ic|bcfg}} modifies the UEFI NVRAM entries which allows the user to change the boot entries or driver options. This command is described in detail in page 83 (Section 5.3) of "UEFI Shell Specification 2.0" PDF document.<br />
<br />
{{Note|<br />
* Try {{ic|bcfg}} only if {{ic|efibootmgr}} fails to create working boot entries on your system.<br />
* UEFI Shell v1 official binary does not support {{ic|bcfg}} command. You can download a [http://dl.dropbox.com/u/17629062/Shell2.zip modified UEFI Shell v2 binary] which may work in UEFI pre-2.3 firmwares.<br />
}}<br />
<br />
To dump a list of current boot entries:<br />
<br />
Shell> bcfg boot dump -v<br />
<br />
To add a boot menu entry for rEFInd (for example) as 4th (numbering starts from zero) option in the boot menu:<br />
<br />
Shell> bcfg boot add 3 fs0:\EFI\refind\refind_x64.efi "rEFInd"<br />
<br />
where {{ic|fs0:}} is the mapping corresponding to the EFI System Partition and {{ic|fs0:\EFI\refind\refind_x64.efi}} is the file to be launched.<br />
<br />
To add an entry to boot directly into your system without a bootloader, configure a boot option using your kernel as an [[EFISTUB#UEFI_Shell|EFISTUB]]:<br />
<br />
Shell> bcfg boot add '''N''' fs'''V''':\vmlinuz-linux "Arch Linux"<br />
Shell> bcfg boot -opt '''N''' "root='''/dev/sdX#''' initrd=\initramfs-linux.img"<br />
<br />
where {{ic|N}} is the priority, {{ic|V}} is the volume number of your EFI partition, and {{ic|/dev/sdX#}} is your root partition.<br />
<br />
To remove the 4th boot option:<br />
<br />
Shell> bcfg boot rm 3<br />
<br />
To move the boot option #3 to #0 (i.e. 1st or the default entry in the UEFI Boot menu):<br />
<br />
Shell> bcfg boot mv 3 0<br />
<br />
For bcfg help text:<br />
<br />
Shell> help bcfg -v -b<br />
<br />
or:<br />
<br />
Shell> bcfg -? -v -b<br />
<br />
==== map ====<br />
<br />
{{ic|map}} displays a list of device mappings i.e. the names of available file systems ({{ic|fs0}}) and storage devices ({{ic|blk0}}).<br />
<br />
Before running file system commands such as {{ic|cd}} or {{ic|ls}}, you need to change the shell to the appropriate file system by typing its name:<br />
<br />
Shell> fs0:<br />
fs0:\> cd EFI/<br />
<br />
==== edit ====<br />
<br />
{{ic|edit}} provides a basic text editor with an interface similar to nano, but slightly less functional. It handles UTF-8 encoding and takes care or LF vs CRLF line endings.<br />
<br />
For example, to edit rEFInd's {{ic|refind.conf}} in the EFI System Partition ({{ic|fs0:}} in the firmware),<br />
<br />
Shell> fs0:<br />
FS0:\> cd \EFI\arch\refind<br />
FS0:\EFI\arch\refind\> edit refind.conf<br />
<br />
Type {{ic|Ctrl-E}} for help.<br />
<br />
== UEFI Linux Hardware Compatibility ==<br />
<br />
See [[Unified Extensible Firmware Interface/Hardware]] for more information.<br />
<br />
== UEFI Bootable Media ==<br />
<br />
=== Create UEFI bootable USB from ISO ===<br />
<br />
Follow [[USB flash installation media#BIOS and UEFI Bootable USB]]<br />
<br />
=== Remove UEFI boot support from Optical Media ===<br />
<br />
{{Note|This section mentions removing UEFI boot support from a '''CD/DVD only''' (Optical Media), not from a USB flash drive.}}<br />
<br />
Most of the 32-bit EFI Macs and some 64-bit EFI Macs refuse to boot from a UEFI(X64)+BIOS bootable CD/DVD. If one wishes to proceed with the installation using optical media, it might be necessary to remove UEFI support first.<br />
<br />
* Mount the official installation media and obtain the {{ic|archisolabel}} as shown in the previous section.<br />
<br />
# mount -o loop ''input.iso'' /mnt/iso<br />
<br />
* Then rebuild the ISO, excluding the UEFI Optical Media booting support, using {{ic|xorriso}} from {{pkg|libisoburn}}. Be sure to set the correct archisolabel, e.g. "ARCH_201411" or similar:<br />
{{bc|1=<br />
$ xorriso -as mkisofs -iso-level 3 \<br />
-full-iso9660-filenames\<br />
-volid "''archisolabel''" \<br />
-appid "Arch Linux CD" \<br />
-publisher "Arch Linux <https://www.archlinux.org>" \<br />
-preparer "prepared by $USER" \<br />
-eltorito-boot isolinux/isolinux.bin \<br />
-eltorito-catalog isolinux/boot.cat \<br />
-no-emul-boot -boot-load-size 4 -boot-info-table \<br />
-isohybrid-mbr "/mnt/iso/isolinux/isohdpfx.bin" \<br />
-output ''output.iso'' /mnt/iso/<br />
}}<br />
<br />
* Burn {{ic|''output.iso''}} to optical media and proceed with installation normally.<br />
<br />
== Testing UEFI in systems without native support ==<br />
<br />
=== OVMF for Virtual Machines ===<br />
<br />
[https://tianocore.github.io/ovmf/ OVMF] is a tianocore project to enable UEFI support for Virtual Machines. OVMF contains a sample UEFI firmware for QEMU.<br />
<br />
You can install {{pkg|ovmf}} from the extra repository and run it as follows:<br />
<br />
$ qemu-system-x86_64 -enable-kvm -net none -m 1024 -drive file=/usr/share/ovmf/ovmf_x64.bin,format=raw,if=pflash,readonly<br />
<br />
As shorter alternative, {{Pkg|ovmf}} can be loaded using {{ic|-bios}} parameter<br />
<br />
$ qemu-system-x86_64 -enable-kvm -m 1G -bios /usr/share/ovmf/ovmf_x64.bin<br />
<br />
=== DUET for BIOS only systems ===<br />
<br />
DUET is a tianocore project that enables chainloading a full UEFI environment from a BIOS system, in a way similar to BIOS OS booting. This method is being discussed extensively in http://www.insanelymac.com/forum/topic/186440-linux-and-windows-uefi-boot-using-tianocore-duet-firmware/. Pre-build DUET images can be downloaded from one of the repos at https://gitorious.org/tianocore_uefi_duet_builds. Specific instructions for setting up DUET is available at https://gitorious.org/tianocore_uefi_duet_builds/tianocore_uefi_duet_installer/blobs/raw/master/Migle_BootDuet_INSTALL.txt. <br />
<br />
You can also try http://sourceforge.net/projects/cloverefiboot/ which provides modified DUET images that may contain some system specific fixes and is more frequently updated compared to the gitorious repos.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Windows 7 will not boot in UEFI Mode ===<br />
<br />
If you have installed Windows to a different hard disk with GPT partitioning and still have a MBR partitioned hard disk in your computer, then it is possible that the firmware (UEFI) is starting its CSM support (for booting MBR partitions) and therefore Windows will not boot. To solve this merge your MBR hard disk to GPT partitioning or disable the SATA port where the MBR hard disk is plugged in or unplug the SATA connector from this hard disk.<br />
<br />
Mainboards with this kind of problem:<br />
<br />
* Gigabyte Z77X-UD3H rev. 1.1 (UEFI version F19e)<br />
** The firmware option for booting "UEFI Only" does not prevent the firmware from starting CSM.<br />
<br />
=== Windows changes boot order ===<br />
<br />
If you [[dual boot with Windows]] and your motherboard just boots Windows immediately instead of your chosen UEFI application, there are several possible causes and workarounds.<br />
<br />
* Ensure [[Dual boot with Windows#Fast_Start-Up|Fast Startup]] is disabled in your Windows power options<br />
* Ensure [[Secure Boot]] is disabled in your BIOS (if you are not using a signed boot loader)<br />
* Ensure your UEFI boot order does not have Windows Boot Manager set first e.g. using [[#efibootmgr]] and what you see in the configuration tool of the UEFI. Some motherboards override by default any settings set with efibootmgr by Windows if it detects it. This is confirmed in a Packard Bell laptop. <br />
* If your motherboard is booting the default UEFI path ({{ic|\EFI\BOOT\BOOTX64.EFI}}), this file may have been overwritten with the Windows boot loader. Try setting the correct boot path e.g. using [[#efibootmgr]].<br />
* If the previous steps do not work, you can tell the Windows boot loader to run a different UEFI application. From a Windows Administrator command prompt: {{bc|# bcdedit /set {bootmgr} path \EFI\''path''\''to''\''app.efi''}}<br />
* Alternatively, you can set a startup script in Windows that ensures that the boot order is set correctly every time you boot Windows.<br />
*# Open a command prompt with admin privlages. Run {{ic|bcdedit /enum firmware}} and find your desired boot entry.<br />
*# Copy the Identifier, including the brackets, e.g. {{ic|<nowiki>{31d0d5f4-22ad-11e5-b30b-806e6f6e6963}</nowiki>}}<br />
*# Create a batch file with the command {{ic|bcdedit /set {fwbootmgr} DEFAULT ''{copied boot identifier}''}}<br />
*# Open ''gpedit'' and under ''Local Computer Policy > Computer Configuration > Windows Settings > Scripts(Startup/Shutdown)'', choose ''Startup''<br />
*# Under the ''Scripts'' tab, choose the ''Add'' button, and select your batch file<br />
<br />
=== USB media gets struck with black screen ===<br />
<br />
* This issue can occur either due to [[KMS]] issue. Try [[Kernel mode setting#Disabling_modesetting|Disabling KMS]] while booting the USB.<br />
<br />
* If the issue is not due to KMS, then it may be due to bug in [[EFISTUB]] booting (see {{Bug|33745}} and [https://bbs.archlinux.org/viewtopic.php?id=156670] for more information.). Both Official ISO ([[Archiso]]) and [[Archboot]] iso use EFISTUB (via [[Gummiboot]] Boot Manager for menu) for booting the kernel in UEFI mode. In such a case you have to use [[GRUB]] as the USB's UEFI bootloader by following the below section.<br />
<br />
==== Using GRUB ====<br />
{{Deletion|Through bug report this issue should be fixed in kernel 3.16 and after, so this workaround is not needed anymore.}}<br />
{{Tip|The given configuration entries can also be entered inside a [[GRUB#Using_the_command_shell|GRUB command-shell]].}}<br />
<br />
* [[USB flash installation media#BIOS_and_UEFI_Bootable_USB|Create an USB Flash Installation]]<br />
<br />
* Backup {{ic|EFI/boot/loader.efi}} to {{ic|EFI/boot/gummiboot.efi}}<br />
<br />
* [[GRUB#GRUB_standalone|Create a GRUB standalone image]] and copy the generate {{ic|grub*.efi}} to the USB as {{ic|EFI/boot/loader.efi}}, {{ic|EFI/boot/bootx64.efi}} and/or {{ic|EFI/boot/bootia32.efi}} (useful when running on a 32-bit UEFI)<br />
<br />
* Create {{ic|EFI/boot/grub.cfg}} with the following contents (replace {{ic|ARCH_YYYYMM}} with the required archiso label e.g. {{ic|ARCH_201507}}):<br />
<br />
{{hc|grub.cfg for Official ISO|<nowiki><br />
insmod part_gpt<br />
insmod part_msdos<br />
insmod fat<br />
<br />
insmod efi_gop<br />
insmod efi_uga<br />
insmod video_bochs<br />
insmod video_cirrus<br />
<br />
insmod font<br />
<br />
if loadfont "${prefix}/fonts/unicode.pf2" ; then<br />
insmod gfxterm<br />
set gfxmode="1024x768x32;auto"<br />
terminal_input console<br />
terminal_output gfxterm<br />
fi<br />
<br />
menuentry "Arch Linux archiso x86_64" {<br />
set gfxpayload=keep<br />
search --no-floppy --set=root --label ARCH_YYYYMM<br />
linux /arch/boot/x86_64/vmlinuz archisobasedir=arch archisolabel=ARCH_YYYYMM add_efi_memmap<br />
initrd /arch/boot/x86_64/archiso.img<br />
}<br />
<br />
menuentry "UEFI Shell x86_64 v2" {<br />
search --no-floppy --set=root --label ARCH_YYYYMM<br />
chainloader /EFI/shellx64_v2.efi<br />
}<br />
<br />
menuentry "UEFI Shell x86_64 v1" {<br />
search --no-floppy --set=root --label ARCH_YYYYMM<br />
chainloader /EFI/shellx64_v1.efi<br />
}<br />
</nowiki>}}<br />
<br />
{{hc|grub.cfg for Archboot ISO|<nowiki><br />
insmod part_gpt<br />
insmod part_msdos<br />
insmod fat<br />
<br />
insmod efi_gop<br />
insmod efi_uga<br />
insmod video_bochs<br />
insmod video_cirrus<br />
<br />
insmod font<br />
<br />
if loadfont "${prefix}/fonts/unicode.pf2" ; then<br />
insmod gfxterm<br />
set gfxmode="1024x768x32;auto"<br />
terminal_input console<br />
terminal_output gfxterm<br />
fi<br />
<br />
menuentry "Arch Linux x86_64 Archboot" {<br />
set gfxpayload=keep<br />
search --no-floppy --set=root --file /boot/vmlinuz_x86_64<br />
linux /boot/vmlinuz_x86_64 cgroup_disable=memory loglevel=7 add_efi_memmap<br />
initrd /boot/initramfs_x86_64.img<br />
}<br />
<br />
menuentry "UEFI Shell x86_64 v2" {<br />
search --no-floppy --set=root --file /boot/vmlinuz_x86_64<br />
chainloader /EFI/tools/shellx64_v2.efi<br />
}<br />
<br />
menuentry "UEFI Shell x86_64 v1" {<br />
search --no-floppy --set=root --file /boot/vmlinuz_x86_64<br />
chainloader /EFI/tools/shellx64_v1.efi<br />
}<br />
</nowiki>}}<br />
<br />
=== UEFI boot loader does not show up in firmware menu ===<br />
<br />
On some UEFI motherboards like boards with an Intel Z77 chipset, adding entries with {{ic|efibootmgr}} or {{ic|bcfg}} from the EFI Shell will not work because they do not show up on the boot menu list after being added to NVRAM.<br />
<br />
This issue is caused because the motherboards can only load Microsoft Windows. To solve this you have to place the {{ic|.efi}} file in the location that Windows uses.<br />
<br />
Copy the {{ic|bootx64.efi}} file from the Arch Linux installation medium ({{ic|FSO:}}) to the Microsoft directory your [[ESP]] partition on your hard drive ({{ic|FS1:}}). Do this by booting into EFI shell and typing:<br />
<br />
FS1:<br />
cd EFI<br />
mkdir Microsoft<br />
cd Microsoft<br />
mkdir Boot<br />
cp FS0:\EFI\BOOT\bootx64.efi FS1:\EFI\Microsoft\Boot\bootmgfw.efi<br />
<br />
After reboot, any entries added to NVRAM should show up in the boot menu.<br />
<br />
== See also ==<br />
<br />
* [[Wikipedia:UEFI]]<br />
* [http://www.uefi.org/home/ UEFI Forum] - contains the official [http://uefi.org/specifications UEFI Specifications] - GUID Partition Table is part of UEFI Specification<br />
* [https://www.happyassassin.net/2014/01/25/uefi-boot-how-does-that-actually-work-then/ UEFI boot: how does that actually work, then? - A blog post by AdamW]<br />
* [https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/x86/x86_64/uefi.txt Linux Kernel x86_64 UEFI Documentation]<br />
* [http://www.intel.com/technology/efi/ Intel's page on EFI]{{Dead link|2016|07|16}}<br />
* [http://uefidk.intel.com/ Intel UEFI Community Resource Center]{{Dead link|2016|07|16}}<br />
* [http://uefidk.intel.com/blog/linux-efi-boot-stub Matt Fleming - The Linux EFI Boot Stub]{{Dead link|2016|07|16}}<br />
* [http://uefidk.intel.com/blog/accessing-uefi-variables-linux Matt Fleming - Accessing UEFI Variables from Linux]{{Dead link|2016|07|16}}<br />
* [http://www.rodsbooks.com/linux-uefi/ Rod Smith - Linux on UEFI: A Quick Installation Guide]<br />
* [https://lkml.org/lkml/2011/6/8/322 UEFI Boot problems on some newer machines (LKML)]<br />
* [http://linuxplumbers.ubicast.tv/videos/plumbing-uefi-into-linux/ LPC 2012 Plumbing UEFI into Linux]<br />
* [http://linuxplumbers.ubicast.tv/videos/uefi-tutorial-part-1/ LPC 2012 UEFI Tutorial : part 1]<br />
* [http://linuxplumbers.ubicast.tv/videos/uefi-tutorial-part-2/ LPC 2012 UEFI Tutorial : part 2]<br />
* [http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=Welcome_to_TianoCore Intel's Tianocore Project] for Open-Source UEFI firmware which includes DuetPkg for direct BIOS based booting and OvmfPkg used in QEMU and Oracle VirtualBox<br />
* [http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/efi-boot-process.html FGA: The EFI boot process]<br />
* [http://www.microsoft.com/whdc/device/storage/GPT_FAQ.mspx Microsoft's Windows and GPT FAQ]<br />
* [https://gitorious.org/tianocore_uefi_duet_builds/pages/Windows_x64_BIOS_to_UEFI Convert Windows x64 from BIOS-MBR mode to UEFI-GPT mode without Reinstall]<br />
* [https://gitorious.org/tianocore_uefi_duet_builds/pages/Linux_Windows_BIOS_UEFI_boot_USB Create a Linux BIOS+UEFI and Windows x64 BIOS+UEFI bootable USB drive]<br />
* [http://rodsbooks.com/bios2uefi/ Rod Smith - A BIOS to UEFI Transformation]<br />
* [http://software.intel.com/en-us/articles/efi-shells-and-scripting/ EFI Shells and Scripting - Intel Documentation]<br />
* [http://software.intel.com/en-us/articles/uefi-shell/ UEFI Shell - Intel Documentation]<br />
* [http://www.hpuxtips.es/?q=node/293 UEFI Shell - bcfg command info]<br />
* [http://dl.dropbox.com/u/17629062/Shell2.zip UEFI Shell v2 binary with bcfg modified to work with UEFI pre-2.3 firmware - from Clover efiboot]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=ArchWiki_talk:Requests&diff=442317ArchWiki talk:Requests2016-07-21T10:08:18Z<p>Alive4ever: /* Creation requests */ iPXE specific wiki page</p>
<hr />
<div>[[Category:ArchWiki]]<br />
Is the wiki missing documentation for a popular software package or coverage of an important topic? Or, is existing content in need of correction, updating, or expansion? Write your requests below and share your ideas...<br />
<br />
See [[ArchWiki:Reports]] to report questionable contributions. Please sign your edits and feel free to comment on others' requests.<br />
<br />
== General requests ==<br />
<br />
; [[:Category:Pages or sections flagged with Template:Accuracy|Inaccurate content]]: Pages flagged with [[Template:Accuracy]].<br />
; [[:Category:Pages or sections flagged with Template:Out of date|Outdated content]]: Pages flagged with [[Template:Out of date]].<br />
; [[:Category:Pages flagged with Template:Archive|Obsolete pages]]: Pages flagged with [[Template:Archive]].<br />
; [[:Category:Sections flagged with Template:Remove|Irrelevant or unhelpful content]]: Pages flagged with [[Template:Remove]].<br />
; [[:Category:Pages or sections flagged with Template:Expansion|Incomplete content]]: Pages flagged with [[Template:Expansion]].<br />
; [[:Category:Pages or sections flagged with Template:Style|Content with language or style issues]]: Pages flagged with [[Template:Style]].<br />
; [[:Category:Pages or sections flagged with Template:Laptop style|Non-standard laptop pages]]: Pages flagged with [[Template:Laptop style]].<br />
; [[:Category:Pages or sections flagged with Template:Merge|Duplicate effort or overlapping scope]]: Pages flagged with [[Template:Merge]].<br />
; [[:Category:Pages or sections flagged with Template:Move|Misleading names]]: Pages flagged with [[Template:Move]].<br />
; [[:Category:Pages or sections flagged with Template:Bad translation|Poor translations]]: Pages flagged with [[Template:Bad translation]].<br />
; [[:Category:Pages or sections flagged with Template:Translateme|Incomplete translations]]: Pages flagged with [[Template:Translateme]]. See also [[ArchWiki Translation Team]].<br />
; [[:Category:Pages flagged with Template:Stub|Incomplete content]]: Pages flagged with [[Template:Stub]] ([[Template talk:Stub#Definition of stub|deprecated]]).<br />
; [[:Category:Pages flagged with Template:Redirect|Deprecated titles]]: Pages flagged with [[Template:Redirect]].<br />
; [[:Category:Pages with dead links|Dead or broken links]]: Pages flagged with [[Template:Dead link]]. Should be repaired or replaced.<br />
; [[:Category:Pages with broken templates|Templates with an undefined parameter]]: Pages automatically flagged with [[Template:META Error]]<br />
; [[Special:WhatLinksHere/Template:META Unexplained Status Template|Unexplained presence of an article status template]]: Pages automatically flagged with [[Template:META Unexplained Status Template]].<br />
; [[:Category:Pages with missing package links|Application listed without links to packages]]: Pages automatically flagged with [[Template:META Missing package]].<br />
; [[Special:WantedTemplates|Misspelled or deprecated templates]]: Need to fix template or change to new template.<br />
; [[:Category:Noindexed pages|Noindexed pages]]: Automatic tracking category.<br />
; [[:Category:Pages using duplicate arguments in template calls|Duplicate arguments in template calls]]: Automatic tracking category.<br />
<br />
Also note that [[Special:WantedCategories]] can show additional automatic [[mw:Help:Tracking categories|tracking categories]].<br />
<br />
=== Problem redirects ===<br />
<br />
{{Note|Redirects should not point to other sites and ones that do sometimes erroneously show up on these pages.}}<br />
<br />
* [[Special:BrokenRedirects]]<br />
* [[Special:DoubleRedirects]]<br />
<br />
=== Broken package links ===<br />
<br />
{{Expansion|Add documentation for all the hints: meaning + recommended action|talk=ArchWiki:Requests#Strategy for updating package templates}}<br />
<br />
ArchWiki contains many broken links to packages not found either in [[official repositories]] or [[AUR]], which is the result of packages being merged, split or removed from the repositories. All pages in the main namespace are regularly checked by a bot, which checks all instances of [[Template:AUR|AUR]], [[Template:Grp|Grp]] and [[Template:Pkg|Pkg]] templates, tries to automatically update them and marks them with [[Template:Broken package link]] when it is not possible to update them automatically.<br />
<br />
To fix a broken package link, do '''not''' simply remove the reference to the packages from the wiki, do some research first:<br />
<br />
* Search the package database ({{ic|pacman -Ss}}) and [https://aur.archlinux.org/packages/ AUR], it is possible that the package was merged/renamed.<br />
* If looking for a specific file, for example a binary that was part of the package, [[pkgfile]] might do the trick.<br />
* If unsure, mark the page or section with an appropriate [[Help:Template#Article status templates|status template]] rather than completely removing the reference to the package.<br />
* For AUR3 package links marked with [[Template:Aur-mirror]], you may consider resubmitting them to the AUR if interested in maintaining them.<br />
<br />
All pages with broken package links are tracked in [[:Category:Pages with broken package links]].<br />
<br />
== Creation requests ==<br />
<br />
''Here, list requests for topics that you think should be covered on ArchWiki. If not obvious, explain why ArchWiki coverage is justified (rather than existing Wikipedia articles or other documentation). Furthermore, please consider researching and creating the initial article yourself (see [[Help:Editing]] for content creation help).''<br />
<br />
=== HOWTO: SAMBA PDC + LDAP ===<br />
<br />
How to configure SAMBA PDC + LDAP in Arch Linux? (Moved from another page. [[User:Hokstein|Hokstein]] 19:57, 16 September 2007 (EDT))<br />
<br />
=== Left-Handed Adjustments for Desktop Environments ===<br />
<br />
I was thinking it would be helpful for lefties if there were a list of configuration options for each desktop environment that facilitate left-handed use of mice and touchpads. I'm not sure if this is related enough to Arch to include in this wiki, but I haven't had a lot of luck finding information for my own DE (KDE) let alone for others. I will start writing down information, and if no one else thinks there should be a separate page for this, I'll just add the information I find to each individual DE's page. —[[User:ajrl|ajrl]] 2013-08-11T15:09−06:00<br />
: I think a separate page is better. -- [[User:Fengchao|Fengchao]] ([[User talk:Fengchao|talk]]) 11:58, 12 August 2013 (UTC)<br />
<br />
=== Input methods ===<br />
<br />
Currently there is no page on ArchWiki properly describing various input methods ''generally''. There is only [[Internationalization#Input_methods_in_Xorg]], but it has several problems:<br />
<br />
* missing descriptions<br />
* [[Keyboard configuration in Xorg#Configuring_compose_key|X compose key]] does not fit in<br />
* GTK has a default "simple" input method featuring the {{ic|Ctrl+Shift+u}} shortcut for entering a unicode character (this was added recently into a wrong article: [https://wiki.archlinux.org/index.php?title=Bash&diff=289079&oldid=287436]) - again, no description<br />
* no description of XIM - outdated, but sometimes used as fallback?<br />
<br />
So this is quite enough material to start a new great article ;)<br />
<br />
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:23, 18 December 2013 (UTC)<br />
<br />
:Update to note: While [[Internationalization#Input_methods_in_Xorg]] itself still remains a stub, we had editors contributing language specific instructions which were set as subpages of the article: <br />
:[[Internationalization/Japanese]] and [[Internationalization/Korean]] <br />
:--[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 21:57, 11 January 2015 (UTC)<br />
<br />
===DRI===<br />
An article, or even stub that links to resources, explaining what DRI is, why it's important, differences between DRI 1, 2, 3, how DRI1 is no longer supported as of xorg-server 1.13, simple xorg.conf code explaining the DRI section, enabling the composite and render extensions there, these and more. Just my thoughts.<br />
<br />
=== ldns ===<br />
<br />
ldns is a core package with no wiki documentation. It is also relatively new in the world of DNS tools and is not well covered on the Internet. Documentation of basic features and what it is not (eg a replacement for bind) would provide a valueable resource. <br />
[[User:MichaelRpdx|MichaelRpdx]] ([[User talk:MichaelRpdx|talk]]) 20:07, 17 February 2014 (UTC)<br />
<br />
:The description of the {{Pkg|ldns}} package is "Fast DNS '''library''' supporting recent RFCs". The [https://www.nlnetlabs.nl/projects/ldns/ official homepage] mentions that several example programs are included with the library, the [https://www.nlnetlabs.nl/projects/ldns/doc/index.html official docs] is probably best for programmers. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:37, 17 February 2014 (UTC)<br />
<br />
=== Perl ===<br />
Surprisingly, there is no wiki page describing the installation and configuration of Perl, unlike Python, Ruby etc. Could include the installation of CPAN modules and a list of good tutorials for beginners, too. So far there is only guides for packaging Perl and its modules ([[Perl Policy]] and [[Perl package guidelines]] respectively) -- [[User:bluestreak0|bluestreak0]] 01:32, 17 April 2014 (UTC)<br />
<br />
===Linux console===<br />
<br />
I was thinking that a new page for the console would be a good idea. The [[Wikipedia:Linux console]] article gives a short general overview, but obviously doesn't concern the configuration. Since it's an independent system, configured separately from any graphical environment, it would bring together several related sections across multiple articles in one place. It's a fairly complex system and difficult to cover in any depth in small sections across other articles (such as [[Fonts]]). I've put together a basic example, [[User:Teppic74/Linux_console]]. -- [[User:Teppic74|Teppic74]] ([[User talk:Teppic74|talk]]) 17:11, 3 July 2014 (UTC)<br />
<br />
:Sounds interesting, but I don't know how deep you want to go in the description, it may be too much for a single page as, according to your outline, the resulting article would cover all [[Fonts#Console fonts]], [[Keyboard configuration in console]], part of [[Extra keyboard keys]], [[Map scancodes to keycodes]] and [[Extra keyboard keys in console]]. The keyboard configuration is split mainly because the configuration for [[Xorg]] is connected to it, I don't know how this would be done if the low-level description is moved. On the other hand, some of these articles could use some reorganization, so it may still be possible... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:17, 4 July 2014 (UTC)<br />
<br />
::I feel this is part of the problem, that the details concerning the console are tacked on to other articles rather than being naturally associated with them. As things stand, I think the documentation is lacking. I don't think a huge amount of information is needed, it would just be helpful to be in one place, as the console is mostly isolated from the rest of the system. The other articles could link to the console article for further details. Another possibility is separate articles exclusively for the console display and keyboard, but they're obviously part of the same topic. -- [[User:Teppic74|Teppic74]] ([[User talk:Teppic74|talk]]) 18:48, 4 July 2014 (UTC)<br />
<br />
===Sublime-text===<br />
I think creating a page and mentioning ways to improve sublime-text integration with Gnome would be a good idea.<br />
The trick is if you run sublime with ''--class=<filename of sublime text .desktop file, e.g. sublime_text_3>'', it would help Gnome and XFCE to group sublime instances with its respective desktop file.<br />
This is mentioned in the comments of the aur package but I think it's better that this would be in the wiki.--[[User:183.amir|183.amir]] ([[User talk:183.amir|talk]]) 12:41, 19 December 2014 (UTC)<br />
<br />
===iPXE===<br />
iPXE is a powerful network boot program with many features. Currently, there is no iPXE specific page to describe iPXE in details.<br />
There are some pages mentioning iPXE in the wiki, mostly related to network booting, without any further instruction on how to get iPXE to work.<br />
So I think it's worth to add a page with detailed iPXE explanation in the wiki.<br />
[[User:Alive4ever|Alive4ever]] ([[User talk:Alive4ever|talk]]) 10:08, 21 July 2016 (UTC)<br />
<br />
== Modification requests ==<br />
<br />
''Here, list requests for correction or other modification of existing articles. Only systemic modifications that affect multiple articles should be included here. If a specific page needs modification, use that page's ''discussion'' or ''talk'' page instead and one of the [[#General requests]] templates.''<br />
<br />
As a rolling release, Arch is constantly receiving updates and improvements. Because of this the Arch wiki must be updated quickly to reflect these changes.<br />
<br />
=== Should we remove or archive obsolete articles? ===<br />
<br />
''[Moved to [[ArchWiki talk:Administrators#Should we remove or archive obsolete articles?]]; keeping the section subtree here to prevent backlink breakage until the whole discussion is closed. — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 08:05, 12 April 2016 (UTC)]''<br />
<br />
==== List of suggested solutions ====<br />
<br />
==== Enforcement ====<br />
<br />
===== Restoring revisions and redirection =====<br />
<br />
===== Separation of archive content =====<br />
<br />
===== Double redirects =====<br />
<br />
===== Rename Template:Deletion =====<br />
<br />
===== How to archive templates =====<br />
<br />
=== Renamed software ===<br />
<br />
==== Nautilus got renamed to Gnome Files ====<br />
<br />
Do we want to rename every occurrence of 'nautilus' in Arch wiki or is [https://wiki.archlinux.org/index.php?title=Nautilus&redirect=no the redirect] enough? -- [[User:Karol|Karol]] ([[User talk:Karol|talk]]) 23:49, 21 August 2014 (UTC)<br />
<br />
:The redirect has only [[Special:WhatLinksHere/Nautilus|3 backlinks]], 2 of which are talk pages. About normal strings, [https://wiki.archlinux.org/index.php?title=Special:Search&limit=500&offset=0&redirs=1&profile=default&search=nautilus this] should be a comprehensive list, but it seems pretty dangerous to do a blind mass rename with a bot.<br />
:Moving this back to the normal requests.<br />
:-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 14:06, 22 August 2014 (UTC)<br />
<br />
:: I replaced appropriate occurrences of 'nautilus' yesterday. I preserved upstream software names e.g. (Nautilus Terminal), package names and gschema names (for obvious reasons) and executable names. -- [[User:Chazza|Chazza]] ([[User talk:Chazza|talk]]) 14:50, 5 November 2014 (UTC)<br />
<br />
:::Well done once again, Chazza, but the search I linked above still seems to show some appearances of "Nautilus" as file manager, so I guess we can't close this item yet. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 09:57, 6 November 2014 (UTC)<br />
<br />
:::: I started going through the pages in the search you link to. I think it will have to be done manually seeing as paths, gschemas, executables and upstream projects that use nautilus in their name cannot be renamed. Regarding foreign language pages, if there are just a handful occurrences of 'Nautilus' google translate can be used to get the gist of a sentence and see if it is safe to change 'Nautilus' to 'GNOME Files' or 'Files' - usually it is. But for the Spanish and Arabic pages Nautilus pages, there are dozens of occurrences so I would much rather leave that to native speakers. -- [[User:Chazza|Chazza]] ([[User talk:Chazza|talk]]) 11:41, 6 November 2014 (UTC)<br />
<br />
:::::Doh, I said the discussion was to be kept open, but I struck the heading anyway ^^' (thanks for re-opening it)<br />
:::::I was only referring to the English pages, I agree that the presence of out of date translations shouldn't be enough to keep requests in this page open, unless they are specifically about translations, which is not this case.<br />
:::::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 13:36, 7 November 2014 (UTC)<br />
<br />
===== List =====<br />
<br />
A list of pages where all possible instances Nautilus have been changed so we know what's been done and what hasn't. I will add to the list as I go through the pages returned in the search. -- [[User:Chazza|Chazza]] ([[User talk:Chazza|talk]]) 11:41, 6 November 2014 (UTC)<br />
<br />
* [[Nautilus]] - Completed<br />
* [[Nautilus (日本語)]] - No changeable instances<br />
* [[Digital Cameras]] - Completed<br />
* [[Awesome (한국어)]] - Completed<br />
* [[GNOME (简体中文)]] - Completed<br />
* [[GNOME tips]] - Completed<br />
* [[Desktop environment]] - No changeable instances<br />
* [[Lineak]] - No changeable instances<br />
* [[GNOME tips (Nederlands)]] - Completed<br />
* [[Firefox (العربية)]] - No changeable instances<br />
* <s> [[Bug Day/2010]] - No changeable instances </s><br />
* [[Openbox (Česky)]] - Completed<br />
* [[fuseiso]] - Completed<br />
* [[Beginners' Guide (Indonesia)]] - Completed<br />
* [[Feh]] - Completed<br />
* [[Bluetooth (Italiano)]] - Completed<br />
* [[Feh (Italiano)]] - Completed<br />
* [[Samba (Italiano)]] - Completed<br />
* [[Backup programs]] - Completed<br />
* [[Oggenc]] - Completed<br />
* [[Samba]] - Completed<br />
* [[IPod]] - Completed<br />
* [[Dropbox]] - Completed<br />
* [[GNOME (Italiano)]] - No changeable instances<br />
* [[Samba (日本語)]] - Completed<br />
* [[GNOME Tips (简体中文)]] - Completed<br />
<br />
==== <s>XBMC renamed to Kodi</s> ====<br />
<br />
Since version 14 XBMC was renamed to Kodi, see {{bug|43220}}. There are also some typos that say 'xmbc'. -- [[User:Karol|Karol]] ([[User talk:Karol|talk]]) 10:59, 25 December 2014 (UTC)<br />
<br />
:I checked backlinks to [[Kodi]] of the now moved article. I think we got it covered. Can this be closed? --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 09:22, 4 January 2015 (UTC)<br />
<br />
::Thank you Indigo, unfortunately there's [https://wiki.archlinux.org/index.php?title=Special%3ASearch&search=xbmc&fulltext=Search more], including an entry in [[List of applications/Multimedia]] and an entire section in [[XScreenSaver]] :) — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 09:21, 5 January 2015 (UTC)<br />
<br />
:::Ah, thanks for search fu. I amended the last two for starters of this lot [https://wiki.archlinux.org/index.php?title=List_of_applications%2FMultimedia&diff=355510&oldid=353008] [https://wiki.archlinux.org/index.php?title=XScreenSaver&diff=355511&oldid=345221]. Simple thing to watch for the [https://wiki.archlinux.org/index.php?title=Special%3ASearch&search=xbmc&fulltext=Search rest] is that the config directory stays {{ic|~/.xmbc/}}. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 14:50, 5 January 2015 (UTC)<br />
::::Ok, english links should be changed now. I have another go at closing. [[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 18:19, 10 July 2016 (UTC)<br />
<br />
==== Gummiboot ====<br />
<br />
Gummiboot is included in {{Pkg|systemd}} since 220-2 as [[systemd-boot]]. Relevant search: [https://wiki.archlinux.org/index.php?title=Special:Search&limit=500&offset=0&profile=default&search=gummiboot gummiboot] -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:05, 30 August 2015 (UTC)<br />
<br />
=== Cleanup: links to non-existent packages ===<br />
<br />
As of today, there are exactly 714 invalid uses (413 unique) of [[Template:AUR]] or [[Template:Pkg]], spread across 398 pages. The complete list is on <s>[[User:Lahwaacz.bot/Report 2014-04-05]]</s>. I will try to go through it and update the links, but this is not a one-man job, so I would really appreciate some help. Please remember to strike/remove the items from the list to save others' time. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 16:42, 5 April 2014 (UTC)<br />
<br />
:The previous report is closed for further updates, please contribute to <s>[[User:Lahwaacz.bot/Report 2014-05-11]]</s>. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:15, 12 May 2014 (UTC)<br />
<br />
::The previous reports are closed for further updates, please contribute to <s>[[User:Lahwaacz.bot/Report 2014-12-24]]</s>. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:14, 25 December 2014 (UTC)<br />
<br />
:::The previous reports are closed for further updates, please contribute to [[User:Lahwaacz.bot/Report 2015-02-06]]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 23:08, 6 February 2015 (UTC)<br />
<br />
:::: After introducing "package not found" link, should the bot pages above be removed now? --[[User:Fengchao|Fengchao]] ([[User talk:Fengchao|talk]]) 13:05, 10 March 2015 (UTC)<br />
<br />
:::::I'll delete them eventually, for now I think they could be useful for searching through the user notes when fixing localized pages (not that many user do this...) First I will need to implement the automatic report page as suggested in [[#Strategy for updating package templates]]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:00, 13 March 2015 (UTC)<br />
<br />
==== Surrounding link text ====<br />
<br />
While performing [[#Cleanup: links to non-existent packages]], the bot updated a lot of package links, but of course it couldn't update the text around them accordingly, for example [https://wiki.archlinux.org/index.php?title=Smokeping&diff=prev&oldid=308608], so that's something else that could be done. Here's the list of the changes: <s>[https://wiki.archlinux.org/index.php?limit=250&tagfilter=&title=Special%3AContributions&contribs=user&target=Lahwaacz.bot&namespace=&year=2014&month=4]</s>. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:24, 7 April 2014 (UTC)<br />
<br />
:Technical detail: the last link is now slightly inaccurate, it shows all edits of the bot made in April 2014. Is there a way to set a specific day? (in this case 5th April) -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:46, 9 April 2014 (UTC)<br />
<br />
::Cool, there's really a way, I've just noticed it :D https://wiki.archlinux.org/index.php?title=Special:Contributions&target=Lahwaacz.bot&offset=20140406000000 (the magic is in the {{ic|offset}} parameter!) -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 13:51, 11 April 2014 (UTC)<br />
<br />
:::Update: the edit list for the 2014-05-11 cleanup is [https://wiki.archlinux.org/index.php?title=Special:Contributions&target=Lahwaacz.bot&offset=20140512000000]. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 09:42, 12 May 2014 (UTC)<br />
<br />
::::Update: the edit list for the 2014-12-24 cleanup is [https://wiki.archlinux.org/index.php?title=Special:Contributions&target=Lahwaacz.bot&offset=20141225000000]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:14, 25 December 2014 (UTC)<br />
<br />
:::::Update: the edit list for the 2015-02-06 cleanup is [https://wiki.archlinux.org/index.php?title=Special:Contributions&target=Lahwaacz.bot&offset=20150207000000]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 23:08, 6 February 2015 (UTC)<br />
<br />
=== Strategy for updating package templates ===<br />
<br />
It is an open secret that the current strategy for updating package templates, which lies in creating a dedicated report page, is not very effective. The number of broken package links was 714 before the [https://lists.archlinux.org/pipermail/arch-general/2014-April/035793.html first cleanup] almost a year ago. Today, after several successful cleanups the number is 979.<br />
<br />
The first problem is that the report page is being noticed only a short time after announcing the cleanup and (almost) completely overlooked after a few days. Updating a wiki should be a continuous effort, but this strategy relies on announcing an event.<br />
<br />
The second problem is that only English pages were consistently updated in the cleanups. No wonder since the events were announced only in English...<br />
<br />
I have a proposal to solve the first problem, and partially also the second: instead of creating report pages and organizing cleanups, the broken package links could be marked directly in wiki pages, similarly to the way external links are marked with [[Template:Dead link]]. The result could look like this: {{Pkg|pkgname}}<sup>broken link: hint</sup> where "broken link" is a link to a section with detailed instructions to fix the package link and "hint" is a short hint uniquely identifying the problem (given by the bot).<br />
<br />
The proposal could be implemented in multiple ways:<br />
<br />
# By introducing a single template, e.g. "Broken package link", which would take "hint" as a parameter and produce {{ic|&lt;sup>broken link: ''hint''&lt;/sup>}}. This template would be added immediately after the broken instance of [[template:Pkg|Pkg]], [[template:AUR|AUR]] or [[template:Grp|Grp]], exactly the same way as [[Template:Dead link]] is added to broken external links.<br />
# By introducing a separate template for each [[template:Pkg|Pkg]], [[template:AUR|AUR]] and [[template:Grp|Grp]], for example "Broken Pkg link", "Broken AUR link" and "Broken Grp link". These templates would take two parameters, the (broken) package name and the hint. Then, "Broken Pkg link" would produce {{ic|<nowiki>{{Pkg|</nowiki>''pkgname''<nowiki>}}<sup>broken link: </nowiki>''hint''<nowiki></sup></nowiki>}} and so on.<br />
<br />
So far I'm for the second way, which should be more favourable to the bot.<br />
<br />
The advantage of this strategy is that broken package links and hints are continuously visible to everybody reading the wiki page, which are presumably people most interested in the topic at the moment, while maintainers can still easily go through full lists generated by [[Special:WhatLinksHere]]. Also, I would not have to announce events :)<br />
<br />
Of course I'm still open to other suggestions on solving the above problems, or any other if I missed something.<br />
<br />
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:51, 10 February 2015 (UTC)<br />
<br />
:I totally support this, although method 1. looks cleaner to me, because:<br />
:* It makes it clearer and more natural for users how to fix the template (just remove the message Vs fix the template name AND remove the message).<br />
:* It's consistent with [[Template:Dead link]].<br />
:Why would method 2. "be more favourable to the bot"?<br />
:— [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 00:51, 11 February 2015 (UTC)<br />
<br />
::The second method would only add checking additional templates. The first method would need checking for an adjacent template, which could be tricky to implement. I haven't tried it yet though, in the end it may be equally easy to the second method. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:59, 11 February 2015 (UTC)<br />
<br />
:::Other thing is that one of the mistakes when using AUR/Pkg/Grp templates is invalid number of parameters, e.g. [https://wiki.archlinux.org/index.php?title=Internationalization/Korean&diff=359911&oldid=353001]. If the additional parameters are to be preserved and not automatically removed by the bot, this would be impossible to mark using the second way. Well, almost impossible, we could still set the hint using a named parameter, but it would be really unclear how the link marked this way should be "fixed". So we should definitely use the first method. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:32, 11 February 2015 (UTC)<br />
<br />
::::Regarding your last point, I think those instances are very rare and editors will figure how to fix the link/sentence correctly (once they did the tricky part of finding where the package went). In my view this should not deter from using method 2, if there are any doubts method 1 with the bot might be problematic (over time). <br />
::::Either method would be great. One suggestion regarding the current report pages: How about still producing them additionally, but onto a static page (overwritten on next run, noting a schedule, e.g. quarterly, on top)? Reason: Particularly if an editor wants to fix articles of a language, [[Special:WhatLinksHere]] is unwieldy to swim through for articles in the language. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 10:20, 12 February 2015 (UTC)<br />
<br />
:::::I could certainly still produce the reports. Also being it a static page, the updating could be done automatically similarly to [[ArchWiki:Statistics]] (so far I have created the report pages manually).<br />
:::::I have implemented the first method in the [https://github.com/lahwaacz/wiki-scripts/commit/3e7e1103ee7a0560ce7d8f298055e4dec8ea6fc8 bot script] today. Since it has taken me almost half a day, it was probably not "equally easy" to the second method, but I think it works quite well and safely now. [[Template:Broken package link]] is now created and its "broken link" link points to [[#Broken package links]], feel free to improve both.<br />
:::::I was also thinking about how to integrate [[#Surrounding link text]] into [[#Broken package links]], maybe the link to the bot's "contributions" with fixed date should be automatically put somewhere on each run? This task also depends too much on context, so the links like [https://wiki.archlinux.org/index.php?title=Special:Contributions&target=Lahwaacz.bot&offset=20150207000000] are not very useful. In a way, it is already marked on the pages, because the link points e.g. to AUR and the context says otherwise. Also, we probably don't have the workforce to do systematic checking on this task, so is it even worth to include these instructions/links?<br />
:::::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:59, 12 February 2015 (UTC)<br />
<br />
::::::Sorry I did not mean to incur an extra manual task regarding the static page, just recalled how helpful it is to do the task systematically. It is related to your question about a run result page of the bot though. For cross-checking the bot's contributions for consistency we can filter like you do above and that should be enough imo. To work on the content, a bot result page probably would require manual transformation like the current method again. So, not required but an option. <br />
::::::Regarding the template: I would leave out "the hint" because the sup-text gets too long and breaks text badly on small resolutions. "Broken link" should be enough, not? Also I would let "Broken link" link itself to [[Template:Broken_package_link]]. This way we can change the link to the instructions ([[#Broken_package_links]]) noted there in case they move (e.g. to [[ArchWiki:Contributing]]) at a later point, or we decide to expand the instructions in the template itself a little, without needing a bot run over existing broken links again. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 22:45, 12 February 2015 (UTC)<br />
<br />
:::::::I actually like your idea about the report page. Don't worry about the manual work, it can all be automated :) The report page could also include some statistics that can be collected during the update, e.g. how many broken links are there per language/in total.<br />
:::::::I think that it is important to include the hint, except for the obvious "package not found", which is included only for consistency (and because the template would otherwise end with the {{ic|: ]}} sequence). It may be silly that the hint is longer than the package name (the message "invalid number of template parameters" is probably too long anyway), but the only alternative I can think of is using some cryptic abbreviations like "PNF" for "package not found", which would be explained among other instructions pointed to by the "broken link" link.<br />
:::::::Having the instructions on this page has the advantage that it is linked from the navigation bar on the left, whereas [[Template:Broken package link]] would not be as easily discovered "by accident". The template page should serve mainly as a description of the template itself and just link to the instructions, so I'd leave it this way. Of course if the instructions are moved, the link in the template can be updated accordingly.<br />
:::::::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:32, 13 February 2015 (UTC)<br />
<br />
::::::::(I was writing this while Lahwaacz was writing his post above, and he saved before me, but I think this comment can still be useful)<br />
::::::::Well done Lahwaacz for implementing method 1.<br />
::::::::The problem of grouping broken links by language would IMO be more naturally solved with localized [[Template:Broken package link]] templates, instead of using a report: it would be easy to add this feature to the bot.<br />
::::::::The problem of the context wording is clearly unsolvable automatically, but for completeness I would mention it briefly in [[#Broken package links]]. I don't think adding any links is going to be of any usefulness; in theory a list of the changes could indeed be maintained in a report, and the entries stricken whenever each link's surrounding text is manually checked to be mentioning the correct location of the package; I'm not sure how popular such a list would be though, and the text would also be fixed anyway by casual users whenever they notice the inconsistency while reading the article. An alternative is using the bot to only always add the broken link template, even when the package template could be updated automatically, letting instead the users do all the actual updates manually; this method could be integrated with Wiki Monkey's editor assistant, which would complete the template updates in the editor, but still allow checking the changes before saving (already implemented there).<br />
::::::::About leaving out "the hint", maybe we could instead remove "broken link: " and move the link to "the hint". Would adding a light-red background to "the hint" help having it recognized as a link status template, even if "broken link: " isn't there anymore? But still, this method would make the template inconsistent with [[Template:Dead link]], unless we want to update that one too.<br />
::::::::If we want the link to [[ArchWiki:Requests#Broken package links]] to be flexible in case we want to move the instructions somewhere else, I'd say the most natural way would be to use a redirect like [[Broken package link]] that we can point to wherever we want.<br />
::::::::— [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 15:50, 13 February 2015 (UTC)<br />
<br />
=== index.php in url address ===<br />
<br />
Admins of Arch Wiki, do you noticed, that in every page address begins with ''https://wiki.archlinux.org/index.php?title=''? Why? It is uncomfortable. Why could not you do just article name after ''https://wiki.archlinux.org/''? — [[User:Agent0|Agent0]] ([[User_talk:Agent0|talk]]|[[Special:Contributions/Agent0|contribs]]) 22:48, 6 March 2015 (UTC)<br />
<br />
:Administrators can't configure the entry-point urls, that's something that should be done in LocalSettings.php, which however is currently unpatchable because of {{Bug|35545}}.<br />
:Nonetheless I agree with you, urls could be prettified by removing "index.php/", I think [https://wiki.archlinux.fr/Sp%C3%A9cial:Version#URL%20des%20points%20d%27entr%C3%A9e wiki.archlinux.fr] has the best configuration in this respect. Documentation is in [[mw:Manual:Short URL/LocalSettings.php]]. Backward compatibility wouldn't be a problem since urls can be easily rewritten by the http server.<br />
:— [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 01:49, 7 March 2015 (UTC)<br />
<br />
::I have noticed, that article's path became ''https://wiki.archlinux.org/index.php/Page_title''. Better, but still with ugly index.php. I agree with you, french arch linux wiki did varian which I wanted: just clearly ''https://wiki.example.com/Page_title''. But according to [https://www.mediawiki.org/wiki/Manual:Wiki_in_site_root_directory] it is not recommended in some cases. As I understand, it just do not allow you (Pierre) to use some titles as articles, for example https://wiki.example.com/favicon.ico, but really, what reason to have such articles =D. And another problem may be that it may require root access to hosting server. Does wiki.archlinux.org is running on virtual server or it is hosted on a normal server? — [[User:Agent0|Agent0]] ([[User_talk:Agent0|talk]]|[[Special:Contributions/Agent0|contribs]]) 09:59, 17 August 2015 (UTC)<br />
<br />
=== Change drive naming/accessing to UUID? ===<br />
<br />
Trying to install drives with/out Luks, LVM on internal, external drives is quite complicated currently. Following the ralated articles suggest different ways of reaching the goal. Many different drive name conventions are suggested, eg.:<br />
<br />
* /dev/sda2<br />
* /dev/md0<br />
* /dev/mapper/md/0<br />
* /dev/mapper/vgroup-lvm-root<br />
* /dev/vgroup-luks/root<br />
* ...<br />
<br />
Some of them don't work with portable external drives. This overcomplicates setting up encrypted drives in different situations. My suggestion is, to change all drive related articles to one specific solution of addressing drives universal. Currently I think of UUDI drive naming as a way to go. This would ease the process of drive naming in all kinds of situations:<br />
<br />
* The reader is guided through system setup along one red line<br />
* Troubleshootiing "no drie found" is strait forward<br />
* Many sections become clearer to read even when not reading the whole article<br />
* Articles are easier to write and maintain<br />
* Beginners have an easier read and geta better idea of how to access drives<br />
* Accessing internal/external encrypted drives is easy<br />
' LMV or other virtual file systems are easier to describe and setup<br />
<br />
Ok, I know it is a big suggestion. I wanted to bring it up here, bacause I have the impression that following one primary path would help a lot - everyone involved. It doesn't need to be done in one day. While I think to have one suggested guideline would be a good start. Then with thain mind, we all have it easier to change those sections while Writing/editing Wiki entries. <br />
<br />
[[User:T.ask|T.ask]] ([[User talk:T.ask|talk]]) 11:22, 30 March 2015 (UTC)<br />
<br />
:Hi, To your own examples above: using an UUID for a /dev/mapper/* device declaration is generally unnecessary (the uniqueness of the device is determined when it is mapped). I think you overestimate the amount of users who actually require setting up the examples where it really matters (e.g. external drives). What I don't understand is why you consider using UUIDs being easier to read/describe. For starters the terribly long UUIDs will break formatting in many cases, e.g. making code blocks in-text not possible. An UUID itself gives no contextual hint, something that a device name does. If you look at the three examples in [[Persistent block device naming#Boot managers]], you really find the UUID one the easiest? <br />
:I think you are certainly right in that we may lack crosslinks to [[Persistent_block_device_naming]] in some articles where it may be important to use an UUID. Maybe we also need an example section to illustrate singular important points in [[Persistent block device naming]] and maybe there are individual articles/sections where content should indeed use a form of persistent naming straight away. <br />
:Suggestion: How about using [[Talk:Persistent block device naming]] to assemble a list of ''particular'' article sections with content where persistent naming should be made more prominent? That way we could also figure if and which examples may be useful to be added. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 17:47, 30 March 2015 (UTC)<br />
::Hi, I started this topic because "by design" Linux has so many ways to assign drives and the Wiki uses them kind of "randomly". Finding the ''best drive naming method'' for the Wiki is my intention. Giving the reader a hand, by enabling him/her to understand one way of accessing drives and collect all the others somewhere.<br />
::I'm suggesting UUIDs, because they can be used for local and mobile situations. They are easy to use. The UUID format is universal and is independent of the location (local/mobile) or the context (LVM, Raid, Luks, ...) in which they are used.<br />
::The reason why I'm bring this up is, that it seems, the wiki has currently no standardized form of drive path declaration. If we can find one practical method, it will be easier to write, edit and maintain articles. Everyone involved will know then, which method is the recommended.<br />
::Therefore, I wanted to start an open conversation, to find ideas to improve the situation. I guess, UUIDs are also a good choice, because they are easy to substitute with pseudo code, eg.:<br />
::* "mount /dev/disks/by-uuid/e9ea05ce-0ccb-87a1-c71e-90fab8be1944 /mnt"<br />
::could then be written as:<br />
::* "/dev/disks/by-uuid/[UUID] /mnt"<br />
::instead of having the choice of:<br />
::* "mount /dev/sda3 '''or''' <br />
::* /dev/mapper/vgroup--lvm-root '''or'''<br />
::* /dev/md/0 '''or'''<br />
::* /dev/md0 '''or''' <br />
::* '''...''' /mnt"<br />
::The reader immediately knows:<br />
::* "I just need to alter [UUID]"<br />
::There is no need to know of all possible alternative methods making use of the Wiki example. Because the user already learned (Beginners Guide) how to determine UUIDs those examples are well adoptable.<br />
::Reduced uncertainties like the reader had before:<br />
::* Can I use that example's local path in my case, too?<br />
::* What's my case anyway? And how is it different for the one provided?<br />
::* Is my drive IDE, SATA or ... what?<br />
::* Where and how is the correct format of my drive/partitions's path?<br />
::* I need an example to boot my USB drive everywhere. That provided example doesn't work for me. Where is the article I need to know?<br />
::* I skimmed through many articles, no success so far. There must be one, but where?<br />
::* I have an Luks, Raid, LVM (or mixed) situation here. The current article just uses /dev/sdi3. What to do?<br />
::* Which article do I need to read first? I can't use the current example. How about alternatives?<br />
::The reader's issue is, that "/dev/sdb3" drive paths aren't that descriptive without the knowledge of how and when they are used as written. They are nice for that particular situation, but may immediately loose their meaning in other use cases?!<br />
::If we could pick out one drive naming method the Wiki uses, then we are able to eliminate many of the upper soliloquies and ...<br />
::* We get a good article structure for the writer, reader and maintainer.<br />
::* The provided method will work in either situation (local/mobile/..).<br />
::* All alternative methods can be listed in '''one''' conversion article/table.<br />
::The reader can quickly move on reading the article:<br />
::* ''Great, I already know how to determine UUIDs. I just change it.''.<br />
::As you mentioned, crosslinks then point to one subpage, where the conversion to other alternative methods is explained.<br />
::Don't get me wrong, I don't want to imply something is wrong with the current way the Wiki does it. This just a natural process how something grows. A bit of standardization may help here.<br />
::I'm for UUIDs so far, because are easily exchangeable and can be written as '''[UUID]''' in the Wiki.<br />
:: OMG, I wrote a huge wall of text. Sorry for that. It's not easy and very time consuming writing down what I wanted to say. as a non-native speaker. I hope, it's now easier to understand what my intention was. I'm kind of uncertain that I found the right words. --[[User:T.ask|T.ask]] ([[User talk:T.ask|talk]]) 13:24, 31 March 2015 (UTC)<br />
<br />
:::Thank you for elaborating on the background of why you propose it. No need to apologize at all for taking the time to give input how to improve our wiki! I just want to add two thoughts on it: <br />
:::(1) One reason descriptive device declarations (/dev/sda/...) are easy to grasp is that everyone is used to them. It starts when you open any partitioning tool - you start it for a device from the /dev tree. Try to find the term "UUID" in the manpage of cfdisk/cgdisk/parted (fdisk has it, the others not a mention). With this I don't want to say your intention to introduce the user early to use persistent naming is wrong, just that using descriptive naming is common and, thereby, accessible to the reader. <br />
:::(2) I like your idea of using a "/dev/disks/by-uuid/[<s>YOUR</s>UUID] /mnt" format (we call other instances of such 'pseudo-variables'). Still, if you used it in an article context, e.g. an encrypted LVM, you would still have to more verbosely describe '''which''' dev/blockdevice/vg/lv UUID is meant to be mounted on /mnt. I still can't really picture for myself how writing and reading it is easier in general. <br />
:::As I wrote above, I agree we might need to pinpoint the advantages of persistent naming more, but we do some already (e.g. right from the start: [[Beginners' guide#Generate an fstab]]). In short I believe we are better off with the way we have it (no rule on it, as long as the contribution fits the article contributed to all editors may choose what's best in context). That's it from me. Looking forward to read feedback & other opinions. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 20:46, 31 March 2015 (UTC)<br />
<br />
::::IMO man page examples are sometimes a bit behind "new standards". That's natural and this shouldn't prevent us from moving a bit more forward. With Arch we have [https://en.wikipedia.org/wiki/Universally_Unique_Identifier UUIDs] - lets use them :)<br />
::::In case the user doesn't know UUIDs, we will guide him/her to a short conversion-table/article on how to switch to UUIDs. Actually it's much easier to grasp than often thought: <br />
::::* Just enter '''lsblk -f''' and it's obvious which UUID points to which drive in any context (raid, luks, lvm, ...). As this [http://dpaste.com/3RYFAPY Get UUID example] shows, just copy the corresponding UUID and use it with all UUID Wiki examples. IMHO it's quite easy.<br />
::::I see where you are coming from, while I'm confident the reader will learn fast how UUIDs work. A new user will not even know which other options have been there before. Moreover, as the reader is already familiar with UUIDs he/she won't experience future problems with moving drives around. The experienced user just reads the conversion-table/article.<br />
::::You see, I'm quite confident that the user will grasp UUIDs easily. Also, this will prevent him/her from experiencing future problems. We just need the courage to do the first step. It's not something we need to do in one day. We have all the time to slowly move into one direction.<br />
::::That's why I would also appreciate other opinions on this topic here.<br />
::::[[User:T.ask|T.ask]] ([[User talk:T.ask|talk]]) 12:45, 1 April 2015 (UTC)<br />
<br />
:::::Hi, T.ask, thank you for discussing this, however I'm not sure if this is all only theoretical or you have a precise idea of how to put it into practice, because after reading all the discussion I haven't understood very well how this idea would change our articles. At this stage you must choose one of our ''important'' articles, e.g. [[LVM]], and explain us how the article would change in details, so we can discuss on something more tangible. — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 14:37, 2 April 2015 (UTC)<br />
<br />
::::::Hi, Kynikos. Yes, it's always better to have a good practical example if things seem to be complicated. I'm quite busy right now. When I find the time, I will start changing the Wiki (slowly) as I mentioned before. [[LVM]] is a nice example, while I would like to start with those sections which are easier to adapt and more commonly used. Especially if I need to add a new subsection (How do you work with UUIDs) beforehand. --[[User:T.ask|T.ask]] ([[User talk:T.ask|talk]]) 10:44, 21 April 2015 (UTC)<br />
<br />
:::::::As I said, it would be better if you showed us an example here or in your User page ''before'' starting to actually "chang[e] the Wiki". Take your time of course :) — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 02:30, 22 April 2015 (UTC)<br />
<br />
=== User and group pacnew files ===<br />
<br />
I just went about handling .pacnew files of {{Pkg|filesystem}} and believe we are missing content for it. It's important, as one can havoc a system mishandling them. Neither [[Users and groups]] nor [[Pacnew and Pacsave files]] mentions it; both should in my view. I'm creating the item here to: <br />
# Check if I missed where it may be mentioned. <br />
# Confirm procedure for handling them: can anyone think of valid reasons/cases in the current situation not to delete passwd/group/shadow.pacnew files? <br />
# Ensure we add it to the relevant places. Opinions? <br />
--[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 12:03, 18 April 2015 (UTC)<br />
<br />
:Well, the user and group database files are handled also from [https://projects.archlinux.org/svntogit/packages.git/tree/trunk/filesystem.install?h=packages/filesystem#n15 filesystem.install] so the only difference I ever got from a .pacnew file was different ordering or (compatible) database format changes. Anyway, I'm wondering as well what is the best way to handle the .pacnew for these 4 files. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:46, 18 April 2015 (UTC)<br />
<br />
::Thanks. Searching the BBS yields a few threads, e.g. [https://bbs.archlinux.org/viewtopic.php?id=194095]. All I saw seem to suggest the files can be deleted. I remember an update where bash path changed; the .pacnew used {{ic|/usr/bin}} while the original still had {{ic|/bin}} path. I guess that would count as an example under "compatible" changes. A manual sorting with ''pwck'' and ''grpck'' could be part of the explanation how to diff the files before deletion. Also ''grpconv'' and ''pwconv'' should be mentioned briefly in my opinion. I added [https://wiki.archlinux.org/index.php?title=Users_and_groups&diff=370749&oldid=368309] and [https://wiki.archlinux.org/index.php?title=Pacnew_and_Pacsave_files&diff=370753&oldid=363010] for now. <br />
::Anyone has input for (2.) or (3.) above? --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 09:33, 23 April 2015 (UTC)<br />
<br />
=== FAQ ===<br />
<br />
The [[FAQ]] could use an entry like "After upgrading my kernel, I can't mount USB devices", preferably linking {{Bug|16702}}. See [https://wiki.archlinux.org/index.php?title=VirtualBox&curid=3745&diff=400434&oldid=400154] for a case where users are not aware of this. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 22:55, 18 September 2015 (UTC)<br />
<br />
:+1, but I'd place it into [[General troubleshooting]]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:52, 19 September 2015 (UTC)<br />
<br />
=== Pacman hooks ===<br />
<br />
Hooks support is mandatory as of 2016-04-23 [https://www.archlinux.org/news/required-update-to-pacman-501-before-2016-04-23/], and {{ic|.install}} files in the repos are gradually being outphased: see [[DeveloperWiki:Pacman Hooks]] -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 15:32, 29 April 2016 (UTC)<br />
<br />
== Bot requests ==<br />
<br />
''Here, list requests for repetitive, systemic modifications to a series of existing articles to be performed by a wiki bot.''</div>Alive4everhttps://wiki.archlinux.org/index.php?title=Windows_PE&diff=442316Windows PE2016-07-21T09:55:31Z<p>Alive4ever: /* From Network */ memdisk only works for bios systems, for uefi system wimboot+iPXE is needed</p>
<hr />
<div>[[Category:System administration]]<br />
[[ja:Windows PE]]<br />
[http://technet.microsoft.com/en-us/library/cc766093(v=ws.10).aspx Windows PE] is a lightweight version of Windows intended to be used for installation of Windows Vista and later versions of Windows, as well as for system maintenance. It runs entirely from memory and can be booted from the network. This page describes how customized Windows PE images can be created, and optionally published on the network, using only free software packages on an Arch Linux machine along with Microsoft's Windows Automated Installation Kit (WAIK). The WAIK can be downloaded at no cost and is only needed to extract the {{ic|boot.wim}} file that contains the initial copy of Windows PE, along with a couple boot files.<br />
<br />
{{Warning|<br />
If you boot Windows PE on a physical computer, you are placing Microsoft's closed-source code in control of that computer. You do so at your own risk.<br />
<br />
In addition, by downloading the Windows Automated Installation Kit, you may be bound by its license, which prevents you from, among other things, using Windows PE as a general-purpose operating system.<br />
}}<br />
<br />
== Use cases ==<br />
<br />
Normally, an image of Windows PE can only be created using the Windows Automated Installation Kit (WAIK) on a Windows machine. However, it is also possible to create and modify images of Windows PE using an (Arch) Linux machine, and optionally publish them on the network for PXE booting. No Windows machine is necessary. You may want to do this if:<br />
<br />
* you need to install Windows from the network, or boot Windows PE from the network for system administration, using an Arch Linux-based server. This may be because you do not have a Windows-based server, or you prefer using a Linux server because of its improved security and configurability, or you are already using a Linux server for other purposes.<br />
* you need to run a Windows environment to run Win32 programs, you do not have a Windows machine available, and you do not want to use [[Wine]] or the programs will not run correctly with [[Wine]].<br />
<br />
== Creating a bootable Windows PE ISO ==<br />
<br />
Download the Windows Automated Installation Kit (WAIK) from [http://www.microsoft.com/en-us/download/details.aspx?id=5753 Microsoft's website].<br />
{{Warning|The entire download, {{ic|KB3AIK_EN.iso}}, is 1.7GB.}}<br />
{{Tip|<br />
* It may be possible to use [http://httpfs.sourceforge.net/ httpfs] to avoid downloading the entire file. Only around 118MB of it is actually needed.<br />
* If you have an installation media of Windows 7 or later versions, you can use that iso file / optical disc instead of WAIK. {{ic|mkwinpeimg}} accepts both WAIK image and Windows installation media. Note that different versions of Windows installation media contains different versions of Windows PE. For the relationship between Windows versions and Windows PE versions, refer to [[wikipedia:Windows_Preinstallation_Environment#Versions|Wikipedia]].<br />
* WAIK has been renamed to WADK since Windows 8 and is now distributed via {{ic|adksetup.exe}}. In order to get Windows PE 4.0 and later versions, you have to use installation media of Windows 8 and later versions. The installation media iso files are avaiable for MSDN subscribers, but you can download otherwhere and compare the hash value with the those published on MSDN.<br />
}}<br />
<br />
[[Install]] {{Pkg|fuse}}, {{Pkg|cdrkit}}, and {{Pkg|cabextract}} from [[official repositories]].<br />
<br />
Install {{AUR|wimlib}} from the [[AUR]].<br />
<br />
Mount the WAIK ISO:<br />
<br />
# mkdir /media/waik<br />
# mount KB3AIK_EN.iso /media/waik<br />
<br />
Use the {{ic|mkwinpeimg}} script provided with {{AUR|wimlib}} to create a bootable Windows PE ISO {{ic|winpe.iso}}:<br />
<br />
$ mkwinpeimg --iso --waik-dir=/media/waik winpe.iso<br />
<br />
See the {{ic|man mkwinpeimg}} for more information.<br />
<br />
Unmount the WAIK ISO:<br />
<br />
# umount /media/waik<br />
<br />
== Booting Windows PE ==<br />
<br />
After creating a bootable ISO of Windows PE ({{ic|winpe.iso}}) as described in the previous section, you may want to boot Windows PE in the following ways:<br />
<br />
=== In virtual machine ===<br />
<br />
Run a virtual machine with {{ic|winpe.iso}} attached as a CD-ROM. Be sure to give it adequate memory, definitely more than the size of the ISO, since Windows PE runs from memory. See [[:Category:Hypervisors]] for a list of available virtualization software.<br />
<br />
=== From CD ===<br />
<br />
Simply [[Optical disc drive#Burning|burn]] {{ic|winpe.iso}} onto a CD, and you can boot from it.<br />
<br />
=== From Network ===<br />
<br />
{{Merge|PXE|The PXE article already describes most of this stuff, no need for duplication. Also rc.d? Just make sure that configuration file is not lost if it's necessary for windows. Besides that everything is dupe.}}<br />
<br />
Windows PE can be booted from the network using [http://www.syslinux.org/wiki/index.php/PXELINUX PXELINUX] and its [http://www.syslinux.org/wiki/index.php/MEMDISK MEMDISK] module on BIOS systems. For UEFI systems, [http://ipxe.org/wimboot wimboot] and [http://ipxe.org iPXE] can be used.<br />
<br />
Install {{pkg|syslinux}} and {{pkg|tftp-hpa}}.<br />
<br />
Copy needed PXELINUX files to the [[Tftpd server|TFTP server]] root directory.<br />
<br />
# cp /usr/lib/syslinux/{pxelinux.0,menu.c32,memdisk} /var/tftpboot<br />
<br />
Put {{ic|winpe.iso}} in the [[Tftpd server|TFTP server]] root directory.<br />
<br />
# mv winpe.iso /var/tftpboot<br />
<br />
Create a [[Syslinux#Configuring_syslinux|configuration file]] for PXELINUX similar to the following:<br />
<br />
{{hc|/var/tftpboot/pxelinux.cfg/default|<nowiki><br />
UI menu.c32<br />
MENU TITLE Network Boot<br />
TIMEOUT 50<br />
<br />
LABEL winpe<br />
MENU LABEL Boot Windows PE from network<br />
KERNEL /memdisk<br />
INITRD winpe.iso<br />
APPEND iso raw<br />
<br />
LABEL localboot<br />
MENU LABEL Boot from local disk<br />
LOCALBOOT 0<br />
</nowiki><br />
}}<br />
<br />
Start the [[Tftpd server|TFTP server]].<br />
<br />
Configure your DHCP server (such as [[Dhcpd]] or [[Dnsmasq]]) to point to {{ic|pxelinux.0}} as the boot file, with the Linux server's IP address. Beware: if your DHCP server is on a router, it may not be possible to do this without installing custom firmware.<br />
<br />
After completing the above steps, you should be able to boot Windows PE from the network.<br />
<br />
{{Note|With the given PXELINUX configuration file, Windows PE will start by default after 5 seconds.}}<br />
<br />
=== Network boot performance ===<br />
<br />
TFTP is not designed to be used to transfer large files, such as {{ic|winpe.iso}}, which may be 118MB or more. Performance may be improved by using the {{ic|gpxelinux.0}} bootloader instead of {{ic|pxelinux.0}} and loading {{ic|winpe.iso}} using HTTP rather than TFTP.<br />
<br />
== Customizing Windows PE ==<br />
<br />
The {{ic|mkwinpeimg}} script provided with {{AUR|wimlib}} supports making modifications to Windows PE using the {{ic|--start-script}} or {{ic|--overlay}} options. See the manual page for {{ic|mkwinpeimg}} for more information.<br />
<br />
You may want to do this to add additional Windows applications that you want to run in Windows PE, or to add any additional drivers that Windows PE needs (drivers can be loaded using the {{ic|drvload}} command within Windows PE).<br />
<br />
==See also==<br />
<br />
* [http://technet.microsoft.com/en-us/library/cc766093(v=ws.10).aspx Microsoft's documentation for Windows PE]<br />
* [http://www.thinkwiki.org/wiki/Windows_PE Another article about making Windows PE images on Linux]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=Dnsmasq&diff=442246Dnsmasq2016-07-20T10:20:04Z<p>Alive4ever: /* PXE setup */ Add RFC4578 source for dhcp boot client-arch numbering</p>
<hr />
<div>{{Lowercase_title}}<br />
[[Category:Domain Name System]]<br />
[[es:Dnsmasq]]<br />
[[it:Dnsmasq]]<br />
[[ja:Dnsmasq]]<br />
[[pt:Dnsmasq]]<br />
[[ru:Dnsmasq]]<br />
[[zh-CN:Dnsmasq]]<br />
<br />
[http://www.thekelleys.org.uk/dnsmasq/doc.html dnsmasq] provides services as a DNS cacher and a DHCP server. As a Domain Name Server (DNS) it can cache DNS queries to improve connection speeds to previously visited sites, and as a DHCP server dnsmasq can be used to provide internal IP addresses and routes to computers on a LAN. Either or both of these services can be implemented. dnsmasq is considered to be lightweight and easy to configure; it is designed for personal computer use or for use on a network with less than 50 computers. It also comes with a [[PXE]] server.<br />
<br />
== Installation ==<br />
<br />
[[Install]] {{Pkg|dnsmasq}}.<br />
<br />
== Configuration ==<br />
<br />
To configure dnsmasq, you need to edit {{ic|/etc/dnsmasq.conf}}. The file contains extensive comments explaining its options. <br />
<br />
{{Warning|dnsmasq by default enables its DNS server. If you do not require it, you need to explicitly disable it by setting DNS port to {{ic|0}}:<br />
{{hc|/etc/dnsmasq.conf|2=port=0}}<br />
}}<br />
<br />
{{Tip|To check configuration file(s) syntax, execute:<br />
$ dnsmasq --test<br />
}}<br />
<br />
== DNS cache setup ==<br />
<br />
To set up dnsmasq as a DNS caching daemon on a single computer edit {{ic|/etc/dnsmasq.conf}} and uncomment the {{ic|listen-address}} directive, adding in the localhost IP address:<br />
<br />
listen-address=127.0.0.1<br />
<br />
To use this computer to listen on its LAN IP address for other computers on the network:<br />
<br />
listen-address=192.168.1.1 # Example IP<br />
<br />
It is recommended that you use a static LAN IP in this case.<br />
<br />
Multiple ip address settings:<br />
<br />
listen-address=127.0.0.1,192.168.1.1 <br />
<br />
=== DNS addresses file ===<br />
<br />
{{Merge|resolv.conf|Same topic. Also note that most of this can also be done natively in {{ic|/etc/resolvconf.conf}} using the {{ic|name_servers}} and {{ic|name_servers_append}} options.}}<br />
<br />
After configuring dnsmasq, the DHCP client will need to prepend the localhost address to the known DNS addresses in {{ic|/etc/resolv.conf}}. This causes all queries to be sent to dnsmasq before trying to resolve them with an external DNS. After the DHCP client is configured, the network will need to be restarted for changes to take effect.<br />
<br />
==== resolv.conf ====<br />
<br />
One option is a pure {{ic|resolv.conf}} configuration. To do this, just make the first nameserver in {{ic|/etc/resolv.conf}} point to localhost:<br />
<br />
{{hc|/etc/resolv.conf|<br />
nameserver 127.0.0.1<br />
# External nameservers<br />
...<br />
}}<br />
<br />
Now DNS queries will be resolved first with dnsmasq, only checking external servers if dnsmasq cannot resolve the query. {{Pkg|dhcpcd}}, unfortunately, tends to overwrite {{ic|/etc/resolv.conf}} by default, so if you use DHCP it is a good idea to protect {{ic|/etc/resolv.conf}}. To do this, append {{ic|nohook resolv.conf}} to the dhcpcd config file:<br />
<br />
{{hc|/etc/dhcpcd.conf|<br />
...<br />
nohook resolv.conf}}<br />
<br />
It is also possible to write protect your resolv.conf:<br />
<br />
# chattr +i /etc/resolv.conf<br />
<br />
===== More than three nameservers =====<br />
<br />
A limitation in the way Linux handles DNS queries is that there can only be a maximum of three nameservers used in {{ic|resolv.conf}}. As a workaround, you can make localhost the only nameserver in {{ic|resolv.conf}}, and then create a separate {{ic|resolv-file}} for your external nameservers. First, create a new resolv file for dnsmasq:<br />
<br />
{{hc|/etc/resolv.dnsmasq.conf|<br />
# Google's nameservers, for example<br />
nameserver 8.8.8.8<br />
nameserver 8.8.4.4<br />
}}<br />
<br />
And then edit {{ic|/etc/dnsmasq.conf}} to use your new resolv file:<br />
<br />
{{hc|/etc/dnsmasq.conf|<br />
...<br />
resolv-file&#61;/etc/resolv.dnsmasq.conf<br />
...<br />
}}<br />
<br />
==== dhcpcd ====<br />
<br />
[[dhcpcd]] has the ability to prepend or append nameservers to {{ic|/etc/resolv.conf}} by creating (or editing) the {{ic|/etc/resolv.conf.head}} and {{ic|/etc/resolv.conf.tail}} files respectively:<br />
<br />
echo "nameserver 127.0.0.1" > /etc/resolv.conf.head<br />
<br />
==== dhclient ====<br />
<br />
For {{Pkg|dhclient}}, uncomment in {{ic|/etc/dhclient.conf}}:<br />
<br />
prepend domain-name-servers 127.0.0.1;<br />
<br />
=== NetworkManager ===<br />
DNS requests can be sped up by caching previous requests locally for subsequent lookup. [[NetworkManager]] has a plugin to enable DNS caching using dnsmasq, but it is not enabled in the default configuration. <br />
<br />
Make sure {{Pkg|dnsmasq}} has been installed, but has been disabled. Then, edit {{ic|/etc/NetworkManager/NetworkManager.conf}} and change the {{ic|dns}} in the {{ic|[main]}} section:<br />
{{hc|/etc/NetworkManager/NetworkManager.conf|<nowiki><br />
[main]<br />
...<br />
dns=dnsmasq<br />
</nowiki>}}<br />
<br />
Now restart NetworkManager or reboot. NetworkManager will automatically start dnsmasq and add 127.0.0.1 to {{ic|/etc/resolv.conf}}. The actual DNS servers can be found in {{ic|/run/NetworkManager/dnsmasq.conf}}. You can verify dnsmasq is being used by doing the same DNS lookup twice with {{ic|$ dig example.com}} that can be installed with {{Pkg|bind-tools}} and verifying the server and query times.<br />
<br />
==== Usage with libvirt ====<br />
<br />
Network-manager think if there is one running libvirt that he run this before. To fix conflicts between other dnsmasq, eg: used in [[libvirt]], you must run it externally.<br />
<br />
We do '''not''' want change our resolv.conf automaticly.<br />
<br />
{{hc|/etc/NetworkManager/NetworkManager.conf|<nowiki><br />
[main]<br />
...<br />
dns=none<br />
</nowiki>}}<br />
<br />
We put it manually here.<br />
<br />
{{hc|/etc/resolv.conf.head|2=<br />
nameserver 127.0.0.1<br />
}}<br />
<br />
The interface to bind and bind it even if there is second dnsmasq runned on computer.<br />
<br />
{{hc|/etc/NetworkManager/dnsmasq.d/bind-interface.conf|2=<br />
interface=lo<br />
bind-interface<br />
}}<br />
<br />
This start service if interface is up. This service can start only once before stop which will be initiate by systemd on restart/shutdown.<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/10_dnsmasq|2=<br />
#!/bin/sh<br />
if [ -n "$2" ] && [ "$2" = "up" ]; then # $INTERFACE is up<br />
systemctl start NetworkManager-dnsmasq.service<br />
fi<br />
}}<br />
<br />
Systemd service.<br />
<br />
{{hc|/etc/systemd/system/NetworkManager-dnsmasq.service|2=<br />
[Unit]<br />
Description=A lightweight DHCP and caching DNS server<br />
After=network.target<br />
Documentation=man:dnsmasq(8)<br />
<br />
[Service]<br />
Type=dbus<br />
BusName=uk.org.thekelleys.dnsmasq<br />
ExecStartPre=/usr/bin/dnsmasq --test<br />
ExecStart=/usr/bin/dnsmasq -k --enable-dbus --user=dnsmasq --pid-file --conf-dir=/etc/NetworkManager/dnsmasq.d/<br />
ExecReload=/bin/kill -HUP $MAINPID<br />
}}<br />
<br />
==== Custom configuration ====<br />
Custom configurations can be created for ''dnsmasq'' by creating configuration files in {{ic|/etc/NetworkManager/dnsmasq.d/}}. For example, to change the size of the DNS cache (which is stored in RAM):<br />
<br />
{{hc|/etc/NetworkManager/dnsmasq.d/cache.conf|2=<br />
cache-size=1000<br />
}}<br />
<br />
==== IPv6 ====<br />
<br />
Enabling {{ic|dnsmasq}} in NetworkManager may break IPv6-only DNS lookups (i.e. {{ic|dig -6 [hostname]}}) which would otherwise work. In order to resolve this, creating the following file will configure ''dnsmasq'' to also listen to the IPv6 loopback:<br />
<br />
{{hc|/etc/NetworkManager/dnsmasq.d/ipv6_listen.conf|2=<br />
listen-address=::1<br />
}}<br />
In addition, {{ic|dnsmasq}} also does not prioritize upstream IPv6 DNS. Unfortunately NetworkManager does not do this ([https://bugs.launchpad.net/ubuntu/+source/network-manager/+bug/936712 Ubuntu Bug]). A workaround would be to disable IPv4 DNS in the NetworkManager config, assuming one exists<br />
<br />
==== Other methods ====<br />
<br />
Another option is in NetworkManagers' settings (usually by right-clicking the applet) and entering settings manually. Setting up will depending on the type of front-end used; the process usually involves right-clicking on the applet, editing (or creating) a profile, and then choosing DHCP type as 'Automatic (specify addresses).' The DNS addresses will need to be entered and are usually in this form: {{ic|127.0.0.1, DNS-server-one, ...}}.<br />
<br />
=== Test ===<br />
<br />
To do a lookup speed test choose a website that has not been visited since dnsmasq has been started (''dig'' is part of the {{Pkg|bind-tools}} package):<br />
<br />
$ dig archlinux.org | grep "Query time"<br />
<br />
Running the command again will use the cached DNS IP and result in a faster lookup time if dnsmasq is setup correctly:<br />
<br />
{{hc|<nowiki>$ dig archlinux.org | grep "Query time"</nowiki>|<br />
;; Query time: 18 msec<br />
}}<br />
<br />
{{hc|<nowiki>$ dig archlinux.org | grep "Query time"</nowiki>|<br />
;; Query time: 2 msec<br />
}}<br />
<br />
== DHCP server setup ==<br />
<br />
By default dnsmasq has the DHCP functionality turned off, if you want to use it you must turn it on in ({{ic|/etc/dnsmasq.conf}}). Here are the important settings:<br />
<br />
{{bc|<nowiki><br />
# Only listen to routers' LAN NIC. Doing so opens up tcp/udp port 53 to<br />
# localhost and udp port 67 to world:<br />
interface=<LAN-NIC><br />
<br />
# dnsmasq will open tcp/udp port 53 and udp port 67 to world to help with<br />
# dynamic interfaces (assigning dynamic ips). Dnsmasq will discard world<br />
# requests to them, but the paranoid might like to close them and let the <br />
# kernel handle them:<br />
bind-interfaces<br />
<br />
# Dynamic range of IPs to make available to LAN pc<br />
dhcp-range=192.168.111.50,192.168.111.100,12h<br />
<br />
# If you’d like to have dnsmasq assign static IPs, bind the LAN computer's<br />
# NIC MAC address:<br />
dhcp-host=aa:bb:cc:dd:ee:ff,192.168.111.50<br />
</nowiki>}}<br />
<br />
=== Test ===<br />
<br />
From a computer that is connected to the one with dnsmasq on it, configure it to use DHCP for automatic IP address assignment, then attempt to log into the network normally.<br />
<br />
== TFTP server setup ==<br />
<br />
Create a directory for TFTP root (e.g. {{ic|/srv/tftp}}) to put transferable files in.<br />
<br />
To use dnsmasq's TFTP secure mode [[chown]] TFTP root and all files in it to {{ic|dnsmasq}} user.<br />
<br />
Enable TFTP in {{ic|dnsmasq.conf}}<br />
{{hc|/etc/dnsmasq.conf|<nowiki><br />
enable-tftp<br />
tftp-root=/srv/tftp<br />
tftp-secure<br />
</nowiki>}}<br />
<br />
== PXE setup ==<br />
<br />
PXE requires DHCP and TFTP servers, both functions can be provided by dnsmasq.<br />
<br />
{{Tip|dnsmasq can add PXE booting options to a network with an already running DHCP server:<br />
{{hc|/etc/dnsmasq.conf|2=<br />
interface=''enp0s0''<br />
bind-dynamic<br />
dhcp-range=''192.168.0.1'',proxy}}<br />
}}<br />
<br />
# set up [[#TFTP server setup|TFTP server]] and [[#DHCP server setup|DHCP server]]<br />
# copy and configure a PXE compatible bootloader (e.g. [[Syslinux#Pxelinux|PXELINUX]]) on TFTP root<br />
# enable PXE in {{ic|/etc/dnsmasq.conf}}:<br />
{{Note|<br />
*file paths are relative to TFTP root<br />
*if the file has a {{ic|.0}} suffix, you must exclude the suffix in {{ic|pxe-service}} options<br />
}}<br />
To simply send one file:<br />
dhcp-boot=lpxelinux.0<br />
To send a file depending on client architecture:<br />
pxe-service=x86PC, "PXELINUX (BIOS)", "bios/lpxelinux"<br />
pxe-service=X86-64_EFI, "PXELINUX (EFI)", "efi64/syslinux.efi"<br />
<br />
{{Note|In case {{ic|pxe-service}} doesn't work (especially for UEFI-based clients), combination of {{ic|dhcp-match}} and {{ic|dhcp-boot}} can be used. See [https://tools.ietf.org/html/rfc4578#section-2.1 RFC4578] for more {{ic|client-arch}} numbers for use with dhcp boot protocol.}}<br />
dhcp-match=set:efi-x86_64,option:client-arch,7<br />
dhcp-match=set:efi-x86_64,option:client-arch,9<br />
dhcp-match=set:efi-x86,option:client-arch,6<br />
dhcp-match=set:bios,option:client-arch,0<br />
dhcp-boot=tag:efi-x86_64,"efi64/syslinux.efi"<br />
dhcp-boot=tag:efi-x86,"efi32/syslinux.efi"<br />
dhcp-boot=tag:bios,"bios/lpxelinux.0"<br />
<br />
<br />
<br />
The rest is up to the bootloader.<br />
<br />
== Start the daemon ==<br />
<br />
[[Start/enable]] {{ic|dnsmasq.service}}.<br />
<br />
To see if dnsmasq started properly, check the system's journal:<br />
<br />
{{bc|$ journalctl -u dnsmasq}}<br />
<br />
The network will also need to be restarted so the DHCP client can create a new {{ic|/etc/resolv.conf}}.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Prevent OpenDNS redirecting Google queries ===<br />
<br />
To prevent OpenDNS from redirecting all Google queries to their own search server, add to {{ic|/etc/dnsmasq.conf}}:<br />
{{bc|1=server=/www.google.com/<ISP DNS IP>}}<br />
<br />
=== View leases ===<br />
{{bc|$ cat /var/lib/misc/dnsmasq.leases}}<br />
<br />
=== Adding a custom domain ===<br />
It is possible to add a custom domain to hosts in your (local) network:<br />
local=/home.lan/<br />
domain=home.lan<br />
<br />
In this example it is possible to ping a host/device (e.g. defined in your hosts file) as {{ic|hostname.home.lan}}.<br />
<br />
Uncomment {{ic|expand-hosts}} to add the custom domain to hosts entries:<br />
expand-hosts<br />
Without this setting, you'll have to add the domain to entries of /etc/hosts.<br />
<br />
=== Override addresses ===<br />
<br />
In some cases, such as when operating a captive portal, it can be useful to resolve specific domains names to a hard-coded set of addresses. This is done with the {{ic|address}} config:<br />
<br />
address=/example.com/1.2.3.4<br />
<br />
Furthermore, it's possible to return a specific address for all domain names that are not answered from {{ic|/etc/hosts}} or DHCP by using a special wildcard:<br />
<br />
address=/#/1.2.3.4<br />
<br />
=== More than one instance ===<br />
<br />
If we want two or more dnsmasq servers works per interface(s).<br />
<br />
==== Static ====<br />
<br />
To do this staticly, server per interface, use {{ic|interface}} and {{ic|bind-interface}} options. This enforce start second dnsmasq.<br />
<br />
==== Dynamic ====<br />
<br />
In this case we can exclude per interface and bind any others:<br />
<br />
except-interface=lo<br />
bind-dynamic<br />
<br />
{{Note|This is default in libvirt.}}<br />
<br />
== See also ==<br />
<br />
* [http://www.g-loaded.eu/2010/09/18/caching-nameserver-using-dnsmasq/ Caching Nameserver using dnsmasq, and a few other tips and tricks.]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=Dnsmasq&diff=442245Dnsmasq2016-07-20T10:04:27Z<p>Alive4ever: /* PXE setup */ pxe-service doesn't always work (especially for UEFI client), use dhcp-match and dhcp-boot combination as workaround</p>
<hr />
<div>{{Lowercase_title}}<br />
[[Category:Domain Name System]]<br />
[[es:Dnsmasq]]<br />
[[it:Dnsmasq]]<br />
[[ja:Dnsmasq]]<br />
[[pt:Dnsmasq]]<br />
[[ru:Dnsmasq]]<br />
[[zh-CN:Dnsmasq]]<br />
<br />
[http://www.thekelleys.org.uk/dnsmasq/doc.html dnsmasq] provides services as a DNS cacher and a DHCP server. As a Domain Name Server (DNS) it can cache DNS queries to improve connection speeds to previously visited sites, and as a DHCP server dnsmasq can be used to provide internal IP addresses and routes to computers on a LAN. Either or both of these services can be implemented. dnsmasq is considered to be lightweight and easy to configure; it is designed for personal computer use or for use on a network with less than 50 computers. It also comes with a [[PXE]] server.<br />
<br />
== Installation ==<br />
<br />
[[Install]] {{Pkg|dnsmasq}}.<br />
<br />
== Configuration ==<br />
<br />
To configure dnsmasq, you need to edit {{ic|/etc/dnsmasq.conf}}. The file contains extensive comments explaining its options. <br />
<br />
{{Warning|dnsmasq by default enables its DNS server. If you do not require it, you need to explicitly disable it by setting DNS port to {{ic|0}}:<br />
{{hc|/etc/dnsmasq.conf|2=port=0}}<br />
}}<br />
<br />
{{Tip|To check configuration file(s) syntax, execute:<br />
$ dnsmasq --test<br />
}}<br />
<br />
== DNS cache setup ==<br />
<br />
To set up dnsmasq as a DNS caching daemon on a single computer edit {{ic|/etc/dnsmasq.conf}} and uncomment the {{ic|listen-address}} directive, adding in the localhost IP address:<br />
<br />
listen-address=127.0.0.1<br />
<br />
To use this computer to listen on its LAN IP address for other computers on the network:<br />
<br />
listen-address=192.168.1.1 # Example IP<br />
<br />
It is recommended that you use a static LAN IP in this case.<br />
<br />
Multiple ip address settings:<br />
<br />
listen-address=127.0.0.1,192.168.1.1 <br />
<br />
=== DNS addresses file ===<br />
<br />
{{Merge|resolv.conf|Same topic. Also note that most of this can also be done natively in {{ic|/etc/resolvconf.conf}} using the {{ic|name_servers}} and {{ic|name_servers_append}} options.}}<br />
<br />
After configuring dnsmasq, the DHCP client will need to prepend the localhost address to the known DNS addresses in {{ic|/etc/resolv.conf}}. This causes all queries to be sent to dnsmasq before trying to resolve them with an external DNS. After the DHCP client is configured, the network will need to be restarted for changes to take effect.<br />
<br />
==== resolv.conf ====<br />
<br />
One option is a pure {{ic|resolv.conf}} configuration. To do this, just make the first nameserver in {{ic|/etc/resolv.conf}} point to localhost:<br />
<br />
{{hc|/etc/resolv.conf|<br />
nameserver 127.0.0.1<br />
# External nameservers<br />
...<br />
}}<br />
<br />
Now DNS queries will be resolved first with dnsmasq, only checking external servers if dnsmasq cannot resolve the query. {{Pkg|dhcpcd}}, unfortunately, tends to overwrite {{ic|/etc/resolv.conf}} by default, so if you use DHCP it is a good idea to protect {{ic|/etc/resolv.conf}}. To do this, append {{ic|nohook resolv.conf}} to the dhcpcd config file:<br />
<br />
{{hc|/etc/dhcpcd.conf|<br />
...<br />
nohook resolv.conf}}<br />
<br />
It is also possible to write protect your resolv.conf:<br />
<br />
# chattr +i /etc/resolv.conf<br />
<br />
===== More than three nameservers =====<br />
<br />
A limitation in the way Linux handles DNS queries is that there can only be a maximum of three nameservers used in {{ic|resolv.conf}}. As a workaround, you can make localhost the only nameserver in {{ic|resolv.conf}}, and then create a separate {{ic|resolv-file}} for your external nameservers. First, create a new resolv file for dnsmasq:<br />
<br />
{{hc|/etc/resolv.dnsmasq.conf|<br />
# Google's nameservers, for example<br />
nameserver 8.8.8.8<br />
nameserver 8.8.4.4<br />
}}<br />
<br />
And then edit {{ic|/etc/dnsmasq.conf}} to use your new resolv file:<br />
<br />
{{hc|/etc/dnsmasq.conf|<br />
...<br />
resolv-file&#61;/etc/resolv.dnsmasq.conf<br />
...<br />
}}<br />
<br />
==== dhcpcd ====<br />
<br />
[[dhcpcd]] has the ability to prepend or append nameservers to {{ic|/etc/resolv.conf}} by creating (or editing) the {{ic|/etc/resolv.conf.head}} and {{ic|/etc/resolv.conf.tail}} files respectively:<br />
<br />
echo "nameserver 127.0.0.1" > /etc/resolv.conf.head<br />
<br />
==== dhclient ====<br />
<br />
For {{Pkg|dhclient}}, uncomment in {{ic|/etc/dhclient.conf}}:<br />
<br />
prepend domain-name-servers 127.0.0.1;<br />
<br />
=== NetworkManager ===<br />
DNS requests can be sped up by caching previous requests locally for subsequent lookup. [[NetworkManager]] has a plugin to enable DNS caching using dnsmasq, but it is not enabled in the default configuration. <br />
<br />
Make sure {{Pkg|dnsmasq}} has been installed, but has been disabled. Then, edit {{ic|/etc/NetworkManager/NetworkManager.conf}} and change the {{ic|dns}} in the {{ic|[main]}} section:<br />
{{hc|/etc/NetworkManager/NetworkManager.conf|<nowiki><br />
[main]<br />
...<br />
dns=dnsmasq<br />
</nowiki>}}<br />
<br />
Now restart NetworkManager or reboot. NetworkManager will automatically start dnsmasq and add 127.0.0.1 to {{ic|/etc/resolv.conf}}. The actual DNS servers can be found in {{ic|/run/NetworkManager/dnsmasq.conf}}. You can verify dnsmasq is being used by doing the same DNS lookup twice with {{ic|$ dig example.com}} that can be installed with {{Pkg|bind-tools}} and verifying the server and query times.<br />
<br />
==== Usage with libvirt ====<br />
<br />
Network-manager think if there is one running libvirt that he run this before. To fix conflicts between other dnsmasq, eg: used in [[libvirt]], you must run it externally.<br />
<br />
We do '''not''' want change our resolv.conf automaticly.<br />
<br />
{{hc|/etc/NetworkManager/NetworkManager.conf|<nowiki><br />
[main]<br />
...<br />
dns=none<br />
</nowiki>}}<br />
<br />
We put it manually here.<br />
<br />
{{hc|/etc/resolv.conf.head|2=<br />
nameserver 127.0.0.1<br />
}}<br />
<br />
The interface to bind and bind it even if there is second dnsmasq runned on computer.<br />
<br />
{{hc|/etc/NetworkManager/dnsmasq.d/bind-interface.conf|2=<br />
interface=lo<br />
bind-interface<br />
}}<br />
<br />
This start service if interface is up. This service can start only once before stop which will be initiate by systemd on restart/shutdown.<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/10_dnsmasq|2=<br />
#!/bin/sh<br />
if [ -n "$2" ] && [ "$2" = "up" ]; then # $INTERFACE is up<br />
systemctl start NetworkManager-dnsmasq.service<br />
fi<br />
}}<br />
<br />
Systemd service.<br />
<br />
{{hc|/etc/systemd/system/NetworkManager-dnsmasq.service|2=<br />
[Unit]<br />
Description=A lightweight DHCP and caching DNS server<br />
After=network.target<br />
Documentation=man:dnsmasq(8)<br />
<br />
[Service]<br />
Type=dbus<br />
BusName=uk.org.thekelleys.dnsmasq<br />
ExecStartPre=/usr/bin/dnsmasq --test<br />
ExecStart=/usr/bin/dnsmasq -k --enable-dbus --user=dnsmasq --pid-file --conf-dir=/etc/NetworkManager/dnsmasq.d/<br />
ExecReload=/bin/kill -HUP $MAINPID<br />
}}<br />
<br />
==== Custom configuration ====<br />
Custom configurations can be created for ''dnsmasq'' by creating configuration files in {{ic|/etc/NetworkManager/dnsmasq.d/}}. For example, to change the size of the DNS cache (which is stored in RAM):<br />
<br />
{{hc|/etc/NetworkManager/dnsmasq.d/cache.conf|2=<br />
cache-size=1000<br />
}}<br />
<br />
==== IPv6 ====<br />
<br />
Enabling {{ic|dnsmasq}} in NetworkManager may break IPv6-only DNS lookups (i.e. {{ic|dig -6 [hostname]}}) which would otherwise work. In order to resolve this, creating the following file will configure ''dnsmasq'' to also listen to the IPv6 loopback:<br />
<br />
{{hc|/etc/NetworkManager/dnsmasq.d/ipv6_listen.conf|2=<br />
listen-address=::1<br />
}}<br />
In addition, {{ic|dnsmasq}} also does not prioritize upstream IPv6 DNS. Unfortunately NetworkManager does not do this ([https://bugs.launchpad.net/ubuntu/+source/network-manager/+bug/936712 Ubuntu Bug]). A workaround would be to disable IPv4 DNS in the NetworkManager config, assuming one exists<br />
<br />
==== Other methods ====<br />
<br />
Another option is in NetworkManagers' settings (usually by right-clicking the applet) and entering settings manually. Setting up will depending on the type of front-end used; the process usually involves right-clicking on the applet, editing (or creating) a profile, and then choosing DHCP type as 'Automatic (specify addresses).' The DNS addresses will need to be entered and are usually in this form: {{ic|127.0.0.1, DNS-server-one, ...}}.<br />
<br />
=== Test ===<br />
<br />
To do a lookup speed test choose a website that has not been visited since dnsmasq has been started (''dig'' is part of the {{Pkg|bind-tools}} package):<br />
<br />
$ dig archlinux.org | grep "Query time"<br />
<br />
Running the command again will use the cached DNS IP and result in a faster lookup time if dnsmasq is setup correctly:<br />
<br />
{{hc|<nowiki>$ dig archlinux.org | grep "Query time"</nowiki>|<br />
;; Query time: 18 msec<br />
}}<br />
<br />
{{hc|<nowiki>$ dig archlinux.org | grep "Query time"</nowiki>|<br />
;; Query time: 2 msec<br />
}}<br />
<br />
== DHCP server setup ==<br />
<br />
By default dnsmasq has the DHCP functionality turned off, if you want to use it you must turn it on in ({{ic|/etc/dnsmasq.conf}}). Here are the important settings:<br />
<br />
{{bc|<nowiki><br />
# Only listen to routers' LAN NIC. Doing so opens up tcp/udp port 53 to<br />
# localhost and udp port 67 to world:<br />
interface=<LAN-NIC><br />
<br />
# dnsmasq will open tcp/udp port 53 and udp port 67 to world to help with<br />
# dynamic interfaces (assigning dynamic ips). Dnsmasq will discard world<br />
# requests to them, but the paranoid might like to close them and let the <br />
# kernel handle them:<br />
bind-interfaces<br />
<br />
# Dynamic range of IPs to make available to LAN pc<br />
dhcp-range=192.168.111.50,192.168.111.100,12h<br />
<br />
# If you’d like to have dnsmasq assign static IPs, bind the LAN computer's<br />
# NIC MAC address:<br />
dhcp-host=aa:bb:cc:dd:ee:ff,192.168.111.50<br />
</nowiki>}}<br />
<br />
=== Test ===<br />
<br />
From a computer that is connected to the one with dnsmasq on it, configure it to use DHCP for automatic IP address assignment, then attempt to log into the network normally.<br />
<br />
== TFTP server setup ==<br />
<br />
Create a directory for TFTP root (e.g. {{ic|/srv/tftp}}) to put transferable files in.<br />
<br />
To use dnsmasq's TFTP secure mode [[chown]] TFTP root and all files in it to {{ic|dnsmasq}} user.<br />
<br />
Enable TFTP in {{ic|dnsmasq.conf}}<br />
{{hc|/etc/dnsmasq.conf|<nowiki><br />
enable-tftp<br />
tftp-root=/srv/tftp<br />
tftp-secure<br />
</nowiki>}}<br />
<br />
== PXE setup ==<br />
<br />
PXE requires DHCP and TFTP servers, both functions can be provided by dnsmasq.<br />
<br />
{{Tip|dnsmasq can add PXE booting options to a network with an already running DHCP server:<br />
{{hc|/etc/dnsmasq.conf|2=<br />
interface=''enp0s0''<br />
bind-dynamic<br />
dhcp-range=''192.168.0.1'',proxy}}<br />
}}<br />
<br />
# set up [[#TFTP server setup|TFTP server]] and [[#DHCP server setup|DHCP server]]<br />
# copy and configure a PXE compatible bootloader (e.g. [[Syslinux#Pxelinux|PXELINUX]]) on TFTP root<br />
# enable PXE in {{ic|/etc/dnsmasq.conf}}:<br />
{{Note|<br />
*file paths are relative to TFTP root<br />
*if the file has a {{ic|.0}} suffix, you must exclude the suffix in {{ic|pxe-service}} options<br />
}}<br />
To simply send one file:<br />
dhcp-boot=lpxelinux.0<br />
To send a file depending on client architecture:<br />
pxe-service=x86PC, "PXELINUX (BIOS)", "bios/lpxelinux"<br />
pxe-service=X86-64_EFI, "PXELINUX (EFI)", "efi64/syslinux.efi"<br />
<br />
{{Note|In case {{ic|pxe-service}} doesn't work (especially for UEFI-based clients), combination of {{ic|dhcp-match}} and {{ic|dhcp-boot}} can be used.}}<br />
dhcp-match=set:efi-x86_64,option:client-arch,7<br />
dhcp-match=set:efi-x86,option:client-arch,6<br />
dhcp-match=set:bios,option:client-arch,0<br />
dhcp-boot=tag:efi-x86_64,"efi64/syslinux.efi"<br />
dhcp-boot=tag:efi-x86,"efi32/syslinux.efi"<br />
dhcp-boot=tag:bios,"bios/lpxelinux.0"<br />
<br />
<br />
<br />
The rest is up to the bootloader.<br />
<br />
== Start the daemon ==<br />
<br />
[[Start/enable]] {{ic|dnsmasq.service}}.<br />
<br />
To see if dnsmasq started properly, check the system's journal:<br />
<br />
{{bc|$ journalctl -u dnsmasq}}<br />
<br />
The network will also need to be restarted so the DHCP client can create a new {{ic|/etc/resolv.conf}}.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Prevent OpenDNS redirecting Google queries ===<br />
<br />
To prevent OpenDNS from redirecting all Google queries to their own search server, add to {{ic|/etc/dnsmasq.conf}}:<br />
{{bc|1=server=/www.google.com/<ISP DNS IP>}}<br />
<br />
=== View leases ===<br />
{{bc|$ cat /var/lib/misc/dnsmasq.leases}}<br />
<br />
=== Adding a custom domain ===<br />
It is possible to add a custom domain to hosts in your (local) network:<br />
local=/home.lan/<br />
domain=home.lan<br />
<br />
In this example it is possible to ping a host/device (e.g. defined in your hosts file) as {{ic|hostname.home.lan}}.<br />
<br />
Uncomment {{ic|expand-hosts}} to add the custom domain to hosts entries:<br />
expand-hosts<br />
Without this setting, you'll have to add the domain to entries of /etc/hosts.<br />
<br />
=== Override addresses ===<br />
<br />
In some cases, such as when operating a captive portal, it can be useful to resolve specific domains names to a hard-coded set of addresses. This is done with the {{ic|address}} config:<br />
<br />
address=/example.com/1.2.3.4<br />
<br />
Furthermore, it's possible to return a specific address for all domain names that are not answered from {{ic|/etc/hosts}} or DHCP by using a special wildcard:<br />
<br />
address=/#/1.2.3.4<br />
<br />
=== More than one instance ===<br />
<br />
If we want two or more dnsmasq servers works per interface(s).<br />
<br />
==== Static ====<br />
<br />
To do this staticly, server per interface, use {{ic|interface}} and {{ic|bind-interface}} options. This enforce start second dnsmasq.<br />
<br />
==== Dynamic ====<br />
<br />
In this case we can exclude per interface and bind any others:<br />
<br />
except-interface=lo<br />
bind-dynamic<br />
<br />
{{Note|This is default in libvirt.}}<br />
<br />
== See also ==<br />
<br />
* [http://www.g-loaded.eu/2010/09/18/caching-nameserver-using-dnsmasq/ Caching Nameserver using dnsmasq, and a few other tips and tricks.]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=St&diff=440887St2016-07-11T15:00:57Z<p>Alive4ever: st - Launching the terminal via desktop entry and a workaround to make Alt+BackSpace more consistent (i.e. sends ^[^? )</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Terminal emulators]]<br />
[[ja:St]]<br />
[http://st.suckless.org/ st] is a simple terminal implementation for [[X]] by [http://suckless.org suckless]. It is intended to serve as a lightweight replacement for [[xterm]] or [[urxvt]]. It currently supports 256 colors, true colors, most VT10X escape sequences, UTF-8, X11 copy/paste, anti-aliased fonts (using fontconfig), fallback fonts, resizing, shortcuts via config.h, and line drawing.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|st}} or {{AUR|st-git}} package.<br />
<br />
== Configuration ==<br />
''st'' is configured through its {{ic|config.h}} file, which is copied over from {{ic|config.h}} at compile time. A default {{ic|config.def.h}} is included with the source. <br />
<br />
Consider maintaining your own [[PKGBUILD]] with your {{ic|config.h}}.<br />
<br />
=== Shell ===<br />
<br />
To change the default shell for ''st'', edit this line:<br />
<br />
static char shell[] = "/bin/sh";<br />
<br />
=== Term ===<br />
<br />
To change the terminal type, edit this line:<br />
<br />
static char termname[] = "st-256color";<br />
<br />
''st'' will set the {{ic|TERM}} variable with the value of {{ic|termname}}.<br />
<br />
{{note|If you experience trouble with ''st'', you can try to set {{ic|termname}} to {{ic|xterm}} or {{ic|xterm-256color}} }}<br />
<br />
=== Font ===<br />
<br />
Edit the following line as you prefer:<br />
<br />
static char font[] = "Liberation Mono:pixelsize=12:antialias=false:autohint=false";<br />
<br />
You can also pass the value of the font in the command line:<br />
<br />
st -f "Liberation Mono:size=12"<br />
<br />
=== Colors ===<br />
<br />
Edit the following line to set ''foreground'', ''background'' and ''cursor'' colors:<br />
<br />
static unsigned int defaultfg = 7;<br />
static unsigned int defaultbg = 0;<br />
static unsigned int defaultcs = 256;<br />
<br />
The values refer to the {{ic|*colorname[]}} array in the same file, you can use default color or add yours in {{ic|#rrggbb}}, for example:<br />
<br />
static const char *colorname[] = {<br />
/* 8 normal colors */<br />
"black",<br />
"red3",<br />
"green3",<br />
"yellow3",<br />
"blue2",<br />
"magenta3",<br />
"cyan3",<br />
"gray90",<br />
<br />
/* 8 bright colors */<br />
"gray50",<br />
"red",<br />
"green",<br />
"yellow",<br />
"#5c5cff",<br />
"magenta",<br />
"cyan",<br />
"white",<br />
<br />
[255] = 0,<br />
<br />
/* more colors can be added after 255 to use with DefaultXX */<br />
"#cccccc",<br />
"#eeeeee",<br />
"#111111",<br />
};<br />
<br />
/*<br />
* Default colors (colorname index)<br />
* foreground, background, cursor<br />
*/<br />
static unsigned int defaultfg = 257;<br />
static unsigned int defaultbg = 258;<br />
static unsigned int defaultcs = 256;<br />
<br />
=== Desktop entry ===<br />
To simplify launching {{ic|st}} with a decent font e.g. {{Pkg|adobe-source-code-pro-fonts}}, create {{ic|~/.local/share/applications/simple-terminal.desktop}}.<br />
<pre><nowiki><br />
[Desktop Entry]<br />
Name=Simple Terminal<br />
GenericName=Terminal<br />
Comment=standard terminal emulator for the X window system<br />
Exec=st -t "Suckless Terminal" -f "Source Code Pro:style=Semibold:size=16" -g "80x24"<br />
Terminal=false<br />
Type=Application<br />
Encoding=UTF-8<br />
Icon=terminal<br />
Categories=System;TerminalEmulator;<br />
Keywords=shell;prompt;command;commandline;cmd;<br />
</nowiki></pre><br />
<br />
The menu entry will appear as {{ic|Simple Terminal}} under {{ic|System Tools}} on application list.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Keyboard ===<br />
==== DEL-Key not working properly in some Application ====<br />
add following to ''~/.inputrc'' or ''/etc/inputrc'':<br />
set enable-keypad on<br />
<br />
==== Backspace not working properly ====<br />
<br />
{{Note | According to the [http://git.suckless.org/st/tree/FAQ FAQ], this behavior has been changed in the upstream, and the issue can be fixed upgrading to the latest version. }}<br />
<br />
While virtual terminal and most popular terminal emulator for X bind {{ic|backscape}} key to {{ic|^?}} escape sequence, older version of {{ic|st}} bind it to {{ic|^H}}, as explained in older version of the FAQ.<br />
<br />
If hitting the {{ic|backspace}} key while typing on standard input of some programs (like {{ic|read}}) prints {{ic|^H}} instead of erasing, you can fix that with:<br />
<br />
stty erase '^H'<br />
<br />
This will make the terminal interprets {{ic|^H}} as an erase command. <br />
<br />
If you want to put the above command in a shell profile, you should consider checking the {{ic|$TERM}} before launch it.<br />
<br />
As of version {{ic|0-6}}, {{ic|st}} interpret backspace as {{ic|^?}} by default. An exception is when {{ic|Alt+BackSpace}} pressed, {{ic|st}} sends {{ic|^[^H}} instead of {{ic|^[^?}} ([https://bugs.archlinux.org/task/50000 FS#50000]). This inconsistent behavior leads to bad experience, especially on Emacs when pressing {{ic|Alt+BackSpace}} no longer delete a word backwards. To fix this, adding a line on {{ic|config.h}} is needed.<br />
<pre><nowiki><br />
{ XK_BackSpace, Mod1Mask, "\033\177", 0, 0, 0},<br />
</nowiki></pre><br />
Rebuild the package to apply the change.<br />
<br />
=== Vim ===<br />
==== The background colour of text in ''vim'' will not fill in anything that is not a character ====<br />
Try setting the value of {{ic|termname}} in your {{ic|config.h}} to {{ic|st-256color}} and recompiling. And do not set the {{ic|TERM}} var in your shell, at least not to {{ic|st-256color}} as this seems to cause the issue.<br />
<br />
Another solution, perhaps a better one, is to have the following lines in your {{ic|.vimrc}} file:<br />
<br />
if &term =~ '256color'<br />
" disable Background Color Erase (BCE) so that color schemes<br />
" render properly when inside 256-color tmux and GNU screen.<br />
" see also http://sunaku.github.io/vim-256color-bce.html<br />
set t_ut=<br />
endif<br />
<br />
== See also ==<br />
*[http://st.suckless.org/ Homepage]<br />
*[http://git.suckless.org/st/plain/FAQ Frequently asked questions]<br />
*[http://git.suckless.org/st/ Official git repository]</div>Alive4everhttps://wiki.archlinux.org/index.php?title=Android&diff=440764Android2016-07-10T08:22:18Z<p>Alive4ever: /* Adding udev Rules */ 0660 is safer than 0666 and to make sure user is a member of adbusers group</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|If you are running a 64-bit system, make sure the [[multilib]] repository is enabled to avoid "error: target not found: lib32-zlib" error messages.}}<br />
<br />
{{Note|If you plan to install [[Android Studio]] and want the IDE to manage your SDK installation, you do not need to install these packages}}<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 />
{{AUR|android-support}} is also required if supporting older devices.<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 modify anything in this directory. If you intend to use it as a regular user, create the Android sdk users group:<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]. You may also use the android-*-dummy packages in the [[AUR]] to handle the system dependencies.}}<br />
<br />
=== Android SDK platform API ===<br />
<br />
{{Note|If you plan to install [[Android Studio]] and want the IDE to handle your SDK, you don't need to install these packages}}<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}}<br />
* {{aur|android-platform-18}}<br />
* {{aur|android-platform-17}}<br />
* {{aur|android-platform-16}}<br />
* {{aur|android-platform-15}}<br />
* {{aur|android-platform-14}}<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|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 />
The official, but deprecated, [http://developer.android.com/sdk/eclipse-adt.html Eclipse ADT] plugin can be installed with the {{AUR|eclipse-android}} package.<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 />
{{Tip|Many devices' udev rules are included in {{Pkg|libmtp}}, so if you have this installed, the following steps may not be necessary.}}<br />
<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 addition, 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 (7 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 [[#Detect the device|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 />
<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="0660", 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 />
Make sure you are member of {{ic|adbusers}} [[group]] to access {{ic|adb}} devices.<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 />
* On moto e it could happen to have a different vendor/product id while you are on sideload or fastboot, verify again lsusb if you get no permission.<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 32-bit and 64-bit systems: {{Aur|ncurses5-compat-libs}}<br />
<br />
* AUR Packages 64-bit systems only: {{Aur|lib32-ncurses5-compat-libs}}<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 {{Pkg|maven}} to build CyanogenMod since, from cm-13.0, they are using maven artifacts}}<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 />
[[Install]] the {{Pkg|repo}} package, then:<br />
<br />
$ mkdir ~/bin<br />
$ export PATH=~/bin:$PATH<br />
$ curl <nowiki>https://storage.googleapis.com/git-repo-downloads/repo</nowiki> > ~/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. As of Android 6.0.1, the entire codebase totals 40 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|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 devices ===<br />
<br />
Samsung devices can't be flashed using '''Fastboot''' tool. Alternatives are only '''Heimdall''' and '''Odin''' (by using Windows and VirtualBox).<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]] and [[VirtualBox#Guest_additions_disc|guest additions]].<br />
# Install your preferred, but compatible with Odin, Windows operating system (with VirtualBox guest additions) into a virtual hard drive using VirtualBox<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>Alive4everhttps://wiki.archlinux.org/index.php?title=Software_access_point&diff=440760Software access point2016-07-10T08:01:48Z<p>Alive4ever: /* Wireless client and software AP with a single Wi-Fi device */ not all interface support wds, so just create a managed virtual interface and hostapd will change it to ap mode automatically</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 />
The ''virtual interfaces'' with unique MAC address 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 managed addr 12:34:56:78:ab:cd <br />
# iw dev wlan0 interface add wlan0_ap type managed addr 12:34:56:78:ab:ce<br />
<br />
Random MAC address can be generated using [[macchanger]].<br />
<br />
== Configuration ==<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, which 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 />
{{Tip|You can set up the SSID with UTF-8 characters, so international characters will show properly. The option to enable it is {{ic|1=utf8_ssid=1}}. Some clients may have problems with recognizing the correct encoding (e.g. [[wpa_supplicant]] or Windows 7).}}<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#Configuration]] for configuration details.<br />
<br />
In 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 />
# create_ap wlan0 internet0 MyAccessPoint MyPassPhrase<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 />
===Cannot start AP mode in 5Ghz band===<br />
<br />
Apparently with the special country code {{ic|00}} (global), all usable frequencies in the 5Ghz band will have the [https://wireless.wiki.kernel.org/en/developers/regulatory/processing_rules#post_processing_mechanisms {{ic|no-ir}} (''no-initiating-radiation'')] flag set, which will prevent hostapd from using them. You will need to have {{Pkg|crda}} installed and have your country code set to make frequencies allowed in your country available for hostapd.<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>Alive4everhttps://wiki.archlinux.org/index.php?title=Ppp/Mobile_broadband_modem&diff=439539Ppp/Mobile broadband modem2016-07-02T07:46:57Z<p>Alive4ever: /* Configuration */ Added pppconfig as easy way to configure pppd profile</p>
<hr />
<div>[[Category:Modems]]<br />
[[ru:3G and GPRS modems with pppd]]<br />
{{Note|3G and GPRS modems with pppd alone}}<br />
<br />
Why not to use a pppd wrapper (like wvdial or similar)?. I particularly switched to direct pppd because my previous software sometimes silently exited instead of reconnecting, as it was configured to do, requiring me to travel to manually perform the reconnection.<br />
<br />
You may be reading this page by the same reason it was written for: you may have finally concluded that the lesser the layers, the less likely the troubles.<br />
<br />
== Prerequisites and tested hardware ==<br />
<br />
The only requirement is the ppp package (2.4.5-1 tested). The method described supports easy switching between several carriers and 3G and GPRS modes. It has been tested and directly works with no modifications (except for the device name) with:<br />
<br />
* Huawei EM770 MiniPCIe modem (Asus Eee PC 1000H Go internal integrated modem).<br />
* Huawei E220 and E1552 external USB dongles.<br />
* Nokia N73 (USB tethering; select "PC Suite" when the phone asks).<br />
* Nokia CS-15 (lsusb says 0421:0612 Nokia Mobile Phones)<br />
* Alcatel x310e (carrier: Wind IT)<br />
<br />
This guide assumes that your modem hardware is properly detected and working. You simply may look at '''/var/log/messages''' to discover the device names appeared when the modem is plugged in. Alternatively:<br />
<br />
root@quark:~# dmesg | grep GSM | grep attached<br />
usb 1-6: GSM modem (1-port) converter now attached to ttyUSB0<br />
usb 1-6: GSM modem (1-port) converter now attached to ttyUSB1<br />
usb 1-6: GSM modem (1-port) converter now attached to ttyUSB2<br />
usb 2-2: GSM modem (1-port) converter now attached to ttyUSB3<br />
usb 2-2: GSM modem (1-port) converter now attached to ttyUSB4<br />
<br />
In this computer there are 2 devices available: a internal 3G modem ('''ttyUSB0''') and a external 3G dongle ('''ttyUSB3'''). The Nokia phones use other device names, like '''ttyACM0'''. The extra devices created are useful to get and query the internal modem state while the main one is in use (you may try the '''cat''' command on them).<br />
<br />
To enable some modems you may need the [https://www.archlinux.org/packages/?q=usb_modeswitch usb_modeswitch] package (see the [[USB 3G Modem]] wiki for more information).<br />
<br />
== Configuration ==<br />
<br />
The following files are also available as {{AUR|netcfg-ppp-mobile-git}}{{Broken package link|{{aur-mirror|netcfg-ppp-mobile-git}}}} in the [[Arch User Repository]]. <br />
<br />
=== /etc/ppp/options-mobile ===<br />
<br />
Create this file:<br />
<br />
{{hc|/etc/ppp/options-mobile|<br />
<nowiki>ttyUSB0<br />
921600<br />
lock<br />
crtscts<br />
modem<br />
passive<br />
novj<br />
defaultroute<br />
noipdefault<br />
usepeerdns<br />
noauth<br />
hide-password<br />
persist<br />
holdoff 10<br />
maxfail 0<br />
debug</nowiki><br />
}}<br />
<br />
The first line is the modem device ('''ttyUSB0''' in the example) and it will be a permanent option while your hardware doesn't changes. You may want to modify some options (see '''man pppd'''). The proposed setup tries to keep the connection permanently established, reconnecting when necessary.<br />
<br />
=== /etc/ppp/peers ===<br />
<br />
Add these files:<br />
<br />
root@quark:/etc/ppp/peers# ll<br />
total 8<br />
-rw-r----- 1 root root 141 Jun 20 19:29 mobile-auth<br />
-rw-r----- 1 root root 104 Jun 20 19:29 mobile-noauth<br />
lrwxrwxrwx 1 root root 13 Jun 20 19:30 provider -> mobile-noauth<br />
<br />
The '''provider''' symlink defines the default peer for pppd, and as you see it points to the '''mobile-noauth''' file. It is possible to setup a different file with user/password for each carrier (with '''mobile-auth''' being a example) but it seems that this is not necessary (at least, not for Vodafone or Simyo in Spain).<br />
<br />
{{hc|/etc/ppp/peers/mobile-auth|<br />
<nowiki>file /etc/ppp/options-mobile<br />
user "your_usr"<br />
password "your_pass"<br />
connect "/usr/sbin/chat -v -t15 -f /etc/ppp/chatscripts/mobile-modem.chat"</nowiki><br />
}}<br />
<br />
{{hc|/etc/ppp/peers/mobile-noauth|<br />
<nowiki>file /etc/ppp/options-mobile<br />
connect "/usr/sbin/chat -v -t15 -f /etc/ppp/chatscripts/mobile-modem.chat"</nowiki><br />
}}<br />
<br />
=== /etc/ppp/chatscripts ===<br />
<br />
Since the '''chatscripts''' directory does not exists in Arch, manually create it to place a few new files there:<br />
<br />
root@quark:/etc/ppp/chatscripts# ll<br />
total 44<br />
lrwxrwxrwx 1 root root 15 Jun 19 19:17 apn -> apn.es.vodafone<br />
-rw-r--r-- 1 root root 37 Jun 19 16:27 apn.es.simyo<br />
-rw-r--r-- 1 root root 35 Jun 19 16:27 apn.es.vodafone<br />
-rw-r--r-- 1 root root 394 Jun 20 19:29 mobile-modem.chat<br />
lrwxrwxrwx 1 root root 12 Jun 19 18:59 mode -> mode.3G-only<br />
-rw-r--r-- 1 root root 29 Jun 19 22:12 mode.3G-only<br />
-rw-r--r-- 1 root root 28 Jun 19 17:05 mode.3G-pref<br />
-rw-r--r-- 1 root root 29 Jun 19 17:05 mode.GPRS-only<br />
-rw-r--r-- 1 root root 28 Jun 19 17:06 mode.GPRS-pref<br />
-rw-r--r-- 1 root root 3 Jun 19 23:40 mode.NONE<br />
lrwxrwxrwx 1 root root 8 Jun 20 19:29 pin -> pin.CODE<br />
-rw------- 1 root root 13 Jun 20 19:29 pin.CODE<br />
-rw-r--r-- 1 root root 3 Jun 19 23:37 pin.NONE<br />
<br />
The core script is '''mobile-modem.chat''', which dialogues with the modem and properly inserts another tiny scripts for selecting the APN, GPRS/3G and the PIN code. You probably won't need to modify it. This script is interpreted by the limited (but powerful enough) chat tool, included in the standard ppp package. With the proposed method, you'll keep a little personal file-based "database" of settings.<br />
<br />
If you exchange the SIM card, to select the new carrier you only need to update the '''apn''' symlink to point to the correct apn file and restart the ppp network (for example with '''killall -HUP pppd'''). The same for changing between 3G/GPRS forced modes ('''mode''' symlink).<br />
<br />
The other files consist in a single line, which in some cases you may need to modify in order to customize it.<br />
<br />
{{hc|/etc/ppp/chatscripts/mobile-modem.chat|2=<br />
<nowiki>ABORT 'BUSY'<br />
ABORT 'NO CARRIER'<br />
ABORT 'VOICE'<br />
ABORT 'NO DIALTONE'<br />
ABORT 'NO DIAL TONE'<br />
ABORT 'NO ANSWER'<br />
ABORT 'DELAYED'<br />
REPORT CONNECT<br />
TIMEOUT 6<br />
'' 'ATQ0'<br />
'OK-AT-OK' 'ATZ'<br />
TIMEOUT 3<br />
'OK' @/etc/ppp/chatscripts/pin<br />
'OK\d-AT-OK' 'ATI'<br />
'OK' 'ATZ'<br />
'OK' 'ATQ0 V1 E1 S0=0 &C1 &D2 +FCLASS=0'<br />
'OK' @/etc/ppp/chatscripts/mode<br />
'OK-AT-OK' @/etc/ppp/chatscripts/apn<br />
'OK' 'ATDT*99***1#'<br />
TIMEOUT 30<br />
CONNECT ''</nowiki><br />
}}<br />
<br />
{{hc|/etc/ppp/chatscripts/apn.es.vodafone|2=<br />
<nowiki>AT+CGDCONT=1,"IP","ac.vodafone.es"</nowiki><br />
}}<br />
<br />
{{hc|/etc/ppp/chatscripts/apn.es.simyo|2=<br />
<nowiki>AT+CGDCONT=1,"IP","gprs-service.com"</nowiki><br />
}}<br />
<br />
{{hc|/etc/ppp/chatscripts/apn.no.telenor|2=<br />
<nowiki>AT+CGDCONT=1,"IP","Telenor"</nowiki><br />
}}<br />
<br />
(of course, you'll have to create your own apn files, replacing ''"ac.vodafone.es"'' or ''"gprs-service.com"'' by your own APN strings on them).<br />
<br />
For Telenor, use your mobile phone number (without country code) for both user and password in /etc/ppp/peers/mobile-noauth.<br />
<br />
{{hc|/etc/ppp/chatscripts/pin.CODE|2=<br />
<nowiki>AT+CPIN=1234</nowiki><br />
}}<br />
<br />
{{hc|/etc/ppp/chatscripts/pin.NONE|<br />
AT<br />
}}<br />
<br />
If your SIM card has the PIN code disabled, you should symlink '''pin''' to '''pin.NONE''' to avoid sending it. When a SIM card has the PIN code enabled, it is only required to be sent the first time after power on. There is a modem command to query about this, but since I didn't find a reliable way to use it in the chat script, the PIN, when enabled, is always sent. This has no drawbacks, other than a little additional delay also due to the chat script limitations while recovering from the modem error response (if the PIN was no longer required).<br />
<br />
{{hc|/etc/ppp/chatscripts/mode.3G-only|2=<br />
<nowiki>AT\^SYSCFG=14,2,3fffffff,0,1</nowiki><br />
}}<br />
<br />
{{hc|/etc/ppp/chatscripts/mode.3G-pref|2=<br />
<nowiki>AT\^SYSCFG=2,2,3fffffff,0,1</nowiki><br />
}}<br />
<br />
{{hc|/etc/ppp/chatscripts/mode.GPRS-only|2=<br />
<nowiki>AT\^SYSCFG=13,1,3fffffff,0,0</nowiki><br />
}}<br />
<br />
{{hc|/etc/ppp/chatscripts/mode.GPRS-pref|2=<br />
<nowiki>AT\^SYSCFG=2,1,3fffffff,0,0</nowiki><br />
}}<br />
<br />
{{hc|/etc/ppp/chatscripts/mode.NONE|<br />
AT<br />
}}<br />
<br />
The SYSCFG line in the '''mode.*''' files is device-dependent, and likely Huawei-specific. It does not works in Nokia phones (you may symlink '''mode''' to '''mode.NONE''', which only sends the AT command with no effect). I had to investigate before achieving success with both EM770 and E220 modems. Despite many forums reporting a "4" trailing code, it seems that the trailing 0/1 number, while optional in E220, becomes mandatory in EM770 for truly switching the mode. At the end of this guide there are explained the available options for this command. As previously said, you may simply link to '''mode.NONE''' and use your modem defaults in case of problems.<br />
<br />
=== Easy wizard configuration ===<br />
Instead of manually creating pppd configuration, {{Aur|pppconfig}} can be used to create pppd configuration and chatscripts easily. Editing chatscript is needed to provide APN name, e.g. adding {{ic|<nowiki>AT+CDGCONT=1,"IP","apnname"</nowiki>}} on specific chatscript profile, e.g {{ic|/etc/chatscripts/mobile}}.<br />
<br />
<pre> /etc/chatscripts/mobile<br />
# This chatfile was generated by pppconfig 2.3.18.<br />
# Please do not delete any of the comments. Pppconfig needs them.<br />
# <br />
# ispauth CHAP<br />
# abortstring<br />
ABORT BUSY ABORT 'NO CARRIER' ABORT VOICE ABORT 'NO DIALTONE' ABORT 'NO DIAL TONE' ABORT 'NO ANSWER' ABORT DELAYED<br />
# modeminit<br />
'' ATZ<br />
'' AT+CDGCONT=1,"IP","internet"<br />
# ispnumber<br />
OK-AT-OK "ATDT*99#"<br />
# ispconnect<br />
CONNECT \d\c<br />
# prelogin<br />
<br />
# ispname<br />
# isppassword<br />
# postlogin<br />
<br />
# end of pppconfig stuff<br />
<br />
</pre><br />
<br />
== Start the pppd ==<br />
<br />
To start the pppd daemon, either run '''pon/poff''' or '''/etc/rc.d/ppp start|stop'''. In Arch this can be automated to occur at system boot by adding '''"@ppp"''' after "network" in the '''DAEMONS''' line of '''/etc/rc.conf''' (the "@" places it in background, since pppd start may be a bit slow).<br />
<br />
The log is stored in '''/var/log/messages'''.<br />
<br />
With the above proposed setup, while the new ppp0 interface is up, pppd will automatically set your default route (if none previously existing) as well as the '''/etc/resolv.conf''' contents. It seems very reliable handling DNS switchings (the backup is kept in resolv.conf.backup.ppp0, but I never had to manually restore it, even after a power failure).<br />
<br />
== Patch for modem availability after booting ==<br />
<br />
If you automate the pppd start, it may occur that the modem device does not exists at the moment of the pppd lauch during the computer boot. This may occur even when the USB modem module load is manually setup in rc.conf: that helps, but the device may be still not always available when pppd comes into scene. The pppd daemon rejects to start when the configured device does not exists, and it doesn't seems to have an option to force it to start (note that in case the device dissapears once pppd is already running, for example by momentarily disconnecting the external 3G USB modem, pppd will continue running and will reconnect once it appears again).<br />
<br />
The following script may be useful to wait until the hardware is ready. It will typically wait for 0-2 seconds. The modem device is assumed to be the first line on '''/etc/ppp/options-mobile'''. It takes an argument with the maximum wait (in seconds). Optionally admits a second argument with a profile name (from ''/etc/ppp/peers'') which will be used to re-run pppd. Do not forget to make the script executable:<br />
<br />
{{hc|/etc/ppp/wait-dialup-hardware|2=<br />
<nowiki>#!/bin/bash<br />
INTERFACE="/dev/$(head -1 /etc/ppp/options-mobile)"<br />
MAX_SECONDS_TIMEOUT=$1<br />
PEER_NAME=$2<br />
dsec=$((${MAX_SECONDS_TIMEOUT} * 10))<br />
for ((retry=0; retry < ${dsec}; retry++))<br />
do<br />
if [ -c ${INTERFACE} ]; then<br />
logger "$0: OK existing required device ${INTERFACE} (in $((retry / 10)).$((100 * (retry % 10) / 10)) seconds)"<br />
break<br />
else<br />
sleep 0.1<br />
fi<br />
done<br />
if [ ! -c ${INTERFACE} ]; then<br />
logger "$0: ERROR timeout waiting for required device ${INTERFACE}"<br />
exit 1<br />
fi<br />
if [ ! -z "${PEER_NAME}" ]; then<br />
logger "$0: starting pppd for ${PEER_NAME}"<br />
setsid nohup pon "${PEER_NAME}" > /dev/null 2>&1 < /dev/null &<br />
fi<br />
exit 0</nowiki><br />
}}<br />
<br />
The script will add a line to '''/var/log/messages''':<br />
<br />
Jun 1 22:52:08 parsec logger: /etc/ppp/wait-dialup-hardware: OK existing required device /dev/ttyUSB0 (in 1.25 seconds)<br />
<br />
=== netcfg hook ===<br />
<br />
To use the above script, netcfg users could add the following profile:<br />
<br />
{{hc|/etc/network.d/ppp|2=<br />
<nowiki>CONNECTION='ppp'<br />
INTERFACE='ignore'<br />
PEER='mobile-noauth'<br />
PPP_TIMEOUT=30<br />
PRE_UP='/etc/ppp/wait-dialup-hardware 10'</nowiki><br />
}}<br />
<br />
=== network hook ===<br />
<br />
Users of traditional network setup (instead of netcfg) can use the following trick to launch the ''wait-dialup-hardware'' script from the standard /etc/rc.d/ppp service. The example is intended to run the mobile-noauth profile:<br />
<br />
{{hc|/etc/ppp/peers/mobile-noauth.wait|<br />
<nowiki>noauth<br />
pty "/etc/ppp/wait-dialup-hardware 10 mobile-noauth"</nowiki><br />
}}<br />
<br />
Updating the default '''provider''' symlink to point to the new intermediate (fake) '''mobile-noauth.wait''' profile, it will simply run the wait-dialup-hardware script from within pppd and, in turn, will restart pppd with the final (non fake) '''mobile-noauth''' profile once the hardware is ready. Note that the ''noauth'' option in the first line of the fake profile is necessary (even if the final profile does requires authentication).<br />
<br />
== Troubleshooting ==<br />
<br />
In case of using a wrong PIN, my modem consistently rejects the APN setting phase (no error in the steps before). This is how '''/var/log/messages''' looks like:<br />
<br />
Jun 20 00:17:30 quark chat[3348]: send (AT+CGDCONT=1,"IP","ac.vodafone.es"^M)<br />
Jun 20 00:17:31 quark chat[3348]: expect (OK) <br />
Jun 20 00:17:31 quark chat[3348]: ^M<br />
Jun 20 00:17:31 quark chat[3348]: AT+CGDCONT=1,"IP","ac.vodafone.es"^M^M<br />
Jun 20 00:17:31 quark chat[3348]: ERROR^M <br />
Jun 20 00:17:34 quark chat[3348]: alarm<br />
Jun 20 00:17:34 quark chat[3348]: Failed<br />
<br />
It would be a long story, but I'll simply abbreviate it: if you have just set or changed the PIN in a phone, please reboot the phone and try it in the phone before placing the SIM card in the modem (I'm not sure if the PIN updates take effect just at the moment they are done in the phone menus).<br />
<br />
In case of frequent manual pppd restarts, as for example when testing configuration options, the EM770 (firmware upgraded to 11.104.16.12.00) sometimes becomes confused. Despite it responds to the AT commands, it gets stuck in a "NO CARRIER" reply (while the 3G network is ok, as a mobile phone may report). This not occurs with the proposed scripts (in case of connection lost, they wait enough time before retrying). With the modem stuck, powering OFF and then ON the computer solves the problem. This is perhaps a firmware bug. Also, when using a PIN, this modem returns a NO CARRIER reply in the first connection try (it seems that a huge wait after setting the PIN helps; anyway the same effect is achieved by the ordinary connection retry). While running, the EM770 is stable, but the E220 or the Nokia phones are far more reliable in the connection phase. Your mileage may vary depending on your hardware.<br />
<br />
At least for Huawei E870 issuing AT+CFUN=1,1 (meaning restart and go to online mode) seems to fix being stuck with no NO CARRIER without having to reboot. This might be related to network registration being done after restart. You can check AT+COPS? to see if you are actually registered but note you also want a service state of 2 (meaning "valid service" - this is automatically reported by the card as ^SRVST:X on the second ttyUSB) otherwise trying to dial out is hopeless. In the rare case of the card becoming completely stuck (doesnt respond to AT commands anymore) this can be fixed by using pccardctl (pccardctl eject [slot-number]; pccardctl insert [slot-number]). Of course this only works for pcmcia cards but maybe there is a similar trick for USB dongles.<br />
<br />
== AT^SYSCFG Huawei command reference ==<br />
<br />
To see the supported values, you can query your own modem sending the "AT^SYSCFG=?" command.<br />
<br />
AT^SYSCFG=$mode,$acqOrder,$band,$roam,$srvDomain<br />
<br />
$mode<br />
2=Auto-Select<br />
13=GSM only<br />
14=WCDMA only<br />
16=no Change<br />
<br />
$acqOrder<br />
0=Automatic<br />
1=GSM prefered<br />
2=WCDMA prefered<br />
3=no Change<br />
<br />
$band<br />
3fffffff = All<br />
other (query list with "AT^SYSCFG=?")<br />
<br />
$roam<br />
0=Not Supported<br />
1=Supported<br />
2=no Change<br />
<br />
$srvDomain<br />
0=Circuit-Switched only<br />
1=Packet-Switched only<br />
2=Circuit- & Packet-Switched<br />
3=Any<br />
4=no Change<br />
<br />
AT^SYSCFG=? command output on Huawei EM770:<br />
<br />
^SYSCFG:(2,13,14,16),(0-3),((80000,"GSM850"),(200000,"GSM1900"),(400380,"GSM900/GSM1800/WCDMA2100"),(4a80000,"GSM850/GSM1900/WCDMA850/WCDMA1900"),(3fffffff,"All Bands")),(0-2),(0-4)<br />
<br />
== Huawei unsolicited report command reference ==<br />
<br />
These appear on the second ttyUSB.<br />
<br />
=== ^SRVST ===<br />
<br />
Reports the type of service the network your currently registered to is providing (it seems normal to first report 1 and then switch to 2). Depending on the device there might be more types.<br />
<br />
0=No service<br />
1=Restricted service<br />
2=Valid service<br />
<br />
=== ^MODE ===<br />
<br />
Reports the mode you are currently transmitting in. Depending on the device there might be more modes. Note: It seems normal for the device to only go to 5,5/5,6/5,7 when transmitting and fall back to 5,4 when idle.<br />
<br />
0,0=No service<br />
3,1=GSM<br />
3,2=GPRS<br />
3,3=EDGE<br />
5,4=WCDMA<br />
5,5=HSDPA<br />
5,6=HSUPA<br />
5,7=HSDPA+HSUPA<br />
<br />
=== ^RSSI ===<br />
<br />
Reports strength of the mobile signal in form of $rssi,[$ber]. This info can also be optained by issuing AT+CSQ but unless you are registered to a network it seems this just returns the value for the strongest network whenever you are able to use it or not. To give some meaning to this you can convert it to percent by RSSI / 31 * 100. RSSI of 3/4 (about 10% reception) seems to be the absolute minimum to get a (rather flaky) HDSPA connection.<br />
<br />
$rssi=0-31 (-113dBm + $rssi * 2) or 99 (unknown or not measurable)<br />
$ber=Bit-error-rate (only returned by AT+CSQ - always 99?)<br />
<br />
== Automatic PPP ==<br />
For the Nokia CS-15, create (or add to) /etc/udev/rules.d/99-nokia.rules with this line:<br />
SUBSYSTEM=="net", ACTION=="add", ATTRS{idVendor}=="0421", ATTRS{idProduct}=="0612", DEVPATH=="*/ttyACM0", RUN+="pon"<br />
and it will connect ppp as soon as you plug in the device. You can probably do something similar for the other modems.<br />
<br />
== Operator selection ==<br />
<br />
=== Listing ===<br />
<br />
AT+COPS=? returns a list of all available networks in the format of $state,$longname,$shortname,$id,$tech.<br />
<br />
$state<br />
0=unknown<br />
1=available<br />
2=current<br />
3=forbidden<br />
<br />
$longname<br />
long alphanumeric operator name<br />
<br />
$shortname<br />
short alphanumeric operator name<br />
<br />
$id<br />
numeric operator id<br />
<br />
$tech<br />
0=GSM (at best you get EDGE here)<br />
2=UTRAN (supports WCDMA/HSDPA/HSUPA)<br />
7=EUTRAN (?)<br />
<br />
=== Manual selection ===<br />
<br />
You can lock the device to only connect to a specific operator by issuing AT+COPS=1,$format,$operator command. Note: Even the numeric id needs to be quoted.<br />
<br />
$format<br />
0=long alphanumeric operator name<br />
1=short alphanumeric operator name<br />
2=numeric operator id<br />
<br />
$operator<br />
operator name/id as specfied by $format<br />
<br />
=== Automatic selection ===<br />
<br />
To let the device decide which operator to use issue AT+COPS=0 command.<br />
<br />
==Related Articles==<br />
[[Dialup without a dialer HOWTO]]<br><br />
[[Huawei E220]]<br><br />
[[USB 3G Modem]]<br></div>Alive4ever